docs: translate German docs + code comments to English

The project is open source; English is the lingua franca for OSS.
Germany-only content that belongs in German stays (the `de` i18n
dictionary + DE tagline list).

- AGENTS.md, CONTEXT.md, DECISIONS.md, ROADMAP.md, CONTRIBUTING.md all
  rewritten in English, content unchanged
- CHANGELOG.md updated to reflect the merged-SW architecture (no more
  separate coi-serviceworker) and TruffleHog swap
- Source comments translated in: project.ts, opfs-cache.ts,
  mediapipe-llm.ts, model-catalog.ts, prompt-template.ts, taglines.ts
- OPFS error messages (thrown from opfs-cache.ts) now English; will be
  i18n-keyed in a later pass

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: lx-0

AGENTS.md

@@ -1,84 +1,86 @@
 # Agents Guide
 
-Dieses Repo ist ein **Browser-LLM-Chat-Scaffold** (Yesterday). Du bist hier richtig gelandet — lies diesen File, dann nach Bedarf weiter.
+This repo is a **browser-local LLM chat scaffold** maintained by Yesterday. You've landed in the right place — read this file first, then branch out as needed.
 
-## Reading Order
+## Reading order
 
-1. **AGENTS.md** (hier) — Regeln, Tasks, Gotchas
-2. **CONTEXT.md** — Architektur-Big-Picture, Datenfluss, kritische Patterns
-3. **DECISIONS.md** — Warum die wichtigen Entscheidungen so fielen (DEC-001 … DEC-009)
-4. **ROADMAP.md** — Was kommt, mit Acceptance-Criteria
-5. **CONTRIBUTING.md** — Dev-Workflow + PR-Regeln
-6. Source-Code: `src/lib/` (Domain-Logik) → `src/hooks/` (Adapter) → `src/components/` (UI)
+1. **AGENTS.md** (here) — rules, tasks, gotchas
+2. **CONTEXT.md** — architecture big picture, data flow, critical patterns
+3. **DECISIONS.md** — why the important decisions went the way they did (DEC-001 … DEC-009)
+4. **ROADMAP.md** — what's coming, with acceptance criteria
+5. **CONTRIBUTING.md** — dev workflow + PR rules
+6. Source: `src/lib/` (domain logic) → `src/hooks/` (adapters) → `src/components/` (UI)
 
-## Build & Test
+## Build & test
 
 ```bash
-pnpm install           # einmalig
-pnpm dev               # Dev-Server, COOP/COEP-Headers gesetzt
+pnpm install           # once
+pnpm dev               # dev server, COOP/COEP headers set
 pnpm lint              # Biome
 pnpm typecheck         # tsc -b --noEmit
-pnpm build             # Production + PWA-SW
+pnpm build             # production + PWA SW
 ```
 
-Vor jedem PR: `pnpm lint && pnpm typecheck && pnpm build` — alle drei gruen.
+Before every PR: `pnpm lint && pnpm typecheck && pnpm build` — all three green.
 
-## Regeln
+## Rules
 
-- **Verifikation vor Claim**: nach jeder relevanten Aenderung `pnpm typecheck` UND `pnpm build`, nicht nur typecheck.
-- **Keine Modelle committen**: OPFS-Cache bleibt im Browser, nie nach Disk exportieren. `public/wasm/` ist `.gitignore`d.
-- **Keine destruktiven Datei-Operationen** — siehe globale CLAUDE.md.
-- **Biome fuer Formatting + Lint** — nicht ESLint/Prettier dazumixen.
-- **Async-Generator Bridge in `mediapipe-llm.ts`** nicht anfassen ohne Verstaendnis — MediaPipe-Callback und AbortSignal-Handling sind zusammen fragil.
-- **Stream tee() im OPFS-Cache** nicht umbauen — beide Branches muessen parallel konsumiert werden, sonst backpressure-Deadlock.
-- **External-Store-Runtime, nicht LocalRuntime** — wir halten Messages selbst in Dexie + Zustand.
+- **Verify before claiming**: after any relevant change run `pnpm typecheck` AND `pnpm build`, not just typecheck.
+- **Never commit models**: the OPFS cache stays in the browser, never export to disk. `public/wasm/` is gitignored.
+- **No destructive file operations** — see the global CLAUDE.md.
+- **Biome for formatting + lint** — don't mix in ESLint/Prettier.
+- **Don't touch the async-generator bridge in `mediapipe-llm.ts`** without understanding it — MediaPipe's callback API and the AbortSignal handling are fragile together.
+- **Don't restructure the stream `tee()` in the OPFS cache** — both branches must be consumed in parallel or backpressure deadlocks.
+- **External-store runtime, not LocalRuntime** — we hold messages ourselves in Dexie + Zustand.
 
