spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/src/instructions/guide/03-domain-model.md

@@ -0,0 +1,223 @@
+---
+title: The Spine domain model
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/003_core_system_data.sql
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - .framework/migrations/020_schema_reconciliation.sql
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/functions/pipeline-runner-background.ts
+  - .framework/src/App.tsx
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/contexts/AppContext.tsx
+  - .framework/src/hooks/useApps.ts
+  - netlify.toml
+---
+
+# The Spine domain model
+
+Everything in Spine is one of about ten primitives. Once you can name them and
+say how they connect, the whole system — admin UI, APIs, automation — is just
+compositions of the diagram below.
+
+```
+                         ┌──────────────────────── IDENTITY ────────────────────────┐
+                         │                                                        │
+   auth.users (Supabase) │   account ──< people >── role                          │
+        │                │   (tenant,    (human,    (permission                  │
+        │ auth_uid       │    tree via    auth_uid,  set; system_admin           │
+        ▼                │    parent_id   account_id, is the seeded root)         │
+   JWT / x-api-key ──────┤    + account_   role_id)                              │
+        │                │    paths)                                             │
+        ▼                └──────────────────────────┬─────────────────────────────┘
+   principal ─────────── every request resolves one │
+   (anonymous | human | machine | system)           │
+                                                    ▼
+                         ┌──────────────────────── SCHEMA ─────────────────────────┐
+                         │  type (kind + slug) → design_schema → validation_schema  │
+                         │  fields · views · record_permissions · scope             │
+                         └──────────────────────────┬─────────────────────────────┘
+                                                    │ stamped at create
+                                                    ▼
+                         ┌──────────────────────── RECORDS ────────────────────────┐
+                         │  items · threads · messages · links · attachments ·      │
+                         │  watchers  (+ accounts, people as records)               │
+                         │  system columns  +  data jsonb  +  stamped schemas       │
+                         └──────────────────────────┬─────────────────────────────┘
+                                                    │ CRUD via /api/admin-data
+        ┌──────────────────────── APPS ◄────────────┘ renders / consumes
+        │                generic | custom | none    │
+        │  app row: slug, route_prefix, renderer,   ▼
+        │  nav_items, roles              ┌────────────────────── AUTOMATION ───────┐
+        └───────────────┬────────────────┤ triggers (event) → pipelines (stages)  │
+                        │ seeds/owns     │ timers (cron/interval/once) ──┘        │
+                        ▼                │ integrations (adapters+creds)          │
+        ┌──────────────────────── AI ────┤ ai_agents · prompt_configs ·           │
+        │  embeddings (pgvector search)  │ embeddings                            │
+        └────────────────────────────────┴──────────────┬────────────────────────┘
+                                                        ▼
+                         ┌──────────────────────── OBSERVE ────────────────────────┐
+                         │ logs · observability · pipeline_executions ·            │
+                         │ trigger_executions · webhook_deliveries ·               │
+                         │ api_key_usage_logs · audit                              │
+                         └─────────────────────────────────────────────────────────┘
+```
+
+## Identity: account → person → role → principal
+
+- **Account** (`public.accounts`) — the tenant. Accounts form a hierarchy via
+  `parent_id` + the `account_paths` closure table; the seeded `spine-system`
+  account is the platform root
+  (`.framework/migrations/011_spine_system_account.sql`).
+- **Person** (`public.people`) — a human user, bound to `auth.users` by
+  `auth_uid`, placed in one `account_id`, holding one `role_id`. Like every
+  runtime record, a person row also carries `type_id` and `data`.
+- **Role** (`public.roles`) — a named permission set with a globally unique
+  `slug`. `system_admin` is seeded, protected, and bypasses record-level
+  checks (`.framework/migrations/003_core_system_data.sql`).
+- **Principal** — the *resolved* identity of a request, computed per call by
+  `.framework/functions/_shared/principal.ts`: `x-api-key` header → machine
+  principal (verified against `api_keys` hash), internal-invoke headers →
+  cron/trigger/system, `Authorization: Bearer` JWT → human principal, anything
+  else → anonymous. Handlers receive it as `ctx.principal` with
+  `ctx.accountId`.
+
+## Schema: type → design_schema → validation_schema
+
+A **type** (`public.types`) is the schema for a record kind. `kind` selects the
+runtime table — `item`, `thread`, `message`, `link`, `attachment`, `watcher`,
+`account`, `person` — and `(kind, slug)` is unique. Its `design_schema` JSON
+carries:
+
+- `fields` — each with `data_type`, `label`, `required`, and optional
+  `system` flag.
+- `views` — `default_list` / `default_detail` consumed by the generic UI.
+- `record_permissions` — per-role base grant of `create`/`read`/`update`/
+  `delete`; `fields.*.permissions` exists only to *override* that base per
+  field (`.framework/functions/_shared/permissions.ts`).
+- `scope` — `account` (tenant data, the default) or `platform` (record is
+  re-anchored to the `spine-system` account at create).
+
+`validation_schema` is **generated from `design_schema`** on every save
+(`.framework/functions/types.ts` via `_shared/schema-utils.ts`) — never
+hand-edit it.
+
+## Records: the runtime tables
+
+Six typed record tables — `items`, `threads`, `messages`, `links`,
+`attachments`, `watchers` — plus `accounts` and `people` in the same shape
+(`.framework/migrations/001_core_schema.sql`). Every record has:
+
+- **system columns** — `id`, `type_id`, `account_id`, `app_id`, `created_at`,
+  `updated_at`, `created_by`, `is_active`, plus kind-specific ones
+  (`items.title/status`, `threads.target_type/target_id`,
+  `messages.thread_id/sequence`, `links.source_*/target_*`,
+  `attachments.storage_path`, `watchers.person_id`).
+- **`data` jsonb** — where all non-system schema fields live. Convention:
+  `system: true` fields read from `record.<field>`; everything else from
+  `record.data.<field>` (see `GenericDetailPage` splitting on
+  `fieldDef.system` in `.framework/src/components/app-shell/GenericDetailPage.tsx`).
+- **stamped `design_schema` + `validation_schema`** — copied from the type at
+  create time by `admin-data` (`create` in `.framework/functions/admin-data.ts`),
+  so the record is the source of truth for its own permissions even if the
+  type changes later.
+
+All CRUD flows through `/api/admin-data` (`action=list|get|stats|create|
+update|remove`, `entity=<table>`; GET for reads, POST/PATCH/DELETE for writes). The handler maps entity → kind
+(`ENTITY_TO_KIND`), resolves `type_slug`/`type_id`, evaluates record/field
+permissions, writes, then fires create/update/delete triggers.
+
+## Apps: registry + two renderers
+
+An **app** (`public.apps`) is a registered application: `slug`,
+`route_prefix`, `renderer`, `nav_items`, `min_role`/`required_roles`,
+`config`, `is_active`, `is_system`. The authenticated router
+(`.framework/src/App.tsx`) mounts every routable app at its `route_prefix`:
+
+- **`renderer: 'generic'`** — `GenericAppShell` builds the UI *from data*: the
+  sidebar comes from `nav_items`, and each nav item with a `type_slug` gets
+  list/new/detail routes rendered by `GenericListPage`/`GenericDetailPage`
+  straight from the type's `views`
+  (`.framework/src/components/app-shell/GenericAppShell.tsx`).
+- **`renderer: 'custom'`** — `CustomAppLoader` lazy-loads
+  `custom/apps/<slug>/index.tsx` (falling back to
+  `.framework/src/apps/<slug>/index.tsx`)
+  (`.framework/src/components/CustomAppLoader.tsx`). Custom apps render their
+  own pages but still use `/api/admin-data` for record CRUD.
+- **`renderer: 'none'`** — registry-only; not routable.
+
+## Automation: triggers → pipelines, timers → pipelines
+
+- **Pipeline** (`public.pipelines`) — a `stages` array executed in order by
+  `runPipeline` (`.framework/functions/_shared/pipeline-runner.ts`). Each
+  stage's `stage_type` resolves to a `public.actions` row or a built-in
+  handler (`update_item`, `create_record`, `http_request`,
+  `send_notification`, `send_email`, `run_pipeline`, `query_items`,
+  `agent_inference`, `search_knowledge`, `generate_embeddings`,
+  `revoke_embeddings`, `kb_ingest`, `kb_revoke`, `create_interaction`).
+  Every run writes a `pipeline_executions` row.
+- **Trigger** (`public.triggers`) — `event_type` + `pipeline_id` (+ optional
+  `config` filters). `admin-data` calls `fireCreate/Update/DeleteTriggers`
+  after each write; events are named `<entity>_<created|updated|deleted>`
+  (e.g. `item_created`). A match enqueues a `pipeline_executions` row and
+  dispatches to the `pipeline-runner-background` function over HTTP — which
+  requires `INTERNAL_INVOKE_SECRET` to be set
+  (`.framework/functions/_shared/trigger-engine.ts`).
+- **Timer** (`public.timers`) — `timer_type` (`interval` | `cron` | `once`) +
+  `pipeline_id` + schedule in `config`. The scheduled function
+  `trigger-scheduler` (every minute, `netlify.toml`) runs `system-cron`,
+  which calls the `get_due_timers` RPC and executes each due timer's pipeline
+  under a `timer:*` machine principal
+  (`.framework/functions/system-cron.ts`).
+
+## Integrations and AI
+
+- **Integration** (`public.integrations`) — a named adapter + `config` +
+  `credentials` (`{"env_var": "NAME"}` resolved in the function environment,
+  or a literal `{"value": …}`). Inbound webhooks arrive via
+  `integration-routes`; outbound calls go through `integration-outbound`,
+  which records each attempt in `public.webhook_deliveries` (the deliveries
+  ledger — `system-cron` retries pending ones via
+  `.framework/functions/_shared/retry-deliveries.ts`).
+- **AI agent** (`public.ai_agents`) — a model/prompt/tool config invocable via
+  `/api/ai-agents?action=run` or the `agent_inference` pipeline stage.
+  **Prompt config** (`public.prompt_configs`) — named, versioned prompt
+  templates agents and stages reference.
+- **Embedding** (`public.embeddings`) — pgvector vectors with the
+  `match_embeddings` / `search_similar_embeddings` RPCs
+  (`.framework/migrations/004_core_rpc_and_broker.sql`), powering semantic
+  search and the `search_knowledge` stage type.
+
+## Observability: everything leaves a trail
+
+`public.logs` (per-account log stream), `public.observability` (metrics),
+`pipeline_executions` + `trigger_executions` (automation history),
+`webhook_deliveries` (outbound attempts), `api_key_usage_logs` (machine
+principal usage), and audit events emitted by `emitAudit` on privileged
+actions. The admin UI surfaces them under Observability, Deliveries, and
+Executions (`.framework/functions/logs.ts`,
+`.framework/functions/observability.ts`,
+`.framework/functions/pipeline-executions.ts`,
+`.framework/functions/deliveries.ts`).
+
+## Where to go next
+
+- Entity deep-dives: [types](../types.md), [apps](../apps.md),
+  [roles](../roles.md), [pipelines](../pipelines.md),
+  [triggers](../triggers.md), [timers](../timers.md),
+  [integrations](../integrations.md), [ai-agents](../ai-agents.md),
+  [prompts](../prompts.md), [api-keys](../api-keys.md),
+  [deliveries](../deliveries.md).
+- Build something: [04-first-app.md](./04-first-app.md).
+- Terminology: [05-glossary.md](./05-glossary.md).

