---
name: apt:docs
description: "Generate or update documentation verified against the actual codebase"
apt-skill-version: {{APT_VERSION}}
stage: ops
intent: capture
when_to_use: "The user wants to generate, update, or verify documentation against the actual codebase (README, API, architecture, changelog, etc.)."
user_invocable: true
internal: false
spawns_agent: false
agent_name: null
task_context: create-new
default_track: STANDARD
default_execution_mode: auto
execution_modes:
  - auto
  - step
allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
argument-hint: "apt:docs [readme|api|architecture|changelog|contributing]"
gates: []
---
<objective>
Generate, update, or audit project documentation. Verifies all claims against the actual codebase — no stale docs. Supports multiple doc types: readme, api, architecture, changelog, contributing.
</objective>

<your_environment>
- **Working directory:** The project root (where you were invoked)
- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
- **Constitution:** Read `AGENTS.md` in the project root if it exists
- **Workflow:** Follow `packages/framework/workflows/docs.md` for the full process
</your_environment>

<state_files>
## State Files

**Reads:**
- `AGENTS.md` — Project constitution
- Existing documentation files (README.md, docs/, etc.)
- Codebase source files (for verification)
- `package.json` files (for API surface, scripts, dependencies)
- `.aperant/features/` (feature registry, if exists)

**Writes:**
- Documentation files as specified by the doc type
- `.aperant/docs-audit.json` — Audit results (if running in verify-only mode)
</state_files>

<process>

Follow the workflow at `packages/framework/workflows/docs.md`.

## Quick Reference

### Usage
```
/apt:docs {type} [flags]
```

### Doc Types
| Type | Output | Description |
|------|--------|-------------|
| `readme` | `README.md` | Project README with setup, usage, architecture overview |
| `api` | `docs/api/` | API documentation from source code |
| `architecture` | `docs/ARCHITECTURE.md` | System architecture, module boundaries, data flow |
| `changelog` | `CHANGELOG.md` | Changelog from git history since last tag |
| `contributing` | `CONTRIBUTING.md` | Contributor guide with setup, conventions, PR process |

### Flags
- `--verify-only` — Audit existing docs without making changes
- `--scope <path>` — Limit to a specific package or directory
- `--force` — Overwrite existing docs (default: merge/update)

### Examples
```
/apt:docs readme                    # Generate/update README.md
/apt:docs api --scope packages/ui   # API docs for the UI package
/apt:docs architecture              # Architecture document
/apt:docs changelog                 # Changelog from recent git history
/apt:docs readme --verify-only      # Audit README for stale claims
```

</process>
