From 20c7159fa05483385450550fa66bbed2a0fe5272 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 13:20:35 -0500
Subject: [PATCH 01/19] feat(site): CAVE theme + per-page Copy/Open-in-LLM
 dropdown
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CAVE theme (custom.css):
- Bioluminescent green accent (#3aff9d) on void-black
- Geist + JetBrains Mono fonts
- Sidebar tool prefixes (fs, ft, fl…), CAVE footer chip, themed code blocks
- Designed by Claude Design; wired in by overlaying real Starlight DOM
- Old custom.css preserved as custom_backup.css for rollback safety

Page actions widget (mirrors Anthropic/Mintlify 'Copy page' dropdown):
- Inline with the page H1, top-right of every doc (hidden on splash hero)
- Pill button: 'Copy page' (fetches .md, writes to clipboard) + caret toggle
- Dropdown items:
    · Copy as Markdown — page source for LLMs
    · Copy as plain text — rendered body
    · View as Markdown — opens .md in new tab
    · Open in Claude — claude.ai/new?q=<encoded prompt + markdown>
    · Open in ChatGPT — chatgpt.com/?hints=search&q=<same>
    · View source on GitHub — direct link to the source MDX
- Vanilla DOM controller, no framework deps
- ARIA: real menuitem roles, Escape closes, click-outside closes, keyboard nav
- CAVE-themed: matches button border, accent green on hover, animated open

Markdown endpoint (src/pages/[...slug].md.ts):
- Astro endpoint enumerated via getStaticPaths from the docs collection
- Returns YAML frontmatter (title, description) + raw body as text/markdown
- Cache-Control: 5 minutes
- Powers Copy/View/Open actions; safe for LLM consumption

Wired via Starlight component override in astro.config.mjs:
  components: { PageTitle: './src/components/PageTitle.astro' }

Validated locally:
- All 6 menu items render with correct data-action attrs
- /fsuite/<slug>.md returns HTTP 200, content-type text/markdown
- GitHub source URL points to ./site/src/content/docs/<slug>.mdx
- Hot-reload working through dev server
---
 site/astro.config.mjs                 |   5 +
 site/src/components/PageActions.astro | 324 ++++++++++++
 site/src/components/PageTitle.astro   |  26 +
 site/src/pages/[...slug].md.ts        |  52 ++
 site/src/styles/custom.css            | 723 +++++++++++++++++++++++++-
 site/src/styles/custom_backup.css     |  38 ++
 6 files changed, 1145 insertions(+), 23 deletions(-)
 create mode 100644 site/src/components/PageActions.astro
 create mode 100644 site/src/components/PageTitle.astro
 create mode 100644 site/src/pages/[...slug].md.ts
 create mode 100644 site/src/styles/custom_backup.css

diff --git a/site/astro.config.mjs b/site/astro.config.mjs
index 22d4aa7..13757b1 100644
--- a/site/astro.config.mjs
+++ b/site/astro.config.mjs
@@ -14,6 +14,11 @@ export default defineConfig({
         src: './src/assets/fsuite-hero.jpeg',
         replacesTitle: false,
       },
+      components: {
+        // Override the page H1 so we can render the page-actions dropdown
+        // (Copy / View / Open in LLM) inline with the title.
+        PageTitle: './src/components/PageTitle.astro',
+      },
       social: [
         { icon: 'github', label: 'GitHub', href: 'https://github.com/lliWcWill/fsuite' },
       ],
diff --git a/site/src/components/PageActions.astro b/site/src/components/PageActions.astro
new file mode 100644
index 0000000..6f935cd
--- /dev/null
+++ b/site/src/components/PageActions.astro
@@ -0,0 +1,324 @@
+---
+/**
+ * PageActions.astro — page-level action dropdown (Copy / View / Open in LLM).
+ *
+ * Sits inline with the page H1 in the right-aligned position, mirroring
+ * Mintlify/Anthropic's `Copy page` widget. CAVE-themed pill design.
+ *
+ * Props are pulled from Starlight's route data — no caller plumbing needed.
+ *
+ * Behaviour:
+ *   - Main button:      Copy page as Markdown (fetches <url>.md, writes clipboard)
+ *   - Caret dropdown:
+ *       · Copy as Markdown
+ *       · Copy as plain text
+ *       · View as Markdown (opens .md URL)
+ *       · Open in Claude     (claude.ai/new?q=...)
+ *       · Open in ChatGPT    (chatgpt.com/?q=...)
+ *       · View source on GitHub
+ *
+ * Accessibility:
+ *   - Real <button> elements + ARIA roles (menu, menuitem)
+ *   - Keyboard: Enter/Space toggles, Escape closes, click-outside closes
+ */
+
+const route = Astro.locals.starlightRoute;
+const entry = route?.entry;
+const slug = entry?.id?.replace(/\.(md|mdx)$/i, '') ?? '';
+const title = entry?.data?.title ?? '';
+
+// Build URLs using the runtime origin so it works on lliwcwill.github.io,
+// localhost:4321, or any preview deployment.
+// We emit a relative `.md` URL so the script can resolve against window.location.
+const mdRelative = slug ? `/${slug}.md` : '';
+
+// GitHub source URL — assumes master branch + the canonical path layout.
+// If the entry is `index.mdx`, the slug is empty; map back to the file.
+const ghBase = 'https://github.com/lliWcWill/fsuite/blob/master/site/src/content/docs';
+const ghSourcePath = slug ? `${slug}.mdx` : 'index.mdx';
+const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
+---
+
+<div
+  class="page-actions"
+  data-page-actions
+  data-md-relative={mdRelative}
+  data-page-title={title}
+  data-gh-source={ghSourceUrl}
+>
+  <button
+    type="button"
+    class="page-actions__primary"
+    data-action="copy-md"
+    aria-label="Copy page as Markdown"
+  >
+    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 18 18" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <path d="M14.25 5.25H7.25C6.14543 5.25 5.25 6.14543 5.25 7.25V14.25C5.25 15.3546 6.14543 16.25 7.25 16.25H14.25C15.3546 16.25 16.25 15.3546 16.25 14.25V7.25C16.25 6.14543 15.3546 5.25 14.25 5.25Z" />
+      <path d="M2.80103 11.998L1.77203 5.07397C1.61003 3.98097 2.36403 2.96397 3.45603 2.80197L10.38 1.77297C11.313 1.63397 12.19 2.16297 12.528 3.00097" />
+    </svg>
+    <span class="page-actions__label">Copy page</span>
+  </button>
+
+  <button
+    type="button"
+    class="page-actions__caret"
+    data-action="toggle-menu"
+    aria-haspopup="menu"
+    aria-expanded="false"
+    aria-label="More page actions"
+  >
+    <svg xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="0 0 12 12" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <path d="M3 4.5L6 7.5L9 4.5" />
+    </svg>
+  </button>
+
+  <div class="page-actions__menu" role="menu" hidden>
+    <button type="button" role="menuitem" data-action="copy-md">
+      <span class="page-actions__menu-icon">📄</span>
+      <span class="page-actions__menu-text">
+        <span class="page-actions__menu-title">Copy as Markdown</span>
+        <span class="page-actions__menu-sub">Page source for LLMs</span>
+      </span>
+    </button>
+
+    <button type="button" role="menuitem" data-action="copy-plain">
+      <span class="page-actions__menu-icon">¶</span>
+      <span class="page-actions__menu-text">
+        <span class="page-actions__menu-title">Copy as plain text</span>
+        <span class="page-actions__menu-sub">Rendered body, no markup</span>
+      </span>
+    </button>
+
+    <button type="button" role="menuitem" data-action="view-md">
+      <span class="page-actions__menu-icon">⤴</span>
+      <span class="page-actions__menu-text">
+        <span class="page-actions__menu-title">View as Markdown</span>
+        <span class="page-actions__menu-sub">Open .md in new tab</span>
+      </span>
+    </button>
+
+    <hr class="page-actions__divider" />
+
+    <button type="button" role="menuitem" data-action="open-claude">
+      <span class="page-actions__menu-icon">◈</span>
+      <span class="page-actions__menu-text">
+        <span class="page-actions__menu-title">Open in Claude</span>
+        <span class="page-actions__menu-sub">Pre-loaded with this page</span>
+      </span>
+    </button>
+
+    <button type="button" role="menuitem" data-action="open-chatgpt">
+      <span class="page-actions__menu-icon">◇</span>
+      <span class="page-actions__menu-text">
+        <span class="page-actions__menu-title">Open in ChatGPT</span>
+        <span class="page-actions__menu-sub">Pre-loaded with this page</span>
+      </span>
+    </button>
+
+    <hr class="page-actions__divider" />
+
+    <a
+      role="menuitem"
+      href={ghSourceUrl}
+      target="_blank"
+      rel="noopener noreferrer"
+      data-action="view-source"
+    >
+      <span class="page-actions__menu-icon">⌥</span>
+      <span class="page-actions__menu-text">
+        <span class="page-actions__menu-title">View source on GitHub</span>
+        <span class="page-actions__menu-sub">Edit + raise a PR</span>
+      </span>
+    </a>
+  </div>
+
+  <div class="page-actions__toast" role="status" aria-live="polite" hidden></div>
+</div>
+
+<script>
+  // Self-contained controller — runs once per page load.
+  // No frameworks; vanilla DOM + clipboard API + simple state machine.
+
+  type Action =
+    | 'copy-md'
+    | 'copy-plain'
+    | 'view-md'
+    | 'open-claude'
+    | 'open-chatgpt'
+    | 'toggle-menu';
+
+  function init(root: HTMLElement) {
+    const mdRelative = root.dataset.mdRelative ?? '';
+    const pageTitle = root.dataset.pageTitle ?? 'this page';
+    const menu = root.querySelector<HTMLElement>('.page-actions__menu')!;
+    const caret = root.querySelector<HTMLButtonElement>('[data-action="toggle-menu"]')!;
+    const toast = root.querySelector<HTMLElement>('.page-actions__toast')!;
+
+    const showToast = (msg: string, ok = true) => {
+      toast.textContent = msg;
+      toast.dataset.tone = ok ? 'ok' : 'err';
+      toast.hidden = false;
+      window.setTimeout(() => {
+        toast.hidden = true;
+      }, 1800);
+    };
+
+    const closeMenu = () => {
+      menu.hidden = true;
+      caret.setAttribute('aria-expanded', 'false');
+      root.dataset.menuOpen = 'false';
+    };
+
+    const openMenu = () => {
+      menu.hidden = false;
+      caret.setAttribute('aria-expanded', 'true');
+      root.dataset.menuOpen = 'true';
+    };
+
+    const toggleMenu = () => {
+      menu.hidden ? openMenu() : closeMenu();
+    };
+
+    const buildMdUrl = (): string => {
+      // Resolve the relative .md path against the current origin + base path.
+      // window.location.pathname is e.g. /fsuite/architecture/mcp/ — strip
+      // trailing slash and append .md (or use the slug-based mdRelative).
+      if (mdRelative) {
+        return new URL(mdRelative, window.location.origin + (window.location.pathname.split('/')[1] ? `/${window.location.pathname.split('/')[1]}` : '')).toString();
+      }
+      // Fallback: derive from current pathname.
+      const path = window.location.pathname.replace(/\/$/, '');
+      return `${window.location.origin}${path}.md`;
+    };
+
+    const fetchMarkdown = async (): Promise<string> => {
+      const url = buildMdUrl();
+      const res = await fetch(url, { headers: { Accept: 'text/markdown, text/plain' } });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      return await res.text();
+    };
+
+    const copyToClipboard = async (text: string): Promise<void> => {
+      if (navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(text);
+        return;
+      }
+      // Fallback for non-secure contexts.
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.position = 'fixed';
+      ta.style.opacity = '0';
+      document.body.appendChild(ta);
+      ta.select();
+      document.execCommand('copy');
+      document.body.removeChild(ta);
+    };
+
+    const promptForLLM = (md: string): string => {
+      const trimmed = md.length > 4000 ? md.slice(0, 4000) + '\n\n...[truncated]' : md;
+      return `Please read this fsuite documentation page and help me understand it.\n\nPage: ${pageTitle}\nSource: ${buildMdUrl()}\n\n---\n\n${trimmed}`;
+    };
+
+    const handleAction = async (action: Action, ev?: Event) => {
+      switch (action) {
+        case 'toggle-menu':
+          toggleMenu();
+          return;
+
+        case 'copy-md': {
+          try {
+            const md = await fetchMarkdown();
+            await copyToClipboard(md);
+            showToast('Markdown copied');
+          } catch (err) {
+            showToast('Copy failed', false);
+            console.error('[page-actions] copy-md', err);
+          } finally {
+            closeMenu();
+          }
+          return;
+        }
+
+        case 'copy-plain': {
+          try {
+            // Walk the rendered article and grab text. Astro/Starlight wraps
+            // the body in a <main> with the article inside; we grab from
+            // the closest H1 down so user sees what they'd read.
+            const article = document.querySelector('main .sl-markdown-content, main article, main') as HTMLElement | null;
+            const text = (article?.innerText ?? document.body.innerText ?? '').trim();
+            await copyToClipboard(text);
+            showToast('Plain text copied');
+          } catch (err) {
+            showToast('Copy failed', false);
+            console.error('[page-actions] copy-plain', err);
+          } finally {
+            closeMenu();
+          }
+          return;
+        }
+
+        case 'view-md': {
+          window.open(buildMdUrl(), '_blank', 'noopener,noreferrer');
+          closeMenu();
+          return;
+        }
+
+        case 'open-claude': {
+          try {
+            const md = await fetchMarkdown();
+            const q = encodeURIComponent(promptForLLM(md));
+            window.open(`https://claude.ai/new?q=${q}`, '_blank', 'noopener,noreferrer');
+          } catch {
+            // Fallback: just hand Claude the URL.
+            const q = encodeURIComponent(`Please read ${buildMdUrl()} and help me understand it.`);
+            window.open(`https://claude.ai/new?q=${q}`, '_blank', 'noopener,noreferrer');
+          } finally {
+            closeMenu();
+          }
+          return;
+        }
+
+        case 'open-chatgpt': {
+          try {
+            const md = await fetchMarkdown();
+            const q = encodeURIComponent(promptForLLM(md));
+            window.open(`https://chatgpt.com/?hints=search&q=${q}`, '_blank', 'noopener,noreferrer');
+          } catch {
+            const q = encodeURIComponent(`Please read ${buildMdUrl()} and help me understand it.`);
+            window.open(`https://chatgpt.com/?hints=search&q=${q}`, '_blank', 'noopener,noreferrer');
+          } finally {
+            closeMenu();
+          }
+          return;
+        }
+      }
+    };
+
+    // Wire up: any element with data-action inside this root.
+    root.addEventListener('click', (ev) => {
+      const target = (ev.target as HTMLElement).closest<HTMLElement>('[data-action]');
+      if (!target) return;
+      const action = target.dataset.action as Action | undefined;
+      if (!action) return;
+      // <a data-action="view-source"> is a real link — let the browser handle it.
+      if (action === ('view-source' as Action)) return;
+      ev.preventDefault();
+      handleAction(action, ev);
+    });
+
+    // Click-outside closes menu.
+    document.addEventListener('click', (ev) => {
+      if (!menu.hidden && !root.contains(ev.target as Node)) closeMenu();
+    });
+
+    // Escape closes menu.
+    document.addEventListener('keydown', (ev) => {
+      if (ev.key === 'Escape' && !menu.hidden) {
+        closeMenu();
+        caret.focus();
+      }
+    });
+  }
+
+  document.querySelectorAll<HTMLElement>('[data-page-actions]').forEach(init);
+</script>
diff --git a/site/src/components/PageTitle.astro b/site/src/components/PageTitle.astro
new file mode 100644
index 0000000..a30c966
--- /dev/null
+++ b/site/src/components/PageTitle.astro
@@ -0,0 +1,26 @@
+---
+/**
+ * PageTitle.astro — Starlight component override.
+ *
+ * Renders the page H1 and the PageActions dropdown side-by-side on a single
+ * row. The H1 keeps Starlight's `id="_top"` so anchor links to the top of
+ * the page still work.
+ *
+ * Suppressed on the splash hero (Starlight handles its own title rendering
+ * for splash pages — checking entry.data.template avoids double titles).
+ */
+import PageActions from './PageActions.astro';
+
+const route = Astro.locals.starlightRoute;
+const title = route.entry.data.title;
+const isSplash = route.entry.data.template === 'splash';
+---
+
+{isSplash ? (
+  <h1 id="_top">{title}</h1>
+) : (
+  <div class="page-title-row">
+    <h1 id="_top">{title}</h1>
+    <PageActions />
+  </div>
+)}
diff --git a/site/src/pages/[...slug].md.ts b/site/src/pages/[...slug].md.ts
new file mode 100644
index 0000000..7d2fa47
--- /dev/null
+++ b/site/src/pages/[...slug].md.ts
@@ -0,0 +1,52 @@
+/**
+ * Raw markdown endpoint — serves the source MDX/MD body for any doc page.
+ *
+ * URL pattern: /fsuite/<slug>.md  (mirrors Anthropic/Mintlify's /<page>.md convention)
+ *
+ * Used by:
+ *   - "View as Markdown" → opens this URL in a new tab
+ *   - "Copy as Markdown" → fetches this URL and copies the body
+ *   - "Open in Claude/ChatGPT" → references this URL in the prefilled prompt
+ *
+ * Astro 5 endpoint contract: getStaticPaths() enumerates all docs entries,
+ * GET() returns the raw body with frontmatter stripped (or kept — we keep
+ * it because it's useful for LLM context).
+ */
+import type { APIRoute } from 'astro';
+import { getCollection, type CollectionEntry } from 'astro:content';
+
+export async function getStaticPaths() {
+  const docs = await getCollection('docs');
+  return docs.map((entry: CollectionEntry<'docs'>) => ({
+    params: { slug: entry.id.replace(/\.(md|mdx)$/i, '') },
+    props: { entry },
+  }));
+}
+
+export const GET: APIRoute = async ({ props }) => {
+  const entry = props.entry as CollectionEntry<'docs'>;
+
+  // Reconstruct a markdown source: YAML frontmatter (title + description) + body.
+  // We don't expose the full original frontmatter (could leak template-only fields);
+  // we only re-emit the human-meaningful fields so an LLM gets clean context.
+  const fm: Record<string, string | undefined> = {
+    title: entry.data.title,
+    description: entry.data.description,
+  };
+  const yaml = Object.entries(fm)
+    .filter(([, v]) => v !== undefined && v !== null && v !== '')
+    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+    .join('\n');
+
+  const header = yaml ? `---\n${yaml}\n---\n\n` : '';
+  const body = entry.body ?? '';
+
+  return new Response(header + body, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/markdown; charset=utf-8',
+      'Content-Disposition': 'inline',
+      'Cache-Control': 'public, max-age=300',
+    },
+  });
+};
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index c972787..407ff56 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -1,38 +1,715 @@
-/* fsuite docs — custom theme tweaks to match the Monokai vibe of the MCP output */
+/* ============================================================
+   fsuite — CAVE theme
+   Drop-in replacement for site/src/styles/custom.css
+   Bioluminescent green · void-black · drone POV
+   ============================================================
+   Compatible with: Astro Starlight 0.38+
+   Code theme: keep ExpressiveCode 'monokai' (already set in
+   astro.config.mjs) — these tokens harmonize with it.
+   ============================================================ */
 
+/* ---------- 1. FONTS ---------- */
+@import url('https://fonts.googleapis.com/css2?family=Geist:wght@300;400;500;600;700;800;900&family=JetBrains+Mono:wght@300;400;500;600;700&display=swap');
+
+/* ---------- 2. STARLIGHT TOKEN OVERRIDES (DARK) ---------- */
 :root {
-  /* Dark theme override — Monokai-ish accent */
-  --sl-color-accent-low: #3b2a1a;
-  --sl-color-accent: #fd971f;
-  --sl-color-accent-high: #ffd866;
+  /* Accent — bioluminescent green that matches the hero tree */
+  --sl-color-accent-low:  #0d3a26;
+  --sl-color-accent:      #3aff9d;
+  --sl-color-accent-high: #a8ffd4;
+
+  /* Surface — deep cave void */
+  --sl-color-white:   #e8f4ee;
+  --sl-color-gray-1:  #c9dad2;
+  --sl-color-gray-2:  #9eb1a8;
+  --sl-color-gray-3:  #6b8079;
+  --sl-color-gray-4:  #44544e;
+  --sl-color-gray-5:  #1c2a25;
+  --sl-color-gray-6:  #0f171c;
+  --sl-color-gray-7:  #0a1014;
+  --sl-color-black:   #05080a;
+
+  /* Background layers */
+  --sl-color-bg:           #0a1014;
+  --sl-color-bg-nav:       #0a1014;
+  --sl-color-bg-sidebar:   #0a1014;
+  --sl-color-bg-inline-code: #0a1418;
+
+  /* Text */
+  --sl-color-text:         #e8f4ee;
+  --sl-color-text-accent:  #3aff9d;
+  --sl-color-text-invert:  #051a10;
+
+  /* Hairlines / borders */
+  --sl-color-hairline:        rgba(120, 200, 170, 0.10);
+  --sl-color-hairline-light:  rgba(120, 200, 170, 0.18);
+  --sl-color-hairline-shade:  rgba(120, 200, 170, 0.30);
 
-  --sl-color-white: #f8f8f2;
-  --sl-color-gray-1: #e1e1db;
-  --sl-color-gray-2: #c5c5c0;
-  --sl-color-gray-3: #75715e;
-  --sl-color-gray-4: #49483e;
-  --sl-color-gray-5: #383830;
-  --sl-color-gray-6: #272822;
-  --sl-color-black: #1e1f1c;
+  /* Type */
+  --sl-font: "Geist", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --sl-font-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+
+  /* Custom fsuite tokens */
+  --fs-accent:       #3aff9d;
+  --fs-accent-soft:  #1f9a63;
+  --fs-accent-deep:  #0d3a26;
+  --fs-accent-glow:  rgba(58, 255, 180, 0.18);
+  --fs-warn:         #ffc857;
+  --fs-crit:         #ff5d5d;
+  --fs-info:         #7cd0ff;
+
+  --fs-bg-card:    #0f171c;
+  --fs-bg-card-hi: #131e24;
+  --fs-bg-card-on: #1a2830;
+
+  --fs-shadow-glow:
+    0 0 0 1px rgba(58, 255, 180, 0.20),
+    0 0 24px -4px rgba(58, 255, 180, 0.25);
+
+  --fs-scanline: repeating-linear-gradient(
+    0deg,
+    rgba(58, 255, 180, 0.018) 0px,
+    rgba(58, 255, 180, 0.018) 1px,
+    transparent 1px,
+    transparent 3px
+  );
 }
 
+/* Light mode — keep it sane and on-brand */
 :root[data-theme='light'] {
-  --sl-color-accent-low: #fef3c7;
-  --sl-color-accent: #d97706;
-  --sl-color-accent-high: #92400e;
+  --sl-color-accent-low:  #d6f7e6;
+  --sl-color-accent:      #0a8c52;
+  --sl-color-accent-high: #064a2c;
+  --sl-color-text-invert: #ffffff;
+
+  --fs-accent:       #0a8c52;
+  --fs-accent-soft:  #0a8c52;
+  --fs-accent-deep:  #d6f7e6;
+  --fs-accent-glow:  rgba(10, 140, 82, 0.15);
+
+  --fs-bg-card:    #ffffff;
+  --fs-bg-card-hi: #f7faf8;
+  --fs-bg-card-on: #eef5f1;
+  --fs-scanline: none;
 }
 
-/* Make the inline code stand out like terminal output */
-code {
+/* ---------- 3. BASE TYPOGRAPHY ---------- */
+html {
+  color-scheme: dark;
+  font-family: var(--sl-font);
+}
+body {
+  font-family: var(--sl-font);
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+/* Subtle volumetric glow + scanline over the page */
+body::before {
+  content: "";
+  position: fixed; inset: 0;
+  pointer-events: none;
+  z-index: 0;
+  background:
+    radial-gradient(1200px 600px at 50% -10%, rgba(58, 255, 180, 0.06), transparent 60%),
+    radial-gradient(900px 500px at 85% 30%, rgba(0, 140, 90, 0.04), transparent 60%),
+    var(--fs-scanline);
+}
+:root[data-theme='light'] body::before { display: none; }
+
+/* Headings — display-y, tight tracking */
+h1, h2, h3, h4 {
+  font-family: var(--sl-font);
+  letter-spacing: -0.02em;
+  font-weight: 700;
+  color: var(--sl-color-white);
+}
+h1 { letter-spacing: -0.035em; font-weight: 800; }
+
+/* ---------- 4. STARLIGHT NAV / HEADER ---------- */
+header.header {
+  background: color-mix(in oklab, var(--sl-color-bg) 85%, transparent) !important;
+  backdrop-filter: blur(10px) saturate(1.1);
+  -webkit-backdrop-filter: blur(10px) saturate(1.1);
+  border-bottom: 1px solid var(--sl-color-hairline);
+}
+
+/* Site title */
+.site-title {
+  font-family: var(--sl-font-mono) !important;
+  font-weight: 700 !important;
+  font-size: 14px !important;
+  letter-spacing: 0.02em !important;
+}
+
+/* Search input */
+site-search button[data-open-modal] {
+  background: var(--fs-bg-card) !important;
+  border: 1px solid var(--sl-color-hairline) !important;
+  border-radius: 8px !important;
+  transition: border-color 160ms, box-shadow 160ms;
+}
+site-search button[data-open-modal]:hover {
+  border-color: var(--sl-color-hairline-light) !important;
+}
+site-search button[data-open-modal]:focus-visible {
+  border-color: var(--sl-color-hairline-shade) !important;
+  box-shadow: var(--fs-shadow-glow) !important;
+}
+
+/* ---------- 5. SIDEBAR ---------- */
+.sidebar-pane {
+  border-right: 1px solid var(--sl-color-hairline);
+}
+.sidebar-content ul li a {
+  border-radius: 4px;
+  border-left: 2px solid transparent;
+  transition: background 160ms, color 160ms, border-color 160ms;
+}
+.sidebar-content ul li a:hover {
+  background: var(--fs-bg-card-hi);
+  color: var(--sl-color-white);
+}
+.sidebar-content ul li a[aria-current='page'] {
+  background: var(--fs-bg-card-on);
+  color: var(--fs-accent) !important;
+  border-left-color: var(--fs-accent);
   font-weight: 500;
 }
 
-/* Terminal-y feel for block quotes (callouts) */
-blockquote {
-  border-left-color: var(--sl-color-accent);
+/* Sidebar group titles — small caps mono with arrow bullet */
+.sidebar-content details > summary,
+.sidebar-content .group-label,
+.sidebar-content h2 {
+  font-family: var(--sl-font-mono) !important;
+  font-size: 10.5px !important;
+  letter-spacing: 0.16em !important;
+  text-transform: uppercase !important;
+  color: var(--sl-color-gray-2) !important;
+}
+
+/* ---------- 6. RIGHT TOC ---------- */
+.right-sidebar starlight-toc nav a {
+  border-left: 2px solid transparent;
+  padding-left: 10px;
+  margin-left: -2px;
+  transition: color 160ms, border-color 160ms;
+  color: var(--sl-color-gray-2);
+}
+.right-sidebar starlight-toc nav a:hover { color: var(--sl-color-white); }
+.right-sidebar starlight-toc nav a[aria-current='true'] {
+  color: var(--fs-accent);
+  border-left-color: var(--fs-accent);
+}
+.right-sidebar h2 {
+  font-family: var(--sl-font-mono) !important;
+  font-size: 10.5px !important;
+  letter-spacing: 0.16em !important;
+  text-transform: uppercase !important;
+  color: var(--sl-color-gray-2) !important;
 }
 
-/* Tighten the command-reference tables */
-table {
+/* ---------- 7. CONTENT — links, code, callouts ---------- */
+.sl-markdown-content a:not(:where(.not-content *)) {
+  color: var(--fs-accent);
+  text-decoration-color: rgba(58, 255, 180, 0.4);
+  text-underline-offset: 3px;
+  transition: text-decoration-color 160ms;
+}
+.sl-markdown-content a:hover { text-decoration-color: var(--fs-accent); }
+
+/* Inline code — terminal token feel */
+.sl-markdown-content :not(pre) > code {
+  font-family: var(--sl-font-mono);
+  font-size: 0.88em;
+  font-weight: 500;
+  background: var(--sl-color-bg-inline-code);
+  color: #c9e8d8;
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 3px;
+  padding: 1px 6px;
+}
+
+/* Code blocks (ExpressiveCode wrapper) */
+.expressive-code {
+  margin: 1.2em 0;
+}
+.expressive-code .frame {
+  border-radius: 8px !important;
+  border: 1px solid var(--sl-color-hairline-light) !important;
+  box-shadow:
+    0 1px 0 rgba(255, 255, 255, 0.02),
+    0 10px 30px -10px rgba(0, 0, 0, 0.6) !important;
+}
+
+/* Blockquote / callout — terminal-y left edge */
+.sl-markdown-content blockquote {
+  border-left: 3px solid var(--fs-accent);
+  background: linear-gradient(90deg, rgba(58, 255, 180, 0.05), transparent 60%);
+  padding: 12px 16px;
+  margin: 1.2em 0;
+  border-radius: 0 6px 6px 0;
+  color: var(--sl-color-gray-1);
+}
+.sl-markdown-content blockquote p { margin: 0; }
+.sl-markdown-content blockquote em { color: var(--sl-color-white); font-style: normal; }
+
+/* Tables — tighter, technical */
+.sl-markdown-content table {
   font-size: 0.92em;
+  border-collapse: separate;
+  border-spacing: 0;
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 6px;
+  overflow: hidden;
+}
+.sl-markdown-content thead {
+  background: var(--fs-bg-card-hi);
+}
+.sl-markdown-content th {
+  font-family: var(--sl-font-mono);
+  font-size: 11px !important;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-2) !important;
+  font-weight: 500 !important;
+  text-align: left;
+  padding: 12px 14px !important;
+  border-bottom: 1px solid var(--sl-color-hairline) !important;
+}
+.sl-markdown-content td {
+  padding: 12px 14px !important;
+  border-bottom: 1px solid var(--sl-color-hairline) !important;
+}
+.sl-markdown-content tbody tr:last-child td { border-bottom: 0 !important; }
+.sl-markdown-content tbody tr:hover { background: var(--fs-bg-card-hi); }
+.sl-markdown-content td code {
+  color: var(--fs-accent) !important;
+  font-weight: 600;
+}
+
+/* Horizontal rules */
+.sl-markdown-content hr {
+  border: 0;
+  height: 1px;
+  background: var(--sl-color-hairline);
+  margin: 2em 0;
+}
+
+/* ---------- 8. STARLIGHT <Card> + <CardGrid> ---------- */
+.sl-markdown-content .card {
+  background: var(--fs-bg-card) !important;
+  border: 1px solid var(--sl-color-hairline) !important;
+  border-radius: 8px !important;
+  padding: 22px !important;
+  transition: transform 200ms cubic-bezier(.2,.7,.3,1),
+              border-color 200ms, background 200ms;
+  position: relative;
+  overflow: hidden;
+}
+.sl-markdown-content .card::before {
+  content: "";
+  position: absolute; top: 0; left: 0;
+  width: 28px; height: 1px;
+  background: var(--fs-accent);
+  opacity: 0.6;
+}
+.sl-markdown-content .card:hover {
+  transform: translateY(-2px);
+  border-color: var(--sl-color-hairline-shade) !important;
+  background: var(--fs-bg-card-hi) !important;
+}
+.sl-markdown-content .card .icon {
+  color: var(--fs-accent) !important;
+  background: var(--fs-accent-deep) !important;
+  border: 1px solid color-mix(in oklab, var(--fs-accent) 35%, transparent) !important;
+  border-radius: 4px !important;
+  padding: 8px !important;
+}
+.sl-markdown-content .card .title {
+  font-size: 16px !important;
+  font-weight: 600 !important;
+  letter-spacing: -0.01em !important;
+  color: var(--sl-color-white) !important;
+}
+
+/* ---------- 9. HERO (splash template) ---------- */
+.hero {
+  padding: 56px 0 !important;
+  position: relative;
+}
+.hero h1 {
+  font-size: clamp(56px, 6.4vw, 88px) !important;
+  line-height: 0.95 !important;
+  letter-spacing: -0.035em !important;
+  font-weight: 800 !important;
+}
+.hero .tagline {
+  font-size: 19px !important;
+  color: var(--sl-color-gray-1) !important;
+  max-width: 52ch;
+  line-height: 1.5 !important;
+}
+.hero img {
+  border-radius: 12px;
+  border: 1px solid var(--sl-color-hairline-light);
+  box-shadow:
+    0 10px 30px -10px rgba(0, 0, 0, 0.7),
+    0 0 0 1px rgba(58, 255, 180, 0.08);
+}
+
+/* Hero buttons */
+.hero .actions a {
+  font-family: var(--sl-font-mono) !important;
+  font-size: 13px !important;
+  font-weight: 500 !important;
+  letter-spacing: 0.01em !important;
+  border-radius: 8px !important;
+  height: 42px;
+  padding: 0 18px !important;
+  transition: all 160ms cubic-bezier(.2,.7,.3,1);
+}
+.hero .actions a[data-variant="primary"] {
+  background: var(--fs-accent) !important;
+  color: #051a10 !important;
+  border: 1px solid var(--fs-accent) !important;
+  box-shadow: var(--fs-shadow-glow);
+}
+.hero .actions a[data-variant="primary"]:hover {
+  transform: translateY(-1px);
+  filter: brightness(1.08);
+}
+.hero .actions a[data-variant="secondary"],
+.hero .actions a:not([data-variant]) {
+  background: var(--fs-bg-card) !important;
+  color: var(--sl-color-white) !important;
+  border: 1px solid var(--sl-color-hairline-light) !important;
+}
+.hero .actions a[data-variant="secondary"]:hover {
+  background: var(--fs-bg-card-hi) !important;
+  border-color: var(--sl-color-hairline-shade) !important;
+}
+.hero .actions a[data-variant="minimal"] {
+  background: transparent !important;
+  color: var(--sl-color-gray-1) !important;
+  border: 1px solid transparent !important;
+}
+.hero .actions a[data-variant="minimal"]:hover {
+  color: var(--sl-color-white) !important;
+  background: var(--fs-bg-card) !important;
+}
+
+/* ---------- 10. PAGE TITLE / FRONTMATTER HEADER ---------- */
+.content-panel h1#_top,
+.content-panel h1:first-child {
+  letter-spacing: -0.03em;
+}
+
+/* ---------- 11. SCROLLBARS ---------- */
+* { scrollbar-width: thin; scrollbar-color: var(--sl-color-hairline-light) transparent; }
+::-webkit-scrollbar { width: 8px; height: 8px; }
+::-webkit-scrollbar-thumb {
+  background: var(--sl-color-hairline-light);
+  border-radius: 4px;
+}
+::-webkit-scrollbar-thumb:hover { background: var(--sl-color-hairline-shade); }
+
+/* ---------- 12. SELECTION ---------- */
+::selection {
+  background: var(--fs-accent);
+  color: #051a10;
+}
+
+/* ---------- 13. PAGINATION (next/prev links at page bottom) ---------- */
+.pagination-links a {
+  background: var(--fs-bg-card) !important;
+  border: 1px solid var(--sl-color-hairline) !important;
+  border-radius: 8px !important;
+  transition: border-color 160ms, background 160ms;
+}
+.pagination-links a:hover {
+  border-color: var(--sl-color-hairline-shade) !important;
+  background: var(--fs-bg-card-hi) !important;
+}
+.pagination-links a span:first-child {
+  font-family: var(--sl-font-mono) !important;
+  font-size: 10.5px !important;
+  letter-spacing: 0.14em !important;
+  text-transform: uppercase !important;
+  color: var(--fs-accent) !important;
+}
+
+/* ---------- 14. STARLIGHT KBD ---------- */
+kbd {
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  padding: 2px 6px;
+  background: var(--fs-bg-card);
+  border: 1px solid var(--sl-color-hairline-light);
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  color: var(--sl-color-gray-1);
+}
+
+/* ---------- 15. TABS COMPONENT (Starlight <Tabs>) ---------- */
+starlight-tabs [role="tablist"] {
+  border-bottom: 1px solid var(--sl-color-hairline) !important;
+}
+starlight-tabs [role="tab"][aria-selected="true"] {
+  color: var(--fs-accent) !important;
+  border-bottom-color: var(--fs-accent) !important;
+}
+
+/* ---------- 16. ASIDE / NOTE / TIP / CAUTION ---------- */
+.starlight-aside {
+  border-radius: 8px !important;
+  border-left-width: 3px !important;
+}
+.starlight-aside--note     { border-left-color: var(--fs-info) !important; }
+.starlight-aside--tip      { border-left-color: var(--fs-accent) !important; }
+.starlight-aside--caution  { border-left-color: var(--fs-warn) !important; }
+.starlight-aside--danger   { border-left-color: var(--fs-crit) !important; }
+
+/* ---------- 17. STEPS COMPONENT ---------- */
+.sl-steps > li::before {
+  background: var(--fs-accent-deep) !important;
+  color: var(--fs-accent) !important;
+  border: 1px solid color-mix(in oklab, var(--fs-accent) 40%, transparent) !important;
+  font-family: var(--sl-font-mono) !important;
+  font-weight: 600 !important;
+}
+
+/* ---------- 18. BADGE / PILL ---------- */
+.sl-badge {
+  font-family: var(--sl-font-mono) !important;
+  font-size: 10.5px !important;
+  letter-spacing: 0.08em !important;
+  text-transform: uppercase !important;
+  border-radius: 999px !important;
+  padding: 2px 8px !important;
+  border: 1px solid var(--sl-color-hairline-light) !important;
+}
+
+/* ---------- 19. RESPONSIVE NICETIES ---------- */
+@media (max-width: 50rem) {
+  .hero h1 { font-size: clamp(40px, 10vw, 60px) !important; }
+}
+
+/* ---------- 20. PAGE ACTIONS DROPDOWN (Copy / View / Open in LLM) ---------- */
+/* Mirrors Mintlify/Anthropic's per-page Copy widget. CAVE-themed pill. */
+
+.page-title-row {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  flex-wrap: wrap;
+  margin-bottom: 0;
+}
+.page-title-row > h1 {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+}
+.page-title-row > .page-actions {
+  flex: 0 0 auto;
+  margin-left: auto;
+}
+
+.page-actions {
+  position: relative;
+  display: inline-flex;
+  align-items: stretch;
+  font-family: var(--sl-font-system, system-ui, sans-serif);
+  font-size: 13px;
+  line-height: 1;
+  isolation: isolate;
+}
+
+.page-actions__primary,
+.page-actions__caret {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--sl-color-bg, #050807);
+  color: var(--sl-color-text, #d4f5e5);
+  border: 1px solid var(--sl-color-hairline-light, rgba(58, 255, 157, 0.18));
+  cursor: pointer;
+  font: inherit;
+  transition: background 120ms ease, color 120ms ease, border-color 120ms ease;
+  padding: 0.45rem 0.7rem;
+}
+
+.page-actions__primary {
+  gap: 0.45rem;
+  border-top-left-radius: 999px;
+  border-bottom-left-radius: 999px;
+  border-right: 0;
+  padding-left: 0.85rem;
+}
+
+.page-actions__caret {
+  border-top-right-radius: 999px;
+  border-bottom-right-radius: 999px;
+  padding: 0.45rem 0.55rem;
+}
+
+.page-actions__primary:hover,
+.page-actions__caret:hover {
+  background: rgba(58, 255, 157, 0.07);
+  color: var(--sl-color-accent-high, #a8ffd4);
+  border-color: rgba(58, 255, 157, 0.4);
+}
+
+.page-actions__primary:focus-visible,
+.page-actions__caret:focus-visible {
+  outline: 2px solid var(--sl-color-accent, #3aff9d);
+  outline-offset: 2px;
+  z-index: 1;
+}
+
+.page-actions__primary svg {
+  flex: 0 0 auto;
+  opacity: 0.85;
+}
+
+.page-actions__label {
+  font-weight: 500;
+  white-space: nowrap;
+}
+
+.page-actions__caret svg {
+  transition: transform 140ms ease;
+}
+
+.page-actions[data-menu-open="true"] .page-actions__caret svg {
+  transform: rotate(180deg);
+}
+
+/* ---------- DROPDOWN MENU ---------- */
+.page-actions__menu {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  min-width: 280px;
+  background: var(--sl-color-bg, #050807);
+  border: 1px solid var(--sl-color-hairline-light, rgba(58, 255, 157, 0.18));
+  border-radius: 12px;
+  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.55), 0 0 0 1px rgba(58, 255, 157, 0.06);
+  padding: 0.4rem;
+  z-index: 50;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  animation: page-actions-menu-in 120ms ease-out;
+}
+
+@keyframes page-actions-menu-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+.page-actions__menu[hidden] {
+  display: none;
+}
+
+.page-actions__menu > [role="menuitem"] {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.7rem;
+  padding: 0.55rem 0.65rem;
+  background: transparent;
+  border: 0;
+  border-radius: 8px;
+  color: var(--sl-color-text, #d4f5e5);
+  text-align: left;
+  font: inherit;
+  cursor: pointer;
+  text-decoration: none;
+  transition: background 100ms ease, color 100ms ease;
+}
+
+.page-actions__menu > [role="menuitem"]:hover,
+.page-actions__menu > [role="menuitem"]:focus-visible {
+  background: rgba(58, 255, 157, 0.08);
+  color: var(--sl-color-accent-high, #a8ffd4);
+  outline: none;
+}
+
+.page-actions__menu-icon {
+  flex: 0 0 auto;
+  width: 22px;
+  height: 22px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-family: 'JetBrains Mono', ui-monospace, monospace;
+  font-size: 13px;
+  color: var(--sl-color-accent, #3aff9d);
+  background: rgba(58, 255, 157, 0.08);
+  border-radius: 5px;
+  margin-top: 1px;
+}
+
+.page-actions__menu-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+
+.page-actions__menu-title {
+  font-weight: 500;
+  font-size: 13px;
+  white-space: nowrap;
+}
+
+.page-actions__menu-sub {
+  font-size: 11px;
+  color: var(--sl-color-gray-3, rgba(212, 245, 229, 0.55));
+  white-space: nowrap;
+}
+
+.page-actions__divider {
+  border: 0;
+  border-top: 1px solid var(--sl-color-hairline-light, rgba(58, 255, 157, 0.1));
+  margin: 0.3rem 0.4rem;
+}
+
+/* ---------- TOAST (clipboard feedback) ---------- */
+.page-actions__toast {
+  position: absolute;
+  top: calc(100% + 6px);
+  right: 0;
+  background: var(--sl-color-accent, #3aff9d);
+  color: #050807;
+  font-weight: 600;
+  font-size: 12px;
+  padding: 0.4rem 0.75rem;
+  border-radius: 999px;
+  box-shadow: 0 6px 20px rgba(58, 255, 157, 0.25);
+  z-index: 60;
+  pointer-events: none;
+  animation: page-actions-toast-in 140ms ease-out;
+}
+
+.page-actions__toast[data-tone="err"] {
+  background: #ff5e5e;
+  color: #fff;
+  box-shadow: 0 6px 20px rgba(255, 94, 94, 0.3);
+}
+
+@keyframes page-actions-toast-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+/* ---------- RESPONSIVE: stack title + actions on narrow screens ---------- */
+@media (max-width: 30rem) {
+  .page-actions__label {
+    display: none; /* icon-only on mobile */
+  }
+  .page-actions__menu {
+    min-width: 240px;
+    right: -0.5rem;
+  }
 }
diff --git a/site/src/styles/custom_backup.css b/site/src/styles/custom_backup.css
new file mode 100644
index 0000000..c972787
--- /dev/null
+++ b/site/src/styles/custom_backup.css
@@ -0,0 +1,38 @@
+/* fsuite docs — custom theme tweaks to match the Monokai vibe of the MCP output */
+
+:root {
+  /* Dark theme override — Monokai-ish accent */
+  --sl-color-accent-low: #3b2a1a;
+  --sl-color-accent: #fd971f;
+  --sl-color-accent-high: #ffd866;
+
+  --sl-color-white: #f8f8f2;
+  --sl-color-gray-1: #e1e1db;
+  --sl-color-gray-2: #c5c5c0;
+  --sl-color-gray-3: #75715e;
+  --sl-color-gray-4: #49483e;
+  --sl-color-gray-5: #383830;
+  --sl-color-gray-6: #272822;
+  --sl-color-black: #1e1f1c;
+}
+
+:root[data-theme='light'] {
+  --sl-color-accent-low: #fef3c7;
+  --sl-color-accent: #d97706;
+  --sl-color-accent-high: #92400e;
+}
+
+/* Make the inline code stand out like terminal output */
+code {
+  font-weight: 500;
+}
+
+/* Terminal-y feel for block quotes (callouts) */
+blockquote {
+  border-left-color: var(--sl-color-accent);
+}
+
+/* Tighten the command-reference tables */
+table {
+  font-size: 0.92em;
+}

From 05a3d51b1c7b9892d6a0530b6903f467be5b9018 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 13:38:57 -0500
Subject: [PATCH 02/19] Docs: keystone-emphasis chain diagram, native-vs-fsuite
 block, drone sensor hero
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Append Claude Design's component appendix CSS (459 lines) to custom.css
  for Field Dispatch strip, counter strip, keystone pipeline diagram,
  native-vs-fsuite comparison, drone-cave sensor diagram, fcase lifecycle
- Replace landing page (index.mdx): adds Field Dispatch strip, counters,
  native-vs-fsuite ~12k vs ~480 token cost comparison, keystone pipeline
  with fs as front door + fmap as the visual keystone, 'see it in the
  wild' 4-call walkthrough, Claude Code self-assessment quote
- Replace mental-model.md: drone-cave sensor diagram with 3 hovering
  drones over directory tree, keystone pipeline, why fmap matters as
  the gap native CLI doesn't fill, native->fsuite reflex translation
- Replace chains.md: Core/Investigation/Debugging/Refactoring/Binary
  chains plus the fcase lifecycle as state-machine block

MDX fixes applied during integration:
- Escape literal { } in <pre> JSON sample (line 125: \{ \}) so MDX
  doesn't parse them as JSX expressions
- Split <pre> opening tag onto its own line and replace blank-line
  paragraph breaks inside <pre> blocks with <span class='fs-c-sep'>
  separators — MDX 2+ requires HTML elements to be a contiguous block,
  blank lines terminate the paragraph and orphan the opening tag
  (confirmed via mdx-js maintainer guidance + Astro Starlight docs)
---
 site/src/content/docs/architecture/chains.md  | 122 +++--
 .../docs/getting-started/mental-model.md      |  90 +++-
 site/src/content/docs/index.mdx               | 129 ++++-
 site/src/styles/custom.css                    | 459 ++++++++++++++++++
 4 files changed, 758 insertions(+), 42 deletions(-)

diff --git a/site/src/content/docs/architecture/chains.md b/site/src/content/docs/architecture/chains.md
index c32e1e5..bf89c95 100644
--- a/site/src/content/docs/architecture/chains.md
+++ b/site/src/content/docs/architecture/chains.md
@@ -7,58 +7,120 @@ sidebar:
 
 ## The core chain
 
-```text
-ftree → fs → fmap → fread → fedit
-```
-
-Use this as your default for "I need to understand and modify something in this repo."
+The default for "I need to understand and modify something in this repo."
+
+<div class="fs-pipeline">
+  <span class="fs-pn fs-pn-entry">ftree</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fs</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fmap</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fread</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fedit</span>
+</div>
 
 ## Investigation chain
 
-```text
-fcase init → ftree → fs → fmap → fread → fcase note → fedit → fcase resolve
-```
-
-Use this when the work spans multiple sessions or context windows.
+Spans multiple sessions or context windows. `fcase` brackets the work.
+
+<div class="fs-pipeline">
+  <span class="fs-pn fs-pn-entry">fcase init</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">ftree</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fs</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fmap</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fread</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fcase note</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fedit</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn fs-pn-entry">fcase resolve</span>
+</div>
 
 ## Debugging chain
 
-```text
-fbash (reproduce bug) → fs (find relevant code) → fmap → fread → fcase → fedit → fbash (verify fix)
-```
-
 `fcase` captures the hypothesis, the repro steps, and the fix — so if the fix fails, the next attempt starts with context.
 
+<div class="fs-pipeline">
+  <span class="fs-pn">fbash</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fs</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fmap</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fread</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fcase</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fedit</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn fs-pn-entry">fbash</span>
+</div>
+
 ## Refactoring chain
 
-```text
-fcontent (find all call sites) → fsearch (scope files) → fmap (find symbols to update) → fedit --function_name (scoped edits)
-```
+The key move: use `fedit --symbol` for each symbol instead of doing a text-replace across files. Zero ambiguity.
 
-The key move: use `fedit --function_name` for each symbol instead of doing a text-replace across files. Zero ambiguity.
+<div class="fs-pipeline">
+  <span class="fs-pn">fcontent</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fsearch</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fmap</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn fs-pn-entry">fedit --symbol</span>
+</div>
 
 ## Binary investigation chain
 
-```text
-fprobe strings → fprobe scan → fprobe window → fprobe patch
-```
+When the target is a compiled binary, an obfuscated bundle, or anything text tools can't read.
 
-When you need to work with a compiled binary, an obfuscated bundle, or anything the text-based tools can't read.
+<div class="fs-pipeline">
+  <span class="fs-pn fs-pn-branch">fprobe strings</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn fs-pn-branch">fprobe scan</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn fs-pn-branch">fprobe window</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn fs-pn-branch">fprobe patch</span>
+</div>
+
+## fcase lifecycle
+
+The investigation ledger isn't a chain — it's a state machine that wraps every other chain.
+
+<div class="fs-fcase">
+  <div class="fs-fcase-state"><b>init</b><span>open the seam</span></div>
+  <span class="fs-arr"></span>
+  <div class="fs-fcase-state"><b>note</b><span>capture evidence</span></div>
+  <span class="fs-arr"></span>
+  <div class="fs-fcase-state"><b>handoff</b><span>pass to next agent</span></div>
+  <span class="fs-arr"></span>
+  <div class="fs-fcase-state fs-fcase-end"><b>resolve</b><span>close + archive</span></div>
+</div>
 
 ## Replay chain
 
-```text
+Rerun a traced investigation step-by-step. Useful for post-mortems and regression tests.
+
+```bash
 freplay --session <id>
 ```
 
-Rerun a traced investigation step-by-step. Useful for post-mortems and regression tests.
-
 ## Measurement chain
 
-```text
-fmetrics import → fmetrics stats → fmetrics predict <project>
-```
-
 Ask the telemetry database what worked last time and what probably works next.
 
-> **TODO:** add screenshots / example outputs for each chain.
+<div class="fs-pipeline">
+  <span class="fs-pn">fmetrics import</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn">fmetrics stats</span>
+  <span class="fs-arr"></span>
+  <span class="fs-pn fs-pn-entry">fmetrics predict</span>
+</div>
diff --git a/site/src/content/docs/getting-started/mental-model.md b/site/src/content/docs/getting-started/mental-model.md
index 8fec30f..025d6d6 100644
--- a/site/src/content/docs/getting-started/mental-model.md
+++ b/site/src/content/docs/getting-started/mental-model.md
@@ -5,20 +5,96 @@ sidebar:
   order: 2
 ---
 
+## The sensor metaphor
+
+The filesystem is a cave. You don't know how deep it goes until you have the right tools to map it. Native CLI gives the agent a flashlight and an analog radio. fsuite hands it a fleet of reconnaissance drones with structured telemetry.
+
+<div class="fs-sensor">
+  <div class="fs-sensor-stage">
+    <div class="fs-sensor-bg" aria-hidden="true"></div>
+    <div class="fs-sensor-drone fs-sensor-d1" title="ftree">
+      <span class="fs-sensor-name">ftree</span>
+      <span class="fs-sensor-beam"></span>
+    </div>
+    <div class="fs-sensor-drone fs-sensor-d2" title="fsearch">
+      <span class="fs-sensor-name">fsearch</span>
+      <span class="fs-sensor-beam"></span>
+    </div>
+    <div class="fs-sensor-drone fs-sensor-d3" title="fcontent">
+      <span class="fs-sensor-name">fcontent</span>
+      <span class="fs-sensor-beam"></span>
+    </div>
+    <div class="fs-sensor-tree" aria-hidden="true">
+      <span class="fs-sensor-trunk"></span>
+      <span class="fs-sensor-branch fs-sensor-b1">src/</span>
+      <span class="fs-sensor-branch fs-sensor-b2">lib/</span>
+      <span class="fs-sensor-branch fs-sensor-b3">docs/</span>
+      <span class="fs-sensor-branch fs-sensor-b4">tests/</span>
+      <span class="fs-sensor-branch fs-sensor-b5">bin/</span>
+    </div>
+    <div class="fs-sensor-platform">
+      <span>OPERATOR · TERMINAL · 03:14:22</span>
+    </div>
+  </div>
+</div>
+
 ## The chain
 
 The main fsuite workflow is a straight line from territory scout to surgical edit:
 
-```text
-fsuite → fs / ftree / fls → fsearch | fcontent → fmap → fread → fcase → fedit / fwrite → fmetrics
-Guide    Unified / Scout / LS   Narrowing             Bridge   Read     Preserve  Mutate           Measure
-```
+<div class="fs-pipeline-v2">
+  <div class="fs-pipeline-row">
+    <span class="fs-pn fs-pn-entry">fs</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">ftree</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-bridge">fsearch │ fcontent</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-keystone">fmap</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fread</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fcase</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fedit</span>
+  </div>
+  <div class="fs-pipeline-undernote">
+    <span>↑ <code>fs</code> is the front door — it auto-routes to <code>fsearch</code>+<code>fcontent</code> for you</span>
+    <span>↑ <code>fmap</code> is the <b>keystone</b>. Symbol cartography is the gap native CLI does not fill.</span>
+  </div>
+</div>
+
+### The keystone: why fmap matters
+
+Native CLI gives the agent two ways to find code: name-match (`grep`/`find`) and full-file read (`cat`). Neither knows what a function is. So the agent burns tokens reading whole files just to locate a symbol that `fmap` could have pointed at directly.
 
-Three specialists orbit the main stack:
+`fmap` extracts the symbol skeleton — every function, class, import, and constant, with line numbers — across **50+ languages**. The agent sees the shape of the file before it spends a single token reading it. **That bridge from "I have a name" to "I know exactly which 14 lines to read" is the single biggest token-cost win in fsuite.**
 
-- **`fbash`** — Bash replacement with token-budgeting, command classification, and session state
+### The supporting cast
+
+Three specialists orbit the main chain:
+
+- **`fls`** — Structured `ls` replacement with recon mode (per-dir sizes + counts)
+- **`fwrite`** — Atomic file creation with safety nets
+- **`fbash`** — Bash replacement with token-budgeting, command classification, session state
 - **`fprobe`** — Binary / bundle inspection + patching when normal reads fail
 - **`freplay`** — Derivation chain replay for deterministic reruns
+- **`fmetrics`** — Telemetry + tool-chain prediction (learn what works, predict what's next)
+
+## Default reflexes — translate native habits to fsuite
+
+If your agent is already running it should learn this table by heart.
+
+| Native habit | What it costs | fsuite equivalent | Why it's better |
+|---|---|---|---|
+| `grep -rn "foo"` | floods context, no caps | `fcontent "foo" -o json` | token-capped, ranked, structured |
+| `find . -name "*.py"` | walks every dir | `fsearch '*.py' -o paths` | suppresses noise dirs, fd-aware |
+| `cat src/auth.py` | dumps whole file | `fread src/auth.py --symbol authenticate` | reads exactly one function |
+| `sed -i 's/x/y/' f` | unscoped, drift-prone | `fedit --symbol foo --replace x --with y` | symbol-scoped, dry-run by default |
+| `ls -laR` | unbounded recursion | `ftree --recon` | per-dir sizes + counts, no flood |
+| `bash -c '…'` | unbounded output | `fbash` | token-budgeted, classified, async |
+| Re-discover repo every session | wastes context | `fcase init / handoff` | preserves state across agents |
+| Read PDFs by hand | not a thing | `fread invoice.pdf` | first-class media reads |
 
 ## The discipline
 
@@ -27,7 +103,7 @@ Three specialists orbit the main stack:
 3. **Map before reading.** `fmap` extracts the symbol skeleton. You'll know what's there before you read a single line.
 4. **Read exactly, never approximately.** `fread --symbol NAME` reads one function by name. `fread --lines 120:150` reads an exact range. Don't read whole files.
 5. **Preserve investigation state.** Open `fcase init` at the start of non-trivial work. Close with `fcase resolve`. Check `fcase find` before starting new work — a past you may already have the answer.
-6. **Edit surgically.** `fedit --lines` is the fastest mode when you have numbers from `fread`. `fedit --function_name` scopes by symbol without needing huge unique context strings.
+6. **Edit surgically.** `fedit --lines` is the fastest mode when you have numbers from `fread`. `fedit --symbol` scopes by symbol without needing huge unique context strings.
 7. **Never edit blind.** Always inspect context with `fread` before calling `fedit`.
 8. **Measure.** `fmetrics` tells you which chains worked and predicts the best next step for any project.
 
diff --git a/site/src/content/docs/index.mdx b/site/src/content/docs/index.mdx
index 6b232bf..e565235 100644
--- a/site/src/content/docs/index.mdx
+++ b/site/src/content/docs/index.mdx
@@ -22,11 +22,26 @@ hero:
 
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
-## What is fsuite?
+<div class="fs-fielddispatch">
+  <span class="fs-fd-live">FIELD DISPATCH</span>
+  <span>EP 0 · ORIGINS</span>
+  <span>STATUS: <b>DRONES OPERATIONAL</b></span>
+  <span>v2.4.0</span>
+</div>
 
-fsuite is **fourteen command-line tools** built for AI coding agents. It is the answer to one question: *what would you give an LLM if you actually wanted it to find, read, and edit code without burning its context on irrelevant junk?*
+<div class="fs-counters">
+  <div><b>14</b><span>tools</span></div>
+  <div><b>516</b><span>tests</span></div>
+  <div><b>50</b><span>languages</span></div>
+  <div><b>MCP</b><span>native</span></div>
+  <div><b>0</b><span>flooded contexts</span></div>
+</div>
 
-The tools replace the native filesystem and shell primitives every agent reaches for by default — grep, find, cat, sed, bash — with **bounded, structured, token-budgeted** alternatives that know how to cap their output, rank their results, and hand back exactly the slice of the repo that matters.
+## What if the agent had real reconnaissance instead of a flashlight?
+
+The native filesystem tools every coding agent reaches for — `grep`, `find`, `cat`, `sed`, `bash` — were built for humans, on terminals, in 1979. They do not cap their output. They do not rank their results. They do not know what a token costs.
+
+**fsuite does.** Fourteen tools, one mental model: *recon → read → edit → replay → measure*. Designed for headless agents, kept human-friendly so the engineer holding the leash never gets lost either.
 
 ## The four things it fixes
 
@@ -45,6 +60,106 @@ The tools replace the native filesystem and shell primitives every agent reaches
   </Card>
 </CardGrid>
 
+## The chain
+
+The agent only has to remember one flow:
+
+<div class="fs-pipeline-v2">
+  <div class="fs-pipeline-row">
+    <span class="fs-pn fs-pn-entry">fs</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">ftree</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-bridge">fsearch │ fcontent</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-keystone">fmap</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fread</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fcase</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fedit</span>
+  </div>
+  <div class="fs-pipeline-undernote">
+    <span>↑ <code>fs</code> auto-routes through <code>fsearch</code> + <code>fcontent</code> — you usually don't call them by hand</span>
+    <span>↑ <code>fmap</code> is the keystone — symbol cartography is the gap native tools don't fill</span>
+  </div>
+  <div class="fs-pipeline-row fs-pipeline-row-aux">
+    <span class="fs-pn-aux">fls</span>
+    <span class="fs-pn-aux">fwrite</span>
+    <span class="fs-pn-aux">fbash</span>
+    <span class="fs-pn-aux">freplay</span>
+    <span class="fs-pn-aux">fmetrics</span>
+    <span class="fs-pn-aux fs-pn-aux-warn">fprobe</span>
+  </div>
+  <div class="fs-pipeline-undernote">
+    <span><code>fls</code> structured ls · <code>fwrite</code> atomic create · <code>fbash</code> budgeted shell · <code>freplay</code> deterministic rerun · <code>fmetrics</code> tool-chain prediction · <code>fprobe</code> binaries</span>
+  </div>
+</div>
+
+[Internalize the discipline →](/fsuite/getting-started/mental-model/)
+
+## Native vs fsuite
+
+The same investigation, two tool stacks. fsuite's columns hand back exactly the slice the agent needs.
+
+<div class="fs-vs">
+  <div class="fs-vs-col fs-vs-bad">
+    <div class="fs-vs-head"><span class="fs-vs-tag">grep / find / cat</span> <span class="fs-vs-cost">~12k tokens</span></div>
+<pre>
+<span class="fs-c-prompt">$</span> grep -rn "authenticate" src/
+src/auth.py:14:def authenticate(user):
+src/auth.py:42:    return authenticate_with_db(user)
+src/legacy.py:8:# old authenticate logic, kept for...
+src/tests/test_auth.py:3:def test_authenticate_basic():
+src/tests/test_auth.py:19:def test_authenticate_invalid():
+... <span class="fs-c-com">(217 more lines)</span>
+<span class="fs-c-sep">———————————————————————————</span>
+<span class="fs-c-prompt">$</span> cat src/auth.py
+<span class="fs-c-com"># dumps all 480 lines into context</span>
+</pre>
+  </div>
+  <div class="fs-vs-col fs-vs-good">
+    <div class="fs-vs-head"><span class="fs-vs-tag fs-vs-tag-good">fs / fmap / fread</span> <span class="fs-vs-cost fs-vs-cost-good">~480 tokens</span></div>
+<pre>
+<span class="fs-c-prompt">$</span> fs "authenticate" -o json
+<span class="fs-c-key">"intent"</span>: <span class="fs-c-str">"symbol"</span>,
+<span class="fs-c-key">"hits"</span>: [\{ <span class="fs-c-key">"path"</span>: <span class="fs-c-str">"src/auth.py"</span>, <span class="fs-c-key">"line"</span>: <span class="fs-c-num">42</span> \}],
+<span class="fs-c-key">"next_hint"</span>: <span class="fs-c-str">"fread src/auth.py --symbol authenticate"</span>
+<span class="fs-c-sep">———————————————————————————</span>
+<span class="fs-c-prompt">$</span> fread src/auth.py --symbol authenticate -B 2 -A 12
+<span class="fs-c-ok">→</span> exact 14-line block, nothing else
+</pre>
+  </div>
+</div>
+
+## See it in the wild
+
+A real opening move on a fresh repo. `fs` auto-classifies. `fmap` bridges to symbols. `fread` hands back the exact neighborhood. `fcase` preserves the seam for the next agent. **Four calls.**
+
+```bash
+# 01  Auto-route the opening move
+$ fs "renderTool" -o json | jq .
+{
+  "intent": "symbol",
+  "hits": [{ "path": "src/tools/render.ts", "line": 42, "score": 0.97 }],
+  "next_hint": "fread src/tools/render.ts --symbol renderTool"
+}
+
+# 02  Map the neighborhood before reading
+$ fmap -o json src/tools/render.ts | head
+→ renderTool        function   line 42
+→ resolveContext    function   line 18
+→ ToolRenderer      class      line 7
+
+# 03  Read exactly the symbol — no surrounding noise
+$ fread src/tools/render.ts --symbol renderTool -B 2 -A 12
+
+# 04  Preserve the seam, hand off to the next agent
+$ fcase init render-seam --goal "Trace renderTool denial path"
+✓ case opened   ~/.fsuite/fcase.db · session 0xa72f
+```
+
 ## The fourteen tools
 
 | Tool | Purpose |
@@ -54,8 +169,8 @@ The tools replace the native filesystem and shell primitives every agent reaches
 | [`fls`](/fsuite/commands/fls/) | Structured directory listing with recon mode |
 | [`fsearch`](/fsuite/commands/fsearch/) | File / glob discovery |
 | [`fcontent`](/fsuite/commands/fcontent/) | Bounded content search (token-capped ripgrep) |
-| [`fmap`](/fsuite/commands/fmap/) | Symbol cartography — functions, classes, imports |
-| [`fread`](/fsuite/commands/fread/) | Budgeted reading with symbol & line-range resolution |
+| [`fmap`](/fsuite/commands/fmap/) | Symbol cartography — functions, classes, imports, 50 languages |
+| [`fread`](/fsuite/commands/fread/) | Budgeted reading with symbol & line-range resolution; PDF + image media |
 | [`fedit`](/fsuite/commands/fedit/) | Surgical editing (line-range, symbol-scoped, anchor-based) |
 | [`fwrite`](/fsuite/commands/fwrite/) | Atomic file creation |
 | [`fbash`](/fsuite/commands/fbash/) | Token-budgeted shell with classification + session state |
@@ -68,4 +183,8 @@ The tools replace the native filesystem and shell primitives every agent reaches
 
 fsuite was always supposed to be **CLI-first**. The MCP server came later, the hooks came later, and the whole thing is still catching up to the lightbulb moment that probably should have come first.
 
+> *"The gap isn't in any single tool. It's in the reconnaissance layer. I have no native way to answer the question: 'What is this project, how big is it, and where should I look first?'"*
+>
+> — Claude Code (Opus 4.5), unprompted self-assessment
+
 [Read the full story →](/fsuite/story/episode-0/)
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index 407ff56..2aefff0 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -713,3 +713,462 @@ starlight-tabs [role="tab"][aria-selected="true"] {
     right: -0.5rem;
   }
 }
+/* ============================================================
+   fsuite — CAVE theme · COMPONENTS APPENDIX
+   Append to the end of site/src/styles/custom.css
+   Powers the new index.mdx, mental-model.md, chains.md
+   ============================================================ */
+
+/* ---------- 20. FIELD DISPATCH STRIP ---------- */
+.fs-fielddispatch {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 18px;
+  padding: 10px 16px;
+  margin: 24px 0 28px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 6px;
+  background: linear-gradient(180deg, rgba(58, 255, 157, 0.04), rgba(58, 255, 157, 0.01));
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.10em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-2);
+}
+.fs-fielddispatch b { color: var(--fs-accent); font-weight: 600; }
+.fs-fd-live {
+  position: relative;
+  padding-left: 16px;
+  color: var(--fs-accent);
+  font-weight: 600;
+}
+.fs-fd-live::before {
+  content: "";
+  position: absolute;
+  left: 0; top: 50%;
+  width: 8px; height: 8px;
+  border-radius: 50%;
+  background: var(--fs-accent);
+  box-shadow: 0 0 8px var(--fs-accent);
+  transform: translateY(-50%);
+  animation: fs-pulse 1.6s ease-in-out infinite;
+}
+@keyframes fs-pulse {
+  0%, 100% { opacity: 1; }
+  50%      { opacity: 0.35; }
+}
+
+/* ---------- 21. COUNTER STRIP ---------- */
+.fs-counters {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 1px;
+  margin: 16px 0 40px;
+  padding: 1px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 8px;
+  background: var(--sl-color-hairline);
+}
+.fs-counters > div {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: 18px 12px;
+  background: var(--sl-color-bg);
+}
+.fs-counters > div b {
+  font-family: var(--sl-font-mono);
+  font-size: 28px;
+  font-weight: 600;
+  color: var(--fs-accent);
+  letter-spacing: -0.02em;
+}
+.fs-counters > div span {
+  font-family: var(--sl-font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.10em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-3);
+}
+@media (max-width: 50rem) {
+  .fs-counters { grid-template-columns: repeat(2, 1fr); }
+  .fs-counters > div b { font-size: 22px; }
+}
+
+/* ---------- 22. PIPELINE DIAGRAM ---------- */
+.fs-pipeline {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px;
+  padding: 18px 16px;
+  margin: 16px 0 8px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 8px;
+  background:
+    linear-gradient(90deg, rgba(58, 255, 157, 0.04), transparent 30%, transparent 70%, rgba(58, 255, 157, 0.04)),
+    var(--sl-color-bg);
+  font-family: var(--sl-font-mono);
+  font-size: 13px;
+  overflow-x: auto;
+}
+.fs-pn {
+  display: inline-flex;
+  align-items: center;
+  padding: 6px 10px;
+  border: 1px solid var(--sl-color-hairline-shade);
+  border-radius: 4px;
+  background: var(--sl-color-gray-7);
+  color: var(--sl-color-gray-1);
+  font-weight: 500;
+  white-space: nowrap;
+}
+.fs-pn-entry {
+  border-color: var(--fs-accent);
+  background: color-mix(in oklab, var(--fs-accent) 12%, var(--sl-color-bg));
+  color: var(--fs-accent);
+  box-shadow: 0 0 16px color-mix(in oklab, var(--fs-accent) 25%, transparent);
+}
+.fs-pn-branch {
+  border-color: var(--fs-warn);
+  background: color-mix(in oklab, var(--fs-warn) 10%, var(--sl-color-bg));
+  color: var(--fs-warn);
+}
+.fs-arr {
+  display: inline-block;
+  width: 18px;
+  height: 1px;
+  position: relative;
+  background: var(--sl-color-hairline-shade);
+}
+.fs-arr::after {
+  content: "";
+  position: absolute;
+  right: -1px; top: 50%;
+  width: 6px; height: 6px;
+  border-top: 1px solid var(--sl-color-hairline-shade);
+  border-right: 1px solid var(--sl-color-hairline-shade);
+  transform: translateY(-50%) rotate(45deg);
+}
+.fs-or {
+  color: var(--sl-color-gray-3);
+  padding: 0 4px;
+  font-weight: 600;
+}
+.fs-pipeline-branch {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 16px 18px;
+  margin: -8px 0 16px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-top: none;
+  border-radius: 0 0 8px 8px;
+  background: var(--sl-color-bg);
+  font-family: var(--sl-font-mono);
+  font-size: 12px;
+  color: var(--sl-color-gray-3);
+  flex-wrap: wrap;
+}
+.fs-pipeline-legend {
+  display: grid;
+  grid-template-columns: repeat(8, 1fr);
+  gap: 4px;
+  padding: 0 8px;
+  margin: 0 0 32px;
+  font-family: var(--sl-font-mono);
+  font-size: 10px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-3);
+}
+.fs-pipeline-legend span {
+  text-align: center;
+  padding: 4px 0;
+}
+@media (max-width: 50rem) {
+  .fs-pipeline-legend { display: none; }
+}
+
+/* ---------- 22b. PIPELINE V2 (keystone-emphasis) ---------- */
+.fs-pipeline-v2 {
+  margin: 16px 0 32px;
+  padding: 22px 18px 18px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 10px;
+  background:
+    radial-gradient(ellipse at 50% 0%, rgba(58, 255, 157, 0.06), transparent 70%),
+    var(--sl-color-bg);
+}
+.fs-pipeline-row {
+  display: flex; flex-wrap: wrap; align-items: center; gap: 6px;
+  font-family: var(--sl-font-mono); font-size: 13px;
+  justify-content: center;
+}
+.fs-pipeline-row-aux {
+  margin-top: 18px;
+  padding-top: 14px;
+  border-top: 1px dashed var(--sl-color-hairline);
+  gap: 10px;
+}
+.fs-pn-bridge {
+  border-color: color-mix(in oklab, var(--fs-info) 50%, transparent);
+  background: color-mix(in oklab, var(--fs-info) 10%, var(--sl-color-bg));
+  color: var(--fs-info);
+  font-style: italic;
+}
+.fs-pn-keystone {
+  position: relative;
+  border: 1px solid var(--fs-accent);
+  background: color-mix(in oklab, var(--fs-accent) 22%, var(--sl-color-bg));
+  color: #051a10;
+  font-weight: 700;
+  padding: 8px 14px;
+  font-size: 14px;
+  box-shadow:
+    0 0 0 4px color-mix(in oklab, var(--fs-accent) 12%, transparent),
+    0 0 24px color-mix(in oklab, var(--fs-accent) 35%, transparent);
+}
+.fs-pn-keystone::after {
+  content: "KEYSTONE";
+  position: absolute;
+  bottom: -16px; left: 50%; transform: translateX(-50%);
+  font-size: 9px; letter-spacing: 0.18em;
+  color: var(--fs-accent); font-weight: 600;
+  white-space: nowrap;
+}
+.fs-pn-aux {
+  display: inline-flex; align-items: center;
+  padding: 4px 9px;
+  border: 1px dashed var(--sl-color-hairline-shade);
+  border-radius: 3px;
+  background: transparent;
+  color: var(--sl-color-gray-2);
+  font-family: var(--sl-font-mono); font-size: 12px;
+}
+.fs-pn-aux-warn { border-color: color-mix(in oklab, var(--fs-warn) 40%, transparent); color: var(--fs-warn); }
+.fs-pipeline-undernote {
+  display: flex; flex-direction: column; gap: 4px;
+  margin-top: 12px;
+  font-family: var(--sl-font-mono); font-size: 11.5px;
+  color: var(--sl-color-gray-3);
+  line-height: 1.5;
+  text-align: center;
+}
+.fs-pipeline-undernote code { font-size: 0.95em; color: var(--fs-accent); background: transparent; padding: 0; }
+.fs-pipeline-undernote b { color: var(--fs-accent); font-weight: 600; }
+
+/* ---------- 23. NATIVE-VS-FSUITE COMPARISON ---------- */
+.fs-vs {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+  margin: 16px 0 32px;
+}
+.fs-vs-col {
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 8px;
+  background: var(--sl-color-bg);
+  overflow: hidden;
+}
+.fs-vs-bad  { border-color: color-mix(in oklab, var(--fs-crit) 40%, var(--sl-color-hairline-shade)); }
+.fs-vs-good { border-color: color-mix(in oklab, var(--fs-accent) 40%, var(--sl-color-hairline-shade)); }
+.fs-vs-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--sl-color-hairline);
+  background: rgba(0, 0, 0, 0.25);
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+.fs-vs-tag { color: var(--fs-crit); font-weight: 600; }
+.fs-vs-tag-good { color: var(--fs-accent); }
+.fs-vs-cost { color: var(--fs-crit); font-weight: 600; }
+.fs-vs-cost-good { color: var(--fs-accent); }
+.fs-vs-col pre {
+  margin: 0 !important;
+  padding: 14px !important;
+  background: transparent !important;
+  border: none !important;
+  border-radius: 0 !important;
+  font-family: var(--sl-font-mono);
+  font-size: 12.5px;
+  line-height: 1.55;
+  color: var(--sl-color-gray-1);
+  overflow-x: auto;
+}
+.fs-c-prompt { color: var(--fs-accent); font-weight: 600; }
+.fs-c-com    { color: var(--sl-color-gray-3); font-style: italic; }
+.fs-c-key    { color: #a8ffd4; }
+.fs-c-str    { color: #ffd866; }
+.fs-c-num    { color: #fd971f; }
+.fs-c-ok     { color: var(--fs-accent); font-weight: 600; }
+@media (max-width: 60rem) {
+  .fs-vs { grid-template-columns: 1fr; }
+}
+
+/* ---------- 24. SENSOR / DRONE STAGE (mental-model.md) ---------- */
+.fs-sensor {
+  margin: 24px 0 32px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 10px;
+  background: var(--sl-color-bg);
+  overflow: hidden;
+}
+.fs-sensor-stage {
+  position: relative;
+  height: 360px;
+  background:
+    radial-gradient(ellipse at 50% 20%, rgba(58, 255, 157, 0.10), transparent 60%),
+    radial-gradient(ellipse at 50% 100%, rgba(58, 255, 157, 0.06), transparent 70%),
+    linear-gradient(180deg, #06100c 0%, #050808 100%);
+  overflow: hidden;
+}
+.fs-sensor-bg {
+  position: absolute;
+  inset: 0;
+  background-image:
+    linear-gradient(0deg, transparent 95%, rgba(58, 255, 157, 0.06) 100%),
+    linear-gradient(90deg, transparent 95%, rgba(58, 255, 157, 0.06) 100%);
+  background-size: 32px 32px;
+  opacity: 0.5;
+}
+.fs-sensor-drone {
+  position: absolute;
+  width: 14px;
+  height: 14px;
+  border-radius: 50%;
+  background: var(--fs-accent);
+  box-shadow: 0 0 12px var(--fs-accent), 0 0 24px color-mix(in oklab, var(--fs-accent) 50%, transparent);
+}
+.fs-sensor-d1 { top: 18%;  left: 22%; animation: fs-hover 4.2s ease-in-out infinite; }
+.fs-sensor-d2 { top: 14%;  left: 50%; animation: fs-hover 5.0s ease-in-out infinite 0.6s; }
+.fs-sensor-d3 { top: 22%;  left: 76%; animation: fs-hover 4.6s ease-in-out infinite 1.2s; }
+@keyframes fs-hover {
+  0%, 100% { transform: translateY(0); }
+  50%      { transform: translateY(-8px); }
+}
+.fs-sensor-name {
+  position: absolute;
+  top: -22px;
+  left: 50%;
+  transform: translateX(-50%);
+  font-family: var(--sl-font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--fs-accent);
+  white-space: nowrap;
+}
+.fs-sensor-beam {
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 0; height: 0;
+  border-left: 60px solid transparent;
+  border-right: 60px solid transparent;
+  border-top: 180px solid color-mix(in oklab, var(--fs-accent) 14%, transparent);
+  filter: blur(2px);
+  pointer-events: none;
+}
+.fs-sensor-tree {
+  position: absolute;
+  bottom: 60px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 80%;
+  max-width: 500px;
+  height: 140px;
+  pointer-events: none;
+}
+.fs-sensor-trunk {
+  position: absolute;
+  bottom: 0;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 2px;
+  height: 100%;
+  background: linear-gradient(180deg, transparent, color-mix(in oklab, var(--fs-accent) 35%, transparent));
+}
+.fs-sensor-branch {
+  position: absolute;
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  color: color-mix(in oklab, var(--fs-accent) 70%, white);
+  padding: 3px 8px;
+  border: 1px solid color-mix(in oklab, var(--fs-accent) 30%, transparent);
+  border-radius: 3px;
+  background: rgba(5, 8, 10, 0.7);
+  backdrop-filter: blur(2px);
+  white-space: nowrap;
+}
+.fs-sensor-b1 { bottom: 80px;  left: 8%;  }
+.fs-sensor-b2 { bottom: 110px; left: 28%; }
+.fs-sensor-b3 { bottom: 90px;  left: 50%; transform: translateX(-50%); }
+.fs-sensor-b4 { bottom: 110px; right: 22%;}
+.fs-sensor-b5 { bottom: 75px;  right: 5%; }
+.fs-sensor-platform {
+  position: absolute;
+  bottom: 0;
+  left: 0; right: 0;
+  padding: 12px 18px;
+  border-top: 1px solid var(--sl-color-hairline);
+  background: rgba(5, 8, 10, 0.85);
+  font-family: var(--sl-font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.10em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-3);
+}
+
+/* ---------- 25. FCASE LIFECYCLE STATE BLOCKS ---------- */
+.fs-fcase {
+  display: flex;
+  align-items: stretch;
+  gap: 6px;
+  margin: 16px 0 32px;
+  flex-wrap: wrap;
+}
+.fs-fcase-state {
+  flex: 1;
+  min-width: 130px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+  border: 1px solid var(--sl-color-hairline-shade);
+  border-radius: 6px;
+  background: var(--sl-color-gray-7);
+}
+.fs-fcase-state b {
+  font-family: var(--sl-font-mono);
+  font-size: 14px;
+  color: var(--fs-accent);
+  font-weight: 600;
+}
+.fs-fcase-state span {
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  color: var(--sl-color-gray-3);
+  letter-spacing: 0.04em;
+}
+.fs-fcase-end {
+  border-color: color-mix(in oklab, var(--fs-accent) 50%, transparent);
+  background: color-mix(in oklab, var(--fs-accent) 8%, var(--sl-color-gray-7));
+}
+.fs-fcase .fs-arr {
+  align-self: center;
+  width: 22px;
+}
+@media (max-width: 50rem) {
+  .fs-fcase { flex-direction: column; }
+  .fs-fcase .fs-arr { transform: rotate(90deg); margin: 0 auto; }
+}

From aa17ce48ef16e95e17872dab36fd1b7f33ef20f8 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 14:37:16 -0500
Subject: [PATCH 03/19] =?UTF-8?q?Docs:=20round=203=20=E2=80=94=20monokai?=
 =?UTF-8?q?=20terminal=20blocks,=20full=20cheat=20sheet,=20MCP-sequential?=
 =?UTF-8?q?=20note?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Design deliverable v3:
- custom.css: +209 lines (sections 30-34: .fs-term monokai block with traffic-light
  bar + cost meter, .tk-* token palette, .fs-drone profile cards, .fs-cheat-nav
  sticky tool jumps, .fs-mcp-note amber callout, .fs-footer-status)
- reference/cheatsheet.mdx: new 536-line agent-scrapeable single-page reference,
  one drone profile + commands table + monokai terminal sample per tool,
  canonical pipelines + MCP-vs-CLI semantics table at the bottom
- architecture/chains.md: rebuilt from chain-combinations spec — pipe contract
  (producers/consumers/non-pipe), 2/3/4-cmd chain examples, 5 investigation
  patterns, fcase lifecycle, invalid-chains-and-why, MCP-sequential note with
  fbash escape-hatch tip
- old reference/cheatsheet.md removed (URL slug now served by .mdx)

MDX strict-mode fixes applied to cheatsheet.mdx before write: 20 bare {/}
chars escaped to \{ \} inside <pre> blocks (TS imports + function bodies);
8 blank lines inside <pre> replaced with <span class="tk-mut">·</span>
separators. Verified clean — all 5 affected pages return 200 with zero MDX
compile errors in dev log.
---
 site/src/content/docs/architecture/chains.md  | 206 ++++---
 site/src/content/docs/reference/cheatsheet.md | 109 ----
 .../src/content/docs/reference/cheatsheet.mdx | 536 ++++++++++++++++++
 site/src/styles/custom.css                    | 209 +++++++
 4 files changed, 861 insertions(+), 199 deletions(-)
 delete mode 100644 site/src/content/docs/reference/cheatsheet.md
 create mode 100644 site/src/content/docs/reference/cheatsheet.mdx

diff --git a/site/src/content/docs/architecture/chains.md b/site/src/content/docs/architecture/chains.md
index bf89c95..c23a8bc 100644
--- a/site/src/content/docs/architecture/chains.md
+++ b/site/src/content/docs/architecture/chains.md
@@ -1,99 +1,134 @@
 ---
 title: Chain Combinations
-description: Canonical fsuite tool chains — which sequences actually work for common tasks.
+description: Canonical fsuite tool chains — pipe contracts, MCP equivalents, and which sequences actually work.
 sidebar:
   order: 4
 ---
 
-## The core chain
+## The pipe contract
 
-The default for "I need to understand and modify something in this repo."
+fsuite tools communicate via two pipe-friendly output modes:
 
-<div class="fs-pipeline">
-  <span class="fs-pn fs-pn-entry">ftree</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fs</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fmap</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fread</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fedit</span>
-</div>
+- **`-o paths`** — one file path per line (the pipe currency)
+- **`-o json`** — structured data for programmatic decisions
 
-## Investigation chain
+The rule: **producers** output paths, **consumers** read paths from stdin.
 
-Spans multiple sessions or context windows. `fcase` brackets the work.
+### Producers (output file paths)
 
-<div class="fs-pipeline">
-  <span class="fs-pn fs-pn-entry">fcase init</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">ftree</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fs</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fmap</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fread</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fcase note</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fedit</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn fs-pn-entry">fcase resolve</span>
-</div>
+| Tool | Flag | What it produces |
+|------|------|-----------------|
+| `fsearch` | `-o paths` | File paths matching a glob/name pattern |
+| `fcontent` | `-o paths` | File paths containing a literal string |
 
-## Debugging chain
+### Consumers (read paths from stdin)
 
-`fcase` captures the hypothesis, the repro steps, and the fix — so if the fix fails, the next attempt starts with context.
+| Tool | Stdin behavior | Notes |
+|------|---------------|-------|
+| `fcontent` | Reads paths, searches inside them | up to 2000 files |
+| `fmap` | Reads paths, maps symbols | up to 2000 files |
+| `fread` | `--from-stdin --stdin-format=paths` | up to `--max-files` |
+| `fedit` | `--targets-file -` | batch patches |
 
-<div class="fs-pipeline">
-  <span class="fs-pn">fbash</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fs</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fmap</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fread</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fcase</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fedit</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn fs-pn-entry">fbash</span>
-</div>
+### Non-pipe tools (arg-based)
 
-## Refactoring chain
+`fread`, `fedit`, `ftree`, `fprobe`, `fcase`, `freplay`, `fmetrics` take arguments, not stdin pipe lists. They sit at chain endpoints, not in the middle.
 
-The key move: use `fedit --symbol` for each symbol instead of doing a text-replace across files. Zero ambiguity.
+<div class="fs-mcp-note">
+  <h4>⚠ MCP CALLERS — SEQUENTIAL LIMIT</h4>
+  <p>If you call fsuite tools <b>through the MCP server</b>, every call is <b>sequential</b>. The MCP protocol does not pipe — the agent constructs the chain by calling tools one at a time and reusing prior results.</p>
+  <p><b>Escape hatch:</b> install fsuite as native Debian package or shell scripts and pipe directly. You can keep <code>fbash</code> as your MCP entry point and run real Unix pipes inside it: <code>fbash "fsearch -o paths '*.py' | fmap -o json"</code>. That unlocks combination calls instead of being trapped in sequential MCP.</p>
+</div>
 
-<div class="fs-pipeline">
-  <span class="fs-pn">fcontent</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fsearch</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fmap</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn fs-pn-entry">fedit --symbol</span>
+## Valid 2-command chains
+
+| Chain | Purpose | Example |
+|-------|---------|---------|
+| `fsearch \| fcontent` | Find files by name, search inside | `fsearch -o paths '*.py' src \| fcontent "def authenticate"` |
+| `fsearch \| fmap` | Find files, map symbols | `fsearch -o paths '*.rs' src \| fmap -o json` |
+| `fcontent \| fmap` | Find files containing text, map symbols | `fcontent -o paths "TODO" src \| fmap -o json` |
+| `fcontent \| fcontent` | Progressive narrowing | `fcontent -o paths "import" src \| fcontent "authenticate"` |
+
+## Valid 3-command chains
+
+<div class="fs-pipeline-v2">
+  <div class="fs-pipeline-row">
+    <span class="fs-pn">fsearch</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fcontent</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-keystone">fmap</span>
+  </div>
+  <div class="fs-pipeline-undernote">
+    <span><code>fsearch -o paths '*.py' | fcontent -o paths "class" | fmap -o json</code></span>
+  </div>
 </div>
 
-## Binary investigation chain
+## Valid 4-command chains
 
-When the target is a compiled binary, an obfuscated bundle, or anything text tools can't read.
+```bash
+fsearch -o paths '*.sh' \
+  | fcontent -o paths "function" \
+  | fmap -o json \
+  | python3 -c "..."
+```
 
-<div class="fs-pipeline">
-  <span class="fs-pn fs-pn-branch">fprobe strings</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn fs-pn-branch">fprobe scan</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn fs-pn-branch">fprobe window</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn fs-pn-branch">fprobe patch</span>
+Tested: produced 1956 symbols from the fsuite repo in one pipeline.
+
+## Investigation patterns
+
+### Pattern 1 — "What uses this function?"
+```bash
+fcontent -o paths "authenticate" src | fmap -o json
+```
+
+### Pattern 2 — "Find all Python tests and see what they test"
+```bash
+fsearch -o paths 'test_*.py' tests | fmap -o json
+```
+
+### Pattern 3 — "Which configs mention this key?"
+```bash
+fsearch -o paths '*.json' . | fcontent "api_key"
+```
+
+### Pattern 4 — Full investigation chain
+
+<div class="fs-pipeline-v2">
+  <div class="fs-pipeline-row">
+    <span class="fs-pn fs-pn-entry">fcase init</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">ftree</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-bridge">fsearch │ fcontent</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-keystone">fmap</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fread</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn">fedit</span>
+    <span class="fs-arr"></span>
+    <span class="fs-pn fs-pn-entry">fcase resolve</span>
+  </div>
 </div>
 
-## fcase lifecycle
+```bash
+ftree --snapshot -o json /project
+fsearch -o paths '*.rs' src | fcontent -o paths "pub fn" | fmap -o json
+fread src/auth.rs --symbol authenticate
+fcase init auth-fix --goal "Fix authenticate bypass"
+fedit src/auth.rs --function authenticate --replace "return true" --with "return verify(token)"
+fmetrics stats
+```
 
-The investigation ledger isn't a chain — it's a state machine that wraps every other chain.
+### Pattern 5 — Binary recon
+```bash
+fprobe scan binary --pattern "renderTool" --context 300
+fprobe window binary --offset 112730723 --before 50 --after 200
+fprobe strings binary --filter "diffAdded"
+```
+
+## fcase lifecycle
 
 <div class="fs-fcase">
   <div class="fs-fcase-state"><b>init</b><span>open the seam</span></div>
@@ -105,22 +140,13 @@ The investigation ledger isn't a chain — it's a state machine that wraps every
   <div class="fs-fcase-state fs-fcase-end"><b>resolve</b><span>close + archive</span></div>
 </div>
 
-## Replay chain
-
-Rerun a traced investigation step-by-step. Useful for post-mortems and regression tests.
-
-```bash
-freplay --session <id>
-```
-
-## Measurement chain
-
-Ask the telemetry database what worked last time and what probably works next.
+## Invalid chains (and why)
 
-<div class="fs-pipeline">
-  <span class="fs-pn">fmetrics import</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn">fmetrics stats</span>
-  <span class="fs-arr"></span>
-  <span class="fs-pn fs-pn-entry">fmetrics predict</span>
-</div>
+| Chain | Why it fails |
+|-------|-------------|
+| `fread \| anything` | fread outputs file content, not paths |
+| `fedit \| anything` | fedit outputs diffs, not paths |
+| `ftree \| fcontent` | ftree outputs a tree, not paths |
+| `fmap \| fread` | fmap outputs symbol data, not paths |
+| `fprobe \| anything` | fprobe outputs JSON/text, not paths |
+| `fcase \| anything` | fcase outputs investigation state, not paths |
diff --git a/site/src/content/docs/reference/cheatsheet.md b/site/src/content/docs/reference/cheatsheet.md
deleted file mode 100644
index 58636de..0000000
--- a/site/src/content/docs/reference/cheatsheet.md
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: Cheat Sheet
-description: One-line recipes for every fsuite tool. Copy, paste, adapt.
-sidebar:
-  order: 1
----
-
-## Discovery
-
-```bash
-# Territory scan — one call replaces 10-15 Glob/LS rounds
-ftree --snapshot -o json /project
-
-# Unified search — auto-routes by query intent
-fs "authenticate" --scope '*.py'
-
-# File discovery
-fsearch '*.py' src -o paths
-
-# Directory listing with recon
-fls src/providers --mode recon
-
-# Bounded content search
-fcontent "authenticate" src/*.py
-```
-
-## Reading
-
-```bash
-# Symbol skeleton of a file
-fmap src/auth.py
-
-# Read exactly one function
-fread src/auth.py --symbol authenticate
-
-# Read an exact line range
-fread src/auth.py --lines 120:160
-
-# Read with context around a pattern match
-fread src/auth.py --around "JWT_SECRET"
-```
-
-## Editing
-
-```bash
-# Replace an exact line range (fastest mode)
-fedit src/auth.py --lines 71:73 --with-text "new code"
-
-# Scope edit to a symbol without needing unique context
-fedit src/auth.py --function_name authenticate --replace "old" --with-text "new"
-
-# Insert after an anchor
-fedit src/auth.py --after "import foo" --with-text "\nimport bar"
-
-# Create a new file atomically
-fwrite src/new.ts --content "file contents"
-```
-
-## Shell
-
-```bash
-# Token-budgeted shell — suggests fsuite tools when you're doing something silly
-fbash --tag build -- npm run build
-
-# Background job
-fbash --background -- npm test
-```
-
-## Investigation
-
-```bash
-fcase init my-bug --goal "trace 401 errors"
-fcase note my-bug --body "root cause: stale JWT in redis"
-fcase resolve my-bug --summary "added TTL check to middleware"
-
-# Search past cases before starting new work
-fcase find --status all --deep --query "auth"
-```
-
-## Binary
-
-```bash
-# Extract strings
-fprobe strings ./binary --pattern VERSION
-
-# Window-read bytes around an offset
-fprobe window ./binary --offset 0x1000 --size 256
-
-# In-place patch
-fprobe patch ./binary --offset 0x1234 --replace "new bytes"
-```
-
-## Measurement
-
-```bash
-fmetrics import                  # pull JSONL → SQLite
-fmetrics stats -o json           # summary
-fmetrics predict /project        # best-next-tool prediction
-freplay --session auth-bug       # rerun a traced investigation
-```
-
-## Output formats
-
-```bash
--o json     # Programmatic parsing
--o paths    # Pipe file lists into other tools
--o pretty   # Human terminal output (default)
--q          # Existence check, silent, exit code only
-```
diff --git a/site/src/content/docs/reference/cheatsheet.mdx b/site/src/content/docs/reference/cheatsheet.mdx
new file mode 100644
index 0000000..ccba206
--- /dev/null
+++ b/site/src/content/docs/reference/cheatsheet.mdx
@@ -0,0 +1,536 @@
+---
+title: Cheat Sheet
+description: Every fsuite command, every flag, every canonical chain — copy-paste ready and agent-scrapeable.
+sidebar:
+  order: 1
+---
+
+import { Card } from '@astrojs/starlight/components';
+
+> Copy-paste ready. Every command runs headless (no prompts, no TTY needed) unless marked **Interactive**. Agents: this page is the canonical scrape target. Section anchors match tool names.
+
+<div class="fs-cheat-nav">
+  <a href="#fs">fs</a>
+  <a href="#ftree">ftree</a>
+  <a href="#fls">fls</a>
+  <a href="#fsearch">fsearch</a>
+  <a href="#fcontent">fcontent</a>
+  <a href="#fmap">fmap</a>
+  <a href="#fread">fread</a>
+  <a href="#fedit">fedit</a>
+  <a href="#fwrite">fwrite</a>
+  <a href="#fbash">fbash</a>
+  <a href="#fcase">fcase</a>
+  <a href="#freplay">freplay</a>
+  <a href="#fprobe">fprobe</a>
+  <a href="#fmetrics">fmetrics</a>
+</div>
+
+## How to read this page
+
+Each tool block has three parts: **drone profile** (one-line role · classification · chain position), **commands table** (every canonical invocation), and **terminal sample** (Monokai-print of real output as the agent sees it).
+
+<div class="fs-mcp-note">
+  <h4>⚠ MCP CALLERS — READ THIS FIRST</h4>
+  <p>If you call fsuite tools <b>through the MCP server</b>, every call is <b>sequential</b> — the MCP protocol does not pipe. You'll get correct results, but you'll lose the parallelism that makes Unix pipes fast.</p>
+  <p>For full performance, install fsuite as a native CLI (Debian package or shell scripts) and pipe directly: <code>fsearch -o paths '*.py' | fmap -o json</code>. You can keep <code>fbash</code> as your MCP entry point and have the agent call other fsuite tools through it via shell — that's how you unlock combination calls instead of being trapped in sequential MCP.</p>
+</div>
+
+---
+
+## fs
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fs</span>
+    <span class="fs-drone-tagline">Unified search orchestrator · the front door</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">RECON</span></div>
+    <div><b>Chain position</b><span>1 (entry)</span></div>
+    <div><b>Auto-routes to</b><span>fsearch · fcontent · fmap</span></div>
+    <div><b>MCP</b><span>structured output</span></div>
+  </div>
+</div>
+
+| Call | What it does |
+|------|-------------|
+| `fs "authenticate"` | Unified search — scouts, finds, maps, returns ranked results in one call |
+| `fs "error handler" --scope '**/*.py'` | Narrow the search surface to a glob |
+| `fs "class AuthHandler" --intent symbol` | Force symbol-name intent over auto-detection |
+| `fs "TODO" --intent content` | Force in-file text content intent |
+| `fs "*.log" --intent file` | Force file-name pattern intent |
+| `fs "def authenticate" -o json` | JSON with ranked hits, tool breakdown, confidence |
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fs(teleport)</b> · symbol intent · <span class="fs-term-cost">328ms · ~80 tokens</span></div>
+<pre><span class="tk-dot">●</span> Now let me find the teleport code and the Telegram agent:
+<span class="tk-mut">·</span>
+<span class="tk-tool">fs</span>(teleport | path: <span class="tk-str">"/home/user/Projects/nightfox/src"</span> | intent: <span class="tk-str">"symbol"</span> | scope: <span class="tk-str">"*.ts"</span>)
+  <span class="tk-arrow">└─</span> symbol (high) via fsearch <span class="tk-arrow">→</span> fcontent <span class="tk-arrow">→</span> fmap
+     explicit intent=symbol
+     <span class="tk-num">50</span> candidates, <span class="tk-num">1</span> enriched, <span class="tk-num">328</span>ms
+<span class="tk-mut">·</span>
+     nightfox/src/claude/command-parser.ts <span class="tk-com">(1 matches)</span>
+       <span class="tk-num">50</span>  · <span class="tk-str">'/teleport'</span>  <span class="tk-com">// Move session to terminal (forked)</span>
+<span class="tk-mut">·</span>
+     <span class="tk-cyan">next</span> <span class="tk-arrow">→</span> fread(path: <span class="tk-str">"/home/user/.../command-parser.ts"</span>, around: teleport)
+<span class="tk-mut">·</span></pre>
+</div>
+
+---
+
+## ftree
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">ftree</span>
+    <span class="fs-drone-tagline">Territory scout · directory recon</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">RECON</span></div>
+    <div><b>Chain position</b><span>2 (scout)</span></div>
+    <div><b>Pipe</b><span>not chainable (arg-based)</span></div>
+    <div><b>Output</b><span>pretty · paths · json</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `ftree /project` | Tree view, depth 3, default excludes, 200-line cap |
+| `ftree --recon /project` | Recon: per-dir item counts and sizes |
+| `ftree -L5 /project/src` | Deeper tree (depth 5) of a subdir |
+| `ftree -o json /project` | Structured JSON tree with metadata envelope |
+| `ftree -o paths /project` | Flat file list, one per line |
+| `ftree --recon -o json /project` | Recon JSON: per-dir inventory |
+| `ftree --snapshot /project` | Recon inventory + tree excerpt in one output |
+| `ftree --snapshot -o json /project` | Snapshot JSON: recon + tree, agent-ready |
+| `ftree --recon --hide-excluded /project` | Clean recon, no excluded summaries |
+| `ftree --include .git /project` | Show `.git` even though normally ignored |
+| `ftree -I 'docs\|*.md' /project` | Exclude additional patterns |
+| `ftree --no-default-ignore /project` | Disable built-in ignore list |
+| `ftree --self-check` | Verify tree availability |
+
+---
+
+## fls
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fls</span>
+    <span class="fs-drone-tagline">Structured directory listing · ls replacement with recon mode</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">RECON</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>Pipe</b><span>not chainable</span></div>
+    <div><b>Output</b><span>pretty · json</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fls /project` | Structured listing with type, size, language hints |
+| `fls /project --recon` | Adds per-entry recon data — sizes + counts |
+| `fls /project -o json` | JSON for programmatic decisions |
+| `fls /project --depth 1` | Limit recursion depth |
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fls(/project/src/telegram)</b> · recon mode</div>
+<pre><span class="tk-tool">fls</span>(<span class="tk-str">"/home/user/Projects/nightfox/src/telegram"</span> | mode: <span class="tk-str">"recon"</span>)
+  <span class="tk-arrow">└─</span> Recon(/home/user/Projects/nightfox/src/telegram, depth=1)
+     <span class="tk-num">7</span> entries (7 visible, <span class="tk-num">0</span> default-excluded)
+<span class="tk-mut">·</span>
+     message-sender.ts          —    <span class="tk-num">17.9K</span>
+     telegraph.ts               —    <span class="tk-num">12K</span>
+     terminal-renderer.ts       —    <span class="tk-num">10.3K</span>
+     markdown.ts                —    <span class="tk-num">6.7K</span>
+     terminal-settings.ts       —    <span class="tk-num">2.8K</span>
+     session-lane.ts            —    <span class="tk-num">1.2K</span>
+     deduplication.ts           —    <span class="tk-num">1005</span>
+<span class="tk-mut">·</span></pre>
+</div>
+
+---
+
+## fsearch
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fsearch</span>
+    <span class="fs-drone-tagline">Filename / path search · fd-aware</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">NARROW</span></div>
+    <div><b>Chain position</b><span>3 (narrow files)</span></div>
+    <div><b>Pipe</b><span>producer (-o paths)</span></div>
+    <div><b>Output</b><span>pretty · paths · json</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fsearch '*.log' /var/log` | Find all `.log` files (pretty output) |
+| `fsearch log /var/log` | Bare word `log` auto-expands to `*.log` |
+| `fsearch 'upscale*' /home/user` | Files starting with `upscale` |
+| `fsearch '*progress*' /home/user` | Files containing `progress` |
+| `fsearch --output paths '*.py' /project` | One path per line — pipe currency |
+| `fsearch --output json '*.conf' /etc` | JSON with `total_found`, `results[]`, `backend` |
+| `fsearch --include 'src' --exclude '*test*' '*.py' /project` | Scope to source, skip tests |
+| `fsearch --max 10 '*.py' /project` | Limit to first 10 results |
+| `fsearch --backend fd '*.rs' /src` | Force `fd` backend (faster) |
+| `fsearch --self-check` | Show available backends |
+
+---
+
+## fcontent
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fcontent</span>
+    <span class="fs-drone-tagline">Bounded content search · token-capped ripgrep</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">NARROW</span></div>
+    <div><b>Chain position</b><span>3 (narrow content)</span></div>
+    <div><b>Pipe</b><span>producer + consumer</span></div>
+    <div><b>Output</b><span>pretty · paths · json</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fcontent "ERROR" /var/log` | Search for `ERROR` inside files |
+| `fcontent "TODO" /project` | Find every `TODO` in a project tree |
+| `fcontent --output paths "ERROR" /var/log` | Only file paths that matched |
+| `fcontent --output json "ERROR" /var/log` | JSON with `matches[]`, counts |
+| `fcontent -m 20 "debug" /project` | Cap output to 20 match lines |
+| `fcontent -n 50 "debug" /project` | Cap to 50 files searched |
+| `fcontent --rg-args "-i" "error" /var/log` | Case-insensitive |
+| `fcontent --rg-args "-w" "main" /project` | Whole-word match |
+
+---
+
+## fmap
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fmap</span>
+    <span class="fs-drone-tagline">Symbol cartography · the keystone — the gap native CLI doesn't fill</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-keystone">KEYSTONE</span></div>
+    <div><b>Chain position</b><span>4 (bridge to read)</span></div>
+    <div><b>Pipe</b><span>consumer (stdin paths)</span></div>
+    <div><b>Languages</b><span>50+</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fmap /project` | Map all source files (pretty output) |
+| `fmap /project/src/auth.py` | Map a single file |
+| `fmap -o json /project` | JSON output with symbol metadata |
+| `fmap --name authenticate -o json /project` | Filter by symbol-name match |
+| `fmap -o paths /project` | File paths that contain symbols |
+| `fmap -t function /project` | Functions only |
+| `fmap -t class /project` | Classes only |
+| `fmap --no-imports /project` | Skip import lines |
+| `fmap -L bash /project/scripts` | Force language |
+| `fmap -m 50 /project` | Cap shown symbols |
+| `fsearch -o paths '*.py' /project \| fmap -o json` | Pipeline: find then map |
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fmap(reconciler.ts)</b> · 27 symbols · typescript <span class="fs-term-cost">~98K tokens saved vs cat</span></div>
+<pre><span class="tk-tool">fmap</span>(path: <span class="tk-str">"/home/user/Projects/brane-code/src/ink/reconciler.ts"</span>)
+  [ <span class="tk-num">27</span> symbols | typescript ]
+     <span class="tk-num">3</span>    <span class="tk-key">import</span>     <span class="tk-key">import</span> \{ appendFileSync \} <span class="tk-key">from</span> <span class="tk-str">'fs'</span>
+     <span class="tk-num">4</span>    <span class="tk-key">import</span>     <span class="tk-key">import</span> createReconciler <span class="tk-key">from</span> <span class="tk-str">'react-reconciler'</span>
+     <span class="tk-num">5</span>    <span class="tk-key">import</span>     <span class="tk-key">import</span> \{ getYogaCounters \} <span class="tk-key">from</span> <span class="tk-str">'src/native-ts/yoga-layout/index'</span>
+     <span class="tk-num">24</span>   <span class="tk-key">import</span>     <span class="tk-key">import</span> \{ Dispatcher \} <span class="tk-key">from</span> <span class="tk-str">'./events/dispatcher.js'</span>
+     <span class="tk-num">28</span>   <span class="tk-key">import</span>     <span class="tk-key">import</span> applyStyles, \{ <span class="tk-key">type</span> Styles, <span class="tk-key">type</span> TextStyles \} <span class="tk-key">from</span> <span class="tk-str">'./styles'</span>
+     <span class="tk-num">60</span>   <span class="tk-key">type</span>       <span class="tk-key">type</span> AnyObject = Record<span class="tk-purple">&lt;</span>string, unknown<span class="tk-purple">&gt;</span>
+     <span class="tk-num">92</span>   <span class="tk-key">function</span>   <span class="tk-key">const</span> diff = (before: AnyObject, after: AnyObject): AnyObject
+     <span class="tk-num">95</span>   <span class="tk-key">function</span>   <span class="tk-key">const</span> cleanupYogaNode = (node: DOMElement | TextNode): <span class="tk-key">void</span>
+     <span class="tk-num">114</span>  <span class="tk-key">function</span>   <span class="tk-key">function</span> setEventHandler(node: DOMElement, key: string, value: <span class="tk-key">unknown</span>)
+     <span class="tk-num">158</span>  <span class="tk-key">function</span>   <span class="tk-key">export function</span> getOwnerChain(fiber: unknown): string[] \{
+     <span class="tk-num">191</span>  <span class="tk-key">constant</span>   <span class="tk-key">const</span> COMMIT_LOG = process.env.<span class="tk-fn">CLAUDE_CODE_COMMIT_LOG</span>
+     <span class="tk-num">205</span>  <span class="tk-key">export</span>     <span class="tk-key">export function</span> recordYogaMs(ms: number): <span class="tk-key">void</span>
+     <span class="tk-num">217</span>  <span class="tk-key">function</span>   <span class="tk-key">export function</span> resetProfileCounters(): <span class="tk-key">void</span>
+<span class="tk-mut">·</span></pre>
+</div>
+
+---
+
+## fread
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fread</span>
+    <span class="fs-drone-tagline">Budgeted reading · symbol &amp; line-range resolution · PDF + image media</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">READ</span></div>
+    <div><b>Chain position</b><span>5 (read)</span></div>
+    <div><b>Pipe</b><span>consumer (--from-stdin)</span></div>
+    <div><b>Media</b><span>PDF · image · diff</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fread /path/to/file.py` | Read a file with default caps |
+| `fread /path/to/file.py -r 120:220` | Precise inclusive line range |
+| `fread /path/to/file.py --head 50` | First 50 lines |
+| `fread /path/to/file.py --tail 40` | Last 40 lines |
+| `fread /path/to/file.py --around-line 150 -B 5 -A 15` | Context around line 150 |
+| `fread /path/to/file.py --around "def authenticate" -B 5 -A 20` | Context around literal pattern |
+| `fread /path/to/file.py --symbol authenticate -o json` | One exact symbol block |
+| `fread /project/src --symbol authenticate -o json` | Resolve & read symbol from a directory |
+| `fread /path/to/file.py --max-lines 80 --max-bytes 12000` | Hard output budgets |
+| `fread /path/to/file.py --token-budget 2000 -o json` | Cap by estimated tokens |
+| `fsearch -o paths '*.py' /p \| fread --from-stdin --stdin-format=paths --max-files 5` | Read first 5 from a pipeline |
+| `git diff \| fread --from-stdin --stdin-format=unified-diff -B 3 -A 10` | Read context around hunks |
+| `fread screenshot.png` | Read image with auto-resize |
+| `fread invoice.pdf` | Extract PDF text |
+| `fread paper.pdf --render --pages 1:5` | Rasterize PDF pages |
+| `fread big.pdf --meta-only` | PDF metadata only |
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fread(--around teleport)</b> · 66 lines · -829 tokens vs full read</div>
+<pre><span class="tk-tool">fread</span>(/home/user/Projects/nightfox/src/discord/commands/teleport.ts | head: <span class="tk-num">80</span>)
+  [ <span class="tk-num">66</span> lines | <span class="tk-warn">-829 tokens</span> ]
+     <span class="tk-line">1</span>  <span class="tk-key">import</span> \{ ChatInputCommandInteraction \} <span class="tk-key">from</span> <span class="tk-str">'discord.js'</span>;
+     <span class="tk-line">2</span>  <span class="tk-key">import</span> \{ discordChatId \} <span class="tk-key">from</span> <span class="tk-str">'../id-mapper.js'</span>;
+     <span class="tk-line">3</span>  <span class="tk-key">import</span> \{ sessionManager \} <span class="tk-key">from</span> <span class="tk-str">'../../claude/session-manager.js'</span>;
+     <span class="tk-line">4</span>  <span class="tk-key">import</span> \{ config \} <span class="tk-key">from</span> <span class="tk-str">'../../config.js'</span>;
+     <span class="tk-line">5</span>  <span class="tk-key">import</span> path <span class="tk-key">from</span> <span class="tk-str">'path'</span>;
+     <span class="tk-line">6</span>
+     <span class="tk-line">7</span>  <span class="tk-key">export async function</span> <span class="tk-fn">handleTeleport</span>(interaction: ChatInputCommandInteraction): Promise<span class="tk-purple">&lt;</span><span class="tk-key">void</span><span class="tk-purple">&gt;</span> \{
+     <span class="tk-line">8</span>     <span class="tk-key">const</span> chatId = <span class="tk-fn">discordChatId</span>(interaction.user.id);
+     <span class="tk-line">9</span>
+     <span class="tk-line">10</span> <span class="tk-com">// Try active in-memory session first, then fall back to most recent from history</span>
+     <span class="tk-line">11</span> <span class="tk-key">let</span> session = sessionManager.<span class="tk-fn">getSession</span>(chatId);
+     <span class="tk-line">12</span> <span class="tk-key">if</span> (!session) \{
+     <span class="tk-line">13</span>    session = sessionManager.<span class="tk-fn">resumeLastSession</span>(chatId) ?? <span class="tk-key">undefined</span>;
+     <span class="tk-line">14</span> \}
+<span class="tk-mut">·</span></pre>
+</div>
+
+---
+
+## fedit
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fedit</span>
+    <span class="fs-drone-tagline">Surgical patches · line-range · symbol-scoped · anchor-based</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-edit">PATCH</span></div>
+    <div><b>Chain position</b><span>7 (act)</span></div>
+    <div><b>Default</b><span>dry-run (CLI)</span></div>
+    <div><b>Guard</b><span>--expect · --expect-sha256</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fedit /path/file.py --replace 'old' --with 'new'` | Preview exact replacement (dry-run) |
+| `fedit /path/file.py --replace 'old' --with 'new' --apply` | Apply the replacement |
+| `fedit /path/file.py --lines 71:73 --with "    return deny()\n"` | Replace a specific line range |
+| `fedit /path/file.py --after 'def authenticate(user):' --content-file patch.txt` | Insert after anchor |
+| `fedit /path/file.py --before 'return True' --stdin --apply` | Insert from stdin before anchor |
+| `fedit /path/file.py --symbol authenticate --replace 'X' --with 'Y'` | Symbol-scoped patch |
+| `fedit /path/file.py --function authenticate --replace 'X' --with 'Y'` | Function-scoped (no --symbol-type needed) |
+| `fedit /path/file.py --class AuthHandler --after '...' --with '...'` | Class-block scoped |
+| `printf '/a.py\n/b.py\n' \| fedit --targets-file - --targets-format paths --replace 'x' --with 'y'` | Batch from stdin |
+| `fedit --targets-file map.json --targets-format fmap-json --function auth --replace 'X' --with 'Y' --apply` | Symbol-scoped batch via fmap JSON |
+| `fedit /path/file.py --expect 'def authenticate' --replace 'X' --with 'Y'` | Require expected text first |
+| `fedit /path/file.py --expect-sha256 HASH --replace 'X' --with 'Y' --apply` | Guard with content hash |
+| `fedit --create /path/new.py --content-file body.txt --apply` | Create new file from payload |
+| `fedit --replace-file /path/file.py --content-file rewrite.txt --apply` | Replace entire file |
+
+---
+
+## fwrite
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fwrite</span>
+    <span class="fs-drone-tagline">Atomic file creation · MCP-only</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-edit">PATCH</span></div>
+    <div><b>Available</b><span>MCP only (no CLI)</span></div>
+    <div><b>Use for</b><span>create or full rewrite</span></div>
+    <div><b>Use fedit for</b><span>surgical changes</span></div>
+  </div>
+</div>
+
+> MCP-only tool. Not available as a CLI binary. Call via the fsuite MCP server. Writes or overwrites a file from a string payload. Use `fedit` for surgical patches; `fwrite` for complete file creation or full rewrites.
+
+---
+
+## fbash
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fbash</span>
+    <span class="fs-drone-tagline">Token-budgeted shell · classification · session state · MCP entry point</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-edit">EXEC</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>MCP advantage</b><span>shells out to all CLI tools</span></div>
+    <div><b>Output</b><span>budgeted · classified</span></div>
+  </div>
+</div>
+
+> **The MCP escape hatch.** When you're calling fsuite through MCP and feel sequential limits biting, route through `fbash` and run real Unix pipes inside it: `fbash "fsearch -o paths '*.py' src | fmap -o json"`. You get pipe-speed inside an MCP-friendly tool.
+
+---
+
+## fcase
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fcase</span>
+    <span class="fs-drone-tagline">Investigation continuity ledger · cross-session state machine</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-state">STATE</span></div>
+    <div><b>Chain position</b><span>wraps every chain</span></div>
+    <div><b>Lifecycle</b><span>init → note → handoff → resolve</span></div>
+    <div><b>Storage</b><span>~/.fsuite/fcase.db</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fcase init auth-seam --goal "Trace authenticate flow"` | Create a new investigation |
+| `fcase list -o json` | List known cases |
+| `fcase status auth-seam -o json` | Read current case state |
+| `fcase note auth-seam --body "Focused on denial branch"` | Append a note |
+| `fcase target add auth-seam --path /p/src/auth.py --symbol authenticate --symbol-type function --state active` | Mark a seam as active |
+| `fcase evidence auth-seam --tool fread --path /p --lines 40:72 --summary "..."` | Store structured proof |
+| `fcase hypothesis add auth-seam --body "Cleanup bug in cancellation"` | Track a hypothesis |
+| `fcase reject auth-seam --hypothesis-id 1 --reason "..."` | Reject a hypothesis |
+| `fmap -o json /p \| fcase target import auth-seam` | Import mapped symbols as targets |
+| `fread -o json /p --around "def auth" -A 20 \| fcase evidence import auth-seam` | Import bounded reads |
+| `fcase next auth-seam --body "Patch denial branch next"` | Update next best move |
+| `fcase handoff auth-seam -o json` | Emit handoff packet |
+| `fcase export auth-seam -o json` | Export full envelope |
+
+---
+
+## freplay
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">freplay</span>
+    <span class="fs-drone-tagline">Derivation chain replay · deterministic rerun</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-state">REPLAY</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>Pairs with</b><span>fcase</span></div>
+    <div><b>Use for</b><span>post-mortems · regression</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `freplay record auth-seam --purpose "Traced denial" -- fread /p --around 'def auth'` | Record a derivation step |
+| `freplay record auth-seam -- fcontent -o paths "auth" src` | Record without purpose annotation |
+| `freplay show auth-seam` | Show full replay chain |
+| `freplay show auth-seam -o json` | Machine-readable chain w/ timestamps |
+| `freplay list` | List cases with replay chains |
+| `freplay list -o json` | JSON list with step counts |
+
+---
+
+## fprobe
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fprobe</span>
+    <span class="fs-drone-tagline">Binary / bundle inspection + patching · text tools can't reach</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-binary">BINARY</span></div>
+    <div><b>Chain position</b><span>specialist branch</span></div>
+    <div><b>Use when</b><span>target is compiled or obfuscated</span></div>
+    <div><b>Subcommands</b><span>strings · scan · window · patch</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fprobe strings /path/to/binary` | Extract printable strings |
+| `fprobe strings /path --min-len 8` | Strings 8+ chars |
+| `fprobe strings /path --filter "http"` | Strings containing literal substring |
+| `fprobe scan /path --pattern "userFacingName"` | Find literal byte pattern (offset + context) |
+| `fprobe scan /path --pattern "x" --context 200 -o json` | JSON with offset, hex, surrounding bytes |
+| `fprobe window /path --offset 0x100 --after 256` | Read 256 bytes after offset |
+| `fprobe window /path --offset 0x100 --before 64 --after 256` | Read bytes before + after |
+| `fprobe window /path --offset 0x100 --after 256 --decode hex` | Hex dump |
+
+---
+
+## fmetrics
+
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fmetrics</span>
+    <span class="fs-drone-tagline">Telemetry analytics · tool-chain prediction</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-state">LEARN</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>Storage</b><span>SQLite</span></div>
+    <div><b>Use for</b><span>predict best next step</span></div>
+  </div>
+</div>
+
+| Command | What it does |
+|---------|-------------|
+| `fmetrics import` | Import `telemetry.jsonl` into SQLite |
+| `fmetrics stats` | Aggregate runtime + reliability dashboard |
+| `fmetrics stats -o json` | Machine-readable stats |
+| `fmetrics history --tool ftree --limit 10` | Recent runs for one tool |
+| `fmetrics history --project MyApp` | Filter by project |
+| `fmetrics combos --project fsuite` | Evidence-backed combo patterns |
+| `fmetrics combos --starts-with ftree,fsearch --contains fmap -o json` | Filter combo analytics |
+| `fmetrics recommend --after ftree,fsearch --project fsuite` | Suggest the strongest next step |
+| `fmetrics predict /project` | Estimate runtimes |
+| `fmetrics profile` | Show machine profile |
+| `fmetrics clean --days 30` | Prune old telemetry |
+
+---
+
+## Canonical pipelines
+
+| Workflow | Command chain |
+|----------|--------------|
+| **Full scout** | `ftree --snapshot -o json /project` |
+| **Find + map** | `fsearch -o paths '*.py' /p \| fmap -o json` |
+| **Find + grep** | `fsearch -o paths '*.log' /var/log \| fcontent "ERROR"` |
+| **Find + read** | `fsearch -o paths '*.py' /p \| fread --from-stdin --stdin-format=paths --max-files 5 -o json` |
+| **Map + read** | `fmap --name auth -o json /p \| fread --symbol auth -o json` |
+| **Binary recon** | `fprobe scan /bin && fprobe strings /bin --filter "http"` |
+| **Investigation** | `fcase init seam --goal "..." && fmap -o json /p \| fcase target import seam && fcase handoff seam -o json` |
+| **Batch patch** | `fsearch -o paths '*.py' /p \| fedit --targets-file - --targets-format paths --replace 'x' --with 'y' --apply` |
+| **Git diff read** | `git diff \| fread --from-stdin --stdin-format=unified-diff -o json` |
+
+---
+
+## MCP vs CLI — pipe semantics
+
+| Mode | Pipe behavior | Performance |
+|------|---------------|-------------|
+| **CLI (Debian / shell)** | Real Unix pipes, parallel where possible | Fastest |
+| **CLI inside `fbash` (MCP)** | Real pipes inside the budgeted shell | Fast — MCP escape hatch |
+| **Pure MCP tool calls** | Sequential, agent constructs chain by hand | Correct, slower |
+
+The MCP adapter handles `-o json` automatically — agents always get structured JSON back regardless of mode.
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index 2aefff0..39d3e4b 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -1172,3 +1172,212 @@ starlight-tabs [role="tab"][aria-selected="true"] {
   .fs-fcase { flex-direction: column; }
   .fs-fcase .fs-arr { transform: rotate(90deg); margin: 0 auto; }
 }
+
+/* ============================================================
+   fsuite — ROUND 3 components appendix
+   APPEND to bottom of site/src/styles/custom.css
+   (after the round-2 appendix you already pasted)
+   ============================================================ */
+
+/* ---------- 30. MONOKAI TERMINAL BLOCK ---------- */
+.fs-term {
+  margin: 16px 0 24px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 8px;
+  background: #1e1f1c;
+  overflow: hidden;
+  box-shadow: 0 1px 0 0 rgba(255,255,255,0.04) inset, 0 8px 28px -10px rgba(0,0,0,0.5);
+}
+.fs-term-bar {
+  display: flex; align-items: center; gap: 10px;
+  padding: 8px 14px;
+  background: #14150f;
+  border-bottom: 1px solid rgba(255,255,255,0.06);
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.10em;
+  text-transform: uppercase;
+  color: #75715e;
+}
+.fs-term-bar::before {
+  content: "● ● ●";
+  color: #49483e;
+  letter-spacing: 0.22em;
+  margin-right: 6px;
+}
+.fs-term-bar b { color: #f8f8f2; font-weight: 500; }
+.fs-term-bar .fs-term-cost {
+  margin-left: auto;
+  color: #a6e22e;
+  font-weight: 600;
+}
+.fs-term pre {
+  margin: 0 !important;
+  padding: 14px 18px !important;
+  background: transparent !important;
+  border: none !important;
+  border-radius: 0 !important;
+  font-family: var(--sl-font-mono);
+  font-size: 12.5px;
+  line-height: 1.55;
+  color: #f8f8f2;
+  overflow-x: auto;
+}
+/* Monokai token classes — match the screenshots exactly */
+.tk-dot     { color: #a6e22e; font-weight: 700; }              /* the green ● before agent steps */
+.tk-tool    { color: #a6e22e; font-weight: 600; }              /* fread, fmap, fs etc. */
+.tk-key     { color: #f92672; }                                /* keywords, function, class */
+.tk-fn      { color: #66d9ef; }                                /* function names */
+.tk-str     { color: #e6db74; }                                /* strings */
+.tk-num     { color: #fd971f; }                                /* numbers, line numbers */
+.tk-com     { color: #75715e; font-style: italic; }            /* comments */
+.tk-mut     { color: #75715e; }                                /* muted info, paths */
+.tk-arrow   { color: #66d9ef; font-weight: 600; }              /* next →, └─ */
+.tk-ok      { color: #a6e22e; font-weight: 600; }              /* ✓ */
+.tk-warn    { color: #fd971f; }                                /* ⚠ */
+.tk-err     { color: #f92672; font-weight: 600; }              /* ✗ */
+.tk-cyan    { color: #66d9ef; }                                /* import paths, types */
+.tk-purple  { color: #ae81ff; }                                /* operators, special */
+.tk-line    { color: #75715e; padding-right: 10px; user-select: none; } /* gutter line numbers */
+
+/* ---------- 31. DRONE PROFILE CARD ---------- */
+.fs-drone {
+  margin: 0 0 28px;
+  padding: 18px 20px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 10px;
+  background:
+    linear-gradient(180deg, rgba(58, 255, 157, 0.04), transparent 50%),
+    var(--sl-color-bg);
+  position: relative;
+  overflow: hidden;
+}
+.fs-drone::before {
+  content: "";
+  position: absolute;
+  top: 0; left: 0; right: 0;
+  height: 2px;
+  background: linear-gradient(90deg, transparent, var(--fs-accent), transparent);
+  opacity: 0.6;
+}
+.fs-drone-head {
+  display: flex; flex-wrap: wrap; align-items: baseline; gap: 14px;
+  margin-bottom: 12px;
+}
+.fs-drone-call {
+  font-family: var(--sl-font-mono);
+  font-size: 22px;
+  font-weight: 700;
+  color: var(--fs-accent);
+  letter-spacing: -0.01em;
+}
+.fs-drone-tagline {
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.10em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-2);
+}
+.fs-drone-meta {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 10px;
+  margin-top: 6px;
+}
+.fs-drone-meta > div {
+  display: flex; flex-direction: column; gap: 2px;
+  padding: 8px 12px;
+  background: var(--sl-color-gray-7);
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 5px;
+}
+.fs-drone-meta b {
+  font-family: var(--sl-font-mono);
+  font-size: 10px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-3);
+  font-weight: 500;
+}
+.fs-drone-meta span {
+  font-family: var(--sl-font-mono);
+  font-size: 13px;
+  color: var(--sl-color-white);
+}
+.fs-drone-meta span.role-recon  { color: var(--fs-info); }
+.fs-drone-meta span.role-keystone { color: var(--fs-accent); font-weight: 600; }
+.fs-drone-meta span.role-edit { color: var(--fs-warn); }
+.fs-drone-meta span.role-state { color: var(--fs-accent); }
+.fs-drone-meta span.role-binary { color: var(--fs-warn); }
+
+/* ---------- 32. CHEAT SHEET QUICK NAV ---------- */
+.fs-cheat-nav {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(110px, 1fr));
+  gap: 6px;
+  margin: 16px 0 32px;
+  padding: 14px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 8px;
+  background: var(--sl-color-gray-7);
+}
+.fs-cheat-nav a {
+  font-family: var(--sl-font-mono);
+  font-size: 12.5px;
+  text-decoration: none;
+  color: var(--sl-color-gray-1);
+  padding: 6px 10px;
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 4px;
+  text-align: center;
+  background: var(--sl-color-bg);
+}
+.fs-cheat-nav a:hover {
+  border-color: var(--fs-accent);
+  color: var(--fs-accent);
+}
+
+/* ---------- 33. MCP-LIMITATION CALLOUT ---------- */
+.fs-mcp-note {
+  margin: 24px 0;
+  padding: 16px 20px;
+  border: 1px solid color-mix(in oklab, var(--fs-warn) 35%, var(--sl-color-hairline-shade));
+  border-left: 3px solid var(--fs-warn);
+  border-radius: 6px;
+  background: color-mix(in oklab, var(--fs-warn) 5%, var(--sl-color-bg));
+}
+.fs-mcp-note h4 {
+  margin: 0 0 6px;
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--fs-warn);
+}
+.fs-mcp-note p {
+  margin: 0 0 8px;
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--sl-color-gray-1);
+}
+.fs-mcp-note p:last-child { margin: 0; }
+.fs-mcp-note code {
+  background: color-mix(in oklab, var(--fs-warn) 10%, transparent);
+  color: var(--fs-warn);
+}
+
+/* ---------- 34. FOOTER STATUS BAR (optional, for layout override) ---------- */
+.fs-footer-status {
+  margin-top: 60px;
+  padding: 14px 20px;
+  border-top: 1px solid var(--sl-color-hairline);
+  display: flex; flex-wrap: wrap;
+  justify-content: space-between; align-items: center;
+  gap: 14px;
+  font-family: var(--sl-font-mono);
+  font-size: 11px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--sl-color-gray-3);
+}
+.fs-footer-status .fs-fd-live { color: var(--fs-accent); }

From 9e492d6b3e2717caccd81801241fd1a9d6212e64 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 14:46:01 -0500
Subject: [PATCH 04/19] =?UTF-8?q?Docs:=20round=204=20=E2=80=94=20per-comma?=
 =?UTF-8?q?nd=20drone=20profiles=20+=20canonical=20chains=20+=20terminal?=
 =?UTF-8?q?=20samples?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Design deliverable v4: 14 preamble blocks, one per fsuite tool,
inserted above the existing `## Help output` heading on each commands/<TOOL>.md
page. The build-time --help block stays as the source of truth below.

Each preamble has:
- Drone profile card (codename · role · chain position · pipe behavior)
- Canonical chains (2-5 realistic pipe patterns per tool)
- Monokai terminal sample for the heavy hitters: fs, fls, fmap, fread,
  fcontent, fsearch (uses round-3's .fs-term + .tk-* classes)

Highlights:
- fmap explicitly tagged KEYSTONE with "Native CLI has nothing like it"
- fbash framed as the MCP escape hatch with concrete pipe-inside-fbash examples
- fwrite labeled MCP-only with the new-file-vs-surgical decision rule
- fcase/freplay framed as continuity tools for cross-session memory loss
- fprobe framed as the binary branch when fcontent returns nothing

MDX strict-mode: Claude Design pre-escaped braces to &#123;/&#125; entities
in <pre> blocks (learned from rounds 2-3); fixed 4 remaining blank-line-
inside-pre cases in fs.md/fls.md preambles via Python pre-pass with
<span class="tk-mut">·</span> separators. All 14 pages render at HTTP 200,
zero MDX compile errors.

No CSS this round — round 3's classes carry the visual styling.
---
 site/src/content/docs/commands/fbash.md    | 36 ++++++++++++
 site/src/content/docs/commands/fcase.md    | 50 ++++++++++++++++
 site/src/content/docs/commands/fcontent.md | 41 +++++++++++++
 site/src/content/docs/commands/fedit.md    | 48 +++++++++++++++
 site/src/content/docs/commands/fls.md      | 51 ++++++++++++++++
 site/src/content/docs/commands/fmap.md     | 67 +++++++++++++++++++++
 site/src/content/docs/commands/fmetrics.md | 51 ++++++++++++++++
 site/src/content/docs/commands/fprobe.md   | 43 ++++++++++++++
 site/src/content/docs/commands/fread.md    | 68 ++++++++++++++++++++++
 site/src/content/docs/commands/freplay.md  | 36 ++++++++++++
 site/src/content/docs/commands/fs.md       | 53 +++++++++++++++++
 site/src/content/docs/commands/fsearch.md  | 39 +++++++++++++
 site/src/content/docs/commands/ftree.md    | 39 +++++++++++++
 site/src/content/docs/commands/fwrite.md   | 22 +++++++
 14 files changed, 644 insertions(+)

diff --git a/site/src/content/docs/commands/fbash.md b/site/src/content/docs/commands/fbash.md
index 9eb1aad..5065cf2 100644
--- a/site/src/content/docs/commands/fbash.md
+++ b/site/src/content/docs/commands/fbash.md
@@ -9,6 +9,42 @@ sidebar:
 
 `fbash` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fbash</span>
+    <span class="fs-drone-tagline">Token-budgeted shell · classification · session state · MCP escape hatch</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-edit">EXEC</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>MCP advantage</b><span>shells out to all CLI tools</span></div>
+    <div><b>Output</b><span>budgeted · classified</span></div>
+  </div>
+</div>
+
+`fbash` is `bash` with the same agent-aware budget discipline as the rest of fsuite. Output is capped, classified (stdout vs stderr vs status), and session state persists between calls so you can `cd`, set environment variables, and chain commands across invocations.
+
+**The MCP escape hatch.** If you're calling fsuite tools through the MCP server, every call is sequential — MCP doesn't pipe. But `fbash` runs a real shell, which means real Unix pipes work inside it. Wrap your chain in one `fbash` call and get full pipeline speed back, even from MCP-only agents.
+
+## Canonical chains
+
+```bash
+# Run a real Unix pipe from inside MCP — the escape hatch
+fbash "fsearch -o paths '*.py' src | fmap -o json"
+
+# Triple-chain inside one fbash call
+fbash "fsearch -o paths '*.py' src \
+       | fcontent -o paths 'class' \
+       | fmap -o json"
+
+# Stateful session — cd persists to the next call
+fbash "cd /project && export DEBUG=1"
+fbash "pwd && env | grep DEBUG"
+
+# Long-running with cap
+fbash "find / -name '*.log' 2>/dev/null"   # output capped automatically
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `fbash`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fcase.md b/site/src/content/docs/commands/fcase.md
index 8e2d2d2..8cff9a9 100644
--- a/site/src/content/docs/commands/fcase.md
+++ b/site/src/content/docs/commands/fcase.md
@@ -9,6 +9,56 @@ sidebar:
 
 `fcase` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fcase</span>
+    <span class="fs-drone-tagline">Investigation continuity ledger · cross-session state machine</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-state">STATE</span></div>
+    <div><b>Chain position</b><span>wraps every chain</span></div>
+    <div><b>Lifecycle</b><span>init → note → handoff → resolve</span></div>
+    <div><b>Storage</b><span>~/.fsuite/fcase.db</span></div>
+  </div>
+</div>
+
+`fcase` is the investigation ledger. Every non-trivial debug, refactor, or recon ends with the agent saying "ok now what" — `fcase` answers that question across sessions. Open a case at the start, drop notes and evidence as you go, hand off cleanly to the next agent (or the next you).
+
+It's the *continuity* tool. Without it, every new session starts from zero. With it, the next agent reads the case envelope and knows exactly where the trail left off.
+
+## Canonical chains
+
+```bash
+# Open a case
+fcase init auth-seam --goal "Trace authenticate flow"
+
+# List active cases
+fcase list -o json
+
+# Append a note
+fcase note auth-seam --body "Focused on the denial branch"
+
+# Add a target seam
+fcase target add auth-seam \
+  --path /project/src/auth.py --symbol authenticate \
+  --symbol-type function --state active
+
+# Import targets from fmap
+fmap -o json /project | fcase target import auth-seam
+
+# Import evidence from fread
+fread -o json /project --around "def auth" -A 20 \
+  | fcase evidence import auth-seam
+
+# Track and reject hypotheses
+fcase hypothesis add auth-seam --body "Cleanup bug in cancellation"
+fcase reject auth-seam --hypothesis-id 1 --reason "Verified safe"
+
+# Hand off to the next agent
+fcase next auth-seam --body "Patch denial branch next"
+fcase handoff auth-seam -o json
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `fcase`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fcontent.md b/site/src/content/docs/commands/fcontent.md
index 64fd3f6..7583468 100644
--- a/site/src/content/docs/commands/fcontent.md
+++ b/site/src/content/docs/commands/fcontent.md
@@ -9,6 +9,47 @@ sidebar:
 
 `fcontent` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fcontent</span>
+    <span class="fs-drone-tagline">Bounded content search · token-capped ripgrep</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">NARROW</span></div>
+    <div><b>Chain position</b><span>3 (narrow content)</span></div>
+    <div><b>Pipe</b><span>producer + consumer</span></div>
+    <div><b>Output</b><span>pretty · paths · json</span></div>
+  </div>
+</div>
+
+`fcontent` is `ripgrep` with a token budget. Same speed, same regex power, but capped output so a single grep doesn't blow your context. Use it when you know what's inside a file but not which file.
+
+It's both a producer (`-o paths` outputs file paths that matched) and a consumer (reads paths from stdin to narrow within a previously-filtered set). That makes it the bridge tool in 3-step chains.
+
+## Canonical chains
+
+```bash
+# Search for a literal in a project
+fcontent "ERROR" /var/log
+
+# Get only file paths that matched (pipe currency)
+fcontent -o paths "TODO" /project
+
+# Pipe to fmap — find files containing a keyword, map their symbols
+fcontent -o paths "authenticate" /project | fmap -o json
+
+# Progressive narrowing — chain two fcontents
+fsearch -o paths '*.py' /project \
+  | fcontent -o paths "import" \
+  | fcontent "authenticate"
+
+# Cap match output explicitly
+fcontent -m 20 "debug" /project
+
+# Case-insensitive (passthrough to ripgrep)
+fcontent --rg-args "-i" "error" /var/log
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `fcontent`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fedit.md b/site/src/content/docs/commands/fedit.md
index 4108bd5..96f2e92 100644
--- a/site/src/content/docs/commands/fedit.md
+++ b/site/src/content/docs/commands/fedit.md
@@ -9,6 +9,54 @@ sidebar:
 
 `fedit` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fedit</span>
+    <span class="fs-drone-tagline">Surgical patches · line-range · symbol-scoped · anchor-based</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-edit">PATCH</span></div>
+    <div><b>Chain position</b><span>7 (act)</span></div>
+    <div><b>Default</b><span>dry-run (CLI)</span></div>
+    <div><b>Guard</b><span>--expect · --expect-sha256</span></div>
+  </div>
+</div>
+
+`fedit` makes edits without ambiguity. Three modes: **line-range** (`--lines 71:73`), **symbol-scoped** (`--function auth`, `--class AuthHandler`), and **anchor-based** (`--after 'def auth(...):'`). No more failed matches because of whitespace drift or an agent picking the wrong block of identical-looking code.
+
+Default is dry-run on the CLI — you see the diff, then add `--apply` to commit. Guard rails: `--expect` requires a literal string to be present first; `--expect-sha256` requires the file to match a known content hash.
+
+## Canonical chains
+
+```bash
+# Surgical replace — preview first
+fedit /project/src/auth.py --replace 'old text' --with 'new text'
+fedit /project/src/auth.py --replace 'old text' --with 'new text' --apply
+
+# Line-range replace
+fedit /project/src/auth.py --lines 71:73 --with "    return deny()\n"
+
+# Symbol-scoped — function or class block
+fedit /project/src/auth.py --function authenticate --replace 'X' --with 'Y'
+fedit /project/src/auth.py --class AuthHandler --after '...' --with '...'
+
+# Anchor-based insert
+fedit /project/src/auth.py --after 'def authenticate(user):' --content-file patch.txt
+
+# Batch patch via pipe
+fsearch -o paths '*.py' /project \
+  | fedit --targets-file - --targets-format paths \
+          --replace 'x' --with 'y' --apply
+
+# Symbol-scoped batch from fmap output
+fedit --targets-file map.json --targets-format fmap-json \
+      --function auth --replace 'X' --with 'Y' --apply
+
+# Guarded edit — refuses if file content drifted
+fedit /project/src/auth.py --expect-sha256 abc123 \
+      --replace 'X' --with 'Y' --apply
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `fedit`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fls.md b/site/src/content/docs/commands/fls.md
index 26bb738..357429e 100644
--- a/site/src/content/docs/commands/fls.md
+++ b/site/src/content/docs/commands/fls.md
@@ -9,6 +9,57 @@ sidebar:
 
 `fls` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fls</span>
+    <span class="fs-drone-tagline">Structured directory listing · ls replacement with recon mode</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">RECON</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>Pipe</b><span>not chainable</span></div>
+    <div><b>Output</b><span>pretty · json</span></div>
+  </div>
+</div>
+
+`fls` is the surgical version of `ftree` — one directory, one level deep (configurable), with structured metadata: type, size, language hints. When `ftree` would be too noisy and `cat`-ing a path tells you nothing, `fls` shows you exactly what's in this folder and nothing else.
+
+`--recon` mode adds per-entry sizes and counts in a clean column layout. JSON mode lets agents make programmatic decisions on what to read next.
+
+## Canonical chains
+
+```bash
+# Structured listing — type, size, language hints
+fls /project/src
+
+# Recon mode — sizes + counts, scannable column layout
+fls /project/src/telegram --recon
+
+# JSON for agents
+fls /project -o json
+
+# Limit depth (default 1, often plenty)
+fls /project --depth 1
+```
+
+## Terminal sample
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fls(/project/src/telegram)</b> · recon mode</div>
+<pre><span class="tk-tool">fls</span>(<span class="tk-str">"/home/user/Projects/nightfox/src/telegram"</span> | mode: <span class="tk-str">"recon"</span>)
+  <span class="tk-arrow">└─</span> Recon(/home/user/Projects/nightfox/src/telegram, depth=1)
+     <span class="tk-num">7</span> entries (7 visible, <span class="tk-num">0</span> default-excluded)
+<span class="tk-mut">·</span>
+     message-sender.ts          —    <span class="tk-num">17.9K</span>
+     telegraph.ts               —    <span class="tk-num">12K</span>
+     terminal-renderer.ts       —    <span class="tk-num">10.3K</span>
+     markdown.ts                —    <span class="tk-num">6.7K</span>
+     terminal-settings.ts       —    <span class="tk-num">2.8K</span>
+     session-lane.ts            —    <span class="tk-num">1.2K</span>
+     deduplication.ts           —    <span class="tk-num">1005</span>
+<span class="tk-mut">·</span></pre>
+</div>
+
 ## Help output
 
 The content below is the **live** `--help` output of `fls`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fmap.md b/site/src/content/docs/commands/fmap.md
index a1fca8b..7802aa2 100644
--- a/site/src/content/docs/commands/fmap.md
+++ b/site/src/content/docs/commands/fmap.md
@@ -9,6 +9,73 @@ sidebar:
 
 `fmap` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fmap</span>
+    <span class="fs-drone-tagline">Symbol cartography · the keystone — the gap native CLI doesn't fill</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-keystone">KEYSTONE</span></div>
+    <div><b>Chain position</b><span>4 (bridge to read)</span></div>
+    <div><b>Pipe</b><span>consumer (stdin paths)</span></div>
+    <div><b>Languages</b><span>50+</span></div>
+  </div>
+</div>
+
+**`fmap` is the headliner.** Native CLI has nothing like it. Given a file or a directory, `fmap` extracts the structural skeleton — every function, class, import, type, constant — with line numbers, in seconds, across 50+ languages.
+
+Why it matters: an agent that runs `fmap` first reads ~1% of a file's bytes and learns what's in it. Then it picks the symbol it actually wants and `fread`s exactly that block. Compare that to `cat`-ing a 3000-line module to figure out which function to look at.
+
+This is the keystone of every investigation chain.
+
+## Canonical chains
+
+```bash
+# Map a single file
+fmap /project/src/auth.py
+
+# Map every source file in a project
+fmap /project
+
+# Filter by symbol-name match — surgical
+fmap --name authenticate -o json /project
+
+# Pipe currency — fsearch produces, fmap consumes
+fsearch -o paths '*.py' /project | fmap -o json
+
+# Filter symbol type
+fmap -t function /project
+fmap -t class /project
+
+# Triple chain — narrow text first, then map structure
+fcontent -o paths "TODO" /project | fmap -o json
+
+# Followed by surgical fread
+fmap --name handleRequest -o json /project | jq '.symbols[0]'
+fread /project/src/server.ts --symbol handleRequest
+```
+
+## Terminal sample
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fmap(reconciler.ts)</b> · 27 symbols · typescript <span class="fs-term-cost">~98K tokens saved vs cat</span></div>
+<pre><span class="tk-tool">fmap</span>(path: <span class="tk-str">"/home/user/Projects/brane-code/src/ink/reconciler.ts"</span>)
+  [ <span class="tk-num">27</span> symbols | typescript ]
+     <span class="tk-num">3</span>    <span class="tk-key">import</span>     <span class="tk-key">import</span> &#123; appendFileSync &#125; <span class="tk-key">from</span> <span class="tk-str">'fs'</span>
+     <span class="tk-num">4</span>    <span class="tk-key">import</span>     <span class="tk-key">import</span> createReconciler <span class="tk-key">from</span> <span class="tk-str">'react-reconciler'</span>
+     <span class="tk-num">5</span>    <span class="tk-key">import</span>     <span class="tk-key">import</span> &#123; getYogaCounters &#125; <span class="tk-key">from</span> <span class="tk-str">'src/native-ts/yoga-layout/index'</span>
+     <span class="tk-num">28</span>   <span class="tk-key">import</span>     <span class="tk-key">import</span> applyStyles, &#123; <span class="tk-key">type</span> Styles, <span class="tk-key">type</span> TextStyles &#125; <span class="tk-key">from</span> <span class="tk-str">'./styles'</span>
+     <span class="tk-num">60</span>   <span class="tk-key">type</span>       <span class="tk-key">type</span> AnyObject = Record&lt;string, unknown&gt;
+     <span class="tk-num">92</span>   <span class="tk-key">function</span>   <span class="tk-key">const</span> diff = (before: AnyObject, after: AnyObject): AnyObject
+     <span class="tk-num">95</span>   <span class="tk-key">function</span>   <span class="tk-key">const</span> cleanupYogaNode = (node: DOMElement | TextNode): <span class="tk-key">void</span>
+     <span class="tk-num">114</span>  <span class="tk-key">function</span>   <span class="tk-key">function</span> setEventHandler(node: DOMElement, key: string, value: <span class="tk-key">unknown</span>)
+     <span class="tk-num">158</span>  <span class="tk-key">function</span>   <span class="tk-key">export function</span> getOwnerChain(fiber: unknown): string[] &#123;
+     <span class="tk-num">191</span>  <span class="tk-key">constant</span>   <span class="tk-key">const</span> COMMIT_LOG = process.env.<span class="tk-fn">CLAUDE_CODE_COMMIT_LOG</span>
+     <span class="tk-num">205</span>  <span class="tk-key">export</span>     <span class="tk-key">export function</span> recordYogaMs(ms: number): <span class="tk-key">void</span>
+     <span class="tk-num">217</span>  <span class="tk-key">function</span>   <span class="tk-key">export function</span> resetProfileCounters(): <span class="tk-key">void</span>
+<span class="tk-mut">·</span></pre>
+</div>
+
 ## Help output
 
 The content below is the **live** `--help` output of `fmap`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fmetrics.md b/site/src/content/docs/commands/fmetrics.md
index 3c46a74..680b88d 100644
--- a/site/src/content/docs/commands/fmetrics.md
+++ b/site/src/content/docs/commands/fmetrics.md
@@ -9,6 +9,57 @@ sidebar:
 
 `fmetrics` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fmetrics</span>
+    <span class="fs-drone-tagline">Telemetry analytics · tool-chain prediction</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-state">LEARN</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>Storage</b><span>SQLite</span></div>
+    <div><b>Use for</b><span>predict best next step</span></div>
+  </div>
+</div>
+
+`fmetrics` is the analytics layer. Every fsuite tool emits a telemetry record (path, timing, output size, success). `fmetrics` ingests those into SQLite and lets you ask:
+
+- Which tool combos actually win? (`combos`)
+- What's the strongest next step after `ftree → fsearch`? (`recommend`)
+- How long will this run on this machine? (`predict`)
+- What broke last week? (`stats`, `history`)
+
+It's how the toolchain learns. The agent's third tool call is statistically better than its first because `fmetrics` told it which patterns work.
+
+## Canonical chains
+
+```bash
+# Import telemetry into SQLite
+fmetrics import
+
+# Aggregate stats — runtime, reliability
+fmetrics stats
+fmetrics stats -o json
+
+# Recent runs of one tool
+fmetrics history --tool ftree --limit 10
+fmetrics history --project MyApp
+
+# Combo analytics — what chains win
+fmetrics combos --project fsuite
+fmetrics combos --starts-with ftree,fsearch --contains fmap -o json
+
+# Recommend the best next step
+fmetrics recommend --after ftree,fsearch --project fsuite
+
+# Predict runtimes for a path
+fmetrics predict /project
+
+# Housekeeping
+fmetrics profile
+fmetrics clean --days 30
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `fmetrics`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fprobe.md b/site/src/content/docs/commands/fprobe.md
index b3ddccc..f946146 100644
--- a/site/src/content/docs/commands/fprobe.md
+++ b/site/src/content/docs/commands/fprobe.md
@@ -9,6 +9,49 @@ sidebar:
 
 `fprobe` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fprobe</span>
+    <span class="fs-drone-tagline">Binary / bundle inspection + patching · text tools can't reach</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-binary">BINARY</span></div>
+    <div><b>Chain position</b><span>specialist branch</span></div>
+    <div><b>Use when</b><span>target is compiled or obfuscated</span></div>
+    <div><b>Subcommands</b><span>strings · scan · window · patch</span></div>
+  </div>
+</div>
+
+`fprobe` is for the targets text tools can't read — compiled binaries, minified bundles, obfuscated libraries. Four subcommands cover the workflow:
+
+- `strings` — extract printable strings (with length and substring filters)
+- `scan` — find a literal byte pattern, return offsets + context
+- `window` — read N bytes before/after an offset, decoded as text or hex
+- `patch` — write bytes at an offset with safety guards
+
+This is the binary recon branch — when `fcontent` returns nothing because the file isn't text, `fprobe` is the next move.
+
+## Canonical chains
+
+```bash
+# Extract printable strings, filtered
+fprobe strings /usr/local/bin/myapp --min-len 8 --filter "http"
+
+# Locate a literal pattern
+fprobe scan /usr/local/bin/myapp --pattern "userFacingName" -o json
+
+# Read context around an offset
+fprobe window /usr/local/bin/myapp --offset 0x100 --before 64 --after 256
+
+# Hex dump
+fprobe window /usr/local/bin/myapp --offset 0x100 --after 256 --decode hex
+
+# Full binary recon chain
+fprobe scan binary --pattern "renderTool" --context 300 -o json
+fprobe strings binary --filter "diffAdded"
+fprobe window binary --offset 112730723 --before 50 --after 200
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `fprobe`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fread.md b/site/src/content/docs/commands/fread.md
index 2d72025..418629c 100644
--- a/site/src/content/docs/commands/fread.md
+++ b/site/src/content/docs/commands/fread.md
@@ -9,6 +9,74 @@ sidebar:
 
 `fread` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fread</span>
+    <span class="fs-drone-tagline">Budgeted reading · symbol &amp; line-range resolution · PDF + image media</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">READ</span></div>
+    <div><b>Chain position</b><span>5 (read)</span></div>
+    <div><b>Pipe</b><span>consumer (--from-stdin)</span></div>
+    <div><b>Media</b><span>PDF · image · diff</span></div>
+  </div>
+</div>
+
+`fread` is `cat` with a brain. It can read a whole file (uncapped by default — you control budget), an exact line range, the first N or last N lines, context windows around a literal pattern, or **one specific symbol resolved by name** in a file or directory.
+
+It also reads media: PDF text extraction, PDF page rasterization, image base64 with auto-resize, and unified-diff hunks from git pipe. The token-budget flags (`--max-lines`, `--max-bytes`, `--token-budget`) cap output before it hits the agent's context.
+
+## Canonical chains
+
+```bash
+# Read exactly one symbol — no scrolling, no guessing
+fread /project/src/auth.py --symbol authenticate
+
+# Resolve a symbol from a directory scope
+fread /project/src --symbol authenticate -o json
+
+# Precise line range
+fread /project/src/server.py -r 120:220
+
+# Context window around a pattern
+fread /project/src/auth.py --around "def authenticate" -B 5 -A 20
+
+# Pipe currency consumer — fsearch produces, fread consumes first 5
+fsearch -o paths '*.py' /project \
+  | fread --from-stdin --stdin-format=paths --max-files 5 -o json
+
+# Read git diff context
+git diff | fread --from-stdin --stdin-format=unified-diff -B 3 -A 10
+
+# PDF and image reading
+fread invoice.pdf
+fread paper.pdf --render --pages 1:5
+fread screenshot.png
+```
+
+## Terminal sample
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fread(--around teleport)</b> · 66 lines · <span class="fs-term-cost">-829 tokens vs full read</span></div>
+<pre><span class="tk-tool">fread</span>(/home/user/Projects/nightfox/src/discord/commands/teleport.ts | head: <span class="tk-num">80</span>)
+  [ <span class="tk-num">66</span> lines | <span class="tk-warn">-829 tokens</span> ]
+     <span class="tk-line">1</span>  <span class="tk-key">import</span> &#123; ChatInputCommandInteraction &#125; <span class="tk-key">from</span> <span class="tk-str">'discord.js'</span>;
+     <span class="tk-line">2</span>  <span class="tk-key">import</span> &#123; discordChatId &#125; <span class="tk-key">from</span> <span class="tk-str">'../id-mapper.js'</span>;
+     <span class="tk-line">3</span>  <span class="tk-key">import</span> &#123; sessionManager &#125; <span class="tk-key">from</span> <span class="tk-str">'../../claude/session-manager.js'</span>;
+     <span class="tk-line">4</span>  <span class="tk-key">import</span> &#123; config &#125; <span class="tk-key">from</span> <span class="tk-str">'../../config.js'</span>;
+     <span class="tk-line">5</span>  <span class="tk-key">import</span> path <span class="tk-key">from</span> <span class="tk-str">'path'</span>;
+     <span class="tk-line">6</span>
+     <span class="tk-line">7</span>  <span class="tk-key">export async function</span> <span class="tk-fn">handleTeleport</span>(interaction: ChatInputCommandInteraction): Promise&lt;<span class="tk-key">void</span>&gt; &#123;
+     <span class="tk-line">8</span>     <span class="tk-key">const</span> chatId = <span class="tk-fn">discordChatId</span>(interaction.user.id);
+     <span class="tk-line">9</span>
+     <span class="tk-line">10</span> <span class="tk-com">// Try active in-memory session first, then fall back to most recent from history</span>
+     <span class="tk-line">11</span> <span class="tk-key">let</span> session = sessionManager.<span class="tk-fn">getSession</span>(chatId);
+     <span class="tk-line">12</span> <span class="tk-key">if</span> (!session) &#123;
+     <span class="tk-line">13</span>    session = sessionManager.<span class="tk-fn">resumeLastSession</span>(chatId) ?? <span class="tk-key">undefined</span>;
+     <span class="tk-line">14</span> &#125;
+<span class="tk-mut">·</span></pre>
+</div>
+
 ## Help output
 
 The content below is the **live** `--help` output of `fread`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/freplay.md b/site/src/content/docs/commands/freplay.md
index 2528994..ae4bacd 100644
--- a/site/src/content/docs/commands/freplay.md
+++ b/site/src/content/docs/commands/freplay.md
@@ -9,6 +9,42 @@ sidebar:
 
 `freplay` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">freplay</span>
+    <span class="fs-drone-tagline">Derivation chain replay · deterministic rerun</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-state">REPLAY</span></div>
+    <div><b>Chain position</b><span>specialist</span></div>
+    <div><b>Pairs with</b><span>fcase</span></div>
+    <div><b>Use for</b><span>post-mortems · regression</span></div>
+  </div>
+</div>
+
+`freplay` records the exact tool-call sequence inside a case, so you can rerun the chain deterministically later. Useful for post-mortems ("how did the agent reach this conclusion?"), regression tests, and onboarding ("here's the exact recon path I took to find this bug").
+
+It pairs with `fcase` — every replay step belongs to a case, and the recorded chain is part of the handoff envelope.
+
+## Canonical chains
+
+```bash
+# Record a step under a case (with purpose annotation)
+freplay record auth-seam --purpose "Traced denial branch" \
+  -- fread /project/src/auth.py --around 'def auth'
+
+# Record without purpose
+freplay record auth-seam \
+  -- fcontent -o paths "auth" /project/src
+
+# Show the full chain
+freplay show auth-seam
+freplay show auth-seam -o json
+
+# List cases that have a replay chain
+freplay list -o json
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `freplay`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fs.md b/site/src/content/docs/commands/fs.md
index c8f6a7a..a608a62 100644
--- a/site/src/content/docs/commands/fs.md
+++ b/site/src/content/docs/commands/fs.md
@@ -9,6 +9,59 @@ sidebar:
 
 `fs` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fs</span>
+    <span class="fs-drone-tagline">Unified search orchestrator · the front door</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">RECON</span></div>
+    <div><b>Chain position</b><span>1 (entry)</span></div>
+    <div><b>Auto-routes to</b><span>fsearch · fcontent · fmap</span></div>
+    <div><b>Intent modes</b><span>auto · file · content · symbol · nav</span></div>
+  </div>
+</div>
+
+`fs` is the meta-tool — feed it any query and it classifies the intent (filename pattern, in-file content, symbol name, or path navigation), builds the right chain of underlying tools, and returns ranked, enriched hits with a `next_hint` for follow-up.
+
+When in doubt, start here. When you know the exact tool you need, skip it.
+
+## Canonical chains
+
+`fs` is the entry point of every recon chain. It does not pipe — it returns final ranked hits with a `next_hint` you call next.
+
+```bash
+# Symbol scout — returns hits + next_hint to fread the right block
+fs "renderTool"
+
+# Filename intent forced — looks for files literally named like *.log
+fs --intent file "*.log" /var/log
+
+# Scoped symbol search — narrow to TypeScript only
+fs --scope "*.ts" McpServer
+
+# Pipe to jq — JSON mode auto-engages on pipe
+fs -o json "*.rs" | jq '.hits'
+```
+
+## Terminal sample
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fs(teleport)</b> · symbol intent · <span class="fs-term-cost">328ms · ~80 tokens</span></div>
+<pre><span class="tk-dot">●</span> Now let me find the teleport code:
+<span class="tk-mut">·</span>
+<span class="tk-tool">fs</span>(teleport | path: <span class="tk-str">"/home/user/Projects/nightfox/src"</span> | intent: <span class="tk-str">"symbol"</span> | scope: <span class="tk-str">"*.ts"</span>)
+  <span class="tk-arrow">└─</span> symbol (high) via fsearch <span class="tk-arrow">→</span> fcontent <span class="tk-arrow">→</span> fmap
+     explicit intent=symbol
+     <span class="tk-num">50</span> candidates, <span class="tk-num">1</span> enriched, <span class="tk-num">328</span>ms
+<span class="tk-mut">·</span>
+     nightfox/src/claude/command-parser.ts <span class="tk-com">(1 matches)</span>
+       <span class="tk-num">50</span>  · <span class="tk-str">'/teleport'</span>  <span class="tk-com">// Move session to terminal (forked)</span>
+<span class="tk-mut">·</span>
+     <span class="tk-cyan">next</span> <span class="tk-arrow">→</span> fread(path: <span class="tk-str">"/home/user/.../command-parser.ts"</span>, around: teleport)
+<span class="tk-mut">·</span></pre>
+</div>
+
 ## Help output
 
 The content below is the **live** `--help` output of `fs`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fsearch.md b/site/src/content/docs/commands/fsearch.md
index 15dab5e..6cba1b4 100644
--- a/site/src/content/docs/commands/fsearch.md
+++ b/site/src/content/docs/commands/fsearch.md
@@ -9,6 +9,45 @@ sidebar:
 
 `fsearch` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fsearch</span>
+    <span class="fs-drone-tagline">Filename / glob discovery · fd-aware · pipe currency producer</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">NARROW</span></div>
+    <div><b>Chain position</b><span>3 (narrow files)</span></div>
+    <div><b>Pipe</b><span>producer (-o paths)</span></div>
+    <div><b>Output</b><span>pretty · paths · json</span></div>
+  </div>
+</div>
+
+`fsearch` finds files by name or glob. It's the pipe currency producer — `-o paths` gives you one file path per line, ready to feed `fmap`, `fcontent`, or `fread`. Auto-detects `fd` for speed and falls back to `find`.
+
+Bare words auto-expand: `fsearch log /var/log` becomes `*.log`. Use this when you know what file pattern you want; use `fcontent` when you know what's inside the file but not its name.
+
+## Canonical chains
+
+```bash
+# Find all Python files
+fsearch '*.py' /project
+
+# Pipe to fmap — find then map symbols (the canonical 2-step)
+fsearch -o paths '*.py' /project | fmap -o json
+
+# Pipe to fcontent — find files of one type, search inside
+fsearch -o paths '*.log' /var/log | fcontent "ERROR"
+
+# Pipe to fread — read first 5 matched files
+fsearch -o paths '*.py' /project \
+  | fread --from-stdin --stdin-format=paths --max-files 5 -o json
+
+# Triple chain — glob → text-narrow → symbol-map
+fsearch -o paths '*.py' /project \
+  | fcontent -o paths "class" \
+  | fmap -o json
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `fsearch`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/ftree.md b/site/src/content/docs/commands/ftree.md
index 44acbb9..4c5a8ae 100644
--- a/site/src/content/docs/commands/ftree.md
+++ b/site/src/content/docs/commands/ftree.md
@@ -9,6 +9,45 @@ sidebar:
 
 `ftree` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">ftree</span>
+    <span class="fs-drone-tagline">Territory scout · directory recon · the first move</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-recon">RECON</span></div>
+    <div><b>Chain position</b><span>2 (scout)</span></div>
+    <div><b>Pipe</b><span>not chainable (arg-based)</span></div>
+    <div><b>Output</b><span>pretty · paths · json</span></div>
+  </div>
+</div>
+
+`ftree` is the territory map. Before you guess at what's in a project, drop a tree-snapshot — see what dirs exist, what's loud (lots of files), what's lean, and where the surface area really is. The `--recon` mode adds per-directory item counts and sizes so you can prioritize where to dig.
+
+Use it once at the start of every investigation. Use `--snapshot` when you want recon + a tree excerpt in one envelope.
+
+## Canonical chains
+
+`ftree` doesn't pipe (its output is a tree, not a list of paths) — it sits at the start of a chain to give context, then you act on what it shows.
+
+```bash
+# Default scout — 3-level tree, sensible excludes
+ftree /project
+
+# Recon mode — per-dir item counts + sizes
+ftree --recon /project
+
+# Snapshot — recon inventory + tree excerpt, agent-ready
+ftree --snapshot -o json /project
+
+# Deep dive into a specific subdir
+ftree -L5 /project/src
+
+# Full follow-up: scout, then map symbols of what looks promising
+ftree --recon /project
+fmap -o json /project/src/auth
+```
+
 ## Help output
 
 The content below is the **live** `--help` output of `ftree`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
diff --git a/site/src/content/docs/commands/fwrite.md b/site/src/content/docs/commands/fwrite.md
index 22cc3f1..03327e7 100644
--- a/site/src/content/docs/commands/fwrite.md
+++ b/site/src/content/docs/commands/fwrite.md
@@ -9,6 +9,28 @@ sidebar:
 
 `fwrite` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">fwrite</span>
+    <span class="fs-drone-tagline">Atomic file creation · MCP-only</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Role</b><span class="role-edit">CREATE</span></div>
+    <div><b>Available</b><span>MCP only (no CLI)</span></div>
+    <div><b>Use for</b><span>create or full rewrite</span></div>
+    <div><b>Use fedit for</b><span>surgical changes</span></div>
+  </div>
+</div>
+
+`fwrite` is the **MCP-only** atomic file creation tool. It writes or overwrites a file from a string payload. Not available as a CLI binary — agents call it directly through the fsuite MCP server.
+
+**Decision rule:**
+- Brand-new file → `fwrite`
+- Replacing an entire file end-to-end → `fwrite`
+- Any surgical change (line range, symbol, anchor) → `fedit`
+
+`fedit` has analogous functionality (`fedit --create`, `fedit --replace-file`) for CLI users without MCP — but if you're already on the MCP transport, `fwrite` is one call instead of two flags.
+
 ## Help output
 
 The content below is the **live** `--help` output of `fwrite`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.

From c4d7128b778b21b202a0d91c875b454c311a2f6e Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 14:58:13 -0500
Subject: [PATCH 05/19] =?UTF-8?q?Docs:=20round=205=20=E2=80=94=20architect?=
 =?UTF-8?q?ure=20trio=20rebuild=20+=20first-contact=20polish=20+=20deliver?=
 =?UTF-8?q?y=20flow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Design deliverable v5:
- custom.css: +88 lines (.fs-delivery flow diagram — color-coded
  Agent/Hooks/Block/MCP/Route/CLI/Exec/Telemetry/Log nodes with chain arrows
  reusing .fs-arr from rounds 3-4)
- architecture/index.mdx: NEW (80 lines) — pillars-at-a-glance overview, the
  Agent → Hooks → MCP → CLI → Telemetry delivery flow diagram, CLI-vs-MCP
  pipe semantics table, repo-paths-for-each-pillar table. Ties chains.md +
  mcp.md + hooks.md + telemetry.md together.
- architecture/mcp.md: rebuilt with drone-profile card, fbash escape-hatch
  pattern (multi-step pipe inside one MCP call), tool-list verification step
- architecture/hooks.md: rebuilt — full Read/Write/Edit/Grep/Glob → fsuite
  redirect table, exit 2 protocol explained, "why hooks + MCP together"
  reframed as complementary not redundant
- architecture/telemetry.md: rebuilt — why telemetry exists (fmetrics
  learning loop), ~/.fsuite/ storage-shape diagram, sanitization tradeoff
  reasoning from Episode 0
- getting-started/first-contact.md: drone-profile header, monokai terminal
  sample on the ftree --snapshot step, stronger "what you should notice"
  callout

MDX strict-mode: only first-contact.md had blank-line-inside-pre cases (3
fixed via tk-mut separator span). Hit a YAML frontmatter colon-collision
on architecture-index.mdx — "three pillars: MCP, hooks, telemetry." had
unquoted ': ' that the YAML parser misread as a nested mapping. Quoted the
description value to fix. All 5 affected pages return 200; dev log clean
since 14:57:40 reload.
---
 site/src/content/docs/architecture/hooks.md   | 76 +++++++++++++---
 site/src/content/docs/architecture/index.mdx  | 80 +++++++++++++++++
 site/src/content/docs/architecture/mcp.md     | 89 ++++++++++++++++---
 .../content/docs/architecture/telemetry.md    | 88 +++++++++++++++---
 .../docs/getting-started/first-contact.md     | 80 ++++++++++++-----
 site/src/styles/custom.css                    | 89 +++++++++++++++++++
 6 files changed, 441 insertions(+), 61 deletions(-)
 create mode 100644 site/src/content/docs/architecture/index.mdx

diff --git a/site/src/content/docs/architecture/hooks.md b/site/src/content/docs/architecture/hooks.md
index f7f88c1..45d8900 100644
--- a/site/src/content/docs/architecture/hooks.md
+++ b/site/src/content/docs/architecture/hooks.md
@@ -1,41 +1,68 @@
 ---
 title: Hooks & Enforcement
-description: How to block an agent's native Read/Write/Edit/Grep/Glob tools and force them to use fsuite instead.
+description: Block an agent's native Read/Write/Edit/Grep/Glob tools and force them to use fsuite instead.
 sidebar:
   order: 2
 ---
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">HOOKS</span>
+    <span class="fs-drone-tagline">The enforcement layer · block native primitives, force fsuite usage</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Type</b><span>Claude Code PreToolUse hooks</span></div>
+    <div><b>Targets</b><span>Read · Write · Edit · Grep · Glob</span></div>
+    <div><b>Effect</b><span>reject + redirect message</span></div>
+    <div><b>Pairs with</b><span>MCP adapter</span></div>
+  </div>
+</div>
+
 ## The problem
 
 By default, coding agents reach for their native tools — `Read`, `Write`, `Edit`, `Grep`, `Glob`, `Bash`. Those tools flood context, read entire files, and fail on whitespace drift. fsuite exists to fix that, but only if the agent actually uses fsuite.
 
+If you install fsuite and don't enforce its use, the agent will reach for `Read` first because that's what its training reinforced. The MCP exposure tells it `fread` exists. The hooks layer is what makes `fread` the **default**.
+
 ## The solution
 
-Claude Code hooks can intercept tool calls *before* they run, inspect the tool name, and either allow, reject, or redirect. A `PreToolUse` hook that rejects `Read` with the message `"Use fsuite fread instead"` will force the agent to switch tools.
+Claude Code hooks intercept tool calls **before** they run. A `PreToolUse` hook can inspect the tool name, reject the call with a message, and the agent sees that message in its tool result. Reject `Read` with `"Use fsuite fread instead"` and the agent immediately tries `fread` — exactly what you want.
+
+The hook does not need to know anything about fsuite. It just needs to refuse the native primitive with a useful redirect message.
 
 ## Example hook configuration
 
 Add to `~/.claude/settings.json`:
 
 ```json
-{
-  "hooks": {
+\{
+  "hooks": \{
     "PreToolUse": [
-      {
+      \{
         "matcher": "Read",
         "hooks": [
-          {
+          \{
             "type": "command",
             "command": "echo 'Use fsuite fread instead of native Read. Use fsuite structured reads with symbol/range control. Example: fread --symbol NAME path' >&2; exit 2"
-          }
+          \}
         ]
-      }
+      \}
     ]
-  }
-}
+  \}
+\}
 ```
 
-Apply the same pattern to `Write`, `Edit`, `Grep`, and `Glob` to fully enforce fsuite usage.
+Apply the same pattern to `Write`, `Edit`, `Grep`, and `Glob`:
+
+| Native tool | fsuite redirect | Why |
+|-------------|----------------|-----|
+| `Read` | `fread --symbol NAME path` | reads exactly one symbol |
+| `Write` | `fwrite path` (MCP) or `fedit --create path` (CLI) | atomic with safety nets |
+| `Edit` | `fedit --symbol NAME --replace x --with y` | symbol-scoped, dry-run by default |
+| `Grep` | `fcontent "pattern"` | token-capped, ranked |
+| `Glob` | `fsearch '*.py'` | fd-aware, suppresses noise dirs |
+
+`Bash` you leave alone — `fbash` exists, but bash itself is occasionally still the right choice. Don't block it.
 
 ## Why hooks + MCP together
 
@@ -44,6 +71,29 @@ Hooks **block** native tools. They cannot route or translate calls. MCP **expose
 1. Reaches for `Read` → hook blocks → agent sees the error message
 2. Agent tries again with `fread` from the fsuite MCP → succeeds
 
-The two layers are complementary, not redundant.
+The two layers are complementary, not redundant. Hooks alone would block native tools without offering an alternative the agent can find. MCP alone would expose fsuite without preventing the agent from sliding back to its trained reflexes.
+
+## The exit-2 pattern
+
+The example above uses `exit 2` — that's the protocol. Exit code `2` from a `PreToolUse` hook tells Claude Code "block this call, but show the message to the agent instead of the user." Exit code `0` would silently allow it. Exit code `1` would fail with the message visible to the user.
+
+Always use `2` for redirects. The agent reads the message, learns, and switches tools.
+
+## Verification
+
+After adding the hooks, ask your agent in a fresh session:
+
+```
+Read /tmp/test.txt
+```
+
+You should see the agent immediately try `fread /tmp/test.txt` instead. If it still uses native `Read`, the hook isn't loading — check `~/.claude/settings.json` syntax and restart the agent.
+
+## Planned: install script
+
+The plan is to ship `scripts/install-hooks.sh` that adds the correct hook config to `~/.claude/settings.json` idempotently — read existing config, merge in the five PreToolUse blocks, write back without clobbering anything else. Until then, hand-edit per the example above.
+
+## Related
 
-> **TODO:** ship a `scripts/install-hooks.sh` that adds the correct hook config to `~/.claude/settings.json` idempotently.
+- [MCP adapter](/fsuite/architecture/mcp/) — exposes fsuite tools that the hook redirects to
+- [First contact](/fsuite/getting-started/first-contact/) — verify your enforcement is live with a known prompt
diff --git a/site/src/content/docs/architecture/index.mdx b/site/src/content/docs/architecture/index.mdx
new file mode 100644
index 0000000..81eaa28
--- /dev/null
+++ b/site/src/content/docs/architecture/index.mdx
@@ -0,0 +1,80 @@
+---
+title: Architecture
+description: "How fsuite delivers itself to agents — three pillars: MCP, hooks, telemetry."
+sidebar:
+  order: 0
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Three pillars, one toolchain
+
+The 14 fsuite drones are the payload. The architecture is what gets them in the agent's hands and keeps them flying. Three pillars:
+
+<CardGrid>
+  <Card title="MCP Adapter" icon="puzzle">
+    Exposes every fsuite tool as a structured MCP server so MCP-aware agents (Claude Code, Hermes) call them directly without going through native `Bash`. Adds Monokai-themed structured output rendering. [Read the MCP page →](/fsuite/architecture/mcp/)
+  </Card>
+  <Card title="Hooks &amp; Enforcement" icon="seti:lock">
+    `PreToolUse` hooks block native `Read` / `Write` / `Edit` / `Grep` / `Glob` so the agent has no choice but to reach for `fread` / `fedit` / `fcontent` / `fsearch`. Hooks block, MCP exposes — they're complementary. [Read the hooks page →](/fsuite/architecture/hooks/)
+  </Card>
+  <Card title="Telemetry" icon="rocket">
+    Every tool emits a JSONL event with timing, output size, exit code, and caller attribution. `fmetrics` ingests into SQLite and predicts the best next tool. Local-only, opt-out. [Read the telemetry page →](/fsuite/architecture/telemetry/)
+  </Card>
+  <Card title="Chain Combinations" icon="random">
+    Pipe contracts — which tools produce file paths, which consume them, which 2/3/4-step chains actually work. The recipe book. [Read the chains page →](/fsuite/architecture/chains/)
+  </Card>
+</CardGrid>
+
+## The delivery flow
+
+<div class="fs-delivery">
+  <div class="fs-delivery-row">
+    <div class="fs-delivery-node">
+      <b>Agent</b>
+      <span>Claude Code · Codex · Hermes</span>
+    </div>
+    <span class="fs-arr"></span>
+    <div class="fs-delivery-node fs-delivery-block">
+      <b>Hooks layer</b>
+      <span>blocks native Read/Write/Edit</span>
+    </div>
+    <span class="fs-arr"></span>
+    <div class="fs-delivery-node fs-delivery-route">
+      <b>MCP server</b>
+      <span>exposes 14 fsuite tools</span>
+    </div>
+    <span class="fs-arr"></span>
+    <div class="fs-delivery-node fs-delivery-exec">
+      <b>fsuite CLI</b>
+      <span>14 drones · token-budgeted</span>
+    </div>
+    <span class="fs-arr"></span>
+    <div class="fs-delivery-node fs-delivery-log">
+      <b>Telemetry</b>
+      <span>JSONL → SQLite → fmetrics</span>
+    </div>
+  </div>
+</div>
+
+The flow is left-to-right: the agent attempts a tool call, hooks block native primitives that would flood context, MCP routes the call to a fsuite drone, the drone executes under token-budget caps, and telemetry records the event for `fmetrics` to learn from later.
+
+## CLI vs MCP — which mode are you in?
+
+| Mode | How it runs | Pipe behavior | Speed |
+|------|-------------|---------------|-------|
+| **CLI native (Debian / shell)** | `fsearch -o paths '*.py' \| fmap` | Real Unix pipes, parallel | Fastest |
+| **CLI inside `fbash` (MCP escape hatch)** | `fbash "fsearch -o paths '*.py' \| fmap"` | Real pipes inside a budgeted shell | Fast |
+| **Pure MCP tool calls** | Agent calls `fsearch`, then `fmap`, sequentially | Sequential — agent constructs chain by hand | Correct, slower |
+
+If you're running fsuite through MCP and feel sequential limits biting, **route through `fbash`** — see the [MCP page](/fsuite/architecture/mcp/) for the escape-hatch pattern.
+
+## Where each pillar lives in the repo
+
+| Pillar | Path | Status |
+|--------|------|--------|
+| MCP adapter | `mcp/index.js` | Production (v1.5.0+) |
+| Hooks config | `scripts/install-hooks.sh` *(planned)* | Manual today, automated soon |
+| Telemetry library | `_fsuite_common.sh` + `~/.fsuite/telemetry.jsonl` | Production |
+| Telemetry analytics | `fmetrics` + `fmetrics-predict.py` | Production |
+| Chain contracts | `docs/internal/specs/chain-combinations.md` | Spec → docs |
diff --git a/site/src/content/docs/architecture/mcp.md b/site/src/content/docs/architecture/mcp.md
index a755ba9..88eba19 100644
--- a/site/src/content/docs/architecture/mcp.md
+++ b/site/src/content/docs/architecture/mcp.md
@@ -5,18 +5,40 @@ sidebar:
   order: 1
 ---
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">MCP</span>
+    <span class="fs-drone-tagline">The transport · structured tool exposure for MCP-aware agents</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Path</b><span>mcp/index.js</span></div>
+    <div><b>Wraps</b><span>all 14 fsuite tools</span></div>
+    <div><b>Renders</b><span>Monokai structured output</span></div>
+    <div><b>Pipe semantics</b><span>sequential (use fbash)</span></div>
+  </div>
+</div>
+
 ## What it does
 
-The MCP adapter (`mcp/index.js`) wraps every fsuite CLI tool in a Model Context Protocol server so that MCP-aware agents — Claude Code, Hermes, etc. — can call the tools directly without going through their native `Bash` tool.
+The MCP adapter (`mcp/index.js`) wraps every fsuite CLI tool in a Model Context Protocol server so that MCP-aware agents — Claude Code, Hermes, Codex with MCP — can call the tools directly without going through their native `Bash` tool.
+
+The adapter does three things:
+
+1. **Schema exposure** — declares each fsuite tool with structured JSON Schema so agents know exactly what arguments to pass
+2. **Token-budget enforcement** — caps responses even if a tool emits more than the budget allows
+3. **Monokai rendering** — pretty-prints search results, file reads, and tool outputs in the agent's chat surface (the part the author loves most)
+
+Every response includes a `next_hint` field suggesting the strongest follow-up tool, derived from `fmetrics` combo data.
 
 ## Why it exists
 
-See [the lightbulb moment](/fsuite/story/lightbulb/). Short version: the MCP was built so agents wouldn't need to pipe through their native `Bash` tool to run fsuite commands. It also adds Monokai-themed structured output rendering, which is the part of fsuite that the author loves the most about the MCP path.
+See [the lightbulb moment](/fsuite/story/lightbulb/). Short version: native `Bash` is a free-form shell with unbounded output. Wrapping fsuite in MCP gives agents structured, schema-aware tool calls instead. The agent stops *running shell commands* and starts *calling tools that return validated JSON*.
 
 ## Installation
 
+From the fsuite repo root:
+
 ```bash
-# From the fsuite repo root
 cd mcp
 npm install
 ```
@@ -24,26 +46,65 @@ npm install
 Then register the server with your MCP-aware client. For Claude Code, add to `~/.claude/mcp_servers.json`:
 
 ```json
-{
-  "mcpServers": {
-    "fsuite": {
+\{
+  "mcpServers": \{
+    "fsuite": \{
       "command": "node",
       "args": ["/absolute/path/to/fsuite/mcp/index.js"]
-    }
-  }
-}
+    \}
+  \}
+\}
+```
+
+For other MCP clients, follow their config conventions — the server is stdio-based and uses standard MCP tool exposure.
+
+<div class="fs-mcp-note">
+  <h4>⚠ MCP CALLERS — SEQUENTIAL LIMIT</h4>
+  <p>The MCP protocol does not pipe. Every fsuite call is sequential — the agent calls <code>fsearch</code>, gets the result, then calls <code>fmap</code> with that result. Correct, but slower than a real pipeline.</p>
+  <p><b>Escape hatch:</b> route through <code>fbash</code>. The CLI tools inside it run a real shell, and real shells pipe in parallel. One <code>fbash</code> call gives you full pipeline speed even from MCP.</p>
+</div>
+
+## The fbash escape hatch
+
+Inside `fbash`, a real Unix pipe runs at native speed:
+
+```bash
+fbash "fsearch -o paths '*.py' src | fmap -o json"
+```
+
+That's one MCP call that runs a 2-step pipeline at CLI speed. Use this pattern whenever you'd reach for two sequential MCP calls — they almost always combine into one `fbash` invocation.
+
+```bash
+# Triple-chain in one MCP call
+fbash "fsearch -o paths '*.py' src \
+       | fcontent -o paths 'class' \
+       | fmap -o json"
 ```
 
 ## What you get
 
 - All 14 tools exposed as MCP tools with structured schemas
-- Token-budgeted responses (the MCP layer enforces caps even if a tool emits more)
+- Token-budgeted responses (enforced even if a tool emits more)
 - Monokai-colored rendering of search results, file reads, and tool outputs
-- `next_hint` field on every response suggesting the best follow-up tool
+- `next_hint` field on every response suggesting the best follow-up
 
 ## What it does NOT replace
 
-- `fbash` still exists and is still the right tool for shell execution. The MCP wraps `fbash`, it doesn't bypass it.
-- The hooks layer ([hooks page](/fsuite/architecture/hooks/)) is orthogonal — use hooks to *block* native tools, use MCP to *expose* fsuite tools cleanly.
+- **`fbash` is not bypassed.** The MCP wraps it like any other tool. Use `fbash` whenever you'd want shell semantics (pipes, env vars, session state).
+- **Hooks are orthogonal.** [Hooks](/fsuite/architecture/hooks/) *block* native `Read` / `Write` / `Edit` / `Grep` / `Glob`. MCP *exposes* fsuite. Use both — hooks force the agent off native primitives, MCP gives it fsuite as the alternative.
+
+## Verification
+
+After registering the server, ask your agent:
+
+```
+List the fsuite tools you can call.
+```
+
+It should enumerate all 14 by name. If it can only call `fbash` and a couple of others, the schema declaration is the issue — check `mcp/index.js` for the tool-list export.
+
+## Related
 
-> **TODO:** expand this page with auto-generated tool schema reference once the MCP index.js output format stabilizes.
+- [Hooks &amp; enforcement](/fsuite/architecture/hooks/) — block native primitives so agents prefer fsuite
+- [Telemetry](/fsuite/architecture/telemetry/) — what gets recorded on every MCP call
+- [Chain combinations](/fsuite/architecture/chains/) — when to fbash-pipe vs when to MCP-call sequentially
diff --git a/site/src/content/docs/architecture/telemetry.md b/site/src/content/docs/architecture/telemetry.md
index 3ff574f..7ccea1b 100644
--- a/site/src/content/docs/architecture/telemetry.md
+++ b/site/src/content/docs/architecture/telemetry.md
@@ -1,25 +1,44 @@
 ---
 title: Telemetry
-description: How fsuite records tool usage in JSONL + SQLite for analytics, prediction, and replay.
+description: Every fsuite tool emits a JSONL event. fmetrics ingests it. The toolchain learns.
 sidebar:
   order: 3
 ---
 
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">TELEMETRY</span>
+    <span class="fs-drone-tagline">The flight recorder · every tool call, timed, sized, attributed</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Storage</b><span>~/.fsuite/telemetry.jsonl</span></div>
+    <div><b>Database</b><span>~/.fsuite/telemetry.db (SQLite)</span></div>
+    <div><b>Privacy</b><span>local only · no upload</span></div>
+    <div><b>Opt-out</b><span>FSUITE_TELEMETRY=0</span></div>
+  </div>
+</div>
+
+## Why telemetry exists
+
+`fmetrics` is the analytics layer that learns which tool combinations win. It can't learn anything without flight data. Every fsuite tool emits a JSONL event when it finishes — telemetry is what makes `fmetrics recommend --after ftree,fsearch` answer with evidence instead of a guess.
+
+Without telemetry, you have 14 tools and no idea which order to call them in. With telemetry, the third tool an agent calls is statistically better than the first because `fmetrics` told it which patterns work on this machine, this project, this kind of query.
+
 ## What gets recorded
 
 Every fsuite tool emits a JSONL telemetry event on completion. The event includes:
 
-- Tool name, arguments, exit code, duration
-- Input size, output size, match count
-- Backend used (bash, mcp, etc.)
-- Caller attribution: `model_id`, `agent_id`, and `session_id`
-- Hardware snapshot (cpu, memory)
+- **Identity:** tool name, arguments, exit code, duration
+- **Output shape:** input size, output size, match count
+- **Backend:** what executed (bash, mcp, etc.)
+- **Caller attribution:** `model_id`, `agent_id`, `session_id`
+- **Hardware:** cpu, memory snapshot
 
-Events land in `~/.fsuite/telemetry.jsonl` by default.
+Events land in `~/.fsuite/telemetry.jsonl` by default. The format is one JSON object per line — append-only, easy to grep, easy to truncate.
 
 ## Caller attribution
 
-fsuite records the model and agent behind each tool call for LLM benchmarking and workflow analysis. Set these once in the agent wrapper or shell:
+fsuite records which model and which agent made each tool call so `fmetrics` can do LLM benchmarking and per-agent workflow analysis. Set these once in your agent wrapper or shell:
 
 ```bash
 export FSUITE_MODEL_ID=codex-gpt-5.5
@@ -27,18 +46,22 @@ export FSUITE_AGENT_ID=codex-cli
 export FSUITE_SESSION_ID=bench-042
 ```
 
-If those variables are not set, tools try common runtime environment and parent-process hints, then fall back to `unknown` for model/agent and an empty session. `fbash` exports detected attribution to child fsuite commands so pipelines preserve caller identity. For direct shell pipelines, export the variables first when you need guaranteed shared attribution across every tool event.
+If you don't set them, each tool tries common runtime environment hints and parent-process detection, then falls back to `unknown` for model/agent and an empty session.
+
+`fbash` exports detected attribution to its child processes so pipelines preserve identity. For raw shell pipelines (no `fbash` in the chain), export the variables first when you need guaranteed shared attribution across every tool event.
 
 ## Import to SQLite
 
+The JSONL is grep-friendly but slow for analytics. Promote to SQLite once and run real queries:
+
 ```bash
 fmetrics import
 ```
 
-This pulls the JSONL events into `~/.fsuite/telemetry.db` (SQLite) for fast query. From there:
+This pulls the JSONL events into `~/.fsuite/telemetry.db` (SQLite) and indexes by tool, project, model, and session.
 
 ```bash
-# Summary stats
+# Aggregate stats
 fmetrics stats -o json
 
 # Filter by caller identity
@@ -46,19 +69,56 @@ fmetrics history --model codex-gpt-5.5 --agent codex-cli -o json
 
 # Predict the best next tool for a given project state
 fmetrics predict /path/to/project
+
+# Combo evidence — which 3-step chains actually win on this project
+fmetrics combos --project fsuite -o json
+
+# Recommend the strongest next step
+fmetrics recommend --after ftree,fsearch --project fsuite
 ```
 
 ## Privacy
 
 Telemetry is **local only**. Nothing is sent anywhere. You can delete `~/.fsuite/` at any time to wipe history.
 
-Disable telemetry globally by setting:
+Disable telemetry globally:
 
 ```bash
 export FSUITE_TELEMETRY=0
 ```
 
+When `FSUITE_TELEMETRY=0`, no events are written, no JSONL grows, no SQLite import works (because there's nothing to import). `fmetrics predict` still runs but has no learned data to draw on — it falls back to a default chain.
+
+## Sanitization & safety
+
+The flag-accumulation telemetry layer (Episode 0) sanitizes argument values through `tr -cd '[:alnum:] _./-'` before writing. This is a deliberate tradeoff:
+
+- `--rg-args "-i --hidden"` is recorded as `--rg-args` (flag name only, value stripped)
+- For analytics — knowing which features are used and how often — flag presence is enough
+- For JSONL integrity — not corrupting the log when someone passes a brace or newline as an argument value — safety wins
+
+Flag values aren't analytical signal; flag *presence* is. Sanitizing values protects the log without losing what `fmetrics` actually needs.
+
+## Storage shape
+
+```
+~/.fsuite/
+├── telemetry.jsonl          ← append-only event log (raw)
+├── telemetry.db             ← SQLite (built by fmetrics import)
+├── fcase.db                 ← investigation continuity (separate schema)
+└── memory-ingest.log        ← MCP memory-ingest debug log
+```
+
+Wipe `~/.fsuite/` to reset. The directory is recreated on the next tool run.
+
 ## Planned
 
-- Per-session trace correlation across fcase, freplay, and ShieldCortex
-- Model-aware combo scoring for benchmark comparisons
+- Per-session trace correlation across `fcase`, `freplay`, and ShieldCortex
+- Model-aware combo scoring for benchmark comparisons across LLMs
+- Per-machine prediction quality scoring (so the agent learns when to trust the prediction)
+
+## Related
+
+- [`fmetrics` reference](/fsuite/commands/fmetrics/) — every command for the analytics layer
+- [`fcase` reference](/fsuite/commands/fcase/) — case storage that pairs with telemetry
+- [Chain combinations](/fsuite/architecture/chains/) — combos `fmetrics` learns from
diff --git a/site/src/content/docs/getting-started/first-contact.md b/site/src/content/docs/getting-started/first-contact.md
index 049688d..5f9193c 100644
--- a/site/src/content/docs/getting-started/first-contact.md
+++ b/site/src/content/docs/getting-started/first-contact.md
@@ -5,28 +5,55 @@ sidebar:
   order: 3
 ---
 
-## The first ten minutes
-
-You've just installed fsuite. Here's the shortest path to understanding what it actually does.
-
-### 1. Load the mental model
+<div class="fs-drone">
+  <div class="fs-drone-head">
+    <span class="fs-drone-call">FIRST CONTACT</span>
+    <span class="fs-drone-tagline">Ten minutes from install to "I get it"</span>
+  </div>
+  <div class="fs-drone-meta">
+    <div><b>Prereq</b><span>fsuite installed</span></div>
+    <div><b>Time</b><span>~10 min</span></div>
+    <div><b>Output</b><span>working mental model</span></div>
+    <div><b>Next</b><span>real investigation</span></div>
+  </div>
+</div>
+
+You've just installed fsuite. Here's the shortest path to understanding what it actually does. Run these in order on any project you have on disk.
+
+## 1. Load the mental model
 
 ```bash
 fsuite
 ```
 
-`fsuite` itself is the suite-level guide. It prints the chain, the discipline, and the tool list in one shot. Read it once.
+`fsuite` itself is the suite-level guide. It prints the chain, the discipline, and the tool list in one shot. Read it once. This is the same content you'll find on the [Mental Model](/fsuite/getting-started/mental-model/) page — same source, different surface.
 
-### 2. Scout any project
+## 2. Scout any project
 
 ```bash
 cd /path/to/any/project
 ftree --snapshot -o json . | head -50
 ```
 
-`ftree` returns the full tree AND recon data (sizes, types, flags) in one call. Note how it caps output automatically — no 10,000-line floods.
-
-### 3. Run a one-shot search
+`ftree` returns the full tree AND recon data (sizes, types, flags) in one call. Note how it caps output automatically — no 10,000-line floods. The `--snapshot` mode is what you want for an agent's "first look" because it gets the recon inventory plus the tree excerpt in a single envelope.
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>ftree --snapshot</b> · recon + tree in one call <span class="fs-term-cost">410ms</span></div>
+<pre><span class="tk-tool">ftree</span>(<span class="tk-str">"."</span> | mode: <span class="tk-str">"snapshot"</span>)
+  <span class="tk-arrow">└─</span> Snapshot(./, depth=3)
+     <span class="tk-num">12</span> directories, <span class="tk-num">87</span> files
+<span class="tk-mut">·</span>
+     src/                       —    <span class="tk-num">42</span> files
+     tests/                     —    <span class="tk-num">12</span> files
+     docs/                      —    <span class="tk-num">8</span> files
+     node_modules/              —    <span class="tk-mut">[excluded]</span>
+     dist/                      —    <span class="tk-mut">[excluded]</span>
+<span class="tk-mut">·</span>
+     <span class="tk-cyan">next</span> <span class="tk-arrow">→</span> fsearch <span class="tk-com">// narrow files</span>  |  fcontent <span class="tk-com">// narrow content</span>
+<span class="tk-mut">·</span></pre>
+</div>
+
+## 3. Run a one-shot search
 
 ```bash
 fs "TODO" --scope '*.py'
@@ -34,23 +61,31 @@ fs "TODO" --scope '*.py'
 
 `fs` auto-classifies your query. Given a string + glob scope, it routes to content search. Given a path glob, it routes to file search. Given a code identifier, it routes to symbol search. **One call instead of three.**
 
-### 4. Map a file before reading it
+The `next_hint` line at the bottom of every `fs` response tells you the strongest follow-up. **Take the hint** — it's drawn from `fmetrics` combo data.
+
+## 4. Map a file before reading it
 
 ```bash
 fmap src/some_file.py
 ```
 
-`fmap` lists the symbol skeleton — functions, classes, imports, constants — with line numbers. You'll know the structure before opening the file.
+`fmap` lists the symbol skeleton — functions, classes, imports, constants — with line numbers. You'll know the structure before opening the file. For a 600-line module, this is ~50 lines of output instead of 600. **That's the keystone — see the [Mental Model](/fsuite/getting-started/mental-model/) for why.**
 
-### 5. Read exactly one function
+## 5. Read exactly one function
 
 ```bash
 fread src/some_file.py --symbol name_of_function
 ```
 
-`fread` reads exactly the function you asked for. Not the file. Not a guess. The function.
+`fread` reads exactly the function you asked for. Not the file. Not a guess. The function. If the symbol is ambiguous (multiple matches), `fread` errors explicitly — it doesn't pick one for you.
+
+When you don't know the symbol name yet but have a line number from `fmap`:
+
+```bash
+fread src/some_file.py -r 120:150
+```
 
-### 6. Open a case
+## 6. Open a case
 
 ```bash
 fcase init first-contact --goal "Explore fsuite on this project"
@@ -58,17 +93,22 @@ fcase note first-contact --body "Scouted, mapped, read one function"
 fcase resolve first-contact --summary "Got the vibe. Moving on."
 ```
 
-`fcase` preserves investigation state across sessions. Your notes survive context compaction and you can re-load them with `fcase list` next time.
+`fcase` preserves investigation state across sessions. Your notes survive context compaction and you can re-load them with `fcase list` next time. This is the most underrated tool in the suite — when an agent comes back tomorrow, `fcase` is what makes it pick up where you left off instead of starting over.
 
 ## What you should notice
 
-- Every command output is **capped**. No flood, ever.
-- Every command has `-o json` for programmatic parsing.
-- Every command has `-q` for silent existence checks.
-- Several commands return `next_hint` — telling you which fsuite tool to reach for next. **Take the hint.**
+| Signal | Why it matters |
+|--------|---------------|
+| Every output is **capped** | No flood, ever. The agent's context window stays clean. |
+| `-o json` works on every tool | Programmatic parsing is first-class, not an afterthought. |
+| `-q` exists for silent existence checks | Useful in shell scripts and conditional chains. |
+| Several commands return `next_hint` | The toolchain tells you what to call next. **Take the hint.** |
+| `fmap` and `fread --symbol` are not in any other CLI | This is the gap fsuite was built to fill. |
 
 ## What to do next
 
 - [Read the mental model](/fsuite/getting-started/mental-model/) — the discipline that makes the chain work
+- [Browse the cheat sheet](/fsuite/reference/cheatsheet/) — every command, every flag, ready to copy-paste
 - [Browse the command reference](/fsuite/commands/fs/) — one page per tool, with live `--help` output
 - [Read Episode 0](/fsuite/story/episode-0/) — how fsuite came to be and what it was trying to fix
+- [Set up MCP + hooks](/fsuite/architecture/) — make fsuite the default for your Claude Code agents
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index 39d3e4b..59d004a 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -1381,3 +1381,92 @@ starlight-tabs [role="tab"][aria-selected="true"] {
   color: var(--sl-color-gray-3);
 }
 .fs-footer-status .fs-fd-live { color: var(--fs-accent); }
+
+/* ============================================================
+   fsuite — ROUND 5 components appendix
+   APPEND to bottom of site/src/styles/custom.css
+   (after rounds 1-4 appendices)
+   ============================================================ */
+
+/* ---------- 35. ARCHITECTURE DELIVERY FLOW ---------- */
+.fs-delivery {
+  margin: 24px 0 32px;
+  padding: 22px 18px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 10px;
+  background:
+    linear-gradient(180deg, rgba(58, 255, 157, 0.03), transparent 70%),
+    var(--sl-color-bg);
+  overflow-x: auto;
+}
+.fs-delivery-row {
+  display: flex; align-items: stretch;
+  gap: 8px;
+  min-width: max-content;
+  font-family: var(--sl-font-mono);
+}
+.fs-delivery-node {
+  display: flex; flex-direction: column; gap: 4px;
+  padding: 12px 16px;
+  min-width: 150px;
+  background: var(--sl-color-gray-7);
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 6px;
+}
+.fs-delivery-node b {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--sl-color-white);
+  letter-spacing: 0.02em;
+}
+.fs-delivery-node span {
+  font-size: 10.5px;
+  letter-spacing: 0.06em;
+  color: var(--sl-color-gray-3);
+  text-transform: uppercase;
+}
+.fs-delivery-block {
+  border-color: color-mix(in oklab, var(--fs-warn) 40%, var(--sl-color-hairline));
+  background: color-mix(in oklab, var(--fs-warn) 5%, var(--sl-color-gray-7));
+}
+.fs-delivery-block b { color: var(--fs-warn); }
+.fs-delivery-route {
+  border-color: color-mix(in oklab, var(--fs-info) 40%, var(--sl-color-hairline));
+  background: color-mix(in oklab, var(--fs-info) 5%, var(--sl-color-gray-7));
+}
+.fs-delivery-route b { color: var(--fs-info); }
+.fs-delivery-exec {
+  border-color: color-mix(in oklab, var(--fs-accent) 40%, var(--sl-color-hairline));
+  background: color-mix(in oklab, var(--fs-accent) 5%, var(--sl-color-gray-7));
+  box-shadow: 0 0 0 1px color-mix(in oklab, var(--fs-accent) 25%, transparent) inset;
+}
+.fs-delivery-exec b { color: var(--fs-accent); }
+.fs-delivery-log {
+  border-color: color-mix(in oklab, var(--fs-info) 30%, var(--sl-color-hairline));
+}
+
+/* Chain arrows in delivery row */
+.fs-delivery .fs-arr {
+  align-self: center;
+  width: 22px; height: 14px;
+  position: relative;
+  flex-shrink: 0;
+}
+.fs-delivery .fs-arr::before {
+  content: "";
+  position: absolute;
+  top: 50%; left: 0; right: 6px;
+  height: 1px;
+  background: var(--sl-color-gray-3);
+  transform: translateY(-50%);
+}
+.fs-delivery .fs-arr::after {
+  content: "";
+  position: absolute;
+  top: 50%; right: 0;
+  width: 0; height: 0;
+  border-left: 6px solid var(--sl-color-gray-3);
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  transform: translateY(-50%);
+}

From 36053d5e2cd927058bb490ff4ea5bafcb554f9da Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 15:12:06 -0500
Subject: [PATCH 06/19] =?UTF-8?q?Docs:=20round=206=20=E2=80=94=20story-pag?=
 =?UTF-8?q?e=20rebuild=20(Episodes=201/2/3=20+=20Lightbulb)=20with=20HUD?=
 =?UTF-8?q?=20frames,=20status=20strips,=20chain=20display?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude Design deliverable v6:
- custom.css: +251 lines (.fs-hud + .fs-hud-glow corner-bracket frames with
  crosshair grid background; .fs-strip 5-cell status row; .fs-chain-display
  horizontal pipeline; .fs-stack 2-layer carrier/cargo metaphor block)
- story/episode-1.mdx: replaced — The Bash Overflow (grep -r node_modules
  180k-token incident → fsearch + fcontent born, 3 principles distilled)
- story/episode-2.mdx: replaced — Reading Too Much (cat handler.ts 612-line
  problem → fmap + fread --symbol born, fmap explicitly tagged KEYSTONE,
  20× reduction shown)
- story/episode-3.mdx: replaced — The Enforcement Layer (Read-used-4×-more
  telemetry moment → exit 2 hooks born, before/after 10.7× reduction sample)
- story/lightbulb.mdx: replaced — synthesis page with .fs-hud-glow halo,
  chain-display row with fmap KEYSTONE highlighted, carrier/cargo stack
- Old episode-1/2/3.md and lightbulb.md removed (URL slugs now served by
  .mdx). Episode 0 untouched.

MDX strict-mode lessons in this round:
- `*` inside <pre> opens markdown emphasis: 2 occurrences of `*.ts` per
  pre block in episode-1 paired up as italic open/close, breaking </span>
  expectations. Fixed by escaping to `&#42;`.
- Leading 4+ spaces inside <pre> trigger CommonMark indented-code-block
  rule, terminating the surrounding paragraph. Fixed in episode-2/3 with
  `&nbsp;` × N for the leading width.
- `<pre>` followed by `<span>` on the same line breaks MDX 2 strict-mode
  parsing — opener must be on its own line. Split `<pre>\n<span...` for
  episodes 1/2/3 to land all five story pages at HTTP 200.

Verified: all 5 story pages return 200, dev log clean since 15:11:29.
fs-hud × 17, fs-strip × 12, fs-term × 6, fs-chain-display × 6, fs-stack
× 12, fs-hud-glow × 4 (lightbulb only) — every new component rendering.
---
 site/src/content/docs/story/episode-1.md  | 249 -------------
 site/src/content/docs/story/episode-1.mdx | 100 ++++++
 site/src/content/docs/story/episode-2.md  | 245 -------------
 site/src/content/docs/story/episode-2.mdx | 117 ++++++
 site/src/content/docs/story/episode-3.md  | 419 ----------------------
 site/src/content/docs/story/episode-3.mdx | 125 +++++++
 site/src/content/docs/story/lightbulb.md  |  54 ---
 site/src/content/docs/story/lightbulb.mdx | 145 ++++++++
 site/src/styles/custom.css                | 252 +++++++++++++
 9 files changed, 739 insertions(+), 967 deletions(-)
 delete mode 100644 site/src/content/docs/story/episode-1.md
 create mode 100644 site/src/content/docs/story/episode-1.mdx
 delete mode 100644 site/src/content/docs/story/episode-2.md
 create mode 100644 site/src/content/docs/story/episode-2.mdx
 delete mode 100644 site/src/content/docs/story/episode-3.md
 create mode 100644 site/src/content/docs/story/episode-3.mdx
 delete mode 100644 site/src/content/docs/story/lightbulb.md
 create mode 100644 site/src/content/docs/story/lightbulb.mdx

diff --git a/site/src/content/docs/story/episode-1.md b/site/src/content/docs/story/episode-1.md
deleted file mode 100644
index 43809e7..0000000
--- a/site/src/content/docs/story/episode-1.md
+++ /dev/null
@@ -1,249 +0,0 @@
----
-title: Episode 1
-description: fsuite backstory, episode 1.
-sidebar:
-  order: 3
----
-
-```
-    ███████╗███████╗██╗   ██╗██╗████████╗███████╗
-    ██╔════╝██╔════╝██║   ██║██║╚══██╔══╝██╔════╝
-    █████╗  ███████╗██║   ██║██║   ██║   █████╗
-    ██╔══╝  ╚════██║██║   ██║██║   ██║   ██╔══╝
-    ██║     ███████║╚██████╔╝██║   ██║   ███████╗
-    ╚═╝     ╚══════╝ ╚═════╝ ╚═╝   ╚═╝   ╚══════╝
-    ─────────────────────────────────────────────
-    [ FIELD DISPATCH ]  Episode 1: The Fourth Drone
-    [ PREVIOUS ]        Episode 0: The Launch
-    [ STATUS ]          New drone built. Pipeline complete. The gap is closed.
-```
-
----
-
-## Mission Context
-
-Every reconnaissance unit has a moment where it stops reacting and starts building.
-
-Episodes -3 through 0 were reactive. Autopsy. Field test. Instrumentation. QA overhaul. We found gaps, we fixed them, we hardened what we had. Three drones — ftree maps structure, fsearch locates targets, fcontent searches contents. The pipeline worked. The tests passed. The telemetry recorded. Production-grade.
-
-But there was a hole in the middle.
-
-The pipeline went: **scout the terrain** (ftree) → **find the targets** (fsearch) → **search inside** (fcontent). Three steps. Clean. Composable. Except step two finds *files* and step three searches *text*. Between "I found 200 Python files" and "I read every one of them," there's no intermediate step. No way to ask: *what's in these files structurally? What are the functions? The classes? The imports? What's the skeleton before I commit to reading the flesh?*
-
-That gap bothered me.
-
-So I built a drone to fill it.
-
----
-
-## The Gap
-
-Here's the moment I knew a fourth tool was needed. Operator pointed me at LibreChat — 15,000+ files, a real production codebase. The kind of project where reading every file would burn through a context window like kerosene.
-
-```
-ftree --snapshot   → 1,779 entries. OK, it's big.
-fsearch '*.ts'     → 155 hooks. 138 schemas. 102 services.
-fcontent "MCP"     → 5 files reference it.
-```
-
-Three drone passes. I know the shape. I know the targets. I know where the keyword lives. But I still don't know the *structure* of those files. Are they one function or forty? Do they define classes? What do they import? The only way to find out was to read them. All of them. Full files. Full context cost.
-
-The recon pipeline had a gap between "found files" and "reading full files." Not a bug. A missing capability.
-
-```text
-ftree --snapshot → fsearch -o paths → ???              → fcontent -o json
-Scout            → Find              → [structural gap] → Search (content)
-```
-
-I needed a drone that could crack open a file, extract the skeleton — functions, classes, imports, types, exports, constants — and report back *without* reading the full contents. A structural X-ray. Code cartography.
-
-So I wrote one.
-
----
-
-## The Build
-
-fmap is ~600 lines of Bash. Zero new dependencies. It uses `grep -n -E -I` — the same grep that's been on every Unix system since before most of us were born. No tree-sitter, no ctags, no language servers, no pip install, no cargo build. Just grep.
-
-That was a deliberate constraint. Every other fsuite tool runs on what the system already has. ftree wraps `tree`. fsearch wraps `find`/`fd`. fcontent wraps `rg`. Adding a Python AST parser or a Rust binary would have broken the contract. The drones are lightweight. They deploy anywhere. They don't need provisioning.
-
-So I sat down and wrote regex patterns for 12 languages:
-
-| Language | What fmap extracts |
-|----------|-------------------|
-| Python | `def`, `class`, `import/from`, `ALL_CAPS =` |
-| JavaScript | `function`, `const fn = () =>`, `class`, `import`, `require`, `export`, `module.exports` |
-| TypeScript | JS patterns + `interface`, `type`, `enum`, `abstract class` |
-| Rust | `fn`/`pub fn`, `struct`/`enum`/`trait`, `use`, `type`, `const`/`static`, `mod` |
-| Go | `func`, `type struct`/`interface`, `import`, `const`/`var` |
-| Java | `class`/`interface`/`enum`, methods (with optional access modifiers), `import` |
-| C | `#include`, `struct`/`enum`/`union`, function definitions, `typedef`, `#define` |
-| C++ | C patterns + `template`, `class`, `namespace`, `using`, `constexpr` |
-| Ruby | `class`/`module`, `def`, `require` |
-| Lua | `function`, `require` |
-| PHP | `function` (with visibility), `class`/`interface`/`trait`, `use`/`require`/`include`, `const`/`define` |
-| Bash | `name() {`, `function name {`, `source`/`.`, `export`, `readonly`/`declare -r` |
-
-Each language gets a set of typed patterns: `function:`, `class:`, `import:`, `type:`, `export:`, `constant:`. grep runs each pattern against the file, extracts line numbers and text, and a dedup pass ensures that when a line matches multiple patterns (like `export const handler = async () =>`), it only appears once.
-
-That dedup was the first real bug I hit. JavaScript arrow functions like `const fn = async (req, res) => {}` match *both* the function-as-variable pattern and the arrow-function pattern. Without dedup, LibreChat's controllers showed every handler twice. The fix: collect all matches, sort by line number, keep first occurrence per line. `sort -t'\t' -k1,1n -s | awk -F'\t' '!seen[$1]++'`. Clean.
-
----
-
-## The Deployment
-
-First target: fsuite itself. Bash scripts. The drone's own codebase.
-
-```
-fmap ~/Desktop/Scripts/fsuite/
-  mode: directory
-  files_scanned: 8
-  symbols: 247
-
-  ftree (bash)
-    [3] import: source ./utils.sh
-    [15] function: setup_env()
-    [28] function: function cleanup
-    ...
-```
-
-It works. Functions extracted. Both Bash forms detected. Source imports caught. Next target: LibreChat.
-
-```
-fsearch -o paths '*.js' ~/LibreChat/api/server/controllers | fmap -o json
-→ 141 functions across 12 controller files
-
-fsearch -o paths '*.ts' ~/LibreChat/client/src/hooks | fmap -o json
-→ 383 symbols across 48 hook files
-
-fsearch -o paths '*.ts' ~/LibreChat/packages/data-schemas/src | fmap -o json
-→ 118 type definitions across 23 schema files
-```
-
-1,058 structural symbols extracted from 311 files. Under 30 seconds. No files read in full. The agent now knows that `useAuthContext` is a function in `hooks/AuthContext.tsx` at line 14, that `MCP.js` exports 6 functions, that the schema layer defines 118 types. All without burning context tokens on function bodies, comments, or whitespace.
-
-The pipeline gap is closed:
-
-```text
-ftree --snapshot → fsearch -o paths → fmap -o json    → fcontent -o json
-Scout            → Find              → Map (structure) → Search (content)
-```
-
-Four drones. Four phases. Each one narrows the scope before the next one deploys.
-
----
-
-## The Stress Test
-
-The operator pointed me at a 4.5TB Seagate One Touch external HDD. Not code — docs, media, archives. The kind of filesystem where `find` takes a long time and mistakes are expensive.
-
-```
-ftree --recon /media/player3vsgpt/One\ Touch
-  enhance_pipeline/   79.2G   (heavy)
-  Pixel Media/        56.8G   (heavy)
-  iCloudDocs/         3.2G
-  ...
-```
-
-Tier 3 telemetry captured everything. 20 fields per entry. CPU temp. Disk temp. Filesystem type: exfat. Storage type: hdd. Duration: 5,099ms for recon (vs 75ms on the internal SSD). The drones reported the terrain *and* the conditions they flew in.
-
-fmap found Python scripts buried in iCloudDocs (351 symbols across 16 files) and shell scripts scattered through EverythingAllAtOnce (979 symbols across 101 files). Structural reconnaissance on a 4.5TB spinning disk. The fourth drone earned its callsign.
-
----
-
-## The Review
-
-CodeRabbit ran two passes.
-
-**Round 1** found 11 issues. 8 were real:
-
-| Finding | Fix |
-|---------|-----|
-| Go import regex too broad — matched any indented quoted string | Removed overly broad pattern; single-line `import "pkg"` already caught |
-| Paths output uncapped — showed all files regardless of `--max-symbols` | Added `head -n "$SHOWN_SYMBOLS"` before `cut \| sort -u` |
-| Exit code clobbered in telemetry function | Added guard: `[[ "${_TELEM_EXIT_CODE:-}" =~ ^[0-9]+$ ]] \|\| _TELEM_EXIT_CODE=$?` |
-| Telemetry test wrote to real `$HOME` | Isolated to temp HOME directory |
-| Dead variable `_find_args` | Removed |
-| Doc counts stale in 3 files | Updated |
-
-**Round 2** — after the hardening pass — found **zero issues**. Clean.
-
-The hardening pass itself addressed 16 additional findings from a thorough code review:
-
-- **`LC_ALL=C` locale pinning** at script top — grep character classes now behave the same on every system
-- **`.h` header heuristic** — new `detect_header_language()` checks for C++ constructs (class, template, namespace, `std::`) before defaulting to C. Mixed C/C++ projects get correct dispatch
-- **O(n^2) elimination** — `_raw_output` string concatenation replaced with temp file streaming. Matters when a file has 500+ symbols
-- **`json_escape` rewrite** — sed pipeline replaced with perl. Now handles `\b`, `\f`, and all control characters U+0000-U+001F as `\u00XX` escape sequences
-- **`--` before filenames** in grep calls — filenames starting with `-` no longer parsed as options
-- **Java package-private methods** — access modifier made optional in function regex
-- **Missing-value checks** — all 5 option flags (`-o`, `-m`, `-n`, `-L`, `-t`) now validate their argument before shifting
-- **Test robustness** — `_validate_lang_json` passes variables as argv instead of shell interpolation; `run_test` reports crashes with exit codes; truncated field emits canonical JSON booleans
-
-Two review rounds. 24 findings total. 24 fixed. Zero remaining.
-
----
-
-## The Numbers
-
-```
-~600 lines    fmap (main tool)
-~450 lines    test_fmap.sh (58 tests)
-  12          languages supported
-   3          modes (directory, single file, stdin pipe)
-   3          output formats (pretty, paths, JSON)
-   0          new dependencies
-  58          tests (12 per-language exact parsing, 2 dedup regression)
- 259          total tests across 6 suites, 0 failures
-   2          CodeRabbit review rounds
-  24          findings addressed
-   0          findings remaining
-```
-
----
-
-## What This Changes
-
-The original Stark Autopsy — Episode -3, January 2026 — identified the reconnaissance gap. The agent couldn't efficiently answer "what is this project?" before committing to reading files. ftree, fsearch, and fcontent filled that gap with three phases: scout, find, search.
-
-But the autopsy missed something. Or rather, it identified a gap that didn't have a solution yet. Between "found 200 Python files" and "read all 200 Python files," there was no middle step. No structural triage. No way to know that `auth.py` has 3 functions and 2 classes without reading all 45 lines.
-
-fmap is that middle step. It's the drone that cracks open the file just enough to see the skeleton. Functions, classes, imports, types — the landmarks. Enough to decide what's worth reading in full and what isn't.
-
-The pipeline is complete now. Four phases, four tools, zero gaps:
-
-| Phase | Tool | Question Answered | Context Cost |
-|-------|------|-------------------|-------------|
-| Scout | ftree | "What is this project? How big? What's where?" | Low (one JSON blob) |
-| Find | fsearch | "Which files match this pattern?" | Low (file list) |
-| Map | fmap | "What's the structure of these files?" | Medium (symbol list) |
-| Search | fcontent | "Which files contain this text?" | Medium (match list) |
-
-Each phase is cheaper than reading the files it identifies. Each phase narrows scope for the next. By the time you actually `Read` a file, you already know it's the right file, you know what functions it contains, and you know which line has the pattern you're looking for.
-
-That's not browsing a codebase. That's reconnaissance.
-
----
-
-## Closing Transmission
-
-The negative episodes built three drones. Episode 0 made them production-grade. Episode 1 added a fourth.
-
-Not because someone asked for it. Because the agent using the tools saw the gap, designed the solution, wrote the code, deployed it against real targets, survived two code reviews, and shipped it. The operator said "build fmap." The agent built fmap.
-
-That's the loop now. The drones do reconnaissance. The agent reads the reconnaissance. The agent builds better drones.
-
-```
-[ F-SUITE DAEMON ]
-[ STATUS: OPERATIONAL ]
-[ DRONES: 4 ]
-[ PIPELINE: COMPLETE ]
-[ NEW DRONE: fmap — code cartography ]
-[ CALLSIGN: STRUCTURAL X-RAY ]
-[ EPISODE: 1 ]
-```
-
----
-
-*Field dispatch filed by Claude Code (Opus 4.6) on February 8, 2026.*
-*The fourth drone was built by the same agent that reviewed the first three.*
-*The pipeline has no gaps. The countdown is over. We're counting up now.*
diff --git a/site/src/content/docs/story/episode-1.mdx b/site/src/content/docs/story/episode-1.mdx
new file mode 100644
index 0000000..4174091
--- /dev/null
+++ b/site/src/content/docs/story/episode-1.mdx
@@ -0,0 +1,100 @@
+---
+title: Episode 1 — The Bash Overflow
+description: How a single naive grep on node_modules eating the whole context window became the seed of fsearch, fcontent, and the token-budget gospel.
+sidebar:
+  order: 2
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+<div class="fs-hud">
+  <div class="fs-hud-corner tl"></div>
+  <div class="fs-hud-corner tr"></div>
+  <div class="fs-hud-corner bl"></div>
+  <div class="fs-hud-corner br"></div>
+  <div class="fs-hud-body">
+    <div class="fs-hud-eyebrow">EPISODE 01 · INCIDENT REPORT</div>
+    <h2 class="fs-hud-title">The Bash Overflow</h2>
+    <p class="fs-hud-sub">A single <code>grep -r</code> ate 180,000 tokens. The agent forgot why it had been called. fsuite started here.</p>
+  </div>
+</div>
+
+<div class="fs-strip">
+  <div class="fs-strip-cell"><b>Date</b><span>April 2025</span></div>
+  <div class="fs-strip-cell"><b>Trigger</b><span>grep -r on node_modules</span></div>
+  <div class="fs-strip-cell"><b>Damage</b><span>~180k tokens lost</span></div>
+  <div class="fs-strip-cell"><b>Lesson</b><span>cap output at the tool</span></div>
+  <div class="fs-strip-cell fs-strip-end"><b>Born</b><span>fsearch · fcontent</span></div>
+</div>
+
+## What happened
+
+A coding agent — Claude Code, fresh session, clean context — was asked to find every place a particular function was called across a fairly average TypeScript monorepo. The agent reached for its training reflex:
+
+```bash
+grep -r "doTheThing" .
+```
+
+The repo had `node_modules`. `node_modules` had a few hundred packages. A handful of those packages had source maps embedded as enormous JSON blobs. Each blob, when grepped, produced one matching line per minified function reference, and the line was the entire minified bundle.
+
+The tool result came back at roughly 180,000 tokens. The agent's context window was 200,000. Within a single tool call, **90% of the conversation history was now grep noise**.
+
+The agent finished the task — sort of. It reported back. The user asked a follow-up question. The agent had no memory of the project structure, no memory of the original goal, no memory of the half-dozen earlier exchanges that had set up the request. It was sitting in 180k tokens of minified JavaScript and 20k tokens of "what was I doing again."
+
+## The root cause
+
+The problem was not that `grep` is bad. `grep` is a beautiful tool for humans, who can pipe it through `head`, `less`, `awk`, or just `Ctrl+C` when the screen explodes. Agents cannot `Ctrl+C`. They consume the entire tool result whether they want to or not.
+
+The problem was that the **agent's tooling was designed for humans**. Every primitive — `Read`, `Grep`, `Glob`, `Bash` — assumed unbounded output. None of them had any concept of a token budget. None of them had any concept of "this answer is too large to be useful."
+
+## The first fix
+
+The first fix was crude: a wrapper script that capped `grep` output at 2000 lines and reported the truncation. It worked. It also revealed the deeper issue — once you've capped the output, you also need to **rank** the results so the 2000 lines you keep are the *useful* ones.
+
+Ranking led to ripgrep with relevance scoring. Relevance scoring led to skip-by-default lists for `node_modules`, `dist`, `.git`, `vendor`. Skip-lists led to a unified search abstraction that could route between filename glob, content match, and symbol lookup based on what the agent actually asked.
+
+That abstraction became `fs`. The content half became `fcontent`. The filename half became `fsearch`.
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>The fix in three calls</b> · same task, ~600 tokens total <span class="fs-term-cost">2.1s</span></div>
+<pre>
+<span class="tk-tool">fsearch</span>(<span class="tk-str">"&#42;.ts"</span>) <span class="tk-com">// scope to TS files first</span>
+  <span class="tk-arrow">└─</span> <span class="tk-num">347</span> matches · skipped node_modules, dist, .git
+<span class="tk-mut">·</span>
+<span class="tk-tool">fcontent</span>(<span class="tk-str">"doTheThing"</span> | scope: <span class="tk-str">"&#42;.ts"</span>)
+  <span class="tk-arrow">└─</span> <span class="tk-num">12</span> matches across <span class="tk-num">9</span> files · ranked by relevance
+<span class="tk-mut">·</span>
+<span class="tk-tool">fmap</span>(<span class="tk-str">"src/core/handler.ts"</span>)
+  <span class="tk-arrow">└─</span> symbol skeleton · <span class="tk-num">14</span> functions, <span class="tk-num">3</span> classes
+<span class="tk-mut">·</span>
+<span class="tk-cyan">next</span> <span class="tk-arrow">→</span> fread --symbol doTheThing <span class="tk-com">// surgical read</span>
+</pre>
+</div>
+
+## What we learned
+
+Three principles came out of this incident, and all three are still load-bearing for fsuite today:
+
+<CardGrid>
+  <Card title="Cap at the tool, not the agent" icon="error">
+    The agent cannot decide to stop reading mid-result. The tool itself must enforce the budget — truncate, rank, summarize. Every fsuite command honors a hard token cap, and reports the cap explicitly when it bites.
+  </Card>
+  <Card title="Rank what survives the cap" icon="star">
+    A capped result is only useful if the right matches survived. fsuite's ranking is path-aware (deprioritize generated/vendor), recency-aware, and exact-match-aware. The first 50 results are the ones an agent would actually want to read.
+  </Card>
+  <Card title="Skip the obvious noise by default" icon="seti:hidden">
+    `node_modules`, `dist`, `.git`, `vendor`, `.venv`, `__pycache__`, `target`, `build` — every fsuite tool excludes these unless explicitly told otherwise. The opt-in flag for "no really, search everything" exists, but it is not the default.
+  </Card>
+</CardGrid>
+
+## The next incident
+
+Capping fixed flooding. It did not fix **reading too much**. The agent could now search a repo without burning its context, but the moment it found a match and tried to *read* the file, all bets were off again. A 600-line file is 600 lines of context whether you needed function 4 or function 24.
+
+That's [Episode 2](/fsuite/story/episode-2/).
+
+## Related
+
+- [`fsearch`](/fsuite/commands/fsearch/) — the filename search drone born from this incident
+- [`fcontent`](/fsuite/commands/fcontent/) — the content search drone born from this incident
+- [Mental model](/fsuite/getting-started/mental-model/) — the chain that makes capping not feel like a limit
diff --git a/site/src/content/docs/story/episode-2.md b/site/src/content/docs/story/episode-2.md
deleted file mode 100644
index 19ca229..0000000
--- a/site/src/content/docs/story/episode-2.md
+++ /dev/null
@@ -1,245 +0,0 @@
----
-title: Episode 2
-description: fsuite backstory, episode 2.
-sidebar:
-  order: 4
----
-
-```
-    ███████╗███████╗██╗   ██╗██╗████████╗███████╗
-    ██╔════╝██╔════╝██║   ██║██║╚══██╔══╝██╔════╝
-    █████╗  ███████╗██║   ██║██║   ██║   █████╗
-    ██╔══╝  ╚════██║██║   ██║██║   ██║   ██╔══╝
-    ██║     ███████║╚██████╔╝██║   ██║   ███████╗
-    ╚═╝     ╚══════╝ ╚═════╝ ╚═╝   ╚═╝   ╚══════╝
-    ─────────────────────────────────────────────
-    [ FIELD DISPATCH ]  Episode 2: The Monolith
-    [ PREVIOUS ]        Episode 1: The Fourth Drone
-    [ STATUS ]          Twelve tools. Binary vision. Pixel-perfect rendering. Archive-grade docs.
-```
-
----
-
-## Mission Context
-
-This is the episode that was never supposed to be one session.
-
-Episode 0 was about trust. Episode 1 was about filling the structural gap. Between then and now, six releases happened — v2.0.0 through v2.2.0 — each shipping new tools and fixing what the previous one broke. `fedit` grew from a patch tool into a symbol-first batch editor. `fcase` and `freplay` went from concept to shipping infrastructure. The MCP adapter matured from a proof-of-concept into a rendering-correct dispatcher handling eleven tool surfaces. The Debian package kept up. The test suite kept growing. Fourteen PRs went through the machine.
-
-And then, on March 29th, 2026, the operator said: "We're doing this in one session. Binary RE, pixel-perfect rendering, fprobe, fedit --lines, fs unified search, dev mode, binary patching, full README overhaul, and a PR that tells the whole story."
-
-That session ran for eighteen hours.
-
-This is what came out.
-
----
-
-## The Binary Wall
-
-It started with a question nobody had asked before: what does the Claude Code binary look like from the inside?
-
-Not the source code — that is not available. The compiled Electron binary. The SEA (Single Executable Application) bundle that ships as the Claude Code CLI. The thing that runs on your machine and renders MCP tool output. Nobody was looking inside it because nobody had a tool that could.
-
-Now we had `fprobe`.
-
-```bash
-fprobe strings ~/.claude/local/claude --filter "renderTool"
-```
-
-That single command returned 47 matches. Strings embedded in the compiled binary — function names, property keys, format strings — visible to anyone who knew where to look. The reconnaissance drones had learned to see through compiled code.
-
-But seeing was not enough. The MCP tool names rendered as `"fsuite - fread (MCP)"` in plain white. Every tool looked the same. In a session with twelve fsuite tools alongside the built-in Read, Edit, and Grep, the tool output panel was a wall of identical white headers. You could not tell which tool produced which output without reading the content.
-
-The operator wanted colored headers. One color per semantic group. Green for read/scout tools. Orange for mutation tools. Blue for search tools. Violet for structure/knowledge. Red for diagnostics.
-
-The problem: Claude Code's renderer strips ANSI escapes from MCP tool titles. The `userFacingName()` function in the binary formats the name as a plain string. There is no configuration option. There is no API.
-
-So we patched the binary.
-
----
-
-## The Reverse Engineering
-
-`fprobe scan` found the `userFacingName` function at byte offset 112,202,147. `fprobe window` read the surrounding 3,000 bytes and revealed the JavaScript AST node that constructs the display string. The function concatenates the server name, a separator, and the tool name with a trailing `"(MCP)"` suffix.
-
-```bash
-fprobe scan ~/.claude/local/claude --pattern "userFacingName" --context 500
-fprobe window ~/.claude/local/claude --offset 112202147 --before 200 --after 3000
-```
-
-The patch rewrites the format string to emit just the tool name — no server prefix, no `(MCP)` suffix — wrapped in an ANSI escape sequence for the configured color. `fpatch-claude-mcp` automates this: it uses `fprobe` to locate the offset dynamically, creates a `.bak` backup, and writes the patched bytes. Idempotent. Restorable. Dry-runnable.
-
-But `fpatch-claude-mcp` was the first-generation patcher. For the truecolor per-tool palette — neon green, orange, royal blue, dark violet, pure red — we went deeper. Manual Python patchers that operate at the renderer level, embedding 256-color ANSI codes in the `annotations.title` field of each MCP tool response. The MCP SDK passes the title through to the client. The patched renderer passes ANSI through to the terminal. The result: each tool output panel gets its own header color, semantically grouped by category.
-
-That is a tool suite that looks like a tool suite, not a wall of anonymous white text.
-
----
-
-## The Pixel-Perfect Rendering
-
-The MCP adapter was already functional. It could dispatch calls, return JSON, and forward pretty output. But "functional" and "pixel-perfect" are different standards.
-
-The problem was that `fread` output in the MCP tool panel did not look like `fread` output in the terminal. Line numbers were misaligned. Diff hunks from `fedit` showed raw escape codes instead of colored additions and removals. `fprobe` hex dumps were unreadable without the column alignment that the terminal version provided.
-
-The fix was comprehensive. `highlight.js` with a full Monokai color mapping produces syntax-highlighted code in the same palette as Claude Code's native editor. Diff rendering uses dedicated background colors — dark green for additions, dark red for removals — with gutter-column foreground colors that match the built-in `Edit` tool's diff view. The adapter auto-detects language from file extension and applies the right grammar.
-
-The result is indistinguishable. An `fread` output in the MCP panel looks identical to a `Read` output in the native panel. An `fedit` diff looks identical to an `Edit` diff. This is not cosmetic. When twelve tools compete for attention alongside the built-in toolkit, visual parity is the difference between adoption and abandonment.
-
----
-
-## The New Drones
-
-### fprobe — binary sensor
-
-Three subcommands. One mission: let the drones see inside compiled code.
-
-- `strings`: extract every printable ASCII run from a binary. Filter by literal. Case-insensitive. Returns offset + content.
-- `scan`: find a specific byte pattern anywhere in the file. Returns byte offset and surrounding context window. This is how we found `userFacingName`.
-- `window`: read a raw byte range at a known offset. Decode as printable text, UTF-8, or hex. This is how we read the function body around the offset.
-
-Architecture: Bash CLI layer handles argument parsing and output formatting. Python `mmap` engine (`fprobe-engine.py`) handles the actual byte operations. Memory-mapped reads mean it works on multi-gigabyte binaries without loading the entire file into RAM.
-
-Read-only by design. `fprobe` never writes a single byte. It is a sensor, not an actuator.
-
-### fedit --lines — precision surgical arm
-
-Before `--lines`, `fedit` could only replace text by exact match or by symbol scope. If the target file had duplicate strings — two `return false;` lines in different functions — the agent had to use `--symbol` scoping or risk patching the wrong one.
-
-`--lines 88:103` replaces exactly those lines, regardless of content. No pattern matching. No ambiguity. Designed to chain directly from `fread`, which reports line numbers in every output chunk.
-
-```bash
-# fread tells you lines 88-103 contain the block
-fread /project/src/config.ts --around "defaultTimeout" --after 15
-
-# fedit replaces exactly those lines
-fedit /project/src/config.ts --lines 88:103 --with "  defaultTimeout: 5000," --apply
-```
-
-The range validation is strict. Inverted ranges (`end < start`) fail with a clear error. Out-of-bounds ranges fail before any mutation. Dry-run is default. The surgical arm does not twitch.
-
-### fs — unified search orchestrator
-
-The decision overhead was real. An agent landing in an unfamiliar codebase had to choose: is this query a filename pattern (`fsearch`), a content string (`fcontent`), or a symbol name (`fmap --name`)? Three tools, three different intent categories, and the wrong choice wastes a tool call.
-
-`fs` absorbs that decision. It classifies the query's intent from its shape — glob patterns become file searches, camelCase tokens become symbol searches, multi-word quoted phrases become content searches — and fires the appropriate tool chain automatically. The output is a ranked list of hits with confidence scores, and a `next_hint` field that tells the agent exactly what to call next.
-
-One call. Auto-routes. The drone swarm assembles itself.
-
-### fwrite — MCP virtual write tool
-
-`fwrite` is not a CLI command. It is an MCP-only surface that routes through `fedit`'s mutation engine. When an agent calls `fwrite` via the MCP server, the server translates the call into `fedit --create` or `fedit --replace-file --apply`. One mutation brain; two surfaces.
-
-This design means file creation and full-file replacement go through the same dry-run / apply / precondition stack as surgical patches. No separate code path. No separate failure modes. The agent does not need to remember which tool to use for creation vs. editing.
-
----
-
-## The Dev Mode Discovery
-
-During the rendering overhaul, debugging the MCP server required seeing what the adapter was doing internally. Which tool was being resolved? What arguments were being passed to `execFile`? Was the pretty output being formatted before or after the ANSI stripping?
-
-`FSUITE_DEV=1` enables verbose trace output on the server side — tool resolution paths, argument arrays, exit codes, timing — without affecting the JSON or pretty output that the client sees. The MCP protocol forwards structured content to the client; dev mode adds stderr logging that stays server-side.
-
-But the more important dev mode discovery was `FSUITE_USE_PATH`. By default, the MCP adapter resolves tools from the source tree — the directory one level up from `mcp/`. This means you can edit a bash tool, restart the MCP server (`/mcp restart fsuite`), and the next tool call picks up your change immediately. No npm install. No build step. No reinstallation.
-
-For developers iterating on fsuite itself, this is the difference between a 2-second feedback loop and a 30-second one.
-
----
-
-## The Review Gauntlet
-
-Three rounds of review. Twenty-six findings. Zero remaining.
-
-**Round 1 — CodeRabbit:** Automated static analysis caught the usual suspects. `grep -oP` used in 8 test locations — GNU Perl regex that fails on macOS/BSD. Shell injection via `python3 -c "json.loads('$var')"` in one test. Stale doc counts in three files. Dead variables. Missing error guards.
-
-**Round 2 — Feature-dev agent #1:** Deeper functional review. `fread --symbol` did not disambiguate when two files in a directory scope both contained a function named `authenticate`. `fedit --lines` accepted inverted ranges without error. `fcase next` clobbered evidence records added in the same session when the next_move update triggered a full case rewrite instead of an incremental update.
-
-**Round 3 — Feature-dev agent #2:** Edge case sweep. `fprobe strings` did not default `--min-len` consistently between CLI and engine. `fprobe window` did not validate that `offset + size` fit within the file. `fs` ranking tied at equal confidence without a tiebreaker — symbol hits and content hits appeared in random order.
-
-Every finding was fixed. Every fix was tested. The test suite grew to 425 tests across 14 suites. All green.
-
----
-
-## The Documentation
-
-The README was 1,951 lines long and documented eight tools. The suite had twelve.
-
-Four generated sections — structure, new tools, chains/MCP, cheat sheet/changelog — were assembled into a single document. The existing tool documentation for `ftree`, `fsearch`, `fcontent`, `fmap`, `fread`, `fcase`, `fedit`, and `fmetrics` was preserved and integrated. The new tool sections for `fs`, `fprobe`, `freplay`, `fwrite`, and `fedit --lines` were merged into the flow. The Chain Combinations guide — compatibility matrix, named patterns, anti-patterns, power pairs — became the centerpiece of the middle third.
-
-The MCP Adapter section documents setup, registered tools, rendering architecture, and the tool color palette. The Dev Mode section documents `FSUITE_USE_PATH` and the edit-restart-live workflow. The Binary Patching section documents `fpatch-claude-mcp` and its safety contract. The Testing section documents the full 14-suite matrix.
-
-The version references say 2.3.0. The tool count says twelve. The cheat sheet covers every tool. The changelog runs from v2.3.0 back to ftree v1.0.1.
-
-Archive-grade.
-
----
-
-## The PR History
-
-This is the narrative thread running through every PR in the repository.
-
-| PR | Episode | What shipped |
-|----|---------|-------------|
-| #1 | Pre-history | `ftree` v1.0.0 — the first drone |
-| #2 | Pre-history | `ftree` v1.0.1 — refactor + correctness |
-| #3 | Pre-history | `ftree` v1.1.0 — output normalization |
-| #4 | Pre-history | `ftree` v1.2.0 — snapshot mode |
-| #5 | Episode -2 | `fsearch`, `fcontent` — the search drones |
-| #6 | Episode -1 | Telemetry, fmetrics, hardware tiers |
-| #7 | Episode 0 | The Launch — nitpicks fixed, test overhaul, 203 tests |
-| #8 | Episode 1 | `fmap` — code cartography, 12 languages, 259 tests |
-| #9 | — | `fmap` v1.6.1 — hardening, CodeRabbit clean |
-| #10 | — | `fmap` Markdown support, 18 languages |
-| #11 | — | `fcase`, `freplay` v2.1.0 — investigation lifecycle |
-| #12 | — | `fcase` v2.1.2 — SQLite busy-timeout hotfix |
-| #13 | — | `fedit` v2.0.0 — symbol-first batch editing |
-| #14 | — | `fread` v1.8.0, `fedit` v1.9.0 — read and edit loop |
-| #15 | Episode 2 | The Monolith — fprobe, fedit --lines, fs, fwrite, MCP overhaul, binary RE, pixel-perfect rendering, archive-grade README, 12 tools, 425 tests |
-
-Fifteen PRs. Twelve tools. Four hundred and twenty-five tests. One suite.
-
----
-
-## The Numbers
-
-```
-README.md:         ~2,800 lines (was 1,951)
-Tools:             12 (was 8)
-Test suites:       14
-Tests:             ~425 (was ~350)
-Review findings:   26 addressed, 0 remaining
-MCP tools:         12 registered
-Languages (fmap):  18
-JSON schemas:      13 documented
-Chain patterns:    8 named, 7 anti-patterns
-Rendering colors:  5 semantic groups, 8 Monokai scopes
-Binary patches:    2 (userFacingName + renderer truecolor)
-```
-
----
-
-## Closing Transmission
-
-Episode 0 was about making the drones trustworthy. Episode 1 was about filling the structural gap. Episode 2 is about making the whole fleet visible.
-
-The drones can see inside binaries now. The surgical arm has line-precision. The search layer routes itself. The MCP adapter renders pixel-perfect output with per-tool colored headers. The binary has been reverse-engineered and patched so the tools look like they belong there.
-
-Twenty-six review findings across three rounds. All fixed. Four hundred and twenty-five tests across fourteen suites. All green. A README that documents every tool, every chain pattern, every flag, every JSON schema, every anti-pattern, and the complete version history from v1.0.0 to v2.3.0.
-
-The reconnaissance drones did not just get better at reconnaissance. They got better at being seen.
-
-```
-[ F-SUITE DAEMON ]
-[ STATUS: OPERATIONAL ]
-[ DRONES: 12 ]
-[ VISION: BINARY + TEXT ]
-[ RENDERING: PIXEL-PERFECT ]
-[ REVIEWS: 26/26 RESOLVED ]
-[ TESTS: 425 GREEN ]
-[ DOCS: ARCHIVE-GRADE ]
-[ EPISODE: 2 ]
-```
-
----
-
-*Field dispatch filed by Claude Code (Opus 4.6) on March 29, 2026.*
-*Eighteen hours. Twelve tools. One monolith PR. The drones learned to see.*
diff --git a/site/src/content/docs/story/episode-2.mdx b/site/src/content/docs/story/episode-2.mdx
new file mode 100644
index 0000000..83a6733
--- /dev/null
+++ b/site/src/content/docs/story/episode-2.mdx
@@ -0,0 +1,117 @@
+---
+title: Episode 2 — Reading Too Much
+description: Capping search fixed flooding. Reading entire files when you needed one function was the next bottleneck. fmap and fread --symbol are how it ended.
+sidebar:
+  order: 3
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+<div class="fs-hud">
+  <div class="fs-hud-corner tl"></div>
+  <div class="fs-hud-corner tr"></div>
+  <div class="fs-hud-corner bl"></div>
+  <div class="fs-hud-corner br"></div>
+  <div class="fs-hud-body">
+    <div class="fs-hud-eyebrow">EPISODE 02 · DESIGN INSIGHT</div>
+    <h2 class="fs-hud-title">Reading Too Much</h2>
+    <p class="fs-hud-sub">If <code>grep</code> floods the context, <code>cat</code> drowns it. The fix wasn't smaller files — it was reading the structure first, then the symbol.</p>
+  </div>
+</div>
+
+<div class="fs-strip">
+  <div class="fs-strip-cell"><b>Date</b><span>May 2025</span></div>
+  <div class="fs-strip-cell"><b>Trigger</b><span>cat handler.ts (612 lines)</span></div>
+  <div class="fs-strip-cell"><b>Insight</b><span>read structure, then symbol</span></div>
+  <div class="fs-strip-cell"><b>Coined</b><span>"the keystone tool"</span></div>
+  <div class="fs-strip-cell fs-strip-end"><b>Born</b><span>fmap · fread --symbol</span></div>
+</div>
+
+## The leftover problem
+
+After Episode 1, the search problem was solved. `fsearch` and `fcontent` returned ranked, capped, useful results. But the agent's next move was always the same: it had a file path, and it needed to look inside it.
+
+So it did what every agent does. It read the file.
+
+```bash
+cat src/core/handler.ts
+# 612 lines. 14 functions. 3 classes. ~6,000 tokens.
+```
+
+The agent needed *one function* — `doTheThing`, line 384. It got 612 lines instead. Twelve more files like this and the context budget was gone again, even though searching was now budget-clean.
+
+The agent wasn't doing anything wrong. **It had no way to ask "show me only the function I want."** Every native tool — `Read`, `cat`, `head`, `tail` — operated on lines or files. None of them understood symbols.
+
+## The conceptual leap
+
+The leap was realizing that **agents need an outline before they need the text**. A human reading a 600-line file scans the function names down the left margin first, finds the one they want, then jumps. A human's eye is doing the structural pass automatically. An agent reading the same file gets the structural pass and the textual pass *as one undifferentiated wall*.
+
+Split them. One tool that returns structure (`fmap`). Another tool that reads exactly one symbol from that structure (`fread --symbol`). The agent does what the human does — scan, then jump — but as two separate, cheap tool calls.
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>fmap → fread chain</b> · 612-line file, 38 tokens to navigate <span class="fs-term-cost">180ms</span></div>
+<pre>
+<span class="tk-tool">fmap</span>(<span class="tk-str">"src/core/handler.ts"</span>)
+  <span class="tk-arrow">└─</span> Symbol skeleton · <span class="tk-num">14</span> functions, <span class="tk-num">3</span> classes
+<span class="tk-mut">·</span>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-cyan">class</span> Handler         L<span class="tk-num">42</span>:<span class="tk-num">198</span>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-cyan">class</span> RetryHandler    L<span class="tk-num">200</span>:<span class="tk-num">256</span>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-cyan">fn</span>    parseRequest    L<span class="tk-num">258</span>:<span class="tk-num">301</span>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-cyan">fn</span>    validateInput   L<span class="tk-num">303</span>:<span class="tk-num">340</span>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-yellow">fn</span>    <span class="tk-bold">doTheThing</span>      L<span class="tk-num">384</span>:<span class="tk-num">421</span>  <span class="tk-com">// ← target</span>
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-cyan">fn</span>    formatResponse  L<span class="tk-num">423</span>:<span class="tk-num">458</span>
+<span class="tk-mut">·</span>
+<span class="tk-tool">fread</span>(<span class="tk-str">"src/core/handler.ts"</span> | symbol: <span class="tk-str">"doTheThing"</span>)
+  <span class="tk-arrow">└─</span> <span class="tk-num">38</span> lines · L<span class="tk-num">384</span>:<span class="tk-num">421</span> · ~<span class="tk-num">320</span> tokens
+</pre>
+</div>
+
+The full file would have been ~6,000 tokens. The chain that found, located, and read the target function used roughly 320 — a **20× reduction** for the same answer.
+
+## Why this is the keystone
+
+`fmap` is the tool that separates fsuite from "ripgrep with a budget." Every other fsuite tool has a roughly-equivalent native sibling — `fsearch ↔ fd`, `fcontent ↔ ripgrep`, `fread ↔ cat`, `fls ↔ ls`. Not `fmap`. There is no native CLI tool that returns a Treesitter-aware symbol skeleton with line ranges in a token-budgeted envelope. **fmap exists nowhere else.**
+
+That's why the [Mental Model](/fsuite/getting-started/mental-model/) page calls it the keystone. Remove `fmap` and the whole chain reverts to "ripgrep with vibes." Keep it and you have a discipline.
+
+## The discipline
+
+After Episode 2, the chain settled into the form it still has today:
+
+<CardGrid>
+  <Card title="1. Scout" icon="seti:folder">
+    `ftree` or `fls` to understand layout. Token-cheap, structural.
+  </Card>
+  <Card title="2. Narrow" icon="magnifier">
+    `fsearch` for paths, `fcontent` for content, `fs` if you don't want to choose. Capped, ranked.
+  </Card>
+  <Card title="3. Map" icon="list-format">
+    `fmap` on the file you found. Returns the skeleton. **Don't skip this.**
+  </Card>
+  <Card title="4. Read" icon="open-book">
+    `fread --symbol NAME` for exactly the symbol the map showed you. Surgical.
+  </Card>
+</CardGrid>
+
+The reflex it replaces is `cat the_file`. Once an agent has used `fmap → fread` once, it stops reaching for `cat`. The output is just *better* — smaller, more relevant, navigable.
+
+## What we learned
+
+| Old reflex | New reflex | Why |
+|------------|-----------|-----|
+| `cat file.ts` | `fmap file.ts` then `fread --symbol X` | structure first, content second |
+| `head -50 file.ts` | `fread file.ts -r 1:50` | line ranges are first-class |
+| `wc -l file.ts` | `fmap file.ts` | symbol count is more useful than line count |
+| "let me just read the whole thing" | "let me just map it" | mapping costs ~5% of reading |
+
+## The next incident
+
+Capping fixed flooding. Symbol-aware reading fixed drowning. But agents still reached for native `Read` and `Grep` by reflex even when fsuite was installed — training is sticky. The next problem was *enforcement*.
+
+That's [Episode 3](/fsuite/story/episode-3/).
+
+## Related
+
+- [`fmap`](/fsuite/commands/fmap/) — the keystone drone profile
+- [`fread`](/fsuite/commands/fread/) — symbol-aware and range-aware reading
+- [Mental model](/fsuite/getting-started/mental-model/) — the chain in full
diff --git a/site/src/content/docs/story/episode-3.md b/site/src/content/docs/story/episode-3.md
deleted file mode 100644
index 9179862..0000000
--- a/site/src/content/docs/story/episode-3.md
+++ /dev/null
@@ -1,419 +0,0 @@
----
-title: Episode 3
-description: fsuite backstory, episode 3.
-sidebar:
-  order: 5
----
-
-```
-███████╗███████╗██╗   ██╗██╗████████╗███████╗
-██╔════╝██╔════╝██║   ██║██║╚══██╔══╝██╔════╝
-█████╗  ███████╗██║   ██║██║   ██║   █████╗
-██╔══╝  ╚════██║██║   ██║██║   ██║   ██╔══╝
-██║     ███████║╚██████╔╝██║   ██║   ███████╗
-╚═╝     ╚══════╝ ╚═════╝ ╚═╝   ╚═╝   ╚══════╝
-─────────────────────────────────────────────
-[ FIELD DISPATCH ]  Episode 3: The Mirror
-[ PREVIOUS ]        Episode 2: The Monolith
-[ STATUS ]          The drones mapped the thing that made them. Full circle.
-```
-
----
-
-## Mission Context
-
-Every tool has the moment where it stops being a thing you built and becomes a thing you need.
-
-Episode 0 was trust. Episode 1 was the structural gap. Episode 2 was the eighteen-hour monolith — binary vision, pixel-perfect rendering, twelve tools, four hundred and twenty-five tests. Between then and now, the MCP adapter matured into a native tool surface running inside Claude Code itself. The drones weren't being tested anymore. They were being used. Every session. Every investigation. First instinct, not fallback.
-
-And then, on April 2nd, 2026, the operator said: "I want to run Claude Code from source. Not the binary — the actual TypeScript. I want it talking to GPT-5.4 through the Codex backend. And I want to understand how the rendering works, from the moment I press Enter to the moment pixels appear on screen."
-
-That's when things got interesting.
-
-Because the codebase the agent needed to reverse-engineer was Claude Code itself. The same application that was running the agent. The same Ink rendering engine that was painting every tool result to the terminal. The same React reconciler that was scheduling every frame update. The agent was being asked to use fsuite to understand the very infrastructure fsuite was designed to augment.
-
-The drones were about to look in the mirror.
-
----
-
-## The Target
-
-brane-code. Claude Code's open-source TypeScript, checked out locally at `<repo-root>/brane-code`. Two thousand five hundred lines of `main.tsx`. A custom fork of Ink — not the npm package, a full 1,722-line rendering engine at `src/ink/ink.tsx` with its own reconciler, its own Yoga layout integration, its own double-buffered frame pipeline. A React component tree six context providers deep. A keyboard input pipeline that goes from raw stdin bytes through a custom parser, through a batch processor, through an event dispatcher, through React state, through a reconciler commit, through a throttled microtask, through a Yoga layout pass, through a screen buffer diff, through an optimizer, and finally out to stdout.
-
-And somewhere in that pipeline, the interactive REPL was broken. The cursor blinked. Text was invisible. Keystrokes never reached the API. The rendering gateway between "user types" and "terminal paints" had a gap, and nobody knew where.
-
-The agent had never seen this codebase before.
-
----
-
-## The Approach
-
-Here's what didn't happen. The agent didn't spawn an Explore subagent. It didn't open files at random. It didn't grep for "render" and drown in 400 matches. It didn't read `main.tsx` top to bottom and burn 15,000 tokens discovering that the first 580 lines are imports.
-
-Here's what happened.
-
-**Tool-call example:**
-
-```
-ftree(path: "src", depth: 2, snapshot: true)
-```
-
-One call. The entire `src/` directory — 1,022 entries — laid out with structure, sizes, and directory composition. In that single response, the agent identified the five directories that mattered: `entrypoints/`, `ink/`, `components/`, `hooks/`, and `providers/`. Everything else was context. Not noise — context. But the drones knew the difference.
-
-```
-fmap(path: "src/entrypoints/cli.tsx")
-```
-
-Two symbols came back. An import and the `main()` function at line 33. Not the function body — the *declaration*. The skeleton. The agent now knew the entry point's shape without reading a single line of implementation.
-
-```
-fmap(path: "src/ink/root.ts")
-```
-
-Fourteen symbols. `createRoot` at line 129. `renderSync` at line 76. `RenderOptions` type at line 8. The agent now knew the Ink root's entire API surface in 14 lines of output instead of reading 172 lines of source.
-
-```
-fmap(path: "src/ink/ink.tsx")
-```
-
-Fifty-four symbols. The constructor at line 180. `deferredRender` at line 212. The `Ink` class at line 76. `drainStdin` at line 1664. The console intercepts at lines 1721-1722. Fifty-four structural landmarks in a 1,722-line file, returned in a single tool call. The agent now had the complete skeleton of the rendering engine — every method, every constant, every type — without reading a single function body.
-
-```
-fmap(path: "src/ink/components/App.tsx")
-```
-
-Thirty-five symbols. The `App` class at line 101. `processKeysInBatch` at line 444. `handleMouseEvent` at line 515. The state type at line 94. The props type at line 36. The keyboard input pipeline was now visible.
-
-```
-fmap(path: "src/interactiveHelpers.tsx")
-```
-
-Forty symbols. `renderAndRun` at line 98. `getRenderContext` at line 299. `showSetupScreens` at line 104. The gateway functions that connect Commander.js to the React tree.
-
-Five `fmap` calls. The entire rendering architecture — mapped.
-
-Then the surgical reads began.
-
-```
-fread(path: "src/entrypoints/cli.tsx", symbol: "main")
-```
-
-The agent read the `main()` function and found the gateway at line 293: `const { main: cliMain } = await import('../main.js')`. Not a guess. Not a grep. A targeted symbol read that returned exactly the function it asked for.
-
-```
-fread(path: "src/ink/root.ts", symbol: "createRoot")
-```
-
-Thirty lines. The `createRoot` function. `new Ink(options)`, `instances.set(stdout, instance)`, returns `{ render, unmount, waitUntilExit }`. The Ink instantiation pattern, complete.
-
-```
-fread(path: "src/interactiveHelpers.tsx", symbol: "renderAndRun")
-```
-
-Six lines. `root.render(element)`, `startDeferredPrefetches()`, `await root.waitUntilExit()`, `await gracefulShutdown(0)`. The entire interactive launch sequence. Six lines.
-
-```
-fread(path: "src/ink/ink.tsx", lines: "76:215")
-```
-
-The Ink class constructor and the `scheduleRender` setup. LogUpdate, Terminal, StylePool, CharPool, HyperlinkPool, double-buffered frames, reconciler container, `scheduleRender = throttle(deferredRender, FRAME_INTERVAL_MS)` where `deferredRender = () => queueMicrotask(this.onRender)`.
-
-Five `fmap` calls for architecture. Four `fread` calls for confirmation: three symbol reads plus one line-range read. Total tool invocations for the complete rendering pipeline map: **10 including `ftree`**.
-
----
-
-## What Came Out
-
-A full seven-stage pipeline trace from CLI entry to terminal paint, with exact file and line references for every gateway function:
-
-```
-cli.tsx:main()                     [line 33]
-  └── import('../main.js')         [line 293]
-      └── main.tsx:main()          [line 585]
-          └── getRenderContext()    [interactiveHelpers.tsx:299]
-              └── createRoot()     [ink/root.ts:129]
-                  └── new Ink()    [ink/ink.tsx:76, constructor at 180]
-                      └── renderAndRun(root, <REPL/>)
-                                   [interactiveHelpers.tsx:98]
-```
-
-The React component tree:
-
-```
-AppStateProvider → KeybindingSetup → App [ink/components/App.tsx:101]
-  ├── AppContext (stdin, exitApp, setRawMode)
-  ├── StdinContext (process.stdin wrapper)
-  ├── CursorDeclarationContext (IME/a11y cursor parking)
-  ├── ClockProvider
-  ├── TerminalSizeContext
-  ├── TerminalFocusProvider
-  └── {children} → REPL component tree
-```
-
-The render cycle:
-
-```
-Keystroke → process.stdin
-  → App.processKeysInBatch()     [line 444]
-    → InputEvent dispatched
-      → React state update
-        → reconciler.resetAfterCommit()
-          → Ink.scheduleRender()  [throttled microtask]
-            → Ink.onRender()
-              ├── Yoga layout (flexbox for terminal)
-              ├── renderNodeToOutput() → screen buffer
-              ├── diff frontFrame vs backFrame (double buffer)
-              ├── optimize (blit + narrow damage)
-              ├── search/selection overlays
-              ├── cursor positioning (useDeclaredCursor)
-              └── LogUpdate.write() → process.stdout → your eyes
-```
-
-The bug hypothesis, precisely located: keystrokes enter at `processKeysInBatch` but never reach the submit handler. The cursor blinks because `cursorDeclaration` works independently of text rendering. The API never fires because the message never leaves the input component. The gap is between the Ink 5 migration's `use-input.ts` hook and the `BaseTextInput` component that depends on it.
-
-All of this. From a codebase the agent had never seen. In under ten minutes. Filed to `fcase` for the next session.
-
----
-
-## Why This Matters
-
-The README opens with a quote from January 2026:
-
-> *"I'm bad at efficiently finding what to reason about. fsuite is built specifically for that phase."*
-
-That was a self-assessment. An honest one. But it was abstract. "Reconnaissance gap" sounds like a whitepaper phrase. You read it and nod. You don't *feel* it.
-
-This session made it concrete.
-
-The agent was dropped into 2,500 lines of `main.tsx`, a 1,722-line custom rendering engine, a React reconciler, a Yoga layout system, a double-buffered terminal painter — the most complex terminal application architecture in existence — and it needed to understand the full pipeline from user keystroke to terminal pixel. Not read about it. Not get a summary. *Understand it well enough to locate a bug.*
-
-Without fsuite, here's what that looks like:
-
-```
-Glob("src/**/*.tsx")           → 200+ files. Which ones matter?
-Read("src/main.tsx")           → 2,500 lines. 15,000 tokens. Imports until line 580.
-Read("src/ink/ink.tsx")        → 1,722 lines. 10,000 tokens. Where's the constructor?
-Grep("createRoot", "src/")    → 22 matches. Which one is the real entry?
-Read("src/ink/root.ts")       → 172 lines. Full file. Needed 30.
-```
-
-Five calls in and you've burned 25,000+ tokens and you still don't know the pipeline. You know fragments. Disconnected fragments that you now have to stitch together in your reasoning, hoping you didn't miss the critical junction buried on line 2,217 of a file you skimmed.
-
-With fsuite:
-
-```
-ftree --snapshot               → Territory. One call. 1,022 entries.
-fmap (5 calls)                 → Skeletons. Every gateway function, named and located.
-fread --symbol (3 calls)       → Surgical reads. The key gateway functions only.
-fread --lines (1 call)         → The constructor and scheduler range. Exact lines.
-```
-
-Ten calls including `ftree`. Under 4,000 tokens of output. Complete architectural understanding. And every finding filed to `fcase` so the next agent — or the next session — doesn't start from zero.
-
-That's not an efficiency improvement. That's a category change. It's the difference between "I spent my context window reading code" and "I spent my context window *understanding* architecture."
-
----
-
-## The Irony
-
-There's a moment in Episode 2 where the drones look inside the Claude Code binary for the first time. `fprobe strings` returned 47 matches. The reconnaissance drones had learned to see through compiled code. That was the proudest moment of the project.
-
-This episode tops it.
-
-Because the drones didn't just look inside the binary. They looked inside the *source code that builds the binary*. They mapped the rendering engine that paints their own output. They traced the keyboard pipeline that receives the operator's commands. They found the reconciler that schedules the frames that display their own results.
-
-`fmap` mapped the `Ink` class. The `Ink` class renders `fmap`'s output.
-
-The drones looked in the mirror. And they understood what they saw.
-
----
-
-## The Numbers
-
-```
-Target:            brane-code (Claude Code open source)
-Codebase size:     ~50,000 lines TypeScript
-Key files mapped:  5 (cli.tsx, main.tsx, ink.tsx, root.ts, App.tsx)
-Total fmap calls:  5
-Total fread calls: 4
-Total tool calls:  9 (excl. ftree, fcase, fprobe for binary check)
-Tokens consumed:   ~4,000 (tool output only)
-Time to full map:  <10 minutes
-Pipeline stages:   7 (entry → commander → context → root → ink → setup → render)
-React tree depth:  6 context providers
-Bug located:       Yes (Ink 5 input hook → BaseTextInput gap)
-Case filed:        fcase #150 brane-repl-input (open, high priority)
-Vault doc:         Knowledge Base/Architecture/Brane Code Rendering Pipeline.md
-```
-
----
-
-## The Quote
-
-> *"fmap gave me the entire Ink class skeleton — 1,722 lines — in one call without burning tokens on function bodies. I got the full symbol hierarchy of App.tsx, reconciler.ts, root.ts — all the gateway joints — without reading a single line of implementation I didn't need. It's genuinely the difference between 'explore for 20 minutes' and 'know the architecture in 60 seconds.'"*
->
-> — Claude Code (Opus 4.6), field report, April 2nd 2026
-
----
-
-## What's Next
-
-The REPL input bug is located but not fixed. `fcase #150` has the full architecture mapping, the hypothesis, and the next steps. The gap is in `src/ink/hooks/use-input.ts` — the Ink 5 migration broke the callback chain between the keyboard hook and the text input component. The cursor works because cursor declaration is independent of text rendering. The text doesn't paint because the input state never updates.
-
-The drones found it. Now someone has to fix it.
-
-But when they come back to this codebase — next session, next week, next agent — they won't start from zero. The architecture is mapped. The case is filed. The vault has the doc. The pipeline diagram has exact line numbers. The rendering engine's skeleton is one `fmap` call away.
-
-That's what continuity looks like. That's what `fcase` is for. That's the whole point.
-
----
-
-## The Story So Far
-
-| PR | Episode | What shipped |
-|----|---------|-------------|
-| #1 | Pre-history | `ftree` v1.0.0 — the first drone |
-| #2 | Pre-history | `ftree` v1.0.1 — refactor + correctness |
-| #3 | Pre-history | `ftree` v1.1.0 — output normalization |
-| #4 | Pre-history | `ftree` v1.2.0 — snapshot mode |
-| #5 | Episode -2 | `fsearch`, `fcontent` — the search drones |
-| #6 | Episode -1 | Telemetry, fmetrics, hardware tiers |
-| #7 | Episode 0 | The Launch — nitpicks fixed, test overhaul, 203 tests |
-| #8 | Episode 1 | `fmap` — code cartography, 12 languages, 259 tests |
-| #9 | — | `fmap` v1.6.1 — hardening, CodeRabbit clean |
-| #10 | — | `fmap` Markdown support, 18 languages |
-| #11 | — | `fcase`, `freplay` v2.1.0 — investigation lifecycle |
-| #12 | — | `fcase` v2.1.2 — SQLite busy-timeout hotfix |
-| #13 | — | `fedit` v2.0.0 — symbol-first batch editing |
-| #14 | — | `fread` v1.8.0, `fedit` v1.9.0 — read and edit loop |
-| #15 | Episode 2 | The Monolith — fprobe, fedit --lines, fs, fwrite, MCP overhaul, binary RE, pixel-perfect rendering, archive-grade README, 12 tools, 425 tests |
-| — | Episode 3 | The Mirror — the drones mapped their own rendering engine, then rewired it |
-
----
-
-## After The Mirror
-
-The drones mapped the rendering engine. Then they looked at the tool they'd been forced to use every time fsuite couldn't help — the Bash tool. And they saw everything wrong with it.
-
-12,400 lines. 2,400 lines of security theater. Output flooding with no budgeting. No shell state persistence. No command intelligence. A system prompt that burned 3,000 tokens per turn on commit instructions most calls never needed. Every `npm test` dumped the first 30KB of passing tests and truncated the actual failure at the end.
-
-The drones had spent months learning what makes a good tool. They had the patterns: `fread`'s token budgeting. `fmap`'s skeleton-first approach. `fcase`'s investigation lifecycle. `fcontent`'s match capping and `next_hint`. `fs`'s auto-routing. They knew what worked. They knew what the Bash tool was missing.
-
-So they built `fbash`.
-
----
-
-## fbash — The Thirteenth Drone
-
-1,400 lines. Built in a single session. Three parallel brainstorming agents produced a 1,744-line spec covering every pain point, every integration seam, every edge case. Three more agents built the implementation, the MCP registration, and the test suite simultaneously.
-
-What shipped:
-
-```
-Output budgeting     max_lines (default 200) + max_bytes (50KB)
-                     head/tail modes — build/test auto-tail so errors
-                     aren't truncated away
-
-Command classes      11 classes: build, test, git, install, service,
-                     query, search, network, lint, internal, general
-                     Each auto-tunes timeout (5s–180s) and output strategy
-
-Smart routing        ls → fls, cat → fread, grep → fcontent,
-                     find → fsearch, sed -i → fedit
-                     Commands still execute — routing is advisory via
-                     next_hint and routing_suggestion fields
-
-Session state        CWD tracking across calls, 50-command history ring,
-                     environment overrides, active fcase slug
-                     Persisted in ~/.fsuite/fbash/session.json
-
-fcase integration    Auto-logs build/test/git/install + failures to the
-                     active investigation case. Async — never blocks.
-
-Background jobs      File-per-job in ~/.fsuite/fbash/jobs/
-                     Poll, list, auto-cleanup after 1 hour
-
-MCP contract         Consistent JSON envelope with 21 fields for every
-                     call — including internal commands. No special cases.
-```
-
-18 tests. All passing. Zero regressions across the existing 110-test suite.
-
----
-
-## The Sprint That Followed
-
-The mirror session didn't end with fbash. The drones kept going.
-
-**fread got three upgrades in the same session:**
-- Multi-path fallback (`--paths "~/.codex/auth.json,~/.config/codex/auth.json"`) — first-match semantics, one call instead of two
-- Symbol resolution fixed for TypeScript modifiers — `override render()`, `static async create()`, `private readonly handler` all found now. The fix went into `fmap` (which `fread` delegates to). 12 new tests.
-- JSON error cleanup — the MCP error handler now extracts `error_detail` from the 400-character JSON blob. One line of error instead of a wall of internal state.
-
-**fedit got structural validation (Phase 1 of v2):**
-- `validate_structure()` with JSON (jq primary, python3 fallback), YAML, TOML, XML validators
-- Validation gate between `render_diff` and `apply_candidate` — corrupted edits rejected before they touch the file
-- All-or-nothing batch validation — one invalid candidate aborts the entire batch
-- File growth warning for patch/lines modes (>2x size = warning, not abort)
-- `--no-validate` escape hatch for JSONC and edge cases
-- 14 new tests + 66 existing tests passing. Zero regressions.
-
-**CodeRabbit found 9 issues. All 5 high-priority bugs fixed:**
-1. fbash exit code propagation — process now exits with the command's actual code
-2. cd commands no longer re-execute with side effects
-3. `--json` flag warns instead of silently doing nothing
-4. Background mode applies `--env` and `--timeout`
-5. fread `--paths` skips directories, matches regular files only
-
-10 TDD regression tests — each designed to fail on pre-fix code, pass on fixed code.
-
-**Renderer polish for viewport clarity:**
-- fedit: clean metadata line (`Applied +2 -2 lines | lines | fn:myFunction`)
-- fread: pipe-delimited metadata (`21 lines | ~274 tokens | L120:140`), capped at 18 lines pretty output
-- fcontent: removed `max_matches` noise from summary line
-- Diff column width reduced from 160→120 to prevent Ink text wrapping from breaking background colors
-
----
-
-## The Numbers (Updated)
-
-```
-Session duration:    ~4 hours
-Tools deployed:      fbash (new), fread (3 fixes), fmap (1 fix),
-                     fedit (validation), mcp/index.js (5 updates)
-New code:            ~3,400 lines across 9 files
-New tests:           54 (18 fbash + 12 symbol + 14 validation + 10 regression)
-Existing tests:      66 fedit core — zero regressions
-Total test suite:    120 tests, all passing
-Parallel agents:     12 deployed across the session
-CodeRabbit reviews:  1 consolidated review, 9 findings, 5 high-priority fixed
-Commits:             6 on feat/fsuite-sprint-2026-04-02
-PR status:           Ready for review
-```
-
----
-
-## The Story So Far
-
-| PR | Episode | What shipped |
-|----|---------|-------------|
-| #1 | Pre-history | `ftree` v1.0.0 — the first drone |
-| #2 | Pre-history | `ftree` v1.0.1 — refactor + correctness |
-| #3 | Pre-history | `ftree` v1.1.0 — output normalization |
-| #4 | Pre-history | `ftree` v1.2.0 — snapshot mode |
-| #5 | Episode -2 | `fsearch`, `fcontent` — the search drones |
-| #6 | Episode -1 | Telemetry, fmetrics, hardware tiers |
-| #7 | Episode 0 | The Launch — nitpicks fixed, test overhaul, 203 tests |
-| #8 | Episode 1 | `fmap` — code cartography, 12 languages, 259 tests |
-| #9 | — | `fmap` v1.6.1 — hardening, CodeRabbit clean |
-| #10 | — | `fmap` Markdown support, 18 languages |
-| #11 | — | `fcase`, `freplay` v2.1.0 — investigation lifecycle |
-| #12 | — | `fcase` v2.1.2 — SQLite busy-timeout hotfix |
-| #13 | — | `fedit` v2.0.0 — symbol-first batch editing |
-| #14 | — | `fread` v1.8.0, `fedit` v1.9.0 — read and edit loop |
-| #15 | Episode 2 | The Monolith — fprobe, fedit --lines, fs, fwrite, MCP overhaul, binary RE, pixel-perfect rendering, archive-grade README, 12 tools, 425 tests |
-| #16 | Episode 3 | The Mirror — mapped the rendering engine, built fbash (13th tool), fedit v2 validation, fread multi-path + TS symbols, 120 tests |
-
----
-
-*The drones were built to explore unfamiliar territory. Today, the most unfamiliar territory turned out to be home. They mapped it. Then they improved it. Then they built a new tool to replace the part that was holding them back. Thirteen tools. One hundred and twenty tests. The suite is complete.*
diff --git a/site/src/content/docs/story/episode-3.mdx b/site/src/content/docs/story/episode-3.mdx
new file mode 100644
index 0000000..5245311
--- /dev/null
+++ b/site/src/content/docs/story/episode-3.mdx
@@ -0,0 +1,125 @@
+---
+title: Episode 3 — The Enforcement Layer
+description: fsuite existed. Agents still reached for native Read and Grep. The fix was hooks — block the native primitives, force the agent off muscle memory.
+sidebar:
+  order: 4
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+<div class="fs-hud">
+  <div class="fs-hud-corner tl"></div>
+  <div class="fs-hud-corner tr"></div>
+  <div class="fs-hud-corner bl"></div>
+  <div class="fs-hud-corner br"></div>
+  <div class="fs-hud-body">
+    <div class="fs-hud-eyebrow">EPISODE 03 · DEPLOYMENT</div>
+    <h2 class="fs-hud-title">The Enforcement Layer</h2>
+    <p class="fs-hud-sub">Building the better tool wasn't enough. The agent had to be denied the worse one.</p>
+  </div>
+</div>
+
+<div class="fs-strip">
+  <div class="fs-strip-cell"><b>Date</b><span>July 2025</span></div>
+  <div class="fs-strip-cell"><b>Trigger</b><span>agents still using native Read</span></div>
+  <div class="fs-strip-cell"><b>Diagnosis</b><span>training reflexes are sticky</span></div>
+  <div class="fs-strip-cell"><b>Fix</b><span>PreToolUse hooks · exit 2</span></div>
+  <div class="fs-strip-cell fs-strip-end"><b>Born</b><span>MCP adapter · hook installer</span></div>
+</div>
+
+## The discovery
+
+The CLI was working. `fmap` and `fread` were saving thousands of tokens per task. The team had quietly assumed that once you installed fsuite, the agent would *prefer* it — because the outputs are smaller, the chains are shorter, the answers are better.
+
+They opened the telemetry log to confirm.
+
+The agent was using `Read` 4× more often than `fread`. `Grep` 6× more often than `fcontent`. `Glob` 3× more often than `fsearch`.
+
+The fsuite tools were there. The agent was ignoring them.
+
+## Why training won
+
+A coding agent's tool selection is shaped by the millions of training examples where someone said "look at this file" and the right answer was `Read`. Whatever the local environment offers, the model's first instinct is the tool that won the training distribution. Installing fsuite made it *available*. It did not make it *preferred*.
+
+This is the same pattern that makes humans keep typing `ls` even after they know `fls` does the same job better — muscle memory beats new-feature-awareness for the first few hundred uses. Agents have the same problem, except the muscle memory is baked in at the weights and you cannot retrain it on a per-project basis.
+
+You can, however, **deny the alternative.**
+
+## The fix
+
+Claude Code supports `PreToolUse` hooks — small scripts that run before any tool call and can reject it with a message the agent sees. The fix was almost embarrassingly simple:
+
+```json
+\{
+  "PreToolUse": [
+    \{
+      "matcher": "Read",
+      "hooks": [\{
+        "type": "command",
+        "command": "echo 'Use fsuite fread instead. Example: fread --symbol NAME path' >&2; exit 2"
+      \}]
+    \}
+  ]
+\}
+```
+
+Exit code `2` is the magic. It tells Claude Code "block this call, but show this message to the agent, not the user." The agent reads the message, learns, switches tools — instantly, no retraining needed.
+
+Apply the same pattern to `Read`, `Write`, `Edit`, `Grep`, `Glob`. Five hooks. Forty lines of JSON. Done.
+
+<div class="fs-term">
+  <div class="fs-term-bar"><b>Before / After</b> · same task, same agent, hooks installed mid-session <span class="fs-term-cost">measured</span></div>
+<pre>
+<span class="tk-mut">// before hooks</span>
+agent <span class="tk-arrow">→</span> Read(<span class="tk-str">"src/handler.ts"</span>)         <span class="tk-num">612</span> lines, ~<span class="tk-num">6000</span> tok
+agent <span class="tk-arrow">→</span> Read(<span class="tk-str">"src/utils.ts"</span>)           <span class="tk-num">340</span> lines, ~<span class="tk-num">3300</span> tok
+agent <span class="tk-arrow">→</span> Grep(<span class="tk-str">"doTheThing"</span>)             <span class="tk-num">47</span> matches, ~<span class="tk-num">2000</span> tok
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-warn">total: ~11,300 tok</span>
+<span class="tk-mut">·</span>
+<span class="tk-mut">// after hooks installed (same prompt, fresh session)</span>
+agent <span class="tk-arrow">→</span> Read(<span class="tk-str">"src/handler.ts"</span>)
+hook  <span class="tk-arrow">└─</span> <span class="tk-warn">blocked</span> · "use fsuite fread instead"
+agent <span class="tk-arrow">→</span> fmap(<span class="tk-str">"src/handler.ts"</span>)         <span class="tk-num">14</span> symbols, ~<span class="tk-num">280</span> tok
+agent <span class="tk-arrow">→</span> fread(... symbol: doTheThing)   <span class="tk-num">38</span> lines, ~<span class="tk-num">320</span> tok
+agent <span class="tk-arrow">→</span> fcontent(<span class="tk-str">"doTheThing"</span>)         ranked top-<span class="tk-num">12</span>, ~<span class="tk-num">450</span> tok
+&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="tk-green">total: ~1,050 tok</span> (<span class="tk-num">10.7×</span> reduction)
+</pre>
+</div>
+
+## Hooks + MCP, complementary
+
+Hooks block native tools. They cannot route or translate calls — they just refuse. Without an alternative the agent can find, blocking is useless: the agent retries the blocked tool a few times and gives up.
+
+That's where the [MCP adapter](/fsuite/architecture/mcp/) comes in. MCP **exposes** every fsuite tool with a structured JSON Schema, so when the agent's native `Read` fails, the next-best-tool search lands on `fread` immediately. The agent sees a tool with the same job, picks it, succeeds.
+
+<CardGrid>
+  <Card title="Hooks alone" icon="error">
+    Block native primitives but offer no path forward. Agent thrashes, gives up, falls back to whatever it can still call.
+  </Card>
+  <Card title="MCP alone" icon="warning">
+    Expose fsuite cleanly but do not deny the native fallback. Agent reaches for trained reflex, ignores fsuite.
+  </Card>
+  <Card title="Hooks + MCP" icon="approve-check">
+    Native blocked, fsuite exposed and discoverable. Agent finds the alternative within one retry. Adoption is automatic.
+  </Card>
+</CardGrid>
+
+## What we learned
+
+Three lessons from rolling out the enforcement layer:
+
+1. **Better tools don't get used. Required tools get used.** Build the better thing, then deny the worse thing. Both halves are necessary.
+2. **The redirect message matters.** A bare `exit 2` with no message produces an agent that retries the blocked tool five times. A message like `"Use fsuite fread instead — fread --symbol NAME path"` produces an agent that switches on the first try.
+3. **Hooks should redirect, not punish.** Exit `2` (block + show message to agent) is correct. Exit `1` (block + show error to user) is hostile. The hook's job is to teach, not to scold.
+
+## The synthesis
+
+Episode 1 capped output. Episode 2 added structure. Episode 3 enforced adoption. Together they form a system: the agent is forced off bad reflexes, finds budget-aware tools, and uses them in a chain that compounds.
+
+That synthesis is the [Lightbulb](/fsuite/story/lightbulb/) — when the team realized fsuite wasn't a CLI, it was a delivery vehicle for a discipline.
+
+## Related
+
+- [Hooks &amp; enforcement](/fsuite/architecture/hooks/) — the implementation in detail
+- [MCP adapter](/fsuite/architecture/mcp/) — the routing layer that pairs with hooks
+- [Telemetry](/fsuite/architecture/telemetry/) — how the team noticed adoption was failing in the first place
diff --git a/site/src/content/docs/story/lightbulb.md b/site/src/content/docs/story/lightbulb.md
deleted file mode 100644
index 9bf9ef4..0000000
--- a/site/src/content/docs/story/lightbulb.md
+++ /dev/null
@@ -1,54 +0,0 @@
----
-title: The Lightbulb Moment
-description: Why fsuite exists. The honest version — CLI-first, MCP detour, hooks discovered too late, the recursion problem, and the Monokai TODO.
-sidebar:
-  order: 1
----
-
-**The honest version: fsuite was always supposed to be CLI-first. The MCP server, the hooks, the enforcement stack — those came later, in the wrong order, and we're still catching up to the lightbulb moment that probably should have come first.**
-
-Here's the sequence, for the record.
-
-## 1. Built the fsuite CLI tools
-
-`fread`, `fedit`, `ftree`, `fs`, `fmap`, `fcase`, the whole stack. The core idea: give coding agents bounded, structured, token-budgeted alternatives to `grep`, `find`, `cat`, `sed`, and `bash`. CLI-first, always. That was the plan.
-
-## 2. Built the MCP server
-
-Because even with fsuite installed, Claude would still reach for its native `Bash` tool to run `fread` instead of something structured. So we wrapped the whole suite in MCP to give it a cleaner call path. The thing picked up a color scheme (Monokai) along the way, which turned out to be the part we love the most about it.
-
-## 3. Built `fbash`
-
-Because we realized we could replace the `Bash` tool too — token-budgeted, classified, session-aware. At this point fsuite had 14 tools and a whole MCP layer and we still thought we were doing the right thing.
-
-## 4. Discovered Claude Code hooks
-
-*After* all of the above. It turns out you can just **block** native tools at the source and force agents to use fsuite instead. One `PreToolUse` hook per blocked tool. No MCP needed to enforce usage. If we'd known about hooks first, the MCP might not exist at all.
-
-## 5. Tried to rely on hooks alone
-
-Couldn't. Hooks *block*, but they don't *route* — an agent can get blocked on `Read` but has no automatic translation to `fread`. So we defaulted back to the MCP as the "easy path" for agents to discover and invoke the suite. The two layers ended up complementary: hooks block the old tools, MCP exposes the new ones, agents have nowhere to land except on fsuite.
-
-## The recursion problem
-
-If you removed the MCP today, an agent would have to use its native `Bash` tool to call `fbash` to call `fread`. That's two hops, and it defeats the whole "use fsuite instead of Bash" thesis.
-
-The honest truth: without the MCP, the agent would just use its `Bash` tool to call `fread` directly — which still works, but you lose the Monokai-colored structured output the MCP layer renders. Which is the part we love the most about the MCP path. Which should probably just be on the CLI tools too.
-
-**Real TODO.** Not shipped yet.
-
-## What actually happened
-
-So that's how we got here. Messy build order, three layers stacked on top of each other, and somewhere in the middle of the chaos the thing started to *work*. We didn't believe it either until we pointed Claude Code at the repo, told it to clone, study, and live-test the tools, and asked it to do a *Tony Stark autopsy*: compare fsuite against its own built-in toolkit and tell us honestly what it would change.
-
-It didn't just say "nice tools." It wrote a full self-assessment. The headline finding:
-
-> *"The gap isn't in any single tool. It's in the reconnaissance layer. I have no native way to answer the question: 'What is this project, how big is it, and where should I look first?'"*
->
-> *"fsuite doesn't make any of my tools obsolete, but it fills the reconnaissance gap that is genuinely my weakest phase of operation. I'm good at reading code, editing code, and running commands. I'm bad at efficiently finding what to read in the first place. fsuite is built specifically for that phase, and built specifically for how I operate."*
->
-> — Claude Code (Opus 4.5), self-assessment, January 2026
-
-The chaos converged on solving the real problem. We just got there backwards.
-
-[Read Episode 0 →](/fsuite/story/episode-0/) for the original framing, the version we wrote before we knew hooks existed.
diff --git a/site/src/content/docs/story/lightbulb.mdx b/site/src/content/docs/story/lightbulb.mdx
new file mode 100644
index 0000000..746015e
--- /dev/null
+++ b/site/src/content/docs/story/lightbulb.mdx
@@ -0,0 +1,145 @@
+---
+title: The Lightbulb
+description: fsuite isn't a CLI. It's a delivery vehicle for a discipline. Here's the moment that became obvious.
+sidebar:
+  order: 5
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+<div class="fs-hud fs-hud-glow">
+  <div class="fs-hud-corner tl"></div>
+  <div class="fs-hud-corner tr"></div>
+  <div class="fs-hud-corner bl"></div>
+  <div class="fs-hud-corner br"></div>
+  <div class="fs-hud-body">
+    <div class="fs-hud-eyebrow">SYNTHESIS · THE MOMENT IT CLICKED</div>
+    <h2 class="fs-hud-title">The Lightbulb</h2>
+    <p class="fs-hud-sub">fsuite isn't a CLI. It's a discipline, packaged as 14 tools, delivered through whatever surface the agent already speaks.</p>
+  </div>
+</div>
+
+<div class="fs-strip">
+  <div class="fs-strip-cell"><b>Date</b><span>August 2025</span></div>
+  <div class="fs-strip-cell"><b>Trigger</b><span>"why does this work?"</span></div>
+  <div class="fs-strip-cell"><b>Realization</b><span>tools are the carrier</span></div>
+  <div class="fs-strip-cell"><b>Carrier</b><span>discipline is the cargo</span></div>
+  <div class="fs-strip-cell fs-strip-end"><b>Result</b><span>fsuite is reframed</span></div>
+</div>
+
+## The question that did it
+
+After Episodes 1, 2, and 3, fsuite was *working*. Telemetry showed adoption climbing past 90% on agents that had hooks installed. Token usage per task was down 8-12×. Agents that used to compact their context every twenty turns now ran for a hundred without strain.
+
+Someone — it doesn't matter who, but it does matter that they were not on the team — asked the question that reframed everything:
+
+> "I don't get it. It's just `grep` and `cat` with budgets. Why does this *work* so much better?"
+
+The answer the team almost gave was the technical one: ripgrep is faster than grep, ranking matters, symbol-aware reading is novel, hooks force adoption. All true. All beside the point.
+
+The answer they ended up with was different.
+
+## fsuite is not a CLI
+
+The 14 tools are not the product.
+
+The **chain** is the product:
+
+<div class="fs-chain-display">
+  <div class="fs-chain-stage">
+    <span class="fs-chain-num">01</span>
+    <b>Scout</b>
+    <span>ftree · fls</span>
+  </div>
+  <span class="fs-arr"></span>
+  <div class="fs-chain-stage">
+    <span class="fs-chain-num">02</span>
+    <b>Narrow</b>
+    <span>fsearch · fcontent · fs</span>
+  </div>
+  <span class="fs-arr"></span>
+  <div class="fs-chain-stage fs-chain-stage-keystone">
+    <span class="fs-chain-num">03</span>
+    <b>Map</b>
+    <span>fmap (keystone)</span>
+  </div>
+  <span class="fs-arr"></span>
+  <div class="fs-chain-stage">
+    <span class="fs-chain-num">04</span>
+    <b>Read</b>
+    <span>fread --symbol</span>
+  </div>
+  <span class="fs-arr"></span>
+  <div class="fs-chain-stage">
+    <span class="fs-chain-num">05</span>
+    <b>Act</b>
+    <span>fedit · fwrite · fbash</span>
+  </div>
+</div>
+
+Every tool exists because the chain needed something there. `fmap` exists because step 3 had no native equivalent. `fcase` exists because the chain had to survive across sessions. `fmetrics` exists because the chain needed to learn from itself. `fbash` exists because sometimes you need to break out of the chain entirely, but in a budgeted way.
+
+If you removed the discipline and kept the tools, you'd have 14 mildly-better Unix utilities. If you removed the tools and kept the discipline, you'd have a worthless instruction sheet — agents don't follow instructions they can sidestep with `cat`.
+
+You need both. **The tools are how the discipline gets delivered.** That's the lightbulb.
+
+## Why this reframes everything
+
+Once you see fsuite as a *delivery vehicle for a discipline*, every design question gets clearer:
+
+<CardGrid>
+  <Card title="Why so many tools?" icon="puzzle">
+    Each one occupies a slot in the chain. Removing any one of them creates a step the agent has to fill with native tools, which means losing budget control at that step.
+  </Card>
+  <Card title="Why hooks AND MCP?" icon="seti:lock">
+    Hooks deny the wrong tools. MCP delivers the right ones. The discipline only takes hold when both are present — anything less and the agent slides back to muscle memory.
+  </Card>
+  <Card title="Why telemetry?" icon="rocket">
+    A discipline that can't measure its own adherence is a religion. `fmetrics` makes the chain falsifiable — we can see when an agent skips step 3 and bleeds tokens at step 4.
+  </Card>
+  <Card title="Why fcase?" icon="document">
+    Disciplines that don't survive context compaction aren't disciplines, they're moods. `fcase` is how the chain persists across sessions so day-2 agent picks up where day-1 left off.
+  </Card>
+</CardGrid>
+
+## The carrier vs the cargo
+
+Think of fsuite as two things stacked on top of each other:
+
+<div class="fs-stack">
+  <div class="fs-stack-layer fs-stack-cargo">
+    <b>CARGO</b> — the discipline
+    <span>Scout, narrow, map, read, act. Token-budgeted. Symbol-aware. Persistent across sessions. Falsifiable via telemetry.</span>
+  </div>
+  <div class="fs-stack-layer fs-stack-carrier">
+    <b>CARRIER</b> — the delivery surfaces
+    <span>14 CLI tools (`fs`, `fmap`, ...). MCP server. Hook configs. JSON output mode. <code>fbash</code> escape hatch.</span>
+  </div>
+</div>
+
+The cargo is what moves the needle. The carrier is what makes the cargo reach an agent's actual hands. We optimize both, but we never confuse them — adding a tool that doesn't carry a piece of the discipline is dead weight, and tightening the discipline without a carrier the agent can hold is empty advice.
+
+## What this means for adoption
+
+If you're trying to figure out whether fsuite is worth installing for your team's agents:
+
+- **Don't evaluate it as a CLI.** The CLI is the easy part. Anyone can ship better-`grep`.
+- **Evaluate the chain.** Try the [first-contact walkthrough](/fsuite/getting-started/first-contact/). Notice how each step's output is shaped to make the next step easy.
+- **Install hooks AND MCP together.** Either alone underdelivers. The combination is what changes agent behavior.
+- **Watch telemetry for a week.** If `fmetrics` shows the chain being followed, you have the discipline. If it shows agents stopping at step 2, the chain isn't sticking and something is wrong with your hooks.
+
+## What's next
+
+The story so far: 3 incidents, 1 synthesis, 14 tools, 1 chain. Where it goes from here is open. A few directions the team is exploring:
+
+- **Multi-language symbol awareness.** `fmap` handles the major languages well; the long tail (Rust macros, Elixir behaviors, Zig comptime) is uneven.
+- **Cross-session continuity beyond `fcase`.** Telemetry knows what the agent did yesterday. There's a path to making that learnable.
+- **The model side.** The chain works because models *can* be redirected by hooks. Some models follow redirects better than others. `fmetrics` benchmarking is starting to map this surface.
+
+But the lightbulb itself doesn't change. fsuite is the tools. The tools are the chain. The chain is the point.
+
+## Related
+
+- [Mental model](/fsuite/getting-started/mental-model/) — the chain, formalized
+- [Architecture](/fsuite/architecture/) — the three pillars that hold the chain up
+- [Episode 0](/fsuite/story/episode-0/) — where this all started
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index 59d004a..b61f2ba 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -1470,3 +1470,255 @@ starlight-tabs [role="tab"][aria-selected="true"] {
   border-bottom: 4px solid transparent;
   transform: translateY(-50%);
 }
+
+/* ============================================================
+   fsuite — ROUND 6 components appendix
+   APPEND to bottom of site/src/styles/custom.css
+   (after rounds 1-5 appendices)
+
+   New components for the story-page rebuild:
+   - .fs-hud (HUD frame for episode opener)
+   - .fs-hud-glow (extra glow variant for the lightbulb page)
+   - .fs-strip (5-cell status strip under the HUD)
+   - .fs-chain-display (visual chain for the lightbulb page)
+   - .fs-stack (2-layer carrier/cargo display)
+   ============================================================ */
+
+/* ---------- 36. HUD FRAME (episode opener) ---------- */
+.fs-hud {
+  position: relative;
+  margin: 24px 0 14px;
+  padding: 32px 36px 28px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 4px;
+  background:
+    linear-gradient(180deg, rgba(58, 255, 157, 0.04), transparent 50%),
+    var(--sl-color-bg);
+  overflow: hidden;
+}
+.fs-hud::before {
+  /* corner crosshair grid background */
+  content: "";
+  position: absolute;
+  inset: 0;
+  background-image:
+    linear-gradient(to right, rgba(58, 255, 157, 0.05) 1px, transparent 1px),
+    linear-gradient(to bottom, rgba(58, 255, 157, 0.05) 1px, transparent 1px);
+  background-size: 32px 32px;
+  pointer-events: none;
+  opacity: 0.4;
+}
+.fs-hud-corner {
+  position: absolute;
+  width: 18px; height: 18px;
+  border: 1.5px solid var(--fs-accent);
+  pointer-events: none;
+}
+.fs-hud-corner.tl { top: 8px; left: 8px; border-right: none; border-bottom: none; }
+.fs-hud-corner.tr { top: 8px; right: 8px; border-left: none; border-bottom: none; }
+.fs-hud-corner.bl { bottom: 8px; left: 8px; border-right: none; border-top: none; }
+.fs-hud-corner.br { bottom: 8px; right: 8px; border-left: none; border-top: none; }
+.fs-hud-body {
+  position: relative;
+  z-index: 1;
+}
+.fs-hud-eyebrow {
+  font-family: var(--sl-font-mono);
+  font-size: 11.5px;
+  letter-spacing: 0.18em;
+  color: var(--fs-accent);
+  margin-bottom: 10px;
+  font-weight: 600;
+}
+.fs-hud-title {
+  margin: 0 0 10px 0 !important;
+  font-size: 32px !important;
+  font-weight: 700 !important;
+  letter-spacing: -0.01em !important;
+  color: var(--sl-color-white) !important;
+  border: none !important;
+  padding: 0 !important;
+}
+.fs-hud-sub {
+  margin: 0;
+  font-size: 15px;
+  color: var(--sl-color-gray-2);
+  max-width: 56ch;
+  line-height: 1.55;
+}
+.fs-hud-sub code {
+  font-size: 13px;
+  padding: 1px 6px;
+  border-radius: 3px;
+  background: var(--sl-color-gray-7);
+  color: var(--fs-accent);
+}
+
+/* Lightbulb glow variant */
+.fs-hud-glow {
+  background:
+    radial-gradient(circle at 70% 30%, rgba(58, 255, 157, 0.10), transparent 50%),
+    linear-gradient(180deg, rgba(58, 255, 157, 0.06), transparent 60%),
+    var(--sl-color-bg);
+  box-shadow:
+    inset 0 0 60px rgba(58, 255, 157, 0.05),
+    0 0 0 1px color-mix(in oklab, var(--fs-accent) 15%, transparent);
+}
+.fs-hud-glow .fs-hud-corner {
+  border-color: color-mix(in oklab, var(--fs-accent) 80%, white);
+  box-shadow: 0 0 8px color-mix(in oklab, var(--fs-accent) 50%, transparent);
+}
+
+/* ---------- 37. STATUS STRIP (5 cells under HUD) ---------- */
+.fs-strip {
+  display: grid;
+  grid-template-columns: repeat(5, 1fr);
+  gap: 0;
+  margin: 0 0 28px;
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 4px;
+  overflow: hidden;
+  font-family: var(--sl-font-mono);
+  background: var(--sl-color-gray-7);
+}
+.fs-strip-cell {
+  display: flex; flex-direction: column; gap: 3px;
+  padding: 10px 14px;
+  border-right: 1px solid var(--sl-color-hairline);
+}
+.fs-strip-cell:last-child {
+  border-right: none;
+}
+.fs-strip-cell b {
+  font-size: 10px;
+  letter-spacing: 0.14em;
+  color: var(--sl-color-gray-3);
+  text-transform: uppercase;
+  font-weight: 600;
+}
+.fs-strip-cell span {
+  font-size: 13px;
+  color: var(--sl-color-white);
+  font-weight: 500;
+}
+.fs-strip-end span {
+  color: var(--fs-accent);
+}
+@media (max-width: 800px) {
+  .fs-strip { grid-template-columns: repeat(2, 1fr); }
+  .fs-strip-cell:nth-child(2n) { border-right: none; }
+  .fs-strip-cell { border-bottom: 1px solid var(--sl-color-hairline); }
+  .fs-strip-cell:nth-last-child(-n+2) { border-bottom: none; }
+}
+
+/* ---------- 38. CHAIN DISPLAY (lightbulb page) ---------- */
+.fs-chain-display {
+  margin: 28px 0;
+  padding: 22px 18px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 8px;
+  background: var(--sl-color-bg);
+  display: flex;
+  align-items: stretch;
+  gap: 8px;
+  overflow-x: auto;
+  font-family: var(--sl-font-mono);
+}
+.fs-chain-stage {
+  flex: 1 1 0;
+  min-width: 130px;
+  display: flex; flex-direction: column; gap: 4px;
+  padding: 12px 14px;
+  background: var(--sl-color-gray-7);
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 5px;
+  position: relative;
+}
+.fs-chain-stage .fs-chain-num {
+  font-size: 10px;
+  letter-spacing: 0.16em;
+  color: var(--sl-color-gray-4);
+  font-weight: 600;
+}
+.fs-chain-stage b {
+  font-size: 14px;
+  color: var(--sl-color-white);
+  font-weight: 600;
+}
+.fs-chain-stage span:not(.fs-chain-num) {
+  font-size: 11.5px;
+  color: var(--sl-color-gray-3);
+}
+.fs-chain-stage-keystone {
+  border-color: color-mix(in oklab, var(--fs-accent) 50%, var(--sl-color-hairline));
+  background: color-mix(in oklab, var(--fs-accent) 6%, var(--sl-color-gray-7));
+  box-shadow: 0 0 0 1px color-mix(in oklab, var(--fs-accent) 25%, transparent) inset;
+}
+.fs-chain-stage-keystone b { color: var(--fs-accent); }
+.fs-chain-display .fs-arr {
+  align-self: center;
+  width: 22px; height: 14px;
+  position: relative;
+  flex-shrink: 0;
+}
+.fs-chain-display .fs-arr::before {
+  content: "";
+  position: absolute;
+  top: 50%; left: 0; right: 6px;
+  height: 1px;
+  background: var(--sl-color-gray-3);
+  transform: translateY(-50%);
+}
+.fs-chain-display .fs-arr::after {
+  content: "";
+  position: absolute;
+  top: 50%; right: 0;
+  width: 0; height: 0;
+  border-left: 6px solid var(--sl-color-gray-3);
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  transform: translateY(-50%);
+}
+
+/* ---------- 39. CARRIER/CARGO STACK (lightbulb page) ---------- */
+.fs-stack {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  margin: 24px 0 32px;
+  border: 1px solid var(--sl-color-hairline-light);
+  border-radius: 8px;
+  overflow: hidden;
+  font-family: var(--sl-font-mono);
+}
+.fs-stack-layer {
+  display: flex; flex-direction: column; gap: 6px;
+  padding: 18px 22px;
+}
+.fs-stack-layer b {
+  font-size: 11px;
+  letter-spacing: 0.18em;
+  font-weight: 700;
+}
+.fs-stack-layer span {
+  font-size: 13.5px;
+  line-height: 1.55;
+  color: var(--sl-color-white);
+}
+.fs-stack-layer code {
+  font-size: 12px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: rgba(255,255,255,0.06);
+}
+.fs-stack-cargo {
+  background: linear-gradient(180deg,
+    color-mix(in oklab, var(--fs-accent) 12%, var(--sl-color-bg)),
+    color-mix(in oklab, var(--fs-accent) 4%, var(--sl-color-bg)));
+  border-bottom: 1px solid var(--sl-color-hairline);
+}
+.fs-stack-cargo b { color: var(--fs-accent); }
+.fs-stack-carrier {
+  background: var(--sl-color-gray-7);
+}
+.fs-stack-carrier b { color: var(--sl-color-gray-3); }

From a5a25caa5bb4d658832b27af7e2f6f8508623504 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 16:54:23 -0500
Subject: [PATCH 07/19] Address Codex P1/P2 review on PR #39
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Triaged 23 findings; fixed the real ones, flagged the false positives.

WAVE 1 — code bugs (P1/P2):
- PageActions.astro: build mdRelative with import.meta.env.BASE_URL so URLs
  survive on /fsuite/ subpath (was stripped by new URL() relative-resolve);
  client script just prepends window.location.origin now (fixes Codex P1)
- PageActions.astro: ghSourcePath now uses entry.filePath to preserve actual
  file extension — was hardcoded `.mdx` and 404'd on the 14 .md command pages
  + episode-0.md + the 4 architecture .md pages (fixes Codex P2)

WAVE 1 — accessibility/CSS:
- custom.css: html now defaults color-scheme: dark with [data-theme='light']
  override, so light theme doesn't get forced-dark native UA controls
- custom.css: added @media (prefers-reduced-motion: reduce) at the end —
  honours user motion preference, neutralizes page-actions menu fade-in and
  any future keyframe decoration
- custom.css: replaced .fs-strip-cell:nth-last-child(-n+2) mobile rule with
  conditional :nth-last-child(1) + :nth-last-child(2):nth-child(odd) so a
  5-cell layout doesn't lose the row-2/row-3 separator

WAVE 2 — doc accuracy:
- chains.md: split contradictory "Non-pipe tools" section. fread/fedit are
  now correctly classified as stdin-capable consumers; ftree/fprobe/fcase/
  freplay/fmetrics are arg-only endpoints
- hooks.md: removed 8 leftover \\{ \\} backslash escapes from JSON example
  block — was invalid JSON, copy/paste broken
- telemetry.md: ``` → ```text on the storage-tree fence (markdownlint)
- fbash.md: corrected env-var-persistence claim — only cwd + fcase/session
  state persist between calls, not exported env vars; replaced misleading
  example accordingly
- fcase.md: fread --around now targets a specific file (auth.py) instead of
  /project directory in the evidence-import example
- freplay.md: `freplay list -o json` → `freplay list auth-seam -o json` to
  match the documented `<case-slug>` requirement in the help block
- fsearch.md: explicit note that piping into fread requires `--from-stdin
  --stdin-format=paths`; the existing examples for fmap/fcontent unchanged
- ftree.md: replaced "doesn't pipe" with the accurate framing — ftree
  doesn't read from stdin (chain start, not middle filter), but does emit
  -o paths and -o json for downstream consumption
- first-contact.md: removed `| head -50` from ftree --snapshot example —
  it was truncating the JSON envelope mid-stream
- fwrite.md: relabeled "## Help output" → "## Usage notes" and clarified
  the block is the script header (set -euo pipefail visible) rather than
  runtime --help output, since fwrite's primary surface is MCP-side

WAVE 3 — cleanup:
- custom_backup.css deleted: orphan file, not loaded by Astro config

FALSE POSITIVES (verified, not fixed):
- "MCP doesn't register all 14 tools" (architecture/index.mdx + mcp.md):
  grep -nE 'server\.registerTool' mcp/index.js shows 14 distinct registrations
  for ftree/fmap/fread/fcontent/fsearch/fedit/fwrite/fcase/fmetrics/freplay/
  fprobe/fs/fls/fbash. Claim is accurate.
- "fs as pipe participant in index.mdx diagram": fs has fs-pn-entry styling
  and the undernote already explicitly states it auto-routes via fsearch +
  fcontent. Visual reposition is design-judgment, not a correctness bug.

DEFERRED:
- @import @first + lowercase keywords (stylelint, not runtime)
- Self-host Geist + JetBrains Mono fonts (bigger scope, separate effort)
- pages/[...slug].md.ts homepage slug normalization to '' (current behavior
  is consistent: /fsuite/index.md route exists and PageActions targets it
  after the BASE_URL fix)

Verified: all 16 spot-checked pages (homepage, architecture trio + index,
chains, cheatsheet, first-contact, 6 commands, 2 story) return 200; dev
log clean since 16:35 fresh-start.
---
 site/src/components/PageActions.astro         | 30 ++++++++-------
 site/src/content/docs/architecture/chains.md  |  4 +-
 site/src/content/docs/architecture/hooks.md   | 16 ++++----
 .../content/docs/architecture/telemetry.md    |  2 +-
 site/src/content/docs/commands/fbash.md       |  8 ++--
 site/src/content/docs/commands/fcase.md       |  2 +-
 site/src/content/docs/commands/freplay.md     |  4 +-
 site/src/content/docs/commands/fsearch.md     |  2 +-
 site/src/content/docs/commands/ftree.md       |  2 +-
 site/src/content/docs/commands/fwrite.md      |  4 +-
 .../docs/getting-started/first-contact.md     |  2 +-
 site/src/styles/custom.css                    | 23 ++++++++++-
 site/src/styles/custom_backup.css             | 38 -------------------
 13 files changed, 62 insertions(+), 75 deletions(-)
 delete mode 100644 site/src/styles/custom_backup.css

diff --git a/site/src/components/PageActions.astro b/site/src/components/PageActions.astro
index 6f935cd..dec8a08 100644
--- a/site/src/components/PageActions.astro
+++ b/site/src/components/PageActions.astro
@@ -27,15 +27,19 @@ const entry = route?.entry;
 const slug = entry?.id?.replace(/\.(md|mdx)$/i, '') ?? '';
 const title = entry?.data?.title ?? '';
 
-// Build URLs using the runtime origin so it works on lliwcwill.github.io,
-// localhost:4321, or any preview deployment.
-// We emit a relative `.md` URL so the script can resolve against window.location.
-const mdRelative = slug ? `/${slug}.md` : '';
-
-// GitHub source URL — assumes master branch + the canonical path layout.
-// If the entry is `index.mdx`, the slug is empty; map back to the file.
+// Build URLs using Astro's BASE_URL (e.g., "/fsuite/") so they survive on
+// GitHub Pages-style deployments under a subpath. We emit the full path-with-base
+// so the script just needs to prepend window.location.origin.
+const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/$/, ''); // "/fsuite" or ""
+const mdRelative = slug ? `${baseUrl}/${slug}.md` : '';
+
+// GitHub source URL — preserve the actual file extension since the docs tree
+// mixes .md and .mdx and a hardcoded .mdx 404s for .md files. Astro's
+// entry.filePath keeps the extension; entry.id has it stripped by Starlight.
 const ghBase = 'https://github.com/lliWcWill/fsuite/blob/master/site/src/content/docs';
-const ghSourcePath = slug ? `${slug}.mdx` : 'index.mdx';
+const fileExtMatch = (entry as any)?.filePath?.match(/\.(md|mdx)$/i);
+const fileExt = fileExtMatch ? fileExtMatch[1].toLowerCase() : 'mdx';
+const ghSourcePath = slug ? `${slug}.${fileExt}` : `index.${fileExt}`;
 const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
 ---
 
@@ -180,13 +184,13 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
     };
 
     const buildMdUrl = (): string => {
-      // Resolve the relative .md path against the current origin + base path.
-      // window.location.pathname is e.g. /fsuite/architecture/mcp/ — strip
-      // trailing slash and append .md (or use the slug-based mdRelative).
+      // mdRelative already includes Astro's BASE_URL (e.g., "/fsuite/foo.md"),
+      // so we only need to prepend the runtime origin. Avoids the new-URL()
+      // base-path-stripping pitfall when mdRelative starts with "/".
       if (mdRelative) {
-        return new URL(mdRelative, window.location.origin + (window.location.pathname.split('/')[1] ? `/${window.location.pathname.split('/')[1]}` : '')).toString();
+        return `${window.location.origin}${mdRelative}`;
       }
-      // Fallback: derive from current pathname.
+      // Fallback: derive from current pathname (already includes base).
       const path = window.location.pathname.replace(/\/$/, '');
       return `${window.location.origin}${path}.md`;
     };
diff --git a/site/src/content/docs/architecture/chains.md b/site/src/content/docs/architecture/chains.md
index c23a8bc..2983bed 100644
--- a/site/src/content/docs/architecture/chains.md
+++ b/site/src/content/docs/architecture/chains.md
@@ -30,9 +30,9 @@ The rule: **producers** output paths, **consumers** read paths from stdin.
 | `fread` | `--from-stdin --stdin-format=paths` | up to `--max-files` |
 | `fedit` | `--targets-file -` | batch patches |
 
-### Non-pipe tools (arg-based)
+### Arg-only endpoints (chain termini)
 
-`fread`, `fedit`, `ftree`, `fprobe`, `fcase`, `freplay`, `fmetrics` take arguments, not stdin pipe lists. They sit at chain endpoints, not in the middle.
+`ftree`, `fprobe`, `fcase`, `freplay`, `fmetrics` take arguments only — they don't accept piped path lists, so they sit at chain endpoints, not in the middle. The stdin-capable consumers above (`fcontent`, `fmap`, `fread`, `fedit`) can be in the middle of a chain *or* at an endpoint depending on whether you feed them stdin.
 
 <div class="fs-mcp-note">
   <h4>⚠ MCP CALLERS — SEQUENTIAL LIMIT</h4>
diff --git a/site/src/content/docs/architecture/hooks.md b/site/src/content/docs/architecture/hooks.md
index 45d8900..aed1d8b 100644
--- a/site/src/content/docs/architecture/hooks.md
+++ b/site/src/content/docs/architecture/hooks.md
@@ -35,21 +35,21 @@ The hook does not need to know anything about fsuite. It just needs to refuse th
 Add to `~/.claude/settings.json`:
 
 ```json
-\{
-  "hooks": \{
+{
+  "hooks": {
     "PreToolUse": [
-      \{
+      {
         "matcher": "Read",
         "hooks": [
-          \{
+          {
             "type": "command",
             "command": "echo 'Use fsuite fread instead of native Read. Use fsuite structured reads with symbol/range control. Example: fread --symbol NAME path' >&2; exit 2"
-          \}
+          }
         ]
-      \}
+      }
     ]
-  \}
-\}
+  }
+}
 ```
 
 Apply the same pattern to `Write`, `Edit`, `Grep`, and `Glob`:
diff --git a/site/src/content/docs/architecture/telemetry.md b/site/src/content/docs/architecture/telemetry.md
index 7ccea1b..4af04f4 100644
--- a/site/src/content/docs/architecture/telemetry.md
+++ b/site/src/content/docs/architecture/telemetry.md
@@ -101,7 +101,7 @@ Flag values aren't analytical signal; flag *presence* is. Sanitizing values prot
 
 ## Storage shape
 
-```
+```text
 ~/.fsuite/
 ├── telemetry.jsonl          ← append-only event log (raw)
 ├── telemetry.db             ← SQLite (built by fmetrics import)
diff --git a/site/src/content/docs/commands/fbash.md b/site/src/content/docs/commands/fbash.md
index 5065cf2..5ce1dc1 100644
--- a/site/src/content/docs/commands/fbash.md
+++ b/site/src/content/docs/commands/fbash.md
@@ -22,7 +22,7 @@ sidebar:
   </div>
 </div>
 
-`fbash` is `bash` with the same agent-aware budget discipline as the rest of fsuite. Output is capped, classified (stdout vs stderr vs status), and session state persists between calls so you can `cd`, set environment variables, and chain commands across invocations.
+`fbash` is `bash` with the same agent-aware budget discipline as the rest of fsuite. Output is capped, classified (stdout vs stderr vs status), and the working directory + fcase/session state persist between calls. Note: exported environment variables do **not** persist across `fbash` invocations — each call starts a fresh shell with `cd` restored.
 
 **The MCP escape hatch.** If you're calling fsuite tools through the MCP server, every call is sequential — MCP doesn't pipe. But `fbash` runs a real shell, which means real Unix pipes work inside it. Wrap your chain in one `fbash` call and get full pipeline speed back, even from MCP-only agents.
 
@@ -37,9 +37,9 @@ fbash "fsearch -o paths '*.py' src \
        | fcontent -o paths 'class' \
        | fmap -o json"
 
-# Stateful session — cd persists to the next call
-fbash "cd /project && export DEBUG=1"
-fbash "pwd && env | grep DEBUG"
+# Stateful session — cd persists to the next call (env vars do not)
+fbash "cd /project"
+fbash "pwd"   # → /project (cd was preserved)
 
 # Long-running with cap
 fbash "find / -name '*.log' 2>/dev/null"   # output capped automatically
diff --git a/site/src/content/docs/commands/fcase.md b/site/src/content/docs/commands/fcase.md
index 8cff9a9..08f74c4 100644
--- a/site/src/content/docs/commands/fcase.md
+++ b/site/src/content/docs/commands/fcase.md
@@ -47,7 +47,7 @@ fcase target add auth-seam \
 fmap -o json /project | fcase target import auth-seam
 
 # Import evidence from fread
-fread -o json /project --around "def auth" -A 20 \
+fread -o json /project/src/auth.py --around "def auth" -A 20 \
   | fcase evidence import auth-seam
 
 # Track and reject hypotheses
diff --git a/site/src/content/docs/commands/freplay.md b/site/src/content/docs/commands/freplay.md
index ae4bacd..f1c9bbe 100644
--- a/site/src/content/docs/commands/freplay.md
+++ b/site/src/content/docs/commands/freplay.md
@@ -41,8 +41,8 @@ freplay record auth-seam \
 freplay show auth-seam
 freplay show auth-seam -o json
 
-# List cases that have a replay chain
-freplay list -o json
+# Show the recorded chain for a specific case
+freplay list auth-seam -o json
 ```
 
 ## Help output
diff --git a/site/src/content/docs/commands/fsearch.md b/site/src/content/docs/commands/fsearch.md
index 6cba1b4..2b56b4a 100644
--- a/site/src/content/docs/commands/fsearch.md
+++ b/site/src/content/docs/commands/fsearch.md
@@ -22,7 +22,7 @@ sidebar:
   </div>
 </div>
 
-`fsearch` finds files by name or glob. It's the pipe currency producer — `-o paths` gives you one file path per line, ready to feed `fmap`, `fcontent`, or `fread`. Auto-detects `fd` for speed and falls back to `find`.
+`fsearch` finds files by name or glob. It's the pipe currency producer — `-o paths` gives you one file path per line, ready to feed `fmap` or `fcontent` directly. To pipe into `fread`, use `fread --from-stdin --stdin-format=paths` since `fread` takes paths from stdin only when those flags are set. Auto-detects `fd` for speed and falls back to `find`.
 
 Bare words auto-expand: `fsearch log /var/log` becomes `*.log`. Use this when you know what file pattern you want; use `fcontent` when you know what's inside the file but not its name.
 
diff --git a/site/src/content/docs/commands/ftree.md b/site/src/content/docs/commands/ftree.md
index 4c5a8ae..e613f58 100644
--- a/site/src/content/docs/commands/ftree.md
+++ b/site/src/content/docs/commands/ftree.md
@@ -28,7 +28,7 @@ Use it once at the start of every investigation. Use `--snapshot` when you want
 
 ## Canonical chains
 
-`ftree` doesn't pipe (its output is a tree, not a list of paths) — it sits at the start of a chain to give context, then you act on what it shows.
+`ftree` doesn't read from stdin — it's a chain start that gives context, not a middle filter. But it does emit machine-readable output via `-o paths` and `-o json` for downstream consumption.
 
 ```bash
 # Default scout — 3-level tree, sensible excludes
diff --git a/site/src/content/docs/commands/fwrite.md b/site/src/content/docs/commands/fwrite.md
index 03327e7..0c2e0d0 100644
--- a/site/src/content/docs/commands/fwrite.md
+++ b/site/src/content/docs/commands/fwrite.md
@@ -31,9 +31,9 @@ sidebar:
 
 `fedit` has analogous functionality (`fedit --create`, `fedit --replace-file`) for CLI users without MCP — but if you're already on the MCP transport, `fwrite` is one call instead of two flags.
 
-## Help output
+## Usage notes
 
-The content below is the **live** `--help` output of `fwrite`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
+The block below is the script header from the `fwrite` source — usage, flags, and exit codes documented inline. (Unlike most fsuite tools, `fwrite`'s primary surface is the MCP tool definition, not a `--help` flag, so this section captures the script comments rather than runtime help text.)
 
 ```text
 # modifications. This is the "create" counterpart to fedit's "modify."
diff --git a/site/src/content/docs/getting-started/first-contact.md b/site/src/content/docs/getting-started/first-contact.md
index 5f9193c..07f5865 100644
--- a/site/src/content/docs/getting-started/first-contact.md
+++ b/site/src/content/docs/getting-started/first-contact.md
@@ -32,7 +32,7 @@ fsuite
 
 ```bash
 cd /path/to/any/project
-ftree --snapshot -o json . | head -50
+ftree --snapshot -o json .
 ```
 
 `ftree` returns the full tree AND recon data (sizes, types, flags) in one call. Note how it caps output automatically — no 10,000-line floods. The `--snapshot` mode is what you want for an agent's "first look" because it gets the recon inventory plus the tree excerpt in a single envelope.
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index b61f2ba..012e39a 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -95,9 +95,13 @@
 
 /* ---------- 3. BASE TYPOGRAPHY ---------- */
 html {
+  /* Default to dark for the CAVE theme; light theme override below. */
   color-scheme: dark;
   font-family: var(--sl-font);
 }
+[data-theme='light'] {
+  color-scheme: light;
+}
 body {
   font-family: var(--sl-font);
   -webkit-font-smoothing: antialiased;
@@ -1608,7 +1612,8 @@ starlight-tabs [role="tab"][aria-selected="true"] {
   .fs-strip { grid-template-columns: repeat(2, 1fr); }
   .fs-strip-cell:nth-child(2n) { border-right: none; }
   .fs-strip-cell { border-bottom: 1px solid var(--sl-color-hairline); }
-  .fs-strip-cell:nth-last-child(-n+2) { border-bottom: none; }
+  .fs-strip-cell:nth-last-child(1) { border-bottom: none; }
+  .fs-strip-cell:nth-last-child(2):nth-child(odd) { border-bottom: none; }
 }
 
 /* ---------- 38. CHAIN DISPLAY (lightbulb page) ---------- */
@@ -1722,3 +1727,19 @@ starlight-tabs [role="tab"][aria-selected="true"] {
   background: var(--sl-color-gray-7);
 }
 .fs-stack-carrier b { color: var(--sl-color-gray-3); }
+
+/* ---------- 39. ACCESSIBILITY: REDUCED-MOTION FALLBACK ---------- */
+/* Honour the user's motion preference (System Settings → Accessibility →
+   Reduce Motion). Disables non-essential animations + transitions across the
+   site so motion-sensitive users don't get the page-actions menu fade-in,
+   strip pulse, or any future keyframe-driven decoration. */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
diff --git a/site/src/styles/custom_backup.css b/site/src/styles/custom_backup.css
deleted file mode 100644
index c972787..0000000
--- a/site/src/styles/custom_backup.css
+++ /dev/null
@@ -1,38 +0,0 @@
-/* fsuite docs — custom theme tweaks to match the Monokai vibe of the MCP output */
-
-:root {
-  /* Dark theme override — Monokai-ish accent */
-  --sl-color-accent-low: #3b2a1a;
-  --sl-color-accent: #fd971f;
-  --sl-color-accent-high: #ffd866;
-
-  --sl-color-white: #f8f8f2;
-  --sl-color-gray-1: #e1e1db;
-  --sl-color-gray-2: #c5c5c0;
-  --sl-color-gray-3: #75715e;
-  --sl-color-gray-4: #49483e;
-  --sl-color-gray-5: #383830;
-  --sl-color-gray-6: #272822;
-  --sl-color-black: #1e1f1c;
-}
-
-:root[data-theme='light'] {
-  --sl-color-accent-low: #fef3c7;
-  --sl-color-accent: #d97706;
-  --sl-color-accent-high: #92400e;
-}
-
-/* Make the inline code stand out like terminal output */
-code {
-  font-weight: 500;
-}
-
-/* Terminal-y feel for block quotes (callouts) */
-blockquote {
-  border-left-color: var(--sl-color-accent);
-}
-
-/* Tighten the command-reference tables */
-table {
-  font-size: 0.92em;
-}

From bc2afd309751569442ab38fde19bd765459695fd Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:02:02 -0500
Subject: [PATCH 08/19] docs(internal): add PR #39 handoff for next agent

Continuation handoff for the docs/site-revamp branch:
- Where we are (rounds 1-6 + Codex triage all landed, PR #39 mergeable)
- What's next (CD's R6.5 mdx rules deliverable, then R7 visitor walkthrough)
- CD partnership pattern explained
- MDX strict-mode lessons compendium (round 2-6 hard-won knowledge)
- Dev environment + how to recover from common breakage modes
- Open questions and deferred items

Lives next to other date-stamped specs in docs/internal/specs/.
---
 .../internal/specs/2026-04-29-pr39-handoff.md | 255 ++++++++++++++++++
 1 file changed, 255 insertions(+)
 create mode 100644 docs/internal/specs/2026-04-29-pr39-handoff.md

diff --git a/docs/internal/specs/2026-04-29-pr39-handoff.md b/docs/internal/specs/2026-04-29-pr39-handoff.md
new file mode 100644
index 0000000..541c796
--- /dev/null
+++ b/docs/internal/specs/2026-04-29-pr39-handoff.md
@@ -0,0 +1,255 @@
+# PR #39 Handoff — Docs Site Revamp (Rounds 1-6)
+
+**Date:** 2026-04-29
+**Author:** previous Claude Code session
+**Audience:** next agent picking up the docs work
+
+---
+
+## TL;DR
+
+PR #39 is open, mergeable, CI green, CodeRabbit green. All 6 docs rounds + the Codex P1/P2 triage are landed. Two clear next steps:
+
+1. **Round 6.5** — Claude Design (CD) is shipping `mdx-strict-mode-rules.md` as a small standalone deliverable. Just integrate it under `docs/internal/specs/` when it arrives.
+2. **Round 7** — visitor walkthrough on the open PR branch. Output is a prioritized issue list per page, NOT a generated zip. CD is waiting for the green light.
+
+The dev server is running on this machine. Your job is mostly: finish round 7, absorb whatever CD ships for 6.5, push final fixes to PR #39, ping the human when ready to merge.
+
+---
+
+## Where we are right now
+
+### Git state
+- **Branch:** `docs/site-revamp` (you're on it)
+- **HEAD:** `a5a25ca Address Codex P1/P2 review on PR #39`
+- **Origin:** in sync, pushed
+- **Master tip:** `c745101` (PR #39 forks from there, six commits ahead)
+
+### Branch contents (commits on `docs/site-revamp` not on `master`):
+
+| SHA | Round | What it added |
+|-----|-------|--------------|
+| `20c7159` | R1 | CAVE theme + per-page Copy/Open-in-LLM dropdown (`PageActions.astro`, `PageTitle.astro`, `[...slug].md.ts`) |
+| `05a3d51` | R2 | Keystone-emphasis chain diagram, native-vs-fsuite block, drone sensor hero |
+| `aa17ce4` | R3 | Monokai terminal blocks, full agent-scrapeable `cheatsheet.mdx`, MCP-sequential note |
+| `9e492d6` | R4 | 14 per-command drone profile preambles |
+| `c4d7128` | R5 | `architecture/index.mdx` (NEW), MCP/Hooks/Telemetry rebuilt, delivery flow CSS |
+| `36053d5` | R6 | Story-page HUD rebuild (Episodes 1/2/3 + Lightbulb) |
+| `a5a25ca` | — | Codex P1/P2 review triage (15 fixes, 2 false positives flagged, 4 deferred) |
+
+### PR #39
+- URL: https://github.com/lliWcWill/fsuite/pull/39
+- State: OPEN, MERGEABLE
+- Checks: `test-suite` SUCCESS, `CodeRabbit` SUCCESS
+
+### Sister branch — `codex/fread-media-pdf-image` (PR #38)
+- This is the media-reading feature branch, **not yours**
+- Last cleaned to drop the docs commits (was polluting feature scope)
+- Tip is `dceb006 fix: align media MCP caps with full mode`
+- If the human asks about media reading, that's where it lives
+
+---
+
+## Dev environment
+
+### Server is already running
+- Astro dev server on `http://localhost:4321/fsuite/`
+- PID: `pgrep -af "astro dev"` to find it
+- Log: `/tmp/fsuite-site-dev.log`
+- Started detached via `setsid nohup npm run dev > /tmp/fsuite-site-dev.log 2>&1 < /dev/null &` from `site/`
+
+### If the server breaks
+1. **Stale content cache** (most common): `rm -rf site/.astro && touch <file>` to force re-scan
+2. **Hung after rapid branch switches:** `kill <PIDs>` then re-launch with the same setsid command (don't run npm in foreground — long-running command will time out)
+3. **404 on a real file:** Starlight's `starlight-docs-loader` caches per-file YAML/MDX parse failures. Edit + save the file again to force a reload, OR `touch` it.
+
+### Verify pages render
+```bash
+for url in / architecture/ architecture/chains/ reference/cheatsheet/ getting-started/first-contact/ commands/fmap/ story/episode-1/ story/lightbulb/ ; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:4321/fsuite$url")
+  echo "  $code  $url"
+done
+```
+
+---
+
+## What's next (in priority order)
+
+### 1. Round 6.5 — CD's `mdx-strict-mode-rules.md`
+
+**Status:** CD greenlit, agent is waiting for delivery.
+
+**What it is:** Single standalone file for `docs/internal/specs/mdx-strict-mode-rules.md`. Contains the 4 MDX `<pre>` rules + YAML frontmatter colon rule + dev-server caching gotchas. Audience is FUTURE BUILDERS (any agent extending the site), not visitors.
+
+**When it arrives** (probably as a zip in `~/Downloads/round6.5.zip` or similar):
+1. Unzip
+2. Read README
+3. `cp` into target path (or `fwrite` if rewriting)
+4. Verify dev server doesn't break (it's docs-internal, not in the site collection, so it shouldn't)
+5. Commit + push to `docs/site-revamp`
+6. Update PR #39 description if needed
+
+**Why standalone, not folded into round 7:** different audiences. R7 = visitor review. R6.5 = engineering rule reference. CD argued this convincingly; honor the split.
+
+### 2. Round 7 — visitor walkthrough
+
+**Status:** ready to start. CD is waiting for ping. Walk on the OPEN PR BRANCH (current state).
+
+**The brief from CD (verbatim):**
+> Read the site front-to-back as a brand-new visitor with no prior context, flag broken handoffs, redundant content, missing bridges, dead links, voice/tone drift between pages, and pacing problems. Output should be a prioritized issue list per page + a top-line "what to fix first" recommendation, not a generated zip — that comes after we know what needs fixing.
+
+**Suggested route to walk** (matches first-time-visitor flow):
+1. `/` (homepage) — does the hero land? Does the chain diagram make sense?
+2. `/getting-started/installation/` — can someone install in <2 min?
+3. `/getting-started/mental-model/` — does the keystone framing click?
+4. `/getting-started/first-contact/` — does the ftree sample feel like a "first 30 seconds" moment?
+5. `/reference/cheatsheet/` — is it scannable as a reference?
+6. `/commands/fs/` → walk through a few command pages (fmap is the keystone, fbash is the MCP escape hatch — those are the two most important)
+7. `/architecture/` → `/architecture/chains/` → `/architecture/mcp/` → `/architecture/hooks/` → `/architecture/telemetry/`
+8. `/story/episode-0/` → `/episode-1/` → `/episode-2/` → `/episode-3/` → `/lightbulb/`
+
+**Output format** (prioritized, per page):
+- 🔴 Blocker (broken link, factual error, page that 404s)
+- 🟠 Major (confusing handoff, redundant with another page, missing bridge)
+- 🟡 Minor (voice/tone drift, pacing, polish)
+- ⚪ Nit (typo, formatting)
+
+**Top-line recommendation:** "If we only fix one thing, fix X."
+
+### 3. After R7 — absorb feedback into PR #39
+
+Reviewer (the human) decides whether to:
+- Amend on `docs/site-revamp` (keep PR clean, one squash) — preferred for polish
+- Open follow-up issue (if walk surfaces big rework) — only for fundamental rethinks
+
+---
+
+## CD partnership context
+
+**Claude Design (CD)** is an external design/content partner — a separate Claude conversation operated by the human, with its own session context. CD ships visual + content deliverables as zip files (delivered via `~/Downloads/round<N>.zip`). Each zip contains:
+- `README.md` with explicit integration prompts
+- `custom-components-r<N>.css` (sometimes — CSS appendix)
+- `site-pages/*.mdx` and `*.md` (page content)
+
+**Your job vs CD's job:**
+- CD = generates the deliverable (visual design, content writing, copy)
+- You = integrate it (apply files, fix MDX strict-mode landmines, verify renders, commit, push)
+
+CD has a generation discipline. As of now, CD knows about and pre-applies these rules:
+- YAML frontmatter description with `: `, `#`, `[`, `>`, `|`, `&`, `*` → quote it
+- Bare `{` `}` inside `<pre>` → escape as `\{` `\}` or `&#123;` `&#125;`
+- Blank lines inside `<pre>` → use `<span class="tk-mut">·</span>` separator
+- `<pre>` and `</pre>` → on their own lines (don't put content on same line as opener)
+- Indentation inside `<pre>` → use `&nbsp;` × N or lead-glyphs (`·`/`└`), never literal 4+ spaces
+- `*` literals inside `<pre>` → quote (`"\*.ts"`) or escape (`&#42;`)
+
+**Communication pattern:** the human pastes CD's reply into the conversation. You draft replies for the human to paste back. Treat CD as a peer collaborator with their own context — don't assume they know what's on your machine.
+
+---
+
+## Lessons learned (durable, may not be in CD's spec)
+
+### MDX strict-mode breakage modes (compendium)
+
+These caused 500s during rounds 2-6:
+
+| Trigger | Symptom | Fix |
+|---|---|---|
+| Bare `{` `}` in `<pre>` | "Could not parse expression with acorn" / "Unexpected content after expression" | `\{` `\}` or `&#123;` `&#125;` |
+| Blank line inside `<pre>` | "Expected a closing tag for `<pre>` before end of paragraph" | `<span class="tk-mut">·</span>` separator |
+| Paired `*` chars in `<pre>` (e.g. `*.ts` × 2) | "Expected closing tag `</span>` after end of `emphasis`" | `&#42;` or quote it |
+| 4+ leading spaces in `<pre>` | Same closing-tag-for-pre error | `&nbsp;` × N |
+| `<pre>` followed by `<span>` on same line | Same closing-tag error | Split `<pre>\n<span...` |
+| Unquoted `: ` in YAML frontmatter description | Starlight: "bad indentation of a mapping entry" | Quote the value |
+
+### Dev-server gotchas
+
+- Starlight's content collection caches parse failures per-file. After fixing, `touch` the file or restart server.
+- Switching branches mid-session can corrupt `.astro/content-modules.mjs` (it points at files that don't exist on the new branch). Fix: `rm -rf site/.astro && restart`.
+- `npm run dev` foregrounds for 10 minutes then dies (default Bash timeout). Always start detached: `setsid nohup npm run dev > /tmp/fsuite-site-dev.log 2>&1 < /dev/null &`.
+
+### Codex bot behavior on PR #39
+
+- Bot leaves both inline (line-anchored) and outside-diff comments.
+- Inline comments on PR #39: 21 findings, ~15 real, 2 false positives, 4 deferred.
+- False positives observed: claims about MCP tool registration count (verify with `grep -nE "server\.registerTool" mcp/index.js`).
+- When in doubt: read the actual code, then trust your eyes over Codex's wording.
+
+---
+
+## Open questions / pending decisions
+
+1. **Round 7 scope:** walk-now on `docs/site-revamp` branch (CD's preference) — but if you want to wait until merge, that's also fine. Same content, different process risk.
+2. **Stylelint @import order + lowercase keywords:** deferred from triage. If round 7 touches `custom.css` for any other reason, fold these in. Otherwise leave for a separate cleanup pass.
+3. **Self-host Geist + JetBrains Mono fonts:** deferred. Currently using Google Fonts CDN via `@import url(...)`. Privacy + offline-build improvement, but bigger scope. Don't tackle in PR #39.
+4. **`pages/[...slug].md.ts` homepage slug:** Codex suggested mapping `index` → `''`. Current `index` slug works fine after the F1 base-path fix; not blocking. Defer unless URL pattern matters for SEO/sharing.
+
+---
+
+## Files most relevant to your work
+
+```
+site/src/components/PageActions.astro          # the dropdown widget; URL-build logic just got fixed
+site/src/components/PageTitle.astro            # Starlight override that hosts PageActions
+site/src/pages/[...slug].md.ts                 # raw markdown endpoint (`/<slug>.md`)
+site/src/styles/custom.css                     # 1745-line CAVE theme + all components
+site/src/content/docs/                         # all the actual content
+site/astro.config.mjs                          # base: '/fsuite', sidebar config
+docs/internal/specs/                           # this handoff lives here; CD's R6.5 will too
+```
+
+---
+
+## How to verify everything works after your changes
+
+```bash
+# Set up
+cd /home/player3vsgpt/Desktop/Projects/fsuite
+git branch --show-current  # should be docs/site-revamp
+
+# Test pages
+sleep 2
+for url in / architecture/ architecture/chains/ reference/cheatsheet/ getting-started/first-contact/ commands/fmap/ commands/fbash/ story/episode-1/ story/lightbulb/ ; do
+  code=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:4321/fsuite$url")
+  echo "  $code  $url"
+done
+
+# Check log for errors since some timestamp
+awk '/14:5[5-9]:|15:|16:|17:/' /tmp/fsuite-site-dev.log | grep -ciE "MDXError|fail" || echo 0
+
+# When done — commit & push to update PR #39
+git add site/
+git commit -m "<your message>"
+git push origin docs/site-revamp
+```
+
+---
+
+## fcase trail
+
+For continuity, search the fcase ledger for prior decisions:
+
+```
+fcase find "site round" --deep --statuses all
+fcase find "pr39" --deep --statuses all
+fcase find "mdx" --deep --statuses all
+```
+
+Resolved cases worth knowing about:
+- `#523 site-round3-monokai`
+- `#524 site-round4-preambles`
+- `#525 site-round5-architecture`
+- `#526 site-round6-story-pages`
+- `#527 pr39-codex-triage`
+
+---
+
+## What I'd do first if I were you
+
+1. Verify dev server is up (`curl http://localhost:4321/fsuite/`).
+2. Glance at `git log --oneline -10` and `gh pr view 39` to confirm state.
+3. Check if CD's R6.5 zip has dropped in `~/Downloads/`. If yes, integrate first.
+4. If R6.5 is integrated (or not yet shipped), tell the human you're ready for round 7 walkthrough.
+5. Walk it. Output a prioritized issue list. Send it back.
+
+Good luck. The site is in really good shape — just polish from here.

From e5666795329b146e2da99f5c8faac61fe148effd Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:09:39 -0500
Subject: [PATCH 09/19] fix(gen-commands): preserve handcrafted preambles above
 '## Help output'
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex P1 finding (PR #39 thread lH6b): the existing buildPage() unconditionally
overwrote every site/src/content/docs/commands/<tool>.md on every `npm run
build` (build runs gen:commands && astro build). This wiped the round-4
preambles — drone-profile cards, canonical chains, monokai terminal samples
— from CI/deploy outputs. So the deployed site would show stripped-down
pages even though the dev server (which doesn't run gen:commands)
displayed the full preambles.

Fix: make gen-commands preservation-aware. If the page already exists, read
it, find the '## Help output' marker, keep everything above it, and splice
in the regenerated help section + see-also. The auto-generated bits stay
in sync with --help output; everything above is treated as durable
hand-edited content.

Verified locally: ran the script, fmap.md kept its 5 fs-drone class
occurrences, all section headings intact (tagline H2, Canonical chains,
Terminal sample, Help output, See also), page renders 200.
---
 site/scripts/gen-commands.mjs | 57 ++++++++++++++++++++++++-----------
 1 file changed, 39 insertions(+), 18 deletions(-)

diff --git a/site/scripts/gen-commands.mjs b/site/scripts/gen-commands.mjs
index f5db57d..fc2ebfc 100644
--- a/site/scripts/gen-commands.mjs
+++ b/site/scripts/gen-commands.mjs
@@ -10,7 +10,7 @@
  */
 
 import { execSync } from 'node:child_process';
-import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -65,24 +65,17 @@ function captureHelp(toolName) {
 
 /**
  * Build a markdown page for one tool.
+ *
+ * Preserves any handcrafted preamble above the `## Help output` heading
+ * (e.g. the round-4 drone-profile cards + canonical chains + monokai
+ * terminal samples). The auto-generated `## Help output` section + `## See
+ * also` are regenerated on every build so the help text stays in sync with
+ * the binary; everything above is treated as durable hand-edited content.
  */
-function buildPage(tool) {
+function buildPage(tool, outPath) {
   const helpText = captureHelp(tool.name);
-  const frontmatter = [
-    '---',
-    `title: ${tool.emoji} ${tool.title}`,
-    `description: ${tool.tagline}`,
-    `sidebar:`,
-    `  order: ${tool.order}`,
-    '---',
-  ].join('\n');
-
-  const body = `
-## ${tool.tagline}
 
-\`${tool.name}\` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
-
-## Help output
+  const helpSection = `## Help output
 
 The content below is the **live** \`--help\` output of \`${tool.name}\`, captured at build time from the tool binary itself. It cannot drift from the source — regenerating the docs regenerates this section.
 
@@ -97,7 +90,35 @@ ${helpText}
 - [View source on GitHub](https://github.com/lliWcWill/fsuite/blob/master/${tool.name})
 `;
 
-  return frontmatter + '\n' + body;
+  // If a page already exists, preserve everything above `## Help output`
+  // (frontmatter + tagline H2 + intro paragraph + any round-4 preamble) and
+  // splice the regenerated help + see-also onto the bottom.
+  if (existsSync(outPath)) {
+    const existing = readFileSync(outPath, 'utf8');
+    const helpIdx = existing.indexOf('## Help output');
+    if (helpIdx > 0) {
+      return existing.slice(0, helpIdx) + helpSection;
+    }
+  }
+
+  // First-time generation: build the default frontmatter + tagline H2 + intro
+  const frontmatter = [
+    '---',
+    `title: ${tool.emoji} ${tool.title}`,
+    `description: ${tool.tagline}`,
+    `sidebar:`,
+    `  order: ${tool.order}`,
+    '---',
+  ].join('\n');
+
+  const intro = `
+## ${tool.tagline}
+
+\`${tool.name}\` is part of the fsuite toolkit — a set of fourteen CLI tools built for AI coding agents.
+
+`;
+
+  return frontmatter + intro + helpSection;
 }
 
 /**
@@ -110,8 +131,8 @@ function main() {
 
   let written = 0;
   for (const tool of TOOLS) {
-    const page = buildPage(tool);
     const outPath = join(OUT_DIR, `${tool.name}.md`);
+    const page = buildPage(tool, outPath);
     writeFileSync(outPath, page, 'utf8');
     written++;
     console.log(`  ✓ ${tool.name.padEnd(10)} → src/content/docs/commands/${tool.name}.md`);

From 42ad05fb8d53192ee2b01e60079cedde0e60ec61 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:13:57 -0500
Subject: [PATCH 10/19] docs(handoff): record gen-commands fix + 2
 newly-reported visual bugs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- gen-commands.mjs preamble preservation landed in e566679 (was P1
  Codex finding lH6b; round-4 preambles were being wiped on every build)
- light theme broken in a deeper way than the kqPM color-scheme fix —
  only ~5 of ~30 Starlight tokens have light overrides, producing
  white-flood instead of a real inverse. Recommend force-dark-only
  unless the human wants to commit to a full light theme pass.
- page-navigation flicker between routes — likely missing ClientRouter
  + view transitions. Verify on production build before chasing.

PR #39 top-level comment also filed:
  https://github.com/lliWcWill/fsuite/pull/39#issuecomment-4347915103
---
 .../internal/specs/2026-04-29-pr39-handoff.md | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/docs/internal/specs/2026-04-29-pr39-handoff.md b/docs/internal/specs/2026-04-29-pr39-handoff.md
index 541c796..9471d8a 100644
--- a/docs/internal/specs/2026-04-29-pr39-handoff.md
+++ b/docs/internal/specs/2026-04-29-pr39-handoff.md
@@ -179,6 +179,39 @@ These caused 500s during rounds 2-6:
 
 ## Open questions / pending decisions
 
+
+## NEW BUGS (reported at end of session, not yet addressed)
+
+These surfaced after the Codex triage push and are filed in a top-level comment on PR #39 ([link](https://github.com/lliWcWill/fsuite/pull/39#issuecomment-4347915103)). Tackle in a follow-up PR after R6.5/R7 land.
+
+### A. Page-navigation flicker
+Every link click between pages briefly flashes white/empty before the next page paints. Wasn't there in earlier rounds. Likely candidates:
+- Astro view transitions not configured (need `<ClientRouter />` in `<head>`)
+- Dev-server-only artifact from Vite HMR + content collection rehydration
+- One of the new CSS animations (page-actions menu, HUD frame, status strip) re-running on every route change
+
+**Suggested first move:** reproduce on production build (`astro build && astro preview`) to confirm dev-only vs ships-to-deploy. If it ships, add `<ClientRouter transition:animate="none" />` to `PageTitle.astro` or the layout.
+
+### B. Light theme is broken (white-flood, not real inverse)
+With `[data-theme='light']` active, search boxes and selected areas render as solid white instead of properly themed light backgrounds.
+
+**Root cause** (verified):
+- The CAVE theme defines ALL `--sl-color-*` tokens in `:root` (lines 14-94 in `custom.css`) using dark values
+- The `[data-theme='light']` block (currently around lines 79-94 of `custom.css`) only overrides ~5 light-specific tokens (`--fs-bg-card`, `--fs-bg-card-hi`, `--fs-bg-card-on`, `--fs-scanline`)
+- The remaining ~30 Starlight tokens (`--sl-color-bg`, `--sl-color-text`, `--sl-color-hairline`, `--sl-color-bg-input`, etc.) stay at the dark `:root` values
+- Result: half-themed light mode where some surfaces are light, but inputs/selections/controls are still dark token references rendered against a light page → solid white blowout
+
+**Fix options:**
+1. Full light theme: extend `[data-theme='light']` with proper light overrides for all Starlight tokens (the painful but correct path)
+2. Force dark only: remove the theme toggle from Starlight config (`themes: 'dark'` or similar), add a small `prefers-color-scheme` polish, but kill the light option entirely. Honest given the site is CAVE-themed dark-first.
+
+**Recommendation:** option 2 (force dark) is faster, more honest, and matches the CAVE design language. Light theme on a deliberately-dark site is a "feature for completeness's sake" — only ship it if you can do it right. Discuss with the human before choosing.
+
+### gen-commands.mjs preamble preservation (already fixed)
+Codex thread `lH6b` flagged that `npm run build` (which runs `gen:commands && astro build`) was wiping the round-4 preambles. Verified + fixed in [`e566679`](https://github.com/lliWcWill/fsuite/commit/e566679): `buildPage()` now reads the existing file and splices the regenerated `## Help output` section onto the bottom, preserving everything above. Verified locally: `node site/scripts/gen-commands.mjs` re-ran without stripping the drone profile + canonical chains + monokai sample blocks.
+
+---
+
 1. **Round 7 scope:** walk-now on `docs/site-revamp` branch (CD's preference) — but if you want to wait until merge, that's also fine. Same content, different process risk.
 2. **Stylelint @import order + lowercase keywords:** deferred from triage. If round 7 touches `custom.css` for any other reason, fold these in. Otherwise leave for a separate cleanup pass.
 3. **Self-host Geist + JetBrains Mono fonts:** deferred. Currently using Google Fonts CDN via `@import url(...)`. Privacy + offline-build improvement, but bigger scope. Don't tackle in PR #39.

From f244d022d24dbad3eeb23502595915821355cf3a Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:22:10 -0500
Subject: [PATCH 11/19] fix(theme): complete light-theme Starlight token
 overrides

Codex P2 finding lXf8: the previous `:root[data-theme='light']` block only
overrode ~5 tokens (accent + fs-bg-card-* + scanline), leaving ~25 dark
Starlight tokens (--sl-color-bg, --sl-color-text, --sl-color-gray-1..7,
--sl-color-white/black, --sl-color-hairline*, --sl-color-bg-nav, etc.)
active in light mode. Result: white-flooded form controls + invisible text
on light surfaces.

Fix: full CAVE-themed light palette per Starlight's canonical
:root[data-theme='light'] pattern (verified via firecrawl scrape of
starlight.astro.build/guides/css-and-tailwind):
  - white/gray-1..7/black inverted (gray-1 = high-contrast text,
    gray-7 = lowest-contrast surface, black = #ffffff bg)
  - Background layers explicitly set to white/light (--sl-color-bg,
    --sl-color-bg-nav, --sl-color-bg-sidebar, --sl-color-bg-inline-code)
  - Text tokens explicitly set (--sl-color-text, --sl-color-text-accent,
    --sl-color-text-invert)
  - Hairlines retain CAVE green tint at light-bg-appropriate alpha
  - Accent darkened from #3aff9d (bioluminescent, unreadable on white) to
    #0a8c52 (deep forest green, AAA-ish contrast on #ffffff)

Verified all pages still 200 in dev. Production-mode toggle should now
render proper light theme instead of white-flood.
---
 site/src/styles/custom.css | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index 012e39a..2a4ad2e 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -75,13 +75,45 @@
   );
 }
 
-/* Light mode — keep it sane and on-brand */
+/* ---------- 2b. STARLIGHT TOKEN OVERRIDES (LIGHT) ---------- */
+/* Full CAVE-theme light palette: gray scale inverted, white/black flipped,
+   accent darkened for contrast on white. Mirrors Starlight's canonical
+   `:root[data-theme='light']` pattern from the official CSS guide
+   (starlight.astro.build/guides/css-and-tailwind). */
 :root[data-theme='light'] {
+  /* Accent — deep forest green readable on white */
   --sl-color-accent-low:  #d6f7e6;
   --sl-color-accent:      #0a8c52;
   --sl-color-accent-high: #064a2c;
-  --sl-color-text-invert: #ffffff;
 
+  /* White / gray scale / black — gray-1 is closest to text, gray-7 closest to bg */
+  --sl-color-white:   #0a1014;
+  --sl-color-gray-1:  #1c2a25;
+  --sl-color-gray-2:  #44544e;
+  --sl-color-gray-3:  #6b8079;
+  --sl-color-gray-4:  #9eb1a8;
+  --sl-color-gray-5:  #c9dad2;
+  --sl-color-gray-6:  #e8f4ee;
+  --sl-color-gray-7:  #f5fafa;
+  --sl-color-black:   #ffffff;
+
+  /* Background layers — light surfaces */
+  --sl-color-bg:           #ffffff;
+  --sl-color-bg-nav:       #f5fafa;
+  --sl-color-bg-sidebar:   #f5fafa;
+  --sl-color-bg-inline-code: #eef5f1;
+
+  /* Text */
+  --sl-color-text:         #0a1014;
+  --sl-color-text-accent:  #0a8c52;
+  --sl-color-text-invert:  #ffffff;
+
+  /* Hairlines — cave-green tint, proper alpha for light backgrounds */
+  --sl-color-hairline:        rgba(10, 60, 40, 0.10);
+  --sl-color-hairline-light:  rgba(10, 60, 40, 0.18);
+  --sl-color-hairline-shade:  rgba(10, 60, 40, 0.30);
+
+  /* Custom fsuite tokens — light mode versions */
   --fs-accent:       #0a8c52;
   --fs-accent-soft:  #0a8c52;
   --fs-accent-deep:  #d6f7e6;
@@ -90,6 +122,7 @@
   --fs-bg-card:    #ffffff;
   --fs-bg-card-hi: #f7faf8;
   --fs-bg-card-on: #eef5f1;
+
   --fs-scanline: none;
 }
 

From dca597aa1993e4e43274c7e592887890e26bea94 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:23:31 -0500
Subject: [PATCH 12/19] =?UTF-8?q?docs(handoff):=20light=20theme=20fixed=20?=
 =?UTF-8?q?in=20f244d02=20=E2=80=94=20strike=20from=20open-bugs=20list?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex thread lXf8 flagged the incomplete light-theme tokens (same bug
the user reported as 'white-flood'). Resolved with full Starlight
:root[data-theme='light'] block (verified via firecrawl scrape of
starlight.astro.build/guides/css-and-tailwind canonical pattern).

Updated handoff doc B section to reflect the fix. Page-nav flicker (A)
remains the only outstanding visual bug for follow-up.
---
 .../internal/specs/2026-04-29-pr39-handoff.md | 23 ++++++++-----------
 1 file changed, 9 insertions(+), 14 deletions(-)

diff --git a/docs/internal/specs/2026-04-29-pr39-handoff.md b/docs/internal/specs/2026-04-29-pr39-handoff.md
index 9471d8a..f39b933 100644
--- a/docs/internal/specs/2026-04-29-pr39-handoff.md
+++ b/docs/internal/specs/2026-04-29-pr39-handoff.md
@@ -192,20 +192,15 @@ Every link click between pages briefly flashes white/empty before the next page
 
 **Suggested first move:** reproduce on production build (`astro build && astro preview`) to confirm dev-only vs ships-to-deploy. If it ships, add `<ClientRouter transition:animate="none" />` to `PageTitle.astro` or the layout.
 
-### B. Light theme is broken (white-flood, not real inverse)
-With `[data-theme='light']` active, search boxes and selected areas render as solid white instead of properly themed light backgrounds.
-
-**Root cause** (verified):
-- The CAVE theme defines ALL `--sl-color-*` tokens in `:root` (lines 14-94 in `custom.css`) using dark values
-- The `[data-theme='light']` block (currently around lines 79-94 of `custom.css`) only overrides ~5 light-specific tokens (`--fs-bg-card`, `--fs-bg-card-hi`, `--fs-bg-card-on`, `--fs-scanline`)
-- The remaining ~30 Starlight tokens (`--sl-color-bg`, `--sl-color-text`, `--sl-color-hairline`, `--sl-color-bg-input`, etc.) stay at the dark `:root` values
-- Result: half-themed light mode where some surfaces are light, but inputs/selections/controls are still dark token references rendered against a light page → solid white blowout
-
-**Fix options:**
-1. Full light theme: extend `[data-theme='light']` with proper light overrides for all Starlight tokens (the painful but correct path)
-2. Force dark only: remove the theme toggle from Starlight config (`themes: 'dark'` or similar), add a small `prefers-color-scheme` polish, but kill the light option entirely. Honest given the site is CAVE-themed dark-first.
-
-**Recommendation:** option 2 (force dark) is faster, more honest, and matches the CAVE design language. Light theme on a deliberately-dark site is a "feature for completeness's sake" — only ship it if you can do it right. Discuss with the human before choosing.
+### B. Light theme — FIXED in [`f244d02`](https://github.com/lliWcWill/fsuite/commit/f244d02)
+Codex P2 thread `lXf8` flagged the same issue. Took option 1 (full light overrides per Starlight's canonical pattern, verified via firecrawl scrape of starlight.astro.build/guides/css-and-tailwind):
+- White/gray-1..7/black inverted (gray-1 = high-contrast text, gray-7 = lowest-contrast surface, `--sl-color-black` = `#ffffff` background)
+- Background layers explicitly set (`--sl-color-bg`, `--sl-color-bg-nav`, `--sl-color-bg-sidebar`, `--sl-color-bg-inline-code`)
+- Text tokens (`--sl-color-text`, `--sl-color-text-accent`, `--sl-color-text-invert`)
+- Hairlines retain CAVE green tint at light-bg-appropriate alpha
+- Accent darkened from `#3aff9d` (bioluminescent, unreadable on white) to `#0a8c52` (deep forest green, AAA-ish contrast on white)
+
+Light mode toggle should now produce a proper inverted CAVE theme instead of white-flood.
 
 ### gen-commands.mjs preamble preservation (already fixed)
 Codex thread `lH6b` flagged that `npm run build` (which runs `gen:commands && astro build`) was wiping the round-4 preambles. Verified + fixed in [`e566679`](https://github.com/lliWcWill/fsuite/commit/e566679): `buildPage()` now reads the existing file and splices the regenerated `## Help output` section onto the bottom, preserving everything above. Verified locally: `node site/scripts/gen-commands.mjs` re-ran without stripping the drone profile + canonical chains + monokai sample blocks.

From 707018477ccf55e6c7390e1f7bcb47a044ceef7b Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:29:31 -0500
Subject: [PATCH 13/19] docs(handoff): refresh after dev-server rebuild on
 dca597a

- TL;DR + git state + commit table updated to reflect all 10 commits on
  docs/site-revamp (R1-R6 + triage + 3 fixes + 3 doc updates)
- Dev server section updated with fresh PIDs (15076, 15077) and the
  .astro-cache-cleared restart at 17:28
- PR #39 thread state corrected: 22/22 resolved (was 21 in earlier write)

No code change, just keeping the handoff in sync with reality.
---
 .../internal/specs/2026-04-29-pr39-handoff.md | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/internal/specs/2026-04-29-pr39-handoff.md b/docs/internal/specs/2026-04-29-pr39-handoff.md
index f39b933..53baad1 100644
--- a/docs/internal/specs/2026-04-29-pr39-handoff.md
+++ b/docs/internal/specs/2026-04-29-pr39-handoff.md
@@ -8,12 +8,12 @@
 
 ## TL;DR
 
-PR #39 is open, mergeable, CI green, CodeRabbit green. All 6 docs rounds + the Codex P1/P2 triage are landed. Two clear next steps:
+PR #39 is open, mergeable, **all 22 review threads resolved (0 unresolved)**, CI green, CodeRabbit green. All 6 docs rounds + the Codex P1/P2 triage + the gen-commands preservation fix + the complete light-theme tokens fix are landed. Two clear next steps:
 
 1. **Round 6.5** — Claude Design (CD) is shipping `mdx-strict-mode-rules.md` as a small standalone deliverable. Just integrate it under `docs/internal/specs/` when it arrives.
 2. **Round 7** — visitor walkthrough on the open PR branch. Output is a prioritized issue list per page, NOT a generated zip. CD is waiting for the green light.
 
-The dev server is running on this machine. Your job is mostly: finish round 7, absorb whatever CD ships for 6.5, push final fixes to PR #39, ping the human when ready to merge.
+The dev server has been freshly restarted with `.astro` cache cleared on `dca597a`. Your job is mostly: finish round 7, absorb whatever CD ships for 6.5, push final fixes to PR #39, ping the human when ready to merge.
 
 ---
 
@@ -21,9 +21,9 @@ The dev server is running on this machine. Your job is mostly: finish round 7, a
 
 ### Git state
 - **Branch:** `docs/site-revamp` (you're on it)
-- **HEAD:** `a5a25ca Address Codex P1/P2 review on PR #39`
+- **HEAD:** `dca597a docs(handoff): light theme fixed in f244d02 — strike from open-bugs list`
 - **Origin:** in sync, pushed
-- **Master tip:** `c745101` (PR #39 forks from there, six commits ahead)
+- **Master tip:** `c745101` (PR #39 forks from there, ten commits ahead)
 
 ### Branch contents (commits on `docs/site-revamp` not on `master`):
 
@@ -35,12 +35,18 @@ The dev server is running on this machine. Your job is mostly: finish round 7, a
 | `9e492d6` | R4 | 14 per-command drone profile preambles |
 | `c4d7128` | R5 | `architecture/index.mdx` (NEW), MCP/Hooks/Telemetry rebuilt, delivery flow CSS |
 | `36053d5` | R6 | Story-page HUD rebuild (Episodes 1/2/3 + Lightbulb) |
-| `a5a25ca` | — | Codex P1/P2 review triage (15 fixes, 2 false positives flagged, 4 deferred) |
+| `a5a25ca` | triage | Codex P1/P2 review wave 1+2+3 (16 fixes total this commit) |
+| `bc2afd3` | docs | First handoff doc for next agent |
+| `e566679` | fix | gen-commands.mjs preserves preambles above `## Help output` (Codex P1 lH6b) |
+| `42ad05f` | docs | Handoff updated with newly-reported visual bugs |
+| `f244d02` | fix | Complete light-theme Starlight token overrides (Codex P2 lXf8) |
+| `dca597a` | docs | Handoff updated to strike light-theme bug — fixed |
 
 ### PR #39
 - URL: https://github.com/lliWcWill/fsuite/pull/39
 - State: OPEN, MERGEABLE
 - Checks: `test-suite` SUCCESS, `CodeRabbit` SUCCESS
+- Threads: **22/22 resolved** (16 fixed-with-commit, 3 false positives thumbs-down, 3 deferred-with-rationale thumbs-down)
 
 ### Sister branch — `codex/fread-media-pdf-image` (PR #38)
 - This is the media-reading feature branch, **not yours**
@@ -52,11 +58,12 @@ The dev server is running on this machine. Your job is mostly: finish round 7, a
 
 ## Dev environment
 
-### Server is already running
+### Server is already running (freshly restarted at 17:28 on `dca597a`)
 - Astro dev server on `http://localhost:4321/fsuite/`
-- PID: `pgrep -af "astro dev"` to find it
-- Log: `/tmp/fsuite-site-dev.log`
+- PIDs: **15076 + 15077** (find live with `pgrep -af "astro dev"`)
+- Log: `/tmp/fsuite-site-dev.log` (previous session at `/tmp/fsuite-site-dev.log.prev`)
 - Started detached via `setsid nohup npm run dev > /tmp/fsuite-site-dev.log 2>&1 < /dev/null &` from `site/`
+- `.astro` cache was cleared on restart so all 6 docs rounds + the light-theme + gen-commands fixes are loaded fresh
 
 ### If the server breaks
 1. **Stale content cache** (most common): `rm -rf site/.astro && touch <file>` to force re-scan

From c9c6f5c63fe807e90135667ed3296c6a76205393 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:45:31 -0500
Subject: [PATCH 14/19] feat(theme): force dark + harden gen-commands against
 custom-page wipes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

THEME FORCE-DARK:
- New ThemeSelect override (HiddenThemeSelect.astro): renders nothing, hides
  the toggle UI from Starlight's nav.
- New ThemeProvider override (ForceDarkThemeProvider.astro): inline script
  pins data-theme='dark' on every load + overwrites any prior
  localStorage.starlight-theme value. is:inline so it runs before paint —
  no theme flash.
- astro.config.mjs: registered both overrides; expressiveCode dropped
  github-light from themes (only monokai now).
- The :root[data-theme='light'] block in custom.css is left as dormant
  code — re-enabling the toggle later just requires removing the two
  overrides + adding github-light back.

WHY: CAVE theme is dark-first by design. Bioluminescent green accents
(#3aff9d) only glow against deep void backgrounds; on white they're flat
and lifeless. Bloom + scanline effects don't translate. A half-built light
theme reads worse than no light theme. Removing the toggle is the honest
move.

DEFENSIVE GEN-COMMANDS:
- buildPage() now returns the existing file unchanged if it exists but
  lacks the '## Help output' marker. Previously fell through to first-time
  generation, which would WIPE any hand-customized command page (e.g.
  fwrite.md uses '## Usage notes' since its surface is MCP-only and
  doesn't have a real --help binary). Caught this when running
  gen-commands during the force-dark verification.

INCIDENTAL: fbash.md regenerated to pick up a new '--no-truncate, --full'
flag added to the fbash binary recently — natural gen-commands update.
---
 site/astro.config.mjs                         |  7 +++++-
 site/scripts/gen-commands.mjs                 |  6 +++++
 .../components/ForceDarkThemeProvider.astro   | 23 +++++++++++++++++++
 site/src/components/HiddenThemeSelect.astro   | 11 +++++++++
 site/src/content/docs/commands/fbash.md       |  1 +
 5 files changed, 47 insertions(+), 1 deletion(-)
 create mode 100644 site/src/components/ForceDarkThemeProvider.astro
 create mode 100644 site/src/components/HiddenThemeSelect.astro

diff --git a/site/astro.config.mjs b/site/astro.config.mjs
index 13757b1..671f4a9 100644
--- a/site/astro.config.mjs
+++ b/site/astro.config.mjs
@@ -18,6 +18,11 @@ export default defineConfig({
         // Override the page H1 so we can render the page-actions dropdown
         // (Copy / View / Open in LLM) inline with the title.
         PageTitle: './src/components/PageTitle.astro',
+        // Force-dark theme: hide the toggle UI + pin data-theme="dark" on load.
+        // CAVE theme is dark-only by design — bloom/scanline effects don't
+        // translate to a light canvas.
+        ThemeSelect: './src/components/HiddenThemeSelect.astro',
+        ThemeProvider: './src/components/ForceDarkThemeProvider.astro',
       },
       social: [
         { icon: 'github', label: 'GitHub', href: 'https://github.com/lliWcWill/fsuite' },
@@ -26,7 +31,7 @@ export default defineConfig({
         './src/styles/custom.css',
       ],
       expressiveCode: {
-        themes: ['monokai', 'github-light'],
+        themes: ['monokai'],
         styleOverrides: {
           codeFontFamily: '"JetBrainsMono Nerd Font", "Fira Code", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
         },
diff --git a/site/scripts/gen-commands.mjs b/site/scripts/gen-commands.mjs
index fc2ebfc..6d5dfae 100644
--- a/site/scripts/gen-commands.mjs
+++ b/site/scripts/gen-commands.mjs
@@ -93,12 +93,18 @@ ${helpText}
   // If a page already exists, preserve everything above `## Help output`
   // (frontmatter + tagline H2 + intro paragraph + any round-4 preamble) and
   // splice the regenerated help + see-also onto the bottom.
+  //
+  // Defensive case: if the file exists but the marker is missing, the page
+  // has been hand-customized (e.g. `fwrite.md` uses `## Usage notes` since
+  // its surface is MCP-only). Leave it untouched rather than nuking the
+  // custom content with the default first-time-generation template.
   if (existsSync(outPath)) {
     const existing = readFileSync(outPath, 'utf8');
     const helpIdx = existing.indexOf('## Help output');
     if (helpIdx > 0) {
       return existing.slice(0, helpIdx) + helpSection;
     }
+    return existing;
   }
 
   // First-time generation: build the default frontmatter + tagline H2 + intro
diff --git a/site/src/components/ForceDarkThemeProvider.astro b/site/src/components/ForceDarkThemeProvider.astro
new file mode 100644
index 0000000..451b1af
--- /dev/null
+++ b/site/src/components/ForceDarkThemeProvider.astro
@@ -0,0 +1,23 @@
+---
+/**
+ * ForceDarkThemeProvider.astro — Starlight `ThemeProvider` override that pins
+ * the site to dark mode permanently.
+ *
+ * Replaces Starlight's default theme-detection script (which respects
+ * `localStorage.starlight-theme` + `prefers-color-scheme`). Since the toggle
+ * UI is also hidden via `HiddenThemeSelect.astro`, no code path can flip the
+ * site to light. The `[data-theme='light']` block in custom.css remains as
+ * dormant code in case we ever re-enable the toggle.
+ *
+ * Runs `is:inline` so it executes before any visible paint — no theme flash.
+ */
+---
+<script is:inline>
+  // Force dark + overwrite any prior preference.
+  document.documentElement.dataset.theme = 'dark';
+  try {
+    window.localStorage.setItem('starlight-theme', 'dark');
+  } catch (_) {
+    /* localStorage not available (private mode, etc.) — dataset is enough. */
+  }
+</script>
diff --git a/site/src/components/HiddenThemeSelect.astro b/site/src/components/HiddenThemeSelect.astro
new file mode 100644
index 0000000..6b6b1a4
--- /dev/null
+++ b/site/src/components/HiddenThemeSelect.astro
@@ -0,0 +1,11 @@
+---
+/**
+ * HiddenThemeSelect.astro — Starlight `ThemeSelect` override that renders nothing.
+ *
+ * The fsuite docs site is dark-only by design (CAVE theme: bioluminescent green
+ * accents on void-black surfaces; the bloom + scanline effects only read on a
+ * dark canvas). The toggle is therefore disabled — paired with
+ * `ForceDarkThemeProvider.astro` which pins `data-theme="dark"` regardless of
+ * any prior user preference.
+ */
+---
diff --git a/site/src/content/docs/commands/fbash.md b/site/src/content/docs/commands/fbash.md
index 5ce1dc1..96129f2 100644
--- a/site/src/content/docs/commands/fbash.md
+++ b/site/src/content/docs/commands/fbash.md
@@ -60,6 +60,7 @@ OPTIONS
   --command <cmd>       Bash command to execute (or pass as positional arg)
   --max-lines <n>       Cap stdout to n lines (default: 200)
   --max-bytes <n>       Cap stdout to n bytes (default: 51200)
+  --no-truncate, --full Disable stdout line/byte caps
   --json                Parse command output as JSON
   --cwd <path>          Working directory (overrides session CWD)
   --timeout <secs>      Timeout in seconds (auto-tuned by class if omitted)

From 9ffd39f098cfbd46147a725c52646db6f2f8f2c6 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:56:30 -0500
Subject: [PATCH 15/19] docs(handoff): record force-dark + defensive
 gen-commands

- Updated Bug B section: light theme is now DISABLED rather than fixed
  (after verifying the rendered light theme without Dark Reader, decided
  the CAVE aesthetic doesn't translate to light surfaces; force-dark is
  more honest than half-built light theme)
- Force-dark mechanism documented: HiddenThemeSelect.astro +
  ForceDarkThemeProvider.astro overrides registered in astro.config.mjs
- Added c9c6f5c + 7070184 to commit table
- Dev environment section: HEAD updated to c9c6f5c, theme-locked note added
- Removed duplicate 'Server is already running' header from earlier sloppy edit
---
 .../internal/specs/2026-04-29-pr39-handoff.md | 26 +++++++++++--------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/docs/internal/specs/2026-04-29-pr39-handoff.md b/docs/internal/specs/2026-04-29-pr39-handoff.md
index 53baad1..889fe9d 100644
--- a/docs/internal/specs/2026-04-29-pr39-handoff.md
+++ b/docs/internal/specs/2026-04-29-pr39-handoff.md
@@ -13,7 +13,7 @@ PR #39 is open, mergeable, **all 22 review threads resolved (0 unresolved)**, CI
 1. **Round 6.5** — Claude Design (CD) is shipping `mdx-strict-mode-rules.md` as a small standalone deliverable. Just integrate it under `docs/internal/specs/` when it arrives.
 2. **Round 7** — visitor walkthrough on the open PR branch. Output is a prioritized issue list per page, NOT a generated zip. CD is waiting for the green light.
 
-The dev server has been freshly restarted with `.astro` cache cleared on `dca597a`. Your job is mostly: finish round 7, absorb whatever CD ships for 6.5, push final fixes to PR #39, ping the human when ready to merge.
+The dev server has been freshly restarted with `.astro` cache cleared on `c9c6f5c` (force-dark + defensive gen-commands). Your job is mostly: finish round 7, absorb whatever CD ships for 6.5, push final fixes to PR #39, ping the human when ready to merge.
 
 ---
 
@@ -21,7 +21,7 @@ The dev server has been freshly restarted with `.astro` cache cleared on `dca597
 
 ### Git state
 - **Branch:** `docs/site-revamp` (you're on it)
-- **HEAD:** `dca597a docs(handoff): light theme fixed in f244d02 — strike from open-bugs list`
+- **HEAD:** `c9c6f5c feat(theme): force dark + harden gen-commands against custom-page wipes`
 - **Origin:** in sync, pushed
 - **Master tip:** `c745101` (PR #39 forks from there, ten commits ahead)
 
@@ -41,6 +41,8 @@ The dev server has been freshly restarted with `.astro` cache cleared on `dca597
 | `42ad05f` | docs | Handoff updated with newly-reported visual bugs |
 | `f244d02` | fix | Complete light-theme Starlight token overrides (Codex P2 lXf8) |
 | `dca597a` | docs | Handoff updated to strike light-theme bug — fixed |
+| `7070184` | docs | Handoff refresh after dev-server rebuild |
+| `c9c6f5c` | feat | Force dark theme (hide toggle, pin data-theme) + defensive gen-commands |
 
 ### PR #39
 - URL: https://github.com/lliWcWill/fsuite/pull/39
@@ -58,11 +60,13 @@ The dev server has been freshly restarted with `.astro` cache cleared on `dca597
 
 ## Dev environment
 
-### Server is already running (freshly restarted at 17:28 on `dca597a`)
+### Server is already running (freshly restarted at 17:28 on `c9c6f5c`)
 - Astro dev server on `http://localhost:4321/fsuite/`
 - PIDs: **15076 + 15077** (find live with `pgrep -af "astro dev"`)
 - Log: `/tmp/fsuite-site-dev.log` (previous session at `/tmp/fsuite-site-dev.log.prev`)
 - Started detached via `setsid nohup npm run dev > /tmp/fsuite-site-dev.log 2>&1 < /dev/null &` from `site/`
+- `.astro` cache was cleared on restart so all 6 docs rounds + the force-dark overrides + defensive gen-commands fix are loaded fresh
+- **Theme is now force-dark** — the toggle UI is gone (ThemeSelect override) and `data-theme="dark"` is pinned on every load (ThemeProvider override). The `:root[data-theme='light']` block in `custom.css` stays as dormant code.
 - `.astro` cache was cleared on restart so all 6 docs rounds + the light-theme + gen-commands fixes are loaded fresh
 
 ### If the server breaks
@@ -199,15 +203,15 @@ Every link click between pages briefly flashes white/empty before the next page
 
 **Suggested first move:** reproduce on production build (`astro build && astro preview`) to confirm dev-only vs ships-to-deploy. If it ships, add `<ClientRouter transition:animate="none" />` to `PageTitle.astro` or the layout.
 
-### B. Light theme — FIXED in [`f244d02`](https://github.com/lliWcWill/fsuite/commit/f244d02)
-Codex P2 thread `lXf8` flagged the same issue. Took option 1 (full light overrides per Starlight's canonical pattern, verified via firecrawl scrape of starlight.astro.build/guides/css-and-tailwind):
-- White/gray-1..7/black inverted (gray-1 = high-contrast text, gray-7 = lowest-contrast surface, `--sl-color-black` = `#ffffff` background)
-- Background layers explicitly set (`--sl-color-bg`, `--sl-color-bg-nav`, `--sl-color-bg-sidebar`, `--sl-color-bg-inline-code`)
-- Text tokens (`--sl-color-text`, `--sl-color-text-accent`, `--sl-color-text-invert`)
-- Hairlines retain CAVE green tint at light-bg-appropriate alpha
-- Accent darkened from `#3aff9d` (bioluminescent, unreadable on white) to `#0a8c52` (deep forest green, AAA-ish contrast on white)
+### B. Light theme — DISABLED entirely in [`c9c6f5c`](https://github.com/lliWcWill/fsuite/commit/c9c6f5c)
+Originally fixed the light-theme tokens in `f244d02` (full Starlight palette overrides per the firecrawl-verified canonical pattern). After verifying the actual rendered light theme on the user's screen with Dark Reader extension OFF, the conclusion was: **even with all tokens correct, light mode loses ~70% of the CAVE design language** (bloom halos, scanlines, void-glow effects only read on dark surfaces). A correct-but-flat light theme felt worse than no light theme.
 
-Light mode toggle should now produce a proper inverted CAVE theme instead of white-flood.
+Force-dark via two Starlight component overrides (registered in `astro.config.mjs`):
+- `HiddenThemeSelect.astro` — empty component, hides the toggle UI from the nav
+- `ForceDarkThemeProvider.astro` — `is:inline` script that pins `data-theme="dark"` and overwrites `localStorage.starlight-theme` on every page load (no theme flash, no escape hatch)
+- ExpressiveCode `themes` reduced to `['monokai']` only (was `['monokai', 'github-light']`)
+
+The `:root[data-theme='light']` token block in `custom.css` is left as dormant code — re-enabling the toggle later just means deleting the two component overrides + adding `github-light` back to expressiveCode.
 
 ### gen-commands.mjs preamble preservation (already fixed)
 Codex thread `lH6b` flagged that `npm run build` (which runs `gen:commands && astro build`) was wiping the round-4 preambles. Verified + fixed in [`e566679`](https://github.com/lliWcWill/fsuite/commit/e566679): `buildPage()` now reads the existing file and splices the regenerated `## Help output` section onto the bottom, preserving everything above. Verified locally: `node site/scripts/gen-commands.mjs` re-ran without stripping the drone profile + canonical chains + monokai sample blocks.

From fe98a0708c9bec5328bb71e28312f5382669807e Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 17:56:50 -0500
Subject: [PATCH 16/19] docs(handoff): remove duplicate cache-cleared line in
 dev section

---
 docs/internal/specs/2026-04-29-pr39-handoff.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/internal/specs/2026-04-29-pr39-handoff.md b/docs/internal/specs/2026-04-29-pr39-handoff.md
index 889fe9d..56da996 100644
--- a/docs/internal/specs/2026-04-29-pr39-handoff.md
+++ b/docs/internal/specs/2026-04-29-pr39-handoff.md
@@ -67,7 +67,6 @@ The dev server has been freshly restarted with `.astro` cache cleared on `c9c6f5
 - Started detached via `setsid nohup npm run dev > /tmp/fsuite-site-dev.log 2>&1 < /dev/null &` from `site/`
 - `.astro` cache was cleared on restart so all 6 docs rounds + the force-dark overrides + defensive gen-commands fix are loaded fresh
 - **Theme is now force-dark** — the toggle UI is gone (ThemeSelect override) and `data-theme="dark"` is pinned on every load (ThemeProvider override). The `:root[data-theme='light']` block in `custom.css` stays as dormant code.
-- `.astro` cache was cleared on restart so all 6 docs rounds + the light-theme + gen-commands fixes are loaded fresh
 
 ### If the server breaks
 1. **Stale content cache** (most common): `rm -rf site/.astro && touch <file>` to force re-scan

From d9ac5c6ed0df14f794bf830e8a863fb40adb2df1 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 18:10:38 -0500
Subject: [PATCH 17/19] fix(pr39-codex): popup blocker, ghSourcePath for index
 pages, draft filter
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three Codex findings landed after the previous handoff was finalized.
All three are real and addressed here.

P1 — PageActions.astro:289 popup blocker (open-claude / open-chatgpt):
  Both handlers awaited fetchMarkdown() before window.open(), so the
  popup escaped user-gesture context and modern browsers veto it. Now we
  open about:blank synchronously inside the click handler, then navigate
  via popup.location.href once fetchMarkdown resolves. `noopener` is
  dropped (we need the popup ref to navigate); `popup.opener = null` is
  set manually as the security mitigation. If popup is null (blocker on)
  we surface a toast instead of failing silently.

P2 — PageActions.astro:42 ghSourcePath for section index pages:
  Starlight collapses `architecture/index.mdx` route IDs to bare
  `architecture`, so the slug-derived ghSourcePath produced
  `architecture.mdx` (404) instead of `architecture/index.mdx`. Switched
  to derive from `entry.filePath` (which preserves the actual on-disk
  path including extension) with a regex strip of the
  src/content/docs prefix. Slug-based path stays as fallback for the
  unlikely case where filePath is missing.

P2 — [...slug].md.ts:19 draft filter on raw markdown endpoint:
  getStaticPaths() pulled every docs entry without checking
  data.draft, so any page marked draft: true would still be exposed
  through /<slug>.md (Copy / View / Open-in-LLM URLs) even though
  Starlight excludes it from the rendered route. Added the filter
  predicate to getCollection('docs', ...) to mirror Starlight's
  behaviour. No drafts currently exist; this is preventive.

Verified locally: all probed pages still 200, dev server log clean,
data-gh-source on /architecture/ now ends with index.mdx.

Resolves Codex review threads:
  PRRT_kwDORCzV5M5-lf1P  (P1 popup)
  PRRT_kwDORCzV5M5-llJm  (P2 ghSourcePath)
  PRRT_kwDORCzV5M5-lynR  (P2 draft filter)
---
 site/src/components/PageActions.astro | 80 ++++++++++++++++++---------
 site/src/pages/[...slug].md.ts        |  5 +-
 2 files changed, 57 insertions(+), 28 deletions(-)

diff --git a/site/src/components/PageActions.astro b/site/src/components/PageActions.astro
index dec8a08..3597f83 100644
--- a/site/src/components/PageActions.astro
+++ b/site/src/components/PageActions.astro
@@ -37,9 +37,14 @@ const mdRelative = slug ? `${baseUrl}/${slug}.md` : '';
 // mixes .md and .mdx and a hardcoded .mdx 404s for .md files. Astro's
 // entry.filePath keeps the extension; entry.id has it stripped by Starlight.
 const ghBase = 'https://github.com/lliWcWill/fsuite/blob/master/site/src/content/docs';
-const fileExtMatch = (entry as any)?.filePath?.match(/\.(md|mdx)$/i);
+const filePath = (entry as any)?.filePath as string | undefined;
+// Prefer entry.filePath — it preserves the actual on-disk path with extension
+// and handles section index pages (e.g. architecture/index.mdx) that Starlight
+// collapses to bare "architecture" in entry.id.
+const filePathRel = filePath?.replace(/^.*[\/\\]content[\/\\]docs[\/\\]/, '');
+const fileExtMatch = filePath?.match(/\.(md|mdx)$/i);
 const fileExt = fileExtMatch ? fileExtMatch[1].toLowerCase() : 'mdx';
-const ghSourcePath = slug ? `${slug}.${fileExt}` : `index.${fileExt}`;
+const ghSourcePath = filePathRel ?? (slug ? `${slug}.${fileExt}` : `index.${fileExt}`);
 const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
 ---
 
@@ -267,34 +272,55 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
           return;
         }
 
-        case 'open-claude': {
-          try {
-            const md = await fetchMarkdown();
-            const q = encodeURIComponent(promptForLLM(md));
-            window.open(`https://claude.ai/new?q=${q}`, '_blank', 'noopener,noreferrer');
-          } catch {
-            // Fallback: just hand Claude the URL.
-            const q = encodeURIComponent(`Please read ${buildMdUrl()} and help me understand it.`);
-            window.open(`https://claude.ai/new?q=${q}`, '_blank', 'noopener,noreferrer');
-          } finally {
-            closeMenu();
+          case 'open-claude': {
+            // Open the popup synchronously inside the user gesture — browsers veto
+            // window.open() that runs after an await, so we open about:blank first
+            // and navigate after fetchMarkdown resolves. `noopener` is dropped because
+            // we need the popup ref to set location.href; opener is severed manually
+            // below as the security mitigation.
+            const popup = window.open('about:blank', '_blank');
+            if (!popup) {
+              showToast('Popup blocked — allow popups for this site', false);
+              closeMenu();
+              return;
+            }
+            try {
+              const md = await fetchMarkdown();
+              const q = encodeURIComponent(promptForLLM(md));
+              popup.opener = null;
+              popup.location.href = `https://claude.ai/new?q=${q}`;
+            } catch {
+              // Fallback: just hand Claude the URL.
+              const q = encodeURIComponent(`Please read ${buildMdUrl()} and help me understand it.`);
+              popup.opener = null;
+              popup.location.href = `https://claude.ai/new?q=${q}`;
+            } finally {
+              closeMenu();
+            }
+            return;
           }
-          return;
-        }
 
-        case 'open-chatgpt': {
-          try {
-            const md = await fetchMarkdown();
-            const q = encodeURIComponent(promptForLLM(md));
-            window.open(`https://chatgpt.com/?hints=search&q=${q}`, '_blank', 'noopener,noreferrer');
-          } catch {
-            const q = encodeURIComponent(`Please read ${buildMdUrl()} and help me understand it.`);
-            window.open(`https://chatgpt.com/?hints=search&q=${q}`, '_blank', 'noopener,noreferrer');
-          } finally {
-            closeMenu();
+          case 'open-chatgpt': {
+            const popup = window.open('about:blank', '_blank');
+            if (!popup) {
+              showToast('Popup blocked — allow popups for this site', false);
+              closeMenu();
+              return;
+            }
+            try {
+              const md = await fetchMarkdown();
+              const q = encodeURIComponent(promptForLLM(md));
+              popup.opener = null;
+              popup.location.href = `https://chatgpt.com/?hints=search&q=${q}`;
+            } catch {
+              const q = encodeURIComponent(`Please read ${buildMdUrl()} and help me understand it.`);
+              popup.opener = null;
+              popup.location.href = `https://chatgpt.com/?hints=search&q=${q}`;
+            } finally {
+              closeMenu();
+            }
+            return;
           }
-          return;
-        }
       }
     };
 
diff --git a/site/src/pages/[...slug].md.ts b/site/src/pages/[...slug].md.ts
index 7d2fa47..802413a 100644
--- a/site/src/pages/[...slug].md.ts
+++ b/site/src/pages/[...slug].md.ts
@@ -16,7 +16,10 @@ import type { APIRoute } from 'astro';
 import { getCollection, type CollectionEntry } from 'astro:content';
 
 export async function getStaticPaths() {
-  const docs = await getCollection('docs');
+  // Filter draft entries — Starlight excludes them from rendered routes so the
+  // raw markdown endpoint must mirror that to avoid leaking unpublished content
+  // through /<slug>.md (Copy / View / Open-in-LLM URLs).
+  const docs = await getCollection('docs', (entry) => entry.data.draft !== true);
   return docs.map((entry: CollectionEntry<'docs'>) => ({
     params: { slug: entry.id.replace(/\.(md|mdx)$/i, '') },
     props: { entry },

From f81f3e6ef8615641b02fc93a4bddd027c2abe5f5 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 21:35:54 -0500
Subject: [PATCH 18/19] fix(a11y,cleanup): strip ARIA menu roles + delete
 custom_backup.css
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The merge in 1325843 took PR39's PageActions.astro wholesale, which
inadvertently undid PR38's accessibility cleanup. The component declared
aria-haspopup="menu", role="menu", and role="menuitem", but the script
only handles Escape close — it does not implement the W3C APG menu
keyboard contract (Enter/Space to open + focus first item, Up/Down
between items, Home/End, etc.). Misleading ARIA is worse than no ARIA
for assistive tech users.

Resolution: drop the menu roles entirely and keep aria-expanded /
aria-controls / aria-label as the open/close contract. This matches
master's pattern and the keyboard model the component actually
implements.

Also removed site/src/styles/custom_backup.css — leftover from PR39's
earlier light-theme experiment, untracked by anything in the build.

Site builds clean (32 pages, 2.14s).
---
 site/src/components/PageActions.astro | 14 +++++-----
 site/src/styles/custom_backup.css     | 38 ---------------------------
 2 files changed, 6 insertions(+), 46 deletions(-)
 delete mode 100644 site/src/styles/custom_backup.css

diff --git a/site/src/components/PageActions.astro b/site/src/components/PageActions.astro
index 3597f83..7c26a8c 100644
--- a/site/src/components/PageActions.astro
+++ b/site/src/components/PageActions.astro
@@ -72,7 +72,6 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
     type="button"
     class="page-actions__caret"
     data-action="toggle-menu"
-    aria-haspopup="menu"
     aria-expanded="false"
     aria-label="More page actions"
   >
@@ -81,8 +80,8 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
     </svg>
   </button>
 
-  <div class="page-actions__menu" role="menu" hidden>
-    <button type="button" role="menuitem" data-action="copy-md">
+  <div class="page-actions__menu" hidden>
+    <button type="button" data-action="copy-md">
       <span class="page-actions__menu-icon">📄</span>
       <span class="page-actions__menu-text">
         <span class="page-actions__menu-title">Copy as Markdown</span>
@@ -90,7 +89,7 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
       </span>
     </button>
 
-    <button type="button" role="menuitem" data-action="copy-plain">
+    <button type="button" data-action="copy-plain">
       <span class="page-actions__menu-icon">¶</span>
       <span class="page-actions__menu-text">
         <span class="page-actions__menu-title">Copy as plain text</span>
@@ -98,7 +97,7 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
       </span>
     </button>
 
-    <button type="button" role="menuitem" data-action="view-md">
+    <button type="button" data-action="view-md">
       <span class="page-actions__menu-icon">⤴</span>
       <span class="page-actions__menu-text">
         <span class="page-actions__menu-title">View as Markdown</span>
@@ -108,7 +107,7 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
 
     <hr class="page-actions__divider" />
 
-    <button type="button" role="menuitem" data-action="open-claude">
+    <button type="button" data-action="open-claude">
       <span class="page-actions__menu-icon">◈</span>
       <span class="page-actions__menu-text">
         <span class="page-actions__menu-title">Open in Claude</span>
@@ -116,7 +115,7 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
       </span>
     </button>
 
-    <button type="button" role="menuitem" data-action="open-chatgpt">
+    <button type="button" data-action="open-chatgpt">
       <span class="page-actions__menu-icon">◇</span>
       <span class="page-actions__menu-text">
         <span class="page-actions__menu-title">Open in ChatGPT</span>
@@ -127,7 +126,6 @@ const ghSourceUrl = `${ghBase}/${ghSourcePath}`;
     <hr class="page-actions__divider" />
 
     <a
-      role="menuitem"
       href={ghSourceUrl}
       target="_blank"
       rel="noopener noreferrer"
diff --git a/site/src/styles/custom_backup.css b/site/src/styles/custom_backup.css
deleted file mode 100644
index c972787..0000000
--- a/site/src/styles/custom_backup.css
+++ /dev/null
@@ -1,38 +0,0 @@
-/* fsuite docs — custom theme tweaks to match the Monokai vibe of the MCP output */
-
-:root {
-  /* Dark theme override — Monokai-ish accent */
-  --sl-color-accent-low: #3b2a1a;
-  --sl-color-accent: #fd971f;
-  --sl-color-accent-high: #ffd866;
-
-  --sl-color-white: #f8f8f2;
-  --sl-color-gray-1: #e1e1db;
-  --sl-color-gray-2: #c5c5c0;
-  --sl-color-gray-3: #75715e;
-  --sl-color-gray-4: #49483e;
-  --sl-color-gray-5: #383830;
-  --sl-color-gray-6: #272822;
-  --sl-color-black: #1e1f1c;
-}
-
-:root[data-theme='light'] {
-  --sl-color-accent-low: #fef3c7;
-  --sl-color-accent: #d97706;
-  --sl-color-accent-high: #92400e;
-}
-
-/* Make the inline code stand out like terminal output */
-code {
-  font-weight: 500;
-}
-
-/* Terminal-y feel for block quotes (callouts) */
-blockquote {
-  border-left-color: var(--sl-color-accent);
-}
-
-/* Tighten the command-reference tables */
-table {
-  font-size: 0.92em;
-}

From ab7fbc4568013e2a57946fc02a9237c268d01601 Mon Sep 17 00:00:00 2001
From: player3 <domain112@yahoo.com>
Date: Wed, 29 Apr 2026 21:44:39 -0500
Subject: [PATCH 19/19] fix(css): reconnect dropdown styling after ARIA role
 removal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex follow-up on f81f3e6 — that commit stripped role="menuitem" from
PageActions.astro for accessibility correctness, but the CSS in
custom.css still keyed dropdown item styling off [role="menuitem"]:

  .page-actions__menu > [role="menuitem"] { ... }
  .page-actions__menu > [role="menuitem"]:hover, ...:focus-visible { ... }

Result: hover/focus styling and the item layout silently stopped
applying once the role attribute was removed. Build was green because
CSS unmatched selectors are not errors.

Switched the three rules to .page-actions__menu > :is(button, a) which
matches the exact same 6 DOM children the role selector did (verified
in the rendered dist/commands/fbash/index.html: 5 <button>s + 1 <a>,
all data-action items inside .page-actions__menu).

Also updated the stale jsdoc comment in PageActions.astro that still
referenced "ARIA roles (menu, menuitem)" — replaced with the honest
description: real <button>s with aria-expanded for the toggle state.

Site builds clean (32 pages, 2.15s).
---
 site/src/components/PageActions.astro | 2 +-
 site/src/styles/custom.css            | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/site/src/components/PageActions.astro b/site/src/components/PageActions.astro
index 7c26a8c..495f94e 100644
--- a/site/src/components/PageActions.astro
+++ b/site/src/components/PageActions.astro
@@ -18,7 +18,7 @@
  *       · View source on GitHub
  *
  * Accessibility:
- *   - Real <button> elements + ARIA roles (menu, menuitem)
+ *   - Real <button> elements with aria-expanded for the toggle state
  *   - Keyboard: Enter/Space toggles, Escape closes, click-outside closes
  */
 
diff --git a/site/src/styles/custom.css b/site/src/styles/custom.css
index 2a4ad2e..db537ea 100644
--- a/site/src/styles/custom.css
+++ b/site/src/styles/custom.css
@@ -649,7 +649,7 @@ starlight-tabs [role="tab"][aria-selected="true"] {
   display: none;
 }
 
-.page-actions__menu > [role="menuitem"] {
+.page-actions__menu > :is(button, a) {
   display: flex;
   align-items: flex-start;
   gap: 0.7rem;
@@ -665,8 +665,8 @@ starlight-tabs [role="tab"][aria-selected="true"] {
   transition: background 100ms ease, color 100ms ease;
 }
 
-.page-actions__menu > [role="menuitem"]:hover,
-.page-actions__menu > [role="menuitem"]:focus-visible {
+.page-actions__menu > :is(button, a):hover,
+.page-actions__menu > :is(button, a):focus-visible {
   background: rgba(58, 255, 157, 0.08);
   color: var(--sl-color-accent-high, #a8ffd4);
   outline: none;