spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/tasks/add-a-trigger.md

@@ -0,0 +1,106 @@
+---
+title: Add a trigger
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/triggers.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/admin-data.ts
+  - .framework/functions/pipeline-runner-background.ts
+  - .framework/src/pages/admin/TriggerDetailPage.tsx
+---
+
+# Add a trigger
+
+## Goal
+
+Create a `public.triggers` row so a record event (`item_created`,
+`item_updated`, …) dispatches a pipeline execution.
+
+## Prerequisites
+
+- The pipeline the trigger will point at ([Add a pipeline](./add-a-pipeline.md)).
+- `INTERNAL_INVOKE_SECRET` set on the deployed functions — dispatch POSTs to
+  `pipeline-runner-background` with an `X-Internal-Secret` header and logs
+  `cannot dispatch trigger pipeline` (then silently no-ops) when it is
+  unset (`.framework/functions/_shared/trigger-engine.ts`). See
+  [Environment variables](../reference/env-vars.md).
+
+## Steps
+
+1. **Pick the `event_type`.** Snake_case `<entity>_<verb>` — the engine's
+   `EventType` union covers `item`, `account`, `person`, `thread`,
+   `message`, `attachment`, and `link` × `created`/`updated`/`deleted`
+   (`.framework/functions/_shared/trigger-engine.ts`). Use
+   `item_created`, not `item.created` — the admin UI's own placeholder text
+   (`e.g., item.created`) is misleading
+   (`.framework/src/pages/admin/TriggerDetailPage.tsx`).
+
+   Scheduled and webhook entry points are **not** trigger event types —
+   use a [timer](./add-a-timer.md) or an
+   [inbound webhook](./add-a-webhook.md) for those.
+
+2. **Add filter config (optional).** `config.entity_type` scopes the row to
+   one table; `config.type_slug` scopes it to one type (resolved from
+   `type_id` when the record carries only that);
+   `config.filters` supports `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`,
+   `$in`, `$nin`, `$exists` on `data->>'field'` paths; and
+   `config.fire_on_transition` fires only when the record moves *into* a
+   matching state (`.framework/functions/_shared/trigger-engine.ts`).
+
+   ```json
+   {
+     "name": "New ticket",
+     "event_type": "item_created",
+     "pipeline_id": "<pipeline-uuid>",
+     "config": { "entity_type": "items", "type_slug": "ticket" }
+   }
+   ```
+
+3. **Create the trigger.** Admin UI → **Configs → Triggers → New**, or
+   `POST /api/triggers` — `name`, `event_type`, and `pipeline_id` required
+   (`.framework/functions/triggers.ts`).
+
+4. **Keep it enabled.** `is_active: true` (default). Only active triggers
+   are matched on an event; `?action=toggle` flips it
+   (`.framework/functions/triggers.ts`). Deleting a trigger is a soft
+   delete (`is_active = false`) — execution history survives.
+
+## Verify
+
+- Create or update a matching record via `/api/admin-data` — creates and
+  updates call `fireCreateTriggers` / `fireUpdateTriggers` after the write
+  (`.framework/functions/admin-data.ts`).
+- A `pipeline_executions` row appears in `queued`, then `running` /
+  `completed` as `pipeline-runner-background` picks it up — watch
+  **Observability → Executions**.
+- The `record_trigger_fire` RPC bumps `triggers.trigger_count` /
+  `last_triggered`, and `trigger.fired` / `trigger.failed` audit rows land
+  in `public.logs`.
+
+## Common mistakes
+
+- **Dotted event names.** `item.created` matches nothing — event names are
+  `item_created` etc.
+- **Expecting `item_deleted`.** The enum includes it, but the `admin-data`
+  delete path never invokes `fireDeleteTriggers` — only create and update
+  fire (`.framework/functions/admin-data.ts`;
+  `.framework/functions/_shared/trigger-engine.ts`). Use an update
+  (`is_active = false`) if you need delete-like notification.
+- **Missing `INTERNAL_INVOKE_SECRET`.** The trigger inserts the queued
+  execution row, but the dispatch to `pipeline-runner-background` cannot be
+  authenticated, so nothing runs — check function logs for the
+  `INTERNAL_INVOKE_SECRET not set` error.
+- **Filtering on `type_slug` without realizing the resolution.** Records
+  carry `type_id`, not the slug; the engine resolves the slug once per
+  event when any trigger filters on `config.type_slug`
+  (`.framework/functions/_shared/trigger-engine.ts`).
+
+## Reference
+
+- [triggers entity page](../triggers.md) · [Automation](../concepts/automation.md)
+- [trigger-scheduler reference](../reference/functions/trigger-scheduler.md) ·
+  [pipeline-runner-background reference](../reference/functions/pipeline-runner-background.md)
+- [Add a pipeline](./add-a-pipeline.md) · [Add a timer](./add-a-timer.md)

