framer-dalton 0.0.5 → 0.0.6

package/README.md

@@ -1,34 +1,78 @@
 # Framer Agent CLI
 
-CLI and Agent skill for interacting with Framer projects via the Framer Server API.
+CLI and agent skills for interacting with Framer projects via the Framer Server API.
 
 ## Installation
 
+Install or refresh the globally available skills:
+
 ```bash
-npx skills add framer/dalton
+npx framer-dalton@latest setup
 ```
 
-Then, simply open your preferred agent, ask to interact with your Framer project and the agent will handle the rest.
+That installs skills into `~/.agents/skills` and `~/.claude/skills`.
+
+## How It Works
 
-## CLI Usage
+The CLI and the installed skills are meant to work together. There are three skills:
 
-See [skills/framer/SKILL.md](skills/framer/SKILL.md) for full CLI usage and API documentation.
+- `framer` - the base skill that explains how to use the CLI and the API in general.
+- `framer-code-components` - explains specific prompts for how to write code components and provides examples.
+- `framer-canvas-editing-project-<project id>` - a dynamically-created skill that explains how to canvas edit and includes project context.
+
+1. Running `npx framer-dalton@latest setup` will install the base `framer` and `framer-code-component` skills.
+2. The frontmatter of `framer-code-components` tells agents to always load `framer` 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.
+4. Creating a new session for a project will create a `framer-canvas-editing-project-<project id>` file. This file contains the latest agent system prompt from `framer.getAgentSystemPrompt` and the latest project context from `framer.getAgentContext`. Agents are told not to load this skill until after creating a session.
 
 ## Local Development
 
-Build and symlink to PATH + install skill locally:
+### Running a development build against production headless api server
+
+1. Run `make install-dev` in this repo.
+
+2. Run your agent in this directory and specifically load the `framer-dev` skill:
 
 ```bash
-make install-dev
+# Claude: 
+> /framer-dev
+
+# Codex:
+> $framer-dev
 ```
 
-If you want to hit a local FramerHeadlessAPI instance, when interacting with your agent, tell it something like this:
+### Running with the local headless plugin server
+
+Use this when you change something in the Server API implementation.
+
+1. Start FramerStudio with `make dev`.
+2. Start FramerHeadlessAPI against the local tunnel with `make dev-tunnel`.
+3. Run `make install-dev` in this repo.
+4. Run your agent in this directory and specifically load the `framer-dev-local` skill:
 
+```bash
+# Claude: 
+> /framer-dev-local
+
+# Codex:
+> $framer-dev-local
 ```
-Use the framer skill, but use `FRAMER_HEADLESS_SERVER_URL=ws://localhost:8080/channel/headless-plugin framer` (never with @latest) for all commands instead of `npx framer-dalton`
+
+### Using a local `framer-api` package
+
+Use this when you change the server API interface itself, such as adding or changing API methods.
+
+1. Publish or otherwise make your updated `framer-api` package available.
+2. Install it locally with `npm install ...`.
+3. Regenerate the type data:
+
+```bash
+make generate-types
 ```
 
