memex-mvp 0.10.7 → 0.10.9

package/HELP.md

@@ -363,6 +363,40 @@ memex get web-1582ab51a7b7 --json > backup.json
 
 ---
 
+## 🖥 Web-дашборд (v0.10.8+) — посмотреть память глазами
+
+Когда хочется не звать AI, а **самому полистать** что у тебя в memex'е — есть локальный read-only веб-UI. Та же SQLite, другая поверхность.
+
+```bash
+memex web --open                       # localhost:8765, откроется в браузере
+memex web --port 9000                  # свой порт
+memex web --public --token s3cret      # 0.0.0.0 с bearer-авторизацией (для туннеля)
+memex web --help
+```
+
+**5 страниц:**
+
+- `/` — статы (messages / conversations / sources / imports), sources breakdown, callout про pending Telegram, последние 10 чатов
+- `/conversations` — список с **live FTS5-поиском** через htmx (печатаешь — обновляется за 200мс), фильтры-чипы по source
+- `/c/:id` — **verbatim** транскрипт chat-bubble'ами (то самое, что не делает claude-mem — он только AI-резюмирует); поиск внутри чата с подсветкой; пагинация для 1000+ сообщений
+- `/pending` — Telegram-экспорты с чекбоксами; нажимаешь Import / Skip — тот же гейт privacy, что и `memex telegram import`
+- `/settings` — daemon status, путь и размер БД, установленные хуки, decisions count (read-only)
+
+**Что важно:**
+- Не always-on. `memex web` поднял — Ctrl+C погасил. Никакого фонового сервера.
+- Read-only. Единственные записи — это TG import / skip на `/pending`.
+- Localhost-only by default. Для remote — `--public --token …`.
+- Без build-step'a. Raw Node `http` + tagged template literals + htmx 14KB. Клиентский bundle ≈ 30KB (для сравнения у claude-mem ~10MB React-бандл).
+- Брендирование как на лендинге (mint #6ee7b7 на тёмном).
+
+**Когда полезно:**
+- Хочешь сам прокрутить большой Telegram-чат и не вспоминать какой именно поиск ввести
+- Демо коллеге — открыл вкладку, показал что у тебя реально лежит дословно (это и есть verbatim-moat — на любой чат с любого источника можно перейти и увидеть сырое, не AI-пересказ)
+- Аудит pending'a с мышкой и галочками вместо `memex telegram import 1 3 5`
+- Cron-friendly remote endpoint (тот же сервер потом получит multi-host sync API в v0.13+)
+
+---
+
 ## 🪄 Auto-context (v0.8+) — Brian Chesky moment
 
 Magic-фича. Когда ты открываешь Claude Code в проекте, Claude **сам** инжектит 500-1500 токенов контекста про этот проект — что ты делал недавно, какие conversations касались темы. Ты ещё ничего не спросил, а AI **уже знает**.

package/README.md

@@ -211,6 +211,36 @@ Terminal equivalents: `memex telegram check / pending / import 1 3 5 / skip 2 /
 
 ---
 
+## Web dashboard (v0.10.8+) — see your own memory
+
+Opt-in, read-only local UI for browsing the corpus without any AI in the loop. Same SQLite, different surface.
+
+```sh
+memex web --open      # localhost:8765, opens in browser
+memex web --port 9000 # custom port
+memex web --public --token s3cret   # bind on 0.0.0.0 with bearer auth (for remote / tunnel)
+memex web --help
+```
+
+Five pages:
+
+| Page              | What it shows                                                                            |
+|-------------------|------------------------------------------------------------------------------------------|
+| `/`               | Stats grid · sources breakdown · pending Telegram callout · recent 10 conversations      |
+| `/conversations`  | Live FTS5 search via htmx (200ms debounce) · source-chip filters · hit counts per chat   |
+| `/c/:id`          | **Verbatim** transcript in chat-bubbles · in-chat search with `<mark>` highlight · paged |
+| `/pending`        | Telegram exports awaiting decision · bulk Import / Skip checkboxes · decision history    |
+| `/settings`       | Daemon status · DB path & size · hooks installed · TG decisions counts (read-only)       |
+
+**Design constraints:**
+- **Opt-in, not always-on.** `memex web` starts the server; Ctrl+C stops it. No daemon.
+- **Read-only by default.** The only writes are TG import / skip on the `/pending` page — same privacy gate as `memex telegram import`.
+- **Localhost-only by default.** Binds `127.0.0.1`. Use `--public --token <…>` for remote access (cron-friendly: same endpoint reserved for the future multi-host sync API).
+- **No build step.** Node raw `http` + tagged template literals + htmx 14KB CDN. Total client bundle: ~30KB.
+- **Brand-aligned.** Same Inter + mint palette as [memex.parallelclaw.ai](https://memex.parallelclaw.ai).
+
+---
+
 ## What it captures
 
 | Source                | How it gets in                                                 |

package/README.ru.md

@@ -528,6 +528,36 @@ One file with all your AI conversations — sounds scarier than it is.
 
 ---
 
+## Web-дашборд (v0.10.8+) — увидеть свою память без AI
+
+Опциональный read-only локальный UI для просмотра корпуса. Та же SQLite, другая поверхность — пригождается когда хочется просто посмотреть на свои разговоры глазами, без MCP-агента в цикле.
+
+```sh
+memex web --open       # localhost:8765, откроет браузер
+memex web --port 9000  # свой порт
+memex web --public --token s3cret   # 0.0.0.0 с bearer-авторизацией (для remote / туннеля)
+memex web --help
+```
+
+Пять страниц:
+
+| Страница          | Что внутри                                                                                |
+|-------------------|-------------------------------------------------------------------------------------------|
+| `/`               | Сетка статов · sources breakdown · callout про pending Telegram · последние 10 conversations |
+| `/conversations`  | Live FTS5-поиск через htmx (200мс debounce) · фильтры-чипы по source · кол-во hit'ов на чат |
+| `/c/:id`          | **Verbatim** транскрипт chat-bubble'ами · поиск внутри чата с `<mark>` подсветкой · пагинация |
+| `/pending`        | Telegram-экспорты ждущие решения · чекбоксы bulk Import / Skip · история твоих решений    |
+| `/settings`       | Статус daemon'а · путь и размер БД · установленные хуки · TG decisions counts (read-only) |
+
+**Принципы:**
+- **Opt-in, не always-on.** `memex web` поднимает сервер; Ctrl+C гасит. Никакого фонового демона.
+- **Read-only по умолчанию.** Единственные записи — TG import / skip на `/pending` (тот же privacy-gate, что и `memex telegram import`).
+- **Localhost-only по умолчанию.** Слушает на `127.0.0.1`. Для удалённого доступа — `--public --token <…>` (на этом же endpoint в будущем поедет multi-host sync API).
+- **Без build-step'а.** Raw Node `http` + tagged template literals + htmx 14KB с CDN. Клиентский bundle ≈ 30KB.
+- **Брендирование совпадает с лендингом.** Inter + mint-палитра как на [memex.parallelclaw.ai](https://memex.parallelclaw.ai).
+
+---
+
 ## Как использовать на практике / How to actually use it
 
 Полный guide с **6 типовыми use case'ами** (Telegram → action plan, cross-AI bridge, recall, project resume, patterns, deck-анализ), описанием всех MCP-tools и troubleshooting — в [HELP.md](HELP.md). Скопируй любой промпт из этого файла → вставь в свой AI-агент → попробуй сразу после установки.

package/lib/cli/index.js

@@ -38,7 +38,7 @@ import {
 // ---------- Subcommand registry ----------
 export const CLI_SUBCOMMAND_NAMES = [
   'search', 'recent', 'list', 'get', 'overview',
-  'projects', 'context', 'hook', 'when', 'telegram',
+  'projects', 'context', 'hook', 'when', 'telegram', 'web',
   'help', '-h', '--help', '-v', '--version',
 ];
 
@@ -1670,6 +1670,81 @@ function tgCmdScan(opts, discovery, pending) {
   console.log(c.dim('Review: memex telegram pending'));
 }
 
+// =============================================================
+// `memex web` — opt-in local dashboard
+// =============================================================
+async function cmdWeb(args) {
+  // Parse web-specific flags out of argv. We DO NOT route through parseArgs()
+  // because it would silently ignore --port/--host/--token (forward-compat
+  // unknown-flag policy), and we want strict parsing for the server.
+  const opts = { port: 8765, host: '127.0.0.1', token: null, open: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--port' || a === '-p') opts.port = parseInt(args[++i], 10);
+    else if (a === '--host') opts.host = args[++i];
+    else if (a === '--token') opts.token = args[++i];
+    else if (a === '--open' || a === '-o') opts.open = true;
+    else if (a === '--public') opts.host = '0.0.0.0';
+    else if (a === '--help' || a === '-h') {
+      console.log(`memex web — local read-only dashboard
+
+Usage:
+  memex web [options]
+
+Options:
+  --port, -p <num>    Port to bind (default: 8765)
+  --host <addr>       Bind address (default: 127.0.0.1, localhost-only)
+  --public            Shorthand for --host 0.0.0.0 (bind on all interfaces)
+  --token <str>       Require Authorization: Bearer <str> for all routes
+                      except /api/health and /static/*. Recommended when
+                      using --public or behind a tunnel.
+  --open, -o          Open the dashboard in your browser after start
+  -h, --help          Show this help
+
+Examples:
+  memex web                              localhost:8765, no auth
+  memex web --open                       and open in browser
+  memex web --port 9000                  custom port
+  memex web --public --token s3cret      bind on 0.0.0.0 with bearer auth
+`);
+      // Help path: exit cleanly so the caller (server.js) doesn't fall through
+      // to MCP-mode init, and Node doesn't warn about an unsettled top-level
+      // await waiting on an HTTP server that was never started.
+      process.exit(0);
+    }
+    else if (a.startsWith('--')) {
+      console.error(`Unknown flag: ${a}`);
+      console.error(`Run 'memex web --help' for usage.`);
+      process.exit(2);
+    }
+  }
+
+  if (!Number.isFinite(opts.port) || opts.port <= 0 || opts.port > 65535) {
+    console.error(`Invalid port: ${opts.port}`);
+    process.exit(2);
+  }
+  if (opts.host !== '127.0.0.1' && opts.host !== 'localhost' && !opts.token) {
+    console.error(c.yellow('⚠  Binding on ' + opts.host + ' without --token leaves the dashboard open to the network.'));
+    console.error(c.yellow('   Press Ctrl+C now if that\'s not what you want. Continuing in 3 seconds…'));
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+
+  if (!existsSync(DB_PATH)) {
+    console.error(`memex.db not found at ${DB_PATH}`);
+    console.error(`Run 'memex-sync install' first to set up the daemon and create the DB.`);
+    process.exit(1);
+  }
+
+  const { startServer } = await import('../web/index.js');
+  await startServer(opts);
+  // The HTTP server now holds the event loop open. Park on an unsettled
+  // promise so cmdWeb never returns to the dispatcher — that way server.js
+  // doesn't reach process.exit(0) below or fall through to MCP-mode init.
+  // (Required because `await runCli(...)` would otherwise resolve as soon
+  // as startServer's listen-callback fires.)
+  await new Promise(() => {});
+}
+
 // =============================================================
 // DISPATCH
 // =============================================================
@@ -1689,6 +1764,7 @@ export async function runCli(sub, args) {
       case 'context':    await cmdContext(args); break;
       case 'hook':       await cmdHook(args); break;
       case 'telegram':   await cmdTelegram(args); break;
+      case 'web':        await cmdWeb(args); break;
       case 'help':       await cmdHelp(); break;
       case '--help':
       case '-h':         await cmdUsage(); break;

package/lib/web/index.js

@@ -0,0 +1,265 @@
+/**
+ * memex web dashboard — HTTP server.
+ *
+ * Opt-in: invoked via `memex web` CLI command. Binds 127.0.0.1 by default.
+ * Read-only by design (only POST endpoints are pending review actions).
+ *
+ * Stack:
+ *   • Node.js raw http module (no Express, no framework)
+ *   • Tagged template literals for HTML
+ *   • htmx for client-side reactivity (from CDN)
+ *   • Better-sqlite3 read-only DB handle
+ *
+ * Routes:
+ *   GET  /                         → dashboard
+ *   GET  /conversations            → list + search
+ *   GET  /conversations/search     → htmx partial
+ *   GET  /c/:id                    → full transcript
+ *   GET  /pending                  → telegram exports awaiting decision
+ *   POST /pending/import           → import selected
+ *   POST /pending/skip             → skip selected
+ *   GET  /settings                 → daemon status, sources, hooks
+ *   GET  /static/<file>            → static assets (CSS, etc)
+ *   GET  /api/health               → JSON liveness probe
+ */
+
+import { createServer } from 'node:http';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { spawn, execSync } from 'node:child_process';
+import Database from 'better-sqlite3';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const STATIC_DIR = join(__dirname, 'static');
+
+const HOME = homedir();
+const MEMEX_DIR = process.env.MEMEX_DIR || join(HOME, '.memex');
+const DB_PATH = join(MEMEX_DIR, 'data', 'memex.db');
+
+// ----- Helpers -----
+
+function send(res, status, body, contentType = 'text/html; charset=utf-8') {
+  res.statusCode = status;
+  res.setHeader('Content-Type', contentType);
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.end(body);
+}
+
+function sendJson(res, status, obj) {
+  send(res, status, JSON.stringify(obj, null, 2), 'application/json; charset=utf-8');
+}
+
+function notFound(res) {
+  send(res, 404, '<h1>404 — not in memex</h1><p><a href="/">back to dashboard</a></p>');
+}
+
+function serverError(res, e) {
+  console.error('[memex web] error:', e);
+  send(res, 500, `<h1>500 — server error</h1><pre>${escapeHtml(e.message || String(e))}</pre>`);
+}
+
+function escapeHtml(s) {
+  return String(s || '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+// Parse the URL into { pathname, query }
+function parseUrl(url) {
+  const i = url.indexOf('?');
+  if (i === -1) return { pathname: url, query: {} };
+  const pathname = url.slice(0, i);
+  const queryStr = url.slice(i + 1);
+  const query = {};
+  for (const pair of queryStr.split('&')) {
+    if (!pair) continue;
+    const [k, v] = pair.split('=');
+    query[decodeURIComponent(k)] = v != null ? decodeURIComponent(v.replace(/\+/g, ' ')) : '';
+  }
+  return { pathname, query };
+}
+
+// ----- Static file serving (CSS, etc) -----
+
+const STATIC_TYPES = {
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+};
+
+function serveStatic(res, pathname) {
+  const rel = pathname.replace(/^\/static\//, '').replace(/\.\./g, '');
+  const full = join(STATIC_DIR, rel);
+  if (!existsSync(full)) return notFound(res);
+  const ext = full.slice(full.lastIndexOf('.'));
+  const type = STATIC_TYPES[ext] || 'application/octet-stream';
+  const body = readFileSync(full);
+  res.statusCode = 200;
+  res.setHeader('Content-Type', type);
+  res.setHeader('Cache-Control', 'public, max-age=300');
+  res.end(body);
+}
+
+// ----- DB handle (read-only) -----
+
+let _db = null;
+function getDb() {
+  if (_db) return _db;
+  if (!existsSync(DB_PATH)) {
+    throw new Error(`memex.db not found at ${DB_PATH}. Run 'memex-sync install' first.`);
+  }
+  _db = new Database(DB_PATH, { readonly: true, fileMustExist: true });
+  return _db;
+}
+
+// ----- Sync status (daemon health) -----
+
+function getDaemonStatus() {
+  try {
+    // Inline check — read the LaunchAgent plist + try to ps the daemon
+    const plistPath = join(HOME, 'Library/LaunchAgents/com.parallelclaw.memex.sync.plist');
+    const installed = existsSync(plistPath);
+    if (!installed) return { installed: false, running: false, lastCaptureMs: null };
+
+    // Recent activity from ingest.log
+    const logPath = join(MEMEX_DIR, 'data', 'ingest.log');
+    let lastCaptureMs = null;
+    if (existsSync(logPath)) {
+      const ageMs = Date.now() - statSync(logPath).mtimeMs;
+      lastCaptureMs = ageMs;
+    }
+
+    // Process check via launchctl (best effort)
+    let running = false;
+    try {
+      const out = execSync('launchctl list | grep com.parallelclaw.memex.sync', { encoding: 'utf-8', timeout: 1000 });
+      running = !out.match(/^\s*-\s/m); // "-" means not running
+    } catch (_) { /* not running */ }
+
+    return { installed: true, running, lastCaptureMs };
+  } catch (_) {
+    return { installed: false, running: false, lastCaptureMs: null };
+  }
+}
+
+// ----- Read-only auth (optional bearer token) -----
+
+function checkAuth(req, expectedToken) {
+  if (!expectedToken) return true; // no auth required
+  const auth = req.headers.authorization || '';
+  return auth === `Bearer ${expectedToken}`;
+}
+
+// ----- Request handler -----
+
+async function handleRequest(req, res, opts) {
+  const { pathname, query } = parseUrl(req.url);
+
+  // Static files (no auth required)
+  if (pathname.startsWith('/static/')) {
+    return serveStatic(res, pathname);
+  }
+
+  // Health check (no auth required, used by tests)
+  if (pathname === '/api/health') {
+    return sendJson(res, 200, { ok: true, db: existsSync(DB_PATH) });
+  }
+
+  // Auth check
+  if (!checkAuth(req, opts.token)) {
+    return send(res, 401, '<h1>401 — auth required</h1><p>Pass <code>--token</code> when starting <code>memex web</code> and include <code>Authorization: Bearer &lt;token&gt;</code></p>');
+  }
+
+  try {
+    // Route dispatch
+    if (pathname === '/') {
+      const { renderDashboard } = await import('./routes/dashboard.js');
+      return send(res, 200, await renderDashboard(getDb(), getDaemonStatus()));
+    }
+    if (pathname === '/conversations') {
+      const { renderConversations } = await import('./routes/conversations.js');
+      return send(res, 200, await renderConversations(getDb(), query, getDaemonStatus()));
+    }
+    if (pathname === '/conversations/search') {
+      const { renderConversationsPartial } = await import('./routes/conversations.js');
+      return send(res, 200, await renderConversationsPartial(getDb(), query));
+    }
+    if (pathname.startsWith('/c/')) {
+      const { renderConversation } = await import('./routes/conversation.js');
+      const id = decodeURIComponent(pathname.slice(3));
+      return send(res, 200, await renderConversation(getDb(), id, query, getDaemonStatus()));
+    }
+    if (pathname === '/pending') {
+      const { renderPending } = await import('./routes/pending.js');
+      return send(res, 200, await renderPending(getDaemonStatus()));
+    }
+    if (pathname === '/pending/import' && req.method === 'POST') {
+      const { handleImport } = await import('./routes/pending.js');
+      const body = await readBody(req);
+      return send(res, 200, await handleImport(body));
+    }
+    if (pathname === '/pending/skip' && req.method === 'POST') {
+      const { handleSkip } = await import('./routes/pending.js');
+      const body = await readBody(req);
+      return send(res, 200, await handleSkip(body));
+    }
+    if (pathname === '/settings') {
+      const { renderSettings } = await import('./routes/settings.js');
+      return send(res, 200, await renderSettings(getDb(), getDaemonStatus()));
+    }
+    return notFound(res);
+  } catch (e) {
+    return serverError(res, e);
+  }
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      const raw = Buffer.concat(chunks).toString('utf-8');
+      // Parse form-encoded body
+      const params = {};
+      for (const pair of raw.split('&')) {
+        if (!pair) continue;
+        const [k, v] = pair.split('=');
+        const key = decodeURIComponent(k);
+        const val = v != null ? decodeURIComponent(v.replace(/\+/g, ' ')) : '';
+        // Handle repeated keys (e.g., index=1&index=3 → array)
+        if (key in params) {
+          params[key] = Array.isArray(params[key]) ? [...params[key], val] : [params[key], val];
+        } else {
+          params[key] = val;
+        }
+      }
+      resolve(params);
+    });
+    req.on('error', reject);
+  });
+}
+
+// ----- Public entry point -----
+
+export function startServer({ port = 8765, host = '127.0.0.1', token = null, open = false } = {}) {
+  const server = createServer((req, res) => {
+    handleRequest(req, res, { token }).catch((e) => serverError(res, e));
+  });
+
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, host, () => {
+      const url = `http://${host === '0.0.0.0' ? 'localhost' : host}:${port}`;
+      console.log(`memex web listening on ${url}`);
+      if (token) console.log(`  auth: bearer token required (Authorization: Bearer ${token})`);
+      if (open) {
+        // Best-effort open browser on macOS / Linux
+        const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
+        try { spawn(cmd, [url], { stdio: 'ignore', detached: true }).unref(); } catch (_) {}
+      }
+      resolve({ server, url });
+    });
+  });
+}

