@jxsuite/studio 4.1.0 → 5.0.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` and
+ * `delete_node` (né `remove_node`) left this table for that one.
  */
 export const AI_TOOL_TIERS: AiToolInfo[] = [
   // Always — a question is not gated on what happens to be open
@@ -181,11 +221,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 +679,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 +764,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 +791,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 +809,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 +888,7 @@ function buildProjectSummary({
   projectConfig,
   components,
   projectRoot,
+  extensionCatalog,
 }: Omit<BuildSystemPromptOptions, "document">) {
   const lines: string[] = [];
 
@@ -852,6 +900,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 +953,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,7 +12,6 @@ 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,
@@ -20,7 +19,6 @@ import {
   isBatching,
   mutateInsertNode,
   mutateMoveNode,
-  mutateRemoveNode,
   mutateUpdateProperty,
   mutateUpdateStyle,
   transactDoc,
@@ -28,7 +26,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 +54,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 +73,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 +98,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);
 }
 
 /**
@@ -258,7 +179,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 +672,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 +751,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,
@@ -915,43 +839,4 @@ export function registerAiTools(
       },
     }),
   );
-
-  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(),
-        );
-      },
-    }),
-  );
 }

package/src/services/ai-write-report.ts

@@ -0,0 +1,174 @@
+/**
+ * Ai-write-report.ts — what the model is told after a document write, whoever made it.
+ *
+ * Extracted from `ai-tools.ts`'s `applyAndValidate`, which used to own both halves of a document
+ * tool: the transaction and the verdict on it. The verdict is the half every document write needs
+ * — the seven hand-registered tree tools AND every command the assistant runs through
+ * `services/ai-command-tools.ts` — so it lives here, in two functions the caller brackets its write
+ * with:
+ *
+ * 1. {@link snapshotBeforeWrite} reads the document's schema errors and render state BEFORE the
+ *    write, because the eval signal (ADR docs/ai-assistant-decision.md §6b) is "what did this edit
+ *    newly introduce", not "is the document valid": a page that was already broken must not make
+ *    every subsequent edit read as the culprit.
+ * 2. {@link reportDocumentWrite} compares AFTER the write, translating each new schema error into a
+ *    fix hint the model can act on, running the render check only when rendering worked before,
+ *    and appending the soft token-discipline hints to a success.
+ *
+ * The change stays applied either way (optimistic apply + undo, ADR §5); reporting the errors lets
+ * the agent loop self-correct on the next round.
+ *
+ * @license MIT
+ */
+
+import type { ToolResult } from "@jxsuite/ai/tools";
+import { toRaw } from "../reactivity";
+import type { Tab } from "../tabs/tab";
+import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
+
+/** A render probe's answer: rendered, or the message it threw. */
+export type RenderVerdict = { ok: true } | { ok: false; error: string };
+
+/** What a write reporter needs. Every member is what `registerAiTools` already takes by injection. */
+export interface WriteReportDeps {
+  /** Schema errors for a document, as raw ajv sentences. */
+  validate: (doc: unknown) => Promise<string[]>;
+  /** The detached-DOM render probe, when the host has one. */
+  renderCheck?: ((doc: unknown) => Promise<RenderVerdict>) | undefined;
+  /** The project's design tokens, read per call so a project opened mid-session contributes. */
+  getProjectStyle?: (() => Record<string, string> | undefined) | undefined;
+}
+
+/** The document as it stood before a write, in the two respects the verdict compares. */
+export interface WriteSnapshot {
+  errors: Set<string>;
+  renderOk: boolean;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Read the document's standing BEFORE a write: its schema errors and whether it renders.
+ *
+ * Reads the RAW document, not the reactive proxy, for the same reason `applyAndValidate` always
+ * did: the validator walks the whole tree, and walking a proxy subscribes whichever effect is
+ * running to every key of it.
+ *
+ * @param {Tab} tab
+ * @param {WriteReportDeps} deps
+ * @returns {Promise<WriteSnapshot>}
+ */
+export async function snapshotBeforeWrite(tab: Tab, deps: WriteReportDeps): Promise<WriteSnapshot> {
+  const rawBefore = toRaw(tab.doc.document);
+  const errors = new Set(await deps.validate(rawBefore));
+  const rendered = deps.renderCheck ? await deps.renderCheck(rawBefore) : { ok: true };
+  return { errors, renderOk: rendered.ok };
+}
+
+/**
+ * The verdict on a write that has been applied: the NEW schema errors with fix hints, the render
+ * check (only when rendering worked before — a page that already failed to render is not this
+ * edit's fault), or a success carrying `summary` plus any token-discipline hints.
+ *
+ * The three sentences here are the ones the model has read since the tools were written; every
+ * bridged document command now answers with the same ones, which is what lets the prompt's error
+ * recovery guidance stay generic.
+ *
+ * @param {Tab} tab
+ * @param {WriteSnapshot} before - What {@link snapshotBeforeWrite} read.
+ * @param {string} summary - The sentence to return on success.
+ * @param {WriteReportDeps} deps
+ * @returns {Promise<ToolResult>}
+ */
+export async function reportDocumentWrite(
+  tab: Tab,
+  before: WriteSnapshot,
+  summary: string,
+  deps: WriteReportDeps,
+): Promise<ToolResult> {
+  const rawAfter = toRaw(tab.doc.document);
+  const after = await deps.validate(rawAfter);
+  const newErrors = after.filter((e) => !before.errors.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 (deps.renderCheck && before.renderOk) {
+    const renderResult = await deps.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)
+  const projectStyle = deps.getProjectStyle?.();
+  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 };
+}