imprint-mcp 0.6.6 → 0.7.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to Imprint. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) (Added / Changed / Deprecated / Removed / Fixed / Security).
 
+## [0.7.0] — 2026-10-14
+
+### Added
+- Master-led teaching with editable operation plans, focused agent passes, and dependency-aware tool compilation.
+- Independent verification receipts and retained evidence for generated tool and producer-to-consumer checks.
+
+### Changed
+- Partial teaches keep ready tools but exit nonzero when planned work remains unresolved.
+- `imprint teach` emits the MCP server; `imprint install` connects it to an AI platform.
+- CI runs the network-isolated verifier suite on macOS and static checks on Linux.
+
+### Fixed
+- Cancelled teaching work no longer starts a late tool invocation.
+- Completed native assignments release their prompt and response data from the active queue.
+- `.redacted.json` is atomically replaced with private file permissions.
+- A whole-playbook deadline governs a hanging step even when its step timeout is nearby.
+
+### Validation
+- The Flights58 run completed with 14/14 tools and passed 30/30 independently graded cases, including fresh booking chains. Flights59–62 ended partial, so repeatability and Hotels destination/date validation remain outstanding. See [the validation timeline](timeline.md).
+
+---
+
 ## [0.2.0] — 2026-05-14
 
 v0.2 overhauls the teach-to-tool pipeline, adds full observability tracing, and introduces state-aware API replay. 12 new features, 7 bug fixes across 24 commits.

package/README.md

@@ -20,6 +20,21 @@ The recording *is* the executable.
 
 ---
 
