veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
kind, status
| kind | status |
|---|---|
| guide | active |
Administrator Guide
Status: Partially migrated. Current SSO and local upgrade/recovery procedures are available; held procedures are labeled non-operative.
This book is the canonical home for installation, configuration, deployment, routine operations, security controls, incident response, and recovery. User workflows belong in USER-GUIDE/; implementation and contributor material belongs in DEVELOPER-GUIDE/.
Start here
- Documentation atlas — placement rules and source-of-truth boundaries.
- Documentation sitemap — resolvable current navigation and authority-gated migration summary.
- Product requirements — normative requirements, currently marked draft.
- Operations index — current local procedures and explicitly held operational outlines.
- Security index — current SSO provider configuration.
Chapter map
| Chapter | Scope | Status |
|---|---|---|
installation/ |
Prerequisites, installation, and first deployment. | Scaffold only. |
configuration/ |
Environment, provider, tier, and runtime configuration. | Scaffold only. |
deployment/ |
Topologies, rollout, migration, and upgrade procedures. | Scaffold only. |
operations/ |
Health, observability, routine operation, and maintenance. | Local upgrade/recovery is current; connector lease operations are held. |
security/ |
Authentication, authorization, SSO, secrets, and security controls. | SSO provider guide is current; other pages are planned. |
recovery/ |
Incident response, backup, rollback, and recovery. | Scaffold only. |
Every promoted page must be added to this index and to SITEMAP.md in the same migration slice.
Evidence — not current operator guidance
P8-003 performance report— historical performance evidence; implementation alignment is partial, and production metrics remain unverified. It is not an operational SLO or runbook.
Migration backlog — not current operator guidance
These are source candidates, not verified runbooks:
_old_structure/guides/admin-guide.md— quarantined historical source; verify claims before promotion._old_structure/guides/deployment.md— quarantined historical source; deployment commands and assumptions remain held.- See the documentation catalog for file-level dispositions.
Do not treat a migration candidate as current until its commands, paths, permissions, and safety status are checked against source and tests.
Authoring boundary
New administrator documentation belongs under one of the chapter directories above. Operationally sensitive pages must identify prerequisites, ownership, source-of-truth dependencies, and whether any procedure is current, illustrative, held, or non-operative.