Documentation Guide

This document describes the types of documentation we maintain, the automation (pnpm scripts, Cursor skills, and rules), and a runbook for common tasks.

---

1. Types of Documentation

Type	Location	Purpose	Source / How updated
API docs	docs/api/	REST endpoint reference: routes, request/response schemas, auth	Generated from src/endpoints/**/*.endpoint.ts and src/data/**/*.endpoint.ts; update via generate-api-docs skill
Command docs	docs/commands/	Discord bot slash commands, parameters, permissions	Generated from src/data/**/*.command.ts; update via generate-command-docs skill
Reference docs	docs/reference/	Service, repository, and validator contracts (method signatures, types)	Generated from src/data/**/*.service.ts, *.repository.ts, *.validators.ts; update via generate-reference-docs skill
Customer docs	docs/customer/	User-facing guides by persona (admin, guild member, developer)	Authored; update via author-customer-docs skill
Developer docs	docs/developer/	Architecture, onboarding, conventions, layer READMEs	Authored; update via author-developer-docs skill
Release notes	docs/releases/	Changelog and semantic-release history	Conventional commits on main drive semantic-release versioning and changelog updates in docs/releases/CHANGELOG.md; GitHub Releases are published automatically
Runbooks	docs/runbooks/	Operational procedures: deployment, incidents, maintenance	Authored markdown; add as needed
Implementation plans	docs/plans/	Linear-issue implementation plans (from workon)	Created by Linear workflow; reference only
AI Ecosystem	docs/ai-ecosystem/	Cursor setup, skills, rules, MCP, external services, local tooling	Authored narrative + generated Reference via pnpm docs:ai-ecosystem:generate
Top-level	docs/*.md	ARCHITECTURE, CONTRIBUTING, AGENTS, SOW, config, auth	Authored; edit directly

The docs site is built with Docusaurus 3 from docs-site/ and sources content from the docs/ tree. The live site is deployed to Render when docs/, docs-site/, or src/**/*.documentation.md changes on main.

Pre-commit doc update: Before every commit, scripts/docs/pre-commit-doc-update.mjs runs. It loads the source-of-truth rules from scripts/docs/documentation-types.rules.json, looks at the staged diff, and determines which doc types are affected (API, commands, reference, customer, developer, AI Ecosystem). It runs generators we have (e.g. docs:ai-ecosystem:generate when .cursor/ changed) and stages their output. For types that require the AI (API, command, reference, customer, developer), it either runs your DOC_UPDATE_CMD (if set) or writes a prompt to scripts/docs/.pre-commit-doc-prompt.md and blocks the commit until you run that prompt in Cursor, update the docs, stage them, and commit again. So every commit that touches endpoints, commands, services, or persona-relevant code either includes the doc updates in the same commit or fails with clear instructions.

To enable full automatic AI doc updates from pre-commit, set:

export DOC_UPDATE_CMD="bash scripts/docs/doc-update-cmd.sh"

The wrapper scripts/docs/doc-update-cmd.sh is production-ready and uses cursor-agent to run doc updates in parallel by doc type (API, commands, reference, customer personas, developer guide). See AI Ecosystem docs for the full behavior and optional env vars (MAX_PARALLEL_DOC_AGENTS, DOC_UPDATE_CURSOR_MODEL, etc.).

---

2. pnpm Scripts (Documentation)

Script	Command	Description
docs:dev	pnpm docs:dev	Start the Docusaurus dev server (hot reload). Use when writing or reviewing docs locally.
docs:build	pnpm docs:build	Install docs-site deps and build the static site. Runs in CI; must pass for merge.
release	pnpm release	Run semantic-release on main: compute next semver from conventional commits, update changelog, tag, and publish GitHub Release.
release:dry	pnpm release:dry	Dry-run semantic-release locally/CI to validate next version and generated notes without publishing.
docs:ai-ecosystem:generate	pnpm docs:ai-ecosystem:generate	Regenerate docs/ai-ecosystem/reference.md from .cursor/skills, .cursor/rules, .cursor/commands, and .cursor/mcp.json. Run after adding or changing any skill, rule, command, or MCP server.
docs:pre-commit-update	pnpm docs:pre-commit-update	Run the same logic as the pre-commit hook: from staged files, determine affected doc types, run generators, and exit 1 with a prompt path if AI doc updates are required. Used by Husky pre-commit.

API, command, and reference docs are regenerated using the Cursor skills below (or by editing generated files only when necessary, respecting the generated-docs-readonly rule).

---

3. Cursor Skills (Documentation)

Use these from Cursor when you need to create or refresh documentation.

Skill	When to use	What it does
generate-api-docs	Endpoint files (*.endpoint.ts) added or changed	Generates/updates docs/api/<feature>.md per endpoint group; documents method, path, body, response, auth; reminds to run pnpm docs:build.
generate-command-docs	Command files (*.command.ts) added or changed	Generates/updates docs/commands/<feature>.md and catalog; documents command name, params, permissions; reminds to run pnpm docs:build.
generate-reference-docs	Services, repositories, or validators added or changed	Generates/updates docs/reference/<feature>.md with method signatures, repository contract, validator schemas; reminds to run pnpm docs:build.
author-customer-docs	User-facing features added or changed	Creates/updates persona docs in docs/customer/admin/, guild-member/, or developer/ with clear steps and examples.
author-developer-docs	Architecture, onboarding, or conventions changed	Updates docs/developer/ and layer READMEs; keeps alignment with docs/ARCHITECTURE.md.

