okengine 0.17.2 → 0.18.3

package/site/content/docs/get-started/why.mdx

@@ -1,116 +1,140 @@
 ---
 title: Why OKE
-description: The six seams every TypeScript backend maintains by hand — and what OKE derives from one Manifest instead.
+description: From forty tools to one species — the Manifest, the `fx` rule, and the eight closed elements.
 source: docs/spec/unified-theory.md
 icon: Compass
 ---
 
-Every TypeScript backend works on day one. The bill arrives later: the cache
-that serves last month's schema, the secret that only exists on your laptop,
-the dashboard that has never heard of your new Flow.
+## From forty tools to one species
 
-None of these are router problems. They are **seams** — copies of your code's
-knowledge, kept in places the compiler cannot check, updated by memory.
+A booking API, a nightly cleanup job, a receipt email, a row-change hook — in most stacks these are **four frameworks**. In OKE they are **one species** with one shape. Learn the shape once; only the trigger changes.
 
-<Callout title="The one rule">
-  **All world access goes through `fx`.** What a Flow reads, writes, emits, and reveals is recorded
-  — so the seams below are derived from one Manifest, not re-typed per project.
-</Callout>
+> **The one rule**
+> Every backend behavior is a **Flow**: `on(Trigger) → Effects`. There are no separate species called endpoints, handlers, consumers, jobs, or workflows.
+
+## The pain we solve
 
-## The six seams
+Every TypeScript backend works on day one. The bill arrives later. None of these are router problems — they are **gaps** between what your code knows and what your tooling knows.
 
-### The cache that lies
+### Cache that lies
 
-You add a column to `orders` and update three writers. The hand-bumped cache
-key in `checkout` is not one of them. A customer finds it a week later.
+You add a column to `orders` and update three writers. The cache key in `checkout` is not one of them. A customer finds it a week later.
 
-**OKE derives:** reads and writes are recorded through `fx`, so invalidation
-follows the Flow — there is no separate key to remember.
+OKE derives: reads and writes are recorded through `fx`, so cache invalidation follows the Flow — there is no separate key to remember.
 
-### The secret that fails in prod
+### Secret that fails at 2am
 
-`STRIPE_KEY` lives in your laptop's `.env`, a README, and a teammate's shell
-history. The deploy boots fine — the first charge request dies at 2am.
+`STRIPE_KEY` lives in your laptop's `.env`, a README, and a teammate's shell history. The deploy boots fine — the first charge request dies at 2am.
 
-**OKE derives:** [Vault](/docs/elements/vault) contracts declare the need in
-code; boot resolves every contract and fails loud with every gap listed —
-never halfway.
+OKE derives: [Vault](/docs/elements/vault) contracts declare the need in code; boot resolves every contract and **fails loud** with every gap listed — never halfway.
 
 ### The glue you rewrite
 
-CORS rules, security headers, CSRF tokens, compression — copied from the last
-repo, tweaked, and already drifting from whatever that repo does today.
+CORS rules, security headers, CSRF tokens, compression — copied from the last repo, tweaked, and already drifting from whatever that repo does today.
 
-**OKE derives:** the official `okengine/plugins` set ships this glue once —
-shared lifecycle, optional live DB config, nothing to re-copy.
+OKE derives: the official `okengine/plugins` set ships this glue once — shared lifecycle, optional live DB config, nothing to re-copy.
 
 ### The dashboard that doesn't know you
 
-Your observability stack learned your routes from sampled traffic. The Flow
-you deployed an hour ago is invisible until someone wires it by hand.
+Your observability stack learned your routes from sampled traffic. The Flow you deployed an hour ago is invisible until someone wires it by hand.
 
-**OKE derives:** its operator interface reads the Manifest —
-flows, effects, traces, architecture — current on every save, in dev and prod
-(`:6533`).
+OKE derives: its operator interface reads the Manifest — flows, effects, traces, architecture — current on every save, in dev and prod (`:6533`).
 
-### The permission check in the wrong place
+### Permission check in the wrong place
 
