npm - @rune-kit/rune - Versions diffs - 2.1.1 - Mend

@rune-kit/rune 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (155) hide show

package/LICENSE +21 -0
package/README.md +357 -0
package/agents/.gitkeep +0 -0
package/agents/architect.md +29 -0
package/agents/asset-creator.md +11 -0
package/agents/audit.md +11 -0
package/agents/autopsy.md +11 -0
package/agents/brainstorm.md +11 -0
package/agents/browser-pilot.md +11 -0
package/agents/coder.md +29 -0
package/agents/completion-gate.md +11 -0
package/agents/constraint-check.md +11 -0
package/agents/context-engine.md +11 -0
package/agents/cook.md +11 -0
package/agents/db.md +11 -0
package/agents/debug.md +11 -0
package/agents/dependency-doctor.md +11 -0
package/agents/deploy.md +11 -0
package/agents/design.md +11 -0
package/agents/docs-seeker.md +11 -0
package/agents/fix.md +11 -0
package/agents/hallucination-guard.md +11 -0
package/agents/incident.md +11 -0
package/agents/integrity-check.md +11 -0
package/agents/journal.md +11 -0
package/agents/launch.md +11 -0
package/agents/logic-guardian.md +11 -0
package/agents/marketing.md +11 -0
package/agents/onboard.md +11 -0
package/agents/perf.md +11 -0
package/agents/plan.md +11 -0
package/agents/preflight.md +11 -0
package/agents/problem-solver.md +11 -0
package/agents/rescue.md +11 -0
package/agents/research.md +11 -0
package/agents/researcher.md +29 -0
package/agents/review-intake.md +11 -0
package/agents/review.md +11 -0
package/agents/reviewer.md +28 -0
package/agents/safeguard.md +11 -0
package/agents/sast.md +11 -0
package/agents/scanner.md +28 -0
package/agents/scope-guard.md +11 -0
package/agents/scout.md +11 -0
package/agents/sentinel.md +11 -0
package/agents/sequential-thinking.md +11 -0
package/agents/session-bridge.md +11 -0
package/agents/skill-forge.md +11 -0
package/agents/skill-router.md +11 -0
package/agents/surgeon.md +11 -0
package/agents/team.md +11 -0
package/agents/test.md +11 -0
package/agents/trend-scout.md +11 -0
package/agents/verification.md +11 -0
package/agents/video-creator.md +11 -0
package/agents/watchdog.md +11 -0
package/agents/worktree.md +11 -0
package/commands/.gitkeep +0 -0
package/commands/rune.md +168 -0
package/compiler/__tests__/openclaw-adapter.test.js +140 -0
package/compiler/__tests__/parser.test.js +55 -0
package/compiler/adapters/antigravity.js +59 -0
package/compiler/adapters/claude.js +37 -0
package/compiler/adapters/cursor.js +67 -0
package/compiler/adapters/generic.js +60 -0
package/compiler/adapters/index.js +45 -0
package/compiler/adapters/openclaw.js +150 -0
package/compiler/adapters/windsurf.js +60 -0
package/compiler/bin/rune.js +288 -0
package/compiler/doctor.js +153 -0
package/compiler/emitter.js +240 -0
package/compiler/parser.js +208 -0
package/compiler/transformer.js +69 -0
package/compiler/transforms/branding.js +27 -0
package/compiler/transforms/cross-references.js +29 -0
package/compiler/transforms/frontmatter.js +38 -0
package/compiler/transforms/hooks.js +68 -0
package/compiler/transforms/subagents.js +36 -0
package/compiler/transforms/tool-names.js +60 -0
package/contexts/dev.md +34 -0
package/contexts/research.md +43 -0
package/contexts/review.md +55 -0
package/extensions/ai-ml/PACK.md +517 -0
package/extensions/analytics/PACK.md +557 -0
package/extensions/backend/PACK.md +678 -0
package/extensions/chrome-ext/PACK.md +995 -0
package/extensions/content/PACK.md +381 -0
package/extensions/devops/PACK.md +520 -0
package/extensions/ecommerce/PACK.md +280 -0
package/extensions/gamedev/PACK.md +393 -0
package/extensions/mobile/PACK.md +273 -0
package/extensions/saas/PACK.md +805 -0
package/extensions/security/PACK.md +536 -0
package/extensions/trading/PACK.md +597 -0
package/extensions/ui/PACK.md +947 -0
package/package.json +47 -0
package/skills/.gitkeep +0 -0
package/skills/adversary/SKILL.md +271 -0
package/skills/asset-creator/SKILL.md +157 -0
package/skills/audit/SKILL.md +466 -0
package/skills/autopsy/SKILL.md +200 -0
package/skills/ba/SKILL.md +279 -0
package/skills/brainstorm/SKILL.md +266 -0
package/skills/browser-pilot/SKILL.md +168 -0
package/skills/completion-gate/SKILL.md +151 -0
package/skills/constraint-check/SKILL.md +165 -0
package/skills/context-engine/SKILL.md +176 -0
package/skills/cook/SKILL.md +636 -0
package/skills/db/SKILL.md +256 -0
package/skills/debug/SKILL.md +240 -0
package/skills/dependency-doctor/SKILL.md +235 -0
package/skills/deploy/SKILL.md +174 -0
package/skills/design/DESIGN-REFERENCE.md +365 -0
package/skills/design/SKILL.md +462 -0
package/skills/doc-processor/SKILL.md +254 -0
package/skills/docs/SKILL.md +336 -0
package/skills/docs-seeker/SKILL.md +166 -0
package/skills/fix/SKILL.md +192 -0
package/skills/git/SKILL.md +285 -0
package/skills/hallucination-guard/SKILL.md +204 -0
package/skills/incident/SKILL.md +241 -0
package/skills/integrity-check/SKILL.md +169 -0
package/skills/journal/SKILL.md +190 -0
package/skills/launch/SKILL.md +330 -0
package/skills/logic-guardian/SKILL.md +240 -0
package/skills/marketing/SKILL.md +229 -0
package/skills/mcp-builder/SKILL.md +311 -0
package/skills/onboard/SKILL.md +298 -0
package/skills/perf/SKILL.md +297 -0
package/skills/plan/SKILL.md +520 -0
package/skills/preflight/SKILL.md +231 -0
package/skills/problem-solver/SKILL.md +284 -0
package/skills/rescue/SKILL.md +434 -0
package/skills/research/SKILL.md +122 -0
package/skills/review/SKILL.md +354 -0
package/skills/review-intake/SKILL.md +222 -0
package/skills/safeguard/SKILL.md +188 -0
package/skills/sast/SKILL.md +190 -0
package/skills/scaffold/SKILL.md +276 -0
package/skills/scope-guard/SKILL.md +150 -0
package/skills/scout/SKILL.md +232 -0
package/skills/sentinel/SKILL.md +320 -0
package/skills/sentinel-env/SKILL.md +226 -0
package/skills/sequential-thinking/SKILL.md +234 -0
package/skills/session-bridge/SKILL.md +287 -0
package/skills/skill-forge/SKILL.md +317 -0
package/skills/skill-router/SKILL.md +267 -0
package/skills/surgeon/SKILL.md +203 -0
package/skills/team/SKILL.md +397 -0
package/skills/test/SKILL.md +271 -0
package/skills/trend-scout/SKILL.md +145 -0
package/skills/verification/SKILL.md +201 -0
package/skills/video-creator/SKILL.md +201 -0
package/skills/watchdog/SKILL.md +166 -0
package/skills/worktree/SKILL.md +140 -0

