@floomhq/floom 1.0.7 → 1.0.9

package/README.md

@@ -4,11 +4,13 @@ Publish AI skills from your terminal. Share them with a link. Add other people's
 
 ```bash
 npx -y @floomhq/floom init my-skill.md
+npx -y @floomhq/floom init brand-voice.md --template brand-voice
 npx -y @floomhq/floom login
-npx -y @floomhq/floom publish my-skill.md
+npx -y @floomhq/floom publish my-skill.md --share teammate@example.com
 npx -y @floomhq/floom share my-skill --add teammate@example.com
 npx -y @floomhq/floom search review
 npx -y @floomhq/floom add awesome-skill --setup
+npx -y @floomhq/floom agent-prompt
 npx -y @floomhq/floom setup --target claude --dry-run
 npx -y @floomhq/floom list
 npx -y @floomhq/floom library list
@@ -21,31 +23,33 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 ## Commands
 
 - `npx -y @floomhq/floom login` — sign in with Google. New accounts are created on first login. Token stored at `~/.floom/config.json`.
-- `floom init [file.md]` — create a starter skill file.
-- `npx -y @floomhq/floom publish <file.md>` — upload a Markdown file. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--skill-version <label>`.
-- `floom share <slug>` — email-share one of your skills. Optional `--add <email>`, `--remove <email>`, and `--list`.
-- `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.
-- `floom info <url-or-slug>` — show skill metadata. Optional `--json`.
-- `floom search <query>` — search public skills and starter libraries. Optional `--library <slug>`, `--type knowledge|instruction|workflow|skill`, and `--json`.
-- `floom setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`.
-- `floom connect` — alias for `floom setup`.
-- `floom mcp` — print MCP setup commands for supported agent CLIs.
-- `floom sync` — preview: pull your published, saved, and subscribed library skills into `~/.claude/skills/`.
-- `floom watch` — preview: run `floom sync` repeatedly. Optional `--interval <seconds>`; minimum `10`.
-- `floom library list` — list public starter libraries. Optional `--json`.
-- `floom library create <slug> --name <name>` — create a personal or starter library. Optional `--public` / `--private` / `--unlisted`.
-- `floom library add <library> <skill> [--folder <path>] [--tags a,b]` — add a skill to a library.
-- `floom library subscribe <slug>` — subscribe to a public or unlisted library so sync can pull it locally.
-- `floom move <slug> --folder <path>` — set your local folder override for a saved or library skill.
-- `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 init [file.md]` — create a starter skill file. Optional `--template generic|brand-voice|pr-review|sales|support|onboarding`.
+- `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, `--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`, `--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/`.
+- `npx -y @floomhq/floom watch` — preview: run sync repeatedly. Optional `--interval <seconds>`; minimum `10`.
+- `npx -y @floomhq/floom library list` — list public starter libraries. Optional `--json`.
+- `npx -y @floomhq/floom library create <slug> --name <name>` — create a personal or starter library. Optional `--public` / `--private` / `--unlisted`.
+- `npx -y @floomhq/floom library add <library> <skill> [--folder <path>] [--tags a,b]` — add a skill to a library.
+- `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. Optional `--json`.
+- `npx -y @floomhq/floom whoami` — show the signed-in account.
+- `npx -y @floomhq/floom logout` — delete local credentials.
 
 ## Skill format
 
-Optional YAML-ish frontmatter (`title`, `description`, `version`), then freeform Markdown.
+Optional YAML frontmatter (`title`, `description`, `version`, `type`, `installs_as`), then freeform Markdown.
 
 ```markdown
 ---
@@ -62,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,23 +63,27 @@ 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
 
    ${c.dim("Publishing")}
      ${c.cyan("init")} ${c.dim("[path]")}        Create a skill scaffold
+                       ${c.dim("Flags: --template generic|brand-voice|pr-review|sales|support|onboarding")}
      ${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("       --skill-version <label>, --share <email>")}
+                       ${c.dim("       --share emails the normal link; no account is needed to add it")}
      ${c.cyan("share")} ${c.dim("<slug>")}       Email-share one of your skills
                        ${c.dim("Flags: --add <email>, --remove <email>, --list")}
 
