Documentation Standard

This is the source of truth for documentation structure in this repository.

Location Policy

• Product/application docs must live under apps/docs.
• Markdown outside apps/docs is limited to:
  • root README.md
  • code-area README.md files (for local developer context)
  • workspace/agent rule files in dot-folders
• If app docs are found outside apps/docs, move them.

Required Frontmatter

Every file under apps/docs must include frontmatter:

• title
• description
• audience where applicable (clients, internal, api)

Missing frontmatter fields block docs completion.

Navigation and Indexing

• Each major section/folder should include an index.md.
• New docs must be linked from an appropriate index (section index or internal root index).
• Cross-links should prefer stable canonical paths, not legacy aliases.

Reality-First Rule

Docs must reflect current behavior in apps/frontend and apps/backend.

• If behavior changed, docs update in the same PR.
• If behavior is not implemented yet, mark clearly as future work.
• Future work entries must link to a GitHub issue.

Future Work Convention

Use a dedicated section like ## Future Work and include issue links.

Examples:

• #207 Bulk import backend ingestion
• #208 Report schedule customization
• #209 Media upload finalize lifecycle
• #210 Direct social auto-publish

Documentation Audit Procedure

When running a migration or cleanup:

1. Generate/update internal/documentation-inventory.md.
2. Validate frontmatter fields across all docs.
3. Validate markdown links.
4. Verify docs build (pnpm build:docs).
5. Fix stale route references (prefer canonical routes from apps/frontend/src/app/router.tsx).

Related

• Internal Documentation Index
• Documentation Inventory
• UI Architecture Strategy