@ninemind/agentgem 0.1.0 → 0.2.0

package/README.md

@@ -3,9 +3,10 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/@ninemind/agentgem"><img src="https://img.shields.io/npm/v/%40ninemind%2Fagentgem?color=9a3324&label=npm" alt="npm version"></a>
   <a href="https://github.com/ninemindai/agentgem/actions/workflows/ci.yml"><img src="https://github.com/ninemindai/agentgem/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9a3324" alt="MIT license"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-LTS-1f6b4f" alt="Node LTS"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/%40ninemind%2Fagentgem?color=1f6b4f" alt="Node version"></a>
   <a href="https://agentback.dev"><img src="https://img.shields.io/badge/built_on-AgentBack-b08436" alt="Built on AgentBack"></a>
   <a href="docs/concepts.md"><img src="https://img.shields.io/badge/MCP-native-211c15" alt="MCP-native"></a>
 </p>
@@ -36,29 +37,32 @@ call exactly the same thing.
   re-reading raw config.
 - **Composition** — the manifest/lock split lets small, focused Gems be reconciled into
   larger agents with a single re-resolved lock, not a pile of overlapping config.
+- **Workflow-aware recommendations** — [Analyze](docs/analyze.md) scans your agent's
+  session history to see which skills, MCP servers, and hooks you actually use, and
+  suggests ready-to-build Gems grouped by recurring workflow.
 - **Deploy targets** — Eve and OpenAI Sandbox (code-gen), Flue (materialize, deployable to
   Cloudflare), and Bedrock AgentCore (managed backend); code-gen targets share a common
   `compose` step.
+- **Agent-to-agent (A2A)** — export a Gem as an [A2A](docs/a2a.md) Agent Card or a
+  runnable A2A server so other agents can discover and call it.
+- **A native desktop app** — a [macOS/Windows/Linux build](docs/desktop.md) alongside the
+  `npx` CLI, hosting the same local server in its own window.
 - **A GitHub-backed registry** — publish, resolve, merge, and install composable Gems over
   the same archive format.
 - **An agent-native path** — every operation is also an MCP tool, so your local agent can
   build Gems over `/mcp` with no browser involved.
 
-## Usage
+## Quickstart
 
-Requires Node.js ≥ 22 and a coding-agent config at `~/.claude`.
+Needs Node.js ≥ 22. From the directory of the agent project you want to package,
+run it without installing:
 
 ```bash
-npx @ninemind/agentgem              # run without installing
-# or install the `agentgem` command globally:
-npm install -g @ninemind/agentgem
-agentgem                            # → http://127.0.0.1:4317
-agentgem --port 8080                # override the port (also honors $PORT)
+npx @ninemind/agentgem         # npm
+pnpm dlx @ninemind/agentgem    # pnpm
 ```
 
-The server starts on `127.0.0.1` (default port `4317`) and prints:
-
-```
+```text
 agentgem listening at http://127.0.0.1:4317
   UI:       http://127.0.0.1:4317/
   API:      http://127.0.0.1:4317/api/inventory  ·  POST http://127.0.0.1:4317/api/gem
@@ -66,33 +70,63 @@ agentgem listening at http://127.0.0.1:4317
   MCP:      http://127.0.0.1:4317/mcp
 ```
 
+Open **<http://127.0.0.1:4317/>**, then:
+
+1. **Open a testbed** — click *Create / open testbed…*. AgentGem detects the project
+   you launched from (it has a `.claude`/`.codex`) and also lists ones from your
+   Claude/Codex session history. Pick it and click *Use this*.
+2. **Pick artifacts** — the project's skills / MCP servers / `CLAUDE.md` show on the
+   left; *Import from machine…* pulls in global ones. Tick what you want, name the Gem.
+3. **Watch it seal** — the live `gem.json` renders with every secret as `<redacted>`.
+   Download it — that archive is what every target and the registry consume.
+
+<p align="center">
+  <img src="docs/screenshot.png" alt="The AgentGem Gem Builder: selected skills and MCP servers on the left, the live gem.json on the right with every secret shown as <redacted>" width="100%">
+</p>
+
+Prefer a persistent command? Install it globally:
+
+```bash
+npm install -g @ninemind/agentgem     # npm
+pnpm add -g @ninemind/agentgem        # pnpm
+agentgem --port 8080                  # honors $PORT; append ?dir=/path/to/.claude for another config
+```
+
 | Path        | What it is                                              |
 | ----------- | ------------------------------------------------------- |
 | `/`         | The Gem Builder web UI                                  |
 | `/explorer` | Swagger UI for the REST API (from the OpenAPI document) |
 | `/mcp`      | The MCP endpoint — the same contract, for your agent    |
 
-Open `/`, tick the skills / MCP servers / `CLAUDE.md` you want, name the Gem, and watch
-the live `gem.json` render with secrets already shown as `<redacted>`. Download it — that
-archive is what every target and the registry consume.
-
-Append `?dir=/path/to/.claude` to introspect a config directory other than the
-default `~/.claude`.
-
 ### From source
 
-To hack on AgentGem, clone the repo and use [pnpm](https://pnpm.io/) (AgentBack
-uses legacy decorators, so it builds with `tsc`, then runs `dist/`):
+To hack on AgentGem, clone the repo. It's a [pnpm](https://pnpm.io/) project
+(`npm` works too), and AgentBack uses legacy decorators, so it builds with `tsc`
+then runs `dist/`:
 
 ```bash
