pi-map/usage-guide.md

pi-project-map Usage Guide

For Pi agents and advanced users who want predictable, low-friction navigation and maintenance of project-map artifacts.

When to use each command

Situation	Command
New project, no .pi-map.md files yet, or artifacts are severely outdated	project_map_init / project-map init
You just edited one or more source files	project_map_patch <file> / project-map patch <file>
You suspect stale data, or you are about to make an architectural decision	project_map_validate / project-map validate
Localized discrepancies detected by validate	project_map_validate with fix=true / project-map validate --fix
Widespread structural staleness, or you pulled major changes from version control	project_map_reinit / project-map reinit
You have a specific question like "where is auth handled?"	project_map_context <query> / project-map context <query>

Command behavior

init

Run once when you start work on a repo, or after large restructuring. It discovers every non-ignored directory, analyzes files with LLM + AST, and writes both .pi-map.md and .pi-map.index.md for every directory.

patch

Run immediately after editing a source file. The command regenerates the pair for that file's directory and refreshes ancestor artifacts.

Patch mode is chosen automatically:

• small - refresh ancestor indexes only
• structural - refresh ancestor map/index pairs

You can force a mode with project-map patch <file> --patch-mode=small|structural. auto remains the default.

validate

Run before architectural decisions, broad refactors, or final handoff. It checks for:

• missing/orphaned files
• stale signatures
• dirty markers
• broken parent/children/sibling links
• map/index disagreements

Use project-map validate --fix to repair affected chains. --fix requires an LLM client.

reinit

Use as a last resort. By default, project_map_reinit (or project-map reinit [path]) regenerates only the target subtree plus its ancestor directories up to the root. It falls back to full regeneration only when the target subtree covers more than reinitFullThresholdPercent of the project's files (default: 10%).

Reach for reinit when project_map_patch and project_map_validate --fix cannot repair widespread structural damage (e.g. broken parent/child links across many directories) or after a large merge.

context

Use when you know what you are looking for:

project-map context "authentication logic"
project-map context "routing metadata generation"
project-map context "LLM client error handling"

The returned bundle is deterministic and ranked. Read indexes first, then strongest-match maps, then the actual source files.

Practical workflows

Starting a new task in a mapped project

1. read the root .pi-map.index.md and the Project Map Protocol
2. use the root index to find the relevant child directory
3. read that directory's .pi-map.index.md, then its .pi-map.md
4. read the relevant source files
5. edit source
6. run project_map_patch <changed-file>
7. run tests/build
8. run project_map_validate before architectural summary or handoff
9. if validation reports localized discrepancies, run project_map_validate with fix=true (or project-map validate --fix)
10. only if discrepancies are widespread or structural, run project_map_reinit

Exploring an unfamiliar area

project-map context "how is validation implemented"

Treat the returned bundle as a ranked entry point, not as truth.

After pulling changes from version control

project-map validate
# if localized discrepancies:
project-map validate --fix
# if widespread structural damage:
project-map reinit

Before a big refactor

project-map validate
# if localized discrepancies:
project-map validate --fix
# if widespread structural damage:
project-map reinit

Prompt injection behavior before and after init

Before init

If no paired artifacts exist:

• off: nothing happens
• advisory, strong, strict: a visible hint appears telling you to run project_map_init

No map content is fabricated.

After init

Once the root pair exists:

• off: no automatic injection
• advisory: a visible reminder that maps are available, but the root pair is not auto-loaded
• strong: root pair is auto-loaded; additional pairs are added within the budget; reinjection happens on relevant turns
• strict: same as strong, plus enforcement of the protocol path for sensitive actions

Relevant turns that trigger reinjection in strong/strict:

• agent start
• edit intent
• architecture-sensitive reasoning
• compaction
• root-pair artifact changes

Advisory vs strong vs strict in practice

Concern	Use
You want maps available but do not want automatic context expansion	advisory
Normal daily work; you want routing/orientation preloaded without friction	strong (default)
High-stakes codebase or you want explicit justification before bypassing context discipline	strict
You prefer fully manual control	off

In strict, if you attempt a sensitive edit or architectural claim without the protocol path in context, a guard appears. To proceed, either restore the project-map context or include:

[PI_MAP_BYPASS: editing a one-line comment, map context not needed]

Use bypass markers sparingly.

Example task flows

Fix a bug in src/utils/validation.ts

1. project-map context "validation utilities"
2. Read src/utils/.pi-map.index.md and .pi-map.md
3. Read src/utils/validation.ts
4. Edit the file
5. project_map_patch src/utils/validation.ts
6. Run tests
7. project_map_validate

Add a new file to src/llm/

1. Create src/llm/new-client.ts
2. Implement the file
3. project_map_patch src/llm/new-client.ts
4. project_map_validate

Review architecture before approving a PR

1. project-map validate
2. If localized discrepancies: project-map validate --fix
3. If clean, read root .pi-map.md and key directory maps
4. Cross-check claims against source
5. Only if widespread: run project-map reinit

Retrieval vs automatic injection

	Automatic injection	project_map_context / project-map context
Trigger	Configured mode + relevant turn	Explicit request
Content	Root pair + budgeted expansion	Top-ranked directories for a query
Cost	No LLM call; reads artifacts	No LLM call; deterministic scoring
Best use	Maintain baseline orientation	Targeted navigation for a specific task

Use both together: injection for baseline orientation, retrieval for focused entry points.

Keeping artifacts fresh

• patch after every edit
• validate before architectural claims
• use validate --fix for localized discrepancies
• use reinit only for widespread structural staleness or after large merges
• watch for the Pi extension warning about dirty packages on session start

Configuration quick reference

{
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000,
  "tagCap": 8,
  "workflowHintCap": 5,
  "reinitFullThresholdPercent": 10,
  "ignorePatterns": ["node_modules", ".git", "dist", "build"]
}

Providing ignorePatterns replaces the built-in default list, so include any defaults you want to keep.

• lower contextBudgetPercent / contextBudgetMaxTokens to reduce token use
• raise them if you want deeper auto-loaded context in large projects
• reinitFullThresholdPercent controls when project-map reinit [path] falls back to full regeneration
• strict is the safest enforcement mode; strong is the best default for everyday work