spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/reference/app-manifest.md

@@ -0,0 +1,150 @@
+---
+title: App Manifest Reference
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/_shared/app-manifest.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/cli/commands/validate-app.ts
+---
+
+# App Manifest Reference
+
+`manifest.json` is the install-time and runtime descriptor every app carries
+at `custom/apps/<slug>/manifest.json`. Two consumers read it:
+
+- **CLI installers** (`install-app`, `update-app`, `update-db-app`, `seed-app`,
+  `uninstall-app` in `.framework/cli/commands/install-app.ts`) — copy files,
+  upsert the `public.apps` row, run the `seed` block, and sync the
+  `registration` policy into `apps.config` and `spine.config.json`.
+- **Runtime** (`loadManifest` / `mergeWithManifest` / `discoverManifests` in
+  `.framework/functions/_shared/app-manifest.ts`) — when an `apps` row has
+  `manifest_path` set and `config_source = 'manifest'`, the manifest file
+  overrides DB columns for slug, name, roles, routes, and nav.
+
+See [Seeds](seeds.md) for the seed mechanics and
+[spine.config.json](spine-config.md) for the registration file the installer
+writes.
+
+## Required fields
+
+| Field | Rule |
+|---|---|
+| `name` | non-empty string |
+| `slug` | must match `/^[a-z][a-z0-9-]*$/`, equal the app directory name, and equal the `seed-app`/`update-db-app` argument |
+
+`loadManifest` rejects manifests missing either, and `preflightAppInputs`
+rejects a manifest whose `slug` does not match the app's directory slug —
+before any database work happens.
+
+## Runtime fields (`AppManifest`)
+
+Read by `.framework/functions/_shared/app-manifest.ts` and mirrored onto the
+`apps` row by `appRowPayload` in the installer:
+
+| Field | Type | Default on the apps row |
+|---|---|---|
+| `description` | string | `''` |
+| `version` | string | `'1.0.0'` |
+| `required_roles` | string[] | `[]`; `min_role` column becomes `required_roles[0]` (or legacy `min_role`) |
+| `route_prefix` | string | `'/' + slug` |
+| `renderer` | `'generic' \| 'custom' \| 'none'` | `'custom'` — matches the `apps.renderer` CHECK constraint |
+| `routes` | string[] | app route paths; `:param` segments supported |
+| `nav_items` | `NavItem[]` | `[]` — `{title, path, icon?, order?, type_slug?, view?, children?}`. **`path` must include the `route_prefix`** (e.g. `/taskboard/tasks`, not `/tasks`) — the app index navigates to `path` verbatim, so a bare path escapes the app and 404s. `view` is **one slug consumed by both the list and the detail page** — naming `default_list` makes the detail page resolve a list view (which has `fields`, not `sections`) and render empty. Omit `view` to get `default_list` + `default_detail`; a nav item cannot pick list and detail views independently |
+| `features` | string[] | `[]` |
+| `dependencies` | string[] | `[]` |
+| `entry_point` | string | e.g. `"./index.tsx"` |
+| `is_public` | boolean | `false` — reachable without auth when true |
+| `auth_required` | boolean | `true` |
+| `preview_domain` | string | `null` |
+| `prod_domain` | string | `null` |
+
+`mergeWithManifest` always keeps DB-owned values for `id`, `is_active`,
+`is_system`, `account_id`, `pack_id`, and `ownership`; the manifest wins for
+`slug`, `name`, `required_roles`, `routes`, `nav_items`, `features`,
+`dependencies`, `version`, `is_public`, `auth_required`.
+
+## Installer-only fields
+
+Consumed by `.framework/cli/commands/install-app.ts`; ignored by the runtime
+loader:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `app_type` | string | informational; the installer always writes `app_type: 'custom'` on the apps row |
+| `sidebar_component` | string | app-relative path to a sidebar component |
+| `seed` | `SeedEntry[]` | seed declarations — see below and [Seeds](seeds.md) |
+| `owned_types` | string[] | type slugs this app may reconcile when `--reconcile-owned-types` is passed; every slug must exist in a types seed |
+| `registration` | object | registration policy synced to `apps.config.registration` and `spine.config.json` |
+| `config` | object | merged (shallow) into `apps.config`; existing keys the manifest does not declare survive |
+| `metadata` | object | written to `apps.metadata` |
+
+### `seed[]` entries
+
+```json
+"seed": [
+  { "file": "seed/roles.json",      "table": "roles",      "conflict": "slug" },
+  { "file": "seed/types.json",       "table": "types",      "conflict": "kind,slug", "inject_app_id": false },
+  { "file": "seed/link-types.json",  "table": "link_types", "conflict": "app_id,slug" },
+  { "file": "seed/type_permissions.json", "table": "types", "conflict": "kind,slug",
+    "inject_app_id": false, "permissions_patch": true },
+  { "file": "seed/pipelines.json",   "table": "pipelines",  "conflict": "app_id,slug" },
+  { "file": "seed/triggers.json",    "table": "triggers",   "conflict": "app_id,slug" }
+]
+```
+
+| Key | Rule |
+|---|---|
+| `file` | path relative to the app root; must resolve inside the app directory (canonicalization rejects `..` and symlink escapes). **Declared files must exist** — a missing declared file fails the install |
+| `table` | target `public.*` table |
+| `conflict` | PostgREST `onConflict` columns, e.g. `slug`, `kind,slug`, `app_id,slug` |
+| `inject_app_id` | default `true` — stamps `app_id` on every row. Set `false` for global rows (types are global per `kind,slug`) |
+| `ignore_duplicates` | upsert skips existing rows instead of updating (always forced for `types`) |
+| `permissions_patch` | row shape `{kind, slug, record_permissions}`; patches `design_schema.record_permissions` on an existing type |
+
+If `manifest.seed` is absent, the installer falls back to the conventional set:
+`seed/roles.json`, `seed/types.json` (`inject_app_id: false`),
+`seed/link-types.json`. A `seed/type_permissions.json` file is auto-declared
+as a `permissions_patch` entry even when `seed` is explicit, unless a patch
+entry already exists. Every row of a `types` seed gets a fresh
+`validation_schema` generated from its `design_schema` at apply time.
+
+### `registration`
+
+```json
+"registration": {
+  "enabled": true,
+  "default_role": "member_admin",
+  "redirect_path": "/my-app",
+  "account_strategy": "new",
+  "parent_account": "spine-system",
+  "target_account": "<account-id>",
+  "allow_domain_join": false,
+  "default_workspace_name": "Team"
+}
+```
+
+Validated at preflight: `registration` must be an object; `enabled` must be a
+boolean; when `enabled: true`, `default_role` and `redirect_path` are required
+non-empty strings. The resolved entry is written to both
+`apps.config.registration` (server-side source of truth) and
+`spine.config.json` `registration.apps.<slug>` — see
+[spine.config.json](spine-config.md). `account_strategy` is `new` or
+`existing`; `parent_account`/`target_account` select where new accounts/users
+land.
+
+## App-row mapping
+
+`appRowPayload` upserts `public.apps` on `slug` with `app_type: 'custom'`,
+`source: 'npm'`, `is_active: true`, and the manifest-derived columns above.
+`manifest.config` is shallow-merged over the existing `apps.config` (manifest
+wins shared keys; unrelated keys are preserved).
+
+## Related files
+
+- `.framework/functions/_shared/app-manifest.ts` — runtime loader, cache, discovery, manifest-over-DB merge
+- `.framework/cli/commands/install-app.ts` — preflight, `appRowPayload`, `seedApp`, `syncAppRegistration`
+- `.framework/cli/commands/validate-app.ts` — `spine-framework validate-app` structural checks
+- [Apps](../apps.md) · [Seeds](seeds.md) · [spine.config.json](spine-config.md) · [Apps and Renderers](../concepts/apps-and-renderers.md)