package/.framework/src/instructions/tasks/add-a-type.md

@@ -0,0 +1,151 @@
+---
+title: Add a type
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/types.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/src/pages/admin/TypeDetailPage.tsx
+  - .framework/migrations/015_types_kind_slug_unique.sql
+---
+
+# Add a type
+
+## Goal
+
+Create a `public.types` row whose `design_schema` drives validation,
+permissions, and the generic list/detail UI for a new record shape. Records
+created through `/api/admin-data` stamp this schema onto themselves at write
+time, so a broken schema propagates into every record.
+
+## Prerequisites
+
+- A `system_admin` login or an API key with `*:*` scope — `POST /api/types`
+  throws `System admin required` for anyone else
+  (`.framework/functions/types.ts`).
+- The target `kind` decided up front (`item`, `thread`, `message`, `link`,
+  `attachment`, `watcher`, `person`, `account`). The kind chooses the runtime
+  table and cannot be implied later — see
+  [Runtime records](../concepts/runtime-records.md).
+
+## Steps
+
+1. **Draft the `design_schema`.** Work through the checklist in
+   [Design schema](../concepts/design-schema.md); the field/display enums are
+   in [Design schema reference](../reference/design-schema.md). The schema
+   below is the minimum for the generic renderer:
+
+   ```json
+   {
+     "scope": "account",
+     "fields": {
+       "title":  { "data_type": "text",   "label": "Title",  "required": true, "system": true },
+       "status": { "data_type": "select", "label": "Status", "required": true, "system": true,
+                   "options": ["open", "closed"] }
+     },
+     "views": {
+       "default_list": {
+         "type": "list", "display": "table", "label": "Tickets",
+         "fields": {
+           "title":      { "sortable": true, "display_type": "text" },
+           "status":     { "sortable": true, "display_type": "badge" },
+           "created_at": { "sortable": true, "display_type": "timestamp" }
+         },
+         "default_sort": { "field": "created_at", "direction": "desc" }
+       },
+       "default_detail": {
+         "type": "detail", "label": "Ticket",
+         "sections": [
+           { "title": "Core",
+             "fields": { "title": { "display_type": "input" },
+                         "status": { "display_type": "select" } } }
+         ]
+       }
+     },
+     "record_permissions": {
+       "system_admin": ["create", "read", "update", "delete"],
+       "support":      ["create", "read", "update"]
+     },
+     "functionality": null
+   }
+   ```
+
+   - `fields`: every entry needs `data_type`, `label`, `required`. `select`,
+     `multiselect`, and `radio` need `options` — `generateValidationSchema`
+     derives allowed values from them (`.framework/functions/_shared/schema-utils.ts`).
+   - `record_permissions` keys are `roles.slug` values matched **verbatim** —
+     `system_admin`, not `system-admin`. A misspelled or nonexistent slug
+     silently grants nothing (`.framework/functions/_shared/permissions.ts`).
+   - **Reserved column names.** `items` has real columns `title`,
+     `description`, and `status` — a field with one of those names and
+     `system: true` maps onto the column; the same name with `system: false`
+     lands in `record.data` and list/detail views show the column's value
+     (e.g. lifecycle `active`) instead of yours. Pick `system: true` for
+     these names or rename the field.
+   - `record_permissions` is the **base, most restrictive** grant; add
+     `fields.*.permissions` only to loosen one field or to restrict a
+     `system: true` field — see [Permission model](../concepts/permissions.md).
+   - Generic apps (`renderer: "generic"`) need `views.default_list` and
+     `views.default_detail` referencing real fields with known
+     `display_type` values; custom apps can omit views but still need
+     `fields` + `record_permissions` so `admin-data` can stamp and validate.
+
+2. **Create the type.** Either:
+
+   - Admin UI → **Configs → Types → New** (`configs/types/new`), fill in
+     name, slug, kind, and paste the schema into the Design Schema JSON
+     field — the page POSTs to `/api/types?action=create`
+     (`.framework/src/pages/admin/TypeDetailPage.tsx`).
+   - API: `POST /api/types` with a body containing `name`, `slug`, `kind`,
+     and `design_schema` — all three fields are required
+     (`.framework/functions/types.ts`).
+
+3. **Let the API generate `validation_schema`.** Do not send it yourself —
+   the create handler replaces a missing `validation_schema` with
+   `generateValidationSchema(design_schema)` before insert, and update
+   regenerates it whenever `design_schema` changes
+   (`.framework/functions/types.ts`).
+
+4. **Set the row-level fields.** `ownership` (`system`/`app`/`tenant`),
+   `is_active`, `icon`, `color`, and optional `app_id` are columns on the
+   `types` row, not inside `design_schema`.
+
+## Verify
+
+- `GET /api/types?action=get&slug=<slug>&include_schema=true` returns the row
+  with a non-null `validation_schema`.
+- Create a record: `POST /api/admin-data?action=create` with
+  `{ "entity": "items", "type_slug": "<slug>", "title": "…", "data": {…} }`
+  — the stored record carries the stamped `design_schema`.
+- If the app uses the generic renderer, open its list page — an unknown
+  `display_type` or missing `default_list` view shows up immediately as a
+  broken page.
+
+## Common mistakes
+
+- **Slug collisions.** Slugs must be unique per `kind`
+  (`.framework/migrations/015_types_kind_slug_unique.sql`); create throws
+  `Type with slug '<slug>' already exists for kind '<kind>'`. App-install
+  seeds go further — `conflict: "kind,slug"` makes type slugs effectively
+  global, so prefix app types (`support_ticket`, not `ticket`) — see
+  [Seeds](../reference/seeds.md).
+- **`system-admin` vs `system_admin`.** Seeded role slugs use underscores;
+  `system-admin` grants nothing.
+- **Editing `data_type` on a live field.** Existing records keep their old
+  stored values; the schema change does not migrate data.
+- **Using `generate` to scaffold types.** `npx spine-framework generate`
+  emits a stale legacy schema shape — author via the admin UI or `/api/types`
+  (see [Build your first app — Gaps](../guide/04-first-app.md)).
+
+## Reference
+
+- [Design schema (concept)](../concepts/design-schema.md) ·
+  [Design schema reference](../reference/design-schema.md)
+- [Permission model](../concepts/permissions.md) ·
+  [Runtime records](../concepts/runtime-records.md)
+- [types entity page](../types.md) ·
+  [types function reference](../reference/functions/types.md) ·
+  [admin-data function reference](../reference/functions/admin-data.md)

