From f1c2adf65763532e6b8d4f06d93a0cd796c3dc06 Mon Sep 17 00:00:00 2001
From: Aditya Garud <153842990+yashranaway@users.noreply.github.com>
Date: Fri, 11 Sep 2026 17:31:23 +0000
Subject: [PATCH 1/5] fix(web): categorize docs nav and stop calling sessions
 isolated

Docs navigation is now an explicit category catalog instead of slicing
the route list. The overview pulls the shared-profile contract from
COMMANDS.md. The command reference is filterable from that same source.
---
 apps/web/app/docs/commands/page.tsx           | 21 ++---
 apps/web/app/docs/page.tsx                    | 12 ++-
 apps/web/app/globals.css                      | 64 ++++++++++++++-
 apps/web/app/sitemap.ts                       |  1 -
 apps/web/components/command-directory.tsx     | 59 +++++++++++++
 apps/web/components/docs-shell.tsx            | 65 +++++++++------
 apps/web/lib/repository-content.d.mts         | 17 +++-
 apps/web/lib/repository-content.mjs           | 82 +++++++++++++++++--
 .../scripts/validate-content-provenance.mjs   |  2 +-
 9 files changed, 266 insertions(+), 57 deletions(-)
 create mode 100644 apps/web/components/command-directory.tsx

diff --git a/apps/web/app/docs/commands/page.tsx b/apps/web/app/docs/commands/page.tsx
index 11e5c3f..5d9cbb2 100644
--- a/apps/web/app/docs/commands/page.tsx
+++ b/apps/web/app/docs/commands/page.tsx
@@ -1,6 +1,5 @@
-import { CommandBlock } from "@/components/docs-copy-controls";
+import { CommandDirectory } from "@/components/command-directory";
 import { DocsShell } from "@/components/docs-shell";
-import { plainText } from "@/lib/markdown";
 import { loadProductDocsContent } from "@/lib/repository-content.mjs";
 import { docsMetadata } from "@/lib/site-metadata";
 
@@ -15,23 +14,15 @@ export default function CommandsPage() {
   return (
     <DocsShell
       activePath="/docs/commands"
+      sections={commands.groups.map((group) => ({
+        id: group.id,
+        label: group.title,
+      }))}
       kicker={`${commands.count} command forms`}
       title={<>The complete agent surface.</>}
       lede="These usage lines come from the generated command reference, which protocol tests keep in sync with the CLI help output. Unknown parameters fail closed."
     >
-      {commands.groups.map((group, index) => (
-        <section
-          id={group.title.toLowerCase().replaceAll(" ", "-")}
-          key={group.title}
-        >
-          <p className="docs-label">
-            {String(index + 1).padStart(2, "0")} / {group.title}
-          </p>
-          <h2>{group.title}</h2>
-          <p>{plainText(group.description)}</p>
-          <CommandBlock>{group.usage}</CommandBlock>
-        </section>
-      ))}
+      <CommandDirectory groups={commands.groups} />
     </DocsShell>
   );
 }
diff --git a/apps/web/app/docs/page.tsx b/apps/web/app/docs/page.tsx
index 7a1fd37..0d13b29 100644
--- a/apps/web/app/docs/page.tsx
+++ b/apps/web/app/docs/page.tsx
@@ -16,6 +16,14 @@ export default function DocsPage() {
   return (
     <DocsShell
       activePath="/docs"
+      sections={[
+        { id: "first-run", label: "First run" },
+        { id: "workflow", label: "QA workflow" },
+        { id: "commands", label: "Command groups" },
+        { id: "context", label: "Context pruning" },
+        { id: "scrollable", label: "Scrollable evidence" },
+        { id: "safety", label: "Safety" },
+      ]}
       kicker="Headless documentation"
       title={
         <>
@@ -31,8 +39,8 @@ export default function DocsPage() {
         <p className="docs-label">01 / First run</p>
         <h2>Start a session.</h2>
         <p>
-          Start the host, create a session, then visit the app. The session
-          stays isolated until you close it.
+          Start the host, create a session, then visit the app.{" "}
+          {plainText(documentation.sessionModel)}
         </p>
         <CommandBlock>{documentation.firstRunCommands}</CommandBlock>
         <p>{plainText(documentation.startupPresentation)}</p>
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index 4ab0d21..132141f 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -1248,6 +1248,19 @@ h3,
   width: min(1180px, calc(100% - 48px));
   margin: 0 auto;
 }
+.skip-link {
+  position: absolute;
+  left: 16px;
+  top: 12px;
+  z-index: 20;
+  padding: 8px 12px;
+  background: var(--amber);
+  color: var(--ink-on-amber);
+  transform: translateY(-150%);
+}
+.skip-link:focus {
+  transform: none;
+}
 .docs-nav {
   height: 84px;
   display: flex;
@@ -1286,14 +1299,55 @@ h3,
   font-family: var(--font-mono), monospace;
   font-size: 12px;
 }
+.docs-nav-group,
+.docs-toc {
+  display: flex;
+  flex-direction: column;
+  gap: 11px;
+}
+.docs-nav-group + .docs-nav-group,
+.docs-toc {
+  margin-top: 30px;
+}
 .docs-sidebar p {
   margin: 0 0 6px;
   color: var(--amber-ink);
   font-size: 9px;
   letter-spacing: 0.12em;
+  text-transform: uppercase;
 }
-.docs-sidebar p:not(:first-child) {
-  margin-top: 30px;
+.command-filter {
+  display: grid;
+  gap: 8px;
+  margin: 0 0 42px;
+}
+.command-filter label {
+  font-family: var(--font-mono), monospace;
+  font-size: 11px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--amber-ink);
+}
+.command-filter input {
+  width: 100%;
+  min-height: 42px;
+  padding: 0 12px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  background: var(--panel);
+  color: var(--ink);
+  font-family: var(--font-mono), monospace;
+  font-size: 13px;
+}
+.command-filter input:focus {
+  outline: 2px solid var(--amber);
+  outline-offset: 2px;
+}
+.command-filter p {
+  margin: 0;
+  color: var(--muted);
+  font-family: var(--font-mono), monospace;
+  font-size: 11px;
 }
 .docs-sidebar a:hover {
   color: var(--ink);
@@ -1934,9 +1988,13 @@ h3,
     padding-bottom: 12px;
     overflow-x: auto;
   }
-  .docs-sidebar p {
+  .docs-sidebar p,
+  .docs-toc {
     display: none;
   }
+  .docs-nav-group {
+    display: contents;
+  }
   .docs-sidebar a {
     flex: 0 0 auto;
     padding: 7px 9px;
diff --git a/apps/web/app/sitemap.ts b/apps/web/app/sitemap.ts
index 2584fb0..ad2ac98 100644
--- a/apps/web/app/sitemap.ts
+++ b/apps/web/app/sitemap.ts
@@ -5,7 +5,6 @@ import type { MetadataRoute } from "next";
 export default function sitemap(): MetadataRoute.Sitemap {
   const routes = [
     "/",
-    "/docs",
     "/docs/markdown",
     ...PRODUCT_DOC_ROUTES.map(({ href }) => href),
   ];
diff --git a/apps/web/components/command-directory.tsx b/apps/web/components/command-directory.tsx
new file mode 100644
index 0000000..5d419a2
--- /dev/null
+++ b/apps/web/components/command-directory.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import { CommandBlock } from "@/components/docs-copy-controls";
+import { plainText } from "@/lib/markdown";
+import { useMemo, useState } from "react";
+
+type CommandGroup = {
+  title: string;
+  id: string;
+  description: string;
+  usage: string;
+};
+
+export function CommandDirectory({ groups }: { groups: CommandGroup[] }) {
+  const [query, setQuery] = useState("");
+  const normalized = query.trim().toLowerCase();
+  const visible = useMemo(() => {
+    if (!normalized) return groups;
+    return groups.filter((group) =>
+      `${group.title} ${group.description} ${group.usage}`
+        .toLowerCase()
+        .includes(normalized),
+    );
+  }, [groups, normalized]);
+
+  return (
+    <>
+      <div className="command-filter">
+        <label htmlFor="command-filter">Filter commands</label>
+        <input
+          id="command-filter"
+          type="search"
+          value={query}
+          onChange={(event) => setQuery(event.target.value)}
+          placeholder="visit, inspect, record…"
+          autoComplete="off"
+          spellCheck={false}
+        />
+        <p>
+          {visible.length} of {groups.length} groups
+        </p>
+      </div>
+      {visible.length === 0 ? (
+        <p role="status">No commands match “{query}”.</p>
+      ) : (
+        visible.map((group, index) => (
+          <section id={group.id} key={group.id}>
+            <p className="docs-label">
+              {String(index + 1).padStart(2, "0")} / {group.title}
+            </p>
+            <h2>{group.title}</h2>
+            <p>{plainText(group.description)}</p>
+            <CommandBlock>{group.usage}</CommandBlock>
+          </section>
+        ))
+      )}
+    </>
+  );
+}
diff --git a/apps/web/components/docs-shell.tsx b/apps/web/components/docs-shell.tsx
index 05d1741..d010175 100644
--- a/apps/web/components/docs-shell.tsx
+++ b/apps/web/components/docs-shell.tsx
@@ -1,7 +1,10 @@
 import { HeadlessMark } from "@/components/headless-mark";
 import { LinkGlyph } from "@/components/link-glyph";
 import { ThemeToggle } from "@/components/theme-toggle";
-import { PRODUCT_DOC_ROUTES } from "@/lib/repository-content.mjs";
+import {
+  PRODUCT_DOC_CATEGORIES,
+  PRODUCT_DOC_ROUTES,
+} from "@/lib/repository-content.mjs";
 import Link from "next/link";
 
 export function DocumentationTable({
@@ -42,6 +45,7 @@ export function DocsShell({
   lede,
   children,
   headingAction,
+  sections,
 }: {
   activePath: string;
   kicker: string;
@@ -49,9 +53,13 @@ export function DocsShell({
   lede: string;
   children: React.ReactNode;
   headingAction?: React.ReactNode;
+  sections?: Array<{ id: string; label: string }>;
 }) {
   return (
     <main className="docs-shell">
+      <a className="skip-link" href="#docs-content">
+        Skip to content
+      </a>
       <nav
         className="docs-nav docs-container"
         aria-label="Documentation navigation"
@@ -62,7 +70,10 @@ export function DocsShell({
         </Link>
         <div>
           <Link href="/">Overview</Link>
-          <Link className="active" href="/docs">
+          <Link
+            className={activePath.startsWith("/docs") ? "active" : ""}
+            href="/docs"
+          >
             Docs
           </Link>
           <a
@@ -77,32 +88,36 @@ export function DocsShell({
 
       <div className="docs-container docs-layout">
         <aside className="docs-sidebar" aria-label="Documentation sections">
-          <p>DOCUMENTATION</p>
-          <Link className={activePath === "/docs" ? "active" : ""} href="/docs">
-            Overview
-          </Link>
-          {PRODUCT_DOC_ROUTES.slice(0, 3).map((route) => (
-            <Link
-              className={activePath === route.href ? "active" : ""}
-              href={route.href}
-              key={route.href}
-            >
-              {route.label}
-            </Link>
-          ))}
-          <p>TRUST &amp; SUPPORT</p>
-          {PRODUCT_DOC_ROUTES.slice(3).map((route) => (
-            <Link
-              className={activePath === route.href ? "active" : ""}
-              href={route.href}
-              key={route.href}
-            >
-              {route.label}
-            </Link>
+          {PRODUCT_DOC_CATEGORIES.map((category) => (
+            <div className="docs-nav-group" key={category.id}>
+              <p>{category.label}</p>
+              {PRODUCT_DOC_ROUTES.filter(
+                (route) => route.category === category.id,
+              ).map((route) => (
+                <Link
+                  className={activePath === route.href ? "active" : ""}
+                  href={route.href}
+                  key={route.href}
+                  aria-current={activePath === route.href ? "page" : undefined}
+                >
+                  {route.label}
+                </Link>
+              ))}
+            </div>
           ))}
+          {sections && sections.length > 0 ? (
+            <nav className="docs-toc" aria-label="On this page">
+              <p>On this page</p>
+              {sections.map((section) => (
+                <a href={`#${section.id}`} key={section.id}>
+                  {section.label}
+                </a>
+              ))}
+            </nav>
+          ) : null}
         </aside>
 
-        <article className="docs-content">
+        <article className="docs-content" id="docs-content" tabIndex={-1}>
           <div className="docs-heading-row">
             <div className="docs-kicker">
               <span className="status-dot" /> {kicker}
diff --git a/apps/web/lib/repository-content.d.mts b/apps/web/lib/repository-content.d.mts
index 4645fdb..8860600 100644
--- a/apps/web/lib/repository-content.d.mts
+++ b/apps/web/lib/repository-content.d.mts
@@ -35,12 +35,14 @@ export type BenchmarkContent = {
 export type DocumentationContent = {
   introduction: string;
   firstRunCommands: string;
+  sessionModel: string;
   qaWorkflowCommands: string;
   startupPresentation: string;
   contextPruning: string;
   scrollableEvidence: string;
   commandGroups: Array<{
     title: string;
+    id: string;
     commands: string;
     description: string;
     usage: string;
@@ -53,13 +55,19 @@ export type DocumentationContent = {
 export type MarkdownTable = { headers: string[]; rows: string[][] };
 
 export type ProductDocsContent = {
-  routes: Array<{ href: string; label: string }>;
+  routes: Array<{ href: string; label: string; category: string }>;
   version: string;
   protocolVersion: string;
   install: Array<{ title: string; copy: string[]; commands: string[] }>;
   commands: {
     count: number;
     groups: DocumentationContent["commandGroups"];
+    forms: Array<{
+      group: string;
+      groupId: string;
+      form: string;
+      description: string;
+    }>;
   };
   mcp: { copy: string[]; commands: string[]; config: string };
   security: {
@@ -81,7 +89,12 @@ export type ProductDocsContent = {
   releases: Array<ProductDocsContent["release"]>;
 };
 
-export const PRODUCT_DOC_ROUTES: Array<{ href: string; label: string }>;
+export const PRODUCT_DOC_CATEGORIES: Array<{ id: string; label: string }>;
+export const PRODUCT_DOC_ROUTES: Array<{
+  href: string;
+  label: string;
+  category: string;
+}>;
 
 export function loadBenchmarkContent(): BenchmarkContent;
 export function loadDocumentationContent(): DocumentationContent;
diff --git a/apps/web/lib/repository-content.mjs b/apps/web/lib/repository-content.mjs
index bda9366..2863c49 100644
--- a/apps/web/lib/repository-content.mjs
+++ b/apps/web/lib/repository-content.mjs
@@ -23,13 +23,19 @@ let benchmarkCache;
 let documentationCache;
 let productDocsCache;
 
+export const PRODUCT_DOC_CATEGORIES = [
+  { id: "documentation", label: "Documentation" },
+  { id: "trust", label: "Trust & support" },
+];
+
 export const PRODUCT_DOC_ROUTES = [
-  { href: "/docs/install", label: "Install" },
-  { href: "/docs/mcp", label: "MCP setup" },
-  { href: "/docs/commands", label: "Commands" },
-  { href: "/docs/security", label: "Security" },
-  { href: "/docs/platforms", label: "Platforms" },
-  { href: "/docs/changelog", label: "Changelog" },
+  { href: "/docs", label: "Overview", category: "documentation" },
+  { href: "/docs/install", label: "Install", category: "documentation" },
+  { href: "/docs/mcp", label: "MCP setup", category: "documentation" },
+  { href: "/docs/commands", label: "Commands", category: "documentation" },
+  { href: "/docs/security", label: "Security", category: "trust" },
+  { href: "/docs/platforms", label: "Platforms", category: "trust" },
+  { href: "/docs/changelog", label: "Changelog", category: "trust" },
 ];
 
 function fail(message) {
@@ -385,7 +391,30 @@ function commandGroup(commandReference, title) {
   const usage = fencedCode(section);
   const description = bulletItems(section)[0];
   if (!description) fail(`missing command description: ${title}`);
-  return { title, commands: commandNames(usage), description, usage };
+  return {
+    title,
+    id: title.toLowerCase().replaceAll(" ", "-"),
+    commands: commandNames(usage),
+    description,
+    usage,
+  };
+}
+
+function listCommandForms(groups) {
+  return groups.flatMap((group) =>
+    group.usage
+      .split("\n")
+      .filter((line) => line && !/^\s/.test(line))
+      .flatMap((line) => line.split(" | "))
+      .map((form) => form.trim())
+      .filter((form) => form && form !== "--version")
+      .map((form) => ({
+        group: group.title,
+        groupId: group.id,
+        form,
+        description: group.description,
+      })),
+  );
 }
 
 function markdownForDocumentation(content) {
@@ -405,6 +434,8 @@ ${content.introduction}
 ${content.firstRunCommands}
 \`\`\`
 
+${content.sessionModel}
+
 ${content.startupPresentation}
 
 ## QA workflow
@@ -438,6 +469,15 @@ export function loadDocumentationContent() {
   if (documentationCache) return documentationCache;
   const readme = readRepositoryFile("README.md");
   const commandReference = readRepositoryFile("apps/headless/docs/COMMANDS.md");
+  const sessionModel = bulletItems(
+    extractSection(commandReference, "Host lifecycle"),
+  ).find(
+    (item) =>
+      item.includes("one browser profile") && item.includes("not an isolation"),
+  );
+  if (!sessionModel) {
+    fail("COMMANDS.md is missing the shared-profile session contract");
+  }
   const workflowSection = extractSection(readme, "Agent workflow");
   const workflowCommands = fencedCode(workflowSection)
     .split("\n")
@@ -469,6 +509,7 @@ export function loadDocumentationContent() {
   const content = {
     introduction: paragraphStarting(readme, "Persistent browser control"),
     firstRunCommands,
+    sessionModel,
     qaWorkflowCommands,
     startupPresentation: paragraphStarting(workflowSection, "On macOS"),
     contextPruning: paragraphStarting(
@@ -641,7 +682,11 @@ export function loadProductDocsContent() {
     version: packageDocument.version,
     protocolVersion: protocolMatch[1],
     install,
-    commands: { groups: commandGroups, count: commandForms },
+    commands: {
+      groups: commandGroups,
+      count: commandForms,
+      forms: listCommandForms(commandGroups),
+    },
     mcp: {
       copy: mcpCopy,
       commands: mcpCommands,
@@ -708,12 +753,33 @@ export function validateRepositoryContent() {
       fail(`benchmark method row is stale: ${workflow.label}`);
     }
   }
+  const docsShell = readRepositoryFile("apps/web/components/docs-shell.tsx");
+  const docsOverview = readRepositoryFile("apps/web/app/docs/page.tsx");
+  if (docsShell.includes(".slice(")) {
+    fail("docs navigation must not slice route arrays by position");
+  }
+  if (/stays isolated/i.test(docsOverview)) {
+    fail("docs overview must not describe sessions as isolated");
+  }
+  if (!docsOverview.includes("sessionModel")) {
+    fail("docs overview must render the COMMANDS.md session contract");
+  }
+  const categoryIds = new Set(PRODUCT_DOC_CATEGORIES.map((category) => category.id));
+  if (categoryIds.size !== PRODUCT_DOC_CATEGORIES.length) {
+    fail("documentation categories must have unique ids");
+  }
   for (const route of productDocs.routes) {
+    if (!categoryIds.has(route.category)) {
+      fail(`documentation route is missing a declared category: ${route.href}`);
+    }
     const page = readRepositoryFile(`apps/web/app${route.href}/page.tsx`);
     if (!page.includes("export const metadata")) {
       fail(`product documentation route lacks metadata: ${route.href}`);
     }
   }
+  if (productDocs.commands.forms.length !== productDocs.commands.count) {
+    fail("command directory forms drifted from the generated command count");
+  }
   for (const convention of ["not-found.tsx", "robots.ts", "sitemap.ts"]) {
     readRepositoryFile(`apps/web/app/${convention}`);
   }
diff --git a/apps/web/scripts/validate-content-provenance.mjs b/apps/web/scripts/validate-content-provenance.mjs
index 8b2c26d..99cad2a 100644
--- a/apps/web/scripts/validate-content-provenance.mjs
+++ b/apps/web/scripts/validate-content-provenance.mjs
@@ -5,7 +5,7 @@ if (
   result.benchmarkCases !== 4 ||
   result.commandGroups !== 4 ||
   result.securityRules < 3 ||
-  result.productDocRoutes !== 6 ||
+  result.productDocRoutes !== 7 ||
   result.commandForms < 30 ||
   result.installMethods !== 4 ||
   result.securityBoundaries < 5 ||

From 4efb48d947bdfeb09e4288fdfed920e06f854e3e Mon Sep 17 00:00:00 2001
From: Aditya Garud <153842990+yashranaway@users.noreply.github.com>
Date: Sat, 12 Sep 2026 09:07:33 +0000
Subject: [PATCH 2/5] fix(web): keep command directory in sync with COMMANDS.md

Extract the session contract from the current shared-profile wording,
include the Credential vault section, drive the on-page TOC from the
filter, and announce result counts to assistive technology.
---
 apps/web/app/docs/commands/page.tsx           |  4 --
 apps/web/app/globals.css                      |  5 +-
 apps/web/components/command-directory.tsx     | 45 ++++++++-----
 apps/web/lib/repository-content.d.mts         |  1 +
 apps/web/lib/repository-content.mjs           | 66 ++++++++++++-------
 apps/web/package.json                         |  2 +-
 .../scripts/validate-command-directory.mjs    | 41 ++++++++++++
 .../scripts/validate-content-provenance.mjs   |  2 +-
 8 files changed, 119 insertions(+), 47 deletions(-)
 create mode 100644 apps/web/scripts/validate-command-directory.mjs

diff --git a/apps/web/app/docs/commands/page.tsx b/apps/web/app/docs/commands/page.tsx
index 5d9cbb2..585d7a6 100644
--- a/apps/web/app/docs/commands/page.tsx
+++ b/apps/web/app/docs/commands/page.tsx
@@ -14,10 +14,6 @@ export default function CommandsPage() {
   return (
     <DocsShell
       activePath="/docs/commands"
-      sections={commands.groups.map((group) => ({
-        id: group.id,
-        label: group.title,
-      }))}
       kicker={`${commands.count} command forms`}
       title={<>The complete agent surface.</>}
       lede="These usage lines come from the generated command reference, which protocol tests keep in sync with the CLI help output. Unknown parameters fail closed."
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index 132141f..0479b3d 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -1309,6 +1309,9 @@ h3,
 .docs-toc {
   margin-top: 30px;
 }
+.docs-toc-inline {
+  margin: 0 0 42px;
+}
 .docs-sidebar p {
   margin: 0 0 6px;
   color: var(--amber-ink);
@@ -1989,7 +1992,7 @@ h3,
     overflow-x: auto;
   }
   .docs-sidebar p,
-  .docs-toc {
+  .docs-sidebar .docs-toc {
     display: none;
   }
   .docs-nav-group {
diff --git a/apps/web/components/command-directory.tsx b/apps/web/components/command-directory.tsx
index 5d419a2..fcde55f 100644
--- a/apps/web/components/command-directory.tsx
+++ b/apps/web/components/command-directory.tsx
@@ -23,6 +23,11 @@ export function CommandDirectory({ groups }: { groups: CommandGroup[] }) {
     );
   }, [groups, normalized]);
 
+  const countLabel =
+    visible.length === 0
+      ? `No commands match “${query}”.`
+      : `${visible.length} of ${groups.length} groups`;
+
   return (
     <>
       <div className="command-filter">
@@ -32,28 +37,34 @@ export function CommandDirectory({ groups }: { groups: CommandGroup[] }) {
           type="search"
           value={query}
           onChange={(event) => setQuery(event.target.value)}
-          placeholder="visit, inspect, record…"
+          placeholder="visit, inspect, credentials…"
           autoComplete="off"
           spellCheck={false}
         />
-        <p>
-          {visible.length} of {groups.length} groups
+        <p role="status" aria-live="polite">
+          {countLabel}
         </p>
       </div>
-      {visible.length === 0 ? (
-        <p role="status">No commands match “{query}”.</p>
-      ) : (
-        visible.map((group, index) => (
-          <section id={group.id} key={group.id}>
-            <p className="docs-label">
-              {String(index + 1).padStart(2, "0")} / {group.title}
-            </p>
-            <h2>{group.title}</h2>
-            <p>{plainText(group.description)}</p>
-            <CommandBlock>{group.usage}</CommandBlock>
-          </section>
-        ))
-      )}
+      {visible.length > 0 ? (
+        <nav className="docs-toc docs-toc-inline" aria-label="On this page">
+          <p>On this page</p>
+          {visible.map((group) => (
+            <a href={`#${group.id}`} key={group.id}>
+              {group.title}
+            </a>
+          ))}
+        </nav>
+      ) : null}
+      {visible.map((group, index) => (
+        <section id={group.id} key={group.id}>
+          <p className="docs-label">
+            {String(index + 1).padStart(2, "0")} / {group.title}
+          </p>
+          <h2>{group.title}</h2>
+          <p>{plainText(group.description)}</p>
+          <CommandBlock>{group.usage}</CommandBlock>
+        </section>
+      ))}
     </>
   );
 }
diff --git a/apps/web/lib/repository-content.d.mts b/apps/web/lib/repository-content.d.mts
index 8860600..407e479 100644
--- a/apps/web/lib/repository-content.d.mts
+++ b/apps/web/lib/repository-content.d.mts
@@ -96,6 +96,7 @@ export const PRODUCT_DOC_ROUTES: Array<{
   category: string;
 }>;
 
+export function sessionModelFromCommands(commandReference: string): string;
 export function loadBenchmarkContent(): BenchmarkContent;
 export function loadDocumentationContent(): DocumentationContent;
 export function loadProductDocsContent(): ProductDocsContent;
diff --git a/apps/web/lib/repository-content.mjs b/apps/web/lib/repository-content.mjs
index 2863c49..fc7f857 100644
--- a/apps/web/lib/repository-content.mjs
+++ b/apps/web/lib/repository-content.mjs
@@ -389,17 +389,43 @@ function commandNames(usage) {
 function commandGroup(commandReference, title) {
   const section = extractSection(commandReference, title);
   const usage = fencedCode(section);
-  const description = bulletItems(section)[0];
+  if (!usage) fail(`missing command usage fence: ${title}`);
+  const description = bulletItems(section)[0] || paragraphs(section)[0];
   if (!description) fail(`missing command description: ${title}`);
   return {
     title,
-    id: title.toLowerCase().replaceAll(" ", "-"),
+    id: title.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
     commands: commandNames(usage),
     description,
     usage,
   };
 }
 
+function commandGroupsFromReference(commandReference) {
+  const titles = [...commandReference.matchAll(/^## (.+)$/gm)].map(
+    (match) => match[1],
+  );
+  return titles.flatMap((title) => {
+    if (title === "Where to go next") return [];
+    const usage = fencedCodeBlocks(extractSection(commandReference, title))[0];
+    return usage ? [commandGroup(commandReference, title)] : [];
+  });
+}
+
+export function sessionModelFromCommands(commandReference) {
+  const lifecycle = extractSection(commandReference, "Host lifecycle");
+  const shared = bulletItems(lifecycle).find((item) =>
+    /one browser profile/i.test(item),
+  );
+  if (!shared) {
+    fail("COMMANDS.md is missing the shared-profile session contract");
+  }
+  if (/stays isolated until you close it/i.test(shared)) {
+    fail("session contract must not claim sessions stay isolated");
+  }
+  return shared;
+}
+
 function listCommandForms(groups) {
   return groups.flatMap((group) =>
     group.usage
@@ -469,15 +495,7 @@ export function loadDocumentationContent() {
   if (documentationCache) return documentationCache;
   const readme = readRepositoryFile("README.md");
   const commandReference = readRepositoryFile("apps/headless/docs/COMMANDS.md");
-  const sessionModel = bulletItems(
-    extractSection(commandReference, "Host lifecycle"),
-  ).find(
-    (item) =>
-      item.includes("one browser profile") && item.includes("not an isolation"),
-  );
-  if (!sessionModel) {
-    fail("COMMANDS.md is missing the shared-profile session contract");
-  }
+  const sessionModel = sessionModelFromCommands(commandReference);
   const workflowSection = extractSection(readme, "Agent workflow");
   const workflowCommands = fencedCode(workflowSection)
     .split("\n")
@@ -520,12 +538,7 @@ export function loadDocumentationContent() {
       workflowSection,
       "For scrollable-page QA",
     ),
-    commandGroups: [
-      commandGroup(commandReference, "Host lifecycle"),
-      commandGroup(commandReference, "Navigation and interaction"),
-      commandGroup(commandReference, "Capture and evidence"),
-      commandGroup(commandReference, "Diagnostics"),
-    ],
+    commandGroups: commandGroupsFromReference(commandReference),
     security: bulletItems(extractSection(readme, "Security boundary")),
     platforms: bulletItems(
       readme.slice(0, readme.indexOf("## Computer use comparison")),
@@ -586,12 +599,7 @@ export function loadProductDocsContent() {
     fail("Headless MCP configuration is malformed");
   }
 
-  const commandGroups = [
-    commandGroup(commandReference, "Host lifecycle"),
-    commandGroup(commandReference, "Navigation and interaction"),
-    commandGroup(commandReference, "Capture and evidence"),
-    commandGroup(commandReference, "Diagnostics"),
-  ];
+  const commandGroups = commandGroupsFromReference(commandReference);
   const commandForms = commandFormCount(commandGroups);
   if (commandForms < 30) fail("command reference contains fewer than 30 forms");
 
@@ -780,6 +788,18 @@ export function validateRepositoryContent() {
   if (productDocs.commands.forms.length !== productDocs.commands.count) {
     fail("command directory forms drifted from the generated command count");
   }
+  sessionModelFromCommands(readRepositoryFile("apps/headless/docs/COMMANDS.md"));
+  if (
+    !productDocs.commands.groups.some((group) => group.title === "Credential vault")
+  ) {
+    fail("command directory omitted the Credential vault section");
+  }
+  const directory = readRepositoryFile(
+    "apps/web/components/command-directory.tsx",
+  );
+  if (!directory.includes('role="status"')) {
+    fail("command directory must announce filter result counts");
+  }
   for (const convention of ["not-found.tsx", "robots.ts", "sitemap.ts"]) {
     readRepositoryFile(`apps/web/app/${convention}`);
   }
diff --git a/apps/web/package.json b/apps/web/package.json
index c28013b..9f354b4 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -6,7 +6,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
+    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-command-directory.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
     "brand": "node scripts/render-brand.mjs"
   },
   "dependencies": {
diff --git a/apps/web/scripts/validate-command-directory.mjs b/apps/web/scripts/validate-command-directory.mjs
new file mode 100644
index 0000000..6a6d51e
--- /dev/null
+++ b/apps/web/scripts/validate-command-directory.mjs
@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  loadProductDocsContent,
+  sessionModelFromCommands,
+} from "../lib/repository-content.mjs";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "../../..");
+const commands = await readFile(
+  join(root, "apps/headless/docs/COMMANDS.md"),
+  "utf8",
+);
+const directory = await readFile(
+  join(root, "apps/web/components/command-directory.tsx"),
+  "utf8",
+);
+
+const sessionModel = sessionModelFromCommands(commands);
+assert.match(sessionModel, /one browser profile/i);
+assert.doesNotMatch(sessionModel, /stays isolated until you close it/i);
+
+const { commands: surface } = loadProductDocsContent();
+assert.ok(
+  surface.groups.some((group) => group.title === "Credential vault"),
+  "command directory must include Credential vault",
+);
+assert.ok(
+  surface.groups.some((group) => /auth login/.test(group.usage)),
+  "command directory must include auth login",
+);
+assert.match(directory, /role="status"/);
+assert.match(directory, /aria-live="polite"/);
+assert.match(directory, /docs-toc-inline/);
+assert.doesNotMatch(
+  await readFile(join(root, "apps/web/app/docs/commands/page.tsx"), "utf8"),
+  /sections=\{commands\.groups/,
+);
+
+console.log("command directory search and accessibility checks passed");
diff --git a/apps/web/scripts/validate-content-provenance.mjs b/apps/web/scripts/validate-content-provenance.mjs
index 99cad2a..f21609b 100644
--- a/apps/web/scripts/validate-content-provenance.mjs
+++ b/apps/web/scripts/validate-content-provenance.mjs
@@ -3,7 +3,7 @@ import { validateRepositoryContent } from "../lib/repository-content.mjs";
 const result = validateRepositoryContent();
 if (
   result.benchmarkCases !== 4 ||
-  result.commandGroups !== 4 ||
+  result.commandGroups < 5 ||
   result.securityRules < 3 ||
   result.productDocRoutes !== 7 ||
   result.commandForms < 30 ||

From 721c1389cc5276c8aad1017294fb007cf78031e1 Mon Sep 17 00:00:00 2001
From: SarthakWade <sarthakssg5@gmail.com>
Date: Sat, 12 Sep 2026 16:59:45 +0530
Subject: [PATCH 3/5] test(web): exercise command directory behavior

---
 apps/web/package.json                         |   3 +-
 apps/web/scripts/command-directory.test.mjs   | 219 ++++++++++++++++++
 apps/web/scripts/component-test-loader.mjs    |  67 ++++++
 .../scripts/validate-command-directory.mjs    |  10 +-
 pnpm-lock.yaml                                |   3 +
 5 files changed, 292 insertions(+), 10 deletions(-)
 create mode 100644 apps/web/scripts/command-directory.test.mjs
 create mode 100644 apps/web/scripts/component-test-loader.mjs

diff --git a/apps/web/package.json b/apps/web/package.json
index 9f354b4..ad05e6c 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -6,7 +6,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-command-directory.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
+    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-command-directory.mjs && node --test scripts/command-directory.test.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
     "brand": "node scripts/render-brand.mjs"
   },
   "dependencies": {
@@ -24,6 +24,7 @@
     "@types/react-dom": "^19.2.7",
     "eslint": "^9.36.0",
     "eslint-config-next": "^16.3.3",
+    "jsdom": "30.0.1",
     "tailwindcss": "^4.1.11",
     "typescript": "^6.0.3"
   }
diff --git a/apps/web/scripts/command-directory.test.mjs b/apps/web/scripts/command-directory.test.mjs
new file mode 100644
index 0000000..b82bb84
--- /dev/null
+++ b/apps/web/scripts/command-directory.test.mjs
@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import * as nodeModule from "node:module";
+import test from "node:test";
+import { JSDOM } from "jsdom";
+import * as componentTestLoader from "./component-test-loader.mjs";
+import { loadProductDocsContent } from "../lib/repository-content.mjs";
+
+if (typeof nodeModule.registerHooks === "function") {
+  nodeModule.registerHooks(componentTestLoader);
+} else {
+  nodeModule.register("./component-test-loader.mjs", import.meta.url);
+}
+
+const { groups } = loadProductDocsContent().commands;
+
+async function renderDirectory({ width = 1280 } = {}) {
+  const dom = new JSDOM('<div id="root"></div>', {
+    pretendToBeVisual: true,
+    url: "https://headless.test/docs/commands",
+  });
+  Object.defineProperty(dom.window, "innerWidth", {
+    configurable: true,
+    value: width,
+  });
+
+  const previousGlobals = new Map();
+  for (const name of [
+    "document",
+    "Event",
+    "HTMLElement",
+    "HTMLInputElement",
+    "InputEvent",
+    "KeyboardEvent",
+    "Node",
+    "navigator",
+    "window",
+  ]) {
+    previousGlobals.set(name, Object.getOwnPropertyDescriptor(globalThis, name));
+    Object.defineProperty(globalThis, name, {
+      configurable: true,
+      value: dom.window[name],
+      writable: true,
+    });
+  }
+  previousGlobals.set(
+    "IS_REACT_ACT_ENVIRONMENT",
+    Object.getOwnPropertyDescriptor(globalThis, "IS_REACT_ACT_ENVIRONMENT"),
+  );
+  Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+    configurable: true,
+    value: true,
+    writable: true,
+  });
+
+  const [{ act, createElement }, { createRoot }, { CommandDirectory }] =
+    await Promise.all([
+      import("react"),
+      import("react-dom/client"),
+      import("@/components/command-directory"),
+    ]);
+  const container = dom.window.document.querySelector("#root");
+  const root = createRoot(container);
+  await act(() => root.render(createElement(CommandDirectory, { groups })));
+
+  return {
+    act,
+    document: dom.window.document,
+    input: dom.window.document.querySelector("input[type=search]"),
+    async cleanup() {
+      await act(() => root.unmount());
+      dom.window.close();
+      for (const [name, descriptor] of previousGlobals) {
+        if (descriptor === undefined) delete globalThis[name];
+        else Object.defineProperty(globalThis, name, descriptor);
+      }
+    },
+  };
+}
+
+async function typeWithKeyboard(view, value) {
+  const valueSetter = Object.getOwnPropertyDescriptor(
+    view.input.ownerDocument.defaultView.HTMLInputElement.prototype,
+    "value",
+  ).set;
+
+  view.input.focus();
+  await view.act(() => {
+    for (let index = 0; index < value.length; index += 1) {
+      const key = value[index];
+      view.input.dispatchEvent(
+        new KeyboardEvent("keydown", { bubbles: true, key }),
+      );
+      valueSetter.call(view.input, value.slice(0, index + 1));
+      view.input.dispatchEvent(
+        new InputEvent("input", {
+          bubbles: true,
+          data: key,
+          inputType: "insertText",
+        }),
+      );
+      view.input.dispatchEvent(
+        new KeyboardEvent("keyup", { bubbles: true, key }),
+      );
+    }
+  });
+}
+
+async function replaceSearch(view, value) {
+  const valueSetter = Object.getOwnPropertyDescriptor(
+    view.input.ownerDocument.defaultView.HTMLInputElement.prototype,
+    "value",
+  ).set;
+  await view.act(() => {
+    valueSetter.call(view.input, value);
+    view.input.dispatchEvent(
+      new InputEvent("input", {
+        bubbles: true,
+        data: value,
+        inputType: "insertReplacementText",
+      }),
+    );
+  });
+}
+
+function assertTocTargetsExist(document) {
+  for (const link of document.querySelectorAll("nav[aria-label='On this page'] a")) {
+    assert.ok(
+      document.querySelector(link.hash),
+      `table-of-contents target ${link.hash} must exist`,
+    );
+  }
+}
+
+test("filters real command groups from keyboard input and updates accessible status", async () => {
+  const view = await renderDirectory();
+  try {
+    const label = view.document.querySelector("label[for=command-filter]");
+    const status = view.document.querySelector("[role=status]");
+
+    assert.equal(label.control, view.input);
+    assert.equal(view.input.tabIndex, 0);
+    assert.equal(status.getAttribute("aria-live"), "polite");
+    assert.equal(status.textContent, `${groups.length} of ${groups.length} groups`);
+    assertTocTargetsExist(view.document);
+
+    await typeWithKeyboard(view, "auth login");
+
+    assert.equal(view.document.activeElement, view.input);
+    assert.equal(status.textContent, `1 of ${groups.length} groups`);
+    assert.deepEqual(
+      [...view.document.querySelectorAll("section h2")].map(
+        (heading) => heading.textContent,
+      ),
+      ["Credential vault"],
+    );
+    assert.deepEqual(
+      [...view.document.querySelectorAll("nav[aria-label='On this page'] a")].map(
+        (link) => link.textContent,
+      ),
+      ["Credential vault"],
+    );
+    assertTocTargetsExist(view.document);
+  } finally {
+    await view.cleanup();
+  }
+});
+
+test("handles normalized queries, no matches, and clearing without stale links", async () => {
+  const view = await renderDirectory();
+  try {
+    const status = view.document.querySelector("[role=status]");
+
+    await replaceSearch(view, "  SCREENSHOT  ");
+    assert.equal(status.textContent, `1 of ${groups.length} groups`);
+    assert.equal(
+      view.document.querySelector("section")?.id,
+      "capture-and-evidence",
+    );
+    assertTocTargetsExist(view.document);
+
+    await replaceSearch(view, "not-a-command");
+    assert.equal(status.textContent, "No commands match “not-a-command”.");
+    assert.equal(view.document.querySelector("section"), null);
+    assert.equal(view.document.querySelector("nav[aria-label='On this page']"), null);
+
+    await replaceSearch(view, "");
+    assert.equal(status.textContent, `${groups.length} of ${groups.length} groups`);
+    assert.equal(view.document.querySelectorAll("section").length, groups.length);
+    assertTocTargetsExist(view.document);
+  } finally {
+    await view.cleanup();
+  }
+});
+
+test("keeps command discovery functional in a mobile viewport", async () => {
+  const view = await renderDirectory({ width: 375 });
+  try {
+    assert.equal(view.document.defaultView.innerWidth, 375);
+    assert.ok(view.input);
+    assert.equal(view.document.querySelectorAll("section").length, groups.length);
+    assertTocTargetsExist(view.document);
+
+    await typeWithKeyboard(view, "visit");
+    assert.equal(
+      view.document.querySelector("[role=status]").textContent,
+      `1 of ${groups.length} groups`,
+    );
+    assert.equal(
+      view.document.querySelector("nav[aria-label='On this page'] a").hash,
+      "#navigation-and-interaction",
+    );
+    assert.equal(
+      view.document.querySelector("section")?.id,
+      "navigation-and-interaction",
+    );
+  } finally {
+    await view.cleanup();
+  }
+});
diff --git a/apps/web/scripts/component-test-loader.mjs b/apps/web/scripts/component-test-loader.mjs
new file mode 100644
index 0000000..977da40
--- /dev/null
+++ b/apps/web/scripts/component-test-loader.mjs
@@ -0,0 +1,67 @@
+import { accessSync, readFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { transformSync } from "next/dist/build/swc/index.js";
+
+const webRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const sourceExtensions = ["", ".tsx", ".ts", ".jsx", ".js", ".mjs"];
+
+export function resolve(specifier, context, nextResolve) {
+  if (!specifier.startsWith("@/")) return nextResolve(specifier, context);
+
+  const sourcePath = join(webRoot, specifier.slice(2));
+  for (const extension of sourceExtensions) {
+    const candidate = `${sourcePath}${extension}`;
+    try {
+      accessSync(candidate);
+      return { shortCircuit: true, url: pathToFileURL(candidate).href };
+    } catch {
+      // Try the next supported source extension.
+    }
+  }
+
+  throw new Error(`Cannot resolve web source import: ${specifier}`);
+}
+
+export function load(url, context, nextLoad) {
+  const extension = extname(new URL(url).pathname);
+  if (extension === ".json") {
+    const source = readFileSync(fileURLToPath(url), "utf8");
+    return {
+      format: "module",
+      shortCircuit: true,
+      source: `export default ${source};`,
+    };
+  }
+  if (extension !== ".tsx" && extension !== ".ts") {
+    return nextLoad(url, context);
+  }
+
+  const filename = fileURLToPath(url);
+  const source = readFileSync(filename, "utf8");
+  const output = transformSync(source, {
+    filename,
+    sourceMaps: false,
+    jsc: {
+      parser: {
+        syntax: "typescript",
+        tsx: extension === ".tsx",
+      },
+      target: "es2022",
+      transform: {
+        react: {
+          runtime: "automatic",
+        },
+      },
+    },
+    module: {
+      type: "es6",
+    },
+  });
+
+  return {
+    format: "module",
+    shortCircuit: true,
+    source: output.code,
+  };
+}
diff --git a/apps/web/scripts/validate-command-directory.mjs b/apps/web/scripts/validate-command-directory.mjs
index 6a6d51e..75bc219 100644
--- a/apps/web/scripts/validate-command-directory.mjs
+++ b/apps/web/scripts/validate-command-directory.mjs
@@ -12,11 +12,6 @@ const commands = await readFile(
   join(root, "apps/headless/docs/COMMANDS.md"),
   "utf8",
 );
-const directory = await readFile(
-  join(root, "apps/web/components/command-directory.tsx"),
-  "utf8",
-);
-
 const sessionModel = sessionModelFromCommands(commands);
 assert.match(sessionModel, /one browser profile/i);
 assert.doesNotMatch(sessionModel, /stays isolated until you close it/i);
@@ -30,12 +25,9 @@ assert.ok(
   surface.groups.some((group) => /auth login/.test(group.usage)),
   "command directory must include auth login",
 );
-assert.match(directory, /role="status"/);
-assert.match(directory, /aria-live="polite"/);
-assert.match(directory, /docs-toc-inline/);
 assert.doesNotMatch(
   await readFile(join(root, "apps/web/app/docs/commands/page.tsx"), "utf8"),
   /sections=\{commands\.groups/,
 );
 
-console.log("command directory search and accessibility checks passed");
+console.log("command directory content checks passed");
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 53e15b7..53aa688 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -53,6 +53,9 @@ importers:
       eslint-config-next:
         specifier: ^16.3.3
         version: 16.3.3(@typescript-eslint/parser@8.68.0(eslint@9.39.5(jiti@2.7.0))(typescript@6.0.3))(eslint@9.39.5(jiti@2.7.0))(typescript@6.0.3)
+      jsdom:
+        specifier: 30.0.1
+        version: 30.0.1
       tailwindcss:
         specifier: ^4.1.11
         version: 4.3.3

From 7fe89ffe22929d943cc1d4e7b6c248766b81a67e Mon Sep 17 00:00:00 2001
From: SarthakWade <sarthakssg5@gmail.com>
Date: Sat, 12 Sep 2026 17:29:25 +0530
Subject: [PATCH 4/5] test(web): verify command discovery in Chromium

---
 .github/workflows/ci.yml                    |  4 ++
 apps/web/app/globals.css                    |  2 +
 apps/web/package.json                       |  2 +
 apps/web/playwright.config.ts               | 16 ++++++++
 apps/web/scripts/command-directory.test.mjs | 32 +---------------
 apps/web/tests/command-directory.spec.ts    | 41 +++++++++++++++++++++
 package.json                                |  2 +-
 pnpm-lock.yaml                              | 33 ++++++++++++++++-
 8 files changed, 98 insertions(+), 34 deletions(-)
 create mode 100644 apps/web/playwright.config.ts
 create mode 100644 apps/web/tests/command-directory.spec.ts

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2e9105d..5556444 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -116,6 +116,10 @@ jobs:
       - run: pnpm install --frozen-lockfile --filter @headless/web
       - run: pnpm --filter @headless/web lint
       - run: pnpm --filter @headless/web build
+      - name: Install Chromium for responsive checks
+        run: pnpm --filter @headless/web exec playwright install --with-deps chromium
+      - name: Responsive command directory
+        run: pnpm --filter @headless/web test:browser
 
   linux-e2e:
     name: Linux E2E (Docker)
diff --git a/apps/web/app/globals.css b/apps/web/app/globals.css
index 0479b3d..37db6f6 100644
--- a/apps/web/app/globals.css
+++ b/apps/web/app/globals.css
@@ -1531,6 +1531,8 @@ h3,
   margin-top: 27px;
 }
 .docs-content .command-block pre {
+  max-width: 100%;
+  overflow-x: auto;
   margin: 0;
   padding: 24px 74px 24px 24px;
   border: 1px solid rgba(255, 176, 32, 0.3);
diff --git a/apps/web/package.json b/apps/web/package.json
index ad05e6c..092c13d 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -6,6 +6,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
+    "test:browser": "playwright test",
     "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-command-directory.mjs && node --test scripts/command-directory.test.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
     "brand": "node scripts/render-brand.mjs"
   },
@@ -18,6 +19,7 @@
     "simple-icons": "^16.26.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.51.1",
     "@tailwindcss/postcss": "^4.1.11",
     "@types/node": "^26.5.0",
     "@types/react": "^19.2.18",
diff --git a/apps/web/playwright.config.ts b/apps/web/playwright.config.ts
new file mode 100644
index 0000000..1092b75
--- /dev/null
+++ b/apps/web/playwright.config.ts
@@ -0,0 +1,16 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  timeout: 30_000,
+  use: {
+    baseURL: "http://127.0.0.1:4173",
+    trace: "retain-on-failure",
+  },
+  webServer: {
+    command: "pnpm exec next start -H 127.0.0.1 -p 4173",
+    url: "http://127.0.0.1:4173/docs/commands",
+    reuseExistingServer: false,
+    timeout: 120_000,
+  },
+});
diff --git a/apps/web/scripts/command-directory.test.mjs b/apps/web/scripts/command-directory.test.mjs
index b82bb84..2f16ef5 100644
--- a/apps/web/scripts/command-directory.test.mjs
+++ b/apps/web/scripts/command-directory.test.mjs
@@ -13,15 +13,11 @@ if (typeof nodeModule.registerHooks === "function") {
 
 const { groups } = loadProductDocsContent().commands;
 
-async function renderDirectory({ width = 1280 } = {}) {
+async function renderDirectory() {
   const dom = new JSDOM('<div id="root"></div>', {
     pretendToBeVisual: true,
     url: "https://headless.test/docs/commands",
   });
-  Object.defineProperty(dom.window, "innerWidth", {
-    configurable: true,
-    value: width,
-  });
 
   const previousGlobals = new Map();
   for (const name of [
@@ -191,29 +187,3 @@ test("handles normalized queries, no matches, and clearing without stale links",
     await view.cleanup();
   }
 });
-
-test("keeps command discovery functional in a mobile viewport", async () => {
-  const view = await renderDirectory({ width: 375 });
-  try {
-    assert.equal(view.document.defaultView.innerWidth, 375);
-    assert.ok(view.input);
-    assert.equal(view.document.querySelectorAll("section").length, groups.length);
-    assertTocTargetsExist(view.document);
-
-    await typeWithKeyboard(view, "visit");
-    assert.equal(
-      view.document.querySelector("[role=status]").textContent,
-      `1 of ${groups.length} groups`,
-    );
-    assert.equal(
-      view.document.querySelector("nav[aria-label='On this page'] a").hash,
-      "#navigation-and-interaction",
-    );
-    assert.equal(
-      view.document.querySelector("section")?.id,
-      "navigation-and-interaction",
-    );
-  } finally {
-    await view.cleanup();
-  }
-});
diff --git a/apps/web/tests/command-directory.spec.ts b/apps/web/tests/command-directory.spec.ts
new file mode 100644
index 0000000..f3cfc9d
--- /dev/null
+++ b/apps/web/tests/command-directory.spec.ts
@@ -0,0 +1,41 @@
+import { expect, test } from "@playwright/test";
+
+test.use({ viewport: { width: 375, height: 812 } });
+
+test("command discovery remains usable on a mobile viewport", async ({ page }) => {
+  await page.goto("/docs/commands");
+
+  const pageWidth = await page.locator("html").evaluate((element) => ({
+    client: element.clientWidth,
+    scroll: element.scrollWidth,
+  }));
+  expect(pageWidth.scroll).toBeLessThanOrEqual(pageWidth.client);
+
+  const filter = page.getByRole("searchbox", { name: "Filter commands" });
+  await expect(filter).toBeVisible();
+  const bounds = await filter.boundingBox();
+  expect(bounds).not.toBeNull();
+  expect(bounds?.x).toBeGreaterThanOrEqual(0);
+  expect((bounds?.x ?? 0) + (bounds?.width ?? 0)).toBeLessThanOrEqual(375);
+
+  await filter.focus();
+  await expect(filter).toBeFocused();
+  await filter.pressSequentially("auth login");
+
+  await expect(page.getByRole("status")).toHaveText(/1 of \d+ groups/);
+  await expect(page.getByRole("heading", { level: 2 })).toHaveText([
+    "Credential vault",
+  ]);
+
+  const tocLinks = page.getByRole("navigation", { name: "On this page" }).getByRole("link");
+  await expect(tocLinks).toHaveCount(1);
+  await expect(tocLinks).toHaveAttribute("href", "#credential-vault");
+  await expect(page.locator("#credential-vault")).toBeVisible();
+
+  await filter.fill("not-a-command");
+  await expect(page.getByRole("status")).toHaveText(
+    "No commands match “not-a-command”.",
+  );
+  await expect(page.getByRole("navigation", { name: "On this page" })).toHaveCount(0);
+  await expect(page.locator("main section")).toHaveCount(0);
+});
diff --git a/package.json b/package.json
index 4e9f5ca..c51c30d 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,7 @@
     "test:e2e:linux": "pnpm --filter @headless/app test:e2e:linux"
   },
   "engines": {
-    "node": ">=22",
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0",
     "pnpm": ">=9"
   },
   "packageManager": "pnpm@9.15.0"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 53aa688..771e10a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21,7 +21,7 @@ importers:
         version: 1.42.0(react@19.2.8)
       next:
         specifier: ^16.3.3
-        version: 16.3.3(@babel/core@7.29.7)(@types/node@26.5.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+        version: 16.3.3(@babel/core@7.29.7)(@playwright/test@1.63.0)(@types/node@26.5.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       postcss:
         specifier: ^8.5.28
         version: 8.5.28
@@ -35,6 +35,9 @@ importers:
         specifier: ^16.26.0
         version: 16.26.0
     devDependencies:
+      '@playwright/test':
+        specifier: ^1.51.1
+        version: 1.63.0
       '@tailwindcss/postcss':
         specifier: ^4.1.11
         version: 4.3.3
@@ -510,6 +513,11 @@ packages:
     resolution: {integrity: sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA==}
     engines: {node: '>=12.4.0'}
 
+  '@playwright/test@1.63.0':
+    resolution: {integrity: sha512-oxMK4vllB9RK5NQ2l1pq1IfOf2AvnEuj/vYGDj0H2nMtmtZpKtCwt/l00GEO6xjGfpBNAvjovvYdCm50dRQkpQ==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   '@rtsao/scc@1.1.0':
     resolution: {integrity: sha512-zt6OdqaDoOnJ1ZYsCYGt9YmWzDXl4vQdKTyJev62gFhRGKdx7mcT54V9KIjg+d2wi9EXsPvAPKe7i7WjfVWB8g==}
 
@@ -1782,6 +1790,16 @@ packages:
     resolution: {integrity: sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==}
     engines: {node: '>=12'}
 
+  playwright-core@1.63.0:
+    resolution: {integrity: sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  playwright@1.63.0:
+    resolution: {integrity: sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   possible-typed-array-names@1.1.0:
     resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
     engines: {node: '>= 0.4'}
@@ -2576,6 +2594,10 @@ snapshots:
 
   '@nolyfill/is-core-module@1.0.39': {}
 
+  '@playwright/test@1.63.0':
+    dependencies:
+      playwright: 1.63.0
+
   '@rtsao/scc@1.1.0': {}
 
   '@swc/helpers@0.5.23':
@@ -3880,7 +3902,7 @@ snapshots:
 
   natural-compare@1.4.0: {}
 
-  next@16.3.3(@babel/core@7.29.7)(@types/node@26.5.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+  next@16.3.3(@babel/core@7.29.7)(@playwright/test@1.63.0)(@types/node@26.5.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
     dependencies:
       '@next/env': 16.3.3
       '@swc/helpers': 0.5.23
@@ -3899,6 +3921,7 @@ snapshots:
       '@next/swc-linux-x64-musl': 16.3.3
       '@next/swc-win32-arm64-msvc': 16.3.3
       '@next/swc-win32-x64-msvc': 16.3.3
+      '@playwright/test': 1.63.0
       sharp: 0.35.4(@types/node@26.5.0)
     transitivePeerDependencies:
       - '@babel/core'
@@ -4000,6 +4023,12 @@ snapshots:
 
   picomatch@4.0.7: {}
 
+  playwright-core@1.63.0: {}
+
+  playwright@1.63.0:
+    dependencies:
+      playwright-core: 1.63.0
+
   possible-typed-array-names@1.1.0: {}
 
   postcss@8.5.23:

From 7bb71e108a778eed63703c530033de6f81eda210 Mon Sep 17 00:00:00 2001
From: SarthakWade <sarthakssg5@gmail.com>
Date: Sat, 12 Sep 2026 17:39:34 +0530
Subject: [PATCH 5/5] refactor(web): simplify command filtering

---
 apps/web/components/command-directory.tsx | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/apps/web/components/command-directory.tsx b/apps/web/components/command-directory.tsx
index fcde55f..2b7d8cb 100644
--- a/apps/web/components/command-directory.tsx
+++ b/apps/web/components/command-directory.tsx
@@ -2,7 +2,7 @@
 
 import { CommandBlock } from "@/components/docs-copy-controls";
 import { plainText } from "@/lib/markdown";
-import { useMemo, useState } from "react";
+import { useState } from "react";
 
 type CommandGroup = {
   title: string;
@@ -14,14 +14,13 @@ type CommandGroup = {
 export function CommandDirectory({ groups }: { groups: CommandGroup[] }) {
   const [query, setQuery] = useState("");
   const normalized = query.trim().toLowerCase();
-  const visible = useMemo(() => {
-    if (!normalized) return groups;
-    return groups.filter((group) =>
-      `${group.title} ${group.description} ${group.usage}`
-        .toLowerCase()
-        .includes(normalized),
-    );
-  }, [groups, normalized]);
+  const visible = normalized
+    ? groups.filter((group) =>
+        `${group.title} ${group.description} ${group.usage}`
+          .toLowerCase()
+          .includes(normalized),
+      )
+    : groups;
 
   const countLabel =
     visible.length === 0