spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/src/instructions/tasks/build-a-custom-page.md

@@ -0,0 +1,118 @@
+---
+title: Build a custom page
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/components/AppWrapper.tsx
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - .framework/src/lib/api.ts
+  - .framework/cli/commands/create-app.ts
+  - scripts/assemble.sh
+---
+
+# Build a custom page
+
+## Goal
+
+Ship a React page inside a custom app (`renderer: 'custom'`) instead of the
+generic list/detail renderer. See
+[Apps and renderers](../concepts/apps-and-renderers.md) for the model.
+
+## When to go custom
+
+Stay on `renderer: 'generic'` when the app is CRUD over typed records — the
+generic renderer gives you list/detail/create/sort/permission-aware editing
+for free from `views.default_list` / `views.default_detail`. Go custom for
+dashboards, wizards, bespoke layouts, or anything not expressible as
+schema-driven list/detail — `GenericAppShell` only generates routes for
+nav items carrying `type_slug`
+(`.framework/src/components/app-shell/GenericAppShell.tsx`).
+
+## Steps
+
+1. **Scaffold the app** (or reuse one):
+
+   ```bash
+   npx spine-framework create-app <slug> --role <role-slug>
+   ```
+
+   Writes `custom/apps/<slug>/` with `manifest.json`, `index.tsx`, and
+   `components/`, and inserts the `apps` row with `renderer: 'custom'`
+   (`.framework/cli/commands/create-app.ts`). Pass `--role` a slug
+   that exists in `roles` — the default `member` is seeded by
+   `073_seed_member_roles.sql`.
+
+2. **Add pages under `custom/apps/<slug>/pages/`.** `CustomAppLoader`
+   lazy-imports only `custom/apps/<slug>/index.tsx`
+   (`import.meta.glob('../../../custom/apps/*/index.tsx')`,
+   `.framework/src/components/CustomAppLoader.tsx`) — `index.tsx`
+   default-exports the component (usually its own `<Routes>`) and imports
+   the page components itself.
+
+   ```tsx
+   // custom/apps/<slug>/pages/DashboardPage.tsx
+   export default function DashboardPage() { /* ... */ }
+   ```
+
+3. **Set the app row.** `renderer: 'custom'`, `route_prefix: '/<slug>'`,
+   `min_role` / `required_roles`, `nav_items` for the sidebar. `AppWrapper`
+   enforces auth + role before mounting your app
+   (`.framework/src/components/AppWrapper.tsx`).
+
+4. **Fetch data through `/api/admin-data`** — never write a bespoke CRUD
+   function:
+
+   ```ts
+   import { apiFetch } from '@core/lib/api'
+
+   const res = await apiFetch(
+     '/api/admin-data?action=list&entity=items&type_slug=ticket&limit=50')
+   const { data } = await res.json()
+   ```
+
+   `apiFetch` attaches the Supabase Bearer token and the `X-Account-Id`
+   header (`.framework/src/lib/api.ts`). Find-or-create related records
+   (e.g. a thread for a work item) through the same endpoint — see
+   [Build your first app — Step 4](../guide/04-first-app.md) for the full
+   call shapes.
+
+5. **Rebuild and run.** `npm run assemble` (or `npm run dev` / `dev:netlify`,
+   which run assembly automatically). Custom functions go in
+   `custom/functions/` prefixed `custom_` — assembly hard-fails on a
+   basename collision with a framework function
+   (`scripts/assemble-functions.sh`).
+
+## Verify
+
+- Navigate to `/<slug>` — `CustomAppLoader` resolves your `index.tsx`
+  (a missing entry shows the `App "<slug>" not found` error naming the
+  expected path).
+- `GET /api/apps?action=get&slug=<slug>` shows `renderer: 'custom'` and the
+  right `route_prefix`.
+- `npm run typecheck` compiles the page.
+
+## Common mistakes
+
+- **A bespoke CRUD endpoint.** Custom Netlify functions that
+  create/update/list runtime records bypass `admin-data`'s permission,
+  type-resolution, audit, and trigger logic — call `/api/admin-data` from
+  the client instead (see [Write a function](./write-a-function.md) for the
+  cases where a custom function *is* allowed).
+- **Forgetting `index.tsx` is the only entry.** New pages in `pages/` are
+  invisible until `index.tsx` routes to them.
+- **`type_slug` nav items on a custom app** — they only do something under
+  the generic renderer; use plain `path` nav items and route them yourself.
+- **Editing before re-assembling** — `CustomAppLoader`'s glob is evaluated
+  at build time; new files need an assemble/dev restart.
+
+## Reference
+
+- [Apps and renderers](../concepts/apps-and-renderers.md) ·
+  [Runtime records](../concepts/runtime-records.md)
+- [App manifest reference](../reference/app-manifest.md) ·
+  [admin-data function reference](../reference/functions/admin-data.md)
+- [Build your first app](../guide/04-first-app.md) ·
+  [Anatomy of an installed project](../guide/02-project-map.md)

package/.framework/src/instructions/tasks/package-and-install-an-app.md

