@ivannikov-pro/ai-context-surgeon 1.0.0

package/strategy/package-json-guide.md

@@ -0,0 +1,541 @@
+<!-- FNH: Strategy — package.json standard for AI agents | SECTIONS: Fields Priority, Ordering, Lean Meta | DEPS: none -->
+
+# 📦 package.json — Field Map for AI Agents
+
+> Guide: Which package.json fields are important, which are noise, how to order them | SECTIONS: Fields Priority, Ordering, Lean Meta, Tools Integration | DEPS: none
+
+---
+
+## Philosophy
+
+```
+package.json of a typical project:   ~80–200 lines, ~2K–5K tokens
+package.json that an AI needs:       ~15–40 lines, ~300–800 tokens
+                                     ─────────────────────────────
+                                     ~80% of content = noise for the agent
+```
+
+An AI agent reads package.json to answer 4 questions:
+
+1. **What is this?** → `name`, `description`
+2. **How to run it?** → `scripts`
+3. **What does it depend on?** → `dependencies`
+4. **What does it export?** → `main`, `exports`, `type`
+
+**Everything else is noise** that fills the context window but doesn't help solve the task.
+
+---
+
+## Priority Field Map
+
+### 🔴 Tier 1 — Critical (Agent MUST read)
+
+Without these fields, the agent won't understand the package. Maximum information density.
+
+| Field | Why the agent needs it | Tokens | Example |
+| --- | --- | --- | --- |
+| `name` | Identity and scope | ~5 | `"@project/api"` |
+| `description` | Understand purpose in 1 second | ~15 | `"REST API server with Express"` |
+| `scripts` | Know how to build/test/run | ~30–60 | `{ "build": "tsc", "test": "vitest" }` |
+| `dependencies` | See runtime dependencies | ~20–100 | List of packages |
+| `main` / `module` / `exports` | Understand entry point and format | ~10–20 | `"./dist/index.js"` |
+| `type` | `"module"` vs `"commonjs"` — affects import/require | ~3 | `"module"` |
+
+**Tier 1 Cost: ~80–200 tokens** — this is all that's needed for 90% of tasks.
+
+---
+
+### 🟡 Tier 2 — Useful (Read when necessary)
+
+Helpful in the context of specific tasks, but not always needed.
+
+| Field | When needed | Tokens | Recommendation |
+| --- | --- | --- | --- |
+| `devDependencies` | When setting up tooling, CI | ~50–300 | Keep it, but agent might skip it |
+| `peerDependencies` | When publishing package, versioning | ~10–30 | Keep it |
+| `version` | For bump, release, changelog | ~3 | Keep it |
+| `private` | When deciding "whether to publish" | ~3 | Keep it |
+| `engines` | For debugging "doesn't work on Node 18" | ~5 | Keep it |
+| `workspaces` | For understanding monorepo structure | ~10–20 | Only in root package.json |
+| `bin` | When creating CLI tools | ~5–15 | Keep if needed |
+| `files` | When publishing (what goes to npm) | ~10 | Keep it |
+
+**Tier 2 Cost: ~100–400 tokens**
+
+---
+
+### 🟢 Tier 3 — Metadata (Can be ignored)
+
+They don't affect code and don't help the agent solve tasks.
+
+| Field | Why it's noise | Tokens | Recommendation |
+| --- | --- | --- | --- |
+| `license` | Agent doesn't make legal decisions | ~3 | Keep it, but agent will skip |
+| `author` | Doesn't affect code | ~5–10 | Keep it |
+| `contributors` | Doesn't affect code | ~20–100 | Keep it |
+| `repository` | Agent is already in the repo | ~10 | Keep it |
+| `bugs` | Doesn't affect code | ~10 | Keep it |
+| `homepage` | Doesn't affect code | ~5 | Keep it |
+| `keywords` | Only for npm search | ~10–20 | Keep it |
+| `funding` | Doesn't affect code | ~5–15 | Keep it |
+
+**Tier 3 Cost: ~70–180 tokens** — harmless but useless noise.
+
+---
+
+### ⚫ Tier 4 — Harmful (Actively impedes agent)
+
+These fields **bloat the context** and create noise that disrupts focus.
+
+| Field | Why harmful | Typical tokens | Recommendation |
+| --- | --- | --- | --- |
+| Inline `jest` config | 30–100 lines inside package.json | ~200–500 | ❌ **Extract** to `jest.config.ts` |
+| Inline `eslint` config | Rules, extends, overrides | ~100–400 | ❌ **Extract** to `.eslintrc.js` |
+| Inline `prettier` config | Formatting | ~30–80 | ❌ **Extract** to `.prettierrc` |
+| Inline `babel` config | Transformations | ~50–200 | ❌ **Extract** to `babel.config.js` |
+| Inline `browserslist` | Target browsers | ~20–30 | ❌ **Extract** to `.browserslistrc` |
+| `resolutions` / `overrides` | Long lists of version overrides | ~100–500 | ⚠️ Keep only in root |
+| `devDependencies` (50+ entries) | Huge tooling list | ~300–800 | ⚠️ Extract to root where possible |
+| `husky` / `lint-staged` config | Git hooks | ~30–80 | ❌ **Extract** to `.husky/` + `.lintstagedrc` |
+| `config` / custom fields | Arbitrary data | ~50–200 | ⚠️ Extract to separate `.config` file |
+| Long `exports` maps | 20+ entry points | ~100–300 | ⚠️ Simplify or document |
+
+**Tier 4 Cost: ~500–3000 tokens** — this is pure garbage for 99% of agent tasks.
+
+> [!CAUTION]
+> **One inline jest-config (40 lines) costs as much as all of Tier 1 (name + description + scripts + deps).**
+> The agent spends context parsing jest rules instead of understanding business logic.
+
+---
+
+## Ideal Field Order
+
+Place fields **from most important to least important**. The agent reads top to bottom.
+If the context gets truncated, the less important stuff gets cut.
+
+```jsonc
+{
+  // ─── TIER 1: Identity ───
+  "name": "@project/api",
+  "version": "1.2.0",
+  "description": "REST API server — Express + Zod + Prisma",
+  "private": true,
+  "type": "module",
+
+  // ─── TIER 1: Entry points ───
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+
+  // ─── TIER 1: Commands ───
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint src/",
+  },
+
+  // ─── TIER 1: Runtime dependencies ───
+  "dependencies": {
+    "@project/core": "workspace:*",
+    "@project/shared": "workspace:*",
+    "express": "^4.18.0",
+    "zod": "^3.22.0",
+    "prisma": "^5.0.0",
+  },
+
+  // ─── TIER 2: Dev tooling ───
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0",
+    "@types/express": "^4.17.0",
+  },
+
+  // ─── TIER 3: Metadata (EOF) ───
+  "license": "MIT",
+  "author": "team",
+}
+```
+
+### Rule: "30 lines or less"
+
+> [!IMPORTANT]
+> The ideal package.json for a monorepo package is **≤30 lines**.
+> If it's larger — look for things to extract into a separate config file.
+
+---
+
+## Monorepo Conventions
+
+### Root package.json
+
+```jsonc
+{
+  "name": "monorepo-root",
+  "private": true,
+  "workspaces": ["packages/*", "apps/*"],
+
+  "scripts": {
+    "build": "turbo build",
+    "test": "turbo test",
+    "lint": "turbo lint",
+    "dev": "turbo dev",
+  },
+
+  // devDependencies here — shared tooling
+  "devDependencies": {
+    "turbo": "^2.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0",
+    "eslint": "^9.0.0",
+  },
+}
+```
+
+**Key point**: Hoist as many `devDependencies` to the **root** as possible. Packages inherit them.
+
+### Package package.json
+
+```jsonc
+{
+  "name": "@project/core",
+  "version": "1.0.0",
+  "description": "Domain entities and business logic",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+  },
+
+  "dependencies": {
+    "@project/shared": "workspace:*",
+  },
+}
+```
+
+**~15 lines. ~200 tokens. Everything you need.**
+
+---
+
+## What to Extract from package.json
+
+| What | Where | Format |
+| --- | --- | --- |
+| Jest/Vitest config | `vitest.config.ts` / `jest.config.ts` | TypeScript |
+| ESLint config | `eslint.config.js` / `.eslintrc.js` | JavaScript |
+| Prettier config | `.prettierrc` | JSON |
+| Babel config | `babel.config.js` | JavaScript |
+| TypeScript config | `tsconfig.json` | JSON (already separate) |
+| Browserslist | `.browserslistrc` | Plaintext |
+| Lint-staged | `.lintstagedrc` | JSON |
+| Husky hooks | `.husky/pre-commit` | Shell |
+| Commitlint | `commitlint.config.js` | JavaScript |
+| Stylelint | `.stylelintrc` | JSON |
+| PostCSS | `postcss.config.js` | JavaScript |
+
+### Rule: If config > 5 lines → extract it
+
+```jsonc
+// ❌ Bad: 40 lines of jest-config in package.json
+{
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "moduleNameMapper": { ... },
+    "coverageThreshold": { ... },
+    "transformIgnorePatterns": [ ... ],
+    // ... 30 more lines
+  }
+}
+
+// ✅ Good: separate file
+// vitest.config.ts exists nicely alongside
+// package.json contains no generic configs
+```
+
+---
+
+## scripts — order and conventions
+
+### Standard Set (in this order)
+
+```jsonc
+"scripts": {
+  // 1. Development
+  "dev": "...",           // Run for development
+  "start": "...",         // Run for production
+
+  // 2. Build
+  "build": "...",         // Build process
+  "clean": "...",         // Clean artifacts
+
+  // 3. Quality
+  "test": "...",          // Run tests
+  "test:watch": "...",    // Tests in watch mode
+  "lint": "...",          // Style check
+  "lint:fix": "...",      // Auto-fix style
+  "typecheck": "...",     // Type checker
+
+  // 4. Utility (if needed)
+  "db:migrate": "...",    // DB migrations
+  "db:seed": "...",       // DB seeder
+  "generate": "..."       // Code generation
+}
+```
+
+### Antipatterns in scripts
+
+```jsonc
+// ❌ Bad: unreadable one-liners
+"scripts": {
+  "build": "rimraf dist && cross-env NODE_ENV=production webpack --config webpack.prod.js --progress --profile --bail && node scripts/post-build.js && echo 'Done'"
+}
+
+// ✅ Good: extract to script
+"scripts": {
+  "build": "bash scripts/build.sh"
+}
+```
+
+```jsonc
+// ❌ Bad: 25 scripts
+"scripts": {
+  "prebuild": "...",
+  "build": "...",
+  "postbuild": "...",
+  "pretest": "...",
+  "test": "...",
+  "test:unit": "...",
+  "test:integration": "...",
+  "test:e2e": "...",
+  "test:coverage": "...",
+  // ... 16 more scripts
+}
+
+// ✅ Good: 5–8 core scripts
+"scripts": {
+  "dev": "...",
+  "build": "...",
+  "test": "vitest run",
+  "test:watch": "vitest",
+  "lint": "eslint src/",
+  "typecheck": "tsc --noEmit"
+}
+```
+
+---
+
+## dependencies — clean and organized
+
+### Rules
+
+1. **Separate runtime and dev**: `dependencies` = needed in production, `devDependencies` = tooling
+2. **Internal deps use `workspace:*`**: `"@project/core": "workspace:*"`
+3. **Minimum deps**: for every dependency ask "is this strictly needed right here?"
+4. **Hoist shared devDeps to root**: TypeScript, ESLint, test frameworks — to root
+
+### Token Cost of dependencies
+
+| Dependencies count | Approx Tokens | Action |
+| --- | --- | --- |
+| 1–10 | ~30–60 | ✅ Normal |
+| 11–25 | ~60–150 | ⚠️ Check — is everything needed? |
+| 26–50 | ~150–300 | 🟡 A lot. Package might be doing too much |
+| 50+ | ~300–600 | 🔴 Split the package into multiple |
+
+---
+
+## exports — when simple is better
+
+```jsonc
+// ✅ Simple (1 entry point — ideal for monorepo packages)
+{
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}
+
+// 🟡 Medium (2-3 entry points — acceptable)
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js"
+    }
+  }
+}
+
+// ❌ Complex (10+ entry points — the agent will get lost)
+{
+  "exports": {
+    ".": { ... },
+    "./components": { ... },
+    "./hooks": { ... },
+    "./utils": { ... },
+    "./types": { ... },
+    "./styles": { ... },
+    "./icons": { ... },
+    "./theme": { ... },
+    "./locales": { ... },
+    "./server": { ... }
+  }
+}
+// → If you need 10+ exports — split into smaller packages
+```
+
+---
+
+## Checklist: Bring package.json to ideal state
+
+### For every package in the monorepo:
+
+- [ ] ≤30 lines
+- [ ] Has `name` with scope (`@project/...`)
+- [ ] Has `description` (one sentence)
+- [ ] Has `type: "module"` (or `"commonjs"`)
+- [ ] `scripts` contains only `dev`, `build`, `test`, `lint` (4–8 scripts)
+- [ ] No inline configs (jest, eslint, prettier, babel)
+- [ ] `dependencies` — only runtime (≤25 entries)
+- [ ] Internal deps via `workspace:*`
+- [ ] `devDependencies` — absolute minimum (shared tooling in root)
+- [ ] No `resolutions` / `overrides` (only in root)
+- [ ] `main` and `types` specified
+- [ ] Fields are ordered logically (Tier 1 → Tier 3)
+- [ ] Metadata (license, author, repository) — at the EOF
+
+### For root package.json:
+
+- [ ] `private: true`
+- [ ] `workspaces` defined
+- [ ] Shared `devDependencies` hoisted here
+- [ ] `scripts` — turbo/nx commands
+- [ ] `resolutions`/`overrides` — only here if needed
+
+---
+
+## The "Lean + Enrich" Strategy — minimum for dev, full for publishing
+
+> [!TIP]
+> **Key Insight**: 90% of the time package.json is read by AI agents and developers.
+> The npm registry only sees it at the moment of `npm publish`.
+> Why keep metadata meant for npm, if it only makes the agent suffer?
+
+### Concept
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ DEVELOPMENT (99% of time)                                   │
+│                                                             │
+│   package.json = LEAN (15–20 lines)                         │
+│   Only Tier 1 + Tier 2                                      │
+│   No: author, license, repository, keywords, bugs, funding  │
+│                                                             │
+│   Agent sees ~200 tokens instead of ~800                    │
+├─────────────────────────────────────────────────────────────┤
+│ PUBLISHING (1% of time)                                     │
+│                                                             │
+│   node tools/enrich-package-json.js . --all                 │
+│   package.json = FULL (40–50 lines)                         │
+│   Added: author, license, repository, keywords, etc.        │
+│                                                             │
+│   npm publish                                               │
+│                                                             │
+│   node tools/enrich-package-json.js . --all --restore       │
+│   package.json = LEAN again                                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Configuration: `.publish-meta.json`
+
+All metadata for publishing is stored in a **single file** at the monorepo root:
+
+```jsonc
+{
+  "shared": {
+    "author": "Your Name <you@example.com>",
+    "license": "MIT",
+    "engines": { "node": ">=18.0.0" },
+  },
+  "repositoryPattern": "git+https://github.com/org/repo.git",
+  "homepagePattern": "https://github.com/org/repo/tree/main/packages/{{package}}",
+  "bugsUrl": "https://github.com/org/repo/issues",
+  "defaultFiles": ["dist", "README.md", "LICENSE"],
+  "packages": {
+    "@scope/core": { "keywords": ["core", "domain"] },
+    "@scope/api": { "keywords": ["api", "rest"] },
+  },
+}
+```
+
+### Commands
+
+```bash
+# Preview (changes nothing)
+node tools/enrich-package-json.js . --all --dry-run
+
+# Enrich before publishing
+node tools/enrich-package-json.js . --all
+
+# Publish
+turbo publish
+
+# Restore to lean version
+node tools/enrich-package-json.js . --all --restore
+```
+
+### CI/CD Integration
+
+```yaml
+# GitHub Actions — publish workflow
+- name: Enrich package.json
+  run: node tools/enrich-package-json.js . --all
+
+- name: Publish
+  run: npx turbo publish
+
+- name: Restore lean package.json
+  run: node tools/enrich-package-json.js . --all --restore
+
+- name: Commit restore
+  run: |
+    git add packages/*/package.json
+    git commit -m "chore: restore lean package.json" || true
+    git push
+```
+
+### Benefits
+
+| Metric | Without Lean+Enrich | With Lean+Enrich |
+| --- | --- | --- |
+| Lines in package.json | 40–80 | 15–20 |
+| Tokens per file | ~600–1500 | ~200–300 |
+| Metadata duplication | In every package | 1 file for entire monorepo |
+| npm publish works | ✅ | ✅ (after enrich) |
+| Agent works efficiently | ❌ noise | ✅ clean context |
+
+---
+
+## Context Cost Formula
+
+```
+package.json cost ≈
+  (tier1_fields × 1.0)     // always read
+  + (tier2_fields × 0.5)   // sometimes read
+  + (tier3_fields × 0.1)   // skipped
+  + (tier4_fields × 2.0)   // HARMFUL — eats context AND breaks focus
+
+Ideal: ≤300 tokens
+Normal: ≤800 tokens
+Bad: ≤2000 tokens
+Harmful: >2000 tokens (inline configs, 50+ deps)
+```
+
+---
+
+_ai-context-surgeon / strategy | 2026-04-04_

