@drunkcoding/agents-and-skills 0.0.43 → 0.0.45

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "tech-graph",
       "source": "./plugins/tech-graph",
       "description": "6-step wizard for technical diagrams (SVG/PNG) via fireworks-tech-graph",
-      "version": "0.0.43",
+      "version": "0.0.45",
       "category": "diagram",
       "keywords": [
         "diagram",
@@ -26,7 +26,7 @@
       "name": "html-effectiveness",
       "source": "./plugins/html-effectiveness",
       "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
-      "version": "0.0.43",
+      "version": "0.0.45",
       "category": "reports",
       "keywords": [
         "html",
@@ -41,7 +41,7 @@
       "name": "plugin-validator",
       "source": "./plugins/plugin-validator",
       "description": "Orchestrated validator for Claude Code plugins — validates skills, agents, commands, and hooks across every plugin under plugins/**.",
-      "version": "0.0.43",
+      "version": "0.0.45",
       "category": "tooling",
       "keywords": [
         "validation",
@@ -57,7 +57,7 @@
       "name": "team-share",
       "source": "./plugins/team-share",
       "description": "Onboard your team with an interactive setup menu: install CodeGraph, build the Understand-Anything knowledge graph, and share Claude Code settings — run any combination, all idempotent.",
-      "version": "0.0.43",
+      "version": "0.0.45",
       "category": "tooling",
       "keywords": [
         "onboarding",
@@ -73,7 +73,7 @@
       "name": "multica-tool",
       "source": "./plugins/multica-tool",
       "description": "Export, import, and sync Multica skills, agents, and squads between workspaces.",
-      "version": "0.0.43",
+      "version": "0.0.45",
       "category": "workflow",
       "keywords": [
         "multica",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "Personal collection of Claude Code skills and agents, installable via `npx skills`.",
   "keywords": [
     "claude-code",

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

@@ -1,7 +1,7 @@
 {
   "name": "html-effectiveness",
   "displayName": "HTML Effectiveness Reports",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "Generate self-contained interactive HTML reports from 20 upstream templates via a conversational agent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/multica-tool/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "multica-tool",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "Export, import, and sync Multica skills, agents, and squads between workspaces via the multica CLI."
 }

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

@@ -53,6 +53,9 @@ export function resolveWorkspaceId(cli, name) {
 export const listRuntimes = (cli) => cli.json(["runtime", "list"]);
 export const listSkills = (cli) => cli.json(["skill", "list"]);
 export const listAgents = (cli) => cli.json(["agent", "list"]);
+// Includes archived agents (archived_at set) — used wherever a name match or an
+// id lookup must also see agents excluded from the default listing above.
+export const listAgentsIncludingArchived = (cli) => cli.json(["agent", "list", "--include-archived"]);
 export const listSquads = (cli) => cli.json(["squad", "list"]);
 export const listWorkspaceMembers = (cli) => cli.json(["workspace", "member", "list"]);
 
@@ -72,6 +75,8 @@ export function getAgent(cli, id) {
   const a = cli.json(["agent", "get", id]);
   return {
     id: a.id, name: a.name, description: a.description, instructions: a.instructions,
+    // Export-time signal only (never written to a bundle record — see redactAgent).
+    archived_at: a.archived_at ?? null,
     model: a.model, visibility: a.visibility, avatar_url: a.avatar_url ?? null,
     service_tier: a.service_tier ?? "",
     permission_mode: a.permission_mode ?? null,

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

@@ -1,10 +1,22 @@
 import * as nodeFs from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname } from "node:path";
-import { slugify, getSkill, getAgent, getAgentCustomEnv, getSquad, getSquadMembers, listRuntimes, listSkills, listAgents, listSquads, listProjects, getProject, getProjectResources, listWorkspaceMembers, getAutopilot, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { slugify, getSkill, getAgent, getAgentCustomEnv, getSquad, getSquadMembers, listRuntimes, listSkills, listAgents, listAgentsIncludingArchived, listSquads, listProjects, getProject, getProjectResources, listWorkspaceMembers, getAutopilot, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
 
 const nonEmpty = (v) => v && typeof v === "object" && Object.keys(v).length > 0;
 
+// Externalize a prose field to a sibling .md next to `jsonRel`
+// (e.g. agents/x.json + ".description.md" → agents/x.description.md), and record
+// the `<field>_file` pointer on `record`. Empty prose writes nothing and adds no
+// key — same sibling-file pattern as avatar_file, applied uniformly to every
+// resource's instructions/description so no prose is ever embedded in the JSON.
+function writeSidecar(fs, outDir, jsonRel, suffix, text, record, key) {
+  if (!text) return;
+  const rel = jsonRel.replace(/\.json$/, suffix);
+  fs.writeFileSync(`${outDir}/${rel}`, text);
+  record[key] = rel;
+}
+
 // An avatar_url is either an uploaded-image URL (http[s]://…) or an inline
 // "emoji:🦍" marker. Only image URLs carry bytes worth bundling; emoji markers
 // are just carried as strings in the record.
@@ -31,7 +43,7 @@ export function redactAgent(a) {
   // a is a normalized agent from getAgent, with `custom_env`/
   // `custom_env_fetch_failed` attached by the caller (collectAgent) — getAgent
   // itself never fetches custom_env, since it requires a separate audited call.
-  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, instructions, ...rest } = a;
+  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, instructions, description, archived_at, ...rest } = a;
   const mcpUsable = !mcp_config_redacted && nonEmpty(mcp_config);
   const envUsable = !custom_env_fetch_failed && nonEmpty(custom_env);
   // mcp_config_redacted / custom_env_fetch_failed alone still flag hadSecrets even
@@ -51,9 +63,10 @@ export function redactAgent(a) {
       had_secrets: hadSecrets,
     },
     hadSecrets,
-    // instructions are written to a sibling .md by the caller (see avatar_file),
-    // never embedded in the JSON record.
+    // instructions and description are written to sibling .md files by the caller
+    // (see avatar_file), never embedded in the JSON record.
     instructions: instructions ?? "",
+    description: description ?? "",
   };
 }
 
@@ -72,9 +85,11 @@ export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squads
     agents: [...seenAgents.values()].map((a) => ({ name: a.name, file: `agents/${slugify(a.name)}.json`, source_id: a.source_id, source_runtime_id: a.source_runtime_id, source_runtime_provider: a.source_runtime_provider ?? null, skill_names: a.skill_names, had_secrets: !!a.had_secrets })),
     squads: (squads ?? []).map((squad) => {
       const file = `squads/${slugify(squad.name)}.json`;
-      const entry = { name: squad.name, file, description: squad.description ?? "", avatar_url: squad.avatar_url ?? null, leader_name: squad.leader_name, members: squad.members };
-      // Instructions go to a sibling .md (see squad write loop); only referenced when non-empty.
+      const entry = { name: squad.name, file, avatar_url: squad.avatar_url ?? null, leader_name: squad.leader_name, members: squad.members };
+      // Instructions and description go to sibling .md files (see squad write
+      // loop); only referenced when non-empty.
       if (squad.instructions) entry.instructions_file = file.replace(/\.json$/, ".md");
+      if (squad.description) entry.description_file = file.replace(/\.json$/, ".description.md");
       return entry;
     }),
     projects: [...seenProjects.values()].map((p) => ({
@@ -96,10 +111,15 @@ function collectSkill(cli, id, skills) {
 }
 
 // Keyed by agent id (so squad leader_id/member_id resolve to names). Stores the
-// normalized agent, its redaction result, and its skill names.
+// normalized agent, its redaction result, and its skill names. Returns
+// `{ archived: true, name }` instead of collecting when the agent is archived —
+// callers reached via a squad/project/explicit id lookup must decide how to
+// handle that (the workspace-listing loop never hits this: listAgents() already
+// excludes archived agents server-side).
 function collectAgent(cli, id, agentsById, skills, providerById) {
   if (agentsById.has(id)) return agentsById.get(id);
   const a = getAgent(cli, id);
+  if (a.archived_at) return { archived: true, name: a.name };
   a.source_runtime_provider = providerById.get(a.runtime_id) ?? null;
   a.custom_env = {};
   a.custom_env_fetch_failed = false;
@@ -117,22 +137,6 @@ function collectAgent(cli, id, agentsById, skills, providerById) {
   return entry;
 }
 
-// Collect a project's portable metadata + its lead agent (bundled, like a squad
-// leader) and github_repo/other resources. Returns the project bundle record.
-function collectProject(cli, id, agentsById, skills, providerById) {
-  const p = getProject(cli, id);
-  let lead_name = null;
-  if (p.lead_type === "agent" && p.lead_id) {
-    lead_name = collectAgent(cli, p.lead_id, agentsById, skills, providerById).raw.name;
-  }
-  return {
-    title: p.title, description: p.description, icon: p.icon,
-    priority: p.priority, status: p.status, due_date: p.due_date, start_date: p.start_date,
-    source_id: id, lead_type: p.lead_type, lead_name, lead_source_id: p.lead_id,
-    resources: getProjectResources(cli, id),
-  };
-}
-
 export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs = nodeFs, download = fetchBinary }) {
   const skills = new Map();       // name -> normalized skill
   const agentsById = new Map();   // id   -> { raw, red, skill_names }
@@ -144,12 +148,34 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
   let providerById = null;
   const getProviderById = () => providerById ??= new Map(listRuntimes(cli).map((r) => [r.id, r.provider]));
 
-  // Collect a squad's agents (leader + members) and return the squad bundle object.
+  // Archived agents skipped anywhere below, deduped by (name, path, detail) —
+  // the operator-facing "why isn't X in my bundle" report.
+  const archivedAgentsSkipped = [];
+  const seenArchivedSkip = new Set();
+  function recordArchivedSkip(name, path, detail) {
+    const key = [name, path, detail ?? ""].join("|");
+    if (seenArchivedSkip.has(key)) return;
+    seenArchivedSkip.add(key);
+    archivedAgentsSkipped.push(detail ? { name, path, detail } : { name, path });
+  }
+
+  // Collect a squad's agents (leader + members) and return the squad bundle
+  // object — or null when the leader is archived, since a squad can't import
+  // without one (the whole squad is excluded from the bundle, not emitted leaderless).
   function collectOneSquad(squadId) {
     const sq = getSquad(cli, squadId);
-    const members = getSquadMembers(cli, squadId).filter((m) => m.member_type === "agent");
-    for (const m of members) collectAgent(cli, m.member_id, agentsById, skills, getProviderById());
-    if (!agentsById.has(sq.leader_id)) collectAgent(cli, sq.leader_id, agentsById, skills, getProviderById());
+    const leaderEntry = collectAgent(cli, sq.leader_id, agentsById, skills, getProviderById());
+    if (leaderEntry.archived) {
+      recordArchivedSkip(leaderEntry.name, "squad leader", sq.name);
+      return null;
+    }
+    const allMembers = getSquadMembers(cli, squadId).filter((m) => m.member_type === "agent");
+    const members = [];
+    for (const m of allMembers) {
+      const entry = collectAgent(cli, m.member_id, agentsById, skills, getProviderById());
+      if (entry.archived) { recordArchivedSkip(entry.name, "squad member", sq.name); continue; }
+      members.push(m);
+    }
     const nameOf = (id) => agentsById.get(id)?.raw.name;
     return {
       name: sq.name, description: sq.description, instructions: sq.instructions, avatar_url: sq.avatar_url,
@@ -158,6 +184,30 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
     };
   }
 
+  // Collect a project's portable metadata + its lead agent (bundled, like a
+  // squad leader) and github_repo/other resources. An archived lead is dropped
+  // (project still exports, just with no lead set) — unlike a squad, a project
+  // has no hard requirement for one.
+  function collectProject(id) {
+    const p = getProject(cli, id);
+    let lead_name = null, lead_type = p.lead_type, lead_source_id = p.lead_id;
+    if (p.lead_type === "agent" && p.lead_id) {
+      const entry = collectAgent(cli, p.lead_id, agentsById, skills, getProviderById());
+      if (entry.archived) {
+        recordArchivedSkip(entry.name, "project lead", p.title);
+        lead_type = null; lead_source_id = null;
+      } else {
+        lead_name = entry.raw.name;
+      }
+    }
+    return {
+      title: p.title, description: p.description, icon: p.icon,
+      priority: p.priority, status: p.status, due_date: p.due_date, start_date: p.start_date,
+      source_id: id, lead_type, lead_name, lead_source_id,
+      resources: getProjectResources(cli, id),
+    };
+  }
+
   // Collect a single autopilot: its assignee (agent, or squad + members + skills)
   // and, when present, the destination-portable project title / subscriber names.
   // Webhook trigger secrets (url/token) are never read into the bundle — only
@@ -166,11 +216,11 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
     const ap = getAutopilot(cli, autopilotId);
     let assignee_name = null;
     if (ap.assignee_type === "agent") {
-      assignee_name = collectAgent(cli, ap.assignee_id, agentsById, skills, getProviderById()).raw.name;
+      const entry = collectAgent(cli, ap.assignee_id, agentsById, skills, getProviderById());
+      assignee_name = entry.archived ? null : entry.raw.name;
     } else if (ap.assignee_type === "squad") {
       const sq = collectOneSquad(ap.assignee_id);
-      squads.push(sq);
-      assignee_name = sq.name;
+      if (sq) { squads.push(sq); assignee_name = sq.name; }
     }
     let project_title = null;
     if (ap.project_id) {
@@ -193,16 +243,24 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
   }
 
   if (scope === "skill") collectSkill(cli, ids.skillId, skills);
-  else if (scope === "agent") collectAgent(cli, ids.agentId, agentsById, skills, getProviderById());
-  else if (scope === "squad") squads.push(collectOneSquad(ids.squadId));
-  else if (scope === "project") projects.push(collectProject(cli, ids.projectId, agentsById, skills, getProviderById()));
-  else if (scope === "projects") for (const p of listProjects(cli)) projects.push(collectProject(cli, p.id, agentsById, skills, getProviderById()));
+  else if (scope === "agent") {
+    const entry = collectAgent(cli, ids.agentId, agentsById, skills, getProviderById());
+    if (entry.archived) throw new Error(`Cannot export agent "${entry.name}": it is archived`);
+  }
+  else if (scope === "squad") { const sq = collectOneSquad(ids.squadId); if (sq) squads.push(sq); }
+  else if (scope === "project") projects.push(collectProject(ids.projectId));
+  else if (scope === "projects") for (const p of listProjects(cli)) projects.push(collectProject(p.id));
   else if (scope === "autopilot") autopilots.push(collectOneAutopilot(ids.autopilotId));
   else if (scope === "all") {
     for (const s of listSkills(cli)) collectSkill(cli, s.id, skills);
     for (const a of listAgents(cli)) collectAgent(cli, a.id, agentsById, skills, getProviderById());
-    for (const sq of listSquads(cli)) squads.push(collectOneSquad(sq.id));
-    for (const p of listProjects(cli)) projects.push(collectProject(cli, p.id, agentsById, skills, getProviderById()));
+    for (const sq of listSquads(cli)) { const built = collectOneSquad(sq.id); if (built) squads.push(built); }
+    for (const p of listProjects(cli)) projects.push(collectProject(p.id));
+    // listAgents() above already excludes archived agents server-side — surface
+    // that exclusion in the report too, not just the squad/project paths.
+    for (const a of listAgentsIncludingArchived(cli)) {
+      if (a.archived_at) recordArchivedSkip(a.name, "workspace listing");
+    }
   }
 
   // Orphan-skill cleanup: drop skills that no exported agent references via its
@@ -261,36 +319,38 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
         record.avatar_file = rel;
       }
     }
-    // Instructions live in a sibling .md for reviewability (same sibling-file
-    // pattern as avatar_file); only written when non-empty.
-    if (red.instructions) {
-      const rel = entry.file.replace(/\.json$/, ".md");
-      fs.writeFileSync(`${outDir}/${rel}`, red.instructions);
-      record.instructions_file = rel;
-    }
+    // Instructions and description each live in a sibling .md for reviewability.
+    writeSidecar(fs, outDir, entry.file, ".md", red.instructions, record, "instructions_file");
+    writeSidecar(fs, outDir, entry.file, ".description.md", red.description, record, "description_file");
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
-  const squadInstrByName = new Map(squads.map((s) => [s.name, s.instructions ?? ""]));
+  const squadByName = new Map(squads.map((s) => [s.name, s]));
   for (const entry of manifest.squads) {
     fs.mkdirSync(`${outDir}/squads`, { recursive: true });
-    if (entry.instructions_file) {
-      fs.writeFileSync(`${outDir}/${entry.instructions_file}`, squadInstrByName.get(entry.name) ?? "");
-    }
+    const s = squadByName.get(entry.name);
+    if (entry.instructions_file) fs.writeFileSync(`${outDir}/${entry.instructions_file}`, s?.instructions ?? "");
+    if (entry.description_file) fs.writeFileSync(`${outDir}/${entry.description_file}`, s?.description ?? "");
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(entry, null, 2));
   }
   const projectByTitle = new Map(projects.map((p) => [p.title, p]));
   for (const entry of manifest.projects) {
     fs.mkdirSync(`${outDir}/projects`, { recursive: true });
-    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(projectByTitle.get(entry.title), null, 2));
+    const record = { ...projectByTitle.get(entry.title) };
+    const desc = record.description; delete record.description;
+    writeSidecar(fs, outDir, entry.file, ".description.md", desc, record, "description_file");
+    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
   const autopilotByTitle = new Map(autopilots.map((a) => [a.title, a]));
   for (const entry of manifest.autopilots) {
     fs.mkdirSync(`${outDir}/autopilots`, { recursive: true });
-    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(autopilotByTitle.get(entry.title), null, 2));
+    const record = { ...autopilotByTitle.get(entry.title) };
+    const desc = record.description; delete record.description;
+    writeSidecar(fs, outDir, entry.file, ".description.md", desc, record, "description_file");
+    fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
   fs.writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2));
   return {
-    manifest, warnings, pruned_skills,
+    manifest, warnings, pruned_skills, archivedAgentsSkipped,
     autopilotWebhookTriggers: autopilots.filter((a) => a.had_webhook_trigger).map((a) => a.title),
   };
 }

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

@@ -1,5 +1,5 @@
 import * as nodeFs from "node:fs";
-import { listSkills, listAgents, 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 } from "./lib.mjs";
 
 // User-facing selectable types are agents/squads/projects/autopilots; skills follow agents.
 export function parseInclude(raw) {
@@ -8,15 +8,18 @@ export function parseInclude(raw) {
   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");
+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 = "") {
@@ -86,8 +89,10 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
   // 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));
-  let created = 0, updated = 0;
-  const existing = listAgents(cli);
+  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.
+  const existing = listAgentsIncludingArchived(cli);
 
   for (const a of manifest.agents) {
     const rec = JSON.parse(fs.readFileSync(`${dir}/${a.file}`, "utf8"));
@@ -98,7 +103,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);
@@ -108,7 +114,14 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
     if (rec.service_tier) common.push("--service-tier", rec.service_tier);
     const match = findByName(existing, rec.name);
     let id;
-    if (match) {
+    if (match && match.archived_at) {
+      // Restored agent then updated exactly like an active-name match — the
+      // matched id is now active, so a re-import of this bundle will find it
+      // via the plain `match` branch below and never restore twice.
+      cli.run(["agent", "restore", match.id]);
+      cli.run(["agent", "update", match.id, "--runtime-id", targetRuntime, ...common]);
+      id = match.id; reused++;
+    } else if (match) {
       cli.run(["agent", "update", match.id, "--runtime-id", targetRuntime, ...common]);
       id = match.id; updated++;
     } else {
@@ -178,7 +191,7 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       }
     }
   }
-  return { idMap, sourceIdMap, created, updated, secretsApplyFailures, avatarApplyFailures, avatarUnsupported, permissionApplyFailures, permissionUnsupported };
+  return { idMap, sourceIdMap, created, updated, reused, secretsApplyFailures, avatarApplyFailures, avatarUnsupported, permissionApplyFailures, permissionUnsupported };
 }
 
 // Rewrites `mention://agent/<id>` links (e.g. `[@dev-backend](mention://agent/<id>)`)
@@ -260,7 +273,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);
@@ -338,7 +352,8 @@ 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.
@@ -448,7 +463,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, secretsApplyFailures: [], avatarApplyFailures: [], avatarUnsupported: [], permissionApplyFailures: [], permissionUnsupported: [] };
+    : { idMap: new Map(), sourceIdMap: new Map(), created: 0, updated: 0, reused: 0, secretsApplyFailures: [], avatarApplyFailures: [], avatarUnsupported: [], permissionApplyFailures: [], permissionUnsupported: [] };
   // 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 })
@@ -460,6 +475,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,6 +498,9 @@ export function importBundle({ cli, dir, runtimeMap, include, fs = nodeFs }) {
     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 },
+    // 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 },
     mentionsRewritten: mentionRes.updated,
     skillIdMap: Object.fromEntries(skillRes.idMap),
     agentIdMap: Object.fromEntries(agentRes.idMap),
@@ -531,6 +550,16 @@ export function preflight({ cli, dir, runtimeMap, include, fs = nodeFs }) {
         ? `${u.srcId} (provider "${u.provider}": ${u.matchCount} matches, expected 1)`
         : `${u.srcId} (no provider recorded)` });
     }
