docs: rewrite documentation system
This commit is contained in:
+198
@@ -0,0 +1,198 @@
|
||||
# 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` |
|
||||
| Validation shows widespread 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 sparingly. It regenerates every pair from scratch and is the blunt instrument for widespread staleness.
|
||||
|
||||
### 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
|
||||
|
||||
### 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 many discrepancies:
|
||||
project-map reinit
|
||||
```
|
||||
|
||||
### Before a big refactor
|
||||
|
||||
```bash
|
||||
project-map validate
|
||||
# if needed:
|
||||
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 clean, read root .pi-map.md and key directory maps
|
||||
3. Cross-check claims against source
|
||||
4. If stale, run project-map reinit first
|
||||
```
|
||||
|
||||
## 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
|
||||
- reinit when many artifacts are stale 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,
|
||||
"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
|
||||
- `strict` is the safest enforcement mode; `strong` is the best default for everyday work
|
||||
Reference in New Issue
Block a user