spine-framework 0.4.4 → 0.5.0-rc.5

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

@@ -0,0 +1,114 @@
+---
+title: Add a timer
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/timers.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/migrations/020_schema_reconciliation.sql
+  - .framework/migrations/068_cron_schedule_timer_rpcs.sql
+  - .framework/src/pages/admin/TimerDetailPage.tsx
+---
+
+# Add a timer
+
+## Goal
+
+Create a `public.timers` row that runs a pipeline every
+`config.interval_minutes` via the system cron sweep.
+
+## Prerequisites
+
+- A pipeline to point at ([Add a pipeline](./add-a-pipeline.md)) —
+  `get_due_timers` ignores timers with `pipeline_id` NULL.
+
+## Steps
+
+1. **Create the timer.** Admin UI → **Configs → Timers → New**
+   (`configs/timers/new`), or `POST /api/timers` — `name` and `timer_type`
+   required (`.framework/functions/timers.ts`). Set
+   `pipeline_id` and `config.interval_minutes`:
+
+   ```json
+   {
+     "name": "Hourly sync",
+     "timer_type": "interval",
+     "pipeline_id": "<pipeline-uuid>",
+     "config": { "interval_minutes": 60 }
+   }
+   ```
+
+   `timer_type` is a label (`interval` | `cron` | `once` in the admin
+   detail page, `.framework/src/pages/admin/TimerDetailPage.tsx`) — the
+   only field that actually reschedules is `config.interval_minutes`
+   (see below).
+
+2. **`next_execution` is armed for you.** On create or toggle-on, the API
+   computes `next_execution` from `config.interval_minutes` (or
+   `config.interval_seconds`, seconds ÷ 60); `once` timers arm from an
+   ISO `config.run_at`/`config.schedule`. You may also pass
+   `next_execution` explicitly. If `next_execution` ever ends up NULL on
+   an active timer it cannot fire — `get_due_timers` requires
+   `next_execution IS NOT NULL` — so check it first when a timer never
+   runs.
+
+3. **Understand the clock.** `trigger-scheduler` is the Netlify scheduled
+   function (`* * * * *` in `netlify.toml`); each minute it invokes the
+   `system-cron` handler under the system principal, which calls
+   `get_due_timers(now())`, then `runPipeline(timer.pipeline_id, …)` with a
+   `timer:<id>` machine principal, then `update_timer_after_run`
+   (`.framework/functions/system-cron.ts`).
+
+   **`netlify dev` does not run scheduled functions.** Clockwork only exists
+   on deployed Netlify — locally, `trigger-scheduler` is loaded but never
+   invoked on schedule. To emulate a tick, invoke it manually:
+
+   ```bash
+   curl -X POST http://localhost:8888/.netlify/functions/trigger-scheduler \
+     -H 'x-nf-event: schedule' \
+     -d "{\"next_run\": \"$(date -u +%Y-%m-%dT%H:%M:%S.000Z)\"}"
+   # or: npx netlify functions:invoke trigger-scheduler
+   ```
+
+4. **Rescheduling is automatic — or never.** `update_timer_after_run`
+   stamps `last_execution`, increments `execution_count` /
+   `success_count` / `failure_count`, and sets
+   `next_execution = now() + interval_minutes` when
+   `config.interval_minutes` is a positive number — otherwise `NULL`, so
+   the timer fires once and stops
+   (`.framework/migrations/068_cron_schedule_timer_rpcs.sql`).
+
+## Verify
+
+- `SELECT id, next_execution, last_execution, execution_count FROM timers`
+  shows `next_execution` in the future, then advancing each tick.
+- **Observability → Executions** shows pipeline runs with a
+  `timer:<id>` principal.
+- `timer.execution_count` increments; `success_count` / `failure_count`
+  reflect outcomes.
+
+## Common mistakes
+
+- **`interval_seconds` vs `interval_minutes`.** The admin detail page seeds
+  `config` with `{ "interval_seconds": 3600 }`, but `update_timer_after_run`
+  only reads `config.interval_minutes` — a timer saved with the default
+  config fires once (if `next_execution` was set) and never reschedules.
+- **No `next_execution`.** The API can't set it; timers created through
+  `/api/timers` or the admin UI sit dormant until the column is seeded.
+- **`toggle` is blind.** `?action=toggle` flips `is_active` to its negation
+  with no target-state argument — read the row first.
+- **Cron expressions do nothing.** There is no cron-expression evaluator;
+  `timer_type: "cron"` is only a label — scheduling is interval arithmetic
+  on `next_execution`.
+- **Timer with no `pipeline_id`** — filtered out of `get_due_timers`.
+
+## Reference
+
+- [timers entity page](../timers.md) ·
+  [timers function reference](../reference/functions/timers.md) ·
+  [system-cron reference](../reference/functions/system-cron.md) ·
+  [trigger-scheduler reference](../reference/functions/trigger-scheduler.md)
+- [Automation](../concepts/automation.md) — *Timers and the scheduler*

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)