framer-dalton 0.0.22 → 0.0.24

package/dist/cli.js

@@ -7,10 +7,11 @@ import http from 'http';
 import { spawn, execFile } from 'child_process';
 import { z } from 'zod';
 import os from 'os';
+import { ErrorCode, FramerAPIError } from 'framer-api';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.22 */
+/* @framer/ai CLI v0.0.24 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
@@ -328,7 +329,7 @@ __name(markTelemetryNoticeShown, "markTelemetryNoticeShown");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.22" 
+  "0.0.24" 
 );
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
@@ -418,8 +419,27 @@ function trackError(payload) {
   });
 }
 __name(trackError, "trackError");
-
-// src/utils.ts
+function rehydrateFramerAPIError(error) {
+  if (!(error instanceof Error)) return null;
+  const framerApi = error.data?.framerApi;
+  if (!framerApi || typeof framerApi.code !== "string") return null;
+  const code = ErrorCode[framerApi.code] ?? ErrorCode.INTERNAL;
+  const options = framerApi.ref ? { ref: framerApi.ref } : void 0;
+  return new FramerAPIError(error.message, code, options);
+}
+__name(rehydrateFramerAPIError, "rehydrateFramerAPIError");
+function errorWithRef(message, ref) {
+  const err = new Error(message);
+  if (ref) err.ref = ref;
+  return err;
+}
+__name(errorWithRef, "errorWithRef");
+function getErrorRef(error) {
+  if (!(error instanceof Error)) return void 0;
+  const ref = error.ref;
+  return typeof ref === "string" && ref.length > 0 ? ref : void 0;
+}
+__name(getErrorRef, "getErrorRef");
 function formatError(error) {
   if (error instanceof Error) {
     return error.message;
@@ -427,6 +447,14 @@ function formatError(error) {
   return String(error);
 }
 __name(formatError, "formatError");
+function formatErrorForUser(error) {
+  if (!(error instanceof Error)) return String(error);
+  const rehydrated = rehydrateFramerAPIError(error);
+  if (rehydrated) return rehydrated.toString();
+  const ref = getErrorRef(error);
+  return ref ? `${error.message} [ref: ${ref}]` : error.message;
+}
+__name(formatErrorForUser, "formatErrorForUser");
 function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
@@ -518,7 +546,7 @@ function successHtml(theme, message) {
   return htmlPage({
     title: "Framer \u2014 Agent Approved",
     heading: "Agent Approved",
-    message: message ?? "Your local agent now has edit access to the project. You can close this tab and continue with the local agent.",
+    message: message ?? "Your external agent now has edit access to the project. You can close this tab and continue with the external agent.",
     theme
   });
 }
@@ -767,7 +795,7 @@ async function acquireAuthWithNewProject() {
     expectProjectId: true,
     successMessage: "Project created and agent authorized",
     authType: "new_project",
-    browserSuccessMessage: "A new project has been created and your local agent is authorized to edit it. You can close this tab."
+    browserSuccessMessage: "A new project has been created and your external agent is authorized to edit it. You can close this tab."
   });
 }
 __name(acquireAuthWithNewProject, "acquireAuthWithNewProject");
@@ -784,7 +812,7 @@ async function acquireAuthWithRemixProject(sourceProjectUrlOrId) {
     expectProjectId: true,
     successMessage: "Project remixed and agent authorized",
     authType: "remix",
-    browserSuccessMessage: "The project has been remixed and your local agent is authorized to edit it. You can close this tab.",
+    browserSuccessMessage: "The project has been remixed and your external agent is authorized to edit it. You can close this tab.",
     projectOrigin
   });
 }
@@ -797,6 +825,48 @@ function isAuthError(errorMessage) {
 }
 __name(isAuthError, "isAuthError");
 
+// src/closest-match.ts
+function levenshteinDistance(source, target) {
+  const sourceLength = source.length;
+  const targetLength = target.length;
+  const matrix = Array.from(
+    { length: sourceLength + 1 },
+    () => Array.from({ length: targetLength + 1 }).fill(0)
+  );
+  for (let row = 0; row <= sourceLength; row++) matrix[row][0] = row;
+  for (let col = 0; col <= targetLength; col++) matrix[0][col] = col;
+  for (let row = 1; row <= sourceLength; row++) {
+    for (let col = 1; col <= targetLength; col++) {
+      const cost = source[row - 1] === target[col - 1] ? 0 : 1;
+      matrix[row][col] = Math.min(
+        matrix[row - 1][col] + 1,
+        matrix[row][col - 1] + 1,
+        matrix[row - 1][col - 1] + cost
+      );
+    }
+  }
+  return matrix[sourceLength][targetLength];
+}
+__name(levenshteinDistance, "levenshteinDistance");
+function findClosestMatch(query, candidates) {
+  const queryLower = query.toLowerCase();
+  let bestMatch;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const distance = levenshteinDistance(queryLower, candidate.toLowerCase());
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      bestMatch = candidate;
+    }
+  }
+  const maxDistance = Math.max(2, Math.floor(query.length / 3));
+  if (bestDistance <= maxDistance) {
+    return bestMatch;
+  }
+  return void 0;
+}
+__name(findClosestMatch, "findClosestMatch");
+
 // src/types-data.ts
 var types = {
   addcomponentinstanceoptions: {
@@ -975,7 +1045,7 @@ var types = {
       {
         name: "imageUrls",
         type: "readonly string[]",
-        description: "Attach images to this agent turn by URL.\n\nURLs can be external or existing Framer asset URLs. They will be ingested into the\nproject's assets if needed, then sent to the model as image parts.\n\nTip: if you have a local file (or bytes), upload it first (e.g. `framer.uploadImage(...)`) and\npass the returned asset URL here.",
+        description: "Attach images to this agent turn by URL.\n\nURLs can be external or existing Framer asset URLs. They will be ingested into the\nproject's assets if needed, then made available to the agent as trusted attachment URLs.\n\nTip: if you have a local file (or bytes), upload it first (e.g. `framer.uploadImage(...)`) and\npass the returned asset URL here.",
         optional: true
       }
     ]
@@ -6293,6 +6363,12 @@ var types = {
         description: "@alpha",
         optional: false
       },
+      {
+        name: "unstable_getDependencyVersion",
+        type: 'FramerPluginAPIAlpha["unstable_getDependencyVersion"]',
+        description: "@alpha",
+        optional: false
+      },
       {
         name: "unstable_ensureMinimumDependencyVersion",
         type: 'FramerPluginAPI["unstable_ensureMinimumDependencyVersion"]',
@@ -7205,6 +7281,24 @@ var types = {
         description: "@alpha",
         optional: false
       },
+      {
+        name: "serializeForAgent",
+        type: "(input: {\n        id: string;\n        depth?: number;\n        attributeFilter?: readonly string[];\n        ancestorPath?: boolean;\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "serializeNodesForAgent",
+        type: "(input: {\n        ids: readonly string[];\n        depth?: number;\n        attributeFilter?: readonly string[];\n        ancestorPath?: boolean;\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "paginateForAgent",
+        type: "(input: {\n        items: readonly unknown[];\n        keyName?: never;\n        cursor?: never;\n    } | {\n        keyName: string;\n        cursor: number;\n        items?: never;\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
+        description: "@alpha",
+        optional: false
+      },
       {
         name: "startAgentConversation",
         type: "(prompt: string, options?: StartAgentConversationOptions) => Promise<StartAgentConversationResult>",
@@ -7680,6 +7774,12 @@ var types = {
         type: "number",
         description: "",
         optional: true
+      },
+      {
+        name: "captureTrainingData",
+        type: "boolean",
+        description: "When true, capture per-step (system, tools, messages) \u2192 response training rows for SFT.",
+        optional: true
       }
     ]
   },
@@ -7700,6 +7800,18 @@ var types = {
         type: "string",
         description: "",
         optional: false
+      },
+      {
+        name: "trainingDataFilename",
+        type: "string",
+        description: "Training-data filename, present when `captureTrainingData` was set.",
+        optional: true
+      },
+      {
+        name: "trainingDataJsonl",
+        type: "string",
+        description: "JSONL string with one training row per inner-agent step, present when `captureTrainingData` was set.",
+        optional: true
       }
     ]
   },
@@ -13092,6 +13204,13 @@ var methodsByCategory = {
       description: 'Converts an external component into a local project component.\n\n@param input - `{ id, replaceAll? }`: the id of the external instance, and whether to replace all instances.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns `success` (with the local component name), `needs_confirmation` (retry with `replaceAll`), or `blocked` with a reason.',
       references: []
     },
+    {
+      name: "[$framerApiOnly.paginateForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.paginateForAgent](input: { items: readonly unknown[]; keyName?: never; cursor?: never; } | { keyName: string; cursor: number; items?: never; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: 'Paginate a large array of values across multiple calls. The cursor is\nopaque and only valid within the same headless session and page.\n\n- First page: pass `{ items }`.\n- Continuation: pass `{ keyName, cursor }` using values returned by a previous call.\n\n@param input - `{ items }` for a fresh array, or `{ keyName, cursor }` for continuation.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The current page, including `keyName`, `cursor`, `results`, `totalResults`, and (if more pages remain) `nextCursor`.',
+      references: []
+    },
     {
       name: "[$framerApiOnly.publishForAgent]",
       category: "framer",
@@ -13120,6 +13239,20 @@ var methodsByCategory = {
       description: "Reviews changes made by prior {@link applyAgentChanges} calls in this session.\n\nConsumes accumulated diagnostics from the session's agent context.\n\n@param options.pagePath - Target page path (e.g. `\"/about\"`). Defaults to the active page.\n@returns The session's accumulated changes, errors, warnings, and deferred trait reports.",
       references: []
     },
+    {
+      name: "[$framerApiOnly.serializeForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.serializeForAgent](input: { id: string; depth?: number; attributeFilter?: readonly string[]; ancestorPath?: boolean; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: 'Serialize a single node on the page.\n\n@param input - `{ id }` plus optional serialization options:\n  - `depth` \u2014 limit how many descendant levels to include.\n  - `attributeFilter` \u2014 only return the listed attributes per node.\n  - `ancestorPath` \u2014 also return the path of ancestors up to the page root.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The serialized node, or `null` if no node with that id exists on the page.',
+      references: []
+    },
+    {
+      name: "[$framerApiOnly.serializeNodesForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.serializeNodesForAgent](input: { ids: readonly string[]; depth?: number; attributeFilter?: readonly string[]; ancestorPath?: boolean; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: 'Serialize multiple nodes on the page. Ids that don\'t resolve to a node are skipped.\n\n@param input - `{ ids }` plus optional serialization options:\n  - `depth` \u2014 limit how many descendant levels to include.\n  - `attributeFilter` \u2014 only return the listed attributes per node.\n  - `ancestorPath` \u2014 also return the path of ancestors up to the page root.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The serialized nodes that were found, in input order.',
+      references: []
+    },
     {
       name: "[$framerInternal.initialState]",
       category: "framer",
@@ -13651,6 +13784,13 @@ var methodsByCategory = {
       description: 'Get the current mode.\n\nA plugin can launch in a special mode where only a subset of the API is\nallowed. The mode is set when the plugin launches and never changes while\nthe plugin is active.\n\n@example\n```ts\nif (framer.mode === "image" || framer.mode === "editImage") {\n  // Do image mode specific logic\n  return\n}\n```\n@category settings',
       references: ["Mode"]
     },
+    {
+      name: "paginateForAgent",
+      category: "framer",
+      signature: "paginateForAgent(input: { items: readonly unknown[]; keyName?: never; cursor?: never; } | { keyName: string; cursor: number; items?: never; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: 'Paginate a large array of values across multiple calls. The cursor is\nopaque and only valid within the same headless session and page.\n\n- First page: pass `{ items }`.\n- Continuation: pass `{ keyName, cursor }` using values returned by a previous call.\n\n@param input - `{ items }` for a fresh array, or `{ keyName, cursor }` for continuation.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The current page, including `keyName`, `cursor`, `results`, `totalResults`, and (if more pages remain) `nextCursor`.',
+      references: []
+    },
     {
       name: "publish",
       category: "framer",
@@ -13731,6 +13871,20 @@ var methodsByCategory = {
       description: "",
       references: ["ScreenshotOptions", "ScreenshotResult"]
     },
+    {
+      name: "serializeForAgent",
+      category: "framer",
+      signature: "serializeForAgent(input: { id: string; depth?: number; attributeFilter?: readonly string[]; ancestorPath?: boolean; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: 'Serialize a single node on the page.\n\n@param input - `{ id }` plus optional serialization options:\n  - `depth` \u2014 limit how many descendant levels to include.\n  - `attributeFilter` \u2014 only return the listed attributes per node.\n  - `ancestorPath` \u2014 also return the path of ancestors up to the page root.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The serialized node, or `null` if no node with that id exists on the page.',
+      references: []
+    },
+    {
+      name: "serializeNodesForAgent",
+      category: "framer",
+      signature: "serializeNodesForAgent(input: { ids: readonly string[]; depth?: number; attributeFilter?: readonly string[]; ancestorPath?: boolean; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: 'Serialize multiple nodes on the page. Ids that don\'t resolve to a node are skipped.\n\n@param input - `{ ids }` plus optional serialization options:\n  - `depth` \u2014 limit how many descendant levels to include.\n  - `attributeFilter` \u2014 only return the listed attributes per node.\n  - `ancestorPath` \u2014 also return the path of ancestors up to the page root.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The serialized nodes that were found, in input order.',
+      references: []
+    },
     {
       name: "sessionId",
       category: "framer",
@@ -15830,6 +15984,26 @@ function getType(name2) {
 __name(getType, "getType");
 
 // src/docs.ts
+function getAllKnownNames() {
+  const bareNames = [
+    ...Object.values(classes).map((classInfo) => classInfo.name),
+    ...Object.values(types).map((typeInfo) => typeInfo.name)
+  ];
+  const framerMethods = methodsByCategory.framer ?? [];
+  for (const method of framerMethods) {
+    bareNames.push(method.name);
+  }
+  const methodNames = [];
+  for (const [category, methods] of Object.entries(methodsByCategory)) {
+    const categoryInfo = classes[category];
+    const displayCategory = categoryInfo?.name ?? category;
+    for (const method of methods) {
+      methodNames.push(`${displayCategory}.${method.name}`);
+    }
+  }
+  return { bareNames, methodNames };
+}
+__name(getAllKnownNames, "getAllKnownNames");
 function formatDocComment(text, indent = "") {
   const lines = text.split("\n");
   if (lines.length === 1) {
@@ -15919,8 +16093,11 @@ function renderDocs(queries) {
     if (query.includes(".")) {
       const method = getMethod(query);
       if (!method) {
+        const { methodNames } = getAllKnownNames();
+        const suggestion = findClosestMatch(query, methodNames);
+        const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
         errors.push(
-          `Method '${query}' not found. Use 'framer docs' to list all.`
+          `Method '${query}' not found.${hint} Use 'framer docs' to list all.`
         );
         return { lines, errors };
       }
@@ -15965,7 +16142,12 @@ ${typeDef}`);
 ${typeDef}`);
           }
         } else {
-          errors.push(`'${query}' not found. Use 'framer docs' to list all.`);
+          const { bareNames } = getAllKnownNames();
+          const suggestion = findClosestMatch(query, bareNames);
+          const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
+          errors.push(
+            `'${query}' not found.${hint} Use 'framer docs' to list all.`
+          );
           return { lines, errors };
         }
       }
@@ -16143,6 +16325,16 @@ async function ensureRelayServerRunning(options = {}) {
   throw new Error("Failed to start relay server after 5 seconds");
 }
 __name(ensureRelayServerRunning, "ensureRelayServerRunning");
+
+// src/skill-discovery-wait.ts
+var CLAUDE_CODE_SKILL_DISCOVERY_WAIT_MS = 4e3;
+async function waitForClaudeCodeSkillDiscovery() {
+  if (process.env.CLAUDECODE === void 0) return;
+  await new Promise(
+    (resolve) => setTimeout(resolve, CLAUDE_CODE_SKILL_DISCOVERY_WAIT_MS)
+  );
+}
+__name(waitForClaudeCodeSkillDiscovery, "waitForClaudeCodeSkillDiscovery");
 var FRAMER_TEMPORARY_DIR = path7.join(os.tmpdir(), "framer");
 function ensureTemporaryDir() {
   fs7.mkdirSync(FRAMER_TEMPORARY_DIR, { recursive: true });
@@ -16294,6 +16486,10 @@ program.name(PROGRAM_NAME).version(VERSION).description("Framer Server API CLI")
     setDebugEnabled(true);
   }
 });
+function throwRelayError(result) {
+  throw errorWithRef(result.error ?? "Relay error", result.errorRef);
+}
+__name(throwRelayError, "throwRelayError");
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -16336,9 +16532,7 @@ async function getAgentSystemPrompt(sessionId) {
     cwd: process.cwd()
   });
   debug("exec", "getAgentSystemPrompt: relay responded");
-  if (result.error) {
-    throw new Error(result.error);
-  }
+  if (result.error) throwRelayError(result);
   const prompt = result.output.at(-1);
   if (typeof prompt !== "string") {
     throw new Error("Did not receive agent prompt output.");
@@ -16354,9 +16548,7 @@ async function getAgentContext(sessionId) {
     cwd: process.cwd()
   });
   debug("exec", "getAgentContext: relay responded");
-  if (result.error) {
-    throw new Error(result.error);
-  }
+  if (result.error) throwRelayError(result);
   const context = result.output.at(-1);
   if (typeof context !== "string") {
     throw new Error("Did not receive agent context output.");
@@ -16380,8 +16572,9 @@ async function refreshSkillsFromSession(sessionId, projectId) {
     });
     debug("skills", "skills installed");
   } catch (err) {
-    throw new Error(
-      `Failed to refresh skills for session ${sessionId}: ${formatError(err)}`
+    throw errorWithRef(
+      `Failed to refresh skills for session ${sessionId}: ${formatError(err)}`,
+      getErrorRef(err)
     );
   }
 }
@@ -16407,7 +16600,7 @@ async function resolveSessionCredentials(projectUrlOrId) {
       projectId,
       errorMessage: message
     });
-    printError(`Failed to resolve credentials: ${message}`);
+    printError(`Failed to resolve credentials: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16421,9 +16614,7 @@ async function getProjectName(sessionId) {
     cwd: process.cwd()
   });
   debug("exec", "getProjectName: relay responded");
-  if (result.error) {
-    throw new Error(result.error);
-  }
+  if (result.error) throwRelayError(result);
   const projectName = result.output.at(-1);
   if (typeof projectName !== "string") {
     throw new Error("Did not receive project name output.");
@@ -16445,7 +16636,7 @@ async function ensureRelayForCli(context) {
       userId: context?.userId,
       errorMessage: message
     });
-    printError(`Failed to check relay status: ${message}`);
+    printError(`Failed to check relay status: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16463,12 +16654,14 @@ async function execAndPrint(sessionId, code) {
       print(line);
     }
     if (result.error) {
-      printError(`Error: ${result.error}`);
+      printError(
+        `Error: ${formatErrorForUser(errorWithRef(result.error, result.errorRef))}`
+      );
       await waitForTrackingToFinish();
       process.exit(1);
     }
   } catch (err) {
-    printError(`Execution failed: ${formatError(err)}`);
+    printError(`Execution failed: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16485,7 +16678,7 @@ program.command("exec").description("Execute code in a session").requiredOption(
     try {
       code = fs7.readFileSync(filePath, "utf-8");
     } catch (err) {
-      printError(`Failed to read file: ${formatError(err)}`);
+      printError(`Failed to read file: ${formatErrorForUser(err)}`);
       await waitForTrackingToFinish();
       process.exit(1);
     }
@@ -16574,6 +16767,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         refreshSkillsFromSession(sessionId, projectId)
       ]);
       debug("session.new", `project name="${projectName}", skills refreshed`);
+      await waitForClaudeCodeSkillDiscovery();
       saveProject({
         projectId,
         apiKey: credentials.apiKey,
@@ -16590,7 +16784,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         cleanupStaleSkills(activeProjectIds);
       } catch (error) {
         printWarning(
-          `Failed to clean up stale skills: ${formatError(error)}`
+          `Failed to clean up stale skills: ${formatErrorForUser(error)}`
         );
       }
       const activeSessionIds = activeSessions.map(
@@ -16600,7 +16794,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         cleanupStaleSessionCodeFiles(activeSessionIds);
       } catch (error) {
         printWarning(
-          `Failed to clean up stale session code files: ${formatError(error)}`
+          `Failed to clean up stale session code files: ${formatErrorForUser(error)}`
         );
       }
       debug(
@@ -16619,7 +16813,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         userId,
         errorMessage: message
       });
-      printError(`Failed to create session: ${message}`);
+      printError(`Failed to create session: ${formatErrorForUser(err)}`);
       if (isAuthError(message)) {
         clearApiKey(projectId);
         printError("The stored API key was invalid and has been removed.");
@@ -16653,7 +16847,7 @@ session.command("list").description("List all active sessions").action(async ()
       })
     );
   } catch (err) {
-    printError(`Failed to list sessions: ${formatError(err)}`);
+    printError(`Failed to list sessions: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16693,7 +16887,7 @@ async function saveAuthResult(verb, authFn) {
     saveProject({ projectId, apiKey: result.apiKey, userId: result.userId });
     print(`Project ${projectId} saved`);
   } catch (error) {
-    printError(`Failed to ${verb} project: ${formatError(error)}`);
+    printError(`Failed to ${verb} project: ${formatErrorForUser(error)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16716,7 +16910,7 @@ session.command("destroy <sessionId>").description("Destroy a session").action(a
     await client.destroySession.mutate({ sessionId });
     print(`Session ${sessionId} destroyed`);
   } catch (err) {
-    printError(`Failed to destroy session: ${formatError(err)}`);
+    printError(`Failed to destroy session: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }
@@ -16744,10 +16938,11 @@ program.command("setup").description(
 ).action(async () => {
   try {
     const results = installSkills();
+    await waitForClaudeCodeSkillDiscovery();
     printSetupSummary(results);
     printTelemetryNotice();
   } catch (err) {
-    printError(`Setup failed: ${formatError(err)}`);
+    printError(`Setup failed: ${formatErrorForUser(err)}`);
     await waitForTrackingToFinish();
     process.exit(1);
   }

package/dist/start-relay-server.js

@@ -8,12 +8,12 @@ import crypto, { randomUUID, timingSafeEqual } from 'crypto';
 import http from 'http';
 import { createHTTPHandler } from '@trpc/server/adapters/standalone';
 import { initTRPC, TRPCError } from '@trpc/server';
+import { connect, FramerAPIError } from 'framer-api';
 import { z } from 'zod';
-import { connect } from 'framer-api';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.22 */
+/* @framer/ai relay server v0.0.24 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -159,7 +159,7 @@ __name(debug, "debug");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.22" 
+  "0.0.24" 
 );
 
 // src/relay-client.ts
@@ -391,6 +391,19 @@ var ScopedFS = class {
   }
   constants = fs4.constants;
 };
+function getErrorRef(error) {
+  if (!(error instanceof Error)) return void 0;
+  const ref = error.ref;
+  return typeof ref === "string" && ref.length > 0 ? ref : void 0;
+}
+__name(getErrorRef, "getErrorRef");
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+__name(formatError, "formatError");
 
 // src/execute.ts
 var EXECUTION_TIMEOUT = 10 * 60 * 1e3;
@@ -530,9 +543,11 @@ async function execute(session, code, options = {}) {
     if (isConnectionError(errorMessage)) {
       session.connection.markDisconnected();
     }
+    const errorRef = getErrorRef(err);
     return {
       output,
-      error: errorMessage
+      error: errorMessage,
+      ...errorRef ? { errorRef } : {}
     };
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
@@ -546,10 +561,13 @@ async function executeWithReconnect(session, code, options, execId) {
     );
     try {
       await session.connection.reconnect();
-    } catch {
+    } catch (err) {
+      const inner = err instanceof Error ? err.message : String(err);
+      const errorRef = getErrorRef(err);
       return {
         output: [],
-        error: "Failed to get connection for session"
+        error: `Failed to get connection for session: ${inner}`,
+        ...errorRef ? { errorRef } : {}
       };
     }
   }
@@ -562,13 +580,16 @@ async function executeWithReconnect(session, code, options, execId) {
   );
   try {
     await session.connection.reconnect();
-  } catch {
+  } catch (err) {
+    const inner = err instanceof Error ? err.message : String(err);
+    const errorRef = getErrorRef(err);
     log(
-      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="reconnect failed"`
+      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="${inner}"`
     );
     return {
       output: [],
-      error: "Connection lost and failed to reconnect"
+      error: `Connection lost and failed to reconnect: ${inner}`,
+      ...errorRef ? { errorRef } : {}
     };
   }
   log(
@@ -1156,7 +1177,17 @@ var SessionManager = class {
 var sessionManager = new SessionManager();
 
 // src/router.ts
-var t = initTRPC.create();
+var t = initTRPC.create({
+  errorFormatter({ shape, error }) {
+    const cause = error.cause;
+    if (cause instanceof FramerAPIError) {
+      const framerApi = { code: cause.code };
+      if (cause.ref !== void 0) framerApi.ref = cause.ref;
+      return { ...shape, data: { ...shape.data, framerApi } };
+    }
+    return shape;
+  }
+});
 var nextExecId = 0;
 var appRouter = t.router({
   version: t.procedure.query(() => {
@@ -1192,7 +1223,7 @@ var appRouter = t.router({
       });
       return { id: session.id };
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = formatError(err);
       trackError({
         errorType: "session_create_error",
         projectId: input.projectId,
@@ -1201,7 +1232,8 @@ var appRouter = t.router({
       });
       throw new TRPCError({
         code: isAuthError(message) ? "UNAUTHORIZED" : "INTERNAL_SERVER_ERROR",
-        message
+        message,
+        cause: err
       });
     }
   }),

package/docs/skills/framer-canvas-editing-project.md

@@ -16,7 +16,7 @@ allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)",
 - `read-project` and `apply-changes` are one-liner CLI shortcuts for the high-frequency canvas-editing methods. Use them to read state and apply DSL inline without writing a file first:
     - `npx framer-dalton read-project -s <sessionId> -q <queries> -p <pagePath>` — equivalent to `framer.readProjectForAgent(queries, { pagePath })`. Query types are documented in the embedded prompt below.
     - `npx framer-dalton apply-changes -s <sessionId> -p <pagePath> -e <dsl>` — equivalent to `framer.applyAgentChanges(dsl, { pagePath })`.
-- The embedded prompt below also references other agent-surface methods (`reviewChangesForAgent`, `publishForAgent`, `queryImagesForAgent`, `flattenComponentInstanceForAgent`, `makeExternalComponentLocalForAgent`, and `getNodeForAgent` / `getNodesForAgent` / `getNodesOfTypesForAgent` / `getScopeNodeForAgent` / `getGroundNodeForAgent` / `getParentNodeForAgent` / `getAncestorsForAgent`). These have no dedicated shortcut; invoke via `npx framer-dalton exec -s <sessionId> -e 'console.log(await framer.<method>(<args>))'`.
+- The embedded prompt below also references other agent-surface methods (`reviewChangesForAgent`, `publishForAgent`, `queryImagesForAgent`, `flattenComponentInstanceForAgent`, `makeExternalComponentLocalForAgent`, `getNodeForAgent` / `getNodesForAgent` / `getNodesOfTypesForAgent` / `getScopeNodeForAgent` / `getGroundNodeForAgent` / `getParentNodeForAgent` / `getAncestorsForAgent`, and `serializeForAgent` / `serializeNodesForAgent` / `paginateForAgent`). These have no dedicated shortcut; invoke via `npx framer-dalton exec -s <sessionId> -e 'console.log(await framer.<method>(<args>))'`.
 
 ## Workflow Loop
 

package/docs/skills/framer.md

@@ -198,12 +198,25 @@ Prompting may take a while to complete, so set the command timeout to 10 minutes
 
 ## Execute Code
 
-Use your write tool to write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`:
+Prefer writing code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and executing it with `-f`:
 
 ```bash
 npx framer-dalton exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
 ```
 
+For short snippets, `exec` also accepts `-e <code>` or code piped on stdin.
+
+## Shell Quoting
+
+In Windows PowerShell, if an argument contains nested quotes, use a single-quoted here-string and pass the variable. Do not backslash-escape quotes.
+
+```powershell
+$value = @'
+[{"key":"value","filter":["text","$rect"]}]
+'@
+npx framer-dalton <command> --option $value
+```
+
 ## API Documentation
 
 ```bash
@@ -438,6 +451,5 @@ await collection.setPluginData("lastSync", new Date().toISOString());
 ### Known Limitations
 
 - **Pages**: Cannot change the path of a page
-- **Collection Index/Detail Pages**: Cannot be created as new pages; the user must create them through the UI. Once they exist, they can be modified normally through canvas editing.
 - **Code overrides**: Cannot assign overrides to nodes
 - **Analytics**: No APIs exist for accessing analytics data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -20,14 +20,14 @@
     "generate-types": "tsx scripts/generate-types.ts"
   },
   "dependencies": {
-    "@trpc/client": "^11.9.0",
-    "@trpc/server": "^11.9.0",
+    "@trpc/client": "^11.17.0",
+    "@trpc/server": "^11.17.0",
     "commander": "^12.1.0",
-    "framer-api": "^0.1.8",
+    "framer-api": "0.1.10",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.13",
+    "@biomejs/biome": "^2.4.13",
     "@framerjs/framer-events": "0.0.175",
     "@types/node": "24.10.9",
     "tsup": "^8.0.2",