feat(gui): surface Aside on the Integrations page

Registers Aside across the GUI so its card, tab and toggle render like any
other file client: the CLIENTS tuple, FILE_INTEGRATION_CLIENTS, the tab hash,
and the three exhaustive label maps.

TABS and FILE_CLIENTS move to integrations/integration-tabs.ts. They are the
only client lists in the GUI that neither the registry invariant compares nor
the compiler forces, so a client added everywhere else still gets no tab and
every gate stays green. They now live in a module a test can import, because
exporting them from Integrations.tsx alongside the component breaks fast
refresh. gui/tests/integrations-tab-coverage.test.ts derives its expectation
from FILE_INTEGRATION_CLIENTS rather than restating a literal, so client
thirteen cannot pass by accident.

Nine locales gain the tab label, the client label, and the ownership
semantics. "Aside" is a product name and stays English everywhere, so both
labels join the intentional-English allowlists. The semantics string carries
one Aside-specific clause: the running app rewrites models.json itself, so it
has to be fully quit and reopened after applying, the same shape as the
Claude Desktop restart copy.

Docs pick up the Aside destination and guide rows, plus the ZCode guide row
that was missing while the CLI reference already documented it.

Verification: bun run typecheck and bun run lint:gui clean; gui focused
tests (tab coverage, api, client-config panel, overview rows, surfaces,
locale parity, fr localization) 55 pass / 0 fail. Full suite deferred to CI.

Author: lidge-jun

docs-site/src/content/docs/guides/integrations.md

@@ -1,10 +1,10 @@
 ---
 title: Integrations
-description: Connect opencodex to OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code and Prime Agent from the dashboard — one switch per client, with a backup taken before every write.
+description: Connect opencodex to OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent and Aside from the dashboard — one switch per client, with a backup taken before every write.
 ---
 
 The **Integrations** tab writes opencodex's provider block into a client's own config
-file, and removes it again. Ten clients work this way, each with a switch:
+file, and removes it again. Twelve clients work this way, each with a switch:
 
 | Client | Config file | Format | When the change takes effect | Credential |
 |---|---|---|---|---|
@@ -18,6 +18,8 @@ file, and removes it again. Ten clients work this way, each with a switch:
 | DeepSeek Harness (DSH) | `$DSH_HOME/settings.yaml` (default `~/.dsh/settings.yaml`) | YAML | hot reload | non-secret loopback bearer placeholder |
 | MiniMax Code | `~/.minimax/config.yaml` | YAML | new sessions, or after opening the model picker | loopback placeholder |
 | Prime Agent | `~/.prime/agent/models.json` | JSON | new sessions | loopback placeholder |
+| ZCode | `~/.zcode/v2/config.json` | JSON | on restart | loopback placeholder |
+| Aside | `~/.aside/u/<account>/models.json` | JSON | after fully quitting and reopening Aside | loopback placeholder |
 
 The managed OpenCode integration owns two fragments: `provider.opencodex` (opencode V1) and
 `providers.opencodex` (opencode V2). Only the V2 block carries the per-model reasoning-effort
@@ -46,6 +48,17 @@ disagree about which file is meant. Its managed block owns only
 stay untouched. Prime Agent reads `models.json` when a session starts, so start
 a new session after connecting it.
 
+Aside is per-account: its state lives under `~/.aside/u/<account>/` and opencodex
+writes the catalog of whichever account Aside's own `accounts.json` names as
+current. If that manifest is missing or unreadable the integration refuses rather
+than guessing an account, because a guess on a multi-account machine would write
+into a different account's catalog. Its managed block owns only
+`providers.opencodex`, so your other Aside providers stay untouched.
+
+One caveat specific to Aside: the running app rewrites `models.json` itself, so
+fully quit and reopen Aside after applying, the same way Claude Desktop needs a
+restart. Aside's block is loopback-only and never carries a real credential.
+
 Paths honor each client's own environment override where it has one. For OMP,
 `OMP_PROFILE` wins over `PI_PROFILE` by presence, even when explicitly empty. A named profile
 uses `PI_CONFIG_DIR` as a directory name relative to the user's home and ignores `PI_CODING_AGENT_DIR`; without a named profile,

docs-site/src/content/docs/reference/cli/agents.md

@@ -207,7 +207,7 @@ Manage and apply the Grok Build model fence.
 
 ## Client config export
 
-### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime>`
+### `ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside>`
 
 Print a client config wired to the running proxy. The command serializes the
 `opencodex` provider block — base URL, model list, and the client's credential
@@ -218,7 +218,7 @@ models Codex can currently see.
 
 | Flag | Action |
 | --- | --- |
-| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime>` | Required. Selects the client config dialect. |
+| `--client <opencode\|pi\|omp\|hermes\|openclaw\|kimi\|gajae\|dsh\|mcode\|zcode\|prime\|aside>` | Required. Selects the client config dialect. |
 | `--json` | Print the generated document as JSON on stdout for scripts. This is JSON even when the selected client's native format is YAML, TOML, or JSON5. |
 | `--out <path>` | Write the client's native config format to `<path>`. Refuses to replace an existing file. |
 | `--force` | Allow `--out` to replace an existing file. |
@@ -247,6 +247,7 @@ client applies its own defaults for those).
 | `mcode` | `~/.minimax/config.yaml` (`MINIMAX_DATA_DIR`, then the legacy `MAVIS_DATA_DIR`, win when set; a relative value is refused) | `mcode-config.yaml` | none — loopback placeholder |
 | `zcode` | `~/.zcode/v2/config.json` (`ZCODE_DATA_DIR` wins when set; a relative value is refused) | `config.json` | none — loopback placeholder |
 | `prime` | `~/.prime/agent/models.json` (`PRIME_AGENT_CODING_AGENT_DIR` wins when set; a relative value is refused) | `prime-models.json` | none — loopback placeholder |
+| `aside` | `~/.aside/u/<account>/models.json` for the account Aside's own `accounts.json` names as current; an unreadable manifest is refused rather than defaulting to an account | `aside-models.json` | none — loopback placeholder |
 
 The managed DSH export requires DSH 0.1.0-rc.6 or newer and owns only
 `llm-pi-ai.providers.opencodex`. DSH hot reloads that provider; the user's default model and

gui/src/pages/Integrations.tsx

@@ -1,60 +1,14 @@
 import { useEffect, useRef, useState, type KeyboardEvent } from "react";
 import { navigateHash, normalizeHashPath } from "../hash-routing";
-import { useT, type TKey } from "../i18n/shared";
+import { useT } from "../i18n/shared";
 import ApiKeys from "./ApiKeys";
 import Claude from "./Claude";
 import Grok from "./Grok";
 import IntegrationsOverview from "./integrations/IntegrationsOverview";
 import FileIntegrationPage, {
   type FileIntegrationClientId,
 } from "./integrations/FileIntegrationPage";
-
-type IntegrationTab =
-  | "overview"
-  | "keys"
-  | "codex"
-  | "claude"
-  | "grok"
-  | FileIntegrationClientId;
-
-interface TabDefinition {
-  id: IntegrationTab;
-  hash: string;
-  labelKey: TKey;
-}
-
-const TABS: readonly TabDefinition[] = [
-  { id: "overview", hash: "integrations", labelKey: "integrations.tab.overview" },
-  { id: "keys", hash: "integrations/keys", labelKey: "integrations.tab.keys" },
-  { id: "codex", hash: "integrations/codex", labelKey: "integrations.tab.codex" },
-  { id: "claude", hash: "integrations/claude", labelKey: "integrations.tab.claude" },
-  { id: "grok", hash: "integrations/grok", labelKey: "integrations.tab.grok" },
-  { id: "opencode", hash: "integrations/opencode", labelKey: "integrations.tab.opencode" },
-  { id: "pi", hash: "integrations/pi", labelKey: "integrations.tab.pi" },
-  { id: "omp", hash: "integrations/omp", labelKey: "integrations.tab.omp" },
-  { id: "hermes", hash: "integrations/hermes", labelKey: "integrations.tab.hermes" },
-  { id: "openclaw", hash: "integrations/openclaw", labelKey: "integrations.tab.openclaw" },
-  { id: "kimi", hash: "integrations/kimi", labelKey: "integrations.tab.kimi" },
-  { id: "gajae", hash: "integrations/gajae", labelKey: "integrations.tab.gajae" },
-  { id: "dsh", hash: "integrations/dsh", labelKey: "integrations.tab.dsh" },
-  { id: "mcode", hash: "integrations/mcode", labelKey: "integrations.tab.mcode" },
-  { id: "zcode", hash: "integrations/zcode", labelKey: "integrations.tab.zcode" },
-  { id: "prime", hash: "integrations/prime", labelKey: "integrations.tab.prime" },
-] as const;
-
-const FILE_CLIENTS = new Set<FileIntegrationClientId>([
-  "opencode",
-  "pi",
-  "omp",
-  "hermes",
-  "openclaw",
-  "kimi",
-  "gajae",
-  "dsh",
-  "mcode",
-  "zcode",
-  "prime",
-]);
+import { FILE_CLIENTS, TABS, type IntegrationTab } from "./integrations/integration-tabs";
 
 function readIntegrationTab(hash = window.location.hash): IntegrationTab {
   const raw = normalizeHashPath(hash);

gui/src/pages/integrations/integration-tabs.ts

@@ -0,0 +1,62 @@
+/**
+ * The Integrations tab strip and the set of tabs backed by a file client.
+ *
+ * A separate module rather than exports on Integrations.tsx, because a file that
+ * exports both a component and constants breaks React fast refresh
+ * (react/only-export-components). These need to be importable: they are the only
+ * client lists in the GUI that neither tests/integrations-invariants.test.ts
+ * compares nor the compiler forces, so a client added everywhere else still gets
+ * no tab and nothing fails. gui/tests/integrations-tab-coverage.test.ts stands in
+ * that gap and reads them from here.
+ */
+import type { TKey } from "../../i18n/shared";
+import type { FileIntegrationClientId } from "./FileIntegrationPage";
+
+export type IntegrationTab =
+  | "overview"
+  | "keys"
+  | "codex"
+  | "claude"
+  | "grok"
+  | FileIntegrationClientId;
+
+export interface TabDefinition {
+  id: IntegrationTab;
+  hash: string;
+  labelKey: TKey;
+}
+
+export const TABS: readonly TabDefinition[] = [
+  { id: "overview", hash: "integrations", labelKey: "integrations.tab.overview" },
+  { id: "keys", hash: "integrations/keys", labelKey: "integrations.tab.keys" },
+  { id: "codex", hash: "integrations/codex", labelKey: "integrations.tab.codex" },
+  { id: "claude", hash: "integrations/claude", labelKey: "integrations.tab.claude" },
+  { id: "grok", hash: "integrations/grok", labelKey: "integrations.tab.grok" },
+  { id: "opencode", hash: "integrations/opencode", labelKey: "integrations.tab.opencode" },
+  { id: "pi", hash: "integrations/pi", labelKey: "integrations.tab.pi" },
+  { id: "omp", hash: "integrations/omp", labelKey: "integrations.tab.omp" },
+  { id: "hermes", hash: "integrations/hermes", labelKey: "integrations.tab.hermes" },
+  { id: "openclaw", hash: "integrations/openclaw", labelKey: "integrations.tab.openclaw" },
+  { id: "kimi", hash: "integrations/kimi", labelKey: "integrations.tab.kimi" },
+  { id: "gajae", hash: "integrations/gajae", labelKey: "integrations.tab.gajae" },
+  { id: "dsh", hash: "integrations/dsh", labelKey: "integrations.tab.dsh" },
+  { id: "mcode", hash: "integrations/mcode", labelKey: "integrations.tab.mcode" },
+  { id: "zcode", hash: "integrations/zcode", labelKey: "integrations.tab.zcode" },
+  { id: "prime", hash: "integrations/prime", labelKey: "integrations.tab.prime" },
+  { id: "aside", hash: "integrations/aside", labelKey: "integrations.tab.aside" },
+] as const;
+
+export const FILE_CLIENTS = new Set<FileIntegrationClientId>([
+  "opencode",
+  "pi",
+  "omp",
+  "hermes",
+  "openclaw",
+  "kimi",
+  "gajae",
+  "dsh",
+  "mcode",
+  "zcode",
+  "prime",
+  "aside",
+]);

gui/tests/integrations-tab-coverage.test.ts

@@ -0,0 +1,39 @@
+import { expect, test } from "bun:test";
+import { FILE_CLIENTS, TABS } from "../src/pages/integrations/integration-tabs";
+import { FILE_INTEGRATION_CLIENTS } from "../src/pages/integrations/integration-api";
+import { INTEGRATION_TAB_HASHES } from "../src/app-routing";
+
+/*
+ * The gap this closes.
+ *
+ * tests/integrations-invariants.test.ts compares five client lists, and the
+ * per-page label maps are Record<FileIntegrationClientId, TKey> so the compiler
+ * forces those. TABS and FILE_CLIENTS are neither: they are a plain array and a
+ * plain Set, so a client added everywhere else still gets no tab and nothing
+ * fails. Aside was the twelfth client to walk this path, and the first with a
+ * test standing in it.
+ *
+ * The expectation is DERIVED rather than written out, so adding client thirteen
+ * cannot leave a stale literal here that passes by accident.
+ */
+test("every file client has a tab definition and is registered as a file client", () => {
+  const tabbed = new Set(TABS.map(tab => tab.id));
+  const missingTab = FILE_INTEGRATION_CLIENTS.filter(id => !tabbed.has(id));
+  expect(missingTab).toEqual([]);
+
+  const missingFileClient = FILE_INTEGRATION_CLIENTS.filter(id => !FILE_CLIENTS.has(id));
+  expect(missingFileClient).toEqual([]);
+});
+
+test("every tab hash is routable, so a tab can actually be reached", () => {
+  // App normalization strips an unregistered hash, which would render the
+  // overview instead of the tab and look like a missing client.
+  const routable = new Set<string>(INTEGRATION_TAB_HASHES);
+  const unroutable = TABS.filter(tab => tab.hash !== "integrations" && !routable.has(tab.hash));
+  expect(unroutable.map(tab => tab.hash)).toEqual([]);
+});
+
+test("FILE_CLIENTS carries no id the API does not know", () => {
+  const known = new Set<string>(FILE_INTEGRATION_CLIENTS);
+  expect([...FILE_CLIENTS].filter(id => !known.has(id))).toEqual([]);
+});