@launchsecure/launch-kit 0.0.39 → 0.0.41

package/dist/server/init-entry.js

@@ -1643,6 +1643,7 @@ var PRESETS = {
 };
 var LAUNCH_KIT_PKG = "@launchsecure/launch-kit";
 var LAUNCH_KIT_PKG_LATEST = `${LAUNCH_KIT_PKG}@latest`;
+var LAUNCH_KIT_NPX_ENV = { npm_config_prefer_online: "true" };
 var LAUNCH_KIT_TOOLS_GUIDE_STATIC_HEAD = `
 Wired in Claude Code (.mcp.json):
   launch-secure   \u2014 LS API: work items, comms, secrets, members, board
@@ -2345,19 +2346,23 @@ function buildLaunchKitMcpEntries(cfg) {
     },
     "launch-chart": {
       command: "npx",
-      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-chart"]
+      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-chart"],
+      env: { ...LAUNCH_KIT_NPX_ENV }
     },
     "launch-deck": {
       command: "npx",
-      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-deck"]
+      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-deck"],
+      env: { ...LAUNCH_KIT_NPX_ENV }
     },
     "launch-orbit": {
       command: "npx",
-      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-orbit", "mcp"]
+      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-orbit", "mcp"],
+      env: { ...LAUNCH_KIT_NPX_ENV }
     },
     "launch-recall": {
       command: "npx",
-      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-recall", "mcp"]
+      args: ["-y", "-p", LAUNCH_KIT_PKG_LATEST, "launch-recall", "mcp"],
+      env: { ...LAUNCH_KIT_NPX_ENV }
     }
   };
 }
@@ -2378,16 +2383,21 @@ function mergeMcpEntry(existing, ours) {
   return merged;
 }
 function pinLaunchKitLatest(servers) {
-  const fixed = [];
+  const fixed = /* @__PURE__ */ new Set();
   for (const [name, entry] of Object.entries(servers)) {
     if (entry.command !== "npx" || !Array.isArray(entry.args)) continue;
     const i = entry.args.indexOf(LAUNCH_KIT_PKG);
     if (i !== -1) {
       entry.args[i] = LAUNCH_KIT_PKG_LATEST;
-      fixed.push(name);
+      fixed.add(name);
+    }
+    const isLaunchKit = entry.args.some((a) => a === LAUNCH_KIT_PKG || a === LAUNCH_KIT_PKG_LATEST);
+    if (isLaunchKit && entry.env?.npm_config_prefer_online === void 0) {
+      entry.env = { ...LAUNCH_KIT_NPX_ENV, ...entry.env ?? {} };
+      fixed.add(name);
     }
   }
-  return fixed;
+  return [...fixed];
 }
 function mergeMcpFile(targetDir, launchKitEntries) {
   const p = path5.join(targetDir, ".mcp.json");

package/dist/server/orbit-entry.js

@@ -1385,7 +1385,7 @@ function rewriteEnvFile(filePath, rewrites) {
   const out = lines.map((line) => {
     const m = LINE_RE.exec(line);
     if (!m) return line;
-    const [, indent, key, sep, rawValue] = m;
+    const [, indent, key, sep2, rawValue] = m;
     if (!(key in rewrites)) return line;
     touched.add(key);
     const { quote, inner } = stripQuotes2(rawValue);
@@ -1396,7 +1396,7 @@ function rewriteEnvFile(filePath, rewrites) {
       return line;
     }
     result.changed.push(key);
-    return `${indent}${key}${sep}${quote}${next2}${quote}`;
+    return `${indent}${key}${sep2}${quote}${next2}${quote}`;
   });
   for (const key of Object.keys(rewrites)) {
     if (!touched.has(key)) result.missing.push(key);
@@ -3060,10 +3060,93 @@ var init_orbit_mcp = __esm({
 });
 
 // src/server/orbit-entry.ts
-var import_node_fs13 = require("node:fs");
-var import_node_path10 = require("node:path");
+var import_node_fs14 = require("node:fs");
+var import_node_path11 = require("node:path");
 init_orchestrator();
 init_logger();
+
+// src/server/prune-npx-cache.ts
+var import_node_fs13 = require("node:fs");
+var import_node_os5 = require("node:os");
+var import_node_path10 = require("node:path");
+var import_node_util = require("node:util");
+var PKG = "@launchsecure/launch-kit";
+var readFileAsync = (0, import_node_util.promisify)(import_node_fs13.readFile);
+var readdirAsync = (0, import_node_util.promisify)(import_node_fs13.readdir);
+var rmAsync = (0, import_node_util.promisify)(import_node_fs13.rm);
+var realpathAsync = (0, import_node_util.promisify)(import_node_fs13.realpath);
+function npxCacheRoot() {
+  const cache = process.env.npm_config_cache;
+  if (cache && cache.trim()) return (0, import_node_path10.join)(cache, "_npx");
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (localAppData) return (0, import_node_path10.join)(localAppData, "npm-cache", "_npx");
+  }
+  return (0, import_node_path10.join)((0, import_node_os5.homedir)(), ".npm", "_npx");
+}
+function ownVersion() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse((0, import_node_fs13.readFileSync)((0, import_node_path10.join)(dir, "package.json"), "utf8"));
+      if (pkg && pkg.name === PKG) return typeof pkg.version === "string" ? pkg.version : null;
+    } catch {
+    }
+    const parent = (0, import_node_path10.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+async function pruneStaleNpxCache() {
+  try {
+    const version = ownVersion();
+    if (!version) return;
+    const root = npxCacheRoot();
+    let hashes;
+    try {
+      hashes = await readdirAsync(root);
+    } catch {
+      return;
+    }
+    const selfPath = await realpathAsync(process.argv[1] || __dirname).catch(() => __dirname);
+    let reaped = 0;
+    for (const hash of hashes) {
+      const dir = (0, import_node_path10.join)(root, hash);
+      if (selfPath === dir || selfPath.startsWith(dir + import_node_path10.sep)) continue;
+      let ver;
+      try {
+        const lkPkg = JSON.parse(
+          await readFileAsync((0, import_node_path10.join)(dir, "node_modules", PKG, "package.json"), "utf8")
+        );
+        ver = lkPkg.version;
+      } catch {
+        continue;
+      }
+      if (ver === version) continue;
+      try {
+        const top = JSON.parse(await readFileAsync((0, import_node_path10.join)(dir, "package.json"), "utf8"));
+        const spec = top?.dependencies?.[PKG];
+        if (typeof spec === "string" && spec.startsWith("file:")) continue;
+      } catch {
+      }
+      try {
+        await rmAsync(dir, { recursive: true, force: true });
+        reaped++;
+      } catch {
+      }
+    }
+    if (reaped > 0) {
+      process.stderr.write(
+        `[launch-kit] npx-cache: reaped ${reaped} stale copy(ies), kept v${version}
+`
+      );
+    }
+  } catch {
+  }
+}
+
+// src/server/orbit-entry.ts
 function parseFlags(argv) {
   const positional = [];
   const flags = { emitCd: false, noBackup: false, skipGates: [], deep: false, all: false, json: false, force: false };
@@ -3099,6 +3182,7 @@ function parseFlags(argv) {
   return { positional, flags };
 }
 async function main() {
+  void pruneStaleNpxCache();
   const argv = process.argv.slice(2);
   const subcommand = argv[0];
   if (!subcommand || subcommand === "mcp") {
@@ -3328,8 +3412,8 @@ function formatRollup(reports) {
   return out.join("\n") + "\n";
 }
 function runInit(projectRoot) {
-  const path = (0, import_node_path10.join)(projectRoot, "orbit.json");
-  if ((0, import_node_fs13.existsSync)(path)) {
+  const path = (0, import_node_path11.join)(projectRoot, "orbit.json");
+  if ((0, import_node_fs14.existsSync)(path)) {
     process.stderr.write(`[launch-orbit] orbit.json already exists at ${path}
 `);
     process.exit(1);
@@ -3384,7 +3468,7 @@ function runInit(projectRoot) {
       full: { resources: ["db", "ports"] }
     }
   };
-  (0, import_node_fs13.writeFileSync)(path, JSON.stringify(starter, null, 2) + "\n", "utf-8");
+  (0, import_node_fs14.writeFileSync)(path, JSON.stringify(starter, null, 2) + "\n", "utf-8");
   process.stdout.write(`\u2713 wrote ${path}
 `);
 }

package/dist/server/recall-entry.js

@@ -284,14 +284,14 @@ function pidFilePath(recallDir) {
 function existingWatcherPid() {
   const { recallDir } = resolveRecallPaths();
   const pf = pidFilePath(recallDir);
-  if (!(0, import_node_fs.existsSync)(pf)) return null;
-  const pid = Number((0, import_node_fs.readFileSync)(pf, "utf-8").trim());
+  if (!(0, import_node_fs2.existsSync)(pf)) return null;
+  const pid = Number((0, import_node_fs2.readFileSync)(pf, "utf-8").trim());
   if (!Number.isFinite(pid) || pid <= 0) return null;
   return isPidAlive(pid) ? pid : null;
 }
 function ensureWatcher() {
   const { gitDir, workTree } = resolveRecallPaths();
-  if (!(0, import_node_fs.existsSync)(gitDir)) {
+  if (!(0, import_node_fs2.existsSync)(gitDir)) {
     process.stderr.write(
       `[launch-recall mcp] shadow repo missing at ${gitDir} \u2014 run \`launch-recall init\` first. MCP tools will still serve read-only queries, but nothing will be captured.
 `
