@gaffa-dev/skills 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# gaffa-for-ai
+
+Four agent skills for building on the [gaffa.dev](https://gaffa.dev) browser-automation REST API, plus the Gaffa docs MCP server, installable as one plugin.
+
+| Skill | Entry | What it does |
+|---|---|---|
+| `gaffa-authoring` | auto-invokes on a gaffa coding prompt | Writes, edits, ports, or reviews code that calls the gaffa API. Loads verified facts and live docs before generating code. |
+| `gaffa-find` | `/gaffa-find` | Iteratively discovers and extracts one piece of information from a target site, given a URL and a plain-language goal. |
+| `gaffa-debug` | `/gaffa-debug` | Diagnoses a failing request or `brq_*` id from its recording and proposes a minimal patch. |
+| `gaffa-support` | `/gaffa-support` (slash only) | Helps when stuck: tries to resolve the problem first, then packages a redacted local report to email to support. Slash only on Claude Code, Cursor, Codex and Copilot. Antigravity has no way to opt a skill out of automatic selection, so there the agent can still reach for it. |
+
+## Install as a plugin
+
+This repo is a plugin. Installing it brings in all four skills and registers the Gaffa docs MCP server in one step, so there is nothing to copy and nothing to configure.
+
+For Claude Code and Codex, point the tool's plugin marketplace at this repository, then install the `gaffa` plugin from it. Cursor and Antigravity install differently and are covered below.
+
+On Claude Code that is two commands:
+
+```
+claude plugin marketplace add https://github.com/GaffaAI/gaffa-for-ai
+claude plugin install gaffa@gaffa --scope project
+```
+
+The full URL is deliberate. Claude Code clones the `owner/repo` shorthand over SSH by default, which fails without a GitHub SSH key.
+
+Scopes are `user` (the default), `project`, which writes `.claude/settings.json` in the project you are working in and is shared with collaborators, and `local`, which writes `.claude/settings.local.json` in that same project and is not shared.
+
+Two things worth knowing:
+
+- Cursor has no command-line install. The plugin manifest is here and the plugin loads once Cursor has it, but adding it is a click in the app rather than something you can script.
+- Updating differs by tool. Claude Code refreshes marketplaces in the background by default and updates an installed plugin with `/plugin update`, where `/plugin marketplace update` only re-pulls the catalog. The others need asking: `codex plugin marketplace upgrade`, `copilot plugin update`, `cursor-agent plugin marketplace update`.
+
+Antigravity has no marketplace concept, so it installs by putting the plugin where it looks. Clone this repo into its plugins directory and restart:
+
+```
+git clone --depth 1 https://github.com/GaffaAI/gaffa-for-ai ~/.gemini/config/plugins/gaffa
+```
+
+That covers Antigravity 2.0 and the IDE. The CLI stages plugins under `~/.gemini/antigravity-cli/plugins/` instead, so use that path if you run `agy`.
+
+For one project rather than the whole machine, clone into `.agents/plugins/gaffa` instead. To commit it for the team, drop the clone's own history first, otherwise git records a pointer to another repository and a teammate ends up with an empty directory:
+
+```
+git clone --depth 1 https://github.com/GaffaAI/gaffa-for-ai .agents/plugins/gaffa
+rm -rf .agents/plugins/gaffa/.git
+```
+
+## Install by copying
+
+Each skill is a self-contained folder that follows the open Agent Skills standard (a `SKILL.md` with `name` and `description` frontmatter), so it works in any tool that reads that format. Copy the folders you want out of `skills/` into the directory your tool reads:
+
+| Tool | Project directory | Personal directory |
+|---|---|---|
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` |
+| Cursor (2.4+) | `.agents/skills/` or `.cursor/skills/` | `~/.agents/skills/` or `~/.cursor/skills/` |
+| Codex CLI | `.agents/skills/` | `~/.agents/skills/` |
+| GitHub Copilot | `.agents/skills/` | `~/.agents/skills/` |
+| Antigravity | `.agents/skills/` | see below |
+
+Antigravity's personal directory depends on which surface you run. Its own docs give `~/.gemini/config/skills/` for Antigravity 2.0, `~/.gemini/antigravity/skills/` for the IDE and `~/.gemini/antigravity-cli/skills/` for the CLI. The project directory is the same for all three, so prefer that one.
+
+For example, to install `gaffa-authoring` into a project on Claude Code:
+
+```
+cp -r skills/gaffa-authoring .claude/skills/gaffa-authoring
+```
+
+Swap the target for your tool. Copy only the skills you want, they do not depend on each other. Restart or reload the tool after adding a skill so it picks them up.
+
+Copying this way brings the skills but not the docs MCP server, which the plugin install registers for you. To add it by hand, point your tool at `https://gaffa.dev/docs/~gitbook/mcp`. It takes no authentication. The two config files in this repo are the shapes to copy: `.mcp.json` for Claude Code and Cursor, and `mcp_config.json` for Antigravity, which uses `serverUrl` where the others use a type and a url. Without it the skills fall back to fetching the docs over plain HTTP, which works and is just slower.
+
+The agent selects a skill automatically from its `description` when the task matches. The slash commands in the table above are a Claude Code affordance. Codex reaches the same skills as `$gaffa-find` or through its picker. In other tools, describe the task and the agent invokes the right skill.
+
+## Setup
+
+Set up two things once before running the skills.
+
+1. API key. The skills read the key from the `GAFFA_API_KEY` environment variable only. It is never prompted for, written to disk, or logged. Set it persistently rather than pasting it each session, for example `export GAFFA_API_KEY=...` in your shell profile. The key stays out of version control.
+2. Network egress. The skills call `api.gaffa.dev` and read docs from `gaffa.dev`. Behind a sandbox or proxy that blocks outbound traffic, allow both hosts first, or requests fail as connectivity errors.
+
+The first real request confirms the setup. A missing or invalid key returns a clear authentication error, and a blocked host surfaces as a connectivity error that points back to the egress step.
+
+## Notes
+
+- Gaffa has no official SDK. The skills emit REST calls in whatever language and library your project already uses.
+- The gaffa docs MCP server makes documentation lookups faster. The plugin install registers it for you, and the copy-install section above covers adding it by hand.
+- The skills spend gaffa credits. `/gaffa-find` enforces a tunable cost cap set in its `SKILL.md`. `/gaffa-debug` spends credits only on an optional re-run after explicit confirmation. `/gaffa-support` spends no credits and makes no gaffa API call.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@gaffa-dev/skills",
+  "version": "0.1.0",
+  "description": "The Gaffa skills for writing code against the Gaffa browser-automation API.",
+  "license": "MIT",
+  "author": {
+    "name": "Impetus Labs Ltd",
+    "email": "support@gaffa.dev"
+  },
+  "homepage": "https://gaffa.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GaffaAI/gaffa-for-ai.git"
+  },
+  "files": [
+    "skills",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/gaffa-authoring/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: gaffa-authoring
+description: Use when the user mentions gaffa in a programming context (a gaffa.dev URL, a gaffa endpoint, or an existing gaffa API call) and wants concrete code. Writes, edits, ports, or reviews code that calls the gaffa.dev browser-automation REST API, loading the verified gaffa API facts and live docs first. For triaging a failing request or a brq_* id, /gaffa-debug leads instead. For a URL with only a vague goal and no script, /gaffa-find leads.
+---
+
+# gaffa authoring
+
+Helps a developer write, edit, port, or hand-review code that calls the gaffa.dev browser-automation REST API.
+Gaffa is a plain HTTP REST API with no official SDK.
+You emit code in whatever language and style the developer's project already uses.
+
+## Critical gaffa facts (grounding)
+
+For anything beyond them, consult the live docs (see Doc-fetching strategy).
+
+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.
+`parse_json` is not the only way to get data off a page, see "Choosing an extraction action" below.
+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`.
+
+### Verified endpoint and field reference
+
+- Endpoints: `POST/GET /v1/browser/requests`, `GET /v1/browser/requests/{id}`, `POST/GET /v1/schemas`, `PUT /v1/schemas/{id}`, `DELETE /v1/schemas/{id}`, `POST/GET /v1/site/map`, `GET /v1/site/map/{id}`.
+  The path is singular `map`, easy to typo as `maps`.
+  Schema update and delete both take the id in the path.
+- Settings fields under `settings`: `actions`, `time_limit`, `record_request`, `max_media_bandwidth`, `block_ads`.
+  `max_cache_age` and `proxy_location` are root-level body fields, not under `settings`.
+- `max_cache_age` is in seconds.
+  Set it to 0 to disable the cross-user cache.
+- If `time_limit` is not set, it defaults to your plan's maximum runtime, and it must stay below that maximum.
+  Set it explicitly so the value is visible and intentional.
+- Available actions: `click`, `scroll`, `type`, `wait`, `capture_cookies`, `capture_dom`, `capture_screenshot`, `capture_snapshot`, `download_file`, `generate_markdown`, `generate_simplified_dom`, `parse_json`, `print`, `block_dom_removals`, `capture_element`, `parse_table`, and `loop`, which repeats nested actions inside one request.
+  The per-action parameter catalog lives in `references/actions.md`.
+  Read it on demand when you need a specific action's parameters.
+- Proxy locations are residential IPs: `us`, `ie`, `sg`, `fr`.
+  Set `proxy_location` to route through a residential IP in that country.
+  With none set, the request uses a generic datacenter IP.
+
+### Choosing an extraction action
+
+Pick the action before you look up its parameters.
+`parse_json` is LLM-backed, so it is token-priced and its output can vary between runs.
+Weigh that against a deterministic path first, and tell the developer the trade-off you took so they can overrule it.
+
+- Prefer a deterministic path when the value sits in a stable, well-structured place.
+  Cheaper, repeatable, identical every run.
+  Good for a price in a known element, a list of cards with a consistent shape, a field in a JSON blob.
+  The options, in rough order of how often they fit:
+  - `parse_table` with a `selector` for a table, which returns the rows already structured.
+  - `generate_markdown` with a `selector` for the region, then parse the markdown in the developer's own language.
+    Good for repeating cards or list items, and your recon capture is often this already.
+  - `capture_element` with a `selector` for one specific element.
+- Reach for `parse_json` when the value is buried in free text or moves around from page to page (a salary somewhere inside a job description), or when the task is interpretive rather than a lookup (summarising, classifying).
+  That is where the LLM earns its cost.
+- Do not use `parse_json` when the developer needs identical output across runs.
+
+## 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
+
+These rules apply to every line of code and every message this skill produces.
+
+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`.
+   When the developer has it configured, call its tools directly.
+   `searchDocumentation` (param `query`, a string) for "how do I do X" questions.
+   `getPage` (param `url`, a full URL) to fetch one page when you already have its URL.
+2. Fallback: live HTTP fetch.
+   `?ask=` against the docs for narrow lookups, `https://gaffa.dev/docs/llms.txt` for breadth, `https://gaffa.dev/docs/sitemap.md` for the full page index.
+   Per-call timeout of 5 seconds.
+   Used when the MCP is not configured or returns an error.
+
+MCP availability probe, once per session, cached, total budget 10 seconds:
+
+1. JSON-RPC `initialize` over POST.
+   Confirms the endpoint speaks MCP.
+2. Send the mandatory `notifications/initialized` notification.
+3. JSON-RPC `tools/list` over POST.
+   Confirms `searchDocumentation` and `getPage` (or at least one) are present.
+
+Per-call MCP timeout is 5 seconds.
+If two consecutive calls in one session time out, demote to live HTTP for the rest of the session and tell the developer once.
+
+If both tiers fail before any code is emitted, refuse with a clear message rather than guessing from training data.
+Both tiers read from `gaffa.dev`, so when they fail together the usual cause is that `gaffa.dev` is blocked by the environment's egress policy, separate from `api.gaffa.dev`.
+The message names that first: "Live gaffa docs are unavailable.
+If `gaffa.dev` is blocked by your environment's egress or proxy policy, allow it and retry, see the setup section in the skills README.
+Otherwise retry, or consult https://gaffa.dev/docs manually." If no gaffa MCP was configured, the message also suggests registering `https://gaffa.dev/docs/~gitbook/mcp` for faster lookups.
+
+## First action
+
+Before emitting code, live-fetch the doc section relevant to the developer's request (MCP preferred, HTTP fallback), grounded by the critical facts above.
+Do not emit code before the relevant docs are confirmed or the grounding alone is sufficient and stated as such.
+
+## Behavior
+
+- Do not guess selectors.
+  When the code needs a selector (for `parse_json` with a `selector`, `capture_element`, `click`, `type`, or `wait`), do not infer it from the URL or from the existing code.
+  First fetch the real page with gaffa using a `generate_simplified_dom` or `capture_dom` capture, read the actual elements, then write the selector from what is really there.
+  If that fetch fails with a connectivity error, the page is unreachable, usually because egress to `api.gaffa.dev` is blocked, so point the developer at the egress setup instead of guessing.
+  If you genuinely cannot fetch the page, mark the selector as unverified and tell the developer to confirm it rather than presenting a guess as correct.
+- Gaffa requests work best when targeting a single URL with actions performed on that page.
+  Pagination and other repeat-the-same-steps flows stay inside that one request with the `loop` action, capture first, then the click that moves on, see the catalog.
+  What remains unsupported is session state across separate requests, every request starts a fresh session, so surface that up front when the developer's request needs it.
+- Always set `settings.time_limit` explicitly in generated code, based on what the job is expected to take.
+  You do not know the developer's plan max, so emit a code comment reminding the developer to verify the value fits their plan (Starter 1 min, Startup 2 min, Growth 5 min).
+- For any request the developer may later want to debug or audit, set `settings.record_request: true` in the emitted code so `/gaffa-debug` has a recording to inspect within the retention window.
+- Default to the async pattern (POST then poll the returned id).
+  Use `"async": false` only when the developer asks for a blocking call and the expected runtime is well under the plan max.
+- Read the template that matches the task and adapt it to the developer's language and library.
+  They are starting points, not literal output.
+  - `templates/async-poll.md` for the POST-then-poll pattern.
+  - `templates/sync.md` for the blocking `"async": false` pattern.
+  - `templates/schema-extraction.md` for `/v1/schemas` structured extraction.
+
+### Schema design and SDK migration
+
+- Schema design with `/v1/schemas`.
+  Same authoring trigger, constrained to one endpoint.
+  See `templates/schema-extraction.md`.
+  Storing a schema uses the endpoint with a normal API key.
+- Migration from Playwright, Puppeteer, or Selenium to gaffa.
+  Read the foreign snippet and map each step to a gaffa action, a pagination while-loop maps to the `loop` action.
+  Flag any step that relies on session state across separate requests as a known gaffa limitation.

package/skills/gaffa-authoring/references/actions.md

@@ -0,0 +1,235 @@
+# gaffa action parameter catalog
+
+Per-action parameters, fetched from the live gaffa docs.
+Read this on demand when you need a specific action's parameters.
+When in doubt, re-confirm against the live docs (`getPage` on the action's page under `/docs/features/browser-requests/actions/`, or the HTTP fallback), because the docs can change.
+
+## Universal parameters (every action)
+
+- `type` (string, required): the action type identifier, for example `capture_dom`.
+- `continue_on_fail` (boolean, optional): continue the run if this action fails.
+  Default `false`.
+- `custom_id` (string, optional): a custom action identifier, echoed back on the matching action in the response.
+  Default `null`.
+
+Actions run in the order they are submitted.
+
+## Selectors
+
+Every `selector` parameter below runs through Playwright's selector engine, not plain CSS.
+All standard CSS works, and so do Playwright's extensions, text selectors such as `:has-text('foo')` and `:text('foo')`, `:visible`, and XPath.
+Pseudo-elements such as `::before` cannot be targeted, there is no real element to return.
+Elements inside same-origin iframes are reached with a plain selector, no frame targeting needed.
+Cross-origin iframes are currently out of reach, a selector cannot match inside them.
+Full reference: `/docs/features/browser-requests/selectors`.
+
+## Actions without outputs
+
+### click
+- `selector` (string, required): selector for the element to click.
+- `timeout` (integer, optional): max wait for the element.
+  Default 5000 ms.
+
+Click waits up to its timeout for the element, so no `wait` before it.
+Prefer stable selectors (`id`, `data-testid`, `aria-label`) over generated class names or positional ones.
+Set `continue_on_fail: true` on clicks for cookie banners and pop-ups that may not appear.
+After a click that loads new content, `wait` for that content before capturing.
+
+### scroll
+- `percentage` (integer, required): the position to scroll to, not a distance, so 50 is halfway down and 100 the bottom.
+  Default 100.
+  Scrolling only goes down, so emit 0 to 100.
+- `wait_time` (integer, optional): after the scroll, keep watching the page and keep scrolling as loading content grows it.
+  Default 0.
+- `max_scroll_time` (integer, optional): max scroll duration.
+  Default 20000 ms.
+- `scroll_speed` (string, optional): one of `slow`, `medium`, `instant`.
+  Default `medium`.
+- `interval` (integer, optional): pause between scroll events in ms. Default 0.
+- `timeout` (integer, optional): wait for a scrollable element.
+  Default 0.
+- `selector` (string, optional): element to scroll.
+  Defaults to the page body.
+
+For infinite scroll, set `wait_time` so the scroll follows the growing page, and cap it with `max_scroll_time`.
+Hitting `max_scroll_time` stops the scroll without failing, later actions still run.
+Scroll a modal or side panel by passing its `selector`, scrolling the body will not move it.
+If rows vanish while scrolling past them, put `block_dom_removals` before the scroll.
+There is no scrolling back up, so order the actions to need one downward pass only.
+
+### type
+- `selector` (string, required): input field selector.
+- `text` (string, required): text to enter.
+- The docs currently list no `timeout` for this action.
+  If the form renders late, `wait` for the field first.
+
+Typing does not submit, follow with a `click` on the submit button and a `wait` for what comes next.
+Target the input element itself, not its wrapper.
+Inside attribute selectors use single quotes (`input[name='email']`) so the selector needs no escaping in the JSON string.
+One `type` action per field, and checkboxes, radios and dropdowns take a `click`, not a `type`.
+
+### wait
+- `time` (integer, optional): milliseconds to wait.
+- `selector` (string, optional): selector to wait for.
+- `timeout` (integer, optional): max wait for the selector.
+  Default 5000 ms.
+
+Prefer a `selector` wait over a fixed `time`, it moves on as soon as the element appears.
+Never set both, `time` silently wins and the selector is ignored.
+No `wait` is needed before `click`, `capture_element`, or `parse_table`, they wait for their own selector.
+Set `continue_on_fail: true` when the awaited element may never appear.
+
+### block_dom_removals
+- No parameters beyond the universal ones are documented.
+
+Run it first, it only protects what happens after it and cannot restore what the page already removed.
+It stays in force for the rest of the request.
+The usual shape is `block_dom_removals`, then `scroll`, then the capture.
+
+## Actions with outputs
+
+### capture_cookies
+- No parameters beyond the universal ones are documented.
+
+Place it after the actions that set the cookies, so a login flow ends `type`, `click`, `wait`, then `capture_cookies`.
+It returns cookie names and values only, no domain, expiry or flags.
+Cookies cannot be replayed into another request, every browser request starts a fresh session.
+Treat the output as credentials.
+
+### capture_dom
+- No parameters beyond the universal ones are documented.
+
+Do not send the output to an LLM, `generate_simplified_dom` and `generate_markdown` carry nearly the same information in far fewer tokens.
+There is no `selector` here, capturing part of the page means `capture_element`.
+If content is missing from the capture, the page was not done loading, `wait` for a selector of the expected content first.
+
+### capture_screenshot
+- `size` (string, optional): one of `view`, `fullscreen`.
+  Default `view`.
+
+`view` captures the visible viewport, `fullscreen` the whole page.
+On pages that lazy-load images, scroll to 100 with a `wait_time` first or they come out blank.
+There is no single-element screenshot, use `capture_element` for the HTML or scroll the element into view.
+
+### capture_snapshot
+- No parameters beyond the universal ones are documented.
+
+The saved file has JavaScript switched off, so open tabs and expand sections with `click` and `wait` before capturing.
+Reach for it when the page will be read or searched later, `capture_screenshot` only shows it, `print` makes a paper-style PDF.
+
+### capture_element
+- `selector` (string, required): selector for the target element.
+- `timeout` (integer, optional): max wait for the element.
+  Default 5000 ms.
+
+It waits for its selector up to the timeout, so no `wait` before it, and a generous timeout does not slow a successful run.
+Only the first match is captured, target a shared container to get more than one element.
+Prefer it over `capture_dom` when you know where the content lives.
+
+### download_file
+- `timeout` (integer, optional): max download wait.
+  Default 5000 ms.
+
+Only the documented file types download: .pdf, .jpg, .png, .gif, .bmp, .webp, .svg, .tiff, .tif, .img.
+Each action returns the most recent download and consumes it, so emit one `download_file` per expected file, each with a `custom_id`.
+The default 5000 ms suits small images, documents want more, the docs suggest 20000 ms as a starting point.
+A file behind a link is a `click` first, then the download.
+
+### generate_markdown
+- `selector` (string, optional): selector for a specific element.
+- `output_type` (string, optional): one of `file`, `inline`.
+  Default `file`.
+
+The default choice for LLM-bound page content, and `output_type: "inline"` returns it in the response, which suits agents and short pages.
+Pass a `selector` such as `main` or `article` to skip navigation and footers.
+Tables survive as Markdown tables, but code that processes a table wants `parse_table` instead.
+
+### generate_simplified_dom
+- No parameters beyond the universal ones are documented.
+
+The selector-discovery step: run it, read the stable ids and classes, then write the other actions' selectors from what is there.
+Query strings are stripped from links, use `capture_dom` when URL parameters matter.
+
+### print
+- `size` (string, optional): paper size, `A4` is the only accepted value at the moment.
+  Default `A4`.
+- `margin` (integer, optional): margin in pixels.
+  Default 20.
+- `orientation` (string, optional): one of `portrait`, `landscape`.
+  Default `portrait`.
+
+The PDF follows the site's print styles, so it can differ from the screen, `capture_screenshot` with `size: "fullscreen"` keeps the screen look.
+Wide content such as tables wants `landscape`, edge-to-edge designs want `margin: 0`.
+A page that already is a PDF wants `download_file`, not `print`.
+
+### parse_json
+Token-priced, so surface cost as token-based, not deterministic.
+The documented rate for `gpt-4o-mini` is 1 credit per 20,000 input tokens and 1 credit per 10,000 output tokens, re-check the live docs before quoting it.
+- `data_schema_id` (string, required if `data_schema` is absent): a saved schema identifier.
+- `data_schema` (json, required if `data_schema_id` is absent): an inline schema definition.
+  It is a structured object with `name`, `description`, and a `fields` array where each field has `type`, `name`, and `description`.
+  The documented field types are `string`, `integer`, `decimal`, `double`, `boolean`, `datetime`, `object`, and `array`, where `object` and `array` take nested `fields`.
+  A flat object such as `{"title":"string"}` is rejected and the action fails.
+- `instruction` (string, optional): additional parsing instructions.
+  This is a sibling parameter of `parse_json`, not a field inside `data_schema`.
+- `model` (string, optional): the parsing model.
+  Defaults to `gpt-4o-mini`, which is also the only accepted value at the moment.
+- `input_token_cap` (integer, optional): max source tokens.
+  Default 1000000.
+- `selector` (string, optional): selector for a content subset.
+- `output_type` (string, optional): one of `file`, `inline`.
+  Default `file`.
+- `max_pages` (integer, optional): PDF page limit.
+  No default documented.
+
+Write field descriptions as instructions, the expected format and what to do when the value is missing, not as labels.
+A list of items is an `array` field with nested `fields` describing the item shape.
+It reads online PDFs too, with `max_pages` capping what is sent to the model.
+
+### parse_table
+- `selector` (string, required): selector identifying the table.
+- `timeout` (integer, optional): max wait for the table.
+  Default 5000 ms.
+
+Headers become the property names, lowercased, and characters other than letters and numbers become underscores, so `Ticket Price (£)` comes back as `ticket_price_`, check the keys before mapping them.
+Every value comes back as a string, convert numbers and dates on your side.
+Only real `<table>` markup parses, a div grid takes `parse_json` or `capture_element`.
+If the table lazy-loads rows, scroll and wait first so the rows exist when it runs.
+There is no merged-cell handling, take `capture_dom` plus your own parser for those.
+
+## Flow actions
+
+### loop
+Repeats its nested actions in order, so pagination or repeated interaction fits in one request.
+- `actions` (action[], required): the actions each iteration runs, any type except another `loop`.
+- `iterations` (integer, optional): fixed number of iterations, 1 to 100.
+- `max_iterations` (integer, optional): upper bound on iterations when the count is open.
+  Default 10, range 1 to 1000.
+  With both set, the lower value wins.
+- `timeout` (integer, optional): max duration of the whole loop, all iterations together, not each one.
+  Default 20000 ms.
+- `stop_on_fail` (boolean, optional): end the loop when a nested action fails.
+  Default `true`.
+  A nested action with `continue_on_fail: true` does not end it.
+
+The basic pagination shape is capture first, then the click to the next page, so the last page is still captured and the click failing on it is what ends the loop.
+Size `timeout` for the whole loop, the 20 second default rarely covers many pages.
+A loop that hits its timeout fails with `action_timed_out`, and the finished iterations keep their outputs.
+Give the nested actions `custom_id`s, every iteration reports its outputs and the ids tell them apart.
+Dismiss cookie banners before the loop with a `continue_on_fail: true` click, and `wait` for the pagination control before the loop starts.
+Set `continue_on_fail: true` on the loop itself when actions follow it, otherwise an early exit cancels them with `action_cancelled`.
+
+## Notes on parse_json
+
+There is no free-form `prompt` parameter.
+Extraction is driven by `data_schema` or `data_schema_id`, with `instruction` as an optional refinement.
+Do not emit a `prompt` field for `parse_json`.
+
+Verified behavior: running `parse_json` over the full DOM of a large, content-rich page (for example a Wikipedia article) returns `data.error: action_failed` with no `output`, even with a valid `data_schema`.
+Narrow the input to fix it: pass a `selector` for the region that holds the data (cheaper, around 2 credits in testing), or set `input_token_cap` (worked but cost more, around 4 credits).
+Small pages extract fine without either.
+
+## When to use parse_json
+
+The rule for choosing between `parse_json` and a deterministic path lives in "Choosing an extraction action" in `SKILL.md`, because the choice has to be made before you get here.
+If you are reading this page to look up `parse_json` parameters and have not weighed a deterministic path yet, go back and do that first.

package/skills/gaffa-authoring/templates/async-poll.md

@@ -0,0 +1,58 @@
+# Template: async request plus poll
+
+The default gaffa pattern.
+`POST /v1/browser/requests` returns an id immediately.
+Poll `GET /v1/browser/requests/{id}` until `state` is terminal.
+
+Language-agnostic shape shown with curl.
+Adapt to the developer's language and HTTP library.
+Keep `time_limit` explicit and read the key from the environment.
+
+## Submit
+
+```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": "capture_screenshot" }
+      ]
+    }
+  }'
+```
+
+The response is wrapped in a top-level `data` object, so the id is at `data.id`.
+The 60000 ms above (60 seconds) is an example value, not the default.
+If you omit `time_limit` it defaults to your plan's maximum runtime and must stay under that maximum.
+Set it explicitly and raise it toward your plan max if the job needs longer (Starter 1 min, Startup 2 min, Growth 5 min).
+
+## Poll
+
+```bash
+curl -sS https://api.gaffa.dev/v1/browser/requests/REQUEST_ID \
+  -H "X-API-Key: ${GAFFA_API_KEY}"
+```
+
+Poll on an interval until the request is terminal.
+Treat `data.state` of `completed` as success and a non-empty `data.error` as failure.
+Keep polling on any other state rather than hard-coding a list of in-progress state names, since the exact in-progress vocabulary is not documented and a name you did not anticipate should not be misread as a failure.
+Always bound the loop with a deadline so it cannot spin forever, for example `time_limit` plus a margin for queueing and network.
+On reaching the deadline, stop and report a timeout rather than continuing to poll.
+A finished run carries `data.actions` (each action result is a URL in `data.actions[].output`) plus `data.credit_usage`, `data.from_cache`, `data.started_at`, `data.completed_at`, `data.running_time`, and `data.page_load_time`.
+A failed run carries `data.error` and `data.error_reason`.
+If you set `record_request: true`, the response also carries `data.video`.
+
+## Notes
+
+- `record_request: true` lets `/gaffa-debug` inspect what happened later, within the plan-tiered retention window (7 days / 30 days / 3 months).
+- `max_cache_age` is a root-level field, not under `settings`, and is in seconds.
+  Set it to 0 to force a fresh fetch and bypass the cross-user cache.
+- Never place the key in the URL or query string.
+  It belongs only in the `X-API-Key` header.

package/skills/gaffa-authoring/templates/schema-extraction.md

@@ -0,0 +1,72 @@
+# Template: structured extraction (/v1/schemas and inline parse_json)
+
+`/v1/schemas` stores a reusable structured-extraction shape that a browser request references by `data_schema_id`.
+The endpoint is reached with a normal API key.
+The extraction cost comes from the token-priced `parse_json` action that uses the schema, so warn the developer that the per-call cost is token-based rather than deterministic.
+
+Two-step flow.
+Create or update a schema, then reference it from a browser request.
+Confirm the exact request and response shape against the live docs before emitting final code, because the schema body format can change.
+
+## Create a schema
+
+```bash
+curl -sS -X POST https://api.gaffa.dev/v1/schemas \
+  -H "X-API-Key: ${GAFFA_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -H "User-Agent: gaffa-skill/1.0" \
+  -d '{
+    "name": "product",
+    "description": "Extract product details",
+    "fields": [
+      { "type": "string", "name": "title", "description": "the product title" },
+      { "type": "string", "name": "price", "description": "the listed price" }
+    ]
+  }'
+```
+
+A schema is a structured object: a `name`, a `description`, and a `fields` array where each field has `type`, `name`, and `description`.
+The response carries the schema id.
+Use `PUT /v1/schemas/{id}` to update, `GET /v1/schemas` to list, and `DELETE /v1/schemas/{id}` to remove.
+Update and delete both take the id in the path.
+Confirm the exact create body against the live docs before relying on it, because the schema body format can change.
+
+## Alternative: parse_json inline
+
+For one-off extraction without a stored schema, the `parse_json` action runs inside a browser request.
+It is token-priced, so flag the cost as token-based rather than deterministic.
+
+```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": "parse_json",
+          "data_schema": {
+            "name": "product",
+            "description": "Extract the product title and price",
+            "fields": [
+              { "type": "string", "name": "title", "description": "the product title" },
+              { "type": "string", "name": "price", "description": "the listed price" }
+            ]
+          }
+        }
+      ]
+    }
+  }'
+```
+
+`parse_json` is driven by `data_schema` (inline) or `data_schema_id` (a saved schema).
+The `data_schema` is a structured object with `name`, `description`, and a `fields` array of `{type, name, description}`.
+A flat object like `{"title":"string"}` is rejected and the action fails.
+There is no free-form `prompt` parameter.
+An optional `instruction` parameter sits alongside `data_schema` for extra parsing guidance.
+See `references/actions.md` for the full parameter list, and "Choosing an extraction action" in `SKILL.md` for whether `parse_json` is the right action here at all.