@@ -0,0 +1,127 @@
+---
+title: Package and install an app
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/cli/commands/install-app.ts
+  - .framework/cli/commands/validate-app.ts
+  - .framework/functions/_shared/app-manifest.ts
+  - .framework/cli/commands/migrate.ts
+---
+
+# Package and install an app
+
+## Goal
+
+Package a `custom/apps/<slug>/` directory as an npm package and install it
+into a Spine project — files copied, `apps` row upserted, migrations run,
+seeds applied. Field-level manifest semantics are in
+[App manifest reference](../reference/app-manifest.md) and
+[Seeds reference](../reference/seeds.md).
+
+## Steps
+
+1. **Author `manifest.json`.** Required fields the installer validates:
+   `slug` (must equal the directory name and match
+   `^[a-z][a-z0-9-]*$`), plus `name`, `route_prefix`, `renderer`,
+   `min_role` / `required_roles`, `nav_items`, `config`, `registration`.
+   See [App manifest reference](../reference/app-manifest.md) for every
+   field.
+
+2. **Author seed files.** The `seed` block is a list of
+   `{ file, table, conflict, inject_app_id?, ignore_duplicates?, permissions_patch? }`
+   entries, each pointing at a JSON file of rows
+   (`.framework/cli/commands/install-app.ts`):
+
+   - `conflict` — the `onConflict` column list for the upsert. Types use
+     `conflict: "kind,slug"` with `inject_app_id: false` — types are
+     **global**, not duplicated per install.
+   - `inject_app_id` — stamps `app_id` on each seeded row (default `true`);
+     set `false` for global tables like `types`.
+   - `ignore_duplicates` — `ignoreDuplicates` on the upsert; `types` rows
+     always get it (`.framework/cli/commands/install-app.ts`).
+   - `permissions_patch` — a types-table entry that merges
+     `record_permissions` into existing design schemas instead of
+     overwriting; ranks just after `types` in apply order.
+   - If no `seed` array is declared, the conventional files
+     `seed/roles.json`, `seed/types.json`, `seed/link-types.json` are used
+     (`.framework/cli/commands/install-app.ts`).
+
+   Seeds apply in dependency order — `roles`, `types`, `link_types`,
+   `actions`, `ai_agents`, `prompt_configs`, `pipelines`, `triggers` —
+   regardless of declaration order
+   (`.framework/cli/commands/install-app.ts`). Pipeline seeds are
+   validated against `public.actions` stage slugs, and trigger seeds
+   resolve `pipeline_slug` → `pipeline_id`.
+
+3. **Package it.** Ship the app directory as an npm package whose files
+   include `index.tsx`, `manifest.json`, and optionally `pages/`,
+   `components/`, `hooks/`, `utils/`, `functions/`, `seed/`, `public/` —
+   the installer copies exactly that allowlist
+   (`.framework/cli/commands/install-app.ts`). Validate locally
+   with `npx spine-framework validate-app`.
+
+4. **Install.**
+
+   ```bash
+   npx spine-framework install-app <package>
+   ```
+
+   Flow: `npm install <package>` → resolve slug → copy files to
+   `custom/apps/<slug>/` (a reinstall preserves the local `manifest.json`)
+   → `runMigrations` → `seedApp` → sync the `registration` block into
+   `apps.config` and `spine.config.json`
+   (`.framework/cli/commands/install-app.ts`). Requires
+   `SUPABASE_URL` + `SUPABASE_DB_PASSWORD` + `SUPABASE_SERVICE_ROLE_KEY`;
+   `--no-seed` skips all DB work.
+
+5. **Update paths.**
+
+   - `update-app <package>` — `npm install @latest` + copy files + sync
+     registration. **It does not re-run migrations or seeds.**
+   - `update-db-app <slug>` — upserts the `apps` row from the local
+     `manifest.json` and syncs registration; no npm, no file changes.
+   - `seed-app <slug>` — re-runs just the seed block for a local app;
+     `--reconcile-owned-types` interactively updates `manifest.owned_types`
+     slugs whose DB `design_schema` drifted from the seed.
+
+6. **Uninstall.** `uninstall-app <package>` removes
+   `custom/apps/<slug>/` and runs `npm uninstall` — and nothing else. The
+   `--keep-data` flag is parsed but never read: seeded rows are **not**
+   deleted either way (`.framework/cli/commands/install-app.ts`).
+
+## Verify
+
+- `npx spine-framework status` lists the installed app and version.
+- `GET /api/apps?action=get&slug=<slug>` shows the upserted row;
+  `migrations status` shows migration state.
+- Seeded rows exist: `GET /api/types?action=list` (or the seeded table's
+  endpoint) includes the app's types/roles.
+
+## Common mistakes
+
+- **Types not global.** Forgetting `inject_app_id: false` on a types seed
+  injects `app_id` into global type rows — and `conflict: "kind,slug"`
+  means a second app with the same slug silently skips or errors on
+  schema drift. Prefix slugs.
+- **Expecting `uninstall --keep-data` to matter** — it is a no-op; seeded
+  rows always survive uninstall.
+- **`update-app` doesn't re-seed** — new seed rows in the package never
+  reach the DB; run `seed-app <slug>` or `update-db-app` after.
+- **Seed rows referencing unseeded slugs** — `owned_types`,
+  `pipeline_slug`, and `send_notification` recipients are validated
+  fail-closed before any DB writes; fix the manifest, don't retry.
+- **`SUPABASE_URL` must be a hosted `https://<ref>.supabase.co` URL** —
+  the migrator rejects anything else before connecting
+  (`.framework/cli/commands/migrate.ts`).
+
+## Reference
+
+- [App manifest reference](../reference/app-manifest.md) ·
+  [Seeds reference](../reference/seeds.md) ·
+  [CLI reference](../reference/cli.md) ·
+  [spine.config.json reference](../reference/spine-config.md)
+- [Apps and renderers](../concepts/apps-and-renderers.md) ·
+  [Write a migration](./write-a-migration.md)

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.