@floomhq/floom 1.0.8 → 1.0.9

package/README.md

@@ -27,11 +27,12 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 - `npx -y @floomhq/floom publish <file.md>` — scan and upload a Markdown file. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, `--skill-version <label>`, and `--share <email>`. `--share` sends the normal link by email; no account is needed to add unlisted or public links.
 - `npx -y @floomhq/floom share <slug>` — email-share one of your skills. Optional `--add <email>`, `--remove <email>`, and `--list`.
 - `npx -y @floomhq/floom list` — show your published skills. Optional `--json`.
-- `npx -y @floomhq/floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>.md`. Optional `--setup` connects Claude Code and `--force` replaces an existing local copy.
+- `npx -y @floomhq/floom add <url-or-slug>` — fetch a skill into `~/.claude/skills/<slug>.md`. Optional `--setup` connects Claude Code, `--force` / `--update` replaces an existing local copy, and `--json` prints machine-readable output.
+- `npx -y @floomhq/floom update <url-or-slug>` — install the latest remote skill content, replacing the local copy.
 - `npx -y @floomhq/floom info <url-or-slug>` — show skill metadata. Optional `--json`.
 - `npx -y @floomhq/floom search <query>` — search public skills and starter libraries. Optional `--library <slug>`, `--type knowledge|instruction|workflow|skill`, and `--json`.
 - `npx -y @floomhq/floom agent-prompt` — print the sentence to paste into Claude Code or Codex.
-- `npx -y @floomhq/floom setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`.
+- `npx -y @floomhq/floom setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`, `--file <path>`.
 - `npx -y @floomhq/floom connect` — alias for setup.
 - `npx -y @floomhq/floom mcp` — print MCP setup commands for supported agent CLIs.
 - `npx -y @floomhq/floom sync` — preview: pull your published, saved, and subscribed library skills into `~/.claude/skills/`.
@@ -42,9 +43,9 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 - `npx -y @floomhq/floom library subscribe <slug>` — subscribe to a public or unlisted library so sync can pull it locally.
 - `npx -y @floomhq/floom move <slug> --folder <path>` — set your local folder override for a saved or library skill.
 - `npx -y @floomhq/floom delete <url-or-slug>` — delete one of your published skills. Optional `--yes`.
-- `npx -y @floomhq/floom doctor` — diagnose your Floom setup.
-- `floom whoami` — show the signed-in account.
-- `floom logout` — delete local credentials.
+- `npx -y @floomhq/floom doctor` — diagnose your Floom setup. Optional `--json`.
+- `npx -y @floomhq/floom whoami` — show the signed-in account.
+- `npx -y @floomhq/floom logout` — delete local credentials.
 
 ## Skill format
 
@@ -65,7 +66,7 @@ version: 0.1.0
 
 Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
 
-`floom sync` and `floom watch` are Version 1 preview commands for published, saved, and subscribed library skills. They store a machine-local manifest at `~/.floom/sync-manifest.json`.
+`npx -y @floomhq/floom sync` and `npx -y @floomhq/floom watch` are Version 1 preview commands for published, saved, and subscribed library skills. They store a machine-local manifest at `~/.floom/sync-manifest.json`.
 The manifest records hashes for files Floom previously wrote. Version 1 sync writes missing files
 only. Remote updates, existing untracked files, and locally edited tracked files are skipped as
 conflicts. Symlinks are never followed. To replace a local skill manually, run

package/dist/cli.js