package/.framework/src/instructions/tasks/add-a-webhook.md

@@ -0,0 +1,108 @@
+---
+title: Add a webhook
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integration-routes.ts
+  - .framework/functions/_shared/webhook-registry.ts
+  - .framework/functions/_shared/webhook-registration.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/adapters/generic-webhook-inbound.ts
+  - .framework/migrations/004_core_rpc_and_broker.sql
+---
+
+# Add a webhook
+
+Two directions, two different mechanisms: **inbound** webhooks arrive at the
+`integration-routes` function and are normalized by a registry adapter into
+`items` records; **outbound** webhooks leave through
+`integration-outbound` (usually from a pipeline stage). See
+[Integrations and webhooks](../concepts/integrations-and-webhooks.md).
+
+## Goal — inbound
+
+Receive an external POST and turn it into a record.
+
+### Steps
+
+1. **Create the integration** ([Add an integration](./add-an-integration.md))
+   the webhook posts against. Set `config.event_path` if the event name
+   lives inside the payload (`"type"` or `"data.event"`), and
+   `config.handler_name` to force an adapter — otherwise the adapter name
+   falls back to `integration.provider`, then `generic-webhook`
+   (`.framework/functions/integration-routes.ts`).
+
+2. **Mint an API key for the sender.** `integration-routes` requires a
+   machine principal (`x-api-key`), and the key is authorized per
+   `account_id` — optionally pinned to `integration_id` and `app_id`
+   (`.framework/functions/integration-routes.ts`). See
+   [Auth and API keys](../concepts/auth-and-api-keys.md).
+
+3. **Register or reuse an adapter.** `webhook_handlers` rows map a handler
+   name → `function_name`; lookup prefers the app/account-scoped row and
+   falls back to a global one, then `loadHandler` dynamically imports the
+   module and takes `adapt` → `handler` → `default`
+   (`.framework/functions/_shared/webhook-registry.ts`). Migration
+   004 seeds a global `generic-webhook` handler bound to
+   `adapters/generic-webhook-inbound`, which stores the raw payload as a
+   `webhook_event` item (`.framework/migrations/004_core_rpc_and_broker.sql`).
+
+4. **Adapter contract.** The adapter receives `(payload, ctx)` where `ctx`
+   carries `integration`, `apiKey`, `accountId`, `appId`, `event`,
+   `headers`, and a `logger`; it returns
+   `{ type_slug, data, title?, status?, thread?, links?, external_id?, error?, retryable? }`.
+   A truthy `error` marks the delivery `failed` (or `pending` when
+   `retryable`); a result with `type_slug` is created through `admin-data`
+   as an `items` record (`.framework/functions/integration-routes.ts`).
+
+5. **Post to it.** `POST /api/integration-routes?slug=<integration-slug>`
+   with `x-api-key: <key>` and the payload body. The event name comes from
+   the `x-event-type` header first, then `config.event_path`
+   (`.framework/functions/integration-routes.ts`).
+
+## Goal — outbound
+
+Call an external URL from a pipeline.
+
+### Steps
+
+1. Add an `http_request` stage (arbitrary HTTP) or a webhook action whose
+   `handler_module: 'webhook'` routes to `executeWebhookHandler` — the
+   webhook URL comes from the action's config
+   (`.framework/functions/_shared/pipeline-runner.ts`).
+2. For credentialed or retried sends, go through `integration-outbound`
+   instead — see [Add an integration](./add-an-integration.md). Deliveries
+   are tracked in `webhook_deliveries` with exponential backoff.
+
+## Verify
+
+- Inbound: `webhook_deliveries` shows `direction: 'inbound'` rows moving
+  `pending → delivered`; the created item appears via `/api/admin-data`.
+- Outbound: `webhook_deliveries` shows `direction: 'outbound'` rows with
+  `response_status`.
+
+## Common mistakes
+
+- **Human JWT instead of `x-api-key`** — the route requires a machine
+  principal and returns `Machine principal required` (401).
+- **API key pinned to a different integration/app** — `403 API key is not
+  authorized`.
+- **`x-event-type` vs `event_path` confusion** — the header wins; if the
+  sender can't set headers, put the event inside the payload and set
+  `config.event_path`.
+- **Unregistered handler name** — `config.handler_name` (or `provider`)
+  that has no `webhook_handlers` row and no global fallback returns
+  `Handler not found` (404).
+- **Registering handlers under the wrong scope** — an app- or
+  account-scoped `webhook_handlers` row shadows the global fallback for
+  that scope only.
+
+## Reference
+
+- [integration-routes reference](../reference/functions/integration-routes.md) ·
+  [integration-outbound reference](../reference/functions/integration-outbound.md) ·
+  [deliveries entity page](../deliveries.md)
+- [Integrations and webhooks](../concepts/integrations-and-webhooks.md) ·
+  [Add a pipeline](./add-a-pipeline.md)

