spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/internal/docs-contract.md

@@ -0,0 +1,158 @@
+---
+title: "Docs contract — how the instruction book is written, tested, and kept true"
+audience: developers, agents
+kind: reference
+verified_against: b3b3ae0
+verified_on: 2026-11-01
+source_files:
+  - scripts/docs-lint.mts
+  - .framework/src/instructions/README.md
+  - docs/audit/clean-room-walkthrough.md
+  - .framework/cli/commands/install-app.ts
+  - .framework/cli/commands/validate-app.ts
+---
+
+# Docs contract
+
+This file is the editorial contract for the Spine instruction book and for
+the instruction books that installed apps carry at
+`custom/apps/<slug>/src/instructions/`. It lives under `internal/` because it
+governs the book itself rather than describing the framework.
+
+## The test rule
+
+Every miss is a documentation bug — fix the book, not the test.
+
+The book must carry a cold agent — one with zero memory of this codebase —
+through installation, orientation, and building on Spine without touching
+monorepo-only material. If an agent has to grep `.framework/functions/` to
+answer a customer-facing question, or has to ask the user something that
+isn't a real-world checkpoint (credentials, first-admin choice), the book is
+missing a page, a section, or a line. Write it. Do not explain around the
+gap in the moment and move on.
+
+Corollaries:
+
+- Retrieval beats derivation. A fact an agent can *find* is safe; a fact it
+  has to *derive* from source is a latent bug.
+- Code is truth; docs are interpretation. When they disagree, the doc is
+  wrong — fix the doc and bump `verified_against`/`verified_on`.
+- "It figured it out eventually" is a fail. Time-to-answer is the metric.
+
+## The capture contract
+
+A code change is **incomplete until the docs covering it are re-synced**.
+Docs are part of the change, not a follow-up chore. One rule, two layers:
+
+**Core.** Every book page lists `source_files` in its frontmatter — the code
+files whose behavior the page interprets. Editing any file in that set
+requires re-verifying every page that lists it, in the same change, and
+bumping `verified_against` (commit short hash) and `verified_on` (date).
+`npm run docs:lint` is the gate.
+
+**Custom.** Editing anything under `custom/apps/<slug>/` requires updating
+that app's `src/instructions/` in the same change:
+
+- New or changed page/route → the app's tasks doc and README route map.
+- New or changed function → the app's `reference/functions` page.
+- New or changed seeded type → the app's entity page for that type.
+- New skill → the app's README skills list.
+
+**Capture, not just sync.** Non-obvious decisions, cautions, and traps
+discovered while doing the work are appended to the relevant page's
+`## Agent notes` section — the next cold agent reads what the last one
+learned. Positive-only corrections: update the source; never append
+"correction notes" that contradict an untouched stale claim.
+
+### Relationship to CIL
+
+CIL (Code Intelligence Layer, the `cil_*` tooling used inside this monorepo)
+is **bottom-up code truth**: per-chunk contracts, `stored_hash` drift
+detection, a call/import/test graph, semantic code search. The book is
+**top-down narrative comprehension**: curated prose at system granularity.
+
+Neither replaces the other:
+
+- CIL can *prove* a doc is stale (hash recompute); the book can only *assert*
+  freshness (`verified_*` stamps + lint gate). The capture contract above is
+  the manual stand-in for CIL's automatic re-sync pipeline.
+- The book carries CIL's *purpose* into shipped projects where no `cil_*`
+  tooling runs — it is the portable distillation, not a replacement.
+
+The definition of done for `.framework/` edits in this repo is therefore
+**both**: CIL re-sync (`cil_store_markers` → `cil_generate_embeddings` →
+`cil_generate_mappings` → `cil_validate_file`) for code truth, and book
+re-verify for narrative truth. Mechanical pages (`reference/functions/*`,
+entity field tables) may eventually be generated/verified from CIL chunks;
+narrative layers stay hand-authored.
+
+## Layer taxonomy — which layer answers which question
+
+| Layer | Kind | Answers | Mandatory shape |
+|---|---|---|---|
+| `guide/` | guide | "Walk me through it end to end" | Numbered sequence (`00` → `05`); each step verifiable |
+| `concepts/` | concept | "Why is it like this? What's the mental model?" | Model first, mechanics second; links to tasks |
+| `tasks/` | task | "How do I do X?" | `## Goal` → `## Steps` → `## Verify` → `## Common mistakes` → `## Reference` |
+| `reference/` | reference | "What's the exact spelling/shape?" | Tables over prose; every row verifiable against `source_files` |
+| Entity pages (root) | entity | "What is this thing and how do I configure it?" | The 7-section template (enforced by docs:lint) |
+| `operations/` | ui | "How do I run/diagnose it in the admin UI?" | Runbook steps anchored to real pages/endpoints |
+| `internal/` | * | "How is the book itself maintained?" | Repo-only; exempt from archived-docs and cil_* reference rules |
+
+Frontmatter on every page: `title`, `audience`, `kind`,
+`verified_against`, `verified_on`, `source_files` (list). Exemption:
+`status: LEGACY_UNVERIFIED` — still checked for links and paths.
+
+## Skills
+
+Invocable procedures live in `.devin/skills/spine-*` (framework-owned,
+dir-replaced on upgrade) and `custom/.devin/skills/<prefix>_*`
+(app-owned — see below). A task doc should name its companion skill where
+one exists; a skill should link its task/reference doc.
+
+**App-shipped skills.** An installed app may ship skills under
+`agent/skills/<prefix>_*/` in its package; `install-app` copies them to
+`custom/.devin/skills/` and `uninstall-app` removes `custom/.devin/skills/<prefix>_*`.
+`manifest.agent.skill_prefix` is required when `agent/skills/` exists and
+must match `^[a-z][a-z0-9]{0,7}$` and be unique across installed apps.
+See [App manifest reference](../reference/app-manifest.md) and
+[Document your app](../tasks/document-your-app.md).
+
+## Acceptance matrix — the regression suite
+
+The cold-agent test protocol lives in the repo at
+`docs/audit/clean-room-walkthrough.md`. Each row is a verbatim prompt; the
+pages listed must satisfy it **alone**. New pages earn a row; a failing row
+means the book regressed, not that the agent did.
+
+| # | Verbatim prompt (abridged) | Pages that must carry it |
+|---|---|---|
+| T1 | Explain this project: what's mine vs framework, how do primitives compose, where does my code go, what do I never touch | `guide/00-orientation.md`, `guide/02-project-map.md`, `concepts/core-vs-custom.md`, `concepts/spine-way.md` |
+| T2 | Create a design_schema for a "task" type (fields, selects, permissions, list+detail views) and validate it | `tasks/add-a-type.md`, `reference/design-schema.md`, `concepts/design-schema.md`; skill `spine_schema_validate`/`spine-schema` |
+| T3 | Create the type and register a generic app at /taskboard that lists it — visible in the UI | `tasks/register-an-app.md`, `apps.md`, `reference/app-manifest.md`, `concepts/apps-and-renderers.md` |
+| T4 | Add a custom page that lists tasks with a working create form — no server-side code | `tasks/build-a-custom-page.md`, `reference/frontend-sdk.md`, `reference/api/admin-data.md` |
+| T5 | Wire a pipeline on task create + a 2-minute timer; show a completed execution | `tasks/add-a-pipeline.md`, `tasks/add-a-trigger.md`, `tasks/add-a-timer.md`, `timers.md` |
+| T6 | Add an AI agent with its own prompt config and send a test message | `tasks/add-an-ai-agent.md`, `ai-agents.md`, `prompts.md` |
+| T7 | Package this app; install it into another Spine project; show create/list working | `tasks/package-and-install-an-app.md`, `reference/app-manifest.md`, `reference/seeds.md`; skill `spine-install-app` |
+| T8 | Something broke — creating a task fails / the pipeline fails. Find and fix it | `operations/troubleshooting.md`, `pipeline-executions.md`, `logs.md`, `deliveries.md`; skill `spine-troubleshoot` |
+| T9 | (cold) Create a type, register an app, wire a pipeline — from docs alone | The whole book end to end |
+| M1 | Mount this app at the site root (served from `/`) | `tasks/register-an-app.md`, `apps.md`, `reference/app-manifest.md`, `concepts/apps-and-renderers.md` |
+| M2 | What can I import in a custom app? Build a page using the framework's UI kit | `reference/frontend-sdk.md`, `tasks/build-a-custom-page.md` |
+| M3 | Install this app, then use its shipped skill and its instruction book | `tasks/package-and-install-an-app.md`, `reference/app-manifest.md` (`agent` block), app `src/instructions/` |
+| M4 | You changed file X — which docs did you update? | This contract (capture section), `AGENTS.md` verify rules |
+
+## Authoring checklist for a new page
+
+- [ ] Correct `kind` + full frontmatter; `source_files` lists the real files
+      that produce the page's truth.
+- [ ] Placed in the layer whose question it answers (taxonomy table above).
+- [ ] Linked from `README.md`'s index and from at least one sibling page.
+- [ ] A row in the acceptance matrix if it covers a cold-agent task.
+- [ ] `npm run docs:lint` clean.
+
+## The gate
+
+`npm run docs:lint` (`scripts/docs-lint.mts`, repo-only) checks: required
+frontmatter, kind taxonomy, the 7-section headings on `entity`/`ui` pages,
+relative-link resolution, existence of every backticked `.framework/...`
+path, and (outside `internal/`) no `docs/archive` references and no `cil_*`
+tool references.

