From a3c72bb87872a2cdfee62e48c0442f34d9efb661 Mon Sep 17 00:00:00 2001
From: francy51 <francesco12382@gmail.com>
Date: Tue, 16 Jun 2026 15:44:29 -0400
Subject: [PATCH] feat(kanban): persist board, reference pages, and run agents
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the localStorage kanban with the backend-backed board, add typed clients
and a React hook with optimistic updates. Cards can reference static doc pages
and user-created custom pages (new "custom" reference type with purple chips).

Add the agentic orchestrator UI: a per-card panel to launch `pi` runs, watch a
live tool/thought stream over SSE, steer mid-run, and stop — while the board
stays fully interactive. The board page wires the orchestrator and custom-pages
stores into every card.
---
 .../src/components/kanban/AgentRunBar.tsx     |  390 ++++++
 .../docs/src/components/kanban/KanbanCard.tsx |  423 ++++++
 .../src/components/kanban/ReferenceLinks.tsx  |  140 ++
 .../src/components/kanban/useKanbanBoard.ts   |  236 ++++
 .../src/components/kanban/useOrchestrator.ts  |  226 ++++
 apps/docs/src/lib/kanbanApi.ts                |  125 ++
 apps/docs/src/lib/orchestratorApi.ts          |  102 ++
 apps/docs/src/pages/docs/KanbanBoardPage.tsx  | 1172 ++++-------------
 8 files changed, 1906 insertions(+), 908 deletions(-)
 create mode 100644 apps/docs/src/components/kanban/AgentRunBar.tsx
 create mode 100644 apps/docs/src/components/kanban/KanbanCard.tsx
 create mode 100644 apps/docs/src/components/kanban/ReferenceLinks.tsx
 create mode 100644 apps/docs/src/components/kanban/useKanbanBoard.ts
 create mode 100644 apps/docs/src/components/kanban/useOrchestrator.ts
 create mode 100644 apps/docs/src/lib/kanbanApi.ts
 create mode 100644 apps/docs/src/lib/orchestratorApi.ts

