From 97a4dd22f5744af2390c514fec45dcc1ba836276 Mon Sep 17 00:00:00 2001 From: Alex Blank Date: Mon, 27 Jul 2026 15:24:01 +0200 Subject: [PATCH] docs: refresh README --- README.md | 174 +++++++++++++++--------------------------------------- 1 file changed, 49 insertions(+), 125 deletions(-) diff --git a/README.md b/README.md index 4304a78..b10fb8d 100644 --- a/README.md +++ b/README.md @@ -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 ` | `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 ` | `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 +project-map validate [--fix] [path] +project-map reinit [path] +project-map context +``` Typical workflow: -1. `project-map init` on first use -2. after editing source, `project-map patch ` -3. before broad architectural decisions, `project-map validate` -4. for targeted exploration, `project-map context ""` +1. Run `project-map init` to generate maps for a project. +2. After editing a file, run `project-map patch `. +3. Run `project-map validate` before relying on maps; use `--fix` only when you intend to repair artifacts. +4. Use `project-map context ""` 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=`, and `--llm-base-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: ] -``` - -### 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 ` 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.