[fas89]

Summary

Documents forge-cli #808. Under --mode amend-and-build or replace-and-build, fluid apply now checks that --build-id names one of the contract's builds[].id, right after the build-id check from #803. Ids match exactly, case and spaces included, as in the build runner. The check runs before the apply hooks, tofu and any build. An id that matches no build is refused with apply_build_id_not_found, which lists the ids the contract has.

Before this, only the build runner checked the id. On the OpenTofu engine it starts after tofu apply, so a mistyped --build-id provisioned the product, and the run then stopped with Build not found and exit 1.

forge-cli #808 is on main (squash-merged as 635ea30e, 2026-11-04), so the "on main" wording is now true and this is ready to merge.

• The text was checked against #808 head edb5bc0a. On the files the squash touched, the only difference from that head is #806, which merged in between: two unrelated CHANGELOG entries and three other error-catalog entries. cli/apply.py is identical, and so is the apply_build_id_not_found catalog entry the output block quotes. The documented behaviour and output are unchanged.
• When the release ships, the "On forge-cli main, not yet in a release" markers become "since X.Y.Z".

Related CLI PR

• CLI PR: fix(apply): refuse an unknown --build-id before tofu apply forge-cli#808

Areas Updated

• Getting Started
• CLI Reference: docs/cli/apply.md.
  • The "Build ids" subsection gets a paragraph on the --build-id match, a real output block and what changed.
  • The --build-id row of "Build execution" gets a sentence.
  • "Errors you can hit" gets an apply_build_id_not_found row.
• Provider Docs
• Walkthroughs / Examples
• Contributing / Community Docs
• Other:
  • docs/upgrading.md: a bullet under "On forge-cli main since 0.26.0", after #803's. It notes that the exit code stays 1 and that a Command Center run records apply_build_id_not_found where it recorded build_not_found:<id>.
  • docs/advanced/production-troubleshooting.md: rows for apply_build_id_not_found and for #803's apply_build_identifier_invalid in "Environment, mode and plan-file errors". Neither event has a docs route of its own, so the CLI's "📖 Documentation" link for both opens this page, which did not mention either.
  • docs/advanced/operating-in-ci.md: one sentence. A Jenkins stage 7 given an APPLY_BUILD_ID that names no build now fails before it applies anything.

Checklist

• I previewed the change locally with npm run docs:dev or built it with npm run docs:build
• I checked links, page titles, and navigation where relevant
• Screenshots or command output are updated if needed

Notes

• Output block: from a real fluid apply run of the #808 branch. It is the full refusal as printed, suggestions included, and it was diffed byte for byte against that run.
• Stage 7 claim: checked against forge/core/pipeline_systems/_base.py. Stage 7 runs fluid apply runtime/plan.json … --mode "$MODE" and appends --build-id "$BUILD_ID" in the build modes. #808's gate refuses on the plan.json path too.
• Checks run locally: against the pinned data-product-forge==0.26.0; all pass.
  • check_cli_docs.py (1,371 documented fluid invocations, the new one included), its --version-only and --markers-only modes, check_providers.py and gen_contract_reference.py --check.
  • npm run docs:build, then scripts/check-dist-links.mjs: clean over 244 pages. The #build-ids anchor is in the built cli/apply.html.
  • lychee --offline over the four pages: no new errors. The only 3 errors are existing root-relative links in apply.md, which CI resolves with its staged root dir.