lavish-axi 0.1.40 → 0.1.41

package/README.md

@@ -53,6 +53,7 @@ npx skills add kunchenguid/lavish-axi --skill lavish
 
 That is the entire setup - no npm install needed.
 The skill teaches your agent to run Lavish through `npx -y lavish-axi`, so the CLI comes along on demand.
+In restricted subprocess sandboxes, CI, or agent harnesses where `npx -y` exits opaquely, the skill also documents direct installed-copy fallbacks through the local or global npm install path.
 Its frontmatter also includes Hermes Agent metadata, so Hermes-compatible harnesses can categorize and surface it as a first-class productivity skill.
 This installs the public `lavish` skill.
 The repository also contains an internal `lavish-design` brand skill for maintainers; default `npx skills add ... --list` and skills.sh discovery hide it unless `INSTALL_INTERNAL_SKILLS=1` is set.
@@ -77,7 +78,7 @@ Lavish is an AXI, so any capable agent can run the CLI directly with nothing ins
 Just tell your agent:
 
 ```
-Use `npx lavish-axi` to write a product or technical plan for what we discussed.
+Use `npx -y lavish-axi` to write a product or technical plan for what we discussed.
 ```
 
 ### Session hook
@@ -159,8 +160,8 @@ pnpm link
 - **Keyboard shortcuts** - In the chrome composer, Enter sends queued prompts and Shift+Enter inserts a newline.
   In the annotation card, Enter queues the annotation, Shift+Enter inserts a newline, and Ctrl+Enter (Cmd+Enter on macOS) queues it and sends all queued prompts immediately.
   Cmd+I or Ctrl+I toggles between annotate and explore mode from either the browser chrome or the artifact iframe, including while focus is in a textarea or control.
-- **Agent presence** - The browser shows when no agent is listening, keeps queued feedback and fresh layout warnings for the next successful `lavish-axi poll` send even across reloads, and only blocks human sends while the agent is working on delivered feedback. The no-timeout poll writes an immediate stderr banner and periodic stderr heartbeats while stdout stays reserved for the final response; if the poll is interrupted or times out, re-run it because queued feedback is never lost.
-- **Session end etiquette** - Lavish tracks who ended a session: a human clicking **End session** (or **Send & End**) in the browser is a user-initiated end, while `lavish-axi end <html-file>` is agent-initiated.
+- **Agent presence** - The browser shows when no agent is listening, keeps queued feedback and fresh layout warnings for the next successful `lavish-axi poll` send even across reloads, and only blocks human sends while the agent is working on delivered feedback. The no-timeout poll writes an immediate stderr banner and periodic stderr heartbeats while stdout stays reserved for the final response; if the poll is interrupted or times out, re-run it because queued feedback is never lost. Codex-specific guidance keeps that poll attached to the active turn instead of hiding it in a background task, because completed background tasks may not resume the agent.
+- **Session end etiquette** - Lavish tracks who ended a session: a human clicking **End session** (or **Send & end session**) in the browser is a user-initiated end, while `lavish-axi end <html-file>` is agent-initiated.
   A plain `lavish-axi <html-file>` after a user-initiated end refuses to reopen the browser and returns guidance instead; pass `--reopen` only when the user asks for further review or something important needs their visual attention.
   Agent-initiated ends keep reopening normally, same as before.
   `lavish-axi poll`'s `ended` response and the `feedback` response for the final batch before an end both carry `next_step` guidance telling the agent to stop polling and deliver remaining updates in chat instead of reopening.
@@ -182,20 +183,20 @@ pnpm link
 
 ## CLI Reference
 