-Remove local install:
+### Removing local builds and returning to production
+
+Later, to return to the procution skills:
 
 ```bash
 make uninstall-dev

package/dist/cli.js

@@ -1,34 +1,34 @@
 #!/usr/bin/env node
+import path3 from 'path';
 import { Command } from 'commander';
-import fs, { readFileSync } from 'fs';
+import fs2 from 'fs';
 import os from 'os';
-import path, { dirname, join } from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.5 */
+/* @framer/ai CLI v0.0.6 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function getConfigDir() {
   if (process.env.XDG_CONFIG_HOME) {
-    return path.join(process.env.XDG_CONFIG_HOME, "framer");
+    return path3.join(process.env.XDG_CONFIG_HOME, "framer");
   }
   if (process.platform === "win32") {
-    return path.join(process.env.APPDATA || os.homedir(), "framer");
+    return path3.join(process.env.APPDATA || os.homedir(), "framer");
   }
-  return path.join(os.homedir(), ".config", "framer");
+  return path3.join(os.homedir(), ".config", "framer");
 }
 __name(getConfigDir, "getConfigDir");
 function getCredentialsPath() {
-  return path.join(getConfigDir(), "credentials.json");
+  return path3.join(getConfigDir(), "credentials.json");
 }
 __name(getCredentialsPath, "getCredentialsPath");
 function readCredentials() {
   const credPath = getCredentialsPath();
   try {
-    if (fs.existsSync(credPath)) {
-      return JSON.parse(fs.readFileSync(credPath, "utf-8"));
+    if (fs2.existsSync(credPath)) {
+      return JSON.parse(fs2.readFileSync(credPath, "utf-8"));
     }
   } catch {
   }
@@ -38,10 +38,10 @@ __name(readCredentials, "readCredentials");
 function writeCredentials(creds) {
   const credPath = getCredentialsPath();
   const configDir = getConfigDir();
-  if (!fs.existsSync(configDir)) {
-    fs.mkdirSync(configDir, { recursive: true, mode: 448 });
+  if (!fs2.existsSync(configDir)) {
+    fs2.mkdirSync(configDir, { recursive: true, mode: 448 });
   }
-  fs.writeFileSync(credPath, JSON.stringify(creds, null, "	"), {
+  fs2.writeFileSync(credPath, JSON.stringify(creds, null, "	"), {
     mode: 384
   });
 }
@@ -14460,6 +14460,7 @@ __name(expandReferences, "expandReferences");
 function renderDocs(queries) {
   const lines = [];
   const errors = [];
+  const framerClass = getClass("framer");
   if (queries.length === 0) {
     queries = ["framer"];
   }
@@ -14482,6 +14483,20 @@ function renderDocs(queries) {
 ${typeDef}`);
       }
     } else {
+      if (framerClass) {
+        const method = framerClass.methods.find((m) => m.name === query);
+        if (method) {
+          if (method.description)
+            lines.push(formatDocComment(method.description));
+          lines.push(`${method.category}.${method.signature}`);
+          const seen = /* @__PURE__ */ new Set();
+          for (const typeDef of expandReferences(method.references, seen)) {
+            lines.push(`
+${typeDef}`);
+          }
+          continue;
+        }
+      }
       const classData = getClass(query);
       if (classData) {
         lines.push(
@@ -14511,8 +14526,8 @@ ${typeDef}`);
 }
 __name(renderDocs, "renderDocs");
 var __filename$1 = fileURLToPath(import.meta.url);
-var __dirname$1 = path.dirname(__filename$1);
-var VERSION = "0.0.5" ;
+var __dirname$1 = path3.dirname(__filename$1);
+var VERSION = "0.0.6" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 var client = createTRPCClient({
   links: [
@@ -14548,7 +14563,7 @@ function compareVersions(v1, v2) {
   return 0;
 }
 __name(compareVersions, "compareVersions");
-async function ensureRelayServer(options = {}) {
+async function ensureRelayServerRunning(options = {}) {
   const { logger, restartOnVersionMismatch = true } = options;
   const serverVersion = await getRelayServerVersion();
   if (serverVersion === VERSION) {
@@ -14574,7 +14589,7 @@ async function ensureRelayServer(options = {}) {
     logger?.log("Relay server not running, starting it...");
   }
   const isRunningFromSource = __filename$1.endsWith(".ts");
-  const scriptPath = isRunningFromSource ? path.resolve(__dirname$1, "./start-relay-server.ts") : path.resolve(__dirname$1, "./start-relay-server.js");
+  const scriptPath = isRunningFromSource ? path3.resolve(__dirname$1, "./start-relay-server.ts") : path3.resolve(__dirname$1, "./start-relay-server.js");
   const serverProcess = spawn(
     isRunningFromSource ? "tsx" : process.execPath,
     [scriptPath],
@@ -14595,22 +14610,107 @@ async function ensureRelayServer(options = {}) {
   }
   throw new Error("Failed to start relay server after 5 seconds");
 }
-__name(ensureRelayServer, "ensureRelayServer");
-var __dirname2 = dirname(fileURLToPath(import.meta.url));
-var docsDir = join(__dirname2, "..", "docs");
-function readDoc(name) {
-  return readFileSync(join(docsDir, `${name}.md`), "utf-8").trimEnd();
+__name(ensureRelayServerRunning, "ensureRelayServerRunning");
+var META_SKILL_NAME = "framer";
+var CODE_COMPONENTS_SKILL_NAME = "framer-code-components";
+var __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
+var skillsDocsDir = path3.join(__dirname2, "..", "docs", "skills");
+function readSkillDoc(name) {
+  return fs2.readFileSync(path3.join(skillsDocsDir, name), "utf-8").trimEnd();
+}
+__name(readSkillDoc, "readSkillDoc");
+function buildMetaSkill() {
+  return `${readSkillDoc("framer.md")}
+`;
+}
+__name(buildMetaSkill, "buildMetaSkill");
+function buildCodeComponentsSkill() {
+  return `${readSkillDoc("framer-code-components.md")}
+`;
+}
+__name(buildCodeComponentsSkill, "buildCodeComponentsSkill");
+function renderTemplate(template, values) {
+  let rendered = template;
+  for (const [key, value] of Object.entries(values)) {
+    rendered = rendered.split(`{{${key}}}`).join(value);
+  }
+  return rendered;
+}
+__name(renderTemplate, "renderTemplate");
+function toProjectSkillName(projectId) {
+  const safeProjectId = projectId.replace(/[^a-zA-Z0-9_-]/g, "-");
+  return `framer-canvas-editing-project-${safeProjectId}`;
+}
+__name(toProjectSkillName, "toProjectSkillName");
+function buildProjectCanvasSkill(projectId, agentContext, canvasPrompt) {
+  const skillName = toProjectSkillName(projectId);
+  const template = readSkillDoc("framer-canvas-editing-project.md");
+  const content = `${renderTemplate(template, {
+    SKILL_NAME: skillName,
+    PROJECT_ID: projectId,
+    GENERATED_AT: (/* @__PURE__ */ new Date()).toISOString(),
+    CANVAS_PROMPT: canvasPrompt.trimEnd(),
+    AGENT_CONTEXT: agentContext.trimEnd()
+  })}
+`;
+  return { skillName, content };
 }
-__name(readDoc, "readDoc");
-var skillTopics = [
-  "code-components",
-  "property-controls",
-  "component-examples"
-];
-function isSkillTopic(topic) {
-  return skillTopics.some((name) => name === topic);
+__name(buildProjectCanvasSkill, "buildProjectCanvasSkill");
+function writeSkill(root, skillName, content) {
+  fs2.mkdirSync(root, { recursive: true });
+  const rootStat = fs2.statSync(root);
+  if (!rootStat.isDirectory()) {
+    throw new Error(`Skill root is not a directory: ${root}`);
+  }
+  const skillDir = path3.join(root, skillName);
+  const filePath = path3.join(skillDir, "SKILL.md");
+  if (fs2.existsSync(skillDir)) {
+    const current = fs2.lstatSync(skillDir);
+    if (current.isSymbolicLink() || !current.isDirectory()) {
+      fs2.rmSync(skillDir, { recursive: true, force: true });
+    }
+  }
+  fs2.mkdirSync(skillDir, { recursive: true });
+  fs2.writeFileSync(filePath, content, "utf-8");
+  return filePath;
+}
+__name(writeSkill, "writeSkill");
+function getDefaultSkillRoots() {
+  const home = os.homedir();
+  return [
+    path3.join(home, ".agents", "skills"),
+    path3.join(home, ".claude", "skills")
+  ];
+}
+__name(getDefaultSkillRoots, "getDefaultSkillRoots");
+function installSkills(options = { type: "base" }) {
+  const skillRoots = options.skillRoots ?? getDefaultSkillRoots();
+  const skills = [
+    { name: META_SKILL_NAME, content: buildMetaSkill() },
+    {
+      name: CODE_COMPONENTS_SKILL_NAME,
+      content: buildCodeComponentsSkill()
+    }
+  ];
+  if (options.type === "project") {
+    const projectSkill = buildProjectCanvasSkill(
+      options.projectId,
+      options.agentContext,
+      options.canvasPrompt
+    );
+    skills.push({
+      name: projectSkill.skillName,
+      content: projectSkill.content
+    });
+  }
+  return skills.map((skill) => ({
+    skillName: skill.name,
+    paths: skillRoots.map(
+      (root) => writeSkill(root, skill.name, skill.content)
+    )
+  }));
 }
-__name(isSkillTopic, "isSkillTopic");
+__name(installSkills, "installSkills");
 
 // src/utils.ts
 function formatError(error) {
@@ -14644,6 +14744,116 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf-8");
 }
 __name(readStdin, "readStdin");
+function printSetupSummary(results) {
+  const skillCount = results.length;
+  const installLocations = /* @__PURE__ */ new Set();
+  for (const result of results) {
+    for (const filePath of result.paths) {
+      const skillDir = path3.dirname(filePath);
+      const root = path3.dirname(skillDir);
+      installLocations.add(root);
+    }
+  }
+  print(
+    `Installed ${skillCount} skills to ${Array.from(installLocations).sort().join(", ")}`
+  );
+}
+__name(printSetupSummary, "printSetupSummary");
+async function getAgentSystemPrompt(sessionId) {
+  const result = await client.exec.mutate({
+    sessionId,
+    code: "return await framer.getAgentSystemPrompt();",
+    cwd: process.cwd()
+  });
+  if (result.error) {
+    throw new Error(result.error);
+  }
+  const prompt = result.output.at(-1);
+  if (typeof prompt !== "string") {
+    throw new Error("Did not receive agent prompt output.");
+  }
+  return prompt;
+}
+__name(getAgentSystemPrompt, "getAgentSystemPrompt");
+async function getAgentContext(sessionId) {
+  const result = await client.exec.mutate({
+    sessionId,
+    code: "return await framer.getAgentContext({ pagePath: '/' });",
+    cwd: process.cwd()
+  });
+  if (result.error) {
+    throw new Error(result.error);
+  }
+  const context = result.output.at(-1);
+  if (typeof context !== "string") {
+    throw new Error("Did not receive agent context output.");
+  }
+  return context;
+}
+__name(getAgentContext, "getAgentContext");
+async function refreshSkillsFromSession(sessionId, projectId) {
+  try {
+    const [canvasPrompt, agentContext] = await Promise.all([
+      getAgentSystemPrompt(sessionId),
+      getAgentContext(sessionId)
+    ]);
+    installSkills({
+      type: "project",
+      canvasPrompt,
+      projectId,
+      agentContext
+    });
+  } catch (err) {
+    printError(
+      `Failed to refresh skills for session ${sessionId}: ${formatError(err)}`
+    );
+    process.exit(1);
+  }
+}
+__name(refreshSkillsFromSession, "refreshSkillsFromSession");
+function resolveSessionCredentials(projectUrl, apiKeyArg) {
+  try {
+    const projectId = extractProjectId(projectUrl);
+    if (!apiKeyArg) {
+      const cachedApiKey = getApiKey(projectId);
+      if (cachedApiKey) {
+        return { projectId, apiKey: cachedApiKey };
+      }
+      printError("No API key provided and none cached for this project.");
+      printError("");
+      printError("Usage: framer session new <projectUrl> <apiKey>");
+      process.exit(1);
+    }
+    saveApiKey(projectId, apiKeyArg);
+    return { projectId, apiKey: apiKeyArg };
+  } catch (err) {
+    printError(`Failed to create session: ${formatError(err)}`);
+    process.exit(1);
+  }
+}
+__name(resolveSessionCredentials, "resolveSessionCredentials");
+async function createSession(projectId, apiKey) {
+  try {
+    const result = await client.createSession.mutate({
+      projectId,
+      apiKey
+    });
+    return result.id;
+  } catch (err) {
+    printError(`Failed to create session: ${formatError(err)}`);
+    process.exit(1);
+  }
+}
+__name(createSession, "createSession");
+async function ensureRelayForCli() {
+  try {
+    await ensureRelayServerRunning({ logger: { log: print } });
+  } 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)").action(async (options) => {
   const { session: sessionId, eval: evalCode } = options;
   let code = evalCode;
@@ -14661,8 +14871,8 @@ program.option("-s, --session <id>", "Session ID (required for code execution)")
     );
     process.exit(1);
   }
+  await ensureRelayForCli();
   try {
-    await ensureRelayServer({ logger: { log: print } });
     const result = await client.exec.mutate({
       sessionId: String(sessionId),
       code,
@@ -14682,36 +14892,18 @@ program.option("-s, --session <id>", "Session ID (required for code execution)")
 });
 var session = program.command("session").description("Manage sessions");
 session.command("new <projectUrl> [apiKey]").description("Create a new session and print the session ID").action(async (projectUrlArg, apiKeyArg) => {
-  try {
-    const projectId = extractProjectId(projectUrlArg);
-    let apiKey = apiKeyArg;
-    if (!apiKey) {
-      const cached = getApiKey(projectId);
-      if (cached) {
-        apiKey = cached;
-      } else {
-        printError("No API key provided and none cached for this project.");
-        printError("");
-        printError("Usage: framer session new <projectUrl> <apiKey>");
-        process.exit(1);
-      }
-    } else {
-      saveApiKey(projectId, apiKey);
-    }
-    await ensureRelayServer({ logger: { log: print } });
-    const result = await client.createSession.mutate({
-      projectId,
-      apiKey
-    });
-    print(result.id);
-  } catch (err) {
-    printError(`Failed to create session: ${formatError(err)}`);
-    process.exit(1);
-  }
+  const { projectId, apiKey } = resolveSessionCredentials(
+    projectUrlArg,
+    apiKeyArg
+  );
+  await ensureRelayForCli();
+  const sessionId = await createSession(projectId, apiKey);
+  await refreshSkillsFromSession(sessionId, projectId);
+  print(sessionId);
 });
 session.command("list").description("List all active sessions").action(async () => {
+  await ensureRelayForCli();
   try {
-    await ensureRelayServer({ logger: { log: print } });
     const sessions = await client.listSessions.query();
     if (sessions.length === 0) {
       print("No active sessions");
@@ -14724,8 +14916,8 @@ session.command("list").description("List all active sessions").action(async ()
   }
 });
 session.command("destroy <sessionId>").description("Destroy a session").action(async (sessionId) => {
+  await ensureRelayForCli();
   try {
-    await ensureRelayServer({ logger: { log: print } });
     await client.destroySession.mutate({ sessionId });
     print(`Session ${sessionId} destroyed`);
   } catch (err) {
@@ -14749,24 +14941,18 @@ relay.command("restart").description("Restart the relay server").action(async ()
   } catch {
   }
   await new Promise((resolve) => setTimeout(resolve, 500));
-  await ensureRelayServer({ logger: { log: print } });
+  await ensureRelayForCli();
 });
-program.command("skill [topic]").description("Output skill documentation").action((topic) => {
-  if (!topic) {
-    print(readDoc("server-api"));
-    print("");
-    print(readDoc("all-skills"));
-    return;
-  }
-  if (!isSkillTopic(topic)) {
-    const available = ["(no argument)", ...skillTopics];
-    printError(`Unknown skill topic: ${topic}`);
-    printError(`Available topics: ${available.join(", ")}`);
+program.command("setup").description(
+  "Install Framer skills into ~/.agents/skills and ~/.claude/skills"
+).action(() => {
+  try {
+    const results = installSkills();
+    printSetupSummary(results);
+  } catch (err) {
+    printError(`Setup failed: ${formatError(err)}`);
     process.exit(1);
   }
-  print(readDoc(topic));
-  print("");
-  print(readDoc("all-skills"));
 });
 program.command("docs [queries...]").description(
   "Look up API documentation. Use: docs, docs ClassName, docs Class.method, or docs TypeName"

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.5 */
+/* @framer/ai relay server v0.0.6 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 function getLogPath() {
@@ -50,7 +50,7 @@ function log(message) {
 __name(log, "log");
 var __filename$1 = fileURLToPath(import.meta.url);
 path.dirname(__filename$1);
-var VERSION = "0.0.5" ;
+var VERSION = "0.0.6" ;
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 createTRPCClient({
   links: [
@@ -688,7 +688,6 @@ process.on("unhandledRejection", (reason) => {
 });
 async function main() {
   const server = await startRelayServer(RELAY_PORT);
-  log(`started v${VERSION} on port ${RELAY_PORT}`);
   console.log(`Framer relay server v${VERSION} running on port ${RELAY_PORT}`);
   process.on("SIGINT", () => {
     log("shutdown SIGINT");

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

@@ -0,0 +1,69 @@
+---
+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."
+---
+
+## Project Scope
+
+- Project ID: {{PROJECT_ID}}
+- Generated At: {{GENERATED_AT}}
+
+## 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.
+- 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.
+- 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`).
+- Regenerate the embedded prompt and context by running `session new` again for the same project.
+- Node IDs assigned during commands are temporary and can only be referenced within the same `framer.applyAgentChanges` call. For later calls, re-read the project to get real IDs.
+- For rich text updates, default to `SET <RichTextNode-id> text="..."` for normal text replacement. Use `SET <TextRun-id> text="..."` only for intentional targeted run-level edits in multi-run content.
+- Child `TextRun` IDs are stable within one `applyAgentChanges` batch, but may change across batches or turns after re-hydration. Re-read before dependent follow-up commands in a new batch.
+- In rich text, block-level properties (for example line height or alignment) belong on block or parent targets, not `TextRun` targets.
+- `IconNode` `$control__icon` is immutable after creation. To change it, delete and recreate the node with the desired icon value.
+- `var(--token-<id>)` requires stable token IDs. Temporary IDs are only reliable within the same `applyAgentChanges` batch. If a token was created in a previous batch, re-read state to get its current real ID before referencing it, or create the token and dependents in one batch.
+
+## Workflow Loop
+
+```bash
+# 1) Read page structure first
+framer -s <sessionId> <<'EOF'
+const { results } = await framer.readProjectForAgent(
+  [{ type: "page", path: "/" }],
+  { pagePath: "/" }
+);
+
+console.log(results);
+EOF
+
+# 2) Request additional targeted queries only if needed
+
+# 3) Apply changes in a later call, once `dsl` has been prepared
+framer -s <sessionId> <<'EOF'
+const dsl = `
+...your canvas DSL...
+`;
+
+await framer.applyAgentChanges(dsl, { pagePath: "/" });
+EOF
+```
+
+## 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`
+- design rules and examples used by the canvas editing flow
+
+{{CANVAS_PROMPT}}
+
+## Live Agent Context (/)
+
+This is the dynamic project context returned by `framer.getAgentContext({ pagePath: "/" })`. It contains project-specific data for the current page, including available fonts, components and their controls, design tokens, style presets, and icon sets.
+
+{{AGENT_CONTEXT}}