docs: scaffold guide and API indexes

2026-08-10 16:06:42 -05:00
parent 48531755eb
commit d210c2d7ea
7 changed files with 220 additions and 0 deletions
@@ -0,0 +1,45 @@
+# Administrator Guide
+
+> **Status:** Scaffold only. No legacy page has been promoted into this book yet.
+
+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) — existing navigation is transitional and still contains legacy paths.
+- [Product requirements](../PRD.md) — normative requirements, currently marked draft.
+
+## 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.          | Scaffold only.                                              |
+| [`security/`](security/README.md) | Authentication, authorization, SSO, secrets, and security controls. | Scaffold only; `SSO-PROVIDERS.md` is a migration candidate. |
+| `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.
+
+## Migration backlog — not current operator guidance
+
+These are source candidates, not verified runbooks:
+
+- [`SSO-PROVIDERS.md`](../SSO-PROVIDERS.md) — partially verified; its documented web feature flags conflict with current dynamic provider discovery.
+- [`PERFORMANCE.md`](../PERFORMANCE.md) — historical performance evidence, not an operational SLO or runbook.
+- [`_old_structure/guides/admin-guide.md`](../_old_structure/guides/admin-guide.md) — historical source; verify claims before promotion.
+- [`_old_structure/guides/deployment.md`](../_old_structure/guides/deployment.md) — historical source; verify commands and deployment assumptions before promotion.
+
+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]]
@@ -0,0 +1,19 @@
+# Security
+
+> **Status:** Scaffold only. Security pages are not migrated yet.
+
+This chapter will contain authentication, authorization, SSO, secrets, RBAC, and security-control guidance for administrators.
+
+## Planned pages
+
+- `sso-providers.md` — migrate and verify [`docs/SSO-PROVIDERS.md`](../../SSO-PROVIDERS.md).
+- `secrets.md` — document secret handling after source/configuration verification.
+- `rbac.md` — document roles and permissions from the canonical implementation.
+
+Do not treat the root SSO document as current guidance until the dynamic provider-discovery behavior and all provider claims have been reconciled.
+
+## Related
+
+- [`Administrator guide`](../README.md)
+- [`API documentation`](../../API/README.md)
+- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]