@drunkcoding/agents-and-skills 0.0.38 → 0.0.40

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.38",
+      "version": "0.0.40",
       "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.38",
+      "version": "0.0.40",
       "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.38",
+      "version": "0.0.40",
       "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.38",
+      "version": "0.0.40",
       "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.38",
+      "version": "0.0.40",
       "category": "workflow",
       "keywords": [
         "multica",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drunkcoding/agents-and-skills",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "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.38",
+  "version": "0.0.40",
   "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.38",
+  "version": "0.0.40",
   "description": "Export, import, and sync Multica skills, agents, and squads between workspaces via the multica CLI."
 }

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

@@ -54,6 +54,7 @@ export const listRuntimes = (cli) => cli.json(["runtime", "list"]);
 export const listSkills = (cli) => cli.json(["skill", "list"]);
 export const listAgents = (cli) => cli.json(["agent", "list"]);
 export const listSquads = (cli) => cli.json(["squad", "list"]);
+export const listWorkspaceMembers = (cli) => cli.json(["workspace", "member", "list"]);
 
 // Get-wrappers: the ONLY place that knows the raw CLI field names — an
 // explicit allow-list, so unexpected/internal CLI fields never leak into a
@@ -71,7 +72,10 @@ 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,
-    model: a.model, visibility: a.visibility,
+    model: a.model, visibility: a.visibility, avatar_url: a.avatar_url ?? null,
+    service_tier: a.service_tier ?? "",
+    permission_mode: a.permission_mode ?? null,
+    invocation_targets: (a.invocation_targets ?? []).map((t) => ({ target_id: t.target_id, target_type: t.target_type })),
     max_concurrent_tasks: a.max_concurrent_tasks,
     runtime_config: a.runtime_config,
     custom_args: a.custom_args,
@@ -93,7 +97,7 @@ export function getAgentCustomEnv(cli, id) {
 
 export function getSquad(cli, id) {
   const s = cli.json(["squad", "get", id]);
-  return { id: s.id, name: s.name, description: s.description, instructions: s.instructions, leader_id: s.leader_id };
+  return { id: s.id, name: s.name, description: s.description, instructions: s.instructions, leader_id: s.leader_id, avatar_url: s.avatar_url ?? null };
 }
 
 export const getSquadMembers = (cli, id) =>

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

@@ -1,14 +1,37 @@
 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, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { slugify, getSkill, getAgent, getAgentCustomEnv, getSquad, getSquadMembers, listRuntimes, listSkills, listAgents, listSquads, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
 
 const nonEmpty = (v) => v && typeof v === "object" && Object.keys(v).length > 0;
 
+// 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.
+const isImageAvatar = (url) => typeof url === "string" && /^https?:\/\//.test(url);
+
+// Extension for the bundled avatar file, from the URL path; defaults to .png.
+function avatarExt(url) {
+  const m = /\.([a-z0-9]{2,5})(?:[?#]|$)/i.exec(url.split("/").pop() || "");
+  return m ? `.${m[1].toLowerCase()}` : ".png";
+}
+
+// Synchronous binary fetch (keeps exportResource sync). Runs the download in a
+// short-lived node subprocess so no top-level async is needed; returns a Buffer,
+// or null on any failure (non-2xx, network error) — a missing avatar is
+// non-fatal, the export continues with just the recorded avatar_url string.
+export function fetchBinary(url) {
+  const script = "fetch(process.argv[1]).then(r=>{if(!r.ok)process.exit(3);return r.arrayBuffer()}).then(b=>process.stdout.write(Buffer.from(b))).catch(()=>process.exit(4))";
+  const res = spawnSync(process.execPath, ["-e", script, "--", url], { maxBuffer: 64 * 1024 * 1024, timeout: 15_000 });
+  if (res.status !== 0 || !res.stdout?.length) return null;
+  return res.stdout;
+}
+
 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, ...rest } = a;
+  const { id, has_custom_env, mcp_config_redacted, custom_env_fetch_failed, mcp_config, custom_env, skills, runtime_id, instructions, ...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
@@ -16,10 +39,10 @@ export function redactAgent(a) {
   // but couldn't be captured, not just silently see an empty bundle.
   const hadSecrets = mcpUsable || envUsable || !!mcp_config_redacted || !!custom_env_fetch_failed;
   return {
-    // source_id lets import-time mention rewriting map stale `mention://agent/<id>`
-    // links (in this or another agent's/squad's instructions) to the new id.
     record: {
       ...rest,
+      // source_id lets import-time mention rewriting map stale `mention://agent/<id>`
+      // links (in this or another agent's/squad's instructions) to the new id.
       source_id: id,
       source_runtime_id: runtime_id,
       skill_names: [],
@@ -28,10 +51,13 @@ 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: instructions ?? "",
   };
 }
 
-export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squad }) {
+export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squads }) {
   const seenSkills = new Map();
   for (const s of skills) if (!seenSkills.has(s.name)) seenSkills.set(s.name, s);
   const seenAgents = new Map();
@@ -42,7 +68,13 @@ export function buildManifest({ scope, sourceWorkspaceId, skills, agents, squad
     source_workspace_id: sourceWorkspaceId,
     skills: [...seenSkills.values()].map((s) => ({ name: s.name, dir: `skills/${slugify(s.name)}`, source_id: s.source_id })),
     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: squad ? [{ name: squad.name, file: `squads/${slugify(squad.name)}.json`, description: squad.description ?? "", instructions: squad.instructions ?? "", leader_name: squad.leader_name, members: squad.members }] : [],
+    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.
+      if (squad.instructions) entry.instructions_file = file.replace(/\.json$/, ".md");
+      return entry;
+    }),
   };
 }
 
@@ -74,37 +106,43 @@ function collectAgent(cli, id, agentsById, skills, providerById) {
   return entry;
 }
 
-export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs = nodeFs }) {
+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 }
-  let squad = null;
+  const squads = [];
   // Lazy + memoized: only fetched when an agent is actually collected (skips
   // the extra CLI call on skill-only exports).
   let providerById = null;
   const getProviderById = () => providerById ??= new Map(listRuntimes(cli).map((r) => [r.id, r.provider]));
 
