@ateam-ai/mcp 0.3.57 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai/mcp",
-  "version": "0.3.57",
+  "version": "0.4.1",
   "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 = [
@@ -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,16 @@ 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.",
+        },
+        source: {
+          type: "string",
+          enum: ["github", "local"],
+          description:
+            "Where the solution/skill definition lives. 'github' (DEFAULT) — read from and write to the tenant's GitHub repo (GitHub is master; the normal path). 'local' — read from and write to the Builder FS store (no GitHub repo required). Use 'local' ONLY for a repo-less bootstrap tenant (e.g. freshly onboarded from a template, before GitHub is connected). This is a DEDICATED, EXPLICIT switch — never a fallback. Redeploy is local in both modes.",
+        },
       },
       required: ["solution_id", "target", "updates"],
     },
@@ -516,7 +612,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 +622,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 +651,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 +678,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"],
     },
   },
 
@@ -2535,21 +2653,45 @@ 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, source }, sid) => {
     const phases = [];
     let isNewSkill = false;
-
-    // GitHub-first patch: read from GitHub → apply patch → write back → redeploy
-    // This ensures GitHub stays the single source of truth.
-
-    // Phase 1: Read current state from GitHub (or create scaffold if new skill)
+    const _diff = { arrays_merged: [], arrays_replaced: [], scalars_changed: [], sections_replaced: [] };
+
+    // Two backing stores, chosen EXPLICITLY by `source` (never inferred):
+    //   'github' (default) — GitHub-first: read from GitHub → apply patch → write
+    //     back → redeploy. GitHub stays the single source of truth.
+    //   'local' — Builder-FS-first: read from and write to the Builder store for a
+    //     repo-less bootstrap tenant (freshly onboarded from a template, GitHub not
+    //     yet connected). GitHub is still master overall; local is a temporary
+    //     bootstrap until the tenant connects a repo (then local is pushed → GitHub).
+    // Redeploy (Phase 4) is local (Builder FS → Core) in BOTH modes.
+    const isLocal = source === "local";
+
+    // Phase 1: Read current state (or create scaffold if new skill)
     let current;
     const filePath = target === "skill" && skill_id
       ? `skills/${skill_id}/skill.json`
       : `solution.json`;
     try {
-      const readResult = await get(`/deploy/solutions/${solution_id}/github/read?path=${encodeURIComponent(filePath)}`, sid);
-      current = JSON.parse(readResult.content);
+      if (isLocal) {
+        // Read the raw definition from the Builder store — no GitHub repo needed.
+        if (target === "skill" && skill_id) {
+          const r = await get(`/deploy/solutions/${solution_id}/skills/${encodeURIComponent(skill_id)}`, sid);
+          current = r.skill || r.definition || r;
+        } else {
+          // ?raw=1 → the agent-api returns the UNSTRIPPED solution (keeps
+          // linked_skills/conversation) so _delete/_push operate on the real arrays.
+          const r = await get(`/deploy/solutions/${solution_id}/definition?raw=1`, sid);
+          current = r.solution || r;
+        }
+        if (!current || typeof current !== "object") {
+          throw new Error(`Local ${filePath} not found (empty definition)`);
+        }
+      } else {
+        const readResult = await get(`/deploy/solutions/${solution_id}/github/read?path=${encodeURIComponent(filePath)}`, sid);
+        current = JSON.parse(readResult.content);
+      }
     } catch (err) {
       // If it's a skill that doesn't exist yet, create a default scaffold.
       // This lets agents use ateam_patch to both CREATE and UPDATE skills —
@@ -2569,7 +2711,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: [],
@@ -2581,7 +2723,7 @@ const handlers = {
         };
         phases.push({ phase: "read", status: "created_scaffold", skill_id });
       } else {
-        return { ok: false, phase: "read", error: `Failed to read ${filePath} from GitHub: ${err.message}` };
+        return { ok: false, phase: "read", error: `Failed to read ${filePath} from ${isLocal ? "Builder store (local)" : "GitHub"}: ${err.message}` };
       }
     }
 
@@ -2656,9 +2798,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]] = {};
@@ -2666,7 +2829,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;
         }
       }
@@ -2675,42 +2845,80 @@ const handlers = {
       return { ok: false, phase: "patch", error: `Failed to apply patch: ${err.message}` };
     }
 