-pnpm install
-pnpm dev        # build + start in one step (→ node dist/index.js)
-pnpm test       # tsc -b && vitest run — tests run against compiled dist/
-pnpm clean      # rm -rf dist *.tsbuildinfo (run before testing after renames/moves)
+pnpm install     # or: npm install
+pnpm dev         # or: npm run dev   — build + start in one step
+pnpm test        # or: npm test      — tsc -b && vitest run, against compiled dist/
+pnpm clean       # or: npm run clean — rm -rf dist *.tsbuildinfo (run before re-testing after moves)
 ```
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
 
+### Desktop app
+
+Prefer a double-click app over the CLI? AgentGem ships a native **desktop build**
+for macOS, Windows, and Linux — download it from
+[Releases](https://github.com/ninemindai/agentgem/releases) (a `desktop-v*` build).
+It hosts the same local server in its own window, adds a native folder picker, app
+menu, and system tray, and never sends secrets off your machine.
+
+> The builds are currently **unsigned**: on macOS right-click → **Open**, on Windows
+> choose **More info → Run anyway** the first time.
+
+To run or package it from source, see the [desktop guide](docs/desktop.md) — in
+short, `pnpm -C desktop dev` to run, `pnpm -C desktop dist` to build installers.
+
 ## Layering
 
 Depends on AgentBack: `@agentback/core` (lifecycle), `@agentback/rest` +
@@ -103,8 +137,11 @@ API, and the MCP endpoint are three boundaries over one set of Zod contracts —
 
 For deeper reference, see [`docs/`](docs/index.md):
 [getting started](docs/getting-started.md) ·
+[desktop app](docs/desktop.md) ·
+[analyze](docs/analyze.md) ·
 [concepts](docs/concepts.md) ·
 [targets & deploy](docs/targets.md) ·
+[A2A](docs/a2a.md) ·
 [registry](docs/registry.md).
 
 ## License

package/dist/gem/acpRecommender.js

@@ -0,0 +1,303 @@
+// src/gem/acpRecommender.ts
+//
+// Turns a deterministic WorkflowSignal + inventory into a GemRecommendation by
+// grounding a local ACP coding agent (Claude) with the signal and asking it to
+// cluster/name/justify a Gem. The agent only ranks and explains — its output is
+// re-validated against the inventory (the source of truth), and any failure
+// degrades to a deterministic frequency-based recommendation. Never throws.
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { Readable, Writable } from "node:stream";
+import { agentgemHome } from "../resolveDir.js";
+// Instructions are a boolean on ProjectSelection, not a named include.
+const SELECTABLE = ["skill", "mcp_server", "hook"];
+// Pinned Claude ACP adapter (npm: @agentclientprotocol/claude-agent-acp).
+export const CLAUDE_AGENT = { id: "claude-code", name: "Claude Code", command: ["claude-agent-acp"] };
+// Neutral working dir for the recommender's ACP session. We do NOT open the
+// session in the analyzed project, or claude-agent-acp would log a session
+// transcript THERE — inflating that project's own session history (skewing
+// future analyses and busting the per-project cache). The agent only reasons
+// over the JSON brief, so its cwd is irrelevant to the result.
+export function analysisWorkspace() { return join(agentgemHome(), ".agentgem", "analysis"); }
+let testConnectFn = null;
+/** Test-only seam: route recommendWorkflow through an in-process fake agent. */
+export function setConnectFnForTests(fn) { testConnectFn = fn; }
+// ── Deterministic analysis (fallback + the agent's baseline) ─────────────────
+// One frequency-based candidate. Multi-candidate splitting is the agent's value-add;
+// the deterministic fallback stays a single coherent Gem.
+export function deterministicAnalysis(signal) {
+    const include = [];
+    let includeInstructions = false;
+    for (const a of signal.artifacts) {
+        if (a.type === "instructions") {
+            if (a.invocations > 0)
+                includeInstructions = true;
+            continue;
+        }
+        if (!SELECTABLE.includes(a.type))
+            continue;
+        if (a.invocations > 0 && a.confidence === "high")
+            include.push({ type: a.type, name: a.name, reason: `${a.invocations} use(s) across ${a.sessionsUsedIn} session(s)`, root: a.root });
+    }
+    const gaps = signal.unresolved.filter((u) => u.kind !== "builtin").map((u) => u.name);
+    const candidates = include.length ? [{
+            name: signal.root.split("/").pop() || "workflow",
+            description: `Recommended from ${signal.sessions.scanned} session(s) of usage.`,
+            root: signal.root,
+            includeInstructions,
+            include,
+            confidence: "medium",
+        }] : [];
+    return { candidates, gaps };
+}
+/**
+ * Map a validated candidate to a GemSelection. Global artifacts (root===null)
+ * go top-level; project artifacts go under projects[root]; instructions are a
+ * project boolean. buildGem resolves both namespaces from introspectAll.
+ */
+export function recommendationToSelection(c) {
+    const sel = {};
+    const globalNames = (t) => c.include.filter((i) => i.type === t && i.root === null).map((i) => i.name);
+    const gSkills = globalNames("skill"), gMcp = globalNames("mcp_server"), gHooks = globalNames("hook");
+    if (gSkills.length)
+        sel.skills = gSkills;
+    if (gMcp.length)
+        sel.mcpServers = gMcp;
+    if (gHooks.length)
+        sel.hooks = gHooks;
+    const projects = {};
+    const ensure = (root) => (projects[root] ??= {});
+    for (const i of c.include) {
+        if (i.root === null)
+            continue;
+        const ps = ensure(i.root);
+        if (i.type === "skill")
+            (ps.skills ??= []).push(i.name);
+        else if (i.type === "mcp_server")
+            (ps.mcpServers ??= []).push(i.name);
+        else if (i.type === "hook")
+            (ps.hooks ??= []).push(i.name);
+    }
+    if (c.includeInstructions)
+        ensure(c.root).includeInstructions = true;
+    if (Object.keys(projects).length)
+        sel.projects = projects;
+    return sel;
+}
+// Pull the first {...} block out of an agent message that may wrap JSON in prose/fences.
+function extractJson(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    return start >= 0 && end > start ? text.slice(start, end + 1) : text;
+}
+/**
+ * Validate a raw agent response against the inventory. Each candidate's include
+ * names are checked against the inventory; hallucinated names are dropped
+ * (logged) and a candidate with no surviving includes is discarded. On any
+ * structural failure or zero valid candidates, fall back to the deterministic
+ * analysis. The inventory is authoritative.
+ */
+export function validateAnalysis(raw, inv, signal) {
+    const fallback = deterministicAnalysis(signal);
+    let obj = raw;
+    if (typeof raw === "string") {
+        try {
+            obj = JSON.parse(extractJson(raw));
+        }
+        catch {
+            return fallback;
+        }
+    }
+    if (!obj || typeof obj !== "object" || !Array.isArray(obj.candidates))
+        return fallback;
+    const g = inv.global ?? { skills: [], mcpServers: [], hooks: [] };
+    // Resolve a name to its namespace: project root if present there, else global
+    // (null), else undefined (hallucinated). Project is preferred on collision.
+    const proj = {
+        skill: new Set(inv.project.skills.map((s) => s.name)),
+        mcp_server: new Set(inv.project.mcpServers.map((m) => m.name)),
+        hook: new Set(inv.project.hooks.map((h) => h.name)),
+    };
+    const glob = {
+        skill: new Set(g.skills.map((s) => s.name)),
+        mcp_server: new Set(g.mcpServers.map((m) => m.name)),
+        hook: new Set(g.hooks.map((h) => h.name)),
+    };
+    const resolveRoot = (type, name) => proj[type]?.has(name) ? inv.project.root : glob[type]?.has(name) ? null : undefined;
+    const candidates = [];
+    for (const c of obj.candidates) {
+        if (!c || typeof c !== "object" || !Array.isArray(c.include))
+            continue;
+        const include = [];
+        for (const it of c.include) {
+            if (!it || !SELECTABLE.includes(it.type) || typeof it.name !== "string")
+                continue;
+            const root = resolveRoot(it.type, it.name);
+            if (root === undefined) {
+                console.error(`workflow: dropping hallucinated ${it.type} '${it.name}'`);
+                continue;
+            }
+            include.push({ type: it.type, name: it.name, reason: typeof it.reason === "string" ? it.reason : "", root });
+        }
+        if (!include.length)
+            continue;
+        candidates.push({
+            name: typeof c.name === "string" ? c.name : (signal.root.split("/").pop() || "workflow"),
+            description: typeof c.description === "string" ? c.description : "",
+            root: signal.root,
+            includeInstructions: c.includeInstructions === true,
+            include,
+            confidence: ["high", "medium", "low"].includes(c.confidence) ? c.confidence : "medium",
+        });
+    }
+    if (!candidates.length)
+        return fallback;
+    const gaps = Array.isArray(obj.gaps) ? obj.gaps.filter((g) => typeof g === "string") : fallback.gaps;
+    return { candidates, gaps };
+}
+// ── The agent run ────────────────────────────────────────────────────────────
+const GROUNDING = (signalJson, inventoryJson) => `You recommend reusable "Gems" — bundles of installed artifacts for a recurring workflow.\n` +
+    `A project often exercises SEVERAL distinct flows (e.g. diagram generation vs web scraping). ` +
+    `Use the per-session "shapes" (sets of artifacts used together) plus co-occurrence to identify each ` +
+    `recurring flow, and propose ONE Gem per flow.\n` +
+    `The inventory has PROJECT artifacts (scoped to this repo) and GLOBAL artifacts (from the machine / ` +
+    `installed plugins). Include either by exact name — both get bundled into the Gem.\n` +
+    `USAGE SIGNAL (authoritative — invocation counts and shapes are facts):\n${signalJson}\n\n` +
+    `INVENTORY (the only artifacts that exist — never invent names outside this):\n${inventoryJson}\n\n` +
+    `Return ONLY a JSON object: {"candidates":[{"name","description","includeInstructions":bool,` +
+    `"include":[{"type":"skill"|"mcp_server"|"hook","name","reason"}],"confidence":"high"|"medium"|"low"}],"gaps":[string]}.\n` +
+    `Each candidate is one coherent flow. Prefer 1–4 candidates; don't split trivially or duplicate. Use exact inventory names.`;
+// Skill bodies are large; send descriptions only. Global section is limited to
+// artifacts that actually fired (the global catalog can be huge) — `usedGlobal`.
+function trimInventory(inv, usedGlobal) {
+    const p = inv.project;
+    const g = inv.global ?? { skills: [], mcpServers: [], hooks: [] };
+    return {
+        projectRoot: p.root, name: p.name,
+        project: {
+            skills: p.skills.map((s) => ({ name: s.name, description: s.description ?? "" })),
+            mcpServers: p.mcpServers.map((m) => ({ name: m.name, transport: m.transport })),
+            instructions: p.instructions.map((i) => ({ name: i.name })),
+            hooks: p.hooks.map((h) => ({ name: h.name, event: h.event, matcher: h.matcher ?? null })),
+        },
+        global: {
+            skills: g.skills.filter((s) => usedGlobal.has(s.name)).map((s) => ({ name: s.name })),
+            mcpServers: g.mcpServers.filter((m) => usedGlobal.has(m.name)).map((m) => ({ name: m.name })),
+            hooks: g.hooks.filter((h) => usedGlobal.has(h.name)).map((h) => ({ name: h.name, event: h.event })),
+        },
+    };
+}
+function withTimeout(p, ms) {
+    return Promise.race([p, new Promise((_, rej) => setTimeout(() => rej(new Error(`agent timeout after ${ms}ms`)), ms))]);
+}
+/**
+ * Analyse `signal`/`inventory` into candidate Gems. Total: never throws. On any
+ * agent error/timeout/junk, returns the deterministic analysis with degraded:true.
+ */
+export async function recommendWorkflow(signal, inv, opts = {}) {
+    const connectFn = opts.connectFn ?? testConnectFn ?? defaultConnectFn;
+    const timeoutMs = opts.timeoutMs ?? 60_000;
+    let conn = null;
+    let handle = null;
+    try {
+        const usedGlobal = new Set(signal.artifacts.filter((a) => a.root === null && a.invocations > 0).map((a) => a.name));
+        const trimmedInv = trimInventory(inv, usedGlobal);
+        conn = await connectFn(CLAUDE_AGENT, null);
+        handle = await conn.ctx.open(analysisWorkspace()); // neutral cwd — don't pollute the project
+        await handle.setMode("plan"); // explicit — never edits files
+        const prompt = GROUNDING(JSON.stringify(signal), JSON.stringify(trimmedInv));
+        const text = await withTimeout(handle.promptText(prompt, opts.onDelta), timeoutMs);
+        return { analysis: validateAnalysis(text, inv, signal), degraded: false };
+    }
+    catch (err) {
+        console.error("workflow: recommender fell back to deterministic:", err.message);
+        return { analysis: deterministicAnalysis(signal), degraded: true };
+    }
+    finally {
+        try {
+            handle?.dispose();
+        }
+        catch { /* ignore */ }
+        try {
+            conn?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Real connect: spawn the ACP adapter and bridge stdio via the SDK. Wrapped so
+ * the rest of the module is SDK-agnostic. Mirrors agentback console-chat's
+ * defaultConnectFn, minus the workspace PATH walk and permission routing — this
+ * agent runs in plan mode and we auto-deny any permission request.
+ *
+ * NEEDS LIVE VALIDATION: stdio bridging + set_mode against claude-agent-acp.
+ */
+export const defaultConnectFn = async (descriptor) => {
+    const { client, ndJsonStream } = await import("@agentclientprotocol/sdk");
+    const [bin, ...args] = descriptor.command;
+    const child = spawn(bin, args, { stdio: ["pipe", "pipe", "inherit"], env: process.env });
+    await new Promise((resolve, reject) => {
+        child.once("spawn", () => resolve());
+        child.once("error", (e) => reject(new Error(`failed to spawn ${bin}: ${e.message}`)));
+    });
+    const app = client({ name: "agentgem-workflow-recommender" });
+    // Auto-deny any permission request — the recommender must not run tools.
+    app.onRequest?.("session/request_permission", async () => ({ outcome: { outcome: "cancelled" } }));
+    const input = Readable.toWeb(child.stdout);
+    const output = Writable.toWeb(child.stdin);
+    const connection = app.connect(ndJsonStream(output, input));
+    const agentCtx = connection.agent;
+    const ctx = {
+        async open(cwd) {
+            try {
+                mkdirSync(cwd, { recursive: true });
+            }
+            catch { /* best-effort */ }
+            const session = await agentCtx.buildSession(cwd).start();
+            const sessionId = session.sessionId;
+            return {
+                async setMode(mode) {
+                    try {
+                        await agentCtx.request("session/set_mode", { sessionId, modeId: mode });
+                    }
+                    catch { /* best-effort */ }
+                },
+                async promptText(text, onDelta) {
+                    let out = "";
+                    void session.prompt(text);
+                    for (;;) {
+                        const msg = await session.nextUpdate();
+                        if (msg.kind === "stop")
+                            break;
+                        if (msg.kind === "session_update" && msg.update?.sessionUpdate === "agent_message_chunk") {
+                            const block = msg.update.content;
+                            if (block?.type === "text" && typeof block.text === "string") {
+                                out += block.text;
+                                onDelta?.(block.text);
+                            }
+                        }
+                    }
+                    return out;
+                },
+                dispose() { try {
+                    session.dispose?.();
+                }
+                catch { /* ignore */ } },
+            };
+        },
+    };
+    return {
+        ctx,
+        close: () => {
+            try {
+                connection.close();
+            }
+            catch { /* ignore */ }
+            try {
+                child.kill();
+            }
+            catch { /* ignore */ }
+        },
+    };
+};

package/dist/gem/analysisCache.js

@@ -0,0 +1,51 @@
+// src/gem/analysisCache.ts
+//
+// Per-project cache of the (expensive, ~15-20s) workflow analysis. Keyed by the
+// project root and a transcript "token" that changes whenever a session is added
+// or updated — so the cache stays valid until the project's sessions change, and
+// revisiting a project to pick a different candidate is instant. Best-effort and
+// persistent (~/.agentgem/analysis-cache.json); failures never throw.
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { agentgemHome } from "../resolveDir.js";
+const MAX_ENTRIES = 50;
+function cachePath() { return join(agentgemHome(), ".agentgem", "analysis-cache.json"); }
+/** A cheap validity token: transcript count + newest mtime. New/updated session → new token. */
+export function transcriptToken(paths) {
+    let maxMs = 0;
+    for (const p of paths) {
+        try {
+            const m = statSync(p).mtimeMs;
+            if (m > maxMs)
+                maxMs = m;
+        }
+        catch { /* gone — ignore */ }
+    }
+    return `${paths.length}:${Math.round(maxMs)}`;
+}
+function readAll() {
+    try {
+        const j = JSON.parse(readFileSync(cachePath(), "utf8"));
+        return Array.isArray(j) ? j : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Cached result for (root, token), or null on miss/stale. */
+export function readAnalysisCache(root, token) {
+    const e = readAll().find((x) => x.root === root && x.token === token);
+    return e ? e.result : null;
+}
+/** Store (root, token) → result, replacing any prior entry for root. Capped + best-effort. */
+export function writeAnalysisCache(root, token, result, nowMs) {
+    try {
+        const all = readAll().filter((x) => x.root !== root);
+        all.push({ root, token, result, ts: nowMs });
+        all.sort((a, b) => b.ts - a.ts);
+        const path = cachePath();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(all.slice(0, MAX_ENTRIES)), "utf8");
+    }
+    catch { /* best-effort */ }
+}

package/dist/gem/targets.js

@@ -499,6 +499,221 @@ const eveComposeProject = (gem, opts = {}) => {
     }
     return rendered(files);
 };
+// ── A2A (Agent2Agent) target ──
+// Card primitive: materialize(gem, "a2a") emits a runtime-free Agent Card derived from the gem — the
+// A2A discovery surface, publishable to the registry. The Card is the part native to AgentGem's
+// "describe an agent" mission; a runnable A2A server is a planned opt-in flavor (MaterializeOpts).
+const A2A_PROTOCOL_VERSION = "0.3.0";
+const a2aSkillCard = (a) => ({
+    id: safePathSegment(a.name),
+    name: a.name,
+    description: a.description?.trim() || `The ${a.name} skill.`,
+    tags: ["skill"],
+});
+// A one-line card description from an instruction artifact: prefer the first non-empty *prose* line
+// (instruction files usually open with a throwaway "# Title" heading); fall back to the de-headed
+// first line if the doc is headings-only.
+const a2aFirstLine = (s) => {
+    const lines = s.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    return lines.find((l) => !l.startsWith("#")) ?? lines[0]?.replace(/^#+\s*/, "") ?? "";
+};
+// Pure Gem -> AgentCard projection. Skills advertise as A2A skills (metadata, not bodies); the first
+// instruction line becomes the card description; a skill-less Gem gets a synthesized `chat` skill
+// (A2A requires >=1). Emits no secret values (skills/instructions carry none post-redaction).
+export const a2aAgentCard = (gem) => {
+    const skills = gem.artifacts.filter((a) => a.type === "skill");
+    const instr = gem.artifacts.filter((a) => a.type === "instructions");
+    const cardSkills = skills.map(a2aSkillCard);
+    return {
+        protocolVersion: A2A_PROTOCOL_VERSION,
+        name: gem.name,
+        description: a2aFirstLine(instr[0]?.content ?? "") || `An agent packaged by AgentGem from ${skills.length} skill(s).`,
+        version: "0.1.0",
+        url: "http://localhost:41241/a2a/jsonrpc", // discovery placeholder; the (future) server overrides from PUBLIC_URL
+        capabilities: { streaming: false, pushNotifications: false },
+        defaultInputModes: ["text"],
+        defaultOutputModes: ["text"],
+        skills: cardSkills.length ? cardSkills
+            : [{ id: "chat", name: "chat", description: `Converse with ${gem.name}.`, tags: ["chat"] }],
+    };
+};
+// ── A2A server mode (opt-in via MaterializeOpts.a2aServer) ──
+// Runtime is Vercel AI SDK v7 (`ai` + `@ai-sdk/mcp`), vendor-neutral via the gateway model string —
+// deliberately NOT @openai/agents, so sandboxMcpServer is not reused (a2aMcpClient is its analogue).
+const A2A_MODEL = "anthropic/claude-sonnet-4-6";
+const a2aMcpClient = (s) => {
+    const url = typeof s.config.url === "string" ? s.config.url : "";
+    if (/^https?:\/\//.test(url)) {
+        const refs = s.secretRefs ?? [];
+        const unsupported = refs.find((r) => !/^headers\./i.test(r.location));
+        if (unsupported)
+            return { skip: `A2A (AI SDK) cannot map secret at ${unsupported.location}` };
+        const authorization = refs.find((r) => r.location.toLowerCase() === "headers.authorization");
+        const headerEntries = [
+            ...(authorization ? [["Authorization", authorization.name]] : []),
+            ...refs.filter((r) => /^headers\./i.test(r.location) && r !== authorization)
+                .map((r) => [r.location.slice("headers.".length), r.name]),
+        ];
+        const headers = headerEntries.length
+            ? `, headers: { ${headerEntries.map(([h, e]) => `${JSON.stringify(h)}: process.env[${JSON.stringify(e)}]!`).join(", ")} }`
+            : "";
+        const type = s.transport === "sse" ? "sse" : "http";
+        return { code: `  createMCPClient({ transport: { type: ${JSON.stringify(type)}, url: ${JSON.stringify(url)}${headers} } }),`, stdio: false };
+    }
+    if (s.transport === "stdio" && typeof s.config.command === "string") {
+        const args = Array.isArray(s.config.args) ? s.config.args.filter((a) => typeof a === "string") : [];
+        const envNames = (s.secretRefs ?? []).map((r) => r.name);
+        const envStr = envNames.length ? `, env: { ${envNames.map((n) => `${JSON.stringify(n)}: process.env[${JSON.stringify(n)}]!`).join(", ")} }` : "";
+        return { code: `  createMCPClient({ transport: new Experimental_StdioMCPTransport({ command: ${JSON.stringify(s.config.command)}, args: ${JSON.stringify(args)}${envStr} }) }),`, stdio: true };
+    }
+    return { skip: `${s.transport} MCP has no usable URL or stdio command` };
+};
+// A2A projects authenticate via plain process.env. Deliberately NOT agentcoreSecretsMd (its
+// `agentcore add credential` / ${arn:...} body is wrong for an A2A/AI-SDK project).
+const a2aSecretsMd = (secrets) => {
+    const model = `## Model access\n\nThe agent calls \`${A2A_MODEL}\` via the AI SDK. Set \`AI_GATEWAY_API_KEY\` ` +
+        `(Vercel AI Gateway) or a direct provider key (e.g. \`ANTHROPIC_API_KEY\`).\n`;
+    const access = `## Access control (optional)\n\nSet \`A2A_API_KEY\` to require \`Authorization: Bearer <key>\` on the ` +
+        `agent's JSON-RPC/REST routes. Agent Card discovery (the \`.well-known\` endpoint) stays open.\n`;
+    const mcp = secrets.length
+        ? `## MCP credentials\n\nSet these before \`npm start\` (e.g. a \`.env\` file):\n\n` +
+            `${secrets.map((s) => `- \`${s.name}\` (for ${s.artifact} at ${s.location})`).join("\n")}\n`
+        : `## MCP credentials\n\nThis agent declares no MCP secrets.\n`;
+    return `# Secrets\n\n${model}\n${access}\n${mcp}`;
+};
+const a2aPackageJson = (gemName) => JSON.stringify({
+    name: safePathSegment(gemName).toLowerCase(), version: "0.1.0", private: true, type: "module",
+    scripts: { build: "tsc", start: "node dist/server.js", dev: "tsx src/server.ts" },
+    // Verified pins: ai v7 beta pairs with @ai-sdk/mcp v2 beta; @a2a-js/sdk 0.3.x.
+    dependencies: { "@a2a-js/sdk": "^0.3.13", ai: "7.0.0-beta.178", "@ai-sdk/mcp": "2.0.0-beta.67", express: "^5", uuid: "^11" },
+    devDependencies: { "@types/express": "^5", "@types/node": "^24", tsx: "^4", typescript: "^5" },
+}, null, 2) + "\n";
+// The runnable A2A server: an AI SDK `streamText` tool loop behind the @a2a-js/sdk JSON-RPC handler.
+// Streams incrementally via the A2A task lifecycle (submitted -> working -> artifact-update* ->
+// completed); the same executor serves message/send (aggregated) and message/stream (SSE). The served
+// card advertises streaming: true and rebinds `url` from PUBLIC_URL (the static card carries neither).
+const a2aServerTs = (system, clientCodes, usesStdio) => {
+    const mcpImports = clientCodes.length
+        ? `import { createMCPClient } from "@ai-sdk/mcp";\n${usesStdio ? `import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";\n` : ""}`
+        : "";
+    const bootBlock = clientCodes.length
+        ? `const mcpClients = await Promise.all([\n${clientCodes.join("\n")}\n]);
+const tools = Object.assign({}, ...(await Promise.all(mcpClients.map((c) => c.tools()))));
+for (const sig of ["SIGINT", "SIGTERM"] as const)
+  process.on(sig, () => { Promise.allSettled(mcpClients.map((c) => c.close())).finally(() => process.exit(0)); });`
+        : `const tools = {};`;
+    return `import express from "express";
+import { streamText, stepCountIs } from "ai";
+${mcpImports}import { type AgentCard, AGENT_CARD_PATH } from "@a2a-js/sdk";
+import { type AgentExecutor, type RequestContext, type ExecutionEventBus,
+  DefaultRequestHandler, InMemoryTaskStore, InMemoryPushNotificationStore, DefaultPushNotificationSender } from "@a2a-js/sdk/server";
+import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from "@a2a-js/sdk/server/express";
+import { v4 as uuid } from "uuid";
+import cardBase from "../agent-card.json" with { type: "json" };
+
+const MODEL = ${JSON.stringify(A2A_MODEL)};
+const SYSTEM = \`${escapeTemplate(system)}\`;
+
+const port = Number(process.env.PORT ?? 41241);
+const baseUrl = process.env.PUBLIC_URL ?? \`http://localhost:\${port}\`;
+const API_KEY = process.env.A2A_API_KEY; // when set, require \`Authorization: Bearer <key>\` on the RPC/REST routes
+const card: AgentCard = { ...(cardBase as AgentCard), url: \`\${baseUrl}/a2a/jsonrpc\`,
+  capabilities: { ...(cardBase as AgentCard).capabilities, streaming: true, pushNotifications: true },
+  additionalInterfaces: [
+    { url: \`\${baseUrl}/a2a/jsonrpc\`, transport: "JSONRPC" },
+    { url: \`\${baseUrl}/a2a/rest\`, transport: "HTTP+JSON" },
+  ],
+  ...(API_KEY ? { securitySchemes: { bearer: { type: "http", scheme: "bearer" } }, security: [{ bearer: [] }] } : {}) };
+
+${bootBlock}
+
+// Streaming executor: drive the tool loop and publish A2A task-lifecycle + artifact-update events.
+class GemExecutor implements AgentExecutor {
+  private inflight = new Map<string, AbortController>();
+  async execute(ctx: RequestContext, bus: ExecutionEventBus): Promise<void> {
+    const { taskId, contextId, userMessage, task } = ctx;
+    const text = (userMessage.parts ?? []).filter((p: any) => p.kind === "text").map((p: any) => p.text).join("\\n");
+    const ac = new AbortController();
+    this.inflight.set(taskId, ac);
+    if (!task) bus.publish({ kind: "task", id: taskId, contextId, status: { state: "submitted", timestamp: new Date().toISOString() }, history: [userMessage] });
+    bus.publish({ kind: "status-update", taskId, contextId, status: { state: "working", timestamp: new Date().toISOString() }, final: false });
+    const artifactId = uuid();
+    let started = false;
+    try {
+      const result = streamText({ model: MODEL, system: SYSTEM, tools, stopWhen: stepCountIs(10), prompt: text, abortSignal: ac.signal });
+      for await (const delta of result.textStream) {
+        bus.publish({ kind: "artifact-update", taskId, contextId, append: started, lastChunk: false,
+          artifact: { artifactId, name: "response", parts: [{ kind: "text", text: delta }] } });
+        started = true;
+      }
+      bus.publish({ kind: "artifact-update", taskId, contextId, append: true, lastChunk: true, artifact: { artifactId, parts: [] } });
+      bus.publish({ kind: "status-update", taskId, contextId, status: { state: "completed", timestamp: new Date().toISOString() }, final: true });
+    } catch (err) {
+      const state = ac.signal.aborted ? "canceled" : "failed";
+      bus.publish({ kind: "status-update", taskId, contextId, status: { state, timestamp: new Date().toISOString() }, final: true });
+    } finally {
+      this.inflight.delete(taskId);
+      bus.finished();
+    }
+  }
+  cancelTask = async (taskId: string): Promise<void> => { this.inflight.get(taskId)?.abort(); };
+}
+
+const pushStore = new InMemoryPushNotificationStore();
+const requestHandler = new DefaultRequestHandler(card, new InMemoryTaskStore(), new GemExecutor(),
+  undefined, pushStore, new DefaultPushNotificationSender(pushStore));
+const app = express();
+// Discovery (the /.well-known Agent Card) stays open; gate only the invocation routes when A2A_API_KEY is set.
+const requireAuth: express.RequestHandler = (req, res, next) => {
+  if (!API_KEY || req.headers.authorization === \`Bearer \${API_KEY}\`) return next();
+  res.status(401).json({ error: "unauthorized" });
+};
+app.use("/a2a", requireAuth);
+app.use(\`/\${AGENT_CARD_PATH}\`, agentCardHandler({ agentCardProvider: requestHandler }));
+app.use("/a2a/jsonrpc", jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+app.use("/a2a/rest", restHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+app.listen(port, () => console.log(\`A2A agent "\${card.name}" listening on :\${port}\`));
+`;
+};
+// A2A is wholly compose-driven: per-type renderers are no-ops (so no artifact is skip-reported), and
+// compose emits the Agent Card. Card-only mode models neither MCP nor hooks, so nothing is skipped.
+// With opts.a2aServer, it additionally emits a runnable server and evaluates MCP/hook mappability.
+const a2aComposeProject = (gem, opts = {}) => {
+    const files = { "agent-card.json": JSON.stringify(a2aAgentCard(gem), null, 2) + "\n" };
+    if (!opts.a2aServer)
+        return { files, skipped: [] };
+    const skills = gem.artifacts.filter((a) => a.type === "skill");
+    const instr = gem.artifacts.filter((a) => a.type === "instructions");
+    const mcps = gem.artifacts.filter((a) => a.type === "mcp_server");
+    const hooks = gem.artifacts.filter((a) => a.type === "hook");
+    // AI SDK has no skills primitive -> fold skill bodies (frontmatter-stripped) into the system prompt.
+    const instrText = instr.map((i) => `## ${i.name}\n\n${i.content}`).join("\n\n---\n\n");
+    const skillText = skills.map((s) => `## Skill: ${s.name}\n\n${stripYamlFrontmatter(s.content)}`).join("\n\n---\n\n");
+    const system = [instrText, skillText].filter(Boolean).join("\n\n---\n\n");
+    const skipped = [];
+    const clientCodes = [];
+    let usesStdio = false;
+    for (const s of mcps) {
+        const r = a2aMcpClient(s);
+        if ("skip" in r) {
+            skipped.push({ artifact: s.name, type: "mcp_server", reason: r.skip });
+            continue;
+        }
+        clientCodes.push(r.code);
+        usesStdio ||= r.stdio;
+    }
+    for (const h of hooks)
+        skipped.push({ artifact: h.name, type: "hook", reason: "A2A has no hook concept" });
+    return {
+        files: {
+            ...files,
+            "src/server.ts": a2aServerTs(system, clientCodes, usesStdio),
+            "package.json": a2aPackageJson(gem.name),
+            "SECRETS.md": a2aSecretsMd(gem.requiredSecrets),
+        },
+        skipped,
+    };
+};
 // ── targets compose the shared renderers (convergence is literal, not duplicated) ──
 export const TARGET_REGISTRY = {
     claude: { id: "claude", label: "Claude", skill: skillSkillMd, instructions: instructionsClaudeMd, mcp: mcpDotMcpJson, hook: hooksSettingsJson },
@@ -516,6 +731,9 @@ export const TARGET_REGISTRY = {
     // AgentCore harness project (app/<gem>/harness.json + container-baked skills). Instructions/MCP
     // fold into the composed harness.json; stdio MCP is reported skipped by compose; hooks unsupported.
     agentcore: { id: "agentcore", label: "AgentCore", skill: skillAgentcoreMd, instructions: () => ({}), mcp: () => ({ files: {}, skipped: [] }), compose: agentcoreComposeProject },
+    // A2A Agent Card primitive. Wholly compose-driven (all per-type renderers no-op); compose emits the
+    // runtime-free agent-card.json. Card-only mode reports nothing skipped.
+    a2a: { id: "a2a", label: "A2A", skill: () => ({}), instructions: () => ({}), mcp: () => ({ files: {}, skipped: [] }), hook: () => ({}), compose: a2aComposeProject },
 };
 export function materialize(gem, target, opts = {}) {
     const spec = TARGET_REGISTRY[target];

package/dist/gem/testbedFlavors.js

@@ -133,6 +133,7 @@ export function discoverProjects(dirs) {
         }
     }
     return [...best.values()]
+        .filter((p) => !p.path.includes("/.agentgem/")) // hide agentgem's own internal workspaces (e.g. the analysis cwd)
         .sort((a, b) => b.lastUsedMs - a.lastUsedMs)
         .map((p) => ({
         path: p.path,

package/dist/gem.controller.js

@@ -15,7 +15,9 @@ import { packTar } from "./gem/archiveTar.js";
 import { readDeployRecord, writeDeployRecord, clearDeployRecord } from "./gem/deployRecord.js";
 import { undeployManagedAgent, anthropicPublishClient } from "./publish.js";
 import { undeployAgentcoreHarness, realAgentcoreControlClient } from "./gem/agentcorePublish.js";
-import { InventorySchema, GemSchema, GemRequestSchema, DirQuerySchema, PickQuerySchema, PickFolderSchema, ScaffoldChecksRequestSchema, ScaffoldChecksResponseSchema, MaterializeRequestSchema, MaterializeResponseSchema, PublishPreviewRequestSchema, PublishRequestSchema, PublishPreviewResponseSchema, PublishReadyResponseSchema, PublishResultSchema, DeployTargetsResponseSchema, DeployReadyQuerySchema, ArchiveRequestSchema, ArchiveResponseSchema, CreateWorkspaceRequestSchema, WorkspaceQuerySchema, RenderRequestSchema, WorkspaceNameRequestSchema, WorkspaceSummarySchema, WorkspaceDetailSchema, RenderResultSchema, ListWorkspacesResponseSchema, DeleteWorkspaceResponseSchema, RunReadyQuerySchema, RunReadyResponseSchema, RunRequestSchema, RunStatusQuerySchema, RunStateSchema, RunStopRequestSchema, RunStopResponseSchema, CredentialRequestSchema, CredentialResponseSchema, TestbedDetectQuerySchema, TestbedDetectResponseSchema, TestbedSuggestionQuerySchema, TestbedSuggestionResponseSchema, TestbedRecentsResponseSchema, TestbedProjectsQuerySchema, TestbedProjectsResponseSchema, TestbedScaffoldRequestSchema, TestbedScaffoldResponseSchema, TestbedImportRequestSchema, TestbedImportResponseSchema, AgentcoreReadyResponseSchema, AgentcoreDeployRequestSchema, AgentcoreStatusQuerySchema, AgentcoreDeployStateSchema, RegistryReadyResponseSchema, RegistryIndexResponseSchema, RegistryResolveRequestSchema, RegistryResolveResponseSchema, RegistryInstallRequestSchema, RegistryInstallResponseSchema, RegistryPublishRequestSchema, RegistryPublishResponseSchema, UndeployRequestSchema, UndeployResponseSchema, DeployRecordQuerySchema, DeployRecordResponseSchema, } from "./schemas.js";
+import { InventorySchema, GemSchema, GemRequestSchema, DirQuerySchema, PickQuerySchema, PickFolderSchema, ScaffoldChecksRequestSchema, ScaffoldChecksResponseSchema, MaterializeRequestSchema, MaterializeResponseSchema, PublishPreviewRequestSchema, PublishRequestSchema, PublishPreviewResponseSchema, PublishReadyResponseSchema, PublishResultSchema, DeployTargetsResponseSchema, DeployReadyQuerySchema, ArchiveRequestSchema, ArchiveResponseSchema, CreateWorkspaceRequestSchema, WorkspaceQuerySchema, RenderRequestSchema, WorkspaceNameRequestSchema, WorkspaceSummarySchema, WorkspaceDetailSchema, RenderResultSchema, ListWorkspacesResponseSchema, DeleteWorkspaceResponseSchema, RunReadyQuerySchema, RunReadyResponseSchema, RunRequestSchema, RunStatusQuerySchema, RunStateSchema, RunStopRequestSchema, RunStopResponseSchema, CredentialRequestSchema, CredentialResponseSchema, TestbedDetectQuerySchema, TestbedDetectResponseSchema, TestbedSuggestionQuerySchema, TestbedSuggestionResponseSchema, TestbedRecentsResponseSchema, TestbedProjectsQuerySchema, TestbedProjectsResponseSchema, TestbedScaffoldRequestSchema, TestbedScaffoldResponseSchema, TestbedImportRequestSchema, TestbedImportResponseSchema, AgentcoreReadyResponseSchema, AgentcoreDeployRequestSchema, AgentcoreStatusQuerySchema, AgentcoreDeployStateSchema, RegistryReadyResponseSchema, RegistryIndexResponseSchema, RegistryResolveRequestSchema, RegistryResolveResponseSchema, RegistryInstallRequestSchema, RegistryInstallResponseSchema, RegistryPublishRequestSchema, RegistryPublishResponseSchema, UndeployRequestSchema, UndeployResponseSchema, DeployRecordQuerySchema, DeployRecordResponseSchema, WorkflowAnalyzeRequestSchema, WorkflowAnalyzeResponseSchema, } from "./schemas.js";
+import { claudeTranscriptsForCwd, scanWorkflow } from "./gem/workflowScan.js";
+import { recommendWorkflow, recommendationToSelection } from "./gem/acpRecommender.js";
 import { runReadiness, startLocal, stopLocal, getRunStatus, deployVercel, deployCloudflare, undeployVercel, undeployCloudflare } from "./gem/run.js";
 import { setCredential } from "./gem/credentials.js";
 import { agentcoreReadiness, deployAgentcore, getAgentcoreStatus } from "./gem/agentcoreRun.js";
@@ -56,7 +58,7 @@ let GemController = class GemController {
             const inventory = introspectAll(input.body.dir, input.body.projects);
             gem = buildGem(inventory, input.body.selection, { name: input.body.name ?? "gem", createdFrom: dirs.claudeDir });
         }
-        return { target, ...materialize(gem, target), compatibility: compatibility(gem) };
+        return { target, ...materialize(gem, target, { a2aServer: input.body.a2aServer }), compatibility: compatibility(gem) };
     }
     async archive(input) {
         const dirs = resolveDirs(input.body.dir);
@@ -274,6 +276,29 @@ let GemController = class GemController {
     async pickFolder(_input) {
         return { path: await pickFolder() };
     }
+    async workflowAnalyze(input) {
+        const { dir, root } = input.body;
+        // Inventory for exactly this one project (project-namespaced selection target).
+        const inventory = introspectAll(dir, [root]);
+        // introspectAll canonicalizes roots via resolveProject (path.resolve); match the same way.
+        const project = (inventory.projects ?? []).find((p) => p.root === resolveProject(root));
+        if (!project)
+            throw new Error(`Project '${root}' not found in inventory`);
+        const dirs = resolveDirs(dir);
+        const paths = claudeTranscriptsForCwd(dirs.claudeDir, root);
+        // The top-level inventory IS the global/plugin inventory; the project section
+        // is namespaced separately. Scan + recommend over both.
+        const scanInv = { project, global: { skills: inventory.skills, mcpServers: inventory.mcpServers, hooks: inventory.hooks } };
+        const signal = scanWorkflow(paths, scanInv);
+        const { analysis, degraded } = await recommendWorkflow(signal, scanInv);
+        const candidates = analysis.candidates.map((c) => ({ ...c, selection: recommendationToSelection(c) }));
+        return {
+            candidates,
+            gaps: analysis.gaps,
+            signalSummary: { sessionsScanned: signal.sessions.scanned, spanDays: signal.sessions.spanDays, notes: signal.notes },
+            degraded,
+        };
+    }
 };
 __decorate([
     get("/inventory", { query: DirQuerySchema, response: InventorySchema }),
@@ -491,6 +516,12 @@ __decorate([
     __metadata("design:paramtypes", [Object]),
     __metadata("design:returntype", Promise)
 ], GemController.prototype, "pickFolder", null);
+__decorate([
+    post("/workflow/analyze", { body: WorkflowAnalyzeRequestSchema, response: WorkflowAnalyzeResponseSchema }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], GemController.prototype, "workflowAnalyze", null);
 GemController = __decorate([
     api({ basePath: "/api" })
 ], GemController);

package/dist/index.js

@@ -17,6 +17,7 @@ import { MCPComponent } from "@agentback/mcp";
 import { installMcpHttp } from "@agentback/mcp-http";
 import { GemController } from "./gem.controller.js";
 import { GemTools } from "./gem.tools.js";
+import { streamWorkflowAnalyze } from "./workflowStream.js";
 const here = dirname(fileURLToPath(import.meta.url));
 function pageHtml() {
     for (const p of [join(here, "public", "index.html"), join(here, "..", "src", "public", "index.html")]) {
@@ -39,6 +40,10 @@ export async function createApp(port) {
     const server = await app.restServer;
     const html = pageHtml();
     server.expressApp.get("/", (_req, res) => res.type("html").send(html));
+    // SSE progress stream for workflow analysis (raw Express — the decorator
+    // framework only returns single JSON bodies). The POST /api/workflow/analyze
+    // route stays for programmatic/test callers.
+    server.expressApp.get("/api/workflow/analyze/stream", streamWorkflowAnalyze);
     return app;
 }
 // Start the server and print where its surfaces live. Shared by the default

package/dist/public/index.html

@@ -2,7 +2,13 @@
 <html lang="en">
 <head>
 <meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" />
+<!-- Same-origin by default. Inline script/style are required by this single-file UI;
+     no eval is used, so 'unsafe-eval' is omitted (this clears Electron's insecure-CSP
+     warning). Google Fonts (stylesheet + font files) and the data: SVG favicon are
+     allowlisted; API calls are same-origin. -->
+<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data:; connect-src 'self'; base-uri 'self'; object-src 'none'" />
 <title>agentgem — Gem Builder</title>
+<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40' fill='none'><path d='M20 2 L36 14 L20 38 L4 14 Z' fill='%239a3324'/><path d='M20 2 L36 14 L20 16 Z' fill='%23bb4a38'/><path d='M20 2 L4 14 L20 16 Z' fill='%237d2a1e'/><path d='M4 14 L20 16 L20 38 Z' fill='%238b2e21'/><path d='M36 14 L20 16 L20 38 Z' fill='%23a8392a'/><path d='M4 14 L36 14 L20 16 Z' fill='%23c8543f'/></svg>" />
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500;9..144,600;9..144,700&family=Hanken+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
@@ -201,7 +207,7 @@
 </nav>
 <main>
   <section class="pane left">
-    <div class="bar" id="nameBar" style="display:none"><input id="name" type="text" placeholder="gem name" value="gem" style="flex:1" /></div>
+    <div class="bar" id="nameBar" style="display:none"><label for="name" class="d" style="white-space:nowrap">Gem name</label><input id="name" type="text" placeholder="gem name" value="gem" style="flex:1" /></div>
     <div class="bar" id="wsBar" style="display:none">
       <select id="wsSelect" title="open a saved workspace" style="flex:1"><option value="">— no workspace —</option></select>
       <button id="wsNew" class="ghost" title="save the current selection as a new workspace">New workspace…</button>
@@ -245,7 +251,7 @@
     </div>
   </section>
   <section class="pane right">
-    <div class="bar"><strong style="flex:1">Gem (live)</strong><select id="target" title="materialize target" style="margin-left:auto"><option value="claude">Claude</option><option value="codex">Codex</option><option value="agents">Agents</option><option value="hermes">Hermes</option><option value="eve">Eve</option><option value="flue">Flue</option><option value="openai-sandbox">OpenAI Sandbox</option><option value="agentcore">AgentCore</option></select><span class="seg" id="preview-modes"><button type="button" data-pmode="summary">Summary</button><button type="button" data-pmode="json">JSON</button><button type="button" data-pmode="materialize">Materialize</button><button type="button" data-pmode="managed">Managed Agents</button></span><span class="exportwrap"><button id="exportBtn">Export ▾</button><div id="exportMenu" class="exportmenu" hidden><button id="dltar" class="menuitem" title="download the gem archive as a .tar.gz">⬇ Download .tar.gz</button><button id="save" class="menuitem" title="write the gem archive (manifest + lock + files) to a folder">💾 Save to folder…</button><button id="dl" class="menuitem">⬇ Download JSON</button><button id="copy" class="menuitem">⧉ Copy JSON</button></div></span><span class="d" id="archiveStatus" style="margin-left:6px"></span></div>
+    <div class="bar"><strong style="flex:1">Gem (live)</strong><select id="target" title="materialize target" style="margin-left:auto"><option value="claude">Claude</option><option value="codex">Codex</option><option value="agents">Agents</option><option value="hermes">Hermes</option><option value="eve">Eve</option><option value="flue">Flue</option><option value="openai-sandbox">OpenAI Sandbox</option><option value="agentcore">AgentCore</option><option value="a2a">A2A</option></select><span class="seg" id="preview-modes"><button type="button" data-pmode="summary">Summary</button><button type="button" data-pmode="json">JSON</button><button type="button" data-pmode="materialize">Materialize</button><button type="button" data-pmode="managed">Managed Agents</button></span><span class="exportwrap"><button id="exportBtn">Export ▾</button><div id="exportMenu" class="exportmenu" hidden><button id="dltar" class="menuitem" title="download the gem archive as a .tar.gz">⬇ Download .tar.gz</button><button id="save" class="menuitem" title="write the gem archive (manifest + lock + files) to a folder">💾 Save to folder…</button><button id="dl" class="menuitem">⬇ Download JSON</button><button id="copy" class="menuitem">⧉ Copy JSON</button></div></span><span class="d" id="archiveStatus" style="margin-left:6px"></span></div>
     <div id="preview"></div>
     <p class="note">MCP server &amp; hook config secrets are shown as <code>&lt;redacted&gt;</code> and never exported. Skill, CLAUDE.md, rules bodies &amp; hook commands are bundled as written — don't keep secrets in them.</p>
     <div id="checksPanel" class="group" style="margin-top:14px">
@@ -274,6 +280,8 @@
   <div class="modal">
     <div class="modal-h"><strong class="t">Open a testbed</strong><button id="recentClose" class="ghost" style="margin-left:auto">✕ Close</button></div>
     <div class="modal-body" style="padding:14px">
+      <div id="anView" hidden></div>
+      <div id="anPicker">
       <div id="tbCwd" hidden style="padding:12px;border:1px solid var(--line);border-radius:8px;margin-bottom:14px">
         <div style="margin-bottom:6px">This folder looks like a <span id="tbCwdFlavor"></span> project</div>
         <div class="d" id="tbCwdPath" style="margin-bottom:8px;word-break:break-all"></div>
@@ -288,8 +296,9 @@
       <div id="recentList">Loading…</div>
       <div class="src" style="margin:14px 0 6px">Discovered <span class="d">(projects from your Claude / Codex history)</span></div>
       <div id="discoveredList">Loading…</div>
+      </div>
     </div>
-    <div class="modal-h" style="border-top:1px solid var(--line);border-bottom:0">
+    <div class="modal-h" id="anFooter" style="border-top:1px solid var(--line);border-bottom:0">
       <span class="d">Not this folder? Pick a recent one above, or browse.</span>
       <button id="recentBrowse" style="margin-left:auto">Browse folder…</button>
     </div>
@@ -327,6 +336,7 @@ let candidate = null; // { path, flavor } currently shown in the top block
 
 async function openOrCreateTestbed(){
   document.getElementById("recentModal").hidden = false;
+  showPicker();   // always open on the project list, not a stale recommendation view
   try {
     const s = await (await fetch("/api/testbed/suggestion")).json();
     if (s.looksLikeProject) renderCandidate(s.cwd, s.flavor, s.name);
@@ -380,11 +390,15 @@ async function renderRecents(){
     const fl = esc((FLAVORS[p.flavor]||FLAVORS.claude).label);
     const when = p.lastUsed ? esc(p.lastUsed.slice(0,10)) : "";
     const stale = p.exists ? "" : ` <span class="d" title="path no longer exists">· missing</span>`;
-    return `<label class="row recent" data-i="${i}"${p.exists?"":' style="opacity:.5"'}><span><b>${short}</b> <span class="src">${fl}</span> <span class="d">${esc(p.path)}</span>${stale}</span><span class="d" style="margin-left:auto">${when}</span></label>`;
+    const an = p.exists ? `<button type="button" class="ghost anBtn" data-i="${i}" title="recommend a Gem from this project's session history">Analyze</button>` : "";
+    return `<label class="row recent" data-i="${i}"${p.exists?"":' style="opacity:.5"'}><span><b>${short}</b> <span class="src">${fl}</span> <span class="d">${esc(p.path)}</span>${stale}</span><span class="d" style="margin-left:auto">${when}</span>${an}</label>`;
   }).join("");
   list.querySelectorAll("label.recent").forEach(row=>{
     row.onclick = ()=>{ const p = recents[+row.dataset.i]; if(!p.exists) return; document.getElementById("recentModal").hidden = true; useTestbed(p.path, p.flavor, p.name); };
   });
+  list.querySelectorAll("button.anBtn").forEach(btn=>{
+    btn.onclick = (e)=>{ e.preventDefault(); e.stopPropagation(); const p = recents[+btn.dataset.i]; analyzeWorkflow(p.path, p.flavor, p.name); };
+  });
 }
 
 // Cross-repo projects from Claude/Codex session history, minus anything already in Recent.
@@ -403,11 +417,15 @@ async function renderDiscovered(){
     const fl = esc((FLAVORS[p.flavor]||FLAVORS.claude).label);
     const when = p.lastUsed ? esc(p.lastUsed.slice(0,10)) : "";
     const stale = p.exists ? "" : ` <span class="d" title="path no longer exists">· missing</span>`;
-    return `<label class="row disc" data-i="${i}"${p.exists?"":' style="opacity:.5"'}><span><b>${short}</b> <span class="src">${fl}</span> <span class="d">${esc(p.path)}</span>${stale}</span><span class="d" style="margin-left:auto">${when}</span></label>`;
+    const an = p.exists ? `<button type="button" class="ghost anBtn" data-i="${i}" title="recommend a Gem from this project's session history">Analyze</button>` : "";
+    return `<label class="row disc" data-i="${i}"${p.exists?"":' style="opacity:.5"'}><span><b>${short}</b> <span class="src">${fl}</span> <span class="d">${esc(p.path)}</span>${stale}</span><span class="d" style="margin-left:auto">${when}</span>${an}</label>`;
   }).join("");
   list.querySelectorAll("label.disc").forEach(row=>{
     row.onclick = ()=>{ const p = projects[+row.dataset.i]; if(!p.exists) return; document.getElementById("recentModal").hidden = true; useTestbed(p.path, p.flavor, p.path.replace(/^.*\//, "")); };
   });
+  list.querySelectorAll("button.anBtn").forEach(btn=>{
+    btn.onclick = (e)=>{ e.preventDefault(); e.stopPropagation(); const p = projects[+btn.dataset.i]; analyzeWorkflow(p.path, p.flavor, p.path.replace(/^.*\//, "")); };
+  });
 }
 
 // Adopt a known project+flavor: scaffold is idempotent (writeIfAbsent) and records a recent.
@@ -418,12 +436,165 @@ async function useTestbed(path, flavor, name){
   setTestbed(path);
   nameEdited = false;                         // picking a project is explicit — default the gem name to it
   document.getElementById("name").value = name;
-  load();
+  await load();                               // awaited so callers (e.g. Analyze) can apply once the inventory is rendered
+}
+
+// Swap the picker for a focused recommendation view (same modal, no stacking).
+function anModalTitle(t){ const el = document.querySelector("#recentModal .modal-h .t"); if (el) el.textContent = t; }
+// NB: #anFooter has class `modal-h` whose CSS `display:flex` overrides the
+// `hidden` attribute, so toggle its inline display directly.
+function showAnView(){ document.getElementById("anPicker").hidden = true; document.getElementById("anFooter").style.display = "none"; document.getElementById("anView").hidden = false; anModalTitle("Workflow recommendation"); }
+function showPicker(){ document.getElementById("anView").hidden = true; document.getElementById("anPicker").hidden = false; document.getElementById("anFooter").style.display = ""; anModalTitle("Open a testbed"); }
+
+// Recommend a Gem for `path` from its session history — IN PLACE, without adopting
+// it as the active testbed. Renders a focused view inside the same modal. One at a
+// time: the focused view replaces the list, so analyses can't overlap from the UI.
+function analyzeWorkflow(path, flavor, name, fresh){
+  const view = document.getElementById("anView");
+  let es = null, acc = "", finished = false;
+  view.innerHTML =
+    `<button type="button" class="ghost anBack">← back to projects</button>`
+    + `<div style="margin-top:10px"><b>${esc(name)}</b></div>`
+    + `<div class="d" id="anPhase" style="margin-top:8px">Starting…</div>`
+    + `<pre id="anStream" style="margin-top:8px;max-height:140px;overflow:auto;white-space:pre-wrap;word-break:break-word;font-size:11px;color:var(--muted);background:rgba(127,127,127,.06);padding:8px;border-radius:6px;display:none"></pre>`;
+  view.querySelector(".anBack").onclick = (e) => { e.preventDefault(); finished = true; if (es) es.close(); showPicker(); };
+  showAnView();
+  const phaseEl = view.querySelector("#anPhase");
+  const streamEl = view.querySelector("#anStream");
+
+  es = new EventSource(`/api/workflow/analyze/stream?root=${encodeURIComponent(path)}${fresh ? "&fresh=1" : ""}`);
+  es.addEventListener("phase", (ev) => {
+    const d = JSON.parse(ev.data);
+    if (d.phase === "scanning") phaseEl.textContent = "Scanning session history…";
+    else if (d.phase === "scanned") phaseEl.textContent = `Scanned ${d.transcripts} transcript(s) · ${d.sessions} session(s). Asking Claude…`;
+    else if (d.phase === "thinking") phaseEl.textContent = "Claude is clustering a Gem from your usage…";
+    else if (d.phase === "validating") phaseEl.textContent = "Validating against your inventory…";
+  });
+  es.addEventListener("delta", (ev) => {
+    acc += JSON.parse(ev.data).text;
+    streamEl.style.display = "block";
+    streamEl.textContent = acc.slice(-1200);          // tail of the agent's live output
+    streamEl.scrollTop = streamEl.scrollHeight;
+  });
+  es.addEventListener("done", (ev) => { finished = true; es.close(); renderAnView(view, path, flavor, name, JSON.parse(ev.data)); });
+  es.addEventListener("failed", (ev) => { finished = true; es.close(); renderAnError(view, esc(JSON.parse(ev.data).message || "unknown error")); });
+  es.onerror = () => { if (finished) return; finished = true; es.close(); renderAnError(view, "connection lost"); };
+}
+
+function renderAnError(view, msg){
+  view.innerHTML = `<button type="button" class="ghost anBack">← back to projects</button><div class="d" style="margin-top:10px">Analysis failed: ${msg}</div>`;
+  view.querySelector(".anBack").onclick = (e) => { e.preventDefault(); showPicker(); };
+}
+
+// Read-only view of the candidate Gems. Each card adopts the project AND applies
+// just that candidate's selection.
+let anCandidates = [];   // stash so a card's button can grab its candidate
+function renderAnView(view, path, flavor, name, res){
+  anCandidates = res.candidates || [];
+  const degraded = res.degraded ? ` <span class="d">(usage frequency — agent unavailable)</span>` : "";
+  const gaps = (res.gaps || []).length ? `<div class="d" style="margin:8px 0">Used but not in inventory: ${esc(res.gaps.join(", "))}</div>` : "";
+  const li = (n, t, reason, root) => {
+    const scope = root === null ? ` <span class="src" title="global / plugin artifact">global</span>` : "";
+    return `<li style="margin-bottom:4px"><b>${esc(n)}</b> <span class="d">${esc(t)}</span>${scope}${reason ? ` — ${esc(reason)}` : ""}</li>`;
+  };
+
+  const cards = anCandidates.map((c, i) => {
+    const items = c.include.map(it => li(it.name, it.type, it.reason, it.root)).join("");
+    const instr = c.includeInstructions ? li("CLAUDE.md", "instructions", "loaded every session", c.root) : "";
+    return `<div style="border:1px solid var(--line);border-radius:8px;padding:10px 12px;margin-bottom:10px">`
+      + `<div style="font-size:14px"><b>${esc(c.name)}</b> <span class="d">· ${c.confidence}</span></div>`
+      + `<div class="d" style="margin:3px 0 8px">${esc(c.description)}</div>`
+      + (items || instr ? `<ul style="margin:0 0 8px 18px;padding:0">${items}${instr}</ul>` : `<div class="d">No project-scoped artifacts.</div>`)
+      + `<button type="button" class="anApply" data-i="${i}" style="margin-top:4px">Switch &amp; apply this Gem ▸</button>`
+      + `</div>`;
+  }).join("");
+
+  const heading = anCandidates.length > 1 ? `${anCandidates.length} candidate Gems` : (anCandidates.length === 1 ? "Recommended Gem" : "No recurring flows found");
+  const cached = res.cached ? ` <span class="src" title="cached — re-analyze to refresh">cached</span>` : "";
+  view.innerHTML =
+    `<div style="display:flex;align-items:center;gap:8px"><button type="button" class="ghost anBack">← back to projects</button>`
+    + `<button type="button" class="ghost anFresh" style="margin-left:auto" title="re-run the analysis ignoring the cache">↻ Re-analyze</button></div>`
+    + `<div style="margin-top:10px;font-size:15px"><b>${esc(heading)}</b>${degraded}${cached} <span class="d">· ${res.signalSummary.sessionsScanned} session(s)</span></div>`
+    + `<div class="d" style="margin:4px 0 10px;word-break:break-all">${esc(path)}</div>`
+    + (cards || `<div class="d">Nothing to recommend from this project's usage.</div>`)
+    + gaps;
+  view.querySelector(".anBack").onclick = (e) => { e.preventDefault(); showPicker(); };
+  view.querySelector(".anFresh").onclick = (e) => { e.preventDefault(); analyzeWorkflow(path, flavor, name, true); };
+  view.querySelectorAll(".anApply").forEach(btn => {
+    btn.onclick = (e) => { e.preventDefault(); switchAndApply(path, flavor, anCandidates[+btn.dataset.i]); };
+  });
+}
+
+// The explicit switch: adopt the project as the active testbed, then pre-check
+// the chosen candidate's selection.
+async function switchAndApply(path, flavor, candidate){
+  document.getElementById("recentModal").hidden = true;
+  showPicker();                            // reset modal for next open
+  await useTestbed(path, flavor, candidate.name);   // adopt + render this project's inventory
+  applyCandidate(path, candidate);         // pre-check this candidate's boxes + banner
+}
+
+function ensureAnalyzeBanner(){
+  let b = document.getElementById("analyzeBanner");
+  if (!b) { b = document.createElement("div"); b.id = "analyzeBanner"; b.className = "note"; b.style.margin = "0 0 12px";
+    const inv = document.getElementById("inventory"); inv.insertBefore(b, inv.firstChild); }
+  return b;
+}
+
+// Mutate the shared `sel` model (same shape onToggle maintains) from one
+// candidate's selection — global artifacts go top-level, project ones under
+// projects[root] — then re-sync the checkboxes and the build preview.
+function applyCandidate(root, candidate){
+  const s = candidate.selection;
+  // global (top-level) artifacts
+  (s.skills || []).forEach(n => sel.skills.add(n));
+  (s.mcpServers || []).forEach(n => sel.mcpServers.add(n));
+  (s.hooks || []).forEach(n => sel.hooks.add(n));
+  if (s.includeInstructions) sel.includeInstructions = true;
+  // project artifacts
+  const ps = (s.projects || {})[root] || {};
+  const ts = projSel(root);
+  (ps.skills || []).forEach(n => ts.skills.add(n));
+  (ps.mcpServers || []).forEach(n => ts.mcpServers.add(n));
+  (ps.hooks || []).forEach(n => ts.hooks.add(n));
+  if (ps.includeInstructions) ts.includeInstructions = true;
+
+  renderGlobalGroup(candidate);   // surface the global picks as checkboxes
+  restoreChecks(); refresh();
+
+  const reasons = candidate.include.map(i => `${esc(i.name)}: ${esc(i.reason)}`).join(" · ");
+  ensureAnalyzeBanner().innerHTML = `<b>${esc(candidate.name)}</b> — ${esc(candidate.description)}<br>${reasons}`;
+}
+
+// The testbed inventory pane normally shows only project artifacts (globals are
+// reached via Import). When a candidate bundles globals, render them as a
+// dedicated checkbox group so they're visible and reviewable. Their data-kind is
+// the top-level kind, so onToggle/restoreChecks/buildSelectionBody treat them as
+// the global selection.
+function renderGlobalGroup(candidate){
+  document.getElementById("globalGroup")?.remove();
+  const globals = (candidate.include || []).filter(i => i.root === null);
+  if (!globals.length) return;
+  const kindOf = t => t === "skill" ? "skills" : t === "mcp_server" ? "mcpServers" : "hooks";
+  const rows = globals.map(i =>
+    `<label class="row"><input type="checkbox" data-kind="${kindOf(i.type)}" data-name="${esc(i.name)}"> <span>${esc(i.name)} <span class="src">global</span> <span class="d">— ${esc(i.type)}</span></span></label>`).join("");
+  document.getElementById("inventory").insertAdjacentHTML("afterbegin",
+    `<div class="group" id="globalGroup"><h2>Global / plugin (recommended)</h2>${rows}</div>`);
+  document.querySelectorAll("#globalGroup input[type=checkbox]").forEach(cb => cb.addEventListener("change", onToggle));
+}
+
+// Prefer the Electron-native folder dialog when running in the desktop app;
+// fall back to the local REST picker in a plain browser. Both return { path }.
+async function pickFolderPath() {
+  if (window.agentgem && window.agentgem.pickFolder) {
+    return await window.agentgem.pickFolder();
+  }
+  return await (await fetch("/api/pick-folder")).json();
 }
 
 // Browse routes the picked folder back through the same confirm block (no prompts).
 async function browseForTestbed(){
-  const pick = await (await fetch("/api/pick-folder")).json();
+  const pick = await pickFolderPath();
   if(!pick.path) return;
   const flavor = (await (await fetch(`/api/testbed/detect?root=${encodeURIComponent(pick.path)}`)).json()).flavor;
   renderCandidate(pick.path, flavor, pick.path.replace(/^.*\//, ""));
@@ -699,16 +870,19 @@ function renderPreview(){
   }
   document.querySelectorAll("#preview-modes button").forEach(b => b.classList.toggle("on", b.dataset.pmode === previewMode));
 }
+let a2aServerMode = false; // a2a target: false = Agent Card only (default), true = also emit the runnable server
 async function renderMaterialize(){
   const el = document.getElementById("preview");
   const reqBody = buildSelectionBody();
   reqBody.target = document.getElementById("target").value;
+  if (reqBody.target === "a2a" && a2aServerMode) reqBody.a2aServer = true;
   const m = await (await fetch("/api/materialize", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(reqBody) })).json();
   window.__materialize = m;
   if (m.error) { el.innerHTML = ""; const pre = document.createElement("pre"); pre.className = "json"; pre.textContent = JSON.stringify(m, null, 2); el.appendChild(pre); return; }
   const paths = Object.keys(m.files || {});
   const compat = Object.entries(m.compatibility || {}).map(([t, c]) => `${t} ${c.skipped ? c.skipped + " skipped" : "✓"}`).join(" · ");
   let h = `<div class="psummary"><div class="phead"><strong>${esc(m.target)}</strong> <span class="d">· ${paths.length} file${paths.length === 1 ? "" : "s"}</span></div>`;
+  if (reqBody.target === "a2a") h += `<div class="pgroup"><label style="display:flex;align-items:center;gap:6px"><input type="checkbox" id="a2aServerToggle" ${a2aServerMode ? "checked" : ""}> Emit runnable server (AI SDK v7) — otherwise just the Agent Card</label></div>`;
   h += `<div class="pgroup"><h3>Files</h3>` + (paths.length ? paths.map(p => `<button type="button" class="prow" data-mpath="${esc(p)}"><span class="pn">${esc(p)}</span></button>`).join("") : `<p class="d">No files — select artifacts on the left.</p>`) + `</div>`;
   if ((m.skipped || []).length) h += `<div class="pgroup"><h3>Skipped (${m.skipped.length})</h3>` + m.skipped.map(s => `<div class="prow"><span class="pn">${esc(s.artifact)}</span> <span class="pm">${esc(s.reason)}</span></div>`).join("") + `</div>`;
   h += `<p class="note">Compatibility: ${esc(compat)}</p></div>`;
@@ -1017,6 +1191,10 @@ document.getElementById("target").addEventListener("change", (e) => {
   if (mapped) deployBackend = mapped;
   renderPreview();
 });
+// a2a server toggle (rendered inside the materialize preview): re-materialize with/without the server.
+document.getElementById("preview").addEventListener("change", (e) => {
+  if (e.target.id === "a2aServerToggle") { a2aServerMode = e.target.checked; renderMaterialize(); }
+});
 document.getElementById("preview").addEventListener("click", e => {
   if (e.target.id === "publishBtn") { doPublish(); return; }
   const mp = e.target.closest("[data-mpath]");
@@ -1048,7 +1226,7 @@ document.getElementById("copy").addEventListener("click", () => navigator.clipbo
 document.getElementById("save").addEventListener("click", async () => {
   const status = document.getElementById("archiveStatus");
   status.textContent = "Choose a folder…";
-  const picked = await (await fetch("/api/pick-folder")).json();
+  const picked = await pickFolderPath();
   if (!picked.path) { status.textContent = ""; return; }
   status.textContent = "Saving…";
   const r = await (await fetch("/api/archive", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ ...buildSelectionBody(), outDir: picked.path }) })).json();

package/dist/schemas.js

@@ -178,6 +178,7 @@ export const MaterializeRequestSchema = z.object({
     name: z.string().optional(),
     dir: z.string().optional(),
     projects: z.array(z.string()).optional(),
+    a2aServer: z.boolean().optional(), // a2a target: also emit the runnable server, not just the Agent Card
 }).refine((d) => d.selection !== undefined || d.archivePath !== undefined, {
     message: "provide either selection or archivePath",
 });
@@ -236,6 +237,37 @@ export const PublishResultSchema = z.discriminatedUnion("kind", [ManagedAgentRes
 export const DirQuerySchema = z.object({ dir: z.string().optional(), projects: z.string().optional() });
 export const PickQuerySchema = z.object({});
 export const PickFolderSchema = z.object({ path: z.string().nullable() });
+// ── Workflow-aware Gem recommendation ──
+export const WorkflowAnalyzeRequestSchema = z.object({
+    dir: z.string().optional(), // .claude dir (resolveDirs handles the default)
+    root: z.string(), // the project root to analyze (one of the discovered cwds)
+});
+const RecommendedItemSchema = z.object({
+    type: z.enum(["skill", "mcp_server", "instructions", "hook"]),
+    name: z.string(),
+    reason: z.string(),
+    root: z.string().nullable(), // project root, or null for a global/plugin artifact
+});
+// One candidate Gem, carrying its own ready-to-POST GemSelection.
+const GemCandidateSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    root: z.string(),
+    includeInstructions: z.boolean(),
+    include: z.array(RecommendedItemSchema),
+    confidence: z.enum(["high", "medium", "low"]),
+    selection: z.record(z.string(), z.unknown()), // a GemSelection; buildGem validates structurally at /api/gem
+});
+export const WorkflowAnalyzeResponseSchema = z.object({
+    candidates: z.array(GemCandidateSchema),
+    gaps: z.array(z.string()), // project-level: used but absent from inventory
+    signalSummary: z.object({
+        sessionsScanned: z.number(),
+        spanDays: z.number(),
+        notes: z.array(z.string()),
+    }),
+    degraded: z.boolean(),
+});
 export const GemSchema = z.object({
     name: z.string(),
     createdFrom: z.string(),

package/dist/workflowStream.js

@@ -0,0 +1,72 @@
+// src/workflowStream.ts
+//
+// SSE endpoint for the workflow analysis. agentgem's decorator framework returns
+// a single JSON body, so streaming progress (scan → agent token stream → done)
+// is served by a raw Express handler registered on `server.expressApp`. The
+// non-streaming POST /api/workflow/analyze stays for programmatic/test callers.
+import { introspectConfig, introspectProject } from "./gem/introspect.js";
+import { resolveDirs, resolveProject } from "./resolveDir.js";
+import { claudeTranscriptsForCwd, scanWorkflow } from "./gem/workflowScan.js";
+import { recommendWorkflow, recommendationToSelection } from "./gem/acpRecommender.js";
+import { transcriptToken, readAnalysisCache, writeAnalysisCache } from "./gem/analysisCache.js";
+export async function streamWorkflowAnalyze(req, res) {
+    const root = typeof req.query.root === "string" ? req.query.root : "";
+    const dir = typeof req.query.dir === "string" ? req.query.dir : undefined;
+    const fresh = req.query.fresh === "1"; // bypass the cache (Re-analyze)
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no", // disable proxy buffering so events flush immediately
+    });
+    const send = (event, data) => {
+        res.write(`event: ${event}\n`);
+        res.write(`data: ${JSON.stringify(data)}\n\n`);
+    };
+    try {
+        if (!root) {
+            send("failed", { message: "missing root" });
+            return;
+        }
+        const dirs = resolveDirs(dir);
+        const project = introspectProject(resolveProject(root));
+        const globalInv = introspectConfig(dirs); // global + plugin artifacts
+        const scanInv = { project, global: { skills: globalInv.skills, mcpServers: globalInv.mcpServers, hooks: globalInv.hooks } };
+        send("phase", { phase: "scanning" });
+        const paths = claudeTranscriptsForCwd(dirs.claudeDir, root);
+        // Cache hit (unless Re-analyze): return the prior result instantly so the
+        // user can revisit a project to pick another candidate without re-running
+        // the agent. Token invalidates when sessions are added/updated.
+        const token = transcriptToken(paths);
+        if (!fresh) {
+            const cached = readAnalysisCache(root, token);
+            if (cached) {
+                send("done", { ...cached, cached: true });
+                return;
+            }
+        }
+        const signal = scanWorkflow(paths, scanInv);
+        send("phase", { phase: "scanned", transcripts: paths.length, sessions: signal.sessions.scanned });
+        send("phase", { phase: "thinking" });
+        const { analysis, degraded } = await recommendWorkflow(signal, scanInv, {
+            onDelta: (chunk) => send("delta", { text: chunk }),
+        });
+        send("phase", { phase: "validating" });
+        const candidates = analysis.candidates.map((c) => ({ ...c, selection: recommendationToSelection(c) }));
+        const payload = {
+            candidates,
+            gaps: analysis.gaps,
+            signalSummary: { sessionsScanned: signal.sessions.scanned, spanDays: signal.sessions.spanDays, notes: signal.notes },
+            degraded,
+        };
+        if (!degraded)
+            writeAnalysisCache(root, token, payload, Date.now()); // don't cache fallbacks
+        send("done", { ...payload, cached: false });
+    }
+    catch (err) {
+        send("failed", { message: err?.message ?? String(err) });
+    }
+    finally {
+        res.end();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninemind/agentgem",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A local web UI that introspects your coding-agent config, redacts secrets at capture, and builds a portable, composable Gem.",
   "license": "MIT",
   "bin": {
@@ -54,6 +54,7 @@
     "@agentback/openapi": "^0.5.2",
     "@agentback/rest": "^0.5.2",
     "@agentback/rest-explorer": "^0.5.2",
+    "@agentclientprotocol/sdk": "^0.28.1",
     "@anthropic-ai/sdk": "^0.104.2",
     "@aws-sdk/client-bedrock-agentcore-control": "^3.1073.0",
     "dotenv": "^17.4.2",