package/.framework/src/instructions/reference/cli.md

@@ -0,0 +1,124 @@
+---
+title: CLI Reference
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/cli/index.ts
+  - .framework/cli/context.ts
+  - .framework/cli/commands/agents.ts
+  - .framework/cli/commands/auth.ts
+  - .framework/cli/commands/bootstrap.ts
+  - .framework/cli/commands/create-app.ts
+  - .framework/cli/commands/doctor.ts
+  - .framework/cli/commands/init.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/cli/commands/items.ts
+  - .framework/cli/commands/migrate.ts
+  - .framework/cli/commands/migrations.ts
+  - .framework/cli/commands/pipelines.ts
+  - .framework/cli/commands/status.ts
+  - .framework/cli/commands/system.ts
+  - .framework/cli/commands/test.ts
+  - .framework/cli/commands/upgrade.ts
+  - .framework/cli/commands/validate-app.ts
+  - .framework/cli/commands/validate-schema.ts
+  - .framework/cli/commands/dev.ts
+  - .framework/cli/commands/generate.ts
+---
+
+# CLI Reference
+
+`spine-framework` is the project CLI (bin entry `.framework/cli/bin.mjs` →
+`.framework/cli/index.ts`, Commander.js). Run it as `npx spine-framework …`
+or via the project script `npm run spine-framework -- …`.
+
+Global behaviors:
+
+- `--account <id>` on the root program overrides the account scope.
+- Most read commands accept `--json` for machine output.
+- Credential resolution lives in `.framework/cli/context.ts`: DB-backed
+  commands need `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY`; remote commands
+  authenticate with `SPINE_CLI_API_KEY` or `SPINE_CLI_JWT`; see
+  [Environment Variables](env-vars.md).
+- `.env` in the project root is preloaded by the bin wrapper before any
+  command module evaluates.
+
+## Project lifecycle
+
+| Command | What it does |
+|---|---|
+| `init [dir]` | Scaffolds a Spine project: copies framework files, creates `custom/` workspace dirs (`apps`, `functions`, `components`, `migrations`, `tests`), writes `package.json`/`package-lock.json`, agent files. Refuses to run over an existing `.framework/` |
+| `bootstrap` | Provisions the first `system_admin` (person bound to `spine-system`, same columns the `handle_new_auth_user` trigger writes) and mints the first `sk_` API key — fully scriptable, no browser. `--email`/`--password` also creates a confirmed auth user via `auth.admin.createUser` (UI-login capable); without them the person row is DB-only. `--scope <scope>` is repeatable (default `*:*` = system_admin), `--name`, `--full-name`, `--json`. Idempotent: an existing `system_admin` skips person creation; each run mints one new key (hash stored, raw key printed once) |
+| `upgrade` | Syncs project files to the `spine-framework` version in `node_modules`. `--dry-run` reports without writing; `--force` overwrites locally modified framework files |
+| `status` | Shows installed apps and framework version (`--json`) |
+| `doctor` | Validates installation health (env, files, DB reachability). `--fix` prints repair instructions; `--ticket <id>` attaches a sanitized diagnostic report to a support ticket |
+| `test [suite]` | Runs Vitest suites. `--watch` for unit/integration; `--reporter <name>`; `--json` |
+| `dev` | Runs `scripts/assemble.sh`, verifies integrity (`--no-verify` skips), then starts Vite via `config/vite.config.ts` on `--port` (default 3001; `--host` exposes to network) — equivalent to `npm run dev`. `--netlify` runs `scripts/dev-netlify.sh` instead (functions + UI on :8888, equivalent to `npm run dev:netlify`; `--port`/`--host` are ignored). Watches `custom/` and re-assembles on change; `--no-watch`, `--watch-delay <ms>` |
+
+## Database
+
+| Command | What it does |
+|---|---|
+| `migrate` | Applies pending `.framework/migrations/` then `custom/migrations/` SQL files in filename order, tracked in the `_spine_migrations` ledger table, one transaction per file. `--db-password` (default `SUPABASE_DB_PASSWORD`), `--dry-run`, `--framework-only` (skip `custom/`) |
+| `migrations list` | Lists applied migrations from `supabase_migrations.schema_migrations` (`--json`) |
+| `migrations status` | Diffs local migration files against applied ones (`--json`) |
+
+## App management
+
+| Command | What it does |
+|---|---|
+| `install-app <package>` | `npm install`s the package, copies `index.tsx`, `manifest.json`, `package.json`, `pages`, `components`, `hooks`, `utils`, `functions`, `seed`, `public` into `custom/apps/<slug>/` (on reinstall `manifest.json` is preserved — use `update-db-app` to sync it), runs migrations, then seeds and syncs registration. `--no-seed` installs files only; `--reconcile-owned-types` prompts to update manifest-owned types whose DB `design_schema` drifted |
+| `uninstall-app <package>` | Removes `custom/apps/<slug>/` and `npm uninstall`s the package. **`--keep-data` is currently a no-op — the command never deletes seeded DB rows** |
+| `update-app <package>` | `npm install <pkg>@latest`, re-copies app files into `custom/apps/<slug>/`, re-syncs registration config |
+| `update-db-app <slug>` | Upserts the `apps` row and registration from local `manifest.json` — no npm, no file copies |
+| `seed-app <slug>` | Runs only the manifest `seed` block (plus registration sync). `--reconcile-owned-types` as above |
+| `validate-app [path]` | Validates app structure and `manifest.json`. `--fix` is declared but **not implemented** |
+| `create-app <slug>` | Scaffolds a new custom app in `custom/apps/<slug>/` (index, manifest, starter pages). `--name`, `--role`, `--force` |
+| `validate-schema <file>` | Validates a `design_schema` JSON file against the field/view/permission rules. `--no-views` skips `default_list`/`default_detail` requirements (for custom apps); `--json` |
+
+## Runtime data
+
+These commands talk to a running instance via the API
+(`SPINE_CLI_API_KEY`/`SPINE_CLI_JWT` + `SUPABASE_URL`).
+
+| Command | What it does |
+|---|---|
+| `auth whoami` | Prints the resolved principal for the current env config (`--json`) |
+| `auth check` | Exits 0 when credentials resolve, 1 otherwise — CI gate |
+| `items list` | Lists items. `--type <slug>`, `--account`, `--limit`, `--json` |
+| `items get <id>` | Fetches one item (`--json`) |
+| `items create` | `--type <slug>`, `--data <json>`, `--title`, `--account` |
+| `items update <id>` | `--data <json>` partial update, `--title` |
+| `items delete <id>` | Soft-deletes (`is_active = false`); `--hard` permanently removes |
+| `pipelines list` | Lists active pipelines. `--all` includes inactive; `--account`, `--json` |
+| `pipelines get <id>` | Pipeline detail (`--json`) |
+| `pipelines run <id>` | Executes a pipeline. `--data <json>` trigger payload, `--account` |
+| `pipelines executions <id>` | Recent executions. `--limit`, `--json` |
+| `agents run <threadId>` | Sends a message to an agent thread and returns the response. `--message` required, `--account`, `--json` |
+| `agents threads list` | Lists agent threads. `--account`, `--limit`, `--json` |
+| `agents threads get <id>` | Thread detail + recent messages. `--limit`, `--json` |
+
+## System
+
+| Command | What it does |
+|---|---|
+| `system manifest` | Fetches the instance manifest (version, functions, migrations) from the `system` function (`--json`) |
+| `system health` | Fetches health-check status (`--json`) |
+| `system openapi` | Fetches the OpenAPI specification |
+
+## Removed commands
+
+These commands remain registered so callers get a clear message instead of
+silent failure — do not build workflows on them.
+
+| Command | Status |
+|---|---|
+| `generate [slug]` | **Removed.** Previously wrote type/handler/page stubs to a `v2-custom/` tree and emitted a legacy `design_schema` shape — both dead. Now prints migration guidance (`create-app` for apps; admin UI or `POST /api/types` + `validate-schema` for types) and exits 1 |
+
+## Related
+
+- `.framework/cli/index.ts` — command registration
+- `.framework/cli/context.ts` — credential and account resolution
+- [Seeds](seeds.md) · [App Manifest](app-manifest.md) · [Environment Variables](env-vars.md)

