@brainbase-labs/cli 0.5.0 → 0.6.0

package/dist/index.js

@@ -28566,7 +28566,7 @@ var require_jsx_dev_runtime = __commonJS((exports, module) => {
 // src/index.ts
 var import_picocolors40 = __toESM(require_picocolors(), 1);
 import process13 from "node:process";
-import fs50 from "node:fs";
+import fs51 from "node:fs";
 
 // src/cli/template.ts
 var import_picocolors12 = __toESM(require_picocolors(), 1);
@@ -50768,8 +50768,9 @@ import fs39 from "node:fs";
 var import_yaml2 = __toESM(require_dist(), 1);
 var AGENT_MANIFEST_FILE = "brainbase.agent.yaml";
 var LEGACY_AGENT_MANIFEST_FILE = "brainbase.yaml";
-var DEFAULT_INSTRUCTIONS_FILE = "instructions.md";
-var DEFAULT_ENTRYPOINT_FILE = "entrypoint.sh";
+var DEFAULT_INSTRUCTIONS_FILE = ".brainbase/instructions.md";
+var DEFAULT_ENTRYPOINT_FILE = ".brainbase/entrypoint.sh";
+var DEFAULT_PLAYBOOKS_DIR = ".brainbase/playbooks";
 var REGISTRY_SOURCE_RE = /^registry:(?:([a-z0-9_-]+)\/)?([a-z0-9_-]+)(?:@(.+))?$/i;
 function parseSkillSource2(raw) {
   if (!raw || typeof raw !== "string") {
@@ -50809,6 +50810,17 @@ var EntrypointSchema = exports_external.object({
 }, {
   message: "entrypoint must set exactly one of `file`, `commands`, or `text`"
 });
+var PlaybookContentSchema = exports_external.object({
+  file: exports_external.string().min(1).optional(),
+  text: exports_external.string().optional()
+}).refine((v3) => v3.file !== undefined || v3.text !== undefined, {
+  message: "playbook content must set either `file` or `text`"
+});
+var PlaybookSchema = exports_external.object({
+  title: exports_external.string().min(1),
+  description: exports_external.string().optional(),
+  content: PlaybookContentSchema
+});
 var SkillEntrySchema = exports_external.object({
   source: exports_external.string().min(1)
 });
@@ -50828,6 +50840,7 @@ var AgentManifestSchema = exports_external.object({
   agent: AgentMetaSchema,
   instructions: InstructionsSchema.optional(),
   entrypoint: EntrypointSchema.optional(),
+  playbooks: exports_external.array(PlaybookSchema).default([]),
   skills: exports_external.array(SkillEntrySchema).default([]),
   mcp: exports_external.array(McpEntrySchema).default([]),
   commands: exports_external.array(exports_external.record(exports_external.unknown())).optional(),
@@ -50911,6 +50924,21 @@ function resolveEntrypoint(cwd2, manifest) {
   }
   return null;
 }
+function resolvePlaybookContent(cwd2, entry) {
+  const c2 = entry.content;
+  if (typeof c2.text === "string")
+    return c2.text;
+  if (typeof c2.file === "string") {
+    const p2 = path42.resolve(cwd2, c2.file);
+    if (!fs39.existsSync(p2))
+      return null;
+    return fs39.readFileSync(p2, "utf8");
+  }
+  return null;
+}
+function slugifyPlaybookTitle(title) {
+  return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "playbook";
+}
 
 // src/core/link.ts
 var LINK_DIR = ".brainbase";
@@ -51064,6 +51092,7 @@ function writeLink(cwd2, link2) {
     manifest = readManifest(cwd2) ?? {
       schema: 1,
       agent: { name: link2.name },
+      playbooks: [],
       skills: [],
       mcp: []
     };
@@ -51071,6 +51100,7 @@ function writeLink(cwd2, link2) {
     manifest = {
       schema: 1,
       agent: { name: link2.name },
+      playbooks: [],
       skills: [],
       mcp: []
     };
@@ -51973,6 +52003,7 @@ import path48 from "node:path";
 import fs45 from "node:fs";
 import os12 from "node:os";
 var import_picocolors25 = __toESM(require_picocolors(), 1);
+var import_yaml3 = __toESM(require_dist(), 1);
 
 // src/core/agent-diff.ts
 import path46 from "node:path";
@@ -52119,8 +52150,34 @@ function readLocalComponents(cwd2, manifest) {
       hash: hashMcpEntry(entry)
     });
   }
+  for (const entry of manifest.playbooks ?? []) {
+    const body = resolvePlaybookContent(cwd2, entry);
+    if (body === null) {
+      out.push({
+        type: "playbook",
+        slug: slugifyPlaybookTitle(entry.title),
+        hash: null
+      });
+      continue;
+    }
+    const wireBody = /^---\s*\n/.test(body) ? body : `---
+title: ${jsonOrPlain(entry.title)}` + (entry.description ? `
+description: ${jsonOrPlain(entry.description)}` : "") + `
+---
+${body.replace(/^\n+/, "")}`;
+    out.push({
+      type: "playbook",
+      slug: slugifyPlaybookTitle(entry.title),
+      hash: componentHashFromFileHashes([hashString(wireBody)])
+    });
+  }
   return out;
 }
+function jsonOrPlain(s3) {
+  if (!/[\n":#&*!|>'%@`{}[\]]/.test(s3) && s3.trim() === s3 && s3 !== "")
+    return s3;
+  return JSON.stringify(s3);
+}
 function threeWayDiff(input) {
   const lockMap = new Map;
   for (const c2 of input.lock)
@@ -52489,8 +52546,9 @@ async function runAgentPull(cwd2, args) {
         }
       }
     }
-    materializeInstructions(cwd2, cloud, toInstallKeys, keepLocalKeys);
+    materializeInstructions(cwd2, cloud, toInstallKeys, keepLocalKeys, existingManifest);
     materializeEntrypoint(cwd2, cloudAgent.entrypoint ?? "", existingManifest);
+    materializePlaybooks(cwd2, cloud, toInstallKeys, keepLocalKeys, existingManifest);
     const yaml = mergeManifest(cwd2, existingManifest, cloud, cloudAgent, harness);
     writeManifest(cwd2, yaml);
     writeLink(cwd2, buildLinkFromAgent(cloudAgent, harness, readLink(cwd2)));
@@ -52595,7 +52653,7 @@ function runHarnessInstall2(harnessId, components, opts, agentName) {
     return installKafkaWithCtx(components, opts, agentName);
   return getAdapter(harnessId).install(components, opts);
 }
-function materializeInstructions(cwd2, cloud, toInstall, keepLocal) {
+function materializeInstructions(cwd2, cloud, toInstall, keepLocal, existingManifest) {
   for (const c2 of cloud.components) {
     if (c2.type !== "instruction")
       continue;
@@ -52607,8 +52665,52 @@ function materializeInstructions(cwd2, cloud, toInstall, keepLocal) {
     const body = c2.files[0]?.content ?? "";
     if (!body.trim())
       continue;
-    fs45.writeFileSync(path48.join(cwd2, DEFAULT_INSTRUCTIONS_FILE), body, "utf8");
+    if (existingManifest?.instructions?.text !== undefined)
+      continue;
+    const targetRel = existingManifest?.instructions?.file ?? DEFAULT_INSTRUCTIONS_FILE;
+    const target = path48.resolve(cwd2, targetRel);
+    ensureDir(path48.dirname(target));
+    fs45.writeFileSync(target, body, "utf8");
+  }
+}
+function materializePlaybooks(cwd2, cloud, toInstall, keepLocal, existingManifest) {
+  for (const c2 of cloud.components) {
+    if (c2.type !== "playbook")
+      continue;
+    const key2 = `${c2.type}/${c2.slug}`;
+    if (keepLocal.has(key2))
+      continue;
+    if (!toInstall.has(key2))
+      continue;
+    const raw = c2.files[0]?.content ?? "";
+    if (!raw.trim())
+      continue;
+    const { body } = stripFrontmatter(raw);
+    const existing = existingManifest?.playbooks?.find((p2) => slugifyForCompare(p2.title) === c2.slug);
+    if (existing?.content?.text !== undefined)
+      continue;
+    const targetRel = existing?.content?.file ?? path48.join(DEFAULT_PLAYBOOKS_DIR, `${c2.slug}.md`);
+    const target = path48.resolve(cwd2, targetRel);
+    ensureDir(path48.dirname(target));
+    fs45.writeFileSync(target, body, "utf8");
+  }
+}
+function slugifyForCompare(s3) {
+  return s3.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "playbook";
+}
+function stripFrontmatter(raw) {
+  const m3 = /^---\s*\n([\s\S]*?)\n---\s*\n?/.exec(raw);
+  if (!m3)
+    return { frontmatter: {}, body: raw };
+  let fm = {};
+  try {
+    const parsed = import_yaml3.default.parse(m3[1] ?? "");
+    if (parsed && typeof parsed === "object")
+      fm = parsed;
+  } catch {
+    return { frontmatter: {}, body: raw };
   }
+  return { frontmatter: fm, body: raw.slice(m3[0].length) };
 }
 function mergeManifest(cwd2, prev, cloud, cloudAgent, harness) {
   const skills = cloud.components.filter((c2) => c2.type === "skill").map((c2) => {
@@ -52645,6 +52747,21 @@ function mergeManifest(cwd2, prev, cloud, cloudAgent, harness) {
     else
       entrypoint = { file: prev?.entrypoint?.file ?? DEFAULT_ENTRYPOINT_FILE };
   }
+  const playbooks = cloud.components.filter((c2) => c2.type === "playbook").map((c2) => {
+    const raw = c2.files[0]?.content ?? "";
+    const { frontmatter } = stripFrontmatter(raw);
+    const local = prev?.playbooks?.find((pb) => slugifyForCompare(pb.title) === c2.slug);
+    const title = local?.title ?? (typeof frontmatter.title === "string" && frontmatter.title || c2.slug);
+    const description = local?.description ?? (typeof frontmatter.description === "string" ? frontmatter.description : undefined);
+    const content = local?.content?.text !== undefined ? { text: local.content.text } : {
+      file: local?.content?.file ?? path48.join(DEFAULT_PLAYBOOKS_DIR, `${c2.slug}.md`)
+    };
+    return {
+      title,
+      ...description ? { description } : {},
+      content
+    };
+  });
   const mcp = cloud.components.filter((c2) => c2.type === "mcp").map((c2) => {
     const payload = (c2.meta ?? {}).mcp ?? {};
     const entry = { name: c2.slug };
@@ -52672,6 +52789,7 @@ function mergeManifest(cwd2, prev, cloud, cloudAgent, harness) {
     },
     ...instructions ? { instructions } : {},
     ...entrypoint ? { entrypoint } : {},
+    playbooks,
     skills,
     mcp
   };
@@ -52910,6 +53028,42 @@ async function buildOutgoingComponents(cwd2, manifest, cloud) {
       }
     });
   }
+  const seenPlaybookSlugs = new Set;
+  for (const entry of manifest.playbooks ?? []) {
+    if (entry.content.text !== undefined && entry.content.file !== undefined) {
+      f2.error(`Playbook ${import_picocolors26.default.bold(entry.title)} sets both ${import_picocolors26.default.cyan("text")} and ${import_picocolors26.default.cyan("file")} — pick one.`);
+      return null;
+    }
+    const body = resolvePlaybookContent(cwd2, entry);
+    if (body === null) {
+      if (entry.content.file) {
+        f2.error(`Playbook ${import_picocolors26.default.bold(entry.title)} content file ${import_picocolors26.default.bold(entry.content.file)} not found.`);
+      } else {
+        f2.error(`Playbook ${import_picocolors26.default.bold(entry.title)} content is empty.`);
+      }
+      return null;
+    }
+    const slug = slugifyPlaybookTitle(entry.title);
+    if (seenPlaybookSlugs.has(slug)) {
+      f2.error(`Two playbooks resolve to the same slug ${import_picocolors26.default.bold(slug)} (from title ${import_picocolors26.default.bold(entry.title)}). Pick distinct titles.`);
+      return null;
+    }
+    seenPlaybookSlugs.add(slug);
+    const wireBody = assemblePlaybookBody(entry, body);
+    const fileName = `${slug}.md`;
+    const fileHash2 = hashString(wireBody);
+    out.push({
+      type: "playbook",
+      slug,
+      description: entry.description,
+      hash: componentHashFromFileHashes([fileHash2]),
+      files: [{ path: fileName, content: wireBody, hash: fileHash2 }],
+      meta: {
+        title: entry.title,
+        ...entry.description ? { description: entry.description } : {}
+      }
+    });
+  }
   for (const entry of manifest.mcp ?? []) {
     if (!entry.url && !entry.command) {
       f2.error(`MCP ${import_picocolors26.default.bold(entry.name)} needs either ${import_picocolors26.default.cyan("url")} or ${import_picocolors26.default.cyan("command")}.`);
@@ -52937,6 +53091,23 @@ async function buildOutgoingComponents(cwd2, manifest, cloud) {
   }
   return out;
 }
+function assemblePlaybookBody(entry, body) {
+  if (/^---\s*\n/.test(body))
+    return body;
+  const lines = ["---", `title: ${yamlScalar(entry.title)}`];
+  if (entry.description) {
+    lines.push(`description: ${yamlScalar(entry.description)}`);
+  }
+  lines.push("---", "");
+  return lines.join(`
+`) + body.replace(/^\n+/, "");
+}
+function yamlScalar(s3) {
+  if (!/[\n":#&*!|>'%@`{}[\]]/.test(s3) && s3.trim() === s3 && s3 !== "") {
+    return s3;
+  }
+  return JSON.stringify(s3);
+}
 
 // src/cli/agent-push.ts
 async function runAgentPush(cwd2, args) {
@@ -53003,8 +53174,8 @@ async function runAgentPush(cwd2, args) {
   }
   const entrypointChanged = resolvedEntrypoint !== undefined && resolvedEntrypoint !== (lock?.agentMeta?.entrypoint ?? "");
   for (const r2 of rows) {
-    if (r2.type !== "instruction" && r2.type !== "skill" && r2.type !== "mcp") {
-      f2.error(`Component ${fmtType(r2.type)} ${import_picocolors27.default.bold(r2.slug)} can't be pushed yet — the server accepts instructions, skills, and mcps in this version.`);
+    if (r2.type !== "instruction" && r2.type !== "skill" && r2.type !== "mcp" && r2.type !== "playbook") {
+      f2.error(`Component ${fmtType(r2.type)} ${import_picocolors27.default.bold(r2.slug)} can't be pushed yet — the server accepts instructions, skills, mcps, and playbooks in this version.`);
       return;
     }
   }
@@ -53731,6 +53902,7 @@ async function loadOrScaffoldManifest(cwd2, args) {
     schema: 1,
     ...seedHarness ? { harness: seedHarness } : {},
     agent: { name: seedName, ...args.tagline ? { tagline: args.tagline } : {} },
+    playbooks: [],
     skills: [],
     mcp: []
   };
@@ -53774,183 +53946,10 @@ function handleApiError4(err) {
 }
 
 // src/cli/agent-unpack.ts
-var import_picocolors31 = __toESM(require_picocolors(), 1);
-
-// src/core/agent-fresh-install.ts
 import path50 from "node:path";
 import fs46 from "node:fs";
 import os13 from "node:os";
-async function installAgentFresh(input) {
-  const { cwd: cwd2, agent, cloud, harness } = input;
-  const scope = input.scope ?? "project";
-  ensureDir(cwd2);
-  const stageRoot = stageManifestComponents2(cloud.components);
-  const justInstalledPaths = new Map;
-  const cloudHasOrchestrationMcp = cloud.components.some((c2) => c2.type === "mcp" && c2.slug === ORCHESTRATION_MCP_SLUG);
-  const needOrchestrationMcpInstall = !cloudHasOrchestrationMcp;
-  const cloudHasMemoryMcp = cloud.components.some((c2) => c2.type === "mcp" && c2.slug === MEMORY_MCP_SLUG);
-  const needMemoryMcpInstall = !cloudHasMemoryMcp;
-  try {
-    if (cloud.components.length > 0 || needOrchestrationMcpInstall || needMemoryMcpInstall) {
-      const toInstall = cloud.components.map((c2) => ({
-        type: c2.type,
-        slug: c2.slug,
-        scope,
-        rootDir: path50.join(stageRoot, c2.type, c2.slug),
-        description: c2.description,
-        meta: c2.meta,
-        payload: c2.meta?.mcp,
-        checksum: c2.hash
-      }));
-      if (needOrchestrationMcpInstall) {
-        toInstall.push(buildOrchestrationMcpComponent(scope));
-      }
-      if (needMemoryMcpInstall) {
-        toInstall.push(buildMemoryMcpComponent(scope));
-      }
-      const installOpts = {
-        cwd: cwd2,
-        scope,
-        resolveConflict: async (_c) => "overwrite",
-        resolveSecret: async () => null
-      };
-      const result = await runHarnessInstall3(harness, toInstall, installOpts, agent.name);
-      for (const o2 of result.installed) {
-        justInstalledPaths.set(`${o2.type}/${o2.slug}`, o2.installedPaths);
-      }
-    }
-    materializeInstructions2(cwd2, cloud);
-    const manifest = input.preserveManifest ? null : buildManifestFromCloud(cloud, agent);
-    if (manifest)
-      writeManifest(cwd2, manifest);
-    writeLink(cwd2, {
-      schemaVersion: 1,
-      agent_id: agent.id,
-      org_id: agent.org_id,
-      team_id: agent.team_id,
-      slug: agent.slug,
-      name: agent.name,
-      tagline: agent.tagline,
-      url: agent.url,
-      linked_at: new Date().toISOString(),
-      harness
-    });
-    const syncedComponents = cloud.components.map((c2) => ({
-      type: c2.type,
-      slug: c2.slug,
-      hash: c2.hash,
-      installedPaths: justInstalledPaths.get(`${c2.type}/${c2.slug}`) ?? []
-    }));
-    writeSyncState(cwd2, {
-      schemaVersion: 1,
-      agent_id: agent.id,
-      revision: cloud.revision,
-      synced_at: new Date().toISOString(),
-      components: syncedComponents,
-      agentMeta: { name: agent.name, tagline: agent.tagline }
-    });
-    if (input.pullSecrets !== false) {
-      await pullAgentSecrets(cwd2, agent.id);
-    }
-    const returnedManifest = manifest ?? buildManifestFromCloud(cloud, agent);
-    return {
-      installedPaths: justInstalledPaths,
-      manifest: returnedManifest,
-      syncedComponents
-    };
-  } finally {
-    try {
-      fs46.rmSync(stageRoot, { recursive: true, force: true });
-    } catch {}
-  }
-}
-function stageManifestComponents2(components) {
-  const root = fs46.mkdtempSync(path50.join(os13.tmpdir(), "brainbase-orch-pull-"));
-  for (const c2 of components) {
-    const compDir = path50.join(root, c2.type, c2.slug);
-    ensureDir(compDir);
-    for (const f4 of c2.files) {
-      const target = path50.join(compDir, f4.path);
-      ensureDir(path50.dirname(target));
-      fs46.writeFileSync(target, f4.content);
-    }
-  }
-  return root;
-}
-function runHarnessInstall3(harnessId, components, opts, agentName) {
-  if (harnessId === "claude-code")
-    return installClaudeCodeWithCtx(components, opts, agentName);
-  if (harnessId === "codex")
-    return installCodexWithCtx(components, opts, agentName);
-  if (harnessId === "kafka")
-    return installKafkaWithCtx(components, opts, agentName);
-  return getAdapter(harnessId).install(components, opts);
-}
-function materializeInstructions2(cwd2, cloud) {
-  for (const c2 of cloud.components) {
-    if (c2.type !== "instruction")
-      continue;
-    const body = c2.files[0]?.content ?? "";
-    if (!body.trim())
-      continue;
-    fs46.writeFileSync(path50.join(cwd2, DEFAULT_INSTRUCTIONS_FILE), body, "utf8");
-    return;
-  }
-}
-function buildManifestFromCloud(cloud, agent) {
-  const skills = cloud.components.filter((c2) => c2.type === "skill").map((c2) => {
-    const meta = c2.meta ?? {};
-    if (meta.name && meta.name.includes("/")) {
-      return {
-        source: meta.version ? `registry:${meta.name}@${meta.version}` : `registry:${meta.name}`
-      };
-    }
-    return { source: `registry:${c2.slug}` };
-  });
-  const hasInstructions = cloud.components.some((c2) => c2.type === "instruction" && c2.files[0]?.content?.trim());
-  const mcp = cloud.components.filter((c2) => c2.type === "mcp").map((c2) => {
-    const payload = (c2.meta ?? {}).mcp ?? {};
-    const entry = { name: c2.slug };
-    if (typeof payload.url === "string")
-      entry.url = payload.url;
-    if (typeof payload.command === "string")
-      entry.command = payload.command;
-    if (Array.isArray(payload.args))
-      entry.args = payload.args.map(String);
-    if (payload.env && typeof payload.env === "object")
-      entry.env = payload.env;
-    if (payload.headers && typeof payload.headers === "object")
-      entry.headers = payload.headers;
-    if (typeof payload.is_enabled === "boolean")
-      entry.is_enabled = payload.is_enabled;
-    return entry;
-  });
-  return {
-    schema: 1,
-    agent: {
-      name: agent.name,
-      ...agent.tagline ? { tagline: agent.tagline } : {}
-    },
-    ...hasInstructions ? { instructions: { file: DEFAULT_INSTRUCTIONS_FILE } } : {},
-    skills,
-    mcp
-  };
-}
-async function pullAgentSecrets(cwd2, agentId) {
-  try {
-    const res = await api.getAgentSecrets(agentId);
-    const secrets = res.secrets ?? {};
-    if (Object.keys(secrets).length > 0) {
-      writeLocalSecrets(cwd2, secrets);
-    }
-  } catch (err) {
-    if (err instanceof ApiError && err.status !== 404) {
-      f2.warn(`Skipped secrets for agent ${agentId}: ${err.message}`);
-    }
-  }
-}
-
-// src/cli/agent-unpack.ts
+var import_picocolors31 = __toESM(require_picocolors(), 1);
 async function runAgentUnpack(cwd2, args) {
   banner("agent unpack — install this agent into a harness layout");
   if (!hasManifest(cwd2)) {
@@ -53982,22 +53981,9 @@ async function runAgentUnpack(cwd2, args) {
   } else {
     harness = await pickHarness2(manifest.harness);
   }
-  const sp = de();
-  sp.start("Fetching agent…");
-  let cloudAgent;
-  let cloud;
-  try {
-    cloudAgent = await api.getAgent(manifest.id);
-    cloud = await api.getAgentManifest(manifest.id);
-    sp.stop(`Cloud revision ${cloud.revision}.`);
-  } catch (err) {
-    sp.stop("Failed.");
-    handleApiError5(err);
-    return;
-  }
   if (!args.yes) {
     const ok = await se({
-      message: `Install ${import_picocolors31.default.bold(cloudAgent.name)} as ${import_picocolors31.default.bold(harness)} here?`,
+      message: `Install ${import_picocolors31.default.bold(manifest.agent.name)} as ${import_picocolors31.default.bold(harness)} here?`,
       initialValue: true
     });
     if (!ensureNotCancelled(ok)) {
@@ -54005,46 +53991,206 @@ async function runAgentUnpack(cwd2, args) {
       return;
     }
   }
-  const prevLink = readLink(cwd2);
+  const scope = args.scope ?? "project";
+  const stageRoot = fs46.mkdtempSync(path50.join(os13.tmpdir(), "brainbase-unpack-"));
   try {
-    await installAgentFresh({
+    const toInstall = [];
+    const instructionsBody = readInstructions(cwd2, manifest);
+    if (instructionsBody && instructionsBody.trim()) {
+      const compDir = path50.join(stageRoot, "instruction", "agent-instructions");
+      ensureDir(compDir);
+      fs46.writeFileSync(path50.join(compDir, "instructions.md"), instructionsBody, "utf8");
+      toInstall.push({
+        type: "instruction",
+        slug: "agent-instructions",
+        scope,
+        rootDir: compDir,
+        description: "Agent instructions",
+        checksum: ""
+      });
+    }
+    for (const entry of manifest.playbooks ?? []) {
+      const issue = stageLocalPlaybook(entry, cwd2, stageRoot, scope, toInstall);
+      if (issue) {
+        f2.warn(issue);
+      }
+    }
+    for (const entry of manifest.skills ?? []) {
+      const issue = stageLocalSkill(entry.source, cwd2, stageRoot, scope, toInstall);
+      if (issue) {
+        f2.warn(issue);
+      }
+    }
+    for (const entry of manifest.mcp ?? []) {
+      const compDir = path50.join(stageRoot, "mcp", entry.name);
+      ensureDir(compDir);
+      const payload = {};
+      if (entry.url !== undefined)
+        payload.url = entry.url;
+      if (entry.command !== undefined)
+        payload.command = entry.command;
+      if (entry.args !== undefined)
+        payload.args = entry.args;
+      if (entry.env !== undefined)
+        payload.env = entry.env;
+      if (entry.headers !== undefined)
+        payload.headers = entry.headers;
+      payload.is_enabled = entry.is_enabled ?? true;
+      toInstall.push({
+        type: "mcp",
+        slug: entry.name,
+        scope,
+        rootDir: compDir,
+        payload,
+        checksum: ""
+      });
+    }
+    const haveOrchMcp = (manifest.mcp ?? []).some((m3) => m3.name === ORCHESTRATION_MCP_SLUG);
+    const haveMemoryMcp = (manifest.mcp ?? []).some((m3) => m3.name === MEMORY_MCP_SLUG);
+    if (!haveOrchMcp)
+      toInstall.push(buildOrchestrationMcpComponent(scope));
+    if (!haveMemoryMcp)
+      toInstall.push(buildMemoryMcpComponent(scope));
+    const opts = {
       cwd: cwd2,
-      agent: {
-        id: cloudAgent.id,
-        name: cloudAgent.name,
-        slug: cloudAgent.slug,
-        tagline: cloudAgent.tagline,
-        org_id: cloudAgent.org_id ?? prevLink?.org_id ?? "",
-        team_id: cloudAgent.team_id ?? prevLink?.team_id ?? "",
-        url: cloudAgent.url,
-        harness
-      },
-      cloud,
-      harness,
-      scope: args.scope ?? "project",
-      preserveManifest: true
-    });
+      scope,
+      resolveConflict: async (_c) => "overwrite",
+      resolveSecret: async () => null
+    };
+    const sp = de();
+    sp.start("Installing harness layout…");
+    const result = await runHarnessInstall3(harness, toInstall, opts, manifest.agent.name);
+    sp.stop("Installed.");
+    if (result.skipped.length) {
+      f2.warn(`Skipped: ${result.skipped.map((s3) => `${s3.type}/${s3.slug} (${s3.reason})`).join(", ")}`);
+    }
   } catch (err) {
     f2.error(`Install failed: ${err.message}`);
     return;
+  } finally {
+    try {
+      fs46.rmSync(stageRoot, { recursive: true, force: true });
+    } catch {}
   }
-  manifest = readManifest(cwd2);
   if (manifest.harness !== harness) {
     manifest.harness = harness;
     writeManifest(cwd2, manifest);
   }
-  $e(`Unpacked ${import_picocolors31.default.bold(cloudAgent.name)} as ${import_picocolors31.default.bold(harness)}.`);
+  $e(`Unpacked ${import_picocolors31.default.bold(manifest.agent.name)} as ${import_picocolors31.default.bold(harness)}.`);
   await showResultCard({
     title: "UNPACKED",
     tone: "ok",
-    subtitle: cloudAgent.name,
+    subtitle: manifest.agent.name,
     meta: [
       ["harness", harness],
-      ["agent", cloudAgent.id],
-      ...cloudAgent.url ? [["url", cloudAgent.url]] : []
+      ["agent", manifest.id]
     ]
   });
 }
+function stageLocalPlaybook(entry, cwd2, stageRoot, scope, toInstall) {
+  if (entry.content.text !== undefined && entry.content.file !== undefined) {
+    return `Playbook ${entry.title}: both text and file set — skipped.`;
+  }
+  const body = resolvePlaybookContent(cwd2, entry);
+  if (body === null) {
+    return entry.content.file ? `Playbook ${entry.title}: file ${entry.content.file} not found — skipped.` : `Playbook ${entry.title}: content empty — skipped.`;
+  }
+  const slug = slugifyPlaybookTitle(entry.title);
+  const compDir = path50.join(stageRoot, "playbook", slug);
+  ensureDir(compDir);
+  const wireBody = /^---\s*\n/.test(body) ? body : assembleFrontmatter(entry.title, entry.description) + body.replace(/^\n+/, "");
+  fs46.writeFileSync(path50.join(compDir, `${slug}.md`), wireBody, "utf8");
+  toInstall.push({
+    type: "playbook",
+    slug,
+    scope,
+    rootDir: compDir,
+    description: entry.description,
+    checksum: ""
+  });
+  return null;
+}
+function stageLocalSkill(source, cwd2, stageRoot, scope, toInstall) {
+  if (source.startsWith("./") || source.startsWith("../") || source.startsWith("/")) {
+    const abs = path50.resolve(cwd2, source);
+    if (!fs46.existsSync(abs)) {
+      return `Skill ${source}: not found on disk — skipped.`;
+    }
+    const slug = path50.basename(abs);
+    const compDir = path50.join(stageRoot, "skill", slug);
+    ensureDir(compDir);
+    copyDirRecursive(abs, compDir);
+    toInstall.push({
+      type: "skill",
+      slug,
+      scope,
+      rootDir: compDir,
+      checksum: ""
+    });
+    return null;
+  }
+  try {
+    const parsed = parseSkillSource(source);
+    if (parsed.type === "local" || parsed.type === "inline")
+      return null;
+    const slug = defaultSlugForSource(source);
+    const compDir = path50.join(stageRoot, "skill", slug);
+    ensureDir(compDir);
+    toInstall.push({
+      type: "skill",
+      slug,
+      scope,
+      rootDir: compDir,
+      source: parsed,
+      checksum: ""
+    });
+    return null;
+  } catch (err) {
+    return `Skill ${source}: ${err.message} — skipped.`;
+  }
+}
+function defaultSlugForSource(source) {
+  const reg = /^registry:(?:[a-z0-9_-]+\/)?([a-z0-9_-]+)/i.exec(source);
+  if (reg)
+    return reg[1].toLowerCase();
+  const gh = /^(?:github|git):[^/]*\/?([a-z0-9_-]+)/i.exec(source);
+  if (gh)
+    return gh[1].toLowerCase();
+  return source.replace(/[^a-z0-9_-]/gi, "-").slice(0, 60) || "skill";
+}
+function copyDirRecursive(src, dest) {
+  ensureDir(dest);
+  for (const entry of fs46.readdirSync(src, { withFileTypes: true })) {
+    const s3 = path50.join(src, entry.name);
+    const d3 = path50.join(dest, entry.name);
+    if (entry.isDirectory())
+      copyDirRecursive(s3, d3);
+    else if (entry.isFile())
+      fs46.copyFileSync(s3, d3);
+  }
+}
+function assembleFrontmatter(title, description) {
+  const lines = ["---", `title: ${yamlScalar2(title)}`];
+  if (description)
+    lines.push(`description: ${yamlScalar2(description)}`);
+  lines.push("---", "");
+  return lines.join(`
+`);
+}
+function yamlScalar2(s3) {
+  if (!/[\n":#&*!|>'%@`{}[\]]/.test(s3) && s3.trim() === s3 && s3 !== "")
+    return s3;
+  return JSON.stringify(s3);
+}
+function runHarnessInstall3(harnessId, components, opts, agentName) {
+  if (harnessId === "claude-code")
+    return installClaudeCodeWithCtx(components, opts, agentName);
+  if (harnessId === "codex")
+    return installCodexWithCtx(components, opts, agentName);
+  if (harnessId === "kafka")
+    return installKafkaWithCtx(components, opts, agentName);
+  return getAdapter(harnessId).install(components, opts);
+}
 async function pickHarness2(current) {
   const initial = current ? normalizeHarnessId(current) : undefined;
   const choice = await ie({
@@ -54058,19 +54204,6 @@ async function pickHarness2(current) {
   });
   return ensureNotCancelled(choice);
 }
-function handleApiError5(err) {
-  if (err instanceof ApiError) {
-    if (err.status === 401) {
-      f2.error("Your session is invalid. Run `brainbase login` and try again.");
-    } else if (err.status === 404) {
-      f2.error(`Agent not found, or you don't have access. The id in ${import_picocolors31.default.bold(AGENT_MANIFEST_FILE)} may be stale.`);
-    } else {
-      f2.error(err.message);
-    }
-  } else {
-    f2.error(err.message);
-  }
-}
 
 // src/cli/agent.ts
 async function runAgent(cwd2, sub, args, opts) {
@@ -54143,14 +54276,14 @@ function printHelp() {
 var import_picocolors37 = __toESM(require_picocolors(), 1);
 
 // src/cli/orchestration-pull.ts
-import path53 from "node:path";
-import fs49 from "node:fs";
+import path54 from "node:path";
+import fs50 from "node:fs";
 var import_picocolors33 = __toESM(require_picocolors(), 1);
 
 // src/core/orchestration-manifest.ts
 import path51 from "node:path";
 import fs47 from "node:fs";
-var import_yaml3 = __toESM(require_dist(), 1);
+var import_yaml4 = __toESM(require_dist(), 1);
 var ORCH_MANIFEST_FILE = "brainbase-orchestration.yaml";
 var ORCH_MEMBERS_DIR = "agents";
 var OrchMetaSchema = exports_external.object({
@@ -54189,7 +54322,7 @@ function readOrchManifest(cwd2) {
   const raw = fs47.readFileSync(p2, "utf8");
   let parsed;
   try {
-    parsed = import_yaml3.default.parse(raw);
+    parsed = import_yaml4.default.parse(raw);
   } catch (err) {
     throw new Error(`${ORCH_MANIFEST_FILE} is not valid YAML: ${err.message}`);
   }
@@ -54200,7 +54333,7 @@ function readOrchManifest(cwd2) {
   return result.data;
 }
 function writeOrchManifest(cwd2, manifest) {
-  const doc = new import_yaml3.default.Document;
+  const doc = new import_yaml4.default.Document;
   doc.contents = manifest;
   doc.commentBefore = ` brainbase-orchestration.yaml — declarative orchestration manifest.
 ` + ` Committed to source control. Edit by hand, then
@@ -54305,6 +54438,181 @@ function ensureGitignore2(cwd2) {
   } catch {}
 }
 
+// src/core/agent-fresh-install.ts
+import path53 from "node:path";
+import fs49 from "node:fs";
+import os14 from "node:os";
+async function installAgentFresh(input) {
+  const { cwd: cwd2, agent, cloud, harness } = input;
+  const scope = input.scope ?? "project";
+  ensureDir(cwd2);
+  const stageRoot = stageManifestComponents2(cloud.components);
+  const justInstalledPaths = new Map;
+  const cloudHasOrchestrationMcp = cloud.components.some((c2) => c2.type === "mcp" && c2.slug === ORCHESTRATION_MCP_SLUG);
+  const needOrchestrationMcpInstall = !cloudHasOrchestrationMcp;
+  const cloudHasMemoryMcp = cloud.components.some((c2) => c2.type === "mcp" && c2.slug === MEMORY_MCP_SLUG);
+  const needMemoryMcpInstall = !cloudHasMemoryMcp;
+  try {
+    if (cloud.components.length > 0 || needOrchestrationMcpInstall || needMemoryMcpInstall) {
+      const toInstall = cloud.components.map((c2) => ({
+        type: c2.type,
+        slug: c2.slug,
+        scope,
+        rootDir: path53.join(stageRoot, c2.type, c2.slug),
+        description: c2.description,
+        meta: c2.meta,
+        payload: c2.meta?.mcp,
+        checksum: c2.hash
+      }));
+      if (needOrchestrationMcpInstall) {
+        toInstall.push(buildOrchestrationMcpComponent(scope));
+      }
+      if (needMemoryMcpInstall) {
+        toInstall.push(buildMemoryMcpComponent(scope));
+      }
+      const installOpts = {
+        cwd: cwd2,
+        scope,
+        resolveConflict: async (_c) => "overwrite",
+        resolveSecret: async () => null
+      };
+      const result = await runHarnessInstall4(harness, toInstall, installOpts, agent.name);
+      for (const o2 of result.installed) {
+        justInstalledPaths.set(`${o2.type}/${o2.slug}`, o2.installedPaths);
+      }
+    }
+    materializeInstructions2(cwd2, cloud);
+    const manifest = input.preserveManifest ? null : buildManifestFromCloud(cloud, agent);
+    if (manifest)
+      writeManifest(cwd2, manifest);
+    writeLink(cwd2, {
+      schemaVersion: 1,
+      agent_id: agent.id,
+      org_id: agent.org_id,
+      team_id: agent.team_id,
+      slug: agent.slug,
+      name: agent.name,
+      tagline: agent.tagline,
+      url: agent.url,
+      linked_at: new Date().toISOString(),
+      harness
+    });
+    const syncedComponents = cloud.components.map((c2) => ({
+      type: c2.type,
+      slug: c2.slug,
+      hash: c2.hash,
+      installedPaths: justInstalledPaths.get(`${c2.type}/${c2.slug}`) ?? []
+    }));
+    writeSyncState(cwd2, {
+      schemaVersion: 1,
+      agent_id: agent.id,
+      revision: cloud.revision,
+      synced_at: new Date().toISOString(),
+      components: syncedComponents,
+      agentMeta: { name: agent.name, tagline: agent.tagline }
+    });
+    if (input.pullSecrets !== false) {
+      await pullAgentSecrets(cwd2, agent.id);
+    }
+    const returnedManifest = manifest ?? buildManifestFromCloud(cloud, agent);
+    return {
+      installedPaths: justInstalledPaths,
+      manifest: returnedManifest,
+      syncedComponents
+    };
+  } finally {
+    try {
+      fs49.rmSync(stageRoot, { recursive: true, force: true });
+    } catch {}
+  }
+}
+function stageManifestComponents2(components) {
+  const root = fs49.mkdtempSync(path53.join(os14.tmpdir(), "brainbase-orch-pull-"));
+  for (const c2 of components) {
+    const compDir = path53.join(root, c2.type, c2.slug);
+    ensureDir(compDir);
+    for (const f4 of c2.files) {
+      const target = path53.join(compDir, f4.path);
+      ensureDir(path53.dirname(target));
+      fs49.writeFileSync(target, f4.content);
+    }
+  }
+  return root;
+}
+function runHarnessInstall4(harnessId, components, opts, agentName) {
+  if (harnessId === "claude-code")
+    return installClaudeCodeWithCtx(components, opts, agentName);
+  if (harnessId === "codex")
+    return installCodexWithCtx(components, opts, agentName);
+  if (harnessId === "kafka")
+    return installKafkaWithCtx(components, opts, agentName);
+  return getAdapter(harnessId).install(components, opts);
+}
+function materializeInstructions2(cwd2, cloud) {
+  for (const c2 of cloud.components) {
+    if (c2.type !== "instruction")
+      continue;
+    const body = c2.files[0]?.content ?? "";
+    if (!body.trim())
+      continue;
+    fs49.writeFileSync(path53.join(cwd2, DEFAULT_INSTRUCTIONS_FILE), body, "utf8");
+    return;
+  }
+}
+function buildManifestFromCloud(cloud, agent) {
+  const skills = cloud.components.filter((c2) => c2.type === "skill").map((c2) => {
+    const meta = c2.meta ?? {};
+    if (meta.name && meta.name.includes("/")) {
+      return {
+        source: meta.version ? `registry:${meta.name}@${meta.version}` : `registry:${meta.name}`
+      };
+    }
+    return { source: `registry:${c2.slug}` };
+  });
+  const hasInstructions = cloud.components.some((c2) => c2.type === "instruction" && c2.files[0]?.content?.trim());
+  const mcp = cloud.components.filter((c2) => c2.type === "mcp").map((c2) => {
+    const payload = (c2.meta ?? {}).mcp ?? {};
+    const entry = { name: c2.slug };
+    if (typeof payload.url === "string")
+      entry.url = payload.url;
+    if (typeof payload.command === "string")
+      entry.command = payload.command;
+    if (Array.isArray(payload.args))
+      entry.args = payload.args.map(String);
+    if (payload.env && typeof payload.env === "object")
+      entry.env = payload.env;
+    if (payload.headers && typeof payload.headers === "object")
+      entry.headers = payload.headers;
+    if (typeof payload.is_enabled === "boolean")
+      entry.is_enabled = payload.is_enabled;
+    return entry;
+  });
+  return {
+    schema: 1,
+    agent: {
+      name: agent.name,
+      ...agent.tagline ? { tagline: agent.tagline } : {}
+    },
+    ...hasInstructions ? { instructions: { file: DEFAULT_INSTRUCTIONS_FILE } } : {},
+    playbooks: [],
+    skills,
+    mcp
+  };
+}
+async function pullAgentSecrets(cwd2, agentId) {
+  try {
+    const res = await api.getAgentSecrets(agentId);
+    const secrets = res.secrets ?? {};
+    if (Object.keys(secrets).length > 0) {
+      writeLocalSecrets(cwd2, secrets);
+    }
+  } catch (err) {
+    if (err instanceof ApiError && err.status !== 404) {
+      f2.warn(`Skipped secrets for agent ${agentId}: ${err.message}`);
+    }
+  }
+}
+
 // src/cli/orchestration-pull.ts
 async function runOrchestrationPull(cwd2, args) {
   banner("orchestration pull — fetch orchestration + all member agents");
@@ -54328,7 +54636,7 @@ async function runOrchestrationPull(cwd2, args) {
     sp.stop(`Cloud revision ${cloud.revision} — ${cloud.members.length} member${cloud.members.length === 1 ? "" : "s"}, ${cloud.edges.length} edge${cloud.edges.length === 1 ? "" : "s"}.`);
   } catch (err) {
     sp.stop("Failed.");
-    handleApiError6(err);
+    handleApiError5(err);
     return;
   }
   const planLines = [];
@@ -54368,7 +54676,7 @@ async function runOrchestrationPull(cwd2, args) {
     }
   }
   const fallbackHarness = args.harness ?? "claude-code";
-  fs49.mkdirSync(cwd2, { recursive: true });
+  fs50.mkdirSync(cwd2, { recursive: true });
   if (hasOrchManifest(cwd2) && existingLink && existingLink.orchestration_id !== orchId) {
     f2.error(`This folder is linked to orchestration ${existingLink.orchestration_id}, not ${orchId}. Move to a fresh directory or unlink first.`);
     return;
@@ -54455,9 +54763,9 @@ async function runOrchestrationPull(cwd2, args) {
       payload_schema: e2.payload_schema ?? {}
     }))
   });
-  $e(`Pulled ${cloud.name} at revision ${cloud.revision} into ${path53.basename(cwd2)}/ ${import_picocolors33.default.dim(`(${installedMembers.length}/${cloud.members.length} members)`)}.`);
+  $e(`Pulled ${cloud.name} at revision ${cloud.revision} into ${path54.basename(cwd2)}/ ${import_picocolors33.default.dim(`(${installedMembers.length}/${cloud.members.length} members)`)}.`);
 }
-function handleApiError6(err) {
+function handleApiError5(err) {
   if (err instanceof ApiError) {
     if (err.status === 401) {
       f2.error("Your session is invalid. Run `brainbase login` and try again.");
@@ -54602,10 +54910,10 @@ async function runOrchestrationPush(cwd2, args) {
     $e(`Pushed ${link2.name} at revision ${updated.revision}.`);
   } catch (err) {
     sp.stop("Failed.");
-    handleApiError7(err);
+    handleApiError6(err);
   }
 }
-function handleApiError7(err) {
+function handleApiError6(err) {
   if (err instanceof ApiError) {
     if (err.status === 401) {
       f2.error("Your session is invalid. Run `brainbase login` and try again.");
@@ -54736,7 +55044,7 @@ async function runOrchestrationList(args) {
     try {
       orgs = await api.listOrgs();
     } catch (err) {
-      handleApiError8(err);
+      handleApiError7(err);
       return;
     }
     if (orgs.length === 0) {
@@ -54758,7 +55066,7 @@ async function runOrchestrationList(args) {
     try {
       teams = await api.listTeams(orgId);
     } catch (err) {
-      handleApiError8(err);
+      handleApiError7(err);
       return;
     }
     if (teams.length === 0) {
@@ -54783,7 +55091,7 @@ async function runOrchestrationList(args) {
     sp.stop(`${items.length} orchestration${items.length === 1 ? "" : "s"}.`);
   } catch (err) {
     sp.stop("Failed.");
-    handleApiError8(err);
+    handleApiError7(err);
     return;
   }
   if (items.length === 0) {
@@ -54803,7 +55111,7 @@ async function runOrchestrationList(args) {
   console.log(lines.join(`
 `));
 }
-function handleApiError8(err) {
+function handleApiError7(err) {
   if (err instanceof ApiError) {
     if (err.status === 401) {
       f2.error("Your session is invalid. Run `brainbase login` and try again.");
@@ -55608,7 +55916,7 @@ var PROTECTED = new Set([
 function help() {
   const out = [];
   out.push("");
-  out.push(`  ${brandTint("◆")}  ${import_picocolors40.default.bold("brainbase")}  ${import_picocolors40.default.dim("v0.5.0")}`);
+  out.push(`  ${brandTint("◆")}  ${import_picocolors40.default.bold("brainbase")}  ${import_picocolors40.default.dim("v0.6.0")}`);
   out.push(`     ${import_picocolors40.default.dim("connect your local agent to the brainbase platform")}`);
   out.push("");
   out.push(divider("USAGE"));
@@ -55751,7 +56059,7 @@ async function main() {
   const rawCwd = process13.cwd();
   const cwd2 = (() => {
     try {
-      return fs50.realpathSync(rawCwd);
+      return fs51.realpathSync(rawCwd);
     } catch {
       return rawCwd;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainbase-labs/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pack, share, and install agent templates across harnesses (Claude Code, Codex, ...).",
   "type": "module",
   "bin": {