spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/roles.md

@@ -0,0 +1,80 @@
+---
+title: Roles
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/roles.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/auth.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/src/pages/admin/RolesPage.tsx
+  - .framework/src/pages/admin/RoleDetailPage.tsx
+  - .framework/migrations/003_core_system_data.sql
+---
+
+## What this is for
+
+A **role** is a named principal category assigned to people (`people.role_id`). Its **slug** is what permission evaluation keys on: each type's `design_schema.record_permissions` maps role slugs to the record actions that role may perform. The role's own `permissions` column feeds `principal.permissions` for coarse gates.
+
+## Fields and settings
+
+- **Name** — string, required. Display label (e.g. "Support Manager"); `slug` and `name` are the API's required fields.
+- **Slug** — string, required, unique per app. **Disabled after creation** because `record_permissions` keys and `people.role_id` references depend on it.
+- **Description** — string, optional.
+- **System Role** — checkbox, create-only. Reserved roles can't be deleted and are protected for core functions.
+- **Active** — checkbox. Inactive roles can't be assigned to people.
+- **Permissions (JSON)** — the form suggests an object mapping type slugs to action arrays (`{ "ticket": ["create","read"] }`), but the permission engine does **not** evaluate this column for record access — see Downstream effects. A **flat array** form (`["read","write","admin","system"]`) is what `auth.ts` copies into `principal.permissions`.
+
+**Downstream effects**
+
+- Record CRUD is governed by each type's `design_schema.record_permissions`, keyed by **role slug** — e.g. `"record_permissions": { "support-agent": ["read"] }`. Assigning a person a role takes effect immediately (the engine resolves `people.role_id → roles.slug` per request, short cache).
+- `record_permissions` keys are matched **verbatim** against `roles.slug` — `system-admin` is a dead key that silently denies the real `system_admin` role. The `all` key is a wildcard granting every authenticated principal.
+- `auth.ts` copies `role.permissions` into `principal.permissions` **only when it is a flat array** (`system_admin` is hardcoded to `["read","write","admin","system"]`). `principal.permissions` backs coarse checks like the invites `system` gate — not per-record access.
+- Malformed permissions don't lock anyone out of records (the column isn't read for that) — a wrong `record_permissions` slug on the type does.
+- Creating a role with slug `system_admin` is restricted to `system_admin` principals.
+
+## Minimal configuration
+
+```json
+{
+  "name": "Support Agent",
+  "slug": "support-agent",
+  "is_active": true,
+  "permissions": { "ticket": ["create", "read", "update"] }
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Support Manager",
+  "slug": "support-manager",
+  "is_active": true,
+  "is_system": false,
+  "permissions": { "ticket": ["create", "read", "update", "delete"] },
+  "metadata": { "department": "support" }
+}
+```
+
+Both examples use the object form the UI suggests — it is stored as documentation/delegated-policy data. Record access still comes from each type's `record_permissions` under the same slug.
+
+## Example
+
+A support app ships three roles: `support-agent`, `support-manager`, and `support-viewer`. On the `ticket` type, `record_permissions` grants `support-agent` `["create","read","update"]`, `support-manager` all four actions, and `support-viewer` `["read"]`; assignment happens on `people` records via `role_id`.
+
+## Core files
+
+- `.framework/functions/roles.ts` — API (list/get/create/update/delete; `system_admin` slug creation gated)
+- `.framework/functions/_shared/permissions.ts` — `record_permissions`/`fields.*.permissions` evaluation (role-slug keyed; `all` wildcard)
+- `.framework/functions/auth.ts` / `.framework/functions/_shared/principal.ts` — `role.permissions` → `principal.permissions` (flat array only)
+- `.framework/src/pages/admin/RolesPage.tsx` / `RoleDetailPage.tsx` — admin UI
+- Table: `public.roles`; assignment on `public.people.role_id`
+
+## Agent notes
+
+- The Permissions textarea's own placeholder shows the object form — know that it is not what gates records. The gate is `record_permissions[role_slug]` on the type.
+- Slug is immutable after create; rename = new role + reassignment. Never introduce a hyphenated `system-admin` slug — seeded slugs use underscores.
+- The seeded `system_admin` role must stay assigned for admin functions; `auth.ts` hardcodes its principal permissions, it is not data-driven.

package/.framework/src/instructions/runtime-detail.md

