Documentation

Documentation Management

Purpose: Keep documentation synchronized with code Primary Agent: release-sentinel (opus) — docs↔code sync, staleness, changelog generation Supporting Agent: docs (sonnet) — writes JSDoc/README/API/architecture docs Contributors: all agents (each documents its own output)

---

The Documentation Promise

"Every feature is documented. Every change is tracked. No user is left wondering how something works."

The doc tree below is the recommended layout for a consuming project — it is aspirational, not the structure of this plugin repo itself. Adopt the parts that fit; do not scaffold empty directories to match it.

---

Documentation Hierarchy

docs/
├── README.md                 # Entry point, always current
├── CHANGELOG.md              # Auto-generated from commits
├── CONTRIBUTING.md           # How to contribute
├── 
├── getting-started/          # Onboarding
│   ├── installation.md
│   ├── quick-start.md
│   └── first-project.md
│
├── guides/                   # How-to guides
│   ├── authentication.md
│   ├── deployment.md
│   └── troubleshooting.md
│
├── api/                      # API reference (auto-generated)
│   ├── overview.md
│   ├── users.md
│   ├── projects.md
│   └── webhooks.md
│
├── components/               # Component docs (auto-generated)
│   ├── button.md
│   ├── input.md
│   └── card.md
│
├── cli/                      # CLI reference (auto-generated)
│   └── commands.md
│
├── architecture/             # Design docs (manual)
│   ├── overview.md
│   ├── decisions/            # ADRs
│   │   ├── 001-database-choice.md
│   │   └── 002-auth-strategy.md
│   └── diagrams/
│
└── templates/                # Doc templates
    ├── api-endpoint.md
    ├── component.md
    └── adr.md

---

Documentation Types & Ownership

1. Reference Documentation (Auto-Generated)

What: API endpoints, component props, CLI commands, config options How: Extract from code annotations (JSDoc, OpenAPI, decorators) When: On every relevant code change Owner: Release Sentinel (automated)

/**
 * Create a new user account
 * 
 * @endpoint POST /api/users
 * @auth Required (Bearer token)
 * @rateLimit 10 requests/minute
 * 
 * @param {string} email - User's email address
 * @param {string} password - Password (min 8 chars)
 * @param {string} [name] - Display name (optional)
 * 
 * @returns {User} Created user object
 * @throws {400} Invalid input
 * @throws {409} Email already exists
 * 
 * @example
 * ```bash
 * curl -X POST https://api.example.com/users \
 *   -H "Authorization: Bearer <token>" \
 *   -d '{"email": "[email protected]", "password": "secure123"}'
 * ```
 */
export async function createUser(req: Request): Promise<User> {
  // Implementation
}