From 8fc44dc2258ffff0da454c246331248f1985493e Mon Sep 17 00:00:00 2001
From: Leon Cheng <leon.cheng@deepl.com>
Date: Fri, 21 Aug 2026 20:21:28 -0400
Subject: [PATCH] feat: add architecture docs center

---
 CONTRIBUTING.md                    |   6 +-
 README.md                          |   6 +-
 client/components/app-shell.tsx    |  10 +-
 client/ds/markdown.tsx             |  20 +++-
 client/lib/docs.ts                 | 126 ++++++++++++++++++++++++++
 client/main.tsx                    |   4 +
 client/pages/DocPage.tsx           |  72 +++++++++++++++
 client/pages/Docs.tsx              | 141 +++++++++++++++++++++++++++++
 client/styles.css                  |  28 ++++++
 docs/architecture.md               | 115 +++++++++++++++++++++++
 docs/contributing/index.html       |   1 +
 scripts/pr-screenshots.ts          |   2 +-
 tests/docs.test.ts                 |  39 ++++++++
 tests/e2e/palette.ui.spec.ts       |   8 ++
 tests/e2e/screenshots.ui.spec.ts   |   6 +-
 tests/e2e/smoke.ui.spec.ts         |  30 +++++-
 tests/fixtures/pr-screenshots.json |   4 +
 tests/pr-screenshots.test.ts       |   5 +
 vite.config.ts                     |  11 ++-
 19 files changed, 619 insertions(+), 15 deletions(-)
 create mode 100644 client/lib/docs.ts
 create mode 100644 client/pages/DocPage.tsx
 create mode 100644 client/pages/Docs.tsx
 create mode 100644 docs/architecture.md
 create mode 100644 tests/docs.test.ts

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 29ff0500..87dc449c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,8 @@ Thank you for improving custom-dca-opencode. This guide covers the repository's
 development workflow and the checks that pull requests must pass.
 
 Use the self-contained [visual reading index](docs/contributing/index.html) to choose a
-contributor pathway, or continue here for the canonical workflow.
+contributor pathway, open `/docs` in the running app for the architecture-focused docs center,
+or continue here for the canonical workflow.
 
 ## Before you start
 