@@ -0,0 +1,70 @@
+---
+title: Runtime Record (detail)
+audience: both
+kind: ui
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/components/runtime/DataDetailPage.tsx
+  - .framework/src/hooks/useEntityRecord.ts
+  - .framework/src/components/runtime/SchemaDetailForm.tsx
+  - .framework/functions/admin-data.ts
+---
+
+## What this is for
+
+**Runtime detail** (`/spine-framework/admin/runtime/:entity/new` and `/runtime/:entity/:id`) is the generic create/view/edit form for one runtime record. It renders sections and fields from the record's stamped `design_schema.views.default_detail` — so any type with a detail view gets a working record page without a custom UI.
+
+## Fields and settings
+
+- **Header** — record title (`design_schema.display_field`, falling back through `full_name` → `display_name` → `name` → `title` → `slug` → `email` → "Untitled"), plus Edit / Save / Cancel / Delete buttons. `?edit=true` toggles edit mode; `new` starts in edit mode.
+- **Sections** — `views.default_detail.sections[*]`: each section's `fields` render as form controls per `display_type` (`input`, `textarea`, `select`, `checkbox`, `date_picker`, `json`-as-textarea, ...).
+- **Field values** — `system: true` fields read `record.<field>`; everything else reads `record.data.<field>` and is written back under `data`.
+- **Field permissions** — `fieldPermissions` from the record response gate which inputs are editable (field-level `read`/`write` from `fields.*.permissions` over the record grant).
+- **Delete** — confirm → `admin-data` remove → back to the entity list.
+
+**Downstream effects**
+
+- All writes go through `/api/admin-data` (`create`/`update`/`remove`): type stamping, `validation_schema` checks, `record_permissions`, and create/update triggers all apply — the same path custom apps must use.
+- Creating a record stamps the type's current `design_schema` onto it — the detail page then renders from that stamped copy (`record.design_schema || record.type.design_schema`).
+- Default `type_slug` per entity on create: `accounts→account`, `people→person`, `items→item`, `threads→thread`, `messages→message`, `links→link`, `attachments→attachment`, `watchers→watcher`, `item_progress→item_progress` — a `typeSlug` route param overrides it.
+
+## Minimal configuration
+
+Define `views.default_detail` on the type:
+
+```json
+"default_detail": {
+  "type": "detail", "label": "Ticket",
+  "sections": [
+    { "title": "Core", "fields": {
+      "title": { "display_type": "input" },
+      "status": { "display_type": "select" }
+    } }
+  ]
+}
+```
+
+## Full configuration
+
+Split fields across multiple named sections, choose richer `display_type` controls (`textarea`, `select`, `multiselect`, `date_picker`, `checkbox`, `color_picker`, `file_upload`, `range_slider`), and set `display_field` on the schema so the header shows a meaningful title. Field-level `permissions` on `design_schema.fields` restrict which roles can write a field even when the record grant allows updates.
+
+## Example
+
+`/spine-framework/admin/runtime/items/<id>?edit=true` renders the ticket: a "Core" section with Title (input), Status (select), Priority (select), and a "Notes" section with a `json` field shown as a monospaced textarea. Save → `admin-data` validates against `validation_schema` and fires `item_updated` triggers.
+
+## Core files
+
+- `.framework/src/components/runtime/DataDetailPage.tsx` — this page
+- `.framework/src/components/runtime/SchemaDetailForm.tsx` — renders sections/fields from the schema
+- `.framework/src/components/runtime/DataDetailHeader.tsx` — title + action buttons
+- `.framework/src/hooks/useEntityRecord.ts` — record fetch (`design_schema` fallback), save/delete via `admin-data`
+- `.framework/functions/admin-data.ts` — get/create/update/remove backend
+- `.framework/src/apps/admin/index.tsx` — `instructionKeyFor`: `runtime/:entity/...` (≥4 segments) → `runtime-detail`
+
+## Agent notes
+
+- Error card "Failed to load record or schema" = the record has no stamped `design_schema` or the type's `default_detail` view is missing — fix the type's schema, not this page.
+- `system: true` fields (e.g. `title`) are top-level record columns; a field defined in `design_schema.fields` but absent from a section won't render — the form only shows what `default_detail` declares.
+- A record stamped under an old schema renders the old view — re-save it to re-stamp the current schema.
+- `new` with no `typeSlug` uses the default type slug map above; creating a different type's record needs the `typeSlug` route param or a different entry point.

package/.framework/src/instructions/runtime-list.md