package/.framework/src/instructions/guide/04-first-app.md

@@ -0,0 +1,227 @@
+---
+title: Build your first app
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/types.ts
+  - .framework/functions/apps.ts
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - .framework/src/components/app-shell/GenericListPage.tsx
+  - .framework/src/components/app-shell/GenericDetailPage.tsx
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/contexts/AppContext.tsx
+  - .framework/src/lib/api.ts
+  - .framework/cli/commands/create-app.ts
+  - .framework/cli/commands/generate.ts
+  - .framework/cli/commands/install-app.ts
+---
+
+# Build your first app
+
+The smallest useful Spine app is one type + one app row — no code at all.
+This walkthrough builds a `task` tracker end to end, then adds a custom page
+and a pipeline. You need a `system_admin` login (see
+[01-install-and-first-run.md](./01-install-and-first-run.md)) — app creation
+is restricted to system admins (`.framework/functions/apps.ts`).
+
+## Step 1 — define the type
+
+Admin UI → **Configs → Types → New** (or `POST /api/types`). Set:
+
+- **Kind**: `item` — records land in `public.items`.
+- **Slug**: `task` — unique within `kind`; callers resolve types by it.
+- **Design schema** — the fields, views, and permissions below.
+
+```json
+{
+  "scope": "account",
+  "fields": {
+    "title":    { "data_type": "text",   "label": "Title",    "required": true,  "system": true },
+    "status":   { "data_type": "select", "label": "Status",   "required": true,
+                  "options": ["todo", "doing", "done"] },
+    "priority": { "data_type": "select", "label": "Priority", "required": false,
+                  "options": ["low", "normal", "high"] },
+    "notes":    { "data_type": "textarea", "label": "Notes",  "required": false }
+  },
+  "views": {
+    "default_list": {
+      "type": "list", "display": "table", "label": "Tasks",
+      "fields": {
+        "title":      { "sortable": true, "display_type": "text" },
+        "status":     { "sortable": true, "display_type": "badge" },
+        "priority":   { "sortable": true, "display_type": "badge" },
+        "created_at": { "sortable": true, "display_type": "timestamp" }
+      },
+      "default_sort": { "field": "created_at", "direction": "desc" }
+    },
+    "default_detail": {
+      "type": "detail", "label": "Task",
+      "sections": [
+        { "title": "Core",
+          "fields": {
+            "title":    { "display_type": "input" },
+            "status":   { "display_type": "select" },
+            "priority": { "display_type": "select" },
+            "notes":    { "display_type": "textarea" }
+          } }
+      ]
+    }
+  },
+  "record_permissions": {
+    "system_admin": ["create", "read", "update", "delete"],
+    "engineering":  ["create", "read", "update"]
+  },
+  "functionality": null
+}
+```
+
+On save, `validation_schema` is regenerated from `design_schema` by the types
+API (`.framework/functions/types.ts`,
+`.framework/functions/_shared/schema-utils.ts`) — you never write it yourself.
+The rules that matter here: `select` fields need `options`; `title` is
+`system: true` so it maps to the `items.title` column while `status`,
+`priority`, and `notes` live in `items.data`; `record_permissions` is the base
+grant evaluated on every `/api/admin-data` call, and its keys are matched
+**verbatim** against `roles.slug` — so use real seeded slugs (`system_admin`,
+`engineering`, `support`, …); a nonexistent or misspelled slug silently grants
+nothing (`.framework/functions/_shared/permissions.ts`).
+
+## Step 2 — register the app
+
+Admin UI → **Configs → Apps → New** (or `POST /api/apps`):
+
+```json
+{
+  "slug": "taskboard",
+  "name": "Taskboard",
+  "route_prefix": "/taskboard",
+  "renderer": "generic",
+  "min_role": "engineering",
+  "is_active": true,
+  "nav_items": [
+    { "id": "tasks", "label": "Tasks", "path": "tasks", "type_slug": "task" }
+  ]
+}
+```
+
+`route_prefix` mounts the app at `/taskboard`; `renderer: "generic"` tells the
+router to use `GenericAppShell`; each `nav_items` entry with a `type_slug`
+gets list, `new`, and `:id` routes rendered from the type's views
+(`.framework/src/components/app-shell/GenericAppShell.tsx`,
+`GenericListPage.tsx`, `GenericDetailPage.tsx`). An app is routable when it
+has a `route_prefix` and a renderer other than `none`
+(`.framework/src/contexts/AppContext.tsx`).
+
+Sign out/in (or wait for the apps registry refetch) and `/taskboard` renders
+the Tasks list — create, edit, sort, and detail all work with zero code.
+
+## Step 3 — add custom UI
+
+When the generic views are not enough, switch `renderer` to `custom` and put
+your code where the loader looks for it:
+
+```bash
+npx spine-framework create-app taskboard --role engineering
+```
+
+This scaffolds `custom/apps/taskboard/` with `manifest.json`, `index.tsx`
+(a React Router stub), and `components/`, and registers the `apps` row with
+`renderer: 'custom'` (`.framework/cli/commands/create-app.ts` — if the row
+already exists it skips the insert). `CustomAppLoader` lazy-loads
+`custom/apps/taskboard/index.tsx` via `import.meta.glob`
+(`.framework/src/components/CustomAppLoader.tsx`), so edit the component, then:
+
+```bash
+npm run dev:netlify   # assemble runs automatically; or: npm run assemble && netlify dev
+```
+
+Your app is a normal React app under the `/taskboard/*` route, inside
+`AppWrapper`. Custom functions go in `custom/functions/` (prefix filenames
+`custom_` — assembly hard-fails on basename collisions with framework
+functions; see [02-project-map.md](./02-project-map.md)).
+
+## Step 4 — CRUD via `/api/admin-data`
+
+Custom pages use the same endpoint as the generic renderer — never write a
+bespoke CRUD function:
+
+```ts
+import { apiFetch } from '@core/lib/api'   // assembled alias → .framework/src
+
+// list
+await apiFetch('/api/admin-data?action=list&entity=items&type_slug=task&limit=50')
+
+// create — type_slug resolves the type; non-system fields go in `data`
+await apiFetch('/api/admin-data?action=create', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    entity: 'items',
+    type_slug: 'task',
+    title: 'Ship the docs',
+    data: { status: 'todo', priority: 'high' }
+  })
+})
+
+// update — entity + id are query params; the body is the field patch
+await apiFetch('/api/admin-data?action=update&entity=items&id=<uuid>', {
+  method: 'PATCH',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ data: { status: 'doing' } })
+})
+
+// remove — soft-deletes (is_active = false) unless soft=false is passed
+await apiFetch(`/api/admin-data?action=remove&entity=items&id=<uuid>`, { method: 'DELETE' })
+```
+
+`apiFetch` (`.framework/src/lib/api.ts`) attaches the Supabase Bearer token and
+the `X-Account-Id` header; `admin-data` resolves `task` → its `type_id`,
+stamps `design_schema`/`validation_schema` onto the new record, evaluates
+`record_permissions` for the caller's role, writes, and fires
+`item_created` triggers (`.framework/functions/admin-data.ts`).
+
+## Step 5 — wire a pipeline
+
+1. Admin UI → **Configs → Pipelines → New**: name it, `trigger_type` =
+   `event`, `stages` = e.g. a `send_notification` stage
+   (`.framework/functions/_shared/pipeline-runner.ts` has the built-in
+   `stage_type` list).
+2. Admin UI → **Configs → Triggers → New**: `event_type` = `item_created`,
+   `pipeline_id` = the pipeline from step 1, `config.type_slug` = `task` to
+   scope it (`.framework/functions/_shared/trigger-engine.ts`).
+3. Ensure `INTERNAL_INVOKE_SECRET` is set — trigger dispatch POSTs to the
+   `pipeline-runner-background` function and silently no-ops without it.
+4. Create a task → the trigger queues a `pipeline_executions` row and the
+   background runner executes the stages; watch it under
+   **Observability → Executions**.
+
+## Gaps
+
+- **`npx spine-framework generate` was removed.** The old scaffold wrote
+  stubs to a `v2-custom/` tree with `../v2-core/...` imports and a legacy
+  `design_schema` shape (`type`/`layout` instead of `data_type`/`views`). It
+  now prints migration guidance and exits 1
+  (`.framework/cli/commands/generate.ts`). Author types in the admin UI or via
+  `/api/types` instead.
+- **`create-app` defaults `--role member`.** `member` and `member_admin`
+  are seeded by `.framework/migrations/073_seed_member_roles.sql` (003
+  seeds `system_admin`, `engineering`, `engineering_admin`, `product`,
+  `docs`, `qa`, `devops`, `management`, `sales`, `csm`, `tam`, `support`,
+  `support_admin`), so the default is valid on current installs. On a
+  database that predates 073, pass `--role` a slug that exists in your
+  `roles` table or create the role first.
+- **`create-app` scaffold is minimal** — a `Routes` stub only. There is no
+  generated CRUD page, `admin-data` hook, or seed block in the manifest it
+  writes; the pattern in Step 4 is the integration contract.
+- **Generic renderer is list/detail only.** `GenericAppShell` generates routes
+  solely for nav items carrying `type_slug`; a nav item without one renders a
+  sidebar button that navigates nowhere routable. Dashboards, wizards, or
+  bespoke layouts require `renderer: 'custom'`.
+- **No packaged example app ships in the npm package** — `custom/` is created
+  empty by `init`, so there is no reference implementation to copy inside an
+  installed project.

