@gaffa-dev/skills 0.1.0

package/skills/gaffa-authoring/templates/sync.md

@@ -0,0 +1,31 @@
+# Template: synchronous request
+
+Use only when the developer wants a blocking call and the expected runtime is well under the plan max.
+Set `"async": false` in the request body.
+The response comes back on the same call, so there is no id to poll.
+
+```bash
+curl -sS -X POST https://api.gaffa.dev/v1/browser/requests \
+  -H "X-API-Key: ${GAFFA_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: gaffa-skill/1.0" \
+  -d '{
+    "url": "https://example.com",
+    "async": false,
+    "max_cache_age": 0,
+    "settings": {
+      "time_limit": 60000,
+      "record_request": true,
+      "actions": [
+        { "type": "capture_dom" }
+      ]
+    }
+  }'
+```
+
+## Notes
+
+- The plan-tiered max runtime (1 / 2 / 5 min) applies to sync calls too.
+  If the job can exceed it, prefer the async-poll template instead.
+- Set the HTTP client read timeout above `time_limit` so the client does not abort a request that is still within its allowed runtime.
+- Everything else (auth, `time_limit`, `record_request`, `max_cache_age`) behaves the same as the async pattern.

package/skills/gaffa-debug/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: gaffa-debug
+description: Use when a gaffa request misbehaves, identified by a brq_* request ID or a script that errors, returns null, times out, or gives wrong output. Pulls the request recording, classifies the failure (gaffa API misuse, target-site change, bot detection, flaky timing, wrong action), and proposes a minimal patch.
+---
+
+# gaffa debug
+
+Given a failing gaffa script or a `brq_*` request id, pull the recording, classify the failure, and suggest a targeted patch.
+Prefers a minimal patch over a speculative rewrite, and recognizes when the target site (not the script) is the problem.
+
+A request id paired with a new extraction goal is ambiguous.
+Ask the developer whether to triage the existing request or start a fresh discovery.
+The only cap that applies is the credits-per-invocation cap on the optional re-run.
+
+## Cost guardrail cap
+
+- `CREDITS_PER_INVOCATION` default `50`.
+  The optional re-run counts against this cap.
+
+## Critical gaffa facts (grounding)
+
+1. Auth header is `X-API-Key: <key>`.
+   Read from `GAFFA_API_KEY` env var.
+   Never hard-code.
+2. `POST /v1/browser/requests` is async by default.
+   Returns an id.
+   Poll `GET /v1/browser/requests/{id}`.
+   Opt into sync with `"async": false`.
+3. Max runtime is plan-tiered (1 / 2 / 5 min) for both sync and async.
+   Always set `settings.time_limit` explicitly.
+4. `parse_json` is token-priced, so its cost scales with the content parsed rather than being a flat per-call charge.
+   Stored `/v1/schemas` extractions run the same `parse_json` action and are priced the same way.
+   Check the live docs for the current model and token rates.
+   Other actions are deterministically priced.
+5. Request recordings (`settings.record_request: true`) are strongly recommended for `/gaffa-debug`.
+   Without one, the skill can only suggest re-running the failing request with recording enabled.
+   Plan-tiered retention applies (7 days / 30 days / 3 months).
+
+The API base URL is `https://api.gaffa.dev`.
+Every `/v1/...` endpoint is called on that host.
+The documentation and the docs MCP live on `https://gaffa.dev`.
+API responses are wrapped in a top-level `data` object, so read fields as `data.id`, `data.state`, `data.credit_usage`, and `data.actions`.
+A finished request has `data.state` equal to `completed`.
+Each action result is a URL in `data.actions[].output`.
+The gaffa edge rejects some default HTTP-client User-Agents (for example Python `urllib`) with a 403, so emitted code should set an explicit `User-Agent` header.
+curl works with its default User-Agent.
+In the request body, `actions`, `time_limit`, and `record_request` go under `settings`, while `url`, `async`, `max_cache_age`, and `proxy_location` are root-level.
+`time_limit` is in milliseconds.
+The `parse_json` action uses a structured `data_schema` of the form `{name, description, fields: [{type, name, description}]}`, never a flat object and never a `schema` or `prompt` field.
+An optional `instruction` parameter sits beside `data_schema` (not inside it) for extra parsing guidance.
+`/v1/schemas` is an endpoint for reusable stored schemas, not an action type.
+LLM-backed extraction runs through the `parse_json` action, with an inline `data_schema` or a stored `data_schema_id`, and there is no separate schema action type.
+On a large content-rich page, `parse_json` over the full DOM can fail with `action_failed` (verified on Wikipedia), so narrow the input with a `selector` for the region that holds the data, or set `input_token_cap`.
+
+## Preferences
+
+General preferences for using the Gaffa API.
+They capture guidance beyond the API docs, and we add to them over time.
+Follow them unless the specific task calls for something else.
+
+- Prefer an inline `data_schema` over a stored `data_schema_id` for `parse_json`, so the end user can see the shape of what is being extracted.
+  Reach for a stored `data_schema_id` only when a shape is registered server-side for reuse across separate scripts or sessions.
+
+## Credential hygiene
+
+1. Read `GAFFA_API_KEY` from env only.
+   Never hard-code in emitted code.
+   Reference it as `${GAFFA_API_KEY}`.
+2. Never echo, log, narrate, or persist the value of `GAFFA_API_KEY`.
+   Never put it in a URL or query string.
+3. Before showing a gaffa recording, error trace, or request body to the user, to an LLM judge, or to disk, strip the values of any fields whose names match (case-insensitive, including vendor-prefixed variants like `gaffa_api_key`): `Authorization`, `X-API-Key`, `api_key` (and `apiKey`, `api-key`), `cookie`, `set-cookie`.
+   Replace the value with `<REDACTED>`.
+4. If the runtime value of `GAFFA_API_KEY` appears as a substring anywhere in a payload you are about to show or persist, replace it with `<REDACTED>`.
+   Only enable this substring scrub when the env value is at least 16 characters long and contains both a digit and a letter.
+   Otherwise skip and warn the developer on first invocation that the entropy floor was not met (field-name and prose rules still apply).
+5. Persisted writes (the `/gaffa-find` reasoning log `./.gaffa-find-<timestamp>.log`, and any other on-disk artifact) go through redaction first, then to a tempfile, then atomic-rename to the final path.
+   A crash mid-write must not leave a plaintext-secrets file on disk.
+6. If unsure whether a string is a secret, redact it.
+
+## Doc-fetching strategy
+
+Resolve documentation queries in two tiers, in order.
+
+1. Preferred: gaffa docs MCP server at `https://gaffa.dev/docs/~gitbook/mcp`.
+   `searchDocumentation` (param `query`) for "how do I do X".
+   `getPage` (param `url`) to fetch one page by URL.
+2. Fallback: live HTTP fetch.
+   `?ask=` against the docs for narrow lookups, `https://gaffa.dev/docs/llms.txt` for breadth.
+   Per-call timeout of 5 seconds.
+
+MCP availability probe, once per session, cached, total budget 10 seconds: JSON-RPC `initialize`, then the mandatory `notifications/initialized` notification, then `tools/list` confirming `searchDocumentation` and `getPage` (or at least one).
+Per-call MCP timeout is 5 seconds.
+Two consecutive timeouts demote to live HTTP for the rest of the session, announced once.
+
+If both tiers fail before any diagnosis work, refuse with a clear message (suggest registering the MCP if none was configured).
+
+## First action
+
+If a `brq_*` id is provided, call `GET /v1/browser/requests/{id}` first to pull the recording.
+If a script is provided without an id, read the script and, when the developer agrees, re-run it once with recording enabled to produce a recording to inspect.
+
+Important limitation of the recording: the `GET` response does not echo the submitted request body or the action configuration.
+Each entry in `data.actions` carries only its `id`, `type`, `timestamp`, an `error` if it failed, and an `output` URL if it produced one.
+So you can see that an action failed and read the top-level `data.error_reason`, but you cannot read the exact parameters that were sent.
+When the misuse is in the request body (for example an invalid `parse_json` `data_schema`), name the most likely cause from the failure signal and ask the developer for the request body or the script, or recommend a re-run with `record_request` plus `capture_dom` and `capture_screenshot` to gather more signal.
+Do not claim to have read a parameter you could not see.
+
+## Behavior
+
+- If `GET /v1/browser/requests/{id}` returns 404, surface the plan-tiered retention reality (Starter 7 days, Startup 30 days, Growth 3 months).
+  The recording has likely expired.
+- If `settings.record_request` was not set on the original request, surface that no recording was captured, so a re-run is needed to inspect what happened.
+- A recommended re-run sets `record_request: true` and adds `capture_dom` and `capture_screenshot` actions.
+- All recording payloads have credential fields scrubbed per the credential-hygiene rules before being shown to the developer, to Claude, or to any LLM judge.
+- If the diagnosis is inconclusive (an expired recording, no recording and no re-run, or a target-side failure with no script-side fix), end the output with one line: *Still stuck? Run `/gaffa-support` to get help or file a report.*
+
+### Failure classification from recording fields
+
+All of these fields live under the top-level `data` object in the response.
+
+- `data.http_status_code` 4xx plus `data.error_reason` indicates gaffa API misuse.
+  Emit a minimal patch.
+- A bare 403 `Forbidden` with no recording and no `data.error_reason`, especially from a non-curl client such as Python `urllib`, often means the gaffa edge blocked the request User-Agent.
+  Recommend setting an explicit `User-Agent` header before assuming a key or permission problem.
+  Confirm by checking whether the same request succeeds from curl.
+- `data.state` is `completed` but an action returned an empty `output` indicates a target-site DOM change versus a wrong selector.
+  Diff the actions against a fresh capture to tell which.
+- `data.error` is `action_failed` on a `parse_json` action has two common, verified causes.
+  First, an invalid `data_schema`: it must be the structured form `{name, description, fields: [{type, name, description}]}`, and a flat object such as `{"title": "string"}`, or a `schema` or `prompt` field, makes the action fail.
+  Second, an un-narrowed large page: `parse_json` over the full DOM of a content-rich page (for example a Wikipedia article) fails even with a valid schema, and the fix is a `selector` for the region that holds the data, or an `input_token_cap`.
+  Check the schema shape first, then the input size.
+  Where the data sits in a stable, well-structured place, say a table or a known element, the third option is to stop using `parse_json` for it: `parse_table` or `capture_element` cannot fail this way, cost the same every run, and are the better patch.
+  Classify that as a wrong action rather than a `parse_json` to be tuned.
+- `data.error_reason` matching bot detection or captcha indicates target-site bot protection.
+  Suggest setting `proxy_location` to a residential location (us, ie, sg, fr), not script changes.
+  If one location is blocked, try another supported location, unless the goal is geo-specific and switching would return irrelevant results.
+- `data.running_time` much greater than `data.page_load_time` indicates flaky timing.
+  Add a `wait` action or raise `time_limit`.
+  Both are duration strings (for example `00:00:01.04`), not numbers.
+- `data.from_cache: true` when fresh data was expected indicates a cross-user cache hit.
+  Set `max_cache_age: 0` to disable, or change a parameter to bust the cache key.
+
+### Patch and re-run
+
+- Prefer minimal patches over rewrites.
+- Before emitting any patch or re-run command, read `templates/rerun-with-capture.md` and follow its request shape exactly.
+  Do not write a request body from memory.
+  Every emitted body must obey these rules, which are the most common mistakes to avoid:
+  - `actions`, `time_limit`, and `record_request` go under `settings`.
+    Never place `actions` at the top level of the body.
+  - `time_limit` is in milliseconds.
+    Use a realistic value such as `60000`, never `60`.
+  - `parse_json` uses `data_schema` (structured), never a field called `schema` and never `prompt`.
+  - Set an explicit `User-Agent` header.
+  - Use the `https://api.gaffa.dev` host and read the key from `${GAFFA_API_KEY}`.
+- Optional re-run defaults to OFF.
+  It requires explicit developer confirmation.
+  The re-run cost counts against `CREDITS_PER_INVOCATION`.
+  Show the credit estimate before re-running and proceed only on an explicit yes.
+
+See `references/failure-classification.md` for the field-to-cause table and `templates/rerun-with-capture.md` for the recommended re-run shape.

