@framer/agent 0.0.33 → 0.0.34

package/README.md

@@ -121,3 +121,17 @@ Usage will only consume your own agent's tokens.
 ### Why does this use so many tokens?
 
 Token consumption for Framer Agent can be relatively high. For other work like web development tasks, your agent already has a lot of knowledge baked into its model and so is able to get to work straight away. For Framer Agent, we need to first teach your AI how to interact with Framer projects and provide a lot of context. This requires a certain amount of token usage before being able to undertake the task at hand.
+
+### How do I get the latest releases if I have `min-release-age` set in my npm config?
+
+If your npm config delays new packages with `min-release-age`, you can make generated Framer Agent skills override that delay. This updates your installed skills immediately:
+
+```bash
+npx --min-release-age=0 @framer/agent@latest override-min-release-age enable
+```
+
+To restore your default npm behavior in generated skills:
+
+```bash
+npx @framer/agent@latest override-min-release-age disable
+```

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import fs7 from 'fs';
+import fs8 from 'fs';
 import path7 from 'path';
 import { Command } from 'commander';
 import crypto, { randomUUID } from 'crypto';
@@ -7,12 +7,13 @@ import http from 'http';
 import { spawn, execFile, execFileSync } from 'child_process';
 import { z } from 'zod';
 import os2 from 'os';
+import isWsl from 'is-wsl';
 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.33 */
