Documentation Index
Fetch the complete documentation index at: https://na-36-merge-docs-v2-dev-draft-into-docs-v2-clean-20260525.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
Feature Map
This repository is a docs-as-infrastructure system, not a folder of pages. The intended operating model is ownerless: every governed surface declares its canonical source, validator, repair path, and primary gate so a contributor or agent can diagnose and repair drift without private maintainer context. Use this page as the high-level system map. Use the linked feature pages for implementation details and the Gap Analysis for purge, migration, and remediation work.Core philosophy
| Principle | What it means in this repo | Primary evidence |
|---|---|---|
| Ownerless governance | A surface is not production-ready unless it has one canonical source, one validator, one repair path, and one primary gate | policies/ownerless-governance.mdx · canonical: operations/governance/config/repo-governance-surfaces.json (5 unified surfaces, 4 ownerless-ready, 1 advisory post-D-ACT-10); legacy ownerless-governance-surfaces.json (8 entries) superseded |
| Source of truth before convenience | Generated outputs, indexes, and registries must be regenerated from canonical inputs, never hand-edited | policies/source-of-truth-policy.mdx · operations/governance/config/generated-artifacts.json (29 artefacts) |
| Root causes over bypasses | Failures get repaired in the policy, generator, source data, or validator that owns the drift. Ignoring files or hiding failures is not sufficient | AGENTS.md · .githooks/ · policies/quality-gates.mdx |
| Layered enforcement | Fast local checks stay in pre-commit; branch and AI task checks stay in pre-push; broad browser/link/network sweeps belong in scheduled CI | policies/infrastructure-principles.mdx · operations/tests/WHEN-TESTS-RUN.md |
| Public docs and repo ops are one product | Content, components, data feeds, automation, AI artefacts, and governance docs evolve together | docs.json · v2/ · snippets/ · operations/ · docs-guide/ |
| Honesty about partial state | ”Ownerless” covers routine drift, not policy authorship or destructive operations. Live state never lies in canonical docs | This map + Gap Analysis are dated; every count traces to a generator or a verified command |
Feature index
| # | Feature | Main page | Core surfaces | State (2026-05-23) |
|---|---|---|---|---|
| 1 | AI features | AI Features | AGENTS.md, ai-tools/, 6 native adapters, llms.txt, sitemap-ai.xml, hosted MCP, Mintlify chat assistant | Production with llms.txt + sitemap-ai.xml 47 days stale (root cause: cron-dry-run); 34 local SKILL.md (18 in draft) |
| 2 | UI system | UI System | snippets/components/, snippets/templates/, snippets/composables/, .vscode/*.code-snippets, style.css | Production; 132 registry exports + 37 templates + 8 Tier-1 composables + 312 VS Code snippets; 4-surface count drift (cleanup queue) |
| 3 | Automations | Automations | .github/workflows/, .github/workspace/, operations/scripts/, operations/tests/, .githooks/ | Production (2026-05-22 4-tier composable refactor): 11 workflows + 321 scripts + 18 locked decisions; cron-is-dry-run bug = P0 |
| 4 | Data integrations | Data Integrations | api/, snippets/data/, operations/scripts/integrators/, operations/scripts/generators/content/reference/ | 11 integration families. Contracts pipeline = gold-standard; OpenAPI specs 67 days stale (weakest link); Luma feed silently dead |
| 5 | Adaptive architecture | Adaptive Architecture | operations/governance/config/, operations/scripts/remediators/, .githooks/, lpd repair | 4 of 5 unified surfaces formally ownerless-ready post-D-ACT-10 (1 advisory: github-workspace-governance); 5-stage control loop (detect/explain/repair/verify/record); honest framing |
| 6 | Contributor tools | Contributor Tools | tools/lpd CLI, tools/dev/, tools/editor-extensions/, .githooks/, .vscode/, tools/lib/ | Production. lpd CLI (13 subcommands + 5 group shorthands) + 4 VS Code extensions + scoped preview + 312 snippets |
| 7 | Content writing pipeline | Content Writing | _MY_PROCESS/, CONTENT-WRITING/, Frameworks.mdx, per-tab _workspace/canonical/ | 9-stage project pipeline. 0 of 5 tabs has IA Approved (all stuck at Phase 2). 14 supporting AI skills (18 of 34 in draft) |
| 8 | Checks framework | Checks Framework | master-checks.mdx, 5 per-tab canonical/checks.mdx, prompts under CONTENT-WRITING/Prompts/, 14 skills | 11-phase per-page review pipeline + 9 universal check categories. veracity-pass.md DRAFT – blocks Phase 6 |
| 9 | Gap analysis | Gap Analysis | workspace/reports/repo-ops/, this feature map, the 10 deep-slice audits | Implementation backlog. P0/P1/P2 priorities with file paths + acceptance criteria; refreshed 2026-05-23 |
System map
| Layer | Runtime role | Canonical sources | Derived outputs | Primary gates |
|---|---|---|---|---|
| Navigation and routing | Mintlify site definition (versions, tabs, groups, redirects, branding, route membership) | docs.json | Mintlify site, generated docs indexes, route lists | operations/scripts/validators/content/structure/lint-structure.js, lpd test --staged |
| Content | User-facing docs, internal docs, legacy docs, section workspaces | v2/, docs-guide/, frozen v1/ | docs-index.json, generated catalogs, browser reports | Content validators, page rendering, link audits |
| Components and templates | Shared presentation + authoring primitives | snippets/components/, snippets/templates/, snippets/composables/ | Component registry, public component-library/ tab, VS Code snippets | Component validators, template generator tests |
| Data | Structured data consumed by pages + integrator components | api/, snippets/data/, external source configs | Generated API docs, snapshots, feed data, reference maps | OpenAPI reference audit, freshness checks, data-fetch workflows |
| Operations | Scripts, tests, hooks, CI workflows, repair commands | operations/scripts/, operations/tests/, .github/workflows/, .githooks/, tools/ | Reports, generated governance maps, CI artefacts | Pre-commit, PR CI, scheduled workflows |
| Governance | Machine-readable policy, surface ownership by contract, root allowlist, generated-artefact manifest, approval policy | operations/governance/config/ (6 JSON configs), docs-guide/policies/, docs-guide/frameworks/, docs-guide/standards/, docs-guide/decisions/ | Repo governance maps, root allowlist, compliance reports | Governance validators, approval labels, hook checks |
| AI agent layer | Tool-specific adapters + reusable skills for agents | AGENTS.md, 6 native adapters (.claude/, .codex/, .cursor/, .windsurf/, .augment/, .github/copilot-instructions.md), ai-tools/ai-skills/ | Agent packs, synced Codex skills, skill indexes | Agent-docs freshness, Codex branch-contract checks |
| Content writing pipeline | The 9-stage project pipeline + 11-phase per-page review | workspace/plan/active/_MY_PROCESS/, CONTENT-WRITING/, master-checks.mdx, per-tab canonical/checks.mdx | Approved page drafts, review packets, decisions registry entries | Human gates per phase recorded in tab-status.md |
Three locked-decision registries
The repo carries 32 locked structural decisions across three ID-prefixed registries. All cross-referenced from the unified index atdocs-guide/decisions/registry.md.
| Registry | Lives at | Count | Coverage |
|---|---|---|---|
| Content writing decisions | workspace/plan/active/CONTENT-WRITING/decisions/decision-registry.md | 1 (D-NAV-01) | Cross-tab navigation patterns |
| GitHub Actions + governance decisions | .github/workspace/decisions-log.mdx | 18 (D-ACT-01..10 + D-GOV-01..08) | Workflow architecture, taxonomy, pipeline tags, dispatcher model, 4-tier composable |
| Docs-guide structure decisions | docs-guide/decisions/docs-guide-structure.md | 13 (D-DG-01..13) | docs-guide IA migration; canonical/ retirement; standards/frameworks/policies/decisions/contributing tiers; thin-adapter rule (D-DG-11) |
Current inventory snapshot (live, 2026-05-23)
| Inventory | Count or state |
|---|---|
| docs.json registered v2 routes | 686 |
| Active v2 MDX outside workspace + archive lanes | 1,128 |
| Active GitHub workflows | 11 (6 dispatch-{concern}.yml + 5 interface-governance-*) post-2026-05-22 4-tier refactor |
| Archived workflows | 1 in deprecated/ + 61 in workflows/x-archive/ + contents of .github/x-archive/ (third lane) |
| Active operations scripts | 321 (102 dispatch + 58 integrators + 55 validators + 37 remediators + 31 generators + 25 audits + 8 interfaces) |
| Archived operations scripts | 38 in archive/ + x-archive/ |
| Script JSDoc compliance | 327 of 321 use canonical @purpose (~100%); 45 use retired @category; 4 use retired @domain |
| Active JSX components | 35 active + 24 archived (59 file count); 132 registry exports |
| Templates | 37 across 14 sub-lanes |
| Composables | 8 Tier-1 + 73 per-tab fragments under pages/ |
| VS Code snippets | 312 across 5 .code-snippets files |
| Assets | 236 files (~101.5 MB) |
| AI skills (local SKILL.md) | 34 active + 1 archived; 18 of 34 status: draft |
| AI portable templates | 53 |
| AI portable skill exports | 53 (agent-packs/skills/); manifest registers 1 |
| AI tools registry entries | 317 (ai-tools-registry.json) |
| AI artefacts at root | llms.txt (188 entries) + sitemap-ai.xml (181 URLs, 6 of 10 tabs covered) + robots.txt + humans.txt |
| Native agent adapters | 6 (Claude, Codex, Cursor, Windsurf, Augment, Copilot) + AGENTS.md baseline (119 lines) + .mintlify/Assistant.md |
.claude/references/ library | 25 files, ~2,860 lines, 13 categories |
| docs-guide canonical files | 13 frameworks + 18 policies + 5 standards + 11 features + 4 decisions + 5 contributing + 5 tooling + 6 catalog + 8 docs-library + repo-ops + canonical |
| Locked decisions across 3 registries | 32 total (1 D-NAV + 18 D-ACT/D-GOV + 13 D-DG) |
| Ownerless surfaces (formally contracted) | 8 of 28 in the wider registry |
| Generated artefacts (registered) | 29 in generated-artifacts.json |
Per-tab _workspace/ files | 3,110 across 11 tab subtrees + v2/_workspace root |
Per-tab canonical/checks.mdx files | 5 (gateways, orchestrators, about, delegators, developers1) |
| V2 folder cleanup matrix backlog | 307 rows (235 _workspace + 72 x-deprecated; gateways carries 199) |
| Script footprint audit findings | 4 medium + 20 low (no critical/high) |
| BACKLOG items registered | BL-001..BL-046 (workspace/plan/future/BACKLOG/master-tasks.md) |
Active plans under workspace/plan/active/ | 26 |
Contributor operating loop
- Read the relevant governance entry point before editing:
policies/governance-index.mdxordocs-guide/index.mdx. - Identify the canonical source for the surface being changed (every surface declares it in
operations/governance/config/*.jsonor its policy doc). - Change the source, generator, validator, or policy that owns the behaviour – never the derived output.
- Regenerate derived outputs with the named generator command – never hand-edit.
- Run the smallest relevant validator – usually
lpd test --staged. - If a failure appears, fix the owning source or repair command. Bypasses are governance debt.
- For route or nav work, treat
docs.jsonas production infrastructure. Validate route impact viacheck-docs-path-sync.js+ redirect-integrity hook.
What good looks like
Every major feature should satisfy this contract:| Requirement | Acceptance check |
|---|---|
| Discoverable | The feature has a feature page, framework, policy, catalog entry, or generated registry entry |
| Governed | The canonical source and allowed write paths are documented |
| Validated | A contributor can run a deterministic check locally or in CI |
| Repairable | The repair path is exact and does not depend on private knowledge |
| Bounded | Workspaces, archives, generated files, and public pages are separated by structure and selection helpers |
| Purgeable | Legacy paths have explicit migration, archive, or deletion criteria |
| Dated | Every claim is verifiable by re-running a named command at the date the doc was verified |
repo-governance-surfaces.json (bridge_mode "retired", legacy bridge inventory empty post-D-ACT-10). The remaining surface (github-workspace-governance) is at advisory state. The legacy 8-entry ownerless-governance-surfaces.json is superseded but kept for reference. The Gap Analysis is the queue for promoting the remaining advisory surface to autofix or blocking.
Related pages
Feature deep dives
- AI Features – public AI surfaces + agent runtime + skill system + adapters
- UI System – component library + templates + composables + design tokens + snippets
- Automations – 4-tier composable architecture + 11 workflows + 321 scripts + hook pipeline
- Data Integrations – 11 integration families incl. contracts (gold-standard) + OpenAPI
- Adaptive Architecture – ownerless contract + 5-stage control loop + remediator families
- Contributor Tools –
lpdCLI + scoped preview + VS Code extensions + hooks
Framework deep dives
- Content Writing Pipeline – 9-stage project pipeline + taxonomies + voice + 5 known gaps
- Checks Framework – 11-phase per-page review + 9 universal Cat 1-9 + per-pageType + per-tab variation
- Component Framework Canonical – 6-category taxonomy + 7-tag JSDoc
- Script Framework – type/concern/niche + 11-tag JSDoc
- GitHub Actions Framework – workflow taxonomy + naming convention
- Styles Engineering Guide –
--lp-*design tokens + theme contract - AI Tools Governance – registry + 7-lane model + lifecycle states
Policy deep dives
- Ownerless Governance – the 4-part contract + promotion ladder
- Source of Truth – canonical boundaries per surface
- Infrastructure Principles – gate-layer rule ownership
- Generated Artefact + Hook Governance – 3 classes + commit/hook/CI policies
- Quality Gates – gate-layer map with named tools per tier
- Agent Governance Framework – adapter rules per D-DG-11
- Workspace Lifecycle – TTL rules (30/90 days) + retention enforcement
- Cleanup + Quarantine – conservative deletion discipline
- V2 Folder Governance – non-publishable lane contract
- Governance Index – entry point for all governed surfaces
Standards
- Voice + Copy – canonical voice + UK English + banned words + per-audience extensions + heading rules
- Frontmatter Spec – required + optional frontmatter fields per authority tier
- Naming Conventions – file + folder + script + workflow naming
- Authoring Standard – quality bar + publication gate
Cross-cutting
- Gap Analysis – implementation-ready backlog with P0/P1/P2 priorities (refreshed 2026-05-23)
- Decisions Registry – unified index of all locked decisions (32 total across 3 ID prefixes)
docs-guide/index.mdx– docs-guide overview (the front door)workspace/plan/active/_MY_PROCESS/– page-authoring + checks process canonical sourceworkspace/thread-outputs/repo-consolidation-deep/– 10 file-level slice audits + master consolidation map (~4,400 lines of evidence)