spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/concepts/auth-and-api-keys.md

@@ -0,0 +1,133 @@
+---
+title: "Auth: sessions, API keys, and invites"
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/hash-api-key.ts
+  - .framework/functions/_shared/rate-limit.ts
+  - .framework/functions/api-keys.ts
+  - .framework/functions/invites.ts
+  - .framework/functions/integration-routes.ts
+  - .framework/migrations/035_rate_limits.sql
+  - .framework/migrations/052_registration_security.sql
+---
+
+# Auth: sessions, API keys, and invites
+
+Every request to a Spine function resolves to one **Principal**
+(`_shared/principal.ts`): either `type: 'human'` (a `people` row + roles) or
+`type: 'machine'` (an `api_keys` row + scopes), plus `ANONYMOUS_PRINCIPAL` and
+`SYSTEM_PRINCIPAL` sentinels. `resolvePrincipal` is the single dispatch point,
+run by `createHandler` / `createPublicHandler` in `_shared/middleware.ts`:
+
+1. `x-api-key` header → **machine** principal.
+2. A valid `INTERNAL_INVOKE_SECRET` (function-to-function) → `x-cron-id` /
+   `x-trigger-id` impersonation, else `SYSTEM_PRINCIPAL`. These headers are
+   honored only alongside the secret — a bare id is ignored.
+3. `Authorization: Bearer <jwt>` → **human** principal via Supabase auth.
+4. Nothing → `ANONYMOUS_PRINCIPAL` (machine, no scopes, no account).
+
+The principal also selects the database client (`getPrincipalDb`): humans get a
+JWT-scoped client (row-level security applies); machines and anonymous get the
+service-role client, so endpoint code is responsible for checking machine
+scopes — `machineHasScope` honors `resource:action`, `resource:*`, and `*:*`,
+and `admin-data` treats a machine with `*:*` as authorized (with role
+`system_admin`) while lesser keys still pass through record permissions.
+
+## Browser sessions (humans)
+
+`Bearer <supabase-jwt>` → `supabase.auth.getUser` → `resolveInternalPersonId`
+binds the auth user to a `people` row by `auth_uid` (email fallback never
+binds unclaimed invite stubs), then loads the person with its role join. The
+principal carries `roles: [role.slug]`, `accountId`, and the raw JWT in
+`authContext` (never serialized — `formatPrincipalForAudit` omits it). Results
+cache for 60 seconds per warm instance, so role/account changes take up to a
+minute to propagate; a person with neither `account_id` nor `role_id`
+(registration not yet placed) is never cached.
+
+A human's effective rights come from `roles` → `isSystemAdmin` /
+`humanHasRole` → the `design_schema.record_permissions` on each type. An
+invalid or expired JWT silently becomes anonymous — endpoints then fail with
+"Authentication required" / "Account context required" rather than 401s.
+
+## API keys (machines)
+
+Mint a key with `POST /api/api-keys` (`.framework/functions/api-keys.ts`):
+`{ name, key_type?, scopes?, rate_limit?, expires_at?, integration_id?,
+app_id?, machine_type?, is_internal? }`. The response returns `raw_key` —
+`sk_<32 hex>` — **once**, with a "store this now" warning. Only the first 8
+characters (`key_prefix`, the lookup index) and a PBKDF2-SHA256 hash
+(100k iterations, `pbkdf2$iterations$salt$hash`) are stored; `omitSecretFields`
+strips secret material from every read response.
+
+Use it as `x-api-key: sk_...` on any function endpoint. Resolution:
+
+- Prefix-matched candidate keys must be `is_active` and unexpired, then the
+  hash is verified with a timing-safe compare.
+- Per-key rate limit: `rate_limit` (default 100) requests per
+  `config.rate_limit_window_seconds` (default 60), counted in
+  `api_key_usage_logs`.
+- Per-IP ceiling: `rate_limit_hit` RPC on `ip:<ip>:<path>`, default 300/minute
+  (`SPINE_IP_RATE_LIMIT`), fail-open.
+- Every request writes an `api_key_usage_logs` row (method, path, IP,
+  user-agent) — `action=usage-logs` on the same endpoint reads them back.
+
+The resulting machine principal inherits `key.scopes`, `key.machine_type`
+(default `'integration'`), `key.is_internal`, and `key.account_id`. A `*:*`
+scope acts as `system_admin`. `integration-routes` (inbound webhooks)
+*requires* a machine principal — a JWT cannot deliver webhooks — and keys
+pinned to `integration_id`/`app_id` are restricted to those integrations.
+Related actions: `action=validate` (verify a key + check permissions),
+`action=revoke` (sets `is_active=false`), `action=usage-logs`.
+
+Shared throttling also applies: `checkRateLimit(ctx, action)`
+(`_shared/rate-limit.ts`) resolves named policies from
+`accounts.data.rate_limits[action]` (account override) or the calling app's
+`config.rate_limits` (with `rate_limit_profile` indirection), and enforces
+them through the atomic `rate_limit_hit` RPC on `public.rate_limits`
+(migration `035`). Over-limit → 429 (`RateLimitError`); a `fail_closed`
+policy → 503 when the counter RPC is unavailable.
+
+## First admin and invites
+
+Bootstrap is a Postgres trigger, not an endpoint: on the first `auth.users`
+signup, `handle_new_auth_user` (migrations `010`, hardened in `052`) takes an
+advisory lock, creates the `people` row, and — only when **no** `people` rows
+exist — grants the `system_admin` role under the `spine-system` account.
+Serialization means two concurrent first signups cannot both become
+system-admin; `system_admin` can never be assigned through registration.
+
+Everyone after that arrives by invite (`.framework/functions/invites.ts`):
+
+- `action=create-invite` — requires `system_admin` or an `*_admin` role on the
+  target account; `role_slug: 'system_admin'` is refused. Creates a stub
+  `people` row holding `data.invite_token` (16-char) and
+  `invite_expires_at` (7 days), returns
+  `{APP_BASE_URL}/register?t=<token>`, and can send the email through a
+  configured email integration.
+- `action=validate-token` (public) — checks the token exists, is unblocked,
+  and unexpired.
+- `action=complete-registration` — after Supabase signup, calls the
+  service-role-only `complete_registration_placement` RPC, which atomically
+  stamps `account_id` + `role_id` from the app's server-side registration
+  config (`new_account`, `existing_account`, `join_request` paths). Client
+  claims about role or target are never trusted — the RPC is the only
+  placement writer.
+- Admin management: `list-invites`, `revoke-invite`, `reinvite`,
+  `block-invite`, `approve`, `deny`, `list-members`, `update-member`,
+  `deactivate-member`. `check-first-user` and `check-domain` are public
+  read-only probes used by the registration UI.
+
+## What each surface can reach
+
+| | Browser JWT | API key | Internal secret |
+|---|---|---|---|
+| Principal | human (roles) | machine (scopes) | system / cron / trigger |
+| DB client | JWT-scoped (RLS) | service role | service role |
+| `admin-data`, entity APIs | role + record permissions | scopes; `*:*` = system admin | full |
+| `integration-routes` (inbound) | no | required | — |
+| `system-cron` / `trigger-scheduler` | no | `SCHEDULER_API_KEY` or internal machine | yes |

