framer-dalton 0.0.13 → 0.0.15

package/dist/cli.js

@@ -10,7 +10,7 @@ import { z } from 'zod';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.13 */
+/* @framer/ai CLI v0.0.15 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function openUrl(url) {
@@ -180,6 +180,19 @@ function clearApiKey(projectId) {
 }
 __name(clearApiKey, "clearApiKey");
 
+// src/debug.ts
+var enabled = false;
+function setDebugEnabled(value) {
+  enabled = value;
+}
+__name(setDebugEnabled, "setDebugEnabled");
+function debug(tag, message) {
+  if (!enabled) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  console.error(`[debug ${timestamp}] ${tag}: ${message}`);
+}
+__name(debug, "debug");
+
 // src/utils.ts
 function formatError(error) {
   if (error instanceof Error) {
@@ -323,6 +336,7 @@ async function acquireKeyFromBrowser(projectId) {
     __name(settle, "settle");
     const server = http.createServer((req, res) => {
       const url = new URL(req.url ?? "/", `http://127.0.0.1`);
+      debug("auth", `request: ${url.pathname}`);
       if (url.pathname === "/done") {
         const theme2 = parseTheme(url.searchParams.get("theme"));
         res.writeHead(200, { "Content-Type": "text/html" });
@@ -331,6 +345,7 @@ async function acquireKeyFromBrowser(projectId) {
             const apiKey2 = pendingApiKey;
             pendingApiKey = null;
             settle(() => {
+              debug("auth", "received API key via /done, resolving");
               print("\u2713 Agent authorized");
               resolve(apiKey2);
             });
@@ -367,6 +382,7 @@ async function acquireKeyFromBrowser(projectId) {
         res.end();
         return;
       }
+      debug("auth", "received valid callback, redirecting to /done");
       pendingApiKey = apiKey;
       res.writeHead(302, { Location: `/done?theme=${theme}` });
       res.end();
@@ -376,6 +392,7 @@ async function acquireKeyFromBrowser(projectId) {
       const apiKey = getApiKey(projectId);
       if (apiKey) {
         settle(() => {
+          debug("auth", "API key detected from config file poll");
           print("\u2713 API key detected from config");
           resolve(apiKey);
         });
@@ -407,6 +424,7 @@ async function acquireKeyFromBrowser(projectId) {
     function cleanup() {
       if (cleaned) return;
       cleaned = true;
+      debug("auth", "cleanup: clearing timers and closing server");
       clearTimeout(timer);
       clearTimeout(hintTimer);
       clearInterval(pollTimer);
@@ -416,20 +434,24 @@ async function acquireKeyFromBrowser(projectId) {
     __name(cleanup, "cleanup");
     server.keepAliveTimeout = 0;
     server.unref();
+    debug("auth", "starting callback server...");
     server.listen(0, "127.0.0.1", () => {
       const addr = server.address();
       if (!addr || typeof addr === "string") {
         settle(() => reject(new Error("Failed to start callback server.")));
         return;
       }
+      debug("auth", `callback server listening on port ${addr.port}`);
       const callbackUrl = `http://127.0.0.1:${addr.port}/callback`;
       const deeplink = new URL("https://framer.com/projects/server-api/auth");
       deeplink.searchParams.set("callback", callbackUrl);
       deeplink.searchParams.set("state", state);
       deeplink.searchParams.set("projectId", projectId);
       const deeplinkStr = deeplink.toString();
+      debug("auth", "opening browser for deeplink...");
       openUrl(deeplinkStr).then((opened) => {
         if (opened) {
+          debug("auth", "browser opened successfully");
           print("Waiting for authorization in browser...");
         } else {
           printError("Could not open browser. Open this URL manually:");
@@ -6629,6 +6651,18 @@ var types = {
         description: "",
         optional: false
       },
+      {
+        name: "[getCurrentUserMessageType]",
+        type: "() => Promise<User>",
+        description: "",
+        optional: false
+      },
+      {
+        name: "[getProjectInfoMessageType]",
+        type: "() => Promise<ProjectInfo>",
+        description: "",
+        optional: false
+      },
       {
         name: "[getHTMLForNodeMessageType]",
         type: "(nodeId: NodeId) => Promise<string | null>",
@@ -14944,9 +14978,16 @@ ${typeDef}`);
   return { lines, errors };
 }
 __name(renderDocs, "renderDocs");
+
+// src/version.ts
+var VERSION = (
+  // typeof is used to ensure this can be used just via tsx or node etc. without build
+  "0.0.15" 
+);
+
+// src/relay-client.ts
 var __filename$1 = fileURLToPath(import.meta.url);
 var __dirname$1 = path4.dirname(__filename$1);
-var VERSION = "0.0.13" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 var client = createTRPCClient({
   links: [
@@ -14984,11 +15025,15 @@ function compareVersions(v1, v2) {
 __name(compareVersions, "compareVersions");
 async function ensureRelayServerRunning(options = {}) {
   const { logger, restartOnVersionMismatch = true } = options;
+  debug("relay", `checking server version (client=${VERSION})...`);
   const serverVersion = await getRelayServerVersion();
+  debug("relay", `server version=${serverVersion ?? "not running"}`);
   if (serverVersion === VERSION) {
+    debug("relay", "version matches, no action needed");
     return;
   }
   if (serverVersion !== null && compareVersions(serverVersion, VERSION) > 0) {
+    debug("relay", "server version is newer, keeping it");
     return;
   }
   if (serverVersion !== null) {
@@ -14996,11 +15041,13 @@ async function ensureRelayServerRunning(options = {}) {
       logger?.log(
         `Relay server version mismatch (server: ${serverVersion}, client: ${VERSION}), restarting...`
       );
+      debug("relay", "shutting down old server...");
       try {
         await client.shutdown.mutate();
         await sleep(500);
       } catch {
       }
+      debug("relay", "old server shut down");
     } else {
       return;
     }
@@ -15009,6 +15056,7 @@ async function ensureRelayServerRunning(options = {}) {
   }
   const isRunningFromSource = __filename$1.endsWith(".ts");
   const scriptPath = isRunningFromSource ? path4.resolve(__dirname$1, "./start-relay-server.ts") : path4.resolve(__dirname$1, "./start-relay-server.js");
+  debug("relay", `spawning server process: ${scriptPath}`);
   const serverProcess = spawn(
     isRunningFromSource ? "tsx" : process.execPath,
     [scriptPath],
@@ -15019,9 +15067,13 @@ async function ensureRelayServerRunning(options = {}) {
     }
   );
   serverProcess.unref();
-  for (let i = 0; i < 10; i++) {
+  for (let attempt = 0; attempt < 10; attempt++) {
     await sleep(500);
     const newVersion = await getRelayServerVersion();
+    debug(
+      "relay",
+      `readiness poll ${attempt + 1}/10: version=${newVersion ?? "not ready"}`
+    );
     if (newVersion) {
       logger?.log("Relay server started successfully");
       return;
@@ -15155,7 +15207,12 @@ __name(installSkills, "installSkills");
 
 // src/cli.ts
 var program = new Command();
-program.name("framer").version(VERSION).description("Framer Server API CLI");
+program.name("framer").version(VERSION).description("Framer Server API CLI").option("--debug", "Enable debug logging").hook("preAction", (thisCommand) => {
+  const opts = thisCommand.opts();
+  if (opts.debug) {
+    setDebugEnabled(true);
+  }
+});
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -15180,11 +15237,13 @@ function printSetupSummary(results) {
 }
 __name(printSetupSummary, "printSetupSummary");
 async function getAgentSystemPrompt(sessionId) {
+  debug("exec", "getAgentSystemPrompt: calling relay...");
   const result = await client.exec.mutate({
     sessionId,
     code: "return await framer.getAgentSystemPrompt();",
     cwd: process.cwd()
   });
+  debug("exec", "getAgentSystemPrompt: relay responded");
   if (result.error) {
     throw new Error(result.error);
   }
@@ -15196,11 +15255,13 @@ async function getAgentSystemPrompt(sessionId) {
 }
 __name(getAgentSystemPrompt, "getAgentSystemPrompt");
 async function getAgentContext(sessionId) {
+  debug("exec", "getAgentContext: calling relay...");
   const result = await client.exec.mutate({
     sessionId,
     code: "return await framer.getAgentContext({ pagePath: '/' });",
     cwd: process.cwd()
   });
+  debug("exec", "getAgentContext: relay responded");
   if (result.error) {
     throw new Error(result.error);
   }
@@ -15213,16 +15274,19 @@ async function getAgentContext(sessionId) {
 __name(getAgentContext, "getAgentContext");
 async function refreshSkillsFromSession(sessionId, projectId) {
   try {
+    debug("skills", "fetching agent system prompt + context...");
     const [canvasPrompt, agentContext] = await Promise.all([
       getAgentSystemPrompt(sessionId),
       getAgentContext(sessionId)
     ]);
+    debug("skills", "installing skills...");
     installSkills({
       type: "project",
       canvasPrompt,
       projectId,
       agentContext
     });
+    debug("skills", "skills installed");
   } catch (err) {
     printError(
       `Failed to refresh skills for session ${sessionId}: ${formatError(err)}`
@@ -15234,11 +15298,15 @@ __name(refreshSkillsFromSession, "refreshSkillsFromSession");
 async function resolveSessionCredentials(projectUrlOrId) {
   try {
     const projectId = extractProjectId(projectUrlOrId);
+    debug("credentials", `projectId=${projectId}`);
     const cachedApiKey = getApiKey(projectId);
     if (cachedApiKey) {
+      debug("credentials", "using cached API key");
       return { projectId, apiKey: cachedApiKey };
     }
+    debug("credentials", "no cached key, starting browser auth flow...");
     const newApiKey = await acquireKeyFromBrowser(projectId);
+    debug("credentials", "browser auth complete, saving project");
     saveProject({ projectId, apiKey: newApiKey });
     return { projectId, apiKey: newApiKey };
   } catch (err) {
@@ -15248,11 +15316,13 @@ async function resolveSessionCredentials(projectUrlOrId) {
 }
 __name(resolveSessionCredentials, "resolveSessionCredentials");
 async function getProjectName(sessionId) {
+  debug("exec", "getProjectName: calling relay...");
   const result = await client.exec.mutate({
     sessionId,
     code: "return (await framer.getProjectInfo()).name;",
     cwd: process.cwd()
   });
+  debug("exec", "getProjectName: relay responded");
   if (result.error) {
     throw new Error(result.error);
   }
@@ -15265,14 +15335,40 @@ async function getProjectName(sessionId) {
 __name(getProjectName, "getProjectName");
 async function ensureRelayForCli() {
   try {
+    debug("relay", "ensuring relay server is running...");
     await ensureRelayServerRunning({ logger: { log: print } });
+    debug("relay", "relay server ready");
   } catch (err) {
     printError(`Failed to check relay status: ${formatError(err)}`);
     process.exit(1);
   }
 }
 __name(ensureRelayForCli, "ensureRelayForCli");
-program.option("-s, --session <id>", "Session ID (required for code execution)").option("-e, --eval <code>", "Code to execute (or pipe via stdin)").option("-f, --file <path>", "File containing code to execute").action(async (options) => {
+async function execAndPrint(sessionId, code) {
+  await ensureRelayForCli();
+  try {
+    const result = await client.exec.mutate({
+      sessionId: String(sessionId),
+      code,
+      cwd: process.cwd()
+    });
+    for (const line of result.output) {
+      print(line);
+    }
+    if (result.error) {
+      printError(`Error: ${result.error}`);
+      process.exit(1);
+    }
+  } catch (err) {
+    printError(`Execution failed: ${formatError(err)}`);
+    process.exit(1);
+  }
+}
+__name(execAndPrint, "execAndPrint");
+program.command("exec").description("Execute code in a session").requiredOption(
+  "-s, --session <id>",
+  "Session ID (create one with `session new <projectUrlOrId>`)"
+).option("-e, --eval <code>", "Code to execute (or pipe via stdin)").option("-f, --file <path>", "File containing code to execute").action(async (options, command) => {
   const { session: sessionId, eval: evalCode, file: filePath } = options;
   ensureTemporaryDir();
   let code = evalCode;
@@ -15291,58 +15387,79 @@ program.option("-s, --session <id>", "Session ID (required for code execution)")
     code = await readStdin();
   }
   if (!code) {
-    program.help();
+    command.help();
     return;
   }
-  if (!sessionId) {
-    printError("Error: -s/--session is required.");
-    printError(
-      "Run `framer session new <projectUrlOrId>` first to get a session ID."
-    );
-    process.exit(1);
-  }
-  await ensureRelayForCli();
+  await execAndPrint(sessionId, code);
+});
+program.command("apply-changes").description("Apply canvas DSL changes to a page").requiredOption(
+  "-s, --session <id>",
+  "Session ID (create one with `session new <projectUrlOrId>`)"
+).requiredOption("-e, --eval <dsl>", "DSL string to apply").option("-p, --page <path>", "Target page path", "/").action(async (options) => {
+  const { session: sessionId, eval: dsl, page: pagePath } = options;
+  const code = `
+      const result = await framer.applyAgentChanges(${JSON.stringify(dsl)}, { pagePath: ${JSON.stringify(pagePath)} });
+      if (result) console.log(JSON.stringify(result, null, 2));
+    `;
+  await execAndPrint(sessionId, code);
+});
+program.command("read-project").description("Read project state for a page").requiredOption(
+  "-s, --session <id>",
+  "Session ID (create one with `session new <projectUrlOrId>`)"
+).requiredOption("-q, --queries <json>", "JSON array of query objects").requiredOption("-p, --page <path>", "Target page path").action(async (options) => {
+  const {
+    session: sessionId,
+    queries: queriesJson,
+    page: pagePath
+  } = options;
+  let queries;
   try {
-    const result = await client.exec.mutate({
-      sessionId: String(sessionId),
-      code,
-      cwd: process.cwd()
-    });
-    for (const line of result.output) {
-      print(line);
-    }
-    if (result.error) {
-      printError(`Error: ${result.error}`);
-      process.exit(1);
-    }
-  } catch (err) {
-    printError(`Execution failed: ${formatError(err)}`);
+    queries = JSON.parse(queriesJson);
+  } catch {
+    printError("Invalid JSON for --queries");
     process.exit(1);
   }
+  const code = `
+      const result = await framer.readProjectForAgent(${JSON.stringify(queries)}, { pagePath: ${JSON.stringify(pagePath)} });
+      if (result) console.log(JSON.stringify(result, null, 2));
+    `;
+  await execAndPrint(sessionId, code);
 });
 var session = program.command("session").description("Manage sessions");
 session.command("new <projectUrlOrId>").description("Create a new session and print the session ID").action(async (projectUrlOrId) => {
+  debug("session.new", `starting for ${projectUrlOrId}`);
+  debug("session.new", "resolving credentials + ensuring relay...");
   const [credentials] = await Promise.all([
     resolveSessionCredentials(projectUrlOrId),
     ensureRelayForCli()
   ]);
+  debug(
+    "session.new",
+    `credentials resolved for project=${credentials.projectId}`
+  );
   try {
+    debug("session.new", "calling createSession on relay...");
     const result = await client.createSession.mutate({
       projectId: credentials.projectId,
       apiKey: credentials.apiKey
     });
     const sessionId = result.id;
+    debug("session.new", `session created id=${sessionId}`);
+    debug("session.new", "fetching project name + refreshing skills...");
     const [projectName] = await Promise.all([
       getProjectName(sessionId),
       refreshSkillsFromSession(sessionId, credentials.projectId)
     ]);
+    debug("session.new", `project name="${projectName}", skills refreshed`);
     saveProject({
       projectId: credentials.projectId,
       apiKey: credentials.apiKey,
       name: projectName,
       lastUsedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
+    debug("session.new", "project saved, printing session id");
     print(sessionId);
+    debug("session.new", "done \u2014 process should exit now");
   } catch (err) {
     const message = formatError(err);
     printError(`Failed to create session: ${message}`);

package/dist/start-relay-server.js

@@ -13,7 +13,7 @@ import { createRequire } from 'module';
 import * as vm from 'vm';
 import { connect } from 'framer-api';
 
-/* @framer/ai relay server v0.0.13 */
+/* @framer/ai relay server v0.0.15 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name, symbol) => (symbol = Symbol[name]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name);
 var __typeError = (msg) => {
@@ -89,9 +89,16 @@ function log(message) {
 `);
 }
 __name(log, "log");
+
+// src/version.ts
+var VERSION = (
+  // typeof is used to ensure this can be used just via tsx or node etc. without build
+  "0.0.15" 
+);
+
+// src/relay-client.ts
 var __filename$1 = fileURLToPath(import.meta.url);
 path.dirname(__filename$1);
-var VERSION = "0.0.13" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 createTRPCClient({
   links: [
@@ -527,7 +534,9 @@ var ConnectionPool = class {
       }
       return entry.connection;
     }
-    const connection = await connect(projectId, apiKey);
+    const connection = await connect(projectId, apiKey, {
+      clientId: `dalton/${VERSION}`
+    });
     this.pool.set(projectId, {
       connection,
       sessions: /* @__PURE__ */ new Set([session]),

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

