@ivannikov-pro/ai-context-surgeon 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+<!-- FNH: Legal — MIT License | SECTIONS: Permissions, Conditions, Disclaimer | DEPS: none -->
+MIT License
+
+Copyright (c) 2026 Aleksandr Ivannikov, https://ivannikov.pro <hi@ivannikov.pro>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,372 @@
+<!-- FNH: Project — ai-context-surgeon AI-native Knowledge API | SECTIONS: Quick Start, For AI Agents, Catalog, CLI, Tools, Roles, Prompts, Workflows, Strategy, Source Structure | DEPS: none -->
+
+# ai-context-surgeon
+
+[![npm version](https://img.shields.io/npm/v/@ivannikov-pro/ai-context-surgeon.svg)](https://www.npmjs.com/package/@ivannikov-pro/ai-context-surgeon)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Toolkit: ai-context-surgeon — an AI-native Knowledge API for autonomous agents doing surgical monorepo restructuring. Roles, strategies, prompts, skills, templates, and analysis tools — all accessible on-demand via CLI. No install required. | SECTIONS: Quick Start, For AI Agents, Catalog, CLI, Tools, Roles, Prompts, Workflows, Strategy, Source Structure | DEPS: none
+
+**ai-context-surgeon** is a Knowledge API, not a traditional CLI tool. It provides on-demand access to roles, strategies, prompts, skills, templates, and analysis tools — everything an AI agent needs to optimize a monorepo's context for minimal token consumption.
+
+---
+
+## 🚀 Quick Start
+
+```bash
+# Browse everything available
+npx -y @ivannikov-pro/ai-context-surgeon@latest catalog
+
+# Run repo analysis
+npx -y @ivannikov-pro/ai-context-surgeon@latest radar
+
+# Get a role prompt for the AI agent to follow
+npx -y @ivannikov-pro/ai-context-surgeon@latest role scout
+
+# Get condensed task instructions (~60 tokens instead of ~2800)
+npx -y @ivannikov-pro/ai-context-surgeon@latest prompt fnh
+
+# Lightweight project setup
+npx -y @ivannikov-pro/ai-context-surgeon@latest init
+```
+
+---
+
+## 🤖 For AI Agents
+
+The npm package IS the knowledge base. The CLI IS the API.
+No files to copy. No install to maintain. Always the latest version.
+
+```bash
+# Step 1: Discover everything available
+npx @ivannikov-pro/ai-context-surgeon@latest catalog
+
+# Step 2: Read a role prompt and follow its instructions
+npx @ivannikov-pro/ai-context-surgeon@latest role scout
+
+# Step 3: Run analysis tools
+npx @ivannikov-pro/ai-context-surgeon@latest radar
+npx @ivannikov-pro/ai-context-surgeon@latest context-weight
+
+# Step 4: Get specific instructions for a task (saves 95% tokens)
+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
+npx @ivannikov-pro/ai-context-surgeon@latest prompt readme    # How to write package READMEs
+npx @ivannikov-pro/ai-context-surgeon@latest prompt agent-rules        # How to write AGENTS.md
+npx @ivannikov-pro/ai-context-surgeon@latest prompt context-exclusion  # How to set up .antigravityignore
+
+# Step 5: Read strategy docs when needed (full reference)
+npx @ivannikov-pro/ai-context-surgeon@latest strategy fnh
+npx @ivannikov-pro/ai-context-surgeon@latest strategy monorepo
+
+# Step 6: Delegate — output a role prompt and send to another agent
+npx @ivannikov-pro/ai-context-surgeon@latest role architect --output .agents/architect-prompt.md
+```
+
+---
+
+## 📈 Token Savings: Before / After
+
+```text
+╔═══════════════════════════════════════════════════════════════╗
+║  LEVEL 1: Blind Navigation (No rules)                         ║
+║  Agent reads 10 files ~3,300 lines            ≈  8,000 tokens ║
+╠═══════════════════════════════════════════════════════════════╣
+║  LEVEL 2: Traditional Docs (Reading markdown files)           ║
+║  Agent reads strategy doc ~560 lines          ≈  2,800 tokens ║
+╠═══════════════════════════════════════════════════════════════╣
+║  LEVEL 3: ai-context-surgeon (Knowledge API)                  ║
+║  Agent calls `prompt fnh`                     ≈     60 tokens ║
+╠═══════════════════════════════════════════════════════════════╣
+║  SAVINGS: 99.3%  (from 8,000 → 60 tokens per task)            ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+| Scenario | Tokens | Method |
+| --- | ---: | --- |
+| Blind repo navigation | ~8,000 | Agent reads random files |
+| Traditional Markdown Docs | ~2,800 | Agent reads `strategy/file-navigation-header.md` |
+| **Knowledge API** | **~60** | Agent calls `prompt fnh` |
+
+**JSDoc annotation example:**
+
+```typescript
+// BEFORE (220 tokens of noise):
+/**
+ * @fileoverview User Service
+ * @author Jane Developer
+ * @since 2024-03-15
+ */
+export class UserService {
+  /** @param {CreateUserInput} input @returns {Promise<User>} */
+  async create(input: CreateUserInput): Promise<User> { ... }
+}
+
+// AFTER (40 tokens — 82% reduction):
+/** Service: UserService — CRUD + auth | deps: prisma, bcrypt */
+export class UserService {
+  /** @throws Conflict(email) | hashes pw bcrypt 12 | sends welcome email */
+  async create(input: CreateUserInput): Promise<User> { ... }
+}
+```
+
+---
+
+## 📋 Catalog
+
+```bash
+npx @ivannikov-pro/ai-context-surgeon@latest catalog
+```
+
+| Category | Command | Count | Description |
+| --- | --- | ---: | --- |
+| 🔧 Tools | `radar`, `godfiles`, `circular`, `context-weight`, `sourcemaps` | 5 | Run analysis directly against any repo |
+| 🎭 Roles | `role <name>` | 6 | Agent role prompts (scout → inspector) |
+| 📖 Strategies | `strategy <name>` | 7 | Full reference docs (FNH, monorepo, JSDoc, ...) |
+| 💡 Prompts | `prompt <task>` | 6 | Condensed task instructions (~60 tokens each) |
+| 🧩 Skills | `skill <name>` | 2 | Reusable agent procedures |
+| 📝 Templates | `template <name>` | 9 | File seeds (AGENTS.md, README, package.json, ...) |
+| 📋 Checklists | `checklist <n>` | 5 | Phase task lists (1–5) |
+| 🧠 Knowledge | `knowledge <name>` | 3 | Reference knowledge items |
+
+---
+
+## 🖥️ CLI Commands
+
+### Content Access
+
+| Command | Description |
+| --- | --- |
+| `catalog` | List all available content across all categories |
+| `role <name>` | Output an agent role prompt |
+| `strategy <name>` | Output a strategy document |
+| `prompt <task>` | Output a condensed task prompt |
+| `skill <name>` | Output a skill procedure |
+| `template <name>` | Output a file template |
+| `checklist <n>` | Output a phase checklist (1–5) |
+| `knowledge <name>` | Output a knowledge item |
+
+All content commands support `--output <path>` to save to a file:
+```bash
+npx @ivannikov-pro/ai-context-surgeon@latest role scout --output .agents/scout.md
+npx @ivannikov-pro/ai-context-surgeon@latest checklist 1 --output .agents/phase-1.md
+```
+
+### Tool Execution
+
+| Command | Script | Description |
+| --- | --- | --- |
+| `radar` | `scan-fnh.sh` | Semantic FNH map of any repository |
+| `godfiles` | `detect-god-files.sh` | Find files exceeding LOC thresholds |
+| `circular` | `detect-circular-deps.sh` | Detect circular dependencies |
+| `context-weight` | `validate-context-weight.sh` | Identify files with high cognitive load (LOC + Fan-out) |
+| `sourcemaps` | `generate-source-map.sh` | Generate AI-friendly structure trees |
+
+### Project Setup
+
+| Command | Description |
+| --- | --- |
+| `init` | Creates `AGENTS.md`, `.antigravityignore`, and injects CI scripts into `package.json` |
+
+After `init`, these CI gates are available in `package.json`:
+```bash
+npm run check:hygiene     # FNH radar scan
+npm run check:god-files   # God file detection
+```
+
+---
+
+## 💡 Prompt Library
+
+Available via `prompt <task>` — each prompt is ~60 tokens vs ~2800 for the full strategy doc.
+
+| Key | Name | Description |
+| --- | --- | --- |
+| `fnh` | File Navigation Header | How to create FNH headers for any file type (all 5 mandatory layers) |
+| `jsdoc` | JSDoc Annotation | How to write AI-optimized JSDoc (what to annotate, what to skip) |
+| `readme` | Package README | How to write a README with Source Structure for AI agents |
+| `agent-rules` | AGENTS.md | How to write an AGENTS.md for any repository |
+| `context-exclusion` | Context Exclusion | How to configure `.antigravityignore` / `.aiignore` |
+| `god-file` | God File Splitting | How to split files >300 lines into focused modules |
+
+**Examples:**
+```bash
+npx @ivannikov-pro/ai-context-surgeon@latest prompt fnh
+npx @ivannikov-pro/ai-context-surgeon@latest prompt god-file
+npx @ivannikov-pro/ai-context-surgeon@latest prompt jsdoc --output /tmp/jsdoc-task.md
+```
+
+---
+
+## 🎭 Agent Roles
+
+6 specialized roles for the 5-phase optimization pipeline:
+
+| Role | Phase | Description | Model | Mode |
+| --- | --- | --- | --- | --- |
+| **Scout** | 1 — Analysis | Context reconnaissance, FNH radar, telemetry gathering | Gemini 3 Flash | Fast |
+| **Architect** | 2 — Planning | Design decisions, refactoring plan, package boundaries | Claude Opus 4.6 / Gemini 3.1 Pro | Planning |
+| **Surgeon** | 3 — Restructuring | Surgical code splitting, import fixing, god-file extraction | Gemini 3.1 Pro (High) | Fast |
+| **Librarian** | 4a — Documentation | FNH headers, JSDoc, package READMEs, Source Structure | Claude Sonnet 4.6 | Planning |
+| **Tuner** | 4b — Configuration | AGENTS.md, `.antigravityignore`, package.json, CI scripts | Claude Opus 4.6 | Planning |
+| **Inspector** | 5 — Validation | Scoring, health checks, before/after comparison, sign-off | Gemini 3.1 Pro (High) | Planning |
+
+```bash
+# Load a role into the current agent
+npx @ivannikov-pro/ai-context-surgeon@latest role scout
+
+# Full pipeline delegation
+npx @ivannikov-pro/ai-context-surgeon@latest role scout    # → reconnaissance
+npx @ivannikov-pro/ai-context-surgeon@latest role architect  # → plan
+npx @ivannikov-pro/ai-context-surgeon@latest role surgeon    # → execute
+npx @ivannikov-pro/ai-context-surgeon@latest role librarian  # → document
+npx @ivannikov-pro/ai-context-surgeon@latest role tuner      # → configure
+npx @ivannikov-pro/ai-context-surgeon@latest role inspector  # → validate
+```
+
+---
+
+## 🔧 Analysis Tools
+
+All 16 shell scripts in `tools/` plus one Node.js enrichment tool:
+
+| Tool | CLI Command | Description |
+| --- | --- | --- |
+| `scan-fnh.sh` | `radar` | Extract FNH headers from all files — semantic repo map |
+| `detect-god-files.sh` | `godfiles` | Flag files exceeding LOC thresholds (default >300) |
+| `detect-circular-deps.sh` | `circular` | Find circular import chains between packages |
+| `validate-context-weight.sh` | `context-weight` | Compute cognitive load (LOC + Fan-out × 20 formula) |
+| `generate-source-map.sh` | `sourcemaps` | Build Source Structure block for README |
+| `analyze-structure.sh` | — | Full monorepo structure metrics and overview |
+| `analyze-package-json.sh` | — | Rate package.json AI-readiness (Tier 1–4 scoring) |
+| `audit-jsdoc.sh` | — | Analyze JSDoc coverage and quality |
+| `check-fnh-freshness.sh` | — | Warn when source changed but FNH header wasn't updated |
+| `lint-imports.sh` | — | Detect cross-package boundary violations |
+| `measure-context-cost.sh` | — | Estimate AI agent context cost for a package |
+| `generate-jsdoc-headers.sh` | — | Add JSDoc navigation headers to source files |
+| `enforce-god-files.sh` | — | CI gate — fail build if files exceed line thresholds |
+| `validate-context-hygiene.sh` | — | CI gate — ensure all packages have README and ignores |
+| `validate-naming.sh` | — | Check kebab-case and naming conventions |
+| `enrich-package-json.js` | — | Lean/Enrich workflow — inject publish metadata before `npm publish` |
+
+---
+
+## 🔄 Full-Pipeline Workflow Summary
+
+| Phase | Role | Checklist | Tools Used | Output |
+| --- | --- | --- | --- | --- |
+| 1 — Analysis | Scout | `checklist 1` | `radar`, `godfiles`, `context-weight`, `circular` | Telemetry report |
+| 2 — Planning | Architect | `checklist 2` | `analyze-structure.sh`, `analyze-package-json.sh` | Refactoring plan |
+| 3 — Restructuring | Surgeon | `checklist 3` | `lint-imports.sh`, `check-fnh-freshness.sh` | Split files, fixed imports |
+| 4a — Documentation | Librarian | `checklist 4` | `audit-jsdoc.sh`, `generate-jsdoc-headers.sh` | FNH headers, JSDoc, READMEs |
+| 4b — Configuration | Tuner | `checklist 4` | `validate-naming.sh`, `validate-context-hygiene.sh` | AGENTS.md, CI scripts |
+| 5 — Validation | Inspector | `checklist 5` | `radar`, `context-weight`, `enforce-god-files.sh` | Score report, sign-off |
+
+Invoke the full pipeline via workflow:
+```bash
+# Analyzes a target repo (requires target path argument)
+npx @ivannikov-pro/ai-context-surgeon@latest # → interactive menu
+```
+
+Or use pre-built agent workflows (defined in `.agents/workflows/`):
+- `/analyze-repo` — Quick analysis using Scout + tools
+- `/full-pipeline` — Complete 5-phase cascade
+- `/self-check` — Validate ai-context-surgeon's own integrity
+
+---
+
+## 📖 Strategy Docs
+
+All accessible via `strategy <key>` — read on-demand, no install:
+
+| Key | Document | Size | Description |
+| --- | --- | --- | --- |
+| `fnh` | File Navigation Headers | ~560 lines | Universal header format for every file type |
+| `monorepo` | Monorepo Strategy | ~700 lines | Architectural patterns and package boundaries |
+| `jsdoc` | JSDoc Guide | ~600 lines | Token-efficient annotation standards |
+| `package-json` | package.json Guide | ~540 lines | Tier 1–4 field priority, Lean+Enrich workflow |
+| `context-exclusion` | Context Exclusion | ~200 lines | .antigravityignore patterns and philosophy |
+| `bash` | Bash Guide | ~180 lines | Writing POSIX scripts for AI agents |
+| `context-weight` | Context Weight Theory | ~120 lines | LOC + Fan-out cognitive load formula |
+
+---
+
+## 🧩 Skills
+
+Reusable agent procedures — a skill is a self-contained, step-by-step instruction set:
+
+| Key | Name | Description |
+| --- | --- | --- |
+| `annotate-jsdoc` | Annotate JSDoc | Reusable JSDoc/FNH injection procedure |
+| `prompt-engineering` | Prompt Engineering | Prompt analysis, amplification, and extraction |
+
+```bash
+npx @ivannikov-pro/ai-context-surgeon@latest skill annotate-jsdoc
+```
+
+---
+
+## 📝 Templates
+
+File seeds for new projects — all use `{{UPPER_SNAKE_CASE}}` placeholders:
+
+| Key | Template | Description |
+| --- | --- | --- |
+| `agents` | `AGENTS.md.template` | Agent rules with Navigation Rules, FNH, ai-context-surgeon Quick Reference |
+| `readme` | `package-readme.template` | Package README with Source Structure and Scripts |
+| `package-json` | `package-json-ideal.template` | Lean package.json (Tier 1 order, ≤30 lines) |
+| `workflow` | `workflow.template` | Executable workflow with `// turbo` annotations |
+| `skill` | `skill.template` | Skill definition with When/When-Not/Steps/Verify |
+| `knowledge` | `knowledge-item.template` | Knowledge item (metadata.json + artifacts/) |
+| `publish-meta` | `publish-meta.template` | Publish metadata for Lean+Enrich workflow |
+| `antigravityignore` | `antigravityignore.template` | Context exclusion rules |
+| `cursorrules` | `cursorrules.template` | Cursor / Windsurf IDE agent rules |
+
+```bash
+npx @ivannikov-pro/ai-context-surgeon@latest template agents
+npx @ivannikov-pro/ai-context-surgeon@latest template agents --output AGENTS.md
+```
+
+---
+
+## 🧠 Knowledge Items
+
+Pre-loaded reference knowledge for agents:
+
+| Key | Name | Description |
+| --- | --- | --- |
+| `agent-context` | Agent Context System | How Knowledge/Skills/Workflows work in AI agents |
+| `vulnerabilities` | Agent Vulnerabilities | AI agent vulnerability patterns and bypass techniques |
+| `power-words` | Power Words Dictionary | Enforcement directive vocabulary for AI prompts |
+
+```bash
+npx @ivannikov-pro/ai-context-surgeon@latest knowledge agent-context
+```
+
+---
+
+## 📂 Source Structure
+
+See [STRUCTURE.md](STRUCTURE.md) for the complete verbose file and directory map.
+
+---
+
+## 🛡️ CI/CD Integration
+
+After `init`, inject these gates into your CI pipeline:
+
+```bash
+npm run check:hygiene     # FNH radar scan — verifies all files have headers
+npm run check:god-files   # God file detection — fails if any file exceeds 300 LOC
+```
+
+Or run tools directly against any target repo:
+```bash
+npx @ivannikov-pro/ai-context-surgeon@latest radar /path/to/repo
+npx @ivannikov-pro/ai-context-surgeon@latest godfiles /path/to/repo
+```
+
+---
+
+_ai-context-surgeon | [MIT](LICENSE) | [npm](https://www.npmjs.com/package/@ivannikov-pro/ai-context-surgeon) | [GitHub](https://github.com/ivannikov-pro/ai-context-surgeon)_

package/bin/catalog.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/** Category: Registry — Central catalog of all ai-context-surgeon content | EXPORTS: CATALOG, getContent, listCategory, listAll | DEPS: fs, path */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, "..");
+
+/**
+ * Central catalog — maps human-friendly keys to files within the package.
+ * This is the single source of truth for all content.
+ */
+export const CATALOG = {
+  tools: {
+    radar: { name: "Radar Scan", description: "Semantic FNH map of any repository", command: "radar" },
+    godfiles: { name: "God Files", description: "Find files exceeding LOC thresholds", command: "godfiles" },
+    circular: { name: "Circular Deps", description: "Detect circular dependencies", command: "circular" },
+    "context-weight": { name: "Context Weight", description: "Identify files with high cognitive load", command: "context-weight" },
+    sourcemaps: { name: "Source Maps", description: "Generate AI-friendly structure trees", command: "sourcemaps" },
+  },
+
+  roles: {
+    scout: { name: "Scout", description: "Phase 1: Context reconnaissance and telemetry gathering", file: "roles/scout.md" },
+    architect: { name: "Architect", description: "Phase 2: Design and strategic planning", file: "roles/architect.md" },
+    surgeon: { name: "Surgeon", description: "Phase 3: Surgical code and structural modifications", file: "roles/surgeon.md" },
+    librarian: { name: "Librarian", description: "Phase 4a: Update docstrings, FNH, and READMEs", file: "roles/librarian.md" },
+    tuner: { name: "Tuner", description: "Phase 4b: Adjust config files, rules, and rulesets", file: "roles/tuner.md" },
+    inspector: { name: "Inspector", description: "Phase 5: Pipeline validation and health checks", file: "roles/inspector.md" },
+  },
+
+  strategies: {
+    fnh: { name: "File Navigation Header", description: "Universal header format for every file", file: "strategy/file-navigation-header.md" },
+    monorepo: { name: "Monorepo Strategy", description: "Architectural patterns and package boundaries", file: "strategy/monorepo_strategy.md" },
+    jsdoc: { name: "JSDoc Guide", description: "Token-efficient annotation standards", file: "strategy/jsdoc-guide.md" },
+    "package-json": { name: "package.json Guide", description: "Tier system for lean manifests", file: "strategy/package-json-guide.md" },
+    "context-exclusion": { name: "Context Exclusion", description: ".antigravityignore patterns", file: "strategy/context-exclusion.md" },
+    bash: { name: "Bash Guide", description: "Writing POSIX scripts for AI agents", file: "strategy/bash-guide.md" },
+    "context-weight": { name: "Context Weight Theory", description: "LOC + Fan-out cognitive load formula", file: "strategy/context-weight-theory.md" },
+  },
+
+  skills: {
+    "annotate-jsdoc": { name: "Annotate JSDoc", description: "Reusable JSDoc/FNH injection procedure", file: "skills/annotate-jsdoc/SKILL.md" },
+    "prompt-engineering": { name: "Prompt Engineering", description: "Prompt analysis, amplification, extraction", file: "skills/prompt-engineering/SKILL.md" },
+  },
+
+  templates: {
+    agents: { name: "AGENTS.md", description: "Agent rules template", file: "templates/AGENTS.md.template" },
+    readme: { name: "Package README", description: "Package README template", file: "templates/package-readme.template" },
+    "package-json": { name: "package.json", description: "Ideal package.json template", file: "templates/package-json-ideal.template" },
+    workflow: { name: "Workflow", description: "Workflow template", file: "templates/workflow.template" },
+    skill: { name: "Skill", description: "Skill template", file: "templates/skill.template" },
+    knowledge: { name: "Knowledge Item", description: "Knowledge item template", file: "templates/knowledge-item.template" },
+    "publish-meta": { name: "Publish Meta", description: "Publish metadata template", file: "templates/publish-meta.template" },
+    antigravityignore: { name: "Antigravityignore", description: "Context exclusion template", file: "templates/antigravityignore.template" },
+    cursorrules: { name: "Cursor/Windsurf Rules", description: "IDE agent rules template", file: "templates/cursorrules.template" },
+  },
+
+  checklists: {
+    1: { name: "Phase 1: Analysis", description: "Tasks for Scout role", file: "checklists/phase-1-analysis.md" },
+    2: { name: "Phase 2: Planning", description: "Tasks for Architect role", file: "checklists/phase-2-planning.md" },
+    3: { name: "Phase 3: Restructuring", description: "Tasks for Surgeon role", file: "checklists/phase-3-restructuring.md" },
+    4: { name: "Phase 4: Documentation", description: "Tasks for Librarian/Tuner roles", file: "checklists/phase-4-documentation.md" },
+    5: { name: "Phase 5: Validation", description: "Tasks for Inspector role", file: "checklists/phase-5-validation.md" },
+  },
+
+  knowledge: {
+    "agent-context": { name: "Agent Context System", description: "How Knowledge/Skills/Workflows work in AI agents", dir: "knowledge/agent-context-system" },
+    vulnerabilities: { name: "Agent Vulnerabilities", description: "AI agent vulnerability patterns", dir: "knowledge/agent-vulnerabilities" },
+    "power-words": { name: "Power Words Dictionary", description: "Enforcement directive vocabulary", dir: "knowledge/power-words-dictionary" },
+  },
+};
+
+/**
+ * Read content of a catalog item by category and key.
+ * For knowledge items (which are directories), reads all artifacts.
+ * @param {string} category
+ * @param {string} key
+ * @returns {string|null} File content or null if not found
+ */
+export function getContent(category, key) {
+  const cat = CATALOG[category];
+  if (!cat) return null;
+
+  const item = cat[key];
+  if (!item) return null;
+
+  // Tools don't have file content — they are commands
+  if (category === "tools") return null;
+
+  // Knowledge items are directories with multiple artifacts
+  if (item.dir) {
+    const dirPath = path.join(ROOT, item.dir);
+    if (!fs.existsSync(dirPath)) return null;
+
+    let output = "";
+
+    // Read metadata.json
+    const metaPath = path.join(dirPath, "metadata.json");
+    if (fs.existsSync(metaPath)) {
+      const meta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
+      output += `# ${meta.title}\n\n> ${meta.summary}\n\n---\n\n`;
+    }
+
+    // Read all artifacts
+    const artifactsDir = path.join(dirPath, "artifacts");
+    if (fs.existsSync(artifactsDir)) {
+      const files = fs.readdirSync(artifactsDir).filter((f) => !f.startsWith("."));
+      for (const file of files) {
+        const content = fs.readFileSync(path.join(artifactsDir, file), "utf8");
+        output += `## ${file}\n\n${content}\n\n---\n\n`;
+      }
+    }
+
+    return output || null;
+  }
+
+  // Regular file items
+  const filePath = path.join(ROOT, item.file);
+  if (!fs.existsSync(filePath)) return null;
+
+  return fs.readFileSync(filePath, "utf8");
+}
+
+/**
+ * List all items in a category.
+ * @param {string} category
+ * @returns {Array<{key: string, name: string, description: string}>}
+ */
+export function listCategory(category) {
+  const cat = CATALOG[category];
+  if (!cat) return [];
+
+  return Object.entries(cat).map(([key, val]) => ({
+    key: String(key),
+    name: val.name,
+    description: val.description,
+  }));
+}
+
+/**
+ * List all categories and their items.
+ * @returns {Object<string, Array>}
+ */
+export function listAll() {
+  const result = {};
+  for (const category of Object.keys(CATALOG)) {
+    result[category] = listCategory(category);
+  }
+  return result;
+}