wdi-method 0.6.30 → 0.6.32

package/bin/wdi-method.js

@@ -20,13 +20,23 @@ import {
   writeProductIdentity,
 } from "../lib/identity.mjs";
 import {
+  declaredPlatforms,
   detectPlatforms,
   formatPlatformList,
+  getPlatform,
+  hostsYaml,
   isKnownPlatform,
+  isRetiredPlatform,
+  normalizePlatformId,
   normalizePlatformIds,
+  PLATFORMS,
   platformSelectOptions,
+  platformsWithManualOnly,
   platformUsesHook,
   PREFERRED_PLATFORM_IDS,
+  RETIRED_PLATFORMS,
+  retiredPlatformsIn,
+  ruleFiles,
   skillDestinations,
 } from "../lib/platforms.mjs";
 import { opencodeCommandsDir, syncOpencodeCommands } from "../lib/opencode-commands.mjs";
@@ -101,9 +111,36 @@ const GUARD_LINE = `> **${GUARD_MARK}.** \`wdi-method\` unlocked model invocatio
   + "session, a subagent that thought this looked relevant — stop and say so: this engine publishes "
   + "to the tracker and writes code.";
 
-// Every folder a platform reads skills from. One list, because a repo installs the engines wherever
-// `npx skills add` was pointed, and that installer offers symlinks across several of them.
-const SKILL_HOMES = [".claude", ".agents", ".agent", ".cursor", ".codex"];
+// The method's own skills a person MUST type. Each carries `disable-model-invocation: true` (the hosts
+// that honour it hold it there), a guard line at the top of its body (every host reads that), and a
+// line in the AGENTS.md block (every host reads that too).
+const WDI_MANUAL_ONLY = [
+  "wdi-daily-what-to-build",
+  "wdi-daily-autopilot",
+  "wdi-daily-what-to-test",
+  "wdi-prune-or-archive",
+  "wdi-explain-to-me",
+];
+
+/** Every folder in a repo that may hold skills.
+ *
+ * NOT a hand-kept list of hosts. The one this replaced named five folders while the installer
+ * offered forty hosts, so an engine installed for Kiro, Cline, or Trae was reported missing and never
+ * unlocked. Every `.<host>/skills` at the root counts, plus every directory a supported host is
+ * documented to read (`skills/` for OpenClaw, nested ones) — a repo installs the engines wherever
+ * `npx skills add` was pointed, and that installer symlinks across several of them.
+ */
+function skillRoots(target) {
+  const roots = new Set(PLATFORMS.flatMap((p) => p.reads));
+  if (fs.existsSync(target)) {
+    for (const e of fs.readdirSync(target, { withFileTypes: true })) {
+      if (!e.name.startsWith(".") || e.name === ".git") continue;
+      if (!e.isDirectory() && !e.isSymbolicLink()) continue;
+      if (fs.existsSync(path.join(target, e.name, "skills"))) roots.add(`${e.name}/skills`);
+    }
+  }
+  return [...roots];
+}
 
 // BMad skills RETIRED at G5. This array is the single home of that list: `bmad-skill-register.md`
 // carries the same names for a reader, and a test fails when the two disagree.
@@ -169,7 +206,10 @@ function usage() {
   install [dir]             first install (TUI unless --yes)
   update  [dir]             update      (TUI unless --yes)
   verify  [dir]
-  engines [dir] [--fix]     report the six engines, their invocation state, and the BMad G5 ban
+  engines [dir] [--fix] [--copy]
+                            report the six engines, their invocation state, and the BMad G5 ban;
+                            --copy puts the repo's own engine copies where each selected host reads
+  upgrade-check [dir]       re-probe what wdi-upgrade still owes; rewrites upgrade_pending (exit 1 if any)
   promote <live-dir> --rescue   pull a method change back out of a consumer (not the normal flow)
 
   --yes                     non-interactive
@@ -181,6 +221,7 @@ function usage() {
   --doc-filename-language <text>   slug part of document filenames; free text, default English
   --skip-bmad-check
   --skip-engines-check      install without to-spec / to-tickets / implement
+  --copy-engines            engines are in the repo but a selected host cannot read them: copy them there
 
 BMad first, then this package. ${WDI_REPO}
 `);
@@ -214,7 +255,7 @@ function parseArgs(argv) {
     return args;
   }
   const first = rest[0];