-| Command                         | Description                                                                                                                                                                                                                                                               |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lavish-axi`                    | Show current sessions and usage guidance.                                                                                                                                                                                                                                 |
-| `lavish-axi update`             | Check for or apply the latest npm release through the AXI SDK self-updater.                                                                                                                                                                                               |
-| `lavish-axi <html-file>`        | Open or resume a Lavish Editor session, with the open-time layout gate enabled by default. Refuses to reopen a session the user explicitly ended from the browser unless `--reopen` is passed.                                                                            |
-| `lavish-axi poll <html-file>`   | Long-poll until the user sends feedback, ends the session, or the browser reports fresh `layout_warnings`; leave no-timeout polls running, or re-run them if interrupted. On `status: ended`, stop polling and do not reopen uninvited.                                   |
-| `lavish-axi end <html-file>`    | End a session as the agent; unlike a user-initiated end from the browser, this still allows a plain reopen later.                                                                                                                                                         |
-| `lavish-axi export <html-file>` | Write a portable copy of the artifact: one HTML file with its local assets inlined, so it opens with no server and no sibling files. Remote CDN/font references are left as links.                                                                                        |
-| `lavish-axi share <html-file>`  | Publish the artifact (local assets inlined) to [ht-ml.app](https://ht-ml.app), a third-party host not part of Lavish, and print a visitable URL plus a secret update key; shares are public by default, and `--password` makes viewers enter the password before viewing. |
-| `lavish-axi stop`               | Shut down the background server.                                                                                                                                                                                                                                          |
-| `lavish-axi playbook [id]`      | List focused artifact guidance or show one playbook; agents must open each matching playbook before writing HTML.                                                                                                                                                         |
-| `lavish-axi design`             | Show agent-facing design guidance, including optional CDN and Mermaid snippets.                                                                                                                                                                                           |
-| `lavish-axi setup hooks`        | Install or repair optional SessionStart hooks for Claude Code, Codex, OpenCode, and GitHub Copilot CLI; restart the agent session afterward.                                                                                                                              |
-| `lavish-axi server`             | Run the local Lavish Editor server.                                                                                                                                                                                                                                       |
+| Command                         | Description                                                                                                                                                                                                                                                                                     |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lavish-axi`                    | Show current sessions and usage guidance.                                                                                                                                                                                                                                                       |
+| `lavish-axi update`             | Check for or apply the latest npm release through the AXI SDK self-updater.                                                                                                                                                                                                                     |
+| `lavish-axi <html-file>`        | Open or resume a Lavish Editor session, with the open-time layout gate enabled by default. Refuses to reopen a session the user explicitly ended from the browser unless `--reopen` is passed.                                                                                                  |
+| `lavish-axi poll <html-file>`   | Long-poll until the user sends feedback, ends the session, or the browser reports fresh `layout_warnings`; leave no-timeout polls running, or re-run them if interrupted. Codex guidance keeps polls attached to the active turn. On `status: ended`, stop polling and do not reopen uninvited. |
+| `lavish-axi end <html-file>`    | End a session as the agent; unlike a user-initiated end from the browser, this still allows a plain reopen later.                                                                                                                                                                               |
+| `lavish-axi export <html-file>` | Write a portable copy of the artifact: one HTML file with its local assets inlined, so it opens with no server and no sibling files. Remote CDN/font references are left as links.                                                                                                              |
+| `lavish-axi share <html-file>`  | Publish the artifact (local assets inlined) to [ht-ml.app](https://ht-ml.app), a third-party host not part of Lavish, and print a visitable URL plus a secret update key; shares are public by default, and `--password` makes viewers enter the password before viewing.                       |
+| `lavish-axi stop`               | Shut down the background server.                                                                                                                                                                                                                                                                |
+| `lavish-axi playbook [id]`      | List focused artifact guidance or show one playbook; agents must open each matching playbook before writing HTML.                                                                                                                                                                               |
+| `lavish-axi design`             | Show agent-facing design guidance, including optional CDN and Mermaid snippets.                                                                                                                                                                                                                 |
+| `lavish-axi setup hooks`        | Install or repair optional SessionStart hooks for Claude Code, Codex, OpenCode, and GitHub Copilot CLI; restart the agent session afterward.                                                                                                                                                    |
+| `lavish-axi server`             | Run the local Lavish Editor server.                                                                                                                                                                                                                                                             |
 
 Known playbook IDs: `diagram`, `table`, `comparison`, `plan`, `code`, `input`, `slides`.
 One artifact often combines several playbooks, such as a plan that includes a comparison and a diagram, so agents must match against each `use_when` trigger and open every matching playbook before writing HTML.

package/dist/chrome-client.js

@@ -938,6 +938,7 @@ async function persistWhiteboardScene(index, message) {
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       source_hash: String(message.sourceHash || ""),
+      text_metrics_version: Number(message.textMetricsVersion) || 0,
       scene: message.scene || null,
       baseline: message.baseline || null,
     }),

