> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation Standards & Maintenance

> Version: 2.0.1 Last Updated: 2026-05-13 Status: Active

**Version:** 2.0.1\
**Last Updated:** 2026-05-13\
**Status:** Active

Naming, structure, versioning, maintenance, and cross-references for documentation in this repo. All contributors should follow these standards when creating or updating docs.

> **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.

***

## Document Hierarchy

The documentation follows a clear hierarchy. Current versions: [VERSIONS.md](VERSIONS.md).

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

**Rule:** If documents conflict, `constitution.md` wins.

***

## Specs vs Docs

Product requirements and tasks: `specs/`. How to run, configure, and operate the repo: `docs/`. Hub: [docs/index.md](index.md).

| Use **`specs/`** for                                                                              | Use **`docs/`** for                                                                               |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Product requirements: user stories, acceptance criteria, data model, RLS intent, testing strategy | How to **run, configure, and operate** the product and repo                                       |
| Task breakdown (`specs/*/tasks/*-TASKS.md`) and implementation plans (`specs/*/plans/`)           | Developer onboarding: env, MCP, Supabase CLI, UI standards                                        |
| Spec reviews and compliance sign-offs under `specs/`                                              | **User / admin guides** (`docs/{core}/`), compliance **trackers** (`docs/compliance/`)            |
| Cross-cutting planning bundles under `specs/cross-cutting/`                                       | **Architecture** narratives: integration matrix, event/API contracts, ADRs (`docs/architecture/`) |

### Module documentation (`docs/{core}/`)

User-facing and developer reference documentation:

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

### Integration stubs

Files matching `docs/architecture/integrations/*-INTEGRATION.md` complement specs: they summarize cross-core touchpoints and should link to the canonical spec at `specs/{core}/specs/{SPEC-ID}-*.md` and to [EVENT\_CONTRACTS.md](architecture/integrations/EVENT_CONTRACTS.md) / [API\_CONTRACTS.md](architecture/integrations/API_CONTRACTS.md). They are not a substitute for the spec.

***

## Canonical Locations (Avoid Duplicates)

| Topic                                    | Canonical path                                                                    | Do not use                                              |
| ---------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Cross-cutting specs and planning bundles | `specs/cross-cutting/`                                                            | ~~`specs/_cross-cutting/`~~ (removed)                   |
| Historical docs                          | `docs/archive/` (single root)                                                     | A second parallel `docs/**/archive/` for the same topic |
| Cross-core integration contracts         | `docs/architecture/integrations/` (`EVENT_CONTRACTS.md`, `API_CONTRACTS.md`, ...) | Duplicating contract tables in multiple places          |
| AI load order for agents                 | `docs/AI_DOC_MANIFEST.yaml`                                                       | Ad-hoc duplicate "start here" lists in wrappers         |

**Wrapper files** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`) should link to `AGENTS.md` / `constitution.md` instead of copying long policy tables.

**Hard-prune rule:** Before deleting a doc, confirm **unreferenced** OR **replaced by a canonical doc** OR **copied to `docs/archive/`** when audit or compliance history must be retained.

***

## 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

All core documentation uses semantic versioning: `v{MAJOR}.{MINOR}.{PATCH}`

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

### Version Format

**In Document Header:**

```markdown theme={null}
**Version:** 1.10.1  
**Last Updated:** 2025-12-21
```

**In Cross-References (always version-aware):**

```markdown theme={null}
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

```markdown theme={null}
# Document Title

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

[Optional: Purpose statement]

---
```

**Metadata Requirements:**

* **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.

***

## Cross-Reference Standards

