# pi-project-map

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.

## Status and limitations

- 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.

## Install and develop

Install the published CLI globally:

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

For local development, install dependencies and build from this repository:

```bash
npm install
npm run build
```

Available development checks:

```bash
npm run test
npm run lint
npm run typecheck
npm run dev
```

`npm run dev` runs TypeScript in watch mode. The project declares no deployment command.

## Use the CLI

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. 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.

`init`, `patch`, `reinit`, and `validate --fix` mutate `.pi-map.md` and/or `.pi-map.index.md` artifacts. `context` retrieves from existing artifacts.

### Pi extension

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`.

## LLM configuration

Standalone CLI use needs credentials for the selected provider. Do not commit keys.

- `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.

Create an optional `.pi-project-map.json` in the project being mapped. It is merged with the defaults:

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

`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`.

## Repository layout

- `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

## Operations

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.