-    // Phase 3: Write patched version back to GitHub
+    // 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 the chosen store.
     try {
       const patchKeys = Object.keys(updates || {});
       const message = `Patch: ${target}${skill_id ? ` ${skill_id}` : ""} — ${patchKeys.join(", ")}`;
-      await post(`/deploy/solutions/${solution_id}/github/patch`, {
-        path: filePath,
-        content: JSON.stringify(patched, null, 2),
-        message,
-      }, sid, { timeoutMs: 30_000 });
-      phases.push({ phase: "github_write", status: "done" });
+      if (isLocal) {
+        // Write the FULL patched object to the Builder store. Top-level keys are
+        // replaced (removals honored) — the client-side merge above already
+        // resolved _push/_delete/_update, so we send the resolved object.
+        const endpoint = (target === "skill" && skill_id)
+          ? `/deploy/solutions/${solution_id}/skills/${encodeURIComponent(skill_id)}`
+          : `/deploy/solutions/${solution_id}`;
+        await patch(endpoint, { state_update: patched }, sid, { timeoutMs: 30_000 });
+        phases.push({ phase: "local_write", status: "done" });
+      } else {
+        await post(`/deploy/solutions/${solution_id}/github/patch`, {
+          path: filePath,
+          content: JSON.stringify(patched, null, 2),
+          message,
+        }, sid, { timeoutMs: 30_000 });
+        phases.push({ phase: "github_write", status: "done" });
+      }
     } catch (err) {
-      return { ok: false, phase: "github_write", error: `Patch applied but failed to write to GitHub: ${err.message}`, phases };
+      const store = isLocal ? "Builder store (local)" : "GitHub";
+      return { ok: false, phase: isLocal ? "local_write" : "github_write", error: `Patch applied but failed to write to ${store}: ${err.message}`, phases };
     }
 
     // Phase 3b: If new skill, add it to solution.json topology (skills[], linked_skills)
     if (isNewSkill && skill_id) {
       try {
-        const solRead = await get(`/deploy/solutions/${solution_id}/github/read?path=solution.json`, sid);
-        const sol = JSON.parse(solRead.content);
         const skillEntry = { id: skill_id, name: patched.name || skill_id, role: "worker", description: patched.description || "", connectors: patched.connectors || [] };
-        // Add to skills[] if not already present
-        if (!sol.skills) sol.skills = [];
-        if (!sol.skills.find(s => s.id === skill_id)) {
-          sol.skills.push(skillEntry);
-        }
-        // Add to linked_skills if not already present
-        if (!sol.linked_skills) sol.linked_skills = [];
-        if (!sol.linked_skills.includes(skill_id)) {
-          sol.linked_skills.push(skill_id);
+        if (isLocal) {
+          // Local: _push the entries via the Builder store (dedup handled by the
+          // store's _push — it updates in place if the id already exists).
+          await patch(`/deploy/solutions/${solution_id}`, {
+            state_update: { skills_push: [skillEntry], linked_skills_push: [skill_id] },
+          }, sid, { timeoutMs: 30_000 });
+          phases.push({ phase: "solution_topology", status: "done", added: skill_id });
+        } else {
+          const solRead = await get(`/deploy/solutions/${solution_id}/github/read?path=solution.json`, sid);
+          const sol = JSON.parse(solRead.content);
+          // Add to skills[] if not already present
+          if (!sol.skills) sol.skills = [];
+          if (!sol.skills.find(s => s.id === skill_id)) {
+            sol.skills.push(skillEntry);
+          }
+          // Add to linked_skills if not already present
+          if (!sol.linked_skills) sol.linked_skills = [];
+          if (!sol.linked_skills.includes(skill_id)) {
+            sol.linked_skills.push(skill_id);
+          }
+          await post(`/deploy/solutions/${solution_id}/github/patch`, {
+            path: "solution.json",
+            content: JSON.stringify(sol, null, 2),
+            message: `Add skill "${skill_id}" to solution topology`,
+          }, sid, { timeoutMs: 30_000 });
+          phases.push({ phase: "solution_topology", status: "done", added: skill_id });
         }
-        await post(`/deploy/solutions/${solution_id}/github/patch`, {
-          path: "solution.json",
-          content: JSON.stringify(sol, null, 2),
-          message: `Add skill "${skill_id}" to solution topology`,
-        }, sid, { timeoutMs: 30_000 });
-        phases.push({ phase: "solution_topology", status: "done", added: skill_id });
       } catch (err) {
         // Non-fatal: skill.json was written, topology can be fixed manually
         phases.push({ phase: "solution_topology", status: "warning", error: err.message });
@@ -2756,19 +2964,23 @@ const handlers = {
     }
 
     const redeployOk = phases.some(p => p.phase === "redeploy" && p.status === "done");
+    const store = isLocal ? "Builder store (local)" : "GitHub";
     return {
       ok: true,
       solution_id,
-      branch: 'main',
+      source: isLocal ? "local" : "github",
+      ...(isLocal ? {} : { branch: 'main' }),
       phases,
       patched: patched,
       ...(isNewSkill && { created_skill: skill_id }),
       ...(redeployResult && { redeploy: redeployResult }),
       ...(test_result && { test_result }),
       _status: redeployOk
-        ? '✅ Patched on GitHub + redeployed.'
-        : '⚠️ Patched on GitHub ✅ but redeploy timed out. Run: ateam_redeploy(solution_id' + (skill_id ? `, skill_id: "${skill_id}"` : '') + ')',
-      _next: 'Create a checkpoint before making more changes: ateam_github_promote(solution_id)',
+        ? `✅ Patched on ${store} + redeployed.`
+        : `⚠️ Patched on ${store} ✅ but redeploy timed out. Run: ateam_redeploy(solution_id` + (skill_id ? `, skill_id: "${skill_id}"` : '') + ')',
+      _next: isLocal
+        ? 'Local edit saved + redeployed. When the tenant connects a GitHub repo, the local state is pushed → GitHub (which then becomes master).'
+        : 'Create a checkpoint before making more changes: ateam_github_promote(solution_id)',
     };
   },
 
@@ -3364,14 +3576,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(