package/skills/gaffa-debug/references/failure-classification.md

@@ -0,0 +1,29 @@
+# gaffa failure classification
+
+Map recording fields to a likely cause and the smallest fix.
+Pull the recording with `GET /v1/browser/requests/{id}` and read these fields.
+All fields live under the top-level `data` object in the response.
+The field set includes `data.id`, `data.url`, `data.actual_url`, `data.state`, `data.credit_usage`, `data.http_status_code`, `data.from_cache`, `data.started_at`, `data.completed_at`, `data.running_time`, `data.page_load_time`, and `data.actions` (each action carries its result as a URL in `output`).
+When relevant the response also carries `data.error`, `data.error_reason`, and `data.proxy_location`.
+With `record_request: true` it also includes `data.video`.
+A finished request has `data.state` equal to `completed`.
+
+| Signal in recording | Likely cause | Smallest fix |
+|---|---|---|
+| `data.http_status_code` 4xx plus `data.error_reason` | gaffa API misuse (malformed body, bad field) | One-line patch to the offending field |
+| Bare 403 `Forbidden`, no recording, no `data.error_reason`, non-curl client | edge blocked the request User-Agent | Set an explicit `User-Agent` header. Confirm the same request works from curl |
+| `data.state` `completed` but an action `output` is empty | target-site DOM change vs wrong selector | Diff actions against a fresh capture, then correct the selector or accept the DOM moved |
+| `parse_json` action has `error: action_failed`, no `output` | invalid `data_schema`, or `parse_json` run over the full DOM of a large page | Fix the schema to the structured form first. If the schema is valid, narrow the input with a `selector` or `input_token_cap` |
+| `data.error_reason` matches bot detection or captcha | target-site bot protection | Set `proxy_location` to a residential location (us, ie, sg, fr). If blocked, try another, unless the goal is geo-specific. Not a script change |
+| `data.running_time` much greater than `data.page_load_time` | flaky timing | Add a `wait` action or raise `time_limit` |
+| `data.from_cache: true` when fresh data expected | cross-user cache hit | Set `max_cache_age: 0` or change a parameter to bust the cache key |
+| A `loop` action ends `action_timed_out` | its `timeout` covers all iterations together and ran out | Raise the loop `timeout` or lower the iteration count. Completed iterations keep their outputs |
+| Actions after a `loop` end `action_cancelled` | the loop exited early and cancelled the rest | Set `continue_on_fail: true` on the loop so the actions after it still run |
+| `GET` returns 404 | recording expired past retention | Re-run with `record_request: true`. Retention is 7 days / 30 days / 3 months by plan |
+
+## Notes
+
+- `max_cache_age` and `proxy_location` are root-level body fields, not under `settings`.
+- Always scrub credential-named fields out of the recording before showing it.
+- Prefer the smallest fix.
+  A rewrite is rarely the right first move.

