​

Docs Guide

Single source of truth for working in this repo. Read the section that matches what you are doing, then follow the pointer to the named framework, policy, or decision.

​

Pick your path

​

Authority tiers

Files in docs-guide/ follow a six-tier precedence model. When two governance docs disagree, the higher tier wins. Every file declares its tier in the authority: frontmatter field. Adapter files (AGENTS.md, .claude/CLAUDE.md, .github/AGENTS.md, .cursor/rules/, .windsurf/rules/, .augment/rules/) point UP into docs-guide/. They surface canonical truth for specific consumers but hold no authority. Any rule stated only in an adapter file is invalid and must canonicalise into a T0–T3 source. Locked by D-DG-11.

​

Source-of-truth model

Where each kind of truth lives. Read the policy for the full boundaries.

​

Frameworks and standards by concern

The most-referenced surfaces, organised by what you are about to do. Citation counts will be auto-injected once the index generator lands; for now, this list is curated.

​

Decision rules – read before doing X

Before writing or moving any governed file, read the listed documents.

​

Before writing a component

1. Component framework – category taxonomy, 7-tag JSDoc header
2. File placement – folder placement rules
3. docs-guide/canonical/collation-data/Mintlify/mintlify-repo-best-practices.md – platform constraints

​

Before writing a script

1. Script framework – type, concern, niche taxonomy; 11-tag JSDoc header
2. File placement – folder placement rules

​

Before writing a docs page

1. Content writing pipeline – pipeline phases, page taxonomy
2. Voice rules – per-audience voice rules
3. Frontmatter spec – required frontmatter fields
4. docs-guide/canonical/collation-data/Mintlify/mintlify-repo-best-practices.md – Mintlify platform constraints

​

Before writing a workflow

1. GitHub Actions framework – type, concern taxonomy; naming convention; pipeline tags
2. .github/workspace/decisions-log.mdx – locked decisions D-ACT-01 through D-ACT-10
3. operations/governance/config/governance-approval-policy.json – required approval labels

​

Before moving files

1. Repo structure – root folder structure (LOCKED)
2. File placement – component and script placement
3. Docs guide structure policy – docs-guide folder rules
4. Run the /propagate skill for any file with more than five incoming references

​

Before adding or changing a decision

1. Decisions registry – master index of all decision logs
2. Docs guide structure decision log – example of the locked format
3. ID grammar: D-{SCOPE}-{NN} where SCOPE is one of NAV, ACT, GOV, SCRIPT, OWN, CONTENT, ORCH, GW, DG, GLOS

​

Governed surfaces

Major areas of this repo are governed. Each has a canonical framework, a root path, and a freshness status. The full live count is auto-generated at repo-governance-map. The full governance map is auto-generated at repo-governance-map. Run node operations/scripts/generators/governance/generate-governance-map.js --check to verify all folders are governed and no frameworks are stale.

​

Did you mean

Common misroutes. If you landed here looking for one of these, follow the pointer.

​

Update rules

1. Update manual docs when behaviour, process, canonical boundaries, or architecture changes. Bump lastVerified on save.
2. Regenerate generated catalogs when scripts, workflows, or templates change:
   • node operations/scripts/generators/governance/catalogs/generate-docs-guide-indexes.js --write
   • node operations/scripts/generators/governance/catalogs/generate-docs-guide-pages-index.js --write
   • node operations/scripts/generators/governance/catalogs/generate-docs-guide-components-index.js --write
   • node operations/scripts/generators/components/library/generate-ui-templates.js --write
   • node operations/tests/unit/script-docs.test.js --write --rebuild-indexes
   • node operations/scripts/validators/content/structure/enforce-generated-file-banners.js --check
3. Re-run the docs audit pipeline when docs, scripts, reports, or routing paths change:
   • node operations/scripts/dispatch/governance/repo/repo-audit-orchestrator.js --mode static --scope full
   • node operations/scripts/integrators/ai/agents/cross-agent-packager.js --agent-pack all
4. Keep README.md high-level. Link to canonical docs-guide pages for deep detail.
5. Keep generator scripts, generated outputs, and downstream consumers in sync whenever a catalog path or title changes. Use the /propagate skill on any move or rename of a file with more than five incoming references.

​

Standards index

Published authoring and style standards in docs-guide/standards/.

​

Decision registry

All decision registries are indexed at decisions/registry. Per-domain registries live under workspace/plan/active/<DOMAIN>/decisions/ and are cross-referenced from the master index. The decisions pipeline (D-DG-01 ID grammar plus generator and validator) is documented in decisions/docs-guide-structure.

​

Related

• Root orientation: README.md
• Public docs guide: v2/resources/documentation-guide/
• Contributor procedures: docs-guide/contributing/
• Test matrices and CI behaviour: operations/tests/README.md
• Approved redesign plan: ~/.claude/plans/hmm-so-there-needs-tender-valley.md