Skip to content

Phase 2: restructure the Concepts (Reference) docs #671

Description

@developerjamiu

Restructures the Concepts section (public label "Reference") into a predictable, findable shape: eight journey-ordered groups, plus a root-level Reference section for true lookups. Legacy content moves to Upgrading/Archive, and duplicated facts get a single home. It ships as seven reader-coherent PRs, and the section rename to "Concepts" happens last.

Acceptance bar (every PR)

Each PR is done only when every page it touches, including pages that mostly stay put, passes:

  • Template conformance: capability pages have a substantive Overview plus action-shaped Operations; reference pages are terse and complete with stable anchors; procedural pages have action-shaped steps, prerequisites, and a verifiable end state.
  • Flow: reads top-to-bottom as a first-timer, with no forward references.
  • Self-contained: every term is explained on first mention; no reliance on an adjacent page having been read.
  • Gap coverage: folds in the relevant open issues and correctness fixes for the area it touches; anything not folded is filed and named in the PR.
  • No information loss: every unit is preserved or explicitly archived; the build and links pass.

PRs

Notes

  • The CLI reference is now auto-generated (#5390), so these PRs link to it rather than rebuild it.
  • Items that need framework-team confirmation are deferred to a later pass so they do not block this work: database seeding (Document database seeding (insert initial data at startup) #651), server role behavior, and the passkey UI. Structural work around them still ships.

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions