leglas 0.1.1 → 0.3.0

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/bin.ts
-import { spawn as spawn2 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import { createRequire as createRequire2 } from "module";
 
 // src/args.ts
@@ -51,7 +51,7 @@ function parseNew(rest) {
   if (surface === void 0) {
     return {
       kind: "error",
-      message: "leglas new needs a surface name, for example: leglas new hero"
+      message: "leglas new needs a surface name, for example: npx leglas new hero"
     };
   }
   return { kind: "new", surface, print, json, from };
@@ -62,6 +62,7 @@ function parseAdd(rest) {
   let note;
   let branch;
   let file;
+  let basedOn;
   const tags = [];
   let json = false;
   for (let index = 0; index < rest.length; index += 1) {
@@ -80,7 +81,7 @@ function parseAdd(rest) {
     } else {
       value = argument.slice(equals + 1);
     }
-    if (!["--title", "--url", "--note", "--tag", "--branch", "--file"].includes(flag)) {
+    if (!["--title", "--url", "--note", "--tag", "--branch", "--file", "--based-on"].includes(flag)) {
       return { kind: "error", message: `leglas add does not take ${flag}.` };
     }
     if (value === void 0 || value === "") {
@@ -91,6 +92,7 @@ function parseAdd(rest) {
     else if (flag === "--note") note = value;
     else if (flag === "--branch") branch = value;
     else if (flag === "--file") file = value;
+    else if (flag === "--based-on") basedOn = value;
     else tags.push(value);
   }
   if (title === void 0) {
@@ -104,7 +106,7 @@ function parseAdd(rest) {
   }
   return {
     kind: "add",
-    preview: { title, url, note, tags: tags.length > 0 ? tags : void 0, branch, file },
+    preview: { title, url, note, tags: tags.length > 0 ? tags : void 0, branch, file, basedOn },
     json
   };
 }
@@ -132,13 +134,42 @@ function parseClassify(rest) {
   if (changes.length === 0) {
     return {
       kind: "error",
-      message: "leglas classify needs what the direction will touch, for example: leglas classify --change package.json --rewrite src/theme.css"
+      message: "leglas classify needs what the direction will touch, for example: npx leglas classify --change package.json --rewrite src/theme.css"
     };
   }
   return { kind: "classify", changes, json };
 }
+function parseWatch(rest) {
+  let run3;
+  let port;
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index];
+    if (argument === "--help" || argument === "-h") return { kind: "help" };
+    const equals = argument.indexOf("=");
+    const flag = equals === -1 ? argument : argument.slice(0, equals);
+    if (flag !== "--run" && flag !== "--port") {
+      return { kind: "error", message: `leglas watch does not take ${argument}.` };
+    }
+    const value = equals === -1 ? rest[index += 1] : argument.slice(equals + 1);
+    if (value === void 0 || value === "") {
+      return {
+        kind: "error",
+        message: flag === "--run" ? '--run needs an agent command, for example --run "claude -p {prompt}"' : "--port needs a value."
+      };
+    }
+    if (flag === "--run") {
+      run3 = value;
+      continue;
+    }
+    const parsed2 = parsePort(flag, value);
+    if (typeof parsed2 !== "number") return { kind: "error", message: parsed2.error };
+    port = parsed2;
+  }
+  return { kind: "watch", run: run3, port };
+}
 function parseArgs(argv) {
   if (argv[0] === "new") return parseNew(argv.slice(1));
+  if (argv[0] === "watch") return parseWatch(argv.slice(1));
   if (argv[0] === "add") return parseAdd(argv.slice(1));
   if (argv[0] === "classify") return parseClassify(argv.slice(1));
   if (argv[0] === "init") {
@@ -178,7 +209,7 @@ function parseArgs(argv) {
     if (title === void 0) {
       return {
         kind: "error",
-        message: 'leglas keep needs a direction title, for example: leglas keep "Aurora" --to src/components/hero.tsx'
+        message: 'leglas keep needs a direction title, for example: npx leglas keep "Aurora" --to src/components/hero.tsx'
       };
     }
     if (to === void 0) {
@@ -190,6 +221,7 @@ function parseArgs(argv) {
     const rest = argv.slice(1);
     let surface;
     let count = 3;
+    let basedOn = null;
     let json = false;
     for (let index = 0; index < rest.length; index += 1) {
       const argument = rest[index];
@@ -205,6 +237,17 @@ function parseArgs(argv) {
         count = Number(raw);
         continue;
       }
+      if (argument === "--based-on" || argument.startsWith("--based-on=")) {
+        const raw = argument.includes("=") ? argument.split("=")[1] : rest[index += 1];
+        if (raw === void 0 || raw === "") {
+          return {
+            kind: "error",
+            message: '--based-on needs a direction title, for example --based-on "Aurora".'
+          };
+        }
+        basedOn = raw;
+        continue;
+      }
       if (argument.startsWith("-")) {
         return { kind: "error", message: `leglas explore does not take ${argument}.` };
       }
@@ -216,10 +259,10 @@ function parseArgs(argv) {
     if (surface === void 0) {
       return {
         kind: "error",
-        message: "leglas explore needs a surface name, for example: leglas explore hero --count 6"
+        message: "leglas explore needs a surface name, for example: npx leglas explore hero --count 6"
       };
     }
-    return { kind: "explore", surface, count, json };
+    return { kind: "explore", surface, count, basedOn, json };
   }
   if (argv[0] === "requests") {
     const rest = argv.slice(1);
@@ -237,6 +280,31 @@ function parseArgs(argv) {
     }
     return { kind: "list", json: rest.includes("--json") };
   }
+  if (argv[0] === "show") {
+    const rest = argv.slice(1);
+    let title;
+    let json = false;
+    for (const argument of rest) {
+      if (argument === "--json") {
+        json = true;
+        continue;
+      }
+      if (argument.startsWith("-")) {
+        return { kind: "error", message: `leglas show does not take ${argument}.` };
+      }
+      if (title !== void 0) {
+        return { kind: "error", message: "leglas show takes one direction title." };
+      }
+      title = argument;
+    }
+    if (title === void 0) {
+      return {
+        kind: "error",
+        message: 'leglas show needs a direction title, for example: npx leglas show "Aurora" --json'
+      };
+    }
+    return { kind: "show", title, json };
+  }
   const options = {
     port: void 0,
     userPort: void 0,
@@ -285,7 +353,7 @@ function parseArgs(argv) {
 
 // src/run-classify.ts
 import { stat } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // ../server/dist/config.js
 var DEFAULT_DEV_SERVER = "http://localhost:3000";
@@ -376,6 +444,10 @@ function normalizeConfig(raw, options = {}) {
         errors.push(`${at} names a branch and a file; a file preview is served by Leglas itself and has no checkout.`);
       }
     }
+    const basedOn = entry["basedOn"];
+    if (basedOn !== void 0 && (typeof basedOn !== "string" || basedOn.trim() === "")) {
+      errors.push(`${at} has a basedOn that is not a direction title.`);
+    }
     const tags = entry["tags"];
     previews.push({
       title: typeof title === "string" ? title : "",
@@ -383,7 +455,8 @@ function normalizeConfig(raw, options = {}) {
       note: typeof entry["note"] === "string" ? entry["note"] : void 0,
       tags: Array.isArray(tags) ? tags.filter((tag) => typeof tag === "string") : [],
       ...typeof branch === "string" ? { branch } : {},
-      ...typeof file === "string" ? { file } : {}
+      ...typeof file === "string" ? { file } : {},
+      ...typeof basedOn === "string" && basedOn.trim() !== "" ? { basedOn } : {}
     });
   });
   const devCommand = source["devCommand"];
@@ -449,12 +522,12 @@ function isExplorationFile(path) {
 }
 var CHECKOUT_STEPS = [
   "Build the direction on its own branch: git switch -c <branch>, commit it there, switch back.",
-  'Register it: leglas add --title "<title>" --url "/" --branch <branch>.',
+  'Register it: npx leglas add --title "<title>" --url "/" --branch <branch>.',
   "Make sure the config sets devCommand (with {port}), so Leglas can start the checkout."
 ];
 var IN_APP_STEPS = [
   "Author it additively under .leglas/variants/<surface>/, beside the existing directions.",
-  'Register it: leglas add --title "<title>" --url "/?v-<surface>=<direction>".'
+  'Register it: npx leglas add --title "<title>" --url "/?v-<surface>=<direction>".'
 ];
 function classifyDirection(input) {
   const checkout = (reason) => ({ level: "checkout", reason, steps: CHECKOUT_STEPS });
@@ -587,7 +660,8 @@ async function addLocalPreview(cwd, input, shared) {
     ...input.note === void 0 ? {} : { note: input.note },
     ...input.tags === void 0 ? {} : { tags: input.tags },
     ...input.branch === void 0 ? {} : { branch: input.branch },
-    ...input.file === void 0 ? {} : { file: input.file }
+    ...input.file === void 0 ? {} : { file: input.file },
+    ...input.basedOn === void 0 ? {} : { basedOn: input.basedOn }
   };
   const check = normalizeConfig({ previews: [candidate] }, { requireDevCommand: false });
   if (check.config === null) {
@@ -821,6 +895,7 @@ async function startAppProcess(options) {
 
 // ../server/dist/requests.js
 import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
+import { randomBytes } from "crypto";
 import { dirname as dirname3, join as join4 } from "path";
 var SAFE_SEGMENT = /^[a-z0-9][a-z0-9-]*$/i;
 function targetFor(url) {
@@ -859,7 +934,16 @@ async function readRequests(cwd) {
   try {
     const raw = await readFile3(join4(cwd, REQUESTS_PATH), "utf8");
     const parsed2 = JSON.parse(raw);
-    return Array.isArray(parsed2.requests) ? parsed2.requests : [];
+    if (!Array.isArray(parsed2.requests))
+      return [];
+    return parsed2.requests.map((request, index) => {
+      const entry = request;
+      return {
+        ...entry,
+        id: typeof entry.id === "string" ? entry.id : String(index),
+        status: entry.status === "picked-up" ? "picked-up" : "queued"
+      };
+    });
   } catch {
     return [];
   }
@@ -871,20 +955,83 @@ async function writeQueue(cwd, requests) {
 `, "utf8");
 }
 async function appendRequest(cwd, request) {
-  await writeQueue(cwd, [...await readRequests(cwd), request]);
+  await writeQueue(cwd, [
+    ...await readRequests(cwd),
+    { ...request, id: randomBytes(6).toString("base64url"), status: "queued" }
+  ]);
+}
+async function collectRequests(cwd) {
+  const requests = await readRequests(cwd);
+  const collected = requests.map((request) => ({ ...request, status: "picked-up" }));
+  if (requests.some((request) => request.status !== "picked-up"))
+    await writeQueue(cwd, collected);
+  return collected;
+}
+async function markPickedUp(cwd, id) {
+  const requests = await readRequests(cwd);
+  if (!requests.some((request) => request.id === id && request.status !== "picked-up"))
+    return false;
+  await writeQueue(cwd, requests.map((request) => request.id === id ? { ...request, status: "picked-up" } : request));
+  return true;
+}
+async function removeRequest(cwd, id) {
+  const requests = await readRequests(cwd);
+  const remaining = requests.filter((request) => request.id !== id);
+  if (remaining.length === requests.length)
+    return false;
+  await writeQueue(cwd, remaining);
+  return true;
 }
 async function clearRequests(cwd) {
-  await writeQueue(cwd, []);
+  const requests = await readRequests(cwd);
+  const pending = requests.filter((request) => request.status !== "picked-up");
+  const cleared = requests.length - pending.length;
+  if (cleared > 0)
+    await writeQueue(cwd, pending);
+  return { cleared, pending: pending.length };
+}
+
+// ../server/dist/renames.js
+import { mkdir as mkdir3, readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname4, join as join5 } from "path";
+var RENAMES_PATH = ".leglas/renames.json";
+async function readRenames(cwd) {
+  try {
+    const raw = await readFile4(join5(cwd, RENAMES_PATH), "utf8");
+    const parsed2 = JSON.parse(raw);
+    if (parsed2.renames === null || typeof parsed2.renames !== "object")
+      return {};
+    return Object.fromEntries(Object.entries(parsed2.renames).filter((entry) => typeof entry[1] === "string" && entry[1] !== ""));
+  } catch {
+    return {};
+  }
+}
+async function writeRenames(cwd, renames) {
+  const path = join5(cwd, RENAMES_PATH);
+  await mkdir3(dirname4(path), { recursive: true });
+  await writeFile3(path, `${JSON.stringify({ renames }, null, 2)}
+`, "utf8");
+}
+function resolveTitle(input, titles, renames) {
+  if (titles.includes(input))
+    return { ok: true, title: input };
+  const matches = titles.filter((title) => renames[title] === input);
+  if (matches.length === 1 && matches[0] !== void 0)
+    return { ok: true, title: matches[0] };
+  if (matches.length > 1)
+    return { ok: false, reason: "ambiguous", matches };
+  return { ok: false, reason: "unknown" };
 }
 
 // ../server/dist/server.js
 import { createReadStream, existsSync as existsSync2, statSync } from "fs";
 import http2 from "http";
 import net3 from "net";
-import { extname, join as join5, normalize } from "path";
+import { extname, join as join6, normalize, relative as relative2 } from "path";
 var LEGLAS_PREFIX = "/leglas";
 var DEFAULT_PORT = 4100;
 var PORT_ATTEMPTS = 20;
+var ATTACHED_WINDOW_MS = 6e3;
 var CONTENT_TYPES = {
   ".css": "text/css; charset=utf-8",
   ".gif": "image/gif",
@@ -932,8 +1079,8 @@ function probe(target, timeoutMs = 1e3) {
   });
 }
 function serveFrom(res, dir, relativePath) {
-  const relative3 = normalize(relativePath).replace(/^(\.\.[/\\])+/, "");
-  const candidate = join5(dir, relative3);
+  const relative4 = normalize(relativePath).replace(/^(\.\.[/\\])+/, "");
+  const candidate = join6(dir, relative4);
   if (!candidate.startsWith(dir))
     return false;
   if (!existsSync2(candidate) || !statSync(candidate).isFile())
@@ -946,9 +1093,36 @@ function serveFrom(res, dir, relativePath) {
   return true;
 }
 function serveShellFile(res, shellDir, urlPath) {
-  const relative3 = normalize(urlPath.slice(LEGLAS_PREFIX.length)).replace(/^(\.\.[/\\])+/, "");
-  const isRoot = relative3 === "" || relative3 === "." || relative3 === "/";
-  return serveFrom(res, shellDir, isRoot ? "index.html" : relative3);
+  const relative4 = normalize(urlPath.slice(LEGLAS_PREFIX.length)).replace(/^(\.\.[/\\])+/, "");
+  const isRoot = relative4 === "" || relative4 === "." || relative4 === "/";
+  return serveFrom(res, shellDir, isRoot ? "index.html" : relative4);
+}
+function snapshotConfig(cwd) {
+  const path = findConfigFile(cwd);
+  if (path === null)
+    return null;
+  try {
+    return { path, mtimeMs: statSync(path).mtimeMs };
+  } catch {
+    return null;
+  }
+}
+function configStalenessNotice(cwd, boot, current) {
+  if (boot === null && current === null)
+    return null;
+  if (boot === null && current !== null) {
+    const label = relative2(cwd, current.path) || current.path;
+    return `${label} appeared after Leglas started. Restart leglas to pick it up.`;
+  }
+  if (boot !== null && current === null) {
+    const label = relative2(cwd, boot.path) || boot.path;
+    return `${label} was removed after Leglas started. Restart leglas to run without it.`;
+  }
+  if (boot !== null && current !== null && (boot.path !== current.path || boot.mtimeMs !== current.mtimeMs)) {
+    const label = relative2(cwd, current.path) || current.path;
+    return `${label} changed after Leglas started. Restart leglas to pick it up.`;
+  }
+  return null;
 }
 var PLACEHOLDER = `<!doctype html>
 <meta charset="utf-8">
@@ -958,7 +1132,8 @@ var PLACEHOLDER = `<!doctype html>
 <p>The server is running and proxying your app. The interface has not been
 built into this install yet.</p>
 <p><a href="/leglas/api/config">/leglas/api/config</a> \xB7
-<a href="/leglas/api/health">/leglas/api/health</a></p>
+<a href="/leglas/api/health">/leglas/api/health</a> \xB7
+<a href="/leglas/api/requests">/leglas/api/requests</a></p>
 </body>`;
 function listen(server, port) {
   return new Promise((resolve, reject) => {
@@ -993,28 +1168,45 @@ async function startServer(options) {
   const { config, configErrors = [], shellDir = null, project = "", cwd = process.cwd(), fileMounts = /* @__PURE__ */ new Map() } = options;
   const target = config?.devServer ?? "http://localhost:3000";
   const proxy = createProxyHandler({ target });
+  const bootConfigSnapshot = snapshotConfig(cwd);
+  let lastSeen = null;
   const server = http2.createServer((req, res) => {
     const url = req.url ?? "/";
     const path = url.split("?")[0] ?? "/";
     if (path === `${LEGLAS_PREFIX}/api/config`) {
-      return sendJson(res, 200, {
+      const boot = config?.previews ?? [];
+      const errors = [...configErrors];
+      const notice = configStalenessNotice(cwd, bootConfigSnapshot, snapshotConfig(cwd));
+      if (notice !== null)
+        errors.push(notice);
+      return void readLocalPreviews(cwd).then(({ previews: local }) => {
+        const known = new Set(boot.map((preview) => preview.title));
+        const fresh = local.filter((preview) => !known.has(preview.title) && preview.branch === void 0 && preview.file === void 0);
+        sendJson(res, 200, {
+          project,
+          devServer: target,
+          previews: [...boot, ...fresh],
+          errors
+        });
+      }).catch(() => sendJson(res, 200, {
         project,
         devServer: target,
-        previews: config?.previews ?? [],
-        errors: configErrors
-      });
+        previews: boot,
+        errors
+      }));
     }
     if (path === `${LEGLAS_PREFIX}/api/request` && req.method === "POST") {
       let body = "";
       req.on("data", (chunk) => body += chunk);
-      return void req.on("end", () => {
+      return void req.on("end", async () => {
         let parsed2;
         try {
           parsed2 = JSON.parse(body || "{}");
         } catch {
           return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
         }
-        const preview = (config?.previews ?? []).find((entry) => entry.title === parsed2.title);
+        const local = await readLocalPreviews(cwd).then((read) => read.previews, () => []);
+        const preview = [...config?.previews ?? [], ...local].find((entry) => entry.title === parsed2.title);
         if (!preview || !parsed2.intent?.trim()) {
           return sendJson(res, 400, { ok: false, error: "Unknown preview, or empty request." });
         }
@@ -1027,6 +1219,46 @@ async function startServer(options) {
         }).then(() => sendJson(res, 200, { ok: true, ...composed })).catch(() => sendJson(res, 200, { ok: true, ...composed, queued: false }));
       });
     }
+    if (path === `${LEGLAS_PREFIX}/api/watch` && req.method === "POST") {
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      return void req.on("end", () => {
+        let parsed2;
+        try {
+          parsed2 = JSON.parse(body || "{}");
+        } catch {
+          return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
+        }
+        if (typeof parsed2.watching !== "boolean") {
+          return sendJson(res, 400, { ok: false, error: "Body needs a watching boolean." });
+        }
+        lastSeen = parsed2.watching ? Date.now() : null;
+        sendJson(res, 200, { ok: true });
+      });
+    }
+    if (path === `${LEGLAS_PREFIX}/api/requests` && req.method === "GET") {
+      return void readRequests(cwd).then((requests) => sendJson(res, 200, {
+        requests: requests.map(({ id, title, intent, status }) => ({ id, title, intent, status })),
+        agent: { attached: lastSeen !== null && Date.now() - lastSeen < ATTACHED_WINDOW_MS }
+      }));
+    }
+    if (path === `${LEGLAS_PREFIX}/api/renames` && req.method === "POST") {
+      let body = "";
+      req.on("data", (chunk) => body += chunk);
+      return void req.on("end", () => {
+        let parsed2;
+        try {
+          parsed2 = JSON.parse(body || "{}");
+        } catch {
+          return sendJson(res, 400, { ok: false, error: "Body must be JSON." });
+        }
+        if (parsed2.renames === null || typeof parsed2.renames !== "object") {
+          return sendJson(res, 400, { ok: false, error: "Body needs a renames object." });
+        }
+        const renames = Object.fromEntries(Object.entries(parsed2.renames).filter((entry) => typeof entry[1] === "string" && entry[1] !== ""));
+        void writeRenames(cwd, renames).then(() => sendJson(res, 200, { ok: true }), () => sendJson(res, 200, { ok: false }));
+      });
+    }
     if (path === `${LEGLAS_PREFIX}/api/health`) {
       return void probe(target).then((reachable) => sendJson(res, 200, { devServer: target, reachable }));
     }
@@ -1034,21 +1266,28 @@ async function startServer(options) {
       const rest = path.slice(FILES_PREFIX.length + 1);
       const slash = rest.indexOf("/");
       const slug = slash === -1 ? rest : rest.slice(0, slash);
-      let relative3 = slash === -1 ? "" : rest.slice(slash + 1);
+      let relative4 = slash === -1 ? "" : rest.slice(slash + 1);
       try {
-        relative3 = decodeURIComponent(relative3);
+        relative4 = decodeURIComponent(relative4);
       } catch {
-        relative3 = "";
+        relative4 = "";
       }
       const dir = fileMounts.get(slug);
-      if (dir !== void 0 && relative3 !== "" && serveFrom(res, dir, relative3))
+      if (dir !== void 0 && relative4 !== "" && serveFrom(res, dir, relative4))
         return;
       res.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
       return res.end("Leglas: no such preview file.");
     }
+    if (path.startsWith(`${LEGLAS_PREFIX}/api/`)) {
+      return sendJson(res, 404, { error: "No such Leglas API path." });
+    }
     if (path === LEGLAS_PREFIX || path.startsWith(`${LEGLAS_PREFIX}/`)) {
       if (shellDir !== null && serveShellFile(res, shellDir, path))
         return;
+      if (shellDir !== null) {
+        res.writeHead(404, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+        return res.end("Leglas: no such path.");
+      }
       res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
       return res.end(PLACEHOLDER);
     }
@@ -1084,7 +1323,7 @@ async function runClassify(options, deps) {
   const declared = await Promise.all(
     options.changes.map(async (change) => ({
       ...change,
-      exists: await stat(join6(options.cwd, change.path)).then(
+      exists: await stat(join7(options.cwd, change.path)).then(
         () => true,
         () => false
       )
@@ -1310,139 +1549,47 @@ Rewriting your component automatically is how a tool breaks a codebase it does n
   };
 }
 
-// src/briefs.ts
-var ALL_BRIEFS = [
-  {
-    slug: "quiet",
-    name: "Quiet",
-    brief: "Reduce until almost nothing is left. Generous whitespace, a single focal element, and typography carrying the whole hierarchy. Remove decoration rather than softening it.",
-    avoid: "Adding a subtle gradient or a lighter shade and calling the result minimal."
-  },
-  {
-    slug: "image-led",
-    name: "Image-led",
-    brief: "Let imagery be the page. Full-bleed visual, text as a restrained overlay, and a composition that follows the artwork rather than sitting beside it.",
-    avoid: "Keeping the existing layout and enlarging the picture inside it."
-  },
-  {
-    slug: "kinetic",
-    name: "Kinetic",
-    brief: "Motion carries the hierarchy. Something continuous and ambient, with elements arriving in a deliberate sequence. Honour prefers-reduced-motion with a still composition that still works.",
-    avoid: "A fade-in on scroll bolted onto the current design."
-  },
-  {
-    slug: "editorial",
-    name: "Editorial",
-    brief: "Compose it like a magazine spread. Asymmetric grid, large display type with tight leading, rules and captions, imagery treated as a plate rather than a background.",
-    avoid: "A centred headline above a centred paragraph."
-  },
-  {
-    slug: "dense",
-    name: "Dense",
-    brief: "Information forward. Tighter rhythm, smaller type, several entry points visible at once, and the confidence that the reader wants more rather than less.",
-    avoid: "The same layout with the padding reduced."
-  },
-  {
-    slug: "high-contrast",
-    name: "High contrast",
-    brief: "Commit to a hard palette: near-black against one saturated accent, or the whole thing inverted. Define shapes with edges rather than gradients.",
-    avoid: "Darkening the existing palette by a few steps."
-  },
-  {
-    slug: "material",
-    name: "Material",
-    brief: "Give it depth and surface. Layered planes, grain or noise, shadow used structurally to stack elements, a sense that the parts are physical objects.",
-    avoid: "One drop shadow on an otherwise flat card."
-  },
-  {
-    slug: "type-led",
-    name: "Type-led",
-    brief: "Remove imagery entirely. Build the composition from letterforms: extreme scale contrast, a second typeface earning its place, text as the visual itself.",
-    avoid: "Keeping the image and setting the headline larger."
-  },
-  {
-    slug: "playful",
-    name: "Playful",
-    brief: "Deliberate imperfection. Rotation, overlap, irregular or hand-made elements, and one colour that ought not to work but does.",
-    avoid: "Increasing the border radius and little else."
-  },
-  {
-    slug: "systemic",
-    name: "Systemic",
-    brief: "Make the structure visible. Modular blocks on a stated grid, consistent module sizes, alignment itself as the aesthetic.",
-    avoid: "Adding borders around the sections that already exist."
-  }
-];
-function briefsFor(count) {
-  if (!Number.isFinite(count) || count <= 0) return [];
-  return ALL_BRIEFS.slice(0, Math.min(Math.floor(count), ALL_BRIEFS.length));
-}
-function planBriefs(surface, count) {
+// src/explore.ts
+function planExplore(surface, count, basedOn = null) {
   const slug = surfaceSlug(surface);
-  const chosen = briefsFor(count);
-  const previews = chosen.map((brief) => ({
-    title: brief.name,
-    url: `/?v-${slug}=${brief.slug}`
-  }));
-  const commands = chosen.map(
-    (brief) => `leglas add --title ${JSON.stringify(brief.name)} --url ${JSON.stringify(
-      `/?v-${slug}=${brief.slug}`
-    )} --note ${JSON.stringify(`${brief.brief.split(".")[0]}.`)}`
-  );
-  const instructions = `Build ${chosen.length} direction${chosen.length === 1 ? "" : "s"} for "${surface}", one per angle below.
+  const goal = basedOn === null ? `Build ${count} design directions for "${surface}".
+
+The set exists to be chosen from, and the choice only means something if the directions genuinely disagree: ${count} variants of one idea would make it empty. What counts as different is yours to decide, and the strongest sets disagree about more than styling.
+
+One trap, seen every time this goes wrong: a set collapses toward whichever direction is built first. Decide all ${count} before building any, and if two would read as the same direction at a glance, replace one of them.` : `Build ${count} variations of the "${basedOn}" direction for "${surface}".
 
-Each goes in its own file under .leglas/variants/${slug}/, named after its slug, and is listed in the DIRECTIONS map in that folder's switch file. If the surface has no switch file yet, run \`leglas new ${slug}\` first.
+The set exists to pick a variant of a direction already chosen, so every variation must stay recognisably that direction. The trap here is drift: change enough and the comparison stops being about the variant. Vary each one deliberately and hold everything else still; if a variation grows into a new direction, it belongs in its own exploration instead.`;
+  const register = basedOn === null ? `  npx leglas add --title "<name>" --url "/?v-${slug}=<key>" --note "<the idea, one line>"` : `  npx leglas add --title "<name>" --url "/?v-${slug}=<key>" --based-on ${JSON.stringify(basedOn)} --note "<the idea, one line>"`;
+  const mechanics = `Each one is its own file under .leglas/variants/${slug}/, listed in the DIRECTIONS map in that folder's switch file. If there is no switch file yet, run \`npx leglas new ${slug}\` first. Register each one the moment it renders, not the set at the end. The interface picks a registration up within seconds, so whoever asked watches the set fill in:
 
-Keep them distinct from each other. The point of exploring several at once is that they disagree; directions that converge on one look waste the exercise. Read each angle's "avoid" line before starting, because it names the obvious reading that collapses the difference.
+${register}
 
-Then register them:
+The title and note are what the user judges from in the rail, so name each one for its idea rather than numbering it.`;
+  return { surface, slug, count, basedOn, instructions: `${goal}
 
-` + commands.map((command) => `  ${command}`).join("\n");
-  return { previews, commands, instructions };
+${mechanics}` };
 }
 
 // src/run-explore.ts
 function runExplore(options, deps) {
-  const chosen = briefsFor(options.count);
-  if (chosen.length === 0) {
+  if (!Number.isFinite(options.count) || options.count <= 0) {
     deps.log(
       options.json ? JSON.stringify({ ok: false, error: "Ask for at least one direction." }) : "Ask for at least one direction, for example --count 4."
     );
     return { exitCode: 1 };
   }
-  const plan = planBriefs(options.surface, options.count);
+  const plan = planExplore(options.surface, Math.floor(options.count), options.basedOn);
   if (options.json) {
-    deps.log(
-      JSON.stringify({
-        ok: true,
-        surface: options.surface,
-        directions: chosen,
-        previews: plan.previews,
-        commands: plan.commands,
-        instructions: plan.instructions
-      })
-    );
+    deps.log(JSON.stringify({ ok: true, ...plan }));
     return { exitCode: 0 };
   }
-  if (options.count > ALL_BRIEFS.length) {
-    deps.log(
-      `Asked for ${options.count}; there are ${ALL_BRIEFS.length} distinct angles, so ${ALL_BRIEFS.length} follow.`
-    );
-    deps.log("");
-  }
-  for (const brief of chosen) {
-    deps.log(`${brief.name}`);
-    deps.log(`  ${brief.brief}`);
-    deps.log(`  Avoid: ${brief.avoid}`);
-    deps.log("");
-  }
   deps.log(plan.instructions);
   return { exitCode: 0 };
 }
 
 // src/run-init.ts
-import { readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
-import { join as join7 } from "path";
+import { readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
+import { join as join8 } from "path";
 
 // src/init.ts
 var AGENTS_MARKER_START = "<!-- leglas:start -->";
@@ -1469,34 +1616,48 @@ When asked for design variations, alternatives, or "a few options":
    If a direction cannot be additive, because it must change dependencies,
    change build configuration, or rewrite an existing file's behaviour, ask
    where it should live before writing it:
-   \`leglas classify --change package.json --rewrite src/theme.css --json\`.
+   \`npx leglas classify --change package.json --rewrite src/theme.css --json\`.
    When the answer is \`checkout\`, build the direction on its own git branch
-   and register it with \`leglas add --title "\u2026" --url "/" --branch <branch>\`
+   and register it with \`npx leglas add --title "\u2026" --url "/" --branch <branch>\`
    (the config needs \`devCommand\` with \`{port}\`). Everything below is the
    ordinary, in-app path.
-2. Run \`leglas explore <surface> --count <n>\` first. It returns distinct
-   angles to build, each with what to avoid, so several directions genuinely
-   disagree instead of becoming shades of one idea. Follow those angles rather
-   than inventing your own variations of the current design.
+2. Run \`npx leglas explore <surface> --count <n>\` first, adding
+   \`--based-on "<title>"\` when the user wants variations of a direction they
+   already like. It prints what the set needs and how to register it. In
+   short: new directions must genuinely disagree with each other, variants of
+   one must not, and either way decide the whole set before building any of
+   it. The designs themselves are yours.
 3. If the surface has no switcher yet, run
-   \`leglas new <surface> --from <the component that renders it today>\`. It
+   \`npx leglas new <surface> --from <the component that renders it today>\`. It
    writes one under \`.leglas/variants/<surface>/\` and prints the single line
    to add where that surface renders. \`--from\` makes the baseline re-export
    the real component rather than copying it, so it stays live.
-4. Put each direction in its own file beside the others in
-   \`.leglas/variants/<surface>/\`, then list it in the \`DIRECTIONS\` map in
-   that folder's \`switch\` file.
-5. Register each one so it appears in the interface:
-   \`leglas add --title "Aurora" --url "/?v-<surface>=aurora" --note "One line on the idea."\`
-6. Tell the user to open the interface, or to run \`leglas\` if it is not
-   already running.
-
-When the user asks to change one direction, check \`leglas requests --json\`
+4. Before building, make sure the interface is up. If Leglas is not
+   already running, tell the user to run \`npx leglas\`, and hand them the
+   URL now rather than when the set is done: the rail picks up each
+   registration within seconds, so they get to watch the exploration fill in.
+5. Build one direction at a time: its own file beside the others in
+   \`.leglas/variants/<surface>/\`, listed in the \`DIRECTIONS\` map in that
+   folder's \`switch\` file, then registered the moment it renders:
+   \`npx leglas add --title "Aurora" --url "/?v-<surface>=aurora" --note "One line on the idea."\`
+   Register each direction as it lands, never the whole set at the end. To
+   the user watching the rail, a batch at the end is minutes of nothing and
+   then everything at once.
+
+When the user asks to change one direction, check \`npx leglas requests --json\`
 first: they may have described it from the interface, and the request names the
-exact file. Clear the queue with \`leglas requests --clear\` once done.
+exact file. Acknowledge them with \`npx leglas requests --clear\` once done: it
+drops what you collected and reports anything the user typed while you worked,
+which is yours to collect and do next.
+
+If the user wants requests handled the moment they are typed, without relaying
+each one, tell them about \`npx leglas watch --run "claude -p {prompt}"\` (any
+agent command works; {prompt} receives the request). It runs in their
+terminal, hands each request to that command as it arrives, and the interface
+shows the request's progress.
 
 When the user picks a winner, run
-\`leglas keep "<title>" --to <path in real source>\`. It moves that direction
+\`npx leglas keep "<title>" --to <path in real source>\`. It moves that direction
 out of the ignored directory, deletes the rest of the exploration, and drops
 them from the rail. Then change their component to use the kept component
 instead of the switcher.
@@ -1507,18 +1668,24 @@ Useful to know:
   ships. Move a direction into real source only when it wins.
 - If the project has no running app yet, a direction can be a plain HTML
   file: write it under \`.leglas/pages/\` and register it with
-  \`leglas add --title "Aurora" --file .leglas/pages/aurora.html\`. Leglas
+  \`npx leglas add --title "Aurora" --file .leglas/pages/aurora.html\`. Leglas
   serves the file itself, so no dev server is needed. Sibling assets in the
   same directory resolve normally.
-- Titles identify previews and must be unique.
-- \`leglas list\` shows every direction, shared and local.
+- Titles identify previews and must be unique. The user may rename one in the
+  rail, which renames it on their machine only; the commands answer to either
+  name, so use whichever they said.
+- \`npx leglas list\` shows every direction, shared and local.
+- \`npx leglas show "<title>" --json\` answers for one of them: the file behind it,
+  the variants based on it, what it is being compared against, and anything
+  they have asked for that is not done yet. Run it when handed a direction you
+  did not register yourself.
 - Every command accepts \`--json\` and prints one envelope with a stable exit
   code, so you can drive it without parsing prose.
 
 ${AGENTS_MARKER_END}
 `;
 var STARTER_CONFIG = `// Previews are URLs of your own app. Add one per direction you want to
-// compare, then run \`leglas\`.
+// compare, then run \`npx leglas\`.
 export default {
   // Where your dev server is. Override at the command line with --user-port.
   devServer: "http://localhost:3000",
@@ -1555,7 +1722,7 @@ ${AGENTS_SECTION}`
 // src/run-init.ts
 async function readIfPresent(path) {
   try {
-    return await readFile4(path, "utf8");
+    return await readFile5(path, "utf8");
   } catch {
     return null;
   }
@@ -1563,18 +1730,18 @@ async function readIfPresent(path) {
 async function runInit(options, deps) {
   const existingConfig = findConfigFile(options.cwd);
   const plan = planInit({
-    agents: await readIfPresent(join7(options.cwd, "AGENTS.md")),
+    agents: await readIfPresent(join8(options.cwd, "AGENTS.md")),
     config: existingConfig === null ? null : "present",
-    gitignore: await readIfPresent(join7(options.cwd, ".gitignore")),
+    gitignore: await readIfPresent(join8(options.cwd, ".gitignore")),
     force: options.force
   });
   const touched = [];
   for (const write of plan.writes) {
-    await writeFile3(join7(options.cwd, write.path), write.contents, "utf8");
+    await writeFile4(join8(options.cwd, write.path), write.contents, "utf8");
     touched.push(write.path);
   }
   if (plan.gitignore !== null) {
-    await writeFile3(join7(options.cwd, ".gitignore"), plan.gitignore, "utf8");
+    await writeFile4(join8(options.cwd, ".gitignore"), plan.gitignore, "utf8");
     touched.push(".gitignore");
   }
   if (options.json) {
@@ -1594,8 +1761,8 @@ async function runInit(options, deps) {
 
 // src/run-keep.ts
 import { existsSync as existsSync3 } from "fs";
-import { mkdir as mkdir3, readFile as readFile5, rm as rm2, writeFile as writeFile4 } from "fs/promises";
-import { dirname as dirname4, join as join8 } from "path";
+import { mkdir as mkdir4, readFile as readFile6, rm as rm2, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname5, join as join9 } from "path";
 
 // src/keep.ts
 import { basename as basename2, extname as extname2, normalize as normalize2 } from "path";
@@ -1616,7 +1783,7 @@ function planKeep(options) {
   if (!winner) {
     return {
       ok: false,
-      error: `No direction called ${JSON.stringify(options.title)}. Run leglas list to see them.`
+      error: `No direction called ${JSON.stringify(options.title)}. Run npx leglas list to see them.`
     };
   }
   const from = targetFor(winner.url);
@@ -1652,6 +1819,22 @@ function planKeep(options) {
   };
 }
 
+// src/resolve-title.ts
+function resolveOrExplain(input, titles, renames) {
+  const resolution = resolveTitle(input, titles, renames);
+  if (resolution.ok) return { ok: true, title: resolution.title };
+  if (resolution.reason === "ambiguous") {
+    return {
+      ok: false,
+      error: `More than one direction is called ${JSON.stringify(input)} on this machine: ${resolution.matches.join(", ")}. Name the one you mean by its title in the config.`
+    };
+  }
+  return {
+    ok: false,
+    error: `No direction called ${JSON.stringify(input)}. Renaming one in the rail only renames it here, and it still answers to its title in the config, which its reference block quotes. npx leglas list shows every title.`
+  };
+}
+
 // src/run-keep.ts
 function renameExport(source, to) {
   const match = /export function ([A-Za-z0-9_]+)\s*\(/.exec(source);
@@ -1665,31 +1848,37 @@ async function runKeep(options, deps) {
   const loaded = await loadConfig(options.cwd);
   const local = await readLocalPreviews(options.cwd);
   const previews = [...loaded.config?.previews ?? [], ...local.previews];
-  const plan = planKeep({ title: options.title, previews, to: options.to });
   const fail = (error) => {
     if (options.json) deps.log(JSON.stringify({ ok: false, error }));
     else deps.error(error);
     return { exitCode: 1 };
   };
+  const resolved = resolveOrExplain(
+    options.title,
+    previews.map((preview) => preview.title),
+    await readRenames(options.cwd)
+  );
+  if (!resolved.ok) return fail(resolved.error);
+  const plan = planKeep({ title: resolved.title, previews, to: options.to });
   if (!plan.ok) return fail(plan.error);
-  const from = join8(options.cwd, plan.move.from);
-  const to = join8(options.cwd, plan.move.to);
+  const from = join9(options.cwd, plan.move.from);
+  const to = join9(options.cwd, plan.move.to);
   if (!existsSync3(from)) {
     return fail(`${plan.move.from} does not exist. Nothing to keep.`);
   }
   if (existsSync3(to)) {
     return fail(`${plan.move.to} already exists. Choose another destination or move it aside.`);
   }
-  const source = await readFile5(from, "utf8");
-  await mkdir3(dirname4(to), { recursive: true });
-  await writeFile4(to, renameExport(source, plan.exportName), "utf8");
-  await rm2(join8(options.cwd, plan.removeDir), { recursive: true, force: true });
+  const source = await readFile6(from, "utf8");
+  await mkdir4(dirname5(to), { recursive: true });
+  await writeFile5(to, renameExport(source, plan.exportName), "utf8");
+  await rm2(join9(options.cwd, plan.removeDir), { recursive: true, force: true });
   const dropped = await dropLocalPreviews(options.cwd, plan.dropTitles);
   if (options.json) {
     deps.log(
       JSON.stringify({
         ok: true,
-        kept: options.title,
+        kept: resolved.title,
         to: plan.move.to,
         exportName: plan.exportName,
         removed: plan.removeDir,
@@ -1718,11 +1907,11 @@ async function runKeep(options, deps) {
 
 // src/run-new.ts
 import { existsSync as existsSync4 } from "fs";
-import { mkdir as mkdir4, readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname5, join as join9 } from "path";
+import { mkdir as mkdir5, readFile as readFile7, writeFile as writeFile6 } from "fs/promises";
+import { dirname as dirname6, join as join10 } from "path";
 async function readIfPresent2(path) {
   try {
-    return await readFile6(path, "utf8");
+    return await readFile7(path, "utf8");
   } catch {
     return null;
   }
@@ -1730,7 +1919,7 @@ async function readIfPresent2(path) {
 async function runNew(options, deps) {
   let from;
   if (options.from !== void 0) {
-    const contents = await readIfPresent2(join9(options.cwd, options.from));
+    const contents = await readIfPresent2(join10(options.cwd, options.from));
     if (contents === null) {
       const message = `${options.from} does not exist, so there is nothing to use as the baseline.`;
       if (options.json) deps.log(JSON.stringify({ ok: false, error: message }));
@@ -1741,8 +1930,8 @@ async function runNew(options, deps) {
   }
   const plan = planNew({
     surface: options.surface,
-    packageJson: await readIfPresent2(join9(options.cwd, "package.json")),
-    gitignore: await readIfPresent2(join9(options.cwd, ".gitignore")),
+    packageJson: await readIfPresent2(join10(options.cwd, "package.json")),
+    gitignore: await readIfPresent2(join10(options.cwd, ".gitignore")),
     from
   });
   const fail = (error) => {
@@ -1765,19 +1954,19 @@ async function runNew(options, deps) {
     deps.log(plan.instructions);
     return { exitCode: 0, written: [] };
   }
-  const existing = plan.writes.filter((write) => existsSync4(join9(options.cwd, write.path)));
+  const existing = plan.writes.filter((write) => existsSync4(join10(options.cwd, write.path)));
   if (existing.length > 0) {
     return fail(`${existing[0]?.path} already exists. Delete it first, or pick another surface name.`);
   }
   const written = [];
   for (const write of plan.writes) {
-    const target = join9(options.cwd, write.path);
-    await mkdir4(dirname5(target), { recursive: true });
-    await writeFile5(target, write.contents, "utf8");
+    const target = join10(options.cwd, write.path);
+    await mkdir5(dirname6(target), { recursive: true });
+    await writeFile6(target, write.contents, "utf8");
     written.push(write.path);
   }
   if (plan.gitignore !== null) {
-    await writeFile5(join9(options.cwd, ".gitignore"), plan.gitignore, "utf8");
+    await writeFile6(join10(options.cwd, ".gitignore"), plan.gitignore, "utf8");
     written.push(".gitignore");
   }
   if (options.json) {
@@ -1792,31 +1981,41 @@ async function runNew(options, deps) {
   deps.log("Then register them so they appear in the interface:");
   deps.log("");
   for (const preview of plan.previews) {
-    deps.log(`  leglas add --title ${JSON.stringify(preview.title)} --url ${JSON.stringify(preview.url)}`);
+    deps.log(`  npx leglas add --title ${JSON.stringify(preview.title)} --url ${JSON.stringify(preview.url)}`);
   }
   return { exitCode: 0, written };
 }
 
 // src/run-previews.ts
-import { readFile as readFile7, writeFile as writeFile6 } from "fs/promises";
-import { join as join10 } from "path";
+import { readFile as readFile8, writeFile as writeFile7 } from "fs/promises";
+import { join as join11 } from "path";
 function envelope(deps, ok, body) {
   deps.log(JSON.stringify({ ok, ...body }));
 }
 async function ensureIgnored(cwd) {
-  const path = join10(cwd, ".gitignore");
+  const path = join11(cwd, ".gitignore");
   let current = null;
   try {
-    current = await readFile7(path, "utf8");
+    current = await readFile8(path, "utf8");
   } catch {
     current = null;
   }
   const next = ignoreEntry(current);
-  if (next !== null) await writeFile6(path, next, "utf8");
+  if (next !== null) await writeFile7(path, next, "utf8");
 }
 async function runAdd(options, deps) {
   const loaded = await loadConfig(options.cwd);
   const shared = loaded.config?.previews ?? [];
+  if (options.preview.basedOn !== void 0) {
+    const local = await readLocalPreviews(options.cwd);
+    const titles = new Set([...shared, ...local.previews].map((preview) => preview.title));
+    if (!titles.has(options.preview.basedOn)) {
+      const error = `--based-on names ${JSON.stringify(options.preview.basedOn)}, which is not a registered direction. npx leglas list shows what exists.`;
+      if (options.json) envelope(deps, false, { error });
+      else deps.error(error);
+      return { exitCode: 1 };
+    }
+  }
   const outcome = await addLocalPreview(
     options.cwd,
     {
@@ -1825,7 +2024,8 @@ async function runAdd(options, deps) {
       note: options.preview.note,
       tags: options.preview.tags,
       branch: options.preview.branch,
-      file: options.preview.file
+      file: options.preview.file,
+      basedOn: options.preview.basedOn
     },
     shared
   );
@@ -1843,6 +2043,7 @@ async function runAdd(options, deps) {
       local: true,
       ...options.preview.branch === void 0 ? {} : { branch: options.preview.branch },
       ...options.preview.file === void 0 ? {} : { file: options.preview.file },
+      note: options.preview.branch === void 0 && options.preview.file === void 0 ? "A running interface picks this up within seconds." : "Restart Leglas to see this preview: branch checkouts and file mounts are built when Leglas starts.",
       ...needsDevCommand ? { warning: "The config sets no devCommand, so Leglas cannot start this branch yet. Add devCommand (with {port}) to the config." } : {}
     });
   } else {
@@ -1855,7 +2056,11 @@ async function runAdd(options, deps) {
       deps.log("    Add devCommand (with {port}) to the config.");
       deps.log("");
     }
-    deps.log("Local to this machine. Restart Leglas to see it, or run leglas list.");
+    if (options.preview.branch === void 0 && options.preview.file === void 0) {
+      deps.log("Local to this machine. A running interface picks it up within seconds.");
+    } else {
+      deps.log("Local to this machine. Restart Leglas to see it, or run npx leglas list.");
+    }
   }
   return { exitCode: 0 };
 }
@@ -1869,9 +2074,17 @@ async function runList(options, deps) {
   ];
   if (options.json) {
     envelope(deps, errors.length === 0, {
+      // The whole record, not a summary of it. What the config holds about a
+      // preview — its note, its tags, the direction it is a variant of — is
+      // exactly what tells an agent why these are being compared, and leaving
+      // it out made the listing thinner than the reference block that points
+      // at it.
       previews: previews.map((preview) => ({
         title: preview.title,
         url: preview.url,
+        note: preview.note ?? null,
+        tags: preview.tags,
+        basedOn: preview.basedOn ?? null,
         local: preview.local,
         branch: preview.branch ?? null,
         file: preview.file ?? null
@@ -1881,7 +2094,7 @@ async function runList(options, deps) {
     return { exitCode: errors.length === 0 ? 0 : 1 };
   }
   if (previews.length === 0) {
-    deps.log("No previews yet. Add one with leglas add, or list them in leglas.config.ts.");
+    deps.log("No previews yet. Add one with npx leglas add, or list them in leglas.config.ts.");
   } else {
     const width = Math.max(...previews.map((preview) => preview.title.length));
     for (const preview of previews) {
@@ -1896,12 +2109,19 @@ async function runList(options, deps) {
 }
 async function runRequests(options, deps) {
   if (options.clear) {
-    await clearRequests(options.cwd);
-    if (options.json) envelope(deps, true, { cleared: true });
-    else deps.log("Queue cleared.");
+    const { cleared, pending } = await clearRequests(options.cwd);
+    if (options.json) envelope(deps, true, { cleared, pending });
+    else {
+      deps.log(cleared === 1 ? "Cleared 1 request." : `Cleared ${cleared} requests.`);
+      if (pending > 0) {
+        deps.log(
+          `${pending} arrived while you worked. Run npx leglas requests to collect ${pending === 1 ? "it" : "them"}.`
+        );
+      }
+    }
     return { exitCode: 0 };
   }
-  const requests = await readRequests(options.cwd);
+  const requests = await collectRequests(options.cwd);
   if (options.json) {
     envelope(deps, true, { requests });
     return { exitCode: 0 };
@@ -1915,21 +2135,331 @@ async function runRequests(options, deps) {
     if (request.target !== null) deps.log(`    ${request.target}`);
   }
   deps.log("");
-  deps.log("Run leglas requests --json to get the full prompts, then --clear when done.");
+  deps.log("Run npx leglas requests --json to get the full prompts, then --clear when done.");
   return { exitCode: 0 };
 }
 
+// src/show.ts
+function describe(preview) {
+  return {
+    title: preview.title,
+    url: preview.url,
+    note: preview.note ?? null,
+    tags: preview.tags,
+    basedOn: preview.basedOn ?? null,
+    branch: preview.branch ?? null,
+    file: preview.file ?? null,
+    local: preview.local === true,
+    // A file preview names its own source. Everything else is decoded from the
+    // URL, and a URL outside the convention yields nothing rather than a path
+    // that looks authoritative and is not there.
+    target: preview.file ?? targetFor(preview.url)
+  };
+}
+function planShow({ title, previews, requests }) {
+  const found = previews.find((preview) => preview.title === title);
+  if (!found) {
+    return {
+      ok: false,
+      error: `No direction called ${JSON.stringify(title)}. Run npx leglas list to see them.`
+    };
+  }
+  const variants = previews.filter((preview) => preview.basedOn === title).map(describe);
+  const variantTitles = new Set(variants.map((variant) => variant.title));
+  return {
+    ok: true,
+    direction: describe(found),
+    variants,
+    // Its own variants are already listed in full, so they are not repeated
+    // here; this is the rest of the comparison.
+    comparedWith: previews.map((preview) => preview.title).filter((other) => other !== title && !variantTitles.has(other)),
+    requests: requests.filter((request) => request.title === title).map((request) => ({
+      id: request.id,
+      intent: request.intent,
+      target: request.target,
+      prompt: request.prompt,
+      status: request.status
+    }))
+  };
+}
+
+// src/run-show.ts
+async function runShow(options, deps) {
+  const loaded = await loadConfig(options.cwd);
+  const local = await readLocalPreviews(options.cwd);
+  const requests = await readRequests(options.cwd);
+  const previews = [
+    ...(loaded.config?.previews ?? []).map((preview) => ({ ...preview, local: false })),
+    ...local.previews
+  ];
+  const resolved = resolveOrExplain(
+    options.title,
+    previews.map((preview) => preview.title),
+    await readRenames(options.cwd)
+  );
+  if (!resolved.ok) {
+    if (options.json) deps.log(JSON.stringify({ ok: false, error: resolved.error }));
+    else deps.error(resolved.error);
+    return { exitCode: 1 };
+  }
+  const plan = planShow({ title: resolved.title, previews, requests });
+  if (!plan.ok) {
+    if (options.json) deps.log(JSON.stringify({ ok: false, error: plan.error }));
+    else deps.error(plan.error);
+    return { exitCode: 1 };
+  }
+  if (options.json) {
+    deps.log(
+      JSON.stringify({
+        ok: true,
+        direction: plan.direction,
+        variants: plan.variants,
+        comparedWith: plan.comparedWith,
+        requests: plan.requests
+      })
+    );
+    return { exitCode: 0 };
+  }
+  const { direction } = plan;
+  deps.log(`  ${direction.title}${direction.local ? "  (local)" : ""}`);
+  if (direction.note !== null) deps.log(`  ${direction.note}`);
+  deps.log("");
+  if (direction.target !== null) deps.log(`  file        ${direction.target}`);
+  if (direction.branch !== null) deps.log(`  branch      ${direction.branch}`);
+  deps.log(`  url         ${direction.url}`);
+  if (direction.tags.length > 0) deps.log(`  tags        ${direction.tags.join(", ")}`);
+  if (direction.basedOn !== null) deps.log(`  variant of  ${direction.basedOn}`);
+  if (plan.variants.length > 0) {
+    deps.log(`  variants    ${plan.variants.map((variant) => variant.title).join(", ")}`);
+  }
+  if (plan.comparedWith.length > 0) {
+    deps.log(`  against     ${plan.comparedWith.join(", ")}`);
+  }
+  if (plan.requests.length > 0) {
+    deps.log("");
+    deps.log(`  Pending, not yet done (${plan.requests.length}):`);
+    for (const request of plan.requests) deps.log(`    ${request.status}  ${request.intent}`);
+    deps.log("");
+    deps.log("  Run npx leglas requests --json for the full prompts.");
+  }
+  return { exitCode: 0 };
+}
+
+// src/run-watch.ts
+import { spawn as spawn2 } from "child_process";
+import { mkdir as mkdir6, readFile as readFile9, writeFile as writeFile8 } from "fs/promises";
+import { dirname as dirname7, join as join12 } from "path";
+
+// src/watch.ts
+var WATCH_PATH = ".leglas/watch.json";
+var PROMPT_TOKEN = "{prompt}";
+var EXAMPLE = `npx leglas watch --run "claude -p ${PROMPT_TOKEN}"`;
+function tokenize(template) {
+  const tokens = [];
+  let current = "";
+  let started = false;
+  let quote = null;
+  for (const character of template) {
+    if (quote !== null) {
+      if (character === quote) quote = null;
+      else current += character;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      started = true;
+      continue;
+    }
+    if (/\s/.test(character)) {
+      if (started) tokens.push(current);
+      current = "";
+      started = false;
+      continue;
+    }
+    current += character;
+    started = true;
+  }
+  if (quote !== null) {
+    return { ok: false, error: `The agent command has an unclosed ${quote} quote.` };
+  }
+  if (started) tokens.push(current);
+  return { ok: true, tokens };
+}
+function parseTemplate(raw) {
+  const tokenized = tokenize(raw);
+  if (!tokenized.ok) return tokenized;
+  const { tokens } = tokenized;
+  const [command, ...args] = tokens;
+  if (command === void 0) {
+    return { ok: false, error: `Watch needs an agent command, for example: ${EXAMPLE}` };
+  }
+  const placeholders = tokens.filter((token) => token === PROMPT_TOKEN).length;
+  if (placeholders === 0) {
+    return {
+      ok: false,
+      error: `The agent command needs ${PROMPT_TOKEN} as a word of its own, for example: ${EXAMPLE}`
+    };
+  }
+  if (placeholders > 1) {
+    return {
+      ok: false,
+      error: `The agent command takes ${PROMPT_TOKEN} once, for example: ${EXAMPLE}`
+    };
+  }
+  if (command === PROMPT_TOKEN) {
+    return {
+      ok: false,
+      error: `The agent command must name a program before ${PROMPT_TOKEN}, for example: ${EXAMPLE}`
+    };
+  }
+  return { ok: true, template: { command, args } };
+}
+function commandFor(template, prompt) {
+  return {
+    command: template.command,
+    args: template.args.map((argument) => argument === PROMPT_TOKEN ? prompt : argument)
+  };
+}
+function nextRequest(requests, failed) {
+  return requests.find((request) => request.status === "queued" && !failed.has(request.id)) ?? null;
+}
+
+// src/run-watch.ts
+var POLL_MS = 2e3;
+var HEARTBEAT_TIMEOUT_MS = 1e3;
+async function readSavedTemplate(cwd) {
+  try {
+    const raw = await readFile9(join12(cwd, WATCH_PATH), "utf8");
+    const parsed2 = JSON.parse(raw);
+    return typeof parsed2.run === "string" && parsed2.run !== "" ? parsed2.run : null;
+  } catch {
+    return null;
+  }
+}
+async function saveTemplate(cwd, run3) {
+  const path = join12(cwd, WATCH_PATH);
+  await mkdir6(dirname7(path), { recursive: true });
+  await writeFile8(path, `${JSON.stringify({ run: run3 }, null, 2)}
+`, "utf8");
+}
+function spawnAgent(command, args, cwd) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (outcome) => {
+      if (settled) return;
+      settled = true;
+      resolve(outcome);
+    };
+    const child = spawn2(command, args, { cwd, stdio: "inherit" });
+    child.on("error", (error) => settle({ ok: false, error: error.message }));
+    child.on(
+      "close",
+      (code, signal) => settle(
+        signal === null ? { ok: true, code: code ?? 0 } : { ok: false, error: `stopped by ${signal}` }
+      )
+    );
+  });
+}
+async function runWatch(options, deps) {
+  const saved = options.run === void 0 ? await readSavedTemplate(options.cwd) : null;
+  const raw = options.run ?? saved;
+  if (raw === null) {
+    deps.error(
+      'Watch needs an agent command the first time: npx leglas watch --run "claude -p {prompt}"'
+    );
+    return { exitCode: 1 };
+  }
+  const parsed2 = parseTemplate(raw);
+  if (!parsed2.ok) {
+    deps.error(parsed2.error);
+    return { exitCode: 1 };
+  }
+  const template = parsed2.template;
+  if (options.run !== void 0) await saveTemplate(options.cwd, raw).catch(() => {
+  });
+  const base = `http://localhost:${options.port ?? DEFAULT_PORT}`;
+  const heartbeat = async (watching) => {
+    try {
+      await fetch(`${base}${LEGLAS_PREFIX}/api/watch`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ watching }),
+        signal: AbortSignal.timeout(HEARTBEAT_TIMEOUT_MS)
+      });
+    } catch {
+    }
+  };
+  deps.log(`Watching for change requests. Each one runs: ${raw}`);
+  deps.log("Stop with Ctrl-C.");
+  const failed = /* @__PURE__ */ new Set();
+  let stopped = false;
+  let busy = false;
+  let inflight = null;
+  const handle = async (request) => {
+    deps.log("");
+    deps.log(`  ${request.title}: ${request.intent}`);
+    if (request.target !== null) deps.log(`    ${request.target}`);
+    await markPickedUp(options.cwd, request.id);
+    const { command, args } = commandFor(template, request.prompt);
+    const outcome = await spawnAgent(command, args, options.cwd);
+    if (outcome.ok && outcome.code === 0) {
+      await removeRequest(options.cwd, request.id);
+      deps.log(`  done    ${request.title}`);
+      return;
+    }
+    failed.add(request.id);
+    deps.error(
+      `  failed  ${request.title}: ${outcome.ok ? `${command} exited ${outcome.code}` : outcome.error}`
+    );
+    deps.error("  Left in the queue and not retried.");
+  };
+  const tick = async () => {
+    if (stopped) return;
+    void heartbeat(true);
+    if (busy) return;
+    busy = true;
+    try {
+      const request = nextRequest(await readRequests(options.cwd), failed);
+      if (request !== null && !stopped) {
+        inflight = handle(request);
+        await inflight;
+      }
+    } catch (error) {
+      deps.error(`  ! ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      inflight = null;
+      busy = false;
+    }
+  };
+  return new Promise((resolve) => {
+    const timer = setInterval(() => void tick(), POLL_MS);
+    const stop = () => {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      void Promise.resolve(inflight).catch(() => {
+      }).then(() => heartbeat(false)).then(() => resolve({ exitCode: 0 }));
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    options.signal?.addEventListener("abort", stop, { once: true });
+    void tick();
+  });
+}
+
 // src/run.ts
 import { existsSync as existsSync5 } from "fs";
 import { createRequire } from "module";
-import { basename as basename3, dirname as dirname6, join as join11, relative as relative2 } from "path";
+import { basename as basename3, dirname as dirname8, join as join13, relative as relative3 } from "path";
 import { fileURLToPath } from "url";
 function findShellDir() {
-  const bundled = join11(dirname6(fileURLToPath(import.meta.url)), "shell");
-  if (existsSync5(join11(bundled, "index.html"))) return bundled;
+  const bundled = join13(dirname8(fileURLToPath(import.meta.url)), "shell");
+  if (existsSync5(join13(bundled, "index.html"))) return bundled;
   try {
     const require2 = createRequire(import.meta.url);
-    return dirname6(require2.resolve("@leglas/shell/dist/index.html"));
+    return dirname8(require2.resolve("@leglas/shell/dist/index.html"));
   } catch {
     return null;
   }
@@ -1963,7 +2493,7 @@ async function run2(options, deps) {
   const fileMounts = /* @__PURE__ */ new Map();
   for (const preview of merged?.previews ?? []) {
     if (preview.file !== void 0) {
-      const absolute = join11(options.cwd, preview.file);
+      const absolute = join13(options.cwd, preview.file);
       if (!existsSync5(absolute)) {
         worktreeErrors.push(
           `"${preview.title}" names file ${preview.file}, which does not exist. The preview is skipped.`
@@ -1974,7 +2504,7 @@ async function run2(options, deps) {
       for (let suffix = 2; fileMounts.has(slug); suffix += 1) {
         slug = `${worktreeSlug(preview.title) || "file"}-${suffix}`;
       }
-      fileMounts.set(slug, dirname6(absolute));
+      fileMounts.set(slug, dirname8(absolute));
       previews.push({
         ...preview,
         url: `${FILES_PREFIX}/${slug}/${encodeURIComponent(basename3(absolute))}`
@@ -2035,7 +2565,7 @@ async function run2(options, deps) {
       })
     );
   } else {
-    const configLabel = loaded.path === null ? "no config file, previewing the app root" : relative2(options.cwd, loaded.path) || loaded.path;
+    const configLabel = loaded.path === null ? "no config file, previewing the app root" : relative3(options.cwd, loaded.path) || loaded.path;
     deps.log(`Leglas   ${url}`);
     deps.log(
       `app      ${devServer}${app !== null ? "  (started by Leglas)" : health.reachable ? "" : "  (not reachable)"}`
@@ -2079,11 +2609,13 @@ Usage
   leglas init                Prepare a project and teach its agents
   leglas [options]           Start the server and open the interface
   leglas new <surface>       Scaffold a branch point for a surface
-  leglas explore <surface>   Print distinct angles for an agent to build
+  leglas explore <surface>   Brief an agent's exploration of a surface
   leglas classify            Decide where a direction should live
   leglas add --title T --url U   Register a preview on this machine
   leglas list                Show every preview, shared and local
+  leglas show <title>        Everything Leglas knows about one direction
   leglas requests            Show change requests made from the interface
+  leglas watch --run "<cmd>" Hand each request to your agent as it arrives
   leglas keep <title> --to <path>  Keep a winner and end the exploration
 
 Options
@@ -2100,7 +2632,13 @@ Options for new
   --from <path>        Use an existing component as the baseline
 
 Options for explore
-  --count <n>          How many angles (default 3)
+  --count <n>          How many directions (default 3)
+  --based-on <title>     Variants of an existing direction instead of new ones
+
+Options for watch
+  --run <command>      Your agent, with {prompt} where the request goes, for
+                       example "claude -p {prompt}". Remembered after first use
+  --port <port>        Port Leglas itself is on (default: 4100)
 
 Options for classify
   --change <path>      A file the direction creates or wires up (repeatable)
@@ -2111,6 +2649,7 @@ Options for add
   --tag <text>         Repeatable
   --branch <name>      Back the preview with a checkout of this git branch
   --file <path>        Preview a plain HTML file served by Leglas itself
+  --based-on <title>   The direction this is a variant of; groups the family
 `;
 function version() {
   const require2 = createRequire2(import.meta.url);
@@ -2120,7 +2659,7 @@ function version() {
 async function openBrowser(url) {
   const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   try {
-    spawn2(command, [url], { detached: true, stdio: "ignore" }).unref();
+    spawn3(command, [url], { detached: true, stdio: "ignore" }).unref();
   } catch {
   }
 }
@@ -2185,7 +2724,7 @@ if (parsed.kind === "keep") {
 }
 if (parsed.kind === "explore") {
   const outcome = runExplore(
-    { surface: parsed.surface, count: parsed.count, json: parsed.json },
+    { surface: parsed.surface, count: parsed.count, basedOn: parsed.basedOn, json: parsed.json },
     { log: (line) => process.stdout.write(`${line}
 `) }
   );
@@ -2198,10 +2737,24 @@ if (parsed.kind === "requests") {
   );
   process.exit(outcome.exitCode);
 }
+if (parsed.kind === "watch") {
+  const outcome = await runWatch(
+    { run: parsed.run, port: parsed.port, cwd: process.cwd() },
+    previewDeps
+  );
+  process.exit(outcome.exitCode);
+}
 if (parsed.kind === "list") {
   const outcome = await runList({ json: parsed.json, cwd: process.cwd() }, previewDeps);
   process.exit(outcome.exitCode);
 }
+if (parsed.kind === "show") {
+  const outcome = await runShow(
+    { title: parsed.title, json: parsed.json, cwd: process.cwd() },
+    previewDeps
+  );
+  process.exit(outcome.exitCode);
+}
 if (parsed.kind === "new") {
   const outcome = await runNew(
     { surface: parsed.surface, print: parsed.print, json: parsed.json, from: parsed.from, cwd: process.cwd() },