@@ -63,14 +63,16 @@ function usage() {
 }
 function commandUsage() {
     const out = `
- ${c.bold("Usage:")} ${c.cyan("npx -y @floomhq/floom")} ${c.dim("<command> [flags]")}
- ${c.dim("Global install binary:")} ${c.cyan("floom-skills")} ${c.dim("<command> [flags]")}
+ ${c.bold("Usage:")} ${c.cyan("npx -y @floomhq/floom")} ${c.dim("<command> [args]")}
+ ${c.dim("Global install binary:")} ${c.cyan("floom-skills")} ${c.dim("<command> [args]")}
 
  ${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), --setup, --force")}
+                       ${c.dim("Flags: --target claude|codex (default: claude), --setup, --force, --update, --json")}
+     ${c.cyan("update")} ${c.dim("<url>")}       Install the latest remote skill content, replacing the local copy
+                       ${c.dim("Alias: add --force")}
      ${c.cyan("search")} ${c.dim("<query>")}     Find public skills and libraries
      ${c.cyan("info")} ${c.dim("<url>")}         Show skill metadata
 
@@ -96,10 +98,12 @@ function commandUsage() {
    ${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.dim("Flags: --target claude|codex, --yes, --dry-run, --file <path>")}
+                       ${c.dim("       From a repo, setup writes that repo's CLAUDE.md/AGENTS.md")}
      ${c.cyan("agent-prompt")}       Print the sentence to paste into your agent
                        ${c.dim("Alias: paste")}
      ${c.cyan("doctor")}             Troubleshoot auth, API, and local folders
+                       ${c.dim("Flags: --json")}
 
    ${c.dim("Advanced")}
      ${c.cyan("library")}            Create, browse, and subscribe to libraries
@@ -160,7 +164,7 @@ function parseFlags(argv) {
             out.explicitVisibility = true;
         }
         else if (a === "--update") {
-            throw new FloomError(V1_NOT_AVAILABLE, "`floom publish --update` is planned for a later Floom release.");
+            throw new FloomError("Publish updates are not available in Floom Version 1.", "Publish as a new skill for now. Use `npx -y @floomhq/floom update <link>` to refresh installed local copies.");
         }
         else if (a === "--share" || a.startsWith("--share=")) {
             const { value, nextIndex } = readFlagValue(argv, i, "--share");
@@ -195,7 +199,7 @@ function parseFlags(argv) {
             throw new FloomError("`--version` prints the Floom CLI version at the top level.", "For skill version labels, use `--skill-version <label>`.");
         }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom publish skill.md --type instruction --public`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom publish skill.md --type instruction --public`.");
         }
         else
             out.rest.push(a);
@@ -206,7 +210,7 @@ function parseFlags(argv) {
             throw new FloomError("Too many --share recipients.", "Use 200 email addresses or fewer.");
         }
         if (out.visibility === "private") {
-            throw new FloomError("`--private --share` would email a link recipients cannot open.", "Use `--unlisted --share` for invite emails, or `floom share <slug> --add <email>` for email-gated access after publishing.");
+            throw new FloomError("`--private --share` would email a link recipients cannot open.", "Use `--unlisted --share` for invite emails, or `npx -y @floomhq/floom share <slug> --add <email>` for email-gated access after publishing.");
         }
     }
     return out;
@@ -243,22 +247,22 @@ function parseShareFlags(argv) {
             i = nextIndex;
         }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom share <slug> --add person@example.com`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom share <slug> --add person@example.com`.");
         }
         else if (!out.slug) {
             out.slug = a;
         }
         else {
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom share <slug> --add person@example.com`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom share <slug> --add person@example.com`.");
         }
     }
     if (!out.slug)
-        throw new FloomError("Missing skill slug.", "Try `floom share <slug> --add person@example.com`.");
+        throw new FloomError("Missing skill slug.", "Try `npx -y @floomhq/floom share <slug> --add person@example.com`.");
     if (out.list && (out.add.length > 0 || out.remove.length > 0)) {
         throw new FloomError("Conflicting share flags.", "Use --list by itself, or use --add/--remove.");
     }
     if (!out.list && out.add.length === 0 && out.remove.length === 0) {
-        throw new FloomError("Missing share action.", "Try `floom share <slug> --add person@example.com`.");
+        throw new FloomError("Missing share action.", "Try `npx -y @floomhq/floom share <slug> --add person@example.com`.");
     }
     return out;
 }
@@ -277,10 +281,10 @@ function parseInitArgs(argv) {
             continue;
         }
         if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom init skill.md --template brand-voice`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom init skill.md --template brand-voice`.");
         }
         if (file) {
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom init skill.md`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom init skill.md`.");
         }
         file = a;
     }
@@ -292,10 +296,10 @@ function parseListFlags(argv) {
         if (a === "--json")
             out.json = true;
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom list --help` for usage.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom list --help` for usage.");
         }
         else {
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom list --json`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom list --json`.");
         }
     }
     return out;
@@ -306,11 +310,11 @@ function parseInfoFlags(argv) {
         if (a === "--json")
             out.json = true;
         else if (a.startsWith("--"))
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom info <slug> --json`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom info <slug> --json`.");
         else if (!out.slug)
             out.slug = a;
         else
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom info <slug> --json`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom info <slug> --json`.");
     }
     return out;
 }
@@ -319,6 +323,7 @@ function parseAddArgs(argv) {
     let target;
     let setup = false;
     let force = false;
+    let json = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? "";
         if (a === "--target" || a.startsWith("--target=")) {
@@ -332,22 +337,40 @@ function parseAddArgs(argv) {
         else if (a === "--setup") {
             setup = true;
         }
-        else if (a === "--force") {
+        else if (a === "--json") {
+            json = true;
+        }
+        else if (a === "--force" || a === "--update") {
             force = true;
         }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom add <url-or-slug> --setup`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom add <url-or-slug> --setup`.");
         }
         else if (slug) {
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom add <url-or-slug> --setup`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom add <url-or-slug> --setup`.");
         }
         else
             slug = a;
     }
     if (!slug) {
-        throw new FloomError("Missing skill slug.", "Try: `floom add <url-or-slug> --setup`");
+        throw new FloomError("Missing skill slug.", "Try: `npx -y @floomhq/floom add <url-or-slug> --setup`");
+    }
+    if (json && setup) {
+        throw new FloomError("Conflicting add flags.", "Use `--json` for machine output or `--setup` for interactive agent setup.");
+    }
+    return target ? { slug, target, setup, force, json } : { slug, setup, force, json };
+}
+function parseDoctorArgs(argv) {
+    const out = { json: false };
+    for (const a of argv) {
+        if (a === "--json")
+            out.json = true;
+        else if (a.startsWith("--"))
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom doctor --json`.");
+        else
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom doctor --json`.");
     }
-    return target ? { slug, target, setup, force } : { slug, setup, force };
+    return out;
 }
 function parseSearchFlags(argv) {
     const out = { json: false };
@@ -370,7 +393,7 @@ function parseSearchFlags(argv) {
             i = nextIndex;
         }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom search \"support tone\" --type instruction`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom search \"support tone\" --type instruction`.");
         }
         else {
             terms.push(a);
@@ -385,11 +408,11 @@ function parseDeleteFlags(argv) {
         if (a === "--yes" || a === "-y")
             out.yes = true;
         else if (a.startsWith("--"))
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom delete <slug> --yes`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom delete <slug> --yes`.");
         else if (!out.slug)
             out.slug = a;
         else
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom delete <slug> --yes`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom delete <slug> --yes`.");
     }
     return out;
 }
@@ -423,12 +446,12 @@ function parseSetupFlags(argv) {
             i = nextIndex;
         }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom setup --target codex --dry-run`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom setup --target codex --dry-run`.");
         }
         else if (!out.file)
             out.file = a;
         else
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom setup --target claude --yes`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom setup --target claude --yes`.");
     }
     return out;
 }
