docs: 100% accuracy pass for v4.0.0 (cfbenchmarks WS, Klear Bearer, account/perps additions)

[TexasCoding]

Documentation accuracy pass for v4.0.0

Brings every doc to 100% accuracy against the v4.0.0 surface that shipped in #444. Found via a parallel audit of all ~25 doc files; each finding verified against the actual code (doc-example field names checked against the shipped models).

WebSocket (11 → 12 channels)

• docs/websockets.md: channel count 11→12, added the cfbenchmarks_value table row + a CF Benchmarks index values section (subscribe, union-return isinstance discrimination, json.loads(msg.data), the CFBenchmarks* models); corrected a stale "channel count stays 11" note.
• docs/index.md + README.md: 11→12 (incl. the #the-12-channels anchor) and subscribe_cfbenchmarks_value in the channel list.

Klear (SCM) Bearer migration

• README.md + docs/index.md: cookie-session/MFA → Bearer; Klear ops 10 → 9.
• docs/perps.md: Bearer-token repr redaction note (was "session cookie").
• New docs/migrations/v3-to-v4.md (full before/after) + a v3 → v4.0.0 section in docs/migration.md + the mkdocs.yml nav entry.

New REST surface

• docs/resources/account.md: upgrade() row + API usage-level grants section (AccountApiLimits.grants, ApiUsageLevelGrant).
• docs/perps.md: margin.api_limits(), and the new MarginMarket/candlestick/ticker notional + leverage_estimates fields.

Prose

• Subaccount range 1‑32 → 1‑63 (docs/resources/subaccounts.md, docs/concepts.md).

docs/reference.md needs no change — it uses module-level mkdocstrings autodoc, so the new models are auto-included. mkdocs build --strict passes.

🤖 Generated with Claude Code

[claude]

Code Review: docs/v4.0.0-accuracy

Summary: Docs-only PR (225 additions, 19 deletions across 10 files). All code examples were checked against the actual shipped models and client code — field names, method signatures, and auth flows are accurate. The migration guide is thorough and well-structured.

---

What's good

• All code examples verified against the implementation: msg.msg.avg_60s_data.value, msg.msg.last_60s_windowed_average_15min, msg.msg.data, msg.msg.index_ids all match the actual CFBenchmarksValuePayload / CFBenchmarksIndexListPayload models exactly.
• The Authorization: Bearer <admin_user_id>:<access_token> wire format is confirmed accurate against KlearAuth.auth_header().
• The operation count drop from 10 → 9 for Klear (removing login()) is correct.
• Honest note in the new migration file: "The subaccount range documented in prose is now 1–63 (no validation change)."
• The cfbenchmarks_value section in websockets.md correctly describes the union-type dispatch and the conditional optionality of last_60s_windowed_average_15min.

---

Issues

1. docs/perps.md:167 — incomplete repr() redaction note

Changed from:

Credentials and the session cookie are never logged or shown in `repr()`.

To:

The Bearer `access_token` is never logged or shown in `repr()` (it is redacted).

The implementation (KlearAuth.__repr__) redacts access_token but does show admin_user_id:

# kalshi/perps/klear/auth.py:47-49
def __repr__(self) -> str:
    return f"KlearAuth(admin_user_id={self._admin_user_id!r}, access_token=<redacted>)"

The new phrasing is technically accurate but may mislead users into thinking both credentials are hidden when only access_token is. Suggest:

The Bearer `access_token` is redacted in `repr()` (only `admin_user_id` is shown).

2. docs/resources/account.md:70 — "(201)" is an unusual inline note

"It returns nothing (201)"

Reads awkwardly — the parenthetical HTTP status mixed into a prose sentence. Suggest:

It returns `None` on success (HTTP 201).

3. docs/migration.md quick-summary table — "(routing only)" is unexplained

The row:

| `KlearClient.from_env()` (routing only) | `KlearClient.from_env()` reads `KALSHI_KLEAR_ADMIN_USER_ID` / `KALSHI_KLEAR_ACCESS_TOKEN` |

The "(routing only)" qualifier has no explanation inline. A reader unfamiliar with v3 won't know what it means. The detailed v3-to-v4.md covers this fully, but the summary table could briefly clarify:

`KlearClient.from_env()` (URL routing only — no credential env vars)

---

Minor nits

• docs/migrations/v3-to-v4.md TL;DR table shows client.login(email=..., password=...) but the Before example below shows the full MFA flow with code=.... The table is intentionally simplified, but a note like "(or with code=... for MFA)" would make the two sections fully consistent.
• docs/websockets.md new section says "Twelve have dedicated subscribe_* methods" — but the intro paragraph still uses "Twelve" in two places and is self-consistent; no change needed.

---

Verdict

Ready to merge after addressing issue #1 (the repr() note accuracy). Issues #2 and #3 are minor polish items that won't mislead users but would improve precision. No correctness bugs, no security issues, no test coverage gaps (docs-only change).

🤖 Generated with Claude Code

[claude]

Code Review — docs: 100% accuracy pass for v4.0.0

Overview: Documentation-only PR (226 additions, 19 deletions across 10 files) that synchronises all ~25 doc files with the v4.0.0 surface. No code changes.

I verified the key claims against the actual implementation before writing this.

---

What's correct and well done

• Channel count consistency — 11→12 updated uniformly in README.md, docs/index.md, and docs/websockets.md. No missed occurrences.
• Klear operation count — 10→9 in sync across README.md and docs/index.md.
• Subaccount range — 1–32 → 1–63 applied to both docs/concepts.md and docs/resources/subaccounts.md.
• CF Benchmarks example field accesses — verified against kalshi/ws/models/cfbenchmarks.py: avg_60s_data.value (DollarDecimal ✓), last_60s_windowed_average_15min (CFBenchmarksAvgData | None ✓), data (str ✓), msg.msg.index_ids (list[str] ✓).
• Bearer token format — Authorization: Bearer <admin_user_id>:<access_token> matches KlearAuth.authorization_header() exactly.
• upgrade() docs — return type None, 403→KalshiAuthError mapping, and the "re-read limits() to see the resulting grant" pattern all match the implementation.
• limits.grants safe iteration — NullableList coerces server-returned null → [], so the direct for grant in limits.grants: example is correct.
• session variable name — consistent with the rest of docs/websockets.md (where ws.connect() yields session).
• mkdocs.yml nav → character — matches the existing v2 → v3 entry style.

---

Minor suggestions

1. CF Benchmarks example — last_60s_windowed_average_15min access pattern

The example shows:

avg60 = msg.msg.avg_60s_data.value          # trailing 60s average (Decimal)
q15 = msg.msg.last_60s_windowed_average_15min  # None outside the final minute

avg60 is a Decimal (accessed via .value), but q15 is a CFBenchmarksAvgData | None — not a Decimal directly. A reader who copies the pattern expecting parallel types would be surprised. Consider showing the guarded access:

q15_avg = msg.msg.last_60s_windowed_average_15min
q15_value = q15_avg.value if q15_avg else None  # Decimal or None

Or at minimum update the comment to clarify the type: # CFBenchmarksAvgData | None.

2. docs/migrations/v3-to-v4.md TL;DR table — AsyncKlearClient not shown

The cheat sheet only covers KlearClient. Async users (who would write AsyncKlearClient(admin_user_id=..., access_token=...) and async with AsyncKlearClient.from_env() as klear:) have to infer the pattern. The body text below does mention both, but a one-liner in the table would help:

- | `KlearClient(demo=True)` + `client.login(...)` | `KlearClient(admin_user_id=..., access_token=..., demo=True)` |
+ | `KlearClient(demo=True)` + `client.login(...)` | `KlearClient(admin_user_id=..., access_token=..., demo=True)` |
+ | `AsyncKlearClient(demo=True)` + `await client.login(...)` | `AsyncKlearClient(admin_user_id=..., access_token=..., demo=True)` |

---

No issues found

• docs/migration.md link [v3-to-v4.md](migrations/v3-to-v4.md) resolves correctly relative to the mkdocs source root.
• The cfbenchmarks_value channel table row (two type values / two message classes) accurately reflects the dual-type nature of the subscription.
• The stale "channel count stays 11" note in docs/websockets.md is correctly fixed to "it does not add a channel".
• AccountApiLimits.grants field description (exchange_instance, level, source, expires_ts) matches the ApiUsageLevelGrant model exactly.

---

Verdict: Ready to merge. Both suggestions are minor — the last_60s_windowed_average_15min type clarification is the more user-facing of the two.