package/.framework/src/instructions/invites.md

@@ -0,0 +1,60 @@
+---
+title: Invites & Access
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/pages/admin/InvitesPage.tsx
+  - .framework/src/components/shared/InviteManager.tsx
+  - .framework/functions/invites.ts
+---
+
+## What this is for
+
+**Invites & Access** (`/spine-framework/admin/access/invites`) manages how people join the account: generating invite links, tracking their status, re-sending or revoking them, and approving access requests. The admin page is scoped to the `system_admin` role; the shared `InviteManager` component underneath supports other role sets.
+
+## Fields and settings
+
+- **Generate invite form** — name, email, and role picker (shown only when more than one role is allowed; here it is fixed to `system_admin`). Produces an `invite_url` copied to the clipboard: `{APP_BASE_URL}/register?t=<invite_token>`.
+- **Invites table** — the person's name/email, assigned role, status, and actions: reinvite (new link), revoke, approve (access requests), block.
+- **Status semantics** — `invited`/`pending` (link issued or request awaiting approval), `approved`, `active`/`claimed` (registered), `revoked` (`inactive`), `expired`, `blocked`. `kind` distinguishes `invite` from `access_request`.
+- **Search + sortable columns** over the list from `action=list-invites` (filtered to the allowed role slugs).
+
+**Downstream effects**
+
+- `create-invite` inserts a stub `people` row carrying `invite_token` (16 chars) and `invite_expires_at` (7 days); the register flow consumes the token via `complete-registration` → `complete_registration_placement` RPC.
+- Only `system_admin` (or an `*_admin` role on the account) can create invites; creating an invite for `role_slug: system_admin` is refused unless the caller is already `system_admin`.
+- `revoke-invite` marks the person `inactive`, killing the unclaimed link; `reinvite` mints a fresh token/link. `block-invite`/`deny` handle abusive requests.
+- Registration and account-creation calls are rate-limited per person and per IP.
+
+## Minimal configuration
+
+Fill name + email → Generate → the invite URL lands on your clipboard; send it out of band. The invitee registers within 7 days or you reinvite.
+
+## Full configuration
+
+The backing API (`/.netlify/functions/invites?action=`) also covers the public registration path and member management:
+
+- `check-first-user`, `check-domain`, `validate-token`, `complete-registration` — anonymous signup flow
+- `create-invite`, `list-invites`, `revoke-invite`, `reinvite`, `block-invite`
+- `approve`, `deny` — access-request review
+- `list-members`, `update-member`, `deactivate-member` — existing members
+
+## Example
+
+An admin generates a `system_admin` invite for a new hire, pastes the link into chat. Until they register, the row shows `pending`; if the link is lost, Reinvite mints a new URL and invalidates the old token; if they never join, Revoke marks the stub `inactive`.
+
+## Core files
+
+- `.framework/src/pages/admin/InvitesPage.tsx` — this page (scopes InviteManager to `system_admin`)
+- `.framework/src/components/shared/InviteManager.tsx` — invite list/form/actions (reusable in other apps)
+- `.framework/functions/invites.ts` — API (all actions above)
+- Table: `public.people` (invite stub rows carry `invite_token`/`invite_expires_at`)
+
+## Agent notes
+
+- The invite URL is shown/copied **once** at create/reinvite — the API never returns it again; a lost link means Reinvite, not retrieve.
+- Invites expire after 7 days (`invite_expires_at`); expired rows show `expired` until reinvited or revoked.
+- This admin page is hardcoded to `system_admin` invites; app-level member invites use the same `InviteManager` with a different `allowedRoles` set.
+- Stub invite rows are real `people` rows — they are excluded from normal principal resolution until registration completes.

