leglas 0.2.0 → 0.3.0

package/README.md

@@ -52,7 +52,7 @@ and sessions that clean up after themselves.
 - Ask for changes without leaving the comparison: describe what you
   want on the direction you're looking at, and Leglas turns it into a
   precise request for your agent, file path included. Leave
-  `leglas watch --run "claude -p {prompt}"` running in another terminal
+  `npx leglas watch --run "claude -p {prompt}"` running in another terminal
   and your agent picks each request up as you send it. In Claude Code,
   the Leglas MCP server can also push each request straight into your
   open session as a channel event (channels are a research preview:
@@ -76,57 +76,81 @@ preview of your app root. Add a config file to compare more than one thing.
 
 It works with whatever you're building in. Leglas never imports or
 executes your framework, so the target can be Next, Vite, Remix,
-SvelteKit, Astro, or a folder of static files. Requires Node 24 or
-newer.
+SvelteKit, Astro, or a folder of static files.
+
+## Install
+
+There is nothing you have to install: `npx leglas` fetches the CLI on
+first use and starts from npm's cache after that, and every instruction
+Leglas writes for agents uses the same form, so a fresh clone works
+with no setup at all. Requires Node 24 or newer.
+
+Two optional upgrades:
+
+- `npm install -D leglas` pins the version in a project. Teammates and
+  CI get the same Leglas from their normal install, and `npx` resolves
+  the local copy from then on.
+- `npm install -g leglas` is for typing `leglas` without the prefix.
 
 ## Working with coding agents
 
-Run `leglas init` once. It writes a section into your project's
-`AGENTS.md`, creates a starter config, and gitignores Leglas's working
-directory. That section travels with the repo, so Claude Code, Cursor,
-Codex, or whatever you switch to next opens the project already knowing
-how to add design directions to it. Every command accepts `--json` and
-prints a single machine-readable envelope, so agents drive the same CLI
-you do.
+The fastest way in is the agent skill:
+
+```sh
+npx skills add FredAmartey/leglas
+```
+
+One install, and your agent recognises "give me a few directions for the
+pricing page" as a Leglas exploration in any project, including ones
+that have never seen Leglas. It sets the project up itself and gets to
+work.
+
+In a project, run `npx leglas init` once. It writes a section into your
+project's `AGENTS.md`, creates a starter config, and gitignores Leglas's
+working directory. That section travels with the repo, so Claude Code,
+Cursor, Codex, or whatever you switch to next opens the project already
+knowing how to add design directions to it. Every command accepts
+`--json` and prints a single machine-readable envelope, so agents drive
+the same CLI you do.
 
 The instructions center on one rule: add beside what exists, never
 rewrite it. Two directions that rewrite the same file cannot render from
 one server, and asking an agent to "make the hero calmer" tempts it to
 edit the hero. The supporting commands:
 
-- `leglas explore hero --count 6` briefs the exploration: what the set
+- `npx leglas explore hero --count 6` briefs the exploration: what the set
   is for, why it only works if the six genuinely disagree, and how each
   direction registers. Unbriefed, six requests come back as six variants
   of one idea. With `--based-on "Aurora"` the goal flips: six deliberate
   variants of a direction you already like, and drifting into a new
   direction is the failure. The designs themselves are the agent's;
   Leglas prescribes none.
-- `leglas new hero --from src/Hero.tsx` scaffolds a switcher under
+- `npx leglas new hero --from src/Hero.tsx` scaffolds a switcher under
   `.leglas/variants/hero/`. With `--from`, the baseline re-exports your
   real component, so you never compare against a stale copy. Leglas
   prints the one line to add in your component and does not edit it,
   because rewriting a file it does not understand is how a tool breaks a
   codebase. Scaffolded branch points return the fallback in production
   builds, so a committed one cannot expose an unreleased direction.
-- `leglas classify --change package.json --rewrite src/theme.css` answers
+- `npx leglas classify --change package.json --rewrite src/theme.css` answers
   where a direction should live before it is written. Changing
   dependencies, build configuration, or an existing file's behaviour
   cannot be additive, so those directions build on their own git branch
   and register with `leglas add --branch`. Everything else stays in-app,
   where switching is instant.
-- `leglas show "Aurora" --json` answers for one direction: its entry, the
+- `npx leglas show "Aurora" --json` answers for one direction: its entry, the
   source file behind it, the variants based on it, what it is being compared
   against, and anything still pending on it. Copying a direction from the
   rail hands over a block that ends in this command, so an agent given the
   block can go and get the rest.
-- `leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
+- `npx leglas keep "Aurora" --to src/components/hero.tsx` moves the winner
   into real source and ends the exploration.
 
 Asking for a change works from the interface too. Type what you want
 changed into the field under the rail (or press `R`) and Leglas composes a
 prompt naming the direction and the file behind it, copies it to your
 clipboard, and queues it. The direction it means is the one highlighted
-directly above the field. Your agent drains the queue with `leglas requests --json` and clears
+directly above the field. Your agent drains the queue with `npx leglas requests --json` and clears
 it with `--clear`. Leglas runs no model of its own; your agent already
 knows your conventions and your taste.
 
@@ -136,6 +160,9 @@ For agent hosts that cannot run shell commands, `leglas-mcp` exposes the
 same operations as MCP tools over stdio: `start`, `add`, `list`, `show`,
 `classify`, `explore`, `scaffold`, `keep`, `requests`, and `init`. Each
 tool calls exactly what the CLI calls and returns the same envelope.
+`watch` is the one command with no tool behind it: it is a loop that
+holds a terminal open, and on a host that speaks channels the server
+already pushes each request into the session as it arrives.
 
 ```sh
 claude mcp add leglas -- npx -y leglas-mcp
@@ -147,9 +174,34 @@ Or in `.mcp.json`:
 { "mcpServers": { "leglas": { "command": "npx", "args": ["-y", "leglas-mcp"] } } }
 ```
 
-The host's working directory names the project. The `start` tool boots
-the viewer and returns its URL, and anything it started stops when the
-session ends.
+The host's working directory names the project, the same contract as the
+CLI. A host that starts the server somewhere else is asked where the
+project is, over MCP roots. The `start` tool boots the viewer and returns
+its URL, and anything it started stops when the session ends.
+
+### As an Agent Plugin
+
+The repository is also an [Agent Plugin](https://agent-plugins.org), the
+open standard for shipping Agent Skills and MCP server configuration in
+one format. Clients that implement it install the skill and the server
+together, instead of the two steps above. It is a layout rather than a
+build: `plugin.json` and `mcp.json` at the root, the skill in
+`skills/leglas/`, nothing generated.
+
+An Agent Plugins client starts a plugin's server in the plugin's own
+install directory rather than the project, so on that path the working
+directory names a copy of Leglas and nothing else. The server therefore
+takes the project from the workspace the host declares over MCP roots,
+and the working directory only when it sits inside one. If a host offers
+neither, `LEGLAS_PROJECT_DIR` names the project outright; without it the
+tools report that there is no project rather than writing into a plugin
+cache. `mcp.json` passes `${PLUGIN_ROOT}` for exactly that check, and
+nothing else.
+
+The plugin's version covers the skill and the configuration, not the
+server it launches: `npx` fetches the current `leglas-mcp` the same way
+every `npx leglas` in these instructions fetches the current CLI, which
+keeps both faces of Leglas on one version in a project they share.
 
 ## Configuration
 

package/dist/bin.js

@@ -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 };
@@ -134,7 +134,7 @@ 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 };
@@ -209,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) {
@@ -259,7 +259,7 @@ 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, basedOn, json };
@@ -300,7 +300,7 @@ function parseArgs(argv) {
     if (title === void 0) {
       return {
         kind: "error",
-        message: 'leglas show needs a direction title, for example: leglas show "Aurora" --json'
+        message: 'leglas show needs a direction title, for example: npx leglas show "Aurora" --json'
       };
     }
     return { kind: "show", title, json };
@@ -522,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 });
@@ -983,7 +983,12 @@ async function removeRequest(cwd, id) {
   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
@@ -1022,7 +1027,7 @@ function resolveTitle(input, titles, renames) {
 import { createReadStream, existsSync as existsSync2, statSync } from "fs";
 import http2 from "http";
 import net3 from "net";
-import { extname, join as join6, 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;
@@ -1074,8 +1079,8 @@ function probe(target, timeoutMs = 1e3) {
   });
 }
 function serveFrom(res, dir, relativePath) {
-  const relative3 = normalize(relativePath).replace(/^(\.\.[/\\])+/, "");
-  const candidate = join6(dir, relative3);
+  const relative4 = normalize(relativePath).replace(/^(\.\.[/\\])+/, "");
+  const candidate = join6(dir, relative4);
   if (!candidate.startsWith(dir))
     return false;
   if (!existsSync2(candidate) || !statSync(candidate).isFile())
@@ -1088,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">
@@ -1136,12 +1168,17 @@ 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`) {
       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);
