lidge-jun · lidge-jun · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026
@@ -0,0 +1,46 @@
+# Aside client + Integrations UX repair
+
+Unit opened 2026-08-31. Two outcomes travel together because they land on the
+same page: Aside becomes an export/integration client, and the Integrations
+("연결") surface stops flooding itself with rollback rows.
+
+They are one unit rather than two because the Aside work ADDS a twelfth card to
+a page that is already too crowded to absorb one. Shipping the client first
+would make the page measurably worse before it got better.
+
+## The two problems
+
+**Aside is unsupported.** Aside is a Chromium fork with a built-in browser
+agent. Its custom-provider catalog lives at `~/.aside/u/<accountId>/models.json`
+and its schema is the one Pi reads. The user on this machine already wired
+opencodex into it BY HAND: the live file carries a `providers.opencodex` block
+with 24 routed models, `api: "openai-completions"`, and
+`apiKey: "opencodex-loopback"` — byte-identical to what `buildPiClientConfig`
+emits. A hand-maintained integration is the strongest possible argument that
+the client belongs in the registry.
+
+**The Integrations page floods.** The rollback journal renders up to 50 rows,
+each with its own border, at the bottom of the overview AND again on every file
+client tab. The user's words were "로그 밑에 막 다닥다닥 뜨는 히스토리" — the
+per-row borders are literally what produces that texture.
+
+## Work phases
+
+| Phase | Doc | Deliverable |
+|---|---|---|
+| wp1 | this unit | Research and roadmap (docs only) |
+| wp2 | 010 | Aside export client + integration registry |
+| wp3 | 020 | Aside GUI surface, marks entry, nine locales |
+| wp4 | 030 | Rollback surface redesign |
+| wp5 | 040 | Brand marks for the nine clients showing a monogram |
+| wp6 | 050 | Stacked PR chain |
+
+Research docs: 001 (Aside contract), 002 (registration checklist),
+003 (Integrations UX diagnosis), 004 (brand mark provenance).
+
+## Ordering constraint
+
+wp4 and wp5 do not depend on wp2/wp3, and wp3 depends on wp2. The stack is
+therefore not a single line: the Aside pair (wp2 then wp3) and the page repair
+pair (wp4, wp5) are independent chains that both branch off `dev`. wp6 puts
+them in review order.
@@ -0,0 +1,158 @@
+# What Aside actually reads
+
+Observed on this machine, 2026-08-31, against Aside CLI `1.26.810.1915` and app
+bundle `1.0.825.1`. Every claim below was read off a real file or a live process,
+not inferred from documentation.
+
+## Account roots
+
+`~/.aside/accounts.json` (mode 600) carries:
+
+```json
+{ "version": ..., "currentAccountId": 0, "accounts": [ { "id": 0, "email": "..." }, { "id": 1 } ], ... }
+```
+
+Per-account state lives at `~/.aside/u/<id>/`. Both `u/0` and `u/1` exist here,
+so multi-account is not hypothetical. The provider catalog is
+`~/.aside/u/<id>/models.json`.
+
+**No environment override exists.** `strings` over the CLI binary yields
+`ASIDE_DAEMON_BASE_URL`, `ASIDE_CLI_*`, `ASIDE_MCP_*`, `ASIDE_PRODUCT_VARIANT`,
+`ASIDE_RELEASE_BASE_URL`, `ASIDE_NATIVE_HELPER_BINDING` — and nothing that
+relocates the account root. The only literal `.aside` path in the binary is
+`path.join(os.homedir(), ".aside", "cli", "update-check.json")`.
+
+This makes Aside unlike every existing client. `dshHomeDir` honors `DSH_HOME`;
+`mcodeHomeDir` honors `MINIMAX_DATA_DIR` then `MAVIS_DATA_DIR`; `piAgentDir`
+honors `PI_CODING_AGENT_DIR`. Aside has no such variable to honor, so the
+resolver's variable is the ACCOUNT ID, not a path.
+
+### Decision: read the manifest, fail closed, add no opencodex env var
+
+A resolver that only reads `~/.aside` cannot be tested without writing to the
+user's real Aside install. Every existing path helper takes `(env, home)` and
+the tests redirect `home`; Aside does the same, so the root is
+`join(home, ".aside")` and tests redirect `home` exactly as
+`tests/prime-client.test.ts` does.
+
+An earlier draft added `OPENCODEX_ASIDE_ACCOUNT` so a user could target a
+non-current account. **Dropped after audit.** This registry's contract is to
+honor each client's OWN override (`registry.ts:45`) — `DSH_HOME`,
+`MINIMAX_DATA_DIR`, `PI_CODING_AGENT_DIR` all belong to their clients. Aside
+ships no such variable, so inventing an opencodex-namespaced one is new product
+behavior dressed up as path resolution. Account selection, if it is ever wanted,
+is its own unit with its own surface.
+
+We write the account Aside itself reports as current, and nothing else.
+
+**Fail closed rather than fall back.** An earlier draft defaulted to account `0`
+when `accounts.json` was missing or unparseable. On this machine both `u/0` and
+`u/1` exist, so that fallback could name a real config file belonging to the
+WRONG account and then pass the installation gate — a silent write into another
+account's catalog. Instead:
+
+- Manifest present with a non-negative integer `currentAccountId`: use it.
+- Manifest absent, unreadable, unparseable, or the id malformed: throw
+  `ClientPathError`. The surface reports the client as unavailable with a real
+  reason, exactly as an unresolvable `DSH_HOME` does today.
+
+A missing manifest means Aside has not established which account is current, and
+there is no honest value to guess.
+
+**Resolve both paths from one account read.** `freezeIntegrationInput` called
+`configPath` and `detectDir` separately (`writer.ts:621`), and `readIntegrationState`
+did the same. Both now depend on file contents rather than only `env` and `home`,
+so a manifest rewritten between the two calls could verify one account's install
+and then write a different account's catalog.
+
+A cache was the first idea and it does not work: any cache keyed on the manifest
+re-reads exactly when the manifest changes, which is the case the consistency is
+needed for, and nothing tells a path helper when an operation ends. The audit
+caught that contradiction.
+
+The fix is a seam instead. `resolveIntegrationPaths(clientId, env, home)` in the
+integration registry returns the PAIR, and an optional `resolvePaths` on a client
+spec lets Aside derive both from a single `asideAccountDir` call. Every other
+client keeps the default behavior, so the pair stays correct for them without
+any of them knowing why the seam exists.
+
+## The provider block
+
+The live `~/.aside/u/0/models.json`, provider keys in their on-disk order with
+values elided:
+
+```json
+{ "providers": { "opencodex": {
+  "baseUrl": "http://127.0.0.1:10100/v1",
+  "apiKey": "opencodex-loopback",
+  "api": "openai-completions",
+  "models": [ { "id": "...", "name": "...", "reasoning": true,
+                "thinkingLevelMap": { "off": null, ..., "max": "max" },
+                "input": ["text","image"], "contextWindow": 1000000,
+                "maxTokens": 32000 } ]
+} } }
+```
+
+Four provider keys and 24 model entries. `thinkingLevelMap` uses the same seven
+pi levels (`off`/`minimal`/`low`/`medium`/`high`/`xhigh`/`max`) with `null` for
+levels the model does not declare. `input` is `["text","image"]` throughout, or
+`["text"]` alone.
+
+### The same key SET, not the same byte order
+
+An earlier draft called this file "byte-identical" to `buildPiClientConfig`
+output. That was wrong, and the audit caught it.
+
+The builder emits `baseUrl`, `api`, `apiKey`, `models`
+(`config-export.ts:1038`); the hand-written file has `baseUrl`, `apiKey`,
+`api`, `models`. Model entries differ the same way — the builder writes `input`
+before the optional reasoning fields, the live file after. `serializeDocument`
+preserves insertion order, so the emitted bytes really do differ.
+
+The true claim is weaker and sufficient: **the same four provider keys, the same
+dialect string, the same placeholder, and the same model field vocabulary.** JSON
+key order is not semantic and Aside parses this file rather than diffing it. What
+the builder produces is a document Aside accepts; it is not the document a human
+happened to type.
+
+So this unit claims compatibility, not equality. The test backing it must NOT be
+`buildAside(ctx) === buildPi(ctx)`: both call the same function, so that
+assertion is tautological. wp2 asserts against a fixture captured from the
+observed Aside shape — same key set, same dialect, placeholder rather than a
+credential, model fields drawn from the observed vocabulary.
+
+## Reuse, and the one thing not to reuse
+
+`prime` set the precedent: it reuses `buildPiClientConfig` and `summarizePi`
+verbatim and adds only `buildPrimeContribution`, so ownership records carry
+`clientId: "prime"`. Aside follows that exactly. Restating the shape would
+create a second copy of one fact, which is the bug that comment warns about.
+
+## loopbackOnly: true
+
+The provider block has four keys and none of them is `headers`. A dedicated
+`x-opencodex-api-key` header has nowhere to live, so a non-loopback bind would
+generate a config that 401s. Same reasoning, same verdict as `dsh`, `kimi`,
+`gajae`, `mcode`, and `zcode`.
+
+`apiKeyEnv` is therefore `""` and `exportHint` says loopback needs no key.
+
+## Hazard: Aside overwrites the file while running
+
+The Aside skill reference states that editing `models.json` while Aside is
+running risks the daemon overwriting it, and `Aside Daemon` was live during
+this investigation. The pattern for this already exists: Claude Desktop's copy
+says "Fully quit and reopen it for this change to take effect"
+(`integrations.dialog.desktop.restart`). Aside gets the same treatment in its
+`integrations.semantics.aside` string.
+
+This is a copy problem, not a writer problem. The writer already snapshots
+before every mutation and journals what it did, so an overwrite by Aside is
+recoverable the same way any drift is.
+
+## Not in scope
+
+`~/.aside/u/0/models.json` can hold a plaintext key for a user's OWN providers,
+and `credentials.json` certainly does. We write one fragment,
+`providers.opencodex`, and the merge layer touches nothing else. No Aside
+credential is ever read, printed, or serialized.
@@ -0,0 +1,72 @@
+# Every surface a new export client must reach
+
+Derived from `git show c6fa2563d` (the `prime` client, 29 files) plus the
+invariant tests. This is the checklist wp2 and wp3 execute.
+
+## Backend (wp2)
+
+- `src/clients/config-export.ts`: `asideHomeDir`/`asideAccountDir`/
+  `asideConfigPath` helpers, `"aside"` in `ExportClientId`,
+  `buildAsideContribution`, and the `EXPORT_CLIENTS.aside` spec. The spec needs
+  all nine fields: `filename`, `destination`, `apiKeyEnv`, `exportHint`,
+  `build`, `format`, `summarize`, `buildContribution`, `loopbackOnly`.
+- `src/integrations/registry.ts`: `INTEGRATION_CLIENTS.aside` with `configPath`
+  and `detectDir`. No `sourcePreservingYaml` (JSON) and no `writerLock`, same as
+  `pi` and `prime`.
+- `src/cli/registry.ts`: the `export` entry's static `usage`/`summary` client
+  union. Acceptance itself comes from `EXPORT_CLIENT_IDS` via
+  `isExportClientId` in `src/cli/export-command.ts`, so this is help text only.
+- `tests/aside-client.test.ts`: new, modeled on `tests/prime-client.test.ts`.
+
+`bun run skill:surface` is NOT implicated: its generator reads `CAPABILITIES`,
+and a new `--client` value creates no capability.
+
+## Existing tests that assert exact lists (wp2)
+
+These fail until updated, which is the point:
+
+- `tests/client-config-export.test.ts`: ordered `EXPORT_CLIENT_IDS`.
+- `tests/client-config-export-new-clients.test.ts`: the loopback-only set.
+- `tests/integrations-invariants.test.ts`: the client count, and `SEED` is a
+  `Record<IntegrationClientId, string>` so typecheck forces an Aside fixture in
+  Aside's own JSON shape.
+- `tests/integrations-state.test.ts`: the loopback-only set.
+
+## GUI (wp3)
+
+Five surfaces the invariant test compares against `EXPORT_CLIENT_IDS`:
+`INTEGRATION_CLIENT_IDS`, the GUI `CLIENTS` tuple, `CLIENT_LABEL_KEYS` keys,
+`FILE_INTEGRATION_CLIENTS`, and the hashes in `INTEGRATION_TAB_HASHES`.
+
+Plus three exhaustive `Record<FileIntegrationClientId, TKey>` maps that
+typecheck catches: `FILE_LABEL_KEY` in `overview-clients.ts`, and
+`SEMANTICS_KEY` + `TAB_LABEL_KEY` in `FileIntegrationPage.tsx`.
+
+**The two silent hazards.** `TABS` and `FILE_CLIENTS` in
+`gui/src/pages/Integrations.tsx` are NOT exhaustive records and NOT covered by
+the invariant test. Omitting Aside from either leaves typecheck and the
+invariants green while the tab silently does not render. wp3 asserts both in a
+GUI test rather than trusting the compiler.
+
+## i18n (wp3)
+
+Three keys across nine locales (`en`, `de`, `fr`, `ja`, `ko`, `ru`, `tr`, `zh`,
+`zh-TW`): `integrations.tab.aside`, `integrations.semantics.aside`,
+`api.clientConfig.clientAside`.
+
+"Aside" is a product name, so the tab and client labels stay English in every
+locale. That means adding them to `ZH_TW_KEEP_ENGLISH` in
+`gui/tests/locale-parity.test.ts` and `INTENTIONAL_ENGLISH` in
+`gui/tests/fr-localization.test.ts`. The semantics string is prose and IS
+translated.
+
+## Docs (wp3)
+
+`docs-site/.../reference/cli/agents.md` client union, flag table, and
+destination table; `docs-site/.../guides/integrations.md` client table. Commit
+`42adf4996` established that translated CLI reference pages are synchronized
+too.
+
+The integrations guide currently lists ten clients and omits `zcode` — a real
+gap found during this research. wp3 adds the missing `zcode` row alongside
+`aside` rather than leaving a known hole next to a new entry.
@@ -0,0 +1,96 @@
+# Why the Integrations page reads as noise
+
+Read against the current tree, 2026-08-31.
+
+## What the user is seeing
+
+"로그 밑에 막 다닥다닥 뜨는 히스토리" — the rollback journal. The real numbers:
+
+- The route `/api/client-integrations/journal` accepts only `client`. There is
+  no HTTP `limit` parameter; `?limit=` is ignored
+  (`src/server/management/integration-routes.ts:313`).
+- It calls `store.listOperations()` with no limit, so `listOperations`' own
+  default applies: **50 rows**, newest first (`src/integrations/journal.ts:138`).
+- Both consumers render the ENTIRE response with no slice —
+  `IntegrationsOverview.tsx:561` and `FileIntegrationPage.tsx:196`.
+- Every row carries its own `1px` border and `border-radius`
+  (`styles-integrations.css:62`). Fifty bordered strips stacked at 6px gaps is
+  precisely the "다닥다닥" texture.
+
+So the flooding is real, and it is worse than one list: the overview shows the
+global journal and every file client tab shows the same journal filtered. The
+same operation is rendered twice in two places.
+
+Two related facts worth recording. Snapshot retention is 10 per client
+(`journal.ts:54`), so of 50 visible rows at most 10 are restorable and the rest
+render an "expired" badge — the list is mostly inert. And journal ROWS are never
+pruned, so `journal.jsonl` is parsed in full on every request before the slice.
+
+## Defects, worst first
+
+1. **History floods and duplicates.** Above.
+2. **Loading, failure, and empty are indistinguishable.** Both components do
+   `data ?? []` and then render the empty state, so a cold fetch, a failed
+   fetch, and a genuinely empty journal look identical. No retry, no stale
+   warning — even though `useDataSurface` exposes `state.kind` for exactly this.
+3. **Undo is buried.** On the overview it sits below the summary, the API-key
+   row, onboarding copy, up to 15 cards, and an empty panel. The most valuable
+   recovery action on the page is viewports away from the switch that caused it.
+4. **RestoreDialog is not modal.** It renders `<dialog open>` with inline
+   full-screen styles instead of `showModal()`, so background controls stay
+   reachable and focus is neither trapped nor restored.
+   `ConsequenceDialog.tsx:34` in the same directory does it correctly.
+5. **Summary claims exceed its data.** "Last change" reads only the file-client
+   journal, so a Codex/Claude/Desktop/Grok change is invisible. Counts paint
+   zero while sources are still unsettled. The "no clients detected" panel tests
+   only FILE clients but its copy does not say so.
+6. **Heading levels skip.** Overview goes `h2` straight to `h4` with no `h3`.
+   CSS targets `.integration-client-head h4` while the JSX renders `h3`.
+7. **Card saturation.** No literal card-in-card, but a raised summary, a raised
+   API row, 15 bordered cards, a bordered empty panel, and 50 bordered history
+   rows give every level the same visual weight.
+8. **No responsive block at all** in `styles-integrations.css`.
+
+## Patterns already in this repo
+
+Nothing here needs a new design system.
+
+- **Bounded pagination:** Claude Desktop reveals six rows at a time behind a
+  `btn btn-ghost btn-sm` show-more (`claude-desktop-lane.ts:11`,
+  `ClaudeDesktop.tsx:671`). `LANE_PAGE = 6` is the local precedent.
+- **Disclosure:** `Logs.tsx:1112` uses native `<details>/<summary>` for
+  secondary detail. There is no generic Accordion component, and adding one is
+  out of scope.
+- **State branching:** `DataSurfaceSkeleton`, `DataSurfaceStatus`,
+  `EmptyState`, `Notice` already exist.
+- Virtualization (`Logs.tsx:518`) is overkill for at most 50 rows.
+
+## The redesign (wp4)
+
+**Overview.** Drop the journal block entirely. In its place, one unframed
+"latest change" line directly below the summary: client, operation, time, and
+its Undo or Restore-point action. Recovery moves above the fold and the
+summary's "last change" scope becomes visible instead of implied.
+
+**Client tab.** Newest row stays visible next to the status and path. Older rows
+move into a collapsed-by-default `<details>`, revealed six at a time. Expired
+rows live only inside that disclosure, so the visible surface is the part that
+can actually be undone.
+
+No total count is displayed: the API caps at 50 and returns neither `total` nor
+`hasMore`, so any number shown would be a claim we cannot support.
+
+**Shared component.** The row JSX is currently duplicated in both files with
+their own `KIND_KEY` maps. wp4 extracts one integrations-domain component.
+
+**Styling.** One list boundary with `border-top` separators instead of a border
+per row. Fix `.integration-client-head h4` to `h3`, add `flex-wrap`, add a
+narrow-viewport rule.
+
+**Also in wp4.** `RestoreDialog` adopts `ConsequenceDialog`'s modal lifecycle,
+and the history resources branch on `state.kind` so cold, failed, and empty
+stop looking alike.
+
+An HTTP `limit` parameter is deliberately NOT in wp4. It would shrink the
+payload without fixing the full-file parse or the unbounded on-disk journal, and
+the UI cap makes it unnecessary for this complaint. Recorded as a follow-up.