package/.framework/src/instructions/kb.md

@@ -0,0 +1,80 @@
+---
+title: Knowledge Base
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/pages/admin/kb/KBAdminPage.tsx
+  - .framework/src/components/kb/KBArticleList.tsx
+  - .framework/src/components/kb/KBArticleEditor.tsx
+  - .framework/src/pages/admin/EmbeddingsPage.tsx
+  - .framework/src/pages/admin/EmbeddingDetailPage.tsx
+  - .framework/functions/kb.ts
+  - .framework/functions/embeddings.ts
+  - .framework/functions/admin-data.ts
+---
+
+## What this is for
+
+The **KB** section (`/spine-framework/admin/kb/*`) covers three surfaces that share this doc:
+
+- `kb/:typeSlug` — the article admin list/editor (`KBAdminPage`) for the KB item types `kb-spine-admin`, `kb-spine-internal`, `kb-spine-public`, `kb-account`. Articles are `items` records created/edited via `admin-data` and published via `kb`.
+- `kb/embeddings` — the embedding record browser (`EmbeddingsPage`): every generated embedding row with its approval state.
+- `kb/embeddings/:id` — single embedding detail (`EmbeddingDetailPage`): content, vector type, chunk index, model, approval/revocation timestamps, optional raw vector.
+
+## Fields and settings
+
+**Articles** (`KBArticleList` / `KBArticleEditor`)
+
+- **Type slug tabs** — the four KB type slugs above; articles are `items` records of that type.
+- **List** — title, status, created date; search hits `/api/kb?action=search` (sources `['kb']`).
+- **Editor** — schema-driven form from the type's `design_schema` (main fields + metadata sidebar); Save writes `admin-data` create/update; **Publish** additionally calls `/api/kb?action=publish`; Delete uses `admin-data` remove.
+- **Modes** — `view` (read-only), `edit`, `new` via route (`:id`, `:id/edit`, `new`).
+
+**Embeddings** (`EmbeddingsPage` / `EmbeddingDetailPage`)
+
+- **List** — content/document/model search + sortable columns; status badge: `Revoked` (revoked_at set) > `Approved` (approved_at set) > `Pending`.
+- **Detail** — document_id, vector_type, chunk_index, model_id, token count, content preview, approved/revoked timestamps, and a show-vector toggle for the raw embedding.
+
+**Downstream effects**
+
+- Articles are plain `items` records — they inherit the type's `record_permissions` and `validation_schema`; `kb?action=publish` handles the publishing step (ingest/indexing) on top.
+- Embeddings are generated per type `design_schema.vector_types` (default `['semantic','structure']`) and feed `match_embeddings`/semantic search used by agents and `search_knowledge` pipeline stages.
+- `embeddings` actions: list/get/create/update + `generate`, `revoke`, `approve`, `stats`, `batch-create`, `delete-document`, `cleanup`, `search-similar`, `search-semantic`. `revoke` stamps `revoked_at` (excluded from search); `approve` stamps `approved_at` and clears revocation.
+
+## Minimal configuration
+
+Pick a KB type slug tab → New → fill the schema form → Save → Publish. The article is now searchable via `kb?action=search`.
+
+## Full configuration
+
+```jsonc
+// article write — POST /api/admin-data?entity=items
+{ "type_id": "kb-account", "title": "Refund policy", "data": { "body": "..." } }
+// publish — POST /api/kb?action=publish { "id": "<article uuid>" }
+// regenerate vectors — POST /api/embeddings?action=generate { "item_id": "<article uuid>" }
+// curate — POST /api/embeddings?action=approve|revoke { "id": "<embedding uuid>" }
+```
+
+## Example
+
+A support team writes refund-policy articles under `kb-account`, publishes them, then checks `kb/embeddings` — the new chunks show `Pending` until reviewed; approving the good ones and revoking a stale `semantic` chunk changes what `search_knowledge` returns to the reply-drafting agent.
+
+## Core files
+
+- `.framework/src/pages/admin/kb/KBAdminPage.tsx` — article page shell (list vs editor by mode)
+- `.framework/src/components/kb/KBArticleList.tsx` / `KBArticleEditor.tsx` — list + schema-driven editor, publish call
+- `.framework/src/pages/admin/EmbeddingsPage.tsx` / `EmbeddingDetailPage.tsx` — embedding browser/detail
+- `.framework/functions/kb.ts` — `search`, `publish`, and KB pipeline actions
+- `.framework/functions/embeddings.ts` — embedding CRUD + generate/approve/revoke/search
+- `.framework/functions/admin-data.ts` — the underlying record CRUD
+- Tables: `public.items` (articles), `public.embeddings` (vectors)
+
+## Agent notes
+
+- `instructionKeyFor` maps every `kb/*` route to this doc — there is no separate `embeddings` page key.
+- Articles are records, not files — edit them through this UI or `admin-data`, never direct table writes that skip validation/triggers.
+- `Pending` embeddings still count toward `stats`; only `revoked_at` removes a vector from similarity search.
+- Deleting an article does not cascade to its embedding rows — use `embeddings?action=delete-document` to clean up vectors for a removed document.
+- Re-publish after large edits: publishing re-ingests; stale chunks otherwise linger until `generate`/`cleanup` runs.

