@gakim-digital/dexter-bridge 0.11.14 → 0.11.16

package/src/framerAgentTools.js

@@ -3,24 +3,32 @@ import fs from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
+import jsTokens from 'js-tokens';
 import {
-  BEHAVIOR_ACTIVATIONS,
-  BEHAVIOR_LAYOUT_EFFECTS,
-  BEHAVIOR_MECHANISMS,
-  BEHAVIOR_PRESENTATIONS,
   canonicalIdMappings,
   evidenceNodeIds,
   mergeBehaviorPlans,
   normalizeBehaviorEvidence,
   normalizeBehaviorPlan,
+  summarizeBehaviorVerification,
   summarizeFramerChanges,
-  verifyBehaviorEvidence,
+  verifyBehaviorChecks,
 } from './framerBehaviorContract.js';
 
 const require = createRequire(import.meta.url);
 const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
 const MAX_MODEL_RESULT_BYTES = 120 * 1024;
 const MAX_CODE_FILE_CONTENT_CHARS = 200_000;
+const MAX_SVG_MARKUP_CHARS = 200_000;
+const MAX_SVG_ATTRIBUTES = 24;
+const UNSAFE_SVG_PATTERN =
+  /<\s*(?:script|foreignObject|iframe)\b|\son[a-z]+\s*=|javascript:|(?:xlink:)?href\s*=\s*["']\s*(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const MUTATION_TOOL_NAMES = new Set([
+  'framer_apply_changes',
+  'framer_add_svg',
+  'framer_update_code_file',
+  'framer_write',
+]);
 const MAX_SCREENSHOT_BYTES = 4 * 1024 * 1024;
 const MAX_SCREENSHOTS_PER_CALL = 4;
 const SCREENSHOT_FETCH_TIMEOUT_MS = 20_000;
@@ -31,8 +39,6 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60_000;
 const SESSION_TIMEOUT_MS = 10 * 60_000;
 const MAX_UNSAFE_WRITE_FAILURES = 2;
 const MAX_LOW_LEVEL_WRITE_FAILURES = 3;
-const MAX_INTERACTION_VERIFICATION_ATTEMPTS_PER_BEHAVIOR = 3;
-const MAX_INTERACTION_REPAIRS_PER_BEHAVIOR = 1;
 const MAX_GUIDANCE_BYTES = 180 * 1024;
 const MAX_GUIDANCE_FILE_BYTES = 48 * 1024;
 const PROJECT_ID_PATTERN = /^[A-Za-z0-9]{20}$/;
@@ -91,10 +97,15 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_instructions',
     description:
-      'Get concise Framer Agent guidance, or request targeted official API documentation when an exact method or type is unclear. Most runs should rely on the tool descriptions and call this only when needed.',
+      'Read on-demand project guides by id from the "On-demand guides" catalog, or request targeted official API documentation when an exact method or type is unclear.',
     inputSchema: {
       type: 'object',
       properties: {
+        guides: {
+          type: 'array',
+          maxItems: 6,
+          items: { type: 'string', minLength: 1, maxLength: 120 },
+        },
         queries: {
           type: 'array',
           maxItems: 8,
@@ -140,7 +151,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_plan_task',
     description:
-      'After inspecting the live Framer target and before the first mutation, declare your semantic understanding, observable behavior requirements, chosen implementation mechanisms, and completion evidence. Dexter does not classify the request or choose mechanisms for you.',
+      'After inspecting the live Framer target and before the first mutation, declare your understanding of the task and the evidence you will produce. Dexter does not classify the request or choose how to build it; use any capability the Framer guidance documents.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -167,147 +178,27 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
           type: 'array',
           maxItems: 20,
           description:
-            'Required for interaction work. Describe observable behavior independently from its implementation.',
+            'Interactive or animated behaviors the result must have, such as links, hover or tap effects, overlays, variants, appear, loop, or ticker motion. Declaring behaviors adds interaction verification.',
           items: {
             type: 'object',
             properties: {
               id: { type: 'string', minLength: 1, maxLength: 120 },
-              description: { type: 'string', minLength: 5, maxLength: 500 },
-              triggerDescription: {
-                type: 'string',
-                minLength: 3,
-                maxLength: 300,
-              },
-              activation: {
-                type: 'string',
-                enum: BEHAVIOR_ACTIVATIONS,
-              },
-              presentation: {
-                type: 'string',
-                enum: BEHAVIOR_PRESENTATIONS,
-              },
-              stateChange: { type: 'boolean' },
-              layoutEffect: {
-                type: 'string',
-                enum: BEHAVIOR_LAYOUT_EFFECTS,
-              },
-              reversible: { type: 'boolean' },
-              repeatable: { type: 'boolean' },
-              expectedTargets: {
-                type: 'integer',
-                minimum: 1,
-                maximum: 50,
-              },
-              expectedContent: {
-                type: 'array',
-                maxItems: 20,
-                items: { type: 'string', minLength: 1, maxLength: 500 },
-                description:
-                  'Optional exact literal text that must exist in the interaction target. Do not put behavioral descriptions or prose assertions here.',
-              },
-              expectedDestinations: {
-                type: 'array',
-                maxItems: 20,
-                items: { type: 'string', minLength: 1, maxLength: 500 },
-                description:
-                  'Required for navigation behavior. Use exact routes or URLs such as /contact.',
-              },
-              initialState: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 300,
-              },
-              activatedState: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 300,
-              },
-            },
-            required: [
-              'id',
-              'description',
-              'triggerDescription',
-              'activation',
-              'presentation',
-              'stateChange',
-              'layoutEffect',
-              'reversible',
-              'repeatable',
-              'expectedTargets',
-              'initialState',
-              'activatedState',
-            ],
-            additionalProperties: false,
-          },
-        },
-        mechanisms: {
-          type: 'array',
-          maxItems: 20,
-          description:
-            'Required for every declared behavior. Choose the mechanism from live project capabilities and explain why it satisfies the behavior.',
-          items: {
-            type: 'object',
-            properties: {
-              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
-              mechanism: {
-                type: 'string',
-                enum: BEHAVIOR_MECHANISMS,
-              },
-              rationale: {
+              description: {
                 type: 'string',
-                minLength: 10,
-                maxLength: 800,
+                minLength: 5,
+                maxLength: 500,
+                description: 'What the visitor should experience.',
               },
-              representativeFirst: { type: 'boolean', default: true },
               targetNodeIds: {
                 type: 'array',
                 maxItems: 50,
                 uniqueItems: true,
-                items: {
-                  type: 'string',
-                  minLength: 1,
-                  maxLength: 200,
-                },
+                items: { type: 'string', minLength: 1, maxLength: 200 },
                 description:
-                  'All intended target node IDs. Required when expectedTargets is greater than one.',
-              },
-              representativeTargetNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-                description:
-                  'The single target to implement and verify before fan-out.',
-              },
-            },
-            required: ['behaviorId', 'mechanism', 'rationale'],
-            additionalProperties: false,
-          },
-        },
-        rejectedMechanisms: {
-          type: 'array',
-          maxItems: 30,
-          description:
-            'Mechanisms already disproven by user-observed failure or prior verification. Do not silently reuse them.',
-          items: {
-            type: 'object',
-            properties: {
-              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
-              behaviorSignature: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 128,
-              },
-              mechanism: {
-                type: 'string',
-                enum: BEHAVIOR_MECHANISMS,
-              },
-              reason: { type: 'string', minLength: 5, maxLength: 800 },
-              source: {
-                type: 'string',
-                enum: ['user_reported_failure', 'verification_failure'],
+                  'Every node that should carry this behavior once the work is done. Update the plan if they change, for example after replacing nodes.',
               },
             },
-            required: ['mechanism', 'reason'],
+            required: ['id', 'description'],
             additionalProperties: false,
           },
         },
@@ -319,7 +210,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_verify_interactions',
     description:
