Merge pull request #980 from pmxt-dev/docs/rename-sidecar-to-local-service

docs: rename 'sidecar' to 'local PMXT service' per 2026-05-27 ADR (v2.49.2)

Combined into the same 2.49.2 changelog entry as #979. Published 2.49.0
and 2.49.1 changelog prose intentionally left untouched.

Author: realfishsam

changelog.md

@@ -4,14 +4,19 @@ All notable changes to this project will be documented in this file.
 
 ## [2.49.2] - 2026-06-09
 
-Per-method docs follow-up to 2.49.1 — every Group A method (`createOrder`, `buildOrder`, `submitOrder`, `cancelOrder`, `fetchBalance`, `fetchPositions`, `fetchOpenOrders`, `fetchMyTrades`, `fetchOrder`, `fetchClosedOrders`, `fetchAllOrders`) now has a synchronized `Hosted (recommended)` / `Self-hosted` tab toggle on its reference page, so customers see the hosted endpoint and the v2.49 SDK constructor shape by default and can flip to the local-sidecar variant in place. Mintlify synchronizes tab selection across pages via shared label keys, so the choice persists as the user navigates the API Reference.
+Per-method docs follow-up to 2.49.1 paired with a terminology cleanup. Every Group A method (`createOrder`, `buildOrder`, `submitOrder`, `cancelOrder`, `fetchBalance`, `fetchPositions`, `fetchOpenOrders`, `fetchMyTrades`, `fetchOrder`, `fetchClosedOrders`, `fetchAllOrders`) now has a synchronized `Hosted (recommended)` / `Self-hosted` tab toggle on its reference page, so customers see the hosted endpoint and the v2.49 SDK constructor shape by default and can flip to the local-service variant in place. Mintlify synchronizes tab selection across pages via shared label keys, so the choice persists as the user navigates the API Reference. In parallel, per the 2026-05-27 ADR "Avoid Sidecar Terminology" in the company brain, user-facing references to the local PMXT runtime now use **"local PMXT service"** (or **"local service"** when unambiguous) across the READMEs and `concepts/hosted-vs-self-hosted.mdx`. Internal implementation identifiers and historical changelog entries from earlier releases are intentionally left as-is.
 
 ### Added
 
 - **Docs (`docs/api-reference/`)**: 11 new shadow MDX files — one per Group A method — wrapping the existing OpenAPI auto-render in a `<Tabs>` toggle. `Hosted (recommended)` tab listed first on every page so it's the default; `Self-hosted` second. Tab labels are byte-identical across all 11 files for cross-page sync.
 - **Core (`openapi-hosted.json`)**: 9 new operations documenting the `trade.pmxt.dev/v0/*` trading surface — `buildOrderHosted` (POST `/v0/trade/build-order`), `submitOrderHosted` (POST `/v0/trade/submit-order`), `createOrderHosted` (SDK-convenience POST `/v0/trade/create-order` documentation entry), `cancelOrderHosted` (POST `/v0/orders/cancel/build`), `fetchBalanceHosted` (GET `/v0/user/{address}/balances`), `fetchPositionsHosted` (GET `/v0/user/{address}/positions`), `fetchOpenOrdersHosted` (GET `/v0/orders/open`), `fetchMyTradesHosted` (GET `/v0/user/{address}/trades`), `fetchOrderHosted` (GET `/v0/orders/{order_id}`). Each carries Python + TypeScript `x-codeSamples` using the v2.49 hosted constructor (`pmxtApiKey`, `walletAddress`, `privateKey`), error responses covering 401/403/404/410/422/503, and bearer auth via the existing `bearerAuth` security scheme. Plus 10 new component schemas for the v0 request/response shapes, all referencing existing components (`Order`, `Balance`, etc.) from 2.49.1.
 - **Docs (`docs.json`)**: Trading and "Orders & Positions" sidebar groups now reference the 11 shadow MDX slugs directly, so Mintlify renders the toggle pages instead of auto-generating from `openapi.json`.
 
