# pi-project-map

A Pi skill that generates and maintains a hierarchical, machine-readable analysis of a software project. Each directory gets a `.pi-map.md` file containing architectural context, exported symbols, and dependencies.

## Tools

### `project-map:init [root]`
Runs a full project scan and generates `.pi-map.md` files in every directory.

### `project-map:patch <file-path>`
Updates the `.pi-map.md` for the directory containing the given file. Uses full rewrite for small packages (< 10 files) or section-level patch for larger packages.

### `project-map:validate [root]`
Checks all `.pi-map.md` files for staleness: missing files, orphaned entries, changed signatures, and dirty markers.

### `project-map:reinit [path]`
Force full re-initialization of the entire project or a specific subtree. Clears all dirty markers.

## Format

Each `.pi-map.md` uses dense markdown with conventions:

```markdown
# pkg/auth
## role
Auth layer: JWT issuance, validation, refresh. Stateless. Dep: pkg/crypto, pkg/db.
## files
- tokens.ts | JWT gen/val | exp: issueToken, verifyToken, refreshToken | dep: crypto/hmac, db/sessions
- middleware.ts | HTTP auth guard | exp: requireAuth, requireRole | dep: tokens/verifyToken
## arch
Guard pattern on routes. Tokens short-lived (15m), refresh long-lived (7d). Rotation on every use.
## dirty
-
```

## Configuration

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

```json
{
  "ignorePatterns": ["node_modules", ".git"],
  "smallPackageThreshold": 10,
  "llmModel": "gpt-4o-mini",
  "contextBudget": 4000,
  "autoInjectPrompt": true
}
```

## Installation

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

Then add to your Pi skills configuration.