-`if (!user.isAdmin)` sits in handler forty-one of sixty. Which Flows touch
-`payments`? grep answers slowly; review answers never.
+`if (!user.isAdmin)` sits in handler forty-one of sixty. Which Flows touch `payments`? grep answers slowly; review answers never.
 
-**OKE derives:** declared effects produce a least-privilege matrix — widening
-access appears in Manifest Diff, not in a diff nobody reads.
+OKE derives: declared effects produce a **least-privilege matrix** — widening access appears in Manifest Diff, not in a diff nobody reads.
 
 ### Local works, prod doesn't
 
-Local runs one vendor client, CI another, prod a third — three glue stories
-for the same database. "Works on my machine" is a driver mismatch.
+Local runs one vendor client, CI another, prod a third — three glue stories for the same database.
 
-**OKE derives:** drivers are named after protocols (`postgres`, `redis`,
-`s3`), the vendor lives in `images`, and `oke dev` runs the real
-stack locally.
+OKE derives: drivers are named after protocols (`postgres`, `redis`, `s3`), the vendor lives in `images`, and `oke dev` runs the real stack locally.
 
-## The tax is drift
+---
 
-Every seam above is the same shape: a hand-maintained copy of knowledge the
-code already has. Watch one change propagate both ways.
+Every gap above is the same shape: knowledge the code already has, duplicated somewhere the compiler cannot check. **The tax is drift.** One change costs fifteen seams to update by hand; in OKE it always costs one.
 
-<DriftBoard />
+## One Manifest feeds every surface
 
-On the left, versions scatter and stay scattered. On the right, one Manifest
-feeds five surfaces — they cannot disagree, because none of them is a copy.
+At build time OKE extracts a **Manifest** — a machine-readable description of your system from TypeScript source. You do not maintain a second source of truth; the Manifest is the _single artifact_ from which everything downstream is derived:
 
-## The answer's shape
+| Surface                           | Port               | You maintain?                 |
+| --------------------------------- | ------------------ | ----------------------------- |
+| Typed client (`okengine/client`)  | your app code      | No — derived from `Manifest`  |
+| Console panels, traces, explorers | `:6533`            | No — reads the Manifest       |
+| MCP for agents                    | `:6535`            | No — reads the Manifest       |
+| Architecture diagram              | Console            | No — it _is_ the effect graph |
+| Capability matrix + cache keys    | compiler / runtime | No — inferred from `fx`       |
 
-Forty infrastructure concerns collapse into eight elements — each kept only
-because it has irreducible physics. One change costs up to fifteen seams in
-the zoo; here it always costs two.
+Because every surface reads the same Manifest, they **cannot disagree** — there is only one source of truth.
 
-<CollapseBoard />
+## The `fx` rule — one door to the world
 
-New infrastructure becomes a **driver** for an existing element, never a
-ninth element — the set of eight is closed.
+**All world access goes through `fx`.** A Flow that imports `node:fs`, calls `fetch` directly, or uses `Date.now()` is a defect. Effects are **inferred from what a Flow touches through `fx`**, and that inference powers the Manifest, the Console, caching, and durability.
 
-## Traditional vs OKE
+<Callout title="What `fx` records">
+  Every read, write, emit, send, ask, secret, and call is captured — so the Manifest knows exactly
+  which flows touch `orders` or send PII to a model, without you declaring it.
+</Callout>
 
