@brainbase-labs/cli 0.2.3 → 0.2.4

package/dist/index.js

@@ -2,8 +2,8 @@
 
 // src/index.ts
 import process2 from "node:process";
-import fs40 from "node:fs";
-import pc31 from "picocolors";
+import fs44 from "node:fs";
+import pc36 from "picocolors";
 
 // src/cli/template.ts
 import pc10 from "picocolors";
@@ -398,11 +398,13 @@ function globalPaths() {
     agents: path4.join(GLOBAL_ROOT, "agents"),
     settings: path4.join(GLOBAL_ROOT, "settings.json"),
     claudeMd: path4.join(GLOBAL_ROOT, "CLAUDE.md"),
-    userClaudeJson: USER_CLAUDE_JSON
+    userClaudeJson: USER_CLAUDE_JSON,
+    mcpStore: USER_CLAUDE_JSON
   };
 }
 function projectPaths(cwd) {
   const root = projectRoot(cwd);
+  const mcpJson = projectMcpJson(cwd);
   return {
     root,
     skills: path4.join(root, "skills"),
@@ -410,8 +412,9 @@ function projectPaths(cwd) {
     agents: path4.join(root, "agents"),
     settings: path4.join(root, "settings.json"),
     claudeMd: path4.join(cwd, "CLAUDE.md"),
-    mcpJson: projectMcpJson(cwd),
-    userClaudeJson: USER_CLAUDE_JSON
+    mcpJson,
+    userClaudeJson: USER_CLAUDE_JSON,
+    mcpStore: mcpJson
   };
 }
 function scopePaths(cwd, scope) {
@@ -491,10 +494,6 @@ function readSettings(file) {
 function writeSettings(file, settings) {
   writeJson(file, settings);
 }
-function ensureSettings(file) {
-  if (!exists(file))
-    writeSettings(file, {});
-}
 function setMcpServer(file, name, entry) {
   const s = readSettings(file);
   if (!s.mcpServers)
@@ -518,6 +517,33 @@ function getMcpServer(file, name) {
 function listMcpServers(file) {
   return readSettings(file).mcpServers ?? {};
 }
+function normalizeMcpPayload(payload) {
+  const out = { ...payload };
+  delete out.is_enabled;
+  const hasUrl = typeof out.url === "string" && out.url.length > 0;
+  const hasCommand = typeof out.command === "string" && out.command.length > 0;
+  if (!out.type) {
+    if (hasUrl)
+      out.type = "http";
+    else if (hasCommand)
+      out.type = "stdio";
+  }
+  if (out.type === "http" || out.type === "sse") {
+    if (Array.isArray(out.args) && out.args.length === 0)
+      delete out.args;
+    if (out.env && typeof out.env === "object" && Object.keys(out.env).length === 0) {
+      delete out.env;
+    }
+    if (out.headers && typeof out.headers === "object" && Object.keys(out.headers).length === 0) {
+      delete out.headers;
+    }
+  }
+  if (out.type === "stdio") {
+    delete out.url;
+    delete out.headers;
+  }
+  return out;
+}
 function listMcpServersFromMcpJson(file) {
   return readJsonOr(file, {}).mcpServers ?? {};
 }
@@ -1028,14 +1054,13 @@ async function installAgent(comp, opts) {
   return installSingleFileComponent(comp, agents, `${comp.slug}.md`, opts);
 }
 async function installMcp(comp, opts, ctx) {
-  const { settings } = scopePaths(opts.cwd, opts.scope);
-  ensureSettings(settings);
-  const existing = getMcpServer(settings, comp.slug);
+  const { mcpStore } = scopePaths(opts.cwd, opts.scope);
+  const existing = getMcpServer(mcpStore, comp.slug);
   if (existing) {
     const choice = await opts.resolveConflict({
       type: "mcp",
       slug: comp.slug,
-      existingPath: settings
+      existingPath: mcpStore
     });
     if (choice === "skip")
       return { skip: "user skipped existing mcp" };
@@ -1064,15 +1089,15 @@ async function installMcp(comp, opts, ctx) {
       }
     }
   }
-  setMcpServer(settings, comp.slug, payload);
+  setMcpServer(mcpStore, comp.slug, normalizeMcpPayload(payload));
   return {
     type: "mcp",
     slug: comp.slug,
-    installedPaths: [settings],
+    installedPaths: [mcpStore],
     sourceChecksum: comp.checksum,
     scope: opts.scope,
     embeddedKey: comp.slug,
-    settingsFile: settings
+    settingsFile: mcpStore
   };
 }
 async function installInstruction(comp, opts, ctx) {
@@ -1296,8 +1321,8 @@ async function diffClaudeCode(components, opts) {
         break;
       }
       case "mcp": {
-        if (exists(sp.settings)) {
-          const servers = listMcpServers(sp.settings);
+        if (exists(sp.mcpStore)) {
+          const servers = listMcpServers(sp.mcpStore);
           const cur = servers[comp.slug];
           if (cur)
             installedChecksum = sha256(JSON.stringify(cur));
@@ -2880,6 +2905,21 @@ var api = {
     return request(`/api/cli/keys/${encodeURIComponent(keyId)}`, {
       method: "DELETE"
     });
+  },
+  listOrchestrations(orgId, teamId) {
+    return request(`/api/cli/orgs/${encodeURIComponent(orgId)}/teams/${encodeURIComponent(teamId)}/orchestrations`);
+  },
+  getOrchestration(orchId) {
+    return request(`/api/cli/orchestrations/${encodeURIComponent(orchId)}`);
+  },
+  getOrchestrationManifest(orchId) {
+    return request(`/api/cli/orchestrations/${encodeURIComponent(orchId)}/manifest`);
+  },
+  updateOrchestration(orchId, input) {
+    return request(`/api/cli/orchestrations/${encodeURIComponent(orchId)}`, {
+      method: "PUT",
+      body: JSON.stringify(input)
+    });
   }
 };
 function proxyBaseUrl(session) {
@@ -9310,6 +9350,906 @@ function printHelp() {
 `));
 }
 
+// src/cli/orchestration.ts
+import pc33 from "picocolors";
+
+// src/cli/orchestration-pull.ts
+import path46 from "node:path";
+import fs43 from "node:fs";
+import * as p21 from "@clack/prompts";
+import pc29 from "picocolors";
+
+// src/core/orchestration-manifest.ts
+import path43 from "node:path";
+import fs40 from "node:fs";
+import { z as z8 } from "zod";
+import YAML2 from "yaml";
+var ORCH_MANIFEST_FILE = "brainbase-orchestration.yaml";
+var ORCH_MEMBERS_DIR = "agents";
+var OrchMetaSchema = z8.object({
+  name: z8.string().min(1),
+  description: z8.string().optional(),
+  icon: z8.string().optional(),
+  icon_color: z8.string().optional(),
+  credit_limit: z8.number().optional()
+});
+var MemberSchema = z8.object({
+  slug: z8.string().min(1),
+  name: z8.string().optional()
+});
+var EdgeSchema = z8.object({
+  from: z8.string().min(1),
+  to: z8.string().min(1),
+  description: z8.string().optional(),
+  payload_schema: z8.record(z8.unknown()).optional()
+});
+var OrchestrationManifestSchema = z8.object({
+  schema: z8.literal(1),
+  orchestration: OrchMetaSchema,
+  members: z8.array(MemberSchema).default([]),
+  edges: z8.array(EdgeSchema).default([])
+});
+function orchManifestPath(cwd) {
+  return path43.join(cwd, ORCH_MANIFEST_FILE);
+}
+function hasOrchManifest(cwd) {
+  return fs40.existsSync(orchManifestPath(cwd));
+}
+function readOrchManifest(cwd) {
+  const p20 = orchManifestPath(cwd);
+  if (!fs40.existsSync(p20))
+    return null;
+  const raw = fs40.readFileSync(p20, "utf8");
+  let parsed;
+  try {
+    parsed = YAML2.parse(raw);
+  } catch (err) {
+    throw new Error(`${ORCH_MANIFEST_FILE} is not valid YAML: ${err.message}`);
+  }
+  const result = OrchestrationManifestSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new Error(`${ORCH_MANIFEST_FILE} is invalid: ${result.error.issues.map((i) => `${i.path.join(".") || "(root)"} — ${i.message}`).join("; ")}`);
+  }
+  return result.data;
+}
+function writeOrchManifest(cwd, manifest) {
+  const doc = new YAML2.Document;
+  doc.contents = manifest;
+  doc.commentBefore = ` brainbase-orchestration.yaml — declarative orchestration manifest.
+` + ` Committed to source control. Edit by hand, then
+` + " `brainbase orchestration push`. Member agents live under ./agents/.";
+  fs40.writeFileSync(orchManifestPath(cwd), String(doc), "utf8");
+}
+function memberDir(cwd, slug) {
+  return path43.join(cwd, ORCH_MEMBERS_DIR, slug);
+}
+
+// src/core/orchestration-link.ts
+import path44 from "node:path";
+import fs41 from "node:fs";
+import { z as z9 } from "zod";
+var ORCH_LINK_FILE = "orchestration-link.json";
+var ORCH_SYNC_STATE_FILE = "orchestration-sync-state.json";
+var OrchestrationLinkSchema = z9.object({
+  schemaVersion: z9.literal(1),
+  orchestration_id: z9.string(),
+  group_id: z9.string(),
+  org_id: z9.string(),
+  team_id: z9.string(),
+  name: z9.string(),
+  description: z9.string().nullish().transform((v) => v ?? undefined),
+  linked_at: z9.string(),
+  linked_by: z9.string().nullish().transform((v) => v ?? undefined)
+});
+var SyncedMemberSchema = z9.object({
+  agent_id: z9.string(),
+  slug: z9.string(),
+  revision: z9.number()
+});
+var SyncedEdgeSchema = z9.object({
+  from_slug: z9.string(),
+  to_slug: z9.string(),
+  description: z9.string().default(""),
+  payload_schema: z9.record(z9.unknown()).default({})
+});
+var OrchestrationSyncStateSchema = z9.object({
+  schemaVersion: z9.literal(1),
+  orchestration_id: z9.string(),
+  revision: z9.number(),
+  synced_at: z9.string(),
+  members: z9.array(SyncedMemberSchema),
+  edges: z9.array(SyncedEdgeSchema)
+});
+function orchLinkPath(cwd) {
+  return path44.join(cwd, LINK_DIR, ORCH_LINK_FILE);
+}
+function orchSyncStatePath(cwd) {
+  return path44.join(cwd, LINK_DIR, ORCH_SYNC_STATE_FILE);
+}
+function readOrchLink(cwd) {
+  const p20 = orchLinkPath(cwd);
+  if (!exists(p20))
+    return null;
+  try {
+    return OrchestrationLinkSchema.parse(readJson(p20));
+  } catch {
+    return null;
+  }
+}
+function writeOrchLink(cwd, link) {
+  ensureDir(path44.join(cwd, LINK_DIR));
+  const clean = {};
+  for (const [k, v] of Object.entries(link)) {
+    if (v !== null && v !== undefined)
+      clean[k] = v;
+  }
+  writeJson(orchLinkPath(cwd), clean);
+  ensureGitignore2(cwd);
+}
+function readOrchSyncState(cwd) {
+  const p20 = orchSyncStatePath(cwd);
+  if (!exists(p20))
+    return null;
+  try {
+    return OrchestrationSyncStateSchema.parse(readJson(p20));
+  } catch {
+    return null;
+  }
+}
+function writeOrchSyncState(cwd, state) {
+  ensureDir(path44.join(cwd, LINK_DIR));
+  writeJson(orchSyncStatePath(cwd), state);
+  ensureGitignore2(cwd);
+}
+function ensureGitignore2(cwd) {
+  const ignorePath = path44.join(cwd, LINK_DIR, ".gitignore");
+  const desired = `${ORCH_SYNC_STATE_FILE}
+`;
+  try {
+    if (!exists(ignorePath)) {
+      fs41.writeFileSync(ignorePath, desired);
+      return;
+    }
+    const current = fs41.readFileSync(ignorePath, "utf8");
+    if (!current.split(/\r?\n/).some((l) => l.trim() === ORCH_SYNC_STATE_FILE)) {
+      fs41.writeFileSync(ignorePath, current.endsWith(`
+`) ? current + desired : current + `
+` + desired);
+    }
+  } catch {}
+}
+
+// src/core/agent-fresh-install.ts
+import path45 from "node:path";
+import fs42 from "node:fs";
+import os10 from "node:os";
+import * as p20 from "@clack/prompts";
+async function installAgentFresh(input) {
+  const { cwd, agent, cloud, harness } = input;
+  const scope = input.scope ?? "project";
+  ensureDir(cwd);
+  const stageRoot = stageManifestComponents2(cloud.components);
+  const justInstalledPaths = new Map;
+  try {
+    if (cloud.components.length > 0) {
+      const toInstall = cloud.components.map((c) => ({
+        type: c.type,
+        slug: c.slug,
+        scope,
+        rootDir: path45.join(stageRoot, c.type, c.slug),
+        description: c.description,
+        meta: c.meta,
+        payload: c.meta?.mcp,
+        checksum: c.hash
+      }));
+      const installOpts = {
+        cwd,
+        scope,
+        resolveConflict: async (_c) => "overwrite",
+        resolveSecret: async () => null
+      };
+      const result = await runHarnessInstall3(harness, toInstall, installOpts, agent.name);
+      for (const o of result.installed) {
+        justInstalledPaths.set(`${o.type}/${o.slug}`, o.installedPaths);
+      }
+    }
+    materializeInstructions2(cwd, cloud);
+    const manifest = buildManifestFromCloud(cloud, agent);
+    writeManifest(cwd, manifest);
+    writeLink(cwd, {
+      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((c) => ({
+      type: c.type,
+      slug: c.slug,
+      hash: c.hash,
+      installedPaths: justInstalledPaths.get(`${c.type}/${c.slug}`) ?? []
+    }));
+    writeSyncState(cwd, {
+      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(cwd, agent.id);
+    }
+    return {
+      installedPaths: justInstalledPaths,
+      manifest,
+      syncedComponents
+    };
+  } finally {
+    try {
+      fs42.rmSync(stageRoot, { recursive: true, force: true });
+    } catch {}
+  }
+}
+function stageManifestComponents2(components) {
+  const root = fs42.mkdtempSync(path45.join(os10.tmpdir(), "brainbase-orch-pull-"));
+  for (const c of components) {
+    const compDir = path45.join(root, c.type, c.slug);
+    ensureDir(compDir);
+    for (const f of c.files) {
+      const target = path45.join(compDir, f.path);
+      ensureDir(path45.dirname(target));
+      fs42.writeFileSync(target, f.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);
+  return getAdapter(harnessId).install(components, opts);
+}
+function materializeInstructions2(cwd, cloud) {
+  for (const c of cloud.components) {
+    if (c.type !== "instruction")
+      continue;
+    const body = c.files[0]?.content ?? "";
+    if (!body.trim())
+      continue;
+    fs42.writeFileSync(path45.join(cwd, DEFAULT_INSTRUCTIONS_FILE), body, "utf8");
+    return;
+  }
+}
+function buildManifestFromCloud(cloud, agent) {
+  const skills = cloud.components.filter((c) => c.type === "skill").map((c) => {
+    const meta = c.meta ?? {};
+    if (meta.name && meta.name.includes("/")) {
+      return {
+        source: meta.version ? `registry:${meta.name}@${meta.version}` : `registry:${meta.name}`
+      };
+    }
+    return { source: `registry:${c.slug}` };
+  });
+  const hasInstructions = cloud.components.some((c) => c.type === "instruction" && c.files[0]?.content?.trim());
+  const mcp = cloud.components.filter((c) => c.type === "mcp").map((c) => {
+    const payload = (c.meta ?? {}).mcp ?? {};
+    const entry = { name: c.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(cwd, agentId) {
+  try {
+    const res = await api.getAgentSecrets(agentId);
+    const secrets = res.secrets ?? {};
+    if (Object.keys(secrets).length > 0) {
+      writeLocalSecrets(cwd, secrets);
+    }
+  } catch (err) {
+    if (err instanceof ApiError && err.status !== 404) {
+      p20.log.warn(`Skipped secrets for agent ${agentId}: ${err.message}`);
+    }
+  }
+}
+
+// src/cli/orchestration-pull.ts
+async function runOrchestrationPull(cwd, args) {
+  banner("orchestration pull — fetch orchestration + all member agents");
+  let orchId = null;
+  const existingLink = readOrchLink(cwd);
+  if (existingLink) {
+    orchId = existingLink.orchestration_id;
+  } else if (args.orchestrationId) {
+    orchId = args.orchestrationId;
+  } else {
+    p21.log.warn("This folder is not linked to any orchestration.");
+    p21.log.info(`Run ${pc29.cyan("brainbase orchestration pull <id>")} with an orchestration id,
+  or ${pc29.cyan("brainbase orchestration list")} to find one.`);
+    return;
+  }
+  const sp = p21.spinner();
+  sp.start(`Fetching orchestration ${orchId}…`);
+  let cloud;
+  try {
+    cloud = await api.getOrchestrationManifest(orchId);
+    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.");
+    handleApiError5(err);
+    return;
+  }
+  const planLines = [];
+  planLines.push("");
+  planLines.push(`  ${pc29.bold(cloud.name)} ${pc29.dim(`(${cloud.id})`)}`);
+  if (cloud.description)
+    planLines.push(`  ${pc29.dim(cloud.description)}`);
+  planLines.push("");
+  planLines.push(`  ${pc29.dim("members:")}`);
+  for (const m of cloud.members) {
+    const skipped = !m.manifest;
+    const tail = skipped ? pc29.red(" (manifest unavailable — skipped)") : "";
+    planLines.push(`    ${pc29.cyan("•")} ${pc29.bold(m.slug)} ${pc29.dim(`(${m.name})`)}${tail}`);
+  }
+  if (cloud.edges.length) {
+    planLines.push("");
+    planLines.push(`  ${pc29.dim("edges:")}`);
+    for (const e of cloud.edges) {
+      const from = e.from_slug ?? e.from_agent_id;
+      const to = e.to_slug ?? e.to_agent_id;
+      const desc = e.description ? `  ${pc29.dim("— " + e.description)}` : "";
+      planLines.push(`    ${pc29.cyan(from)} ${pc29.dim("→")} ${pc29.cyan(to)}${desc}`);
+    }
+  }
+  planLines.push("");
+  console.log(planLines.join(`
+`));
+  const isRefresh = !!existingLink;
+  if (!args.yes && !isRefresh) {
+    const ok = await p21.confirm({
+      message: `Pull into ${pc29.bold(cwd)}?`,
+      initialValue: true
+    });
+    if (!ensureNotCancelled(ok)) {
+      p21.outro("Aborted.");
+      return;
+    }
+  }
+  const fallbackHarness = args.harness ?? "claude-code";
+  fs43.mkdirSync(cwd, { recursive: true });
+  if (hasOrchManifest(cwd) && existingLink && existingLink.orchestration_id !== orchId) {
+    p21.log.error(`This folder is linked to orchestration ${existingLink.orchestration_id}, not ${orchId}. Move to a fresh directory or unlink first.`);
+    return;
+  }
+  const installedMembers = [];
+  for (const m of cloud.members) {
+    if (!m.manifest) {
+      p21.log.warn(`Skipping member ${m.slug}: server did not return a manifest.`);
+      continue;
+    }
+    const dest = memberDir(cwd, m.slug);
+    const memberSp = p21.spinner();
+    memberSp.start(`Installing ${m.slug}…`);
+    try {
+      await installAgentFresh({
+        cwd: dest,
+        agent: {
+          id: m.agent_id,
+          name: m.name || m.slug,
+          slug: m.slug,
+          tagline: undefined,
+          org_id: cloud.group_id,
+          team_id: cloud.group_id,
+          url: undefined,
+          harness: fallbackHarness
+        },
+        cloud: m.manifest,
+        harness: fallbackHarness,
+        scope: "project",
+        pullSecrets: true
+      });
+      memberSp.stop(`Installed ${pc29.bold(m.slug)} ${pc29.dim(`(${m.manifest.components.length} components)`)}.`);
+      installedMembers.push({
+        agent_id: m.agent_id,
+        slug: m.slug,
+        revision: m.manifest.revision
+      });
+    } catch (err) {
+      memberSp.stop(`Failed to install ${m.slug}.`);
+      p21.log.error(err.message);
+    }
+  }
+  const manifest = {
+    schema: 1,
+    orchestration: {
+      name: cloud.name,
+      ...cloud.description ? { description: cloud.description } : {},
+      ...cloud.icon ? { icon: cloud.icon } : {},
+      ...cloud.icon_color ? { icon_color: cloud.icon_color } : {},
+      ...cloud.credit_limit != null ? { credit_limit: cloud.credit_limit } : {}
+    },
+    members: cloud.members.map((m) => ({
+      slug: m.slug,
+      ...m.name && m.name !== m.slug ? { name: m.name } : {}
+    })),
+    edges: cloud.edges.map((e) => ({
+      from: e.from_slug ?? e.from_agent_id,
+      to: e.to_slug ?? e.to_agent_id,
+      ...e.description ? { description: e.description } : {},
+      ...e.payload_schema && Object.keys(e.payload_schema).length ? { payload_schema: e.payload_schema } : {}
+    }))
+  };
+  writeOrchManifest(cwd, manifest);
+  writeOrchLink(cwd, {
+    schemaVersion: 1,
+    orchestration_id: cloud.id,
+    group_id: cloud.group_id,
+    org_id: cloud.group_id,
+    team_id: cloud.group_id,
+    name: cloud.name,
+    description: cloud.description || undefined,
+    linked_at: new Date().toISOString()
+  });
+  writeOrchSyncState(cwd, {
+    schemaVersion: 1,
+    orchestration_id: cloud.id,
+    revision: cloud.revision,
+    synced_at: new Date().toISOString(),
+    members: installedMembers,
+    edges: cloud.edges.map((e) => ({
+      from_slug: e.from_slug ?? e.from_agent_id,
+      to_slug: e.to_slug ?? e.to_agent_id,
+      description: e.description ?? "",
+      payload_schema: e.payload_schema ?? {}
+    }))
+  });
+  p21.outro(`Pulled ${cloud.name} at revision ${cloud.revision} into ${path46.basename(cwd)}/ ${pc29.dim(`(${installedMembers.length}/${cloud.members.length} members)`)}.`);
+}
+function handleApiError5(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 401) {
+      p21.log.error("Your session is invalid. Run `brainbase login` and try again.");
+    } else if (err.status === 403) {
+      p21.log.error("You do not have access to this orchestration. Ask the team owner to grant you access via `group_memberships`.");
+    } else {
+      p21.log.error(err.message);
+    }
+  } else {
+    p21.log.error(err.message);
+  }
+}
+
+// src/cli/orchestration-push.ts
+import * as p22 from "@clack/prompts";
+import pc30 from "picocolors";
+async function runOrchestrationPush(cwd, args) {
+  banner("orchestration push — recursively push each member, then update the graph");
+  const link = readOrchLink(cwd);
+  if (!link) {
+    p22.log.warn("This folder is not linked to any orchestration.");
+    p22.log.info(`Run ${pc30.cyan("brainbase orchestration pull <id>")} first.`);
+    return;
+  }
+  if (!hasOrchManifest(cwd)) {
+    p22.log.warn(`No ${pc30.bold(ORCH_MANIFEST_FILE)} here.`);
+    p22.log.info(`Run ${pc30.cyan("brainbase orchestration pull")} to materialise the manifest before pushing.`);
+    return;
+  }
+  let manifest;
+  try {
+    manifest = readOrchManifest(cwd);
+  } catch (err) {
+    p22.log.error(err.message);
+    return;
+  }
+  const memberSlugs = new Set(manifest.members.map((m) => m.slug));
+  for (const e of manifest.edges) {
+    if (!memberSlugs.has(e.from)) {
+      p22.log.error(`Edge from "${pc30.bold(e.from)}" references a slug that isn't in members.`);
+      return;
+    }
+    if (!memberSlugs.has(e.to)) {
+      p22.log.error(`Edge to "${pc30.bold(e.to)}" references a slug that isn't in members.`);
+      return;
+    }
+    if (e.from === e.to) {
+      p22.log.error(`Edge ${pc30.bold(e.from)} → ${pc30.bold(e.to)}: self-loops are not allowed.`);
+      return;
+    }
+  }
+  const slugToAgentId = new Map;
+  const missing = [];
+  for (const m of manifest.members) {
+    const dir = memberDir(cwd, m.slug);
+    const memberLink = readLink(dir);
+    if (!memberLink) {
+      missing.push(m.slug);
+      continue;
+    }
+    slugToAgentId.set(m.slug, memberLink.agent_id);
+  }
+  if (missing.length) {
+    p22.log.error(`These members have no local checkout (expected at agents/<slug>/.brainbase/link.json): ${missing.join(", ")}.`);
+    p22.log.info(`Run ${pc30.cyan("brainbase orchestration pull")} to materialise the missing folders.`);
+    return;
+  }
+  const plan = [""];
+  plan.push(`  ${pc30.bold(link.name)} ${pc30.dim(`(${link.orchestration_id})`)}`);
+  plan.push(`  ${pc30.dim(`${manifest.members.length} member${manifest.members.length === 1 ? "" : "s"}, ${manifest.edges.length} edge${manifest.edges.length === 1 ? "" : "s"}`)}`);
+  plan.push("");
+  if (!args.graphOnly) {
+    plan.push(`  ${pc30.dim("per-member agent push:")}`);
+    for (const m of manifest.members) {
+      plan.push(`    ${pc30.cyan("•")} ${pc30.bold(m.slug)}`);
+    }
+    plan.push("");
+  }
+  console.log(plan.join(`
+`));
+  if (!args.yes) {
+    const ok = await p22.confirm({
+      message: args.graphOnly ? "Push graph (members + edges) only?" : "Push each member, then update the graph?",
+      initialValue: true
+    });
+    if (!ensureNotCancelled(ok)) {
+      p22.outro("Aborted.");
+      return;
+    }
+  }
+  if (!args.graphOnly) {
+    for (const m of manifest.members) {
+      const dir = memberDir(cwd, m.slug);
+      console.log("");
+      console.log(`${pc30.dim("───")} ${pc30.bold(m.slug)} ${pc30.dim("───")}`);
+      try {
+        await runAgentPush(dir, { yes: true });
+      } catch (err) {
+        p22.log.error(`Failed to push ${m.slug}: ${err.message}`);
+        return;
+      }
+    }
+  }
+  const memberIds = manifest.members.map((m) => slugToAgentId.get(m.slug));
+  const edges = manifest.edges.map((e) => ({
+    from_agent_id: slugToAgentId.get(e.from),
+    to_agent_id: slugToAgentId.get(e.to),
+    description: e.description ?? "",
+    payload_schema: e.payload_schema ?? {}
+  }));
+  const sp = p22.spinner();
+  sp.start("Updating orchestration graph…");
+  const lock = readOrchSyncState(cwd);
+  try {
+    const updated = await api.updateOrchestration(link.orchestration_id, {
+      name: manifest.orchestration.name,
+      description: manifest.orchestration.description ?? "",
+      icon: manifest.orchestration.icon,
+      icon_color: manifest.orchestration.icon_color,
+      credit_limit: manifest.orchestration.credit_limit,
+      members: memberIds,
+      edges,
+      ...lock?.revision != null ? { base_revision: lock.revision } : {}
+    });
+    sp.stop(`Graph updated. New cloud revision ${updated.revision}.`);
+    writeOrchSyncState(cwd, {
+      schemaVersion: 1,
+      orchestration_id: updated.id,
+      revision: updated.revision,
+      synced_at: new Date().toISOString(),
+      members: updated.members.map((m) => ({
+        agent_id: m.agent_id,
+        slug: m.slug,
+        revision: m.revision ?? 0
+      })),
+      edges: updated.edges.map((e) => ({
+        from_slug: e.from_slug ?? e.from_agent_id,
+        to_slug: e.to_slug ?? e.to_agent_id,
+        description: e.description ?? "",
+        payload_schema: e.payload_schema ?? {}
+      }))
+    });
+    p22.outro(`Pushed ${link.name} at revision ${updated.revision}.`);
+  } catch (err) {
+    sp.stop("Failed.");
+    handleApiError6(err);
+  }
+}
+function handleApiError6(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 401) {
+      p22.log.error("Your session is invalid. Run `brainbase login` and try again.");
+    } else if (err.status === 403) {
+      p22.log.error("You do not have access to this orchestration.");
+    } else if (err.status === 409) {
+      p22.log.error(err.message);
+      p22.log.info(`Run ${pc30.cyan("brainbase orchestration pull")} to reconcile, then push again.`);
+    } else {
+      p22.log.error(err.message);
+    }
+  } else {
+    p22.log.error(err.message);
+  }
+}
+
+// src/cli/orchestration-status.ts
+import * as p23 from "@clack/prompts";
+import pc31 from "picocolors";
+async function runOrchestrationStatus(cwd) {
+  banner("orchestration status — what changed locally, remotely, both");
+  const link = readOrchLink(cwd);
+  if (!link) {
+    p23.log.warn("This folder is not linked to any orchestration.");
+    p23.log.info(`Run ${pc31.cyan("brainbase orchestration pull <id>")} first.`);
+    return;
+  }
+  const localManifest = hasOrchManifest(cwd) ? readOrchManifest(cwd) : null;
+  const lock = readOrchSyncState(cwd);
+  let cloud;
+  const sp = p23.spinner();
+  sp.start(`Fetching ${link.name}…`);
+  try {
+    cloud = await api.getOrchestration(link.orchestration_id);
+    sp.stop(`Cloud revision ${cloud.revision}.`);
+  } catch (err) {
+    sp.stop("Failed to reach brainbase.");
+    if (err instanceof ApiError && err.status === 401) {
+      p23.log.error("Your session is invalid. Run `brainbase login` and try again.");
+    } else {
+      p23.log.error(err.message);
+    }
+    return;
+  }
+  const lines = [];
+  lines.push("");
+  lines.push(`  ${pc31.bold(link.name)} ${pc31.dim(`(${link.orchestration_id})`)}`);
+  lines.push(`  ${pc31.dim("revision")}  cloud ${cloud.revision}${lock ? ` · lock ${lock.revision}` : " · never pulled"}`);
+  lines.push("");
+  const cloudMemberSet = new Set(cloud.members.map((m) => m.slug));
+  const localMemberSet = new Set((localManifest?.members ?? []).map((m) => m.slug));
+  const membersAdded = [...localMemberSet].filter((s) => !cloudMemberSet.has(s));
+  const membersRemoved = [...cloudMemberSet].filter((s) => !localMemberSet.has(s));
+  if (membersAdded.length || membersRemoved.length) {
+    lines.push(`  ${pc31.bold("members")}`);
+    for (const slug of membersAdded) {
+      lines.push(`    ${pc31.yellow("→ push")}  added in yaml: ${pc31.bold(slug)}`);
+    }
+    for (const slug of membersRemoved) {
+      lines.push(`    ${pc31.cyan("← pull")}  added on cloud: ${pc31.bold(slug)}`);
+    }
+    lines.push("");
+  }
+  const cloudEdgeKey = (e) => `${e.from_slug ?? e.from_agent_id}->${e.to_slug ?? e.to_agent_id}|${e.description ?? ""}`;
+  const localEdgeKey = (e) => `${e.from}->${e.to}|${e.description ?? ""}`;
+  const cloudEdges = new Map;
+  for (const e of cloud.edges)
+    cloudEdges.set(cloudEdgeKey(e), true);
+  const localEdges = new Map;
+  for (const e of localManifest?.edges ?? [])
+    localEdges.set(localEdgeKey(e), true);
+  const edgesAdded = [...localEdges.keys()].filter((k) => !cloudEdges.has(k));
+  const edgesRemoved = [...cloudEdges.keys()].filter((k) => !localEdges.has(k));
+  if (edgesAdded.length || edgesRemoved.length) {
+    lines.push(`  ${pc31.bold("edges")}`);
+    for (const k of edgesAdded)
+      lines.push(`    ${pc31.yellow("→ push")}  added in yaml: ${k}`);
+    for (const k of edgesRemoved)
+      lines.push(`    ${pc31.cyan("← pull")}  added on cloud: ${k}`);
+    lines.push("");
+  }
+  const lockByAgentId = new Map((lock?.members ?? []).map((m) => [m.agent_id, m]));
+  const memberDrift = [];
+  for (const m of cloud.members) {
+    const dir = memberDir(cwd, m.slug);
+    const memberSync = readSyncState(dir);
+    if (!memberSync) {
+      memberDrift.push({ slug: m.slug, reason: "no local checkout" });
+      continue;
+    }
+    const lockEntry = lockByAgentId.get(m.agent_id);
+    const lockedRev = lockEntry?.revision;
+    if (m.revision != null && lockedRev != null && m.revision !== lockedRev) {
+      memberDrift.push({
+        slug: m.slug,
+        reason: `cloud rev ${m.revision} ≠ lock ${lockedRev}`
+      });
+    }
+  }
+  if (memberDrift.length) {
+    lines.push(`  ${pc31.bold("member content drift")}`);
+    for (const d of memberDrift) {
+      lines.push(`    ${pc31.cyan("?")} ${pc31.bold(d.slug)}  ${pc31.dim("— " + d.reason)}`);
+    }
+    lines.push(`    ${pc31.dim("cd into each member folder and run")} ${pc31.cyan("brainbase agent status")}`);
+    lines.push("");
+  }
+  if (!membersAdded.length && !membersRemoved.length && !edgesAdded.length && !edgesRemoved.length && !memberDrift.length) {
+    lines.push(`  ${pc31.green("✓")} everything is in sync`);
+    lines.push("");
+    console.log(lines.join(`
+`));
+    return;
+  }
+  lines.push(`  ${pc31.dim("run")} ${pc31.cyan("brainbase orchestration pull")} ${pc31.dim("to apply cloud changes,")} ${pc31.cyan("brainbase orchestration push")} ${pc31.dim("to send yours")}`);
+  lines.push("");
+  console.log(lines.join(`
+`));
+}
+
+// src/cli/orchestration-list.ts
+import * as p24 from "@clack/prompts";
+import pc32 from "picocolors";
+async function runOrchestrationList(args) {
+  banner("orchestration list — orchestrations under a team");
+  let orgId = args.orgId;
+  let teamId = args.teamId;
+  if (!orgId) {
+    let orgs;
+    try {
+      orgs = await api.listOrgs();
+    } catch (err) {
+      handleApiError7(err);
+      return;
+    }
+    if (orgs.length === 0) {
+      p24.log.warn("You are not a member of any organization.");
+      return;
+    }
+    if (orgs.length === 1) {
+      orgId = orgs[0].id;
+    } else {
+      const choice = await p24.select({
+        message: "Which organization?",
+        options: orgs.map((o) => ({ value: o.id, label: o.name }))
+      });
+      orgId = ensureNotCancelled(choice);
+    }
+  }
+  if (!teamId) {
+    let teams;
+    try {
+      teams = await api.listTeams(orgId);
+    } catch (err) {
+      handleApiError7(err);
+      return;
+    }
+    if (teams.length === 0) {
+      p24.log.warn("No teams under this organization. Create one in the web app first.");
+      return;
+    }
+    if (teams.length === 1) {
+      teamId = teams[0].id;
+    } else {
+      const choice = await p24.select({
+        message: "Which team?",
+        options: teams.map((t) => ({ value: t.id, label: t.name }))
+      });
+      teamId = ensureNotCancelled(choice);
+    }
+  }
+  let items;
+  const sp = p24.spinner();
+  sp.start("Fetching orchestrations…");
+  try {
+    items = await api.listOrchestrations(orgId, teamId);
+    sp.stop(`${items.length} orchestration${items.length === 1 ? "" : "s"}.`);
+  } catch (err) {
+    sp.stop("Failed.");
+    handleApiError7(err);
+    return;
+  }
+  if (items.length === 0) {
+    p24.log.info("This team has no orchestrations yet.");
+    return;
+  }
+  const lines = [""];
+  for (const o of items) {
+    lines.push(`  ${pc32.bold(o.name)}  ${pc32.dim(o.id)}`);
+    if (o.description)
+      lines.push(`    ${pc32.dim(o.description)}`);
+    lines.push(`    ${pc32.dim(`${o.member_count} member${o.member_count === 1 ? "" : "s"} · ${o.edge_count} edge${o.edge_count === 1 ? "" : "s"}`)}`);
+    lines.push("");
+  }
+  lines.push(`  ${pc32.dim("pull one with")} ${pc32.cyan("brainbase orchestration pull <id>")}`);
+  lines.push("");
+  console.log(lines.join(`
+`));
+}
+function handleApiError7(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 401) {
+      p24.log.error("Your session is invalid. Run `brainbase login` and try again.");
+    } else {
+      p24.log.error(err.message);
+    }
+  } else {
+    p24.log.error(err.message);
+  }
+}
+
+// src/cli/orchestration.ts
+async function runOrchestration(cwd, sub, args, opts) {
+  switch (sub) {
+    case "pull":
+      await runOrchestrationPull(cwd, {
+        orchestrationId: args[0],
+        yes: opts.yes,
+        harness: opts.harness
+      });
+      return;
+    case "push":
+      await runOrchestrationPush(cwd, {
+        yes: opts.yes,
+        graphOnly: opts.graphOnly
+      });
+      return;
+    case "status":
+      await runOrchestrationStatus(cwd);
+      return;
+    case "list":
+    case "ls":
+      await runOrchestrationList({ orgId: opts.orgId, teamId: opts.teamId });
+      return;
+    case undefined:
+    case "help":
+    case "-h":
+    case "--help":
+      printHelp2();
+      return;
+    default:
+      console.error(`Unknown orchestration subcommand: ${sub}
+`);
+      printHelp2();
+      process.exit(1);
+  }
+}
+function printHelp2() {
+  const out = [];
+  out.push("");
+  out.push(`  ${pc33.bold("brainbase orchestration")} ${pc33.dim("<sub> [options]")}`);
+  out.push("");
+  out.push(`  ${pc33.cyan("pull")} ${pc33.dim("<id>")}      ${pc33.dim("fetch orchestration + every member agent into this folder")}`);
+  out.push(`  ${pc33.cyan("push")}             ${pc33.dim("push each member, then update the orchestration graph")}`);
+  out.push(`  ${pc33.cyan("status")}           ${pc33.dim("show what would push and what would pull")}`);
+  out.push(`  ${pc33.cyan("list")}             ${pc33.dim("list orchestrations under a team")}`);
+  out.push("");
+  out.push(`  ${pc33.bold("Flags")}`);
+  out.push(`    ${pc33.dim("--yes, -y")}        skip confirmations`);
+  out.push(`    ${pc33.dim("--harness <id>")}   harness for newly-created member folders (default claude-code)`);
+  out.push(`    ${pc33.dim("--graph-only")}     for push: only update members + edges, skip per-member push`);
+  out.push(`    ${pc33.dim("--org <id>")}       for list: org id (CLI vocab — DB teams.id)`);
+  out.push(`    ${pc33.dim("--team <id>")}      for list: team id (CLI vocab — DB groups.id)`);
+  out.push("");
+  console.log(out.join(`
+`));
+}
+
 // src/cli/run.ts
 import { spawn as spawn2 } from "node:child_process";
 async function runRun(cwd, args) {
@@ -9349,17 +10289,17 @@ async function runRun(cwd, args) {
 }
 
 // src/cli/publish.ts
-import * as p20 from "@clack/prompts";
-import pc29 from "picocolors";
+import * as p25 from "@clack/prompts";
+import pc34 from "picocolors";
 async function runPublish(cwd, _args) {
   banner("publish — send your changes to the team");
   const link = readLink(cwd);
   if (!link) {
-    p20.log.warn("This folder is not linked to any agent.");
-    p20.log.info(`Run ${pc29.cyan("brainbase link")} first.`);
+    p25.log.warn("This folder is not linked to any agent.");
+    p25.log.info(`Run ${pc34.cyan("brainbase link")} first.`);
     return;
   }
-  p20.log.info(`${pc29.bold("publish")} is coming soon — for now, edit the agent on the web app and run ${pc29.cyan("brainbase sync")} to bring changes here.`);
+  p25.log.info(`${pc34.bold("publish")} is coming soon — for now, edit the agent on the web app and run ${pc34.cyan("brainbase sync")} to bring changes here.`);
 }
 
 // src/ui/ink/StatusCard.tsx
@@ -9658,8 +10598,8 @@ async function runStatus(cwd) {
 }
 
 // src/cli/token.ts
-import * as p21 from "@clack/prompts";
-import pc30 from "picocolors";
+import * as p26 from "@clack/prompts";
+import pc35 from "picocolors";
 
 // src/ui/ink/TokenCards.tsx
 import { Box as Box15, Text as Text16 } from "ink";
@@ -9905,7 +10845,7 @@ async function runTokenCreate(args) {
   banner("token create — make a long-lived CLI key");
   let name = args.name;
   if (!name) {
-    const ans = await p21.text({
+    const ans = await p26.text({
       message: "Token label",
       placeholder: "my-laptop or ci-runner",
       validate: (v) => v.length === 0 ? "Required." : undefined
@@ -9913,13 +10853,13 @@ async function runTokenCreate(args) {
     name = ensureNotCancelled(ans);
   }
   const scopes = args.scopes && args.scopes.length > 0 ? args.scopes : DEFAULT_SCOPES;
-  const spinner17 = p21.spinner();
-  spinner17.start("Creating token…");
+  const spinner21 = p26.spinner();
+  spinner21.start("Creating token…");
   const created = await registryApi.createCliToken({
     name,
     scopes
   });
-  spinner17.stop("Token created.");
+  spinner21.stop("Token created.");
   writeToken(created.token, name);
   await showTokenCreatedCard({
     token: created.token,
@@ -9953,8 +10893,8 @@ async function runTokenRevoke(args) {
     process.exit(1);
   }
   if (!args.yes) {
-    const ok = await p21.confirm({
-      message: `Revoke token ${pc30.bold(args.id)}? CIs and machines using it will stop working.`,
+    const ok = await p26.confirm({
+      message: `Revoke token ${pc35.bold(args.id)}? CIs and machines using it will stop working.`,
       initialValue: false
     });
     if (!ensureNotCancelled(ok))
@@ -9969,7 +10909,7 @@ async function runTokenRevoke(args) {
 }
 async function runTokenClear() {
   if (!readToken()) {
-    console.log(pc30.dim("No local token stored."));
+    console.log(pc35.dim("No local token stored."));
     return;
   }
   clearToken();
@@ -10020,17 +10960,17 @@ async function runToken(sub, rest, args) {
 function printTokenHelp() {
   const out = [];
   out.push("");
-  out.push(`  ${pc30.bold("brainbase token")} ${pc30.dim("<command>")}`);
+  out.push(`  ${pc35.bold("brainbase token")} ${pc35.dim("<command>")}`);
   out.push("");
-  out.push(`  ${pc30.cyan("create")}                        ${pc30.dim("issue a new long-lived CLI key (PAT)")}`);
-  out.push(`  ${pc30.cyan("list")}                          ${pc30.dim("show your active tokens")}`);
-  out.push(`  ${pc30.cyan("revoke")} ${pc30.dim("<id>")}                  ${pc30.dim("revoke a token by id")}`);
-  out.push(`  ${pc30.cyan("clear")}                         ${pc30.dim("forget the local token (does not revoke)")}`);
+  out.push(`  ${pc35.cyan("create")}                        ${pc35.dim("issue a new long-lived CLI key (PAT)")}`);
+  out.push(`  ${pc35.cyan("list")}                          ${pc35.dim("show your active tokens")}`);
+  out.push(`  ${pc35.cyan("revoke")} ${pc35.dim("<id>")}                  ${pc35.dim("revoke a token by id")}`);
+  out.push(`  ${pc35.cyan("clear")}                         ${pc35.dim("forget the local token (does not revoke)")}`);
   out.push("");
-  out.push(`  ${pc30.bold("create flags")}`);
-  out.push(`  ${pc30.cyan("--name, -n")} ${pc30.dim("<label>")}        ${pc30.dim("token label (prompted if omitted)")}`);
-  out.push(`  ${pc30.cyan("--scopes")} ${pc30.dim("<list>")}           ${pc30.dim("comma-separated; allowed: read, publish, admin")}`);
-  out.push(`                                ${pc30.dim("default: read,publish")}`);
+  out.push(`  ${pc35.bold("create flags")}`);
+  out.push(`  ${pc35.cyan("--name, -n")} ${pc35.dim("<label>")}        ${pc35.dim("token label (prompted if omitted)")}`);
+  out.push(`  ${pc35.cyan("--scopes")} ${pc35.dim("<list>")}           ${pc35.dim("comma-separated; allowed: read, publish, admin")}`);
+  out.push(`                                ${pc35.dim("default: read,publish")}`);
   out.push("");
   console.log(out.join(`
 `));
@@ -10050,81 +10990,88 @@ var PROTECTED = new Set([
 function help() {
   const out = [];
   out.push("");
-  out.push(`  ${brandTint("◆")}  ${pc31.bold("brainbase")}  ${pc31.dim("v0.2.0")}`);
-  out.push(`     ${pc31.dim("connect your local agent to the brainbase platform")}`);
+  out.push(`  ${brandTint("◆")}  ${pc36.bold("brainbase")}  ${pc36.dim("v0.2.0")}`);
+  out.push(`     ${pc36.dim("connect your local agent to the brainbase platform")}`);
   out.push("");
   out.push(divider("USAGE"));
   out.push("");
-  out.push(`  ${pc31.bold("brainbase")} ${pc31.dim("<command> [options]")}`);
+  out.push(`  ${pc36.bold("brainbase")} ${pc36.dim("<command> [options]")}`);
   out.push("");
   out.push(divider("AUTH"));
   out.push("");
-  out.push(`  ${pc31.cyan("login")}     ${pc31.dim("  open the web app and connect this device")}`);
-  out.push(`  ${pc31.cyan("logout")}    ${pc31.dim("  clear the local session")}`);
-  out.push(`  ${pc31.cyan("whoami")}    ${pc31.dim("  show the current user")}`);
+  out.push(`  ${pc36.cyan("login")}     ${pc36.dim("  open the web app and connect this device")}`);
+  out.push(`  ${pc36.cyan("logout")}    ${pc36.dim("  clear the local session")}`);
+  out.push(`  ${pc36.cyan("whoami")}    ${pc36.dim("  show the current user")}`);
   out.push("");
   out.push(divider("LINKED AGENT"));
   out.push("");
-  out.push(`  ${pc31.cyan("agent create")}               ${pc31.dim("make a new agent on the cloud and link this folder")}`);
-  out.push(`  ${pc31.cyan("link")}                       ${pc31.dim("attach this folder to an existing agent")}`);
-  out.push(`  ${pc31.cyan("agent pull")}                 ${pc31.dim("bring cloud changes into this folder")}`);
-  out.push(`  ${pc31.cyan("agent push")}                 ${pc31.dim("send local changes to the cloud")}`);
-  out.push(`  ${pc31.cyan("agent status")}               ${pc31.dim("show what would pull and what would push")}`);
-  out.push(`  ${pc31.cyan("agent env")}                  ${pc31.dim("print export lines for `eval $(brainbase agent env)`")}`);
-  out.push(`  ${pc31.cyan("run")} ${pc31.dim("<cmd> [args...]")}         ${pc31.dim("run <cmd> with secrets.env loaded into env")}`);
-  out.push(`  ${pc31.cyan("status")}                     ${pc31.dim("show what this folder is linked to")}`);
-  out.push(`  ${pc31.cyan("unlink")}                     ${pc31.dim("disconnect this folder")}`);
+  out.push(`  ${pc36.cyan("agent create")}               ${pc36.dim("make a new agent on the cloud and link this folder")}`);
+  out.push(`  ${pc36.cyan("link")}                       ${pc36.dim("attach this folder to an existing agent")}`);
+  out.push(`  ${pc36.cyan("agent pull")}                 ${pc36.dim("bring cloud changes into this folder")}`);
+  out.push(`  ${pc36.cyan("agent push")}                 ${pc36.dim("send local changes to the cloud")}`);
+  out.push(`  ${pc36.cyan("agent status")}               ${pc36.dim("show what would pull and what would push")}`);
+  out.push(`  ${pc36.cyan("agent env")}                  ${pc36.dim("print export lines for `eval $(brainbase agent env)`")}`);
+  out.push(`  ${pc36.cyan("run")} ${pc36.dim("<cmd> [args...]")}         ${pc36.dim("run <cmd> with secrets.env loaded into env")}`);
+  out.push(`  ${pc36.cyan("status")}                     ${pc36.dim("show what this folder is linked to")}`);
+  out.push(`  ${pc36.cyan("unlink")}                     ${pc36.dim("disconnect this folder")}`);
+  out.push("");
+  out.push(divider("ORCHESTRATIONS"));
+  out.push("");
+  out.push(`  ${pc36.cyan("orchestration list")}             ${pc36.dim("list orchestrations under a team")}`);
+  out.push(`  ${pc36.cyan("orchestration pull")} ${pc36.dim("<id>")}        ${pc36.dim("recursively fetch an orchestration + every member agent")}`);
+  out.push(`  ${pc36.cyan("orchestration push")}             ${pc36.dim("recursively push each member, then update the graph")}`);
+  out.push(`  ${pc36.cyan("orchestration status")}           ${pc36.dim("show what would push and what would pull")}`);
   out.push("");
   out.push(divider("TEMPLATES"));
   out.push("");
-  out.push(`  ${pc31.cyan("template pack")}                       ${pc31.dim("bundle the current agent into a template")}`);
-  out.push(`  ${pc31.cyan("template publish")}                    ${pc31.dim("upload a template to the registry")}`);
-  out.push(`  ${pc31.cyan("template search")} ${pc31.dim("[query]")}             ${pc31.dim("search the registry")}`);
-  out.push(`  ${pc31.cyan("template info")}    ${pc31.dim("<creator/slug>")}     ${pc31.dim("show registry details for a template")}`);
-  out.push(`  ${pc31.cyan("template onboard")} ${pc31.dim("<creator/slug>")}     ${pc31.dim("install (or refresh) a template")}`);
-  out.push(`  ${pc31.cyan("template list")}                       ${pc31.dim("show installed templates")}`);
-  out.push(`  ${pc31.cyan("template remove")}  ${pc31.dim("<creator/slug>")}     ${pc31.dim("uninstall a template")}`);
+  out.push(`  ${pc36.cyan("template pack")}                       ${pc36.dim("bundle the current agent into a template")}`);
+  out.push(`  ${pc36.cyan("template publish")}                    ${pc36.dim("upload a template to the registry")}`);
+  out.push(`  ${pc36.cyan("template search")} ${pc36.dim("[query]")}             ${pc36.dim("search the registry")}`);
+  out.push(`  ${pc36.cyan("template info")}    ${pc36.dim("<creator/slug>")}     ${pc36.dim("show registry details for a template")}`);
+  out.push(`  ${pc36.cyan("template onboard")} ${pc36.dim("<creator/slug>")}     ${pc36.dim("install (or refresh) a template")}`);
+  out.push(`  ${pc36.cyan("template list")}                       ${pc36.dim("show installed templates")}`);
+  out.push(`  ${pc36.cyan("template remove")}  ${pc36.dim("<creator/slug>")}     ${pc36.dim("uninstall a template")}`);
   out.push("");
   out.push(divider("SKILLS"));
   out.push("");
-  out.push(`  ${pc31.cyan("skill add")} ${pc31.dim("<source>")}                  ${pc31.dim("install a skill (github / git / brainbase)")}`);
-  out.push(`  ${pc31.cyan("skill list")}                            ${pc31.dim("show locally installed skills + their source")}`);
-  out.push(`  ${pc31.cyan("skill update")} ${pc31.dim("<slug>")}                  ${pc31.dim("re-fetch a skill from its recorded source")}`);
-  out.push(`  ${pc31.cyan("skill remove")} ${pc31.dim("<slug>")}                  ${pc31.dim("uninstall a skill")}`);
-  out.push(`  ${pc31.cyan("skill search")} ${pc31.dim("[query]")}                 ${pc31.dim("search the brainbase skill registry")}`);
-  out.push(`  ${pc31.cyan("skill info")} ${pc31.dim("<creator/slug>")}            ${pc31.dim("show registry details for a skill")}`);
-  out.push(`  ${pc31.cyan("skill publish")} ${pc31.dim("[creator/slug][@v]")}     ${pc31.dim("publish a local skill to the registry")}`);
+  out.push(`  ${pc36.cyan("skill add")} ${pc36.dim("<source>")}                  ${pc36.dim("install a skill (github / git / brainbase)")}`);
+  out.push(`  ${pc36.cyan("skill list")}                            ${pc36.dim("show locally installed skills + their source")}`);
+  out.push(`  ${pc36.cyan("skill update")} ${pc36.dim("<slug>")}                  ${pc36.dim("re-fetch a skill from its recorded source")}`);
+  out.push(`  ${pc36.cyan("skill remove")} ${pc36.dim("<slug>")}                  ${pc36.dim("uninstall a skill")}`);
+  out.push(`  ${pc36.cyan("skill search")} ${pc36.dim("[query]")}                 ${pc36.dim("search the brainbase skill registry")}`);
+  out.push(`  ${pc36.cyan("skill info")} ${pc36.dim("<creator/slug>")}            ${pc36.dim("show registry details for a skill")}`);
+  out.push(`  ${pc36.cyan("skill publish")} ${pc36.dim("[creator/slug][@v]")}     ${pc36.dim("publish a local skill to the registry")}`);
   out.push("");
   out.push(divider("CLI TOKENS"));
   out.push("");
-  out.push(`  ${pc31.cyan("token create")}                        ${pc31.dim("issue a long-lived CLI key for CI / scripts")}`);
-  out.push(`  ${pc31.cyan("token list")}                          ${pc31.dim("show your active tokens")}`);
-  out.push(`  ${pc31.cyan("token revoke")} ${pc31.dim("<id>")}                  ${pc31.dim("revoke a token")}`);
+  out.push(`  ${pc36.cyan("token create")}                        ${pc36.dim("issue a long-lived CLI key for CI / scripts")}`);
+  out.push(`  ${pc36.cyan("token list")}                          ${pc36.dim("show your active tokens")}`);
+  out.push(`  ${pc36.cyan("token revoke")} ${pc36.dim("<id>")}                  ${pc36.dim("revoke a token")}`);
   out.push("");
   out.push(divider("FLAGS"));
   out.push("");
-  out.push(`  ${pc31.dim("--harness <id>")}     force harness for onboard / sync (e.g. claude-code)`);
-  out.push(`  ${pc31.dim("--scope <s>")}        force scope: global | project`);
-  out.push(`  ${pc31.dim("--yes, -y")}          skip confirmations / auto-overwrite`);
-  out.push(`  ${pc31.dim("--agent <id>")}       for link: attach this folder to an existing agent non-interactively`);
-  out.push(`  ${pc31.dim("--no-tracking")}      for link: skip routing LLM traffic through brainbase`);
-  out.push(`  ${pc31.dim("--shell <sh|fish>")}  for agent env: pick output format (auto-detected from $SHELL)`);
-  out.push(`  ${pc31.dim("--all")}              for template list: include installs from other folders`);
-  out.push(`  ${pc31.dim("--web <url>")}        for login: web app URL (default https://new.usekafka.com)`);
+  out.push(`  ${pc36.dim("--harness <id>")}     force harness for onboard / sync (e.g. claude-code)`);
+  out.push(`  ${pc36.dim("--scope <s>")}        force scope: global | project`);
+  out.push(`  ${pc36.dim("--yes, -y")}          skip confirmations / auto-overwrite`);
+  out.push(`  ${pc36.dim("--agent <id>")}       for link: attach this folder to an existing agent non-interactively`);
+  out.push(`  ${pc36.dim("--no-tracking")}      for link: skip routing LLM traffic through brainbase`);
+  out.push(`  ${pc36.dim("--shell <sh|fish>")}  for agent env: pick output format (auto-detected from $SHELL)`);
+  out.push(`  ${pc36.dim("--all")}              for template list: include installs from other folders`);
+  out.push(`  ${pc36.dim("--web <url>")}        for login: web app URL (default https://new.usekafka.com)`);
   out.push("");
   out.push(divider("ENV"));
   out.push("");
-  out.push(`  ${pc31.dim("BRAINBASE_HOME")}         override the local config dir (default ~/.brainbase)`);
-  out.push(`  ${pc31.dim("BRAINBASE_WEB_URL")}      override the web app URL used by login`);
-  out.push(`  ${pc31.dim("BRAINBASE_API_URL")}      override the API URL used by link / sync`);
-  out.push(`  ${pc31.dim("BRAINBASE_REGISTRY_URL")} override the registry API URL`);
-  out.push(`  ${pc31.dim("BRAINBASE_TOKEN")}        long-lived CLI PAT (overrides token.json)`);
-  out.push(`  ${pc31.dim("BRAINBASE_SKIP_AUTH")}    bypass the auth gate for development`);
+  out.push(`  ${pc36.dim("BRAINBASE_HOME")}         override the local config dir (default ~/.brainbase)`);
+  out.push(`  ${pc36.dim("BRAINBASE_WEB_URL")}      override the web app URL used by login`);
+  out.push(`  ${pc36.dim("BRAINBASE_API_URL")}      override the API URL used by link / sync`);
+  out.push(`  ${pc36.dim("BRAINBASE_REGISTRY_URL")} override the registry API URL`);
+  out.push(`  ${pc36.dim("BRAINBASE_TOKEN")}        long-lived CLI PAT (overrides token.json)`);
+  out.push(`  ${pc36.dim("BRAINBASE_SKIP_AUTH")}    bypass the auth gate for development`);
   out.push("");
   out.push(divider("HARNESSES"));
   out.push("");
-  out.push(`  ${pc31.dim("•")} ${pc31.bold("claude-code")}  ${pc31.dim("skills, mcps, agents, commands, instructions, files")}`);
-  out.push(`  ${pc31.dim("•")} ${pc31.bold("codex")}        ${pc31.dim("skills, mcps, commands, instructions, files")}`);
+  out.push(`  ${pc36.dim("•")} ${pc36.bold("claude-code")}  ${pc36.dim("skills, mcps, agents, commands, instructions, files")}`);
+  out.push(`  ${pc36.dim("•")} ${pc36.bold("codex")}        ${pc36.dim("skills, mcps, commands, instructions, files")}`);
   out.push("");
   console.log(out.join(`
 `));
@@ -10168,13 +11115,13 @@ async function requireAuth(cmd) {
   if (status.ok)
     return;
   console.error("");
-  console.error(`  ${brandTint("◆")}  ${pc31.bold("brainbase")}`);
+  console.error(`  ${brandTint("◆")}  ${pc36.bold("brainbase")}`);
   console.error("");
-  console.error(`  ${pc31.red("✗")}  You need to sign in to use ${pc31.bold("brainbase " + cmd)}.`);
+  console.error(`  ${pc36.red("✗")}  You need to sign in to use ${pc36.bold("brainbase " + cmd)}.`);
   if (status.reason)
-    console.error(`     ${pc31.dim(status.reason)}`);
+    console.error(`     ${pc36.dim(status.reason)}`);
   console.error("");
-  console.error(`     Run ${pc31.cyan("brainbase login")} to connect this device.`);
+  console.error(`     Run ${pc36.cyan("brainbase login")} to connect this device.`);
   console.error("");
   process2.exit(1);
 }
@@ -10184,7 +11131,7 @@ async function main() {
   const rawCwd = process2.cwd();
   const cwd = (() => {
     try {
-      return fs40.realpathSync(rawCwd);
+      return fs44.realpathSync(rawCwd);
     } catch {
       return rawCwd;
     }
@@ -10211,6 +11158,7 @@ async function main() {
   const agentFlag = getFlag(argv, "--agent");
   const shellFlag = getFlag(argv, "--shell");
   const noTracking = hasFlag(argv, "--no-tracking");
+  const graphOnlyFlag = hasFlag(argv, "--graph-only");
   const nameFlag = getFlag(argv, "--name");
   const taglineFlag = getFlag(argv, "--tagline");
   const orgIdFlag = getFlag(argv, "--org");
@@ -10295,6 +11243,18 @@ async function main() {
         });
         break;
       }
+      case "orchestration":
+      case "orch": {
+        const sub = argv.shift();
+        await runOrchestration(cwd, sub, argv, {
+          yes,
+          harness,
+          orgId: orgIdFlag,
+          teamId: teamIdFlag,
+          graphOnly: graphOnlyFlag
+        });
+        break;
+      }
       case "publish": {
         await runPublish(cwd, { yes });
         break;
@@ -10310,7 +11270,7 @@ async function main() {
         process2.exit(1);
     }
   } catch (err) {
-    console.error(pc31.red(`
+    console.error(pc36.red(`
 ${err.message}`));
     if (process2.env.BRAINBASE_DEBUG)
       console.error(err.stack);

package/package.json

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