package/.framework/src/instructions/tasks/add-an-ai-agent.md

@@ -0,0 +1,108 @@
+---
+title: Add an AI agent
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/ai-agents.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/functions/_shared/llm.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/prompt-configs.ts
+  - .framework/functions/integration-outbound.ts
+---
+
+# Add an AI agent
+
+## Goal
+
+Create an `ai_agents` row plus a `prompt_configs` row, then run it either
+conversationally (`ai-agents?action=run` on a thread) or inside a pipeline
+(`agent_inference` stage). See
+[AI agents, prompt configs, and embeddings](../concepts/ai-and-prompts.md).
+
+## Steps
+
+1. **Create the prompt config.** Admin UI → **Configs → Prompts → New**, or
+   `POST /api/prompt-configs`. Key fields: `system_prompt`,
+   `context_template` (substitutes `{{user_message}}` and
+   `{{conversation_history}}` only), `model` (default `gpt-4o`),
+   `temperature` (default `0.7`), `max_tokens` (default `4000`),
+   `is_multi_turn`, `max_history_messages` (default `20`)
+   (`.framework/functions/prompt-configs.ts`).
+
+2. **Create the agent.** Admin UI → **Configs → AI Agents → New**, or
+   `POST /api/ai-agents` — `name` and `agent_type` required; optional
+   `model_config`, `system_prompt`, `tools`, `capabilities`,
+   `constraints`, `metadata` (`.framework/functions/ai-agents.ts`).
+   Link the prompt config via `metadata.default_prompt_config_id`.
+
+3. **Configure the LLM integration.** Inference routes through
+   `integration-outbound` against the integration slug `openai` with
+   `credential_field: 'api_token'` (`.framework/functions/_shared/llm.ts`).
+   Migration 004 seeds `openai` with
+   `api_token: { source: 'env_var', value: 'OPENAI_API_KEY' }` — set that env
+   var or update the credential. Without it the runner returns a
+   `[Mock Response]` string instead of calling the model
+   (`.framework/functions/_shared/agent-runner.ts`).
+
+4. **Conversational path — `ai-agents?action=run`.**
+   `POST /api/ai-agents?action=run` with `{ thread_id, user_message, mode }`;
+   `mode` is `step` | `complete` (default) | `episode`. The runner resolves
+   the agent from `thread.data.agent_id` → `design_schema.default_agent_id`,
+   and the prompt config from `thread.data.prompt_config_id` →
+   `agent.metadata.default_prompt_config_id` — both must be `is_active`
+   (`.framework/functions/_shared/agent-runner.ts`). A
+   prompt-injection preflight reads `config.security.prompt_injection`
+   (`off` | `flag` | `block`) on the agent
+   (`.framework/functions/ai-agents.ts`).
+
+5. **Pipeline path — `agent_inference` stage.** Add a stage with
+   `stage_type: 'agent_inference'` and `config.context` (required;
+   `{{trigger.*}}`/`{{record.*}}` templates resolve). With a
+   `config.webhook_url` the stage POSTs `{ context, model, temperature,
+   max_tokens }` to that URL via the `generic-http` integration; without
+   one it returns a mock response —
+   `[Mock Response] Received N chars of context`
+   (`.framework/functions/_shared/pipeline-runner.ts`).
+
+## Verify
+
+- `POST /api/ai-agents?action=run` on a thread whose `data.agent_id` points
+  at the agent — returns a completion (or the mock string when the OpenAI
+  credential is missing).
+- `agent_step` rate-limit debits and injection audits appear in
+  `public.logs`.
+- The `agent_inference` stage output appears in the execution's stage
+  results (**Observability → Executions**).
+
+## Common mistakes
+
+- **`threads.target_type` is `NOT NULL`.** A chat thread must be bound to a
+  target record — there is no unbound "conversation" row. Point it at
+  something stable such as `target_type: 'account'` +
+  `target_id: <account id>` and keep `data.agent_id` /
+  `data.prompt_config_id` on the thread.
+- **No `default_prompt_config_id` on the agent and no
+  `prompt_config_id` on the thread** — the run has no prompt config to
+  assemble from; always set the agent fallback.
+- **Missing `OPENAI_API_KEY` / unconfigured `openai` integration** — you
+  get a mock response, not an error; check the reply text for
+  `[Mock Response]`.
+- **`agent_inference` with no `webhook_url`** — returns a mock. This stage
+  is an HTTP bridge, not the in-process `runAgent` path.
+- **Agent or prompt config `is_active: false`** — resolution fails before
+  inference.
+- **`context_template` with unsupported placeholders** — only
+  `{{user_message}}` and `{{conversation_history}}` substitute; anything
+  else stays literal (`.framework/functions/_shared/agent-runner.ts`).
+
+## Reference
+
+- [ai-agents entity page](../ai-agents.md) ·
+  [ai-agents function reference](../reference/functions/ai-agents.md) ·
+  [prompt-configs function reference](../reference/functions/prompt-configs.md) ·
+  [prompts entity page](../prompts.md)
+- [AI agents, prompt configs, and embeddings](../concepts/ai-and-prompts.md) ·
+  [Add a pipeline](./add-a-pipeline.md) · [Add an integration](./add-an-integration.md)

