[fas89]

What and why

forge-cli #850 changed how forge picks and calls an LLM, and its description promised this docs PR. #850 merged on 2026-11-12 as 28a1f2e2, so every new sentence carries the house marker On forge-cli main, not yet in a release. Each one also says what 0.28.0 did, because the site still pins 0.28.0.

Waits for: a review. Nothing else blocks it, since #850 is already merged. At the next forge-cli release, the pin-bump PR turns the markers into (since X).

Checked against: forge-cli main at 28a1f2e2. That squash is byte-identical to #850's final head ad913502. The brief named fadbdbf5, but the two later commits (f27b6a40 and ad913502) touch only .secrets.baseline, litellm's endpoint-name list and one test, so no documented behaviour moved.

The pages

• advanced/llm-providers.md has three new sections:

  • When nothing is configured: the non-interactive pick (a running local Ollama, then claude, codex, cursor-agent, kiro-cli on PATH), the warning it logs, everything that blocks it, the base install, and interactive runs.
  • Claude Code: the isolation flags and CLAUDECODE, each feature-detected from claude --help. Also sign-in (settings-based auth must come from the shell) and the failure messages.
  • The Ollama endpoint: where the calls go, how OLLAMA_HOST is parsed (ollama-python's _parse_host), local-only model discovery, and routing keeping a stated endpoint.

  The Ollama row and the OLLAMA_HOST row no longer say "local addresses only".

• cli/forge.md: in headless agent mode, any AI flag selects AI mode. The page also covers forge.contract_written, the non-zero exit, and an example. --llm-endpoint now applies to routing calls too, and a pointer to the keyless pick is added.

• cli/ai.md: ai test probes through the call fluid forge makes. It shows endpoint: null / "provider default", and the exit codes on main are 3 for 401/403, 4 for an unknown model or a 404, and 5 for the rest. The OLLAMA_HOST note now says where the localhost guard still applies (interactive Ollama setup).

• cli/doctor.md: "Provider default", coding-agent://<name>, agent readiness by CLI on PATH, the not-on-PATH message, and readiness without a terminal.

• advanced/litellm-backend.md, advanced/environment-variables.md: the OLLAMA_HOST row, FLUID_LLM_ENDPOINT for routing, FLUID_COPILOT_AGENT_LOOP blocking the pick, and a pointer to the pick.

• advanced/production-troubleshooting.md: a coding agent that is not signed in.

• upgrading.md: On forge-cli main since 0.28.0, the five changes a script or CI job can notice.

Borrow before build

Extended the pages that already own each surface; no new page. Linked the upstream sources #850 borrowed from:

• claude-agent-sdk-python subprocess_cli.py @ 3cf3446b;
• ollama-python _parse_host @ 35d9667e;
• Claude Code's CLI reference and authentication pages.

Validation

Gates, reproduced locally on Python 3.11 with data-product-forge==0.28.0 from pypi.org/simple. FORGE_CLI_CHANGELOG was set to forge-cli main's CHANGELOG at 28a1f2e2.

• check_cli_docs.py --version-only, check_cli_docs.py, check_providers.py, check_cli_docs.py --markers-only and gen_contract_reference.py --check all pass.
  • The flag oracle passes all 1382 documented fluid invocations. Every flag the new example shows exists in 0.28.0, so no flag_oracle_ok entry is needed.
• npm ci && npm run docs:build && node scripts/check-dist-links.mjs is clean: 141,667 references, and every new anchor renders.
• lychee --offline over CI's route mirror reports 0 errors. Every new external link returns 200.

Claims, checked by a verifier agent that ran the CLI:

• It ran main's CLI from the #850 worktree with a clean HOME, a null keyring, stub agent CLIs (which logged their argv and environment) and the local Ollama. It ran v0.28.0, built from the tag, for every "Through 0.28.0" sentence. It made no paid model call.
• The first pass found 5 imprecise sentences and 5 surviving contradictions: three "Ollama is localhost only" claims, the network-safety table row, and the ai test example's error code. All are fixed, and a re-check confirmed each fix.
• Not run live: the claim that Claude Code authentication kept in settings (apiKeyHelper, or Bedrock or Vertex variables in settings.json) does not reach forge's calls. It follows from --setting-sources=: Anthropic's CLI reference and Agent SDK docs say an empty list loads no user, project or local settings, and #850's CHANGELOG says the same. Checking it live needs one of those setups and a paid call.

Follow-ups (forge-cli, not this PR)

• AI-mode forge.contract_written is not emitted when --target-dir is outside the current directory, because the receipt snapshot scans Path.cwd() (scan_root in cli/forge.py). Blank mode emits it for any target. The page states the condition.
• fluid ai test --endpoint checks model availability against OLLAMA_HOST or localhost:11434, not against the stated endpoint (0.28.0 too). The page states it.
• Non-interactive runs do not use the saved fluid ai setup provider. #850 already lists this under "Not in this PR".
• fluid doctor says Not selected where a forge run falls back to gemini.
• Docs: the 0.18.1 warning that fluid ai test crashes on detect_ollama_available (in cli/ai.md and advanced/production-troubleshooting.md) is stale. 0.28.0 returns ai_test_no_provider, exit 2.