everyapp 0.2.2 → 0.3.0-rc.1

package/skills/everyapp/setup/context.md

@@ -0,0 +1,117 @@
+# Context.dev for the Gateway
+
+Context.dev is a hosted web scraping API: it loads a page in a browser, with
+JavaScript rendering and anti-bot handling included, and returns the result.
+The Gateway holds one Context.dev API key as `CONTEXT_API_KEY` and sends it
+as a Bearer token in the `Authorization` header, to `api.context.dev` only,
+for apps that list `capabilities.context` (access `read`). Open CRM requires
+it (its research agent's brand data, LinkedIn profiles and website
+extraction); OpenSEO lists it optional: a site audit with **Render
+JavaScript** on renders pages through Context, and project setup reads
+rate-limited Shopify store pages through it.
+Deployed with `everyapp deploy`, OpenSEO has no browser of its own (the
+manifest has no browser resource), so every page a rendered audit loads is
+one Context credit; only OpenSEO's own Alchemy deploy binds Cloudflare Browser
+Run and sends Context just the pages that browser can't render. At the end
+the person has a Context.dev account (the Free plan is enough to start), one
+key on the Gateway, Open CRM open, and OpenSEO's **Render JavaScript** toggle
+enabled.
+
+## Settings
+
+| NAME              | required or optional                                                                     | what it holds                                                                                                                                                                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CONTEXT_API_KEY` | required by Open CRM; optional for OpenSEO (audits run without it; the Render JavaScript option says an admin sets it); a Gateway with neither leaves it unset | One Context.dev API key, exactly as the dashboard shows it (a key from the agent flow in step 2 begins with `ctxt_secret_`). The Gateway trims spaces around it and sends it as a Bearer token to `api.context.dev` only. |
+
+## Costs and plans
+
+As of October 2026 (context.dev/pricing and docs.context.dev/account):
+
+- Free: $0, no credit card, 1,000 credits a month (refilled monthly), 2 requests in flight at a time (pricing page and API reference; the billing docs' plan table says 1; the dashboard shows the organization's effective limit), 2 API keys per organization.
+- Developer $19/month for 7,500 credits (10 in flight); Pro $99 for 125,000; Growth $299 for 500,000; Scale $499 for 1,000,000. Paid plans turn on Auto-Topup at checkout: below 1,000 credits it adds 1,000-credit blocks at the plan's rate ($2.20 per 1,000 on Developer).
+- A basic scrape is 1 credit; OpenSEO counts 1 credit per rendered page (an audit with rendering stops at 1,000 pages). Failed requests (401, 403, 408, 429, 5xx, a site that blocks Context) are not billed; a page that answers 404 is.
+- The usage call (the smoke check) costs 0 credits; 60 calls a minute.
+- The limit that matters is concurrency: on Free, 1-2 renders run at once, so a large rendered audit is slow or sees 429s. On Free, a run of failed requests can also get every key in the organization disabled (401 `DISABLED`, below), not only slow the audit.
+
+## Only a person can
+
+- Sign up or sign in at context.dev and accept its Terms of Service and Privacy Policy.
+- Choose a paid plan or add a card (the Free plan needs neither); in the Context organization only an Owner or Admin can.
+- Create the key in the dashboard and copy it; or open the setup link and enter the code in the agent flow (step 2).
+- Type or export the key (README: the three ways). It never goes through the chat.
+
+## Before you start
+
+- `pnpm everyapp secret list crm --json` (Open CRM) or `pnpm everyapp secret list openseo --json`, from any directory: a `CONTEXT_API_KEY` entry with `holder` `gateway` and `setup` `setup/context.md` means this file applies (in the checkout: `packages/cli/skills/everyapp/setup/context.md`). For Open CRM it is in `data.app.setup.unmet` (`names` `["CONTEXT_API_KEY"]`, `need.kind` `required`) and the app doesn't open until it is set: the Gateway lists it as needing setup, sends a browser opening `https://crm.<app base domain>` to its setup dialog and answers anything else 503 `app_needs_setup`; `data.app.setup.command` is `pnpm everyapp configure crm`, which asks for every missing setting (the OpenRouter key among them while that is missing; `data.next` repeats it), `data.gateway.needed` has `{ "name": "CONTEXT_API_KEY", "required": true, "set": false }`, `data.gateway.missing` names it, and `status` (under "crm needs setup") and `secret list crm` (under the unmet setting) print `Guide: .claude/skills/everyapp/setup/context.md`: that is how an agent lands here. For OpenSEO it is in `data.app.setup.settings` with `need.kind` `optional` and `set: false`: the app opens, `missing` and the setup gate never name it (`pnpm everyapp configure openseo` offers it after the required ones), and its **Render JavaScript** toggle says an admin sets it. The entry with `"set": true` means it is set already: ask before replacing it (a value can't be read back, so "replace" means a new key). `APP_NOT_FOUND` ("<app> isn't deployed to this Gateway yet"): that app isn't deployed; set the key anyway (`pnpm everyapp secret list --json` from the `every-app` checkout then shows it in `data.gateway.names`; in the app's directory the same command reads its `everyapp.config.ts` and works before the first deploy too, as does `pnpm everyapp configure` there) and run the app-level check after that deploy.
+- `pnpm everyapp status --json`: `data.installed` and `data.claimed` are `true`; `data.gatewayUrl` gives `<gateway host>`, `data.appBaseDomain` the `<app base domain>`. The entry in `data.apps` with `"id": "crm"` (or `"openseo"`), `"status": "active"` and `"bound": true` carries the same `setup`; `data.fixes` has `APP_NEEDS_SETUP` for crm (severity `warning`, headline "crm needs setup", `run` the same command) while a required setting is missing, never for OpenSEO on this key's account.
+- Ask whether the person already has a Context.dev account or key (a password manager, a variable in their shell). An existing key skips steps 2 and 3. Context allows one Free organization per person: with an account already, they sign in to it (and the agent flow must use that account's email).
+- Ask how many pages a month they expect to render. More than 1,000 means a paid plan: their decision, never yours.
+
+## Steps
+
+1. **You:** Run the two commands above. Tell the person in one line what they get (Open CRM's research agent: brand data, LinkedIn profiles and website extraction; rendered site audits in OpenSEO) and what it costs (free up to 1,000 rendered pages a month), ask the two questions in Before you start, and stop: their answers pick the path (an existing key: step 4 alone; an account: sign in, not up; the agent flow in step 2 only on their say-so). Then steps 2-4 go in one message, in order; wait once, after step 4.
+
+2. **Person:** Sign up, or sign in. Page: https://www.context.dev/signup. Type their email in **Email** and click **Continue** (an email sign-up sets a password and asks them to verify the address by email), or pick Google or GitHub under "or continue with" (no verification step). Continuing accepts the Terms of Service and Privacy Policy. An existing account signs in from "Already have an account? Sign in" (https://context.dev/login). It worked when the dashboard opens.
+
+   Alternative, only with their say-so (it registers a key in their name): Context.dev's agent flow (context.dev/auth.md, read today, not run). Everything in one shell, with `EMAIL` set to the address they gave (an existing account's email, when they have one). Register:
+   `reg=$(jq -n --arg email "$EMAIL" '{type:"service_auth",login_hint:$email,api_key_name:"Every App Gateway",client_name:"everyapp setup"}' | curl -sS -X POST https://www.context.dev/agent/identity -H 'Content-Type: application/json' -d @-); printf '%s' "$reg" | jq '{claim, offer}'`
+   Show them `claim.verification_uri` and `claim.user_code` in full, and that both expire in `claim.expires_in` seconds (600: ten minutes). If the response has `offer`, say it includes 1,000 extra credits (deadline `offer.claim_by`); promise nothing otherwise. A 429 `rate_limit_exceeded` from the registration means stop, no retry: step 3 instead. They open the link, enter the 6-digit code, and sign up or sign in with that email (a password sign-up also verifies the address). Then poll every `claim.interval` seconds, for ten minutes at most, until the key arrives or an error ends it, and pipe the key straight in (README's "a command produced it"); `claim_token` is read from `$reg` in the same shell, never typed (it is short-lived and not the key):
+   `CLAIM=$(printf '%s' "$reg" | jq -r .claim_token); INTERVAL=$(printf '%s' "$reg" | jq -r '.claim.interval // 5'); for i in $(seq 1 120); do r=$(curl -sS -X POST https://www.context.dev/oauth2/token -d "grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=$CLAIM"); e=$(printf '%s' "$r" | jq -r '.error // empty'); case "$e" in '') break;; authorization_pending) ;; slow_down) sleep 10;; *) printf '%s' "$r" | jq '{error, error_description}'; break;; esac; sleep "$INTERVAL"; done; printf '%s' "$r" | jq -e .access_token >/dev/null && printf '%s' "$r" | jq -r .access_token | pnpm everyapp secret set CONTEXT_API_KEY --json`
+   `authorization_pending` means they haven't finished (`email_verification_required`: the address isn't verified yet); `expired_token` means the ten minutes passed: register again, only with their agreement; `invalid_grant` means stop and show its `error_description`. When the loop ends without a key, nothing is set and the printed error says why (none printed: curl itself failed). Never print `$r`: the key is in it. This replaces steps 3 and 4: go to Verify (nobody but the Gateway holds the key now, so its smoke check is skipped; 1 and 3 there are the check).
+
+3. **Person:** Create the key. Page: https://context.dev/dashboard/api-keys. Create a new key with the page's button (its label isn't in the docs); if the dialog shows the key once, copy it before closing. Keep **Full access** (the default; it covers the Data APIs the apps use and the usage read the smoke check uses), or choose **Restricted** with Data APIs = Use and "Account logs, usage, and browser profiles" = Read. Name it "Every App Gateway" when the form asks (renaming later needs a paid plan). It worked when the key is listed on that page. A Free organization holds at most two keys: with two there already, delete one they no longer use (whether a disabled key still counts toward the two isn't in the docs), or use the agent flow above, which needs no button.
+
+4. **Person, then You:** Put it on the Gateway. README's first way (the key is on a screen they are looking at): they open a second terminal in the `every-app` folder and run `pnpm everyapp configure crm` (or `pnpm everyapp configure openseo`; no `--json`: with it nothing prompts), which asks for this key among the app's other unset settings (for OpenSEO it is optional: Yes to `Set the N optional settings too?` (`Set the optional setting too?` for one), then `CONTEXT_API_KEY (Enter to skip)`; once an app is ready, its menu `Everything <app> needs is set. Change one?` lists it), or `pnpm everyapp secret set CONTEXT_API_KEY` for just this one. The prompt is hidden (`CONTEXT_API_KEY`, under lines saying what it is for and where it comes from; `secret set` asks `Value for CONTEXT_API_KEY`); they paste, press Enter, and see `Set CONTEXT_API_KEY on the Gateway` (configure then says `crm is ready.` or what the app still needs, and `Live now. No deploy needed.`; `secret set` ends `Live now on <gateway host>. No deploy needed.`). Nothing is exported afterwards, so offer the smoke check (Verify 2, 0 credits) in that same terminal: the hidden read (README's third way: `read -rs CONTEXT_API_KEY && export CONTEXT_API_KEY`, paste, Enter), Verify 2's curl, they tell you its last line (200) and `credits_remaining`, then `unset CONTEXT_API_KEY`; declined, the app (Verify 3) is the check. README's third way from the start, when they read it in hidden instead (never a typed `export …=`, which the shell history keeps; run the smoke check below first): `pnpm everyapp configure <app id> --from-env --json`, whose `done` event has `data.set` `["CONTEXT_API_KEY"]` and `data.changed.gateway.names`, or `pnpm everyapp secret set CONTEXT_API_KEY --from-env CONTEXT_API_KEY --json`, whose `done` event has `data.gateway.names` `["CONTEXT_API_KEY"]`; then `unset CONTEXT_API_KEY`. Never on a command line, never in the chat (a key seen in the chat gets rotated: step 3 again). Wait for "done".
+
+5. **You:** Verify, below. Neither app needs a restart or redeploy: the Gateway reads the new value on its next request.
+
+## Verify
+
+1. `pnpm everyapp secret list crm --json` or `pnpm everyapp secret list openseo --json`, from anywhere: the `CONTEXT_API_KEY` entry in `data.app.setup.settings` has `"set": true`; for Open CRM it has also left `data.app.setup.unmet`, and `ready` is true once nothing else is missing (its OpenRouter key counts too; until then `command` and `data.next` name only what is left); for OpenSEO it was never in `unmet` (optional). In the older fields, `data.gateway.names` lists it, its `data.gateway.needed` entry has `"set": true` and it has left `data.gateway.missing` (before the app is deployed, the root `pnpm everyapp secret list --json` shows `data.gateway.names` and that is the check). Then `pnpm everyapp status --json`: the `crm` entry's `setup.ready` is true and `data.fixes` has no `APP_NEEDS_SETUP` for it, once everything else is set.
+2. Smoke check, only while the key is exported in the person's terminal (README's third way, before `unset`; or, after the hidden prompt, when they read it in hidden there for this check). After the agent flow nobody but the Gateway holds the key: skip to 3, which with 1 is the check. 0 credits; `--config -` keeps the key out of the process list:
+   `printf 'header = "Authorization: Bearer %s"\n' "$CONTEXT_API_KEY" | curl -sS --config - -w '\n%{http_code}\n' https://api.context.dev/v1/org/usage`
+   Expected: `200` on the last line, and JSON with `credits_remaining` (1,000 on a fresh Free plan; 2,000 when the agent flow's gift applied) and `request_id`, always present; `period.credits_used` and `next_refill.at` (null on a paused account); `key_metadata.credits_consumed`, when present, 0. The body's `error_code` is what the If it fails table keys on: 401 `NOT_FOUND` ("API key not found") or `UNAUTHORIZED` is the key, not the path, and an empty or unset variable gives the same 401; `USAGE_EXCEEDED` (402, or 401 on older deployments) is credits; 401 `DISABLED` a disabled key; 403 `INSUFFICIENT_PERMISSIONS` a Restricted key without the usage read (OpenSEO still works when Data APIs is Use). The Gateway's proxy answers only over an app's binding, so no curl goes through it.
+3. The app. Open CRM: `https://crm.<app base domain>` opens instead of the setup dialog at `https://<gateway host>/?setup=crm` (that dialog means a required setting is still unset: Verify 1 says which), and its research agent reads brand data, LinkedIn profiles and website pages through Context. OpenSEO: open `https://openseo.<app base domain>` (a browser sent to `https://<gateway host>/?setup=openseo` instead means another required setting is unset: [dataforseo.md](dataforseo.md), [openrouter.md](openrouter.md)), a project, then **Site Audit** (the URL is `/p/`, the project's id, `/audit`). The **Render JavaScript** toggle is enabled, with no "needs a Context.dev API key" note (reload if the page was open). Start a small audit of a JavaScript-rendered site (a React or other single-page app) with it on; the audit lists the pages with their content. Each rendered page spends 1 credit: run the usage call again and `period.credits_used` went up, or open the key's usage link on the API keys page. For Open CRM `pnpm everyapp status --json` checks this setting too: its `APP_NEEDS_SETUP` for crm goes once every required setting is set (Verify 1); OpenSEO's never names it.
+4. Logs: the Gateway logs every proxied call as `integration.proxy.call` with the app, path and status, and OpenSEO's own Worker logs `site_audit:render` with `provider: "context"`, `httpStatus`, `creditsUsed` and `outcome`: the status only, never the body, so a 401's `error_code` comes from the smoke check, or from the key's usage link on the API keys page (its recent usage and request logs; whether those show `error_code`: unverified). Cloudflare dashboard, README's path: **Workers & Pages** → `every-app-gateway` → **Observability** (**Logs** on older accounts) → **Live** for a stream, or the stored Workers Logs on the same page (the Gateway's config turns them on). `cf` has no terminal tail: `cf o11y telemetry query --help` reads Workers Logs (read-only; filter on the Gateway's script) and `cf o11y telemetry live-tail` only prepares a websocket, so the dashboard is the simpler path; `npx wrangler tail every-app-gateway` streams them live (wrangler isn't in the checkout: unverified).
+
+## If it fails
+
+| error or symptom                                                                                                                                          | meaning                                                                                                                                             | what to do                                                                                                                                                                                                                                                                                              |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A browser opening the app is sent to `https://<gateway host>/?setup=<app id>`; any other request gets 503 with the body `{"error":"app_needs_setup","app":"<app id>"}` | The Gateway's setup gate: a required setting is still unset (for OpenSEO the DataForSEO or OpenRouter key, never this one; for Open CRM, at `/?setup=crm`, this key or OpenRouter's) | `data.app.setup.command`, `pnpm everyapp configure <app id>` (step 4), then Verify 1                                                                                                                                                                                                                      |
+| `integration_not_configured` (503, header `x-everyapp-error`); OpenSEO's toggle disabled with "needs a Context.dev API key"; `AUDIT_RENDERING_UNAVAILABLE` | The Gateway holds no `CONTEXT_API_KEY` (OpenSEO, which marks `context` optional, opens and shows these; Open CRM, which requires it, stays behind the setup gate instead: the row above) | Step 4; check the name with `secret list --json`; reload OpenSEO (no restart: that note is for Docker)                                                                                                                                                                                                  |
+| `capability_not_requested` (403)                                                                                                                          | The deployed app's manifest doesn't list `context`                                                                                                  | Deploy a current OpenSEO or Open CRM                                                                                                                                                                                                                                                                    |
+| `integration_method_not_allowed` (405), `invalid_integration_route` (400)                                                                                 | A method other than GET or POST, or a host other than `api.context.dev`                                                                             | An app bug, not a key problem                                                                                                                                                                                                                                                                           |
+| `integration_upstream_failed` (502)                                                                                                                       | `api.context.dev` unreachable from the Gateway                                                                                                      | Retry later                                                                                                                                                                                                                                                                                             |
+| `SECRET_VALUE_REQUIRED`                                                                                                                                   | `secret set --json` ran with nothing piped and no terminal to ask in                                                                                | One of the three ways (step 4)                                                                                                                                                                                                                                                                          |
+| `SECRET_VALUE_REQUIRED` from `pnpm everyapp configure <app id> --json`                                                                                   | Nothing was piped (with `--from-env`, stdin isn't read), no variable of a missing name was found, and there is no terminal to ask in; the message names what the app still needs (for OpenSEO this key is optional, so it is never among them) | The person's terminal (step 4), `NAME=value` lines on stdin, or the hidden read then its `data.rerun`, `pnpm everyapp configure <app id> --from-env` (which takes this key's variable too, as an unset optional setting)                                                                                |
+| `SECRET_NOT_DECLARED` from `pnpm everyapp configure <app id> --json`                                                                                     | A piped `NAME=value` line whose name the app's manifest doesn't declare (a typo of `CONTEXT_API_KEY`; the name is echoed only when it looks like one, else `line <n> (not shown: it may be a value)`); nothing was written | The name is exactly `CONTEXT_API_KEY`: pipe the lines again (a bare value goes to `pnpm everyapp secret set CONTEXT_API_KEY`, not to `configure`; a line that isn't `NAME=value` at all is `PIPED_LINE_INVALID`)                                                                                  |
+| `SECRET_SEVERAL_NAMES`                                                                                                                                    | `--from-env` or a pipe with several names                                                                                                           | One name per call                                                                                                                                                                                                                                                                                       |
+| `SECRET_EMPTY`                                                                                                                                            | The `--from-env` variable is empty or unset                                                                                                         | They export it first, in the terminal that runs the command                                                                                                                                                                                                                                             |
+| `SECRET_NOT_DECLARED`                                                                                                                                     | A typo (`context_api_key`, `CONTEXTAPIKEY`, another unknown name): `data.didYouMean` names the close one                                           | The name is exactly `CONTEXT_API_KEY`: rerun with it and the same value source (the pipe, or `--from-env`); `data.rerun` carries only the names, so run as is it stops with `SECRET_VALUE_REQUIRED`                                                                                                  |
+| `SECRET_NOT_SETTABLE`                                                                                                                                     | One of setup's own names (`GATEWAY_URL`, `BETTER_AUTH_SECRET`, …), never this one                                                                   | Check the command: it named another setting                                                                                                                                                                                                                                                             |
+| `SECRET_NAME_INVALID`                                                                                                                                     | A character other than letters, digits and underscore                                                                                               | The name is exactly `CONTEXT_API_KEY`                                                                                                                                                                                                                                                                   |
+| `CONFIRMATION_REQUIRED`                                                                                                                                   | `secret unset --json` without `--yes`: no terminal to confirm in                                                                                    | Rerun with `--yes` only when the person asked                                                                                                                                                                                                                                                           |
+| Provider 401 with `error_code` `NOT_FOUND` ("API key not found") or `UNAUTHORIZED` (the smoke check; the Gateway's log shows the 401 status only)           | Key wrong, pasted incompletely, or an empty variable in the smoke check; not the path                                                               | New key (step 3), set again (step 4)                                                                                                                                                                                                                                                                    |
+| Provider 401 `DISABLED`                                                                                                                                   | Context disabled the key; on Free, every key in the organization after repeated request errors (a rendered audit of an erroring site can do it)     | Stop the audit; read the account email; inspect the key on https://context.dev/dashboard/api-keys and re-enable it once what was failing is fixed, or write support@context.dev. A new key alone doesn't fix the cause                                                                               |
+| Provider `USAGE_EXCEEDED` (402; 401 on older deployments)                                                                                                 | Credits used up; the request isn't run or charged                                                                                                   | Wait for `error_data.next_refill_at`, or the person upgrades or tops up at https://context.dev/dashboard/subscription (the URL the 402 body gives; a first paid plan from the pricing page's plan buttons). Only an Owner or Admin of the Context organization can; the billing docs say Auto-Topup, pauses and cancellation may need a message to Context |
+| Provider 403 `INSUFFICIENT_PERMISSIONS`                                                                                                                   | A Restricted key without Data APIs = Use (or without the usage read: smoke check only)                                                              | A Full access key                                                                                                                                                                                                                                                                                       |
+| Provider 429 with `Retry-After`                                                                                                                           | Concurrency limit (Free: 1-2 in flight), a per-minute limit, or authentication protection after repeated calls with a bad key                       | Not billed; smaller audits, or a higher plan; with a bad key, fix the key, don't retry. OpenSEO never retries a paid call by itself                                                                                                                                                                      |
+| Provider 408, or output `REQUEST_TIMEOUT`                                                                                                                 | The page didn't load within the 30 s OpenSEO allows                                                                                                 | The site's speed, not the key; the audit goes on and logs `outcome: "error"` for that page                                                                                                                                                                                                              |
+| Output `WEBSITE_BLOCKED`                                                                                                                                  | The site served an anti-bot wall to Context too                                                                                                     | Not billed; nothing to fix on the Gateway                                                                                                                                                                                                                                                               |
+| `action_required cloudflare_login` (`waiting: true`) from any command                                                                                     | No Cloudflare login, or it expired; the command logs in by itself                                                                                   | Show `data.url` and `data.code` to the person and keep reading; exit 2 means nobody approved in time: run the command again (`pnpm everyapp login --json` only to log in ahead of time)                                                                                                                    |
+
+## Rerun, rotate, remove
+
+- Rerun: every step is safe to repeat. `configure` and `secret set` replace the value in one new Gateway version; the dashboard shows the keys that exist (Free: two at most, so delete an unused one before creating a third). After an interruption start at Verify and continue at the first step that isn't done.
+- Rotate: the person creates a replacement key (step 3), sets it (step 4; live at once, no deploy), you verify, then they disable the old key from its action menu on https://context.dev/dashboard/api-keys. Rotate too when a teammate who copied the key leaves, or when a key was ever pasted in a chat.
+- Remove: `pnpm everyapp secret unset CONTEXT_API_KEY --json --yes`, and `--yes` only when the person asked (with `--json` and no `--yes` there is no terminal to confirm in: `CONFIRMATION_REQUIRED`). Its `done` event's `data.gateway.names` lists the removed name; a name the Gateway doesn't hold ends `done` with `data.removed: false` and "isn't set on the Gateway. Nothing changed." Then they disable or delete the key in the dashboard: a key the Gateway no longer holds is still a key. Open CRM then needs setup again: the Gateway closes it until the key is back (`status` says so, with this file's path). OpenSEO keeps opening, with the **Render JavaScript** toggle back to disabled and audits without rendering working.
+
+## Sources
+
+- https://www.context.dev (what it is, plans) and https://www.context.dev/pricing (prices, credits per operation, in-flight limits per plan, "any plan returns 401 USAGE_EXCEEDED" when credits run out)
+- https://www.context.dev/signup and https://www.context.dev/login (the forms' fields and links), https://www.context.dev/auth.md and https://docs.context.dev/agent-quickstart.md (the agent key flow: registration errors, the poll's errors and interval, the signup gift)
+- https://docs.context.dev (base URL, Bearer auth), https://docs.context.dev/account/api-keys.md (dashboard page, Full access and Restricted, key limits, rotation), https://docs.context.dev/account/credits.md (credit costs, what isn't billed, one unpaid organization per person), https://docs.context.dev/account/billing.md (allowances, Auto-Topup, 402 and its `info_url`, what the dashboard can't change, Free keys disabled after request errors), https://docs.context.dev/account/team.md (which roles manage billing), https://docs.context.dev/optimization/rate-limits.md (concurrency, 429 headers, authentication protection), https://docs.context.dev/optimization/troubleshooting.md (401 `NOT_FOUND`, `DISABLED`, the 429 causes), https://docs.context.dev/api-reference/usage/retrieve.md (`GET /v1/org/usage`: 0 credits, `logs:read`, which fields are required or null), https://docs.context.dev/api-reference/web-scraping/scrape.md (`POST /v1/web/scrape`, status codes, the legacy 401), https://docs.context.dev/scrape/timeouts-and-errors.md (output error codes)
+- https://developers.cloudflare.com/workers/observability/logs/workers-logs/ (the dashboard path); `cf o11y telemetry --help` and `cf cli search tail` (cf 1.0.0-beta.14)
+- Probed today without a key: `GET https://api.context.dev/v1/web/scrape/html` (the path OpenSEO calls; not in today's docs, but it answers 401 `NOT_FOUND` "No API key provided" while an unknown path answers 404 `ENDPOINT_NOT_FOUND`, so it still exists), `GET /v1/org/usage` (the same 401 body; with a bogus key, 401 `NOT_FOUND` "API key not found"), and `POST https://www.context.dev/oauth2/token` with an unknown claim token (400 `invalid_grant`, no `access_token`)
+- In code: `packages/sdk/src/internal/capabilities.ts` (host, Bearer, trim, GET and POST), `apps/every-app-gateway/src/server/integration-proxy.ts` (the Gateway's codes; its log line carries the status, not the body), `packages/cli/src/lib/secretValue.ts` and `packages/cli/src/commands/secret/index.ts` (the `SECRET_*` codes, `secret list <app>` from anywhere, `data.app.setup`, the kept `data.gateway.needed` and `missing`, `data.next`, `data.removed`, `APP_NOT_FOUND`), `packages/cli/src/commands/configure/index.ts` (`configure <app>`: the prompts, `NAME=value` lines on stdin, `--from-env`, `SECRET_VALUE_REQUIRED`, `SECRET_NOT_DECLARED`), `packages/sdk/src/internal/appSettings.ts` (`AppSetup`: `unmet`, `settings`, `groups`, `command`; `setup/context.md` from the capability registry, `packages/sdk/src/internal/capabilities.ts`), `packages/cli/src/lib/app/settings.ts` (the `Guide:` line), `packages/cli/src/commands/status/problems.ts` (`APP_NEEDS_SETUP`), `apps/every-app-gateway/src/server/app-needs-setup.ts` (the setup gate: the redirect to `/?setup=<app id>` and 503 `app_needs_setup`), `packages/cli/src/lib/output/prompt.ts` (`CONFIRMATION_REQUIRED`), `packages/perimeter/src/manifest/manifest.ts` (what a manifest can bind: no browser); OpenSEO's `src/server/lib/audit/rendered-page.ts`, `rendering-policy.ts`, `src/server/lib/provider-access.ts`, `src/shared/audit-limits.ts`, `everyapp.config.ts` (`context` optional, with its `why`; Open CRM's marks it required) and `docs/SELF_HOSTING_CLOUDFLARE_OPERATIONS.md` (all in OpenSEO's repository)

package/skills/everyapp/setup/dataforseo.md

@@ -0,0 +1,287 @@
+# DataForSEO for the Gateway
+
+DataForSEO is the SEO data provider behind OpenSEO: keyword metrics, SERPs,
+backlinks, local business and AI answer data, and scheduled rank checks.
+The Gateway holds one DataForSEO credential (`DATAFORSEO_API_KEY`) and puts
+it on every call OpenSEO makes to `api.dataforseo.com` (or the free
+`sandbox.dataforseo.com`); the app never sees it. At the end the person has
+a DataForSEO account with credit on it, the Gateway holds the credential,
+and a keyword lookup in OpenSEO returns real numbers.
+
+## Settings
+
+| NAME                 | required or optional | what it holds                                                                                                                                   |
+| -------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DATAFORSEO_API_KEY` | required by OpenSEO and by the DataForSEO MCP app | `login:password`: the API login and API password from the dashboard's API Access page, joined by a colon. The base64 of that string works too. |
+
+The API password is generated by DataForSEO and is not the account's
+sign-in password. The Gateway base64-encodes a value containing a colon and
+sends the result as HTTP Basic auth; a value without a colon is sent as is.
+
+The same credential serves the DataForSEO MCP app, which offers
+DataForSEO's tools to members' AI clients through the Gateway's `/mcp` with
+no page and nothing to deploy: `pnpm everyapp mcp on dataforseo --json` turns
+it on (before or after the key is set; `mcp list` shows both), and members an
+admin grants see `dataforseo_<tool>` tools in their connected client.
+
+## Costs and plans
+
+As of October 2026: a free account gets a $1 trial credit on registration,
+with no time limit, and the Sandbox is free for any registered user (it
+answers like production with made-up data). Real data is pay as you go, no
+subscription; the minimum top-up is $50 and funds do not expire. Daily
+spending limits can be set per account or per endpoint (API Settings). The
+docs state 10,000 API calls per minute and 30 simultaneous requests (the
+older FAQ still says 2,000 per minute); the account's own limits are in the
+`user_data` response. Each keyword lookup costs a few cents: a Google Ads
+search-volume request is $0.09 live, a DataForSEO Labs request starts at
+$0.012 plus $0.00012 per result, a live SERP is $0.002. Since 2026-07-01 the
+Backlinks API is pay as you go like the rest (DataForSEO removed its $100
+monthly commitment; prices went up 20%). No card is asked for at sign-up
+(dataforseo.com/apis/serp-api: "No credit card required"); a card or other
+payment comes in only at Add Funds.
+
+## Only a person can
+
+- Register the DataForSEO account and accept its terms.
+- Read the API login and API password off the API Access page (or their
+  email) and type them at the hidden prompt.
+- Add funds, pick a daily spending limit, or clear an old IP Access list.
+- Decide to replace a credential the Gateway already holds.
+
+## Before you start
+
+1. `pnpm everyapp secret list openseo --json`, from any directory (the app
+   id is `openseo`; a fork may have changed the manifest's `id`): the
+   `DATAFORSEO_API_KEY` entry in `data.app.setup.unmet` (`names`,
+   `need.kind` `required`, `holder` `gateway`, `setup`
+   `setup/dataforseo.md`) means this file applies, and OpenSEO doesn't open
+   until it is set: the Gateway lists it as needing setup, sends a browser
+   opening `https://openseo.<app base domain>` to its setup dialog and
+   answers anything else 503 `app_needs_setup`. `data.app.setup.command` is
+   `pnpm everyapp configure openseo`, which asks for every missing setting
+   (`data.next` repeats it; the OpenRouter key is among them while it is
+   missing: [openrouter.md](openrouter.md); Context is optional for
+   OpenSEO, so `CONTEXT_API_KEY` sits in `data.app.setup.settings` with
+   `set: false` and never in `unmet`, and configure offers it after the
+   required ones: [context.md](context.md)). The same entry in
+   `data.app.setup.settings` with `"set": true` means it is set already: ask
+   before replacing; a value can't be read back, so "replace" means the
+   person fetches the credential again. The older fields still say the same:
+   `data.gateway.needed` has `{ "name": "DATAFORSEO_API_KEY", "required":
+   true, "set": … }` and `data.gateway.missing` names it while unset. This
+   is how an agent lands here: `status` (under "openseo needs setup") and
+   `secret list openseo` (under the unmet setting) print `Guide:
+   .claude/skills/everyapp/setup/dataforseo.md`, and `secret list --json`
+   carries the path as the entry's `setup` (in the checkout the file is
+   `packages/cli/skills/everyapp/setup/dataforseo.md`). The error
+   `APP_NOT_FOUND` ("openseo isn't deployed to this Gateway yet", exit 1):
+   deploy it first. OpenSEO lives in its own repository, which publishes a
+   release on every push: `pnpm everyapp install
+   https://github.com/every-app/open-seo --json` from this checkout installs
+   it (any repository or tarball URL works; `NO_RELEASE` means that one
+   publishes none). From a clone instead: `pnpm install` there, then this
+   checkout's `pnpm everyapp deploy --json` from that directory (a clone's
+   own CLI copy can't deploy; its `pnpm everyapp` is for dev). The key can
+   be set before that deploy all the same (`pnpm everyapp configure` in
+   OpenSEO's directory reads its `everyapp.config.ts` instead of the
+   registry and asks for the Gateway's settings before the first deploy;
+   step 5's root list is then the check, and so is
+   `pnpm everyapp secret list --json` in that directory).
+2. `pnpm everyapp status --json`: `data.installed` and `data.claimed` are
+   true; `data.gatewayUrl` is `https://<gateway host>`; `data.appBaseDomain`
+   is `<app base domain>`. The entry in `data.apps` with `"id": "openseo"`
+   has `"status": "active"`, `"bound": true` and the same `setup` as 1;
+   while a required setting is missing `data.fixes` has `APP_NEEDS_SETUP`
+   for it (severity `warning`, headline "openseo needs setup", `run` the
+   same command). Not installed, or no owner: [gateway.md](gateway.md)
+   first.
+
+## Steps
+
+One step per message: give the step, wait for the words it ends with ("I'm
+in", "I can see them", "done"), then the next. Not a checklist to send at
+once: steps 1 and 2 catch an unconfirmed email and an IP list before the
+value is set.
+
+1. **Person:** Open with the one question: do they already have a
+   DataForSEO account, or has OpenSEO run anywhere else? No account: open
+   https://app.dataforseo.com/register and create it (goal: a DataForSEO
+   account; the API login is whatever the API Access page shows in step 2:
+   DataForSEO generates it, on older accounts it is the sign-up email).
+   Confirm the email if asked: until it is confirmed the API answers 40104.
+   When it worked, the dashboard at app.dataforseo.com opens and shows a $1
+   balance. Already registered: sign in at https://app.dataforseo.com. Ran
+   elsewhere: an OpenSEO deployed outside Every App held the base64 form of
+   the same credential, which works unchanged here (step 4's note), and if
+   that deployment whitelisted its server's IP on API Access, the list has
+   to be emptied (step 2). Wait for "I'm in".
+2. **Person:** Open https://app.dataforseo.com/api-access (API Access in the
+   left menu). It shows the API login, the API password and, for the first 24
+   hours after registration, a ready-made Base64 string of `login:password`.
+   After 24 hours the password is hidden: click **Send by e-mail** (goal: get
+   the password again) and read it from the email. Leave the **IP Access**
+   list on this page empty: the Gateway calls from Cloudflare's addresses,
+   which change, and one entry makes DataForSEO refuse every other address
+   (40207). Keep the page or email open; nothing is typed yet. Wait for "I
+   can see them".
+3. **Person:** Optional now, needed before real use: **Add Funds** in the
+   Billing section or the top bar (goal: credit for live calls; minimum $50),
+   and a daily limit under API Settings, https://app.dataforseo.com/api-settings
+   (counted per 24 hours UTC), so a runaway job stops at a number they chose.
+   The $1 trial credit covers the free smoke check and about ten keyword
+   lookups (at $0.09 a Google Ads request).
+4. **Person:** The README's first way, the person types it. In a second
+   terminal in the `every-app` folder: `pnpm everyapp configure openseo`
+   (from OpenSEO's directory, `pnpm everyapp configure`, which works before
+   its first deploy too), which asks for this key among OpenSEO's other
+   unset settings (the OpenRouter key while it is missing: [openrouter.md](openrouter.md)
+   says where it comes from; the optional Context key is offered after,
+   and Enter skips it), or `pnpm everyapp secret set DATAFORSEO_API_KEY`
+   for just this one. At the hidden prompt (`DATAFORSEO_API_KEY`, under
+   lines saying what it is for and where it comes from; `secret set` asks
+   `Value for DATAFORSEO_API_KEY`), paste the API login, a colon, and the
+   API password (`login:password`): the form to recommend, since Verify
+   2's check takes it as is. Nothing is echoed. It ends with the setting
+   live on the Gateway (`Set DATAFORSEO_API_KEY on the Gateway`; configure
+   then says `openseo is ready.` or what it still needs). Wait for "done".
+   (The page's Base64 string, or the value an older OpenSEO held, works
+   too; Verify 2 then needs its `header =` form.)
+   Alternative, README's third way, when they want the smoke check (Verify
+   2) as well: in their terminal the hidden read (bash or zsh
+   `read -rs DATAFORSEO_API_KEY && export DATAFORSEO_API_KEY`, fish
+   `read -s -x DATAFORSEO_API_KEY`), paste `login:password`, Enter, then there
+   `pnpm everyapp configure openseo --from-env --json` (every unset setting
+   whose variable is exported, at once) or
+   `pnpm everyapp secret set DATAFORSEO_API_KEY --from-env DATAFORSEO_API_KEY --json`;
+   never a typed `export …=`, which the shell history keeps. No DataForSEO
+   CLI or API returns the credential, so the second way does not apply.
+5. **You:** `pnpm everyapp secret list --json`: `DATAFORSEO_API_KEY` is in
+   `data.gateway.names`. Then the Verify section.
+
+## Verify
+
+1. `pnpm everyapp secret list openseo --json`, from anywhere: the
+   `DATAFORSEO_API_KEY` entry in `data.app.setup.settings` has `"set": true`
+   and has left `data.app.setup.unmet`; `data.app.setup.ready` is true once
+   nothing else of OpenSEO's is missing (its OpenRouter key counts too,
+   Context doesn't; until then `command` and `data.next` name only what is
+   left). In the older fields, its `data.gateway.needed` entry has
+   `"set": true` and the name left `data.gateway.missing`. Then
+   `pnpm everyapp status --json`: the `openseo` entry's `setup.ready` is
+   true and `data.fixes` has no `APP_NEEDS_SETUP` for it, once everything
+   else is set. OpenSEO not deployed yet (`APP_NOT_FOUND`): step 5's root
+   list is the check until it is.
+2. Smoke check, in the person's terminal (the endpoint is account-wide, so
+   the Gateway refuses it for apps; from the terminal it is the right check).
+   It needs the variable in that shell, holding the same form they pasted
+   in step 4: after the hidden prompt nothing is exported, so either have
+   them read it in hidden again for this check (README's third way:
+   `read -rs DATAFORSEO_API_KEY && export DATAFORSEO_API_KEY`, paste,
+   Enter), or let the app be the check (3). The credential reaches curl
+   as a config file on stdin, never on the command line (`printf` is a shell
+   builtin, so no process carries it):
+   `printf 'user = "%s"\n' "$DATAFORSEO_API_KEY" | curl -s -K - https://api.dataforseo.com/v3/appendix/user_data | jq '{status: .status_code, message: .status_message, balance: .tasks[0].result[0].money.balance}'`
+   Expected: `"status": 20000`, `"message": "Ok."`, and the balance in USD
+   (1 on a fresh account). The call is free. A wrong credential prints
+   `"status": 40100` and `"balance": null`; the Base64 form in `user =`
+   prints the same, so when the variable holds Base64 (step 4's note), give
+   them this line instead, before reading 40100 as a wrong login or password:
+   `printf 'header = "Authorization: Basic %s"\n' "$DATAFORSEO_API_KEY" | curl -s -K - https://api.dataforseo.com/v3/appendix/user_data | jq …`
+   Then `unset DATAFORSEO_API_KEY`.
+3. The app: open `https://<app>.<app base domain>` (the id from
+   `data.apps`, usually `openseo`), open a project, then **Keyword Research**
+   (under Research in the sidebar; the URL ends in `/keywords`), and search
+   one keyword. Search volume and difficulty appear; each lookup costs a few
+   cents. A browser that lands on the Gateway's setup dialog instead
+   (`https://<gateway host>/?setup=openseo`) means a required setting is
+   still unset: Verify 1 says which. OpenSEO shows one message for a
+   missing key and a rejected one alike: "DataForSEO isn't set up on your
+   Every App gateway yet, or rejected the key it holds. An owner or admin
+   sets it with pnpm everyapp secret set DATAFORSEO_API_KEY." Tell them apart with
+   `pnpm everyapp secret list --json`: `DATAFORSEO_API_KEY` absent from
+   `data.gateway.names` means step 4 did not land (behind the Gateway's
+   setup gate the app doesn't open in that state, so expect the second);
+   present means the value is wrong (Verify 2 says which way). The
+   Gateway's log tells them apart too (4).
+4. Logs, if that helps: `cf` has no Worker tail (`cf workers --help` lists
+   none). In the Cloudflare dashboard, README's path:
+   **Workers & Pages** → `every-app-gateway` → **Observability** (**Logs** on older accounts) → **Live**
+   for a stream, or the stored Workers Logs on the same page. Each call that reached
+   DataForSEO is one JSON line with `evt: "integration.proxy.call"`,
+   `capability: "dataforseo"`, the path, the upstream `status` and
+   DataForSEO's `cost`; the keys are indexed, so filter on `evt`. A wrong
+   value shows `status: 401` there. A key the Gateway does not hold is
+   refused before any call, so no event appears at all;
+   `evt: "integration.proxy.upstream_failed"` means DataForSEO could not be
+   reached. Without the dashboard, `cf o11y telemetry query --view events --limit 50 --timeframe-from <ms> --timeframe-to <ms> --body '<query JSON>'`
+   reads the same stored logs (read-only); the query body that filters on
+   `evt` is not worked out yet (unverified).
+
+## If it fails
+
+| error or symptom                                                                   | meaning                                                                                                                | what to do                                                                                                                    |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `SECRET_VALUE_REQUIRED` from `secret set --json`                                   | Nothing was piped and there is no terminal to prompt in                                                                | One of the README's three ways: the person's own terminal, or `--from-env`                                                    |
+| `SECRET_VALUE_REQUIRED` from `pnpm everyapp configure openseo --json`             | Nothing was piped (with `--from-env`, stdin isn't read), no variable of a missing name was found, and there is no terminal to ask in; the message names what OpenSEO still needs | The person's own terminal (step 4), `NAME=value` lines on stdin, or the hidden read then its `data.rerun`, `pnpm everyapp configure openseo --from-env` |
+| `SECRET_SEVERAL_NAMES`                                                             | `--from-env` or a pipe with more than one name                                                                         | One name per call                                                                                                             |
+| `SECRET_EMPTY`                                                                     | The `--from-env` variable is empty or not exported in that shell                                                       | The hidden read (README's third way) in that same terminal first, then rerun                                                  |
+| A browser opening OpenSEO is sent to `https://<gateway host>/?setup=openseo`; any other request gets 503 with the body `{"error":"app_needs_setup","app":"openseo"}` | The Gateway's setup gate: a required setting of OpenSEO is still unset (this key or the OpenRouter one; Context is optional) | `data.app.setup.command`, `pnpm everyapp configure openseo` (step 4), then Verify 1                                  |
+| `integration_not_configured` (503, header `x-everyapp-error`)                      | The Gateway holds no `DATAFORSEO_API_KEY`; OpenSEO shows it as "DataForSEO isn't set up on your Every App gateway yet, or rejected the key it holds. An owner or admin sets it with pnpm everyapp secret set DATAFORSEO_API_KEY." (behind the setup gate the app doesn't open in this state) | Steps 4 and 5; check the name's spelling in `data.gateway.names`                                                 |
+| `capability_not_requested` (403)                                                   | The deployed manifest does not list `capabilities.dataforseo`                                                          | OpenSEO's does; a fork must add it to `everyapp.config.ts` and deploy again                                                   |
+| `integration_path_not_allowed` (403)                                               | The app called an account-wide path (`appendix/user_data`, `appendix/webhook_resend`, `tasks_ready`, `id_list`, `errors`) | By design: one key serves every app. Check balance and limits from the terminal (Verify 2)                                 |
+| `integration_method_not_allowed` (405)                                             | A method other than GET or POST                                                                                        | DataForSEO reads with GET and POST only                                                                                       |
+| `integration_upstream_failed` (502)                                                | The Gateway could not reach DataForSEO                                                                                 | Retry; a persisting failure is on DataForSEO's side                                                                           |
+| `status_code` 40100, or HTTP 401, "you are not authorized to access this resource" | Wrong login or password: the sign-in password instead of the API password, a typo, whitespace                          | Re-read API Access (or Send by e-mail), set it again (step 4); the `user` form needs `login:password`, not base64             |
+| 40104 "please verify your account before using the api"                            | The sign-up email is not confirmed yet                                                                                 | Open DataForSEO's confirmation email, click its link, rerun Verify 2                                                          |
+| 40200 "payment required", 40210 "insufficient funds"                               | The balance is too low for the request                                                                                 | Add Funds (minimum $50)                                                                                                       |
+| 40203 "the cost limit has been exceeded"                                           | The daily spending limit in API Settings was reached (counted per 24 hours UTC)                                        | Raise it at https://app.dataforseo.com/api-settings, or wait for 00:00 UTC                                                    |
+| 40202 "rate-limit per minute has been exceeded", 40209 "too many simultaneous queries" | Over the per-minute or 30-concurrent limit                                                                         | Retry after a pause; OpenSEO's scheduled checks spread out on their own                                                       |
+| 40204 "access denied. visit plans and subscriptions"                               | Left over from the Backlinks commitment DataForSEO removed on 2026-07-01; a funded pay-as-you-go account should not see it | Contact DataForSEO, https://dataforseo.com/contact                                                                         |
+| 40207 "access denied. your ip is not whitelisted"                                  | API Access has an IP list; the Gateway's Cloudflare addresses are not on it                                            | The person removes every entry under IP Access on https://app.dataforseo.com/api-access (step 2)                              |
+| 40201 "unusual activity"                                                           | DataForSEO paused the account                                                                                          | The person contacts DataForSEO at https://dataforseo.com/contact (a form; the page says support is available 24/7)            |
+| 40400 or 40402 "invalid path"                                                      | The endpoint path is wrong                                                                                             | An app bug, not a setup problem: compare with docs.dataforseo.com                                                             |
+| `curl` prints nothing, or `jq` reports that the input is not JSON                  | The variable is empty, or the response is not JSON (a redirect or block page)                                          | `printf … \| curl -s -K - -o /dev/null -w '%{http_code}\n' …` with the same stdin config to see the HTTP status; never print the variable |
+
+## Rerun, rotate, remove
+
+- **Rerun.** Every step is safe to repeat: the dashboard shows what exists,
+  `configure` and `secret set` replace the value in one new Gateway version
+  (once OpenSEO is ready, configure's menu changes one setting at a time),
+  and the Verify section says where to continue after an interruption.
+- **Rotate.** The person changes the API login in API Access (documented:
+  the old `login:password` and its base64 stop working). A new API password
+  needs DataForSEO's support (https://dataforseo.com/contact): the help
+  center mentions regenerating it from the dashboard but documents no
+  control for it, and Send by e-mail resends the same one. Then step 4 again
+  with the new value, then Verify. A value that went through the chat is
+  compromised: rotate it, then set it one of the three ways.
+- **Remove.** `pnpm everyapp secret unset DATAFORSEO_API_KEY --json`. Without
+  `--yes` it exits 1 with `CONFIRMATION_REQUIRED`: that is the ask; rerun
+  with `--yes` only once the person has said yes. OpenSEO then needs setup
+  again: the Gateway closes it until the key is back (its manifest marks
+  `dataforseo` required; `status` says so, with this file's path). Then
+  revoke on DataForSEO's side: change the API login (or have
+  support issue a new password), or close the account if nothing else uses
+  it.
+
+## Sources
+
+- https://docs.dataforseo.com/v3/auth/ (API login and password, Basic auth, API Access page)
+- https://docs.dataforseo.com/v3/appendix/user_data/ (the free account endpoint; `result` is an array, `money.balance`, `rates.limits`; `backlinks_subscription_expiry_date` deprecated)
+- https://docs.dataforseo.com/v3/appendix/errors/ (status codes 20000 to 50000, 40104, 40207; the 40204 note still names the old Backlinks commitment)
+- https://docs.dataforseo.com/v3/appendix-sandbox/ (sandbox host, free, dummy data, limits)
+- https://dataforseo.com/pricing (pay as you go, $50 minimum, $1 trial credit, funds do not expire)
+- https://dataforseo.com/pricing/keywords-data/google-ads ($0.09 per live task, $0.06 standard, billed per task) and https://dataforseo.com/pricing/dataforseo-labs ($0.012 per task plus $0.00012 per item)
+- https://dataforseo.com/apis/serp-api ("No credit card required", $1 credit, $0.002 per live SERP)
+- https://dataforseo.com/update/pricing-update-in-dataforseo-apis (2026-07-01: the $100 Backlinks and LLM Mentions commitment removed, +20%)
+- https://dataforseo.com/faq (2,000 calls per minute, $50 minimum, trial credit)
+- https://dataforseo.com/help-center/dfs-dashboard-how-to-find-everything (API login is generated and changed in API Access, Send by e-mail, Payments, API Settings; no regenerate control)
+- https://dataforseo.com/help-center/how-to-authenticate-with-dataforseo-google-search-serp-api-api-key-setup-and-code-examples (sign-up link, 24-hour visibility; calls the login the sign-up email)
+- https://dataforseo.com/help-center/how-does-your-free-unlimited-trial-work (trial terms, one account per user)
+- https://dataforseo.com/help-center/whitelist-ips (IP Access on the API Access page, 40207, static IPs only, empty list means no restriction)
+- https://dataforseo.com/help-center/limit-my-payments (API Settings, per API or endpoint, 24 hours UTC, 40203)
+- https://dataforseo.com/contact (form and phone; "support available 24/7"; no support@ address anywhere on it)
+- https://developers.cloudflare.com/workers/observability/logs/real-time-logs/ (Workers & Pages, Overview, Worker, Logs, Live; `npx wrangler tail`) and https://developers.cloudflare.com/workers/observability/logs/workers-logs/ (Observability tab; JSON log keys are indexed as fields)
+- https://app.dataforseo.com/register and https://app.dataforseo.com/api-access (the pages the person opens; both load a signed-in app, so their text was not read)
+- In code: `packages/sdk/src/internal/appSettings.ts` (`AppSetup`: `unmet`, `settings`, `groups`, `command`; `setup/dataforseo.md` from the capability registry, `packages/sdk/src/internal/capabilities.ts`), `packages/cli/src/commands/secret/index.ts` (`secret list <app>` from anywhere, `data.app.setup`, the kept `data.gateway.needed` and `missing`, `APP_NOT_FOUND`), `packages/cli/src/commands/configure/index.ts` (`configure <app>`: the prompts, `NAME=value` lines on stdin, `--from-env`, `SECRET_VALUE_REQUIRED`), `packages/cli/src/lib/app/settings.ts` (the `Guide:` line), `packages/cli/src/commands/status/problems.ts` (`APP_NEEDS_SETUP`), `apps/every-app-gateway/src/server/app-needs-setup.ts` (the setup gate: the redirect to `/?setup=<app id>` and 503 `app_needs_setup`); OpenSEO's `everyapp.config.ts` (`dataforseo` required, with its `why`)