spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/src/instructions/reference/functions/admin-data.md

@@ -0,0 +1,195 @@
+---
+title: admin-data
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/access.ts
+  - .framework/functions/_shared/security.ts
+  - .framework/public/_redirects
+---
+
+# admin-data
+
+## What it does
+
+`admin-data` is the generic CRUD endpoint for Spine's runtime and config
+tables. One function exposes list, get, stats, create, update, and remove
+across a fixed allowlist of entities, with record-permission evaluation,
+field-level sanitization, type-schema stamping, and trigger firing built in.
+Custom apps are expected to use this endpoint for all runtime-record CRUD
+rather than wrapping it.
+
+## Route and methods
+
+`/.netlify/functions/admin-data`, reachable publicly as `/api/admin-data`
+(`/api/*` is redirected to `/.netlify/functions/:splat` in
+`.framework/public/_redirects`).
+
+Dispatch is by `?action=` plus HTTP method (`.framework/functions/admin-data.ts`
+handler):
+
+| Call | Action |
+|---|---|
+| `GET /api/admin-data?action=list&entity=…` | `list` |
+| `GET /api/admin-data?action=get&entity=…&id=…` | `get` |
+| `GET /api/admin-data?action=stats&entity=…` | `stats` |
+| `POST /api/admin-data?action=create` | `create` |
+| `PATCH /api/admin-data?action=update&entity=…&id=…` | `update` |
+| `DELETE /api/admin-data?action=remove&entity=…&id=…` | `remove` |
+
+Without a recognized `action` (absent or unmatched), the HTTP method alone
+dispatches: `GET` → `get` when `id` is present else `list`, `POST` →
+`create`, `PATCH` → `update`, `DELETE` → `remove`. A `?method=` query
+parameter overrides the HTTP method for dispatch (the middleware copies
+`event.httpMethod` into `query.method` only when the query did not set
+it). A matched action with the wrong method (e.g. `action=list` on `POST`)
+falls through to `Invalid action or method`.
+
+## Authentication
+
+Standard `createHandler` authentication: `x-api-key` (machine), internal
+invoke secret (system), or `Authorization: Bearer <jwt>` (human). Anonymous
+requests are rejected with 401 before the handler runs.
+
+- Humans query through a JWT-scoped client (`ctx.db`), so row-level security
+  applies. Machines, anonymous, and system principals get the service-role
+  client — endpoint-level checks carry the weight.
+- `list` switches to `adminDb` when `principal.isInternal` or the principal
+  is a system admin; otherwise it uses `ctx.db`.
+- `create` calls `resolveFirstSurfacePermissions(personId, accountId,
+  typeSlug, 'create', designSchema)` — a machine whose scopes contain `*:*`
+  bypasses (`isMachineGlobal`); a `*:*` machine also resolves as
+  `system_admin`.
+- `update` runs `validateUpdatePermissions` and lets system admins through
+  regardless of the result.
+- `remove` calls `resolveFirstSurfacePermissions(..., 'delete',
+  existing.design_schema)` with a system-admin bypass.
+- Non-internal audiences never see `visibility: 'internal'` threads, and
+  internal messages on external threads are projected to label-only
+  skeletons via `projectMessageForCustomer`.
+
+## Request contract
+
+`entity` is required on every call and must be one of `VALID_ENTITIES`:
+`accounts`, `people`, `items`, `threads`, `messages`, `links`,
+`attachments`, `watchers`, `item_progress`, `logs`, `test_runs`,
+`observability`, `test_cases`, `types`, `link_types`, `ai_agents`,
+`prompt_configs`.
+
+**list** (query params): `entity`, `search` (ILIKE against a per-entity
+field — e.g. `title` for items, `full_name` for people, `message` for
+logs), `sort_field` (default `created_at`), `sort_direction` (`desc`
+default), `limit` (default 50), `offset` (default 0), `type_slug`,
+`type_slugs` (comma-separated, resolved through `ENTITY_TO_KIND` to
+`type_id` filters), `view`, `flag_only` / `exclude_flag` (filter on
+`data->><flag>` for `items`, `threads`, `messages`, `links`, `attachments`,
+`watchers`). Every other query parameter becomes an `.eq(key, value)`
+filter, with boolean coercion for `is_active`, `is_verified`, `is_primary`.
+Soft-deleted rows are hidden by default — pass `is_active=false` or
+`include_inactive=true` to include them.
+
+**get** (query params): `entity`, `id`, `view`, `lineage` — for `items`,
+parent/child lineage is attached unless `lineage=0`.
+
+**stats** (query params): `entity` only.
+
+**create** (body): `entity` (or `?entity=`), `type_slug` or `type_id` —
+required for every non-raw entity; `account_id` (optional override);
+arbitrary record fields. `design_schema`, `validation_schema`, and `id` in
+the body are stripped. `thread_id`, `target_id`, or `parent_id` in the body
+pull account and `scope` from the parent record.
+
+**update** (query `entity` + `id`; body): record fields; `design_schema`,
+`validation_schema`, `type_id`, `type_slug`, `id`, `entity` are stripped.
+`account_id` is honored only for `entity=people`.
+
+**remove** (query params): `entity`, `id`, `soft` (default `'true'`).
+
+## Response contract
+
+All responses use the middleware envelope:
+`{ "data": <result>, "error": null, "meta": { "requestId", "duration" } }`
+with HTTP 200. Errors return `{ "data": null, "error": "<message>" }` with
+HTTP `err.statusCode || 500`.
+
+- `list` → array of sanitized records; when both `view` and `type_slug`
+  are given and the type resolves, `{ data, schema, view }` (schema = the
+  type's `design_schema`, `view` = `schema.views[view]` or `null`). The
+  exact-count probe runs but the count is not returned.
+- `get` → one sanitized record; `items` records additionally carry
+  `parents`, `children`, and `type_slug` fields from
+  `design_schema.functionality.lineage`. With `view`, returns
+  `{ data, schema, view }`.
+- `stats` → `{ entity, count }`.
+- `create` / `update` → the sanitized row.
+- `remove` → `{ deleted: true, soft: true, data }` on soft delete, or
+  `{ deleted: true, soft: false }` on hard delete.
+
+## Side effects
+
+- Writes to the target table. On create, `design_schema` and
+  `validation_schema` are stamped onto the record from the resolved type
+  (missing `record_permissions` defaults to `PERMISSIONS_ALL` — all
+  actions for everyone), plus `created_by`, `created_at`, `updated_at`,
+  and `account_id` (except `accounts`, which gets `parent_id` instead).
+  `types` and `link_types` skip `created_by`/`updated_by` (`UNAUDITED_ENTITIES`).
+- `scope: 'platform'` schemas force `account_id` to the `spine-system`
+  account; a `thread_id`/`target_id`/`parent_id` parent overrides both
+  account and scope.
+- `fireCreateTriggers` runs after every create (including raw entities) and
+  `fireUpdateTriggers` after every update; trigger errors are logged, not
+  raised. **`fireDeleteTriggers` is imported but never called** — removing
+  a record fires no triggers.
+- `logs`, `test_runs`, `observability`, `test_cases` (`RAW_ENTITIES`)
+  bypass type resolution entirely: create inserts a fixed column whitelist
+  (e.g. `level`+`message` required for `logs`, `suite` for `test_runs`,
+  `metric_name`+`metric_value` for `observability`, `slug`+`name` for
+  `test_cases`) and update skips the `updated_by`/`updated_at` stamps.
+- `checkTypeSlugRateLimit` enforces the app's `rate_limits.<type_slug>_create`
+  policies on create.
+- Every action is wrapped in `withAdminLogging`, which writes
+  admin-operation log rows (entity, action, method, duration, row count).
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| No/invalid `entity` | 400 (create) / 500 (others) | `Valid entity parameter is required` |
+| Missing `id` on get/update/remove | 500 | `ID parameter is required` / `ID is required for update|delete` |
+| Missing type on create | 400 | `type_id or type_slug is required — every runtime record must reference a type` |
+| Bad `type_id` / inactive type | 500 | `type_id not found: …` / `type_id references an inactive type: …` |
+| `type_slug` on an unmappable entity | 400 | `type_slug is not supported for entity: …` |
+| Missing parent | 403 | `Parent record not found or not accessible` |
+| Permission denied | 403 | `Insufficient permissions to create|update|delete this record` |
+| Record missing or RLS-hidden | 500 | `Record not found or access denied` |
+| Bad flag name | 400 | `Invalid flag field name` |
+| Unknown action/method | 500 | `Invalid action or method` |
+
+## Agent notes
+
+- Always pass `type_slug` (not `type_id`) when creating runtime records —
+  the endpoint resolves it per `kind` via `ENTITY_TO_KIND`
+  (`items`→`item`, `threads`→`thread`, `messages`→`message`, `links`→`link`,
+  `attachments`→`attachment`, `watchers`→`watcher`, `accounts`→`account`,
+  `people`→`person`, `item_progress`→`item_progress`).
+- Soft delete is the default and only applies to `accounts`, `people`,
+  `items`, `threads`, `messages`, `watchers`, `item_progress`,
+  `test_cases` — it sets `is_active=false`. Everything else hard-deletes
+  even without `soft=false`; pass `soft=false` explicitly when you mean it.
+- Delete triggers do not exist in practice: `remove` never calls
+  `fireDeleteTriggers`, so automations keyed on delete events will not run.
+- `?id=` is mirrored into the JSON body by the middleware before the
+  handler runs.
+- Record reads are sanitized per principal: second/third-surface tables and
+  field-level `permissions` in `design_schema` shape what comes back, and a
+  principal with no account context gets only `id`/`created_at`/`updated_at`.
+- A machine API key without `*:*` scope cannot create (the permission
+  lookup is by `people.id`, which machine keys don't have) — use `*:*`
+  keys for server-side writes, or a human JWT.
+- `update` does not re-stamp `design_schema`; changing a record's type
+  is not possible through this endpoint (`type_id` is stripped).

package/.framework/src/instructions/reference/functions/admin-funnel.md

@@ -0,0 +1,90 @@
+---
+title: admin-funnel
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-funnel.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/funnel.ts
+---
+
+# admin-funnel
+
+## What it does
+
+Computes anonymous-visitor → identified-user → installed-instance
+conversion metrics for the platform funnel. It reads `items` rows under
+three app-seeded item types — `funnel_signal`, `anonymous_session`, and
+`spine_instance` — and returns counts, conversion rates, and a
+stage distribution over the last 30 days.
+
+This is framework-internal telemetry for the platform operator (growth
+and install funnel for Spine itself), not per-customer app analytics.
+
+## Route and methods
+
+**None — this file exports no `handler`.** It exports a single
+`createHandler`-wrapped const, `metrics`, which nothing else imports or
+dispatches. As shipped there is no HTTP entrypoint: the file is deployed
+to the functions directory by the assembly script like every other
+`.framework/functions` file, but Netlify has no `handler` export to
+invoke. Treat it as a dormant module pending a dispatch handler (or a
+wiring bug); do not cite it as a live endpoint.
+
+## Authentication
+
+If `metrics` were wired: `createHandler` requires any non-anonymous
+principal — no role check inside the function. All queries run on
+`adminDb` across **all accounts** (see Agent notes).
+
+## Request contract
+
+`metrics(ctx, body)` takes no parameters — the 30-day window is hardcoded.
+
+## Response contract
+
+`{ anonymous_visitors, identified_users, installed_instances,
+conversion_rates: { anonymous_to_identified, identified_to_installed },
+stage_distribution: [{ stage, count, percentage }] }`
+
+- `anonymous_visitors` — `anonymous_session` items in the last 30 days
+  whose `data->lifecycle->>stitched_to_account_id` is null.
+- `identified_users` — distinct `account_id`s on `funnel_signal` items in
+  the last 30 days.
+- `installed_instances` — `spine_instance` items with a non-null
+  `data->>claimed_by_person_id` (all time).
+- `stage_distribution` — counts of `funnel_signal.data->>stage` over the
+  last 30 days, only counting rows that have an `account_id`.
+
+## Side effects
+
+None — read-only aggregation.
+
+## Errors
+
+No explicit error paths. Missing signal types are expected on a clean
+install (the types are seeded by installed apps): when none of the three
+type slugs resolves, `metrics` returns a zeroed payload instead of
+failing. Database errors would surface as thrown errors through
+`createHandler`'s 500 path.
+
+## Agent notes
+
+- **Verify before use.** The missing `handler` export means there is no
+  routed endpoint; check the current tree before assuming
+  `GET /api/admin-funnel` does anything.
+- **Unscoped platform-wide reads.** If wired as-is, every query runs on
+  `adminDb` with no `account_id` filter and no `isSystemAdmin` gate — any
+  authenticated principal would see cross-account funnel data. A
+  `system_admin` check belongs in any dispatch handler that exposes it.
+- Signal data is written elsewhere — `emitSignal` in
+  `.framework/functions/_shared/funnel.ts` inserts typed signal items
+  (`funnel_signal` among them) and fires `item_created` triggers; these
+  admin modules only read the results.
+- The `funnel_signal_use` type seed exists in the framework
+  (`.framework/seeds/types/funnel_signal_use.json`); the
+  `funnel_signal`/`anonymous_session`/`spine_instance` slugs the queries
+  look for are seeded by installed apps, hence the degrade-to-zeros
+  behavior.

package/.framework/src/instructions/reference/functions/admin-install-funnel.md

@@ -0,0 +1,107 @@
+---
+title: admin-install-funnel
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-install-funnel.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/funnel.ts
+---
+
+# admin-install-funnel
+
+## What it does
+
+Install-funnel analytics for the platform operator: download/install/
+first-use/claimed counts, per-day install trends over 30 days, recent
+install records with contact and account joins, a version breakdown, and
+a full export of install-instance records. All data comes from `items`
+rows under the `funnel_signal` type where `data->>source = 'inst'`, plus
+`spine_instance` rows for the version split.
+
+Framework-internal telemetry about Spine installations (serials, app
+versions, environments), not customer app data.
+
+## Route and methods
+
+**None — this file exports no `handler`.** It exports two
+`createHandler`-wrapped consts, `metrics` and `exportData`, which nothing
+imports or dispatches. As shipped there is no HTTP entrypoint; treat it
+as a dormant module pending a dispatch handler (or a wiring bug), not a
+live endpoint.
+
+## Authentication
+
+If wired: `createHandler` requires any non-anonymous principal — no role
+check inside either export. All queries run on `adminDb` across **all
+accounts** (see Agent notes).
+
+## Request contract
+
+Neither export reads parameters — `metrics` uses fixed windows and
+`exportData` returns the full matching set.
+
+## Response contract
+
+`metrics` →
+
+```json
+{
+  "total_downloads": 0,
+  "unique_installers": 0,
+  "active_instances": 0,
+  "conversion_funnel": { "downloads": 0, "installations": 0, "first_use": 0, "claimed": 0 },
+  "install_trends": [{ "date": "YYYY-MM-DD", "downloads": 0, "installations": 0 }],
+  "recent_installs": [{ "id": "…", "serial": "…", "app_version": "…", "environment": "…",
+                        "first_seen_at": "…", "last_signal_at": "…",
+                        "claimed_by": "…", "claimed_at": "…",
+                        "account_name": "…", "person_email": "…" }],
+  "top_versions": [{ "version": "…", "count": 0, "percentage": 0 }]
+}
+```
+
+Field semantics:
+
+- `total_downloads` / `installations` / `first_use` — `funnel_signal`
+  rows with `action_type` `download` / `install` / `first_command`.
+- `unique_installers` — distinct `data->>serial` values.
+- `active_instances` — serialized signals seen in the last 7 days.
+- `claimed` — signals with non-null `data->>claimed_by_person_id`.
+- `install_trends` — 30 daily buckets of download + install counts.
+- `recent_installs` — latest 20 serialized signals joined to
+  `people(email)` and `accounts(name)`.
+- `top_versions` — up to 10 versions by `spine_instance` count share.
+
+`exportData` → `{ instances, exported_at, total_count }` — every
+`funnel_signal` row with `source='inst'` and a serial, full `data` bag,
+`account_id`, and the same people/accounts joins, newest first.
+
+## Side effects
+
+None — read-only.
+
+## Errors
+
+No explicit error paths. When the `funnel_signal` type is absent
+(app-seeded; missing on a clean install) `metrics` returns a zeroed
+payload and `exportData` returns `{ instances: [], …, total_count: 0 }`.
+The 30-day trend loop issues two count queries per day (60 sequential
+queries) — slow but not an error.
+
+## Agent notes
+
+- **Verify before use** — no `handler` export means no routed endpoint;
+  `?action=export`-style dispatch does not exist in the file.
+- **Platform-wide PII.** `exportData` and the `recent_installs` join
+  return `people.email` and `accounts.name` across all accounts via
+  `adminDb`, gated only by authentication if this is ever wired. Any
+  dispatch handler added later must gate on `system_admin` (or narrower)
+  before exposing these exports.
+- The daily-trend loop is 60 round trips per call — do not put it on a
+  hot path; if the endpoint is wired for real use, fold the loop into a
+  single grouped query or RPC.
+- `serial` is the installer-instance identity; `claimed_by_person_id`
+  links an install to a registered person — that join is what makes the
+  export PII-bearing.

package/.framework/src/instructions/reference/functions/admin-signals.md

@@ -0,0 +1,102 @@
+---
+title: admin-signals
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/admin-signals.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/funnel.ts
+---
+
+# admin-signals
+
+## What it does
+
+Two read surfaces over `funnel_signal` items for the platform operator:
+`metrics` aggregates signal totals (all-time, today, this week), a
+conversion rate from high-value signals, top sources, and the 20 most
+recent signals; `audit` lists individual signal records with filters,
+pagination, attribution fields (UTM/referrer/anonymous identity), and an
+unpaginated export mode.
+
+Signals record product-journey events (`action_type`, `stage`, `source`,
+`rating`) — framework-internal telemetry for the platform, not customer
+app analytics.
+
+## Route and methods
+
+**None — this file exports no `handler`.** It exports `metrics` and
+`audit`, both `createHandler`-wrapped, which nothing imports or
+dispatches. As shipped there is no HTTP entrypoint; treat it as a dormant
+module pending a dispatch handler, not a live endpoint.
+
+## Authentication
+
+If wired: `createHandler` requires any non-anonymous principal — no role
+check in either export. All queries run on `adminDb` across **all
+accounts** (see Agent notes).
+
+## Request contract
+
+`metrics` — no parameters; windows are hardcoded (today, trailing 7
+days).
+
+`audit` — query parameters:
+
+| Param | Effect |
+|---|---|
+| `page` (default 1), `limit` (default 50) | Pagination (ignored in export mode) |
+| `date_from`, `date_to` | `created_at` bounds |
+| `source`, `stage`, `action_type` | Exact match on `data->>` fields |
+| `min_rating` | `data->>rating >= value` |
+| `account_id` | Caller-supplied account filter |
+| `search` | OR-match on `accounts.name`, `people.email`, `data->attribution->>first_touch_referrer_domain` (ILIKE) |
+| `export` (any value) | Returns the full formatted array with no range limit |
+
+## Response contract
+
+`metrics` → `{ total_signals, signals_today, signals_this_week,
+conversion_rate, top_sources: [{source, count}], recent_signals: [{id,
+action_type, source, stage, created_at, account_name, rating}] }`.
+`conversion_rate` is the share of this week's signals with
+`data->>rating >= '4'` — a "high-value signal" rate, not a funnel
+conversion.
+
+`audit` → `{ signals, total, page, limit }`, or in export mode the bare
+formatted array. Each signal row: `{ id, action_type, action_value,
+stage, source, created_at, account_name, person_email, anonymous_id,
+session_id, rating, raw_score, referrer_domain, utm_source, utm_medium,
+utm_campaign }` — joined to `people(email)` and `accounts(name)`, with
+identity fields from `data->identity` and attribution from
+`data->attribution`.
+
+## Side effects
+
+None — read-only.
+
+## Errors
+
+- `Failed to fetch signals: <message>` — the one thrown error, on query
+  failure inside `audit`.
+- Missing `funnel_signal` type (app-seeded; absent on clean installs)
+  degrades gracefully: `metrics` returns zeroed metrics, `audit` returns
+  an empty page or `[]` in export mode.
+
+## Agent notes
+
+- **Verify before use** — no `handler` export means no routed endpoint.
+- **Cross-account PII, caller-steered.** `audit` accepts an arbitrary
+  `account_id` filter and returns `people.email`, `accounts.name`,
+  anonymous IDs, session IDs, and UTM attribution across all accounts via
+  `adminDb`. If a dispatch handler is ever added, it needs a
+  `system_admin` gate before this surface is exposed.
+- `export` mode drops the range limit — it returns the entire filtered
+  set, so combined with the joins it is the heaviest call in the file.
+- Rating comparisons are string comparisons on `data->>rating`
+  (`gte '4'`) — works for single digits, but `"10" >= "4"` is false
+  lexicographically; values above 9 would misclassify.
+- Signals are produced by `emitSignal` in
+  `.framework/functions/_shared/funnel.ts` (deduped once per account +
+  `action_type` by default) — this module only reads them.

package/.framework/src/instructions/reference/functions/ai-agents.md

@@ -0,0 +1,148 @@
+---
+title: ai-agents
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/ai-agents.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/functions/_shared/rate-limit.ts
+  - .framework/functions/_shared/security.ts
+  - .framework/public/_redirects
+---
+
+# ai-agents
+
+## What it does
+
+CRUD over `public.ai_agents` (agent definitions: `agent_type`,
+`model_config`, `system_prompt`, `tools`, `capabilities`,
+`constraints`), plus `action=run` — the interactive entry point that
+executes a multi-turn agent episode against a **thread** (not against an
+agent row directly; the agent and prompt config are resolved inside
+`runAgent` from the thread's `data.agent_id` /
+`data.prompt_config_id` and type schema).
+
+## Route and methods
+
+`/.netlify/functions/ai-agents`, reachable as `/api/ai-agents` (`/api/*`
+→ `/.netlify/functions/:splat`, `.framework/public/_redirects`).
+Dispatch is by `?action=` then method:
+
+| Call | Handler |
+|---|---|
+| `POST /api/ai-agents?action=run` | `run` (any method dispatches; a JSON body is required in practice) |
+| `GET /api/ai-agents` | `list` |
+| `GET /api/ai-agents?id=<uuid>` | `get` |
+| `POST /api/ai-agents` | `create` |
+| `PATCH /api/ai-agents` (`id` in body or query) | `update` |
+| `DELETE /api/ai-agents?id=<uuid>` | `remove` |
+
+## Authentication
+
+Standard `createHandler` auth: `x-api-key` → machine principal,
+`x-internal-secret` → internal principal, `Bearer <jwt>` → human;
+anonymous → 401.
+
+- `list`/`create`/`update`/`run` require `ctx.accountId`.
+- No role gate anywhere in this file — `create`/`update`/`remove` only
+  require an authenticated person+account context; humans are bounded by
+  RLS on `ctx.db`, machines run service-role.
+- `run` debits the `agent_step` rate limit
+  (`.framework/functions/_shared/rate-limit.ts`) — a fail-closed,
+  cost-bearing action; over-limit throws `RateLimitError` (HTTP 429 with
+  `retry_after`).
+
+## Request contract
+
+**list** (query): `agent_type`, `is_active` (`'true'`/`'false'`),
+`limit` (default 100), `offset` (default 0).
+
+**get** (query): `id`.
+
+**create** (body): `name`, `agent_type` required. Optional: `app_id`,
+`description`, `model_config` `{}`, `system_prompt`, `tools` `[]`,
+`capabilities` `[]`, `constraints` `{}`, `metadata` `{}`. `account_id`
+and `created_by` stamped from context.
+
+**update** (`id` in body or query + body): allowlist — `name`,
+`description`, `agent_type`, `model_config`, `system_prompt`, `tools`,
+`capabilities`, `constraints`, `metadata`, `is_active`, `app_id`.
+
+**remove** (query): `id` — **hard delete**.
+
+**run** (body): `thread_id` required; `user_message`; `mode`
+(`'step'`/`'complete'`/`'episode'`, default `'complete'`);
+`driver_token` (optional — lets a client keep a stable driver identity
+across calls instead of `ctx.requestId`).
+
+## Response contract
+
+Standard `{ data, error, meta }` envelope.
+
+- CRUD → sanitized row(s) (`{ id }` for non-admins); `remove` →
+  `{ success: true }`.
+- `run` → `{ ok, thread_id, message_id, status, turn_count, content,
+  message_type, data, agent_id, prompt_config_id }` where `status` comes
+  from the thread's `data.research_state` (`complete`,
+  `awaiting_input`, `failed`, …).
+- Lease-refused runs return HTTP 200 with `{ ok: true, status:
+  'running', driver_id }` (plus `already_running: true` in episode
+  mode) — callers poll the thread rather than interleave writes. A
+  replay of an already-answered episode returns `status: 'complete'`
+  with `already_done: true` and the last outbound message.
+
+## Side effects
+
+- `run` performs a prompt-injection pre-flight (`detectInjection`); the
+  app's `config.security.prompt_injection` mode (`'off'`/`'flag'`
+  default/`'block'`) decides whether the hit is audited
+  (`security.injection_detected`) or rejected with HTTP 400.
+- `run` claims the thread's episode lease — atomically via the
+  `episode_leases` RPC (`.framework/migrations/064_episode_leases.sql`),
+  with a legacy heartbeat check as fallback — so concurrent drivers
+  can't double-drive a thread.
+- `run` executes `runAgent`
+  (`.framework/functions/_shared/agent-runner.ts`), which writes agent
+  messages to `public.messages` and mutates `threads.data
+  .research_state`. Episode mode runs inline under an 8-second budget,
+  then the client's step loop continues under the same lease.
+- Rate limit is debited **only after** a successful lease claim —
+  refused requests never double-charge an episode.
+- CRUD emits `ai_agent.created` / `.updated` / `.deleted` audit rows to
+  `public.logs`.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Missing `thread_id` | 500 | `thread_id is required` |
+| No person+account context | 500 | `User context (person and account) required` |
+| Missing thread | 500 | `Thread not found` / PostgREST message |
+| Injection in `block` mode | 400 | `Your message could not be processed automatically. A support specialist will review it.` |
+| `agent_step` over limit | 429 | rate-limit message + `retry_after` |
+| Missing `id` | 500 | `Agent ID is required` |
+| Row missing on delete | 500 | `Agent not found` |
+| Bad action/method | 500 | `Invalid action or method` |
+
+Most `Error`s map to 500 (no `statusCode`); the injection-block and
+rate-limit paths carry explicit 400/429 codes.
+
+## Agent notes
+
+- `run` takes a thread, not an agent id — the agent binding lives on
+  `threads.data.agent_id` (or the thread type's
+  `design_schema.default_agent_id`). Creating an `ai_agents` row does
+  not wire it to anything.
+- Episode single-flight is keyed by `driver_id`: pass a stable
+  `driver_token` from a polling client so re-entry renews the lease
+  instead of being refused.
+- A "stuck" live driver blocks the thread for the 60-second lease TTL —
+  `status: 'running'` is a normal response, not an error.
+- `remove` is a hard delete of the agent row; in-flight episodes are
+  unaffected (they hold ids in thread data).
+- The dispatch `case 'run'` ignores the HTTP method — a `GET
+  ?action=run` reaches `run` and fails on missing `thread_id` (body is
+  null on GET).