@drunkcoding/agents-and-skills 0.0.44 → 0.0.46

package/plugins/multica-tool/scripts/multica-import.mjs

@@ -1,22 +1,35 @@
 import * as nodeFs from "node:fs";
-import { listSkills, listAgents, listAgentsIncludingArchived, listSquads, listRuntimes, listWorkspaceMembers, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId, listProjects, getProjectResources, findByTitle, listAutopilots, getAutopilot } from "./lib.mjs";
+import { listSkills, listAgents, listAgentsIncludingArchived, listSquads, listRuntimes, listWorkspaceMembers, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId, listProjects, getProjectResources, findByTitle, listAutopilots, getAutopilot, listLabels, listProperties, listWorkspaceMcpServers } from "./lib.mjs";
 
-// User-facing selectable types are agents/squads/projects/autopilots; skills follow agents.
+// User-facing selectable types are agents/squads/projects/autopilots/labels/properties;
+// skills follow agents. Default stays agents,squads — everything else opts in.
 export function parseInclude(raw) {
   const set = new Set((raw ? raw.split(",") : ["agents", "squads"]).map((s) => s.trim()).filter(Boolean));
   if (set.has("agents")) set.add("skills");
   return set;
 }
 
-// Instructions live in a sibling .md referenced by `instructions_file` (mirrors
-// avatar_file). Legacy bundles carry no instructions_file and keep instructions
-// inline in the JSON — fall back to that so older exports still import.
-function readInstructions(fs, dir, rec) {
-  if (rec.instructions_file && fs.existsSync(`${dir}/${rec.instructions_file}`)) {
-    return fs.readFileSync(`${dir}/${rec.instructions_file}`, "utf8");
+// A prose field (instructions/description) lives in a sibling .md referenced by
+// `<field>_file` (mirrors avatar_file). Legacy bundles carry no `<field>_file`
+// and keep the prose inline in the JSON — fall back to that so older exports
+// still import.
+function readSidecar(fs, dir, rec, fileKey, inlineKey) {
+  if (rec[fileKey] && fs.existsSync(`${dir}/${rec[fileKey]}`)) {
+    return fs.readFileSync(`${dir}/${rec[fileKey]}`, "utf8");
   }
-  return rec.instructions ?? "";
+  return rec[inlineKey] ?? "";
 }
+const readInstructions = (fs, dir, rec) => readSidecar(fs, dir, rec, "instructions_file", "instructions");
+
+// Workspace-wide sets (labels, properties, MCP roster) live in their own flat
+// folder, pointed at by `<key>_file` in the manifest. Legacy bundles carried the
+// array inline under `<key>` — fall back to that so older exports still import.
+export function readTaxonomy(fs, dir, manifest, key) {
+  const rel = manifest[`${key}_file`];
+  if (rel && fs.existsSync(`${dir}/${rel}`)) return JSON.parse(fs.readFileSync(`${dir}/${rel}`, "utf8"));
+  return manifest[key] ?? [];
+}
+const readDescription = (fs, dir, rec) => readSidecar(fs, dir, rec, "description_file", "description");
 
 // Relative paths of every file under root (recursing into subdirs like scripts/).
 function walkSkillFiles(fs, root, rel = "") {
@@ -83,9 +96,14 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
   const avatarUnsupported = [];     // emoji avatar — no CLI setter for agents
   const permissionApplyFailures = [];  // CLI rejected --public-to-member
   const permissionUnsupported = [];    // no member target resolved in the destination
+  const mcpServersUnresolved = [];     // bundled server name absent from the destination library
+  const mcpServersApplyFailures = [];  // CLI rejected the enable/disable
   // Lazy + memoized: destination member user_ids, only listed when an agent needs them.
   let destMemberIds = null;
   const getDestMemberIds = () => destMemberIds ??= new Set(listWorkspaceMembers(cli).map((m) => m.user_id));
+  // Lazy + memoized: destination MCP library, name -> id.
+  let destMcp = null;
+  const destMcpServerIds = () => destMcp ??= new Map(listWorkspaceMcpServers(cli).map((m) => [m.name, m.id]));
   let created = 0, updated = 0, reused = 0;
   // Includes archived agents so a bundle name matching a retired agent restores
   // and reuses it instead of failing to create under the held name.
@@ -100,7 +118,8 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       "--visibility", rec.visibility ?? "private",
       "--max-concurrent-tasks", String(rec.max_concurrent_tasks ?? 6),
     ];
-    if (rec.description) common.push("--description", rec.description);
+    const description = readDescription(fs, dir, rec);
+    if (description) common.push("--description", description);
     const instructions = readInstructions(fs, dir, rec);
     if (instructions) common.push("--instructions", instructions);
     if (rec.model) common.push("--model", rec.model);
@@ -129,6 +148,21 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
     const skillIds = (rec.skill_names ?? []).map((n) => skillIdMap.get(n)).filter(Boolean);
     cli.run(["agent", "skills", "set", id, "--skill-ids", skillIds.join(",")]);
 
+    // Workspace MCP server assignments, resolved by NAME against the destination
+    // library (ids are per-workspace). A server the destination doesn't have is
+    // reported, not created: `workspace mcp list` never returns the server entry
+    // JSON, so the bundle has no config to recreate it from.
+    for (const m of rec.mcp_servers ?? []) {
+      const serverId = destMcpServerIds().get(m.name);
+      if (!serverId) { mcpServersUnresolved.push(`${rec.name}:${m.name}`); continue; }
+      try { cli.run(["agent", "mcp", "add", id, serverId]); } catch { /* already assigned */ }
+      try {
+        cli.run(["agent", "mcp", m.enabled ? "enable" : "disable", id, serverId]);
+      } catch {
+        mcpServersApplyFailures.push(`${rec.name}:${m.name}`);
+      }
+    }
+
     // Avatar: only ever set it when the target agent has none — never clobber an
     // avatar an existing agent already has. Agents accept only image uploads
     // (`agent avatar --file`); an emoji-only avatar can't be restored via the CLI.
@@ -187,7 +221,7 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       }
     }
   }