-      'Verify the observable behavior contract from live Framer evidence. Results are verified, contradicted, or unknown. Unknown evidence never proves failure and must not trigger mutation. Native links and component-control navigation are verified from destinations, not onTap. You may add a grounded semanticAssessment; it cannot override a deterministic contradiction or authorize writes.',
+      'Confirm planned behaviors against the live project. For each target node, name the Framer property that carries the behavior (for example loopEffect, hoverEffect, appearEffect, link, or onTap) and optionally a literal the value must contain (such as a route or SHOW_OVERLAY). Results: verified (the property is set and matches), contradicted (the property holds a different value), or unknown (the property was not found on the node). Unknown never blocks your work; it is reported as unverified. Checks accumulate across calls, so you can verify targets on several pages.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -327,103 +218,16 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
         checks: {
           type: 'array',
           minItems: 1,
-          maxItems: 20,
+          maxItems: 50,
           items: {
             type: 'object',
             properties: {
-              description: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 300,
-              },
-              behaviorId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 120,
-              },
-              triggerNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-              },
-              event: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 80,
-              },
-              expectedDestination: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 500,
-              },
-              targetNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-              },
-              componentNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-              },
-              instanceNodeIds: {
-                type: 'array',
-                maxItems: 50,
-                uniqueItems: true,
-                items: {
-                  type: 'string',
-                  minLength: 1,
-                  maxLength: 200,
-                },
-              },
-              openVariantNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-              },
-              closedVariantNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-              },
-              openAnswerNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-              },
-              closedAnswerNodeId: {
-                type: 'string',
-                minLength: 1,
-                maxLength: 200,
-              },
-              semanticAssessment: {
-                type: 'object',
-                properties: {
-                  verdict: {
-                    type: 'string',
-                    enum: ['verified', 'contradicted', 'unknown'],
-                  },
-                  rationale: {
-                    type: 'string',
-                    minLength: 10,
-                    maxLength: 1200,
-                  },
-                  evidenceNodeIds: {
-                    type: 'array',
-                    maxItems: 50,
-                    uniqueItems: true,
-                    items: {
-                      type: 'string',
-                      minLength: 1,
-                      maxLength: 200,
-                    },
-                  },
-                },
-                required: ['verdict', 'rationale', 'evidenceNodeIds'],
-                additionalProperties: false,
-              },
+              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
+              nodeId: { type: 'string', minLength: 1, maxLength: 200 },
+              property: { type: 'string', minLength: 1, maxLength: 120 },
+              contains: { type: 'string', minLength: 1, maxLength: 500 },
             },
-            required: ['behaviorId'],
+            required: ['behaviorId', 'nodeId', 'property'],
             additionalProperties: false,
           },
         },
@@ -477,6 +281,33 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'framer_add_svg',
+    description:
+      'Create an SVG layer from markup you write and place it inside a parent node. Use it for geometric and decorative artwork such as line work, starbursts, rings, sparkles, wireframe shapes, dividers, and simple marks. Use icon sets for icons, real text for text, and images for photos. Returns the new SVG node id; check it in a screenshot. To revise its markup later, use framer_write with setAttributes({ svg }) on that node.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        svg: {
+          type: 'string',
+          minLength: 1,
+          maxLength: MAX_SVG_MARKUP_CHARS,
+          description:
+            'One self-contained <svg> element with a viewBox. No scripts, event handlers, foreignObject, or external references.',
+        },
+        parentId: { type: 'string', minLength: 1, maxLength: 200 },
+        index: { type: 'integer', minimum: 0 },
+        name: { type: 'string', minLength: 1, maxLength: 120 },
+        attributes: {
+          type: 'object',
+          description:
+            'Optional Framer layer attributes for the SVG node, for example {"position":"absolute","top":"40px","left":"0px","width":"320px","height":"320px","rotation":12,"opacity":0.6}. Defaults to position relative at the SVG\'s own size.',
+        },
+      },
+      required: ['svg', 'parentId'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'framer_read_code_file',
     description:
@@ -646,6 +477,50 @@ function readGuidanceFile(projectRoot, relativePath, remainingBytes, section) {
   };
 }
 