-  if (scope === "skill") collectSkill(cli, ids.skillId, skills);
-  if (scope === "agent") collectAgent(cli, ids.agentId, agentsById, skills, getProviderById());
-  if (scope === "squad") {
-    const sq = getSquad(cli, ids.squadId);
-    const members = getSquadMembers(cli, ids.squadId).filter((m) => m.member_type === "agent");
+  // Collect a squad's agents (leader + members) and return the squad bundle object.
+  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 nameOf = (id) => agentsById.get(id)?.raw.name;
-    squad = {
-      name: sq.name,
-      description: sq.description,
-      instructions: sq.instructions,
+    return {
+      name: sq.name, description: sq.description, instructions: sq.instructions, avatar_url: sq.avatar_url,
       leader_name: nameOf(sq.leader_id),
       members: members.map((m) => ({ agent_name: nameOf(m.member_id), role: m.role })),
     };
   }
 
+  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 === "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));
+  }
+
   const manifest = buildManifest({
     scope, sourceWorkspaceId,
     skills: [...skills.values()].map((s) => ({ name: s.name, source_id: s.id })),
     agents: [...agentsById.values()].map((a) => ({ name: a.raw.name, source_id: a.raw.id, source_runtime_id: a.raw.runtime_id, source_runtime_provider: a.raw.source_runtime_provider, skill_names: a.skill_names, had_secrets: a.red.hadSecrets })),
-    squad,
+    squads,
   });
 
   const warnings = [];
@@ -129,10 +167,33 @@ export function exportResource({ cli, scope, ids, outDir, sourceWorkspaceId, fs
     const record = { ...red.record, skill_names };
     if (red.hadSecrets) warnings.push(raw.name);
     fs.mkdirSync(`${outDir}/agents`, { recursive: true });
+    // Download an uploaded-image avatar into the bundle so import can re-upload
+    // it (the only way to set an agent avatar). Emoji avatars stay as the
+    // recorded avatar_url string; a failed download leaves avatar_url without a
+    // file, and import simply won't restore it.
+    if (isImageAvatar(record.avatar_url)) {
+      const rel = entry.file.replace(/\.json$/, `.avatar${avatarExt(record.avatar_url)}`);
+      const bytes = download(record.avatar_url);
+      if (bytes && bytes.length) {
+        fs.writeFileSync(`${outDir}/${rel}`, bytes);
+        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;
+    }
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(record, null, 2));
   }
+  const squadInstrByName = new Map(squads.map((s) => [s.name, s.instructions ?? ""]));
   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) ?? "");
+    }
     fs.writeFileSync(`${outDir}/${entry.file}`, JSON.stringify(entry, null, 2));
   }
   fs.writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2));
