imprint-mcp 0.3.0 → 0.3.1

package/README.md

@@ -29,6 +29,24 @@ imprint teach southwest --url https://www.southwest.com
 
 A browser opens. You drive the workflow and narrate what you're doing. Imprint records every request and interaction, then compiles a deterministic **MCP tool** your agent can call forever.
 
+Want to try a finished MCP before recording anything?
+
+```bash
+imprint install google-flights --source examples --platform claude-desktop
+```
+
+That registers the checked-in Google Flights example as an MCP server in your client. Swap `claude-desktop` for `claude-code`, `codex`, `openclaw`, or `hermes`, or add `--print` to see the config without changing anything.
+
+On a Hermes agent or Docker host, register the examples directly into Hermes:
+
+```bash
+for site in google-flights google-hotels southwest discoverandgo echo; do
+  imprint install "$site" --source examples --platform hermes --no-interactive
+done
+```
+
+When `HERMES_HOME` is set, Imprint writes Hermes MCP entries to `$HERMES_HOME/config.yaml`; outside Hermes it uses `~/.hermes/config.yaml`. For browser-backed MCPs, `imprint install` also installs Playwright Chromium into `$HERMES_HOME/.cache/ms-playwright` and writes `PLAYWRIGHT_BROWSERS_PATH` into the MCP config so Hermes can find it. Use `--skip-browser-install` only for offline builds where you preinstall the browser yourself. In a fresh Linux image that is missing browser system libraries, install those during image build with `bunx playwright install --with-deps chromium`.
+
 ---
 
 ## See It in Action
@@ -118,7 +136,7 @@ bun install && bun link
 
 <br>
 
-**Browser commands** (`teach`, `record`, `login`, `playbook`) need Playwright's Chromium:
+**Browser commands** (`teach`, `record`, `login`, `playbook`) and browser-backed `imprint install` targets auto-install Playwright Chromium when it is missing. For offline CI or prebuilt Linux images where you pass `--skip-browser-install`, preinstall it ahead of time:
 
 ```bash
 bunx playwright install chromium
@@ -207,6 +225,21 @@ Install any example into your MCP client:
 imprint install google-flights --source examples --platform claude-desktop
 ```
 
+Examples are real generated MCPs, not handwritten SDK samples. `imprint install <site> --source examples` points the MCP server at this repo's `examples/` directory with `IMPRINT_HOME`, ensures Playwright Chromium for browser-backed tools, and lets your client list and call the checked-in tools immediately:
+
+```bash
+imprint install google-hotels --source examples --platform codex
+imprint install southwest --source examples --platform claude-code
+imprint install echo --source examples --platform claude-desktop --print
+```
+
+For your own generated tools, leave off `--source examples`:
+
+```bash
+imprint install mysite --platform claude-code
+imprint install mysite --platform codex
+```
+
 ---
 
 ## CLI Reference
@@ -227,7 +260,14 @@ imprint <command> --help    # per-command options
 
 ## Sharing Skills
 
-Teach on your laptop, ship to a remote agent. Skill folders contain **zero plaintext credentials** — only `${credential.NAME}` placeholders and a manifest listing what the receiver must provision.
+Teach on your laptop, ship to a remote agent. Generated MCP folders contain the portable tool artifacts: `workflow.json`, `playbook.yaml`, `index.ts`, optional shared modules, and cron/backend metadata. Copy `~/.imprint/<site>` into the receiver's `~/.imprint/<site>` or commit it to a private repo, install Imprint there, then register it:
+
+```bash
+bun install -g imprint-mcp
+imprint install mysite --platform claude-code
+```
+
+Credentials stay separate. Skill folders contain **zero plaintext credentials** — only `${credential.NAME}` placeholders and a manifest listing what the receiver must provision.
 
 ```bash
 # Export (encrypted with libsodium + argon2id)

package/examples/google-flights/get_flight_calendar_prices/index.ts

@@ -75,7 +75,7 @@ const WORKFLOW: Workflow = {
       {
         "name": "f_sid",
         "required": false,
-        "capability": "ordinary_http",
+        "capability": "browser_bootstrap",
         "source": "html_regex",
         "pattern": "\"FdrFJe\":\"([^\"]+)\"",
         "group": 1
@@ -83,7 +83,7 @@ const WORKFLOW: Workflow = {
       {
         "name": "bl",
         "required": false,
-        "capability": "ordinary_http",
+        "capability": "browser_bootstrap",
         "source": "html_regex",
         "pattern": "\"cfb2h\":\"([^\"]+)\"",
         "group": 1

package/examples/google-flights/get_flight_calendar_prices/workflow.json

@@ -44,14 +44,16 @@
         "name": "f_sid",
         "pattern": "\"FdrFJe\":\"([^\"]+)\"",
         "group": 1,
-        "required": false
+        "required": false,
+        "capability": "browser_bootstrap"
       },
       {
         "source": "html_regex",
         "name": "bl",
         "pattern": "\"cfb2h\":\"([^\"]+)\"",
         "group": 1,
-        "required": false
+        "required": false,
+        "capability": "browser_bootstrap"
       }
     ]
   },

package/examples/southwest/README.md

@@ -8,13 +8,14 @@
 - **`probe-backends` skipping the futile rung.** The cached `backends.json` orders the ladder `stealth-fetch → playbook` so cron doesn't burn 200ms on a fetch attempt every tick.
 - **`notifyWhen: price_below`** pushing only on real drops, with the `pricePath` extracting from real Southwest response shape.
 - **The fresh-UUID header trick** — Southwest rejects stale `X-User-Experience-ID`; stealth-fetch regenerates per call.
+- **Public bootstrap config capture.** The workflow fetches Southwest's public bootstrap `data.js` and captures the current `api-keys.prod` value, so installed examples do not require a `SOUTHWEST_API_KEY` environment variable.
 - **Multi-path `pricePath`** — `cron.json`'s notifyWhen lists both the raw API shape (when stealth-fetch wins) and the playbook's reshaped output, so the push fires regardless of which backend produced the result.
 
 ## Run it
 
 ```bash
