@floomhq/floom 1.0.2 → 1.0.4

package/dist/cli.js

@@ -14,77 +14,101 @@ import { sync } from "./sync.js";
 import { printMcpSetup } from "./mcp.js";
 import { setupAgent } from "./setup.js";
 import { search } from "./search.js";
+import { scanSkill } from "./scan.js";
 import { libraryAddSkill, libraryCreate, libraryList, libraryRemoveSkill, librarySubscribe, libraryUnsubscribe, moveSkill, } from "./library.js";
 import { c, symbols } from "./ui.js";
 import { printError, FloomError } from "./errors.js";
-const VERSION = "1.0.2";
-const PKG = { name: "@floomhq/floom", version: VERSION };
+import { CLI_VERSION } from "./version.js";
+const PKG = { name: "@floomhq/floom", version: CLI_VERSION };
 const V1_NOT_AVAILABLE = "Not available in Floom Version 1.";
 function usage() {
     const out = `
- ${c.coral("  __ _")}
- ${c.coral(" / _| |___  ___ _ __")}   ${c.dim(`v${VERSION}`)}
- ${c.coral("|  _| / _ \\/ _ \\ '  \\")}
- ${c.coral("|_| |_\\___/\\___/_|_|_|")}
+ ${c.coral("       ________")}
+ ${c.coral("      / ____/ /___  ____  ____ ___")}      ${c.dim(`v${CLI_VERSION}`)}
+ ${c.coral("     / /_  / / __ \\/ __ \\/ __ `__ \\")}
+ ${c.coral("    / __/ / / /_/ / /_/ / / / / / /")}
+ ${c.coral("   /_/   /_/\\____/\\____/_/ /_/ /_/")}
 
  ${c.bold("Share AI agent skills with a link.")}
  ${c.dim("Publish knowledge, instructions, and workflows from your terminal.")}
 
- ${c.bold("Usage")}
-   ${c.cyan("floom")} ${c.dim("<command> [options]")}
+ ${c.bold("Do this next")}
+   ${c.dim("1. Add a skill someone sent you")}
+      ${c.cyan("npx -y @floomhq/floom add")} ${c.dim("https://floom.dev/s/ffas93ud --target claude")}
 
- ${c.bold("Start Here")}
-   ${c.cyan("floom init")} ${c.dim("support-tone.md")}
-      ${c.dim("Create a starter Markdown skill.")}
+   ${c.dim("2. Publish your own skill")}
+      ${c.cyan("npx -y @floomhq/floom init")} ${c.dim("support-tone.md")}
+      ${c.dim("# edit support-tone.md")}
+      ${c.cyan("npx -y @floomhq/floom scan")} ${c.dim("support-tone.md")}
+      ${c.cyan("npx -y @floomhq/floom login")}
+      ${c.cyan("npx -y @floomhq/floom publish")} ${c.dim("support-tone.md --type instruction --public")}
 
-   ${c.cyan("floom add")} ${c.dim("https://floom.dev/s/ffas93ud")}
-      ${c.dim("Install a public skill. No account needed.")}
+   ${c.dim("3. Tell your agent where skills land")}
+      ${c.cyan("npx -y @floomhq/floom setup")} ${c.dim("--target claude --yes")}
+      ${c.cyan("npx -y @floomhq/floom setup")} ${c.dim("--target codex --yes")}
 
-   ${c.cyan("floom publish")} ${c.dim("./support-tone.md --type instruction --public")}
-      ${c.dim("Publish Markdown and print a share link.")}
+ ${c.bold("Safety")}
+   ${c.yellow("!")} ${c.dim("publish scans for API keys, prompt injection, and exfiltration.")}
 
- ${c.bold("Commands")}
-     ${c.dim("Receive")}
-     ${c.cyan("add")} ${c.dim("<url-or-slug>")}             Install into ~/.claude/skills/
-     ${c.cyan("info")} ${c.dim("<url-or-slug>")}            Show metadata ${c.dim("[--json]")}
-     ${c.cyan("search")} ${c.dim("<query>")}                Search public skills and libraries ${c.dim("[--json]")}
+ ${c.bold("More")}
+   ${c.cyan("floom commands")}    ${c.dim("Full command list")}
+   ${c.cyan("floom doctor")}      ${c.dim("Check auth, API, and local folders")}
+   ${c.dim("Docs")}           https://floom.dev
+`;
+    process.stdout.write(out);
+}
+function commandUsage() {
+    const out = `
+ ${c.bold("Usage:")} ${c.cyan("floom")} ${c.dim("<command> [flags]")}
 
-   ${c.dim("Create")}
-     ${c.cyan("init")} ${c.dim("[file.md]")}                Create a starter skill file
-     ${c.cyan("publish")} ${c.dim("<file.md>")}             Upload Markdown and print a URL
+ ${c.bold("Commands")}
+   ${c.dim("Skills")}
+     ${c.cyan("add")} ${c.dim("<url>")}          Install a skill into the local agent skills folder
+                       ${c.dim("Alias: install")}
+                       ${c.dim("Flags: --target claude|codex (default: claude)")}
+     ${c.cyan("search")} ${c.dim("<query>")}     Find public skills and libraries
+     ${c.cyan("info")} ${c.dim("<url>")}         Show skill metadata
 
-   ${c.dim("Publish Flags")}
-     ${c.dim("--public | --private | --unlisted")}        ${c.dim("Set link visibility")}
-     ${c.dim("--type <kind>")}                            ${c.dim("knowledge | instruction | workflow | skill")}
-     ${c.dim("--installs-as <target>")}                   ${c.dim("Set install target metadata")}
-       ${c.dim("claude_skill | memory | rule | codex_instruction")}
-     ${c.dim("--version <label>")}                        ${c.dim("Attach a human version label")}
+   ${c.dim("Publishing")}
+     ${c.cyan("init")} ${c.dim("[path]")}        Create a skill scaffold
+     ${c.cyan("scan")} ${c.dim("<path>")}        Check for secrets, injection, exfiltration
+     ${c.cyan("publish")} ${c.dim("<path>")}     Scan, publish, and print a share link
+                       ${c.dim("Flags: --public, --private, --type knowledge|instruction|workflow|skill")}
+                       ${c.dim("       --skill-version <label>")}
 
    ${c.dim("Account")}
-     ${c.cyan("login")}                         Sign in with Google
-     ${c.cyan("list")}                          List your published skills ${c.dim("[--json]")}
-     ${c.cyan("library")}                       Create, browse, and subscribe to skill libraries
+     ${c.cyan("login")}              Authenticate
+     ${c.cyan("list")}               Your published skills
+     ${c.cyan("delete")} ${c.dim("<url>")}       Delete one of your skills
+                       ${c.dim("Alias: rm")}
+     ${c.cyan("whoami")}             Show the signed-in account
+     ${c.cyan("logout")}             Switch accounts or remove local credentials
+
+   ${c.dim("Agent setup")}
+     ${c.cyan("setup")}              Configure Claude Code or Codex instructions
+                       ${c.dim("Alias: connect")}
+                       ${c.dim("Flags: --target claude|codex, --yes, --dry-run")}
+     ${c.cyan("doctor")}             Troubleshoot auth, API, and local folders
+
+   ${c.dim("Advanced")}
+     ${c.cyan("library")}            Create, browse, and subscribe to libraries
+                       ${c.dim("Alias: lib")}
      ${c.cyan("move")} ${c.dim("<slug> --folder <path>")}  Place a saved skill in a local folder
-     ${c.cyan("delete")} ${c.dim("<url-or-slug>")}          Delete one of your skills ${c.dim("[--yes]")}
-     ${c.cyan("whoami")}                        Show the signed-in account
-     ${c.cyan("logout")}                        Delete local credentials
+     ${c.cyan("mcp")}                Print optional MCP setup guidance
+     ${c.cyan("sync")}               Preview pull of published, saved, and library skills
+     ${c.cyan("watch")}              Preview polling sync loop
 
-   ${c.dim("System")}
-     ${c.cyan("setup")} ${c.dim("[--target claude|codex] [--file path]")}  Add Floom guidance to agent instructions
-     ${c.cyan("connect")} ${c.dim("[--target claude|codex]")}              Alias for setup
-     ${c.cyan("mcp")}                           Print MCP setup guidance
-     ${c.cyan("sync")}                          Preview: pull published, saved, and library skills
-     ${c.cyan("watch")}                         Preview: poll published, saved, and library skills ${c.dim("[--interval <seconds>, min 10]")}
-     ${c.cyan("doctor")}                        Diagnose auth, API, and local setup
-     ${c.cyan("--help")}                        Show this help
-     ${c.cyan("--version")}                     Show version
+ ${c.bold("Examples")}
+   ${c.cyan("floom add")} ${c.dim("https://floom.dev/s/ffas93ud")}
+   ${c.cyan("floom publish")} ${c.dim("support-tone.md --type instruction --public")}
+   ${c.cyan("floom setup")} ${c.dim("--target claude --yes")}
 
- ${c.bold("Env")}
-   ${c.cyan("FLOOM_API_URL")}                   Override the API host
+ ${c.bold("Help")}
+   ${c.cyan("floom commands")}       Show this reference
+   ${c.cyan("--help")}               Show this reference
+   ${c.cyan("--version")}            Show CLI version
 
- ${c.bold("Links")}
-   ${c.dim("Docs")}     https://floom.dev
-   ${c.dim("Source")}   https://github.com/floomhq/floom
+ ${c.dim("Run")} ${c.cyan("floom")} ${c.dim("with no command for the guided start screen.")}
 `;
     process.stdout.write(out);
 }
@@ -110,14 +134,17 @@ function readFlagValue(argv, index, flag) {
 }
 function parseFlags(argv) {
     const out = { visibility: "unlisted", update: false, rest: [] };
+    let visibilityFlag = null;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? "";
-        if (a === "--public")
-            out.visibility = "public";
-        else if (a === "--private")
-            out.visibility = "private";
-        else if (a === "--unlisted")
-            out.visibility = "unlisted";
+        if (a === "--public" || a === "--private" || a === "--unlisted") {
+            const nextVisibility = a.slice(2);
+            if (visibilityFlag && visibilityFlag !== nextVisibility) {
+                throw new FloomError("Conflicting visibility flags.", "Use only one of: --public, --private, or --unlisted.");
+            }
+            visibilityFlag = nextVisibility;
+            out.visibility = nextVisibility;
+        }
         else if (a === "--update") {
             throw new FloomError(V1_NOT_AVAILABLE, "`floom publish --update` is planned for a later Floom release.");
         }
@@ -140,19 +167,36 @@ function parseFlags(argv) {
             out.installsAs = value;
             i = nextIndex;
         }
-        else if (a === "--version" || a.startsWith("--version=")) {
-            const { value, nextIndex } = readFlagValue(argv, i, "--version");
+        else if (a === "--skill-version" || a.startsWith("--skill-version=") || a === "--version" || a.startsWith("--version=")) {
+            const flagName = a.startsWith("--skill-version") ? "--skill-version" : "--version";
+            const { value, nextIndex } = readFlagValue(argv, i, flagName);
             if (!VERSION_RE.test(value)) {
-                throw new FloomError(`Invalid --version: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
+                throw new FloomError(`Invalid ${flagName}: ${value}`, "Use 1-64 characters: letters, numbers, dots, underscores, plus, or hyphen.");
             }
             out.version = value;
             i = nextIndex;
         }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom publish skill.md --type instruction --public`.");
+        }
         else
             out.rest.push(a);
     }
     return out;
 }
+function parseInitArgs(argv) {
+    let file;
+    for (const a of argv) {
+        if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom init skill.md`.");
+        }
+        if (file) {
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom init skill.md`.");
+        }
+        file = a;
+    }
+    return file ? { file } : {};
+}
 function parseListFlags(argv) {
     const out = { json: false };
     for (const a of argv) {
@@ -161,6 +205,9 @@ function parseListFlags(argv) {
         else if (a.startsWith("--")) {
             throw new FloomError(`Unknown flag: ${a}`, "Try `floom list --help` for usage.");
         }
+        else {
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom list --json`.");
+        }
     }
     return out;
 }
