@floomhq/floom 1.0.50 → 1.0.52

package/README.md

@@ -12,6 +12,8 @@ floom share my-skill --add teammate@example.com
 floom search review
 floom add awesome-skill --setup
 floom setup --target claude --dry-run
+floom daemon install --target all
+floom status
 floom list
 floom library list
 ```
@@ -27,14 +29,19 @@ The package is designed for `npx -y @floomhq/floom ...`. Global installs expose
 - `npx -y @floomhq/floom publish <path>` — upload a skill folder or Markdown file. Folder packages use `<slug>/SKILL.md` plus optional `references/`, `examples/`, `scripts/`, and `assets/`. Optional `--public` / `--private` / `--unlisted`, `--type knowledge|instruction|workflow|skill`, `--installs-as <target>`, and `--skill-version <label>`.
 - `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>/SKILL.md` with supporting package files. Optional `--target claude|codex`, `--setup` to connect the agent, and `--force` to replace an existing local copy.
+- `npx -y @floomhq/floom add <url-or-slug>` — fetch a skill into the selected agent skills root with supporting package files. Optional `--target claude|codex|cursor|opencode|kimi`, `--setup` to connect the agent, and `--force` to replace an existing 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 setup` — add Floom usage guidance to `CLAUDE.md` or `AGENTS.md`. Optional `--target claude|codex`, `--dry-run`, `--yes`.
+- `npx -y @floomhq/floom setup` — add Floom usage guidance to the selected harness instructions file. Optional `--target claude|codex|cursor|opencode|kimi`, `--dry-run`, `--yes`.
 - `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 or Codex. Optional `--target claude|codex`.
-- `npx -y @floomhq/floom watch` — preview: run sync repeatedly. Optional `--interval <seconds>`; minimum `10`.
+- `npx -y @floomhq/floom sync` — pull your published, saved, and subscribed library skills into one target. Optional `--target claude|codex|cursor|opencode|kimi`.
+- `npx -y @floomhq/floom watch` — run one target sync loop. Optional `--target claude|codex|cursor|opencode|kimi`, `--push`, `--no-yolo`, `--interval <seconds>`; minimum `10`.
+- `npx -y @floomhq/floom daemon install --target all` — install always-on sync for Claude, Codex, Cursor, OpenCode, and Kimi.
+- `npx -y @floomhq/floom daemon status --json` — show the latest daemon cycle and per-target result.
+- `npx -y @floomhq/floom status --json` — reconcile cloud, cache, native projection, and daemon counts.
+- `npx -y @floomhq/floom feedback --kind <kind> --message <text>` — send bounded agent feedback to Floom.
+- `npx -y @floomhq/floom audit skills --json` — report malformed, duplicate, and suspicious owned skills.
 - `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.
@@ -75,7 +82,7 @@ version: 0.1.0
 
 Override the API host with `FLOOM_API_URL` (defaults to `https://floom.dev`).
 
-`floom sync` and `floom watch` are v1 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. Sync writes missing files only.
-Remote updates, existing untracked files, and locally edited tracked files are skipped as conflicts.
+`floom sync`, `floom watch`, and `floom daemon` handle 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. Sync writes missing files and applies cloud updates when the local file still matches the last Floom-tracked hash.
+Existing untracked files and locally edited tracked files are preserved as conflicts.
 Symlinks are never followed. To replace a local skill manually, run `floom add <url-or-slug> --force`.

package/dist/audit.js

@@ -1,6 +1,7 @@
 import ora from "ora";
+import { readFile } from "node:fs/promises";
 import { readConfig, resolveApiUrl } from "./config.js";
-import { getJson } from "./lib/api.js";
+import { getJson, postJson } from "./lib/api.js";
 import { FloomError } from "./errors.js";
 import { c, symbols } from "./ui.js";
 const FIXTURE_RE = /\b(?:cli lifecycle audit fixture|launch gate|temp skill|test fixture|audit fixture)\b/i;
@@ -99,6 +100,44 @@ async function loadOwnedSkills() {
     }
     return skills;
 }