@@ -1,7 +1,7 @@
 ---
 name: {{SKILL_NAME}}
 description: "Project-scoped Framer canvas editing skill for project {{PROJECT_ID}}. 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:*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 ## Project Scope
@@ -11,12 +11,11 @@ allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)",
 
 ## Rules
 
-- For design/layout work, do not use low-level node APIs (`createNode`, `setAttributes`, `setRect`, etc.). Use the canvas editing flow (`readProjectForAgent` + `applyAgentChanges`) with the embedded prompt and project context in this skill.
+- For design/layout work, do not use low-level node APIs (`createNode`, `setAttributes`, `setRect`, etc.). Use the canvas editing flow (`read-project` + `apply-changes`) with the embedded prompt and project context in this skill.
 - Canvas editing agent methods are employee-only.
-- Canvas editing methods are not globals. Call `framer.readProjectForAgent` and `framer.applyAgentChanges` as `framer.*`.
 - During normal task execution, do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()`. This skill already includes `getAgentContext({ pagePath: "/" })`.
-- `framer.readProjectForAgent(queries, { pagePath })` reads project state. Start with page structure only, then request additional targeted queries only if needed. Query types are documented in the embedded prompt below. Never guess names for examples, icon sets, or fonts; look them up first.
-- `framer.applyAgentChanges(dsl, { pagePath })` applies canvas DSL changes. After applying changes, re-read project state to inspect results and iterate with `readProjectForAgent` + `applyAgentChanges` until accurate.
+- `npx framer-dalton read-project -s <sessionId> -q <queries> -p <pagePath>` reads project state. Start with page structure only, then request additional targeted queries only if needed. Query types are documented in the embedded prompt below. Never guess names for examples, icon sets, or fonts; look them up first.
+- `npx framer-dalton apply-changes -s <sessionId> -p <pagePath> -e <dsl>` applies canvas DSL changes. After applying changes, re-read project state to inspect results and iterate with `read-project` + `apply-changes` until accurate.
 - Request examples only when needed, and only after inspecting page structure first. Keep example queries targeted and minimal.
 - Use screenshots only when visual verification is necessary and cannot be confirmed from state reads. Do not use them for initial inspection or between every small change.
 - When setting text content, use raw Unicode characters directly (for example `->`, not `\u2192`).
@@ -27,34 +26,27 @@ allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)",
 ## Workflow Loop
 
 ```bash