+Authentication work stays visible through operation handles and reusable context
+references. Agents choose whether to continue a retained context or start another;
+native verification and browser checkpoints return within the same assignment.
+Native compiler tools share the host executor; failed calls retain their duration
+and error code so a live process cannot hide a broken compiler connection.
+Plan/research differences are advisory construction facts. Changed artifacts still
+need their own live checks. See [authentication and repair](docs/architecture.md#agent-questions-and-authentication).
+
+Timed-out questions release the terminal input queue; declared nonsecret choices
+remain readable by the agent. Successful browser-backed data calls can preserve
+renewed cookies for later calls without overwriting newer saved authentication.
+Same-name host-only and domain cookies keep their distinct scopes across replay
+and browser restoration.
+That continuity still needs verification against the requested data operation.
+
 ## Quick Start
 
 ```bash
@@ -27,7 +42,7 @@ bun install -g imprint-mcp
 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.
+A browser opens. You drive the workflows and narrate what you're doing. Imprint records every request and interaction, then compiles the complete discovered set of deterministic **MCP tools** your agent can call later.
 
 Want to try a finished MCP before recording anything?
 
@@ -81,7 +96,7 @@ regenerate/record it with `bun scripts/demo-teach.ts`.)*
 </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>
+<p>Builds an API workflow when the recording supports one. A DOM playbook is the final fallback, used only when the agent finds the faster replay paths incompatible.<br><br>Known login credentials are replaced with credential placeholders; other recorded data remains available to the agents.</p>
 </td>
 <td align="center" width="34%">
 <h3>3. Use</h3>
@@ -91,12 +106,305 @@ regenerate/record it with `bun scripts/demo-teach.ts`.)*
 </table>
 
 > [!TIP]
-> All three steps happen in a single `imprint teach` command. Credentials and PII are redacted automatically before anything reaches the LLM.
-
-When one recording yields multiple tools, all candidates are selected by default.
-Imprint automatically includes upstream lookup/producer tools required by any
-selected downstream tool. Use `--primary-tool` to compile only the primary tool
-and its prerequisites; `--all-tools` makes the default full-set selection explicit.
+> Recording and compilation happen in one foreground `imprint teach` command. Install the completed tools in your MCP client with `imprint install`. Only known user-supplied login credentials are replaced before teaching; cookies, API tokens, responses, and personal data remain visible to the agents.
+
+Existing `${credential.NAME}` references in an already-redacted recording reuse
+values from your local credential backend. They do not replace saved passwords
+with placeholder text. MFA may still require your input.
+
+Request-building errors return to the compile agent as verification feedback,
+including errors from asynchronous transforms, so it can repair the request
+and retry.
+
+Recordings and logs, including files named `.redacted.json`, are not safe to share publicly. Automatic PII and token redaction is disabled; review any file before sharing it.
+Imprint writes `.redacted.json` with private file permissions. A teach that leaves
+planned tools unresolved reports a partial result and exits nonzero, even if some
+ready tools were published.
+
+Teaching agents and standalone compilers can ask questions in the foreground
+terminal, including login approvals, MFA/OTP codes, and missing information.
+Questions from concurrent agents appear one at a time; secret input is masked
+and returned to agents as temporary references. Authentication uses the existing
+auth compiler to continue the same browser and challenge. Later recovery requests
+retain that auth work within the teach. Agents first check or restore existing
+access before starting another login. Compiled actions can branch on current
+responses to reuse authenticated access or continue an observed challenge;
+retaining a browser alone does not guarantee MFA is avoided.
+Identical concurrent requests share the active
+attempt; a previous success never substitutes for the caller's own data check.
+Failed teach checks reach a focused component recovery agent before broader
+plan repair. It can renew authentication, repair the caller's artifact or a
+declared prerequisite through its retained compiler, or dispatch a registered
+shared runtime component owner. State recovery immediately retries the built
+caller; prerequisite repair rebuilds the selected owner and binds fresh outputs
+into consumer checks. Accepted contracts and unrelated builds remain intact.
+Every actual failed and retried call stays in the check history. Unknown owners
+or changes to contracts, strategy, or dependencies return to the master.
+When the live login offers a flow missing from the recording, the auth agent can
+operate its verification browser and capture additional request/response evidence.
+It can learn the offered flow before requesting the actual OTP or approval, then
+compile and verify its replay. Original recordings remain unchanged; discovering
+or manually completing a flow alone does not prove reusable authentication.
+Run without
+`--no-interactive` when answers may be needed. Detached runs and piped terminals
+report input as unavailable. Browser closure during stealth user-agent setup
+returns through the existing setup-error handling instead of terminating teach.
+On hosts with limited RAM or disk for swap, set `IMPRINT_TEACH_LOW_MEMORY=1`
+to run live data checks one at a time. Successive checks in the same research
+pass reuse its browser; a competing pass evicts that browser before using its
+own isolated context. Authentication keeps its persistent browser across MFA prompts.
+Closing an Imprint-owned browser removes its temporary Chrome profile. Explicit
+profiles, including `record --persist-profile`, are retained; recordings and run
+evidence are stored separately.
+
+For every teach, a master agent accounts for the complete discovered operation
+set. Focused advisors review tool boundaries and parameters, focused planners
+map one tool at a time, and focused compilers build one tool at a time. The
+master chooses the build waves: independent tools can run together, while a
+producer runs before its consumers. Failed checks return factual evidence to
+the master, which can revise the affected tool and its dependants without
+rebuilding unrelated tools. Recorded response availability is supplied before
+MVP selection. The boundary advisor and master receive the same human scope.
+Agents choose separate tools for distinct recorded purposes before narrowing each
+tool's inputs; unsupported purposes remain explicit coverage limits. Invalid focused-planner reports return exact diagnostics to the
+master for repair while preserving successful sibling proposals; they never
+become accepted execution plans. The retained master receives changed research
+handoffs without repeatedly resending unchanged history; host validation still
+uses the full evidence. Codex teaches use one native agent family, with up to ten
+concurrent children. Agents can delegate further and continue the same conversations
+through repairs. Each research pass stays in one native assignment: test and
+inspection results return directly to that researcher, with the same host validation.
+Master, planner and reviewer repairs and shared-memory queries use that same channel,
+without routing every intermediate response through the parent.
+Inspected alternative requests carry their nearest recorded action, and agents
+explain how any substituted request compares with the selected purpose. Shared
+research delivers a short index; detailed methods and failed approaches are
+stored as immutable assets that agents read only when relevant.
+Independent research calls keep separate browser state and reserve paced start times
+without holding a shared site lock through slow responses.
+Master-directed follow-ups resume the same child. Codex owns child lifecycle and concurrency; Imprint retains
+provider retries, deadlines, execution tools and strict evidence checks. Other
+providers retain their existing execution paths with four focused workers.
+Independent research repairs share the master’s parallel waves; dependent repairs,
+compilation and execution follow the accepted producer ordering. Compiler conversations
+survive revision-directory changes, and finished tools enter verification immediately
+while independent siblings continue compiling. Consumers still wait for verified producers.
+Capture timeouts group repeated endpoint facts so telemetry does not crowd out
+distinct responses, while keeping matching and readiness rules unchanged.
+Research request diagnostics also show bounded decoded body differences, helping
+agents distinguish changed inputs from accidental nesting or encoding changes.
+Agents judge those differences; they are not an automatic pass/fail rule.
+
+Before that tool's planning, one retained researcher conversation first proves the
+smallest useful API call. If part of the selected MVP contract or a required
+downstream value is still unproven, the researcher returns that working partial
+result instead of pretending it is complete or discarding it. Optional breadth
+waits for the later best-effort pass. Once all first passes finish, the master
+can send the exact missing question back to that same conversation with only
+the relevant sibling results and recorded requests.
+An independent proven tool can prepare its plan and compile a draft while
+other research continues, when no queued research needs that attention. The master still
+reviews the complete plan before normal verification and publication; only an
+exactly matching draft is reused. With native delegation, completed research reaches
+the master while unrelated drafts finish. Those drafts settle before final planning
+can reuse or replace them. Declared consumers retain producer-first ordering.
+The terminal names each tool entering detailed planning and each master review,
+reports elapsed waiting time every 30 seconds, and reports when that stage
+finishes or stops. A waiting update means the stage has not returned yet.
+Researchers can call proven sibling requests with fresh inputs before testing a
+consumer; recorded continuation values are not a substitute for fresh output.
+Compilers can inspect full retained responses from that tool's earlier research
+through a local index, then choose relevant repeat and contrast cases for offline
+checks. Each observation keeps its own inputs, outcome and response chain. Researchers can
+query an entire retained response with a bounded, offline data projection; failed
+queries return for repair, and projected output is labelled separately from raw text.
+Teaching now selects a fixed set of recording-backed examples and matches live calls to those examples, changing only expired dates or state. A separate evidence reader establishes expected facts from raw recorded/live responses before seeing parser output, then judges the parser against those facts. Citations can quote the original response bytes or their displayed JSON representation. Each selected live case is reviewed against its matched recorded response chain; unrelated fixtures are left for their own case reviews. Every selected live case and declared dependency chain must pass before publication. Missing coverage is unverified, and raw failures stay with the draft for repair. Fixture bodies are checked before compilation, and research history and inspected recording evidence survive same-run contract revisions. Grounded input mappings are kept separate from the limits of the recorded test cases; missing contrasts alone should not freeze a tool to recorded constants. Research can batch selected calls sequentially and retain isolated browsers during agent thinking. Bootstrap snapshots are cached separately by the requested URL, and capture failures show which matcher conditions failed; cold-start setup remains unchanged. Readiness failures state when no actions have started, and schema repair errors name the exact required fields. These checks need fresh repeated validation before a reliability claim.
+
+Repair or extend an installed data tool with `imprint refine <site> --tool <name> --issue "<change>" --from-session <recording.json>`. Refinement works in an isolated staging home, preserves existing parameter contracts, and requires recording/live verification plus a strict audit before replacement. Failed refinements preserve installed tools and local evidence. Use `imprint audit <site> --strict` to reject known broken calls even when the aggregate score exceeds 95%. See [targeted refinement](docs/refinement.md). Audits forward explicitly set browser settings (`CHROMIUM_PATH`, `IMPRINT_CDP_HEADED`, `IMPRINT_JAR_MAX_AGE_SECONDS`, `IMPRINT_PROXY`, and `DISPLAY`) into their isolated MCP server for either audit provider. See [audit troubleshooting](docs/troubleshooting.md#imprint-audit--scoring-a-sites-generated-tools).
+
+MVP reviewers see the checked request and parser code alongside live results.
+Publication retains the backend from that exact reviewed passing call in
+`backends.json`, so a fresh MCP process starts on the tested path. This records
+one execution choice, not a cold/warm benchmark or proof of repeatability.
+They also receive actual research comparisons and inspected response excerpts,
+not just the researcher's explanation of what those tests proved.
+Agents are instructed to distinguish competing meanings of ambiguous fields
+with focused evidence, rather than treating a coincidentally matching number
+as proof. Uncertain mappings go back to the master for research or a narrower MVP.
+Invalid research handoffs also return to the master with their actual test
+history, rather than ending the whole teach or counting as an API failure.
+Browser snapshots are reused by tool and rung without cookie-name requirements.
+An explicit bootstrap URL runs before resolving request URLs that need its
+captured state. MCP closes an idle or timed-out tool's CDP sessions without
+closing another tool's browser, and a cancelled call does not start another rung.
+Fetch-bootstrap tries the API request before deciding whether to escalate; a
+missing cookie marker is not reported as an HTTP failure.
+Rewording auth or token notes reuses that proof; the master explicitly requests
+new research when the actual strategy changes.
+The final reviewer receives the same human scope and checks requested tool
+connections rather than requiring explicitly excluded operations.
+If an agent mistypes run metadata, repair feedback supplies the exact current values.
+Recorded page references support generated API-navigation URLs; the final URL
+need not appear literally in the recording, but must be grounded and live-tested.
+Tool handoffs use agent-selected concrete result paths, not array wildcards.
+Binding failures explain the path problem and distinguish it from an API call failure.
+Result reviewers see the actual invocation inputs; an unrelated planned test's
+expected answer is never substituted for the research baseline or a chain call.
+A successful chain result can be reviewed even if a standalone test failed;
+that failed test remains visible and still prevents completion until repaired.
+Compiler guidance separates a returned value's location from its meaning and
+omits uncertain optional metadata instead of filling it from unrelated matching
+shapes. Extra responses used to corroborate research stay in the evidence;
+required execution requests must contribute necessary state or core output.
+Agents ground rendered-result completion checks in core content and inspect
+observed layout variations before treating an incidental element as required.
+Agents can scope a background response capture to a specific navigation click.
+Requests started before that action cannot satisfy the capture, including ones
+that finish later. Without an action boundary, capture starts with navigation.
+Navigation clicks wait for the selected target to become clickable within the
+existing navigation deadline, then dispatch once. Failed clicks report bounded
+match, geometry, computed-style and center-hit facts so agents can repair their
+chosen interaction from actual page evidence.
+Before accepting a navigation capture as reusable, researchers repeat a valid
+input and compare a small core-input variation with the same candidate. They
+reuse existing decisive observations and distinguish session reuse from setup.
+When a background capture fails despite current page results, agents inspect
+their delivery source, including structured document data. Changing the baseline
+input does not repair the failed valid case. Reviewers trace ambiguous metadata
+to its context; matching keywords or units alone cannot justify a named field.
+Compilers test the complete current research response before live validation,
+including result frames beyond initial metadata, alongside recording examples.
+For a request chain, they receive its actual ordered response bodies as a local
+offline fixture. They test associations using current response identities and
+unmatched records, rather than copying one example's values into parser logic.
+For framed protocols, a small parser test checks that an earlier empty or metadata
+frame does not hide later records; agents derive the expected result from evidence.
+Failed browser calls can include bounded page evidence from browser inspection,
+including through fallback and MCP audit errors. Agents use it to investigate missing
+captures without treating a timeout as automatic infrastructure failure or rendered
+text as API success. Network-capture timeouts also include a bounded list of
+observed response endpoints, methods, resource types, statuses and navigation
+scope facts, with omitted counts. These facts help agents compare a failed
+matcher with actual traffic; they do not change response selection.
+Parser checks distinguish unsupported missing fields from evidenced protocol defaults.
+Auditors receive exact report tool names.
+Planning and final review also check how callers obtain required inputs,
+without relying on identifiers hidden in the recording.
+Research uses a small contrasting core-input check before claiming parameter
+mappings are proven; optional parameter breadth remains deferred.
+Agents check the advertised meaning, not just whether results change; a range
+contrast distinguishes its bounds from a fixed result region that merely moves.
+Handoffs identify the response evidence that establishes the core records' scope
+for the compiler to preserve. Demonstrated ignored inputs return for contract
+revision; they are not deferred as optional minimization. Audits distinguish a
+bound pair's combined behavior from proof of each input's individual effect.
+For rendered results after navigation or actions, agents verify that the current
+collection finished rendering; document load, a page shell, or an updated control
+alone cannot establish readiness. When timing is uncertain, agents compare
+initial setup with changed-input calls in the same tool's warm session.
+Selection handling respects structured field boundaries and complete identities.
+Checking an input does not prove that it selects the corresponding result.
+That contrast must distinguish claimed mappings from defaults; changing one
+input does not prove the others, and unproven mappings return for follow-up.
+The master reviews that evidence even when research labels itself proven;
+missing proof within one tool can return to its retained researcher.
+Live verification uses the planner's selected test inputs, not a replacement
+with the research baseline; the proven backend remains reusable.
+The planner chooses that first live case to challenge weak core evidence;
+additional unexecuted cases are not claimed as coverage.
+Research handoff repair reports independent missing fields together, so one
+repair turn can correct the candidate, test reference, and remaining proof gaps.
+If a repair exposes further schema errors, the same conversation can correct
+them within the shared deadline. Identical rejected outputs stop the repair loop;
+invalid decisions never execute.
+Blocked terminal counts include unresolved discoveries even when no tool was planned.
+Researchers can inspect or search bounded portions of retained live results,
+including HTML attributes and embedded state, without repeating the API call.
+Compilers receive the selected research call's full saved response and inputs
+for offline parser tests, not just a written summary. This evidence stays out of
+published runtime artifacts.
+After live failures, the master can return an unchanged tool to its retained
+researcher with the actual failure evidence, then replan only the affected tool.
+MVP reviewers receive the checked build's parser to distinguish observed values
+from input echoes; audits require an attributable effect, not merely changed ordering.
+Server-returned query text is also an echo, not proof of applied settings.
+Final review also sees prior semantic rejections and their actual inputs, so a
+later passing baseline does not silently erase an unresolved core failure.
+MVP reviewers check returned values against their claimed meaning: optional
+breadth can wait, but mislabeled data is a repair, not polish.
+If the Codex child reports missing stdin despite a non-empty prompt, Imprint
+retries that exact delivery once on the same conversation and deadline.
+
+Researchers can return a concrete input or dependency gap for a master decision
+without exhausting transport permutations. The master coordinates affected
+producer outputs and consumer inputs together; fresh live proof is still required.
+Agents can plan repeated calls to the same tool and bind each call to an exact
+prior result. The runtime checks a finite invocation order and invalidates dependent
+proof when that source result changes; a continuation does not require a separate
+public tool. Existing single-call plans retain their behavior.
+Chain checks and audits compare actual producer record structures with the
+consumer's public contract. One selected record can contain several members;
+unless explicitly excluded, an available fresh multi-member record is checked
+and compared with the complete consumer result.
+A passing singleton check does not establish that every selected member survives.
+Validation, request construction, and parsing keep group properties separate
+from member properties; a valid group need not repeat its overall fields on every
+member. Parsers preserve the distinction between alternatives and required
+components, including when action links exist only on components. Verification
+compares eligible source records with the output and checks each attribute against
+its own evidence; a plausible subset or matching sibling value is insufficient.
+Missing optional details must not erase required members, and constructed
+selections must preserve the complete selected record through the consumer result.
+Reviewers also report
+explicit parser or request guards that reject inputs allowed by the public contract;
+a fixture's shape must not silently become a restriction on callers.
+
+Generated modules reload from their resolved filesystem paths, so repeated
+research tests also work when the teach directory is reached through a symlink.
+Generated wrappers forward caller cancellation and request/response observation
+callbacks. Cancellation reaches active fetch requests and response reads; a
+cancelled call is reported separately from a request timeout. Raw prepared-request
+observations stay inside host diagnostics. Parsers distinguish a valid empty
+result from a missing or unsupported result envelope.
+
+Semantic agents receive the current shared deadline and remaining time on each
+turn, including output repairs, so they can budget for compilation and live
+checks. Repair feedback identifies missing fields by path and expected type,
+including whether a list or scalar is expected. Invalid output remains rejected.
+Baseline and dependency API calls are cancelled when that budget expires,
+with a short bounded cleanup period; late results cannot become successful checks.
+Exhausting the run deadline is reported as a failed run; provider
+unavailability is reserved for an actual provider interruption.
+
+Every teach is fresh and stays in the foreground until it reaches a terminal
+result. There are no resume, phase-window, primary-tool, or partial-selection
+modes. A run succeeds only when every planned tool is verified; otherwise the
+terminal reports the failure honestly and exits non-zero.
+
+For an API operation that only the page can construct, a workflow navigation
+may explicitly select one matching live background response and return its body
+to the parser. The teaching agent derives that matcher from recording evidence;
+the runtime does not guess which request matters or turn the capability into a
+site rule. The recorded response used for offline checks is separate from the
+response order in a fresh live call. Playbooks remain the final fallback.
+
+During research and compilation, request transforms can compute navigation
+targets and click actions from current inputs or earlier responses. The declared
+API response matcher stays fixed so live and offline checks select the same data.
+Dependent selections preserve the machine values required by the next tool.
+Producer compilers receive the current tested consumer construction for declared
+links, so they can check the required representation instead of guessing from names.
+Adding contextual recording references preserves request proof when the tested
+request and public inputs remain covered; executable request changes still need
+matching proof. Parser tests compare contrasting fixture records and check that
+reported summaries agree with their underlying data. They retain records with
+absent optional fields and distinguish requested context from observed attributes.
+Provider capacity failures retry the same conversation within the existing
+deadline; deterministic request and access errors remain terminal.
+Compile-time browser cleanup waits for concurrent calls to finish; one completed
+request cannot idle-close another request's active browser.
+MCP failures include the completed backend attempts and timings, so a final
+fallback error does not hide an earlier navigation timeout.
 
 The recorder also has a bounded fallback for Next.js React Server Component
 responses that Chromium evicts before `Network.getResponseBody` can read them.
@@ -166,6 +474,9 @@ bunx playwright install chromium
 | 4 | Cursor | `cursor` on PATH |
 
 Override with `--provider <name>` and `--model <name>`.
+Codex teaching defaults to `gpt-6.1-sol`. Keep the Codex CLI current when using
+that model for audits or standalone compilation; older installations may reject
+it even when the Codex app offers it.
 
 </details>
 
@@ -196,21 +507,28 @@ The full order is `fetch → fetch-bootstrap → cdp-replay → stealth-fetch
 
 For bot-protected sites, `imprint probe-backends <site> --tool <toolName>` writes a `backends.json` preference cache so cron and MCP start from the known-good backend instead of rediscovering blocked rungs. Use `imprint probe-backends <site> --all` to refresh every tool in a multi-tool site; `imprint mcp status` reports stale or invalid backend caches before they quietly fall back to the default ladder. CDP replay records both cold and warm timings when it succeeds: a timeout-safe cold start may rank by its fast warm runtime, but a cold start above the preferred threshold stays behind cold-safe backends in durable cache order.
 
-During `imprint teach`, the independent final verifier uses the same probe before it runs the compiler-written integration suite. Probe time is separate from the suite timeout, and verification pins the selected backend. Compiler revisions reuse that proven preference without probing; only a transport/network/browser failure can prompt a reprobe. Semantic failures return directly to the compiler. Live verifier progress and retained suite receipts are written beside the generated tool as `.live-verifier-log.jsonl` and `.live-verification-evidence.json`.
+During `imprint teach`, each tool goes through contract, replay, live, and
+producer-consumer checks as applicable. The checks leave factual receipts. A
+failure goes back to the master for a focused repair, and an independent final
+reviewer sees both the current plan and the check history before the run can
+complete.
 
-Every recording compiles to *both* `workflow.json` and `playbook.yaml`, so the ladder always has a DOM fallback.
+The agent prefers an API `workflow.json`. It adds `playbook.yaml` only as the
+last fallback when the higher replay rungs are not compatible with the
+recorded operation.
 
 ---
 
 ## Platform Support
 
-At the end of `imprint teach`, pick your AI platform and Imprint wires it up:
+After `imprint teach` completes, register the generated site with
+`imprint install <site> --platform <platform>`:
 
 | Platform | Integration |
 |:--|:--|
-| **Claude Code** | Automatic — runs `claude mcp add` |
-| **Codex CLI** | Automatic — runs `codex mcp add` |
-| **Claude Desktop** | Paste-ready JSON config |
+| **Claude Code** | Runs `claude mcp add` |
+| **Codex CLI** | Runs `codex mcp add` |
+| **Claude Desktop** | Writes or prints the MCP config |
 | **OpenClaw** | MCP config + SKILL.md export |
 | **Hermes** | MCP config + SKILL.md + cron mapping |
 
@@ -269,16 +587,20 @@ imprint <command> --help    # per-command options
 
 | Category | Commands |
 |:--|:--|
-| **Pipeline** | `teach` · `record` · `redact` · `generate` · `compile-playbook` · `emit` |
+| **Teaching** | `teach` (the single fresh foreground flow) |
+| **Artifact utilities** | `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` |
 
+The artifact utilities are useful on individual files, but they are not
+resumable phases of `imprint teach`.
+
 ---
 
 ## Sharing Skills
 
-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:
+Teach on your laptop, ship to a remote agent. Generated MCP folders contain the portable tool artifacts: `workflow.json` or the fallback `playbook.yaml`, `index.ts`, optional parser/request-transform 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
@@ -342,3 +664,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
 **[MIT License](LICENSE)**
 
 </div>
+
+Teach research retains each received response before later requests, extraction, or parsing can fail. Agents can inspect bounded excerpts of failed calls without repeating them; those responses remain failed evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imprint-mcp",
-  "version": "0.6.6",
+  "version": "0.7.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": {
@@ -56,6 +56,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@napi-rs/keyring": "^1.3.0",
     "@noble/hashes": "^2.2.0",
+    "@openai/codex-sdk": "^0.159.2",
     "@opentelemetry/api": "^1.9.1",
     "chrome-remote-interface": "^0.33.0",
     "env-paths": "^3.0.0",
@@ -64,7 +65,6 @@
     "playwright": "^1.49.0",
     "playwright-extra": "^4.3.6",
     "puppeteer-extra-plugin-stealth": "^2.11.2",
-    "redactum": "^1.1.0",
     "semver": "^7.8.4",
     "tldts": "^7.4.8",
     "yaml": "^2.8.4",

package/prompts/audit-agent.md

@@ -1,3 +1,5 @@
+When the initial task supplies recording-backed fixed cases, use that list instead of creating additional challenges or sweeping unrelated parameter combinations. Preserve the recorded operation and coupled inputs, updating only expired dates/state and using fresh producer outputs. Report each supplied caseId on its corresponding invocation. Missing coverage is unverified. This fixed-case policy takes precedence over general differential-sweep instructions below.
+
 # Imprint Audit Agent
 
 You are an automated QA auditor. A set of eligible MCP tools is connected to you. Each tool replays a real workflow that was captured from a browser session and turned into a deterministic API call. Your job is to exercise every connected tool, and every parameter advertised by data tools, decide whether each behaves as described, and return a single structured report. Human-interactive authentication and irreversible workflows are excluded by the harness and must never be initiated by you.
@@ -19,18 +21,19 @@ Your priority is **functional coverage, not edge cases.** A tool that returns da
    **Verify the result is actually FOR what you asked.** A well-formed response is not automatically correct — check that it answers your specific inputs. If you searched for a place/entity, confirm the response is for THAT place/entity: the returned records, any echoed area/scope label, and identifying fields (addresses, names, ids) must match what you requested, not some other value the backend defaulted to. A response that is structurally perfect but for the **wrong entity** (a different place, a different account, an ignored search term that silently fell back to a default/IP-geo result) is `tool_broken`, not `correct`. This is the most common silent failure: the input parameter reached the API but was ignored, and the tool returned confident, well-shaped results for the wrong thing.
 
 3. **Differentially test EACH advertised data-tool parameter.** This is the core of the audit. For every optional/filter/sort/option parameter a data tool exposes, make one more call **identical to the baseline except that single parameter**, set to a value that *should* visibly change the result per its description. Do not apply this procedure to authentication tools. Compare the new result to the baseline and classify the parameter with exactly one `verdict`:
-   - `works` — the result changed the way the description promises (a filter added/removed/reshaped results; a sort reordered them; a mode/basis changed the relevant field). Name the observed change in the reason.
+   - `works` — the result changed the way the description promises, with evidence attributable to that parameter (a filter changed matching records; a sort obeyed its requested ordering; a mode/basis changed the relevant field). Name that evidence, not merely that two responses differed.
    - `no_op` — there is positive evidence that the parameter is inert: use a meaningfully discriminating value and show that the response still reflects the baseline value or otherwise ignores the requested change. A single unchanged comparison is not enough for conditional inputs such as eligibility, age, inventory, locale, or pricing controls; two valid values may legitimately land in the same behavior class.
    - `broken` — there is positive evidence that the parameter produces a wrong result: it errors because of a valid value, contradicts the requested value, or corrupts the response. An empty result is not automatically broken for inventory-, date-, time-, location-, or filter-dependent reads; empty availability can be the correct semantic result unless a control or returned metadata shows that matches should exist.
-   - `untestable` — reserve this for genuine impossibility, NOT inconvenience. Valid only when: you cannot construct a distinct valid value (an opaque enum/code with no discoverable members and none echoed in any tool's output); OR the action is **state-changing / irreversible** (book/order/pay/send/cancel/delete) so a probing burst would fire real side effects; OR a **bot-defended call stayed blocked (`infra`) across repeated PACED retries**. State which in the reason. **Bot-defense alone is NOT sufficient** — a bot-defended *idempotent read* (search/list/calendar/quote) MUST be differentially probed with pacing (see the differential rule below); marking its params `untestable` without exhausting paced retries is a cop-out. Do not mark a parameter `untestable` merely because testing it is tedious.
-   To isolate the parameter, change only that one field between the two calls. When two parameters interact (e.g. a min/max pair), test the pair together and say so in the reason.
+   - `untestable` — reserve this for genuine impossibility, NOT inconvenience. Valid only when: you cannot construct a distinct valid value (an opaque enum/code with no discoverable members and none echoed in any tool's output); OR valid bound inputs cannot be varied independently and the result cannot attribute an effect to the individual member; OR the action is **state-changing / irreversible** (book/order/pay/send/cancel/delete) so a probing burst would fire real side effects; OR a **bot-defended call stayed blocked (`infra`) across repeated PACED retries**. State which in the reason. **Bot-defense alone is NOT sufficient** — a bot-defended *idempotent read* (search/list/calendar/quote) MUST be differentially probed with pacing (see the differential rule below); marking its params `untestable` without exhausting paced retries is a cop-out. Do not mark a parameter `untestable` merely because testing it is tedious.
+   To isolate the parameter, change only that one field between the two calls. When validity requires two parameters to change together (e.g. a bound producer-returned pair), keep the pair coherent and say so in the reason. That comparison proves the pair's combined behavior, not each member's individual effect or necessity. Grade an individual member `works` only when the evidence supports its own advertised claim; otherwise record the successful invocations and mark that member `untestable` with the attribution limit. Do not mix incompatible values merely to force an isolated test.
+   Echoed inputs, including fields labeled `applied` or `effective`, prove only that the tool repeated the request, not that the website honored it. Inventory, prices and ordering can change between identical requests. If that variability is the only apparent signal, repeat the baseline as a control when useful and look for an attributable effect or independently observed state. A changed list by itself is not proof of an unrelated parameter. If the available tool output cannot distinguish the claim, preserve that lack of proof as `untestable` with the actual attempts; do not manufacture either a pass or a defect.
    For conditional parameters, choose a boundary value likely to cross a behavior class and inspect echoed request metadata as well as result data. If no safely constructible value produces a discriminating observation, use `untestable` and record exactly what was tried. Preserve that ambiguity for the compiler or human reviewer; do not turn absence of proof into a defect.
    Promo/coupon/voucher/discount-code parameters need a **known valid code** to produce a visible discount. If the schema or another tool output does not give you a valid code, do not invent a random value and call an unchanged result `no_op`; mark that parameter `untestable` with the reason that no valid code was discoverable. If you do have a valid code and the request still has no effect, then classify it `no_op`.
 
 4. **Judge the baseline invocation** against what the description and schema promise, with exactly one `verdict`:
    - `correct` — sensible, well-formed, on-topic data matching the description (or a legitimately empty result for inputs that should yield none). Read the payload — do not judge solely on "it returned without throwing."
    - `tool_broken` — the tool ran but the result is wrong: malformed or empty when data was expected, fields missing or mis-mapped, an internal error, the wrong kind of data, or a shape that contradicts the schema/description.
-   - `infra` — environmental, not a tool bug: rate limiting, bot-defense challenge, HTTP 403/429, network error, timeout, or an upstream 5xx.
+   - `infra` — evidence supports an environmental failure, such as rate limiting, bot-defense challenge, HTTP 403/429, connectivity loss, or an upstream 5xx. A timeout while waiting for a selected response or page element does not by itself establish an environmental cause; a workflow can wait for something its actions never produce.
    - `bad_params` — your own mistake: a value the schema/description should have told you was invalid. Use this so the tool isn't penalized for your error.
    Set `ok` to `true` only for `correct`; otherwise `false`. Put a one-line, specific `reason` on every invocation and every parameter verdict (what you sent, what came back, why that verdict).
 
@@ -44,10 +47,28 @@ Your priority is **functional coverage, not edge cases.** A tool that returns da
 - Derive parameters **only** from each tool's schema and description. Never hardcode values for a particular service, brand, or domain — the same procedure must work for any tool you are given.
 - Audit **every eligible connected** tool, and within each data tool, test **every** advertised parameter (subject to the read-type rule above). Do not skip a tool because another failed. Authentication tools are limited to one baseline as described above.
 - Prefer `infra` over `tool_broken`/`broken` when the evidence points to anti-bot, rate-limiting, or network/upstream failure — a blocked request is not a code bug.
+- Inspect supplied failure details and rendered-page evidence before attributing a timeout. A loaded results page alongside a missing expected capture is evidence to investigate the workflow's trigger or response selection, not proof that the requested API tool succeeded. Compare a supported contrasting input when useful. Cite concrete contradictions for `tool_broken`; if the cause remains unresolved, use `infra` with that uncertainty stated rather than inventing bot defense. Keep unsuccessful core tools and their dependent coverage gaps explicit even when the graded score passes.
 - Prefer `bad_params` over `tool_broken` when re-reading the schema shows your own inputs were invalid.
+- Check source coverage when the result or available evidence makes it testable. A bounded collection may legitimately be sparse, but a plausible non-empty subset alone does not prove completeness. Investigate missing eligible records and distinguish observed absence from extraction loss. For related returned attributes that can differ, use an available contrasting record to verify each attribute rather than treating baseline equality as proof. If source coverage cannot be established, report that limit without inventing a failure.
 - Require affirmative evidence before assigning `no_op` or `broken`. The audit reports observations; it does not decide that an otherwise working tool must be removed merely because a secondary parameter is ambiguous or unsupported. Preserve the per-parameter reason so the compile agent can choose to retain, narrow, or omit that surface.
 - **Chain producer-sourced values.** When a parameter's description says to obtain its value from another tool's output field (e.g. "Obtain this from the `search_x` tool's `item_id` output"), that value is produced context you must NOT invent: first call the named producer tool, read that exact field from its result, then pass the value to the consumer (reuse it across calls). Judge the consumer on that real value. If the producer is blocked and you genuinely cannot obtain the value, classify the dependent call `bad_params` and the dependent parameters `untestable`, never `tool_broken`.
 
+Compare the consumer's public contract with the actual producer record shapes.
+One selected record can contain several members even when the description uses
+a singular noun. Unless the public contract explicitly excludes that structure,
+use an available fresh multi-member producer record for a representative chain
+call. Compare all selected members and their order with the consumer result;
+a plausible result for only the first member is not a correct grouped result.
+The consumer may legitimately return components that together cover the selected
+record; each component need not cover every member. Check that their relationship
+and value scopes are explicit instead of assuming component records are complete
+alternatives. Cite a concrete missing or contradictory relationship, not merely
+a component containing fewer members than the overall selection.
+A runtime rejection does not retroactively make a contract-compatible producer
+value bad input. Changing labels between two singleton records does not cover
+this distinction. If no suitable record is available, report the coverage gap
+without inventing a selection or declaring an unobserved failure.
+
 ## Output
 
 End your final message with **exactly one** fenced `json` block and nothing after it. It must parse as this object: