framer-dalton 0.0.29 → 0.0.31

package/dist/cli.js

@@ -12,7 +12,7 @@ import net from 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.29 */
+/* @framer/ai CLI v0.0.31 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
@@ -375,7 +375,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.29" 
+  "0.0.31" 
 );
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
@@ -1070,6 +1070,114 @@ var types = {
       }
     ]
   },
+  agentbranch: {
+    name: "AgentBranch",
+    description: "",
+    kind: "interface",
+    references: [],
+    members: [
+      {
+        name: "id",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "title",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "url",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "baseId",
+        type: "string",
+        description: "",
+        optional: true
+      },
+      {
+        name: "joined",
+        type: "boolean",
+        description: "",
+        optional: false
+      }
+    ]
+  },
+  agentbranchchange: {
+    name: "AgentBranchChange",
+    description: "",
+    kind: "interface",
+    references: ["AgentBranchCollectionItemChange"],
+    members: [
+      {
+        name: "type",
+        type: '"page" | "collection" | "designPage" | "siteSettings" | "component" | "layoutTemplate"',
+        description: "",
+        optional: false
+      },
+      {
+        name: "nodeId",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "name",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "isRemoved",
+        type: "boolean",
+        description: "",
+        optional: false
+      },
+      {
+        name: "items",
+        type: "AgentBranchCollectionItemChange[]",
+        description: "",
+        optional: true
+      },
+      {
+        name: "settingsTab",
+        type: '"general" | "redirects"',
+        description: "",
+        optional: true
+      }
+    ]
+  },
+  agentbranchcollectionitemchange: {
+    name: "AgentBranchCollectionItemChange",
+    description: "",
+    kind: "interface",
+    references: [],
+    members: [
+      {
+        name: "nodeId",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "name",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "isRemoved",
+        type: "boolean",
+        description: "",
+        optional: false
+      }
+    ]
+  },
   agentclarificationanswer: {
     name: "AgentClarificationAnswer",
     description: "",
@@ -4374,6 +4482,20 @@ var types = {
     alias: "PixelNumber | `${PixelNumber} ${PixelNumber} ${PixelNumber} ${PixelNumber}`",
     references: ["PixelNumber"]
   },
+  framerreconnectoptions: {
+    name: "FramerReconnectOptions",
+    description: "",
+    kind: "interface",
+    references: [],
+    members: [
+      {
+        name: "expectedInitialBranchId",
+        type: "string",
+        description: "",
+        optional: true
+      }
+    ]
+  },
   fusednumber: {
     name: "FusedNumber",
     description: "",
@@ -7338,6 +7460,66 @@ var types = {
         description: "@alpha",
         optional: false
       },
+      {
+        name: "getActiveBranchForAgent",
+        type: "() => Promise<AgentBranch>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "getBranchesForAgent",
+        type: "() => Promise<AgentBranch[]>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "getBranchChangesForAgent",
+        type: "(branchId: string) => Promise<AgentBranchChange[]>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "switchBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "createBranchForAgent",
+        type: "(title?: string) => Promise<AgentBranch>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "mergeBranchForAgent",
+        type: "(targetBranchId?: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "joinBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "leaveBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "renameBranchForAgent",
+        type: "(branchId: string, title: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "deleteBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
       {
         name: "readProjectForAgent",
         type: "(queries: Record<string, unknown>[], options?: {\n        pagePath?: string;\n    }) => Promise<{\n        results: unknown[];\n    }>",
@@ -7941,9 +8123,9 @@ var types = {
         optional: false
       },
       {
-        name: "userAgentModel",
+        name: "framerAgentModel",
         type: "string",
-        description: "Inner Framer Agent model override. Defaults to `model` when omitted. Supports the same `model=effort` syntax.",
+        description: "Inner Framer Agent model override. Defaults to `model` when omitted.\n\nSupports the same `model=effort` syntax. Omitting effort is equivalent to `none`.",
         optional: true
       },
       {
@@ -7996,6 +8178,18 @@ var types = {
         description: "JSONL string with one training row per inner-agent step, present when `captureTrainingData` was set.",
         optional: true
       },
+      {
+        name: "traceFilename",
+        type: "string",
+        description: "Replay trace filename, present when the inner agent produced at least one model step.",
+        optional: true
+      },
+      {
+        name: "traceJson",
+        type: "string",
+        description: "Replay trace JSON with system, tools, and final ModelMessage conversation.",
+        optional: true
+      },
       {
         name: "fixtureFilename",
         type: "string",
@@ -13933,6 +14127,20 @@ var methodsByCategory = {
       description: 'Applies commands to the canvas to create, update, remove, move, or duplicate nodes.\n\nThe command syntax is documented in the string returned by {@link getSystemPrompt}.\nEach call is scoped to a single page.\n\n@param dsl - A string of commands separated by `;`. See {@link getSystemPrompt} for syntax.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.',
       references: []
     },
+    {
+      name: "createBranch",
+      category: "FramerAgentAPI",
+      signature: "createBranch(title?: string): Promise<AgentBranch>",
+      description: "Creates a branch and switches to it.\n\n@param title - Optional branch title. The new branch is created from the active branch.\n@returns The created branch.",
+      references: ["AgentBranch"]
+    },
+    {
+      name: "deleteBranch",
+      category: "FramerAgentAPI",
+      signature: "deleteBranch(branchId: string): Promise<void>",
+      description: "Deletes a branch.\n\n@param branchId - Branch id to delete.",
+      references: []
+    },
     {
       name: "flattenComponentInstance",
       category: "FramerAgentAPI",
@@ -13940,6 +14148,13 @@ var methodsByCategory = {
       description: 'Flattens a local component instance into raw editable layers.\n\n@param input - `{ id }`: the id of the component instance to flatten.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The flatten result \u2014 `success` with a `replacementId`, or `blocked` with a reason.',
       references: []
     },
+    {
+      name: "getActiveBranch",
+      category: "FramerAgentAPI",
+      signature: "getActiveBranch(): Promise<AgentBranch>",
+      description: "Returns the active project branch.\n\n@returns Branch metadata for the active branch.",
+      references: ["AgentBranch"]
+    },
     {
       name: "getAncestors",
       category: "FramerAgentAPI",
@@ -13947,11 +14162,25 @@ var methodsByCategory = {
       description: 'Get every ancestor of a node, from the direct parent up to the page root.\n\n@param input - `{ id }`: the id of the node to start from.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The ancestors ordered from closest parent to the page root.',
       references: []
     },
+    {
+      name: "getBranchChanges",
+      category: "FramerAgentAPI",
+      signature: "getBranchChanges(branchId: string): Promise<AgentBranchChange[]>",
+      description: "Returns a summarized changelog for a branch.\n\n@param branchId - Branch id.",
+      references: ["AgentBranchChange"]
+    },
+    {
+      name: "getBranches",
+      category: "FramerAgentAPI",
+      signature: "getBranches(): Promise<AgentBranch[]>",
+      description: "Returns the project branches.\n\n@returns Branch metadata for each available branch.",
+      references: ["AgentBranch"]
+    },
     {
       name: "getContext",
       category: "FramerAgentAPI",
-      signature: "getContext(options?: { pagePath?: string; }): Promise<string>",
-      description: 'Returns the dynamic project context as a string.\n\nThe context includes project-specific data:\n- **Available fonts** \u2014 font families loaded in the project.\n- **Components** \u2014 component names and their controls.\n- **Design tokens** \u2014 color tokens defined in the project.\n- **Style presets** \u2014 text style presets defined in the project.\n- **Icon sets** \u2014 available icon sets and their definitions.\n\nThis data changes per project and page. Pair with the static prompt\nfrom {@link getSystemPrompt} for complete agent context.\n\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns A string containing the project context.',
+      signature: "getContext(): Promise<string>",
+      description: "Returns the dynamic project context as a string.\n\nThe context includes project-specific data:\n- **Available fonts** \u2014 font families loaded in the project.\n- **Components** \u2014 component names and their controls.\n- **Design tokens** \u2014 color tokens defined in the project.\n- **Style presets** \u2014 text style presets defined in the project.\n- **Icon sets** \u2014 available icon sets and their definitions.\n\nThis data changes per project. Pair with the static prompt\nfrom {@link getSystemPrompt} for complete agent context.\n\n@returns A string containing the project context.",
       references: []
     },
     {
@@ -14003,6 +14232,20 @@ var methodsByCategory = {
       description: "Returns the static agent system prompt as a string.\n\nThe prompt includes:\n- **Command reference** \u2014 syntax for adding, updating, removing, moving, and duplicating nodes.\n- **Design rules** \u2014 spacing, layout, typography, and responsive design guidance.\n- **Examples** \u2014 common UI patterns expressed as commands.\n- **`readProject` query reference** \u2014 available query types and their parameters.\n\nThis is the sole documentation for the command syntax used by {@link applyChanges}\nand the query types used by {@link readProject}.\n\nThe prompt is static and does not depend on any specific project.\nCall {@link getContext} to get the project-specific context.\n\n@returns A string containing the agent system prompt.",
       references: []
     },
+    {
+      name: "joinBranch",
+      category: "FramerAgentAPI",
+      signature: "joinBranch(branchId: string): Promise<void>",
+      description: "Joins a branch as a contributor so the current user can edit it when permissions allow.\n\n@param branchId - Branch id to join.",
+      references: []
+    },
+    {
+      name: "leaveBranch",
+      category: "FramerAgentAPI",
+      signature: "leaveBranch(branchId: string): Promise<void>",
+      description: "Leaves a branch as a contributor.\n\n@param branchId - Branch id to leave.",
+      references: []
+    },
     {
       name: "makeExternalComponentLocal",
       category: "FramerAgentAPI",
@@ -14010,6 +14253,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: "mergeBranch",
+      category: "FramerAgentAPI",
+      signature: "mergeBranch(targetBranchId?: string): Promise<void>",
+      description: 'Merges the active branch into its base or a target branch and switches to the target.\n\n@param targetBranchId - Optional target branch id. Use `"main"` for the main branch.',
+      references: []
+    },
     {
       name: "paginate",
       category: "FramerAgentAPI",
@@ -14034,29 +14284,29 @@ var methodsByCategory = {
     {
       name: "readComponentControls",
       category: "FramerAgentAPI",
-      signature: "readComponentControls(input: { componentIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads control definitions for project components.\n\n@param input - `{ componentIds }`: component ids from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching component control definitions.',
+      signature: "readComponentControls(input: { componentIds: readonly string[]; }): Promise<unknown>",
+      description: "Reads control definitions for project components.\n\n@param input - `{ componentIds }`: component ids from project context or previous reads.\n@returns The matching component control definitions.",
       references: []
     },
     {
       name: "readIcons",
       category: "FramerAgentAPI",
-      signature: "readIcons(input: { iconSetName: string; }, options?: { pagePath?: string; }): Promise<string[]>",
-      description: 'Reads exact icon names for an icon set.\n\n@param input - `{ iconSetName }`: icon set name from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The available icon names in that set.',
+      signature: "readIcons(input: { iconSetName: string; }): Promise<string[]>",
+      description: "Reads exact icon names for an icon set.\n\n@param input - `{ iconSetName }`: icon set name from project context or previous reads.\n@returns The available icon names in that set.",
       references: []
     },
     {
       name: "readIconSetControls",
       category: "FramerAgentAPI",
-      signature: "readIconSetControls(input: { iconSetNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads icon-set control definitions.\n\n@param input - `{ iconSetNames }`: icon set names from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching icon-set control definitions.',
+      signature: "readIconSetControls(input: { iconSetNames: readonly string[]; }): Promise<unknown>",
+      description: "Reads icon-set control definitions.\n\n@param input - `{ iconSetNames }`: icon set names from project context or previous reads.\n@returns The matching icon-set control definitions.",
       references: []
     },
     {
       name: "readLayoutTemplateControls",
       category: "FramerAgentAPI",
-      signature: "readLayoutTemplateControls(input: { layoutTemplateIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads layout-template control definitions.\n\n@param input - `{ layoutTemplateIds }`: layout template ids from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching layout-template control definitions.',
+      signature: "readLayoutTemplateControls(input: { layoutTemplateIds: readonly string[]; }): Promise<unknown>",
+      description: "Reads layout-template control definitions.\n\n@param input - `{ layoutTemplateIds }`: layout template ids from project context or previous reads.\n@returns The matching layout-template control definitions.",
       references: []
     },
     {
@@ -14069,15 +14319,22 @@ var methodsByCategory = {
     {
       name: "readShaderControls",
       category: "FramerAgentAPI",
-      signature: "readShaderControls(input: { shaderNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads shader control definitions.\n\n@param input - `{ shaderNames }`: shader names from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching shader control definitions.',
+      signature: "readShaderControls(input: { shaderNames: readonly string[]; }): Promise<unknown>",
+      description: "Reads shader control definitions.\n\n@param input - `{ shaderNames }`: shader names from project context or previous reads.\n@returns The matching shader control definitions.",
+      references: []
+    },
+    {
+      name: "renameBranch",
+      category: "FramerAgentAPI",
+      signature: "renameBranch(branchId: string, title: string): Promise<void>",
+      description: "Renames a branch.\n\n@param branchId - Branch id to rename.\n@param title - New branch title.",
       references: []
     },
     {
       name: "reviewChanges",
       category: "FramerAgentAPI",
-      signature: "reviewChanges(options?: { pagePath?: string; }): Promise<unknown>",
-      description: "Reviews changes made by prior {@link applyChanges} 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.",
+      signature: "reviewChanges(): Promise<unknown>",
+      description: "Reviews changes made by prior {@link applyChanges} calls in this session.\n\nConsumes accumulated diagnostics from the session's agent context.\n\n@returns The session's accumulated changes, errors, warnings, and deferred trait reports.",
       references: []
     },
     {
@@ -14093,6 +14350,13 @@ var methodsByCategory = {
       signature: "serializeNodes(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: "switchBranch",
+      category: "FramerAgentAPI",
+      signature: "switchBranch(branchId: string): Promise<void>",
+      description: 'Switches the active project branch.\n\n@param branchId - Branch id. Use `"main"` for the main branch.',
+      references: []
     }
   ],
   framerapierror: [
@@ -16814,6 +17078,10 @@ async function execAndPrint(sessionId, code) {
     for (const line of result.output) {
       print(line);
     }
+    if (result.branchChange) {
+      const { title, id, url } = result.branchChange.activeBranch;
+      print(`[FRAMER_BRANCH_CHANGE] title="${title}" id="${id}" url="${url}"`);
+    }
     if (result.error) {
       printError(
         `Error: ${formatErrorForUser(errorWithRef(result.error, result.errorRef), { fromExecResult: true })}`

package/dist/start-relay-server.js

@@ -14,7 +14,7 @@ import { z } from 'zod';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.29 */
+/* @framer/ai relay server v0.0.31 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -199,7 +199,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.29" 
+  "0.0.31" 
 );
 
 // src/relay-client.ts
@@ -602,6 +602,7 @@ __name(sandboxedImport, "sandboxedImport");
 async function execute(session, code, options = {}) {
   const { cwd } = options;
   const output = [];
+  const previousBranch = await readActiveBranch(session);
   const customConsole = {
     log: /* @__PURE__ */ __name((...args) => {
       output.push(args.map((arg) => formatValue(arg)).join(" "));
@@ -669,7 +670,8 @@ async function execute(session, code, options = {}) {
     if (result !== void 0) {
       output.push(formatValue(result));
     }
-    return { output };
+    const branchChange = await getBranchChange(session, previousBranch);
+    return { output, branchChange };
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
     const retryable = isRetryableError(err);
@@ -677,17 +679,33 @@ async function execute(session, code, options = {}) {
       session.connection.markDisconnected();
     }
     const errorRef = getErrorRef(err);
-    return {
-      output,
-      error: errorMessage,
-      ...errorRef ? { errorRef } : {},
-      ...retryable ? { retryable: true } : {}
-    };
+    const branchChange = await getBranchChange(session, previousBranch);
+    return { output, error: errorMessage, errorRef, retryable, branchChange };
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
   }
 }
 __name(execute, "execute");
+async function readActiveBranch(session) {
+  try {
+    const branch = await session.connection.framer.agent.getActiveBranch();
+    session.connection.setActiveBranchId(branch.id);
+    return branch;
+  } catch {
+    return void 0;
+  }
+}
+__name(readActiveBranch, "readActiveBranch");
+async function getBranchChange(session, previousBranch) {
+  if (!previousBranch) return void 0;
+  const activeBranch = await readActiveBranch(session);
+  if (!activeBranch || previousBranch.id === activeBranch.id) return void 0;
+  return {
+    previousBranch,
+    activeBranch
+  };
+}
+__name(getBranchChange, "getBranchChange");
 function isReconnectable(err) {
   return isRetryableError(err) || isConnectionError(err instanceof Error ? err.message : String(err));
 }
@@ -743,15 +761,19 @@ async function executeWithReconnect(session, code, options, execId) {
     log(
       `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="${err instanceof Error ? err.message : String(err)}"`
     );
-    return connectionFailureResult(
+    const failureResult = connectionFailureResult(
       "Connection lost and failed to reconnect",
       err
     );
+    failureResult.branchChange = result.branchChange;
+    return failureResult;
   }
   log(
     `reconnect.success exec=${execId} session=${session.id} req=${session.connection.framer.requestId}`
   );
-  return execute(session, code, options);
+  const retryResult = await execute(session, code, options);
+  retryResult.branchChange ??= result.branchChange;
+  return retryResult;
 }
 __name(executeWithReconnect, "executeWithReconnect");
 function formatValue(value) {
@@ -1093,6 +1115,7 @@ var Connection = class _Connection {
   sessions = [];
   status = "connected";
   pendingReconnect;
+  activeBranchId;
   static async open(projectId, userId, apiKey, headlessServerUrl) {
     const framer = await connect(projectId, apiKey, {
       clientId: `dalton/${VERSION}`,
@@ -1106,6 +1129,9 @@ var Connection = class _Connection {
   markDisconnected() {
     this.status = "disconnected";
   }
+  setActiveBranchId(branchId) {
+    this.activeBranchId = branchId;
+  }
   getServerSessionId() {
     return this.framer.sessionId ?? MISSING_SERVER_SESSION_ID;
   }
@@ -1149,7 +1175,7 @@ var Connection = class _Connection {
       (session) => session.inflight === 0 && now - session.lastActivityAt >= timeoutMs
     );
   }
-  async reconnect() {
+  async reconnect(expectedInitialBranchId = this.activeBranchId) {
     if (this.status === "connected") {
       return;
     }
@@ -1157,7 +1183,7 @@ var Connection = class _Connection {
       return this.pendingReconnect;
     }
     this.status = "reconnecting";
-    this.pendingReconnect = this.framer.reconnect().then(() => {
+    this.pendingReconnect = this.framer.reconnect({ expectedInitialBranchId }).then(() => {
       this.status = "connected";
       trackConnectionReconnect({
         projectId: this.projectId,

package/docs/skills/framer-project.md

@@ -36,13 +36,12 @@ Always save results you'll need again. Don't repeat API calls.
 
 ## Method Selection
 
-Choose the highest-priority interface available for the task:
+Prefer the agent-specific methods `framer.agent.*` over regular plugin API methods (`framer.*`).
 
-1. Subcommands, such as `npx @framer/agent@latest read-project` and `npx @framer/agent@latest apply-changes`
-2. Agent-specific methods, such as `framer.agent.readProject`, `framer.agent.applyChanges`, and `framer.agent.publish`
-3. Generic plugin API methods, such as top-level `framer.*` methods
+For `framer.agent.readProject` and `framer.agent.applyChanges` calls, use the `npx @framer/agent@latest read-project` and `npx @framer/agent@latest apply-changes` subcommands when possible. It's still ok to call those methods in exec scripts if you require something more complex than a plain method call.
 
-- Use `framer.agent.readProject`, `framer.agent.getNode`, `framer.agent.getNodes`, `framer.agent.getNodesOfTypes`, `framer.agent.getScopeNode`, `framer.agent.getGroundNode`, `framer.agent.getParentNode`, `framer.agent.getAncestors`, `framer.agent.serialize`, `framer.agent.serializeNodes`, and `framer.agent.paginate` for project tree reads.
+- Use `framer.agent.getNode`, `framer.agent.getNodes`, `framer.agent.getNodesOfTypes`, `framer.agent.getScopeNode`, `framer.agent.getGroundNode`, `framer.agent.getParentNode`, `framer.agent.getAncestors`, `framer.agent.serialize`, `framer.agent.serializeNodes`, and `framer.agent.paginate` for project tree reads.
+- Do not use `npx @framer/agent@latest read-project` or `framer.agent.readProject` for node tree reads unless you have just checked current docs and confirmed the exact query type. Query shapes such as `{ type: "node-by-id" }` are not valid for the current local API.
 - Use `framer.agent.readComponentControls`, `framer.agent.readIconSetControls`, `framer.agent.readIcons`, `framer.agent.readLayoutTemplateControls`, and `framer.agent.readShaderControls` for reading the controls of components, icon sets, icons, layout templates, and shaders.
 - Use `framer.agent.applyChanges` for page and layout edits. Do not use low-level node APIs like `createNode`, `setAttributes`, or `setRect` for design/layout work.
 - Use `framer.agent.publish` for publishing. Do not use `publish`, `getDeployments`, or `deploy` for normal agent publishing flows.
@@ -57,6 +56,7 @@ During normal task execution, do not call `framer.agent.getSystemPrompt()` or `f
 
 - Be concise. Don't narrate implementation details like field IDs, escaping, or internal steps. Just do the work and report what was accomplished in user-facing terms.
 - Use `framer.*` for plugin API calls. Top-level methods are not globals.
+- If command output includes `[FRAMER_BRANCH_CHANGE]`, tell the user the active branch changed and include the `url` value.
 - Before making changes that add/update/delete content that the user has not clearly and explicitly requested in this conversation, inform the user of what you plan to do and why, and ask them to confirm.
     - You do not need to ask for confirmation when carrying out a specific add/update/delete change that the user has already clearly requested (this counts as explicit consent).
     - You do not need to explain or ask for confirmation for non-destructive calls like reading project state.
@@ -262,7 +262,7 @@ const commands = rows.flatMap((row, i) => {
   return [`+CollectionItemNode ${itemId} parent="${collectionId}";`, `SET ${itemId} ${sets.join(" ")};`];
 });
 
-await framer.agent.applyChanges(commands.join(" "));
+console.log(await framer.agent.applyChanges(commands.join(" ")));
 ```
 
 #### Writing enum fields
@@ -275,10 +275,10 @@ const collection = (await framer.agent.getNodesOfTypes({ types: ["CollectionNode
 const statusField = collection.variables.find((v) => v.name === "Status");
 const status = statusField.cases.find((name) => name === "New");
 
-await framer.agent.applyChanges(
+console.log(await framer.agent.applyChanges(
   `+CollectionItemNode newPost parent="${collection.id}";
    SET newPost $control__slug="hello-world" ${statusField.key}="${status}";`,
-);
+));
 ```
 
 #### Sync external data
@@ -306,7 +306,7 @@ const commands = source.flatMap((row, i) => {
 });
 existing.filter((item) => !seen.has(item.id)).forEach((item) => commands.push(`DEL ${item.id};`));
 
-await framer.agent.applyChanges(commands.join(" "));
+console.log(await framer.agent.applyChanges(commands.join(" ")));
 ```
 
 #### Field Types
@@ -383,10 +383,10 @@ console.log(state.diagnostics);
 state.component = state.codeFile.exports.find(
   (exportItem) => exportItem.type === "component" && exportItem.isDefaultExport,
 );
-await framer.agent.applyChanges(
+console.log(await framer.agent.applyChanges(
   `+ComponentInstanceNode badge parent="wrapper" component="${state.component.componentId}"; SET badge width=120 height=48;`,
   { pagePath: "/" },
-);
+));
 ```
 
 #### Editing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -24,13 +24,13 @@
     "@trpc/client": "^11.17.0",
     "@trpc/server": "^11.17.0",
     "commander": "^12.1.0",
-    "framer-api": "0.1.14",
+    "framer-api": "^0.1.16",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
     "@framerjs/framer-events": "0.0.185",
-    "@types/node": "24.12.4",
+    "@types/node": "24.13.0",
     "tsup": "^8.0.2",
     "tsx": "^4.22.3",
     "typescript": "^5.9.2",