@@ -148,8 +209,8 @@ function main() {
   const out       = get("--out");
   const workspace = get("--workspace"); // optional: source workspace name
 
-  if (!scope || !id || !out) {
-    console.error("Usage: multica-export.mjs --scope <skill|agent|squad> --id <id> --out <dir> [--workspace <name>]");
+  if (!scope || !out || (scope !== "all" && !id)) {
+    console.error("Usage: multica-export.mjs --scope <skill|agent|squad|all> --id <id> --out <dir> [--workspace <name>]  (--id not needed for --scope all)");
     process.exit(1);
   }
 
@@ -164,7 +225,8 @@ function main() {
   if (scope === "skill")       ids.skillId  = id;
   else if (scope === "agent")  ids.agentId  = id;
   else if (scope === "squad")  ids.squadId  = id;
-  else { console.error(`Unknown scope "${scope}" — use skill|agent|squad`); process.exit(1); }
+  else if (scope === "all")    { /* whole workspace — no id */ }
+  else { console.error(`Unknown scope "${scope}" — use skill|agent|squad|all`); process.exit(1); }
 
   const result = exportResource({ cli, scope, ids, outDir: out, sourceWorkspaceId, fs: nodeFs });
   console.log(JSON.stringify(result, null, 2));

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

@@ -1,5 +1,15 @@
 import * as nodeFs from "node:fs";
-import { listSkills, listAgents, listSquads, listRuntimes, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+import { listSkills, listAgents, listSquads, listRuntimes, listWorkspaceMembers, getSquadMembers, findByName, makeCli, realExec, requireAuth, resolveWorkspaceId } from "./lib.mjs";
+
+// 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");
+  }
+  return rec.instructions ?? "";
+}
 
 // Relative paths of every file under root (recursing into subdirs like scripts/).
 function walkSkillFiles(fs, root, rel = "") {
@@ -55,10 +65,20 @@ export function importSkills({ cli, manifest, dir, fs = nodeFs }) {
   return { idMap, created, updated };
 }
 
+// True when a resource already carries an avatar (uploaded image or emoji).
+const hasAvatar = (r) => !!(r && typeof r.avatar_url === "string" && r.avatar_url);
+
 export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs = nodeFs }) {
   const idMap = new Map();
   const sourceIdMap = new Map(); // source agent id -> new agent id, for mention rewriting
   const secretsApplyFailures = [];
+  const avatarApplyFailures = [];   // image upload rejected
+  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
+  // 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);
 
@@ -72,11 +92,13 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       "--max-concurrent-tasks", String(rec.max_concurrent_tasks ?? 6),
     ];
     if (rec.description) common.push("--description", rec.description);
-    if (rec.instructions) common.push("--instructions", rec.instructions);
+    const instructions = readInstructions(fs, dir, rec);
+    if (instructions) common.push("--instructions", instructions);
     if (rec.model) common.push("--model", rec.model);
     if (rec.thinking_level) common.push("--thinking-level", rec.thinking_level);
     if (rec.runtime_config && Object.keys(rec.runtime_config).length) common.push("--runtime-config", JSON.stringify(rec.runtime_config));
     if (Array.isArray(rec.custom_args) && rec.custom_args.length) common.push("--custom-args", JSON.stringify(rec.custom_args));
+    if (rec.service_tier) common.push("--service-tier", rec.service_tier);
     const match = findByName(existing, rec.name);
     let id;
     if (match) {
@@ -91,6 +113,39 @@ 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(",")]);
 
+    // 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.
+    if (!hasAvatar(match)) {
+      if (rec.avatar_file) {
+        try {
+          cli.run(["agent", "avatar", id, "--file", `${dir}/${rec.avatar_file}`]);
+        } catch {
+          avatarApplyFailures.push(rec.name);
+        }
+      } else if (typeof rec.avatar_url === "string" && rec.avatar_url.startsWith("emoji:")) {
+        avatarUnsupported.push(rec.name);
+      }
+    }
+
+    // Restore member-specific public_to sharing that --visibility can't express.
+    // (private and workspace-wide public_to already round-trip via --visibility.)
+    if (rec.permission_mode === "public_to") {
+      const memberTargets = (rec.invocation_targets ?? []).filter((t) => t.target_type === "user");
+      if (memberTargets.length) {
+        const resolvable = memberTargets.map((t) => t.target_id).filter((tid) => getDestMemberIds().has(tid));
+        if (!resolvable.length) {
+          permissionUnsupported.push(rec.name);
+        } else {
+          try {
+            cli.run(["agent", "update", id, "--permission-mode", "public_to", ...resolvable.flatMap((tid) => ["--public-to-member", tid])]);
+          } catch {
+            permissionApplyFailures.push(rec.name);
+          }
+        }
+      }
+    }
+
     // mcp_config/custom_env carry real secrets. Each is applied via its OWN
     // follow-up call, never bundled into the create/update call above — that
     // keeps a rejected secret from failing the whole agent create/update, and
