docs: the story — contract fragments, environments and two clouds, a generated contract reference, and navigation a reader can follow

[fas89]

Re-cut onto main after #141 merged: one commit whose tree is exactly the reviewed branch (the delta was compared byte-for-byte).

What this changes

#141 makes every existing page correct for 0.18.1. This PR adds what the site never had: a story a reader can follow, from installing the CLI to running a governed product on two clouds. It also adds the explanation pages behind that story.

New pages

• concepts/fragments.md — contract fragments.
  • Why you would split a contract, and the layout fluid split writes.
  • The split ↔ bundle round trip, and which commands read a fragment root directly.
  • --env overlays apply after $ref resolution.
  • CI: bundle once, then pass the bundle on.
  • Digests on fragment layouts, what catalogs receive, and why an external JSON Schema validator must validate the bundled document.
  • It builds on concepts/contract-refs.md (docs: 0.18.0 contract confinement — $ref root, DuckDB sandbox, contract-loading API #139) for how a single $ref resolves rather than repeating it. cli/split.md and cli/bundle.md become complete references that link to it.
• Environments and clouds. concepts/environments-and-overlays.md, concepts/workspaces.md (fluid.workspace.yaml), concepts/state.md (where OpenTofu state lives and how it is keyed), and concepts/governance-parity.md. Governance parity is stated as measured: GCP against real BigQuery, Cloud KMS and Data Catalog on 4 Oct 2026, matching forge-cli docs/governance-parity.md (#694). recipes/one-contract-two-clouds.md is a runnable how-to. The switch-clouds pages now give the measured claim instead of "one line".
• Contract field reference (reference/).
  • Generated from the schemas bundled in the pinned CLI by scripts/gen_contract_reference.py, and deterministic: 0.7.5 stable, plus the 0.7.6 preview delta.
  • cli-consistency.yml runs --check, so a CLI bump that changes a schema fails CI until the pages are regenerated. The job stays read-only.
• Story pages. concepts/semantic-layer.md, concepts/command-center.md, concepts/federation.md and recipes/evolve-a-live-product.md.

Navigation and front door

• The navbar and sidebar are reorganised by Diátaxis: Get started, Tutorials, How-to, Concepts in reading order, Reference, Providers, Operate, Releases. No page moved or was renamed, because the CLI prints links into this site.
• Every page is reachable: 234 pages, 0 unreachable.
• The home page is rewritten.
• Getting Started is a tutorial run end to end on 0.18.1 with data-product-forge[local], and all its output is real. It says why it does not use --quickstart: on 0.18.1 the quickstart's local apply writes a placeholder file.
• There is a new walkthrough index.
• The concepts, recipes and advanced indexes are rewritten.
• Existing pages link into the new story pages.

Tested

• npm run docs:build exits 0.
• node scripts/check-dist-links.mjs: Clean, 137,770 references across 242 built pages.
• scripts/check_cli_docs.py against data-product-forge==0.18.1: all OK, including the flag oracle over every documented fluid invocation.
• scripts/check_providers.py OK; scripts/gen_contract_reference.py --check OK.
• Live: I served the built site under /forge_docs/ and walked it in a browser.
  • Every docs URL and anchor 0.18.1 prints, and every new page, resolves.
  • No console errors.
• The tutorial and recipes were run on 0.18.1 where a cloud isn't needed. Cloud-only paths were checked against the v0.18.1 source.

Security review

A dedicated review of this delta found one HIGH, now fixed. The Workload Identity Federation setup lacked an attribute condition and a role-scoped principalSet, which would let any AWS role in the account impersonate the deploy service account. Also fixed:

• Real third-party domains and globally-namespaced bucket names replaced with fail-closed placeholders such as <your-domain> and <your-state-bucket>.
• Federation token handling.
• Command Center credentials in CI.
• The workspace root and the DuckDB sandbox.
• State bucket protection.
• KMS and Data Catalog admin scope.
• PII aggregates.
• verify --strict in CI.
• What OpenTofu install verification actually checks.

gitleaks reports no leaks.

Prior art

• Fragments: Redocly CLI's split/bundle file management, the closest equivalent for multi-file OpenAPI.
• Information architecture: Diátaxis.