docs(hosted): user-friendly QA pass + 2.49.2 doc backlog (2.49.4)

Friendly rewrite of all 9 hosted op descriptions, ~129 per-field
descriptions added across 16 hosted-trading schemas, outcome_id
removed from BuildOrderHostedRequest (spec-only; backend still
accepts it), non-custodial language sweep across concept pages,
UI-first deposit/withdraw flow on trading-quickstart and
escrow-lifecycle (programmatic flow tucked under Accordion), x-mint
funding Note now links to pmxt.dev/dashboard/wallet directly.

Also ships the 2.49.2 doc restructure backlog that accumulated dirty
in the working tree: Pattern E sidebar split, hosted-custody page,
prediction-markets-101 glossary, terminology cleanup, custody
hardening, migration-from-Polymarket section, and the 11 shadow MDX
toggle-page deletes.

Author: realfishsam

changelog.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.49.4] - 2026-06-09
+
+Hosted-trading docs QA pass. This patch also ships the 2.49.2 doc restructure work that had accumulated dirty in the working tree but never landed (Pattern E sidebar split, custody page, prediction-markets-101 glossary, terminology cleanup, etc. — see the 2.49.2 entry below for the full list).
+
+### Changed
+
+- **Hosted op descriptions (`openapi-hosted-trading.json`)**: All 9 hosted Group A operations (`createOrderHosted`, `buildOrderHosted`, `submitOrderHosted`, `cancelOrderHosted`, `fetchBalanceHosted`, `fetchPositionsHosted`, `fetchOpenOrdersHosted`, `fetchMyTradesHosted`, `fetchOrderHosted`) rewritten in a user-friendly style: lead with what the customer gets, demote internals (EIP-712, build/sign/submit decomposition, custodial-flow alternatives) to a final paragraph or remove entirely. `createOrderHosted` now opens with an inline code sample showing the natural `client.fetch_markets() → client.create_order(outcome=market.yes)` chain. No more "EIP-712 typed-data payload" or "PreFundedEscrow balance" in opening sentences.
+- **Non-custodial language sweep** across customer-facing concept docs: `docs/concepts/hosted-trading.mdx`, `docs/concepts/hosted-custody.mdx` (new), `docs/concepts/hosted-vs-self-hosted.mdx`, `docs/concepts/prediction-markets-101.mdx` (new), `docs/trading-quickstart.mdx`, `docs/guides/escrow-lifecycle.mdx` all reworded so the escrow story reads "USDC sits in a non-custodial `PreFundedEscrow` smart contract; PMXT cannot move funds without your EIP-712 signature" rather than "PMXT custodies USDC." `docs/security.mdx` left alone — its credential-handling discussion is intentional and scoped correctly.
+- **UI-first deposit / withdraw flow on `docs/trading-quickstart.mdx` and `docs/guides/escrow-lifecycle.mdx`**: Both pages now lead the deposit and withdraw sections with a "Recommended: use the dashboard" subsection (connect wallet at [pmxt.dev/dashboard/wallet](https://pmxt.dev/dashboard/wallet) → click Deposit/Withdraw → confirm in your wallet). The previous `client.escrow.approve_tx(...)` / `deposit_tx(...)` / `withdraw_tx(...)` `<CodeGroup>` blocks are preserved verbatim but tucked inside `<Accordion title="Advanced: programmatic ...">` so they're one click away for the scripting / treasury-automation case.
+- **`x-mint.content` callouts on all 9 hosted ops (`openapi-hosted-trading.json`)**: The funding-prereq `<Note>` now links directly to [pmxt.dev/dashboard/wallet](https://pmxt.dev/dashboard/wallet) for the one-time deposit (with `/guides/escrow-lifecycle` as the programmatic-flow fallback), replacing the previous link to the lifecycle guide alone. The EVM-key `<Tip>` now reads "Your USDC sits in a non-custodial `PreFundedEscrow` on Polygon — the single funding location for every hosted venue (including Opinion, which PMXT settles cross-chain for you). PMXT cannot move funds without your EIP-712 signature." Previous wording said "PMXT custodies USDC on Polygon for every hosted venue."
+
+### Removed
+
+- **`BuildOrderHostedRequest.outcome_id` (`openapi-hosted-trading.json`)**: Following the same logic as `market_id` (relaxed in 2.49.3), `outcome_id` is no longer documented as a request property. The schema now only documents `venue` + `venue_outcome_id` as the way to identify the target outcome. The hosted trading backend continues to accept `outcome_id` (UUID) for backward compatibility — existing callers that send it keep working — but the spec stops promising it as a supported input. Net effect: a new reader looking at the create-order page sees one clean way to identify the outcome instead of an "EITHER (a) catalog UUID OR (b) venue + venue_outcome_id" fork. Schema description tightened to a single sentence.
+- **Dual-identifier framing across the hosted spec**: All "catalog UUID" / "Provide this OR" / "venue-native id from fetch_markets()" / "catalog UUID lookup required" language scrubbed from operation descriptions, schema property descriptions, and `x-codeSamples` header comments. Net `grep -E "catalog UUID|Provide this OR" docs/api-reference/openapi-hosted-trading.json` count went from 14 → 0. Response-side `outcome_id` / `market_id` on `OrderV0`, `UserTradeV0`, `PositionV0` now described as plain "Identifier of the outcome / market this row refers to" without the "catalog UUID" / "cross-venue canonical" framing — readers no longer have to learn an ID-architecture taxonomy before reading a position.
+
+### Added
+
+- **Per-field descriptions across every hosted-trading spec schema (`openapi-hosted-trading.json`)**: ~129 `description` strings added to bare properties across 16 schemas (`BalanceV0`, `BuildOrderHostedRequest`, `BuildOrderHostedResponse` and nested `quote` / `resolved`, `CancelBuildHostedRequest`, `CancelBuildHostedResponse`, `ErrorResponse`, `HostedErrorResponse`, `ListMeta`, `OrderV0`, `PositionV0`, `RateLimitError`, `SubmitOrderHostedRequest`, `UnifiedEvent`, `UnifiedMarket`, `UnifiedOutcome`, `UserTradeV0`). Mintlify now renders meaningful per-field doc strings instead of bare `type | null` rows. Descriptions are grounded in the trading backend's `models_v0.py` Pydantic field semantics — e.g. `fee` is now documented as a USDC dollar amount net of per-fill venue fees, `PositionV0.shares` is documented as the ERC-1155 balance held by `PreFundedEscrow` on behalf of the wallet (*not* the wallet's on-chain balance), and `PositionV0.entry_price` is documented as the v1 cost-basis approximation (`sum(buy_quote_micros) / sum(buy_shares_micros)`, ignoring sells) — with the explicit caveat that `current_price`, `current_value`, and `unrealized_pnl` are reserved and currently return `null` in this release. Verify-grep on bare properties (`jq '... .description == null ...'`) returns zero records.
+
+### Not changed (deliberate)
+
+- **`docs/security.mdx`**: The mode-scoped credential-handling table is intentional — its "credentials hit process memory ephemerally" claim is scoped to **self-hosted** mode and correctly distinguishes from the hosted flow (where the private key never leaves the user's machine). Left alone in the non-custodial sweep.
+- **Auto-generated `docs/api-reference/openapi.json`** (self-hosted spec, regenerated by `core/scripts/generate-openapi.js`): the same description / friendly-rewrite passes were not applied because they'd be lost on the next regeneration. If self-hosted reference docs need the same polish later, the source is the `SCHEMAS` literal inside `core/scripts/generate-openapi.js`, not the rendered JSON.
+- **Backend `BuildOrderV0Req` Pydantic model** (`pmxt-trading`): `outcome_id` remains an accepted field at the API layer for backward compatibility with pre-2.49.3 callers. The spec-side removal is documentation-only — no breaking change on the wire.
+
 ## [2.49.3] - 2026-06-09
 
 Backend-deploy patch for the venue-native outcome ID acceptance feature described in 2.49.2. Includes a follow-up SDK bug fix discovered during end-to-end verification on Polygon mainnet, plus the doc and test deltas that bring this release to a confirmed working state.