@@ -173,9 +220,38 @@ function parseInfoFlags(argv) {
             throw new FloomError(`Unknown flag: ${a}`, "Try `floom info <slug> --json`.");
         else if (!out.slug)
             out.slug = a;
+        else
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom info <slug> --json`.");
     }
     return out;
 }
+function parseAddArgs(argv) {
+    let slug;
+    let target;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--target" || a.startsWith("--target=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--target");
+            if (value !== "claude" && value !== "codex") {
+                throw new FloomError("Invalid --target.", "Use `claude` or `codex`.");
+            }
+            target = value;
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, "Try `floom add <url-or-slug> --target claude`.");
+        }
+        else if (slug) {
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom add <url-or-slug> --target claude`.");
+        }
+        else
+            slug = a;
+    }
+    if (!slug) {
+        throw new FloomError("Missing skill slug.", "Try: `floom add <url-or-slug> --target claude`");
+    }
+    return target ? { slug, target } : { slug };
+}
 function parseSearchFlags(argv) {
     const out = { json: false };
     const terms = [];
@@ -215,9 +291,19 @@ function parseDeleteFlags(argv) {
             throw new FloomError(`Unknown flag: ${a}`, "Try `floom delete <slug> --yes`.");
         else if (!out.slug)
             out.slug = a;
+        else
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom delete <slug> --yes`.");
     }
     return out;
 }
+function rejectArgs(argv, usageHint) {
+    const arg = argv[0];
+    if (!arg)
+        return;
+    if (arg.startsWith("--"))
+        throw new FloomError(`Unknown flag: ${arg}`, usageHint);
+    throw new FloomError(`Unexpected argument: ${arg}`, usageHint);
+}
 function parseSetupFlags(argv) {
     const out = { dryRun: false, yes: false };
     for (let i = 0; i < argv.length; i++) {
@@ -341,6 +427,9 @@ async function runLibrary(argv) {
             if (!librarySlug || !skillSlug) {
                 throw new FloomError("Missing library or skill slug.", "Try `floom library add team-onboarding support-tone --folder support`.");
             }
+            if (flags.rest.length > 2) {
+                throw new FloomError(`Unexpected argument: ${flags.rest[2]}`, "Try `floom library add team-onboarding support-tone --folder support`.");
+            }
             await libraryAddSkill({
                 librarySlug,
                 skillSlug,
@@ -355,6 +444,9 @@ async function runLibrary(argv) {
             if (!librarySlug || !skillSlug) {
                 throw new FloomError("Missing library or skill slug.", "Try `floom library remove team-onboarding support-tone`.");
             }
+            if (rest.length > 2) {
+                throw new FloomError(`Unexpected argument: ${rest[2]}`, "Try `floom library remove team-onboarding support-tone`.");
+            }
             await libraryRemoveSkill(librarySlug, skillSlug);
             return;
         }
@@ -362,6 +454,9 @@ async function runLibrary(argv) {
             const slug = rest[0];
             if (!slug)
                 throw new FloomError("Missing library slug.", "Try `floom library subscribe superpowers`.");
+            if (rest.length > 1) {
+                throw new FloomError(`Unexpected argument: ${rest[1]}`, "Try `floom library subscribe superpowers`.");
+            }
             await librarySubscribe(slug);
             return;
         }
@@ -369,6 +464,9 @@ async function runLibrary(argv) {
             const slug = rest[0];
             if (!slug)
                 throw new FloomError("Missing library slug.", "Try `floom library unsubscribe superpowers`.");
+            if (rest.length > 1) {
+                throw new FloomError(`Unexpected argument: ${rest[1]}`, "Try `floom library unsubscribe superpowers`.");
+            }
             await libraryUnsubscribe(slug);
             return;
         }
@@ -401,6 +499,19 @@ function parseWatchFlags(argv) {
 function notAvailable(feature) {
     throw new FloomError(V1_NOT_AVAILABLE, `${feature} is planned for a later Floom release.`);
 }
+function parseSingleFileArg(argv, usageHint) {
+    let file;
+    for (const a of argv) {
+        if (a.startsWith("--"))
+            throw new FloomError(`Unknown flag: ${a}`, usageHint);
+        if (file)
+            throw new FloomError(`Unexpected argument: ${a}`, usageHint);
+        file = a;
+    }
+    if (!file)
+        throw new FloomError("Missing file argument.", usageHint);
+    return file;
+}
 function sleep(ms, signal) {
     if (signal.aborted)
         return Promise.resolve();
@@ -456,28 +567,37 @@ async function main() {
     try {
         switch (cmd) {
             case undefined:
+                usage();
+                return;
             case "--help":
             case "-h":
             case "help":
-                usage();
+                commandUsage();
+                return;
+            case "commands":
+                rejectArgs(rest, "Try `floom commands`.");
+                commandUsage();
                 return;
             case "--version":
             case "-v":
-                process.stdout.write(`${VERSION}\n`);
+                process.stdout.write(`${CLI_VERSION}\n`);
                 return;
             case "login":
+                rejectArgs(rest, "Try `floom login`.");
                 await login();
                 return;
             case "logout":
+                rejectArgs(rest, "Try `floom logout`.");
                 await deleteConfig();
                 process.stdout.write(`\n${symbols.ok}  Signed out\n\n`);
                 return;
             case "whoami":
+                rejectArgs(rest, "Try `floom whoami`.");
                 await whoami();
                 return;
             case "init": {
-                const file = rest[0];
-                await init(file);
+                const flags = parseInitArgs(rest);
+                await init(flags.file);
                 return;
             }
             case "publish": {
@@ -486,6 +606,9 @@ async function main() {
                 if (!file) {
                     throw new FloomError("Missing file argument.", "Try: `floom publish skill.md`");
                 }
+                if (flags.rest.length > 1) {
+                    throw new FloomError(`Unexpected argument: ${flags.rest[1]}`, "Try: `floom publish skill.md`");
+                }
                 await publish({
                     file,
                     visibility: flags.visibility,
@@ -496,6 +619,11 @@ async function main() {
                 });
                 return;
             }
+            case "scan": {
+                const file = parseSingleFileArg(rest, "Try `floom scan skill.md`.");
+                await scanSkill(file);
+                return;
+            }
             case "share":
                 notAvailable("`floom share`");
             case "list": {
@@ -524,14 +652,12 @@ async function main() {
             }
             case "add":
             case "install": {
-                const slug = rest.find((a) => !a.startsWith("--"));
-                if (!slug) {
-                    throw new FloomError("Missing skill slug.", "Try: `floom add <url-or-slug>`");
-                }
-                await install(slug);
+                const flags = parseAddArgs(rest);
+                await install(flags.slug, flags.target ? { target: flags.target } : {});
                 return;
             }
             case "sync":
+                rejectArgs(rest, "Try `floom sync`.");
                 await sync();
                 return;
             case "setup":
@@ -564,13 +690,18 @@ async function main() {
                 if (flags.folder === undefined) {
                     throw new FloomError("Missing --folder.", "Use --folder <path> or --root. Add --tag or --tags when useful.");
                 }
+                if (flags.rest.length > 1) {
+                    throw new FloomError(`Unexpected argument: ${flags.rest[1]}`, "Try `floom move support-tone --folder support/tone`.");
+                }
                 await moveSkill({ slug, folder: flags.folder, tags: flags.tags });
                 return;
             }
             case "mcp":
+                rejectArgs(rest, "Try `floom mcp`.");
                 printMcpSetup();
                 return;
             case "doctor":
+                rejectArgs(rest, "Try `floom doctor`.");
                 await doctor();
                 return;
             default:

package/dist/config.js

@@ -8,6 +8,9 @@ export const DEFAULT_WEB_URL = "https://floom.dev";
 export function getApiUrl() {
     return process.env.FLOOM_API_URL?.replace(/\/$/, "") ?? DEFAULT_API_URL;
 }
+export function resolveApiUrl(cfg) {
+    return process.env.FLOOM_API_URL?.replace(/\/$/, "") ?? cfg?.apiUrl?.replace(/\/$/, "") ?? DEFAULT_API_URL;
+}
 export function getWebUrl() {
     return process.env.FLOOM_WEB_URL?.replace(/\/$/, "") ?? DEFAULT_WEB_URL;
 }

package/dist/delete.js

@@ -1,7 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import ora from "ora";
-import { getApiUrl, readConfig } from "./config.js";
+import { readConfig, resolveApiUrl } from "./config.js";
 import { deleteRequest } from "./lib/api.js";
 import { c, symbols } from "./ui.js";
 import { FloomError } from "./errors.js";
@@ -43,7 +43,7 @@ export async function deleteSkill(opts) {
             return;
         }
     }
-    const apiUrl = cfg.apiUrl ?? getApiUrl();
+    const apiUrl = resolveApiUrl(cfg);
     const spinner = ora({ text: c.dim(`Deleting ${slug}...`), color: "yellow" }).start();
     try {
         await deleteRequest(`${apiUrl}/api/v1/skills/${encodeURIComponent(slug)}`, "delete skill", cfg.accessToken);

package/dist/doctor.js

@@ -1,9 +1,10 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { stat, readFile, access, readdir, constants } from "node:fs/promises";
-import { getApiUrl, readConfig, CONFIG_PATH } from "./config.js";
+import { readConfig, CONFIG_PATH, resolveApiUrl } from "./config.js";
+import { floomFetch } from "./lib/api.js";
 import { c, symbols } from "./ui.js";
-const CLI_VERSION = "1.0.2";
+import { CLI_VERSION, compareSemverish, formatVersionLabel } from "./version.js";
 function statusBadge(s) {
     if (s === "ok")
         return c.green(symbols.ok);
@@ -20,10 +21,11 @@ async function checkAuth() {
             detail: "Receiver mode ready. Sign in only when publishing or listing your own skills.",
         };
     }
-    const apiUrl = cfg.apiUrl ?? getApiUrl();
+    const apiUrl = resolveApiUrl(cfg);
     try {
-        const res = await fetch(`${apiUrl}/api/me`, {
-            headers: { authorization: `Bearer ${cfg.accessToken}` },
+        const res = await floomFetch(`${apiUrl}/api/me`, "check authentication", {
+            token: cfg.accessToken,
+            checkOk: false,
         });
         if (res.status === 401) {
             return {
@@ -196,48 +198,49 @@ async function checkLastSync() {
     }
 }
 async function checkVersion() {
-    const apiUrl = (await readConfig())?.apiUrl ?? getApiUrl();
+    const apiUrl = resolveApiUrl(await readConfig());
     try {
-        const res = await fetch(`${apiUrl}/api/v1/cli-version`, {
+        const res = await floomFetch(`${apiUrl}/api/v1/cli-version`, "check CLI version", {
             headers: { accept: "application/json" },
+            checkOk: false,
         });
         if (!res.ok) {
             // Endpoint optional — treat as info-only, not a failure
             return {
                 name: "Version",
                 status: "ok",
-                detail: `CLI v${CLI_VERSION} (server check skipped)`,
+                detail: `CLI ${formatVersionLabel(CLI_VERSION)} (server check skipped)`,
             };
         }
         const data = (await res.json());
-        if (data.min && CLI_VERSION < data.min) {
+        if (data.min && compareSemverish(CLI_VERSION, data.min) < 0) {
             return {
                 name: "Version",
                 status: "fail",
-                detail: `CLI v${CLI_VERSION} below required v${data.min}.`,
+                detail: `CLI ${formatVersionLabel(CLI_VERSION)} below required ${formatVersionLabel(data.min)}.`,
                 hint: "Run `npm i -g @floomhq/floom` to upgrade.",
             };
         }
-        if (data.latest && CLI_VERSION !== data.latest) {
+        if (data.latest && compareSemverish(CLI_VERSION, data.latest) < 0) {
             return {
                 name: "Version",
                 status: "warn",
-                detail: `CLI v${CLI_VERSION}, latest is v${data.latest}.`,
+                detail: `CLI ${formatVersionLabel(CLI_VERSION)}, latest is ${formatVersionLabel(data.latest)}.`,
                 hint: "Run `npm i -g @floomhq/floom` to upgrade.",
             };
         }
-        return { name: "Version", status: "ok", detail: `CLI v${CLI_VERSION} (current)` };
+        return { name: "Version", status: "ok", detail: `CLI ${formatVersionLabel(CLI_VERSION)} (current)` };
     }
     catch {
         return {
             name: "Version",
             status: "ok",
-            detail: `CLI v${CLI_VERSION} (offline)`,
+            detail: `CLI ${formatVersionLabel(CLI_VERSION)} (offline)`,
         };
     }
 }
 export async function doctor() {
-    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(v${CLI_VERSION})`)}\n\n`);
+    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(${formatVersionLabel(CLI_VERSION)})`)}\n\n`);
     const checks = await Promise.all([
         checkAuth(),
         checkMcp(),

package/dist/errors.js

@@ -40,8 +40,12 @@ export function friendlyNetwork(err) {
 export function printError(err) {
     if (err instanceof FloomError) {
         process.stderr.write(`\n${symbols.fail}  ${err.message}\n`);
-        if (err.hint)
-            process.stderr.write(`   ${c.dim(err.hint)}\n\n`);
+        if (err.hint) {
+            for (const line of err.hint.split("\n")) {
+                process.stderr.write(`   ${c.dim(line)}\n`);
+            }
+            process.stderr.write("\n");
+        }
         else
             process.stderr.write("\n");
         return;

package/dist/info.js

@@ -1,9 +1,10 @@
 import ora from "ora";
-import { getApiUrl, readConfig } from "./config.js";
+import { readConfig, resolveApiUrl } from "./config.js";
 import { getJson } from "./lib/api.js";
 import { extractRequires, formatToolList, formatType } from "./lib/skill-labels.js";
 import { c, symbols } from "./ui.js";
 import { FloomError } from "./errors.js";
+const SLUG_RE = /^[A-Za-z0-9_-]{1,128}$/;
 function slugFromInput(input) {
     const trimmed = input.trim();
     try {
@@ -19,8 +20,11 @@ export async function info(opts) {
     const slug = slugFromInput(opts.slug);
     if (!slug)
         throw new FloomError("Missing skill slug.", "Try: `floom info <slug>`");
+    if (!SLUG_RE.test(slug)) {
+        throw new FloomError(`Invalid skill slug: ${opts.slug}`, "Use a Floom skill slug or URL.");
+    }
     const cfg = await readConfig();
-    const apiUrl = cfg?.apiUrl ?? getApiUrl();
+    const apiUrl = resolveApiUrl(cfg);
     const spinner = opts.json ? null : ora({ text: c.dim(`Loading ${slug}...`), color: "yellow" }).start();
     let detail;
     try {

package/dist/init.js

@@ -1,5 +1,5 @@
 import { writeFile, access } from "node:fs/promises";
-import { resolve, basename } from "node:path";
+import { dirname, resolve, basename } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { c, symbols } from "./ui.js";
@@ -43,10 +43,29 @@ export async function init(filename) {
             return;
         }
     }
-    await writeFile(filePath, TEMPLATE, "utf8");
+    try {
+        await writeFile(filePath, TEMPLATE, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new FloomError(`Directory not found: ${dirname(target)}`, "Create the directory first, or choose a filename in the current directory.");
+        }
+        if (code === "EISDIR") {
+            throw new FloomError(`That's a directory, not a file: ${target}`);
+        }
+        throw new FloomError(`Couldn't create ${target}: ${err.message}`);
+    }
     process.stdout.write(`\n${symbols.ok}  Created ${c.bold(basename(filePath))}\n`);
-    process.stdout.write(`   ${c.dim("Fill in the title + description, then run:")}\n`);
-    process.stdout.write(`   ${c.cyan(`floom publish ${target}`)}\n\n`);
+    process.stdout.write(`\n   ${c.bold("Next")}\n`);
+    process.stdout.write(`   ${c.dim("1.")} Fill in the title, description, and instructions.\n`);
+    process.stdout.write(`   ${c.dim("2.")} Check it: ${c.cyan(`floom scan ${shellQuote(target)}`)}\n`);
+    process.stdout.write(`   ${c.dim("3.")} Publish:  ${c.cyan(`floom publish ${shellQuote(target)} --type instruction --public`)}\n\n`);
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
 }
 async function fileExists(p) {
     try {