docs: bring docs up to date with v2.1.0 surface

[TexasCoding]

Summary

Documentation coverage pass for the v2.1.0 spec sync that merged via #155. Four parallel docs agents audited the docs tree against the implementation; this PR closes every gap they found across 14 files.

What's covered

• README + docs/index — feature lists now mention V2 orders, deposits/withdrawals, endpoint_costs; OpenAPI version + endpoint/channel counts refreshed.
• docs/migration.md — new ## v2.0 → v2.1 section covering the Balance.balance_dollars construction-time soft break, V2 orders family + client_order_id idempotency, the spec-driven subaccount / exchange_index placement asymmetry, and the new optional kwargs.
• docs/resources/orders.md — split quick reference into V1 (legacy) + V2 sections; new "V2 event-market orders" section with examples for every V2 method plus the placement-asymmetry table; legacy deprecation callout (no earlier than May 6, 2026).
• docs/resources/portfolio.md — Balance section now covers balance_dollars, balance_breakdown, and the cents-vs-DollarDecimal type collision; new "Deposits and withdrawals" section.
• docs/resources/account.md — endpoint_costs() documented.
• docs/resources/communications.md — list_quotes filter warning updated; new "Filtering shortcuts (v2.1.0)" + "Post-only quotes" sections.
• docs/resources/incentive-programs.md — incentive_description kwarg surfaced.
• docs/resources/order-groups.md — exchange_index on create/delete + a new section.
• docs/types.md — integer-cents table extended; Balance/IndexedBalance type-collision warning; literals table adds BookSideLiteral, UserFilterLiteral, PaymentStatusLiteral, PaymentTypeLiteral.
• docs/request-models.md — inventory adds 5 V2 request models; new "V2 surface: model-only" subsection.
• docs/concepts.md — Order section now distinguishes V1 vs V2 families.
• ROADMAP.md — v2.1.0 entry in Shipped; response-side spec drift detection flagged as the motivating follow-up (the Balance.balance_dollars miss).
• CLAUDE.md — spec version, endpoint count, channel count, test count refreshed.

Test plan

• uv run mkdocs build — clean (no anchor warnings).
• uv run mypy kalshi/ — clean.
• uv run ruff check . — clean.
• Reviewer eye on the V2 orders section, especially the asymmetry table.

🤖 Generated with Claude Code

[claude]

Code Review — PR #156: docs: bring docs up to date with v2.1.0 surface

This is a docs-only PR (521 additions, 25 deletions, 14 files). No production code is changed. Overall the coverage is comprehensive, the warnings and asymmetry callouts are excellent, and the migration guide is actionable. A few small items worth addressing before merge:

---

Issues

1. Imprecise test count in CLAUDE.md

-pytest + pytest-asyncio + respx (httpx mock); 1455 tests collected (1407 passing, 48 skipped without live credentials).
+pytest + pytest-asyncio + respx (httpx mock); ~1920 tests across unit + contract drift suites.

The old line was an exact count; the new one uses ~. CLAUDE.md is an agent context file — imprecision there degrades future tooling. Run uv run pytest tests/ --collect-only -q 2>/dev/null | tail -1 and use the actual number.

---

2. rfq_user_filter has no Literal alias in docs/types.md

UserFilterLiteral is documented in the literals table, but the communications section introduces rfq_user_filter="self" with no corresponding RFQUserFilterLiteral entry. Either:

• add a RFQUserFilterLiteral row to the table (if one exists in the implementation), or
• note in the existing UserFilterLiteral row that the same literal is reused for rfq_user_filter.

Currently the table leaves readers guessing what type rfq_user_filter accepts.

---

3. cancel_v2 parameters — are they required or optional?

The V2 quick-reference table shows:

cancel_v2(order_id, *, subaccount, exchange_index)

No =None defaults, unlike the V1 cancel(order_id, *, subaccount=None, exchange_index=None). If both are truly required keyword args on the actual method, that's an important deviation from the V1 pattern and the asymmetry section should flag it. If they have defaults, the signature should show them. Worth confirming against the implementation.

---

4. series_ticker quietly dropped from incentive-programs example

The diff swaps series_ticker="KXPRES" for incentive_description="Q2 maker". If series_ticker is still a valid filter kwarg (just not in v2.1 scope), removing it from the only code example may confuse users who relied on it. Consider either keeping both in the example or adding a note that the param still works.

---

Minor

• The note UserFilterLiteral only accepts "self" today is correct and future-proofed. Good call.
• The WebSocket channel rename list (order_group → order_group_updates, market_lifecycle → market_lifecycle_v2, etc.) should be cross-checked against the committed specs/asyncapi.yaml snapshot from feat: sync spec to v3.18.0 + fix asyncapi drift false alarm #155 — the PR description says it's pinned there, so a quick diff would confirm.

---

What's done well

• Asymmetry table in orders.md — this is the right call. The subaccount-in-query vs exchange_index-in-body inconsistency across endpoints will trip people up, and surfacing it as a named section prevents support questions.
• Type-collision warning (Balance.balance vs IndexedBalance.balance) is prominently placed in both portfolio.md and types.md. Exactly the right treatment for a non-obvious gotcha.
• Migration guide structure — before/after code blocks, clear "what's breaking vs additive" framing, and a link to the anchor from types.md all work well together.
• ROADMAP.md follow-up — flagging response-side drift detection as the motivating next task (and naming Balance.balance_dollars as the miss that exposes the gap) is the right level of institutional memory.

The three items above (test count, rfq_user_filter type, cancel_v2 signature) are small enough to fix in a follow-up or as a push to this branch before merge. The rest is ship-ready.