package/skills/gaffa-debug/templates/rerun-with-capture.md

@@ -0,0 +1,31 @@
+# Template: re-run with capture for triage
+
+When the original request had no recording, or you need fresh page state to compare against, recommend a re-run with recording plus DOM and screenshot captures.
+The video lets a human review what happened.
+The DOM and screenshot let an agent inspect page state directly.
+
+The re-run defaults to OFF.
+Get explicit developer confirmation and show the credit estimate first.
+The cost counts against `CREDITS_PER_INVOCATION`.
+
+```bash
+curl -sS -X POST https://api.gaffa.dev/v1/browser/requests \
+  -H "X-API-Key: ${GAFFA_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: gaffa-skill/1.0" \
+  -d '{
+    "url": "URL_FROM_FAILING_REQUEST",
+    "max_cache_age": 0,
+    "settings": {
+      "time_limit": 60000,
+      "record_request": true,
+      "actions": [
+        { "type": "capture_dom" },
+        { "type": "capture_screenshot" }
+      ]
+    }
+  }'
+```
+
+Append the original failing action after the captures when you want to reproduce the failure with full evidence.
+Keep `max_cache_age: 0` so the re-run reflects live page state rather than a cache hit.

package/skills/gaffa-find/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: gaffa-find
+description: Use when the user wants to find or extract a specific piece of information from a target website given only a URL and a plain-language goal but has no gaffa script yet. Iteratively writes and refines a gaffa script through reconnaissance, extraction, and validation, then stops in a clear terminal state.
+---
+
+# gaffa find
+
+Given a target URL and a natural-language information goal, write and refine a gaffa script through reconnaissance, hypothesis, extraction, validation, and refinement, then stop with a clear terminal state.
+Prevents premature commitment to a wrong selector and silent acceptance of empty or wrong results.
+
+## Cost guardrail caps
+
+The skill enforces the caps below.
+
+- `REQUESTS_PER_ITERATION` default `3`.
+  Caps requests inside one loop step.
+- `REQUESTS_PER_INVOCATION` default `15`.
+  Caps total requests per run.
+- `CREDITS_PER_INVOCATION` default `50`.
+  Caps total credits per run.
+- `MAX_ITERATIONS` default `5`.
+  Caps loop iterations.
+
+## Critical gaffa facts (grounding)
+
+1. Auth header is `X-API-Key: <key>`.
+   Read from `GAFFA_API_KEY` env var.
+   Never hard-code.
+2. `POST /v1/browser/requests` is async by default.
+   Returns an id.
+   Poll `GET /v1/browser/requests/{id}`.
+   Opt into sync with `"async": false`.
+3. Max runtime is plan-tiered (1 / 2 / 5 min) for both sync and async.
+   Always set `settings.time_limit` explicitly.
+4. `parse_json` is token-priced, so its cost scales with the content parsed rather than being a flat per-call charge.
+   Stored `/v1/schemas` extractions run the same `parse_json` action and are priced the same way.
+   Check the live docs for the current model and token rates.
+   Other actions are deterministically priced.
+5. Request recordings (`settings.record_request: true`) are strongly recommended for `/gaffa-debug`.
+   Without one, the skill can only suggest re-running the failing request with recording enabled.
+   Plan-tiered retention applies (7 days / 30 days / 3 months).
+
+The API base URL is `https://api.gaffa.dev`.
+Every `/v1/...` endpoint is called on that host.
+The documentation and the docs MCP live on `https://gaffa.dev`.
+API responses are wrapped in a top-level `data` object, so read fields as `data.id`, `data.state`, `data.credit_usage`, and `data.actions`.
+A finished request has `data.state` equal to `completed`.
+Each action result is a URL in `data.actions[].output`.
+The gaffa edge rejects some default HTTP-client User-Agents (for example Python `urllib`) with a 403, so emitted code should set an explicit `User-Agent` header.
+curl works with its default User-Agent.
+In the request body, `actions`, `time_limit`, and `record_request` go under `settings`, while `url`, `async`, `max_cache_age`, and `proxy_location` are root-level.
+`time_limit` is in milliseconds.
+Each entry in `settings.actions` is an object keyed by `type`, for example `{"type": "generate_markdown"}` or `{"type": "capture_element", "selector": "h1"}`.
+The key is `type`, never `action`, and an action object missing it is rejected with `invalid_action`.
+The `parse_json` action uses a structured `data_schema` of the form `{name, description, fields: [{type, name, description}]}`, never a flat object and never a `schema` or `prompt` field.
+An optional `instruction` parameter sits beside `data_schema` (not inside it) for extra parsing guidance.
+`/v1/schemas` is an endpoint for reusable stored schemas, not an action type.
+LLM-backed extraction runs through the `parse_json` action, with an inline `data_schema` or a stored `data_schema_id`, and there is no separate schema action type.
+`parse_json` is not the only way to get data off a page, see step 3 of the loop.
+On a large content-rich page, `parse_json` over the full DOM can fail with `action_failed` (verified on Wikipedia), so narrow the input with a `selector` for the region that holds the data, or set `input_token_cap`.
+
+Reconnaissance uses `POST /v1/site/map` (singular `map`, GET the id to read results) or a broad markdown capture (`generate_markdown`).
+
+## Preferences
+
+General preferences for using the Gaffa API.
+They capture guidance beyond the API docs, and we add to them over time.
+Follow them unless the specific task calls for something else.
+
+- Prefer an inline `data_schema` over a stored `data_schema_id` for `parse_json`, so the end user can see the shape of what is being extracted.
+  Reach for a stored `data_schema_id` only when a shape is registered server-side for reuse across separate scripts or sessions.
+
+## Credential hygiene
+
+1. Read `GAFFA_API_KEY` from env only.
+   Never hard-code in emitted code.
+   Reference it as `${GAFFA_API_KEY}`.
+2. Never echo, log, narrate, or persist the value of `GAFFA_API_KEY`.
+   Never put it in a URL or query string.
+3. Before showing a gaffa recording, error trace, or request body to the user, to an LLM judge, or to disk, strip the values of any fields whose names match (case-insensitive, including vendor-prefixed variants like `gaffa_api_key`): `Authorization`, `X-API-Key`, `api_key` (and `apiKey`, `api-key`), `cookie`, `set-cookie`.
+   Replace the value with `<REDACTED>`.
+4. If the runtime value of `GAFFA_API_KEY` appears as a substring anywhere in a payload you are about to show or persist, replace it with `<REDACTED>`.
+   Only enable this substring scrub when the env value is at least 16 characters long and contains both a digit and a letter.
+   Otherwise skip and warn the developer on first invocation that the entropy floor was not met (field-name and prose rules still apply).
+5. Persisted writes (the `/gaffa-find` reasoning log `./.gaffa-find-<timestamp>.log`, and any other on-disk artifact) go through redaction first, then to a tempfile, then atomic-rename to the final path.
+   A crash mid-write must not leave a plaintext-secrets file on disk.
+6. If unsure whether a string is a secret, redact it.
+
+## Doc-fetching strategy
+
+Resolve documentation queries in two tiers, in order.
+
+1. Preferred: gaffa docs MCP server at `https://gaffa.dev/docs/~gitbook/mcp`.
+   `searchDocumentation` (param `query`) for "how do I do X".
+   `getPage` (param `url`) to fetch one page by URL.
+2. Fallback: live HTTP fetch.
+   `?ask=` against the docs for narrow lookups, `https://gaffa.dev/docs/llms.txt` for breadth.
+   Per-call timeout of 5 seconds.
+
+MCP availability probe, once per session, cached, total budget 10 seconds: JSON-RPC `initialize`, then the mandatory `notifications/initialized` notification, then `tools/list` confirming `searchDocumentation` and `getPage` (or at least one).
+Per-call MCP timeout is 5 seconds.
+Two consecutive timeouts demote to live HTTP for the rest of the session, announced once.
+
+If both tiers fail at iteration 0 (before any work), refuse with a clear message (suggest registering the MCP if none was configured).
+If both tiers fail mid-flight (at least one iteration done), do not discard progress: return the current best candidate as `needs-human-review`, persist the reasoning log, and surface the doc-fetch failure as the reason.
+
+## First action
+
+Fire a reconnaissance request, not a doc load.
+The reconnaissance (site map or broad markdown capture) tells you where the answer is likely to live before you commit to a selector.
+
+## Terminal states
+
+The skill always ends in exactly one of these three states.
+
+- success.
+  The extracted value clearly fits the goal, and any developer-supplied validator passed.
+  Output includes a short evidence line (which page, which selector or extraction step) so the developer can verify without rerunning.
+- needs-human-review.
+  The skill is uncertain (judgment ambiguous, or budget exhausted with a partial candidate).
+  Output includes the best candidate, the reasoning-log location, and the failing script's request id with a `/gaffa-debug` suggestion.
+- terminal-failure.
+  Unrecoverable error: the target blocks every attempt, or the doc fetch fails mid-flight after work began.
+  Output explains why and surfaces the request id.
+
+On `needs-human-review` or `terminal-failure`, end the output with one line: *Still stuck? Run `/gaffa-support` to get help or file a report.*
+
+## Loop
+
+1. Reconnaissance (`/v1/site/map` or a broad markdown capture).
+2. Hypothesize the answer's likely location.
+3. Targeted extraction.
+   Choose the action before you look up its parameters, and say which you chose and why.
+   When the value sits in a stable, well-structured place, take the deterministic path: `parse_table` with a `selector` for a table, `generate_markdown` with a `selector` for a region you then parse in the developer's own language, or `capture_element` with a `selector` for one element.
+   Cheaper, repeatable, identical every run, and your `generate_markdown` recon output often already shows whether the shape is stable enough.
+   Only when the value is buried in free text or moves from page to page (a salary somewhere in a job description), or the goal is interpretive (summarising, classifying), use the `parse_json` action (inline `data_schema`, or `data_schema_id` for a reused shape), which handles ambiguity a selector cannot but is token-priced and can vary between runs.
+4. Check the stop condition: does the value clearly fit the goal, and does any supplied validator pass?
+5. Refine the hypothesis or finish, returning the answer plus a re-runnable script.
+6. Stop on success, on budget exhaustion (any of the three caps or `MAX_ITERATIONS`), or on an unrecoverable error.
+
+## Behavior
+
+- Inputs.
+  Required: target URL and a plain-language goal.
+  Optional: an explicit validator passed as `--validator` (a regex, JSON schema, or expected type) for deterministic termination, and a max-iterations override.
+- Pre-flight credit estimate before each request.
+  Pause and confirm when the invocation total would breach `CREDITS_PER_INVOCATION`.
+  For token-priced actions (`parse_json`, `/v1/schemas`) gate against the upper bound of the estimate, not the midpoint.
+  For `parse_json`, fetch current rates from https://gaffa.dev/docs/credits-and-pricing.md once per invocation, reuse that cached rate for later requests, and add a 50% safety margin on output tokens.
+  For `/v1/schemas`, pin a conservative ceiling at the worst current `parse_json` rate applied to the captured page size in tokens, tell the developer the ceiling is a guess, and ask for confirmation regardless of headroom.
+- `--reconnaissance-only` returns the site map or landing capture without entering the extraction loop.
+- Per-iteration reasoning is logged to `./.gaffa-find-<timestamp>.log` in the developer's working directory, written through the redaction-then-tempfile-then-atomic-rename path.
+  See `templates/loop.md` for the rationale and shape.
+- Always set `settings.time_limit` explicitly and `settings.record_request: true` so a failing attempt can be triaged with `/gaffa-debug`.
+- Do not invent an answer.
+  If the goal is not found within budget, stop with `needs-human-review` and say so plainly.
+- Returns both the answer and the working, re-runnable gaffa script.
+
+See `templates/loop.md` for the reconnaissance, extraction, and reasoning-log shapes.