-## Typische Tasks
+## Typical tasks
 
-| Task | Pfad |
+| Task | Where |
 |---|---|
-| Neues Modell hinzufuegen | `src/lib/model-catalog.ts` erweitern |
-| UI-Komponente hinzufuegen | `src/components/` + assistant-ui Primitives |
-| Persistenz-Schema erweitern | `src/lib/db.ts` Version bumpen (Dexie migration) |
-| Branding anpassen | `src/lib/project.ts`, `public/icons/icon.svg`, `index.html` |
-| Neue Sprache hinzufuegen | neue `src/lib/i18n/<locale>.ts` + `LOCALES` + `LOCALE_LABELS` + `DICTS` in `index.ts` + `detectLocale` |
-| Neue Tagline dazu | `src/lib/taglines.ts` pro Sprache |
-| Default-Sampling aendern | `src/lib/mediapipe-llm.ts#DEFAULT_OPTIONS` |
-| Deploy-Workflow | `.github/workflows/deploy.yml`; Base-Path via `PROJECT.basePath` |
-| Prompt-Format fuer anderes Modell | `src/lib/prompt-template.ts` |
-| PWA-Caching anpassen | `vite.config.ts#VitePWA.workbox.runtimeCaching` |
-
-## Nicht tun
-
-- Kein HTTP-Backend-Layer — der Point ist Serverless-Browser.
-- Keine OpenAI-SDK-Stubs — wir nutzen ausschliesslich `@mediapipe/tasks-genai`.
-- Keine `alert()` / `confirm()` — UI via React-Components.
-- Keine Model-Files in `public/` oder Git-LFS — nur WASM (via `copy-wasm`).
-- Keine harten `localhost`-URLs — Modelle kommen aus HF Hub (direkt) oder zukuenftig R2-Mirror (via Env).
+| Add a new model | extend `src/lib/model-catalog.ts` |
+| Add a UI component | `src/components/` + assistant-ui primitives |
+| Extend the persistence schema | bump `src/lib/db.ts` version (Dexie migration) |
+| Change branding | `src/lib/project.ts`, `public/icons/icon.svg`, `index.html` |
+| Add a language | new `src/lib/i18n/<locale>.ts` + `LOCALES` + `LOCALE_LABELS` + `DICTS` in `index.ts` + `detectLocale` |
+| Add a tagline | `src/lib/taglines.ts` per language |
+| Change default sampling | `src/lib/mediapipe-llm.ts#DEFAULT_OPTIONS` |
+| Deploy pipeline | `.github/workflows/deploy.yml`; base path via `PROJECT.basePath` |
+| Prompt format for a different model | `src/lib/prompt-template.ts` |
+| Adjust PWA caching | `src/sw.ts` (routes, plugins, COI header injection) |
+
+## Don't do
+
+- No HTTP backend layer — the point is serverless-in-browser.
+- No OpenAI-SDK stubs — we use `@mediapipe/tasks-genai` exclusively.
+- No `alert()` / `confirm()` — UI through React components only.
+- No model files in `public/` or Git-LFS — only WASM (via `copy-wasm`).
+- No hardcoded `localhost` URLs — models come from HF Hub directly or (future) an R2 mirror.
 
 ## Debugging
 
-- Chrome DevTools → Application → Storage → OPFS: Model-Files sichtbar
-- Application → IndexedDB → `browser-llm-demo`: Conversations + Messages
-- Application → Service Workers: SW Status (nur in Production-Build aktiv)
-- Network → Filter `wasm`: sieht WASM-CacheFirst-Hits
-- `navigator.storage.estimate()` in Console: Quota-Status
+- Chrome DevTools → Application → Storage → OPFS: model files visible
+- Application → IndexedDB → `browser-llm-demo`: conversations + messages
+- Application → Service Workers: SW status (only active in production builds)
+- Network → filter `wasm`: WASM CacheFirst hits
+- `navigator.storage.estimate()` in console: quota status
+- `window.crossOriginIsolated` in console: must be `true` for threaded WASM
 
