Documentation Standards & Maintenance

Consolidation note (2026-04-10): This file now includes content previously in MODULE_DOCUMENTATION_GUIDE.md, SPECS_AND_DOCS.md, PUBLISHED_DOCUMENTATION.md, DOCUMENTATION_MAINTENANCE.md, and _inventory/REFERENCE_MAP.md. 2026-05-25 (v2.1.0): added Structure Allowlist & Guards. 2026-06-11 (v2.2.0): added Editorial Rules for Published Pages (de-numbering, spec: frontmatter, duplicate-title pattern, module nav skeleton). 2026-06-13 (v2.3.0): added the description SEO-summary rule (no metadata cruft) and the single Planned convention (tag: "Planned" + /snippets/planned.mdx).

​

Document Hierarchy

constitution.md - Authoritative, non-negotiable guardrails (WHAT)
  └─ AI_GUIDE.md - Detailed AI contribution guidelines (HOW)
      └─ AGENTS.md - Quick reference for AI agents (GitHub Copilot, Cursor, Lovable)
          └─ .cursor/rules/ - Detailed patterns
          └─ Platform AGENTS.md, Core AGENTS.md - Module-specific patterns

​

Specs vs Docs

​

Module documentation (docs/{core}/)

• User guides: *-user-guide.md | Admin guides: *-admin-guide.md
• API references: *-API-REFERENCE.md | Module settings: *-MODULE-SETTINGS.md

​

Integration stubs

​

Canonical Locations (Avoid Duplicates)

​

Mintlify site

​

Editorial Rules for Published Pages

​

De-numbering (no spec IDs in human-visible text)

• title:, sidebarTitle:, description:, and the first H1 of a user-facing page must not contain spec IDs (CL-15, HR-09-P5-4, CE-74-EN-01, …).
• Spec traceability lives in the non-rendered frontmatter field spec: <SPEC-ID> (alongside the existing audience: and core: fields). Body prose may still reference spec IDs where genuinely helpful (e.g. compliance evidence detail).
• Compliance-evidence pages follow the same rule: plain-language title + spec: field; the spec ID stays in the body so auditors can trace evidence to implementation.
• Engineering and Reference tabs are exempt — spec IDs are load-bearing traceability in ADRs, integration contracts, and snapshots. Those pages carry noindex: true instead (internal operational surface, kept out of search engines).

​

description: a human SEO summary, not metadata cruft