Skills live under .cursor/skills/. Invoke by name in Cursor when the task matches “when to use” above.

---

4. Cursor Rules (Documentation)

These rules enforce documentation contracts. They live under .cursor/rules/.

Rule	Purpose
api-doc-contract	When changing *.endpoint.ts, update or create docs/api/<feature>.md and run pnpm docs:build. Use generate-api-docs skill.
command-doc-contract	When changing *.command.ts, update or create docs/commands/<feature>.md and run pnpm docs:build. Use generate-command-docs skill.
service-doc-contract	When changing *.service.ts, *.repository.ts, or *.validators.ts, update or create docs/reference/<feature>.md and run pnpm docs:build. Use generate-reference-docs skill.
generated-docs-readonly	Treat docs/api/, docs/commands/, and docs/reference/ as generated; don’t edit by hand except to fix urgent issues. Update source and re-run the corresponding skill. READMEs in those dirs may be edited.
documentation-and-comments	Code-level: JSDoc for exported/shared symbols; inline comments for non-obvious logic. Applies to src/**/*.ts. Keeps source the single source of truth for generated API/reference docs.

---

5. Cursor Commands

There are no documentation-specific Cursor commands. Documentation work is done via the skills above and the pnpm scripts in §2. General commands (e.g. workon, openpr) are unchanged.

---

6. Runbook: do this when you want that

Goal	What to do
Preview the docs site locally	Run pnpm docs:dev and open the URL (e.g. http://localhost:3000).
Check that the docs site builds (e.g. before pushing)	Run pnpm docs:build. Fix any build or link errors.
Add or change an API endpoint	1) Implement in *.endpoint.ts. 2) Use generate-api-docs skill (or update docs/api/<feature>.md and keep it in sync). 3) Run pnpm docs:build.
Add or change a Discord command	1) Implement in *.command.ts. 2) Use generate-command-docs skill (or update docs/commands/<feature>.md). 3) Run pnpm docs:build.
Add or change a service, repository, or validator	1) Implement in src/data/<feature>/. 2) Use generate-reference-docs skill (or update docs/reference/<feature>.md). 3) Run pnpm docs:build.
Document something for admins, guild members, or API users	Use author-customer-docs skill; add or edit pages under docs/customer/admin/, docs/customer/guild-member/, or docs/customer/developer/. Run pnpm docs:build.
Update architecture, onboarding, or developer conventions	Use author-developer-docs skill; edit docs/developer/ and/or docs/ARCHITECTURE.md, docs/CONTRIBUTING.md, docs/AGENTS.md as needed. Run pnpm docs:build.
Add a user-visible change to release notes	Use conventional commits in your PR (feat, fix, perf, and BREAKING CHANGE), merge to main, and let semantic-release update changelog/tags/releases automatically.
Preview next release version/notes before merge	Run pnpm release:dry. This validates semantic-release parsing and shows the computed next version and notes without creating a tag/release.
Document an operational procedure (deploy, incident, maintenance)	Add a new markdown file under docs/runbooks/ with clear steps and link it from docs/runbooks/README.md if useful.
Fix a typo or small error in generated API/command/reference docs	Edit the file in docs/api/, docs/commands/, or docs/reference/ if necessary, but prefer fixing the source and re-running the corresponding generate-* skill so the fix persists.
See why the docs build failed in CI	Check the job that runs pnpm docs:build (e.g. in ci.yml). Fix broken links, invalid frontmatter, or missing files.
Deploy the docs site	Push changes to main that touch docs/, docs-site/, or src/**/*.documentation.md; the docs-deploy workflow runs and Render deploys from the repo. No manual deploy step.
Add or change a Cursor skill, rule, command, or MCP server	Pre-commit runs docs:pre-commit-update, which runs docs:ai-ecosystem:generate when .cursor/ changed and stages reference.md. No extra step unless you bypass the hook.
Commit code that touches endpoints, commands, or services	Pre-commit runs first. If API/command/reference/customer/developer docs are affected, the hook writes scripts/docs/.pre-commit-doc-prompt.md and fails. In Cursor, run that prompt to update all affected docs, then git add docs/ and commit again. For full automation, set DOC_UPDATE_CMD and have that wrapper run AI updates (optionally parallel subagents).

---

Legal Templates

Tenant-customizable legal document templates live under docs/legal/. The set includes a privacy policy, terms of service, refund policy, and cookie policy — each pre-wired for the platform's third-party integrations (Stripe, NOWPayments, TaxJar, SendGrid, EasyPost, Discord) and using a consistent placeholder vocabulary. See docs/legal/README.md for customization instructions.

---

7. Release Conventions

• Canonical source: Conventional commits merged to main.
• Versioning: semantic-release computes semver and creates release tags.
• Release notes: semantic-release generates notes and updates docs/releases/CHANGELOG.md.

---

8. CI and Deployment

• CI: pnpm docs:build runs in the main pipeline. The branch cannot merge if the docs site fails to build.
• Release: On successful CI completion for main, the Release workflow runs pnpm release (semantic-release) to compute semver, update changelog, tag, and publish GitHub release notes.
• Deploy: The docs-deploy workflow runs on push to main when paths under docs/, docs-site/, or src/**/*.documentation.md change. Render builds and serves the static site per render.yaml.