-# One-time setup (if you haven't already)
-bunx playwright install chromium
+# One-time setup: registers the example MCP and installs Playwright Chromium if missing
+imprint install southwest --source examples --platform claude-desktop
 
 # Run a single tick (verifies everything still works)
 imprint cron southwest --once

package/examples/southwest/search_southwest_flights/index.ts

@@ -55,13 +55,30 @@ const WORKFLOW: Workflow = {
     }
   ],
   "requests": [
+    {
+      "method": "GET",
+      "url": "https://www.southwest.com/swa-ui/bootstrap/landing-home-page-v2/1/data.js",
+      "headers": {
+        "Accept": "application/javascript, text/javascript, */*; q=0.01"
+      },
+      "captures": [
+        {
+          "name": "southwest_api_key",
+          "source": "text_regex",
+          "pattern": "\"swa-bootstrap-landing-home-page-v2/api-keys\":\\[function\\(require,module,exports\\)\\{\\s*module\\.exports = \\{[^}]*\"prod\":\"([^\"]+)\"",
+          "group": 1,
+          "required": true,
+          "capability": "ordinary_http"
+        }
+      ]
+    },
     {
       "method": "POST",
       "url": "https://www.southwest.com/api/air-booking/v1/air-booking/page/air/booking/shopping",
       "headers": {
         "Content-Type": "application/json",
         "Accept": "application/json, text/javascript, */*; q=0.01",
-        "X-API-Key": "${env.SOUTHWEST_API_KEY}",
+        "X-API-Key": "${state.southwest_api_key}",
         "X-App-ID": "air-booking",
         "X-Channel-ID": "southwest"
       },

package/examples/southwest/search_southwest_flights/workflow.json

@@ -37,13 +37,30 @@
     }
   ],
   "requests": [
+    {
+      "method": "GET",
+      "url": "https://www.southwest.com/swa-ui/bootstrap/landing-home-page-v2/1/data.js",
+      "headers": {
+        "Accept": "application/javascript, text/javascript, */*; q=0.01"
+      },
+      "captures": [
+        {
+          "name": "southwest_api_key",
+          "source": "text_regex",
+          "pattern": "\"swa-bootstrap-landing-home-page-v2/api-keys\":\\[function\\(require,module,exports\\)\\{\\s*module\\.exports = \\{[^}]*\"prod\":\"([^\"]+)\"",
+          "group": 1,
+          "required": true,
+          "capability": "ordinary_http"
+        }
+      ]
+    },
     {
       "method": "POST",
       "url": "https://www.southwest.com/api/air-booking/v1/air-booking/page/air/booking/shopping",
       "headers": {
         "Content-Type": "application/json",
         "Accept": "application/json, text/javascript, */*; q=0.01",
-        "X-API-Key": "${env.SOUTHWEST_API_KEY}",
+        "X-API-Key": "${state.southwest_api_key}",
         "X-App-ID": "air-booking",
         "X-Channel-ID": "southwest"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Teach an AI agent how to use any website. Once. Records a real browser session + narration; generates a deterministic MCP tool plus a DOM-replay playbook fallback.",
   "type": "module",
   "exports": {

package/src/cli.ts

@@ -238,7 +238,7 @@ export const VERB_HELP: Record<string, VerbHelp> = {
     summary:
       'Install an already-emitted MCP server into Claude Code, Codex, Claude Desktop, OpenClaw, or Hermes.',
     usage: [
-      'imprint install [<site>] [--platform <name>] [--source local|examples] [--print] [--no-interactive]',
+      'imprint install [<site>] [--platform <name>] [--source local|examples] [--print] [--no-interactive] [--skip-browser-install]',
     ],
     flags: [
       {
@@ -257,6 +257,10 @@ export const VERB_HELP: Record<string, VerbHelp> = {
         name: '--no-interactive',
         description: 'Do not prompt; requires <site> and --platform.',
       },
+      {
+        name: '--skip-browser-install',
+        description: 'Do not auto-install Playwright Chromium for browser-backed tools.',
+      },
     ],
     example: 'imprint install google-flights --source examples --platform claude-desktop',
   },
@@ -822,6 +826,7 @@ async function main(argv: string[]): Promise<number> {
           source: { type: 'string' },
           print: { type: 'boolean' },
           'no-interactive': { type: 'boolean' },
+          'skip-browser-install': { type: 'boolean' },
         },
         allowPositionals: false,
       });
@@ -850,6 +855,7 @@ async function main(argv: string[]): Promise<number> {
             source: values.source as (typeof sources)[number] | undefined,
             print: values.print,
             noInteractive: values['no-interactive'],
+            skipBrowserInstall: values['skip-browser-install'],
           });
       console.log(`[imprint] ${result.message}`);
       if ('source' in result)

package/src/imprint/cdp-browser-fetch.ts

@@ -283,7 +283,10 @@ export function createCdpBrowserFetch(opts: CdpBrowserFetchOptions): CdpBrowserF
           throw new Error('navigate timeout');
         }),
       ]);