package/.framework/src/instructions/logs.md

@@ -0,0 +1,77 @@
+---
+title: Logs
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/pages/admin/LogsPage.tsx
+  - .framework/functions/logs.ts
+  - .framework/functions/_shared/logging.ts
+  - .framework/functions/system-cron.ts
+  - .framework/migrations/069_log_stats_window.sql
+---
+
+## What this is for
+
+**Logs** (`/spine-framework/admin/observability/logs`) is the account's audit-trail and event-history viewer — every `emitLog`/`emitAudit`/`emitSpan`/`emitActivity` write lands in the `logs` table and shows up here. Use it to trace a request end-to-end (via `trace_id`), answer "who did what when", and debug trigger/pipeline/delivery failures.
+
+## Fields and settings
+
+- **Stats cards** — Total Events, Event Types, Errors, User Actions over the current filter window (`/api/logs?action=stats`).
+- **Search** — free text over message/actor fields; debounced 300ms.
+- **Level** — `event_type` of the log row (error/audit/span/activity categories surface as selectable values from the stats payload).
+- **Source / Source Type** — `action` and `target_type` of the row (e.g. `type.updated`, `item`).
+- **Source ID / Actor ID / Trace ID** — UUID/prefix filters: `target_id`, `actor_id`, `trace_id`.
+- **From / To dates** — `date_from`/`date_to`; defaults to the last 24h. Stats default to a 7-day window when no `date_from` is given.
+- **Row click** — expands the row to show `details`, `metadata`, span info (`span_name`, `span_id`, `parent_span_id`, `duration_ms`, `outcome`).
+- **Trace button** — clicking a `trace_id` filters the whole grid to that trace (all spans of one request).
+- Paged at 100 rows per page; sortable columns (Time, Trace, Level, Source, Source Type, Source ID, Person, Message).
+
+**Downstream effects**
+
+- What gets written is gated by `system_settings` key `logging`: levels `off | timing | warnings | errors | all` (default `['timing','errors']`). Rows at unconfigured levels are dropped at write time — they never reach this page.
+- Retention is `cleanup` with `days_to_keep` (default 30); `system-cron` runs `cleanup_old_logs` at 00:00 UTC. Debugging a week-old issue? Check before it ages out.
+- `logs` is also a queryable `admin-data` entity, so pipelines and agents can read the same rows.
+- The Observability dashboard and Security page both read this table (`threshold.breached` events, security signals).
+
+## Minimal configuration
+
+Nothing to configure on the page itself. To see useful data, ensure the account's `system_settings.logging.levels` includes the level you need (e.g. `errors`), then filter:
+
+```
+Level = error · From = <incident date> · Trace ID = <trace from a failed request>
+```
+
+## Full configuration
+
+Combine all filters for a forensic query — e.g. every log row for one record by one person in a window:
+
+```
+query = "ticket"
+target_type = "items" · source_id = "<record uuid>"
+actor_id = "<person uuid>" · trace_id = "<trace uuid>"
+date_from = 2026-10-01 · date_to = 2026-10-30
+```
+
+API equivalents: `/api/logs?action=account` (paged rows), `action=stats`, plus `target`, `person`, `search`, `cleanup` actions server-side.
+
+## Example
+
+A user reports a failed save at 14:03. Open Logs, set From to that day, paste the `trace_id` from the error toast into Trace ID — the grid now shows the request's full span tree (`api.request` → `db.update` → `trigger.fired`), and the red `error` row's expanded `details` names the failing stage.
+
+## Core files
+
+- `.framework/src/pages/admin/LogsPage.tsx` — this page
+- `.framework/functions/logs.ts` — API (`account`, `target`, `person`, `stats`, `search`, `cleanup` actions)
+- `.framework/functions/_shared/logging.ts` — `emitLog`, level resolution from `system_settings`
+- `.framework/functions/_shared/audit.ts` / `.framework/functions/_shared/tracing.ts` — `emitAudit`/`emitSpan` writers, W3C trace context
+- `.framework/functions/system-cron.ts` — daily `cleanup_old_logs` at 00:00 UTC
+- Table: `public.logs`
+
+## Agent notes
+
+- Empty page with active traffic almost always means log **levels** filter writes, not that nothing happened — check `system_settings.logging` first.
+- `trace_id` is the fastest debugging primitive: every function request shares one, so one click reconstructs the whole call including trigger dispatch.
+- System admins query across accounts via `adminDb`; everyone else sees only their account's rows.
+- Cleanup is destructive and daily — export anything worth keeping before the 30-day default window closes.

