alex/pi-map
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh README

Browse Source
This commit is contained in:
Alex
2026-07-27 15:24:01 +02:00
parent 3e7410b6bd
commit 97a4dd22f5
1 changed files with 49 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -125
View File
@@ -1,140 +1,74 @@
# pi-project-map
> Pi skill and CLI for hierarchical project analysis.
A Pi extension and command-line tool that generates paired project-navigation artifacts: `.pi-map.index.md` files for routing and `.pi-map.md` files for directory orientation. The artifacts help agents navigate a codebase; source remains the authority.
`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.
## Status and limitations
## What it is
- Generation and repair commands call an LLM and write map artifacts into the target project.
- `validate` without `--fix` checks artifacts without creating an LLM client; `validate --fix` can modify them and requires an LLM.
- Token budgeting and relevant-turn detection are best-effort. Retrieved maps route and orient work but do not replace source verification.
- No Node.js version requirement or deployment configuration is declared in this repository.
For every non-ignored directory, the tool produces two files:
## Install and develop
| 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:
Install the published CLI globally:
```bash
npm install -g pi-project-map
```
Generate paired artifacts in a repo:
For local development, install dependencies and build from this repository:
```bash
cd my-project
project-map init
npm install
npm run build
```
For standalone CLI usage, provide an LLM provider/API key. For example:
Available development checks:
```bash
export OPENAI_API_KEY=...
project-map init
npm run test
npm run lint
npm run typecheck
npm run dev
```
Inside Pi, the extension uses Pi's configured model automatically.
`npm run dev` runs TypeScript in watch mode. The project declares no deployment command.
## Command overview
## Use the CLI
| 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. |
Run the installed `project-map` command from the project to map. Use `--help` or `--version` for CLI metadata.
```bash
project-map init [path]
project-map patch <file>
project-map validate [--fix] [path]
project-map reinit [path]
project-map context <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>"`
1. Run `project-map init` to generate maps for a project.
2. After editing a file, run `project-map patch <file>`.
3. Run `project-map validate` before relying on maps; use `--fix` only when you intend to repair artifacts.
4. Use `project-map context "<query>"` to retrieve a ranked context bundle.
## Operating model
`init`, `patch`, `reinit`, and `validate --fix` mutate `.pi-map.md` and/or `.pi-map.index.md` artifacts. `context` retrieves from existing artifacts.
Follow a three-tier model when consuming project maps:
### Pi extension
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 repository exposes `pi-extension.ts` as a Pi extension. Inside Pi it uses Pi's configured model and registers equivalent `project_map_*` tools. The extension can also inject project-map guidance according to `promptInjectionMode`.
The trust boundary is always:
## LLM configuration
> **index routes, map orients, source decides.**
Standalone CLI use needs credentials for the selected provider. Do not commit keys.
## Prompt injection policy
- `openai` (the default) reads `OPENAI_API_KEY`; its model can be set with `OPENAI_MODEL` or `LLM_MODEL`.
- `kimi` reads `KIMI_API_KEY` (or `KIMI_COM_API_KEY`); its model can be set with `KIMI_MODEL` or `LLM_MODEL`.
- CLI options `--llm-provider=openai|kimi`, `--llm-model=<model>`, and `--llm-base-url=<url>` override corresponding settings for a command.
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:
Create an optional `.pi-project-map.json` in the project being mapped. It is merged with the defaults:
```json
{
@@ -149,26 +83,16 @@ Create `.pi-project-map.json` in the project root:
}
```
Providing `ignorePatterns` replaces the built-in default list, so include any defaults you want to keep.
`promptInjectionMode` accepts `off`, `advisory`, `strong`, or `strict`. Supplying `ignorePatterns` **replaces** the built-in ignore list rather than extending it. Additional supported settings include `llmBaseUrl` and `reinitFullThresholdPercent`.
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
## Repository layout
## Documentation map
- `src/` — CLI, map generation, validation, retrieval, configuration, and LLM clients
- `pi-extension.ts` — Pi extension entry point
- `SKILL.md` — Pi skill definition and operator guidance
- `usage-guide.md`, `design-doc.md`, `troubleshooting.md` — additional usage and design documentation
- `package.json` — package metadata, dependencies, and npm scripts
- [`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
## Operations
## 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
There is no server or deployment manifest. Operate the tool from the project being mapped and keep generated maps under the target project's normal review and version-control practices.