@jxsuite/studio 4.1.0 → 5.1.0

package/src/services/ai-system-prompt.ts

@@ -29,6 +29,14 @@ interface BuildSystemPromptOptions {
    * prompt-shape tests — advertises the same list it always did.
    */
   treeEditable?: boolean | undefined;
+  /**
+   * The blurbs of the tools projected from command records this round —
+   * `services/ai-command-tools.ts`'s `commandToolBlurbs(activeRegistry())`. Rendered after the hand
+   * tools under every "Tools available right now" heading, one line each. Passed in rather than
+   * read here so this stays a pure function of its options: a caller that passes none sees the hand
+   * list it always did, and only `document-assistant.ts`, which holds the registry, adds them.
+   */
+  commandTools?: readonly string[] | undefined;
   /**
    * Whether the platform can import a site. Defaults TRUE so this stays a pure function of what it
    * is given — a caller that knows nothing about the platform gets the full list, and only
@@ -37,11 +45,32 @@ interface BuildSystemPromptOptions {
   canImport?: boolean | undefined;
   /** Project-relative file paths for the inventory section (project modes; capped). */
   fileInventory?: string[] | undefined;
+  /**
+   * What this backend can run, enabled or not.
+   *
+   * Passed in rather than read here, because it comes from the PLATFORM and this builder is a pure
+   * function of its options. Without it the model can only discover an extension by being told
+   * about one, which is how a request for a blog gets a hand-built Markdown pipeline instead of
+   * `@jxsuite/parser`.
+   */
+  extensionCatalog?: readonly ExtensionCatalogSummary[] | undefined;
+}
+
+/** One extension this backend can run — the prompt's view of a catalogue entry. */
+export interface ExtensionCatalogSummary {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  /** `project.json` keys that become legal once it is enabled. */
+  sections?: readonly string[] | undefined;
 }
 
 /** Max file paths embedded in the prompt's inventory section. */
 const FILE_INVENTORY_CAP = 100;
 
+/** Max catalogue entries listed in the prompt. */
+const EXTENSION_CATALOG_CAP = 20;
+
 // ─── Tool tiers (single source of truth for prompt AND gating) ──────────────
 
 /** Studio state a tool tier requires. Used by the gating registry AND the prompt tool list. */
@@ -54,9 +83,14 @@ const FILE_INVENTORY_CAP = 100;
  * with Project Settings open, `project.json` drawn as a layer tree. The assistant's tier asked only
  * whether a tab existed, so in that exact state the agent was advertised `remove_node` and
  * `move_node` and executed them against the file that defines the project, while the human's
- * `delete_node` was refused. `remove_node` self-refuses only the document root (`path.length < 2`),
+ * `delete_node` was refused. `remove_node` self-refused only the document root (`path.length < 2`),
  * a weaker test than `structurallyEditable`, so a repeater template or `$switch` case was removable
- * by the agent and not by the person.
+ * by the agent and not by the person. A tier was the first fix; the second predicate went with
+ * `remove_node` itself, which is now `delete_node`, the projection of `selection.delete`
+ * (`services/ai-command-tools.ts`) — one record, one gate, and no tier row here at all.
+ *
+ * This union is the HAND table's vocabulary and nothing a record declares: a projected command's
+ * tier is derived from its `level` by the bridge.
  */
 export type AiToolTier = "always" | "no-project" | "project" | "document" | "document-tree";
 