package/skills/doc-processor/SKILL.md ADDED Viewed

@@ -0,0 +1,254 @@
+---
+name: doc-processor
+description: Generate and parse office documents — PDF, DOCX, XLSX, PPTX, CSV. Pure format utility for creating reports, exporting data, and processing uploaded documents.
+metadata:
+  author: runedev
+  version: "0.2.0"
+  layer: L3
+  model: sonnet
+  group: utility
+  tools: "Read, Write, Edit, Bash, Glob, Grep"
+---
+# doc-processor
+## Purpose
+Document format utility. Generates and parses office documents (PDF, DOCX, XLSX, PPTX, CSV). Pure utility — no business logic, just format handling. Other skills call doc-processor when they need to produce or consume structured documents.
+## Triggers
+- Called by `docs` when export to PDF/DOCX is requested
+- Called by `marketing` for generating PDF reports, PPTX presentations
+- Called by Rune Pro packs for business document generation
+- `/rune doc-processor generate <format> <source>` — manual document generation
+- `/rune doc-processor parse <file>` — manual document parsing
+## Calls (outbound)
+None — pure L3 utility. Receives content, produces formatted output.
+## Called By (inbound)
+- `docs` (L2): export documentation to PDF/DOCX
+- `marketing` (L2): generate PDF reports, PPTX pitch decks
+- Rune Pro packs: business document generation (invoices, proposals, reports)
+- User: `/rune doc-processor` direct invocation
+## Format Reference
+### Supported Formats
+| Format | Generate | Parse | Node.js Library | Python Library |
+|--------|----------|-------|-----------------|----------------|
+| PDF | Yes | Yes (via Read tool) | jsPDF, Puppeteer (HTML→PDF) | reportlab, weasyprint |
+| DOCX | Yes | Yes | docx (officegen) | python-docx |
+| XLSX | Yes | Yes | ExcelJS | openpyxl |
+| PPTX | Yes | Yes | pptxgenjs | python-pptx |
+| CSV | Yes | Yes | Built-in (fs + string ops) | Built-in (csv module) |
+| HTML | Yes | Yes | Built-in | Built-in |
+### Library Selection
+Detect project language from context:
+- If Node.js project → use Node.js libraries
+- If Python project → use Python libraries
+- If unclear → default to Node.js (wider ecosystem)
+- For HTML→PDF → prefer Puppeteer (best fidelity) or weasyprint (Python)
+## Executable Steps
+### Generate Mode
+#### Step 1 — Determine Format and Template
+Identify:
+- Target format (PDF, DOCX, XLSX, PPTX, CSV)
+- Content source (markdown, data object, template + data)
+- Styling requirements (brand colors, fonts, layout)
+- Output path
+#### Step 2 — Select Generation Strategy
+| Source | Target | Strategy |
+|--------|--------|----------|
+| Markdown → PDF | HTML intermediate | Render MD → HTML → Puppeteer → PDF |
+| Markdown → DOCX | Direct conversion | Parse MD → docx library → DOCX |
+| Data → XLSX | Direct write | Map data to sheets/cells → ExcelJS |
+| Slides → PPTX | Template + data | Build slides from content → pptxgenjs |
+| Data → CSV | Direct write | Serialize rows → CSV string → file |
+| Any → HTML | Direct render | Template engine → HTML file |
+#### Step 3 — Generate Code
+Produce the generation script:
+**PDF from Markdown:**
+```javascript
+// Strategy: Markdown → HTML → Puppeteer → PDF
+const puppeteer = require('puppeteer');
+const { marked } = require('marked');
+async function generatePDF(markdownContent, outputPath, options = {}) {
+  const html = `
+    <!DOCTYPE html>
+    <html>
+    <head><style>${options.css || defaultCSS}</style></head>
+    <body>${marked(markdownContent)}</body>
+    </html>
+  `;
+  const browser = await puppeteer.launch();
+  const page = await browser.newPage();
+  await page.setContent(html, { waitUntil: 'networkidle0' });
+  await page.pdf({ path: outputPath, format: 'A4', margin: { top: '1in', bottom: '1in', left: '1in', right: '1in' } });
+  await browser.close();
+}
+```
+**XLSX from Data:**
+```javascript
+const ExcelJS = require('exceljs');
+async function generateXLSX(data, outputPath, options = {}) {
+  const workbook = new ExcelJS.Workbook();
+  const sheet = workbook.addWorksheet(options.sheetName || 'Sheet1');
+  if (data.length > 0) {
+    sheet.columns = Object.keys(data[0]).map(key => ({ header: key, key, width: 20 }));
+    data.forEach(row => sheet.addRow(row));
+    // Style header row
+    sheet.getRow(1).font = { bold: true };
+    sheet.getRow(1).fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: 'FFE0E0E0' } };
+  }
+  await workbook.xlsx.writeFile(outputPath);
+}
+```
+**PPTX from Slides:**
+```javascript
+const PptxGenJS = require('pptxgenjs');
+function generatePPTX(slides, outputPath, options = {}) {
+  const pptx = new PptxGenJS();
+  pptx.author = options.author || 'Generated by Rune';
+  slides.forEach(slide => {
+    const s = pptx.addSlide();
+    if (slide.title) s.addText(slide.title, { x: 0.5, y: 0.5, fontSize: 28, bold: true });
+    if (slide.body) s.addText(slide.body, { x: 0.5, y: 1.5, fontSize: 16 });
+    if (slide.bullets) s.addText(slide.bullets.map(b => ({ text: b, options: { bullet: true } })), { x: 0.5, y: 1.5, fontSize: 16 });
+  });
+  return pptx.writeFile({ fileName: outputPath });
+}
+```
+#### Step 4 — Execute and Verify
+Run the generation script. Verify:
+- Output file exists and is non-empty
+- File can be opened (basic format validation)
+- Content matches expected structure
+### Parse Mode
+#### Step 1 — Detect Format
+Identify file format from extension and MIME type.
+#### Step 2 — Extract Content
+| Format | Extraction Strategy |
+|--------|-------------------|
+| PDF | Use Read tool (Claude can read PDFs natively) |
+| DOCX | docx library → extract text, tables, images |
+| XLSX | ExcelJS → extract sheets, rows, formulas |
+| PPTX | pptxgenjs → extract slides, text, notes |
+| CSV | Built-in parser → structured data |
+#### Step 3 — Structure Output
+Return parsed content as structured data:
+```json
+{
+  "format": "xlsx",
+  "sheets": [
+    {
+      "name": "Sheet1",
+      "headers": ["Name", "Email", "Role"],
+      "rows": [["Alice", "alice@co.com", "Engineer"], ...],
+      "rowCount": 100
+    }
+  ]
+}
+```
+## Output Format
+### Generate Mode Output
+- Generated document file at specified output path
+- Verification report: file exists, non-empty, format valid
+```
+Document Generated:
+- Format: [PDF/DOCX/XLSX/PPTX/CSV]
+- Path: [output file path]
+- Size: [file size]
+- Strategy: [e.g., Markdown → HTML → Puppeteer → PDF]
+- Status: verified ✓
+```
+### Parse Mode Output
+Structured JSON returned to calling skill:
+```json
+{
+  "format": "xlsx",
+  "metadata": { "author": "...", "created": "..." },
+  "content": {
+    "sheets": [
+      {
+        "name": "Sheet1",
+        "headers": ["Col1", "Col2"],
+        "rows": [["val1", "val2"]],
+        "rowCount": 100
+      }
+    ]
+  }
+}
+```
+Format-specific fields: `sheets` (XLSX), `pages` (PDF/DOCX), `slides` (PPTX), `rows` (CSV).
+## Constraints
+1. MUST verify output file exists and is non-empty after generation
+2. MUST handle missing libraries gracefully — suggest `npm install` / `pip install` if not found
+3. MUST NOT embed secrets or sensitive data in generated documents
+4. MUST preserve formatting fidelity — generated docs should look professional
+5. Parse mode MUST handle malformed files gracefully — report errors, don't crash
+6. MUST use appropriate library for each format — don't force one library for all formats
+## Sharp Edges
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Library not installed in project | HIGH | Check package.json/requirements.txt, suggest install command |
+| PDF generation fails without headless browser | HIGH | Puppeteer needs chromium — suggest alternative (jsPDF) if unavailable |
+| XLSX with formulas not evaluated | MEDIUM | Use ExcelJS formula support, warn if complex formulas |
+| Large file generation runs out of memory | MEDIUM | Stream large datasets instead of loading all at once |
+| Generated file is empty or corrupt | HIGH | Step 4 verification catches this — retry or report |
+## Done When
+### Generate Mode
+- Target format and source identified
+- Generation strategy selected
+- Code produced and executed
+- Output file verified (exists, non-empty, valid format)
+### Parse Mode
+- File format detected
+- Content extracted to structured data
+- Output returned in consistent JSON format
+## Cost Profile
+~1000-3000 tokens input, ~500-2000 tokens output. Sonnet — document processing requires understanding format libraries and generating correct code, but not deep reasoning.