package/.framework/src/instructions/concepts/automation.md

@@ -0,0 +1,186 @@
+---
+title: "Automation: pipelines, triggers, and timers"
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/pipelines.ts
+  - .framework/functions/pipeline-executions.ts
+  - .framework/functions/pipeline-runner-background.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/timers.ts
+  - .framework/functions/triggers.ts
+  - .framework/functions/trigger-scheduler.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/admin-data.ts
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/018_runtime_tables.sql
+  - .framework/migrations/020_schema_reconciliation.sql
+  - .framework/migrations/068_cron_schedule_timer_rpcs.sql
+  - netlify.toml
+---
+
+# Automation: pipelines, triggers, and timers
+
+Spine automation is three primitives plus a ledger:
+
+- A **pipeline** (`public.pipelines`) is an ordered JSON `stages` array — the
+  definition of *what runs*.
+- A **trigger** (`public.triggers`) maps a record event
+  (`<kind>_created` / `<kind>_updated` / `<kind>_deleted`) to a pipeline — *when
+  data changes*.
+- A **timer** (`public.timers`) points at a pipeline and carries
+  `next_execution` — *when the clock says so*.
+- A **pipeline execution** (`public.pipeline_executions`) is the durable record
+  of one run — *what actually happened*.
+
+There is no separate "workflow engine" service. Everything runs inside the
+Netlify functions, coordinated through Postgres rows.
+
+## Pipelines and the runner
+
+`runPipeline` in `.framework/functions/_shared/pipeline-runner.ts` is the single
+executor. It loads the pipeline row (inactive or missing pipelines throw),
+creates or claims a `pipeline_executions` row, then walks `pipeline.stages` in
+array order.
+
+Each stage names a `stage_type`. That value is **not** a function name — it is a
+slug looked up in `public.actions` (`eq('slug', stage.stage_type)`,
+`is_active = true`). The action row supplies `handler_module` and `handler`;
+the stage's `config` is merged over `action.config` along with internal keys
+`_pipelineId`, `_executionId`, `_stageIndex`, and `_triggerData`. The runner
+then routes on `handler_module`:
+
+- `functions` — dispatch to a named handler in the runner's `stageHandlers`
+  map. Built-ins include `update_item`, `create_record`, `http_request`,
+  `send_notification`, `send_email`, `run_pipeline`, `query_items`,
+  `search_knowledge`, `agent_inference`, `generate_embeddings`,
+  `revoke_embeddings`, `kb_ingest`, `kb_revoke`, and `create_interaction`.
+- `integrations` — dispatch through `integration-outbound` (the same path
+  outbound webhooks use).
+- `webhook` — POST/GET to `action.config.url` via `integration-outbound`.
+
+Stage config strings support `{{trigger.*}}` and `{{record.*}}` placeholders,
+resolved recursively against the trigger envelope and the firing record's data
+(`record` is `triggerData.entity.data`). Timer- and manual-fired runs have **no
+record context** — `{{record.*}}` placeholders pass through unresolved and
+appear literally in stage output (e.g. notification text). Author timer-driven
+stages against `{{trigger.*}}` or fixed text.
+
+A stage that throws is recorded as `failed` in the stage results; the run then
+aborts **unless** the stage sets `continue_on_error: true`. Completed and
+failed runs both write terminal status, stage results, and duration back to the
+execution row — `pipeline-executions` is therefore the ground truth for "did it
+work", and `status: 'cancelled'` is available for operator-initiated stops.
+
+## Triggers: record events
+
+Writes that go through `admin-data` call into
+`.framework/functions/_shared/trigger-engine.ts`: creates fire
+`fireCreateTriggers`, updates fire `fireUpdateTriggers` with the previous row
+snapshot. (The delete path currently does not invoke `fireDeleteTriggers` —
+`*_deleted` event types exist in the union, but nothing emits them from
+`admin-data`.) Trigger fires are caught-and-logged, so a failing trigger never
+rolls back the write that caused it.
+
+`checkAndFireTriggers` loads active triggers for the event type and evaluates
+each against `config`:
+
+- `config.entity_type` must match the runtime table's kind (`items` → `item`,
+  `people` → `person`, and so on).
+- `config.type_slug` restricts to one `types.slug`; the engine resolves the
+  slug from the record's `type_id` when needed.
+- `config.filters` is a map of path → expected value. Paths support dot
+  notation and Postgres-style `data->>'field'` accessors; expected values may
+  be literals, arrays (membership), or operator objects using `$eq`, `$ne`,
+  `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`.
+- `config.fire_on_transition` makes an update trigger fire only when the record
+  *moves into* the matching state — the previous snapshot must not already
+  match. This is what prevents "every save to a published record re-fires the
+  pipeline".
+
+A matching trigger does **not** run the pipeline inline. It:
+
+1. Inserts a `pipeline_executions` row with `status: 'queued'` (a stable
+   execution id exists before any work starts).
+2. POSTs to `/.netlify/functions/pipeline-runner-background` with an
+   `X-Internal-Secret` header, awaiting only the dispatch ack (bounded by a 5s
+   timeout) — the caller's request never waits for the pipeline to finish.
+3. Records `record_trigger_fire` bookkeeping and emits a `trigger.fired` audit
+   event (or `trigger.failed` on error).
+
+The background function verifies `INTERNAL_INVOKE_SECRET`, reconstructs a
+machine context, and calls `runPipeline` with the pre-created `execution_id`,
+which claims the row `queued → running` instead of inserting a duplicate.
+
+## Timers and the scheduler
+
+A timer row carries `timer_type`, `pipeline_id`, `config`, and
+`next_execution`. The `get_due_timers` RPC returns active timers whose
+`pipeline_id` is set and `next_execution <= now()`; `update_timer_after_run`
+stamps `last_execution`, increments `execution_count`/`success_count`/
+`failure_count`, and reschedules `next_execution` from
+`config.interval_minutes` — a timer with no positive `interval_minutes` gets
+`next_execution = NULL` and never runs again.
+
+The clock is `trigger-scheduler`, a Netlify scheduled function configured for
+`* * * * *` (every minute) in `netlify.toml`. It accepts genuine Netlify
+Clockwork invocations (schedule header or `Netlify Clockwork` user-agent *plus*
+a `{"next_run": ...}` body) and fabricates a system-principal context;
+non-Clockwork calls fall through to the cron handler's own auth, which accepts
+either `?api_key=$SCHEDULER_API_KEY` or an internal machine principal — anything
+else gets 403 and an audit event.
+
+Each tick, `system-cron` does all of the following:
+
+- **Sweeps stale executions** — `sweepStaleExecutions` marks
+  `running`/`pending`/`queued` rows untouched for over 10 minutes as `failed`.
+  This is the safety net for a runner that died mid-flight or a dispatch that
+  never arrived.
+- **Runs due schedules** — `get_due_schedules` → validate the creator → load
+  the `public.actions` row → execute as the schedule's delegated machine
+  principal (`schedules`/`actions`/`schedule_executions` are the runtime
+  scheduling tables).
+- **Runs due timers** — each due timer runs its pipeline as machine principal
+  `timer:<timer_id>` with scope `pipelines:execute`, then
+  `update_timer_after_run` reschedules it.
+- **Evaluates threshold alerts** — `threshold_alerts` rows compare
+  `error_rate`, `latency_p95`, or `pipeline_failure_rate` metrics against a
+  value and fire the alert's `pipeline_id` on breach.
+- **Retries webhook deliveries** — `retryPendingDeliveries` runs every tick.
+- **Cleans logs** — `cleanup_old_logs` runs on the 00:00 UTC tick.
+
+## Observing executions
+
+- `pipeline-executions` (`.framework/functions/pipeline-executions.ts`):
+  `GET` list/get, `action=running`, `action=stats`, `action=cleanup`
+  (`days_to_keep` defaults to 30), plus `start`/`complete`/`cancel`.
+- `pipelines` (`.framework/functions/pipelines.ts`): CRUD plus
+  `action=by-trigger`, `action=executions`, `action=toggle`.
+- `triggers` and `timers` (`.framework/functions/triggers.ts`,
+  `.framework/functions/timers.ts`): CRUD plus `toggle`; triggers also expose
+  `listByEvent` and `getExecutions`.
+- CLI: `spine-framework pipelines run <id>` executes a pipeline;
+  `spine-framework pipelines executions <id>` lists recent runs
+  (`.framework/cli/commands/pipelines.ts`).
+
+An execution stuck in `queued` means dispatch failed before the background
+function claimed it — the sweeper fails it after 10 minutes. An execution stuck
+in `running` means the runner died — same sweeper, same outcome.
+
+## How the pieces connect
+
+1. A client writes a record through `admin-data`; `fireCreateTriggers` /
+   `fireUpdateTriggers` run in-process after the write.
+2. The trigger engine matches the event to active `triggers` rows, inserts a
+   `queued` execution, and dispatches to `pipeline-runner-background`.
+3. Independently, Netlify Clockwork invokes `trigger-scheduler` every minute;
+   `system-cron` runs due timers and schedules through the same `runPipeline`,
+   sweeps dead executions, retries deliveries, and evaluates alert thresholds.
+4. `runPipeline` resolves each `stage_type` through `public.actions` and runs
+   the stage handlers — which is also where outbound integrations, AI agent
+   calls, and embedding jobs enter the system.
+5. Every step lands in `pipeline_executions`, `logs`, and the audit trail,
+   which is what the admin UI and `pipeline-executions` API read.

