@floomhq/skills 0.2.7 → 0.2.9

package/dist/index.js

@@ -1907,10 +1907,10 @@ function parseManifest(raw) {
   };
 }
 async function readManifest(skillDir) {
-  const { readFile: readFile9 } = await import("node:fs/promises");
-  const { join: join12 } = await import("node:path");
+  const { readFile: readFile11 } = await import("node:fs/promises");
+  const { join: join15 } = await import("node:path");
   try {
-    const raw = await readFile9(join12(skillDir, "skill.json"), "utf8");
+    const raw = await readFile11(join15(skillDir, "skill.json"), "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -2049,12 +2049,13 @@ function presetDir(target, opts) {
       return join(root, ".claude", "skills");
     case "gemini":
       return join(root, ".gemini", "skills");
+    case "kimi":
+      return join(root, ".kimi", "skills");
     case "codex":
     case "cursor":
     case "generic":
     case "all":
     case "opencode":
-    case "kimi":
     default:
       return join(root, ".agents", "skills");
   }
@@ -2364,7 +2365,7 @@ var log = {
   err: (msg) => console.error(chalk.red("\u2717 ") + msg),
   step: (msg) => console.log(chalk.dim("\xB7 ") + msg),
   heading: (msg) => console.log("\n" + chalk.bold(msg)),
-  kv: (key, value) => console.log(`  ${chalk.dim(key.padEnd(16))}${value}`),
+  kv: (key, value) => console.log(`  ${chalk.dim(key.padEnd(18))}${value}`),
   blank: () => console.log("")
 };
 
@@ -2448,7 +2449,7 @@ function isLegacyApiUrl(apiUrl) {
 }
 
 // src/version.ts
-var VERSION = "0.2.7";
+var VERSION = "0.2.9";
 
 // src/api-client.ts
 var DEFAULT_TIMEOUT_MS = 2e4;
@@ -2876,7 +2877,8 @@ import { readFile as readFile6 } from "node:fs/promises";
 import { join as join6 } from "node:path";
 async function publishCommand(opts = {}) {
   const auth = await readAuth();
-  if (!auth && !opts.dryRun) {
+  const envToken = process.env.FLOOM_API_TOKEN?.trim();
+  if (!auth && !envToken && !opts.dryRun) {
     log.err("Not logged in. Run: floom login");
     process.exit(1);
   }
@@ -2896,7 +2898,9 @@ async function publishCommand(opts = {}) {
   const manifest = m.manifest;
   const skillMd = await readFile6(join6(dir, "SKILL.md"), "utf8");
   const { meta } = parseSkillFrontmatter(skillMd);
-  const refRoot = opts.workspace ?? opts.library ?? auth?.handle ?? "<your-handle>";
+  const me = !opts.dryRun && !auth && envToken ? await api("/me", { authRequired: true }) : null;
+  const handle = auth?.handle ?? me?.user.handle;
+  const refRoot = opts.workspace ?? opts.library ?? handle ?? "<your-handle>";
   log.heading(`${opts.dryRun ? "Dry-running" : "Publishing"} ${refRoot}/${manifest.name}@${manifest.version}`);
   log.step("Packing bundle...");
   const bundle = await collectBundle(dir);
@@ -2909,8 +2913,7 @@ async function publishCommand(opts = {}) {
     log.ok("Dry run passed. No upload was requested.");
     return;
   }
-  const activeAuth = auth;
-  if (!activeAuth) {
+  if (!handle) {
     log.err("Not logged in. Run: floom login");
     process.exit(1);
   }
@@ -2937,7 +2940,7 @@ async function publishCommand(opts = {}) {
     });
   } catch (e) {
     if (e instanceof FloomError && e.code === "VERSION_ALREADY_EXISTS") {
-      log.err(`Version ${manifest.version} already exists for @${activeAuth.handle}/${manifest.name}.`);
+      log.err(`Version ${manifest.version} already exists for @${handle}/${manifest.name}.`);
       log.info("Bump the version in skill.json (e.g. 0.1.1) and try again.");
       process.exit(1);
     }
@@ -2955,7 +2958,7 @@ async function publishCommand(opts = {}) {
   log.ok(`Published ${complete.ref}`);
   log.blank();
   log.info("View:");
-  log.kv("", `${activeAuth.apiUrl.replace("/api/v1", "")}/@${activeAuth.handle}/${manifest.name}`);
+  log.kv("", `${(auth?.apiUrl ?? process.env.FLOOM_API_URL ?? "https://skills.floom.dev/api/v1").replace("/api/v1", "")}/@${handle}/${manifest.name}`);
   log.info("Install:");
   log.kv("", complete.install_command);
 }
@@ -2966,7 +2969,7 @@ import { join as join8 } from "node:path";
 import { tmpdir } from "node:os";
 
 // src/lib/floom-lock.ts
-import { readFile as readFile7, writeFile as writeFile3, stat as stat3, readdir as readdir2 } from "node:fs/promises";
+import { readFile as readFile7, writeFile as writeFile3, mkdir as mkdir3, stat as stat3, readdir as readdir2 } from "node:fs/promises";
 import { join as join7, relative as relative2, sep as sep2, posix as posix2 } from "node:path";
 import { createHash as createHash3 } from "node:crypto";
 var EMPTY = { schema_version: "0.1", skills: {} };
@@ -2975,6 +2978,7 @@ async function readLock(projectDir) {
     const raw = await readFile7(join7(projectDir, "floom.lock"), "utf8");
     const parsed = JSON.parse(raw);
     if (parsed.schema_version === "0.1") return parsed;
+    if (parsed.schema_version === "0.2") return parsed;
     const version = typeof parsed.schema_version === "string" ? parsed.schema_version : "missing";
     throw new Error(
       `LOCK_SCHEMA_UNSUPPORTED: floom.lock schema_version ${version} is not supported by this CLI. The existing floom.lock was left unchanged; migrate it or reinstall skills with the current CLI.`
@@ -2985,11 +2989,32 @@ async function readLock(projectDir) {
   }
 }
 async function writeLock(projectDir, lock) {
+  await mkdir3(projectDir, { recursive: true });
   await writeFile3(join7(projectDir, "floom.lock"), JSON.stringify(lock, null, 2) + "\n", "utf8");
 }
 function setLockEntry(lock, ref, entry) {
   return { ...lock, skills: { ...lock.skills, [ref]: entry } };
 }
+function upgradeLockToV02(lock, opts = {}) {
+  if (lock.schema_version === "0.2") {
+    return {
+      ...lock,
+      target: opts.target ?? lock.target,
+      scope: opts.scope ?? lock.scope,
+      default_workspace: opts.defaultWorkspace ?? lock.default_workspace,
+      last_sync_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  return {
+    schema_version: "0.2",
+    default_workspace: opts.defaultWorkspace,
+    target: opts.target,
+    scope: opts.scope,
+    last_sync_at: (/* @__PURE__ */ new Date()).toISOString(),
+    instructions: [],
+    skills: lock.skills
+  };
+}
 async function hashInstalledFolder(folderAbs) {
   const out = [];
   async function walk2(dir) {
@@ -3358,7 +3383,7 @@ async function shareCommand(refStr, email, opts = {}) {
     body: { email, role }
   });
   log.ok(`Shared ${refStr} with ${r.grant.email} as ${r.grant.role}.`);
-  log.info("No email is sent in V0. They will see the skill under 'Shared with Me' on next login.");
+  if (r.email_status) log.kv("email", r.email_status);
 }
 async function unshareCommand(refStr, email) {
   const ref = parseSkillRef(refStr);
@@ -3404,11 +3429,509 @@ async function libraryLeaveCommand(librarySlug) {
   log.ok(`Left workspace ${librarySlug}`);
 }
 
+// src/lib/config-file.ts
+import { mkdir as mkdir6, readFile as readFile8, writeFile as writeFile4 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { dirname, join as join10 } from "node:path";
+import { z as z2 } from "zod";
+var FLOOM_CONFIG_VERSION = "0.1";
+var TARGETS = ["claude", "codex", "cursor", "kimi", "opencode"];
+var targetConfigSchema = z2.object({
+  active_workspaces: z2.array(z2.string().min(1)).default([]),
+  instruction_path: z2.string().min(1).optional()
+});
+var configSchema = z2.object({
+  version: z2.literal(FLOOM_CONFIG_VERSION).default(FLOOM_CONFIG_VERSION),
+  default_workspace: z2.string().min(1).optional(),
+  targets: z2.record(z2.enum(TARGETS), targetConfigSchema).default({})
+});
+function configPath(scope, cwd = process.cwd()) {
+  if (scope === "global") return join10(homedir3(), ".floom", "config.json");
+  return join10(cwd, ".floom", "config.json");
+}
+async function readFloomConfig(scope, cwd = process.cwd()) {
+  try {
+    const raw = await readFile8(configPath(scope, cwd), "utf8");
+    return configSchema.parse(JSON.parse(raw));
+  } catch (e) {
+    if (e.code === "ENOENT") return configSchema.parse({});
+    throw e;
+  }
+}
+async function writeFloomConfig(scope, config, cwd = process.cwd()) {
+  const path = configPath(scope, cwd);
+  const parsed = configSchema.parse(config);
+  await mkdir6(dirname(path), { recursive: true, mode: 448 });
+  await writeFile4(path, JSON.stringify(parsed, null, 2) + "\n", { mode: 384 });
+}
+function normalizeScope(value) {
+  return value === "global" ? "global" : "local";
+}
+function assertTarget(value) {
+  if (TARGETS.includes(value)) return value;
+  throw new Error(`Invalid target: ${value}. Expected ${TARGETS.join(", ")}`);
+}
+async function setDefaultWorkspace(slug, scope, cwd = process.cwd()) {
+  const config = await readFloomConfig(scope, cwd);
+  const next = { ...config, default_workspace: slug };
+  await writeFloomConfig(scope, next, cwd);
+  return next;
+}
+async function setWorkspaceActive(input) {
+  const config = await readFloomConfig(input.scope, input.cwd);
+  const current = config.targets[input.target] ?? { active_workspaces: [] };
+  const set = new Set(current.active_workspaces);
+  if (input.active) set.add(input.workspace);
+  else set.delete(input.workspace);
+  const next = {
+    ...config,
+    targets: {
+      ...config.targets,
+      [input.target]: {
+        ...current,
+        active_workspaces: Array.from(set).sort()
+      }
+    }
+  };
+  await writeFloomConfig(input.scope, next, input.cwd);
+  return next;
+}
+
+// src/commands/instruction.ts
+import { mkdir as mkdir7, readFile as readFile9, writeFile as writeFile5 } from "node:fs/promises";
+import { basename as basename2, dirname as dirname2, join as join11 } from "node:path";
+import { createHash as createHash4 } from "node:crypto";
+var START = "<!-- FLOOM START -->";
+var END = "<!-- FLOOM END -->";
+var AGENT_INSTRUCTION_TARGETS = ["claude", "codex", "cursor", "opencode"];
+function defaultInstructionPath(target) {
+  if (target === "claude") return "CLAUDE.md";
+  if (target === "codex") return "AGENTS.md";
+  if (target === "cursor") return ".cursor/rules/floom.mdc";
+  if (target === "opencode") return ".opencode/instructions/floom.md";
+  throw new Error(`No default instruction path for target ${target}`);
+}
+function replaceManagedBlock(existing, blockBody) {
+  const block = `${START}
+${blockBody.trim()}
+${END}
+`;
+  const start = existing.indexOf(START);
+  const end = existing.indexOf(END);
+  if (start >= 0 && end > start) {
+    const afterEnd = end + END.length;
+    const prefix = existing.slice(0, start);
+    const suffix = existing.slice(afterEnd).replace(/^\n/, "");
+    return { content: `${prefix}${block}${suffix}`, hadBlock: true };
+  }
+  return { content: existing.trim() ? `${existing.trimEnd()}
+
+${block}` : block, hadBlock: false };
+}
+function resolveScope(opts) {
+  if (opts.account && opts.workspace) throw new Error("Use either --account or --workspace, not both.");
+  if (opts.account) return "account";
+  if (opts.workspace) return "workspace";
+  throw new Error("Instruction command requires --account or --workspace <slug>.");
+}
+function bodySha256(body) {
+  return createHash4("sha256").update(body, "utf8").digest("hex");
+}
+async function readUtf8FileStrict(path) {
+  const bytes = await readFile9(path);
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new Error(`${path} is not valid UTF-8; refusing to rewrite it as a managed instruction file.`);
+  }
+  return bytes.toString("utf8");
+}
+function assertAgentInstructionTarget(value) {
+  if (AGENT_INSTRUCTION_TARGETS.includes(value)) return value;
+  throw new Error(`Invalid instruction target: ${value}. Expected ${AGENT_INSTRUCTION_TARGETS.join(", ")}. Kimi uses the Floom guide skill in V0.`);
+}
+function assertPublishInstructionTarget(value) {
+  if (value === "default") return "default";
+  return assertAgentInstructionTarget(value);
+}
+async function fetchInstruction(input) {
+  return api("/instructions", {
+    authRequired: true,
+    query: input
+  });
+}
+function buildInstructionBlock(sections) {
+  return [
+    "# Floom",
+    "",
+    "Use Floom for workspace-approved AI skills and instructions.",
+    "",
+    ...sections.flatMap((section) => [
+      `## ${section.label}`,
+      "",
+      section.body_md.trim(),
+      ""
+    ])
+  ].join("\n");
+}
+async function writeManagedInstructionFile(input) {
+  let existing = "";
+  let existed = true;
+  try {
+    existing = await readUtf8FileStrict(input.path);
+  } catch (e) {
+    if (e.code === "ENOENT") existed = false;
+    else throw e;
+  }
+  const next = replaceManagedBlock(existing, input.blockBody);
+  if (existed && !next.hadBlock && !input.apply && !input.force) {
+    log.warn(`Refusing to modify ${input.path} without an existing Floom managed block.`);
+    log.info("Re-run with --apply to append the managed block, or --path <file> for a dedicated file.");
+    process.exit(1);
+  }
+  if (existed && existing === next.content) return { changed: false };
+  let backupPath;
+  if (existed && existing) {
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    backupPath = join11(".floom", "backups", `${basename2(input.path)}.${stamp}.bak`);
+    await mkdir7(dirname2(backupPath), { recursive: true, mode: 448 });
+    await writeFile5(backupPath, existing, { mode: 384 });
+  }
+  await mkdir7(dirname2(input.path), { recursive: true });
+  await writeFile5(input.path, next.content, "utf8");
+  return { changed: true, backupPath };
+}
+async function recordCliActivity(input) {
+  try {
+    await api("/cli/activity", { method: "POST", authRequired: true, body: input });
+  } catch (e) {
+    log.warn(`Activity event not recorded: ${e.message}`);
+  }
+}
+async function upsertInstructionLock(input) {
+  const lock = upgradeLockToV02(await readLock(process.cwd()), {
+    target: input.target,
+    scope: input.configScope,
+    defaultWorkspace: input.defaultWorkspace
+  });
+  const instructions = (lock.instructions ?? []).filter(
+    (entry) => !(entry.scope === input.scope && entry.workspace === input.workspace && entry.target === input.target && entry.path === input.path)
+  );
+  instructions.push({
+    scope: input.scope,
+    workspace: input.workspace,
+    target: input.target,
+    version_id: input.version_id,
+    body_sha256: input.body_sha256,
+    pulled_at: (/* @__PURE__ */ new Date()).toISOString(),
+    path: input.path
+  });
+  await writeLock(process.cwd(), { ...lock, instructions, last_sync_at: (/* @__PURE__ */ new Date()).toISOString() });
+}
+async function instructionPullCommand(opts = {}) {
+  const target = assertAgentInstructionTarget(opts.target ?? "codex");
+  const configScope = normalizeScope(opts.scope);
+  const scope = resolveScope(opts);
+  const config = await readFloomConfig(configScope);
+  const workspace = opts.workspace ?? (scope === "workspace" ? config.default_workspace : void 0);
+  if (scope === "workspace" && !workspace) throw new Error("Workspace instruction pull requires --workspace <slug> or a configured default workspace.");
+  const path = opts.path ?? defaultInstructionPath(target);
+  const resp = await fetchInstruction({ scope, workspace, target });
+  if (!resp.instruction?.latest) {
+    log.info("No remote instruction found.");
+    return;
+  }
+  const label = scope === "account" ? "Account Instructions" : `Workspace Instructions: ${workspace}`;
+  const writeResult = await writeManagedInstructionFile({
+    path,
+    blockBody: buildInstructionBlock([{ label, body_md: resp.instruction.latest.body_md }]),
+    apply: opts.apply,
+    force: opts.force
+  });
+  if (!writeResult.changed) {
+    log.info(`${path} is already at the latest ${scope} instruction.`);
+    return;
+  }
+  if (writeResult.backupPath) log.info(`Backed up previous instruction file to ${writeResult.backupPath}`);
+  await upsertInstructionLock({
+    scope,
+    workspace,
+    target,
+    path,
+    version_id: resp.instruction.latest.id,
+    body_sha256: resp.instruction.latest.body_sha256,
+    configScope,
+    defaultWorkspace: config.default_workspace
+  });
+  await recordCliActivity({
+    event_type: "instruction.pulled_cli",
+    scope,
+    workspace,
+    target,
+    instruction_id: resp.instruction.id,
+    version_id: resp.instruction.latest.id,
+    path
+  });
+  log.ok(`Pulled ${scope} instruction to ${path}`);
+}
+async function instructionPushCommand(file, opts = {}) {
+  const target = assertPublishInstructionTarget(opts.target ?? "default");
+  const scope = resolveScope(opts);
+  if (scope === "workspace") {
+    const workspace = opts.workspace;
+    const info = await api(`/libraries/${workspace}`, { authRequired: true });
+    if (info.role !== "admin" && info.role !== "editor") {
+      throw new Error(`Workspace instruction push requires editor or admin role in ${workspace}.`);
+    }
+  }
+  const body = await readFile9(file, "utf8");
+  const resp = await api("/instructions", {
+    method: "POST",
+    authRequired: true,
+    body: {
+      scope,
+      workspace: opts.workspace,
+      target,
+      body_md: body,
+      changelog: opts.changelog ?? `Published from CLI (${file}, ${bodySha256(body).slice(0, 12)})`
+    }
+  });
+  log.ok(`Published ${scope} instruction ${resp.instruction?.latest?.version_seq ? `v${resp.instruction.latest.version_seq}` : ""}`.trim());
+}
+
+// src/commands/workspace-config.ts
+async function assertWorkspaceExists(slug) {
+  await api(`/libraries/${slug}`, { authRequired: true });
+}
+function parseOptions(opts) {
+  return {
+    target: assertTarget(opts.target ?? "codex"),
+    scope: normalizeScope(opts.scope)
+  };
+}
+async function defaultWorkspaceCommand(slug, opts = {}) {
+  const scope = normalizeScope(opts.scope);
+  if (!slug) {
+    const config = await readFloomConfig(scope);
+    if (!config.default_workspace) {
+      log.info(`No default workspace configured for ${scope} scope.`);
+      return;
+    }
+    console.log(config.default_workspace);
+    return;
+  }
+  await assertWorkspaceExists(slug);
+  await setDefaultWorkspace(slug, scope);
+  log.ok(`Default workspace (${scope}) set to ${slug}`);
+}
+async function workspaceActivateCommand(slug, opts = {}) {
+  const parsed = parseOptions(opts);
+  await assertWorkspaceExists(slug);
+  await setWorkspaceActive({ workspace: slug, target: parsed.target, scope: parsed.scope, active: true });
+  await recordCliActivity({ event_type: "workspace.activate_cli", workspace: slug, target: parsed.target });
+  log.ok(`Activated ${slug} for ${parsed.target} (${parsed.scope})`);
+}
+async function workspaceDeactivateCommand(slug, opts = {}) {
+  const parsed = parseOptions(opts);
+  await setWorkspaceActive({ workspace: slug, target: parsed.target, scope: parsed.scope, active: false });
+  await recordCliActivity({ event_type: "workspace.deactivate_cli", workspace: slug, target: parsed.target });
+  log.ok(`Deactivated ${slug} for ${parsed.target} (${parsed.scope})`);
+}
+async function workspaceActiveCommand(opts = {}) {
+  const parsed = parseOptions(opts);
+  const config = await readFloomConfig(parsed.scope);
+  const active = config.targets[parsed.target]?.active_workspaces ?? [];
+  if (!active.length) {
+    log.info(`No active workspaces for ${parsed.target} (${parsed.scope}).`);
+    return;
+  }
+  for (const workspace of active) console.log(workspace);
+}
+
+// src/commands/sync.ts
+import { mkdir as mkdir8, writeFile as writeFile6 } from "node:fs/promises";
+import { dirname as dirname3, join as join12 } from "node:path";
+var ROUTER_SKILL = [
+  "# Floom Find Skills",
+  "",
+  "Use this router skill instead of loading every Floom skill into context.",
+  "",
+  "When a task may need a reusable skill:",
+  "",
+  "1. Call the Floom MCP `search_skills` tool with a short query.",
+  "2. Review the compact candidate list.",
+  "3. Call `get_skill` only for the selected candidate.",
+  "4. Call `install_skill` only when the skill needs to be available locally.",
+  "",
+  "Do not enumerate the whole workspace library into model context. Keep skill bodies out of context until selected.",
+  ""
+].join("\n");
+async function installRouter(target) {
+  const install = resolveInstallDir({ target });
+  const routerDir = target === "kimi" ? "floom" : "floom-find-skills";
+  const path = join12(install.dir, routerDir, "SKILL.md");
+  await mkdir8(dirname3(path), { recursive: true });
+  await writeFile6(path, ROUTER_SKILL, "utf8");
+  return path;
+}
+async function pullInstructions(input) {
+  const path = defaultInstructionPath(input.target);
+  const sections = [];
+  const account = await fetchInstruction({ scope: "account", target: input.target });
+  if (account.instruction?.latest) {
+    sections.push({
+      label: "Account Instructions",
+      scope: "account",
+      instruction_id: account.instruction.id,
+      version_id: account.instruction.latest.id,
+      body_sha256: account.instruction.latest.body_sha256,
+      body_md: account.instruction.latest.body_md
+    });
+  }
+  for (const workspace of input.activeWorkspaces) {
+    const resp = await fetchInstruction({ scope: "workspace", workspace, target: input.target });
+    if (!resp.instruction?.latest) continue;
+    sections.push({
+      label: `Workspace Instructions: ${workspace}`,
+      scope: "workspace",
+      workspace,
+      instruction_id: resp.instruction.id,
+      version_id: resp.instruction.latest.id,
+      body_sha256: resp.instruction.latest.body_sha256,
+      body_md: resp.instruction.latest.body_md
+    });
+  }
+  if (sections.length === 0) {
+    log.info("No remote instructions found.");
+    return;
+  }
+  const writeResult = await writeManagedInstructionFile({
+    path,
+    blockBody: buildInstructionBlock(sections.map((section) => ({ label: section.label, body_md: section.body_md }))),
+    apply: input.apply,
+    force: input.force
+  });
+  if (!writeResult.changed) {
+    log.info(`${path} already contains the latest Floom instruction block.`);
+    return;
+  }
+  if (writeResult.backupPath) log.info(`Backed up previous instruction file to ${writeResult.backupPath}`);
+  for (const section of sections) {
+    await upsertInstructionLock({
+      scope: section.scope,
+      workspace: section.workspace,
+      target: input.target,
+      path,
+      version_id: section.version_id,
+      body_sha256: section.body_sha256,
+      configScope: input.scope,
+      defaultWorkspace: input.defaultWorkspace
+    });
+    await recordCliActivity({
+      event_type: "instruction.pulled_cli",
+      scope: section.scope,
+      workspace: section.workspace,
+      target: input.target,
+      instruction_id: section.instruction_id,
+      version_id: section.version_id,
+      path
+    });
+  }
+  log.ok(`Pulled ${sections.length} instruction section(s) to ${path}`);
+}
+async function statusCommand(opts = {}) {
+  const target = assertTarget(opts.target ?? "codex");
+  const scope = normalizeScope(opts.scope);
+  const config = await readFloomConfig(scope);
+  const active = config.targets[target]?.active_workspaces ?? [];
+  log.heading(`Floom status for ${target} (${scope})`);
+  log.kv("Default workspace", config.default_workspace ?? "(none)");
+  log.kv("Active workspaces", active.length ? active.join(", ") : "(none)");
+  log.kv("Local pull policy", "router + pinned skills + instructions only");
+  for (const workspace of active) {
+    const pins = await api(`/libraries/${workspace}/pins`, {
+      authRequired: true,
+      query: { target }
+    });
+    log.blank();
+    log.info(`${workspace}: ${pins.pins.length} pinned skill(s) for ${target}`);
+    for (const pin of pins.pins) {
+      log.kv("", `${pin.skill?.slug ?? pin.skill_id}${pin.skill?.latest?.version ? `@${pin.skill.latest.version}` : ""}`);
+    }
+  }
+}
+async function pullCommand(opts = {}) {
+  const target = assertTarget(opts.target ?? "codex");
+  const scope = normalizeScope(opts.scope);
+  const config = await readFloomConfig(scope);
+  const active = config.targets[target]?.active_workspaces ?? [];
+  const routerPath = await installRouter(target);
+  log.ok(`Installed Floom router skill to ${routerPath}`);
+  if (target === "kimi") {
+    log.info("Kimi uses the Floom guide/router skill in V0; account and workspace instructions are not merged into Kimi context.");
+  } else {
+    await pullInstructions({
+      target: assertAgentInstructionTarget(target),
+      scope,
+      defaultWorkspace: config.default_workspace,
+      activeWorkspaces: active,
+      apply: opts.apply,
+      force: opts.force
+    });
+  }
+  for (const workspace of active) {
+    const pins = await api(`/libraries/${workspace}/pins`, {
+      authRequired: true,
+      query: { target }
+    });
+    for (const pin of pins.pins) {
+      if (!pin.skill?.slug) continue;
+      await installCommand(`${workspace}/${pin.skill.slug}`, { for: target, force: opts.force });
+    }
+    await recordCliActivity({
+      event_type: "workspace.pulled_cli",
+      workspace,
+      target,
+      resources: pins.pins.map((pin) => ({ type: "skill", id: pin.skill_id, name: pin.skill?.slug ?? pin.skill_id }))
+    });
+  }
+  log.blank();
+  log.ok("Pull complete.");
+}
+
+// src/commands/pin.ts
+async function resolveWorkspace(opts) {
+  if (opts.workspace) return opts.workspace;
+  const config = await readFloomConfig("local");
+  if (config.default_workspace) return config.default_workspace;
+  throw new Error("Pin command requires --workspace <slug> or a configured default workspace.");
+}
+async function pinCommand(ref, opts = {}) {
+  const target = assertTarget(opts.target ?? "codex");
+  const workspace = await resolveWorkspace(opts);
+  await api(`/libraries/${workspace}/pins`, {
+    method: "POST",
+    authRequired: true,
+    body: { ref, target }
+  });
+  log.ok(`Pinned ${ref} for ${target} in ${workspace}`);
+}
+async function unpinCommand(ref, opts = {}) {
+  const target = assertTarget(opts.target ?? "codex");
+  const workspace = await resolveWorkspace(opts);
+  await api(`/libraries/${workspace}/pins`, {
+    method: "DELETE",
+    authRequired: true,
+    query: { ref, target }
+  });
+  log.ok(`Unpinned ${ref} for ${target} in ${workspace}`);
+}
+
 // src/commands/mcp.ts
-import { mkdtemp, mkdir as mkdir6, readdir as readdir4, readFile as readFile8, rename as rename3, rm as rm3, writeFile as writeFile4 } from "node:fs/promises";
-import { join as join10 } from "node:path";
+import { mkdtemp, mkdir as mkdir9, readdir as readdir4, readFile as readFile10, rename as rename3, rm as rm3, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join13 } from "node:path";
 import { tmpdir as tmpdir3 } from "node:os";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 var API_TIMEOUT_MS = 2e4;
@@ -3477,11 +4000,11 @@ async function installViaApi(token, refText, target) {
   const bundle = await rawGet(dl.download.url);
   if (!verifyBundleHash(bundle, dl.bundle_sha256)) throw new Error("Bundle hash mismatch");
   const install = resolveInstallDir({ target });
-  await mkdir6(install.dir, { recursive: true });
-  const dest = join10(install.dir, parsed.slug);
+  await mkdir9(install.dir, { recursive: true });
+  const dest = join13(install.dir, parsed.slug);
   const exists = await readdir4(dest).then(() => true).catch(() => false);
   if (exists) await rm3(dest, { recursive: true, force: true });
-  const temp = await mkdtemp(join10(tmpdir3(), `floom-mcp-${parsed.slug}-`));
+  const temp = await mkdtemp(join13(tmpdir3(), `floom-mcp-${parsed.slug}-`));
   try {
     await extractBundle(bundle, temp);
     await rename3(temp, dest);
@@ -3504,7 +4027,7 @@ async function installViaApi(token, refText, target) {
   return { path: dest, version: dl.version, ref: info.ref ?? ref };
 }
 async function parseSkillBundle(bundle) {
-  const tmp = await mkdtemp(join10(tmpdir3(), "floom-mcp-read-"));
+  const tmp = await mkdtemp(join13(tmpdir3(), "floom-mcp-read-"));
   try {
     await extractBundle(bundle, tmp);
     const files = [];
@@ -3512,16 +4035,16 @@ async function parseSkillBundle(bundle) {
       const entries = await readdir4(dir, { withFileTypes: true });
       for (const entry of entries) {
         const nextRel = rel ? `${rel}/${entry.name}` : entry.name;
-        const full = join10(dir, entry.name);
+        const full = join13(dir, entry.name);
         if (entry.isDirectory()) await walk2(full, nextRel);
         else files.push(nextRel);
       }
     };
     await walk2(tmp);
     const skillMdPath = files.find((f) => f.toUpperCase() === "SKILL.MD");
-    const skillMd = skillMdPath ? await readFile8(join10(tmp, skillMdPath), "utf8") : "";
+    const skillMd = skillMdPath ? await readFile10(join13(tmp, skillMdPath), "utf8") : "";
     const skillJsonPath = files.find((f) => f.toLowerCase() === "skill.json");
-    const skillJson = skillJsonPath ? JSON.parse(await readFile8(join10(tmp, skillJsonPath), "utf8")) : null;
+    const skillJson = skillJsonPath ? JSON.parse(await readFile10(join13(tmp, skillJsonPath), "utf8")) : null;
     return { files, skill_md: skillMd, skill_json: skillJson };
   } finally {
     await rm3(tmp, { recursive: true, force: true });
@@ -3529,13 +4052,13 @@ async function parseSkillBundle(bundle) {
 }
 async function mcpCommand() {
   const server = new McpServer({ name: "floom", version: VERSION });
-  server.tool("search_skills", { query: z2.string().min(1), workspace: z2.string().optional(), library: z2.string().optional() }, async ({ query, workspace, library }) => {
+  server.tool("search_skills", { query: z3.string().min(1), workspace: z3.string().optional(), library: z3.string().optional() }, async ({ query, workspace, library }) => {
     const token = await resolveRequiredToken();
     const workspaceSlug = workspace ?? library;
     const result = await apiRequest(token, "/skills", { q: query, ...workspaceSlug ? { library: workspaceSlug } : {} });
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
   });
-  server.tool("get_skill", { ref: z2.string().min(3) }, async ({ ref }) => {
+  server.tool("get_skill", { ref: z3.string().min(3) }, async ({ ref }) => {
     const token = await resolveOptionalToken();
     const parsed = parseSkillRef(ref);
     if (!parsed) throw new Error("Invalid ref. Expected @owner/slug or workspace/slug");
@@ -3552,7 +4075,55 @@ async function mcpCommand() {
   }
   server.tool("list_workspaces", {}, listWorkspaces);
   server.tool("list_libraries", {}, listWorkspaces);
-  server.tool("install_skill", { ref: z2.string().min(3), target: z2.enum(["claude", "codex", "cursor", "kimi", "opencode", "gemini"]) }, async ({ ref, target }) => {
+  server.tool("get_floom_guide", {}, async () => {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          guide: [
+            "Use Floom to discover approved AI skills without loading every skill into context.",
+            "Call search_skills when you need a skill that is not already installed.",
+            "Call get_skill only after selecting a specific skill candidate.",
+            "Call install_skill only after the user or task requires local installation.",
+            "Use get_instruction for account/workspace guidance visible to this agent."
+          ]
+        })
+      }]
+    };
+  });
+  server.tool("get_instruction", {
+    scope: z3.enum(["account", "workspace"]).default("account"),
+    workspace: z3.string().optional(),
+    target: z3.enum(["default", "claude", "codex", "cursor", "opencode"]).default("default")
+  }, async ({ scope, workspace, target }) => {
+    const token = await resolveRequiredToken();
+    const result = await apiRequest(token, "/instructions", {
+      scope,
+      ...workspace ? { workspace } : {},
+      target
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  });
+  server.tool("list_active_workspaces", {
+    target: z3.enum(["claude", "codex", "cursor", "kimi", "opencode"]).default("codex"),
+    scope: z3.enum(["global", "local"]).default("local")
+  }, async ({ target, scope }) => {
+    const config = await readFloomConfig(normalizeScope(scope));
+    const active = config.targets[assertTarget(target)]?.active_workspaces ?? [];
+    return { content: [{ type: "text", text: JSON.stringify({ target, scope, active_workspaces: active }) }] };
+  });
+  server.tool("list_pinned_skills", {
+    workspace: z3.string().optional(),
+    target: z3.enum(["claude", "codex", "cursor", "kimi", "opencode"]).default("codex")
+  }, async ({ workspace, target }) => {
+    const token = await resolveRequiredToken();
+    const config = await readFloomConfig("local");
+    const workspaceSlug = workspace ?? config.default_workspace;
+    if (!workspaceSlug) throw new Error("workspace is required when no default workspace is configured");
+    const result = await apiRequest(token, `/libraries/${workspaceSlug}/pins`, { target });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  });
+  server.tool("install_skill", { ref: z3.string().min(3), target: z3.enum(["claude", "codex", "cursor", "kimi", "opencode", "gemini"]) }, async ({ ref, target }) => {
     const token = await resolveOptionalToken();
     const installed = await installViaApi(token, ref, target);
     return { content: [{ type: "text", text: JSON.stringify(installed) }] };
@@ -3564,7 +4135,7 @@ async function mcpCommand() {
 // src/commands/doctor.ts
 import { mkdtemp as mkdtemp2, readdir as readdir5, rm as rm4 } from "node:fs/promises";
 import { tmpdir as tmpdir4 } from "node:os";
-import { join as join11 } from "node:path";
+import { join as join14 } from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 function textOf(result) {
@@ -3642,9 +4213,9 @@ async function doctorCommand(opts = {}) {
     emitDoctor(checks, opts.json);
     process.exit(1);
   }
-  const tmpHome = await mkdtemp2(join11(tmpdir4(), "floom-doctor-home-"));
-  const tmpSkills = await mkdtemp2(join11(tmpdir4(), "floom-doctor-skills-"));
-  const tmpProject = await mkdtemp2(join11(tmpdir4(), "floom-doctor-project-"));
+  const tmpHome = await mkdtemp2(join14(tmpdir4(), "floom-doctor-home-"));
+  const tmpSkills = await mkdtemp2(join14(tmpdir4(), "floom-doctor-skills-"));
+  const tmpProject = await mkdtemp2(join14(tmpdir4(), "floom-doctor-project-"));
   const transport = new StdioClientTransport({
     command: process.execPath,
     args: [cliPath, "mcp"],
@@ -3728,16 +4299,28 @@ program.command("outdated").description("Show installed skills with newer versio
 program.command("update [ref]").description("Update installed skills to latest.").option("--force", "Overwrite local edits").action((ref, opts) => updateCommand(ref, opts));
 program.command("list").description("List remote skills.").option("--mine", "Only your own skills (default)").option("--workspace <slug>", "Filter by workspace slug").option("--library <slug>", "Legacy alias for --workspace").option("--folder <uuid>", "Filter by folder id").option("--flat", "Print one ref per line").option("--query <q>", "Filter by query").action(listCommand);
 program.command("info <ref>").description("Show details for a remote skill.").action(infoCommand);
+program.command("status").description("Show local vs remote Floom workspace state").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").action((opts) => statusCommand(opts));
+program.command("pull").description("Pull account/workspace instructions for active workspaces").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").option("--apply", "Append managed block when the target file has no Floom block").option("--force", "Write without the first-apply guard").action((opts) => pullCommand(opts));
+program.command("pin <ref>").description("Pin a workspace skill for local pull").option("--workspace <slug>", "Workspace slug").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").action((ref, opts) => pinCommand(ref, opts));
+program.command("unpin <ref>").description("Unpin a workspace skill for local pull").option("--workspace <slug>", "Workspace slug").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").action((ref, opts) => unpinCommand(ref, opts));
 program.command("share <ref> <email>").description("Invite someone to a skill by email.").option("--role <role>", "viewer (default) or editor").action((ref, email, opts) => shareCommand(ref, email, opts));
 program.command("unshare <ref> <email>").description("Revoke someone's access.").action((ref, email) => unshareCommand(ref, email));
+var configCmd = program.command("config").description("Manage local Floom configuration");
+configCmd.command("default-workspace [slug]").description("Show or set the default workspace").option("--scope <scope>", "global | local", "local").action((slug, opts) => defaultWorkspaceCommand(slug, opts));
 function addWorkspaceCommands(cmd) {
   cmd.command("list").action(libraryListCommand);
   cmd.command("create <slug> <name>").action((slug, name) => libraryCreateCommand(slug, name));
   cmd.command("invite <workspaceSlug> <email>").option("--role <role>", "viewer|editor|admin", "viewer").action((workspaceSlug, email, opts) => libraryInviteCommand(workspaceSlug, email, opts.role));
   cmd.command("leave <workspaceSlug>").action((workspaceSlug) => libraryLeaveCommand(workspaceSlug));
+  cmd.command("activate <workspaceSlug>").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").action((workspaceSlug, opts) => workspaceActivateCommand(workspaceSlug, opts));
+  cmd.command("deactivate <workspaceSlug>").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").action((workspaceSlug, opts) => workspaceDeactivateCommand(workspaceSlug, opts));
+  cmd.command("active").option("--target <target>", "claude | codex | cursor | kimi | opencode", "codex").option("--scope <scope>", "global | local", "local").action((opts) => workspaceActiveCommand(opts));
 }
 addWorkspaceCommands(program.command("workspace").description("Manage workspaces"));
 addWorkspaceCommands(program.command("library").description("Manage workspaces (legacy alias)"));
+var instructionCmd = program.command("instruction").description("Manage account and workspace instructions");
+instructionCmd.command("pull").description("Pull an account or workspace instruction into a managed local block").option("--account", "Pull account instruction").option("--workspace <slug>", "Pull workspace instruction").option("--target <target>", "default | claude | codex | cursor | opencode", "codex").option("--scope <scope>", "global | local", "local").option("--path <path>", "Instruction file path override").option("--apply", "Append managed block when the target file has no Floom block").option("--force", "Write without the first-apply guard").action((opts) => instructionPullCommand(opts));
+instructionCmd.command("push <file>").description("Publish an account or workspace instruction from a markdown file").option("--account", "Publish account instruction").option("--workspace <slug>", "Publish workspace instruction").option("--target <target>", "default | claude | codex | cursor | opencode", "default").option("--changelog <text>", "Version changelog").action((file, opts) => instructionPushCommand(file, opts));
 program.command("doctor").description("Check local Floom CLI, auth, and fresh-agent MCP installability.").option("--fresh-agent", "Run MCP checks with a clean HOME and temp skills directory").option("--ref <ref>", "Skill ref to install during --fresh-agent, e.g. @depontefede/pdf").option("--target <target>", "Install target for --fresh-agent", "codex").option("--query <query>", "Search query for --fresh-agent", "pdf").option("--json", "Emit machine-readable JSON").action((opts) => doctorCommand(opts));
 program.command("mcp").description("Run local MCP server over stdio.").action(mcpCommand);
 async function main() {