-## Upstream-Referenz
+## Upstream reference
 
-Port-Quellen (Apache-2.0):
+Port sources (Apache-2.0):
 
 - `https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/llm_inference/llm_chat_ts`
-- `opfs_cache.ts` und `llm_service.ts` sind die Kern-Referenzen fuer OPFS- und MediaPipe-Interop.
+- `opfs_cache.ts` and `llm_service.ts` are the core references for OPFS + MediaPipe interop.
 
 ## Gotchas
 
-- **iOS Safari < 18.4**: keine WebGPU → CPU-Fallback, E2B zaeh, E4B nicht sinnvoll
-- **OPFS-Quota unter iOS**: ~1 GB default, via `persist()` erweiterbar
-- **PWA Install-Prompt**: Android-Chrome automatisch, iOS manuell "Zum Home-Bildschirm"
-- **SharedArrayBuffer**: braucht COOP/COEP — bei GitHub Pages via `coi-serviceworker` (siehe DEC-008) automatisch
-- **HF-Rate-Limits**: unwahrscheinlich bei Direct-Downloads, aber bei vielen Users evtl. Mirror noetig
-- **Shader-Compile-Latenz**: 10–25 s beim ersten Load pro Session, danach Browser-WebGPU-Cache greift
-- **Firefox ~30–50 % langsamer** als Chrome (wgpu vs Dawn + OPFS SQLite). Feature, nicht Bug.
-- **Stop-Token-Leak**: Gemma emittet manchmal `<end_of_turn>` literal. Regex in `mediapipe-llm.ts#GEMMA_STOP_PATTERN` + `cancelProcessing()` fangen das
-- **Doppel-BOS vermeiden**: MediaPipes Tokenizer prepended BOS automatisch — nicht manuell in `renderGemmaPrompt` einfuegen
+- **iOS Safari < 18.4**: no WebGPU → CPU fallback, E2B is slow, E4B not viable
+- **OPFS quota on iOS**: ~1 GB default, extendable via `persist()`
+- **PWA install prompt**: automatic on Android Chrome, manual "Add to Home Screen" on iOS
+- **SharedArrayBuffer**: needs COOP/COEP — on GitHub Pages we inject them via `src/sw.ts` (see DEC-008)
+- **HF rate limits**: unlikely for direct downloads, but may need a mirror at scale
+- **Shader compile latency**: 10–25 s on first session load, then the browser WebGPU cache kicks in
+- **Firefox ~30–50 % slower** than Chrome (wgpu vs Dawn + SQLite-backed OPFS). Feature, not bug.
+- **Stop-token leak**: Gemma sometimes emits `<end_of_turn>` as a literal string. The regex in `mediapipe-llm.ts#GEMMA_STOP_PATTERN` + `cancelProcessing()` catch it.
+- **Avoid double BOS**: MediaPipe's tokenizer prepends BOS automatically — don't add one manually in `renderGemmaPrompt`.
+- **Two SWs collide**: never register multiple service workers for the same scope. All SW logic lives in `src/sw.ts`.

CHANGELOG.md

@@ -22,13 +22,13 @@ Initial public release. Ships as a scaffold for building browser-local LLM chat
 - i18n: German + English dictionaries, `navigator.language` auto-detect, `useT()` hook (~40 LOC, no framework)
 - Rotating privacy taglines on the landing page ("An LLM that doesn't phone home", etc.)
 - Key-facts footer: `0` server calls · `100 %` browser-local · `Apache 2.0` + GitHub link
-- PWA: manifest, service worker (CacheFirst for WASM), install prompt, offline indicator
+- PWA: manifest, installable, offline indicator, install prompt
+- Custom service worker (`src/sw.ts`) — Workbox precache + runtime cache for WASM + client-side COOP/COEP header injection so SharedArrayBuffer works on GitHub Pages (see DEC-008)
 - Atomic Design component structure: atoms · molecules · organisms · templates · pages
 - Dark-theme only (see DEC-005)
