docs: journey-first documentation refactor

CONTRIBUTING.md

@@ -55,6 +55,18 @@ cascade owns the third-party action pins it emits into generated workflows, and
 - Generated files are targets, never sources: a pin (or any other value) is read from the manifest and written into generated output, never read back out of a generated file. This keeps generation a pure, offline function of the manifest, which is what makes a regenerate reproducible and a diff meaningful.
 - cascade's own self-heal companion is generated, not hand-written. `.github/workflows/pin-reconcile.yaml` is produced by the same reconcile generator that emits a downstream user's companion, in its own-repo variant, and is drift-locked byte-for-byte by a test so a hand-edit fails the suite. The own-repo variant differs from the user emission in exactly three ways: it installs the latest non-prerelease cascade release (never an rc or a draft, so cascade's own CI cannot self-install a prerelease), it scans both the workflow and composite-action trees for a moved pin, and it commits the regenerated workflows alongside the updated `action_pins.yaml`. Change the generator and regenerate the file; never edit the workflow by hand.
 
+## Documentation quality
+
+A change that alters behavior, CLI surface, flags, config or manifest fields, generated output, or the release flow updates the affected docs in the same pull request: the docs site under `docs/src/content/docs/`, the root `README.md`, and any other affected Markdown file. The docs site follows these rules:
+
+- Every page is typed to one Diataxis mode (tutorial, how-to, reference, or explanation) and stays in that mode.
+- Depth is layered: the common path a typical reader needs comes first; edge cases, the full field surface, and advanced options move into a clearly labeled later section.
+- Each concept is single-sourced on exactly one page. Every other page that touches it links there instead of restating it.
+- A manifest field's emission status ("emitted", "validated-only", or "reserved") is stated accurately wherever the field is documented. Get this wrong and the reference has failed its one job.
+- Every page carries a prerequisite and next-step link, so a reader always knows what to read before and after.
+
+Stale docs fail review.
+
 ## Reporting bugs
 
 Open an issue with the manifest config, the generated workflow (if relevant), and what you expected versus what happened. A minimal reproduction helps a lot.

SECURITY.md

@@ -9,7 +9,7 @@
 
 The latest release line is the active one. Only the most recent release receives security patches. Upgrade to the latest release to stay covered.
 
-The schema-version compatibility policy (which CLI versions read which manifest versions) is documented separately in [versioning and schema compatibility](https://stablekernel.github.io/cascade/versioning/).
+The schema-version compatibility policy (which CLI versions read which manifest versions) is documented separately in [versioning and schema compatibility](https://stablekernel.github.io/cascade/reference/versioning/).
 
 ## Reporting a vulnerability
 
@@ -33,4 +33,4 @@ We follow [coordinated disclosure](https://en.wikipedia.org/wiki/Coordinated_vul
 
 Cascade is a build-time tool that generates GitHub Actions workflows you commit and review in your own repository. The generated workflows run under your own runners, branch protection, and environment gates, and cross-repo coordination uses a same-organization, shared-token model where a dispatch token you provision is the trust boundary. Deploying cascade safely is therefore a shared responsibility between cascade and your organization's GitHub and cloud configuration.
 
-See the [security and hardening guide](https://stablekernel.github.io/cascade/security/hardening/) for the full model and a step-by-step hardening checklist.
+See the [security and hardening guide](https://stablekernel.github.io/cascade/security/) for the full model and a step-by-step hardening checklist.

docs/astro.config.mjs

@@ -68,27 +68,40 @@ export default defineConfig({
           attrs: { name: 'twitter:card', content: 'summary_large_image' },
         },
       ],
-      // Sidebar order mirrors the previous MkDocs nav, with the decision-aid
-      // "Why Cascade" page first so readers can self-qualify before onboarding.
+      // Sidebar mirrors the journey: orient (Why Cascade), start (mental model +
+      // tutorial), task guides (operator how-tos), reference (exhaustive lookup),
+      // security, then internals (contributor depth). Every label pairs with its
+      // page's `title` frontmatter.
       sidebar: [
-        { label: 'Why Cascade', link: '/comparison/' },
-        { label: 'Stage Graph', link: '/stage-graph/' },
-        { label: 'Getting Started', link: '/getting-started/' },
-        { label: 'Adoption Guide', link: '/adoption/' },
-        { label: 'Manifest Reference', link: '/configuration/' },
-        { label: 'Callback Contract', link: '/callback-contract/' },
-        {
-          label: 'Workflows',
-          items: [{ label: 'Overview', link: '/workflows/' }],
-        },
-        { label: 'CLI Reference', link: '/cli-reference/' },
-        { label: 'Local Simulation', link: '/simulate/' },
-        { label: 'Architecture', link: '/architecture/' },
-        { label: 'How it is tested', link: '/testing/' },
-        { label: 'Feature coverage matrix', link: '/coverage-matrix/' },
-        { label: 'Release orchestration', link: '/release-orchestration/' },
-        { label: 'Security & Hardening', link: '/security/hardening/' },
-        { label: 'Versioning & Schema', link: '/versioning/' },
+        { label: 'Why Cascade', link: '/start/why-cascade/' },
+        { label: 'Start here', items: [
+            { label: 'How Cascade works', link: '/start/how-it-works/' },
+            { label: 'Getting started',   link: '/start/getting-started/' },
+        ]},
+        { label: 'Task guides', items: [
+            { label: 'Adopt an existing pipeline', link: '/guides/adopt/' },
+            { label: 'Add or change environments', link: '/guides/environments/' },
+            { label: 'Promote a release',          link: '/guides/promote/' },
+            { label: 'Run a hotfix',               link: '/guides/hotfix/' },
+            { label: 'Roll back an environment',   link: '/guides/rollback/' },
+            { label: 'Simulate and verify',        link: '/guides/simulate-and-verify/' },
+            { label: 'Coordinate multiple repos',  link: '/guides/multi-repo/' },
+            { label: 'Visualize the pipeline',     link: '/guides/visualize/' },
+        ]},
+        { label: 'Reference', items: [
+            { label: 'Manifest',            link: '/reference/manifest/' },
+            { label: 'Callback contract',   link: '/reference/callbacks/' },
+            { label: 'CLI',                 link: '/reference/cli/' },
+            { label: 'Generated workflows', link: '/reference/generated-workflows/' },
+            { label: 'Versioning & schema', link: '/reference/versioning/' },
+        ]},
+        { label: 'Security & hardening', link: '/security/' },
+        { label: 'Internals', items: [
+            { label: 'Architecture',            link: '/internals/architecture/' },
+            { label: 'How Cascade is tested',   link: '/internals/testing/' },
+            { label: 'Feature coverage matrix', link: '/internals/coverage-matrix/' },
+            { label: 'Release orchestration',   link: '/internals/release-orchestration/' },
+        ]},
       ],
     }),
   ],