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:

```bash
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

```bash
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

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

### Before a big refactor

```bash
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:

```text
[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`

```text
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/`

```text
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

```text
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

```json
{
  "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