@@ -76,9 +110,15 @@ export interface AiToolInfo {
 }
 
 /**
- * Every assistant tool with its availability tier and prompt blurb. document-assistant.ts derives
- * the gating predicates from the same rows, so the advertised tool list and the executable tool
- * list cannot drift (a test asserts the names match the registered tools).
+ * Every HAND-REGISTERED assistant tool with its availability tier and prompt blurb.
+ * document-assistant.ts derives the gating predicates from the same rows, so the advertised tool
+ * list and the executable tool list cannot drift (a test asserts the names match the registered
+ * tools, and that none is also a command record's projection).
+ *
+ * The other kind of tool is not here and must not be added here: a command record that declares
+ * `aiTool` is projected by `services/ai-command-tools.ts`, gated by the record's own `when` /
+ * `enablement`, and described by the record. `enable_extension`, `disable_extension`, `delete_node`
+ * (né `remove_node`) and `open_document` left this table for that one.
  */
 export const AI_TOOL_TIERS: AiToolInfo[] = [
   // Always — a question is not gated on what happens to be open
@@ -145,12 +185,8 @@ export const AI_TOOL_TIERS: AiToolInfo[] = [
     tier: "project",
     blurb: "create_page(path, content) — create a new .json page file on disk.",
   },
-  {
-    name: "open_document",
-    tier: "project",
-    blurb:
-      "open_document(path) — open a file on the canvas as the active document; the document tools then operate on it. Use when the user should SEE the page, or for iterative visual refinement.",
-  },
+  /* `open_document` is not a row: it is the projection of the `document.open` record
+     (`workspace/workspace.ts`), advertised by the record's own gate and described by the record. */
   // Document (an active document on the canvas)
   {
     name: "read_document",
@@ -181,11 +217,6 @@ export const AI_TOOL_TIERS: AiToolInfo[] = [
     blurb:
       "add_child(parentPath, index, node) — insert a new node into the children of parentPath at index.",
   },
-  {
-    name: "remove_node",
-    tier: "document-tree",
-    blurb: "remove_node(path) — remove the node at path.",
-  },
   {
     name: "move_node",
     tier: "document-tree",
@@ -644,17 +675,24 @@ export function buildSystemPrompt({
   hasProject = Boolean(projectRoot),
   treeEditable = true,
   canImport = true,
+  commandTools = [],
   fileInventory,
+  extensionCatalog,
 }: BuildSystemPromptOptions = {}) {
   const hasDocument = Boolean(document);
 
   // 1. Role, state-appropriate workflow, and the tool list for the current state.
   // The list the model is TOLD about and the list the gate will honour are the same filter, so a
-  // Refusal is never a surprise to it.
-  const toolList = AI_TOOL_TIERS.filter((t) =>
-    toolActive(t, { canImport, hasDocument, hasProject, treeEditable }),
-  )
-    .map((t) => `- ${t.blurb}`)
+  // Refusal is never a surprise to it. The command-projected tools arrive already filtered by
+  // Their records' own gates, for the same reason — one function answers both the prompt and the
+  // Executor (`advertisedCommandTools`).
+  const toolList = [
+    ...AI_TOOL_TIERS.filter((t) =>
+      toolActive(t, { canImport, hasDocument, hasProject, treeEditable }),
+    ).map((t) => t.blurb),
+    ...commandTools,
+  ]
+    .map((blurb) => `- ${blurb}`)
     .join("\n");
 
   const role = `You are an expert Jx builder assistant embedded in Jx Studio. You help users build websites, components, pages, and layouts using the Jx JSON schema. The live jxsuite.com marketing site is built entirely with Jx — you can produce production-quality Jx code.`;
@@ -722,7 +760,12 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
 
   // 6. Project context
   if (hasProject && (projectConfig || components || projectRoot)) {
-    const projectSummary = buildProjectSummary({ projectConfig, components, projectRoot });
+    const projectSummary = buildProjectSummary({
+      components,
+      extensionCatalog,
+      projectConfig,
+      projectRoot,
+    });
     if (projectSummary) {
       sections.push(`## Project Context\n\n${projectSummary}`);
     }
@@ -744,7 +787,7 @@ Be concise. Don't explain what Jx is unless asked. Just build.`;
 If a tool call fails (returns { success: false }):
 1. Read the error message carefully — it includes a "→ Fix:" hint telling you exactly how to correct the error.
 2. Each error points to a specific path in the document and a specific rule violation.
-3. Apply the suggested fix using set_property, remove_node, or add_child as appropriate.
+3. Apply the suggested fix using set_property, delete_node, or add_child as appropriate.
 4. Do NOT re-issue the exact same tool call with the same arguments — you must CHANGE something.
 5. If you see the SAME error after 2 attempts, try a completely different approach (e.g., remove and re-add the node instead of patching it).
 
@@ -762,7 +805,7 @@ If a tool call fails (returns { success: false }):
 
 ### If you keep getting errors:
 - Call read_document again — the document may have changed since you last read it.
-- Remove the problematic node entirely with remove_node, then re-create it correctly with add_child.
+- Remove the problematic node entirely with delete_node, then re-create it correctly with add_child.
 - If the error message points to a different path than you expected, the node might have moved due to previous edits.`);
 
   return sections.join("\n\n---\n\n");
@@ -841,6 +884,7 @@ function buildProjectSummary({
   projectConfig,
   components,
   projectRoot,
+  extensionCatalog,
 }: Omit<BuildSystemPromptOptions, "document">) {
   const lines: string[] = [];
 
@@ -852,6 +896,13 @@ function buildProjectSummary({
     lines.push(`Root: ${projectRoot}`);
   }
 
+  /* One line, closing a gap that was pure oversight: this function has always received the whole
+     `projectConfig`, `extensions` included, and dropped it on the floor. */
+  const enabled = projectConfig?.extensions ?? [];
+  if (enabled.length > 0) {
+    lines.push(`Extensions enabled: ${enabled.join(", ")}`);
+  }
+
   // Available components — tag + purpose so the model can reuse them
   if (components && components.length > 0) {
     lines.push(`Available components (reuse these instead of rebuilding):`);
@@ -898,6 +949,43 @@ function buildProjectSummary({
     }
   }
 
+  /*
+   * The catalogue, last, so the design-token block keeps its prominence. The guidance names
+   * CAPABILITIES rather than packages on purpose: the capability-to-package mapping is what each
+   * entry's own description is for, and hardcoding "@jxsuite/parser" here would be a second,
+   * staler copy of the backend's answer.
+   */
+  if (extensionCatalog && extensionCatalog.length > 0) {
+    const enabledSet = new Set(enabled);
+    lines.push(
+      `Extensions available. Turn one on with enable_extension BEFORE writing the project.json ` +
+        `section it owns: a section belonging to a disabled extension is a schema error, and an ` +
+        `"extensions" entry whose package is not installed fails the build. When a request needs ` +
+        `a capability the core does not have (a blog or any folder of Markdown, a search box, a ` +
+        `feed, sign-ins, a database table), look for it below rather than hand-building it.`,
+    );
+    for (const entry of extensionCatalog.slice(0, EXTENSION_CATALOG_CAP)) {
+      const parts = [`  ${entry.name}`];
+      if (entry.title) {
+        parts.push(` — ${entry.title}.`);
+      }
+      if (entry.description) {
+        parts.push(` ${entry.description}`);
+      }
+      if (entry.sections && entry.sections.length > 0) {
+        parts.push(` Contributes: ${entry.sections.join(", ")}.`);
+      }
+      if (enabledSet.has(entry.name)) {
+        parts.push(" [enabled]");
+      }
+      lines.push(parts.join(""));
+    }
+    if (extensionCatalog.length > EXTENSION_CATALOG_CAP) {
+      const more = extensionCatalog.length - EXTENSION_CATALOG_CAP;
+      lines.push(`  … and ${more} more (open_settings { section: "extensions" })`);
+    }
+  }
+
   // Breakpoints — surfaced prominently so the model uses @--breakpoint responsive overrides
   if (projectConfig?.$media) {
     const breakpoints = Object.entries(projectConfig.$media)

package/src/services/ai-tools.ts

@@ -12,15 +12,10 @@ import { createToolDefinition } from "@jxsuite/ai/tools";
 import type { ToolRegistry, ToolResult } from "@jxsuite/ai/tools";
 import type { JxMutableNode, JxPath, JxStateDefinition } from "@jxsuite/schema/types";
 import { getNodeAtPath } from "../state";
-import { toRaw } from "../reactivity";
 import type { Tab } from "../tabs/tab";
 import {
-  beginBatch,
-  endBatch,
-  isBatching,
   mutateInsertNode,
   mutateMoveNode,
-  mutateRemoveNode,
   mutateUpdateProperty,
   mutateUpdateStyle,
   transactDoc,
@@ -28,7 +23,18 @@ import {
 import type { JxNodeValue } from "../tabs/transact";
 import { validateDoc } from "./jx-validate";
 import { recordWrite } from "./ai-writes";
-import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
+import { serializeJson } from "../files/json-layout";
+import {
+  reportDocumentWrite,
+  snapshotBeforeWrite,
+  translateValidationError,
+} from "./ai-write-report";
+import type { RenderVerdict } from "./ai-write-report";
+
+/* Re-exported from its new home so `ai-project-tools.ts` and the tests keep their import: the
+   translation moved with the verdict it belongs to (`ai-write-report.ts`), where every document
+   write — hand-registered or projected from a command record — now reads it. */
+export { translateValidationError } from "./ai-write-report";
 
 const PATH_DESCRIPTION =
   "Path to a node in the document, as a JSON array of keys/indices from the root " +
@@ -45,74 +51,17 @@ function noDocError(): ToolResult {
 }
 
 /**
- * Translate a raw JSON Schema validation error into a Jx-specific actionable message. The LLM needs
- * concrete guidance on HOW to fix errors, not just what rule was violated. Shared with the
- * project-level file tools (ai-project-tools.ts), which pre-validate Jx documents before writing.
- *
- * @param {string} rawError - Message from ajv (e.g. "/children/0/style: must NOT have additional
- *   property")
- * @returns {string}
- */
-export function translateValidationError(rawError: string): string {
-  const lower = rawError.toLowerCase();
-
-  // Additional property — extract the offending key from the message if present
-  if (
-    lower.includes("must not have additional property") ||
-    lower.includes("additional properties")
-  ) {
-    return `${rawError}\n  → Fix: Remove or move the unexpected property. Style properties must be camelCase (e.g. "backgroundColor", not "background-color"). Non-IDL HTML attributes (aria-*, data-*, role, ...) must go inside an "attributes" object: { "attributes": { "aria-label": "..." } }.`;
-  }
-
-  // Pattern — usually tagName hyphen rule
-  if (lower.includes("must match pattern")) {
-    return `${rawError}\n  → Fix: Custom element tag names must contain a hyphen (e.g. "newsletter-form", "feature-card"). Standard HTML elements use their exact name (e.g. "div", "input", "button").`;
-  }
-
-  // Type error
-  if (lower.includes("must be string")) {
-    return `${rawError}\n  → Fix: Wrap the value in quotes — all Jx property values should be strings. For example, use "10px" (string) not 10px (unquoted).`;
-  }
-
-  if (lower.includes("must be number") || lower.includes("must be integer")) {
-    return `${rawError}\n  → Fix: Remove quotes from the numeric value — it should be a plain number, not a string.`;
-  }
-
-  if (lower.includes("must be object") || lower.includes("must be array")) {
-    return `${rawError}\n  → Fix: The value must be an object/array (use {} or []), not a string or number.`;
-  }
-
-  if (lower.includes("must be boolean")) {
-    return `${rawError}\n  → Fix: Use true or false without quotes for boolean values.`;
-  }
-
-  // Required property
-  if (lower.includes("must have required property")) {
-    return `${rawError}\n  → Fix: Add the missing required property. Every Jx element must have at least a "tagName" field.`;
-  }
-
-  // Enum / allowed values
-  if (lower.includes("must be equal to one of the allowed values")) {
-    return `${rawError}\n  → Fix: Change the value to one of the allowed options listed in the error.`;
-  }
-
-  return rawError;
-}
-
-/**
- * Apply a mutation, then validate the document and report only the schema errors the edit newly
- * introduced (the eval signal — ADR §6b). The change stays applied either way (optimistic apply +
- * undo, ADR §5); reporting the errors lets the agent loop self-correct on the next round.
- *
- * When a renderCheck function is provided, a second gate runs after schema validation passes: the
- * mutated document is rendered in a detached DOM context and any render-time throws are surfaced as
- * tool errors (same contract as schema errors).
+ * Apply a mutation, then hand the verdict to `ai-write-report.ts`: only the schema errors the edit
+ * NEWLY introduced are reported (the eval signal — ADR §6b), the render check runs when a
+ * renderCheck was provided and rendering worked before, and a success carries the token hints. The
+ * change stays applied either way (optimistic apply + undo, ADR §5); reporting the errors lets the
+ * agent loop self-correct on the next round.
  *
  * @param {import("../tabs/tab").Tab} tab
  * @param {(t: import("../tabs/tab").Tab) => void} mutationFn
  * @param {string} summary
  * @param {(doc: unknown) => Promise<string[]>} validate
- * @param {((doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>) | undefined} renderCheck
+ * @param {((doc: unknown) => Promise<RenderVerdict>) | undefined} renderCheck
  * @param {Record<string, string> | undefined} projectStyle
  * @returns {Promise<import("@jxsuite/ai/tools").ToolResult>}
  */
@@ -121,12 +70,11 @@ async function applyAndValidate(
   mutationFn: (t: Tab) => void,
   summary: string,
   validate: (doc: unknown) => Promise<string[]>,
-  renderCheck: ((doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>) | undefined,
+  renderCheck: ((doc: unknown) => Promise<RenderVerdict>) | undefined,
   projectStyle: Record<string, string> | undefined,
 ): Promise<ToolResult> {
-  const rawBefore = toRaw(tab.doc.document);
-  const before = new Set(await validate(rawBefore));
-  const renderOkBefore = renderCheck ? await renderCheck(rawBefore) : { ok: true };
+  const deps = { getProjectStyle: () => projectStyle, renderCheck, validate };
+  const before = await snapshotBeforeWrite(tab, deps);
 
   /* AND THE WRITE CAN BE REFUSED, in which case the model must be told rather than congratulated.
      The collab gate pauses structural editing while source is canonical, and this went on to
@@ -147,37 +95,7 @@ async function applyAndValidate(
      went through transactDoc, so the tab's history — and "Restore to here" — can reach it. */
   recordWrite({ disk: false, ok: true, path: tab.documentPath ?? "(untitled)", tool: summary });
 
-  const rawAfter = toRaw(tab.doc.document);
-  const after = await validate(rawAfter);
-  const newErrors = after.filter((e) => !before.has(e));
-  if (newErrors.length > 0) {
-    const formatted = newErrors.map((e) => `- ${translateValidationError(e)}`).join("\n");
-    return {
-      success: false,
-      error: `Change applied, but it introduced schema errors. Fix these issues with follow-up edits:\n${formatted}`,
-    };
-  }
-
-  if (renderCheck && renderOkBefore.ok) {
-    const renderResult = await renderCheck(rawAfter);
-    if (!renderResult.ok) {
-      return {
-        success: false,
-        error: `Change applied and schema-valid, but it broke rendering. Fix with follow-up edits:\n- ${renderResult.error}`,
-      };
-    }
-  }
-
-  // Soft token-discipline hints (never fail the mutation)
-  if (projectStyle) {
-    const findings = flagHardcodedTokens(rawAfter, projectStyle);
-    const hints = formatTokenHints(findings);
-    if (hints) {
-      return { success: true, summary: `${summary}\n\n${hints}` };
-    }
-  }
-
-  return { success: true, summary };
+  return reportDocumentWrite(tab, before, summary, deps);
 }
 
 /**
@@ -189,7 +107,6 @@ async function applyAndValidate(
  *   validate?: (doc: unknown) => Promise<string[]>;
  *   saveFile?: (relPath: string, content: string) => Promise<void>;
  *   renderCheck?: (doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>;
- *   openDocument?: (path: string) => Promise<void>;
  *   projectStyle?: Record<string, string>;
  *   getProjectStyle?: () => Record<string, string> | undefined;
  *   findOpenTab?: (path: string) => import("../tabs/tab").Tab | null;
@@ -203,7 +120,6 @@ export function registerAiTools(
     validate = validateDoc,
     saveFile,
     renderCheck,
-    openDocument,
     projectStyle,
     getProjectStyle,
     findOpenTab,
@@ -213,7 +129,6 @@ export function registerAiTools(
     validate?: (doc: unknown) => Promise<string[]>;
     saveFile?: (relPath: string, content: string) => Promise<void>;
     renderCheck?: (doc: unknown) => Promise<{ ok: true } | { ok: false; error: string }>;
-    openDocument?: (path: string) => Promise<void>;
     projectStyle?: Record<string, string> | undefined;
     /**
      * Live variant of `projectStyle` — takes precedence; re-read per tool call so a project
@@ -258,7 +173,7 @@ export function registerAiTools(
       name: "read_document",
       description:
         "Read the current Jx document, or the subtree at a given path. Use this to discover " +
-        "node paths before calling set_property, add_child, or remove_node.",
+        "node paths before calling set_property, add_child, or delete_node.",
       parameters: {
         type: "object",
         properties: {
@@ -751,7 +666,9 @@ export function registerAiTools(
           }
         }
         try {
-          await saveFile(relPath, JSON.stringify(content, null, 2));
+          // The save serializer, layout-less (`files/json-layout.ts`): the assistant supplied a
+          // Value, not a text, so the formatter's layout for fresh output is the right one.
+          await saveFile(relPath, serializeJson(content, null));
           recordWrite({ disk: true, ok: true, path: relPath, tool: "create_component" });
           return {
             success: true,
@@ -828,7 +745,8 @@ export function registerAiTools(
           }
         }
         try {
-          await saveFile(relPath, JSON.stringify(content, null, 2));
+          // As `create_component`: a value the assistant supplied, written in the formatter's layout.
+          await saveFile(relPath, serializeJson(content, null));
           recordWrite({ disk: true, ok: true, path: relPath, tool: "create_page" });
           return {
             success: true,
@@ -852,106 +770,12 @@ export function registerAiTools(
     }),
   );
 
-  // ── open_document ─────────────────────────────────────────────────────
-
-  registry.register(
-    createToolDefinition({
-      name: "open_document",
-      description:
-        "Switch the active document to another file in the project. After opening, all " +
-        "tools (read_document, set_property, add_child, etc.) operate on the newly-active " +
-        "document. Use this to iteratively refine pages or components after creating them " +
-        "with create_page or create_component.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: {
-            type: "string",
-            description:
-              'File path relative to the project root, e.g. "pages/about.json" or ' +
-              '"components/nav-bar.json". Must be an existing file.',
-          },
-        },
-        required: ["path"],
-      },
-      async execute(args) {
-        if (!openDocument) {
-          return {
-            success: false,
-            error: "File navigation is not available in this environment.",
-          };
-        }
-        const { path: relPath } = args as { path: string };
-        try {
-          await openDocument(relPath);
-          const tab = getTab();
-          if (!tab) {
-            return {
-              success: false,
-              error: `File "${relPath}" could not be opened — no active tab after navigation.`,
-            };
-          }
-          /*
-           * The agent loop opens a single undo batch on the tab that was active at loop start
-           * (tool-executor.js → beginBatch). Switching the active document mid-loop would strand
-           * the new tab's edits with no history snapshot — undo would have nothing to roll back.
-           * Flush the previous tab's batch and re-open one on the newly-active tab so edits in
-           * each document remain individually undoable.
-           */
-          if (isBatching()) {
-            endBatch();
-            beginBatch(tab);
-          }
-          return {
-            success: true,
-            summary: `Switched to "${relPath}". All tools now operate on this document.`,
-          };
-        } catch (error) {
-          return {
-            success: false,
-            error: `Failed to open "${relPath}": ${error instanceof Error ? error.message : String(error)}`,
-          };
-        }
-      },
-    }),
-  );
-
-  registry.register(
-    createToolDefinition({
-      name: "remove_node",
-      description: "Remove the node at the given path from its parent's children array.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: {
-            type: "array",
-            description: `${PATH_DESCRIPTION} Cannot be the document root.`,
-            items: { type: ["string", "number"] },
-          },
-        },
-        required: ["path"],
-      },
-      async execute(args) {
-        const tab = getTab();
-        if (!tab) {
-          return noDocError();
-        }
-        const { path } = args as { path: JxPath };
-        if (path.length < 2) {
-          return { success: false, error: "Cannot remove the document root." };
-        }
-        if (getNodeAtPath(tab.doc.document, path) === undefined) {
-          return { success: false, error: `No node exists at path ${JSON.stringify(path)}.` };
-        }
-        return applyAndValidate(
-          tab,
-          (t) => mutateRemoveNode(t, path),
-          `Removed node at ${JSON.stringify(path)}.`,
-          validate,
-          renderCheck,
-          styleOf(),
-        );
-      },
-    }),
-  );
+  /*
+   * `open_document` is NOT here any more. It is the projection of the `document.open` record
+   * (`workspace/workspace.ts`'s `tabCommands`), so the person's palette row and the model's tool
+   * are one `run` and one gate (§12.4). The hand tool read `getTab()` after the open and called
+   * whatever it found a success — a missing file left the previous document active and reported
+   * "Switched to" — and it re-anchored the undo batch itself, which `tool-executor.ts` has done
+   * after EVERY tool since project adoption started replacing tabs mid-loop.
+   */
 }