spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/guide/01-install-and-first-run.md

@@ -0,0 +1,253 @@
+---
+title: Install and first run
+audience: developers, agents
+kind: guide
+verified_against: d0c49d4
+verified_on: 2026-10-30
+source_files:
+  - .framework/cli/commands/init.ts
+  - .framework/cli/lib/project-files.ts
+  - .framework/templates/project.json
+  - .framework/templates/spine.config.neutral.json
+  - .framework/cli/commands/migrate.ts
+  - .framework/cli/commands/bootstrap.ts
+  - .env.example
+  - netlify.toml
+  - scripts/dev-netlify.sh
+  - scripts/netlify-dev-wrapper.sh
+  - config/vite.config.ts
+  - .framework/public/_redirects
+  - .framework/src/App.tsx
+  - .framework/src/pages/SetupPage.tsx
+  - .framework/src/pages/auth/RegisterPage.tsx
+  - .framework/functions/invites.ts
+  - .framework/migrations/052_registration_security.sql
+---
+
+# Install and first run
+
+Prerequisites: Node ≥ 22.13 and npm ≥ 10 (recorded in `.spine-manifest.json`
+by init), a Supabase project, and (for local dev) the Netlify CLI — pinned as a
+devDependency, so `npm install` puts it in `node_modules`.
+
+## Step 1 — scaffold
+
+```bash
+npm install spine-framework
+npx spine-framework init          # or: init <dir>
+```
+
+Tarball/pre-release installs work the same way: `npm i
+./spine-framework-<ver>.tgz` — `init` keeps the `file:` spec in
+`package.json` rather than overwriting it with a registry version.
+
+`init` (`.framework/cli/commands/init.ts`) copies the framework-owned file set
+declared by `.framework/templates/project.json` into the target directory:
+
+- **`.framework/`** — `cli`, `functions`, `migrations`, `public`, `schemas`,
+  `scripts`, `seeds`, `src`, `tests`, `docs`, `templates`, plus `index.html`
+  and `README.md`.
+- **`config/`** — `vite.config.ts`, the tsconfig family, `tailwind.config.cjs`,
+  `postcss.config.cjs`, `components.json`.
+- **Root files** — the shipped `scripts/*.sh` / `*.mts` / `verify-install.ts`
+  set, `bin/`, `vitest.config.ts`, `.env.example`, `LICENSE.md`.
+- **`custom/`** — the empty workspace `init` creates for your code:
+  `custom/apps`, `custom/functions`, `custom/components`,
+  `custom/migrations`, `custom/tests`.
+- **Generated files** — `package.json` (your name, framework scripts, the
+  framework's dependency set inlined, plus an exact `spine-framework` pin),
+  `package-lock.json` (when the package ships the verified lock template),
+  `.gitignore`, `netlify.toml`, a neutral `spine.config.json`, and the frozen
+  `.spine-manifest.json` integrity manifest.
+- **Agent assets** — `AGENTS.md` (the framework-owned rules block between the
+  `spine-framework:begin/end` markers — refreshed on upgrade; keep your own
+  notes outside the markers) and `.devin/skills/spine-*/` task skills, synced
+  from `.framework/templates/agent/`. These are hashed into the manifest's
+  `agent_files` map rather than `files`.
+
+`init` is deliberately file-only: it does **not** run `npm install`, write
+`.env`, or touch any database or network resource. It refuses to run into a
+directory that already has `.framework/` — that is what
+`npx spine-framework upgrade` is for.
+
+## Step 2 — `.env`
+
+```bash
+cp .env.example .env
+```
+
+Required for a working install (`.env.example` has the full list):
+
+| Variable | Used by |
+|---|---|
+| `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY` | the browser app (`.framework/src/lib/supabase.ts`) |
+| `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_ANON_KEY` | Netlify functions (service-role + user-scoped clients) |
+| `SUPABASE_DB_PASSWORD` | `npx spine-framework migrate` — connects directly to `db.<project-ref>.supabase.co:5432` as `postgres` (`.framework/cli/commands/migrate.ts`) |
+| `APP_BASE_URL` | invite links and auth redirects (`http://localhost:8888` in dev) |
+
+Where to find them: the URL and both keys are on one page — **Supabase
+Dashboard → Project Settings → API Keys** (older dashboards: Settings →
+API / Data API); `SUPABASE_DB_PASSWORD` is under **Project Settings →
+Database**. Current dashboards issue new-style keys: the **Publishable
+key** (`sb_publishable_…`) is the anon key and a **Secret key**
+(`sb_secret_…`) is the service-role key — set `*_ANON_KEY` /
+`SUPABASE_SERVICE_ROLE_KEY` to them directly. Legacy `anon`/`service_role`
+JWTs work identically (verified end-to-end on a hosted project:
+`signInWithPassword`, `auth.admin.createUser`, and PostgREST all accept the
+new formats).
+
+Optional but worth knowing early: `RESEND_API_KEY` (invite/notification
+email), `OPENAI_API_KEY` (AI stage types), `VITE_TURNSTILE_SITE_KEY` (bot
+protection on auth pages), `SCHEDULER_API_KEY` (system-cron HTTP guard), and
+`INTERNAL_INVOKE_SECRET` — **required for trigger-dispatched pipelines**: if it
+is unset, triggers write a `queued` execution row but the pipeline runner is
+never invoked (`.framework/functions/_shared/trigger-engine.ts`).
+
+## Step 3 — install deps and verify
+
+```bash
+npm install
+npm run verify     # scripts/verify-integrity.sh — checks the tree against .spine-manifest.json
+```
+
+Expect `npm audit` findings — the pinned dependency set (mostly the
+`netlify-cli` devDependency tree) carries known advisories, and the count
+jumps between the tarball-only install and the full post-init install. The
+shipped `package-lock.json` template is the verified set: do **not** run
+`npm audit fix`, which moves pinned versions the manifest was generated
+against. Findings are tracked upstream, not per-project.
+
+## Step 4 — migrate the database
+
+```bash
+npx spine-framework migrate
+```
+
+This applies every `.framework/migrations/*.sql` file (and anything in
+`custom/migrations/`, unless `--framework-only`) in order, recording each in a
+`_spine_migrations` table so reruns are idempotent (`--dry-run` shows pending
+files without applying them). File numbering is non-contiguous — retired
+migrations are removed from the package rather than renumbered, so gaps are
+expected and only lexical order matters. The core migration seeds the `system_admin`
+role, the `spine-core` and `admin` apps, the `spine-system` account, and the
+core runtime types (`.framework/migrations/003_core_system_data.sql`,
+`.framework/migrations/011_spine_system_account.sql`).
+
+## Step 5 — run it
+
+```bash
+npm run dev:netlify
+```
+
+`dev:netlify` runs `npm run assemble` first (via `predev:netlify`) and then
+`scripts/dev-netlify.sh`, which cleans stale processes and launches the pinned
+`netlify dev`. Netlify serves the site on **http://localhost:8888** and starts
+the Vite dev server on 3001 via `scripts/netlify-dev-wrapper.sh`.
+**Wait for the "Local dev server ready" banner** — the first `dev:netlify`
+run bundles ~80 functions and can take a couple of minutes before the banner
+appears; this is normal, not a hang. Early requests during function bundling
+can crash the dev server (noted in `scripts/dev-netlify.sh`).
+
+Ports are **fixed**: `netlify dev` must bind 8888 and Vite 3001 — both are
+set in manifest-protected files (`netlify.toml` `[dev]` port/targetPort,
+`config/vite.config.ts`), and there is no supported alternate-port
+configuration. Moving only one side breaks the `/api` proxy and can
+silently cross-connect two Spine projects on the same machine. Check the
+ports are free first (`lsof -i :8888 -i :3001`): `dev-netlify.sh` cleans up
+stale processes it owns but will not kill an unrelated server holding the
+port — a second Spine project's dev stack is the usual culprit; stop that
+one yourself.
+
+Ignore `Failed to fetch AI Gateway token … Unauthorized` in `netlify dev`
+output — that is the Netlify CLI's own AI feature probing your Netlify
+account, unrelated to Spine.
+
+Two URL spaces matter:
+
+- `/api/*` → `/.netlify/functions/:splat`. In dev this is the Vite proxy to
+  `localhost:8888` (`config/vite.config.ts`); in production it is the
+  `_redirects` rule in `.framework/public/_redirects`.
+- Everything else → the React SPA.
+
+`npm run dev` alone starts *only* Vite on 3001 — fine for frontend work, but
+`/api/*` calls still proxy to 8888, so functions need `netlify dev` running.
+
+## First admin — browser-free bootstrap (recommended for automation)
+
+```bash
+npx spine-framework bootstrap --email you@example.com --password '<pick-one>'
+```
+
+This is the scriptable path (`S-002`): it creates the first `system_admin`
+person bound to the `spine-system` account — the same row shape the
+`handle_new_auth_user` trigger writes on registration — creates a confirmed
+auth user through `auth.admin.createUser(email_confirm: true)`, and mints a
+`sk_` API key, all without a browser. The raw key is printed **once**; only
+its PBKDF2 hash is stored. `--scope <scope>` (repeatable) narrows the key —
+the default `*:*` resolves to the `system_admin` role on the machine
+principal. Omit `--email`/`--password` and the person record is created
+DB-only (no UI login; the minted key still works for `x-api-key` callers).
+The command is idempotent: when a `system_admin` already exists in
+`spine-system` it skips person creation and just mints another key
+(`.framework/cli/commands/bootstrap.ts`).
+
+## First login — what actually happens
+
+Alternatively, register in the browser. The real flow, as the code
+implements it:
+
+1. An unauthenticated visitor is redirected to `/login`
+   (`.framework/src/App.tsx`). If `VITE_SETUP_MODE=true` is set, the `/` route
+   instead shows a static `SetupPage` listing the same steps as this page
+   (`.framework/src/pages/SetupPage.tsx`).
+2. Go to `/register` and create an account. **The first user to register gets
+   `system_admin`**: the `handle_new_auth_user` database trigger detects an
+   empty `people` table and binds the new person to the `spine-system` account
+   with the `system_admin` role
+   (`.framework/migrations/052_registration_security.sql`). If the seeds are
+   missing, registration raises instead of creating a rootless user.
+3. Non-first, non-invited signups get **no account and no role** — placement
+   happens when `complete-registration` runs the server-side RPC
+   (`.framework/functions/invites.ts`). An authenticated user without an
+   account is routed to `/register?resume=1` until placement finishes, never
+   to a 404 (`.framework/src/App.tsx`).
+4. After login, a `system_admin` lands on `/spine-framework/admin` — the
+   schema-driven admin app from `.framework/src/apps/admin/index.tsx`. Other
+   users land on the first app their role can see, or `NoAppPage` when nothing
+   is routable.
+
+## Giving your agent access
+
+The verified path for letting an agent (or any machine caller) reach the
+runtime API:
+
+1. **Bootstrap an admin + key** — one step, no browser: `npx
+   spine-framework bootstrap` (see "First admin" above) both creates the
+   `system_admin` and prints a `sk_` key. The browser alternative: register
+   at `/register` (first user becomes `system_admin`), then create a scoped
+   key under **Admin → Configs → API Keys**. Either way the raw key is shown
+   **once** — copy it immediately (`.framework/functions/api-keys.ts`).
+2. **Give the key to the agent** as the environment variable `SPINE_API_KEY`.
+   Agents send `x-api-key: sk_…` on `/api/*` requests; the header resolves to
+   a machine principal carrying the key's scopes and account binding
+   (`.framework/functions/_shared/principal.ts`). Turnstile is not in this
+   path — bot protection only guards the human auth pages.
+
+**Caveat:** for the browser path, Supabase **email confirmation must be
+off** in the project (Auth → Providers), or the first registrant cannot sign
+in without access to a real inbox. `bootstrap` is unaffected — it creates
+the auth user with `email_confirm: true` through the service role.
+
+## Gaps
+
+- **`npx spine-framework dev` runs the same flow as the package scripts** —
+  `scripts/assemble.sh`, then Vite via `config/vite.config.ts` (`--netlify`
+  for the full `netlify dev` stack on :8888). `npm run dev` /
+  `npm run dev:netlify` remain the canonical entry points.
+- **`bootstrap` covers first-run provisioning only.** Subsequent admins are
+  added through the invite flow in the admin app (or another `bootstrap`
+  run, which skips person creation and only mints a new key).
+- **Timers only tick under the Netlify scheduler.** `trigger-scheduler` is a
+  scheduled function (`* * * * *` in `netlify.toml`); pipelines triggered by
+  timers do not run without it, and trigger dispatch additionally needs
+  `INTERNAL_INVOKE_SECRET` (see Step 2).

package/.framework/src/instructions/guide/02-project-map.md

@@ -0,0 +1,147 @@
+---
+title: Anatomy of an installed project
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/templates/project.json
+  - .framework/cli/commands/init.ts
+  - .framework/cli/commands/upgrade.ts
+  - .framework/cli/lib/project-files.ts
+  - scripts/checksum-manifest.mts
+  - scripts/verify-integrity.sh
+  - scripts/assemble.sh
+  - scripts/assemble-frontend.sh
+  - scripts/assemble-functions.sh
+  - config/vite.config.ts
+  - netlify.toml
+  - .framework/cli/commands/create-app.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/schemas/spine.config.schema.json
+---
+
+# Anatomy of an installed project
+
+A Spine project is two concentric layers: a **sealed framework layer** the
+package owns and overwrites on upgrade, and a **customer layer** the framework
+never writes to.
+
+```
+my-project/
+├─ .framework/            # SEALED — framework source, vendored by init/upgrade
+│  ├─ cli/                #   the spine-framework CLI source
+│  ├─ functions/          #   Netlify functions (the whole API surface)
+│  ├─ migrations/         #   SQL migrations applied by `migrate`
+│  ├─ public/             #   static assets + _redirects
+│  ├─ schemas/            #   spine.config.schema.json
+│  ├─ scripts/ seeds/ docs/ templates/
+│  ├─ src/                #   React frontend + admin app + this book
+│  └─ tests/
+├─ config/                # SEALED — build config (vite, tsconfig, tailwind…)
+├─ scripts/               # SEALED — assemble/verify/dev shell scripts
+├─ bin/                   # SEALED — spine-framework bin shims
+├─ custom/                # YOURS — apps, functions, components, migrations, tests
+├─ .assembled/            # GENERATED — build output, never edit
+├─ .spine-manifest.json   # GENERATED — frozen integrity manifest
+├─ spine.config.json      # YOURS — branding + registration policy
+├─ netlify.toml           # mixed — framework blocks + your custom_* sections
+├─ package.json           # merged — framework scripts/deps + your own
+└─ .env                   # YOURS — secrets; never written by the framework
+```
+
+## The sealed layer
+
+The file set is declared in `.framework/templates/project.json`
+(`framework_dirs`, `framework_files`, `config_files`, `root_scripts`, `bin`)
+and every protected file's sha256 is recorded in `.spine-manifest.json` — the
+protected trees are `.framework`, `config`, `scripts`, and `bin`
+(`scripts/checksum-manifest.mts`, `PROTECTED_DIRS`).
+
+- `npm run verify` (`scripts/verify-integrity.sh` → `scripts/verify-manifest.mts`)
+  re-hashes the tree and fails on drift. `SPINE_INTEGRITY=warn` downgrades to
+  warnings.
+- `npx spine-framework upgrade` re-syncs the sealed layer to the
+  `spine-framework` version installed in `node_modules`
+  (`.framework/cli/commands/upgrade.ts`). It first verifies the tree against
+  the manifest and **aborts on any locally modified or missing protected file**
+  unless `--force` is passed — so do not edit `.framework/`, `config/`,
+  `scripts/`, or `bin/`; changes there are destroyed on the next upgrade
+  anyway.
+- Deletions on upgrade are confined to `.framework/`; sealed files dropped
+  upstream outside it are left in place with a warning.
+
+## `custom/` — your code
+
+`init` creates `custom/apps`, `custom/functions`, `custom/components`,
+`custom/migrations`, and `custom/tests` (`.framework/cli/commands/init.ts`).
+Everything in it is yours: not integrity-tracked, never touched by upgrade.
+
+- **Custom apps** live at `custom/apps/<slug>/`.
+  `npx spine-framework create-app <slug>` scaffolds `manifest.json`,
+  `index.tsx`, and `components/`, then inserts the `apps` row with
+  `renderer: 'custom'` (`.framework/cli/commands/create-app.ts`).
+  `CustomAppLoader` resolves the UI via
+  `import.meta.glob('../../../custom/apps/*/index.tsx')`
+  (`.framework/src/components/CustomAppLoader.tsx`), and the Vite alias
+  `@custom` points at `custom/apps` (`config/vite.config.ts`).
+- **Custom functions** live at `custom/functions/` or inside an app at
+  `custom/apps/<slug>/functions/`; assembly merges them into the flat
+  functions directory and hard-fails on basename collisions with framework
+  functions (`scripts/assemble-functions.sh`). Name yours `custom_*`.
+- **Custom migrations** in `custom/migrations/` run with
+  `npx spine-framework migrate` (skip them with `--framework-only`).
+- **Packaged apps** installed via `npx spine-framework install-app <pkg>` also
+  land under `custom/apps/<slug>/`; their `manifest.json` can seed types,
+  roles, pipelines, and registration policy into the database
+  (`.framework/cli/commands/install-app.ts`).
+
+## `.assembled/` — build output
+
+`npm run assemble` (`scripts/assemble.sh`) produces `.assembled/` fresh on
+every dev start and build:
+
+- `.assembled/src` — the framework frontend plus each `custom/apps/<slug>/`
+  copied verbatim (never basename-flattened), plus the fixed-up `index.html`
+  (`scripts/assemble-frontend.sh`). Vite builds and serves from here.
+- `.assembled/netlify/functions` — framework + custom functions flattened into
+  the single directory Netlify requires (`netlify.toml`
+  `functions.directory`); duplicate basenames are a hard error, not a
+  last-wins overwrite (`scripts/assemble-functions.sh`).
+
+Never edit `.assembled/` — it is regenerated and deleted freely.
+
+## `.spine-manifest.json` — the integrity contract
+
+Written by `init` and regenerated by `upgrade`
+(`.framework/cli/lib/project-files.ts` → `writeFrozenManifest`): the package
+version (`framework_version`), the framework-owned dependency list, a tree
+digest, and a sha256 per protected file. It is the input to `npm run verify`
+and to upgrade's local-modification check.
+
+## `spine.config.json` — project runtime config
+
+Customer-owned; `init` seeds the neutral template
+(`.framework/templates/spine.config.neutral.json`) and
+`install-app`/`update-db-app` merge per-app registration policy into it
+(`.framework/cli/commands/install-app.ts`). It carries `branding` and the
+`registration` block that drives signup routing/role assignment — schema at
+`.framework/schemas/spine.config.schema.json`. Upgrade never writes it.
+
+## `netlify.toml` and `package.json` — mixed ownership
+
+- `netlify.toml`: framework blocks are rewritten on upgrade, but
+  `[functions."custom_*"]` sections are treated as app-owned and preserved
+  verbatim (`.framework/cli/lib/project-files.ts` → `splitNetlifyToml` /
+  `renderNetlifyToml`). Scheduled custom functions belong there.
+- `package.json`: framework-owned scripts and dependencies are merged in and
+  `spine-framework` pinned exactly; your own scripts and deps are preserved.
+  Upgrade removes a dependency only if the previous framework version owned it
+  and the new one does not.
+
+## `.env` — yours, always
+
+No framework command writes `.env`; it is gitignored and excluded from the
+file set (`.framework/templates/project.json` `exclude_globs`). `.env.example`
+ships as the documented baseline.

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).