@@ -1149,13 +1186,13 @@ async function startServer(options) {
           project,
           devServer: target,
           previews: [...boot, ...fresh],
-          errors: configErrors
+          errors
         });
       }).catch(() => sendJson(res, 200, {
         project,
         devServer: target,
         previews: boot,
-        errors: configErrors
+        errors
       }));
     }
     if (path === `${LEGLAS_PREFIX}/api/request` && req.method === "POST") {
@@ -1229,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);
     }
@@ -1515,8 +1559,8 @@ The set exists to be chosen from, and the choice only means something if the dir
 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}".
 
 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 ? `  leglas add --title "<name>" --url "/?v-${slug}=<key>" --note "<the idea, one line>"` : `  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 \`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:
+  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:
 
 ${register}
 
@@ -1572,46 +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, adding
+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. Before building, make sure the interface is up. If \`leglas\` is not
-   already running, tell the user to run it, 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.
+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:
-   \`leglas add --title "Aurora" --url "/?v-<surface>=aurora" --note "One line on the idea."\`
+   \`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 \`leglas requests --json\`
+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 \`leglas watch --run "claude -p {prompt}"\` (any
+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.
@@ -1622,14 +1668,14 @@ 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. 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.
-- \`leglas list\` shows every direction, shared and local.
-- \`leglas show "<title>" --json\` answers for one of them: the file behind it,
+- \`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.
@@ -1639,7 +1685,7 @@ Useful to know:
 ${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",
@@ -1737,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);
@@ -1785,7 +1831,7 @@ function resolveOrExplain(input, titles, renames) {
   }
   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. leglas list shows every title.`
