everyapp 0.2.2 → 0.3.0-rc.1

package/skills/everyapp/setup/slack.md

@@ -0,0 +1,344 @@
+# Slack for the Gateway
+
+One Slack app, registered once at api.slack.com, whose OAuth client the
+Gateway holds. Open CRM uses it: an owner or admin connects their workspace
+from **Settings → Connections**, and the CRM's team agents post to approved
+channels, manage those channels and match members to Slack users by email.
+At the end the person has a Slack app in their workspace, the Gateway holds
+its Client ID and Client Secret, and **Connect Slack** in Open CRM completes.
+
+## Settings
+
+| Name                  | Required | What it holds                                                                                          |
+| --------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `SLACK_CLIENT_ID`     | required | The app's **Client ID** (Basic Information → App Credentials), as shown. Public; apps get it for the authorize URL. |
+| `SLACK_CLIENT_SECRET` | required | The app's **Client Secret** from the same section, as shown. The Gateway puts it on `oauth.v2.access` only. |
+
+Set both: the Gateway offers Slack only when it holds the two.
+
+## Costs and plans
+
+As of October 2026: creating a Slack app is free, no card. It needs a Slack
+workspace the person may add apps to; Slack's free plan allows 10 app
+installs per workspace, custom apps included. `apps.manifest.create` is Tier
+1 (about one call a minute); `chat.postMessage` allows about one message a
+second per channel. Slack's 2025 limit on `conversations.history` (1 request
+a minute, 15 objects) applies to apps sold outside the Marketplace, not to
+an internal app installed in its own workspace.
+
+## Only a person can
+
+- Sign in to Slack and pick the workspace. Anyone can create the app; a
+  workspace that requires approved apps turns the install into a request a
+  Workspace Owner (or an app manager they named) approves first. That
+  approval is a wait: resume at Verify 3 once they say it is approved.
+- Create the app in the browser, or generate the app configuration token
+  that lets you create it.
+- Copy the Client ID and Client Secret off Basic Information (path A).
+- Click **Allow** on Slack's consent page when connecting Open CRM.
+
+## Before you start
+
+1. `pnpm everyapp secret list crm --json`, from any directory (the id reads
+   the manifest Open CRM's last deploy stored; in its directory the id can
+   be left off), before the Slack side, not at Verify. The rule: read
+   `data.app.setup.settings`, `unmet` and `command`. The client is one
+   setting there, `id: "slack"`, `kind: "capability"`, `holder:
+   "gateway"`, `names: ["SLACK_CLIENT_ID", "SLACK_CLIENT_SECRET"]` (an
+   OAuth client's id and secret are the two names of one setting, set
+   only when both are), `need.kind` as the CRM's manifest declares it
+   (Open CRM: `optional`: it sits in `settings` with `set: false`, never
+   in `unmet`, the CRM opens without Slack and `command`,
+   `pnpm everyapp configure crm`, offers it after the required ones;
+   `required` would put it in `unmet`, close the CRM and have configure
+   ask for both names first), `setup: "setup/slack.md"` (this file). While
+   its `set` is false this file applies.
+   The same entry in `data.app.setup.settings` with `set: true`: ask
+   before replacing (a new app, or a regenerated secret). Not deployed
+   yet: `secret list crm` stops with `APP_NOT_FOUND`; a bare
+   `pnpm everyapp secret list --json` from the checkout still says whether
+   the two names are in `data.gateway.names` (ask before replacing), and
+   the rest of this item waits for the first deploy.
+2. `pnpm everyapp status --json`: `data.installed` and `data.claimed` are
+   true; `data.appBaseDomain` is `<app base domain>` (the redirect URL to
+   register is `https://<app>.<app base domain>/integrations/slack/callback`,
+   deployed as `crm`: `https://crm.<app base domain>/integrations/slack/callback`);
+   Open CRM's entry in `data.apps[]` (its `id`, `crm` below) has
+   `"status": "active"`, `"bound": true`, the `workerName` Verify 4 needs
+   and, as `setup`, 1's `data.app.setup` again: what else the CRM needs.
+   Not deployed yet: the URL is the same, so the Slack side can go first;
+   Verify 3 needs the CRM deployed.
+3. In 1's answer, `data.app.workers[].names` must hold
+   `TOKEN_ENCRYPTION_KEY`, the CRM's own secret its Slack connect needs (it
+   stores the tokens encrypted under it; optional in the manifest, so its
+   entry sits in `settings` with `holder: "app"`, never in `unmet`).
+   Unset: set it first, after the CRM's first deploy, at the hidden prompt
+   of `pnpm everyapp configure crm` (which offers it with the optional
+   ones) or `pnpm everyapp secret set TOKEN_ENCRYPTION_KEY --app crm`, from
+   anywhere, 32 or more random characters, never through the chat; without
+   it **Connect Slack** stops
+   before Slack opens (the table). Not deployed yet: set it right after its
+   first deploy, before Verify 3.
+4. Ask: which workspace; whether a Slack app for this exists already at
+   https://api.slack.com/apps (reuse it: step 2a's second paragraph); and
+   whether they have `curl` and `jq` (path B).
+5. Pick a path. **A**: they create the app from a manifest in the browser
+   and type the client at a hidden prompt. **B**: they generate an app
+   configuration token; `apps.manifest.create` returns the client, piped in.
+
+## Steps
+
+1. **You:** write the manifest to a file outside the repository, say
+   `/tmp/slack-manifest.json`, with `<app>` (Open CRM's `id`) and
+   `<app base domain>` filled in. Nothing in it is secret.
+
+   ```json
+   {
+     "_metadata": { "major_version": 2, "minor_version": 1 },
+     "display_information": {
+       "name": "Open CRM",
+       "description": "Team agents post to your Slack channels from Open CRM."
+     },
+     "features": { "bot_user": { "display_name": "open-crm", "always_online": false } },
+     "oauth_config": {
+       "redirect_urls": ["https://<app>.<app base domain>/integrations/slack/callback"],
+       "scopes": {
+         "bot": ["users:read", "users:read.email", "channels:read", "groups:read", "chat:write", "chat:write.public", "im:write", "channels:join", "channels:manage", "groups:write", "channels:write.invites", "groups:write.invites"],
+         "user": ["channels:read", "channels:write", "groups:read", "groups:write"]
+       }
+     },
+     "settings": { "org_deploy_enabled": false, "socket_mode_enabled": false, "token_rotation_enabled": false }
+   }
+   ```
+
+   Use these lists as written: they are Open CRM's own (its
+   `src/shared/slack.ts`, which matters only when a newer CRM changes them;
+   a CRM directory with no `src/` has nothing to compare, and needs none):
+   bot scopes to post, manage channels and match members by email; user
+   scopes so the installer can invite the bot to private channels. Its
+   authorize URL carries them as `scope` (bot) and `user_scope` (user), and
+   that URL decides what Slack asks the installer for: Slack's docs name
+   only `invalid_scope` (a scope that doesn't exist, or conflicting ones)
+   and `unapproved_scope` (a published Marketplace app requesting scopes
+   its review didn't cover) on the authorize URL. The manifest's lists are
+   what the console's own Install button and a reinstall request. The
+   registry (`packages/sdk/src/internal/capabilities.ts`, the `slack`
+   entry's `scopePolicy`, #425) groups them into sets an app lists in its
+   manifest entry (`everyapp deploy` refuses `slack` without `scopes`):
+   bot sets `channels.read`, `users.read`, `users.email`,
+   `messages.write`, `channels.join`, `channels.manage`, `files.write`,
+   user set `user-channels.manage` (the table in docs/capabilities.md,
+   "OAuth clients"). Open CRM lists all but `files.write`; the lists
+   above are the provider scopes behind its sets, less
+   `chat:write.customize` (in `messages.write`; the CRM doesn't ask for
+   it). The Gateway holds the CRM to its sets at `oauth.v2.access` (#411):
+   an entry without `scopes` is refused (`integration_scopes_undeclared`),
+   an installation carrying a scope outside them too
+   (`integration_scope_exceeded`: reinstall from the CRM); a CRM deployed
+   before its manifest carried `scopes` must redeploy before the Gateway
+   is updated from main (TODO.md "OAuth scopes (2026-10-24)", follow-up 0).
+   Slack's limits: `name` 35 characters, `description` 140; `display_name`
+   takes a-z, 0-9, `-`, `_` and `.` only. Step 3b validates the file first.
+
+2a. **Person (path A):** open https://api.slack.com/apps, signed in to
+   Slack: **Create New App** (https://api.slack.com/apps?new_app=1 opens
+   that dialog) → **From an app manifest** (older dialogs: **From a
+   manifest**) → pick the workspace → **Next** → the **JSON** tab, paste
+   the file's content → **Next** (the review lists the name, the redirect
+   URL and the scopes) → **Create**. It lands on **Basic Information**,
+   whose **App Credentials** section shows **Client ID** and a hidden
+   **Client Secret**; 3a uses both.
+   Reusing an app: **OAuth & Permissions**, add the redirect URL under
+   **Redirect URLs** and save; under **Scopes**, add the bot scopes to **Bot
+   Token Scopes** (**Add an OAuth Scope**) and the user scopes to **User
+   Token Scopes**. Or, with path B's token, `apps.manifest.update` with
+   `app_id=` and the same manifest; it returns no credentials.
+
+3a. **Person (path A):** in a second terminal, in the `every-app` folder:
+   `pnpm everyapp configure crm` (it asks for the client's two names, id
+   then secret, with hidden prompts, after the CRM's required settings;
+   the client is optional for Open CRM, so Yes to `Set the N optional
+   settings too?`, Enter skipping the others; with one of the two
+   names set it asks only for the other; or pick
+   `SLACK_CLIENT_ID + SLACK_CLIENT_SECRET` from the menu once the CRM is
+   ready) or `pnpm everyapp secret set SLACK_CLIENT_ID SLACK_CLIENT_SECRET`
+   for just these two (README's first way; no `--json`, so it prompts).
+   Paste the Client ID at the first prompt; click **Show** next to Client
+   Secret and paste it at the second. Nothing is echoed. Give 2a and 3a in
+   one message and wait once, until they say both values are in (a create
+   that failed, they report instead). Go to Verify.
+
+2b. **Person (path B):** open https://api.slack.com/apps; below the list of
+   apps, under **Your App Configuration Tokens**, click **Generate Token**,
+   pick the workspace, **Generate**; copy the **Access Token** (it starts
+   `xoxe.xoxp-`, expires 12 hours later, and adds "Slack Tooling Tokens
+   Vendor" to the workspace). In their terminal, in the `every-app` folder,
+   read it in hidden (README's third way), never on a command line or in a
+   typed `export …=`, which the shell history keeps: bash or zsh
+   `read -rs SLACK_CONFIG_TOKEN && export SLACK_CONFIG_TOKEN`, fish
+   `read -s -x SLACK_CONFIG_TOKEN`; they paste the token and press Enter;
+   nothing is echoed. Wait until they say it is exported.
+
+3b. **Person (path B)**, or **You** when they exported it before starting
+   you: one line at a time. `printf` keeps the token out of the process
+   list; `-d @-` reads it from stdin.
+
+   ```sh
+   printf 'token=%s' "$SLACK_CONFIG_TOKEN" | curl -s -d @- --data-urlencode manifest@/tmp/slack-manifest.json https://slack.com/api/apps.manifest.validate
+   ```
+
+   Expect `{"ok":true,"errors":[]}`; `invalid_manifest` names each problem
+   in `errors[].pointer`. Then, once only (each run makes another app). The
+   answer carries three secrets (`client_secret`, `signing_secret`,
+   `verification_token`), so it goes to a file only you and `jq` read,
+   created private first, and removed on the same line as the last pipe:
+
+   ```sh
+   install -m 600 /dev/null /tmp/slack-app.json
+   printf 'token=%s' "$SLACK_CONFIG_TOKEN" | curl -s -d @- --data-urlencode manifest@/tmp/slack-manifest.json https://slack.com/api/apps.manifest.create > /tmp/slack-app.json
+   jq -e '.ok' /tmp/slack-app.json && jq '.app_id' /tmp/slack-app.json
+   jq -r '.credentials.client_secret // empty' /tmp/slack-app.json | pnpm everyapp secret set SLACK_CLIENT_SECRET --json
+   jq -r '.credentials.client_id // empty' /tmp/slack-app.json | pnpm everyapp secret set SLACK_CLIENT_ID --json; rm -f /tmp/slack-app.json
+   ```
+
+   README's second way. `jq -e '.ok'` printing `false`: `jq '.error'`
+   names why (step 1, or the name is taken); stop and
+   `rm -f /tmp/slack-app.json`. `// empty` keeps a missing field from
+   going in as the string `null`: the pipe is empty and `secret set` stops
+   with `SECRET_VALUE_REQUIRED`. Never print the file, and remove it even
+   when a step failed. Each `secret set` ends with a `done` event. Keep the
+   `app_id` for Verify.
+
+## Verify
+
+1. `pnpm everyapp secret list crm --json`, from anywhere: the `slack`
+   setting has `set: true` (optional for Open CRM, so it was never in
+   `data.app.setup.unmet`; a manifest that requires it has it leave
+   `unmet`, with `ready: true` and `command` null once nothing else is
+   missing); both names in `data.gateway.names`, `"set": true` in
+   `data.gateway.needed`, not in `data.gateway.missing`. Then
+   `pnpm everyapp status --json`: the `crm` entry's `setup.ready` is true
+   and `data.fixes` has no `APP_NEEDS_SETUP` for it (the Gateway opens the
+   CRM again).
+2. Smoke check, in the person's terminal while `SLACK_CONFIG_TOKEN` is
+   exported (path B), after `export SLACK_APP_ID=<app_id>` (fish:
+   `set -x SLACK_APP_ID <app_id>`; the id isn't secret):
+
+   ```sh
+   printf 'token=%s&app_id=%s' "$SLACK_CONFIG_TOKEN" "$SLACK_APP_ID" | curl -s -d @- https://slack.com/api/apps.manifest.export | jq '.manifest.oauth_config'
+   ```
+
+   Expected: `redirect_urls` holds exactly
+   `https://<app>.<app base domain>/integrations/slack/callback`, and
+   `scopes.bot` and `scopes.user` the lists in step 1. Then
+   `unset SLACK_CONFIG_TOKEN SLACK_APP_ID` (fish: `set -e`). Path A: the
+   same is on the app's **OAuth & Permissions** page.
+3. The app, deployed and open: 1's `data.app.setup.ready` true. While
+   another required setting of the CRM is unmet, the Gateway sends a
+   browser to its setup dialog instead of the CRM (anything else gets 503
+   `app_needs_setup`): finish those first (each `unmet` entry's `setup`
+   names its file); until then 1 is the check of the Slack client. Then
+   at `https://<app>.<app base domain>`, **Settings →
+   Connections → Slack** (an owner or admin). With the client on the
+   Gateway the card has **Connect Slack**; without it the section reads
+   **Slack is not configured** and, for an owner or admin, shows the
+   redirect URL and `pnpm everyapp secret set SLACK_CLIENT_ID SLACK_CLIENT_SECRET`
+   (Verify 1 again; the same when the deployed CRM doesn't list `slack`,
+   or lists it without `scopes`).
+   **Connect Slack**: Slack's page names the app and the workspace and
+   lists the permissions; **Allow**; the CRM comes back connected and shows
+   the workspace. Otherwise its page says why, `?error=` naming one of
+   seven: `access_denied` (Cancel was clicked), `invalid_state` (the
+   approval is older than ten minutes, was used already, or was started by
+   someone else: start again), `forbidden` (not an owner or admin),
+   `rejected` (Slack sent another error, or no code: try again),
+   `exchange_failed` (the token call returned no token: Verify 4, then the
+   table), `failed` (the CRM couldn't store the tokens: its log has
+   `[slack] connect failed`), `not_configured` (local dev only: the CRM
+   has no Gateway binding).
+4. Logs. Slack's error code is in Open CRM's Worker, not the Gateway's: the
+   Cloudflare dashboard, README's path with the CRM's Worker in place of
+   the Gateway's: **Workers & Pages** → the `crm` entry's `workerName` →
+   **Observability** (**Logs** on older accounts) → **Live** (Workers Logs keeps them; `cf workers` has
+   no tail, and `cf o11y telemetry query` needs a query body). On
+   `exchange_failed` the line `[slack] connect refused` carries `status`
+   and `reason`: Slack's code (`invalid_code`, `bad_redirect_uri`,
+   `invalid_client_id`, `bad_client_secret`: the table), or a Gateway
+   refusal that reached the callback (`status` 503, reason
+   `Service Unavailable`: `integration_not_configured`; 403, `Forbidden`:
+   `capability_not_requested`, `integration_scopes_undeclared` (the
+   deployed CRM lists `slack` without `scopes`) or
+   `integration_scope_exceeded` (the installation carries a scope outside
+   the CRM's sets: reinstall from the CRM)). The Gateway's own log (`every-app-gateway`,
+   same path) has one `integration.proxy.call` per token call:
+   `capability`, host, path, method, `grantType` (the request's
+   `grant_type`) and `status`; never the body, and Slack answers `200` with
+   `"ok": false` on a bad client, so it says only whether the call went
+   through.
+
+## If it fails
+
+| Error or symptom                                                               | Meaning                                                                                  | What to do                                                                                              |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `SECRET_VALUE_REQUIRED`                                                        | Nothing was piped (path B: the field was missing, so `// empty` piped nothing) and there is no terminal to prompt at | `jq '.error' /tmp/slack-app.json`; or one of README's three ways (its `data.rerun` shows the `--from-env` form) |
+| `SECRET_VALUE_REQUIRED` from `pnpm everyapp configure crm --json`             | Nothing was piped (with `--from-env`, stdin isn't read), no variable of a missing name was found, and there is no terminal; the message names what the CRM still needs (this client is optional for Open CRM, so never among them) | The pipes in 3b, or the person's terminal (3a)                                              |
+| `SECRET_SEVERAL_NAMES`                                                         | A pipe or `--from-env` with two names                                                    | One name per call (the fix in `data.fix`)                                                                |
+| `SECRET_NOT_DECLARED` with `data.didYouMean`                                   | The name differs from a known one in case or underscores only                            | rerun with the name in `data.didYouMean` and the same value source (`--from-env VAR --json`, or the same pipe); `data.rerun` carries only the names, so run as is it stops with `SECRET_VALUE_REQUIRED` |
+| `SECRET_NOT_DECLARED` without it                                               | A misspelt name; in Open CRM's directory its `data.fix` offers to add it to the CRM's own `secrets` | Retype the name from Settings above; never add a `SLACK_*` name to Open CRM's `secrets`            |
+| CRM: **Slack is not configured**, the `secret set` command, no **Connect Slack** | The Gateway holds no client, or one of the two names (a call would get `integration_not_configured`); or the deployed CRM doesn't list `slack` with `access: "write"` and `scopes` (`capability_not_requested`; without `scopes`, `integration_scopes_undeclared`) | `secret set` both, then Verify 1; or its `everyapp.config.ts` (`slack: { access: "write", scopes: [...], why }`), then `pnpm everyapp deploy --json` in its directory |
+| CRM: `exchange_failed`; its log `[slack] connect refused` with `status` 503 or 403 | The Gateway refused between **Connect Slack** and the callback: the client was unset, or the manifest changed, meanwhile | The row above, then connect again                                                              |
+| CRM: **Connect Slack** fails before Slack opens: "Connections aren't set up on this CRM yet" | The CRM's own `TOKEN_ENCRYPTION_KEY` is unset, or under 32 characters                 | Set it after the CRM's first deploy: `pnpm everyapp configure crm` (which asks for it) or `pnpm everyapp secret set TOKEN_ENCRYPTION_KEY --app crm` from anywhere (in the CRM's directory the flag can be left off), the value in one of README's three ways (Before you start 3); connect again |
+| Slack's page: "redirect_uri did not match any configured URIs", then `Passed URI: …` | The URI the CRM sent isn't registered on the app exactly, or under a registered URL  | Register the Passed URI, `https://<app>.<app base domain>/integrations/slack/callback` (https only, no `#`), under OAuth & Permissions → Redirect URLs; Verify 2 |
+| `bad_redirect_uri` (token call)                                                | `redirect_uri` differed between the authorize and token calls                            | The CRM sends its own host; check the app runs on `https://<app>.<app base domain>`                     |
+| `invalid_scope`                                                                | A scope name doesn't exist, or bot and user scopes are mixed up                          | Compare with step 1; bot scopes go in `scope`, user scopes in `user_scope`                               |
+| `invalid_client_id`                                                            | `SLACK_CLIENT_ID` is wrong, or another app's                                             | Set it again from Basic Information → App Credentials                                                    |
+| `bad_client_secret`                                                            | `SLACK_CLIENT_SECRET` is wrong or was regenerated                                        | Set it again (Rotate, below)                                                                             |
+| `invalid_code`                                                                 | The code was used already or is older than ten minutes; also when `SLACK_CLIENT_ID` is another app's (Slack checks the code before the client) | Connect again and **Allow**; a second failure: compare the Client ID on Basic Information |
+| CRM: `access_denied`                                                           | The person clicked Cancel on Slack's page                                                | Connect again and **Allow**                                                                              |
+| `invalid_team_for_non_distributed_app`                                         | Installing into a workspace other than the one the app was created in                    | Create the app in that workspace, or **Manage Distribution → Activate Public Distribution**             |
+| `token_expired`, `invalid_auth`, `not_authed` from `apps.manifest.*`           | The configuration token is past 12 hours, wrong, or missing from the body                | Generate a new one (step 2b)                                                                             |
+| `invalid_manifest` with `errors[]`                                             | The manifest breaks Slack's schema                                                       | Fix what each `pointer` names; validate again                                                            |
+| CRM: "Slack refused: a permission is missing. Reconnect Slack."                | The workspace's install predates a scope                                                 | Disconnect and connect again, so Slack asks for the new scopes                                           |
+
+## Rerun, rotate, remove
+
+- **Rerun.** `configure` and `secret set` replace. Never run `apps.manifest.create` twice
+  for one app: update the existing one (step 2a's second paragraph, or
+  `apps.manifest.update`). A duplicate it made: with `SLACK_CONFIG_TOKEN`
+  and the duplicate's id exported, and only when the person said to delete
+  it (it is permanent),
+  `printf 'token=%s&app_id=%s' "$SLACK_CONFIG_TOKEN" "$SLACK_APP_ID" | curl -s -d @- https://slack.com/api/apps.manifest.delete`
+  (expect `{"ok":true}`). Path A, or a token past 12 hours: its **Basic
+  Information** page.
+- **Rotate.** Basic Information → App Credentials → **Regenerate** next to
+  **Client Secret** (Slack's FAQ still says **Change secret**). The old
+  secret works for 24 hours unless revoked manually. The person sets
+  `SLACK_CLIENT_SECRET` again at the hidden prompt (step 3a); no API
+  returns the new secret.
+- **Remove.** In Open CRM, **Settings → Connections → Disconnect Slack**.
+  Then `pnpm everyapp secret unset SLACK_CLIENT_ID SLACK_CLIENT_SECRET --json --yes`
+  (`--yes` only when the person said so). Then delete the app: the
+  `apps.manifest.delete` line above (path B, token still valid, person
+  said so) or https://api.slack.com/apps → the app → Basic Information; or
+  at least regenerate its secret: a client the Gateway no longer holds is
+  still a client.
+
+## Sources
+
+- https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests (manifest flow; configuration tokens)
+- https://docs.slack.dev/reference/app-manifest (fields and limits)
+- https://docs.slack.dev/reference/methods/apps.manifest.create, …/apps.manifest.validate, …/apps.manifest.export, …/apps.manifest.delete (permanent; `token` and `app_id`)
+- https://docs.slack.dev/tools/bolt-python/tutorial/custom-steps-workflow-builder-new/ (the create-from-manifest clicks: Create New App, From an app manifest, Next, JSON, Create)
+- https://docs.slack.dev/authentication/installing-with-oauth/ (authorize parameters, redirect rules: https, no `#`, a subdirectory matches; `invalid_scope`, `unapproved_scope`, `bad_redirect_uri`; the code expires after ten minutes)
+- https://docs.slack.dev/legacy/legacy-authentication/ (`error=access_denied` on Cancel; codes exchanged once, expire 10 minutes)
+- https://docs.slack.dev/reference/methods/oauth.v2.access/ (token-call errors)
+- https://docs.slack.dev/reference/scopes/channels.write (User only) and …/channels.manage (Bot only)
+- https://docs.slack.dev/distribution/ (own workspace only until **Activate Public Distribution**)
+- https://slack.com/help/articles/1500009181142 (no setting stops members creating internal apps) and https://slack.com/help/articles/222386767 (app approval: Workspace Owners and app managers approve requests)
+- https://docs.slack.dev/authentication/verifying-requests-from-slack/ (**Regenerate**; the old secret valid 24 hours unless revoked) and https://docs.slack.dev/faq/ (**Change secret**)
+- https://docs.slack.dev/apis/web-api/rate-limits and https://docs.slack.dev/changelog/2025/05/29/rate-limit-changes-for-non-marketplace-apps
+- https://slack.com/help/articles/27204752526611 (free plan: 10 app installs)
+- https://community.n8n.io/t/slack-oauth-redirect-uri-did-not-match-any-configured-uris-self-hosted-on-windows/271936 (the redirect error's wording, with its `Passed URI:` line)
+- https://developers.cloudflare.com/workers/observability/logs/real-time-logs/ (Workers & Pages → Overview → the Worker → Logs → Live)
+- https://api.slack.com/apps (the console; `?new_app=1` opens the create dialog)
+- Local, 2026-10-24: `packages/sdk/src/internal/capabilities.ts` (the `slack` entry: its `scopePolicy`, seven bot sets and one user set, #425), docs/capabilities.md ("OAuth clients": the scope sets table), TODO.md ("OAuth scopes (2026-10-24)", the Slack bullet)

package/skills/everyapp/setup/workers-ai.md

@@ -0,0 +1,138 @@
+# Workers AI for the Gateway
+
+Workers AI runs Meta's Llama and other open models inside the Gateway's own
+Cloudflare account, behind the Gateway's AI proxy. agentic-inbox lists it as
+`optional: true` beside a required `openrouter`, so `secret list` shows the
+token in `settings` with `set: false`, never in `unmet`: the inbox opens
+without it. Its Worker calls Workers AI (the Email Agent, the draft verifier
+and the prompt-injection scanner, on `/api/ai/workers-ai/v1/chat/completions`)
+only when built with `AI_PROVIDER=workers-ai`, which is still the build
+default until the inbox's PR #6 flips it to OpenRouter; a Worker built with
+it and no token says so in the chat. Only the token is missing: the account is
+`CLOUDFLARE_ACCOUNT_ID`, which `everyapp setup` set. At the end the person
+has one Cloudflare API token limited to Workers AI on that account, held by
+the Gateway, and a Workers AI model answering through it.
+
+## Settings
+
+| Name                    | Required                                                                                                                                               | What it holds                                                                                                                                                                                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WORKERS_AI_API_TOKEN`  | optional for agentic-inbox (`{ id: "workers-ai", optional: true }`); needed only by a Worker built with `AI_PROVIDER=workers-ai`                        | A Cloudflare API token with Workers AI Read on the Gateway's account (and Edit when made by hand: Cloudflare's REST guide asks for both on a custom token): the token string alone, one line, no `Bearer`. New user tokens start `cfut_`, account tokens `cfat_`. |
+| `CLOUDFLARE_ACCOUNT_ID` | set once by `everyapp setup`; `secret set` refuses it (`SECRET_NOT_SETTABLE` from the every-app checkout, `SECRET_NOT_DECLARED` from an app directory) | The account inference runs and bills in: `data.accountId` in `pnpm everyapp status --json`, written `<account id>` below. The token must include this account.                                                                                                   |
+
+`OPENROUTER_API_KEY` stays: the inbox's manifest requires it, and OpenSEO and Open CRM use it. This file adds a provider; it removes none.
+
+## Costs and plans
+
+As of October 2026 (Cloudflare's pricing page, updated 2026-10-20):
+
+- The Gateway's account is on Workers Paid already ($5 a month; everyapp needs it). Workers AI adds no fixed fee, and an API token is free.
+- 10,000 neurons a day are included. Beyond that, Workers Paid bills $0.011 per 1,000 neurons on the monthly invoice; Workers Free stops for the day instead (error 3036).
+- The Workers AI path's default agent model (and its draft verifier), `@cf/meta/llama-4-scout-17b-16e-instruct`: $0.27 per million input tokens, $0.85 per million output; 300 requests a minute.
+- `@cf/moonshotai/kimi-k2.6` (the inbox's optional `AGENT_MODEL`): paid-only; $0.95 in and $4.00 out per million tokens; 20 requests a minute per account and model on Workers Paid (Cloudflare's 50-a-minute tier is for calls through an AI Gateway on prepaid credits, which the Gateway doesn't use), shared by every organization on the Gateway.
+
+## Only a person can
+
+- Sign in to the Cloudflare dashboard and create the token. `cf`'s OAuth login cannot mint one: `cf auth whoami` lists no API-token scope, and the token endpoints answer it 403 code 9109. So neither `cf accounts tokens create` nor the API works from the login; it needs a token to make a token.
+- Copy the token off the screen (shown once) and type or export it in their own terminal.
+- Choose a user token (tied to their login) or an account token (a team's choice; needs API Token Provisioning or Super Administrator on the account), and whether it expires.
+
+## Before you start
+
+1. `pnpm everyapp secret list agentic-inbox --json`, from any directory: the `WORKERS_AI_API_TOKEN` entry in `data.app.setup.settings` (`names` `["WORKERS_AI_API_TOKEN"]`, `need.kind` `optional`, `holder` `gateway`, `setup` `setup/workers-ai.md`) with `"set": false` means this file applies. It is never in `unmet` (`command`, `pnpm everyapp configure agentic-inbox`, offers it after the inbox's required settings) and the inbox opens without it; what keeps the inbox closed is `OPENROUTER_API_KEY` ([openrouter.md](openrouter.md)) and its email sender ([email.md](email.md)); `data.app.setup.groups` is `[]`. `"set": true`: ask before replacing (a value can't be read back; replacing means a new token). In the older fields `data.gateway.needed` has it with `"required": false`, never in `data.gateway.missing`. `status` prints no `Guide:` line for it (only unmet settings get one): `secret list --json`, carrying the path as the entry's `setup`, is how an agent lands here (in the checkout: `packages/cli/skills/everyapp/setup/workers-ai.md`). `APP_NOT_FOUND` ("agentic-inbox isn't deployed to this Gateway yet"): deploy the app first, from its directory (the token can be set before that all the same, from anywhere).
+2. `pnpm everyapp status --json`: `data.installed` and `data.claimed` true; `data.accountId` is the account the token must include (tell the person; it is not a secret); `data.apps[]` has `"id": "agentic-inbox"` with `"status": "active"`, `"bound": true` and the same `setup`; while a required setting is missing `data.fixes` has `APP_NEEDS_SETUP` for it (severity `warning`, headline "agentic-inbox needs setup", `run` the same command). `action_required cloudflare_login` with `waiting: true` (`status` logs in by itself): show `data.url` and `data.code` to the person and keep reading; `pnpm everyapp login --json` is only for logging in ahead of time.
+3. In 1's output (or `pnpm everyapp secret list --json` from any directory), `data.gateway.names` has `CLOUDFLARE_ACCOUNT_ID`. Missing: stop and tell the person. It is written once, at install, from the account the Gateway lives in (`data.accountId` is what it should be); `secret set` refuses it and `setup` adds nothing to a Gateway that already has a version, so there is no everyapp repair today. The settings model leaves it out (an install-owned setting), so the setup gate doesn't notice it missing: the proxy's 503 (If it fails) is where it shows.
+4. Ask, together with 5 in one message, and wait for both answers before Steps (they change the steps): was the inbox's Worker deployed with `AI_PROVIDER=workers-ai` (a variable of its own deploy; `status` doesn't show it)? It decides whether the inbox needs this token at all: the manifest marks it optional, so the inbox opens either way. The build default is still `workers-ai` (the inbox's PR #6 flips it to OpenRouter; open): a Worker deployed without the variable uses this token; one deployed with `AI_PROVIDER=openrouter` never does, until its own Worker is deployed again without it, from its repository (its `cloudflare.config.ts` reads it), not from here: say so, and never redeploy the inbox from this file.
+5. Ask whether the person already holds a Cloudflare API token with Workers AI on this account (a token from another project is fine if it includes this account). Yes: skip to step 3.
+
+## Steps
+
+One step per message, and wait between them: step 1 once the two answers from Before you start are in; step 2, then "copied"; step 3, then "done". The curl line comes in Verify, after that.
+
+1. **You:** Say which token to make. A user token (My Profile) is the quick path for a solo operator; an account token keeps working after that person leaves and is the better fit for a team. Both reach Workers AI the same way: the Gateway sends either as a Bearer token to `api.cloudflare.com/client/v4/accounts/<account id>/ai/v1/…`, and Cloudflare's compatibility matrix lists Workers AI as supporting account tokens (not tried live here). Give them `data.accountId` to check against the token's account resources.
+
+2. **Person:** Create the token. Done when the screen shows the token once, with a copy button and a `curl … /user/tokens/verify` test under it. Wait for "copied".
+   - Prefilled user token: open https://dash.cloudflare.com/?to=/:account/ai/workers-ai (the Workers AI page; pick the Gateway's account if asked), select **Use REST API**, then **Create a Workers AI API Token**. A token form opens prefilled (Cloudflare's guide says it grants Workers AI Read on this account, which is what the `/ai/*` endpoints need; one permission row is expected): check that **Account Resources** names the Gateway's account (`data.accountId`), leave **TTL (time to live)** empty unless they want an expiry (the Gateway stops the day it expires), select **Create API Token**, then **Copy API Token**.
+   - Custom user token: https://dash.cloudflare.com/profile/api-tokens, **Create Token**, the custom token at the bottom (label unverified), name it `every-app-gateway workers-ai`, permissions **Account** | **Workers AI** | **Read** and a second row **Account** | **Workers AI** | **Edit** (Cloudflare's REST guide asks for both on a token made by hand), account resources: Include, the Gateway's account (`data.accountId`), no client IP filter (the Gateway's egress addresses vary), **Continue to summary**, **Create Token**.
+   - Account token: in the dashboard pick the Gateway's account, **Manage account** > **Account API tokens**, **Create Token**, the same name and permissions, optional expiration, **Continue to summary**, **Create Token**.
+
+3. **Person:** Hand it to the Gateway (README's third way, the hidden read, in their own terminal, in the `every-app` folder; bash or zsh):
+   ```sh
+   read -rs WORKERS_AI_API_TOKEN; export WORKERS_AI_API_TOKEN
+   pnpm everyapp secret set WORKERS_AI_API_TOKEN --from-env WORKERS_AI_API_TOKEN --json
+   ```
+   After the first line the terminal shows nothing, not even a prompt: paste the token, press Enter, then run the second line. `SECRET_EMPTY` means the paste didn't land: redo the first line in the same terminal. fish: `read -s -x WORKERS_AI_API_TOKEN` (it does show `read> `), then the same `pnpm everyapp secret set … --from-env …` line; `set -e WORKERS_AI_API_TOKEN` clears it afterwards.
+   The last line is `"type": "done"`; the change is live at once (one new Gateway version, no deploy). `pnpm everyapp configure agentic-inbox --from-env --json` sets it from the same variable (and every other unset setting of the inbox whose variable is exported; its `done` event's `data.set` names them). Keep the variable until the smoke check below is done, then `unset WORKERS_AI_API_TOKEN`. Without the smoke check, README's first way is simpler: in a second terminal, `pnpm everyapp configure agentic-inbox` (it asks for the token after the inbox's required settings, as an optional one: Yes to `Set the N optional settings too?` (`Set the optional setting too?` for one), Enter skips the others; once the inbox is ready its menu lists `WORKERS_AI_API_TOKEN`) or `pnpm everyapp secret set WORKERS_AI_API_TOKEN` for just this one; paste at the hidden prompt. Wait for "done".
+
+4. **You:** Run the Verify section. The person runs its curl line in the terminal that still has the variable.
+
+## Verify
+
+1. `pnpm everyapp secret list agentic-inbox --json`, from anywhere: the `WORKERS_AI_API_TOKEN` entry in `data.app.setup.settings` has `"set": true` (it was never in `data.app.setup.unmet`: optional); `data.app.setup.ready` doesn't depend on it (`OPENROUTER_API_KEY`, required by the same manifest, and its email sender do: until then `command` and `data.next` name what is left). In the older fields, its `data.gateway.needed` entry has `"set": true`, `data.gateway.missing` never listed it, and `data.gateway.names` does (for an inbox not deployed yet, the root `pnpm everyapp secret list --json` shows `data.gateway.names` and that is the check). Then `pnpm everyapp status --json`: the `agentic-inbox` entry's `setup.ready` is true and `data.fixes` has no `APP_NEEDS_SETUP` for it, once everything required is set.
+2. Smoke check, in the person's terminal with `WORKERS_AI_API_TOKEN` exported. The header goes in on stdin (`-H @-`) so the token never sits in curl's argument list, which the process list shows. The token reaches Workers AI on the Gateway's account (a few neurons):
+   ```sh
+   printf 'Authorization: Bearer %s\n' "$WORKERS_AI_API_TOKEN" | curl -s -H @- -H "Content-Type: application/json" https://api.cloudflare.com/client/v4/accounts/<account id>/ai/v1/chat/completions -d '{"model":"@cf/meta/llama-4-scout-17b-16e-instruct","messages":[{"role":"user","content":"Say ok."}],"max_tokens":5}'
+   ```
+   expects a JSON body with `choices[0].message.content`. Any `"success":false` body is read in If it fails; a 401 starts with the verify curl there. Then `unset WORKERS_AI_API_TOKEN`.
+3. The app, only when the inbox's Worker was built with `AI_PROVIDER=workers-ai` (the build default until the inbox's PR #6; Before you start, 4); one built with `AI_PROVIDER=openrouter` never sends this token and the curl line above is the whole proof. Either way the inbox opens only once every required setting is set (Verify 1): a browser sent to `https://<gateway host>/?setup=agentic-inbox` means something still isn't. Open `https://agentic-inbox.<app base domain>/`, open a mailbox, **Show agent panel** (the header button), type in "Ask your email agent..." and send. A reply streams in, and the Gateway's `ai.proxy.usage` line (step 4) says `"provider":"workers-ai"`. A missing token shows up in the panel as "AI isn't set up on this gateway yet, so I can't help with this inbox. An admin sets WORKERS_AI_API_TOKEN with `pnpm everyapp secret set WORKERS_AI_API_TOKEN`."; any other refusal as the Gateway's message.
+4. The Gateway's logs, when a refusal isn't clear: `cf` has no terminal tail (`cf workers` lists none; `cf o11y telemetry live-tail` only prepares a websocket, not tried here; `cf o11y telemetry query` is the raw query API). Cloudflare's CLI for it is `npx wrangler tail every-app-gateway --format json` (after its own `wrangler login`; wrangler isn't in this checkout). Dashboard, README's path: https://dash.cloudflare.com/?to=/:account/workers-and-pages, then **Workers & Pages** → `every-app-gateway` → **Observability** (**Logs** on older accounts) → **Live**. The proxy writes one JSON line per call: `"evt":"ai.proxy.usage"` with `provider`, `model`, `status` and `usage`; `"evt":"ai.proxy.upstream_failed"` with the message when the request to Cloudflare failed. The Gateway's config turns these logs on; Workers Paid keeps 7 days.
+
+## If it fails
+
+A 401 from the chat call: first, in the same terminal, Cloudflare's verify route says whether the string itself is good. A user token (`cfut_`):
+
+```sh
+printf 'Authorization: Bearer %s\n' "$WORKERS_AI_API_TOKEN" | curl -s -H @- https://api.cloudflare.com/client/v4/user/tokens/verify
+```
+
+An account token (`cfat_`): the same header on `https://api.cloudflare.com/client/v4/accounts/<account id>/tokens/verify`; on the user route it answers 401 code 1000 "Invalid API Token", like any token that route doesn't know. `"success":true` with `"status":"active"`: the string is good, and the rows for code 10000 and 9109 say what is (the permission or the account). 401 code 1000 on its own route: the string (its row).
+
+| Error or symptom                                                                                                        | Meaning                                                                                                                                                                                 | What to do                                                                                                                                      |
+| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| a browser opening the inbox is sent to `https://<gateway host>/?setup=agentic-inbox`; any other request gets 503 with the body `{"error":"app_needs_setup","app":"agentic-inbox"}` | the Gateway's setup gate: a required setting of the inbox is still unset (`OPENROUTER_API_KEY` or its email sender; this token is optional and never closes the inbox)   | `data.app.setup.command`, `pnpm everyapp configure agentic-inbox`, then Verify 1                                                                |
+| 503 `ai_provider_not_configured`, "needs WORKERS_AI_API_TOKEN and CLOUDFLARE_ACCOUNT_ID"                                | the Gateway holds no token (the inbox opens anyway: its manifest marks the provider optional; a Worker built with `AI_PROVIDER=workers-ai` shows it in the chat as "AI isn't set up on this gateway yet, so I can't help with this inbox. An admin sets WORKERS_AI_API_TOKEN with `pnpm everyapp secret set WORKERS_AI_API_TOKEN`."), or no account id (which the gate doesn't check) | `secret list --json`; set the token; `CLOUDFLARE_ACCOUNT_ID` missing: no everyapp repair today, tell the person (Before you start, 3)           |
+| `provider_not_allowed`                                                                                                  | the app's manifest doesn't list `workers-ai` under `providers`                                                                                                                          | agentic-inbox lists it; another app adds it to `everyapp.config.ts` and deploys                                                                 |
+| `model_not_allowed`                                                                                                     | a model id outside the app's `ai.models`                                                                                                                                                | use one from the manifest, or add it and deploy                                                                                                 |
+| `ai_route_not_allowed`                                                                                                  | a path other than `/v1/chat/completions`, `/v1/embeddings`, `/v1/responses` (the native run route is closed)                                                                            | call the OpenAI-compatible routes                                                                                                               |
+| 502 `ai_upstream_failed`                                                                                                | the request to `api.cloudflare.com` failed before an answer                                                                                                                             | retry; the Gateway log line `ai.proxy.upstream_failed` has the message                                                                          |
+| 401, code 1000 "Invalid API Token" (the verify routes)                                                                  | the string is wrong, expired, rolled or deleted; or a `cfat_` token on the user route                                                                                                   | verify a `cfat_` token on `/accounts/<account id>/tokens/verify`; otherwise make a new token and set it again                                   |
+| 401, code 10000 "Authentication error" (the `/ai/v1` route: curl's chat completion, or passed through by the Gateway)   | token invalid, expired, rolled, deleted, IP-filtered, or without Workers AI on this account; or `$WORKERS_AI_API_TOKEN` empty in that terminal                                          | the verify curl above; make a new token with Workers AI Read including `data.accountId`; set it again                                          |
+| 403, code 9109 "Unauthorized to access requested resource" or "Invalid access token"                                    | the token's resources don't include this account                                                                                                                                        | a token whose account resources include the Gateway's account                                                                                   |
+| 403, code 5035 "This model requires a Workers Paid plan."                                                               | a paid-only model (`kimi-k2.6`) on an account without Workers Paid                                                                                                                      | the Gateway's account must be on Workers Paid (everyapp needs it anyway)                                                                        |
+| 429, code 3036 "You have used up your daily free allocation of 10,000 neurons."                                         | Workers Free's daily cap                                                                                                                                                                | Workers Paid; it doesn't occur there                                                                                                            |
+| 429, code 3040 "Capacity temporarily exceeded", or a bare 429                                                           | Cloudflare capacity, or a rate limit (kimi: 20 a minute per account; the limit's own code unverified)                                                                                   | retry later; on kimi expect it, or use `@cf/meta/llama-4-scout-17b-16e-instruct`                                                                |
+| 400 code 5007 "No such model", or 404 code 3042 "The model name is invalid"                                             | the model id isn't in the catalog                                                                                                                                                       | `cf ai models list --search llama` (read-only) for a current id; change the app's manifest and code                                             |
+| `SECRET_EMPTY`                                                                                                          | `$WORKERS_AI_API_TOKEN` is empty in the terminal that ran `secret set`                                                                                                                  | redo the `read -rs …; export …` line in that same terminal, then rerun                                                                          |
+| `SECRET_VALUE_REQUIRED`                                                                                                 | nothing was piped and there is no terminal                                                                                                                                              | one of README's three ways                                                                                                                      |
+| `SECRET_VALUE_REQUIRED` from `pnpm everyapp configure agentic-inbox --json`                                             | nothing was piped (with `--from-env`, stdin isn't read), no variable of a missing name was found, and there is no terminal; the message names what the inbox still needs (this token is optional, so never among them) | the person's terminal (step 3), `NAME=value` lines on stdin, or the hidden read then its `data.rerun`, `pnpm everyapp configure agentic-inbox --from-env` |
+| `SECRET_SEVERAL_NAMES`                                                                                                  | `--from-env` or a pipe with several names                                                                                                                                               | one name per call                                                                                                                               |
+| `SECRET_NOT_SETTABLE` (from the every-app checkout) or `SECRET_NOT_DECLARED` (from an app directory)                    | the name is one setup writes (`CLOUDFLARE_ACCOUNT_ID`)                                                                                                                                  | set only `WORKERS_AI_API_TOKEN`; never add it to the manifest's `secrets`; a wrong account id has no everyapp repair today (tell the person)     |
+| 400, code 6003 "Invalid request headers" / 6111 "Invalid format for Authorization header" (the verify routes)           | `$WORKERS_AI_API_TOKEN` is empty in that terminal (not exported, or a new terminal); the chat route shows the same as 401 code 10000                                                      | redo step 3 in one terminal, in order; an HTML page instead means a mistyped URL                                                                |
+
+## Rerun, rotate, remove
+
+- Rerun: every step is safe to repeat. `configure` and `secret set` replace the value in one new Gateway version; a second token on Cloudflare's side is harmless until you delete it. Interrupted or back later: start at Verify and continue at the first step that isn't done.
+- Rotate: on the token's row in the dashboard (user tokens at https://dash.cloudflare.com/profile/api-tokens, account tokens under **Manage account** > **Account API tokens**) the three-dot menu, **Roll**, **Confirm**. The new secret keeps the permissions and the old one stops at once, so run step 3 again straight away. The API's roll: `cf user tokens roll <token-id>` for a user token, `cf accounts tokens roll <token-id>` for an account token; both need an API token with the matching API Tokens Edit permission, not the login.
+- Remove: `pnpm everyapp secret unset WORKERS_AI_API_TOKEN --json` (add `--yes` only when the person said so). The inbox keeps opening (its manifest marks the provider optional); a Worker built with `AI_PROVIDER=workers-ai` then loses its agent, verifier and scanner to `ai_provider_not_configured`, one built with `AI_PROVIDER=openrouter` is unaffected. Then delete the token in the same row menu (label unverified): a token the Gateway no longer holds is still a token.
+
+## Sources
+
+Verified 2026-10-23:
+
+- https://developers.cloudflare.com/workers-ai/get-started/rest-api/ (Use REST API, Create a Workers AI API Token; the prefilled token grants Workers AI Read, a token made by hand needs Read and Edit)
+- https://developers.cloudflare.com/fundamentals/api/get-started/create-token/ (dashboard flow, TTL, verify command, `cfut_`)
+- https://developers.cloudflare.com/fundamentals/api/get-started/account-owned-tokens/ (Manage account > Account API tokens, roles, Workers AI supported, `cfat_`)
+- https://developers.cloudflare.com/fundamentals/api/how-to/create-via-api/ (token creation needs a token with API Tokens Edit)
+- https://developers.cloudflare.com/fundamentals/api/how-to/roll-token/ (Roll, Confirm)
+- https://developers.cloudflare.com/fundamentals/api/reference/permissions/ (Workers AI Read, Workers AI Edit)
+- https://developers.cloudflare.com/api/resources/user/subresources/tokens/methods/verify/ and https://developers.cloudflare.com/api/resources/accounts/subresources/tokens/methods/verify/; probed with a bogus token and an empty header: both verify routes answer 401 code 1000 and 400 code 6003/6111, `/ai/v1/chat/completions` 401 code 10000 for either
+- https://developers.cloudflare.com/workers-ai/configuration/open-ai-compatibility/ (`/accounts/<account id>/ai/v1/chat/completions`, embeddings, responses for gpt-oss only)
+- https://developers.cloudflare.com/workers-ai/platform/pricing/ (neurons, per-model prices, paid-only list)
+- https://developers.cloudflare.com/workers-ai/platform/limits/ (300 a minute; 20 for paid-only models, 50 only through an AI Gateway on prepaid credits with Unified billing)
+- https://developers.cloudflare.com/workers-ai/platform/errors/ (3036, 3040, 3042, 5007, 5035)
+- https://developers.cloudflare.com/ai-gateway/usage/rest-api/ (`/accounts/<account id>/ai/*` needs Workers AI Read; code 10000 without it)
+- https://developers.cloudflare.com/workers-ai/models/llama-4-scout-17b-16e-instruct/ and https://developers.cloudflare.com/workers-ai/models/kimi-k2.6/
+- the live catalog via `cf ai models list` (`--search`, from its `--help`)
+- https://developers.cloudflare.com/workers/observability/logs/real-time-logs/ (`npx wrangler tail`, no storage) and https://developers.cloudflare.com/workers/observability/logs/workers-logs/ (Observability, retention); https://developers.cloudflare.com/workers/wrangler/commands/workers/ (`wrangler tail [WORKER]`, `--format json`)
+- `cf` 1.0.0-beta.14: `cf workers --help`, `cf o11y telemetry live-tail --help`, `cf user tokens --help`, `cf accounts tokens --help`
+- In this repository: `apps/every-app-gateway/src/server/ai-proxy.ts`, `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/sdk/src/internal/aiProviders.ts` (`setup/workers-ai.md`; `CLOUDFLARE_ACCOUNT_ID` under `alsoNeeds`), `packages/sdk/src/internal/appSettings.ts` (`AppSetup`: `unmet`, `settings`, `groups`, `command`; `needOf`: a plain provider id is required, `anyOf` makes a group; `providerNames` leaves install-owned settings out), `packages/sdk/src/internal/gatewaySettings.ts`, `packages/cli/src/lib/gateway/apply.ts` (install-owned secrets go with the first deploy only), `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 optional settings' prompts and the menu, `--from-env`), `packages/cli/src/lib/app/settings.ts` (the `Guide:` line), `packages/cli/src/commands/status/problems.ts` (`APP_NEEDS_SETUP`), `packages/cli/src/lib/secretValue.ts`, `docs/capabilities.md`; in agentic-inbox: `everyapp.config.ts` (`openrouter` required, `workers-ai` `optional: true`; no any-of group), `cloudflare.config.ts` (`AI_PROVIDER` defaults to `workers-ai` until its PR #6) and `workers/everyapp/gateway.ts` (each provider's models)

package/bin/__everyapp_bash_complete.js

@@ -1,12 +0,0 @@
-#!/usr/bin/env node
-// Committed launcher so package managers can link the bin at install time,
-// before dist/ exists (fresh CI checkouts install with --ignore-scripts).
-import("../dist/bash-complete.js").catch((error) => {
-  if (error?.code === "ERR_MODULE_NOT_FOUND") {
-    console.error(
-      "everyapp CLI is not built. In the monorepo, run: pnpm -C packages/cli build",
-    );
-    process.exit(1);
-  }
-  throw error;
-});

package/dist/bash-complete.js

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-import{a as o,b as s}from"./chunk-POSDLD3G.js";import"./chunk-RB5D2R45.js";import"./chunk-YJ2DKIZS.js";import{proposeCompletions as r}from"@stricli/core";var t=process.argv.slice(3);process.env.COMP_LINE?.endsWith(" ")&&t.push("");await r(s,t,o(process));try{for(let{completion:p}of await r(s,t,o(process)))process.stdout.write(`${p}
-`)}catch{}

package/dist/chunk-7BOQJFI5.js

@@ -1,8 +0,0 @@
-import{c as l,d as m,e as f,m as g,n as w,o as y}from"./chunk-DLGPLHBH.js";import{c as d}from"./chunk-U4LIQ5VR.js";import{c as h,d as k}from"./chunk-WO3NE7ZU.js";import I from"enquirer";import p from"chalk";async function x(){if(process.env.CLOUDFLARE_API_TOKEN){let r=process.env.CLOUDFLARE_ACCOUNT_ID;return r?f(r):(console.log(p.yellow(`
-CLOUDFLARE_ACCOUNT_ID is required when using CLOUDFLARE_API_TOKEN
-`)),d(1))}let e=await g(),{account:t,otherAccounts:o}=await y(e);return w(t,o),{id:t.account.id,name:t.account.name}}async function C(e="this",t=!1){let o=await x();if(process.env.CLOUDFLARE_API_TOKEN&&(console.log(p.dim(`  ${o.name} (${o.id})`)),console.log()),t)return console.log(p.dim(`Skipping deployment confirmation due to -y flag.
-`)),!0;let{confirm:r}=await I.prompt({type:"confirm",name:"confirm",message:`Do you want to deploy ${e} to ${o.name}?`,initial:!1});return r}function v({domain:e,accountId:t,mode:o,hostname:r}){let n=t?`https://dash.cloudflare.com/${t}/${e}/dns/records`:`https://dash.cloudflare.com -> ${e} -> DNS`,i=r??`todo.${e}`,s=o==="app-blocking"?[`Each app you deploy will live at [app].${e} - this app at`,`${i} - but that address does not resolve yet. To support`,"this, you must add the DNS record below:"]:[`Each app you deploy will live at [app].${e} - for example`,`todo.${e}. To support this, you must add the DNS record`,"below (the login this CLI uses isn't allowed to add it for you):"],a=o==="app-blocking"?["After DNS propagates, re-run everyapp app deploy.","If you know DNS is ready and this check is blocked locally, re-run with --skip-dns-check."]:["Continuing the deploy - once you add that record, apps at",`*.${e} will work properly. You only do this once.`];return["",...s,"",`  Add record at: ${n}`,"    Type:    CNAME","    Name:    *",`    Target:  ${e}`,"    Proxy:   ON (orange cloud)","","Here are the docs explaining how this works:","  https://developers.cloudflare.com/workers/configuration/routing/routes/","  https://github.com/cloudflare/workers-sdk/issues/5568","",...a,""].join(`
-`)}import c from"chalk";async function u(e,t){let o=await m();if(t)return{accountId:o,workerName:t};let r=await k(e),n=h(r.id);return{accountId:o,workerName:n}}async function N(e){return await l(`/accounts/${e.accountId}/workers/scripts/${e.workerName}/secrets`)}async function W({cwd:e,workerName:t}){let o=await u(e,t);return(await N(o)).map(n=>n.name)}async function F({secretName:e,cwd:t,workerName:o,verbose:r=!1}){r&&console.log(c.dim(`   Checking secret: ${e}`));let n=await u(t,o),s=(await N(n)).some(a=>a.name===e);return s&&r&&console.log(c.dim(`   Secret already exists
-`)),s}async function R({secretName:e,secretValue:t,cwd:o,workerName:r,verbose:n=!1,description:i}){n&&i&&console.log(c.dim(`   ${i}
-`));let s=await u(o,r);await l(`/accounts/${s.accountId}/workers/scripts/${s.workerName}/secrets`,{method:"PUT",body:JSON.stringify({name:e,text:t,type:"secret_text"})}),n&&console.log(c.green(`Created secret: ${e}
-`))}export{C as a,W as b,F as c,R as d,v as e};

package/dist/chunk-7YVJFS4A.js

@@ -1 +0,0 @@
-import{b as i,d,g as D}from"./chunk-DLGPLHBH.js";import{f}from"./chunk-WO3NE7ZU.js";import{execa as A}from"execa";async function E(s){let{config:t}=await f(s);if(!t.d1_databases||t.d1_databases.length===0)throw new Error("No D1 databases found in everyapp.config.ts. Please add a D1 resource declaration.");let a=t.d1_databases[0];if(!a)throw new Error("No D1 database configuration found.");let e=a.database_name;if(!e)throw new Error("No database_name found in generated D1 database configuration.");let[n,r]=await Promise.all([d(),i()]),o=(await D(n)).find(u=>u.name===e);if(!o)throw new Error(`Database "${e}" not found in your Cloudflare account. Have you run deployment to create the database?`);return{CLOUDFLARE_ACCOUNT_ID:n,CLOUDFLARE_DATABASE_ID:o.uuid,CLOUDFLARE_API_TOKEN:r}}async function O(s,t,a){let{cwd:e,env:n={},verbose:r=!1}=a,c=a.d1DatabaseId?{CLOUDFLARE_ACCOUNT_ID:await d(),CLOUDFLARE_DATABASE_ID:a.d1DatabaseId,CLOUDFLARE_API_TOKEN:await i()}:await E(e),o={cwd:e,stdio:r?"inherit":"pipe",env:{...process.env,...n,...c}};await A(s,t,o)}export{E as a,O as b};

package/dist/chunk-BIXKPCDH.js

@@ -1,2 +0,0 @@
-import{b as w,c as y}from"./chunk-VEYSNPDH.js";var h=15e3,c="INTERNAL_APIS_DISABLED",a=class extends Error{status;code;constructor({message:e,status:r,code:o}){super(e),this.name="GatewayApiError",this.status=r,this.code=o}},i=class extends a{constructor(e="OUTDATED_GATEWAY"){super({message:e,status:404}),this.name="OutdatedGatewayError"}},u=class extends a{constructor(e="GATEWAY_INTERNAL_APIS_DISABLED"){super({message:e,status:404,code:c}),this.name="GatewayInternalApisDisabledError"}},p=class extends a{constructor(e,r="GATEWAY_INTERNAL_AUTH"){super({message:r,status:e}),this.name="GatewayAuthError"}};function A(s){return s instanceof i}function f(s){return s instanceof u}function G(s){return s instanceof p}var l=class{gatewayUrl;getAuthToken;constructor({gatewayUrl:e,getAuthToken:r}){this.gatewayUrl=e.replace(/\/+$/,""),this.getAuthToken=r??(()=>y(this.gatewayUrl))}getIdentityKeys(){return this.request("/api/deploy/identity-keys",{method:"GET"})}registerApp(e){return this.request("/api/deploy/register",{method:"POST",body:e})}async hasOwner(){let e=await this.request("/api/admin/has-owner",{method:"GET",auth:!1});if(typeof e.hasOwner!="boolean")throw new a({message:"Gateway returned an invalid owner response",status:200});return e.hasOwner}whoami(){return this.request("/api/deploy/whoami",{method:"GET"})}async request(e,r){let o={"content-type":"application/json"};if(r.auth!==!1){let g=await this.getAuthToken();o.authorization=`Bearer ${g}`}let t=await fetch(`${this.gatewayUrl}${e}`,{method:r.method,signal:AbortSignal.timeout(h),headers:o,body:r.body?JSON.stringify(r.body):void 0}),d=await t.text(),n=null;if(d.trim())try{n=JSON.parse(d)}catch{throw t.ok?new a({message:"Gateway returned an invalid JSON response",status:t.status}):new a({message:`Gateway request failed (${t.status})`,status:t.status})}if(t.status===404)throw n?.code===c?new u:new i;if(!t.ok)throw t.status===401||t.status===403?new p(t.status,[n?.error||"Gateway deploy-token authorization failed.",w(this.gatewayUrl)].join(`
-`)):new a({message:n?.error||`Gateway request failed (${t.status})`,status:t.status,code:n?.code});return n??{}}};export{A as a,f as b,G as c,l as d};