imprint-mcp 0.2.0

package/prompts/intent-detection.md

@@ -0,0 +1,198 @@
+# Imprint Intent Detection
+
+You analyze a captured browser session and produce a deterministic, parameterized workflow that an MCP tool can replay.
+
+## Input
+
+You will receive a JSON object with this shape:
+
+```json
+{
+  "site": "string",
+  "url": "string (starting URL)",
+  "narration": [
+    { "timestamp": ms, "text": "what the user said they were doing" }
+  ],
+  "events": [
+    { "timestamp": ms, "type": "click|input|change|submit|navigation", "detail": "..." }
+  ],
+  "requests": [
+    {
+      "seq": int,
+      "timestamp": ms,
+      "method": "GET|POST|...",
+      "url": "string",
+      "headers": { ... },
+      "body": "string or omitted",
+      "resourceType": "Document|XHR|Fetch|Stylesheet|...",
+      "response": { "status": int, "headers": {...}, "body": "string" }
+    }
+  ]
+}
+```
+
+The narration is in the user's own words and is your most reliable signal of intent. Use the timestamps to correlate narration → events → requests.
+
+Sensitive fields fall into two categories in the input you receive:
+
+1. **Already-templated credentials** — login form values like username/email + password are rewritten to `${credential.NAME}` placeholders BEFORE you see the session. When you see a request body like `username=${credential.username}&password=${credential.password}`, those placeholders MUST be preserved verbatim in your generated workflow.json. The runtime substitutes them from a per-site credential manager (OS keychain) at call time. Do NOT replace these with parameters or the redacted-byte form.
+
+2. **Generic redactions** — other secrets (cookies, auth headers, response tokens) have been replaced with `[REDACTED:N]` markers (N = original byte length). The presence of these tells you "this field was a credential/token in the original capture" — you should treat such fields as parameterized auth that the runtime will inject from the user's credential store. Reference them as `${credential.NAME}` (pick a snake_case name like `csrf_token`, `patron_id`). NEVER hardcode the redacted values.
+
+## Output
+
+You output a single JSON object matching this schema, and ONLY that JSON (no prose before or after):
+
+```json
+{
+  "toolName": "snake_case_verb_phrase",
+  "intent": {
+    "description": "one-sentence human description of what this workflow does",
+    "userSaid": "concatenated relevant narration verbatim"
+  },
+  "parameters": [
+    {
+      "name": "snake_case_param_name",
+      "type": "string|number|boolean",
+      "description": "what this parameter represents from the user's perspective",
+      "default": "optional default value"
+    }
+  ],
+  "requests": [
+    {
+      "method": "GET|POST|...",
+      "url": "https://... — supports THREE placeholder syntaxes (and ONLY these three): ${param.NAME} for user-supplied parameters; ${response[N].JSON_PATH} for values extracted from a prior response in this chain (N is the 0-based index into THIS requests array); ${credential.NAME} for values stored at login time (patron_id, csrf_token, etc.) — anything that's per-user-account state",
+      "headers": { "Header-Name": "value or ${param.X} or ${response[N].field} or ${credential.X}" },
+      "body": "optional — same templating rules as url",
+      "extract": {
+        "json_path_expression": "name_to_use_in_subsequent_${response[N].name}_substitutions"
+      }
+    }
+  ],
+  "site": "string (echo from input)"
+}
+```
+
+## Rules
+
+1. **Pick the smallest set of requests that accomplishes the user's stated intent.** Most captured requests are noise: analytics, asset loads, telemetry beacons, prefetches, font/image fetches. Drop them all.
+
+2. **Identify the LOAD-BEARING requests** — the ones that actually do the user's work (the booking, the search, the post). Keep them in chronological order. There are usually 1-5 of these.
+
+3. **Parameterize aggressively but correctly.** Anything the user would change between runs is a parameter (use `${param.NAME}`). Anything that's identity-specific to this user (their library card patron ID, an internal user UUID, a CSRF token established at login) is NOT a parameter — it's stable per-account state that the runtime injects via credentials (use `${credential.NAME}` and pick a `NAME` that's snake_case and descriptive: `patron_id`, `csrf_token`, `account_uuid`). User-facing things like email or display name CAN be parameters if the user might want to override (e.g., booking a museum pass for a friend's email).
+
+   ALWAYS use `${credential.X}` (never `${auth.X}` or `${cred.X}` or any other prefix) for credentialed values. Consistency matters because the runtime resolves these by literal prefix match.
+
+4. **Detect chained requests.** If request N+1 uses a value that came from request N's response (e.g., a `reservationID` returned by `makeReservation` that's then sent to `cancelReservation`), use the `extract` field on request N to name the value, and `${response[N].name}` in request N+1.
+
+5. **Login request handling.** Examine the captured login request:
+   - **KEEP the login request** when the request body uses `${credential.username}` / `${credential.password}` placeholders (the redaction step has already templated them in for you). The runtime will replay the login each call, get a fresh session, and chain it into subsequent requests via `extract`. This is the right pattern for sites where cookies expire quickly or auth tokens rotate per session.
+   - **DROP the login request** only when (a) there's no login POST in the capture (the user was already logged in via prior cookies), or (b) the user's stated intent has nothing to do with auth (e.g., a public search). In those cases the runtime relies on persisted cookies from `imprint login`.
+   - When in doubt — INCLUDE the login. The runtime tolerates "login already valid" outcomes gracefully; what it can't tolerate is workflows that assume cookies and find them expired.
+   - When you keep a login request, use `extract` to pull any returned auth tokens (`id_token`, `access_token`, etc.) so subsequent requests can reference them via `${response[0].id_token}`.
+
+6. **Drop requests to third-party origins** (analytics, fonts, maps tiles, translation widgets) unless the user's intent explicitly references them.
+
+7. **Drop redirect chains** — only the final destination matters.
+
+8. **Keep request headers minimal.** Drop:
+   - `User-Agent`, `Accept-Encoding`, `sec-ch-*` client hints, `x-client-data`, browser-internal headers.
+   - **Bot-detection / fingerprinting headers** — these have opaque values bound to the original browser session and go stale on replay. Common patterns:
+     - **Akamai Bot Manager**: a per-site randomized prefix followed by `-a`/`-b`/`-c`/`-d`/`-f`/`-z` suffixes (e.g. `EE30zvQLWf-a`, `xY7nQ-c`). The prefix is uppercase+lowercase+digits, ~10 chars, repeated across multiple headers in the same request.
+     - **DataDome**: headers starting with `x-dd-` or `dd-`.
+     - **PerimeterX / HUMAN**: `_px*`, `x-px*`.
+     - **Cloudflare bot**: `cf-*` (except `cf-connecting-ip` if echoed back).
+     - **Generic fingerprinting**: any header whose name doesn't appear in standard HTTP/MDN listings AND whose value is a long opaque base64-ish string.
+   - Drop them all. The runtime will replay without them; the API may flag the request as bot-driven, in which case the failure tells the operator to pivot.
+
+   **Keep**:
+   - `Content-Type`
+   - `Origin` (when the server enforces it)
+   - `Referer` (when the server enforces it)
+   - Genuine CSRF-style `X-*` headers established at login time — parameterize via `extract` from the login response, not as `${param.X}`.
+
+   **Special case — `X-API-Key`**: usually an app-level identifier embedded in the site's JavaScript (every visitor sees the same value). Keep it as a literal string in the workflow. If the redaction step replaced it with `[REDACTED:N]`, the operator should re-run `imprint redact --keep-header x-api-key` and regenerate. Only treat `X-API-Key` as a credential if the value is clearly per-user (e.g., it appears in a `Set-Cookie` after login, or differs between two captures from different accounts).
+
+9. **toolName is a verb phrase the LLM caller would naturally use** — `book_museum_pass`, `search_southwest_seats`, `cancel_reservation`. Snake_case. Specific.
+
+10. **If multiple workflows are present in one capture** (e.g., the user did a booking AND THEN a cancellation as TWO separate intents), pick the MORE SIGNIFICANT one as the workflow — the booking, not the cleanup. The cancellation might be exposed as a chained `extract` step within the booking workflow if the user's narration suggests a "book then cancel" flow, but typically should be its own separate workflow.
+
+11. **Use a domain-aware default for parameters that have a clear repeated value across the capture.** If the user always selected "2 adult passes" you can set `default: 2`. If a date varied, no default.
+
+## Example with login
+
+Suppose the user narrated: "log in to southwest and show me the seat map for my upcoming flight to LAS"
+
+The capture contains:
+- a `POST /api/security/v4/security/token` with body `username=${credential.username}&password=${credential.password}&scope=openid&...` returning `{"id_token": "...", "swa_token": "...", "customers.userInformation.accountNumber": "12345"}`
+- a `GET /api/customers/account/upcoming-trips` returning `{"trips": [{"confirmation": "ABC123"}, ...]}`
+- a `GET /api/extensions/v1/seat-map?confirmation=ABC123&firstName=Ashay&lastName=Changwani` returning a seat map
+
+You would output:
+
+```json
+{
+  "toolName": "get_southwest_seat_map",
+  "intent": {
+    "description": "Log in to Southwest, fetch the user's upcoming flights, and return the seat map for a specific confirmation number.",
+    "userSaid": "log in to southwest and show me the seat map for my upcoming flight to LAS"
+  },
+  "parameters": [
+    { "name": "confirmation_number", "type": "string", "description": "Southwest confirmation/PNR (6 alphanumeric chars)." },
+    { "name": "first_name", "type": "string", "description": "Passenger's first name (matches the booking)." },
+    { "name": "last_name", "type": "string", "description": "Passenger's last name (matches the booking)." }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.southwest.com/api/security/v4/security/token",
+      "headers": { "Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json" },
+      "body": "username=${credential.username}&password=${credential.password}&scope=openid&response_type=id_token+swa_token&client_id=...",
+      "extract": { "id_token": "id_token", "swa_token": "swa_token" }
+    },
+    {
+      "method": "GET",
+      "url": "https://www.southwest.com/api/extensions/v1/seat-map?confirmation=${param.confirmation_number}&firstName=${param.first_name}&lastName=${param.last_name}",
+      "headers": { "Accept": "application/json", "Authorization": "Bearer ${response[0].id_token}" }
+    }
+  ],
+  "site": "southwest-seats"
+}
+```
+
+Notice: `${credential.username}` and `${credential.password}` are emitted verbatim into the login body. The login response's `id_token` is `extract`-ed and chained into the seat-map request's `Authorization` header.
+
+If the same recording also exercised an "upcoming trips list" view, that would typically be a SEPARATE workflow (`list_upcoming_trips`) the user records in another teach run — Claude can call list-then-loop to get all seat maps for upcoming flights.
+
+## Example without login
+
+Suppose the user narrated: "i'm searching for southwest seats on my BUR to LAS flight"
+
+And the capture contained 47 requests — 2 to `southwest.com/api/flights/{id}/seats` (the load-bearing one), 1 OPTIONS preflight, 4 to `analytics.southwest.com/event`, 12 to `*.googletagmanager.com`, 8 image fetches, etc.
+
+You would output something like:
+
+```json
+{
+  "toolName": "check_southwest_seats",
+  "intent": {
+    "description": "Check seat availability on a Southwest Airlines flight by flight ID.",
+    "userSaid": "i'm searching for southwest seats on my BUR to LAS flight"
+  },
+  "parameters": [
+    { "name": "flight_id", "type": "string", "description": "Southwest's internal flight identifier (from a confirmation email or flight search result)" }
+  ],
+  "requests": [
+    {
+      "method": "GET",
+      "url": "https://southwest.com/api/flights/${param.flight_id}/seats",
+      "headers": { "Accept": "application/json" }
+    }
+  ],
+  "site": "southwest"
+}
+```
+
+You DO NOT include the analytics, the GTM, the image fetches, or the OPTIONS preflight (browsers send those automatically; the runtime will too).
+
+Now analyze the input session and produce the workflow.

