docs: establish canonical documentation architecture (#1210)

2026-08-13 17:56:13 +00:00
parent f82307c4dc
commit 7a6fb024b4
241 changed files with 4722 additions and 1579 deletions
@@ -0,0 +1,50 @@
+# 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/`](../USER-GUIDE/); implementation and contributor material belongs in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
+
+## Start here
+
+- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
+- [Documentation sitemap](../SITEMAP.md) — resolvable current navigation and authority-gated migration summary.
+- [Product requirements](../PRD.md) — normative requirements, currently marked draft.
+- [Operations index](operations/README.md) — current local procedures and explicitly held operational outlines.
+- [Security index](security/README.md) — 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/`](operations/README.md) | Health, observability, routine operation, and maintenance.          | Local upgrade/recovery is current; connector lease operations are held. |
+| [`security/`](security/README.md)     | 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`](../SITEMAP.md) in the same migration slice.
+
+## Evidence — not current operator guidance
+
+- [`P8-003 performance report`](../reports/qa/p8-003-performance-optimization.md) — 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](../reports/documentation/2026-08-10-docs-catalog-audit.md) 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.
+
+## Related
+
+- [[README|Documentation contract]]
+- [[PRD|Product requirements]]
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]