@drunkcoding/agents-and-skills 0.0.45 → 0.0.46

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

@@ -1,7 +1,8 @@
 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");
@@ -19,6 +20,15 @@ function readSidecar(fs, dir, rec, fileKey, inlineKey) {
   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/).
@@ -86,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.
@@ -133,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.
@@ -191,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>)`)
@@ -344,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;
@@ -355,10 +388,11 @@ export function importAutopilots({ cli, manifest, dir, agentIdMap, fs = nodeFs }
     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);
@@ -403,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) {
@@ -463,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 })
@@ -489,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 },
@@ -513,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,
@@ -521,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,
   };
 }
 
@@ -528,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 = [];
@@ -596,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)` });
+      }
     }
   }
 
@@ -635,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
@@ -41,28 +61,73 @@ First resolve `<workspace-name>`:
 
 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:
 
-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.
+- **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.
 
-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.
+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.
 
 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:
 
@@ -73,14 +138,19 @@ An empty field gets no file and no `*_file` key. Skills keep their own layout
 
 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>`."

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

@@ -19,13 +19,13 @@ No existence check is needed here: the Step 2 dry-run fails with `Unknown worksp
 
 ## Step 2 — Pre-flight (dry run)
 
-Before writing anything, run the import script with `--dry-run` to preview the bundle. Preview against the **full** set (`--include agents,squads,projects,autopilots`) regardless of what the user ultimately chooses to import — incompatibilities for a type (e.g. project caveats) are only computed when that type is included, so previewing everything up front is what lets the user see a project's or autopilot's cost before deciding whether to opt it in:
+Before writing anything, run the import script with `--dry-run` to preview the bundle. Preview against the **full** set (`--include agents,squads,projects,autopilots,labels,properties`) regardless of what the user ultimately chooses to import — incompatibilities for a type (e.g. project caveats) are only computed when that type is included, so previewing everything up front is what lets the user see a project's or autopilot's cost before deciding whether to opt it in:
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
   --dir <folder> \
   --workspace <workspace-name> \
-  --include agents,squads,projects,autopilots \
+  --include agents,squads,projects,autopilots,labels,properties \
   [--runtime-map <srcId1=dstId1,srcId2=dstId2,...>] \
   --dry-run
 ```
@@ -34,9 +34,11 @@ Present the `bundle` and `willImport` counts, and every entry in `incompatibilit
 
 ## Step 3 — Select which types to import
 
-Ask the user which of `agents`, `squads`, `projects`, `autopilots` they want to import. **Default is `agents,squads`** — `projects` and `autopilots` each require explicit opt-in.
+Ask the user which of `agents`, `squads`, `projects`, `autopilots`, `labels`, `properties` they want to import. **Default is `agents,squads`** — `projects`, `autopilots`, `labels`, and `properties` each require explicit opt-in.
 
-If the pre-flight's `incompatibilities` list contains an `unmapped-runtime` or `autopilot-squad-assignee-unsupported` entry, tell the user it **aborts the import before any write** (see Step 4 below) — `unmapped-runtime` needs `--runtime-map`; a squad-assigned autopilot has no fix, since the multica CLI has no command to assign a squad to an autopilot (only `--agent`) — drop that autopilot from the bundle or recreate its assignment by hand after importing the squad. An `autopilot-assignee-missing` entry also aborts unless resolved by including `agents` or ensuring that agent already exists in the destination. Other incompatibility kinds are informational only and applied best-effort, fixed up afterward in the Multica UI: `priority-not-settable` (project priority isn't settable via the CLI, so it never round-trips), `resource-not-portable` (only `github_repo` resources are portable — other resource kinds are dropped), `lead-agent-missing` (a non-agent lead isn't re-applied to the imported project), `autopilot-priority-not-captured` (the multica CLI/API never returns an autopilot's priority, so it can't be captured or restored at all — a known platform gap, not a bug in this tool), `autopilot-project-missing` (the autopilot's target project isn't found by title in the destination — it's created/updated with no project set), and `autopilot-webhook-reissued` (informational — the webhook trigger always gets a freshly issued URL).
+`labels` and `properties` write **workspace-wide** definitions (Multica has no project-scoped label or property), so importing them changes the target workspace's issue taxonomy for every project in it, not just the one being migrated. Say so before the user opts in.
+
+If the pre-flight's `incompatibilities` list contains an `unmapped-runtime` or `autopilot-squad-assignee-unsupported` entry, tell the user it **aborts the import before any write** (see Step 4 below) — `unmapped-runtime` needs `--runtime-map`; a squad-assigned autopilot has no fix, since the multica CLI has no command to assign a squad to an autopilot (only `--agent`) — drop that autopilot from the bundle or recreate its assignment by hand after importing the squad. An `autopilot-assignee-missing` entry also aborts unless resolved by including `agents` or ensuring that agent already exists in the destination. Other incompatibility kinds are informational only and applied best-effort, fixed up afterward in the Multica UI: `priority-not-settable` (project priority isn't settable via the CLI, so it never round-trips), `resource-not-portable` (only `github_repo` resources are portable — other resource kinds are dropped), `lead-agent-missing` (a non-agent lead isn't re-applied to the imported project), `autopilot-priority-not-captured` (the multica CLI/API never returns an autopilot's priority, so it can't be captured or restored at all — a known platform gap, not a bug in this tool), `autopilot-project-missing` (the autopilot's target project isn't found by title in the destination — it's created/updated with no project set), `autopilot-webhook-reissued` (informational — the webhook trigger always gets a freshly issued URL), `label-description-not-settable` (the CLI has no `--description` flag on `label create`/`update`, so a label's description never round-trips — re-enter it in the UI), `property-type-conflict` (a property of that name already exists at the destination with a **different** type; type is immutable, so that property is **skipped** entirely rather than re-created, which would orphan every value already stored under that name), `property-archived` (informational — an archived source definition is imported and then archived at the destination too), `autopilot-arrives-paused` (informational — the autopilot was active at the source; every import lands paused), `mcp-server-not-creatable` (a workspace MCP server named in the bundle is absent at the destination and **cannot** be created from the bundle — `workspace mcp list` never returns a server's config, so re-add it with `multica workspace mcp add <name> --server-config ...`), and `agent-mcp-server-missing` (an agent's MCP server assignment is dropped because that server isn't in the destination library).
 
 ## Step 4 — Run the import (auto-mapping first)
 