package/.framework/src/instructions/tasks/add-an-integration.md

@@ -0,0 +1,124 @@
+---
+title: Add an integration
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integrations.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/_shared/resolve-credentials.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/004_core_rpc_and_broker.sql
+---
+
+# Add an integration
+
+## Goal
+
+Create a `public.integrations` row — the config + credentials handle for
+outbound HTTP calls (`integration-outbound`) and inbound webhook routing
+(`integration-routes`). See
+[Integrations and webhooks](../concepts/integrations-and-webhooks.md) for
+the full model.
+
+## Prerequisites
+
+- A `system_admin` login — the integrations function enforces it
+  (`.framework/functions/integrations.ts`, `isSystemAdmin` signal).
+
+## Steps
+
+1. **Choose the integration shape.**
+
+   - `integration_type`: semantic category — `webhook`, `oauth`, `api`,
+     `scheduled_sync` (column comment,
+     `.framework/migrations/004_core_rpc_and_broker.sql`).
+   - `provider`: the vendor name — `stripe`, `openai`, `generic`, …
+     (used as the fallback inbound adapter name).
+   - `slug`: unique per `(app_id, account_id)` —
+     `integrations_app_account_slug_key`
+     (`.framework/migrations/004_core_rpc_and_broker.sql`).
+
+2. **Configure `config` and `credentials`.**
+
+   - `config.outbound_adapter` selects the adapter module for outbound
+     calls — built-ins: `adapters/openai-outbound`,
+     `adapters/generic-webhook-outbound`, `adapters/resend-outbound`
+     (`.framework/functions/integration-outbound.ts`). `action_config.adapter`
+     can override it per call.
+   - `credentials` is a map `{ field: { source, value } }`:
+     `source: "value"` stores a literal secret; `source: "env_var"` resolves
+     `value` as a `process.env` name server-side at call time
+     (`.framework/functions/_shared/resolve-credentials.ts`).
+
+   ```json
+   {
+     "slug": "acme-api", "name": "Acme API",
+     "integration_type": "api", "provider": "acme",
+     "config": {
+       "base_url": "https://api.acme.test",
+       "outbound_adapter": "adapters/generic-webhook-outbound"
+     },
+     "credentials": {
+       "api_token": { "source": "env_var", "value": "ACME_API_TOKEN" }
+     }
+   }
+   ```
+
+   `is_configured` is recomputed on every save — `true` only when every
+   credential entry is present and non-empty
+   (`.framework/functions/integrations.ts`).
+
+3. **Create the integration.** Admin UI → **Configs → Integrations → New**,
+   or `POST /api/integrations` — `name`, `integration_type`, and `provider`
+   required (`.framework/functions/integrations.ts`).
+
+4. **Call it outbound.** `POST /api/integration-outbound` (or a pipeline
+   `http_request`/webhook stage) with `{ integration_slug, action_config }`.
+   `action_config` carries `endpoint`/`url`, `body`, `credential_field`
+   (default `api_token`), `action_slug`, `max_attempts`, and optional
+   `adapter` (`.framework/functions/integration-outbound.ts`).
+   Deliveries land in `webhook_deliveries` with retry bookkeeping — see
+   [integration-outbound reference](../reference/functions/integration-outbound.md).
+
+5. **For inbound**, point senders at `integration-routes` and pick an
+   adapter — see [Add a webhook](./add-a-webhook.md).
+
+## Verify
+
+- `GET /api/integrations?action=list` — `is_configured: true` once every
+  credential resolves.
+- A `webhook_deliveries` row is written per outbound call with
+  `response_status` and retry fields.
+
+## Common mistakes
+
+- **An empty or absent credential means "no auth", not an error.**
+  `execute` skips resolution for an absent entry or an empty
+  `source: "value"` literal and the call goes out without a credential —
+  the stock `generic-http` seed (`{"api_token":{"source":"value","value":""}}`,
+  `.framework/migrations/004_core_rpc_and_broker.sql`) therefore works
+  unauthenticated out of the box. Whether a credential is required is the
+  *adapter's* call: `generic-webhook-outbound` only attaches
+  `Authorization: Bearer` when a credential resolved, while
+  `openai-outbound`/`resend-outbound` throw in `buildRequest`. What still
+  fails hard: an `env_var` entry naming an unset variable
+  (`credential_env_missing`).
+- **Expecting credentials in reads.** Integrations are a protected
+  second-surface table — non-system-admin/machine reads are sanitized to
+  minimal fields; secrets are only resolved server-side
+  (`.framework/functions/_shared/permissions.ts`).
+- **`env_var` pointing at a missing env** — `resolveCredential` throws
+  before the request is sent and emits `integration.credential_*` audit
+  rows.
+- **Slug not unique within `(app_id, account_id)`** — the DB unique
+  constraint rejects it; account-scoped and global rows share the key.
+
+## Reference
+
+- [integrations entity page](../integrations.md) ·
+  [integrations function reference](../reference/functions/integrations.md) ·
+  [integration-outbound reference](../reference/functions/integration-outbound.md) ·
+  [integration-routes reference](../reference/functions/integration-routes.md)
+- [Integrations and webhooks](../concepts/integrations-and-webhooks.md)