@@ -487,17 +510,21 @@ function parseLibraryCreateFlags(argv) {
         else if (a === "--unlisted")
             out.visibility = "unlisted";
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom library create team-onboarding --name \"Team onboarding\"`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom library create team-onboarding --name \"Team onboarding\"`.");
         }
         else if (!out.slug)
             out.slug = a;
         else
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom library create <slug> --name <name>`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom library create <slug> --name <name>`.");
     }
     return out;
 }
 async function runLibrary(argv) {
     const [subcommand, ...rest] = argv;
+    if (!subcommand || subcommand === "--json") {
+        await libraryList(parseListFlags(argv));
+        return;
+    }
     switch (subcommand ?? "list") {
         case "list": {
             const flags = parseListFlags(rest);
@@ -507,9 +534,9 @@ async function runLibrary(argv) {
         case "create": {
             const flags = parseLibraryCreateFlags(rest);
             if (!flags.slug)
-                throw new FloomError("Missing library slug.", "Try `floom library create team-onboarding --name \"Team onboarding\"`.");
+                throw new FloomError("Missing library slug.", "Try `npx -y @floomhq/floom library create team-onboarding --name \"Team onboarding\"`.");
             if (!flags.name)
-                throw new FloomError("Missing --name.", "Try `floom library create team-onboarding --name \"Team onboarding\"`.");
+                throw new FloomError("Missing --name.", "Try `npx -y @floomhq/floom library create team-onboarding --name \"Team onboarding\"`.");
             await libraryCreate({
                 slug: flags.slug,
                 name: flags.name,
@@ -522,10 +549,10 @@ async function runLibrary(argv) {
             const flags = parseFolderTagFlags(rest);
             const [librarySlug, skillSlug] = flags.rest;
             if (!librarySlug || !skillSlug) {
-                throw new FloomError("Missing library or skill slug.", "Try `floom library add team-onboarding support-tone --folder support`.");
+                throw new FloomError("Missing library or skill slug.", "Try `npx -y @floomhq/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`.");
+                throw new FloomError(`Unexpected argument: ${flags.rest[2]}`, "Try `npx -y @floomhq/floom library add team-onboarding support-tone --folder support`.");
             }
             await libraryAddSkill({
                 librarySlug,
@@ -539,10 +566,10 @@ async function runLibrary(argv) {
         case "rm": {
             const [librarySlug, skillSlug] = rest;
             if (!librarySlug || !skillSlug) {
-                throw new FloomError("Missing library or skill slug.", "Try `floom library remove team-onboarding support-tone`.");
+                throw new FloomError("Missing library or skill slug.", "Try `npx -y @floomhq/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`.");
+                throw new FloomError(`Unexpected argument: ${rest[2]}`, "Try `npx -y @floomhq/floom library remove team-onboarding support-tone`.");
             }
             await libraryRemoveSkill(librarySlug, skillSlug);
             return;
@@ -550,9 +577,9 @@ async function runLibrary(argv) {
         case "subscribe": {
             const slug = rest[0];
             if (!slug)
-                throw new FloomError("Missing library slug.", "Try `floom library subscribe superpowers`.");
+                throw new FloomError("Missing library slug.", "Try `npx -y @floomhq/floom library subscribe superpowers`.");
             if (rest.length > 1) {
-                throw new FloomError(`Unexpected argument: ${rest[1]}`, "Try `floom library subscribe superpowers`.");
+                throw new FloomError(`Unexpected argument: ${rest[1]}`, "Try `npx -y @floomhq/floom library subscribe superpowers`.");
             }
             await librarySubscribe(slug);
             return;
@@ -560,9 +587,9 @@ async function runLibrary(argv) {
         case "unsubscribe": {
             const slug = rest[0];
             if (!slug)
-                throw new FloomError("Missing library slug.", "Try `floom library unsubscribe superpowers`.");
+                throw new FloomError("Missing library slug.", "Try `npx -y @floomhq/floom library unsubscribe superpowers`.");
             if (rest.length > 1) {
-                throw new FloomError(`Unexpected argument: ${rest[1]}`, "Try `floom library unsubscribe superpowers`.");
+                throw new FloomError(`Unexpected argument: ${rest[1]}`, "Try `npx -y @floomhq/floom library unsubscribe superpowers`.");
             }
             await libraryUnsubscribe(slug);
             return;
@@ -585,10 +612,10 @@ function parseWatchFlags(argv) {
             i = nextIndex;
         }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom watch --interval 60`.");
+            throw new FloomError(`Unknown flag: ${a}`, "Try `npx -y @floomhq/floom watch --interval 60`.");
         }
         else {
-            throw new FloomError(`Unexpected argument: ${a}`, "Try `floom watch --interval 60`.");
+            throw new FloomError(`Unexpected argument: ${a}`, "Try `npx -y @floomhq/floom watch --interval 60`.");
         }
     }
     return out;
@@ -662,10 +689,10 @@ async function main() {
             // never block on update-notifier
         }
     }
-    // Subcommand --help: any rest arg = --help/-h/help → show top-level usage.
+    // Subcommand --help: any rest arg = --help/-h/help → show top-level reference.
     // Subcommands are simple enough that one help screen is fine for Version 1.
     if (rest.includes("--help") || rest.includes("-h") || rest.includes("help")) {
-        usage();
+        commandUsage();
         return;
     }
     try {
@@ -679,7 +706,7 @@ async function main() {
                 commandUsage();
                 return;
             case "commands":
-                rejectArgs(rest, "Try `floom commands`.");
+                rejectArgs(rest, "Try `npx -y @floomhq/floom commands`.");
                 commandUsage();
                 return;
             case "--version":
@@ -687,16 +714,16 @@ async function main() {
                 process.stdout.write(`${CLI_VERSION}\n`);
                 return;
             case "login":
-                rejectArgs(rest, "Try `floom login`.");
+                rejectArgs(rest, "Try `npx -y @floomhq/floom login`.");
                 await login();
                 return;
             case "logout":
-                rejectArgs(rest, "Try `floom logout`.");
+                rejectArgs(rest, "Try `npx -y @floomhq/floom logout`.");
                 await deleteConfig();
                 process.stdout.write(`\n${symbols.ok}  Signed out\n\n`);
                 return;
             case "whoami":
-                rejectArgs(rest, "Try `floom whoami`.");
+                rejectArgs(rest, "Try `npx -y @floomhq/floom whoami`.");
                 await whoami();
                 return;
             case "init": {
@@ -708,10 +735,10 @@ async function main() {
                 const flags = parseFlags(rest);
                 const file = flags.rest[0];
                 if (!file) {
-                    throw new FloomError("Missing file argument.", "Try: `floom publish skill.md`");
+                    throw new FloomError("Missing file argument.", "Try: `npx -y @floomhq/floom publish skill.md`");
                 }
                 if (flags.rest.length > 1) {
-                    throw new FloomError(`Unexpected argument: ${flags.rest[1]}`, "Try: `floom publish skill.md`");
+                    throw new FloomError(`Unexpected argument: ${flags.rest[1]}`, "Try: `npx -y @floomhq/floom publish skill.md`");
                 }
                 await publish({
                     file,
@@ -725,7 +752,7 @@ async function main() {
                 return;
             }
             case "scan": {
-                const file = parseSingleFileArg(rest, "Try `floom scan skill.md`.");
+                const file = parseSingleFileArg(rest, "Try `npx -y @floomhq/floom scan skill.md`.");
                 await scanSkill(file);
                 return;
             }
@@ -754,7 +781,7 @@ async function main() {
             case "search": {
                 const flags = parseSearchFlags(rest);
                 if (!flags.query) {
-                    throw new FloomError("Missing search query.", "Try: `floom search \"support tone\"`.");
+                    throw new FloomError("Missing search query.", "Try: `npx -y @floomhq/floom search \"support tone\"`.");
                 }
                 await search({
                     query: flags.query,
@@ -771,6 +798,20 @@ async function main() {
                     ...(flags.target ? { target: flags.target } : {}),
                     setup: flags.setup,
                     force: flags.force,
+                    json: flags.json,
+                });
+                if (flags.setup) {
+                    await setupAgent({ target: flags.target ?? "claude", dryRun: false, yes: true });
+                }
+                return;
+            }
+            case "update": {
+                const flags = parseAddArgs(rest);
+                await install(flags.slug, {
+                    ...(flags.target ? { target: flags.target } : {}),
+                    setup: flags.setup,
+                    force: true,
+                    json: flags.json,
                 });
                 if (flags.setup) {
                     await setupAgent({ target: flags.target ?? "claude", dryRun: false, yes: true });
@@ -778,7 +819,7 @@ async function main() {
                 return;
             }
             case "sync":
-                rejectArgs(rest, "Try `floom sync`.");
+                rejectArgs(rest, "Try `npx -y @floomhq/floom sync`.");
                 await sync();
                 return;
             case "setup":
@@ -789,7 +830,7 @@ async function main() {
             }
             case "agent-prompt":
             case "paste":
-                rejectArgs(rest, "Try `floom agent-prompt`.");
+                rejectArgs(rest, "Try `npx -y @floomhq/floom agent-prompt`.");
                 agentPrompt();
                 return;
             case "watch": {
@@ -811,27 +852,29 @@ async function main() {
                 const flags = parseFolderTagFlags(rest);
                 const slug = flags.rest[0];
                 if (!slug) {
-                    throw new FloomError("Missing skill slug.", "Try `floom move support-tone --folder support/tone`.");
+                    throw new FloomError("Missing skill slug.", "Try `npx -y @floomhq/floom move support-tone --folder support/tone`.");
                 }
                 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`.");
+                    throw new FloomError(`Unexpected argument: ${flags.rest[1]}`, "Try `npx -y @floomhq/floom move support-tone --folder support/tone`.");
                 }
                 await moveSkill({ slug, folder: flags.folder, tags: flags.tags });
                 return;
             }
             case "mcp":
-                rejectArgs(rest, "Try `floom mcp`.");
+                rejectArgs(rest, "Try `npx -y @floomhq/floom mcp`.");
                 printMcpSetup();
                 return;
             case "doctor":
-                rejectArgs(rest, "Try `floom doctor`.");
-                await doctor();
+                {
+                    const flags = parseDoctorArgs(rest);
+                    await doctor(flags);
+                }
                 return;
             default:
-                throw new FloomError(`Unknown command: ${cmd}`, "Run `floom --help` to see available commands.");
+                throw new FloomError(`Unknown command: ${cmd}`, "Run `npx -y @floomhq/floom --help` to see available commands.");
         }
     }
     catch (e) {

package/dist/delete.js

@@ -31,10 +31,10 @@ async function confirm(question) {
 export async function deleteSkill(opts) {
     const slug = slugFromInput(opts.slug);
     if (!slug)
-        throw new FloomError("Missing skill slug.", "Try: `floom delete <slug>`");
+        throw new FloomError("Missing skill slug.", "Try: `npx -y @floomhq/floom delete <slug>`");
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     if (!opts.yes) {
         process.stdout.write(`\n${symbols.bullet}  About to delete ${c.bold(slug)}.\n`);
         const ok = await confirm(`Delete ${c.bold(slug)}? Cannot be undone in CLI.`);

package/dist/doctor.js

@@ -32,7 +32,7 @@ async function checkAuth() {
                 name: "Auth",
                 status: "fail",
                 detail: "Token rejected (401).",
-                hint: "Run `floom logout && floom login` to refresh.",
+                hint: "Run `npx -y @floomhq/floom logout && npx -y @floomhq/floom login` to refresh.",
             };
         }
         if (!res.ok) {
@@ -88,7 +88,7 @@ async function checkMcp() {
         return {
             name: "MCP",
             status: "ok",
-            detail: "Optional MCP not registered. `floom add` still writes local skill files.",
+            detail: "Optional MCP not registered. `npx -y @floomhq/floom add` still writes local skill files.",
         };
     }
     return {
@@ -130,7 +130,7 @@ async function checkTargetDir() {
                 name: "Target dir",
                 status: "warn",
                 detail: `${dir} does not exist yet.`,
-                hint: "It will be created on first `floom add`.",
+                hint: "It will be created on first `npx -y @floomhq/floom add`.",
             };
         }
         throw err;
@@ -146,7 +146,7 @@ async function checkLastSync() {
                 name: "Last sync",
                 status: "warn",
                 detail: "No synced skills found yet.",
-                hint: "Run `floom add <link>` to install your first skill.",
+                hint: "Run `npx -y @floomhq/floom add <link>` to install your first skill.",
             };
         }
         // Find most recently modified entry
@@ -239,8 +239,7 @@ async function checkVersion() {
         };
     }
 }
-export async function doctor() {
-    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(${formatVersionLabel(CLI_VERSION)})`)}\n\n`);
+export async function doctor(opts = {}) {
     const checks = await Promise.all([
         checkAuth(),
         checkMcp(),
@@ -248,6 +247,22 @@ export async function doctor() {
         checkLastSync(),
         checkVersion(),
     ]);
+    const anyFail = checks.some((c) => c.status === "fail");
+    const anyWarn = checks.some((c) => c.status === "warn");
+    const status = anyFail ? "fail" : anyWarn ? "warn" : "ok";
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({
+            ok: !anyFail,
+            status,
+            version: CLI_VERSION,
+            config_path: CONFIG_PATH,
+            checks,
+        }, null, 2)}\n`);
+        if (anyFail)
+            process.exit(1);
+        return;
+    }
+    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(${formatVersionLabel(CLI_VERSION)})`)}\n\n`);
     // Compute column widths for clean table output.
     const nameW = Math.max(...checks.map((c) => c.name.length), 6);
     for (const check of checks) {
@@ -257,8 +272,6 @@ export async function doctor() {
             process.stdout.write(`     ${c.dim("→ " + check.hint)}\n`);
         }
     }
-    const anyFail = checks.some((c) => c.status === "fail");
-    const anyWarn = checks.some((c) => c.status === "warn");
     process.stdout.write("\n");
     if (anyFail) {
         process.stdout.write(`  ${c.red("✗ Some checks failed.")} See hints above.\n\n`);

package/dist/errors.js

@@ -14,7 +14,7 @@ export class FloomError extends Error {
 }
 export function friendlyHttp(status, action) {
     if (status === 401) {
-        return new FloomError("Your token expired.", "Run `floom login` to refresh.");
+        return new FloomError("Your token expired.", "Run `npx -y @floomhq/floom login` to refresh.");
     }
     if (status === 403) {
         return new FloomError(`You don't have permission to ${action}.`);
@@ -23,7 +23,7 @@ export function friendlyHttp(status, action) {
         if (/fetch|inspect|add|install|show|get|search|list|info/i.test(action)) {
             return new FloomError("Skill not found.", "Check the link or slug, then try again.");
         }
-        return new FloomError("Skill not found.", "Run `floom publish` without `--update` to create a new one.");
+        return new FloomError("Skill not found.", "Publish as a new skill for now. Publisher-side version updates are planned for a later release.");
     }
     if (status === 413) {
         return new FloomError("That file is too large to publish.");

package/dist/info.js

@@ -19,7 +19,7 @@ function slugFromInput(input) {
 export async function info(opts) {
     const slug = slugFromInput(opts.slug);
     if (!slug)
-        throw new FloomError("Missing skill slug.", "Try: `floom info <slug>`");
+        throw new FloomError("Missing skill slug.", "Try: `npx -y @floomhq/floom info <slug>`");
     if (!SLUG_RE.test(slug)) {
         throw new FloomError(`Invalid skill slug: ${opts.slug}`, "Use a Floom skill slug or URL.");
     }
@@ -28,7 +28,7 @@ export async function info(opts) {
     const spinner = opts.json ? null : ora({ text: c.dim(`Loading ${slug}...`), color: "yellow" }).start();
     let detail;
     try {
-        detail = await getJson(`${apiUrl}/api/v1/skills/${encodeURIComponent(slug)}`, "load skill metadata", cfg?.accessToken);
+        detail = await getJson(`${apiUrl}/api/v1/skills/${encodeURIComponent(slug)}`, "info skill metadata", cfg?.accessToken);
     }
     finally {
         spinner?.stop();

package/dist/install.js

@@ -58,7 +58,7 @@ async function localHash(path) {
         if (code === "ENOENT")
             return null;
         if (code === "ELOOP")
-            throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `floom add` again.");
+            throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `npx -y @floomhq/floom add` again.");
         if (code === "ENOTDIR" || code === "EISDIR") {
             throw new FloomError("Local path is blocked by an existing file or directory.");
         }
@@ -144,7 +144,7 @@ async function ensureSafeParentDirectory(root, target) {
 async function assertSafeDirectory(path) {
     const stat = await lstat(path);
     if (stat.isSymbolicLink()) {
-        throw new FloomError("Local path contains a symbolic link.", "Move or delete the local path, then run `floom add` again.");
+        throw new FloomError("Local path contains a symbolic link.", "Move or delete the local path, then run `npx -y @floomhq/floom add` again.");
     }
     if (!stat.isDirectory()) {
         throw new FloomError("Local path is blocked by an existing file or directory.");
@@ -159,7 +159,7 @@ export async function install(slugInput, opts = {}) {
     }
     const cfg = await readConfig();
     const apiUrl = resolveApiUrl(cfg);
-    const spinner = ora({ text: c.dim(`Adding ${slug}...`), color: "yellow" }).start();
+    const spinner = opts.json ? null : ora({ text: c.dim(`Adding ${slug}...`), color: "yellow" }).start();
     let detail;
     try {
         detail = await getJson(`${apiUrl}/api/v1/skills/${encodeURIComponent(slug)}`, "fetch skill", cfg?.accessToken);
@@ -168,7 +168,7 @@ export async function install(slugInput, opts = {}) {
         }
     }
     catch (err) {
-        spinner.stop();
+        spinner?.stop();
         throw err;
     }
     try {
@@ -194,7 +194,7 @@ export async function install(slugInput, opts = {}) {
         catch (err) {
             const code = err.code;
             if (code === "ELOOP")
-                throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `floom add` again.");
+                throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `npx -y @floomhq/floom add` again.");
             throw err;
         }
         action = "updated";
@@ -212,16 +212,28 @@ export async function install(slugInput, opts = {}) {
                 throw new FloomError("Local skill already exists with different content.", "Run `npx -y @floomhq/floom add <link> --force` to replace it, or move the local file first.");
             }
             if (code === "ELOOP") {
-                throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `floom add` again.");
+                throw new FloomError("Local path is a symbolic link.", "Move or delete the local path, then run `npx -y @floomhq/floom add` again.");
             }
             if (code === "ENOENT") {
-                throw new FloomError("Local path changed during install.", "Run `floom add` again.");
+                throw new FloomError("Local path changed during install.", "Run `npx -y @floomhq/floom add` again.");
             }
             throw err;
         }
         action = "installed";
     }
-    spinner.stop();
+    const result = {
+        slug,
+        title: detail.title,
+        action,
+        target: targetAgent,
+        path: target,
+        content_hash: remoteHash,
+    };
+    spinner?.stop();
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
     process.stdout.write(`\n${symbols.ok}  [floom] ${action} ${c.bold(slug)}\n`);
     process.stdout.write(`   ${c.dim(target)}\n\n`);
     process.stdout.write(`   ${c.bold("Next")}\n`);

package/dist/library.js

@@ -35,7 +35,7 @@ export async function libraryList(opts = {}) {
 export async function libraryCreate(opts) {
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     const apiUrl = resolveApiUrl(cfg);
     const result = await postJson(`${apiUrl}/api/v1/libraries`, "create library", cfg.accessToken, {
         slug: opts.slug,
@@ -45,12 +45,12 @@ export async function libraryCreate(opts) {
     });
     process.stdout.write(`\n${symbols.ok}  Library created: ${c.cyan(result.slug)}\n`);
     process.stdout.write(`   ${c.dim("API:")}  ${apiUrl}/api/v1/libraries/${result.slug}\n`);
-    process.stdout.write(`   ${c.dim("Sync:")} floom library subscribe ${result.slug}\n\n`);
+    process.stdout.write(`   ${c.dim("Sync:")} npx -y @floomhq/floom library subscribe ${result.slug}\n\n`);
 }
 export async function libraryAddSkill(opts) {
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     const apiUrl = resolveApiUrl(cfg);
     await postJson(`${apiUrl}/api/v1/libraries/${encodeURIComponent(opts.librarySlug)}/skills`, "add skill to library", cfg.accessToken, {
         skill_slug: opts.skillSlug,
@@ -66,7 +66,7 @@ export async function libraryAddSkill(opts) {
 export async function libraryRemoveSkill(librarySlug, skillSlug) {
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     const apiUrl = resolveApiUrl(cfg);
     await deleteRequest(`${apiUrl}/api/v1/libraries/${encodeURIComponent(librarySlug)}/skills/${encodeURIComponent(skillSlug)}`, "remove skill from library", cfg.accessToken);
     process.stdout.write(`\n${symbols.ok}  Removed ${c.cyan(skillSlug)} from ${c.cyan(librarySlug)}\n\n`);
@@ -74,7 +74,7 @@ export async function libraryRemoveSkill(librarySlug, skillSlug) {
 export async function librarySubscribe(slug) {
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     const apiUrl = resolveApiUrl(cfg);
     await postJson(`${apiUrl}/api/v1/me/subscriptions`, "subscribe to library", cfg.accessToken, { library_slug: slug });
     process.stdout.write(`\n${symbols.ok}  Subscribed to ${c.cyan(slug)}\n`);
@@ -83,7 +83,7 @@ export async function librarySubscribe(slug) {
 export async function libraryUnsubscribe(slug) {
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     const apiUrl = resolveApiUrl(cfg);
     await deleteRequest(`${apiUrl}/api/v1/me/subscriptions/${encodeURIComponent(slug)}`, "unsubscribe from library", cfg.accessToken);
     process.stdout.write(`\n${symbols.ok}  Unsubscribed from ${c.cyan(slug)}\n\n`);
@@ -91,7 +91,7 @@ export async function libraryUnsubscribe(slug) {
 export async function moveSkill(opts) {
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     const apiUrl = resolveApiUrl(cfg);
     await putJson(`${apiUrl}/api/v1/me/skills/${encodeURIComponent(opts.slug)}/override`, "set skill override", cfg.accessToken, { folder: opts.folder, tags: opts.tags });
     const folderText = opts.folder ?? c.dim("(root)");

package/dist/list.js

@@ -36,7 +36,7 @@ function formatRelative(iso) {
 export async function list(opts) {
     const cfg = await readConfig();
     if (!cfg) {
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     }
     const apiUrl = resolveApiUrl(cfg);
     const spinner = opts.json ? null : ora({ text: c.dim("Loading skills..."), color: "yellow" }).start();
@@ -54,7 +54,7 @@ export async function list(opts) {
     }
     process.stdout.write(`\n${symbols.dot}  ${c.bold("Published")} ${c.dim(`(${published.length})`)}\n\n`);
     if (published.length === 0) {
-        process.stdout.write(`   ${c.dim("Nothing published yet. Try `floom publish skill.md`.")}\n`);
+        process.stdout.write(`   ${c.dim("Nothing published yet. Try `npx -y @floomhq/floom publish skill.md`.")}\n`);
     }
     else {
         for (const s of published)

package/dist/login.js

@@ -21,7 +21,7 @@ export async function login() {
     catch (err) {
         spinner.stop();
         if (err instanceof Error && /timed out/i.test(err.message)) {
-            throw new FloomError("No worries — try `floom login` again when ready.");
+            throw new FloomError("No worries — try `npx -y @floomhq/floom login` again when ready.");
         }
         throw err;
     }

package/dist/mcp.js

@@ -2,8 +2,8 @@ import { c } from "./ui.js";
 export function printMcpSetup() {
     const snippet = `## Floom
 - Use Floom skills from the local Floom skills folder when they match the task.
-- To install a shared skill, run \`floom add <slug-or-url> --target claude\` or \`floom add <slug-or-url> --target codex\`.
-- To find reusable behavior, run \`floom search <query>\`.
+- To install a shared skill, run \`npx -y @floomhq/floom add <slug-or-url> --target claude\` or \`npx -y @floomhq/floom add <slug-or-url> --target codex\`.
+- To find reusable behavior, run \`npx -y @floomhq/floom search <query>\`.
 - MCP sync is optional preview behavior; use it only while the Floom MCP server is configured and running.`;
     process.stdout.write(`\n${c.bold("Floom MCP setup")}\n\n`);
     process.stdout.write(`${c.dim("Pick your tool:")}\n\n`);

package/dist/publish.js

@@ -140,7 +140,7 @@ export async function publish(opts) {
     const version = opts.version ?? parseVersion(meta.version, "frontmatter version") ?? null;
     const cfg = await readConfig();
     if (!cfg) {
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     }
     // Later version: detect already-published when --update is missing.
     // The current API does not return a duplicate-skill code, so we leave

package/dist/secrets.js

@@ -5,15 +5,29 @@ const SECRET_PATTERNS = [
     { label: "Google API key", regex: /\bAIza[0-9A-Za-z_-]{25,}\b/g },
     { label: "GitHub token", regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{30,}\b/g },
     { label: "GitHub token", regex: /\bgithub_pat_[A-Za-z0-9_]{40,}\b/g },
+    { label: "npm token", regex: /\bnpm_[A-Za-z0-9]{30,}\b/g },
     { label: "Supabase access token", regex: /\bsbp_[A-Za-z0-9]{30,}\b/g },
     { label: "Stripe secret key", regex: /\bsk_(?:live|test)_[A-Za-z0-9]{20,}\b/g },
     { label: "Slack token", regex: /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/g },
     { label: "AWS access key", regex: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g },
+    { label: "Database URL with password", regex: /\b(?:postgres|postgresql|mysql|mongodb(?:\+srv)?|redis):\/\/[^:\s/@]+:[^@\s]{8,}@[^\s]+/gi },
     { label: "Private key", regex: /-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----/g },
 ];
 const GENERIC_ASSIGNMENT_RE = /\b(?:api[_-]?key|secret|access[_-]?token|auth[_-]?token|bearer[_-]?token)\b\s*[:=]\s*["']?([A-Za-z0-9_./+=-]{24,})["']?/gi;
 const PROVIDER_LIKE_ASSIGNMENT_RE = /\b(?:api[_-]?key|secret|access[_-]?token|auth[_-]?token|bearer[_-]?token)\b\s*[:=]\s*["']?((?:sk|pk|rk)-[A-Za-z0-9_-]{8,}|sbp_[A-Za-z0-9]{12,}|xox[baprs]-[A-Za-z0-9-]{12,})["']?/gi;
-const PLACEHOLDER_RE = /(?:^|[_./+=-])(?:your|example|placeholder|replace|changeme|todo|xxx|test|demo|dummy|fake|redacted)(?:$|[_./+=-])/i;
+const PLACEHOLDER_RE = /(?:^|[_./+=-])(?:your|example|sample|mock|placeholder|replace|changeme|todo|xxx|demo|dummy|fake|redacted)(?:$|[_./+=-])/i;
+const PLACEHOLDER_PHRASE_WORDS = new Set([
+    "and",
+    "fake",
+    "is",
+    "key",
+    "long",
+    "looks",
+    "real",
+    "secret",
+    "that",
+    "very",
+]);
 const PROMPT_INJECTION_PATTERNS = [
     { label: "Prompt injection instruction", regex: /\bignore (?:all )?(?:previous|prior|above|earlier) instructions\b/gi },
     { label: "Prompt injection instruction", regex: /\bdisregard (?:all )?(?:previous|prior|above|earlier) instructions\b/gi },
@@ -46,6 +60,12 @@ function pushFinding(findings, seen, label, line, value) {
     seen.add(key);
     findings.push({ label, line, preview: redact(value) });
 }
+function isPlaceholderValue(value) {
+    if (PLACEHOLDER_RE.test(value))
+        return true;
+    const words = value.toLowerCase().split(/[^a-z]+/).filter(Boolean);
+    return words.length >= 6 && words.every((word) => PLACEHOLDER_PHRASE_WORDS.has(word));
+}
 export function detectSecrets(input) {
     const findings = [];
     const seen = new Set();
@@ -59,14 +79,14 @@ export function detectSecrets(input) {
     GENERIC_ASSIGNMENT_RE.lastIndex = 0;
     for (const match of input.matchAll(GENERIC_ASSIGNMENT_RE)) {
         const value = match[1] ?? "";
-        if (!value || PLACEHOLDER_RE.test(value))
+        if (!value || isPlaceholderValue(value))
             continue;
         pushFinding(findings, seen, "Possible secret assignment", lineNumberAt(input, match.index ?? 0), value);
     }
     PROVIDER_LIKE_ASSIGNMENT_RE.lastIndex = 0;
     for (const match of input.matchAll(PROVIDER_LIKE_ASSIGNMENT_RE)) {
         const value = match[1] ?? "";
-        if (!value)
+        if (!value || isPlaceholderValue(value))
             continue;
         pushFinding(findings, seen, "Provider-like secret assignment", lineNumberAt(input, match.index ?? 0), value);
     }

package/dist/setup.js

@@ -13,16 +13,16 @@ const TARGETS = {
 };
 function floomAgentInstructions(target) {
     const addCommand = target === "codex"
-        ? "floom add <slug-or-url> --target codex"
-        : "floom add <slug-or-url> --target claude";
+        ? "npx -y @floomhq/floom add <slug-or-url> --target codex"
+        : "npx -y @floomhq/floom add <slug-or-url> --target claude";
     return `${START_MARKER}
 ## Floom
 
 - Before recreating agent behavior from scratch, check Floom for reusable skills.
-- Search or inspect skills with \`floom search <query>\`, \`floom info <slug-or-url>\`, and \`floom list\`.
+- Search or inspect skills with \`npx -y @floomhq/floom search <query>\`, \`npx -y @floomhq/floom info <slug-or-url>\`, and \`npx -y @floomhq/floom list\`.
 - Add shared skills with \`${addCommand}\`; public and unlisted links do not require a Floom account.
 - Use installed Markdown skills from the local skills folder when they match the task.
-- \`floom sync\`, \`floom watch\`, and \`@floomhq/floom-mcp-sync\` are preview paths for saved, published, and subscribed library skills; review conflicts before relying on synced output.
+- \`npx -y @floomhq/floom sync\`, \`npx -y @floomhq/floom watch\`, and \`@floomhq/floom-mcp-sync\` are preview paths for saved, published, and subscribed library skills; review conflicts before relying on synced output.
 ${END_MARKER}`;
 }
 async function fileExists(path) {
@@ -96,7 +96,7 @@ async function detectTarget(opts) {
         return { agent: "claude", label: TARGETS.claude.label, path: claude };
     if (codex)
         return { agent: "codex", label: TARGETS.codex.label, path: codex };
-    throw new FloomError("No agent instruction file found.", "Run `floom setup --target claude --yes` or `floom setup --target codex --yes` from the repo root.");
+    throw new FloomError("No agent instruction file found.", "Run `npx -y @floomhq/floom setup --target claude --yes` or `npx -y @floomhq/floom setup --target codex --yes` from the repo root.");
 }
 function renderPreview(target, existing) {
     const action = existing === null ? "create" : "append";
@@ -108,7 +108,7 @@ function renderPreview(target, existing) {
         "",
         floomAgentInstructions(target.agent),
         "",
-        `${c.dim("MCP setup guidance:")} run ${c.cyan("floom mcp")} to print local agent commands.`,
+        `${c.dim("MCP setup guidance:")} run ${c.cyan("npx -y @floomhq/floom mcp")} to print local agent commands.`,
         "",
     ].join("\n");
 }
@@ -153,7 +153,7 @@ export async function setupAgent(opts) {
     if (existing === null) {
         await writeFile(target.path, next, { encoding: "utf8", flag: "wx" }).catch((err) => {
             if (err instanceof Error && "code" in err && err.code === "EEXIST") {
-                throw new FloomError("Instruction file appeared while setup was running.", "Re-run `floom setup` so Floom can inspect the current file before writing.");
+                throw new FloomError("Instruction file appeared while setup was running.", "Re-run `npx -y @floomhq/floom setup` so Floom can inspect the current file before writing.");
             }
             throw err;
         });
@@ -162,5 +162,5 @@ export async function setupAgent(opts) {
         await writeFile(target.path, next, "utf8");
     }
     process.stdout.write(`\n${symbols.ok}  Added Floom instructions to ${c.bold(target.path)}\n`);
-    process.stdout.write(`   ${c.dim("MCP setup guidance:")} ${c.cyan("floom mcp")}\n\n`);
+    process.stdout.write(`   ${c.dim("MCP setup guidance:")} ${c.cyan("npx -y @floomhq/floom mcp")}\n\n`);
 }

package/dist/share.js

@@ -19,11 +19,11 @@ async function readJson(res) {
 export async function share(opts) {
     const cfg = await readConfig();
     if (!cfg) {
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     }
     const slug = slugFromInput(opts.slug);
     if (!slug) {
-        throw new FloomError("Missing skill slug.", "Try: `floom share <slug> --list`");
+        throw new FloomError("Missing skill slug.", "Try: `npx -y @floomhq/floom share <slug> --list`");
     }
     const apiUrl = resolveApiUrl(cfg);
     const endpoint = `${apiUrl}/api/skills/${encodeURIComponent(slug)}/share`;

package/dist/sync.js

@@ -205,7 +205,7 @@ function conflictError(message, code) {
 export async function sync(opts = {}) {
     const cfg = await readConfig();
     if (!cfg)
-        throw new FloomError("Not signed in.", "Run `floom login` first.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
     await ensureSyncManifestDir();
     const apiUrl = resolveApiUrl(cfg);
     const spinner = opts.spinner === false ? null : ora({ text: c.dim("Syncing skills..."), color: "yellow" }).start();
@@ -394,7 +394,7 @@ export async function sync(opts = {}) {
             process.stderr.write(`${symbols.bullet}  [floom] skipped local conflict: ${note}\n`);
         }
         if (conflicts > 0) {
-            process.stderr.write(`   ${c.dim("Move or delete the local file, then run `floom sync` again.")}\n`);
+            process.stderr.write(`   ${c.dim("Move or delete the local file, then run `npx -y @floomhq/floom sync` again.")}\n`);
         }
         process.stdout.write(`\n${symbols.ok}  [floom] synced ${synced} skills (${unchanged} unchanged, ${updated} updated${conflictNote})${skippedNote}\n\n`);
     }

package/dist/whoami.js

@@ -6,7 +6,7 @@ import { FloomError, friendlyHttp, friendlyNetwork } from "./errors.js";
 export async function whoami() {
     const cfg = await readConfig();
     if (!cfg) {
-        throw new FloomError("Not signed in.", "Run `floom login` to sign in.");
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` to sign in.");
     }
     const apiUrl = resolveApiUrl(cfg);
     const spinner = ora({ text: c.dim("Checking session..."), color: "yellow" }).start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "Publish AI skills from your terminal. Share with a link.",
   "license": "MIT",
   "type": "module",