@@ -94,8 +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
@@ -108,6 +116,7 @@ function commandUsage() {
  ${c.bold("Examples")}
    ${c.cyan("npx -y @floomhq/floom add")} ${c.dim("https://floom.dev/s/ffas93ud --setup")}
    ${c.cyan("npx -y @floomhq/floom publish")} ${c.dim("support-tone.md --type instruction --public")}
+   ${c.cyan("npx -y @floomhq/floom publish")} ${c.dim("support-tone.md --share teammate@example.com")}
    ${c.cyan("npx -y @floomhq/floom setup")} ${c.dim("--target claude --yes")}
 
  ${c.bold("Help")}
@@ -120,6 +129,7 @@ function commandUsage() {
     process.stdout.write(out);
 }
 const ASSET_TYPES = new Set(["knowledge", "instruction", "workflow", "skill"]);
+const INIT_TEMPLATES = new Set(["generic", "brand-voice", "pr-review", "sales", "support", "onboarding"]);
 const INSTALL_TARGETS = new Set([
     "claude_skill",
     "memory",
@@ -140,7 +150,7 @@ function readFlagValue(argv, index, flag) {
     return { value, nextIndex: index + 1 };
 }
 function parseFlags(argv) {
-    const out = { visibility: "unlisted", update: false, rest: [] };
+    const out = { visibility: "unlisted", update: false, shareEmails: [], explicitVisibility: false, rest: [] };
     let visibilityFlag = null;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? "";
@@ -151,12 +161,15 @@ function parseFlags(argv) {
             }
             visibilityFlag = nextVisibility;
             out.visibility = nextVisibility;
+            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=")) {
-            throw new FloomError(V1_NOT_AVAILABLE, "`floom publish --share` is planned for a later Floom release.");
+            const { value, nextIndex } = readFlagValue(argv, i, "--share");
+            out.shareEmails.push(...parseEmailList(value, "--share"));
+            i = nextIndex;
         }
         else if (a === "--type" || a.startsWith("--type=")) {
             const { value, nextIndex } = readFlagValue(argv, i, "--type");
@@ -186,13 +199,36 @@ 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);
     }
+    if (out.shareEmails.length > 0) {
+        out.shareEmails = dedupeEmails(out.shareEmails);
+        if (out.shareEmails.length > 200) {
+            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 `npx -y @floomhq/floom share <slug> --add <email>` for email-gated access after publishing.");
+        }
+    }
     return out;
 }
+function parseEmailList(value, source) {
+    const emails = value.split(",").map((email) => email.trim().toLowerCase()).filter(Boolean);
+    if (emails.length === 0)
+        throw new FloomError(`Missing value for ${source}.`, `Try \`${source} teammate@example.com\`.`);
+    for (const email of emails) {
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+            throw new FloomError(`Invalid email for ${source}: ${email}`, "Use an address like teammate@example.com.");
+        }
+    }
+    return emails;
+}
+function dedupeEmails(emails) {
+    return [...new Set(emails)];
+}
 function parseShareFlags(argv) {
     const out = { list: false, add: [], remove: [] };
     for (let i = 0; i < argv.length; i++) {
@@ -211,37 +247,48 @@ 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;
 }
 function parseInitArgs(argv) {
     let file;
-    for (const a of argv) {
+    let template = "generic";
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--template" || a.startsWith("--template=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--template");
+            if (!INIT_TEMPLATES.has(value)) {
+                throw new FloomError(`Invalid --template: ${value}`, "Use one of: generic, brand-voice, pr-review, sales, support, onboarding.");
+            }
+            template = value;
+            i = nextIndex;
+            continue;
+        }
         if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, "Try `floom init skill.md`.");
+            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;
     }
-    return file ? { file } : {};
+    return file ? { file, template } : { template };
 }
 function parseListFlags(argv) {
     const out = { json: false };
@@ -249,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;
@@ -263,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;
 }
@@ -276,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=")) {
@@ -289,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 } : { slug, setup, force };
+    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 out;
 }
 function parseSearchFlags(argv) {
     const out = { json: false };
@@ -327,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);
@@ -342,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;
 }
@@ -380,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;
 }
@@ -444,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);
@@ -464,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,
@@ -479,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,
@@ -496,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;
@@ -507,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;
@@ -517,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;
@@ -542,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;
@@ -566,6 +636,9 @@ function parseSingleFileArg(argv, usageHint) {
         throw new FloomError("Missing file argument.", usageHint);
     return file;
 }
+function agentPrompt() {
+    process.stdout.write("Use my installed Floom skills when they fit the task. Search ~/.claude/skills first.\n");
+}
 function sleep(ms, signal) {
     if (signal.aborted)
         return Promise.resolve();
@@ -616,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 {
@@ -633,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":
@@ -641,31 +714,31 @@ 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": {
                 const flags = parseInitArgs(rest);
-                await init(flags.file);
+                await init(flags.file, flags.template);
                 return;
             }
             case "publish": {
                 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,
@@ -674,11 +747,12 @@ async function main() {
                     ...(flags.assetType ? { assetType: flags.assetType } : {}),
                     ...(flags.installsAs ? { installsAs: flags.installsAs } : {}),
                     ...(flags.version ? { version: flags.version } : {}),
+                    ...(flags.shareEmails.length > 0 ? { sharedWithEmails: flags.shareEmails } : {}),
                 });
                 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;
             }
@@ -707,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,
@@ -724,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 });
@@ -731,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":
@@ -740,6 +828,11 @@ async function main() {
                 await setupAgent(flags);
                 return;
             }
+            case "agent-prompt":
+            case "paste":
+                rejectArgs(rest, "Try `npx -y @floomhq/floom agent-prompt`.");
+                agentPrompt();
+                return;
             case "watch": {
                 const flags = parseWatchFlags(rest);
                 await watch(flags.intervalSeconds);
@@ -759,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) {