package/.framework/src/instructions/guide/05-glossary.md

@@ -0,0 +1,183 @@
+---
+title: Glossary
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - .framework/migrations/011_spine_system_account.sql
+  - .framework/migrations/020_schema_reconciliation.sql
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/system-cron.ts
+  - .framework/cli/lib/project-files.ts
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - scripts/assemble.sh
+  - scripts/assemble-frontend.sh
+  - scripts/assemble-functions.sh
+---
+
+# Glossary
+
+The Spine vocabulary, in dependency order. Terms in **bold** are defined
+elsewhere on this page or in the [domain model](./03-domain-model.md).
+
+## Identity
+
+**account** — a tenant boundary (`public.accounts`). Every runtime record is
+scoped to an `account_id`; accounts nest via `parent_id` with the
+`account_paths` closure table for descendant lookups. The seeded `spine-system`
+account is the platform root (see **scope**).
+
+**person** — a human user (`public.people`), linked to Supabase `auth.users`
+by `auth_uid` and placed in one account with one role. Non-first,
+non-invited signups have no account until registration placement assigns one.
+
+**principal** — the resolved identity attached to a request (`ctx.principal`),
+computed per call by `.framework/functions/_shared/principal.ts`. One of:
+`human` (Bearer JWT → person), `machine` (`x-api-key` header → API key, or
+internal cron/trigger principal), `system` (internal invoke), or `anonymous`.
+Carries `id`, `type`, `accountId`, `roles`, `scopes`, and provenance.
+
+**role** — a named permission set (`public.roles`, unique `slug`) assigned to
+a person. Roles are referenced throughout `design_schema.record_permissions`.
+`system_admin` is the seeded superuser role; roles ending in `_admin` can
+manage invites/members within their own account.
+
+## Schema
+
+**type** — the schema definition for a record kind (`public.types`), unique
+per `(kind, slug)`. Carries `design_schema` (generated into
+`validation_schema`), `ownership` (`system` | `app` | `tenant`), `icon`,
+`color`, `is_active`.
+
+**design_schema** — the authoring-format JSON on a type: `fields`, `views`,
+`record_permissions`, `scope`, `functionality`. See [types](../types.md) and
+the worked example in [04-first-app.md](./04-first-app.md).
+
+**validation_schema** — the runtime-format schema derived from
+`design_schema` on every save by `.framework/functions/types.ts` /
+`.framework/functions/_shared/schema-utils.ts`. Read-only; used to validate
+record writes.
+
+**kind** — which runtime table a type governs: `item`, `thread`, `message`,
+`link`, `attachment`, `watcher`, `account`, `person` (the `ENTITY_TO_KIND`
+map in `.framework/functions/admin-data.ts`).
+
+**runtime record** — a row in one of the typed tables (`items`, `threads`,
+`messages`, `links`, `attachments`, `watchers`, `accounts`, `people`). Always
+has `type_id`, `account_id`, `data` jsonb, and the `design_schema`/
+`validation_schema` stamped at creation.
+
+**system field** — a `design_schema` field flagged `system: true`, stored as
+a real table column and read as `record.<field>` (e.g. `title` →
+`items.title`). Non-system fields live in `data` and read as
+`record.data.<field>` (split implemented in
+`.framework/src/components/app-shell/GenericDetailPage.tsx`).
+
+## Apps
+
+**app** — a registered application (`public.apps`): `slug`, `route_prefix`,
+`renderer`, `nav_items`, `min_role`/`required_roles`, `config`, `is_active`,
+`is_system`. Appears in the authenticated router when it has a
+`route_prefix` and `renderer != 'none'`
+(`.framework/src/contexts/AppContext.tsx`).
+
+**renderer** — how an app's UI is produced. `generic` = schema-driven shell
+(`GenericAppShell` renders `nav_items` → list/detail pages from type views).
+`custom` = lazy-loaded React entry (`custom/apps/<slug>/index.tsx`, falling
+back to `.framework/src/apps/<slug>/index.tsx`) via
+`.framework/src/components/CustomAppLoader.tsx`. `none` = registry-only, not
+routed.
+
+**manifest** — two meanings, both frozen JSON contracts: (a) an app
+`manifest.json` in `custom/apps/<slug>/` declaring routes, `nav_items`,
+`required_roles`, `registration`, and a `seed` block consumed by
+`install-app`/`seed-app`/`update-db-app`
+(`.framework/cli/commands/install-app.ts`); (b) `.spine-manifest.json`, the
+project's frozen integrity manifest of per-file sha256 hashes
+(`.framework/cli/lib/project-files.ts`).
+
+## Automation
+
+**pipeline** — a multi-step workflow (`public.pipelines`, `stages` jsonb)
+executed by `runPipeline` in
+`.framework/functions/_shared/pipeline-runner.ts`. Each stage's `stage_type`
+maps to a `public.actions` row or a built-in handler (`http_request`,
+`send_notification`, `agent_inference`, `query_items`, …).
+
+**trigger** — an event subscription (`public.triggers`): `event_type` +
+`pipeline_id` + optional `config` filters. `admin-data` emits
+`<entity>_<created|updated|deleted>` events (e.g. `item_created`); matching
+triggers enqueue an execution and dispatch the pipeline via the
+`pipeline-runner-background` function (requires `INTERNAL_INVOKE_SECRET`).
+
+**timer** — a schedule (`public.timers`): `timer_type`
+(`interval` | `cron` | `once`) + `pipeline_id`. The `trigger-scheduler`
+Netlify scheduled function (every minute, `netlify.toml`) runs `system-cron`,
+which runs due timers through `runPipeline` under a `timer:*` principal.
+
+**integration** — a named external connection (`public.integrations`):
+adapter slug + `config` + `credentials` (`env_var` reference or literal
+`value`). Inbound webhooks arrive via `integration-routes`; outbound calls
+via `integration-outbound` write **deliveries**.
+
+## AI
+
+**prompt config** — a named, versioned prompt template
+(`public.prompt_configs`) referenced by AI agents and pipeline stages.
+
+**AI agent** — a reusable model + prompt + tool configuration
+(`public.ai_agents`), invocable via `/api/ai-agents?action=run` or the
+`agent_inference` pipeline stage.
+
+**embedding** — a pgvector embedding (`public.embeddings`) queried through
+the `match_embeddings`/`search_similar_embeddings` RPCs; backs semantic
+search and knowledge stages.
+
+## Access and delivery
+
+**API key** — a machine credential (`public.api_keys`) presented as the
+`x-api-key` header; resolved by prefix and verified against a stored hash
+(`.framework/functions/_shared/principal.ts`,
+`.framework/functions/_shared/hash-api-key.ts`). Has `rate_limit` and usage
+logged in `api_key_usage_logs`.
+
+**delivery** — an outbound delivery attempt record
+(`public.webhook_deliveries`) written by `integration-outbound`; retried by
+`retry-deliveries` inside `system-cron`. See [deliveries](../deliveries.md).
+
+**execution** — a run record: `pipeline_executions` for pipelines,
+`trigger_executions` for trigger fires, `schedule_executions` for scheduled
+actions. Statuses progress `queued` → `running` → `completed`/`failed`.
+
+**audit log** — privileged-action events written by `emitAudit`
+(`.framework/functions/_shared/audit.ts`) plus the `public.logs` stream —
+e.g. `trigger.fired`, `app.created`, `app.version_updated`.
+
+## Project layout
+
+**scope** — `design_schema.scope`: `account` (records belong to the caller's
+tenant, the default) or `platform` (`admin-data` re-anchors created records
+to the `spine-system` account).
+
+**assembled** — `.assembled/`, the generated build tree:
+`.assembled/src` (framework frontend + verbatim `custom/apps/<slug>/`) and
+`.assembled/netlify/functions` (flattened functions for Netlify), produced by
+`npm run assemble` (`scripts/assemble.sh`).
+
+**`.framework/`** — the sealed, framework-owned tree vendored into your
+project. Checksummed in `.spine-manifest.json`; overwritten by
+`npx spine-framework upgrade`. See
+[02-project-map.md](./02-project-map.md).
+
+**CIL** — the Code Intelligence Layer: Spine's code-intelligence subsystem
+(ingested code chunks, embeddings, and a searchable project graph) surfaced
+under the admin `cil` pages (`.framework/src/pages/admin/cil/`). Optional;
+your apps do not depend on it.