@@ -0,0 +1,77 @@
+---
+title: Runtime Records (list)
+audience: both
+kind: ui
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/components/runtime/DataListPage.tsx
+  - .framework/src/hooks/useListSchema.ts
+  - .framework/src/hooks/useEntityList.ts
+  - .framework/functions/admin-data.ts
+---
+
+## What this is for
+
+**Runtime list** (`/spine-framework/admin/runtime/:entity`) is the generic, schema-driven list page for any runtime entity table — `items`, `threads`, `messages`, `links`, `attachments`, `watchers`, `people`, `accounts`, `item_progress`. It renders whatever the entity's type `design_schema.views.default_list` declares, so every type gets a working admin list for free.
+
+## Fields and settings
+
+- **Header** — entity name, description, and a New button → `runtime/:entity/new`.
+- **Stats cards** — driven by `views.default_list.stats` (empty when undeclared).
+- **Filters** — driven by `views.default_list.filters`; values go into the `admin-data` list query.
+- **Columns** — `views.default_list.fields`: label from `design_schema.fields[key].label`, sortable unless `sortable: false`, rendered per `display_type` (`text`, `badge`, `timestamp`, `currency`, ...).
+- **Sort** — defaults to `views.default_list.default_sort` (fallback `created_at` desc); sent as `sort_field`/`sort_direction`.
+- **Rows** — `record.data.<field>` values for non-system fields, `record.<field>` for `system: true` fields.
+
+**How the schema is resolved** (`useListSchema`, in order)
+
+1. Fetch one sample record (`admin-data?action=list&entity=<entity>&limit=1`) and use its **stamped** `design_schema.views.default_list`.
+2. No stamped schema → look up `/api/types?action=list&kind=<mapped>`; used only when **exactly one** type matches the entity's kind.
+3. Otherwise a fallback view (just `id` + `created_at` columns).
+
+**Downstream effects**
+
+- All data flows through `/api/admin-data` — the same permission, validation, and trigger path as any other client.
+- Multi-type entities (e.g. `items` with `ticket`, `threshold_alert`, `kb-article`) resolve schema from the *sample record* — the columns shown are whichever type the most recent matching record carries, and `type_slug` filtering is available via the route's `typeSlug` param.
+- A type with no `default_list` view (or a fresh table with no records and >1 candidate type) renders the fallback two-column view — fix the type's `design_schema`, not this page.
+
+## Minimal configuration
+
+Define `views.default_list` on the type:
+
+```json
+"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" }
+}
+```
+
+## Full configuration
+
+Add `stats` and `filters` arrays to the view for stat cards and filter controls, choose `display_type` per column to control rendering, and set a different `default_sort` (e.g. `priority asc`). Valid `entity` path segments are the `admin-data` whitelist: `accounts`, `people`, `items`, `threads`, `messages`, `links`, `attachments`, `watchers`, `item_progress`, plus config entities (`types`, `link_types`, `ai_agents`, `prompt_configs`, ...).
+
+## Example
+
+`/spine-framework/admin/runtime/items` shows the ticket list: columns Title/Status/Priority/Created from `default_list.fields`, status rendered as a badge, sorted by `created_at` desc; the New button lands on `runtime/items/new`.
+
+## Core files
+
+- `.framework/src/components/runtime/DataListPage.tsx` — this page
+- `.framework/src/components/runtime/DataTable.tsx` / `DataFilters.tsx` / `DataStats.tsx` / `DataHeader.tsx` — subcomponents
+- `.framework/src/hooks/useListSchema.ts` — stamped-schema → type → fallback resolution
+- `.framework/src/hooks/useEntityList.ts` — the `admin-data` list query (filters, sort)
+- `.framework/functions/admin-data.ts` — list/get backend (`VALID_ENTITIES` whitelist)
+- `.framework/src/apps/admin/index.tsx` — `instructionKeyFor`: `runtime/:entity` → `runtime-list`
+
+## Agent notes
+
+- The schema comes from a **record's stamped** `design_schema` first — old records stamped before a schema change keep old views; the list can flip shape depending on which record it samples.
+- If the page shows only `id`/`created_at`, the type's `default_list` view is missing or ambiguous — check the type, then check that the entity has records.
+- Non-system fields live under `record.data` — a column for a `system: true` field reads `record.<field>`; mixing these up shows blank cells.
+- Filter/sort state is client-side over the fetched page — this is a browsing surface, not a reporting tool.

package/.framework/src/instructions/security.md