+    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.`
   };
 }
 
@@ -1935,7 +1981,7 @@ 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 };
 }
@@ -1964,7 +2010,7 @@ async function runAdd(options, deps) {
     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. leglas list shows what exists.`;
+      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 };
@@ -1997,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 {
@@ -2012,7 +2059,7 @@ async function runAdd(options, deps) {
     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 leglas list.");
+      deps.log("Local to this machine. Restart Leglas to see it, or run npx leglas list.");
     }
   }
   return { exitCode: 0 };
@@ -2047,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) {
@@ -2062,9 +2109,16 @@ 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 collectRequests(options.cwd);
@@ -2081,7 +2135,7 @@ 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 };
 }
 
@@ -2107,7 +2161,7 @@ function planShow({ title, previews, requests }) {
   if (!found) {
     return {
       ok: false,
-      error: `No direction called ${JSON.stringify(title)}. Run leglas list to see them.`
+      error: `No direction called ${JSON.stringify(title)}. Run npx leglas list to see them.`
     };
   }
   const variants = previews.filter((preview) => preview.basedOn === title).map(describe);
@@ -2186,7 +2240,7 @@ async function runShow(options, deps) {
     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 leglas requests --json for the full prompts.");
+    deps.log("  Run npx leglas requests --json for the full prompts.");
   }
   return { exitCode: 0 };
 }
@@ -2199,7 +2253,7 @@ import { dirname as dirname7, join as join12 } from "path";
 // src/watch.ts
 var WATCH_PATH = ".leglas/watch.json";
 var PROMPT_TOKEN = "{prompt}";
-var EXAMPLE = `leglas watch --run "claude -p ${PROMPT_TOKEN}"`;
+var EXAMPLE = `npx leglas watch --run "claude -p ${PROMPT_TOKEN}"`;
 function tokenize(template) {
   const tokens = [];
   let current = "";
@@ -2311,7 +2365,7 @@ async function runWatch(options, deps) {
   const raw = options.run ?? saved;
   if (raw === null) {
     deps.error(
-      'Watch needs an agent command the first time: leglas watch --run "claude -p {prompt}"'
+      'Watch needs an agent command the first time: npx leglas watch --run "claude -p {prompt}"'
     );
     return { exitCode: 1 };
   }
@@ -2398,7 +2452,7 @@ async function runWatch(options, deps) {
 // src/run.ts
 import { existsSync as existsSync5 } from "fs";
 import { createRequire } from "module";
-import { basename as basename3, dirname as dirname8, join as join13, 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 = join13(dirname8(fileURLToPath(import.meta.url)), "shell");
@@ -2511,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)"}`