Polish bundle: docs cleanup (env-vars NameError, stale AUDIT doc, kalshi_python_async ref, limits default, cancel idempotency docs, WS perf section, events.get default) #222

Summary

Bundle of small docs / DX cleanup items.

1. docs/environment-variables.md retry example NameErrors on dataclasses.replace

Example block imports only os, KalshiClient, KalshiConfig but calls dataclasses.replace(config, timeout=10.0, max_retries=5). dataclasses is never imported. Pasted verbatim, raises NameError.

Fix: Either add import dataclasses, or rewrite to use KalshiConfig.demo(timeout=10.0, max_retries=5) (already documented in docs/configuration.md:53 and avoids the import).

2. docs/AUDIT-resource-params.md is v0.7.0-era, stale

File header reads Resource Method / Spec Parameter Audit (v0.7.0). The repo is now v2.3.0. mkdocs.yml hides it from nav but it's still committed as a 15KB working-doc artifact, appears in repo browsers / grep, and looks like current SDK guidance.

Fix: git rm docs/AUDIT-resource-params.md OR move it to docs/archive/v0.7.0-resource-params.md with a banner noting it's historical.

3. Stale kalshi_python_async references-the-project-README claim

docs/migration.md:182-184 opens with "If you're coming from kalshi_python_async (the predecessor community client referenced in the project README)…" — but the current README.md contains zero references to kalshi_python_async. The clause is factually inaccurate.

Fix: Drop the "referenced in the project README" clause, or delete the predecessor-migration section entirely if no longer relevant in v2.3+.

4. docs/configuration.md mislabels limits default

Fields table row says default is httpx.Limits() defaults. Dataclass declares limits: httpx.Limits | None = None. The literal default is None.

Fix: Change cell to None and keep meaning column: "When None, the underlying httpx.Client uses its own pool defaults. Pass an httpx.Limits(...) to tune."

5. Cancel methods don't document idempotency semantics for already-canceled / missing orders

orders.cancel, orders.cancel_v2, communications.delete_rfq, communications.delete_quote, api_keys.delete, order_groups.delete — none document what happens when the order/rfq/quote is already canceled or doesn't exist (the SDK propagates whatever _map_error produces, typically a 404 wrapped in KalshiNotFoundError).

Fix: Document in each cancel/delete docstring that 404 propagates and the caller is responsible for safe-retry idempotency, with a one-line example:

try:
    client.orders.cancel(order_id)
except KalshiNotFoundError:
    pass  # already canceled — idempotent

6. events.get default-value drift

Every other endpoint with a tri-state bool uses param: bool | None = None + _bool_param(param). events.get instead defaults with_nested_markets: bool = False, which serializes to "false" and _params keeps it. So every default-shape client.events.get("KXFOO-25") sends ?with_nested_markets=false.

Fix: Change signature to with_nested_markets: bool | None = None on both sync + async events.get. Wire behavior unchanged for explicit callers.

7. Missing WS performance section in docs/websockets.md

For a SDK marketed at automated trading, no doc covers: typical msg/s per channel, queue sizing rule of thumb (maxsize >= 2× peak burst per second), overflow strategy choice (DROP_OLDEST vs ERROR), CPU cost of orderbook_delta vs depth, or the single-threaded recv loop implication.

Fix: Add a "Performance" section to docs/websockets.md. Cross-link from docs/configuration.md. (Pairs with the pluggable-JSON-loader medium issue — both improve high-throughput viability.)

Severity & category

Bundle of low items, documentation + dx.