@@ -0,0 +1,67 @@
+---
+title: Security
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/pages/admin/SecurityPage.tsx
+  - .framework/functions/security.ts
+  - .framework/functions/_shared/security.ts
+  - .framework/migrations/049_security_blocklist.sql
+---
+
+## What this is for
+
+The **Security** page (`/spine-framework/admin/security`) is the system-admin console for abusive actors: a report of flagged users/accounts/IPs built from security signal logs, plus the platform blocklist. Its actions apply a three-layer ban — internal `security_blocklist` rows, a Supabase Auth ban, and a Netlify edge IP-deny rule.
+
+## Fields and settings
+
+- **Flagged actors table** — Actor (email or "(no person)"), Account, IP / Country, Signals (count + kind badges e.g. `rate_limit`, `prompt_injection`, `blocked_registration`), Last seen, Status (`active`/person status or `banned`).
+- **Row checkboxes + Add to Blacklist** — issues one `ban_user` call per selected row and prints per-layer results (`blocklist`, `auth`, `edge`) inline.
+- **Unban** — per-row on banned actors with a `person_id`; revokes their blocklist rows and lifts the auth ban and edge rule.
+- **Active blocklist table** — Type (`ip`/`email`/`person`/`account`), Value, Severity, Reason, Created, with per-row Revoke (`blocklist_revoke` sets `revoked_at`).
+- All calls go to `/api/security?action=…` (POST): `flagged_accounts`, `blocklist`, `ban_user`, `unban_user`, `blocklist_add`, `blocklist_revoke`.
+
+**Downstream effects**
+
+- `ban_user` accepts `person_id`, `email`, or `ip` — anonymous-signal rows (no person) still ban by account/IP. Layer 1 (internal blocklist) is authoritative; the Supabase Auth and Netlify edge layers report `applied`/`skipped`/`error` per call — the edge layer degrades gracefully when Netlify API credentials aren't configured.
+- Blocked principals are rejected at request time by `isBlockedRequest`/`isBlockedIp` in `_shared/security.ts` (checked in middleware and at registration).
+- Every action emits `security.*` audit events into `logs` — the same table the flagged report is aggregated from.
+- Every action requires a `system_admin` principal.
+
+## Minimal configuration
+
+Nothing to configure — the report fills itself from security signals (rate-limit violations, prompt-injection detections, blocked registrations). To act: select flagged rows → Add to Blacklist.
+
+## Full configuration
+
+Direct API calls for finer control:
+
+```
+POST /api/security?action=blocklist_add   { type: "ip", value: "203.0.113.7", severity: "high", reason: "credential stuffing", expires_at: null }
+POST /api/security?action=blocklist_revoke { id: "<row uuid>" }
+POST /api/security?action=ban_user         { email: "abuser@example.com", ip: "203.0.113.7", reason: "..." }
+POST /api/security?action=unban_user       { person_id: "<uuid>" }
+```
+
+`expires_at` may be set for temporary bans; entries with `revoked_at` are hidden from the Active blocklist.
+
+## Example
+
+A burst of `rate_limit` signals from one IP appears in Flagged actors. Select the row, Add to Blacklist — the result line shows `banned (auth:applied edge:applied)`; subsequent requests from that IP 403 at the edge and at `isBlockedIp`. If it was a false positive, Unban restores the person and revokes the rows.
+
+## Core files
+
+- `.framework/src/pages/admin/SecurityPage.tsx` — this page
+- `.framework/functions/security.ts` — flagged report, three-layer ban/unban, blocklist CRUD, Netlify edge sync
+- `.framework/functions/_shared/security.ts` — `isBlockedRequest`/`isBlockedIp` enforcement, `emitSecurityEvent`, injection patterns
+- `.framework/migrations/049_security_blocklist.sql` — `security_blocklist` schema
+- Tables: `public.security_blocklist`, `public.logs` (signal source)
+
+## Agent notes
+
+- The Netlify edge layer needs Netlify API credentials in env — without them `edge: skipped` is normal, not a failure; the internal blocklist still enforces.
+- Banning by `email`/`ip` does not stop a determined actor from rotating — treat the edge deny as a speed bump and watch for re-registration signals.
+- Unban requires a `person_id` — rows banned only by IP/email must be lifted via `blocklist_revoke` on the blocklist entries.
+- This page is marked experimental and is system-admin only; all writes are audited.

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

@@ -0,0 +1,110 @@
+---
+title: Add a pipeline
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/pipelines.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/migrations/053_builtin_action_seeds.sql
+  - .framework/functions/system-cron.ts
+---
+
+# Add a pipeline
+
+## Goal
+
+Create a `public.pipelines` row: an ordered `stages` array the runner
+executes when something (a trigger, a timer, or a manual run) invokes it.
+
+## Steps
+
+1. **Choose the `trigger_type`.** `manual` (run by button/API), `event`
+   (fired by a trigger), `scheduled` (fired by a timer), or `webhook`. This
+   is metadata for callers — what actually runs a pipeline is whatever
+   invokes `runPipeline`, so the type should match how you plan to wire it
+   ([Automation](../concepts/automation.md)).
+
+2. **Draft the `stages` array.** Each stage needs a `stage_type` matching an
+   active slug in `public.actions` plus a `config`. Built-in stage types
+   (seeded by `.framework/migrations/053_builtin_action_seeds.sql`):
+
+   `update_item`, `create_record`, `http_request`, `send_notification`,
+   `send_email`, `run_pipeline`, `search_knowledge`, `query_items`,
+   `agent_inference`, `generate_embeddings`, `revoke_embeddings`,
+   `kb_ingest`, `kb_revoke`, `create_interaction`
+   (`.framework/functions/_shared/pipeline-runner.ts`).
+
+   ```json
+   [
+     {
+       "stage_type": "query_items",
+       "config": { "entity": "items", "type_slug": "ticket",
+                   "filters": { "status": "open" } }
+     },
+     {
+       "stage_type": "http_request",
+       "config": { "url": "https://example.com/hook", "method": "POST",
+                   "body": { "title": "{{record.data.title}}" } }
+     }
+   ]
+   ```
+
+   - Stage config merges `action.config` (defaults on the actions row) under
+     `stage.config`, plus injected `_pipelineId` / `_executionId` /
+     `_stageIndex` / `_triggerData`
+     (`.framework/functions/_shared/pipeline-runner.ts`).
+   - `{{trigger.*}}` resolves into the trigger-data envelope; `{{record.*}}`
+     resolves into `triggerData.entity.data` — the record that fired the
+     run (`.framework/functions/_shared/pipeline-runner.ts`).
+   - `continue_on_error: true` on a stage lets the run continue after a
+     failure; otherwise a failed stage aborts the whole run
+     (`.framework/functions/_shared/pipeline-runner.ts`).
+
+3. **Create the pipeline.** Admin UI → **Configs → Pipelines → New**
+   (`configs/pipelines/new`), or `POST /api/pipelines` with
+   `{ name, trigger_type, stages }` — all three required
+   (`.framework/functions/pipelines.ts`). Set `is_active: true`;
+   `runPipeline` refuses inactive pipelines.
+
+4. **Wire the entry point.** A pipeline with `trigger_type: "event"` needs a
+   trigger ([Add a trigger](./add-a-trigger.md)); `scheduled` needs a timer
+   ([Add a timer](./add-a-timer.md)); `manual` runs on demand. Changing
+   `trigger_type` later does not rewire existing triggers or timers — relink
+   them separately.
+
+## Verify
+
+- Run it directly: `npx spine-framework pipelines run <id> --data '{"x":1}'`
+  — see [CLI reference](../reference/cli.md).
+- Check **Observability → Executions** (`observability/executions`) or
+  `pipelines executions <id>` for a `completed` row with per-stage results.
+- A missing `stage_type` fails fast with
+  `Action not found for stage type: <type>` — the runner looks the slug up
+  in `public.actions` with `is_active = true` before executing
+  (`.framework/functions/_shared/pipeline-runner.ts`).
+
+## Common mistakes
+
+- **Nonexistent stage_type.** Seed validation and the runner both reject
+  unknown slugs; stick to the built-ins or seed your own `actions` row
+  (see [Package and install an app](./package-and-install-an-app.md)).
+- **Expecting stage outputs to chain into the next stage.** Each stage gets
+  the merged `action.config` + `stage.config` + `_triggerData`; previous
+  stage outputs are collected into the execution result, not injected into
+  later configs. Templates only see `{{trigger.*}}` and `{{record.*}}`.
+- **`scheduled` with no timer, or `event` with no trigger.** The pipeline
+  is then unreachable — `get_due_timers` only returns timers with
+  `pipeline_id` set, and triggers dispatch by `pipeline_id`.
+- **Editing `stages` while runs are queued.** The runner reads the pipeline
+  row at execution time; a queued execution picks up whatever `stages`
+  exist when it starts, not when it was queued.
+
+## Reference
+
+- [pipelines entity page](../pipelines.md) ·
+  [Automation](../concepts/automation.md)
+- [pipeline-executions reference](../reference/functions/pipeline-executions.md) ·
+  [pipeline-runner-background reference](../reference/functions/pipeline-runner-background.md)
+- [Add a trigger](./add-a-trigger.md) · [Add a timer](./add-a-timer.md)

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

