[fas89]

This PR documents forge-cli #853 and forge-cli #854, and pins forge-cli 0.29.0, the release that contains them. forge-cli tagged v0.29.0 on 802ffed7 (#855), and the release is on PyPI.

Draft for review. There are two commits:

1. d35a322 documents #853 and #854. It was checked against forge-cli 33326517, and the earlier states against 3b7e8c10, cd67e429, 28a1f2e2 and 0.28.0.
2. ef4d86e is the 0.29.0 release refresh. It also covers the pages that docs(ai): keyless auto-pick, --agent AI mode, an isolated claude -p and the Ollama endpoint (forge-cli#850) #204 and docs(ai): no gemini fallback, one Ollama address for every read, --agent target dirs (forge-cli#852) #205 merged for #850 and #852:
   • cli-version.json now pins 0.29.0. forge-cli-releases.json is reviewed through 0.29.0, from --refresh-releases.
   • 14 version claims move to 0.29.0, and the two generated contract pages are restamped. The schema hashes are unchanged.
   • The 70 "On forge-cli main, not yet in a release" markers for #850, #852, #853 and #854 become *(since 0.29.0, [forge-cli #N](...))*. #851 and #844 had no markers.
   • "Before #85x" sentences described main between those PRs, a state no release shipped:
     • Most become "Through 0.28.0" history. Each was checked against the 0.28.0 source or earlier 0.28.0 runs.
     • Three held only on main, so they are removed: the old saved-choice message, --agent AI mode's cwd-only receipt scan, and the ai test model check's exit 4.
   • upgrading.md: "On forge-cli main since 0.28.0" becomes "Changes in 0.29.0", grouped by topic. The mission bullet is dropped, because 0.28.0 never picked a coding agent either.

What changed

• llm-providers.md gets two new sections:
  • "Which provider a run uses" (#854) covers:
    • the ladder: a named provider, then one key variable, then the saved fluid ai setup choice, then one keyring key, then Ollama, then a coding agent;
    • what the saved choice fills in;
    • that a saved coding agent is passed over when a run states an endpoint or a model, or runs the agent loop;
    • that saved names are normalised and the saved endpoint field is not applied;
    • that fluid mission run never picks an agent.
  • "Which key a provider gets" (#853) covers:
    • FLUID_LLM_API_KEY only for a provider named with --llm-provider, FLUID_LLM_PROVIDER or FLUID_FORGE_AGENT;
    • the warning when the key is not used;
    • fluid ai test --provider and fluid doctor.
• project-dotenv-trust.md: new "LLM endpoints in a project file" (#853):
  • OpenAI, Anthropic, Gemini and GitHub Models endpoints need the provider's own key, while groq, deepseek and the like still pair with FLUID_LLM_API_KEY;
  • interactive setup no longer copies your saved key over a project's key.
• production-troubleshooting.md:
  • The saved-choice row of "No LLM provider is selected" is replaced. #854 removed the "does not read the saved choice" message. The saved variant now fires only for a saved coding agent passed over by a stated endpoint, a stated model or the agent loop.
  • New "A key forge did not use", with the three warning texts.
• environment-variables.md, cli/ai.md, cli/doctor.md, cli/forge.md, cli/mission.md, upgrading.md:
  • the key rule;
  • the saved choice in runs without a terminal;
  • FLUID_LLM_MODEL, FLUID_LLM_ENDPOINT and the agent loop passing over a saved agent;
  • JSON-Lines-only --agent stdout;
  • mission.
• docs(ai): no gemini fallback, one Ollama address for every read, --agent target dirs (forge-cli#852) #205's text corrected for #854:
  • the troubleshooting row and its doctor sentence;
  • the forge data-model --llm-model parenthetical in cli/forge.md;
  • the saved-provider items in "When nothing is configured";
  • "names" becomes "selects" where #853 gives "named" a narrower meaning.

Checks run locally

Run on ef4d86e with Python 3.11 and data-product-forge==0.29.0 from pypi.org/simple, with FORGE_CLI_CHANGELOG set to forge-cli main's CHANGELOG.md. check_cli_docs.py also confirms fluid --version 0.29.0 and that every version claim agrees with the pin:

• check_cli_docs.py: exit 0. All 1382 fluid invocations match, and the marker sweep is OK. No flag_oracle_ok entry is needed.
• gen_contract_reference.py --check and check_providers.py: exit 0.
• npm ci && npm run docs:build: exit 0. node scripts/check-dist-links.mjs is clean, and every new anchor is in dist/.
• Base-prefix check: OK.
• lychee-source, offline, over CI's route mirror: 0 errors; the canaries behave (0 and 2).

How the claims were checked

Every sentence was checked by running the CLI on forge-cli 33326517, 3b7e8c10, cd67e429, 28a1f2e2 and v0.28.0, in an isolated environment:

• a scratch HOME and a null keyring;
• no agent CLIs on PATH, except a fake claude where a case needed one;
• a dead proxy hiding the local Ollama, and a loopback stub Ollama that logs the Authorization header;
• project directories with .env endpoint and key pairs.

The tests of #853 and #854 pass on 33326517 (341 passed). Interactive fluid forge and fluid init need a TTY, so their setup functions were called directly.

The first pass found no wrong claim, but 9 imprecise sentences. It also found 3 rows outside the change that #854 left incomplete (FLUID_LLM_MODEL, FLUID_LLM_ENDPOINT, FLUID_COPILOT_AGENT_LOOP). The re-check confirmed all were fixed, and the last small wording gaps it found are fixed too.