# pi-project-map

> Pi skill and CLI for hierarchical project analysis.

`pi-project-map` generates and maintains paired, machine-readable analysis artifacts throughout a codebase so agents can navigate quickly, orient themselves, and then verify details from source.

## What it is

For every non-ignored directory, the tool produces two files:

| File | Purpose |
|------|---------|
| `.pi-map.index.md` | Routing-first index for deciding what to open next. |
| `.pi-map.md` | Orientation-first rich map for understanding a directory. |

Together they form a **paired artifact model**:
- indexes are small and routing-optimized
- maps are denser and architecture-optimized
- source remains the final authority

`pi-project-map` runs as both:
- a **CLI** (`project-map`)
- a **Pi extension** (`pi-extension.ts`) that registers tools and optional runtime prompt injection

## Quick start

Install:

```bash
npm install -g pi-project-map
```

Generate paired artifacts in a repo:

```bash
cd my-project
project-map init
```

For standalone CLI usage, provide an LLM provider/API key. For example:

```bash
export OPENAI_API_KEY=...
project-map init
```

Inside Pi, the extension uses Pi's configured model automatically.

## Command overview

| CLI command | Pi tool | Purpose |
|-------------|---------|---------|
| `project-map init [path]` | `project_map_init` | Generate paired artifacts for the whole project or a subdirectory. |
| `project-map patch <file>` | `project_map_patch` | Regenerate artifacts for the directory containing the changed file and refresh ancestors appropriately. |
| `project-map validate [--fix]` | `project_map_validate` | Check paired artifacts for staleness or inconsistency. |
| `project-map reinit [path]` | `project_map_reinit` | Force full regeneration of all artifacts. |
| `project-map context <query>` | `project_map_context` | Return a ranked context bundle for a natural-language query. |

Typical workflow:

1. `project-map init` on first use
2. after editing source, `project-map patch <changed-file>`
3. before broad architectural decisions, `project-map validate`
4. for targeted exploration, `project-map context "<query>"`

## Operating model

Follow a three-tier model when consuming project maps:

1. **Tier 0 — Protocol and root index**  
   Start with the root `Project Map Protocol` and root `.pi-map.index.md`.
2. **Tier 1 — Indexes and maps**  
   Use indexes to route, then open the strongest-match `.pi-map.md` files for orientation.
3. **Tier 2 — Source and tests**  
   Read actual source, config, tests, and docs before editing or making exact runtime claims.

The trust boundary is always:

> **index routes, map orients, source decides.**

## Prompt injection policy

The Pi extension can automatically inject lightweight project-map guidance into the agent context. Behavior is controlled by `promptInjectionMode` in `.pi-project-map.json`.

### Before init

No synthetic map content is injected. The agent sees only a visible startup hint telling it to run `project_map_init`.

### After init

The root pair is guaranteed to load first:
- root `.pi-map.index.md`
- root `.pi-map.md`

Additional directory pairs are expanded only while the configured context budget allows.

### Mode ladder

| Mode | Behavior |
|------|----------|
| `off` | No automatic injection. |
| `advisory` | Visible hints/reminders only; maps are read manually. |
| `strong` | Root pair injection, budgeted expansion, reinjection on relevant turns. |
| `strict` | Same as `strong`, plus a visible guard for sensitive turns when the protocol path is missing. |

The **protocol path** is present when outgoing context contains:
- the canonical root-pair marker/block
- the trust-boundary instruction

In `strict` mode, a sensitive action can be bypassed explicitly with:

```text
[PI_MAP_BYPASS: <brief justification>]
```

### Context budget

Default automatic-injection budget is the smaller of:
- **15%** of the active model context window
- **100,000 tokens** absolute cap

If the runtime cannot discover the model context window, it falls back to the absolute cap.

## Retrieval is separate

`project-map context <query>` and `project_map_context` are **separate, on-demand retrieval** paths. They do **not** replace automatic prompt injection.

Retrieval is deterministic and metadata-driven:
1. score every directory's paired map/index metadata against the query
2. keep the top matches (default: 3)
3. return a compact markdown bundle with indexes, maps, likely files, and symbols

Use retrieval for targeted navigation when you already have a specific question.

## Configuration overview

Create `.pi-project-map.json` in the project root:

```json
{
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000,
  "llmProvider": "openai",
  "llmModel": "gpt-4o-mini",
  "ignorePatterns": ["node_modules", ".git"],
  "tagCap": 8,
  "workflowHintCap": 5
}
```

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

Key knobs:
- `promptInjectionMode` — `off`, `advisory`, `strong`, `strict`
- `contextBudgetPercent` — relative share of model context used for automatic injection
- `contextBudgetMaxTokens` — hard absolute cap on automatic injection
- `llmProvider` / `llmModel` / `llmBaseUrl` — standalone CLI provider settings
- `ignorePatterns` — directories/files to skip
- `tagCap` / `workflowHintCap` — routing metadata limits

## Documentation map

- [`SKILL.md`](SKILL.md) — skill definition and agent/operator instructions
- [`usage-guide.md`](usage-guide.md) — practical workflows and examples
- [`design-doc.md`](design-doc.md) — architecture and implementation details
- [`troubleshooting.md`](troubleshooting.md) — common issues and recovery steps

## Known limitations

- token budgeting is best-effort, not tokenizer-exact
- relevant-turn detection uses explicit event types plus heuristics
- provider payload fallback depends on runtime serialization shapes
- retrieval routes and orients; it never replaces source verification