@wairon/cli 5.1.1-dev.88 → 5.1.1-dev.89

package/dist/cli/index.js

@@ -65,7 +65,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.88";
+    WAIRON_VERSION = "5.1.1-dev.89";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -201,6 +201,7 @@ var fs_exports = {};
 __export(fs_exports, {
   aiDir: () => aiDir,
   aiDirAt: () => aiDirAt,
+  backupBeside: () => backupBeside,
   currentRootBinding: () => currentRootBinding,
   ensureDir: () => ensureDir,
   findProjectRoot: () => findProjectRoot,
@@ -211,6 +212,7 @@ __export(fs_exports, {
   getProjectRootOverride: () => getProjectRootOverride,
   getRequestParentReach: () => getRequestParentReach,
   getRequestProjectRoot: () => getRequestProjectRoot,
+  isOutsideRoot: () => isOutsideRoot,
   listFiles: () => listFiles,
   listFilesRecursive: () => listFilesRecursive,
   pathExists: () => pathExists,
@@ -248,6 +250,15 @@ function readFileOrNull(filePath) {
 function pathExists(targetPath) {
   return fs3.existsSync(targetPath);
 }
+function isOutsideRoot(root, target) {
+  const rel2 = path4.relative(path4.resolve(root), path4.resolve(target));
+  return rel2 === ".." || rel2.startsWith(`..${path4.sep}`) || path4.isAbsolute(rel2);
+}
+function backupBeside(file, at = /* @__PURE__ */ new Date()) {
+  const backup = `${file}.wairon-backup-${at.toISOString().replace(/[:.]/g, "-")}`;
+  fs3.copyFileSync(file, backup);
+  return backup;
+}
 function listFiles(dirPath, ext) {
   if (!fs3.existsSync(dirPath)) return [];
   return fs3.readdirSync(dirPath).filter((f) => f.endsWith(ext)).map((f) => path4.join(dirPath, f));
@@ -2831,6 +2842,12 @@ function parseDeclaredCall(ref) {
   if (at <= 0 || at === ref.length - 1) return null;
   return { compId: ref.slice(0, at), methodName: ref.slice(at + 1) };
 }
+function technologyName(tech) {
+  return typeof tech === "string" ? tech : tech.name;
+}
+function technologyTokens(tech) {
+  return typeof tech === "string" ? [tech] : [...tech.matches];
+}
 function methodSourceFile(method2, implementationSourcePath) {
   return method2.sourcePath || implementationSourcePath || void 0;
 }
@@ -2890,7 +2907,7 @@ function typeSourceFiles(type) {
   for (const method2 of type.methods ?? []) add2(method2.sourcePath);
   return files;
 }
-var import_zod8, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, RETIRED_STEREOTYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, DependencyClassSchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, PortalAuthSchemeSchema, PortalAuthSchema, PortalMountSchema, ComponentSpecSchema, BLOCK_NOUNS, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, FindingDeclarationSchema, MethodSignatureSchema, INTENT_FLOOR_MIN_CHARS, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceTypeExportSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, ExternalLockEntrySchema, ExternalsLockSchema, NamedOpenApiSpecSchema, GroupSpecSchema;
+var import_zod8, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, RETIRED_STEREOTYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, DependencyClassSchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, PortalAuthSchemeSchema, PortalAuthSchema, PortalMountSchema, ComponentSpecSchema, BLOCK_NOUNS, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, FindingDeclarationSchema, MethodSignatureSchema, INTENT_FLOOR_MIN_CHARS, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, TechnologySchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceTypeExportSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, ExternalLockEntrySchema, ExternalsLockSchema, NamedOpenApiSpecSchema, GroupSpecSchema;
 var init_specs = __esm({
   "src/models/specs.ts"() {
     "use strict";
@@ -3564,6 +3581,13 @@ var init_specs = __esm({
       /** Opaque pack/tool extension data (see ExtDataSchema) — preserved verbatim. */
       ext: ExtDataSchema.optional()
     });
+    TechnologySchema = import_zod8.z.union([
+      import_zod8.z.string().min(1),
+      import_zod8.z.object({
+        name: import_zod8.z.string().min(1),
+        matches: import_zod8.z.array(import_zod8.z.string().min(1)).min(1)
+      }).strict()
+    ]);
     ImplementationSpecSchema = import_zod8.z.object({
       id: SpecIdSchema,
       name: import_zod8.z.string(),
@@ -3588,9 +3612,10 @@ var init_specs = __esm({
        * component's ownership tree the technology's home: references anywhere
        * outside it are flagged (TECH_LEAKAGE), contract identifiers must stay
        * intent-language (VENDOR_NAME_IN_CONTRACT), and only data-layer
-       * stereotypes should bind tech directly (TECH_ON_LOGIC_COMPONENT).
+       * stereotypes should bind tech directly (TECH_ON_LOGIC_COMPONENT). An entry
+       * is a bare name or `{ name, matches }` (see TechnologySchema).
        */
-      technologies: import_zod8.z.array(import_zod8.z.string()).optional(),
+      technologies: import_zod8.z.array(TechnologySchema).optional(),
       /**
        * The parameter names THIS realization takes BEFORE the ones its contract
        * declares — a config object, a data root, the transport handles a portal is
@@ -19143,6 +19168,7 @@ var DATA_LAYER, technologyBindingRule;
 var init_technology_binding = __esm({
   "src/core/rules/heuristic/technology-binding.ts"() {
     "use strict";
+    init_models();
     DATA_LAYER = /* @__PURE__ */ new Set(["Adapter", "Store", "Registry", "Index"]);
     technologyBindingRule = {
       name: "technology-binding",
@@ -19159,7 +19185,7 @@ var init_technology_binding = __esm({
           ctx.addIssue(
             "warning",
             "TECH_ON_LOGIC_COMPONENT",
-            `Implementation "${impl.id}" binds technology (${impl.technologies.join(", ")}) on component "${comp.id}" (${comp.componentType}). Technology belongs behind a data-layer seam \u2014 extract an Adapter (or Store/Registry/Index) behind an intent interface and let this component depend on that.`,
+            `Implementation "${impl.id}" binds technology (${impl.technologies.map(technologyName).join(", ")}) on component "${comp.id}" (${comp.componentType}). Technology belongs behind a data-layer seam \u2014 extract an Adapter (or Store/Registry/Index) behind an intent interface and let this component depend on that.`,
             impl.id,
             ctx.isImplementationDraft(impl)
           );
@@ -19186,6 +19212,16 @@ function makeMatcher(tech) {
     return false;
   };
 }
+function newHome(label7) {
+  const home = {
+    label: label7,
+    matchers: [],
+    match: (text3) => home.matchers.some((m) => m(text3)),
+    ownerComponents: /* @__PURE__ */ new Set(),
+    scope: /* @__PURE__ */ new Set()
+  };
+  return home;
+}
 function contractIdentifiers(m) {
   const parts = [m.name, m.signature, m.returns];
   for (const p of m.params ?? []) parts.push(p.name, p.type);
@@ -19212,7 +19248,7 @@ var init_technology_boundaries = __esm({
     technologyRule = {
       name: "technology-boundaries",
       judges: "design",
-      description: "Technology stays behind its owning boundary: an L4 that declares `technologies` (e.g. [mysql]) makes its component's ownership tree the technology's home. References outside that tree are leakage, and L3 contract identifiers must stay intent-language \u2014 the contract is the swap seam, so the vendor name is wrong even on the owning component's own interface.",
+      description: "Technology stays behind its owning boundary: an L4 that declares `technologies` (e.g. [mysql]) makes its component's ownership tree the technology's home. References outside that tree are leakage, and L3 contract identifiers must stay intent-language \u2014 the contract is the swap seam, so the vendor name is wrong even on the owning component's own interface. A technology is matched by its name, or \u2014 when it declares `matches` because its name is also an ordinary word of the tree (a package named after the file format it reads) \u2014 by those tokens alone.",
       codes: [
         { code: "TECH_LEAKAGE", defaultSeverity: "warning", summary: "Technology referenced outside its owning boundary" },
         { code: "VENDOR_NAME_IN_CONTRACT", defaultSeverity: "warning", summary: "Technology name in L3 contract identifiers" }
@@ -19249,7 +19285,9 @@ var init_technology_boundaries = __esm({
           const intf = ctx.interfaceMap.get(impl.contract);
           const comp = intf ? ctx.componentMap.get(intf.component) : void 0;
           if (!comp) continue;
-          for (const tech of impl.technologies) declarations.push({ comp, tech });
+          for (const tech of impl.technologies) {
+            declarations.push({ comp, name: technologyName(tech), tokens: technologyTokens(tech) });
+          }
         }
         const scopes = /* @__PURE__ */ new Map();
         const scopeOf3 = (comp) => {
@@ -19273,11 +19311,12 @@ var init_technology_boundaries = __esm({
           return scope;
         };
         const homes = /* @__PURE__ */ new Map();
-        for (const { comp, tech } of declarations) {
-          const match2 = makeMatcher(tech);
-          if (!match2) continue;
-          const key = tech.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join("");
-          const home = homes.get(key) ?? { label: tech, match: match2, ownerComponents: /* @__PURE__ */ new Set(), scope: /* @__PURE__ */ new Set() };
+        for (const { comp, name, tokens } of declarations) {
+          const matchers = tokens.map(makeMatcher).filter((m) => m !== null);
+          if (!matchers.length) continue;
+          const key = name.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).join("");
+          const home = homes.get(key) ?? newHome(name);
+          home.matchers.push(...matchers);
           home.ownerComponents.add(comp.id);
           for (const id of scopeOf3(comp)) home.scope.add(id);
           homes.set(key, home);
@@ -22936,8 +22975,8 @@ function generateSequenceDiagram(componentId, methodName, options) {
     const steps = [...methodImpl.narrative].sort((a, b) => a.stepNumber - b.stepNumber);
     for (const step of steps) {
       for (const par of parallelArms) {
-        const sep16 = par.sepByStep.get(step.stepNumber);
-        if (sep16 !== void 0) lines.push(`  and ${escapeLabel(sep16)}`);
+        const sep17 = par.sepByStep.get(step.stepNumber);
+        if (sep17 !== void 0) lines.push(`  and ${escapeLabel(sep17)}`);
       }
       switch (step.type) {
         case "local":
@@ -24046,7 +24085,7 @@ function mapSpecReferences(kind, spec, map) {
       const s = spec;
       return {
         ...s,
-        publicInterfaces: s.publicInterfaces.map((p) => ({
+        publicInterfaces: (s.publicInterfaces ?? []).map((p) => ({
           ...p,
           ...p.component !== void 0 ? { component: map("publicInterfaces", p.component) } : {},
           ...p.interface !== void 0 ? { interface: map("publicInterfaces", p.interface) } : {},
@@ -24062,8 +24101,8 @@ function mapSpecReferences(kind, spec, map) {
       return {
         ...c,
         subsystem: map("subsystem", c.subsystem),
-        owns: c.owns.map((o) => map("owns", o)),
-        dependsOn: c.dependsOn.map((d) => map("dependsOn", d)),
+        owns: (c.owns ?? []).map((o) => map("owns", o)),
+        dependsOn: (c.dependsOn ?? []).map((d) => map("dependsOn", d)),
         ...c.dispatch ? { dispatch: c.dispatch.map((b) => ({ ...b, component: map("dispatch", b.component) })) } : {},
         ...c.mounts ? { mounts: c.mounts.map((m) => ({ ...m, portal: map("mounts", m.portal) })) } : {}
       };
@@ -24077,9 +24116,9 @@ function mapSpecReferences(kind, spec, map) {
       return {
         ...impl,
         contract: map("contract", impl.contract),
-        methods: impl.methods.map((m) => ({
+        methods: (impl.methods ?? []).map((m) => ({
           ...m,
-          narrative: m.narrative.map((step) => step.targetComponent !== void 0 ? { ...step, targetComponent: map("narrative", step.targetComponent) } : step)
+          narrative: (m.narrative ?? []).map((step) => step.targetComponent !== void 0 ? { ...step, targetComponent: map("narrative", step.targetComponent) } : step)
         }))
       };
     }
@@ -25459,7 +25498,7 @@ function rewriteReferences(kind, id, edits) {
 function moveMethods(from, to, methods, hooks, dryRun) {
   return current().moveMethods(from, to, methods, hooks, dryRun);
 }
-var fs14, path21, IMPORTABLE_POSITIONS, SIGNATURE_TTL_MS, COMPONENT_AUTH_SOURCE, STEP_JUMP_FIELDS, STEP_JUMP_LISTS, DELTA_VERBS, JUMP_LABEL_TWINS, LABEL_TWIN_CONTAINERS, SpecWorkspace, DEFAULT_DEPENDENCY_LIMIT, PROSE_FIELDS, workspaces, lastServedBinding;
+var fs14, path21, IMPORTABLE_POSITIONS, SIGNATURE_TTL_MS, COMPONENT_AUTH_SOURCE, STEP_JUMP_FIELDS, STEP_JUMP_LISTS, DELTA_VERBS, JUMP_LABEL_TWINS, LABEL_TWIN_CONTAINERS, SpecWorkspace, DEFAULT_DEPENDENCY_LIMIT, PROSE_FIELDS, DELTA_JUMP_PINS, workspaces, lastServedBinding;
 var init_specs2 = __esm({
   "src/core/specs.ts"() {
     "use strict";
@@ -26332,10 +26371,10 @@ var init_specs2 = __esm({
         return this.relativizeSpec("interface", spec);
       }
       prepareImplementationForWrite(spec, carry = true) {
-        const relative25 = this.relativizeSpec("implementation", spec, carry);
+        const relative26 = this.relativizeSpec("implementation", spec, carry);
         const member = this.getSubprojectPrefix(spec.id);
         const memberRoot = member ? this.resolveSubprojectForNamespace(member) : null;
-        return memberRoot ? childRelativeFilePaths(relative25, this.rootDir, memberRoot) : relative25;
+        return memberRoot ? childRelativeFilePaths(relative26, this.rootDir, memberRoot) : relative26;
       }
       prepareTypeForWrite(spec) {
         return this.relativizeSpec("type", spec);
@@ -27174,7 +27213,10 @@ var init_specs2 = __esm({
        *     second delete written as 7 addresses what used to be step 8. That is why
        *     a delete may restate the step's `label` or `description` as a guard, and
        *     why labels are the reliable way to name a jump target. Inserts and
-       *     deletes relocate every jump field in the same narrative around them; a
+       *     deletes relocate every STORED jump field in the same narrative around
+       *     them; a jump the delta itself writes is already in the numbering the
+       *     whole delta leaves behind, so none of its later steps moves it. A new
+       *     implementation method with no narrative is intent-level ([]); a
        *     step whose `type` changes is REBUILT for its new type, keeping its
        *     description and label.
        *  5. UNSET the fields the delta names, at the level each `unset` sits in.
@@ -27232,16 +27274,19 @@ var init_specs2 = __esm({
         }
         const JUMP_FIELDS = ["onTrueStep", "onFalseStep", "defaultStep", "endStep", "finallyStep", "toStep"];
         const JUMP_LIST_FIELDS = ["cases", "catches", "branches"];
+        const isPinned = (step, field) => step?.[DELTA_JUMP_PINS] instanceof Set && step[DELTA_JUMP_PINS].has(field);
+        const isPinnedEntry = (entry) => entry?.[DELTA_JUMP_PINS] === true;
         const relocateJumps = (step, shiftFrom, deltaN, captureInsertTarget = false) => {
           const hit = (v, isRegionTail = false) => deltaN > 0 ? captureInsertTarget && !isRegionTail ? v > shiftFrom : v >= shiftFrom : v > shiftFrom;
           const out = { ...step };
           for (const f of JUMP_FIELDS) {
+            if (isPinned(step, f)) continue;
             if (typeof out[f] === "number" && hit(out[f], f === "endStep")) out[f] = out[f] + deltaN;
           }
           for (const lf of JUMP_LIST_FIELDS) {
             if (Array.isArray(out[lf])) {
               out[lf] = out[lf].map(
-                (c) => typeof c?.step === "number" && hit(c.step) ? { ...c, step: c.step + deltaN } : c
+                (c) => !isPinnedEntry(c) && typeof c?.step === "number" && hit(c.step) ? { ...c, step: c.step + deltaN } : c
               );
             }
           }
@@ -27249,14 +27294,39 @@ var init_specs2 = __esm({
         };
         const jumpRefsTo = (step, target) => {
           const refs = [];
-          for (const f of JUMP_FIELDS) if (step[f] === target) refs.push(f);
+          for (const f of JUMP_FIELDS) if (step[f] === target && !isPinned(step, f)) refs.push(f);
           for (const lf of JUMP_LIST_FIELDS) {
             (Array.isArray(step[lf]) ? step[lf] : []).forEach((c, i) => {
-              if (c?.step === target) refs.push(`${lf}[${i}].step`);
+              if (c?.step === target && !isPinnedEntry(c)) refs.push(`${lf}[${i}].step`);
             });
           }
           return refs;
         };
+        const pinDeltaJumps = (deltaStep, carried) => {
+          const pins = new Set(carried ?? []);
+          for (const f of JUMP_FIELDS) if (typeof deltaStep[f] === "number") pins.add(f);
+          const out = { ...deltaStep };
+          for (const lf of JUMP_LIST_FIELDS) {
+            if (!Array.isArray(out[lf])) continue;
+            out[lf] = out[lf].map((c) => c && typeof c === "object" && typeof c.step === "number" ? { ...c, [DELTA_JUMP_PINS]: true } : c);
+          }
+          out[DELTA_JUMP_PINS] = pins;
+          return out;
+        };
+        const unpinned = (step) => {
+          const out = { ...step };
+          delete out[DELTA_JUMP_PINS];
+          for (const lf of JUMP_LIST_FIELDS) {
+            if (!Array.isArray(out[lf])) continue;
+            out[lf] = out[lf].map((c) => {
+              if (!c || typeof c !== "object" || !(DELTA_JUMP_PINS in c)) return c;
+              const entry = { ...c };
+              delete entry[DELTA_JUMP_PINS];
+              return entry;
+            });
+          }
+          return out;
+        };
         const normalizeIdentity = (k) => String(k ?? "").toLowerCase().replace(/[_\-\s]/g, "");
         const unsetFieldsOf = (item) => Array.isArray(item?.unset) ? item.unset.filter((f) => typeof f === "string") : [];
         const withUnset = (merged, deltaItem) => {
@@ -27436,21 +27506,24 @@ var init_specs2 = __esm({
                 capture
               ));
               const { action, remove: remove3, captureJumps, ...cleanStep } = deltaStep;
-              steps.push(withUnset(cleanStep, deltaStep));
+              steps.push(withUnset(pinDeltaJumps(cleanStep), deltaStep));
             } else {
               const idx = steps.findIndex((s) => s.stepNumber === stepNum);
               if (idx !== -1) {
-                const { action, remove: remove3, ...cleanStep } = deltaStep;
+                const { action, remove: remove3, ...rawStep } = deltaStep;
                 const stored = steps[idx];
+                const cleanStep = pinDeltaJumps(rawStep, stored[DELTA_JUMP_PINS]);
                 const merged = withUnset(retargetByLabel(mergeElement(stored, cleanStep), cleanStep), deltaStep);
-                steps[idx] = rebuildOnRetype(stored, cleanStep, merged, methodName);
+                const rebuilt = rebuildOnRetype(stored, rawStep, merged, methodName);
+                rebuilt[DELTA_JUMP_PINS] = cleanStep[DELTA_JUMP_PINS];
+                steps[idx] = rebuilt;
               } else {
                 const { action, remove: remove3, ...cleanStep } = deltaStep;
-                steps.push(withUnset(cleanStep, deltaStep));
+                steps.push(withUnset(pinDeltaJumps(cleanStep), deltaStep));
               }
             }
           }
-          return steps.sort((a, b) => a.stepNumber - b.stepNumber);
+          return steps.map(unpinned).sort((a, b) => a.stepNumber - b.stepNumber);
         };
         const isPlainObject2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
         const mergeExt = (existing, delta2) => {
@@ -27473,6 +27546,11 @@ var init_specs2 = __esm({
               } else {
                 const existingMethod = merged[idx];
                 let narrative = existingMethod.narrative ? [...existingMethod.narrative] : [];
+                if (deltaMethod.narrative !== void 0 && deltaMethod.narrative !== null && !Array.isArray(deltaMethod.narrative)) {
+                  throw new Error(
+                    `Refusing to update implementation method "${String(deltaMethod.name)}": its "narrative" must be a list of step deltas, got ${JSON.stringify(deltaMethod.narrative)}.`
+                  );
+                }
                 if (Array.isArray(deltaMethod.narrative)) {
                   narrative = deltaMethod.narrative.length === 0 ? [] : mergeNarrative(String(deltaMethod.name), narrative, deltaMethod.narrative);
                 }
@@ -27485,11 +27563,21 @@ var init_specs2 = __esm({
               }
             } else {
               assertUnmatchedIsAnAddition(deltaMethod, deltaMethod.name, merged.map((m) => m.name), "method");
-              merged.push(withUnset(deltaMethod, deltaMethod));
+              merged.push(withUnset(newMethodOf(deltaMethod), deltaMethod));
             }
           }
           return merged;
         };
+        const newMethodOf = (deltaMethod) => {
+          if (kind !== "implementation") return deltaMethod;
+          if (deltaMethod.narrative === void 0 || deltaMethod.narrative === null) return { ...deltaMethod, narrative: [] };
+          if (!Array.isArray(deltaMethod.narrative)) {
+            throw new Error(
+              `Refusing to add implementation method "${String(deltaMethod.name)}": its "narrative" must be a list of steps, got ${JSON.stringify(deltaMethod.narrative)}. Leave it out (or pass []) for an intent-level method.`
+            );
+          }
+          return deltaMethod;
+        };
         const mergeNamedArray = (existing, delta2) => {
           const merged = [...existing];
           for (const deltaItem of delta2) {
@@ -27667,6 +27755,12 @@ var init_specs2 = __esm({
         const qualifiedDelta = qualifyDeltaRefs(mergeableDelta);
         const mergedResult = mergeDelta(result, qualifiedDelta);
         for (const field of unsetFields) delete mergedResult[field];
+        const withDefaults = deltaSchema.safeParse(mergedResult);
+        if (withDefaults.success) {
+          for (const [key, value] of Object.entries(withDefaults.data)) {
+            if (!(key in mergedResult)) mergedResult[key] = value;
+          }
+        }
         if (kind === "implementation" && Array.isArray(mergedResult.methods)) {
           const labelErrors = [];
           for (const m of mergedResult.methods) {
@@ -28187,6 +28281,7 @@ var init_specs2 = __esm({
       "note",
       "caller"
     ]);
+    DELTA_JUMP_PINS = /* @__PURE__ */ Symbol("jumps written by this delta");
     workspaces = /* @__PURE__ */ new Map();
     lastServedBinding = null;
   }
@@ -30443,17 +30538,17 @@ function memberHop(agentId) {
   const alias = agentId.slice(0, at);
   const member = graph().nodes.find((n) => n.parent === "" && n.mountAlias === alias);
   if (!member) return null;
-  const relative25 = path28.relative(getProjectRoot(), member.directory).split(path28.sep).join("/");
-  return { alias, rest: agentId.slice(at + 2), directory: member.directory, relative: relative25 };
+  const relative26 = path28.relative(getProjectRoot(), member.directory).split(path28.sep).join("/");
+  return { alias, rest: agentId.slice(at + 2), directory: member.directory, relative: relative26 };
 }
-function throughMount(brief, alias, relative25) {
-  const under = (p) => path28.posix.join(relative25, p);
+function throughMount(brief, alias, relative26) {
+  const under = (p) => path28.posix.join(relative26, p);
   return {
     ...brief,
     agentId: `${alias}::${brief.agentId}`,
     ownedPaths: brief.ownedPaths.map(under),
     ...brief.readPaths ? { readPaths: brief.readPaths.map(under) } : {},
-    root: brief.root ? under(brief.root) : relative25
+    root: brief.root ? under(brief.root) : relative26
   };
 }
 function loadRegistry() {
@@ -33843,8 +33938,8 @@ var require_dist = __commonJS({
           walkPackDir(root, path90.join(current2, entry.name), out);
         } else if (entry.isFile()) {
           const absolute = path90.join(current2, entry.name);
-          const relative25 = path90.relative(root, absolute).split(path90.sep).join("/");
-          out.push({ path: relative25, contents: fs66.readFileSync(absolute) });
+          const relative26 = path90.relative(root, absolute).split(path90.sep).join("/");
+          out.push({ path: relative26, contents: fs66.readFileSync(absolute) });
         }
       }
     }
@@ -34151,19 +34246,19 @@ function commitStagedTree(stagingDir, destDir, roots, backupExisting) {
   const backupDir = path33.join(root, BACKUP_DIR, timestampSlug());
   let backedUp = false;
   for (const rootRel of roots) {
-    const relative25 = rootRel === "." ? "" : rootRel;
-    const stagedSpecDir = path33.join(stagingDir, relative25, ".wai");
+    const relative26 = rootRel === "." ? "" : rootRel;
+    const stagedSpecDir = path33.join(stagingDir, relative26, ".wai");
     if (!fs19.existsSync(stagedSpecDir)) continue;
-    const liveSpecDir = liveSpecDirFor(path33.join(root, relative25));
+    const liveSpecDir = liveSpecDirFor(path33.join(root, relative26));
     if (backupExisting && liveSpecDir && fs19.existsSync(liveSpecDir)) {
-      const backupTarget = path33.join(backupDir, relative25, path33.basename(liveSpecDir));
+      const backupTarget = path33.join(backupDir, relative26, path33.basename(liveSpecDir));
       fs19.mkdirSync(path33.dirname(backupTarget), { recursive: true });
       fs19.renameSync(liveSpecDir, backupTarget);
       backedUp = true;
     } else if (liveSpecDir && fs19.existsSync(liveSpecDir)) {
       fs19.rmSync(liveSpecDir, { recursive: true, force: true });
     }
-    const target = path33.join(root, relative25, ".wai");
+    const target = path33.join(root, relative26, ".wai");
     fs19.mkdirSync(path33.dirname(target), { recursive: true });
     if (fs19.existsSync(target)) fs19.rmSync(target, { recursive: true, force: true });
     fs19.renameSync(stagedSpecDir, target);
@@ -34806,7 +34901,7 @@ function contextDir(...segments) {
   return aiDir("context", ...segments);
 }
 function hasContext() {
-  return pathExists(CONTEXT_PATHS.projectMd());
+  return pathExists(CONTEXT_PATHS.dir());
 }
 function readProjectContext() {
   return readFileOrNull(CONTEXT_PATHS.projectMd());
@@ -40373,7 +40468,7 @@ ${renderChangeReport(report3)}`,
     contract: import_zod11.z.string().describe("The L3 Interface contract ID this implements"),
     sourcePath: import_zod11.z.string().optional().describe("Optional: target source code file path relative to project root \u2014 for a chained subproject's implementation (qualified id), relative to that subproject's root; a path given relative to this root that lands inside the subproject is re-expressed for you"),
     simPath: import_zod11.z.string().optional().describe("Optional: the committed integration-sim harness file (project-relative; N:1 sharing allowed). The validator proves it exists and its import graph wires the REAL modules (this component + each direct dependency; technology adapters may stay faked) \u2014 running it is CI's job. Declaring the first simPath in a subsystem activates MISSING_INTEGRATION_SIM for its other complete non-leaf implementations"),
-    technologies: import_zod11.z.array(import_zod11.z.string()).optional().describe(`External technologies this implementation binds to (e.g. ["mysql"]) \u2014 declares this component's ownership tree as the technology's home; references outside it are flagged (TECH_LEAKAGE) and contract identifiers must stay intent-language. Only for Adapter/Store/Registry/Index components.`),
+    technologies: import_zod11.z.array(import_zod11.z.union([import_zod11.z.string(), import_zod11.z.object({ name: import_zod11.z.string(), matches: import_zod11.z.array(import_zod11.z.string()).min(1).describe("The tokens the leakage and contract checks match INSTEAD of the name \u2014 for a technology whose name is also an ordinary word of the tree (the yaml package, the YAML format)") }).strict()])).optional().describe(`External technologies this implementation binds to (e.g. ["mysql"], or [{ "name": "yaml", "matches": ["yaml package", "parseDocument"] }] when the bare name would match a common word) \u2014 declares this component's ownership tree as the technology's home; references outside it are flagged (TECH_LEAKAGE) and contract identifiers must stay intent-language. Only for Adapter/Store/Registry/Index components.`),
     injectedParams: import_zod11.z.array(import_zod11.z.string()).optional().describe("The parameter names this realization takes BEFORE the ones its contract declares \u2014 a config object, a data root, the transport handles a portal is handed. Supplied by whatever wires the component up, never by the caller the contract describes, which is why they belong here and not to the contract: another realization may hold them as fields instead. Declared rather than guessed, because a leading parameter the contract does not name cannot be told from one it named under a different name (`seed(config)` realized as `bootstrapInstance(cfg)`); a leading parameter this list does not name is reported (UNDECLARED_PARAM). Only a LEADING run is dropped \u2014 one of these names appearing after the contract's own parameters is an argument in the middle of the caller's list, not wiring"),
     detail: detailEnum.optional().describe("Spec-level narrative detail default for all methods"),
     conformance: conformanceEnum.optional().describe("Spec-level conformance tier default: declared | anchored | off (omitted = stereotype default: Portal \u2192 anchored, else declared)"),
@@ -40652,7 +40747,7 @@ ${testsBlock}` : ""}`, deletion);
       inputSchema: {
         kind: import_zod11.z.enum(["system", "subsystem", "component", "interface", "implementation", "type"]).describe("The spec kind to update (system = the singleton L0 \u2014 vision, boundaries, globalRequirements, databases, and publicInterfaces: the project export table, each entry a re-export {from, component, interface, typeDef, as, name, type, details, audience: project|department|instance|partner|external} \u2014 from alone re-exports everything a subsystem exports, and a legacy {id, subsystem} reads as {as, from})"),
         id: import_zod11.z.string().describe("The ID of the spec to update (namespaced if needed)"),
-        delta: import_zod11.z.record(import_zod11.z.any()).describe(`The partial fields to merge into the spec. ARRAYS UPSERT, they do not replace: an array whose elements carry an identity is merged element-by-element, so a delta naming ONE element leaves the others intact. Identity is "name" or "id" by default, and per field: dispatch by "capability", a listener's mounts by "portal", lifecycle by phase+component+method, emits/subscribesTo by topic+event, trustedLinks by "subsystem", a subsystem's publicInterfaces by component+interface (or type+details for an entry not yet bound to a component, and by from+item+interface+as for a re-export or a type export), invariants and patterns by "id", lint.allow by "code" AND "at" (an allow covers one occurrence, so several may share a code on one spec), an interface method's findings by "code", boundaries by "name", globalRequirements by "description", switch cases by "value", try catches by "error". Identity merging applies at EVERY depth, including an array INSIDE an element (a method's params, a step's catches). Add "action: 'delete'" (or "remove: true") alongside that identity to REMOVE an element \u2014 including a stale lint allow. Arrays of plain STRINGS (owns, dependsOn, guarantees) carry no per-element identity and are replaced wholesale; pass [] to clear any array outright. To REMOVE an optional field entirely, list it in "unset": e.g. {"unset": ["basePath", "variant"]} \u2014 passing null/undefined means "no change" (they are skipped), and writing "" would leave the field present but empty, which is a different and usually wrong spec. Unsetting a required field is refused by schema validation, which names it. For narrative steps, match by "stepNumber" and use "action: 'insert'" (shifts subsequent steps up) or "action: 'delete'" (shifts subsequent steps down and removes it). Step entries apply in ASCENDING stepNumber order, each against the numbering the earlier entries of the SAME delta left behind \u2014 delete step 3 and step 7 becomes step 6 \u2014 so prefer labels, and restate the step's "label" or "description" on a delete to have it checked against the step actually addressed. Renumbering RELOCATES every flow jump field (onTrueStep/onFalseStep/cases.step/defaultStep/endStep/catches.step/finallyStep/toStep) in the same narrative. A delete is REJECTED when the narrative has no such step, when a jump still targets it (retarget the referrers first), when a restated label/description does not match, or when it is a loop/try/parallel header whose body would be left standing (retype the header first to dissolve the region, then delete it). Changing a step's "type" REBUILDS it for the new type: its description and label are kept and every field the new type cannot carry is dropped (returned as a NOTICE); a delta that retypes AND sets such a field is refused. A step delta is also refused when it carries a marker the merge does not recognise: a non-boolean "remove", an "action" that is neither "insert" nor "delete", a "captureJumps" outside an insert, or no "stepNumber" to address. Inserting AT a jump target relocates those jumps past the inserted step by default (a NOTICE is returned) \u2014 add "captureJumps": true on the inserted step to retarget entry jumps onto it (loop/try endStep region tails always relocate with the body and are never captured). Every jump field has a "*Label" twin (toLabel, onFalseLabel, endLabel, \u2026, and "label" on a cases/catches entry) resolved against step labels AFTER the merge, so a delta may anchor on a label only pre-existing steps carry; a label the delta supplies REPLACES the stored number it twins, while setting the number and its label together in one delta is refused as a contradiction. Reference ids in deltas may use LOCAL names \u2014 they are qualified against the spec's namespace exactly as the loader would. Per-spec lint suppression: set "lint: { allow: [{ code, at, covers, reason }] }" to silence a WARNING or NOTICE code on this spec only (errors always surface; stale allows are flagged). An allow covers EXACTLY the occurrence it names: "at" is the site the finding names (a contract method, an import edge "from -> to", a declared edge "component -> target") and is REQUIRED for a code whose findings report one, while a finding that reports no site is covered only by an allow that names none; "covers" lists the units an aggregating finding reports, and the allow silences it only when every one is listed. This delta is deliberately OPEN below its top level \u2014 the shapes nest further than a schema here should restate \u2014 so a key that is not a field at its depth is not refused, it is NAMED BACK under NO EFFECT in the answer, together with any value the spec already held and any "unset" that removed nothing. Read that list: it is where a nested typo shows up.`),
+        delta: import_zod11.z.record(import_zod11.z.any()).describe(`The partial fields to merge into the spec. ARRAYS UPSERT, they do not replace: an array whose elements carry an identity is merged element-by-element, so a delta naming ONE element leaves the others intact. Identity is "name" or "id" by default, and per field: dispatch by "capability", a listener's mounts by "portal", lifecycle by phase+component+method, emits/subscribesTo by topic+event, trustedLinks by "subsystem", a subsystem's publicInterfaces by component+interface (or type+details for an entry not yet bound to a component, and by from+item+interface+as for a re-export or a type export), invariants and patterns by "id", lint.allow by "code" AND "at" (an allow covers one occurrence, so several may share a code on one spec), an interface method's findings by "code", boundaries by "name", globalRequirements by "description", switch cases by "value", try catches by "error". Identity merging applies at EVERY depth, including an array INSIDE an element (a method's params, a step's catches). Add "action: 'delete'" (or "remove: true") alongside that identity to REMOVE an element \u2014 including a stale lint allow. Arrays of plain STRINGS (owns, dependsOn, guarantees) carry no per-element identity and are replaced wholesale; pass [] to clear any array outright. To REMOVE an optional field entirely, list it in "unset": e.g. {"unset": ["basePath", "variant"]} \u2014 passing null/undefined means "no change" (they are skipped), and writing "" would leave the field present but empty, which is a different and usually wrong spec. Unsetting a required field is refused by schema validation, which names it. For narrative steps, match by "stepNumber" and use "action: 'insert'" (shifts subsequent steps up) or "action: 'delete'" (shifts subsequent steps down and removes it). Step entries apply in ASCENDING stepNumber order, each against the numbering the earlier entries of the SAME delta left behind \u2014 delete step 3 and step 7 becomes step 6 \u2014 so prefer labels, and restate the step's "label" or "description" on a delete to have it checked against the step actually addressed. Renumbering RELOCATES every flow jump field (onTrueStep/onFalseStep/cases.step/defaultStep/endStep/catches.step/finallyStep/toStep) in the same narrative. Only STORED jumps relocate: a jump the delta itself writes (on an inserted, appended or edited step) names its target in the numbering the WHOLE delta leaves behind, after all of its inserts and deletes, and no later step of the same delta moves it. A method the delta ADDS without a narrative is an intent-level method with none ([]). A delete is REJECTED when the narrative has no such step, when a jump still targets it (retarget the referrers first), when a restated label/description does not match, or when it is a loop/try/parallel header whose body would be left standing (retype the header first to dissolve the region, then delete it). Changing a step's "type" REBUILDS it for the new type: its description and label are kept and every field the new type cannot carry is dropped (returned as a NOTICE); a delta that retypes AND sets such a field is refused. A step delta is also refused when it carries a marker the merge does not recognise: a non-boolean "remove", an "action" that is neither "insert" nor "delete", a "captureJumps" outside an insert, or no "stepNumber" to address. Inserting AT a jump target relocates those jumps past the inserted step by default (a NOTICE is returned) \u2014 add "captureJumps": true on the inserted step to retarget entry jumps onto it (loop/try endStep region tails always relocate with the body and are never captured). Every jump field has a "*Label" twin (toLabel, onFalseLabel, endLabel, \u2026, and "label" on a cases/catches entry) resolved against step labels AFTER the merge, so a delta may anchor on a label only pre-existing steps carry; a label the delta supplies REPLACES the stored number it twins, while setting the number and its label together in one delta is refused as a contradiction. Reference ids in deltas may use LOCAL names \u2014 they are qualified against the spec's namespace exactly as the loader would. Per-spec lint suppression: set "lint: { allow: [{ code, at, covers, reason }] }" to silence a WARNING or NOTICE code on this spec only (errors always surface; stale allows are flagged). An allow covers EXACTLY the occurrence it names: "at" is the site the finding names (a contract method, an import edge "from -> to", a declared edge "component -> target") and is REQUIRED for a code whose findings report one, while a finding that reports no site is covered only by an allow that names none; "covers" lists the units an aggregating finding reports, and the allow silences it only when every one is listed. This delta is deliberately OPEN below its top level \u2014 the shapes nest further than a schema here should restate \u2014 so a key that is not a field at its depth is not refused, it is NAMED BACK under NO EFFECT in the answer, together with any value the spec already held and any "unset" that removed nothing. Read that list: it is where a nested typo shows up.`),
         dryRun: import_zod11.z.boolean().optional().describe("Ask what this delta WOULD do instead of doing it. The whole write runs, the candidate gate included, and the answer is the change report it would have produced \u2014 marked DRY RUN, with nothing stamped and not one byte of the stored file moved. Use it before a delta that renumbers a long narrative.")
       },
       outputSchema: specChangeReportOutput
@@ -41202,8 +41297,10 @@ var mcp_exports = {};
 __export(mcp_exports, {
   claudeMcpConfigPath: () => claudeMcpConfigPath,
   detectHostedMcpSource: () => detectHostedMcpSource,
+  findLegacyPlugin: () => findLegacyPlugin,
   normalizeBackend: () => normalizeBackend,
-  removeLegacyGlobalPlugin: () => removeLegacyGlobalPlugin,
+  planMcpInstall: () => planMcpInstall,
+  retireLegacyPlugin: () => retireLegacyPlugin,
   runMcpInstall: () => runMcpInstall,
   runMcpServe: () => runMcpServe,
   runMcpStatus: () => runMcpStatus,
@@ -41335,33 +41432,27 @@ function normalizeBackend(input) {
     `Unknown --backend "${input}". Supported: claude (Claude Code) or gemini (a.k.a. agy / antigravity \u2014 both are Gemini-based). MCP auto-registration for codex / cursor / copilot is not yet supported; configure those manually.`
   );
 }
-async function runMcpInstall(options = {}) {
+function resolveBackends(options) {
+  if (options.backend) return [normalizeBackend(options.backend)];
+  const backends = [];
+  try {
+    const config = loadProjectConfig();
+    const enabledTypes = (config?.targets ?? []).filter((t) => !("enabled" in t) || t.enabled).map((t) => t.type);
+    if (enabledTypes.includes("claude")) backends.push("claude");
+    if (enabledTypes.includes("gemini") || enabledTypes.includes("agy")) backends.push("gemini");
+  } catch {
+  }
+  return backends.length ? backends : ["claude"];
+}
+function resolveInstallTargets(options) {
   assertProjectInitialized();
   if (options.configDir && !options.backend) {
     throw new WaironError("--config-dir requires --backend (claude or gemini), since a config dir is agent-specific.");
   }
-  let backends = [];
-  if (options.backend) {
-    backends = [normalizeBackend(options.backend)];
-  } else {
-    try {
-      const config = loadProjectConfig();
-      const enabledTypes = (config?.targets ?? []).filter((t) => !("enabled" in t) || t.enabled).map((t) => t.type);
-      if (enabledTypes.includes("claude")) {
-        backends.push("claude");
-      }
-      if (enabledTypes.includes("gemini") || enabledTypes.includes("agy")) {
-        backends.push("gemini");
-      }
-    } catch {
-    }
-    if (backends.length === 0) {
-      backends = ["claude"];
-    }
-  }
-  for (const backend of backends) {
+  const root = getProjectRoot();
+  return resolveBackends(options).map((backend) => {
     if (options.configDir) validateConfigDir(options.configDir, backend);
-    const useGlobal = options.global || !!options.configDir;
+    const useGlobal = !!(options.global || options.configDir);
     let configBase;
     let settingsPath;
     if (backend === "gemini") {
@@ -41385,40 +41476,75 @@ async function runMcpInstall(options = {}) {
       }
     }
     const mcpServers = settings["mcpServers"] ?? {};
-    const agentLabel = backend === "gemini" ? "Antigravity" : "Claude";
     const isPackaged = typeof process.pkg !== "undefined";
     const scriptPath = process.argv[1] ? path48.resolve(process.argv[1]).replace(/\\/g, "/") : null;
     const useDirectNode = !isPackaged && scriptPath && (scriptPath.endsWith(".js") || scriptPath.endsWith(".ts"));
     const env = useGlobal ? {} : { WAIRON_PROJECT_DIR: process.cwd().replace(/\\/g, "/") };
     const desiredEntry = options.hostedUrl ? hostedMcpEntry(options) : useDirectNode ? { command: "node", args: [scriptPath, "mcp", "serve"], env } : { command: "wairon", args: ["mcp", "serve"], env };
     const existingEntry = mcpServers["wairon"];
-    if (existingEntry && JSON.stringify(existingEntry) === JSON.stringify(desiredEntry)) {
-      logger.info(`wairon MCP server already registered (up to date) for ${agentLabel} in ${import_chalk3.default.gray(settingsPath)}.`);
+    return {
+      backend,
+      path: settingsPath,
+      outsideProject: isOutsideRoot(root, settingsPath),
+      ...existingEntry !== void 0 ? { before: existingEntry } : {},
+      after: desiredEntry,
+      upToDate: !!existingEntry && JSON.stringify(existingEntry) === JSON.stringify(desiredEntry),
+      configBase,
+      settings,
+      useGlobal
+    };
+  });
+}
+function planMcpInstall(options) {
+  return resolveInstallTargets(options).map(({ backend, path: file, outsideProject, before, after, upToDate }) => ({
+    backend,
+    path: file,
+    outsideProject,
+    ...before !== void 0 ? { before } : {},
+    after,
+    upToDate
+  }));
+}
+async function runMcpInstall(options = {}) {
+  for (const target of resolveInstallTargets(options)) {
+    const agentLabel = target.backend === "gemini" ? "Antigravity" : "Claude";
+    if (target.upToDate) {
+      logger.info(`wairon MCP server already registered (up to date) for ${agentLabel} in ${import_chalk3.default.gray(target.path)}.`);
       continue;
     }
-    const wasStale = !!existingEntry;
-    mcpServers["wairon"] = desiredEntry;
-    settings["mcpServers"] = mcpServers;
-    if (!fs28.existsSync(configBase)) fs28.mkdirSync(configBase, { recursive: true });
-    fs28.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-    logger.success(`wairon MCP server ${wasStale ? "updated (was stale)" : "registered"} for ${agentLabel} in ${import_chalk3.default.cyan(settingsPath)}.`);
-    logger.blank();
-    logger.info("AI tools using this config will have access to these wairon tools:");
-    logger.info("  listAgents \xB7 getAgent \xB7 listDomains \xB7 validateTopology \xB7 getProjectConfig");
-    logger.info("  sdd_initialize_system \xB7 sdd_add_subsystem \xB7 sdd_add_component \xB7 sdd_define_interface");
-    logger.info("  sdd_write_narrative \xB7 sdd_validate_tree \xB7 sdd_get_status");
-    logger.blank();
-    const restartApp = backend === "gemini" ? "Antigravity CLI (agy)" : "claude";
-    logger.info(`Restart ${import_chalk3.default.bold(restartApp)} (or reload MCP servers) to activate.`);
-    if (backend === "claude" && !useGlobal) {
-      logger.warn('Claude shows project .mcp.json servers as "\u23F8 Pending approval" \u2014 approve wairon once on next launch (or run `claude` and accept the trust prompt).');
-    }
-    if (backend === "gemini" && !useGlobal) {
-      logger.warn("Note: Antigravity (agy) reads MCP servers from its global ~/.gemini/antigravity-cli/mcp_config.json, not this project file.");
-      logger.warn("If the agent cannot see the sdd_* tools, run: " + import_chalk3.default.bold("wairon mcp install --backend gemini --global"));
-    }
-    logger.blank();
+    writeInstallTarget(target);
+    reportInstalled(target, agentLabel);
+  }
+}
+function writeInstallTarget(target) {
+  const mcpServers = target.settings["mcpServers"] ?? {};
+  mcpServers["wairon"] = target.after;
+  target.settings["mcpServers"] = mcpServers;
+  if (!fs28.existsSync(target.configBase)) fs28.mkdirSync(target.configBase, { recursive: true });
+  if (target.outsideProject && fs28.existsSync(target.path)) {
+    logger.info(`Backed up ${import_chalk3.default.gray(target.path)} to ${import_chalk3.default.cyan(backupBeside(target.path))} before replacing it (outside the project root).`);
   }
+  fs28.writeFileSync(target.path, JSON.stringify(target.settings, null, 2) + "\n");
+}
+function reportInstalled(target, agentLabel) {
+  const wasStale = target.before !== void 0;
+  logger.success(`wairon MCP server ${wasStale ? "updated (was stale)" : "registered"} for ${agentLabel} in ${import_chalk3.default.cyan(target.path)}.`);
+  logger.blank();
+  logger.info("AI tools using this config will have access to these wairon tools:");
+  logger.info("  listAgents \xB7 getAgent \xB7 listDomains \xB7 validateTopology \xB7 getProjectConfig");
+  logger.info("  sdd_initialize_system \xB7 sdd_add_subsystem \xB7 sdd_add_component \xB7 sdd_define_interface");
+  logger.info("  sdd_write_narrative \xB7 sdd_validate_tree \xB7 sdd_get_status");
+  logger.blank();
+  const restartApp = target.backend === "gemini" ? "Antigravity CLI (agy)" : "claude";
+  logger.info(`Restart ${import_chalk3.default.bold(restartApp)} (or reload MCP servers) to activate.`);
+  if (target.backend === "claude" && !target.useGlobal) {
+    logger.warn('Claude shows project .mcp.json servers as "\u23F8 Pending approval" \u2014 approve wairon once on next launch (or run `claude` and accept the trust prompt).');
+  }
+  if (target.backend === "gemini" && !target.useGlobal) {
+    logger.warn("Note: Antigravity (agy) reads MCP servers from its global ~/.gemini/antigravity-cli/mcp_config.json, not this project file.");
+    logger.warn("If the agent cannot see the sdd_* tools, run: " + import_chalk3.default.bold("wairon mcp install --backend gemini --global"));
+  }
+  logger.blank();
 }
 async function runMcpStatus() {
   assertProjectInitialized();
@@ -41475,19 +41601,25 @@ function hostedMcpEntry(options) {
   if (options.hostedProject) headers["X-Wairon-Project"] = options.hostedProject;
   return { type: "http", url: `${base}/mcp`, headers };
 }
-function removeLegacyGlobalPlugin() {
-  const home = process.env["USERPROFILE"] ?? process.env["HOME"] ?? os8.homedir();
-  const pluginDir = path48.join(home, ".gemini", "config", "plugins", "wairon");
+function legacyPluginDir() {
+  return path48.join(geminiGlobalDir(), "config", "plugins", "wairon");
+}
+function findLegacyPlugin() {
+  const dir = legacyPluginDir();
+  return fs28.existsSync(dir) ? dir : null;
+}
+function retireLegacyPlugin() {
+  const dir = findLegacyPlugin();
+  if (!dir) return null;
+  const backup = path48.join(path48.dirname(path48.dirname(dir)), `wairon-plugin.wairon-backup-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
   try {
-    if (fs28.existsSync(pluginDir)) {
-      fs28.rmSync(pluginDir, { recursive: true, force: true });
-      logger.info(`Removed legacy global Antigravity plugin at ${import_chalk3.default.gray(pluginDir)} (it collides with the wairon MCP server).`);
-      return true;
-    }
+    fs28.renameSync(dir, backup);
+    logger.info(`Moved the legacy global Antigravity plugin ${import_chalk3.default.gray(dir)} aside to ${import_chalk3.default.cyan(backup)} (it collides with the wairon MCP server).`);
+    return backup;
   } catch (e) {
-    logger.warn(`Could not remove legacy wairon Antigravity plugin: ${String(e)}`);
+    logger.warn(`Could not move the legacy wairon Antigravity plugin aside: ${String(e)}`);
+    return null;
   }
-  return false;
 }
 var fs28, os8, path48, import_chalk3;
 var init_mcp = __esm({
@@ -42399,10 +42531,12 @@ init_base();
 init_fs();
 init_project();
 var WAIRON_AGENT_FILE = /-(owner|implementer|architect)\.md$/;
-function pruneStaleAgents(expectedPaths, scanDirs) {
+function pruneStaleAgents(expectedPaths, scanDirs, reach2) {
   const dirs = new Set(scanDirs ?? [...expectedPaths].map((p) => path50.dirname(p)));
   let pruned = 0;
   for (const dir of dirs) {
+    const outside = reach2 !== void 0 && isOutsideRoot(reach2.root, dir);
+    if (outside && !reach2.global) continue;
     let entries;
     try {
       entries = fs29.readdirSync(dir);
@@ -42422,6 +42556,7 @@ function pruneStaleAgents(expectedPaths, scanDirs) {
         }
       }
       if (!owned) continue;
+      if (outside) logger.info(`Backed up ${full} to ${backupBeside(full)} before pruning it (outside the project root).`);
       fs29.unlinkSync(full);
       pruned++;
       logger.verbose(`Pruned stale: ${full}`);
@@ -42429,6 +42564,28 @@ function pruneStaleAgents(expectedPaths, scanDirs) {
   }
   return pruned;
 }
+function targetsOutsideRoot(projectConfig, root) {
+  const out = [];
+  for (const target of projectConfig.targets) {
+    if (typeof target === "string" || !("outputDir" in target) || !target.outputDir) continue;
+    if ("enabled" in target && target.enabled === false) continue;
+    const dir = path50.resolve(root, target.outputDir);
+    if (isOutsideRoot(root, dir)) out.push({ type: target.type, dir });
+  }
+  return out;
+}
+function announceOutsideTargets(projectConfig, reach2) {
+  const outside = targetsOutsideRoot(projectConfig, reach2.root);
+  if (!outside.length) return [];
+  if (reach2.global) {
+    for (const t of outside) logger.info(`Target "${t.type}" writes agent files outside the project root, to ${t.dir} (--global): each file replaced or pruned there is backed up beside itself first.`);
+    return [];
+  }
+  for (const t of outside) {
+    logger.warn(`Skipped target "${t.type}": its agent files would land outside the project root, in ${t.dir}. Nothing was written or pruned there \u2014 re-run with --global to write there (each replaced file is backed up beside itself).`);
+  }
+  return outside.map((t) => t.type);
+}
 async function runGenerate(options = {}) {
   await generateLayer(options);
   const scoped = options.root || options.domain || options.domains;
@@ -42452,13 +42609,15 @@ async function generateLayer(options = {}) {
     logger.warn("No agents resolved from the spec tree. Define subsystems and components first \u2014 see `wairon status`.");
     return;
   }
+  const reach2 = { root: getProjectRoot(), global: options.global === true };
+  const skippedTargets = announceOutsideTargets(projectConfig, reach2);
   if (projectConfig.rules.materializeAgentFiles) {
-    materializeAgentLayer(agents, projectConfig, options);
+    materializeAgentLayer(agents, projectConfig, options, reach2, skippedTargets);
   } else if (options.dryRun) {
     logger.info("Dry run \u2014 rules.materializeAgentFiles is off: no agent files are written; leftover managed files would be removed.");
   } else if (options.prune !== false) {
     const candidateDirs = [...resolveExpectedOutputPaths(agents, projectConfig)].map((p) => path50.dirname(p));
-    const removed = pruneStaleAgents(/* @__PURE__ */ new Set(), candidateDirs);
+    const removed = pruneStaleAgents(/* @__PURE__ */ new Set(), candidateDirs, reach2);
     if (removed > 0) {
       logger.info(`Removed ${removed} previously materialized agent file(s) \u2014 agents are served as live briefs (sdd_get_agent_brief); opt back in with rules.materializeAgentFiles: true.`);
     }
@@ -42483,8 +42642,17 @@ async function generateLayer(options = {}) {
     logger.warn(`Failed to re-inject AI guides: ${String(err)}`);
   }
 }
-function materializeAgentLayer(agents, projectConfig, options) {
-  const filterTargets = options.target ? [options.target] : void 0;
+function backUpOutsideFiles(agents, projectConfig, reach2) {
+  const backups = /* @__PURE__ */ new Map();
+  if (!reach2.global) return backups;
+  for (const file of resolveExpectedOutputPaths(agents, projectConfig)) {
+    if (isOutsideRoot(reach2.root, file) && pathExists(file)) backups.set(path50.resolve(file), backupBeside(file));
+  }
+  return backups;
+}
+function materializeAgentLayer(agents, projectConfig, options, reach2, skippedTargets) {
+  const configured = activeTargetTypes(projectConfig);
+  const filterTargets = options.target ? [options.target].filter((t) => !skippedTargets.includes(t)) : skippedTargets.length ? configured.filter((t) => !skippedTargets.includes(t)) : void 0;
   let filterDomainIds;
   if (options.root) {
     filterDomainIds = ["root"];
@@ -42500,6 +42668,7 @@ function materializeAgentLayer(agents, projectConfig, options) {
   }
   logger.info(`Generating ${agentPool.length} agent(s)...`);
   logger.blank();
+  const backups = options.dryRun ? /* @__PURE__ */ new Map() : backUpOutsideFiles(agents, projectConfig, reach2);
   const summaries = generateAll(agents, projectConfig, {
     filterTargets,
     filterDomainIds,
@@ -42518,13 +42687,19 @@ function materializeAgentLayer(agents, projectConfig, options) {
         } else {
           logger.success(`Written:   ${result.outputPath}`);
           written++;
+          const backup = backups.get(path50.resolve(result.outputPath));
+          if (backup) {
+            logger.info(`Backed up the replaced ${result.outputPath} to ${backup}.`);
+            backups.delete(path50.resolve(result.outputPath));
+          }
         }
       }
     }
   }
+  for (const backup of backups.values()) fs29.rmSync(backup, { force: true });
   let prunedCount = 0;
   if (!options.dryRun && options.prune !== false) {
-    prunedCount = pruneStaleAgents(resolveExpectedOutputPaths(agents, projectConfig));
+    prunedCount = pruneStaleAgents(resolveExpectedOutputPaths(agents, projectConfig), void 0, reach2);
   }
   logger.blank();
   if (options.dryRun) {
@@ -44279,9 +44454,9 @@ async function runDoctor(options = {}) {
       line(tally, hp.mark === "error" ? "error" : "ok", `Gemini CLI (project): ${hp.note} ${import_chalk12.default.gray("(Antigravity ignores this file)")}`);
     }
   }
-  const pluginDir = path54.join(os10.homedir(), ".gemini", "config", "plugins", "wairon");
-  if (fs32.existsSync(pluginDir)) {
-    line(tally, "warn", `Legacy Antigravity plugin present (${pluginDir}) \u2014 it collides with the wairon MCP server. Remove it with \`wairon doctor --fix\`.`);
+  const pluginDir = findLegacyPlugin();
+  if (pluginDir) {
+    line(tally, "warn", `Legacy Antigravity plugin present (${pluginDir}) \u2014 it collides with the wairon MCP server. Move it aside with \`wairon doctor --fix --global\` (it is outside the project, so --fix asks first).`);
   }
   logger.blank();
   printSummary(tally);
@@ -44358,28 +44533,70 @@ async function applyFixes(options, tally) {
     console.log(`  ${icon("error")} Narrative-step repair failed: ${e instanceof Error ? e.message : String(e)}`);
   }
   await migrateChaining(options, tally);
-  const { runMcpInstall: runMcpInstall2 } = (init_mcp(), __toCommonJS(mcp_exports));
-  if (targets.includes("claude")) {
+  await repairMcpRegistration(options, targets);
+  logger.blank();
+}
+async function repairMcpRegistration(options, targets) {
+  const installs = [];
+  if (targets.includes("claude")) installs.push({ backend: "claude", global: false });
+  const gemini = targets.includes("gemini") || targets.includes("agy");
+  if (gemini) installs.push({ backend: "gemini", global: targets.includes("agy") });
+  const outside = [];
+  for (const install of installs) {
+    let writes;
     try {
-      await runMcpInstall2({ backend: "claude", global: false });
+      writes = planMcpInstall(install);
     } catch (e) {
-      console.log(`  ${icon("warn")} MCP install for claude failed: ${e instanceof Error ? e.message : String(e)}`);
+      console.log(`  ${icon("warn")} MCP install for ${install.backend} could not be planned: ${e instanceof Error ? e.message : String(e)}`);
+      continue;
     }
+    if (writes.some((w) => w.outsideProject && !w.upToDate)) outside.push({ install, writes });
+    else await installMcp(install);
   }
-  if (targets.includes("gemini") || targets.includes("agy")) {
-    const global = targets.includes("agy");
-    try {
-      await runMcpInstall2({ backend: "gemini", global });
-    } catch (e) {
-      console.log(`  ${icon("warn")} MCP install for gemini failed: ${e instanceof Error ? e.message : String(e)}`);
-    }
-    try {
-      const { removeLegacyGlobalPlugin: removeLegacyGlobalPlugin2 } = (init_mcp(), __toCommonJS(mcp_exports));
-      if (removeLegacyGlobalPlugin2()) console.log(`  ${icon("ok")} Removed the legacy global Antigravity plugin (name collided with the MCP server).`);
-    } catch {
+  const plugin = gemini ? findLegacyPlugin() : null;
+  if (outside.length === 0 && !plugin) return;
+  printOutsideWrites(outside, plugin);
+  if (!await confirmOutsideWrites(options)) return;
+  for (const planned of outside) await installMcp(planned.install);
+  if (plugin) retireLegacyPlugin();
+}
+async function installMcp(install) {
+  try {
+    await runMcpInstall(install);
+  } catch (e) {
+    console.log(`  ${icon("warn")} MCP install for ${install.backend} failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+function printOutsideWrites(outside, plugin) {
+  console.log(`  ${icon("warn")} ${import_chalk12.default.bold("Writes outside this project")} \u2014 machine-wide state every project on this machine shares:`);
+  for (const { writes } of outside) {
+    for (const w of writes.filter((x) => x.outsideProject && !x.upToDate)) {
+      console.log(`      ${w.path} (${w.backend} MCP registration)`);
+      console.log(`        mcpServers.wairon now: ${describeMcpEntry(w.before)}`);
+      console.log(`        mcpServers.wairon new: ${describeMcpEntry(w.after)}`);
+      console.log("        the file is backed up beside itself before it is replaced");
     }
   }
-  logger.blank();
+  if (plugin) console.log(`      ${plugin} (legacy Antigravity plugin) \u2014 moved aside, not deleted`);
+}
+function describeMcpEntry(entry) {
+  if (entry === void 0 || entry === null) return "(none)";
+  const text3 = JSON.stringify(entry, (key, value) => key === "Authorization" && typeof value === "string" ? value.replace(/^(\S+\s+).+$/, "$1***") : value);
+  const LIMIT = 200;
+  return text3.length <= LIMIT ? text3 : `${text3.slice(0, LIMIT)}\u2026 (${text3.length} characters)`;
+}
+async function confirmOutsideWrites(options) {
+  if (options.yes && options.global) return true;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    const why = options.global ? "no terminal to confirm them" : options.yes ? "--yes does not cover a write outside the project without --global" : "no terminal to confirm them and no --global";
+    console.log(`  ${icon("warn")} Skipped the writes outside this project: ${why}. Nothing outside the project was written \u2014 re-run with \`wairon doctor --fix --yes --global\` to apply them.`);
+    return false;
+  }
+  const { confirmed } = await import_inquirer5.default.prompt([
+    { type: "confirm", name: "confirmed", message: "Apply the writes outside this project listed above?", default: false }
+  ]);
+  if (!confirmed) console.log(`  ${icon("warn")} Skipped the writes outside this project. Nothing outside the project was written.`);
+  return confirmed;
 }
 function reportOnly(options) {
   if (options.fix) {
@@ -44571,7 +44788,8 @@ function printChainingPlan(migration) {
 }
 var projectLabel2 = (project2) => project2 === "" ? "(top root)" : project2;
 function printProjectMigration(p) {
-  console.log(`  ${import_chalk12.default.bold(projectLabel2(p.project))} ${import_chalk12.default.gray(p.directory)}`);
+  const above = isOutsideRoot(getProjectRoot(), p.directory) ? import_chalk12.default.yellow(" (outside this project's root \u2014 the family above it)") : "";
+  console.log(`  ${import_chalk12.default.bold(projectLabel2(p.project))} ${import_chalk12.default.gray(p.directory)}${above}`);
   if (p.idToWrite) console.log(`    id: declare "${p.idToWrite}"`);
   if (p.createsSystem) console.log("    L0: create a minimal one \u2014 the project exports and has none");
   for (const e of p.exports) console.log(`    L0 entry: ${describeEntry(e)}`);
@@ -44665,13 +44883,13 @@ function writeArtifact(dest, content) {
   fs33.writeFileSync(dest, content, "utf-8");
 }
 function parseSequenceRef(ref) {
-  const sep16 = ref.includes(":") ? ref.lastIndexOf(":") : ref.lastIndexOf(".");
-  if (sep16 <= 0 || sep16 === ref.length - 1) {
+  const sep17 = ref.includes(":") ? ref.lastIndexOf(":") : ref.lastIndexOf(".");
+  if (sep17 <= 0 || sep17 === ref.length - 1) {
     throw new WaironError(
       `Invalid --sequence reference "${ref}". Use <componentId>:<methodName> (e.g. billing-portal:authorize).`
     );
   }
-  return { component: ref.slice(0, sep16), method: ref.slice(sep16 + 1) };
+  return { component: ref.slice(0, sep17), method: ref.slice(sep17 + 1) };
 }
 async function runDiagram(rawOptions = {}) {
   assertProjectInitialized();
@@ -45074,7 +45292,7 @@ async function installPack(source, yes) {
       const update = await confirmFloatingUpdate(extracted.dir, yes);
       if (update === "declined") return;
       const installed = installPackFromDirectory(extracted.dir, source);
-      reportInstalled(installed, source, update, yes);
+      reportInstalled2(installed, source, update, yes);
     } catch (e) {
       logger.error(e instanceof Error ? e.message : String(e));
       process.exitCode = 1;
@@ -45112,7 +45330,7 @@ async function installPack(source, yes) {
   try {
     const update = await confirmFloatingUpdate(sourceDir, yes);
     if (update === "declined") return;
-    reportInstalled(installPackFromDirectory(sourceDir, origin), origin, update, yes);
+    reportInstalled2(installPackFromDirectory(sourceDir, origin), origin, update, yes);
   } catch (e) {
     logger.error(e instanceof Error ? e.message : String(e));
     process.exitCode = 1;
@@ -45141,7 +45359,7 @@ async function confirmFloatingUpdate(sourceDir, yes) {
   logger.info("Nothing was installed.");
   return "declined";
 }
-function reportInstalled(installed, origin, movedFloating = false, yes) {
+function reportInstalled2(installed, origin, movedFloating = false, yes) {
   logger.success(`Installed ${installed.name} v${installed.version} into the pack store.`);
   console.log(`  ${import_chalk16.default.dim(installed.path)}`);
   console.log(`  ${import_chalk16.default.dim(installed.digest)}`);
@@ -61483,8 +61701,9 @@ program.command("init").description("Initialize wairon and bootstrap the SDD Spe
     await addPack(source, false, opts.yes);
   }
 });
-program.command("generate").description("Generate agent output files from the spec tree").option("--target <type>", "limit to a specific target (claude|gemini|custom)").option("--domain <id>", "limit to agents in a single domain").option("--domains <ids>", "limit to a comma-separated list of domain ids").option("--root", "only generate root-level agents").option("--family", "also generate each member's own layer in its own root (generate never cascades otherwise)").option("--no-recurse", "accepted for one release: generating only this project's layer is now the default").option("--no-prune", "do not remove wairon-managed agent files that are no longer in the topology").option("--dry-run", "preview what would be generated without writing files").action(async (opts) => {
+program.command("generate").description("Generate agent output files from the spec tree").option("--target <type>", "limit to a specific target (claude|gemini|custom)").option("--domain <id>", "limit to agents in a single domain").option("--domains <ids>", "limit to a comma-separated list of domain ids").option("--root", "only generate root-level agents").option("--family", "also generate each member's own layer in its own root (generate never cascades otherwise)").option("--no-recurse", "accepted for one release: generating only this project's layer is now the default").option("--no-prune", "do not remove wairon-managed agent files that are no longer in the topology").option("--dry-run", "preview what would be generated without writing files").option("--global", "also write (and prune) a target whose output directory resolves outside the project root, backing up each file replaced there").action(async (opts) => {
   await runGenerate({
+    global: opts.global === true,
     target: opts.target,
     domain: opts.domain,
     domains: opts.domains,
@@ -61611,8 +61830,8 @@ program.command("validate").description("Validate the project configuration and
 program.command("status").description("Show a hierarchical completeness graph of the SDD Spec Tree").option("--subsystem <id>", "only show status for the specified subsystem").option("--no-recursive", "do not recursively show status for subprojects").action(async (opts) => {
   await statusCommand(opts);
 });
-program.command("doctor").description("Health check: flags stale generated guides/skills, an unregistered MCP server, spec-tree issues and the chaining migration still pending").option("--fix", "regenerate stale in-project guides/context/skills, register the MCP server, then apply the chaining migration once confirmed").option("--report <section>", "print one section's report and nothing else, writing nothing (chaining | composed-validation); never combines with --fix").option("-y, --yes", "answer the chaining migration's confirmation (for a non-interactive --fix)").action(async (opts) => {
-  await runDoctor({ fix: opts.fix, report: opts.report, yes: opts.yes });
+program.command("doctor").description("Health check: flags stale generated guides/skills, an unregistered MCP server, spec-tree issues and the chaining migration still pending").option("--fix", "regenerate stale in-project guides/context/skills, register the MCP server, then apply the chaining migration once confirmed").option("--report <section>", "print one section's report and nothing else, writing nothing (chaining | composed-validation); never combines with --fix").option("-y, --yes", "answer the chaining migration's confirmation (for a non-interactive --fix); a write outside the project root also needs --global").option("--global", "consent to the --fix writes outside the project root (a machine-wide MCP config, the legacy global plugin); with --yes it answers their confirmation, and each replaced file is backed up beside itself").action(async (opts) => {
+  await runDoctor({ fix: opts.fix, report: opts.report, yes: opts.yes, global: opts.global === true });
 });
 async function runRules() {
   await listRules3();