feat(export): client config export for Pi and OpenCode (#852)

* feat(export): add client-neutral config export core

Phase 010 of devlog/_plan/260731_client_config_export.

Lifts the OpenCode provider-block builder out of the launcher into a
client-neutral module and adds a Pi serializer beside it. `ocx opencode`
keeps every export it had and its launch path is untouched; the builder
now has one body shared by the launcher and future export surfaces.

The OpenCode output is pinned by a golden captured from the pre-refactor
implementation. Pi emits a models array, always omits `cost` (we have no
price data and zeros would assert "free"), and omits context/maxTokens
when no authoritative context window exists.

Neither serializer ever emits a live key: OpenCode carries
`{env:OPENCODEX_OPENCODE_API_KEY}`, Pi carries `$OPENCODEX_API_KEY`.

* feat(export): add the ocx export CLI command

Phase 020 of devlog/_plan/260731_client_config_export.

`ocx export --client <opencode|pi>` prints the client config. With --json
stdout is the config and nothing else, so an agent can pipe it; without
it, the JSON is followed by the destination path, the merge warning, the
env line, and a count of models shipping without context limits.

--out writes the file but refuses to clobber an existing one without
--force, since the obvious target is a populated config whose other
providers would be lost.

Disabled rows are filtered here, at the /api/models boundary: the export
core dedupes and sorts but cannot see visibility state. A non-array
models payload is an error rather than an empty-model config.

Also corrects two example paths in the plan docs that tripped
privacy:scan.

* feat(export): serve client configs from the management API

Phase 030 of devlog/_plan/260731_client_config_export.

GET /api/client-config?client=<opencode|pi> returns the same bytes the
CLI prints, wrapped in an envelope carrying the destination path, the env
var name, and the model counts the GUI needs to render its states.

The /api/models row logic moved into listManagementModelRows() and both
branches now call it. Copying it would have created a second definition
of which models exist, free to drift from the first; disabled/dedupe
precedence is ~40 lines and only correct in one place.

modelsWithoutLimits is counted from the serialized document rather than
re-derived from input rows, so the number cannot disagree with the bytes
the caller receives. A catalog failure is 503, never a partial 200.

* feat(gui): add the client config panel to the API tab

Phase 040 of devlog/_plan/260731_client_config_export.

Renders what GET /api/client-config returns: a segmented OpenCode/Pi
switch, the JSON itself, copy as the primary action, download as the
secondary one, plus the destination path and the env line the config
references.

Download names the file from the server envelope and announces that
nothing changed yet and the file must be merged. A downloaded config
that reads as "applied" is how someone loses the other providers in
their opencode.json.

Rendering it in a real browser caught two defects a static read missed:
a bare .awi-clientconfig-panel selector ties .api-panel's overflow on
specificity and loses, leaving a clipping ancestor between the JSON and
the page scroller; and a max-height on the JSON made a second capped
scroll region on a tab whose invariant is that the model catalog is the
only one. Both are fixed and the layout invariant test covers the second.

Placement is the fallback 003 §6 allows, since the connect-bar rework
has not landed yet.

* docs: document ocx export and the Pi client

Phase 050 of devlog/_plan/260731_client_config_export.

The export command shipped in the previous four commits with nothing in
docs-site pointing at it, and Pi had no page at all.

Adds the ocx export section to the CLI reference (English plus the four
translated copies), a section in the opencode guide on getting the
provider block into your own config, and a Pi guide.

Three things the docs have to get right, each verified against the code
while writing: the two clients use DIFFERENT env vars
(OPENCODEX_OPENCODE_API_KEY vs OPENCODEX_API_KEY), a loopback bind needs
no admission key at all since shouldInjectApiAuthHeader is just
!isLoopbackHostname, and an exported config must be merged rather than
replace an existing file.

BYOK is split rather than restated: the proxy admission key is what the
exported config references, provider keys stay in providers.<name>.apiKey
and keep their existing home in the providers guide.

The Pi schema is still unverified against a real install and the guide
says so.

* fix(gui): gate the client-config fetch behind an explicit cancel flag

React Doctor flagged the setter after `await` in the panel's effect. The
write was already safe — every result carries its request key and a
superseded run's key no longer matches — but the guard was an
`AbortController.signal.aborted` check, which states "the request was
cancelled", not "this run may no longer write".

An explicit `cancelled` flag set in the cleanup makes the invariant local
to the setter, so a reader (and the linter) can see why a stale resolve
cannot land. The abort stays: it stops the in-flight request, the flag
stops the write.

* test(cli): map /api/client-config to ocx export in the parity sweep

The headless-parity sweep asserts every GUI management endpoint has a
documented CLI resource. Phase 030 added GET /api/client-config without
registering it, so the sweep went red — correctly: the route and the CLI
command shipped in the same unit and `ocx export` is exactly its mirror.

Author: lidge-jun

devlog/_plan/260731_client_config_export/000_plan.md

@@ -0,0 +1,99 @@
+# 000 — Client config export for Pi and OpenCode
+
+Unit: `devlog/_plan/260731_client_config_export/`
+Opened: 2026-07-31 · Work class: C3 · Branch target: `dev`
+
+## Objective
+
+Let a user or an agent take the opencodex model catalog out of the proxy as a
+ready-to-use custom-provider config for Pi and OpenCode, through four surfaces
+that all serve the same bytes: CLI text, CLI `--json`, management API, and a GUI
+panel with copy + JSON download.
+
+## Why this unit exists
+
+The proxy already speaks the wire every client understands. What it does not do is
+hand over the *metadata* — which models exist, what they are called, how large
+their context is — in the dialect each client's config file expects. Today a user
+wanting opencodex in Pi writes that JSON by hand, and gets it wrong, because model
+ids are namespaced and context windows are not guessable.
+
+`ocx opencode` solves half of this already, in memory, at launch, for one client
+(`002`). This unit turns that private capability into an artifact and adds Pi.
+
+## Constraints
+
+| Constraint | Source |
+|-----------|--------|
+| Never serialize a live key; emit an env reference | AGENTS.md security boundary; `001` §3 |
+| Never write or rewrite a user's client config file | existing `ocx opencode` design; `002` §2 |
+| Never guess model metadata; omit what we do not know | existing `limit`-drop rule; `002` §4 |
+| One payload, four presentations | `003` §2 |
+| OpenCode V1 schema only | `001` §2 |
+| Bun-native TypeScript, `dev` branch | AGENTS.md |
+
+## Scope boundary
+
+IN
+- Client-neutral export core with OpenCode + Pi serializers.
+- `ocx export --client <id> [--json] [--out]`.
+- `GET /api/client-config?client=<id>`.
+- GUI panel: client switch, JSON preview, copy, download.
+- Tests at each phase; docs-site update when the CLI surface lands.
+
+OUT
+- OpenCode V2 schema migration (recorded in `001`, not built).
+- Automatic merging into an existing user config file.
+- Any client beyond Pi and OpenCode. Claude Desktop already has its own path.
+- Changes to routing, adapters, or the catalog itself.
+- Pricing metadata. We do not have it; `cost` is omitted rather than faked.
+
+## Work-phase map
+
+Dependency-ordered. Each phase is one full PABCD cycle and closes with something
+independently verifiable.
+
+| Phase | Doc | Delivers | Verified by |
+|-------|-----|----------|-------------|
+| 1 | `010_export_core.md` | `src/clients/config-export.ts`; OpenCode builder relocated, Pi serializer added | unit tests + golden diff against pre-refactor output |
+| 2 | `020_cli_surface.md` | `ocx export` with `--json` / `--out` | CLI tests; stdout parses clean under `--json` |
+| 3 | `030_management_api.md` | `GET /api/client-config` | route test; payload identical to CLI `--json` |
+| 4 | `040_gui_panel.md` | GUI panel with copy + download | GUI test + rendered check |
+
+The order is the build order, not a schedule: `020`, `030`, `040` each import the
+core, and `040` renders what `030` returns. Nothing later can be built first.
+
+## Research documents
+
+| Doc | Contents |
+|-----|----------|
+| `001_client_config_survey.md` | Pi + OpenCode V1/V2 schemas, injection points, absence of a standard, V1 decision |
+| `002_existing_surface_inventory.md` | What `ocx opencode` already does, the corrected gap, catalog metadata availability |
+| `003_export_ux_design.md` | Design Read, dials, Lazy-User Gate, five UX states, download rules, placement |
+
+## Open assumptions
+
+1. **Pi schema is unverified against a real install.** Taken from published docs
+   only (`001` §2). The cycle that ships Pi must diff against a real
+   `~/.pi/agent/models.json` or ship the Pi client marked experimental.
+2. **The API page layout rework may or may not have landed** when `040` runs.
+   `003` §6 gives both placements; the panel is layout-independent.
+3. **32k output budget** is a schema stand-in inherited from `ocx opencode`, not a
+   per-model truth. If an authoritative max-output field ever reaches
+   `CatalogModel`, both serializers should switch to it.
+
+## Acceptance
+
+The unit is DONE when all four phases have closed with their evidence, `bun run
+typecheck` and `bun run test` are green, `bun run privacy:scan` is green, and a
+config exported from each of the four surfaces is byte-identical for the same
+client and catalog state.
+
+Terminal outcomes other than DONE: `BLOCKED` if Pi's real schema contradicts the
+survey badly enough to need a new design; `NEEDS_HUMAN` if a decision outside this
+plan's boundary appears.
+
+## Status
+
+Roadmap written 2026-07-31 during the docs-only cycle. No implementation has
+started; no production file has been modified by this unit.

devlog/_plan/260731_client_config_export/001_client_config_survey.md

@@ -0,0 +1,155 @@
+# 001 — External client config survey
+
+Research only. No diffs here; implementation designs live in the decade docs.
+
+Scope of the survey: where a user (or an agent) drops a custom OpenAI-compatible
+provider so that Pi and OpenCode can call the opencodex proxy, what JSON those
+files require, and whether any cross-vendor standard governs the shape.
+
+## 1. Is there a standard?
+
+No. There is no formal specification body governing agent-client provider
+configuration. What exists instead is a stack of de-facto layers:
+
+| Layer | What it standardizes | Who honors it |
+|-------|----------------------|---------------|
+| OpenAI `/v1` wire (`/chat/completions`, `/responses`, `/models`) | request/response bytes | effectively everyone |
+| Anthropic `/v1/messages` wire | request/response bytes | Claude clients, our Messages surface |
+| `@ai-sdk/openai-compatible` (Vercel AI SDK) | adapter package name + option names | OpenCode, several TS agents |
+| models.dev | model metadata registry (context, cost, modality) | OpenCode, Pi metadata seeds |
+| per-client JSON Schema (`https://opencode.ai/config.json`) | one client's config file only | that client |
+
+The consequence for this unit: the transport half is already solved — the proxy
+speaks `/v1` and clients speak `/v1`. Everything left is **metadata translation**
+into per-client dialects, and each dialect is a moving target owned by one vendor.
+
+Critically, **models.dev does not populate custom providers.** A user-defined
+provider block gets no inherited context window, no pricing, no modality flags.
+Whatever we do not emit ourselves, the client simply does not know.
+
+## 2. Where custom providers are injected
+
+### OpenCode
+
+Three layers, highest priority first:
+
+| Layer | Location | Notes |
+|-------|----------|-------|
+| Inline runtime | `OPENCODE_CONFIG_CONTENT` env var | outranks every file; what `ocx opencode` uses today |
+| Project | `<git root>/opencode.json` or `.jsonc` | committed per repo |
+| Global | `~/.config/opencode/opencode.json`, XDG-aware via `XDG_CONFIG_HOME` | the file most users hand-edit |
+
+JSONC is accepted for the file layers (comments must survive a round trip, which
+is why we never rewrite a user's file — see `002`).
+
+V1 schema (current, what we generate):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "opencodex": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "opencodex",
+      "options": { "baseURL": "http://127.0.0.1:10100/v1", "apiKey": "{env:OPENCODEX_OPENCODE_API_KEY}" },
+      "models": {
+        "anthropic/claude-opus-5": { "name": "Claude Opus 5", "limit": { "context": 200000, "output": 32000 } }
+      }
+    }
+  }
+}
+```
+
+V2 schema (documented at `opencode.ai/v2/docs/models`) renames nearly every key:
+
+| Concept | V1 | V2 |
+|---------|----|----|
+| container | `provider` | `providers` |
+| adapter | `npm: "@ai-sdk/openai-compatible"` | `package: "aisdk:@ai-sdk/openai-compatible"` |
+| endpoint | `options.baseURL` | `settings.baseURL` |
+| upstream id | `models.<k>.id` | `models.<k>.modelID` |
+| credentials | `options.apiKey` / auth store | `env[]` |
+| new in V2 | — | `capabilities`, `variants`, `disabled` |
+
+**Decision: stay on V1.** The shipped launcher already emits V1 and that path is
+exercised by tests; switching would break it in exchange for `capabilities` and
+`variants` fields we have no authoritative data to fill. V2 is recorded here so a
+later migration starts from a written diff rather than a re-survey.
+
+### Pi
+
+Single global file: `~/.pi/agent/models.json`.
+
+```json
+{
+  "providers": {
+    "opencodex": {
+      "baseUrl": "http://127.0.0.1:10100/v1",
+      "api": "openai-completions",
+      "apiKey": "$OPENCODEX_API_KEY",
+      "models": [
+        {
+          "id": "anthropic/claude-opus-5",
+          "name": "Claude Opus 5",
+          "reasoning": false,
+          "input": ["text"],
+          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
+          "contextWindow": 200000,
+          "maxTokens": 32000
+        }
+      ]
+    }
+  }
+}
+```
+
+Shape differences that matter for the serializer:
+
+- `models` is an **array**, not a keyed object. Model identity lives in `id`.
+- `cost` demands all four fields when present.
+- `apiKey` supports `$ENV_VAR` interpolation (bare `$NAME`, not `{env:NAME}`).
+- `api` selects the wire dialect; `openai-completions` is ours.
+
+**Verification status: UNVERIFIED against a real installation.** The shape above
+comes from Pi's published `models.md` and `pi.dev/docs/latest/custom-provider`.
+No `~/.pi/agent/models.json` was read on this machine. The first implementation
+cycle touching Pi must diff this against a real file before shipping.
+
+### Cross-client field map
+
+| Concept | Pi | OpenCode V1 |
+|---------|----|-------------|
+| container | `providers` | `provider` |
+| adapter | `api: "openai-completions"` | `npm: "@ai-sdk/openai-compatible"` |
+| endpoint | `baseUrl` | `options.baseURL` |
+| model container | array | keyed object |
+| context | `contextWindow` | `limit.context` |
+| max output | `maxTokens` | `limit.output` |
+| price | `cost{4}` | absent |
+| modality | `input[]` | absent |
+| key reference | `$VAR` | `{env:VAR}` |
+
+Only four concepts are universal: endpoint, adapter kind, model id, and the
+context/output pair. Everything else is one client's luxury.
+
+## 3. Credential handling
+
+All three injection paths support an environment reference, so no exporter needs
+to serialize a live `ocx_...` key. Pi takes `$VAR`, OpenCode takes `{env:VAR}`,
+and OpenCode additionally has an auth store. AGENTS.md treats token serialization
+as a release blocker, so emitting a reference is not merely polite — writing the
+plaintext key into an exported file would be a security-review failure.
+
+The exported artifact therefore carries a variable name, and every surface that
+hands the file over must also tell the user which variable to export.
+
+## 4. Sources
+
+- Pi: `github.com/earendil-works/pi` `packages/coding-agent/docs/models.md`; `pi.dev/docs/latest/custom-provider`
+- OpenCode V1: `opencode.ai/docs/providers`, `opencode.ai/config.json`
+- OpenCode V2: `opencode.ai/v2/docs/models`
+- AI SDK adapter: `@ai-sdk/openai-compatible`
+- Metadata registry: `models.dev`
+
+All external claims were read during the 2026-07-31 P phase. Client schemas drift;
+re-verify before any cycle that changes serializer output.

devlog/_plan/260731_client_config_export/002_existing_surface_inventory.md

@@ -0,0 +1,91 @@
+# 002 — What already exists, and what the real gap is
+
+Research only. Written because the first pass of this unit's P phase proposed
+building things that were already shipped. Recording the correction here so a
+later cycle's P does not repeat the same miss.
+
+## 1. Correction to the initial survey
+
+The opening research turn concluded that OpenCode export had to be built from
+scratch and listed three "design blockers" (slash-bearing model ids, credential
+leakage, missing `limit.output`). All three were already solved in
+`src/cli/opencode.ts`, a 701-line module that predates this unit.
+
+| Claimed blocker | Actual state |
+|-----------------|--------------|
+| `provider/model` ids produce a double slash | `opencodeModelKey()` emits `provider/id` for routed and a bare slug for native; OpenCode splits on the FIRST slash, so the nested id survives |
+| Exported config would leak `ocx_...` | Only `{env:OPENCODEX_OPENCODE_API_KEY}` is serialized; the real value rides the child process env |
+| `limit.output` has no authoritative source | `SCHEMA_REQUIRED_OUTPUT_BUDGET` (32k, clamped to context) fills the schema-required half, and the whole `limit` block is dropped when no authoritative context exists |
+
+The lesson is procedural: a survey of external formats is not a survey of our own
+tree. Both halves are required before a phase map is credible.
+
+## 2. Inventory of the shipped surface
+
+### `src/cli/opencode.ts`
+
+| Export | Role |
+|--------|------|
+| `buildOpencodeProviderBlockFromCatalog` | catalog rows -> V1 provider block. The real serializer core |
+| `buildOpencodeProviderBlock` | test-facing wrapper over the same builder |
+| `opencodeModelKey` | `provider/id` vs bare native slug |
+| `opencodeProxyBaseUrl` | `http://<host>:<port>/v1` |
+| `opencodeCatalogFromProxyRows` | `GET /api/models` rows -> catalog entries, drops disabled + dupes |
+| `mergeOpencodeRuntimeConfig` | merges inherited inline config, overrides only `provider.opencodex` |
+| `buildOpencodeConfig` / `serializeOpencodeRuntimeConfig` | assemble + stringify the inline runtime layer |
+| `opencodeGlobalConfigPath` / `opencodeProviderOverridePath` / `projectConfigOverridesProvider` | detect (never write) user files |
+
+Design properties worth preserving verbatim:
+
+- **Never writes user config.** File layers are read for detection only; injection
+  goes through `OPENCODE_CONFIG_CONTENT`. This avoids clobbering comments,
+  relative `{file:...}` paths, and unrelated MCP credentials.
+- **Never guesses metadata.** Absent context window means no `limit` block, not a
+  fabricated one.
+- **Never serializes a secret.**
+
+### Adjacent precedents
+
+- `src/cli/claude-desktop.ts` — writes a Claude Desktop 3P config.
+- `gui/src/pages/ClaudeDesktop.tsx:313` — `exportProfile()` does Blob +
+  `URL.createObjectURL` + `anchor.download`, then announces to a live region.
+  This is the house pattern for browser-side JSON download and the 040 phase
+  reuses it rather than inventing a second one.
+- `src/cli/access.ts` — the `ocx access ...` family establishes the CLI contract
+  this unit extends: `--json` on every subcommand, `printData(value, wantsJson, lines)`
+  emitting either raw JSON or human lines from the SAME value.
+- `src/server/management/model-routes.ts:115` — `GET /api/models`, the authenticated
+  route whose rows already feed the OpenCode builder.
+
+## 3. The actual gap
+
+`ocx opencode` produces a provider block **only in memory, only at launch**, and
+only for OpenCode. Three things are missing:
+
+1. **No artifact.** A user who wants the provider block in their own
+   `~/.config/opencode/opencode.json` cannot get it out of opencodex. There is no
+   command that prints it and no file to download.
+2. **No Pi support at all.** No serializer, no command, no surface.
+3. **No shared abstraction.** The builder is private to the launcher module and
+   shaped around one client's schema, so a second client cannot reuse it as-is.
+
+Everything this unit builds is downstream of closing those three. The transport,
+the catalog, and the security posture are already correct.
+
+## 4. Catalog metadata availability
+
+Checked because every serializer depends on it:
+
+| Field | Source | Available? |
+|-------|--------|-----------|
+| context window | `CatalogModel.contextWindow`; `NATIVE_OPENAI_CONTEXT_OVERRIDES` + upstream `context_window` for native | yes, with a documented 128k fallback in `parsing.ts:287` |
+| display name | `CatalogModel.displayName` | yes, optional |
+| max output | none | **no** — 32k schema stand-in only |
+| price | not on `CatalogModel` | **no** |
+| input modality | `CatalogModel.inputModalities` | yes |
+| reasoning | `CatalogModel.reasoningEfforts` | yes, as effort list |
+
+Consequence for Pi: `cost` cannot be filled honestly. Emitting zeros would assert
+"this model is free," which is false for routed providers. The 010 phase must
+decide omit-vs-zero, and the survey's field table says `cost` is optional when the
+key is absent — so omission is the honest option.