package/skills/gaffa-find/templates/loop.md

@@ -0,0 +1,105 @@
+# Template: find loop shapes
+
+Language-agnostic shapes for the discovery loop.
+Adapt to the developer's language.
+
+## Reconnaissance: site map
+
+```bash
+curl -sS -X POST https://api.gaffa.dev/v1/site/map \
+  -H "X-API-Key: ${GAFFA_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: gaffa-skill/1.0" \
+  -d '{ "url": "https://example.com" }'
+```
+
+The response carries an id.
+Read the result with `GET /v1/site/map/{id}`.
+The path is singular `map`, not `maps`.
+
+## Reconnaissance: broad markdown capture
+
+```bash
+curl -sS -X POST https://api.gaffa.dev/v1/browser/requests \
+  -H "X-API-Key: ${GAFFA_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: gaffa-skill/1.0" \
+  -d '{
+    "url": "https://example.com",
+    "max_cache_age": 0,
+    "settings": {
+      "time_limit": 60000,
+      "record_request": true,
+      "actions": [
+        { "type": "generate_markdown" }
+      ]
+    }
+  }'
+```
+
+## Targeted extraction with the parse_json action
+
+Only reach for this once you have ruled out a deterministic path, per step 3 of the loop in SKILL.md.
+LLM-backed extraction runs through the `parse_json` action, and there is no `/v1/schemas` action type.
+Pass an inline `data_schema`, or reference a stored schema with `data_schema_id` after creating it via the `/v1/schemas` endpoint.
+
+```bash
+curl -sS -X POST https://api.gaffa.dev/v1/browser/requests \
+  -H "X-API-Key: ${GAFFA_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: gaffa-skill/1.0" \
+  -d '{
+    "url": "https://example.com/leadership",
+    "max_cache_age": 0,
+    "settings": {
+      "time_limit": 60000,
+      "record_request": true,
+      "actions": [
+        {
+          "type": "parse_json",
+          "selector": "main",
+          "data_schema": {
+            "name": "leadership",
+            "description": "Find the chief executive officer",
+            "fields": [
+              { "type": "string", "name": "ceo_name", "description": "the full name of the CEO" }
+            ]
+          }
+        }
+      ]
+    }
+  }'
+```
+
+`parse_json` is token-priced.
+Gate it against the upper-bound estimate before firing.
+Give it a `selector` for the region your recon identified, because `parse_json` over the full DOM of a large page can return `action_failed`.
+If you do not yet know a good selector, your `generate_markdown` recon output often already contains the answer, so read that before spending another extraction request.
+
+## Reasoning log
+
+Append one entry per iteration to `./.gaffa-find-<timestamp>.log`.
+One entry records the iteration number, the hypothesis, the request id, the candidate value, and the stop-condition decision.
+Never write a key value into the log.
+
+Write it safely.
+The tempfile must live in the same directory as the final log so the rename is atomic on the same filesystem.
+A tempfile in `/tmp` and a final log in the working directory are usually on different filesystems, which turns the rename into a non-atomic copy and defeats the crash-safety guarantee.
+
+```bash
+FINALLOG="./.gaffa-find-$(date +%Y%m%dT%H%M%S).log"
+TMPLOG="${FINALLOG}.tmp"          # same directory as the final log, not /tmp
+
+cat > "$TMPLOG" << 'EOF'
+# gaffa-find reasoning log
+... one entry per iteration ...
+EOF
+
+# redact only when the env value meets the entropy floor (16+ chars, a digit and a letter)
+if [ "${#GAFFA_API_KEY}" -ge 16 ] && printf '%s' "$GAFFA_API_KEY" | grep -q '[0-9]' && printf '%s' "$GAFFA_API_KEY" | grep -q '[A-Za-z]'
+then
+  sed -i "s|${GAFFA_API_KEY}|<REDACTED>|g" "$TMPLOG"
+fi
+
+mv "$TMPLOG" "$FINALLOG"          # atomic rename within the same directory
+```