Docs

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.

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:

markdownCopy code
# [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:

markdownCopy code
# Architecture

## Overview
[System diagram in text/mermaid — components and data flow]

> The ARCHITECTURE overview may call `rune:diagram` for a designed system figure (type `architecture`) instead of raw Mermaid — `suggested_next: diagram`.

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

Step 3 — Generate Changelog Entry

Delegate to rune:git changelog to produce a changelog entry from commits since last docs update.

Step 4 — Cross-Doc Consistency Pass

Cross-document consistency prevents the second-most-common docs problem: docs that exist but contradict each other.

After updating any doc, verify consistency across all project documentation:

Copy code
Cross-Doc Consistency:
- [x] README.md ↔ CLAUDE.md: versions match, commands match
- [x] README.md ↔ docs/index.html: stats match, features match
- [ ] README.md says "62 skills" but CLAUDE.md says "59" → FIX CLAUDE.md

Fix inconsistencies immediately — don't just report them. Update the stale doc to match the source of truth (usually the code or the most recently updated doc).

Step 5 — Report

Show user: what was updated, what was added, what was flagged for review. Include Cross-Doc Consistency results.

API Mode

Step 1 — Detect API Framework

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:

markdownCopy code
# 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

Copy code

#### 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]

Copy code

### 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]

Copy code

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

## Returns

| Artifact | Format | Location |
|----------|--------|----------|
| README.md | Markdown | project root |
| ARCHITECTURE.md | Markdown | project root (if 10+ files) |
| API reference | Markdown | `docs/API.md` |
| Changelog entry | Markdown (Keep a Changelog) | `CHANGELOG.md` |
| Docs update report | Markdown | inline (chat output) |

**Scope guardrail:** Documents only what exists in the codebase — never invents features, endpoints, or APIs.

## 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 |
| Cross-document inconsistency (README says X, CLAUDE.md says Y) | HIGH | Step 7: Cross-Doc Consistency Pass — verify stats, versions, and feature lists match across all docs |
| Updating one doc but not others (stats drift) | HIGH | After any doc update, sweep all related docs for stale stats — especially README ↔ CLAUDE.md ↔ landing page |

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