Skip to content

docs: restructure navigation into five top-level sections (Start / Build / Operate / Security / Internals)#31

Merged
abrichr merged 1 commit into
mainfrom
docs/restructure
Jul 20, 2026
Merged

docs: restructure navigation into five top-level sections (Start / Build / Operate / Security / Internals)#31
abrichr merged 1 commit into
mainfrom
docs/restructure

Conversation

@abrichr

@abrichr abrichr commented Jul 20, 2026

Copy link
Copy Markdown
Member

What

Reorganizes docs.openadapt.ai into the review's five top-level sections and relinks the nav accordingly. This is an organize-what-exists change — no page content was rewritten and no new docs were invented.

Five-section structure

Section Scope Pages moved in
Start install, first success, quickstart get-started overview, desktop/install, first-workflow, what-you-get
Build record → compile → lint → certify, effect verifiers, identity concepts overview + all how-to guides, demonstration-compiler, workflow-ir, record-your-app, induce-a-program, multi-trace-induction, parameters-and-secrets, capability-ladder, policy-and-certification, policy-and-certify, effect-verification, identity-gate
Operate run, halt/teach, on-prem, hosted lifecycle, monitoring run-a-deployment, run-reports, halt-learn-loop, self-healing, durable-runtime, deploy-on-prem, vlm-appliance, hosted, connect-to-cloud, troubleshooting
Security LIMITS / claims, trust boundary, PHI what-works-today (qualification evidence), regulated-execution, security-and-data-handling, security-review
Internals architecture, package registry, contributing/governance substrate-model, deployment-matrix, backends, reference/* (CLI, compatibility, deployment-config, bundle-format, configuration), ecosystem catalog, documentation-governance, what's-new, changelog

Notes

  • Pages keep their existing on-disk paths, so every cross-link, the substrate-evidence copy tests, and the product-docs contract markers are preserved.
  • scripts/validate_docs.py's package-catalog guard previously required the ecosystem catalog under a section literally named Reference; it now accepts Reference or Internals, keeping the no-package-first-IA intent while matching the new section name.
  • The "seeking design partners" honesty and scoped substrate evidence are untouched; no customer names introduced.

Gates

  • mkdocs build --strict — pass
  • python scripts/validate_docs.py — "Validation passed!"
  • pytest tests/ — 64 passed

Reorganize the documentation IA into the review's five top-level sections:
Start, Build, Operate, Security, Internals. Every existing page keeps its
on-disk path (get-started/, concepts/, guides/, reference/, desktop/,
ecosystem/); only the nav grouping changes, so all content, cross-links,
and page-path-based tests are preserved.

Section mapping:
- Start: install, first success, quickstart (get-started + desktop/install)
- Build: record -> compile -> lint -> certify, effect verifiers, identity
- Operate: run, halt/teach, on-prem, hosted lifecycle, monitoring
- Security: qualification/claims, trust boundary, PHI/data handling
- Internals: architecture, package/repository registry, docs governance

validate_docs.py's package-catalog guard now accepts the ecosystem catalog
under the renamed Internals section (previously hardcoded "Reference"),
preserving its no-package-first-IA intent. mkdocs build --strict,
validate_docs, and all 64 tests pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@abrichr
abrichr merged commit 93e3ce5 into main Jul 20, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant