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.

Author: yashranaway

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."

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 {

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>
+      ))}
     </>
   );
 }

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;

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}`);
   }

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": {

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");

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 ||