spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/tasks/test-your-code.md

@@ -0,0 +1,108 @@
+---
+title: Test your code
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - vitest.config.ts
+  - .framework/tests/setup.ts
+  - .framework/tests/reporter.ts
+  - package.json
+  - config/tsconfig.json
+  - config/tsconfig.functions.json
+---
+
+# Test your code
+
+## Goal
+
+Run the Vitest suite and the TypeScript checks, and place new tests where
+the runner picks them up.
+
+## Steps
+
+1. **Know the runners** (`package.json` scripts):
+
+   - `npm run test` → `vitest run` — everything matching the `include`
+     globs in `vitest.config.ts`: `.framework/tests/unit/**/*.test.ts`,
+     `.framework/tests/api/**/*.test.ts`, `.framework/tests/integration/**/*.test.ts`,
+     and `custom/tests/**/*.test.ts`.
+   - `npm run test:unit` — the unit suite only.
+   - `npm run test:integration` — the integration suite (needs real env,
+     see below).
+   - `npm run test:core` — the core-isolation suite.
+   - `npm run typecheck` → `tsc -b config/tsconfig.json` — frontend +
+     CLI. Functions are **not** covered here: check them separately with
+     `npx tsc --noEmit -p config/tsconfig.functions.json` after
+     `npm run assemble` (it typechecks the assembled layout).
+   - `npx spine-framework test [suite]` — the CLI wrapper
+     (`--watch`, `--reporter`, `--json`; see [CLI reference](../reference/cli.md)).
+
+2. **Put tests where the globs look.** New project tests belong in
+   `custom/tests/**/*.test.ts` — picked up automatically, and they keep
+   `.framework/` untouched. Framework-level additions go under
+   `.framework/tests/unit/`. Test files inside `custom/functions/` are
+   excluded from function assembly (`*-test.ts`, `*.test.ts` are skipped
+   by `scripts/assemble-functions.sh`), but naming convention is still
+   `*.test.ts`.
+
+3. **Understand the env layering.** `vitest.config.ts` loads a root
+   `.env.test` file (if present) into `process.env` **before** any module
+   graph runs — that is how integration/API tests get real Supabase
+   credentials before `db.ts`/`principal.ts` call `createClient` at import
+   time. `.framework/tests/setup.ts` then stubs `SUPABASE_URL`,
+   `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` so unit tests never
+   crash on missing env. Integration helpers additionally require
+   `SPINE_TEST_ACCOUNT_ID`; API-surface tests use `SPINE_DEV_URL`,
+   `SPINE_DEV_JWT`, `SPINE_TEST_API_KEY` (see
+   [Environment variables](../reference/env-vars.md)).
+
+4. **Mock at module boundaries.** The config sets `isolate: true` — every
+   test file gets a fresh module registry, so `vi.mock` on
+   `./_shared/db`-style imports works per file. Existing unit suites mock
+   the Supabase client, principal resolution, and the LLM/embedding calls
+   rather than hitting the network (browse `.framework/tests/unit/` for
+   patterns — `pipeline-runner.test.ts`, `permissions.test.ts`,
+   `principal-cache.test.ts`).
+
+5. **Integration tests need a real project.** They exercise admin-data,
+   triggers, pipelines, and schema validation against a live Supabase
+   project using a service-role client and a seeded test account —
+   `custom/tests` and the unit suite run with no credentials, the
+   integration suite does not. `passWithNoTests: true` means a missing
+   env never fails the suite outright, so check that tests actually ran.
+
+## Verify
+
+- `npm run test` exits 0; `vitest` prints per-file pass counts. A custom
+  reporter that persists runs to `public.test_runs` exists at
+  `.framework/tests/reporter.ts` but is **not** registered — the config
+  uses `reporters: ['default']`, so opt in with `--reporter` if you want
+  persisted runs.
+- `npm run typecheck` and
+  `npx tsc --noEmit -p config/tsconfig.functions.json` are both clean.
+- `npx spine-framework doctor` sanity-checks the environment when tests
+  behave oddly ([CLI reference](../reference/cli.md)).
+
+## Common mistakes
+
+- **`typecheck` doesn't cover functions.** `config/tsconfig.json` excludes
+  the functions project by design — always run the
+  `tsconfig.functions.json` check too, and only after `npm run assemble`.
+- **Assuming integration tests ran.** With no `.env.test`, integration
+  files that can't build a client may skip silently — grep the output for
+  your file's pass count.
+- **Importing `createClient` at module top-level in a unit test.** Setup
+  stubs the env, but a module that builds a client at import time before
+  `setupFiles` runs still fails — mock the module or import lazily.
+- **Writing repo-only paths into `custom/tests`** — tests there must run
+  in an installed project too; import from `custom/` and assembled
+  aliases, not from repo internals.
+
+## Reference
+
+- [CLI reference](../reference/cli.md) — `test`, `doctor`
+- [Environment variables](../reference/env-vars.md) — `SPINE_TEST_*`,
+  `SPINE_DEV_*`, `SUPABASE_*`
+- [Write a function](./write-a-function.md) — assembled-layout imports

