Documentation Types and Rules

This is the source-of-truth guide for what documentation must be updated when code changes.

The automation rules are defined in:

• scripts/docs/documentation-types.rules.json

The pre-commit hook reads that file and decides which docs are required for the staged diff.

Rule model

Each doc type has:

• docPaths - where the documentation lives in docs/
• triggerPatterns - staged file patterns that mark this doc type as affected
• automationMode - generator or ai
• skills or generatorCommand - how updates are produced

Documentation coverage matrix

Documentation type	Docs path(s)	Triggered by changes in	Automation kickoff
API Documentation	docs/api/	*.endpoint.ts	Pre-commit marks API docs affected; AI update via generate-api-docs skill required before commit can pass
Data Dictionary	docs/reference/data-dictionary.md	src/data/**, *.model.ts	Pre-commit marks data dictionary affected; AI update via generate-reference-docs skill required
Service Guide	docs/developer/service-guide.md	*.service.ts	Pre-commit marks service guide affected; AI update via author-developer-docs skill required
Command Documentation	docs/commands/	*.command.ts	Pre-commit marks command docs affected; AI update via generate-command-docs skill required
Domain Reference Documentation	docs/reference/	*.service.ts, *.repository.ts, *.validators.ts	Pre-commit marks reference docs affected; AI update via generate-reference-docs skill required
Customer Guide - Server Admin	docs/customer/admin/	API changes, command changes, and admin-facing feature folders under src/data/	Pre-commit marks admin guide affected; AI update via author-customer-docs skill required
Customer Guide - Guild Member	docs/customer/guild-member/	Discord command flow, ordering/payment/product-related source changes	Pre-commit marks guild-member guide affected; AI update via author-customer-docs skill required
Customer Guide - Developer/Integrator	docs/customer/developer/	Endpoint and validator changes affecting API contracts	Pre-commit marks developer guide affected; AI update via author-customer-docs skill required
Developer Documentation	docs/developer/, docs/ARCHITECTURE.md, docs/CONTRIBUTING.md, docs/AGENTS.md	architecture/composition/local-tooling changes (src/init, src/server, .cursor/rules, .husky, package.json, etc.)	Pre-commit marks developer docs affected; AI update via author-developer-docs skill required
Release Notes	docs/releases/CHANGELOG.md	Conventional commits merged to main	Release workflow runs semantic-release after CI success; not pre-commit generated
AI Ecosystem Reference	docs/ai-ecosystem/reference.md	.cursor/ and scripts/docs/ changes	Pre-commit runs generator pnpm docs:ai-ecosystem:generate and auto-stages output

When automation kicks off

CI and deploy responsibilities

• Pre-commit: decides what docs must change and enforces updates in the same commit (except release notes).
• CI (pnpm docs:build): validates the docs site builds; does not infer missing docs.
• Release workflow (pnpm release): semantic-release computes version/changelog from commits and publishes tags/releases.
• Docs deploy workflow: publishes the docs site on main when doc paths change.

AI execution modes (manual vs automatic)

There are two ways AI-backed doc types run during pre-commit:

1. Manual mode (default)
   If DOC_UPDATE_CMD is not set, pre-commit writes scripts/docs/.pre-commit-doc-prompt.md and exits 1.
   You run that prompt in Cursor, stage updated docs, and commit again.

2. Automatic mode (recommended for full automation)
   Set DOC_UPDATE_CMD to a wrapper command/script that accepts the prompt path and runs AI updates. Pre-commit calls it, stages docs/, validates required doc paths are staged, and continues.

DOC_UPDATE_CMD wrapper

Use the included wrapper:

• scripts/docs/doc-update-cmd.sh

Example setup:

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

This wrapper already implements parallel cursor-agent runs per affected doc type.

Environment knobs:

• MAX_PARALLEL_DOC_AGENTS (default 4)
• DOC_UPDATE_CURSOR_MODEL (optional)
• DOC_UPDATE_APPROVE_MCPS (default 1)
• CURSOR_AGENT_BIN (default cursor-agent)

Operational checklist (2-minute setup)

1. Authenticate Cursor Agent
   • Run cursor-agent login once on your machine.
2. Enable automatic mode
   • Export: DOC_UPDATE_CMD="bash scripts/docs/doc-update-cmd.sh"
3. (Optional) tune parallelism
   • Export MAX_PARALLEL_DOC_AGENTS=2 or 3 if your machine/network is constrained.
4. Smoke test without committing
   • Stage a file that should trigger docs and run:
   • pnpm docs:pre-commit-update
5. Review logs when a doc-type run fails
   • Check scripts/docs/.doc-update-logs/<doc-type>.log
6. Verify output before final commit
   • Run pnpm docs:build and review staged docs/** changes.

How to extend safely

When you add a new doc type or need different triggers:

1. Edit scripts/docs/documentation-types.rules.json.
2. Keep docPaths, triggerPatterns, and automationMode explicit.
3. If automationMode=generator, provide generatorCommand and stagePaths.
4. If automationMode=ai, provide the skill names in skills.
5. Test with a small staged diff and run node scripts/docs/pre-commit-doc-update.mjs.

This keeps documentation automation behavior declarative and maintainable.