<purpose>
Documentation generation and verification workflow. Generates or updates project
documentation verified against the actual codebase. Every claim in the docs must be
traceable to real code — no stale descriptions, no phantom APIs, no outdated setup steps.
</purpose>

<process>

<step name="parse_args" priority="first">
## 1. Parse Arguments

Extract from `$ARGUMENTS`:
- **Doc type:** `readme` | `api` | `architecture` | `changelog` | `contributing`
- **Flags:** `--verify-only`, `--scope <path>`, `--force`

If no doc type is specified, default to `readme`.

Validate the doc type is one of the supported types. If not:
```
Unknown doc type: {type}

Supported types: readme, api, architecture, changelog, contributing

Usage: /apt:docs {type} [--verify-only] [--scope <path>] [--force]
```
Exit.
</step>

<step name="load_context">
## 2. Load Project Context

Read project constitution and metadata:
```bash
cat AGENTS.md 2>/dev/null || cat CLAUDE.md 2>/dev/null || echo "No constitution"
```

Read the root package.json for project name, description, scripts:
```bash
cat package.json 2>/dev/null
```

If `--scope` is set, also read the scoped package.json:
```bash
cat {scope}/package.json 2>/dev/null
```

Read existing documentation (if updating):
- For `readme`: Read existing `README.md`
- For `api`: Read existing `docs/api/` files
- For `architecture`: Read existing `docs/ARCHITECTURE.md`
- For `changelog`: Read existing `CHANGELOG.md`
- For `contributing`: Read existing `CONTRIBUTING.md`

Read feature registry if it exists:
```bash
cat .aperant/features/REGISTRY.md 2>/dev/null
```
</step>

<step name="investigate_codebase">
## 3. Investigate Codebase

Gather facts from the actual codebase. The depth depends on doc type:

### For README
- Project structure (top-level directories)
- Available scripts (`pnpm` commands from package.json)
- Tech stack (from dependencies)
- Entry points
- Environment variables needed (grep for `process.env`, `.env.example`)

### For API
- Exported functions, types, and components in the scoped package
- JSDoc/TSDoc comments
- Public interfaces and their signatures
- Usage examples from tests or other packages that import it

### For Architecture
- Package/module boundaries
- Import dependency graph (what imports what)
- Data flow patterns
- Key abstractions and their responsibilities
- External service integrations

### For Changelog
- Git log since last tag or specified date:
  ```bash
  git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~50")..HEAD
  ```
- Conventional commit messages to categorize changes
- Breaking changes (commits with `BREAKING CHANGE` or `!:`)

> **Two-skill split (v0.7.0+).** `/apt:docs changelog` owns the
> dev-flavored `CHANGELOG.md` surface — internal task IDs, file paths,
> schema-bump notes, process trivia. For the user-facing complement,
> projects can opt in to `/apt:release-notes` via `/apt:setup` →
> Batch 9. That skill produces persona-voice-tuned release notes
> (towncrier-style fragments at PR-merge time, compiled per tag, pushed
> to GitHub Releases). The two skills coexist intentionally: a single
> `--audience` flag inside `/apt:docs changelog` drifts to a
> lowest-common-denominator artifact that satisfies neither audience.
> See `packages/framework/skills/apt-release-notes/SKILL.md` for the
> opt-in surface and the three modes (draft / compile / publish).

### For Contributing
- Development setup steps (verified by checking file existence)
- Test commands (verified by running them)
- Linting/formatting commands
- Branch strategy (from git config or convention)
- PR process
</step>

<step name="verify_existing">
## 4. Verify Existing Documentation (All Modes)

If existing docs exist, audit them for accuracy:

### Verification Checks
For each factual claim in the existing docs:
1. **File paths** — Do referenced files actually exist?
2. **Commands** — Do documented commands actually work?
3. **API signatures** — Do function signatures match the source?
4. **Dependencies** — Are listed dependencies in package.json?
5. **Environment variables** — Are documented env vars actually used?
6. **Architecture claims** — Do described boundaries match actual imports?

Build an audit report:
```json
{
  "doc_type": "{type}",
  "file": "{doc file path}",
  "claims_checked": {n},
  "claims_valid": {n},
  "claims_stale": [
    {
      "line": {n},
      "claim": "{what the doc says}",
      "reality": "{what the code actually does}",
      "severity": "error|warning"
    }
  ],
  "missing_topics": [
    "{topic that should be documented but isn't}"
  ]
}
```

If `--verify-only`:
- Write audit to `.aperant/docs-audit.json`
- Print summary and exit without modifying docs:
  ```
  Documentation Audit: {doc file}
  Claims checked: {n}
  Valid: {n}
  Stale: {n} ({errors} errors, {warnings} warnings)

  Stale claims:
  - Line {n}: {claim} -> Actually: {reality}

  Missing topics:
  - {topic}

  Audit saved to: .aperant/docs-audit.json
  Run /apt:docs {type} to fix these issues.
  ```
  Exit.
</step>

<step name="generate">
## 5. Generate / Update Documentation

### README Template
```markdown
# {Project Name}

{One-line description from package.json}

## Overview
{2-3 sentences about what the project does — derived from constitution/AGENTS.md}

## Quick Start

### Prerequisites
{List verified prerequisites — node version, pnpm, etc.}

### Setup
```bash
{Actual setup commands — verified against package.json scripts}
```

### Development
```bash
{Dev server commands}
```

## Project Structure
```
{Actual directory tree — generated from filesystem}
```

## Tech Stack
{Derived from actual dependencies in package.json}

## Scripts
| Command | Description |
|---------|-------------|
{Derived from package.json scripts}

## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## License
{From package.json or LICENSE file}
```

### API Template
For each exported module in the scope:
```markdown
# {Module Name}

## Functions

### `{functionName}({params}): {returnType}`
{JSDoc description or inferred description}

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
{From type signatures}

**Returns:** `{type}` — {description}

**Example:**
```typescript
{From tests or usage in codebase}
```
```

### Architecture Template
```markdown
# Architecture

## System Overview
{High-level description}

## Package Structure
{Module/package map with responsibilities}

## Data Flow
{How data moves through the system}

## Key Abstractions
{Core types, interfaces, patterns}

## Module Boundaries
{What imports what — and what must NOT import what}

## External Dependencies
{Services, APIs, databases}
```

### Changelog Template (Keep a Changelog format)
```markdown
# Changelog

## [Unreleased]

### Added
{feat: commits}

### Changed
{refactor:/chore: commits}

### Fixed
{fix: commits}

### Breaking
{BREAKING CHANGE commits}
```

### Contributing Template
```markdown
# Contributing

## Development Setup
{Verified setup steps}

## Running Tests
{Verified test commands}

## Code Style
{From linter config and conventions}

## Pull Request Process
{From project conventions}
```

### Merge vs Overwrite
- **Default (merge):** Preserve custom sections the user added. Only update sections that map to verifiable facts.
- **`--force`:** Overwrite the entire file with generated content.
</step>

<step name="commit">
## 6. Commit

```bash
apt-tools commit "docs: {generate|update} {doc-type} documentation" --files {doc-files}
```

If audit was also produced:
```bash
apt-tools commit "docs: {doc-type} documentation with audit" --files {doc-files} .aperant/docs-audit.json
```
</step>

<step name="report">
## 7. Report

```
Documentation {generated|updated}: {doc file}

{If existing docs were updated:}
  Stale claims fixed: {n}
  New sections added: {n}
  Custom sections preserved: {n}

{If new docs were generated:}
  Sections: {n}
  Verified against: {n} source files

All claims verified against codebase.

Commit: {commit hash}
```
</step>

</process>