package/.framework/src/instructions/tasks/write-a-function.md

@@ -0,0 +1,132 @@
+---
+title: Write a function
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/db.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/logging.ts
+  - .framework/functions/timers.ts
+  - .framework/public/_redirects
+  - scripts/assemble-functions.sh
+---
+
+# Write a function
+
+## Goal
+
+Add a custom Netlify function when — and only when — the generic
+`/api/admin-data` endpoint cannot cover the case: specialized auth, inbound
+webhooks, heavy compute, or bespoke orchestration. Record CRUD must go
+through `admin-data` so permission, validation, audit, and trigger logic
+stay shared ([Runtime records](../concepts/runtime-records.md)).
+
+## Steps
+
+1. **Decide it is warranted.** `admin-data` already covers list/get/create/
+   update/remove/stats across every runtime table with permissions and
+   triggers enforced ([admin-data reference](../reference/functions/admin-data.md)).
+   Legitimate custom functions: public webhook receivers, scheduled
+   sweeps, compute-heavy transforms, auth-bridging endpoints.
+
+2. **Create the file.** Put it in `custom/functions/` (or
+   `custom/apps/<slug>/functions/` for app-scoped code) with a `custom_`
+   prefix — assembly copies `.framework/functions`, `custom/functions`,
+   and `custom/apps/*/functions` into one flat Netlify dir and **fails the
+   build on a basename collision**
+   (`scripts/assemble-functions.sh`). All functions are reachable at
+   `/api/<basename>` via the `_redirects` rule
+   (`.framework/public/_redirects`).
+
+   Imports resolve in the **assembled** layout, not the source tree:
+   `./_shared/*` and `./<other-function>` are sibling paths inside
+   `.assembled/netlify/functions/`, and `@shared/*` is an alias to the
+   same dir (`config/tsconfig.functions.json`). A function's own
+   `functions/_shared -> .framework/functions/_shared` symlink (as the
+   existing app functions dirs carry) makes `./_shared` resolve in the
+   source tree too.
+
+   ```ts
+   // custom/functions/custom_my-endpoint.ts
+   import { createHandler, error, json } from './_shared/middleware'
+   import { adminDb } from './_shared/db'
+   import { PermissionEngine } from './_shared/permissions'
+   import { emitLog } from './_shared/logging'
+
+   export const handler = createHandler(async (ctx, body) => {
+     // ctx.requestId, ctx.principal, ctx.db, ctx.accountId, ctx.appId,
+     // ctx.query, ctx.headers, ctx.trace — all populated by middleware
+     if (!PermissionEngine.isSystemAdmin(ctx)) {
+       throw new Error('System admin required')
+     }
+     const { data, error: err } = await ctx.db
+       .from('items').select('id,title').eq('is_active', true).limit(10)
+     if (err) throw err
+     return data
+   })
+   ```
+
+3. **Follow the `createHandler` contract** (`.framework/functions/_shared/middleware.ts`):
+
+   - The middleware resolves the principal (`x-api-key` → internal secret →
+     Bearer JWT), builds `RequestContext`, and wraps your return value in
+     the `{ data, error, meta }` envelope. Thrown `Error`s become
+     `{ error }` responses — don't build response objects yourself.
+   - `ctx.db` is the principal-scoped client (humans get a user-scoped,
+     RLS-bound client; machines/anonymous get `adminDb`).
+   - `ctx.query` merges `queryStringParameters`; `ctx.query.method` carries
+     the HTTP method. Functions dispatching on `?action=` use a
+     `switch (ctx.query.action)` (see `.framework/functions/timers.ts`).
+   - For endpoints that must accept anonymous or raw requests, use
+     `createPublicHandler` instead (same file, `createPublicHandler`).
+
+4. **Use the `_shared` modules, don't reinvent them** — `db` (`adminDb`,
+   `getUserDb`), `permissions` (`PermissionEngine`, `isSystemAdmin`,
+   `sanitizeRecordData`), `principal` (`resolvePrincipal`,
+   `SYSTEM_PRINCIPAL`), `audit`/`logging` (`emitLog`, `emitAudit`),
+   `resolve-ids`, `rate-limit` — see
+   [Shared modules reference](../reference/shared-modules.md) and
+   [Functions index](../reference/functions/index.md).
+
+5. **Assemble and run.** `npm run assemble && npm run dev:netlify`, then
+   `curl http://localhost:8888/api/custom_my-endpoint` — see
+   [Install and first run](../guide/01-install-and-first-run.md).
+   Function typecheck is separate from `npm run typecheck`:
+   `npx tsc --noEmit -p config/tsconfig.functions.json` checks the
+   assembled output (run it after `assemble`).
+
+## Verify
+
+- `GET /api/custom_my-endpoint` returns the `{ data, error, meta }`
+  envelope; unauthenticated calls return `401 Authentication required`
+  from the middleware, not from your code.
+- `npm run assemble` passes (no basename collision error) and
+  `npm run typecheck` compiles.
+
+## Common mistakes
+
+- **Duplicating a framework basename.** Assembly hard-fails naming both
+  sources — prefix custom files `custom_`.
+- **Returning raw Response objects.** `createHandler` expects a return
+  value (serialized into `data`) or a thrown error — don't emit Netlify
+  `{statusCode, body}` shapes yourself inside a `createHandler` function.
+- **Using `adminDb` for user-facing reads.** It bypasses RLS — prefer
+  `ctx.db` unless you intentionally need service-role access.
+- **Putting secrets in the response.** `sanitizeRecordData` /
+  `omitSecretFields` exist for a reason — strip credentials before
+  returning.
+- **Writing record CRUD** — if the function creates/updates `items`,
+  `threads`, etc., you are bypassing `admin-data`; call it via
+  `adminDataCreate`/`/api/admin-data` instead.
+
+## Reference
+
+- [Shared modules reference](../reference/shared-modules.md) ·
+  [Functions index](../reference/functions/index.md) ·
+  [Auth and API keys](../concepts/auth-and-api-keys.md)
+- [admin-data reference](../reference/functions/admin-data.md) ·
+  [Build a custom page](./build-a-custom-page.md) ·
+  [Anatomy of an installed project](../guide/02-project-map.md)