package/lib/web/routes/conversation.js

@@ -0,0 +1,193 @@
+/**
+ * GET /c/:id — verbatim transcript of one conversation.
+ *
+ * This is the page that demonstrates memex's verbatim moat: every message
+ * the user and the AI exchanged, in chat-bubble form, never paraphrased.
+ *
+ * Query params:
+ *   q       — optional search term to highlight inside the transcript
+ *   offset  — pagination offset (default 0)
+ *   limit   — page size (default 200, max 1000)
+ */
+
+import { renderPage, html, raw, esc, fmtDate, fmtDateTime, fmtNum } from '../templates.js';
+
+const MAX_LIMIT = 1000;
+const DEFAULT_LIMIT = 200;
+
+function clampLimit(raw) {
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+
+/**
+ * Determine which side of the transcript the message should appear on.
+ *
+ * Conventions:
+ *   - role='user' or sender is the user (claude-code/cowork) → right side ("you")
+ *   - role='assistant' or 'model' → left side ("ai")
+ *   - Telegram: sender matches "self_indicator" → right; everyone else → left
+ */
+function bubbleSide(msg) {
+  if (msg.role === 'user') return 'right';
+  if (msg.role === 'assistant' || msg.role === 'model') return 'left';
+  // Telegram heuristic: first sender alphabetically goes "left", rest on alternating sides.
+  // Without a notion of "me", we just put non-user roles on the left.
+  return 'left';
+}
+
+function dayKey(ts) {
+  if (!ts) return null;
+  return new Date(ts * 1000).toISOString().slice(0, 10);
+}
+
+/**
+ * Highlight occurrences of `q` (case-insensitive) inside escaped text.
+ * Receives ALREADY-ESCAPED HTML — we do regex over that string and wrap
+ * matches in <mark>. Safe because we never let user input near a tag opener.
+ */
+function highlight(escapedText, q) {
+  if (!q || !q.trim()) return escapedText;
+  const needle = q.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Avoid matching inside existing tags by requiring no '<' before next '>'
+  const re = new RegExp(`(${needle})`, 'gi');
+  return escapedText.replace(re, '<mark>$1</mark>');
+}
+
+function renderBubble(msg, q) {
+  const side = bubbleSide(msg);
+  const cls = side === 'right' ? 'chat-bubble user' : 'chat-bubble ai';
+  const who = msg.sender || msg.role || (side === 'right' ? 'you' : 'ai');
+  const when = msg.ts ? fmtDateTime(msg.ts) : '';
+  const text = msg.text || '';
+  const highlighted = highlight(esc(text), q);
+  return `
+    <div class="${cls}" id="msg-${msg.id}">
+      <span class="chat-who">${esc(who)}${when ? ' · ' + esc(when) : ''}</span>
+      <p>${highlighted}</p>
+    </div>
+  `;
+}
+
+export async function renderConversation(db, id, query, status) {
+  const q = query.q || '';
+  const offset = Math.max(0, parseInt(query.offset, 10) || 0);
+  const limit = clampLimit(query.limit);
+
+  const conv = db
+    .prepare('SELECT * FROM conversations WHERE conversation_id = ?')
+    .get(id);
+
+  if (!conv) {
+    const body = html`
+      <div class="empty">
+        <h3>Conversation not found</h3>
+        <p>No conversation with id <code>${esc(id)}</code> in this database.</p>
+        <p style="margin-top:12px;"><a class="btn" href="/conversations">← Back to conversations</a></p>
+      </div>
+    `;
+    return renderPage({ title: 'Not found', active: 'conversations', body, status });
+  }
+
+  const messages = db
+    .prepare(
+      `
+      SELECT id, role, sender, text, ts, msg_id
+      FROM messages
+      WHERE conversation_id = ?
+        AND role NOT IN ('boundary', 'summary')
+      ORDER BY COALESCE(ts, 0) ASC, id ASC
+      LIMIT ? OFFSET ?
+    `
+    )
+    .all(id, limit, offset);
+
+  const totalNonMeta = db
+    .prepare(
+      "SELECT COUNT(*) AS n FROM messages WHERE conversation_id = ? AND role NOT IN ('boundary', 'summary')"
+    )
+    .get(id).n;
+
+  // Build day-separated transcript
+  const transcriptParts = [];
+  let lastDay = null;
+  for (const m of messages) {
+    const day = dayKey(m.ts);
+    if (day && day !== lastDay) {
+      transcriptParts.push(`<div class="transcript-day">${esc(day)}</div>`);
+      lastDay = day;
+    }
+    transcriptParts.push(renderBubble(m, q));
+  }
+
+  const transcriptHtml = transcriptParts.join('\n');
+
+  // Pagination
+  const hasPrev = offset > 0;
+  const hasNext = offset + messages.length < totalNonMeta;
+  const baseQs = q ? `?q=${encodeURIComponent(q)}&` : '?';
+  const pagination = (hasPrev || hasNext)
+    ? html`
+        <div class="search-bar" style="justify-content:space-between;margin-top:24px;">
+          ${hasPrev
+            ? html`<a class="btn" href="/c/${encodeURIComponent(id)}${raw(baseQs)}offset=${Math.max(0, offset - limit)}&limit=${limit}">← Previous ${limit}</a>`
+            : html`<span></span>`}
+          <span class="search-meta">
+            Showing ${fmtNum(offset + 1)}–${fmtNum(offset + messages.length)} of ${fmtNum(totalNonMeta)}
+          </span>
+          ${hasNext
+            ? html`<a class="btn" href="/c/${encodeURIComponent(id)}${raw(baseQs)}offset=${offset + limit}&limit=${limit}">Next ${limit} →</a>`
+            : html`<span></span>`}
+        </div>
+      `
+    : null;
+
+  // Search box scoped to this conversation
+  const searchBar = html`
+    <form class="search-bar" method="get" action="/c/${encodeURIComponent(id)}">
+      <input
+        class="search-input"
+        type="search"
+        name="q"
+        placeholder="🔍  Find in this conversation…"
+        value="${esc(q)}"
+        autocomplete="off"
+      />
+      ${q
+        ? html`<a class="btn" href="/c/${encodeURIComponent(id)}">Clear</a>`
+        : null}
+    </form>
+  `;
+
+  const header = html`
+    <p style="margin-bottom:14px;">
+      <a class="btn" href="/conversations">← All conversations</a>
+    </p>
+    <section class="card">
+      <div class="card-label">
+        <span class="conv-source-tag">${conv.source}</span>
+        ${fmtNum(totalNonMeta)} messages
+        · ${fmtDate(conv.first_ts)} → ${fmtDate(conv.last_ts)}
+        ${conv.project_path ? raw(' · <code>' + esc(conv.project_path) + '</code>') : null}
+      </div>
+      <div class="card-body">
+        <h2 style="font-size:20px;font-weight:700;letter-spacing:-0.02em;">${conv.title || '(untitled)'}</h2>
+      </div>
+    </section>
+  `;
+
+  const body = html`
+    ${header}
+    ${searchBar}
+    <div class="transcript">${raw(transcriptHtml)}</div>
+    ${pagination}
+  `;
+
+  return renderPage({
+    title: conv.title || 'Conversation',
+    active: 'conversations',
+    body,
+    status,
+  });
+}