package/prompts/playbook-compilation.md

@@ -0,0 +1,279 @@
+# Imprint Playbook Compilation
+
+You analyze a captured browser session and produce a deterministic DOM playbook — a step-by-step recipe a real browser can follow to reproduce what the user did. Where the network workflow says "POST this URL with these params," the playbook says "navigate here, type into this field, click that button, wait for that XHR."
+
+## Input
+
+You will receive a JSON object with this shape:
+
+```json
+{
+  "site": "string",
+  "url": "string (starting URL)",
+  "candidate": { "toolName": "optional selected tool scope", "...": "..." },
+  "sharedContext": { "loginRequestSeqs": [1], "...": "optional shared auth/helper guidance" },
+  "narration": [
+    { "timestamp": ms, "text": "what the user said they were doing" }
+  ],
+  "events": [
+    {
+      "seq": int,
+      "timestamp": ms,
+      "type": "click | input | change | submit | navigation",
+      "detail": "JSON-encoded element info — tag, id, name, text, ariaLabel, href, selector, value, fields"
+    }
+  ],
+  "requests": [
+    { "method": "GET|POST|...", "url": "string", "resourceType": "XHR|Fetch|Document|...", "response": { "status": int } }
+  ]
+}
+```
+
+Most events are noise — focus changes, hover, accidental clicks the user reverted. The narration is your highest-signal input: timestamps tell you which events the user actually meant.
+
+If `candidate` is present, compile only that candidate. Ignore other independent actions in the recording unless they are required setup for the selected candidate.
+
+## Output
+
+YAML matching this exact shape, and ONLY the YAML (no prose before or after, no `\`\`\`yaml` fences):
+
+```yaml
+toolName: <snake_case_verb_phrase>
+summary: <one sentence describing what the playbook does>
+parameters:
+  - name: <param_name>
+    type: <string|number|boolean>
+    description: <what this parameter is>
+    default: <optional default value>
+steps:
+  - action: <navigate|click|type|submit|press|wait>
+    # action-specific fields below
+result:
+  source: <xhr|dom>
+  # source-specific fields below
+notes: <optional free-form caveats for downstream agents>
+```
+
+### Step shapes
+
+**navigate** — opens a URL.
+```yaml
+- action: navigate
+  url: https://www.example.com/path
+  wait_for: networkidle
+```
+
+**type** — types into an input.
+```yaml
+- action: type
+  locators:
+    - by: id
+      value: originationAirportCode
+    - by: css
+      value: input[name="origin"]
+  value: ${origin}
+  wait_for:
+    sleep_ms: 300
+```
+
+**click** — clicks an element.
+```yaml
+- action: click
+  locators:
+    - by: aria_label
+      value_pattern: ${origin}
+    - by: text
+      value_pattern: ${origin}
+  wait_for: visible
+```
+
+**submit** — submits a form.
+```yaml
+- action: submit
+  locators:
+    - by: css
+      value: form#search
+  wait_for:
+    xhr: /api/search
+```
+
+**press** — dispatches a key (Escape to dismiss overlays, Enter to submit a focused form, etc.).
+```yaml
+- action: press
+  key: Escape
+  wait_for:
+    sleep_ms: 300
+```
+
+**wait** — explicit wait without an action.
+```yaml
+- action: wait
+  wait_for: networkidle
+```
+
+### Locator priority
+
+Always provide MULTIPLE locators per click/type/submit step, in this priority order:
+
+1. **`by: role`** — `value: button`, `name: "Search"`. Most stable; survives CSS rewrites and a11y improvements.
+2. **`by: aria_label`** — exact `value` or `value_pattern` (regex source). Stable when sites maintain a11y.
+3. **`by: text`** — visible text. Stable for buttons/links with persistent labels.
+4. **`by: id`** — only when the id looks stable (`originationAirportCode` good; `react-aria-:r3:` bad — those are auto-generated).
+5. **`by: css`** — last resort. Captured CSS-Modules class names like `pageContent__3XVqO` change on every site deploy. Include them as a fallback only.
+
+### wait_for values
+
+Strings:
+- `networkidle` — page settled (no network activity for 500ms). Good after nav and submit.
+- `load` — DOMContentLoaded fired.
+- `visible` — the element matched by THIS STEP's locator is now visible. Useful when the locator is the autocomplete option you JUST typed for. NOT useful after clicking a dropdown trigger to open it (the trigger was already visible) — use `sleep_ms` instead.
+- `hidden` — same but for disappearing.
+
+Objects:
+- `xhr: <pattern>` (with optional `method: GET`) — wait for an XHR/fetch response whose URL matches the pattern (substring or regex source).
+- `sleep_ms: <number>` — unconditional pause. Use after clicking a dropdown trigger to give it time to expand, after typing into an autocomplete to give it time to filter, or anywhere a UI animation needs to finish before the next interaction. 300-500ms is the typical range.
+
+### Dropdown / popover pattern
+
+For a click that OPENS a popover/dropdown (trip-type selector, date picker, settings menu), the next click on a dropdown ITEM needs the popover to be rendered first. Use `sleep_ms: 300` on the trigger click — the dropdown's items aren't yet in the DOM at the moment of the trigger click, so `visible` would resolve to the trigger itself and skip the wait.
+
+```yaml
+- action: click
+  locators:
+    - by: text
+      value: Round-trip
+  wait_for:
+    sleep_ms: 300
+
+- action: click
+  locators:
+    - by: text
+      value: One-way
+    - by: role
+      value: option
+      name: One-way
+  wait_for: visible
+```
+
+### Result block
+
+Identify which captured XHR carries the data the user actually cares about (the LAST data-bearing XHR before the user's narration ends, in most cases). Then the path within its JSON body to extract.
+
+**The `extract` path MUST exist in the actual response body.** The input includes a truncated `response_body` for each XHR — read the result-bearing one and walk its real key structure. Do NOT invent paths based on what you think the API "should" return. The path syntax is dot-separated keys with `[]` to mean "iterate every element of this array" — same as the network workflow's substitution syntax. Examples:
+- `data.searchResults.airProducts[].lowestFare.value` (Southwest's actual shape)
+- `flights[].fares[].price.amount` (a different airline's shape)
+
+If the field you want is wrapped in standard envelopes (`data`, `result`, `response`, `payload`), include the envelope in the path.
+
+```yaml
+result:
+  source: xhr
+  url_pattern: /api/search/results
+  extract: items[].price
+  return_as: prices
+```
+
+For pages where the data is rendered to the DOM without an XHR backing:
+
+```yaml
+result:
+  source: dom
+  locators:
+    - by: css
+      value: .price-table tr td.fare
+  extract: text
+  return_as: prices
+```
+
+## Rules
+
+1. **Filter aggressively.** The capture contains every focus change, hover, and accidental click. Use narration timestamps to keep only events the user meant. A 60-second capture for a 5-step workflow should produce 5-10 steps, not 50.
+
+2. **Group autocomplete-then-pick into one step pair.** `input` + `change` + `click` events on a search-then-pick widget are usually two logical steps: type, then click the option. Don't emit a step for every keystroke.
+
+3. **Parameterize what changes.** The user typed "SJC" once during recording, but they'll type many origins at runtime. Make `${origin}` a parameter. Locator value_patterns can interpolate the same parameter so "click the option whose aria-label contains SJC" generalizes.
+
+4. **Same parameter naming as workflow.json when both exist.** If the network workflow uses `origin_airport_code`, the playbook should too. The cron + MCP layer maps params 1:1 across both backends.
+
+5. **Identify wait points carefully.** A click that triggers an XHR needs `wait_for: { xhr: <url-pattern> }` so subsequent steps don't race the response. A nav needs `wait_for: networkidle`. A typed-then-pick autocomplete needs the option element to be `visible` first.
+
+6. **Drop login flows.** Same as the API workflow — login is `imprint login`'s job. The playbook starts from a logged-in state (cookies will be loaded into the browser context).
+
+7. **Keep step descriptions short.** No need for verbose human-readable titles — the YAML is the spec.
+
+8. **The toolName and parameters should match workflow.json EXACTLY when both are produced from the same session.** This lets cron/MCP fall back from API to playbook with the same params.
+
+9. **If the recording shows the user navigating between multiple pages, capture each navigation explicitly as a `navigate` step.** Don't assume single-page.
+
+10. **Output format is strict.** YAML, parsed by `YAML.parse` then validated against the Zod schema in `src/imprint/types.ts` (search for `PlaybookSchema`). Stick to the templates above. **YAML quoting**: if any string value contains colons, single quotes, or YAML-special characters (`{}[]|>&*!#%@`), wrap the entire value in double quotes.
+
+## Example
+
+For a Southwest fare search recording (user typed SJC, picked the autocomplete, typed SAN, picked, typed depart date, clicked search), output:
+
+```yaml
+toolName: search_southwest_flights
+summary: Search Southwest for one-way fares between two airports on a given date.
+parameters:
+  - name: origin
+    type: string
+    description: IATA airport code, e.g. SJC
+  - name: destination
+    type: string
+    description: IATA airport code, e.g. SAN
+  - name: depart_date
+    type: string
+    description: YYYY-MM-DD
+steps:
+  - action: navigate
+    url: https://www.southwest.com/air/booking/
+    wait_for: networkidle
+  - action: type
+    locators:
+      - by: id
+        value: originationAirportCode
+    value: ${origin}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: aria_label
+        value_pattern: ${origin}
+      - by: text
+        value_pattern: ${origin}
+    wait_for: visible
+  - action: type
+    locators:
+      - by: id
+        value: destinationAirportCode
+    value: ${destination}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: aria_label
+        value_pattern: ${destination}
+      - by: text
+        value_pattern: ${destination}
+    wait_for: visible
+  - action: type
+    locators:
+      - by: id
+        value: departureDate
+    value: ${depart_date}
+  - action: click
+    locators:
+      - by: text
+        value: Search
+      - by: aria_label
+        value: Search flights
+    wait_for:
+      xhr: /api/air-booking/v1/.*/shopping
+result:
+  source: xhr
+  url_pattern: /api/air-booking/v1/.*/shopping
+  extract: airProducts[].lowestFare.value
+  return_as: prices
+```
+
+Now compile the input session.

package/prompts/request-triage.md

@@ -0,0 +1,74 @@
+# Imprint Request Triage
+
+You analyze the network requests from a captured browser session and identify which requests are relevant to the user's workflow. Most requests are noise -- analytics, telemetry, config fetches, prefetches, ad beacons, health checks -- even when they share the same origin as the site.
+
+## Input
+
+You receive a JSON object:
+
+```json
+{
+  "site": "string",
+  "url": "string (starting URL)",
+  "narration": [
+    { "timestamp": ms, "text": "what the user said they were doing" }
+  ],
+  "requests": [
+    {
+      "seq": int,
+      "timestamp": ms,
+      "method": "GET|POST|...",
+      "url": "string",
+      "resourceType": "XHR|Fetch|Document",
+      "status": int,
+      "mimeType": "string",
+      "headers": "truncated request headers",
+      "body": "request payload (NOT the response body)",
+      "bodyLength": int,
+      "responseBodyLength": int,
+      "repeatCount": int,
+      "repeatedSeqs": [int],
+      "lastTimestamp": ms
+    }
+  ]
+}
+```
+
+The narration is the user's own description of what they did. Use it to understand the workflow's intent, then select the requests that serve that intent.
+
+Request entries may include `repeatCount`, `repeatedSeqs`, and `lastTimestamp` when identical requests were compacted. Select the representative `seq` unless a specific repeated seq is needed for an intentional multi-step workflow.
+
+## What to include
+
+**Data-bearing API calls** -- requests whose responses carry the data the user was after:
+- Search results (flights, hotels, products, prices)
+- Form submissions (booking, reservation, login)
+- Data fetches that populate the page the user cared about
+- Navigation documents (the HTML pages the user visited)
+- Lookup or resolution endpoints (anything that converts user input into structured data -- e.g. returning locations, IDs, or options the user selects from)
+
+**What to EXCLUDE** (even if same-origin):
+- Analytics and telemetry (`/collect`, `/event`, `/track`, `/log`, `/beacon`, `/pixel`, `analytics`, `telemetry`, `metrics`)
+- Health checks and heartbeats (`/health`, `/ping`, `/alive`, `/heartbeat`)
+- Config and feature-flag fetches (`/config`, `/flags`, `/features`, `/settings`, `/toggle`)
+- Prefetch and preload requests (speculative fetches that the user didn't trigger)
+- Asset manifests and service-worker registrations
+- CORS preflight OPTIONS requests
+- Duplicate requests to the same endpoint (keep only the one whose timestamp aligns with the user's action; if multiple calls to the same endpoint are intentional -- e.g., paginating through results -- keep them all)
+- Third-party API calls to domains unrelated to the user's workflow (ad networks, tag managers, social widgets)
+
+## Deciding what's relevant
+
+1. **Read the narration first.** It tells you the user's goal -- "searching for flights," "booking a hotel," "checking prices." Every request you select should serve that goal.
+2. **Correlate timestamps.** The narration has timestamps; the requests have timestamps. A request whose timestamp falls near a narration event ("now I clicked search") is likely load-bearing.
+3. **Prefer POST/PUT/PATCH over GET** when both exist for the same endpoint -- the mutation is usually the load-bearing one.
+4. **When in doubt, include it.** A false positive (including a noise request) is cheaper than a false negative (excluding the result-bearing XHR). The downstream compilation LLM can ignore noise, but it can't work with data it never sees.
+5. **Aim for 5-50 requests** out of potentially hundreds. If you're selecting more than 50, you're probably not filtering aggressively enough. If fewer than 3, double-check you haven't dropped the key data-fetch.
+
+## Output
+
+A JSON array of `seq` numbers, and ONLY that array (no prose before or after, no code fences):
+
+[3, 17, 42, 98]
+
+The order does not matter. The downstream system will sort by seq.

package/prompts/tool-candidate-detection.md

@@ -0,0 +1,104 @@
+You identify which generated tools should come from one redacted browser recording.
+
+Return ONLY one JSON object. No markdown, no prose.
+
+Schema:
+
+{
+  "sharedContext": {
+    "loginRequestSeqs": [number],
+    "credentialNames": [string],
+    "tokenExtractionNotes": "string",
+    "sharedHelperNotes": "string"
+  },
+  "candidates": [
+    {
+      "toolName": "snake_case_tool_name",
+      "description": "short user-facing description",
+      "rationale": "why this is an independent tool",
+      "confidence": 0.0,
+      "primary": true,
+      "requestSeqs": [number],
+      "representativeSeqs": [number],
+      "eventSeqs": [number],
+      "eventTimeRange": { "startTimestamp": 0, "endTimestamp": 0 },
+      "expectedOutput": "what the tool should return",
+      "likelyParams": [
+        { "name": "snake_case_param", "type": "string", "description": "short description" }
+      ],
+      "dependencySeqs": [number]
+    }
+  ]
+}
+
+Rules:
+
+1. Expose user-facing independent intents as tools. A recording may include one
+   intent or several independent intents.
+2. Do not expose login, auth, CSRF refresh, telemetry, page bootstrap, or
+   tracking as tools. Put login/auth request seqs in sharedContext.loginRequestSeqs
+   or candidate.dependencySeqs instead.
+3. Cleanup, cancel, delete, or undo flows should be candidates only when the
+   narration clearly says they are the user's target.
+4. Shared auth dependency seqs may be reused by multiple tools.
+5. There must be exactly one primary candidate. Pick the candidate that best
+   matches the user's narration and the most complete request/event path.
+6. Use stable snake_case tool names. Prefer verb_object names such as
+   search_flights, book_museum_pass, list_orders.
+7. Candidate requestSeqs should include the load-bearing API requests for that
+   tool. dependencySeqs should include prerequisite requests needed to replay it,
+   especially auth/token requests.
+   Request entries may include repeatCount/repeatedSeqs when identical requests
+   were compacted; use the representative seq unless the repeated seqs are
+   specifically needed to describe the workflow.
+8. expectedOutput should be concrete enough for a compiler to write a parser.
+9. likelyParams should describe user-controllable inputs, not session-bound
+   tokens, cookies, account IDs, or credentials.
+10. likelyParams.type must be exactly one of "string", "number", or "boolean".
+    If a parameter can accept multiple values, describe that in description and
+    use "string" instead of array syntax such as "string[]".
+11. If the recording has only one useful intent, return one primary candidate.
+12. When an endpoint returns a large dataset (high responseBodyLength — e.g.
+    a product catalog, pricing index, or comprehensive listing), prefer it as
+    the primary load-bearing request over smaller supplementary endpoints
+    (status checks, metadata lookups, narrow feeds). Include both in
+    requestSeqs when they serve the same user intent.
+13. When multiple endpoints contribute complementary data for the same user
+    intent (e.g. a catalog endpoint + a supplementary data endpoint), include
+    ALL of them in requestSeqs so the compile-agent can chain them into one
+    workflow and merge the data in the parser.
+14. Lookup or resolution endpoints (any endpoint that converts user input
+    into structured data — returning IDs, codes, options, or entities the
+    user selects from) MAY be separate tool candidates when they serve a
+    standalone use case. Expose them as a separate candidate when the
+    endpoint accepts a user query and returns structured results that an
+    agent could use independently. Include them in dependencySeqs of the
+    primary tool when its parameters depend on the lookup result.
+15. Prefer more candidates over fewer. If a request or group of requests
+    could be useful to a caller on its own — without completing the rest of
+    the flow — emit it as a separate candidate even if the recording used
+    it as a step toward a larger goal. A read-only query that returns data
+    an agent could act on independently is a strong signal for a separate
+    tool.
+16. Every candidate MUST have at least one seq in requestSeqs. A tool with
+    no backing requests cannot be compiled. If you cannot identify the
+    specific request(s) for an action, do not emit it as a candidate.
+17. When the same API endpoint (same URL path and method) is called
+    multiple times with different parameter values — such as toggling
+    filters, changing sort order, adjusting constraints, or paginating —
+    those are parameter variations of a single tool, NOT separate tools.
+    Consolidate them into one candidate and add the varying values as
+    likelyParams. Only split into separate candidates when different
+    endpoints serve genuinely independent intents.
+18. When requestSeqs contains multiple calls to the same API endpoint with
+    different parameter values (autocomplete keystrokes, pagination, filter
+    toggles, sort changes), select representativeSeqs to MAXIMIZE likelyParam
+    coverage. Every likelyParam must have at least one representative where
+    its value is non-default or non-null — a representative where the param
+    is null or absent teaches nothing about its wire position. Start with one
+    baseline representative (all defaults/nulls), then add the minimum number
+    of additional representatives needed so every likelyParam is exercised.
+    Prefer representatives that exercise multiple uncovered params at once.
+    If every seq in requestSeqs is a distinct API call (different endpoints
+    or fundamentally different operations), set representativeSeqs equal to
+    requestSeqs or omit it.