@@ -0,0 +1,96 @@
+---
+title: Add a role
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/roles.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/003_core_system_data.sql
+  - .framework/migrations/009_roles_slug_unique.sql
+---
+
+# Add a role
+
+## Goal
+
+Create a `public.roles` row whose slug you can reference from
+`record_permissions` in type design schemas, `min_role`/`required_roles` on
+apps, and `role:<slug>` notification recipients.
+
+## Prerequisites
+
+- A `system_admin` login — role create/update/remove requires it
+  (`.framework/functions/roles.ts`).
+
+## Steps
+
+1. **Pick the slug.** Lowercase snake_case (`support_agent`). It is matched
+   verbatim as a key inside every type's `record_permissions` and is
+   effectively immutable — the admin UI disables slug editing after creation.
+   Uniqueness is enforced at both the API layer (duplicate-slug check before
+   insert) and the database (`UNIQUE(slug)`,
+   `.framework/migrations/009_roles_slug_unique.sql`).
+
+2. **Decide the permissions payload.** `roles.permissions` is a JSON
+   document on the role row (`permissions jsonb` on the table,
+   `.framework/migrations/001_core_schema.sql`). Seeded roles carry
+   `'["*"]'` — a wildcard grant. Per-type grants are expressed on the
+   **type** side (`design_schema.record_permissions` keys are role slugs),
+   which is what `admin-data` evaluates per request — see
+   [Permission model](../concepts/permissions.md).
+
+3. **Create the role.** Admin UI → **Configs → Roles → New**
+   (`configs/roles/new`), or `POST /api/roles` with
+   `{ slug, name, permissions, is_system }` — `slug` and `name` are required
+   (`.framework/functions/roles.ts`). The `system_admin` slug itself
+   is protected: only a system admin may create it
+   (`.framework/functions/roles.ts`).
+
+4. **Reference the role.** Add its slug to each type's
+   `design_schema.record_permissions`, to `apps.min_role` /
+   `apps.required_roles`, and to `send_notification` stage recipients as
+   `role:<slug>` (resolved via `people.role_id → roles.slug` — see
+   [Automation](../concepts/automation.md)).
+
+5. **Assign it to people.** A person's `role_id` joins to `roles`; the
+   permission engine resolves `people.role:role_id(slug)` and evaluates
+   `record_permissions` against that slug
+   (`.framework/functions/_shared/permissions.ts`).
+
+## Verify
+
+- `GET /api/roles?action=list` returns the row; `slug` is unique and active.
+- Create or update a type whose `record_permissions` includes the new slug,
+  then perform an `admin-data` call as a person holding the role — the
+  action is permitted.
+- `system_admin` users see all roles regardless of `is_active` filters.
+
+## Common mistakes
+
+- **`system-admin` vs `system_admin`.** All seeded slugs are snake_case:
+  `system_admin`, `member`, `member_admin`, `engineering`,
+  `engineering_admin`, `product`, `docs`, `qa`, `devops`, `management`,
+  `sales`, `csm`, `tam`, `support`, `support_admin`
+  (`.framework/migrations/003_core_system_data.sql`,
+  `.framework/migrations/073_seed_member_roles.sql`).
+  Using hyphens in `record_permissions` grants nothing.
+- **Expecting `roles.permissions` to gate `admin-data`.** Record-level
+  grants live on the type's `record_permissions`; the role row's
+  `permissions` JSON is not consulted per-request for record CRUD.
+- **Renaming a slug later.** Every type's `record_permissions` and every
+  app's `min_role`/`required_roles` reference the slug verbatim — a rename
+  orphans the grants. Create a new role and migrate people instead.
+- **Creating `system_admin` via API as a non-admin** — explicitly blocked.
+- **Deactivating a role with live assignees** — the slug stops resolving to
+  a grant for those people; check `people.role_id` usage first.
+
+## Reference
+
+- [roles entity page](../roles.md) ·
+  [roles function reference](../reference/functions/roles.md)
+- [Permission model](../concepts/permissions.md) ·
+  [Add a type](./add-a-type.md)
+- [Database reference](../reference/database.md) for the `roles` columns

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*