+/* @framer/ai CLI v0.0.34 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
@@ -34,11 +35,12 @@ Please upgrade: https://nodejs.org/`
 var MAX_AGENT_THREAD_ID_LENGTH = 256;
 var MAX_AGENT_PROVIDER_LENGTH = 64;
 var SAFE_VALUE_PATTERN = /^[A-Za-z0-9._:-]+$/;
-var providerEnvVars = [
+var threadIdEnvVars = [
   { provider: "codex", envVar: "CODEX_THREAD_ID" },
   { provider: "claude", envVar: "CLAUDE_CODE_SESSION_ID" },
   { provider: "claude", envVar: "CLAUDE_CODE_REMOTE_SESSION_ID" }
 ];
+var providerPresenceEnvVars = [{ provider: "cursor", envVar: "CURSOR_AGENT" }];
 function normalizeValue(value, maxLength) {
   const trimmed = value?.trim();
   if (!trimmed) return void 0;
@@ -48,29 +50,38 @@ function normalizeValue(value, maxLength) {
 }
 __name(normalizeValue, "normalizeValue");
 function normalizeAgentThreadContext(input) {
+  const trimmedAgentThreadId = input.agentThreadId?.trim();
   const agentThreadId = normalizeValue(
     input.agentThreadId,
     MAX_AGENT_THREAD_ID_LENGTH
   );
-  if (!agentThreadId) return {};
+  if (trimmedAgentThreadId && !agentThreadId) return {};
   const agentProvider = normalizeValue(
     input.agentProvider,
     MAX_AGENT_PROVIDER_LENGTH
   );
+  if (!agentThreadId && !agentProvider) return {};
   return {
-    agentThreadId,
+    ...agentThreadId ? { agentThreadId } : {},
     ...agentProvider ? { agentProvider } : {}
   };
 }
 __name(normalizeAgentThreadContext, "normalizeAgentThreadContext");
 function resolveAgentThreadContext(env = process.env) {
-  for (const { provider, envVar } of providerEnvVars) {
+  for (const { provider, envVar } of threadIdEnvVars) {
     const agentThreadContext = normalizeAgentThreadContext({
       agentThreadId: env[envVar],
       agentProvider: provider
     });
     if (agentThreadContext.agentThreadId) return agentThreadContext;
   }
+  for (const { provider, envVar } of providerPresenceEnvVars) {
+    if (!env[envVar]?.trim()) continue;
+    const agentThreadContext = normalizeAgentThreadContext({
+      agentProvider: provider
+    });
+    if (agentThreadContext.agentProvider) return agentThreadContext;
+  }
   return {};
 }
 __name(resolveAgentThreadContext, "resolveAgentThreadContext");
@@ -107,7 +118,7 @@ function getConfigDir() {
 __name(getConfigDir, "getConfigDir");
 function ensureConfigDir() {
   const configDir = getConfigDir();
-  fs7.mkdirSync(configDir, { recursive: true, mode: 448 });
+  fs8.mkdirSync(configDir, { recursive: true, mode: 448 });
 }
 __name(ensureConfigDir, "ensureConfigDir");
 
@@ -135,7 +146,7 @@ var ProjectsConfigSchema = z.object({
 var LegacyCredentialsSchema = z.record(z.string(), z.string());
 function readJsonFile(filePath) {
   try {
-    return JSON.parse(fs7.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs8.readFileSync(filePath, "utf-8"));
   } catch (_error) {
     return null;
   }
@@ -143,7 +154,7 @@ function readJsonFile(filePath) {
 __name(readJsonFile, "readJsonFile");
 function writeProjectsConfig(config) {
   ensureConfigDir();
-  fs7.writeFileSync(
+  fs8.writeFileSync(
     getProjectsConfigPath(),
     JSON.stringify(config, null, "	"),
     {
@@ -170,7 +181,7 @@ function migrateLegacyCredentials() {
   }
   const config = { version: 2, projects };
   writeProjectsConfig(config);
-  fs7.rmSync(getLegacyCredentialsPath(), { force: true });
+  fs8.rmSync(getLegacyCredentialsPath(), { force: true });
   return config;
 }
 __name(migrateLegacyCredentials, "migrateLegacyCredentials");
@@ -183,7 +194,7 @@ function readProjectsConfig() {
       return result.data;
     }
   }
-  if (fs7.existsSync(getLegacyCredentialsPath())) {
+  if (fs8.existsSync(getLegacyCredentialsPath())) {
     return migrateLegacyCredentials();
   }
   return { version: 2, projects: {} };
@@ -266,7 +277,7 @@ var SettingsWatcher = class {
     __name(this, "SettingsWatcher");
   }
   start(callback) {
-    fs7.watchFile(
+    fs8.watchFile(
       this.settingsPath,
       { persistent: false, interval: fsPollIntervalMs },
       (curr, prev) => {
@@ -283,7 +294,7 @@ var SettingsWatcher = class {
     return this;
   }
   stop() {
-    fs7.unwatchFile(this.settingsPath);
+    fs8.unwatchFile(this.settingsPath);
     return this;
   }
 };
@@ -292,11 +303,13 @@ var SettingsWatcher = class {
 var DEFAULT_MACHINE_ID = "unknown-machine-id-this-should-never-be-persisted";
 var DEFAULT_SETTINGS = {
   machineId: DEFAULT_MACHINE_ID,
+  npxMinReleaseAgeOverrideEnabled: false,
   telemetryEnabled: true,
   telemetryNoticeShown: false
 };
 var SettingsFileSchema = z.object({
   machineId: z.string().optional(),
+  npxMinReleaseAgeOverrideEnabled: z.boolean().optional(),
   telemetryEnabled: z.boolean().optional(),
   telemetryNoticeShown: z.boolean().optional()
 });
@@ -320,10 +333,11 @@ __name(getSettings, "getSettings");
 function readSettingsFile() {
   const settingsPath = getSettingsPath();
   try {
-    const raw = JSON.parse(fs7.readFileSync(settingsPath, "utf-8"));
+    const raw = JSON.parse(fs8.readFileSync(settingsPath, "utf-8"));
     const result = SettingsFileSchema.parse(raw);
     return {
       machineId: result.machineId ?? DEFAULT_SETTINGS.machineId,
+      npxMinReleaseAgeOverrideEnabled: result.npxMinReleaseAgeOverrideEnabled ?? DEFAULT_SETTINGS.npxMinReleaseAgeOverrideEnabled,
       telemetryEnabled: result.telemetryEnabled ?? DEFAULT_SETTINGS.telemetryEnabled,
       telemetryNoticeShown: result.telemetryNoticeShown ?? DEFAULT_SETTINGS.telemetryNoticeShown
     };
@@ -339,7 +353,7 @@ function setSettings(newSettings) {
 __name(setSettings, "setSettings");
 function writeSettingsFile(settings2) {
   ensureConfigDir();
-  fs7.writeFileSync(getSettingsPath(), JSON.stringify(settings2, null, "	"), {
+  fs8.writeFileSync(getSettingsPath(), JSON.stringify(settings2, null, "	"), {
     mode: 384
   });
 }
@@ -353,6 +367,15 @@ function getMachineId() {
   return getSettings().machineId;
 }
 __name(getMachineId, "getMachineId");
+function isNpxMinReleaseAgeOverrideEnabled() {
+  return getSettings().npxMinReleaseAgeOverrideEnabled;
+}
+__name(isNpxMinReleaseAgeOverrideEnabled, "isNpxMinReleaseAgeOverrideEnabled");
+function setNpxMinReleaseAgeOverrideEnabled(enabled2) {
+  const settings2 = getSettings();
+  setSettings({ ...settings2, npxMinReleaseAgeOverrideEnabled: enabled2 });
+}
+__name(setNpxMinReleaseAgeOverrideEnabled, "setNpxMinReleaseAgeOverrideEnabled");
 function isTelemetryEnabled() {
   return getSettings().telemetryEnabled;
 }
@@ -375,7 +398,7 @@ __name(markTelemetryNoticeShown, "markTelemetryNoticeShown");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.33" 
+  "0.0.34" 
 );
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
@@ -405,8 +428,27 @@ function getMacOsVersion() {
   }
 }
 __name(getMacOsVersion, "getMacOsVersion");
+function parseOsReleaseValue(content, key) {
+  const line = content.split("\n").find((candidate) => candidate.startsWith(`${key}=`));
+  const value = line?.slice(key.length + 1).trim();
+  if (!value) return void 0;
+  return value.replace(/^"|"$/g, "") || void 0;
+}
+__name(parseOsReleaseValue, "parseOsReleaseValue");
+function getLinuxOsVersion() {
+  let version;
+  try {
+    const osRelease = fs8.readFileSync("/etc/os-release", "utf8");
+    version = parseOsReleaseValue(osRelease, "PRETTY_NAME") ?? "unknown";
+  } catch {
+    version = os2.release().trim() || "unknown";
+  }
+  return isWsl ? `${version} wsl` : version;
+}
+__name(getLinuxOsVersion, "getLinuxOsVersion");
 function getOsVersion(platform) {
   if (platform === "darwin") return getMacOsVersion();
+  if (platform === "linux") return getLinuxOsVersion();
   const version = os2.release().trim();
   return version || "unknown";
 }
@@ -654,6 +696,7 @@ var themes = {
 };
 function htmlPage(opts) {
   const t = themes[opts.theme];
+  const footer = opts.action ? `<div class="footer"><a href="${opts.action.href}">${opts.action.label}</a></div>` : "";
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -670,26 +713,28 @@ body{font-family:"Inter",system-ui,-apple-system,sans-serif;font-feature-setting
 .header{display:flex;align-items:center;height:50px;border-bottom:1px solid ${t.separatorColor};color:${t.titleColor};font-size:12px;font-weight:600;line-height:1}
 .content{padding:10px 0}
 .text{color:${t.textColor};font-size:12px;font-weight:500;line-height:1.5;text-wrap:balance}
-.footer{padding:10px 0;border-top:1px solid ${t.separatorColor}}
-.footer button{display:block;width:100%;height:30px;border:none;border-radius:8px;background:${t.buttonBackground};color:${t.buttonText};font-size:12px;font-weight:600;cursor:pointer;font-family:inherit}
-.footer button:hover{background:${t.buttonBackgroundHover}}
+.footer{padding:0 0 10px}
+.footer a{display:block;width:100%;height:30px;border:none;border-radius:8px;background:${t.buttonBackground};color:${t.buttonText};font-size:12px;font-weight:600;line-height:30px;text-align:center;cursor:pointer;font-family:inherit;text-decoration:none}
+.footer a:hover{background:${t.buttonBackgroundHover}}
 </style>
 </head>
 <body>
 <div class="modal">
 <div class="header">${opts.heading}</div>
 <div class="content"><span class="text">${opts.message}</span></div>
+${footer}
 </div>
 </body>
 </html>`;
 }
 __name(htmlPage, "htmlPage");
-function successHtml(theme, message) {
+function successHtml(theme, message, action) {
   return htmlPage({
     title: "Framer \u2014 Agent Approved",
     heading: "Agent Approved",
     message: message ?? "Your external agent now has edit access to the project. You can close this tab and continue with the external agent.",
-    theme
+    theme,
+    action
   });
 }
 __name(successHtml, "successHtml");
@@ -729,12 +774,18 @@ __name(isFramerHostname, "isFramerHostname");
 function resolveProjectOrigin(projectUrlOrId) {
   try {
     const url = new URL(projectUrlOrId);
-    if (isFramerHostname(url.hostname.toLowerCase())) return url.origin;
+    if (url.protocol === "https:" && isFramerHostname(url.hostname.toLowerCase())) {
+      return url.origin;
+    }
   } catch {
   }
   return "https://framer.com";
 }
 __name(resolveProjectOrigin, "resolveProjectOrigin");
+function projectUrl(projectOrigin, projectId) {
+  return new URL(`/projects/${encodeURIComponent(projectId)}`, projectOrigin).href;
+}
+__name(projectUrl, "projectUrl");
 function runBrowserAuthFlow(options) {
   const {
     deeplinkParams,
@@ -762,8 +813,13 @@ function runBrowserAuthFlow(options) {
       debug("auth", `request: ${url.pathname}`);
       if (url.pathname === "/done") {
         const theme2 = parseTheme(url.searchParams.get("theme"));
+        const projectId = pendingAuth?.projectId ?? pollProjectId;
+        const action = projectId ? {
+          label: "Open Project",
+          href: projectUrl(projectOrigin, projectId)
+        } : void 0;
         res.writeHead(200, { "Content-Type": "text/html" });
-        res.end(successHtml(theme2, browserSuccessMessage), () => {
+        res.end(successHtml(theme2, browserSuccessMessage, action), () => {
           if (pendingAuth) {
             const auth = pendingAuth;
             pendingAuth = null;
@@ -1112,11 +1168,14 @@ var types = {
     name: "AgentBranchChange",
     description: "",
     kind: "interface",
-    references: ["AgentBranchCollectionItemChange"],
+    references: [
+      "AgentBranchCollectionItemChange",
+      "AgentBranchChangeSettingsTab"
+    ],
     members: [
       {
         name: "type",
-        type: '"page" | "collection" | "designPage" | "siteSettings" | "component" | "layoutTemplate"',
+        type: '"page" | "collection" | "designPage" | "siteSettings" | "component" | "layoutTemplate" | "vectorSet" | "codeFile"',
         description: "",
         optional: false
       },
@@ -1146,12 +1205,19 @@ var types = {
       },
       {
         name: "settingsTab",
-        type: '"general" | "redirects"',
+        type: "AgentBranchChangeSettingsTab",
         description: "",
         optional: true
       }
     ]
   },
+  agentbranchchangesettingstab: {
+    name: "AgentBranchChangeSettingsTab",
+    description: "",
+    kind: "alias",
+    alias: '"general" | "redirects" | "customCode"',
+    references: []
+  },
   agentbranchcollectionitemchange: {
     name: "AgentBranchCollectionItemChange",
     description: "",
@@ -7558,7 +7624,7 @@ var types = {
       },
       {
         name: "applyAgentChanges",
-        type: "(dsl: string, options?: {\n        pagePath?: string;\n    }) => Promise<void>",
+        type: "(dsl: string, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
         description: "@alpha",
         optional: false
       },
@@ -14123,8 +14189,8 @@ var methodsByCategory = {
     {
       name: "applyChanges",
       category: "FramerAgentAPI",
-      signature: "applyChanges(dsl: string, options?: { pagePath?: string; }): Promise<void>",
-      description: 'Applies commands to the canvas to create, update, remove, move, or duplicate nodes.\n\nThe command syntax is documented in the string returned by {@link getSystemPrompt}.\nEach call is scoped to a single page.\n\n@param dsl - A string of commands separated by `;`. See {@link getSystemPrompt} for syntax.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.',
+      signature: "applyChanges(dsl: string, options?: { pagePath?: string; }): Promise<unknown>",
+      description: 'Applies commands to the canvas to create, update, remove, move, or duplicate nodes.\n\nThe command syntax is documented in the string returned by {@link getSystemPrompt}.\nEach call is scoped to a single page.\n\nCommands that fail (including syntax errors) are reported in the result\'s `errors`\nwithout blocking the remaining commands. Errors returned here are not repeated by\n{@link reviewChanges}, which reports the remaining project diagnostics.\n\nThe result schema is documented in the string returned by {@link getSystemPrompt}.\n\n@param dsl - A string of commands separated by `;`. See {@link getSystemPrompt} for syntax.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The per-command status and errors, and the canonical system ids of created nodes.',
       references: []
     },
     {
@@ -14334,7 +14400,7 @@ var methodsByCategory = {
       name: "reviewChanges",
       category: "FramerAgentAPI",
       signature: "reviewChanges(): Promise<unknown>",
-      description: "Reviews changes made by prior {@link applyChanges} calls in this session.\n\nConsumes accumulated diagnostics from the session's agent context.\n\n@returns The session's accumulated changes, errors, warnings, and deferred trait reports.",
+      description: "Reviews changes made by prior {@link applyChanges} calls in this session.\n\nConsumes accumulated diagnostics from the session's agent context. Command errors\nalready returned by {@link applyChanges} are not repeated here.\n\n@returns The session's accumulated changes, errors, warnings, and deferred trait reports.",
       references: []
     },
     {
@@ -16576,8 +16642,8 @@ function createProjectBaseUrl(origin) {
 __name(createProjectBaseUrl, "createProjectBaseUrl");
 function inferHeadlessServerUrl(projectUrlOrId) {
   try {
-    const projectUrl = new URL(projectUrlOrId);
-    const hostname = projectUrl.hostname.toLowerCase();
+    const projectUrl2 = new URL(projectUrlOrId);
+    const hostname = projectUrl2.hostname.toLowerCase();
     if (hostname === "development.framer.com") {
       return DEV_HEADLESS_SERVER_URL;
     }
@@ -16585,7 +16651,7 @@ function inferHeadlessServerUrl(projectUrlOrId) {
       const headlessServerUrl = new URL(PROD_HEADLESS_SERVER_URL);
       headlessServerUrl.searchParams.set(
         "baseUrl",
-        createProjectBaseUrl(projectUrl.origin)
+        createProjectBaseUrl(projectUrl2.origin)
       );
       return headlessServerUrl.toString();
     }
@@ -16593,7 +16659,7 @@ function inferHeadlessServerUrl(projectUrlOrId) {
       const headlessServerUrl = new URL(DEV_HEADLESS_SERVER_URL);
       headlessServerUrl.searchParams.set(
         "baseUrl",
-        createProjectBaseUrl(projectUrl.origin)
+        createProjectBaseUrl(projectUrl2.origin)
       );
       return headlessServerUrl.toString();
     }
@@ -16609,7 +16675,7 @@ function getRelayTokenPath() {
 __name(getRelayTokenPath, "getRelayTokenPath");
 function readRelayToken() {
   try {
-    const token = fs7.readFileSync(getRelayTokenPath(), "utf-8").trim();
+    const token = fs8.readFileSync(getRelayTokenPath(), "utf-8").trim();
     return token.length > 0 ? token : null;
   } catch {
     return null;
@@ -16783,17 +16849,17 @@ async function waitForClaudeCodeSkillDiscovery() {
 __name(waitForClaudeCodeSkillDiscovery, "waitForClaudeCodeSkillDiscovery");
 var FRAMER_TEMPORARY_DIR = path7.join(os2.tmpdir(), "framer");
 function ensureTemporaryDir() {
-  fs7.mkdirSync(FRAMER_TEMPORARY_DIR, { recursive: true });
+  fs8.mkdirSync(FRAMER_TEMPORARY_DIR, { recursive: true });
 }
 __name(ensureTemporaryDir, "ensureTemporaryDir");
 function cleanupStaleSessionCodeFiles(activeSessionIds) {
-  if (!fs7.existsSync(FRAMER_TEMPORARY_DIR)) return;
+  if (!fs8.existsSync(FRAMER_TEMPORARY_DIR)) return;
   const activeSessionIdsSet = new Set(activeSessionIds);
-  for (const entry of fs7.readdirSync(FRAMER_TEMPORARY_DIR)) {
+  for (const entry of fs8.readdirSync(FRAMER_TEMPORARY_DIR)) {
     const [sessionId] = entry.split("-");
     if (activeSessionIdsSet.has(sessionId)) continue;
     const filePath = path7.join(FRAMER_TEMPORARY_DIR, entry);
-    fs7.rmSync(filePath, { recursive: true, force: true, maxRetries: 2 });
+    fs8.rmSync(filePath, { recursive: true, force: true, maxRetries: 2 });
   }
 }
 __name(cleanupStaleSessionCodeFiles, "cleanupStaleSessionCodeFiles");
@@ -16804,12 +16870,16 @@ var CODE_COMPONENTS_SKILL_NAME = "framer-code-components";
 var __dirname2 = path7.dirname(fileURLToPath(import.meta.url));
 var skillsDocsDir = path7.join(__dirname2, "..", "docs", "skills");
 function readSkillDoc(name2) {
-  return fs7.readFileSync(path7.join(skillsDocsDir, name2), "utf-8").trimEnd();
+  return fs8.readFileSync(path7.join(skillsDocsDir, name2), "utf-8").trimEnd();
 }
 __name(readSkillDoc, "readSkillDoc");
 function buildMetaSkill() {
+  const command = getFramerAgentCommand();
   const template = readSkillDoc("framer.md");
-  return `${renderTemplate(template, { FRAMER_TEMPORARY_DIR })}
+  return `${renderTemplate(template, {
+    FRAMER_TEMPORARY_DIR,
+    FRAMER_AGENT_COMMAND: command
+  })}
 `;
 }
 __name(buildMetaSkill, "buildMetaSkill");
@@ -16828,49 +16898,58 @@ function renderTemplate(template, values) {
 __name(renderTemplate, "renderTemplate");
 var PROJECT_SKILL_PREFIX = "framer-project-";
 var LEGACY_CANVAS_EDITING_SKILL_PREFIX = "framer-canvas-editing-project-";
+var PACKAGE_NAME = "@framer/agent";
+var DEFAULT_FRAMER_AGENT_COMMAND = `npx ${PACKAGE_NAME}`;
+var RELEASE_AGE_OVERRIDE_FRAMER_AGENT_COMMAND = `npx --min-release-age=0 ${PACKAGE_NAME}`;
+function getFramerAgentCommand() {
+  return isNpxMinReleaseAgeOverrideEnabled() ? RELEASE_AGE_OVERRIDE_FRAMER_AGENT_COMMAND : DEFAULT_FRAMER_AGENT_COMMAND;
+}
+__name(getFramerAgentCommand, "getFramerAgentCommand");
 function toSafeProjectId(projectId) {
   return projectId.replace(/[^a-zA-Z0-9_-]/g, "-");
 }
 __name(toSafeProjectId, "toSafeProjectId");
 function buildProjectSkill(projectId, agentContext, agentPrompt) {
+  const command = getFramerAgentCommand();
   const skillName = `${PROJECT_SKILL_PREFIX}${toSafeProjectId(projectId)}`;
   const template = readSkillDoc("framer-project.md");
   const content = `${renderTemplate(template, {
     SKILL_NAME: skillName,
     PROJECT_ID: projectId,
     GENERATED_AT: (/* @__PURE__ */ new Date()).toISOString(),