• Every published page carries a description: that is a human, ~150–160-char summary of what the page covers. It is what search engines and the in-product search surface to readers, so it must read as a sentence.
• No document-header metadata in description — values like Version: 1.1.0 Last Updated: 2026-04-11 Status: Active, a trailing Last Updated: <date> stamp, or Feature ID: … leaked in from the old in-body header convention when frontmatter was first injected. They tell a reader nothing and are rejected.
• Drafting is script-assisted, then reviewed: npm run docs:inject-frontmatter:rewrite-cruft replaces a cruft description with the first prose paragraph of the body (skipping the legacy **Version:**/**Last Updated:** header lines, callouts, lists, and code). Pages where no prose is derivable are printed under “needing a MANUAL summary” — author those by hand. Always review the drafts; the script gets you 90% there, not 100%.

​

Planned: one convention for features documented ahead of GA

• Page-level — add tag: "Planned" to the page frontmatter so a Planned badge renders beside the page title in the sidebar (Mintlify tag field). Use this when the whole surface is planned.
• Inline — import and drop the reusable snippet next to the specific feature it qualifies:
  import Planned from '/snippets/planned.mdx'
  
  - **Scheduling** — automated report delivery <Planned />
  
  The badge links the changelog, where planned items are tracked (and which the site banner points to).
• Do not write raw “Coming Soon”, “(coming soon)”, or “Coming Soon” section headings in published pages — reframe them as Planned. (The page-level coming-soon.mdx “full per-core docs are planned” Note remains for module-overview landing pages; it is a structured placeholder, not ad-hoc prose.)

​

Duplicate-title pattern

​

Module navigation skeleton

​

Structure Allowlist & Guards

​

specs// sanctioned subfolders

​

docs/ rules

​

Transient analysis

• .scratch/ (gitignored) — one-off agent analysis; never committed.
• docs/_working/ — shared in-progress work; updated: frontmatter required; 90-day TTL (ttl_days: overrides).

​

Guards (enforced by npm run docs:validate + pre-commit)

• docs:check-structure — placement (allowlist) + naming (kebab vs SCREAMING_SNAKE).
• docs:check-frontmatter — required header fields + spec status: enum.
• docs:check-spec-status — canonical spec status: enum (warn-only).
• docs:check-staleness — summary/status doc TTL.

​

Canonical docs guard set (where each check runs)

Agent-doc staleness checker: scans agent docs (AGENTS.md + nested, AI_GUIDE.md, constitution.md/.mdc) for [YYYY-MM] date markers older than 90 days. With no arguments it scans a fixed list of high-traffic docs (governance / full scan); pass --since=<ref> and/or explicit paths to scope to a PR’s changed agent docs (so any core’s AGENTS.md is checked, not just the default three). The PR step in docs-coverage.yml runs --since=origin/<base_ref>. Use audit:agent-doc-staleness:strict (adds --fail-on-stale) when promoting to blocking; to flip the PR step to blocking, switch it to :strict and drop continue-on-error.

​

File Naming Conventions

• Guides: *-guide.md (e.g., workflow-builder-guide.md)
• References: *-REFERENCE.md or *-API-REFERENCE.md
• Standards: *-standards.md or *-pattern.md
• Reviews: *-REVIEW.md or *-ANALYSIS.md
• Templates: *-TEMPLATE.md
• Index: index.md (Mintlify nav landing pages) or README.md (non-published directories)

​

Case Conventions

• Lowercase with hyphens: For most files (e.g., workflow-builder-guide.md)
• UPPERCASE with underscores: For important standards/references (e.g., UI_UX_STANDARDS.md)
• PascalCase: Avoid

​

Version Numbering

• MAJOR: Breaking principle changes or removed principles
• MINOR: New principles or materially expanded guidance
• PATCH: Clarifications, wording, typos, non-semantic fixes

​

Version Format

**Version:** 1.10.1  
**Last Updated:** 2025-12-21

See `constitution.md` (current: see docs/VERSIONS.md) for details.

​

Version Management

• Single Source of Truth: docs/VERSIONS.md contains current versions
• Update Process:
  1. Update version in source document
  2. Update docs/VERSIONS.md
  3. Run npm run check-doc-versions
  4. Update all cross-references
  5. Verify with script

​

Document Structure

​

Standard Header

# Document Title

**Version:** X.Y.Z  
**Last Updated:** YYYY-MM-DD  
**Status:** Active | Archived | Deprecated

[Optional: Purpose statement]

---

• Version: Required for core governance documents. Optional for guides.
• Last Updated: Required for all documents. Update when content changes.
• Status: Required. Use Active, Archived, or Deprecated.
• Location: Header only. No footer duplicates.

​

Module overview page contract

1. Lead paragraph — one or two sentences on what the core does.
2. Semantic callout — a <Note> / <Warning> for the architecture boundary or alpha/PHI caveat (not bold inline text).
3. Key surfaces — a <CardGroup> of the core’s primary surfaces, each with an icon and (where a page exists) an href. Required.
4. Get oriented — a <Steps> block walking the primary end-to-end flow. Recommended.
5. By role — a <Tabs> block, one tab per persona. Recommended.
6. Scope at a glance — the bulleted scope list.
7. Related — a closing <CardGroup> of cross-core integrations, specs, and compliance trackers.

​

Cross-Reference Standards

See `constitution.md` (current: see docs/VERSIONS.md) for engineering guardrails.

• Use relative paths for same-repo references
• Always include version awareness via (current: see docs/VERSIONS.md) pattern
• Link to specific sections: [Architecture](../constitution.md#1-architecture--module-boundaries)

​

Published Documentation

• Source: Root docs/ — commit here; Mintlify Cloud picks it up automatically
• Nav config: docs.json — add pages to the appropriate navigation group
• Standards: Same quality standards as root docs/ (clarity, consistency, completeness, cross-references)
• Frontmatter: title and description required for all published pages
• Not published: docs/archive/**, docs/_inventory/**, most ADRs and integration stubs

​

Source-of-truth policy

• Canonical authoring source: Root docs/ remains canonical for governance, engineering workflow, architecture, compliance trackers, and internal operations documentation.
• Publishing: Commit to docs/; Mintlify Cloud deploys the pages listed in docs.json.
• Nav ownership: Any page linked in docs.json must be maintained in docs/, with required frontmatter.
• Not every docs/ page is published — only pages explicitly listed in docs.json appear on the site.

​

Documentation Organization

​

Directory Structure

/docs
  /architecture      # System design, integration patterns, ADRs
  /development       # Developer guides, setup instructions
  /{core}            # Module-specific documentation (fw, fa, rh, etc.)
  /guides            # User guides and use cases
  /integrations      # External integrations (Supabase, n8n, etc.)
  /compliance        # Regulatory compliance
  /security          # Security guidelines
  /operations        # Runbooks, monitoring
  /testing           # Testing strategies, UAT
  /migration         # Migration guides
  /archive           # Archived/historical documentation
  /templates         # Documentation templates

​

Active vs Historical Content

• Active docs (default validation scope): standards, guides, architecture, module references, compliance trackers.
• Historical docs: docs/archive/ — superseded plans, old inventories, archived checklists.
• npm run check-doc-versions scans active docs only.
• node scripts/docs/check-doc-versions.js --include-historical for full scan.

​

High-Traffic Paths (Do Not Move Without Updating Links)

​

Root and agent entry points

​

Engineering workflow

​

Architecture contracts

​

Compliance and research

​

Maintenance

​

Schedule

​

AI/Vibe Maintenance Checklist

• Versions: docs/VERSIONS.md is the single source of truth; sync all governance version references from it.
• AI manifest: After changing canonical governance paths, run npm run check-ai-doc-manifest and update docs/AI_DOC_MANIFEST.yaml.
• Hierarchy: The canonical chain is constitution.md -> AI_GUIDE.md -> AGENTS.md -> .cursor/rules/* (no LOVABLE peer file).
• Agents: Each file in .cursor/agents/ has a “Context to load” section; no long duplicate tables.
• Commands: .cursor/README.md command inventory is current.
• Bloat: Run audit-ai-docs periodically; archive superseded docs.
• CI map: Keep docs/development/CI_PIPELINE.md aligned with .github/workflows/build.yml.

​

Ownership

​

Archiving

• When: Documentation superseded by newer version, or historical reference only.
• Where: docs/archive/{category}/. Implementation log archives: specs/{core}/IMPLEMENTATION_LOG_ARCHIVE.md.
• How: Keep original file name. Add archive note at top. Update cross-references.

​

Template Usage

​

Specification Template

​

AGENTS Template

​

Tools & Automation

​

Version Checking

npm run check-doc-versions                                   # active docs only
node scripts/docs/check-doc-versions.js --include-historical # full scan

​

Link Validation

npm run validate-docs                    # full link validation
npm run docs:validate                    # combined (links + versions)
npm run docs:check-frontmatter           # Mintlify frontmatter completeness
npm run docs:audit-nav                   # navigation config audit

The docs:audit:freshness scripts (and scripts/audit/audit-docs-freshness.js) were removed; per-doc TTL freshness is covered by scripts/docs/check-staleness.ts.

​

Release Checklist Gate

• updated user/admin/developer/security docs in the same PR, or
• a linked follow-up task with owner + due date in docs planning artifacts.

• npm run docs:check-frontmatter
• npm run docs:audit-nav
• node scripts/audit/validate-doc-links.js

​

Inventory Regeneration

npm run validate-docs          # re-run validation counts
npm run check-doc-versions     # verify version consistency

​

Related Documents

• Version Registry: docs/VERSIONS.md
• Constitution: constitution.md (current: see docs/VERSIONS.md)
• AI Guide: AI_GUIDE.md (current: see docs/VERSIONS.md)
• Documentation Hub: docs/index.md