# Glossary

Names you'll see in code, docs, and CLI output.

| Term | What it is |
|---|---|
| **Site** | The organizing label for a group of recordings and tools. Chosen by the user during `imprint teach` or `imprint record` — becomes the directory name at `~/.imprint/<site>/`. |
| **IMPRINT_HOME** | Environment variable that overrides the default `~/.imprint` root directory. Set this to relocate all Imprint data (sessions, tools, cron configs). |
| **IMPRINT_KEEP_TEST** | Environment variable (`=1` to enable). Retains the agent-generated `parser.test.ts` and `integration.test.ts` after compilation succeeds. Equivalent to the `--keep-test` CLI flag on `teach` and `generate`. Useful when you always want to inspect compile-agent test output without passing the flag every time. |
| **MCP** | Model Context Protocol — the standard interface Imprint tools expose. AI agents (Claude Code, Codex, etc.) communicate with `imprint mcp-server` over stdio or HTTP to invoke generated tools. |
| **Provider** | An LLM provider used by compile commands: `anthropic-api` (direct API), `claude-cli` (Claude Code CLI), `codex-cli` (Codex CLI), `cursor-cli` (Cursor CLI — playbook compilation only). |
| **Session** | A captured browser run: every network request + every DOM event + the user's narration. On disk: `~/.imprint/<site>/sessions/<ts>.{jsonl,json}`. |
| **Workflow** | The API-replay artifact compiled from a session. A chain of `WorkflowRequest` records with `${param}`, `${credential}`, `${state}`, and legacy `${response[N]}` substitutions. On disk: `workflow.json`. |
| **Playbook** | The DOM-replay artifact compiled from a session. A list of typed steps (`navigate`, `click`, `type`, `submit`, `press`, `wait`) with locator-priority arrays. On disk: `playbook.yaml`. |
| **Tool** | The user-facing object: a `runWorkflow(input)`-style function exposed as MCP, scheduled by cron, or invoked directly. The generated `~/.imprint/<site>/<toolName>/index.ts` exports one. |
| **Redacted session** | A `.redacted.json` variant of the session file with credentials and PII replaced by `[REDACTED:v3:id=N:len=L]` markers. Created by `imprint redact` or automatically by `imprint teach`. The compile pipeline auto-redacts in-memory if markers are missing. |
| **Triage** | An LLM request-filtering pass before compilation. Sends request metadata (method/URL/resourceType/status) to the LLM to select which captured requests are relevant to the user's intent. Reduces compile-agent input from thousands of requests to the handful that matter. |
| **Compile agent** | The agentic system (`compile-agent.ts`) that generates `workflow.json` + `parser.ts` from a session. Runs a multi-turn loop with read/write/test tools, iterating until external verification passes. |
| **Parser module** | The `parser.ts` file emitted alongside `workflow.json`. Contains response-parsing functions that extract structured data from API responses. Written by the compile-agent and verified with `parser.test.ts` before emission. |
| **Generated module** | The TypeScript file emitted by `imprint emit` — a thin wrapper over `executeWorkflow` with the workflow inlined. Imports from `imprint/runtime` via a `node_modules/imprint` symlink that Imprint maintains automatically — created on `emit`, self-healed at runtime if the link is missing or dangling (e.g. after a worktree move). Portable across worktrees and machines — just install Imprint on the new machine. |
| **Integration test** | A live API test (`integration.test.ts`) written by the compile-agent alongside `parser.test.ts`. A baseline test calls the generated tool with default params and verifies a real HTTP response (catches expired hardcoded tokens, missing URL signing); one `param:<name>` test per exposed parameter overrides it with a discriminating value and asserts the response is actually constrained. The verifier counts coverage by which `param:<name>` tests *ran green* (JUnit-parsed), not a static scan. Ephemeral — deleted after verification unless `--keep-test`. |
| **Verified parameter** | A `verified` flag on each `WorkflowParameter` in `workflow.json`. `true` when a `param:<name>` integration test confirmed the parameter's effect against live data at compile time. `false` (with a `verifyNote`) when it couldn't be confirmed — the live suite was waived by anti-bot (`waived-bot`/`waived-infra`), the param was annotated `// exposed-but-not-verified` (`annotated`), or a producer-sourced token couldn't be chain-verified because the producer was unavailable (`waived-chain`) — in which case the param still ships (keep + mark, never dropped) and `imprint audit` is told to probe it. Undefined on tools compiled before this gate (treated as verified). Not surfaced in the user-facing MCP schema. |
| **Producer-sourced token** | A parameter whose value is an opaque token/id minted by a *sibling* tool — recorded on the param as `sourcedFrom: {tool, field}` in `workflow.json`. The build plan declares the contract (consumer `tokenParams` ⇄ producer `emitsTokens`), detected **deterministically** from the dual-pass diff (`deriveTokenContractHints` maps a provenance-tagged value's producer/consumer requests to their owning tools — covering both `server_derived` values and stable per-entity `constant`s whose opaque value appears in a sibling response, which same-flow replay would otherwise miss) and reconciled into the plan so a planner shortcut can't drop it; the compile gate verifies it with a **chained** `param:<name>` test that mints a fresh value from the producer's `workflow.json` and feeds it to the consumer (reusing the recorded constant is rejected as `unchained`). The MCP schema turns `sourcedFrom` into a param-description hint ("Obtain this from the `<tool>` tool's `<field>` output…") so the orchestrating LLM calls the producer once and reuses the value, and `imprint audit` chains producer→consumer instead of fabricating a token. |
| **Backend** | A replay strategy. Five exist: `fetch`, `fetch-bootstrap`, `cdp-replay`, `stealth-fetch`, `playbook`. |
| **ConcreteBackend** | A `ReplayBackend` value excluding `'auto'` — one of `fetch`, `fetch-bootstrap`, `cdp-replay`, `stealth-fetch`, or `playbook`. Used when a specific backend is required rather than auto-escalation. |
| **cdp-replay** | Runs the workflow's API requests *inside* a live trusted Chrome page (cdp-browser-fetch's in-page `fetchImpl`) instead of replaying a harvested jar via plain fetch. Decisive for multi-step state-changing anti-bot flows: a sensitive POST (`*.act`) self-invalidates Akamai's `_abck`, and only the live page's bmak sensor auto-re-validates it before the next call — so plain-fetch replay dies after ~1–2 POSTs while cdp-replay sustains the whole sequence. Spliced after `fetch-bootstrap` (only runs when that escalates); for workflows with ≥2 mutating requests behind an anti-bot signal it runs *first* so the doomed cheaper rungs don't pre-burn the per-IP rate budget. |
| **Backend ladder** | An ordered list of backends `runWithLadder` walks. `FORBIDDEN` and satisfiable `STATE_MISSING` escalate; terminal errors return immediately. `auto` is a meta-value that expands to the cached preferred order or the default. |
| **RequestTransformModule** | An optional sibling module (`request-transform.ts`) referenced by `workflow.requestTransformModule`. Exports `transform(method, url, responses)` — called by the runtime before each outgoing request. Used for URL signing (HMAC, CRC32, OAuth) or dynamic query param injection. The compile-agent writes it when stateHints flag per-call query params and it reverse-engineers the signing function from captured JS bundles. |
| **Probe** | `imprint probe-backends <site> --tool <toolName>` or `imprint probe-backends <site> --all` — runs every applicable backend and caches the working order to `backends.json`. `--tool` is optional for single-tool sites; `--all` refreshes every generated tool for a multi-tool site. Conditional backends like `fetch-bootstrap` are skipped unless the workflow declares state they can produce. |
| **Fetch-bootstrap** | A short-lived Playwright context that seeds credential cookies/storage, navigates to `workflow.bootstrap.url`, harvests cookies/storage/DOM-derived state, closes the browser, and then runs native API replay. It is not a full DOM fallback. |
| **Stealth-fetch** | A short-lived Playwright bootstrap that mints Akamai / Cloudflare / DataDome sensor tokens, then native `fetch()` augmented with those tokens. |
| **Sensor headers** | Bot-detection headers a site's JS injects (e.g. `EE-a`, `_abck` cookie). The stealth bootstrap captures them so plain `fetch()` can replay later. |
| **Token TTL refresh** | Stealth-fetch proactively re-bootstraps when tokens age past `maxTokenAgeSeconds`, and reactively on a 403 response. |
| **Capture** | A named value extracted from a request response or bootstrap page: JSON path, response header, regex text, cookie, localStorage/sessionStorage key, HTML regex, DOM attribute, or DOM text. Captures are referenced later as `${state.NAME}`. |
| **Capture hint** | A pre-built capture block suggestion included in the session summary's `captureHints` array. Generated from `server_derived` dual-pass classifications — specifies the producer request index, capture definition (`source`/`name`/`path`), and which downstream requests consume the value. The compile agent copies these into `workflow.json` instead of discovering value provenance manually. |
| **Inline data** | Full request headers, request body, response headers, and (possibly truncated) response body included directly in the session summary for candidate-scoped requests. Eliminates serial `read_request` / `read_response_body` tool calls. Subject to a 30 KB summary budget — progressively reduced when the total summary would exceed `claude-cli`'s tool-result size limit. |
| **STATE_MISSING** | A typed runtime failure for required state that could not be produced. It carries a capability (`ordinary_http`, `browser_bootstrap`, `stealth_bootstrap`, `credential_required`, or `unsupported`) so the ladder can decide whether escalation is valid. |
| **RuntimeCookieJar** | Per-execution cookie jar used by API replay. It ingests `Set-Cookie`, emits Cookie headers, preserves browser session cookies, detects ambiguous scalar lookups, and guards HttpOnly projection. |
| **Sentinel** | The `[IMPRINT]` prefix on injected DOM-listener console.log lines. The recorder's `Runtime.consoleAPICalled` handler exact-match-checks this. |
| **CDP** | Chrome DevTools Protocol. The recorder uses it (via `chrome-remote-interface`) for Network + Page + Runtime events. |
| **Credential store** | Per-site secrets, cookies, and declared storage values populated by `imprint login` or `imprint credential import`. Three-tier backend resolution: OS keychain (macOS Keychain / GNOME Keyring / Windows Credential Manager) → encrypted file (libsodium secretbox + argon2id) → legacy JSON (read-only migration from v0.0.x). Metadata lives in `~/.config/imprint/manifests/<site>.json`. |
| **Tool candidate** | A potential tool detected during multi-tool teach. When a single recording session contains multiple distinct user intents (e.g., search + book), `tool-candidates.ts` identifies them so each can be compiled into a separate tool. |
| **Replay-and-diff** | An automated dual-pass verification step that re-runs the recorded DOM events in a fresh browser to classify request values as constant, server-derived, or browser-minted. Runs in parallel with triage. Skippable via `--skip-replay`. Classifications feed into `stateHints` and `captureHints` in the session summary. |
| **State hints** | Deterministic equality relationships and value classifications included in the session summary. Three sources: redaction-marker matching (request field equals earlier Set-Cookie or storage key), per-call query param detection, and dual-pass classifications (`constant`, `server_derived`, `browser_minted`). Guide the compile agent's capture and state management decisions. |
| **IMPRINT_TEACH_CREDENTIALS** | Process-scoped environment variable set by `imprint teach` when spawning compile-agent integration tests. Contains a JSON payload `{ site, values }` with the credential values extracted during the redact step. Merged into the credential store at runtime so integration tests can verify workflows without requiring a separate `imprint credential set`. Never written to disk. |
| **Partial compilation** | Fault-tolerant teach behavior: if one tool fails to compile (timeout, bot defense), the others continue successfully. Each tool has a 20-minute default timeout (override with `--timeout`). |
| **Differential param grounding** | Event-correlated request diffing (`param-grounding.ts`) that deterministically maps `likelyParams` to exact request body fields. For each UI event, finds the request it triggered, diffs it against the most recent comparable request of the same endpoint, and reports the changed paths. Handles JSON, `batchexecute` `f.req=` envelopes, and form fields transparently. Surfaced as `EventGrounding[]` in the session summary. |
| **Input provenance hints** | Detection of opaque ids (entity handles, place ids, category tokens) in request bodies that were minted by an earlier response, not typed by the user. `inputProvenance()` in `param-grounding.ts` walks candidate requests for id-like values and searches prior responses for matches. Surfaced as `inputProvenanceHints` in the session summary so the compile agent chains the minting request instead of hardcoding the id. `selfChain: true` indicates the tool's own endpoint minted the value (resolve-then-refine pattern). |
| **Cost accumulator** | An `AsyncLocalStorage`-based mechanism (`tracedWithCostRollup` in `tracing.ts`) that rolls up `llm.cost.*` and `llm.token_count.*` from all descendant LLM spans to a parent span. Used on root spans (`cli.teach`, `cli.audit`) so Phoenix shows the full pipeline cost — including the cache-aware breakdown (uncached input at 1.0×, cache reads at 0.1×, cache writes at 1.25×). |
| **CDP pool** | A per-site reusable Chrome instance for the `cdp-replay` backend at runtime. Instead of launching a fresh browser per tool call (~33–35s cold start), the pool keeps a live Chrome page open across calls, cutting per-call overhead to ~2–5s. Keyed by site; managed by the MCP server with a 5-minute idle timeout. |
| **NotifyWhen** | A predicate config in `cron.json` that decides whether a successful tool result is interesting enough to push (e.g. `price_below`). |