package/.framework/src/instructions/tasks/write-a-migration.md

@@ -0,0 +1,110 @@
+---
+title: Write a migration
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/cli/commands/migrate.ts
+  - .framework/migrations/068_cron_schedule_timer_rpcs.sql
+  - .framework/migrations/053_builtin_action_seeds.sql
+---
+
+# Write a migration
+
+## Goal
+
+Add a `.sql` file that the `migrate` command applies exactly once, in order,
+tracked in the `_spine_migrations` ledger table. See
+[Database reference](../reference/database.md) for the table map.
+
+## Steps
+
+1. **Pick the directory.**
+
+   - `custom/migrations/` — project/app migrations (**default choice**).
+     `collectMigrations` reads `.framework/migrations/*.sql` first, then
+     `custom/migrations/*.sql`, each sorted lexically — custom migrations
+     always run after every framework migration
+     (`.framework/cli/commands/migrate.ts`).
+   - `.framework/migrations/` — only for framework-owned changes (you are
+     editing the framework itself).
+
+2. **Pick the number.** Framework files use `NNN_name.sql` with zero-padded
+   sequence numbers. Occupied ranges today: `001`–`021`, `032`–`038`,
+   `042`–`062`, `064`–`069`; gaps `22`–`31`, `39`–`41`, `63` are reserved/
+   consolidated — **do not reuse gap numbers** (see
+   [Database reference](../reference/database.md)). Custom migrations get
+   their own files in `custom/migrations/`; filenames are tracked verbatim
+   in `_spine_migrations`, so keep them globally unique.
+
+3. **Write idempotent SQL.** Migrations run once per filename — but
+   installs re-run them against databases in unknown drifted states, so
+   guard everything:
+
+   ```sql
+   ALTER TABLE public.my_table
+     ADD COLUMN IF NOT EXISTS my_col text;
+
+   CREATE INDEX IF NOT EXISTS idx_my_table_col
+     ON public.my_table (my_col);
+
+   INSERT INTO public.roles (slug, name, is_active)
+   SELECT 'my_role', 'My Role', true
+   WHERE NOT EXISTS (SELECT 1 FROM public.roles WHERE slug = 'my_role');
+   ```
+
+   `CREATE TABLE IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`,
+   `DROP … IF EXISTS`, `ON CONFLICT … DO NOTHING`, and
+   `INSERT … SELECT … WHERE NOT EXISTS` are the house patterns (see
+   `.framework/migrations/053_builtin_action_seeds.sql`).
+
+4. **Apply it.**
+
+   ```bash
+   npx spine-framework migrate              # framework + custom
+   npx spine-framework migrate --dry-run    # list pending only
+   npx spine-framework migrate --framework-only
+   ```
+
+   Requires `SUPABASE_URL` (a hosted `https://<ref>.supabase.co` URL — the
+   CLI rejects anything else before connecting) and
+   `SUPABASE_DB_PASSWORD` or `--db-password`
+   (`.framework/cli/commands/migrate.ts`).
+
+5. **Check state.** `npx spine-framework migrations list` reads the
+   `_spine_migrations` ledger; `migrations status` diffs local files vs
+   applied — see [CLI reference](../reference/cli.md).
+
+## Verify
+
+- `_spine_migrations` contains the filename: each file runs in a
+  transaction, records `INSERT INTO _spine_migrations (filename)`, and the
+  runner **stops at the first failure** — fix and re-run
+  (`.framework/cli/commands/migrate.ts`).
+- Re-running `migrate` reports the file as skipped.
+
+## Common mistakes
+
+- **Renaming a file after it ran.** Tracking is by filename — a rename
+  makes it a new migration and re-applies the SQL.
+- **Non-idempotent DDL.** `ALTER TABLE … ADD COLUMN` without
+  `IF NOT EXISTS` fails on the second run (e.g. a fresh install that
+  already got the column from a later reconciliation migration).
+- **Gap numbers.** `022`–`031`, `039`–`041`, `063` are reserved — using
+  them collides with framework history.
+- **Depending on framework ordering.** Custom files all sort *after* every
+  framework file; you cannot interleave a custom migration between
+  framework ones — express dependencies inside the SQL (e.g.
+  `CREATE OR REPLACE`, existence checks).
+- **`SUPABASE_URL` with a port, path, or credentials** — rejected by the
+  CLI before it ever connects.
+
+## Reference
+
+- [Database reference](../reference/database.md) — table map, numbering
+  gaps
+- [CLI reference](../reference/cli.md) — `migrate`, `migrations list`,
+  `migrations status`
+- [Package and install an app](./package-and-install-an-app.md) — app
+  installers run `migrate` automatically before seeding

