docs(rust): final-state cleanup — tiktoken pin + error-aware cap handling

[amavashev]

What

Fresh codex review against `main` (after PR #659/#660/#661 all landed) caught two issues that slipped through the three earlier rounds:

1. `tiktoken-rs` version pin stale. The streaming tokenizer-fallback subsection pinned `tiktoken-rs = "0.6"` while crates.io is at 0.11.0. The cited API (`o200k_base`, `encode_with_special_tokens`) is unchanged across that range, but the pin should match current.

2. Error-aware example skipped cap handling. The `run_completion` function called `.max_completion_tokens(800u32)` without checking `guard.caps()`. The intro's loud-failure stance claimed all examples on the page error out on non-positive `caps.max_tokens` — that was false for this example.

A third issue surfaced in codex round 2 of this PR: the basic example also doesn't read caps (it takes `_ctx` to keep the minimum-viable composition compact). Rather than dilute that example by adding cap handling to it, I narrowed the intro claim to accurately describe what each example demonstrates.

Changes

`how-to/integrating-cycles-with-async-openai.md`:

• `tiktoken-rs` pin: `"0.6"` → `"0.11"` in the streaming tokenizer-fallback Cargo.toml comment.

• Error-aware example cap handling: added the same `u32::try_from(cap)` + zero-check + release-and-error pattern used in the ALLOW_WITH_CAPS and streaming examples. The error variants are typed as `CompletionError::Cycles(CyclesError::Validation(...))` to flow through the function's typed-error contract:

  ```rust
  let mut max_tokens: u32 = 800;
  if let Some(caps) = guard.caps() {
  if let Some(cap) = caps.max_tokens {
  let cap_u32 = u32::try_from(cap).map_err(|_| {
  CompletionError::Cycles(CyclesError::Validation(
  "caps.max_tokens is negative".into(),
  ))
  })?;
  if cap_u32 == 0 {
  let _ = guard.release("caps.max_tokens is 0".to_string()).await;
  return Err(CompletionError::Cycles(CyclesError::Validation(
  "caps.max_tokens is 0".into(),
  )));
  }
  max_tokens = cap_u32.min(max_tokens);
  }
  }
  ```

• Intro Loud-failure stance narrowed: all four examples fail loud on missing `usage` and missing `content`. The three cap-reading examples (ALLOW_WITH_CAPS, streaming, error-aware) additionally fail loud on non-positive caps. The basic example deliberately ignores caps to keep the minimum-viable composition compact; production code should follow the capped pattern.

Review

• Codex final-state pass (against `main` HEAD 779c022) → REVISE-MINOR
  • tiktoken pin stale
  • Error-aware example missing cap handling
• Codex round 2 (after applying both) → REVISE-MINOR
  • Basic example also doesn't read caps; intro claim still over-stated
• Codex round 3 (after narrowing the intro) → SHIP

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

Test plan

• `npm run build` succeeds; no broken-link warnings
• Rendered "Loud-failure stance" callout reads as the narrowed claim
• Error-aware example renders the new cap-handling block
• tiktoken-rs version pin shows 0.11

Why a fresh PR rather than amending

PR #661 was already merged into main before the user prompted for a final-state re-review. Branching off main is the clean path; this PR is small and focused.