-    AGENT_PROMPT: agentPrompt.trimEnd(),
-    AGENT_CONTEXT: agentContext.trimEnd(),
-    FRAMER_TEMPORARY_DIR
+    AGENT_PROMPT: agentPrompt.trimEnd().replaceAll(DEFAULT_FRAMER_AGENT_COMMAND, command),
+    AGENT_CONTEXT: agentContext.trimEnd().replaceAll(DEFAULT_FRAMER_AGENT_COMMAND, command),
+    FRAMER_TEMPORARY_DIR,
+    FRAMER_AGENT_COMMAND: command
   })}
 `;
   return { skillName, content };
 }
 __name(buildProjectSkill, "buildProjectSkill");
 function writeSkill(root, skillName, content) {
-  fs7.mkdirSync(root, { recursive: true });
-  const rootStat = fs7.statSync(root);
+  fs8.mkdirSync(root, { recursive: true });
+  const rootStat = fs8.statSync(root);
   if (!rootStat.isDirectory()) {
     throw new Error(`Skill root is not a directory: ${root}`);
   }
   const skillDir = path7.join(root, skillName);
   const filePath = path7.join(skillDir, "SKILL.md");
-  const current = fs7.lstatSync(skillDir, { throwIfNoEntry: false });
+  const current = fs8.lstatSync(skillDir, { throwIfNoEntry: false });
   if (current && (current.isSymbolicLink() || !current.isDirectory())) {
-    fs7.rmSync(skillDir, { recursive: true, force: true });
+    fs8.rmSync(skillDir, { recursive: true, force: true });
   }
-  fs7.mkdirSync(skillDir, { recursive: true });
-  fs7.writeFileSync(filePath, content, "utf-8");
+  fs8.mkdirSync(skillDir, { recursive: true });
+  fs8.writeFileSync(filePath, content, "utf-8");
   return filePath;
 }
 __name(writeSkill, "writeSkill");
 function cleanupLegacyCanvasEditingSkills(skillRoots = getDefaultSkillRoots()) {
   for (const root of skillRoots) {
-    if (!fs7.existsSync(root)) continue;
-    for (const entry of fs7.readdirSync(root)) {
+    if (!fs8.existsSync(root)) continue;
+    for (const entry of fs8.readdirSync(root)) {
       if (!entry.startsWith(LEGACY_CANVAS_EDITING_SKILL_PREFIX)) continue;
       const skillDir = path7.join(root, entry);
-      fs7.rmSync(skillDir, { recursive: true, force: true, maxRetries: 2 });
+      fs8.rmSync(skillDir, { recursive: true, force: true, maxRetries: 2 });
     }
   }
 }
@@ -16888,14 +16967,14 @@ function cleanupStaleSkills(activeProjectIds, skillRoots = getDefaultSkillRoots(
     [...activeProjectIds].map(toSafeProjectId)
   );
   for (const root of skillRoots) {
-    if (!fs7.existsSync(root)) continue;
-    for (const entry of fs7.readdirSync(root)) {
+    if (!fs8.existsSync(root)) continue;
+    for (const entry of fs8.readdirSync(root)) {
       if (!entry.startsWith(PROJECT_SKILL_PREFIX)) continue;
       const sanitizedProjectId = entry.slice(PROJECT_SKILL_PREFIX.length);
       const isActive = sanitizedActiveProjectIds.has(sanitizedProjectId);
       if (isActive) continue;
       const skillDir = path7.join(root, entry);
-      fs7.rmSync(skillDir, { recursive: true, force: true, maxRetries: 2 });
+      fs8.rmSync(skillDir, { recursive: true, force: true, maxRetries: 2 });
     }
   }
 }
@@ -16981,6 +17060,19 @@ function printTelemetryNotice() {
   markTelemetryNoticeShown();
 }
 __name(printTelemetryNotice, "printTelemetryNotice");
+async function installBaseSkills() {
+  try {
+    cleanupLegacyCanvasEditingSkills();
+  } catch (error) {
+    printWarning(
+      `Failed to clean up legacy canvas editing skills: ${formatErrorForUser(error)}`
+    );
+  }
+  const results = installSkills();
+  await waitForClaudeCodeSkillDiscovery();
+  return results;
+}
+__name(installBaseSkills, "installBaseSkills");
 async function getAgentSystemPrompt(sessionId) {
   debug("exec", "getAgentSystemPrompt: calling relay...");
   const result = await client.exec.mutate({
@@ -17137,7 +17229,7 @@ program.command("exec").description("Execute code in a session").requiredOption(
   let code = evalCode;
   if (!code && filePath) {
     try {
-      code = fs7.readFileSync(filePath, "utf-8");
+      code = fs8.readFileSync(filePath, "utf-8");
     } catch (err) {
       printError(`Failed to read file: ${formatErrorForUser(err)}`);
       await waitForTrackingToFinish();
@@ -17401,15 +17493,7 @@ program.command("setup").description(
   "Install Framer skills into ~/.agents/skills and ~/.claude/skills"
 ).action(async () => {
   try {
-    try {
-      cleanupLegacyCanvasEditingSkills();
-    } catch (error) {
-      printWarning(
-        `Failed to clean up legacy canvas editing skills: ${formatErrorForUser(error)}`
-      );
-    }
-    const results = installSkills();
-    await waitForClaudeCodeSkillDiscovery();
+    const results = await installBaseSkills();
     printSetupSummary(results);
     printTelemetryNotice();
   } catch (err) {
@@ -17441,4 +17525,48 @@ telemetry.command("disable").description("Disable telemetry").action(() => {
 telemetry.command("status").description("Show current telemetry status").action(() => {
   print(`Telemetry is ${isTelemetryEnabled() ? "enabled" : "disabled"}`);
 });
+var overrideMinReleaseAge = program.command("override-min-release-age").description("Configure generated skills to override npm min-release-age");
+overrideMinReleaseAge.command("enable").description("Override npm min-release-age for generated Framer npx commands").action(async () => {
+  try {
+    setNpxMinReleaseAgeOverrideEnabled(true);
+    print(
+      "Generated Framer skills will use `npx --min-release-age=0 @framer/agent`."
+    );
+    const results = await installBaseSkills();
+    printSetupSummary(results);
+  } catch (err) {
+    printError(
+      `Failed to enable min-release-age override: ${formatErrorForUser(err)}`
+    );
+    await waitForTrackingToFinish();
+    process.exit(1);
+  }
+});
+overrideMinReleaseAge.command("disable").description("Use the default npm min-release-age for generated npx commands").action(async () => {
+  try {
+    setNpxMinReleaseAgeOverrideEnabled(false);
+    print(
+      "Generated Framer skills will use the default npm min-release-age."
+    );
+    const results = await installBaseSkills();
+    printSetupSummary(results);
+  } catch (err) {
+    printError(
+      `Failed to disable min-release-age override: ${formatErrorForUser(err)}`
+    );
+    await waitForTrackingToFinish();
+    process.exit(1);
+  }
+});
+overrideMinReleaseAge.command("status").description("Show current npm min-release-age override status").action(() => {
+  if (isNpxMinReleaseAgeOverrideEnabled()) {
+    print(
+      "npm min-release-age override is enabled for generated Framer skills."
+    );
+    return;
+  }
+  print(
+    "npm min-release-age override is disabled for generated Framer skills."
+  );
+});
 program.parse();

package/dist/start-relay-server.js

@@ -13,8 +13,9 @@ import { connect, FramerAPIError } from 'framer-api';
 import { z } from 'zod';
 import { createRequire } from 'module';
 import * as vm from 'vm';
+import isWsl from 'is-wsl';
 
-/* @framer/ai relay server v0.0.33 */
+/* @framer/ai relay server v0.0.34 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -199,7 +200,7 @@ __name(debug, "debug");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.33" 
+  "0.0.34" 
 );
 
 // src/relay-client.ts
@@ -234,17 +235,19 @@ function normalizeValue(value, maxLength) {
 }
 __name(normalizeValue, "normalizeValue");
 function normalizeAgentThreadContext(input) {
+  const trimmedAgentThreadId = input.agentThreadId?.trim();
   const agentThreadId = normalizeValue(
     input.agentThreadId,
     MAX_AGENT_THREAD_ID_LENGTH
   );
-  if (!agentThreadId) return {};
+  if (trimmedAgentThreadId && !agentThreadId) return {};
   const agentProvider = normalizeValue(
     input.agentProvider,
     MAX_AGENT_PROVIDER_LENGTH
   );
+  if (!agentThreadId && !agentProvider) return {};
   return {
-    agentThreadId,
+    ...agentThreadId ? { agentThreadId } : {},
     ...agentProvider ? { agentProvider } : {}
   };
 }
@@ -842,11 +845,13 @@ var SettingsWatcher = class {
 var DEFAULT_MACHINE_ID = "unknown-machine-id-this-should-never-be-persisted";
 var DEFAULT_SETTINGS = {
   machineId: DEFAULT_MACHINE_ID,
+  npxMinReleaseAgeOverrideEnabled: false,
   telemetryEnabled: true,
   telemetryNoticeShown: false
 };
 var SettingsFileSchema = z.object({
   machineId: z.string().optional(),
+  npxMinReleaseAgeOverrideEnabled: z.boolean().optional(),
   telemetryEnabled: z.boolean().optional(),
   telemetryNoticeShown: z.boolean().optional()
 });
@@ -874,6 +879,7 @@ function readSettingsFile() {
     const result = SettingsFileSchema.parse(raw);
     return {
       machineId: result.machineId ?? DEFAULT_SETTINGS.machineId,
+      npxMinReleaseAgeOverrideEnabled: result.npxMinReleaseAgeOverrideEnabled ?? DEFAULT_SETTINGS.npxMinReleaseAgeOverrideEnabled,
       telemetryEnabled: result.telemetryEnabled ?? DEFAULT_SETTINGS.telemetryEnabled,
       telemetryNoticeShown: result.telemetryNoticeShown ?? DEFAULT_SETTINGS.telemetryNoticeShown
     };
@@ -935,8 +941,27 @@ function getMacOsVersion() {
   }
 }
 __name(getMacOsVersion, "getMacOsVersion");
+function parseOsReleaseValue(content, key) {
+  const line = content.split("\n").find((candidate) => candidate.startsWith(`${key}=`));
+  const value = line?.slice(key.length + 1).trim();
+  if (!value) return void 0;
+  return value.replace(/^"|"$/g, "") || void 0;
+}
+__name(parseOsReleaseValue, "parseOsReleaseValue");
+function getLinuxOsVersion() {
+  let version;
+  try {
+    const osRelease = fs4.readFileSync("/etc/os-release", "utf8");
+    version = parseOsReleaseValue(osRelease, "PRETTY_NAME") ?? "unknown";
+  } catch {
+    version = os5.release().trim() || "unknown";
+  }
+  return isWsl ? `${version} wsl` : version;
+}
+__name(getLinuxOsVersion, "getLinuxOsVersion");
 function getOsVersion(platform) {
   if (platform === "darwin") return getMacOsVersion();
+  if (platform === "linux") return getLinuxOsVersion();
   const version = os5.release().trim();
   return version || "unknown";
 }
@@ -1106,22 +1131,20 @@ var SESSION_IDLE_TIMEOUT_MS = 60 * 1e3;
 var SESSION_IDLE_CHECK_INTERVAL_MS = 30 * 1e3;
 var MISSING_SERVER_SESSION_ID = "missing-session-id-should-not-happen";
 var Connection = class _Connection {
-  constructor(projectId, userId, apiKey, headlessServerUrl, framer) {
+  constructor(projectId, userId, headlessServerUrl, framer) {
     this.projectId = projectId;
     this.userId = userId;
-    this.apiKey = apiKey;
     this.headlessServerUrl = headlessServerUrl;
     this.framer = framer;
   }
   projectId;
   userId;
-  apiKey;
   headlessServerUrl;
   framer;
   static {
     __name(this, "Connection");
   }
-  sessions = [];
+  session;
   status = "connected";
   pendingReconnect;
   activeBranchId;
@@ -1130,7 +1153,7 @@ var Connection = class _Connection {
       clientId: `dalton/${VERSION}`,
       serverUrl: headlessServerUrl
     });
-    return new _Connection(projectId, userId, apiKey, headlessServerUrl, framer);
+    return new _Connection(projectId, userId, headlessServerUrl, framer);
   }
   isConnected() {
     return this.status === "connected";
@@ -1144,15 +1167,19 @@ var Connection = class _Connection {
   getServerSessionId() {
     return this.framer.sessionId ?? MISSING_SERVER_SESSION_ID;
   }
-  listSessionInfo() {
-    return this.sessions.map((session) => ({
-      id: session.id,
+  getSessionInfo() {
+    if (!this.session) return void 0;
+    return {
+      id: this.session.id,
       projectId: this.projectId,
-      stateKeys: Object.keys(session.state),
+      stateKeys: Object.keys(this.session.state),
       headlessServerUrl: this.headlessServerUrl
-    }));
+    };
   }
   createSession(id, agentThreadContext) {
+    if (this.session) {
+      throw new Error("Connection already has a session");
+    }
     const session = {
       id,
       state: {},
@@ -1161,28 +1188,17 @@ var Connection = class _Connection {
       inflight: 0,
       connection: this
     };
-    this.sessions.push(session);
+    this.session = session;
     return session;
   }
   findSession(id) {
-    return this.sessions.find((session) => session.id === id);
-  }
-  removeSession(id) {
-    const index = this.sessions.findIndex((session) => session.id === id);
-    if (index >= 0) {
-      this.sessions.splice(index, 1);
-    }
+    return this.session?.id === id ? this.session : void 0;
   }
-  hasSessions() {
-    return this.sessions.length > 0;
-  }
-  clearSessions() {
-    this.sessions.length = 0;
+  clearSession() {
+    this.session = void 0;
   }
   isIdle(now, timeoutMs) {
-    return this.sessions.every(
-      (session) => session.inflight === 0 && now - session.lastActivityAt >= timeoutMs
-    );
+    return this.session !== void 0 && this.session.inflight === 0 && now - this.session.lastActivityAt >= timeoutMs;
   }
   async reconnect(expectedInitialBranchId = this.activeBranchId) {
     if (this.status === "connected") {
@@ -1228,7 +1244,7 @@ var SessionManager = class {
   connections = [];
   idleCheck = null;
   async create(projectId, userId, apiKey, headlessServerUrl, agentThreadContext = {}) {
-    const connection = await this.findOrCreateConnection(
+    const connection = await Connection.open(
       projectId,
       userId,
       apiKey,
@@ -1238,13 +1254,23 @@ var SessionManager = class {
       this.getNextSessionId(),
       agentThreadContext
     );
+    trackConnectionAcquire({
+      projectId,
+      userId: connection.userId,
+      sessionId: connection.getServerSessionId(),
+      isReuse: false
+    });
+    this.connections.push(connection);
     this.startIdleCheck();
     return session;
   }
   list() {
-    return this.connections.flatMap(
-      (connection) => connection.listSessionInfo()
-    );
+    const sessions = [];
+    for (const connection of this.connections) {
+      const sessionInfo = connection.getSessionInfo();
+      if (sessionInfo) sessions.push(sessionInfo);
+    }
+    return sessions;
   }
   get(id) {
     return this.findSession(id);
@@ -1305,30 +1331,29 @@ var SessionManager = class {
     if (!session) {
       return;
     }
+    const connection = session.connection;
+    await connection.disconnect();
+    connection.clearSession();
+    const index = this.connections.indexOf(connection);
+    if (index >= 0) {
+      this.connections.splice(index, 1);
+    }
+    if (this.connections.length === 0) {
+      this.stopIdleCheck();
+    }
     trackSessionDestroy({
       projectId: session.connection.projectId,
       userId: session.connection.userId,
       sessionId: session.connection.getServerSessionId(),
       ...session.agentThreadContext
     });
-    session.connection.removeSession(id);
-    if (!session.connection.hasSessions()) {
-      await session.connection.disconnect();
-      const index = this.connections.indexOf(session.connection);
-      if (index >= 0) {
-        this.connections.splice(index, 1);
-      }
-    }
-    if (this.connections.length === 0) {
-      this.stopIdleCheck();
-    }
   }
   async destroyAll() {
     const connections = [...this.connections];
     this.connections = [];
     this.stopIdleCheck();
     for (const connection of connections) {
-      connection.clearSessions();
+      connection.clearSession();
       await connection.disconnect();
     }
   }
@@ -1385,42 +1410,6 @@ var SessionManager = class {
       }
     }
   }
-  findConnection(projectId, apiKey, headlessServerUrl) {
-    return this.connections.find(
-      (connection) => connection.projectId === projectId && connection.apiKey === apiKey && connection.headlessServerUrl === headlessServerUrl
-    );
-  }
-  async findOrCreateConnection(projectId, userId, apiKey, headlessServerUrl) {
-    const existingConnection = this.findConnection(
-      projectId,
-      apiKey,
-      headlessServerUrl
-    );
-    if (existingConnection) {
-      await existingConnection.reconnect();
-      trackConnectionAcquire({
-        projectId,
-        userId: existingConnection.userId,
-        sessionId: existingConnection.getServerSessionId(),
-        isReuse: true
-      });
-      return existingConnection;
-    }
-    const connection = await Connection.open(
-      projectId,
-      userId,
-      apiKey,
-      headlessServerUrl
-    );
-    trackConnectionAcquire({
-      projectId,
-      userId: connection.userId,
-      sessionId: connection.getServerSessionId(),
-      isReuse: false
-    });
-    this.connections.push(connection);
-    return connection;
-  }
   findSession(id) {
     for (const connection of this.connections) {
       const session = connection.findSession(id);

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/agent:*)", "Bash(npx @framer/agent@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+allowed-tools: ["Bash({{FRAMER_AGENT_COMMAND}}:*)", "Bash({{FRAMER_AGENT_COMMAND}}@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/agent@latest docs` before writing any code.** Do not guess method names or signatures.
+**You MUST run `{{FRAMER_AGENT_COMMAND}}@latest docs` before writing any code.** Do not guess method names or signatures.
 
 ```bash
-npx @framer/agent@latest docs Collection           # What methods exist?
-npx @framer/agent@latest docs Collection.getItems  # What are the parameters and return type?
+{{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
@@ -27,7 +27,7 @@ npx @framer/agent@latest docs Collection.getItems  # What are the parameters and
 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/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
+{{FRAMER_AGENT_COMMAND}}@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
 ```
 
 ### 3. Store results in `state`
