everyapp 0.2.2 → 0.3.0-rc.2

package/skills/build-every-app/patterns.md

@@ -0,0 +1,140 @@
+# Example patterns
+
+How the apps on Every App do each thing, and the file to copy from. `starter/` is what `pnpm everyapp create` copies (in the Every App checkout); in an app `everyapp create` made, a `starter/` path is that path in the app. The four apps are open, at `https://github.com/every-app/<name>`, cited by their repository names: `open-crm/` (OpenCRM), `open-analytics/` (OpenAnalytics), `open-seo/` (OpenSEO) and `agentic-inbox/` (Agentic Inbox); a path is relative to that repository's root. Read a file before copying from it: each is short where it matters, and its comments say why. When a cited file is out of reach, the "What it is" and "Copy this" columns are the pattern; start from the starter's file when the row names one.
+
+## Identity
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| Identity in a server function | `requireEveryAppUser(getRequest(), env)` in a TanStack Start middleware; every server function lists it and reads `context.user` | `starter/src/middleware/ensureUser.ts`, `starter/src/serverFunctions/todos.ts` | `.middleware([ensureUserMiddleware])` on every server function, and `context.user.id` as the first argument of every query |
+| Identity resolved once, with the organization | `getEveryAppUser()` over the request's headers; the deploy's `EVERY_APP_ORG_ID` pin; the role from the token, never from a member row; one context `{ userId, userEmail, organizationId, role }` every repository filters by | `open-crm/src/middleware/ensure-user/everyApp.ts`, `open-crm/src/middleware/ensureUser.ts`; the same shape in `open-seo/src/middleware/ensure-user/everyApp.ts` | `resolveEveryAppUserContext(user)`: the pin check, `ROLES`, and that a server function accepts only a credential holding every scope (`hasScope(user, "*")`) |
+| Identity at the Worker entry | `everyApp()`'s handler gets `user` as its fourth argument; the app refuses another organization, keeps the user in a `WeakMap` by request, and its routes read it from there | `agentic-inbox/workers/app.ts`, `agentic-inbox/workers/everyapp/identity.ts` | `requireOrganization(env, user)` before routing; `roleOf()`; the `requireAdmin` middleware on the routes only owners and admins may use |
+| Identity mirrored into the app's tables | A `Viewer` from `getEveryAppUser()`; the person, their organization and their membership are mirrored into rows so other rows can join on them, and access still comes from the signed identity alone | `open-analytics/src/lib/edge/auth/viewer.ts` | `mirror()` writes at most once an hour per person and is never consulted for access |
+| Identity in a tool handler | The handler's second argument carries the verified caller (`user.id`, `user.orgId`, `user.orgRole`, `user.scopes`); the starter passes `user.id` to the same queries the page uses | `starter/src/tools.ts`; `open-crm/src/server/everyapp/crm-tool.ts` | `crmTool()`: one wrapper that resolves the context, scopes the handler to the organization, and turns an `AppError` into a `ToolError` |
+| Identity on a public route | A public route is open to anyone, so it never assumes a member: `getEveryAppUser(request, env)` is the member when the Gateway signed one in (a member's session still travels on a public route) and `null` otherwise. The four apps' public routes read no identity at all: OpenAnalytics' collector checks the token its tracker was issued, OpenCRM's tracker takes the site from the id in the URL | `open-analytics/src/lib/edge/collector/collect.ts`, `open-analytics/src/lib/hono/routes/collect.ts`; `open-crm/src/server/features/tracking/trackingRoutes.ts` | A public route exists only when the app needs one (a webhook, a collector, an OAuth callback); it checks what it must itself and answers nothing that is anyone's without that check |
+| Organization-wide rows | Sharing by design: every table keys on the organization in the signed identity, every member sees the organization's rows, owners and admins manage. OpenCRM hangs every table off `organization_id`; OpenAnalytics' `teamId` is the organization; Agentic Inbox is one organization per deploy, every mailbox shared | `open-crm/docs/maintainers/every-app.md`, `open-crm/src/middleware/ensure-user/everyApp.ts`; `open-analytics/src/lib/edge/auth/viewer.ts`; `agentic-inbox/workers/everyapp/identity.ts` | The rule in words: authorization reads the organization and the role from the token on every request, never from a row the app wrote |
+| Roles from the Gateway | `owner`, `admin` and `member` from `user.orgRole`; anything else is a member | `open-crm/src/server/auth/org-gate.ts`; `agentic-inbox/workers/everyapp/identity.ts` | `requireOrgPermission(context, permissions)` throwing `FORBIDDEN`; `isAdmin(user)` |
+| The way back | A link to the Gateway. The starter's `launcher` is the identity issuer (`EVERYAPP_IDENTITY_ISSUER`, the Gateway's URL), or the dev host one label up under `everyapp dev`; the apps read `GATEWAY_URL` (set by the deploy, absent under `everyapp dev`) first, then the issuer. Where: the starter's header ("All apps"), OpenCRM's and OpenSEO's sidebar footer, Agentic Inbox's signed-in line ("Back to Every App"). The convention the identity page states for a new app: the first sidebar row, muted "‹ Every App", aria-label "Back to Every App" | `starter/src/serverFunctions/home.ts`, `starter/src/routes/index.tsx`; `open-crm/src/client/components/Sidebar.tsx`, `open-crm/src/serverFunctions/everyApp.ts`; `open-seo/src/client/components/Sidebar.tsx`; `agentic-inbox/app/routes/home.tsx`, `agentic-inbox/workers/everyapp/identity.ts` | `launcher` (the starter, dev-aware); `getEveryAppGatewayUrl()`: `GATEWAY_URL`, then `EVERYAPP_IDENTITY_ISSUER` |
+
+## Public routes with their own checks
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| A public route with its own token | OpenAnalytics' tracker: `/script.js` (GET) issues a signed collect token (an HMAC over the site id and the client's address, 12 hours, derived from `MAIN_SECRET`); `/collect` (POST) verifies it, then runs the site's blocking rules and bot checks before anything is ingested | `open-analytics/everyapp.config.ts` (`public`), `open-analytics/src/lib/edge/collector/script-endpoint.ts`, `open-analytics/src/lib/edge/auth/collect-token.ts`, `open-analytics/src/lib/edge/collector/collect.ts`, `open-analytics/src/lib/hono/routes/collect.ts` | `verifyCollectToken()` before anything is stored; the tracker posts `text/plain`, so the browser sends no preflight and `OPTIONS` stays private |
+| A public tracker for another website | OpenCRM's `/t/*`: the loader, a per-site tracker with its config baked in, and a collector that always answers 204; the organization comes from the site id, the client's address only counts requests | `open-crm/src/server/features/tracking/trackingRoutes.ts`, `open-crm/everyapp.config.ts` | The route sets its own CORS and resource-policy headers; `withinAddressLimit()` before any work |
+| A public route armed by a secret | An operator endpoint that answers 404 until `ERASURE_SECRET` is set, and then only to a request signed with it in the last five minutes | `open-crm/src/server/features/erasure/erasureRoute.ts` | Compare signatures in constant time; keep the secret `optional` and unset it after use |
+| Share links and assets | Public pages, their data and the built assets they load, each listed with its method | `open-analytics/everyapp.config.ts` | `/share/**`, `/api/public/share/**`, `/assets/**`: list the assets a public page loads, or it renders bare |
+| No public routes | `public: []` with a comment saying why nothing is open; the Gateway's own tool calls carry their own tokens | `open-seo/everyapp.config.ts`, `agentic-inbox/everyapp.config.ts` | Say why in the manifest comment |
+
+## The manifest, field by field
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| `id`, `name`, `description`, `icon` | The id names the hostname and the Worker; the description is the app library's one line; the icon an SVG the app serves | `open-crm/everyapp.config.ts` | `icon: "/everyapp-icon.svg"` |
+| `resources.d1` | The database, bound as `env.DB`; the deploy creates it | `starter/everyapp.config.ts` | `resources: { d1: ["DB"] }` |
+| `resources.kv` | Per-site settings read on the hot path | `open-analytics/everyapp.config.ts` (`SITE_SETTINGS_KV`), `open-seo/everyapp.config.ts` (`KV`) | One namespace per purpose, named for it |
+| `resources.durableObjects` | `{ name, className }`, the class exported from the Worker entry; `worker` when a helper Worker defines it | `agentic-inbox/everyapp.config.ts` (`MAILBOX`, `EMAIL_AGENT`), `open-crm/everyapp.config.ts` (`CRM_AGENT`), `open-seo/everyapp.config.ts` (`AUDIT_SCRATCHPAD` on the `audit` Worker) | The comment above each: what one instance is (a mailbox, a research session) |
+| `resources.workflows` and `workers` | Workflows by binding and class, one of them on a helper Worker; the helper declared with its service binding | `open-seo/everyapp.config.ts` | `workers: [{ name: "audit", binding: "AUDIT_ENGINE" }]` with `SITE_AUDIT_WORKFLOW` on it |
+| An R2 bucket | Added in `cloudflare.config.ts` beside the manifest's bindings, named after the Worker (`bindings.r2({ name: worker.name })`); `resources.r2` in the manifest does the same. The deploy creates the bucket; an account that never enabled R2 stops with `R2_NOT_ENABLED` until the person enables it once in the Cloudflare dashboard | `open-crm/cloudflare.config.ts`, `open-seo/cloudflare.config.ts`, `agentic-inbox/cloudflare.config.ts` | Spread `worker.env` and add to it; import nothing the Worker imports there |
+| `migrations` with drizzle | `{ engine: "drizzle", dir, config, binding }`, and a drizzle config that opens the local D1 `pnpm dev` serves | `open-crm/everyapp.config.ts`, `open-crm/drizzle/sqlite.config.ts`, `open-crm/drizzle/sqlite/0000_init.sql`; the starter's default is `starter/drizzle.config.ts` with no `migrations` field | `localD1Path()` from `@every-app/sdk/cloudflare` for drizzle-kit studio |
+| `migrations` with hand-written SQL | `{ engine: "d1-sql", dir: "migrations", binding: "DB" }` and plain SQL files, one `;`-terminated statement after another | `open-analytics/everyapp.config.ts`, `open-analytics/migrations/0001_baseline.sql` | For an app whose schema drizzle doesn't own |
+| `public` | `{ path, methods }` per route, `GET` by default; a route is listed only when something other than a signed-in member must reach it: a webhook, a collector, an OAuth callback. The starter lists none (its manifest's comment shows a webhook); OpenAnalytics opens its tracker, collector and share pages, OpenCRM its tracker; OpenSEO and Agentic Inbox nothing | `starter/everyapp.config.ts` (the comment), `open-analytics/everyapp.config.ts`, `open-crm/everyapp.config.ts` | Comment each route with why it is open; `/mcp` can't be one |
+| `providers` with `why` | The AI provider the Gateway calls for the app; required unless `optional: true` | `open-crm/everyapp.config.ts` (`openrouter`), `agentic-inbox/everyapp.config.ts` (`openrouter` required, `workers-ai` optional) | One sentence for whoever sets the key |
+| `capabilities`: an API key | `dataforseo` and `context` with `access: "read"` and a `why`; `optional` where a feature can say what is missing | `open-seo/everyapp.config.ts` | `context: { access: "read", optional: true, why }` |
+| `capabilities`: an OAuth client with scopes | `google-workspace`, `microsoft-365` and `slack` with `access: "write"`, `scopes: [...]` (the least that does the job) and `optional: true`; the Gateway holds the client, the app keeps each member's tokens | `open-crm/everyapp.config.ts` | `scopes: ["gmail.read", "calendar.read"]` |
+| `capabilities.email` and `capabilities.members` | Email as `access: "write"` (required for an inbox, optional for reports); members as `access: "read"` to know who can open the app | `agentic-inbox/everyapp.config.ts`, `open-analytics/everyapp.config.ts`, `starter/everyapp.config.ts` | The starter's `members` and `listMembers()` in `starter/src/serverFunctions/home.ts` |
+| `secrets`, required | The app's own root secret, with a `why` that says how to make one | `open-analytics/everyapp.config.ts` (`MAIN_SECRET`) | "32 or more random characters, e.g. openssl rand -base64 32" |
+| `secrets`, optional | Keys one feature needs, each with a `why`, and `docs` where a page exists (`GITHUB_TOKEN`); the feature says so where it is used | `open-crm/everyapp.config.ts` (`TOKEN_ENCRYPTION_KEY`, `GITHUB_TOKEN`, `OPENROUTER_MODEL`, `ERASURE_SECRET`) | `{ name, optional: true, why }`, plus `docs` when there is a page |
+| `access: "everyone"` | Every member of the organization can open the app; owners and admins manage inside it. OpenSEO leaves the default | `open-crm/everyapp.config.ts`, `open-analytics/everyapp.config.ts`, `agentic-inbox/everyapp.config.ts` | The default is `admins`: say `everyone` when the app is for the team |
+| `ai.models` | The model ids the Gateway accepts from the app; any other is `model_not_allowed` | `agentic-inbox/everyapp.config.ts` | List every id the code can send, per provider |
+| `email.inbound` | The Worker exports an `email()` handler; the addresses are set after the deploy with `everyapp email set --inbound` | `agentic-inbox/everyapp.config.ts` | `email: { inbound: true }` |
+| `build` and `dev` | Commands when the app's build is more than `cf build` (bundles to build first, an environment variable to set) | `open-analytics/everyapp.config.ts`, `open-seo/everyapp.config.ts` | `dev` must listen on `PORT` |
+| `compatibilityDate` | The runtime date every build runs on | `open-analytics/everyapp.config.ts`, `open-seo/everyapp.config.ts` | Pin it when porting an app that ran under Wrangler |
+| `cloudflare.config.ts` beyond the manifest | Crons, compatibility flags and plain text bindings read when the Worker is built | `open-crm/cloudflare.config.ts` (`crons: ["* * * * *"]`, `global_fetch_strictly_public`), `agentic-inbox/cloudflare.config.ts` (`AI_PROVIDER`, `AGENT_MODEL`), `open-seo/cloudflare.config.ts` | `everyAppWorker({ manifest, entrypoint, ctx, crons })`, then spread and extend |
+
+## Cloudflare resources
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| Workers AI as a binding | `resources.ai` binds `env.AI` on every Worker of the app: `env.AI.run()` directly (the Agents SDK, models the OpenAI-compatible routes don't carry, an AI Gateway by id), billed to the account with no Gateway budget or cap. Under `pnpm dev` every call throws `Binding AI needs to be run remotely` until `vite.config.ts` sets `remoteBindings: true` and `cf auth login` has run. For calls the Gateway caps and counts, list the `workers-ai` provider instead | `packages/sdk/src/cloudflare/worker.ts` (`addAiBindings()`); no app uses it yet: `agentic-inbox/workers/everyapp/gateway.ts` (`gatewayAi()`) is the provider path for code written against `env.AI.run()` | `resources: { ai: ["AI"] }`, then `await env.AI.run("@cf/meta/llama-3.1-8b-instruct", { prompt })` |
+
+## Sending and receiving email
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| Sending email | `sendEmail({ env, for, message })` through the Gateway's `email` capability; the Gateway checks the sender against what `everyapp email set --sender` allowed, and the budgets | `agentic-inbox/workers/everyapp/email.ts`; `open-analytics/src/lib/notifications/edge/delivery.ts` | `gatewayEmail()`: the SDK call shaped as the `send_email` binding upstream's code expects, every refusal an `EmailSendError` with the Gateway's code; OpenAnalytics skips the mail, and says so, on a Gateway without email |
+| Receiving email | An `email()` export beside `everyApp()`'s `fetch`; the deploy makes the Email Routing rules from `email.inbound` and the addresses `everyapp email set --inbound` names | `agentic-inbox/workers/app.ts`, `agentic-inbox/workers/everyapp/inbound.ts`, `agentic-inbox/test/receive-email.test.ts` | `export default { ...everyApp(handler, { tools }), async email(event, env, ctx) { … } }`; rethrow so Email Routing retries or bounces |
+
+## AI through the Gateway
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| AI through the Gateway | `createGatewayFetch({ env, for })` as the `fetch` of an OpenAI-compatible client, with a base URL on the Gateway's `/api/ai/<provider>/…` path; the Gateway holds the key, so the client's own key is a placeholder | `open-crm/src/server/lib/openrouter.ts`; `agentic-inbox/workers/everyapp/gateway.ts` | OpenCRM: `createOpenRouter` over the Gateway fetch, the model from the optional secret `OPENROUTER_MODEL`; Agentic Inbox: `gatewayModel()` with `@ai-sdk/openai-compatible`, and `gatewayAi()` as a `run()` shim for code written against Workers AI |
+| Every AI failure as a sentence | `ConfigurationError` (no Gateway and no dev key), `ai_provider_not_configured` (the key isn't set on the Gateway) and every other refusal read with `gatewayRefusal()`, each turned into one sentence that names the setting and who sets it | `agentic-inbox/workers/everyapp/agent-ai.ts`, `agentic-inbox/workers/everyapp/gateway.ts` | `aiSetupProblem()` before the first call; `aiProviderNotSetUpMessage()` names the command, never a value |
+| Whose call it is | Attribution: while serving a request, `for: request`; for work no request started (a cron, a Workflow, an agent's turn), `for: { background: true, organizationId }` | `open-crm/src/server/lib/gateway-attribution.ts`, `open-seo/src/server/lib/gateway-attribution.ts`; `agentic-inbox/workers/everyapp/agent-ai.ts` (`forMailbox()`) | `serveEveryAppRequest(request, user, fn)` at the entry and in tools; `forOrganization(id, fn)` around background work |
+
+## Agents, Workflows and a second Worker
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| A Durable Object agent | One Durable Object per conversation or task, named for its organization; authorized in the Worker before the request reaches the object; the model through the Gateway | `open-crm/src/server/features/agent/CrmAgent.ts` (on `@cloudflare/think`), `open-crm/src/server/features/agent/agentRoutes.ts`; `agentic-inbox/workers/agent/index.ts` (on `@cloudflare/ai-chat`), `agentic-inbox/workers/app.ts`; `open-seo/src/server/features/sam/SamChatAgent.ts`, `open-seo/src/server.ts` | `routeAgentRequest(request, env, { onBeforeConnect, onBeforeRequest })` with a guard that checks the session is the caller's organization's |
+| Workflows | A `WorkflowEntrypoint` a cron starts; the organization named once around `run()` and carried into every step | `open-seo/src/server/workflows/RankCheckWorkflow.ts`, `open-seo/src/server/workflows/pgStep.ts`, `open-seo/cloudflare.config.ts` (the cron) | `forOrganization()` around `run()`; `carryOrganization()` inside `pgStep()` |
+| A second Worker | A helper Worker for work that should not share the app's memory (a crawler, Lighthouse); it exports its Workflow and Durable Object classes and an RPC `WorkerEntrypoint`, and only the app's Worker can reach it | `open-seo/src/audit-worker.ts`, `open-seo/vite-plugin-every-app.ts`, `open-seo/everyapp.config.ts` (`workers`) | `everyAppAuxiliaryWorker({ manifest, worker: "audit", entrypoint, ctx })` under the Cloudflare Vite plugin's `auxiliaryWorkers` |
+| The lean Worker bundle | A Vite plugin that stubs dead-weight packages, swaps zod's locales for English alone, and fails the build when a denylisted module reaches the Worker's eager import graph | `open-seo/vite-plugin-lean-worker-bundle.ts` | `EAGER_DENYLIST` with an `expected` note per entry; the `generateBundle` assertion |
+
+## Tools
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| The starter's catalog | Four tools over the same queries as the server functions, the zod schemas shared; `instructions` for the set; `ToolError` for a message the model may read | `starter/src/tools.ts`, `starter/src/server/todos.ts` | `risk` per tool, `idempotent` where true, `handler: (input, { user }) => todos.listTodos(user.id)` |
+| Tools per feature, with output schemas | One module per feature exporting a map, spread into one `defineTools()`; a `crmTool()` wrapper that adds `output` schemas, with the shapes several tools share (`personOutput`, `recordRefOutput`, `pageOf()`) | `open-crm/src/server/everyapp/tools.ts`, `open-crm/src/server/everyapp/tools/companies.ts`, `open-crm/src/server/everyapp/crm-tool.ts`, `open-crm/docs/maintainers/mcp.md` | People named by email, never by id, in what a model reads; "Never guess ids" in `INSTRUCTIONS` |
+| Wrapping an existing tool registry | An app that had an MCP server keeps its registry and adapts each entry: `risk` from the annotations and the name, `objectSchema()` for input and output, `toolResult({ text, structured })` from the old `CallToolResult` | `open-seo/src/server/everyapp/tools.ts` | `riskOf()`; the old MCP server is off: the Gateway's `/mcp` serves the catalog (an app's host answers `/mcp` only with the manifest's `mcp: { by, why }`, which none of the four sets) |
+| Tools over the private API, in-process | Each tool calls the same Hono API the dashboard uses, with the call's identity, so permissions and validation live in one place | `open-analytics/src/lib/mcp/tools.ts` | `resolveViewer()` from the call; `MAX_RESULT_BYTES` asking for a narrower question |
+| Tools loaded on first use | The tools module behind a dynamic import on `/__everyapp/*`, so the app's eager bundle stays small | `open-crm/src/server.ts` | `if (pathname.startsWith("/__everyapp/")) { const { everyAppTools } = await import(...) }` |
+| Schemas without zod 4.2 | `{ jsonSchema, validate }` from an older zod's `toJSONSchema` and Standard Schema | `agentic-inbox/workers/everyapp/tools.ts` | `plainSchema(schema)` |
+| Testing the catalog | The catalog read the way the Gateway reads it (`POST /__everyapp/tools/list` with a system token), the risk of every tool checked, and calls as a read-only and a read-write caller | `open-crm/src/server/everyapp/catalog.test.ts`, `open-crm/src/server/everyapp/toolTestSupport.ts`; `agentic-inbox/test/tools.test.ts` | `reads` equals every `list_`, `get_` and `search_` tool |
+
+## Needs setup inside the app
+
+Every app says, inside itself, what the Gateway hasn't got yet: the setting's name and who sets it, never a value, never the Gateway's own refusal sentence.
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| The starter's first screen | Who the Gateway signed in and what the app was allowed, read from the inlined manifest; a `GatewayRefusalError` from `listMembers()` is a state the page shows | `starter/src/routes/index.tsx`, `starter/src/serverFunctions/home.ts` | `whoCanOpen()`: catch the refusal, return its code |
+| A paused agent | A checklist of the Gateway's keys for the agent (`OPENROUTER_API_KEY`, `CONTEXT_API_KEY`): done, checking or missing, each with what being unset costs and the command an owner or admin runs; members are told whom to ask | `open-crm/src/server/features/setup/services/SetupService.ts`, `open-crm/src/client/features/agent/AgentPaused.tsx`, `open-crm/src/serverFunctions/setup.ts` | `pausedResearchMessage(canManage)`: two sentences, by role |
+| A required secret | Without the root secret every page redirects to one that names the secret and the command (`pnpm everyapp secret set MAIN_SECRET --app analytics`), or `.dev.vars` under `everyapp dev` | `open-analytics/src/middleware.ts`, `open-analytics/src/routes/$locale.runtime-config-error.tsx` | `loadRuntimeSetupMode()` asks the Worker whether it runs under `everyapp dev` |
+| A capability | `integrationStatus({ env, provider }).ready` without calling the provider, driving the "set up DataForSEO" prompt | `open-seo/src/server/lib/provider-access.ts`, `open-seo/src/serverFunctions/config.ts` | `hasProviderAccess()` |
+| Email | A banner before the person writes: no sender allowed yet (`everyapp email set --sender`) or no `EMAIL_FROM`; owners and admins get the command with the mailbox's domain filled in, members whom to ask; Send stays enabled, the server decides | `agentic-inbox/app/components/SendingOffBanner.tsx` | `config.ready === false` from `GET /api/v1/config` |
+
+## Cookies, headers and the bundle
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| App-host session cookies | The Gateway strips every `Cookie` header before a request reaches the app and refuses requests whose cookies repeat its own session cookie's name, so an app can never read back a cookie it set; `withoutCookies()` drops any `Set-Cookie` the app's framework adds (a WebSocket upgrade passes through) | `open-crm/src/server/everyapp/cookies.ts`, `open-seo/src/server/everyapp/cookies.ts`; `open-analytics/src/server.ts` | Wrap the response of `everyApp()`'s `fetch` in `withoutCookies()`; keep preferences in the browser |
+| Security headers the app sets itself | `frame-ancestors 'self'`, an `img-src` of only what the app shows, a per-response nonce for inline scripts, on HTML documents without a policy of their own. OpenAnalytics sets one static policy on every page instead (`withPageHeaders` in `open-analytics/src/server.ts`: `frame-ancestors 'none'`, no nonce) | `open-crm/src/server.ts` | `APP_CSP` |
+
+## Tests
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| Tests over queries with an in-memory SQLite | libsql `:memory:` with the app's migrations applied by drizzle's migrator, `@/db` mocked to it; one test that two people's rows stay apart | `starter/src/server/todos.test.ts` | `vi.hoisted` and `vi.mock("@/db", …)`; `migrate(db, { migrationsFolder })` |
+| A test database with every migration | `createSqliteTestDb()` applies every production migration so repositories run their real queries; `seedTwoOrganizations()` and tests that one organization never sees another's rows | `open-crm/src/server/testing/testDb.ts`, `open-crm/src/server/features/agent/repositories/isolation.test.ts` | Mock `cloudflare:workers`, `@/db` and `@/db/runBatch` from the hoisted database |
+| A fake Gateway binding | A `fetch` that records every call's URL, body and identity header, standing in for `EVERY_APP_GATEWAY` | `agentic-inbox/test/with-gateway.test.ts`, `agentic-inbox/test/gateway-email.test.ts` | `fakeGateway(reply)` |
+| Public routes under test | The collect token's issue and verify, and the collector's refusals | `open-analytics/src/lib/edge/__tests__/collect-token.test.ts`, `open-analytics/src/lib/edge/__tests__/collect.test.ts` | Test the refusal paths first |
+
+## Dev vs production
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| `.dev.vars` | Locally there is no Gateway: the app's own secrets and the Gateway settings its manifest names (a provider key, `EMAIL_FROM`, `EVERYAPP_EMAIL_SENDERS`) come from `.dev.vars`, gitignored; `pnpm dev` names the ones missing | `agentic-inbox/.dev.vars.example`, `open-analytics/.dev.vars.example`, `open-crm/.dev.vars.example`; `starter/src/env.d.ts` | Ship a `.dev.vars.example` that names each variable and where it comes from, with no values |
+| The manifest inlined for the page | The Worker can't import `everyapp.config.ts`; Vite's `define` inlines it as `__EVERYAPP_MANIFEST__` for the first screen | `starter/vite.config.ts`, `starter/src/serverFunctions/home.ts`, `starter/src/env.d.ts` | `remoteBindings: false`: local dev never touches remote resources |
+| Dev or deployed, in the app | `env.EVERYAPP_DEV` says which. The starter's `launcher` is `EVERYAPP_IDENTITY_ISSUER` (the Gateway's URL) when deployed and the dev host one label up under `everyapp dev`; the apps read `GATEWAY_URL` (set by the deploy) first, then the issuer | `starter/src/serverFunctions/home.ts`; `open-crm/src/serverFunctions/everyApp.ts`, `agentic-inbox/workers/everyapp/identity.ts`; `open-analytics/src/routes/$locale.runtime-config-error.tsx` | Name `.dev.vars` in dev and `pnpm everyapp configure <app>` when deployed |
+| What a port changes | What the Gateway replaces in an app that ran elsewhere (sign-in, keys, MCP, email), in one table | `open-crm/docs/maintainers/every-app.md`, `open-seo/docs/maintainers/every-app.md`, `agentic-inbox/docs/EVERY_APP.md` | Keep such a document in the app |
+
+## Release and install
+
+| Pattern | What it is | Where | Copy this |
+| --- | --- | --- | --- |
+| Release and install | `pnpm everyapp release` packs the production build, the migrations and a `release.json` into `everyapp-release.tar.gz`; from a GitHub release of the app's repository, anyone installs it with `pnpm everyapp install <repository url>`, no clone. `pnpm pack-for-app <app dir> --workflow` from an Every App checkout vendors the CLI and the SDK into the app's repository (`file:` tarballs under `vendor/`) and adds the Release workflow that publishes the tarball on every push. The vendored CLI runs `dev`, `db migrate` and `release`, not `deploy`: deploys run from an Every App checkout (`pnpm everyapp install <url>` there, or that checkout's CLI from the app's directory). OpenCRM, OpenSEO and Agentic Inbox bind an R2 bucket, so R2 is enabled once on the account before their first install (`R2_NOT_ENABLED` otherwise); OpenAnalytics needs nothing | `docs/runbooks/app-releases.md`, `scripts/pack-for-app.mjs`, `scripts/pack-for-app/release.yml` and `landing-page/content/agent/deploy.md` ("Release installs") in the checkout; `open-crm/docs/maintainers/releases.md` (tags, notes) | `pnpm pack-for-app <app dir> --workflow` once, then commit `vendor/`, `package.json`, `pnpm-lock.yaml` and the workflow; after a platform change the same command without `--workflow`; the version in `package.json` names the release |
+
+A pattern missing here: read the four manifests first, then search the app for the SDK export you need (`createGatewayFetch`, `integrationFetch`, `sendEmail`, `listMembers`, `defineTools`).

package/skills/everyapp/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: everyapp
+description: Create, run, deploy and manage private web apps on Cloudflare with everyapp (Every App). Use before running any everyapp command, to deploy an app, set a secret, query its database, check the Gateway, or answer any "how do I" question about Every App.
+---
+
+everyapp: self-hosted platform for private web apps on Cloudflare. While
+publishing is paused the command is `pnpm everyapp` (never `npx everyapp`),
+run from the Every App checkout or from an app's directory (its package.json
+links the CLI).
+
+Docs: two worlds. The user docs (https://everyapp.com/docs) are short and
+for the person. The agent docs are yours: https://everyapp.com/llms.txt
+lists every page with a one-line summary; a page is Markdown at its URL
+plus .md (https://everyapp.com/docs/agent/manifest.md); in a checkout they
+are landing-page/content/agent/*.md. Pages: setup (driving setup for a
+person, every handoff), cli (every command and flag), json (the --json
+protocol), errors (every code and its fix), troubleshooting (by symptom),
+status (the report, every line, and its fixes in order), manifest
+(everyapp.config.ts), identity (headers, token, env, SDK), secrets
+(secrets vs Gateway settings vs capabilities), dev (dev vs production),
+email, events (webhooks, email alerts, the signature, every event type,
+emit()), mcp (tools, connector, OAuth), deploy (the pipeline, what the policy
+check refuses), providers (API providers: the catalog, registering one,
+a spec's fields), access (Cloudflare Access), workspace (the workspace from
+the terminal and from an AI client: every command and every tool), gateway
+(everything a Gateway offers: apps vs MCP apps vs the compact MCP surface,
+people, groups and caps, the CLI by job, what to suggest next, other MCP
+servers), build (the build-every-app skill as a page), patterns (its
+example-patterns index), repo/* (security model, capabilities, runbooks).
+Step-by-step setup of each
+integration (the Gateway, Access, email, DataForSEO, Context, OpenRouter,
+OpenAI, Workers AI, Google, Microsoft 365, Slack; every catalog provider by
+id in setup/providers.md): setup/README.md beside this file.
+Answering "how do I": fetch the page for the subject and answer from it
+with the exact command or manifest field, naming the page. A failed
+command: look its code up on errors (anchor: the code, lowercased) before
+trying anything else. Never guess a flag: cli has them all.
+Building an app: the Gateway signs people in, so never build a login page
+or auth; read the user with the SDK (identity page), and scope every query
+by user.id: the Gateway admits every member of the organization. A new app
+edits everyapp.config.ts for name, resources, public, providers,
+capabilities, secrets and email (manifest page), and the Gateway gives it
+nothing it doesn't declare there. AI: list the provider, providers:
+["openai"] (or openrouter, workers-ai), and call it with the SDK's
+createGatewayFetch({ env, for: request }), a fetch for
+http://every-app-gateway.internal/api/ai/<provider>/... (an OpenAI client
+takes it as fetch, with http://every-app-gateway.internal/api/ai/openai/v1
+as baseURL; the other two base URLs and the code are on the identity
+page); the Gateway holds the key, never the app, and a provider the
+manifest doesn't list is refused provider_not_allowed 403. A capability
+(members, email, an OAuth client, DataForSEO) is listed under
+capabilities with access and a why and called with listMembers(),
+sendEmail() or integrationFetch() (secrets page); an OAuth client with
+scope sets (google-workspace, microsoft-365, slack) is listed with
+scopes: [...] and held to them; after a schema change run pnpm run
+db:generate; a value only dev needs goes in .dev.vars, never in git (dev
+page). The way back: the first row of the app's sidebar (or of its page
+header when it has no sidebar) is a muted "‹ Every App" link to
+GATEWAY_URL (aria-label "Back to Every App"), above the app's own name,
+so every app on the Gateway reads the same; put nothing else about the
+Gateway in the footer.
+
+Pass --json. One JSON event per line; "done" = success; exit 2 = show the
+user the last action_required (url, code), then run its data.rerun (the same
+command, unless it names another); exit 1 = show the error; if data.authorize
+is set, ask before using data.rerun. waiting: true = keep reading (5 min
+for the device login, up to 15 for the owner link).
+
+State:   pnpm everyapp status --json   (data.fixes says what to run when something is off;
+         data.next says what to do next: at most four { code, command | url, note, why }
+         from the Gateway's state, never repeating a fix; tell the person
+         each why and offer the command or page; data.apps[].setup says what each
+         app needs set: ready, settings, unmet (each with why and docs), and
+         command, pnpm everyapp configure <app>)
+Gateway: pnpm everyapp setup --domain <host> --json   (install, upgrade, repair;
+         a fresh install runs 5-20 min: build, certificate, then up to 15 min
+         waiting for the owner link, so give it a long timeout or background
+         it and keep reading; run data.rerun as given (a needsTerminal rerun
+         goes to the person))
+New app: pnpm everyapp create ../<id> --json   (from the every-app folder: the
+         app is its own repository beside it, linked to the checkout; a bare
+         <id> makes apps/<id> inside the checkout instead) then cd into it and
+         edit src/; the manifest is everyapp.config.ts
+Run:     pnpm everyapp dev   (long-running, human-facing: start it in the
+         background and read the printed URL; no --json; --port when 8787 is
+         taken; stop it with Ctrl-C/SIGINT to the everyapp process, never a
+         pattern kill of vite or workerd; a pnpm install or deploy meanwhile
+         rebuilds the SDK and breaks dev for a few seconds)
+Ship:    pnpm everyapp deploy --json   (from the app directory; safe to repeat;
+         also upgrades the Gateway to this checkout when it has to rebind).
+         No Gateway yet: action_required install_gateway; ask the user, run
+         its data.rerun (setup), then deploy again. done.data.publicRoutes
+         lists the routes the manifest opens to the internet without
+         sign-in; tell the person which.
+Release: someone else's app, without a clone: pnpm everyapp install
+         https://github.com/<owner>/<repo> --json (its latest release's
+         everyapp-release.tar.gz; a tarball URL or file works too). NO_RELEASE:
+         the repository publishes none; clone it, pnpm install in it, then
+         this checkout's pnpm everyapp deploy from its directory. Never
+         build a repository from its URL yourself.
+         To publish one: pnpm everyapp release, then attach the
+         tarball to a GitHub release of the app's repository, or give
+         the repository the Release workflow that does it on every push
+         (pnpm pack-for-app <app> --workflow from this checkout;
+         docs/runbooks/app-releases.md).
+Data:    pnpm everyapp db migrate (local)   pnpm everyapp db query "<sql>" [--local] --json
+         (a production write stops with CONFIRMATION_REQUIRED: add --yes only
+         if the user said so). pnpm everyapp db restore --json undoes the last
+         deploy's migrations (and every write since): only when the user asks.
+Postgres: an app with resources.hyperdrive or migrations.dialect "postgresql"
+         reads POSTGRES_DATABASE_URL (and <BINDING>_ORIGIN_URL) from
+         .everyapp/secrets.env, which the user writes; never print, commit or
+         ask for its values in chat. deploy runs drizzle-kit migrate before
+         the upload.
+Secrets: pnpm everyapp configure <app> --json   sets up an app: every setting its
+         manifest declares, each where it is held (an AI key or a capability's
+         client on the Gateway, once for every app; the app's own secrets on
+         its Worker, after its first deploy); live at once, no deploy. At a
+         terminal it shows what is set (names only), asks for each required
+         setting that isn't with a hidden prompt (why, where to get it and its
+         guide above), which member of an any-of group, then offers the
+         optional ones; from you (no prompt): NAME=value lines on stdin (one
+         per line, from a command's output) or --from-env (each unset
+         setting from the variable of its own name; stdin isn't read then).
+         A value never goes on the command line (VALUE_ON_COMMAND_LINE). One
+         name at a time: pnpm everyapp secret set NAME [--app <id>] --json
+         (the value from a hidden prompt, stdin, or --from-env VAR). The name
+         decides where it goes. A Gateway setting (OPENAI_API_KEY, EMAIL_FROM,
+         GOOGLE_WORKSPACE_CLIENT_ID, …) is set on the Gateway from any
+         directory. An app's own secret must be listed under `secrets` in its
+         everyapp.config.ts and is set after its first deploy, from the app's
+         directory or from anywhere with --app <id> (SECRET_NOT_DECLARED: add
+         it there first). secret unset NAME [--app <id>]; secret list [<app>]
+         --json (one app's settings, where each is held and whether it is set,
+         with data.app.setup; elsewhere with no app named: the Gateway's names
+         and every app's settings).
+Needs setup: read data.apps[].setup; for each unmet setting show its why and docs
+         and read its setup guide (.claude/skills/everyapp/<setup>); then run
+         setup.command, pnpm everyapp configure <app>, without a value passing
+         through the chat: tell the person to run it in their own terminal (it
+         asks for each setting with a hidden prompt and says where to get it)
+         and say when done; or drive it yourself, --json always: NAME=value
+         lines on stdin from a command's output, or --from-env for variables
+         the person exported before starting you. Never a value on the command
+         line; never ask for, print, repeat or invent a value. An app whose
+         setup.ready is false doesn't open (status shows "needs setup"; deploy
+         warns APP_NEEDS_SETUP and puts the command under next); an any-of
+         group (setup.groups) needs one member set, not all: configure asks
+         which.
+Email:   pnpm everyapp email set --sender "*@<domain>" --inbound <address> --json
+         In the app's directory, after its first deploy; nothing is deployed. --sender
+         replaces the From addresses the Gateway lets the app name (everyapp.config.ts
+         lists capabilities.email); --inbound replaces the addresses routed to its
+         email() handler (everyapp.config.ts declares email: { inbound: true }) and
+         makes the Email Routing rules now. EMAIL_ROUTING_DISABLED needs the user's
+         yes: rerun with --enable-email-routing only if they said so. email unset
+         senders|inbound clears; email show prints both.
+Access:  pnpm everyapp access on --json   (Cloudflare Access in front of the Gateway
+         and its apps: finds or creates the Zero Trust team (--team NAME when the
+         account has none: permanent, ask the user), keeps both sign-in methods
+         (Sign in with Cloudflare for the account's members, the one-time PIN for
+         everyone else), keeps the allow policy with every member's and invitee's
+         email, puts two Access applications in front of the hosts with the
+         Gateway's MCP, OAuth and /health and each app's public routes let through
+         (an app host's /mcp only where its manifest sets mcp), and sets the three
+         CLOUDFLARE_ACCESS_* Gateway settings in one version. Rerunnable; run again
+         after inviting someone. access off asks (--yes); access show reports. Each
+         existing member then signs in once with their password through Access;
+         tell the user who (done.data.signIn).
+Set up:  what the Gateway holds for apps, end to end (the provider's side, the
+         key or OAuth client, configure or secret set, the check): read
+         setup/README.md in this skill first, then the file it names, each on
+         its own with the file-reading tool (together they pass a shell's
+         output cap). Cloudflare and the Gateway
+         (setup/gateway.md), Cloudflare Access (setup/access.md), email
+         (setup/email.md), API keys (setup/dataforseo.md, context.md,
+         openrouter.md, openai.md, workers-ai.md), OAuth clients
+         (setup/google.md, microsoft-365.md, slack.md), any other catalog
+         provider (setup/providers.md#<id>, generated from the catalog); a
+         provider registered on the Gateway has no file: pnpm everyapp
+         provider show <id> prints its spec. A key or client secret
+         never goes through the chat: README.md says the three ways it gets in.
+Remove:  pnpm everyapp delete <id> --json   never add --purge, --force-dns,
+         --allow-delete-*, --allow-downgrade, or --yes to delete unless the
+         user asked.
+MCP apps: pnpm everyapp mcp on dataforseo --json   offers a data provider's
+         tools (dataforseo_<tool>) to members' AI clients through the Gateway's
+         /mcp with the Gateway's key (DATAFORSEO_API_KEY, setup/dataforseo.md);
+         no page, nothing to deploy (the launcher lists it under "MCP apps").
+         pnpm everyapp mcp add <url> --auth bearer --json   does the same for
+         any remote MCP server (Streamable HTTP): <id>_<tool>, its credential
+         a Gateway setting <ID>_MCP_TOKEN set with secret set and pinned to
+         the URL's origin (setup/remote-mcp.md). add looks at the server once
+         and only warns. mcp list shows each app's kind, on/off/needs setup,
+         tools and key; mcp show <id> its URL, credential and every tool with
+         its risk; mcp tool <id> <tool> --risk read|write|destructive or --off
+         overrides one tool; mcp refresh <id> re-lists. mcp off <id> stops
+         serving and keeps access (mcp on is instant); mcp remove <id> deletes
+         it (the key stays; before 2026-10-25 off deleted it). The credential
+         never goes through the chat (setup/README.md's three ways). provider
+         on|off still run mcp on|off through launch week; provider list is the
+         API providers' list. You, owners and admins get it;
+         others are granted in Admin → Apps → Manage access. An owner or admin
+         caps an app's provider calls per month in Admin → Usage (off by
+         default): past it a provider tool answers a tool error naming the
+         cap, and an app's brokered call gets 429 app_monthly_cap_exceeded
+         until the next UTC month.
+APIs:    pnpm everyapp provider add stripe.json --json   registers an API
+         provider the catalog doesn't have on the Gateway: a JSON spec (hosts,
+         auth, settings named after its id, STRIPE_…; never a value; fields
+         and rules on the providers page), from a file or an https URL. Then
+         pnpm everyapp secret set STRIPE_API_KEY (it names the provider and
+         the hosts the key goes to, and binds the key to them: a row replaced
+         with --replace needs the key set again). An app lists it under
+         capabilities like a catalog provider and calls integrationFetch().
+         provider list (the catalog and the rows), provider show <id> (the
+         whole spec; --save writes .everyapp/providers/<id>.json for dev),
+         provider remove <id> (PROVIDER_IN_USE while an app lists it).
+Workspace: pnpm everyapp workspace rename "Acme Corp" --json   renames the workspace
+         (the Gateway's organization: the name in the switcher and in invitations;
+         1 to 64 characters, no line breaks). Nothing is deployed; members see it
+         on their next page. Owners and admins can do the same under Manage
+         workspace → Rename. WORKSPACE_NOT_CLAIMED: the Gateway has no owner yet.
+Roles:   pnpm everyapp workspace role <email> owner|admin|member --json   sets a
+         member's role in the workspace under the Cloudflare login (the Users
+         page does the same). Owners are peers and the workspace always keeps
+         one: the last owner's role is refused (LAST_OWNER); someone still
+         invited isn't a member yet (MEMBER_NOT_FOUND).
+Manage:  pnpm everyapp workspace --help   the rest of Manage workspace from the
+         terminal, under the Cloudflare login: show, users, invite (prints the
+         link; nothing is mailed), invite-link, uninvite, deactivate, reactivate,
+         remove (--yes), reset-link, groups, group create|set|delete|members|apps,
+         apps, app set|access|cap, usage, activity, tokens, token revoke,
+         connections, connection revoke; --json on each. --org <slug> acts on
+         another organization (a name two organizations share is refused:
+         ORG_AMBIGUOUS; scripts pass the slug or id). deactivate and remove keep
+         the last owner who can act (LAST_OWNER); a ban is account-wide, so
+         deactivate checks every organization the person owns.
+Events:  pnpm everyapp events add <url> --events 'cap.*,member.*' --json   sends
+         those Gateway events to a webhook (Slack workflow, Zapier, n8n), signed;
+         the generated secret is data.secret, shown once: hand it to the person,
+         never invent or echo one. --email admins mails owners and admins instead.
+         events list|test <id>|deliveries --dead|redeliver <id>; events types lists
+         types. An app emits its own with emit() (app.<id>.<name>), declaring
+         nothing. Everything: /docs/agent/events.
+Tools:   an app's AI tools are defineTools() in src/tools.ts; the Gateway
+         serves them at https://<gateway>/mcp as <app>_<tool> (dev:
+         http://<app-id>.localhost:8787/mcp) and snapshots them at deploy.
+         How to write, connect and debug them: mcp.md beside this file.
+Wipe:    pnpm everyapp teardown --account-id <id> --dry-run --json   deletes
+         EVERYTHING Every App made in one Cloudflare account (the Gateway too):
+         only on a dedicated test account the user names, never one they use.
+         Always --dry-run --json first and show the user data.plan. It needs
+         EVERYAPP_TEST_ACCOUNTS=<id> and CLOUDFLARE_API_TOKEN scoped to that
+         account in the environment, which the user sets. Without --confirm it
+         stops with TEARDOWN_CONFIRMATION_REQUIRED (authorize): never add
+         --confirm <id> unless the user explicitly asked for the deletion.
+
+Security: the Gateway signs people in and passes identity to the app in a
+         header the SDK verifies (everyApp(), getEveryAppUser(),
+         requireEveryAppUser(), a tool call's identity); never read who the
+         user is from a client-supplied header, cookie or parameter. Routes
+         are private unless listed under `public` in everyapp.config.ts; a
+         public route is open to the internet and does its own checks.
+         Before opening a pull request that touches identity, public routes,
+         tools, secrets or queries, review the changes locally against the
+         app boundaries in security-review.md beside this file: in Claude
+         Code, /security-review (its built-in review of the branch's pending
+         changes) pointed at that file; any other agent reads git diff
+         against the list there. No CI job and no API key: the review runs
+         where you run. Fix what it finds, or say in the pull request why a
+         finding is a false positive. What the Gateway promises and what an
+         app must do itself: docs/threat-model.md in the Every App checkout
+         (https://everyapp.com/docs/agent/repo/threat-model).
+
+Only a person can: approve the Cloudflare login, open the owner link, pick
+a workers.dev subdomain, pay for Workers Paid, buy a domain. Interactive
+setup optionally offers browser deployment: a Yes/No prompt (default No),
+then a hidden Cloudflare API token prompt. Never ask for its value in chat.
+It then offers Cloudflare Access (Yes by default; the team name asked for
+when the account has none); under --json neither is asked, and --yes
+answers No to both.
+Handing off: stop, tell the person in one or two lines what to do (the
+action's url and code, what to click, what to come back with), and resume
+with data.rerun when they say it is done. Two more only a person can do:
+pick the account (choose_account: data.choices, each with its rerun) and
+confirm in a terminal a Worker changed outside everyapp (rerun_interactive,
+data.needsTerminal: true: hand them the command without --json; adding it
+back loops). https://everyapp.com/docs/agent/setup.md has the words for
+each handoff and the order of a whole setup.
+Full reference: https://everyapp.com/docs/agent/cli.md (every command and flag),
+https://everyapp.com/llms.txt (every page).