+const CORE_GUIDE_SECTIONS = [
+  { file: 'how-projects-work', section: 'Scope Types' },
+  { file: 'how-projects-work', section: 'Replicas' },
+  { file: 'how-projects-work', section: 'Transforms' },
+  { file: 'implementation-strategy', section: 'Determining Strategy' },
+  { file: 'implementation-strategy', section: 'Edit Strategy' },
+  { file: 'implementation-strategy', section: 'Update Loop' },
+];
+const ON_DEMAND_GUIDE_FILES = [
+  { file: 'how-projects-work', sections: true },
+  { file: 'implementation-strategy', sections: true },
+  { file: 'core-examples', sections: false },
+];
+
+// Lists the topic guides that are not part of every prompt, keyed by
+// "file#Section" (or "file" for a whole file), from the files on disk.
+function onDemandGuideCatalog(projectRoot) {
+  const catalog = new Map();
+  for (const { file, sections } of ON_DEMAND_GUIDE_FILES) {
+    const relativePath = `prompt/${file}.md`;
+    const absolutePath = path.join(projectRoot, relativePath);
+    if (!fs.existsSync(absolutePath)) continue;
+    if (!sections) {
+      catalog.set(file, { root: projectRoot, path: relativePath });
+      continue;
+    }
+    const headings = fs.readFileSync(absolutePath, 'utf8')
+      .split('\n')
+      .filter((line) => line.startsWith('## '))
+      .map((line) => line.slice(3).trim())
+      .filter((heading) => !CORE_GUIDE_SECTIONS.some(
+        (core) => core.file === file && core.section === heading,
+      ));
+    for (const heading of headings) {
+      catalog.set(`${file}#${heading}`, {
+        root: projectRoot,
+        path: relativePath,
+        section: heading,
+      });
+    }
+  }
+  return catalog;
+}
+
 function markdownSection(markdown, heading) {
   const lines = markdown.split('\n');
   const start = lines.findIndex((line) => line.trim() === `## ${heading}`);
@@ -742,7 +617,7 @@ function normalizeCodeFilePath(value) {
   return filePath;
 }
 
-function codeFileResultError(result, fallbackCode, fallbackMessage) {
+function structuredResultError(result, fallbackCode, fallbackMessage) {
   const error = isRecord(result?.error) ? result.error : {};
   const code =
     typeof error.code === 'string' && error.code.trim()
@@ -753,7 +628,7 @@ function codeFileResultError(result, fallbackCode, fallbackMessage) {
       ? error.message.trim().slice(0, 2_000)
       : fallbackMessage;
   const statusCode =
-    code === 'FRAMER_CODE_FILE_NOT_FOUND'
+    code === 'FRAMER_CODE_FILE_NOT_FOUND' || code === 'FRAMER_SVG_PARENT_NOT_FOUND'
       ? 404
       : code === 'FRAMER_CODE_FILE_VERSION_CONFLICT'
         ? 409
@@ -779,7 +654,7 @@ function normalizeVerificationValues(values, allowed) {
     .filter((value) => allowed.includes(value));
 }
 
-function normalizeTaskPlan(rawArguments, inheritedRejectedMechanisms = []) {
+function normalizeTaskPlan(rawArguments) {
   const summary = String(rawArguments.summary || '').trim().slice(0, 1000);
   const domains = normalizeVerificationValues(
     rawArguments.domains,
@@ -798,19 +673,7 @@ function normalizeTaskPlan(rawArguments, inheritedRejectedMechanisms = []) {
   // The model's declared verification is authoritative; domains describe the
   // work and never add checks on their own.
   const verification = new Set(['structural', ...requestedVerification]);
-  const behaviorPlan = normalizeBehaviorPlan(
-    rawArguments,
-    inheritedRejectedMechanisms,
-  );
-  if (
-    domains.includes('interactions')
-    && behaviorPlan.behaviors.length === 0
-  ) {
-    throw toolError(
-      'FRAMER_BEHAVIOR_CONTRACT_REQUIRED',
-      'Interaction work requires observable behaviors and one compatible mechanism decision per behavior.',
-    );
-  }
+  const behaviorPlan = normalizeBehaviorPlan(rawArguments);
   if (behaviorPlan.behaviors.length > 0) {
     if (!domains.includes('interactions')) domains.push('interactions');
     verification.add('interactions');
@@ -936,6 +799,28 @@ function authoritativeNodeIdsFromAssignment(assignment) {
   ]);
 }
 
+const LITERAL_TOKEN_TYPES = new Set([
+  'StringLiteral',
+  'NoSubstitutionTemplate',
+  'TemplateHead',
+  'TemplateMiddle',
+  'TemplateTail',
+  'SingleLineComment',
+  'MultiLineComment',
+  'RegularExpressionLiteral',
+]);
+
+// Blanks string, template, comment, and regex text so data such as image URLs
+// or product copy is not mistaken for a forbidden global. Template
+// substitutions stay visible because they are code.
+function codeOutsideLiterals(code) {
+  let visible = '';
+  for (const token of jsTokens(code)) {
+    visible += LITERAL_TOKEN_TYPES.has(token.type) ? ' ' : token.value;
+  }
+  return visible;
+}
+
 function validateCode(value, { write = false, allowPublishing = false } = {}) {
   const code = String(value || '').trim();
   if (!code) {
@@ -944,7 +829,7 @@ function validateCode(value, { write = false, allowPublishing = false } = {}) {
       'Framer Agent code is required.',
     );
   }
-  if (UNSAFE_EXEC_PATTERN.test(code)) {
+  if (UNSAFE_EXEC_PATTERN.test(codeOutsideLiterals(code))) {
     throw toolError(
       'FRAMER_AGENT_CODE_UNSAFE',
       'Framer Agent code may use only the provided framer, state, and console globals.',
@@ -968,6 +853,35 @@ function validateCode(value, { write = false, allowPublishing = false } = {}) {
   return code;
 }
 
+function normalizeSvgMarkup(value) {
+  const svg = String(value || '').trim();
+  if (!/^<svg\b[\s\S]*<\/svg>$/i.test(svg) || svg.length > MAX_SVG_MARKUP_CHARS) {
+    throw toolError(
+      'FRAMER_SVG_INVALID',
+      `Provide one <svg>…</svg> element of at most ${MAX_SVG_MARKUP_CHARS} characters.`,
+    );
+  }
+  if (UNSAFE_SVG_PATTERN.test(svg)) {
+    throw toolError(
+      'FRAMER_SVG_UNSAFE',
+      'SVG markup must be self-contained: no scripts, event handlers, foreignObject, or external references.',
+    );
+  }
+  return svg;
+}
+
+function normalizeSvgAttributes(value) {
+  if (value === undefined) return {};
+  if (!isRecord(value) || Object.keys(value).length > MAX_SVG_ATTRIBUTES) {
+    throw toolError(
+      'FRAMER_SVG_ATTRIBUTES_INVALID',
+      `attributes must be an object with at most ${MAX_SVG_ATTRIBUTES} Framer layer attributes.`,
+    );
+  }
+  const { svg: _ignored, ...attributes } = value;
+  return attributes;
+}
+
 function extractJsonArray(value) {
   const text = String(value || '').trim();
   const start = text.indexOf('[');
@@ -1246,32 +1160,9 @@ export function createFramerAgentToolRuntime({
     );
   }
   const allowPublishing = assignment?.context?.permissions?.publish === true;
-  const inheritedRejectedMechanisms =
-    assignment?.context?.repairContext?.rejectedMechanisms
-    || assignment?.repairContext?.rejectedMechanisms
-    || [];
-  const authorizedInstanceContainerIds = uniqueStrings(
-    assignment?.context?.permissions?.scopedComponentArtifacts
-      ?.instanceContainerNodeIds
-      || assignment?.context?.contextGrant?.writableNodeIds
-      || [],
-  );
   const activePagePath = normalizePagePath(
     assignment?.context?.activePagePath,
   );
-  const semanticVerifierMode =
-    ['off', 'shadow', 'enforce'].includes(
-      String(
-        assignment?.context?.harnessAuthority?.semanticVerifierMode
-        || env.DEXTER_FRAMER_SEMANTIC_VERIFIER_MODE
-        || '',
-      ).trim(),
-    )
-      ? String(
-          assignment?.context?.harnessAuthority?.semanticVerifierMode
-          || env.DEXTER_FRAMER_SEMANTIC_VERIFIER_MODE,
-        ).trim()
-      : 'enforce';
   const authoritativeNodeIds =
     authoritativeNodeIdsFromAssignment(assignment);
   let sessionId = null;
@@ -1303,20 +1194,10 @@ export function createFramerAgentToolRuntime({
   let lastMutationAt = null;
   let screenshotCalls = 0;
   let interactionVerificationCalls = 0;
-  let interactionVerification = {
-    completed: false,
-    verificationLevel: 'unknown',
-    checks: [],
-    behaviors: [],
-    budgetExhaustedBehaviorIds: [],
-    verifiedAt: null,
-  };
-  const representativeVerifiedBehaviorIds = new Set();
-  const representativeMutatedBehaviorIds = new Set();
-  const representativeRepairNodeIds = new Set();
-  const representativeRepairBehaviorByNode = new Map();
-  const representativeEvidenceBehaviorByNode = new Map();
-  const behaviorVerificationAttempts = new Map();
+  // Latest result per behavior/node/property, with the operation sequence it
+  // was observed at, so checks from several calls (or pages) accumulate.
+  const interactionCheckResults = new Map();
+  let interactionVerifiedAt = null;
   const mutationReceipts = [];
   let lastScreenshotSequence = 0;
   let lastScreenshotAttemptSequence = 0;
@@ -1326,6 +1207,8 @@ export function createFramerAgentToolRuntime({
   const screenshotFailures = [];
   let taskPlan = null;
   const verificationEvidence = new Map();
+  let guideCatalog = new Map();
+  const guidesRead = [];
   let guidanceMetadata = {
     loaded: false,
     contentHash: null,
@@ -1334,6 +1217,7 @@ export function createFramerAgentToolRuntime({
     bytes: 0,
   };
   let promptMetadata = {
+    promptBytes: 0,
     doctrineLoaded: false,
     doctrineVersion: null,
   };
@@ -1343,6 +1227,7 @@ export function createFramerAgentToolRuntime({
   const framerAgentVersion = installedFramerAgentVersion();
   let operationSequence = 0;
   let lastMutationSequence = 0;
+  let lastCodeMutationSequence = 0;
   let lastInspectionSequence = 0;
   const abortController = new AbortController();
 
@@ -1649,6 +1534,10 @@ export function createFramerAgentToolRuntime({
     if (!fs.existsSync(projectRoot)) {
       return { content: '', ...guidanceMetadata };
     }
+    // Every run gets the guidance an edit always needs: principles, command
+    // syntax, tool APIs, scope and replica rules, and the edit loop. Topic
+    // guides (CMS, components, creation strategy, examples, ...) are listed
+    // in a catalog and read on demand through framer_instructions.
     const requestedFiles = [
       { root: skillRoot, path: 'SKILL.md', label: 'SKILL.md' },
       { root: projectRoot, path: 'index.md', label: 'project/index.md' },
@@ -1657,24 +1546,19 @@ export function createFramerAgentToolRuntime({
         path: 'project-inventory.md',
         label: 'project/project-inventory.md',
       },
-      { root: projectRoot, path: 'prompt/core-principles.md' },
-      { root: projectRoot, path: 'prompt/core-examples.md' },
-      { root: projectRoot, path: 'prompt/implementation-strategy.md' },
-      { root: projectRoot, path: 'prompt/updating-the-project.md' },
-      { root: projectRoot, path: 'prompt/tools.md' },
       { root: projectRoot, path: 'prompt/overview.md' },
+      { root: projectRoot, path: 'prompt/core-principles.md' },
       { root: projectRoot, path: 'prompt/guardrails.md' },
       { root: projectRoot, path: 'prompt/critical-reminders.md' },
-      // The byte cap clips how-projects-work.md before its 3D transform
-      // guidance, so that section loads on its own first.
-      {
-        root: projectRoot,
-        path: 'prompt/how-projects-work.md',
-        section: 'Transforms',
-        label: 'prompt/how-projects-work.md#transforms',
-      },
       { root: projectRoot, path: 'prompt/design-rules.md' },
-      { root: projectRoot, path: 'prompt/how-projects-work.md' },
+      { root: projectRoot, path: 'prompt/updating-the-project.md' },
+      { root: projectRoot, path: 'prompt/tools.md' },
+      ...CORE_GUIDE_SECTIONS.map(({ file, section }) => ({
+        root: projectRoot,
+        path: `prompt/${file}.md`,
+        section,
+        label: `prompt/${file}.md#${section}`,
+      })),
     ];
     const files = [];
     let remainingBytes = MAX_GUIDANCE_BYTES;
@@ -1693,9 +1577,19 @@ export function createFramerAgentToolRuntime({
       remainingBytes -= Buffer.byteLength(loaded.content, 'utf8');
       if (remainingBytes <= 0) break;
     }
-    const content = files
-      .map((file) => `## ${file.path}\n\n${file.content}`)
-      .join('\n\n');
+    guideCatalog = onDemandGuideCatalog(projectRoot);
+    const catalogText = guideCatalog.size > 0
+      ? [
+          '## On-demand guides',
+          '',
+          'Read a guide with framer_instructions({ guides: [id] }) before work that depends on it.',
+          ...[...guideCatalog.keys()].map((id) => `- ${id}`),
+        ].join('\n')
+      : '';
+    const content = [
+      ...files.map((file) => `## ${file.path}\n\n${file.content}`),
+      ...(catalogText ? [catalogText] : []),
+    ].join('\n\n');
     const inventory = files.find(
       (file) => file.path.endsWith('project-inventory.md'),
     )?.content || '';
@@ -1716,8 +1610,10 @@ export function createFramerAgentToolRuntime({
   const configurePromptContext = ({
     doctrineLoaded = false,
     doctrineVersion = null,
+    promptBytes = 0,
   } = {}) => {
     promptMetadata = {
+      promptBytes: Math.max(0, Number(promptBytes) || 0),
       doctrineLoaded: doctrineLoaded === true,
       doctrineVersion:
         typeof doctrineVersion === 'string' && doctrineVersion.trim()
@@ -1858,9 +1754,14 @@ export function createFramerAgentToolRuntime({
     return result;
   };
 
+  // Selected layers that do not resolve to native nodes (stale selections,
+  // aliases, layers inside component instances) no longer stop the run. The
+  // model is told which targets to locate by name, and the reason is kept for
+  // debugging.
+  let unresolvedTargets = [];
   const validateAuthoritativeNodeIds = async () => {
     await ensureSession();
-    if (authoritativeNodeIds.length === 0) return;
+    if (authoritativeNodeIds.length === 0) return { unresolvedTargets };
     if (nodeValidationPromise) return nodeValidationPromise;
     nodeValidationPromise = (async () => {
       reportActivity({
@@ -1872,9 +1773,13 @@ export function createFramerAgentToolRuntime({
         [
           `const requestedIds = ${JSON.stringify(authoritativeNodeIds)};`,
           'const resolved = await Promise.all(requestedIds.map(async (requestedId) => {',
-          '  const node = await framer.agent.getNode({ id: requestedId },',
-          `    { pagePath: ${JSON.stringify(activePagePath)} }).catch(() => null);`,
-          '  return { requestedId, resolvedId: node?.id ?? null };',
+          '  try {',
+          '    const node = await framer.agent.getNode({ id: requestedId },',
+          `      { pagePath: ${JSON.stringify(activePagePath)} });`,
+          '    return { requestedId, resolvedId: node?.id ?? null, error: node ? null : "not found on the active page" };',
+          '  } catch (error) {',
+          '    return { requestedId, resolvedId: null, error: String(error?.message || error).slice(0, 200) };',
+          '  }',
           '}));',
           'console.log(JSON.stringify({ resolved }));',
         ].join('\n'),
@@ -1884,26 +1789,30 @@ export function createFramerAgentToolRuntime({
       const resolved = Array.isArray(parsed?.resolved)
         ? parsed.resolved
         : [];
-      const invalid = authoritativeNodeIds.filter((requestedId) => {
+      unresolvedTargets = authoritativeNodeIds.flatMap((requestedId) => {
         const match = resolved.find(
           (entry) =>
             isRecord(entry)
             && entry.requestedId === requestedId,
         );
-        return !match || match.resolvedId !== requestedId;
+        if (match?.resolvedId === requestedId) return [];
+        return [{
+          id: requestedId,
+          reason: !match
+            ? 'not checked'
+            : match.resolvedId
+              ? `resolves to ${match.resolvedId}`
+              : String(match.error || 'not found on the active page'),
+        }];
       });
-      if (invalid.length > 0) {
-        throw toolError(
-          'FRAMER_AGENT_NODE_ID_INVALID',
-          `Dexter received Framer targets that do not resolve to exact native node IDs: ${invalid.join(', ')}. Re-select the affected layers in Framer and try again.`,
-          409,
-        );
-      }
       reportActivity({
         kind: 'status_update',
         source: 'framer-agent',
-        message: 'The selected Framer layers are ready.',
+        message: unresolvedTargets.length > 0
+          ? 'Some selected layers could not be matched exactly, so Dexter will locate them by name.'
+          : 'The selected Framer layers are ready.',
       });
+      return { unresolvedTargets };
     })().catch((error) => {
       nodeValidationPromise = null;
       throw error;
@@ -1954,9 +1863,10 @@ export function createFramerAgentToolRuntime({
     }
   };
 
-  const markMutation = () => {
+  const markMutation = ({ code = false } = {}) => {
     operationSequence += 1;
     lastMutationSequence = operationSequence;
+    if (code) lastCodeMutationSequence = operationSequence;
     lastMutationAt = new Date().toISOString();
   };
 
@@ -1972,30 +1882,35 @@ export function createFramerAgentToolRuntime({
         ? {
             behaviors: taskPlan.behaviors.map((behavior) => ({
               ...behavior,
-              expectedContent: [...behavior.expectedContent],
-              expectedDestinations: [...behavior.expectedDestinations],
-            })),
-            mechanisms: taskPlan.mechanisms.map((decision) => ({
-              ...decision,
-              targetNodeIds: [...decision.targetNodeIds],
-            })),
-            rejectedMechanisms: taskPlan.rejectedMechanisms.map((entry) => ({
-              ...entry,
-            })),
-            compatibility: taskPlan.compatibility.map((entry) => ({
-              ...entry,
-              requiredCapabilities: [...entry.requiredCapabilities],
+              targetNodeIds: [...behavior.targetNodeIds],
             })),
           }
         : {}),
     };
   };
+  // Only checks observed after the latest mutation describe the current project.
+  const freshInteractionChecks = () =>
+    [...interactionCheckResults.values()]
+      .filter((entry) => entry.sequence > lastMutationSequence)
+      .map((entry) => entry.result);
+  const interactionSummary = () =>
+    summarizeBehaviorVerification(taskPlan, freshInteractionChecks());
+  const interactionStatus = () => {
+    if (!taskPlan?.behaviors?.length || mutationCalls === 0) return 'not_required';
+    return interactionSummary().status;
+  };
   const synchronized = () =>
     mutationCalls === 0 || lastInspectionSequence > lastMutationSequence;
   const verificationCheckCompleted = (check) => {
     if (mutationCalls === 0) return true;
     if (check === 'structural') return synchronized();
-    return Number(verificationEvidence.get(check) || 0) > lastMutationSequence;
+    if (check === 'interactions') {
+      return ['verified', 'not_required'].includes(interactionStatus());
+    }
+    // Canvas edits cannot change a code file, so only code edits stale it.
+    const staleAfter =
+      check === 'code' ? lastCodeMutationSequence : lastMutationSequence;
+    return Number(verificationEvidence.get(check) || 0) > staleAfter;
   };
   const visualVerificationRequired = () =>
     requiredVerificationChecks().includes('visual');
@@ -2013,12 +1928,19 @@ export function createFramerAgentToolRuntime({
   const requiredChecks = () => [
     ...new Set(['structural', ...requiredVerificationChecks()]),
   ];
+  // Checks the model attempted but that live evidence could not confirm. They
+  // are reported as unverified and do not fail the run.
+  const unavailableChecks = () => [
+    ...(visualVerificationStatus() === 'unavailable' ? ['visual'] : []),
+    ...(interactionStatus() === 'unverified' ? ['interactions'] : []),
+  ];
   const missingVerificationChecks = () => {
     if (mutationCalls === 0) return [];
     const missing = [];
     if (!taskPlan) missing.push('task-plan');
+    const unavailable = unavailableChecks();
     for (const check of requiredChecks()) {
-      if (check === 'visual' && visualVerificationUnavailable()) continue;
+      if (unavailable.includes(check)) continue;
       if (!verificationCheckCompleted(check)) missing.push(check);
     }
     return missing;
@@ -2046,48 +1968,17 @@ export function createFramerAgentToolRuntime({
       ? {
           interactionVerificationCalls,
           interactionVerification: {
-            completed: verificationCheckCompleted('interactions'),
-            verificationLevel:
-              verificationCheckCompleted('interactions')
-                ? interactionVerification.verificationLevel
-                : 'unknown',
-            checks: interactionVerification.checks.map((check) => ({
-              ...check,
-              contradictions: [...check.contradictions],
-              unknowns: [...check.unknowns],
-              observations: check.observations.map((observation) => ({
-                ...observation,
-              })),
-              nextSafeActions: [...check.nextSafeActions],
-              ...(check.semanticAssessment
-                ? {
-                    semanticAssessment: {
-                      ...check.semanticAssessment,
-                      evidenceNodeIds: [
-                        ...check.semanticAssessment.evidenceNodeIds,
-                      ],
-                    },
-                  }
-                : {}),
-            })),
-            behaviors: interactionVerification.behaviors.map((behavior) => ({
-              ...behavior,
-              contradictions: [...behavior.contradictions],
-              unknowns: [...behavior.unknowns],
-            })),
-            semanticVerifierMode,
-            budgetExhaustedBehaviorIds: [
-              ...interactionVerification.budgetExhaustedBehaviorIds,
-            ],
-            verifiedAt: interactionVerification.verifiedAt,
+            status: interactionStatus(),
+            behaviors: taskPlan?.behaviors?.length ? interactionSummary().behaviors : [],
+            checks: freshInteractionChecks().map((check) => ({ ...check })),
+            verifiedAt: interactionVerifiedAt,
           },
         }
       : {}),
     taskPlan: taskPlanSnapshot(),
     requiredChecks: requiredChecks(),
     completedChecks: requiredChecks().filter(verificationCheckCompleted),
-    unavailableChecks:
-      visualVerificationStatus() === 'unavailable' ? ['visual'] : [],
+    unavailableChecks: unavailableChecks(),
     missingChecks: missingVerificationChecks(),
     lastMutationAt,
     lastInspectionAt,
@@ -2109,49 +2000,58 @@ export function createFramerAgentToolRuntime({
     };
   };
 
-  const withUnavailableVisualCheck = (completion) =>
-    visualVerificationStatus() === 'unavailable'
-      ? {
-          ...completion,
-          checks: [
-            ...(Array.isArray(completion?.checks) ? completion.checks : []),
-            {
+  const withUnavailableChecks = (completion) => {
+    const unavailable = unavailableChecks();
+    if (unavailable.length === 0) return completion;
+    const unverifiedBehaviors = interactionSummary().behaviors
+      .filter((behavior) => behavior.verdict === 'unknown')
+      .map((behavior) => `${behavior.behaviorId} (${behavior.unknowns[0] || 'not confirmed'})`);
+    return {
+      ...completion,
+      checks: [
+        ...(Array.isArray(completion?.checks) ? completion.checks : []),
+        ...(unavailable.includes('visual')
+          ? [{
               command: 'Visual verification',
               status: 'skipped',
               output:
                 'Screenshots of the final canvas could not be delivered to the model, so the visual result is unverified.',
-            },
-          ],
-        }
-      : completion;
+            }]
+          : []),
+        ...(unavailable.includes('interactions')
+          ? [{
+              command: 'Interaction verification',
+              status: 'skipped',
+              output:
+                `The live project did not expose evidence for: ${unverifiedBehaviors.join('; ')}. These behaviors are unverified.`,
+            }]
+          : []),
+      ],
+    };
+  };
 
   const finalizeCompletion = (completion) => {
     if (completion?.status !== 'completed' || mutationCalls === 0) {
       return completion;
     }
-    if (verification().completed) return withUnavailableVisualCheck(completion);
+    if (verification().completed) return withUnavailableChecks(completion);
     const missing = missingVerificationChecks().map((check) => {
       if (check === 'task-plan') return 'a harness task and verification plan';
       if (check === 'structural') return 'a final structural read';
       if (check === 'visual') return 'post-mutation screenshot verification';
       return `post-mutation ${check} verification`;
     });
-    const interactionDetails = interactionVerification.behaviors
-      .filter((behavior) => behavior.verdict !== 'verified')
-      .map((behavior) => {
-        const detail =
-          behavior.contradictions[0]
-          || behavior.unknowns[0]
-          || 'no conclusive live evidence';
-        return `${behavior.behaviorId}=${behavior.verdict} (${detail})`;
-      });
+    const interactionDetails = (taskPlan?.behaviors?.length ? interactionSummary().behaviors : [])
+      .filter((behavior) => behavior.verdict === 'contradicted' || !behavior.checked)
+      .map((behavior) =>
+        `${behavior.behaviorId}=${behavior.verdict === 'contradicted' ? behavior.contradictions[0] : 'not checked after the latest change'}`);
     const reason = [
       `The harness ended before completing ${missing.join(' and ')}.`,
       ...(interactionDetails.length > 0
         ? [`Interaction evidence: ${interactionDetails.join('; ')}.`]
         : []),
     ].join(' ');
-    const failed = withUnavailableVisualCheck(completion);
+    const failed = withUnavailableChecks(completion);
     return {
       ...failed,
       status: 'failed',
@@ -2170,6 +2070,22 @@ export function createFramerAgentToolRuntime({
     };
   };
 
+  // A model that reports failure without changing anything and without a
+  // refused plan or edit gave up on its own. It gets one prompt to continue.
+  const unblockedFailurePrompt = (completion) => {
+    if (completion?.status !== 'failed' || mutationCalls > 0) return null;
+    const lastGate = [...toolCalls]
+      .reverse()
+      .find((call) => call.category === 'plan' || call.category === 'mutation');
+    if (lastGate?.status === 'failed') return null;
+    return [
+      'You returned failed without changing the Framer project, and no tool refused the work.',
+      'Nothing in this run is blocking you and there is no time limit.',
+      'Continue the same task from the current project state: plan it, apply the change, verify it, then return the required JSON outcome.',
+      'Return failed or blocked only for a concrete blocker you can name.',
+    ].join(' ');
+  };
+
   const verificationRepairPrompt = () => {
     const current = verification();
     if (current.completed || mutationCalls === 0) return null;
@@ -2185,27 +2101,33 @@ export function createFramerAgentToolRuntime({
         missing.push(
           'capture and inspect a screenshot of the affected canvas after the latest mutation',
         );
+      } else if (check === 'interactions') {
+        const summary = interactionSummary();
+        const unchecked = summary.behaviors
+          .filter((behavior) => !behavior.checked)
+          .map((behavior) => behavior.uncheckedTargets.length
+            ? `${behavior.behaviorId} on ${behavior.uncheckedTargets.join(', ')}`
+            : behavior.behaviorId);
+        const contradicted = summary.behaviors
+          .filter((behavior) => behavior.verdict === 'contradicted')
+          .map((behavior) => behavior.contradictions[0]);
+        missing.push([
+          unchecked.length
+            ? `call framer_verify_interactions for ${unchecked.join('; ')}, naming the Framer property that carries each behavior`
+            : '',
+          contradicted.length
+            ? `fix or explain these mismatches: ${contradicted.join('; ')}`
+            : '',
+        ].filter(Boolean).join(' and '));
       } else {
-        const interactionState = interactionVerification.behaviors
-          .map((behavior) =>
-            `${behavior.behaviorId}:${behavior.verdict}`)
-          .join(', ');
-        const exhausted =
-          interactionVerification.budgetExhaustedBehaviorIds.length > 0;
-        missing.push(
-          check === 'interactions'
-            ? exhausted
-              ? `report interaction verification as incomplete without further mutation or repeated verification (${interactionState || 'unknown'})`
-              : `call framer_verify_interactions with canonical evidence node IDs for every declared behavior and chosen mechanism; repair only contradicted evidence, while unknown evidence requires a different read or grounded semantic assessment (${interactionState || 'not yet checked'})`
-            : `perform a focused read tagged with verifies:["${check}"] after the latest mutation`,
-        );
+        missing.push(`perform a focused read tagged with verifies:["${check}"] after the latest mutation`);
       }
     }
     return [
       'Continue the same Framer task from its current project state.',
       'Do not redo successful work.',
       `Before returning, ${missing.join(' and ')}.`,
-      'Never mutate merely because evidence is unknown. Repair one observed contradiction at most once, then return the required JSON outcome.',
+      'If the live project does not expose a property, report that behavior as unverified rather than changing working parts. Then return the required JSON outcome.',
     ].join(' ');
   };
 
@@ -2219,6 +2141,7 @@ export function createFramerAgentToolRuntime({
         'Use framer_read_project for supported project queries such as screenshots.',
         'To place a user attachment in the project, call framer_upload_attachment with its id from context.referenceAssetFiles and use the returned url as the image fill. Never upload user files to external services.',
         'Use framer_query_images for approved stock imagery only after checking user attachments and suitable existing project images.',
+        'Use framer_add_svg for geometric or decorative artwork you draw as SVG markup; use icon sets for icons and real text for text.',
         'Use framer_apply_changes for layout and styling. Read its diagnostics, verify the result, and repair concrete issues.',
         'Use framer_read_code_file and framer_update_code_file for existing code components and overrides instead of generic JavaScript.',
         'If framer_write is rejected as unsafe, do not retry JavaScript variants. Switch to framer_apply_changes or report the concrete blocker.',
@@ -2250,109 +2173,13 @@ export function createFramerAgentToolRuntime({
       .update(`${name}\n${JSON.stringify(rawArguments)}`)
       .digest('hex');
 
-  const representativeRepairTargets = (changes) => {
-    const commands = summarizeFramerChanges(changes).commands;
-    if (
-      commands.length === 0
-      || commands.some((command) =>
-        command.operation !== 'set'
-        || !command.nodeId
-        || !representativeRepairNodeIds.has(command.nodeId))
-    ) {
-      return [];
-    }
-    return uniqueStrings(commands.map((command) => command.nodeId));
-  };
-
-  const requireTaskPlanForMutation = ({ changes = '' } = {}) => {
+  const requireTaskPlanForMutation = () => {
     if (!taskPlan) {
       throw toolError(
         'FRAMER_HARNESS_PLAN_REQUIRED',
         'Inspect the live Framer target, then call framer_plan_task before making a mutation.',
       );
     }
-    const repairTargets = representativeRepairTargets(changes);
-    const isRepresentativeRepair = repairTargets.length > 0;
-    const rejectedSelectedMechanisms = taskPlan.behaviors.filter((behavior) => {
-      const selected = taskPlan.mechanisms.find((decision) =>
-        decision.behaviorId === behavior.id);
-      return selected && taskPlan.rejectedMechanisms.some((rejected) =>
-        rejected.mechanism === selected.mechanism
-        && (
-          rejected.behaviorId === behavior.id
-          || rejected.behaviorSignature === behavior.signature
-        ));
-    });
-    if (rejectedSelectedMechanisms.length > 0) {
-      throw toolError(
-        'FRAMER_BEHAVIOR_MECHANISM_REPLAN_REQUIRED',
-        `Choose a different mechanism for ${rejectedSelectedMechanisms.map((behavior) => behavior.id).join(', ')} before making another mutation.`,
-      );
-    }
-    const changedNodeIds = new Set(
-      summarizeFramerChanges(changes).commands
-        .flatMap((command) => [
-          command.nodeId,
-          command.sourceNodeId,
-        ])
-        .filter(Boolean),
-    );
-    const rawChanges = String(changes || '');
-    const pendingRepresentative = taskPlan.behaviors
-      .filter((behavior) => behavior.expectedTargets > 1)
-      .map((behavior) => ({
-        behavior,
-        decision: taskPlan.mechanisms.find((decision) =>
-          decision.behaviorId === behavior.id),
-      }))
-      .filter(({ decision }) => decision?.representativeFirst)
-      .filter(({ behavior }) =>
-        !representativeVerifiedBehaviorIds.has(behavior.id));
-    for (const { behavior, decision } of pendingRepresentative) {
-      const touchedTargets = decision.targetNodeIds.filter((nodeId) =>
-        rawChanges.includes(nodeId));
-      const touchedEvidence = [...changedNodeIds].filter((nodeId) =>
-        representativeEvidenceBehaviorByNode.get(nodeId) === behavior.id);
-      if (
-        touchedTargets.length > 1
-        || (
-          touchedTargets.length === 1
-          && touchedTargets[0] !== decision.representativeTargetNodeId
-        )
-      ) {
-        throw toolError(
-          'FRAMER_BEHAVIOR_REPRESENTATIVE_MUTATION_REQUIRED',
-          `Implement only representative target ${decision.representativeTargetNodeId} for ${behavior.id} before changing the remaining targets.`,
-        );
-      }
-      if (touchedTargets.length === 0 && touchedEvidence.length === 0) {
-        continue;
-      }
-      if (!representativeMutatedBehaviorIds.has(behavior.id)) continue;
-      const attempt = behaviorVerificationAttempts.get(behavior.id);
-      const repairForBehavior =
-        isRepresentativeRepair
-        && repairTargets.every((nodeId) =>
-          representativeRepairBehaviorByNode.get(nodeId) === behavior.id);
-      if (
-        !repairForBehavior
-        || Number(attempt?.repairs || 0)
-          >= MAX_INTERACTION_REPAIRS_PER_BEHAVIOR
-      ) {
-        throw toolError(
-          'FRAMER_BEHAVIOR_REPRESENTATIVE_VERIFICATION_REQUIRED',
-          `Verify representative target ${decision.representativeTargetNodeId} for ${behavior.id} before changing it again or batching the remaining targets.`,
-        );
-      }
-      behaviorVerificationAttempts.set(behavior.id, {
-        ...attempt,
-        repairs: Number(attempt?.repairs || 0) + 1,
-      });
-    }
-    return pendingRepresentative
-      .filter(({ decision }) =>
-        rawChanges.includes(decision.representativeTargetNodeId))
-      .map(({ behavior }) => behavior.id);
   };
 
   async function invokeUnsafe(name, rawArguments = {}) {
@@ -2374,10 +2201,7 @@ export function createFramerAgentToolRuntime({
         'Framer Agent tool arguments must be an object.',
       );
     }
-    const mutation =
-      name === 'framer_apply_changes'
-      || name === 'framer_update_code_file'
-      || name === 'framer_write';
+    const mutation = MUTATION_TOOL_NAMES.has(name);
     const category =
       name === 'framer_plan_task'
         ? 'plan'
@@ -2423,9 +2247,7 @@ export function createFramerAgentToolRuntime({
       name,
       phase: 'started',
       message:
-        name === 'framer_apply_changes'
-        || name === 'framer_update_code_file'
-        || name === 'framer_write'
+        mutation
           ? 'Updating the Framer project'
           : name === 'framer_plan_task'
             ? 'Planning the Framer work and verification'
@@ -2444,7 +2266,40 @@ export function createFramerAgentToolRuntime({
         const queries = Array.isArray(rawArguments.queries)
           ? uniqueStrings(rawArguments.queries, 8)
           : [];
-        if (queries.length > 0 && !instructionLookupUnavailable) {
+        const guideIds = Array.isArray(rawArguments.guides)
+          ? uniqueStrings(rawArguments.guides, 6)
+          : [];
+        if (guideIds.length > 0) {
+          const guides = guideIds.flatMap((id) => {
+            const entry = guideCatalog.get(id);
+            const loaded = entry
+              ? readGuidanceFile(
+                  entry.root,
+                  entry.path,
+                  MAX_GUIDANCE_FILE_BYTES,
+                  entry.section,
+                )
+              : null;
+            if (!loaded) return [];
+            if (!guidesRead.includes(id)) guidesRead.push(id);
+            return [{ id, content: loaded.content }];
+          });
+          const unknown = guideIds.filter(
+            (id) => !guides.some((guide) => guide.id === id),
+          );
+          result = {
+            stdout: JSON.stringify({
+              guides,
+              ...(unknown.length > 0
+                ? {
+                    unknownGuides: unknown,
+                    availableGuides: [...guideCatalog.keys()],
+                  }
+                : {}),
+            }),
+            stderr: '',
+          };
+        } else if (queries.length > 0 && !instructionLookupUnavailable) {
           try {
             result = await executeCli(
               ['docs', ...queries],
@@ -2487,22 +2342,7 @@ export function createFramerAgentToolRuntime({
             'Inspect the live Framer target before declaring the task and verification plan.',
           );
         }
-        const nextPlan = normalizeTaskPlan(
-          rawArguments,
-          inheritedRejectedMechanisms,
-        );
-        const previousMechanisms = new Map(
-          (taskPlan?.mechanisms || []).map((decision) => [
-            decision.behaviorId,
-            JSON.stringify({
-              mechanism: decision.mechanism,
-              targetNodeIds: decision.targetNodeIds,
-              representativeTargetNodeId:
-                decision.representativeTargetNodeId,
-            }),
-          ]),
-        );
-        const behaviorPlan = mergeBehaviorPlans(taskPlan, nextPlan);
+        const nextPlan = normalizeTaskPlan(rawArguments);
         taskPlan = {
           summary: nextPlan.summary,
           domains: uniqueStrings([
@@ -2513,280 +2353,55 @@ export function createFramerAgentToolRuntime({
             ...(taskPlan?.verification || []),
             ...nextPlan.verification,
           ]),
-          ...behaviorPlan,
+          ...mergeBehaviorPlans(taskPlan, nextPlan),
         };
-        for (const decision of taskPlan.mechanisms) {
-          const prior = previousMechanisms.get(decision.behaviorId);
-          const current = JSON.stringify({
-            mechanism: decision.mechanism,
-            targetNodeIds: decision.targetNodeIds,
-            representativeTargetNodeId:
-              decision.representativeTargetNodeId,
-          });
-          if (prior && prior !== current) {
-            representativeVerifiedBehaviorIds.delete(decision.behaviorId);
-            representativeMutatedBehaviorIds.delete(decision.behaviorId);
-            behaviorVerificationAttempts.delete(decision.behaviorId);
-          }
-        }
         result = {
-          stdout: JSON.stringify({
-            plan: {
-              summary: taskPlan.summary,
-              domains: [...taskPlan.domains],
-              verification: [...taskPlan.verification],
-              behaviors: taskPlan.behaviors.map((behavior) => ({
-                ...behavior,
-                expectedContent: [...behavior.expectedContent],
-              })),
-              mechanisms: taskPlan.mechanisms.map((decision) => ({
-                ...decision,
-              })),
-              compatibility: taskPlan.compatibility.map((entry) => ({
-                ...entry,
-                requiredCapabilities: [...entry.requiredCapabilities],
-              })),
-              rejectedMechanisms: taskPlan.rejectedMechanisms.map((entry) => ({
-                ...entry,
-              })),
-            },
-            instruction:
-              'Implement one representative first when required, verify it, then complete coverage and gather every derived verification result after the final mutation.',
-          }),
+          stdout: JSON.stringify({ plan: taskPlanSnapshot() }),
           stderr: '',
         };
       } else if (name === 'framer_verify_interactions') {
-        if (mutationCalls === 0) {
-          throw toolError(
-            'FRAMER_HARNESS_INTERACTION_MUTATION_REQUIRED',
-            'Verify interactions only after the relevant Framer mutation has succeeded.',
-          );
-        }
         if (!taskPlan?.behaviors?.length) {
           throw toolError(
             'FRAMER_BEHAVIOR_CONTRACT_REQUIRED',
-            'Declare observable behaviors and compatible mechanisms with framer_plan_task before interaction verification.',
-          );
-        }
-        const checks = normalizeBehaviorEvidence(
-          rawArguments.checks,
-          taskPlan,
-        );
-        const exhaustedBehaviorIds = uniqueStrings(
-          checks
-            .map((check) => check.behaviorId)
-            .filter((behaviorId) =>
-              behaviorVerificationAttempts.get(behaviorId)?.exhausted),
-        );
-        if (exhaustedBehaviorIds.length > 0) {
-          throw toolError(
-            'FRAMER_INTERACTION_VERIFICATION_BUDGET_EXHAUSTED',
-            `Interaction verification is exhausted for ${exhaustedBehaviorIds.join(', ')}. Stop retrying unchanged evidence and report the work as partially verified.`,
+            'Declare the behaviors to confirm in framer_plan_task before verifying them.',
           );
         }
+        const checks = normalizeBehaviorEvidence(rawArguments.checks, taskPlan);
         const pagePath = normalizePagePath(rawArguments.pagePath);
-        const requestedIds = evidenceNodeIds(checks);
-        const componentIds = uniqueStrings(
-          checks.map((check) => check.componentNodeId),
-        );
         const liveResult = await execCode(
           [
-            `const requestedIds = ${JSON.stringify(requestedIds)};`,
-            `const componentIds = ${JSON.stringify(componentIds)};`,
-            'const [nodes, componentControls] = await Promise.all([',
-            '  Promise.all(requestedIds.map(async (id) => ({',
-            '    id,',
-            '    node: await framer.agent.serialize({ id, depth: 8 },',
-            `      { pagePath: ${JSON.stringify(pagePath)} }).catch(() => null),`,
-            '    parentId: await framer.agent.getParentNode({ id },',
-            `      { pagePath: ${JSON.stringify(pagePath)} }).then((node) => node?.id ?? null).catch(() => null),`,
-            '    ancestorIds: await framer.agent.getAncestors({ id },',
-            `      { pagePath: ${JSON.stringify(pagePath)} }).then((nodes) => Array.isArray(nodes) ? nodes.map((node) => node?.id).filter(Boolean) : []).catch(() => []),`,
-            '  }))),',
-            '  componentIds.length > 0',
-            '    ? framer.agent.readComponentControls({ componentIds },',
-            `        { pagePath: ${JSON.stringify(pagePath)} }).catch(() => null)`,
-            '    : null,',
-            ']);',
-            'console.log(JSON.stringify({ nodes, componentControls }, null, 2));',
+            `const requestedIds = ${JSON.stringify(evidenceNodeIds(checks))};`,
+            'const nodes = await Promise.all(requestedIds.map(async (id) => ({',
+            '  id,',
+            '  node: await framer.agent.serialize({ id, depth: 1 },',
+            `    { pagePath: ${JSON.stringify(pagePath)} }).catch(() => null),`,
+            '})));',
+            'console.log(JSON.stringify({ nodes }, null, 2));',
           ].join('\n'),
         );
         const parsed = parseStructuredOutput(liveResult.stdout);
-        const nodesById = new Map(
+        const nodes = new Map(
           (Array.isArray(parsed?.nodes) ? parsed.nodes : [])
-            .filter((entry) => isRecord(entry) && typeof entry.id === 'string')
-            .map((entry) => [entry.id, {
-              node: entry.node || null,
-              parentId:
-                typeof entry.parentId === 'string'
-                  ? entry.parentId
-                  : null,
-              ancestorIds: Array.isArray(entry.ancestorIds)
-                ? entry.ancestorIds
-                : [],
-            }]),
+            .filter((entry) => isRecord(entry) && typeof entry.id === 'string' && entry.node)
+            .map((entry) => [entry.id, entry.node]),
         );
-        const verified = verifyBehaviorEvidence({
-          plan: taskPlan,
-          checks,
-          snapshots: nodesById,
-          context: {
-            lowLevelWriteCalls,
-            authorizedInstanceContainerIds,
-            componentControls: parsed?.componentControls || null,
-            semanticVerifierMode,
-          },
-        });
+        const results = verifyBehaviorChecks({ checks, nodes });
         markInspection();
         interactionVerificationCalls += 1;
-        representativeRepairNodeIds.clear();
-        representativeRepairBehaviorByNode.clear();
-        representativeEvidenceBehaviorByNode.clear();
-        const checkedBehaviorIds = new Set(
-          checks.map((check) => check.behaviorId),
-        );
-        for (const behaviorResult of verified.behaviors) {
-          if (!checkedBehaviorIds.has(behaviorResult.behaviorId)) continue;
-          const behaviorChecks = verified.checks.filter((check) =>
-            check.behaviorId === behaviorResult.behaviorId);
-          for (const check of behaviorChecks) {
-            evidenceNodeIds([check]).forEach((nodeId) =>
-              representativeEvidenceBehaviorByNode.set(
-                nodeId,
-                behaviorResult.behaviorId,
-              ));
-          }
-          const deterministicallyContradicted = behaviorChecks.some((check) =>
-            check.deterministicVerdict === 'contradicted');
-          const prior = behaviorVerificationAttempts.get(
-            behaviorResult.behaviorId,
-          ) || {
-            attempts: 0,
-            unchangedEvidenceCount: 0,
-            repairs: 0,
-            fingerprint: null,
-            exhausted: false,
-          };
-          if (behaviorResult.verdict === 'verified') {
-            behaviorVerificationAttempts.delete(behaviorResult.behaviorId);
-            Object.assign(behaviorResult, {
-              verificationAttempts: prior.attempts + 1,
-              verificationAttemptsRemaining: Math.max(
-                0,
-                MAX_INTERACTION_VERIFICATION_ATTEMPTS_PER_BEHAVIOR
-                  - prior.attempts
-                  - 1,
-              ),
-              repairAttempts: prior.repairs,
-              budgetExhausted: false,
-            });
-            continue;
-          }
-          const evidenceFingerprint = crypto
-            .createHash('sha256')
-            .update(JSON.stringify({
-              mechanism: behaviorResult.mechanism,
-              verdict: behaviorResult.verdict,
-              contradictions: [...behaviorResult.contradictions].sort(),
-              unknowns: [...behaviorResult.unknowns].sort(),
-              checks: behaviorChecks.map((check) => ({
-                verdict: check.verdict,
-                nodeIds: evidenceNodeIds([check]).sort(),
-                observations: check.observations,
-              })),
-            }))
-            .digest('hex');
-          const attempts = prior.attempts + 1;
-          const unchangedEvidenceCount =
-            prior.fingerprint === evidenceFingerprint
-              ? prior.unchangedEvidenceCount + 1
-              : 1;
-          const exhausted =
-            attempts >= MAX_INTERACTION_VERIFICATION_ATTEMPTS_PER_BEHAVIOR
-            || unchangedEvidenceCount >= 2
-            || (
-              behaviorResult.verdict === 'contradicted'
-              && prior.repairs >= MAX_INTERACTION_REPAIRS_PER_BEHAVIOR
-            );
-          behaviorVerificationAttempts.set(behaviorResult.behaviorId, {
-            attempts,
-            unchangedEvidenceCount,
-            repairs: prior.repairs,
-            fingerprint: evidenceFingerprint,
-            exhausted,
-          });
-          Object.assign(behaviorResult, {
-            verificationAttempts: attempts,
-            verificationAttemptsRemaining: Math.max(
-              0,
-              MAX_INTERACTION_VERIFICATION_ATTEMPTS_PER_BEHAVIOR - attempts,
-            ),
-            repairAttempts: prior.repairs,
-            budgetExhausted: exhausted,
-          });
-          for (const check of behaviorChecks) {
-            check.repairAllowed =
-              check.deterministicVerdict === 'contradicted'
-              && prior.repairs < MAX_INTERACTION_REPAIRS_PER_BEHAVIOR
-              && !exhausted;
-            if (!check.repairAllowed) continue;
-            evidenceNodeIds([check]).forEach((nodeId) => {
-              representativeRepairNodeIds.add(nodeId);
-              representativeRepairBehaviorByNode.set(
-                nodeId,
-                behaviorResult.behaviorId,
-              );
-            });
-          }
-          if (
-            !deterministicallyContradicted
-            || !exhausted
-            || !behaviorResult.mechanism
-          ) continue;
-          const alreadyRejected = taskPlan.rejectedMechanisms.some((rejected) =>
-            rejected.mechanism === behaviorResult.mechanism
-            && (
-              rejected.behaviorId === behaviorResult.behaviorId
-              || rejected.behaviorSignature
-                === behaviorResult.behaviorSignature
-            ));
-          if (alreadyRejected) continue;
-          taskPlan = {
-            ...taskPlan,
-            rejectedMechanisms: [
-              ...taskPlan.rejectedMechanisms,
-              {
-                behaviorId: behaviorResult.behaviorId,
-                behaviorSignature: behaviorResult.behaviorSignature,
-                mechanism: behaviorResult.mechanism,
-                reason:
-                  `Repeated live evidence contradicted this mechanism: ${behaviorChecks
-                    .flatMap((check) => check.contradictions)
-                    .join('; ')
-                    .slice(0, 700)}`,
-                source: 'verification_failure',
-              },
-            ],
-          };
-        }
-        const budgetExhaustedBehaviorIds = [...behaviorVerificationAttempts]
-          .filter(([, attempt]) => attempt.exhausted)
-          .map(([behaviorId]) => behaviorId);
-        interactionVerification = {
-          ...verified,
-          semanticVerifierMode,
-          budgetExhaustedBehaviorIds,
-          verifiedAt: new Date().toISOString(),
-        };
-        verified.representativeBehaviorIds.forEach((behaviorId) =>
-          representativeVerifiedBehaviorIds.add(behaviorId));
-        if (interactionVerification.completed) {
-          verificationEvidence.set('interactions', operationSequence);
-        } else {
-          verificationEvidence.delete('interactions');
+        interactionVerifiedAt = new Date().toISOString();
+        for (const checkResult of results) {
+          interactionCheckResults.set(
+            `${checkResult.behaviorId}\n${checkResult.nodeId}\n${checkResult.property}`,
+            { sequence: operationSequence, result: checkResult },
+          );
         }
+        const summary = interactionSummary();
         result = {
-          stdout: JSON.stringify(interactionVerification),
+          stdout: JSON.stringify({
+            status: summary.status,
+            checks: results,
+            behaviors: summary.behaviors,
+          }),
           stderr: liveResult.stderr,
         };
       } else if (name === 'framer_read_project') {
@@ -2860,6 +2475,88 @@ export function createFramerAgentToolRuntime({
         imageSearchCalls += 1;
       } else if (name === 'framer_upload_attachment') {
         result = await uploadAttachment(String(rawArguments.attachmentId || ''));
+      } else if (name === 'framer_add_svg') {
+        const svg = normalizeSvgMarkup(rawArguments.svg);
+        const parentId = String(rawArguments.parentId || '').trim();
+        if (!parentId) {
+          throw toolError(
+            'FRAMER_SVG_PARENT_REQUIRED',
+            'framer_add_svg needs the id of the parent node.',
+          );
+        }
+        const index = Number.isInteger(rawArguments.index) && rawArguments.index >= 0
+          ? rawArguments.index
+          : null;
+        const svgName = String(rawArguments.name || '').trim().slice(0, 120) || 'SVG';
+        const attributes = normalizeSvgAttributes(rawArguments.attributes);
+        requireTaskPlanForMutation();
+        // addSVG has no parent option and replaces a selected SVG, so clear
+        // the selection, find the one new SVG node, then move it into place.
+        result = await execCode(
+          [
+            `const svg = ${JSON.stringify(svg)};`,
+            `const parentId = ${JSON.stringify(parentId)};`,
+            `const index = ${JSON.stringify(index)};`,
+            `const attributes = ${JSON.stringify({ name: svgName, position: 'relative', ...attributes })};`,
+            'const fail = (code, message) => console.log(JSON.stringify({ ok: false, error: { code, message } }));',
+            'const parent = await framer.getNode(parentId);',
+            'if (!parent) {',
+            '  fail("FRAMER_SVG_PARENT_NOT_FOUND", `No node exists with id "${parentId}".`);',
+            '} else {',
+            '  const previousIds = new Set((await framer.getNodesWithType("SVGNode")).map((node) => node.id));',
+            '  try { await framer.setSelection([]); } catch {}',
+            '  await framer.addSVG({ svg, name: attributes.name });',
+            '  let node = null;',
+            '  for (let attempt = 0; attempt < 6 && !node; attempt += 1) {',
+            '    if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, 150));',
+            '    const inserted = (await framer.getNodesWithType("SVGNode")).filter((candidate) => !previousIds.has(candidate.id));',
+            '    if (inserted.length === 1) node = inserted[0];',
+            '  }',
+            '  if (!node) {',
+            '    fail("FRAMER_SVG_NOT_INSERTED", "Framer did not expose exactly one new SVG node after inserting the markup.");',
+            '  } else {',
+            '    try {',
+            '      await framer.setParent(node.id, parentId, index ?? undefined);',
+            '      await node.setAttributes(attributes);',
+            '      const placedParent = await node.getParent();',
+            '      if (placedParent?.id !== parentId) throw new Error("The SVG did not land inside the requested parent.");',
+            '      const placed = await framer.getNode(node.id);',
+            '      console.log(JSON.stringify({',
+            '        ok: true,',
+            '        node: {',
+            '          id: node.id,',
+            '          name: placed?.name ?? attributes.name,',
+            '          parentId,',
+            '          position: placed?.position ?? null,',
+            '          width: placed?.width ?? null,',
+            '          height: placed?.height ?? null,',
+            '        },',
+            '      }));',
+            '    } catch (error) {',
+            '      await framer.removeNodes([node.id]).catch(() => undefined);',
+            '      fail("FRAMER_SVG_PLACEMENT_FAILED", String(error?.message || error));',
+            '    }',
+            '  }',
+            '}',
+          ].join('\n'),
+        );
+        const parsed = parseStructuredOutput(result.stdout);
+        if (!isRecord(parsed) || parsed.ok !== true) {
+          throw structuredResultError(
+            parsed,
+            'FRAMER_SVG_PLACEMENT_FAILED',
+            'Dexter could not place the SVG in the Framer project.',
+          );
+        }
+        mutationCalls += 1;
+        markMutation();
+        mutationReceipts.push({
+          sequence: operationSequence,
+          kind: 'framer_add_svg',
+          nodeId: parsed.node?.id ?? null,
+          parentId,
+          svgHash: crypto.createHash('sha256').update(svg).digest('hex'),
+        });
       } else if (name === 'framer_read_code_file') {
         const filePath = normalizeCodeFilePath(rawArguments.path);
         result = await execCode(
@@ -2913,7 +2610,7 @@ export function createFramerAgentToolRuntime({
         );
         const parsed = parseStructuredOutput(result.stdout);
         if (!isRecord(parsed) || parsed.ok !== true) {
-          throw codeFileResultError(
+          throw structuredResultError(
             parsed,
             'FRAMER_CODE_FILE_READ_FAILED',
             `Dexter could not read ${filePath}.`,
@@ -3072,14 +2769,14 @@ export function createFramerAgentToolRuntime({
         );
         const parsed = parseStructuredOutput(result.stdout);
         if (!isRecord(parsed) || parsed.ok !== true) {
-          throw codeFileResultError(
+          throw structuredResultError(
             parsed,
             'FRAMER_CODE_FILE_UPDATE_FAILED',
             `Dexter could not update ${filePath}.`,
           );
         }
         mutationCalls += 1;
-        markMutation();
+        markMutation({ code: true });
         const mutationSequence = operationSequence;
         markInspection({
           verifies: parsed.typecheck?.passed === true ? ['code'] : [],
@@ -3116,8 +2813,7 @@ export function createFramerAgentToolRuntime({
             'Framer Agent changes are required.',
           );
         }
-        const mutatedRepresentativeBehaviorIds =
-          requireTaskPlanForMutation({ changes });
+        requireTaskPlanForMutation();
         const pagePath = normalizePagePath(rawArguments.pagePath);
         result = await execCode(
           [
@@ -3128,8 +2824,6 @@ export function createFramerAgentToolRuntime({
         mutationCalls += 1;
         applyChangesCalls += 1;
         markMutation();
-        mutatedRepresentativeBehaviorIds.forEach((behaviorId) =>
-          representativeMutatedBehaviorIds.add(behaviorId));
         const parsedResult = parseStructuredOutput(result.stdout);
         mutationReceipts.push({
           sequence: operationSequence,
@@ -3192,9 +2886,7 @@ export function createFramerAgentToolRuntime({
         name,
         phase: 'completed',
         message:
-          name === 'framer_apply_changes'
-          || name === 'framer_update_code_file'
-          || name === 'framer_write'
+          mutation
             ? 'Updated the Framer project'
             : 'Finished inspecting the Framer project',
         durationMs,
@@ -3203,6 +2895,9 @@ export function createFramerAgentToolRuntime({
         name === 'framer_read_code_file'
           ? normalizedCodeFileReadResult(result)
           : normalizedResult(result);
+      // Result size is what this call adds to every later model turn.
+      toolCall.resultBytes = Buffer.byteLength(JSON.stringify(normalized), 'utf8');
+      if (modelImages.length > 0) toolCall.imageCount = modelImages.length;
       if (name !== 'framer_read_project') return normalized;
       const screenshotCount = screenshotQueries(rawArguments).length;
       return {
@@ -3271,7 +2966,7 @@ export function createFramerAgentToolRuntime({
         name,
         phase: 'failed',
         message:
-          name === 'framer_apply_changes' || name === 'framer_write'
+          mutation
             ? 'The Framer project update failed'
             : 'The Framer project inspection failed',
         durationMs: Date.now() - startedAt,
@@ -3353,12 +3048,14 @@ export function createFramerAgentToolRuntime({
     inspect: inspectFinalState,
     finalizeCompletion,
     verificationRepairPrompt,
+    unblockedFailurePrompt,
     sourceHash: () => null,
     hasPendingChanges: () => false,
     directWorkspace: true,
     summary: () => ({
       projectId,
       projectUrl,
+      unresolvedTargets: unresolvedTargets.map((target) => ({ ...target })),
       mutationCalls,
       applyChangesCalls,
       lowLevelWriteCalls,
@@ -3412,10 +3109,6 @@ export function createFramerAgentToolRuntime({
         lowLevelWriteDisabled,
         lowLevelWriteBlockedCalls,
         instructionFallbacks,
-        interactionVerificationAttemptLimit:
-          MAX_INTERACTION_VERIFICATION_ATTEMPTS_PER_BEHAVIOR,
-        interactionRepairLimit:
-          MAX_INTERACTION_REPAIRS_PER_BEHAVIOR,
       },
       branch: branchChange,
       lastInspectionAt,
@@ -3442,6 +3135,7 @@ export function createFramerAgentToolRuntime({
         projectContextHash: guidanceMetadata.projectContextHash,
         files: [...guidanceMetadata.files],
         bytes: guidanceMetadata.bytes,
+        guidesRead: [...guidesRead],
       },
       doctrine: { ...promptMetadata },
     }),