.test.ts` for fast iteration on a single suite.
+When a test spawns `git` or other subprocesses, ensure the spawn sets
+`stdin: "ignore"` and `GIT_TERMINAL_PROMPT=0` so a hung credential prompt
+cannot exhaust the test timeout. Also give it an explicit timeout
+(`test(name, fn, 30_000)`) — the 5s Bun default is too tight for CI runners.
+
+# Wiki
+
+Public docs site lives in `wiki/` (Astro Starlight) and is deployed to
+https://kanna-wiki.lowbit.link on every push to `main` that touches `wiki/**`.
+
+Regenerate screenshots:
+
+```bash
+bash wiki/scripts/capture-all.sh
+```
+
+This spawns a seeded demo Kanna under a tmpdir `KANNA_HOME`, captures all
+~32 PNGs via Playwright, and writes them to `wiki/public/screenshots/`.
+Commit the PNGs.
+
+Regenerate env-var reference table:
+
+```bash
+cd wiki && bun run scripts/extract-env-vars.ts
+```
+
+Wiki is isolated from the main repo build — its own `package.json`, own
+`node_modules`. `bun run lint` and `bun test` at the repo root do NOT touch
+`wiki/`.
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 000000000..6c48a9ab5
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,290 @@
+---
+name: Kanna
+description: A calm, editorial web UI for the Claude Code & Codex CLIs.
+colors:
+ paper: "oklch(99.5% 0.003 13)"
+ inkstone: "oklch(20% 0.01 13)"
+ espresso-ink: "oklch(16% 0.01 13)"
+ pale-foreground: "oklch(98% 0.003 13)"
+ warm-card-light: "oklch(99.5% 0.003 13)"
+ warm-card-dark: "oklch(23% 0.01 13)"
+ surface-secondary-light: "oklch(96% 0.005 13)"
+ surface-secondary-dark: "oklch(26% 0.01 13)"
+ margin-gray-light: "oklch(55% 0.013 13)"
+ margin-gray-dark: "oklch(70% 0.012 13)"
+ soft-edge-light: "oklch(91% 0.008 13)"
+ soft-edge-dark: "oklch(29% 0.008 13)"
+ muted-icon-light: "oklch(82% 0.008 13)"
+ muted-icon-dark: "oklch(55% 0.01 13)"
+ kanna-coral: "oklch(71.2% 0.194 13.428)"
+ destructive-text: "oklch(56% 0.18 13)"
+ verified-sage: "oklch(68% 0.15 155)"
+ editor-amber: "oklch(76% 0.14 78)"
+ reference-blue: "oklch(66% 0.13 235)"
+typography:
+ display:
+ fontFamily: "Bricolage Grotesque Variable, Bricolage Grotesque, sans-serif"
+ fontSize: "clamp(1.75rem, 3.5vw, 2.5rem)"
+ fontWeight: 800
+ lineHeight: 1.05
+ letterSpacing: "-0.02em"
+ headline:
+ fontFamily: "Body, ui-sans-serif, system-ui, -apple-system, sans-serif"
+ fontSize: "1.125rem"
+ fontWeight: 500
+ lineHeight: 1.3
+ letterSpacing: "-0.01em"
+ title:
+ fontFamily: "Body, ui-sans-serif, system-ui, -apple-system, sans-serif"
+ fontSize: "0.9375rem"
+ fontWeight: 600
+ lineHeight: 1.35
+ letterSpacing: "normal"
+ body:
+ fontFamily: "Body, ui-sans-serif, system-ui, -apple-system, sans-serif"
+ fontSize: "0.875rem"
+ fontWeight: 400
+ lineHeight: 1.55
+ letterSpacing: "normal"
+ label:
+ fontFamily: "Body, ui-sans-serif, system-ui, -apple-system, sans-serif"
+ fontSize: "0.75rem"
+ fontWeight: 500
+ lineHeight: 1.3
+ letterSpacing: "0.005em"
+ mono:
+ fontFamily: "Roboto Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
+ fontSize: "0.8125rem"
+ fontWeight: 400
+ lineHeight: 1.55
+ fontFeature: "tnum"
+rounded:
+ sm: "calc(0.5rem - 4px)"
+ md: "calc(0.5rem - 2px)"
+ lg: "0.5rem"
+spacing:
+ xs: "4px"
+ sm: "8px"
+ md: "12px"
+ lg: "16px"
+ xl: "24px"
+ "2xl": "32px"
+components:
+ button-primary:
+ backgroundColor: "{colors.espresso-ink}"
+ textColor: "{colors.pale-foreground}"
+ rounded: "{rounded.md}"
+ padding: "8px 14px"
+ button-secondary:
+ backgroundColor: "{colors.surface-secondary-light}"
+ textColor: "{colors.espresso-ink}"
+ rounded: "{rounded.md}"
+ padding: "8px 14px"
+ button-ghost:
+ backgroundColor: "transparent"
+ textColor: "{colors.espresso-ink}"
+ rounded: "{rounded.md}"
+ padding: "8px 14px"
+ button-destructive:
+ backgroundColor: "{colors.kanna-coral}"
+ textColor: "{colors.pale-foreground}"
+ rounded: "{rounded.md}"
+ padding: "8px 14px"
+ card-surface:
+ backgroundColor: "{colors.warm-card-light}"
+ textColor: "{colors.espresso-ink}"
+ rounded: "{rounded.lg}"
+ padding: "16px"
+ input-field:
+ backgroundColor: "{colors.paper}"
+ textColor: "{colors.espresso-ink}"
+ rounded: "{rounded.md}"
+ padding: "8px 12px"
+ dialog-surface:
+ backgroundColor: "{colors.warm-card-light}"
+ textColor: "{colors.espresso-ink}"
+ rounded: "{rounded.lg}"
+ padding: "24px"
+---
+
+# Design System: Kanna
+
+## 1. Overview
+
+**Creative North Star: "The Editorial Workspace"**
+
+Kanna reads like a well-edited document, not a dashboard. The system stays warm-tinted and quiet so that long agent sessions remain legible at 11pm on a 27-inch monitor without wearing the user down. Density is paid for in rhythm, not in chrome: hierarchy emerges from typographic weight and generous spacing, never from gradients, glow, or decorative borders. The palette tints every neutral toward a warm rose hue (~13°) so even greys feel like paper, not aluminium. The system explicitly rejects the four anti-references in PRODUCT.md: generic AI SaaS gradient chrome, marketing-heavy SaaS-cream landing pages, neon terminal cyberpunk, and cluttered dashboard density.
+
+Color is restrained by default. One brand accent (Kanna Coral) carries identity and destructive intent both, used on under 10% of any screen. Three semantic accents (sage, amber, blue) carry success/warning/info — never decorative. State is always paired with a label or icon shape; color alone never communicates.
+
+**Key Characteristics:**
+
+- Warm-tinted neutrals (chroma 0.003–0.013, hue ~13°) across both themes.
+- One brand accent, used rarely and on purpose.
+- Editorial type pairing: Body (a custom warm sans) for prose; Bricolage Grotesque for the logo only; Roboto Mono for code, IDs, and tabular data.
+- Flat by default. Depth comes from contrast and spacing, not shadows.
+- Tabular numerics on every duration, count, age, or pid. No reflow under live tickers.
+
+## 2. Colors: The Warm Editorial Palette
+
+The palette is one rose-tinted neutral family with a single saturated coral accent and three semantic markers. Every color is OKLCH; the doctrine is "tint everything, even white."
+
+### Primary
+
+- **Kanna Coral** (`oklch(71.2% 0.194 13.428)`): the brand mark and the destructive surface. Used as logo color, as the primary CTA in landing/auth contexts, and as `--destructive` for stop/delete affordances. Never used as a background fill or a decorative gradient stop.
+
+- **Destructive Text** (`oklch(56% 0.18 13)` light / `var(--destructive)` dark): AA-compliant coral variant for text and icon-only destructive contexts (e.g. "Confirm stop?", "Force kill" labels). The bright Kanna Coral (`oklch(71.2% 0.194 13.428)`) achieves only 2.81:1 on Warm Paper — below WCAG AA. This darker variant hits 5.04:1 on Warm Paper in light mode while preserving the editorial-light-text-button feel. In dark mode the token aliases back to `--destructive` (6.35:1 on Inkstone), so the bright coral is used in both contexts where it passes. Filled destructive buttons continue to use the bright coral as background with Pale Foreground text — this token is only for text or icon-only foreground use.
+
+### Neutral (warm rose family, hue ~13°)
+
+- **Warm Paper** (`oklch(99.5% 0.003 13)`): light-mode background. Tinted just enough to feel paper-like rather than clinical.
+- **Inkstone** (`oklch(20% 0.01 13)`): dark-mode background. Warm enough to read as ink rather than asphalt.
+- **Espresso Ink** (`oklch(16% 0.01 13)`): light-mode foreground; primary fill in dark-mode buttons.
+- **Pale Foreground** (`oklch(98% 0.003 13)`): dark-mode foreground; readable on Inkstone.
+- **Margin Gray** (`oklch(55% 0.013 13)` light / `oklch(70% 0.012 13)` dark): muted text — timestamps, secondary metadata, system messages.
+- **Soft Edge** (`oklch(91% 0.008 13)` light / `oklch(29% 0.008 13)` dark): borders and dividers. Always 1px, never wider; never colored.
+- **Muted Icon** (`oklch(82% 0.008 13)` light / `oklch(55% 0.01 13)` dark): icon-only fills when the icon is informational, not actionable.
+- **Surface Secondary** (`oklch(96% 0.005 13)` light / `oklch(26% 0.01 13)` dark): tonal layer for secondary buttons, hover states, muted panels.
+- **Warm Card** (`oklch(99.5% 0.003 13)` light / `oklch(23% 0.01 13)` dark): elevated surfaces (cards, dialogs, popovers). One step warmer than the page in dark mode to give tonal lift without a shadow.
+
+### Semantic
+
+- **Verified Sage** (`oklch(68% 0.15 155)`): success — completed tasks, applied diffs, healthy state. Pair with check shape.
+- **Editor Amber** (`oklch(76% 0.14 78)`): warning and *running* state. Used for live agent indicators and background-task running dots. Never alarms, never congratulates; states *attention available*. Pair with text or icon.
+- **Reference Blue** (`oklch(66% 0.13 235)`): informational — links, references, neutral notices. Pair with underline or icon.
+
+### Named Rules
+
+**The Tint-Everything Rule.** No `#000` or `#fff`. Every neutral carries chroma 0.003–0.013 toward hue 13°. Pure black or pure white in this codebase is a bug.
+
+**The One-Voice Rule.** Kanna Coral is the only brand color and is used on ≤10% of any given screen. Its rarity is the point. Decorative use prohibited.
+
+**The Color-Plus Rule.** Color alone never carries meaning. Status, errors, and live states always pair color with shape (icon), text, or weight, so the interface remains legible to users with reduced color vision and to anyone glancing past a screen.
+
+## 3. Typography
+
+**Display Font:** Bricolage Grotesque Variable (Bricolage Grotesque fallback, sans-serif). Used **only** for the Kanna wordmark. Not for headings.
+
+**Body Font:** Body — a self-hosted warm humanist sans served from `/fonts/body-*.woff2` at weights 400, 500, 600. Fallback stack: `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif`. Body is the workhorse: chat content, sidebar, dialogs, settings, every label that is not code.
+
+**Label/Mono Font:** Roboto Mono. Used for code, command names, ids, durations, ages, pids, and any column that benefits from `font-variant-numeric: tabular-nums`.
+
+**Character:** Body reads warmer and less industrial than Inter or system-default. Roboto Mono is geometric without being playful. Together they sit close to a serious editorial publication that happens to render code, not a terminal that grew a UI.
+
+### Hierarchy
+
+- **Display** (Bricolage Grotesque, 800, `clamp(1.75rem, 3.5vw, 2.5rem)`, line-height 1.05, letter-spacing -0.02em): the Kanna wordmark only.
+- **Headline** (Body, 500, 1.125rem / 18px, line-height 1.3, letter-spacing -0.01em): page titles, dialog titles, section headers. Sentence case, no all-caps, no icon prefix on dialog titles.
+- **Title** (Body, 600, 0.9375rem / 15px, line-height 1.35): chat list rows, sidebar group labels, primary command names in lists.
+- **Body** (Body, 400, 0.875rem / 14px, line-height 1.55): chat content, prose, descriptive metadata. Cap line length at 65–75ch in long-form contexts.
+- **Label** (Body, 500, 0.75rem / 12px, line-height 1.3): metadata pairs, timestamps, type tags, secondary annotations.
+- **Mono** (Roboto Mono, 400, 0.8125rem / 13px, line-height 1.55, `tabular-nums`): commands, durations, ages, pids, anything monospaced or numeric.
+
+### Named Rules
+
+**The No-All-Caps Rule.** Headers and labels are sentence case. ALL CAPS is reserved for emergencies the system does not have.
+
+**The Tabular-Nums Rule.** Any duration, count, age, pid, or time-to-x ticker uses `font-variant-numeric: tabular-nums`. Reflow under live tickers is a regression.
+
+**The Mobile-Input-16 Rule.** Inputs, textareas, and selects use `font-size: 16px` minimum on mobile to prevent iOS zoom-on-focus. Carried at the global stylesheet level; do not override.
+
+## 4. Elevation
+
+Kanna is **flat by default with tonal layering for depth**. There is no global shadow vocabulary. In light mode, the page and elevated surfaces share the same lightness; depth comes from a 1px border and from the warm-card hue being identical. In dark mode, elevated surfaces (cards, popovers, dialogs) shift one step lighter than the background (Inkstone → Warm Card Dark) so they lift without a glow.
+
+Shadows appear only as a response to *state*: focus rings, dialog overlays, and the toaster. Even those are restrained — no halo, no spread larger than 4px.
+
+### Shadow Vocabulary
+
+- **Focus ring** (`outline: 2px solid var(--ring)` with 2px offset): keyboard focus only. Visible always; `outline: none` without a replacement is prohibited.
+- **Dialog backdrop** (default shadcn dialog overlay, no blur): a single dimming layer at ~50% black-tinted-warm. **No backdrop-filter blur.**
+- **Toaster** (default sonner shadow): the only floating element with a soft shadow. Bottom-right desktop, top-center mobile.
+
+### Named Rules
+
+**The Flat-By-Default Rule.** Surfaces are flat at rest. Depth is a state response (focus, overlay), not an idle aesthetic.
+
+**The No-Glassmorphism Rule.** `backdrop-filter: blur(...)` on a translucent panel is prohibited as a default. Use it only when the underlying content must stay partially visible for a functional reason (e.g. media overlay).
+
+## 5. Components
+
+### Buttons
+
+- **Shape:** rounded corners (`rounded-md`, ~6px). Never pill, never sharp.
+- **Primary:** Espresso Ink fill, Pale Foreground text, 8×14 padding. Hover steps to slightly lighter ink.
+- **Secondary:** Surface Secondary fill, Espresso Ink text. Used for non-destructive secondary actions.
+- **Ghost:** transparent fill, Espresso Ink text. Used inside dense lists where another fill would be noise.
+- **Destructive:** Kanna Coral fill, Pale Foreground text. Reserved for stop, delete, force-kill. Pairs with confirm-step inline; never opens a modal-on-modal.
+- **Hover / Focus:** color transitions in 150ms ease-out. Focus ring (2px solid Ring) on `:focus-visible`. Active state slightly compresses background luminance, no transform.
+
+### Inputs / Fields
+
+- **Style:** Paper background, Soft Edge 1px border, `rounded-md`, 8×12 padding.
+- **Focus:** border shifts to Ring color; subtle 1px focus ring outside the border, no glow.
+- **Error:** border shifts to Kanna Coral, helper text in Coral with icon prefix.
+- **Mobile:** font-size 16px enforced globally to prevent iOS zoom.
+
+### Cards / Surfaces
+
+- **Corner Style:** `rounded-lg` (8px).
+- **Background:** Warm Card (light or dark variant) — same hue as page in light, one step lighter in dark.
+- **Shadow Strategy:** none at rest; depth via background hue + 1px Soft Edge border in light mode.
+- **Border:** 1px Soft Edge in light mode; borderless in dark mode (tonal lift carries it).
+- **Internal Padding:** 16px default; 24px for dialog surfaces.
+
+### Dialogs / Popovers / Sheets
+
+- **Surface:** Warm Card with `rounded-lg`, 24px padding for dialogs, 12–16px for popovers.
+- **Title:** Headline scale, sentence case, no icon prefix.
+- **Backdrop:** dim layer, no blur.
+- **Open animation:** scale 0.98 → 1, opacity 0 → 1, 160ms ease-out-quart. Disabled under `prefers-reduced-motion`.
+- **Mobile:** dialogs become bottom sheets, full width, swipe-down to dismiss.
+
+### Navigation (Sidebar + ChatNavbar)
+
+- **Sidebar:** Surface Secondary background, Title-scale group labels, Body-scale chat rows, status indicator dot at start of row (sage / amber / coral / muted, pair with shape variation). Drag-and-drop project ordering via clear handle, never a hidden affordance.
+- **Navbar:** flat, 1px Soft Edge bottom border, Body-scale title centered, action icon group right-aligned. Tooltips use the project `Tooltip` component, **never** native `title`.
+- **Active state:** background shifts to Surface Secondary, label weight steps up to Title (600). No left-border stripe.
+
+### Lists (chat transcripts, sidebar, background tasks)
+
+- **Row anatomy:** two-line by default — Title-scale primary line + Label-scale meta line. Mono used for command names and timestamps; sans for descriptive labels.
+- **Hover:** background tints to Surface Secondary, no transform, no scale.
+- **Selected:** subtle Surface Secondary fill plus 1px-left visual is **prohibited** (anti-pattern). Use full-row tonal fill or a leading marker dot instead.
+
+### Status Indicators
+
+- **Dots:** 6–8px solid circle, paired with a label or context (chat title, list row). Amber = running, Sage = completed/idle, Coral = failed/needs attention, Muted = neutral. **Static; no pulse, no glow.** A pulsing dot reads as anxiety.
+
+### Terminal pane (signature component)
+
+`kanna-terminal` overrides xterm's default background to transparent, inheriting the page background. The PTY content sits in the same tonal field as the chat — the terminal is part of the document, not a separate window. Roboto Mono carries content; selection uses Surface Secondary; cursor blink is a single CSS animation, no canvas glow.
+
+## 6. Do's and Don'ts
+
+### Do:
+
+- **Do** tint every neutral toward hue 13° at chroma 0.003–0.013. White is `oklch(99.5% 0.003 13)`. Black is `oklch(20% 0.01 13)`. Pure `#fff` and `#000` are bugs.
+- **Do** carry the One-Voice Rule: Kanna Coral on ≤10% of any screen, used for brand mark and destructive intent only.
+- **Do** pair color with shape, label, or weight on every state indicator. Color alone never communicates.
+- **Do** use Roboto Mono with `tabular-nums` for every duration, age, count, pid, or live ticker. Reflow under a ticker is a regression.
+- **Do** keep dialogs flat: scale-and-fade entry, no backdrop blur, no nested modals; inline confirm flows for destructive actions.
+- **Do** write keyboard shortcuts on every action. Every keyboard action also has a clear mouse target. No dead-ends in either direction.
+- **Do** respect `prefers-reduced-motion`: disable all entry animations and translateY/translateX transitions.
+- **Do** use the project `Tooltip` component. Native `title` attributes are prohibited as a hover-explanation surface.
+- **Do** target body text contrast ≥ 7:1 (AAA) where the design allows; never below AA (4.5:1).
+
+### Don't:
+
+- **Don't** use `#000`, `#fff`, or any zero-chroma neutral. Tint everything toward hue 13°.
+- **Don't** use purple-blue gradients, glassmorphism cards, or glow accents. Quoting PRODUCT.md: avoid "**generic AI SaaS gradient** — purple-blue hero gradients, glassmorphism cards, glow accents, ChatGPT-clone chrome."
+- **Don't** ship marketing-cream backgrounds, oversized illustrations, or hero-feature-card grids. Quoting PRODUCT.md: avoid "**marketing-heavy SaaS-cream** — cream backgrounds, hero illustrations, 'feature card' grids, oversized CTA buttons."
+- **Don't** put saturated green or cyan on a black background. Quoting PRODUCT.md: avoid "**neon terminal cyberpunk** — black background plus saturated green/cyan accents; hacker-aesthetic chrome."
+- **Don't** stack panels at Datadog/Grafana density. Quoting PRODUCT.md: avoid "**cluttered devtool dashboards** — every pixel a panel, no breathing room, no hierarchy."
+- **Don't** use `border-left` greater than 1px as a colored stripe to indicate state. Use a leading dot, full-row tint, or weight change instead.
+- **Don't** clip text inside a gradient (`background-clip: text` with a gradient). Use a solid color; emphasis via weight or size.
+- **Don't** open a modal on top of a modal. Inline confirm or step the existing dialog.
+- **Don't** animate layout properties (`width`, `height`, `top`, `left`, `padding`). Animate `transform` and `opacity` only.
+- **Don't** pulse status dots. A pulsing dot reads as anxiety; the warm coral is alarming enough on its own when it appears.
+- **Don't** use `outline: none` on focusable elements without a clear replacement focus indicator.
+- **Don't** rely on color alone for status; pair with icon, label, or weight.
diff --git a/PRODUCT.md b/PRODUCT.md
new file mode 100644
index 000000000..88e3e57ac
--- /dev/null
+++ b/PRODUCT.md
@@ -0,0 +1,45 @@
+# Product
+
+## Register
+
+product
+
+## Users
+
+Solo developers running Claude Code or Codex CLIs on their own machine for focused, multi-hour sessions. They jump between many chats and projects, expect keyboard-first navigation with mouse fallbacks, and watch agents work for long stretches while occasionally steering. Context is a quiet desk on a real monitor, not a phone. They came to Kanna because the raw CLI made long sessions hard to track; they stay because the UI makes the work legible without getting in the way.
+
+## Product Purpose
+
+Kanna is a web UI for the Claude Code and Codex CLIs that makes long agent sessions tractable. It surfaces project structure, chat status, transcripts, tool calls, plan-mode prompts, and background work as a single calm, navigable workspace. Success looks like: a developer running three agents across two projects can tell at a glance what each is doing, jump in to steer any of them, never lose work to a forgotten background process, and trust what the transcript shows.
+
+## Brand Personality
+
+Editorial, thoughtful, warm. Voice: confident without swagger; explains state, never performs it. Closer to a well-edited document than a control panel. Quiet typography does the heavy lifting. Color is restrained and tinted toward warm neutrals, never the icy grays of generic devtools.
+
+## Anti-references
+
+- **Generic AI SaaS gradient** — purple-blue hero gradients, glassmorphism cards, glow accents, ChatGPT-clone chrome.
+- **Marketing-heavy SaaS-cream** — cream backgrounds, hero illustrations, "feature card" grids, oversized CTA buttons.
+- **Neon terminal cyberpunk** — black background plus saturated green/cyan accents; hacker-aesthetic chrome.
+- **Cluttered devtool dashboards** — Datadog/Grafana density: every pixel a panel, no breathing room, no hierarchy.
+
+Reference for the right feel: **Notion**. Warm neutrals, content-first, calm density, editorial type discipline.
+
+## Design Principles
+
+1. **Workflow over wow.** Design serves the developer's task; it never performs. If a flourish does not help someone steer an agent faster, cut it.
+2. **Calm density.** Show a lot of state at once, but with breathing room, weighted hierarchy, and warmth. Density without rhythm is clutter.
+3. **Editorial typography earns hierarchy.** Scale, weight, and spacing carry meaning. No decorative gradients, no glow, no chrome substituting for type.
+4. **Keyboard-first, mouse-friendly.** Every action reachable from the keyboard. Every keyboard action also reachable from a clear mouse target. No dead-ends in either direction.
+5. **Trust via legibility.** Agent output, tool calls, and background processes read like documents you can audit — not log dumps, not loading spinners. The user must always be able to verify what is happening.
+
+## Accessibility & Inclusion
+
+Target WCAG 2.1 AAA where feasible, AA as the floor. Specifically:
+
+- Contrast ≥ 7:1 for body text and ≥ 4.5:1 for large text where the design allows; never below AA.
+- Full keyboard navigation including all destructive actions (e.g. stopping background tasks).
+- Visible focus rings on every interactive element; never `outline: none` without a replacement.
+- Respect `prefers-reduced-motion`: disable non-essential transitions and any directional motion.
+- Color is never the only signal — pair with icon, label, or weight (status, errors, running/stopped states).
+- Tabular numerics (`font-variant-numeric: tabular-nums`) for any timing, count, or status duration.
diff --git a/README.md b/README.md
index 57fc5c8f3..9bac8d9a5 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,18 @@
- 
+ Community fork of jakemor/kanna — kept in sync with upstream and extended with subscription-billing PTY mode, OAuth token pooling, multi-provider chat (Claude + Codex), subagent orchestration, durable tool-approval protocol, in-app self-update, and more.
+
+
+
+ 
+ 
+ 
+ 
+
+
+
+ 📖 Docs: kanna-wiki.lowbit.link
@@ -24,10 +35,27 @@
+## About this fork
+
+Kanna started life as [jakemor/kanna](https://github.com/jakemor/kanna) — a clean web UI for the Claude Code CLI. This fork (`@cuongtran001/kanna`) tracks upstream and layers on features needed for heavier day-to-day use, multi-account billing, and self-hosting.
+
+**Headline additions vs. upstream:**
+
+- **Subscription-billing PTY driver** (`KANNA_CLAUDE_DRIVER=pty`) — runs the `claude` CLI under a pseudo-terminal so Pro/Max plans are charged instead of API rates. Includes JSONL event parity with the SDK driver, macOS `sandbox-exec` / Linux `bwrap` sandboxing, allowlist preflight probes, and failure-mode parity.
+- **OAuth token pool** — register multiple Claude OAuth tokens; Kanna rotates across them per chat with automatic fallover on rate-limit and an explicit disabled state.
+- **Multi-provider chat** — switch between Claude and Codex (OpenAI) from the composer with per-provider model + reasoning-effort controls and Codex fast mode.
+- **Subagent orchestration** — first-class subagent CRUD, `@agent/` mentions, parallel runs, live activity labels, MCP progress notifications, and `mcp__kanna__delegate_subagent` so the main agent itself can delegate.
+- **Durable tool-approval protocol** (`KANNA_MCP_TOOL_CALLBACKS=1`) — pending `AskUserQuestion` / `ExitPlanMode` / built-in shims survive server restart and replay to the client on reconnect.
+- **Cloudflare `expose_port` MCP tool** — agent-callable port exposure with always-ask or auto-expose modes, replacing bash-output sniffing.
+- **In-app self-update** — one-click pull/rebuild/reload with a host-agnostic supervisor (works under pm2, systemd, docker, plain shell) or direct pm2 reload; install any prior release straight from the changelog UI.
+- **Git worktree isolation** per chat, **bulk import** of existing `~/.claude/projects/` sessions, **proactive context compaction**, **password gate** for HTTP/WS/API, **PWA / mobile layout**, **mermaid rendering** in transcripts, **standalone HTML transcript export**, and **customizable keybindings**.
+
+See the full inventory in [Features](#features) below.
+
## Quickstart
```bash
-bun install -g kanna-code
+bun install -g @cuongtran001/kanna
```
If Bun isn't installed, install it first:
@@ -46,41 +74,151 @@ That's it. Kanna opens in your browser at [`localhost:3210`](http://localhost:32
## Features
-- **Multi-provider support** — switch between Claude and Codex (OpenAI) from the chat input, with per-provider model selection, reasoning effort controls, and Codex fast mode
+**Providers & models**
+
+- **Multi-provider support** — switch between Claude and Codex (OpenAI) from the chat input, with per-provider model selection, reasoning-effort controls, and Codex fast mode
+- **OAuth token pool** — register multiple Claude OAuth tokens; Kanna rotates across them per chat
+- **Subscription-billing PTY driver** — optional `KANNA_CLAUDE_DRIVER=pty` runs the `claude` CLI under a pseudo-terminal so Pro/Max subscription billing is preserved instead of API rates
+
+**Chat & transcript**
+
+- **Rich transcript rendering** — hydrated tool calls, collapsible tool groups, plan-mode dialogs, and interactive prompts with full result display
+- **Inline diff viewer** — file and commit diffs rendered directly in the transcript
+- **Embedded terminal** — per-project xterm terminal in a resizable side panel (macOS/Linux)
+- **File & image uploads** — drag-and-drop attachments into the composer
+- **Slash commands & @-mentions** — in-composer pickers for slash commands, file mentions, and subagents
+- **Plan mode** — review and approve agent plans before execution
+- **Subagent orchestration** — run and track parallel subagents within a turn
+- **Background tasks** — long-running tasks tracked out-of-band with a status indicator
+- **Auto-continue** — optionally continue a turn automatically when the agent stops short
+- **Proactive compaction** — context-window meter with automatic transcript compaction before limits are hit
+
+**Projects & sessions**
+
- **Project-first sidebar** — chats grouped under projects, with live status indicators (idle, running, waiting, failed)
- **Drag-and-drop project ordering** — reorder project groups in the sidebar with persistent ordering
- **Local project discovery** — auto-discovers projects from both Claude and Codex local history
-- **Rich transcript rendering** — hydrated tool calls, collapsible tool groups, plan mode dialogs, and interactive prompts with full result display
-- **Quick responses** — lightweight structured queries (e.g. title generation) via Haiku with automatic Codex fallback
-- **Plan mode** — review and approve agent plans before execution
-- **Persistent local history** — refresh-safe routes backed by JSONL event logs and compacted snapshots
-- **Auto-generated titles** — chat titles generated in the background via Claude Haiku
+- **Bulk import Claude Code sessions** — one-click import of existing `~/.claude/projects/` sessions with full transcript and seamless resume via the Claude Agent SDK
+- **Git worktree isolation** — run a chat in an isolated worktree without disturbing your working tree
- **Session resumption** — resume agent sessions with full context preservation
+- **Auto-generated titles** — chat titles generated in the background via Claude Haiku
+- **Quick responses** — lightweight structured queries (e.g. title generation) via Haiku with automatic Codex fallback
+
+**Persistence & realtime**
+
+- **Persistent local history** — refresh-safe routes backed by append-only JSONL event logs and compacted snapshots
- **WebSocket-driven** — real-time subscription model with reactive state broadcasting
+- **Standalone transcript export** — export a chat as a self-contained HTML viewer
+
+**Access & notifications**
+
+- **Password protection** — optional launch password gating the app, WebSocket, and API routes
+- **Public share link** — `--share` creates a temporary `trycloudflare.com` URL with a terminal QR code
+- **Cloudflare tunnel via `expose_port` tool** — opt-in; the agent proactively calls the Kanna `expose_port` MCP tool with a port. In `always-ask` mode Kanna shows an inline "expose via Cloudflare" card for you to accept; in `auto-expose` mode `cloudflared tunnel --url` spawns immediately. Both modes are gated by the Cloudflare Tunnel setting
+- **Web push & sound notifications** — browser push and sound alerts when a chat needs attention
+- **Customizable keybindings** — user-editable keyboard shortcuts
+- **In-app self-update** — one-click update that pulls, rebuilds, and hot-reloads (host-agnostic supervisor or pm2)
+- **Mobile-friendly** — responsive layout, installable as a standalone PWA
## Architecture
+```mermaid
+flowchart LR
+ Browser["Browser
React + Zustand"]
+
+ subgraph Server["Bun Server (src/server/**)"]
+ direction TB
+ WS["WSRouter
subscriptions + commands"]
+ Auth["Auth gate"]
+ Agent["AgentCoordinator
multi-provider turns"]
+ ES["EventStore
append-only JSONL + snapshots"]
+ RM["ReadModels
derived views"]
+ Diff["DiffStore"]
+ Term["TerminalManager"]
+ Up["Uploads"]
+ Disc["Discovery"]
+ Push["Push"]
+ Tun["Share / Tunnel"]
+ Upd["UpdateManager"]
+
+ subgraph Adapters["*.adapter.ts (IO seal exempt)"]
+ direction LR
+ FsA["fs / chokidar"]
+ DbA["bun:sqlite / pg"]
+ SpA["Bun.spawn / child_process"]
+ HtA["node:http / fetch"]
+ PtyA["Bun.Terminal (PTY)"]
+ end
+
+ WS --> Agent
+ WS --> ES
+ WS --> RM
+ Agent --> ES
+ Agent -.spawn.-> SpA
+ Agent -.spawn.-> PtyA
+ ES -.fs.-> FsA
+ Diff -.fs+spawn.-> SpA
+ Diff -.fs.-> FsA
+ Term -.pty.-> PtyA
+ Up -.fs.-> FsA
+ Disc -.fs.-> FsA
+ Tun -.spawn+http.-> SpA
+ Tun -.http.-> HtA
+ Upd -.spawn.-> SpA
+ end
+
+ subgraph Shared["src/shared/** (pure)"]
+ Proto["protocol types"]
+ Types["domain types"]
+ end
+
+ subgraph External["External processes"]
+ CC["Claude Agent SDK / claude CLI (PTY)"]
+ CX["Codex App Server"]
+ FS["Local FS
~/.kanna/data/, project dirs"]
+ end
+
+ Browser <-->|WebSocket| WS
+ Browser -.types.-> Shared
+ Server -.types.-> Shared
+
+ SpA --> CC
+ SpA --> CX
+ PtyA --> CC
+ FsA --> FS
```
-Browser (React + Zustand)
- ↕ WebSocket
-Bun Server (HTTP + WS)
- ├── WSRouter ─── subscription & command routing
- ├── AgentCoordinator ─── multi-provider turn management
- ├── ProviderCatalog ─── provider/model/effort normalization
- ├── QuickResponseAdapter ─── structured queries with provider fallback
- ├── EventStore ─── JSONL persistence + snapshot compaction
- └── ReadModels ─── derived views (sidebar, chat, projects)
- ↕ stdio
-Claude Agent SDK / Codex App Server (local processes)
- ↕
-Local File System (~/.kanna/data/, project dirs)
-```
+
+**Layer rules (lint-enforced, see [CLAUDE.md](./CLAUDE.md#side-effect-lint-ports-and-adapters-seal)):**
+
+- `src/shared/**` + `src/client/**` — pure. ESLint `no-restricted-imports` errors on `node:fs`, `bun:sqlite`, `node:child_process`, `node:http`, `Bun.spawn`, `Bun.file`, `Bun.serve`, …
+- `src/server/**` production — also sealed at `error`. Side-effect call sites only allowed inside files matching `**/*.adapter.ts` (or the legacy `src/server/adapters/**` dir).
+- Mixed-concern modules extract their IO into a sibling `*-io.adapter.ts` and import through it.
**Key patterns:** Event sourcing for all state mutations. CQRS with separate write (event log) and read (derived snapshots) paths. Reactive broadcasting — subscribers get pushed fresh snapshots on every state change. Multi-provider agent coordination with tool gating for user-approval flows. Provider-agnostic transcript hydration for unified rendering.
+### Workflow: adding code that touches IO
+
+```mermaid
+flowchart TD
+ Start(["You need fs / spawn / http / DB / Bun globals"]) --> Layer{"Which layer?"}
+ Layer -->|src/shared or src/client| Reject["ESLint errors at CI"]
+ Reject --> Move["Move the module to src/server/**
or inject through a typed parameter"]
+ Move --> Server
+ Layer -->|src/server| Server{"File responsibility?"}
+ Server -->|leaf IO wrapper| RenameAdapter["Name it foo.adapter.ts
(exempt from seal)"]
+ Server -->|mixed domain + IO| SiblingAdapter["Extract calls into foo-io.adapter.ts
keep domain logic in foo.ts
import helpers from the adapter"]
+ Server -->|domain only| Port["Take a typed port parameter
provided by caller's adapter"]
+ RenameAdapter --> Lint["bun run lint"]
+ SiblingAdapter --> Lint
+ Port --> Lint
+ Lint --> CI(["CI: lint + tests + build"])
+```
+
+For the longer story (90 → 0 burndown, ratchet pipeline retired in PR #303) see the **Side-Effect Lint** section of `CLAUDE.md`.
+
## Requirements
-- [Bun](https://bun.sh) v1.3.5+
+- [Bun](https://bun.sh) v1.3.11+
- A working [Claude Code](https://docs.anthropic.com/en/docs/claude-code) environment
- _(Optional)_ [Codex CLI](https://github.com/openai/codex) for Codex provider support
@@ -91,7 +229,7 @@ Embedded terminal support uses Bun's native PTY APIs and currently works on macO
Install Kanna globally:
```bash
-bun install -g kanna-code
+bun install -g @cuongtran001/kanna
```
If Bun isn't installed, install it first:
@@ -103,7 +241,7 @@ curl -fsSL https://bun.sh/install | bash
Or clone and build from source:
```bash
-git clone https://github.com/jakemor/kanna.git
+git clone https://github.com/cuongtranba/kanna.git
cd kanna
bun install
bun run build
@@ -114,6 +252,7 @@ bun run build
```bash
kanna # start with defaults (localhost only)
kanna --port 4000 # custom port
+kanna --strict-port # fail instead of trying another port
kanna --no-open # don't open browser
kanna --password # require a password before loading the app
kanna --share # create a public quick tunnel + terminal QR
@@ -176,6 +315,20 @@ With `--cloudflared `, Kanna runs `cloudflared tunnel run --token
If Kanna can detect the public hostname from cloudflared output, it prints the same QR/public/local block.
If not, it keeps the tunnel running, warns that no public hostname was detected, and prints the local URL so you can use the hostname already configured for that tunnel in Cloudflare.
+### Auto-expose detected ports
+
+When the agent runs a Bash command in a chat (`bun run dev`, `go run`, `uvicorn`, etc.), Kanna can detect any listening port from the command's stdout and offer to expose it through a Cloudflare quick tunnel without leaving the chat.
+
+Enable from **Settings → Cloudflare Tunnel**:
+
+- **Toggle** — opt-in (off by default)
+- **Mode** — `Always ask` (one card per detected port; click Expose to spawn) or `Auto-expose` (spawn immediately on detection)
+- **`cloudflared` path** — defaults to `cloudflared` on `$PATH`
+
+Each detected port shows up inline in the transcript. Click **Expose**, watch the spinner until cloudflared returns the `*.trycloudflare.com` URL, then click **Stop** when done. Tunnels are also stopped automatically when the chat closes or the server restarts.
+
+Requires the `cloudflared` binary installed locally — `brew install cloudflared` on macOS, or see [Cloudflare's downloads](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).
+
## Development
```bash
@@ -204,43 +357,63 @@ bun run dev:server # http://localhost:5175
## Scripts
-| Command | Description |
-| -------------------- | ---------------------------- |
-| `bun run build` | Build for production |
-| `bun run check` | Typecheck + build |
-| `bun run dev` | Run client + server together |
-| `bun run dev:client` | Vite dev server only |
-| `bun run dev:server` | Bun backend only |
-| `bun run start` | Start production server |
+| Command | Description |
+| -------------------- | ------------------------------------ |
+| `bun run build` | Build client + standalone export viewer |
+| `bun run check` | Typecheck, lint, and build |
+| `bun run lint` | ESLint over `src/` (zero-warning gate) |
+| `bun run dev` | Run client + server together |
+| `bun run dev:client` | Vite dev server only (`:5174`) |
+| `bun run dev:server` | Bun backend only (`:5175`) |
+| `bun run start` | Start production server |
+| `bun test` | Run the test suite |
## Project Structure
+Abridged — the actual tree has more modules, each with co-located `*.test.ts`:
+
```
src/
├── client/ React UI layer
│ ├── app/ App router, pages, central state hook, socket client
-│ ├── components/ Messages, chat chrome, dialogs, buttons, inputs
-│ ├── hooks/ Theme, standalone mode detection
-│ ├── stores/ Zustand stores (chat input, preferences, project order)
-│ └── lib/ Formatters, path utils, transcript parsing
+│ ├── components/ chat-ui, messages, settings, ui primitives, modals
+│ ├── hooks/ mobile/standalone detection, theme, mention/slash suggestions
+│ ├── stores/ Zustand stores (chat input, preferences, terminal, tasks…)
+│ └── lib/ formatters, path utils, transcript parsing, keybindings
├── server/ Bun backend
-│ ├── cli.ts CLI entry point & browser launcher
-│ ├── server.ts HTTP/WS server setup & static serving
-│ ├── agent.ts AgentCoordinator (multi-provider turn management)
-│ ├── codex-app-server.ts Codex App Server JSON-RPC client
-│ ├── provider-catalog.ts Provider/model/effort normalization
-│ ├── quick-response.ts Structured queries with provider fallback
-│ ├── ws-router.ts WebSocket message routing & subscriptions
-│ ├── event-store.ts JSONL persistence, replay & compaction
-│ ├── discovery.ts Auto-discover projects from Claude and Codex local state
-│ ├── read-models.ts Derive view models from event state
-│ └── events.ts Event type definitions
+│ ├── cli.ts · cli-runtime.ts CLI entry, flag parsing, supervisor
+│ ├── server.ts HTTP/WS server + static serving
+│ ├── auth.ts password gate for HTTP/WS/API
+│ ├── ws-router.ts WebSocket routing & subscriptions
+│ ├── agent.ts AgentCoordinator (multi-provider turns)
+│ ├── codex-app-server.ts Codex App Server JSON-RPC client
+│ ├── claude-pty/ PTY driver (subscription billing)
+│ ├── oauth-pool/ Claude OAuth token rotation
+│ ├── provider-catalog.ts provider/model/effort normalization
+│ ├── quick-response.ts structured queries w/ provider fallback
+│ ├── event-store.ts JSONL persistence, replay & compaction
+│ ├── read-models.ts derived view models
+│ ├── events.ts event type definitions
+│ ├── discovery.ts auto-discover Claude/Codex projects
+│ ├── claude-session-importer.ts bulk import existing sessions
+│ ├── diff-store.ts per-chat diff hydration
+│ ├── terminal-manager.ts embedded-terminal PTY sessions
+│ ├── uploads.ts attachment intake
+│ ├── subagent-orchestrator.ts parallel subagent runs
+│ ├── background-tasks.ts out-of-band task tracking
+│ ├── worktree-store.ts git worktree isolation
+│ ├── push/ web-push notifications
+│ ├── share.ts · cloudflare-tunnel/ trycloudflare / expose_port tunnels
+│ ├── update-manager.ts · update-strategy.ts self-update
+│ ├── kanna-mcp.ts Kanna MCP tools (built-in shims)
+│ └── keybindings.ts persisted keybindings
└── shared/ Shared between client & server
- ├── types.ts Core data types, provider catalog, transcript entries
- ├── tools.ts Tool call normalization and hydration
- ├── protocol.ts WebSocket message protocol
- ├── ports.ts Port configuration
- └── branding.ts App name, data directory paths
+ ├── types.ts core domain types, provider catalog, transcript entries
+ ├── tools.ts tool-call normalization & hydration
+ ├── protocol.ts WebSocket wire envelopes
+ ├── ports.ts default ports & dev-mode offsets
+ ├── share.ts share/tunnel shared types
+ └── branding.ts app name & data-directory paths
```
## Data Storage
@@ -257,13 +430,128 @@ All state is stored locally at `~/.kanna/data/`:
Event logs are append-only JSONL. On startup, Kanna replays the log tail after the last snapshot, then compacts if the logs exceed 2 MB.
+## Self-hosting on macOS (pm2 + Cloudflare tunnel)
+
+Run Kanna as a background service on macOS under [pm2](https://pm2.keymetrics.io/), exposed through a named Cloudflare tunnel. The in-app **Update** button then pulls the latest commit, rebuilds, and hot-reloads the pm2 process — no terminal round-trip needed.
+
+### 1. Link the repo as the global install
+
+`bun link` makes the global `kanna` binary resolve to your checkout:
+
+```bash
+cd ~/path/to/kanna
+bun install
+bun run build
+bun link # registers @cuongtran001/kanna → repo
+```
+
+After this, `~/.bun/install/global/node_modules/@cuongtran001/kanna` is a symlink to your repo.
+
+### 2. Create a named Cloudflare tunnel
+
+In the [Cloudflare Zero Trust dashboard](https://one.dash.cloudflare.com/) → **Networks → Tunnels → Create tunnel** (type: **Cloudflared**):
+
+1. Name the tunnel (e.g. `kanna`) and copy the **connector token** Cloudflare shows you. You will paste it as `KANNA_CLOUDFLARED_TOKEN` in the next step.
+2. Add a **public hostname** route: pick your subdomain (e.g. `kanna.example.com`) and point service to `HTTP` → `localhost:5174` (or whatever `--port` you plan to run). Kanna binds `127.0.0.1` automatically when `--cloudflared` is set, so the tunnel is the only ingress.
+3. Save. The hostname's TLS is terminated at Cloudflare's edge.
+
+### 3. Write `scripts/pm2.env` (untracked secrets)
+
+`scripts/deploy.sh` reads this file and passes the values to kanna as `--cloudflared --password `. Without it, deploy launches kanna with no token and no password — kanna will then run as plain HTTP on localhost, **`trustProxy` will not auto-enable**, and every `/auth/login` POST through the tunnel will return **403** because the CSRF origin check compares the browser's `https://` Origin against the server's `http://` `req.url`.
+
+Create `scripts/pm2.env` (gitignored) with at least:
+
+```env
+KANNA_CLOUDFLARED_TOKEN=
+KANNA_PASSWORD=
+# Optional: pass through to spawned Claude Code agents
+# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
+```
+
+Generate a strong password with `openssl rand -base64 24`.
+
+### 4. (Migrating from launchd) Unload the old agent
+
+If you previously ran Kanna under launchd, unload it once so pm2 can take over:
+
+```bash
+launchctl bootout gui/$(id -u)/io.silentium.kanna || true
+```
+
+### 5. First deploy
+
+`scripts/deploy.sh` installs pm2 if missing, renders `scripts/pm2.config.cjs` from the template (via `envsubst` from `brew install gettext`), and starts the pm2 process:
+
+```bash
+./scripts/deploy.sh
+pm2 list # kanna should be "online"
+pm2 logs kanna --lines 50
+```
+
+`pm2 save` persists the running process list. To resurrect after a reboot, run `pm2 startup` once (pm2 prints the exact command) and then `pm2 save` again.
+
+The pm2 config sets `KANNA_RELOADER=pm2` and `KANNA_REPO_DIR=` so the in-app Update button triggers the pm2 reload pipeline (see next section). Override the pm2 process name with `KANNA_PM2_PROCESS_NAME` before running `./scripts/deploy.sh` if you need to run multiple instances.
+
+### 6. Redeploy / update
+
+Two ways to ship a new build:
+
+**a. From the UI (fastest).** Click **Update** in the running app. The server runs `git pull --ff-only` → conditional `bun install` → `bun run build` → `pm2.reload` internally, and the UI reconnects to the fresh build. If any step fails, the UI shows a red banner with the stderr tail and the old build keeps serving.
+
+**b. From the terminal.** Useful for non-Kanna deploys (e.g., pm2 config edits) or when the UI is unreachable:
+
+```bash
+git pull
+./scripts/deploy.sh
+```
+
+### 7. Troubleshooting: 403 on login
+
+If the login screen rejects the correct password with **403** behind a Cloudflare (or any HTTPS-terminating) tunnel, the server is running without `trustProxy` enabled. The CSRF origin check then compares the browser's `https://kanna.example.com` `Origin` against the local `http://127.0.0.1:` `req.url` and rejects them as mismatched. Two ways to enable it:
+
+- **Recommended.** Pass `--cloudflared ` (or `--share`) on the kanna command line. Both flags auto-enable `trustProxy` and bind to `127.0.0.1`. With `scripts/pm2.env` populated, `scripts/deploy.sh` does this for you — verify with `pm2 logs kanna --lines 20` that the startup line includes `--cloudflared`.
+- **Running cloudflared separately?** Use `--cloudflared` on kanna anyway and let kanna spawn the tunnel; the standalone `cloudflared` daemon does not set `trustProxy` for you. (There is no standalone `--trust-proxy` CLI flag today.)
+
+Other things to check if the 403 persists:
+
+- Cloudflare tunnel **public hostname** points to `http://localhost:`, not `https://` — kanna terminates plain HTTP locally.
+- The public hostname's **TLS mode** is `Full` or `Flexible` (Cloudflare → Origin is HTTP), not `Full (strict)` against a self-signed origin.
+- No `Access` policy in front of the hostname is stripping or rewriting the `Origin` header.
+
+### 8. Update strategies
+
+The update mechanism is abstracted behind `UpdateChecker` + `UpdateReloader` interfaces in `src/server/update-strategy.ts`, selected at startup by `KANNA_RELOADER`:
+
+| `KANNA_RELOADER` | Check | Reload | Notes |
+|---|---|---|---|
+| unset / `supervisor` | npm registry for `@cuongtran001/kanna` | ` install -g @cuongtran001/kanna@latest`, exit 76, supervisor respawns | Default. End-user path. `` auto-detected: `bun`/`npm`/`pnpm`/`yarn`. Override via `KANNA_UPDATE_COMMAND`. |
+| `pm2` | `git fetch` + `HEAD` vs `origin/main` | `git pull --ff-only` → cond. `bun install` → `bun run build` → `pm2 reload` | Dev/self-host path. Requires `KANNA_REPO_DIR`. |
+
+**Host-agnostic supervisor mode.** When `KANNA_RELOADER` is unset (default), the in-app Update button works under any process host (pm2, systemd, docker, screen, plain shell) — the internal supervisor catches the child's exit-76 and respawns. The package manager used to install the new version is auto-detected from the running binary path:
+
+- `~/.bun/bin/kanna` → `bun install -g`
+- `~/.local/share/pnpm/kanna` (or any `pnpm/` path) → `pnpm add -g`
+- `~/.yarn/bin/kanna` (or any `.yarn/` path) → `yarn global add`
+- anything else (e.g. `/usr/local/bin/kanna`, `~/.npm-global/bin/kanna`) → `npm install -g`
+
+If the detected manager is not on `PATH`, kanna falls back through `bun → npm → pnpm → yarn`. To override the install command entirely — useful for custom installers, monorepo wrappers, docker pulls, ansible, etc. — set `KANNA_UPDATE_COMMAND`. Placeholders `{package}` and `{version}` are substituted; the result is executed via `sh -c`.
+
+```bash
+# Force npm regardless of detection
+KANNA_UPDATE_COMMAND="npm install -g {package}@{version}" pm2 start kanna
+# Custom: chain pre-install hook
+KANNA_UPDATE_COMMAND="my-deploy-hook && npm install -g {package}@{version}" kanna
+```
+
+To add another reload mechanism (e.g., docker, systemd) at the strategy layer, implement `UpdateChecker` + `UpdateReloader` and branch inside `createUpdateStrategy`; no changes to `UpdateManager`, `server.ts`, or any client code are needed.
+
## Star History
-
+
-