+
+    // Read-only check, mirrors importAgents' restore-and-reuse match — never
+    // calls restore itself, just reports what a real import would do.
+    const existingAgents = listAgentsIncludingArchived(cli);
+    for (const a of manifest.agents ?? []) {
+      const match = findByName(existingAgents, a.name);
+      if (match && match.archived_at) {
+        incompatibilities.push({ type: "agent-archived-will-restore", detail: `${a.name} (archived in destination — import would restore and reuse it)` });
+      }
+    }
   }
 
   if (inc.has("projects")) {

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

@@ -37,13 +37,7 @@ 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).
 
@@ -70,7 +64,12 @@ Pass `--scope all` (with no `--id`) to export the **entire workspace** — every
 
 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.
 
-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`.
+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:
+
+- **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.
+
+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.
 

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

@@ -13,7 +13,7 @@ Import a local Multica bundle (produced by the export skill) into a target works
 You need the exact workspace name as registered in Multica for `--workspace` in the steps below.
 
 - If the user named a target workspace, use it.
-- If the user did **not** name one, default to the **basename of the import folder** — e.g. importing from `export/mx-workspace` defaults the target workspace to `mx-workspace`. State the inferred workspace name to the user before continuing.
+- If the user did **not** name one, default to the **basename of the import folder** — e.g. importing from `export/mx-workspace` defaults the target workspace to `mx-workspace`. State the inferred workspace name to the user before continuing. This default is reliable for whole-workspace bundles (`export/<workspace-name>`); a single-resource bundle nested under `export/<workspace-name>/<slug>-<type>` has the resource slug as its basename, not the workspace — name the target workspace explicitly in that case.
 
 No existence check is needed here: the Step 2 dry-run fails with `Unknown workspace "<name>"` if the inferred workspace is not present in the target account, at which point ask the user for the correct name.
 
@@ -70,7 +70,7 @@ 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.
 
-Instructions are read back from each resource's sibling `.md` (`agents/<slug>.md`, `squads/<slug>.md`) when present — editing that Markdown is the supported way to review and enhance an agent's or squad's instructions before import. Older bundles that predate the split (instructions inline in the JSON, no `instructions_file`) still import unchanged.
+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.
 

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

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

package/plugins/team-share/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "team-share",
   "displayName": "Team Share",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "Onboard your team with an interactive setup menu: install CodeGraph, build the Understand-Anything knowledge graph, and share Claude Code settings — run any combination, all idempotent.",
   "author": {
     "name": "Steven Hoang"

package/plugins/tech-graph/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-graph",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"