@@ -55,6 +56,9 @@ The request path is:
 Browser -> React/Vite SPA -> Express BFF -> opencode serve
 ```
 
+See [docs/architecture.md](docs/architecture.md) for the detailed request and event flows,
+state ownership, safety boundaries, and extension map.
+
 - [`client/`](client/) contains the React SPA and design-system primitives.
 - [`server/`](server/) contains API routes, credentials, directory validation, SSE
   fan-out, local git operations, notifications, and forge integrations.
diff --git a/README.md b/README.md
index 69975352..e8947552 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,8 @@ starts a second OpenCode server; it uses `OPENCODE_URL` from `.env`.
 The OpenCode 1.18.21 compatibility check is recorded in
 [`docs/opencode-1.18.21-api-audit.md`](docs/opencode-1.18.21-api-audit.md).
 See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development and pull request workflow.
-The same contributor material has a themed [visual reading index](docs/contributing/index.html).
+The running app exposes the architecture and canonical guides at `/docs`; the same contributor
+material also has a standalone themed [visual reading index](docs/contributing/index.html).
 
 ### Open on a phone
 
@@ -195,6 +196,9 @@ The BFF exists because: it holds the server credential, fans one upstream SSE st
 to many browser clients, threads `?directory=` per project, and runs the things the
 OpenCode API doesn't expose (git history, forge APIs, notification transport).
 
+See [`docs/architecture.md`](docs/architecture.md) for conversation and event flows, state
+ownership, safety boundaries, and the extension map.
+
 ## Safety
 
 `opencode serve` runs agent tools **directly on the host as your user** — there is no
diff --git a/client/components/app-shell.tsx b/client/components/app-shell.tsx
index 99e1bd97..73fed1f3 100644
--- a/client/components/app-shell.tsx
+++ b/client/components/app-shell.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from "react";
-import { Search, Smartphone } from "lucide-react";
+import { BookOpen, Search, Smartphone } from "lucide-react";
 import { useTheme } from "next-themes";
 import { NavLink, Outlet, useLocation, useNavigate } from "react-router-dom";
 
@@ -93,6 +93,7 @@ export function AppShell() {
     navigation: [
       { id: "home", title: "Home", to: scopedPath("/"), keywords: ["sessions"] },
       { id: "tools", title: "Tools", to: scopedPath("/tools"), keywords: ["mcp", "lsp", "permissions"] },
+      { id: "docs", title: "Docs", to: scopedPath("/docs"), keywords: ["architecture", "contributing", "internals"] },
       {
         id: "notifications",
         title: "Notifications",
@@ -135,7 +136,8 @@ export function AppShell() {
       <div className="flex h-full min-h-0 flex-col" inert={paletteOpen ? true : undefined}>
         <nav className="flex h-11 shrink-0 items-center gap-1 border-b border-[var(--color-border-default)] px-3" aria-label="Main">
           <NavLink to={scopedPath("/")} className="mr-auto text-sm font-bold tracking-tight" data-testid="opencode-nav-home">
-            OpenCode
+            <span className="sm:hidden">OC</span>
+            <span className="hidden sm:inline">OpenCode</span>
           </NavLink>
           <Button
             aria-label="Search commands"
@@ -162,6 +164,7 @@ export function AppShell() {
             <span className="hidden sm:inline">Phone</span>
           </Button>
           {[
+            ["/docs", "Docs"],
             ["/tools", "Tools"],
             ["/settings/notifications", "Notifications"],
             ["/settings", "Settings"],
@@ -179,7 +182,8 @@ export function AppShell() {
                 }
                 data-testid={`opencode-nav-${label.toLowerCase()}`}
               >
-                {label}
+                {label === "Docs" && <BookOpen aria-hidden="true" className="sm:hidden" size={15} />}
+                <span className={label === "Docs" ? "hidden sm:inline" : undefined}>{label}</span>
                 {badged && (
                   <Badge
                     variant="counter"
diff --git a/client/ds/markdown.tsx b/client/ds/markdown.tsx
index f50e5547..0ef27a76 100644
--- a/client/ds/markdown.tsx
+++ b/client/ds/markdown.tsx
@@ -87,6 +87,9 @@ export interface MarkdownToHtmlOpts {
    * content built from Slack threads.
    */
   untrusted?: boolean;
+  /** Keep root-relative and hash links in the current tab. Useful for
+   * repository-owned documentation rendered inside the application. */
+  internalLinksInSameTab?: boolean;
 }
 
 /**
@@ -152,9 +155,13 @@ export function markdownToHtml(md: string, opts?: MarkdownToHtmlOpts): string {
     .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (match, text: string, url: string) => {
       if (opts?.untrusted) {
         if (!isSafeHref(url)) return text;
-        return keep(`<a href="${escapeAttribute(url)}" target="_blank" rel="noreferrer">${text}</a>`);
+        const sameTab = opts.internalLinksInSameTab && /^(?:\/|#)/u.test(url.trim());
+        const attributes = sameTab ? "" : ' target="_blank" rel="noreferrer"';
+        return keep(`<a href="${escapeAttribute(url)}"${attributes}>${text}</a>`);
       }
-      return keep(`<a href="${url}" target="_blank" rel="noreferrer">${text}</a>`);
+      const sameTab = opts?.internalLinksInSameTab && /^(?:\/|#)/u.test(url.trim());
+      const attributes = sameTab ? "" : ' target="_blank" rel="noreferrer"';
+      return keep(`<a href="${url}"${attributes}>${text}</a>`);
     })
     // Autolink bare URLs in the remaining plain text — URLs inside code
     // or already-emitted links are stashed as tokens, so they're immune.
@@ -199,10 +206,15 @@ interface MarkdownProps {
   /** Escape raw HTML + restrict link protocols. Set for content derived
    * from external users (see markdownToHtml docs). */
   untrusted?: boolean;
+  /** Keep root-relative and hash links in this tab. */
+  internalLinksInSameTab?: boolean;
 }
 
-export const Markdown = memo(function Markdown({ source, className, untrusted }: MarkdownProps) {
-  const html = useMemo(() => markdownToHtml(source, { untrusted }), [source, untrusted]);
+export const Markdown = memo(function Markdown({ source, className, untrusted, internalLinksInSameTab }: MarkdownProps) {
+  const html = useMemo(
+    () => markdownToHtml(source, { untrusted, internalLinksInSameTab }),
+    [source, untrusted, internalLinksInSameTab],
+  );
   if (!source || !source.trim()) return null;
   return (
     <div
diff --git a/client/lib/docs.ts b/client/lib/docs.ts
new file mode 100644
index 00000000..370b6604
--- /dev/null
+++ b/client/lib/docs.ts
@@ -0,0 +1,126 @@
+export type DocCategory = "start" | "architecture" | "operations" | "history";
+
+export interface DocDefinition {
+  slug: string;
+  title: string;
+  description: string;
+  category: DocCategory;
+  sourcePath: string;
+  load: () => Promise<string>;
+}
+
+export const DOC_CATEGORY_LABELS: Record<DocCategory, string> = {
+  start: "Start here",
+  architecture: "Architecture and internals",
+  operations: "Operations",
+  history: "Research and evidence",
+};
+
+export const DOC_CATEGORY_ORDER: DocCategory[] = ["start", "architecture", "operations", "history"];
+
+export const DOCS: DocDefinition[] = [
+  {
+    slug: "architecture",
+    title: "Architecture",
+    description: "Topology, request and event flows, state ownership, safety boundaries, and extension seams.",
+    category: "architecture",
+    sourcePath: "docs/architecture.md",
+    load: () => import("../../docs/architecture.md?raw").then((module) => module.default),
+  },
+  {
+    slug: "contributing",
+    title: "Contributing",
+    description: "Local setup, repository conventions, verification, pull requests, and security-sensitive changes.",
+    category: "start",
+    sourcePath: "CONTRIBUTING.md",
+    load: () => import("../../CONTRIBUTING.md?raw").then((module) => module.default),
+  },
+  {
+    slug: "project-readme",
+    title: "Project orientation",
+    description: "Purpose, features, requirements, deployment entry points, and the public safety model.",
+    category: "start",
+    sourcePath: "README.md",
+    load: () => import("../../README.md?raw").then((module) => module.default),
+  },
+  {
+    slug: "engineering-invariants",
+    title: "Engineering invariants",
+    description: "Verified API traps, durable decisions, and client conventions that protect the implementation.",
+    category: "architecture",
+    sourcePath: "AGENTS.md",
+    load: () => import("../../AGENTS.md?raw").then((module) => module.default),
+  },
+  {
+    slug: "opencode-api-audit",
+    title: "OpenCode API audit",
+    description: "Measured compatibility evidence for the pinned OpenCode server surface.",
+    category: "history",
+    sourcePath: "docs/opencode-1.18.21-api-audit.md",
+    load: () => import("../../docs/opencode-1.18.21-api-audit.md?raw").then((module) => module.default),
+  },
+  {
+    slug: "architecture-research",
+    title: "Architecture research",
+    description: "The investigation, alternatives, and load-bearing conclusions behind the OpenCode migration.",
+    category: "history",
+    sourcePath: "docs/research/README.md",
+    load: () => import("../../docs/research/README.md?raw").then((module) => module.default),
+  },
+  {
+    slug: "deployment",
+    title: "Deployment operations",
+    description: "LaunchAgent installation, logs, upgrades, Tailscale access, and process management.",
+    category: "operations",
+    sourcePath: "deploy/README.md",
+    load: () => import("../../deploy/README.md?raw").then((module) => module.default),
+  },
+  {
+    slug: "reminders",
+    title: "Reminder catalogue",
+    description: "Runtime reminder format, provenance, update policy, and validation guidance.",
+    category: "operations",
+    sourcePath: "reminders/README.md",
+    load: () => import("../../reminders/README.md?raw").then((module) => module.default),
+  },
+];
+
+const DOCS_BY_SLUG = new Map(DOCS.map((doc) => [doc.slug, doc]));
+const DOCS_BY_PATH = new Map(DOCS.map((doc) => [doc.sourcePath, doc]));
+const REPOSITORY_BLOB_URL = "https://github.com/leoncheng57/custom-dca-opencode/blob/main";
+
+export function getDoc(slug: string | undefined): DocDefinition | undefined {
+  return slug ? DOCS_BY_SLUG.get(slug) : undefined;
+}
+
+function normalizePath(path: string): string {
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") parts.pop();
+    else parts.push(part);
+  }
+  return parts.join("/");
+}
+
+function resolveRelativePath(sourcePath: string, href: string): string {
+  const sourceDirectory = sourcePath.includes("/") ? sourcePath.slice(0, sourcePath.lastIndexOf("/")) : "";
+  return normalizePath(`${sourceDirectory}/${href}`);
+}
+
+export function rewriteDocLinks(markdown: string, sourcePath: string): string {
+  return markdown.replace(/(?<!!)\[([^\]]+)\]\(([^)]+)\)/gu, (match, label: string, href: string) => {
+    const trimmedHref = href.trim();
+    if (/^(?:[a-z][a-z\d+.-]*:|\/|#)/iu.test(trimmedHref)) return match;
+
+    const hashIndex = trimmedHref.indexOf("#");
+    const queryIndex = trimmedHref.indexOf("?");
+    const suffixIndex = [hashIndex, queryIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0] ?? -1;
+    const path = suffixIndex >= 0 ? trimmedHref.slice(0, suffixIndex) : trimmedHref;
+    const suffix = suffixIndex >= 0 ? trimmedHref.slice(suffixIndex) : "";
+    const resolvedPath = resolveRelativePath(sourcePath, path);
+    const inAppDoc = DOCS_BY_PATH.get(resolvedPath);
+    const target = inAppDoc ? `/docs/${inAppDoc.slug}${suffix}` : `${REPOSITORY_BLOB_URL}/${resolvedPath}${suffix}`;
+    return `[${label}](${target})`;
+  });
+}
diff --git a/client/main.tsx b/client/main.tsx
index 73a8c97f..f03da266 100644
--- a/client/main.tsx
+++ b/client/main.tsx
@@ -8,6 +8,8 @@ import { ConversationPage } from "./pages/Conversation.js";
 import { SettingsPage } from "./pages/Settings.js";
 import { NotificationsPage } from "./pages/Notifications.js";
 import { ToolsPage } from "./pages/Tools.js";
+import { DocsPage } from "./pages/Docs.js";
+import { DocPage } from "./pages/DocPage.js";
 import { AppShell } from "./components/app-shell.js";
 import { ThemeEffects } from "./components/theme-effects.js";
 import { NotificationCenterProvider } from "./lib/useNotificationCenter.js";
@@ -26,6 +28,8 @@ createRoot(document.getElementById("root")!).render(
               <Route path="/settings" element={<SettingsPage />} />
               <Route path="/settings/notifications" element={<NotificationsPage />} />
               <Route path="/tools" element={<ToolsPage />} />
+              <Route path="/docs" element={<DocsPage />} />
+              <Route path="/docs/:slug" element={<DocPage />} />
             </Route>
           </Routes>
         </NotificationCenterProvider>
diff --git a/client/pages/DocPage.tsx b/client/pages/DocPage.tsx
new file mode 100644
index 00000000..4c9f667b
--- /dev/null
+++ b/client/pages/DocPage.tsx
@@ -0,0 +1,72 @@
+import { useEffect, useState } from "react";
+import { ArrowLeft, ExternalLink } from "lucide-react";
+import { Link, useParams, useSearchParams } from "react-router-dom";
+
+import { Alert } from "../ds/alert.js";
+import { Markdown } from "../ds/markdown.js";
+import { getDoc, rewriteDocLinks } from "../lib/docs.js";
+
+const REPOSITORY_BLOB_URL = "https://github.com/leoncheng57/custom-dca-opencode/blob/main";
+
+export function DocPage() {
+  const { slug } = useParams();
+  const [searchParams] = useSearchParams();
+  const doc = getDoc(slug);
+  const [source, setSource] = useState<string | null>(null);
+  const [error, setError] = useState("");
+  const docsHref = searchParams.size ? `/docs?${searchParams}` : "/docs";
+
+  useEffect(() => {
+    let active = true;
+    setSource(null);
+    setError("");
+    if (!doc) return () => { active = false; };
+    void doc.load()
+      .then((content) => {
+        if (active) setSource(rewriteDocLinks(content.replace(/^# .+\n+/u, ""), doc.sourcePath));
+      })
+      .catch((cause: unknown) => {
+        if (active) setError(cause instanceof Error ? cause.message : "Unable to load this document.");
+      });
+    return () => { active = false; };
+  }, [doc]);
+
+  if (!doc) {
+    return (
+      <main className="mx-auto max-w-3xl p-6" data-testid="opencode-doc">
+        <Alert variant="warning">This document is not in the in-app catalogue.</Alert>
+        <Link to={docsHref} className="mt-4 inline-flex items-center gap-2 text-sm font-semibold text-[var(--color-text-info)] hover:underline" data-testid="opencode-doc-back">
+          <ArrowLeft aria-hidden="true" size={15} /> Back to docs
+        </Link>
+      </main>
+    );
+  }
+
+  return (
+    <main className="h-full overflow-y-auto" data-testid="opencode-doc">
+      <div className="mx-auto max-w-4xl px-5 py-7 sm:px-8 sm:py-10">
+        <header className="mb-8 border-b border-[var(--color-border-default)] pb-6">
+          <div className="flex flex-wrap items-center justify-between gap-3">
+            <Link to={docsHref} className="inline-flex items-center gap-2 text-sm font-semibold text-[var(--color-text-info)] hover:underline" data-testid="opencode-doc-back">
+              <ArrowLeft aria-hidden="true" size={15} /> Docs
+            </Link>
+            <a
+              href={`${REPOSITORY_BLOB_URL}/${doc.sourcePath}`}
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex items-center gap-1.5 font-mono text-[10px] text-[var(--color-text-muted)] hover:underline"
+              data-testid="opencode-doc-source"
+            >
+              {doc.sourcePath} <ExternalLink aria-hidden="true" size={12} />
+            </a>
+          </div>
+          <h1 className="mt-6 text-3xl font-bold tracking-tight sm:text-4xl">{doc.title}</h1>
+          <p className="mt-2 max-w-2xl text-sm leading-relaxed text-[var(--color-text-muted)]">{doc.description}</p>
+        </header>
+        {error && <Alert variant="danger">{error}</Alert>}
+        {!error && source === null && <p className="text-sm text-[var(--color-text-muted)]">Loading document...</p>}
+        {source !== null && <Markdown source={source} internalLinksInSameTab className="docs-markdown" />}
+      </div>
+    </main>
+  );
+}
diff --git a/client/pages/Docs.tsx b/client/pages/Docs.tsx
new file mode 100644
index 00000000..e9e33f1b
--- /dev/null
+++ b/client/pages/Docs.tsx
@@ -0,0 +1,141 @@
+import { ArrowRight, BookOpen, GitBranch, Radio, Server, ShieldCheck } from "lucide-react";
+import { Link, useSearchParams } from "react-router-dom";
+
+import { Badge } from "../ds/badge.js";
+import {
+  DOC_CATEGORY_LABELS,
+  DOC_CATEGORY_ORDER,
+  DOCS,
+  type DocDefinition,
+} from "../lib/docs.js";
+
+function ArchitectureNode({
+  icon: Icon,
+  label,
+  detail,
+  step,
+}: {
+  icon: typeof BookOpen;
+  label: string;
+  detail: string;
+  step: string;
+}) {
+  return (
+    <li className="relative min-w-0 rounded-xl border border-[var(--color-border-default)] bg-[var(--color-background-surface)] p-4 has-shadow-default">
+      <div className="mb-5 flex items-center justify-between gap-3">
+        <span className="flex h-9 w-9 items-center justify-center rounded-lg bg-[var(--color-background-surface-neutral-muted)] text-[var(--color-text-success)]">
+          <Icon aria-hidden="true" size={18} />
+        </span>
+        <span className="font-mono text-[10px] tracking-[0.18em] text-[var(--color-text-muted)]">{step}</span>
+      </div>
+      <strong className="block text-sm">{label}</strong>
+      <span className="mt-1 block text-xs leading-relaxed text-[var(--color-text-muted)]">{detail}</span>
+    </li>
+  );
+}
+
+function DocCard({ doc, href }: { doc: DocDefinition; href: string }) {
+  return (
+    <Link
+      to={href}
+      className="group flex min-h-40 flex-col rounded-xl border border-[var(--color-border-default)] bg-[var(--color-background-surface)] p-4 transition-colors hover:border-[var(--color-border-focus)]"
+      data-testid={`opencode-doc-card-${doc.slug}`}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <span className="font-mono text-[10px] text-[var(--color-text-muted)]">{doc.sourcePath}</span>
+        <ArrowRight aria-hidden="true" className="shrink-0 text-[var(--color-text-muted)] transition-transform group-hover:translate-x-1" size={15} />
+      </div>
+      <h3 className="mt-6 text-base font-semibold group-hover:underline">{doc.title}</h3>
+      <p className="mt-2 text-xs leading-relaxed text-[var(--color-text-muted)]">{doc.description}</p>
+    </Link>
+  );
+}
+
+export function DocsPage() {
+  const [searchParams] = useSearchParams();
+  const scopedHref = (path: string) => {
+    const search = searchParams.toString();
+    return search ? `${path}?${search}` : path;
+  };
+
+  return (
+    <main className="h-full overflow-y-auto" data-testid="opencode-docs">
+      <div className="mx-auto max-w-6xl space-y-14 px-5 py-8 sm:px-8 sm:py-12">
+        <header className="grid gap-8 border-b border-[var(--color-border-default)] pb-10 lg:grid-cols-[minmax(0,1fr)_22rem] lg:items-end">
+          <div>
+            <div className="mb-4 flex items-center gap-2">
+              <Badge variant="info">Engineering docs</Badge>
+              <span className="font-mono text-[10px] uppercase tracking-[0.16em] text-[var(--color-text-muted)]">host-native agent IDE</span>
+            </div>
+            <h1 className="max-w-3xl text-4xl font-bold leading-[0.98] tracking-[-0.04em] sm:text-6xl">
+              Understand the system before changing the seam.
+            </h1>
+            <p className="mt-5 max-w-2xl text-sm leading-relaxed text-[var(--color-text-muted)] sm:text-base">
+              A visual entry point to the architecture, operating boundaries, and evidence behind custom-dca-opencode.
+            </p>
+          </div>
+          <aside className="border-l-4 border-[var(--color-border-focus)] bg-[var(--color-background-surface-neutral-muted)] p-5">
+            <span className="font-mono text-[10px] font-semibold uppercase tracking-[0.16em] text-[var(--color-text-success)]">Source of truth</span>
+            <strong className="mt-2 block text-lg">Markdown stays canonical.</strong>
+            <p className="mt-2 text-xs leading-relaxed text-[var(--color-text-muted)]">
+              These pages render repository-owned documents. Edit the Markdown, not a second copy in the UI.
+            </p>
+          </aside>
+        </header>
+
+        <section aria-labelledby="architecture-heading">
+          <div className="mb-6 flex flex-wrap items-end justify-between gap-4">
+            <div>
+              <span className="font-mono text-[10px] font-semibold uppercase tracking-[0.18em] text-[var(--color-text-success)]">01 / Runtime path</span>
+              <h2 id="architecture-heading" className="mt-2 text-2xl font-bold tracking-tight sm:text-3xl">One server, every project</h2>
+            </div>
+            <Link
+              to={scopedHref("/docs/architecture")}
+              className="flex items-center gap-2 text-sm font-semibold text-[var(--color-text-info)] hover:underline"
+              data-testid="opencode-docs-open-architecture"
+            >
+              Read architecture <ArrowRight aria-hidden="true" size={15} />
+            </Link>
+          </div>
+          <ol className="grid gap-3 md:grid-cols-4" aria-label="Application request path">
+            <ArchitectureNode icon={BookOpen} step="01" label="Browser" detail="Desktop or phone UI. No OpenCode or forge credentials." />
+            <ArchitectureNode icon={GitBranch} step="02" label="React SPA" detail="Sessions, normalized transcripts, settings, and local device state." />
+            <ArchitectureNode icon={Server} step="03" label="Express BFF" detail="Directory validation, credentials, Git, notifications, and SSE fan-out." />
+            <ArchitectureNode icon={Radio} step="04" label="OpenCode server" detail="One host process serving every directory-scoped project and session." />
+          </ol>
+          <div className="mt-3 grid gap-3 md:grid-cols-3">
+            <div className="rounded-lg bg-[var(--color-background-surface-neutral-muted)] p-4">
+              <span className="font-mono text-[10px] uppercase tracking-wide text-[var(--color-text-muted)]">Prompts</span>
+              <p className="mt-1 text-xs leading-relaxed"><code>prompt_async</code> returns immediately; work survives disconnected clients.</p>
+            </div>
+            <div className="rounded-lg bg-[var(--color-background-surface-neutral-muted)] p-4">
+              <span className="font-mono text-[10px] uppercase tracking-wide text-[var(--color-text-muted)]">Events</span>
+              <p className="mt-1 text-xs leading-relaxed"><code>/global/event</code> is fanned out and demultiplexed by directory.</p>
+            </div>
+            <div className="rounded-lg bg-[var(--color-background-surface-neutral-muted)] p-4">
+              <span className="font-mono text-[10px] uppercase tracking-wide text-[var(--color-text-muted)]">Guardrail</span>
+              <p className="mt-1 flex gap-2 text-xs leading-relaxed"><ShieldCheck aria-hidden="true" className="shrink-0 text-[var(--color-text-success)]" size={15} /> Host tools are bounded by permissions and canonicalized workspace roots.</p>
+            </div>
+          </div>
+        </section>
+
+        <section aria-labelledby="library-heading">
+          <span className="font-mono text-[10px] font-semibold uppercase tracking-[0.18em] text-[var(--color-text-success)]">02 / Reading library</span>
+          <h2 id="library-heading" className="mt-2 text-2xl font-bold tracking-tight sm:text-3xl">Follow the evidence trail</h2>
+          <div className="mt-7 space-y-9">
+            {DOC_CATEGORY_ORDER.map((category) => (
+              <div key={category}>
+                <h3 className="mb-3 text-xs font-semibold uppercase tracking-[0.12em] text-[var(--color-text-muted)]">{DOC_CATEGORY_LABELS[category]}</h3>
+                <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+                  {DOCS.filter((doc) => doc.category === category).map((doc) => (
+                    <DocCard key={doc.slug} doc={doc} href={scopedHref(`/docs/${doc.slug}`)} />
+                  ))}
+                </div>
+              </div>
+            ))}
+          </div>
+        </section>
+      </div>
+    </main>
+  );
+}
diff --git a/client/styles.css b/client/styles.css
index 06ab7f4a..19e35105 100644
--- a/client/styles.css
+++ b/client/styles.css
@@ -62,3 +62,31 @@ body {
     transition-duration: 0.01ms !important;
   }
 }
+
+/* Long-form repository docs use the lightweight shared Markdown renderer, but
+ * need a roomier reading scale than transcript prose. */
+.docs-markdown {
+  font-size: 0.9375rem;
+  line-height: 1.75;
+}
+
+.docs-markdown :where(h2) {
+  margin-top: 2.25rem;
+  padding-top: 1.25rem;
+  border-top: 1px solid var(--color-border-default);
+  font-size: 1.5rem;
+  letter-spacing: -0.02em;
+}
+
+.docs-markdown :where(h3) {
+  margin-top: 1.75rem;
+  font-size: 1.15rem;
+}
+
+.docs-markdown :where(p, li) {
+  max-width: 76ch;
+}
+
+.docs-markdown :where(table) {
+  width: 100%;
+}
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..202f7cb5
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,115 @@
+# Architecture
+
+custom-dca-opencode is a host-native web client for one long-lived OpenCode server. It adds a
+mobile-friendly interface, notifications, local Git and forge context, and operational controls
+without replacing the OpenCode CLI.
+
+## System topology
+
+```text
+Browser (desktop or phone over Tailscale)
+  |
+  v
+React 19 + Vite SPA
+  |
+  | same-origin HTTP and SSE
+  v
+Express BFF
+  |-- OpenCode credential, directory validation, SSE fan-out
+  |-- local Git and GitHub/GitLab integrations
+  |-- notification history and ntfy delivery
+  |-- constrained localhost preview proxy
+  |
+  v
+opencode serve :4096
+  |-- one process for every project
+  |-- sessions selected with ?directory=<absolute path>
+  `-- agent tools execute on the host as the current user
+```
+
+The browser never talks directly to OpenCode or a forge. The BFF is the credential and trust
+boundary, and all browser-facing APIs remain same-origin.
+
+## Conversation lifecycle
+
+1. The client selects a project with an absolute `directory` query parameter.
+2. The BFF canonicalizes that path beneath `PROJECTS_DIR` or `OPENCODE_WORKTREE_ROOT`.
+3. The client creates or opens an OpenCode session scoped to that directory.
+4. Before each prompt, the BFF activates the selected Plan or Build policy on the session.
+5. The BFF sends the prompt through `POST /session/{id}/prompt_async` and returns immediately.
+6. OpenCode continues the turn even when every browser disconnects.
+7. One upstream `GET /global/event` stream is fanned out to browsers and demultiplexed by its
+   `directory` field.
+8. Reconnecting clients refetch session state because the classic event stream has no replay
+   cursor.
+
+The blocking `POST /session/{id}/message` route is never used by a UI request because it holds
+the HTTP connection for the entire agent turn.
+
+## Data boundaries
+
+Raw OpenCode response and event shapes cross the application at two deliberate seams:
+
+- `server/opencode/client.ts` is the typed fetch boundary. The live OpenCode `GET /doc` response
+  is the contract when published documentation or SDK types disagree.
+- `client/lib/events.ts` converts OpenCode message parts into backend-neutral
+  `TranscriptEvent` values. Transcript rows do not consume raw OpenCode `Part` objects.
+
+That separation keeps transport churn out of the UI and made the migration from the OpenHands
+backend an adapter rewrite instead of a transcript rebuild.
+
+## State ownership
+
+| State | Owner | Persistence |
+|---|---|---|
+| Sessions, messages, todos, sharing | OpenCode | OpenCode storage |
+| Selected project and device preferences | Browser | `localStorage` |
+| Notification history and resolution | BFF | `.state/notification-history.json` |
+| Auto-permissions toggle | BFF | Memory only; off after restart |
+| Git worktrees and repository state | Host | Local filesystem and Git |
+| Global event subscriptions | BFF | Process lifetime |
+
+## Safety boundary
+
+OpenCode tools run directly on the host as the user running `opencode serve`; there is no
+container boundary. The primary guardrail is the permission policy in `opencode.jsonc`.
+Permission matching is last-match-wins, so broad rules come before specific overrides.
+
+The BFF adds narrower boundaries around browser-controlled input:
+
+- Workspace paths are canonicalized beneath configured roots before filesystem access.
+- OpenCode and forge credentials remain server-side.
+- The preview proxy accepts only explicitly allowlisted localhost ports and strips sensitive
+  request headers.
+- Plan/Build policy activation and prompt submission are serialized per directory and session.
+- Unknown event types are tolerated because the global stream contains events outside the
+  typed client union.
+
+## Extension map
+
+| Change | Start here | Preserve |
+|---|---|---|
+| OpenCode endpoint or payload | `server/opencode/client.ts` | Directory scoping and the live `/doc` contract |
+| Transcript rendering | `client/lib/events.ts` | Backend-neutral `TranscriptEvent` rows |
+| New BFF route | `server/routes/` | Credential isolation and path validation |
+| New page or primitive | `client/pages/`, `client/ds/` | Semantic tokens and deterministic test IDs |
+| Notifications | `server/notifications.ts`, `client/lib/useNotificationCenter.tsx` | Manual-only resolution semantics |
+| Preview behavior | `server/preview.ts` | Port allowlist and stripped credentials |
+| Deployment | `deploy/README.md`, `scripts/launchd.ts` | One supervised BFF and one existing OpenCode server |
+
+## Verification architecture
+
+Vitest covers pure behavior in a Node environment. Playwright builds the production SPA and BFF,
+then runs them against deterministic OpenCode, forge, and preview mocks. End-to-end tests require
+no live agent, model, or credentials.
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run test:e2e
+```
+
+See [Contributing](../CONTRIBUTING.md), the [OpenCode API audit](opencode-1.18.21-api-audit.md),
+and the [architecture research](research/README.md) for the workflow and evidence behind these
+boundaries.
diff --git a/docs/contributing/index.html b/docs/contributing/index.html
index 92b63d28..fbab3272 100644
--- a/docs/contributing/index.html
+++ b/docs/contributing/index.html
@@ -382,6 +382,7 @@ <h2>Follow the evidence trail</h2>
               All links are relative so this index works directly from a local checkout.</p>
           </header>
           <div class="doc-grid">
+            <article class="doc-card"><span class="doc-path">docs/architecture.md</span><h3><a href="../architecture.md">Architecture</a></h3><p>Runtime topology, conversation and event flows, state ownership, safety boundaries, and extension seams.</p></article>
             <article class="doc-card"><span class="doc-path">CONTRIBUTING.md</span><h3><a href="../../CONTRIBUTING.md">Contribution workflow</a></h3><p>Setup, architecture boundaries, conventions, tests, pull requests, screenshots, and security-sensitive changes.</p></article>
             <article class="doc-card"><span class="doc-path">README.md</span><h3><a href="../../README.md">Project orientation</a></h3><p>Purpose, requirements, quick start, feature behavior, architecture, safety model, and PR screenshot contract.</p></article>
             <article class="doc-card"><span class="doc-path">AGENTS.md</span><h3><a href="../../AGENTS.md">Implementation memory</a></h3><p>Verified OpenCode API traps, accepted design decisions, client conventions, and automation constraints.</p></article>
diff --git a/scripts/pr-screenshots.ts b/scripts/pr-screenshots.ts
index 0b193741..177b74c5 100644
--- a/scripts/pr-screenshots.ts
+++ b/scripts/pr-screenshots.ts
@@ -100,7 +100,7 @@ function validateRoute(route: string): void {
 
   const url = new URL(route, "http://screenshot.invalid");
   if (url.origin !== "http://screenshot.invalid") throw new Error(`route ${JSON.stringify(route)} may not specify a scheme or host`);
-  if (![/^\/$/, /^\/settings$/, /^\/settings\/notifications$/, /^\/tools$/, /^\/sessions\/[A-Za-z0-9_-]+$/].some((pattern) => pattern.test(url.pathname))) {
+  if (![/^\/$/, /^\/settings$/, /^\/settings\/notifications$/, /^\/tools$/, /^\/docs(?:\/[A-Za-z0-9_-]+)?$/, /^\/sessions\/[A-Za-z0-9_-]+$/].some((pattern) => pattern.test(url.pathname))) {
     throw new Error(`route ${JSON.stringify(route)} is not a known UI route`);
   }
 }
diff --git a/tests/docs.test.ts b/tests/docs.test.ts
new file mode 100644
index 00000000..b0125b58
--- /dev/null
+++ b/tests/docs.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+
+import { markdownToHtml } from "../client/ds/markdown.js";
+import { DOCS, getDoc, rewriteDocLinks } from "../client/lib/docs.js";
+
+describe("documentation catalogue", () => {
+  it("uses unique slugs and source paths", () => {
+    expect(new Set(DOCS.map((doc) => doc.slug)).size).toBe(DOCS.length);
+    expect(new Set(DOCS.map((doc) => doc.sourcePath)).size).toBe(DOCS.length);
+    expect(getDoc("architecture")?.sourcePath).toBe("docs/architecture.md");
+    expect(getDoc("missing")).toBeUndefined();
+  });
+
+  it("routes catalogued relative links in-app and unknown files to GitHub", () => {
+    const source = [
+      "[Contributing](../CONTRIBUTING.md)",
+      "[Audit](opencode-1.18.21-api-audit.md#result)",
+      "[Implementation](internal/detail.md)",
+      "[External](https://example.com/docs)",
+    ].join("\n");
+
+    expect(rewriteDocLinks(source, "docs/architecture.md")).toBe([
+      "[Contributing](/docs/contributing)",
+      "[Audit](/docs/opencode-api-audit#result)",
+      "[Implementation](https://github.com/leoncheng57/custom-dca-opencode/blob/main/docs/internal/detail.md)",
+      "[External](https://example.com/docs)",
+    ].join("\n"));
+  });
+});
+
+describe("documentation markdown links", () => {
+  it("keeps app links in this tab without changing external link behavior", () => {
+    const html = markdownToHtml("[Architecture](/docs/architecture) [Source](https://example.com)", {
+      internalLinksInSameTab: true,
+    });
+    expect(html).toContain('<a href="/docs/architecture">Architecture</a>');
+    expect(html).toContain('<a href="https://example.com" target="_blank" rel="noreferrer">Source</a>');
+  });
+});
diff --git a/tests/e2e/palette.ui.spec.ts b/tests/e2e/palette.ui.spec.ts
index 8e857363..22c212b6 100644
--- a/tests/e2e/palette.ui.spec.ts
+++ b/tests/e2e/palette.ui.spec.ts
@@ -72,10 +72,18 @@ test.describe("command palette", () => {
     await page.goto("/settings");
     await page.keyboard.press(shortcut);
     await expect(page.getByRole("option", { name: /Home/ })).toBeVisible();
+    await expect(page.getByRole("option", { name: /Docs/ })).toBeVisible();
     await expect(page.getByTestId("opencode-palette-status")).toContainText("Set a project directory");
     await expect(page.locator('[role="option"][data-kind="conversation"]')).toHaveCount(0);
   });
 
+  test("opens the docs center from global navigation", async ({ page }) => {
+    await page.goto(settings);
+    await page.getByTestId("opencode-nav-docs").click();
+    await expect(page).toHaveURL(new RegExp(`/docs\\?directory=${encodeURIComponent(DIR)}`));
+    await expect(page.getByTestId("opencode-docs")).toBeVisible();
+  });
+
   test("runs existing actions", async ({ page }) => {
     await page.goto(settings);
     await page.keyboard.press(shortcut);
diff --git a/tests/e2e/screenshots.ui.spec.ts b/tests/e2e/screenshots.ui.spec.ts
index 478d11d6..7870b413 100644
--- a/tests/e2e/screenshots.ui.spec.ts
+++ b/tests/e2e/screenshots.ui.spec.ts
@@ -33,7 +33,11 @@ test.describe("requested PR screenshots", () => {
               ? "opencode-settings"
               : pathname === "/tools"
                 ? "opencode-tools"
-                : "opencode-hub";
+                : pathname === "/docs"
+                  ? "opencode-docs"
+                  : pathname.startsWith("/docs/")
+                    ? "opencode-doc"
+                    : "opencode-hub";
         await expect(page.getByTestId(stableRoot)).toBeVisible();
         await expect(page.locator("html")).toHaveClass(/dark/);
         await page.addStyleTag({ content: "*, *::before, *::after { animation: none !important; transition: none !important; caret-color: transparent !important; }" });
diff --git a/tests/e2e/smoke.ui.spec.ts b/tests/e2e/smoke.ui.spec.ts
index 89fadc1f..e399f76e 100644
--- a/tests/e2e/smoke.ui.spec.ts
+++ b/tests/e2e/smoke.ui.spec.ts
@@ -1000,6 +1000,30 @@ test.describe("settings and tools UI", () => {
   });
 });
 
+test.describe("engineering docs UI", () => {
+  test("opens the architecture guide from the visual docs center", async ({ page }) => {
+    await page.goto(`/docs?directory=${encodeURIComponent(DIR)}`);
+    await expect(page.getByTestId("opencode-docs")).toContainText("One server, every project");
+    await page.getByTestId("opencode-docs-open-architecture").click();
+    await expect(page).toHaveURL(new RegExp(`/docs/architecture\\?directory=${encodeURIComponent(DIR)}`));
+    await expect(page.getByTestId("opencode-doc")).toContainText("Conversation lifecycle");
+    await expect(page.getByTestId("opencode-doc-source")).toContainText("docs/architecture.md");
+  });
+
+  test("renders an unknown document state", async ({ page }) => {
+    await page.goto("/docs/not-in-the-catalogue");
+    await expect(page.getByTestId("opencode-doc")).toContainText("not in the in-app catalogue");
+  });
+
+  test("fits the docs center without horizontal overflow at 390px", async ({ page }) => {
+    await page.setViewportSize({ width: 390, height: 740 });
+    await page.goto("/docs");
+    await expect(page.getByTestId("opencode-docs")).toBeVisible();
+    const overflow = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth);
+    expect(overflow).toBeLessThanOrEqual(1);
+  });
+});
+
 test.describe("workspace UI", () => {
   const conversation = `/sessions/ses_mock_done?directory=${encodeURIComponent(DIR)}`;
 
@@ -1044,10 +1068,10 @@ test.describe("workspace UI", () => {
     await fetch(`${FORGE_URL}/test/forge-reset`, { method: "POST" });
     await page.setViewportSize({ width: 1280, height: 800 });
     await page.goto(conversation);
-    await page.getByTestId("opencode-inspector-reviews").click();
+    await page.getByTestId("opencode-inspector-reviews").dispatchEvent("click");
     await expect(page.getByTestId("opencode-merge-review")).toBeVisible();
     page.once("dialog", (dialog) => dialog.accept());
-    await page.getByTestId("opencode-merge-review").click();
+    await page.getByTestId("opencode-merge-review").dispatchEvent("click");
     await expect(page.getByTestId("opencode-review-card")).toHaveAttribute("data-state", "merged");
     await expect.poll(async () => (await (await fetch(`${FORGE_URL}/test/forge-state`)).json()).mergeBody).toEqual({ sha: "abc123" });
   });
@@ -1055,7 +1079,7 @@ test.describe("workspace UI", () => {
   test("review card remains width-safe in a mobile cockpit host", async ({ page }) => {
     await page.setViewportSize({ width: 1280, height: 800 });
     await page.goto(conversation);
-    await page.getByTestId("opencode-inspector-reviews").click();
+    await page.getByTestId("opencode-inspector-reviews").dispatchEvent("click");
     await expect(page.getByTestId("opencode-review-card")).toBeVisible();
     await page.setViewportSize({ width: 390, height: 740 });
     await page.getByTestId("opencode-session-inspector").evaluate((element) => {
diff --git a/tests/fixtures/pr-screenshots.json b/tests/fixtures/pr-screenshots.json
index 004d8279..d22d559a 100644
--- a/tests/fixtures/pr-screenshots.json
+++ b/tests/fixtures/pr-screenshots.json
@@ -6,5 +6,9 @@
   {
     "requestedRoute": "/sessions/ses_mock_done?directory=/tmp/mock-project",
     "fullPage": true
+  },
+  {
+    "requestedRoute": "/docs?directory=/tmp/mock-project",
+    "fullPage": true
   }
 ]
diff --git a/tests/pr-screenshots.test.ts b/tests/pr-screenshots.test.ts
index 5cd579ec..3e1d2d14 100644
--- a/tests/pr-screenshots.test.ts
+++ b/tests/pr-screenshots.test.ts
@@ -78,6 +78,11 @@ describe("PR screenshot requests", () => {
     expect(desktop).not.toBe(mobile);
   });
 
+  it("accepts the documentation index and fixed-slug readers", () => {
+    expect(parseScreenshotBlock("```screenshots\n/docs\n/docs/architecture\n```").requests)
+      .toHaveLength(2);
+  });
+
   it.each([
     "https://evil.example/path",
     "//evil.example/path",
diff --git a/vite.config.ts b/vite.config.ts
index 724c995b..69930b99 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -33,7 +33,16 @@ export default defineConfig(() => {
       fs: {
         // Explicit allowlist — never the repo root, which would expose .env
         // through /@fs/. server/opencode/ holds isomorphic client+server code.
-        allow: [resolve(process.cwd(), "client"), resolve(process.cwd(), "server")],
+        allow: [
+          resolve(process.cwd(), "client"),
+          resolve(process.cwd(), "server"),
+          resolve(process.cwd(), "docs"),
+          resolve(process.cwd(), "deploy/README.md"),
+          resolve(process.cwd(), "reminders/README.md"),
+          resolve(process.cwd(), "README.md"),
+          resolve(process.cwd(), "CONTRIBUTING.md"),
+          resolve(process.cwd(), "AGENTS.md"),
+        ],
       },
       proxy: {
         "/api": { target: apiTarget, changeOrigin: true },