Docs Guide Structure Policy

Canonical policy for the docs-guide/ folder structure, authority tiers, naming conventions, and generated-file rules.

Docs Guide Structure Policy

Defines what belongs in docs-guide/, how it is organised, the authority tiers that govern conflict resolution, and the rules that apply to each content type.

Scope

In scope	Out of scope
All files and folders under docs-guide/	v2/ content pages
Authority tier model and frontmatter contract	snippets/ component library
Naming conventions for catalog, policy, framework, standard, decision, and reference files	AI adapter files (.claude/, .cursor/, .windsurf/, .augment/)
Generator freshness, validator coverage, and CI pipeline rules	Root-level .allowlist governance (see root-allowlist-governance.mdx)
_workspace/ usage within docs-guide/	operations/governance/config/ (script-consumed registries)

Authority Tiers

docs-guide/ files are governed by a six-tier precedence model declared in the mandatory authority: frontmatter field. When two governance docs conflict, the higher tier wins.

Tier	Folder	Authority	Conflict resolution
T0	decisions/	Locked precedent with IDs and supersession chains	Beats every other tier
T1	policies/	Enforced rules, prohibited actions, gate-owned controls	Beats frameworks, standards, contributing, reference
T2	frameworks/	Subject models, taxonomies, lifecycles	Beats standards, contributing, reference
T3	standards/	Rules about form (voice, frontmatter, naming)	Beats contributing, reference
T4	contributing/	Procedures (how to do work)	Beats reference
T5	reference/, catalog/	Look-up only, never normative	Always loses to higher tiers