package/.framework/src/instructions/reference/database.md

@@ -0,0 +1,132 @@
+---
+title: Database Reference
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - .framework/migrations/018_runtime_tables.sql
+  - .framework/migrations/035_rate_limits.sql
+  - .framework/migrations/049_security_blocklist.sql
+  - .framework/migrations/050_notifications.sql
+  - .framework/migrations/054_kb_ingest_lease.sql
+  - .framework/migrations/064_episode_leases.sql
+  - .framework/cli/commands/migrate.ts
+  - .framework/src/types/types.ts
+---
+
+# Database Reference
+
+Postgres (Supabase) tables that custom code touches, grouped by purpose.
+Column lists are the ones custom code actually reads/writes — every table has
+`id uuid` plus `created_at`, and most have `updated_at`, `is_active`,
+`account_id`, `app_id`, `created_by`/`updated_by`, and stamped
+`design_schema`/`validation_schema` jsonb. The canonical DDL is
+`.framework/migrations/001_core_schema.sql` (base) plus later migrations.
+
+## Tenancy & identity
+
+| Table | Purpose | Key columns |
+|---|---|---|
+| `accounts` | Tenant boundary; every scoped row hangs off one | `slug` UNIQUE, `display_name`, `parent_id`, `type_id`, `data`, `logs_retention_days`, `observability_retention_days` |
+| `account_paths` | Closure table for account hierarchies | `ancestor_id`, `descendant_id`, `depth` (PK pair) |
+| `people` | Human users (one per Supabase auth user + invite stubs) | `auth_uid` UNIQUE, `email` UNIQUE, `full_name`, `account_id`, `role_id`, `status`, `data` |
+| `roles` | Role definitions granting record/field permissions | `slug` UNIQUE, `name`, `permissions` jsonb, `is_system`, `is_protected`, `account_id` |
+| `system_settings` | Instance/account-scoped key-value settings | `scope`, `scope_id`, `key`, `value` |
+| `invites` | Invite tokens and placement config | `app_id`, `account_id`, `slug`, `config`, `is_active` |
+
+## Types, apps, configuration
+
+| Table | Purpose | Key columns |
+|---|---|---|
+| `types` | Type definitions — the `design_schema` contract lives here | `kind`, `slug` (UNIQUE per `kind,slug` since 015), `name`, `icon`, `color`, `design_schema`, `validation_schema`, `ownership`, `is_active`, `app_id` |
+| `apps` | Installed apps | `slug` UNIQUE, `name`, `app_type`, `source`, `renderer` (`generic`/`custom`/`none`), `route_prefix`, `required_roles`, `min_role`, `config` (incl. `registration`), `nav_items`, `manifest_path`, `config_source` |
+| `link_types` | Named link semantics between records | `slug`, `name`, `config`, `source_kind`, `target_kind` |
+
+## Runtime records
+
+Every runtime row is typed (`type_id` → `types`) and stamped with the type's
+schemas at insert. `system: true` fields are top-level columns; others live
+in `data`.
+
+| Table | Purpose | Key columns |
+|---|---|---|
+| `items` | The workhorse record kind | `type_id`, `title`, `status`, `data`, `account_id`, `app_id` |
+| `threads` | Conversation containers bound to a target record | `type_id`, `title`, `target_type`, `target_id`, `visibility` (`internal`/`external`/`public`), `status`; UNIQUE `(target_type, target_id, visibility)` |
+| `messages` | Posts inside threads | `thread_id`, `type_id`, `content`, `direction`, `sequence`, `visibility`, `person_id`; UNIQUE `(thread_id, sequence)` |
+| `links` | Typed edges between records | `link_type_id`, `link_type`, `source_type`/`source_id`, `target_type`/`target_id`; UNIQUE edge constraint |
+| `attachments` | File records | `filename`, `file_size`, `mime_type`, `storage_path`, `storage_provider`, `uploaded_by` |
+| `watchers` | People watching a target record | `target_type`/`target_id`, `person_id`, `watch_type`, `notification_level`; UNIQUE `(target_type, target_id, person_id)` |
+| `item_progress` | Per-item pipeline progress rows | `item_id`, `slug`, `config`, `status` fields |
+
+## Automation
+
+| Table | Purpose | Key columns |
+|---|---|---|
+| `pipelines` | Declarative stage sequences | `slug`, `name`, `config`/`metadata` (incl. `stages[]`), `account_id`, `app_id`, UNIQUE `(app_id, slug)` |
+| `pipeline_executions` | Pipeline run ledger | `pipeline_id` FK CASCADE, `status`, `started_at`, `completed_at`, `input_data`, `output_data`, `error_message` |
+| `triggers` | Event→pipeline dispatch rules | `slug`, `config` (event type, entity, filters, `pipeline_id`), `account_id`, UNIQUE `(app_id, slug)` |
+| `trigger_executions` | Trigger fire ledger | `trigger_id` FK CASCADE, `status`, `input_data`, `output_data` |
+| `timers` | Scheduled work definitions | `slug`, `config`, `account_id`, UNIQUE `(app_id, slug)` |
+| `schedules` | Cron schedule principals (018) | schedule rows bound to `machine_principal_id` with `delegated_scopes` |
+| `schedule_executions` | Schedule run ledger (018) | execution rows |
+| `actions` | Stage-type catalog for pipelines (018, seeded by 053) | `slug`, `name`, `config`, `default_machine_principal_id` |
+| `episode_leases` | Agent-episode concurrency leases (064) | lease rows gated by `lease_token` |
+| `document_leases` | KB ingest leases by content hash (054) | lease rows |
+| `rate_limits` | Atomic rate counters for `rate_limit_hit` RPC (035) | `key`, `window_start`, `count` |
+
+## AI & knowledge
+
+| Table | Purpose | Key columns |
+|---|---|---|
+| `ai_agents` | Agent configurations | `slug`, `name`, `config` (model, prompts, capabilities), `account_id`, UNIQUE `(app_id, slug)` |
+| `prompt_configs` | Named prompt templates | `slug`, `name`, `config`, `account_id`, UNIQUE `(app_id, slug)` |
+| `embeddings` | KB chunks with pgvector | `model_id`, `document_id`, `chunk_index`, `content`, `embedding vector(1536)`, `content_hash`, `approved_at`, `revoked_at`; UNIQUE `(model_id, document_id, chunk_index)` |
+
+## Integrations & webhooks
+
+| Table | Purpose | Key columns |
+|---|---|---|
+| `integrations` | Outbound/inbound integration configs | `slug`, `name`, `config` (credentials, adapters), `account_id`, UNIQUE `(app_id, account_id, slug)` |
+| `integration_routes` | Inbound route definitions | `slug`, `config` (event path, handler), `account_id` |
+| `webhook_handlers` | Dynamic handler registry (004) | `name`, `function_name`, `events[]`, `account_id`, `is_deleted`; UNIQUE `(app_id, account_id, name)` |
+| `webhook_deliveries` | Inbound+outbound delivery ledger (004) | `direction`, `integration_id`, `api_key_id`, `handler_name`, `action_slug`, attempt/status fields |
+| `api_keys` | Machine principals and integration keys | `key_prefix`, `key_hash`, `key_type` (`inbound`/`outbound`/`internal`/`cli`), `scopes[]`, `rate_limit`, `machine_type`, `is_internal`, `expires_at`, `integration_id` |
+| `api_key_usage_logs` | Per-key request ledger (004) | `api_key_id` FK, `request_method`, `request_path`, `request_ip`, `success` |
+
+## Observability & security
+
+| Table | Purpose | Key columns |
+|---|---|---|
+| `logs` | Append-only log/audit/span/event rows | `level`, `message`, `context`, `metadata`, `source`/`source_type`/`source_id` |
+| `observability` | Metric points | `metric_name`, `metric_value`, `metric_unit`, `context` |
+| `alerts` | Alert rule configs | `slug`, `config` |
+| `security_blocklist` | Hard-blocked persons/accounts/emails/IPs (049) | blocklist entries with `type` and value |
+| `notifications` | User notifications (050) | recipient/title/body rows |
+
+## Testing
+
+`test_runs` (suite results incl. `pipeline_execution_id`), `test_cases`,
+`test_results` (018) — test definitions and outcomes.
+
+## Migration conventions
+
+- Files live in `.framework/migrations/` (framework) and `custom/migrations/`
+  (project); `migrate` applies framework first, then custom, in filename
+  order — `.framework/cli/commands/migrate.ts`.
+- Naming: `NNN_snake_case_description.sql`, three-digit prefix. Applied files
+  are recorded in the `_spine_migrations` ledger (`filename` UNIQUE); each
+  file runs in its own transaction and the run stops on first failure.
+- Known numbering gaps: **22–31, 39–41, 63** — numbers were reserved or
+  consolidated during development (audit D-007). A gap is expected, not a
+  missing migration.
+- `idempotent by convention`: framework migrations use `IF NOT EXISTS` /
+  `ON CONFLICT DO NOTHING` so re-running a file is safe.
+
+## Related
+
+- [Design Schema](design-schema.md) · [Runtime Records](../concepts/runtime-records.md)
+- [admin-data](api/admin-data.md) — the API surface over these tables
+- `.framework/migrations/` — authoritative DDL