@@ -358,7 +358,7 @@ async function handleTool(name, args) {
 function doctorTool() {
   const { gitDir, recallDir } = resolveRecallPaths();
   const checks = [];
-  const shadowOk = (0, import_node_fs.existsSync)(gitDir);
+  const shadowOk = (0, import_node_fs2.existsSync)(gitDir);
   checks.push({
     name: "shadow_repo",
     ok: shadowOk,
@@ -391,7 +391,7 @@ function doctorTool() {
 }
 function reportTool() {
   const { gitDir, recallDir, workTree } = resolveRecallPaths();
-  if (!(0, import_node_fs.existsSync)(gitDir)) return { error: "shadow repo not initialised" };
+  if (!(0, import_node_fs2.existsSync)(gitDir)) return { error: "shadow repo not initialised" };
   let totalSnapshots = 0;
   try {
     const out = (0, import_node_child_process2.execFileSync)("git", [`--git-dir=${gitDir}`, "rev-list", "--count", "HEAD"], {
@@ -425,9 +425,9 @@ function reportTool() {
   }
   let config = null;
   const cfgPath = `${workTree}/.launch-recall.json`;
-  if ((0, import_node_fs.existsSync)(cfgPath)) {
+  if ((0, import_node_fs2.existsSync)(cfgPath)) {
     try {
-      config = JSON.parse((0, import_node_fs.readFileSync)(cfgPath, "utf-8"));
+      config = JSON.parse((0, import_node_fs2.readFileSync)(cfgPath, "utf-8"));
     } catch {
     }
   }
@@ -435,7 +435,7 @@ function reportTool() {
 }
 function historyTool(path7, limit) {
   const { gitDir, workTree } = resolveRecallPaths();
-  if (!(0, import_node_fs.existsSync)(gitDir)) return { error: "shadow repo not initialised", path: path7, snapshots: [] };
+  if (!(0, import_node_fs2.existsSync)(gitDir)) return { error: "shadow repo not initialised", path: path7, snapshots: [] };
   const rel = path7.startsWith("/") ? path7.replace(`${workTree}/`, "").replace(/^\/+/, "") : path7;
   const snapshots = [];
   try {
@@ -456,7 +456,7 @@ function statusTool() {
   const { gitDir, workTree } = resolveRecallPaths();
   const pid = existingWatcherPid();
   let lastSnapshotAt = null;
-  if ((0, import_node_fs.existsSync)(gitDir)) {
+  if ((0, import_node_fs2.existsSync)(gitDir)) {
     try {
       lastSnapshotAt = (0, import_node_child_process2.execFileSync)("git", [`--git-dir=${gitDir}`, "log", "-1", "--format=%aI"], {
         encoding: "utf-8",
@@ -551,14 +551,14 @@ function startRecallMcpServer() {
     process.stderr.write("[launch-recall mcp] stdin closed, exiting\n");
     teardown();
   });
-  void import_node_fs.statSync;
+  void import_node_fs2.statSync;
 }
-var import_node_child_process2, import_node_fs, SERVER_INFO, TOOLS, childWatcher;
+var import_node_child_process2, import_node_fs2, SERVER_INFO, TOOLS, childWatcher;
 var init_recall_mcp = __esm({
   "src/server/recall-mcp.ts"() {
     "use strict";
     import_node_child_process2 = require("node:child_process");
-    import_node_fs = require("node:fs");
+    import_node_fs2 = require("node:fs");
     init_paths();
     SERVER_INFO = { name: "launch-recall", version: "0.0.1" };
     TOOLS = [
@@ -1355,6 +1355,87 @@ var init_uninstall = __esm({
   }
 });
 
+// src/server/prune-npx-cache.ts
+var import_node_fs = require("node:fs");
+var import_node_os = require("node:os");
+var import_node_path = require("node:path");
+var import_node_util = require("node:util");
+var PKG = "@launchsecure/launch-kit";
+var readFileAsync = (0, import_node_util.promisify)(import_node_fs.readFile);
+var readdirAsync = (0, import_node_util.promisify)(import_node_fs.readdir);
+var rmAsync = (0, import_node_util.promisify)(import_node_fs.rm);
+var realpathAsync = (0, import_node_util.promisify)(import_node_fs.realpath);
+function npxCacheRoot() {
+  const cache = process.env.npm_config_cache;
+  if (cache && cache.trim()) return (0, import_node_path.join)(cache, "_npx");
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (localAppData) return (0, import_node_path.join)(localAppData, "npm-cache", "_npx");
+  }
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".npm", "_npx");
+}
+function ownVersion() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse((0, import_node_fs.readFileSync)((0, import_node_path.join)(dir, "package.json"), "utf8"));
+      if (pkg && pkg.name === PKG) return typeof pkg.version === "string" ? pkg.version : null;
+    } catch {
+    }
+    const parent = (0, import_node_path.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+async function pruneStaleNpxCache() {
+  try {
+    const version = ownVersion();
+    if (!version) return;
+    const root = npxCacheRoot();
+    let hashes;
+    try {
+      hashes = await readdirAsync(root);
+    } catch {
+      return;
+    }
+    const selfPath = await realpathAsync(process.argv[1] || __dirname).catch(() => __dirname);
+    let reaped = 0;
+    for (const hash of hashes) {
+      const dir = (0, import_node_path.join)(root, hash);
+      if (selfPath === dir || selfPath.startsWith(dir + import_node_path.sep)) continue;
+      let ver;
+      try {
+        const lkPkg = JSON.parse(
+          await readFileAsync((0, import_node_path.join)(dir, "node_modules", PKG, "package.json"), "utf8")
+        );
+        ver = lkPkg.version;
+      } catch {
+        continue;
+      }
+      if (ver === version) continue;
+      try {
+        const top = JSON.parse(await readFileAsync((0, import_node_path.join)(dir, "package.json"), "utf8"));
+        const spec = top?.dependencies?.[PKG];
+        if (typeof spec === "string" && spec.startsWith("file:")) continue;
+      } catch {
+      }
+      try {
+        await rmAsync(dir, { recursive: true, force: true });
+        reaped++;
+      } catch {
+      }
+    }
+    if (reaped > 0) {
+      process.stderr.write(
+        `[launch-kit] npx-cache: reaped ${reaped} stale copy(ies), kept v${version}
+`
+      );
+    }
+  } catch {
+  }
+}
+
 // src/server/recall-entry.ts
 function logStderr(msg) {
   process.stderr.write(`[launch-recall] ${msg}
@@ -1383,6 +1464,7 @@ function printUsage() {
   );
 }
 async function main() {
+  void pruneStaleNpxCache();
   const argv = process.argv.slice(2);
   const subcommand = argv[0];
   if (!subcommand || subcommand === "--help" || subcommand === "-h") {

package/dist/server/rover-entry.js

@@ -608,7 +608,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@launchsecure/launch-kit",
-      version: "0.0.39",
+      version: "0.0.41",
       description: "LaunchSecure toolkit \u2014 launch-sequencer (pipeline runner + terminal bridge), launch-radar (feedback webhook receiver), launch-chart (project graph MCP), launch-deck (visual playground MCP), launch-kit-beacon (feedback Web Component), launch-recall (file-watcher backup). launch-pod is the container image these run inside.",
       license: "MIT",
       author: "LaunchSecure - AutomateWithUs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchsecure/launch-kit",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "LaunchSecure toolkit — launch-sequencer (pipeline runner + terminal bridge), launch-radar (feedback webhook receiver), launch-chart (project graph MCP), launch-deck (visual playground MCP), launch-kit-beacon (feedback Web Component), launch-recall (file-watcher backup). launch-pod is the container image these run inside.",
   "license": "MIT",
   "author": "LaunchSecure - AutomateWithUs",

package/scaffolds/ls-marketplace/plugins/kit/skills/comms/SKILL.md

@@ -47,6 +47,38 @@ Examples:
 
 If a search comes back empty, widen *before* concluding it's absent: drop `resource_type`, drop `tag`, try a shorter `q` stem (`"deck"` not `"create deck kit skill"`), try `author` alone. Only after the unfiltered `q`/`author` sweep is empty should you say it isn't there.
 
+## Cross-project paste: the "Copy for Claude" payload
+
+The CapCom UI has a **Copy for Claude** button on the selected thread. It puts a payload on the clipboard that starts with `/kit:comms reply` followed by a fenced ` ```capcom ` block — so when the user pastes it, this skill fires. The whole point is **cross-project**: the block names the project the thread lives in, which is usually NOT the MCP's default project. Parse it; do not fall back to the default project.
+
+The block looks like:
+
+```capcom
+project: duet-pay
+org: automatewithus
+type: discussion
+id: cmc1x9k20003
+author: drew.m.jacobs
+status: OPEN
+url: https://.../communication?comment=cmc1x9k20003
+title: launch-kit init: scaffold .mcp.json with @latest
+---
+<full thread body>
+
+--- replies (2) ---
+[drew.m.jacobs] first reply text...
+[prajyot] second reply text...
+```
+
+How to handle a pasted payload:
+
+1. **Parse the metadata** (everything above the `---` line). `project` → `project_slug`, `org` → `org_slug`. **Pass both on every MCP call** — this is what targets the right project instead of the local default. `id` is the thread's comment id (use as `parent_id` to reply). `type` is the `resource_type`. `title`/`author` help locate it.
+2. **Get current context.** The body + replies are embedded so you can read and draft immediately, but they're a snapshot from when the user clicked. Before drafting a reply, do one `communication_read(project_slug, org_slug, resource_type:<type>, q:<distinctive title words>, author:<author>)` to confirm nothing new landed (there's no read-by-id; `q`+`author`+`project_slug` pins it). If the read surfaces newer replies than the paste, use those.
+3. **Draft, preview, gate.** Draft the reply, paste the full body in the terminal, and wait for explicit "post it" — same write gate as everywhere else (the paste is NOT authorization to post).
+4. **Post** with `communication_write(project_slug, org_slug, parent_id:<id>, body:<reply>)`. Keep `resource_type` off the reply unless threading rules require it — a reply inherits its parent's thread.
+
+If the user pastes the block with no instruction beyond the leading command, default to: read for freshness, summarize the thread, and draft a reply for their review.
+
 ## Default system tags
 
 These ship on every org (from `tags_list`, `isSystem: true`) — you don't need to call `tags_list` to know them, only to get their **IDs** for a write. Numeric tags (e.g. `247`) are auto-created per work-item and are not in this list.
@@ -84,5 +116,6 @@ To attach tags on a write you need their IDs: call `tags_list` once and map name
 
 - **Repo-backed long-form doc?** That's `/kit:brief` — it writes a file and the server syncs the comment; don't hand-post it here.
 - **Daily standup?** That's `/kit:standup` — it has the voice/format conventions and the "since last push" diffing.
-- **Bug/gap in launch-kit itself?** That's `kit_feedback_submit`, not a hand-written comment.
+- **Bug/gap in launch-kit TOOLING?** (launch-chart/deck/orbit/beacon/recall or a kit skill) That's `kit_feedback_submit`, not a hand-written comment.
+- **Bug/feedback about the LaunchSecure PLATFORM itself?** (the LS web app / API / pipeline) That's `ls_feedback_submit` — it routes to the LS project regardless of which project you're in, so an LS bug you hit while working in another project (e.g. DuetPay) lands with the LS team instead of in that project's Comm Hub. It stamps your current org/project into `fields.origin` for context. Pass `severity` (bug/feature/idea/question) to tag it.
 - **Reading is free; writing is gated.** Default to read/search freely; gate every write on an explicit go-ahead.

package/scaffolds/ls-marketplace/plugins/kit/skills/gen-test/SKILL.md

@@ -0,0 +1,126 @@
+---
+description: Generate a runnable Playwright test for a feature by walking launch-chart's context (business-logic) graph. Plans the required snippet chain (requires/produces), scaffolds + fills any missing snippets from the endpoint source, then emits a .spec.ts via generate_spec — auto-filling free-form params with faker, secrets from env, leaving only state-bound values (a real user/org) for you to confirm.
+when_to_use: |
+  Auto-fire when the user wants to CREATE/GENERATE an end-to-end test for a feature or action — "write a test for creating a tag", "generate the e2e for the X flow", "scaffold a playwright test for endpoint Y", "I need a test that does login then Z". The deliverable is a real .spec.ts assembled from the context graph + reusable snippets, not a hand-written one-off. Do NOT auto-fire for: running an existing test (just run playwright), unit tests of a pure function, reading how a flow works (use /kit:analyse), or visual/manual verification (use /verify). Requires launch-chart's `context` layer + a snippets dir; if the project has neither, this skill sets them up as it goes.
+allowed-tools:
+  - mcp__launch-chart__detect_project_stack
+  - mcp__launch-chart__generate_graph
+  - mcp__launch-chart__read_graph
+  - mcp__launch-chart__test_plan
+  - mcp__launch-chart__scaffold_snippet
+  - mcp__launch-chart__generate_spec
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# /kit:gen-test
+
+Assemble a runnable Playwright test for a target action by walking the context graph. The graph is the grammar (what state each action requires/produces), reusable snippets are the vocabulary, and this skill is the loop that turns them into a `.spec.ts`.
+
+Parse `$ARGUMENTS`:
+- **target** (required) — a context action node id (`action:app/api/.../tags/route.ts`), a bare endpoint path, or a plain-English feature ("create a tag"). If a feature phrase, resolve it to a node in step 1. If absent, ask.
+- **--run** — after generating, actually execute the spec with `playwright test`.
+- **--snippets-dir=<dir>** / **--spec-dir=<dir>** — override defaults (`tests/snippets`, `tests/generated`).
+
+## Preflight
+
+1. `mcp__launch-chart__detect_project_stack` — confirm launch-chart is wired AND can actually parse this stack. Read the result and gate in order:
+
+   - **Chart MCP missing** (the call itself fails) → stop. Tell the user to run `npx @launchsecure/launch-kit refresh`.
+   - **Stack unsupported** — the context layer is derived from the **api** graph, which only the TypeScript parser produces. If `available_layers` does **not** include `api`, this skill cannot generate a test for this project. Stop **here**, before resolving any target, and say so plainly — quote `unsupported_hint` if present. Example: a Python/Go/Ruby backend (FastAPI, Django, Flask, Rails, …) has no TS api parser, so no `action:` nodes exist to walk. Do not run `generate_graph` or `read_graph` hoping a node turns up — it won't, and an empty-search miss is a confusing way to report "wrong stack." Output the failure block below and exit.
+   - **Supported but `context` not built** — `available_layers` includes `api` but not `context` → run `mcp__launch-chart__generate_graph` once (it builds `context.json` from the api graph), then continue.
+   - **Ready** — `context` is in `available_layers` → continue to step 1.
+
+   Unsupported-stack failure output (terse, no markdown table):
+
+   ```
+   gen-test: cannot generate — stack unsupported
+     launch-chart's context parser only builds from a TypeScript api layer.
+     this project: <unsupported_hint>
+     available layers: <available_layers>
+   No action graph to walk, so no .spec.ts can be assembled. Hand-write the Playwright test, or add a TS api surface the chart can parse.
+   ```
+
+## 1. Resolve the target
+
+If `target` isn't already a node id, `mcp__launch-chart__read_graph` with `layer: "context"`, `search: <phrase>` and pick the matching `action:` node. Confirm the node with the user if ambiguous.
+
+## 2. Plan the chain
+
+`mcp__launch-chart__test_plan` with `target: <node>`. Read the result:
+- `steps[]` — the ordered chain (prerequisites first, target last), each bound to a snippet or flagged.
+- `gaps[]` — `no_snippet` (an action with no snippet), `no_producer` (a required state nothing produces), or `cycle`.
+- `runnable` — true when every step has a snippet.
+
+If `runnable: true`, skip to step 4.
+
+## 3. Close the gaps
+
+For each gap, smallest fix first:
+
+- **`no_snippet`** → `mcp__launch-chart__scaffold_snippet` with `target: <action>`. It returns a stub with `requires`/`produces` pre-filled (from the graph) and `params`/`run()` as TODOs. Then **you** complete it — this is the judgment step:
+  1. `Read` the endpoint's route file (and its zod schema) to get the real `params`.
+  2. Write the `run()` body with real Playwright steps. Prefer the **real UI** for the action under test (navigate, fill, click, assert), and the **fast door** (API/`page.request`) for pure setup snippets like login.
+  3. `Write` the finished snippet to the snippets dir.
+- **`no_producer`** → either a prerequisite snippet/producer is genuinely missing (scaffold it, same as above), OR it's a low-confidence derived edge that's a false positive. Check the edge confidence via `read_graph layer:context`; if it's a `guard:notFound` low-confidence requires that doesn't really gate the action, note it and proceed (a curation overlay can reject it later — out of scope here).
+- **`cycle`** → surface it; the snippet graph has a circular dependency that needs a human decision.
+
+Re-run `test_plan` until `runnable: true`.
+
+## 4. Generate the spec
+
+`mcp__launch-chart__generate_spec` with `target: <node>`. Inspect:
+- `missing_fixtures` — **state-bound** params (a real `email`/`password` user, an `orgSlug`, an id) that faker can't invent. Resolve them: `Read` `prisma/seed.ts` (or the project's seed/fixtures) for a seeded user + org; secrets come from env (the spec already emits `process.env.X`).
+- Re-call `generate_spec` with `fixtures: { email, orgSlug, ... }` until `complete: true`.
+
+`Write` the returned `code` to `suggested_path` (default `tests/generated/<target>.spec.ts`).
+
+**faker check (required — the emitted code imports it).** The generated spec `import`s `@faker-js/faker`, so it won't run without it. Check `package.json` (`grep '@faker-js/faker' package.json`); if absent, `npm i -D @faker-js/faker` before continuing. Don't defer this to `--run` — a spec that can't resolve its own import is broken on disk even if the user never runs it here.
+
+## 5. Run (only with `--run`)
+
+**Precheck before invoking Playwright — fail fast with a punch list, don't half-run.** Only when `--run` is set, verify all three; if any fail, stop and print exactly what's missing rather than letting `playwright test` error cryptically:
+
+1. **Playwright installed** — `npx playwright --version` resolves (or `@playwright/test` is in `package.json`). If missing: `npm i -D @playwright/test && npx playwright install`.
+2. **Config covers the spec dir** — a `playwright.config.*` exists and its `testDir`/`testMatch` includes `suggested_path` (default `tests/generated`). If there's no config, or it scopes to a different dir, say so — the run would collect zero tests and falsely "pass."
+3. **Secret env vars set** — every `process.env.X` the spec reads (e.g. the password) is present in the environment. List any unset ones by name; don't invent values.
+
+Punch-list output when a precheck fails (terse, no markdown table):
+
+```
+gen-test --run: blocked, prerequisites missing
+  playwright: <ok | not installed → npm i -D @playwright/test>
+  config:     <ok | tests/generated not in testDir of playwright.config.ts>
+  env:        <ok | unset: TEST_USER_PASSWORD>
+Spec is written at <spec-path>; fix the above and re-run `npx playwright test <spec-path>`.
+```
+
+Only once all three pass:
+
+```
+npx playwright test <spec-path>
+```
+Report pass/fail with the captured output.
+
+## Output
+
+Terse summary:
+
+```
+gen-test for <target>
+  plan: <step1> -> <step2> -> <target>   (runnable: yes)
+  snippets: created <N>, reused <M>
+  fixtures resolved: email, orgSlug   (faker: name,color,icon; secret: password)
+  spec: tests/generated/<x>.spec.ts   (complete: yes)
+  [--run] result: PASSED | FAILED
+```
+
+## Constraints
+
+- **The graph plans, you fill.** `requires`/`produces` ordering comes from the graph (deterministic); the `run()` body and the state-bound fixtures are your judgment from the real source — never guess selectors, read the page/route.
+- **Setup via the fast door, test via the real door.** Login/seed snippets may hit the API; the action under test drives the real UI.
+- **Don't invent state-bound values.** A faked email/orgSlug fails at runtime — resolve those from the seed, leave faker for free-form inputs only.
+- **Idempotent snippets.** A `createTag` that collides on a duplicate name will fail a second run — use faker/unique values for created entities.
+- **Plain-text summary.** No markdown tables in the human-facing output.