docs(rust): sync async-openai how-to with the loud-failure example

[amavashev]

Why

When the cycles-client-rust example (PR #37, merged) went through codex code review, codex caught silent-under-billing bugs in patterns like `response.usage.map(...).unwrap_or(0)`. Those fixes landed in the example. They didn't land in the cycles-docs how-to — PR #659 merged the doc with the original buggy patterns intact.

The result: the shipped doc on `main` and the shipped example in cycles-client-rust were teaching opposite things on the same edge cases.

Edge case	Doc (on main, pre-PR)	Example (on main, post-PR-#37)
Missing `response.usage`	`.unwrap_or(0)` → commit zero	`.ok_or(...)?` → release + error
Missing `message.content`	`.unwrap_or_default()` → empty string success	`.ok_or(...)?` → release + error
Non-positive `caps.max_tokens`	`(cap as u32)` wraps; `max_completion_tokens=0` sent	`u32::try_from(...)?` + zero-check + error
OpenAI field	`.max_tokens(...)` (deprecated upstream)	`.max_completion_tokens(...)`
Token conversion	`as i64`	`i64::from(...)` / `i64::try_from(...)`

Plus an internal contradiction in the doc itself: gotcha #2 told readers "Treat `None` as estimate locally rather than no spend" while the code blocks unwrapped to zero — which is no spend. Description and code disagreed.

What's in this PR

Brings the doc back in sync with the example and fixes the internal contradictions.

Code changes across all four code blocks (basic, ALLOW_WITH_CAPS, streaming, error-aware)

• `.max_tokens(...)` → `.max_completion_tokens(...)`
• Missing `response.usage`: `.unwrap_or(0)` → `.ok_or(...)?` in non-streaming examples. Streaming keeps the option of a tokenizer fallback (legitimate exception — re-issuing a consumed stream is expensive), but the default code path now releases + errors; the tokenizer fallback is shown in a dedicated subsection.
• Missing `message.content`: `.unwrap_or_default()` → `.ok_or(...)?` everywhere
• `(cap as u32)` → `u32::try_from(cap)?` with explicit zero-check
• `usage.total_tokens as i64` → `i64::from(usage.total_tokens)`
• `microcents as i64` → `i64::try_from(microcents)?`
• `ChatCompletionStreamOptions`: fixed to use `Option` field shape that async-openai 0.38.x actually defines (`include_usage: Some(true), include_obfuscation: None`)
• Streaming end-of-stream: added an empty-`full_text` release-and-bail check before the usage check, so the loud-failure stance applies to the "no content but has usage" edge case too
• Streaming zero-cap: `guard.release(...).await?` → `let _ = guard.release(...).await;` so the typed zero-cap error wins over a release-side error

Tokenizer fallback (streaming only)

The fictional `estimate_tokens_with_tiktoken(...)` call became a real, copy-pasteable helper in a new "Optional: tokenizer fallback for missing-usage chunks" subsection. Uses `tiktoken_rs::o200k_base()` with `i64::try_from(...)` conversions (matches gotcha #6).

Prose changes

• Added a "Loud-failure stance" callout in the intro that explicitly references the shipped example
• Rewrote gotchas Standardize Cycles scope terminology and clarify protocol behavior #2 and Add comprehensive documentation for Cycles protocol and client #3 to match the new code (no longer contradict it):
  • Standardize Cycles scope terminology and clarify protocol behavior #2 now distinguishes non-streaming (loud failure) from streaming (tokenizer fallback)
  • Add comprehensive documentation for Cycles protocol and client #3 says "fail loud and release" instead of "commit zero or commit the prompt-token cost only"
• Added gotcha Add comprehensive comparison guide for Cycles vs alternatives #6 covering `as u32` / `as i64` on values from external sources
• Cargo.toml block: added `thiserror = "2"` (was referenced by the `#[derive(thiserror::Error)]` in the error-aware example but missing from the deps list)
• "Other Rust LLM clients" adaptation guidance updated to teach the `ok_or(...)?` + `i64::from(...)` pattern for non-OpenAI providers too

Review process

• Codex round 1 → REVISE-MINOR (6 findings, all applied):
  • `ChatCompletionStreamOptions` field shape against actual async-openai 0.38.2 surface
  • Missing `thiserror` in Cargo.toml block
  • Streaming `release(...).await?` vs `let _ = ... .await` swallow order
  • End-of-stream empty-content hole
  • Stale `response.usage.map(...).unwrap_or(0)` prose still in "Other Rust LLM clients"
  • Fictional `estimate_tokens(...)` call — made real
  • Also caught: tiktoken stub itself used `as i64` casts (the same pattern gotcha Add comprehensive comparison guide for Cycles vs alternatives #6 warns against); switched to `i64::try_from(...)`
• Codex round 2 → SHIP

Verified against runcycles 0.2.4 source, async-openai 0.38.2 docs.rs, tiktoken-rs latest docs.rs, and the shipped `cycles-client-rust/examples/async_openai_completion.rs` on main.

Test plan

• `npm run build` succeeds; no broken-link warnings
• Rendered page shows the new "Loud-failure stance" callout under "What you get"
• All four code blocks use `.max_completion_tokens(...)` and `ok_or(...)?` patterns
• Streaming section's "Optional: tokenizer fallback" subsection renders correctly
• Gotchas Standardize Cycles scope terminology and clarify protocol behavior #2 and Add comprehensive documentation for Cycles protocol and client #3 read consistently with the new code (no longer contradict)