@powerformer/refly-cli 0.1.16 → 0.1.17

package/dist/bin/refly.js

@@ -34,10 +34,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_@swc+core@1.12.14_@swc+helpers@0.5.17__jiti@2.4.2_postcss@8.5.6_tsx@4.20.6_typescript@5.8.3_yaml@2.8.0/node_modules/tsup/assets/cjs_shims.js
+// ../../node_modules/.pnpm/tsup@8.5.1_@swc+core@1.12.14_@swc+helpers@0.5.17__jiti@2.6.1_postcss@8.5.6_tsx@4.20.6_typescript@5.8.3_yaml@2.8.0/node_modules/tsup/assets/cjs_shims.js
 var getImportMetaUrl, importMetaUrl;
 var init_cjs_shims = __esm({
-  "../../node_modules/.pnpm/tsup@8.5.1_@swc+core@1.12.14_@swc+helpers@0.5.17__jiti@2.4.2_postcss@8.5.6_tsx@4.20.6_typescript@5.8.3_yaml@2.8.0/node_modules/tsup/assets/cjs_shims.js"() {
+  "../../node_modules/.pnpm/tsup@8.5.1_@swc+core@1.12.14_@swc+helpers@0.5.17__jiti@2.6.1_postcss@8.5.6_tsx@4.20.6_typescript@5.8.3_yaml@2.8.0/node_modules/tsup/assets/cjs_shims.js"() {
     "use strict";
     getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
     importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
@@ -989,8 +989,8 @@ var require_command = __commonJS({
     init_cjs_shims();
     var EventEmitter = require("events").EventEmitter;
     var childProcess2 = require("child_process");
-    var path16 = require("path");
-    var fs20 = require("fs");
+    var path22 = require("path");
+    var fs27 = require("fs");
     var process8 = require("process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -1922,11 +1922,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path16.resolve(baseDir, baseName);
-          if (fs20.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path16.extname(baseName))) return void 0;
+          const localBin = path22.resolve(baseDir, baseName);
+          if (fs27.existsSync(localBin)) return localBin;
+          if (sourceExt.includes(path22.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs20.existsSync(`${localBin}${ext}`)
+            (ext) => fs27.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -1938,21 +1938,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs20.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs27.realpathSync(this._scriptPath);
           } catch (err) {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path16.resolve(
-            path16.dirname(resolvedScriptPath),
+          executableDir = path22.resolve(
+            path22.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path16.basename(
+            const legacyName = path22.basename(
               this._scriptPath,
-              path16.extname(this._scriptPath)
+              path22.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -1963,7 +1963,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path16.extname(executableFile));
+        launchWithNode = sourceExt.includes(path22.extname(executableFile));
         let proc;
         if (process8.platform !== "win32") {
           if (launchWithNode) {
@@ -2803,7 +2803,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path16.basename(filename, path16.extname(filename));
+        this._name = path22.basename(filename, path22.extname(filename));
         return this;
       }
       /**
@@ -2817,9 +2817,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path17) {
-        if (path17 === void 0) return this._executableDir;
-        this._executableDir = path17;
+      executableDir(path23) {
+        if (path23 === void 0) return this._executableDir;
+        this._executableDir = path23;
         return this;
       }
       /**
@@ -3055,15 +3055,22 @@ var require_commander = __commonJS({
 var paths_exports = {};
 __export(paths_exports, {
   claudeDirectoriesExist: () => claudeDirectoriesExist,
+  ensureClaudeSkillsDir: () => ensureClaudeSkillsDir,
   ensureDir: () => ensureDir,
+  ensureReflySkillsDir: () => ensureReflySkillsDir,
   ensureSkillsDir: () => ensureSkillsDir,
   getCacheDir: () => getCacheDir,
   getClaudeCommandsDir: () => getClaudeCommandsDir,
   getClaudeSkillDir: () => getClaudeSkillDir,
+  getClaudeSkillSymlinkPath: () => getClaudeSkillSymlinkPath,
+  getClaudeSkillsDir: () => getClaudeSkillsDir,
   getCliVersion: () => getCliVersion,
   getConfigPath: () => getConfigPath,
   getLegacyBuilderDir: () => getLegacyBuilderDir,
+  getReflyBaseSkillDir: () => getReflyBaseSkillDir,
   getReflyDir: () => getReflyDir,
+  getReflyDomainSkillDir: () => getReflyDomainSkillDir,
+  getReflySkillsDir: () => getReflySkillsDir,
   getSkillsDir: () => getSkillsDir
 });
 function getCliVersion() {
@@ -3119,6 +3126,33 @@ async function ensureSkillsDir() {
     fs.mkdirSync(dir, { recursive: true, mode: 448 });
   }
 }
+function getReflySkillsDir() {
+  return path.join(getReflyDir(), "skills");
+}
+function getReflyBaseSkillDir() {
+  return path.join(getReflySkillsDir(), "base");
+}
+function getReflyDomainSkillDir(skillName) {
+  return path.join(getReflySkillsDir(), skillName);
+}
+function getClaudeSkillsDir() {
+  return path.join(os.homedir(), ".claude", "skills");
+}
+function getClaudeSkillSymlinkPath(skillName) {
+  return path.join(getClaudeSkillsDir(), skillName);
+}
+function ensureReflySkillsDir() {
+  const dir = getReflySkillsDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  }
+}
+function ensureClaudeSkillsDir() {
+  const dir = getClaudeSkillsDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 493 });
+  }
+}
 var os, path, fs;
 var init_paths = __esm({
   "src/config/paths.ts"() {
@@ -3226,6 +3260,356 @@ var init_logger = __esm({
   }
 });
 
+// src/skill/symlink.ts
+var symlink_exports = {};
+__export(symlink_exports, {
+  createReflySkillWithSymlink: () => createReflySkillWithSymlink,
+  createSkillSymlink: () => createSkillSymlink,
+  deleteDomainSkillWithSymlink: () => deleteDomainSkillWithSymlink,
+  generateReflySkillMd: () => generateReflySkillMd,
+  initializeBaseSkillSymlink: () => initializeBaseSkillSymlink,
+  isSkillSymlinkValid: () => isSkillSymlinkValid,
+  listSkillSymlinks: () => listSkillSymlinks,
+  parseReflySkillMd: () => parseReflySkillMd,
+  removeSkillSymlink: () => removeSkillSymlink
+});
+function createSkillSymlink(skillName) {
+  const reflyPath = skillName === "refly" ? getReflyBaseSkillDir() : getReflyDomainSkillDir(skillName);
+  const claudePath = getClaudeSkillSymlinkPath(skillName);
+  try {
+    ensureReflySkillsDir();
+    ensureClaudeSkillsDir();
+    if (!fs4.existsSync(reflyPath)) {
+      return {
+        success: false,
+        skillName,
+        reflyPath,
+        claudePath,
+        error: `Source skill directory does not exist: ${reflyPath}`
+      };
+    }
+    if (fs4.existsSync(claudePath) || fs4.lstatSync(claudePath).isSymbolicLink()) {
+      const stat = fs4.lstatSync(claudePath);
+      if (stat.isSymbolicLink()) {
+        fs4.unlinkSync(claudePath);
+        logger.debug(`Removed existing symlink: ${claudePath}`);
+      } else if (stat.isDirectory()) {
+        logger.warn(`Cannot create symlink: ${claudePath} is a directory, not a symlink`);
+        return {
+          success: false,
+          skillName,
+          reflyPath,
+          claudePath,
+          error: `Target path is a directory, not a symlink: ${claudePath}`
+        };
+      }
+    }
+    fs4.symlinkSync(reflyPath, claudePath, "dir");
+    logger.info(`Created symlink: ${claudePath} -> ${reflyPath}`);
+    return {
+      success: true,
+      skillName,
+      reflyPath,
+      claudePath
+    };
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      try {
+        fs4.symlinkSync(reflyPath, claudePath, "dir");
+        logger.info(`Created symlink: ${claudePath} -> ${reflyPath}`);
+        return {
+          success: true,
+          skillName,
+          reflyPath,
+          claudePath
+        };
+      } catch (innerErr) {
+        return {
+          success: false,
+          skillName,
+          reflyPath,
+          claudePath,
+          error: innerErr.message
+        };
+      }
+    }
+    return {
+      success: false,
+      skillName,
+      reflyPath,
+      claudePath,
+      error: err.message
+    };
+  }
+}
+function removeSkillSymlink(skillName) {
+  const claudePath = getClaudeSkillSymlinkPath(skillName);
+  try {
+    if (!fs4.existsSync(claudePath)) {
+      logger.debug(`Symlink not found: ${claudePath}`);
+      return false;
+    }
+    const stat = fs4.lstatSync(claudePath);
+    if (!stat.isSymbolicLink()) {
+      logger.warn(`Not a symlink: ${claudePath}`);
+      return false;
+    }
+    fs4.unlinkSync(claudePath);
+    logger.info(`Removed symlink: ${claudePath}`);
+    return true;
+  } catch (err) {
+    logger.error(`Failed to remove symlink ${claudePath}:`, err);
+    return false;
+  }
+}
+function isSkillSymlinkValid(skillName) {
+  const claudePath = getClaudeSkillSymlinkPath(skillName);
+  const expectedTarget = skillName === "refly" ? getReflyBaseSkillDir() : getReflyDomainSkillDir(skillName);
+  try {
+    if (!fs4.existsSync(claudePath)) {
+      return { exists: false, isSymlink: false, isValid: false };
+    }
+    const stat = fs4.lstatSync(claudePath);
+    if (!stat.isSymbolicLink()) {
+      return { exists: true, isSymlink: false, isValid: false };
+    }
+    const target = fs4.readlinkSync(claudePath);
+    const resolvedTarget = path4.resolve(path4.dirname(claudePath), target);
+    const isValid2 = resolvedTarget === expectedTarget && fs4.existsSync(resolvedTarget);
+    return {
+      exists: true,
+      isSymlink: true,
+      isValid: isValid2,
+      target: resolvedTarget
+    };
+  } catch {
+    return { exists: false, isSymlink: false, isValid: false };
+  }
+}
+function initializeBaseSkillSymlink() {
+  const baseDir = getReflyBaseSkillDir();
+  ensureDir(baseDir);
+  ensureDir(path4.join(baseDir, "rules"));
+  return createSkillSymlink("refly");
+}
+function createReflySkillWithSymlink(skillName, skillMdContent) {
+  const skillDir = getReflyDomainSkillDir(skillName);
+  try {
+    ensureReflySkillsDir();
+    if (fs4.existsSync(skillDir)) {
+      return {
+        success: false,
+        skillName,
+        reflyPath: skillDir,
+        claudePath: getClaudeSkillSymlinkPath(skillName),
+        error: `Skill directory already exists: ${skillDir}`
+      };
+    }
+    fs4.mkdirSync(skillDir, { recursive: true, mode: 493 });
+    const skillMdPath = path4.join(skillDir, "SKILL.md");
+    fs4.writeFileSync(skillMdPath, skillMdContent, { encoding: "utf-8", mode: 420 });
+    logger.debug(`Created SKILL.md: ${skillMdPath}`);
+    return createSkillSymlink(skillName);
+  } catch (err) {
+    return {
+      success: false,
+      skillName,
+      reflyPath: skillDir,
+      claudePath: getClaudeSkillSymlinkPath(skillName),
+      error: err.message
+    };
+  }
+}
+function deleteDomainSkillWithSymlink(skillName) {
+  const symlinkRemoved = removeSkillSymlink(skillName);
+  const skillDir = getReflyDomainSkillDir(skillName);
+  let directoryRemoved = false;
+  try {
+    if (fs4.existsSync(skillDir)) {
+      fs4.rmSync(skillDir, { recursive: true, force: true });
+      directoryRemoved = true;
+      logger.info(`Removed skill directory: ${skillDir}`);
+    }
+  } catch (err) {
+    logger.error(`Failed to remove skill directory ${skillDir}:`, err);
+  }
+  return { symlinkRemoved, directoryRemoved };
+}
+function listSkillSymlinks() {
+  const claudeSkillsDir = getClaudeSkillsDir();
+  const results = [];
+  if (!fs4.existsSync(claudeSkillsDir)) {
+    return results;
+  }
+  try {
+    const entries = fs4.readdirSync(claudeSkillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path4.join(claudeSkillsDir, entry.name);
+      try {
+        const stat = fs4.lstatSync(fullPath);
+        if (stat.isSymbolicLink()) {
+          const target = fs4.readlinkSync(fullPath);
+          const resolvedTarget = path4.resolve(path4.dirname(fullPath), target);
+          const isValid2 = fs4.existsSync(resolvedTarget);
+          results.push({
+            name: entry.name,
+            claudePath: fullPath,
+            target: resolvedTarget,
+            isValid: isValid2
+          });
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+function generateReflySkillMd(options) {
+  const {
+    name,
+    displayName,
+    description,
+    skillId,
+    workflowId,
+    installationId,
+    triggers = [],
+    tags = [],
+    version = "1.0.0",
+    inputSchema,
+    outputSchema
+  } = options;
+  const frontmatterLines = ["---", `name: ${name}`];
+  frontmatterLines.push(`description: ${description}`);
+  if (tags.length > 0) {
+    frontmatterLines.push("tags:");
+    frontmatterLines.push(...tags.map((t) => `  - ${t}`));
+  }
+  frontmatterLines.push(`version: ${version}`);
+  frontmatterLines.push(`skillId: ${skillId}`);
+  frontmatterLines.push(`workflowId: ${workflowId}`);
+  if (installationId) {
+    frontmatterLines.push(`installationId: ${installationId}`);
+  }
+  if (triggers.length > 0) {
+    frontmatterLines.push("triggers:");
+    frontmatterLines.push(...triggers.map((t) => `  - ${t}`));
+  }
+  frontmatterLines.push("---");
+  const title = displayName || name.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+  const inputExample = inputSchema ? JSON.stringify(inputSchema, null, 2) : `{
+  "query": "your input here"
+}`;
+  const runCommand = installationId ? `refly skill run ${installationId} --input '${inputSchema ? JSON.stringify(inputSchema) : "{}"}'` : `refly workflow run ${workflowId} --input '${inputSchema ? JSON.stringify(inputSchema) : "{}"}'`;
+  const outputSection = outputSchema ? `The skill returns:
+
+\`\`\`json
+${JSON.stringify(outputSchema, null, 2)}
+\`\`\`` : "The skill returns the workflow execution result.";
+  const content = `
+
+# ${title}
+
+${description}
+
+## Usage
+
+This skill is executed via Refly CLI:
+
+\`\`\`bash
+${runCommand}
+\`\`\`
+
+## Input
+
+Provide input as JSON:
+
+\`\`\`json
+${inputExample}
+\`\`\`
+
+## Output
+
+${outputSection}
+
+## Rules
+
+For workflow operations, refer to the base skill rules:
+- Workflow: \`~/.claude/skills/refly/rules/workflow.md\`
+- Node: \`~/.claude/skills/refly/rules/node.md\`
+- File: \`~/.claude/skills/refly/rules/file.md\`
+`;
+  return frontmatterLines.join("\n") + content;
+}
+function parseReflySkillMd(content) {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+  if (!match) {
+    throw new Error("Invalid SKILL.md format: missing frontmatter");
+  }
+  const [, frontmatterStr, body] = match;
+  const meta = {};
+  const lines = frontmatterStr.split("\n");
+  let currentKey = null;
+  let currentArray = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("- ")) {
+      if (currentKey) {
+        currentArray.push(trimmed.slice(2).trim());
+      }
+      continue;
+    }
+    if (currentKey && currentArray.length > 0) {
+      meta[currentKey] = currentArray;
+      currentArray = [];
+      currentKey = null;
+    }
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex > 0) {
+      const key = trimmed.slice(0, colonIndex).trim();
+      const value = trimmed.slice(colonIndex + 1).trim();
+      if (value === "") {
+        currentKey = key;
+        currentArray = [];
+      } else {
+        meta[key] = value;
+      }
+    }
+  }
+  if (currentKey && currentArray.length > 0) {
+    meta[currentKey] = currentArray;
+  }
+  if (!meta.name) {
+    throw new Error('Invalid SKILL.md: missing required field "name"');
+  }
+  if (!meta.description) {
+    throw new Error('Invalid SKILL.md: missing required field "description"');
+  }
+  if (!meta.skillId) {
+    throw new Error('Invalid SKILL.md: missing required field "skillId"');
+  }
+  if (!meta.workflowId) {
+    throw new Error('Invalid SKILL.md: missing required field "workflowId"');
+  }
+  return {
+    meta,
+    body: body.trim(),
+    raw: content
+  };
+}
+var fs4, path4;
+var init_symlink = __esm({
+  "src/skill/symlink.ts"() {
+    "use strict";
+    init_cjs_shims();
+    fs4 = __toESM(require("fs"));
+    path4 = __toESM(require("path"));
+    init_paths();
+    init_logger();
+  }
+});
+
 // src/bin/refly.ts
 init_cjs_shims();
 
@@ -4023,6 +4407,10 @@ var OutputFormatter = class {
     if (error.code) {
       console.log(UI.keyValue("Code", UI.dim(error.code)));
     }
+    if (error.recoverable !== void 0) {
+      const recoverableText = error.recoverable ? "\u{1F504} Recoverable: Fix the parameter and retry the SAME command" : "\u274C Not recoverable: Consider a different approach";
+      console.log(UI.dim(`  ${recoverableText}`));
+    }
     if (error.details && Object.keys(error.details).length > 0) {
       console.log();
       console.log(UI.indent(UI.dim("Details:")));
@@ -4040,6 +4428,13 @@ var OutputFormatter = class {
       console.log();
       console.log(UI.dim(`  \u{1F4A1} Hint: ${error.hint}`));
     }
+    if (error.suggestedFix && Object.keys(error.suggestedFix).length > 0) {
+      console.log();
+      console.log(UI.dim("  \u2705 Suggested fix:"));
+      console.log(
+        UI.indent(this.formatObject(error.suggestedFix, 2), 4)
+      );
+    }
     console.log();
   }
   // === Workflow List Format (Phase 2: Docker-style table) ===
@@ -4265,6 +4660,9 @@ var OutputFormatter = class {
     if (error.hint) {
       console.log(UI.dim(`  ${error.hint}`));
     }
+    if (error.suggestedFix) {
+      console.log(UI.dim(`  fix: ${this.formatValue(error.suggestedFix)}`));
+    }
   }
   // === Plain Format ===
   outputPlain(type, payload) {
@@ -4282,6 +4680,9 @@ var OutputFormatter = class {
     if (error.hint) {
       console.log(`  hint: ${error.hint}`);
     }
+    if (error.suggestedFix) {
+      console.log(`  suggestedFix: ${this.formatValue(error.suggestedFix)}`);
+    }
   }
   // === Helper Methods ===
   humanizeType(type) {
@@ -4403,13 +4804,29 @@ function print(type, payload) {
   const formatter = getFormatter();
   formatter.success(type, payload);
 }
+function isRecoverableError(code, hasSuggestedFix) {
+  const recoverableCodes = [
+    "INVALID_INPUT",
+    "VALIDATION_ERROR",
+    "INVALID_NODE_INPUT",
+    "TIMEOUT",
+    // Can retry
+    "RATE_LIMIT"
+    // Can retry after waiting
+  ];
+  if (hasSuggestedFix) return true;
+  return recoverableCodes.includes(code);
+}
 function fail(code, message, options) {
   const formatter = getFormatter();
+  const recoverable = options?.recoverable ?? isRecoverableError(code, !!options?.suggestedFix);
   formatter.error({
     code,
     message,
     details: options?.details,
-    hint: options?.hint
+    hint: options?.hint,
+    suggestedFix: options?.suggestedFix,
+    recoverable
   });
   process.exit(options?.exitCode ?? getExitCode(code));
 }
@@ -4419,7 +4836,8 @@ function printError(code, message, options) {
     code,
     message,
     details: options?.details,
-    hint: options?.hint
+    hint: options?.hint,
+    suggestedFix: options?.suggestedFix
   });
 }
 function getExitCode(code) {
@@ -4467,8 +4885,8 @@ var ErrorCodes = {
 };
 
 // src/bin/refly.ts
-var fs19 = __toESM(require("fs"));
-var path15 = __toESM(require("path"));
+var fs26 = __toESM(require("fs"));
+var path21 = __toESM(require("path"));
 
 // src/commands/init.ts
 init_cjs_shims();
@@ -4973,8 +5391,8 @@ function getErrorMap() {
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 init_cjs_shims();
 var makeIssue = (params) => {
-  const { data, path: path16, errorMaps, issueData } = params;
-  const fullPath = [...path16, ...issueData.path || []];
+  const { data, path: path22, errorMaps, issueData } = params;
+  const fullPath = [...path22, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -5094,11 +5512,11 @@ var errorUtil;
 
 // ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path16, key) {
+  constructor(parent, value, path22, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path16;
+    this._path = path22;
     this._key = key;
   }
   get path() {
@@ -8706,23 +9124,41 @@ init_paths();
 
 // src/skill/installer.ts
 init_cjs_shims();
-var fs4 = __toESM(require("fs"));
-var path4 = __toESM(require("path"));
+var fs5 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
 init_paths();
 init_logger();
+init_symlink();
+function removeOldSkillDirectory() {
+  const claudeSkillPath = getClaudeSkillSymlinkPath("refly");
+  if (!fs5.existsSync(claudeSkillPath)) {
+    return;
+  }
+  try {
+    const stat = fs5.lstatSync(claudeSkillPath);
+    if (stat.isSymbolicLink()) {
+      fs5.unlinkSync(claudeSkillPath);
+    } else if (stat.isDirectory()) {
+      fs5.rmSync(claudeSkillPath, { recursive: true, force: true });
+      logger.info("Removed old skill directory");
+    }
+  } catch (err) {
+    logger.warn("Failed to remove old directory:", err);
+  }
+}
 function getPackageSkillDir() {
   const possiblePaths = [
-    path4.join(__dirname, "..", "..", "skill"),
+    path5.join(__dirname, "..", "..", "skill"),
     // Built package: dist/bin/../../skill
-    path4.join(__dirname, "..", "..", "..", "skill"),
+    path5.join(__dirname, "..", "..", "..", "skill"),
     // Development: dist/bin/../../../skill
-    path4.join(__dirname, "..", "skill")
+    path5.join(__dirname, "..", "skill")
     // Alternative: dist/../skill
   ];
   logger.debug("Looking for skill files, __dirname:", __dirname);
   for (const p of possiblePaths) {
-    const resolved = path4.resolve(p);
-    const exists = fs4.existsSync(resolved);
+    const resolved = path5.resolve(p);
+    const exists = fs5.existsSync(resolved);
     logger.debug(`  Checking path: ${resolved} - exists: ${exists}`);
     if (exists) {
       return resolved;
@@ -8734,42 +9170,52 @@ function installSkill() {
   const result = {
     skillInstalled: false,
     skillPath: null,
+    symlinkPath: null,
     commandsInstalled: false,
     commandsPath: null,
     version: getSkillVersion()
   };
   const sourceDir = getPackageSkillDir();
   logger.debug("Source skill directory:", sourceDir);
-  const targetDir = getClaudeSkillDir();
+  ensureReflySkillsDir();
+  const targetDir = getReflyBaseSkillDir();
   logger.debug("Target skill directory:", targetDir);
   try {
     ensureDir(targetDir);
-    ensureDir(path4.join(targetDir, "references"));
+    ensureDir(path5.join(targetDir, "rules"));
     logger.debug("Created target directories");
   } catch (err) {
     logger.error("Failed to create target directories:", err);
     throw err;
   }
-  const skillSource = path4.join(sourceDir, "SKILL.md");
-  const skillTarget = path4.join(targetDir, "SKILL.md");
+  const skillSource = path5.join(sourceDir, "SKILL.md");
+  const skillTarget = path5.join(targetDir, "SKILL.md");
   logger.debug(`Copying SKILL.md: ${skillSource} -> ${skillTarget}`);
-  if (fs4.existsSync(skillSource)) {
-    fs4.copyFileSync(skillSource, skillTarget);
+  if (fs5.existsSync(skillSource)) {
+    fs5.copyFileSync(skillSource, skillTarget);
     result.skillInstalled = true;
     result.skillPath = targetDir;
     logger.debug("SKILL.md copied successfully");
   } else {
     logger.warn("SKILL.md source not found:", skillSource);
   }
-  const refsSource = path4.join(sourceDir, "references");
-  const refsTarget = path4.join(targetDir, "references");
-  if (fs4.existsSync(refsSource)) {
-    const files = fs4.readdirSync(refsSource);
-    logger.debug(`Copying ${files.length} reference files`);
+  const refsSource = path5.join(sourceDir, "references");
+  const rulesTarget = path5.join(targetDir, "rules");
+  if (fs5.existsSync(refsSource)) {
+    const files = fs5.readdirSync(refsSource);
+    logger.debug(`Copying ${files.length} rule files`);
     for (const file of files) {
-      fs4.copyFileSync(path4.join(refsSource, file), path4.join(refsTarget, file));
+      fs5.copyFileSync(path5.join(refsSource, file), path5.join(rulesTarget, file));
     }
   }
+  removeOldSkillDirectory();
+  const symlinkResult = createSkillSymlink("refly");
+  if (symlinkResult.success) {
+    result.symlinkPath = symlinkResult.claudePath;
+    logger.info(`Created symlink: ${symlinkResult.claudePath} -> ${symlinkResult.reflyPath}`);
+  } else {
+    logger.warn(`Failed to create symlink: ${symlinkResult.error}`);
+  }
   const commandsDir = getClaudeCommandsDir();
   logger.debug("Commands directory:", commandsDir);
   ensureDir(commandsDir);
@@ -8781,20 +9227,21 @@ function installSkill() {
   updateSkillInfo(result.version);
   logger.info("Skill installation complete:", {
     skillInstalled: result.skillInstalled,
+    symlinkPath: result.symlinkPath,
     commandsInstalled: result.commandsInstalled
   });
   return result;
 }
 function installSlashCommands(sourceDir, targetDir) {
-  const commandsSource = path4.join(sourceDir, "..", "commands");
-  if (!fs4.existsSync(commandsSource)) {
+  const commandsSource = path5.join(sourceDir, "..", "commands");
+  if (!fs5.existsSync(commandsSource)) {
     return false;
   }
   try {
-    const files = fs4.readdirSync(commandsSource);
+    const files = fs5.readdirSync(commandsSource);
     for (const file of files) {
       if (file.endsWith(".md")) {
-        fs4.copyFileSync(path4.join(commandsSource, file), path4.join(targetDir, file));
+        fs5.copyFileSync(path5.join(commandsSource, file), path5.join(targetDir, file));
       }
     }
     return files.length > 0;
@@ -8804,8 +9251,8 @@ function installSlashCommands(sourceDir, targetDir) {
 }
 function getSkillVersion() {
   try {
-    const skillPath = path4.join(getPackageSkillDir(), "SKILL.md");
-    const content = fs4.readFileSync(skillPath, "utf-8");
+    const skillPath = path5.join(getPackageSkillDir(), "SKILL.md");
+    const content = fs5.readFileSync(skillPath, "utf-8");
     const versionMatch = content.match(/version:\s*(\d+\.\d+\.\d+)/);
     if (versionMatch) {
       return versionMatch[1];
@@ -8813,23 +9260,26 @@ function getSkillVersion() {
   } catch {
   }
   try {
-    const pkgPath = path4.join(__dirname, "..", "..", "package.json");
-    const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf-8"));
+    const pkgPath = path5.join(__dirname, "..", "..", "package.json");
+    const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
     return pkg.version;
   } catch {
     return "0.1.0";
   }
 }
 function isSkillInstalled() {
-  const skillPath = path4.join(getClaudeSkillDir(), "SKILL.md");
-  if (!fs4.existsSync(skillPath)) {
+  const skillPath = path5.join(getReflyBaseSkillDir(), "SKILL.md");
+  if (!fs5.existsSync(skillPath)) {
     return { installed: false, upToDate: false };
   }
   const currentVersion = getSkillVersion();
+  const { isSkillSymlinkValid: isSkillSymlinkValid2 } = (init_symlink(), __toCommonJS(symlink_exports));
+  const symlinkStatus = isSkillSymlinkValid2("refly");
   return {
     installed: true,
     upToDate: true,
-    currentVersion
+    currentVersion,
+    symlinkValid: symlinkStatus.isValid
   };
 }
 
@@ -9314,14 +9764,14 @@ var baseOpen = async (options) => {
   }
   const subprocess = import_node_child_process5.default.spawn(command, cliArguments, childProcessOptions);
   if (options.wait) {
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       subprocess.once("error", reject);
       subprocess.once("close", (exitCode) => {
         if (!options.allowNonzeroExitCode && exitCode > 0) {
           reject(new Error(`Exited with code ${exitCode}`));
           return;
         }
-        resolve6(subprocess);
+        resolve7(subprocess);
       });
     });
   }
@@ -9397,19 +9847,20 @@ var open_default = open;
 
 // src/api/client.ts
 init_cjs_shims();
-var fs10 = __toESM(require("fs"));
+var fs11 = __toESM(require("fs"));
 var import_node_fs4 = require("fs");
-var path6 = __toESM(require("path"));
+var path7 = __toESM(require("path"));
 var import_mime = __toESM(require("mime"));
 
 // src/utils/errors.ts
 init_cjs_shims();
 var CLIError = class extends Error {
-  constructor(code, message, details, hint) {
+  constructor(code, message, details, hint, suggestedFix) {
     super(message);
     this.code = code;
     this.details = details;
     this.hint = hint;
+    this.suggestedFix = suggestedFix;
     this.name = "CLIError";
   }
 };
@@ -9427,10 +9878,10 @@ var NetworkError = class extends CLIError {
 // src/api/client.ts
 init_logger();
 var DEFAULT_TIMEOUT = 3e4;
-async function apiRequest(path16, options = {}) {
+async function apiRequest(path22, options = {}) {
   const { method = "GET", body, query, timeout = DEFAULT_TIMEOUT, requireAuth = true } = options;
   const endpoint = getApiEndpoint();
-  let url = `${endpoint}${path16}`;
+  let url = `${endpoint}${path22}`;
   if (query && Object.keys(query).length > 0) {
     const params = new URLSearchParams(query);
     url = `${url}?${params.toString()}`;
@@ -9468,7 +9919,7 @@ async function apiRequest(path16, options = {}) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeout);
   try {
-    logger.debug(`API Request: ${method} ${path16}`);
+    logger.debug(`API Request: ${method} ${path22}`);
     const response = await fetch(url, {
       method,
       headers,
@@ -9560,7 +10011,8 @@ function mapAPIError(status, response) {
       cliError.code || "UNKNOWN",
       cliError.message || "Unknown error",
       void 0,
-      cliError.hint
+      cliError.hint,
+      cliError.suggestedFix
     );
   }
   const errCode = response.errCode ?? response.error ?? "UNKNOWN";
@@ -9582,10 +10034,10 @@ function mapAPIError(status, response) {
   }
   return new CLIError(errCode, errMsg);
 }
-async function apiRequestStream(path16, options = {}) {
+async function apiRequestStream(path22, options = {}) {
   const { timeout = 3e5 } = options;
   const endpoint = getApiEndpoint();
-  const url = `${endpoint}${path16}`;
+  const url = `${endpoint}${path22}`;
   const headers = {
     "User-Agent": "refly-cli/0.1.0"
   };
@@ -9616,7 +10068,7 @@ async function apiRequestStream(path16, options = {}) {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeout);
   try {
-    logger.debug(`API Stream Request: GET ${path16}`);
+    logger.debug(`API Stream Request: GET ${path22}`);
     const response = await fetch(url, {
       method: "GET",
       headers,
@@ -9711,7 +10163,7 @@ async function uploadToPresignedUrl(presignedUrl, filePath, contentType, retryCo
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     try {
-      const fileBuffer = await fs10.promises.readFile(filePath);
+      const fileBuffer = await fs11.promises.readFile(filePath);
       const response = await fetch(presignedUrl, {
         method: "PUT",
         headers: {
@@ -9769,7 +10221,7 @@ async function apiGetWorkflow(workflowId) {
   return apiRequest(`/v1/cli/workflow/${workflowId}`);
 }
 async function apiUploadDriveFile(filePath, canvasId, options) {
-  const filename = path6.basename(filePath);
+  const filename = path7.basename(filePath);
   const mimeType = getMimeType(filePath);
   const fileStats = (0, import_node_fs4.statSync)(filePath);
   logger.debug(`Starting presigned upload: ${filename} (${fileStats.size} bytes)`);
@@ -10016,7 +10468,7 @@ async function getUserInfoFromToken(accessToken) {
   };
 }
 function sleep(ms) {
-  return new Promise((resolve6) => setTimeout(resolve6, ms));
+  return new Promise((resolve7) => setTimeout(resolve7, ms));
 }
 
 // src/commands/init.ts
@@ -10083,6 +10535,7 @@ var initCommand = new Command("init").description("Initialize Refly CLI, install
         apiEndpoint,
         skillInstalled: installResult.skillInstalled,
         skillPath: installResult.skillPath,
+        symlinkPath: installResult.symlinkPath,
         commandsInstalled: installResult.commandsInstalled,
         commandsPath: installResult.commandsPath,
         version: installResult.version
@@ -10135,7 +10588,10 @@ var initCommand = new Command("init").description("Initialize Refly CLI, install
         configDir: getReflyDir(),
         apiEndpoint,
         skillInstalled: installResult.skillInstalled,
+        skillPath: installResult.skillPath,
+        symlinkPath: installResult.symlinkPath,
         commandsInstalled: installResult.commandsInstalled,
+        commandsPath: installResult.commandsPath,
         version: installResult.version,
         authenticated: !!(getAccessToken() || getApiKey())
       });
@@ -10270,7 +10726,7 @@ var import_node_child_process6 = require("child_process");
 var import_node_fs5 = __toESM(require("fs"));
 init_logger();
 init_paths();
-var CLI_VERSION = "0.1.16";
+var CLI_VERSION = "0.1.17";
 var NPM_TAG = "test";
 function compareSemver(a, b) {
   const parseVersion = (v) => {
@@ -10526,16 +10982,16 @@ configCommand.action(() => {
   };
   ok("config", safeConfig);
 });
-function getNestedValue(obj, path16) {
-  return path16.split(".").reduce((current, key) => {
+function getNestedValue(obj, path22) {
+  return path22.split(".").reduce((current, key) => {
     if (current && typeof current === "object" && key in current) {
       return current[key];
     }
     return void 0;
   }, obj);
 }
-function setNestedValue(obj, path16, value) {
-  const keys = path16.split(".");
+function setNestedValue(obj, path22, value) {
+  const keys = path22.split(".");
   const lastKey = keys.pop();
   let current = obj;
   for (const key of keys) {
@@ -10640,14 +11096,25 @@ var workflowCreateCommand = new Command("create").description("Create a workflow
       spec = Array.isArray(parsed) ? { nodes: parsed } : parsed;
     } catch {
       fail(ErrorCodes.INVALID_INPUT, "Invalid JSON in --spec", {
-        hint: "Ensure the spec is valid JSON"
+        hint: `Spec format: '[{"id": "node1", "type": "skill", "query": "task description", "toolsetKeys": ["web_search"]}]'
+Or full format: '{"nodes": [...], "edges": [...]}'`,
+        suggestedFix: {
+          field: "--spec",
+          format: "json-array | json-object",
+          example: '[{"id": "node1", "type": "skill", "query": "task description", "toolsetKeys": ["web_search"]}]'
+        }
       });
       return;
     }
     const validationError = validateSimplifiedSpec(spec);
     if (validationError) {
       fail(ErrorCodes.INVALID_INPUT, validationError, {
-        hint: 'Use simplified format: [{"id":"node1","type":"skill","query":"...","toolsetKeys":["tool_name"],"dependsOn":["other_node"]}]'
+        hint: 'Use simplified format: [{"id":"node1","type":"skill","query":"...","toolsetKeys":["tool_name"],"dependsOn":["other_node"]}]',
+        suggestedFix: {
+          field: "--spec",
+          format: "json-array",
+          example: '[{"id":"node1","type":"skill","query":"...","toolsetKeys":["tool_name"],"dependsOn":["other_node"]}]'
+        }
       });
       return;
     }
@@ -10667,7 +11134,11 @@ var workflowCreateCommand = new Command("create").description("Create a workflow
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -10729,7 +11200,13 @@ var workflowGenerateCommand = new Command("generate").description("Generate a wo
         variables = JSON.parse(options.variables);
       } catch {
         fail(ErrorCodes.INVALID_INPUT, "Invalid JSON in --variables", {
-          hint: "Ensure the variables parameter is valid JSON"
+          hint: `Variables format: '[{"name": "varName", "variableType": "string", "description": "desc", "required": true}]'
+Variable types: "string" (text input) or "resource" (file input)`,
+          suggestedFix: {
+            field: "--variables",
+            format: "json-array",
+            example: '[{"name": "varName", "variableType": "string", "description": "desc", "required": true}]'
+          }
         });
       }
     }
@@ -10782,7 +11259,8 @@ var workflowGenerateCommand = new Command("generate").description("Generate a wo
     if (error instanceof CLIError) {
       fail(error.code, error.message, {
         details: { ...error.details, cleanedUp: cleanupResult?.deleted },
-        hint: error.hint
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
       });
     }
     fail(
@@ -10820,7 +11298,11 @@ var workflowListCommand = new Command("list").description("List all workflows").
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -10837,133 +11319,15 @@ var workflowGetCommand = new Command("get").description("Get workflow details").
     ok("workflow.get", result);
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
-    }
-    fail(
-      ErrorCodes.INTERNAL_ERROR,
-      error instanceof Error ? error.message : "Failed to get workflow"
-    );
-  }
-});
-
-// src/commands/workflow/edit.ts
-init_cjs_shims();
-function transformOperations(ops) {
-  const opMapping = {
-    add: "add_node",
-    remove: "remove_node",
-    update: "update_node",
-    addEdge: "add_edge",
-    removeEdge: "remove_edge",
-    // Also support direct backend format
-    add_node: "add_node",
-    remove_node: "remove_node",
-    update_node: "update_node",
-    add_edge: "add_edge",
-    remove_edge: "remove_edge"
-  };
-  return ops.map((op) => {
-    const { op: opType, ...rest } = op;
-    const backendType = opMapping[opType];
-    if (!backendType) {
-      throw new Error(`Unknown operation type: ${opType}`);
-    }
-    return {
-      type: backendType,
-      ...rest
-    };
-  });
-}
-var workflowEditCommand = new Command("edit").description("Edit an existing workflow").argument("<workflowId>", "Workflow ID or URL").option("--name <name>", "New workflow name").option("--ops <json>", "Node/edge operations as JSON array").option("--variables <json>", "Workflow variables as JSON array").option("--toolsets <keys>", 'Toolset inventory keys (comma-separated, e.g., "tavily,fal_audio")').option("--auto-layout", "Enable auto-layout to prevent node overlapping").action(async (workflowIdOrUrl, options) => {
-  try {
-    let workflowId = workflowIdOrUrl;
-    if (workflowIdOrUrl.includes("/workflow/")) {
-      const match = workflowIdOrUrl.match(/\/workflow\/(c-[a-z0-9]+)/);
-      if (match) {
-        workflowId = match[1];
-      }
-    }
-    const body = {};
-    if (options.name) {
-      body.name = options.name;
-    }
-    let toolsetKeys;
-    if (options.toolsets) {
-      toolsetKeys = options.toolsets.split(",").map((k) => k.trim()).filter((k) => k.length > 0);
-    }
-    if (options.ops) {
-      try {
-        const rawOps = JSON.parse(options.ops);
-        body.operations = transformOperations(rawOps);
-        if (toolsetKeys && toolsetKeys.length > 0 && body.operations) {
-          body.operations = body.operations.map((op) => {
-            if (op.type === "add_node" && op.node) {
-              const node = op.node;
-              const data = node.data || {};
-              const metadata = data.metadata || {};
-              return {
-                ...op,
-                node: {
-                  ...node,
-                  data: {
-                    ...data,
-                    metadata: {
-                      ...metadata,
-                      toolsetKeys
-                    }
-                  }
-                }
-              };
-            }
-            return op;
-          });
-        }
-      } catch (error) {
-        fail(ErrorCodes.INVALID_INPUT, `Invalid operations: ${error.message}`, {
-          hint: "Ensure the operations are a valid JSON array with correct op types"
-        });
-      }
-    }
-    if (options.variables) {
-      try {
-        body.variables = JSON.parse(options.variables);
-      } catch {
-        fail(ErrorCodes.INVALID_INPUT, "Invalid JSON in --variables", {
-          hint: "Ensure the variables are a valid JSON array"
-        });
-      }
-    }
-    if (!options.name && !options.ops && !options.variables) {
-      fail(ErrorCodes.INVALID_INPUT, "No update options provided", {
-        hint: "Use --name, --ops, --variables, or --toolsets to specify what to update"
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
       });
     }
-    let endpoint = `/v1/cli/workflow/${workflowId}`;
-    const queryParams = [];
-    if (toolsetKeys && toolsetKeys.length > 0) {
-      queryParams.push("resolveToolsetKeys=true");
-    }
-    if (options.autoLayout) {
-      queryParams.push("autoLayout=true");
-    }
-    if (queryParams.length > 0) {
-      endpoint += `?${queryParams.join("&")}`;
-    }
-    await apiRequest(endpoint, {
-      method: "PATCH",
-      body
-    });
-    ok("workflow.edit", {
-      message: "Workflow updated successfully",
-      workflowId
-    });
-  } catch (error) {
-    if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
-    }
     fail(
       ErrorCodes.INTERNAL_ERROR,
-      error instanceof Error ? error.message : "Failed to edit workflow"
+      error instanceof Error ? error.message : "Failed to get workflow"
     );
   }
 });
@@ -10981,7 +11345,11 @@ var workflowDeleteCommand = new Command("delete").description("Delete a workflow
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -10994,14 +11362,14 @@ var workflowDeleteCommand = new Command("delete").description("Delete a workflow
 init_cjs_shims();
 var readline2 = __toESM(require("readline/promises"));
 var import_node_process8 = require("process");
-var path9 = __toESM(require("path"));
+var path10 = __toESM(require("path"));
 
 // src/utils/prompt.ts
 init_cjs_shims();
 var readline = __toESM(require("readline/promises"));
 var import_node_process7 = require("process");
-var fs12 = __toESM(require("fs"));
-var path7 = __toESM(require("path"));
+var fs13 = __toESM(require("fs"));
+var path8 = __toESM(require("path"));
 function isInteractive() {
   return process.stdin?.isTTY ?? false;
 }
@@ -11025,12 +11393,12 @@ async function promptForFilePath(variableName, resourceTypes, isRequired) {
         const homeDir = process.env.HOME || process.env.USERPROFILE || "";
         resolvedPath = resolvedPath.replace("~", homeDir);
       }
-      resolvedPath = path7.resolve(resolvedPath);
-      if (!fs12.existsSync(resolvedPath)) {
+      resolvedPath = path8.resolve(resolvedPath);
+      if (!fs13.existsSync(resolvedPath)) {
         console.log(`    File not found: ${resolvedPath}`);
         continue;
       }
-      const stats = fs12.statSync(resolvedPath);
+      const stats = fs13.statSync(resolvedPath);
       if (!stats.isFile()) {
         console.log(`    Not a file: ${resolvedPath}`);
         continue;
@@ -11044,12 +11412,12 @@ async function promptForFilePath(variableName, resourceTypes, isRequired) {
 
 // src/utils/file-type.ts
 init_cjs_shims();
-var path8 = __toESM(require("path"));
+var path9 = __toESM(require("path"));
 var IMAGE_EXTENSIONS = ["jpg", "jpeg", "png", "gif", "webp", "svg", "bmp", "ico", "tiff", "tif"];
 var VIDEO_EXTENSIONS = ["mp4", "webm", "mov", "avi", "mkv", "flv", "wmv", "m4v"];
 var AUDIO_EXTENSIONS = ["mp3", "wav", "ogg", "flac", "m4a", "aac", "wma", "opus"];
 function determineFileType(filePath, mimeType) {
-  const ext = path8.extname(filePath).slice(1).toLowerCase();
+  const ext = path9.extname(filePath).slice(1).toLowerCase();
   if (IMAGE_EXTENSIONS.includes(ext)) {
     return "image";
   }
@@ -11104,12 +11472,12 @@ async function pollToolsStatus(workflowId, maxWaitTime = 15 * 60 * 1e3, pollInte
         );
         previousRemainingCount = remainingCount;
       }
-      await new Promise((resolve6) => setTimeout(resolve6, pollInterval));
+      await new Promise((resolve7) => setTimeout(resolve7, pollInterval));
     } catch (error) {
       console.log(`
 \u26A0\uFE0F  Failed to check authorization status: ${error.message}`);
       console.log("Continuing to wait...");
-      await new Promise((resolve6) => setTimeout(resolve6, pollInterval));
+      await new Promise((resolve7) => setTimeout(resolve7, pollInterval));
     }
   }
   console.log("\n\u23F0 Timeout waiting for tool authorization.");
@@ -11149,24 +11517,57 @@ async function collectFileVariables(workflowId, existingInput, noPrompt) {
   if (resourceVars.length === 0) {
     return [];
   }
-  const providedIds = new Set(existingInput.map((v) => v.variableId).filter(Boolean));
-  const providedNames = new Set(existingInput.map((v) => v.name).filter(Boolean));
+  const invalidFormatVars = [];
   const missingVars = resourceVars.filter((v) => {
-    if (v.variableId && providedIds.has(v.variableId)) return false;
-    if (v.name && providedNames.has(v.name)) return false;
-    return true;
+    const provided = existingInput.find(
+      (input3) => v.variableId && input3.variableId === v.variableId || v.name && input3.name === v.name
+    );
+    if (!provided) {
+      return true;
+    }
+    const values = provided.value;
+    if (!Array.isArray(values) || values.length === 0) {
+      invalidFormatVars.push({
+        name: v.name,
+        reason: "value must be an array with at least one file"
+      });
+      return true;
+    }
+    const hasValidFileId = values.some((val) => {
+      const fileId = val?.resource?.fileId || val?.fileId;
+      return typeof fileId === "string" && fileId.length > 0;
+    });
+    if (!hasValidFileId) {
+      invalidFormatVars.push({
+        name: v.name,
+        reason: "no valid fileId found in value"
+      });
+      return true;
+    }
+    return false;
   });
   if (missingVars.length === 0) {
     return [];
   }
   if (noPrompt || !isInteractive()) {
-    const names = missingVars.map((v) => v.name).join(", ");
-    throw new CLIError(
-      ErrorCodes.INVALID_INPUT,
-      `Missing required file variables: ${names}`,
-      void 0,
-      "Provide files via --input or run interactively without --no-prompt"
-    );
+    const missingNames = missingVars.map((v) => v.name);
+    const formatIssues = invalidFormatVars.filter((f) => missingNames.includes(f.name));
+    let message;
+    let hint;
+    if (formatIssues.length > 0) {
+      const details = formatIssues.map((f) => `  - ${f.name}: ${f.reason}`).join("\n");
+      message = `Invalid format for file variables:
+${details}`;
+      hint = `For file variables, use format: '{"varName": "df-fileId"}' or '{"varName": [{"fileId": "df-xxx"}]}'`;
+    } else {
+      message = `Missing required file variables: ${missingNames.join(", ")}`;
+      hint = "Provide files via --input or run interactively without --no-prompt";
+    }
+    throw new CLIError(ErrorCodes.INVALID_INPUT, message, void 0, hint, {
+      field: "--input",
+      format: "json-object",
+      example: '{"fileVar": "df-fileId"}'
+    });
   }
   console.log("");
   console.log("This workflow requires file inputs:");
@@ -11180,7 +11581,7 @@ async function collectFileVariables(workflowId, existingInput, noPrompt) {
     if (!filePath) {
       continue;
     }
-    const filename = path9.basename(filePath);
+    const filename = path10.basename(filePath);
     process.stdout.write(`  Uploading ${filename}...`);
     try {
       const uploadResult = await apiUploadDriveFile(filePath, workflowId);
@@ -11216,18 +11617,79 @@ async function collectFileVariables(workflowId, existingInput, noPrompt) {
   console.log("");
   return uploadedVars;
 }
-async function runWorkflow(workflowId, options) {
-  let inputVars = [];
-  try {
-    const parsed = JSON.parse(options?.input ?? "{}");
+function convertKeyValueToVariables(obj, workflow) {
+  const variables = [];
+  for (const [name, rawValue] of Object.entries(obj)) {
+    const varDef = workflow?.variables?.find((v) => v.name === name || v.variableId === name);
+    const isResourceVar = varDef?.variableType === "resource";
+    const looksLikeFileId = typeof rawValue === "string" && rawValue.startsWith("df-");
+    const looksLikeFileArray = Array.isArray(rawValue) && rawValue.length > 0 && typeof rawValue[0] === "object" && rawValue[0] !== null && ("fileId" in rawValue[0] || "type" in rawValue[0]);
+    if (isResourceVar || looksLikeFileId || looksLikeFileArray) {
+      let fileValues = [];
+      if (typeof rawValue === "string") {
+        fileValues = [
+          {
+            type: "resource",
+            resource: { fileId: rawValue }
+          }
+        ];
+      } else if (Array.isArray(rawValue)) {
+        fileValues = rawValue.map((item) => ({
+          type: "resource",
+          resource: { fileId: item.fileId || item.resource?.fileId || "" }
+        }));
+      }
+      variables.push({
+        variableId: varDef?.variableId,
+        name,
+        variableType: "resource",
+        value: fileValues,
+        required: varDef?.required
+      });
+    } else {
+      let value = [];
+      if (typeof rawValue === "string") {
+        value = [{ type: "text", text: rawValue }];
+      } else if (Array.isArray(rawValue)) {
+        value = rawValue;
+      }
+      variables.push({
+        variableId: varDef?.variableId,
+        name,
+        variableType: "string",
+        value,
+        required: varDef?.required
+      });
+    }
+  }
+  return variables;
+}
+async function runWorkflow(workflowId, options) {
+  let workflow;
+  try {
+    workflow = await apiGetWorkflow(workflowId);
+  } catch {
+  }
+  let inputVars = [];
+  try {
+    const parsed = JSON.parse(options?.input ?? "{}");
     if (Array.isArray(parsed)) {
       inputVars = parsed;
     } else if (parsed.variables && Array.isArray(parsed.variables)) {
       inputVars = parsed.variables;
+    } else if (typeof parsed === "object" && parsed !== null && Object.keys(parsed).length > 0) {
+      inputVars = convertKeyValueToVariables(parsed, workflow);
     }
   } catch {
     fail(ErrorCodes.INVALID_INPUT, "Invalid JSON in --input", {
-      hint: 'Ensure the input is valid JSON, e.g., {"variables":[...]}'
+      hint: `Ensure the input is valid JSON. Supported formats:
+  - Simple: '{"varName": "value", "fileVar": "df-xxx"}'
+  - Array: '[{"name": "varName", "value": [...]}]'`,
+      suggestedFix: {
+        field: "--input",
+        format: "json-object | json-array",
+        example: '{"varName": "value", "fileVar": "df-xxx"}'
+      }
     });
     return;
   }
@@ -11322,7 +11784,11 @@ var workflowRunCommand = new Command("run").description("Start a workflow execut
     await runWorkflow(workflowId, options);
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11365,7 +11831,11 @@ var workflowRunsCommand = new Command("runs").description("List workflow executi
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11387,7 +11857,11 @@ var workflowAbortCommand = new Command("abort").description("Abort a running wor
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11471,7 +11945,7 @@ var workflowStatusCommand = new Command("status").description("Get detailed work
       });
       prevStatus = status;
       while (status.status === "init" || status.status === "executing") {
-        await new Promise((resolve6) => setTimeout(resolve6, pollInterval));
+        await new Promise((resolve7) => setTimeout(resolve7, pollInterval));
         status = await fetchStatus();
         if (options.full || hasStatusChanged(prevStatus, status)) {
           if (options.full) {
@@ -11507,7 +11981,11 @@ var workflowStatusCommand = new Command("status").description("Get detailed work
     }
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11580,7 +12058,11 @@ var workflowDetailCommand = new Command("detail").description("Get detailed work
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11632,7 +12114,11 @@ var workflowToolcallsCommand = new Command("toolcalls").description("Get all too
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11664,7 +12150,11 @@ var workflowToolsetKeysCommand = new Command("toolset-keys").description("List a
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11704,7 +12194,11 @@ var workflowLayoutCommand = new Command("layout").description("Auto-layout workf
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11751,7 +12245,11 @@ var workflowNodesCommand = new Command("nodes").description("List all nodes in a
     ok("workflow.nodes", output3);
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11812,7 +12310,11 @@ var workflowNodeGetCommand = new Command("node").description("Get single node in
     ok("workflow.node", output3);
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11821,6 +12323,289 @@ var workflowNodeGetCommand = new Command("node").description("Get single node in
   }
 });
 
+// src/commands/workflow/node-add.ts
+init_cjs_shims();
+var workflowNodeAddCommand = new Command("node-add").description("Add a node to a workflow").argument("<workflowId>", "Workflow ID (c-xxx)").requiredOption("--type <type>", "Node type (skillResponse, start, document, resource, memo)").option("--id <nodeId>", "Custom node ID (auto-generated if not provided)").option("--query <query>", "Query/prompt for the node").option("--title <title>", "Node title").option("--toolset-keys <keys>", 'Comma-separated toolset keys (e.g., "web_search,execute_code")').option("--position <x,y>", 'Node position as "x,y" (default: 0,0)').option("--connect-from <nodeId>", "Connect from this node (creates edge)").option("--connect-to <nodeId>", "Connect to this node (creates edge)").option("--resolve-toolset-keys", "Resolve toolset keys to full IDs").option("--auto-layout", "Enable auto-layout to prevent overlapping").action(async (workflowId, options) => {
+  if (!workflowId.startsWith("c-")) {
+    fail(ErrorCodes.INVALID_INPUT, `Invalid workflow ID: ${workflowId}`, {
+      hint: 'Workflow ID should start with "c-"',
+      suggestedFix: {
+        field: "<workflowId>",
+        format: "c-<id>",
+        example: "c-123456"
+      }
+    });
+    return;
+  }
+  const validTypes = ["skillResponse", "start", "document", "resource", "memo"];
+  if (!validTypes.includes(options.type)) {
+    fail(ErrorCodes.INVALID_INPUT, `Invalid node type: ${options.type}`, {
+      hint: `Valid types: ${validTypes.join(", ")}`,
+      suggestedFix: {
+        field: "--type",
+        format: "string",
+        example: "skillResponse"
+      }
+    });
+    return;
+  }
+  try {
+    const nodeId = options.id || `node-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let position = { x: 0, y: 0 };
+    if (options.position) {
+      const parts = options.position.split(",").map((p) => Number.parseFloat(p.trim()));
+      if (parts.length === 2 && !Number.isNaN(parts[0]) && !Number.isNaN(parts[1])) {
+        position = { x: parts[0], y: parts[1] };
+      }
+    }
+    const metadata = {};
+    if (options.query) {
+      metadata.query = options.query;
+    }
+    if (options.title) {
+      metadata.title = options.title;
+    }
+    if (options.toolsetKeys) {
+      metadata.toolsetKeys = options.toolsetKeys.split(",").map((k) => k.trim());
+    }
+    const node = {
+      id: nodeId,
+      type: options.type,
+      position,
+      data: {
+        metadata
+      }
+    };
+    const operations = [
+      {
+        type: "add_node",
+        node
+      }
+    ];
+    if (options.connectFrom) {
+      operations.push({
+        type: "add_edge",
+        edge: {
+          id: `edge-${options.connectFrom}-${nodeId}`,
+          source: options.connectFrom,
+          target: nodeId
+        }
+      });
+    }
+    if (options.connectTo) {
+      operations.push({
+        type: "add_edge",
+        edge: {
+          id: `edge-${nodeId}-${options.connectTo}`,
+          source: nodeId,
+          target: options.connectTo
+        }
+      });
+    }
+    const body = { operations };
+    const queryParams = [];
+    if (options.resolveToolsetKeys) queryParams.push("resolveToolsetKeys=true");
+    if (options.autoLayout) queryParams.push("autoLayout=true");
+    const queryString = queryParams.length > 0 ? `?${queryParams.join("&")}` : "";
+    await apiRequest(`/v1/cli/workflow/${workflowId}${queryString}`, {
+      method: "PATCH",
+      body
+    });
+    ok("workflow.node.add", {
+      message: "Node added successfully",
+      workflowId,
+      nodeId,
+      type: options.type,
+      position,
+      ...options.query && { query: options.query },
+      ...options.toolsetKeys && {
+        toolsetKeys: options.toolsetKeys.split(",").map((k) => k.trim())
+      },
+      ...options.connectFrom && { connectedFrom: options.connectFrom },
+      ...options.connectTo && { connectedTo: options.connectTo },
+      nextSteps: [
+        `View node: \`refly workflow node ${workflowId} ${nodeId}\``,
+        `List all nodes: \`refly workflow nodes ${workflowId}\``
+      ]
+    });
+  } catch (error) {
+    if (error instanceof CLIError) {
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
+      return;
+    }
+    fail(
+      ErrorCodes.INTERNAL_ERROR,
+      error instanceof Error ? error.message : "Failed to add node"
+    );
+  }
+});
+
+// src/commands/workflow/node-update.ts
+init_cjs_shims();
+var workflowNodeUpdateCommand = new Command("node-update").description("Update a node in a workflow").argument("<workflowId>", "Workflow ID (c-xxx)").argument("<nodeId>", "Node ID to update").option("--query <query>", "Update the query/prompt for the node").option("--title <title>", "Update the node title").option("--toolset-keys <keys>", 'Comma-separated toolset keys (e.g., "web_search,execute_code")').option("--data <json>", "Full node data as JSON (advanced usage)").option("--resolve-toolset-keys", "Resolve toolset keys to full IDs").action(async (workflowId, nodeId, options) => {
+  if (!workflowId.startsWith("c-")) {
+    fail(ErrorCodes.INVALID_INPUT, `Invalid workflow ID: ${workflowId}`, {
+      hint: 'Workflow ID should start with "c-"',
+      suggestedFix: {
+        field: "<workflowId>",
+        format: "c-<id>",
+        example: "c-123456"
+      }
+    });
+    return;
+  }
+  try {
+    let nodeData = {};
+    if (options.data) {
+      try {
+        nodeData = JSON.parse(options.data);
+      } catch {
+        fail(ErrorCodes.INVALID_INPUT, "Invalid JSON in --data", {
+          hint: `Data format: '{"data": {"metadata": {"query": "...", "toolsetKeys": ["..."]}}}'`,
+          suggestedFix: {
+            field: "--data",
+            format: "json-object",
+            example: '{"data": {"metadata": {"query": "Search for information"}}}'
+          }
+        });
+        return;
+      }
+    }
+    const metadataUpdates = {};
+    if (options.query) {
+      metadataUpdates.query = options.query;
+    }
+    if (options.title) {
+      metadataUpdates.title = options.title;
+    }
+    if (options.toolsetKeys) {
+      const keys = options.toolsetKeys.split(",").map((k) => k.trim());
+      metadataUpdates.toolsetKeys = keys;
+    }
+    if (Object.keys(metadataUpdates).length > 0) {
+      nodeData = {
+        ...nodeData,
+        data: {
+          ...nodeData.data || {},
+          metadata: {
+            ...nodeData.data?.metadata || {},
+            ...metadataUpdates
+          }
+        }
+      };
+    }
+    if (Object.keys(nodeData).length === 0) {
+      fail(ErrorCodes.INVALID_INPUT, "No update provided", {
+        hint: "Use --query, --title, --toolset-keys, or --data to specify what to update",
+        suggestedFix: {
+          field: "--query",
+          format: "string",
+          example: '--query "Search for the latest news"'
+        }
+      });
+      return;
+    }
+    const body = {
+      operations: [
+        {
+          type: "update_node",
+          nodeId,
+          data: nodeData
+        }
+      ]
+    };
+    const queryParams = options.resolveToolsetKeys ? "?resolveToolsetKeys=true" : "";
+    await apiRequest(`/v1/cli/workflow/${workflowId}${queryParams}`, {
+      method: "PATCH",
+      body
+    });
+    ok("workflow.node.update", {
+      message: "Node updated successfully",
+      workflowId,
+      nodeId,
+      updates: {
+        ...options.query && { query: options.query },
+        ...options.title && { title: options.title },
+        ...options.toolsetKeys && {
+          toolsetKeys: options.toolsetKeys.split(",").map((k) => k.trim())
+        },
+        ...options.data && { data: "custom data applied" }
+      },
+      nextSteps: [
+        `View updated node: \`refly workflow node ${workflowId} ${nodeId}\``,
+        `List all nodes: \`refly workflow nodes ${workflowId}\``
+      ]
+    });
+  } catch (error) {
+    if (error instanceof CLIError) {
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
+      return;
+    }
+    fail(
+      ErrorCodes.INTERNAL_ERROR,
+      error instanceof Error ? error.message : "Failed to update node"
+    );
+  }
+});
+
+// src/commands/workflow/node-delete.ts
+init_cjs_shims();
+var workflowNodeDeleteCommand = new Command("node-delete").description("Delete a node from a workflow").argument("<workflowId>", "Workflow ID (c-xxx)").argument("<nodeId>", "Node ID to delete").action(async (workflowId, nodeId) => {
+  if (!workflowId.startsWith("c-")) {
+    fail(ErrorCodes.INVALID_INPUT, `Invalid workflow ID: ${workflowId}`, {
+      hint: 'Workflow ID should start with "c-"',
+      suggestedFix: {
+        field: "<workflowId>",
+        format: "c-<id>",
+        example: "c-123456"
+      }
+    });
+    return;
+  }
+  try {
+    const body = {
+      operations: [
+        {
+          type: "remove_node",
+          nodeId
+        }
+      ]
+    };
+    await apiRequest(`/v1/cli/workflow/${workflowId}`, {
+      method: "PATCH",
+      body
+    });
+    ok("workflow.node.delete", {
+      message: "Node deleted successfully",
+      workflowId,
+      nodeId,
+      note: "Connected edges were also removed",
+      nextSteps: [`List remaining nodes: \`refly workflow nodes ${workflowId}\``]
+    });
+  } catch (error) {
+    if (error instanceof CLIError) {
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
+      return;
+    }
+    fail(
+      ErrorCodes.INTERNAL_ERROR,
+      error instanceof Error ? error.message : "Failed to delete node"
+    );
+  }
+});
+
 // src/commands/workflow/node-output.ts
 init_cjs_shims();
 var workflowNodeOutputCommand = new Command("node-output").description("Get node execution output content").argument("<id>", "Workflow ID (c-xxx) or Run ID (we-xxx)").argument("<nodeId>", "Node ID").option("--include-tool-calls", "Include tool call details in output").option("--raw", "Output raw content without formatting").action(async (id, nodeId, options) => {
@@ -11856,7 +12641,11 @@ var workflowNodeOutputCommand = new Command("node-output").description("Get node
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -11868,30 +12657,51 @@ var workflowNodeOutputCommand = new Command("node-output").description("Get node
   }
 });
 
-// src/commands/workflow/patch.ts
+// src/commands/workflow/edit.ts
 init_cjs_shims();
-var fs13 = __toESM(require("fs"));
-var workflowPatchCommand = new Command("patch").description("Apply semantic patch operations to a workflow plan").argument("<planId>", "Workflow Plan ID").option("--ops <json>", "Operations array as JSON").option("--ops-file <path>", "Read operations from file").option("--update-title <title>", "Shortcut: update workflow title").option("--delete-task <taskId>", "Shortcut: delete a task").option("--delete-variable <variableId>", "Shortcut: delete a variable").action(async (planId, options) => {
+var fs14 = __toESM(require("fs"));
+var workflowEditCommand = new Command("edit").description("Edit a workflow plan using semantic operations").argument("<planId>", "Workflow Plan ID").option("--ops <json>", "Operations array as JSON").option("--ops-file <path>", "Read operations from file").option("--update-title <title>", "Shortcut: update workflow title").option("--delete-task <taskId>", "Shortcut: delete a task").option("--delete-variable <variableId>", "Shortcut: delete a variable").action(async (planId, options) => {
   try {
     const operations = [];
+    const opsFormatHint = `Operations format: '[{"op": "updateTitle", "title": "New Title"}]'
+Available ops: updateTitle, createTask, updateTask, deleteTask, createVariable, updateVariable, deleteVariable
+Examples:
+  - Update title: {"op": "updateTitle", "title": "New Title"}
+  - Delete task: {"op": "deleteTask", "taskId": "task-id"}
+  - Update task: {"op": "updateTask", "taskId": "task-id", "data": {"prompt": "new prompt"}}`;
     if (options.opsFile) {
       try {
         const filePath = options.opsFile;
-        if (!fs13.existsSync(filePath)) {
+        if (!fs14.existsSync(filePath)) {
           fail(ErrorCodes.NOT_FOUND, `Operations file not found: ${filePath}`);
         }
-        const fileContent = fs13.readFileSync(filePath, "utf-8");
+        const fileContent = fs14.readFileSync(filePath, "utf-8");
         const fileOps = JSON.parse(fileContent);
         if (Array.isArray(fileOps)) {
           operations.push(...fileOps);
         } else {
-          fail(ErrorCodes.INVALID_INPUT, "Operations file must contain a JSON array");
+          fail(ErrorCodes.INVALID_INPUT, "Operations file must contain a JSON array", {
+            hint: opsFormatHint,
+            suggestedFix: {
+              field: "--ops-file",
+              format: "json-array",
+              example: '[{"op": "updateTitle", "title": "New Title"}]'
+            }
+          });
         }
       } catch (error) {
         if (error instanceof CLIError) throw error;
         fail(
           ErrorCodes.INVALID_INPUT,
-          `Failed to parse operations file: ${error.message}`
+          `Failed to parse operations file: ${error.message}`,
+          {
+            hint: opsFormatHint,
+            suggestedFix: {
+              field: "--ops-file",
+              format: "json-array",
+              example: '[{"op": "updateTitle", "title": "New Title"}]'
+            }
+          }
         );
       }
     }
@@ -11901,11 +12711,23 @@ var workflowPatchCommand = new Command("patch").description("Apply semantic patc
         if (Array.isArray(jsonOps)) {
           operations.push(...jsonOps);
         } else {
-          fail(ErrorCodes.INVALID_INPUT, "--ops must be a JSON array");
+          fail(ErrorCodes.INVALID_INPUT, "--ops must be a JSON array", {
+            hint: opsFormatHint,
+            suggestedFix: {
+              field: "--ops",
+              format: "json-array",
+              example: '[{"op": "updateTitle", "title": "New Title"}]'
+            }
+          });
         }
       } catch (error) {
         fail(ErrorCodes.INVALID_INPUT, `Invalid JSON in --ops: ${error.message}`, {
-          hint: "Ensure the operations are a valid JSON array"
+          hint: opsFormatHint,
+          suggestedFix: {
+            field: "--ops",
+            format: "json-array",
+            example: '[{"op": "updateTitle", "title": "New Title"}]'
+          }
         });
       }
     }
@@ -11929,7 +12751,12 @@ var workflowPatchCommand = new Command("patch").description("Apply semantic patc
     }
     if (operations.length === 0) {
       fail(ErrorCodes.INVALID_INPUT, "No operations provided", {
-        hint: "Use --ops, --ops-file, or shortcut options (--update-title, --delete-task, --delete-variable)"
+        hint: "Use --ops, --ops-file, or shortcut options (--update-title, --delete-task, --delete-variable)",
+        suggestedFix: {
+          field: "--ops",
+          format: "json-array",
+          example: '[{"op": "updateTitle", "title": "New Title"}]'
+        }
       });
     }
     const body = {
@@ -11941,7 +12768,7 @@ var workflowPatchCommand = new Command("patch").description("Apply semantic patc
       body
     });
     const plan = response.data ?? response;
-    ok("workflow.patch", {
+    ok("workflow.edit", {
       planId,
       operationsApplied: operations.length,
       plan: {
@@ -11960,18 +12787,22 @@ var workflowPatchCommand = new Command("patch").description("Apply semantic patc
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
-      error instanceof Error ? error.message : "Failed to patch workflow plan"
+      error instanceof Error ? error.message : "Failed to edit workflow plan"
     );
   }
 });
 
 // src/commands/workflow/index.ts
-var workflowCommand = new Command("workflow").description("Manage and run workflows").addCommand(workflowCreateCommand).addCommand(workflowGenerateCommand).addCommand(workflowListCommand).addCommand(workflowGetCommand).addCommand(workflowEditCommand).addCommand(workflowDeleteCommand).addCommand(workflowRunCommand).addCommand(workflowRunsCommand).addCommand(workflowStatusCommand).addCommand(workflowDetailCommand).addCommand(workflowToolcallsCommand).addCommand(workflowAbortCommand).addCommand(workflowToolsetKeysCommand).addCommand(workflowLayoutCommand).addCommand(workflowNodesCommand).addCommand(workflowNodeGetCommand).addCommand(workflowNodeOutputCommand).addCommand(workflowPatchCommand);
+var workflowCommand = new Command("workflow").description("Manage and run workflows").addCommand(workflowCreateCommand).addCommand(workflowGenerateCommand).addCommand(workflowListCommand).addCommand(workflowGetCommand).addCommand(workflowDeleteCommand).addCommand(workflowRunCommand).addCommand(workflowRunsCommand).addCommand(workflowStatusCommand).addCommand(workflowDetailCommand).addCommand(workflowToolcallsCommand).addCommand(workflowAbortCommand).addCommand(workflowToolsetKeysCommand).addCommand(workflowLayoutCommand).addCommand(workflowNodesCommand).addCommand(workflowNodeGetCommand).addCommand(workflowNodeAddCommand).addCommand(workflowNodeUpdateCommand).addCommand(workflowNodeDeleteCommand).addCommand(workflowNodeOutputCommand).addCommand(workflowEditCommand);
 
 // src/commands/tool/index.ts
 init_cjs_shims();
@@ -12003,7 +12834,11 @@ var toolCallsCommand = new Command("calls").description("Get tool execution resu
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -12048,7 +12883,11 @@ var toolGetCommand = new Command("get").description("Get full details for a sing
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -12096,7 +12935,11 @@ var fileListCommand = new Command("list").description("List files").option("--pa
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -12124,7 +12967,11 @@ var fileGetCommand = new Command("get").description("Get file details").argument
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -12135,16 +12982,16 @@ var fileGetCommand = new Command("get").description("Get file details").argument
 
 // src/commands/file/download.ts
 init_cjs_shims();
-var fs14 = __toESM(require("fs"));
-var path10 = __toESM(require("path"));
+var fs15 = __toESM(require("fs"));
+var path11 = __toESM(require("path"));
 var fileDownloadCommand = new Command("download").description("Download file to local filesystem").argument("<fileId>", "File ID").option("-o, --output <path>", "Output file path (defaults to original filename)").action(async (fileId, options) => {
   try {
     const { data, filename, contentType, size } = await apiRequestStream(
       `/v1/cli/drive/files/${fileId}/download`
     );
     const outputPath = options.output || filename || `${fileId}`;
-    const resolvedPath = path10.resolve(outputPath);
-    fs14.writeFileSync(resolvedPath, data);
+    const resolvedPath = path11.resolve(outputPath);
+    fs15.writeFileSync(resolvedPath, data);
     ok("file.download", {
       fileId,
       path: resolvedPath,
@@ -12154,7 +13001,11 @@ var fileDownloadCommand = new Command("download").description("Download file to
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -12165,8 +13016,8 @@ var fileDownloadCommand = new Command("download").description("Download file to
 
 // src/commands/file/upload.ts
 init_cjs_shims();
-var fs15 = __toESM(require("fs"));
-var path11 = __toESM(require("path"));
+var fs16 = __toESM(require("fs"));
+var path12 = __toESM(require("path"));
 var MAX_FILES = 10;
 function formatSize(bytes) {
   if (bytes < 1024) return `${bytes}B`;
@@ -12176,8 +13027,8 @@ function formatSize(bytes) {
 var fileUploadCommand = new Command("upload").description("Upload file(s) to a canvas").argument("<path>", "File or directory path").requiredOption("--canvas-id <id>", "Canvas ID (required)").option("--filter <extensions>", "Filter by extensions (e.g., pdf,docx,png)").action(async (inputPath, options) => {
   const formatter = getFormatter();
   try {
-    const resolvedPath = path11.resolve(inputPath);
-    if (!fs15.existsSync(resolvedPath)) {
+    const resolvedPath = path12.resolve(inputPath);
+    if (!fs16.existsSync(resolvedPath)) {
       fail(ErrorCodes.NOT_FOUND, `Path not found: ${inputPath}`, {
         hint: "Check if the file or directory exists"
       });
@@ -12195,8 +13046,8 @@ var fileUploadCommand = new Command("upload").description("Upload file(s) to a c
     const errors = [];
     for (let i = 0; i < files.length; i++) {
       const filePath = files[i];
-      const filename = path11.basename(filePath);
-      const fileStats = fs15.statSync(filePath);
+      const filename = path12.basename(filePath);
+      const fileStats = fs16.statSync(filePath);
       const sizeStr = formatSize(fileStats.size);
       let currentStage = "presign";
       const updateProgress = () => {
@@ -12264,7 +13115,11 @@ var fileUploadCommand = new Command("upload").description("Upload file(s) to a c
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
@@ -12273,11 +13128,11 @@ var fileUploadCommand = new Command("upload").description("Upload file(s) to a c
   }
 });
 function resolveFilesToUpload(inputPath, filter) {
-  const stats = fs15.statSync(inputPath);
+  const stats = fs16.statSync(inputPath);
   if (stats.isFile()) {
     if (filter) {
       const filterExts = filter.split(",").map((e) => e.trim().toLowerCase());
-      const ext = path11.extname(inputPath).slice(1).toLowerCase();
+      const ext = path12.extname(inputPath).slice(1).toLowerCase();
       if (!filterExts.includes(ext)) {
         return [];
       }
@@ -12285,21 +13140,21 @@ function resolveFilesToUpload(inputPath, filter) {
     return [inputPath];
   }
   if (stats.isDirectory()) {
-    const entries = fs15.readdirSync(inputPath);
+    const entries = fs16.readdirSync(inputPath);
     const filterExts = filter?.split(",").map((e) => e.trim().toLowerCase());
-    const files = entries.map((e) => path11.join(inputPath, e)).filter((p) => {
+    const files = entries.map((e) => path12.join(inputPath, e)).filter((p) => {
       try {
-        return fs15.statSync(p).isFile();
+        return fs16.statSync(p).isFile();
       } catch {
         return false;
       }
     }).filter((p) => {
       if (!filterExts) return true;
-      const ext = path11.extname(p).slice(1).toLowerCase();
+      const ext = path12.extname(p).slice(1).toLowerCase();
       return filterExts.includes(ext);
     }).sort((a, b) => {
       try {
-        return fs15.statSync(a).size - fs15.statSync(b).size;
+        return fs16.statSync(a).size - fs16.statSync(b).size;
       } catch {
         return 0;
       }
@@ -12344,7 +13199,11 @@ var skillListCommand = new Command("list").description("List skill packages").op
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -12383,7 +13242,11 @@ var skillGetCommand = new Command("get").description("Get skill package details"
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -12395,388 +13258,10 @@ var skillGetCommand = new Command("get").description("Get skill package details"
 
 // src/commands/skill/create.ts
 init_cjs_shims();
-
-// src/skill/storage.ts
-init_cjs_shims();
-var fs16 = __toESM(require("fs"));
-var path12 = __toESM(require("path"));
+var fs17 = __toESM(require("fs"));
+init_symlink();
 init_paths();
 init_logger();
-
-// src/skill/types.ts
-init_cjs_shims();
-var SKILL_NAME_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
-var SKILL_NAME_MAX_LENGTH = 64;
-var SKILL_DESCRIPTION_MAX_LENGTH = 200;
-var SKILL_TRIGGERS_MIN = 1;
-var SKILL_TRIGGERS_MAX = 10;
-var REGISTRY_VERSION = 1;
-function isSkillRegistry(obj) {
-  return typeof obj === "object" && obj !== null && typeof obj.version === "number" && typeof obj.updatedAt === "string" && Array.isArray(obj.skills);
-}
-function isValidSkillName(name) {
-  return typeof name === "string" && name.length >= 1 && name.length <= SKILL_NAME_MAX_LENGTH && SKILL_NAME_REGEX.test(name);
-}
-function createSkillError(code, message, options) {
-  return {
-    code,
-    message,
-    details: options?.details,
-    suggestions: options?.suggestions
-  };
-}
-function validateCommonSkillFields(data, issues) {
-  if (typeof data.name !== "string") {
-    issues.push({ path: "name", message: "Name is required", value: data.name });
-  } else if (!isValidSkillName(data.name)) {
-    issues.push({
-      path: "name",
-      message: `Name must match pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ and be 1-${SKILL_NAME_MAX_LENGTH} chars`,
-      value: data.name
-    });
-  }
-  if (typeof data.description !== "string") {
-    issues.push({
-      path: "description",
-      message: "Description is required",
-      value: data.description
-    });
-  } else if (data.description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
-    issues.push({
-      path: "description",
-      message: `Description must be <= ${SKILL_DESCRIPTION_MAX_LENGTH} chars`,
-      value: data.description.length
-    });
-  }
-  if (typeof data.workflowId !== "string" || data.workflowId.trim() === "") {
-    issues.push({ path: "workflowId", message: "WorkflowId is required", value: data.workflowId });
-  }
-  validateTriggers(data.triggers, issues);
-}
-function validateTriggers(triggers, issues) {
-  if (!Array.isArray(triggers)) {
-    issues.push({ path: "triggers", message: "Triggers must be an array", value: triggers });
-    return;
-  }
-  if (triggers.length < SKILL_TRIGGERS_MIN || triggers.length > SKILL_TRIGGERS_MAX) {
-    issues.push({
-      path: "triggers",
-      message: `Triggers must have ${SKILL_TRIGGERS_MIN}-${SKILL_TRIGGERS_MAX} items`,
-      value: triggers.length
-    });
-  }
-  for (let i = 0; i < triggers.length; i++) {
-    if (typeof triggers[i] !== "string" || triggers[i].trim() === "") {
-      issues.push({
-        path: `triggers[${i}]`,
-        message: "Each trigger must be a non-empty string",
-        value: triggers[i]
-      });
-    }
-  }
-}
-function validateOptionalSkillFields(data, issues) {
-  if (data.tags !== void 0) {
-    if (!Array.isArray(data.tags)) {
-      issues.push({ path: "tags", message: "Tags must be an array if provided", value: data.tags });
-    } else {
-      for (let i = 0; i < data.tags.length; i++) {
-        if (typeof data.tags[i] !== "string") {
-          issues.push({
-            path: `tags[${i}]`,
-            message: "Each tag must be a string",
-            value: data.tags[i]
-          });
-        }
-      }
-    }
-  }
-  if (data.author !== void 0 && typeof data.author !== "string") {
-    issues.push({
-      path: "author",
-      message: "Author must be a string if provided",
-      value: data.author
-    });
-  }
-  if (data.version !== void 0 && typeof data.version !== "string") {
-    issues.push({
-      path: "version",
-      message: "Version must be a string if provided",
-      value: data.version
-    });
-  }
-}
-
-// src/skill/storage.ts
-function getDomainSkillsDir() {
-  return path12.join(getClaudeSkillDir(), "domain-skills");
-}
-function getSkillDir(name) {
-  if (!isValidSkillName(name)) {
-    throw createSkillError("INVALID_NAME" /* INVALID_NAME */, `Invalid skill name: ${name}`, {
-      suggestions: [
-        "Skill name must match pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
-        "Use lowercase letters, numbers, and hyphens only",
-        "Name must be 1-64 characters"
-      ]
-    });
-  }
-  return path12.join(getDomainSkillsDir(), name);
-}
-function getSkillFilePath(name) {
-  return path12.join(getSkillDir(name), "skill.md");
-}
-function getSkillRelativePath(name) {
-  return `domain-skills/${name}`;
-}
-function skillExists(name) {
-  try {
-    const skillDir = getSkillDir(name);
-    return fs16.existsSync(skillDir);
-  } catch {
-    return false;
-  }
-}
-function createSkillDir(name) {
-  const skillDir = getSkillDir(name);
-  const domainSkillsDir = getDomainSkillsDir();
-  ensureDir(domainSkillsDir);
-  if (fs16.existsSync(skillDir)) {
-    throw createSkillError("SKILL_EXISTS" /* SKILL_EXISTS */, `Skill directory already exists: ${name}`, {
-      suggestions: ["Choose a different name or delete the existing skill first"]
-    });
-  }
-  fs16.mkdirSync(skillDir, { recursive: true, mode: 493 });
-  logger.debug(`Created skill directory: ${skillDir}`);
-  return skillDir;
-}
-function writeSkillFile(name, content) {
-  const skillDir = getSkillDir(name);
-  const skillFile = getSkillFilePath(name);
-  if (!fs16.existsSync(skillDir)) {
-    createSkillDir(name);
-  }
-  fs16.writeFileSync(skillFile, content, { encoding: "utf-8", mode: 420 });
-  logger.debug(`Wrote skill file: ${skillFile}`);
-  return skillFile;
-}
-function readSkillFile(name) {
-  const skillFile = getSkillFilePath(name);
-  if (!fs16.existsSync(skillFile)) {
-    throw createSkillError("SKILL_DIR_NOT_FOUND" /* SKILL_DIR_NOT_FOUND */, `Skill file not found: ${name}`, {
-      details: { path: skillFile },
-      suggestions: [
-        "Check if the skill exists with `refly skill list`",
-        "Create a new skill with `refly skill create`"
-      ]
-    });
-  }
-  return fs16.readFileSync(skillFile, "utf-8");
-}
-function listSkillDirectories() {
-  const domainSkillsDir = getDomainSkillsDir();
-  if (!fs16.existsSync(domainSkillsDir)) {
-    return [];
-  }
-  const entries = fs16.readdirSync(domainSkillsDir, { withFileTypes: true });
-  return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => isValidSkillName(name));
-}
-function generateSkillTemplate(options) {
-  const { name, description, workflowId, triggers, tags, author, version } = options;
-  const frontmatterLines = [
-    "---",
-    `name: ${name}`,
-    `description: ${description}`,
-    `workflowId: ${workflowId}`,
-    "triggers:",
-    ...triggers.map((t) => `  - ${t}`)
-  ];
-  if (tags && tags.length > 0) {
-    frontmatterLines.push("tags:");
-    frontmatterLines.push(...tags.map((t) => `  - ${t}`));
-  }
-  if (author) {
-    frontmatterLines.push(`author: ${author}`);
-  }
-  if (version) {
-    frontmatterLines.push(`version: ${version}`);
-  }
-  frontmatterLines.push("---");
-  const titleName = name.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-  const content = `
-# ${titleName}
-
-## Overview
-
-${description}
-
-## Quick Start
-
-\`\`\`bash
-refly skill run ${name} --input '{}'
-\`\`\`
-
-## Workflow
-
-This skill executes workflow \`${workflowId}\`.
-
-## Input
-
-Provide input as JSON:
-
-\`\`\`json
-{
-  // Add your input parameters here
-}
-\`\`\`
-
-## Output
-
-The skill returns the workflow execution result.
-`;
-  return frontmatterLines.join("\n") + content;
-}
-function syncCloudSkillToLocal(options) {
-  const { name, description, workflowId, triggers = [], tags, version, skillId } = options;
-  const finalTriggers = triggers.length > 0 ? triggers : [name];
-  const content = generateSkillTemplate({
-    name,
-    description: description || `Skill: ${name}`,
-    workflowId,
-    triggers: finalTriggers,
-    tags,
-    version
-  });
-  const filePath = writeSkillFile(name, content);
-  const registryEntry = {
-    name,
-    description: description || `Skill: ${name}`,
-    workflowId,
-    triggers: finalTriggers,
-    path: getSkillRelativePath(name),
-    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-    source: "refly-cloud",
-    tags,
-    version,
-    skillId
-  };
-  logger.info(`Synced cloud skill '${name}' to local: ${filePath}`);
-  return { filePath, registryEntry };
-}
-
-// src/skill/registry.ts
-init_cjs_shims();
-var fs17 = __toESM(require("fs"));
-var path13 = __toESM(require("path"));
-var crypto2 = __toESM(require("crypto"));
-init_paths();
-init_logger();
-function getRegistryPath() {
-  return path13.join(getClaudeSkillDir(), "registry.json");
-}
-function createEmptyRegistry() {
-  return {
-    version: REGISTRY_VERSION,
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    skills: []
-  };
-}
-function readRegistry() {
-  const registryPath = getRegistryPath();
-  if (!fs17.existsSync(registryPath)) {
-    logger.debug("Registry file not found, returning empty registry");
-    return createEmptyRegistry();
-  }
-  try {
-    const content = fs17.readFileSync(registryPath, "utf-8");
-    const data = JSON.parse(content);
-    if (!isSkillRegistry(data)) {
-      throw createSkillError("REGISTRY_CORRUPTED" /* REGISTRY_CORRUPTED */, "Registry structure is invalid", {
-        suggestions: ["Run `refly skill validate --fix` to repair the registry"]
-      });
-    }
-    logger.debug(`Registry loaded with ${data.skills.length} skills`);
-    return data;
-  } catch (err) {
-    if (err instanceof SyntaxError) {
-      throw createSkillError("REGISTRY_CORRUPTED" /* REGISTRY_CORRUPTED */, "Registry JSON is malformed", {
-        details: { error: err.message },
-        suggestions: ["Run `refly skill validate --fix` to repair the registry"]
-      });
-    }
-    throw err;
-  }
-}
-function writeRegistry(registry) {
-  const registryPath = getRegistryPath();
-  const registryDir = path13.dirname(registryPath);
-  ensureDir(registryDir);
-  registry.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const content = JSON.stringify(registry, null, 2);
-  const tempPath = path13.join(registryDir, `.registry-${crypto2.randomUUID()}.tmp`);
-  try {
-    fs17.writeFileSync(tempPath, content, { encoding: "utf-8", mode: 384 });
-    fs17.renameSync(tempPath, registryPath);
-    logger.debug(`Registry saved with ${registry.skills.length} skills`);
-  } catch (err) {
-    try {
-      if (fs17.existsSync(tempPath)) {
-        fs17.unlinkSync(tempPath);
-      }
-    } catch {
-    }
-    throw err;
-  }
-}
-function findSkill(name) {
-  const registry = readRegistry();
-  return registry.skills.find((s) => s.name === name) ?? null;
-}
-function addSkill(entry) {
-  const registry = readRegistry();
-  if (registry.skills.some((s) => s.name === entry.name)) {
-    throw createSkillError("SKILL_EXISTS" /* SKILL_EXISTS */, `Skill '${entry.name}' already exists`, {
-      suggestions: ["Choose a different name or use `refly skill delete` first"]
-    });
-  }
-  const validationErrors = validateSkillEntry(entry);
-  if (validationErrors.length > 0) {
-    throw createSkillError("VALIDATION_ERROR" /* VALIDATION_ERROR */, "Invalid skill entry", {
-      details: { errors: validationErrors },
-      suggestions: validationErrors.map((e) => e.message)
-    });
-  }
-  registry.skills.push(entry);
-  writeRegistry(registry);
-  logger.info(`Skill '${entry.name}' added to registry`);
-}
-function validateSkillEntry(entry) {
-  const issues = [];
-  if (!entry || typeof entry !== "object") {
-    issues.push({ path: "", message: "Entry must be an object", value: entry });
-    return issues;
-  }
-  const e = entry;
-  validateCommonSkillFields(e, issues);
-  if (typeof e.path !== "string" || e.path.trim() === "") {
-    issues.push({ path: "path", message: "Path is required", value: e.path });
-  }
-  if (typeof e.createdAt !== "string") {
-    issues.push({ path: "createdAt", message: "CreatedAt is required", value: e.createdAt });
-  }
-  if (e.source !== "local" && e.source !== "refly-cloud") {
-    issues.push({
-      path: "source",
-      message: "Source must be 'local' or 'refly-cloud'",
-      value: e.source
-    });
-  }
-  validateOptionalSkillFields(e, issues);
-  return issues;
-}
-
-// src/commands/skill/create.ts
-init_logger();
 var skillCreateCommand = new Command("create").description("Create a new skill package with workflow").requiredOption("--name <name>", "Skill package name").option("--version <version>", "Semantic version", "1.0.0").option("--description <description>", "Skill description").option("--triggers <triggers>", "Trigger phrases (comma-separated)").option("--tags <tags>", "Category tags (comma-separated)").option("--workflow <workflowId>", "Bind existing workflow ID").option("--workflow-ids <workflowIds>", "Bind multiple workflow IDs (comma-separated)").option("--workflow-spec <json>", "Workflow spec JSON (structured)").option("--workflow-query <query>", "Natural language workflow description (be specific)").option("--verbose", "Include workflow details in output").action(async (options) => {
   try {
     const hasWorkflowOption = options.workflow || options.workflowIds || options.workflowSpec || options.workflowQuery;
@@ -12818,25 +13303,36 @@ var skillCreateCommand = new Command("create").description("Create a new skill p
       body: input3
     });
     const result = response.payload;
-    let localSkillPath;
+    let localPath;
+    let symlinkPath;
     if (result.workflowId) {
       try {
         const localName = options.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-        if (findSkill(localName) || skillExists(localName)) {
+        const skillDir = getReflyDomainSkillDir(localName);
+        const symlinkStatus = isSkillSymlinkValid(localName);
+        if (fs17.existsSync(skillDir) || symlinkStatus.exists) {
           logger.debug(`Local skill '${localName}' already exists, skipping sync`);
         } else {
-          const { filePath, registryEntry } = syncCloudSkillToLocal({
+          const skillMdContent = generateReflySkillMd({
             name: localName,
+            displayName: options.name,
             description: input3.description || `Skill: ${options.name}`,
+            skillId: result.skillId,
             workflowId: result.workflowId,
             triggers: input3.triggers,
             tags: input3.tags,
             version: options.version,
-            skillId: result.skillId
+            inputSchema: result.inputSchema,
+            outputSchema: result.outputSchema
           });
-          addSkill(registryEntry);
-          localSkillPath = filePath;
-          logger.info(`Created local domain skill: ${localName}`);
+          const symlinkResult = createReflySkillWithSymlink(localName, skillMdContent);
+          if (symlinkResult.success) {
+            localPath = symlinkResult.reflyPath;
+            symlinkPath = symlinkResult.claudePath;
+            logger.info(`Created local domain skill: ${localName}`);
+          } else {
+            logger.warn(`Failed to create local skill: ${symlinkResult.error}`);
+          }
         }
       } catch (syncError) {
         logger.warn(`Failed to sync to local: ${syncError.message}`);
@@ -12850,8 +13346,9 @@ var skillCreateCommand = new Command("create").description("Create a new skill p
       workflowId: result.workflowId,
       url: `${getWebUrl()}/skill/${result.skillId}`
     };
-    if (localSkillPath) {
-      payload.localSkillPath = localSkillPath;
+    if (localPath) {
+      payload.localPath = localPath;
+      payload.symlinkPath = symlinkPath;
     }
     if (options.verbose) {
       payload.workflowIds = result.workflowIds;
@@ -12860,7 +13357,11 @@ var skillCreateCommand = new Command("create").description("Create a new skill p
     ok("skill.create", payload);
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -12870,37 +13371,188 @@ var skillCreateCommand = new Command("create").description("Create a new skill p
   }
 });
 
-// src/commands/skill/delete.ts
+// src/commands/skill/update.ts
 init_cjs_shims();
-var skillDeleteCommand = new Command("delete").description("Delete a skill package").argument("<skillId>", "Skill package ID to delete").option("--force", "Skip confirmation").action(async (skillId, _options) => {
+var fs18 = __toESM(require("fs"));
+var path13 = __toESM(require("path"));
+init_paths();
+init_symlink();
+var MIN_DESCRIPTION_WORDS = 20;
+function validateDescription(description, skillName) {
+  if (!description) {
+    return {
+      message: "Skill description is required for Claude Code discovery",
+      hint: `Add a description field with at least ${MIN_DESCRIPTION_WORDS} words to your SKILL.md`,
+      example: generateDescriptionExample(skillName)
+    };
+  }
+  const wordCount = description.trim().split(/\s+/).length;
+  if (wordCount < MIN_DESCRIPTION_WORDS) {
+    return {
+      message: `Description too short (${wordCount} words). Minimum ${MIN_DESCRIPTION_WORDS} words required for Claude Code discovery`,
+      hint: `Expand the description in your SKILL.md to at least ${MIN_DESCRIPTION_WORDS} words`,
+      example: generateDescriptionExample(skillName)
+    };
+  }
+  return null;
+}
+function generateDescriptionExample(skillName) {
+  const baseName = skillName.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return `${baseName} automation and processing. Use when Claude needs to: (1) [describe primary use case], (2) [describe secondary use case], or [general catch-all scenario].`;
+}
+var skillUpdateCommand = new Command("update").description("Update skill installation from local SKILL.md").requiredOption("--name <name>", "Local skill name (directory in ~/.refly/skills/)").option("--id <installationId>", "Override installation ID (default: from SKILL.md)").option("--skip-description", "Skip description validation").action(async (options) => {
   try {
-    await apiRequest(`/v1/skill-packages/${skillId}`, {
-      method: "DELETE"
-    });
-    ok("skill.delete", {
-      skillId,
-      deleted: true
+    const name = options.name;
+    const skillDir = getReflyDomainSkillDir(name);
+    const skillMdPath = path13.join(skillDir, "SKILL.md");
+    if (!fs18.existsSync(skillMdPath)) {
+      const skillsDir = getReflySkillsDir();
+      fail(ErrorCodes.NOT_FOUND, `SKILL.md not found at ${skillMdPath}`, {
+        hint: `Make sure the skill '${name}' exists in ${skillsDir}/
+
+To see installed skills: refly skill list`
+      });
+      return;
+    }
+    const skillContent = fs18.readFileSync(skillMdPath, "utf-8");
+    let meta;
+    try {
+      const parsed = parseReflySkillMd(skillContent);
+      meta = parsed.meta;
+    } catch (parseError) {
+      fail(
+        ErrorCodes.INVALID_INPUT,
+        `Failed to parse SKILL.md: ${parseError.message}`,
+        {
+          hint: "Make sure SKILL.md has valid frontmatter with required fields: name, description, skillId, workflowId"
+        }
+      );
+      return;
+    }
+    const installationId = options.id || meta.installationId;
+    if (!installationId) {
+      fail(ErrorCodes.INVALID_INPUT, "Installation ID not found", {
+        hint: "Provide --id <installationId> or ensure your SKILL.md contains the installationId field"
+      });
+      return;
+    }
+    const skipDescription = options.skipDescription;
+    if (!skipDescription) {
+      const descriptionError = validateDescription(meta.description, name);
+      if (descriptionError) {
+        fail(ErrorCodes.VALIDATION_ERROR, descriptionError.message, {
+          hint: descriptionError.hint,
+          recoverable: true,
+          suggestedFix: {
+            field: "description",
+            format: "[What it does]. Use when [scenarios]: (1) [case1], (2) [case2], or [catch-all].",
+            example: descriptionError.example
+          }
+        });
+        return;
+      }
+    }
+    const updatePayload = {
+      ...meta.name && { name: meta.name },
+      ...meta.description && { description: meta.description },
+      ...meta.workflowId && { workflowId: meta.workflowId },
+      ...meta.triggers?.length && { triggers: meta.triggers },
+      ...meta.tags?.length && { tags: meta.tags },
+      ...meta.version && { version: meta.version }
+    };
+    if (Object.keys(updatePayload).length === 0) {
+      fail(ErrorCodes.INVALID_INPUT, "No updateable fields found in SKILL.md", {
+        hint: "Ensure SKILL.md contains fields like name, description, triggers, tags, or version"
+      });
+      return;
+    }
+    const response = await apiRequest(
+      `/v1/skill-installations/${installationId}`,
+      {
+        method: "PATCH",
+        body: updatePayload
+      }
+    );
+    ok("skill.update", {
+      ...response,
+      localName: name,
+      updated: true,
+      fields: Object.keys(updatePayload)
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
       ErrorCodes.INTERNAL_ERROR,
-      error instanceof Error ? error.message : "Failed to delete skill package"
+      error instanceof Error ? error.message : "Failed to update skill installation"
     );
   }
 });
 
 // src/commands/skill/publish.ts
 init_cjs_shims();
-var skillPublishCommand = new Command("publish").description("Publish a skill package to make it publicly available").argument("<skillId>", "Skill package ID to publish").action(async (skillId) => {
+var fs19 = __toESM(require("fs"));
+var path14 = __toESM(require("path"));
+init_symlink();
+init_paths();
+var skillPublishCommand = new Command("publish").description("Publish a skill package using local SKILL.md").option("--id <skillId>", "Skill ID (skp-xxx) - overrides ID from SKILL.md").option("--name <name>", "Local skill name (directory in ~/.refly/skills/)").action(async (options) => {
   try {
+    const skillsDir = getReflySkillsDir();
+    if (!options.name) {
+      fail(ErrorCodes.INVALID_INPUT, "Missing required option: --name", {
+        hint: `The publish command requires --name to locate the local SKILL.md.
+
+Usage:
+  refly skill publish --name <name>
+  refly skill publish --name <name> --id <skillId>  # override skillId
+
+To find your skill name:
+  refly skill list
+  ls ${skillsDir}/`
+      });
+      return;
+    }
+    const name = options.name;
+    const skillDir = getReflyDomainSkillDir(name);
+    const skillMdPath = path14.join(skillDir, "SKILL.md");
+    if (!fs19.existsSync(skillMdPath)) {
+      fail(ErrorCodes.NOT_FOUND, `SKILL.md not found at ${skillMdPath}`, {
+        hint: `Make sure the skill '${name}' exists in ${skillsDir}/
+
+To see installed skills: refly skill list
+To create a new skill: refly skill create --name "${name}" --workflow-query "..."`
+      });
+      return;
+    }
+    const skillContent = fs19.readFileSync(skillMdPath, "utf-8");
+    let parsedSkill;
+    try {
+      parsedSkill = parseReflySkillMd(skillContent);
+    } catch (parseError) {
+      fail(
+        ErrorCodes.INVALID_INPUT,
+        `Failed to parse SKILL.md: ${parseError.message}`,
+        {
+          hint: "Make sure SKILL.md has valid frontmatter with required fields: name, description, skillId, workflowId"
+        }
+      );
+      return;
+    }
+    const { meta } = parsedSkill;
+    const skillId = options.id || meta.skillId;
     const result = await apiRequest(
       `/v1/skill-packages/${skillId}/publish`,
       {
-        method: "POST"
+        method: "POST",
+        body: {
+          skillContent
+        }
       }
     );
     ok("skill.publish", {
@@ -12910,11 +13562,18 @@ var skillPublishCommand = new Command("publish").description("Publish a skill pa
       status: result.status,
       isPublic: result.isPublic,
       shareId: result.shareId,
-      shareUrl: result.shareId ? `https://refly.ai/skill/${result.shareId}` : void 0
+      shareUrl: result.shareId ? `https://refly.ai/skill/${result.shareId}` : void 0,
+      githubPrUrl: result.githubPrUrl,
+      githubPrNumber: result.githubPrNumber,
+      localPath: skillMdPath
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -12926,19 +13585,72 @@ var skillPublishCommand = new Command("publish").description("Publish a skill pa
 
 // src/commands/skill/unpublish.ts
 init_cjs_shims();
-var skillUnpublishCommand = new Command("unpublish").description("Unpublish a skill package to make it private").argument("<skillId>", "Skill package ID to unpublish").action(async (skillId) => {
+var fs20 = __toESM(require("fs"));
+var path15 = __toESM(require("path"));
+init_symlink();
+init_paths();
+var skillUnpublishCommand = new Command("unpublish").description("Unpublish a skill package to make it private").option("--id <skillId>", "Skill ID (skp-xxx)").option("--name <name>", "Local skill name (directory in ~/.refly/skills/)").action(async (options) => {
   try {
+    const skillsDir = getReflySkillsDir();
+    if (!options.id && !options.name) {
+      fail(ErrorCodes.INVALID_INPUT, "Missing required option: --id or --name", {
+        hint: `Usage:
+  refly skill unpublish --name <name>
+  refly skill unpublish --id <skillId>
+
+To find your skill name:
+  refly skill list
+  ls ${skillsDir}/`
+      });
+      return;
+    }
+    let skillId;
+    let name;
+    if (options.name) {
+      name = options.name;
+      const skillDir = getReflyDomainSkillDir(name);
+      const skillMdPath = path15.join(skillDir, "SKILL.md");
+      if (!fs20.existsSync(skillMdPath)) {
+        fail(ErrorCodes.NOT_FOUND, `SKILL.md not found at ${skillMdPath}`, {
+          hint: `Make sure the skill '${name}' exists in ${skillsDir}/
+
+To see installed skills: refly skill list`
+        });
+        return;
+      }
+      const skillContent = fs20.readFileSync(skillMdPath, "utf-8");
+      try {
+        const { meta } = parseReflySkillMd(skillContent);
+        skillId = options.id || meta.skillId;
+      } catch (parseError) {
+        fail(
+          ErrorCodes.INVALID_INPUT,
+          `Failed to parse SKILL.md: ${parseError.message}`,
+          {
+            hint: "Make sure SKILL.md has valid frontmatter with required fields: name, description, skillId, workflowId"
+          }
+        );
+        return;
+      }
+    } else {
+      skillId = options.id;
+    }
     await apiRequest(`/v1/skill-packages/${skillId}/unpublish`, {
       method: "POST"
     });
     ok("skill.unpublish", {
+      name,
       skillId,
       status: "draft",
       isPublic: false
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -12950,18 +13662,94 @@ var skillUnpublishCommand = new Command("unpublish").description("Unpublish a sk
 
 // src/commands/skill/run.ts
 init_cjs_shims();
-var skillRunCommand = new Command("run").description("Run an installed skill").argument("<installationId>", "Installation ID").option("--input <json>", "Input JSON for the skill").option("--workflow <skillWorkflowId>", "Run specific workflow only").option("--async", "Run asynchronously").action(async (installationId, options) => {
+var fs21 = __toESM(require("fs"));
+var path16 = __toESM(require("path"));
+init_symlink();
+init_paths();
+var skillRunCommand = new Command("run").description("Run an installed skill").option("--id <installationId>", "Installation ID (skpi-xxx)").option("--name <name>", "Local skill name (directory in ~/.refly/skills/)").option("--input <json>", "Input JSON for the skill").option("--workflow <skillWorkflowId>", "Run specific workflow only").option("--async", "Run asynchronously").action(async (options) => {
   try {
+    const skillsDir = getReflySkillsDir();
+    if (!options.id && !options.name) {
+      fail(ErrorCodes.INVALID_INPUT, "Missing required option: --id or --name", {
+        hint: `Usage:
+  refly skill run --name <name>
+  refly skill run --id <installationId>
+
+To find your skill name:
+  refly skill list
+  ls ${skillsDir}/`
+      });
+      return;
+    }
+    let installationId;
+    let name;
+    let skillId;
+    if (options.name) {
+      name = options.name;
+      const skillDir = getReflyDomainSkillDir(name);
+      const skillMdPath = path16.join(skillDir, "SKILL.md");
+      if (!fs21.existsSync(skillMdPath)) {
+        fail(ErrorCodes.NOT_FOUND, `SKILL.md not found at ${skillMdPath}`, {
+          hint: `Make sure the skill '${name}' exists in ${skillsDir}/
+
+To see installed skills: refly skill list
+To install a skill: refly skill install <skillId>`
+        });
+        return;
+      }
+      const skillContent = fs21.readFileSync(skillMdPath, "utf-8");
+      try {
+        const { meta } = parseReflySkillMd(skillContent);
+        skillId = meta.skillId;
+        if (options.id) {
+          installationId = options.id;
+        } else if (meta.installationId) {
+          installationId = meta.installationId;
+        } else {
+          fail(ErrorCodes.INVALID_INPUT, `Skill '${name}' does not have an installationId`, {
+            hint: `This skill may have been created locally but not installed.
+
+To install: refly skill install ${meta.skillId}`
+          });
+          return;
+        }
+      } catch (parseError) {
+        fail(
+          ErrorCodes.INVALID_INPUT,
+          `Failed to parse SKILL.md: ${parseError.message}`,
+          {
+            hint: "Make sure SKILL.md has valid frontmatter with required fields: name, description, skillId, workflowId"
+          }
+        );
+        return;
+      }
+    } else {
+      installationId = options.id;
+    }
     let input3 = {};
     if (options.input) {
       try {
         input3 = JSON.parse(options.input);
         if (typeof input3 !== "object" || input3 === null || Array.isArray(input3)) {
-          fail(ErrorCodes.INVALID_INPUT, "Input must be a JSON object");
+          fail(ErrorCodes.INVALID_INPUT, "Input must be a JSON object", {
+            hint: `Use format: '{"varName": "value", "fileVar": "df-fileId"}'`,
+            suggestedFix: {
+              field: "--input",
+              format: "json-object",
+              example: '{"varName": "value", "fileVar": "df-fileId"}'
+            }
+          });
           return;
         }
       } catch {
-        fail(ErrorCodes.INVALID_INPUT, "Invalid JSON input");
+        fail(ErrorCodes.INVALID_INPUT, "Invalid JSON input", {
+          hint: `Ensure the input is valid JSON, e.g., '{"varName": "value"}'`,
+          suggestedFix: {
+            field: "--input",
+            format: "json-object",
+            example: '{"varName": "value"}'
+          }
+        });
         return;
       }
     }
@@ -12976,6 +13764,8 @@ var skillRunCommand = new Command("run").description("Run an installed skill").a
       }
     );
     ok("skill.run", {
+      name,
+      skillId,
       executionId: result.executionId,
       installationId: result.installationId,
       status: result.status,
@@ -12985,7 +13775,11 @@ var skillRunCommand = new Command("run").description("Run an installed skill").a
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -13023,7 +13817,11 @@ var skillSearchCommand = new Command("search").description("Search public skill
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -13035,6 +13833,8 @@ var skillSearchCommand = new Command("search").description("Search public skill
 
 // src/commands/skill/install.ts
 init_cjs_shims();
+init_symlink();
+init_logger();
 var skillInstallCommand = new Command("install").description("Install a skill package").argument("<skillId>", "Skill package ID to install").option("--version <version>", "Specific version to install").option("--share-id <shareId>", "Share ID for private skills").option("--config <json>", "Installation config JSON").action(async (skillId, options) => {
   try {
     const body = { skillId };
@@ -13044,7 +13844,14 @@ var skillInstallCommand = new Command("install").description("Install a skill pa
       try {
         body.config = JSON.parse(options.config);
       } catch {
-        fail(ErrorCodes.INVALID_INPUT, "Invalid config JSON");
+        fail(ErrorCodes.INVALID_INPUT, "Invalid config JSON", {
+          hint: `Config must be a valid JSON object, e.g., '{"key": "value"}'`,
+          suggestedFix: {
+            field: "--config",
+            format: "json-object",
+            example: '{"key": "value"}'
+          }
+        });
         return;
       }
     }
@@ -13055,6 +13862,37 @@ var skillInstallCommand = new Command("install").description("Install a skill pa
         body
       }
     );
+    let localPath;
+    let symlinkPath;
+    const skillName = result.skillPackage?.name;
+    const workflowId = result.skillPackage?.workflowId;
+    if (skillName && workflowId) {
+      try {
+        const skillMdContent = generateReflySkillMd({
+          name: skillName,
+          displayName: result.skillPackage?.displayName,
+          description: result.skillPackage?.description || `Skill: ${skillName}`,
+          skillId: result.skillId,
+          workflowId,
+          installationId: result.installationId,
+          triggers: result.skillPackage?.triggers,
+          tags: result.skillPackage?.tags,
+          version: result.installedVersion,
+          inputSchema: result.skillPackage?.inputSchema,
+          outputSchema: result.skillPackage?.outputSchema
+        });
+        const symlinkResult = createReflySkillWithSymlink(skillName, skillMdContent);
+        if (symlinkResult.success) {
+          localPath = symlinkResult.reflyPath;
+          symlinkPath = symlinkResult.claudePath;
+          logger.info(`Created local skill: ${localPath}`);
+        } else {
+          logger.warn(`Failed to create local skill: ${symlinkResult.error}`);
+        }
+      } catch (err) {
+        logger.warn(`Failed to create local skill: ${err.message}`);
+      }
+    }
     ok("skill.install", {
       installationId: result.installationId,
       skillId: result.skillId,
@@ -13062,11 +13900,17 @@ var skillInstallCommand = new Command("install").description("Install a skill pa
       skillVersion: result.installedVersion,
       status: result.status,
       config: result.userConfig,
-      installedAt: result.createdAt
+      installedAt: result.createdAt,
+      localPath,
+      symlinkPath
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -13078,18 +13922,101 @@ var skillInstallCommand = new Command("install").description("Install a skill pa
 
 // src/commands/skill/uninstall.ts
 init_cjs_shims();
-var skillUninstallCommand = new Command("uninstall").description("Uninstall a skill").argument("<installationId>", "Installation ID to uninstall").option("--force", "Skip confirmation").action(async (installationId, _options) => {
+var fs22 = __toESM(require("fs"));
+var path17 = __toESM(require("path"));
+init_symlink();
+init_paths();
+init_logger();
+var skillUninstallCommand = new Command("uninstall").description("Uninstall a skill").option("--id <installationId>", "Installation ID (skpi-xxx)").option("--name <name>", "Local skill name (directory in ~/.refly/skills/)").option("--force", "Skip confirmation").option("--keep-local", "Keep local skill files and symlink").action(async (options) => {
   try {
-    await apiRequest(`/v1/skill-installations/${installationId}`, {
-      method: "DELETE"
-    });
+    const skillsDir = getReflySkillsDir();
+    if (!options.id && !options.name) {
+      fail(ErrorCodes.INVALID_INPUT, "Missing required option: --id or --name", {
+        hint: `Usage:
+  refly skill uninstall --name <name>
+  refly skill uninstall --id <installationId>
+
+To find your skill name:
+  refly skill list
+  ls ${skillsDir}/`
+      });
+      return;
+    }
+    let installationId;
+    let skillId;
+    let name;
+    if (options.name) {
+      name = options.name;
+      const skillDir = getReflyDomainSkillDir(name);
+      const skillMdPath = path17.join(skillDir, "SKILL.md");
+      if (!fs22.existsSync(skillMdPath)) {
+        fail(ErrorCodes.NOT_FOUND, `SKILL.md not found at ${skillMdPath}`, {
+          hint: `Make sure the skill '${name}' exists in ${skillsDir}/
+
+To see installed skills: refly skill list`
+        });
+        return;
+      }
+      const skillContent = fs22.readFileSync(skillMdPath, "utf-8");
+      try {
+        const { meta } = parseReflySkillMd(skillContent);
+        skillId = meta.skillId;
+        installationId = options.id || meta.installationId;
+      } catch (parseError) {
+        fail(
+          ErrorCodes.INVALID_INPUT,
+          `Failed to parse SKILL.md: ${parseError.message}`,
+          {
+            hint: "Make sure SKILL.md has valid frontmatter with required fields: name, description, skillId, workflowId"
+          }
+        );
+        return;
+      }
+    } else {
+      installationId = options.id;
+    }
+    if (installationId) {
+      try {
+        await apiRequest(`/v1/skill-installations/${installationId}`, {
+          method: "DELETE"
+        });
+      } catch (error) {
+        if (error instanceof CLIError && error.code === "NOT_FOUND") {
+          logger.debug("Installation not found on server, proceeding with local cleanup");
+        } else {
+          throw error;
+        }
+      }
+    }
+    let symlinkRemoved = false;
+    let directoryRemoved = false;
+    if (name && !options.keepLocal) {
+      try {
+        const cleanup = deleteDomainSkillWithSymlink(name);
+        symlinkRemoved = cleanup.symlinkRemoved;
+        directoryRemoved = cleanup.directoryRemoved;
+        logger.info(`Cleaned up local skill: ${name}`);
+      } catch (err) {
+        logger.warn(`Failed to clean up local skill: ${err.message}`);
+      }
+    }
     ok("skill.uninstall", {
+      name,
+      skillId,
       installationId,
-      uninstalled: true
+      uninstalled: true,
+      localCleanup: {
+        symlinkRemoved,
+        directoryRemoved
+      }
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -13127,7 +14054,11 @@ var skillInstallationsCommand = new Command("installations").description("List i
     });
   } catch (error) {
     if (error instanceof CLIError) {
-      fail(error.code, error.message, { details: error.details, hint: error.hint });
+      fail(error.code, error.message, {
+        details: error.details,
+        hint: error.hint,
+        suggestedFix: error.suggestedFix
+      });
       return;
     }
     fail(
@@ -13142,8 +14073,114 @@ init_cjs_shims();
 
 // src/skill/loader.ts
 init_cjs_shims();
+var fs23 = __toESM(require("fs"));
+var path18 = __toESM(require("path"));
 var import_gray_matter = __toESM(require("gray-matter"));
 init_logger();
+
+// src/skill/types.ts
+init_cjs_shims();
+var SKILL_NAME_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+var SKILL_NAME_MAX_LENGTH = 64;
+var SKILL_DESCRIPTION_MAX_LENGTH = 200;
+var SKILL_TRIGGERS_MIN = 1;
+var SKILL_TRIGGERS_MAX = 10;
+function isValidSkillName(name) {
+  return typeof name === "string" && name.length >= 1 && name.length <= SKILL_NAME_MAX_LENGTH && SKILL_NAME_REGEX.test(name);
+}
+function createSkillError(code, message, options) {
+  return {
+    code,
+    message,
+    details: options?.details,
+    suggestions: options?.suggestions
+  };
+}
+function validateCommonSkillFields(data, issues) {
+  if (typeof data.name !== "string") {
+    issues.push({ path: "name", message: "Name is required", value: data.name });
+  } else if (!isValidSkillName(data.name)) {
+    issues.push({
+      path: "name",
+      message: `Name must match pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ and be 1-${SKILL_NAME_MAX_LENGTH} chars`,
+      value: data.name
+    });
+  }
+  if (typeof data.description !== "string") {
+    issues.push({
+      path: "description",
+      message: "Description is required",
+      value: data.description
+    });
+  } else if (data.description.length > SKILL_DESCRIPTION_MAX_LENGTH) {
+    issues.push({
+      path: "description",
+      message: `Description must be <= ${SKILL_DESCRIPTION_MAX_LENGTH} chars`,
+      value: data.description.length
+    });
+  }
+  if (typeof data.workflowId !== "string" || data.workflowId.trim() === "") {
+    issues.push({ path: "workflowId", message: "WorkflowId is required", value: data.workflowId });
+  }
+  validateTriggers(data.triggers, issues);
+}
+function validateTriggers(triggers, issues) {
+  if (!Array.isArray(triggers)) {
+    issues.push({ path: "triggers", message: "Triggers must be an array", value: triggers });
+    return;
+  }
+  if (triggers.length < SKILL_TRIGGERS_MIN || triggers.length > SKILL_TRIGGERS_MAX) {
+    issues.push({
+      path: "triggers",
+      message: `Triggers must have ${SKILL_TRIGGERS_MIN}-${SKILL_TRIGGERS_MAX} items`,
+      value: triggers.length
+    });
+  }
+  for (let i = 0; i < triggers.length; i++) {
+    if (typeof triggers[i] !== "string" || triggers[i].trim() === "") {
+      issues.push({
+        path: `triggers[${i}]`,
+        message: "Each trigger must be a non-empty string",
+        value: triggers[i]
+      });
+    }
+  }
+}
+function validateOptionalSkillFields(data, issues) {
+  if (data.tags !== void 0) {
+    if (!Array.isArray(data.tags)) {
+      issues.push({ path: "tags", message: "Tags must be an array if provided", value: data.tags });
+    } else {
+      for (let i = 0; i < data.tags.length; i++) {
+        if (typeof data.tags[i] !== "string") {
+          issues.push({
+            path: `tags[${i}]`,
+            message: "Each tag must be a string",
+            value: data.tags[i]
+          });
+        }
+      }
+    }
+  }
+  if (data.author !== void 0 && typeof data.author !== "string") {
+    issues.push({
+      path: "author",
+      message: "Author must be a string if provided",
+      value: data.author
+    });
+  }
+  if (data.version !== void 0 && typeof data.version !== "string") {
+    issues.push({
+      path: "version",
+      message: "Version must be a string if provided",
+      value: data.version
+    });
+  }
+}
+
+// src/skill/loader.ts
+init_paths();
+init_symlink();
 function parseFrontmatter(content) {
   try {
     const result = (0, import_gray_matter.default)(content);
@@ -13185,23 +14222,6 @@ function toSkillFrontmatter(data) {
     version: data.version
   };
 }
-function loadSkill(name) {
-  logger.debug(`Loading skill: ${name}`);
-  const content = readSkillFile(name);
-  const filePath = getSkillFilePath(name);
-  const parsed = parseFrontmatter(content);
-  const frontmatter = toSkillFrontmatter(parsed.data);
-  if (frontmatter.name !== name) {
-    logger.warn(
-      `Skill name mismatch: file path says '${name}', frontmatter says '${frontmatter.name}'`
-    );
-  }
-  return {
-    frontmatter,
-    content: parsed.content,
-    filePath
-  };
-}
 function extractSkillMetadata(content) {
   try {
     const parsed = parseFrontmatter(content);
@@ -13234,23 +14254,23 @@ function extractSkillMetadata(content) {
 
 // src/commands/skill/validate.ts
 init_paths();
-var fs18 = __toESM(require("fs"));
-var path14 = __toESM(require("path"));
+var fs24 = __toESM(require("fs"));
+var path19 = __toESM(require("path"));
 var skillValidateCommand = new Command("validate").description("Validate local skill files").argument("[skillPath]", "Path to skill file or directory (defaults to ~/.refly/skills)").option("--fix", "Attempt to fix common issues").action(async (skillPath, _options) => {
   try {
     const results = [];
     let targetPath;
     if (skillPath) {
-      targetPath = path14.resolve(skillPath);
+      targetPath = path19.resolve(skillPath);
     } else {
       await ensureSkillsDir();
       targetPath = getSkillsDir();
     }
-    if (!fs18.existsSync(targetPath)) {
+    if (!fs24.existsSync(targetPath)) {
       fail(ErrorCodes.NOT_FOUND, `Path not found: ${targetPath}`);
       return;
     }
-    const stats = fs18.statSync(targetPath);
+    const stats = fs24.statSync(targetPath);
     if (stats.isFile()) {
       const result = validateSkillFile(targetPath);
       results.push(result);
@@ -13283,7 +14303,7 @@ var skillValidateCommand = new Command("validate").description("Validate local s
 });
 function validateSkillFile(filePath) {
   try {
-    const content = fs18.readFileSync(filePath, "utf-8");
+    const content = fs24.readFileSync(filePath, "utf-8");
     const { frontmatter, issues } = extractSkillMetadata(content);
     const errors = issues.map((i) => `${i.path}: ${i.message}`);
     const warnings = [];
@@ -13309,9 +14329,9 @@ function validateSkillFile(filePath) {
   }
 }
 function findSkillFiles(dir, files = []) {
-  const entries = fs18.readdirSync(dir, { withFileTypes: true });
+  const entries = fs24.readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = path14.join(dir, entry.name);
+    const fullPath = path19.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (!entry.name.startsWith(".")) {
         findSkillFiles(fullPath, files);
@@ -13325,85 +14345,76 @@ function findSkillFiles(dir, files = []) {
 
 // src/commands/skill/sync.ts
 init_cjs_shims();
-var skillSyncCommand = new Command("sync").description("Sync local skill registry with filesystem").option("--dry-run", "Show changes without writing registry").option("--prune", "Remove registry entries that have no local files").action(async (options) => {
+init_symlink();
+init_paths();
+var fs25 = __toESM(require("fs"));
+var path20 = __toESM(require("path"));
+var skillSyncCommand = new Command("sync").description("Validate and repair skill symlinks").option("--dry-run", "Show issues without making changes").option("--fix", "Attempt to repair broken symlinks").option("--prune", "Remove orphan symlinks (symlinks without source directory)").action(async (options) => {
   try {
-    const registry = readRegistry();
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const existingLocal = new Map(
-      registry.skills.filter((s) => s.source === "local").map((s) => [s.name, s])
-    );
-    const nonLocal = registry.skills.filter((s) => s.source !== "local");
-    const skillDirs = listSkillDirectories();
+    const symlinks = listSkillSymlinks();
     const warnings = [];
     const errors = [];
-    const updatedLocal = [];
-    let added = 0;
-    let updated = 0;
-    let unchanged = 0;
-    let skipped = 0;
-    for (const dirName of skillDirs) {
-      try {
-        const loaded = loadSkill(dirName);
-        const frontmatter = loaded.frontmatter;
-        if (frontmatter.name !== dirName) {
-          warnings.push(`Skill name mismatch: dir=${dirName}, frontmatter=${frontmatter.name}`);
-          skipped += 1;
-          continue;
-        }
-        const prev = existingLocal.get(frontmatter.name);
-        const entry = {
-          name: frontmatter.name,
-          description: frontmatter.description,
-          workflowId: frontmatter.workflowId,
-          triggers: frontmatter.triggers,
-          path: getSkillRelativePath(frontmatter.name),
-          createdAt: prev?.createdAt ?? now,
-          updatedAt: now,
-          source: "local",
-          tags: frontmatter.tags,
-          author: frontmatter.author,
-          version: frontmatter.version
-        };
-        updatedLocal.push(entry);
-        if (!prev) {
-          added += 1;
-        } else if (prev.description !== entry.description || prev.workflowId !== entry.workflowId || JSON.stringify(prev.triggers) !== JSON.stringify(entry.triggers) || JSON.stringify(prev.tags ?? []) !== JSON.stringify(entry.tags ?? []) || prev.author !== entry.author || prev.version !== entry.version || prev.path !== entry.path) {
-          updated += 1;
-        } else {
-          unchanged += 1;
+    let valid = 0;
+    let invalid = 0;
+    let repaired = 0;
+    let orphans = 0;
+    for (const symlink of symlinks) {
+      if (symlink.isValid) {
+        valid += 1;
+      } else {
+        invalid += 1;
+        warnings.push(`Invalid symlink: ${symlink.claudePath} -> ${symlink.target}`);
+        if (options.fix && !options.dryRun) {
+          const result = createSkillSymlink(symlink.name);
+          if (result.success) {
+            repaired += 1;
+          } else {
+            errors.push(`Failed to repair ${symlink.name}: ${result.error}`);
+          }
         }
-      } catch (err) {
-        errors.push(err instanceof Error ? err.message : "Failed to load skill");
-        skipped += 1;
       }
     }
-    const updatedNames = new Set(updatedLocal.map((s) => s.name));
-    const orphans = Array.from(existingLocal.keys()).filter((name) => !updatedNames.has(name));
-    const pruned = options.prune ? orphans.length : 0;
-    if (!options.prune && orphans.length > 0) {
-      warnings.push(`Orphan registry entries (no local files): ${orphans.join(", ")}`);
+    const skillsDir = getReflySkillsDir();
+    if (fs25.existsSync(skillsDir)) {
+      const entries = fs25.readdirSync(skillsDir, { withFileTypes: true });
+      const symlinkNames = new Set(symlinks.map((s) => s.name));
+      for (const entry of entries) {
+        if (entry.isDirectory() && entry.name !== "base") {
+          if (!symlinkNames.has(entry.name)) {
+            orphans += 1;
+            warnings.push(`Orphan directory (no symlink): ${path20.join(skillsDir, entry.name)}`);
+            if (options.prune && !options.dryRun) {
+              const result = createSkillSymlink(entry.name);
+              if (result.success) {
+                repaired += 1;
+              }
+            }
+          }
+        }
+      }
     }
-    const preservedLocal = options.prune ? [] : registry.skills.filter((s) => s.source === "local" && orphans.includes(s.name));
-    const finalSkills = [...nonLocal, ...updatedLocal, ...preservedLocal];
-    if (!options.dryRun) {
-      writeRegistry({
-        ...registry,
-        skills: finalSkills,
-        updatedAt: now
-      });
+    for (const symlink of symlinks) {
+      if (!symlink.isValid && options.prune && !options.dryRun) {
+        removeSkillSymlink(symlink.name);
+      }
     }
     const summary = {
-      scanned: skillDirs.length,
-      added,
-      updated,
-      unchanged,
-      skipped,
-      pruned,
+      scanned: symlinks.length,
+      valid,
+      invalid,
+      repaired,
+      orphans,
       warnings: warnings.length
     };
     ok("skill.sync", {
       dryRun: Boolean(options.dryRun),
       summary,
+      symlinks: symlinks.map((s) => ({
+        name: s.name,
+        claudePath: s.claudePath,
+        target: s.target,
+        valid: s.isValid
+      })),
       warnings: warnings.length ? warnings : void 0,
       errors: errors.length ? errors : void 0
     });
@@ -13416,13 +14427,13 @@ var skillSyncCommand = new Command("sync").description("Sync local skill registr
 });
 
 // src/commands/skill/index.ts
-var skillCommand = new Command("skill").description("Manage skill packages and local skills").addCommand(skillListCommand).addCommand(skillGetCommand).addCommand(skillCreateCommand).addCommand(skillDeleteCommand).addCommand(skillPublishCommand).addCommand(skillUnpublishCommand).addCommand(skillSearchCommand).addCommand(skillInstallCommand).addCommand(skillUninstallCommand).addCommand(skillInstallationsCommand).addCommand(skillRunCommand).addCommand(skillValidateCommand).addCommand(skillSyncCommand);
+var skillCommand = new Command("skill").description("Manage skill packages and local skills").addCommand(skillListCommand).addCommand(skillGetCommand).addCommand(skillCreateCommand).addCommand(skillUpdateCommand).addCommand(skillPublishCommand).addCommand(skillUnpublishCommand).addCommand(skillSearchCommand).addCommand(skillInstallCommand).addCommand(skillUninstallCommand).addCommand(skillInstallationsCommand).addCommand(skillRunCommand).addCommand(skillValidateCommand).addCommand(skillSyncCommand);
 
 // src/bin/refly.ts
 function getVersion() {
   try {
-    const pkgPath = path15.join(__dirname, "..", "..", "package.json");
-    const pkg = JSON.parse(fs19.readFileSync(pkgPath, "utf-8"));
+    const pkgPath = path21.join(__dirname, "..", "..", "package.json");
+    const pkg = JSON.parse(fs26.readFileSync(pkgPath, "utf-8"));
     return pkg.version || "0.1.0";
   } catch {
     return "0.1.0";