@floomhq/floom 1.0.18 → 1.0.20

package/dist/cli.js

@@ -71,7 +71,9 @@ function commandUsage() {
    ${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, --json")}
+     ${c.cyan("update")} ${c.dim("<url>")}       Refresh or migrate a local skill
+                       ${c.dim("Flags: --target claude|codex (default: claude), --json")}
      ${c.cyan("search")} ${c.dim("<query>")}     Find public skills and libraries
      ${c.cyan("info")} ${c.dim("<url>")}         Show skill metadata
 
@@ -98,7 +100,7 @@ function commandUsage() {
                        ${c.dim("Alias: connect")}
                        ${c.dim("Flags: --target claude|codex, --yes, --dry-run")}
      ${c.cyan("doctor")}             Troubleshoot auth, API, and local folders
-                       ${c.dim("Flags: --target claude|codex (default: claude)")}
+                       ${c.dim("Flags: --target claude|codex (default: claude), --json")}
 
    ${c.dim("Advanced")}
      ${c.cyan("library")}            Create, browse, and subscribe to libraries
@@ -108,6 +110,10 @@ function commandUsage() {
      ${c.cyan("sync")}               Preview pull of published, saved, and library skills
                        ${c.dim("Flags: --target claude|codex (default: claude)")}
      ${c.cyan("watch")}              Preview polling sync loop
+                       ${c.dim("Flags: --target claude|codex (default: claude), --interval <seconds>")}
+     ${c.cyan("agent-prompt")}       Print the one-line agent instruction
+                       ${c.dim("Alias: paste")}
+                       ${c.dim("Flags: --target claude|codex (default: claude)")}
 
  ${c.bold("Examples")}
    ${c.cyan("npx -y @floomhq/floom add")} ${c.dim("https://floom.dev/s/ffas93ud --setup")}
@@ -123,6 +129,112 @@ function commandUsage() {
 `;
     process.stdout.write(out);
 }
+function subcommandUsage(cmd) {
+    const key = cmd === "install" ? "add" : cmd === "rm" ? "delete" : cmd === "connect" ? "setup" : cmd === "paste" ? "agent-prompt" : cmd;
+    const usageByCommand = {
+        add: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} add`)} ${c.dim("<url-or-slug> [flags]")}
+
+Install a Floom skill into a local agent skills folder.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Install for Claude Code or Codex. Default: claude.
+  ${c.cyan("--setup")}                Add Floom guidance to the matching agent instructions file.
+  ${c.cyan("--force")}                Replace the local copy when remote content differs.
+  ${c.cyan("--json")}                 Print machine-readable install output.
+
+${c.bold("Examples")}
+  ${c.cyan(`${CLI_COMMAND} add https://floom.dev/s/ffas93ud --setup`)}
+  ${c.cyan(`${CLI_COMMAND} add ffas93ud --target codex --json`)}
+`,
+        update: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} update`)} ${c.dim("<url-or-slug> [flags]")}
+
+Refresh or migrate one local skill through the same installer as add.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Update Claude Code or Codex local skills. Default: claude.
+  ${c.cyan("--setup")}                Also refresh agent setup instructions.
+  ${c.cyan("--json")}                 Print machine-readable install output.
+`,
+        doctor: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} doctor`)} ${c.dim("[flags]")}
+
+Diagnose auth, API reachability, PATH collisions, MCP setup, and local skills folders.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Check Claude Code or Codex paths. Default: claude.
+  ${c.cyan("--json")}                 Print structured checks for scripts.
+`,
+        publish: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} publish`)} ${c.dim("<path> [flags]")}
+
+Scan and publish a Markdown skill file or skill folder. Prints a Floom share URL.
+
+${c.bold("Flags")}
+  ${c.cyan("--public")} | ${c.cyan("--private")} | ${c.cyan("--unlisted")}   Set visibility. Default: unlisted.
+  ${c.cyan("--type")} ${c.dim("knowledge|instruction|workflow|skill")}
+  ${c.cyan("--installs-as")} ${c.dim("claude_skill|memory|rule|codex_instruction|opencode_instruction|cursor_rule|other")}
+  ${c.cyan("--skill-version")} ${c.dim("<label>")}
+`,
+        init: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} init`)} ${c.dim("[path] [flags]")}
+
+Create a starter skill folder with SKILL.md.
+
+${c.bold("Flags")}
+  ${c.cyan("--template")} ${c.dim(`generic|${INIT_TEMPLATES.filter((t) => t !== "generic").join("|")}`)}
+`,
+        sync: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} sync`)} ${c.dim("[flags]")}
+
+Preview pull of published, saved, and subscribed library skills.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Sync into Claude Code or Codex skills. Default: claude.
+`,
+        watch: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} watch`)} ${c.dim("[flags]")}
+
+Poll sync on an interval. Preview behavior.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Watch Claude Code or Codex skills. Default: claude.
+  ${c.cyan("--interval")} ${c.dim("<seconds>")}    Poll interval. Minimum: 10.
+`,
+        setup: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} setup`)} ${c.dim("[flags]")}
+
+Add Floom guidance to CLAUDE.md or AGENTS.md.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Configure Claude Code or Codex.
+  ${c.cyan("--file")} ${c.dim("<path>")}           Write a specific instructions file.
+  ${c.cyan("--yes")}                  Write without prompting.
+  ${c.cyan("--dry-run")}              Preview the change only.
+`,
+        search: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} search`)} ${c.dim("<query> [flags]")}
+
+Find public skills and libraries.
+
+${c.bold("Flags")}
+  ${c.cyan("--library")} ${c.dim("<slug>")}        Limit search to one library.
+  ${c.cyan("--type")} ${c.dim("knowledge|instruction|workflow|skill")}
+  ${c.cyan("--json")}                 Print machine-readable results.
+`,
+        info: `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} info`)} ${c.dim("<url-or-slug> [flags]")}
+
+Show public skill metadata.
+
+${c.bold("Flags")}
+  ${c.cyan("--json")}                 Print machine-readable metadata.
+`,
+        "agent-prompt": `${c.bold("Usage:")} ${c.cyan(`${CLI_COMMAND} agent-prompt`)} ${c.dim("[flags]")}
+
+Print the one-line instruction to paste into your agent.
+
+${c.bold("Flags")}
+  ${c.cyan("--target")} ${c.dim("claude|codex")}   Print the right local skills path. Default: claude.
+`,
+    };
+    const body = key ? usageByCommand[key] : undefined;
+    if (!body)
+        return false;
+    process.stdout.write(`${body}\n`);
+    return true;
+}
 const ASSET_TYPES = new Set(["knowledge", "instruction", "workflow", "skill"]);
 const INSTALL_TARGETS = new Set([
     "claude_skill",
@@ -312,6 +424,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=")) {
@@ -328,6 +441,9 @@ function parseAddArgs(argv) {
         else if (a === "--force") {
             force = true;
         }
+        else if (a === "--json") {
+            json = true;
+        }
         else if (a.startsWith("--")) {
             throw new FloomError(`Unknown flag: ${a}`, `Try \`${CLI_COMMAND} add <url-or-slug> --setup\`.`);
         }
@@ -340,7 +456,10 @@ function parseAddArgs(argv) {
     if (!slug) {
         throw new FloomError("Missing skill slug.", `Try: \`${CLI_COMMAND} add <url-or-slug> --setup\``);
     }
-    return target ? { slug, target, setup, force } : { slug, setup, force };
+    if (json && setup) {
+        throw new FloomError("Cannot combine --json with --setup.", "Run the install first, then run `npx -y @floomhq/floom setup --target claude --yes`.");
+    }
+    return target ? { slug, target, setup, force, json } : { slug, setup, force, json };
 }
 function parseSearchFlags(argv) {
     const out = { json: false };
@@ -426,7 +545,7 @@ function parseSetupFlags(argv) {
     return out;
 }
 function parseDoctorFlags(argv) {
-    const out = {};
+    const out = { json: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i] ?? "";
         if (a === "--target" || a.startsWith("--target=")) {
@@ -437,8 +556,11 @@ function parseDoctorFlags(argv) {
             out.target = value;
             i = nextIndex;
         }
+        else if (a === "--json") {
+            out.json = true;
+        }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, `Try \`${CLI_COMMAND} doctor --target codex\`.`);
+            throw new FloomError(`Unknown flag: ${a}`, `Try \`${CLI_COMMAND} doctor --target codex --json\`.`);
         }
         else {
             throw new FloomError(`Unexpected argument: ${a}`, `Try \`${CLI_COMMAND} doctor --target claude\`.`);
@@ -598,11 +720,19 @@ function parseWatchFlags(argv) {
             out.intervalSeconds = interval;
             i = nextIndex;
         }
+        else if (a === "--target" || a.startsWith("--target=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--target");
+            if (value !== "claude" && value !== "codex") {
+                throw new FloomError("Invalid --target.", "Use claude or codex.");
+            }
+            out.target = value;
+            i = nextIndex;
+        }
         else if (a.startsWith("--")) {
-            throw new FloomError(`Unknown flag: ${a}`, `Try \`${CLI_COMMAND} watch --interval 60\`.`);
+            throw new FloomError(`Unknown flag: ${a}`, `Try \`${CLI_COMMAND} watch --target claude --interval 60\`.`);
         }
         else {
-            throw new FloomError(`Unexpected argument: ${a}`, `Try \`${CLI_COMMAND} watch --interval 60\`.`);
+            throw new FloomError(`Unexpected argument: ${a}`, `Try \`${CLI_COMMAND} watch --target claude --interval 60\`.`);
         }
     }
     return out;
@@ -610,6 +740,31 @@ function parseWatchFlags(argv) {
 function notAvailable(feature) {
     throw new FloomError(V1_NOT_AVAILABLE, `${feature} is planned for a later Floom release.`);
 }
+function parseAgentPromptFlags(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--target" || a.startsWith("--target=")) {
+            const { value, nextIndex } = readFlagValue(argv, i, "--target");
+            if (value !== "claude" && value !== "codex") {
+                throw new FloomError("Invalid --target.", "Use `claude` or `codex`.");
+            }
+            out.target = value;
+            i = nextIndex;
+        }
+        else if (a.startsWith("--")) {
+            throw new FloomError(`Unknown flag: ${a}`, `Try \`${CLI_COMMAND} agent-prompt --target codex\`.`);
+        }
+        else {
+            throw new FloomError(`Unexpected argument: ${a}`, `Try \`${CLI_COMMAND} agent-prompt --target claude\`.`);
+        }
+    }
+    return out;
+}
+function printAgentPrompt(target = "claude") {
+    const folder = target === "codex" ? "~/.codex/skills" : "~/.claude/skills";
+    process.stdout.write(`Use my installed Floom skills when they fit the task. Search ${folder} first.\n`);
+}
 function parseSingleFileArg(argv, usageHint) {
     let file;
     for (const a of argv) {
@@ -634,7 +789,7 @@ function sleep(ms, signal) {
         }, { once: true });
     });
 }
-async function watch(intervalSeconds) {
+async function watch(intervalSeconds, target) {
     const cfg = await readConfig();
     if (!cfg) {
         throw new FloomError("Not signed in.", `Run \`${CLI_COMMAND} login\` before \`${CLI_COMMAND} watch\`, or use \`${CLI_COMMAND} add <link>\` without an account.`);
@@ -651,9 +806,9 @@ async function watch(intervalSeconds) {
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
-    process.stdout.write(`${symbols.bullet}  Watching Floom sync every ${intervalSeconds}s. Press Ctrl-C to stop.\n`);
+    process.stdout.write(`${symbols.bullet}  Watching Floom sync for ${target ?? "claude"} every ${intervalSeconds}s. Press Ctrl-C to stop.\n`);
     while (!controller.signal.aborted) {
-        await sync({ spinner: false, quietUnchanged: true });
+        await sync({ spinner: false, quietUnchanged: true, ...(target ? { target } : {}) });
         await sleep(intervalSeconds * 1000, controller.signal);
     }
 }
@@ -673,10 +828,9 @@ async function main() {
             // never block on update-notifier
         }
     }
-    // Subcommand --help: any rest arg = --help/-h/help → show top-level usage.
-    // Subcommands are simple enough that one help screen is fine for Version 1.
     if (rest.includes("--help") || rest.includes("-h") || rest.includes("help")) {
-        usage();
+        if (!subcommandUsage(cmd))
+            commandUsage();
         return;
     }
     try {
@@ -781,6 +935,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 });
@@ -798,7 +966,7 @@ async function main() {
             }
             case "watch": {
                 const flags = parseWatchFlags(rest);
-                await watch(flags.intervalSeconds);
+                await watch(flags.intervalSeconds, flags.target);
                 return;
             }
             case "delete":
@@ -830,6 +998,13 @@ async function main() {
                 rejectArgs(rest, `Try \`${CLI_COMMAND} mcp\`.`);
                 printMcpSetup();
                 return;
+            case "agent-prompt":
+            case "paste":
+                {
+                    const flags = parseAgentPromptFlags(rest);
+                    printAgentPrompt(flags.target);
+                }
+                return;
             case "doctor":
                 await doctor(parseDoctorFlags(rest));
                 return;

package/dist/doctor.js

@@ -335,7 +335,6 @@ async function readExecutableVersion(path) {
 }
 export async function doctor(opts = {}) {
     const target = opts.target ?? "claude";
-    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(${formatVersionLabel(CLI_VERSION)}, target: ${target})`)}\n\n`);
     const checks = await Promise.all([
         checkCliCommand(),
         checkAuth(),
@@ -344,6 +343,22 @@ export async function doctor(opts = {}) {
         checkLastSync(target),
         checkVersion(),
     ]);
+    const anyFail = checks.some((check) => check.status === "fail");
+    const anyWarn = checks.some((check) => check.status === "warn");
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({
+            ok: !anyFail,
+            status: anyFail ? "fail" : anyWarn ? "warn" : "ok",
+            version: CLI_VERSION,
+            target,
+            checks,
+            configPath: CONFIG_PATH,
+        })}\n`);
+        if (anyFail)
+            process.exit(1);
+        return;
+    }
+    process.stdout.write(`\n${c.bold("floom doctor")} ${c.dim(`(${formatVersionLabel(CLI_VERSION)}, target: ${target})`)}\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) {
@@ -353,8 +368,6 @@ export async function doctor(opts = {}) {
             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/install.js

@@ -1,5 +1,5 @@
 import { constants } from "node:fs";
-import { lstat, mkdir, open } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, rmdir, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import ora from "ora";
@@ -66,12 +66,14 @@ async function readLocalFile(path) {
         throw err;
     }
 }
-async function localPackageHash(root, slug, target, files) {
+async function localPackageState(root, slug, target, files) {
     const main = await readLocalFile(target);
     if (main === null) {
         const legacy = await readLocalFile(legacySkillPath(root, slug));
-        if (legacy !== null && files.length === 0)
-            return packageHash(legacy.toString("utf8"), []);
+        if (legacy !== null && legacy.length === 0)
+            return null;
+        if (legacy !== null)
+            return { hash: packageHash(legacy.toString("utf8"), []), source: "legacy" };
         return null;
     }
     const localFiles = [];
@@ -81,7 +83,7 @@ async function localPackageHash(root, slug, target, files) {
             return null;
         localFiles.push({ path: file.path, bytes, sha256: file.sha256 });
     }
-    return packageHash(main.toString("utf8"), localFiles);
+    return { hash: packageHash(main.toString("utf8"), localFiles), source: "native" };
 }
 async function markInstallSynced(root, slug, files) {
     const manifest = await readSyncManifest();
@@ -119,6 +121,33 @@ async function writeInstallFile(root, target, body) {
         await parent.close();
     }
 }
+async function removeLegacySkillFile(root, slug) {
+    try {
+        await unlink(legacySkillPath(root, slug));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return;
+        if (code === "EISDIR" || code === "ELOOP" || code === "EPERM")
+            return;
+        throw err;
+    }
+}
+async function removeEmptyNativeSkillDir(root, slug) {
+    try {
+        const dir = dirname(skillPath(root, slug));
+        const entries = await readdir(dir);
+        if (entries.length === 0)
+            await rmdir(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTEMPTY" || code === "EEXIST")
+            return;
+        throw err;
+    }
+}
 async function overwriteInstallFile(root, target, body) {
     const parent = await openSafeParentDirectory(root, target);
     const handle = await open(childCreatePath(parent, dirname(target), basename(target)), constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
@@ -203,7 +232,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);
@@ -212,7 +241,7 @@ export async function install(slugInput, opts = {}) {
         }
     }
     catch (err) {
-        spinner.stop();
+        spinner?.stop();
         throw err;
     }
     const target = skillPath(root, slug);
@@ -238,21 +267,29 @@ export async function install(slugInput, opts = {}) {
             }
             throw err;
         }
-        await ensureSafeParentDirectory(root, target);
-        const existing = await localPackageHash(root, slug, target, remotePackageFiles);
+        const existing = await localPackageState(root, slug, target, remotePackageFiles);
         const conflictingTarget = await preflightInstallPackage(root, installFiles, opts.force ? { force: true } : {});
         if (conflictingTarget) {
             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: ${relative(root, conflictingTarget).split(sep).join("/")}`);
         }
-        if (existing === remoteHash) {
+        if (existing?.hash === remoteHash && existing.source === "native") {
+            await removeLegacySkillFile(root, slug);
             action = "unchanged";
         }
-        else if (existing !== null && opts.force) {
+        else if (existing !== null && (opts.force || (existing.source === "legacy" && existing.hash === remoteHash))) {
             try {
-                await overwriteInstallFile(root, target, detail.body_md);
+                if (existing.source === "legacy")
+                    await writeInstallFile(root, target, detail.body_md);
+                else
+                    await overwriteInstallFile(root, target, detail.body_md);
                 for (const file of remotePackageFiles) {
-                    await overwriteInstallFile(root, join(dirname(target), file.path), file.bytes);
+                    const fileTarget = join(dirname(target), file.path);
+                    if (existing.source === "legacy")
+                        await writeInstallFile(root, fileTarget, file.bytes);
+                    else
+                        await overwriteInstallFile(root, fileTarget, file.bytes);
                 }
+                await removeLegacySkillFile(root, slug);
             }
             catch (err) {
                 const code = err.code;
@@ -260,7 +297,7 @@ export async function install(slugInput, opts = {}) {
                     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";
+            action = existing.source === "legacy" ? "installed" : "updated";
         }
         else if (existing !== null) {
             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.");
@@ -271,6 +308,7 @@ export async function install(slugInput, opts = {}) {
                 for (const file of remotePackageFiles) {
                     await writeInstallFile(root, join(dirname(target), file.path), file.bytes);
                 }
+                await removeLegacySkillFile(root, slug);
             }
             catch (err) {
                 const code = err.code;
@@ -294,7 +332,17 @@ export async function install(slugInput, opts = {}) {
             manifestWarning = err instanceof Error ? err.message : String(err);
         }
     });
-    spinner.stop();
+    spinner?.stop();
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({
+            slug,
+            action,
+            target: targetAgent,
+            path: target,
+            setup: Boolean(opts.setup),
+        })}\n`);
+        return;
+    }
     process.stdout.write(`\n${symbols.ok}  [floom] ${action} ${c.bold(slug)}\n`);
     process.stdout.write(`   ${c.dim(dirname(target))}\n\n`);
     if (manifestWarning) {

package/dist/login.js

@@ -1,5 +1,6 @@
 import { createServer } from "node:http";
 import { createServer as createNetServer } from "node:net";
+import { randomBytes } from "node:crypto";
 import open from "open";
 import ora from "ora";
 import { getApiUrl, writeConfig } from "./config.js";
@@ -92,6 +93,7 @@ function reserveEphemeralPort() {
 function waitForCallback(port) {
     return new Promise((resolve, reject) => {
         const apiUrl = getApiUrl();
+        const state = randomBytes(32).toString("base64url");
         let settled = false;
         const server = createServer((req, res) => {
             // CORS preflight from the browser bridge page.
@@ -122,6 +124,15 @@ function waitForCallback(port) {
                             res.end(localCallbackPage("Missing tokens from OAuth response."));
                             return;
                         }
+                        if (data.state !== state) {
+                            res.writeHead(400, {
+                                "access-control-allow-origin": origin,
+                                "access-control-allow-private-network": "true",
+                                "content-type": "text/html; charset=utf-8",
+                            });
+                            res.end(localCallbackPage("Invalid sign-in state."));
+                            return;
+                        }
                         res.writeHead(200, {
                             "access-control-allow-origin": origin,
                             "access-control-allow-private-network": "true",
@@ -161,7 +172,7 @@ function waitForCallback(port) {
             reject(new FloomError(`Local auth server failed on port ${port}.`, `Is port ${port} already in use? (${err.message})`));
         });
         server.listen(port, "127.0.0.1", () => {
-            const target = `${apiUrl}/auth/cli?port=${port}`;
+            const target = `${apiUrl}/auth/cli?port=${port}&state=${encodeURIComponent(state)}`;
             open(target).catch((e) => {
                 const msg = e instanceof Error ? e.message : String(e);
                 process.stdout.write(c.yellow(`Could not auto-open browser (${msg}).\n`) +
@@ -175,7 +186,7 @@ function parseCallbackBody(body, contentType) {
     if (type.includes("application/x-www-form-urlencoded")) {
         const params = new URLSearchParams(body);
         const parsed = {};
-        for (const key of ["access_token", "refresh_token", "expires_in", "token_type"]) {
+        for (const key of ["access_token", "refresh_token", "expires_in", "token_type", "state"]) {
             const value = params.get(key);
             if (value)
                 parsed[key] = value;

package/dist/sync.js

@@ -79,6 +79,17 @@ function skillPath(skill, targetAgent) {
 function syncKey(skill) {
     return `${skill.library_slug ?? ""}\0${skill.folder ?? ""}\0${skill.slug}`;
 }
+function hasStructuredPath(skill) {
+    return Boolean(skill.library_slug || skill.folder);
+}
+function dedupeSyncSkills(skills) {
+    const structuredSlugs = new Set();
+    for (const skill of skills) {
+        if (hasStructuredPath(skill))
+            structuredSlugs.add(skill.slug);
+    }
+    return skills.filter((skill) => !structuredSlugs.has(skill.slug) || hasStructuredPath(skill));
+}
 function validateSyncSkillShape(skill) {
     if (!skill || typeof skill !== "object")
         throw new FloomError("Invalid sync response.");
@@ -288,7 +299,7 @@ export async function sync(opts = {}) {
             for (const skill of payload.skills)
                 validateSyncSkillShape(skill);
             // Version 1 preview syncs published, saved, and subscribed library skills.
-            const all = payload.skills;
+            const all = dedupeSyncSkills(payload.skills);
             const seen = new Set();
             let unchanged = 0;
             let updated = 0;

package/dist/targets.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function resolveSkillsDir(target) {
+    if (process.env.FLOOM_SKILLS_DIR)
+        return process.env.FLOOM_SKILLS_DIR;
+    if (target === "codex") {
+        const codexHome = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+        return process.env.CODEX_SKILLS_DIR ?? join(codexHome, "skills");
+    }
+    return process.env.CLAUDE_SKILLS_DIR ?? join(homedir(), ".claude", "skills");
+}
+export function skillsDirHint(target) {
+    if (process.env.FLOOM_SKILLS_DIR)
+        return "FLOOM_SKILLS_DIR";
+    return target === "codex" ? "CODEX_SKILLS_DIR" : "CLAUDE_SKILLS_DIR";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floomhq/floom",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Sync AI skills across agents and machines.",
   "license": "MIT",
   "type": "module",