-# 1) Read page structure first — write code to a unique file, then execute with -f
-# {{FRAMER_TEMPORARY_DIR}}/<sessionId>-read-page.js:
-#   const { results } = await framer.readProjectForAgent(
-#     [{ type: "page", path: "/" }],
-#     { pagePath: "/" }
-#   );
-#   console.log(results);
-
-framer -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-read-page.js
+# 1) Read page structure first
+npx framer-dalton read-project -s <sessionId> -q '[{"type":"page","path":"/"}]' -p "/"
 
 # 2) Request additional targeted queries only if needed
 
-# 3) Apply changes in a later call, once `dsl` has been prepared
-# {{FRAMER_TEMPORARY_DIR}}/<sessionId>-apply-changes.js:
-#   const dsl = `
-#   ...your canvas DSL...
-#   `;
-#   await framer.applyAgentChanges(dsl, { pagePath: "/" });
-
-framer -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-apply-changes.js
+# 3) Apply changes — pass DSL directly via apply-changes
+npx framer-dalton apply-changes -s <sessionId> -p "/" -e "$dsl"
 ```
 
+## Critical for UX: Streaming
+
+When you generate DSL to apply, keep it short. Each `apply-changes` call must only cover ONE logical section (header, footer, hero, card, etc.). Once you apply ONE section, continue with the next.
+
+This ensures progress is streamed to the user in small, visible increments.
+
 ## Live Agent System Prompt
 
 This is the static canvas-editing prompt returned by `framer.getAgentSystemPrompt()`. It is the sole documentation for:
 
-- command syntax for `applyAgentChanges`
-- query types and parameters for `readProjectForAgent`
+- command syntax for `apply-changes`
+- query types and parameters for `read-project`
 - design rules and examples used by the canvas editing flow
 
 {{CANVAS_PROMPT}}

package/docs/skills/framer.md

@@ -3,7 +3,7 @@ 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:*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 If you didn't run this command before loading the skill, run it now:
@@ -28,6 +28,10 @@ What you can do with the Framer CLI:
 
 ## CLI Usage
 
+### 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.
+
 ### Required Workflow
 
 Every task follows these steps:
@@ -62,7 +66,7 @@ npx framer-dalton docs Collection.getItems  # What are the parameters and return
 Only after checking docs, write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`. 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`). Files are automatically deleted after execution.
 
 ```bash