@@ -46,7 +48,7 @@ Each exported agent record carries its source runtime's `provider` (e.g. `claude
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
   --dir <folder> \
   --workspace <workspace-name> \
-  --include <agents,squads,projects,autopilots>
+  --include <agents,squads,projects,autopilots,labels,properties>
 ```
 
 If it aborts with `Unmapped runtimes: ...` (0 or 2+ runtimes share that provider in the target workspace, or the bundle predates provider capture), resolve manually:
@@ -62,7 +64,7 @@ Ask the user to pick a matching target runtime by name or ID for each unmapped `
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
   --dir <folder> \
   --workspace <workspace-name> \
-  --include <agents,squads,projects,autopilots> \
+  --include <agents,squads,projects,autopilots,labels,properties> \
   --runtime-map <srcId1=dstId1,srcId2=dstId2,...>
 ```
 
@@ -70,17 +72,23 @@ If it instead aborts with `Unresolved autopilot assignees: ...`, that is not fix
 
 The import also rewrites any `mention://agent/<id>` link inside squad and agent instructions (e.g. `[@dev-backend](mention://agent/<id>)`) from the source agent's id to its new id in the target workspace — the CLI does this automatically for every agent captured in the bundle; no extra flag needed. Mentions pointing to an agent outside the bundle are left untouched.
 
+Workspace-wide sets are read from their own folder: `labels/labels.json`, `properties/properties.json`, and `mcp/servers.json`, located via the `labels_file` / `properties_file` / `mcp_servers_file` pointers in `manifest.json`. A pre-folder bundle that carried the arrays inline in the manifest still imports unchanged.
+
+Agent **MCP server assignments** (`mcp_servers` on each agent record) are re-linked by **name** against the destination's workspace MCP library, then each is enabled or disabled to match the source. The library itself is **never created** — only a server's name and transport ever travel, so a missing server means its assignments are skipped and reported. Add the missing servers first (`multica workspace mcp add`), then re-run the import to attach them.
+
 Prose fields are read back from each resource's sibling `.md` when a `*_file` key points at it — **instructions** from `<slug>.md` (agents, squads) and **description** from `<slug>.description.md` (agents, squads, projects, autopilots). Editing that Markdown is the supported way to review and enhance the prose before import. Older bundles that predate the split (prose inline in the JSON, no `*_file` key) still import unchanged.
 
 Avatars are restored automatically, but **only when the target resource has none** — an existing agent or squad that already carries an avatar is never overwritten. New agents get their bundled image re-uploaded; new squads get their `avatar_url` (emoji or URL) set. An agent whose source avatar was an emoji can't be restored (the CLI has no emoji setter for agents) and is reported as unsupported.
 
+Importing `labels` and `properties` matches by **name** and is idempotent: an existing label is updated to the bundle's colour, an existing property is updated in place (`property update` re-matches its options by name so option ids — and any issue values already set — survive). An archived definition is unarchived before the update and re-archived afterwards, so its archived state round-trips without ever writing to an archived record. A property whose name collides with a **different type** at the destination is skipped and reported, never re-created.
+
 Importing `autopilots` always creates a brand-new autopilot **paused**, regardless of the source's status — activation is left as a deliberate follow-up action, never automatic. Re-importing an already-imported autopilot updates it by title (never duplicates) but leaves its current status alone. Its triggers are upserted by kind+label — a re-import never adds a duplicate trigger — and a webhook trigger always gets a freshly issued URL, never the source's.
 
 ## Step 5 — Report results
 
 Parse the JSON output and report:
 
