docs: track 0.18.1 — every page says what 0.18.1 does, with release notes and an upgrade guide for 0.15.1–0.18.1

[fas89]

What this changes

The docs claimed to track CLI 0.15.3. pip install data-product-forge gives 0.18.1. Content was last written for 0.15.0: 0.15.1–0.15.3 only bumped version strings, and 0.16.0–0.17.0 had no docs pass at all. This PR brings every existing page up to what 0.18.1 does, and adds the release notes and upgrade guide that were missing.

• Pin.
  • cli-version.json moves to 0.18.1.
  • quickstartScaffoldVersion moves to 0.7.5, because fluid init --quickstart now emits it.
  • Schema 0.7.5 is stable and 0.7.6 is the preview.
• New pages.
  • RELEASE_NOTES_0.16.0.md covers 0.15.1–0.16.2, and RELEASE_NOTES_0.17.0.md covers 0.16.3–0.17.0. Both use the 0.15.0 page's shape: headline, who should upgrade, checklist, per-area changes.
  • upgrading.md is a standing upgrade guide, with a per-version checklist from 0.15.x to 0.18.1 and how to check each step.
  • RELEASE_NOTES_0.18.0.md gains the 0.18.1 fix.
• CLI reference (docs/cli/**).
  • Each command was compared with --help on 0.18.1. Missing flags and subcommands are added, for example diff --state-backend/--workspace-dir/--no-state-drift, schedule-sync --delete-scope, generate ci's pipeline defaults and contract digest. Wrong defaults, choices and outputs are corrected.
  • Behaviour changes are written in:
    • plan/apply mode and env binding;
    • the per-provider state key and its migration;
    • the drift gate reading the live target and the apply's OpenTofu state;
    • env-scoped Airflow DAG ids;
    • Command Center publish: org resolution, private by default, last-writer-wins per contract;
    • apply run reporting.
• Providers.
  • AWS:
    • bucket landing and the region pin (opentofu_region_moved);
    • Lake Formation column grants, bucketPolicy, and admins being authoritative;
    • KMS plus lifecycle.expire;
    • masking at landing;
    • verify on Glue/Athena.
  • GCP: governance parity, which was measured against real BigQuery, Cloud KMS and Data Catalog on 4 Oct 2026 on 0.18.0, matching forge-cli docs/governance-parity.md (#694). This covers dataset grants as iam_member, policy tags (with BigQuery's live refusal wording), CMEK, DAY-partition retention and sovereignty failing closed.
  • Local and Snowflake: the 0.18 DuckDB sandbox.
• Concepts, recipes, walkthroughs, advanced, SDK.
  • consumes[] examples now validate.
  • The governance enforcement matrix says per provider what is enforced, what is only declared, and what verify checks.
  • The 11-stage pipeline walkthrough follows the generated bundle chain.
  • Environment variables were re-derived from the code.
  • The error reference keeps every anchor the CLI prints.
• Truth over tidiness. Where 0.18.1 behaves badly, the page says what it actually does. Examples:
  • fluid policy-apply changes no permissions;
  • the quickstart's local apply writes a placeholder file;
  • validate --probe is accepted and ignored.
• Not changed. No page was moved or renamed, and no heading behind a CLI-printed anchor changed. Since 0.15.2, the CLI prints links into this site (fluid_build/_errors.py::_DOC_ROUTES), so those URLs are a contract.

A second PR, "the story", follows once this merges. It adds the contract fragments concept page, environments, workspaces and state, one contract on two clouds, the generated contract field reference, and the reorganised navigation.

Tested

• Gates, run locally on the branch:
  • npm run docs:build: exit 0.
  • node scripts/check-dist-links.mjs: clean, 115,736 absolute references across 227 built pages.
  • scripts/check_cli_docs.py against an installed data-product-forge==0.18.1: every check OK, including the flag oracle over 1,226 documented fluid invocations and the version sweep.
  • scripts/check_providers.py: OK.
• Live. The built site was served under /forge_docs/, as GitHub Pages serves it, and walked in a browser:
  • All 37 docs URLs and anchors that 0.18.1 prints in its own output resolve, including advanced/typed-cli-errors.html#validation-schema, #capability-negotiation, #connectivity-secrets, #pipeline-operations and #governance.
  • No console errors.
  • At phone width there is no horizontal scroll on the widest new pages.
• Commands and output. Every command a page tells you to run was run on 0.18.1, or checked against the v0.18.1 source where it needs a cloud. Example output is real.
• Method. 23 units wrote the pages. Each unit's diff then went through an adversarial claim-by-claim review and a fix round. A final pass applied cross-page handoffs.

Security review

• A dedicated review found no HIGH issues. Every MEDIUM and LOW in this PR is fixed:
  • mTLS is no longer described as binding caller identity on the MCP output port; only FLUID_MCP_AUTH_MODE=jwt does.
  • Jenkins credentials go through withCredentials, not agent-wide properties.
  • A warning that any MCP client can set allow_metadata_service.
  • Dependency-confusion warnings for extra pip indexes.
  • GitHub Actions OIDC trust is scoped to the repo and environment, and id-token: write is granted on deploy jobs only.
  • A danger box on the legacy "universal pipeline" Jenkinsfile.
  • Real third-party domains used as placeholders are replaced.
• gitleaks over the branch reports no leaks.

Prior art

• The page types follow Diátaxis.
• The upgrade guide takes its shape from dbt's "Upgrading to vX" guides.

Follow-ups (not in this PR)

• CLI defects found while verifying the docs have gone to the maintainer as a separate list. They are not filed here.
• The repo-root examples/ directory still uses company.com / yourcompany.com in sample contracts.