bootstrap/guides/DOCUMENTATION.md

Documentation Standard (MANDATORY)

This guide defines REQUIRED documentation behavior for all Mosaic projects. If code, API contracts, auth, or infrastructure changes, documentation updates are REQUIRED before completion.

Hard Rules

1. Documentation is a delivery gate. Missing required documentation is a BLOCKER.
2. docs/PRD.md or docs/PRD.json is REQUIRED as the project requirements source before coding begins.
3. API documentation is OpenAPI-first. docs/API/OPENAPI.yaml (or .json) is the canonical API contract.
4. Public and private/internal endpoints MUST be documented.
5. API input and output schemas MUST be documented.
6. API authentication and permissions MUST be documented per endpoint.
7. A current site map MUST exist at docs/SITEMAP.md.
8. Documentation updates MUST be committed in the same logical change set as the code/API change.
9. Generated publishing output (Docusaurus/VitePress/MkDocs artifacts) is not canonical unless the project explicitly declares it canonical.
10. docs/ root MUST stay clean. Reports and working artifacts MUST be stored in dedicated subdirectories, not dumped at docs/ root.

Required Documentation Structure

docs/
  PRD.md (or PRD.json)
  TASKS.md (active orchestrator tracking, when orchestrator is used)
  SITEMAP.md
  USER-GUIDE/
  ADMIN-GUIDE/
  DEVELOPER-GUIDE/
  API/
    OPENAPI.yaml
    ENDPOINTS.md
  scratchpads/
  reports/
  tasks/
  releases/
  templates/ (optional)

Minimum requirements:

• docs/PRD.md or docs/PRD.json: authoritative requirements source for implementation and testing.
• docs/USER-GUIDE/: End-user workflows, feature behavior, common troubleshooting.
• docs/ADMIN-GUIDE/: Configuration, deployment, operations, incident/recovery procedures.
• docs/DEVELOPER-GUIDE/: Architecture, local setup, contribution/testing workflow, design constraints.
• docs/API/OPENAPI.yaml: API SSOT for all HTTP endpoints.
• docs/API/ENDPOINTS.md: Human-readable index for API endpoints, permissions, and change notes.
• docs/SITEMAP.md: Navigation index for all user/admin/developer/API documentation pages.
• docs/reports/: Review outputs, QA automation reports, deferrals, and audit artifacts.
• docs/tasks/: Archived task snapshots and orchestrator learnings.
• docs/releases/: Release notes and release-specific documentation.
• docs/scratchpads/: Active task-level working notes.

Root Hygiene Rule (MANDATORY)

Allowed root documentation files are intentionally limited:

1. docs/PRD.md or docs/PRD.json
2. docs/TASKS.md (active milestone only, when task orchestration is in use)
3. docs/SITEMAP.md
4. docs/README.md (optional index)

All other docs MUST be placed in scoped folders (docs/reports/, docs/tasks/, docs/releases/, docs/scratchpads/, docs/API/, guide books).

Artifact Placement Rules

Artifact Type	REQUIRED Location
Code review reports, QA reports, audits	docs/reports/<category>/
Deferred error lists / unresolved findings	docs/reports/deferred/
Archived milestone task snapshots	docs/tasks/
Orchestrator learnings JSON	docs/tasks/orchestrator-learnings.json
Release notes	docs/releases/
Active scratchpads	docs/scratchpads/

API Documentation Contract (OpenAPI-First)

For every API endpoint, documentation MUST include:

1. visibility: public or private/internal
2. method and path
3. endpoint purpose
4. request/input schema
5. response/output schema(s)
6. auth method and required permission/role/scope
7. error status codes and behavior

If OpenAPI cannot fully express an internal constraint, document it in docs/API/ENDPOINTS.md.

Book/Chapter/Page Structure

Use this structure for every guide:

1. Book: one root guide folder (USER-GUIDE, ADMIN-GUIDE, DEVELOPER-GUIDE)
2. Chapter: one subdirectory per topic area
3. Page: one focused markdown file per concern

Required index files:

1. docs/USER-GUIDE/README.md
2. docs/ADMIN-GUIDE/README.md
3. docs/DEVELOPER-GUIDE/README.md

Each index file MUST link to all chapters and pages in that book.

Situational Documentation Matrix

Change Surface	REQUIRED Documentation Updates
New feature or behavior change	User guide + developer guide + sitemap
API endpoint added/changed/removed	OpenAPI + API endpoint index + sitemap
Auth/RBAC/permission change	API auth/permission docs + admin guide + developer guide
Database schema/migration change	Developer guide + admin operational notes if runbook impact
CI/CD or deployment change	Admin guide + developer guide
Incident, recovery, or security control change	Admin guide runbook + security notes + sitemap

Publishing Target Rule (MANDATORY)

If the user does not specify documentation publishing target, the agent MUST ask:

1. Publish in-app (embedded docs)
2. Publish on external docs platform (for example: Docusaurus, VitePress, MkDocs)

Default behavior before publishing decision:

• Keep canonical docs in-repo under docs/.
• Do not assume external publishing platform.

Completion Gate

You MUST NOT declare completion until all required documentation updates are done.

Use ~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md as the final gate.