-| Seam               | Maintained by hand                                        | Derived by OKE                                                          |
-| ------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------- |
-| Behavior model     | Endpoints, jobs, consumers, workflows as separate species | One species — Flow: `on(Trigger) → Effects`                             |
-| Cache invalidation | Hand-written keys; drift from writers                     | Derived from effects recorded through `fx`                              |
-| HTTP glue          | Middleware copied per repo                                | Official plugins — `headers`, `cors`, `csrf`, compression, IP allowlist |
-| Secrets / config   | Env sprawl; fails on first request                        | Vault contracts; `VaultBootError` at boot                               |
-| Observability      | Bolted on; separate source of truth                       | Console from the Manifest, dev and prod (`:6533`)                       |
-| Permissions        | Ad-hoc checks scattered in handlers                       | Least-privilege matrix from declared effects                            |
-| Local vs prod      | Vendor clients; one-off compose                           | Protocol drivers; vendor in `images`; `oke dev`                         |
-| Client / agents    | Separate codegen or hand-kept schemas                     | Typed client and MCP (`:6535`) from the same Manifest                   |
+| Inferred from `fx`      | What it gives you                    |
+| ----------------------- | ------------------------------------ |
+| Cache invalidation keys | Automatic — follows the Flow         |
+| Live queries            | Built-in subscription model          |
+| Least-privilege tokens  | Capability matrix from effects       |
+| Deterministic tests     | Time, clock, and randomness injected |
+| Manifest Diff           | Exact change surface on every save   |
+
+## Eight elements — a closed set
+
+Forty infrastructure concerns collapse into eight elements — each kept only because it has **irreducible physics**. New infrastructure becomes a **driver** for an existing element, never a ninth.
+
+| Element     | Essence                       | Replaces the zoo                                          |
+| ----------- | ----------------------------- | --------------------------------------------------------- |
+| **Flow**    | Behavior                      | endpoint · handler · consumer · job · workflow · webhook  |
+| **Signal**  | Data in motion                | queue · pub/sub · stream · websocket · SSE · event bus    |
+| **Store**   | Data at rest                  | database · cache · KV · file storage · search index       |
+| **Clock**   | Time                          | cron · delay · timeout · durable sleep · TTL              |
+| **Gate**    | Permission to act             | auth · session · ABAC · rate limit · quota · feature flag |
+| **Vault**   | Protected knowledge           | secrets · config · environment                            |
+| **Channel** | Reaching humans               | email · SMS · WhatsApp · push                             |
+| **AI**      | Reaching machine intelligence | model calls · prompts · embeddings · agents · RAG         |
+
+Drivers are named after **protocols** (`postgres`, `redis`, `s3`) — never vendors. The vendor lives in `images`, and `oke dev` runs the real stack locally.
+
+## The shape of a Flow
+
+One pipeline. Only the trigger changes between an endpoint, a job, a consumer, and a row hook:
+
+```ts
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+
+export const health = on(
+  http.get().public(),
+  flow({
+    out: z.object({ ok: z.literal(true) }),
+    do: () => ({ ok: true as const }),
+  }),
+);
+```
+
+| Piece         | Role                                                           |
+| ------------- | -------------------------------------------------------------- |
+| **Trigger**   | How work starts — `http`, a signal, `every`, a row change      |
+| **Contracts** | `in`, `out`, typed `errors` — validated before and after `do`  |
+| **`do`**      | The body — every read, write, emit, and call goes through `fx` |
+| **Effects**   | Inferred from those `fx` calls — not hand-annotated            |
+
+Consequence: **one documentation path, one trace shape, one Flow model, one thing for an AI agent to learn.**
 
 ## Ambition, stated plainly
 
-|                 | Statement                                                                                        |
-| --------------- | ------------------------------------------------------------------------------------------------ |
-| **Ambition**    | The default, most capable TypeScript backend — Bun-first, Web-Standards portable, contract-first |
-| **Grounded in** | Eight elements, effect inference through `fx`, Gate and Vault, the official plugin set           |
-| **Maturity**    | **pre-1.0** — published and usable; not independently battle-tested at scale yet                 |
+> **Ambition**: The default, most capable TypeScript backend — Bun-first, Web-Standards portable, contract-first  
+> **Grounded in**: Eight elements, effect inference through `fx`, Gate and Vault, the official plugin set  
+> **Maturity**: **pre-1.0** — published and usable; not independently battle-tested at scale yet
 
 ## Learn more
 

package/site/content/docs/index.mdx

@@ -23,7 +23,7 @@ on(orderPlaced, sendReceipt);
   <Card
     title="Get Started"
     description="One law → install → first flows."
-    href="/docs/get-started"
+    href="/docs/get-started/introduction"
   />
   <Card title="Elements" description="Flow → AI reference, one page each." href="/docs/elements" />
   <Card

package/site/content/docs/plugins/apple.mdx