package/dist/cli.mjs

@@ -5476,10 +5476,11 @@ function whiteboardFeedbackPaths(stateDir2, key, index) {
     previewPath: path3.join(dir, `${Number(index)}.png`)
   };
 }
-async function saveWhiteboard(stateDir2, key, index, { sourceHash, scene, baseline = null }) {
+async function saveWhiteboard(stateDir2, key, index, { sourceHash, textMetricsVersion = 0, scene, baseline = null }) {
   assertValidRef(key, index);
   const record = {
     source_hash: String(sourceHash || ""),
+    text_metrics_version: Math.max(0, Math.floor(Number(textMetricsVersion) || 0)),
     updated_at: (/* @__PURE__ */ new Date()).toISOString(),
     scene: sanitizeWhiteboardScene(scene),
     baseline: baseline ?? null
@@ -5499,6 +5500,7 @@ async function loadWhiteboard(stateDir2, key, index) {
     if (!parsed || typeof parsed !== "object") return null;
     return {
       source_hash: String(parsed.source_hash || ""),
+      text_metrics_version: Math.max(0, Math.floor(Number(parsed.text_metrics_version) || 0)),
       updated_at: String(parsed.updated_at || ""),
       scene: parsed.scene ?? null,
       baseline: parsed.baseline ?? null
@@ -6330,6 +6332,7 @@ data: ${JSON.stringify({ state: computePresence(req.params.key, activePolls, del
       const body = req.body || {};
       await saveWhiteboard(whiteboardStateRoot, req.params.key, Number(req.params.index), {
         sourceHash: String(body.source_hash || body.sourceHash || ""),
+        textMetricsVersion: Number(body.text_metrics_version || body.textMetricsVersion) || 0,
         scene: body.scene ?? null,
         baseline: body.baseline ?? null
       });
@@ -6937,10 +6940,26 @@ function normalizePagePath(path7) {
 var COMMANDS = /* @__PURE__ */ new Set(["open", "poll", "end", "stop", "server", "playbook", "design", "setup", "export", "share"]);
 var RESERVED = new Set(RESERVED_COMMANDS);
 var DESCRIPTION = "Lavish Editor helps agents turn rich HTML artifacts into collaborative human review surfaces. Whenever you are about to give user a complex response that will be easier to understand via a rich / interactive page, consider using Lavish Editor. First generate an interactive HTML artifact according to user request, then run `lavish-axi <html-file>` so the user can visually review it, annotate elements or selected text, queue prompts, and send feedback back through `lavish-axi poll`.";
-var VERSION = "0.1.40";
+var POLL_BACKGROUND_TASK_GUIDANCE = "If your agent harness limits how long a foreground command may run, run the poll as a background task";
+var CODEX_POLL_BACKGROUND_TASK_GUIDANCE = "Codex detected: do not hide the poll in a background task. Completed background tasks may not resume Codex automatically, so keep the poll attached to the active turn.";
+var VERSION = "0.1.41";
+function detectInvokingAgent(env = process.env) {
+  return ["CODEX_SANDBOX", "CODEX_THREAD_ID"].some((key) => Object.hasOwn(env, key)) ? "codex" : "generic";
+}
+function pollExecutionGuidance({ waitForBackground = false, agent = "generic" } = {}) {
+  if (agent === "codex") {
+    return `${CODEX_POLL_BACKGROUND_TASK_GUIDANCE} If it gets killed or times out anyway, just re-run it - queued feedback is never lost.`;
+  }
+  if (agent === "static") {
+    return "If it gets killed or times out anyway, just re-run it - queued feedback is never lost.";
+  }
+  const backgroundGuidance = `${POLL_BACKGROUND_TASK_GUIDANCE}${waitForBackground ? " and wait for it to finish" : ""}; if it gets killed or times out anyway, just re-run it - queued feedback is never lost.`;
+  return backgroundGuidance;
+}
 async function run(argv) {
   await ensureStateDir();
   const normalizedArgv = normalizeArgv(argv);
+  const agent = detectInvokingAgent(process.env);
   const isTopLevelHelp = argv.length === 1 && argv[0] === "--help";
   const command = telemetryCommandName(argv);
   const telemetry = initDefaultTelemetry({
@@ -6955,11 +6974,12 @@ async function run(argv) {
       description: DESCRIPTION,
       version: VERSION,
       argv: isTopLevelHelp ? [] : normalizedArgv,
-      topLevelHelp: TOP_LEVEL_HELP,
+      topLevelHelp: createTopLevelHelp({ agent }),
       home: async () => createHomeOutput({
         bin: process.argv[1] || "lavish-axi",
         sessions: isTopLevelHelp ? [] : await visibleSessions(),
-        includeSessions: !isTopLevelHelp
+        includeSessions: !isTopLevelHelp,
+        agent
       }),
       commands: {
         open: openCommand,
@@ -6973,7 +6993,7 @@ async function run(argv) {
         export: exportCommand,
         share: shareCommand
       },
-      getCommandHelp
+      getCommandHelp: (command2) => getCommandHelp(command2, { agent })
     });
     telemetry.track("command", { command, status: "success" });
   } catch (error) {
@@ -7008,7 +7028,7 @@ function telemetryCommandName(argv) {
   const normalized = normalizeArgv(argv);
   return normalized[0] && !normalized[0].startsWith("-") ? normalized[0] : "home";
 }
-function createHomeOutput({ bin, sessions, includeSessions = true }) {
+function createHomeOutput({ bin, sessions, includeSessions = true, agent = "generic" }) {
   return {
     bin: collapseHomeDirectory(bin, os2.homedir()),
     description: DESCRIPTION,
@@ -7032,7 +7052,7 @@ function createHomeOutput({ bin, sessions, includeSessions = true }) {
       "Run `lavish-axi <html-file>` to open or resume a Lavish Editor session. If the user explicitly ended the session from the browser, this refuses to reopen it and explains why instead of reopening uninvited - pass `--reopen` only when the user asks for further review or something important needs their visual attention",
       "Unless the user specifies another location, create HTML artifacts in the current working directory under `.lavish/`",
       "Lavish serves the html file through a local express.js server. If your html needs to reference other filesystem assets such as images, CSS, fonts, and local scripts, copy them into the same directory as the HTML file, then reference them with relative paths from that directory. Never prepend `/` to those asset paths - root paths won't work",
-      "Run `lavish-axi poll <html-file>` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost. When it reports the session ended, stop polling and do not reopen it uninvited - deliver remaining updates in this conversation instead",
+      `Run \`lavish-axi poll <html-file>\` to wait for user feedback or browser-reported layout_warnings. It long-polls and stays silent until the user sends feedback, ends the session, or the real browser reports fresh layout_warnings, so leave it running - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; if the poll says every current warning is persistent or low-severity, proceed with a note instead of looping. ${pollExecutionGuidance({ agent })} When it reports the session ended, stop polling and do not reopen it uninvited - deliver remaining updates in this conversation instead`,
       'Rendered Mermaid diagrams in `.mermaid` containers become embedded, editable Excalidraw whiteboards in the browser (click a diagram to unlock editing; a Fullscreen action opens it over the whole viewport) - flowchart, sequence, class, ER, and state diagrams convert to editable shapes; other types embed as an image to draw on. Scenes autosave locally; when a reload detects a changed Mermaid source, the reviewer explicitly chooses to re-convert and discard saved edits or keep editing the saved scene. Standalone and exported copies still render plain Mermaid. Queue feedback adds a prompt to the Conversation panel; when the user sends it, poll returns a tag "whiteboard" prompt carrying a bounded edit summary plus local scenePath (.excalidraw JSON) and previewPath (PNG) files - read the summary first, open the files only when needed, then apply the edits by updating the Mermaid source in the artifact (never try to write the scene back)',
       "Run `lavish-axi end <html-file>` to end a session as the agent - ending it this way still allows a plain reopen later. When the user ends it from the browser instead, a later `lavish-axi <html-file>` refuses to reopen it without `--reopen`",
       "Run `lavish-axi export <html-file> [--out <path>]` to write a portable copy of the artifact - one HTML file with its LOCAL assets inlined - so it opens with no Lavish server and no sibling files. Remote CDN/font references are left as links, so it needs network to render those. Users can also export from the browser chrome's overflow menu",
@@ -7060,10 +7080,10 @@ function createPlaybookOutput(args) {
   }
   return { playbook };
 }
-function createOpenOutput({ file, url, status }) {
+function createOpenOutput({ file, url, status, agent = "generic" }) {
   return {
     session: { file, url, status },
-    next_step: `Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file}\`. This command long-polls until the user sends feedback, ends the session, or the real browser reports layout_warnings from the in-iframe layout audit, and it stays silent the whole time - that is normal, never kill it. If layout_warnings arrive, follow the poll response's next_step: fix and re-check fresh error-severity overflow or clipped-text findings before involving the human, but persistent or low-severity warnings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use. If your harness limits how long a foreground command may run, run the poll as a background task and wait for it to finish; if the poll still gets killed or times out, just re-run it - queued feedback is never lost. After applying feedback, run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms to show your response in Lavish Editor and wait for more feedback. If the user ends the session, stop polling and do not reopen it by re-running \`lavish-axi ${file}\` unless the user asks for further review or something genuinely important needs their visual attention - deliver routine updates directly in this conversation instead. When reopening is warranted, run \`lavish-axi ${file} --reopen\`.`
+    next_step: `Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file}\`. This command long-polls until the user sends feedback, ends the session, or the real browser reports layout_warnings from the in-iframe layout audit, and it stays silent the whole time - that is normal, never kill it. If layout_warnings arrive, follow the poll response's next_step: fix and re-check fresh error-severity overflow or clipped-text findings before involving the human, but persistent or low-severity warnings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use. ${pollExecutionGuidance({ waitForBackground: true, agent })} After applying feedback, run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms to show your response in Lavish Editor and wait for more feedback. If the user ends the session, stop polling and do not reopen it by re-running \`lavish-axi ${file}\` unless the user asks for further review or something genuinely important needs their visual attention - deliver routine updates directly in this conversation instead. When reopening is warranted, run \`lavish-axi ${file} --reopen\`.`
   };
 }
 function createUserEndedOpenOutput({ file, url }) {
@@ -7094,7 +7114,12 @@ async function openCommand(args) {
       response.status = "ready";
     }
   }
-  return createOpenOutput({ file: absolute, url: response.url, status: response.status || "opened" });
+  return createOpenOutput({
+    file: absolute,
+    url: response.url,
+    status: response.status || "opened",
+    agent: detectInvokingAgent(process.env)
+  });
 }
 function shouldOpenBrowser(args, env) {
   return !args.includes("--no-open") && env.LAVISH_AXI_NO_OPEN !== "1";
@@ -7128,7 +7153,7 @@ ${pollInterruptedText(absolute)}
       retries: 3,
       retryDelayMs: 500
     });
-    return createPollOutput({ file: absolute, response });
+    return createPollOutput({ file: absolute, response, agent: detectInvokingAgent(process.env) });
   } finally {
     waitReporter?.stop();
     if (!timeoutMs) {
@@ -7165,7 +7190,7 @@ function startPollWaitReporter({
   timer.unref?.();
   return { stop: () => clearInterval(timer) };
 }
-function createPollOutput({ file, response }) {
+function createPollOutput({ file, response, agent = "generic" }) {
   if (response.status === "missing") {
     throw new AxiError("No active Lavish Editor session for this file", "NOT_FOUND", [
       `Run \`lavish-axi ${file}\` first`
@@ -7184,7 +7209,7 @@ function createPollOutput({ file, response }) {
       dom_snapshot: response.dom_snapshot || "",
       prompts: response.prompts || [],
       ...layoutWarnings.length > 0 ? { layout_warnings: layoutWarnings } : {},
-      next_step: createFeedbackNextStep(file, layoutWarnings, sessionEnded, endedBy, response.prompts || [])
+      next_step: createFeedbackNextStep(file, layoutWarnings, sessionEnded, endedBy, response.prompts || [], agent)
     };
   }
   if (response.status === "ended") {
@@ -7198,7 +7223,7 @@ function createPollOutput({ file, response }) {
     next_step: `No user feedback arrived before the optional timeout. Run \`lavish-axi poll ${file}\` without --timeout-ms to wait indefinitely - queued feedback is never lost, so re-running the poll is always safe.`
   };
 }
-function createFeedbackNextStep(file, layoutWarnings, sessionEnded, endedBy, prompts = []) {
+function createFeedbackNextStep(file, layoutWarnings, sessionEnded, endedBy, prompts = [], agent = "generic") {
   const count = layoutWarnings.length;
   const whiteboardNote = prompts.some((prompt) => prompt && prompt.tag === "whiteboard") ? `This feedback includes whiteboard edits (tag "whiteboard"): read the edit summary in the prompt text first, and only when it is not enough, open the target's scenePath (.excalidraw scene JSON) or previewPath (PNG) local files for detail. The artifact's Mermaid source stays authoritative - apply the edits by updating the Mermaid text in ${file} (Lavish live-reloads it); never try to write the .excalidraw scene back. ` : "";
   if (sessionEnded) {
@@ -7209,7 +7234,7 @@ function createFeedbackNextStep(file, layoutWarnings, sessionEnded, endedBy, pro
     return `${layoutNote}${whiteboardNote}This was the last feedback before the Lavish Editor session ended. Stop polling ${file}. Deliver any remaining updates directly in this conversation, or run \`lavish-axi ${file}\` to open a fresh session if the user needs further visual review.`;
   }
   const layoutPrefix = count > 0 ? layoutWarningsPrefix(file, layoutWarnings) : `Apply the requested changes to ${file}. `;
-  return `${layoutPrefix}${whiteboardNote}Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms unless the user ended the session. The poll waits silently until the user sends more feedback, ends the session, or reports fresh layout_warnings - never kill it. If your harness limits how long a foreground command may run, run the poll as a background task; if it still gets killed or times out, just re-run it - queued feedback is never lost.`;
+  return `${layoutPrefix}${whiteboardNote}Do not respond to the user just yet. Now you must run \`lavish-axi poll ${file} --agent-reply "<message for the user>"\` without --timeout-ms unless the user ended the session. The poll waits silently until the user sends more feedback, ends the session, or reports fresh layout_warnings - never kill it. ${pollExecutionGuidance({ agent })}`;
 }
 function layoutWarningsPrefix(file, layoutWarnings) {
   const count = layoutWarnings.length;
@@ -7749,10 +7774,11 @@ function isValueFlagToken(arg, flags) {
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function getCommandHelp(command) {
-  return COMMAND_HELP[command] || null;
+function getCommandHelp(command, { agent = "generic" } = {}) {
+  return createCommandHelp({ agent })[command] || null;
 }
-var TOP_LEVEL_HELP = `lavish-axi - Lavish Editor AXI
+function createTopLevelHelp({ agent = "generic" } = {}) {
+  return `lavish-axi - Lavish Editor AXI
 
 Usage:
   lavish-axi
@@ -7768,35 +7794,37 @@ Usage:
 
 ${DESIGN_SYSTEM_HINT}
 
-Note: poll long-polls indefinitely by default until the user sends feedback, ends the session, or the browser reports fresh layout_warnings, staying silent while it waits - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. If your harness limits how long a foreground command may run, run the poll as a background task; if it gets killed or times out anyway, just re-run it - queued feedback is never lost. When the user ends a session from the browser, stop polling and do not reopen it uninvited - pass --reopen to <html-file> only when the user asks for further review or something important needs their visual attention.
+Note: poll long-polls indefinitely by default until the user sends feedback, ends the session, or the browser reports fresh layout_warnings, staying silent while it waits - never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. ${pollExecutionGuidance({ agent })} When the user ends a session from the browser, stop polling and do not reopen it uninvited - pass --reopen to <html-file> only when the user asks for further review or something important needs their visual attention.
 
 `;
-var COMMAND_HELP = {
-  open: `Usage: lavish-axi <html-file> [--no-open] [--no-gate] [--reopen]
+}
+function createCommandHelp({ agent = "generic" } = {}) {
+  return {
+    open: `Usage: lavish-axi <html-file> [--no-open] [--no-gate] [--reopen]
 
 Open or resume a Lavish Editor review session for an HTML artifact. Use --no-open when you need to ensure the server/session exists without opening another browser window. Use --no-gate to skip the open-time layout curtain for this browser open. If the user explicitly ended the session from the browser, this refuses to reopen it and returns guidance instead - pass --reopen to force it open when the user asks for further review or something important needs their visual attention. Sessions ended by the agent (\`lavish-axi end\`) reopen normally without the flag.
 `,
-  poll: `Usage: lavish-axi poll <html-file> [--agent-reply "..."]
+    poll: `Usage: lavish-axi poll <html-file> [--agent-reply "..."]
 
-This command long-polls indefinitely for queued user prompts and browser-reported layout_warnings, then returns them to the agent. It stays silent while it waits - that is normal, never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. If your harness limits how long a foreground command may run, run the poll as a background task and wait for it to finish; if it still gets killed or times out, just re-run it - queued feedback is never lost. Use --agent-reply after applying prior feedback to display your response in Lavish Editor before waiting again. When status is ended, stop polling and do not reopen the session uninvited - deliver remaining updates directly in this conversation instead.
+This command long-polls indefinitely for queued user prompts and browser-reported layout_warnings, then returns them to the agent. It stays silent while it waits - that is normal, never kill it. Fix and re-check fresh error-severity layout_warnings before involving the human; persistent or low-severity findings may be surfaced with a note when the cause is not obvious. Do not pass --timeout-ms during normal agent use; it is for tests and debugging only. ${pollExecutionGuidance({ waitForBackground: true, agent })} Use --agent-reply after applying prior feedback to display your response in Lavish Editor before waiting again. When status is ended, stop polling and do not reopen the session uninvited - deliver remaining updates directly in this conversation instead.
 `,
-  end: `Usage: lavish-axi end <html-file>
+    end: `Usage: lavish-axi end <html-file>
 
 End a Lavish Editor session as the agent. A session ended this way still reopens normally on the next \`lavish-axi <html-file>\`, unlike a user ending it from the browser, which requires --reopen.
 `,
-  export: `Usage: lavish-axi export <html-file> [--out <path>]
+    export: `Usage: lavish-axi export <html-file> [--out <path>]
 
 Write a portable copy of an artifact: one HTML file with its LOCAL assets inlined (relative-path stylesheets, scripts, images, and fonts become inline <style>/<script> blocks and data URIs). Remote CDN/font references (https URLs) are left as links for the browser to load, so the file needs network to render those. Lavish makes no outbound requests - it only reads local files, confined to the artifact's directory. Defaults to writing <name>.export.html next to the source; pass --out to choose a path. The Lavish annotation SDK is never included in an export.
 `,
-  share: `Usage: lavish-axi share <html-file> [--password <pw>] [--token <t>]
+    share: `Usage: lavish-axi share <html-file> [--password <pw>] [--token <t>]
 
 Publish the artifact on ht-ml.app (https://ht-ml.app), a third-party hosting service not part of Lavish, and print a visitable URL. Shares are PUBLIC by default: anyone with the link can open the page, and it may be indexed or scraped. Pass --password to publish a PRIVATE password-protected page; viewers must supply the password to view. Builds the same local-inlined HTML as 'export' (local assets inlined; remote CDN/font URLs left as links and are not blocked by CSP on ht-ml.app, but still load over the viewer's network), then POSTs it to ht-ml.app's /v1 API. Creating a site needs no account or API key. The response includes the url plus a secret update_key (shown once) for updating or deleting the page later. Set LAVISH_AXI_HTML_APP_TOKEN (or pass --token) to attach an optional bearer token; it is never required. The annotation SDK is never included.
 `,
-  stop: `Usage: lavish-axi stop [--port <port>]
+    stop: `Usage: lavish-axi stop [--port <port>]
 
 Shut down the background Lavish Editor server. The server also stops itself when no browser or poll has been connected for a while (LAVISH_AXI_IDLE_TIMEOUT_MS, default 30m) and immediately when the last session ends with nothing connected.
 `,
-  playbook: `Usage: lavish-axi playbook [playbook_id]
+    playbook: `Usage: lavish-axi playbook [playbook_id]
 
 List focused artifact guidance playbooks, or show one playbook by ID. Known IDs: diagram, table, comparison, plan, code, input, slides.
 
@@ -7807,21 +7835,22 @@ Examples:
   lavish-axi playbook diagram
   lavish-axi playbook input
 `,
-  design: `Usage: lavish-axi design
+    design: `Usage: lavish-axi design
 
 Show a copy-pasteable CDN snippet for Tailwind CSS browser runtime v4 + DaisyUI v5 + themes, Mermaid diagram tooling, a content-to-playbook router, an optional layout safety CSS snippet, plus technical reference for DaisyUI components. ${PLAYBOOK_ROUTER_HELP} Lavish artifacts stay portable HTML. This CDN snippet is the design fallback, not the default: inspect the subject project before falling back, and paste the layout safety CSS only when useful for dense nested grid/flex layouts, badges, wide fonts, or local media. ${DESIGN_PRIORITY_RULE}
 `,
-  setup: `Usage: lavish-axi setup hooks
+    setup: `Usage: lavish-axi setup hooks
 
 Install or repair agent SessionStart hooks for lavish-axi ambient context in Claude Code, Codex, OpenCode, and GitHub Copilot CLI. Restart your agent session afterward to receive the context.
 `,
-  server: `Usage: lavish-axi server [--port 4387] [--verbose]
+    server: `Usage: lavish-axi server [--port 4387] [--verbose]
 
 Run the local Lavish Editor server. Pass --verbose (or set LAVISH_AXI_DEBUG=1) to log session and watcher events to stderr. Detached server output is appended to ~/.lavish-axi/server.log, or LAVISH_AXI_STATE_DIR/server.log when set, for startup and crash diagnostics.
 
 LAVISH_AXI_HOST sets the bind address (default 127.0.0.1; a wildcard 0.0.0.0 or :: binds every interface). Binding beyond loopback exposes an unauthenticated server that can read and serve arbitrary local files to anything that can reach it, so only do so on a trusted network. LAVISH_AXI_LINK_HOST sets the hostname written into generated session links (default: the bind address, or loopback when bound to a wildcard). LAVISH_AXI_NO_OPEN=1 (or --no-open) suppresses the local browser launch.
 `
-};
+  };
+}
 
 // bin/lavish-axi.js
 await run(process.argv.slice(2));