package/templates/AGENTS.md.template

@@ -0,0 +1,148 @@
+<!-- FNH: Template — AGENTS.md for new projects | SECTIONS: Rules, Structure, ai-context-surgeon | DEPS: none -->
+# {{PROJECT_NAME}} — Agent Rules
+
+> Config: AGENTS.md — highest priority rules for all AI agents in this repository | SECTIONS: Rules, Naming, FNH, Structure, ai-context-surgeon | DEPS: none
+
+> This file has the HIGHEST PRIORITY. All agents MUST follow these rules without exception.
+
+## Language & Communication
+- Respond to the user in: {{USER_LANGUAGE}}
+- All agent-facing content MUST be in English:
+  - Code comments, variable names, commit messages
+  - FNH headers (all file types)
+  - JSDoc annotations
+  - README Source Structure descriptions
+  - AGENTS.md rules
+  - Knowledge Items and Skills
+- Rationale: English is 1.5–2x more token-efficient than non-Latin scripts and has stronger enforcement calibration in LLMs
+
+## Architecture Rules
+- Every package MUST have a `README.md` with Source Structure section
+- No cross-package imports except through `src/index.ts`
+- Shared types go to `packages/shared/types/`
+- Dependency direction: `routes → services → repositories → entities`
+- No circular dependencies between packages
+
+## Navigation Rules (CRITICAL for context optimization)
+- Before modifying ANY package, ALWAYS read its `README.md` first
+- Do NOT scan the entire monorepo — work within the target package only
+- If you need types from another package, read ONLY its `src/types.ts` or `src/index.ts`
+- Do NOT read more than 5 files before starting work
+- Use `grep_search` to find specific code instead of reading entire files
+
+## File Navigation Headers (FNH)
+
+MANDATORY RULE: Every file in this repository MUST have a navigation header on its first lines.
+
+- `.ts`/`.js`: `/** Category: Name — description | deps: ... */`
+- `.md`: `<!-- FNH comment -->` on line 1, AND `> Category: description` (blockquote after H1)
+- `.sh`: `# Tool/Script: description` (after shebang)
+- `.yml`/`.yaml`: `# Config: description` (first line)
+- `.json`: `"description": "..."` (e.g., package.json)
+- `.jsonc`/others: `// Config: description` (if comments supported)
+
+**FNH Freshness Rule**: When you modify a file, you MUST update its FNH to reflect changes:
+- ADD a new export/function/route → add it to the FNH
+- REMOVE an export/function/route → remove it from the FNH
+- RENAME anything → update it in the FNH
+- Change deps, @throws, or side effects → update the FNH
+- FNH does not exist → create one BEFORE starting your work
+
+A stale FNH actively misleads other agents. Keeping it current is MANDATORY.
+
+## Context Exclusion (.antigravityignore)
+
+MANDATORY RULE: Agents MUST respect and maintain the `.antigravityignore` file to prevent context pollution.
+- Hide lock files (`pnpm-lock.yaml`, `package-lock.json`)
+- Hide build artifacts (`dist/`, `.next/`, `coverage/`)
+- Hide cache directories (`.turbo/`, `.cache/`)
+- NEVER hide source code, tests (`*.test.ts`), or `README.md`
+
+## Code Conventions
+- TypeScript strict mode — no `any`
+- Validation: {{VALIDATION_LIB}} (e.g., Zod)
+- Error handling: {{ERROR_PATTERN}} (e.g., Result<T, E> pattern)
+- Logging: {{LOGGING_LIB}} (e.g., Winston structured JSON)
+- Testing: {{TEST_FRAMEWORK}} (e.g., Vitest), minimum {{COVERAGE}}% coverage
+
+## JSDoc Rules
+- File headers: AI-optimized one-line format (see `npx @ivannikov-pro/ai-context-surgeon@latest strategy jsdoc`)
+- Function JSDoc: ONLY for information invisible from TypeScript types
+  - ✅ @throws, side effects, @mutates, @deprecated, business rules
+  - ❌ @param {type}, @returns {type}, @author, @since, @fileoverview
+- In JavaScript (non-TS) files: @param types ARE needed (replace missing TS)
+
+## File Operations
+- Never modify files in packages you are not explicitly asked to work on
+- After changes, run: `{{BUILD_COMMAND}}`
+- Before signaling done, run: `{{TEST_COMMAND}}`
+
+## Naming Conventions
+- Files: `kebab-case.ts`
+- Directories: `kebab-case`
+- Classes: `PascalCase`
+- Functions/variables: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Packages: `@{{SCOPE}}/kebab-case`
+- Types/Interfaces: `PascalCase` (no `I` prefix)
+
+## Package Ownership
+{{PACKAGE_OWNERSHIP_TABLE}}
+<!-- Example:
+| Package | Owner | Description |
+|----|----|----| 
+| packages/core | backend-team | Domain logic |
+| packages/api | backend-team | REST API |
+| packages/web | frontend-team | React SPA |
+-->
+
+---
+
+## 🔧 AI Context Surgeon — Tools & Knowledge API
+
+This repository is optimized with [ai-context-surgeon](https://github.com/ivannikov-pro/ai-context-surgeon).
+All tools, roles, strategies, and prompts are available on-demand — no file install needed.
+
+### Quick Reference for AI Agents
+
+```bash
+# Browse everything available
+npx @ivannikov-pro/ai-context-surgeon@latest catalog
+
+# Get condensed task instructions (saves ~95% tokens vs reading docs)
+npx @ivannikov-pro/ai-context-surgeon@latest prompt fnh       # How to create FNH headers
+npx @ivannikov-pro/ai-context-surgeon@latest prompt jsdoc     # How to write JSDoc
+npx @ivannikov-pro/ai-context-surgeon@latest prompt god-file  # How to split large files
+
+# Run analysis tools
+npx @ivannikov-pro/ai-context-surgeon@latest radar            # FNH map of this repo
+npx @ivannikov-pro/ai-context-surgeon@latest godfiles         # Find files > 300 LOC
+npx @ivannikov-pro/ai-context-surgeon@latest context-weight   # Cognitive load analysis
+npx @ivannikov-pro/ai-context-surgeon@latest circular         # Circular dependency check
+
+# Read full strategy docs when needed
+npx @ivannikov-pro/ai-context-surgeon@latest strategy fnh
+npx @ivannikov-pro/ai-context-surgeon@latest strategy monorepo
+
+# Save any content to a file for other agents
+npx @ivannikov-pro/ai-context-surgeon@latest role scout --output .agents/scout-prompt.md
+npx @ivannikov-pro/ai-context-surgeon@latest checklist 1 --output .agents/phase-1.md
+```
+
+### When to Use
+
+| Situation | Command |
+| --- | --- |
+| Need to add FNH headers to files | `prompt fnh` |
+| Need to write JSDoc annotations | `prompt jsdoc` |
+| Need to split a god-file (>300 LOC) | `prompt god-file` |
+| Need to understand repo structure | `radar` |
+| Need to find heavy files | `context-weight` |
+| Need to write a package README | `prompt readme` |
+| Need full-pipeline optimization | `role scout` → `role architect` → `role surgeon` |
+
+### Benefits
+
+- **95% token savings**: `prompt fnh` = ~60 tokens (vs reading strategy doc = ~2,800 tokens)
+- **Always up-to-date**: `@latest` ensures the newest version
+- **Zero maintenance**: No files to keep in sync — tools run from npm cache