[SeeRay11]

Issue for this PR

None. This follows a design discussion about how users can run Claude, and free models, in OpenFlow.

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

A Claude subscription can't drive OpenFlow. Anthropic doesn't allow it, and OpenRouter's BYOK takes API keys only. So this PR makes the paid API path cheaper and more predictable, and adds a free local path.

• Local models (lib/local.ts, /flow/api/local, provider panel group). The panel finds Ollama and LM Studio, or a custom OpenAI-compatible URL, lists their models, and declares them in the global config. The declaration needs four fields because the engine's defaults are wrong for a local server:
  • a local- id, because the catalog hides a models.dev id like lmstudio until a key is stored;
  • tools: true, because tools default to off;
  • a context limit, because it defaults to {0,0};
  • a zero price row, so spend reads $0 while the unpriced-never-$0 rule still holds.
• Spend cap in every mode. Pipeline.maxSpend is read through spendCapOf and defaults to $5. Non-gauntlet runs hard-stop in enforceCap and record RunLog.capped. A gauntlet keeps its existing graceful cap. There's a cap: selector in the runbar.
• Pre-run estimate (graph/estimate.ts). Card turns are counted from the graph and each is priced between a short turn and a heavy one. It shows as a range, with an open end for a gauntlet.
• Preflight:
  • weak-seat fires only when an orchestrator, critic or synthesizer is cheaper than a card it works over. It suggests a change and never sets a model.
  • unpriced-cap fires when a model with no price makes the cap partial.
• Spend panel shows what share of the input came from the prompt cache.
• Docs: README sections "Using Claude", "Local models" and "Spend cap and estimate", plus notes on the Anthropic and OpenRouter rows in the provider panel. FLOW.md gets the rules.

Fork-clean: only packages/flow and FLOW.md change.

How did you verify your code works?

• bun test passes (1123 tests) and bun run typecheck is clean. New tests cover local.ts, the /flow/api/local routes (against a temp XDG_CONFIG_HOME), the engine cap (pipeline stopped at the cap, default cap on, a run under it records nothing), the estimate, weak-seat/unpriced-cap, and cacheShare.
• Live check against a real opencode serve whose global config came from declare(), with a stand-in OpenAI-compatible server in place of Ollama:
  • the engine listed local-custom/fake-qwen with no key, priced at 0, with tools on;
  • a session prompted on it reached the server with all 12 card tools and returned its answer.
• Not verified: a real Ollama or LM Studio install, and the panel's write-and-restart click. That click writes the developer's real global config, so it is covered by the route tests rather than clicked live.

Screenshots / recordings

The provider panel shows a new Local models · free, on this machine group with Ollama, LM Studio and a custom-server row.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

🤖 Generated with Claude Code