-  return { idMap, sourceIdMap, created, updated, reused, secretsApplyFailures, avatarApplyFailures, avatarUnsupported, permissionApplyFailures, permissionUnsupported };
+  return { idMap, sourceIdMap, created, updated, reused, secretsApplyFailures, avatarApplyFailures, avatarUnsupported, permissionApplyFailures, permissionUnsupported, mcpServersUnresolved, mcpServersApplyFailures };
 }
 
 // Rewrites `mention://agent/<id>` links (e.g. `[@dev-backend](mention://agent/<id>)`)
@@ -269,7 +303,8 @@ export function importProjects({ cli, manifest, dir, agentIdMap, fs = nodeFs })
   for (const entry of manifest.projects ?? []) {
     const rec = JSON.parse(fs.readFileSync(`${dir}/${entry.file}`, "utf8"));
     const flags = ["--title", rec.title];
-    if (rec.description) flags.push("--description", rec.description);
+    const description = readDescription(fs, dir, rec);
+    if (description) flags.push("--description", description);
     if (rec.icon) flags.push("--icon", rec.icon);
     if (rec.status) flags.push("--status", rec.status);
     if (rec.due_date) flags.push("--due-date", rec.due_date);
@@ -339,6 +374,9 @@ export function importAutopilots({ cli, manifest, dir, agentIdMap, fs = nodeFs }
   const idMap = new Map();
   let created = 0, updated = 0;
   const projectUnresolved = [], subscribersUnresolved = [], priorityNotCaptured = [], webhookReissued = [];
+  // Every import lands paused; these were live at the source and need a
+  // deliberate `autopilot update <id> --status active` at the destination.
+  const activeAtSource = recs.filter((r) => r.status === "active").map((r) => r.title);
   const existing = listAutopilots(cli);
   let destProjects = null;
   const resolveProjectId = (title) => (destProjects ??= listProjects(cli)).find((p) => p.title === title)?.id ?? null;
@@ -347,12 +385,14 @@ export function importAutopilots({ cli, manifest, dir, agentIdMap, fs = nodeFs }
 
   for (const rec of recs) {
     const common = [];
-    if (rec.description) common.push("--description", rec.description);
+    const description = readDescription(fs, dir, rec);
+    if (description) common.push("--description", description);
     if (rec.issue_title_template) common.push("--issue-title-template", rec.issue_title_template);
-    // priority is never present today — the multica CLI/API accepts it on write but
-    // never returns it on read, so export can't capture the source's real value.
-    if (rec.priority && rec.priority !== "none") common.push("--priority", rec.priority);
-    else priorityNotCaptured.push(rec.title);
+    // Priority never round-trips: the API omits it on read, and as of multica
+    // 0.4.36 `autopilot create`/`update` reject `--priority` outright ("unknown
+    // flag"). Passing a legacy bundle's value through would abort the import, so
+    // it is always reported instead of applied.
+    priorityNotCaptured.push(rec.title);
 
     if (rec.project_title) {
       const projectId = resolveProjectId(rec.project_title);
@@ -397,7 +437,82 @@ export function importAutopilots({ cli, manifest, dir, agentIdMap, fs = nodeFs }
       if (t.kind === "webhook") webhookReissued.push(rec.title);
     }
   }
-  return { idMap, created, updated, projectUnresolved, subscribersUnresolved, priorityNotCaptured, webhookReissued };
+  return { idMap, created, updated, projectUnresolved, subscribersUnresolved, priorityNotCaptured, webhookReissued, activeAtSource };
+}
+
+// Workspace issue labels, matched by name. Colour is the only field the CLI can
+// set besides the name — a label's description has no `--description` flag on
+// `label create`/`update` (multica 0.4.36), so it is reported, never applied.
+export function importLabels({ cli, manifest, dir, fs = nodeFs }) {
+  const entries = readTaxonomy(fs, dir, manifest, "labels");
+  if (!entries.length) return { created: 0, updated: 0, descriptionUnsupported: [] };
+  const existing = listLabels(cli);
+  let created = 0, updated = 0;
+  const descriptionUnsupported = [];
+  for (const l of entries) {
+    const match = findByName(existing, l.name);
+    if (match) {
+      cli.run(["label", "update", match.id, "--color", l.color]);
+      updated++;
+    } else {
+      cli.run(["label", "create", "--name", l.name, "--color", l.color]);
+      created++;
+    }
+    // Only worth reporting when the destination doesn't already carry the same text.
+    if (l.description && match?.description !== l.description) descriptionUnsupported.push(l.name);
+  }
+  return { created, updated, descriptionUnsupported };
+}
+
+// Workspace custom issue property definitions, matched by name — the same key
+// issue values reference, and the key `property update` uses to re-match existing
+// options so their ids (and any values already set on issues) survive.
+//
+// A property's type is immutable: a name collision with a different type is
+// skipped and reported rather than forced, since re-creating it would orphan
+// every value already stored under that name at the destination.
+export function importProperties({ cli, manifest, dir, fs = nodeFs }) {
+  const entries = readTaxonomy(fs, dir, manifest, "properties");
+  if (!entries.length) return { created: 0, updated: 0, typeConflicts: [], archivedApplied: [] };
+  const existing = listProperties(cli);
+  let created = 0, updated = 0;
+  const typeConflicts = [], archivedApplied = [];
+  for (const p of entries) {
+    const match = findByName(existing, p.name);
+    if (match && match.type !== p.type) {
+      typeConflicts.push(`${p.name} (destination is "${match.type}", bundle is "${p.type}" — type is immutable)`);
+      continue;
+    }
+    // Unarchive first so the update below always lands on an active definition;
+    // the desired archived state is re-applied at the end of the loop body.
+    if (match?.archived) cli.run(["property", "unarchive", p.name]);
+
+    const flags = [];
+    if (p.description) flags.push("--description", p.description);
+    if (p.icon) flags.push("--icon", p.icon);
+    // `--option` is select/multi_select only; every other type exports none.
+    for (const o of p.options ?? []) flags.push("--option", o.color ? `${o.name}:${o.color}` : o.name);
+
+    if (match) {
+      cli.run(["property", "update", p.name, ...flags]);
+      updated++;
+    } else {
+      cli.run(["property", "create", "--name", p.name, "--type", p.type, ...flags]);
+      created++;
+    }
+    if (p.archived) { cli.run(["property", "archive", p.name]); archivedApplied.push(p.name); }
+  }
+  return { created, updated, typeConflicts, archivedApplied };
+}
+
+// Workspace MCP servers named in the bundle that the destination library lacks.
+// Only name + transport ever travel (see listWorkspaceMcpServers), so these are
+// reported for manual re-entry — never created.
+export function mcpServerGap({ cli, manifest, dir, fs = nodeFs }) {
+  const wanted = readTaxonomy(fs, dir, manifest, "mcp_servers");
+  if (!wanted.length) return [];
+  const have = new Set(listWorkspaceMcpServers(cli).map((m) => m.name));
+  return wanted.filter((m) => !have.has(m.name)).map((m) => m.name);
 }
 
 export function collectSourceRuntimes(manifest) {
@@ -457,7 +572,7 @@ export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
     : { idMap: new Map(), created: 0, updated: 0 };
   const agentRes = inc.has("agents")
     ? importAgents({ cli, manifest, dir, skillIdMap: skillRes.idMap, runtimeMap: effective, fs })
-    : { idMap: new Map(), sourceIdMap: new Map(), created: 0, updated: 0, reused: 0, secretsApplyFailures: [], avatarApplyFailures: [], avatarUnsupported: [], permissionApplyFailures: [], permissionUnsupported: [] };
+    : { idMap: new Map(), sourceIdMap: new Map(), created: 0, updated: 0, reused: 0, secretsApplyFailures: [], avatarApplyFailures: [], avatarUnsupported: [], permissionApplyFailures: [], permissionUnsupported: [], mcpServersUnresolved: [], mcpServersApplyFailures: [] };
   // Runs after every agent exists so forward-referencing mentions resolve.
   const mentionRes = inc.has("agents")
     ? rewriteAgentMentions({ cli, manifest, dir, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap, fs })
@@ -469,6 +584,7 @@ export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
   if (inc.has("squads")) {
     for (const squad of manifest.squads ?? []) {
       squad.instructions = readInstructions(fs, dir, squad);
+      squad.description = readDescription(fs, dir, squad);
       const r = importSquad({ cli, squad, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
       if (r.skipped) { squadsSkipped.push(squad.name); continue; }
       squadIdMap.set(squad.name, r.newId);
@@ -482,15 +598,22 @@ export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
     projectRes = importProjects({ cli, manifest, dir, agentIdMap: agentRes.idMap, fs });
   }
 
-  let autopilotRes = { idMap: new Map(), created: 0, updated: 0, projectUnresolved: [], subscribersUnresolved: [], priorityNotCaptured: [], webhookReissued: [] };
+  let autopilotRes = { idMap: new Map(), created: 0, updated: 0, projectUnresolved: [], subscribersUnresolved: [], priorityNotCaptured: [], webhookReissued: [], activeAtSource: [] };
   if (inc.has("autopilots")) {
     autopilotRes = importAutopilots({ cli, manifest, dir, agentIdMap: agentRes.idMap, fs });
   }
 
+  const labelRes = inc.has("labels")
+    ? importLabels({ cli, manifest, dir, fs })
+    : { created: 0, updated: 0, descriptionUnsupported: [] };
+  const propertyRes = inc.has("properties")
+    ? importProperties({ cli, manifest, dir, fs })
+    : { created: 0, updated: 0, typeConflicts: [], archivedApplied: [] };
+
   return {
     include: [...inc],
-    created: { skills: skillRes.created, agents: agentRes.created, squads: squadsCreated, projects: projectRes.created, autopilots: autopilotRes.created },
-    updated: { skills: skillRes.updated, agents: agentRes.updated, squads: squadsUpdated, projects: projectRes.updated, autopilots: autopilotRes.updated },
+    created: { skills: skillRes.created, agents: agentRes.created, squads: squadsCreated, projects: projectRes.created, autopilots: autopilotRes.created, labels: labelRes.created, properties: propertyRes.created },
+    updated: { skills: skillRes.updated, agents: agentRes.updated, squads: squadsUpdated, projects: projectRes.updated, autopilots: autopilotRes.updated, labels: labelRes.updated, properties: propertyRes.updated },
     // Agents restored from archived + updated to the bundle's definition — distinct
     // from a plain update (an active-name match). Only agents can be reused today.
     reused: { agents: agentRes.reused },
@@ -506,6 +629,13 @@ export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
     avatarUnsupported: agentRes.avatarUnsupported,
     permissionApplyFailures: agentRes.permissionApplyFailures,
     permissionUnsupported: agentRes.permissionUnsupported,
+    mcpServersUnresolved: agentRes.mcpServersUnresolved,
+    mcpServersApplyFailures: agentRes.mcpServersApplyFailures,
+    // Bundled workspace MCP servers missing at the destination. The CLI never
+    // exposes a server's entry JSON on read, so each must be re-added by hand
+    // (`multica workspace mcp add <name> --server-config ...`) before its agent
+    // assignments can land.
+    mcpServersNotCreatable: mcpServerGap({ cli, manifest, dir, fs }),
     squadsSkipped,
     priorityUnsupported: projectRes.priorityUnsupported,
     resourcesUnsupported: projectRes.resourcesUnsupported,
@@ -514,6 +644,10 @@ export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
     autopilotSubscribersUnresolved: autopilotRes.subscribersUnresolved,
     autopilotPriorityNotCaptured: autopilotRes.priorityNotCaptured,
     autopilotWebhookReissued: autopilotRes.webhookReissued,
+    autopilotsActiveAtSource: autopilotRes.activeAtSource,
+    labelDescriptionUnsupported: labelRes.descriptionUnsupported,
+    propertyTypeConflicts: propertyRes.typeConflicts,
+    propertiesArchived: propertyRes.archivedApplied,
   };
 }
 
@@ -521,13 +655,20 @@ export function preflight({ cli, dir, runtimeMap, include, fs = nodeFs }) {
   const inc = include ?? new Set(["skills", "agents", "squads"]);
   const manifest = JSON.parse(fs.readFileSync(`${dir}/manifest.json`, "utf8"));
   const count = (k) => (manifest[k] ?? []).length;
-  const bundle = { skills: count("skills"), agents: count("agents"), squads: count("squads"), projects: count("projects"), autopilots: count("autopilots") };
+  // labels/properties/mcp live in their own folder; read through the manifest
+  // pointer (with the legacy inline fallback) rather than counting a key that
+  // current bundles no longer carry.
+  const bundleLabels = readTaxonomy(fs, dir, manifest, "labels");
+  const bundleProperties = readTaxonomy(fs, dir, manifest, "properties");
+  const bundle = { skills: count("skills"), agents: count("agents"), squads: count("squads"), projects: count("projects"), autopilots: count("autopilots"), labels: bundleLabels.length, properties: bundleProperties.length };
   const willImport = {
     skills: inc.has("skills") ? bundle.skills : 0,
     agents: inc.has("agents") ? bundle.agents : 0,
     squads: inc.has("squads") ? bundle.squads : 0,
     projects: inc.has("projects") ? bundle.projects : 0,
     autopilots: inc.has("autopilots") ? bundle.autopilots : 0,
+    labels: inc.has("labels") ? bundle.labels : 0,
+    properties: inc.has("properties") ? bundle.properties : 0,
   };
 
   const incompatibilities = [];
@@ -589,15 +730,56 @@ export function preflight({ cli, dir, runtimeMap, include, fs = nodeFs }) {
       } else if (!agentAvailable(rec.assignee_name)) {
         incompatibilities.push({ type: "autopilot-assignee-missing", detail: `${rec.title} → agent "${rec.assignee_name}" (ensure this agent exists in the destination or is included in this import)` });
       }
-      if (!rec.priority) {
-        incompatibilities.push({ type: "autopilot-priority-not-captured", detail: `${rec.title} (the multica CLI/API never returns an autopilot's priority, so export could not capture it)` });
-      }
+      incompatibilities.push({ type: "autopilot-priority-not-captured", detail: `${rec.title} (the multica CLI/API never returns an autopilot's priority on read, and multica 0.4.36 dropped --priority from autopilot create/update — it can be neither captured nor restored)` });
       if (rec.project_title && !projectAvailable(rec.project_title)) {
         incompatibilities.push({ type: "autopilot-project-missing", detail: `${rec.title} → project "${rec.project_title}" (not found in the destination)` });
       }
       if (rec.had_webhook_trigger) {
         incompatibilities.push({ type: "autopilot-webhook-reissued", detail: `${rec.title} (webhook trigger will get a newly issued URL — the old one never travels)` });
       }
+      if (rec.status === "active") {
+        incompatibilities.push({ type: "autopilot-arrives-paused", detail: `${rec.title} (active at the source; every imported autopilot lands paused — activate it deliberately at the destination)` });
+      }
+    }
+  }
+
+  // MCP: the workspace library can never be recreated from a bundle (no CLI read
+  // of a server's entry JSON), so a missing server blocks its agent assignments.
+  if (inc.has("agents")) {
+    for (const name of mcpServerGap({ cli, manifest, dir, fs })) {
+      incompatibilities.push({ type: "mcp-server-not-creatable", detail: `${name} (in the bundle's workspace MCP roster but absent at the destination; \`workspace mcp list\` never returns a server's config, so re-add it with \`multica workspace mcp add ${name} --server-config ...\`)` });
+    }
+    let destMcpNames = null;
+    const mcpAvailable = (n) => (destMcpNames ??= new Set(listWorkspaceMcpServers(cli).map((m) => m.name))).has(n);
+    for (const a of manifest.agents ?? []) {
+      const rec = JSON.parse(fs.readFileSync(`${dir}/${a.file}`, "utf8"));
+      for (const m of rec.mcp_servers ?? []) {
+        if (!mcpAvailable(m.name)) {
+          incompatibilities.push({ type: "agent-mcp-server-missing", detail: `${rec.name} → MCP server "${m.name}" (not in the destination workspace library — the assignment will be skipped)` });
+        }
+      }
+    }
+  }
+
+  if (inc.has("labels")) {
+    for (const l of bundleLabels) {
+      if (l.description) {
+        incompatibilities.push({ type: "label-description-not-settable", detail: `${l.name} (the multica CLI exposes no --description flag on label create/update)` });
+      }
+    }
+  }
+
+  if (inc.has("properties")) {
+    // Read-only mirror of importProperties' immutable-type skip.
+    const existingProps = bundleProperties.length ? listProperties(cli) : [];
+    for (const prop of bundleProperties) {
+      const match = findByName(existingProps, prop.name);
+      if (match && match.type !== prop.type) {
+        incompatibilities.push({ type: "property-type-conflict", detail: `${prop.name} (destination is "${match.type}", bundle is "${prop.type}" — type is immutable, this property will be skipped)` });
+      }
+      if (prop.archived) {
+        incompatibilities.push({ type: "property-archived", detail: `${prop.name} (archived at the source — imported, then archived at the destination too)` });
+      }
     }
   }
 
@@ -628,7 +810,7 @@ function main() {
   const dryRun    = args.includes("--dry-run");
 
   if (!dir || !workspace) {
-    console.error("Usage: multica-import.mjs --dir <folder> --workspace <name> [--runtime-map <src=dst,...>] [--include <csv>] [--dry-run]");
+    console.error("Usage: multica-import.mjs --dir <folder> --workspace <name> [--runtime-map <src=dst,...>] [--include agents,squads,projects,autopilots,labels,properties] [--dry-run]");
     process.exit(1);
   }
 

package/plugins/multica-tool/skills/export/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export
-description: Use when the user wants to export Multica skills, agents, or squads to a local folder for backup, version control, or cross-workspace migration.
+description: Use when the user wants to export Multica skills, agents, squads, projects, or autopilots to a local folder for backup, version control, or cross-workspace migration. Supports whole-workspace exports by level (skill, agent, squad, project) or a single named resource.
 allowed-tools: Bash, Read
 ---
 
@@ -18,11 +18,31 @@ multica auth status 2>&1 || true
 
 If `multica login` is required, surface that message verbatim and stop.
 
-## Step 2 — Determine scope and resource ID
+## Step 2 — Pick a level, or a single resource
 
-If the user named a specific resource and type (`skill`, `agent`, `squad`, `project`, or `autopilot`), use those directly.
+There are two ways to export, and they are mutually exclusive:
 
-Otherwise, list available resources for the chosen type and present a pick list:
+- **Whole workspace, by level** (`--level`) — the default shape. A level bundles its own tier plus every tier below it. Use this whenever the user asks for a workspace, a backup, or a migration.
+- **One named resource** (`--scope <type> --id <id>`) — for a single skill, agent, squad, project, or autopilot.
+
+### Levels
+
+Lowest tier first; **the default level is `squad`**.
+
+| `--level` | Object folders written |
+|---|---|
+| `skill` | `skills/` |
+| `agent` | `skills/`, `agents/` |
+| `squad` *(default)* | `skills/`, `agents/`, `squads/` |
+| `project` | `skills/`, `agents/`, `squads/`, `projects/`, `autopilots/`, `labels/`, `properties/`, `mcp/` |
+
+Notes on the tiers:
+
+- **Project** carries portable project metadata (title, description, icon, priority, status, dates, lead mapping) plus its attached resource records — **never issues, never members**. Workspace issue **labels**, custom **properties**, and the workspace **MCP server roster** ride along at this level.
+- **Autopilots** are bundled **only** at `--level project`. Every other level omits them.
+- `--level skill` keeps every workspace skill, including ones no agent references. Every higher level prunes those orphans, since the agents are what reference them.
+
+If the user asked for a single resource but did not name it, list the type and present a pick list:
 
 ```bash
 multica <type> list --output json
@@ -37,51 +57,100 @@ If the user specified an output directory, use it verbatim. Otherwise default to
 First resolve `<workspace-name>`:
 
 - If the user named a source workspace (the value you would pass as `--workspace <name>`), use that name.
-- Otherwise, read the current default workspace's name:
-
-```bash
-multica workspace get --output json
-```
-
-  and take its `.name`.
+- Otherwise, run `multica workspace get --output json` and take its `.name` (the current default workspace).
 
 Slugify the resolved name for filesystem safety — lowercase it, replace each run of non-`[a-z0-9]` characters with a single `-`, and trim leading/trailing `-` (the same rule the scripts use internally).
 
-Then construct the default directory by scope:
+Then construct the default directory:
 
-- `all` or `projects` (whole workspace) → `export/<workspace-name>`
-- a single resource (`skill`, `agent`, `squad`, `project`, or `autopilot`) → `export/<workspace-name>/<slug>-<type>`, where `<slug>` is the slugified resource name and `<type>` is the resource type.
+- a whole-workspace export (`--level`) → `export/<workspace-name>`
+- a single resource (`--scope <type> --id`) → `export/<workspace-name>/<slug>-<type>`, where `<slug>` is the slugified resource name and `<type>` is the resource type.
 
-Examples: `export all from mx-workspace` → `export/mx-workspace`; `export skill "Foo Bar" from mx-workspace` → `export/mx-workspace/foo-bar-skill`.
+Examples: `export everything from mx-workspace` → `export/mx-workspace`; `export skill "Foo Bar" from mx-workspace` → `export/mx-workspace/foo-bar-skill`.
 
 ## Step 4 — Run the export
 
+Whole workspace, by level (the default path — `--level` defaults to `squad`):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-export.mjs" \
+  --out <dir> \
+  [--level skill|agent|squad|project] \
+  [--workspace <workspace-name>]
+```
+
+One named resource:
+
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-export.mjs" \
-  --scope <skill|agent|squad|project|projects|autopilot|all> \
+  --scope <skill|agent|squad|project|autopilot> \
   --id <id> \
   --out <dir> \
   [--workspace <workspace-name>]
 ```
 
-`--id` is required for `skill`, `agent`, `squad`, `project`, and `autopilot` (a single named resource); it is **not needed** for `projects` (every project in the workspace) or `all` (the entire workspace). `all` does **not** include autopilots — an autopilot is always exported explicitly, by name, never auto-bundled.
+`--scope` and `--level` are mutually exclusive; the script exits 1 if both are passed. `--id` is required with `--scope`.
+
+A workspace export is one flat, deduped bundle: a skill, agent, or squad reached from several places is written exactly once and referenced by name.
+
+Every export that reaches a resource with a dependency **bundles that dependency** so the bundle is self-contained — a squad's leader and members, a project's lead agent, an autopilot's assignee agent or squad, and every skill those agents use. On import, only `github_repo` project resources are portable and recreated; other resource types are reported and skipped.
+
+### Folder layout
+
+One flat folder per object type:
+
+```
+<dir>/
+  manifest.json
+  skills/<slug>/SKILL.md, config.json, <skill files…>
+  agents/<slug>.json, <slug>.md, <slug>.description.md, <slug>.avatar.<ext>
+  squads/<slug>.json, <slug>.md, <slug>.description.md
+  projects/<slug>.json, <slug>.description.md
+  autopilots/<slug>.json, <slug>.description.md
+  labels/labels.json
+  properties/properties.json
+  mcp/servers.json
+```
+
+`manifest.json` points at `labels/`, `properties/` and `mcp/` via `labels_file`, `properties_file` and `mcp_servers_file` (with a matching `*_count`); the arrays themselves are no longer inline. Import still reads a pre-folder bundle that carried them inline.
+
+### Issue labels, custom properties, and the MCP roster
+
+`--scope project` and `--level project` also bundle the workspace's **issue labels**, **custom issue property definitions**, and the **workspace MCP server roster**, so a migrated project lands somewhere its issues can actually be labelled and filled in. All three are **workspace-scoped in Multica — there is no project-scoped label, property, or MCP server** — so what travels is the whole workspace's taxonomy, not a per-project subset. State that plainly to the user when they ask for "the project's labels".
+
+Narrower selections (`skill`, `agent`, `squad`, `autopilot` scopes; `skill`/`agent`/`squad` levels) bundle none of the three — a single resource is not a workspace migration.
+
+What travels, and what cannot:
+
+- **Labels** — `name` and `color`. A label's `description` is captured in the bundle for review but **cannot be restored**: `label create`/`label update` expose no `--description` flag. Every affected label is listed in `labelDescriptionsNotPortable`.
+- **Properties** — `name`, `type`, `description`, `icon`, `archived`, and each select option's `name` + `color`. Server-assigned `position` and `usage_count` are not bundled (no CLI setter). Option **ids** are deliberately dropped: `property update` re-matches options by name at the destination, which is also how issue values reference them.
+- Archived property definitions **are** included (`property list --include-archived`), so a retired definition arrives retired instead of reappearing in every picker.
+- **MCP servers** — `name` and `transport` only. A server's entry JSON (command/args/env, and any token inside it) is **write-only in the CLI**: `workspace mcp add`/`update` accept it, and nothing reads it back. So `mcp/servers.json` is a roster, not a copy — every entry is listed in `mcpServerConfigsNotPortable`, and each must be re-added by hand at the destination before agent assignments can attach to it.
+
+Every agent record also carries `mcp_servers` — which workspace MCP servers that agent uses, as `{name, enabled}`. This is separate from the agent's own inline `mcp_config`. Import re-links them by name against the destination library.
 
-Pass `--scope all` (with no `--id`) to export the **entire workspace** — every skill, agent, squad, and project — into one flat, deduped bundle. A skill or agent shared across many agents/squads is written exactly once and referenced by name.
+The script writes `manifest.json`, skill `SKILL.md` files, agent JSON files, and squad JSON files into `<dir>`. Every resource's prose fields are externalized to sibling Markdown files, never embedded in the JSON — so they are easy to read, diff, and edit:
 
-Exporting a project (or `projects`/`all`) also **bundles the project's lead agent** so the bundle is self-contained; projects carry metadata only (title, description, icon, priority, status, dates, lead mapping) plus their attached resource records — never issues. On import, only `github_repo` resources are portable and recreated; other resource types are reported and skipped.
+- **instructions** (system prompt / charter, agents and squads) → `<slug>.md`, referenced by an `instructions_file` key.
+- **description** (agents, squads, projects, autopilots) → `<slug>.description.md`, referenced by a `description_file` key.
 
-The script writes `manifest.json`, skill `SKILL.md` files, agent JSON files, and squad JSON files into `<dir>`. Each agent's and squad's **instructions** (system prompt / charter) are written to a sibling Markdown file — `agents/<slug>.md`, `squads/<slug>.md` — referenced by an `instructions_file` key in the JSON, so the prose is easy to read, diff, and edit. Agents/squads with no instructions get no `.md`.
+An empty field gets no file and no `*_file` key. Skills keep their own layout — the description lives in `SKILL.md` frontmatter and the body is the content.
 
 Avatars are captured automatically: an agent's uploaded-image avatar is downloaded into the bundle (`agents/<slug>.avatar.<ext>`) and referenced by `avatar_file`; emoji avatars (agents and squads) and a squad's avatar are recorded as the `avatar_url` string.
 
-Exporting `--scope autopilot` bundles the autopilot's **assignee** so the bundle is self-contained — an agent assignee (and its skills), or a squad assignee (its members, their skills, and the squad itself). It also captures the schedule and webhook triggers, the target project's **title** (not its ID — resolved by name on import) when one is set, and human subscribers' **names** (not their IDs). A webhook trigger's secret (URL/token) is **never** written to the bundle — only that it exists (its label); a fresh secret is issued on import.
+Exporting `--scope autopilot` bundles the autopilot configuration **and its assignee** (an agent, or a squad with its members and their skills), so the bundle imports on its own. The assignee is linked by name (`assignee_type` + `assignee_name`); import resolves that name against the bundle first, then the destination workspace. An autopilot's `status` is captured, but **every imported autopilot lands paused** regardless — the ones that were live at the source are listed in `autopilotsActiveAtSource` so they can be re-activated deliberately. The bundle also captures the schedule and webhook triggers, the target project's **title** (not its ID — resolved by name on import) when one is set, and human subscribers' **names** (not their IDs). A webhook trigger's secret (URL/token) is **never** written to the bundle — only that it exists (its label); a fresh secret is issued on import.
 
 ## Step 5 — Report results
 
 Parse the JSON output from the script and report:
 
 - Directory written to.
-- Count of skills, agents, squads, and projects exported.
+- The level (or the single resource) exported.
+- Count of skills, agents, squads, projects, and autopilots exported.
 - If `pruned_skills` is non-empty, note it: "Pruned N orphan skill(s) not linked to any agent: `<name>`, …" (these are standalone workspace skills that no exported agent references — only `--scope all` produces them).
 - If `warnings` is non-empty, surface every agent name verbatim with this message: "WARNING: the following agents' exported files contain custom environment variables or MCP config in PLAINTEXT — treat the export directory as sensitive (avoid committing it to a public repo, restrict file permissions, delete it once the import is done): `<agent-name>`."
 - If `autopilotWebhookTriggers` is non-empty, surface every autopilot title verbatim with: "NOTE: the following autopilots have a webhook trigger — its secret was NOT exported; a newly issued URL will be created on import: `<autopilot-title>`."
+- Count of labels and custom properties bundled (`manifest.labels.length`, `manifest.properties.length`), noting that both are workspace-wide, not project-specific.
+- If `autopilotsActiveAtSource` is non-empty, surface every title verbatim with: "NOTE: the following autopilots were ACTIVE at the source; every imported autopilot lands paused — re-activate each one deliberately with `multica autopilot update <id> --status active`: `<autopilot-title>`."
+- If `mcpServerConfigsNotPortable` is non-empty, surface every server name verbatim with: "NOTE: the following workspace MCP servers travelled by name and transport only — the CLI never returns a server's config on read, so re-add each one at the destination (`multica workspace mcp add <name> --server-config ...`) before importing the agents that use it: `<server-name>`."
+- If `labelDescriptionsNotPortable` is non-empty, surface every label name verbatim with: "NOTE: the following labels have a description that the multica CLI cannot set on import (`label create`/`update` have no `--description` flag) — re-enter it in the Multica UI at the destination: `<label-name>`."