package/.framework/src/instructions/testing.md

@@ -0,0 +1,59 @@
+---
+title: Testing
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/pages/admin/TestingDashboard.tsx
+  - .framework/src/pages/admin/TestRunDetailPage.tsx
+  - .framework/functions/tests.ts
+  - .framework/migrations/001_core_schema.sql
+---
+
+## What this is for
+
+The **Testing** page (`/spine-framework/admin/testing`) is a dashboard over `test_runs`/`test_results` — rows written by external test harnesses (e.g. suite runs triggered from the IDE). It summarizes per-suite health and lists recent runs so you can spot a red suite without opening the CI output.
+
+## Fields and settings
+
+- **Suite cards** — one per suite (`unit`, `integration`, `api`, `ui`): last status, last run time, last pass/fail/total counts, and total runs (last 30 days).
+- **Recent runs table** — last 20 runs: suite, status (`passed`/`failed`/`running`/etc.), started time, passed, failed, total, duration.
+- **Row click** — navigates to `testing/:run_id` for the individual test-case results (`name`, `status`, `message`, `duration_ms` per case).
+- No actions on this page — runs are produced by harnesses, not created here.
+
+**Downstream effects**
+
+- Backed by `/api/tests` (function `tests`): `action=stats` aggregates the last 30 days by suite; `action=list` returns recent runs; `action=get&id=` returns one run plus its ordered `test_results`. All require system context.
+- `system` health checks (`/api/system`) and `spine-framework doctor` also read `test_runs` — a stale suite shows up in deploy health.
+- Rows are append-only; there is no cleanup action on this API today.
+
+## Minimal configuration
+
+Nothing on the page — have your harness insert `test_runs` (+ `test_results` per case) and the dashboard populates itself.
+
+## Full configuration
+
+```
+GET /.netlify/functions/tests?action=stats        # per-suite 30-day rollup
+GET /.netlify/functions/tests?action=list&limit=20
+GET /.netlify/functions/tests?action=get&id=<run uuid>   # run + ordered test_results
+```
+
+## Example
+
+A nightly job runs the `integration` suite and writes a `test_runs` row with `failed: 2`. The dashboard's Integration card flips red with last-run counts; click the row to see which two `test_results` failed and their messages.
+
+## Core files
+
+- `.framework/src/pages/admin/TestingDashboard.tsx` — this page
+- `.framework/src/pages/admin/TestRunDetailPage.tsx` — run detail route (`testing/:run_id`)
+- `.framework/functions/tests.ts` — API (`stats`, `list`, `get`)
+- Tables: `public.test_runs`, `public.test_results`
+
+## Agent notes
+
+- Known mismatch: `TestRunDetailPage` fetches `/api/test-runs?action=...`, but the shipped function is `tests` — the detail route currently fails to load. Use `tests?action=get&id=` until the page is repointed.
+- The suites list is hardcoded (`unit`, `integration`, `api`, `ui`) — a run with a different `suite` value won't get a card, though it still appears in Recent runs.
+- `stats` is a fixed 30-day window capped at 200 rows — high-volume suites need direct table queries for longer trends.
+- Nothing here triggers runs; the "no runs yet" empty state points at running suites from your IDE/CI.