package/.framework/src/instructions/concepts/concurrency-and-idempotency.md

@@ -0,0 +1,125 @@
+---
+title: "Concurrency and idempotency"
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/_shared/message-sequence.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/retry-deliveries.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/_shared/kb.ts
+  - .framework/cli/commands/migrate.ts
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/035_rate_limits.sql
+  - .framework/migrations/054_kb_ingest_lease.sql
+  - .framework/migrations/064_episode_leases.sql
+  - .framework/migrations/066_episode_steal_thread_merge.sql
+  - .framework/migrations/067_episode_lease_stale_steal.sql
+---
+
+# Concurrency and idempotency
+
+Spine runs on serverless functions: an invocation can die at the response
+flush, a client can retry a request that already succeeded, and two instances
+can race the same resource. Spine's answer is consistent: **the database
+decides**. Ordering, single-flight, and deduplication are enforced by
+constraints and atomic RPCs — never by reading state and deciding in memory.
+
+## Ordered writes: message sequencing
+
+`public.messages` has `UNIQUE(thread_id, sequence)`
+(migration `001_core_schema.sql`) — the hard invariant for conversation order.
+Two writers honor it differently:
+
+- `_shared/message-sequence.ts` (`insertMessageSequenced`) is the simple path:
+  read the max `sequence` for the thread, insert `max + 1`, retry up to 3
+  times on a `23505` duplicate-key error. The retry exists because a racing
+  writer may take the same number; the constraint makes the conflict visible.
+- The agent runner keeps a per-instance counter (`threadSeqCounter`) seeded by
+  one `COUNT(*)` per thread, then allocates locally — a batch of tool-result
+  messages gets consecutive numbers up front so `Promise.all` inserts stay in
+  order. A `23505` triggers a reseed + retry. The counter is an optimization;
+  the unique constraint remains the backstop.
+
+## Pipeline executions: claim, don't create-twice
+
+Trigger dispatches reserve a `pipeline_executions` row with
+`status: 'queued'` *before* calling the background runner. `runPipeline` then
+**claims** that row (`queued → running` on `id = executionId AND status =
+'queued'`) rather than inserting a second execution — a retried or duplicated
+dispatch converges on the same row. If the claim finds nothing, the runner
+falls back to inserting, so an execution record always exists. Rows stuck in
+`queued`/`running`/`pending` for over 10 minutes are swept to `failed` — a
+runner that died mid-flight can never write its own terminal status.
+
+Individual stages can also be idempotent: `create_record` accepts
+`config.dedupe { field, value, account_scoped? }` — when a record matching
+`field = value` already exists, the stage returns the existing row
+(`deduped: true`) instead of inserting a duplicate.
+
+## Webhook deliveries: retry in place
+
+An outbound delivery is one `webhook_deliveries` row for its whole life:
+`pending → processing → delivered | pending | failed`. Retries — automatic
+(`retryPendingDeliveries` each cron tick) or manual
+(`deliveries?action=retry`) — call `integration-outbound` with the existing
+`delivery_id`, which reloads the row, reuses its payload, and increments
+`attempt_count` in place; they never create a second delivery. Backoff is
+exponential (`30s × 2^attempt`, 1h cap, ±20% jitter) until `max_attempts`
+turns the row `failed`; the sweep is bounded (`attempt_count < 10`, 100 rows
+per pass) so one poisoned integration can't monopolize the tick. Inbound
+deliveries get the same row lifecycle, but inbound retry is not implemented —
+a failed inbound delivery stays visible for manual handling.
+
+## Leases: single-flight with fencing
+
+Long-running agent episodes coordinate through `public.episode_leases`
+(migration `064`; service-role only). `acquire_episode_lease` is atomic: an
+`INSERT … ON CONFLICT (thread_id) DO NOTHING` fast path, then a
+`FOR UPDATE` conflict path returning `claimed` + a fresh `lease_token`, or
+`held` + the live holder's `driver_id`. The same driver re-acquiring renews;
+an expired lease is taken over with a new token.
+
+The token is a **fence**, not just a lock:
+
+- `heartbeat_episode_lease(thread_id, lease_token)` extends the TTL only when
+  the token matches — `false` means "you were displaced; stop writing now."
+- `release_episode_lease` is token-gated for the same reason.
+- `merge_thread_data(thread_id, patch, lease_token)` (migration `066`) is the
+  only way episode checkpoints are written: an atomic jsonb merge whose
+  `WHERE` clause refuses the write when a different token holds the lease —
+  so a fenced driver's late write is dropped instead of resurrecting stale
+  state.
+
+Migration `067` adds `p_steal_detached` / `p_stale_seconds`: request-bound
+drivers may steal a lease from a `detached:`-prefixed holder **only** when its
+heartbeat is older than `p_stale_seconds` (default 30). Detached drivers are a
+liveness fallback, never an owner that blocks live work. The same lease shape
+guards knowledge ingest: `document_leases` with
+`acquire_document_lease`/`release_document_lease` (migration `054`), claimed
+by content hash in `_shared/kb.ts`.
+
+## Atomic counters and bookkeeping
+
+- `rate_limit_hit` (migration `035`) upsert-increments the `rate_limits`
+  window counter in one statement — concurrent invocations can't double-spend
+  a window.
+- `record_trigger_fire` (migration `064`) bumps trigger bookkeeping atomically
+  on each fire.
+
+## Migrations: ordered, transactional, ledgered
+
+`spine-framework migrate` (`.framework/cli/commands/migrate.ts`) applies
+`.framework/migrations/*.sql` (plus `custom/migrations/` unless
+`--framework-only`) in **filename order** — the numeric prefix is the order.
+Each file runs inside one transaction together with its ledger insert into
+`_spine_migrations` (`filename UNIQUE`, `applied_at`): a file either lands
+complete with its ledger row or rolls back, and the run stops at the first
+failure. Re-runs skip anything already in the ledger (`--dry-run` lists
+pending without touching the DB). The connection is derived from
+`SUPABASE_URL` (a hosted `*.supabase.co` URL only — no credentials, ports, or
+paths) plus `SUPABASE_DB_PASSWORD`.