-- AsteriskAnimation atom for load/generation waiting states
-- Governance docs: DECISIONS.md, ROADMAP.md, CONTRIBUTING.md, AGENTS.md, CONTEXT.md, SECURITY.md
-- GitHub Actions workflows: CI (lint, typecheck, build, gitleaks) + Pages deploy
-- `coi-serviceworker` bundled — enables threaded WASM on hosts without custom headers (GitHub Pages)
+- `AsteriskAnimation` atom for load / generation waiting states
+- Governance docs: DECISIONS.md, ROADMAP.md, CONTRIBUTING.md, AGENTS.md, CONTEXT.md, SECURITY.md, RELEASING.md
+- GitHub Actions workflows: CI (lint, typecheck, build, TruffleHog secret scan) + Pages deploy
 
 ### Known Limitations
 

CONTEXT.md

@@ -1,6 +1,6 @@
-# Architektur
+# Architecture
 
-## Big Picture
+## Big picture
 
 ```
                   HF Hub (public)             OPFS (Browser)
@@ -34,47 +34,54 @@
                                            Sidebar, ModelPicker)
 ```
 
-## Wichtige Dateien
+## Key files
 
-| File | Rolle |
+| File | Role |
 |---|---|
-| `src/lib/model-catalog.ts` | Swappable Modell-Liste (Scaffold-Point) |
-| `src/lib/opfs-cache.ts` | Download + OPFS-Cache mit Progress + Abort |
-| `src/lib/mediapipe-llm.ts` | MediaPipe-Wrapper, Callback→Async-Generator Bridge |
-| `src/lib/prompt-template.ts` | Gemma-Turn-Formatting |
-| `src/lib/llm-store.ts` | LLM-Load-State (Zustand) |
-| `src/lib/chat-store.ts` | Conversation-State + Dexie-Persistenz (Zustand + Persist) |
-| `src/lib/db.ts` | Dexie-Schema (conversations, messages) |
-| `src/lib/capabilities.ts` | Browser-Fähigkeiten pruefen + Modell-Eignung |
-| `src/hooks/useLlmRuntime.ts` | `useExternalStoreRuntime` Adapter |
-| `src/components/ChatShell.tsx` | Top-Level-Layout, Model-Picker-Flow |
-| `src/components/ChatThread.tsx` | Thread + Composer (assistant-ui primitives) |
-| `scripts/copy-wasm.mjs` | `predev`/`prebuild` — MediaPipe-WASM aus node_modules nach public/wasm |
+| `src/lib/project.ts` | Project identity (name, displayName, GitHub URL, base path) |
+| `src/lib/model-catalog.ts` | Swappable model list (scaffold point) |
+| `src/lib/opfs-cache.ts` | HF download + OPFS cache with progress + abort |
+| `src/lib/mediapipe-llm.ts` | MediaPipe wrapper, callback → async-generator bridge |
+| `src/lib/prompt-template.ts` | Gemma turn formatting |
+| `src/lib/llm-store.ts` | LLM load state (Zustand) |
+| `src/lib/chat-store.ts` | Conversation state + Dexie persistence (Zustand + persist) |
+| `src/lib/db.ts` | Dexie schema (conversations, messages) |
+| `src/lib/capabilities.ts` | Browser capability checks + model eligibility |
+| `src/lib/settings-store.ts` | User-editable sampling, context, locale, system prompt |
+| `src/lib/i18n/{de,en,types,index}.ts` | Lean i18n (no framework) |
+| `src/lib/taglines.ts` | Rotating privacy taglines (per locale) |
+| `src/lib/asset-path.ts` | `import.meta.env.BASE_URL` prefixing for runtime asset refs |
+| `src/hooks/useLlmRuntime.ts` | `useExternalStoreRuntime` adapter |
+| `src/components/pages/ChatShell.tsx` | Top-level layout, model-picker flow |
+| `src/components/organisms/ChatThread.tsx` | Thread + composer (assistant-ui primitives) |
+| `src/sw.ts` | Service Worker — Workbox precache + COI header injection |
+| `scripts/copy-wasm.mjs` | `predev`/`prebuild` — copies MediaPipe WASM from node_modules to public/wasm |
 