```markdown theme={null}
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

The Mintlify site is a **curated, operator-facing slice** of repo docs. Not every markdown file is published. Mintlify Cloud auto-deploys on every commit to `docs/` (via `docs.json` navigation config).

* **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)

These paths are heavily linked from governance, specs, CI, or agent config.

### Root and agent entry points

| Path                              | Why it matters                                     |
| --------------------------------- | -------------------------------------------------- |
| `constitution.md`                 | Non-negotiable engineering guardrails              |
| `AI_GUIDE.md`                     | AI contribution workflow                           |
| `AGENTS.md`                       | Cross-platform patterns and pre-flight checks      |
| `docs/index.md`                   | Primary documentation hub                          |
| `docs/VERSIONS.md`                | Version sync for governance docs                   |
| `docs/DOCUMENTATION_STANDARDS.md` | Hierarchy, authoring rules, maintenance            |
| `docs/AI_DOC_MANIFEST.yaml`       | Deterministic AI load order for agents and tooling |

### Engineering workflow

| Path                                    | Why it matters                                       |
| --------------------------------------- | ---------------------------------------------------- |
| `docs/development/index.md`             | Development index                                    |
| `docs/development/SPEC_WORKFLOW.md`     | Spec workflow                                        |
| `docs/development/CI_PIPELINE.md`       | Maps `.github/workflows/build.yml` to local commands |
| `docs/testing/TESTING_SETUP_AND_RUN.md` | Canonical test commands and E2E setup                |
| `docs/integrations/EDGE_FUNCTIONS.md`   | Edge function catalog                                |

### Architecture contracts

| Path                                                            | Why it matters                |
| --------------------------------------------------------------- | ----------------------------- |
| `docs/architecture/integrations/index.md`                       | Integration documentation hub |
| `docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md` | Pattern 1                     |
| `docs/architecture/integrations/EVENT_CONTRACTS.md`             | Pattern 2                     |
| `docs/architecture/integrations/API_CONTRACTS.md`               | Pattern 3                     |
| `docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md`     | Integration matrix            |
| `docs/architecture/integrations/*-INTEGRATION.md`               | Per-spec stubs                |

### Compliance and research

| Path                                               | Why it matters                   |
| -------------------------------------------------- | -------------------------------- |
| `docs/compliance/REGULATORY_COMPLIANCE_TRACKER.md` | Regulatory index                 |
| `docs/ehr_pm/research-20260216.md`                 | CL/PM research summary           |
| `docs/ehr_pm/ai-context/README.md`                 | Domain-scoped AI context loading |
| `docs/audits/KEYBOARD_NAVIGATION_AUDIT.md`         | PF-93 accessibility traceability |

***

## Maintenance

### Schedule

| When                     | What to do                                                                                                      |
| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **On version bump**      | Update source doc → `docs/VERSIONS.md` → `npm run check-doc-versions` → update cross-refs → verify              |
| **Monthly**              | `npm run check-doc-versions`, review for outdated info, check broken links                                      |
| **Quarterly**            | Full consistency review, `--include-historical` scan, archive completed audits, check `docs/archive/` for drift |
| **On new feature**       | Update module docs, spec files, implementation logs, architecture if needed                                     |
| **On release candidate** | Run docs validation + freshness audits and confirm docs owner sign-off for changed modules                      |

### AI/Vibe Maintenance Checklist

Primary doc consumers are Cursor and Vibe. Use this checklist when doing doc passes:

* [ ] **Versions:** [docs/VERSIONS.md](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](development/CI_PIPELINE.md) aligned with `.github/workflows/build.yml`.

### Ownership

| Document Category                           | Owner              | Update Trigger                     |
| ------------------------------------------- | ------------------ | ---------------------------------- |
| Core docs (constitution, AI\_GUIDE, AGENTS) | Platform Team      | Version bump or significant change |
| Module docs (core AGENTS.md)                | Module Owners      | Module changes                     |
| Architecture docs                           | Architecture Team  | Architecture changes               |
| Standards docs                              | Documentation Team | Standards changes                  |
| Spec files                                  | Spec Authors       | Feature delivery                   |

Detailed module/audience ownership: `docs/reports/DOCS_OWNERSHIP_MATRIX.md`.

### 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

**Location:** `specs/_templates/SPEC_TEMPLATE.md` — All new feature specifications.

### AGENTS Template

**Location:** `docs/templates/AGENTS_TEMPLATE.md` — Creating/updating core-specific AGENTS.md files.

**AGENTS.md versioning:** Root `AGENTS.md` has explicit version. Platform and core files reference root version only (no own version).

***

## Tools & Automation

### Version Checking

```bash theme={null}
npm run check-doc-versions                                   # active docs only
node scripts/docs/check-doc-versions.js --include-historical # full scan
```

### Link Validation

```bash theme={null}
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
npm run docs:audit:freshness
npm run docs:audit:freshness:strict
```

Pre-commit hooks automatically validate staged `.md` files for broken links.

### Release Checklist Gate

Every release that touches workflows, permissions, compliance controls, integrations, or settings must include one of:

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

For docs-focused PRs, required checks are:

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

Use `docs:audit:freshness:strict` only after the current warning-reduction target for the quarter is reached and accepted in the quarterly docs health report.

### Inventory Regeneration

```bash theme={null}
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`