spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/src/instructions/integrations.md

@@ -0,0 +1,96 @@
+---
+title: Integrations
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integrations.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/integration-routes.ts
+  - .framework/functions/_shared/resolve-credentials.ts
+  - .framework/src/pages/admin/IntegrationsPage.tsx
+  - .framework/src/pages/admin/IntegrationDetailPage.tsx
+---
+
+## What this is for
+
+An **integration** connects Spine to an external service (OpenAI, Resend, a generic HTTP endpoint, a database, ...). The record stores the provider, runtime `config` (including which adapter handles calls), and `credentials`. Pipelines and app code reference the integration by slug.
+
+## Fields and settings
+
+- **Name** *(required)* — display name. The slug is **derived from it** server-side (`OpenAI` → `openai`); pass `slug` in the body only to override.
+- **Type** *(required)* — select: `webhook`, `api`, `database`, `file`, `custom`. Categorizes the integration; the create form pre-fills sensible `config`/`credentials` templates per type.
+- **Provider** *(required)* — free-text provider name (e.g. `openai`, `resend`, `postgres`).
+- **Version** — string, default `1.0.0`.
+- **Config (JSON)** — adapter and runtime settings. The adapter is named **here**, not as a top-level field: `config.outbound_adapter` (or `config.inbound_adapter` for inbound webhooks) points at an adapter module such as `adapters/openai-outbound`.
+- **Credentials (JSON)** — secrets keyed by field name, each `{ "source": "env_var" | "value", "value": "..." }`. `source: "env_var"` resolves the named env var inside the function runtime; `source: "value"` stores the literal secret in the DB. The credential field callers read defaults to `api_token`.
+- **Configured** — computed, read-only. `is_configured` is re-derived on every save from `credentials` (all entries must resolve); the UI shows it as Configured/Pending.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Active** — boolean. Inactive integrations fail closed — callers get an error, not a fallback.
+- **Description / Metadata** — optional notes and free-form data.
+
+**Downstream effects**
+
+- `env_var` credentials are resolved inside the function runtime — the variable must exist in the deployed env or calls fail at request time (`credential_env_missing`), not at save time. `source: "value"` persists the literal secret — prefer `env_var` for anything real.
+- An absent or explicitly-empty (`source: "value"`, `value: ""`) credential entry means "call without auth" — the outbound broker sends no credential and the adapter decides whether one is required (the seeded `generic-http` integration works unauthenticated out of the box this way).
+- Built-in outbound adapters: `adapters/openai-outbound`, `adapters/generic-webhook-outbound`, `adapters/resend-outbound`. Any other adapter path is dynamically imported — a typo saves fine but fails on first call.
+- Outbound calls create a `webhook_deliveries` row (`pending`, `max_attempts` default 3 or `config.retry_policy.max_attempts`) and show up under Deliveries.
+- Apps declare `integration_deps`; installing an app without its integrations leaves features broken until the records exist.
+- The list/detail APIs use `adminDb` for system admins — integrations exist per account and per system scope.
+
+## Minimal configuration
+
+```json
+{
+  "name": "OpenAI",
+  "integration_type": "api",
+  "provider": "openai",
+  "is_active": true,
+  "config": {
+    "outbound_adapter": "adapters/openai-outbound",
+    "model": "gpt-4o"
+  },
+  "credentials": { "api_token": { "source": "env_var", "value": "OPENAI_API_KEY" } }
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Outbound webhook",
+  "integration_type": "api",
+  "provider": "custom",
+  "version": "1.2.0",
+  "is_active": true,
+  "config": {
+    "outbound_adapter": "adapters/generic-webhook-outbound",
+    "base_url": "https://hooks.example.com",
+    "timeout_ms": 10000,
+    "retry_policy": { "max_attempts": 5 }
+  },
+  "credentials": { "api_token": { "source": "env_var", "value": "ACME_HOOK_TOKEN" } },
+  "metadata": { "owner": "platform" }
+}
+```
+
+## Example
+
+A support app lists `integration_deps: ["openai"]` — the AI agents resolve the `openai` integration by slug for model calls (credential field `api_token`), and a second integration (`config.outbound_adapter: "adapters/generic-webhook-outbound"`) delivers outbound ticket events, each attempt logged under Deliveries.
+
+## Core files
+
+- `.framework/functions/integrations.ts` — API (list/get/create/update; `is_configured` computed on write; non-admin reads are sanitized)
+- `.framework/functions/integration-outbound.ts` — outbound broker (adapter registry, delivery rows, retry math)
+- `.framework/functions/integration-routes.ts` — inbound webhook entry
+- `.framework/functions/_shared/resolve-credentials.ts` — `env_var`/`value` credential resolution
+- `.framework/src/pages/admin/IntegrationsPage.tsx` / `IntegrationDetailPage.tsx` — admin UI (per-type config templates on the detail form)
+- Table: `public.integrations`
+
+## Agent notes
+
+- Credentials shape is `{ "api_token": { "source": "env_var", "value": "OPENAI_API_KEY" } }` — nested `source`/`value` objects, not `{ "env_var": "..." }`. The latter saves but never resolves.
+- Never put real secrets in `credentials.*.value` with `source: "value"` in seeds or docs — always `env_var`.
+- There is no top-level `adapter` or `configuration` column — the field is `config`, and the adapter lives at `config.outbound_adapter` / `config.inbound_adapter`.
+- After changing credentials, the broker picks them up on the next call — no cache flush needed.