+function archiveSlugsFromPlan(raw) {
+    const value = raw && typeof raw === "object" ? raw : {};
+    const plan = value.archive_plan;
+    if (!Array.isArray(plan))
+        throw new FloomError("Invalid archive plan.", "Pass a JSON file from `floom audit skills --fix-plan`.");
+    const slugs = plan.map((item) => {
+        if (typeof item === "string")
+            return item;
+        if (item && typeof item === "object" && typeof item.slug === "string") {
+            return item.slug;
+        }
+        return "";
+    }).filter(Boolean);
+    if (slugs.length === 0)
+        throw new FloomError("Archive plan has no slugs.");
+    return [...new Set(slugs)];
+}
+async function applyArchivePlan(planPath, yes, json) {
+    const cfg = await readConfig();
+    if (!cfg)
+        throw new FloomError("Not signed in.", "Run `npx -y @floomhq/floom login` first.");
+    const raw = JSON.parse(await readFile(planPath, "utf8"));
+    const slugs = archiveSlugsFromPlan(raw);
+    const payload = await postJson(`${resolveApiUrl(cfg)}/api/v1/me/skills/archive`, yes ? "archive skills" : "preview skill archive", cfg.accessToken, { slugs, dry_run: !yes });
+    if (json) {
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    const action = payload.dry_run ? "Archive preview" : "Archive applied";
+    process.stdout.write(`\n${symbols.ok}  ${action}: ${payload.matched.length}/${payload.requested} matched\n`);
+    if (payload.archived)
+        process.stdout.write(`   archived: ${payload.archived.length}\n`);
+    if (payload.missing.length > 0)
+        process.stdout.write(`   missing or not owned: ${payload.missing.join(", ")}\n`);
+    if (payload.dry_run)
+        process.stdout.write(`   ${c.dim("Re-run with --yes to archive matched skills.")}\n`);
+    process.stdout.write("\n");
+}
 function duplicateGroups(skills) {
     const byHash = new Map();
     for (const skill of skills) {
@@ -135,7 +174,11 @@ function summarize(skills, findings) {
     };
 }
 export async function auditSkills(opts) {
-    const spinner = opts.json ? null : ora({ text: c.dim("Auditing skills..."), color: "yellow" }).start();
+    if (opts.archivePlan) {
+        await applyArchivePlan(opts.archivePlan, opts.yes, opts.json);
+        return;
+    }
+    const spinner = opts.json || opts.fixPlan ? null : ora({ text: c.dim("Auditing skills..."), color: "yellow" }).start();
     let skills;
     try {
         skills = await loadOwnedSkills();

package/dist/cli.js

@@ -20,6 +20,7 @@ import { scanSkill } from "./scan.js";
 import { auditSkills } from "./audit.js";
 import { share } from "./share.js";
 import { feedback } from "./feedback.js";
+import { status } from "./status.js";
 import { libraryAddSkill, libraryCreate, libraryList, libraryRemoveSkill, librarySubscribe, libraryUnsubscribe, moveSkill, } from "./library.js";
 import { c, symbols } from "./ui.js";
 import { printError, FloomError } from "./errors.js";
@@ -114,6 +115,8 @@ function commandUsage() {
                        ${c.dim(`Flags: --target ${TARGET_HINT} (default: claude)`)}
 
    ${c.dim("Advanced")}
+     ${c.cyan("status")}             Show cloud, cache, native projection, and daemon counts
+                       ${c.dim("Flags: --json")}
      ${c.cyan("library")}            Create, browse, and subscribe to libraries
                        ${c.dim("Alias: lib")}
      ${c.cyan("move")} ${c.dim("<slug> --folder <path>")}  Place a saved skill in a relative folder
@@ -278,10 +281,14 @@ function auditUsage() {
    ${c.cyan(`${CLI_COMMAND} audit skills`)}
    ${c.cyan(`${CLI_COMMAND} audit skills --json`)}
    ${c.cyan(`${CLI_COMMAND} audit skills --fix-plan`)}
+   ${c.cyan(`${CLI_COMMAND} audit skills --archive-plan plan.json`)} ${c.dim("(dry-run)")}
+   ${c.cyan(`${CLI_COMMAND} audit skills --archive-plan plan.json --yes`)}
 
  ${c.bold("Flags")}
    ${c.cyan("--json")}       Full machine-readable report
    ${c.cyan("--fix-plan")}   Include archive recommendations, without applying them
+   ${c.cyan("--archive-plan <file>")} Preview or apply a reviewed archive plan
+   ${c.cyan("--yes")}        Apply the archive plan instead of dry-run preview
 `);
 }
 function feedbackUsage() {
@@ -718,17 +725,37 @@ function parseDoctorFlags(argv) {
     }
     return out;
 }
+function parseStatusFlags(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 \`${CLI_COMMAND} status --json\`.`);
+        else
+            throw new FloomError(`Unexpected argument: ${a}`, `Try \`${CLI_COMMAND} status --json\`.`);
+    }
+    return out;
+}
 function parseAuditFlags(argv) {
     const [subcommand, ...rest] = argv;
     if (subcommand !== "skills") {
         throw new FloomError("Unknown audit command.", `Try \`${CLI_COMMAND} audit skills --json\`.`);
     }
-    const out = { json: false, fixPlan: false };
-    for (const a of rest) {
+    const out = { json: false, fixPlan: false, yes: false };
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i] ?? "";
         if (a === "--json")
             out.json = true;
         else if (a === "--fix-plan")
             out.fixPlan = true;
+        else if (a === "--archive-plan" || a.startsWith("--archive-plan=")) {
+            const { value, nextIndex } = readFlagValue(rest, i, "--archive-plan");
+            out.archivePlan = value;
+            i = nextIndex;
+        }
+        else if (a === "--yes")
+            out.yes = true;
         else if (a.startsWith("--"))
             throw new FloomError(`Unknown flag: ${a}`, `Try \`${CLI_COMMAND} audit skills --json\`.`);
         else
@@ -1182,6 +1209,9 @@ async function main() {
                 });
                 return;
             }
+            case "status":
+                await status(parseStatusFlags(rest));
+                return;
             case "add":
             case "install": {
                 const flags = parseAddArgs(rest);

package/dist/daemon.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { access, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { access, appendFile, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { homedir, hostname, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR } from "./config.js";
@@ -17,9 +17,10 @@ function targetsFor(value) {
     return value === "all" ? [...AGENT_TARGETS] : [value];
 }
 function cliInvocation() {
-    const node = JSON.stringify(process.execPath);
-    const entry = JSON.stringify(process.argv[1] ?? "floom");
-    return `${node} ${entry}`;
+    const override = process.env.FLOOM_DAEMON_CLI_COMMAND?.trim();
+    if (override)
+        return override;
+    return `npx -y @floomhq/floom@${CLI_VERSION}`;
 }
 function shellQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
@@ -57,12 +58,7 @@ function runCommand(args, extraEnv = {}) {
 }
 async function appendLog(message) {
     await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    const existing = await readFile(LOG_PATH, "utf8").catch((err) => {
-        if (err.code === "ENOENT")
-            return "";
-        throw err;
-    });
-    await writeFile(LOG_PATH, `${existing}${message}`, { mode: 0o600 });
+    await appendFile(LOG_PATH, message, { mode: 0o600 });
 }
 async function writeStatus(status) {
     await mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
@@ -78,6 +74,30 @@ async function readStatus() {
         throw err;
     }
 }
+function pidIsAlive(pid) {
+    if (!pid || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function statusIsLive(status) {
+    if (!status?.running)
+        return false;
+    if (!pidIsAlive(status.pid))
+        return false;
+    if (!status.next_run_at || !status.interval_seconds)
+        return true;
+    const nextRun = Date.parse(status.next_run_at);
+    if (!Number.isFinite(nextRun))
+        return false;
+    const graceMs = Math.max(status.interval_seconds * 2000, 120_000);
+    return nextRun + graceMs >= Date.now();
+}
 function parseSyncResult(output) {
     const match = output.match(/synced\s+(\d+)\s+skills\s+\((\d+)\s+unchanged,\s+(\d+)\s+updated(?:,\s+(\d+)\s+conflicts?\s+skipped)?/i);
     if (!match)
@@ -291,15 +311,16 @@ async function installDaemon(opts) {
 }
 async function showStatus(opts) {
     const status = await readStatus();
+    const live = statusIsLive(status);
     if (opts.json) {
-        process.stdout.write(`${JSON.stringify(status ?? { running: false }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify(status ? { ...status, running: live } : { running: false }, null, 2)}\n`);
         return;
     }
     if (!status) {
         process.stdout.write(`${symbols.bullet}  Floom daemon has no status yet.\n`);
         return;
     }
-    process.stdout.write(`${symbols.ok}  Floom daemon ${status.running ? "status" : "last status"}\n`);
+    process.stdout.write(`${live ? symbols.ok : symbols.bullet}  Floom daemon ${live ? "status" : "last status"}\n`);
     process.stdout.write(`   ${c.dim("manager:")} ${status.manager}\n`);
     process.stdout.write(`   ${c.dim("targets:")} ${status.targets.join(", ")}\n`);
     if (status.last_completed_at)

package/dist/setup.js

@@ -140,7 +140,7 @@ async function detectTarget(opts) {
             return {
                 agent,
                 label: targetLabel(agent),
-                path: join(homedir(), ".kimi", "agents", "federico-system.md"),
+                path: join(homedir(), ".kimi", "agents", "floom-system.md"),
             };
         }
         const existing = await findUp(INSTRUCTION_FILES[agent].filename);

package/dist/status.js

@@ -0,0 +1,181 @@
+import { constants } from "node:fs";
+import { open, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_DIR, readConfig, resolveApiUrl } from "./config.js";
+import { floomFetch } from "./lib/api.js";
+import { AGENT_TARGETS, targetSkillsDir } from "./targets.js";
+import { c, symbols } from "./ui.js";
+const STATUS_CLOUD_TIMEOUT_MS = 8_000;
+async function readJsonFile(path) {
+    try {
+        const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            return JSON.parse(await handle.readFile("utf8"));
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ELOOP" || err instanceof SyntaxError)
+            return null;
+        throw err;
+    }
+}
+async function countDirectSkillPackages(root) {
+    let count = 0;
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+    if (entries.some((entry) => entry.isFile() && entry.name === "SKILL.md"))
+        count += 1;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        try {
+            const child = await readdir(join(root, entry.name), { withFileTypes: true });
+            if (child.some((item) => item.isFile() && item.name === "SKILL.md"))
+                count += 1;
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    return count;
+}
+function manifestCounts(manifest) {
+    const files = manifest?.files && typeof manifest.files === "object" ? Object.values(manifest.files) : [];
+    return {
+        files: files.length,
+        skills: new Set(files.map((entry) => entry.slug).filter((slug) => typeof slug === "string" && slug.length > 0)).size,
+    };
+}
+async function countCloudVisible() {
+    const cfg = await readConfig();
+    if (!cfg)
+        return { signedIn: false, total: null };
+    const apiUrl = resolveApiUrl(cfg);
+    try {
+        const url = new URL(`${apiUrl}/api/v1/me/skills`);
+        url.searchParams.set("limit", "100");
+        const res = await floomFetch(url.toString(), "load your skills", {
+            token: cfg.accessToken,
+            timeoutMs: STATUS_CLOUD_TIMEOUT_MS,
+            rateLimitRetries: 0,
+        });
+        const payload = (await res.json());
+        const sampleCount = Array.isArray(payload.skills) ? payload.skills.length : 0;
+        const hasMore = Boolean(payload.next_cursor);
+        return {
+            signedIn: true,
+            total: hasMore ? null : sampleCount,
+            sampleCount,
+            hasMore,
+        };
+    }
+    catch (err) {
+        return {
+            signedIn: true,
+            total: null,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+async function buildStatus() {
+    const cloud = await countCloudVisible();
+    const daemonRaw = await readJsonFile(join(CONFIG_DIR, "daemon-status.json"));
+    const daemonRunning = daemonIsLive(daemonRaw);
+    const targets = {};
+    for (const target of AGENT_TARGETS) {
+        const cacheRoot = join(CONFIG_DIR, "skill-cache", target);
+        const nativeRoot = targetSkillsDir(target);
+        const cacheManifest = manifestCounts(await readJsonFile(join(cacheRoot, ".floom-cli-sync-manifest.json")));
+        const nativeManifest = manifestCounts(await readJsonFile(join(CONFIG_DIR, "native-sync-manifests", `${target}.json`)));
+        targets[target] = {
+            cache_packages: cacheManifest.skills || await countDirectSkillPackages(cacheRoot),
+            cache_manifest_files: cacheManifest.files,
+            cache_manifest_skills: cacheManifest.skills,
+            native_root: nativeRoot,
+            native_packages: nativeManifest.skills || await countDirectSkillPackages(nativeRoot),
+            native_manifest_files: nativeManifest.files,
+            native_manifest_skills: nativeManifest.skills,
+            ...(daemonRaw?.last_run?.[target] ? { daemon: daemonRaw.last_run[target] } : {}),
+        };
+    }
+    return {
+        cloud: {
+            signed_in: cloud.signedIn,
+            visible_total: cloud.total,
+            ...(cloud.sampleCount !== undefined ? { visible_sample_count: cloud.sampleCount } : {}),
+            ...(cloud.hasMore !== undefined ? { visible_has_more: cloud.hasMore } : {}),
+            ...(cloud.error ? { error: cloud.error } : {}),
+        },
+        daemon: {
+            running: daemonRunning,
+            ...(daemonRaw?.version ? { version: daemonRaw.version } : {}),
+            ...(daemonRaw?.hostname ? { hostname: daemonRaw.hostname } : {}),
+            ...(daemonRaw?.targets ? { targets: daemonRaw.targets } : {}),
+            ...(daemonRaw?.last_completed_at ? { last_completed_at: daemonRaw.last_completed_at } : {}),
+            ...(daemonRaw?.next_run_at ? { next_run_at: daemonRaw.next_run_at } : {}),
+        },
+        targets,
+        notes: [
+            "Floom cache is the synced local package store used by MCP/search/router flows.",
+            "Native harness roots stay small where the harness would otherwise preload thousands of skills.",
+            "Instruction files tell agents to use Floom search/MCP instead of enumerating every cached package.",
+        ],
+    };
+}
+function daemonIsLive(status) {
+    if (!status?.running)
+        return false;
+    if (!status.pid || status.pid < 1)
+        return false;
+    try {
+        process.kill(status.pid, 0);
+    }
+    catch {
+        return false;
+    }
+    if (!status.next_run_at || !status.interval_seconds)
+        return true;
+    const nextRun = Date.parse(status.next_run_at);
+    if (!Number.isFinite(nextRun))
+        return false;
+    const graceMs = Math.max(status.interval_seconds * 2000, 120_000);
+    return nextRun + graceMs >= Date.now();
+}
+export async function status(opts) {
+    const payload = await buildStatus();
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`\n${symbols.dot}  ${c.bold("Floom status")}\n\n`);
+    process.stdout.write(`   ${c.dim("cloud signed in:")} ${payload.cloud.signed_in ? "yes" : "no"}\n`);
+    const cloudVisible = payload.cloud.visible_total ?? (payload.cloud.visible_has_more ? `${payload.cloud.visible_sample_count ?? "?"}+` : "unknown");
+    process.stdout.write(`   ${c.dim("cloud visible skills:")} ${cloudVisible}\n`);
+    if (payload.cloud.error)
+        process.stdout.write(`   ${c.dim("cloud status:")} ${payload.cloud.error}\n`);
+    process.stdout.write(`   ${c.dim("daemon:")} ${payload.daemon.running ? "running" : "not running"}${payload.daemon.version ? ` (${payload.daemon.version})` : ""}\n`);
+    if (payload.daemon.last_completed_at)
+        process.stdout.write(`   ${c.dim("last completed:")} ${payload.daemon.last_completed_at}\n`);
+    process.stdout.write("\n");
+    for (const target of AGENT_TARGETS) {
+        const row = payload.targets[target];
+        const daemon = row.daemon ? ` daemon=${row.daemon.ok ? "ok" : "error"} synced=${row.daemon.synced ?? "?"} conflicts=${row.daemon.conflicts ?? "?"}` : "";
+        process.stdout.write(`   ${c.cyan(target.padEnd(8))} cache=${row.cache_packages} native=${row.native_packages} nativeTracked=${row.native_manifest_skills}${daemon}\n`);
+    }
+    process.stdout.write("\n");
+    for (const note of payload.notes)
+        process.stdout.write(`   ${c.dim(`- ${note}`)}\n`);
+    process.stdout.write("\n");
+}

package/dist/sync.js

@@ -153,6 +153,7 @@ function syncPackageFiles(target, body, files) {
 async function planPackageSync(root, files, manifest) {
     let missing = 0;
     let unchanged = 0;
+    let remoteChanged = 0;
     let firstMissingTarget = null;
     for (const file of files) {
         const targetKey = manifestKey(root, file.target);
@@ -186,12 +187,16 @@ async function planPackageSync(root, files, manifest) {
         }
         if (state.hash !== tracked.hash)
             return { kind: "conflict", target: file.target, reason: "local file changed since the last Floom sync" };
-        if (state.hash !== file.hash)
-            return { kind: "conflict", target: file.target, reason: "remote skill changed; move or delete the local file to accept the Floom version" };
+        if (state.hash !== file.hash) {
+            remoteChanged += 1;
+            continue;
+        }
         unchanged += 1;
     }
     if (unchanged === files.length)
         return { kind: "unchanged" };
+    if (missing === 0 && remoteChanged > 0)
+        return { kind: "update" };
     if (missing === files.length)
         return { kind: "write" };
     return {
@@ -200,6 +205,25 @@ async function planPackageSync(root, files, manifest) {
         reason: "local package is only partially installed",
     };
 }
+async function overwriteTrackedFile(root, target, body, expectedHash) {
+    const parent = await openSafeParentDirectory(root, target, false);
+    let handle = null;
+    try {
+        handle = await open(childCreatePath(parent, dirname(target), basename(target)), constants.O_RDWR | constants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw conflictError("path is blocked by an existing local file or directory", "ENOTDIR");
+        const currentHash = sha256(await handle.readFile());
+        if (currentHash !== expectedHash)
+            throw conflictError("local file changed since the last Floom sync", "EEXIST");
+        await handle.truncate(0);
+        await writeAll(handle, body);
+    }
+    finally {
+        await handle?.close();
+        await parent.close();
+    }
+}
 async function ensureSafeParentDirectory(root, target) {
     const resolvedRoot = resolve(root);
     const resolvedParent = resolve(dirname(target));
@@ -348,8 +372,19 @@ export async function sync(opts = {}) {
                         continue;
                     }
                     try {
-                        for (const file of packageFiles)
-                            await writeSyncedFile(root, file.target, file.bytes);
+                        if (plan.kind === "update") {
+                            for (const file of packageFiles) {
+                                const targetKey = manifestKey(root, file.target);
+                                const tracked = manifest.files[targetKey];
+                                if (!tracked)
+                                    throw conflictError("existing file is not tracked by Floom sync", "EEXIST");
+                                await overwriteTrackedFile(root, file.target, file.bytes, tracked.hash);
+                            }
+                        }
+                        else {
+                            for (const file of packageFiles)
+                                await writeSyncedFile(root, file.target, file.bytes);
+                        }
                     }
                     catch (err) {
                         const code = err.code;

package/package.json

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