-npx framer-dalton -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
+npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
 ```
 
 #### 4. Store results in `state`
@@ -96,7 +100,7 @@ state.collections = await framer.getCollections();
 ```
 
 ```bash
-npx framer-dalton -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
+npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
 ```
 
 ```js
@@ -106,7 +110,7 @@ console.log(state.teamItems.length);
 ```
 
 ```bash
-npx framer-dalton -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
+npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
 ```
 
 Store anything you'll reference again.
@@ -136,7 +140,7 @@ npx framer-dalton session list
 
 ## Canvas Editing
 
-For design tasks, do not try to build or restyle pages with low-level node APIs. Instead, load the dynamically created project-scoped canvas skill and follow its `readProjectForAgent` plus `applyAgentChanges` flow.
+For design tasks, do not try to build or restyle pages with low-level node APIs. Instead, load the dynamically created project-scoped canvas skill and use the `read-project` and `apply-changes` subcommands.
 
 After session creation, load the dynamically created project-scoped skill `framer-canvas-editing-project-<projectId>` for canvas editing on the connected project. It contains the canvas editing guidance, the live agent system prompt, and the live project context for `pagePath: "/"`.
 
@@ -145,7 +149,7 @@ After session creation, load the dynamically created project-scoped skill `frame
 Write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and execute with `-f`:
 
 ```bash
-npx framer-dalton -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
+npx framer-dalton exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
 ```
 
 ## API Documentation
@@ -641,6 +645,7 @@ const contributors = await framer.getChangeContributors();
 
 ### Known Limitations
 
-- **Pages**: No list, delete, update, move, or settings APIs (create only)
+- **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.13",
+  "version": "0.0.15",
   "type": "module",
   "bin": {
     "framer-dalton": "./dist/cli.js"
@@ -25,7 +25,7 @@
     "@trpc/client": "^11.9.0",
     "@trpc/server": "^11.9.0",
     "commander": "^12.1.0",
-    "framer-api": "https://pkg.pr.new/framer/FramerStudio/framer-api@0711174.tgz",
+    "framer-api": "^0.1.4",
     "zod": "^4.3.6"
   },
   "devDependencies": {