USER_GUIDE.md JSON examples show duration_s / cost_usd as strings; server returns numbers

[scoropeza]

Follow-up from PR #52 — surfaced during a post-merge documentation audit. The recent chore(docs): clean docs commit (0742ebe) covered 11 of 12 doc gaps; this is the remaining one.

Functional description

The JSON example responses in docs/guides/USER_GUIDE.md show duration_s and cost_usd as quoted strings:

"duration_s":"125.9","cost_usd":"0.15938219999999997"

After the krokoko PR #52 review fix #2 (commit d6ad9a5), the server now coerces these fields to numbers in the response. The documented examples no longer match the actual API response shape.

User-visible impact:

• Developers integrating against the REST API may write parsing code that treats these fields as strings, then hit type errors at runtime.
• The discrepancy undermines trust in the reference examples — "if this is wrong, what else is wrong?"
• Downstream TypeScript clients (like bgagent itself) declare these as number | null (see cli/src/types.ts), so the docs contradict the CLI's own types.

Technical fix

Three JSON blobs in docs/guides/USER_GUIDE.md need the string quotes removed from duration_s and cost_usd:

Line 222 (Create a task — SUBMITTED response):

• "duration_s":null,"cost_usd":null → already correct (nulls are untyped; no change)

Line 331 (Get task detail — COMPLETED response):

-"duration_s":"125.9","cost_usd":"0.15938219999999997"
+"duration_s":125.9,"cost_usd":0.15938219999999997

Line 638 (another SUBMITTED-state example):

• "duration_s":null,"cost_usd":null → already correct

So the fix is effectively one line at line 331. While touching the file, consider also verifying:

• max_budget_usd — also now numeric per the shared coercion helper
• turns_attempted / turns_completed — if they appear in any example, also numeric

After editing docs/guides/USER_GUIDE.md, run cd docs && node scripts/sync-starlight.mjs (or mise //docs:sync) to regenerate the Starlight mirrors under docs/src/content/docs/, and commit both together.

Acceptance criteria

• docs/guides/USER_GUIDE.md example JSON responses show duration_s and cost_usd as unquoted numbers (where non-null).
• Starlight mirrors in docs/src/content/docs/ regenerated and committed alongside.
• CI's "Fail build on mutation" step passes (i.e. the committed mirrors match what the sync script produces).

Out of scope

• API contract changes — the server already returns numbers; this is a pure docs fix.
• Adding new example responses for other endpoints.
• Migrating example payloads to a schema-generated source of truth.

References

• docs/guides/USER_GUIDE.md:331 — the stale COMPLETED-state example
• cdk/src/handlers/shared/numeric.ts — coerceNumericOrNull (introduced by PR feat(interactive-agents): async-only background task UX + Cedar HITL design #52 commit d6ad9a5)
• cli/src/types.ts — TaskDetail.duration_s: number | null, TaskDetail.cost_usd: number | null
• PR feat(interactive-agents): async-only background task UX + Cedar HITL design #52 review comment Docs: specify that you can't use the agent with the canned repo #2 (krokoko) — original finding that triggered the server-side coercion

[krokoko]

Done in 6e4a6c8