@ateam-ai/mcp 0.3.56 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.3.56",
+  "version": "0.4.0",
   "mcpName": "io.github.ariekogan/ateam-mcp",
   "description": "A-Team MCP Server — build, validate, and deploy multi-agent solutions from any AI environment",
   "type": "module",

package/src/tools.js

@@ -83,6 +83,89 @@ function _resolveDottedField(obj, dottedPath) {
   return { parent, leaf: parts[parts.length - 1] };
 }
 
+// ─── Protected array fields (v0.4.0 sibling-loss guard) ─────────────
+//
+// Historically, `ateam_patch(target:"solution", updates:{ linked_skills:["only-one"] })`
+// silently REPLACED the whole linked_skills array — wiping every other
+// skill wired into the solution. Same footgun on ui_plugins, handoffs,
+// grants, connectors, etc. The Solution Builder skill hit this in the
+// wild and wiped a tenant's whole solution.
+//
+// From v0.4.0, ateam_patch REFUSES a bare array-replace on any of these
+// fields unless the caller explicitly opts in via one of:
+//   updates: { _replace: true, linked_skills: [...] }        // object-level
+//   updates: { linked_skills: [...], linked_skills_replace: true } // field-level
+// To ADD or REMOVE without opt-in, use the _push / _delete / _update
+// suffix pattern that has always been the correct form.
+const SOLUTION_ARRAY_FIELDS = new Set([
+  'linked_skills',
+  'ui_plugins',
+  'platform_connectors',
+  'handoffs',
+  'grants',
+  'triggers',
+  'notification_routes',
+  'channels',
+  'actor_types',
+  'admin_roles',
+  'plugins',
+  'security_contracts',
+  'connectors',
+  'skills',
+]);
+
+const SKILL_ARRAY_FIELDS = new Set([
+  'tools',
+  'connectors',
+  'handoffs',
+  'scenarios',
+  'triggers',
+  'notification_routes',
+  'plugins',
+  'bootstrap_tools',
+]);
+
+// Returns { ok:false, ... } if the write would REPLACE a protected array
+// without an explicit opt-in; returns null if the write is safe to proceed.
+function _guardArrayReplace({ target, key, value, current, updates }) {
+  const knownFields = target === 'skill' ? SKILL_ARRAY_FIELDS : SOLUTION_ARRAY_FIELDS;
+  if (!knownFields.has(key)) return null;
+  if (!Array.isArray(value)) return null;
+  const currentArr = Array.isArray(current) ? current : [];
+  if (currentArr.length === 0) return null; // nothing to lose
+  if (updates && updates._replace === true) return null;
+  if (updates && updates[key + '_replace'] === true) return null;
+
+  // Compute what would be dropped so the error message is actionable.
+  const keyOf = (item) => (item && typeof item === 'object') ? (item.id ?? item.name ?? JSON.stringify(item)) : item;
+  const newKeys = new Set(value.map(keyOf));
+  const dropped = currentArr.map(keyOf).filter(k => !newKeys.has(k));
+  const kept = currentArr.map(keyOf).filter(k => newKeys.has(k));
+  const wouldAdd = value.map(keyOf).filter(k => !currentArr.map(keyOf).includes(k));
+
+  return {
+    ok: false,
+    phase: 'patch',
+    error:
+      `⚠️ REFUSED: bare-array replace on ${target}.${key} would drop ${dropped.length} sibling item(s): ` +
+      `[${dropped.slice(0, 8).join(', ')}${dropped.length > 8 ? ', ...' : ''}]. ` +
+      `This footgun wiped a whole solution in the wild — v0.4.0 refuses it by default. ` +
+      `\n\nWhat to do instead:` +
+      `\n  • To ADD items: updates: { "${key}_push": ${JSON.stringify(wouldAdd)} }` +
+      (dropped.length ? `\n  • To REMOVE items: updates: { "${key}_delete": ${JSON.stringify(dropped)} }` : '') +
+      `\n  • To FULLY REPLACE (rare): updates: { "${key}": [...], "${key}_replace": true }` +
+      `\n  • To replace many arrays in one call: updates: { _replace: true, "${key}": [...] }`,
+    dropped_ids: dropped,
+    kept_ids: kept,
+    would_add: wouldAdd,
+    safe_alternatives: {
+      push: { [`${key}_push`]: wouldAdd },
+      ...(dropped.length && { delete: { [`${key}_delete`]: dropped } }),
+      force_replace: { [key]: value, [`${key}_replace`]: true },
+    },
+  };
+}
+
 // ─── Tool definitions ───────────────────────────────────────────────
 
 export const tools = [
@@ -131,15 +214,15 @@ export const tools = [
     name: "ateam_get_spec",
     core: true,
     description:
-      "Get the A-Team specification — schemas, validation rules, system tools, agent guides, and templates. Start here after bootstrap to understand how to build skills and solutions. Use 'section' to get just one part of the skill spec (much smaller than the full spec). Use 'search' to find specific fields or concepts across the spec.\n\nWhen designing a persona that orchestrates logic via run_python_script (the Python-as-orchestrator pattern), also fetch topic='python_helpers' — that returns the adas.* helper namespace reference. Skills designed without knowing about adas.* produce 5-10x larger / brittler scripts.",
+      "Get the A-Team specification — schemas, validation rules, system tools, agent guides, and templates. Start here after bootstrap to understand how to build skills and solutions. Use 'section' to get just one part of the skill spec (much smaller than the full spec). Use 'search' to find specific fields or concepts across the spec.\n\nWhen designing a persona that orchestrates logic via run_python_script (the Python-as-orchestrator pattern), also fetch topic='python_helpers' — that returns the adas.* helper namespace reference. Skills designed without knowing about adas.* produce 5-10x larger / brittler scripts.\n\nWhen wiring widgets (UI plugins) into a solution, fetch topic='widgets' — that returns the widget spec (catalog model, how_to_use blocks, opener_call shape, persona phrasing rules, binding semantics) so you can declare `ui_plugins` correctly. For the live catalog of widgets actually available in a deployed tenant, use ateam_get_widget_catalog instead.",
     inputSchema: {
       type: "object",
       properties: {
         topic: {
           type: "string",
-          enum: ["overview", "skill", "solution", "enums", "connector-multi-user", "python_helpers"],
+          enum: ["overview", "skill", "solution", "enums", "connector-multi-user", "python_helpers", "widgets"],
           description:
-            "What to fetch: 'overview' = API overview + endpoints, 'skill' = full skill spec, 'solution' = full solution spec, 'enums' = all enum values, 'connector-multi-user' = multi-user connector guide, 'python_helpers' = adas.* helper namespace for run_python_script orchestration (read this when designing personas that read state → call tools → checkpoint → status; without it, scripts hand-roll JSON parsing and tool delegation = 5-10x larger and brittler).",
+            "What to fetch: 'overview' = API overview + endpoints, 'skill' = full skill spec, 'solution' = full solution spec, 'enums' = all enum values, 'connector-multi-user' = multi-user connector guide, 'python_helpers' = adas.* helper namespace for run_python_script orchestration (read this when designing personas that read state → call tools → checkpoint → status; without it, scripts hand-roll JSON parsing and tool delegation = 5-10x larger and brittler), 'widgets' = widget (UI plugin) spec: catalog model, how_to_use block shape (solution.json snippet + opener_call + persona_phrasing + binding_notes), and rules for declaring ui_plugins. Pair with ateam_get_widget_catalog for the live per-tenant inventory.",
         },
         section: {
           type: "string",
@@ -428,24 +511,27 @@ export const tools = [
     core: true,
     description:
       "Surgically update ANY field in a skill or solution definition, redeploy, and optionally re-test — all in one step.\n\n" +
-      "SUPPORTED OPERATIONS:\n" +
+      "⚠️ MERGE-BY-DEFAULT (v0.4.0) — Arrays are protected from silent replace. Bare array writes on solution.linked_skills / ui_plugins / platform_connectors / handoffs / grants / triggers (etc.) and skill.tools / connectors / handoffs / scenarios are REFUSED to prevent sibling loss. Add or remove items with the _push / _delete / _update suffixes; opt into a full-array replace only when you really mean it.\n\n" +
+      "OPERATIONS (safe by construction):\n" +
       "1. Scalar (dot notation): { \"problem.statement\": \"new value\", \"role.persona\": \"You are...\" }\n" +
       "2. Deep nested: { \"intents.thresholds.accept\": 0.9, \"policy.escalation.enabled\": true }\n" +
-      "3. Array push: { \"tools_push\": [{ name: \"new_tool\", description: \"...\" }] }\n" +
-      "4. Array delete: { \"tools_delete\": [\"tool_name\"] }\n" +
-      "5. Array update: { \"tools_update\": [{ name: \"existing_tool\", description: \"updated\" }] }\n" +
-      "6. Replace whole section: { \"role\": { persona: \"...\", goals: [...] } }\n\n" +
-      "EXAMPLES:\n" +
-      "- Change persona (full replace): updates: { \"role.persona\": \"You are a friendly assistant\" }\n" +
-      "- Append to persona (don't replace): updates: { \"persona_append\": \"\\n\\nALWAYS respond in 2 sentences.\" }\n" +
+      "3. Array APPEND: { \"tools_push\": [{ name: \"new_tool\", description: \"...\" }] }\n" +
+      "4. Array REMOVE: { \"tools_delete\": [\"tool_name\"] }\n" +
+      "5. Array MODIFY-ONE: { \"tools_update\": [{ name: \"existing_tool\", description: \"updated\" }] }\n" +
+      "6. Full-array REPLACE (opt-in): { \"linked_skills\": [...], \"linked_skills_replace\": true } — or { _replace: true, ... } to opt every array in this call.\n\n" +
+      "SOLUTION-LEVEL EXAMPLES (target='solution'):\n" +
+      "- ADD a skill to the solution: updates: { \"linked_skills_push\": [\"my-new-skill\"] } ← NOT { linked_skills: [\"my-new-skill\"] } (that would REFUSE — it drops your other skills)\n" +
+      "- REMOVE a skill: updates: { \"linked_skills_delete\": [\"old-skill\"] }\n" +
+      "- ADD a UI plugin: updates: { \"ui_plugins_push\": [{ id: \"mcp:conn:panel\", ... }] }\n" +
+      "- ADD a handoff: updates: { \"handoffs_push\": [{ id: \"h1\", ... }] }\n\n" +
+      "SKILL-LEVEL EXAMPLES (target='skill' + skill_id):\n" +
+      "- Change persona: updates: { \"role.persona\": \"You are a friendly assistant\" }\n" +
+      "- Append to persona: updates: { \"persona_append\": \"\\n\\nALWAYS respond in 2 sentences.\" }\n" +
       "- Add a guardrail: updates: { \"policy.guardrails.never_push\": [\"Never share passwords\"] }\n" +
-      "- Update problem: updates: { \"problem.statement\": \"...\", \"problem.goals\": [\"goal1\"] }\n" +
       "- Add a tool: updates: { \"tools_push\": [{ name: \"conn.tool\", description: \"...\", inputs: [...], output: {...} }] }\n" +
       "- Change intent: updates: { \"intents.supported_update\": [{ id: \"i1\", description: \"new desc\" }] }\n" +
-      "- Force redeploy: updates: { \"_force_redeploy\": true }\n" +
-      "- CREATE a new skill: target='skill', skill_id='my-new-skill', updates: { \"problem.statement\": \"...\", \"role.persona\": \"...\" }\n" +
-      "  If the skill doesn't exist yet, a default scaffold is created and the updates are applied on top. The skill is automatically added to the solution topology.\n\n" +
-      "Use target='skill' + skill_id for skill fields. Use target='solution' for solution-level fields (linked_skills, platform_connectors, ui_plugins).",
+      "- CREATE a new skill: target='skill', skill_id='my-new-skill', updates: { \"problem.statement\": \"...\", \"role.persona\": \"...\" } — auto-scaffolded and added to solution topology.\n\n" +
+      "PREVIEW BEFORE WRITING: pass dry_run:true to see the diff (arrays_merged, arrays_replaced, dropped_ids, added_ids) without applying. Use this before any destructive-looking edit.",
     inputSchema: {
       type: "object",
       properties: {
@@ -473,6 +559,10 @@ export const tools = [
           type: "string",
           description: "Optional: re-test the skill after patching. Requires skill_id.",
         },
+        dry_run: {
+          type: "boolean",
+          description: "If true, apply the patch in memory and return the diff (arrays_merged, arrays_replaced, dropped_ids, added_ids, would_write_bytes) WITHOUT writing to GitHub or redeploying. Preview a change before committing to it.",
+        },
       },
       required: ["solution_id", "target", "updates"],
     },
@@ -516,7 +606,9 @@ export const tools = [
     name: "ateam_delete_solution",
     core: true,
     description:
-      "Delete a deployed solution and all its skills from A-Team. Use with caution — this removes the solution from both the Skill Builder and A-Team Core. Useful for cleaning up test solutions or starting fresh.",
+      "⚠️ IRREVERSIBLE — kills Mongo state, running MCP processes, and Builder FS for the whole solution and every skill. " +
+      "REQUIRES `confirm:true` AND `confirm_solution_id` echoing the solution id you're destroying (defeats typos and hallucinated ids). " +
+      "RECOVERY: the GitHub repo is untouched; `ateam_github_pull` rebuilds the solution from `main`. Prefer that over re-deploying from memory.",
     inputSchema: {
       type: "object",
       properties: {
@@ -524,15 +616,24 @@ export const tools = [
           type: "string",
           description: "The solution ID to delete",
         },
+        confirm: {
+          type: "boolean",
+          description: "REQUIRED. Must be exactly true. A missing/false value refuses the call with a recovery hint.",
+        },
+        confirm_solution_id: {
+          type: "string",
+          description: "REQUIRED. Must exactly equal `solution_id`. This defeats typos and hallucinated ids — you can't wipe a solution you couldn't spell.",
+        },
       },
-      required: ["solution_id"],
+      required: ["solution_id", "confirm", "confirm_solution_id"],
     },
   },
   {
     name: "ateam_delete_skill",
     core: true,
     description:
-      "Delete a single skill from a deployed solution. Removes the skill from A-Team Core (kills the running MCP process, unregisters from skill registry, deletes from Mongo), removes the skill from solution.skills[] and solution.linked_skills, and deletes the skill's files from Builder FS. Use this to drop a skill without tearing down the whole solution.",
+      "⚠️ IRREVERSIBLE in Core + Builder FS — kills the running MCP process, unregisters from skill registry, deletes the Mongo record, drops from solution.skills[] and solution.linked_skills, and removes the skill's files from Builder FS. " +
+      "REQUIRES `confirm:true`. RECOVERY: the skill still lives in GitHub — `ateam_github_pull` rebuilds the whole solution (no per-skill restore path).",
     inputSchema: {
       type: "object",
       properties: {
@@ -544,15 +645,22 @@ export const tools = [
           type: "string",
           description: "The skill ID to remove (e.g. 'linkedin-agent')",
         },
+        confirm: {
+          type: "boolean",
+          description: "REQUIRED. Must be exactly true. A missing/false value refuses the call with a recovery hint.",
+        },
       },
-      required: ["solution_id", "skill_id"],
+      required: ["solution_id", "skill_id", "confirm"],
     },
   },
   {
     name: "ateam_delete_connector",
     core: true,
     description:
-      "Remove a connector from a deployed solution. Stops and deletes it from A-Team Core, removes references from the solution definition (grants, platform_connectors) and skill definitions (connectors array), and cleans up mcp-store files.",
+      "⚠️ CASCADING — any skill whose engine.bootstrap_tools or tools[] name a tool from this connector will FAIL its next execution. " +
+      "Stops and deletes the connector from A-Team Core; drops references from the solution definition (grants, platform_connectors, ui_plugins ids starting `mcp:<connector-id>:*`) and skill definitions (connectors array); cleans up mcp-store files. " +
+      "GitHub source is preserved — a follow-up `ateam_build_and_run(github:true)` can resurrect. " +
+      "REQUIRES `confirm:true`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -564,8 +672,12 @@ export const tools = [
           type: "string",
           description: "The connector ID to remove (e.g. 'device-mock-mcp')",
         },
+        confirm: {
+          type: "boolean",
+          description: "REQUIRED. Must be exactly true. A missing/false value refuses the call with a recovery hint.",
+        },
       },
-      required: ["solution_id", "connector_id"],
+      required: ["solution_id", "connector_id", "confirm"],
     },
   },
 
@@ -993,6 +1105,45 @@ export const tools = [
       required: ["job_id"],
     },
   },
+  {
+    name: "ateam_get_widget_catalog",
+    core: true,
+    description:
+      "Get the live catalog of widgets (UI plugins) available in this tenant's solution. Returns platform-bundled + solution-bundled + skill-declared widgets, each with a paste-ready how_to_use block (solution.json snippet + opener_call + persona_phrasing + binding_notes).\n\n" +
+      "Use this when wiring widgets into a skill or solution — the how_to_use block is designed to be copied verbatim into the solution.json ui_plugins[] entry and into the persona's opener phrasing, so you don't have to hand-roll either. The catalog reflects what is actually deployed in the tenant right now, not the abstract spec (for the spec itself, use ateam_get_spec topic='widgets').\n\n" +
+      "Origins:\n" +
+      "  • 'platform' = widgets bundled with the platform (always available).\n" +
+      "  • 'solution' = widgets bundled with this tenant's solution.\n" +
+      "  • 'skill' = widgets declared by a specific skill in the solution.\n\n" +
+      "Auth: forwards your authed api_key to Core (no master-secret involvement). Tenant scope is pinned by the key itself.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        solution_id: {
+          type: "string",
+          description: "Optional. The solution to query. Defaults to the tenant's current solution.",
+        },
+        origin: {
+          type: "string",
+          enum: ["all", "platform", "solution", "skill"],
+          description:
+            "Optional. Filter by widget origin. 'all' (default) returns everything. 'platform' = platform-bundled only. 'solution' = solution-bundled only. 'skill' = skill-declared only.",
+        },
+        include_unused: {
+          type: "boolean",
+          description:
+            "Optional. If true, includes widgets that are available but not currently referenced by any skill or ui_plugins entry. Default false (only widgets actually wired into the solution).",
+        },
+        format: {
+          type: "string",
+          enum: ["summary", "full"],
+          description:
+            "Optional. 'full' (default) returns each widget with its paste-ready how_to_use block (solution.json snippet, opener_call, persona_phrasing, binding_notes). 'summary' returns just id/name/origin/description for a quick overview.",
+        },
+      },
+      required: [],
+    },
+  },
   {
     name: "ateam_test_abort",
     core: true,
@@ -1512,6 +1663,7 @@ const SPEC_PATHS = {
   enums: "/spec/enums",
   "connector-multi-user": "/spec/multi-user-connector",
   python_helpers: "/spec/python_helpers",
+  widgets: "/spec/widgets",
 };
 
 const EXAMPLE_PATHS = {
@@ -1554,6 +1706,7 @@ const TENANT_TOOLS = new Set([
   "ateam_test_status",
   "ateam_test_abort",
   "ateam_get_chain",
+  "ateam_get_widget_catalog",
   "ateam_get_connector_source",
   "ateam_get_metrics",
   "ateam_diff",
@@ -2494,9 +2647,10 @@ const handlers = {
   // Updates → Redeploys → Optionally tests
   // One call replaces: ateam_update + ateam_redeploy
 
-  ateam_patch: async ({ solution_id, target, skill_id, updates, test_message }, sid) => {
+  ateam_patch: async ({ solution_id, target, skill_id, updates, test_message, dry_run }, sid) => {
     const phases = [];
     let isNewSkill = false;
+    const _diff = { arrays_merged: [], arrays_replaced: [], scalars_changed: [], sections_replaced: [] };
 
     // GitHub-first patch: read from GitHub → apply patch → write back → redeploy
     // This ensures GitHub stays the single source of truth.
@@ -2528,7 +2682,7 @@ const handlers = {
           role: { name: "", persona: "", goals: [], limitations: [], communication_style: { tone: "professional", verbosity: "concise" } },
           intents: { supported: [], thresholds: { accept: 0.8, clarify: 0.5, reject: 0.5 }, out_of_domain: { action: "redirect", message: "" } },
           tools: [],
-          policy: { guardrails: { never: [], always: [] }, approvals: [], workflows: [], escalation: { enabled: false, conditions: [], target: "" } },
+          policy: { access: { requires_roles: [] }, guardrails: { never: [], always: [] }, approvals: [], workflows: [], escalation: { enabled: false, conditions: [], target: "" } },
           engine: { rv2: { max_iterations: 10, iteration_timeout_ms: 120000, allow_parallel_tools: false, on_max_iterations: "ask_user" }, hlr: { enabled: true, critic: { enabled: true, check_interval: 3, strictness: "medium" }, reflection: { enabled: true, depth: "shallow" }, replanning: { enabled: true, max_replans: 3 } }, autonomy: { level: "supervised" }, finalization_gate: { enabled: true, max_retries: 2 } },
           access_policy: { rules: [{ tools: ["*"], effect: "allow" }] },
           grant_mappings: [],
@@ -2615,9 +2769,30 @@ const handlers = {
             else arr.push(upd);
           }
           parent[leaf] = arr;
+        } else if (key === "_replace" || key.endsWith("_replace")) {
+          // Escape-hatch flags handled by the guard — skip them here so they
+          // don't get written into the patched object as literal fields.
+          continue;
         } else if (key.includes(".")) {
           // Dot notation: "role.persona", "intents.thresholds.accept"
           const parts = key.split(".");
+          // Sibling-loss guard: if the leaf resolves to an existing non-empty
+          // array and the incoming value is also an array, refuse the replace
+          // unless the caller opted in. (Dot-notation is how many agents
+          // accidentally hit this — e.g. updates:{ "linked_skills": ["one"] }
+          // on target='solution'.)
+          const leafKey = parts[parts.length - 1];
+          let cursor = patched;
+          for (let i = 0; i < parts.length - 1; i++) {
+            if (!cursor || typeof cursor[parts[i]] !== 'object') { cursor = null; break; }
+            cursor = cursor[parts[i]];
+          }
+          const currentLeaf = cursor && Object.prototype.hasOwnProperty.call(cursor, leafKey) ? cursor[leafKey] : undefined;
+          const guardErr = _guardArrayReplace({ target, key: leafKey, value, current: currentLeaf, updates });
+          if (guardErr) return guardErr;
+          if (Array.isArray(value) && Array.isArray(currentLeaf)) _diff.arrays_replaced.push(key);
+          else if (typeof value === 'object' && value !== null && !Array.isArray(value)) _diff.sections_replaced.push(key);
+          else _diff.scalars_changed.push(key);
           let obj = patched;
           for (let i = 0; i < parts.length - 1; i++) {
             if (!obj[parts[i]] || typeof obj[parts[i]] !== "object") obj[parts[i]] = {};
@@ -2625,7 +2800,14 @@ const handlers = {
           }
           obj[parts[parts.length - 1]] = value;
         } else {
-          // Direct field replacement
+          // Direct top-level field replacement. Sibling-loss guard: if this
+          // names a known array field and would drop items, refuse unless the
+          // caller passed _replace:true (object-level) or <field>_replace:true.
+          const guardErr = _guardArrayReplace({ target, key, value, current: patched[key], updates });
+          if (guardErr) return guardErr;
+          if (Array.isArray(value) && Array.isArray(patched[key])) _diff.arrays_replaced.push(key);
+          else if (typeof value === 'object' && value !== null && !Array.isArray(value)) _diff.sections_replaced.push(key);
+          else _diff.scalars_changed.push(key);
           patched[key] = value;
         }
       }
@@ -2634,6 +2816,23 @@ const handlers = {
       return { ok: false, phase: "patch", error: `Failed to apply patch: ${err.message}` };
     }
 
+    // Dry-run: return diff + would-be after-state without writing to GitHub
+    // or redeploying. Lets an agent preview any destructive-looking edit.
+    if (dry_run) {
+      return {
+        ok: true,
+        dry_run: true,
+        target,
+        solution_id,
+        skill_id,
+        phases,
+        _diff,
+        after_state: patched,
+        would_write_bytes: JSON.stringify(patched, null, 2).length,
+        hint: "No changes applied. Remove dry_run:true to commit + redeploy.",
+      };
+    }
+
     // Phase 3: Write patched version back to GitHub
     try {
       const patchKeys = Object.keys(updates || {});
@@ -3097,6 +3296,84 @@ const handlers = {
     return data;
   },
 
+  ateam_get_widget_catalog: async ({ origin, format }, sid) => {
+    // Wraps Core's existing GET /api/ui-plugins (merged tenant plugin list)
+    // and enriches each entry with the documentation/how-to-use layer.
+    // Filtering by origin and the summary/full format projection happen
+    // client-side here — Core just returns the raw merged plugins[].
+    const creds = getCredentials(sid);
+    const apiKey = creds?.apiKey;
+    if (!apiKey) throw new Error("No api_key in session — call ateam_auth(api_key) first.");
+    const coreUrl = process.env.ADAS_CORE_URL || "http://adas-backend:4000";
+    const res = await fetch(`${coreUrl}/api/ui-plugins`, {
+      method: "GET",
+      headers: { "x-api-key": apiKey, "X-ADAS-SERVICE": "ateam-mcp.get_widget_catalog" },
+      signal: AbortSignal.timeout(15_000),
+    });
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = { ok: false, error: text.slice(0, 400) }; }
+    if (!res.ok) {
+      throw new Error(`Core /api/ui-plugins returned ${res.status}: ${data.error || JSON.stringify(data).slice(0, 200)}`);
+    }
+
+    // Project each plugin into the catalog shape with how_to_use guidance.
+    const plugins = Array.isArray(data?.plugins) ? data.plugins : [];
+    const wantSummary = format === "summary";
+    const filterOrigin = origin && origin !== "all" ? origin : null;
+
+    const widgets = plugins.map((p) => {
+      const id = p?.id || "";
+      const shortId = id.split(":").pop() || id;
+      // origin classification: platform vs solution vs skill
+      const src = p?._source || "";
+      const inferredOrigin = src === "mcp_introspection" ? "platform"
+        : src === "skill_declared" ? "skill"
+        : "solution";
+      const opener = Array.isArray(p?.capabilities?.commands) && p.capabilities.commands.length > 0
+        ? `ui.${shortId}.${p.capabilities.commands[0].name || "open"}({ /* args per input_schema */ })`
+        : `sys.focusUiPlugin({ plugin_id: "${id}" })`;
+      const entry = {
+        id,
+        name: p?.name,
+        version: p?.version,
+        description: p?.description,
+        type: p?.type || "ui",
+        origin: inferredOrigin,
+        owned_by_connector: p?._connector_id,
+        render: p?.render,
+        surface: p?.surface,
+        capabilities: p?.capabilities,
+        channels: p?.channels,
+        commands: p?.capabilities?.commands || p?.commands || [],
+        uiActions: p?.uiActions,
+      };
+      if (!wantSummary) {
+        entry.how_to_use = {
+          solution_json_snippet: { id, name: p?.name, version: p?.version, render: p?.render },
+          opener_call: opener,
+          persona_phrasing: `When the user wants to view ${(p?.description || p?.name || shortId).toString().toLowerCase()}, call ${opener.split("(")[0]}.`,
+          binding_notes: {
+            commands_input_schemas: (p?.capabilities?.commands || []).map(c => ({ command: c.name, schema: c.input_schema })),
+            deeplink_template: p?.uiActions?.deeplink || null,
+            view_entity_kinds: p?.uiActions?.intents?.view_entity?.entity_kinds || null,
+            host_auto_routes_intents: Object.keys(p?.uiActions?.intents || {}),
+          },
+        };
+      }
+      return entry;
+    });
+
+    const filtered = filterOrigin ? widgets.filter(w => w.origin === filterOrigin) : widgets;
+    const counts = {
+      total: filtered.length,
+      platform: filtered.filter(w => w.origin === "platform").length,
+      solution: filtered.filter(w => w.origin === "solution").length,
+      skill: filtered.filter(w => w.origin === "skill").length,
+    };
+    return { ok: true, generated_at: new Date().toISOString(), counts, widgets: filtered };
+  },
+
   ateam_test_abort: async ({ solution_id, skill_id, job_id }, sid) =>
     del(`/deploy/solutions/${solution_id}/skills/${skill_id}/test/${job_id}`, sid),
 
@@ -3245,14 +3522,46 @@ const handlers = {
   ateam_github_list_versions: async ({ solution_id }, sid) =>
     get(`/deploy/solutions/${solution_id}/versions/dev`, sid),
 
-  ateam_delete_solution: async ({ solution_id }, sid) =>
-    del(`/deploy/solutions/${solution_id}`, sid),
+  ateam_delete_solution: async ({ solution_id, confirm, confirm_solution_id }, sid) => {
+    if (confirm !== true) {
+      return {
+        ok: false,
+        error: "⚠️ REFUSED: ateam_delete_solution requires confirm:true. This is irreversible in Core + Builder FS. GitHub source is preserved — ateam_github_pull rebuilds from `main` if you already deleted by mistake.",
+        recovery: "ateam_github_pull(solution_id, ref:'main')",
+      };
+    }
+    if (confirm_solution_id !== solution_id) {
+      return {
+        ok: false,
+        error: `⚠️ REFUSED: confirm_solution_id must exactly equal solution_id. Got confirm_solution_id="${confirm_solution_id}" but solution_id="${solution_id}". This check defeats typos and hallucinated ids — you should not be able to wipe a solution whose id you can't spell correctly.`,
+        expected: solution_id,
+        received: confirm_solution_id,
+      };
+    }
+    return del(`/deploy/solutions/${solution_id}`, sid);
+  },
 
-  ateam_delete_skill: async ({ solution_id, skill_id }, sid) =>
-    del(`/deploy/solutions/${solution_id}/skills/${skill_id}`, sid),
+  ateam_delete_skill: async ({ solution_id, skill_id, confirm }, sid) => {
+    if (confirm !== true) {
+      return {
+        ok: false,
+        error: `⚠️ REFUSED: ateam_delete_skill requires confirm:true. Kills the running MCP process and deletes the skill from Core + Builder FS. GitHub source is preserved — ateam_github_pull rebuilds the whole solution.`,
+        recovery: "ateam_github_pull(solution_id, ref:'main') — no per-skill restore path",
+      };
+    }
+    return del(`/deploy/solutions/${solution_id}/skills/${skill_id}`, sid);
+  },
 
-  ateam_delete_connector: async ({ solution_id, connector_id }, sid) =>
-    del(`/deploy/solutions/${solution_id}/connectors/${connector_id}`, sid),
+  ateam_delete_connector: async ({ solution_id, connector_id, confirm }, sid) => {
+    if (confirm !== true) {
+      return {
+        ok: false,
+        error: `⚠️ REFUSED: ateam_delete_connector requires confirm:true. Cascading — any skill wired to this connector's tools will fail its next execution. GitHub source is preserved.`,
+        recovery: "ateam_build_and_run(solution_id, github:true) can resurrect from GitHub",
+      };
+    }
+    return del(`/deploy/solutions/${solution_id}/connectors/${connector_id}`, sid);
+  },
 
   ateam_upload_connector: async ({ solution_id, connector_id, github, files, ref, replace }, sid) =>
     post(