package/.framework/src/instructions/concepts/core-vs-custom.md

@@ -0,0 +1,124 @@
+---
+title: Core vs Custom Boundary
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/templates/project.json
+  - .framework/cli/commands/upgrade.ts
+  - .framework/cli/lib/project-files.ts
+  - .framework/cli/commands/migrate.ts
+  - scripts/boundary-check.sh
+  - scripts/assemble-frontend.sh
+  - scripts/assemble-functions.sh
+  - config/vite.config.ts
+  - config/tsconfig.json
+  - config/tsconfig.functions.json
+  - netlify.toml
+---
+
+# Core vs Custom Boundary
+
+Spine projects are two trees with different owners: `.framework/` is the
+sealed, upgradeable package; `custom/` is project-owned code and data the
+package never writes. Everything about the boundary — the alias config, the
+assembly, the upgrade command, the lint script — exists to keep one promise:
+**upgrading the framework can never destroy your work.**
+
+## What lives where
+
+**`.framework/` (core, framework-owned)** — the React app shell and admin UI
+(`.framework/src/`), Netlify functions and shared middleware
+(`.framework/functions/`), ordered SQL migrations (`.framework/migrations/`),
+the CLI (`.framework/cli/`), this instruction book
+(`.framework/src/instructions/`), schemas, seeds, tests, and templates
+(`.framework/templates/`). The shipped file set is declared in
+`.framework/templates/project.json` under `framework_dirs`, `framework_files`,
+`config_files`, `root_scripts`, and `bin`.
+
+**`custom/` (project-owned)** — apps under `custom/apps/<slug>/` (each with a
+`manifest.json` and `index.tsx`), migrations under `custom/migrations/`,
+function handlers under `custom/functions/` and `custom/apps/<slug>/functions`,
+plus tests and vendored packages. This tree is created by `init` / `create-app`
+/ `install-app`; it is not part of the npm package and `upgrade` never writes
+into it.
+
+**Shared but owned:** `config/` (Vite + tsconfig), `netlify.toml`, and the
+`scripts/` assembly-and-integrity scripts ship with the framework and are
+synced on upgrade, with one carve-out — `netlify.toml`
+`[functions."custom_*"]` sections belong to apps and are re-appended verbatim
+by `renderNetlifyToml` in `.framework/cli/lib/project-files.ts`.
+
+## Why the boundary exists: upgrade safety
+
+`npx spine-framework upgrade` is a file sync, not a git operation:
+
+1. It reads `.spine-manifest.json` — frozen per-file hashes written at install
+   — and **aborts if any framework file was locally modified or deleted**
+   unless `--force` is passed (`.framework/cli/commands/upgrade.ts`,
+   `runUpgrade`).
+2. It copies the new package's framework files over yours and deletes only
+   `.framework/` entries that disappeared upstream. Files outside
+   `.framework/` that upstream dropped are warned about, never removed.
+3. It re-merges `package.json` (framework scripts + dependency pin), re-renders
+   `netlify.toml` preserving `custom_*` sections, and regenerates the manifest.
+   New migrations are reported, never run — `npx spine-framework migrate`
+   applies them.
+
+Because overwrite-on-upgrade is guaranteed, the only way a local change inside
+`.framework/` survives is `verify`/`upgrade` treating the tree as sealed. The
+frozen manifest is the integrity contract: `scripts/verify-integrity.sh`
+re-hashes the tree and compares.
+
+## How the boundary is enforced
+
+- **`scripts/boundary-check.sh`** — fails the build if `.framework/` code
+  imports `custom/` or `custom_*` modules, if core source references
+  known app slugs, or if `custom/` code reaches `.framework/` via relative
+  imports instead of the `@core` alias.
+- **Aliases** — `config/tsconfig.json` maps `@core/*` → `.framework/src/*` and
+  `@custom/*` → `custom/*`; `config/vite.config.ts` maps `@core` to the
+  assembled `src` tree. `config/tsconfig.functions.json` maps `@shared/*` to
+  the assembled `_shared/` directory — custom functions import `./_shared/...`
+  at runtime.
+- **Assembly** — `scripts/assemble-frontend.sh` copies `.framework/src` as the
+  base layer and each `custom/apps/<slug>` verbatim into `.assembled/src/<slug>/`;
+  `scripts/assemble-functions.sh` flattens framework + custom handlers into
+  `.assembled/netlify/functions/` and treats duplicate function basenames as a
+  hard error, while letting `custom/` overlay `_shared/` helpers.
+- **Manifest** — `.spine-manifest.json` + `scripts/verify-integrity.sh` seal
+  the `.framework/` tree between upgrades.
+
+## How to extend core without crossing the boundary
+
+Custom code reaches core through three sanctioned channels, in order of
+preference:
+
+1. **Data** — `public.apps` rows, `public.types` `design_schema`, roles,
+   link types, triggers, pipelines. Most "customization" is data.
+2. **Custom apps** — `custom/apps/<slug>/` with a `manifest.json`, mounted by
+   `route_prefix`/`renderer` and loaded dynamically by
+   `.framework/src/components/CustomAppLoader.tsx`.
+3. **Custom functions** — new handler files alongside the assembled
+   `_shared/` layer, for behavior admin-data can't express. Never wrappers
+   for runtime CRUD — that is `/api/admin-data`'s job.
+
+## What breaks if you cross it
+
+- **Core → custom import:** `boundary-check.sh` fails; even if merged, the next
+  `upgrade` overwrites or refuses, and the core now fails in projects lacking
+  that app.
+- **Custom → `.framework/` relative import:** `boundary-check.sh` check 2b
+  fails; the path also breaks under the assembled layout Vite actually builds.
+- **Edit inside `.framework/`:** `verify` reports drift and `upgrade` aborts —
+  or `--force` silently reverts your change. Either way the change was never
+  yours to keep.
+- **Custom runtime-CRUD function:** compiles fine and quietly bypasses
+  permissions, validation, audit, and triggers — the worst kind of violation
+  because nothing fails.
+
+## See also
+
+- [The Spine Way](spine-way.md) — the ten rules this boundary is part of
+- [Apps and Renderers](apps-and-renderers.md) — how `custom/` apps register and mount