-- Created and updated counts for skills, agents, squads, projects, and autopilots (`created.autopilots`/`updated.autopilots`).
+- Created and updated counts for skills, agents, squads, projects, autopilots, labels, and properties (`created.labels`, `created.properties`, and the matching `updated.*`).
 - Name-to-ID maps for skills and agents (`skillIdMap`, `agentIdMap`).
 - `squadIdMap`: name-to-ID map for every squad imported.
 - `autopilotIdMap`: name-to-ID map for every autopilot imported.
@@ -96,3 +104,10 @@ Parse the JSON output and report:
 - If `autopilotSubscribersUnresolved` is non-empty, surface every `<title>:<member-name>` entry verbatim with: "NOTE: the following autopilot subscribers could not be matched by name in the target workspace — skipped: `<entry>`."
 - If `autopilotPriorityNotCaptured` is non-empty, surface every autopilot title verbatim with: "NOTE: the following autopilots' priority could not be captured from the source (the multica CLI/API never returns it) — a known platform gap, not something this tool can fix: `<autopilot-title>`."
 - If `autopilotWebhookReissued` is non-empty, surface every autopilot title verbatim with: "NOTE: the following autopilots had a webhook trigger created with a freshly issued URL — the previous URL does not carry over: `<autopilot-title>`."
+- If `autopilotsActiveAtSource` is non-empty, surface every autopilot title verbatim with: "NOTE: the following autopilots were ACTIVE at the source but landed PAUSED here — activate each deliberately with `multica autopilot update <id> --status active`: `<autopilot-title>`."
+- If `mcpServersNotCreatable` is non-empty, surface every server name verbatim with: "WARNING: the following workspace MCP servers are in the bundle but missing at the destination, and CANNOT be created from it (the CLI never returns a server's config on read) — add each with `multica workspace mcp add <name> --server-config ...`, then re-run the import to attach the agent assignments: `<server-name>`."
+- If `mcpServersUnresolved` is non-empty, surface every `<agent-name>:<server-name>` entry verbatim with: "NOTE: the following agent MCP server assignments were skipped — no server of that name exists in the destination workspace library: `<entry>`."
+- If `mcpServersApplyFailures` is non-empty, surface every `<agent-name>:<server-name>` entry verbatim with: "WARNING: the following agent MCP server assignments were added but the CLI rejected the enable/disable that follows — check their state in the Multica UI: `<entry>`."
+- If `labelDescriptionUnsupported` is non-empty, surface every label name verbatim with: "NOTE: the following labels' descriptions could not be applied (the multica CLI has no `--description` flag on `label create`/`update`) — re-enter them in the Multica UI: `<label-name>`."
+- If `propertyTypeConflicts` is non-empty, surface every entry verbatim with: "WARNING: the following custom properties were SKIPPED — a property of that name already exists at the destination with a different type, and a property's type is immutable: `<entry>`. Rename one side, or map the values by hand."
+- If `propertiesArchived` is non-empty, surface every property name verbatim with: "NOTE: the following custom properties were imported and then archived, matching their state at the source: `<property-name>`."

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

@@ -18,7 +18,7 @@ sync <type> <name> from <src-ws> to <dest-ws>
 
 Where `<type>` is `skill`, `agent`, `squad`, `project`, or `autopilot`; `<name>` is the resource name (for `project` and `autopilot`, its **title**); `<src-ws>` and `<dest-ws>` are workspace names registered in Multica.
 
-Projects and autopilots are resolved by title, not ID, e.g. `multica-sync.mjs project "<title>" from <src-ws> <dest-ws>` — the project's lead agent is synced alongside it. `multica-sync.mjs autopilot "<title>" from <src-ws> <dest-ws>` syncs the autopilot's assignee (agent, or squad + members) alongside it; a squad-assigned autopilot aborts (see the import skill — the multica CLI has no command to assign a squad to an autopilot).
+Projects and autopilots are resolved by title, not ID, e.g. `multica-sync.mjs project "<title>" from <src-ws> <dest-ws>` — the project's lead agent is synced alongside it. `multica-sync.mjs autopilot "<title>" from <src-ws> <dest-ws>` syncs only the autopilot configuration (title, description, triggers, etc.) — its assignee is linked by name and must already exist in the destination workspace; the assignee is not bundled or synced alongside the autopilot. A squad-assigned autopilot aborts (see the import skill — the multica CLI has no command to assign a squad to an autopilot).
 
 ## Step 2 — Run the sync (auto-mapping first)
 

package/plugins/plugin-validator/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plugin-validator",
   "displayName": "Plugin Validator",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
   "author": {
     "name": "Steven Hoang"

package/plugins/html-effectiveness/.claude-plugin/plugin.json

@@ -1,17 +0,0 @@
-{
-  "name": "html-effectiveness",
-  "displayName": "HTML Effectiveness Reports",
-  "version": "0.0.45",
-  "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
-  "author": {
-    "name": "Steven Hoang"
-  },
-  "keywords": [
-    "html",
-    "report",
-    "status",
-    "incident",
-    "slide-deck",
-    "decision-matrix"
-  ]
-}