ai: tighten public surface and document CuaProvider + supported models

[rgarcia]

Summary

Follow-up polish to @onkernel/cua-ai's docs and public surface:

• parseCuaModelRef / formatCuaModelRef: now module-private. They were only ever shaped as implementation details (pure string munging) and had no external callers in the workspace — getCuaModel exercises both internally. Tests for the error paths now route through getCuaModel so the user-visible behavior is still covered. Also dropped the empty-id guard from formatCuaModelRef since both call sites pass a known-non-empty id.
• README:
  • Dropped the "See examples/quickstart.ts" stub — wasn't adding value.
  • Added a CuaProvider section between Model Refs and listCuaModels. Explains that CuaProvider is a string union (not a runtime object), how it overlaps with pi-ai's Provider, and the gemini/google rename.
  • Pulled the model catalog into docs/supported-models.md and linked it from Model Refs. Each provider section lists family/exact matchers with citation links to the official CUA docs.
• Quickstart timestamp: Date.now(): kept. Investigated pi-ai's complete() — it just delegates to the registered provider's stream function and pi-ai's UserMessage type requires timestamp: number. Nothing defaults it, so the example must include it.

Test plan

• npm run build (cua-ai package)
• npm test (cua-ai package — 43 passed / 7 skipped)
• npm run typecheck (workspace)

🤖 Generated with Claude Code

---

Note

Medium Risk
Medium risk because it changes the public provider identifier from gemini to google and narrows top-level exports, which can break downstream imports and model refs even though runtime behavior is mostly unchanged.

Overview
Provider ID alignment: switches CUA provider/model refs from gemini:* to google:* (including agent defaults, tool routing, model annotations/overrides, examples, and integration tests) and simplifies providerForModel() to return model.provider after validation.

Public surface + docs: restructures packages/ai/src/index.ts to explicitly export only the intended APIs/types (adding isCuaProvider) and adds docs/supported-models.md plus README updates describing CuaProvider, model-ref format, and supported-model listings.

Test robustness: relaxes batch tool integration assertions for providers that may emit no tool calls (e.g. tzafon), gating expectations via new per-provider flags while still requiring usage token reporting.

^{Reviewed by Cursor Bugbot for commit ce5024b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR modifies documentation and public API surface of the @onkernel/cua-ai package, not the kernel API endpoints (packages/api/cmd/api/) or Temporal workflows (packages/api/lib/temporal) specified in the filter.

To monitor this PR anyway, reply with @firetiger monitor this.