feat(docs): per-method hosted/self-hosted toggle on Group A reference pages (v2.49.2)

[realfishsam]

Follow-up to v2.49.1. Adds a synchronized Hosted (recommended) / Self-hosted tab toggle to every Group A method reference page so customers see the hosted endpoint and v2.49 SDK constructor shape by default, and can flip to the local-sidecar variant in place. Mintlify syncs tab selection across pages via shared label keys.

What's in this PR

11 shadow MDX files (docs/api-reference/{buildOrder,cancelOrder,createOrder,fetchAllOrders,fetchBalance,fetchClosedOrders,fetchMyTrades,fetchOpenOrders,fetchOrder,fetchPositions,submitOrder}.mdx) — each wraps the existing OpenAPI auto-render in a <Tabs> toggle. Tab labels byte-identical across all 11 files for cross-page sync.

9 new operations in openapi-hosted.json documenting trade.pmxt.dev/v0/*: buildOrderHosted, submitOrderHosted, createOrderHosted, cancelOrderHosted, fetchBalanceHosted, fetchPositionsHosted, fetchOpenOrdersHosted, fetchMyTradesHosted, fetchOrderHosted. Each with Python + TypeScript x-codeSamples, error coverage 401/403/404/410/422/503, bearer auth.

10 new component schemas for the v0 request/response shapes, reusing existing components from 2.49.1.

docs.json updated so Trading + Orders & Positions sidebar groups point at the shadow MDX slugs.

JSDoc rot fix: createOrder / buildOrder code samples used to show type="market" with price=0.55 (incoherent — price is limit-only). Replaced with coherent limit samples across all 16 venues via PARAM_OVERRIDES in the generator.

Changelog 2.49.2 entry added.

Not addressed (flagged in changelog)

• fetchClosedOrdersHosted / fetchAllOrdersHosted raise NotSupported in hosted mode (no underlying endpoint). Shadow MDX surfaces this via <Warning> linking to fetchMyTrades.
• Escrow methods are hosted-only, not in Group A scope. Future PR.
• Generator capability-map gap (Hyperliquid/GeminiTitan/Mock missing). Future PR.

Test plan

• Mintlify preview renders all 11 toggle pages
• Click Self-hosted on createOrder → navigate to fetchBalance → confirm Self-hosted tab is still active (sync)
• Confirm Hosted tab is active by default on first load
• No regressions on existing OpenAPI-auto-rendered pages outside Group A

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
PMXT	🟢 Ready	View Preview	Jun 8, 2026, 9:26 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[realfishsam]

PR Review: FAIL

What This Does

This adds manual “Hosted (recommended)” / “Self-hosted” tabs for 11 Group A API reference pages and adds hosted v0 trading operations to docs/api-reference/openapi-hosted.json. The intended consumer impact is that hosted SDK/API usage becomes visible by default while self-hosted local-service examples remain available.

Blast Radius

Docs/API-reference only plus the OpenAPI generator sample overrides: 11 new docs/api-reference/*.mdx shadow pages, docs/docs.json sidebar wiring, docs/api-reference/openapi-hosted.json, docs/api-reference/openapi.json, changelog.md, and core/scripts/generate-openapi.js example parameters. No exchange runtime, SDK runtime, auth, or router behavior changed.

Consumer Verification

Before (base branch):
The API reference sidebar pointed directly at self-hosted OpenAPI operations like POST /api/{exchange}/createOrder and did not have per-method hosted/self-hosted tabs for Group A pages.

After (PR branch):
The new shadow pages exist and docs/docs.json points Trading / Orders & Positions at slugs such as api-reference/createOrder, api-reference/buildOrder, and api-reference/fetchBalance. JSON validation passes for docs/api-reference/openapi-hosted.json, docs/api-reference/openapi.json, and docs/docs.json.

However, the hosted operation schemas added to openapi-hosted.json are not actually rendered or linked from those new pages: the shadow pages contain no <OpenApi ...> component, and the Trading / Orders & Positions groups in docs/docs.json no longer declare an openapi source for these operations. One page even links to [hosted fetchBalanceHosted operation](#), confirming the schema link is currently a placeholder rather than a usable reference.

Test Results

• Build: PASS (npm run build --workspace=pmxt-core)
• Unit tests: PASS (npm test --workspace=pmxt-core: 24 passed, 1 skipped; 644 passed, 3 skipped)
• Server starts: NOT RUN — docs-only surface for this PR.
• E2E smoke: FAIL for docs/manual reference review: hosted schema rendering/linkage is missing, and several curl snippets are malformed.

Findings

1. docs/docs.json:173-191 + new docs/api-reference/*.mdx pages — The hosted v0 operation schemas added in openapi-hosted.json are effectively unreachable from the new Group A method pages. The new sidebar entries point to manual MDX slugs, but those groups do not set openapi: "api-reference/openapi-hosted.json", and the pages themselves do not embed an <OpenApi> component. A reader gets examples/prose, but not the full hosted request/response schema promised by this PR.
2. docs/api-reference/fetchBalance.mdx:45 — Broken placeholder link: [hosted fetchBalanceHosted operation](#). This ships a dead link exactly where the page says the user can see the full hosted request/response schema.
3. docs/api-reference/buildOrder.mdx:62, submitOrder.mdx:61, cancelOrder.mdx:45, fetchOpenOrders.mdx:42, fetchBalance.mdx:41, fetchPositions.mdx:43, fetchMyTrades.mdx:43, fetchOrder.mdx:41 — Hosted curl examples have malformed Authorization headers such as -H "Authorization: Bearer *** \ or -H "Authorization: Bearer *** with no closing quote. Copy/paste from the new default hosted docs will fail before reaching trade.pmxt.dev.

PMXT Pipeline Check

• Field propagation (3-layer): N/A — docs/schema only; no unified runtime fields changed.
• OpenAPI sync: ISSUE — hosted operations were added to openapi-hosted.json, but the new shadow pages/sidebar do not render or link those schemas.
• Financial precision: N/A
• Type safety: N/A for runtime; JSON syntax validates.
• Auth safety: ISSUE in docs — curl auth header examples are syntactically invalid.

Semver Impact

patch -- documentation/reference-site fix, assuming no published SDK/runtime behavior changes.

Risk

I could not run Mintlify locally, so the exact rendered failure mode may differ, but the repository evidence is concrete: the new pages contain no schema-rendering component, one schema link is #, and multiple default hosted curl snippets are malformed in source.