framer-dalton 0.0.27 → 0.0.29

package/README.md

@@ -7,7 +7,7 @@ CLI and agent skills for interacting with Framer projects via the Framer Server
 Install or refresh the globally available skills:
 
 ```bash
-npx framer-dalton@latest setup
+npx @framer/agent@latest setup
 ```
 
 That installs skills into `~/.agents/skills` and `~/.claude/skills`.
@@ -20,9 +20,9 @@ The CLI and the installed skills are meant to work together. There are three ski
 - `framer-code-components` - explains specific prompts for how to write code components and provides examples.
 - `framer-project-<project id>` - a dynamically-created skill for interacting with a specific project.
 
-1. Running `npx framer-dalton@latest setup` will install the base `framer` and `framer-code-components` skills.
+1. Running `npx @framer/agent@latest setup` will install the base `framer` and `framer-code-components` skills.
 2. The frontmatter of `framer-code-components` tells agents to always load `framer` and the generated project skill first.
-3. The frontmatter of `framer` tells agents to run `npx framer-dalton@latest setup` BEFORE loading the skill. This command will auto-update the cli and update the skill files.
+3. The frontmatter of `framer` tells agents to run `npx @framer/agent@latest setup` BEFORE loading the skill. This command will auto-update the cli and update the skill files.
 4. Creating a new session for a project will create a `framer-project-<project id>` file. This file contains the latest agent system prompt from `framer.agent.getSystemPrompt` and the latest project context from `framer.agent.getContext`. Agents must load this project-specific skill immediately after creating a session before doing any connected-project work.
 
 ## Local Development

package/dist/cli.js

@@ -4,20 +4,20 @@ import path7 from 'path';
 import { Command } from 'commander';
 import crypto, { randomUUID } from 'crypto';
 import http from 'http';
-import { spawn, execFile } from 'child_process';
+import { spawn, execFile, execFileSync } from 'child_process';
 import { z } from 'zod';
-import os from 'os';
+import os2 from 'os';
 import { ErrorCode, FramerAPIError } from 'framer-api';
 import net from 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.27 */
+/* @framer/ai CLI v0.0.29 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // package.json
-var name = "framer-dalton";
+var name = "@framer/agent";
 
 // src/check-node-version.ts
 var MINIMUM_NODE_VERSION = 22;
@@ -100,9 +100,9 @@ function getConfigDir() {
     return path7.join(process.env.XDG_CONFIG_HOME, "framer");
   }
   if (process.platform === "win32") {
-    return path7.join(process.env.APPDATA || os.homedir(), "framer");
+    return path7.join(process.env.APPDATA || os2.homedir(), "framer");
   }
-  return path7.join(os.homedir(), ".config", "framer");
+  return path7.join(os2.homedir(), ".config", "framer");
 }
 __name(getConfigDir, "getConfigDir");
 function ensureConfigDir() {
@@ -375,15 +375,59 @@ __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.27" 
+  "0.0.29" 
 );
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
-function sharedFields() {
+var cachedSharedFields;
+function getOsName(platform) {
+  switch (platform) {
+    case "darwin":
+      return "macos";
+    case "win32":
+      return "windows";
+    case "linux":
+      return "linux";
+    default:
+      return "unknown";
+  }
+}
+__name(getOsName, "getOsName");
+function getMacOsVersion() {
+  try {
+    const version = execFileSync("/usr/bin/sw_vers", ["-productVersion"], {
+      encoding: "utf8",
+      timeout: 1e3
+    }).trim();
+    return version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+__name(getMacOsVersion, "getMacOsVersion");
+function getOsVersion(platform) {
+  if (platform === "darwin") return getMacOsVersion();
+  const version = os2.release().trim();
+  return version || "unknown";
+}
+__name(getOsVersion, "getOsVersion");
+function getOsMetadata() {
+  const platform = os2.platform();
+  const arch = os2.arch();
   return {
+    arch: arch || "unknown",
+    osName: getOsName(platform),
+    osVersion: getOsVersion(platform)
+  };
+}
+__name(getOsMetadata, "getOsMetadata");
+function sharedFields() {
+  cachedSharedFields ??= {
     machineId: getMachineId(),
-    cliVersion: VERSION
+    cliVersion: VERSION,
+    ...getOsMetadata()
   };
+  return cachedSharedFields;
 }
 __name(sharedFields, "sharedFields");
 function wrapEvent(event) {
@@ -396,16 +440,19 @@ function wrapEvent(event) {
   };
 }
 __name(wrapEvent, "wrapEvent");
-function postEvent(event) {
+function postEvent(createEvent) {
   if (!isTelemetryEnabled()) return false;
   if (process.env.NODE_ENV === "test" && true) return false;
+  const event = createEvent();
+  const body = JSON.stringify([wrapEvent(event)]);
+  debug("tracking", `sending ${event.event} to ${trackingEndpoint}: ${body}`);
   const promise = fetch(trackingEndpoint, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "User-Agent": `framer-dalton/${VERSION}`
     },
-    body: JSON.stringify([wrapEvent(event)]),
+    body,
     signal: AbortSignal.timeout(
       5e3
       /* 5 seconds */