@@ -116,7 +171,7 @@ export function importAgents({ cli, manifest, dir, skillIdMap, runtimeMap, fs =
       }
     }
   }
-  return { idMap, sourceIdMap, created, updated, secretsApplyFailures };
+  return { idMap, sourceIdMap, created, updated, secretsApplyFailures, avatarApplyFailures, avatarUnsupported, permissionApplyFailures, permissionUnsupported };
 }
 
 // Rewrites `mention://agent/<id>` links (e.g. `[@dev-backend](mention://agent/<id>)`)
@@ -140,9 +195,10 @@ export function rewriteAgentMentions({ cli, manifest, dir, agentIdMap, sourceIdM
   let updated = 0;
   for (const a of manifest.agents) {
     const rec = JSON.parse(fs.readFileSync(`${dir}/${a.file}`, "utf8"));
-    if (!rec.instructions) continue;
-    const rewritten = rewriteMentions(rec.instructions, sourceIdMap);
-    if (rewritten === rec.instructions) continue;
+    const instructions = readInstructions(fs, dir, rec);
+    if (!instructions) continue;
+    const rewritten = rewriteMentions(instructions, sourceIdMap);
+    if (rewritten === instructions) continue;
     cli.run(["agent", "update", agentIdMap.get(rec.name), "--instructions", rewritten]);
     updated++;
   }
@@ -165,6 +221,13 @@ export function importSquad({ cli, squad, agentIdMap, sourceIdMap }) {
     const out = cli.run(["squad", "create", "--name", squad.name, "--leader", leaderId, "--description", squad.description ?? "", ...instr]);
     id = JSON.parse(out).id; created++;
   }
+  // Avatar: squads accept only an avatar-url string (emoji or URL) via
+  // `squad update`. Set it only when the target squad has none — never clobber
+  // an existing squad's avatar.
+  if (!hasAvatar(match) && squad.avatar_url) {
+    cli.run(["squad", "update", id, "--avatar-url", squad.avatar_url]);
+  }
+
   // Add non-leader members, skipping any already present so re-runs are idempotent.
   const present = new Set(getSquadMembers(cli, id).map((m) => m.member_id));
   for (const m of squad.members) {
@@ -226,18 +289,29 @@ export function importBundle({ cli, dir, runtimeMap, fs = nodeFs }) {
   const agentRes = importAgents({ cli, manifest, dir, skillIdMap: skillRes.idMap, runtimeMap: effective, fs });
   // Runs after every agent exists so forward-referencing mentions resolve.
   const mentionRes = rewriteAgentMentions({ cli, manifest, dir, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap, fs });
-  let squadRes = { newId: null, created: 0, updated: 0 };
-  if (manifest.squads?.length) squadRes = importSquad({ cli, squad: manifest.squads[0], agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
+  const squadIdMap = new Map();
+  let squadsCreated = 0, squadsUpdated = 0;
+  for (const squad of manifest.squads ?? []) {
+    squad.instructions = readInstructions(fs, dir, squad);
+    const r = importSquad({ cli, squad, agentIdMap: agentRes.idMap, sourceIdMap: agentRes.sourceIdMap });
+    squadIdMap.set(squad.name, r.newId);
+    squadsCreated += r.created;
+    squadsUpdated += r.updated;
+  }
 
   return {
-    created: { skills: skillRes.created, agents: agentRes.created, squads: squadRes.created },
-    updated: { skills: skillRes.updated, agents: agentRes.updated, squads: squadRes.updated },
+    created: { skills: skillRes.created, agents: agentRes.created, squads: squadsCreated },
+    updated: { skills: skillRes.updated, agents: agentRes.updated, squads: squadsUpdated },
     mentionsRewritten: mentionRes.updated,
     skillIdMap: Object.fromEntries(skillRes.idMap),
     agentIdMap: Object.fromEntries(agentRes.idMap),
-    squadId: squadRes.newId,
+    squadIdMap: Object.fromEntries(squadIdMap),
     secretsReminder: (manifest.agents ?? []).filter((a) => a.had_secrets).map((a) => a.name),
     secretsApplyFailures: agentRes.secretsApplyFailures,
+    avatarApplyFailures: agentRes.avatarApplyFailures,
+    avatarUnsupported: agentRes.avatarUnsupported,
+    permissionApplyFailures: agentRes.permissionApplyFailures,
+    permissionUnsupported: agentRes.permissionUnsupported,
   };
 }
 

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

@@ -44,13 +44,17 @@ where `<slug>` is a lowercased, hyphenated form of the resource name.
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-export.mjs" \
-  --scope <type> \
+  --scope <type|all> \
   --id <id> \
   --out <dir> \
   [--workspace <workspace-name>]
 ```
 
-The script writes `manifest.json`, skill SKILL.md files, agent JSON files, and squad JSON files into `<dir>`.
+Pass `--scope all` (with no `--id`) to export the **entire workspace** — every skill, agent, and squad — 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>`. 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`.
+
+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.
 
 ## Step 5 — Report results
 

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

@@ -40,13 +40,21 @@ node "${CLAUDE_PLUGIN_ROOT}/scripts/multica-import.mjs" \
 
 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.
+
+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.
+
 ## Step 3 — Report results
 
 Parse the JSON output and report:
 
 - Created and updated counts for skills, agents, and squads.
 - Name-to-ID maps for skills and agents (`skillIdMap`, `agentIdMap`).
-- Squad ID if a squad was imported.
+- `squadIdMap`: name-to-ID map for every squad imported.
 - `mentionsRewritten`: how many agents had an agent-mention link rewritten to its new id.
 - If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents' bundle files contained custom environment variables or MCP config in PLAINTEXT — the source export directory should be treated as sensitive: `<agent-name>`."
 - If `secretsApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: mcp_config or custom_env failed to apply to the following agents during import (the agent itself was still created/updated) — set them manually in the Multica UI: `<agent-name>`."
+- If `avatarApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: the avatar image failed to upload for the following agents — set it manually in the Multica UI: `<agent-name>`."
+- If `avatarUnsupported` is non-empty, surface every agent name verbatim with: "NOTE: the following agents had an emoji avatar at the source, which the CLI cannot set on an agent — set it manually in the Multica UI: `<agent-name>`."
+- If `permissionApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: member-specific sharing failed to apply for the following agents — set their invocation permissions manually in the Multica UI: `<agent-name>`."
+- If `permissionUnsupported` is non-empty, surface every agent name verbatim with: "NOTE: the following agents were shared with specific members at the source, but none of those users exist in the target workspace — re-share manually if needed: `<agent-name>`."

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

@@ -49,6 +49,12 @@ Parse the JSON output and report:
 
 - Created and updated counts for skills, agents, and squads.
 - Name-to-ID maps (`skillIdMap`, `agentIdMap`).
-- Squad ID if a squad was synced.
+- `squadIdMap`: name-to-ID map for every squad synced.
 - If `secretsReminder` is non-empty, surface every agent name verbatim with: "WARNING: the following agents' bundle files contained custom environment variables or MCP config in PLAINTEXT — the temporary export directory (already cleaned up) briefly held these secrets in plaintext: `<agent-name>`."
 - If `secretsApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: mcp_config or custom_env failed to apply to the following agents during sync (the agent itself was still created/updated) — set them manually in the Multica UI: `<agent-name>`."
+- If `avatarApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: the avatar image failed to upload for the following agents — set it manually in the destination workspace: `<agent-name>`."
+- If `avatarUnsupported` is non-empty, surface every agent name verbatim with: "NOTE: the following agents had an emoji avatar at the source, which the CLI cannot set on an agent — set it manually in the destination workspace: `<agent-name>`."
+- If `permissionApplyFailures` is non-empty, surface every agent name verbatim with: "WARNING: member-specific sharing failed to apply for the following agents — set their invocation permissions manually in the destination workspace: `<agent-name>`."
+- If `permissionUnsupported` is non-empty, surface every agent name verbatim with: "NOTE: the following agents were shared with specific members at the source, but none of those users exist in the destination workspace — re-share manually if needed: `<agent-name>`."
+
+Avatars sync automatically, but **only when the destination resource has none** — an existing agent or squad that already carries an avatar is never overwritten.

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

@@ -1,7 +1,7 @@
 {
   "name": "plugin-validator",
   "displayName": "Plugin Validator",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "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.38",
+  "version": "0.0.40",
   "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.38",
+  "version": "0.0.40",
   "description": "Step-by-step wizard for generating technical diagrams as SVG+PNG.",
   "author": {
     "name": "steven"