-  if (["install", "update", "verify", "promote", "engines"].includes(first)) {
+  if (["install", "update", "verify", "promote", "engines", "upgrade-check"].includes(first)) {
     args.cmd = rest.shift();
   } else if (first.startsWith("-")) {
     args.cmd = "wizard";
@@ -226,15 +267,21 @@ function parseArgs(argv) {
     const t = rest.shift();
     if (t === "--skip-bmad-check") args.skipBmad = true;
     else if (t === "--fix") args.fix = true;
+    else if (t === "--copy" || t === "--copy-engines") args.copyEngines = true;
     else if (t === "--skip-engines-check") args.skipEngines = true;
     else if (t === "--rescue") args.rescue = true;
     else if (t === "--yes" || t === "-y") args.yes = true;
     else if (t === "--agents") {
       const raw = rest.shift();
       if (!raw) die("--agents needs a comma-separated list");
-      args.agents = normalizePlatformIds(raw.split(",").map((s) => s.trim()).filter(Boolean));
-      const unknown = raw.split(",").map((s) => s.trim()).filter(Boolean)
-        .filter((a) => !isKnownPlatform(a));
+      const asked = raw.split(",").map((s) => s.trim()).filter(Boolean);
+      const retired = asked.filter((a) => isRetiredPlatform(a));
+      if (retired.length) {
+        die(retired.map((a) => `${a} is no longer supported — ${RETIRED_PLATFORMS[normalizePlatformId(a)]}`)
+          .join("\n       "));
+      }
+      args.agents = normalizePlatformIds(asked);
+      const unknown = asked.filter((a) => !isKnownPlatform(a));
       if (unknown.length) die(`unknown platform: ${unknown.join(", ")} (run --list-agents)`);
       if (!args.agents.length) die("--agents needs at least one known platform");
     } else if (t === "--product") args.product = rest.shift();
@@ -361,30 +408,73 @@ function requireTarget(dir) {
  */
 function repoSkillFiles(target, names) {
   const out = new Map();
-  for (const home of SKILL_HOMES) {
+  for (const root of skillRoots(target)) {
     for (const name of names) {
-      const file = path.join(target, home, "skills", name, "SKILL.md");
+      const file = path.join(target, root, name, "SKILL.md");
       if (!fs.existsSync(file)) continue;
       let real = file;
       try {
         real = fs.realpathSync(file);
       } catch {}
       if (!out.has(name)) out.set(name, new Map());
-      out.get(name).set(real, file);
+      const seen = out.get(name);
+      if (!seen.has(real)) seen.set(real, []);
+      seen.get(real).push(file);
     }
   }
   return out;
 }
 
-/** The six engines, in the REPO. A user-level plugin is not an answer here — see ENGINE_SKILLS. */
-function enginesReport(target) {
+/** The six engines, in the REPO — and visible to EVERY selected host.
+ *
+ * Present somewhere is not enough. Kiro reads `.kiro/skills` and nothing else, so engines in
+ * `.agents/skills` are invisible to it and `wdi-build` fails there at G5. `missingByHost` names, per
+ * selected host, the engines none of its `reads` directories holds. With no hosts given it falls
+ * back to "anywhere in the repo", which is what the unlock and the lock work on.
+ * A user-level plugin is not an answer here — see ENGINE_SKILLS.
+ */
+function enginesReport(target, agents = []) {
   const files = repoSkillFiles(target, ENGINE_SKILLS);
   const missing = ENGINE_SKILLS.filter((n) => !files.has(n));
-  return { files, missing, present: missing.length === 0 };
+  const missingByHost = new Map();
+  for (const id of normalizePlatformIds(agents)) {
+    const reads = getPlatform(id).reads.map((d) => path.join(target, d) + path.sep);
+    const visible = (name) => [...(files.get(name)?.values() || [])].flat()
+      .some((f) => reads.some((r) => f.startsWith(r)));
+    const lacking = ENGINE_SKILLS.filter((n) => !visible(n));
+    if (lacking.length) missingByHost.set(id, lacking);
+  }
+  const present = agents.length ? missingByHost.size === 0 : missing.length === 0;
+  return { files, missing, missingByHost, present };
+}
+
+function enginesPresent(target, agents = []) {
+  return enginesReport(target, agents).present;
 }
 
-function enginesPresent(target) {
-  return enginesReport(target).present;
+/** Engines that ARE in the repo, copied into the skill folder of each selected host that cannot see
+ * them. The source is the repo's own copy — no network, no third-party installer — which is what
+ * `npx skills add` in "copy" mode would have produced. An existing folder is never overwritten.
+ * Returns the number of engine folders written; engines missing from the repo entirely are left to
+ * `npx skills add`, because there is nothing here to copy from.
+ */
+function copyEnginesToHosts(target, agents) {
+  const report = enginesReport(target, agents);
+  let written = 0;
+  for (const [id, names] of report.missingByHost) {
+    const host = getPlatform(id);
+    for (const name of names) {
+      const copies = report.files.get(name);
+      if (!copies) continue;
+      const source = path.dirname([...copies.keys()].sort()[0]);
+      const dest = path.join(target, ...host.skillDir.split("/"), name);
+      if (fs.existsSync(dest)) continue;
+      copyTree(source, dest);
+      written += 1;
+    }
+    note(`copied engines for ${host.name} → ${host.skillDir}/ (from the repo's own copy)`);
+  }
+  return written;
 }
 
 /** Only ever a WARNING. The plugin's copies are namespaced and still flagged, so they can neither be
@@ -482,7 +572,10 @@ function retireBmadG5(target) {
  * Merged, never replaced: a product's own permissions are its own. Invalid JSON is reported rather
  * than repaired — rewriting a settings file nobody can parse is how a repo loses its allowlist.
  */
-function writeDenyRules(target) {
+function writeDenyRules(target, agents) {
+  // Claude Code's own settings file, for Claude Code only. Writing it for a Kiro-only repo would
+  // create a `.claude/` folder nothing reads.
+  if (!platformsWithManualOnly(agents, "claude").length) return 0;
   const file = path.join(target, ".claude", "settings.json");
   let settings = {};
   if (fs.existsSync(file)) {
@@ -509,6 +602,46 @@ function writeDenyRules(target) {
   return added.length;
 }
 
+/** OpenCode's equivalent: `permission.skill: ask` in `opencode.json`. The model may still reach for
+ * the skill, and OpenCode then asks the person before loading it — a gate the model cannot pass
+ * alone, with the human route left open. `deny` would hide it from the person too.
+ *
+ * Merged, never replaced, under the same rules as `.claude/settings.json`: a value the product
+ * already set for a name is kept, and a file nobody can parse (`opencode.json` may carry comments) is
+ * reported rather than rewritten.
+ */
+function writeOpencodePermissions(target, agents) {
+  if (!platformsWithManualOnly(agents, "opencode").length) return 0;
+  const file = path.join(target, "opencode.json");
+  let cfg = {};
+  if (fs.existsSync(file)) {
+    try {
+      cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      note("opencode.json is not plain JSON — skill permissions NOT written; add them by hand: "
+           + `permission.skill "${WDI_MANUAL_ONLY[0]}": "ask" (and the rest in bmad-skill-register.md)`);
+      return 0;
+    }
+    if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) return 0;
+  }
+  const perm = cfg.permission && typeof cfg.permission === "object" && !Array.isArray(cfg.permission)
+    ? cfg.permission : {};
+  if (typeof perm.skill === "string") {
+    note(`opencode.json sets permission.skill to "${perm.skill}" for every skill — left as the product wrote it`);
+    return 0;
+  }
+  const skill = perm.skill && typeof perm.skill === "object" ? perm.skill : {};
+  const added = [...WDI_MANUAL_ONLY, ...BMAD_RETIRED_G5].filter((n) => !(n in skill));
+  if (!added.length) return 0;
+  for (const n of added) skill[n] = "ask";
+  perm.skill = skill;
+  cfg.permission = perm;
+  if (!cfg.$schema) cfg = { $schema: "https://opencode.ai/config.json", ...cfg };
+  fs.writeFileSync(file, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
+  note(`opencode.json: ${added.length} manual-only skill${added.length === 1 ? "" : "s"} set to "ask"`);
+  return added.length;
+}
+
 /** A trace of what the engines were when the method last looked — not a lockfile.
  *
  * `npx skills add` writes its own `skills-lock.json` with a folder hash per skill, and that hash
@@ -564,18 +697,37 @@ function bmadMissingMessage() {
 //
 // So it blocks, and `--skip-engines-check` is the escape, exactly as `--skip-bmad-check` is for BMad. The
 // escape matters: CI installs into a bare checkout, and a repo that will never reach G5 is a real case.
-function enginesMissingMessage(missing) {
-  const names = (missing && missing.length ? missing : ENGINE_SKILLS).join(" · ");
+function enginesMissingMessage(report) {
+  const missing = report?.missing?.length ? report.missing
+    : report?.missingByHost?.size ? [] : ENGINE_SKILLS;
+  const byHost = report?.missingByHost?.size ? [...report.missingByHost] : [];
+  const head = [];
+  if (missing.length) {
+    head.push(`The engines are not in this repo. Missing: ${missing.join(" · ")}`, "",
+      `  ${ENGINES_INSTALL_ANY}`);
+  }
+  if (byHost.length) {
+    if (head.length) head.push("");
+    head.push("Not where every selected host can read them — install for each host named here:", "");
+    for (const [id, names] of byHost) {
+      const p = getPlatform(id);
+      head.push(`  ${p.name} reads ${p.reads.join(", ")} — cannot see ${names.join(" · ")}`,
+        `    ${ENGINES_INSTALL_ANY} --agent ${p.skillsCli}   (lands them where ${p.name} reads)`);
+    }
+    head.push("",
+      "Or, without the network — the engines are already in this repo, just not where those hosts read:",
+      "  npx wdi-method engines --copy        (or add --copy-engines to install / update)",
+      "Or leave those hosts out if this repo does not use them:  --agents <the hosts you use>");
+  }
   return [
-    `The engines are not in this repo. Missing: ${names}`,
+    ...head,
     "",
     "They MUST be installed INTO the repo, not as a user-level plugin — the method strips",
     "`disable-model-invocation` from its own copies so `wdi-build` and `wdi-autopilot` can drive",
     "them, and a plugin's files are not the repo's to edit.",
     "",
-    `  ${ENGINES_INSTALL_ANY}`,
-    "",
-    `Take all six: ${ENGINE_SKILLS.join(" · ")}. Choose "copy" or "symlink" — either is read.`,
+    `Take all six: ${ENGINE_SKILLS.join(" · ")}. Choose "copy" or "symlink" — either is read; on Windows`,
+    "without Developer Mode a symlink fails and the installer falls back to copy, which is fine.",
     "",
     "You do NOT need to run the setup skill after this — the installer seeds docs/agents/ already",
     `answered for this method. Run ${ENGINES_SETUP} only to change tracker.`,
@@ -1266,9 +1418,47 @@ function seedEmptyLayers(target, { first }) {
   }
 }
 
-function writeStamp(target) {
+// What `wdi-upgrade` still owes, written where it is committed. The summary line alone was the only
+// record, so a repo whose owner missed that one screen could not find out again — and `wdi-help` can
+// only route to `wdi-upgrade` from something it can read. Absent when nothing is pending: an empty
+// list would read as a question nobody has to answer.
+const PENDING_HEADER = "# What wdi-upgrade still has to move. Re-probed by `npx wdi-method upgrade-check`; absent = nothing.";
+
+function pendingBlock(items) {
+  if (!items.length) return "";
+  return `${PENDING_HEADER}\nupgrade_pending:\n${items.map((i) => `  - ${JSON.stringify(i)}\n`).join("")}`;
+}
+
+// Re-probe and rewrite ONLY the pending block, leaving the rest of the stamp as `update` wrote it.
+// This is how `wdi-upgrade` closes: the field disappears when the probes come back clean.
+function upgradeCheck(target) {
+  const file = path.join(target, ".control", "wdi-method.yaml");
+  if (!fs.existsSync(file)) die("no .control/wdi-method.yaml — the method is not installed here");
+  const items = pendingUpgrades(target);
+  let text = fs.readFileSync(file, "utf8")
+    .replace(/^# What wdi-upgrade still has to move\..*\r?\n/m, "")
+    .replace(/^upgrade_pending:\r?\n(?:[ \t]+- .*\r?\n)*/m, "");
+  const block = pendingBlock(items);
+  if (block) {
+    text = /^installed_at:/m.test(text)
+      ? text.replace(/^installed_at:/m, `${block}installed_at:`)
+      : `${text.replace(/\s*$/, "\n")}${block}`;
+  }
+  fs.writeFileSync(file, text, "utf8");
+  console.log("");
+  if (!items.length) {
+    ok("nothing pending — wdi-upgrade owes nothing here");
+    return 0;
+  }
+  console.log(`  upgrade   ${items.length} item${items.length === 1 ? "" : "s"} still in the OLD shape — run the wdi-upgrade skill`);
+  for (const item of items) console.log(`    ${DIM}·${RESET} ${item}`);
+  return 1;
+}
+
+function writeStamp(target, agents) {
   const control = path.join(target, ".control");
   if (!fs.existsSync(control)) return;
+  const hosts = normalizePlatformIds(agents && agents.length ? agents : declaredPlatforms(target, fs));
   const eng = enginesReport(target);
   const fp = engineFingerprints(target);
   const names = Object.keys(fp);
@@ -1276,6 +1466,12 @@ function writeStamp(target) {
     "# Written by wdi-method install/update. A trace, not a lockfile.",
     `wdi_method: ${PKG.version}`,
     `bmad_method: ${readBmadVersion(target) || '""'}`,
+    "# The hosts this repo was installed for. `update` reuses this list; the skills and validate.py",
+    "# read `hosts:` to learn where each host reads skills, how a person types one, and whether the",
+    "# host has its own scheduler.",
+    "platforms:",
+    ...hosts.map((id) => `  - ${id}`),
+    hostsYaml(hosts),
   ];
   if (names.length) {
     const blocked = engineInvocationState(target).blocked;
@@ -1293,6 +1489,8 @@ function writeStamp(target) {
     lines.push("engines:");
     lines.push("  source: none   # none in this repo — G5 cannot run until they are installed");
   }
+  const pending = pendingBlock(pendingUpgrades(target));
+  if (pending) lines.push(pending.trimEnd());
   lines.push(`installed_at: ${today()}`);
   lines.push("");
   const stamp = lines.join("\n");
@@ -1427,17 +1625,17 @@ function pendingUpgrades(target) {
     });
   };
   const items = [];
-  if (has(".control", "registry", "requirements.yaml")) items.push("requirements.yaml → goals.yaml + requirements-<slug>.yaml");
+  if (has(".control", "registry", "requirements.yaml")) items.push("#1 requirements.yaml → goals.yaml + requirements-<slug>.yaml");
   // The file the engines actually read. `/setup-matt-pocock-skills` writes its own answer here — no
   // `specs.yaml`, no predefined path — and `seedAgentDocs` will not overwrite a file the product owns,
   // so without this probe the repo never learns why its tickets scatter.
   if (has("docs", "agents", "issue-tracker.md")
       && !read("docs", "agents", "issue-tracker.md").includes("seeded by `wdi-method`")) {
-    items.push("docs/agents/issue-tracker.md is not the method's answer (npx wdi-method engines --fix)");
+    items.push("#11 docs/agents/issue-tracker.md is not the method's answer (npx wdi-method engines --fix)");
   }
   const strays = specsOutsideScratch(read(".control", "registry", "specs.yaml"));
   if (strays.length) {
-    items.push(`spec_folder outside .scratch/<spec-id>-<slug>/ on ${strays.join(", ")} `
+    items.push(`#12 spec_folder outside .scratch/<spec-id>-<slug>/ on ${strays.join(", ")} `
                + `(the folder moves, then its cites)`);
   }
   // Reported only where it is still WORK. A closed pre-rename wave is read correctly (0.6.7 taught
@@ -1451,46 +1649,109 @@ function pendingUpgrades(target) {
   // that would answer "not mine" and stop.
   const legacyOpen = specsInLegacyShape(read(".control", "registry", "specs.yaml"));
   if (legacyOpen.length) {
-    items.push(`${legacyOpen.join(", ")} still in the W<n>/epics/stories shape and not closed `
+    items.push(`#2 ${legacyOpen.join(", ")} still in the W<n>/epics/stories shape and not closed `
                + `(flattened into tickets, id kept as its retired alias)`);
   }
-  if (/^## (Executive Summary|Vision|Assumptions|Prerequisites)\s*$/m.test(read(".what", "_product-brief", "brief.md"))) items.push("brief.md in the 14-section shape");
+  if (/^## (Executive Summary|Vision|Assumptions|Prerequisites)\s*$/m.test(read(".what", "_product-brief", "brief.md"))) items.push("#3 brief.md in the 14-section shape");
   // Sections by NAME: the numbers moved between kits (Non-Goals was §7 in one, §5 in the next).
-  if (anyIn(".what/_prd", "prd.md", /^## (\d+\.\s*)?(Document Purpose|Glossary|Non-Goals|Open Questions|Assumptions Index)\b|\*\*Proof of done:\*\*/m)) items.push("a prd.md in the 12-section shape, or with FR blocks");
+  if (anyIn(".what/_prd", "prd.md", /^## (\d+\.\s*)?(Document Purpose|Glossary|Non-Goals|Open Questions|Assumptions Index)\b|\*\*Proof of done:\*\*/m)) items.push("#4 a prd.md in the 12-section shape, or with FR blocks");
   const whatDir = path.join(target, ".what");
   if (fs.existsSync(whatDir)) {
     for (const pc of fs.readdirSync(whatDir)) {
       if (pc.startsWith("_")) continue;
       const srs = read(".what", pc, `SRS-${pc}.md`);
-      if (/^\|\s*UC-\d+\s*\|/m.test(srs)) { items.push("an SRS with a UC Catalogue table (now a pointer)"); break; }
+      if (/^\|\s*UC-\d+\s*\|/m.test(srs)) { items.push("#5 an SRS with a UC Catalogue table (now a pointer)"); break; }
     }
   }
   const howDir = path.join(target, ".how");
   if (fs.existsSync(howDir)) {
     for (const pc of fs.readdirSync(howDir)) {
       if (pc.startsWith("_")) continue;
-      if (/\|\s*Quoted rule\s*\||Quoted verbatim from/.test(read(".how", pc, `SDD-${pc}.md`))) { items.push("an SDD quoting AD-N text (now ids only)"); break; }
+      if (/\|\s*Quoted rule\s*\||Quoted verbatim from/.test(read(".how", pc, `SDD-${pc}.md`))) { items.push("#6 an SDD quoting AD-N text (now ids only)"); break; }
     }
   }
-  if (/\|\s*Container\s*\|\s*Product Components living in it\s*\|/.test(read(".how", "_platform", "c4-l2-containers.md"))) items.push("c4-l2 with a PC x container table (now a pointer)");
-  if (has(".control", "generated", "brief.md") || has(".control", "generated", "blueprint.md")) items.push("human pages still in .control/generated/ (render clears them)");
-  if (has(".what", "_product-brief", "brief.md") && !has(".what-rendered")) items.push("no .what-rendered/ yet (render creates it)");
+  if (/\|\s*Container\s*\|\s*Product Components living in it\s*\|/.test(read(".how", "_platform", "c4-l2-containers.md"))) items.push("#7 c4-l2 with a PC x container table (now a pointer)");
+  if (has(".control", "generated", "brief.md") || has(".control", "generated", "blueprint.md")) items.push("#8 human pages still in .control/generated/ (render clears them)");
+  if (has(".what", "_product-brief", "brief.md") && !has(".what-rendered")) items.push("#9 no .what-rendered/ yet (render creates it)");
   // Skipped: what the validator never reads (kit copies, rendered output, dependencies) and what it
   // treats as a record of the PAST — memlog, decisions, reports, _bmad-output. A stale path in a log
   // is history, not a finding, and repointing it would falsify the record.
   const SKIP = new Set([".git", "node_modules", "target", ".constitution", ".claude", ".agents", ".agent",
     ".what-rendered", ".how-rendered", "dist", "build", "memlog", "decisions", "reports", "meetings", "_bmad-output", ".work"]);
   const OLD_PAGE = /\.control\/generated\/(brief|blueprint|prd-[a-z0-9-]+)\.md/;
+  // At the root, every dot-folder except the corpus layers is a tool's: an agent host's skill copies
+  // (`.kiro/skills/wdi-upgrade` names the OLD paths on purpose, to probe for them), editor state, CI.
+  // Listing hosts by name missed every one outside the first three, and each such repo was told to run
+  // `wdi-upgrade` on every update with nothing to move.
+  const CORPUS_DOT = new Set([".control", ".what", ".how"]);
   const citesOldPage = (dir, depth) => {
     if (depth > 8) return false;
     for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory() && depth === 0 && e.name.startsWith(".") && !CORPUS_DOT.has(e.name)) continue;
       if (e.isDirectory()) { if (!SKIP.has(e.name) && citesOldPage(path.join(dir, e.name), depth + 1)) return true; continue; }
       if (e.name === "answered.md") continue;
       if (e.name.endsWith(".md") && OLD_PAGE.test(fs.readFileSync(path.join(dir, e.name), "utf8"))) return true;
     }
     return false;
   };
-  if (citesOldPage(target, 0)) items.push("a document cites .control/generated/brief|blueprint|prd-*.md (pages moved to the rendered trees)");
+  if (citesOldPage(target, 0)) items.push("#10 a document cites .control/generated/brief|blueprint|prd-*.md (pages moved to the rendered trees)");
+  // Cross-component EXPERIENCE parked in the product's design system. Before `.what/experience.md`
+  // existed it had no home, so a repo put it in the one product-level UX file there was — a promise
+  // in the build layer. The section names are bmad-ux's own, which is where the content comes from.
+  // The names are bmad-ux's own and the product-level template's, in either spelling — a probe narrower
+  // than the template it migrates into reports "nothing owed" while the content is still in the wrong layer.
+  if (/^## (Foundation|Information architecture|Voice and tone|Flow map|Onboarding|Journeys|Shared edge cases|Promises every surface keeps|Cross-component (behaviou?r|journeys?))\b/mi
+        .test(read(".how", "_platform", "design-system.md"))) {
+    items.push("#15 cross-component experience in design-system.md (moves to .what/experience.md)");
+  }
+  // #16 and #18 follow `ux-landed`: nothing about a UX run is owed before a Product Component exists.
+  const components = read(".control", "registry", "components.yaml");
+  const hasPcs = /^product_components:[ \t]*\r?\n[ \t]+-/m.test(components);
+  const LANDED_FROM = /^landed_from:.*(?:\r?\n[ \t]+-.*)*/m;   // provenance, not a citation
+  const UX_RUN = /_bmad-output\/ux\/[A-Za-z0-9_./-]*?(DESIGN|EXPERIENCE|design-system)\.md/;
+  const citesUxRun = (dir, depth) => {
+    if (depth > 8 || !fs.existsSync(dir)) return false;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (citesUxRun(full, depth + 1)) return true; continue; }
+      if (/\.(md|ya?ml)$/.test(e.name) && UX_RUN.test(fs.readFileSync(full, "utf8").replace(LANDED_FROM, ""))) return true;
+    }
+    return false;
+  };
+  if (hasPcs && (citesUxRun(path.join(target, ".what"), 0) || citesUxRun(path.join(target, ".how"), 0))) {
+    items.push("#16 the corpus cites a UX run in _bmad-output/ux/ (repoint at what landed; provenance to landed_from)");
+  }
+  // #17 — a container whose `repo:` sends its code elsewhere but still has a heading here, or a `repo:` on
+  // a container nobody writes. The self-naming case needs the origin remote and is left to `container-built`.
+  const ctrSection = (components.match(/^containers:[^\n]*\n((?:[ \t].*(?:\r?\n|$)|\r?\n)*)/m) || [, ""])[1];
+  const headings = new Set([...(read(".control", "structure-codebase.md").split(/^## Containers\s*$/m)[1] || "")
+    .split(/^## (?!#)/m)[0].matchAll(/^###\s+(.+?)\s*$/gm)].map((m) => m[1]));
+  const repoDebt = ctrSection.split(/^[ \t]*-[ \t]+id:[ \t]*/m).slice(1).some((block) => {
+    const id = block.split(/\r?\n/)[0].trim().replace(/^["']|["']$/g, "");
+    const repo = /^[ \t]+repo:[ \t]*["']?([^"'\r\n]+)/m.exec(block)?.[1].trim();
+    if (!repo) return false;
+    return /^[ \t]+built:[ \t]*false\b/m.test(block) || headings.has(id);
+  });
+  if (repoDebt) {
+    items.push("#17 a container's repo: disagrees with the code map (heading for code kept elsewhere, or repo: on built: false)");
+  }
+  // #18 — landed UX documents written before `landed_from` existed. Without it `ux-landed` cannot tell
+  // which run a landing discharged, so every run in `_bmad-output/ux/` reads as still owed.
+  const uxRoot = path.join(target, "_bmad-output", "ux");
+  const hasRun = fs.existsSync(uxRoot) && fs.readdirSync(uxRoot, { recursive: true })
+    .some((f) => /(^|[\\/])(DESIGN|EXPERIENCE)\.md$/.test(String(f)));
+  const landedDocs = [];
+  for (const [layer, slot, name] of [[".how", "01-ux", "DESIGN.md"], [".what", "04-usecases", "EXPERIENCE.md"]]) {
+    const base = path.join(target, layer);
+    if (!fs.existsSync(base)) continue;
+    for (const pc of fs.readdirSync(base)) {
+      const f = path.join(base, pc, slot, name);
+      if (fs.existsSync(f)) landedDocs.push(f);
+    }
+  }
+  if (hasPcs && hasRun && landedDocs.some((f) => !/^landed_from:/m.test(fs.readFileSync(f, "utf8")))) {
+    items.push("#18 a landed UX document has no landed_from (name the run file(s) it came from)");
+  }
   return items;
 }
 
@@ -1529,34 +1790,20 @@ function upsertAgentFiles(target, platforms, productName) {
   if (!next.endsWith("\n")) next += "\n";
   fs.writeFileSync(agentsFile, next);
 
-  const mirrors = [];
-  if (platformUsesHook(platforms, "cursorrules")) {
-    mirrors.push(path.join(target, ".cursorrules"));
-  }
-  if (platformUsesHook(platforms, "agents-mirror")) {
-    mirrors.push(path.join(target, ".agents", "AGENTS.md"));
-  }
-  for (const mirror of mirrors) {
+  // Every rule file a selected host reads in place of, or beside, AGENTS.md — CLAUDE.md, GEMINI.md,
+  // .junie/guidelines.md, … — carries the same block. A host that never sees the block never sees
+  // the method policy, and on a host with no manual-only gate that policy is the lock.
+  for (const rel of ruleFiles(platforms).slice(1)) {
+    const mirror = path.join(target, ...rel.split("/"));
     fs.mkdirSync(path.dirname(mirror), { recursive: true });
-    if (fs.existsSync(mirror)) {
-      const patched = upsertMethodBlock(fs.readFileSync(mirror, "utf8"), template);
-      fs.writeFileSync(mirror, patched.endsWith("\n") ? patched : `${patched}\n`);
-      note(`method block refreshed in ${posixRel(target, mirror)}`);
-    } else {
+    const current = fs.existsSync(mirror) ? fs.readFileSync(mirror, "utf8") : "";
+    if (!current.trim() || current.trim() === "@AGENTS.md") {
       fs.writeFileSync(mirror, next);
-      note(`created ${posixRel(target, mirror)}`);
-    }
-  }
-
-  if (platformUsesHook(platforms, "claude-md")) {
-    const claude = path.join(target, "CLAUDE.md");
-    if (!fs.existsSync(claude) || fs.readFileSync(claude, "utf8").trim() === "@AGENTS.md") {
-      fs.writeFileSync(claude, next);
-      note("CLAUDE.md synchronized from AGENTS.md");
+      note(current.trim() ? `${rel} synchronized from AGENTS.md` : `created ${rel}`);
     } else {
-      const patched = upsertMethodBlock(fs.readFileSync(claude, "utf8"), template);
-      fs.writeFileSync(claude, patched.endsWith("\n") ? patched : `${patched}\n`);
-      note("method block refreshed in CLAUDE.md");
+      const patched = upsertMethodBlock(current, template);
+      fs.writeFileSync(mirror, patched.endsWith("\n") ? patched : `${patched}\n`);
+      note(`method block refreshed in ${rel}`);
     }
   }
 }
@@ -1612,12 +1859,17 @@ function printSummary(target, agents, { first, was, written, skipped, skills, to
                         `run the ${INIT_SKILL} skill, intent ${DIM}readers${RESET}, ` +
                         `to write it for this repo's stack`);
   }
-  const engReport = enginesReport(target);
+  const engReport = enginesReport(target, agents);
   summaryLine("engines", engReport.present
-    ? `${ENGINE_SKILLS.join(" · ")} — found (in this repo)`
-    : `NOT found: ${engReport.missing.join(" · ")}. G5 (wdi-build) and the Fast Path need them; G1–G4 run without them`);
+    ? `${ENGINE_SKILLS.join(" · ")} — found (in this repo), readable by every selected host`
+    : engReport.missing.length
+      ? `NOT found: ${engReport.missing.join(" · ")}. G5 (wdi-build) and the Fast Path need them; G1–G4 run without them`
+      : `NOT readable by ${[...engReport.missingByHost.keys()].join(", ")}. G5 (wdi-build) and the Fast Path need them; G1–G4 run without them`);
   if (!engReport.present) {
-    summaryLine("", `${DIM}·${RESET} into THIS repo: ${DIM}${ENGINES_INSTALL_ANY}${RESET} — a user-level plugin does not count`);
+    for (const [id, names] of engReport.missingByHost) {
+      summaryLine("", `${DIM}·${RESET} ${id}: ${names.join(" · ")} — ${DIM}${ENGINES_INSTALL_ANY} --agent ${getPlatform(id).skillsCli}${RESET}`);
+    }
+    summaryLine("", `${DIM}·${RESET} into THIS repo — a user-level plugin does not count`);
     summaryLine("", `${DIM}·${RESET} docs/agents/ is already seeded, so ${DIM}${ENGINES_SETUP}${RESET} is not needed · ${ENGINES_REPO}`);
   } else {
     const blocked = engineInvocationState(target).blocked;
@@ -1735,8 +1987,10 @@ function apply(target, agents,
   // wrappers. A one-time fix would hold for about a week.
   enableEngineInvocation(target);
   retireBmadG5(target);
-  writeDenyRules(target);
-  writeStamp(target);
+  writeDenyRules(target, agents);
+  writeOpencodePermissions(target, agents);
+  noteRetiredPlatforms(target);
+  writeStamp(target, agents);
   printSummary(target, agents, { first, was, written, skipped, skills, tomls, opencodeCmds });
   printNextSteps({
     first,
@@ -1745,16 +1999,34 @@ function apply(target, agents,
   });
 }
 
-function enginesCommand(target, { fix }) {
-  const before = enginesReport(target);
+/** A host the repo still names that the method dropped. Said, never acted on: its folder holds
+ * whatever the product put there too, and on update absence is a decision the owner makes. */
+function noteRetiredPlatforms(target) {
+  for (const id of retiredPlatformsIn(target, fs)) {
+    note(`${id} is no longer supported — ${RETIRED_PLATFORMS[id]}. Its wdi-* skill folders were left `
+         + "in place; remove them by hand when you are ready");
+  }
+}
+
+function enginesCommand(target, { fix, copy }) {
+  const agents = declaredPlatforms(target, fs);
+  if (copy) {
+    const n = copyEnginesToHosts(target, agents);
+    if (n) enableEngineInvocation(target);
+    ok(n ? `copied ${n} engine folder${n === 1 ? "" : "s"}` : "nothing to copy — every selected host already reads the engines, or none are in the repo");
+  }
+  const before = enginesReport(target, agents);
   console.log("");
-  console.log(`  engines   ${before.present ? "all present" : `MISSING ${before.missing.join(" · ")}`}`);
+  console.log(`  engines   ${before.present ? "all present" : before.missing.length ? `MISSING ${before.missing.join(" · ")}` : "present, but not where every host reads"}`);
+  for (const [id, names] of before.missingByHost) {
+    console.log(`    ${id.padEnd(17)}cannot read ${names.join(" · ")}  ${DIM}${ENGINES_INSTALL_ANY} --agent ${getPlatform(id).skillsCli}${RESET}`);
+  }
   for (const name of ENGINE_SKILLS) {
     const copies = before.files.get(name);
     if (!copies) continue;
     const flagged = [...copies.keys()].some((f) =>
       /^disable-model-invocation\s*:\s*true/m.test(fs.readFileSync(f, "utf8")));
-    const where = [...copies.values()].map((f) => posixRel(target, f)).join(", ");
+    const where = [...copies.values()].flat().map((f) => posixRel(target, f)).join(", ");
     console.log(`    ${name.padEnd(17)}${flagged ? "flagged — no skill can invoke it" : "invocable"}  ${DIM}${where}${RESET}`);
   }
   const banned = repoSkillFiles(target, BMAD_RETIRED_G5);
@@ -1782,12 +2054,13 @@ function enginesCommand(target, { fix }) {
   repairAgentDocs(target);
   enableEngineInvocation(target);
   retireBmadG5(target);
-  writeDenyRules(target);
-  writeStamp(target);
+  writeDenyRules(target, agents);
+  writeOpencodePermissions(target, agents);
+  writeStamp(target, agents);
   ok("engines aligned");
   if (!before.present) {
     console.log("");
-    console.log(enginesMissingMessage(before.missing));
+    console.log(enginesMissingMessage(before));
   }
 }
 
@@ -2024,7 +2297,7 @@ async function runWizard(pre) {
   // both is told about BMad first rather than sent to install the second thing.
   const engineGate = enginesReport(target);
   if (!engineGate.present && !pre.skipEngines) {
-    p.note(enginesMissingMessage(engineGate.missing), "Engines next");
+    p.note(enginesMissingMessage(engineGate), "Engines next");
     p.outro("Install them into this repo, then run this again: npx wdi-method");
     process.exit(1);
   }
@@ -2101,17 +2374,48 @@ async function runWizard(pre) {
   const detected = pre.agents
     ? normalizePlatformIds(pre.agents)
     : detectPlatforms(target, fs);
-  const selected = cancelIf(
+  let selected = cancelIf(
     await p.autocompleteMultiselect({
       message: "Which tools get the wdi-* skills? (⭐ = recommended)",
       options: platformSelectOptions(detected),
       initialValues: detected,
       required: true,
       maxItems: 8,
-      placeholder: "Type to search…",
+      placeholder: `Type to search all ${PLATFORMS.length} hosts — Space selects, Enter confirms`,
     }),
   );
 
+  // Step 2 again, now that the hosts are known. Present somewhere is not enough: Kiro reads
+  // `.kiro/skills` only, so engines in `.agents/skills` leave it unable to run G5.
+  let hostGate = enginesReport(target, selected);
+  if (!hostGate.present && !pre.skipEngines && !hostGate.missing.length) {
+    // The engines are in the repo, only not where these hosts read. That is fixable right here.
+    const blind = [...hostGate.missingByHost.keys()];
+    const names = blind.map((id) => getPlatform(id).name).join(", ");
+    const choice = cancelIf(await p.select({
+      message: `The engines are in this repo, but ${names} cannot read them. What now?`,
+      options: [
+        { value: "copy", label: `Copy them where ${names} read`, hint: "from this repo's own copy, no network" },
+        { value: "drop", label: `Leave ${names} out of this install`, hint: "if this repo does not use them" },
+        { value: "stop", label: "Stop — I will run npx skills add myself" },
+      ],
+      initialValue: "copy",
+    }));
+    if (choice === "copy") copyEnginesToHosts(target, selected);
+    if (choice === "drop") selected = selected.filter((id) => !blind.includes(id));
+    if (choice === "stop" || !selected.length) {
+      p.note(enginesMissingMessage(hostGate), "Engines for the hosts you picked");
+      p.outro("Install them where each host reads, then run this again: npx wdi-method");
+      process.exit(1);
+    }
+    hostGate = enginesReport(target, selected);
+  }
+  if (!hostGate.present && !pre.skipEngines) {
+    p.note(enginesMissingMessage(hostGate), "Engines for the hosts you picked");
+    p.outro("Install them where each host reads, then run this again: npx wdi-method");
+    process.exit(1);
+  }
+
   p.note(
     [
       "The corpus folder names are fixed — they are not an install option:",
@@ -2119,9 +2423,9 @@ async function runWizard(pre) {
       "",
       "What gets written for the platforms you picked:",
       "  AGENTS.md  (the BEGIN:wdi-method block — always)",
-      platformUsesHook(selected, "claude-md") ? "  CLAUDE.md  (method block mirror)" : "",
-      platformUsesHook(selected, "cursorrules") ? "  .cursorrules  (method block mirror)" : "",
-      platformUsesHook(selected, "agents-mirror") ? "  .agents/AGENTS.md  (method block mirror)" : "",
+      ...ruleFiles(selected).slice(1).map((f) => `  ${f}  (method block mirror)`),
+      platformsWithManualOnly(selected, "claude").length ? "  .claude/settings.json  (deny rules, merged)" : "",
+      platformsWithManualOnly(selected, "opencode").length ? "  opencode.json  (permission.skill: ask, merged)" : "",
       platformUsesHook(selected, "opencode-commands")
         ? `  ${opencodeCommandsDir()}/wdi-*.md  (slash commands → skills)`
         : "",
@@ -2134,12 +2438,12 @@ async function runWizard(pre) {
 
   const okGo = cancelIf(await p.confirm({ message: first ? "Run the install?" : "Run the update?", initialValue: true }));
   if (!okGo) {
-    p.cancel("Dibatalkan.");
+    p.cancel("Cancelled.");
     process.exit(0);
   }
 
   const spinner = p.spinner();
-  spinner.start(first ? "Memasang…" : "Meng-update…");
+  spinner.start(first ? "Installing…" : "Updating…");
   apply(target, selected, {
     docLanguage,
     docFilenameLanguage,
@@ -2148,7 +2452,7 @@ async function runWizard(pre) {
     product: String(product).trim(),
     client: String(client).trim(),
   });
-  spinner.stop(first ? "Terpasang" : "Ter-update");
+  spinner.stop(first ? "Installed" : "Updated");
   p.outro(first ? "Done. Take the after-install steps above." : "Done. Read the method-block diff in AGENTS.md.");
 }
 
@@ -2162,8 +2466,9 @@ function runNonInteractive(args) {
   if (!args.skipBmad && !bmadPresent(target)) {
     die(bmadMissingMessage());
   }
-  if (!args.skipEngines && !enginesPresent(target)) {
-    die(enginesMissingMessage(enginesReport(target).missing));
+  if (args.copyEngines) copyEnginesToHosts(target, agents);
+  if (!args.skipEngines && !enginesPresent(target, agents)) {
+    die(enginesMissingMessage(enginesReport(target, agents)));
   }
   const existing = readIndexIdentity(target);
   const product = args.product || existing.name;
@@ -2181,7 +2486,7 @@ function runNonInteractive(args) {
 
 async function main() {
   const args = parseArgs(process.argv);
-  if (!["wizard", "install", "update", "verify", "promote", "engines"].includes(args.cmd)) {
+  if (!["wizard", "install", "update", "verify", "promote", "engines", "upgrade-check"].includes(args.cmd)) {
     usage();
     process.exit(2);
   }
@@ -2205,7 +2510,11 @@ async function main() {
     return;
   }
   if (args.cmd === "engines") {
-    enginesCommand(requireTarget(args.dir), { fix: Boolean(args.fix) });
+    enginesCommand(requireTarget(args.dir), { fix: Boolean(args.fix), copy: Boolean(args.copyEngines) });
+    return;
+  }
+  if (args.cmd === "upgrade-check") {
+    process.exitCode = upgradeCheck(requireTarget(args.dir));
     return;
   }
   const wantTui = !args.yes && args.cmd !== "verify" && process.stdin.isTTY && process.stdout.isTTY;