zcode-workbuddy-connect 0.0.0-stage → 1.0.0

package/.zcode-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "zcode-workbuddy-connect",
+  "version": "1.0.0",
+  "description": "Bring WorkBuddy desktop-app models — domestic and international (GLM-5.3, DeepSeek-V4-Pro, Kimi-K3, MiniMax-M3, Hy3, GPT-5.6, Gemini-3.5-Flash …) — into ZCode as OpenAI-compatible providers, with zero configuration.",
+  "description_i18n": {
+    "en": "Bring WorkBuddy desktop-app models, domestic and international, into ZCode as OpenAI-compatible providers, with zero configuration.",
+    "zh-CN": "把 WorkBuddy 桌面 App 的国内版与国际版模型（GLM-5.3、DeepSeek-V4-Pro、Kimi-K3、MiniMax-M3、Hy3、GPT-5.6、Gemini-3.5-Flash 等）零配置接入 ZCode 的模型供应商。"
+  },
+  "author": {
+    "name": "hawchou1995 (a port of corrinehu/dsh-workbuddy-connect, MIT)"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/hawchou1995/zcode-workbuddy-connect",
+  "keywords": [
+    "workbuddy",
+    "codebuddy",
+    "openai-compatible",
+    "provider",
+    "glm",
+    "deepseek"
+  ],
+  "skills": "skills",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "process",
+            "command": "node",
+            "args": [
+              "${ZCODE_PLUGIN_ROOT}/hooks/service-ensure.mjs"
+            ],
+            "timeoutMs": 60000,
+            "statusMessage": "Starting the WorkBuddy endpoint"
+          }
+        ]
+      }
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Corrine Hu
+Copyright (c) 2026 workbuddy-connect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,49 @@
+# Attribution
+
+This project is a port of **[corrinehu/dsh-workbuddy-connect](https://github.com/corrinehu/dsh-workbuddy-connect)**
+(MIT, Copyright (c) 2026 Corrine Hu) from the DeepSeek Harness plugin API to
+ZCode's.
+
+The upstream project in turn ports its WorkBuddy wire behaviour from
+**[Sliverkiss/workbuddy2api](https://github.com/Sliverkiss/workbuddy2api)** (MIT).
+
+## What came from where
+
+**Brought over from the upstream (behaviour preserved deliberately, because it is
+what makes the endpoint work at all):**
+
+- The upstream HTTP client: chat streaming, token refresh, model catalog,
+  credit/billing endpoints, error classification
+- The wire quirks: forced `stream: true`, `developer` → `system` role rewrite,
+  string-form `tool_choice`, the `X-No-*` / `X-User-Id` / `X-Product` header set
+- The desktop-shaped chat `User-Agent` and its installed-App → saved → fallback
+  resolution order
+- The credential model: read the desktop app's sign-in file read-only, refresh
+  into a separate plugin-owned copy, prefer identity over expiry
+- The loopback OpenAI-compatible endpoint and its inbound hardening (loopback
+  Host, loopback Origin, JSON content type, constant-time bearer check)
+- The promotion/billing display rules, including dropping a rate that can no
+  longer be stood behind rather than keep claiming a discount
+
+**Rewritten for this port:**
+
+- Everything that touched DSH APIs: the provider adapter, the settings card, the
+  Composer probe control, the DSH-home path resolution, the atomic-write
+  dependency. ZCode has no equivalents, so the provider half became
+  configuration and the UI half was dropped.
+- The shim became a standalone service rather than an in-process object.
+- The endpoint bearer became persisted rather than per-process, because the
+  client records it in a config file and it must survive restarts.
+- Reasoning-level probing was dropped (see the README).
+- SSE handling was rewritten after testing found three real defects in the port
+  — see the git history.
+- Windows is the primary target, so the App-version and credential probes cover
+  Windows install roots rather than macOS bundles.
+- The international catalog's User-Agent was CORRECTED relative to upstream:
+  the gateway now rejects the App-shaped UA with HTTP 400 (code 12403) and
+  requires the CLI-form UA (live-verified 2026-09-18). Upstream's assumption
+  no longer holds on today's wire.
+
+## Licence
+
+MIT throughout. See [LICENSE](./LICENSE).

package/README.md

@@ -1,3 +1,265 @@
-# Temporary Holding Version
+# zcode-workbuddy-connect
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use the models inside the **WorkBuddy desktop app** from ZCode (or any
+OpenAI-compatible client), with zero configuration.
+
+A port of [corrinehu/dsh-workbuddy-connect](https://github.com/corrinehu/dsh-workbuddy-connect)
+(MIT) from the DeepSeek Harness plugin API to ZCode's, keeping the original's
+wire behaviour and discarding the parts that have no ZCode equivalent.
+
+```
+ZCode ──(OpenAI chat-completions)──▶ 127.0.0.1:39271 ──▶ copilot.tencent.com
+                                       local endpoint        (WorkBuddy)
+```
+
+## Why this shape
+
+The upstream plugin registered models into DSH's own provider registry and drew
+a settings card in DSH's UI. ZCode has **no "register an LLM provider" plugin
+slot**, so a literal port is impossible. What ZCode *does* have is native
+support for third-party models configured as
+`api.type: "openai-chat-completions"` with a `baseUrl` and API key — and the
+original plugin already contained a loopback OpenAI-compatible shim
+(`src/shim.ts`). Extracting that shim into a standalone service and pointing a
+ZCode provider at it yields something the original could not give: the models
+appear as first-class entries in ZCode's model selector, driving the normal agent
+loop with tool calls, images and streaming.
+
+The discarded parts are the ones with no ZCode surface: the settings card, the
+Composer probe control, and the reasoning-level detection feature. Reasoning
+levels now use the efforts the upstream catalog declares, with no probing
+requests (which would have consumed credit with nowhere to show the result).
+
+## Layout
+
+```
+.zcode-plugin/plugin.json      plugin manifest (skills + SessionStart hook)
+skills/workbuddy-models/       operational skill for the agent
+hooks/service-ensure.mjs       starts the endpoint at session start
+src/                           the service (no dependencies; Node >= 18)
+  upstream.js                  WorkBuddy wire client: chat, refresh, catalog, billing
+  auth.js                      reads the desktop app's sign-in; refreshes into our own copy
+  catalog.js                   model roster + static fallback
+  server.js                    the loopback OpenAI-compatible endpoint
+  loopback.js                  Host/Origin guards
+  client-identity.js           desktop-shaped chat User-Agent
+  app-version.js               installed-App version resolution
+  config.js                    runtime paths
+  cli.js                       command-line interface
+bin/cli.mjs                    entry point
+```
+
+## Commands
+
+```sh
+node bin/cli.mjs serve              # run the endpoint (foreground)
+node bin/cli.mjs status             # sign-in, credit, model roster
+node bin/cli.mjs doctor             # diagnose credentials/upstream/endpoint
+node bin/cli.mjs refresh            # re-pull the roster
+node bin/cli.mjs setup              # (re)write the ZCode provider entry
+node bin/cli.mjs service-status     # is it reachable; is autostart registered
+node bin/cli.mjs install-service    # register a logon autostart launcher
+node bin/cli.mjs uninstall-service  # remove it
+node bin/cli.mjs logout             # drop our token copy (desktop app untouched)
+node bin/cli.mjs token              # print the endpoint bearer
+```
+
+## Install
+
+1. Put this directory anywhere and add its **path** to ZCode's
+   `plugins.dirs` in `%USERPROFILE%\.zcode\cli\config.json`:
+
+   ```json
+   { "plugins": { "dirs": ["<absolute-path-to-this-repo>"] } }
+   ```
+
+   Plugins found this way get the marketplace id `inline` and are enabled by
+   default. The listed directory **is** the plugin root — do not nest it.
+
+2. Write the provider entries (one per signed-in region):
+
+   ```sh
+   node bin/cli.mjs setup
+   ```
+
+   `setup` refuses to guess: it writes the roster the upstream actually reports,
+   including each model's real context window, output ceiling and vision
+   support. It also **validates before writing** — the document is serialised to
+   a temp file and run through `docs/validate-provider-config.mjs`, and is only
+   renamed into place if it passes. See the strict-schema note below for why
+   that gate is not optional.
+
+3. Restart ZCode. The `SessionStart` hook starts the endpoint; the models appear
+   in the model selector under **WorkBuddy** (CN) and **WorkBuddy AI**
+   (international).
+
+### WorkBuddy 5.6 encrypted credentials
+
+Since 5.6 the desktop app no longer writes its sign-in as plain JSON: both
+token fields arrive sealed in a `{$wbEncrypted:1, envelope}` wrapper opened with
+AES-256-GCM. The at-rest key lives in the app's own (Electron-modified) process,
+so the plugin unlocks a sealed file by running **the app's own Electron binary
+once as plain Node** (`ELECTRON_RUN_AS_NODE=1`) and asking its private
+`workbuddyStorage` binding for the sealed secret. The key is derived with
+`sha256(atRestSecretKey)`, cached in memory only, and never written anywhere.
+
+This is automatic on Windows and macOS for the CN app, whose install locations
+are the platform defaults:
+
+| Platform | CN (`WorkBuddy`) | International (`WorkBuddy AI`) |
+|---|---|---|
+| Windows | `C:\Program Files\WorkBuddy\WorkBuddy.exe` | `C:\Program Files\WorkBuddyAI\WorkBuddyAI.exe` |
+| macOS | `/Applications/WorkBuddy.app/Contents/MacOS/Electron`, falling back to a Spotlight search for the CN bundle id | none — `WORKBUDDY_ELECTRON_BIN` only |
+| Linux | none — `WORKBUDDY_ELECTRON_BIN` only | none — `WORKBUDDY_ELECTRON_BIN` only |
+
+**Overriding the binary.** If your app lives somewhere else, point the plugin at
+it:
+
+```sh
+set WORKBUDDY_ELECTRON_BIN=C:\path\to\WorkBuddy.exe
+```
+
+The variable must be set in the environment the **service** starts in — for the
+ZCode `SessionStart` hook, that means ZCode's own environment, so restart ZCode
+after setting it. Setting it only in a terminal does nothing.
+
+There is deliberately **no automatic search on Linux**, and **none at all for
+the international app on macOS/Linux**: upstream restricts auto-discovery to the
+one product and platform whose encrypted-credential chain has been verified
+live, and executing a binary that has not been identified is not something a
+credential reader should do on a guess.
+
+`node bin/cli.mjs doctor` reports what it found — the file's format
+(`encrypted` is the healthy state for a current install), which Electron binary
+the unlock would use, and, when the unlock fails, a reason naming sizes, key ids
+and exit codes only.
+
+The reasoning behind this — and where it deliberately differs from upstream's
+discovery policy — is in `docs/adr/0004-workbuddy-56-at-rest-credentials.md`.
+
+### Two regions, two mounts
+
+Both regions are served from one endpoint, told apart by the URL the client
+uses — not by renaming models:
+
+| Region | Provider | Base URL |
+|---|---|---|
+| CN | `workbuddy` | `http://127.0.0.1:39271/v1` |
+| International ("WorkBuddy AI") | `workbuddy-ai` | `http://127.0.0.1:39271/ai/v1` |
+
+Seven model ids exist in both regions (`glm-5.3`, `glm-5.2`, `hy3`,
+`hy4-preview`, `deepseek-v4.1-flash`, `kimi-k2.8-preview`, `kimi-k2.6`) with
+different windows and rates. They are kept apart by the mount rather than by an
+id prefix, because ZCode's picker renders the **raw model id and nothing else**
+in each row while grouping rows under a provider header — so `glm-5.3` under
+"WorkBuddy" and `glm-5.3` under "WorkBuddy AI" are already unambiguous to the
+user, while a `wbai:` prefix was pure noise in the one string they read. A
+leading `wbai:` on a chat request is still *accepted* and wins over the mount, so
+an older config keeps routing correctly. See `docs/adr/0003-region-by-url-path.md`.
+
+### Limits written into ZCode
+
+Both limits are taken at their **maximum**:
+
+| ZCode field | Source | Why not the alternative |
+|---|---|---|
+| `properties.contextWindow` | upstream `maxInputTokens` | `contextWindow.defaultLength` is a softer tier the UI offers and can be up to 3.3× smaller; declaring it makes ZCode compact the conversation early and waste the window. Verified by probe: 312,856 tokens accepted, 1,294,869 rejected. |
+| `optionSpecs.maxOutputTokens.max` | upstream `maxOutputTokens` | This is the ceiling on the value a user may select. There is no `maxTokens` property — see below. |
+
+`map` is deliberately left out of `optionSpecs.maxOutputTokens`: the shipped
+`openai-chat-completions` API rule already supplies
+`{'max_completion_tokens': maxOutputTokens}`, so restating it would only add an
+expression-language failure mode. `serve` reports the same window through
+`/v1/models`; `--default-context-window` reverts to the softer number.
+
+### The strict-schema trap
+
+ZCode parses `provider_config.json` with zod schemas that are `.strict()`, and
+its failure mode is brutal: **one unrecognised key anywhere makes ZCode discard
+the entire personal provider config** and fall back to an empty one — taking
+every other provider you had configured (OpenRouter, DeepSeek, …) with it, and
+surfacing no error. Two keys are easy to get wrong:
+
+- **`maxTokens` is not a property.** Output limits live in
+  `optionSpecs.maxOutputTokens.max`.
+- **`provider: []` is not a config key.** It belongs to the legacy CLI registry
+  in `config.json`, a different document.
+
+Both mistakes existed in this codebase and were caught by the validator's first
+run. After any hand-edit, check it yourself:
+
+```sh
+node docs/validate-provider-config.mjs
+```
+
+## Stream lifecycle (why a turn never "just stops")
+
+Long turns are where every proxy flaw looks identical: the model goes quiet,
+the spinner keeps turning, nothing errors. Five rules prevent that:
+
+| Situation | What the endpoint does |
+|---|---|
+| Upstream silent for 180 s on an open stream | `error` frame (`type: "upstream_stalled"`) + `finish_reason: "network_error"` + `[DONE]`, and the upstream call is aborted. The client retries instead of hanging behind our heartbeat. |
+| Upstream closes without a finish frame | Finishes with `finish_reason: "length"`. A cut answer is reported as cut, never rewritten to `stop`. |
+| Tool calls streamed, finish labelled `stop` | Corrected to `finish_reason: "tool_calls"`; the mirror case (promising `tool_calls` with no call delivered) still degrades to `stop`. |
+| Turn produced nothing at all | An `error` frame so the client retries rather than accepting an empty assistant message. |
+| Client disconnects mid-stream | The upstream request is aborted, so a cancelled turn stops being generated (and billed) immediately. |
+
+Watchdog interval: `ZC_STREAM_IDLE_TIMEOUT_MS` (default `180000`). The 10 s
+heartbeats keep the *client's* read timer alive but deliberately do not reset
+the watchdog, which only counts real upstream bytes.
+
+## Design decisions
+
+| Decision | Why |
+|---|---|
+| Standalone loopback service, not an MCP server | An MCP tool cannot drive ZCode's agent loop; a provider can. Native streaming, tool calls and images come for free. |
+| Zero runtime dependencies | Node 18+ has `fetch`, `AbortSignal.timeout` and `http`. Fewer moving parts to break, and no install step. |
+| Dual region, one service | CN and international (WorkBuddy AI) variants share one endpoint, separated by URL mount: the root (`/v1`) serves CN and `/ai/v1` serves the international region. The mount is what keeps the 7 shared ids (glm-5.3, hy3…) distinct, so the region never has to be encoded into the model id a client displays. A region whose app is not signed in is skipped at `setup` and exposes no models. |
+| Fixed port + persisted bearer | The client records the bearer in its own config, so it must survive restarts. A per-process secret would break on every restart. |
+| Credential copy kept separate from the desktop app | The app's sign-in file is read-only input. Refreshes go to our own state dir, so the plugin can never break the app's login. |
+| Startup folder for autostart | `schtasks` needs elevation on this host (it fails outright); the Startup folder is per-user and needs none. |
+| Heartbeats during silence | Reasoning models think for minutes; the upstream pads that with SSE comments. Dropping them (as the first port did) leaves the client seeing zero bytes and timing out on a working request. |
+| Validate before writing provider config | A stray key does not fail one model, it silently deletes every provider. A temp file plus a schema mirror turns that into a loud error. |
+| Decrypt WorkBuddy 5.6 credentials inside the plugin | Since 5.6 the desktop app seals `accessToken`/`refreshToken` at rest, so the file is no longer readable as plain JSON. The plugin opens them by running the app's own Electron once as Node and reading its private storage binding — never by copying the tokens anywhere new. |
+
+## Notes
+
+- **Never write to WorkBuddy's own files.** The sign-in file is input only.
+- **No credential ever reaches ZCode's config** other than the local endpoint's
+  own bearer. The WorkBuddy token stays in the state directory, in memory, or on
+  the wire to WorkBuddy.
+- **Prices are informational.** Rates come from the upstream roster and are
+  cached; an expired promotion is dropped (`rateUnknown`) rather than left
+  claiming a discount.
+- State lives in `%USERPROFILE%\.zcode-workbuddy-connect\`
+  (`ZCODE_WORKBUDDY_CONNECT_HOME` overrides it).
+
+## A note on what this talks to
+
+The endpoint forwards to WorkBuddy's own internal API (`copilot.tencent.com`),
+using the WorkBuddy desktop app's existing login. That API is **undocumented and
+unofficial** — it is not a public integration surface, and it can change or break
+without notice. This project therefore:
+
+- makes **no stability promise** on the wire format, and
+- inherits any terms the WorkBuddy service imposes on its own client.
+
+It reads only the app's own sign-in file, never writes to it, and reuses session
+the user already established — there is no bypass, no credential harvesting, and no
+traffic to any host the desktop app does not already talk to. Use it with your own
+account. This is a port of a project that already does the same thing publicly; the
+caveats above are the original's, restated because they matter more than the
+feature list.
+
+**Never committed:** the credential copy, the endpoint bearer, and all runtime
+state. See `.gitignore` — state lives in `%USERPROFILE%\.zcode-workbuddy-connect\`, and
+`endpoint.json` there holds a bearer that would let a reader call *your* endpoint.
+
+## Licence
+
+MIT, following the original. The wire behaviour is itself ported by the original
+project from [Sliverkiss/workbuddy2api](https://github.com/Sliverkiss/workbuddy2api) (MIT).
+
+See [NOTICE.md](./NOTICE.md) for exactly which parts were carried over from the
+upstream and which were rewritten for this port.

package/bin/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/** Entry point for the zcode-workbuddy-connect CLI. */
+import { main } from '../src/cli.js'
+
+main().catch(error => {
+  console.error(`zcode-workbuddy-connect: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+})

package/docs/adr/0001-loopback-provider-for-zcode.md

@@ -0,0 +1,66 @@
+# ADR 0001 — Expose WorkBuddy models as a loopback OpenAI-compatible provider
+
+Status: accepted (2026-09-18)
+
+## Context
+
+`corrinehu/dsh-workbuddy-connect` is a **DeepSeek Harness (DSH) Cordis plugin**,
+not a Claude Code plugin. It calls DSH APIs to (a) register WorkBuddy desktop-app
+models into DSH's provider registry, (b) draw a settings card and a Composer
+probe control into DSH's UI slots, and (c) host a loopback OpenAI-compatible
+"shim" that applies WorkBuddy's wire quirks (`src/shim.ts`).
+
+The task was to port it to ZCode and install it. Inspection of
+`D:\Program Files\ZCode\resources\glm\zcode.cjs` and the installed plugin set
+established that **ZCode's plugin API has no "register an LLM provider"
+capability**. A plugin may contribute skills, commands, agents, hooks and MCP
+servers — none of which can drive ZCode's model selector or agent loop.
+
+A literal port is therefore impossible. Something had to be dropped or
+re-shaped.
+
+## Decision
+
+Extract the shim into a **standalone, dependency-free Node service** exposing an
+OpenAI-compatible endpoint on `127.0.0.1:39271`, and register it with ZCode the
+way ZCode already supports third-party models: an
+`api.type: "openai-chat-completions"` entry in
+`%USERPROFILE%\.zcode\v2\provider_config.json`.
+
+The plugin proper contributes three things: the service source, one operational
+skill, and a `SessionStart` hook that starts the endpoint.
+
+Discarded, because ZCode has no surface for them: the settings card, the
+Composer probe control, and reasoning-level probing.
+
+## Consequences
+
+**Gained.** The models are first-class entries in ZCode's model selector,
+driving the normal agent loop with streaming, tool calls and image input. This
+is stronger than the MCP-server alternative, which could only ever have been
+*one tool that asks a model something* — usable, but unable to participate in
+ZCode's agent loop at all.
+
+**Lost.** Credit/quota and promotion data is no longer displayed on a card; it
+is reachable through `status` and `doctor`. Reasoning-level detection is gone:
+the plugin now uses the efforts the upstream catalog declares, so no probing
+requests are made. Given probes consume credit and ZCode has nowhere to render
+their result, dropping them is a smaller loss than it first appears.
+
+**Constraint inherited.** The provider is only usable while the endpoint is
+running, which is a deployment obligation the DSH original did not have (DSH
+loaded the plugin in-process). Mitigated by the `SessionStart` hook, which is
+self-verifying: it probes the endpoint after spawning and reports plainly when it
+could not start it, rather than leaving the failure to surface as an unexplained
+connection error on the first message.
+
+## Alternatives rejected
+
+- **MCP server wrapping the models as tools** — cannot drive the agent loop;
+  the models would never appear in the model selector.
+- **Patching ZCode's provider registry from a plugin** — the capability does not
+  exist in the plugin API, and fabricating it would break on every upgrade.
+- **A per-process bearer** — the original shim used a fresh in-memory secret per
+  process, which is correct for a client that resolves it in-process. Here the
+  bearer is recorded in ZCode's config file, so it must survive restarts; it is
+  generated once and persisted (mode 0600) instead.

package/docs/adr/0002-widest-window-and-output-ceiling.md

@@ -0,0 +1,98 @@
+# ADR 0002 — Declare the widest context window, and cap output via `optionSpecs`
+
+Status: accepted (2026-09-18)
+
+## Context
+
+The port must register each WorkBuddy model with ZCode carrying its real limits.
+Two limits matter, and the second one has a trap in it.
+
+**Context window.** The upstream catalog reports two different numbers: a soft
+`contextWindow.defaultLength` (300 000 for many models) and the hard
+`maxInputTokens` (1 000 000 for those same models). It also occasionally ships
+`contextWindow.supportedLengths`, a list of selectable tiers whose maximum
+equals `maxInputTokens`.
+
+Declaring the soft default makes ZCode compact the conversation far earlier
+than the model can actually accept, wasting most of the window. A live probe
+confirmed the hard number is the honest one: a 312 856-token prompt was
+accepted while 1 294 869 tokens was rejected with "> 1048576 maximum".
+
+**Output ceiling.** ZCode's provider schema lives only as compiled zod inside
+`ZCode\resources\app.asar` (there is no JSON Schema file shipped). Reading that
+schema out of `out/host/index.js` shows the rule object is `.strict()`, and the
+two writable paths are:
+
+```
+config.properties   { contextWindow, inputFormat.{supportsImage,Video,Pdf},
+                      supportsToolCall, supportsJsonSchemaOutput,
+                      supportsNativeWebSearch, supportsMidConversationSystem,
+                      requiresMfjsToolSchema }
+config.optionSpecs  { reasoningLevel:{values,map}, maxOutputTokens:{max,map} }
+```
+
+There is **no `maxTokens` property**. An output limit belongs in
+`optionSpecs.maxOutputTokens.max`, which is the ceiling ZCode enforces on the
+value a user may select — the CLI throws "maxOutputTokens is outside the model
+option range" above it.
+
+The trap: because the schema is strict and ZCode's failure mode is to discard
+the **entire** personal provider config and fall back to an empty one, a single
+unrecognised key does not break one model — it silently removes every provider
+the user had (OpenRouter, DeepSeek, …), with nothing surfaced anywhere.
+
+## Decision
+
+Take the **maximum** for both limits, and write them through the two paths the
+schema actually accepts.
+
+- `properties.contextWindow` = `max(contextWindow, ...supportedContextWindows)`
+  — the widest window the upstream admits.
+- `optionSpecs.maxOutputTokens.max` = the upstream's own `maxOutputTokens`,
+  taken per model rather than guessed. `map` is **omitted**: the shipped
+  `openai-chat-completions` API rule already supplies
+  `{'max_completion_tokens': maxOutputTokens}`, and a hand-written expression
+  with a typo in the option-map mini-language would fail validation and take the
+  whole document down with it.
+
+Both are gated behind a new `docs/validate-provider-config.mjs`, which mirrors
+the strict schema and now runs on every `setup` write: the document is
+serialised to a temp file, validated, and only then renamed over the real path.
+A rejected document is never written and the offending key is printed.
+
+`serve` applies the same intent to `/v1/models` via the catalogue's
+`useMaximumContextWindow` switch, which had existed in `catalog.js` but was
+never wired to anything. `--default-context-window` restores the softer number.
+
+## Consequences
+
+**Gained.** ZCode plans against the real window instead of the conservative
+one, and the output-budget control is bounded by what the model can actually
+produce. All 36 models carry both values (verified: 0 rules missing
+`maxOutputTokens`).
+
+**A latent defect fixed.** The `setup` template for a *missing* config file
+contained a `provider: []` key that is not in the schema — writing it produced a
+document ZCode would discard wholesale. Found by the new validator on its first
+run against a throwaway path.
+
+**A host policy recorded, not worked around.** `install-service` writes its
+launcher to the Startup folder, and this host refuses script files there
+(`.vbs`, `.cmd`, `.bat`, `.ps1` all return `EPERM` while `.txt` in the same
+folder succeeds). That is a deliberate security control, so the command now
+reports it plainly and points at the `SessionStart` hook — which is the path
+that actually starts the endpoint, and was verified to bring it up from a cold
+stop.
+
+## Alternatives rejected
+
+- **Writing `properties.maxTokens`** — not in the schema; this is the exact
+  mistake the original comment warned about, and it costs the whole document.
+- **Supplying `optionSpecs.maxOutputTokens.map` as well** — redundant against
+  the built-in API rule, and adds an expression-language failure mode for no
+  gain.
+- **Trusting `contextWindow.defaultLength`** — understates the window by up to
+  3.3× and makes the agent compact early.
+- **Validating in-process instead of via a subprocess** — the validator is
+  meant to be runnable by hand for diagnosis; a copy that could drift from the
+  schema mirror would be worse than none.

package/docs/adr/0003-region-by-url-path.md

@@ -0,0 +1,97 @@
+# ADR 0003 — Separate the regions by URL path, not by an id prefix
+
+Status: accepted (2026-09-18)
+
+## Context
+
+The two WorkBuddy regions share **seven** model ids with different windows and
+rates: `glm-5.3`, `glm-5.2`, `hy3`, `hy4-preview`, `deepseek-v4.1-flash`,
+`kimi-k2.8-preview`, `kimi-k2.6`. One id therefore cannot stand for both, and
+something has to distinguish them.
+
+The original port did it by renaming: international models were exposed as
+`wbai:glm-5.3`. That prefix did two jobs at once — routing a chat request to the
+right credential store, and keeping the two rows apart.
+
+It also leaked into the one place it hurts most. Reading ZCode's renderer out of
+`resources/app.asar` shows the model picker rows render `e.name`, which is the
+**raw model id and nothing else**:
+
+```js
+// styles-ou2or4Yg.js, model-row renderer
+jsx('span', { className: `min-w-0 truncate`, title: e.name, children: e.name })
+```
+
+So `wbai:` was not an internal wire detail; it was literally the text the user
+read in the model list.
+
+The same investigation settled what alternatives exist:
+
+- **The picker groups by provider.** Each provider contributes a submenu whose
+  header is `providerName`, so `glm-5.3` under "WorkBuddy" and `glm-5.3` under
+  "WorkBuddy AI" are already unambiguous, and the closed trigger even shows
+  `WorkBuddy/glm-5.3`.
+- **There is no display-name mechanism.** The personal-provider schema is
+  `.strict()` with no `name`/`displayName`/`label`/`alias` key, and the
+  `settings.modelProvider.modelDisplayName` i18n string has zero references
+  outside its own dictionary — dead UI. A model cannot be given a friendlier
+  label.
+- **Identity is `(providerId, modelId)`.** Cross-provider id collisions are
+  legal and preserved; nothing suffixes or renames ids.
+- **ZCode sends no provider identifier.** No header, no query parameter, no body
+  field names the provider, and it never calls `/models` to learn the roster.
+  The baseUrl is used essentially verbatim (`<baseUrl>/chat/completions`, with
+  one trailing slash trimmed).
+
+## Decision
+
+Route by **URL path**, and leave the model ids bare.
+
+```
+CN             http://127.0.0.1:39271/v1/chat/completions
+International  http://127.0.0.1:39271/ai/v1/chat/completions
+```
+
+`setup` writes one provider per region with its own `baseUrl` and its own bare
+`modelIds`. The endpoint resolves the variant from the request path
+(`routePath`), so `/v1/models` lists only the CN roster and `/ai/v1/models` only
+the international one — each client sees 16 or 20 bare ids rather than a union
+of 36.
+
+A leading `wbai:` on a model id is still accepted and still selects the
+international store, so a client configured the old way keeps working; the
+prefix is stripped before the body goes upstream. `setup` also retires leftover
+`wbai:`-prefixed model rules from the user's document, since they name models
+that no longer exist under that spelling.
+
+## Consequences
+
+**Gained.** The model list reads as model names again. The region is a property
+of the *connection*, which is where the user configures it, rather than of the
+*name*, which only the display consumed.
+
+**Cost.** Two baseUrls instead of one — a client that hard-codes `/v1` for
+everything reaches only the CN region. Accepted because the only such client is
+`setup` itself, which writes both, and the `wbai:` fallback covers hand-written
+configs.
+
+**Not a compatibility break for ZCode.** It has no notion of a shared endpoint
+between providers; two providers pointing at two paths is the ordinary shape.
+
+## Alternatives rejected
+
+- **`api.headers` on each provider rule** — this would be the tidiest signal,
+  but it cannot be trusted to reach the upstream client: the header set is
+  assembled through several merge layers (`kEt`, `qVr`, `gN6`), and on a
+  `127.0.0.1` baseUrl some of them are skipped entirely. Path routing depends on
+  none of that.
+- **The `Authorization` bearer** — ZCode does send it, but both providers share
+  one endpoint bearer by design; giving each its own would mean two secrets to
+  rotate and would still leave the regions indistinguishable to any other
+  client.
+- **Renaming one region's ids** (the status quo) — the only place the id is ever
+  read by a human is the picker, so the cost lands entirely on the user and the
+  benefit is zero.
+- **One provider listing all 36 ids** — impossible: ZCode's `personalModelIds`
+  is a flat list, and the two `glm-5.3` entries would collide within a single
+  provider (the schema allows only one rule per provider+model).