@kadj-amoah/showrunner 1.1.4 → 1.1.6

package/dist/cli.js

@@ -1824,7 +1824,7 @@ async function fileExists2(p) {
   }
 }
 function sleep(ms) {
-  return new Promise((resolve27) => setTimeout(resolve27, ms));
+  return new Promise((resolve28) => setTimeout(resolve28, ms));
 }
 
 // src/providers/llm/custom.ts
@@ -5317,14 +5317,14 @@ function printRow(r) {
   else logger.info(line);
 }
 async function checkBinary(name, args) {
-  return new Promise((resolve27) => {
+  return new Promise((resolve28) => {
     const child = spawn3(name, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     child.stdout?.on("data", (chunk) => {
       stdout += chunk.toString("utf8");
     });
     child.on("error", () => {
-      resolve27({
+      resolve28({
         status: "FAIL",
         label: `${name} not on PATH`,
         detail: installHintFor(name)
@@ -5333,9 +5333,9 @@ async function checkBinary(name, args) {
     child.on("exit", (code) => {
       if (code === 0) {
         const firstLine = stdout.split("\n")[0]?.trim() ?? "";
-        resolve27({ status: "PASS", label: `${name} present`, detail: firstLine });
+        resolve28({ status: "PASS", label: `${name} present`, detail: firstLine });
       } else {
-        resolve27({
+        resolve28({
           status: "FAIL",
           label: `${name} exited with code ${code}`,
           detail: installHintFor(name)
@@ -5596,7 +5596,7 @@ async function runCommand2(opts) {
 
 // src/commands/init.ts
 import { mkdir as mkdir11, writeFile as writeFile12, access as access3 } from "fs/promises";
-import { dirname as dirname10, isAbsolute as isAbsolute8, join as join10, resolve as resolve15 } from "path";
+import { dirname as dirname10, isAbsolute as isAbsolute8, join as join11, resolve as resolve15 } from "path";
 
 // src/setup/detect.ts
 import { spawn as spawn4 } from "child_process";
@@ -5621,7 +5621,7 @@ async function detectEnvironment() {
   };
 }
 async function isOnPath(binary) {
-  return new Promise((resolve27) => {
+  return new Promise((resolve28) => {
     const useShell = process.platform === "win32";
     const child = spawn4(binary, ["--version"], {
       stdio: ["ignore", "ignore", "ignore"],
@@ -5631,7 +5631,7 @@ async function isOnPath(binary) {
     const finish = (ok) => {
       if (settled) return;
       settled = true;
-      resolve27(ok);
+      resolve28(ok);
     };
     child.on("error", () => finish(false));
     child.on("exit", (code) => finish(code === 0));
@@ -5696,6 +5696,234 @@ async function probeUrl(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
   }
 }
 
+// src/setup/portScan.ts
+var COMMON_DEV_PORTS = [3e3, 3001, 4321, 5173, 5174, 8e3, 8080];
+async function scanLocalPorts(host = "localhost", ports = COMMON_DEV_PORTS, timeoutMs = 800) {
+  const probes = ports.map(async (port) => {
+    const url = `http://${host}:${port}`;
+    const result = await probeUrl(url, timeoutMs);
+    if (!result.reachable) return null;
+    return {
+      url,
+      port,
+      statusCode: result.statusCode ?? 0,
+      elapsedMs: result.elapsedMs ?? 0
+    };
+  });
+  const all = await Promise.all(probes);
+  return all.filter((x) => x !== null).sort((a, b) => a.port - b.port);
+}
+
+// src/setup/agentDiscover.ts
+import { z as z9 } from "zod";
+
+// src/setup/projectSnapshot.ts
+import { readFile as readFile10, readdir as readdir2, stat as stat11 } from "fs/promises";
+import { join as join10, relative } from "path";
+var FILE_CAP_BYTES = 2048;
+var README_LINE_CAP = 100;
+var CONFIG_FILE_PATTERNS = [
+  /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^next\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^astro\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^svelte\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^vue\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^webpack\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^remix\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^gatsby-config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^rsbuild\.config\.(?:js|mjs|cjs|ts|mts|cts)$/,
+  /^manage\.py$/,
+  /^pyproject\.toml$/,
+  /^Cargo\.toml$/
+];
+async function collectProjectSnapshot(projectDir) {
+  const sections = [];
+  const pkg = await readFileSafe(join10(projectDir, "package.json"));
+  if (pkg) sections.push({ label: "package.json", path: "package.json", body: pkg });
+  for (const candidate of ["README.md", "readme.md", "README.MD"]) {
+    const r = await readFileSafe(join10(projectDir, candidate), { lineCap: README_LINE_CAP });
+    if (r) {
+      sections.push({ label: "README (head)", path: candidate, body: r });
+      break;
+    }
+  }
+  const envEx = await readFileSafe(join10(projectDir, ".env.example"));
+  if (envEx) sections.push({ label: ".env.example", path: ".env.example", body: envEx });
+  else {
+    const envSample = await readFileSafe(join10(projectDir, ".env.sample"));
+    if (envSample) sections.push({ label: ".env.sample", path: ".env.sample", body: envSample });
+  }
+  let topEntries;
+  try {
+    topEntries = await readdir2(projectDir);
+  } catch {
+    topEntries = [];
+  }
+  for (const entry of topEntries) {
+    if (CONFIG_FILE_PATTERNS.some((re) => re.test(entry))) {
+      const body = await readFileSafe(join10(projectDir, entry));
+      if (body) sections.push({ label: entry, path: entry, body });
+    }
+  }
+  return { projectDir, sections };
+}
+function renderSnapshot(snap) {
+  if (snap.sections.length === 0) {
+    return `(empty or non-readable project at ${snap.projectDir})`;
+  }
+  const out = [];
+  for (const s of snap.sections) {
+    out.push(`### ${s.label} \u2014 ${s.path}`);
+    out.push("```");
+    out.push(s.body.trim());
+    out.push("```");
+    out.push("");
+  }
+  return out.join("\n");
+}
+async function readFileSafe(path, options = {}) {
+  try {
+    const s = await stat11(path);
+    if (!s.isFile()) return null;
+  } catch {
+    return null;
+  }
+  let text2;
+  try {
+    text2 = await readFile10(path, "utf8");
+  } catch {
+    return null;
+  }
+  if (options.lineCap !== void 0) {
+    const lines = text2.split("\n");
+    if (lines.length > options.lineCap) {
+      text2 = lines.slice(0, options.lineCap).join("\n") + `
+\u2026[truncated at ${options.lineCap} lines]`;
+    }
+  }
+  const byteCap = options.byteCap ?? FILE_CAP_BYTES;
+  if (Buffer.byteLength(text2, "utf8") > byteCap) {
+    text2 = text2.slice(0, byteCap) + `
+\u2026[truncated at ${byteCap} bytes]`;
+  }
+  return text2;
+}
+
+// src/setup/agentDiscover.ts
+var DevServerProposalSchema = z9.object({
+  command: z9.string().min(1).describe('Executable name, e.g. "npm" or "pnpm".'),
+  args: z9.array(z9.string()).describe('CLI arguments, e.g. ["run", "dev"].'),
+  url: z9.string().url().describe("URL the dev server will listen on once started."),
+  confidence: z9.enum(["high", "medium", "low"]),
+  rationale: z9.string().min(1).describe("One short sentence on why this is the right command.")
+});
+var SYSTEM_PROMPT = [
+  "You are helping the Showrunner CLI identify how to start a project's development server.",
+  "You will be given a project snapshot (package.json, README head, common framework config files, .env.example).",
+  "",
+  "Your job: identify the command + arguments to run the dev server, and the URL it will listen on.",
+  "",
+  "Rules:",
+  '- Use the scripts in package.json as your primary signal. Prefer "dev" > "start" > "serve" when present.',
+  "- For Vite default port = 5173; Next/CRA = 3000; Astro = 4321; Vue CLI = 8080; Django = 8000.",
+  "- If the project explicitly sets a port (via env, config, or CLI flags), use that, NOT the framework default.",
+  '- If the snapshot is too sparse to tell, set confidence to "low" and use your best guess for both command and URL.',
+  '- "confidence" reflects how sure you are. "high" = explicit script + config-confirmed port; "medium" = explicit script, default port; "low" = guessing.',
+  '- "rationale" is one short sentence, plain English. No marketing speak.',
+  "",
+  "Return only the structured output. No prose outside the JSON."
+].join("\n");
+async function discoverDevServer(projectDir, opts = {}) {
+  const snapshot = await collectProjectSnapshot(projectDir);
+  const rendered = renderSnapshot(snapshot);
+  const provider = new AgentBridgeLLMProvider({
+    mode: "spawn",
+    command: opts.command ?? "claude",
+    args: opts.args ?? ["-p", "--output-format", "json"],
+    timeoutMs: opts.timeoutMs ?? 9e4
+  });
+  const userPrompt = [
+    `Project directory: ${projectDir}`,
+    "",
+    "Project snapshot follows:",
+    "",
+    rendered,
+    "",
+    "Identify the dev-server command + args + URL."
+  ].join("\n");
+  return await provider.generateStructured({
+    systemPrompt: SYSTEM_PROMPT,
+    userPrompt,
+    schema: DevServerProposalSchema,
+    schemaName: "DevServerProposal"
+  });
+}
+
+// src/setup/spawnDevServer.ts
+import { spawn as spawn5 } from "child_process";
+async function spawnAndWait(opts) {
+  const waitTimeoutMs = opts.waitTimeoutMs ?? 6e4;
+  const pollIntervalMs = opts.pollIntervalMs ?? 750;
+  const useShell = process.platform === "win32";
+  let child;
+  try {
+    child = spawn5(opts.command, opts.args, {
+      cwd: opts.cwd,
+      detached: true,
+      stdio: "ignore",
+      shell: useShell
+    });
+    child.unref();
+  } catch (err) {
+    return {
+      ok: false,
+      command: opts.command,
+      args: opts.args,
+      url: opts.url,
+      reason: `failed to spawn: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const pid = child.pid;
+  const start = Date.now();
+  let lastReason = "";
+  while (Date.now() - start < waitTimeoutMs) {
+    if (child.exitCode !== null) {
+      return {
+        ok: false,
+        pid,
+        command: opts.command,
+        args: opts.args,
+        url: opts.url,
+        reason: `child process exited with code ${child.exitCode} before the URL came up`
+      };
+    }
+    const probe = await probeUrl(opts.url, pollIntervalMs);
+    if (probe.reachable) {
+      return {
+        ok: true,
+        pid,
+        command: opts.command,
+        args: opts.args,
+        url: opts.url
+      };
+    }
+    lastReason = probe.reason ?? `HTTP ${probe.statusCode ?? "?"}`;
+    await sleep3(pollIntervalMs);
+  }
+  return {
+    ok: false,
+    pid,
+    command: opts.command,
+    args: opts.args,
+    url: opts.url,
+    reason: `timed out after ${waitTimeoutMs}ms waiting for ${opts.url} (last: ${lastReason}). Child still running as pid ${pid}.`
+  };
+}
+function sleep3(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
 // src/setup/wizard.ts
 var SLUG_RE = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/i;
 async function runWizard(env) {
@@ -5798,39 +6026,13 @@ async function runWizard(env) {
     if (key === null) return null;
     if (key.length > 0) collectedKeys["OPENAI_API_KEY"] = key;
   }
-  const url = await ask(
-    text({
-      message: "What URL is your product dev server on?",
-      placeholder: "http://localhost:3000",
-      defaultValue: "http://localhost:3000",
-      validate: (v) => {
-        if (!v) return void 0;
-        try {
-          new URL(v);
-          return void 0;
-        } catch {
-          return "Must be a valid URL (e.g. http://localhost:3000).";
-        }
-      }
-    })
-  );
-  if (url === null) return null;
-  const probeSpinner = spinner();
-  probeSpinner.start(`Probing ${url} ...`);
-  const probe = await probeUrl(url);
-  if (probe.reachable) {
-    probeSpinner.stop(`${url} reachable (HTTP ${probe.statusCode}, ${probe.elapsedMs}ms).`);
-  } else {
-    probeSpinner.stop(`${url} not reachable yet.`);
-    note(
-      `That's fine \u2014 you can start your dev server later. When it's up, run:
-
-  showrunner set-target -c demo.yaml --url ${url}
-
-to re-probe and update the config.`,
-      "Heads up"
-    );
-  }
+  const resolved = await resolveTargetUrl({
+    env,
+    llm,
+    projectDir: process.cwd()
+  });
+  if (resolved === null) return null;
+  const url = resolved.url;
   const proceed = await ask(
     confirm({
       message: `Scaffold ${projectName}/ with these choices?`,
@@ -5881,6 +6083,164 @@ function formatDetection(env) {
   lines.push(`  ELEVENLABS_API_KEY: ${env.envVars.elevenlabs ? "set" : "unset"}`);
   return lines.join("\n");
 }
+async function resolveTargetUrl(input) {
+  const { env, llm, projectDir } = input;
+  const initialUrl = await ask(
+    text({
+      message: "What URL is your product dev server on?",
+      placeholder: "http://localhost:3000",
+      defaultValue: "http://localhost:3000",
+      validate: (v) => {
+        if (!v) return void 0;
+        try {
+          new URL(v);
+          return void 0;
+        } catch {
+          return "Must be a valid URL (e.g. http://localhost:3000).";
+        }
+      }
+    })
+  );
+  if (initialUrl === null) return null;
+  const probeSpin = spinner();
+  probeSpin.start(`Probing ${initialUrl} ...`);
+  const directProbe = await probeUrl(initialUrl);
+  if (directProbe.reachable) {
+    probeSpin.stop(`${initialUrl} reachable (HTTP ${directProbe.statusCode}, ${directProbe.elapsedMs}ms).`);
+    return { url: initialUrl };
+  }
+  probeSpin.stop(`${initialUrl} not reachable yet.`);
+  const scanSpin = spinner();
+  scanSpin.start("Scanning common dev-server ports on localhost...");
+  let scanHits = [];
+  try {
+    scanHits = await scanLocalPorts("localhost");
+  } catch {
+  }
+  if (scanHits.length > 0) {
+    scanSpin.stop(`Found ${scanHits.length} responding port${scanHits.length === 1 ? "" : "s"} on localhost.`);
+    const pick = await ask(
+      select({
+        message: "Use one of the running servers?",
+        options: [
+          ...scanHits.map((h) => ({
+            value: h.url,
+            label: `${h.url}  (HTTP ${h.statusCode})`
+          })),
+          { value: "__keep__", label: `No \u2014 keep what I typed (${initialUrl})` },
+          { value: "__agent__", label: "No \u2014 let the agent figure it out (only useful with agent_bridge + claude)" }
+        ],
+        initialValue: scanHits[0]?.url ?? "__keep__"
+      })
+    );
+    if (pick === null) return null;
+    if (pick !== "__keep__" && pick !== "__agent__") {
+      return { url: pick };
+    }
+    if (pick === "__keep__") {
+      warnFallback(initialUrl);
+      return { url: initialUrl, warnedUnreachable: true };
+    }
+  } else {
+    scanSpin.stop("No common dev ports responding on localhost.");
+  }
+  const agentAvailable = llm === "agent_bridge" && env.claudeCli;
+  if (!agentAvailable) {
+    if (scanHits.length === 0) {
+      warnFallback(initialUrl);
+      return { url: initialUrl, warnedUnreachable: true };
+    }
+    return { url: initialUrl, warnedUnreachable: true };
+  }
+  const useAgent = await ask(
+    confirm({
+      message: "Want me to inspect this directory with the `claude` agent and propose a dev-server command + URL?",
+      initialValue: true
+    })
+  );
+  if (useAgent === null) return null;
+  if (useAgent === false) {
+    warnFallback(initialUrl);
+    return { url: initialUrl, warnedUnreachable: true };
+  }
+  const discoverSpin = spinner();
+  discoverSpin.start("Asking the agent to read your project...");
+  let proposal;
+  try {
+    proposal = await discoverDevServer(projectDir);
+    discoverSpin.stop("Agent returned a proposal.");
+  } catch (err) {
+    discoverSpin.stop("Agent inspection failed.");
+    note(
+      `${err instanceof Error ? err.message : String(err)}
+
+Keeping your typed URL for now. Start your server, then run:
+  showrunner set-target -c demo.yaml --url ${initialUrl}`,
+      "Agent error"
+    );
+    return { url: initialUrl, warnedUnreachable: true };
+  }
+  note(formatProposal(proposal, projectDir), "Agent proposal");
+  const spawnIt = await ask(
+    confirm({
+      message: `Spawn \`${proposal.command} ${proposal.args.join(" ")}\` in ${projectDir} and wait for ${proposal.url}?`,
+      initialValue: proposal.confidence !== "low"
+    })
+  );
+  if (spawnIt === null) return null;
+  if (spawnIt === false) {
+    note(
+      `OK \u2014 start the server yourself, then run:
+  showrunner set-target -c demo.yaml --url ${proposal.url}`,
+      "Skipping spawn"
+    );
+    return { url: proposal.url, warnedUnreachable: true };
+  }
+  const spawnSpin = spinner();
+  spawnSpin.start(`Spawning and waiting for ${proposal.url} (up to 60s)...`);
+  const spawnResult = await spawnAndWait({
+    command: proposal.command,
+    args: proposal.args,
+    url: proposal.url,
+    cwd: projectDir
+  });
+  if (spawnResult.ok) {
+    spawnSpin.stop(`Dev server up at ${proposal.url} (pid ${spawnResult.pid}).`);
+    note(
+      `When you're done, stop it with:  kill ${spawnResult.pid}`,
+      "Server running"
+    );
+    return { url: proposal.url, spawnedPid: spawnResult.pid };
+  }
+  spawnSpin.stop(`Spawn or wait failed.`);
+  note(
+    `${spawnResult.reason ?? "unknown error"}
+
+Keeping ${proposal.url} as the configured target. If the server eventually comes up, no action needed; otherwise run:
+  showrunner set-target -c demo.yaml --url <actual-url>`,
+    "Spawn issue"
+  );
+  return { url: proposal.url, warnedUnreachable: true };
+}
+function warnFallback(url) {
+  note(
+    `That's fine \u2014 you can start your dev server later. When it's up, run:
+
+  showrunner set-target -c demo.yaml --url ${url}
+
+to re-probe and update the config.`,
+    "Heads up"
+  );
+}
+function formatProposal(p, cwd) {
+  return [
+    `command:    ${p.command} ${p.args.join(" ")}`,
+    `cwd:        ${cwd}`,
+    `url:        ${p.url}`,
+    `confidence: ${p.confidence}`,
+    `rationale:  ${p.rationale}`
+  ].join("\n");
+}
 
 // src/commands/init.ts
 var LLM_CHOICES = ["anthropic", "openai", "agent_bridge"];
@@ -5938,7 +6298,7 @@ async function initCommand(opts) {
     };
   }
   const parent = isAbsolute8(resolved.dir) ? resolved.dir : resolve15(process.cwd(), resolved.dir);
-  const projectRoot = join10(parent, resolved.name);
+  const projectRoot = join11(parent, resolved.name);
   if (!resolved.force && await pathExists(projectRoot)) {
     logger.error(
       `Directory already exists: ${projectRoot}. Pass --force to overwrite, or choose a different --name/--dir.`
@@ -5947,28 +6307,28 @@ async function initCommand(opts) {
   }
   await mkdir11(projectRoot, { recursive: true });
   for (const rel of PLACEHOLDER_FILES) {
-    const dest = join10(projectRoot, rel);
+    const dest = join11(projectRoot, rel);
     await mkdir11(dirname10(dest), { recursive: true });
     await writeFile12(dest, "", "utf8");
   }
-  await writeFile12(join10(projectRoot, "demo.yaml"), demoYamlTemplate(resolved), "utf8");
-  await writeFile12(join10(projectRoot, ".env.example"), envExampleTemplate(resolved), "utf8");
-  await writeFile12(join10(projectRoot, ".gitignore"), gitignoreTemplate(), "utf8");
-  await mkdir11(join10(projectRoot, "docs"), { recursive: true });
-  await writeFile12(join10(projectRoot, "docs/PRD.md"), prdStubTemplate(resolved), "utf8");
-  await writeFile12(join10(projectRoot, "scripts/manifest.json"), starterManifest(resolved), "utf8");
-  await writeFile12(join10(projectRoot, "scripts/seed_demo_data.sh"), seedScript(), {
+  await writeFile12(join11(projectRoot, "demo.yaml"), demoYamlTemplate(resolved), "utf8");
+  await writeFile12(join11(projectRoot, ".env.example"), envExampleTemplate(resolved), "utf8");
+  await writeFile12(join11(projectRoot, ".gitignore"), gitignoreTemplate(), "utf8");
+  await mkdir11(join11(projectRoot, "docs"), { recursive: true });
+  await writeFile12(join11(projectRoot, "docs/PRD.md"), prdStubTemplate(resolved), "utf8");
+  await writeFile12(join11(projectRoot, "scripts/manifest.json"), starterManifest(resolved), "utf8");
+  await writeFile12(join11(projectRoot, "scripts/seed_demo_data.sh"), seedScript(), {
     mode: 493
   });
-  await writeFile12(join10(projectRoot, "scripts/reset_demo_data.sh"), resetScript(), {
+  await writeFile12(join11(projectRoot, "scripts/reset_demo_data.sh"), resetScript(), {
     mode: 493
   });
-  await writeFile12(join10(projectRoot, "scripts/teardown.sh"), teardownScript(), {
+  await writeFile12(join11(projectRoot, "scripts/teardown.sh"), teardownScript(), {
     mode: 493
   });
-  await writeFile12(join10(projectRoot, "README.md"), readmeTemplate(resolved), "utf8");
+  await writeFile12(join11(projectRoot, "README.md"), readmeTemplate(resolved), "utf8");
   if (Object.keys(collectedKeys).length > 0) {
-    await writeFile12(join10(projectRoot, ".env"), buildEnvFile(collectedKeys, resolved), "utf8");
+    await writeFile12(join11(projectRoot, ".env"), buildEnvFile(collectedKeys, resolved), "utf8");
   }
   logger.info(`Showrunner project scaffolded at ${projectRoot} (llm=${resolved.llm}, tts=${resolved.tts})`);
   printNextSteps(resolved.name, resolved, collectedKeys);
@@ -6469,22 +6829,22 @@ and \`at_word\` actions degrade to \`at\`).
 }
 
 // src/commands/installBrowser.ts
-import { spawn as spawn5 } from "child_process";
+import { spawn as spawn6 } from "child_process";
 import { access as access4 } from "fs/promises";
 import { fileURLToPath } from "url";
-import { dirname as dirname11, join as join11 } from "path";
+import { dirname as dirname11, join as join12 } from "path";
 var DEFAULT_BROWSER = "chromium";
 async function installBrowserCommand(opts) {
   const browser = opts.browser ?? DEFAULT_BROWSER;
   const cli = await resolvePlaywrightCoreCli();
   logger.info(`installing Playwright ${browser} (via bundled playwright-core, no project required)`);
-  const child = spawn5(process.execPath, [cli, "install", browser], {
+  const child = spawn6(process.execPath, [cli, "install", browser], {
     stdio: "inherit",
     env: process.env
   });
-  const code = await new Promise((resolve27, reject) => {
+  const code = await new Promise((resolve28, reject) => {
     child.on("error", reject);
-    child.on("close", (c) => resolve27(c ?? 0));
+    child.on("close", (c) => resolve28(c ?? 0));
   });
   if (code !== 0) {
     logger.error(`playwright install exited with code ${code}`);
@@ -6497,7 +6857,7 @@ async function resolvePlaywrightCoreCli() {
   let dir = dirname11(here);
   const root = dir.split(/[\\/]/)[0] + "/";
   while (dir && dir !== root) {
-    const candidate = join11(dir, "node_modules", "playwright-core", "cli.js");
+    const candidate = join12(dir, "node_modules", "playwright-core", "cli.js");
     try {
       await access4(candidate);
       return candidate;
@@ -6512,9 +6872,60 @@ async function resolvePlaywrightCoreCli() {
   );
 }
 
-// src/commands/validate.ts
-import { stat as stat11 } from "fs/promises";
+// src/commands/setTarget.ts
+import { readFile as readFile11, writeFile as writeFile13 } from "fs/promises";
 import { isAbsolute as isAbsolute9, resolve as resolve16 } from "path";
+import yaml2 from "js-yaml";
+async function setTargetCommand(opts) {
+  try {
+    new URL(opts.url);
+  } catch {
+    logger.error(`Invalid URL: ${opts.url}`);
+    process.exit(2);
+  }
+  try {
+    await loadConfig(opts.config);
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      logger.error(err.message);
+      process.exit(2);
+    }
+    throw err;
+  }
+  if (!opts.force) {
+    logger.info(`probing ${opts.url} ...`);
+    const probe = await probeUrl(opts.url);
+    if (!probe.reachable) {
+      logger.error(
+        `target ${opts.url} not reachable${probe.reason ? ` (${probe.reason})` : ""}. Start your dev server first, or pass --force to set the URL anyway.`
+      );
+      process.exit(1);
+    }
+    logger.info(`reachable (HTTP ${probe.statusCode}, ${probe.elapsedMs}ms).`);
+  }
+  const absPath = isAbsolute9(opts.config) ? opts.config : resolve16(process.cwd(), opts.config);
+  const rawText = await readFile11(absPath, "utf8");
+  const doc = yaml2.load(rawText);
+  if (!doc || typeof doc !== "object" || !doc["recording"] || typeof doc["recording"] !== "object") {
+    logger.error(
+      `config has no \`recording\` block \u2014 has it been edited by hand into an invalid shape?`
+    );
+    process.exit(2);
+  }
+  doc["recording"]["target_url"] = opts.url;
+  const newText = yaml2.dump(doc, {
+    lineWidth: 100,
+    noRefs: true,
+    sortKeys: false
+  });
+  await writeFile13(absPath, newText, "utf8");
+  logger.info(`updated recording.target_url \u2192 ${opts.url}`);
+  logger.info(`(comments in demo.yaml may have been stripped \u2014 re-add them if needed.)`);
+}
+
+// src/commands/validate.ts
+import { stat as stat12 } from "fs/promises";
+import { isAbsolute as isAbsolute10, resolve as resolve17 } from "path";
 async function validateCommand(opts) {
   try {
     process.loadEnvFile?.();
@@ -6549,9 +6960,9 @@ async function checkReferencedPaths(config, configDir) {
   const warnings = [];
   const check = async (relPath, label) => {
     if (!relPath) return;
-    const abs = isAbsolute9(relPath) ? relPath : resolve16(configDir, relPath);
+    const abs = isAbsolute10(relPath) ? relPath : resolve17(configDir, relPath);
     try {
-      await stat11(abs);
+      await stat12(abs);
     } catch {
       warnings.push(`${label} not found: ${abs}`);
     }
@@ -6579,7 +6990,7 @@ async function checkReferencedPaths(config, configDir) {
 }
 
 // src/commands/printVo.ts
-import { resolve as resolve17 } from "path";
+import { resolve as resolve18 } from "path";
 async function printVoCommand(opts) {
   let loaded;
   try {
@@ -6591,7 +7002,7 @@ async function printVoCommand(opts) {
     }
     throw err;
   }
-  const manifestPath = resolve17(loaded.configDir, "./scripts/manifest.json");
+  const manifestPath = resolve18(loaded.configDir, "./scripts/manifest.json");
   let manifest;
   try {
     manifest = await readManifest(manifestPath);
@@ -6607,8 +7018,8 @@ async function printVoCommand(opts) {
 }
 
 // src/commands/approveVo.ts
-import { rm as rm2, stat as stat12 } from "fs/promises";
-import { resolve as resolve18 } from "path";
+import { rm as rm2, stat as stat13 } from "fs/promises";
+import { resolve as resolve19 } from "path";
 async function approveVoCommand(opts) {
   let loaded;
   try {
@@ -6620,9 +7031,9 @@ async function approveVoCommand(opts) {
     }
     throw err;
   }
-  const manifestPath = resolve18(loaded.configDir, "./scripts/manifest.json");
-  const voScriptPath = resolve18(loaded.configDir, "./scripts/vo_script.txt");
-  const lockPath = resolve18(loaded.configDir, ".showrunner-lock");
+  const manifestPath = resolve19(loaded.configDir, "./scripts/manifest.json");
+  const voScriptPath = resolve19(loaded.configDir, "./scripts/vo_script.txt");
+  const lockPath = resolve19(loaded.configDir, ".showrunner-lock");
   let manifest;
   try {
     manifest = await readManifest(manifestPath);
@@ -6655,7 +7066,7 @@ async function approveVoCommand(opts) {
 }
 async function pathExists2(p) {
   try {
-    await stat12(p);
+    await stat13(p);
     return true;
   } catch {
     return false;
@@ -6663,8 +7074,8 @@ async function pathExists2(p) {
 }
 
 // src/commands/rerunSegment.ts
-import { mkdir as mkdir12, rename as rename3, writeFile as writeFile13 } from "fs/promises";
-import { join as join12, resolve as resolve19 } from "path";
+import { mkdir as mkdir12, rename as rename3, writeFile as writeFile14 } from "fs/promises";
+import { join as join13, resolve as resolve20 } from "path";
 import { chromium as chromium4, firefox as firefox4, webkit as webkit4 } from "playwright-core";
 var RERUN_BUFFER_MS = 500;
 var browserMap4 = { chromium: chromium4, firefox: firefox4, webkit: webkit4 };
@@ -6680,8 +7091,8 @@ async function rerunSegmentCommand(opts) {
     throw err;
   }
   const { config, configDir } = loaded;
-  const manifestPath = resolve19(configDir, "./scripts/manifest.json");
-  const videoDir = resolve19(configDir, config.recording.output_dir);
+  const manifestPath = resolve20(configDir, "./scripts/manifest.json");
+  const videoDir = resolve20(configDir, config.recording.output_dir);
   let manifest;
   try {
     manifest = await readManifest(manifestPath);
@@ -6781,9 +7192,9 @@ async function rerunSegmentCommand(opts) {
       }
     }
     await page.waitForTimeout(config.recording.segment_buffer_ms);
-    const traceDir = resolve19(configDir, config.recording.trace_dir);
+    const traceDir = resolve20(configDir, config.recording.trace_dir);
     await mkdir12(traceDir, { recursive: true });
-    await ctx.tracing.stopChunk({ path: join12(traceDir, `${segment.id}.zip`) });
+    await ctx.tracing.stopChunk({ path: join13(traceDir, `${segment.id}.zip`) });
     const videoHandle = page.video();
     await ctx.close();
     if (!videoHandle) {
@@ -6791,10 +7202,10 @@ async function rerunSegmentCommand(opts) {
       process.exit(1);
     }
     const original = await videoHandle.path();
-    const dest = join12(videoDir, `${segment.id}.webm`);
+    const dest = join13(videoDir, `${segment.id}.webm`);
     await rename3(original, dest);
-    const metadataPath = join12(videoDir, `${segment.id}.rerun.json`);
-    await writeFile13(
+    const metadataPath = join13(videoDir, `${segment.id}.rerun.json`);
+    await writeFile14(
       metadataPath,
       JSON.stringify(
         {
@@ -6822,12 +7233,12 @@ async function rerunSegmentCommand(opts) {
 
 // src/commands/captureAuth.ts
 import { mkdir as mkdir14 } from "fs/promises";
-import { dirname as dirname12, isAbsolute as isAbsolute10, resolve as resolve21 } from "path";
+import { dirname as dirname12, isAbsolute as isAbsolute11, resolve as resolve22 } from "path";
 import { createInterface } from "readline/promises";
 
 // src/recording/headed.ts
 import { mkdir as mkdir13 } from "fs/promises";
-import { resolve as resolve20 } from "path";
+import { resolve as resolve21 } from "path";
 import {
   chromium as chromium5,
   firefox as firefox5,
@@ -6841,7 +7252,7 @@ async function launchHeadedSession(opts) {
     viewport: { width: recording.viewport.width, height: recording.viewport.height }
   };
   if (opts.recordVideo) {
-    const videoDir = resolve20(configDir, recording.output_dir);
+    const videoDir = resolve21(configDir, recording.output_dir);
     await mkdir13(videoDir, { recursive: true });
     contextOptions.recordVideo = {
       dir: videoDir,
@@ -6902,13 +7313,13 @@ async function captureAuthCommand(opts) {
     }
     throw err;
   }
-  const envFile = resolve21(loaded.configDir, ".env");
+  const envFile = resolve22(loaded.configDir, ".env");
   try {
     process.loadEnvFile(envFile);
   } catch {
   }
   const cookiesRel = opts.outputCookies ?? "./auth/session.json";
-  const cookiesPath = isAbsolute10(cookiesRel) ? cookiesRel : resolve21(loaded.configDir, cookiesRel);
+  const cookiesPath = isAbsolute11(cookiesRel) ? cookiesRel : resolve22(loaded.configDir, cookiesRel);
   await mkdir14(dirname12(cookiesPath), { recursive: true });
   logger.info("Launching headed browser for auth capture", {
     target: loaded.config.recording.target_url,
@@ -6949,8 +7360,8 @@ Then re-run \`showrunner run --config <demo.yaml>\`.
 }
 
 // src/commands/trace.ts
-import { readdir as readdir2, stat as stat13 } from "fs/promises";
-import { isAbsolute as isAbsolute11, join as join13, resolve as resolve22 } from "path";
+import { readdir as readdir3, stat as stat14 } from "fs/promises";
+import { isAbsolute as isAbsolute12, join as join14, resolve as resolve23 } from "path";
 async function traceCommand(opts) {
   let loaded;
   try {
@@ -6962,9 +7373,9 @@ async function traceCommand(opts) {
     }
     throw err;
   }
-  const traceDir = resolve22(loaded.configDir, loaded.config.recording.trace_dir);
-  const videoDir = resolve22(loaded.configDir, loaded.config.recording.output_dir);
-  const slicePlanPath = join13(videoDir, "slice_plan.json");
+  const traceDir = resolve23(loaded.configDir, loaded.config.recording.trace_dir);
+  const videoDir = resolve23(loaded.configDir, loaded.config.recording.output_dir);
+  const slicePlanPath = join14(videoDir, "slice_plan.json");
   if (opts.all) {
     let plan;
     try {
@@ -6975,14 +7386,14 @@ async function traceCommand(opts) {
       process.exit(1);
     }
     for (const seg of plan.segments) {
-      const tracePath = seg.trace_path && isAbsolute11(seg.trace_path) ? seg.trace_path : seg.trace_path ? resolve22(loaded.configDir, seg.trace_path) : join13(traceDir, `${seg.id}.zip`);
+      const tracePath = seg.trace_path && isAbsolute12(seg.trace_path) ? seg.trace_path : seg.trace_path ? resolve23(loaded.configDir, seg.trace_path) : join14(traceDir, `${seg.id}.zip`);
       logger.info(`Opening trace for ${seg.id}`, { path: tracePath });
       await openTrace(tracePath);
     }
     return;
   }
   if (opts.segment) {
-    const tracePath = join13(traceDir, `${opts.segment}.zip`);
+    const tracePath = join14(traceDir, `${opts.segment}.zip`);
     if (!await fileExists8(tracePath)) {
       logger.error(`No trace found at ${tracePath}`);
       process.exit(1);
@@ -7023,7 +7434,7 @@ async function openTrace(tracePath) {
 }
 async function listTraces(dir) {
   try {
-    const entries = await readdir2(dir);
+    const entries = await readdir3(dir);
     return entries.filter((e) => e.endsWith(".zip")).sort();
   } catch {
     return [];
@@ -7031,7 +7442,7 @@ async function listTraces(dir) {
 }
 async function fileExists8(path) {
   try {
-    await stat13(path);
+    await stat14(path);
     return true;
   } catch {
     return false;
@@ -7039,8 +7450,8 @@ async function fileExists8(path) {
 }
 
 // src/commands/preview.ts
-import { stat as stat14 } from "fs/promises";
-import { resolve as resolve23 } from "path";
+import { stat as stat15 } from "fs/promises";
+import { resolve as resolve24 } from "path";
 async function previewCommand(opts) {
   let loaded;
   try {
@@ -7052,7 +7463,7 @@ async function previewCommand(opts) {
     }
     throw err;
   }
-  const previewSpec = resolve23(loaded.configDir, "./scripts/playwright_demo.spec.ts");
+  const previewSpec = resolve24(loaded.configDir, "./scripts/playwright_demo.spec.ts");
   if (!await fileExists9(previewSpec)) {
     logger.error(
       `No preview spec at ${previewSpec}. Run \`showrunner run --stages script\` first to generate it.`
@@ -7078,7 +7489,7 @@ async function previewCommand(opts) {
 }
 async function fileExists9(path) {
   try {
-    await stat14(path);
+    await stat15(path);
     return true;
   } catch {
     return false;
@@ -7086,8 +7497,8 @@ async function fileExists9(path) {
 }
 
 // src/commands/understand.ts
-import { mkdir as mkdir15, readFile as readFile10, writeFile as writeFile14 } from "fs/promises";
-import { dirname as dirname13, isAbsolute as isAbsolute12, resolve as resolve24 } from "path";
+import { mkdir as mkdir15, readFile as readFile12, writeFile as writeFile15 } from "fs/promises";
+import { dirname as dirname13, isAbsolute as isAbsolute13, resolve as resolve25 } from "path";
 
 // src/productModel/prompts.ts
 var PRODUCT_MODEL_SYSTEM_PROMPT = `You build product_model.json for Showrunner, an automated product demo recorder.
@@ -7176,6 +7587,71 @@ Regenerate the product_model strictly matching the schema.`
   }
 }
 
+// src/productModel/generateViaAgent.ts
+var DEFAULT_MAX_TOKENS5 = 8e3;
+var AGENT_SYSTEM_PROMPT = [
+  "You are helping Showrunner build a product_model.json for a product demo recording.",
+  "",
+  "You have read-only filesystem tools (Read, Glob, Grep) and can explore the project freely.",
+  "Use them \u2014 do NOT guess from the prompt alone.",
+  "",
+  "What to look for, in order:",
+  "  1. package.json (or pyproject.toml, Cargo.toml, etc.) \u2014 name, description, scripts, deps",
+  "  2. README.md / README.* at the project root \u2014 product description, primary user, features",
+  "  3. docs/PRD.md or similar \u2014 explicit product brief if present",
+  "  4. src/ tree (sample a few files) \u2014 what the product actually DOES, names of routes/pages/components",
+  "  5. .env.example \u2014 hints at integrations and external services",
+  "  6. Any framework config (next.config, vite.config, astro.config, etc.) \u2014 confirms what kind of app this is",
+  "",
+  "When you have enough signal, synthesize a product_model.json matching the requested schema.",
+  "",
+  "Rules:",
+  '  - product_name: short, exact product name as branded. Take this from package.json "name" only if it looks human, else from README.',
+  "  - tagline: one sentence, 8\u201315 words, plain language. Derived from README/PRD, not invented.",
+  `  - primary_user: one short phrase. Inferred from the README's "who is this for" framing if explicit, else from the product's shape.`,
+  "  - core_flows: 2\u20134 user flows. Each has id (kebab-case), name, 3\u20136 imperative steps from the user's POV, optional entry_url. Ground these in the actual routes/pages the codebase exposes.",
+  "  - key_features: 3\u20136 short bullets. No marketing fluff.",
+  "  - demo_recommendation.suggested_flows: ids from core_flows, in demo order.",
+  "  - demo_recommendation.suggested_duration_seconds: 60\u201390 typical.",
+  "  - confidence: 'high' if you found explicit, clear sources; 'medium' if you had to infer; 'low' if the codebase was sparse and you mostly guessed.",
+  "  - source: always 'documents' (this path counts as document-driven, just agentically discovered).",
+  "  - generated_at: ISO-8601 timestamp.",
+  "",
+  "Output exactly the structured JSON. No prose, no commentary, no markdown fence outside the JSON."
+].join("\n");
+async function generateProductModelViaAgent(opts) {
+  const provider = new AgentBridgeLLMProvider({
+    mode: "spawn",
+    command: opts.command ?? "claude",
+    args: opts.args ?? ["-p", "--output-format", "json"],
+    timeoutMs: opts.timeoutMs ?? 18e4,
+    cwd: opts.projectDir
+  });
+  const userPrompt = [
+    `Project directory: ${opts.projectDir}`,
+    "",
+    "Explore this directory with your filesystem tools, then synthesize a product_model.json."
+  ].join("\n");
+  logger.debug("Generating product_model via agent", { projectDir: opts.projectDir });
+  try {
+    return await generateWithRetry(provider, {
+      systemPrompt: AGENT_SYSTEM_PROMPT,
+      userPrompt,
+      schema: productModelSchema,
+      schemaName: "product_model",
+      maxTokens: DEFAULT_MAX_TOKENS5,
+      retryRenderer: (errorText, prevUserPrompt) => `${prevUserPrompt}
+
+Your previous output failed validation with this error:
+${errorText}
+
+Regenerate the product_model strictly matching the schema.`
+    });
+  } catch (err) {
+    throw new ProductModelGenerationError(err instanceof Error ? err.message : String(err));
+  }
+}
+
 // src/productModel/interactive.ts
 import { createInterface as createInterface2 } from "readline";
 var LineReader = class {
@@ -7211,8 +7687,8 @@ var LineReader = class {
     if (this.closed) {
       return Promise.reject(new Error("stdin closed before answer was provided"));
     }
-    return new Promise((resolve27, reject) => {
-      this.waiter = resolve27;
+    return new Promise((resolve28, reject) => {
+      this.waiter = resolve28;
       this.rejecter = reject;
     });
   }
@@ -7264,6 +7740,10 @@ function clamp(n, lo, hi) {
 
 // src/commands/understand.ts
 async function understandCommand(opts) {
+  if (opts.interactive && opts.agent) {
+    logger.error("--interactive and --agent are mutually exclusive. Pick one.");
+    process.exit(2);
+  }
   let configDir = process.cwd();
   let outputRel = opts.output ?? "./product_model.json";
   let sources = [];
@@ -7285,33 +7765,37 @@ async function understandCommand(opts) {
     }
     sources = loaded.config.comprehension.sources.map((s) => ({ path: s.path, type: s.type }));
     llmConfig = loaded.config.llm;
-    const envFile = resolve24(loaded.configDir, ".env");
+    const envFile = resolve25(loaded.configDir, ".env");
     try {
       process.loadEnvFile(envFile);
     } catch {
     }
   }
-  const outputPath = isAbsolute12(outputRel) ? outputRel : resolve24(configDir, outputRel);
+  const outputPath = isAbsolute13(outputRel) ? outputRel : resolve25(configDir, outputRel);
   await mkdir15(dirname13(outputPath), { recursive: true });
   let productModel;
-  const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
   try {
-    if (opts.interactive) {
+    if (opts.agent) {
+      const projectDir = process.cwd();
+      logger.info("Generating product_model via local `claude` agent", { projectDir });
+      productModel = await generateProductModelViaAgent({ projectDir });
+    } else if (opts.interactive) {
       const answers = await runInteractiveQA();
       logger.info("Generating product_model from interactive answers");
+      const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
       productModel = await generateProductModelFromInteractive({ answers, provider });
     } else {
       if (sources.length === 0) {
         logger.error(
-          "No `comprehension.sources` configured in demo.yaml. Add at least one source (prd, readme, codebase, etc.) or re-run with --interactive."
+          "No `comprehension.sources` configured in demo.yaml. Add at least one source (prd, readme, codebase, etc.), re-run with --interactive (Q&A), or re-run with --agent (the local `claude` CLI explores your repo)."
         );
         process.exit(2);
       }
       const docs = [];
       for (const src of sources) {
-        const abs = isAbsolute12(src.path) ? src.path : resolve24(configDir, src.path);
+        const abs = isAbsolute13(src.path) ? src.path : resolve25(configDir, src.path);
         try {
-          const content = await readFile10(abs, "utf8");
+          const content = await readFile12(abs, "utf8");
           docs.push({ path: src.path, type: src.type, content });
         } catch (err) {
           const cause = err instanceof Error ? err.message : String(err);
@@ -7325,6 +7809,7 @@ async function understandCommand(opts) {
       logger.info("Generating product_model from documents", {
         sources: docs.map((d) => d.path)
       });
+      const provider = resolveDefaultLLMProvider({ configDir, llm: llmConfig });
       productModel = await generateProductModelFromDocs({ sources: docs, provider });
     }
   } catch (err) {
@@ -7334,16 +7819,16 @@ async function understandCommand(opts) {
     }
     throw err;
   }
-  await writeFile14(outputPath, JSON.stringify(productModel, null, 2) + "\n", "utf8");
+  await writeFile15(outputPath, JSON.stringify(productModel, null, 2) + "\n", "utf8");
   logger.info("Wrote product_model.json", { path: outputPath });
 }
 
 // src/commands/instrument.ts
-import { mkdir as mkdir16, readdir as readdir3, writeFile as writeFile15 } from "fs/promises";
-import { dirname as dirname14, isAbsolute as isAbsolute13, join as join14, resolve as resolve25, relative as relative2 } from "path";
+import { mkdir as mkdir16, readdir as readdir4, writeFile as writeFile16 } from "fs/promises";
+import { dirname as dirname14, isAbsolute as isAbsolute14, join as join15, resolve as resolve26, relative as relative3 } from "path";
 
 // src/instrument/scan.ts
-import { readFile as readFile11 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 import { parse } from "@babel/parser";
 import _traverse from "@babel/traverse";
 var traverse = _traverse.default ?? _traverse;
@@ -7361,7 +7846,7 @@ var TARGET_TAGS = /* @__PURE__ */ new Set([
   "Form"
 ]);
 async function scanFile(filePath) {
-  const source = await readFile11(filePath, "utf8");
+  const source = await readFile13(filePath, "utf8");
   let ast;
   try {
     ast = parse(source, {
@@ -7420,23 +7905,23 @@ function pickAttr(node, attr) {
 }
 
 // src/instrument/suggest.ts
-import { z as z9 } from "zod";
-var DEFAULT_MAX_TOKENS5 = 8e3;
-var suggestionSchema = z9.object({
-  suggestions: z9.array(
-    z9.object({
-      file: z9.string(),
-      line: z9.number().int().positive(),
-      original: z9.string(),
-      replacement: z9.string(),
-      reasoning: z9.string().default("")
+import { z as z10 } from "zod";
+var DEFAULT_MAX_TOKENS6 = 8e3;
+var suggestionSchema = z10.object({
+  suggestions: z10.array(
+    z10.object({
+      file: z10.string(),
+      line: z10.number().int().positive(),
+      original: z10.string(),
+      replacement: z10.string(),
+      reasoning: z10.string().default("")
     })
   )
 });
 var InstrumentSuggestionError = class extends Error {
   name = "InstrumentSuggestionError";
 };
-var SYSTEM_PROMPT = `You add data-testid attributes to JSX elements so they can be reliably targeted by automated demo tools.
+var SYSTEM_PROMPT2 = `You add data-testid attributes to JSX elements so they can be reliably targeted by automated demo tools.
 
 Rules:
 - For each candidate, propose a stable kebab-case data-testid based on visible text, surrounding context, or the element's role. Examples: "login-submit", "new-article-button", "todo-item-toggle".
@@ -7463,11 +7948,11 @@ For each, return {file, line, original (exact source line), replacement (source
   });
   try {
     const result = await opts.provider.generateStructured({
-      systemPrompt: SYSTEM_PROMPT,
+      systemPrompt: SYSTEM_PROMPT2,
       userPrompt,
       schema: suggestionSchema,
       schemaName: "instrument_suggestions",
-      maxTokens: DEFAULT_MAX_TOKENS5
+      maxTokens: DEFAULT_MAX_TOKENS6
     });
     return result.suggestions;
   } catch (err) {
@@ -7478,8 +7963,8 @@ For each, return {file, line, original (exact source line), replacement (source
 }
 
 // src/instrument/diff.ts
-import { readFile as readFile12 } from "fs/promises";
-import { relative } from "path";
+import { readFile as readFile14 } from "fs/promises";
+import { relative as relative2 } from "path";
 async function buildDiff(suggestions, opts = {}) {
   const byFile = /* @__PURE__ */ new Map();
   for (const s of suggestions) {
@@ -7492,7 +7977,7 @@ async function buildDiff(suggestions, opts = {}) {
   for (const [file, perFile] of byFile) {
     let source;
     try {
-      source = await readFile12(file, "utf8");
+      source = await readFile14(file, "utf8");
     } catch (err) {
       for (const s of perFile) {
         skipped.push({
@@ -7528,7 +8013,7 @@ async function buildDiff(suggestions, opts = {}) {
       );
     }
     if (hunks.length === 0) continue;
-    const displayPath = opts.basePath ? relative(opts.basePath, file).replace(/\\/g, "/") : file;
+    const displayPath = opts.basePath ? relative2(opts.basePath, file).replace(/\\/g, "/") : file;
     fileDiffs.push(`--- a/${displayPath}
 +++ b/${displayPath}
 ${hunks.join("\n")}`);
@@ -7548,7 +8033,7 @@ async function instrumentCommand(opts) {
     }
     throw err;
   }
-  const envFile = resolve25(loaded.configDir, ".env");
+  const envFile = resolve26(loaded.configDir, ".env");
   try {
     process.loadEnvFile(envFile);
   } catch {
@@ -7563,13 +8048,13 @@ async function instrumentCommand(opts) {
   const filesToScan = /* @__PURE__ */ new Set();
   const IGNORED_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "out"]);
   async function walk(root, accept) {
-    const entries = await readdir3(root, { withFileTypes: true });
+    const entries = await readdir4(root, { withFileTypes: true });
     for (const entry of entries) {
-      const abs = join14(root, entry.name);
+      const abs = join15(root, entry.name);
       if (entry.isDirectory()) {
         if (IGNORED_DIRS.has(entry.name)) continue;
         await walk(abs, accept);
-      } else if (entry.isFile() && accept(relative2(root, abs))) {
+      } else if (entry.isFile() && accept(relative3(root, abs))) {
         filesToScan.add(abs);
       }
     }
@@ -7580,7 +8065,7 @@ async function instrumentCommand(opts) {
     await walk(root, isJsxFile);
   } else {
     for (const src of codebaseSources) {
-      const root = isAbsolute13(src.path) ? src.path : resolve25(loaded.configDir, src.path);
+      const root = isAbsolute14(src.path) ? src.path : resolve26(loaded.configDir, src.path);
       await walk(root, isJsxFile);
     }
   }
@@ -7621,9 +8106,9 @@ async function instrumentCommand(opts) {
   for (const s of skipped) {
     logger.warn(`Skipped suggestion at ${s.file}:${s.line} \u2014 ${s.reason}`);
   }
-  const outputPath = isAbsolute13(opts.output) ? opts.output : resolve25(loaded.configDir, opts.output);
+  const outputPath = isAbsolute14(opts.output) ? opts.output : resolve26(loaded.configDir, opts.output);
   await mkdir16(dirname14(outputPath), { recursive: true });
-  await writeFile15(outputPath, patch, "utf8");
+  await writeFile16(outputPath, patch, "utf8");
   logger.info("Wrote instrumentation patch", { path: outputPath, suggestions: suggestions.length });
   process.stdout.write(`
 Apply with:  cd ${loaded.configDir} && git apply ${opts.output}
@@ -7633,8 +8118,8 @@ Apply with:  cd ${loaded.configDir} && git apply ${opts.output}
 
 // src/commands/recordActions.ts
 import { createInterface as createInterface3 } from "readline/promises";
-import { resolve as resolve26 } from "path";
-import { stat as stat15 } from "fs/promises";
+import { resolve as resolve27 } from "path";
+import { stat as stat16 } from "fs/promises";
 
 // src/recording/captureEvents.ts
 async function installCaptureBinding(context, onEvent) {
@@ -7832,12 +8317,12 @@ async function recordActionsCommand(opts) {
     }
     throw err;
   }
-  const envFile = resolve26(loaded.configDir, ".env");
+  const envFile = resolve27(loaded.configDir, ".env");
   try {
     process.loadEnvFile(envFile);
   } catch {
   }
-  const manifestPath = opts.output ? resolve26(loaded.configDir, opts.output) : resolve26(loaded.configDir, "./scripts/manifest.json");
+  const manifestPath = opts.output ? resolve27(loaded.configDir, opts.output) : resolve27(loaded.configDir, "./scripts/manifest.json");
   logger.info("Launching headed browser for action capture", {
     target: loaded.config.recording.target_url
   });
@@ -7948,7 +8433,7 @@ async function mergeIntoManifest(opts) {
 }
 async function fileExists10(path) {
   try {
-    await stat15(path);
+    await stat16(path);
     return true;
   } catch {
     return false;
@@ -7957,7 +8442,7 @@ async function fileExists10(path) {
 
 // src/cli.ts
 var program = new Command();
-program.name("showrunner").description("Automated product demo recording & production tool").version("1.1.4").option("--json", "emit structured JSON logs to stdout").option("--log-level <level>", "log level (debug|info|warn|error)").hook("preAction", (thisCmd) => {
+program.name("showrunner").description("Automated product demo recording & production tool").version("1.1.6").option("--json", "emit structured JSON logs to stdout").option("--log-level <level>", "log level (debug|info|warn|error)").hook("preAction", (thisCmd) => {
   const opts = thisCmd.opts();
   if (opts.json) logger.setJson(true);
   if (opts.logLevel) logger.setLevel(opts.logLevel);
@@ -7990,10 +8475,14 @@ program.command("init").description("Scaffold a new Showrunner project (interact
   "scaffold resolution: low (854x480) | standard (720p) | high (1080p) | extreme (4K)",
   "standard"
 ).action(initCommand);
+program.command("set-target").description("Update demo.yaml's recording.target_url and re-probe it").requiredOption("-c, --config <path>", "path to demo.yaml").requiredOption("--url <url>", "new target URL (e.g. http://localhost:5173)").option("--force", "skip the reachability probe and update the URL anyway", false).action(setTargetCommand);
 program.command("install-browser").description("Install the Playwright browser binary (chromium by default) \u2014 wraps playwright-core install").option("--browser <name>", "browser to install: chromium | firefox | webkit", "chromium").action(installBrowserCommand);
 program.command("doctor").description("Run preflight checks on the current config + environment").requiredOption("-c, --config <path>", "path to demo.yaml").option("--json", "emit results as JSON instead of human-readable rows").action(doctorCommand);
 program.command("validate").description("Validate a demo.yaml config file").requiredOption("-c, --config <path>", "path to demo.yaml").option("--strict", "exit nonzero on any warning (e.g. missing provider env var)").action(validateCommand);
-program.command("understand").description("Build product_model.json from documents or interactive Q&A").option("-c, --config <path>", "path to demo.yaml").option("--interactive", "use interactive Q&A mode").option("--output <path>", "output path for product_model.json").action(understandCommand);
+program.command("understand").description("Build product_model.json from documents, interactive Q&A, or agent-driven repo exploration").option("-c, --config <path>", "path to demo.yaml").option("--interactive", "use interactive Q&A mode (5 prompts, no LLM)").option(
+  "--agent",
+  "delegate to the local `claude` CLI: it explores the current directory with its read tools and synthesizes the product model. Closes the type=codebase gap in demo.yaml sources."
+).option("--output <path>", "output path for product_model.json").action(understandCommand);
 program.command("instrument").description("Suggest data-testid attributes for a codebase").requiredOption("-c, --config <path>", "path to demo.yaml").requiredOption("--output <path>", "unified diff output path").option("--glob <pattern>", "override comprehension.sources with an ad-hoc glob (relative to configDir)").action(instrumentCommand);
 program.command("record-actions").description("Author manifest actions by demonstrating them in a live browser").requiredOption("-c, --config <path>", "path to demo.yaml").option("--segment <id>", "replace actions for an existing segment id").option("--output <path>", "manifest output path (default ./scripts/manifest.json)").action(recordActionsCommand);
 program.command("preview").description("Preview the generated Playwright script in UI Mode").requiredOption("-c, --config <path>", "path to demo.yaml").action(previewCommand);
@@ -8009,8 +8498,8 @@ program.parseAsync(process.argv).catch((err) => {
 });
 async function printWelcome() {
   const { access: access5 } = await import("fs/promises");
-  const { resolve: resolve27 } = await import("path");
-  const demoYaml = resolve27(process.cwd(), "demo.yaml");
+  const { resolve: resolve28 } = await import("path");
+  const demoYaml = resolve28(process.cwd(), "demo.yaml");
   let inProject = false;
   try {
     await access5(demoYaml);
@@ -8018,7 +8507,7 @@ async function printWelcome() {
   } catch {
   }
   const browserMissing = await isChromiumMissing();
-  const lines = ["", `Showrunner v1.1.4`, ""];
+  const lines = ["", `Showrunner v1.1.6`, ""];
   if (browserMissing) {
     lines.push(`Showrunner records using Chromium. You haven't installed it yet.`);
     lines.push(``);
@@ -8046,8 +8535,8 @@ async function isChromiumMissing() {
   try {
     const { chromium: chromium6 } = await import("playwright-core");
     const exec = chromium6.executablePath();
-    const { stat: stat16 } = await import("fs/promises");
-    await stat16(exec);
+    const { stat: stat17 } = await import("fs/promises");
+    await stat17(exec);
     return false;
   } catch {
     return true;