Docs

---
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.3.0"
  layer: L2
  model: sonnet
  group: delivery
  tools: "Read, Write, Edit, Glob, Grep"
  emit: docs.updated
---

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

> 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

<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 — 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:

| Check | Files | What to Compare |
|-------|-------|----------------|
| **Version numbers** | README, CLAUDE.md, package.json, CHANGELOG | Must all match current version |
| **Feature lists** | README, landing page, CLAUDE.md | Same features listed (may differ in detail level) |
| **Stats** | README, CLAUDE.md, landing page, dashboard | Skill count, test count, signal count must match |
| **Commands** | README, CLAUDE.md, docs/ | Same commands with same flags |
| **Tech stack** | README, ARCHITECTURE.md, CLAUDE.md | Consistent framework/library references |

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

| 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

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