package/.framework/src/instructions/timers.md

@@ -0,0 +1,84 @@
+---
+title: Timers
+audience: both
+kind: entity
+verified_against: b3b3ae0
+verified_on: 2026-11-01
+source_files:
+  - .framework/functions/timers.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/src/pages/admin/TimersPage.tsx
+  - .framework/src/pages/admin/TimerDetailPage.tsx
+  - .framework/migrations/068_cron_schedule_timer_rpcs.sql
+  - .framework/migrations/020_schema_reconciliation.sql
+---
+
+## What this is for
+
+A **timer** is a scheduled job that invokes a pipeline when it comes due — Spine's recurring/one-off background task primitive. `system-cron` (invoked every minute by the `trigger-scheduler` Netlify scheduled function) asks the `get_due_timers` RPC for due timers and runs each one's pipeline.
+
+## Fields and settings
+
+- **Name** — string. Display name; required (`name` and `timer_type` are the API's required fields).
+- **Type** — select: `interval`, `cron`, `once`. **Stored but not read by the scheduler** — it labels intent only; see Downstream effects.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Pipeline ID** — select. The pipeline invoked when the timer fires. `get_due_timers` skips rows where `pipeline_id IS NULL`, so a blank pipeline means the timer never runs.
+- **Active** — checkbox. Inactive timers are skipped by `get_due_timers`.
+- **Description** — string, optional.
+- **Config (JSON)** — the schedule. The only key the rescheduler reads today is `interval_minutes` (minutes between runs). The form seeds `{ "schedule": "", "interval_seconds": 3600 }` — neither key is honored by the current RPCs.
+- **Metadata (JSON)** — optional metadata.
+
+**Downstream effects**
+
+- `get_due_timers` returns active timers with `pipeline_id IS NOT NULL` and `next_execution <= now()`. The timers API arms `next_execution` automatically on create/activate when `config.interval_minutes` (or `interval_seconds`) resolves to a positive interval — or pass `next_execution` explicitly.
+- `update_timer_after_run` reschedules `next_execution = now() + interval` only when `config.interval_minutes` is a positive number; otherwise it sets `next_execution = NULL` and the timer becomes one-shot/dead. `timer_type`, `interval_seconds`, `schedule`, and `run_at` are ignored by the RPC.
+- Each firing also stamps `last_execution` and increments `execution_count` / `success_count` / `failure_count` — the source of the list page's Executions and Success Rate columns.
+- True cron expressions live on the separate `public.schedules` table (read by `get_due_schedules`), not on `timers` — a `cron`-type timer is a label, not a working cron.
+
+## Minimal configuration
+
+```json
+{
+  "name": "Hourly sync",
+  "timer_type": "interval",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true,
+  "config": { "interval_minutes": 60 }
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Nightly-ish rollup",
+  "timer_type": "interval",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true,
+  "config": { "interval_minutes": 1440 },
+  "metadata": { "owner": "platform", "notes": "fires ~daily once next_execution is seeded" }
+}
+```
+
+## Example
+
+A support app keeps an `interval` timer with `interval_minutes: 360` to re-check stale tickets every six hours, and a second timer whose `interval_minutes` was left blank to run a one-off backfill — after its first fire, `update_timer_after_run` writes `next_execution = NULL` so it never re-fires.
+
+## Core files
+
+- `.framework/functions/timers.ts` — API (list/get/create/update/delete; does not set `next_execution`)
+- `.framework/functions/system-cron.ts` — per-tick driver: calls `get_due_timers`, runs `runPipeline` as a `timer:<id>` principal, then `update_timer_after_run`
+- `.framework/functions/trigger-scheduler.ts` — Netlify scheduled entry point that delegates to `system-cron`
+- `.framework/migrations/068_cron_schedule_timer_rpcs.sql` — the `get_due_timers` / `update_timer_after_run` RPCs
+- `.framework/src/pages/admin/TimersPage.tsx` / `TimerDetailPage.tsx` — admin UI
+- Table: `public.timers` (`timer_type`, `pipeline_id`, `next_execution`, `execution_count` added by migration 020)
+
+## Agent notes
+
+- The list's "Next Execution" column shows `Not scheduled` when `next_execution` is NULL — an active timer in that state cannot fire until it is re-armed (edit its interval or toggle it off/on).
+- A timer with a blank `pipeline_id` saves fine but is filtered out by `get_due_timers` — always pick the pipeline.
+- **Under `netlify dev`, timers arm but never fire.** Netlify scheduled functions only run on deployed sites — locally, `trigger-scheduler` is loaded but never invoked on schedule. Emulate a tick with `netlify functions:invoke trigger-scheduler` or `curl -X POST localhost:8888/.netlify/functions/trigger-scheduler -H 'x-scheduler-key: <SCHEDULER_API_KEY>'`. A timer that schedules but never executes locally is an environment limitation, not a defect — unless manual invoke also fails.
+- Trigger dispatch requires `INTERNAL_INVOKE_SECRET` set **and a dev-server restart** — a queued execution that never runs usually means the secret is missing (see [Add a trigger](tasks/add-a-trigger.md)).
+- To arm a new timer, set `next_execution` in the DB (e.g. `now() + interval`); after the first successful run, `interval_minutes` keeps it rescheduling.
+- "Success Rate" is `success_count / execution_count`; failures still reschedule — a broken pipeline does not stop the cadence.

package/.framework/src/instructions/triggers.md

@@ -0,0 +1,69 @@
+---
+title: Triggers
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/triggers.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/src/pages/admin/TriggersPage.tsx
+  - .framework/src/pages/admin/TriggerDetailPage.tsx
+  - .framework/migrations/064_episode_leases.sql
+---
+
+## What this is for
+
+A **trigger** listens for a Spine event and, when active, hands the event payload to a pipeline for processing. It is the link between emitted platform events (e.g. `item_created`) and the workflows that react to them.
+
+## Fields and settings
+
+- **Name** — string. Display name; missing name prevents saving.
+- **Event Type** — string. The event to listen to, e.g. `item_created`. Must match the emitted event name **exactly** — a typo means the trigger never fires.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Pipeline ID** — select, required at create (`name`, `event_type`, `pipeline_id` are all required by the API). The pipeline invoked when the trigger fires; a stale ID means the queued execution fails instead of running.
+- **Active** — checkbox. Inactive triggers are skipped at fire time — matching events produce no run.
+- **Description** — string, optional.
+- **Config (JSON)** — trigger-engine configuration, e.g. filters or payload mapping.
+- **Metadata (JSON)** — optional metadata.
+
+**Downstream effects**
+
+- The trigger engine (`admin-data` writes → `_shared/trigger-engine`) matches emitted events to active triggers by `event_type`; real event names use underscores — `item_created`, `item_updated`, `item_deleted`, `thread_created`, `message_created`, etc. (see the `EventType` union in `_shared/trigger-engine.ts`).
+- `config` filters narrow which matching events actually invoke the pipeline.
+- A wrong or stale `pipeline_id` means the trigger fires, queues an execution row, and the run fails — check Pipeline Executions, not just the trigger, when "nothing happened".
+
+## Minimal configuration
+
+```json
+{
+  "name": "On item created",
+  "event_type": "item_created",
+  "pipeline_id": "<pipeline uuid>",
+  "is_active": true
+}
+```
+
+## Full configuration
+
+Adds `config` with payload filters (e.g. match only `item_created` where `type_slug = "ticket"`), field mappings into the pipeline input, and `metadata` documenting the contract the event producer is expected to emit.
+
+## Example
+
+A support app fires `item_created` filtered to `type_slug = "ticket"`; the trigger invokes its triage pipeline, which assigns the ticket and posts a thread message. A second trigger on `item_updated` handles SLA warnings — both share the same pipeline pattern but different filters.
+
+## Core files
+
+- `.framework/functions/triggers.ts` — API
+- `.framework/functions/_shared/trigger-engine.ts` — event matching and dispatch to `pipeline-runner-background`
+- `.framework/functions/trigger-scheduler.ts` — Netlify scheduled entry point (delegates to `system-cron`)
+- `.framework/src/pages/admin/TriggersPage.tsx` / `TriggerDetailPage.tsx` — admin UI
+- Table: `public.triggers`
+
+## Agent notes
+
+- Event names are `<entity>_<past tense>` (`item_created`, `message_deleted`, ...) — the Event Type input's own placeholder still shows the stale `item.created` form; use underscores.
+- `config` filters (`entity_type`, `type_slug`, `filters` with `$eq`/`$ne`/`$gt`/etc.) narrow which matching events actually invoke the pipeline.
+- The list's "Total Fires" stat and "Fires"/"Last Fired" columns count trigger firings (the `record_trigger_fire` RPC), not successful pipeline runs — a trigger can fire while its pipeline fails.
+- `config` must be a JSON **object**, not a string — the second most common save failure after event-type typos.

package/.framework/src/instructions/types.md

@@ -0,0 +1,93 @@
+---
+title: Types
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/types.ts
+  - .framework/src/pages/admin/TypesPage.tsx
+  - .framework/src/pages/admin/TypeDetailPage.tsx
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/resolve-ids.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/migrations/015_types_kind_slug_unique.sql
+---
+
+## What this is for
+
+A **type** is the design schema for a runtime record kind. It defines the fields, default list/detail views, record permissions, icon, and color that the generic admin and runtime UIs use to create, validate, and display records. Every `items`/`threads`/`messages`/etc. record is stamped with its type's `design_schema` at creation.
+
+## Fields and settings
+
+- **Name** — string. Display label for the type. Empty name blocks save.
+- **Slug** — string. URL-friendly identifier, unique per `kind`. Callers resolve types by slug; duplicates break `resolveTypeId`/`.single()` lookups. Rarely change after records exist.
+- **Description** — string, optional. Human-readable context.
+- **Kind** — select: `item`, `account`, `person`, `thread`, `message`, `link`, `attachment`, `watcher`. Determines which runtime table the type governs.
+- **Ownership** — select: `system` (platform types, protected from deletion), `app` (owned by an app), `tenant` (account-specific).
+- **Is Active** — checkbox. Inactive types are hidden from lists and cannot have records created.
+- **App ID** — select. Required whenever ownership is not `system` — the form rejects save otherwise.
+- **Icon / Color** — UI presentation stored on the `types` row.
+- **Design Schema (JSON)** — the full schema: `fields`, `views` (`default_list`, `default_detail`), `record_permissions`, `scope`, `functionality`.
+- **Validation Schema** — read-only, regenerated from `design_schema` on every save by the API.
+
+**Downstream effects**
+
+- Generic list/detail pages render directly from `views`. A missing `default_list`/`default_detail` or unknown `display_type` breaks those pages.
+- `record_permissions` is the **base, most restrictive grant**: if a role can read/update a record, all fields default to read/write. `fields.*.permissions` only *loosen* access per field or restrict `system: true` fields.
+- `system: true` fields are read from `record.<field>`; non-system fields from `record.data.<field>`.
+- Changing `data_type` on a field with existing records does not migrate data — old values remain until rewritten.
+- Type seeds use `conflict: "kind,slug"` with `inject_app_id: false` — types are global, not duplicated per app install.
+
+## Minimal configuration
+
+```json
+{
+  "scope": "account",
+  "fields": {
+    "title": { "data_type": "text", "label": "Title", "required": true, "system": true }
+  },
+  "views": {
+    "default_list": {
+      "type": "list", "display": "table", "label": "List",
+      "fields": {
+        "title": { "sortable": true, "display_type": "text" },
+        "created_at": { "sortable": true, "display_type": "timestamp" }
+      },
+      "default_sort": { "field": "created_at", "direction": "desc" }
+    },
+    "default_detail": {
+      "type": "detail", "label": "Detail",
+      "sections": [{ "title": "Details", "fields": { "title": { "display_type": "input" } } }]
+    }
+  },
+  "record_permissions": { "system_admin": ["create", "read", "update", "delete"] },
+  "functionality": null
+}
+```
+
+## Full configuration
+
+Adds typed fields, select `options`, per-field `permissions` overrides, multiple views with sorting/badges, and per-role record grants (`admin`, `member`). See the [design schema reference](reference/design-schema.md) for the full `data_type` list (`text`, `number`, `select`, `multiselect`, `reference`, `json`, `date`, `boolean`, ...) and `display_type` list (`badge`, `timestamp`, `select`, `currency`, ...).
+
+## Example
+
+A support app defines a `ticket` type (kind `item`, ownership `app`): `title` (system text), `status` (select: open/pending/closed), `priority` (select), `assignee_id` (reference). `record_permissions` grants `system_admin` all actions, `admin` create/read/update, `member` read. `fields.assignee_id.permissions` loosens `write` to `member` so agents can self-assign.
+
+## Core files
+
+- `.framework/functions/types.ts` — API (list/get/create/update/delete; regenerates `validation_schema`)
+- `.framework/src/pages/admin/TypesPage.tsx` / `TypeDetailPage.tsx` — admin UI
+- `.framework/src/components/app-shell/GenericListPage.tsx` / `GenericDetailPage.tsx` — generic renderer
+- `.framework/functions/_shared/permissions.ts` — record/field permission evaluation
+- [Design schema reference](reference/design-schema.md) — full field/view schema reference in this book
+- Table: `public.types`
+
+## Agent notes
+
+- Never hand-edit `validation_schema`; change `design_schema` and the API regenerates it.
+- Slug uniqueness is per `(kind, slug)` — reuse across kinds is fine, reuse within a kind breaks lookups.
+- Every field needs `data_type`, `label`, `required`; `select`/`multiselect`/`radio` also need `options`.
+- Don't add `fields.*.permissions` unless overriding the base grant — the common mistake is re-stating record-level permissions per field.
+- Custom apps CRUD runtime records through `/api/admin-data` — never custom wrappers.