# 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

```text
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.