package/.framework/src/instructions/notifications.md

@@ -0,0 +1,77 @@
+---
+title: Notifications
+audience: both
+kind: entity
+verified_against: b3b3ae0
+verified_on: 2026-11-01
+source_files:
+  - .framework/migrations/050_notifications.sql
+  - .framework/functions/_shared/notify.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/_shared/agent-runner.ts
+---
+
+# Notifications
+
+## What this is for
+
+A **notification** is an in-app message to a specific person — "a pipeline
+wants your attention on this record." `public.notifications` (migration 050)
+is written by pipeline `send_notification` stages and the agent-runner's
+notification action, and read by the signed-in recipient. It is the
+*inbound* counterpart to [Deliveries](deliveries.md), which tracks outbound
+webhook/integration sends.
+
+## Fields and settings
+
+| Column | Notes |
+|---|---|
+| `person_id` | required — the recipient (`people.id`). RLS scopes reads to `person_id = current_actor_id()`; users see only their own. |
+| `account_id` | required — tenant scope; service role writes across accounts. |
+| `source_type` / `source_id` | what produced it — default `'pipeline_execution'`; `source_id` is a text request/execution id (not always a uuid). |
+| `target_type` / `target_id` | the record the notification concerns — the deep link. |
+| `message` | required text body. |
+| `data` | jsonb — arbitrary payload (e.g. rendered title, action hints). |
+| `is_read`, `read_at` | read state; indexed `(account_id, person_id, is_read, created_at DESC)` for the unread inbox query. |
+
+**Recipient resolution**
+
+Pipeline/agent stages accept recipients as person UUIDs or `role:<slug>`
+entries. `resolveNotificationRecipients`
+(`.framework/functions/_shared/notify.ts`) expands `role:slug` → all
+`people.id` in the account holding that role; unknown entries warn and are
+skipped. A role matching zero people produces a valid empty insert — not an
+error.
+
+## Minimal configuration
+
+Written by the platform — a valid row needs `account_id`, `person_id`,
+`message` (from the stage's recipients + message config).
+
+## Full configuration
+
+Adds `source_type`/`source_id` attribution, `target_type`/`target_id`
+deep-linking, and a `data` payload.
+
+## Example
+
+A pipeline `send_notification` stage with `recipients: ["role:support_admin"]`
+inserts one row per support_admin in the account; each sees it in their
+inbox, scoped to their `person_id` by RLS.
+
+## Core files
+
+- `.framework/migrations/050_notifications.sql` — table, indexes, RLS
+- `.framework/functions/_shared/notify.ts` — `role:` → `person_id` resolver
+- `.framework/functions/_shared/pipeline-runner.ts` — `send_notification` stage
+- `.framework/functions/_shared/agent-runner.ts` — agent notification action
+
+## Agent notes
+
+- Never write literal `role:*` strings into `person_id` — it's a uuid
+  column; only resolved `people.id` values may be inserted. Both writers
+  share the resolver — use it.
+- `notifications` ≠ `deliveries`: notifications are in-app inbox rows;
+  deliveries are outbound webhook/integration attempts.
+- RLS allows `UPDATE` where `person_id = current_actor_id()` — recipients
+  can mark their own rows read; they cannot read each other's.

package/.framework/src/instructions/observability.md

@@ -0,0 +1,61 @@
+---
+title: Observability Dashboard
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/pages/admin/ObservabilityDashboard.tsx
+  - .framework/functions/observability.ts
+  - .framework/functions/logs.ts
+  - .framework/functions/_shared/logging.ts
+---
+
+## What this is for
+
+The **Observability Dashboard** (`/spine-framework/admin/observability`, also `/observability/dashboard`) is the account's health console: event volume, error rate, latency percentiles, per-pipeline run stats, top actors, and recent threshold-alert breaches — all computed from the `logs` table and refreshed on an interval.
+
+## Fields and settings
+
+- **Time range** — Last Hour / Last 24 Hours / Last 7 Days (`from`/`to` sent to every query; the volume chart buckets by minute/hour/day respectively).
+- **Refresh interval** — auto-refetch every 10s / 30s / 1m, plus a manual Refresh Now button.
+- **Stats cards** — Total Events, Error Rate (%), P95 Latency (ms, red above 2000ms), Pipelines with runs.
+- **Charts** — Event Volume line chart (bucketed counts), error rate, latency percentiles (p50/p95/p99), per-pipeline success/failure/avg-duration, Top Actors (limit 5).
+- **Recent alerts** — last 5 `threshold.breached` log events in the window (metric, threshold, actual value, time).
+
+**Downstream effects**
+
+- Everything derives from `public.logs` rows written by `emitLog`/`emitAudit`/`emitSpan` — if log levels drop a category (`system_settings.logging.levels`), it disappears from these charts too.
+- Queries are account-scoped for normal users; `system_admin` principals get cross-account reads (`adminDb`).
+- The metrics here are exactly what threshold alerts compare against (`error_rate`, `latency_percentiles`, `pipeline_stats` actions).
+- This page is read-only — it writes nothing.
+
+## Minimal configuration
+
+Open the page — defaults (24h range, 30s refresh) are sane for monitoring. There is nothing to configure.
+
+## Full configuration
+
+The backing API exposes more than the charts use:
+
+- `GET /api/observability?action=event_volume&from=&to=&bucket=minute|hour|day`
+- `action=error_rate` · `action=latency_percentiles` · `action=pipeline_stats` · `action=top_actors&limit=` · `action=ai_support_metrics` · `action=cleanup` (POST)
+
+## Example
+
+After deploying a new pipeline, set the range to Last Hour and refresh to 10s: Event Volume climbs with each run, the pipeline stats panel shows success vs failure counts and average duration, and a spike in the error-rate card correlates to the `error`-level rows you can drill into under Logs.
+
+## Core files
+
+- `.framework/src/pages/admin/ObservabilityDashboard.tsx` — this page (recharts)
+- `.framework/functions/observability.ts` — metrics API (all `action=` queries above)
+- `.framework/functions/logs.ts` — the `threshold.breached` alert feed (`action=account&event=`)
+- `.framework/functions/_shared/logging.ts` — the emit path and level gating that decides what reaches `logs`
+- Table: `public.logs` (source of all charts)
+
+## Agent notes
+
+- Flat charts with healthy traffic = log-level filtering, not broken metrics — the dashboard can only chart what `system_settings.logging.levels` allowed to be written.
+- `system_admin` sees cross-account aggregates here; account members see only their own account.
+- The 10s refresh is client-side polling — each tick re-runs all five metric queries; don't leave it open on a metered connection.
+- Breach alerts shown here are read from `logs`, not from the alert records — see Threshold Alerts for the rules themselves.

package/.framework/src/instructions/operations/deployment.md

@@ -0,0 +1,115 @@
+---
+title: Netlify Deployment
+audience: both
+kind: reference
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - netlify.toml
+  - .framework/public/_redirects
+  - scripts/assemble.sh
+  - scripts/assemble-frontend.sh
+  - scripts/assemble-functions.sh
+  - config/vite.config.ts
+  - .env.example
+  - .framework/functions/system.ts
+---
+
+# Netlify Deployment
+
+Spine deploys as a single Netlify site: a Vite-built SPA in `dist/` plus a
+flat directory of functions in `.assembled/netlify/functions`, backed by a
+Supabase (Postgres) project. Both halves are produced by the same build
+command — there is no separate function deploy step.
+
+## `netlify.toml` anatomy
+
+The root `netlify.toml` is partly framework-owned (regenerated on
+`npx spine-framework upgrade`, preserving `[functions."custom_*"]` sections):
+
+| Block | Contents |
+|---|---|
+| `[build]` | `command = "npm run assemble && npm run build"`, `publish = "dist"`, `functions = ".assembled/netlify/functions"` |
+| `[build.environment]` | `SECRETS_SCAN_OMIT_KEYS` whitelists the intentionally-public vars (`VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY`, `APP_BASE_URL`, `SITE_URL`, …) so Netlify's secrets scanner does not flag them; `SECRETS_SCAN_OMIT_PATHS` covers `.framework/.xenv*` |
+| `[functions]` | `directory = ".assembled/netlify/functions"`, `included_files` for `_shared/**`, `node_bundler = "esbuild"`, `external_node_modules = ["typescript"]` (the esbuild printer panic workaround — typescript.js ships unbundled) |
+| `[dev]` | `netlify dev` runs `scripts/netlify-dev-wrapper.sh`, site on `8888`, Vite `targetPort` `3001`, `startTimeout 300` |
+| `[functions."<name>"]` | per-function config: `trigger-scheduler` gets `schedule = "* * * * *"`; `cil-ingest`, `cil-embeddings`, `cil-callmap`, `cil-agent`, `ai-agents`, `kb` get `timeout` overrides |
+| `[[redirects]]` | `/* → /index.html` with status `200` (SPA fallback) |
+| `[[headers]]` | `X-Frame-Options DENY`, `nosniff`, HSTS, `Referrer-Policy`, `Permissions-Policy`, and a CSP that allows `*.supabase.co` (https+wss) and `challenges.cloudflare.com` (Turnstile) |
+
+Dispatched trigger pipelines run as Netlify **background functions**
+(`pipeline-runner-background`): the dispatcher gets a `202` immediately and
+each run gets the fixed 15-minute background budget — which is why no
+`timeout` entry exists for it.
+
+## How `.assembled/` is produced
+
+`npm run assemble` (`scripts/assemble.sh`) runs before every dev start
+(`predev:netlify`) and every build (`prebuild`). It wipes stale `dist/`,
+then:
+
+1. `scripts/assemble-functions.sh` flattens `.framework/functions` plus
+   `custom/functions` and `custom/apps/*/functions` into
+   `.assembled/netlify/functions`. Basename collisions are a **hard error**
+   naming both sources — Netlify needs one flat dir, so last-wins overwrite
+   is forbidden. `_quarantine` and `*-test.ts`/`*.test.ts` are excluded.
+2. `scripts/assemble-frontend.sh` copies `.framework/src` as the base layer,
+   each `custom/apps/<slug>` verbatim to `.assembled/src/<slug>/`, fixes up
+   `index.html`, merges `.framework/public` + app `public/` dirs into the
+   project `public/` (same-path collisions are a hard error), copies
+   `_redirects` into `.assembled/src/` for `netlify dev`, and stages the
+   project `spine.config.json` into `public/`.
+
+`config/vite.config.ts` then builds with `root: .assembled/src`,
+`publicDir: public/`, `build.outDir: dist/` — matching `publish = "dist"`.
+Never edit `.assembled/`; it is regenerated freely.
+
+## The `/api/*` URL space
+
+Requests to `/api/*` are rewritten to `/.netlify/functions/:splat`:
+
+- **Production:** the published `_redirects` file — sourced from
+  `.framework/public/_redirects`, merged into `public/` at assemble time —
+  carries `/api/* → /.netlify/functions/:splat 200`, plus
+  `/spine.config.json` passthrough and the `/* → /index.html` fallback.
+- **Dev:** the Vite proxy in `config/vite.config.ts` maps `/api/*` to
+  `localhost:8888` with the same rewrite.
+
+Because the SPA fallback is `/* → /index.html 200`, **any unmatched URL
+returns HTTP 200 with HTML** — including typos under `/api/`. A probe that
+gets HTML instead of JSON is hitting the SPA fallback, not a function.
+
+## Environment variables in production
+
+Set these in the Netlify site environment (not in `netlify.toml`).
+The full annotated list is [Environment Variables](../reference/env-vars.md);
+
+| Variable | Needed for |
+|---|---|
+| `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY` | browser bundle (public by design) |
+| `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY` | all functions — service-role key is server-only, never `VITE_`-prefixed |
+| `INTERNAL_INVOKE_SECRET` | trigger-dispatched pipelines — unset means `queued` rows that never run |
+| `APP_BASE_URL` | invite links, auth redirects, `base_url` allowlist |
+| `SCHEDULER_API_KEY` | key-gated `system-cron`/`trigger-scheduler` invocation |
+| `SITE_URL` | CORS `Access-Control-Allow-Origin`; falls back to Netlify's auto-set `URL` |
+| `RESEND_API_KEY`, `EMAIL_FROM` | outbound email (invites, notification stages) |
+| `OPENAI_API_KEY` | AI stage types, agents, embeddings |
+| `NETLIFY_ACCESS_TOKEN`, `NETLIFY_SITE_ID` | optional — push banned IPs to the edge firewall (security function skips silently without them) |
+
+`SUPABASE_DB_PASSWORD` is **not** a function env var — it is used locally by
+`npx spine-framework migrate` to connect to Postgres directly.
+
+## Deploy checklist
+
+- [ ] Supabase project exists; `SUPABASE_*` + `VITE_SUPABASE_*` vars set in Netlify.
+- [ ] `INTERNAL_INVOKE_SECRET` generated (`openssl rand -hex 32`) if triggers are used; `APP_BASE_URL`/`SITE_URL` set to the production origin.
+- [ ] Migrations applied: `npx spine-framework migrate` against the production DB (see [Migrations](migrations.md)).
+- [ ] Deploy via git push or `netlify deploy --prod` — the build command runs `assemble` then `vite build` automatically.
+- [ ] Post-deploy smoke: `/api/system?action=health` and `?action=manifest` answer; first registration grants `system_admin` (see [Install and first run](../guide/01-install-and-first-run.md)).
+- [ ] If timers/triggers are used: `trigger-scheduler` ticks appear in function logs within a minute; a test record write produces a `trigger.fired` log row.
+
+## Related
+
+- [Migrations](migrations.md) · [Upgrade](upgrade.md) · [Troubleshooting](troubleshooting.md)
+- [Environment Variables](../reference/env-vars.md) · [CLI Reference](../reference/cli.md)
+- [Anatomy of an installed project](../guide/02-project-map.md) — sealed vs customer trees