-      await Page.loadEventFired().catch(() => {});
+      await Promise.race([
+        Page.loadEventFired(),
+        sleep(Math.min(abckWaitMs, 5000)).then(() => undefined),
+      ]).catch(() => {});
     } catch (err) {
       log(`navigation issue (continuing): ${err instanceof Error ? err.message : String(err)}`);
     }

package/src/imprint/chromium.ts

@@ -2,11 +2,20 @@
  *  bundled Chromium (unmanaged) over system Chrome (corporate policy
  *  often blocks --remote-debugging-port). $CHROMIUM_PATH overrides. */
 
-import { type ChildProcess, spawn } from 'node:child_process';
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { type ChildProcess, spawnSync as nodeSpawnSync, spawn } from 'node:child_process';
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
 import { createServer } from 'node:net';
 import { homedir, tmpdir } from 'node:os';
-import { join as pathJoin } from 'node:path';
+import { dirname as pathDirname, join as pathJoin } from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { isDebug } from './log.ts';
 
@@ -62,6 +71,13 @@ export function chromeProxyArg(proxy: string): string | null {
   return /^[\w.-]+:\d+$/.test(proxy) ? proxy : null;
 }
 
+export function shouldDisableChromiumSandbox(): boolean {
+  const override = process.env.IMPRINT_CHROMIUM_NO_SANDBOX?.trim().toLowerCase();
+  if (override === '1' || override === 'true' || override === 'yes') return true;
+  if (override === '0' || override === 'false' || override === 'no') return false;
+  return process.platform === 'linux' && existsSync('/.dockerenv');
+}
+
 interface LaunchedChromium {
   process: ChildProcess;
   port: number;
@@ -77,14 +93,36 @@ const LINUX_CANDIDATES = [
   '/usr/bin/chromium',
   '/usr/bin/chromium-browser',
 ];
+const require = createRequire(import.meta.url);
+
+export function defaultPlaywrightBrowsersPath(): string | undefined {
+  const hermesHome = process.env.HERMES_HOME?.trim();
+  if (hermesHome) return pathJoin(hermesHome, '.cache', 'ms-playwright');
+  const explicit = process.env.PLAYWRIGHT_BROWSERS_PATH?.trim();
+  if (explicit) return explicit;
+  return undefined;
+}
+
+function playwrightInstallEnv(): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  const browsersPath = defaultPlaywrightBrowsersPath();
+  if (browsersPath) env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  return env;
+}
+
+function playwrightChromiumCacheRoots(): string[] {
+  const roots = [
+    defaultPlaywrightBrowsersPath(),
+    pathJoin(homedir(), 'Library/Caches/ms-playwright'),
+    pathJoin(homedir(), '.cache/ms-playwright'),
+  ].filter((root): root is string => Boolean(root));
+  return [...new Set(roots)];
+}
 
 /** Find Playwright's "Google Chrome for Testing" — newest version wins
  *  if multiple are installed. */
 function findPlaywrightChromium(): string | null {
-  const cacheRoots = [
-    pathJoin(homedir(), 'Library/Caches/ms-playwright'),
-    pathJoin(homedir(), '.cache/ms-playwright'),
-  ];
+  const cacheRoots = playwrightChromiumCacheRoots();
   for (const root of cacheRoots) {
     if (!existsSync(root)) continue;
     let dirs: string[];
@@ -122,6 +160,7 @@ function findPlaywrightChromium(): string | null {
           'Google Chrome for Testing',
         ),
         // Linux layout
+        pathJoin(root, dir, 'chrome-linux64', 'chrome'),
         pathJoin(root, dir, 'chrome-linux', 'chrome'),
       ];
       for (const c of candidates) {
@@ -136,7 +175,236 @@ function findPlaywrightChromium(): string | null {
   return null;
 }
 
+function playwrightInstallCommand(): string[] {
+  const playwrightCli = resolvePlaywrightCli();
+  if (playwrightCli) return ['node', playwrightCli, 'install', 'chromium'];
+  if (process.versions.bun) return [process.execPath, 'x', 'playwright', 'install', 'chromium'];
+  return ['bunx', 'playwright', 'install', 'chromium'];
+}
+
+function resolvePlaywrightCli(): string | null {
+  try {
+    const packageJson = require.resolve('playwright/package.json');
+    const cli = pathJoin(pathDirname(packageJson), 'cli.js');
+    return existsSync(cli) ? cli : null;
+  } catch {
+    return null;
+  }
+}
+
+function quoteShellArg(value: string): string {
+  if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function commandText(command: string[], env: NodeJS.ProcessEnv): string {
+  const prefix = env.PLAYWRIGHT_BROWSERS_PATH
+    ? `PLAYWRIGHT_BROWSERS_PATH=${quoteShellArg(env.PLAYWRIGHT_BROWSERS_PATH)} `
+    : '';
+  return `${prefix}${command.map(quoteShellArg).join(' ')}`;
+}
+
+interface InstallerResult {
+  exitCode: number | null;
+  stdout?: string;
+  stderr?: string;
+  signal?: NodeJS.Signals | null;
+  error?: string;
+  timedOut?: boolean;
+  timeoutMs?: number;
+  logPath?: string;
+}
+
+type ChromiumInstaller = (command: string[], env: NodeJS.ProcessEnv) => InstallerResult;
+
+let chromiumInstallerForTest: ChromiumInstaller | null = null;
+let chromiumFinderForTest: (() => string | null) | null = null;
+let verifiedChromiumPath: string | null = null;
+
+export function __setPlaywrightChromiumInstallerForTest(installer: ChromiumInstaller | null): void {
+  chromiumInstallerForTest = installer;
+}
+
+export function __setChromiumFinderForTest(finder: (() => string | null) | null): void {
+  chromiumFinderForTest = finder;
+  verifiedChromiumPath = null;
+}
+
+function runPlaywrightChromiumInstall(command: string[], env: NodeJS.ProcessEnv): InstallerResult {
+  if (chromiumInstallerForTest) return chromiumInstallerForTest(command, env);
+  const timeoutMs = playwrightInstallTimeoutMs();
+  const logPath = pathJoin(tmpdir(), `imprint-playwright-install-${process.pid}-${Date.now()}.log`);
+  let logFd: number | null = null;
+  try {
+    logFd = openSync(logPath, 'w');
+    const result = nodeSpawnSync(command[0] ?? '', command.slice(1), {
+      env,
+      // Playwright emits frequent progress lines. Send them to a file so parent
+      // command runners that capture stderr without draining it cannot block.
+      stdio: ['ignore', logFd, logFd],
+      timeout: timeoutMs,
+    });
+    const failed = result.status !== 0 || Boolean(result.error);
+    if (!failed) unlinkInstallerLog(logPath);
+    return formatSpawnResult(
+      result,
+      timeoutMs,
+      failed ? readInstallerLog(logPath) : undefined,
+      logPath,
+    );
+  } finally {
+    if (logFd !== null) closeSync(logFd);
+  }
+}
+
+function formatSpawnResult(
+  result: ReturnType<typeof nodeSpawnSync>,
+  timeoutMs: number,
+  output: string | undefined,
+  logPath: string,
+): InstallerResult {
+  const error = result.error as (Error & { code?: string }) | undefined;
+  return {
+    exitCode: result.status,
+    stderr: output,
+    signal: result.signal,
+    error: error?.message,
+    timedOut: error?.code === 'ETIMEDOUT',
+    timeoutMs,
+    logPath,
+  };
+}
+
+function readInstallerLog(logPath: string): string | undefined {
+  try {
+    const output = readFileSync(logPath, 'utf8').trim();
+    const maxChars = 50_000;
+    if (output.length <= maxChars) return output;
+    return `[last ${maxChars} chars of ${logPath}]\n${output.slice(-maxChars)}`;
+  } catch {
+    return undefined;
+  }
+}
+
+function unlinkInstallerLog(logPath: string): void {
+  try {
+    unlinkSync(logPath);
+  } catch {
+    // best effort cleanup
+  }
+}
+
+function playwrightInstallTimeoutMs(): number {
+  const raw = process.env.IMPRINT_PLAYWRIGHT_INSTALL_TIMEOUT_MS?.trim();
+  if (!raw) return 10 * 60 * 1000;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 10 * 60 * 1000;
+}
+
+function formatInstallerFailure(result: InstallerResult): string | undefined {
+  const lines: string[] = [];
+  if (result.timedOut) {
+    lines.push(`Timed out after ${Math.round((result.timeoutMs ?? 0) / 1000)}s.`);
+  }
+  if (result.signal) lines.push(`Terminated by signal: ${result.signal}`);
+  if (result.error) lines.push(`Error: ${result.error}`);
+  const output = [result.stderr, result.stdout].filter(Boolean).join('\n').trim();
+  if (output) lines.push(`Output:\n${output}`);
+  else if (result.logPath) lines.push(`Installer log: ${result.logPath}`);
+  return lines.length > 0 ? lines.join('\n') : undefined;
+}
+
+interface EnsureChromiumResult {
+  path: string;
+  installed: boolean;
+  command?: string;
+}
+
+function verifyChromiumExecutable(path: string): void {
+  if (verifiedChromiumPath === path) return;
+  const result = Bun.spawnSync([path, '--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
+  if (result.exitCode === 0) {
+    verifiedChromiumPath = path;
+    return;
+  }
+  const output = `${result.stderr.toString()}\n${result.stdout.toString()}`.trim();
+  throw new Error(
+    [
+      `Chromium was found at ${path}, but it could not start.`,
+      output ? `Output:\n${output}` : undefined,
+      process.platform === 'linux'
+        ? 'Install missing Linux browser libraries with: bunx playwright install --with-deps chromium'
+        : undefined,
+    ]
+      .filter((line): line is string => Boolean(line))
+      .join('\n'),
+  );
+}
+
+export function ensurePlaywrightChromiumInstalled(
+  opts: {
+    log?: (message: string) => void;
+  } = {},
+): EnsureChromiumResult {
+  let existingPath: string | null = null;
+  try {
+    existingPath = findChromium();
+  } catch {
+    // Install below.
+  }
+  if (existingPath) {
+    verifyChromiumExecutable(existingPath);
+    return { path: existingPath, installed: false };
+  }
+
+  const env = playwrightInstallEnv();
+  if (env.PLAYWRIGHT_BROWSERS_PATH) {
+    process.env.PLAYWRIGHT_BROWSERS_PATH = env.PLAYWRIGHT_BROWSERS_PATH;
+  }
+  const command = playwrightInstallCommand();
+  const displayCommand = commandText(command, env);
+  opts.log?.(`Chromium not found; installing Playwright Chromium with: ${displayCommand}`);
+  const result = runPlaywrightChromiumInstall(command, env);
+  if (result.exitCode !== 0 || result.error) {
+    const failure = formatInstallerFailure(result);
+    throw new Error(
+      [
+        'Could not install Playwright Chromium automatically.',
+        `Command: ${displayCommand}`,
+        failure,
+        '',
+        'Retry manually with the command above.',
+        process.platform === 'linux'
+          ? 'If Chromium is installed but cannot launch in a fresh Linux image, install OS browser libraries with: bunx playwright install --with-deps chromium'
+          : undefined,
+      ]
+        .filter((line): line is string => Boolean(line))
+        .join('\n'),
+    );
+  }
+
+  try {
+    const path = findChromium();
+    verifyChromiumExecutable(path);
+    return { path, installed: true, command: displayCommand };
+  } catch (err) {
+    throw new Error(
+      [
+        'Playwright Chromium install completed, but Imprint still could not locate or start the Chromium binary.',
+        `Command: ${displayCommand}`,
+        err instanceof Error ? err.message : String(err),
+      ].join('\n'),
+    );
+  }
+}
+
 export function findChromium(): string {
+  if (chromiumFinderForTest) {
+    const path = chromiumFinderForTest();
+    if (path) return path;
+    throw new Error('Could not locate Chromium.');
+  }
+
   const explicit = process.env.CHROMIUM_PATH;
   if (explicit && existsSync(explicit)) return explicit;
 
@@ -272,7 +540,9 @@ async function waitForCdp(port: number, timeoutMs = 10_000): Promise<void> {
 }
 
 export async function launchChromium(opts: LaunchOptions = {}): Promise<LaunchedChromium> {
-  const exe = findChromium();
+  const exe = ensurePlaywrightChromiumInstalled({
+    log: (message) => process.stderr.write(`[imprint] ${message}\n`),
+  }).path;
   const port = opts.port ?? (await pickFreePort());
   const userDataDir =
     opts.userDataDir ?? pathJoin(tmpdir(), `imprint-chrome-${Date.now()}-${process.pid}`);
@@ -286,6 +556,7 @@ export async function launchChromium(opts: LaunchOptions = {}): Promise<Launched
     '--disable-popup-blocking',
     '--use-mock-keychain',
   ];
+  if (shouldDisableChromiumSandbox()) args.push('--no-sandbox');
   if (opts.headless) args.push('--headless=new');
   const proxy = opts.proxy ?? proxyUrl();
   if (proxy) {

package/src/imprint/compile-tools.ts

@@ -7,7 +7,14 @@
  */
 
 import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 import { basename, dirname, join as pathJoin, relative as pathRelative } from 'node:path';
 import type { AgentTool } from './agent.ts';
 import { inferAppApiHosts } from './app-api-hosts.ts';
@@ -1234,8 +1241,9 @@ export async function typecheckArtifacts(
   includes: string[],
 ): Promise<{ stdout: string; stderr: string; exitCode: number; timedOut: boolean }> {
   const configPath = pathJoin(dir, '.imprint-typecheck.tsconfig.json');
-  const rootTsconfig = pathJoin(REPO_ROOT, 'tsconfig.json');
-  const extendsPath = normalizeTsconfigPath(pathRelative(dir, rootTsconfig));
+  const rootTsconfig = realpathSync(pathJoin(REPO_ROOT, 'tsconfig.json'));
+  const configDir = realpathSync(dir);
+  const extendsPath = normalizeTsconfigPath(pathRelative(configDir, rootTsconfig));
 
   writeFileSync(
     configPath,

package/src/imprint/cron.ts

@@ -77,6 +77,7 @@ async function runOnce(
   ladder: ConcreteBackend[],
   assetRoot: string,
   stealthCache: Map<string, StealthFetch>,
+  skipBootstrapSplice: boolean,
 ): Promise<ToolResult> {
   const startedAt = new Date();
   log(
@@ -90,6 +91,7 @@ async function runOnce(
     params,
     assetRoot,
     stealthCache,
+    { skipBootstrapSplice },
   );
 
   const elapsed = Date.now() - t0;
@@ -274,6 +276,7 @@ async function runCronImpl(opts: RunCronOptions): Promise<void> {
     ladder,
     assetRoot,
     stealthCache,
+    Boolean(cached?.preferredOrder.length),
   ] as const;
 
   if (opts.once) {

package/src/imprint/doctor.ts

@@ -6,6 +6,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join as pathJoin } from 'node:path';
 import { findChromium } from './chromium.ts';
+import { defaultHermesConfigPath } from './install.ts';
 import { getProviderStatuses } from './llm.ts';
 import { VERSION } from './version.ts';
 
@@ -63,9 +64,13 @@ function checkPlaywrightChromium(): CheckResult {
   // useful as a separate line so users see whether the Playwright path
   // specifically is set up (matters for stealth-fetch + playbook backends).
   const cacheRoots = [
+    process.env.PLAYWRIGHT_BROWSERS_PATH,
+    process.env.HERMES_HOME
+      ? pathJoin(process.env.HERMES_HOME, '.cache', 'ms-playwright')
+      : undefined,
     pathJoin(homedir(), 'Library/Caches/ms-playwright'),
     pathJoin(homedir(), '.cache/ms-playwright'),
-  ];
+  ].filter((root): root is string => Boolean(root));
   for (const root of cacheRoots) {
     if (!existsSync(root)) continue;
     try {
@@ -84,7 +89,8 @@ function checkPlaywrightChromium(): CheckResult {
   return {
     name: 'Playwright Chromium',
     ok: false,
-    detail: 'no chromium-* install under ~/Library/Caches/ms-playwright or ~/.cache/ms-playwright',
+    detail:
+      'no chromium-* install under PLAYWRIGHT_BROWSERS_PATH, $HERMES_HOME/.cache/ms-playwright, ~/Library/Caches/ms-playwright, or ~/.cache/ms-playwright',
     fix: 'run: bunx playwright install chromium  (needed for stealth-fetch + playbook)',
   };
 }
@@ -209,7 +215,7 @@ function checkClaudeCode(): CheckResult {
 }
 
 function checkHermes(): CheckResult {
-  const configPath = pathJoin(homedir(), '.hermes', 'config.yaml');
+  const configPath = defaultHermesConfigPath();
   if (!existsSync(configPath)) {
     return {
       name: 'Hermes Agent',

package/src/imprint/install.ts

@@ -3,6 +3,7 @@ import { homedir } from 'node:os';
 import { dirname as pathDirname, join as pathJoin, resolve as pathResolve } from 'node:path';
 import * as p from '@clack/prompts';
 import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
+import { defaultPlaywrightBrowsersPath, ensurePlaywrightChromiumInstalled } from './chromium.ts';
 import {
   type McpServerConfig,
   PLATFORMS,
@@ -16,7 +17,7 @@ import {
   shellQuote,
 } from './integrations.ts';
 import { imprintHomeDir } from './paths.ts';
-import { discoverTools } from './tool-loader.ts';
+import { type ResolvedTool, discoverTools } from './tool-loader.ts';
 import type { Workflow } from './types.ts';
 
 type InstallSource = 'local' | 'examples';
@@ -28,6 +29,7 @@ interface InstallOptions {
   source?: InstallSource;
   print?: boolean;
   noInteractive?: boolean;
+  skipBrowserInstall?: boolean;
 }
 
 interface UninstallOptions {
@@ -70,6 +72,7 @@ interface InstallTarget {
   source: InstallSource;
   assetRoot: string;
   site: string;
+  tools: ResolvedTool[];
   workflows: Workflow[];
 }
 
@@ -114,7 +117,11 @@ function defaultOpenClawConfigPath(): string {
   return pathJoin(homedir(), '.openclaw', 'openclaw.json');
 }
 
-function defaultHermesConfigPath(): string {
+export function defaultHermesConfigPath(): string {
+  const explicit = process.env.HERMES_CONFIG?.trim();
+  if (explicit) return explicit;
+  const hermesHome = process.env.HERMES_HOME?.trim();
+  if (hermesHome) return pathJoin(hermesHome, 'config.yaml');
   return pathJoin(homedir(), '.hermes', 'config.yaml');
 }
 
@@ -255,7 +262,7 @@ export async function install(opts: InstallOptions = {}): Promise<InstallResult>
   const imprintCommand = configFilePlatform(platform)
     ? detectDirectBunImprintCommand()
     : detectImprintCommand();
-  const env = { IMPRINT_HOME: target.assetRoot };
+  const env = buildInstallEnvironment(target);
   const workflow = target.workflows[0];
   if (!workflow) {
     throw new Error(`No emitted workflows found for ${target.site}. Run \`imprint emit\` first.`);
@@ -287,6 +294,10 @@ export async function install(opts: InstallOptions = {}): Promise<InstallResult>
     };
   }
 
+  if (!opts.skipBrowserInstall) {
+    ensureBrowserRuntimeForInstall(target);
+  }
+
   const regCommand = buildRegistrationCommand({
     site: target.site,
     platform,
@@ -422,10 +433,68 @@ async function resolveInstallTarget(opts: InstallOptions): Promise<InstallTarget
     source: selected.source,
     assetRoot: selected.assetRoot,
     site: selected.site,
+    tools,
     workflows,
   };
 }
 
+function buildInstallEnvironment(target: InstallTarget): Record<string, string> {
+  const env: Record<string, string> = { IMPRINT_HOME: target.assetRoot };
+  const browsersPath = defaultPlaywrightBrowsersPath();
+  if (browsersPath && installTargetNeedsBrowserRuntime(target)) {
+    env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  }
+  return env;
+}
+
+function ensureBrowserRuntimeForInstall(target: InstallTarget): void {
+  if (!installTargetNeedsBrowserRuntime(target)) return;
+  const result = ensurePlaywrightChromiumInstalled({
+    log: (message) => process.stderr.write(`[imprint install] ${message}\n`),
+  });
+  if (result.installed) {
+    process.stderr.write(`[imprint install] installed Playwright Chromium at ${result.path}\n`);
+  }
+}
+
+function installTargetNeedsBrowserRuntime(target: InstallTarget): boolean {
+  return target.tools.some(
+    (tool) => workflowNeedsBrowserRuntime(tool.workflow) || toolDirNeedsBrowserRuntime(tool.dir),
+  );
+}
+
+function workflowNeedsBrowserRuntime(workflow: Workflow): boolean {
+  if (workflow.bootstrap) return true;
+  if (workflow.liveVerified === false && workflow.liveVerifiedWaiver?.kind === 'waived-bot') {
+    return true;
+  }
+  if (workflow.requests.some((request) => request.url.includes('${state.'))) return true;
+  return workflow.requests.some((request) =>
+    (request.captures ?? []).some((capture) => captureNeedsBrowserRuntime(capture.capability)),
+  );
+}
+
+function toolDirNeedsBrowserRuntime(toolDir: string): boolean {
+  if (existsSync(pathJoin(toolDir, 'playbook.yaml'))) return true;
+  const backendsPath = pathJoin(toolDir, 'backends.json');
+  if (!existsSync(backendsPath)) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(backendsPath, 'utf8')) as { preferredOrder?: unknown };
+    if (!Array.isArray(parsed.preferredOrder)) return false;
+    return parsed.preferredOrder.some(
+      (backend) =>
+        typeof backend === 'string' &&
+        ['fetch-bootstrap', 'cdp-replay', 'stealth-fetch', 'playbook'].includes(backend),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function captureNeedsBrowserRuntime(capability: string | undefined): boolean {
+  return capability === 'browser_bootstrap' || capability === 'stealth_bootstrap';
+}
+
 async function resolveInstallPlatform(
   opts: Pick<InstallOptions, 'platform' | 'noInteractive'>,
   message = 'Install this MCP server where?',
@@ -658,7 +727,13 @@ function isPlatformDetected(platform: Platform): boolean {
     case 'openclaw':
       return commandExists('openclaw') || existsSync(pathJoin(homedir(), '.openclaw'));
     case 'hermes':
-      return commandExists('hermes') || existsSync(pathJoin(homedir(), '.hermes'));
+      return (
+        commandExists('hermes') ||
+        Boolean(process.env.HERMES_CONFIG?.trim()) ||
+        Boolean(process.env.HERMES_HOME?.trim()) ||
+        existsSync(defaultHermesConfigPath()) ||
+        existsSync(pathJoin(homedir(), '.hermes'))
+      );
   }
 }
 

package/src/imprint/integrations.ts

@@ -105,7 +105,7 @@ export function generatePasteSnippet(opts: {
 This gives your agent a tool that ${descLower}. Parameters: ${paramList}.`;
 
     case 'hermes':
-      return `Add the ${toolName} tool: add to ~/.hermes/config.yaml under mcp_servers:
+      return `Add the ${toolName} tool: add to $HERMES_HOME/config.yaml (or ~/.hermes/config.yaml outside Hermes) under mcp_servers:
 
   ${toolName}:
     command: "${ic.command}"

package/src/imprint/mcp-maintenance.ts

@@ -144,6 +144,14 @@ function defaultContext(opts: Partial<MaintenanceContext> = {}): MaintenanceCont
   };
 }
 
+function hermesConfigPath(ctx: MaintenanceContext): string {
+  const explicit = process.env.HERMES_CONFIG?.trim();
+  if (explicit) return explicit;
+  const hermesHome = process.env.HERMES_HOME?.trim();
+  if (hermesHome) return pathJoin(hermesHome, 'config.yaml');
+  return pathJoin(ctx.homeDir, '.hermes', 'config.yaml');
+}
+
 function parseSubArgs(argv: string[]): ParsedArgs {
   const positionals: string[] = [];
   const flags: Record<string, string | boolean> = {};
@@ -1419,7 +1427,7 @@ function scanJsonMap(
 }
 
 function scanHermes(ctx: MaintenanceContext): McpRegistration[] {
-  const configPath = pathJoin(ctx.homeDir, '.hermes', 'config.yaml');
+  const configPath = hermesConfigPath(ctx);
   if (!existsSync(configPath)) return [];
   const doc = YAML.parseDocument(readFileSync(configPath, 'utf8'));
   const servers = doc.get('mcp_servers', true);

package/src/imprint/mcp-server.ts

@@ -179,7 +179,7 @@ function buildServer(
         args,
         assetRoot,
         stealthCache,
-        { cdpPool, winnerCache },
+        { cdpPool, winnerCache, skipBootstrapSplice: Boolean(tool.preferredOrder?.length) },
       );
       // Reset the idle timer for this site's pooled Chrome.
       if (result.ok && usedBackend === 'cdp-replay' && cdpPool.has(tool.site)) {

package/src/imprint/stealth-chromium.ts

@@ -1,4 +1,4 @@
-import { findChromium } from './chromium.ts';
+import { ensurePlaywrightChromiumInstalled } from './chromium.ts';
 
 /**
  * Shared loader for Playwright's chromium with the stealth plugin applied.
@@ -69,13 +69,11 @@ export async function isStealthPluginAvailable(): Promise<boolean> {
  * replay browser using chrome-headless-shell looks like a bot. Using the
  * SAME binary for both eliminates the binary asymmetry.
  *
- * Returns `undefined` if no Chromium can be located — callers should let
- * Playwright fall back to whatever default it finds.
+ * Throws if Chromium cannot be installed or started; callers translate the
+ * error into their own result shape.
  */
 export function getStealthExecutablePath(): string | undefined {
-  try {
-    return findChromium();
-  } catch {
-    return undefined;
-  }
+  return ensurePlaywrightChromiumInstalled({
+    log: (message) => process.stderr.write(`[imprint] ${message}\n`),
+  }).path;
 }