package/skills/docs/SKILL.md ADDED Viewed

@@ -0,0 +1,336 @@
+---
+name: docs
+description: Auto-generate and maintain project documentation. Creates README, API docs, architecture docs, changelogs, and keeps them in sync with code changes. The "docs are never outdated" skill.
+metadata:
+  author: runedev
+  version: "0.2.0"
+  layer: L2
+  model: sonnet
+  group: delivery
+  tools: "Read, Write, Edit, Glob, Grep"
+---
+# docs
+## Purpose
+Documentation lifecycle manager. Generates initial project documentation, keeps docs in sync with code changes, produces API references, and auto-generates changelogs. Solves the #1 documentation problem: docs that exist but are outdated.
+<HARD-GATE>
+Docs MUST be generated from actual code, not invented. Every statement in generated docs must be traceable to a specific file, function, or configuration in the codebase. If code doesn't exist yet, docs describe the PLAN, not the implementation.
+</HARD-GATE>
+## Triggers
+- Called by `scaffold` Phase 7 for initial documentation generation
+- Called by `cook` post-Phase 7 to update docs after feature implementation
+- Called by `launch` pre-deploy to ensure docs are current
+- `/rune docs init` — first-time documentation generation
+- `/rune docs update` — sync docs with recent code changes
+- `/rune docs api` — generate API documentation
+- `/rune docs changelog` — auto-generate changelog from git history
+## Calls (outbound)
+- `scout` (L2): scan codebase for documentation targets (routes, exports, components, configs)
+- `doc-processor` (L3): generate PDF/DOCX exports if requested
+- `git` (L3): read commit history for changelog generation
+## Called By (inbound)
+- `scaffold` (L1): Phase 7 — generate initial docs for new project
+- `cook` (L1): post-implementation — update docs for changed modules
+- `launch` (L1): pre-deploy — verify docs are current
+- `mcp-builder` (L2): generate MCP server documentation
+- User: `/rune docs` direct invocation
+## Modes
+### Init Mode — `/rune docs init`
+First-time documentation generation for a project.
+### Update Mode — `/rune docs update`
+Incremental sync — update only docs affected by recent code changes.
+### API Mode — `/rune docs api`
+Generate or update API documentation specifically.
+### Changelog Mode — `/rune docs changelog`
+Auto-generate changelog from git commit history.
+## Executable Steps
+### Init Mode
+#### Step 1 — Scan Codebase
+Invoke `rune:scout` to extract:
+- Project name, description, tech stack
+- Directory structure and key files
+- Entry points (main, index, app)
+- Public API surface (exports, routes, components)
+- Configuration files (.env.example, config patterns)
+- Existing docs (if any — merge, don't overwrite)
+#### Step 2 — Generate README.md
+Structure:
+```markdown
+# [Project Name]
+[One-line description]
+## Quick Start
+[3-5 commands to get running: install, configure, start]
+## Features
+[Bullet list extracted from code — routes, components, capabilities]
+## Tech Stack
+[Detected from package.json, requirements.txt, Cargo.toml, etc.]
+## Project Structure
+[Key directories with one-line descriptions]
+## Configuration
+[Environment variables from .env.example with descriptions]
+## Development
+[Dev server, test, lint, build commands]
+## API Reference
+[Link to API.md if applicable, or inline summary]
+## License
+[Detected from LICENSE file or package.json]
+```
+#### Step 3 — Generate ARCHITECTURE.md (if project has 10+ files)
+Structure:
+```markdown
+# Architecture
+## Overview
+[System diagram in text/mermaid — components and data flow]
+## Key Decisions
+[Detected patterns: framework choice, state management, DB, auth approach]
+## Module Map
+[Each top-level directory: purpose, key files, dependencies]
+## Data Flow
+[Request lifecycle or data pipeline description]
+```
+#### Step 4 — Generate API.md (if routes/endpoints detected)
+Scan route files and extract:
+- HTTP method + path
+- Request parameters (path, query, body)
+- Response shape
+- Authentication requirements
+- Error responses
+Format as markdown table or OpenAPI-compatible reference.
+#### Step 5 — Report
+Present generated docs to user with summary:
+- Files generated: [list]
+- Coverage: [what's documented vs what exists]
+- Gaps: [code areas without docs — suggest next steps]
+### Update Mode
+#### Step 1 — Detect Changes
+Read `git diff` since last docs update (tracked via git log on doc files or `.rune/docs-sync.json`).
+Identify:
+- New files/modules → need new doc sections
+- Changed functions/routes → need doc updates
+- Deleted code → need doc removal
+- New configuration → need config doc update
+#### Step 2 — Update Affected Sections
+For each changed area:
+1. Read the changed code
+2. Find corresponding doc section
+3. Update doc to match current code
+4. If doc section doesn't exist → create it
+5. If code was deleted → remove or mark as deprecated in docs
+<HARD-GATE>
+Never silently remove doc content. If code was deleted, mark the doc section as "Removed in [commit]" or ask user before deleting the doc section.
+</HARD-GATE>
+#### Step 3 — Generate Changelog Entry
+Delegate to `rune:git changelog` to produce a changelog entry from commits since last docs update.
+#### Step 4 — Report
+Show user: what was updated, what was added, what was flagged for review.
+### API Mode
+#### Step 1 — Detect API Framework
+| Framework | Route Pattern | File Pattern |
+|-----------|--------------|--------------|
+| Express | `router.get/post/put/delete` | `routes/*.ts`, `*.router.ts` |
+| FastAPI | `@app.get/post/put/delete` | `routers/*.py`, `main.py` |
+| NestJS | `@Get/@Post/@Put/@Delete` | `*.controller.ts` |
+| Next.js App | `export async function GET/POST` | `app/**/route.ts` |
+| Next.js Pages | `export default function handler` | `pages/api/**/*.ts` |
+| SvelteKit | `export function GET/POST` | `src/routes/**/+server.ts` |
+| Hono | `app.get/post/put/delete` | `src/*.ts` |
+#### Step 2 — Extract Endpoints
+For each detected route:
+- Method (GET, POST, PUT, DELETE, PATCH)
+- Path (with parameters highlighted)
+- Request: params, query, body shape (from Zod schemas, TypeScript types, Pydantic models)
+- Response: shape (from return type or response helper)
+- Auth: required? (detect middleware like `authMiddleware`, `@UseGuards`)
+- Description: from JSDoc/docstring if available
+#### Step 3 — Generate API Reference
+Format as markdown:
+```markdown
+# API Reference
+## Authentication
+[Auth mechanism description]
+## Endpoints
+### `POST /api/auth/login`
+**Description**: Authenticate user and return tokens
+**Auth**: None
+**Request Body**:
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| email | string | yes | User email |
+| password | string | yes | User password |
+**Response** (200):
+```json
+{ "token": "string", "refreshToken": "string" }
+```
+**Errors**:
+- 401: Invalid credentials
+- 422: Validation error
+```
+#### Step 4 — Output
+Save to `docs/API.md` or project-specific location. If OpenAPI requested, generate `openapi.yaml`.
+### Changelog Mode
+#### Step 1 — Delegate to Git
+Invoke `rune:git changelog` to group commits by type and format as Keep a Changelog.
+#### Step 2 — Enhance
+Add context to raw changelog:
+- Link PR numbers to actual descriptions
+- Group related changes under feature headers
+- Highlight breaking changes prominently
+#### Step 3 — Output
+Append to or update `CHANGELOG.md`.
+## Output Format
+### Init Mode Output
+Files generated in project root:
+- `README.md` — Quick Start, Features, Tech Stack, Structure, Config, Dev Commands
+- `ARCHITECTURE.md` — Overview diagram, Key Decisions, Module Map, Data Flow (if 10+ files)
+- `docs/API.md` — Endpoint reference with method, path, params, response, auth (if routes detected)
+### Update Mode Output
+Modified doc sections with change summary:
+```
+Docs Update Report:
+- Updated: [list of doc sections modified]
+- Added: [new sections for new code]
+- Flagged: [stale sections referencing deleted code]
+- Changelog: [entry appended to CHANGELOG.md]
+```
+### API Mode Output
+`docs/API.md` — markdown reference per endpoint:
+```
+### `METHOD /path/:param`
+**Description**: [from JSDoc/docstring]
+**Auth**: [required/none]
+**Request**: [params, query, body table]
+**Response**: [shape with status codes]
+**Errors**: [error codes and descriptions]
+```
+### Changelog Mode Output
+`CHANGELOG.md` — Keep a Changelog format grouped by: Added, Fixed, Changed, Removed.
+## Constraints
+1. MUST generate docs from actual code — never invent features or APIs that don't exist
+2. MUST preserve existing docs — update sections, don't overwrite entire files
+3. MUST detect doc staleness — flag sections that reference deleted/changed code
+4. MUST include Quick Start in every README — users need to get running in < 2 minutes
+5. MUST NOT generate docs for code that doesn't exist yet (unless explicitly creating spec docs)
+6. API docs MUST match actual route signatures — wrong API docs are worse than no docs
+## Sharp Edges
+| Failure Mode | Severity | Mitigation |
+|---|---|---|
+| Inventing API endpoints that don't exist | CRITICAL | Constraint 1: scan actual route files, not guess |
+| Overwriting user-written README sections | HIGH | Constraint 2: merge, don't overwrite — detect custom sections |
+| Stale docs after code changes | HIGH | Update mode detects diffs and updates affected sections |
+| API docs with wrong request/response shapes | HIGH | Extract from Zod/Pydantic/TypeScript types, not from memory |
+| Missing Quick Start section | MEDIUM | Constraint 4: every README has Quick Start |
+| Changelog with orphan PR links | LOW | Validate PR numbers exist before linking |
+## Done When
+### Init Mode
+- Codebase scanned with scout
+- README.md generated with Quick Start, Features, Tech Stack, Structure
+- ARCHITECTURE.md generated (if 10+ files)
+- API.md generated (if routes detected)
+- Coverage report presented to user
+### Update Mode
+- Changes since last doc update detected
+- Affected doc sections updated
+- Changelog entry generated
+- Update report presented to user
+### API Mode
+- API framework detected
+- All endpoints extracted with method, path, request, response
+- API reference generated in markdown
+- Saved to docs/API.md
+### Changelog Mode
+- Commits grouped by type
+- Formatted as Keep a Changelog
+- CHANGELOG.md updated
+## Cost Profile
+~2000-5000 tokens input, ~1000-3000 tokens output. Sonnet — documentation requires understanding code patterns but not deep architectural reasoning.