+### Changed
+
+- **READMEs (`readme.md`, `sdks/python/README.md`, `sdks/typescript/README.md`)**: Every user-visible "sidecar" reference replaced with "local PMXT service" or "local service" depending on context. The Quick Start, "How it works (self-hosted)", and "Self-hosted trading (advanced)" sections now use the canonical terms.
+- **Docs (`docs/concepts/hosted-vs-self-hosted.mdx`)**: "...or run a sidecar" → "...or run a local PMXT service" in the "When hosted is the right choice" list.
+
 ### Fixed
 
 - **Core (`createOrder` / `buildOrder` code samples)**: Pre-existing JSDoc rot — the auto-generated reference pages showed `type="market"` combined with `price=0.55`, an incoherent combination since price is only meaningful for limit orders. Replaced with coherent limit-order samples across all 16 venues (32 createOrder + 32 buildOrder samples, 64 line changes total). The fix lives in `core/scripts/generate-openapi.js`'s `PARAM_OVERRIDES` map so future regeneration emits the correct shape.
@@ -22,6 +27,12 @@ Per-method docs follow-up to 2.49.1 — every Group A method (`createOrder`, `bu
 - **Escrow methods**: `client.escrow.{approve, deposit, withdraw, withdrawals}` aren't in Group A and so don't have toggle pages yet. They're hosted-only (no self-hosted variant exists), so a follow-up could add single-tab reference pages.
 - **Generator capability map gap**: `buildCapabilityMap()` in `core/scripts/generate-openapi.js` only instantiates 13 of the 16 exported exchange classes, omitting `Hyperliquid`, `GeminiTitan`, and `Mock`. Re-running the generator drops their `x-codeSamples`. The merged main spec retains the missing samples from a prior generator run; the surgical fix here didn't disturb them. Worth a real fix in a follow-up.
 
+### Not changed (deliberate)
+
+- **Internal implementation identifiers** (`_resolve_sidecar_host`, `_kill_orphan_sidecars`, `sidecarReadRequest`, `pmxt-ensure-server`, etc.) — per the ADR's scope ("Existing internal implementation identifiers may remain unchanged unless they are user-visible in generated outputs").
+- **Historical changelog entries** for 2.49.1 and earlier — they accurately describe what shipped at the time using the terms in use then.
+- **Auto-generated files** (`docs/api-reference/openapi.json`, `docs/llms-full.txt`, `docs/llms.txt`) — these are emitted by the generator pipeline. The terminology fix flows through the next regeneration via the source files; not hand-editing the artifacts here.
+
 ## [2.49.1] - 2026-06-08
 
 Positioning-shift patch on top of 2.49.0 — the hosted trading mode shipped in 2.49.0 but the docs, READMEs, and OpenAPI schemas still defaulted to the self-hosted sidecar path. This release flips the default everywhere the SDK + docs surface a customer hits: hosted PMXT is the primary experience; self-hosting becomes the advanced escape hatch. No SDK runtime behavior changes — pure documentation, schema, and copy work. Marketing-site changes ship separately in a sibling pmxt-website PR.

docs/concepts/hosted-vs-self-hosted.mdx

@@ -27,7 +27,7 @@ PMXT runs two ways. **Hosted** is the default — it's what `pmxt.Polymarket(pmx
 - You're building a **web or mobile app** and want to keep `pmxt_api_key` server-side while end users keep their private keys client-side.
 - You want **one HTTP surface** across Polymarket and Opinion without learning each venue's order schema.
 - You want **PreFundedEscrow custody** instead of managing venue-native accounts.
-- You don't want to operate the pmxt-core process, manage upgrades, or run a sidecar.
+- You don't want to operate the pmxt-core process, manage upgrades, or run a local PMXT service.
 
 ## When self-hosted is the right choice
 

readme.md

@@ -277,7 +277,7 @@ exchange = pmxt.Limitless(
 
 ## Self-hosted
 
-To self-host pmxt-core on your own machine: `pip install pmxt-core` (Python) or `npm install pmxt-core` (Node.js), then construct any venue client without `pmxt_api_key`. The SDK spawns a local sidecar process; you supply venue credentials directly. See the [self-hosted guide](https://pmxt.dev/docs/guides/self-hosted) for details.
+To self-host pmxt-core on your own machine: `pip install pmxt-core` (Python) or `npm install pmxt-core` (Node.js), then construct any venue client without `pmxt_api_key`. The SDK spawns a local PMXT service; you supply venue credentials directly. See the [self-hosted guide](https://pmxt.dev/docs/guides/self-hosted) for details.
 
 ## Documentation
 

sdks/python/README.md

@@ -2,15 +2,15 @@
 
 A unified Python interface for prediction market exchanges (Polymarket, Kalshi, Limitless, Opinion, and more).
 
-> **Note**: Use with a PMXT API key (hosted, recommended) or self-host the sidecar locally. Get a key at [pmxt.dev/dashboard](https://pmxt.dev/dashboard).
+> **Note**: Use with a PMXT API key (hosted, recommended) or run a local PMXT service. Get a key at [pmxt.dev/dashboard](https://pmxt.dev/dashboard).
 
 ## Installation
 
 ```bash
 pip install pmxt
 ```
 
-**Requirements**: Python >= 3.8. The sidecar server is bundled automatically via the `pmxt-core` dependency — only needed when self-hosting.
+**Requirements**: Python >= 3.8. The local PMXT service is bundled automatically via the `pmxt-core` dependency — only needed when self-hosting.
 
 ## Quick Start
 
@@ -61,7 +61,7 @@ When you pass `pmxt_api_key`, the SDK talks to the PMXT hosted services:
 
 ### How it works (self-hosted)
 
-When you omit `pmxt_api_key`, the Python SDK manages the PMXT sidecar server for you:
+When you omit `pmxt_api_key`, the Python SDK manages the local PMXT service for you:
 
 1. **First API call**: Checks if server is running
 2. **Auto-start**: Starts server if needed (takes ~1-2 seconds)
@@ -128,7 +128,7 @@ See the full [hosted trading guide](https://pmxt.dev/docs/concepts/hosted-tradin
 
 ### Self-hosted trading (advanced)
 
-When self-hosting, you supply venue credentials directly — no `pmxt_api_key`. The SDK spawns a local sidecar process.
+When self-hosting, you supply venue credentials directly — no `pmxt_api_key`. The SDK spawns a local PMXT service.
 
 #### Polymarket
 

sdks/typescript/README.md

@@ -2,7 +2,7 @@
 
 A unified TypeScript/Node.js SDK for prediction markets — The ccxt for prediction markets.
 
-> **Note**: Use with a PMXT API key (hosted, recommended) or self-host the sidecar locally. Get a key at [pmxt.dev/dashboard](https://pmxt.dev/dashboard).
+> **Note**: Use with a PMXT API key (hosted, recommended) or run a local PMXT service. Get a key at [pmxt.dev/dashboard](https://pmxt.dev/dashboard).
 
 ## Installation
 
@@ -53,7 +53,7 @@ When you pass `pmxtApiKey`, the SDK talks to PMXT's hosted services: catalog req
 
 ### How it works (self-hosted)
 
-Omit `pmxtApiKey` to use the local sidecar. Install `pmxt-core` from npm and supply venue credentials directly. See [Self-hosted trading (advanced)](#self-hosted-trading-advanced) below.
+Omit `pmxtApiKey` to use the local PMXT service. Install `pmxt-core` from npm and supply venue credentials directly. See [Self-hosted trading (advanced)](#self-hosted-trading-advanced) below.
 
 ## Core Methods
 
@@ -139,7 +139,7 @@ See the full [hosted trading guide](https://pmxt.dev/docs/concepts/hosted-tradin
 
 ### Self-hosted trading (advanced)
 
-When self-hosting, supply venue credentials directly — no `pmxtApiKey`. The SDK spawns a local sidecar process.
+When self-hosting, supply venue credentials directly — no `pmxtApiKey`. The SDK spawns a local PMXT service.
 
 **Polymarket:**
 ```typescript