viteboard 0.1.0

package/src/shell/Shell.ts

@@ -0,0 +1,2950 @@
+import { Sidebar, type SidebarCallbacks } from "./Sidebar";
+import {
+  ContentApi,
+  filesUnder,
+  firstMarkdownPath,
+  relativePathBetween,
+  type DocsRootSummary,
+  type TreeNode,
+  type WorkspaceState,
+} from "../content/ContentApi";
+import { renderMarkdownInto, currentTheme } from "../content/MarkdownView";
+import { renderMarkdown } from "../content/Markdown";
+import {
+  BoardService,
+  boardIdFromFilePath,
+  resolveBoardIdCandidatesFromDoc,
+  resolveBoardIdFromDoc,
+  type BoardSummary,
+} from "../board/BoardService";
+import { AppController } from "../app/AppController";
+import { DocEditor } from "../editor/DocEditor";
+import { openModal, showToast } from "../ui/Modal";
+import { ICONS } from "../ui/icons";
+
+const THEME_KEY = "docs:theme";
+const SIDEBAR_KEY = "docs:sidebar-collapsed";
+
+type SearchEntry = {
+  title: string;
+  path: string;
+  href: string;
+  section: string;
+  summary: string;
+  body: string;
+  chunks: SearchChunk[];
+  rootId?: string;
+};
+
+type EditableFileRef = {
+  rootId: string;
+  path: string;
+};
+
+type BoardRegion = [number, number, number, number];
+type SearchChunk = {
+  heading: string;
+  text: string;
+  normalized: string;
+  kind: "heading" | "text" | "code" | "board";
+};
+type SearchResult = {
+  entry: SearchEntry;
+  score: number;
+  preview: string;
+  heading: string;
+};
+type CapabilityCartItem = {
+  path: string;
+  displayPath: string;
+  title: string;
+  summary: string;
+  tags: string[];
+  md: string;
+};
+type DesignToken = {
+  group: "Brand Colors" | "Neutral Colors" | "Semantic Colors";
+  name: string;
+  variable: string;
+  value: string;
+  description: string;
+};
+
+const DESIGN_TOKENS: DesignToken[] = [
+  { group: "Brand Colors", name: "100", variable: "--brand-100", value: "#FFFFFF", description: "lightest brand tone" },
+  { group: "Brand Colors", name: "200", variable: "--brand-200", value: "#4DABF7", description: "light azure accent" },
+  { group: "Brand Colors", name: "300", variable: "--brand-300", value: "#0078D4", description: "primary azure blue" },
+  { group: "Brand Colors", name: "400", variable: "--brand-400", value: "#495057", description: "deep slate gray" },
+  { group: "Brand Colors", name: "500", variable: "--brand-500", value: "#0078D4", description: "primary azure blue" },
+  { group: "Brand Colors", name: "600", variable: "--brand-600", value: "#005A9E", description: "darker azure blue" },
+  { group: "Neutral Colors", name: "100", variable: "--neutral-100", value: "#F3F2F1", description: "page background" },
+  { group: "Neutral Colors", name: "200", variable: "--neutral-200", value: "#EAEAEA", description: "subtle surface" },
+  { group: "Neutral Colors", name: "300", variable: "--neutral-300", value: "#D1D1D1", description: "soft border" },
+  { group: "Neutral Colors", name: "400", variable: "--neutral-400", value: "#C8C8C8", description: "medium gray" },
+  { group: "Neutral Colors", name: "500", variable: "--neutral-500", value: "#6E6E6E", description: "neutral mid-tone" },
+  { group: "Neutral Colors", name: "600", variable: "--neutral-600", value: "#7A7A7A", description: "secondary text" },
+  { group: "Neutral Colors", name: "700", variable: "--neutral-700", value: "#495057", description: "deep slate gray" },
+  { group: "Neutral Colors", name: "800", variable: "--neutral-800", value: "#4A4A4A", description: "strong text" },
+  { group: "Neutral Colors", name: "900", variable: "--neutral-900", value: "#0F0F0F", description: "primary text" },
+  { group: "Neutral Colors", name: "000", variable: "--neutral-000", value: "#FFFFFF", description: "white" },
+  { group: "Semantic Colors", name: "Success Main", variable: "--success-main", value: "#28A745", description: "positive actions" },
+  { group: "Semantic Colors", name: "Success Background", variable: "--success-bg", value: "#E6F4EA", description: "positive surface" },
+  { group: "Semantic Colors", name: "Success Text", variable: "--success-text", value: "#1E7E34", description: "positive text" },
+  { group: "Semantic Colors", name: "Warning Main", variable: "--warning-main", value: "#DC2626", description: "warning actions" },
+  { group: "Semantic Colors", name: "Warning Background", variable: "--warning-bg", value: "#FEF2F2", description: "warning surface" },
+  { group: "Semantic Colors", name: "Warning Text", variable: "--warning-text", value: "#FFFFFF", description: "warning text" },
+  { group: "Semantic Colors", name: "Error Main", variable: "--error-main", value: "#CD0000", description: "destructive actions" },
+  { group: "Semantic Colors", name: "Error Background", variable: "--error-bg", value: "#FFE5E5", description: "destructive surface" },
+  { group: "Semantic Colors", name: "Error Text", variable: "--error-text", value: "#B91C1C", description: "destructive text" },
+  { group: "Semantic Colors", name: "Info Main", variable: "--info-main", value: "#1080A6", description: "informational actions" },
+  { group: "Semantic Colors", name: "Info Background", variable: "--info-bg", value: "#E0F7FA", description: "informational surface" },
+  { group: "Semantic Colors", name: "Info Text", variable: "--info-text", value: "#0369A1", description: "informational text" },
+];
+
+/**
+ * Top-level application frame: a VitePress-style sidebar + content pane that
+ * renders docs, the board list, and the capability library, plus a full-screen
+ * board editor mode. Routing is hash-based so the app works as static files.
+ */
+export class Shell {
+  private root: HTMLElement;
+  private layout: HTMLElement;
+  private main: HTMLElement;
+  private topbar: HTMLElement;
+  private contentScroll: HTMLElement;
+  private content: HTMLElement;
+  private sidebar: Sidebar;
+  private searchBtn!: HTMLButtonElement;
+  private cartBtn!: HTMLButtonElement;
+  private editBtn!: HTMLButtonElement;
+  private themeBtn!: HTMLButtonElement;
+  private palette?: HTMLElement;
+  private paletteInput?: HTMLInputElement;
+  private paletteResults?: HTMLElement;
+  private cartPopover?: HTMLElement;
+  private searchIndex: SearchEntry[] = [];
+  private capabilityCart = new Map<string, CapabilityCartItem>();
+  private selectedTokens = new Set<string>();
+  private currentEditableFile?: EditableFileRef;
+  private workspace: WorkspaceState = { projects: [] };
+  private treesByRoot = new Map<string, TreeNode[]>();
+  private treesByProject = new Map<string, TreeNode[]>();
+
+  private cleanup?: () => void;
+  private editor?: AppController;
+  private editorHost?: HTMLElement;
+  private editingId?: string;
+  private lastNonBoardHash = "#/";
+  private lastNonBoardScrollTop = 0;
+  private pendingScrollRestore?: number;
+
+  constructor(root: HTMLElement) {
+    this.root = root;
+    this.applyInitialTheme();
+
+    this.layout = el("div", "shell");
+    const sidebarCallbacks: SidebarCallbacks = {
+      onAddRepo: () => void this.addRepoDocs(),
+      onRemoveProject: (projectId, label) => void this.promptRemoveProject(projectId, label),
+      onCreateDirectory: (rootId, dirPath) => this.promptNewDirectory(rootId, dirPath),
+      onCreateDoc: (rootId, dirPath) => this.promptNewDoc(rootId, dirPath),
+      onCreateBoard: (rootId, dirPath) => this.promptNewBoard(rootId, dirPath),
+      onCreateCapability: (rootId, dirPath) => this.promptNewCapability(rootId, dirPath),
+      onCreateDocsFolder: (projectId, parentPath) => void this.createDocsFolder(projectId, parentPath),
+      onCreateProjectDirectory: (projectId) => void this.promptNewProjectDirectory(projectId),
+      onCreateProjectDoc: (projectId) => void this.promptNewProjectDoc(projectId),
+      onCreateProjectBoard: (projectId) => void this.promptNewProjectBoard(projectId),
+      onRenameDirectory: (rootId, dirPath) => void this.promptRenameDirectory(rootId, dirPath),
+      onDeleteDirectory: (rootId, dirPath) => void this.promptDeleteDirectory(rootId, dirPath),
+      onOpenDoc: (rootId, filePath) => { location.hash = rootDocHash(rootId, filePath); },
+      onEditDoc: (rootId, filePath) => this.openDocEditor({ rootId, path: filePath }),
+      onRenameDoc: (rootId, filePath) => void this.promptRenameDoc(rootId, filePath),
+      onDeleteDoc: (rootId, filePath) => void this.promptDeleteDoc(rootId, filePath),
+      onOpenBoard: (rootId, boardId) => { location.hash = rootBoardHash(rootId, boardId); },
+      onRenameBoard: (rootId, boardId) => void this.promptRenameBoard(rootId, boardId),
+      onDeleteBoard: (rootId, boardId) => void this.promptDeleteBoard(rootId, boardId),
+      onMoveDoc: (rootId, filePath, targetDir) => void this.moveDoc(rootId, filePath, targetDir),
+      onMoveBoard: (rootId, boardId, targetDir) => void this.moveBoard(rootId, boardId, targetDir),
+      onMoveDirectory: (rootId, dirPath, targetDir) => void this.moveDirectory(rootId, dirPath, targetDir),
+    };
+    this.sidebar = new Sidebar(this.layout, sidebarCallbacks);
+    this.main = el("div", "shell-main");
+    this.topbar = this.createTopbar();
+
+    this.contentScroll = el("div", "content-scroll");
+    this.content = el("div", "content");
+    this.contentScroll.appendChild(this.content);
+    this.main.append(this.topbar, this.contentScroll);
+    this.layout.appendChild(this.main);
+    this.root.appendChild(this.layout);
+
+    window.addEventListener("hashchange", () => this.route());
+    window.addEventListener("keydown", (e) => this.handleGlobalKeydown(e));
+    if (localStorage.getItem(SIDEBAR_KEY) === "true") this.setSidebarCollapsed(true);
+    void this.refreshContentIndex().then(() => this.route());
+  }
+
+  // ---------- routing ----------
+
+  private route(opts: { preserveScroll?: boolean } = {}): void {
+    const scrollTop = opts.preserveScroll ? this.contentScroll.scrollTop : this.pendingScrollRestore;
+    this.pendingScrollRestore = undefined;
+    const hash = location.hash || "#/";
+    this.sidebar.setActive(hash);
+    const path = hash.replace(/^#/, "");
+    this.setEditableFile(undefined);
+
+    const boardMatch = path.match(/^\/root\/([^/]+)\/boards\/([^?]+)(?:\?(.*))?$/);
+    if (boardMatch) {
+      this.lastNonBoardScrollTop = this.contentScroll.scrollTop;
+      this.updateTopbarCart(true);
+      this.closeCartPopover();
+      void this.openEditor(
+        decodeURIComponent(boardMatch[1]),
+        decodeURIComponent(boardMatch[2]),
+        parseBoardRegion(boardMatch[3])
+      );
+      return;
+    }
+
+    this.lastNonBoardHash = hash;
+    this.exitEditor();
+    this.layout.style.display = "";
+    this.updateTopbarCart(/\/root\/[^/]+\/boards/.test(path));
+    if (/\/root\/[^/]+\/boards/.test(path)) this.closeCartPopover();
+
+    if (path === "/" || path === "") return void this.renderWorkspaceHome(scrollTop);
+
+    // All /root/ routes need a valid docs root — check once and handle missing
+    const rootRouteMatch = path.match(/^\/root\/([^/]+)\//);
+    if (rootRouteMatch) {
+      const rootId = decodeURIComponent(rootRouteMatch[1]);
+      if (!this.docsRootById(rootId)) {
+        return void this.renderMessage(
+          "Project not found",
+          "This link points to a docs root that isn't in your workspace. Add the project and try again."
+        );
+      }
+    }
+
+    const docMatch = path.match(/^\/root\/([^/]+)\/docs\/(.+)$/);
+    if (docMatch) {
+      return void this.renderDoc(decodeURIComponent(docMatch[1]), decodeURIComponent(docMatch[2]), scrollTop);
+    }
+
+    const boardListMatch = path.match(/^\/root\/([^/]+)\/boards$/);
+    if (boardListMatch) {
+      return void this.renderBoardList(decodeURIComponent(boardListMatch[1]), scrollTop);
+    }
+
+    const projectBoardListMatch = path.match(/^\/project\/([^/]+)\/boards$/);
+    if (projectBoardListMatch) {
+      return void this.renderProjectBoardList(decodeURIComponent(projectBoardListMatch[1]), scrollTop);
+    }
+
+    const capabilitiesOverviewMatch = path.match(/^\/root\/([^/]+)\/capabilities$/);
+    if (capabilitiesOverviewMatch) {
+      return void this.renderCapabilitiesIndex(decodeURIComponent(capabilitiesOverviewMatch[1]), scrollTop);
+    }
+
+    const capabilityDocMatch = path.match(/^\/root\/([^/]+)\/capabilities\/(.+)$/);
+    if (capabilityDocMatch) {
+      return void this.renderCapabilityDoc(
+        decodeURIComponent(capabilityDocMatch[1]),
+        decodeURIComponent(capabilityDocMatch[2]),
+        scrollTop
+      );
+    }
+
+    const projectWikiMatch = path.match(/^\/project\/([^/]+)$/);
+    if (projectWikiMatch) {
+      return void this.renderProjectWiki(decodeURIComponent(projectWikiMatch[1]), scrollTop);
+    }
+
+    const directoryWikiMatch = path.match(/^\/root\/([^/]+)\/directory\/(.+)$/);
+    if (directoryWikiMatch) {
+      const rootId = decodeURIComponent(directoryWikiMatch[1]);
+      const dirPath = decodeURIComponent(directoryWikiMatch[2]);
+      const root = this.docsRootById(rootId);
+      if (root) {
+        // Always pass dirPath through. renderProjectWiki handles all levels.
+        return void this.renderProjectWiki(
+          root.projectId,
+          scrollTop,
+          rootId,
+          dirPath
+        );
+      }
+    }
+
+    if (path === "/tokens") return void this.renderTokenLibrary(scrollTop);
+
+    this.renderMessage("Not found", `No route for ${path}`);
+  }
+
+  // ---------- docs ----------
+
+  private async renderWorkspaceHome(scrollTop?: number): Promise<void> {
+    this.disposeContent();
+    this.content.classList.add("content-wide");
+
+    const page = el("div", "page home-page");
+    const layout = el("div", "home-layout");
+
+    // ════════════════════════════════════════════════════
+    // LEFT — feature guide
+    // ════════════════════════════════════════════════════
+    const guide = el("div", "home-guide");
+
+    const heroTitle = el("h1", "home-hero-title");
+    heroTitle.textContent = "ViteBoard";
+    const heroSub = el("p", "home-hero-sub");
+    heroSub.textContent =
+      "A local-first documentation workspace and infinite-canvas whiteboard. Markdown files, boards, and structured capability specs — plain files on disk, tracked by git.";
+    guide.append(heroTitle, heroSub);
+
+    // Feature sections
+    type FeatureDef = { label: string; kind: string; body: string; items?: string[] };
+    const features: FeatureDef[] = [
+      {
+        label: "Docs", kind: "doc",
+        body: "Markdown files discovered inside any docs/ directory you register. The sidebar builds a live tree from the filesystem — create, rename, and delete docs by right-clicking any directory or file.",
+        items: [
+          "Standard markdown: headings, lists, tables, code blocks, blockquotes, images, links",
+          "Inline board previews via fenced board blocks",
+          "Full-text search across all docs — Cmd K / Ctrl K",
+        ],
+      },
+      {
+        label: "Boards", kind: "board",
+        body: "Infinite-canvas editors saved as JSON files alongside your docs. Open from the sidebar, edit in full-screen, close to return. Boards are small, diffable, and git-native.",
+        items: [
+          "Elements: sticky notes, tasks, shapes, text, arrows, images, frames",
+          "Embed any board region into a doc with a fenced board block",
+          'Click "Copy embed" inside the board editor to get the exact region snippet',
+          "Cmd/Ctrl + scroll to zoom · Shift + scroll to pan",
+        ],
+      },
+      {
+        label: "Capabilities", kind: "capability",
+        body: "Structured markdown specs with YAML frontmatter (title, summary, tags). Build a cart of specs you need for a task and copy them as a single combined prompt.",
+        items: [
+          "Add any spec to the component cart from the sidebar or the capabilities page",
+          "Cart lives in the topbar — click to open, review, or copy the prompt",
+          "Copied prompt includes all selected specs formatted for an LLM",
+        ],
+      },
+      {
+        label: "Search", kind: "",
+        body: "Full-text search across every doc and capability in every registered project. Indexed at startup and refreshed after any content change.",
+        items: [
+          "Cmd K / Ctrl K to open from anywhere",
+          "Ranked by title, path, headings, and body text",
+          "Arrow keys to navigate · Enter to open · Escape to close",
+        ],
+      },
+    ];
+
+    for (const f of features) {
+      const section = el("div", "home-feature");
+      const header = el("div", "home-feature-header");
+      const badge = el("span", `home-feature-badge home-feature-badge-${f.kind || "neutral"}`);
+      badge.textContent = f.label;
+      header.appendChild(badge);
+      section.appendChild(header);
+      const body = el("p", "home-feature-body");
+      body.textContent = f.body;
+      section.appendChild(body);
+      if (f.items) {
+        const list = document.createElement("ul");
+        list.className = "home-feature-list";
+        for (const item of f.items) {
+          const li = document.createElement("li");
+          li.textContent = item;
+          list.appendChild(li);
+        }
+        section.appendChild(list);
+      }
+      guide.appendChild(section);
+    }
+
+    // Keyboard shortcuts
+    const shortcutTitle = el("div", "home-shortcut-title");
+    shortcutTitle.textContent = "Shortcuts & interactions";
+    guide.appendChild(shortcutTitle);
+
+    const shortcuts: [string, string][] = [
+      ["Cmd K / Ctrl K", "Open search"],
+      ["Right-click project header", "Remove from workspace"],
+      ["Right-click directory", "New doc · New board · New capability"],
+      ["Right-click doc", "Open · Edit · Rename · Delete"],
+      ["Right-click board", "Open · Rename · Delete"],
+      ["Cmd/Ctrl + scroll on board", "Zoom"],
+      ["Shift + scroll on board", "Pan"],
+      ["Copy embed (board toolbar)", "Snippet for current view region"],
+    ];
+    const scTable = el("div", "home-shortcut-table");
+    for (const [k, v] of shortcuts) {
+      const row = el("div", "home-shortcut-row");
+      const key = el("kbd", "home-shortcut-key");
+      key.textContent = k;
+      const desc = el("span", "home-shortcut-desc");
+      desc.textContent = v;
+      row.append(key, desc);
+      scTable.appendChild(row);
+    }
+    guide.appendChild(scTable);
+
+    layout.appendChild(guide);
+
+    // ════════════════════════════════════════════════════
+    // RIGHT — workspace panel
+    // ════════════════════════════════════════════════════
+    const panel = el("div", "home-panel");
+
+    const panelHead = el("div", "home-panel-head");
+    const panelTitle = el("div", "home-panel-title");
+    panelTitle.textContent = "Workspace";
+    const addBtn = el("button", "btn primary home-panel-add") as HTMLButtonElement;
+    addBtn.textContent = "+ Add repo";
+    addBtn.addEventListener("click", () => void this.addRepoDocs());
+    panelHead.append(panelTitle, addBtn);
+    panel.appendChild(panelHead);
+
+    if (this.workspace.projects.length === 0) {
+      const empty = el("div", "home-panel-empty");
+      empty.textContent = "No projects yet. Add a project root to discover docs folders.";
+      panel.appendChild(empty);
+    } else {
+      for (const project of this.workspace.projects) {
+        const pc = el("div", "home-panel-project");
+
+        // Project header — links to the project wiki
+        const pcHead = el("a", "home-panel-project-head") as HTMLAnchorElement;
+        pcHead.href = projectWikiHash(project.id);
+        const pcName = el("span", "home-panel-project-name");
+        pcName.textContent = project.label;
+
+        // Aggregate stats
+        const totalDocs = project.docsRoots.reduce((n, r) => {
+          const tree = this.treesByRoot.get(r.id) ?? [];
+          return n + visibleMarkdownFiles(tree).length;
+        }, 0);
+        const totalBoards = project.docsRoots.reduce((n, r) => {
+          const tree = this.treesByRoot.get(r.id) ?? [];
+          return n + allBoardFiles(tree).length;
+        }, 0);
+        const pcMeta = el("span", "home-panel-project-meta");
+        const metaParts: string[] = [`${project.docsRoots.length} root${project.docsRoots.length === 1 ? "" : "s"}`];
+        if (totalDocs) metaParts.push(`${totalDocs} doc${totalDocs === 1 ? "" : "s"}`);
+        if (totalBoards) metaParts.push(`${totalBoards} board${totalBoards === 1 ? "" : "s"}`);
+        pcMeta.textContent = metaParts.join(" · ");
+        pcHead.append(pcName, pcMeta);
+        pc.appendChild(pcHead);
+
+        // Root list — show up to 6, then a "view all" link
+        const MAX_ROOTS = 6;
+        const roots = project.docsRoots;
+        const shown = roots.slice(0, MAX_ROOTS);
+
+        const rootList = el("div", "home-panel-roots");
+        for (const root of shown) {
+          const tree = this.treesByRoot.get(root.id) ?? [];
+          const firstDoc = firstMarkdownPath(visibleDocsTree(tree));
+          const href = firstDoc ? rootDocHash(root.id, firstDoc) : rootBoardsHash(root.id);
+          const row = el("a", "home-panel-root") as HTMLAnchorElement;
+          row.href = href;
+
+          const path = el("span", "home-panel-root-path");
+          path.textContent = root.displayPath;
+
+          const mdCount = visibleMarkdownFiles(tree).length;
+          const boardCount = allBoardFiles(tree).length;
+          if (mdCount || boardCount) {
+            const meta = el("span", "home-panel-root-meta");
+            const p: string[] = [];
+            if (mdCount) p.push(String(mdCount));
+            if (boardCount) p.push(`${boardCount}▦`);
+            meta.textContent = p.join(" · ");
+            row.append(path, meta);
+          } else {
+            row.appendChild(path);
+          }
+          rootList.appendChild(row);
+        }
+
+        if (roots.length > MAX_ROOTS) {
+          const more = el("a", "home-panel-more") as HTMLAnchorElement;
+          more.href = projectWikiHash(project.id);
+          more.textContent = `+ ${roots.length - MAX_ROOTS} more roots`;
+          rootList.appendChild(more);
+        }
+
+        pc.appendChild(rootList);
+        panel.appendChild(pc);
+      }
+    }
+
+    layout.appendChild(panel);
+    page.appendChild(layout);
+
+    this.content.replaceChildren(page);
+    this.contentScroll.scrollTop = scrollTop ?? 0;
+  }
+
+  private async renderProjectWiki(projectId: string, scrollTop?: number, filterRootId?: string, filterDirPath?: string): Promise<void> {
+    this.disposeContent();
+    this.content.classList.add("content-wide");
+
+    const project = this.workspace.projects.find(p => p.id === projectId);
+    if (!project) {
+      this.renderMessage("Project not found", "This project is no longer registered.");
+      return;
+    }
+
+    const page = el("div", "page wiki-page");
+    const isScoped = !!filterRootId;
+    const isFiltered = !!filterDirPath;
+
+    // Determine if filterDirPath is above/at the docs root or inside it
+    let isAboveDocsRoot = false;
+    if (isFiltered && filterRootId) {
+      const root = this.docsRootById(filterRootId);
+      if (root) {
+        isAboveDocsRoot = root.displayPath === filterDirPath
+          || root.displayPath.startsWith(filterDirPath + "/");
+      }
+    }
+
+    // Header with breadcrumbs
+    const wikiHead = el("div", "wiki-head");
+    if (isFiltered && filterRootId) {
+      // Build breadcrumbs: Home > Project > path segments
+      const crumbs: Crumb[] = [{ label: "Home", href: "#/" }];
+      crumbs.push({ label: project.label, href: projectWikiHash(project.id) });
+      const segments = filterDirPath!.split("/").filter(Boolean);
+      for (let i = 0; i < segments.length; i++) {
+        const partial = segments.slice(0, i + 1).join("/");
+        const isLast = i === segments.length - 1;
+        crumbs.push({
+          label: segments[i],
+          href: isLast ? undefined : directoryWikiHash(filterRootId, partial),
+        });
+      }
+      wikiHead.appendChild(makeBreadcrumb(crumbs));
+      const wikiTitle = el("h1", "wiki-title");
+      wikiTitle.textContent = segments[segments.length - 1] || project.label;
+      wikiHead.appendChild(wikiTitle);
+    } else if (isScoped && filterRootId) {
+      const root = this.docsRootById(filterRootId);
+      const crumbs: Crumb[] = [{ label: "Home", href: "#/" }];
+      crumbs.push({ label: project.label, href: projectWikiHash(project.id) });
+      if (root) {
+        const parts = root.displayPath.split("/").filter(Boolean);
+        for (let i = 0; i < parts.length; i++) {
+          const partial = parts.slice(0, i + 1).join("/");
+          const isLast = i === parts.length - 1;
+          crumbs.push({
+            label: parts[i],
+            href: isLast ? undefined : directoryWikiHash(filterRootId, partial),
+          });
+        }
+      }
+      wikiHead.appendChild(makeBreadcrumb(crumbs));
+      const wikiTitle = el("h1", "wiki-title");
+      wikiTitle.textContent = root?.displayPath.split("/").pop() || project.label;
+      wikiHead.appendChild(wikiTitle);
+    } else {
+      wikiHead.appendChild(makeBreadcrumb([
+        { label: "Home", href: "#/" },
+        { label: project.label },
+      ]));
+      const wikiTitle = el("h1", "wiki-title");
+      wikiTitle.textContent = project.label;
+      wikiHead.appendChild(wikiTitle);
+    }
+
+    // Stats bar (only for the full project wiki)
+    if (!isScoped && !isFiltered) {
+      const totalDocs = project.docsRoots.reduce((n, r) => {
+        const tree = this.treesByRoot.get(r.id) ?? [];
+        return n + visibleMarkdownFiles(tree).length;
+      }, 0);
+      const totalBoards = project.docsRoots.reduce((n, r) => {
+        const tree = this.treesByRoot.get(r.id) ?? [];
+        return n + allBoardFiles(tree).length;
+      }, 0);
+      const totalCaps = project.docsRoots.reduce((n, r) => {
+        const tree = this.treesByRoot.get(r.id) ?? [];
+        const capsDir = tree.find(n2 => n2.type === "dir" && n2.name === "capabilities");
+        return n + (capsDir?.type === "dir" ? capsDir.children.filter(f => f.name.endsWith(".md")).length : 0);
+      }, 0);
+
+      const stats = el("div", "wiki-stats");
+      for (const [val, label] of [
+        [String(project.docsRoots.length), "docs roots"],
+        [String(totalDocs), "documents"],
+        [String(totalBoards), "boards"],
+        [String(totalCaps), "capabilities"],
+      ] as [string, string][]) {
+        const stat = el("div", "wiki-stat");
+        const statVal = el("div", "wiki-stat-val");
+        statVal.textContent = val;
+        const statLabel = el("div", "wiki-stat-label");
+        statLabel.textContent = label;
+        stat.append(statVal, statLabel);
+        stats.appendChild(stat);
+      }
+      wikiHead.appendChild(stats);
+    }
+    page.appendChild(wikiHead);
+
+    // Filter roots if needed
+    const rootsToShow = filterRootId
+      ? project.docsRoots.filter(r => r.id === filterRootId)
+      : project.docsRoots;
+
+    // One section per docs root
+    for (const root of rootsToShow) {
+      const tree = this.treesByRoot.get(root.id) ?? [];
+      
+      // Filter to specific directory if requested (only for paths INSIDE the docs root)
+      let scopedTree = tree;
+      if (filterDirPath && !isAboveDocsRoot) {
+        const findDir = (nodes: TreeNode[], target: string): TreeNode | null => {
+          for (const n of nodes) {
+            if (n.type === "dir" && n.path === target) return n;
+            if (n.type === "dir") {
+              const found = findDir(n.children, target);
+              if (found) return found;
+            }
+          }
+          return null;
+        };
+        const dirNode = findDir(tree, filterDirPath);
+        scopedTree = dirNode?.type === "dir" ? dirNode.children : [];
+      }
+      
+      const mdFiles = visibleMarkdownFiles(scopedTree);
+      const boards = allBoardFiles(scopedTree);
+      const capsDir = scopedTree.find(n => n.type === "dir" && n.name === "capabilities");
+      const caps = capsDir?.type === "dir"
+        ? capsDir.children.filter(f => f.name.endsWith(".md"))
+        : [];
+
+      const section = el("div", "wiki-root-section");
+
+      // Root header (skip when viewing a subdirectory inside the docs root)
+      if (!filterDirPath || isAboveDocsRoot) {
+        const rootHead = el("div", "wiki-root-head");
+        const rootPath = el("div", "wiki-root-path");
+        rootPath.textContent = root.displayPath;
+        rootHead.appendChild(rootPath);
+        section.appendChild(rootHead);
+      }
+
+      // If completely empty
+      if (!mdFiles.length && !boards.length && !caps.length) {
+        const empty = el("div", "wiki-root-empty");
+        empty.textContent = "No docs, boards, or capabilities yet. Right-click in the sidebar to add content.";
+        section.appendChild(empty);
+        page.appendChild(section);
+        continue;
+      }
+
+      const cols = el("div", "wiki-root-cols");
+
+      // Docs column
+      if (mdFiles.length > 0) {
+        const col = el("div", "wiki-col");
+        const colHead = el("div", "wiki-col-head");
+        colHead.textContent = `Docs (${mdFiles.length})`;
+        col.appendChild(colHead);
+        const list = el("div", "wiki-col-list");
+        for (const file of mdFiles) {
+          const a = el("a", "wiki-col-item wiki-col-item-doc") as HTMLAnchorElement;
+          a.href = rootDocHash(root.id, file.path);
+          a.textContent = file.name === "index.md"
+            ? "Overview"
+            : file.name.replace(/\.md$/, "").replace(/[-_]/g, " ");
+          const pathHint = el("span", "wiki-col-item-path");
+          const dir = file.path.includes("/") ? file.path.slice(0, file.path.lastIndexOf("/")) : "";
+          pathHint.textContent = dir;
+          if (dir) a.appendChild(pathHint);
+          list.appendChild(a);
+        }
+        col.appendChild(list);
+        cols.appendChild(col);
+      }
+
+      // Boards column
+      if (boards.length > 0) {
+        const col = el("div", "wiki-col");
+        const colHead = el("div", "wiki-col-head");
+        colHead.textContent = `Boards (${boards.length})`;
+        col.appendChild(colHead);
+        const list = el("div", "wiki-col-list");
+        for (const f of boards) {
+          const boardId = boardIdFromFilePath(f.path);
+          const a = el("a", "wiki-col-item wiki-col-item-board") as HTMLAnchorElement;
+          a.href = rootBoardHash(root.id, boardId);
+          a.textContent = boardId.split("/").pop()!.replace(/[-_]/g, " ");
+          const pathHint = el("span", "wiki-col-item-path");
+          pathHint.textContent = boardId.includes("/") ? boardId.slice(0, boardId.lastIndexOf("/")) : root.displayPath;
+          a.appendChild(pathHint);
+          list.appendChild(a);
+        }
+        col.appendChild(list);
+        cols.appendChild(col);
+      }
+
+      // Capabilities column
+      if (caps.length > 0) {
+        const col = el("div", "wiki-col");
+        const colHead = el("div", "wiki-col-head");
+        colHead.textContent = `Capabilities (${caps.length})`;
+        col.appendChild(colHead);
+        const list = el("div", "wiki-col-list");
+        for (const f of caps) {
+          const a = el("a", "wiki-col-item wiki-col-item-cap") as HTMLAnchorElement;
+          a.href = rootCapabilityHash(root.id, f.path);
+          a.textContent = f.name.replace(/\.md$/, "").replace(/[-_]/g, " ");
+          list.appendChild(a);
+        }
+        col.appendChild(list);
+        cols.appendChild(col);
+      }
+
+      section.appendChild(cols);
+      page.appendChild(section);
+    }
+
+    this.content.replaceChildren(page);
+    this.contentScroll.scrollTop = scrollTop ?? 0;
+  }
+
+  private async renderDoc(rootId: string, filePath: string, scrollTop?: number): Promise<void> {
+    this.disposeContent();
+    if (!this.docsRootById(rootId)) {
+      this.renderMessage("Docs root unavailable", "This docs root is no longer registered. Re-add the project root if needed.");
+      return;
+    }
+    try {
+      const md = await ContentApi.readFile(rootId, filePath);
+      this.setEditableFile({ rootId, path: filePath });
+      const page = el("div", "doc-page");
+      const docsRoot = this.docsRootById(rootId);
+      const crumbs = standardCrumbs(this.workspace, rootId, { filePath });
+      page.appendChild(makeBreadcrumb(crumbs));
+      const article = el("div", "");
+      page.appendChild(article);
+      this.content.replaceChildren(page);
+      const { destroy } = renderMarkdownInto(article, md, { rootId, docPath: filePath });
+      this.cleanup = destroy;
+      // Prev / next
+      const tree = await ContentApi.getTree(rootId);
+      const seq = buildNavSequence(rootId, tree);
+      const nav = makePageNav(seq, rootDocHash(rootId, filePath));
+      if (nav) page.appendChild(nav);
+      this.contentScroll.scrollTop = scrollTop ?? 0;
+    } catch {
+      this.renderMessage("Document not found", filePath);
+    }
+  }
+
+  private openDocEditor(file: EditableFileRef): void {
+    this.topbar.classList.add("editing-doc");
+    this.closeCartPopover();
+    DocEditor.open({
+      rootId: file.rootId,
+      path: file.path,
+      onClose: () => {
+        this.topbar.classList.remove("editing-doc");
+        this.route();
+      },
+    });
+  }
+
+  private async renderCapabilityDoc(rootId: string, filePath: string, scrollTop?: number): Promise<void> {
+    this.disposeContent();
+    if (!this.docsRootById(rootId)) {
+      this.renderMessage("Docs root unavailable", "This docs root is no longer registered. Re-add the project root if needed.");
+      return;
+    }
+    let md: string;
+    try {
+      md = await ContentApi.readFile(rootId, filePath);
+      this.setEditableFile({ rootId, path: filePath });
+    } catch {
+      this.renderMessage("Capability not found", filePath);
+      return;
+    }
+
+    const page = el("div", "page");
+    const docsRoot = this.docsRootById(rootId);
+    const proj = docsRoot ? this.workspace.projects.find(p => p.id === docsRoot.projectId) : undefined;
+    const capName = prettify(filePath.split("/").pop()?.replace(/\.md$/, "") ?? filePath);
+    const crumbs = standardCrumbs(this.workspace, rootId, { filePath, currentLabel: capName });
+    page.appendChild(makeBreadcrumb(crumbs));
+    const bar = el("div", "page-bar");
+    const actions = el("div", "doc-actions capability-doc-actions");
+    const { frontmatter } = renderMarkdown(md);
+    const cartBtn = el("button", "btn") as HTMLButtonElement;
+    cartBtn.classList.add("capability-detail-btn");
+    const item = capabilityItemFrom(rootId, filePath, md, frontmatter);
+    this.updateCartButton(cartBtn, item.path);
+    cartBtn.addEventListener("click", () => {
+      this.toggleCapabilityCart(item);
+      this.updateCartButton(cartBtn, item.path);
+    });
+    const copyBtn = el("button", "btn primary") as HTMLButtonElement;
+    copyBtn.classList.add("capability-detail-btn");
+    copyBtn.textContent = "Copy as LLM prompt";
+    copyBtn.addEventListener("click", async () => {
+      try {
+        await navigator.clipboard.writeText(md);
+        showToast("Capability copied — paste into your AI assistant");
+      } catch {
+        showToast("Could not access clipboard");
+      }
+    });
+    actions.append(cartBtn, copyBtn);
+    bar.append(actions);
+    page.appendChild(bar);
+
+    const body = el("div", "");
+    page.appendChild(body);
+    this.content.replaceChildren(page);
+    const { destroy } = renderMarkdownInto(body, md, { rootId, docPath: filePath });
+    this.cleanup = destroy;
+    // Prev / next
+    const tree = this.treesByRoot.get(rootId) ?? [];
+    const seq = buildNavSequence(rootId, tree);
+    const nav = makePageNav(seq, rootCapabilityHash(rootId, filePath));
+    if (nav) page.appendChild(nav);
+    this.contentScroll.scrollTop = scrollTop ?? 0;
+  }
+
+  private async renderCapabilitiesIndex(rootId: string, scrollTop?: number): Promise<void> {
+    this.disposeContent();
+    if (!this.docsRootById(rootId)) {
+      this.renderMessage("Docs root unavailable", "This docs root is no longer registered. Re-add the project root if needed.");
+      return;
+    }
+    this.content.classList.add("content-wide");
+    const page = el("div", "page capability-library");
+    const capsCrumbs = standardCrumbs(this.workspace, rootId, { currentLabel: "Capabilities" });
+    page.appendChild(makeBreadcrumb(capsCrumbs));
+    const h1 = el("h1", "");
+    h1.textContent = "Capability library";
+    const lead = el("p", "page-lead");
+    lead.textContent =
+      "Select reusable specs into a component cart, then copy one combined prompt for your coding assistant.";
+    page.append(h1, lead);
+
+    const layout = el("div", "capability-layout");
+    const grid = el("div", "card-grid capability-grid");
+    const cart = this.renderCapabilityCart();
+    layout.append(grid, cart);
+    page.appendChild(layout);
+    this.content.replaceChildren(page);
+
+    try {
+      const tree = this.treesByRoot.get(rootId) ?? (await ContentApi.getTree(rootId));
+      const caps = tree.find((n) => n.type === "dir" && n.name === "capabilities");
+      const files =
+        caps && caps.type === "dir"
+          ? caps.children.filter((n) => n.type === "file" && n.name.endsWith(".md"))
+          : [];
+      for (const f of files) {
+        const md = await ContentApi.readFile(rootId, f.path);
+        const { frontmatter } = renderMarkdown(md);
+        const item = capabilityItemFrom(rootId, f.path, md, frontmatter);
+        const card = document.createElement("article");
+        card.className = "card";
+        if (this.capabilityCart.has(item.path)) card.classList.add("selected");
+        const title = el("div", "card-title");
+        const link = document.createElement("a");
+        link.href = rootCapabilityHash(rootId, f.path);
+        link.textContent = item.title;
+        title.appendChild(link);
+        const desc = el("div", "card-desc");
+        desc.textContent = item.summary;
+        card.append(title, desc);
+        if (item.tags.length) {
+          const tags = el("div", "card-tags");
+          for (const t of item.tags) {
+            const tag = el("span", "tag");
+            tag.textContent = t;
+            tags.appendChild(tag);
+          }
+          card.appendChild(tags);
+        }
+        const actions = el("div", "card-actions");
+        const add = el("button", "btn") as HTMLButtonElement;
+        add.classList.add("capability-add-btn");
+        this.updateCartButton(add, item.path);
+        add.addEventListener("click", () => {
+          this.toggleCapabilityCart(item);
+          void this.renderCapabilitiesIndex(rootId, this.contentScroll.scrollTop);
+        });
+        actions.appendChild(add);
+        card.appendChild(actions);
+        grid.appendChild(card);
+      }
+      if (files.length === 0) grid.appendChild(emptyNote("No capabilities yet."));
+      // Prev / next
+      const seq = buildNavSequence(rootId, tree);
+      const nav = makePageNav(seq, rootCapabilitiesHash(rootId));
+      if (nav) page.appendChild(nav);
+    } catch {
+      grid.appendChild(emptyNote("Could not load capabilities."));
+    }
+    this.contentScroll.scrollTop = scrollTop ?? 0;
+  }
+
+  private renderTokenLibrary(scrollTop?: number): void {
+    this.disposeContent();
+    this.content.classList.add("content-wide");
+    const page = el("div", "page token-library");
+    const head = el("div", "page-bar");
+    const title = el("h1", "");
+    title.textContent = "Tokens";
+    const actions = el("div", "token-actions");
+    const selectAll = el("button", "btn") as HTMLButtonElement;
+    selectAll.textContent = "Select all";
+    selectAll.addEventListener("click", () => {
+      this.selectedTokens = new Set(DESIGN_TOKENS.map((token) => token.variable));
+      this.renderTokenLibrary(this.contentScroll.scrollTop);
+    });
+    const clear = el("button", "btn") as HTMLButtonElement;
+    clear.textContent = "Clear";
+    clear.addEventListener("click", () => {
+      this.selectedTokens.clear();
+      this.renderTokenLibrary(this.contentScroll.scrollTop);
+    });
+    const copy = el("button", "btn primary") as HTMLButtonElement;
+    copy.textContent = `Copy selected (${this.selectedTokens.size})`;
+    copy.disabled = this.selectedTokens.size === 0;
+    copy.addEventListener("click", () => void this.copySelectedTokens());
+    actions.append(selectAll, clear, copy);
+    head.append(title, actions);
+    const lead = el("p", "page-lead");
+    lead.textContent =
+      "Brand, neutral, and semantic CSS variables used throughout the app. Select tokens and copy them as a ready-to-paste :root block.";
+    page.append(head, lead);
+
+    for (const group of ["Brand Colors", "Neutral Colors", "Semantic Colors"] as DesignToken["group"][]) {
+      const section = el("section", "token-section");
+      const h = el("h2", "");
+      h.textContent = group;
+      const grid = el("div", "token-grid");
+      for (const token of DESIGN_TOKENS.filter((t) => t.group === group)) {
+        const card = el("div", "token-card");
+        if (this.selectedTokens.has(token.variable)) card.classList.add("selected");
+        const selectZone = el("label", "token-select-zone") as HTMLLabelElement;
+        const input = document.createElement("input");
+        input.type = "checkbox";
+        input.checked = this.selectedTokens.has(token.variable);
+        input.addEventListener("change", () => {
+          if (input.checked) this.selectedTokens.add(token.variable);
+          else this.selectedTokens.delete(token.variable);
+          this.renderTokenLibrary(this.contentScroll.scrollTop);
+        });
+        const swatch = el("span", "token-swatch");
+        swatch.style.background = token.value;
+        const text = el("span", "token-copy");
+        const name = el("strong", "");
+        name.textContent = token.name;
+        const value = el("code", "");
+        value.textContent = token.value;
+        const desc = el("small", "");
+        desc.textContent = token.description;
+        text.append(name, value, desc);
+        selectZone.append(input, swatch, text);
+        const copyOne = el("button", "token-copy-btn") as HTMLButtonElement;
+        copyOne.type = "button";
+        copyOne.innerHTML = ICONS.copy;
+        copyOne.title = `Copy ${token.variable}`;
+        copyOne.setAttribute("aria-label", `Copy ${token.variable}`);
+        copyOne.addEventListener("click", (e) => {
+          e.stopPropagation();
+          void this.copyToken(token);
+        });
+        card.append(selectZone, copyOne);
+        grid.appendChild(card);
+      }
+      section.append(h, grid);
+      page.appendChild(section);
+    }
+
+    this.content.replaceChildren(page);
+    this.contentScroll.scrollTop = scrollTop ?? 0;
+  }
+
+  private async copySelectedTokens(): Promise<void> {
+    const tokens = DESIGN_TOKENS.filter((token) => this.selectedTokens.has(token.variable));
+    if (tokens.length === 0) return;
+    const css = [":root {", ...tokens.map((token) => `  ${token.variable}: ${token.value};`), "}"].join("\n");
+    try {
+      await navigator.clipboard.writeText(css);
+      showToast(`${tokens.length} token${tokens.length === 1 ? "" : "s"} copied`);
+    } catch {
+      showToast("Could not access clipboard");
+    }
+  }
+
+  private async copyToken(token: DesignToken): Promise<void> {
+    try {
+      await navigator.clipboard.writeText(`${token.variable}: ${token.value};`);
+      showToast(`${token.variable} copied`);
+    } catch {
+      showToast("Could not access clipboard");
+    }
+  }
+
+  private renderCapabilityCart(onChange?: () => void): HTMLElement {
+    const refresh =
+      onChange ??
+      (() => {
+        const rootId = currentRootIdFromHash(location.hash);
+        if (rootId) void this.renderCapabilitiesIndex(rootId, this.contentScroll.scrollTop);
+      });
+    const panel = el("aside", "capability-cart");
+    const head = el("div", "capability-cart-head");
+    const title = el("h2", "");
+    title.textContent = "Component cart";
+    const count = el("span", "capability-cart-count");
+    count.textContent = String(this.capabilityCart.size);
+    head.append(title, count);
+
+    const body = el("div", "capability-cart-body");
+    if (this.capabilityCart.size === 0) {
+      const empty = el("div", "capability-cart-empty");
+      empty.textContent = "Select specs to build a combined prompt.";
+      body.appendChild(empty);
+    } else {
+      for (const item of this.capabilityCart.values()) {
+        const row = el("div", "capability-cart-item");
+        const text = el("div", "");
+        const name = el("div", "capability-cart-item-title");
+        name.textContent = item.title;
+        const meta = el("div", "capability-cart-item-meta");
+        meta.textContent = item.displayPath;
+        text.append(name, meta);
+        const remove = el("button", "capability-cart-remove") as HTMLButtonElement;
+        remove.type = "button";
+        remove.textContent = "Remove";
+        remove.addEventListener("click", () => {
+          this.capabilityCart.delete(item.path);
+          this.updateTopbarCart();
+          refresh();
+        });
+        row.append(text, remove);
+        body.appendChild(row);
+      }
+    }
+
+    const actions = el("div", "capability-cart-actions");
+    const copy = el("button", "btn primary") as HTMLButtonElement;
+    copy.textContent = "Copy prompt";
+    copy.disabled = this.capabilityCart.size === 0;
+    copy.addEventListener("click", () => void this.copyCapabilityCartPrompt());
+    const clear = el("button", "btn") as HTMLButtonElement;
+    clear.textContent = "Clear";
+    clear.disabled = this.capabilityCart.size === 0;
+    clear.addEventListener("click", () => {
+      this.capabilityCart.clear();
+      this.updateTopbarCart();
+      refresh();
+    });
+    actions.append(copy, clear);
+    panel.append(head, body, actions);
+    return panel;
+  }
+
+  private toggleCapabilityCart(item: CapabilityCartItem): void {
+    if (this.capabilityCart.has(item.path)) this.capabilityCart.delete(item.path);
+    else this.capabilityCart.set(item.path, item);
+    this.updateTopbarCart();
+  }
+
+  private updateCartButton(button: HTMLButtonElement, path: string): void {
+    const selected = this.capabilityCart.has(path);
+    button.textContent = selected ? "Remove from cart" : "Add to cart";
+    button.classList.toggle("primary", !selected);
+    button.classList.toggle("is-selected", selected);
+  }
+
+  private async copyCapabilityCartPrompt(): Promise<void> {
+    if (this.capabilityCart.size === 0) return;
+    const specs = [...this.capabilityCart.values()]
+      .map((item, idx) => `## ${idx + 1}. ${item.title}\n\n${item.md.trim()}`)
+      .join("\n\n---\n\n");
+    const prompt =
+      "Use these capability/component specs as implementation guidance for the next coding task.\n\n" +
+      specs;
+    try {
+      await navigator.clipboard.writeText(prompt);
+      showToast(`${this.capabilityCart.size} spec${this.capabilityCart.size === 1 ? "" : "s"} copied`);
+    } catch {
+      showToast("Could not access clipboard");
+    }
+  }
+
+  // ---------- boards ----------
+
+  private async renderBoardList(rootId: string, scrollTop?: number): Promise<void> {
+    this.disposeContent();
+    if (!this.docsRootById(rootId)) {
+      this.renderMessage("Docs root unavailable", "This docs root is no longer registered. Re-add the project root if needed.");
+      return;
+    }
+    this.content.classList.add("content-wide");
+    const page = el("div", "page board-library");
+
+    const crumbs = standardCrumbs(this.workspace, rootId, { currentLabel: "Boards" });
+    page.appendChild(makeBreadcrumb(crumbs));
+    const head = el("div", "page-bar");
+    const title = el("h1", "");
+    title.textContent = "Boards";
+    const newBtn = el("button", "btn primary") as HTMLButtonElement;
+    newBtn.textContent = "+ New board";
+    newBtn.addEventListener("click", () => this.promptNewBoard(rootId));
+    head.append(title, newBtn);
+    page.appendChild(head);
+
+    const lead = el("p", "page-lead");
+    lead.textContent =
+      "Each board is a git-tracked JSON file. Open one to edit it, then use “Copy embed” to drop a framed preview into any doc.";
+    page.appendChild(lead);
+
+    const grid = el("div", "card-grid board-grid");
+    page.appendChild(grid);
+    this.content.replaceChildren(page);
+
+    try {
+      const boards = await BoardService.list(rootId);
+      for (const b of boards) {
+        const card = document.createElement("a");
+        card.className = "card";
+        card.href = rootBoardHash(rootId, b.id);
+        const t = el("div", "card-title");
+        t.textContent = b.title;
+        const meta = el("div", "card-desc");
+        meta.textContent = `${b.elementCount} element${b.elementCount === 1 ? "" : "s"} · ${b.filePath}`;
+        card.append(t, meta);
+        grid.appendChild(card);
+      }
+      if (boards.length === 0) grid.appendChild(emptyNote("No boards yet — create one."));
+      // Prev / next
+      const tree = await ContentApi.getTree(rootId);
+      const seq = buildNavSequence(rootId, tree);
+      const nav = makePageNav(seq, rootBoardsHash(rootId));
+      if (nav) page.appendChild(nav);
+    } catch {
+      grid.appendChild(emptyNote("Could not load boards."));
+    }
+    this.contentScroll.scrollTop = scrollTop ?? 0;
+  }
+
+  private async renderProjectBoardList(projectId: string, scrollTop?: number): Promise<void> {
+    this.disposeContent();
+    this.content.classList.add("content-wide");
+    const project = this.workspace.projects.find((p) => p.id === projectId);
+    if (!project) {
+      this.renderMessage("Project unavailable", "This project is no longer registered. Re-add it if needed.");
+      return;
+    }
+
+    const page = el("div", "page boards-page");
+    const crumbs: Crumb[] = [
+      { label: "Home", href: "#/" },
+      { label: project.label, href: projectWikiHash(projectId) },
+      { label: "Boards" },
+    ];
+    page.appendChild(makeBreadcrumb(crumbs));
+
+    const head = el("div", "page-bar");
+    const title = el("h1", "");
+    title.textContent = `${project.label} boards`;
+    head.appendChild(title);
+    page.appendChild(head);
+
+    const lead = el("p", "page-lead");
+    lead.textContent = "Boards across every mounted docs root in this project. Each card shows the docs root and board file path.";
+    page.appendChild(lead);
+
+    const grid = el("div", "card-grid board-grid");
+    page.appendChild(grid);
+    this.content.replaceChildren(page);
+
+    try {
+      const boards = await this.listProjectBoards(project);
+      for (const item of boards) {
+        const card = document.createElement("a");
+        card.className = "card";
+        card.href = rootBoardHash(item.root.id, item.board.id);
+        const t = el("div", "card-title");
+        t.textContent = item.board.title;
+        const meta = el("div", "card-desc");
+        meta.textContent = `${item.board.elementCount} element${item.board.elementCount === 1 ? "" : "s"} · ${item.root.displayPath} · ${item.board.filePath}`;
+        card.append(t, meta);
+        grid.appendChild(card);
+      }
+      if (boards.length === 0) grid.appendChild(emptyNote("No boards yet — create one."));
+    } catch {
+      grid.appendChild(emptyNote("Could not load boards."));
+    }
+    this.contentScroll.scrollTop = scrollTop ?? 0;
+  }
+
+  private async listProjectBoards(project: WorkspaceState["projects"][number]): Promise<Array<{ root: DocsRootSummary; board: BoardSummary }>> {
+    const out: Array<{ root: DocsRootSummary; board: BoardSummary }> = [];
+    for (const root of project.docsRoots) {
+      const boards = await BoardService.list(root.id);
+      for (const board of boards) out.push({ root, board });
+    }
+    out.sort((a, b) => {
+      if (b.board.updatedAt !== a.board.updatedAt) return b.board.updatedAt - a.board.updatedAt;
+      if (a.root.displayPath !== b.root.displayPath) return a.root.displayPath.localeCompare(b.root.displayPath);
+      return a.board.filePath.localeCompare(b.board.filePath);
+    });
+    return out;
+  }
+
+  private promptNewBoard(rootId: string, dirPath = ""): void {
+    const containerKey = dirPath ? `doc:${rootId}:${dirPath}` : rootId;
+    const collapsible = this.sidebar.collapsibles.get(containerKey);
+    const container = collapsible?.body ?? this.sidebar.element.querySelector(".nav-repo-body");
+
+    if (container) {
+      this.sidebar.startInlineCreate(container as HTMLElement, "board-name", async (raw) => {
+        const name = validateNewItemName(raw, "board");
+        if (!name.ok) { showToast(name.message); return; }
+        try {
+          const id = await BoardService.create(rootId, name.raw, currentTheme(), dirPath);
+          await this.refreshContentIndex();
+          location.hash = rootBoardHash(rootId, id);
+        } catch { showToast("Could not create board"); }
+      });
+    } else {
+      openModal("New board", (body, close) => {
+        const input = document.createElement("input");
+        input.className = "board-title";
+        input.placeholder = "Board title";
+        input.style.width = "100%";
+        input.style.marginBottom = "12px";
+        const actions = el("div", "modal-actions");
+        const create = el("button", "btn primary") as HTMLButtonElement;
+        create.textContent = "Create";
+        const go = async () => {
+          const name = validateNewItemName(input.value, "board");
+          if (!name.ok) { showToast(name.message); input.focus(); return; }
+          try {
+            const id = await BoardService.create(rootId, name.raw, currentTheme(), dirPath);
+            close();
+            await this.refreshContentIndex();
+            location.hash = rootBoardHash(rootId, id);
+          } catch { showToast("Could not create board file"); }
+        };
+        create.addEventListener("click", () => void go());
+        input.addEventListener("keydown", (e) => { e.stopPropagation(); if (e.key === "Enter") void go(); });
+        actions.appendChild(create);
+        body.append(input, actions);
+        input.focus();
+      });
+    }
+  }
+
+  private promptNewDirectory(rootId: string, dirPath: string): void {
+    const containerKey = dirPath ? `doc:${rootId}:${dirPath}` : rootId;
+    const collapsible = this.sidebar.collapsibles.get(containerKey);
+    const container = collapsible?.body ?? this.sidebar.element.querySelector(".nav-repo-body");
+
+    if (container) {
+      this.sidebar.startInlineCreate(container as HTMLElement, "directory-name", async (raw) => {
+        const name = validateNewItemName(raw, "directory");
+        if (!name.ok) { showToast(name.message); return; }
+        const directoryPath = dirPath ? `${dirPath}/${name.slug}` : name.slug;
+        try {
+          await ContentApi.createDirectory(rootId, directoryPath);
+          await this.refreshContentIndex();
+        } catch { showToast("Could not create directory"); }
+      });
+    } else {
+      openModal("New directory", (body, close) => {
+        const input = document.createElement("input");
+        input.className = "board-title";
+        input.placeholder = "Directory name";
+        input.style.width = "100%";
+        input.style.marginBottom = "12px";
+        const actions = el("div", "modal-actions");
+        const create = el("button", "btn primary") as HTMLButtonElement;
+        create.textContent = "Create";
+        const go = async () => {
+          const name = validateNewItemName(input.value, "directory");
+          if (!name.ok) { showToast(name.message); input.focus(); return; }
+          const directoryPath = dirPath ? `${dirPath}/${name.slug}` : name.slug;
+          try {
+            await ContentApi.createDirectory(rootId, directoryPath);
+            close();
+            await this.refreshContentIndex();
+          } catch { showToast("Could not create directory"); }
+        };
+        create.addEventListener("click", () => void go());
+        input.addEventListener("keydown", (e) => { e.stopPropagation(); if (e.key === "Enter") void go(); });
+        actions.appendChild(create);
+        body.append(input, actions);
+        input.focus();
+      });
+    }
+  }
+
+  private async ensureProjectDocsRoot(projectId: string): Promise<DocsRootSummary | undefined> {
+    const existing = this.workspace.projects.find((project) => project.id === projectId)?.docsRoots[0];
+    if (existing) return existing;
+    try {
+      const root = await ContentApi.ensureProjectDocsRoot(projectId);
+      await this.refreshContentIndex();
+      return this.docsRootById(root.id) ?? root;
+    } catch {
+      showToast("Could not create docs folder");
+      return undefined;
+    }
+  }
+
+  private async createDocsFolder(projectId: string, parentPath: string): Promise<void> {
+    try {
+      await ContentApi.createDocsFolder(projectId, parentPath);
+      await this.refreshContentIndex();
+      // Auto-close browse mode so the new docs root is immediately visible
+      this.sidebar.clearBrowseMode();
+      showToast(`Created docs/ in ${parentPath || "project root"}`);
+    } catch {
+      showToast("Could not create docs folder");
+    }
+  }
+
+  private async promptNewProjectDirectory(projectId: string): Promise<void> {
+    const root = await this.ensureProjectDocsRoot(projectId);
+    if (root) this.promptNewDirectory(root.id, "");
+  }
+
+  private async promptNewProjectDoc(projectId: string): Promise<void> {
+    const root = await this.ensureProjectDocsRoot(projectId);
+    if (root) this.promptNewDoc(root.id, "");
+  }
+
+  private async promptNewProjectBoard(projectId: string): Promise<void> {
+    const root = await this.ensureProjectDocsRoot(projectId);
+    if (root) this.promptNewBoard(root.id, "");
+  }
+
+  private promptNewDoc(rootId: string, dirPath: string): void {
+    // Find the container in the sidebar for this directory to insert inline input
+    const containerKey = dirPath ? `doc:${rootId}:${dirPath}` : rootId;
+    const collapsible = this.sidebar.collapsibles.get(containerKey);
+    const container = collapsible?.body ?? this.sidebar.element.querySelector(".nav-repo-body");
+
+    if (container) {
+      this.sidebar.startInlineCreate(container as HTMLElement, "document-name.md", async (raw) => {
+        const name = validateNewItemName(raw.replace(/\.md$/i, ""), "doc");
+        if (!name.ok) { showToast(name.message); return; }
+        const filePath = dirPath ? `${dirPath}/${name.slug}.md` : `${name.slug}.md`;
+        try {
+          await ContentApi.writeFile(rootId, filePath, `# ${prettify(name.slug)}\n`);
+          await this.refreshContentIndex();
+          location.hash = rootDocHash(rootId, filePath);
+        } catch { showToast("Could not create doc"); }
+      });
+    } else {
+      // Fallback to modal if we can't find the container
+      openModal("New doc", (body, close) => {
+        const input = document.createElement("input");
+        input.className = "board-title";
+        input.placeholder = "Document name (e.g. overview)";
+        input.style.width = "100%";
+        input.style.marginBottom = "12px";
+        const actions = el("div", "modal-actions");
+        const create = el("button", "btn primary") as HTMLButtonElement;
+        create.textContent = "Create";
+        const go = async () => {
+          const name = validateNewItemName(input.value.replace(/\.md$/i, ""), "doc");
+          if (!name.ok) { showToast(name.message); input.focus(); return; }
+          const filePath = dirPath ? `${dirPath}/${name.slug}.md` : `${name.slug}.md`;
+          try {
+            await ContentApi.writeFile(rootId, filePath, `# ${prettify(name.slug)}\n`);
+            close();
+            await this.refreshContentIndex();
+            location.hash = rootDocHash(rootId, filePath);
+          } catch { showToast("Could not create doc file"); }
+        };
+        create.addEventListener("click", () => void go());
+        input.addEventListener("keydown", (e) => { e.stopPropagation(); if (e.key === "Enter") void go(); });
+        actions.appendChild(create);
+        body.append(input, actions);
+        input.focus();
+      });
+    }
+  }
+
+  private promptNewCapability(rootId: string, dirPath: string): void {
+    openModal("New capability", (body, close) => {
+      const input = document.createElement("input");
+      input.className = "board-title";
+      input.placeholder = "Capability name (e.g. auth-flow)";
+      input.style.width = "100%";
+      input.style.marginBottom = "12px";
+
+      const actions = el("div", "modal-actions");
+      const create = el("button", "btn primary") as HTMLButtonElement;
+      create.textContent = "Create";
+      const go = async () => {
+        const name = (input.value.trim() || "untitled")
+          .replace(/\.md$/, "")
+          .replace(/\s+/g, "-")
+          .toLowerCase();
+        // Capabilities always live under the capabilities/ folder.
+        // If dirPath is given we nest within it, otherwise root of capabilities/.
+        const capPath = dirPath
+          ? `capabilities/${dirPath}/${name}.md`
+          : `capabilities/${name}.md`;
+        const title = prettify(name);
+        const stub = `---\ntitle: ${title}\nsummary: \ntags: \n---\n\n# ${title}\n`;
+        try {
+          await ContentApi.writeFile(rootId, capPath, stub);
+          close();
+          await this.refreshContentIndex();
+          location.hash = rootCapabilityHash(rootId, capPath);
+        } catch {
+          showToast("Could not create capability");
+        }
+      };
+      create.addEventListener("click", () => void go());
+      input.addEventListener("keydown", (e) => {
+        e.stopPropagation();
+        if (e.key === "Enter") void go();
+      });
+      actions.appendChild(create);
+      body.append(input, actions);
+      input.focus();
+    });
+  }
+
+  private promptRenameDoc(rootId: string, filePath: string): void {
+    const dir = filePath.includes("/") ? filePath.slice(0, filePath.lastIndexOf("/") + 1) : "";
+    const current = filePath.replace(/\.md$/, "").split("/").pop() ?? "";
+    const linkKey = `doc:${rootId}:${filePath}`;
+    const linkEl = this.sidebar.links.get(linkKey) as HTMLElement | undefined;
+
+    if (linkEl) {
+      this.sidebar.startInlineRename(linkEl, current, async (newName) => {
+        const name = newName.replace(/\.md$/, "").replace(/\s+/g, "-").toLowerCase();
+        const newPath = `${dir}${name}.md`;
+        if (newPath === filePath) return;
+        try {
+          await ContentApi.renameFile(rootId, filePath, newPath);
+          await this.refreshContentIndex();
+          location.hash = rootDocHash(rootId, newPath);
+        } catch { showToast("Could not rename doc"); }
+      });
+    } else {
+      // Fallback
+      openModal("Rename doc", (body, close) => {
+        const input = document.createElement("input");
+        input.className = "board-title";
+        input.value = current;
+        input.style.width = "100%";
+        input.style.marginBottom = "12px";
+        input.select();
+        const actions = el("div", "modal-actions");
+        const save = el("button", "btn primary") as HTMLButtonElement;
+        save.textContent = "Rename";
+        const go = async () => {
+          const name = (input.value.trim() || current).replace(/\.md$/, "").replace(/\s+/g, "-").toLowerCase();
+          const newPath = `${dir}${name}.md`;
+          if (newPath === filePath) { close(); return; }
+          try {
+            await ContentApi.renameFile(rootId, filePath, newPath);
+            close();
+            await this.refreshContentIndex();
+            location.hash = rootDocHash(rootId, newPath);
+          } catch { showToast("Could not rename doc"); }
+        };
+        save.addEventListener("click", () => void go());
+        input.addEventListener("keydown", (e) => { e.stopPropagation(); if (e.key === "Enter") void go(); });
+        actions.appendChild(save);
+        body.append(input, actions);
+        input.focus();
+      });
+    }
+  }
+
+  private async moveDoc(rootId: string, filePath: string, targetDir: string): Promise<void> {
+    const newPath = joinPath(targetDir, pathBasename(filePath));
+    if (newPath === filePath) return;
+    try {
+      const boardIds = new Set(allBoardFiles(await ContentApi.getTree(rootId)).map((node) => boardIdFromFilePath(node.path)));
+      const md = await ContentApi.readFile(rootId, filePath);
+      const rewritten = rewriteBoardEmbedsForDocMove(md, filePath, newPath, boardIds);
+      await ContentApi.renameFile(rootId, filePath, newPath);
+      if (rewritten !== md) await ContentApi.writeFile(rootId, newPath, rewritten);
+      await this.refreshContentIndex();
+      if (location.hash === rootDocHash(rootId, filePath)) {
+        location.hash = rootDocHash(rootId, newPath);
+      }
+      showToast(`Moved ${pathBasename(filePath)}`);
+    } catch {
+      showToast("Could not move doc");
+    }
+  }
+
+  private async moveBoard(rootId: string, boardId: string, targetDir: string): Promise<void> {
+    try {
+      const newId = await BoardService.move(rootId, boardId, targetDir);
+      const updatedEmbeds = await this.updateBoardEmbedReferences(rootId, boardId, newId);
+      await this.refreshContentIndex();
+      if (location.hash === rootBoardHash(rootId, boardId)) {
+        location.hash = rootBoardHash(rootId, newId);
+      }
+      showToast(updatedEmbeds > 0
+        ? `Moved ${pathBasename(boardId)} and updated ${updatedEmbeds} embed${updatedEmbeds === 1 ? "" : "s"}`
+        : `Moved ${pathBasename(boardId)}`);
+    } catch (err) {
+      showToast(err instanceof Error ? err.message : "Could not move board");
+    }
+  }
+
+  private async updateBoardEmbedReferences(rootId: string, oldBoardId: string, newBoardId: string): Promise<number> {
+    if (oldBoardId === newBoardId) return 0;
+    const tree = await ContentApi.getTree(rootId);
+    const docs = allMarkdownFiles(tree);
+    let updated = 0;
+    for (const doc of docs) {
+      const md = await ContentApi.readFile(rootId, doc.path);
+      const next = rewriteBoardEmbedSources(md, doc.path, oldBoardId, newBoardId);
+      if (next === md) continue;
+      await ContentApi.writeFile(rootId, doc.path, next);
+      updated++;
+    }
+    return updated;
+  }
+
+  private async moveDirectory(rootId: string, dirPath: string, targetDir: string): Promise<void> {
+    const name = pathBasename(dirPath);
+    const newDirPath = joinPath(targetDir, name);
+    if (newDirPath === dirPath) return;
+    try {
+      const tree = await ContentApi.getTree(rootId);
+      const boardIds = new Set(allBoardFiles(tree).map((node) => boardIdFromFilePath(node.path)));
+      const movedBoardIds = boardIdsUnderDirectory(tree, dirPath);
+      const movedDocs = docsUnderDirectory(tree, dirPath);
+      const movedDocContents = await Promise.all(
+        movedDocs.map(async (doc) => [doc.path, await ContentApi.readFile(rootId, doc.path)] as const)
+      );
+      await ContentApi.renameFile(rootId, dirPath, newDirPath);
+      let updatedEmbeds = 0;
+      for (const [oldDocPath, md] of movedDocContents) {
+        const newDocPath = `${newDirPath}${oldDocPath.slice(dirPath.length)}`;
+        const rewritten = rewriteBoardEmbedsForDocMove(md, oldDocPath, newDocPath, boardIds);
+        if (rewritten === md) continue;
+        await ContentApi.writeFile(rootId, newDocPath, rewritten);
+        updatedEmbeds++;
+      }
+      for (const oldBoardId of movedBoardIds) {
+        const newBoardId = `${newDirPath}${oldBoardId.slice(dirPath.length)}`;
+        await this.rewriteMovedBoardDocumentId(rootId, oldBoardId, newBoardId);
+        updatedEmbeds += await this.updateBoardEmbedReferences(rootId, oldBoardId, newBoardId);
+      }
+      await this.refreshContentIndex();
+      this.rewriteRouteAfterDirectoryMove(rootId, dirPath, newDirPath);
+      showToast(updatedEmbeds > 0
+        ? `Moved ${name} and updated ${updatedEmbeds} embed${updatedEmbeds === 1 ? "" : "s"}`
+        : `Moved ${name}`);
+    } catch {
+      showToast("Could not move directory");
+    }
+  }
+
+  private promptRenameDirectory(rootId: string, dirPath: string): void {
+    const parentDir = dirPath.includes("/") ? dirPath.slice(0, dirPath.lastIndexOf("/") + 1) : "";
+    const current = dirPath.split("/").pop() ?? "";
+    openModal("Rename directory", (body, close) => {
+      const input = document.createElement("input");
+      input.className = "board-title";
+      input.value = current;
+      input.style.width = "100%";
+      input.style.marginBottom = "12px";
+      input.select();
+      const actions = el("div", "modal-actions");
+      const save = el("button", "btn primary") as HTMLButtonElement;
+      save.textContent = "Rename";
+      const go = async () => {
+        const name = (input.value.trim() || current).replace(/\s+/g, "-").toLowerCase();
+        const newPath = `${parentDir}${name}`;
+        if (newPath === dirPath) { close(); return; }
+        try {
+          await ContentApi.renameFile(rootId, dirPath, newPath);
+          close();
+          await this.refreshContentIndex();
+          showToast(`Renamed to ${name}`);
+        } catch { showToast("Could not rename directory"); }
+      };
+      save.addEventListener("click", () => void go());
+      input.addEventListener("keydown", (e) => { e.stopPropagation(); if (e.key === "Enter") void go(); });
+      actions.appendChild(save);
+      body.append(input, actions);
+      input.focus();
+    });
+  }
+
+  private async promptDeleteDirectory(rootId: string, dirPath: string): Promise<void> {
+    const name = dirPath.split("/").pop() ?? dirPath;
+    const confirmed = confirm(`Delete "${name}" and all its contents? This cannot be undone.`);
+    if (!confirmed) return;
+    try {
+      await ContentApi.deleteFile(rootId, dirPath);
+      await this.refreshContentIndex();
+      showToast(`Deleted ${name}`);
+    } catch {
+      showToast("Could not delete directory");
+    }
+  }
+
+  private async rewriteMovedBoardDocumentId(rootId: string, oldBoardId: string, newBoardId: string): Promise<void> {
+    const moved = await ContentApi.getBoard(rootId, newBoardId);
+    if (!moved) return;
+    if (moved.id === newBoardId) return;
+    await ContentApi.saveBoard(rootId, newBoardId, { ...moved, id: newBoardId, updatedAt: Date.now() });
+  }
+
+  private rewriteRouteAfterDirectoryMove(rootId: string, oldDir: string, newDir: string): void {
+    const encodedRoot = encodeURIComponent(rootId);
+    const docPrefix = `#/root/${encodedRoot}/docs/`;
+    const boardPrefix = `#/root/${encodedRoot}/boards/`;
+    const hash = location.hash;
+    if (hash.startsWith(docPrefix)) {
+      const current = decodeURIComponent(hash.slice(docPrefix.length));
+      if (current === oldDir || current.startsWith(`${oldDir}/`)) {
+        location.hash = rootDocHash(rootId, `${newDir}${current.slice(oldDir.length)}`);
+      }
+    } else if (hash.startsWith(boardPrefix)) {
+      const current = decodeURIComponent(hash.slice(boardPrefix.length));
+      if (current === oldDir || current.startsWith(`${oldDir}/`)) {
+        location.hash = rootBoardHash(rootId, `${newDir}${current.slice(oldDir.length)}`);
+      }
+    }
+  }
+
+  private async promptDeleteDoc(rootId: string, filePath: string): Promise<void> {
+    const name = filePath.split("/").pop() ?? filePath;
+    openModal("Delete doc", (body, close) => {
+      const msg = el("p", "modal-copy");
+      msg.textContent = `Delete "${name}"? This cannot be undone.`;
+      const actions = el("div", "modal-actions");
+      const del = el("button", "btn danger") as HTMLButtonElement;
+      del.textContent = "Delete";
+      del.addEventListener("click", async () => {
+        try {
+          await ContentApi.deleteFile(rootId, filePath);
+          close();
+          await this.refreshContentIndex();
+          location.hash = "#/";
+        } catch { showToast("Could not delete doc"); }
+      });
+      const cancel = el("button", "btn") as HTMLButtonElement;
+      cancel.textContent = "Cancel";
+      cancel.addEventListener("click", close);
+      actions.append(del, cancel);
+      body.append(msg, actions);
+    });
+  }
+
+  private async promptRenameBoard(rootId: string, boardId: string): Promise<void> {
+    const doc = await BoardService.load(rootId, boardId);
+    if (!doc) { showToast("Board not found"); return; }
+    openModal("Rename board", (body, close) => {
+      const input = document.createElement("input");
+      input.className = "board-title";
+      input.value = doc.title;
+      input.style.width = "100%";
+      input.style.marginBottom = "12px";
+      input.select();
+      const actions = el("div", "modal-actions");
+      const save = el("button", "btn primary") as HTMLButtonElement;
+      save.textContent = "Rename";
+      const go = async () => {
+        const name = validateNewItemName(input.value, "board");
+        if (!name.ok) {
+          showToast(name.message);
+          input.focus();
+          return;
+        }
+        try {
+          const newId = await BoardService.rename(rootId, boardId, name.raw);
+          const updatedEmbeds = await this.updateBoardEmbedReferences(rootId, boardId, newId);
+          close();
+          await this.refreshContentIndex();
+          if (location.hash === rootBoardHash(rootId, boardId)) {
+            location.hash = rootBoardHash(rootId, newId);
+          }
+          if (updatedEmbeds > 0) {
+            showToast(`Renamed board and updated ${updatedEmbeds} embed${updatedEmbeds === 1 ? "" : "s"}`);
+          }
+        } catch (err) {
+          showToast(err instanceof Error ? err.message : "Could not rename board");
+        }
+      };
+      save.addEventListener("click", () => void go());
+      input.addEventListener("keydown", (e) => { e.stopPropagation(); if (e.key === "Enter") void go(); });
+      actions.appendChild(save);
+      body.append(input, actions);
+      input.focus();
+    });
+  }
+
+  private promptDeleteBoard(rootId: string, boardId: string): void {
+    openModal("Delete board", (body, close) => {
+      const msg = el("p", "modal-copy");
+      msg.textContent = `Delete "${boardId}.board.json"? This cannot be undone.`;
+      const actions = el("div", "modal-actions");
+      const del = el("button", "btn danger") as HTMLButtonElement;
+      del.textContent = "Delete";
+      del.addEventListener("click", async () => {
+        try {
+          await BoardService.delete(rootId, boardId);
+          close();
+          await this.refreshContentIndex();
+          location.hash = rootBoardsHash(rootId);
+        } catch { showToast("Could not delete board"); }
+      });
+      const cancel = el("button", "btn") as HTMLButtonElement;
+      cancel.textContent = "Cancel";
+      cancel.addEventListener("click", close);
+      actions.append(del, cancel);
+      body.append(msg, actions);
+    });
+  }
+
+  private async openEditor(rootId: string, id: string, initialRegion?: BoardRegion): Promise<void> {
+    if (!this.docsRootById(rootId)) {
+      this.renderMessage("Docs root unavailable", "This docs root is no longer registered. Re-add the project root if needed.");
+      return;
+    }
+    if (this.editor && this.editingId === `${rootId}:${id}`) return;
+    this.exitEditor();
+    this.disposeContent();
+    this.layout.style.display = "none";
+
+    this.editorHost = el("div", "board-editor-host");
+    this.root.appendChild(this.editorHost);
+    this.editingId = `${rootId}:${id}`;
+    this.editor = new AppController(this.editorHost, {
+      boardId: id,
+      loadBoard: (bid) => BoardService.load(rootId, bid),
+      saveBoard: (doc) => BoardService.save(rootId, doc),
+      deleteBoard: (bid) => BoardService.delete(rootId, bid),
+      uploadImage: (blob, name) => BoardService.uploadImage(rootId, blob, name),
+      resolveAssetUrl: (src) => ContentApi.assetUrl(rootId, src),
+      initialRegion,
+      onExit: () => {
+        this.pendingScrollRestore = this.lastNonBoardScrollTop;
+        location.hash = this.lastNonBoardHash;
+      },
+      onDeleted: () => {
+        location.hash = rootBoardsHash(rootId);
+      },
+    });
+  }
+
+  private exitEditor(): void {
+    if (this.editor) {
+      this.editor.destroy();
+      this.editor = undefined;
+    }
+    if (this.editorHost) {
+      this.editorHost.remove();
+      this.editorHost = undefined;
+    }
+    this.editingId = undefined;
+    // editor may have set data-theme from the board doc; restore shell theme
+    this.applyInitialTheme();
+  }
+
+  // ---------- theme ----------
+
+  private applyInitialTheme(): void {
+    const saved = localStorage.getItem(THEME_KEY);
+    const theme =
+      saved === "dark" || saved === "light"
+        ? saved
+        : window.matchMedia("(prefers-color-scheme: dark)").matches
+        ? "dark"
+        : "light";
+    document.documentElement.setAttribute("data-theme", theme);
+  }
+
+  private toggleTheme(): void {
+    const next = currentTheme() === "dark" ? "light" : "dark";
+    document.documentElement.setAttribute("data-theme", next);
+    localStorage.setItem(THEME_KEY, next);
+    this.updateThemeButton();
+    this.route({ preserveScroll: true }); // re-render so board previews pick up the new theme
+  }
+
+  // ---------- top bar + command palette ----------
+
+  private createTopbar(): HTMLElement {
+    const bar = el("div", "shell-topbar");
+
+    const navToggle = el("button", "topbar-icon-btn") as HTMLButtonElement;
+    navToggle.innerHTML = ICONS.panelLeft;
+    navToggle.title = "Toggle navigation";
+    navToggle.setAttribute("aria-label", "Toggle navigation");
+    navToggle.addEventListener("click", () =>
+      this.setSidebarCollapsed(!this.layout.classList.contains("sidebar-collapsed"))
+    );
+
+    this.searchBtn = el("button", "topbar-search") as HTMLButtonElement;
+    this.searchBtn.type = "button";
+    this.searchBtn.innerHTML = `${ICONS.search}<span>Search docs</span><kbd>${this.shortcutLabel()}</kbd>`;
+    this.searchBtn.addEventListener("click", () => this.openCommandPalette());
+
+    this.cartBtn = el("button", "topbar-cart") as HTMLButtonElement;
+    this.cartBtn.type = "button";
+    this.cartBtn.addEventListener("click", () => this.toggleCartPopover());
+    this.updateTopbarCart();
+
+    this.editBtn = el("button", "btn topbar-edit") as HTMLButtonElement;
+    this.editBtn.type = "button";
+    this.editBtn.innerHTML = `${ICONS.edit}<span>Edit</span>`;
+    this.editBtn.title = "Edit this document";
+    this.editBtn.addEventListener("click", () => {
+      if (this.currentEditableFile) this.openDocEditor(this.currentEditableFile);
+    });
+
+    this.themeBtn = el("button", "topbar-icon-btn topbar-theme") as HTMLButtonElement;
+    this.themeBtn.type = "button";
+    this.themeBtn.title = "Toggle theme";
+    this.themeBtn.setAttribute("aria-label", "Toggle theme");
+    this.themeBtn.addEventListener("click", () => this.toggleTheme());
+    this.updateThemeButton();
+
+    bar.append(navToggle, this.searchBtn, this.cartBtn, this.editBtn, this.themeBtn);
+    return bar;
+  }
+
+  private setSidebarCollapsed(collapsed: boolean): void {
+    this.layout.classList.toggle("sidebar-collapsed", collapsed);
+    localStorage.setItem(SIDEBAR_KEY, String(collapsed));
+  }
+
+  private setEditableFile(file: EditableFileRef | undefined): void {
+    this.currentEditableFile = file;
+    if (!this.editBtn) return;
+    this.editBtn.hidden = !file;
+    this.editBtn.disabled = !file;
+  }
+
+  private promptRemoveProject(projectId: string, label: string): void {
+    openModal("Remove from workspace", (body, close) => {
+      const msg = el("p", "modal-copy");
+      msg.textContent = `Remove "${label}" from the workspace? The files on disk are not deleted.`;
+      const actions = el("div", "modal-actions");
+      const remove = el("button", "btn danger") as HTMLButtonElement;
+      remove.textContent = "Remove";
+      remove.addEventListener("click", async () => {
+        try {
+          await ContentApi.removeProject(projectId);
+          close();
+          await this.refreshContentIndex();
+          location.hash = "#/";
+        } catch {
+          showToast("Could not remove project");
+        }
+      });
+      const cancel = el("button", "btn") as HTMLButtonElement;
+      cancel.textContent = "Cancel";
+      cancel.addEventListener("click", close);
+      actions.append(remove, cancel);
+      body.append(msg, actions);
+    });
+  }
+
+  private async addRepoDocs(): Promise<void> {
+    try {
+      const before = new Set(this.allDocsRoots().map((root) => root.id));
+      const result = await ContentApi.pickAndAddProject();
+      if (result.cancelled) return;
+      await this.refreshContentIndex();
+      const roots = this.allDocsRoots();
+      const preferred = result.addedProjectId
+        ? this.workspace.projects.find((project) => project.id === result.addedProjectId)?.docsRoots[0]
+        : roots.find((root) => !before.has(root.id));
+      const targetRoot = preferred ?? roots[0];
+      if (!targetRoot) {
+        showToast("No docs folders found under that project root.");
+        return;
+      }
+      const tree = this.treesByRoot.get(targetRoot.id) ?? [];
+      const firstDoc = firstMarkdownPath(visibleDocsTree(tree));
+      if (firstDoc) location.hash = rootDocHash(targetRoot.id, firstDoc);
+      else location.hash = rootBoardsHash(targetRoot.id);
+      showToast(`Added ${targetRoot.projectLabel}.`);
+    } catch (err) {
+      showToast(err instanceof Error ? err.message : "Could not add project root.");
+    }
+  }
+
+  private updateTopbarCart(hidden = false): void {
+    if (!this.cartBtn) return;
+    const count = this.capabilityCart.size;
+    this.cartBtn.hidden = hidden;
+    this.cartBtn.innerHTML = `<span>Cart</span><strong>${count}</strong>`;
+    this.cartBtn.title = `${count} item${count === 1 ? "" : "s"} in component cart`;
+    this.cartBtn.setAttribute("aria-label", this.cartBtn.title);
+    this.cartBtn.disabled = count === 0;
+  }
+
+  private toggleCartPopover(): void {
+    if (this.cartPopover?.classList.contains("visible")) {
+      this.closeCartPopover();
+      return;
+    }
+    this.openCartPopover();
+  }
+
+  private openCartPopover(): void {
+    if (this.capabilityCart.size === 0) return;
+    if (!this.cartPopover) {
+      this.cartPopover = el("div", "topbar-cart-popover");
+      this.topbar.appendChild(this.cartPopover);
+      document.addEventListener("mousedown", (e) => {
+        if (!this.cartPopover?.classList.contains("visible")) return;
+        const target = e.target as Node;
+        if (this.cartPopover.contains(target) || this.cartBtn.contains(target)) return;
+        this.closeCartPopover();
+      });
+    }
+    this.cartPopover.replaceChildren(
+      this.renderCapabilityCart(() => {
+        this.updateTopbarCart();
+        if (this.capabilityCart.size === 0) this.closeCartPopover();
+        else this.openCartPopover();
+      })
+    );
+    this.content.classList.add("cart-popover-open");
+    this.cartPopover.classList.add("visible");
+  }
+
+  private closeCartPopover(): void {
+    this.content.classList.remove("cart-popover-open");
+    this.cartPopover?.classList.remove("visible");
+  }
+
+  private updateThemeButton(): void {
+    if (!this.themeBtn) return;
+    const isDark = currentTheme() === "dark";
+    this.themeBtn.innerHTML = isDark ? ICONS.sun : ICONS.moon;
+    this.themeBtn.title = isDark ? "Switch to light mode" : "Switch to dark mode";
+    this.themeBtn.setAttribute("aria-label", this.themeBtn.title);
+  }
+
+  private handleGlobalKeydown(e: KeyboardEvent): void {
+    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
+      const target = e.target as HTMLElement | null;
+      if (target?.closest(".doc-editor")) return;
+      e.preventDefault();
+      this.openCommandPalette();
+      return;
+    }
+    
+    // F2 to rename the current item
+    if (e.key === "F2") {
+      const hash = location.hash;
+      const target = e.target as HTMLElement | null;
+      if (target?.closest(".doc-editor, input, textarea, [contenteditable]")) return;
+      e.preventDefault();
+      
+      // Check if we're viewing a doc
+      const docMatch = hash.match(/^#\/root\/([^/]+)\/docs\/(.+)$/);
+      if (docMatch) {
+        const rootId = decodeURIComponent(docMatch[1]);
+        const filePath = decodeURIComponent(docMatch[2]);
+        this.promptRenameDoc(rootId, filePath);
+        return;
+      }
+      
+      // Check if we're viewing a board
+      const boardMatch = hash.match(/^#\/root\/([^/]+)\/boards\/(.+)$/);
+      if (boardMatch) {
+        const rootId = decodeURIComponent(boardMatch[1]);
+        const boardId = decodeURIComponent(boardMatch[2]);
+        this.promptRenameBoard(rootId, boardId);
+        return;
+      }
+      
+      // Check if we're viewing a directory wiki
+      const dirMatch = hash.match(/^#\/root\/([^/]+)\/directory\/(.+)$/);
+      if (dirMatch) {
+        const rootId = decodeURIComponent(dirMatch[1]);
+        const dirPath = decodeURIComponent(dirMatch[2]);
+        this.promptRenameDirectory(rootId, dirPath);
+        return;
+      }
+    }
+  }
+
+  private allDocsRoots(): DocsRootSummary[] {
+    return this.workspace.projects.flatMap((project) => project.docsRoots);
+  }
+
+  private docsRootById(rootId: string): DocsRootSummary | undefined {
+    return this.allDocsRoots().find((root) => root.id === rootId);
+  }
+
+  private async refreshContentIndex(): Promise<void> {
+    try {
+      this.workspace = await ContentApi.getWorkspace();
+    } catch {
+      this.workspace = { projects: [] };
+      this.treesByRoot = new Map();
+      this.treesByProject = new Map();
+      this.sidebar.refresh(this.workspace, this.treesByRoot);
+      this.searchIndex = [];
+      return;
+    }
+
+    const roots = this.allDocsRoots();
+    const trees = await Promise.all(
+      roots.map(async (root) => {
+        try {
+          return [root.id, await ContentApi.getTree(root.id)] as const;
+        } catch {
+          return [root.id, [] as TreeNode[]] as const;
+        }
+      })
+    );
+    this.treesByRoot = new Map(trees);
+
+    // Also fetch full project trees for sidebar
+    const projectTrees = await Promise.all(
+      this.workspace.projects.map(async (project) => {
+        try {
+          return [project.id, await ContentApi.getProjectTree(project.id)] as const;
+        } catch {
+          return [project.id, [] as TreeNode[]] as const;
+        }
+      })
+    );
+    this.treesByProject = new Map(projectTrees);
+    
+    this.sidebar.refresh(this.workspace, this.treesByRoot, this.treesByProject);
+
+    const entries: SearchEntry[] = [];
+    for (const root of roots) {
+      const tree = this.treesByRoot.get(root.id) ?? [];
+      const files = [...visibleMarkdownFiles(tree), ...filesUnder(tree, "capabilities")].filter(
+        (node) => node.type === "file" && node.name.endsWith(".md")
+      );
+      for (const node of files) {
+        const path = "path" in node ? node.path : "";
+        let md = "";
+        try {
+          md = await ContentApi.readFile(root.id, path);
+        } catch {
+          /* Skip unreadable files from search, but keep the shell usable. */
+        }
+        const { frontmatter } = renderMarkdown(md);
+        const chunks = searchChunksFromMarkdown(md);
+        const title = frontmatter.title ?? firstHeading(md) ?? prettify(node.name);
+        const summary = frontmatter.summary ?? firstParagraph(chunks);
+        const section = path.startsWith("capabilities/") ? "Capability" : "Doc";
+        const href = path.startsWith("capabilities/")
+          ? rootCapabilityHash(root.id, path)
+          : rootDocHash(root.id, path);
+        entries.push({
+          title,
+          path: `${root.projectLabel}/${root.displayPath}/${path}`,
+          href,
+          section,
+          summary,
+          body: chunks.map((c) => c.text).join(" "),
+          chunks,
+          rootId: root.id,
+        });
+      }
+    }
+    this.searchIndex = entries.filter((entry) => entry.body || entry.title);
+  }
+
+  private openCommandPalette(): void {
+    if (!this.palette) this.createCommandPalette();
+    this.palette?.classList.add("visible");
+    document.body.style.overflow = "hidden";
+    this.paletteInput!.value = "";
+    this.renderSearchResults("");
+    requestAnimationFrame(() => this.paletteInput?.focus());
+  }
+
+  private closeCommandPalette(): void {
+    this.palette?.classList.remove("visible");
+    document.body.style.overflow = "";
+  }
+
+  private createCommandPalette(): void {
+    this.palette = el("div", "command-palette");
+    const panel = el("div", "command-panel");
+    const search = el("div", "command-search");
+    search.innerHTML = ICONS.search;
+    this.paletteInput = document.createElement("input");
+    this.paletteInput.type = "search";
+    this.paletteInput.placeholder = "Search docs";
+    this.paletteInput.setAttribute("aria-label", "Search docs");
+    search.appendChild(this.paletteInput);
+    this.paletteResults = el("div", "command-results");
+    panel.append(search, this.paletteResults);
+    this.palette.appendChild(panel);
+    document.body.appendChild(this.palette);
+
+    this.palette.addEventListener("mousedown", (e) => {
+      if (e.target === this.palette) this.closeCommandPalette();
+    });
+    this.paletteInput.addEventListener("input", () => this.renderSearchResults(this.paletteInput!.value));
+    this.paletteInput.addEventListener("keydown", (e) => this.handlePaletteKeydown(e));
+  }
+
+  private handlePaletteKeydown(e: KeyboardEvent): void {
+    if (e.key === "Escape") {
+      e.preventDefault();
+      this.closeCommandPalette();
+      return;
+    }
+    const items = [...(this.paletteResults?.querySelectorAll<HTMLAnchorElement>(".command-result") ?? [])];
+    const active = this.paletteResults?.querySelector<HTMLAnchorElement>(".command-result.active");
+    const index = active ? items.indexOf(active) : -1;
+    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+      e.preventDefault();
+      const next =
+        e.key === "ArrowDown"
+          ? Math.min(index + 1, items.length - 1)
+          : Math.max(index - 1, 0);
+      items.forEach((item) => item.classList.remove("active"));
+      items[next]?.classList.add("active");
+      items[next]?.scrollIntoView({ block: "nearest" });
+    }
+    if (e.key === "Enter") {
+      e.preventDefault();
+      (active ?? items[0])?.click();
+    }
+  }
+
+  private renderSearchResults(query: string): void {
+    if (!this.paletteResults) return;
+    const terms = searchTerms(query);
+    const results = this.rankSearch(terms).slice(0, 8);
+    this.paletteResults.replaceChildren();
+    if (results.length === 0) {
+      const empty = el("div", "command-empty");
+      empty.textContent = this.searchIndex.length ? "No matching docs." : "No docs indexed yet.";
+      this.paletteResults.appendChild(empty);
+      return;
+    }
+    for (const [i, result] of results.entries()) {
+      const { entry } = result;
+      const item = document.createElement("a");
+      item.className = "command-result";
+      if (i === 0) item.classList.add("active");
+      item.href = entry.href;
+      item.addEventListener("click", () => this.closeCommandPalette());
+      const title = el("div", "command-result-title");
+      appendHighlightedText(title, entry.title, terms);
+      const meta = el("div", "command-result-meta");
+      meta.textContent = [entry.section, result.heading, entry.path].filter(Boolean).join(" · ");
+      const summary = el("div", "command-result-summary");
+      appendHighlightedText(summary, result.preview, terms);
+      item.append(title, meta);
+      if (summary.textContent) item.appendChild(summary);
+      this.paletteResults.appendChild(item);
+    }
+  }
+
+  private rankSearch(terms: string[]): SearchResult[] {
+    if (terms.length === 0) {
+      return this.searchIndex.map((entry) => ({
+        entry,
+        score: 0,
+        heading: "",
+        preview: entry.summary || entry.body.slice(0, 220),
+      }));
+    }
+    const normalizedTerms = terms.map(normalizeSearchText).filter(Boolean);
+    const phrase = normalizeSearchText(terms.join(" "));
+    return this.searchIndex
+      .map((entry) => {
+        const title = normalizeSearchText(entry.title);
+        const path = normalizeSearchText(entry.path);
+        const summary = normalizeSearchText(entry.summary);
+        let docScore = scoreText(title, normalizedTerms, phrase, 10);
+        docScore += scoreText(path, normalizedTerms, phrase, 4);
+        docScore += scoreText(summary, normalizedTerms, phrase, 3);
+        let bestChunk: SearchChunk | undefined;
+        let bestChunkScore = 0;
+        for (const chunk of entry.chunks) {
+          const headingScore = scoreText(normalizeSearchText(chunk.heading), normalizedTerms, phrase, 5);
+          const textScore = scoreText(chunk.normalized, normalizedTerms, phrase, chunk.kind === "heading" ? 8 : 2);
+          const chunkScore = headingScore + textScore;
+          if (chunkScore > bestChunkScore) {
+            bestChunkScore = chunkScore;
+            bestChunk = chunk;
+          }
+        }
+        const score = docScore + bestChunkScore;
+        return {
+          entry,
+          score,
+          heading: bestChunk?.heading && bestChunk.heading !== entry.title ? bestChunk.heading : "",
+          preview: bestChunk ? chunkPreview(bestChunk.text, normalizedTerms) : entry.summary,
+        };
+      })
+      .filter((r) => r.score > 0)
+      .sort((a, b) => b.score - a.score || a.entry.title.localeCompare(b.entry.title));
+  }
+
+  private shortcutLabel(): string {
+    return /Mac|iPhone|iPad/.test(navigator.platform) ? "⌘K" : "Ctrl K";
+  }
+
+  // ---------- helpers ----------
+
+  private disposeContent(): void {
+    if (this.cleanup) {
+      this.cleanup();
+      this.cleanup = undefined;
+    }
+    this.content.classList.remove("content-wide");
+    this.content.replaceChildren();
+  }
+
+  private renderMessage(title: string, detail: string): void {
+    this.disposeContent();
+    const page = el("div", "page");
+    const h = el("h1", "");
+    h.textContent = title;
+    const p = el("p", "page-lead");
+    p.textContent = detail;
+    page.append(h, p);
+    this.content.replaceChildren(page);
+  }
+}
+
+// ---------- Breadcrumb ----------
+
+type Crumb = { label: string; href?: string };
+
+/**
+ * Standard breadcrumb builder for docs content.
+ *
+ * Given a rootId (and optional filePath or dirPath), produces a consistent
+ * breadcrumb array:  Home / Project / directory… / currentPage
+ *
+ * The docs root label (e.g. "docs") is intentionally omitted — it's just
+ * scaffolding. The project name already tells you which project you're in,
+ * and the directory segments tell you where inside it.
+ */
+function standardCrumbs(
+  workspace: { projects: { id: string; label: string; docsRoots: { id: string; projectId: string; displayPath: string }[] }[] },
+  rootId: string,
+  opts: { filePath?: string; dirPath?: string; currentLabel?: string } = {}
+): Crumb[] {
+  const crumbs: Crumb[] = [{ label: "Home", href: "#/" }];
+
+  // Find project and docs root
+  let docsRoot: { id: string; projectId: string; displayPath: string } | undefined;
+  for (const p of workspace.projects) {
+    const r = p.docsRoots.find(r => r.id === rootId);
+    if (r) {
+      crumbs.push({ label: p.label, href: projectWikiHash(p.id) });
+      docsRoot = r;
+      break;
+    }
+  }
+
+  // Add the docs root's display path segments (the directories BETWEEN
+  // the project root and the /docs/ folder, e.g. "calwc-esc/docs").
+  if (docsRoot) {
+    const rootParts = docsRoot.displayPath.split("/").filter(Boolean);
+    for (let i = 0; i < rootParts.length; i++) {
+      const partial = rootParts.slice(0, i + 1).join("/");
+      crumbs.push({
+        label: rootParts[i],
+        href: directoryWikiHash(rootId, partial),
+      });
+    }
+  }
+
+  // Add the path segments within the docs root (subdirectories of /docs/)
+  const path = opts.filePath ?? opts.dirPath ?? "";
+  const parts = path.split("/").filter(Boolean);
+  const dirParts = opts.filePath ? parts.slice(0, -1) : parts;
+  for (let i = 0; i < dirParts.length; i++) {
+    const partial = dirParts.slice(0, i + 1).join("/");
+    crumbs.push({
+      label: prettify(dirParts[i]),
+      href: directoryWikiHash(rootId, partial),
+    });
+  }
+
+  // Current page label
+  if (opts.currentLabel) {
+    crumbs.push({ label: opts.currentLabel });
+  } else if (opts.filePath) {
+    const fileName = parts[parts.length - 1];
+    crumbs.push({ label: fileName === "index.md" ? "Overview" : prettify(fileName) });
+  }
+  return crumbs;
+}
+
+/**
+ * Build a breadcrumb bar element.
+ * Segments with an href become <a> links; the last segment is always plain text.
+ */
+function makeBreadcrumb(crumbs: Crumb[]): HTMLElement {
+  const nav = el("nav", "breadcrumb");
+  nav.setAttribute("aria-label", "Breadcrumb");
+  for (let i = 0; i < crumbs.length; i++) {
+    const crumb = crumbs[i];
+    const isLast = i === crumbs.length - 1;
+    if (!isLast && crumb.href) {
+      const a = document.createElement("a");
+      a.className = "breadcrumb-link";
+      a.href = crumb.href;
+      a.textContent = crumb.label;
+      nav.appendChild(a);
+    } else {
+      const span = el("span", "breadcrumb-current");
+      span.textContent = crumb.label;
+      nav.appendChild(span);
+    }
+    // Always add separator except after the last crumb
+    if (!isLast) {
+      const sep = el("span", "breadcrumb-sep");
+      sep.textContent = "/";
+      sep.setAttribute("aria-hidden", "true");
+      nav.appendChild(sep);
+    }
+  }
+  return nav;
+}
+
+function el(tag: string, cls: string): HTMLElement {
+  const node = document.createElement(tag);
+  if (cls) node.className = cls;
+  return node;
+}
+
+function emptyNote(text: string): HTMLElement {
+  const note = el("div", "empty-note");
+  note.textContent = text;
+  return note;
+}
+
+function capabilityItemFrom(
+  rootId: string,
+  path: string,
+  md: string,
+  frontmatter: Record<string, string>
+): CapabilityCartItem {
+  return {
+    path: `${rootId}:${path}`,
+    displayPath: path,
+    title: frontmatter.title ?? firstHeading(md) ?? prettify(path.split("/").pop() ?? path),
+    summary: frontmatter.summary ?? firstParagraph(searchChunksFromMarkdown(md)),
+    tags: frontmatter.tags ? frontmatter.tags.split(",").map((t) => t.trim()).filter(Boolean) : [],
+    md,
+  };
+}
+
+// ---------- Nav sequence (prev/next) ----------
+
+type NavItem = { label: string; href: string };
+
+/**
+ * Build the full ordered list of navigable pages for a single docs root.
+ * Order: docs tree (index first, dirs before files, alpha) →
+ *        All Boards page → each individual board (alpha by id) →
+ *        All Capabilities page → each capability (alpha).
+ * This mirrors the sidebar order so prev/next feels natural.
+ */
+function buildNavSequence(rootId: string, tree: TreeNode[]): NavItem[] {
+  const items: NavItem[] = [];
+
+  // ── docs ──────────────────────────────────────────────────────────────
+  function walkDocs(nodes: TreeNode[]): void {
+    const visible = visibleDocsTree(nodes);
+    const sorted = [...visible].sort((a, b) => {
+      const ai = a.type === "file" && a.name === "index.md" ? -1 : 0;
+      const bi = b.type === "file" && b.name === "index.md" ? -1 : 0;
+      if (ai !== bi) return ai - bi;
+      if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+    for (const node of sorted) {
+      if (node.type === "file") {
+        const label = node.name === "index.md" ? "Overview" : prettify(node.name);
+        items.push({ label, href: rootDocHash(rootId, node.path) });
+      } else {
+        walkDocs(node.children);
+      }
+    }
+  }
+  walkDocs(tree);
+
+  // ── boards ────────────────────────────────────────────────────────────
+  const boardFiles = allBoardFiles(tree)
+    .sort((a, b) => a.path.localeCompare(b.path));
+  if (boardFiles.length > 0) {
+    items.push({ label: "All Boards", href: rootBoardsHash(rootId) });
+    for (const f of boardFiles) {
+      const id = boardIdFromFilePath(f.path);
+      items.push({ label: prettify(id.split("/").pop() ?? id), href: rootBoardHash(rootId, id) });
+    }
+  }
+
+  // ── capabilities ──────────────────────────────────────────────────────
+  const capsDir = tree.find(n => n.type === "dir" && n.name === "capabilities");
+  const capFiles = capsDir?.type === "dir"
+    ? capsDir.children.filter(f => f.type === "file" && f.name.endsWith(".md"))
+        .sort((a, b) => a.name.localeCompare(b.name))
+    : [];
+  if (capFiles.length > 0) {
+    items.push({ label: "All Capabilities", href: rootCapabilitiesHash(rootId) });
+    for (const f of capFiles) {
+      items.push({ label: prettify(f.name), href: rootCapabilityHash(rootId, f.path) });
+    }
+  }
+
+  return items;
+}
+
+/** Render a prev/next navigation bar given the full sequence and current href. */
+function makePageNav(sequence: NavItem[], currentHref: string): HTMLElement | null {
+  const idx = sequence.findIndex(item => item.href === currentHref);
+  if (idx === -1) return null;
+  const prev = idx > 0 ? sequence[idx - 1] : null;
+  const next = idx < sequence.length - 1 ? sequence[idx + 1] : null;
+  if (!prev && !next) return null;
+
+  const nav = el("nav", "page-nav");
+  if (prev) {
+    const a = el("a", "page-nav-prev") as HTMLAnchorElement;
+    (a as HTMLAnchorElement).href = prev.href;
+    a.innerHTML =
+      `<span class="page-nav-arrow">←</span>` +
+      `<span class="page-nav-label">${prev.label}</span>`;
+    nav.appendChild(a);
+  } else {
+    nav.appendChild(el("span", "page-nav-spacer"));
+  }
+  if (next) {
+    const a = el("a", "page-nav-next") as HTMLAnchorElement;
+    (a as HTMLAnchorElement).href = next.href;
+    a.innerHTML =
+      `<span class="page-nav-label">${next.label}</span>` +
+      `<span class="page-nav-arrow">→</span>`;
+    nav.appendChild(a);
+  }
+  return nav;
+}
+
+/** Compute rootCapabilitiesHash inline (mirrors the sidebar helper). */
+function rootCapabilitiesHash(rootId: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/capabilities`;
+}
+
+function visibleDocsTree(tree: TreeNode[]): TreeNode[] {
+  return tree
+    .filter((node) => {
+      if (node.type === "file") return node.name.endsWith(".md");
+      if (node.name === "capabilities" || node.name === "assets") return false;
+      return visibleDocsTree(node.children).length > 0;
+    })
+    .map((node) => {
+      if (node.type === "file") return node;
+      return { ...node, children: visibleDocsTree(node.children) };
+    });
+}
+
+function visibleMarkdownFiles(tree: TreeNode[]): TreeNode[] {
+  const out: TreeNode[] = [];
+  const walk = (nodes: TreeNode[]) => {
+    for (const node of visibleDocsTree(nodes)) {
+      if (node.type === "file") out.push(node);
+      else walk(node.children);
+    }
+  };
+  walk(tree);
+  return out;
+}
+
+function rootDocHash(rootId: string, path: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/docs/${encodeURIComponent(path)}`;
+}
+
+function rootCapabilityHash(rootId: string, path: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/capabilities/${encodeURIComponent(path)}`;
+}
+
+function rootBoardsHash(rootId: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/boards`;
+}
+
+function rootBoardHash(rootId: string, boardId: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/boards/${encodeURIComponent(boardId)}`;
+}
+
+function projectWikiHash(projectId: string): string {
+  return `#/project/${encodeURIComponent(projectId)}`;
+}
+
+function directoryWikiHash(rootId: string, dirPath: string): string {
+  return `#/root/${encodeURIComponent(rootId)}/directory/${encodeURIComponent(dirPath)}`;
+}
+
+function currentRootIdFromHash(hash: string): string | null {
+  const match = hash.match(/^#\/root\/([^/]+)/);
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+function firstHeading(md: string): string | null {
+  return md.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? null;
+}
+
+function searchTerms(query: string): string[] {
+  return [...new Set(query.trim().split(/\s+/).map(normalizeSearchText).filter(Boolean))];
+}
+
+function appendHighlightedText(parent: HTMLElement, text: string, terms: string[]): void {
+  const needles = terms.filter(Boolean).sort((a, b) => b.length - a.length);
+  if (needles.length === 0) {
+    parent.textContent = text;
+    return;
+  }
+
+  const re = new RegExp(`(${needles.map(escapeRegExp).join("|")})`, "ig");
+  let lastIndex = 0;
+  for (const match of text.matchAll(re)) {
+    const index = match.index ?? 0;
+    if (index > lastIndex) parent.appendChild(document.createTextNode(text.slice(lastIndex, index)));
+    const mark = document.createElement("mark");
+    mark.textContent = match[0];
+    parent.appendChild(mark);
+    lastIndex = index + match[0].length;
+  }
+  if (lastIndex < text.length) parent.appendChild(document.createTextNode(text.slice(lastIndex)));
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function firstParagraph(chunks: SearchChunk[]): string {
+  return chunks.find((chunk) => chunk.kind === "text" && chunk.text.length > 0)?.text.slice(0, 180) ?? "";
+}
+
+function searchChunksFromMarkdown(md: string): SearchChunk[] {
+  const body = md.replace(/^---[\s\S]*?---\s*/, "");
+  const lines = body.split("\n");
+  const chunks: SearchChunk[] = [];
+  let heading = "";
+  let paragraph: string[] = [];
+
+  const push = (text: string, kind: SearchChunk["kind"] = "text", explicitHeading = heading) => {
+    const clean = cleanMarkdownText(text);
+    if (!clean) return;
+    chunks.push({ heading: explicitHeading, text: clean, normalized: normalizeSearchText(clean), kind });
+  };
+  const flushParagraph = () => {
+    if (paragraph.length === 0) return;
+    push(paragraph.join(" "), "text");
+    paragraph = [];
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const fence = raw.match(/^(`{3,})\s*([\w-]+)?\s*$/);
+    if (fence) {
+      flushParagraph();
+      const fenceLen = fence[1].length;
+      const lang = (fence[2] ?? "").toLowerCase();
+      const closeRe = new RegExp("^`{" + fenceLen + ",}\\s*$");
+      const buf: string[] = [];
+      i++;
+      while (i < lines.length && !closeRe.test(lines[i])) {
+        buf.push(lines[i]);
+        i++;
+      }
+      push(lang === "board" ? boardBlockSearchText(buf.join("\n")) : buf.join("\n"), lang === "board" ? "board" : "code");
+      continue;
+    }
+
+    const headingMatch = raw.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      flushParagraph();
+      heading = cleanMarkdownText(headingMatch[2]);
+      push(heading, "heading", heading);
+      continue;
+    }
+
+    if (raw.trim() === "" || /^(-{3,}|\*{3,}|_{3,})\s*$/.test(raw)) {
+      flushParagraph();
+      continue;
+    }
+
+    if (isTableSeparator(raw)) continue;
+
+    const line = raw
+      .replace(/^>\s?/, "")
+      .replace(/^\s*([-*+]|\d+\.)\s+/, "")
+      .replace(/^\[([ xX])\]\s+/, "")
+      .replace(/\|/g, " ");
+    paragraph.push(line);
+  }
+  flushParagraph();
+  return chunks;
+}
+
+function boardBlockSearchText(block: string): string {
+  return block
+    .split("\n")
+    .map((line) => line.replace(/#.*$/, "").trim())
+    .filter(Boolean)
+    .map((line) => line.replace(/^(\w+)\s*:\s*/, "$1 "))
+    .join(" ");
+}
+
+function allMarkdownFiles(tree: TreeNode[]): Array<Extract<TreeNode, { type: "file" }>> {
+  const out: Array<Extract<TreeNode, { type: "file" }>> = [];
+  const walk = (nodes: TreeNode[]) => {
+    for (const node of nodes) {
+      if (node.type === "file") {
+        if (node.name.endsWith(".md")) out.push(node);
+      } else {
+        walk(node.children);
+      }
+    }
+  };
+  walk(tree);
+  return out;
+}
+
+function allBoardFiles(tree: TreeNode[]): Array<Extract<TreeNode, { type: "file" }>> {
+  const out: Array<Extract<TreeNode, { type: "file" }>> = [];
+  const walk = (nodes: TreeNode[]) => {
+    for (const node of nodes) {
+      if (node.type === "file") {
+        if (node.name.endsWith(".board.json")) out.push(node);
+      } else {
+        walk(node.children);
+      }
+    }
+  };
+  walk(tree);
+  return out;
+}
+
+function boardIdsUnderDirectory(tree: TreeNode[], dirPath: string): string[] {
+  const normalized = dirPath.replace(/^\/+|\/+$/g, "");
+  return allBoardFiles(tree)
+    .map((node) => boardIdFromFilePath(node.path))
+    .filter((id) => id === normalized || id.startsWith(`${normalized}/`));
+}
+
+function docsUnderDirectory(tree: TreeNode[], dirPath: string): Array<Extract<TreeNode, { type: "file" }>> {
+  const normalized = dirPath.replace(/^\/+|\/+$/g, "");
+  return allMarkdownFiles(tree).filter((doc) => doc.path.startsWith(`${normalized}/`));
+}
+
+function rewriteBoardEmbedsForDocMove(
+  markdown: string,
+  oldDocPath: string,
+  newDocPath: string,
+  boardIds: Set<string>
+): string {
+  if (oldDocPath === newDocPath) return markdown;
+  const lines = markdown.split("\n");
+  let inBoardFence = false;
+  let closeFence: RegExp | undefined;
+  let changed = false;
+
+  const next = lines.map((line) => {
+    if (!inBoardFence) {
+      const open = line.match(/^(`{3,})\s*board\s*$/i);
+      if (open) {
+        inBoardFence = true;
+        closeFence = new RegExp("^`{" + open[1].length + ",}\\s*$");
+      }
+      return line;
+    }
+
+    if (closeFence?.test(line)) {
+      inBoardFence = false;
+      closeFence = undefined;
+      return line;
+    }
+
+    const src = line.match(/^(\s*src\s*:\s*)(.*)$/i);
+    if (!src) return line;
+
+    const parsed = splitBoardSrcValue(src[2]);
+    if (!parsed.value) return line;
+    const moved = formatBoardSrcForDocMove(parsed.value, oldDocPath, newDocPath, boardIds);
+    if (moved === parsed.value) return line;
+
+    changed = true;
+    return `${src[1]}${moved}${parsed.suffix}`;
+  });
+
+  return changed ? next.join("\n") : markdown;
+}
+
+function rewriteBoardEmbedSources(markdown: string, docPath: string, oldBoardId: string, newBoardId: string): string {
+  const lines = markdown.split("\n");
+  let inBoardFence = false;
+  let closeFence: RegExp | undefined;
+  let changed = false;
+
+  const next = lines.map((line) => {
+    if (!inBoardFence) {
+      const open = line.match(/^(`{3,})\s*board\s*$/i);
+      if (open) {
+        inBoardFence = true;
+        closeFence = new RegExp("^`{" + open[1].length + ",}\\s*$");
+      }
+      return line;
+    }
+
+    if (closeFence?.test(line)) {
+      inBoardFence = false;
+      closeFence = undefined;
+      return line;
+    }
+
+    const src = line.match(/^(\s*src\s*:\s*)(.*)$/i);
+    if (!src) return line;
+
+    const parsed = splitBoardSrcValue(src[2]);
+    if (!parsed.value) return line;
+    const candidates = resolveBoardIdCandidatesFromDoc(parsed.value, docPath);
+    if (!candidates.includes(oldBoardId)) return line;
+
+    changed = true;
+    return `${src[1]}${formatMovedBoardSrc(parsed.value, docPath, oldBoardId, newBoardId)}${parsed.suffix}`;
+  });
+
+  return changed ? next.join("\n") : markdown;
+}
+
+function splitBoardSrcValue(rest: string): { value: string; suffix: string } {
+  const commentIndex = rest.indexOf("#");
+  const beforeComment = commentIndex === -1 ? rest : rest.slice(0, commentIndex);
+  const suffix = commentIndex === -1 ? "" : rest.slice(commentIndex);
+  const trailing = beforeComment.match(/\s*$/)?.[0] ?? "";
+  return {
+    value: beforeComment.trim(),
+    suffix: `${trailing}${suffix}`,
+  };
+}
+
+function formatMovedBoardSrc(previousSrc: string, docPath: string, oldBoardId: string, newBoardId: string): string {
+  const normalizedPrevious = previousSrc.trim();
+  const explicitRootPrefix = normalizedPrevious.startsWith("/");
+  const explicitRelative = normalizedPrevious.startsWith("./") || normalizedPrevious.startsWith("../");
+  const hadExtension = normalizedPrevious.endsWith(".board.json");
+  const candidates = resolveBoardIdCandidatesFromDoc(normalizedPrevious, docPath);
+  const matchedAsFallbackRelative = !explicitRelative && candidates[0] !== oldBoardId && candidates.includes(oldBoardId);
+
+  if (explicitRootPrefix) {
+    const next = `/${newBoardId}`;
+    return hadExtension && !next.endsWith(".board.json") ? `${next}.board.json` : next;
+  }
+
+  let next = explicitRelative || matchedAsFallbackRelative
+    ? formatExplicitRelativeBoardSrc(relativePathBetween(docPath, newBoardId))
+    : newBoardId;
+  if (hadExtension && !next.endsWith(".board.json")) next = `${next}.board.json`;
+  return next;
+}
+
+function formatBoardSrcForDocMove(
+  previousSrc: string,
+  oldDocPath: string,
+  newDocPath: string,
+  boardIds: Set<string>
+): string {
+  const normalizedPrevious = previousSrc.trim();
+  const explicitRelative = normalizedPrevious.startsWith("./") || normalizedPrevious.startsWith("../");
+  const candidates = resolveBoardIdCandidatesFromDoc(normalizedPrevious, oldDocPath);
+  const primary = candidates[0] ?? "";
+  const fallback = candidates.find((id) => id !== primary && boardIds.has(id));
+  if (!explicitRelative && (!fallback || boardIds.has(primary))) {
+    return previousSrc;
+  }
+
+  const hadExtension = normalizedPrevious.endsWith(".board.json");
+  const boardId = explicitRelative ? resolveBoardIdFromDoc(normalizedPrevious, oldDocPath) : fallback;
+  if (!boardId) return previousSrc;
+
+  let next = formatExplicitRelativeBoardSrc(relativePathBetween(newDocPath, boardId));
+  if (hadExtension && !next.endsWith(".board.json")) next = `${next}.board.json`;
+  return next;
+}
+
+function formatExplicitRelativeBoardSrc(src: string): string {
+  if (!src || src.startsWith("./") || src.startsWith("../")) return src;
+  return `./${src}`;
+}
+
+function cleanMarkdownText(text: string): string {
+  return text
+    .replace(/!\[([^\]]*)\]\(([^)]+)\)/g, "$1 $2")
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1 $2")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/~~([\s\S]*?)~~/g, "$1")
+    .replace(/\*\*\*([\s\S]*?)\*\*\*/g, "$1")
+    .replace(/___([\s\S]*?)___/g, "$1")
+    .replace(/\*\*([\s\S]*?)\*\*/g, "$1")
+    .replace(/__([\s\S]*?)__/g, "$1")
+    .replace(/(^|[\s([{])\*([^*\s][\s\S]*?[^*\s])\*(?=$|[\s)\]},.!?:;])/g, "$1$2")
+    .replace(/(^|[\s([{])_([^_\s][\s\S]*?[^_\s])_(?=$|[\s)\]},.!?:;])/g, "$1$2")
+    .replace(/\\([\\`*_[\]{}()#+\-.!|>])/g, "$1")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/(^|[\s([{])[*_]{1,3}(?=\S)/g, "$1")
+    .replace(/(?<=\S)[*_]{1,3}(?=$|[\s)\]},.!?:;])/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function normalizeSearchText(text: string): string {
+  return text
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function scoreText(text: string, terms: string[], phrase: string, weight: number): number {
+  if (!text) return 0;
+  let score = phrase && text.includes(phrase) ? weight * 4 : 0;
+  for (const term of terms) {
+    if (text === term) score += weight * 5;
+    if (text.startsWith(term)) score += weight * 3;
+    if (text.includes(term)) score += weight;
+  }
+  return score;
+}
+
+function chunkPreview(text: string, terms: string[]): string {
+  if (terms.length === 0) return text.slice(0, 220);
+  const normalizedText = normalizeSearchText(text);
+  const hit = terms
+    .map((term) => normalizedText.indexOf(term))
+    .filter((idx) => idx >= 0)
+    .sort((a, b) => a - b)[0];
+  if (hit === undefined) return text.slice(0, 220);
+
+  const ratio = normalizedText.length === 0 ? 0 : hit / normalizedText.length;
+  const center = Math.round(text.length * ratio);
+  const start = Math.max(0, center - 90);
+  const end = Math.min(text.length, center + 170);
+  const snippet = text.slice(start, end).trim();
+  return `${start > 0 ? "... " : ""}${snippet}${end < text.length ? " ..." : ""}`;
+}
+
+function isTableSeparator(line: string): boolean {
+  return /^\s*\|?\s*:?-{1,}:?\s*(\|\s*:?-{1,}:?\s*)*\|?\s*$/.test(line);
+}
+
+function prettify(name: string): string {
+  const base = name.replace(/\.md$/, "").replace(/[-_]/g, " ");
+  return base.charAt(0).toUpperCase() + base.slice(1);
+}
+
+function slugName(name: string): string {
+  return name
+    .trim()
+    .replace(/[\\/]+/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9-_]/gi, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .toLowerCase();
+}
+
+type NameKind = "directory" | "doc" | "board";
+type NameValidationResult =
+  | { ok: true; raw: string; slug: string }
+  | { ok: false; message: string };
+
+const RESERVED_NEW_ITEM_NAMES = new Set([
+  ".",
+  "..",
+  "assets",
+  "boards",
+  "capabilities",
+  "docs",
+]);
+
+function validateNewItemName(input: string, kind: NameKind): NameValidationResult {
+  const label = kind === "doc" ? "doc" : kind;
+  const raw = input.trim();
+  if (!raw) return { ok: false, message: `Enter a ${label} name.` };
+  if (raw.length > 80) return { ok: false, message: "Name must be 80 characters or fewer." };
+  if (/[\\/]/.test(raw)) return { ok: false, message: "Name cannot contain slashes." };
+  if (/^\.+$/.test(raw)) return { ok: false, message: "Name cannot contain only dots." };
+  if (raw.startsWith(".")) return { ok: false, message: "Name cannot start with a dot." };
+  if (/[<>:"|?*\x00-\x1F]/.test(raw)) return { ok: false, message: "Name contains characters that are not allowed in files." };
+
+  const slug = slugName(raw);
+  if (!slug) return { ok: false, message: "Name must include letters or numbers." };
+  if (slug.length > 64) return { ok: false, message: "Name is too long after formatting." };
+  if (RESERVED_NEW_ITEM_NAMES.has(slug)) return { ok: false, message: `"${slug}" is reserved by the workspace.` };
+  if (!/[a-z0-9]/.test(slug)) return { ok: false, message: "Name must include letters or numbers." };
+  return { ok: true, raw, slug };
+}
+
+function pathBasename(path: string): string {
+  const clean = path.replace(/^\/+|\/+$/g, "");
+  return clean.split("/").pop() ?? clean;
+}
+
+function parentPath(path: string): string {
+  const clean = path.replace(/^\/+|\/+$/g, "");
+  const idx = clean.lastIndexOf("/");
+  return idx === -1 ? "" : clean.slice(0, idx);
+}
+
+function joinPath(dir: string, name: string): string {
+  const cleanDir = dir.replace(/^\/+|\/+$/g, "");
+  const cleanName = name.replace(/^\/+|\/+$/g, "");
+  return cleanDir ? `${cleanDir}/${cleanName}` : cleanName;
+}
+
+function parseBoardRegion(query: string | undefined): BoardRegion | undefined {
+  if (!query) return undefined;
+  const raw = new URLSearchParams(query).get("region");
+  if (!raw) return undefined;
+  const nums = raw.split(",").map((n) => Number(n.trim()));
+  if (nums.length !== 4 || nums.some((n) => !Number.isFinite(n)) || nums[2] <= 0 || nums[3] <= 0) {
+    return undefined;
+  }
+  return [nums[0], nums[1], nums[2], nums[3]];
+}