Adapter files (AGENTS.md, .claude/CLAUDE.md, .github/AGENTS.md, IDE 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 be canonicalised into a T0–T3 source.

Locked by D-DG-01.

Canonical Structure

docs-guide/
├── index.mdx              ← single landing page (replaces source-of-truth-guide and governance-index)
├── GOVERNANCE.md          ← root governance marker (YAML-front, generated by generate-governance-map.js)
├── standards/             ← T3: voice, frontmatter, naming, authoring rules
├── frameworks/            ← T2: subject models (component, script, content, page taxonomy, etc.)
├── policies/              ← T1: enforced rules; each policy declares consumers and validator
├── decisions/             ← T0: locked precedent with IDs and supersession chains
├── contributing/          ← T4: contributor and agent procedures, onboarding, governance quickstart
├── reference/             ← T5: descriptive look-up surfaces (no rules)
│   ├── features/          ←   feature, system, and architecture maps
│   ├── tooling/           ←   CLI, dev tools, ai-tools, reference maps (badges, icons)
│   ├── repo-ops/          ←   enforcement maps, repo-governance maps, secrets, config registries
│   ├── pipelines/         ←   pipeline concern docs (formerly docs-library)
│   ├── external/          ←   external platform reference (mintlify best-practices, etc.)
│   └── internal-glossary.mdx  ← internal contributor and agent terminology, derived from corpus
├── catalog/               ← auto-generated catalogs only; do not edit manually
└── _workspace/            ← scratch, drafts, archive; not in nav; TTL-governed

No other top-level subdirectories are permitted without an explicit superseding decision in decisions/docs-guide-structure.md.

Locked by D-DG-02. Migration paths from the previous structure are recorded in D-DG-03 (features/tooling/repo-ops/docs-library merge into reference/), D-DG-04 (canonical/ retired), and D-DG-05 (config/ moved to operations/).

Rules

1. Top-level structure is locked. New top-level subdirectories under docs-guide/ require a superseding decision (D-DG-NN) in decisions/docs-guide-structure.md before they can be created.

2. No 0-byte stubs. Placeholder files with no content are not permitted. A file at a nav path must contain real content or must not exist.

3. One canonical file per subject. When a framework and a policy address the same subject, the framework holds the model and the policy holds the enforcement. Subject-level duplicates are prohibited; the contract validator flags them.

4. Generated files must not be manually edited. All files in docs-guide/catalog/ and any file with maintenance: generated frontmatter are auto-generated. They carry a generated-file-banner:v1 comment block identifying their generator script. Manual edits are overwritten on the next run.

5. Generated files must stay current. If a generator’s source input changes (workflows, templates, docs.json, registries, surfaces JSON), the corresponding output must be regenerated before the PR merges. The catalog freshness CI workflow enforces this.

6. Naming suffix discipline. Follow the suffix pattern for each section:

   • catalog/ files: <subject>-catalog.mdx
   • policies/ files: <subject>-policy.mdx
   • frameworks/ files: <subject>-framework.mdx
   • standards/ files: <subject>-standard.mdx or descriptive (e.g. voice-and-copy.mdx)
   • decisions/ files: <subject>.md (decision logs are MD, not MDX); index.mdx is the master index
   • contributing/ files: <subject>.mdx (descriptive)
   • reference/ files: <subject>-map.mdx, <subject>.mdx, or descriptive
   • The -governance.mdx suffix is retired in favour of -policy.mdx or -framework.mdx per authority tier (D-DG-09).

7. No -index.mdx naming for hand-maintained content. Use -catalog.mdx for generated inventories; descriptive names for hand-maintained pages; index.mdx is reserved for folder-level entry points (e.g. decisions/index.mdx).

8. Archive before delete. Files being removed from navigation move to _workspace/archive/ with a 90-day TTL before permanent deletion, unless they are 0-byte stubs (which may be deleted immediately). High-cite files (>5 incoming references) require /propagate skill execution before move or delete.

9. _workspace/ is not a nav path. docs-guide/_workspace/ must never appear in docs.json. It is covered by .mintignore and every page under it carries noindex: true frontmatter.

10. Frontmatter contract is mandatory. Every file in docs-guide/ (excluding _workspace/ and catalog/) must declare title, description, authority, consumer, maintenance, status, lastVerified, owner. Conditional fields apply per authority tier. Enforced by check-docs-guide-contract.js (D-DG-07).

11. Adapter files cannot hold authority. Rules stated only in AGENTS.md, .claude/CLAUDE.md, .github/AGENTS.md, .cursor/rules/, .windsurf/rules/, or .augment/rules/ must canonicalise into a T0–T3 source. Adapter files are pointer-only delegates with length caps enforced by check-adapter-parity.js (D-DG-11).

Enforcement

Status legend: Live = wired today. Planned (Phase N) = scheduled in the docs-guide redesign plan and not yet enforcing.

Mechanism	Trigger	Script / Tool	Status
CI check – catalog freshness	PR to docs-v2 or main	.github/workflows/validator-maintenance-check-catalogs.yml	Live
CI generate – catalog auto-update	Push and dispatch	.github/workflows/generator-maintenance-generate-catalogs.yml	Live
CI dispatch – catalog repair	Manual dispatch	.github/workflows/dispatch-maintenance-check-catalogs.yml	Live
Scheduled drift – governance map	Schedule + dispatch	.github/workflows/validator-governance-check-governance-map.yml	Live
Scheduled drift – data freshness	Schedule + dispatch	.github/workflows/audit-health-scan-data-freshness.yml	Live
Pre-commit – file deletion guard	Staged deletion of any governed file	.githooks/pre-commit (deletion gate)	Live
CI check – frontmatter contract	PR to docs-v2 or main	operations/scripts/validators/governance/compliance/check-docs-guide-contract.js	Planned (Phase 2)
CI check – decision registry	PR + daily	operations/scripts/validators/governance/compliance/check-decisions-registry.js	Planned (Phase 4)
CI check – policy consumers	PR touching policies/** or standards/**	operations/scripts/validators/governance/compliance/check-policy-consumers.js	Planned (Phase 7)
CI check – adapter parity	Pre-push + PR touching adapter files	operations/scripts/validators/governance/ai/check-adapter-parity.js	Planned (Phase 9)
CI check – canonical citation	PR open / sync	operations/scripts/validators/governance/compliance/check-canonical-citation.js	Planned (Phase 9)

Exceptions

• docs-guide/_workspace/ – exempt from frontmatter contract and naming rules; governed by workspace-lifecycle-policy.mdx.
• docs-guide/catalog/ – files are generated and exempt from consumers: blocks; their generator: frontmatter is mandatory instead.
• Legacy files in _workspace/archive/ during their 90-day TTL window are exempt from naming enforcement.

Related

• Decisions registry
• Docs guide structure decision log
• Workspace lifecycle policy
• Generated artifact and hook governance
• Root allowlist governance
• V2 folder governance
• Frontmatter standard
• Naming conventions
• Ownerless governance