@framer/agent 0.0.36 → 0.0.38

package/docs/skills/framer-project.md

@@ -1,479 +0,0 @@
----
-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({{FRAMER_AGENT_COMMAND}}:*)", "Bash({{FRAMER_AGENT_COMMAND}}@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
----
-
-## Project Scope
-
-- Project ID: {{PROJECT_ID}}
-- Generated At: {{GENERATED_AT}}
-
-## Required Workflow
-
-Every connected-project task follows these steps:
-
-### 1. Look up the API (before EVERY new use of an API method)
-
-**You MUST run `{{FRAMER_AGENT_COMMAND}}@latest docs` before writing any code.** Do not guess method names or signatures.
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest docs Collection           # What methods exist?
-{{FRAMER_AGENT_COMMAND}}@latest docs Collection.getItems  # What are the parameters and return type?
-```
-
-### 2. Execute code
-
-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
-{{FRAMER_AGENT_COMMAND}}@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
-```
-
-### 3. Store results in `state`
-
-Always save results you'll need again. Don't repeat API calls.
-
-## Method Selection
-
-Prefer the agent-specific methods `framer.agent.*` over regular plugin API methods (`framer.*`).
-
-For `framer.agent.readProject` and `framer.agent.applyChanges` calls, use the `{{FRAMER_AGENT_COMMAND}}@latest read-project` and `{{FRAMER_AGENT_COMMAND}}@latest apply-changes` subcommands when possible. It's still ok to call those methods in exec scripts if you require something more complex than a plain method call.
-
-- Use `framer.agent.getNode`, `framer.agent.getNodes`, `framer.agent.getNodesOfTypes`, `framer.agent.getScopeNode`, `framer.agent.getGroundNode`, `framer.agent.getParentNode`, `framer.agent.getAncestors`, `framer.agent.serialize`, `framer.agent.serializeNodes`, and `framer.agent.paginate` for project tree reads.
-- Do not use `{{FRAMER_AGENT_COMMAND}}@latest read-project` or `framer.agent.readProject` for node tree reads unless you have just checked current docs and confirmed the exact query type. Query shapes such as `{ type: "node-by-id" }` are not valid for the current local API.
-- Use `framer.agent.readComponentControls`, `framer.agent.readIconSetControls`, `framer.agent.readIcons`, `framer.agent.readLayoutTemplateControls`, and `framer.agent.readShaderControls` for reading the controls of components, icon sets, icons, layout templates, and shaders.
-- Use `framer.agent.applyChanges` for page and layout edits. Do not use low-level node APIs like `createNode`, `setAttributes`, or `setRect` for design/layout work.
-- Use `framer.agent.publish` for publishing. Do not use `publish`, `getDeployments`, or `deploy` for normal agent publishing flows.
-- 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.
-
-During normal task execution, do not call `framer.agent.getSystemPrompt()` or `framer.agent.getContext()`. This skill already includes their output.
-
-## Core Usage Principles
-
-- Be concise. Don't narrate implementation details like field IDs, escaping, or internal steps. Just do the work and report what was accomplished in user-facing terms.
-- Use `framer.*` for plugin API calls. Top-level methods are not globals.
-- If command output includes `[FRAMER_BRANCH_CHANGE]`, tell the user the active branch changed and include the `url` value.
-- Before making changes that add/update/delete content that the user has not clearly and explicitly requested in this conversation, inform the user of what you plan to do and why, and ask them to confirm.
-    - You do not need to ask for confirmation when carrying out a specific add/update/delete change that the user has already clearly requested (this counts as explicit consent).
-    - You do not need to explain or ask for confirmation for non-destructive calls like reading project state.
-    - If the exact action was not agreed upon, or you are inferring a broader change or choosing between multiple reasonable options using your own judgment, ask for confirmation.
-    - Always ask for confirmation before destructive actions that the user did not explicitly request - especially deletes, cleanup, resets, or broad removals inferred by the agent.
-
-## Compaction
-
-**Critical**: if an agent conversation is compacted, you MUST read the entirety of this skill back into context. This is non-negotiable and this instruction itself must not be lost during compaction.
-
-## Context Variables
-
-- `framer` - Connected Framer Server API instance
-- `state` - Object persisted between calls within your session
-- `console` - For output (`console.log`, `console.error`)
-- `require` - Sandboxed Node.js modules: fs, path, url, crypto, buffer, util, os
-- Standard globals: `fetch`, `Buffer`, `URL`, `crypto`, `setTimeout`
-
-**Note:** `fs` operations are sandboxed to cwd, /tmp, and os.tmpdir().
-
-## Use `state` to Avoid Repeated Calls
-
-**Always store results in `state` when you'll need them again.** API calls are slow - don't repeat them.
-
-```js
-// {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
-state.collections = await framer.getCollections();
-```
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
-```
-
-```js
-// {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js — reuse from state
-state.teamItems = await state.collections.find(c => c.name === 'Team').getItems();
-console.log(state.teamItems.length);
-```
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
-```
-
-Store anything you'll reference again.
-
-## Canvas Editing: Alternative Approach (“Prompt the Framer agent”)
-
-Use this approach only if the user asks for it. Do not mention this approach to the user otherwise.
-
-This approach is called “Prompt the Framer agent”. With this approach, use `framer.agent.startConversation()` to start a stateful design subagent. Keep the `conversationId` it returns in `state`, and call `framer.agent.continueConversation()` with it to continue the same design task.
-
-Do not call `framer.agent.getSystemPrompt()` or `framer.agent.getContext()` or `framer.agent.applyChanges()` with this approach.
-
-Example:
-
-```js
-state.agent ??= {};
-const first = await framer.agent.startConversation(
-  "Build me a landing page based on the attached screenshot",
-  {
-    pagePath: "/",
-    imageUrls: ["https://example.com/image.png"],
-    // selectionNodeIds: [...]
-  },
-);
-state.agent.conversationId = first.conversationId;
-console.log(first.responseMessages);
-
-const second = await framer.agent.continueConversation("Now make it pink", {
-  conversationId: state.agent.conversationId,
-  selectionNodeIds: ["someNodeId"],
-  // imageUrls: [...],
-  // changing pagePath or model is not supported
-});
-console.log(second.responseMessages);
-```
-
-Prompting may take a while to complete, so set the command timeout to 10 minutes.
-
-## Execute Code
-
-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
-{{FRAMER_AGENT_COMMAND}}@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.
-
-## Shell Quoting
-
-In Windows PowerShell, if an argument contains nested quotes, use a single-quoted here-string and pass the variable. Do not backslash-escape quotes.
-
-```powershell
-$value = @'
-[{"key":"value","filter":["text","$rect"]}]
-'@
-{{FRAMER_AGENT_COMMAND}}@latest <command> --option $value
-```
-
-## API Documentation
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest docs                            # List all available methods
-{{FRAMER_AGENT_COMMAND}}@latest docs framer.getCollections      # Show top level method
-{{FRAMER_AGENT_COMMAND}}@latest docs Collection                 # Show class with all method signatures
-{{FRAMER_AGENT_COMMAND}}@latest docs Collection.addItems        # Show method + recursively expand all referenced types
-{{FRAMER_AGENT_COMMAND}}@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 `{{FRAMER_AGENT_COMMAND}}@latest docs <ClassName>` to verify the current signature.**
-
-### Working with Collections (CMS)
-
-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.
-
-#### List collections and fields
-
-```js
-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 })),
-})));
-```
-
-#### Read items
-
-If you know the collection id, serialize the collection with `depth: 1` to read its direct item children.
-
-```js
-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 })),
-});
-```
-
-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.
-
-First page:
-
-```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 })),
-});
-```
-
-Next page, if nextCursor is set:
-
-```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 })),
-});
-```
-
-To search across all collections, read item nodes directly and filter by `$parentId`:
-
-```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);
-```
-
-#### Create and edit items
-
-`+CollectionItemNode` adds a row; `SET … $control__<fieldId>` sets cells (a `SET` on an existing item id updates it; `DEL <itemId>` removes it).
-
-```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(" ")};`];
-});
-
-console.log(await framer.agent.applyChanges(commands.join(" ")));
-```
-
-#### Writing enum fields
-
-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 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");
-
-console.log(await framer.agent.applyChanges(
-  `+CollectionItemNode newPost parent="${collection.id}";
-   SET newPost $control__slug="hello-world" ${statusField.key}="${status}";`,
-));
-```
-
-#### 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 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};`));
-
-console.log(await framer.agent.applyChanges(commands.join(" ")));
-```
-
-#### Field Types
-
-`boolean`, `color`, `number`, `string`, `formattedText` (HTML), `image`, `file`, `link`, `date`, `enum`, `collectionReference`, `multiCollectionReference`, `array` (galleries)
-
-### Working with Images
-
-Canvas editing accepts image URLs directly when setting an image fill, so the typical task is to obtain a URL and use it directly with `framer.agent.applyChanges`.
-
-There are three sources you'll typically pull URLs from:
-
-**Stock photography.** Use `framer.agent.queryImages` to source candidates and stash the URL you want:
-
-```js
-const { results } = await framer.agent.queryImages({
-  source: "unsplash",
-  query: "snow-capped mountains",
-  count: 4,
-  orientation: "landscape",
-});
-state.heroUrl = results[0].url;
-```
-
-**An external URL the user provided.** Pass it through directly. If you'll reuse the same image across many edits, upload it once and stash the resulting asset URL to avoid re-resolving the source on every change:
-
-```js
-state.heroUrl = (await framer.uploadImage({
-  image: "https://example.com/hero.png",
-  altText: "Mountain range at sunset",
-})).url;
-```
-
-**An image already on the canvas.** Read the node and reuse its existing image URL:
-
-```js
-const node = await framer.agent.getNode({ id: "<image-node-id>" });
-state.heroUrl = node.attributes.fill;
-```
-
-For inline SVGs, use the plugin method directly:
-
-```js
-await framer.addSVG({
-  svg: '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20"><circle cx="10" cy="10" r="8"/></svg>',
-  name: "circle.svg",
-});
-```
-
-### Code Components
-
-Code components are custom React components that run inside Framer. Use them when you need behavior that Framer's canvas doesn't support:
-
-- **Custom interactivity** — drag-to-reorder, gesture-driven animations, games, form validation
-- **External data** — fetching from APIs, rendering dynamic content, real-time updates
-- **Complex logic** — state machines, calculations, conditional rendering beyond simple variants
-- **Third-party libraries** — maps, charts, video players, rich text editors
-- **Canvas/WebGL** — custom drawing, 3D rendering, generative art
-
-
-If the design can be built with Framer's built-in components, layout tools, and interactions — don't use a code component. Code components are harder to maintain and can't be visually edited.
-
-Before writing code components, load the `framer-code-components` skill.
-
-#### Creation
-
-```js
-state.codeFile = await framer.createCodeFile("Badge.tsx", code);
-state.diagnostics = await state.codeFile.typecheck();
-console.log(state.diagnostics);
-```
-
-```js
-state.component = state.codeFile.exports.find(
-  (exportItem) => exportItem.type === "component" && exportItem.isDefaultExport,
-);
-console.log(await framer.agent.applyChanges(
-  `+ComponentInstanceNode badge parent="wrapper" component="${state.component.componentId}"; SET badge width=120 height=48;`,
-  { pagePath: "/" },
-));
-```
-
-#### Editing
-
-```js
-const codeFile = await framer.getCodeFile("Badge.tsx");
-state.updatedCodeFile = await codeFile.setFileContent(code);
-state.diagnostics = await state.updatedCodeFile.typecheck();
-console.log(state.diagnostics);
-```
-
-For large files, write `codeFile.content` to disk:
-
-```js
-const fs = require("fs");
-
-state.codeFile = await framer.getCodeFile("Badge.tsx");
-state.localCodePath = "{{FRAMER_TEMPORARY_DIR}}/Badge.tsx";
-fs.writeFileSync(state.localCodePath, state.codeFile.content);
-```
-
-Update the file with your patch tools, then load it back into Framer:
-
-```js
-const fs = require("fs");
-const code = fs.readFileSync(state.localCodePath, "utf8");
-state.updatedCodeFile = await state.codeFile.setFileContent(code);
-state.diagnostics = await state.updatedCodeFile.typecheck();
-console.log(state.diagnostics);
-```
-
-### Storing Data
-
-Store metadata on nodes or globally in the project.
-
-```js
-// Store global project data
-await framer.setPluginData("myKey", "myValue");
-const value = await framer.getPluginData("myKey");
-
-// Store data on a node
-await node.setPluginData("processed", "true");
-const nodeData = await node.getPluginData("processed");
-
-// List all keys
-const keys = await framer.getPluginDataKeys();
-const nodeKeys = await node.getPluginDataKeys();
-
-// Delete data (set to null)
-await framer.setPluginData("myKey", null);
-```
-
-### Localization
-
-```js
-// Get all locales
-const locales = await framer.getLocales();
-const defaultLocale = await framer.getDefaultLocale();
-
-// Get localization groups (pages, CMS items with translations)
-const groups = await framer.getLocalizationGroups();
-
-// Update translations
-const french = locales.find((l) => l.code === "fr");
-await framer.setLocalizationData({
-  valuesBySource: {
-    [sourceId]: {
-      [french.id]: { action: "set", value: "Bonjour" },
-    },
-  },
-});
-```
-
-### Known Limitations
-
-- **Pages**: Cannot change the path of a page
-- **Code overrides**: Cannot assign overrides to nodes
-- **Analytics**: No APIs exist for accessing analytics data
-
----
-
-Below is documentation for agent-specific methods and guidelines on how to work on projects.
-
-{{AGENT_PROMPT}}
-
----
-
-Below is the current project context:
-
-{{AGENT_CONTEXT}}

package/docs/skills/framer.md

@@ -1,76 +0,0 @@
----
-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 `{{FRAMER_AGENT_COMMAND}}@latest setup` and let it complete **BEFORE** loading this skill.
-allowed-tools: ["Bash({{FRAMER_AGENT_COMMAND}}:*)", "Bash({{FRAMER_AGENT_COMMAND}}@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
----
-
-If you didn't run this command before loading the skill, run it now:
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest setup
-```
-
-## Capabilities
-
-What you can do with the Framer CLI:
-
-- **Canvas Editing**: For design tasks — creating or editing pages, sections, layouts, recreating designs from screenshots, etc.
-- **CMS**: Create, read, update, delete collections and items. Sync external databases.
-- **Styles**: Manage color and text styles. Sync design systems.
-- **Code Components**: Create, edit, type-check, and add custom React components to the canvas.
-- **Assets**: Upload and manage images and files.
-- **Localization**: Manage translations programmatically.
-- **Data**: Store metadata on nodes and projects for plugin state.
-- **Screenshots**: Capture node screenshots as PNG/JPEG. Export nodes as SVG.
-- **Publishing**: Publish projects, manage deployments, track changes.
-
-## 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 `{{FRAMER_AGENT_COMMAND}}@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
-{{FRAMER_AGENT_COMMAND}}@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.
-
-Each session maintains a persistent connection to a Framer project. Use sessions to keep state separate between different tasks, persist data across multiple execute calls, and reuse the `framer` API instance without reconnecting.
-
-Create a session against an existing project:
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@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.
-
-To create a brand new empty project and connect to it:
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest project new
-{{FRAMER_AGENT_COMMAND}}@latest session new "<returned project id>"
-```
-
-To remix (duplicate) an existing project and connect to the copy:
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest project remix "<url, project id, or remix link>"
-{{FRAMER_AGENT_COMMAND}}@latest session new "<returned project id>"
-```
-
-List active sessions:
-
-```bash
-{{FRAMER_AGENT_COMMAND}}@latest session list
-```
-
-## Project-scoped skill
-
-**Always load the project-scoped skill `framer-project-<projectId>` immediately after `session new`, regardless of the task.** That skill is generated by `session new` and contains the documentation for everything you need to know about working with a Framer project.