@vellumai/assistant 0.5.1 → 0.5.3

package/src/tools/skills/load.ts

@@ -21,12 +21,24 @@ import {
   indexCatalogById,
   validateIncludes,
 } from "../../skills/include-graph.js";
+import { renderInlineCommands } from "../../skills/inline-command-render.js";
 import { parseToolManifestFile } from "../../skills/tool-manifest.js";
 import { computeSkillVersionHash } from "../../skills/version-hash.js";
 import { getLogger } from "../../util/logger.js";
+import { getWorkspaceDirDisplay } from "../../util/platform.js";
 import { registerTool } from "../registry.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
+/** Canonical feature flag key for inline skill command expansion. */
+const INLINE_COMMANDS_FLAG_KEY = "feature_flags.inline-skill-commands.enabled";
+
+/** Skill sources eligible for inline command expansion in v1. */
+const INLINE_COMMAND_ELIGIBLE_SOURCES = new Set([
+  "bundled",
+  "managed",
+  "workspace",
+]);
+
 const log = getLogger("skill-load");
 
 /**
@@ -76,7 +88,9 @@ function formatToolSchemas(
 
   for (const tool of manifest.tools) {
     lines.push(`${toolHeadingLevel} ${tool.name}`);
-    lines.push(tool.description);
+    lines.push(
+      tool.description.replaceAll("{workspaceDir}", getWorkspaceDirDisplay()),
+    );
 
     const schema = tool.input_schema;
     const properties = schema.properties as
@@ -96,7 +110,7 @@ function formatToolSchemas(
           : "optional";
         const descPart =
           typeof paramDef.description === "string"
-            ? `: ${paramDef.description}`
+            ? `: ${paramDef.description.replaceAll("{workspaceDir}", getWorkspaceDirDisplay())}`
             : "";
         lines.push(
           `- ${paramName} (${paramType}, ${requiredLabel})${descPart}`,
@@ -113,7 +127,7 @@ function formatToolSchemas(
 export class SkillLoadTool implements Tool {
   name = "skill_load";
   description =
-    "Load full instructions for a skill. Works for both bundled skills (listed in the catalog) and workspace skills in ~/.vellum/workspace/skills.";
+    "Load full instructions for a skill. Works for both bundled skills (listed in the catalog) and custom workspace skills.";
   category = "skills";
   defaultRiskLevel = RiskLevel.Low;
 
@@ -136,7 +150,7 @@ export class SkillLoadTool implements Tool {
 
   async execute(
     input: Record<string, unknown>,
-    _context: ToolContext,
+    context: ToolContext,
   ): Promise<ToolExecutionResult> {
     const selector = input.skill;
     if (typeof selector !== "string" || selector.trim().length === 0) {
@@ -279,7 +293,63 @@ export class SkillLoadTool implements Tool {
       }
     }
 
-    const body = skill.body.length > 0 ? skill.body : "(No body content)";
+    let body = skill.body.length > 0 ? skill.body : "(No body content)";
+
+    // ── Inline command expansion ──────────────────────────────────────────
+    const hasInlineCommands =
+      skill.inlineCommandExpansions && skill.inlineCommandExpansions.length > 0;
+
+    if (hasInlineCommands) {
+      const inlineFlagEnabled = isAssistantFeatureFlagEnabled(
+        INLINE_COMMANDS_FLAG_KEY,
+        config,
+      );
+
+      if (!inlineFlagEnabled) {
+        // Feature flag is off: fail closed instead of leaving live tokens in
+        // the prompt that the LLM might try to interpret.
+        return {
+          content: `Error: skill "${skill.id}" contains inline command expansions but the inline-skill-commands feature flag is disabled. Enable the flag to use this skill.`,
+          isError: true,
+        };
+      }
+
+      if (skill.source === "extra") {
+        // Third-party extra roots are out of scope for inline command
+        // expansion in v1. Reject explicitly so the failure is clear.
+        return {
+          content: `Error: skill "${skill.id}" contains inline command expansions but inline commands are not supported for third-party (extra) skill sources.`,
+          isError: true,
+        };
+      }
+
+      if (!INLINE_COMMAND_ELIGIBLE_SOURCES.has(skill.source)) {
+        // Defensive: reject any other unknown sources that somehow have
+        // inline commands. Should not happen with current SkillSource values,
+        // but fail closed if a new source type is added without updating this.
+        return {
+          content: `Error: skill "${skill.id}" contains inline command expansions but source "${skill.source}" is not eligible for inline command expansion.`,
+          isError: true,
+        };
+      }
+
+      // Render inline commands by executing each through the sandbox runner
+      const renderResult = await renderInlineCommands(
+        body,
+        skill.inlineCommandExpansions!,
+        context.workingDir,
+      );
+      body = renderResult.renderedBody;
+
+      log.info(
+        {
+          skillId: skill.id,
+          expandedCount: renderResult.expandedCount,
+          failedCount: renderResult.failedCount,
+        },
+        "Rendered inline command expansions",
+      );
+    }
 
     // Build reference file listing (if any)
     const referenceListing = listReferenceFiles(skill.directoryPath);
@@ -313,8 +383,72 @@ export class SkillLoadTool implements Tool {
         // Load the included skill's body content
         const childLoaded = loadSkillBySelector(childId);
         if (childLoaded.skill && childLoaded.skill.body.length > 0) {
+          let childBody = childLoaded.skill.body;
+
+          // ── Inline command expansion for included child skill ─────────
+          const childHasInlineCommands =
+            childLoaded.skill.inlineCommandExpansions &&
+            childLoaded.skill.inlineCommandExpansions.length > 0;
+
+          if (childHasInlineCommands) {
+            const childInlineFlagEnabled = isAssistantFeatureFlagEnabled(
+              INLINE_COMMANDS_FLAG_KEY,
+              config,
+            );
+
+            // Fail closed: if the flag is off, reject the entire skill_load
+            // just like we do for root skills. Leaving raw !`...` tokens in
+            // the prompt would violate the documented fail-closed contract.
+            if (!childInlineFlagEnabled) {
+              return {
+                content: `Error: included skill "${childId}" contains inline command expansions but the inline-skill-commands feature flag is disabled. Enable the flag to use skill "${skill.id}".`,
+                isError: true,
+              };
+            }
+
+            if (childLoaded.skill.source === "extra") {
+              return {
+                content: `Error: included skill "${childId}" contains inline command expansions but inline commands are not supported for third-party (extra) skill sources.`,
+                isError: true,
+              };
+            }
+
+            if (
+              !INLINE_COMMAND_ELIGIBLE_SOURCES.has(childLoaded.skill.source)
+            ) {
+              return {
+                content: `Error: included skill "${childId}" contains inline command expansions but source "${childLoaded.skill.source}" is not eligible for inline command expansion.`,
+                isError: true,
+              };
+            }
+
+            try {
+              const childRenderResult = await renderInlineCommands(
+                childBody,
+                childLoaded.skill.inlineCommandExpansions!,
+                context.workingDir,
+              );
+              childBody = childRenderResult.renderedBody;
+
+              log.info(
+                {
+                  skillId: childId,
+                  parentSkillId: skill.id,
+                  expandedCount: childRenderResult.expandedCount,
+                  failedCount: childRenderResult.failedCount,
+                },
+                "Rendered inline command expansions for included skill",
+              );
+            } catch (err) {
+              log.warn(
+                { err, skillId: childId, parentSkillId: skill.id },
+                "Failed to render inline commands for included skill, using raw body",
+              );
+            }
+          }
+
           includedBodies.push(
-            `--- Included Skill: ${childLoaded.skill.displayName} (${childId}) ---\n${childLoaded.skill.body}`,
+            `--- Included Skill: ${childLoaded.skill.displayName} (${childId}) ---\n${childBody}`,
           );
 
           // List reference files for the included skill

package/src/tools/tool-manifest.ts

@@ -11,8 +11,6 @@ import {
   isCesSecureInstallEnabled,
   isCesToolsEnabled,
 } from "../credential-execution/feature-gates.js";
-import { assetMaterializeTool } from "./assets/materialize.js";
-import { assetSearchTool } from "./assets/search.js";
 import { makeAuthenticatedRequestTool } from "./credential-execution/make-authenticated-request.js";
 import { manageSecureCommandTool } from "./credential-execution/manage-secure-command-tool.js";
 import { runAuthenticatedCommandTool } from "./credential-execution/run-authenticated-command.js";
@@ -63,8 +61,6 @@ export const eagerModuleToolNames: string[] = [
   "skill_execute",
   "skill_load",
   "request_system_permission",
-  "asset_search",
-  "asset_materialize",
 ];
 
 // ── Explicit tool instances ─────────────────────────────────────────
@@ -85,8 +81,6 @@ export const explicitTools: Tool[] = [
   skillExecuteTool,
   skillLoadTool,
   requestSystemPermissionTool,
-  assetSearchTool,
-  assetMaterializeTool,
   // Always-explicit tools
   memoryManageTool,
   memoryRecallTool,

package/src/tools/ui-surface/definitions.ts

@@ -30,7 +30,7 @@ export const uiShowTool: Tool = {
   description:
     "Show structured data or UI to the user. For long-form writing use the document skill; for interactive apps use the app-builder skill.\n\n" +
     "Surface types (data shapes):\n" +
-    "- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: \"weather_forecast\" (native weather widget), \"task_progress\" (live step tracker - update via ui_update on data.templateData; shape: { title, status: \"in_progress\"|\"completed\"|\"failed\", steps: [{ label, status: \"pending\"|\"in_progress\"|\"completed\"|\"failed\", detail? }] })\n" +
+    '- card: { title, subtitle?, body, metadata?: [{ label, value }], template?, templateData? }. Templates: "weather_forecast" (native weather widget), "task_progress" (live step tracker - update via ui_update on data.templateData; shape: { title, status: "in_progress"|"completed"|"failed", steps: [{ label, status: "pending"|"in_progress"|"completed"|"failed", detail? }] })\n' +
     '- table: { columns: [{ id, label, width? }], rows: [{ id, cells: Record<id, string | { text, icon?, iconColor?: "success"|"warning"|"error"|"muted" }>, selectable?, selected? }], selectionMode?: "none"|"single"|"multiple", caption? }\n' +
     '- form: { description?, fields: [{ id, type: "text"|"textarea"|"select"|"toggle"|"number"|"password", label, placeholder?, required?, defaultValue?, options?: [{ label, value }] }], submitLabel? }. Multi-page: { pages: [{ id, title, description?, fields }], pageLabels?: { next?, back?, submit? }, submitLabel? }\n' +
     '- list: { items: [{ id, title, subtitle?, icon?, selected? }], selectionMode: "single"|"multiple"|"none" }\n' +
@@ -91,7 +91,7 @@ export const uiShowTool: Tool = {
             type: "string",
             enum: ["inline", "panel"],
             description:
-              'Where to render the surface. "inline" embeds it in the chat message. "panel" shows a floating window. Defaults to "inline".',
+              'Where to render the surface. "inline" embeds it in the chat message. "panel" shows a floating window. Defaults to "inline". Prefer inline — only use panel when the user explicitly asks for a separate window.',
           },
           await_action: {
             type: "boolean",

package/src/util/device-id.ts

@@ -1,9 +1,16 @@
 /**
  * Device ID resolver.
  *
- * Reads or creates a stable per-device UUID stored in ~/.vellum/device.json.
- * The file is a JSON object (`{ "deviceId": "<uuid>" }`) extensible for
- * future per-device metadata.
+ * Reads or creates a stable per-device UUID stored in device.json under the
+ * Vellum config directory. The file is a JSON object (`{ "deviceId": "<uuid>" }`)
+ * extensible for future per-device metadata.
+ *
+ * Path resolution:
+ *   - Containerized (IS_CONTAINERIZED=true): uses BASE_DATA_DIR, which maps to a
+ *     persistent volume. Each container is effectively its own "device."
+ *   - Local (single or multi-instance): uses homedir() so all instances on the
+ *     same machine share a single device ID, even when BASE_DATA_DIR is set to
+ *     an instance-scoped directory.
  *
  * The value is cached in memory after the first successful read/write.
  * Falls back to a generated UUID if the file cannot be read or written.
@@ -14,18 +21,34 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { getBaseDataDir, getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "./logger.js";
 
 const log = getLogger("device-id");
 
 let cached: string | undefined;
 
+/**
+ * Resolve the base directory for device.json.
+ *
+ * In containerized environments, BASE_DATA_DIR points to a persistent volume
+ * and homedir() is ephemeral, so we must use BASE_DATA_DIR.
+ * In local environments (including multi-instance), homedir() is stable and
+ * shared across instances, giving a true per-machine device ID.
+ */
+export function getDeviceIdBaseDir(): string {
+  if (getIsContainerized()) {
+    return getBaseDataDir() || homedir();
+  }
+  return homedir();
+}
+
 /**
  * Get the stable device ID for this machine.
  *
  * Resolution order:
  *   1. Cached in-memory value (populated on first call)
- *   2. `deviceId` field from ~/.vellum/device.json
+ *   2. `deviceId` field from device.json
  *   3. Generate a new UUID, persist it to device.json, and return it
  *
  * On any read/write error the generated UUID is still cached so the
@@ -36,7 +59,7 @@ export function getDeviceId(): string {
     return cached;
   }
 
-  const vellumDir = join(homedir(), ".vellum");
+  const vellumDir = join(getDeviceIdBaseDir(), ".vellum");
   const filePath = join(vellumDir, "device.json");
   const generated = randomUUID();
 

package/src/util/platform.ts

@@ -366,6 +366,24 @@ export function getWorkspaceDir(): string {
   return join(getRootDir(), "workspace");
 }
 
+/**
+ * Returns a display-friendly workspace path for embedding in agent-facing text
+ * (skill bodies, tool descriptions). Replaces the home directory prefix with `~`
+ * so paths stay concise and portable across machines.
+ *
+ * Examples:
+ *   /Users/sidd/.vellum/workspace → ~/.vellum/workspace
+ *   /data/.vellum/workspace       → /data/.vellum/workspace
+ */
+export function getWorkspaceDirDisplay(): string {
+  const abs = getWorkspaceDir();
+  const home = homedir();
+  if (abs.startsWith(home + "/") || abs === home) {
+    return "~" + abs.slice(home.length);
+  }
+  return abs;
+}
+
 /** Returns ~/.vellum/workspace/config.json */
 export function getWorkspaceConfigPath(): string {
   return join(getWorkspaceDir(), "config.json");
@@ -381,6 +399,11 @@ export function getWorkspaceHooksDir(): string {
   return join(getWorkspaceDir(), "hooks");
 }
 
+/** Returns ~/.vellum/workspace/conversations */
+export function getConversationsDir(): string {
+  return join(getWorkspaceDir(), "conversations");
+}
+
 /** Returns the workspace path for a prompt file (e.g. IDENTITY.md, SOUL.md, USER.md). */
 export function getWorkspacePromptPath(file: string): string {
   return join(getWorkspaceDir(), file);
@@ -399,6 +422,7 @@ export function ensureDataDir(): void {
     join(root, "hooks"),
     join(workspace, "skills"),
     join(workspace, "embedding-models"),
+    join(workspace, "conversations"),
     // Data sub-dirs under workspace
     wsData,
     join(wsData, "db"),

package/src/util/pricing.ts

@@ -25,6 +25,7 @@ const PROVIDER_PRICING: Record<string, Record<string, ModelPricing>> = {
   },
   openai: {
     "gpt-5.4": { inputPer1M: 2.5, outputPer1M: 15 },
+    "gpt-5.4-mini": { inputPer1M: 0.5, outputPer1M: 3 },
     "gpt-5.4-nano": { inputPer1M: 0.2, outputPer1M: 1.25 },
     "gpt-5.2": { inputPer1M: 1.75, outputPer1M: 14 },
     "gpt-4o": { inputPer1M: 2.5, outputPer1M: 10 },

package/src/util/retry.ts

@@ -108,9 +108,7 @@ export function isRetryableNetworkError(error: unknown): boolean {
 
   // Fall back to message-based detection for errors without errno codes
   // (e.g. Bun's "The socket connection was closed unexpectedly")
-  if (
-    RETRYABLE_NETWORK_MESSAGE_PATTERNS.some((p) => p.test(error.message))
-  ) {
+  if (RETRYABLE_NETWORK_MESSAGE_PATTERNS.some((p) => p.test(error.message))) {
     return true;
   }
 

package/src/workspace/migrations/003-seed-device-id.ts

@@ -1,16 +1,15 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
-import { getBaseDataDir } from "../../config/env-registry.js";
+import { getDeviceIdBaseDir } from "../../util/device-id.js";
 import type { WorkspaceMigration } from "./types.js";
 
 export const seedDeviceIdMigration: WorkspaceMigration = {
   id: "003-seed-device-id",
   description:
-    "Seed ~/.vellum/device.json deviceId from the most recent lockfile installationId for continuity",
+    "Seed device.json deviceId from the most recent lockfile installationId for continuity",
   run(_workspaceDir: string): void {
-    const base = getBaseDataDir() || homedir();
+    const base = getDeviceIdBaseDir();
     const vellumDir = join(base, ".vellum");
     const devicePath = join(vellumDir, "device.json");
 

package/src/workspace/migrations/006-services-config.ts

@@ -83,6 +83,11 @@ export const servicesConfigMigration: WorkspaceMigration = {
       ...existingServices,
     };
 
+    // Legacy top-level fields (provider, model) are the user's actual
+    // configuration from before the services structure existed. If they're
+    // present as strings they take precedence over any `existingServices`
+    // values, which are just defaults written by backfillConfigDefaults().
+    // The spread preserves any extra keys that future backfills may add.
     services.inference = {
       ...(existingServices.inference ?? {}),
       mode: inferenceMode,

package/src/workspace/migrations/008-voice-timeout-and-max-steps.ts

@@ -0,0 +1,12 @@
+import type { WorkspaceMigration } from "./types.js";
+
+export const voiceTimeoutAndMaxStepsMigration: WorkspaceMigration = {
+  id: "008-voice-timeout-and-max-steps",
+  description:
+    "Add elevenlabs.conversationTimeoutSeconds and maxStepsPerSession to config schema (defaults handle new installs; macOS client syncs existing UserDefaults values on startup)",
+  run(_workspaceDir: string): void {
+    // No-op — schema defaults handle new installs.
+    // Existing users: macOS client will sync UserDefaults values
+    // to config on next startup via settings sync endpoints.
+  },
+};

package/src/workspace/migrations/009-backfill-conversation-disk-view.ts

@@ -0,0 +1,10 @@
+import { rebuildConversationDiskViewFromDb } from "./rebuild-conversation-disk-view.js";
+import type { WorkspaceMigration } from "./types.js";
+
+export const backfillConversationDiskViewMigration: WorkspaceMigration = {
+  id: "009-backfill-conversation-disk-view",
+  description: "Rebuild conversation disk view for existing conversations",
+  run(_workspaceDir: string): void {
+    rebuildConversationDiskViewFromDb();
+  },
+};

package/src/workspace/migrations/010-app-dir-rename.ts

@@ -0,0 +1,223 @@
+/**
+ * Workspace migration 010: Rename UUID-based app directories and files to
+ * human-readable slugified names.
+ *
+ * Inline slugify + dedup logic (not imported from app-store) so the migration
+ * remains stable even if runtime code changes in the future.
+ *
+ * Idempotent: safe to re-run after interruption at any point. Handles
+ * partially-renamed states (crash between JSON write and file rename).
+ */
+
+import { execSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import type { WorkspaceMigration } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Self-contained slug generation (do NOT import from app-store)
+// ---------------------------------------------------------------------------
+
+function slugify(name: string): string {
+  let slug = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  if (slug.length > 60) {
+    slug = slug.slice(0, 60).replace(/-+$/, "");
+  }
+
+  if (!slug) {
+    slug = `app-${randomUUID().slice(0, 8)}`;
+  }
+
+  return slug;
+}
+
+function generateUniqueDirName(name: string, usedNames: Set<string>): string {
+  const base = slugify(name);
+  if (!usedNames.has(base)) return base;
+  let counter = 2;
+  while (usedNames.has(`${base}-${counter}`)) {
+    counter++;
+  }
+  return `${base}-${counter}`;
+}
+
+/** Defense-in-depth: reject dirNames that could cause path traversal. */
+function isValidDirName(dirName: string): boolean {
+  return (
+    !!dirName &&
+    !dirName.includes("/") &&
+    !dirName.includes("\\") &&
+    !dirName.includes("..") &&
+    dirName === dirName.trim()
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Migration
+// ---------------------------------------------------------------------------
+
+export const appDirRenameMigration: WorkspaceMigration = {
+  id: "010-app-dir-rename",
+  description:
+    "Rename UUID-based app directories and files to human-readable slugified names",
+
+  run(workspaceDir: string): void {
+    const appsDir = join(workspaceDir, "data", "apps");
+    if (!existsSync(appsDir)) return;
+
+    // Read all JSON files (sorted for deterministic ordering)
+    const jsonFiles = readdirSync(appsDir)
+      .filter((f) => f.endsWith(".json"))
+      .sort();
+
+    if (jsonFiles.length === 0) return;
+
+    const usedNames = new Set<string>();
+
+    for (const jsonFile of jsonFiles) {
+      const jsonPath = join(appsDir, jsonFile);
+      let raw: string;
+      try {
+        raw = readFileSync(jsonPath, "utf-8");
+      } catch {
+        continue; // skip unreadable files
+      }
+
+      let parsed: {
+        id?: string;
+        name?: string;
+        dirName?: string;
+      };
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        continue; // skip malformed JSON
+      }
+
+      const appId = parsed.id;
+      const appName = parsed.name ?? "untitled";
+      if (!appId) continue;
+
+      // Check if already migrated: has dirName AND filesystem matches
+      if (parsed.dirName && isValidDirName(parsed.dirName)) {
+        const expectedJsonFile = `${parsed.dirName}.json`;
+        if (
+          jsonFile === expectedJsonFile &&
+          existsSync(join(appsDir, parsed.dirName))
+        ) {
+          // Already fully migrated -- just track the name
+          usedNames.add(parsed.dirName);
+          continue;
+        }
+
+        // Partially renamed: JSON has dirName but files may still be at old paths.
+        // Use the dirName from JSON but rename from wherever the files actually are.
+        const dirName = parsed.dirName;
+        usedNames.add(dirName);
+        renameAppFiles(appsDir, jsonFile, appId, dirName, parsed, raw);
+        continue;
+      }
+
+      // No dirName yet -- generate one
+      const dirName = generateUniqueDirName(appName, usedNames);
+      if (!isValidDirName(dirName)) continue; // safety check
+      usedNames.add(dirName);
+      renameAppFiles(appsDir, jsonFile, appId, dirName, parsed, raw);
+    }
+
+    // Best-effort git commit
+    try {
+      const gitDir = join(appsDir, ".git");
+      if (existsSync(gitDir)) {
+        execSync(
+          "git add -A && git commit -m 'Migration 010: rename app dirs to slugified names' --allow-empty",
+          {
+            cwd: appsDir,
+            stdio: "ignore",
+            timeout: 10_000,
+          },
+        );
+      }
+    } catch {
+      // Git failure is non-fatal -- log nothing since we don't have
+      // the logger available in migrations. The next commitAppChange()
+      // call will pick up the renamed files naturally.
+    }
+  },
+};
+
+/**
+ * Rename app files from their current location to dirName-based paths.
+ * Each step checks existence to handle partial completion.
+ */
+function renameAppFiles(
+  appsDir: string,
+  currentJsonFile: string,
+  appId: string,
+  dirName: string,
+  parsed: Record<string, unknown>,
+  _rawJson: string,
+): void {
+  const targetJsonFile = `${dirName}.json`;
+  const targetPreviewFile = `${dirName}.preview`;
+
+  // 1. Rename the app directory: {appId}/ -> {dirName}/
+  const oldDir = join(appsDir, appId);
+  const newDir = join(appsDir, dirName);
+  if (existsSync(oldDir) && !existsSync(newDir) && oldDir !== newDir) {
+    renameSync(oldDir, newDir);
+  } else if (!existsSync(newDir)) {
+    // Directory doesn't exist at either location -- create it
+    mkdirSync(newDir, { recursive: true });
+  }
+
+  // 2. Rename the preview file: {appId}.preview -> {dirName}.preview
+  const oldPreview = join(appsDir, `${appId}.preview`);
+  const newPreview = join(appsDir, targetPreviewFile);
+  if (
+    existsSync(oldPreview) &&
+    !existsSync(newPreview) &&
+    oldPreview !== newPreview
+  ) {
+    renameSync(oldPreview, newPreview);
+  }
+
+  // 3. Rename the JSON file: {currentFilename} -> {dirName}.json
+  //    Also update the dirName field in the JSON content.
+  const currentJsonPath = join(appsDir, currentJsonFile);
+  const targetJsonPath = join(appsDir, targetJsonFile);
+
+  // Update the JSON with dirName field
+  const updatedParsed = { ...parsed, dirName };
+  const updatedJson = JSON.stringify(updatedParsed, null, 2);
+
+  if (currentJsonFile !== targetJsonFile) {
+    // Write to new location, then remove old
+    writeFileSync(targetJsonPath, updatedJson, "utf-8");
+    if (existsSync(currentJsonPath) && currentJsonPath !== targetJsonPath) {
+      try {
+        unlinkSync(currentJsonPath);
+      } catch {
+        // Old file cleanup is best-effort
+      }
+    }
+  } else {
+    // Just update the content in place
+    writeFileSync(targetJsonPath, updatedJson, "utf-8");
+  }
+}