From ed4d640c1dfbef1078e8458a670e0901b16c49b1 Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Sat, 20 Jun 2026 03:56:24 +0200
Subject: [PATCH 1/5] fix(viewer): make Chinese locale selectable

---
 .env.example                                  |   1 +
 README.md                                     |   2 +
 .../arena-synthesis.md                        |  49 ++++
 .../plan.md                                   | 249 ++++++++++++++++++
 .../todo.md                                   | 158 +++++++++++
 src/viewer/index.html                         | 201 ++++++++++----
 src/viewer/locales.ts                         |   8 +
 src/viewer/locales/en.json                    |  83 +++++-
 src/viewer/locales/zh.json                    |  83 +++++-
 test/viewer-i18n.test.ts                      |  86 ++++++
 10 files changed, 870 insertions(+), 50 deletions(-)
 create mode 100644 docs/todos/2026-06-19-issue-288-web-display-issue/arena-synthesis.md
 create mode 100644 docs/todos/2026-06-19-issue-288-web-display-issue/plan.md
 create mode 100644 docs/todos/2026-06-19-issue-288-web-display-issue/todo.md

diff --git a/.env.example b/.env.example
index 9e4c7c8a9..c1b5ed31f 100644
--- a/.env.example
+++ b/.env.example
@@ -191,6 +191,7 @@
 # AGENTMEMORY_IMPORT_TIMEOUT_MS=120000           # import-jsonl POST timeout
 # AGENTMEMORY_URL=http://localhost:3111          # REST base URL — honored by status, doctor, MCP shim
 # AGENTMEMORY_VIEWER_URL=http://localhost:3113   # Override the viewer URL printed by `agentmemory status`
+# VIEWER_LANGUAGE=zh-CN                          # Startup default for the viewer UI; users can switch in the viewer header
 # AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup   # Default destination for `agentmemory export`
 # AGENTMEMORY_BACKUP_ENABLED=true                # Periodically write logical JSON exports
 # AGENTMEMORY_BACKUP_DIR=~/.agentmemory/backups  # Required when scheduled backups are enabled
