pi-map/README.md

# pi-project-map

Pi skill for hierarchical project analysis.

## What it does

Generates **paired** project-analysis artifacts throughout your project:

- `.pi-map.index.md` — routing-first index for deciding what to open next
- `.pi-map.md` — orientation-first rich map for understanding a directory

This gives Pi agents fast navigation plus deeper architectural context without reading every source file up front.

## Quick Start

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

## Agent operating model

### Tier 0
Always start with:
- `Project Map Protocol`
- root `.pi-map.index.md`

### Tier 1
Load likely relevant directory indexes first, then open the strongest-match rich maps.

### Tier 2
Read actual source, tests, config, and docs before editing or making exact runtime claims.

**Trust boundary:** index routes, map orients, source decides.

## Prompt Injection Policy

The Pi extension can automatically inject lightweight project-map guidance into the agent context according to the configured `promptInjectionMode`.

### Before init
When no `.pi-map.md` / `.pi-map.index.md` artifacts exist, only a visible startup hint is injected. It tells the agent that the project-map extension is active and to run `project_map_init`. No synthetic or fake map content is ever injected before real artifacts exist.

### After init
Once real artifacts exist, the runtime guarantees that the root pair is loaded before any budgeted expansion:

- root `.pi-map.index.md`
- root `.pi-map.md`

Additional directory pairs are expanded only while the configured context budget allows, in shallow-first order.

### Trust boundary
Injected maps and indexes are navigation and orientation aids, not final authority:

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

If an injected artifact and the source disagree, source wins. Always verify critical behavior from source before editing or making exact runtime claims.

### Mode ladder
- `off`: no automatic injection beyond existing tool/docs discovery.
- `advisory`: inject startup/init hints and allow optional root-pair preload; use light reminders.
- `strong` (default): inject the root pair, expand under the configured budget, run reinjection checks on relevant turns, and remind before edits or architecture-sensitive reasoning.
- `strict`: same as `strong`, plus require an explicit bypass justification before sensitive edits or architectural claims when the protocol path is missing.

The **protocol path** is present when the outgoing context contains the canonical injected root-pair block and the trust-boundary instruction. In `strict` mode, sensitive actions without it are blocked unless the agent includes `[PI_MAP_BYPASS: <brief justification>]`.

### Context budget
The default budget is **15% of the active model context window**, capped at **100k tokens**. The smaller of the relative and absolute values wins. If the runtime cannot discover the active model's context window, it falls back to the absolute cap.

Configure it in `.pi-project-map.json`:

```json
{
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000
}
```

## Retrieval
When you have a specific query (e.g. "authentication logic" or "routing metadata"):
1. Run `project-map context <query>` or use the Pi tool `project_map_context`
2. Read the returned **Context bundle** — it contains relevant indexes, maps, likely files, and symbols
3. Always verify critical behavior from source before editing

Retrieval via `project_map_context` (tool) or `project-map context` (CLI) remains a separate, on-demand path. Use it for targeted navigation when you have a specific query; automatic injection does not replace it.

### Integration-test expectations and known limitations
The implementation is validated by integration tests covering:

- pre-init hint behavior,
- post-init root-pair preload,
- budgeted expansion behavior,
- canonical-marker dedupe,
- reinjection after compaction,
- reinjection after root-pair artifact changes,
- mixed visibility behavior,
- guidance-mode differences,
- strict-mode bypass behavior.

Known limitations:

- Token estimation is best-effort (≈ 4 chars per token); actual provider token counts may differ.
- Relevant-turn detection uses explicit event types when available and falls back to heuristics on generic turns.
- Message-layer scanning is preferred; provider-payload serialization quirks require a fallback scan path.

## Commands

```bash
project-map init
project-map patch <file>
project-map validate [--fix]
project-map reinit
project-map context <query>
```

### Context retrieval

`project-map context <query>` searches the paired map/index artifacts and returns a compact markdown bundle with the most relevant directories, files, and symbols. No LLM call is needed — it uses deterministic metadata scoring.

## Configuration

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

```json
{
  "ignorePatterns": ["node_modules", ".git"],
  "smallPackageThreshold": 10,
  "contextBudget": 4000,
  "autoInjectPrompt": true,
  "tagCap": 8,
  "workflowHintCap": 5,
  "promptInjectionMode": "strong",
  "contextBudgetPercent": 15,
  "contextBudgetMaxTokens": 100000
}
```

- `promptInjectionMode`: `off`, `advisory`, `strong` (default), or `strict`.
- `contextBudgetPercent`: relative share of the active model context window used for automatic map/index injection.
- `contextBudgetMaxTokens`: hard absolute cap on the injection budget.

## Design

See [design-doc.md](design-doc.md) for the full specification.

## Implementation Plan

See [implementation-plan.md](implementation-plan.md) for the engineering roadmap.