@floomhq/floom 1.0.7 → 1.0.9

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/init.js

@@ -4,7 +4,8 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { c, symbols } from "./ui.js";
 import { FloomError } from "./errors.js";
-const TEMPLATE = `---
+const TEMPLATES = {
+    generic: `---
 title:
 description:
 version: 1.0
@@ -26,10 +27,156 @@ version: 1.0
 
 
 # Examples
-`;
-export async function init(filename) {
+`,
+    "brand-voice": `---
+title: Brand voice
+description: Help an agent write in our company voice.
+type: knowledge
+installs_as: memory
+version: 1.0
+---
+
+# Brand Voice
+
+## Use when
+- Writing customer-facing copy
+- Rewriting drafts to match our tone
+- Reviewing messaging before it ships
+
+## Voice rules
+- Sound clear, direct, and useful.
+- Prefer concrete nouns and short sentences.
+- Avoid hype, filler, and generic AI language.
+
+## Words we use
+- Replace this list with approved terms.
+
+## Words we avoid
+- Replace this list with banned or overused terms.
+
+## Examples
+- Before:
+- After:
+`,
+    "pr-review": `---
+title: PR review
+description: Review code changes with risk-first feedback.
+type: workflow
+installs_as: claude_skill
+version: 1.0
+---
+
+# PR Review
+
+## Use when
+- Reviewing a pull request or diff
+- Checking a change before merge
+
+## Review order
+1. Correctness and regressions
+2. Security and data safety
+3. Tests and missing edge cases
+4. Maintainability
+
+## Output
+- Lead with findings.
+- Include file paths and line references.
+- Keep style comments out unless they affect behavior.
+- If no issues are found, say that clearly and name any test gaps.
+`,
+    sales: `---
+title: Sales research
+description: Prepare concise account research and outreach context.
+type: workflow
+installs_as: memory
+version: 1.0
+---
+
+# Sales Research
+
+## Use when
+- Preparing for a prospect call
+- Writing a relevant outbound message
+- Summarizing account context for the team
+
+## Gather
+- Company
+- Buyer persona
+- Recent trigger
+- Likely pain
+- Existing tools or workflow
+
+## Output
+- 5 bullet account summary
+- 3 likely pain points
+- 2 tailored opener angles
+- 1 clear next action
+`,
+    support: `---
+title: Support tone
+description: Answer support tickets with a clear and calm company voice.
+type: instruction
+installs_as: memory
+version: 1.0
+---
+
+# Support Tone
+
+## Use when
+- Replying to customer support messages
+- Summarizing customer issues
+- Drafting escalation notes
+
+## Rules
+- Acknowledge the issue in plain language.
+- Give the next concrete step.
+- Do not over-apologize.
+- Do not invent product behavior.
+- Escalate when data, billing, or account access is involved.
+
+## Reply shape
+1. Short acknowledgement
+2. Direct answer or next step
+3. What happens next
+`,
+    onboarding: `---
+title: Team onboarding
+description: Help a new teammate understand how this team works.
+type: knowledge
+installs_as: memory
+version: 1.0
+---
+
+# Team Onboarding
+
+## Use when
+- A new teammate asks how work gets done
+- An agent needs company or team context
+- Creating first-week task plans
+
+## Team context
+- Mission:
+- Customers:
+- Current priorities:
+- Tools:
+
+## How we work
+- Decision rules:
+- Review process:
+- Communication norms:
+- Definition of done:
+
+## First-week checklist
+- Read:
+- Set up:
+- Ask:
+- Ship:
+`,
+};
+export async function init(filename, template = "generic") {
     const target = filename ?? "skill.md";
     const filePath = resolve(process.cwd(), target);
+    const body = TEMPLATES[template];
     const exists = await fileExists(filePath);
     if (exists) {
         if (!process.stdin.isTTY) {
@@ -44,7 +191,7 @@ export async function init(filename) {
         }
     }
     try {
-        await writeFile(filePath, TEMPLATE, "utf8");
+        await writeFile(filePath, body, "utf8");
     }
     catch (err) {
         const code = err.code;
@@ -57,10 +204,11 @@ export async function init(filename) {
         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(`Template: ${template}`)}\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`);
+    process.stdout.write(`   ${c.dim("2.")} Check it: ${c.cyan(`npx -y @floomhq/floom scan ${shellQuote(target)}`)}\n`);
+    process.stdout.write(`   ${c.dim("3.")} Publish:  ${c.cyan(`npx -y @floomhq/floom publish ${shellQuote(target)} --public`)}\n\n`);
 }
 function shellQuote(value) {
     if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))

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
@@ -192,10 +192,15 @@ export async function publish(opts) {
     spinner.stop();
     const versionTag = version ? c.dim(` (${formatVersionLabel(version)})`) : "";
     const titleLabel = data.title ? `"${data.title}"` : opts.file;
+    const invitedEmails = opts.sharedWithEmails ?? [];
     process.stdout.write(`\n${symbols.ok}  Published ${c.bold(titleLabel)}${versionTag}\n\n`);
+    process.stdout.write(`   ${c.bold("Send this to someone:")}\n`);
     process.stdout.write(`   ${c.cyan(humanUrl)}\n\n`);
-    if (data.visibility === "shared" && data.shared_with_emails?.length) {
-        process.stdout.write(`   ${c.dim(`Shared with ${data.shared_with_emails.join(", ")}`)}\n\n`);
+    process.stdout.write(`   ${c.bold("They run:")}\n`);
+    process.stdout.write(`   ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --setup`)}\n\n`);
+    if (invitedEmails.length) {
+        process.stdout.write(`   ${c.bold("Email invite:")}\n`);
+        process.stdout.write(`   ${c.dim(invitedEmails.join(", "))}\n\n`);
     }
     let copied = false;
     try {
@@ -206,14 +211,11 @@ export async function publish(opts) {
         copied = false;
     }
     if (copied) {
-        process.stdout.write(`   ${c.dim("Copied to clipboard. Share it anywhere.")}\n\n`);
+        process.stdout.write(`   ${c.dim("Copied link to clipboard.")}\n\n`);
     }
     else {
         process.stdout.write(`   ${c.dim("Share it anywhere.")}\n\n`);
     }
-    process.stdout.write(`   ${c.bold("Next")}\n`);
-    process.stdout.write(`   ${c.dim("1.")} Test locally: ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --setup`)}\n`);
-    process.stdout.write(`   ${c.dim("2.")} Send the link.\n`);
-    process.stdout.write(`   ${c.dim("3.")} Receiver runs ${c.cyan(`npx -y @floomhq/floom add ${humanUrl} --setup`)}\n`);
-    process.stdout.write(`   ${c.dim("4.")} Agent reads the installed Markdown from the local skills folder.\n\n`);
+    process.stdout.write(`   ${c.bold("Agent prompt:")}\n`);
+    process.stdout.write(`   ${c.cyan("npx -y @floomhq/floom agent-prompt")}\n\n`);
 }

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`);
 }