diff --git a/README.md b/README.md
index d0572b8b5..ff88d89a2 100644
--- a/README.md
+++ b/README.md
@@ -1248,6 +1248,8 @@ Auto-starts on port `3113`. Live observation stream, session explorer, memory br
 open http://localhost:3113
 ```
 
+The viewer ships English and Simplified Chinese UI strings. It auto-selects Chinese for Chinese browser language preferences when no local viewer preference has been saved, and the header language selector persists your choice in the browser. Operators can also set the startup default with `VIEWER_LANGUAGE=zh` or `VIEWER_LANGUAGE=zh-CN`.
+
 The viewer server binds to `127.0.0.1` by default. The REST-served `/agentmemory/viewer` endpoint follows the normal `AGENTMEMORY_SECRET` bearer-token rules. CSP headers use a per-response script nonce and disable inline handler attributes (`script-src-attr 'none'`).
 
 ---
diff --git a/docs/todos/2026-06-19-issue-288-web-display-issue/arena-synthesis.md b/docs/todos/2026-06-19-issue-288-web-display-issue/arena-synthesis.md
new file mode 100644
index 000000000..3d1fec326
--- /dev/null
+++ b/docs/todos/2026-06-19-issue-288-web-display-issue/arena-synthesis.md
@@ -0,0 +1,49 @@
+# Issue 288 Arena Synthesis
+
+Artifact: issue-validity and fix-direction decision for GitHub issue #288.
+
+Rubric:
+- Issue evidence accuracy.
+- Current-code reproduction clarity.
+- Duplicate/staleness diligence.
+- Scoped fix direction.
+- Verification specificity.
+
+## Candidate Scores
+
+| Candidate | Score | Summary |
+| --- | ---: | --- |
+| A | 23/25 | Correctly identified partial existing Chinese locale support and remaining coverage gaps; strongest route/build inventory. |
+| B | 25/25 | Clearest conclusion: valid unresolved coverage/discoverability gap, not fixed, with practical implementation direction. |
+| C | 21/25 | Strong rendered-output proof and font/search nuance, but verification attempt caused ignored dependency artifacts. |
+
+## Pick
+
+Base: Candidate B.
+
+Reason: Candidate B best distinguishes existing i18n foundation from the unresolved user-facing gap. It recommends a scoped fix that does not require API, auth, schema, dependency, or architecture changes.
+
+## Grafts
+
+- From Candidate A: keep the route/build inventory in scope and remember that the shipped legacy viewer remains the production surface while the Vue/Vite app is preview-only.
+- From Candidate A: do not import upstream PR #673 wholesale; local history already adapted the safe foundation.
+- From Candidate C: use rendered-output style checks where practical so tests prove Chinese surfaces are reachable, not just locale files exist.
+- From Candidate C: CJK search is separate from UI localization and must not be treated as closing this issue.
+- From Candidate C: font fallback can improve Chinese readability, but font-only work does not satisfy the issue by itself.
+
+## Rejections
+
+- Close as already fixed: rejected because major shipped viewer surfaces remain hardcoded English and `VIEWER_LANGUAGE` is not discoverable for ordinary users.
+- Close as duplicate without implementation: rejected because the current request requires a Human Checkpoint for duplicate closure and the arena found valid unresolved scope.
+- Replace the viewer architecture: rejected because issue #148 owns the Vue/Vite migration and the shipped viewer remains `src/viewer/index.html`.
+- Add runtime machine translation or external services: rejected because checked-in locale strings are safer and avoid privacy/CSP/network consequences.
+
+## Decision
+
+Proceed with a scoped valid-issue implementation:
+- expose bundled locales to the browser safely;
+- add a visible language selector with local persistence and Chinese-browser preference handling;
+- expand Chinese locale keys for representative Dashboard and Memories surfaces;
+- document `VIEWER_LANGUAGE=zh` / `zh-CN` and the in-viewer picker.
+
+Verification must preserve existing CSP/nonced-script behavior, translated-attribute allowlist restrictions, viewer layout, and package build behavior.
diff --git a/docs/todos/2026-06-19-issue-288-web-display-issue/plan.md b/docs/todos/2026-06-19-issue-288-web-display-issue/plan.md
new file mode 100644
index 000000000..97ed53ddb
--- /dev/null
+++ b/docs/todos/2026-06-19-issue-288-web-display-issue/plan.md
@@ -0,0 +1,249 @@
+# Issue 288 Viewer Chinese Localization Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the shipped viewer's Chinese localization directly selectable and more complete on high-traffic Dashboard and Memories surfaces.
+
+**Architecture:** Keep the existing nonced locale injection and static legacy viewer. Extend the injected locale bundle with bundled `available` locale data, add client-side locale selection/localStorage/browser-language resolution, and route representative Dashboard/Memories strings through existing safe translation helpers.
+
+**Tech Stack:** TypeScript, static HTML/JavaScript viewer, JSON locale files, Vitest, pnpm.
+
+---
+
+## Files
+
+- Modify: `src/viewer/locales.ts`
+- Modify: `src/viewer/index.html`
+- Modify: `src/viewer/locales/en.json`
+- Modify: `src/viewer/locales/zh.json`
+- Modify: `test/viewer-i18n.test.ts`
+- Modify: `test/viewer-security.test.ts`
+- Modify: `README.md`
+- Modify: `.env.example`
+- Modify: `docs/todos/2026-06-19-issue-288-web-display-issue/todo.md`
+
+## Task 1: Red Tests For Switchable Viewer Locales
+
+- [x] **Step 1: Add failing bundle and document tests**
+
+Add tests to `test/viewer-i18n.test.ts` that assert:
+- `buildLocaleBundle("en")` exposes `available.en` and `available.zh`.
+- the rendered document includes `id="language-select"`.
+- the rendered document includes the `agentmemory-viewer-language` storage key and `navigator.languages` browser-language check.
+- `zh.json` contains representative Dashboard and Memories keys such as `dashboard.first_run_eyebrow`, `dashboard.cards.sessions`, `memories.search_placeholder`, and `common.delete`.
+- the viewer source routes representative Dashboard and Memories HTML-builder strings through escaped `t(...)`: first-run copy, stat labels, Memories search/empty states/table headers, and delete modal copy.
+- a viewer sandbox test can render Dashboard/Memories in English, switch to Chinese, and observe representative dynamic text change without a reload.
+
+- [x] **Step 2: Verify red**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-i18n.test.ts -t "viewer locale"
+```
+
+Expected: fail because `available`, the picker, and new keys do not exist.
+
+Evidence: failed 4 expected tests after deterministic pnpm setup.
+
+## Task 2: Expose Locale Data Safely
+
+- [x] **Step 1: Extend `LocaleBundle`**
+
+Update `src/viewer/locales.ts` so `LocaleBundle` includes:
+
+```ts
+available: Record<string, LocaleMessages>;
+```
+
+Build it from checked-in `en` and `zh` locale files only. Keep the existing `lang`, `messages`, and `fallback` fields for compatibility.
+
+- [x] **Step 2: Verify green for bundle tests**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-i18n.test.ts -t "bundle"
+```
+
+Expected: pass for the bundle tests that do not depend on HTML picker code yet.
+
+Evidence: full focused i18n suite passed after implementation.
+
+## Task 3: Add Viewer Language Picker Runtime
+
+- [x] **Step 1: Add picker markup and runtime selection**
+
+Modify `src/viewer/index.html`:
+- Add a compact `<select id="language-select">` in `.header-right` with `en` and `zh` options.
+- Add `agentmemory-viewer-language` localStorage handling.
+- Pick language in this order: valid localStorage preference, Chinese browser language from `navigator.languages`, injected bundle language.
+- Re-apply `window.applyI18n(document)` after switching.
+- Update `document.documentElement.lang`.
+- Re-render already-loaded dynamic surfaces after switching. At minimum, call `renderDashboard()` when `state.dashboard.loaded` is true and `renderMemories()` when `state.memories.loaded` is true.
+- Keep the active bundle used by `t(...)` and `tRaw(...)` in sync with the selected language before re-rendering.
+
+- [x] **Step 2: Preserve CSP/attribute safety**
+
+Keep locale JSON inside the existing nonced script. Do not add translated `href`, `src`, event handler, or IDREF attributes.
+
+- [x] **Step 3: Verify picker/security tests**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-i18n.test.ts test/viewer-security.test.ts
+```
+
+Expected: pass after implementation.
+
+Evidence: focused i18n/security/layout run passed 3 files / 37 tests.
+
+## Task 4: Localize Dashboard And Memories Representative Surfaces
+
+- [x] **Step 1: Add locale keys**
+
+Expand `src/viewer/locales/en.json` and `src/viewer/locales/zh.json` with nested keys for:
+- `language`
+- `common`
+- `dashboard.first_run_*`
+- `dashboard.cards.*`
+- `dashboard.sections.*`
+- `memories.*`
+
+Preserve every placeholder marker across English and Chinese.
+
+- [x] **Step 2: Route Dashboard strings through helpers**
+
+In `src/viewer/index.html`, use escaped `t(...)` for any translated string concatenated into `innerHTML`/modal HTML. Reserve `tRaw(...)` for `textContent`, safe allowlisted attributes, and other non-HTML contexts only.
+
+Use `t(...)` for:
+- first-run hero copy;
+- stat card labels and subtitles;
+- system resource title and labels;
+- recent sessions and recent activity titles;
+- dashboard table headers and empty states.
+
+Keep backend values such as health state, connection state, operation names, and user data escaped/raw.
+
+- [x] **Step 3: Route Memories strings through helpers**
+
+In `src/viewer/index.html`, use locale helpers for:
+- Memories description;
+- search placeholder and type filter label;
+- loading/empty/no-results copy;
+- table headers;
+- Delete button;
+- Delete Memory modal title, body, Cancel, and Delete buttons.
+
+Use `t(...)` in HTML strings and modal HTML. Use `tRaw(...)` only when assigning an input `placeholder` property or other safe non-HTML text/attribute value.
+
+- [x] **Step 4: Verify focused i18n tests**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-i18n.test.ts
+```
+
+Expected: pass all locale parity and placeholder parity tests.
+
+Evidence: focused i18n suite passed 17 tests.
+
+- [x] **Step 5: Verify rendered path tests**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-i18n.test.ts -t "renders switched Dashboard and Memories copy"
+```
+
+Expected: pass because the sandbox renders English first, switches to Chinese, and sees representative Dashboard and Memories copy update.
+
+Evidence: covered by focused i18n suite.
+
+## Task 5: Document Viewer Language Selection
+
+- [x] **Step 1: Update `README.md`**
+
+In the Real-Time Viewer section, add concise docs that the viewer ships English and Simplified Chinese, auto-prefers Chinese browser languages when available, offers an in-viewer language selector, and supports `VIEWER_LANGUAGE=zh` or `VIEWER_LANGUAGE=zh-CN` as the startup default.
+
+- [x] **Step 2: Update `.env.example`**
+
+Add a commented `VIEWER_LANGUAGE=zh-CN` example near viewer runtime settings.
+
+- [x] **Step 3: Verify docs references**
+
+Run:
+
+```bash
+rg -n "VIEWER_LANGUAGE|Simplified Chinese|language selector|zh-CN" README.md .env.example
+```
+
+Expected: the new docs/config lines are present.
+
+Evidence: command found README and `.env.example` entries.
+
+## Task 6: Stabilization And PR Verification
+
+- [ ] **Step 1: Focused cleanup**
+
+Run a simple-code pass on the touched viewer/i18n files only. Preserve CSP, auth, routing, persistence, API, and build contracts.
+
+- [ ] **Step 2: Run targeted checks**
+
+Run:
+
+```bash
+corepack pnpm exec vitest run test/viewer-i18n.test.ts test/viewer-security.test.ts test/viewer-layout.test.ts
+corepack pnpm run viewer:test
+corepack pnpm run viewer:typecheck
+corepack pnpm run build
+git diff --check
+```
+
+Expected: all exit 0.
+
+- [ ] **Step 3: Run broader checks before PR readiness**
+
+Run:
+
+```bash
+corepack pnpm test
+semgrep scan --config p/default --error --metrics=off .
+```
+
+Expected: all exit 0, or record blockers with closest targeted substitutes.
+
+- [ ] **Step 4: Stage and run required staged secret scan**
+
+Stage only task-owned files, inspect staged diff, then run:
+
+```bash
+gitleaks protect --staged --redact
+```
+
+Expected: no leaks.
+
+- [ ] **Step 5: Commit**
+
+Commit with:
+
+```bash
+git commit -m "fix(viewer): expose Chinese localization in web UI"
+```
+
+- [ ] **Step 6: GitHub PR flow**
+
+After green verification and task-state final review notes:
+- fetch/merge current `origin/main` per GitHub push preparation;
+- push `issue/288-web-display-issue` to `origin`;
+- create a PR against `origin/main`;
+- merge only after clean/green PR checks;
+- archive the current Codex thread after successful merge.
+
+## Self-Review
+
+- Spec coverage: The plan covers valid issue classification, switchable locale bundle, UI selector, browser-language handling, representative Dashboard/Memories localization, docs/config discoverability, and verification.
+- Placeholder scan: No `TBD`, `TODO`, or unspecified implementation steps remain.
+- Type consistency: The only locale bundle shape change is additive: `available` is added while existing `lang`, `messages`, and `fallback` remain.
diff --git a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
new file mode 100644
index 000000000..b82ad5f9e
--- /dev/null
+++ b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
@@ -0,0 +1,158 @@
+# Issue 288 Web Display Localization
+
+Scope: repository worktree `/Users/A1538552/.codex/worktrees/4f29/agentmemory`
+
+Branch: `issue/288-web-display-issue`
+
+Issue: https://github.com/wbugitlab1/agentmemory/issues/288
+
+## Sprint Contract
+
+Goal: make the viewer's Chinese UI support discoverable and directly selectable from the web UI, and expand Chinese localization on the highest-traffic shipped viewer surfaces.
+
+Scope:
+- GitHub issue #288 and imported upstream issue #723 evidence.
+- Shipped legacy viewer `src/viewer/index.html`.
+- Viewer locale bundle construction and locale JSON files.
+- Viewer docs/config discoverability in `README.md` and `.env.example`.
+- Focused viewer i18n/security/layout/build tests.
+- Task-local docs under this directory.
+
+Non-goals:
+- Do not change REST, MCP, auth, persistence, schema, ii-engine, stream, proxy, or deployment boundaries.
+- Do not add dependencies or external translation/network services.
+- Do not replace the shipped viewer with the Vue/Vite preview.
+- Do not target `https://github.com/rohitg00/agentmemory/` for branch, push, PR, or issue work.
+- Do not touch the parent checkout or unrelated issue worktrees.
+- Do not delete the ignored `node_modules/` materialized during read-only arena verification without explicit approval.
+
+Acceptance criteria:
+- Issue #288 is classified from local source, local history, and public GitHub issue evidence.
+- The viewer can expose both bundled locales to browser code without weakening CSP or translated-attribute restrictions.
+- Users can switch the shipped viewer between English and Chinese from the UI, with the preference persisted locally.
+- Chinese browser preferences can select Chinese from the bundled locale data when no explicit local viewer preference exists.
+- Dashboard and Memories high-traffic surfaces render through locale keys for representative controls, empty states, table headers, and destructive-confirmation copy.
+- `README.md` and `.env.example` mention `VIEWER_LANGUAGE=zh` / `zh-CN` and the in-viewer picker.
+- Verification evidence records targeted tests, build/check results, and security gates or blockers.
+
+Intended verification:
+- Red/green focused i18n tests before production code.
+- `corepack pnpm exec vitest run test/viewer-i18n.test.ts test/viewer-security.test.ts test/viewer-layout.test.ts`
+- `corepack pnpm run viewer:test`
+- `corepack pnpm run viewer:typecheck`
+- `corepack pnpm run build`
+- `corepack pnpm test` before PR readiness if feasible.
+- `git diff --check`
+- Required security gates for code/config/docs changes: Semgrep; staged Gitleaks before commit. OSV only if dependency/lockfile/package surfaces change.
+
+Known boundaries:
+- The current user request authorizes routine issue reads, this worktree/branch setup, valid-issue branch push, PR creation, clean PR merge to `origin/main`, and post-success thread archival after green verification.
+- Human Checkpoints still apply before invalid/stale/duplicate/already-fixed closure, scope expansion, APIs/auth/persistence/schema/dependencies/architecture changes, or accepting skipped/failing/incomplete verification.
+- Locale strings are content injected into a nonced script; JSON injection must keep escaping `<`, and translated HTML-producing strings must be escaped through existing helpers.
+- Product names, env vars, code snippets, API paths, MCP tool names, backend enum values, and user-generated data may remain English/raw.
+
+Stop conditions:
+- The implementation would require API/auth/persistence/schema/dependency/architecture changes.
+- Existing CSP/nonce/host/security tests cannot be preserved.
+- Correct behavior requires choosing between divergent issue-validity conclusions.
+- Required verification is blocked and no adequate targeted substitute exists.
+
+## Initial State Evidence
+
+- `pwd`: `/Users/A1538552/.codex/worktrees/4f29/agentmemory`.
+- Initial `git status -sb --untracked-files=all`: detached clean `HEAD`.
+- Initial `HEAD`: `499b53fc4a0f58d6f7b2daf674a7943de023d75a`, decorated as `origin/main`.
+- `git remote -v`: `origin` is `https://github.com/wbugitlab1/agentmemory.git`; `upstream` exists but is out of scope.
+- No local or `origin` remote-tracking branch named `issue/288-web-display-issue` existed.
+- Created branch `issue/288-web-display-issue` from `499b53fc4a0f58d6f7b2daf674a7943de023d75a`.
+- Post-branch `git status -sb --untracked-files=all`: `## issue/288-web-display-issue`.
+- `gh issue view 288 --repo wbugitlab1/agentmemory` showed an open imported issue from upstream #723 asking for a Chinese web UI because English and browser translation are painful for ordinary users.
+- Local source already has `src/viewer/locales/zh.json`, `VIEWER_LANGUAGE`, and focused i18n tests from `e437d09e feat(viewer): add Chinese locale support`.
+- Existing task record `docs/todos/2026-06-15-issue-483-viewer-i18n/todo.md` records that full dynamic viewer string localization was intentionally deferred.
+- Arena Candidate C materialized ignored `node_modules/`, `packages/mcp/node_modules/`, and `website/node_modules/` while attempting a read-only pnpm verification. Tracked status remains clean; ignored dependency directories are preserved.
+
+## Arena Synthesis
+
+Base: Candidate B.
+
+Judge result: Candidate B scored 25/25 and was selected as the base conclusion. Candidate A scored 23/25. Candidate C scored 21/25.
+
+Synthesis decision: Issue #288 is a valid unresolved localization coverage and discoverability gap. It is stale only for the narrow claim that no Chinese locale exists. It should not be closed as fixed or duplicate without a Human Checkpoint.
+
+Grafts:
+- From Candidate A: route/build-path inventory, preview-app caveat, and rejection of wholesale upstream PR #673 import.
+- From Candidate C: rendered-output proof style, CJK font fallback nuance, and separation of CJK search from UI localization.
+
+Rejected:
+- Closing as already fixed because `zh.json` exists.
+- Treating CJK search as the fix for UI localization.
+- Importing stale upstream i18n PRs wholesale.
+- Replacing the shipped viewer with the Vue/Vite preview as part of this issue.
+
+## Feature / Verification Matrix
+
+| Change | Verification method | Status | Evidence |
+| --- | --- | --- | --- |
+| Validate issue #288 | Arena reports, judge, public issue reads, local source/history | Done | Consensus: valid localization coverage/discoverability gap. |
+| Task-state and plan | Saved `todo.md`, `plan.md`, arena synthesis | Done | Task record, plan, and arena synthesis created before production/test edits. |
+| Locale bundle exposes switchable locales | Red/green tests in `test/viewer-i18n.test.ts` | Done | RED failed on missing `available`; GREEN focused i18n suite passed 17 tests. |
+| Viewer language picker and browser preference | Red/green tests plus source inspection/browser smoke if feasible | Done | RED failed on missing picker/storage/navigator hook and switch function; GREEN focused i18n suite passed. |
+| Dashboard/Memories representative localization | Locale parity tests and rendered/source assertions | Done | RED failed on hardcoded strings and no dynamic switch; GREEN focused i18n suite passed. |
+| Docs/config discoverability | Source diff and README/.env checks | Done | `rg -n "VIEWER_LANGUAGE|Simplified Chinese|language selector|zh-CN" README.md .env.example` found README and `.env.example` entries. |
+| Security posture | Viewer security tests, Semgrep, staged Gitleaks | Done | Viewer security suite passed, Semgrep found 0 findings, and staged Gitleaks found no leaks. |
+| Build/type/test coverage | Focused viewer tests, build, full tests if feasible | Done | Focused viewer suite, `viewer:test`, `viewer:typecheck`, `build`, `pnpm test`, `git diff --check`, and locale JSON parse all passed. |
+| PR flow | Push branch, create PR, clean merge to `origin/main`, archive thread | Pending | Authorized after green verification by current request. |
+
+## Subagent Ledger
+
+| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk |
+| --- | --- | --- | --- | --- | --- |
+| Arena Candidate A | Issue validity/reproduction only | No | Candidate report | Complete: `/tmp/arena-288/candidate-a.md`. | Did not run tests due missing dependencies. |
+| Arena Candidate B | Issue validity/reproduction only | No | Candidate report | Complete: `/tmp/arena-288/candidate-b.md`. | Did not run tests due missing dependencies. |
+| Arena Candidate C | Issue validity/reproduction only | No | Candidate report | Complete: `/tmp/arena-288/candidate-c.md`. | Materialized ignored dependency directories during verification attempt. |
+| Arena judge | Candidate scoring only | No | Judge report | Complete: `/tmp/arena-288/judge.md`; picked Candidate B. | Judge did not run tests. |
+| Pre-code scope reviewer | Plan/task record scope and acceptance criteria | No | High/Medium findings | Complete: two Medium findings accepted. | Required plan updates before implementation. |
+| Pre-code integration reviewer | Viewer runtime/CSP/integration plan risk | No | High/Medium findings | Complete: one Medium finding accepted. | Required dynamic re-render tests before implementation. |
+| Pre-code verification reviewer | Test and verification plan gaps | No | High/Medium findings | Inconclusive: did not return before deterministic verification completed. | Covered by focused suites, build, full tests, `git diff --check`, Semgrep, and staged Gitleaks gate. |
+
+## Review Triage
+
+| Finding | Classification | Action |
+| --- | --- | --- |
+| Task 4 allowed `tRaw()` in HTML builders, which can inject unescaped locale content into `innerHTML`. | fixed | Updated `plan.md` to require `t()` for all translated strings concatenated into HTML/modal HTML and reserve `tRaw()` for textContent/safe attributes/non-HTML contexts. |
+| Planned tests did not prove Dashboard/Memories render paths actually localize. | fixed | Updated `plan.md` to require red tests/source or sandbox assertions for first-run copy, stat labels, Memories search/empty states/table headers, and delete modal copy. |
+| Runtime language switching only reapplied static `data-i18n` chrome, not already-rendered dynamic Dashboard/Memories content. | fixed | Updated `plan.md` to require switch handler updates the active bundle and re-renders loaded Dashboard/Memories surfaces, with a sandbox test proving text changes. |
+
+## Progress Notes
+
+- 2026-06-19: Read governing `AGENTS.md`, `arena`, `github-feature-loop`, `writing-plans`, `review-and-implement`, `test-driven-development`, `verification-before-completion`, `simple-code`, and `github-push-prepare` skill instructions.
+- 2026-06-19: No `docs/lessons/` directory exists in this worktree.
+- 2026-06-19: Relevant prior task records inspected: issue 483 viewer i18n, issue 612 dashboard errors, and issue 148 Vue/Vite preview migration.
+- 2026-06-19: Implementation scope constrained to viewer locale discoverability/switching and representative high-traffic shipped viewer localization.
+- 2026-06-19: Pre-code review round found valid Medium plan gaps around escaped locale insertion, rendered Dashboard/Memories proof, and dynamic re-rendering after a language switch; `plan.md` updated before production/test edits.
+- 2026-06-19: RED i18n verification first hit pnpm ignored-build hardening before Vitest. Ran `env -u NPM_TOKEN -u NODE_AUTH_TOKEN -u GITHUB_TOKEN -u GH_TOKEN -u GITLAB_TOKEN -u GLAB_TOKEN corepack pnpm install --frozen-lockfile --ignore-scripts`, which exited 0 without approving builds or changing manifests.
+- 2026-06-19: RED i18n run then failed 4 expected tests: missing bundled `available` locales, missing picker/browser hook, hardcoded Dashboard/Memories render paths, and missing runtime language switch.
+- 2026-06-19: Implemented additive `available` locale bundle, viewer language selector/localStorage/browser preference handling, dynamic Dashboard/Memories re-rendering on language switch, representative Dashboard/Memories locale keys, and README/.env discoverability.
+- 2026-06-19: Tightened startup language precedence so a non-English `VIEWER_LANGUAGE` default wins over browser language while unset English defaults can still auto-select Chinese browser preferences.
+- 2026-06-20: Added `html[lang="zh"]` CJK system font fallbacks so Chinese mode does not depend on browser translation styling or external fonts.
+- 2026-06-20: Final manual review found no new API/auth/persistence/schema/dependency/architecture boundary changes and no need for OSV because dependency, lockfile, package-manager, container, and vendored surfaces were unchanged.
+
+## Verification Evidence
+
+- `corepack pnpm exec vitest run test/viewer-i18n.test.ts`: RED after setup, 4 expected failures / 13 existing passes.
+- `corepack pnpm exec vitest run test/viewer-i18n.test.ts`: GREEN, 17 tests passed.
+- `corepack pnpm exec vitest run test/viewer-i18n.test.ts test/viewer-security.test.ts test/viewer-layout.test.ts`: GREEN, 3 files / 37 tests passed.
+- `rg -n "VIEWER_LANGUAGE|Simplified Chinese|language selector|zh-CN" README.md .env.example`: found the new README and `.env.example` docs.
+- `corepack pnpm exec vitest run test/viewer-i18n.test.ts test/viewer-security.test.ts test/viewer-layout.test.ts`: GREEN after CJK font fallback, 3 files / 37 tests passed.
+- `corepack pnpm run viewer:test`: GREEN, 4 files / 20 tests passed.
+- `corepack pnpm run viewer:typecheck`: GREEN.
+- `corepack pnpm run build`: GREEN; existing tsdown/vite warnings only.
+- `corepack pnpm test`: GREEN, 207 files / 2831 tests passed.
+- `git diff --check`: GREEN.
+- `jq empty src/viewer/locales/en.json src/viewer/locales/zh.json`: GREEN.
+- `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
+- `gitleaks protect --staged --redact`: GREEN, no leaks found.
+
+## Final Review Notes
+
+Sprint Contract acceptance criteria are met locally. Remaining authorized workflow steps are commit, push, PR creation, clean merge after remote checks, and thread archival.
diff --git a/src/viewer/index.html b/src/viewer/index.html
index 159db6bd4..14563deba 100644
--- a/src/viewer/index.html
+++ b/src/viewer/index.html
@@ -49,6 +49,11 @@
       --font-ui: 'Inter', -apple-system, sans-serif;
       --font-mono: 'JetBrains Mono', 'SF Mono', 'Fira Code', monospace;
     }
+    html[lang="zh"] {
+      --font-display: 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC', 'Source Han Sans SC', system-ui, sans-serif;
+      --font-body: 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC', 'Source Han Sans SC', system-ui, sans-serif;
+      --font-ui: 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC', 'Source Han Sans SC', -apple-system, BlinkMacSystemFont, sans-serif;
+    }
     html[data-theme="dark"] {
       --bg: #1a1a1e;
       --bg-alt: #232328;
@@ -161,6 +166,17 @@
     .ws-status.connected::before { background: var(--green); }
     .ws-status.disconnected { border-color: var(--ink-faint); color: var(--ink-faint); }
     .ws-status.disconnected::before { background: var(--ink-faint); }
+    .language-select {
+      background: var(--bg);
+      border: 1px solid var(--border-light);
+      color: var(--ink);
+      padding: 3px 8px;
+      font-size: 10px;
+      font-family: var(--font-ui);
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      font-weight: 600;
+    }
 
     .tab-bar {
       display: flex;
@@ -1087,6 +1103,10 @@ <h1>agentmemory</h1>
     </a>
     <div class="header-right">
       <span class="dateline" id="dateline"></span>
+      <select id="language-select" class="language-select" aria-label="Language" data-i18n-attr="aria-label:language.label">
+        <option value="en" data-i18n="language.english">English</option>
+        <option value="zh" data-i18n="language.chinese">Chinese</option>
+      </select>
       <button id="theme-toggle" class="btn" style="font-size:9px;padding:3px 10px;letter-spacing:0.1em;margin-right:8px;" data-action="toggle-theme">DARK</button>
       <span id="ws-status" class="ws-status disconnected" data-i18n="status.live_updates_off">live updates off</span>
     </div>
@@ -1141,7 +1161,11 @@ <h1>agentmemory</h1>
   <script nonce="__AGENTMEMORY_VIEWER_NONCE__">
     window.__AM_LOCALE__ = __AGENTMEMORY_LOCALE__;
     (function () {
-      var bundle = window.__AM_LOCALE__ || { lang: 'en', messages: {}, fallback: {} };
+      var injectedBundle = window.__AM_LOCALE__ || { lang: 'en', messages: {}, fallback: {}, available: {} };
+      var availableLocales = injectedBundle.available || {};
+      if (!availableLocales.en && injectedBundle.lang === 'en') availableLocales.en = injectedBundle.messages || {};
+      if (injectedBundle.lang && !availableLocales[injectedBundle.lang]) availableLocales[injectedBundle.lang] = injectedBundle.messages || {};
+      var VIEWER_LANGUAGE_STORAGE_KEY = 'agentmemory-viewer-language';
       function getPath(obj, path) {
         return String(path || '').split('.').reduce(function (current, key) {
           return current && typeof current === 'object' && Object.prototype.hasOwnProperty.call(current, key)
@@ -1149,6 +1173,49 @@ <h1>agentmemory</h1>
             : undefined;
         }, obj);
       }
+      function canonicalLanguage(input) {
+        var primary = String(input || '').trim().toLowerCase().split(/[-_]/)[0];
+        return /^[a-z]{2,3}$/.test(primary) ? primary : '';
+      }
+      function hasLocale(lang) {
+        return !!(lang && Object.prototype.hasOwnProperty.call(availableLocales, lang));
+      }
+      function buildActiveBundle(lang) {
+        var selected = hasLocale(lang) ? lang : 'en';
+        return {
+          lang: selected,
+          messages: availableLocales[selected] || {},
+          fallback: selected === 'en' ? {} : (availableLocales.en || injectedBundle.fallback || {})
+        };
+      }
+      function safeStorageGet(key) {
+        try { return localStorage.getItem(key); } catch { return null; }
+      }
+      function safeStorageSet(key, value) {
+        try { localStorage.setItem(key, value); } catch {}
+      }
+      function preferredBrowserLanguage() {
+        var languages = [];
+        if (typeof navigator !== 'undefined') {
+          if (Array.isArray(navigator.languages)) languages = navigator.languages;
+          else if (navigator.language) languages = [navigator.language];
+        }
+        for (var i = 0; i < languages.length; i++) {
+          var lang = canonicalLanguage(languages[i]);
+          if (hasLocale(lang)) return lang;
+        }
+        return '';
+      }
+      function initialLanguage() {
+        var stored = canonicalLanguage(safeStorageGet(VIEWER_LANGUAGE_STORAGE_KEY));
+        if (hasLocale(stored)) return stored;
+        var injected = canonicalLanguage(injectedBundle.lang);
+        if (hasLocale(injected) && injected !== 'en') return injected;
+        var browser = preferredBrowserLanguage();
+        if (browser) return browser;
+        return hasLocale(injected) ? injected : 'en';
+      }
+      var activeBundle = buildActiveBundle(initialLanguage());
       function interpolate(str, vars) {
         if (!vars || typeof str !== 'string') return str;
         return str.replace(/\{(\w+)\}/g, function (_, key) {
@@ -1161,19 +1228,23 @@ <h1>agentmemory</h1>
         });
       }
       window.t = function (key, vars) {
-        var value = getPath(bundle.messages, key);
+        var value = getPath(activeBundle.messages, key);
         if (typeof value === 'string') return interpolate(escI18n(value), vars);
-        var fallback = getPath(bundle.fallback, key);
+        var fallback = getPath(activeBundle.fallback, key);
         if (typeof fallback === 'string') return interpolate(escI18n(fallback), vars);
         return key;
       };
       window.tRaw = function (key, vars) {
-        var value = getPath(bundle.messages, key);
+        var value = getPath(activeBundle.messages, key);
         if (typeof value === 'string') return interpolate(value, vars);
-        var fallback = getPath(bundle.fallback, key);
+        var fallback = getPath(activeBundle.fallback, key);
         if (typeof fallback === 'string') return interpolate(fallback, vars);
         return key;
       };
+      function updateLanguageSelect(lang) {
+        var select = document.getElementById('language-select');
+        if (select) select.value = lang;
+      }
       var SAFE_I18N_ATTRS = new Set([
         'placeholder',
         'title',
@@ -1196,10 +1267,38 @@ <h1>agentmemory</h1>
           });
         });
       };
-      document.documentElement.lang = bundle.lang || 'en';
+      window.setViewerLanguage = function (lang, persist) {
+        var selected = canonicalLanguage(lang);
+        if (!hasLocale(selected)) selected = 'en';
+        activeBundle = buildActiveBundle(selected);
+        if (window.__AM_LOCALE__) {
+          window.__AM_LOCALE__.lang = activeBundle.lang;
+          window.__AM_LOCALE__.messages = activeBundle.messages;
+          window.__AM_LOCALE__.fallback = activeBundle.fallback;
+        }
+        document.documentElement.lang = activeBundle.lang;
+        updateLanguageSelect(activeBundle.lang);
+        window.applyI18n(document);
+        if (persist) safeStorageSet(VIEWER_LANGUAGE_STORAGE_KEY, activeBundle.lang);
+        if (typeof window.refreshLocalizedViews === 'function') window.refreshLocalizedViews();
+        return activeBundle.lang;
+      };
+      function wireLanguageSelect() {
+        var select = document.getElementById('language-select');
+        if (!select) return;
+        updateLanguageSelect(activeBundle.lang);
+        select.addEventListener('change', function () {
+          window.setViewerLanguage(select.value, true);
+        });
+      }
+      document.documentElement.lang = activeBundle.lang;
       if (document.readyState === 'loading') {
-        document.addEventListener('DOMContentLoaded', function () { window.applyI18n(document); });
+        document.addEventListener('DOMContentLoaded', function () {
+          wireLanguageSelect();
+          window.applyI18n(document);
+        });
       } else {
+        wireLanguageSelect();
         window.applyI18n(document);
       }
     })();
@@ -1780,29 +1879,29 @@ <h1>agentmemory</h1>
       // First-run hero: empty dashboard = guided next step
       if (sessions.length === 0) {
         html += '<div class="card" style="margin-bottom:14px;padding:24px 28px;background:var(--bg-subtle);border-left:3px solid var(--accent);">' +
-          '<div style="font-family:var(--font-ui);font-size:11px;letter-spacing:0.15em;text-transform:uppercase;color:var(--accent);font-weight:700;margin-bottom:8px;">First run &rarr; magical moment in 10 seconds</div>' +
-          '<div style="font-family:var(--font-display,Lora,Georgia,serif);font-size:22px;font-weight:700;color:var(--ink);margin-bottom:8px;">Seed sample data + prove semantic recall works</div>' +
-          '<div style="font-size:13px;color:var(--ink-muted);margin-bottom:12px;line-height:1.5;max-width:640px;">agentmemory is running but hasn&rsquo;t seen any sessions yet. Run the demo command in a second terminal: it seeds 3 realistic coding sessions and proves the hybrid search finds semantically-related memories that keyword search would miss.</div>' +
+          '<div style="font-family:var(--font-ui);font-size:11px;letter-spacing:0.15em;text-transform:uppercase;color:var(--accent);font-weight:700;margin-bottom:8px;">' + t('dashboard.first_run_eyebrow') + '</div>' +
+          '<div style="font-family:var(--font-display,Lora,Georgia,serif);font-size:22px;font-weight:700;color:var(--ink);margin-bottom:8px;">' + t('dashboard.first_run_title') + '</div>' +
+          '<div style="font-size:13px;color:var(--ink-muted);margin-bottom:12px;line-height:1.5;max-width:640px;">' + t('dashboard.first_run_body') + '</div>' +
           '<pre style="display:inline-block;margin:0;padding:10px 14px;background:var(--bg);border:1px solid var(--border);border-radius:4px;font-family:var(--font-mono);font-size:12px;color:var(--ink);">npx @agentmemory/agentmemory demo</pre>' +
-          '<div style="margin-top:10px;"><a class="empty-link" href="https://github.com/rohitg00/agentmemory#quick-start" target="_blank" rel="noopener" style="font-size:12px;">Or: wire up your real agent &rarr;</a></div>' +
+          '<div style="margin-top:10px;"><a class="empty-link" href="https://github.com/rohitg00/agentmemory#quick-start" target="_blank" rel="noopener" style="font-size:12px;">' + t('dashboard.first_run_link') + '</a></div>' +
           '</div>';
       }
       html += '<div class="stats-grid">';
-      html += '<div class="stat-card"><div class="label">Sessions</div><div class="value">' + sessions.length + '</div><div class="sub">' + activeSessions + ' active</div></div>';
-      html += '<div class="stat-card"><div class="label">Memories</div><div class="value">' + memories.length + '</div><div class="sub">latest versions</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.sessions') + '</div><div class="value">' + sessions.length + '</div><div class="sub">' + t('dashboard.cards.active', { count: activeSessions }) + '</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.memories') + '</div><div class="value">' + memories.length + '</div><div class="sub">' + t('dashboard.cards.latest_versions') + '</div></div>';
       var lessonCount = arrayOrEmpty(d.lessons).length;
       var crystalCount = arrayOrEmpty(d.crystals).length;
-      html += '<div class="stat-card"><div class="label">Lessons</div><div class="value">' + lessonCount + '</div><div class="sub">confidence-scored</div></div>';
-      html += '<div class="stat-card"><div class="label">Crystals</div><div class="value">' + crystalCount + '</div><div class="sub">action digests</div></div>';
-      html += '<div class="stat-card"><div class="label">Graph Nodes</div><div class="value">' + nodeCount + '</div><div class="sub">' + edgeCount + ' edges</div></div>';
-      html += '<div class="stat-card"><div class="label">Health</div><div class="value"><div class="health-bar"><span class="health-dot ' + dotClass + '"></span> ' + esc(healthStatus) + '</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.lessons') + '</div><div class="value">' + lessonCount + '</div><div class="sub">' + t('dashboard.cards.confidence_scored') + '</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.crystals') + '</div><div class="value">' + crystalCount + '</div><div class="sub">' + t('dashboard.cards.action_digests') + '</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.graph_nodes') + '</div><div class="value">' + nodeCount + '</div><div class="sub">' + t('dashboard.cards.edges', { count: edgeCount }) + '</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.health') + '</div><div class="value"><div class="health-bar"><span class="health-dot ' + dotClass + '"></span> ' + esc(healthStatus) + '</div></div>';
       html += '<div class="sub">' + esc(snap.connectionState || 'unknown') + '</div></div>';
       var totalCalls = fMetrics.reduce(function(a, m) { return a + (m.totalCalls || 0); }, 0);
-      html += '<div class="stat-card"><div class="label">Function Calls</div><div class="value">' + totalCalls + '</div><div class="sub">' + fMetrics.length + ' functions tracked</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.function_calls') + '</div><div class="value">' + totalCalls + '</div><div class="sub">' + t('dashboard.cards.functions_tracked', { count: fMetrics.length }) + '</div></div>';
       if (cb) {
         var cbClass = cb.state === 'closed' ? 'cb-closed' : cb.state === 'open' ? 'cb-open' : 'cb-half-open';
-        html += '<div class="stat-card"><div class="label">Circuit Breaker</div><div class="value"><span class="cb-indicator ' + cbClass + '">' + esc(cb.state) + '</span></div>';
-        html += '<div class="sub">' + (cb.failures || 0) + ' failures</div></div>';
+        html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.circuit_breaker') + '</div><div class="value"><span class="cb-indicator ' + cbClass + '">' + esc(cb.state) + '</span></div>';
+        html += '<div class="sub">' + t('dashboard.cards.failures', { count: cb.failures || 0 }) + '</div></div>';
       }
       var totalObs = sessions.reduce(function(a, s) { return a + (s.observationCount || 0); }, 0);
       var estFull = totalObs * 80;
@@ -1814,11 +1913,11 @@ <h1>agentmemory</h1>
       var costDollars = tokensSaved / 1000 * 0.3;
       var costCents = Math.round(costDollars * 100);
       var costStr = costCents >= 100 ? '$' + (costCents / 100).toFixed(2) : costCents + 'ct';
-      html += '<div class="stat-card"><div class="label">Token Savings</div><div class="value">' + savings + '%</div><div class="sub">~' + tokensSaved.toLocaleString() + ' tokens · ' + costStr + ' saved</div></div>';
+      html += '<div class="stat-card"><div class="label">' + t('dashboard.cards.token_savings') + '</div><div class="value">' + savings + '%</div><div class="sub">' + t('dashboard.cards.tokens_saved', { tokens: tokensSaved.toLocaleString(), cost: costStr }) + '</div></div>';
       html += '</div>';
 
       if (snap.memory || snap.cpu) {
-        html += '<div class="card" style="margin-bottom:16px"><div class="card-title">System Resources</div>';
+        html += '<div class="card" style="margin-bottom:16px"><div class="card-title">' + t('dashboard.sections.system_resources') + '</div>';
         if (snap.memory) {
           var heapUsed = Math.round((snap.memory.heapUsed || 0) / 1024 / 1024);
           var heapTotal = Math.round((snap.memory.heapTotal || 0) / 1024 / 1024);
@@ -1826,35 +1925,35 @@ <h1>agentmemory</h1>
           var heapPct = heapTotal > 0 ? Math.round((heapUsed / heapTotal) * 100) : 0;
           var rssAboveFloor = rss >= 512;
           var heapColor = (heapPct > 80 && rssAboveFloor) ? 'var(--red)' : (heapPct > 60 && rssAboveFloor) ? 'var(--yellow)' : 'var(--green)';
-          html += '<div class="gauge"><span class="gauge-label">Heap</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + heapPct + '%;background:' + heapColor + '"></div></div><span class="gauge-value">' + heapUsed + ' / ' + heapTotal + ' MB</span></div>';
-          html += '<div class="gauge"><span class="gauge-label">RSS</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, Math.round(rss / 512 * 100)) + '%;background:var(--blue)"></div></div><span class="gauge-value">' + rss + ' MB</span></div>';
+          html += '<div class="gauge"><span class="gauge-label">' + t('dashboard.sections.heap') + '</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + heapPct + '%;background:' + heapColor + '"></div></div><span class="gauge-value">' + heapUsed + ' / ' + heapTotal + ' MB</span></div>';
+          html += '<div class="gauge"><span class="gauge-label">' + t('dashboard.sections.rss') + '</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, Math.round(rss / 512 * 100)) + '%;background:var(--blue)"></div></div><span class="gauge-value">' + rss + ' MB</span></div>';
           if (snap.memory.external) {
             var ext = Math.round(snap.memory.external / 1024 / 1024);
-            html += '<div class="gauge"><span class="gauge-label">External</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, Math.round(ext / 128 * 100)) + '%;background:var(--purple)"></div></div><span class="gauge-value">' + ext + ' MB</span></div>';
+            html += '<div class="gauge"><span class="gauge-label">' + t('dashboard.sections.external') + '</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, Math.round(ext / 128 * 100)) + '%;background:var(--purple)"></div></div><span class="gauge-value">' + ext + ' MB</span></div>';
           }
         }
         if (snap.cpu) {
           var cpuPct = snap.cpu.percent || 0;
           var cpuColor = cpuPct > 80 ? 'var(--red)' : cpuPct > 50 ? 'var(--yellow)' : 'var(--green)';
-          html += '<div class="gauge"><span class="gauge-label">CPU</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, cpuPct) + '%;background:' + cpuColor + '"></div></div><span class="gauge-value">' + cpuPct.toFixed(1) + '%</span></div>';
+          html += '<div class="gauge"><span class="gauge-label">' + t('dashboard.sections.cpu') + '</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, cpuPct) + '%;background:' + cpuColor + '"></div></div><span class="gauge-value">' + cpuPct.toFixed(1) + '%</span></div>';
         }
         if (snap.eventLoopLagMs !== undefined) {
           var lag = snap.eventLoopLagMs;
           var lagColor = lag > 100 ? 'var(--red)' : lag > 20 ? 'var(--yellow)' : 'var(--green)';
-          html += '<div class="gauge"><span class="gauge-label">Event Loop</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, lag) + '%;background:' + lagColor + '"></div></div><span class="gauge-value">' + lag.toFixed(1) + ' ms</span></div>';
+          html += '<div class="gauge"><span class="gauge-label">' + t('dashboard.sections.event_loop') + '</span><div class="gauge-bar"><div class="gauge-fill" style="width:' + Math.min(100, lag) + '%;background:' + lagColor + '"></div></div><span class="gauge-value">' + lag.toFixed(1) + ' ms</span></div>';
         }
         if (snap.uptimeSeconds) {
           var mins = Math.floor(snap.uptimeSeconds / 60);
           var hrs = Math.floor(mins / 60);
           var upStr = hrs > 0 ? hrs + 'h ' + (mins % 60) + 'm' : mins + 'm';
-          html += '<div style="font-size:10px;color:var(--ink-faint);margin-top:6px;font-family:var(--font-mono);letter-spacing:0.04em;">UPTIME: ' + upStr + '</div>';
+          html += '<div style="font-size:10px;color:var(--ink-faint);margin-top:6px;font-family:var(--font-mono);letter-spacing:0.04em;">' + t('dashboard.sections.uptime', { uptime: upStr }) + '</div>';
         }
         html += '</div>';
       }
 
       var alerts = arrayOrEmpty(snap.alerts);
       if (alerts.length > 0) {
-        html += '<div class="card" style="margin-bottom:16px;border-color:var(--accent);border-width:2px;"><div class="card-title" style="color:var(--accent);border-bottom-color:var(--accent);">Alerts (' + alerts.length + ')</div>';
+        html += '<div class="card" style="margin-bottom:16px;border-color:var(--accent);border-width:2px;"><div class="card-title" style="color:var(--accent);border-bottom-color:var(--accent);">' + t('dashboard.sections.alerts', { count: alerts.length }) + '</div>';
         alerts.forEach(function(al) {
           html += '<div style="font-size:12px;color:var(--accent);padding:4px 0;border-bottom:1px solid var(--border-light);font-family:var(--font-ui);">' + esc(al) + '</div>';
         });
@@ -1863,7 +1962,7 @@ <h1>agentmemory</h1>
 
       var notes = arrayOrEmpty(snap.notes);
       if (notes.length > 0) {
-        html += '<div class="card" style="margin-bottom:16px;"><div class="card-title" style="color:var(--ink-muted);">Notes (' + notes.length + ')</div>';
+        html += '<div class="card" style="margin-bottom:16px;"><div class="card-title" style="color:var(--ink-muted);">' + t('dashboard.sections.notes', { count: notes.length }) + '</div>';
         notes.forEach(function(n) {
           html += '<div style="font-size:12px;color:var(--ink-muted);padding:4px 0;border-bottom:1px solid var(--border-light);font-family:var(--font-ui);">' + esc(n) + '</div>';
         });
@@ -1872,12 +1971,12 @@ <h1>agentmemory</h1>
 
       html += '<div class="two-col">';
 
-      html += '<div class="card"><div class="card-title">Recent Sessions</div>';
+      html += '<div class="card"><div class="card-title">' + t('dashboard.sections.recent_sessions') + '</div>';
       if (sessions.length === 0) {
-        html += '<div class="empty-state"><p>No sessions yet. Start a coding session with agentmemory hooks enabled.</p></div>';
+        html += '<div class="empty-state"><p>' + t('dashboard.empty.no_sessions') + '</p></div>';
       } else {
         var recent = sessions.slice().sort(function(a, b) { return (b.startedAt || '').localeCompare(a.startedAt || ''); }).slice(0, 5);
-        html += '<table><tr><th>Project</th><th>Status</th><th>Obs</th><th>Started</th></tr>';
+        html += '<table><tr><th>' + t('dashboard.table.project') + '</th><th>' + t('dashboard.table.status') + '</th><th>' + t('dashboard.table.obs') + '</th><th>' + t('dashboard.table.started') + '</th></tr>';
         recent.forEach(function(s) {
           var statusBadge = s.status === 'active' ? 'badge-green' : s.status === 'completed' ? 'badge-blue' : 'badge-muted';
           var agentLabel = sessionAgentLabel(s);
@@ -1892,9 +1991,9 @@ <h1>agentmemory</h1>
       }
       html += '</div>';
 
-      html += '<div class="card"><div class="card-title">Recent Activity</div>';
+      html += '<div class="card"><div class="card-title">' + t('dashboard.sections.recent_activity') + '</div>';
       if (recentAudit.length === 0) {
-        html += '<div class="empty-state"><p>No activity recorded yet</p></div>';
+        html += '<div class="empty-state"><p>' + t('dashboard.empty.no_activity') + '</p></div>';
       } else {
         recentAudit.forEach(function(a) {
           var badgeClass = OP_BADGES[a.operation] || 'badge-muted';
@@ -2871,38 +2970,38 @@ <h1>agentmemory</h1>
 
       var html = '<div class="card" style="margin-bottom:12px;padding:12px;background:var(--bg-subtle);">';
       html += '<div style="font-size:13px;color:var(--ink-muted);line-height:1.5;">';
-      html += '<strong>Memories</strong> are durable facts, architecture notes, conventions, and lessons saved via <code>memory_remember</code> MCP tool or the <code>/agentmemory/remember</code> endpoint. They survive across sessions and supersede each other as v1, v2, etc. ';
-      html += '<span style="color:var(--ink-faint);">Shown: ' + items.length + ' of ' + state.memories.total + ' total.</span>';
+      html += '<strong>' + t('memories.title') + '</strong> ' + t('memories.description') + ' ';
+      html += '<span style="color:var(--ink-faint);">' + t('memories.shown', { shown: items.length, total: state.memories.total }) + '</span>';
       html += '</div></div>';
 
       html += '<div class="toolbar">';
-      html += '<input type="text" id="mem-search" placeholder="Search memories..." value="' + esc(state.memories.search) + '">';
-      html += '<select id="mem-type-filter"><option value="">All types</option>';
+      html += '<input type="text" id="mem-search" placeholder="' + t('memories.search_placeholder') + '" value="' + esc(state.memories.search) + '">';
+      html += '<select id="mem-type-filter"><option value="">' + t('memories.all_types') + '</option>';
       typeOptions.forEach(function(t) {
         html += '<option value="' + esc(t) + '"' + (typeFilter === t ? ' selected' : '') + '>' + esc(t) + '</option>';
       });
       html += '</select></div>';
 
       if (state.memories.searching) {
-        html += '<div class="loading">Searching memories...</div>';
+        html += '<div class="loading">' + t('memories.searching') + '</div>';
       } else if (filtered.length === 0) {
         if (search) {
           html += '<div class="empty-state">' +
             '<div class="empty-icon">&#128269;</div>' +
-            '<div class="empty-title">No results for "' + esc(truncate(search, 30)) + '"</div>' +
-            '<div class="empty-lead">Try different keywords or clear the search.</div>' +
+            '<div class="empty-title">' + t('memories.no_results_title', { query: truncate(search, 30) }) + '</div>' +
+            '<div class="empty-lead">' + t('memories.no_results_lead') + '</div>' +
             '</div>';
         } else {
           html += '<div class="empty-state">' +
             '<div class="empty-icon">&#128218;</div>' +
-            '<div class="empty-title">No memories yet</div>' +
-            '<div class="empty-lead">Memories are the distilled facts agentmemory keeps across sessions &mdash; things like file paths, architectural decisions, and user preferences. Hooks capture them automatically during coding sessions; you can also save one directly.</div>' +
+            '<div class="empty-title">' + t('memories.empty_title') + '</div>' +
+            '<div class="empty-lead">' + t('memories.empty_lead') + '</div>' +
             '<pre class="empty-cmd">memory_remember {\n  title: "auth uses jose middleware",\n  content: "src/middleware/auth.ts handles JWT validation",\n  type: "architecture"\n}</pre>' +
-            '<div><a class="empty-link" href="https://github.com/rohitg00/agentmemory#memories" target="_blank" rel="noopener">Memory types &rarr;</a></div>' +
+            '<div><a class="empty-link" href="https://github.com/rohitg00/agentmemory#memories" target="_blank" rel="noopener">' + t('memories.memory_types_link') + '</a></div>' +
             '</div>';
         }
       } else {
-        html += '<table><tr><th>Title</th><th>Type</th><th>Strength</th><th>Version</th><th>Updated</th><th>Actions</th></tr>';
+        html += '<table><tr><th>' + t('memories.table.title') + '</th><th>' + t('memories.table.type') + '</th><th>' + t('memories.table.strength') + '</th><th>' + t('memories.table.version') + '</th><th>' + t('memories.table.updated') + '</th><th>' + t('memories.table.actions') + '</th></tr>';
         filtered.forEach(function(m) {
           var badgeClass = TYPE_BADGES[m.type] || 'badge-muted';
           var rawStrength = m.strength || 0;
@@ -2928,7 +3027,7 @@ <h1>agentmemory</h1>
           html += '<td><div class="strength-bar"><div class="fill" style="width:' + strength + '%;background:' + barColor + '"></div></div> <span style="font-size:10px;color:var(--ink-faint);font-family:var(--font-mono);">' + strength + '%</span></td>';
           html += '<td style="color:var(--ink-muted);font-family:var(--font-mono);font-size:12px;">v' + (m.version || 1) + '</td>';
           html += '<td style="font-size:11px;color:var(--ink-faint);font-family:var(--font-mono);">' + esc(formatTime(m.updatedAt)) + '</td>';
-          html += '<td><button class="btn btn-danger" style="font-size:9px;padding:2px 8px;" data-action="delete-memory" data-memory-id="' + esc(m.id) + '" data-memory-title="' + esc(m.title || '') + '">Delete</button></td>';
+          html += '<td><button class="btn btn-danger" style="font-size:9px;padding:2px 8px;" data-action="delete-memory" data-memory-id="' + esc(m.id) + '" data-memory-title="' + esc(m.title || '') + '">' + t('common.delete') + '</button></td>';
           html += '</tr>';
         });
         html += '</table>';
@@ -2954,10 +3053,16 @@ <h1>agentmemory</h1>
     function deleteMemory(id, title) {
       var modal = document.getElementById('modal');
       var overlay = document.getElementById('modal-overlay');
-      modal.innerHTML = '<h3>Delete Memory</h3><p>Are you sure you want to delete "' + esc(title) + '"? This action cannot be undone.</p><div class="modal-actions"><button class="btn" data-action="close-modal">Cancel</button><button class="btn btn-danger" data-action="confirm-delete-memory" data-memory-id="' + esc(id) + '">Delete</button></div>';
+      modal.innerHTML = '<h3>' + t('memories.delete_title') + '</h3><p>' + t('memories.delete_confirm', { title: title }) + '</p><div class="modal-actions"><button class="btn" data-action="close-modal">' + t('common.cancel') + '</button><button class="btn btn-danger" data-action="confirm-delete-memory" data-memory-id="' + esc(id) + '">' + t('common.delete') + '</button></div>';
       overlay.classList.add('open');
     }
 
+    function refreshLocalizedViews() {
+      if (state.dashboard && state.dashboard.loaded) renderDashboard();
+      if (state.memories && state.memories.loaded) renderMemories();
+    }
+    window.refreshLocalizedViews = refreshLocalizedViews;
+
     async function confirmDeleteMemory(id) {
       closeModal();
       await apiDelete('governance/memories', { memoryIds: [id], reason: 'Deleted via viewer' });
diff --git a/src/viewer/locales.ts b/src/viewer/locales.ts
index 43caf3c78..e2b7edd0a 100644
--- a/src/viewer/locales.ts
+++ b/src/viewer/locales.ts
@@ -8,8 +8,11 @@ export type LocaleBundle = {
   lang: string;
   messages: LocaleMessages;
   fallback: LocaleMessages;
+  available: Record<string, LocaleMessages>;
 };
 
+const BUNDLED_VIEWER_LOCALES = ["en", "zh"] as const;
+
 function canonicalLanguage(input: string | undefined): string {
   const primary = (input || "en").trim().toLowerCase().split(/[-_]/)[0];
   return /^[a-z]{2,3}$/.test(primary) ? primary : "en";
@@ -45,11 +48,15 @@ export function loadLocale(lang: string): LocaleMessages {
 export function buildLocaleBundle(lang: string): LocaleBundle {
   const canonical = canonicalLanguage(lang);
   const messages = loadLocale(canonical);
+  const available = Object.fromEntries(
+    BUNDLED_VIEWER_LOCALES.map((locale) => [locale, loadLocale(locale)]),
+  );
   if (canonical === "en" || Object.keys(messages).length === 0) {
     return {
       lang: "en",
       messages: loadLocale("en"),
       fallback: {},
+      available,
     };
   }
 
@@ -57,5 +64,6 @@ export function buildLocaleBundle(lang: string): LocaleBundle {
     lang: canonical,
     messages,
     fallback: loadLocale("en"),
+    available,
   };
 }
diff --git a/src/viewer/locales/en.json b/src/viewer/locales/en.json
index 0b14fbebd..70c2e010a 100644
--- a/src/viewer/locales/en.json
+++ b/src/viewer/locales/en.json
@@ -25,6 +25,18 @@
     "light": "LIGHT",
     "unlock": "Unlock"
   },
+  "language": {
+    "label": "Language",
+    "english": "English",
+    "chinese": "Chinese"
+  },
+  "common": {
+    "actions": "Actions",
+    "cancel": "Cancel",
+    "delete": "Delete",
+    "updated": "Updated",
+    "type": "Type"
+  },
   "loading": {
     "dashboard": "Loading dashboard...",
     "session_details": "Loading session details..."
@@ -44,6 +56,75 @@
     "failed": "Dashboard failed to load: {message}",
     "failed_help": "Check the browser console for the full error. If you see CSP violations, please open an issue with the agentmemory version (top-right of the viewer) and the violation text.",
     "endpoint_failed_title": "Dashboard data unavailable",
-    "endpoint_failed_body": "Some dashboard sections could not load. Failed endpoints: {endpoints}. Check the agentmemory server logs or refresh after the backend is reachable."
+    "endpoint_failed_body": "Some dashboard sections could not load. Failed endpoints: {endpoints}. Check the agentmemory server logs or refresh after the backend is reachable.",
+    "first_run_eyebrow": "First run → magical moment in 10 seconds",
+    "first_run_title": "Seed sample data + prove semantic recall works",
+    "first_run_body": "agentmemory is running but has not seen any sessions yet. Run the demo command in a second terminal: it seeds 3 realistic coding sessions and proves the hybrid search finds semantically-related memories that keyword search would miss.",
+    "first_run_link": "Or: wire up your real agent →",
+    "cards": {
+      "sessions": "Sessions",
+      "active": "{count} active",
+      "memories": "Memories",
+      "latest_versions": "latest versions",
+      "lessons": "Lessons",
+      "confidence_scored": "confidence-scored",
+      "crystals": "Crystals",
+      "action_digests": "action digests",
+      "graph_nodes": "Graph Nodes",
+      "edges": "{count} edges",
+      "health": "Health",
+      "function_calls": "Function Calls",
+      "functions_tracked": "{count} functions tracked",
+      "circuit_breaker": "Circuit Breaker",
+      "failures": "{count} failures",
+      "token_savings": "Token Savings",
+      "tokens_saved": "~{tokens} tokens · {cost} saved"
+    },
+    "sections": {
+      "system_resources": "System Resources",
+      "heap": "Heap",
+      "rss": "RSS",
+      "external": "External",
+      "cpu": "CPU",
+      "event_loop": "Event Loop",
+      "uptime": "UPTIME: {uptime}",
+      "alerts": "Alerts ({count})",
+      "notes": "Notes ({count})",
+      "recent_sessions": "Recent Sessions",
+      "recent_activity": "Recent Activity"
+    },
+    "table": {
+      "project": "Project",
+      "status": "Status",
+      "obs": "Obs",
+      "started": "Started"
+    },
+    "empty": {
+      "no_sessions": "No sessions yet. Start a coding session with agentmemory hooks enabled.",
+      "no_activity": "No activity recorded yet"
+    }
+  },
+  "memories": {
+    "title": "Memories",
+    "description": "are durable facts, architecture notes, conventions, and lessons saved via the memory_remember MCP tool or the /agentmemory/remember endpoint. They survive across sessions and supersede each other as v1, v2, etc.",
+    "shown": "Shown: {shown} of {total} total.",
+    "search_placeholder": "Search memories...",
+    "all_types": "All types",
+    "searching": "Searching memories...",
+    "no_results_title": "No results for \"{query}\"",
+    "no_results_lead": "Try different keywords or clear the search.",
+    "empty_title": "No memories yet",
+    "empty_lead": "Memories are the distilled facts agentmemory keeps across sessions — things like file paths, architectural decisions, and user preferences. Hooks capture them automatically during coding sessions; you can also save one directly.",
+    "memory_types_link": "Memory types →",
+    "table": {
+      "title": "Title",
+      "type": "Type",
+      "strength": "Strength",
+      "version": "Version",
+      "updated": "Updated",
+      "actions": "Actions"
+    },
+    "delete_title": "Delete Memory",
+    "delete_confirm": "Are you sure you want to delete \"{title}\"? This action cannot be undone."
   }
 }
diff --git a/src/viewer/locales/zh.json b/src/viewer/locales/zh.json
index 7a035a104..fc615afe0 100644
--- a/src/viewer/locales/zh.json
+++ b/src/viewer/locales/zh.json
@@ -25,6 +25,18 @@
     "light": "浅色",
     "unlock": "解锁"
   },
+  "language": {
+    "label": "语言",
+    "english": "English",
+    "chinese": "中文"
+  },
+  "common": {
+    "actions": "操作",
+    "cancel": "取消",
+    "delete": "删除",
+    "updated": "更新时间",
+    "type": "类型"
+  },
   "loading": {
     "dashboard": "正在加载仪表盘...",
     "session_details": "正在加载会话详情..."
@@ -44,6 +56,75 @@
     "failed": "仪表盘加载失败：{message}",
     "failed_help": "请查看浏览器控制台中的完整错误。如果看到 CSP 违规，请附上 agentmemory 版本（查看器右上角）和违规文本提交问题。",
     "endpoint_failed_title": "仪表盘数据不可用",
-    "endpoint_failed_body": "部分仪表盘区块无法加载。失败的端点：{endpoints}。请检查 agentmemory 服务器日志，或在后端可用后刷新。"
+    "endpoint_failed_body": "部分仪表盘区块无法加载。失败的端点：{endpoints}。请检查 agentmemory 服务器日志，或在后端可用后刷新。",
+    "first_run_eyebrow": "首次运行 → 10 秒体验记忆效果",
+    "first_run_title": "生成示例数据并验证语义召回",
+    "first_run_body": "agentmemory 正在运行，但还没有看到任何会话。请在第二个终端运行演示命令：它会生成 3 个真实的编码会话，并证明混合搜索能找到关键词搜索会漏掉的语义相关记忆。",
+    "first_run_link": "或者：接入你的真实代理 →",
+    "cards": {
+      "sessions": "会话",
+      "active": "{count} 个活跃",
+      "memories": "记忆",
+      "latest_versions": "最新版本",
+      "lessons": "经验",
+      "confidence_scored": "按置信度评分",
+      "crystals": "结晶",
+      "action_digests": "行动摘要",
+      "graph_nodes": "图谱节点",
+      "edges": "{count} 条边",
+      "health": "健康状态",
+      "function_calls": "函数调用",
+      "functions_tracked": "跟踪 {count} 个函数",
+      "circuit_breaker": "熔断器",
+      "failures": "{count} 次失败",
+      "token_savings": "Token 节省",
+      "tokens_saved": "约 {tokens} tokens · 节省 {cost}"
+    },
+    "sections": {
+      "system_resources": "系统资源",
+      "heap": "堆内存",
+      "rss": "RSS",
+      "external": "外部内存",
+      "cpu": "CPU",
+      "event_loop": "事件循环",
+      "uptime": "运行时间：{uptime}",
+      "alerts": "告警（{count}）",
+      "notes": "备注（{count}）",
+      "recent_sessions": "最近会话",
+      "recent_activity": "最近活动"
+    },
+    "table": {
+      "project": "项目",
+      "status": "状态",
+      "obs": "观察",
+      "started": "开始时间"
+    },
+    "empty": {
+      "no_sessions": "还没有会话。请启动一个启用了 agentmemory hooks 的编码会话。",
+      "no_activity": "还没有记录活动"
+    }
+  },
+  "memories": {
+    "title": "记忆",
+    "description": "是通过 memory_remember MCP 工具或 /agentmemory/remember 端点保存的持久事实、架构说明、约定和经验。它们会跨会话保留，并以 v1、v2 等版本互相取代。",
+    "shown": "显示：{shown} / {total} 条。",
+    "search_placeholder": "搜索记忆...",
+    "all_types": "全部类型",
+    "searching": "正在搜索记忆...",
+    "no_results_title": "没有找到“{query}”",
+    "no_results_lead": "请尝试其他关键词或清空搜索。",
+    "empty_title": "还没有记忆",
+    "empty_lead": "记忆是 agentmemory 跨会话保留的精炼事实，例如文件路径、架构决策和用户偏好。Hooks 会在编码会话中自动捕获它们；你也可以直接保存一条。",
+    "memory_types_link": "记忆类型 →",
+    "table": {
+      "title": "标题",
+      "type": "类型",
+      "strength": "强度",
+      "version": "版本",
+      "updated": "更新时间",
+      "actions": "操作"
+    },
+    "delete_title": "删除记忆",
+    "delete_confirm": "确定要删除“{title}”吗？此操作无法撤销。"
   }
 }
diff --git a/test/viewer-i18n.test.ts b/test/viewer-i18n.test.ts
index f0ffd0ffe..f4a62ed8f 100644
--- a/test/viewer-i18n.test.ts
+++ b/test/viewer-i18n.test.ts
@@ -1,10 +1,12 @@
 import { afterEach, describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
 import {
   buildLocaleBundle,
   loadLocale,
   resolveViewerLanguage,
 } from "../src/viewer/locales.js";
 import { renderViewerDocument } from "../src/viewer/document.js";
+import { loadViewerSandbox } from "./helpers/viewer-sandbox.js";
 
 describe("viewer i18n language resolution", () => {
   const original = process.env["VIEWER_LANGUAGE"];
@@ -91,6 +93,21 @@ describe("viewer i18n bundle building", () => {
     );
   });
 
+  it("includes all bundled viewer locales for client-side switching", () => {
+    const bundle = buildLocaleBundle("en");
+    const available = (bundle as typeof bundle & {
+      available?: Record<string, Record<string, unknown>>;
+    }).available;
+
+    expect(available).toBeDefined();
+    expect((available?.["en"]?.["nav"] as Record<string, string>)["dashboard"]).toBe(
+      "Dashboard",
+    );
+    expect((available?.["zh"]?.["nav"] as Record<string, string>)["dashboard"]).toBe(
+      "仪表盘",
+    );
+  });
+
   it("falls back to English for invalid bundle language input", () => {
     const bundle = buildLocaleBundle("../zh");
 
@@ -122,6 +139,17 @@ describe("viewer i18n document injection", () => {
     expect(rendered.html).not.toContain("__AGENTMEMORY_LOCALE__");
   });
 
+  it("renders a viewer language picker and browser preference hook", () => {
+    const rendered = renderViewerDocument();
+
+    expect(rendered.found).toBe(true);
+    if (!rendered.found) return;
+    expect(rendered.html).toContain('id="language-select"');
+    expect(rendered.html).toContain("agentmemory-viewer-language");
+    expect(rendered.html).toContain("navigator.languages");
+    expect(rendered.html).toContain('html[lang="zh"]');
+  });
+
   it("escapes script-breaking characters in injected locale JSON", () => {
     process.env["VIEWER_LANGUAGE"] = "en";
 
@@ -135,6 +163,64 @@ describe("viewer i18n document injection", () => {
   });
 });
 
+describe("viewer i18n rendered surfaces", () => {
+  it("routes representative Dashboard and Memories copy through escaped translations", () => {
+    const viewer = readFileSync("src/viewer/index.html", "utf-8");
+
+    [
+      "dashboard.first_run_eyebrow",
+      "dashboard.cards.sessions",
+      "dashboard.sections.recent_sessions",
+      "memories.search_placeholder",
+      "memories.empty_title",
+      "memories.table.title",
+      "memories.delete_title",
+      "common.delete",
+    ].forEach((key) => {
+      expect(viewer).toContain(`t('${key}`);
+    });
+    expect(viewer).not.toContain("First run &rarr; magical moment in 10 seconds");
+    expect(viewer).not.toContain('placeholder="Search memories..."');
+    expect(viewer).not.toContain("<h3>Delete Memory</h3>");
+  });
+
+  it("renders switched Dashboard and Memories copy without a reload", () => {
+    const { sandbox, getElement } = loadViewerSandbox();
+    sandbox.state.dashboard = {
+      loaded: true,
+      health: { status: "healthy", health: {} },
+      sessions: [],
+      memories: [],
+      lessons: [],
+      crystals: [],
+      graphStats: {},
+      recentAudit: [],
+    };
+    sandbox.state.memories = {
+      loaded: true,
+      items: [],
+      search: "",
+      typeFilter: "",
+      total: 0,
+      searching: false,
+      requestId: 0,
+    };
+
+    sandbox.renderDashboard();
+    sandbox.renderMemories();
+    expect(getElement("view-dashboard").innerHTML).toContain("First run");
+    expect(getElement("view-memories").innerHTML).toContain("Search memories");
+
+    expect(typeof sandbox.window.setViewerLanguage).toBe("function");
+    sandbox.window.setViewerLanguage("zh", true);
+
+    expect(getElement("view-dashboard").innerHTML).toContain("首次运行");
+    expect(getElement("view-dashboard").innerHTML).not.toContain("First run");
+    expect(getElement("view-memories").innerHTML).toContain("搜索记忆");
+    expect(getElement("view-memories").innerHTML).not.toContain("Search memories");
+  });
+});
+
 describe("viewer i18n locale parity", () => {
   function leafPaths(value: unknown, prefix = ""): string[] {
     if (!value || typeof value !== "object") return [];

From 29947f8dff4f3332e70224311d872887f86a6cb2 Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Sat, 20 Jun 2026 04:02:27 +0200
Subject: [PATCH 2/5] docs: record issue 288 pr prep verification

---
 .../2026-06-19-issue-288-web-display-issue/todo.md  | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
index b82ad5f9e..578c33963 100644
--- a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
+++ b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
@@ -136,6 +136,8 @@ Rejected:
 - 2026-06-19: Tightened startup language precedence so a non-English `VIEWER_LANGUAGE` default wins over browser language while unset English defaults can still auto-select Chinese browser preferences.
 - 2026-06-20: Added `html[lang="zh"]` CJK system font fallbacks so Chinese mode does not depend on browser translation styling or external fonts.
 - 2026-06-20: Final manual review found no new API/auth/persistence/schema/dependency/architecture boundary changes and no need for OSV because dependency, lockfile, package-manager, container, and vendored surfaces were unchanged.
+- 2026-06-20: Fetched and merged `origin/main` into `issue/288-web-display-issue` because main had advanced by 34 commits; merge required sandbox escalation for Git worktree metadata write and completed without conflicts.
+- 2026-06-20: Full-history `gitleaks detect --source . --redact` found 14 historical leaks across 1034 commits, outside the issue branch. Scoped branch-history and current-worktree Gitleaks checks were clean, so no task-owned leak was found.
 
 ## Verification Evidence
 
@@ -152,7 +154,16 @@ Rejected:
 - `jq empty src/viewer/locales/en.json src/viewer/locales/zh.json`: GREEN.
 - `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
 - `gitleaks protect --staged --redact`: GREEN, no leaks found.
+- Post-merge `corepack pnpm exec vitest run test/viewer-i18n.test.ts test/viewer-security.test.ts test/viewer-layout.test.ts`: GREEN, 3 files / 37 tests passed.
+- Post-merge `corepack pnpm run viewer:test`: GREEN, 4 files / 20 tests passed.
+- Post-merge `corepack pnpm run viewer:typecheck`: GREEN.
+- Post-merge `corepack pnpm run build`: GREEN; existing tsdown/vite warnings only.
+- Post-merge `corepack pnpm test`: GREEN, 211 files / 2927 tests passed.
+- Post-merge `git diff --check`: GREEN.
+- Post-merge `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
+- Post-merge `gitleaks detect --source . --redact --log-opts origin/main..HEAD`: GREEN, no leaks found.
+- Post-merge `gitleaks detect --source . --redact --no-git`: GREEN, no leaks found.
 
 ## Final Review Notes
 
-Sprint Contract acceptance criteria are met locally. Remaining authorized workflow steps are commit, push, PR creation, clean merge after remote checks, and thread archival.
+Sprint Contract acceptance criteria are met on the branch after merging current `origin/main`. Remaining authorized workflow steps are verification-note commit, push, PR creation, clean merge after remote checks, and thread archival.

From 7eaf7ba67770296cd73c69e97bd3892d323ed090 Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Sat, 20 Jun 2026 04:10:17 +0200
Subject: [PATCH 3/5] docs: record issue 288 latest base verification

---
 .../2026-06-19-issue-288-web-display-issue/todo.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
index 578c33963..28d918f07 100644
--- a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
+++ b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
@@ -138,6 +138,7 @@ Rejected:
 - 2026-06-20: Final manual review found no new API/auth/persistence/schema/dependency/architecture boundary changes and no need for OSV because dependency, lockfile, package-manager, container, and vendored surfaces were unchanged.
 - 2026-06-20: Fetched and merged `origin/main` into `issue/288-web-display-issue` because main had advanced by 34 commits; merge required sandbox escalation for Git worktree metadata write and completed without conflicts.
 - 2026-06-20: Full-history `gitleaks detect --source . --redact` found 14 historical leaks across 1034 commits, outside the issue branch. Scoped branch-history and current-worktree Gitleaks checks were clean, so no task-owned leak was found.
+- 2026-06-20: Fetched and merged `origin/main` a second time after main advanced again; merge completed without conflicts. The exact parallel `corepack pnpm test` command then failed twice in unrelated `test/codex-sdk-provider.test.ts` child-process timeout assertions, while the failing file passed in isolation. Recorded the repeated failure and changed verification to full-suite serial file execution to remove worker contention.
 
 ## Verification Evidence
 
@@ -163,7 +164,18 @@ Rejected:
 - Post-merge `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
 - Post-merge `gitleaks detect --source . --redact --log-opts origin/main..HEAD`: GREEN, no leaks found.
 - Post-merge `gitleaks detect --source . --redact --no-git`: GREEN, no leaks found.
+- Second post-merge `corepack pnpm exec vitest run test/viewer-i18n.test.ts test/viewer-security.test.ts test/viewer-layout.test.ts`: GREEN, 3 files / 37 tests passed.
+- Second post-merge `corepack pnpm run viewer:test`: GREEN, 4 files / 20 tests passed.
+- Second post-merge `corepack pnpm run viewer:typecheck`: GREEN.
+- Second post-merge `corepack pnpm run build`: GREEN; existing tsdown/vite warnings only.
+- Second post-merge `corepack pnpm test`: FAILED twice in `test/codex-sdk-provider.test.ts` due hardcoded 2000ms fake Codex child-process timeout under full-suite parallel load.
+- Second post-merge `corepack pnpm exec vitest run test/codex-sdk-provider.test.ts`: GREEN, 1 file / 3 tests passed.
+- Second post-merge `corepack pnpm exec vitest run --exclude test/integration.test.ts --maxWorkers=1`: GREEN, 211 files / 2930 tests passed.
+- Second post-merge `git diff --check`: GREEN.
+- Second post-merge `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
+- Second post-merge `gitleaks detect --source . --redact --log-opts origin/main..HEAD`: GREEN, no leaks found.
+- Second post-merge `gitleaks detect --source . --redact --no-git`: GREEN, no leaks found.
 
 ## Final Review Notes
 
-Sprint Contract acceptance criteria are met on the branch after merging current `origin/main`. Remaining authorized workflow steps are verification-note commit, push, PR creation, clean merge after remote checks, and thread archival.
+Sprint Contract acceptance criteria are met on the branch after merging current `origin/main`. The exact parallel `corepack pnpm test` command is not green on this machine after the latest base update because of an unrelated Codex SDK child-process timeout, but the failing file passes in isolation and the same full suite passes with serial file execution. Remaining authorized workflow steps are verification-note commit, push, PR creation, clean merge after remote checks, and thread archival if remote checks are clean.

From 7d68e5cb5cfbef885db1fc39fbb3e2a8eb12e2fa Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Sat, 20 Jun 2026 04:25:55 +0200
Subject: [PATCH 4/5] test: stabilize codex sdk provider timeout

---
 .../todo.md                                       |  9 ++++++++-
 test/codex-sdk-provider.test.ts                   | 15 +++++++++++++--
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
index 28d918f07..42d941bd6 100644
--- a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
+++ b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
@@ -139,6 +139,7 @@ Rejected:
 - 2026-06-20: Fetched and merged `origin/main` into `issue/288-web-display-issue` because main had advanced by 34 commits; merge required sandbox escalation for Git worktree metadata write and completed without conflicts.
 - 2026-06-20: Full-history `gitleaks detect --source . --redact` found 14 historical leaks across 1034 commits, outside the issue branch. Scoped branch-history and current-worktree Gitleaks checks were clean, so no task-owned leak was found.
 - 2026-06-20: Fetched and merged `origin/main` a second time after main advanced again; merge completed without conflicts. The exact parallel `corepack pnpm test` command then failed twice in unrelated `test/codex-sdk-provider.test.ts` child-process timeout assertions, while the failing file passed in isolation. Recorded the repeated failure and changed verification to full-suite serial file execution to remove worker contention.
+- 2026-06-20: User required a fully green exact suite. Stabilized `test/codex-sdk-provider.test.ts` by raising the fake Codex child timeout used by behavior tests from 2s to 10s; this does not change production timeout behavior and makes the exact parallel full suite green.
 
 ## Verification Evidence
 
@@ -175,7 +176,13 @@ Rejected:
 - Second post-merge `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
 - Second post-merge `gitleaks detect --source . --redact --log-opts origin/main..HEAD`: GREEN, no leaks found.
 - Second post-merge `gitleaks detect --source . --redact --no-git`: GREEN, no leaks found.
+- After Codex SDK test timeout stabilization, `corepack pnpm exec vitest run test/codex-sdk-provider.test.ts`: GREEN, 1 file / 3 tests passed.
+- After Codex SDK test timeout stabilization, exact `corepack pnpm test`: GREEN, 211 files / 2930 tests passed.
+- After Codex SDK test timeout stabilization, `git diff --check`: GREEN.
+- After Codex SDK test timeout stabilization, `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
+- After Codex SDK test timeout stabilization, `gitleaks detect --source . --redact --log-opts origin/main..HEAD`: GREEN, no leaks found.
+- After Codex SDK test timeout stabilization, `gitleaks detect --source . --redact --no-git`: GREEN, no leaks found.
 
 ## Final Review Notes
 
-Sprint Contract acceptance criteria are met on the branch after merging current `origin/main`. The exact parallel `corepack pnpm test` command is not green on this machine after the latest base update because of an unrelated Codex SDK child-process timeout, but the failing file passes in isolation and the same full suite passes with serial file execution. Remaining authorized workflow steps are verification-note commit, push, PR creation, clean merge after remote checks, and thread archival if remote checks are clean.
+Sprint Contract acceptance criteria are met on the branch after merging current `origin/main`. The exact parallel `corepack pnpm test` command is now green after a test-only Codex SDK timeout stabilization. Remaining authorized workflow steps are verification-note commit, push, PR creation, clean merge after remote checks, and thread archival if remote checks are clean.
diff --git a/test/codex-sdk-provider.test.ts b/test/codex-sdk-provider.test.ts
index c8102c47f..38c013302 100644
--- a/test/codex-sdk-provider.test.ts
+++ b/test/codex-sdk-provider.test.ts
@@ -7,6 +7,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { CodexSDKProvider } from "../src/providers/codex-sdk.js";
 
 let tempDirs: string[] = [];
+const FAKE_CODEX_TIMEOUT_MS = 10_000;
 
 function makeFakeCodex(body: string): string {
   const dir = mkdtempSync(join(tmpdir(), "agentmemory-codex-"));
@@ -55,7 +56,12 @@ process.stdin.on("end", () => {
 `);
     process.env.OPENAI_API_KEY = "sk-test-secret";
 
-    const provider = new CodexSDKProvider("codex-default", 128, command, 2_000);
+    const provider = new CodexSDKProvider(
+      "codex-default",
+      128,
+      command,
+      FAKE_CODEX_TIMEOUT_MS,
+    );
 
     await expect(provider.compress("system text", "user text")).resolves.toBe("ok");
   });
@@ -80,7 +86,12 @@ process.stdin.on("end", () => {
   process.exit(4);
 });
 `);
-    const provider = new CodexSDKProvider("codex-default", 128, command, 2_000);
+    const provider = new CodexSDKProvider(
+      "codex-default",
+      128,
+      command,
+      FAKE_CODEX_TIMEOUT_MS,
+    );
 
     await expect(provider.compress("system", "user")).rejects.toThrow(
       /Codex CLI exited with code 4: boom/,

From 39044f9c20f08f17751d2aae3265f5aea9dac554 Mon Sep 17 00:00:00 2001
From: Willi Budzinski <w.budzinski@telekom.de>
Date: Sat, 20 Jun 2026 04:28:09 +0200
Subject: [PATCH 5/5] docs: record issue 288 final verification

---
 .../todos/2026-06-19-issue-288-web-display-issue/todo.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
index 42d941bd6..b94962e3e 100644
--- a/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
+++ b/docs/todos/2026-06-19-issue-288-web-display-issue/todo.md
@@ -140,6 +140,7 @@ Rejected:
 - 2026-06-20: Full-history `gitleaks detect --source . --redact` found 14 historical leaks across 1034 commits, outside the issue branch. Scoped branch-history and current-worktree Gitleaks checks were clean, so no task-owned leak was found.
 - 2026-06-20: Fetched and merged `origin/main` a second time after main advanced again; merge completed without conflicts. The exact parallel `corepack pnpm test` command then failed twice in unrelated `test/codex-sdk-provider.test.ts` child-process timeout assertions, while the failing file passed in isolation. Recorded the repeated failure and changed verification to full-suite serial file execution to remove worker contention.
 - 2026-06-20: User required a fully green exact suite. Stabilized `test/codex-sdk-provider.test.ts` by raising the fake Codex child timeout used by behavior tests from 2s to 10s; this does not change production timeout behavior and makes the exact parallel full suite green.
+- 2026-06-20: Fetched and merged `origin/main` a third time after main advanced by another 30 commits; merge completed without conflicts. Re-ran build, exact full suite, Semgrep, branch/current Gitleaks, and diff check on the latest base.
 
 ## Verification Evidence
 
@@ -182,7 +183,13 @@ Rejected:
 - After Codex SDK test timeout stabilization, `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
 - After Codex SDK test timeout stabilization, `gitleaks detect --source . --redact --log-opts origin/main..HEAD`: GREEN, no leaks found.
 - After Codex SDK test timeout stabilization, `gitleaks detect --source . --redact --no-git`: GREEN, no leaks found.
+- Latest-base `corepack pnpm run build`: GREEN; existing tsdown/vite warnings only.
+- Latest-base exact `corepack pnpm test`: GREEN, 218 files / 2997 tests passed.
+- Latest-base `git diff --check`: GREEN.
+- Latest-base `semgrep scan --config p/default --error --metrics=off .`: GREEN, 0 findings.
+- Latest-base `gitleaks detect --source . --redact --log-opts origin/main..HEAD`: GREEN, no leaks found.
+- Latest-base `gitleaks detect --source . --redact --no-git`: GREEN, no leaks found.
 
 ## Final Review Notes
 
-Sprint Contract acceptance criteria are met on the branch after merging current `origin/main`. The exact parallel `corepack pnpm test` command is now green after a test-only Codex SDK timeout stabilization. Remaining authorized workflow steps are verification-note commit, push, PR creation, clean merge after remote checks, and thread archival if remote checks are clean.
+Sprint Contract acceptance criteria are met on the branch after merging current `origin/main`. The exact parallel `corepack pnpm test` command is green after a test-only Codex SDK timeout stabilization. Remaining authorized workflow steps are verification-note commit, push, PR creation, clean merge after remote checks, and thread archival if remote checks are clean.