imprint-mcp 0.2.1 → 0.3.1

package/README.md

@@ -1,311 +1,313 @@
-<h1 align="center">Imprint</h1>
+<div align="center">
 
-<p align="center">
-  <strong>Don't do anything twice. Teach your AI agent once, and it remembers forever.</strong>
-</p>
+# imprint
 
-<p align="center">
-  <a href="https://github.com/ashaychangwani/imprint/actions/workflows/test.yml"><img src="https://github.com/ashaychangwani/imprint/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
-  <img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ashaychangwani/cbd3134e06fb4fabf24aed94b251bdfd/raw/test-count.json" alt="Test count">
-  <a href="https://github.com/ashaychangwani/imprint/releases"><img src="https://img.shields.io/github/v/release/ashaychangwani/imprint?label=release" alt="Release"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
-  <a href="https://github.com/ashaychangwani/imprint/stargazers"><img src="https://img.shields.io/github/stars/ashaychangwani/imprint?style=social" alt="GitHub Stars"></a>
-</p>
+**Teach your AI agent any website. Once.**
 
-<br>
+Record a real browser session, get a deterministic MCP tool back.\
+No tokens burned on exploration. No "the LLM clicked the wrong button."\
+The recording *is* the executable.
 
-```bash
-bun install -g imprint-mcp
-imprint teach southwest --url https://www.southwest.com
-```
+[![Tests](https://github.com/ashaychangwani/imprint/actions/workflows/test.yml/badge.svg)](https://github.com/ashaychangwani/imprint/actions/workflows/test.yml)
+![Test count](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/ashaychangwani/cbd3134e06fb4fabf24aed94b251bdfd/raw/test-count.json)
+[![Release](https://img.shields.io/github/v/release/ashaychangwani/imprint?label=release)](https://github.com/ashaychangwani/imprint/releases)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/ashaychangwani/imprint?style=social)](https://github.com/ashaychangwani/imprint/stargazers)
 
-That's it. Imprint opens a browser, you drive the workflow, and it compiles a deterministic **MCP tool** your AI agent can call from then on. No tokens burned on exploration, no "the LLM clicked the wrong button" variance. The recording *is* the executable.
+[Quick Start](#quick-start) · [Examples](#examples) · [How It Works](#how-it-works) · [Docs](docs/getting-started.md)
 
-<br>
+</div>
 
-## See it in action
+---
 
-After teaching, your agent has a tool called `search_namecheap_domains`. The compile-agent reverse-engineered the site's CRC32 URL signing scheme from a captured JavaScript bundle, chains five API endpoints, and merges availability + pricing + aftermarket data:
+## Quick Start
 
+```bash
+bun install -g imprint-mcp
+imprint teach southwest --url https://www.southwest.com
 ```
-$ claude "search for getimprint on Namecheap, under $20/yr renewal"
 
-  getimprint.com     taken         registered 2008         GoDaddy.com, LLC
-  getimprint.dev     available     $12.98/yr (19% off)     renews $20.98/yr
-  getimprint.org     available     $7.48/yr (42% off)      renews $15.98/yr
-  getimprint.fyi     available     $6.98/yr                renews $9.68/yr
-  getimprint.xyz     available     $2.00/yr (90% off)      renews $19.48/yr
-```
+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.
 
-Real-time domain availability with per-request URL signing — the agent wrote the signing function itself by reading the site's JS bundle.
+Want to try a finished MCP before recording anything?
 
-<br>
-
-## How it works
+```bash
+imprint install google-flights --source examples --platform claude-desktop
+```
 
-<table>
-<tr>
-<td width="33%">
+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.
 
-### 1. Teach
+On a Hermes agent or Docker host, register the examples directly into Hermes:
 
 ```bash
-imprint teach mysite \
-  --url https://example.com
+for site in google-flights google-hotels southwest discoverandgo echo; do
+  imprint install "$site" --source examples --platform hermes --no-interactive
+done
 ```
 
-A browser opens. You drive the workflow and narrate what you're doing. Imprint records every network request and DOM interaction.
+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`.
 
-Raw recordings are stored locally under `~/.imprint/<site>/sessions/`, and each generated tool lives under `~/.imprint/<site>/<toolName>/` by default, outside the repo. The generated `index.ts` imports from `imprint/runtime` via a `node_modules/imprint` symlink that Imprint maintains automatically — created on `emit`, self-healed at runtime if a worktree moves or vanishes (so the next `imprint mcp-server`/`cron`/`probe-backends` repairs a stale link without re-emitting). The tracked `examples/` tree remains as source fixtures and demos.
+---
 
-</td>
-<td width="33%">
+## See It in Action
 
-### 2. Compile
+**Teach once.** `imprint teach google-flights` records one real search and compiles a **4-tool** MCP server from that single session — the compile agent reverse-engineers Google's `batchexecute` wire format itself and wires the search→booking token chain, with no hand-written request code. Here is the actual run (6 recordings → 4 tools, every tool live-verified):
 
-Imprint generates replay artifacts:
+![imprint teach google-flights — a real run: six recordings compiled into four live-verified MCP tools](web/public/imprint-teach.gif)
 
-- **`workflow.json`** — API-level replay (fast, with named state captures)
-- **`playbook.yaml`** — DOM-level fallback (universal)
-- **`request-transform.ts`** — URL signing when the API requires per-call tokens (optional)
+**Then your agent calls those tools** like any other — real-time results through a live trusted-Chrome (`cdp-replay`) backend:
 
-Both artifacts are written into the generated tool directory (`~/.imprint/<site>/<toolName>/`). `compile-playbook` uses that nested location by default so cron and MCP discovery can see the fallback without a custom `--out`.
+```
+$ claude "cheapest nonstop SJC→SAN the first week of July, with a carry-on"
 
-Credentials and PII are redacted automatically: credential values become `${credential.NAME}` placeholders, sensitive values become redaction markers that preserve equality within the artifact, and a supplemental free-form scan catches common emails, phone numbers, SSNs, payment cards, JWTs, API keys, private keys, database URLs, and webhook URLs before LLM compile.
+  Alaska     AS1623   SJC→SAN   6:00a→7:32a   nonstop   $137
+  Southwest  WN2412   SJC→SAN   8:15a→9:45a   nonstop   $158
+  Delta      DL2901   SJC→SAN   7:10a→8:44a   nonstop   $169
+```
 
-</td>
-<td width="34%">
+The suite was one-shot compiled from one recording and audited at **92.6%**, every tool live-verified. *(The terminal above is a faithful replay — regenerate/record it with `bun scripts/demo-teach.ts`.)*
 
-### 3. Use
+---
 
-A typed MCP tool is generated and wired into your AI platform. Re-run `imprint install <site>` any time to add the same emitted MCP server to another platform, or remove it later with `imprint uninstall <site>`.
+## How It Works
 
+<table>
+<tr>
+<td align="center" width="33%">
+<h3>1. Teach</h3>
+<p>Open a real browser, drive the workflow, narrate what you're doing. Imprint records every network request and DOM interaction.</p>
+</td>
+<td align="center" width="33%">
+<h3>2. Compile</h3>
+<p>Generates two replay artifacts:<br><br><code>workflow.json</code> — API-level replay<br><code>playbook.yaml</code> — DOM-level fallback<br><br>Credentials are redacted automatically.</p>
+</td>
+<td align="center" width="34%">
+<h3>3. Use</h3>
+<p>A typed MCP tool your agent calls like any other tool. Works with Claude Code, Codex, Claude Desktop, and any MCP client.</p>
 </td>
 </tr>
 </table>
 
-> All three steps happen in a single `imprint teach` command.
+> [!TIP]
+> All three steps happen in a single `imprint teach` command. Credentials and PII are redacted automatically before anything reaches the LLM.
 
-<br>
+---
 
 ## Why Imprint?
 
-Other browser-tool frameworks (browser-use, Computer Use) ask the LLM to **decide every click at runtime**.
+Other browser-tool frameworks ask the LLM to **decide every click at runtime**. Imprint takes a fundamentally different approach:
 
-| | Imprint | browser-use / Computer Use |
-|---|---|---|
-| **How it works** | Record once, replay deterministically | LLM decides every click at runtime |
+| | **Imprint** | **browser-use / Computer Use** |
+|:--|:--|:--|
+| **Approach** | Record once, replay deterministically | LLM decides every click at runtime |
 | **Token cost** | Zero at runtime | Scales with workflow complexity |
 | **Reliability** | Deterministic — same input, same output | Variable — exploration can diverge |
 | **Bot detection** | Real Chromium + stealth-fetch | Detectable automation fingerprint |
-| **When it breaks** | Automatic fallback via backend ladder | No fallback |
-| **Time to result** | 200ms – 9s | 30s+ |
+| **Fallback** | Automatic ladder (API → DOM) | None |
+| **Speed** | 200ms – 9s | 30s+ |
 
-<br>
+---
 
-## Install
+## Installation
 
-### npm (requires [Bun](https://bun.sh) >= 1.3)
+### Recommended
 
 ```bash
 bun install -g imprint-mcp
 ```
 
-Or run without installing: `bunx imprint-mcp teach southwest --url https://www.southwest.com`
+> Requires [Bun](https://bun.sh) >= 1.3. Or run without installing: `bunx imprint-mcp teach <site> --url <url>`
 
-### Standalone binary (no Bun needed)
+### Standalone Binary
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/ashaychangwani/imprint/main/scripts/install.sh | bash
 ```
 
-The standalone binary supports `mcp-server`, `install`, `cron`, and `credential` commands.
-Browser commands (`teach`, `record`, `login`, `playbook`) require a full Bun + Playwright install.
-
-### From source
+### From Source
 
 ```bash
 git clone https://github.com/ashaychangwani/imprint.git && cd imprint
 bun install && bun link
 ```
 
-### Browser commands
+<details>
+<summary><strong>Browser setup & LLM providers</strong></summary>
 
-The `teach`, `record`, `login`, and `playbook` commands need Playwright's Chromium. Install it once:
+<br>
+
+**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
 ```
 
-### LLM providers
-
-Imprint detects LLM providers from what's already on your system:
+**LLM providers** are auto-detected. Run `imprint doctor` to see what's available.
 
-| Priority | Provider | Triggered by |
-|---|---|---|
-| 1 | `claude-cli` | `claude` on PATH (Claude Code subscription) |
-| 2 | `codex-cli` | `codex` on PATH (Codex subscription) |
-| 3 | `anthropic-api` | `ANTHROPIC_API_KEY` env var |
-| 4 | `cursor-cli` | `cursor` on PATH (generic prompt/playbook compile only; not `teach`/`generate`) |
+| Priority | Provider | Detected via |
+|:--|:--|:--|
+| 1 | Claude Code | `claude` on PATH |
+| 2 | Codex CLI | `codex` on PATH |
+| 3 | Anthropic API | `ANTHROPIC_API_KEY` env var |
+| 4 | Cursor | `cursor` on PATH |
 
-```bash
-imprint doctor
-```
-
-Shows which providers are detected. Interactive `imprint teach` prompts you to choose when multiple compatible compile providers are available, and also lists undetected providers as setup-help entries. Pick one of those help entries to see exactly which CLI or environment variable to add so it will be detected next time.
+Override with `--provider <name>` and `--model <name>`.
 
-To force a specific provider and skip the picker, pass `--provider <name>` to `teach`, `generate`, or `compile-playbook`. `teach` and `generate` require a compile-agent provider (`claude-cli`, `codex-cli`, or `anthropic-api`); `compile-playbook` can also use `cursor-cli`.
+</details>
 
-After selecting a provider, `teach` prompts for a **model** (e.g. `claude-opus-4-7` vs `claude-sonnet-4-6` for Anthropic, `gpt-5.4` vs `o3` for Codex). Override with `--model <name>`. Each tool compiles with a **20-minute timeout** by default — the compile agent writes the MCP server and runs thorough verification tests, so most complex tools take 10-15 minutes. Override with `--timeout <duration>` (e.g. `--timeout 30m`, `--timeout 1h`). To persist the generated tests after compilation, set `IMPRINT_KEEP_TEST=1` or pass `--keep-test`. To skip the replay-and-diff stage (the automated second pass that classifies ephemeral vs constant values), pass `--skip-replay` — faster, but may reduce workflow accuracy for sites with dynamic request parameters.
-
-<br>
+---
 
-## Local compile tracing
+## The Backend Ladder
 
-Slow or suspicious compiles can be inspected in a local [Phoenix](https://arize.com/docs/phoenix/self-hosting/deployment-options/terminal) trace UI.
+When an API call gets blocked, Imprint doesn't jump to DOM replay. It escalates through the cheapest backend that works:
 
-```bash
-# one-time install with uv
-uv tool install arize-phoenix
-phoenix serve
-
-# in another terminal
-IMPRINT_TRACE=1 \
-IMPRINT_TRACE_BATCH=false \
-IMPRINT_TRACE_LLM_IO=1 \
-IMPRINT_TRACE_TOOL_IO=1 \
-PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006 \
-imprint teach namecheap-domains --from-session ~/.imprint/namecheap-domains/sessions/<ts>.json --provider codex-cli
+```
+  fetch            ~200ms    Plain APIs, persisted cookies
+    │
+    ▼
+  fetch-bootstrap  browser   Mints cookies, CSRF tokens, storage
+    │               + API
+    ▼
+  cdp-replay       ~2-35s    API calls run inside a live, trusted Chrome —
+    │                        a protected POST refreshes its anti-bot token
+    │                        between calls (multi-step state-changing flows)
+    ▼
+  stealth-fetch    ~1-12s    Defeats Akamai, Cloudflare, DataDome
+    │
+    ▼
+  playbook         ~9s       Full DOM replay — universal fallback
 ```
 
-Traces show the full compile pipeline at every level of detail: each `agent.turn.N` span captures per-turn token counts; each `llm.message_with_tools` span records model, provider, input/output tokens, and stop reason; each `agent.tool.X` span times individual tool dispatches. Drill from `cli.teach` → `compile.generate` → `agent.turn.1` → tool calls to find exactly which turn or tool is spending tokens. Set `IMPRINT_TRACE_IO_MAX_CHARS` to raise or lower captured payload size. Set `IMPRINT_TRACE_INPUT_USD_PER_1M` and `IMPRINT_TRACE_OUTPUT_USD_PER_1M` to add estimated cost attributes.
+The full order is `fetch → fetch-bootstrap → cdp-replay → stealth-fetch → playbook`; `auto` mode walks it and stops at the first backend that works.
 
-<br>
+Every recording compiles to *both* `workflow.json` and `playbook.yaml`, so the ladder always has a DOM fallback.
 
-## Platform support
+---
 
-At the end of `imprint teach`, you pick your AI platform and Imprint handles the wiring:
+## Platform Support
+
+At the end of `imprint teach`, pick your AI platform and Imprint wires it up:
 
 | Platform | Integration |
-|---|---|
-| **Claude Code** | Automatic — runs `claude mcp add` for you |
-| **Codex CLI** | Automatic — runs `codex mcp add` for you |
+|:--|:--|
+| **Claude Code** | Automatic — runs `claude mcp add` |
+| **Codex CLI** | Automatic — runs `codex mcp add` |
 | **Claude Desktop** | Paste-ready JSON config |
 | **OpenClaw** | MCP config + SKILL.md export |
 | **Hermes** | MCP config + SKILL.md + cron mapping |
 
-Each site registers as its own MCP server (`imprint-southwest`, `imprint-discoverandgo`, ...) so tools never collide. See [Integrations](docs/integrations.md) for HTTP transport, Docker, and systemd options.
+Each site registers as its own MCP server (`imprint-southwest`, `imprint-google-flights`, ...) so tools never collide.
 
-Audit or clean up those registrations with `imprint mcp`:
+---
 
-```bash
-imprint mcp status                         # registrations + local teach state
-imprint mcp                                # interactive cleanup TUI
-imprint mcp disable imprint-mysite --yes   # reversible; stores a local snapshot
-imprint mcp delete imprint-mysite --yes    # removes external MCP registrations only
-```
+## Examples
 
-Raw recordings under `~/.imprint/<site>/sessions/` may contain sensitive browser state. Cleanup commands leave them alone unless you explicitly choose `--local site`.
+Every example below was **one-shot compiled from a single real browser-session recording** (`imprint teach`) — the generated artifacts are committed verbatim as a **proof of concept** of what the compiler produces, not as maintained integrations. Recording-derived defaults (dates, geo) age out; pass explicit values.
 
-See [MCP Maintenance](docs/mcp-maintenance.md) for status classifications, supported client config files, reversible disable behavior, and local artifact cleanup rules.
+**★ Star examples** — multi-tool suites, each compiled from one recording and scored by the headless differential audit:
 
-<br>
+| Example | Tools | Audit | What it shows |
+|:--|:--|:--|:--|
+| [**google-flights**](examples/google-flights) | 4 | 92.6% | `batchexecute` wire-format decode + search→booking producer-token chain, live `cdp-replay` |
+| [**google-hotels**](examples/google-hotels) | 4 | 91.7% | autocomplete → search → reviews/booking producer-token chaining |
 
-## Sharing skills across machines
+Other examples:
 
-Teach on your laptop, ship the skill to a remote agent (OpenClaw, Hermes, a server-side cron host, ...). Skill folders committed to git contain **zero plaintext credentials** — only placeholders like `${credential.NAME}` / `${state.NAME}` and a `credentials.manifest.json` listing the secrets or durable storage keys the receiver must provision.
+| Example | Description |
+|:--|:--|
+| [**southwest**](examples/southwest) | Live fare search — defeats Akamai bot detection |
+| [**discoverandgo**](examples/discoverandgo) | Authenticated booking via per-site credential store |
+| [**echo**](examples/echo) | MCP smoke-test fixture |
 
-For credentials, use the **encrypted bundle** flow when you can't (or don't want to) re-type passwords on the receiving machine:
+Install any example into your MCP client:
 
 ```bash
-# On the laptop where you taught the skill:
-imprint credential export southwest --out southwest.imprintbundle
-# → prompts for a passphrase. The bundle is libsodium-encrypted with an
-#   argon2id-derived key. Safe to send via Slack, email, scp, S3, etc.
-
-# On the OpenClaw machine (or any other receiver):
-imprint credential import southwest southwest.imprintbundle
-# → prompts for the same passphrase. Decrypts; secrets land in the OS keychain.
+imprint install google-flights --source examples --platform claude-desktop
 ```
 
-Pass the passphrase **out-of-band** (Signal, phone, password manager share — *not* the same channel as the bundle file).
-
-After import, the same `imprint mcp-server <site>` config you'd use locally works on the receiver — it resolves credentials from that machine's credential backend and initializes a fresh cookie/state jar for every tool call. If anything's missing, `imprint mcp-server` and `imprint cron` log/fail with the exact `imprint credential set`, `imprint login`, or `imprint credential import` commands you need.
+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:
 
-See [Sharing Skills](docs/credential-sharing.md) for the full flow including interactive `imprint credential set` (when you can re-type), threat model, rotation, and OpenClaw / Hermes wiring details.
-
-<br>
+```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
+```
 
-## The backend ladder
+For your own generated tools, leave off `--source examples`:
 
-When an API call gets blocked or needs browser-minted state, Imprint doesn't jump straight to DOM replay. It escalates through the cheapest mode that can satisfy the workflow:
+```bash
+imprint install mysite --platform claude-code
+imprint install mysite --platform codex
+```
 
-| | Speed | Handles |
-|---|---|---|
-| **fetch** | ~200ms | Plain APIs, persisted cookies, in-flight HTTP captures |
-| **fetch-bootstrap** | browser bootstrap + API replay | Pages that only need Chromium to mint cookies, CSRF, storage, or DOM-derived state |
-| **stealth-fetch** | ~12s first call, ~1s after | Akamai, Cloudflare, DataDome, bot-defense state |
-| **playbook** | ~9s | Anything — full DOM replay as fallback |
+---
 
-`fetch-bootstrap` is not a default rung for every workflow. `auto` inserts it only when the workflow declares bootstrap metadata, a capture requires browser/stealth bootstrap, or `fetch` returns structured `STATE_MISSING` that a browser bootstrap can satisfy. Every recording still compiles to *both* `workflow.json` and `playbook.yaml`, so the ladder has a DOM fallback when API replay cannot work.
+## CLI Reference
 
-State-aware workflows use named captures and `${state.NAME}` placeholders. For example, request A can set a CSRF cookie, request B can project it into a header, and the whole run stays on plain `fetch` without launching Chromium.
+```bash
+imprint --help              # all commands
+imprint <command> --help    # per-command options
+```
 
-<br>
+| Category | Commands |
+|:--|:--|
+| **Pipeline** | `teach` · `record` · `redact` · `generate` · `compile-playbook` · `emit` |
+| **Runtime** | `cron` · `mcp-server` · `playbook` · `probe-backends` · `audit` |
+| **Credentials** | `credential set` · `credential list` · `credential export` · `credential import` · `credential migrate` |
+| **Utilities** | `mcp` · `login` · `assemble` · `check` · `doctor` · `install` · `uninstall` |
 
-## Examples
+---
 
-The checked-in `examples/` directory contains committed fixtures and demos. Generated tools from `imprint teach` go into `~/.imprint/<site>/<toolName>/` by default (configurable via `IMPRINT_HOME`). Runtime discovery (cron, MCP, probe-backends) reads `IMPRINT_HOME`, so to run the checked-in examples, point it at the repo's `examples/` directory:
+## Sharing Skills
 
-You can also install an example directly into an MCP client:
+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
-imprint install google-flights --source examples --platform claude-desktop
+bun install -g imprint-mcp
+imprint install mysite --platform claude-code
 ```
 
-Run `imprint install` with no arguments for an interactive install/uninstall picker. It only shows detected AI platforms; uninstall lists installed `imprint-*` MCP servers directly. For GUI config-file clients such as Claude Desktop, install writes an absolute Bun + Imprint CLI path so the app does not depend on your shell PATH.
+Credentials stay separate. Skill folders contain **zero plaintext credentials** — only `${credential.NAME}` placeholders and a manifest listing what the receiver must provision.
 
-| Example | What it demonstrates | Run it |
-|---|---|---|
-| [**southwest**](examples/southwest) | Live fare watcher, defeats Akamai bot detection, price-drop notifications | `IMPRINT_HOME=examples imprint cron southwest --once` |
-| [**google-flights**](examples/google-flights) | Real-time flight search across all carriers, parses Google's raw protobuf response | `IMPRINT_HOME=examples imprint mcp-server google-flights` |
-| [**google-hotels**](examples/google-hotels) | Hotel search with star rating, guest scores, nightly + total prices | `IMPRINT_HOME=examples imprint mcp-server google-hotels` |
-| [**discoverandgo**](examples/discoverandgo) | Authenticated booking via per-site credential store | `IMPRINT_HOME=examples imprint cron discoverandgo --once` |
-| [**namecheap-domains**](examples/namecheap-domains) | Domain search with CRC32 URL signing reverse-engineered from JS, 5-endpoint chain with availability + aftermarket pricing | `IMPRINT_HOME=examples imprint mcp-server namecheap-domains` |
-| [**echo**](examples/echo) | MCP smoke-test fixture (no network, no LLM) | `IMPRINT_HOME=examples imprint mcp-server echo` |
+```bash
+# Export (encrypted with libsodium + argon2id)
+imprint credential export southwest --out southwest.imprintbundle
 
-<br>
+# Import on another machine
+imprint credential import southwest southwest.imprintbundle
+```
 
-## CLI reference
+Send the bundle over any channel. Pass the passphrase **out-of-band**.
 
-```
-imprint --help              # all commands
-imprint <command> --help    # per-command options
-```
+See [Sharing Skills](docs/credential-sharing.md) for the full flow.
 
-| | Commands |
-|---|---|
-| **Pipeline** | `teach` · `record` · `redact` · `generate` · `compile-playbook` · `emit` |
-| **Runtime** | `cron` · `mcp-server` · `playbook` · `probe-backends` |
-| **Credentials** | `credential set` · `credential list` · `credential export` · `credential import` · `credential migrate` |
-| **Utilities** | `mcp` · `login` · `assemble` · `check` · `doctor` |
+---
 
-`teach`, `generate`, and `compile-playbook` accept `--provider <name>` to override the auto-detected LLM (see [Install](#install) for valid names and compile-agent support). `teach` and `generate` also take `--keep-test` to retain the agent-written `parser.test.ts` for debugging — it's deleted by default since it reads the gitignored redacted session via `$IMPRINT_SESSION_PATH` and isn't reproducible elsewhere. For multi-tool sites, use `imprint cron <site> --tool <toolName>` and `imprint probe-backends <site> --tool <toolName>` unless `--config` or `--out` points inside the target tool directory.
+## Documentation
 
-<br>
+| | |
+|:--|:--|
+| [Getting Started](docs/getting-started.md) | Full walkthrough |
+| [Architecture](docs/architecture.md) | Data flow and module map |
+| [Integrations](docs/integrations.md) | Per-platform setup |
+| [Security](docs/security.md) | Redaction, credential handling, what gets stored |
+| [Sharing Skills](docs/credential-sharing.md) | Credential export/import and remote provisioning |
+| [MCP Maintenance](docs/mcp-maintenance.md) | Audit, disable, restore, and prune MCP state |
+| [Troubleshooting](docs/troubleshooting.md) | Common failures and fixes |
+| [Tracing](docs/tracing.md) | OpenTelemetry tracing, cost rollup, and Phoenix setup |
 
-## Docs
+<details>
+<summary>More docs</summary>
 
-- [Getting Started](docs/getting-started.md) — full walkthrough
-- [Integrations](docs/integrations.md) — per-platform setup
-- [MCP Maintenance](docs/mcp-maintenance.md) — audit, disable, restore, and prune Imprint MCP state
-- [Sharing Skills](docs/credential-sharing.md) — laptop ↔ OpenClaw / Hermes / remote-agent provisioning
-- [Architecture](docs/architecture.md) — data flow and module map
-- [Security](docs/security.md) — redaction, credential handling, what gets stored
-- [Troubleshooting](docs/troubleshooting.md) — common failures and fixes
-- [Decisions](docs/decisions.md) · [Glossary](docs/glossary.md) · [Capture Protocol](docs/capture-protocol.md) · [Playbook Debugging](docs/playbook-debugging.md) · [Notifications](docs/notifications.md)
+- [Decisions](docs/decisions.md) — design rationale
+- [Glossary](docs/glossary.md) — terms and concepts
+- [Capture Protocol](docs/capture-protocol.md) — CDP recording details
+- [Playbook Debugging](docs/playbook-debugging.md) — DOM replay debugging
+- [Notifications](docs/notifications.md) — alert setup
 
-<br>
+</details>
+
+---
 
 ## Contributing
 
@@ -315,8 +317,10 @@ Good first contributions: replay backends, notification predicates, auth extract
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
 
-<br>
+---
+
+<div align="center">
 
-## License
+**[MIT License](LICENSE)**
 
-[MIT](LICENSE)
+</div>

package/examples/discoverandgo/README.md

@@ -49,7 +49,7 @@ imprint cron discoverandgo --once
 ## Notes
 
 - Discover & Go's auth model is patron-ID + session cookies. The session cookie expires; re-run `imprint login` if you start seeing AUTH_EXPIRED.
-- The workflow chains an `epass_server.php?method=Login` followed by the booking call. Generated `workflow.json` references both via the `${response[N].patronID}` extraction syntax.
+- `imprint login` parses the `patronID` out of the recorded `epass_server.php?method=Login` POST and stores it in the credential store as `patron_id`. The booking `workflow.json` then references it via `${credential.patron_id}` — no Login call is replayed at runtime.
 
 ## Not in this demo
 

package/examples/echo/README.md

@@ -11,7 +11,7 @@
 
 ```bash
 # Inspect via mcp-inspector (recommended for debugging)
-npx @modelcontextprotocol/inspector imprint mcp-server --site echo
+npx @modelcontextprotocol/inspector imprint mcp-server echo
 
 # Or run the included client smoke test
 bun scripts/mcp-client-test.ts

package/examples/google-flights/README.md

@@ -0,0 +1,28 @@
+# Google Flights — `imprint-google-flights`
+
+> **One-shot compiled, proof of concept.** Every file in this directory was generated by a single `imprint teach google-flights` run against **one** recorded browser session — no hand-written request code, parsers, or selectors. It is committed here as a proof of concept of what the compiler produces, not as a maintained integration.
+
+A 4-tool MCP server for Google Flights, compiled from a recording of a normal flight search. Headless-claude differential audit: **92.6%** — every tool `liveVerified=true`.
+
+## Tools
+
+| Tool | What it does | Notes |
+|---|---|---|
+| `lookup_airport` | Resolve a city/airport query to IATA codes | |
+| `search_flights` | Search itineraries (origin, destination, dates, trip type, stops, price, times, duration, bags) | the star tool |
+| `get_flight_booking_details` | Fare/booking detail for a selected itinerary | **consumes** a `flight_token` produced by `search_flights` (producer → consumer chain) |
+| `get_flight_calendar_prices` | Lowest price per day across a date window | |
+
+## How it was compiled
+
+- **Protocol**: Google's `/_/FlightsFrontendUi` **`batchexecute`** endpoint returns a nested-array (protobuf-ish) payload. The compiler reverse-engineered the encoding into `_shared/batchexecute.ts` (shared decoder) + per-tool `parser.ts`, and the `f.req` request shape into `_shared/flights_request.ts` + per-tool `request-transform.ts`.
+- **Anti-bot**: the per-page `f.sid` / `bl` tokens are bootstrapped at runtime (`${state.f_sid}` placeholders), and calls run on the **cdp-replay** rung (requests issued inside a live, trusted Chrome) with a **stealth-fetch** fallback.
+- **Artifacts per tool**: `workflow.json` (API replay), `playbook.yaml` (DOM fallback), `index.ts` (MCP tool), `parser.ts` + `request-transform.ts` (codecs).
+
+## Install
+
+```bash
+imprint install google-flights --source examples --platform claude-desktop
+```
+
+*Recording-derived defaults (dates) age out — pass explicit values. See the repo [README](../../README.md) and [docs](../../docs/architecture.md).*

package/examples/google-flights/_shared/batchexecute.ts

@@ -0,0 +1,63 @@
+// Decode Google's batchexecute streaming envelope used by every FlightsFrontendUi RPC.
+//
+// Wire format (verified against recorded seq 69/97/111/667):
+//   )]}'\n\n            <- anti-XSSI magic prefix
+//   <decimal length>\n   <- length line (jsonChars + 2; counts bounding newlines)
+//   [[...rows...]]\n      <- one chunk = single-line JSON array of rows
+//   ...repeats...
+//
+// We DELIBERATELY do not slice by the length lines: the stated length is
+// `jsonChars + 2`, so naive slice(pos, pos+len) overshoots into the next token.
+// Because every chunk is single-line JSON (all interior newlines are escaped as
+// \n), splitting on "\n" is exact and robust. Each real RPC result is a row
+// ["wrb.fr", <rpcid|null>, "<doubly-encoded JSON payload>", ...]; row[2] must be
+// JSON.parse'd a SECOND time. Sidecar rows ("di", "af.httprm", "e") are ignored.
+
+export function decodeBatchExecute(raw: string): Array<{ rpcid: string | null; payload: any }> {
+  let text = raw;
+  if (text.startsWith(")]}'")) {
+    text = text.slice(4);
+  }
+
+  const out: Array<{ rpcid: string | null; payload: any }> = [];
+  const lines = text.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    // Skip the decimal length marker lines.
+    if (/^\d+$/.test(trimmed)) continue;
+    // Chunks are JSON arrays; anything else is noise / partial.
+    if (trimmed[0] !== '[') continue;
+
+    let chunk: any;
+    try {
+      chunk = JSON.parse(trimmed);
+    } catch {
+      // Tolerate truncated / partial trailing lines.
+      continue;
+    }
+    if (!Array.isArray(chunk)) continue;
+
+    for (const row of chunk) {
+      if (!Array.isArray(row) || row[0] !== 'wrb.fr') continue;
+      const rpcid = typeof row[1] === 'string' ? row[1] : null;
+      if (typeof row[2] !== 'string') continue;
+      let payload: any;
+      try {
+        payload = JSON.parse(row[2]);
+      } catch {
+        continue;
+      }
+      out.push({ rpcid, payload });
+    }
+  }
+
+  return out;
+}
+
+export function extractRpcPayload(raw: string, rpcid?: string): any {
+  const frames = decodeBatchExecute(raw);
+  const frame = rpcid != null ? frames.find((f) => f.rpcid === rpcid) : frames[0];
+  return frame?.payload;
+}