@@ -0,0 +1,151 @@
+---
+title: "Apple"
+description: "Official plugin — Sign in with Apple with form_post callbacks and an ES256 client-secret JWT."
+icon: "Apple"
+source: "docs/spec/unified-theory.md"
+---
+
+Sign in with Apple is OIDC with three twists: the web flow **posts** its
+response, every exchange needs an ES256 client-secret **JWT you sign**, and
+`email_verified` can arrive as the _string_ `"false"`.
+
+<Callout title="The one rule">
+  Create a Sign in with Apple key (Team ID, Key ID, `.p8` private key), seed the key in Vault, and
+  register your exact callback URI — Apple validates all three on every exchange.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create a key
+
+In the Apple Developer portal: Identifiers → register an App ID with _Sign In
+with Apple_; Keys → create a key with that capability; note the **Team ID**
+and **Key ID**, and download the `.p8` once.
+
+</Step>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { oauth } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "dev",
+  gate: { auth: {} },
+}).plug(
+  oauth({
+    baseUrl: "https://app.example.com",
+    providers: {
+      apple: {
+        enabled: true,
+        teamId: "ABCDE12345",
+        keyId: "XYZ6789012",
+      },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Seed the private key
+
+```text
+# .env.local
+OAUTH_APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
+MIGTAgEAMBMGByqGSM49AgEGCCqGSM49AwEH...
+-----END PRIVATE KEY-----"
+```
+
+The driver mints a fresh ES256 client-secret JWT per exchange (`iss` = team,
+`kid` = key, one-hour life) and discards nothing to disk.
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect      | Behavior                                                                  |
+| ----------- | ------------------------------------------------------------------------- |
+| Callback    | Apple posts `code` + `state` as a form body — both GET and POST are bound |
+| Signature   | ES256 against `appleid.apple.com` JWKS                                    |
+| Issuer      | must equal `https://appleid.apple.com`                                    |
+| Name        | delivered only on first authorization via the form-posted `user` field    |
+| Email trust | strict parse — only boolean `true`, `"true"`, or `"1"` count              |
+
+**Consequence:** the string `"false"` stays unverified. Naive truthiness would
+mark every private-relay email verified — that is the takeover bug class this
+parse exists to close.
+
+Default scopes: `name`, `email`.
+
+## Options
+
+| Option                | Type       | Default            | Meaning                                 |
+| --------------------- | ---------- | ------------------ | --------------------------------------- |
+| `enabled`             | `boolean`  | `false`            | Turn the provider on                    |
+| `clientId`            | `string`   | Vault/env\*        | `\*OAUTH_APPLE_CLIENT_ID` (Services ID) |
+| `teamId`              | `string`   | required           | Apple Developer Team ID                 |
+| `keyId`               | `string`   | required           | Private-key identifier                  |
+| `redirectUri`         | `string`   | `{baseUrl}…/apple` | Exact registered URI                    |
+| `scopes`              | `string[]` | `name email`       | Requested scopes                        |
+| `storeProviderTokens` | `boolean`  | `false`            | Keep tokens in Vault                    |
+
+## Surfaces
+
+| Flow     | Path                                  |
+| -------- | ------------------------------------- |
+| Start    | `POST /auth/oauth/apple/start`        |
+| Callback | `GET+POST /auth/oauth/callback/apple` |
+| Link     | `POST /auth/oauth/apple/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="invalid_client at token exchange">
+
+Team ID, Key ID, or the `.p8` does not match the App ID / Services ID you are
+signing for. The JWT is minted fresh per exchange, so fixing the inputs is
+enough — no restart cache to clear.
+
+</Accordion>
+<Accordion title="invalid_request mentioning response_mode">
+
+Your Services ID must allow the callback you registered. Check the return URLs
+on the Sign in with Apple key configuration.
+
+</Accordion>
+<Accordion title="Callback never fires">
+
+Browsers post to `/auth/oauth/callback/apple`; make sure proxies do not strip
+form bodies. The route accepts POST with
+`application/x-www-form-urlencoded`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [Vault](/docs/elements/vault) — seeding `OAUTH_APPLE_PRIVATE_KEY`
+- [Gate](/docs/elements/gate) — `gate.auth`
+
+## Next
+
+<Cards>
+  <Card title="Google" description="OIDC reference provider." href="/docs/plugins/google" />
+  <Card
+    title="Microsoft"
+    description="Entra tenants and issuer templates."
+    href="/docs/plugins/microsoft"
+  />
+  <Card title="X" description="PKCE public client, never-verified emails." href="/docs/plugins/x" />
+</Cards>

package/site/content/docs/plugins/discord.mdx

@@ -0,0 +1,139 @@
+---
+title: "Discord"
+description: "Official plugin — Discord sign-in where email can be real, verified, or legitimately absent."
+icon: "MessageCircle"
+source: "docs/spec/unified-theory.md"
+---
+
+Discord is OAuth2 with one quirk: `/users/@me` `email` can be **null**
+(phone-only accounts). `oauth()` signs those people in without an email
+instead of failing them.
+
+<Callout title="The one rule">
+  Keep the `email` scope in the request (it is on by default). Without it Discord never reports
+  `verified: true`, and unverified emails cannot claim existing accounts.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create an application
+
+Discord Developer Portal → Applications → **New Application** → OAuth2. Add a
+redirect under OAuth2 → Redirects:
+`https://app.example.com/auth/oauth/callback/discord`.
+
+</Step>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { oauth } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "dev",
+  gate: { auth: {} },
+}).plug(
+  oauth({
+    baseUrl: "https://app.example.com",
+    providers: {
+      discord: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_DISCORD_CLIENT_SECRET=...
+```
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect      | Behavior                                                                            |
+| ----------- | ----------------------------------------------------------------------------------- |
+| Profile     | `GET https://discord.com/api/users/@me` (string `id` is the subject)                |
+| Email       | taken as-is when present; `null` flows through as _no email_                        |
+| Email trust | `verified: true` only; the flag silently going missing keeps the address unverified |
+| Name        | `global_name`, falling back to `username`                                           |
+
+**Consequence:** an integration bug that drops the `verified` field degrades
+to unverified — never to falsely verified. That direction of failure is what
+keeps account takeover off the table.
+
+Default scopes: `identify`, `email`. The authorize URL always carries
+`prompt=consent`.
+
+## Options
+
+| Option                | Type       | Default              | Meaning                     |
+| --------------------- | ---------- | -------------------- | --------------------------- |
+| `enabled`             | `boolean`  | `false`              | Turn the provider on        |
+| `clientId`            | `string`   | Vault/env\*          | `\*OAUTH_DISCORD_CLIENT_ID` |
+| `redirectUri`         | `string`   | `{baseUrl}…/discord` | Exact registered URI        |
+| `scopes`              | `string[]` | driver defaults      | Extra scopes                |
+| `storeProviderTokens` | `boolean`  | `false`              | Keep tokens in Vault        |
+
+## Surfaces
+
+| Flow     | Path                                    |
+| -------- | --------------------------------------- |
+| Start    | `POST /auth/oauth/discord/start`        |
+| Callback | `GET+POST /auth/oauth/callback/discord` |
+| Link     | `POST /auth/oauth/discord/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Users sign in with no email attached">
+
+Phone-only Discord accounts expose `email: null`. The session works; the user
+row simply has no address until they add one at Discord.
+
+</Accordion>
+<Accordion title="invalid_oauth2 error code">
+
+The client secret was rotated in the portal while old codes were in flight.
+Restart the flow — flow rows are single-use and expire after ten minutes.
+
+</Accordion>
+<Accordion title="Email never marked verified">
+
+The app lacks the `email` scope or the user has not confirmed their address at
+Discord. Unverified emails provision new accounts but never take over
+existing ones.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [GitHub](/docs/plugins/github) — primary-email lookup pattern
+- [Vault](/docs/elements/vault) — where secrets live
+
+## Next
+
+<Cards>
+  <Card
+    title="GitHub"
+    description="OAuth2 with verified-email lookup."
+    href="/docs/plugins/github"
+  />
+  <Card title="Facebook" description="Never-verified emails." href="/docs/plugins/facebook" />
+  <Card title="Google" description="OIDC reference provider." href="/docs/plugins/google" />
+</Cards>

package/site/content/docs/plugins/facebook.mdx

@@ -0,0 +1,134 @@
+---
+title: "Facebook"
+description: "Official plugin — Facebook Login via Graph API with conservative email handling."
+icon: "Share2"
+source: "docs/spec/unified-theory.md"
+---
+
+Facebook Login is OAuth2 against the Graph API, and its trust story is the
+simplest one in `oauth()`: the platform offers **no verification signal to
+apps**, so emails from Facebook are treated as unverified — always.
+
+<Callout title="The one rule">
+  Treat every Facebook-provided address as unverified. The flow provisions new accounts with them
+  but refuses to let them claim accounts that already exist.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Create an app
+
+Meta for Developers → **Create App** → _Authentication_. Under Facebook Login
+→ Settings, add `https://app.example.com/auth/oauth/callback/facebook` as a
+Valid OAuth Redirect URI.
+
+</Step>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { oauth } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "dev",
+  gate: { auth: {} },
+}).plug(
+  oauth({
+    baseUrl: "https://app.example.com",
+    providers: {
+      facebook: { enabled: true },
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Set the client secret
+
+```text
+# .env.local
+OAUTH_FACEBOOK_CLIENT_SECRET=...
+```
+
+</Step>
+
+</Steps>
+
+## How identity works
+
+| Aspect         | Behavior                                                      |
+| -------------- | ------------------------------------------------------------- |
+| Authorize      | `www.facebook.com/v21.0/dialog/oauth`                         |
+| Token exchange | `graph.facebook.com/v21.0/oauth/access_token`                 |
+| Profile        | `GET /me?fields=id,name,email` (the `id` is the subject)      |
+| Email          | present when the user has one; phone-only accounts have none  |
+| Email trust    | **always unverified** — no trustworthy provider signal exists |
+
+**Consequence:** an attacker completing Facebook login with _your_ email gets
+`email_in_use`, not your session. This exact scenario is the takeover class
+the trust matrix closes.
+
+Default scopes: `email`, `public_profile`.
+
+## Options
+
+| Option                | Type       | Default               | Meaning                               |
+| --------------------- | ---------- | --------------------- | ------------------------------------- |
+| `enabled`             | `boolean`  | `false`               | Turn the provider on                  |
+| `clientId`            | `string`   | Vault/env\*           | `\*OAUTH_FACEBOOK_CLIENT_ID` (App ID) |
+| `redirectUri`         | `string`   | `{baseUrl}…/facebook` | Exact registered URI                  |
+| `scopes`              | `string[]` | driver defaults       | Extra scopes                          |
+| `storeProviderTokens` | `boolean`  | `false`               | Keep tokens in Vault                  |
+
+## Surfaces
+
+| Flow     | Path                                     |
+| -------- | ---------------------------------------- |
+| Start    | `POST /auth/oauth/facebook/start`        |
+| Callback | `GET+POST /auth/oauth/callback/facebook` |
+| Link     | `POST /auth/oauth/facebook/link`         |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="URL Blocked: redirect_uri">
+
+The URI is not on the Valid OAuth Redirect URIs list, or the app is in
+development mode and the user lacks a role. Byte-exact matching applies.
+
+</Accordion>
+<Accordion title="Sign-in works but there is no email">
+
+The user declined the email permission or has none on file. The flow proceeds
+without an address — same behavior as Discord phone-only accounts.
+
+</Accordion>
+<Accordion title="Error code 190 at exchange">
+
+The app secret was rotated or the code was replayed. Codes are single-use;
+restart from `/start`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [OAuth](/docs/plugins/oauth) — shared flows and security model
+- [X](/docs/plugins/x) — also never-verified emails
+- [Vault](/docs/elements/vault) — where secrets live
+
+## Next
+
+<Cards>
+  <Card title="X" description="PKCE public client." href="/docs/plugins/x" />
+  <Card title="Figma" description="Basic-auth token endpoint." href="/docs/plugins/figma" />
+  <Card title="Discord" description="Nullable emails." href="/docs/plugins/discord" />
+</Cards>