@@ -434,35 +481,43 @@ function waitForTrackingToFinish() {
 }
 __name(waitForTrackingToFinish, "waitForTrackingToFinish");
 function trackAuthStart(payload) {
-  postEvent({
-    event: "local_agents_auth_start",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_auth_start",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackAuthStart, "trackAuthStart");
 function trackAuthSuccess(payload) {
-  postEvent({
-    event: "local_agents_auth_success",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_auth_success",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackAuthSuccess, "trackAuthSuccess");
 function trackSkillsInstall(payload) {
-  postEvent({
-    event: "local_agents_skills_install",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_skills_install",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackSkillsInstall, "trackSkillsInstall");
 function trackError(payload) {
-  postEvent({
-    event: "local_agents_error",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_error",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackError, "trackError");
 
@@ -537,7 +592,7 @@ function formatErrorForUser(error, opts) {
   const rehydrated = rehydrateFramerAPIError(error);
   if (rehydrated) return rehydrated.toString();
   if (!opts?.fromExecResult && isRelayConnectionLost(error))
-    return "Connection to the Framer server was lost. Run `framer session new` to reconnect.";
+    return "Connection to the Framer server was lost. Run `npx @framer/agent@latest session new` to reconnect.";
   const ref = getErrorRef(error);
   return ref ? `${error.message} [ref: ${ref}]` : error.message;
 }
@@ -800,7 +855,7 @@ function runBrowserAuthFlow(options) {
       printError(`  1. Open Site Settings \u2192 General: ${settingsUrl}`);
       printError("  2. Scroll to API Keys and create a new key");
       printError(
-        `  3. In another terminal, run: framer project auth ${pollProjectId} <your-api-key>`
+        `  3. In another terminal, run: npx @framer/agent@latest project auth ${pollProjectId} <your-api-key>`
       );
       print("");
       print("Waiting for authorization in browser...");
@@ -814,7 +869,7 @@ function runBrowserAuthFlow(options) {
         });
         reject(
           new Error(
-            pollProjectId ? "Browser authorization timed out. Use `framer project auth <projectUrlOrId> <apiKey>` instead." : "Browser authorization timed out."
+            pollProjectId ? "Browser authorization timed out. Use `npx @framer/agent@latest project auth <projectUrlOrId> <apiKey>` instead." : "Browser authorization timed out."
           )
         );
       });
@@ -16142,7 +16197,7 @@ function renderDocs(queries) {
         const suggestion = findClosestMatch(query, methodNames);
         const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
         errors.push(
-          `Method '${query}' not found.${hint} Use 'framer docs' to list all.`
+          `Method '${query}' not found.${hint} Use 'npx @framer/agent@latest docs' to list all.`
         );
         return { lines, errors };
       }
@@ -16191,7 +16246,7 @@ ${typeDef}`);
           const suggestion = findClosestMatch(query, bareNames);
           const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
           errors.push(
-            `'${query}' not found.${hint} Use 'framer docs' to list all.`
+            `'${query}' not found.${hint} Use 'npx @framer/agent@latest docs' to list all.`
           );
           return { lines, errors };
         }
@@ -16430,7 +16485,7 @@ async function waitForClaudeCodeSkillDiscovery() {
   );
 }
 __name(waitForClaudeCodeSkillDiscovery, "waitForClaudeCodeSkillDiscovery");
-var FRAMER_TEMPORARY_DIR = path7.join(os.tmpdir(), "framer");
+var FRAMER_TEMPORARY_DIR = path7.join(os2.tmpdir(), "framer");
 function ensureTemporaryDir() {
   fs7.mkdirSync(FRAMER_TEMPORARY_DIR, { recursive: true });
 }
@@ -16525,7 +16580,7 @@ function cleanupLegacyCanvasEditingSkills(skillRoots = getDefaultSkillRoots()) {
 }
 __name(cleanupLegacyCanvasEditingSkills, "cleanupLegacyCanvasEditingSkills");
 function getDefaultSkillRoots() {
-  const home = os.homedir();
+  const home = os2.homedir();
   return [
     path7.join(home, ".agents", "skills"),
     path7.join(home, ".claude", "skills")
@@ -16584,7 +16639,7 @@ function installSkills(options = { type: "base" }) {
 __name(installSkills, "installSkills");
 
 // src/cli.ts
-var PROGRAM_NAME = "framer-dalton";
+var PROGRAM_NAME = "@framer/agent";
 var program = new Command();
 program.name(PROGRAM_NAME).version(VERSION).description("Framer Server API CLI").option("--debug", "Enable debug logging").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();

package/dist/start-relay-server.js

@@ -1,7 +1,7 @@
 import fs4 from 'fs';
-import os from 'os';
-import path from 'path';
-import 'child_process';
+import os5 from 'os';
+import path5 from 'path';
+import { execFileSync } from 'child_process';
 import 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
@@ -14,7 +14,7 @@ import { z } from 'zod';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.27 */
+/* @framer/ai relay server v0.0.29 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -60,7 +60,7 @@ var __callDispose = (stack, error, hasError) => {
 };
 
 // package.json
-var name = "framer-dalton";
+var name = "@framer/agent";
 
 // src/check-node-version.ts
 var MINIMUM_NODE_VERSION = 22;
@@ -72,44 +72,83 @@ Please upgrade: https://nodejs.org/`
   );
   process.exit(1);
 }
+var DEFAULT_MAX_LOG_FILE_BYTES = 1024 * 1024;
+var DEFAULT_RETAINED_LOG_FILE_BYTES = 512 * 1024;
+var LOG_TRIM_CHECK_INTERVAL = 10;
+var maxLogFileBytes = DEFAULT_MAX_LOG_FILE_BYTES;
+var retainedLogFileBytes = DEFAULT_RETAINED_LOG_FILE_BYTES;
 function getLogPath() {
   if (process.env.XDG_STATE_HOME) {
-    return path.join(process.env.XDG_STATE_HOME, "framer", "relay.log");
+    return path5.join(process.env.XDG_STATE_HOME, "framer", "relay.log");
   }
   if (process.platform === "win32") {
-    return path.join(
-      process.env.APPDATA || os.homedir(),
+    return path5.join(
+      process.env.APPDATA || os5.homedir(),
       "framer",
       "relay.log"
     );
   }
-  return path.join(os.homedir(), ".local", "state", "framer", "relay.log");
+  return path5.join(os5.homedir(), ".local", "state", "framer", "relay.log");
 }
 __name(getLogPath, "getLogPath");
 var logPath = getLogPath();
 var initialized = false;
+var logEntriesSinceTrimCheck = LOG_TRIM_CHECK_INTERVAL - 1;
 function ensureLogDir() {
   if (initialized) return;
-  const dir = path.dirname(logPath);
+  const dir = path5.dirname(logPath);
   fs4.mkdirSync(dir, { recursive: true });
   initialized = true;
 }
 __name(ensureLogDir, "ensureLogDir");
+function trimLogFileIfNeeded() {
+  logEntriesSinceTrimCheck += 1;
+  if (logEntriesSinceTrimCheck < LOG_TRIM_CHECK_INTERVAL) return;
+  logEntriesSinceTrimCheck = 0;
+  let size;
+  try {
+    size = fs4.statSync(logPath).size;
+  } catch (err) {
+    if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+      return;
+    }
+    throw err;
+  }
+  if (size <= maxLogFileBytes) return;
+  const retainedBytes = Math.min(retainedLogFileBytes, size);
+  const buffer = Buffer.alloc(retainedBytes);
+  const file = fs4.openSync(logPath, "r");
+  let bytesRead = 0;
+  try {
+    bytesRead = fs4.readSync(
+      file,
+      buffer,
+      0,
+      retainedBytes,
+      size - retainedBytes
+    );
+  } finally {
+    fs4.closeSync(file);
+  }
+  fs4.writeFileSync(logPath, buffer.subarray(0, bytesRead));
+}
+__name(trimLogFileIfNeeded, "trimLogFileIfNeeded");
 function log(message) {
   ensureLogDir();
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   fs4.appendFileSync(logPath, `${timestamp} ${message}
 `);
+  trimLogFileIfNeeded();
 }
 __name(log, "log");
 function getConfigDir() {
   if (process.env.XDG_CONFIG_HOME) {
-    return path.join(process.env.XDG_CONFIG_HOME, "framer");
+    return path5.join(process.env.XDG_CONFIG_HOME, "framer");
   }
   if (process.platform === "win32") {
-    return path.join(process.env.APPDATA || os.homedir(), "framer");
+    return path5.join(process.env.APPDATA || os5.homedir(), "framer");
   }
-  return path.join(os.homedir(), ".config", "framer");
+  return path5.join(os5.homedir(), ".config", "framer");
 }
 __name(getConfigDir, "getConfigDir");
 function ensureConfigDir() {
@@ -120,7 +159,7 @@ __name(ensureConfigDir, "ensureConfigDir");
 
 // src/config/relay-token.ts
 function getRelayTokenPath() {
-  return path.join(getConfigDir(), "relay-token");
+  return path5.join(getConfigDir(), "relay-token");
 }
 __name(getRelayTokenPath, "getRelayTokenPath");
 function generateRelayToken() {
@@ -160,12 +199,12 @@ __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.27" 
+  "0.0.29" 
 );
 
 // src/relay-client.ts
 var __filename$1 = fileURLToPath(import.meta.url);
-path.dirname(__filename$1);
+path5.dirname(__filename$1);
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 createTRPCClient({
   links: [
@@ -264,30 +303,74 @@ var ScopedFS = class {
   static {
     __name(this, "ScopedFS");
   }
-  allowedDirs;
+  allowedRoots;
   constructor(allowedDirs) {
-    const defaultDirs = [process.cwd(), "/tmp", os.tmpdir()];
+    const defaultDirs = [process.cwd(), "/tmp", os5.tmpdir()];
     const dirs = allowedDirs ?? defaultDirs;
-    this.allowedDirs = [...new Set(dirs.map((d) => path.resolve(d)))];
+    this.allowedRoots = [
+      ...new Set(dirs.map((dir) => this.canonicalizePath(dir)))
+    ];
   }
-  isPathAllowed(resolved) {
-    return this.allowedDirs.some((dir) => {
-      return resolved === dir || resolved.startsWith(dir + path.sep);
+  isPathAllowed(candidatePath) {
+    return this.allowedRoots.some((allowedRoot) => {
+      return candidatePath === allowedRoot || candidatePath.startsWith(allowedRoot + path5.sep);
     });
   }
   resolvePath(filePath) {
-    const resolved = path.resolve(filePath);
-    if (!this.isPathAllowed(resolved)) {
-      const error = new Error(
-        `EPERM: operation not permitted, access outside allowed directories: ${filePath}`
-      );
-      error.code = "EPERM";
-      error.errno = -1;
-      error.syscall = "access";
-      error.path = filePath;
+    const resolvedPath = path5.resolve(filePath);
+    const canonicalPath = this.canonicalizePath(resolvedPath);
+    if (!this.isPathAllowed(canonicalPath)) {
+      this.throwOutsideAllowedRoots(filePath);
+    }
+    return resolvedPath;
+  }
+  canonicalizePath(inputPath) {
+    const resolvedPath = path5.resolve(inputPath);
+    const missingSegments = [];
+    let ancestorPath = resolvedPath;
+    while (true) {
+      const realPath = this.resolveRealPath(ancestorPath);
+      if (realPath !== null) {
+        return path5.resolve(realPath, ...missingSegments);
+      }
+      if (this.isSymbolicLink(ancestorPath)) {
+        this.throwOutsideAllowedRoots(inputPath);
+      }
+      const parentPath = path5.dirname(ancestorPath);
+      if (parentPath === ancestorPath) {
+        return resolvedPath;
+      }
+      missingSegments.unshift(path5.basename(ancestorPath));
+      ancestorPath = parentPath;
+    }
+  }
+  resolveRealPath(targetPath) {
+    try {
+      return path5.resolve(fs4.realpathSync.native(targetPath));
+    } catch (error) {
+      const errnoError = error;
+      if (errnoError.code === "ENOENT") {
+        return null;
+      }
       throw error;
     }
-    return resolved;
+  }
+  isSymbolicLink(targetPath) {
+    try {
+      return fs4.lstatSync(targetPath).isSymbolicLink();
+    } catch {
+      return false;
+    }
+  }
+  throwOutsideAllowedRoots(filePath) {
+    const error = new Error(
+      `EPERM: operation not permitted, access outside allowed directories: ${filePath}`
+    );
+    error.code = "EPERM";
+    error.errno = -1;
+    error.syscall = "access";
+    error.path = filePath;
+    throw error;
   }
   // Sync methods
   readFileSync = /* @__PURE__ */ __name((filePath, options) => {
@@ -533,7 +616,7 @@ async function execute(session, code, options = {}) {
       output.push(args.map((arg) => formatValue(arg)).join(" "));
     }, "info")
   };
-  const scopedFs = cwd ? new ScopedFS([cwd, "/tmp", os.tmpdir()]) : new ScopedFS();
+  const scopedFs = cwd ? new ScopedFS([cwd, "/tmp", os5.tmpdir()]) : new ScopedFS();
   const sandboxedRequire = createSandboxedRequire(scopedFs);
   const vmContextObj = {
     // Framer API
@@ -737,7 +820,7 @@ var SettingsFileSchema = z.object({
   telemetryNoticeShown: z.boolean().optional()
 });
 function getSettingsPath() {
-  return path.join(getConfigDir(), "settings.json");
+  return path5.join(getConfigDir(), "settings.json");
 }
 __name(getSettingsPath, "getSettingsPath");
 var settings;
@@ -795,11 +878,55 @@ function isTelemetryEnabled() {
 __name(isTelemetryEnabled, "isTelemetryEnabled");
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
-function sharedFields() {
+var cachedSharedFields;
+function getOsName(platform) {
+  switch (platform) {
+    case "darwin":
+      return "macos";
+    case "win32":
+      return "windows";
+    case "linux":
+      return "linux";
+    default:
+      return "unknown";
+  }
+}
+__name(getOsName, "getOsName");
+function getMacOsVersion() {
+  try {
+    const version = execFileSync("/usr/bin/sw_vers", ["-productVersion"], {
+      encoding: "utf8",
+      timeout: 1e3
+    }).trim();
+    return version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+__name(getMacOsVersion, "getMacOsVersion");
+function getOsVersion(platform) {
+  if (platform === "darwin") return getMacOsVersion();
+  const version = os5.release().trim();
+  return version || "unknown";
+}
+__name(getOsVersion, "getOsVersion");
+function getOsMetadata() {
+  const platform = os5.platform();
+  const arch = os5.arch();
   return {
+    arch: arch || "unknown",
+    osName: getOsName(platform),
+    osVersion: getOsVersion(platform)
+  };
+}
+__name(getOsMetadata, "getOsMetadata");
+function sharedFields() {
+  cachedSharedFields ??= {
     machineId: getMachineId(),
-    cliVersion: VERSION
+    cliVersion: VERSION,
+    ...getOsMetadata()
   };
+  return cachedSharedFields;
 }
 __name(sharedFields, "sharedFields");
 function wrapEvent(event) {
@@ -812,16 +939,19 @@ function wrapEvent(event) {
   };
 }
 __name(wrapEvent, "wrapEvent");
-function postEvent(event) {
+function postEvent(createEvent) {
   if (!isTelemetryEnabled()) return false;
   if (process.env.NODE_ENV === "test" && true) return false;
+  const event = createEvent();
+  const body = JSON.stringify([wrapEvent(event)]);
+  debug("tracking", `sending ${event.event} to ${trackingEndpoint}: ${body}`);
   const promise = fetch(trackingEndpoint, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "User-Agent": `framer-dalton/${VERSION}`
     },
-    body: JSON.stringify([wrapEvent(event)]),
+    body,
     signal: AbortSignal.timeout(
       5e3
       /* 5 seconds */
@@ -850,75 +980,93 @@ function waitForTrackingToFinish() {
 }
 __name(waitForTrackingToFinish, "waitForTrackingToFinish");
 function trackRelayStart() {
-  postEvent({
-    event: "local_agents_relay_start",
-    ...sharedFields()
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_relay_start",
+      ...sharedFields()
+    })
+  );
 }
 __name(trackRelayStart, "trackRelayStart");
 var relayShutdownTracked = false;
 function trackRelayShutdown() {
   if (relayShutdownTracked) return;
-  relayShutdownTracked = postEvent({
-    event: "local_agents_relay_shutdown",
-    ...sharedFields()
-  });
+  relayShutdownTracked = postEvent(
+    () => ({
+      event: "local_agents_relay_shutdown",
+      ...sharedFields()
+    })
+  );
 }
 __name(trackRelayShutdown, "trackRelayShutdown");
 function trackSessionCreate(payload) {
-  postEvent({
-    event: "local_agents_session_create",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_session_create",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackSessionCreate, "trackSessionCreate");
 function trackSessionDestroy(payload) {
-  postEvent({
-    event: "local_agents_session_destroy",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_session_destroy",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackSessionDestroy, "trackSessionDestroy");
 function trackExec(payload) {
-  postEvent({
-    event: "local_agents_exec",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_exec",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackExec, "trackExec");
 function trackConnectionAcquire(payload) {
-  postEvent({
-    event: "local_agents_connection_acquire",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_connection_acquire",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackConnectionAcquire, "trackConnectionAcquire");
 function trackConnectionReconnect(payload) {
-  postEvent({
-    event: "local_agents_connection_reconnect",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_connection_reconnect",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackConnectionReconnect, "trackConnectionReconnect");
 function trackConnectionIdleDisconnect(payload) {
-  postEvent({
-    event: "local_agents_connection_idle_disconnect",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_connection_idle_disconnect",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackConnectionIdleDisconnect, "trackConnectionIdleDisconnect");
 function trackError(payload) {
-  postEvent({
-    event: "local_agents_error",
-    ...sharedFields(),
-    ...payload
-  });
+  postEvent(
+    () => ({
+      event: "local_agents_error",
+      ...sharedFields(),
+      ...payload
+    })
+  );
 }
 __name(trackError, "trackError");
 

package/docs/skills/framer-project.md

@@ -1,7 +1,7 @@
 ---
 name: {{SKILL_NAME}}
 description: "Project-scoped Framer skill for project {{PROJECT_ID}}. Covers project reads, edits, change review, publishing, image sourcing, component operations, and canvas editing. Very important: never load this skill without having already read the `framer` skill and without having already run `session new`, which will dynamically update this skill."
-allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+allowed-tools: ["Bash(npx @framer/agent:*)", "Bash(npx @framer/agent@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 ## Project Scope
@@ -15,11 +15,11 @@ Every connected-project task follows these steps:
 
 ### 1. Look up the API (before EVERY new use of an API method)
 
-**You MUST run `npx framer-dalton docs` before writing any code.** Do not guess method names or signatures.
+**You MUST run `npx @framer/agent@latest docs` before writing any code.** Do not guess method names or signatures.
 
 ```bash
-npx framer-dalton docs Collection           # What methods exist?
-npx framer-dalton docs Collection.getItems  # What are the parameters and return type?
+npx @framer/agent@latest docs Collection           # What methods exist?
+npx @framer/agent@latest docs Collection.getItems  # What are the parameters and return type?
 ```
 
 ### 2. Execute code
@@ -27,7 +27,7 @@ npx framer-dalton docs Collection.getItems  # What are the parameters and return
 Only after checking docs, use your write tool to write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/`, then execute it with `-f`. Do not create code files with shell heredocs or `cat`. Name each file `<sessionId>-<short-summary>.js` where `<short-summary>` is a brief kebab-case description (e.g., `1-read-collections.js`, `1-add-team-member.js`).
 
 ```bash
-npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
+npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
 ```
 
 ### 3. Store results in `state`
@@ -38,7 +38,7 @@ Always save results you'll need again. Don't repeat API calls.
 
 Choose the highest-priority interface available for the task:
 
-1. Subcommands, such as `framer-dalton read-project` and `framer-dalton apply-changes`
+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
 
@@ -46,6 +46,8 @@ Choose the highest-priority interface available for the task:
 - 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.
+- Prefer `framer.agent.applyChanges` and project tree read methods for CMS work where possible. Fall back to the collection APIs only for functionality otherwise not supported. Note that if you add collections or fields via collection APIs, some things may not work as expected when then using those collections or fields on the canvas via `framer.agent.applyChanges`.
+- Create styles, design tokens, components, and variables via `framer.agent.applyChanges`. Using plugin API methods can cause issues when trying to use newly created values later in `framer.agent.applyChanges` calls.
 
 Use generic plugin API methods only for capabilities that do not have a subcommand or agent-specific counterpart, such as code file management, localization, and redirects.
 
@@ -85,7 +87,7 @@ state.collections = await framer.getCollections();
 ```
 
 ```bash
-npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
+npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
 ```
 
 ```js
@@ -95,7 +97,7 @@ console.log(state.teamItems.length);
 ```
 
 ```bash
-npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
+npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
 ```
 
 Store anything you'll reference again.
@@ -139,7 +141,7 @@ Prompting may take a while to complete, so set the command timeout to 10 minutes
 Prefer using your write tool to write code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and executing it with `-f`. Do not create code files with shell heredocs or `cat`:
 
 ```bash
-npx framer-dalton exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
+npx @framer/agent@latest exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
 ```
 
 For short snippets, `exec` also accepts `-e <code>` or code piped on stdin.
@@ -152,130 +154,164 @@ In Windows PowerShell, if an argument contains nested quotes, use a single-quote
 $value = @'
 [{"key":"value","filter":["text","$rect"]}]
 '@
-npx framer-dalton <command> --option $value
+npx @framer/agent@latest <command> --option $value
 ```
 
 ## API Documentation
 
 ```bash
-npx framer-dalton docs                            # List all available methods
-npx framer-dalton docs framer.getCollections      # Show top level method
-npx framer-dalton docs Collection                 # Show class with all method signatures
-npx framer-dalton docs Collection.addItems        # Show method + recursively expand all referenced types
-npx framer-dalton docs ScreenshotOptions          # Show type + recursively expand all referenced types
+npx @framer/agent@latest docs                            # List all available methods
+npx @framer/agent@latest docs framer.getCollections      # Show top level method
+npx @framer/agent@latest docs Collection                 # Show class with all method signatures
+npx @framer/agent@latest docs Collection.addItems        # Show method + recursively expand all referenced types
+npx @framer/agent@latest docs ScreenshotOptions          # Show type + recursively expand all referenced types
 ```
 
 `docs` with no arguments lists available methods. Looking up a class shows its full definition without expanding referenced types. Looking up a specific method or type automatically expands all referenced types recursively.
 
 ## API Examples
 
-**STOP: These are patterns only. Before using any method below, run `npx framer-dalton docs <ClassName>` to verify the current signature.**
+**STOP: These are patterns only. Before using any method below, run `npx @framer/agent@latest docs <ClassName>` to verify the current signature.**
 
 ### Working with Collections (CMS)
 
-Collections are Framer's CMS. Each collection has fields (columns) and items (rows). Use the plugin Collection API (the methods below) for collection schema and item CRUD.
+Collections and items are nodes: read them with the agent read methods, create and edit them with `framer.agent.applyChanges`. A collection's fields are its `variables`; an item's cells are `$control__<fieldId>` attributes.
 
-**Exception — CMS Collection Lists.** The in-canvas construct that *renders* a collection as a repeating list of cards (the "Collection List" / repeater) is an agent/page concern. Build and edit those through `framer.agent.readProject` and `framer.agent.applyChanges`, not the plugin API. Use the plugin Collection API to read available collections and field schema first, then use `framer.agent.applyChanges` to add the list.
-
-#### Reading Collections
+#### List collections and fields
 
 ```js
-// Get all collections
-const collections = await framer.getCollections();
-console.log(collections.map((c) => ({ name: c.name, id: c.id })));
-
-// Get a specific collection by ID
-const collection = await framer.getCollection("collection-id");
-
-// Get fields (columns)
-const fields = await collection.getFields();
-// Note that a plain console.log will miss getter-backed properties
-console.log(fields.map((f) => ({ id: f.id, name: f.name, type: f.type })));
-// [{ id: "BnNuS2i3o", name: "Title", type: "string" }, ...]
-
-// Get items (rows)
-const items = await collection.getItems();
-console.log(items);
-// [{ id: "XTM8FSHGs", slug: "post-1", draft: false, fieldData: {...} }, ...]
+const collections = await framer.agent.getNodesOfTypes({ types: ["CollectionNode"] });
+console.log(collections.map((c) => ({
+  id: c.id,
+  name: c.name,
+  itemCount: c.$itemCount,
+  fields: c.variables.map((v) => ({ id: v.id, name: v.name, type: v.type })),
+})));
 ```
 
-#### Sync external data to collection
+#### Read items
+
+If you know the collection id, serialize the collection with `depth: 1` to read its direct item children.
 
 ```js
-const collection = await framer.getCollection("collection-id");
-const existing = await collection.getItems();
-const existingIds = new Set(existing.map((i) => i.id));
+const collectionId = "collection-id";
+const collection = await framer.agent.serialize({ id: collectionId, depth: 1 });
+const items = collection.children ?? [];
+console.log({
+  itemCount: collection.$itemCount,
+  items: items.map((item) => ({ id: item.id, ...item.attributes })),
+});
+```
 
-const externalData = await fetch("https://api.example.com/posts").then((r) =>
-  r.json(),
-);
+For huge collections, paginate the serialized children and process one page per call. Store the page in `state` only when you need to continue in a later exec call. Stop when the logged `nextCursor` is missing.
 
-const items = externalData.map((post) => ({
-  id: post.id,
-  slug: post.slug,
-  fieldData: { title: post.title, content: post.body },
-}));
+First page:
 
-await collection.addItems(items);
+```js
+const collectionId = "collection-id";
+const collection = await framer.agent.serialize({ id: collectionId, depth: 1 });
+state.page = await framer.agent.paginate({ items: collection.children ?? [] });
+console.log({
+  totalResults: state.page.totalResults,
+  nextCursor: state.page.nextCursor,
+  items: state.page.results.map((item) => ({ id: item.id, ...item.attributes })),
+});
+```
 
-// Remove items no longer in external source
-const newIds = new Set(items.map((i) => i.id));
-const toRemove = [...existingIds].filter((id) => !newIds.has(id));
-if (toRemove.length) await collection.removeItems(toRemove);
+Next page, if nextCursor is set:
 
-await collection.setPluginData("lastSync", new Date().toISOString());
+```js
+state.page = await framer.agent.paginate({
+  keyName: state.page.keyName,
+  cursor: state.page.nextCursor,
+});
+console.log({
+  totalResults: state.page.totalResults,
+  nextCursor: state.page.nextCursor,
+  items: state.page.results.map((item) => ({ id: item.id, ...item.attributes })),
+});
 ```
 
-#### Field Types
+To search across all collections, read item nodes directly and filter by `$parentId`:
 
-`boolean`, `color`, `number`, `string`, `formattedText` (HTML), `image`, `file`, `link`, `date`, `enum`, `collectionReference`, `multiCollectionReference`, `array` (galleries)
+```js
+const collectionId = "collection-id";
+const items = await framer.agent.getNodesOfTypes({ types: ["CollectionItemNode"] });
+const collectionItems = items
+  .filter((item) => item.$parentId === collectionId)
+  .map((item) => ({ id: item.id, ...item.attributes }));
+console.log(collectionItems);
+```
 
-#### Updating Collection Items
+#### Create and edit items
 
-```js
-// Add or update items (if id matches existing item, it updates)
-await collection.addItems([
-  {
-    id: "new-item-1",
-    slug: "hello-world",
-    fieldData: { titleFieldId: "Hello World" },
-  },
-]);
+`+CollectionItemNode` adds a row; `SET … $control__<fieldId>` sets cells (a `SET` on an existing item id updates it; `DEL <itemId>` removes it).
 
-// Remove items
-await collection.removeItems(["item-id-1", "item-id-2"]);
+```js
+const { readFileSync } = require("fs");
+
+const collectionId = "collection-id";
+const columnToFieldId = { title: "title-field-id", body: "body-field-id" };
+const rows = JSON.parse(readFileSync("/abs/path/to/import.json", "utf8"));
+
+const commands = rows.flatMap((row, i) => {
+  const itemId = `item-${i}`;
+  const sets = Object.entries(columnToFieldId)
+    .filter(([col]) => row[col] != null)
+    .map(([col, fieldId]) => `$control__${fieldId}="${String(row[col]).replace(/"/g, '\\"')}"`);
+  return [`+CollectionItemNode ${itemId} parent="${collectionId}";`, `SET ${itemId} ${sets.join(" ")};`];
+});
 
-// Reorder items
-const ids = items.map((i) => i.id).reverse();
-await collection.setItemOrder(ids);
+await framer.agent.applyChanges(commands.join(" "));
 ```
 
 #### Writing enum fields
 
-Enum fields are **write-by-case-id, read-by-name**: a write must pass the case's `id`, but `getItems()` reads the value back as the case name. Writing `{ type: "enum", value: "New" }` (the name) is rejected — look up the id from the field definition first:
+With agent methods, enum fields are read and written by case name. Look up the field on the collection's `variables`, verify the case exists, then set the field's `$control__...` key:
 
 ```js
-const caseId = field.cases.find((c) => c.name === "New").id;
-await collection.addItems([
-  { slug: "hello-world", fieldData: { [field.id]: { type: "enum", value: caseId } } },
-]);
+const collection = (await framer.agent.getNodesOfTypes({ types: ["CollectionNode"] }))
+  .find((c) => c.name === "Posts");
+const statusField = collection.variables.find((v) => v.name === "Status");
+const status = statusField.cases.find((name) => name === "New");
+
+await framer.agent.applyChanges(
+  `+CollectionItemNode newPost parent="${collection.id}";
+   SET newPost $control__slug="hello-world" ${statusField.key}="${status}";`,
+);
 ```
 
-#### Working with CollectionItem
+#### Sync external data
+
+Upsert by a stable key (e.g. slug): `SET` existing rows, add new ones, `DEL` rows no longer in the source.
 
 ```js
-const items = await collection.getItems();
-const item = items[0];
+const collectionId = "collection-id";
+const fieldBySource = { title: "title-field-id", body: "body-field-id" };
+const source = await fetch("https://api.example.com/posts").then((r) => r.json());
+
+const existing = (await framer.agent.getNodesOfTypes({ types: ["CollectionItemNode"] }))
+  .filter((item) => item.$parentId === collectionId);
+const idBySlug = new Map(existing.map((item) => [item.attributes.$control__slug, item.id]));
+
+const seen = new Set();
+const commands = source.flatMap((row, i) => {
+  const itemId = idBySlug.get(row.slug) ?? `new-${i}`;
+  seen.add(itemId);
+  const sets = Object.entries(fieldBySource)
+    .filter(([k]) => row[k] != null)
+    .map(([k, fieldId]) => `$control__${fieldId}="${String(row[k]).replace(/"/g, '\\"')}"`);
+  const add = idBySlug.has(row.slug) ? [] : [`+CollectionItemNode ${itemId} parent="${collectionId}";`];
+  return [...add, `SET ${itemId} ${sets.join(" ")};`];
+});
+existing.filter((item) => !seen.has(item.id)).forEach((item) => commands.push(`DEL ${item.id};`));
 
-// Update item attributes
-await item.setAttributes({ slug: "new-slug" });
+await framer.agent.applyChanges(commands.join(" "));
+```
 
-// Navigate to item in Framer UI
-await item.navigateTo();
+#### Field Types
 
-// Remove item
-await item.remove();
-```
+`boolean`, `color`, `number`, `string`, `formattedText` (HTML), `image`, `file`, `link`, `date`, `enum`, `collectionReference`, `multiCollectionReference`, `array` (galleries)
 
 ### Working with Images
 

package/docs/skills/framer.md

@@ -2,13 +2,13 @@
 name: framer
 description: >
   Use when the user wants to design, edit, or publish a website or web page — creating layouts, editing sections, updating text or images, managing CMS collections and content, syncing external data, creating or modifying code components, managing color and text styles, handling localization, or publishing deployments. Trigger when the user mentions Framer, references their website or web pages, asks to edit designs, update site content, or work with any Framer project — even if they don't explicitly say 'Framer'.
-  **Mandatory precondition**: run `npx framer-dalton@latest setup` and let it complete **BEFORE** loading this skill.
-allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+  **Mandatory precondition**: run `npx @framer/agent@latest setup` and let it complete **BEFORE** loading this skill.
+allowed-tools: ["Bash(npx @framer/agent:*)", "Bash(npx @framer/agent@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 If you didn't run this command before loading the skill, run it now:
 ```bash
-npx framer-dalton@latest setup
+npx @framer/agent@latest setup
 ```
 
 ## Capabilities
@@ -29,14 +29,14 @@ What you can do with the Framer CLI:
 
 ### Permissions
 
-The Framer CLI requires network access (to download packages and connect to Framer servers) and file-system access outside the project directory (to install skills into `~/.agents/skills/` and `~/.claude/skills/`). In sandboxed environments, you must execute `npx framer-dalton` commands with elevated permissions from the get-go. Do not try to execute them with the default sandboxed permissions; they will hang or fail.
+The Framer CLI requires network access (to download packages and connect to Framer servers) and file-system access outside the project directory (to install skills into `~/.agents/skills/` and `~/.claude/skills/`). In sandboxed environments, you must execute `npx @framer/agent@latest` commands with elevated permissions from the get-go. Do not try to execute them with the default sandboxed permissions; they will hang or fail.
 
 ### Session Management
 
 If the user refers to a project by name or description rather than giving a URL, first inspect the recent projects:
 
 ```bash
-npx framer-dalton project list
+npx @framer/agent@latest project list
 ```
 
 Use that list to infer the likely project from the names and recency. If the right project is already known, use its project ID with `session new`. If there are multiple possible matches, clarify with the user. Only ask the user for a Project URL if there is no clear match. Avoid talking about the technical contents of returned data like IDs.
@@ -46,7 +46,7 @@ Each session maintains a persistent connection to a Framer project. Use sessions
 Create a session against an existing project:
 
 ```bash
-npx framer-dalton session new "<url or id>"
+npx @framer/agent@latest session new "<url or id>"
 ```
 
 This prints the session ID. You must always use that session ID with `-s <id>` for all subsequent commands. Using the same session preserves your `state` between calls.
@@ -54,15 +54,15 @@ This prints the session ID. You must always use that session ID with `-s <id>` f
 To create a brand new empty project and connect to it:
 
 ```bash
-npx framer-dalton project new
-npx framer-dalton session new "<returned project id>"
+npx @framer/agent@latest project new
+npx @framer/agent@latest session new "<returned project id>"
 ```
 
 To remix (duplicate) an existing project and connect to the copy:
 
 ```bash
-npx framer-dalton project remix "<url, project id, or remix link>"
-npx framer-dalton session new "<returned project id>"
+npx @framer/agent@latest project remix "<url, project id, or remix link>"
+npx @framer/agent@latest session new "<returned project id>"
 ```
 
 Note that during beta, you cannot connect to non-beta projects. If creating a session errors with a message about this, you need to move your project to beta.
@@ -70,7 +70,7 @@ Note that during beta, you cannot connect to non-beta projects. If creating a se
 List active sessions:
 
 ```bash
-npx framer-dalton session list
+npx @framer/agent@latest session list
 ```
 
 ## Project-scoped skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
-    "@framerjs/framer-events": "0.0.183",
+    "@framerjs/framer-events": "0.0.185",
     "@types/node": "24.12.4",
     "tsup": "^8.0.2",
     "tsx": "^4.22.3",