@vibeframe/cli 0.106.5 → 0.106.7

package/dist/commands/_shared/host-integration.d.ts

@@ -41,7 +41,7 @@ export interface HostDoctorResult {
 }
 export declare function hostDefinitions(_projectDir?: string): HostDefinition[];
 export declare function resolveHostSelection(selection: HostSelection): HostSetupId[];
-export declare function renderHostSnippet(host: HostDefinition, _projectDir: string): string;
+export declare function renderHostSnippet(host: HostDefinition, projectDir: string): string;
 export declare function claudeCodeAddCommand(): string;
 export declare function planHostSetup(host: HostDefinition, projectDir: string, opts: {
     write?: boolean;

package/dist/index.js

@@ -67076,7 +67076,7 @@ function summariseLint(result) {
     fixed: result.fixed
   };
 }
-var SCENE_PRESETS2, sceneStylesSchema, sceneStylesTool, sceneInitSchema, sceneInitTool, sceneAddSchema, sceneAddTool, sceneLintSchema, sceneLintTool, sceneRepairSchema, sceneRepairTool, sceneRenderSchema, sceneRenderTool, sceneBuildSchema, sceneBuildTool, sceneInstallSkillSchema, sceneInstallSkillTool, sceneComposePromptsSchema, sceneComposePromptsTool, sceneTools;
+var SCENE_PRESETS2, PROJECT_DIR_DESCRIPTION, INIT_DIR_DESCRIPTION, sceneStylesSchema, sceneStylesTool, sceneInitSchema, sceneInitTool, sceneAddSchema, sceneAddTool, sceneLintSchema, sceneLintTool, sceneRepairSchema, sceneRepairTool, sceneRenderSchema, sceneRenderTool, sceneBuildSchema, sceneBuildTool, sceneInstallSkillSchema, sceneInstallSkillTool, sceneComposePromptsSchema, sceneComposePromptsTool, sceneTools;
 var init_scene2 = __esm({
   "src/tools/manifest/scene.ts"() {
     "use strict";
@@ -67099,6 +67099,8 @@ var init_scene2 = __esm({
       "kinetic-type",
       "product-shot"
     ];
+    PROJECT_DIR_DESCRIPTION = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
+    INIT_DIR_DESCRIPTION = "Project directory to create. Prefer a project name or workspace-relative path; in MCP hosts, relative paths resolve under the configured server workspace. Do not use /tmp or /home/claude unless the user explicitly asks.";
     sceneStylesSchema = external_exports.object({
       name: external_exports.string().optional().describe("Style name or slug (e.g. 'Swiss Pulse', 'swiss-pulse'). Omit to list all 8.")
     });
@@ -67158,7 +67160,7 @@ var init_scene2 = __esm({
       }
     });
     sceneInitSchema = external_exports.object({
-      dir: external_exports.string().describe("Project directory (created if missing)."),
+      dir: external_exports.string().describe(INIT_DIR_DESCRIPTION),
       name: external_exports.string().optional().describe("Project name. Defaults to the directory basename."),
       aspect: external_exports.enum(["16:9", "9:16", "1:1", "4:5"]).optional().describe("Aspect ratio. Default 16:9."),
       duration: external_exports.number().optional().describe("Default root composition duration in seconds. Default 10.")
@@ -67205,7 +67207,7 @@ var init_scene2 = __esm({
       visuals: external_exports.string().optional().describe("Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider."),
       headline: external_exports.string().optional().describe("Visible headline text. Defaults to the humanised scene name."),
       kicker: external_exports.string().optional().describe("Small label above the headline (used by 'explainer' and 'product-shot' presets)."),
-      projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+      projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
       insertInto: external_exports.string().optional().describe("Root composition file (relative to projectDir). Default 'index.html'."),
       imageProvider: external_exports.enum(["gemini", "openai"]).optional().describe("Image provider for visuals. Default 'gemini'."),
       voice: external_exports.string().optional().describe("ElevenLabs voice id or name."),
@@ -67266,7 +67268,7 @@ var init_scene2 = __esm({
       }
     });
     sceneLintSchema = external_exports.object({
-      projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+      projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
       root: external_exports.string().optional().describe("Root composition file relative to projectDir. Default 'index.html'."),
       fix: external_exports.boolean().optional().describe('Apply mechanical auto-fixes (currently: missing class="clip").')
     });
@@ -67303,7 +67305,7 @@ var init_scene2 = __esm({
       }
     });
     sceneRepairSchema = external_exports.object({
-      projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+      projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
       root: external_exports.string().optional().describe("Root composition file relative to projectDir. Default 'index.html'."),
       dryRun: external_exports.boolean().optional().describe("Preview deterministic repairs without writing files.")
     });
@@ -67332,7 +67334,7 @@ var init_scene2 = __esm({
       }
     });
     sceneRenderSchema = external_exports.object({
-      projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+      projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
       root: external_exports.string().optional().describe("Root composition file relative to projectDir. Default 'index.html'."),
       beat: external_exports.string().optional().describe("Render only one storyboard beat using a temporary root."),
       output: external_exports.string().optional().describe("Output file path (relative paths resolve against projectDir)."),
@@ -67387,7 +67389,7 @@ var init_scene2 = __esm({
     });
     sceneBuildSchema = external_exports.object({
       projectDir: external_exports.string().optional().describe(
-        "Project directory containing STORYBOARD.md, DESIGN.md, index.html. Defaults to the surface's cwd."
+        "Project directory containing STORYBOARD.md, DESIGN.md, index.html. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace."
       ),
       stage: external_exports.enum(["assets", "compose", "sync", "render", "all"]).optional().describe("Build stage to run. Default all."),
       beat: external_exports.string().optional().describe("Restrict asset/compose work to one beat id."),
@@ -67502,7 +67504,7 @@ var init_scene2 = __esm({
     });
     sceneInstallSkillSchema = external_exports.object({
       projectDir: external_exports.string().describe(
-        "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit and prevent accidental installs in unintended cwd."
+        "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit; in MCP hosts, relative paths resolve under the configured server workspace."
       ),
       host: external_exports.enum(["claude-code", "cursor", "auto", "all"]).optional().describe(
         "Host layout target. 'auto' (default) detects installed agent hosts; 'all' writes every layout; 'claude-code' / 'cursor' force a single host. Codex / Aider read the universal SKILL.md via AGENTS.md so don't need a host-specific layout."
@@ -67552,7 +67554,7 @@ var init_scene2 = __esm({
     });
     sceneComposePromptsSchema = external_exports.object({
       projectDir: external_exports.string().describe(
-        "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit."
+        "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit; in MCP hosts, relative paths resolve under the configured server workspace."
       ),
       beat: external_exports.string().optional().describe(
         "Restrict the plan to a single beat by id (e.g. 'hook', '1'). Omit to emit every beat in the storyboard."
@@ -68241,7 +68243,7 @@ var init_ai_suggest_edit = __esm({
 
 // src/tools/manifest/inspect.ts
 import { resolve as resolve75 } from "node:path";
-var inspectProjectTool, inspectRenderTool, analyzeMediaTool, analyzeVideoTool, analyzeReviewTool, analyzeSuggestTool, inspectTools;
+var PROJECT_DIR_DESCRIPTION2, inspectProjectTool, inspectRenderTool, analyzeMediaTool, analyzeVideoTool, analyzeReviewTool, analyzeSuggestTool, inspectTools;
 var init_inspect = __esm({
   "src/tools/manifest/inspect.ts"() {
     "use strict";
@@ -68252,13 +68254,14 @@ var init_inspect = __esm({
     init_ai_suggest_edit();
     init_scene_inspect();
     init_render_inspect();
+    PROJECT_DIR_DESCRIPTION2 = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
     inspectProjectTool = defineTool({
       name: "inspect_project",
       category: "analyze",
       cost: "free",
       description: "Local project inspection: checks STORYBOARD.md, DESIGN.md, config, build-report, scene lint, composition files, and referenced assets. Writes review-report.json by default.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION2),
         beat: external_exports.string().optional().describe("Inspect only one storyboard beat where beat-scoped checks apply."),
         outputPath: external_exports.string().optional().describe("Optional review report path. Defaults to <project>/review-report.json."),
         report: external_exports.boolean().optional().describe("Write review-report.json. Default true.")
@@ -68273,7 +68276,11 @@ var init_inspect = __esm({
         });
         return {
           success: result.status !== "fail",
-          data: result,
+          data: {
+            ...result,
+            workingDirectory: ctx.workingDirectory,
+            projectDir
+          },
           error: result.status === "fail" ? `${result.issues.filter((issue) => issue.severity === "error").length} project inspection error(s)` : void 0,
           humanLines: [
             `${result.status === "pass" ? "\u2705" : result.status === "warn" ? "\u26A0\uFE0F" : "\u274C"} Project inspection ${result.status} \u2014 score ${result.score}/100`,
@@ -68288,7 +68295,7 @@ var init_inspect = __esm({
       cost: "low",
       description: "Render inspection: runs cheap local video checks by default, optionally adds Gemini AI review with ai: true, and writes review-report.json by default.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION2),
         beat: external_exports.string().optional().describe("Inspect a render for one storyboard beat."),
         videoPath: external_exports.string().optional().describe("Rendered video path. Defaults to build-report outputPath or latest renders/* video."),
         outputPath: external_exports.string().optional().describe("Optional review report path. Defaults to <project>/review-report.json."),
@@ -68311,7 +68318,11 @@ var init_inspect = __esm({
           });
           return {
             success: true,
-            data: result2,
+            data: {
+              ...result2,
+              workingDirectory: ctx.workingDirectory,
+              projectDir
+            },
             humanLines: [
               `Render inspection dry-run \u2014 ${result2.videoPath ? "render found" : "render missing"}`,
               ...result2.reportPath ? [`report: ${result2.reportPath}`] : []
@@ -68329,7 +68340,11 @@ var init_inspect = __esm({
         });
         return {
           success: result.status !== "fail",
-          data: result,
+          data: {
+            ...result,
+            workingDirectory: ctx.workingDirectory,
+            projectDir
+          },
           error: result.status === "fail" ? `${result.issues.filter((issue) => issue.severity === "error").length} render inspection error(s)` : void 0,
           humanLines: [
             `${result.status === "pass" ? "\u2705" : result.status === "warn" ? "\u26A0\uFE0F" : "\u274C"} Render inspection ${result.status} \u2014 score ${result.score}/100`,
@@ -68713,7 +68728,7 @@ var init_generate2 = __esm({
       schema: external_exports.object({
         description: external_exports.string().describe("Background description / image prompt."),
         aspect: external_exports.enum(["16:9", "9:16", "1:1"]).optional().describe("Aspect ratio. Default '16:9'."),
-        output: external_exports.string().optional().describe("Output PNG path. Relative paths resolve against the surface's cwd.")
+        output: external_exports.string().optional().describe("Output PNG path. Relative paths resolve against the surface's cwd; in MCP hosts, that is the configured server workspace.")
       }),
       async execute(args) {
         const result = await executeBackground(args);
@@ -68920,7 +68935,7 @@ async function readStoryboard2(projectDir) {
   if (!existsSync54(path2)) return null;
   return { path: path2, markdown: await readFile49(path2, "utf-8") };
 }
-var projectDirSchema, storyboardListTool, storyboardValidateTool, storyboardGetTool, storyboardSetTool, storyboardMoveTool, storyboardReviseTool, planTool, storyboardTools;
+var PROJECT_DIR_DESCRIPTION3, projectDirSchema, storyboardListTool, storyboardValidateTool, storyboardGetTool, storyboardSetTool, storyboardMoveTool, storyboardReviseTool, planTool, storyboardTools;
 var init_storyboard2 = __esm({
   "src/tools/manifest/storyboard.ts"() {
     "use strict";
@@ -68930,8 +68945,9 @@ var init_storyboard2 = __esm({
     init_storyboard_edit();
     init_storyboard_revise();
     init_build_plan();
+    PROJECT_DIR_DESCRIPTION3 = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
     projectDirSchema = external_exports.object({
-      projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd.")
+      projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3)
     });
     storyboardListTool = defineTool({
       name: "storyboard_list",
@@ -68995,7 +69011,7 @@ var init_storyboard2 = __esm({
       cost: "free",
       description: "Return one STORYBOARD.md beat as structured data.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
         beat: external_exports.string().describe("Beat id to return.")
       }),
       async execute(args, ctx) {
@@ -69017,7 +69033,7 @@ var init_storyboard2 = __esm({
       cost: "free",
       description: "Set or unset one cue on one beat in STORYBOARD.md.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
         beat: external_exports.string().describe("Beat id to mutate."),
         key: external_exports.string().describe("Cue key to set."),
         value: external_exports.string().optional().describe("Cue value. Required unless unset is true."),
@@ -69053,7 +69069,7 @@ var init_storyboard2 = __esm({
       cost: "free",
       description: "Move one beat after another beat in STORYBOARD.md.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
         beat: external_exports.string().describe("Beat id to move."),
         after: external_exports.string().describe("Beat id that should precede the moved beat.")
       }),
@@ -69083,7 +69099,7 @@ var init_storyboard2 = __esm({
       cost: "low",
       description: "Revise an existing STORYBOARD.md from a natural-language request. Reads project context, validates the revised storyboard, and writes unless dryRun is true.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
         request: external_exports.string().describe("Revision request, e.g. 'make the hook punchier and shorten to 30 seconds'."),
         durationSec: external_exports.number().optional().describe("Target total duration in seconds."),
         composer: external_exports.enum(["claude", "openai", "gemini"]).optional().describe("Revision LLM provider. Defaults to project config or available API keys."),
@@ -69114,7 +69130,7 @@ var init_storyboard2 = __esm({
       cost: "free",
       description: "Read STORYBOARD.md and return the build plan, missing artifacts, provider needs, and estimated cost.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
         stage: external_exports.enum(["assets", "compose", "sync", "render", "all"]).optional().describe("Stage to plan. Default all."),
         beat: external_exports.string().optional().describe("Restrict the plan to one beat id."),
         mode: external_exports.enum(["agent", "batch", "auto"]).optional().describe("Build mode. Default auto."),
@@ -71673,13 +71689,14 @@ var init_walkthrough = __esm({
 
 // src/tools/manifest/status.ts
 import { resolve as resolve82 } from "node:path";
-var statusJobTool, statusProjectTool, statusTools;
+var PROJECT_DIR_DESCRIPTION4, statusJobTool, statusProjectTool, statusTools;
 var init_status = __esm({
   "src/tools/manifest/status.ts"() {
     "use strict";
     init_zod();
     init_define_tool();
     init_status_jobs();
+    PROJECT_DIR_DESCRIPTION4 = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
     statusJobTool = defineTool({
       name: "status_job",
       category: "status",
@@ -71687,7 +71704,7 @@ var init_status = __esm({
       description: "Read one local async job record and optionally refresh supported provider status. Supports Runway/Kling video and Replicate music live checks.",
       schema: external_exports.object({
         jobId: external_exports.string().describe("Local job id returned by a no-wait command."),
-        projectDir: external_exports.string().optional().describe("Project directory containing .vibeframe/jobs. Defaults to nearest project root."),
+        projectDir: external_exports.string().optional().describe("Project directory containing .vibeframe/jobs. Defaults to nearest project root; in MCP hosts, relative paths resolve under the configured server workspace."),
         refresh: external_exports.boolean().optional().describe("Call provider status APIs when supported. Default true."),
         wait: external_exports.boolean().optional().describe("Wait for completion when supported."),
         output: external_exports.string().optional().describe("Download result media to this path when complete.")
@@ -71721,7 +71738,7 @@ var init_status = __esm({
       cost: "free",
       description: "Summarize build-report.json, review-report.json, and local async job records for a VibeFrame project.",
       schema: external_exports.object({
-        projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+        projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION4),
         refresh: external_exports.boolean().optional().describe("Refresh active supported jobs before summarizing. Default false.")
       }),
       async execute(args, ctx) {
@@ -71729,7 +71746,11 @@ var init_status = __esm({
         const result = await inspectProjectStatus(projectDir, { refresh: args.refresh === true });
         return {
           success: true,
-          data: result,
+          data: {
+            ...result,
+            workingDirectory: ctx.workingDirectory,
+            projectDir
+          },
           humanLines: [
             `Project status: ${result.status} (${result.currentStage}), ${result.jobs.active} active job(s), ${result.jobs.failed} failed job(s)`,
             ...result.build ? [`build: ${result.build.phase ?? "unknown"}`] : [],
@@ -72007,7 +72028,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.106.5",
+  version: "0.106.7",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",
@@ -80681,9 +80702,23 @@ function resolveHostSelection(selection) {
   if (selection === "claude") return ["claude-code", "claude-desktop"];
   return [selection];
 }
-function renderHostSnippet(host, _projectDir) {
+function vibeframeMcpJson(host, projectDir) {
+  if (host.id !== "claude-desktop") return { ...VIBEFRAME_MCP_JSON };
+  const workspace = resolve53(projectDir);
+  if (process.platform === "win32") {
+    return {
+      command: "cmd.exe",
+      args: ["/d", "/s", "/c", `cd /d ${cmdQuote(workspace)} && npx -y @vibeframe/mcp-server`]
+    };
+  }
+  return {
+    command: "bash",
+    args: ["-lc", `cd ${shellQuote(workspace)} && exec npx -y @vibeframe/mcp-server`]
+  };
+}
+function renderHostSnippet(host, projectDir) {
   if (host.configKind === "codex-toml") return CODEX_MCP_BLOCK.trimEnd();
-  return JSON.stringify({ mcpServers: { vibeframe: VIBEFRAME_MCP_JSON } }, null, 2);
+  return JSON.stringify({ mcpServers: { vibeframe: vibeframeMcpJson(host, projectDir) } }, null, 2);
 }
 function claudeCodeAddCommand() {
   return "claude mcp add vibeframe --scope project -- npx -y @vibeframe/mcp-server";
@@ -80712,6 +80747,7 @@ async function planHostSetup(host, projectDir, opts) {
   }
   try {
     const action = host.configKind === "codex-toml" ? await mergeCodexToml(configPath, { force: opts.force === true }) : await mergeMcpJson(configPath, {
+      server: vibeframeMcpJson(host, projectDir),
       force: opts.force === true,
       backup: host.id === "claude-desktop"
     });
@@ -80737,7 +80773,18 @@ async function inspectHost(host, projectDir) {
   if (existsSync40(configPath)) {
     try {
       const content = await readFile37(configPath, "utf-8");
-      configured = host.configKind === "codex-toml" ? /\[mcp_servers\.vibeframe\]/.test(content) : hasVibeframeMcpServer(JSON.parse(content));
+      if (host.configKind === "codex-toml") {
+        configured = /\[mcp_servers\.vibeframe\]/.test(content);
+      } else {
+        const json = JSON.parse(content);
+        configured = hasVibeframeMcpServer(json);
+        const server = readVibeframeMcpServer(json);
+        if (host.id === "claude-desktop" && configured && !isAnchoredClaudeDesktopServer(server)) {
+          warnings.push(
+            "Claude Desktop vibeframe MCP config is not workspace-anchored; run `vibe host setup claude-desktop <workspace> --write` to anchor relative paths."
+          );
+        }
+      }
     } catch (error) {
       warnings.push(error instanceof Error ? error.message : String(error));
     }
@@ -80757,13 +80804,26 @@ async function mergeMcpJson(configPath, opts) {
   }
   const mcpServers = typeof root.mcpServers === "object" && root.mcpServers !== null && !Array.isArray(root.mcpServers) ? root.mcpServers : {};
   if (mcpServers.vibeframe && !opts.force) {
+    const existing = mcpServers.vibeframe;
+    if (canUpgradeDefaultServer(existing, opts.server)) {
+      root.mcpServers = {
+        ...mcpServers,
+        vibeframe: opts.server
+      };
+      await mkdir22(dirname18(configPath), { recursive: true });
+      if (exists && opts.backup) {
+        await writeFile44(`${configPath}.bak-${timestamp()}`, await readFile37(configPath, "utf-8"), "utf-8");
+      }
+      await writeFile44(configPath, JSON.stringify(root, null, 2) + "\n", "utf-8");
+      return { path: configPath, status: "merged", reason: "anchored existing default vibeframe MCP server" };
+    }
     return {
       path: configPath,
       status: "skipped-exists",
       reason: "vibeframe MCP server already exists; pass --force to replace"
     };
   }
-  root.mcpServers = { ...mcpServers, vibeframe: VIBEFRAME_MCP_JSON };
+  root.mcpServers = { ...mcpServers, vibeframe: opts.server };
   await mkdir22(dirname18(configPath), { recursive: true });
   if (exists && opts.backup) {
     await writeFile44(`${configPath}.bak-${timestamp()}`, await readFile37(configPath, "utf-8"), "utf-8");
@@ -80817,6 +80877,33 @@ function hasVibeframeMcpServer(value) {
   if (!root.mcpServers || typeof root.mcpServers !== "object") return false;
   return Object.prototype.hasOwnProperty.call(root.mcpServers, "vibeframe");
 }
+function readVibeframeMcpServer(value) {
+  if (!value || typeof value !== "object") return null;
+  const root = value;
+  if (!root.mcpServers || typeof root.mcpServers !== "object" || Array.isArray(root.mcpServers)) return null;
+  const server = root.mcpServers.vibeframe;
+  if (!server || typeof server !== "object" || Array.isArray(server)) return null;
+  return server;
+}
+function isAnchoredClaudeDesktopServer(server) {
+  if (!server) return false;
+  if (server.command === "bash" && Array.isArray(server.args)) {
+    return server.args[0] === "-lc" && typeof server.args[1] === "string" && server.args[1].includes("exec npx -y @vibeframe/mcp-server");
+  }
+  if (server.command === "cmd.exe" && Array.isArray(server.args)) {
+    return server.args.some((arg) => typeof arg === "string" && arg.includes("npx -y @vibeframe/mcp-server"));
+  }
+  return false;
+}
+function canUpgradeDefaultServer(existing, target) {
+  if (!existing || typeof existing !== "object" || Array.isArray(existing)) return false;
+  const current = existing;
+  if (!Array.isArray(current.args)) return false;
+  if (current.command === target.command && JSON.stringify(current.args) === JSON.stringify(target.args)) {
+    return false;
+  }
+  return current.command === VIBEFRAME_MCP_JSON.command && JSON.stringify(current.args) === JSON.stringify(VIBEFRAME_MCP_JSON.args);
+}
 function hostNextSteps(host) {
   if (host.id === "codex") {
     return [
@@ -80855,6 +80942,12 @@ function ensureTrailingNewline(value) {
 function escapeRegExp3(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function cmdQuote(value) {
+  return `"${value.replace(/"/g, '""')}"`;
+}
 
 // src/commands/_shared/init-templates.ts
 var AGENTS_MD = `# AGENTS.md

package/dist/tools/adapters/mcp.js

@@ -159,7 +159,11 @@ function buildMcpDispatcher(manifest) {
         workingDirectory: process.cwd(),
         surface: "mcp"
       });
-      const text = result.success ? JSON.stringify({ success: true, ...result.data }) : `${name} failed: ${result.error ?? "unknown error"}`;
+      const text = result.success ? JSON.stringify({ success: true, ...result.data }) : result.data ? JSON.stringify({
+        success: false,
+        error: result.error ?? "unknown error",
+        ...result.data
+      }) : `${name} failed: ${result.error ?? "unknown error"}`;
       return { content: [{ type: "text", text }] };
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);

package/dist/tools/manifest/index.js

@@ -52320,6 +52320,8 @@ var SCENE_PRESETS2 = [
   "kinetic-type",
   "product-shot"
 ];
+var PROJECT_DIR_DESCRIPTION = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
+var INIT_DIR_DESCRIPTION = "Project directory to create. Prefer a project name or workspace-relative path; in MCP hosts, relative paths resolve under the configured server workspace. Do not use /tmp or /home/claude unless the user explicitly asks.";
 var sceneStylesSchema = external_exports.object({
   name: external_exports.string().optional().describe("Style name or slug (e.g. 'Swiss Pulse', 'swiss-pulse'). Omit to list all 8.")
 });
@@ -52379,7 +52381,7 @@ var sceneStylesTool = defineTool({
   }
 });
 var sceneInitSchema = external_exports.object({
-  dir: external_exports.string().describe("Project directory (created if missing)."),
+  dir: external_exports.string().describe(INIT_DIR_DESCRIPTION),
   name: external_exports.string().optional().describe("Project name. Defaults to the directory basename."),
   aspect: external_exports.enum(["16:9", "9:16", "1:1", "4:5"]).optional().describe("Aspect ratio. Default 16:9."),
   duration: external_exports.number().optional().describe("Default root composition duration in seconds. Default 10.")
@@ -52426,7 +52428,7 @@ var sceneAddSchema = external_exports.object({
   visuals: external_exports.string().optional().describe("Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider."),
   headline: external_exports.string().optional().describe("Visible headline text. Defaults to the humanised scene name."),
   kicker: external_exports.string().optional().describe("Small label above the headline (used by 'explainer' and 'product-shot' presets)."),
-  projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+  projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
   insertInto: external_exports.string().optional().describe("Root composition file (relative to projectDir). Default 'index.html'."),
   imageProvider: external_exports.enum(["gemini", "openai"]).optional().describe("Image provider for visuals. Default 'gemini'."),
   voice: external_exports.string().optional().describe("ElevenLabs voice id or name."),
@@ -52487,7 +52489,7 @@ var sceneAddTool = defineTool({
   }
 });
 var sceneLintSchema = external_exports.object({
-  projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+  projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
   root: external_exports.string().optional().describe("Root composition file relative to projectDir. Default 'index.html'."),
   fix: external_exports.boolean().optional().describe('Apply mechanical auto-fixes (currently: missing class="clip").')
 });
@@ -52545,7 +52547,7 @@ var sceneLintTool = defineTool({
   }
 });
 var sceneRepairSchema = external_exports.object({
-  projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+  projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
   root: external_exports.string().optional().describe("Root composition file relative to projectDir. Default 'index.html'."),
   dryRun: external_exports.boolean().optional().describe("Preview deterministic repairs without writing files.")
 });
@@ -52574,7 +52576,7 @@ var sceneRepairTool = defineTool({
   }
 });
 var sceneRenderSchema = external_exports.object({
-  projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+  projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION),
   root: external_exports.string().optional().describe("Root composition file relative to projectDir. Default 'index.html'."),
   beat: external_exports.string().optional().describe("Render only one storyboard beat using a temporary root."),
   output: external_exports.string().optional().describe("Output file path (relative paths resolve against projectDir)."),
@@ -52629,7 +52631,7 @@ var sceneRenderTool = defineTool({
 });
 var sceneBuildSchema = external_exports.object({
   projectDir: external_exports.string().optional().describe(
-    "Project directory containing STORYBOARD.md, DESIGN.md, index.html. Defaults to the surface's cwd."
+    "Project directory containing STORYBOARD.md, DESIGN.md, index.html. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace."
   ),
   stage: external_exports.enum(["assets", "compose", "sync", "render", "all"]).optional().describe("Build stage to run. Default all."),
   beat: external_exports.string().optional().describe("Restrict asset/compose work to one beat id."),
@@ -52744,7 +52746,7 @@ var sceneBuildTool = defineTool({
 });
 var sceneInstallSkillSchema = external_exports.object({
   projectDir: external_exports.string().describe(
-    "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit and prevent accidental installs in unintended cwd."
+    "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit; in MCP hosts, relative paths resolve under the configured server workspace."
   ),
   host: external_exports.enum(["claude-code", "cursor", "auto", "all"]).optional().describe(
     "Host layout target. 'auto' (default) detects installed agent hosts; 'all' writes every layout; 'claude-code' / 'cursor' force a single host. Codex / Aider read the universal SKILL.md via AGENTS.md so don't need a host-specific layout."
@@ -52794,7 +52796,7 @@ var sceneInstallSkillTool = defineTool({
 });
 var sceneComposePromptsSchema = external_exports.object({
   projectDir: external_exports.string().describe(
-    "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit."
+    "Project directory containing STORYBOARD.md / DESIGN.md. Required to keep cross-host calls explicit; in MCP hosts, relative paths resolve under the configured server workspace."
   ),
   beat: external_exports.string().optional().describe(
     "Restrict the plan to a single beat by id (e.g. 'hook', '1'). Omit to emit every beat in the storyboard."
@@ -55095,13 +55097,14 @@ function sanitizeFileSegment2(value) {
 }
 
 // src/tools/manifest/inspect.ts
+var PROJECT_DIR_DESCRIPTION2 = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
 var inspectProjectTool = defineTool({
   name: "inspect_project",
   category: "analyze",
   cost: "free",
   description: "Local project inspection: checks STORYBOARD.md, DESIGN.md, config, build-report, scene lint, composition files, and referenced assets. Writes review-report.json by default.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION2),
     beat: external_exports.string().optional().describe("Inspect only one storyboard beat where beat-scoped checks apply."),
     outputPath: external_exports.string().optional().describe("Optional review report path. Defaults to <project>/review-report.json."),
     report: external_exports.boolean().optional().describe("Write review-report.json. Default true.")
@@ -55116,7 +55119,11 @@ var inspectProjectTool = defineTool({
     });
     return {
       success: result.status !== "fail",
-      data: result,
+      data: {
+        ...result,
+        workingDirectory: ctx.workingDirectory,
+        projectDir
+      },
       error: result.status === "fail" ? `${result.issues.filter((issue) => issue.severity === "error").length} project inspection error(s)` : void 0,
       humanLines: [
         `${result.status === "pass" ? "\u2705" : result.status === "warn" ? "\u26A0\uFE0F" : "\u274C"} Project inspection ${result.status} \u2014 score ${result.score}/100`,
@@ -55131,7 +55138,7 @@ var inspectRenderTool = defineTool({
   cost: "low",
   description: "Render inspection: runs cheap local video checks by default, optionally adds Gemini AI review with ai: true, and writes review-report.json by default.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION2),
     beat: external_exports.string().optional().describe("Inspect a render for one storyboard beat."),
     videoPath: external_exports.string().optional().describe("Rendered video path. Defaults to build-report outputPath or latest renders/* video."),
     outputPath: external_exports.string().optional().describe("Optional review report path. Defaults to <project>/review-report.json."),
@@ -55154,7 +55161,11 @@ var inspectRenderTool = defineTool({
       });
       return {
         success: true,
-        data: result2,
+        data: {
+          ...result2,
+          workingDirectory: ctx.workingDirectory,
+          projectDir
+        },
         humanLines: [
           `Render inspection dry-run \u2014 ${result2.videoPath ? "render found" : "render missing"}`,
           ...result2.reportPath ? [`report: ${result2.reportPath}`] : []
@@ -55172,7 +55183,11 @@ var inspectRenderTool = defineTool({
     });
     return {
       success: result.status !== "fail",
-      data: result,
+      data: {
+        ...result,
+        workingDirectory: ctx.workingDirectory,
+        projectDir
+      },
       error: result.status === "fail" ? `${result.issues.filter((issue) => issue.severity === "error").length} render inspection error(s)` : void 0,
       humanLines: [
         `${result.status === "pass" ? "\u2705" : result.status === "warn" ? "\u26A0\uFE0F" : "\u274C"} Render inspection ${result.status} \u2014 score ${result.score}/100`,
@@ -55548,7 +55563,7 @@ var generateBackgroundTool = defineTool({
   schema: external_exports.object({
     description: external_exports.string().describe("Background description / image prompt."),
     aspect: external_exports.enum(["16:9", "9:16", "1:1"]).optional().describe("Aspect ratio. Default '16:9'."),
-    output: external_exports.string().optional().describe("Output PNG path. Relative paths resolve against the surface's cwd.")
+    output: external_exports.string().optional().describe("Output PNG path. Relative paths resolve against the surface's cwd; in MCP hosts, that is the configured server workspace.")
   }),
   async execute(args) {
     const result = await executeBackground(args);
@@ -56085,8 +56100,9 @@ function stripUndefined3(value) {
 
 // src/tools/manifest/storyboard.ts
 init_build_plan();
+var PROJECT_DIR_DESCRIPTION3 = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
 var projectDirSchema = external_exports.object({
-  projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd.")
+  projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3)
 });
 async function readStoryboard(projectDir) {
   const path2 = resolve52(projectDir, "STORYBOARD.md");
@@ -56155,7 +56171,7 @@ var storyboardGetTool = defineTool({
   cost: "free",
   description: "Return one STORYBOARD.md beat as structured data.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
     beat: external_exports.string().describe("Beat id to return.")
   }),
   async execute(args, ctx) {
@@ -56177,7 +56193,7 @@ var storyboardSetTool = defineTool({
   cost: "free",
   description: "Set or unset one cue on one beat in STORYBOARD.md.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
     beat: external_exports.string().describe("Beat id to mutate."),
     key: external_exports.string().describe("Cue key to set."),
     value: external_exports.string().optional().describe("Cue value. Required unless unset is true."),
@@ -56213,7 +56229,7 @@ var storyboardMoveTool = defineTool({
   cost: "free",
   description: "Move one beat after another beat in STORYBOARD.md.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
     beat: external_exports.string().describe("Beat id to move."),
     after: external_exports.string().describe("Beat id that should precede the moved beat.")
   }),
@@ -56243,7 +56259,7 @@ var storyboardReviseTool = defineTool({
   cost: "low",
   description: "Revise an existing STORYBOARD.md from a natural-language request. Reads project context, validates the revised storyboard, and writes unless dryRun is true.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
     request: external_exports.string().describe("Revision request, e.g. 'make the hook punchier and shorten to 30 seconds'."),
     durationSec: external_exports.number().optional().describe("Target total duration in seconds."),
     composer: external_exports.enum(["claude", "openai", "gemini"]).optional().describe("Revision LLM provider. Defaults to project config or available API keys."),
@@ -56274,7 +56290,7 @@ var planTool = defineTool({
   cost: "free",
   description: "Read STORYBOARD.md and return the build plan, missing artifacts, provider needs, and estimated cost.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION3),
     stage: external_exports.enum(["assets", "compose", "sync", "render", "all"]).optional().describe("Stage to plan. Default all."),
     beat: external_exports.string().optional().describe("Restrict the plan to one beat id."),
     mode: external_exports.enum(["agent", "batch", "auto"]).optional().describe("Build mode. Default auto."),
@@ -60834,6 +60850,7 @@ var guideTools = [guideTool];
 // src/tools/manifest/status.ts
 import { resolve as resolve62 } from "node:path";
 init_status_jobs();
+var PROJECT_DIR_DESCRIPTION4 = "Project directory. Defaults to the surface's cwd; in MCP hosts, relative paths resolve under the configured server workspace.";
 var statusJobTool = defineTool({
   name: "status_job",
   category: "status",
@@ -60841,7 +60858,7 @@ var statusJobTool = defineTool({
   description: "Read one local async job record and optionally refresh supported provider status. Supports Runway/Kling video and Replicate music live checks.",
   schema: external_exports.object({
     jobId: external_exports.string().describe("Local job id returned by a no-wait command."),
-    projectDir: external_exports.string().optional().describe("Project directory containing .vibeframe/jobs. Defaults to nearest project root."),
+    projectDir: external_exports.string().optional().describe("Project directory containing .vibeframe/jobs. Defaults to nearest project root; in MCP hosts, relative paths resolve under the configured server workspace."),
     refresh: external_exports.boolean().optional().describe("Call provider status APIs when supported. Default true."),
     wait: external_exports.boolean().optional().describe("Wait for completion when supported."),
     output: external_exports.string().optional().describe("Download result media to this path when complete.")
@@ -60875,7 +60892,7 @@ var statusProjectTool = defineTool({
   cost: "free",
   description: "Summarize build-report.json, review-report.json, and local async job records for a VibeFrame project.",
   schema: external_exports.object({
-    projectDir: external_exports.string().optional().describe("Project directory. Defaults to the surface's cwd."),
+    projectDir: external_exports.string().optional().describe(PROJECT_DIR_DESCRIPTION4),
     refresh: external_exports.boolean().optional().describe("Refresh active supported jobs before summarizing. Default false.")
   }),
   async execute(args, ctx) {
@@ -60883,7 +60900,11 @@ var statusProjectTool = defineTool({
     const result = await inspectProjectStatus(projectDir, { refresh: args.refresh === true });
     return {
       success: true,
-      data: result,
+      data: {
+        ...result,
+        workingDirectory: ctx.workingDirectory,
+        projectDir
+      },
       humanLines: [
         `Project status: ${result.status} (${result.currentStage}), ${result.jobs.active} active job(s), ${result.jobs.failed} failed job(s)`,
         ...result.build ? [`build: ${result.build.phase ?? "unknown"}`] : [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.106.5",
+  "version": "0.106.7",
   "description": "VibeFrame CLI - agentic video workflow runtime",
   "private": false,
   "license": "MIT",
@@ -83,8 +83,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.106.5",
-    "@vibeframe/core": "0.106.5"
+    "@vibeframe/ai-providers": "0.106.7",
+    "@vibeframe/core": "0.106.7"
   },
   "engines": {
     "node": ">=20"