-## Datenfluss
+## Data flow
 
-1. **Modell-Download**: `ChatShell` → `llm-store.load()` → `mediapipe-llm.load()` → `opfs-cache.loadModelWithCache()` → Stream tee'd, eine Haelfte an MediaPipe, andere in OPFS
-2. **Inferenz**: User-Message via `useLlmRuntime.onNew()` → `chat-store.sendUserMessage()` → Dexie + Stream-Update → `llm-store.llm.generate()` yields chunks → store-update → React re-render
-3. **Persistenz**: Messages nach Stream-Ende nach Dexie; Conversation-Liste via `useLiveQuery` reaktiv in Sidebar
+1. **Model download**: `ChatShell` → `llm-store.load()` → `mediapipe-llm.load()` → `opfs-cache.loadModelWithCache()` → stream `tee()`'d, one half into MediaPipe, the other into OPFS
+2. **Inference**: user message via `useLlmRuntime.onNew()` → `chat-store.sendUserMessage()` → Dexie write + streaming state update → `llm-store.llm.generate()` yields chunks → store update → React re-render
+3. **Persistence**: messages flushed to Dexie after stream end; conversation list reactive via `useLiveQuery` in the sidebar
 
-## Kritische Patterns
+## Critical patterns
 
-- **Callback→AsyncGenerator**: `mediapipe-llm.ts#generate()` — MediaPipe hat callback API, assistant-ui will AsyncGenerator
-- **Stream-tee**: `opfs-cache.ts#loadModelWithCache()` — ein Fetch, zwei Verbraucher (MediaPipe + Cache-Writer)
-- **Sidecar _size-File**: Cache-Validierung ohne vollstaendiges Re-Hash
-- **External-Store-Runtime**: statt `useLocalRuntime` — wir halten Messages selbst, assistant-ui rendert nur
+- **Callback → AsyncGenerator** in `mediapipe-llm.ts#generate()` — MediaPipe exposes a callback API, assistant-ui expects an AsyncGenerator
+- **Stream tee()** in `opfs-cache.ts#loadModelWithCache()` — one fetch, two consumers (MediaPipe + cache writer)
+- **Sidecar `_size` file** — cache validation without re-hashing multi-GB blobs
+- **External-store runtime** instead of `useLocalRuntime` — we own the message array; assistant-ui only renders
+- **Atomic Design layering** — atoms never import from molecules/organisms; organisms may import stores
 
 ## Mobile + PWA
 
-- `viewport-fit=cover` + `env(safe-area-inset-*)` fuer Notches
-- `interactive-widget=resizes-content` fuer iOS-Keyboard
-- Service Worker: App-Shell precached, WASM CacheFirst, HF NetworkOnly
-- Model-Files leben in OPFS, NICHT im SW-Cache
+- `viewport-fit=cover` + `env(safe-area-inset-*)` for notches
+- `interactive-widget=resizes-content` for iOS keyboard
+- Service Worker: app-shell precached, WASM CacheFirst, HF bypasses the SW entirely
+- Model files live in OPFS, NOT in the SW cache
 
-## COOP/COEP
+## COOP / COEP
 
-MediaPipe nutzt SharedArrayBuffer → `Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp` in `vite.config.ts`. HF-Hub-Downloads gehen via `fetch()` (keine Embed-Restriction).
+MediaPipe uses SharedArrayBuffer → needs `Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp` + `Cross-Origin-Resource-Policy: cross-origin`. Dev server sets them via `vite.config.ts`. On GitHub Pages (which can't set custom headers), `src/sw.ts` injects them client-side via a Workbox plugin (`fetchDidSucceed` + `cachedResponseWillBeUsed`). HF Hub downloads go straight through `fetch()` and bypass the SW.
 
-## Offene Entscheidungen / Roadmap
+## Open questions / roadmap
 
-Siehe Plan-File und README. AG-UI-Protocol-Layer, MCP-Tools, RAG, i18n in der Roadmap.
+See `ROADMAP.md` and `README.md`. AG-UI protocol layer, MCP tools, RAG, voice I/O, light theme, Playwright tests are all tracked there.