docs: overhaul mkdocs site with full SDK coverage

[TexasCoding]

Summary

Audit-driven rewrite of the docs site. Nine research agents compared each SDK subsystem against the existing docs in parallel; this PR fixes everything they flagged and fills in the gaps.

• 35 doc files touched (8 modified, 27 new). Builds clean under mkdocs build --strict.
• New per-resource pages for all 19 resources, each with an auth matrix, examples, footgun callouts, and mkdocstrings autodoc tails.
• New core pages: Configuration, Concepts, Environment variables, Pagination, Types & literals, Request models, DataFrames, Retries & idempotency, Testing.
• WebSocket page fully rewritten from source.
• Nav restructured into Getting Started / Core / Resources / WebSocket / Testing / Migration / Reference.

Inaccuracies fixed

• errors.md documented the backoff as additive jitter — actual code is AWS Full Jitter (_base_client.py:86-87).
• websockets.md listed the wrong wire type values (singular market_position / user_order / multivariate_lookup); claimed callbacks "take over routing" — they actually fan out alongside iterators; claimed backpressure errors are recoverable — they are fatal teardown of the recv loop.
• resources/index.md claimed a non-existent 1000-page cap in list_all() and that all market data is auth-free (false for orderbook / bulk_orderbooks / series.forecast_percentile_history / exchange.user_data_timestamp).
• authentication.md conflated preflight AuthRequiredError with server 401/403 KalshiAuthError; missed from_pem, PKCS#8 / RSA constraints, and passphrase-key remediation.

Other notes

• kalshi/cli/ was investigated and intentionally not documented — no .py sources are tracked, only stale __pycache__.
• mkdocs.yml: tightened mkdocstrings options, added not_in_nav for internal worklog pages (AUDIT-resource-params.md, RELEASING.md).

Test plan

• uv run mkdocs build --strict succeeds cleanly.
• Spot-check the rendered pages locally with uv run mkdocs serve and verify the autodoc blocks render for each resource.
• Skim the inline examples for any from kalshi import paths that don't exist.

🤖 Generated with Claude Code

[claude]

Code Review — PR #153: docs: overhaul mkdocs site with full SDK coverage

This is a well-executed documentation overhaul. The inaccuracy fixes are correct and material — the old backoff description, WebSocket routing claim, backpressure fatality, and the phantom 1000-page cap were genuinely misleading. The new per-resource pages are consistently structured and the cross-linking is good. A few things worth addressing before merge.

---

Potential inaccuracy — retries.md PUT/PATCH treatment

The new table says POST, DELETE, PUT, PATCH are never retried, but CLAUDE.md documents only POST and DELETE as never-retried ("duplicate order/cancel risk"). PUT and PATCH aren't mentioned there. Please verify _base_client.py — if PUT is treated the same as GET in the retry logic, this table is wrong and could surprise users who expect PUT (e.g. order_groups.reset(), subaccounts.update_netting()) to retry on 5xx.

---

Factual issue — reconciliation example filters on status="resting"

In retries.md under 'Reconciliation after a 5xx on a write', the example scans client.orders.list_all(status="resting"). An order that landed before the 5xx may be executed or canceled by the time you check, not resting. Filtering to only resting orders means you'd retry a fill that already happened. Drop the status= filter and add a note that executed is also a valid terminal state here.

---

Missing per-channel overflow/behavior reference in websockets.md

The old doc had per-channel sections (subscribe_ticker, subscribe_orderbook_delta, etc.) documenting overflow strategy, unique params (shard_factor/shard_key for subscribe_communications), and firehose behavior. The new backpressure table covers overflow, but a reader of subscribe_communications() won't know that shard_factor/shard_key exist — they're buried in the generic subscribe() section. Consider adding a 'Notable params' column to the 11-channel table.

---

Unchecked test plan items

Two of three test plan items are still open — the 'from kalshi import' path check is especially worth doing before merge. The new pages use 'from kalshi import TickerPair', 'from kalshi import CreateOrderRequest', etc. A quick python -c 'from kalshi import TickerPair' confirms they're reachable from the public surface.

---

Minor nits

• authentication.md — 'The constructor is keyword-only' and 'an empty key_id raises ValueError' are new claims worth a one-liner verification against KalshiClient.init.
• structured_targets.get() — documented to return None for 404s rather than raising KalshiNotFoundError, unlike every other get(). Confirm this is intentional and not a code bug.
• resources/orders.md — action="buy", # ActionLiteral, defaults to "buy" — if action is required (not optional), the comment is misleading.
• dataframes.md async example — async def collect() -> list: should be list[Order] or similar.

---

What is well done

• The backoff formula fix (AWS Full Jitter) is correct and matches the implementation.
• WebSocket wire type values (singular user_order, market_position, multivariate_lookup) were wrong and are now correct.
• Callback fan-out correction is a significant behavioral fix (was 'takes over routing', now 'fans out alongside iterators').
• Backpressure fatality correction is accurate; the danger admonition is the right level.
• Removing the phantom 1000-page cap is correct.
• Auth matrix additions (orderbook, bulk_orderbooks, series.forecast_percentile_history, exchange.user_data_timestamp) are accurate.
• The !^_ filter in mkdocstrings avoids leaking private members.
• not_in_nav for AUDIT-resource-params.md / RELEASING.md is clean.
• Nav restructure is a clear improvement over the flat list.

The PUT/PATCH retry claim and the reconciliation example are the two items to confirm before merge.