package/.framework/src/instructions/internal/cil-markers.md

@@ -0,0 +1,83 @@
+---
+title: "CIL markers and generated doc tags"
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/scripts/cil-migrate-markers.ts
+  - AGENTS.md
+---
+
+# CIL markers and generated doc tags
+
+Files throughout `.framework/` — `src`, `functions`, `cli`, `migrations` —
+carry dense comment blocks that look like this:
+
+```ts
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/pipeline-runner.ts:isuuid:function" type="function" identity="isUuid" parent="~/.framework/functions/_shared/pipeline-runner.ts"]
+// CIL[DOC-MACRO purpose="isUuid function"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+function isUuid(v: string | undefined | null): v is string { ... }
+// CIL[END stable_id="~/.framework/functions/_shared/pipeline-runner.ts:isuuid:function"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+```
+
+and generated JSDoc like this:
+
+```ts
+/**
+ * Validates whether a given string is a properly formatted UUID.
+ * @inputSpec   - v: string — the value to be checked
+ * @outputSpec  v is string — true if the value is a valid UUID
+ * @sideEffects none
+ * @stability   stable
+ * @calls       UUID_RE.test
+ * @cil-generated
+ */
+```
+
+## What they are
+
+**CIL** (Code Intelligence Layer) is the repository's internal
+code-indexing tooling — it chunks the codebase into addressable units,
+attaches generated documentation, and keeps embeddings in sync for semantic
+search inside the monorepo. The comments are its on-disk metadata:
+
+- `// CIL[BEGIN ...]` / `// CIL[END ...]` — delimit one tracked code chunk.
+  `stable_id` is the chunk's durable identity
+  (`<file>:<slug>:<kind>`); `type`, `identity`, and `parent` describe it.
+- `// CIL[DOC-* …]` — generated or curated facts about the chunk:
+  `DOC-MACRO` (purpose), `DOC-RESPONSIBILITY`, `DOC-CONTEXT`
+  (module/layer/related files), `DOC-CONTRACT` (inputs/outputs/errors/
+  side_effects), `DOC-MICRO` (logic summary, notable decisions),
+  `DOC-CONFIDENCE` (pass + score), `DOC-STABILITY`, `DOC-AUDIENCE`,
+  `DOC-PARAM`, `DOC-NOTE`, and `DOC-LEARNING`.
+- `// CIL[DOC-VECTOR type="…" content="…" status="…"]` — the payload that
+  becomes a search embedding (types include `context`, `blast_radius`,
+  `constraint`, `configuration`, `implementation_pattern`, `user_journey`).
+  `status="ready"` means it was generated; **`status="pending_human_input"`
+  means the field is intentionally blank until an author fills it** — it is
+  not an error and not a warning about the code itself.
+- JSDoc tags `@macro`, `@micro`, `@inputSpec`, `@outputSpec`, `@sideEffects`,
+  `@calls`, `@seeAlso`, `@errorHandling`, `@stability`, `@module`, `@layer`,
+  `@audience`, `@cil-generated` mirror the same metadata in human-readable
+  form; `@cil-generated` marks text written by the pipeline rather than a
+  person.
+
+## What they mean for you
+
+- **Safe to ignore.** They are comments; they have no runtime effect, no API
+  surface, and no effect on how you build apps on Spine. CIL is maintainer
+  tooling, not a framework feature.
+- **Read them as hints, not truth.** `DOC-*` summaries and JSDoc are
+  generated interpretation — usually accurate, occasionally stale. The code
+  is the authority; treat the tags like any other doc comment.
+- **In framework files, leave them in place.** Editing or deleting markers by
+  hand is harmless locally but gets rebuilt/renumbered the next time the
+  repo's marker tooling runs (see `cil:migrate-markers` /
+  `.framework/scripts/cil-migrate-markers.ts`). In your own `custom/` code
+  you're free to add or omit them — nothing requires them.
+- The contributor-facing conventions live in the repo's `AGENTS.md`; this
+  page is only the legend for readers who meet the markers in shipped source.

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/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