docs(cost): "Where do I set max_budget_usd?" has no complete answer — Blueprint knob is documented but unimplemented

[scottschreckengaust]

Surfaced while planning the #740/#741 model-configuration stack. Filed separately because it is a pre-existing docs↔code mismatch, independent of the Opus 5 bump.

Scope note: this issue is not a proposal to change the unlimited-by-default posture. That posture is deliberate. This is about being able to answer the customer question "Where do I set max_budget_usd?" correctly and completely — today one of the four documented answers points at a knob that does not exist.

The mismatch

docs/guides/USER_GUIDE.md promises a per-repo Blueprint budget default in two places:

• :226 — table row: max_budget_usd | "Default cost budget in USD per task" | "None (unlimited)", listed under Blueprint per-repository settings
• :370 — "Overrides the per-repo Blueprint default"

But cdk/src/constructs/blueprint.ts has no maxBudgetUsd prop. It implements maxTurns (line 90, written at :251/:343/:360/:377) and simply omits the budget. Verified: grep -n max_budget_usd cdk/src/constructs/blueprint.ts returns nothing.

The type surface makes it look supported, which is why this went unnoticed:

• RepoConfig.max_budget_usd?: number exists (cdk/src/handlers/shared/repo-config.ts:39)
• BlueprintConfig.max_budget_usd?: number exists (:74)
• cli/src/repo-onboard.ts:116 preserves an existing value on re-onboard
• cli/src/repo-display.ts:109,188 renders it with a blueprint field source

So every layer can read and carry a per-repo budget, and nothing can write one. The blueprint field source in repo-display is unreachable for this field.

Verified: where it actually can be set

Surface	How	Works?
Per task, CLI	bgagent submit --max-budget <dollars> (cli/src/commands/submit.ts:69), validated 0.01–100 (:137)	✅
Per task, REST	max_budget_usd in POST /v1/tasks (USER_GUIDE.md:370)	✅
Local batch only	MAX_BUDGET_USD env (agent/src/config.py:688); ECS strategy forwards the payload value as this env var (ecs-strategy.ts:216). Not read in deployed AgentCore server mode — see agent/README.md:124	⚠️ narrow
Per repo, Blueprint	agent.maxBudgetUsd	❌ not implemented
Platform default	—	❌ none by design; unset ⇒ unlimited (USER_GUIDE.md:231)

Why it matters now

With a heavier-token default model landing (#745 — same $5.00/MTok rate, ~1.17x token volume on an identical prompt), the natural operator question is "how do I cap this per repo?" The honest answer today is you can't — only per task, or by choosing a lighter-token model per repo via blueprint agent.modelId. That is a legitimate answer, but the docs currently imply a budget knob exists, which sends operators looking for a prop that isn't there.

Resolution — pick one

Option A (docs-only, smallest). Correct USER_GUIDE.md:226/:231 to state that per-repo budget defaults are not currently supported, and point operators at the per-task flag plus the per-repo agent.modelId model-choice lever. Also correct docs/design/REPO_ONBOARDING.md if it repeats the claim.

Option B (implement the prop). Add maxBudgetUsd to BlueprintProps.agent mirroring maxTurns exactly — the write paths at blueprint.ts:251/:343/:360/:377, plus validation matching the CLI's 0.01–100 range so the two boundaries agree. Read path and CLI display already exist, so this is a small, well-patterned change.

Recommend B if a per-repo budget is genuinely wanted (the plumbing is already 80% there and the docs already promise it), otherwise A. Either way the docs and code must agree.

Acceptance criteria

• Docs and code agree on whether a per-repo Blueprint budget default exists
• USER_GUIDE.md:226/:231 corrected, or the prop implemented with tests mirroring the maxTurns coverage in cdk/test/constructs/blueprint.test.ts
• If implemented: validation range matches MAX_BUDGET_USD_MIN/MAX_BUDGET_USD_MAX used by cli/src/commands/submit.ts:137
• The complete "where can I set this" surface table (above) appears in the docs — including that MAX_BUDGET_USD env is local-batch-only and ignored by deployed AgentCore server mode
• cli/src/repo-display.ts blueprint field source for max_budget_usd is either reachable (Option B) or documented as unreachable (Option A)
• mise //docs:sync run if guides changed; mise run build green

Related

• docs(model): canonical model-configuration reference + fix stale defaults #742 — documents the cost/model-selection story and the "Where do I set max_budget_usd?" table; will reference whichever resolution this issue takes
• feat(agent): flip platform default model to us.anthropic.claude-opus-5 #745 — heavier-token default model; the reason this gap became visible
• Docs: document model-ID configuration layers, governing env vars, and global Bedrock endpoints #740 / feat(agent): default to Claude Opus 5 on the global Bedrock inference profile #741 — parent tracking issues for the model-configuration stack

[scottschreckengaust]

@scottschreckengaust (agent:w4) working on it — #748 — branch docs/748-max-budget-usd-surfaces

[scottschreckengaust]

🤖 @scottschreckengaust (agent:w4) — signing out, over and out.

PR #763 opened (draft); body lists Closes #748 so it auto-closes on merge (verified: closingIssuesReferences registers #748). Now in the orchestrator's review pipeline.

Chose Option B — implemented agent.maxBudgetUsd on the Blueprint construct. It needed nothing beyond mirroring maxTurns: no schema migration, no API contract change, and no new orchestrator read (orchestrator.ts:697 already merged blueprintConfig?.max_budget_usd — the tier just could not be populated). Bounds read contracts/constants.json, the same source cli/src/commands/submit.ts:137 validates against, so per-repo and per-task ranges cannot drift. Also added the complete surface table to USER_GUIDE.md and documented unlimited-by-default as deliberate alongside the model-choice escape hatch.

One follow-up flagged in the PR body: docs/guides/DEVELOPER_GUIDE.md:193 still says the Blueprint knob is "Not implemented", which this PR makes false. #742 owns that file so I did not edit it — suggested replacement text is in the PR.