@@ -38,10 +38,10 @@ Always save results you'll need again. Don't repeat API calls.
 
 Prefer the agent-specific methods `framer.agent.*` over regular plugin API methods (`framer.*`).
 
-For `framer.agent.readProject` and `framer.agent.applyChanges` calls, use the `npx @framer/agent@latest read-project` and `npx @framer/agent@latest apply-changes` subcommands when possible. It's still ok to call those methods in exec scripts if you require something more complex than a plain method call.
+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 `npx @framer/agent@latest read-project` or `framer.agent.readProject` for node tree reads unless you have just checked current docs and confirmed the exact query type. Query shapes such as `{ type: "node-by-id" }` are not valid for the current local API.
+- 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.
@@ -87,7 +87,7 @@ state.collections = await framer.getCollections();
 ```
 
 ```bash
-npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
+{{FRAMER_AGENT_COMMAND}}@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
 ```
 
 ```js
@@ -97,7 +97,7 @@ console.log(state.teamItems.length);
 ```
 
 ```bash
-npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
+{{FRAMER_AGENT_COMMAND}}@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
 ```
 
 Store anything you'll reference again.
@@ -141,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/agent@latest exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
+{{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.
@@ -154,24 +154,24 @@ In Windows PowerShell, if an argument contains nested quotes, use a single-quote
 $value = @'
 [{"key":"value","filter":["text","$rect"]}]
 '@
-npx @framer/agent@latest <command> --option $value
+{{FRAMER_AGENT_COMMAND}}@latest <command> --option $value
 ```
 
 ## API Documentation
 
 ```bash
-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
+{{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 `npx @framer/agent@latest docs <ClassName>` to verify the current signature.**
+**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)
 

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/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}}/*)"]
+  **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
-npx @framer/agent@latest setup
+{{FRAMER_AGENT_COMMAND}}@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/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.
+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
-npx @framer/agent@latest project list
+{{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.
@@ -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/agent@latest session new "<url or id>"
+{{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.
@@ -54,21 +54,21 @@ 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/agent@latest project new
-npx @framer/agent@latest session new "<returned project id>"
+{{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
-npx @framer/agent@latest project remix "<url, project id, or remix link>"
-npx @framer/agent@latest session new "<returned project id>"
+{{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
-npx @framer/agent@latest session list
+{{FRAMER_AGENT_COMMAND}}@latest session list
 ```
 
 ## Project-scoped skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framer/agent",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -24,15 +24,16 @@
     "@trpc/client": "^11.17.0",
     "@trpc/server": "^11.17.0",
     "commander": "^12.1.0",
-    "framer-api": "^0.1.16",
+    "framer-api": "^0.1.17",
+    "is-wsl": "^3.1.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
-    "@framerjs/framer-events": "0.0.185",
+    "@framerjs/framer-events": "0.0.187",
     "@types/node": "24.13.0",
     "tsup": "^8.0.2",
-    "tsx": "^4.22.3",
+    "tsx": "^4.22.4",
     "typescript": "^5.9.2",
     "vitest": "^4.1.7"
   },