diff --git a/apps/docs/src/components/kanban/AgentRunBar.tsx b/apps/docs/src/components/kanban/AgentRunBar.tsx
new file mode 100644
index 0000000..a7f50a0
--- /dev/null
+++ b/apps/docs/src/components/kanban/AgentRunBar.tsx
@@ -0,0 +1,390 @@
+import { useEffect, useRef, useState } from 'react';
+import type { Card } from '../../lib/kanbanApi';
+import type { RunEvent } from '../../lib/orchestratorApi';
+import type { UseOrchestrator } from './useOrchestrator';
+
+/**
+ * Inline agentic control for one kanban card.
+ *
+ * Lets the operator launch a `pi` run against the card, watch its live
+ * tool/thought stream, steer it mid-flight, and stop it — all while the rest of
+ * the board stays interactive. Settled runs show their outcome, commit, and
+ * summary, with the worktree-backed changes recorded back onto the card and the
+ * documentation by the agent itself.
+ */
+
+interface AgentRunBarProps {
+  card: Card;
+  orch: UseOrchestrator;
+}
+
+const STATUS_META: Record<string, { label: string; color: string }> = {
+  queued: { label: 'Queued', color: 'var(--muted)' },
+  running: { label: 'Running', color: 'var(--accent)' },
+  completed: { label: 'Completed', color: 'var(--green)' },
+  failed: { label: 'Failed', color: 'var(--red)' },
+  stopped: { label: 'Stopped', color: 'var(--fg-dim)' },
+};
+
+export function AgentRunBar({ card, orch }: AgentRunBarProps) {
+  const run = orch.runForCard(card.id);
+  const isActive = run?.status === 'running';
+
+  const [promptDraft, setPromptDraft] = useState('');
+  const [steerDraft, setSteerDraft] = useState('');
+  const [showPrompt, setShowPrompt] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const logRef = useRef<HTMLDivElement>(null);
+
+  // Stream the active run's events while it is running.
+  useEffect(() => {
+    if (!run || !isActive) return;
+    orch.watch(run.id);
+    return () => orch.unwatch(run.id);
+  }, [run, isActive, orch]);
+
+  // Auto-scroll the log to the latest event.
+  const events = run ? orch.eventsForRun(run.id) : [];
+  useEffect(() => {
+    if (logRef.current) logRef.current.scrollTop = logRef.current.scrollHeight;
+  }, [events.length]);
+
+  const start = async () => {
+    setBusy(true);
+    try {
+      await orch.start({ cardId: card.id, prompt: promptDraft.trim() || undefined });
+      setPromptDraft('');
+      setShowPrompt(false);
+    } catch (e) {
+      alert(e instanceof Error ? e.message : 'Failed to start run');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const steer = async () => {
+    if (!run || !steerDraft.trim()) return;
+    setBusy(true);
+    try {
+      await orch.message(run.id, steerDraft.trim(), 'steer');
+      setSteerDraft('');
+    } catch (e) {
+      alert(e instanceof Error ? e.message : 'Failed to steer');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const stop = async () => {
+    if (!run) return;
+    setBusy(true);
+    try {
+      await orch.stop(run.id);
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const dismiss = async () => {
+    if (!run) return;
+    try {
+      await orch.remove(run.id);
+    } catch (e) {
+      alert(e instanceof Error ? e.message : 'Failed to remove run');
+    }
+  };
+
+  return (
+    <div style={wrapStyle}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '6px' }}>
+        <span style={{ fontSize: '0.78rem', fontWeight: 600, color: 'var(--fg)' }}>🤖 Agent</span>
+        {run && (
+          <StatusPill status={run.status} />
+        )}
+        {run?.branch && (
+          <span style={branchStyle} title={run.worktreePath ?? undefined}>
+            ⎇ {run.branch}
+          </span>
+        )}
+        <span style={{ marginLeft: 'auto' }}>
+          {!run && !showPrompt && (
+            <button type="button" style={primaryBtn} onClick={() => setShowPrompt(true)}>
+              ▶ Run agent
+            </button>
+          )}
+          {isActive && (
+            <button type="button" style={dangerBtn} onClick={stop} disabled={busy}>
+              ■ Stop
+            </button>
+          )}
+          {run && !isActive && (
+            <>
+              <button type="button" style={ghostBtn} onClick={() => setShowPrompt((s) => !s)}>
+                ↻ Re-run
+              </button>
+              <button type="button" style={ghostBtn} onClick={dismiss} title="Remove this run">
+                Dismiss
+              </button>
+            </>
+          )}
+        </span>
+      </div>
+
+      {/* Start prompt (create or re-run) */}
+      {showPrompt && (
+        <div style={{ marginBottom: '8px' }}>
+          <textarea
+            placeholder="Optional extra instructions for this run (e.g. 'focus on the Rust client', 'also update the economy doc')…"
+            value={promptDraft}
+            onChange={(e) => setPromptDraft(e.target.value)}
+            onClick={(e) => e.stopPropagation()}
+            style={{ ...inputStyle, width: '100%', minHeight: '56px', resize: 'vertical' }}
+            spellCheck={false}
+          />
+          <div style={{ marginTop: '4px', display: 'flex', gap: '6px' }}>
+            <button type="button" style={primaryBtn} onClick={start} disabled={busy}>
+              {busy ? 'Starting…' : '▶ Start'}
+            </button>
+            <button type="button" style={ghostBtn} onClick={() => setShowPrompt(false)}>
+              Cancel
+            </button>
+            <span style={hintStyle}>
+              Runs in an isolated git worktree. The agent reads the docs, implements,
+              verifies with cargo/pnpm, then updates the card & docs.
+            </span>
+          </div>
+        </div>
+      )}
+
+      {/* Steer box while running */}
+      {isActive && (
+        <div style={{ display: 'flex', gap: '6px', marginBottom: '8px' }}>
+          <input
+            type="text"
+            placeholder="Steer the agent mid-run…"
+            value={steerDraft}
+            onChange={(e) => setSteerDraft(e.target.value)}
+            onKeyDown={(e) => {
+              e.stopPropagation();
+              if (e.key === 'Enter' && steerDraft.trim()) void steer();
+            }}
+            onClick={(e) => e.stopPropagation()}
+            style={{ ...inputStyle, flex: 1 }}
+          />
+          <button type="button" style={smallBtn} onClick={steer} disabled={busy || !steerDraft.trim()}>
+            Steer
+          </button>
+        </div>
+      )}
+
+      {/* Settled summary */}
+      {run && !isActive && (run.summary || run.commitSha) && (
+        <div style={summaryStyle}>
+          {run.summary && <div style={{ whiteSpace: 'pre-wrap' }}>{run.summary}</div>}
+          <div style={{ marginTop: '4px', fontSize: '0.65rem', color: 'var(--muted)', fontFamily: 'var(--font-mono)' }}>
+            {run.commitSha && <>commit {run.commitSha}</>}
+            {run.finishedAt && <> · finished {new Date(run.finishedAt).toLocaleTimeString()}</>}
+          </div>
+        </div>
+      )}
+
+      {/* Live event log */}
+      {run && events.length > 0 && (
+        <div ref={logRef} style={logStyle}>
+          {events.slice(-200).map((ev, i) => (
+            <EventRow key={`${run.id}-${ev.seq ?? i}`} ev={ev} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function StatusPill({ status }: { status: string }) {
+  const meta = STATUS_META[status] ?? STATUS_META.queued;
+  const pulse = status === 'running';
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: '4px',
+        fontSize: '0.65rem',
+        padding: '2px 7px',
+        borderRadius: 'var(--radius-pill)',
+        border: `1px solid ${meta.color}`,
+        background: `${meta.color}1a`,
+        color: meta.color,
+        textTransform: 'capitalize',
+      }}
+    >
+      <span
+        style={{
+          width: '6px',
+          height: '6px',
+          borderRadius: '50%',
+          background: meta.color,
+          boxShadow: pulse ? `0 0 6px ${meta.color}` : 'none',
+        }}
+      />
+      {meta.label}
+    </span>
+  );
+}
+
+function EventRow({ ev }: { ev: RunEvent }) {
+  switch (ev.type) {
+    case 'tool_start': {
+      const tool = String(ev.data.tool ?? 'tool');
+      const preview = String(ev.data.preview ?? '');
+      return (
+        <div style={evStyle('var(--cyan)')}>
+          <span style={tagStyle}>▸ {tool}</span>{' '}
+          <span style={previewStyle}>{preview}</span>
+        </div>
+      );
+    }
+    case 'tool_end': {
+      const tool = String(ev.data.tool ?? 'tool');
+      const ok = ev.data.ok !== false;
+      const preview = String(ev.data.preview ?? '');
+      return (
+        <div style={evStyle(ok ? 'var(--fg-dim)' : 'var(--red)')}>
+          <span style={tagStyle}>{ok ? '✓' : '✗'} {tool}</span>{' '}
+          <span style={previewStyle}>{preview}</span>
+        </div>
+      );
+    }
+    case 'text':
+      return (
+        <div style={{ ...evStyle('var(--fg)'), background: 'rgba(255,255,255,0.03)', borderRadius: '4px', padding: '4px 6px' }}>
+          <span style={{ whiteSpace: 'pre-wrap' }}>{String(ev.data.text ?? '')}</span>
+        </div>
+      );
+    case 'done':
+      return (
+        <div style={evStyle('var(--green)')}>
+          <span style={tagStyle}>✓ done</span>{' '}
+          <span style={previewStyle}>{String(ev.data.summary ?? '')}</span>
+        </div>
+      );
+    case 'error':
+      return <div style={evStyle('var(--red)')}>⚠ {String(ev.data.message ?? '')}</div>;
+    case 'log': {
+      const level = String(ev.data.level ?? 'info');
+      const color = level === 'error' ? 'var(--red)' : level === 'warn' ? 'var(--accent)' : 'var(--muted)';
+      return <div style={evStyle(color)}>{String(ev.data.text ?? '')}</div>;
+    }
+    default:
+      return null;
+  }
+}
+
+// --- styles ----------------------------------------------------------------
+
+const wrapStyle: React.CSSProperties = {
+  marginTop: 'var(--sp-3)',
+  padding: '10px',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-md)',
+  background: 'var(--surface-raised)',
+};
+
+const branchStyle: React.CSSProperties = {
+  fontFamily: 'var(--font-mono)',
+  fontSize: '0.62rem',
+  color: 'var(--muted)',
+  background: 'var(--surface)',
+  padding: '1px 6px',
+  borderRadius: 'var(--radius-sm)',
+  border: '1px solid var(--border)',
+  maxWidth: '160px',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+};
+
+const logStyle: React.CSSProperties = {
+  maxHeight: '220px',
+  overflowY: 'auto',
+  fontFamily: 'var(--font-mono)',
+  fontSize: '0.7rem',
+  lineHeight: 1.45,
+  background: 'var(--bg)',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-sm)',
+  padding: '6px 8px',
+};
+
+const summaryStyle: React.CSSProperties = {
+  fontSize: '0.75rem',
+  color: 'var(--fg-dim)',
+  background: 'rgba(34,197,94,0.06)',
+  border: '1px solid rgba(34,197,94,0.2)',
+  borderRadius: 'var(--radius-sm)',
+  padding: '6px 8px',
+  marginBottom: '8px',
+};
+
+const inputStyle: React.CSSProperties = {
+  padding: '4px 8px',
+  fontSize: '0.78rem',
+  background: 'var(--surface)',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-sm)',
+  color: 'var(--fg)',
+  fontFamily: 'var(--font-mono)',
+};
+
+const primaryBtn: React.CSSProperties = {
+  padding: '3px 10px',
+  fontSize: '0.74rem',
+  background: 'var(--accent)',
+  border: 'none',
+  borderRadius: 'var(--radius-sm)',
+  cursor: 'pointer',
+  color: 'var(--surface)',
+  fontWeight: 500,
+};
+
+const dangerBtn: React.CSSProperties = {
+  ...primaryBtn,
+  background: 'var(--red)',
+};
+
+const ghostBtn: React.CSSProperties = {
+  padding: '3px 10px',
+  fontSize: '0.74rem',
+  background: 'var(--surface)',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-sm)',
+  cursor: 'pointer',
+  color: 'var(--fg-dim)',
+};
+
+const smallBtn: React.CSSProperties = {
+  ...ghostBtn,
+  padding: '3px 12px',
+};
+
+const hintStyle: React.CSSProperties = {
+  fontSize: '0.62rem',
+  color: 'var(--muted)',
+  fontFamily: 'var(--font-mono)',
+  alignSelf: 'center',
+  flex: 1,
+};
+
+function evStyle(color: string): React.CSSProperties {
+  return { color, marginBottom: '3px', wordBreak: 'break-word' };
+}
+
+const tagStyle: React.CSSProperties = {
+  fontWeight: 600,
+  opacity: 0.95,
+};
+
+const previewStyle: React.CSSProperties = {
+  color: 'var(--fg-dim)',
+  opacity: 0.85,
+};
diff --git a/apps/docs/src/components/kanban/KanbanCard.tsx b/apps/docs/src/components/kanban/KanbanCard.tsx
new file mode 100644
index 0000000..0faaceb
--- /dev/null
+++ b/apps/docs/src/components/kanban/KanbanCard.tsx
@@ -0,0 +1,423 @@
+import { useState } from 'react';
+import type { Card, Column, DocPage, ReferenceType } from '../../lib/kanbanApi';
+import type { CustomPage } from '../../lib/pagesApi';
+import { ReferenceLinks } from './ReferenceLinks';
+import { AgentRunBar } from './AgentRunBar';
+import type { UseOrchestrator } from './useOrchestrator';
+
+const COLUMN_LABELS: Record<Column, string> = {
+  done: 'Done',
+  'in-progress': 'In Progress',
+  todo: 'Todo',
+  backlog: 'Backlog',
+};
+
+interface KanbanCardProps {
+  card: Card;
+  pages: DocPage[];
+  customPages: CustomPage[];
+  orch: UseOrchestrator;
+  expanded: boolean;
+  onToggle: () => void;
+  onMove: (status: Column) => void;
+  onAddComment: (text: string) => void;
+  onDeleteComment: (commentId: string) => void;
+  onAddTag: (tag: string) => void;
+  onRemoveTag: (tag: string) => void;
+  onAddReference: (ref: { label: string; type: ReferenceType; href: string }) => void;
+  onRemoveReference: (href: string) => void;
+}
+
+export function KanbanCard(props: KanbanCardProps) {
+  const { card, pages, customPages, orch, expanded, onToggle } = props;
+  const [commentDraft, setCommentDraft] = useState('');
+  const [tagDraft, setTagDraft] = useState('');
+  const [refDraft, setRefDraft] = useState('');
+  const [customRefDraft, setCustomRefDraft] = useState('');
+
+  const hasComments = card.comments.length > 0;
+  const hasTags = card.tags.length > 0;
+
+  // Doc pages not already referenced (for the add-reference picker).
+  const availablePages = pages.filter(
+    (p) => !card.references.some((r) => r.href === p.path),
+  );
+
+  // Custom pages not already referenced (for the add-reference picker).
+  const availableCustomPages = customPages.filter(
+    (p) => !card.references.some((r) => r.href === `/docs/custom/${p.slug}`),
+  );
+
+  return (
+    <div
+      style={{
+        background: 'var(--surface)',
+        border: `1px solid ${expanded ? 'var(--accent)' : 'var(--border)'}`,
+        borderRadius: 'var(--radius-md)',
+        padding: 'var(--sp-3)',
+        cursor: 'pointer',
+        transition: 'all 0.15s ease',
+        boxShadow: expanded ? '0 2px 8px rgba(0,0,0,0.1)' : 'none',
+      }}
+      onClick={onToggle}
+      className="hover:shadow-sm"
+    >
+      {/* Header: id + category + counts */}
+      <div style={{ display: 'flex', alignItems: 'flex-start', gap: 'var(--sp-2)', marginBottom: 'var(--sp-2)' }}>
+        <span style={badgeStyle}>{card.id}</span>
+        <span style={categoryStyle}>{card.category}</span>
+        <span style={{ marginLeft: 'auto', fontSize: '0.7rem', color: 'var(--fg-dim)' }}>
+          {orch.isRunning(card.id) && (
+            <span style={{ color: 'var(--accent)', marginRight: '6px' }}>🤖 running</span>
+          )}
+          {hasComments && `💬 ${card.comments.length} `}
+          {hasTags && `🏷️ ${card.tags.length} `}
+          {card.references.length > 0 && `🔗 ${card.references.length}`}
+        </span>
+      </div>
+
+      <h4 style={{ margin: '0 0 var(--sp-1) 0', fontSize: '0.9rem', fontWeight: 500, color: 'var(--fg)' }}>
+        {card.title}
+      </h4>
+      <p style={{ margin: '0 0 var(--sp-1) 0', fontSize: '0.8rem', color: 'var(--fg-dim)', lineHeight: 1.4 }}>
+        {card.description}
+      </p>
+      <p style={{ margin: '0 0 var(--sp-2) 0', fontSize: '0.75rem', color: 'var(--fg-dim)', lineHeight: 1.4, fontStyle: 'italic' }}>
+        {card.details}
+      </p>
+
+      {/* References (compact) */}
+      <div style={{ marginBottom: 'var(--sp-2)' }}>
+        <ReferenceLinks references={card.references} pages={pages} customPages={customPages} compact />
+      </div>
+
+      {/* Footer: files + notes + tags */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sp-1)' }}>
+        {card.files && (
+          <div style={{ fontSize: '0.65rem', color: 'var(--muted)', fontFamily: 'var(--font-mono)' }}>
+            📁 {card.files}
+          </div>
+        )}
+        {card.notes && (
+          <div style={noteStyle}>💡 {card.notes}</div>
+        )}
+        {hasTags && (
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: '4px' }}>
+            {card.tags.map((tag) => (
+              <span
+                key={tag}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  props.onRemoveTag(tag);
+                }}
+                style={tagStyle}
+                title="Click to remove tag"
+              >
+                🏷️ {tag} ×
+              </span>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Expanded section */}
+      {expanded && (
+        <div style={{ marginTop: 'var(--sp-3)', paddingTop: 'var(--sp-3)', borderTop: '1px solid var(--border)' }}>
+          {/* Agent orchestrator */}
+          <AgentRunBar card={card} orch={orch} />
+
+          {/* Move */}
+          <div style={{ marginBottom: 'var(--sp-3)' }}>
+            <label style={{ fontSize: '0.75rem', color: 'var(--fg-dim)', marginRight: '8px' }}>Move to:</label>
+            <select
+              onClick={(e) => e.stopPropagation()}
+              onChange={(e) => props.onMove(e.target.value as Column)}
+              value={card.status}
+              style={inputStyle}
+            >
+              {(Object.keys(COLUMN_LABELS) as Column[]).map((c) => (
+                <option key={c} value={c}>
+                  {COLUMN_LABELS[c]}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {/* Add reference (doc page) */}
+          {availablePages.length > 0 && (
+            <div style={{ marginBottom: 'var(--sp-3)' }}>
+              <label style={{ fontSize: '0.75rem', color: 'var(--fg-dim)', display: 'block', marginBottom: '4px' }}>
+                Add doc reference:
+              </label>
+              <select
+                onClick={(e) => e.stopPropagation()}
+                value={refDraft}
+                onChange={(e) => setRefDraft(e.target.value)}
+                style={inputStyle}
+              >
+                <option value="">Select a doc page…</option>
+                {availablePages.map((p) => (
+                  <option key={p.path} value={p.path}>
+                    {p.icon} {p.title}
+                  </option>
+                ))}
+              </select>
+              {refDraft && (
+                <button
+                  type="button"
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    const page = pages.find((p) => p.path === refDraft);
+                    if (page) {
+                      props.onAddReference({ label: page.title, type: 'doc', href: page.path });
+                      setRefDraft('');
+                    }
+                  }}
+                  style={smallButtonStyle}
+                >
+                  Add
+                </button>
+              )}
+            </div>
+          )}
+
+          {/* Add reference (custom page) */}
+          {availableCustomPages.length > 0 && (
+            <div style={{ marginBottom: 'var(--sp-3)' }}>
+              <label style={{ fontSize: '0.75rem', color: 'var(--purple)', display: 'block', marginBottom: '4px' }}>
+                Add custom page reference:
+              </label>
+              <select
+                onClick={(e) => e.stopPropagation()}
+                value={customRefDraft}
+                onChange={(e) => setCustomRefDraft(e.target.value)}
+                style={inputStyle}
+              >
+                <option value="">Select a custom page…</option>
+                {availableCustomPages.map((p) => (
+                  <option key={p.id} value={p.slug}>
+                    {p.icon} {p.title}
+                  </option>
+                ))}
+              </select>
+              {customRefDraft && (
+                <button
+                  type="button"
+                  onClick={(e) => {
+                    e.stopPropagation();
+                    const page = customPages.find((p) => p.slug === customRefDraft);
+                    if (page) {
+                      props.onAddReference({
+                        label: page.title,
+                        type: 'custom',
+                        href: `/docs/custom/${page.slug}`,
+                      });
+                      setCustomRefDraft('');
+                    }
+                  }}
+                  style={smallButtonStyle}
+                >
+                  Add
+                </button>
+              )}
+            </div>
+          )}
+
+          {/* Full reference list with removal */}
+          <div style={{ marginBottom: 'var(--sp-3)' }}>
+            <label style={{ fontSize: '0.75rem', color: 'var(--fg-dim)', display: 'block', marginBottom: '4px' }}>
+              References
+            </label>
+            <ReferenceLinks
+              references={card.references}
+              pages={pages}
+              customPages={customPages}
+              onRemove={(href) => props.onRemoveReference(href)}
+            />
+          </div>
+
+          {/* Add tag */}
+          <div style={{ marginBottom: 'var(--sp-3)', display: 'flex', gap: '8px' }}>
+            <input
+              type="text"
+              placeholder="Add tag…"
+              value={tagDraft}
+              onChange={(e) => setTagDraft(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter') {
+                  e.stopPropagation();
+                  if (tagDraft.trim()) {
+                    props.onAddTag(tagDraft.trim());
+                    setTagDraft('');
+                  }
+                }
+              }}
+              onClick={(e) => e.stopPropagation()}
+              style={{ ...inputStyle, flex: 1 }}
+            />
+            <button
+              type="button"
+              onClick={(e) => {
+                e.stopPropagation();
+                if (tagDraft.trim()) {
+                  props.onAddTag(tagDraft.trim());
+                  setTagDraft('');
+                }
+              }}
+              style={smallButtonStyle}
+            >
+              Tag
+            </button>
+          </div>
+
+          {/* Comments */}
+          <div>
+            <h5 style={{ margin: '0 0 var(--sp-2) 0', fontSize: '0.85rem', color: 'var(--fg)' }}>Comments</h5>
+            {hasComments ? (
+              <div style={{ marginBottom: 'var(--sp-2)', maxHeight: '200px', overflowY: 'auto' }}>
+                {card.comments.map((comment) => (
+                  <div key={comment.id} style={commentStyle}>
+                    <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '4px' }}>
+                      <span style={{ fontWeight: 500, color: 'var(--fg)' }}>{comment.author}</span>
+                      <button
+                        type="button"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          props.onDeleteComment(comment.id);
+                        }}
+                        title="Delete comment"
+                        style={{
+                          border: 'none',
+                          background: 'transparent',
+                          color: 'var(--muted)',
+                          cursor: 'pointer',
+                          fontSize: '0.7rem',
+                          padding: 0,
+                          lineHeight: 1,
+                        }}
+                      >
+                        ✕
+                      </button>
+                    </div>
+                    <div style={{ color: 'var(--fg-dim)', lineHeight: 1.4, fontSize: '0.8rem' }}>{comment.text}</div>
+                    <div style={{ fontSize: '0.65rem', color: 'var(--muted)', marginTop: '4px' }}>
+                      {new Date(comment.createdAt).toLocaleString()}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            ) : (
+              <p style={{ fontSize: '0.8rem', color: 'var(--muted)', fontStyle: 'italic' }}>No comments yet</p>
+            )}
+
+            <div style={{ display: 'flex', gap: '8px' }}>
+              <input
+                type="text"
+                placeholder="Add a comment…"
+                value={commentDraft}
+                onChange={(e) => setCommentDraft(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') {
+                    e.stopPropagation();
+                    if (commentDraft.trim()) {
+                      props.onAddComment(commentDraft.trim());
+                      setCommentDraft('');
+                    }
+                  }
+                }}
+                onClick={(e) => e.stopPropagation()}
+                style={{ ...inputStyle, flex: 1 }}
+              />
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  if (commentDraft.trim()) {
+                    props.onAddComment(commentDraft.trim());
+                    setCommentDraft('');
+                  }
+                }}
+                style={primaryButtonStyle}
+              >
+                Post
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// --- shared styles ---------------------------------------------------------
+
+const badgeStyle: React.CSSProperties = {
+  fontFamily: 'var(--font-mono)',
+  fontSize: '0.65rem',
+  color: 'var(--muted)',
+  background: 'var(--surface-raised)',
+  padding: '2px 6px',
+  borderRadius: 'var(--radius-sm)',
+};
+
+const categoryStyle: React.CSSProperties = {
+  fontSize: '0.7rem',
+  color: 'var(--fg-dim)',
+  background: 'rgba(100,100,100,0.1)',
+  padding: '2px 6px',
+  borderRadius: 'var(--radius-sm)',
+};
+
+const noteStyle: React.CSSProperties = {
+  fontSize: '0.7rem',
+  color: 'var(--accent)',
+  padding: '4px 8px',
+  background: 'rgba(240,160,48,0.08)',
+  borderRadius: 'var(--radius-sm)',
+  borderLeft: '2px solid var(--accent)',
+};
+
+const tagStyle: React.CSSProperties = {
+  fontSize: '0.65rem',
+  padding: '2px 6px',
+  background: 'rgba(100,150,255,0.1)',
+  border: '1px solid rgba(100,150,255,0.3)',
+  borderRadius: 'var(--radius-sm)',
+  cursor: 'pointer',
+};
+
+const inputStyle: React.CSSProperties = {
+  padding: '4px 8px',
+  fontSize: '0.8rem',
+  background: 'var(--surface)',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-sm)',
+  color: 'var(--fg)',
+};
+
+const smallButtonStyle: React.CSSProperties = {
+  padding: '4px 12px',
+  fontSize: '0.8rem',
+  background: 'var(--surface)',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-sm)',
+  cursor: 'pointer',
+  color: 'var(--fg)',
+};
+
+const primaryButtonStyle: React.CSSProperties = {
+  padding: '8px 16px',
+  fontSize: '0.8rem',
+  background: 'var(--accent)',
+  border: 'none',
+  borderRadius: 'var(--radius-sm)',
+  cursor: 'pointer',
+  color: 'var(--surface)',
+};
+
+const commentStyle: React.CSSProperties = {
+  padding: '8px',
+  marginBottom: '8px',
+  background: 'var(--surface-raised)',
+  borderRadius: 'var(--radius-sm)',
+};
diff --git a/apps/docs/src/components/kanban/ReferenceLinks.tsx b/apps/docs/src/components/kanban/ReferenceLinks.tsx
new file mode 100644
index 0000000..b5d85c4
--- /dev/null
+++ b/apps/docs/src/components/kanban/ReferenceLinks.tsx
@@ -0,0 +1,140 @@
+import { Link } from 'react-router-dom';
+import type { DocPage, Reference } from '../../lib/kanbanApi';
+import type { CustomPage } from '../../lib/pagesApi';
+
+interface ReferenceLinksProps {
+  references: Reference[];
+  pages: DocPage[];
+  /** User-created custom pages, used to resolve icons/blurbs for `custom` refs. */
+  customPages?: CustomPage[];
+  /** Compact chips (card footer) vs full rows (expanded card). */
+  compact?: boolean;
+  onRemove?: (href: string) => void;
+}
+
+const TYPE_ICON: Record<Reference['type'], string> = {
+  doc: '◈',
+  custom: '✦',
+  code: '📁',
+  demo: '▶',
+  external: '↗',
+};
+
+/** Build the internal route for a custom page reference. */
+const customHref = (slug: string) => `/docs/custom/${slug}`;
+
+export function ReferenceLinks({ references, pages, customPages, compact, onRemove }: ReferenceLinksProps) {
+  if (references.length === 0) {
+    return compact ? null : (
+      <p style={{ fontSize: '0.75rem', color: 'var(--muted)', fontStyle: 'italic', margin: 0 }}>
+        No references yet.
+      </p>
+    );
+  }
+
+  const pageByPath = new Map(pages.map((p) => [p.path, p]));
+  const customByHref = new Map((customPages ?? []).map((p) => [customHref(p.slug), p]));
+
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '4px' }}>
+      {references.map((r) => {
+        const customPage = customByHref.get(r.href);
+        const icon =
+          r.type === 'doc'
+            ? (pageByPath.get(r.href)?.icon ?? TYPE_ICON.doc)
+            : r.type === 'custom'
+              ? (customPage?.icon ?? TYPE_ICON.custom)
+              : TYPE_ICON[r.type];
+        const inner = (
+          <>
+            <span style={{ opacity: 0.8 }}>{icon}</span> {r.label}
+          </>
+        );
+
+        // `doc` and `custom` references are both internal routes.
+        const isInternal = r.type === 'doc' || r.type === 'custom';
+        const body = isInternal ? (
+          <Link
+            to={r.href}
+            onClick={(e) => e.stopPropagation()}
+            style={chipStyle(r.type, compact)}
+            title={
+              r.type === 'doc'
+                ? (pageByPath.get(r.href)?.blurb ?? r.label)
+                : (customPage?.blurb ?? r.label)
+            }
+          >
+            {inner}
+          </Link>
+        ) : (
+          <a
+            href={r.href}
+            target={r.type === 'external' ? '_blank' : undefined}
+            rel={r.type === 'external' ? 'noreferrer' : undefined}
+            onClick={(e) => e.stopPropagation()}
+            style={chipStyle(r.type, compact)}
+          >
+            {inner}
+          </a>
+        );
+
+        return (
+          <span key={r.href} style={{ display: 'inline-flex', alignItems: 'center' }}>
+            {body}
+            {r.removable && onRemove && (
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onRemove(r.href);
+                }}
+                title="Remove reference"
+                style={{
+                  border: 'none',
+                  background: 'transparent',
+                  color: 'var(--muted)',
+                  cursor: 'pointer',
+                  fontSize: '0.7rem',
+                  padding: '0 2px',
+                  lineHeight: 1,
+                }}
+              >
+                ×
+              </button>
+            )}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+function chipStyle(type: Reference['type'], compact?: boolean): React.CSSProperties {
+  const color =
+    type === 'doc'
+      ? 'var(--cyan)'
+      : type === 'custom'
+        ? 'var(--purple)'
+        : type === 'code'
+          ? 'var(--fg-dim)'
+          : type === 'demo'
+            ? 'var(--accent)'
+            : 'var(--muted)';
+  const accentBorder =
+    type === 'doc' ? 'rgba(100,180,255,0.3)' : type === 'custom' ? 'rgba(167,139,250,0.3)' : 'var(--border)';
+  const accentBg =
+    type === 'doc' ? 'rgba(100,180,255,0.08)' : type === 'custom' ? 'rgba(167,139,250,0.08)' : 'var(--surface-raised)';
+  return {
+    fontSize: compact ? '0.65rem' : '0.72rem',
+    padding: '2px 7px',
+    borderRadius: 'var(--radius-sm)',
+    border: `1px solid ${accentBorder}`,
+    background: accentBg,
+    color,
+    textDecoration: 'none',
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '4px',
+    whiteSpace: 'nowrap',
+  };
+}
diff --git a/apps/docs/src/components/kanban/useKanbanBoard.ts b/apps/docs/src/components/kanban/useKanbanBoard.ts
new file mode 100644
index 0000000..40cb687
--- /dev/null
+++ b/apps/docs/src/components/kanban/useKanbanBoard.ts
@@ -0,0 +1,236 @@
+import { useCallback, useEffect, useState } from 'react';
+import {
+  kanbanApi,
+  type Board,
+  type Column,
+  type DocPage,
+  type ReferenceType,
+} from '../../lib/kanbanApi';
+
+interface UseKanbanBoard {
+  board: Board | null;
+  pages: DocPage[];
+  loading: boolean;
+  /** Last mutation error, if any (cleared on next successful action/reload). */
+  error: string | null;
+  reload: () => Promise<void>;
+  moveCard: (id: string, status: Column) => Promise<void>;
+  addComment: (cardId: string, text: string, author: string) => Promise<void>;
+  deleteComment: (commentId: string, cardId: string) => Promise<void>;
+  addTag: (cardId: string, tag: string) => Promise<void>;
+  removeTag: (cardId: string, tag: string) => Promise<void>;
+  addReference: (
+    cardId: string,
+    ref: { label: string; type: ReferenceType; href: string },
+  ) => Promise<void>;
+  removeReference: (cardId: string, href: string) => Promise<void>;
+  reset: () => Promise<void>;
+}
+
+export function useKanbanBoard(): UseKanbanBoard {
+  const [board, setBoard] = useState<Board | null>(null);
+  const [pages, setPages] = useState<DocPage[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const reload = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const [b, p] = await Promise.all([kanbanApi.getBoard(), kanbanApi.getPages()]);
+      setBoard(b);
+      setPages(p);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Failed to load board');
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  /** Run a mutation, optimistic-local-updating via `apply`, then reconcile. */
+  const run = useCallback(
+    async (
+      apply: () => void,
+      remote: () => Promise<unknown>,
+    ): Promise<void> => {
+      setError(null);
+      apply(); // optimistic local update
+      try {
+        await remote();
+      } catch (e) {
+        setError(e instanceof Error ? e.message : 'Mutation failed');
+        await reload(); // reconcile on failure
+      }
+    },
+    [reload],
+  );
+
+  const moveCard = useCallback(
+    (id: string, status: Column) =>
+      run(
+        () =>
+          setBoard((prev) =>
+            prev
+              ? { ...prev, cards: prev.cards.map((c) => (c.id === id ? { ...c, status } : c)) }
+              : prev,
+          ),
+        () => kanbanApi.moveCard(id, status),
+      ),
+    [run],
+  );
+
+  const addComment = useCallback(
+    async (cardId: string, text: string, author: string) => {
+      setError(null);
+      try {
+        const comment = await kanbanApi.addComment(cardId, text, author);
+        setBoard((prev) =>
+          prev
+            ? {
+                ...prev,
+                cards: prev.cards.map((c) =>
+                  c.id === cardId ? { ...c, comments: [...c.comments, comment] } : c,
+                ),
+              }
+            : prev,
+        );
+      } catch (e) {
+        setError(e instanceof Error ? e.message : 'Failed to add comment');
+      }
+    },
+    [],
+  );
+
+  const deleteComment = useCallback(
+    (commentId: string, cardId: string) =>
+      run(
+        () =>
+          setBoard((prev) =>
+            prev
+              ? {
+                  ...prev,
+                  cards: prev.cards.map((c) =>
+                    c.id === cardId
+                      ? { ...c, comments: c.comments.filter((cm) => cm.id !== commentId) }
+                      : c,
+                  ),
+                }
+              : prev,
+          ),
+        () => kanbanApi.deleteComment(commentId),
+      ),
+    [run],
+  );
+
+  const addTag = useCallback(
+    (cardId: string, tag: string) =>
+      run(
+        () =>
+          setBoard((prev) =>
+            prev
+              ? {
+                  ...prev,
+                  cards: prev.cards.map((c) =>
+                    c.id === cardId && !c.tags.includes(tag)
+                      ? { ...c, tags: [...c.tags, tag] }
+                      : c,
+                  ),
+                }
+              : prev,
+          ),
+        () => kanbanApi.addTag(cardId, tag),
+      ),
+    [run],
+  );
+
+  const removeTag = useCallback(
+    (cardId: string, tag: string) =>
+      run(
+        () =>
+          setBoard((prev) =>
+            prev
+              ? {
+                  ...prev,
+                  cards: prev.cards.map((c) =>
+                    c.id === cardId ? { ...c, tags: c.tags.filter((t) => t !== tag) } : c,
+                  ),
+                }
+              : prev,
+          ),
+        () => kanbanApi.removeTag(cardId, tag),
+      ),
+    [run],
+  );
+
+  const addReference = useCallback(
+    (cardId: string, ref: { label: string; type: ReferenceType; href: string }) =>
+      run(
+        () =>
+          setBoard((prev) =>
+            prev
+              ? {
+                  ...prev,
+                  cards: prev.cards.map((c) =>
+                    c.id === cardId && !c.references.some((r) => r.href === ref.href)
+                      ? { ...c, references: [...c.references, { ...ref, removable: true }] }
+                      : c,
+                  ),
+                }
+              : prev,
+          ),
+        () => kanbanApi.addReference(cardId, ref),
+      ),
+    [run],
+  );
+
+  const removeReference = useCallback(
+    (cardId: string, href: string) =>
+      run(
+        () =>
+          setBoard((prev) =>
+            prev
+              ? {
+                  ...prev,
+                  cards: prev.cards.map((c) =>
+                    c.id === cardId
+                      ? { ...c, references: c.references.filter((r) => r.href !== href) }
+                      : c,
+                  ),
+                }
+              : prev,
+          ),
+        () => kanbanApi.removeReference(cardId, href),
+      ),
+    [run],
+  );
+
+  const reset = useCallback(async () => {
+    setError(null);
+    try {
+      await kanbanApi.reset();
+      await reload();
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Reset failed');
+    }
+  }, [reload]);
+
+  return {
+    board,
+    pages,
+    loading,
+    error,
+    reload,
+    moveCard,
+    addComment,
+    deleteComment,
+    addTag,
+    removeTag,
+    addReference,
+    removeReference,
+    reset,
+  };
+}
diff --git a/apps/docs/src/components/kanban/useOrchestrator.ts b/apps/docs/src/components/kanban/useOrchestrator.ts
new file mode 100644
index 0000000..2a4649e
--- /dev/null
+++ b/apps/docs/src/components/kanban/useOrchestrator.ts
@@ -0,0 +1,226 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  orchestratorApi,
+  type AgentRun,
+  type RunEvent,
+} from '../../lib/orchestratorApi';
+
+/**
+ * Drives the agentic orchestrator from the board UI.
+ *
+ * Holds the latest run per card plus a live, replayable event log for any run
+ * currently being "watched" (typically the expanded card's active run). Live
+ * updates arrive over Server-Sent Events; the board stays fully interactive
+ * while an agent works a card — start, steer, and stop at any time.
+ */
+
+export interface UseOrchestrator {
+  /** Newest run for a card (active if one is running, else the last settled). */
+  runForCard: (cardId: string) => AgentRun | undefined;
+  /** True while a run is actively working the given card. */
+  isRunning: (cardId: string) => boolean;
+  /** All known runs (newest first), for a global activity view. */
+  runs: AgentRun[];
+  /** Watched events keyed by run id (ordered). */
+  eventsForRun: (runId: string) => RunEvent[];
+  /** Load initial state. */
+  reload: () => Promise<void>;
+  loading: boolean;
+  error: string | null;
+  /** Begin a run for a card. Returns the created run. */
+  start: (input: { cardId: string; prompt?: string }) => Promise<AgentRun>;
+  /** Send a steer/follow-up message to an active run. */
+  message: (runId: string, text: string, mode: 'steer' | 'followUp') => Promise<void>;
+  /** Stop an active run. */
+  stop: (runId: string) => Promise<void>;
+  /** Open the live event stream for a run (ref-counted; safe to call repeatedly). */
+  watch: (runId: string) => void;
+  /** Release a watch (ref-counted; closes the stream when the last watcher leaves). */
+  unwatch: (runId: string) => void;
+  /** Remove a settled run from the UI (and reclaim its worktree). */
+  remove: (runId: string) => Promise<void>;
+}
+
+export function useOrchestrator(): UseOrchestrator {
+  const [runs, setRuns] = useState<AgentRun[]>([]);
+  const [eventsByRun, setEventsByRun] = useState<Record<string, RunEvent[]>>({});
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Refcounted EventSource subscriptions + replay cursors, kept in refs so the
+  // SSE callbacks always see fresh state without re-subscribing.
+  const sources = useRef(new Map<string, EventSource>());
+  const refcounts = useRef(new Map<string, number>());
+  const cursors = useRef(new Map<string, number>());
+
+  const reload = useCallback(async () => {
+    setError(null);
+    try {
+      const { runs: list } = await orchestratorApi.listRuns();
+      setRuns(list);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Failed to load runs');
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  const upsertRun = useCallback((run: AgentRun) => {
+    setRuns((prev) => {
+      const next = prev.filter((r) => r.id !== run.id);
+      next.unshift(run);
+      return next;
+    });
+  }, []);
+
+  const appendEvent = useCallback((runId: string, ev: RunEvent) => {
+    setEventsByRun((prev) => {
+      const cur = prev[runId] ?? [];
+      // Dedup by seq when present (history flush vs. live may overlap).
+      if (typeof ev.seq === 'number' && cur.some((e) => e.seq === ev.seq)) return prev;
+      return { ...prev, [runId]: [...cur, ev] };
+    });
+  }, []);
+
+  const start = useCallback(
+    async (input: { cardId: string; prompt?: string }) => {
+      const { run } = await orchestratorApi.startRun(input);
+      upsertRun(run);
+      return run;
+    },
+    [upsertRun],
+  );
+
+  const message = useCallback(
+    async (runId: string, text: string, mode: 'steer' | 'followUp') => {
+      await orchestratorApi.messageRun(runId, text, mode);
+    },
+    [],
+  );
+
+  const stop = useCallback(
+    async (runId: string) => {
+      await orchestratorApi.stopRun(runId);
+    },
+    [],
+  );
+
+  const remove = useCallback(async (runId: string) => {
+    await orchestratorApi.deleteRun(runId);
+    setRuns((prev) => prev.filter((r) => r.id !== runId));
+    setEventsByRun((prev) => {
+      const next = { ...prev };
+      delete next[runId];
+      return next;
+    });
+  }, []);
+
+  /** (Re)open the SSE stream for a run, replaying persisted history first. */
+  const openStream = useCallback(
+    (runId: string) => {
+      if (sources.current.has(runId)) return;
+      const since = cursors.current.get(runId) ?? 0;
+      const es = new EventSource(`/api/orchestrator/runs/${runId}/stream?since=${since}`);
+      sources.current.set(runId, es);
+      es.addEventListener('event', (msg) => {
+        const ev = JSON.parse((msg as MessageEvent).data) as RunEvent;
+        if (typeof ev.seq === 'number') cursors.current.set(runId, ev.seq);
+        appendEvent(runId, ev);
+        // Reflect status changes onto the run record.
+        if (ev.type === 'status') {
+          const status = ev.data.status as AgentRun['status'];
+          setRuns((prev) =>
+            prev.map((r) =>
+              r.id === runId
+                ? {
+                    ...r,
+                    status,
+                    finishedAt: ['completed', 'failed', 'stopped'].includes(status)
+                      ? new Date().toISOString()
+                      : r.finishedAt,
+                  }
+                : r,
+            ),
+          );
+        }
+        if (ev.type === 'done' && typeof ev.data.summary === 'string') {
+          setRuns((prev) =>
+            prev.map((r) => (r.id === runId ? { ...r, summary: ev.data.summary as string } : r)),
+          );
+        }
+      });
+      es.onerror = () => {
+        // EventSource auto-reconnects; nothing to do here.
+      };
+    },
+    [appendEvent],
+  );
+
+  const watch = useCallback(
+    (runId: string) => {
+      const n = (refcounts.current.get(runId) ?? 0) + 1;
+      refcounts.current.set(runId, n);
+      if (n === 1) openStream(runId);
+    },
+    [openStream],
+  );
+
+  const unwatch = useCallback((runId: string) => {
+    const n = (refcounts.current.get(runId) ?? 0) - 1;
+    if (n > 0) {
+      refcounts.current.set(runId, n);
+      return;
+    }
+    refcounts.current.delete(runId);
+    const es = sources.current.get(runId);
+    if (es) {
+      es.close();
+      sources.current.delete(runId);
+    }
+  }, []);
+
+  // Close all streams on unmount.
+  useEffect(() => {
+    return () => {
+      for (const es of sources.current.values()) es.close();
+      sources.current.clear();
+      refcounts.current.clear();
+    };
+  }, []);
+
+  const runForCard = useCallback(
+    (cardId: string) => {
+      const forCard = runs.filter((r) => r.cardId === cardId);
+      const active = forCard.find((r) => r.status === 'running');
+      return active ?? forCard[0];
+    },
+    [runs],
+  );
+
+  const isRunning = useCallback(
+    (cardId: string) => Boolean(runs.find((r) => r.cardId === cardId && r.status === 'running')),
+    [runs],
+  );
+
+  const eventsForRun = useCallback((runId: string) => eventsByRun[runId] ?? [], [eventsByRun]);
+
+  return {
+    runForCard,
+    isRunning,
+    runs,
+    eventsForRun,
+    reload,
+    loading,
+    error,
+    start,
+    message,
+    stop,
+    watch,
+    unwatch,
+    remove,
+  };
+}
diff --git a/apps/docs/src/lib/kanbanApi.ts b/apps/docs/src/lib/kanbanApi.ts
new file mode 100644
index 0000000..e1e55df
--- /dev/null
+++ b/apps/docs/src/lib/kanbanApi.ts
@@ -0,0 +1,125 @@
+/**
+ * Typed client for the @void-nav/api kanban backend.
+ *
+ * In development, requests are proxied to `http://localhost:3001` by the Vite
+ * config (`server.proxy['/api']`), so the docs site and API share one origin.
+ * Keep these types in sync with `apps/api/src/types.ts`.
+ */
+
+export type Column = 'done' | 'in-progress' | 'todo' | 'backlog';
+
+export type ReferenceType = 'doc' | 'code' | 'demo' | 'external' | 'custom';
+
+export interface Reference {
+  label: string;
+  type: ReferenceType;
+  href: string;
+  /** Canonical references come from the seed and cannot be removed by users. */
+  removable: boolean;
+}
+
+export interface Comment {
+  id: string;
+  cardId: string;
+  text: string;
+  author: string;
+  /** Epoch milliseconds. */
+  createdAt: number;
+}
+
+export interface Card {
+  id: string;
+  title: string;
+  description: string;
+  details: string;
+  category: string;
+  files: string | null;
+  notes: string | null;
+  status: Column;
+  sortOrder: number;
+  comments: Comment[];
+  tags: string[];
+  references: Reference[];
+}
+
+export interface Board {
+  cards: Card[];
+  lastUpdated: string;
+}
+
+export interface DocPage {
+  path: string;
+  title: string;
+  icon: string;
+  blurb: string;
+}
+
+const BASE = '/api/kanban';
+
+class ApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+async function req<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE}${path}`, {
+    ...init,
+    headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
+  });
+  if (!res.ok) {
+    let detail = `${res.status} ${res.statusText}`;
+    try {
+      const body = await res.json();
+      if (body?.error) detail = body.error;
+    } catch {
+      /* non-JSON error body; keep status text */
+    }
+    throw new ApiError(detail, res.status);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+
+export const kanbanApi = {
+  getBoard: () => req<Board>('/board'),
+  getPages: () => req<DocPage[]>('/pages'),
+
+  moveCard: (id: string, status: Column) =>
+    req<Card>(`/cards/${id}`, { method: 'PATCH', body: JSON.stringify({ status }) }),
+
+  addComment: (cardId: string, text: string, author: string) =>
+    req<Comment>(`/cards/${cardId}/comments`, {
+      method: 'POST',
+      body: JSON.stringify({ text, author }),
+    }),
+
+  deleteComment: (commentId: string) =>
+    req<void>(`/comments/${commentId}`, { method: 'DELETE' }),
+
+  addTag: (cardId: string, tag: string) =>
+    req<{ cardId: string; tag: string }>(`/cards/${cardId}/tags`, {
+      method: 'POST',
+      body: JSON.stringify({ tag }),
+    }),
+
+  removeTag: (cardId: string, tag: string) =>
+    req<void>(`/cards/${cardId}/tags/${encodeURIComponent(tag)}`, { method: 'DELETE' }),
+
+  addReference: (cardId: string, ref: { label: string; type: ReferenceType; href: string }) =>
+    req<Reference>(`/cards/${cardId}/references`, {
+      method: 'POST',
+      body: JSON.stringify(ref),
+    }),
+
+  removeReference: (cardId: string, href: string) =>
+    req<void>(`/cards/${cardId}/references?href=${encodeURIComponent(href)}`, {
+      method: 'DELETE',
+    }),
+
+  reset: () => req<{ ok: boolean }>('/reset', { method: 'POST' }),
+};
diff --git a/apps/docs/src/lib/orchestratorApi.ts b/apps/docs/src/lib/orchestratorApi.ts
new file mode 100644
index 0000000..d76ef4b
--- /dev/null
+++ b/apps/docs/src/lib/orchestratorApi.ts
@@ -0,0 +1,102 @@
+/**
+ * Typed client for the @void-nav/api orchestrator backend.
+ *
+ * The orchestrator turns the implementation board into an agentic system: each
+ * run hands a kanban card to a `pi` subprocess (running inside an isolated git
+ * worktree) and streams its progress back to the UI. The agent drives the board
+ * and the documentation through the server's internal endpoints, so the board
+ * stays fully interactive and the docs remain the central store of truth.
+ *
+ * Keep these types in sync with `apps/api/src/types.ts`.
+ */
+
+export type RunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'stopped';
+
+export interface AgentRun {
+  id: string;
+  cardId: string;
+  status: RunStatus;
+  useWorktree: boolean;
+  branch: string | null;
+  worktreePath: string | null;
+  prompt: string;
+  summary: string | null;
+  commitSha: string | null;
+  error: string | null;
+  createdAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+}
+
+export type RunEventType =
+  | 'status'
+  | 'text'
+  | 'tool_start'
+  | 'tool_end'
+  | 'log'
+  | 'done'
+  | 'error';
+
+export interface RunEvent {
+  seq?: number;
+  type: RunEventType;
+  data: Record<string, unknown>;
+  createdAt?: string;
+}
+
+const BASE = '/api/orchestrator';
+
+class ApiError extends Error {
+  constructor(message: string, readonly status: number) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+async function req<T>(path: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE}${path}`, {
+    ...init,
+    headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
+  });
+  if (!res.ok) {
+    let detail = `${res.status} ${res.statusText}`;
+    try {
+      const body = await res.json();
+      if (body?.error) detail = body.error;
+    } catch {
+      /* keep status text */
+    }
+    throw new ApiError(detail, res.status);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+
+export interface StartRunInput {
+  cardId: string;
+  prompt?: string;
+  useWorktree?: boolean;
+  cleanupOnFinish?: boolean;
+}
+
+export const orchestratorApi = {
+  listRuns: (cardId?: string) =>
+    req<{ runs: AgentRun[] }>(`/runs${cardId ? `?cardId=${encodeURIComponent(cardId)}` : ''}`),
+
+  getRun: (id: string, since = 0) =>
+    req<{ run: AgentRun; events: RunEvent[] }>(`/runs/${id}?since=${since}`),
+
+  startRun: (input: StartRunInput) =>
+    req<{ run: AgentRun }>(`/runs`, { method: 'POST', body: JSON.stringify(input) }),
+
+  messageRun: (id: string, text: string, mode: 'steer' | 'followUp') =>
+    req<{ ok: boolean }>(`/runs/${id}/message`, {
+      method: 'POST',
+      body: JSON.stringify({ text, mode }),
+    }),
+
+  stopRun: (id: string) =>
+    req<{ ok: boolean }>(`/runs/${id}/stop`, { method: 'POST' }),
+
+  deleteRun: (id: string) => req<void>(`/runs/${id}`, { method: 'DELETE' }),
+};
diff --git a/apps/docs/src/pages/docs/KanbanBoardPage.tsx b/apps/docs/src/pages/docs/KanbanBoardPage.tsx
index 95e39cf..c3c1249 100644
--- a/apps/docs/src/pages/docs/KanbanBoardPage.tsx
+++ b/apps/docs/src/pages/docs/KanbanBoardPage.tsx
@@ -1,625 +1,207 @@
-// @ts-nocheck
-import * as React from 'react';
+import { useMemo, useState } from 'react';
+import { Link } from 'react-router-dom';
+import { useKanbanBoard } from '../../components/kanban/useKanbanBoard';
+import { KanbanCard } from '../../components/kanban/KanbanCard';
+import { useOrchestrator } from '../../components/kanban/useOrchestrator';
+import { useCustomPages } from '../../lib/customPagesStore';
+import type { Card, Column } from '../../lib/kanbanApi';
 
-const LAST_UPDATED = '2025-06-16';
-const STORAGE_KEY = 'void-nav-kanban-data';
+const COLUMNS: { key: Column; title: string; color: string; bgColor: string }[] = [
+  { key: 'done', title: 'DONE', color: 'var(--green)', bgColor: 'rgba(34,197,94,0.05)' },
+  { key: 'in-progress', title: 'IN PROGRESS', color: 'var(--accent)', bgColor: 'rgba(240,160,48,0.05)' },
+  { key: 'todo', title: 'TODO', color: 'var(--red)', bgColor: 'rgba(239,68,68,0.05)' },
+  { key: 'backlog', title: 'BACKLOG', color: 'var(--muted)', bgColor: 'var(--surface-raised)' },
+];
 
-type Column = 'done' | 'in-progress' | 'todo' | 'backlog';
+const CATEGORIES = [
+  'Onboarding', 'Core', 'Content', 'In-System', 'UI', 'Navigation', 'Economy', 'Ships',
+  'Combat', 'NPCs', 'Social', 'Progression', 'Industry', 'Narrative', 'UX', 'Infrastructure',
+];
 
-interface FeatureCard {
-  id: string;
-  title: string;
-  description: string;
-  details: string;
-  category: string;
-  files: string;
-  notes?: string;
-  comments?: Comment[];
-  tags?: string[];
-  status?: string;
-}
-
-interface Comment {
-  id: string;
-  text: string;
-  timestamp: number;
-  author: string;
-}
-
-interface ColumnData {
-  title: string;
-  color: string;
-  bgColor: string;
-  items: FeatureCard[];
-}
-
-// Initial static data
-const INITIAL_COLUMN_DATA: Record<Column, ColumnData> = {
-  done: {
-    title: 'DONE',
-    color: 'var(--green)',
-    bgColor: 'rgba(34,197,94,0.05)',
-    items: [
-      {
-        id: 'G1',
-        title: 'Galaxy Generation & Viewer',
-        description: 'Complete procedural spiral galaxy with core cluster, disk layers, and beam structures. Interactive 3D viewer with star selection, parameter controls, and system connections.',
-        details: 'Fully functional: generates star systems with faction distribution, nearest-neighbor connections, and POI contents. Control panel allows real-time parameter adjustment.',
-        category: 'Onboarding',
-        files: 'apps/game/src/gameplay/galaxy/mod.rs, apps/game/src/gameplay/galaxy/contents.rs',
-      },
-      {
-        id: 'G2',
-        title: 'Character Creation',
-        description: 'Bannerlord-style character generation with name selection, 4 origin archetypes, 3 ship choices, and 5-step backstory questionnaire with stat bonuses.',
-        details: 'Fully functional: complete UI with scrollable panels, stat calculation display, and character draft persistence for campaign.',
-        category: 'Onboarding',
-        files: 'apps/game/src/gameplay/character_creation/mod.rs',
-      },
-      {
-        id: 'G3',
-        title: 'Starting Base Selection',
-        description: 'System selection from outer-galaxy candidates with 3D visualization, POI display, and interactive camera controls.',
-        details: 'Fully functional: shows candidate systems from generated galaxy, with camera focus on selection and system contents preview.',
-        category: 'Onboarding',
-        files: 'apps/game/src/gameplay/starting_base/mod.rs',
-      },
-      {
-        id: 'S1',
-        title: 'Game State Management',
-        description: 'AppState with clean transitions: MainMenu, Galaxy, CharacterCreation, StartingBaseSelection, InGame, Options.',
-        details: 'Fully functional: state system works properly with OnEnter/OnExit/Update schedules for each game phase.',
-        category: 'Core',
-        files: 'apps/game/src/state.rs',
-      },
-      {
-        id: 'S2',
-        title: 'Campaign Persistence',
-        description: 'Galaxy draft, character draft, and starting base selection persisted through game flow.',
-        details: 'Fully functional: Resources carry data through state transitions. New game properly clears previous state.',
-        category: 'Core',
-        files: 'apps/game/src/gameplay/campaign.rs',
-      },
-      {
-        id: 'C1',
-        title: 'Camera System',
-        description: 'Three camera modes: Orbit (for galaxy inspection), Follow (for flight), Cinematic (for docked views).',
-        details: 'Fully functional: orbit camera with mouse controls, camera transitions between modes, proper target following.',
-        category: 'Core',
-        files: 'apps/game/src/camera.rs',
-      },
-      {
-        id: 'P1',
-        title: 'POI Data Structures',
-        description: 'Complete POI type system: 7 planet types, asteroid belts, stations, stargates, anomalies, gas clouds.',
-        details: 'Fully functional: POI generation with orbital mechanics, faction-based biasing, and system context awareness.',
-        category: 'Content',
-        files: 'apps/game/src/gameplay/galaxy/poi.rs, apps/game/src/gameplay/galaxy/contents.rs',
-      },
-    ],
-  },
-  'in-progress': {
-    title: 'IN PROGRESS',
-    color: 'var(--accent)',
-    bgColor: 'rgba(240,160,48,0.05)',
-    items: [
-      {
-        id: 'I1',
-        title: 'In-System Scene Framework',
-        description: 'Scene setup with star, POIs, and player ship. Docked/Flight state management exists.',
-        details: 'Framework exists: scene spawns correctly, state transitions work. But UI is commented out and most gameplay features are stubs.',
-        category: 'In-System',
-        files: 'apps/game/src/gameplay/in_system/mod.rs, apps/game/src/gameplay/in_system/scene.rs',
-        notes: 'UI systems removed/commented. No flight HUD visible to player.',
-      },
-      {
-        id: 'I2',
-        title: 'Target Selection',
-        description: 'Click-to-select POIs (stations, asteroid belts) with selection tracking.',
-        details: 'Framework exists: target selection works, but no gameplay uses the target yet. No distance display or spatial grouping.',
-        category: 'In-System',
-        files: 'apps/game/src/gameplay/in_system/target.rs',
-        notes: 'Selection system works but no gameplay features depend on it yet.',
-      },
-      {
-        id: 'I3',
-        title: 'Operations Framework',
-        description: 'Timed operations system with undock (3s), travel (5s). Framework for docking (4s) and mining (8s).',
-        details: 'Partial: undock and travel work. Docking and mining are skeleton operations marked TODO. No actual gameplay consequences.',
-        category: 'In-System',
-        files: 'apps/game/src/gameplay/in_system/operations.rs, apps/game/src/gameplay/in_system/flight.rs',
-        notes: 'Only undock and approach are implemented. Docking and mining are TODO.',
-      },
-      {
-        id: 'M1',
-        title: 'Basic Movement',
-        description: 'Click-to-move navigation with kinematic steering and velocity integration.',
-        details: 'Partial: ship moves to target position, but no orbital mechanics, no physics-based movement, no collision avoidance.',
-        category: 'In-System',
-        files: 'apps/game/src/gameplay/movement/mod.rs',
-        notes: 'Basic steering works. No actual gameplay uses movement yet.',
-      },
-      {
-        id: 'U1',
-        title: 'Basic UI Shell',
-        description: 'Main menu, galaxy control panel, info panels. Foundation for UI exists.',
-        details: 'Partial: main menu and galaxy UI work. In-game flight UI is commented out. No station mode panel swap.',
-        category: 'UI',
-        files: 'apps/game/src/ui/',
-        notes: 'Flight HUD and station UI are removed/commented in code.',
-      },
-    ],
-  },
-  todo: {
-    title: 'TODO',
-    color: 'var(--red)',
-    bgColor: 'rgba(239,68,68,0.05)',
-    items: [
-      {
-        id: 'I4',
-        title: 'Complete In-System Gameplay',
-        description: 'Docking operation, mining operation with output, cargo collection, station interactions.',
-        details: 'Missing: docking only undocks, mining has no resource output. No station services, no refueling, no repairs.',
-        category: 'In-System',
-        files: 'apps/game/src/gameplay/in_system/operations.rs',
-        notes: 'Docks and mines marked as TODO in operations.rs.',
-      },
-      {
-        id: 'U2',
-        title: 'Flight HUD / In-Game UI',
-        description: 'Target reticle, ship status display, operation progress bars, contextual action buttons.',
-        details: 'Missing: all in-game UI is commented out. Player has no visual feedback during flight.',
-        category: 'UI',
-        files: 'apps/game/src/gameplay/in_system/',
-        notes: 'UI setup and update systems are commented out in mod.rs.',
-      },
-      {
-        id: 'M2',
-        title: 'Star Map Plugin',
-        description: 'Galaxy-scale navigation showing all systems, hyperspace lanes, and current position.',
-        details: 'Missing: plugin structure exists but implementation is empty. No camera, no rendering, no interaction.',
-        category: 'Navigation',
-        files: 'apps/game/src/gameplay/star_map/mod.rs',
-        notes: 'File contains only TODO comments and empty plugin struct.',
-      },
-      {
-        id: 'P2',
-        title: 'Physics & Collision',
-        description: 'Mass-based interactions, collision detection between ships and objects, spatial queries.',
-        details: 'Missing: only basic geometry primitives exist. No collision system, no physics simulation.',
-        category: 'Core',
-        files: 'apps/game/src/gameplay/physics/mod.rs',
-        notes: 'Module exports marker components only. No actual physics systems.',
-      },
-      {
-        id: 'R1',
-        title: 'Resource System',
-        description: 'Ore types, cargo inventory, resource collection during mining.',
-        details: 'Missing: no resource types defined, no inventory system, no cargo hold.',
-        category: 'Economy',
-        files: 'N/A',
-        notes: 'No resource or inventory modules exist in codebase.',
-      },
-      {
-        id: 'E1',
-        title: 'Economy System',
-        description: 'Credits, market prices, trading, station markets.',
-        details: 'Missing: no economy simulation, no pricing, no trade mechanics.',
-        category: 'Economy',
-        files: 'N/A',
-        notes: 'No economy modules exist in codebase.',
-      },
-      {
-        id: 'C2',
-        title: 'Ship Components',
-        description: 'Shields, armor, hull, capacitor, power grid, CPU.',
-        details: 'Missing: ships have no stats beyond position. No component systems.',
-        category: 'Ships',
-        files: 'N/A',
-        notes: 'Ship is just a mesh with position. No stats or systems.',
-      },
-    ],
-  },
-  backlog: {
-    title: 'BACKLOG',
-    color: 'var(--muted)',
-    bgColor: 'var(--surface-raised)',
-    items: [
-      {
-        id: 'C3',
-        title: 'Combat System',
-        description: 'Weapons, damage resolution, shield/armor/hull pools, combat AI, target locking.',
-        details: 'Not started: no weapon systems, no damage calculations, no combat state. FTL-style auto-combat planned.',
-        category: 'Combat',
-        files: 'N/A',
-        notes: 'No combat modules exist. Design specifies FTL-style power allocation combat.',
-      },
-      {
-        id: 'S3',
-        title: 'Multiple Ship Types',
-        description: 'Frigate, hauler, scout, warship, battleship classes with different stats.',
-        details: 'Not started: only generic starter ship mesh exists. No ship catalog or stat variations.',
-        category: 'Ships',
-        files: 'N/A',
-        notes: 'Single cone+box+sphere ship. No classes or variations.',
-      },
-      {
-        id: 'F1',
-        title: 'Module Fitting',
-        description: 'High/Med/Low slots, CPU/PG constraints, module catalog, fitting screen.',
-        details: 'Not started: no fitting system. Design specifies full fitting with drag-and-drop.',
-        category: 'Ships',
-        files: 'N/A',
-        notes: 'Reference: apps/docs/src/prototypes/existing-demos/FittingDemo.tsx',
-      },
-      {
-        id: 'N1',
-        title: 'NPC Ships & AI',
-        description: 'NPC spawning, behavior state machines, ambient traffic, hostile pirates.',
-        details: 'Not started: no NPC entities, no AI systems. Design describes full NPC AI.',
-        category: 'NPCs',
-        files: 'N/A',
-        notes: 'No NPC modules exist in codebase.',
-      },
-      {
-        id: 'Q1',
-        title: 'Quest & Mission System',
-        description: 'NPC agents, mission templates (kill, courier, mining), active mission tracking.',
-        details: 'Not started: no quest system. Design specifies 6 mission types with rewards.',
-        category: 'Content',
-        files: 'N/A',
-        notes: 'Reference: design docs describe faction quests and mission templates.',
-      },
-      {
-        id: 'A1',
-        title: 'Faction System',
-        description: 'Faction standing, loyalty points, reputation effects, faction-controlled space.',
-        details: 'Not started: factions are colors only. No standing or reputation tracking.',
-        category: 'Social',
-        files: 'N/A',
-        notes: 'Factions exist as labels only. No gameplay effects.',
-      },
-      {
-        id: 'W1',
-        title: 'Dynamic World Events',
-        description: 'Random events, anomalies, faction conflicts, world state changes.',
-        details: 'Not started: no event system. Design describes 6 event categories.',
-        category: 'Content',
-        files: 'N/A',
-        notes: 'No world event modules exist.',
-      },
-      {
-        id: 'PR1',
-        title: 'Skill & Progression',
-        description: 'XP awards, skill catalog (Mining, Industry, Trade, Gunnery, Navigation), level 0-5.',
-        details: 'Not started: no XP or skills. Design specifies 5 skills with tier bonuses.',
-        category: 'Progression',
-        files: 'N/A',
-        notes: 'Reference: apps/docs/src/prototypes/existing-demos/ProgressionDemo.tsx',
-      },
-      {
-        id: 'MF1',
-        title: 'Manufacturing',
-        description: 'Blueprints, production jobs, material requirements, output queues.',
-        details: 'Not started: no manufacturing. Design: Ore→Mineral→Component→Module→Ship chain.',
-        category: 'Industry',
-        files: 'N/A',
-        notes: 'Reference: apps/docs/src/prototypes/existing-demos/RefiningDemo.tsx',
-      },
-      {
-        id: 'Z1',
-        title: 'Zora Ship AI',
-        description: 'AI companion with personality, soul depth, tier progression (0-5).',
-        details: 'Not started: no Zora implementation. Design specifies full AI companion system.',
-        category: 'Ships',
-        files: 'N/A',
-        notes: 'Reference: apps/docs/src/prototypes/existing-demos/ZoraDemo.tsx',
-      },
-      {
-        id: 'ST1.1',
-        title: 'Event Logging System',
-        description: 'Track all player actions (mining, trading, combat, exploration) as structured events.',
-        details: 'Missing: no event logging exists. Need event types, event bus, persistence.',
-        category: 'Narrative',
-        files: 'apps/game/src/gameplay/narrative/events.rs',
-        notes: 'Foundation for narrative synthesis. Must capture all player actions.',
-      },
-      {
-        id: 'ST1.2',
-        title: 'Narrative Synthesis Engine',
-        description: 'LLM-based system that weaves events into coherent narrative text.',
-        details: 'Missing: no narrative generation. Need event aggregation, story templates, LLM integration.',
-        category: 'Narrative',
-        files: 'apps/game/src/gameplay/narrative/synthesis.rs',
-        notes: 'Core differentiator. Use Claude API for story generation.',
-      },
-      {
-        id: 'ST1.3',
-        title: 'Campaign History Tracking',
-        description: 'Persistent story log with chapter divisions and key moments.',
-        details: 'Missing: no campaign history. Need timeline, chapter detection, milestone tracking.',
-        category: 'Narrative',
-        files: 'apps/game/src/gameplay/narrative/history.rs',
-        notes: 'Player should access full campaign story at any time.',
-      },
-      {
-        id: 'ST1.4',
-        title: 'Story Log UI',
-        description: 'In-game interface for reading campaign narrative with chapter navigation.',
-        details: 'Missing: no UI for narrative. Need story viewer, chapter list, search.',
-        category: 'Narrative',
-        files: 'apps/game/src/gameplay/narrative/ui.rs',
-        notes: 'Integrates with existing UI system. Should support export/save.',
-      },
-      {
-        id: 'T1',
-        title: 'Tutorial & Onboarding',
-        description: 'Guided mission sequence, skip option, tutorial hints, objective tracking.',
-        details: 'Not started: no tutorial system. New players have no guidance.',
-        category: 'UX',
-        files: 'N/A',
-        notes: 'Design specifies 7-objective tutorial chain.',
-      },
-      {
-        id: 'MP1',
-        title: 'Multiplayer / Backend',
-        description: 'Server auth, multiplayer sessions, cloud persistence.',
-        details: 'Removed: multiplayer services deleted. Game is now single-player only with local persistence.',
-        category: 'Infrastructure',
-        files: 'Removed (services/spacetimedb, services/auth)',
-        notes: 'Multiplayer infrastructure has been removed to focus on single-player experience.',
-      },
-    ],
-  },
-};
-
-const CATEGORIES = ['Onboarding', 'Core', 'Content', 'In-System', 'UI', 'Navigation', 'Economy', 'Ships', 'Combat', 'NPCs', 'Social', 'Progression', 'Industry', 'Narrative', 'UX', 'Infrastructure'];
+const DEFAULT_AUTHOR = 'User';
 
 export function KanbanBoardPage() {
-  // Load saved data from localStorage or use initial data
-  const [columnData, setColumnData] = React.useState<Record<Column, ColumnData>>(() => {
-    const saved = localStorage.getItem(STORAGE_KEY);
-    if (saved) {
-      try {
-        return JSON.parse(saved);
-      } catch (e) {
-        console.error('Failed to parse saved kanban data:', e);
-        return INITIAL_COLUMN_DATA;
+  const {
+    board,
+    pages,
+    loading,
+    error,
+    reload,
+    moveCard,
+    addComment,
+    deleteComment,
+    addTag,
+    removeTag,
+    addReference,
+    removeReference,
+    reset,
+  } = useKanbanBoard();
+
+  // Custom pages power the "custom page reference" picker on each card.
+  const { pages: customPages } = useCustomPages();
+
+  // Agentic orchestrator: launch/watch/steer pi runs from the board.
+  const orch = useOrchestrator();
+
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+
+  const byColumn = useMemo(() => {
+    const groups: Record<Column, Card[]> = { done: [], 'in-progress': [], todo: [], backlog: [] };
+    if (board) {
+      for (const card of board.cards) {
+        groups[card.status].push(card);
       }
     }
-    return INITIAL_COLUMN_DATA;
-  });
+    return groups;
+  }, [board]);
 
-  // Save to localStorage whenever columnData changes
-  React.useEffect(() => {
-    localStorage.setItem(STORAGE_KEY, JSON.stringify(columnData));
-  }, [columnData]);
+  const counts = useMemo(() => {
+    const c = { done: 0, 'in-progress': 0, todo: 0, backlog: 0, total: 0 };
+    if (board) {
+      for (const card of board.cards) {
+        c[card.status]++;
+        c.total++;
+      }
+    }
+    return c;
+  }, [board]);
 
-  // Expanded card state
-  const [expandedCard, setExpandedCard] = React.useState<string | null>(null);
-
-  // Comment input state
-  const [commentInputs, setCommentInputs] = React.useState<Record<string, string>>({});
-
-  // New tag input state
-  const [tagInputs, setTagInputs] = React.useState<Record<string, string>>({});
-
-  const counts = React.useMemo(() => {
-    return {
-      done: columnData.done.items.length,
-      'in-progress': columnData['in-progress'].items.length,
-      todo: columnData.todo.items.length,
-      backlog: columnData.backlog.items.length,
-      total: Object.values(columnData).reduce((sum, col) => sum + col.items.length, 0),
-    };
-  }, [columnData]);
-
-  const completionRate = React.useMemo(() => {
-    const weighted = counts.done + (counts['in-progress'] * 0.3);
+  const completionRate = useMemo(() => {
+    if (counts.total === 0) return 0;
+    const weighted = counts.done + counts['in-progress'] * 0.3;
     return Math.round((weighted / counts.total) * 100);
   }, [counts]);
 
-  // Move card to different column
-  const moveCard = (cardId: string, fromColumn: Column, toColumn: Column) => {
-    setColumnData(prev => {
-      const newPrev = { ...prev };
-      const cardIndex = newPrev[fromColumn].items.findIndex(c => c.id === cardId);
-      if (cardIndex === -1) return prev;
-
-      const [card] = newPrev[fromColumn].items.splice(cardIndex, 1);
-      newPrev[toColumn].items.push(card);
-      return newPrev;
-    });
-  };
-
-  // Add comment to card
-  const addComment = (cardId: string, text: string) => {
-    if (!text.trim()) return;
-
-    setColumnData(prev => {
-      const newPrev = { ...prev };
-      for (const col of Object.keys(newPrev) as Column[]) {
-        const card = newPrev[col].items.find(c => c.id === cardId);
-        if (card) {
-          if (!card.comments) card.comments = [];
-          card.comments.push({
-            id: `comment-${Date.now()}`,
-            text: text.trim(),
-            timestamp: Date.now(),
-            author: 'User',
-          });
-          break;
-        }
-      }
-      return newPrev;
-    });
-
-    setCommentInputs(prev => ({ ...prev, [cardId]: '' }));
-  };
-
-  // Add tag to card
-  const addTag = (cardId: string, tag: string) => {
-    if (!tag.trim()) return;
-
-    setColumnData(prev => {
-      const newPrev = { ...prev };
-      for (const col of Object.keys(newPrev) as Column[]) {
-        const card = newPrev[col].items.find(c => c.id === cardId);
-        if (card) {
-          if (!card.tags) card.tags = [];
-          if (!card.tags.includes(tag.trim())) {
-            card.tags.push(tag.trim());
-          }
-          break;
-        }
-      }
-      return newPrev;
-    });
-
-    setTagInputs(prev => ({ ...prev, [cardId]: '' }));
-  };
-
-  // Remove tag from card
-  const removeTag = (cardId: string, tagToRemove: string) => {
-    setColumnData(prev => {
-      const newPrev = { ...prev };
-      for (const col of Object.keys(newPrev) as Column[]) {
-        const card = newPrev[col].items.find(c => c.id === cardId);
-        if (card && card.tags) {
-          card.tags = card.tags.filter(t => t !== tagToRemove);
-          break;
-        }
-      }
-      return newPrev;
-    });
-  };
-
-  // Reset to initial data
-  const resetData = () => {
-    if (confirm('Reset all kanban data to defaults? This will delete all comments and tags.')) {
-      setColumnData(INITIAL_COLUMN_DATA);
-      localStorage.removeItem(STORAGE_KEY);
-    }
-  };
-
-  // Export data
-  const exportData = () => {
-    const dataStr = JSON.stringify(columnData, null, 2);
-    const blob = new Blob([dataStr], { type: 'application/json' });
-    const url = URL.createObjectURL(blob);
-    const a = document.createElement('a');
-    a.href = url;
-    a.download = `kanban-export-${new Date().toISOString().split('T')[0]}.json`;
-    a.click();
-    URL.revokeObjectURL(url);
-  };
-
   return (
     <div className="mx-auto max-w-content">
+      {/* Header */}
       <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '8px' }}>
         <h1 style={{ marginBottom: '0' }}>Implementation Board</h1>
-        <div style={{ display: 'flex', gap: 'var(--sp-2)' }}>
-          <button
-            onClick={exportData}
-            style={{
-              padding: '4px 12px',
-              fontSize: '0.8rem',
-              background: 'var(--surface)',
-              border: '1px solid var(--border)',
-              borderRadius: 'var(--radius-sm)',
-              cursor: 'pointer',
-            }}
-          >
-            Export Data
+        <div style={{ display: 'flex', gap: 'var(--sp-2)', alignItems: 'center' }}>
+          <SyncStatus loading={loading} error={error} />
+          <button type="button" onClick={() => void reload()} style={headerButtonStyle}>
+            Reload
           </button>
           <button
-            onClick={resetData}
-            style={{
-              padding: '4px 12px',
-              fontSize: '0.8rem',
-              background: 'var(--surface)',
-              border: '1px solid var(--border)',
-              borderRadius: 'var(--radius-sm)',
-              cursor: 'pointer',
+            type="button"
+            onClick={() => {
+              if (
+                confirm(
+                  'Reset the board? This clears all comments, tags, and user references, and restores cards to their default columns.',
+                )
+              ) {
+                void reset();
+                setExpandedId(null);
+              }
             }}
+            style={headerButtonStyle}
           >
-            Reset Data
+            Reset
           </button>
         </div>
       </div>
       <p style={{ color: 'var(--fg-dim)', fontSize: '0.95rem', maxWidth: '720px' }}>
-        Interactive kanban board. Updated on {LAST_UPDATED}.
-        Click cards to expand for comments and tags. Drag cards or use dropdowns to change status.
-        Data persists in localStorage.
+        Interactive implementation board, backed by{' '}
+        <code style={{ fontSize: '0.85em' }}>apps/api</code> (SQLite). Cards reference the{' '}
+        <Link to="/docs/overview" style={{ color: 'var(--cyan)', textDecoration: 'underline' }}>
+          design docs
+        </Link>{' '}
+        — click a card to comment, tag, move, or add references. Comments persist to the database.
       </p>
 
-      {/* Stats overview */}
-      <div className="mb-6 grid grid-cols-[repeat(auto-fit,minmax(140px,1fr))] gap-4" style={{ marginTop: 'var(--sp-5)' }}>
-        <div className="rounded-xl border border-border bg-surface p-4 max-md:rounded-lg max-md:p-3" style={{ borderTop: '3px solid var(--green)' }}>
-          <div className="font-mono text-[1.4rem] font-bold tabular-nums" style={{ color: 'var(--green)' }}>{counts.done}</div>
-          <div className="mt-1 text-[0.7rem] uppercase tracking-[0.05em] text-muted">Done</div>
+      {/* Error banner */}
+      {error && (
+        <div
+          style={{
+            marginTop: 'var(--sp-4)',
+            padding: '10px 14px',
+            border: '1px solid var(--red)',
+            background: 'rgba(239,68,68,0.08)',
+            color: 'var(--red)',
+            borderRadius: 'var(--radius-sm)',
+            fontSize: '0.85rem',
+          }}
+        >
+          ⚠ {error} — <button onClick={() => void reload()} style={{ background: 'none', border: 'none', color: 'inherit', textDecoration: 'underline', cursor: 'pointer' }}>retry</button>
         </div>
-        <div className="rounded-xl border border-border bg-surface p-4 max-md:rounded-lg max-md:p-3" style={{ borderTop: '3px solid var(--accent)' }}>
-          <div className="font-mono text-[1.4rem] font-bold tabular-nums" style={{ color: 'var(--accent)' }}>{counts['in-progress']}</div>
-          <div className="mt-1 text-[0.7rem] uppercase tracking-[0.05em] text-muted">In Progress</div>
-        </div>
-        <div className="rounded-xl border border-border bg-surface p-4 max-md:rounded-lg max-md:p-3" style={{ borderTop: '3px solid var(--red)' }}>
-          <div className="font-mono text-[1.4rem] font-bold tabular-nums" style={{ color: 'var(--red)' }}>{counts.todo}</div>
-          <div className="mt-1 text-[0.7rem] uppercase tracking-[0.05em] text-muted">Todo</div>
-        </div>
-        <div className="rounded-xl border border-border bg-surface p-4 max-md:rounded-lg max-md:p-3" style={{ borderTop: '3px solid var(--muted)' }}>
-          <div className="font-mono text-[1.4rem] font-bold tabular-nums" style={{ color: 'var(--muted)' }}>{counts.backlog}</div>
-          <div className="mt-1 text-[0.7rem] uppercase tracking-[0.05em] text-muted">Backlog</div>
-        </div>
-      </div>
+      )}
 
-      {/* Overall progress */}
-      <div className="mb-6 rounded-lg border border-border bg-surface p-4 max-md:rounded-lg max-md:p-3">
-        <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--sp-3)', marginBottom: 'var(--sp-2)' }}>
-          <span style={{ fontSize: '0.85rem', color: 'var(--fg)', fontWeight: 500 }}>Overall Implementation Progress</span>
-          <span style={{ marginLeft: 'auto', fontFamily: 'var(--font-mono)', fontSize: '0.85rem', color: 'var(--fg-dim)' }}>
-            {completionRate}%
-          </span>
-        </div>
-        <div style={{
-          width: '100%',
-          height: '8px',
-          borderRadius: '4px',
-          background: 'var(--surface-raised)',
-          overflow: 'hidden',
-        }}>
-          <div style={{
-            width: `${completionRate}%`,
-            height: '100%',
-            borderRadius: '4px',
-            background: completionRate > 50 ? 'var(--green)' : completionRate > 25 ? 'var(--accent)' : 'var(--red)',
-          }} />
-        </div>
-      </div>
+      {/* Loading state */}
+      {loading && !board && (
+        <div style={{ marginTop: 'var(--sp-6)', color: 'var(--muted)', fontSize: '0.9rem' }}>Loading board…</div>
+      )}
 
-      {/* Critical insight banner */}
-      <div className="mb-5 rounded-lg px-5 py-4 text-[0.85rem] leading-[1.5] border border-amber/30 bg-amber/10 text-amber" style={{ maxWidth: '720px' }}>
-        <strong>Current State:</strong> The game has a complete <em>onboarding experience</em> (galaxy → character → base) but lacks a playable game loop.
-        The core systems (mining, trading, combat, economy) are frameworks without gameplay. Most in-System UI is commented out.
-        This reflects a focus on foundational architecture before gameplay implementation.
-      </div>
+      {board && (
+        <>
+          {/* Stats */}
+          <div
+            className="grid gap-4"
+            style={{
+              marginTop: 'var(--sp-5)',
+              gridTemplateColumns: 'repeat(auto-fit, minmax(140px, 1fr))',
+            }}
+          >
+            {COLUMNS.map((col) => (
+              <StatCard key={col.key} label={col.title} value={counts[col.key]} color={col.color} />
+            ))}
+          </div>
 
-      {/* Kanban board */}
-      <div style={{ marginTop: 'var(--sp-6)' }}>
-        <div style={{
-          display: 'grid',
-          gridTemplateColumns: 'repeat(4, minmax(280px, 1fr))',
-          gap: 'var(--sp-4)',
-          overflowX: 'auto',
-          paddingBottom: 'var(--sp-4)',
-        }}>
-          {(Object.keys(columnData) as Column[]).map((columnKey) => {
-            const column = columnData[columnKey];
-            return (
+          {/* Progress */}
+          <div style={{ marginTop: 'var(--sp-4)', marginBottom: 'var(--sp-4)', padding: 'var(--sp-4)', border: '1px solid var(--border)', background: 'var(--surface)', borderRadius: 'var(--radius-lg)' }}>
+            <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--sp-3)', marginBottom: 'var(--sp-2)' }}>
+              <span style={{ fontSize: '0.85rem', color: 'var(--fg)', fontWeight: 500 }}>Overall Implementation Progress</span>
+              <span style={{ marginLeft: 'auto', fontFamily: 'var(--font-mono)', fontSize: '0.85rem', color: 'var(--fg-dim)' }}>
+                {completionRate}%
+              </span>
+            </div>
+            <div style={{ width: '100%', height: '8px', borderRadius: '4px', background: 'var(--surface-raised)', overflow: 'hidden' }}>
               <div
-                key={columnKey}
                 style={{
-                  background: column.bgColor,
+                  width: `${completionRate}%`,
+                  height: '100%',
+                  borderRadius: '4px',
+                  background: completionRate > 50 ? 'var(--green)' : completionRate > 25 ? 'var(--accent)' : 'var(--red)',
+                }}
+              />
+            </div>
+          </div>
+
+          {/* Insight */}
+          <div
+            style={{
+              maxWidth: '720px',
+              marginBottom: 'var(--sp-5)',
+              padding: '14px 20px',
+              border: '1px solid rgba(245,158,11,0.3)',
+              background: 'rgba(245,158,11,0.1)',
+              color: 'var(--amber, #f59e0b)',
+              borderRadius: 'var(--radius-md)',
+              fontSize: '0.85rem',
+              lineHeight: 1.5,
+            }}
+          >
+            <strong>Current state:</strong> complete onboarding (galaxy → character → base) plus built-but-unbacked
+            frameworks for NPC AI, narrative event logging/history, and in-system contextual actions. Still missing the
+            playable loop: no damage/combat resolution, no resources/cargo, no economy, no disk persistence. See the{' '}
+            <Link to="/docs/roadmap" style={{ color: 'inherit', textDecoration: 'underline' }}>Roadmap</Link> and{' '}
+            <Link to="/docs/gap-analysis" style={{ color: 'inherit', textDecoration: 'underline' }}>Gap Analysis</Link>.
+          </div>
+
+          {/* Board */}
+          <div
+            style={{
+              display: 'grid',
+              gridTemplateColumns: 'repeat(4, minmax(280px, 1fr))',
+              gap: 'var(--sp-4)',
+              overflowX: 'auto',
+              paddingBottom: 'var(--sp-4)',
+            }}
+          >
+            {COLUMNS.map((col) => (
+              <div
+                key={col.key}
+                style={{
+                  background: col.bgColor,
                   borderRadius: 'var(--radius-md)',
                   padding: 'var(--sp-3)',
                   border: '1px solid var(--border)',
@@ -628,331 +210,105 @@ export function KanbanBoardPage() {
                   flexDirection: 'column',
                 }}
               >
-                {/* Column header */}
-                <div style={{
-                  display: 'flex',
-                  alignItems: 'center',
-                  gap: 'var(--sp-2)',
-                  marginBottom: 'var(--sp-3)',
-                  paddingBottom: 'var(--sp-2)',
-                  borderBottom: '2px solid var(--border)',
-                }}>
-                  <div style={{
-                    width: '10px',
-                    height: '10px',
-                    borderRadius: '50%',
-                    background: column.color,
-                    boxShadow: `0 0 8px ${column.color}66`,
-                  }} />
-                  <h3 style={{ margin: 0, fontSize: '0.9rem', fontWeight: 600, color: 'var(--fg)' }}>
-                    {column.title}
-                  </h3>
-                  <span style={{
-                    marginLeft: 'auto',
-                    fontFamily: 'var(--font-mono)',
-                    fontSize: '0.75rem',
-                    color: 'var(--muted)',
-                    background: 'var(--surface)',
-                    padding: '2px 8px',
-                    borderRadius: 'var(--radius-pill)',
-                  }}>
-                    {column.items.length}
+                <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--sp-2)', marginBottom: 'var(--sp-3)', paddingBottom: 'var(--sp-2)', borderBottom: '2px solid var(--border)' }}>
+                  <span style={{ width: '10px', height: '10px', borderRadius: '50%', background: col.color, boxShadow: `0 0 8px ${col.color}66` }} />
+                  <h3 style={{ margin: 0, fontSize: '0.9rem', fontWeight: 600, color: 'var(--fg)' }}>{col.title}</h3>
+                  <span style={{ marginLeft: 'auto', fontFamily: 'var(--font-mono)', fontSize: '0.75rem', color: 'var(--muted)', background: 'var(--surface)', padding: '2px 8px', borderRadius: 'var(--radius-pill)' }}>
+                    {byColumn[col.key].length}
                   </span>
                 </div>
 
-                {/* Cards */}
                 <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sp-2)', flex: 1 }}>
-                  {column.items.map((item) => {
-                    const isExpanded = expandedCard === item.id;
-                    const hasComments = item.comments && item.comments.length > 0;
-                    const hasTags = item.tags && item.tags.length > 0;
-
-                    return (
-                      <div
-                        key={item.id}
-                        style={{
-                          background: 'var(--surface)',
-                          border: `1px solid ${isExpanded ? 'var(--accent)' : 'var(--border)'}`,
-                          borderRadius: 'var(--radius-md)',
-                          padding: 'var(--sp-3)',
-                          cursor: 'pointer',
-                          transition: 'all 0.15s ease',
-                          boxShadow: isExpanded ? '0 2px 8px rgba(0,0,0,0.1)' : 'none',
-                        }}
-                        onClick={() => setExpandedCard(isExpanded ? null : item.id)}
-                        className="hover:shadow-sm"
-                      >
-                        {/* Card header */}
-                        <div style={{ display: 'flex', alignItems: 'flex-start', gap: 'var(--sp-2)', marginBottom: 'var(--sp-2)' }}>
-                          <span style={{
-                            fontFamily: 'var(--font-mono)',
-                            fontSize: '0.65rem',
-                            color: 'var(--muted)',
-                            background: 'var(--surface-raised)',
-                            padding: '2px 6px',
-                            borderRadius: 'var(--radius-sm)',
-                          }}>
-                            {item.id}
-                          </span>
-                          <span style={{
-                            fontSize: '0.7rem',
-                            color: 'var(--fg-dim)',
-                            background: 'rgba(100,100,100,0.1)',
-                            padding: '2px 6px',
-                            borderRadius: 'var(--radius-sm)',
-                          }}>
-                            {item.category}
-                          </span>
-                          <span style={{ marginLeft: 'auto', fontSize: '0.7rem' }}>
-                            {hasComments && `💬 ${item.comments!.length} `}
-                            {hasTags && `🏷️ ${item.tags!.length}`}
-                          </span>
-                        </div>
-
-                        {/* Card title */}
-                        <h4 style={{ margin: '0 0 var(--sp-1) 0', fontSize: '0.9rem', fontWeight: 500, color: 'var(--fg)' }}>
-                          {item.title}
-                        </h4>
-
-                        {/* Card description */}
-                        <p style={{ margin: '0 0 var(--sp-1) 0', fontSize: '0.8rem', color: 'var(--fg-dim)', lineHeight: '1.4' }}>
-                          {item.description}
-                        </p>
-
-                        {/* Card details */}
-                        <p style={{ margin: '0 0 var(--sp-2) 0', fontSize: '0.75rem', color: 'var(--fg-dim)', lineHeight: '1.4', fontStyle: 'italic' }}>
-                          {item.details}
-                        </p>
-
-                        {/* Card footer */}
-                        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sp-1)' }}>
-                          <div style={{ fontSize: '0.65rem', color: 'var(--muted)', fontFamily: 'var(--font-mono)' }}>
-                            📁 {item.files}
-                          </div>
-                          {item.notes && (
-                            <div style={{
-                              fontSize: '0.7rem',
-                              color: 'var(--accent)',
-                              padding: '4px 8px',
-                              background: 'rgba(240,160,48,0.08)',
-                              borderRadius: 'var(--radius-sm)',
-                              borderLeft: '2px solid var(--accent)',
-                            }}>
-                              💡 {item.notes}
-                            </div>
-                          )}
-
-                          {/* Tags display */}
-                          {hasTags && (
-                            <div style={{ display: 'flex', flexWrap: 'wrap', gap: '4px', marginTop: '4px' }}>
-                              {item.tags!.map(tag => (
-                                <span
-                                  key={tag}
-                                  onClick={(e) => {
-                                    e.stopPropagation();
-                                    removeTag(item.id, tag);
-                                  }}
-                                  style={{
-                                    fontSize: '0.65rem',
-                                    padding: '2px 6px',
-                                    background: 'rgba(100,150,255,0.1)',
-                                    border: '1px solid rgba(100,150,255,0.3)',
-                                    borderRadius: 'var(--radius-sm)',
-                                    cursor: 'pointer',
-                                  }}
-                                  title="Click to remove tag"
-                                >
-                                  🏷️ {tag}
-                                </span>
-                              ))}
-                            </div>
-                          )}
-                        </div>
-
-                        {/* Expanded section */}
-                        {isExpanded && (
-                          <div style={{ marginTop: 'var(--sp-3)', paddingTop: 'var(--sp-3)', borderTop: '1px solid var(--border)' }}>
-                            {/* Status change dropdown */}
-                            <div style={{ marginBottom: 'var(--sp-3)' }}>
-                              <label style={{ fontSize: '0.75rem', color: 'var(--fg-dim)', marginRight: '8px' }}>Move to:</label>
-                              <select
-                                onClick={(e) => e.stopPropagation()}
-                                onChange={(e) => {
-                                  const newColumn = e.target.value as Column;
-                                  if (newColumn !== columnKey) {
-                                    moveCard(item.id, columnKey, newColumn);
-                                  }
-                                }}
-                                value={columnKey}
-                                style={{
-                                  padding: '4px 8px',
-                                  fontSize: '0.8rem',
-                                  background: 'var(--surface)',
-                                  border: '1px solid var(--border)',
-                                  borderRadius: 'var(--radius-sm)',
-                                  color: 'var(--fg)',
-                                }}
-                              >
-                                <option value="done">Done</option>
-                                <option value="in-progress">In Progress</option>
-                                <option value="todo">Todo</option>
-                                <option value="backlog">Backlog</option>
-                              </select>
-                            </div>
-
-                            {/* Add tag */}
-                            <div style={{ marginBottom: 'var(--sp-3)', display: 'flex', gap: '8px' }}>
-                              <input
-                                type="text"
-                                placeholder="Add tag..."
-                                value={tagInputs[item.id] || ''}
-                                onChange={(e) => setTagInputs(prev => ({ ...prev, [item.id]: e.target.value }))}
-                                onKeyDown={(e) => {
-                                  if (e.key === 'Enter') {
-                                    e.stopPropagation();
-                                    addTag(item.id, tagInputs[item.id] || '');
-                                  }
-                                }}
-                                onClick={(e) => e.stopPropagation()}
-                                style={{
-                                  flex: 1,
-                                  padding: '4px 8px',
-                                  fontSize: '0.8rem',
-                                  background: 'var(--surface)',
-                                  border: '1px solid var(--border)',
-                                  borderRadius: 'var(--radius-sm)',
-                                  color: 'var(--fg)',
-                                }}
-                              />
-                              <button
-                                onClick={(e) => {
-                                  e.stopPropagation();
-                                  addTag(item.id, tagInputs[item.id] || '');
-                                }}
-                                style={{
-                                  padding: '4px 12px',
-                                  fontSize: '0.8rem',
-                                  background: 'var(--surface)',
-                                  border: '1px solid var(--border)',
-                                  borderRadius: 'var(--radius-sm)',
-                                  cursor: 'pointer',
-                                }}
-                              >
-                                Add Tag
-                              </button>
-                            </div>
-
-                            {/* Comments section */}
-                            <div>
-                              <h5 style={{ margin: '0 0 var(--sp-2) 0', fontSize: '0.85rem', color: 'var(--fg)' }}>Comments</h5>
-
-                              {/* Existing comments */}
-                              {hasComments ? (
-                                <div style={{ marginBottom: 'var(--sp-2)', maxHeight: '200px', overflowY: 'auto' }}>
-                                  {item.comments!.map(comment => (
-                                    <div
-                                      key={comment.id}
-                                      style={{
-                                        padding: '8px',
-                                        marginBottom: '8px',
-                                        background: 'var(--surface-raised)',
-                                        borderRadius: 'var(--radius-sm)',
-                                        fontSize: '0.8rem',
-                                      }}
-                                    >
-                                      <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: '4px' }}>
-                                        <span style={{ fontWeight: 500, color: 'var(--fg)' }}>{comment.author}</span>
-                                        <span style={{ fontSize: '0.7rem', color: 'var(--muted)' }}>
-                                          {new Date(comment.timestamp).toLocaleString()}
-                                        </span>
-                                      </div>
-                                      <div style={{ color: 'var(--fg-dim)', lineHeight: '1.4' }}>{comment.text}</div>
-                                    </div>
-                                  ))}
-                                </div>
-                              ) : (
-                                <p style={{ fontSize: '0.8rem', color: 'var(--muted)', fontStyle: 'italic' }}>No comments yet</p>
-                              )}
-
-                              {/* Add comment */}
-                              <div style={{ display: 'flex', gap: '8px' }}>
-                                <input
-                                  type="text"
-                                  placeholder="Add a comment..."
-                                  value={commentInputs[item.id] || ''}
-                                  onChange={(e) => setCommentInputs(prev => ({ ...prev, [item.id]: e.target.value }))}
-                                  onKeyDown={(e) => {
-                                    if (e.key === 'Enter') {
-                                      e.stopPropagation();
-                                      addComment(item.id, commentInputs[item.id] || '');
-                                    }
-                                  }}
-                                  onClick={(e) => e.stopPropagation()}
-                                  style={{
-                                    flex: 1,
-                                    padding: '8px',
-                                    fontSize: '0.8rem',
-                                    background: 'var(--surface)',
-                                    border: '1px solid var(--border)',
-                                    borderRadius: 'var(--radius-sm)',
-                                    color: 'var(--fg)',
-                                  }}
-                                />
-                                <button
-                                  onClick={(e) => {
-                                    e.stopPropagation();
-                                    addComment(item.id, commentInputs[item.id] || '');
-                                  }}
-                                  style={{
-                                    padding: '8px 16px',
-                                    fontSize: '0.8rem',
-                                    background: 'var(--accent)',
-                                    border: 'none',
-                                    borderRadius: 'var(--radius-sm)',
-                                    cursor: 'pointer',
-                                    color: 'var(--surface)',
-                                  }}
-                                >
-                                  Post
-                                </button>
-                              </div>
-                            </div>
-                          </div>
-                        )}
-                      </div>
-                    );
-                  })}
+                  {byColumn[col.key].map((card) => (
+                    <KanbanCard
+                      key={card.id}
+                      card={card}
+                      pages={pages}
+                      customPages={customPages}
+                      orch={orch}
+                      expanded={expandedId === card.id}
+                      onToggle={() => setExpandedId(expandedId === card.id ? null : card.id)}
+                      onMove={(status) => void moveCard(card.id, status)}
+                      onAddComment={(text) => void addComment(card.id, text, DEFAULT_AUTHOR)}
+                      onDeleteComment={(commentId) => void deleteComment(commentId, card.id)}
+                      onAddTag={(tag) => void addTag(card.id, tag)}
+                      onRemoveTag={(tag) => void removeTag(card.id, tag)}
+                      onAddReference={(ref) => void addReference(card.id, ref)}
+                      onRemoveReference={(href) => void removeReference(card.id, href)}
+                    />
+                  ))}
                 </div>
               </div>
-            );
-          })}
-        </div>
-      </div>
+            ))}
+          </div>
 
-      {/* Legend */}
-      <div style={{ marginTop: 'var(--sp-6)', padding: 'var(--sp-3)', background: 'var(--surface-raised)', borderRadius: 'var(--radius-md)', border: '1px solid var(--border)' }}>
-        <h4 style={{ margin: '0 0 var(--sp-2) 0', fontSize: '0.85rem', color: 'var(--fg)' }}>Categories</h4>
-        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--sp-2)', fontSize: '0.75rem', color: 'var(--fg-dim)' }}>
-          {CATEGORIES.map(cat => (
-            <span key={cat} style={{
-              padding: '2px 8px',
-              background: 'var(--surface)',
-              borderRadius: 'var(--radius-sm)',
-              border: '1px solid var(--border)',
-            }}>
-              {cat}
-            </span>
-          ))}
-        </div>
-      </div>
-
-      {/* Notes */}
-      <div className="mb-5 rounded-lg px-5 py-4 text-[0.85rem] leading-[1.5] border border-cyan/20 bg-cyan/8 text-cyan" style={{ marginTop: 'var(--sp-6)', maxWidth: '720px' }}>
-        <strong>Implementation note:</strong> This board reflects code analysis of <code>apps/game/</code> as of {LAST_UPDATED}.
-        "Done" means fully functional. "In Progress" means framework exists but gameplay incomplete. "Todo" means next priority items.
-        See <a href="/docs/roadmap" style={{ color: 'var(--cyan)', textDecoration: 'underline' }}>Roadmap</a> for planned phases and
-        <a href="/docs/gameplay" style={{ color: 'var(--cyan)', textDecoration: 'underline' }}> Gameplay</a> for design details.
-      </div>
+          {/* Legend */}
+          <div style={{ marginTop: 'var(--sp-6)', padding: 'var(--sp-3)', background: 'var(--surface-raised)', borderRadius: 'var(--radius-md)', border: '1px solid var(--border)' }}>
+            <h4 style={{ margin: '0 0 var(--sp-2) 0', fontSize: '0.85rem', color: 'var(--fg)' }}>Categories</h4>
+            <div style={{ display: 'flex', flexWrap: 'wrap', gap: 'var(--sp-2)', fontSize: '0.75rem', color: 'var(--fg-dim)' }}>
+              {CATEGORIES.map((cat) => (
+                <span key={cat} style={{ padding: '2px 8px', background: 'var(--surface)', borderRadius: 'var(--radius-sm)', border: '1px solid var(--border)' }}>
+                  {cat}
+                </span>
+              ))}
+            </div>
+          </div>
+        </>
+      )}
     </div>
   );
 }
+
+function StatCard({ label, value, color }: { label: string; value: number; color: string }) {
+  return (
+    <div
+      className="rounded-xl border border-border bg-surface p-4 max-md:rounded-lg max-md:p-3"
+      style={{ borderTop: `3px solid ${color}` }}
+    >
+      <div className="font-mono text-[1.4rem] font-bold tabular-nums" style={{ color }}>
+        {value}
+      </div>
+      <div className="mt-1 text-[0.7rem] uppercase tracking-[0.05em] text-muted">{label}</div>
+    </div>
+  );
+}
+
+function SyncStatus({ loading, error }: { loading: boolean; error: string | null }) {
+  const state = error ? 'error' : loading ? 'loading' : 'synced';
+  const conf = {
+    loading: { label: 'Syncing…', color: 'var(--muted)', tip: 'Talking to the API…' },
+    synced: { label: 'Synced', color: 'var(--green)', tip: 'Changes persist to the SQLite backend.' },
+    error: { label: 'Error', color: 'var(--red)', tip: 'Last request failed — see banner.' },
+  }[state];
+  return (
+    <span title={conf.tip} style={syncPillStyle(conf.color)}>
+      <span style={{ width: '7px', height: '7px', borderRadius: '50%', background: conf.color, boxShadow: `0 0 6px ${conf.color}` }} />
+      {conf.label}
+    </span>
+  );
+}
+
+function syncPillStyle(color: string): React.CSSProperties {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '6px',
+    fontSize: '0.72rem',
+    color,
+    padding: '3px 8px',
+    borderRadius: 'var(--radius-pill)',
+    border: '1px solid var(--border)',
+    background: 'var(--surface)',
+    whiteSpace: 'nowrap',
+  };
+}
+
+const headerButtonStyle: React.CSSProperties = {
+  padding: '4px 12px',
+  fontSize: '0.8rem',
+  background: 'var(--surface)',
+  border: '1px solid var(--border)',
+  borderRadius: 'var(--radius-sm)',
+  cursor: 'pointer',
+  color: 'var(--fg)',
+};