spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/reference/design-schema.md

@@ -0,0 +1,280 @@
+---
+title: Design Schema Reference
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/types/types.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/admin-data.ts
+  - .framework/functions/types.ts
+  - .framework/cli/commands/validate-schema.ts
+  - .framework/src/components/shared/FieldRenderer.tsx
+  - .framework/src/components/app-shell/GenericListPage.tsx
+  - .framework/src/components/app-shell/GenericDetailPage.tsx
+  - .framework/src/hooks/useForm.ts
+---
+
+# Design Schema Reference
+
+Exhaustive field-level spec for `public.types.design_schema` — the JSON every
+type carries and every runtime record is stamped with at creation. The mental
+model is in [Design Schema](../concepts/design-schema.md); this page is the
+lookup table. The TypeScript source of truth is `DesignSchema`,
+`FieldDefinition`, `ViewFieldConfig`, `ListView`, `DetailView`, and
+`FunctionalityBindings` in `.framework/src/types/types.ts`.
+
+## Top-level shape
+
+| Key | Type | Required | Purpose |
+|---|---|---|---|
+| `fields` | `Record<string, FieldDefinition>` | yes | Flat map of `snake_case` field names to definitions |
+| `views` | `Record<string, View>` | yes for generic apps | `default_list` and `default_detail` drive the generic UI |
+| `record_permissions` | `Record<string, string[]>` | yes | Base CRUD grant per role slug |
+| `scope` | `"account" \| "platform"` | no (default `"account"`) | Which account owns records of this type at create |
+| `functionality` | `FunctionalityBindings` or extensions | no | Automation bindings; `null` until a binding is confirmed live |
+| `display_field` | `string` | no | Field used for record titles in detail pages |
+
+`validate-schema` enforces: `fields` non-empty; every field has `data_type`,
+`label`, `required`; `record_permissions` grants at least `system-admin` or
+`system_admin`; `scope` is `account` or `platform`
+(`.framework/cli/commands/validate-schema.ts`).
+
+## `fields.<name>` — FieldDefinition
+
+| Key | Type | Notes |
+|---|---|---|
+| `data_type` | enum, see below | required |
+| `label` | string | required |
+| `required` | boolean | required; enforced client-side by `useForm` (`.framework/src/hooks/useForm.ts`), propagated into `validation_schema` |
+| `system` | boolean | `true` → top-level record column; absent/`false` → `record.data.<name>` |
+| `placeholder` | string | input hint |
+| `description` | string | help text |
+| `name` | string | optional field alias |
+| `rows` | number | textarea height hint |
+| `min`, `max`, `step` | number | range input bounds |
+| `readonly`, `disabled` | boolean | form-state hints |
+| `validation` | object | constraint keys, see below |
+| `options` | `(string \| {value, label})[]` | required for `select`, `multiselect`, `radio` |
+| `permissions` | `Record<string, string[]>` | per-role field overrides, `read`/`write` only |
+
+### `data_type` values
+
+The authoritative dispatch is `sanitizeFieldData` in
+`.framework/functions/_shared/schema-utils.ts`. Unknown types are **not
+rejected** — the value passes through unsanitized and unvalidated.
+
+**Where the sanitizer runs.** `sanitizeFieldData` executes only on the
+`admin-data` **update** path, only for `data.*` (non-system) fields, and only
+for **non-system-admin** principals. `create` performs no field sanitization —
+the request body is inserted as-is — and system columns (`system: true`,
+including `select` fields like `status`) are never option-validated
+server-side. `required` is enforced client-side by `useForm` only. So
+"sanitizer behavior throws" below means: on a `data.*` update by a non-admin
+caller. The trust boundary is the client + field permissions, not
+`validation_schema` — treat API writes as unvalidated input.
+
+| `data_type` | Stored as | Sanitizer behavior |
+|---|---|---|
+| `text` | string | trim, strip control chars; `minLength` throws, `maxLength` truncates, `pattern` throws |
+| `textarea` | string | trim, strip control chars; `minLength`/`maxLength` |
+| `rich_text` | HTML string | tag allowlist (`p br strong em u ol ul li a h1–h6`), strips `<script>` and `on*=` handlers; `minLength`/`maxLength` |
+| `email` | string | lowercase + trim; must match `^[^\s@]+@[^\s@]+\.[^\s@]+$` |
+| `phone` | string | strips non-`0-9+` chars; optional `pattern` |
+| `url` | string | parses URL; `http:`/`https:` only; normalized via `URL.toString()` |
+| `number` | number | `Number()` coercion; `min`/`max` throw; `step` snaps down to step |
+| `currency` | number | `Number()` coercion rounded to 2 decimals; `min`/`max` throw |
+| `range` | number | same as `number` |
+| `date` | `"YYYY-MM-DD"` | parses any `Date()` input, stores ISO date; `min`/`max` bounds |
+| `datetime` | ISO string | parses any `Date()` input, stores `toISOString()`; `min`/`max` bounds |
+| `boolean` | boolean | `true`/`false` pass through; strings `"true" "1" "yes" "on"` → `true`, `"false" "0" "no" "off"` → `false`; anything else throws |
+| `checkbox` | boolean | alias of `boolean` |
+| `select` | string | trim; when `options` are declared the value must match an option (`value` for `{label,value}` entries) or it throws |
+| `multiselect` | string[] | accepts an array or comma-separated string; dedupes; each element must match an option; `validation.max` truncates the list |
+| `radio` | string | same sanitizer as `select` |
+| `color` | string | must match `#rgb`/`#rrggbb`; normalized to 6-digit uppercase hex |
+| `file` | object | must be an object with `.name`; `maxSize` and `allowedTypes` (MIME) enforced; filename sanitized to `[a-zA-Z0-9.-]` |
+| `image` | object | same sanitizer as `file` (`maxWidth`/`maxHeight` are declared but not enforced) |
+| `json` | any JSON value | string input is `JSON.parse`d; rejects script tags, `javascript:`, `eval(`/`function(`, `on*=` handlers, and `__proto__` keys; arbitrary nesting allowed under `data.<name>` |
+| `reference` | string (uuid) | must match the UUID regex; `validation.reference_kind`/`reference_type` describe the target |
+| `address` | object | must be an object; string values are text-sanitized |
+
+`formatFieldData` (display formatting) covers only `json`, `date`, `datetime`,
+`currency`, `phone`, `url`, `reference`, `address`, `multiselect`, `boolean` —
+all other types render raw.
+
+### `validation.*` keys
+
+Declared on `FieldDefinition.validation`; copied verbatim into the generated
+`validation_schema` by `generateValidationSchema`
+(`.framework/functions/_shared/schema-utils.ts`).
+
+| Key | Applies to | Effect |
+|---|---|---|
+| `pattern` | `text`, `phone` | regex must match or the write throws |
+| `minLength`, `maxLength` | `text`, `textarea`, `rich_text` | min throws; max truncates |
+| `min`, `max` | `number`, `currency`, `range`, `date`, `datetime` | bounds; out-of-range throws |
+| `step` | `number`, `range` | value snapped down to step multiple |
+| `integer` | `number` | declared; not enforced by the server sanitizer |
+| `precision` | `number` | declared decimal precision; not enforced server-side |
+| `maxSize` | `file`, `image` | byte-size limit, enforced server-side |
+| `allowedTypes` | `file`, `image` | MIME allowlist, enforced server-side |
+| `maxWidth`, `maxHeight` | `image` | declared; not enforced server-side |
+| `max` | `multiselect` | truncates the list to `max` entries |
+| `currency_code` | `currency` | display currency (e.g. `USD`) |
+| `reference_kind` | `reference` | runtime table of the target (`item`, `person`, `account`, …) |
+| `reference_type` | `reference` | type slug of the target record |
+
+### `options` formats
+
+Required for `select`/`multiselect`/`radio`; validated non-empty by
+`validate-schema`. Both forms accepted:
+
+```json
+"options": ["todo", "done"]
+"options": [{ "label": "Bug", "value": "bug" }]
+```
+
+### `permissions` (field-level overrides)
+
+`record_permissions` is the **base, most restrictive** grant: when a role can
+`read`/`update` a record, every field defaults to `read`/`write` unless the
+field declares a `permissions` entry for that role. Field-level actions are
+`read` and `write` only; `create`/`delete` are record-level
+(`.framework/functions/_shared/permissions.ts`, `resolveFirstSurfacePermissions`
+step 5–6). Use field permissions to **loosen** one field beyond the record
+grant or to re-restrict a `system: true` field.
+
+```json
+"fields": {
+  "cost": {
+    "data_type": "currency", "label": "Cost", "required": false,
+    "permissions": { "member": ["read"], "finance": ["read", "write"] }
+  }
+}
+```
+
+### `system` flag semantics
+
+`system: true` fields are stored as top-level record columns (`record.title`),
+all others under `record.data.<name>` — see
+[Runtime Records](../concepts/runtime-records.md). Writers split payloads the
+same way (`useEntityRecord` / the update path). Conventionally `title` is
+system; flag `system: true` fields that humans must not edit with a
+`permissions` override restricting `write` to `system_admin`.
+
+## `views`
+
+`views` is a map of view names to `ListView | DetailView`. Generic apps
+(`apps.renderer = "generic"`) need `default_list` and `default_detail`; a
+custom app may omit views but loses the generic admin/runtime fallback.
+
+### `default_list` — ListView
+
+| Key | Type | Purpose |
+|---|---|---|
+| `type` | `"list"` | required discriminator |
+| `display` | `"table" \| "card" \| "board"` | layout in `GenericListPage` |
+| `label` | string | view title |
+| `fields` | `Record<string, ViewFieldConfig>` | column map, keyed by field name (may include `created_at`/`updated_at`). Non-system fields resolve automatically — key `priority` reads `record.data.priority`; the explicit `data.priority` form also works and filters on `data.<field>` are translated server-side |
+| `default_sort` | `{field, direction: "asc"\|"desc"}` | initial ordering |
+| `filters` | `(string \| EntityFilter)[]` | filter affordances — a bare field-name string is normalized from the field def (`select` → enum with its option values, `boolean` → boolean, else search); or pass full `{key, label, type: "search"\|"enum"\|"boolean", options?: string[]}` objects |
+| `stats` | `{title, type: "count"\|"filter_count", icon?, color?, filter?}[]` | stat cards above the list; `filter` is a `{<field>: <value>}` map matched per row (e.g. `{"status": "todo"}`) |
+| `group_by` | string | field to group rows by (board display) |
+
+### `default_detail` — DetailView
+
+| Key | Type | Purpose |
+|---|---|---|
+| `type` | `"detail"` | required discriminator |
+| `label` | string | page title |
+| `sections` | `DetailViewSection[]` | ordered sections of `{title, fields: Record<string, ViewFieldConfig>}` |
+
+### `ViewFieldConfig` — `display_type`
+
+Each view field is `{display_type, sortable?, searchable?}`. Implemented
+`display_type` values — enforced by `validate-schema` and rendered by
+`.framework/src/components/shared/FieldRenderer.tsx`:
+
+| `display_type` | Context |
+|---|---|
+| `text` | read-only text (list/detail) |
+| `badge` | status pill (list) |
+| `timestamp` | formatted date/time (list/detail) |
+| `currency` | formatted amount |
+| `number` | formatted number |
+| `input` | single-line edit input (detail) |
+| `textarea` | multi-line edit |
+| `rich_text` | rich-text editor |
+| `select`, `multiselect`, `radio` | option pickers |
+| `checkbox`, `switch` | boolean toggles |
+| `date_picker`, `datetime_picker` | date/time pickers |
+| `color_picker` | color input |
+| `file_upload`, `image_upload` | upload widgets |
+| `range_slider` | numeric slider |
+
+Reserved in `ViewFieldConfig` but not yet implemented by `FieldRenderer`:
+`rating`, `autocomplete`, `address_form`, `reference_picker` (the type union
+admits them in `.framework/src/types/types.ts`; treat as forward-compatible
+placeholders).
+
+## `record_permissions`
+
+```json
+"record_permissions": {
+  "system_admin": ["create", "read", "update", "delete"],
+  "admin":        ["create", "read", "update"],
+  "member":       ["read"]
+}
+```
+
+- Actions are `create`, `read`, `update`, `delete` — evaluated per request
+  against the caller's role slug.
+- `"all"` is a wildcard role granted to every authenticated principal that
+  passed RLS; always evaluated when present
+  (`.framework/functions/_shared/permissions.ts`).
+- Evaluation happens against the schema **stamped on the record**, not the
+  type row — records created before a schema edit keep the old grant.
+- If a type's `design_schema` omits `record_permissions`, `admin-data` create
+  merges a permissive default `{all: [create,read,update,delete]}` before
+  stamping (`.framework/functions/admin-data.ts`, `PERMISSIONS_ALL`). An
+  explicit empty object denies everything downstream — always author
+  deliberately.
+
+## `scope`
+
+Read at create time as `designSchema.scope ?? 'account'`
+(`.framework/functions/admin-data.ts`). `"platform"` stamps new records with
+the `spine-system` account id; records created against a parent
+(`thread_id`, `target_id`, `parent_id`) inherit the parent's stamped scope.
+See [Scope and Accounts](../concepts/scope-and-accounts.md).
+
+## `functionality`
+
+`FunctionalityBindings` (`.framework/src/types/types.ts`) declares optional
+automation:
+
+| Binding | Shape |
+|---|---|
+| `pipelines[]` | `{pipeline_id, trigger: manual\|on_create\|on_update\|on_field_change\|on_delete\|scheduled, field?, condition?, roles[]}` |
+| `ai_agents[]` | `{agent_id, capabilities: (read\|summarize\|suggest\|update)[], trigger, roles[]}` |
+| `embeddings[]` | `{slug, fields[], model, vector_column, trigger}` |
+| `integrations[]` | `{integration_id, sync: bidirectional\|inbound\|outbound, field_map, trigger}` |
+| `constraints[]` | `{type: unique\|conditional_required\|immutable, fields?/field?, condition?, message, after?: create\|update}` |
+
+`admin-data` also reads `functionality.lineage`
+(`{parent_fields: string[], link_type: string, children: {[slug]: field}}`)
+on `items` get/list to attach `parents`/`children` — declared per type in the
+seed, interpreted by `attachLineage` in `.framework/functions/admin-data.ts`.
+Set `functionality` to `null` until the binding you need is confirmed live.
+
+## `validation_schema` (generated, never authored)
+
+`generateValidationSchema` derives `{fields: {name: {data_type, required,
+...validation, options, reference_kind?, reference_type?}}}` from
+`design_schema.fields` on every type create and on every update that touches
+`design_schema` (`.framework/functions/types.ts`,
+`.framework/cli/commands/install-app.ts` seed path). Never hand-edit — change
+`design_schema` and let the writer regenerate it.

package/.framework/src/instructions/reference/env-vars.md

@@ -0,0 +1,133 @@
+---
+title: Environment Variables
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .env.example
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/db.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/resolve-credentials.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/pipeline-runner-background.ts
+  - .framework/functions/security.ts
+  - .framework/functions/invites.ts
+  - .framework/functions/adapters/resend-outbound.ts
+  - .framework/cli/context.ts
+  - .framework/cli/commands/migrate.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/src/lib/supabase.ts
+  - .framework/src/App.tsx
+---
+
+# Environment Variables
+
+Every variable read across `.framework/` — where it's read, whether it's
+required, and whether it is browser-exposed. `VITE_*` vars are compiled into
+the frontend bundle and are **public by definition**; all others are
+server-only (Netlify functions, CLI, MCP tooling). `.env` at the project root
+is preloaded by the CLI and dev tooling.
+
+> **Security rule:** never set `VITE_SUPABASE_SERVICE_ROLE_KEY` or put any
+> secret behind a `VITE_*` name. The service-role key bypasses RLS entirely;
+> shipping it to the browser hands full database access to every visitor.
+> Only `VITE_SUPABASE_ANON_KEY` belongs in the client bundle.
+
+## Required — server
+
+| Variable | Read by | Purpose |
+|---|---|---|
+| `SUPABASE_URL` | `.framework/functions/_shared/db.ts`, `.framework/functions/_shared/principal.ts`, CLI (`context.ts`, `install-app.ts`, `migrate.ts`, `status.ts`, `system.ts`) | Supabase project URL for service + user clients |
+| `SUPABASE_SERVICE_ROLE_KEY` | `.framework/functions/_shared/db.ts` (`adminDb`), `.framework/cli/context.ts`, `install-app.ts`, `status.ts` | Service-role client; bypasses RLS. **Server-only** |
+| `SUPABASE_ANON_KEY` | `.framework/functions/_shared/principal.ts`, `.framework/functions/_shared/db.ts` (`getUserDb`) | JWT verification and user-scoped PostgREST clients inside functions |
+
+Missing `SUPABASE_URL`/`SUPABASE_SERVICE_ROLE_KEY` fails CLI commands that
+touch the DB and leaves `adminDb` on placeholder credentials — function
+calls then fail at query time.
+
+> **Key naming:** all three values are under Supabase Dashboard → Project
+> Settings → API Keys (older dashboards: Settings → API / Data API).
+> Current dashboards issue the anon key as a **Publishable key**
+> (`sb_publishable_…`) and the service-role key as a **Secret key**
+> (`sb_secret_…`) — set `*_ANON_KEY` / `SUPABASE_SERVICE_ROLE_KEY` to them
+> directly; they work everywhere the legacy JWTs did.
+
+## Required for specific features — server
+
+| Variable | Read by | Required for |
+|---|---|---|
+| `SUPABASE_DB_PASSWORD` | `.framework/cli/commands/migrate.ts`, `install-app.ts` | Direct Postgres connection for `migrate`/`install-app` (from Supabase Dashboard → Database) |
+| `SUPABASE_DB_URL` | `.framework/cli/commands/migrate.ts` | Optional full connection string overriding host/user/port — use the **Session Pooler** (`postgres://postgres.<ref>:<pw>@aws-0-<region>.pooler.supabase.com:5432/postgres`) when `db.<ref>.supabase.co:5432` is unreachable (direct connections are IPv6-only on most Supabase projects) |
+| `INTERNAL_INVOKE_SECRET` | `.framework/functions/_shared/principal.ts` (`isInternalInvokeAuthorized`), `.framework/functions/_shared/trigger-engine.ts`, `.framework/functions/pipeline-runner-background.ts` | Authenticates function-to-function invocation via `x-internal-secret`. **Required for trigger dispatch** — without it, `dispatchTriggerPipeline` cannot invoke `pipeline-runner-background` and `x-cron-id`/`x-trigger-id`/`x-internal-secret` headers are never honored. Generate with `openssl rand -hex 32` |
+| `SCHEDULER_API_KEY` | `.framework/functions/system-cron.ts` | `?api_key=`/`?scheduler_key=` on the scheduler endpoint; unset disables key-gated scheduling |
+| `APP_BASE_URL` | `.framework/functions/invites.ts` | Base URL for invite links, auth redirects, and the allowlist for client-supplied `base_url` params |
+| `RESEND_API_KEY` | resolved via `env_var` credentials on the `transactional-email`/`resend` integration (`.framework/functions/_shared/resolve-credentials.ts`) | Outbound email (invites, notification stages). Unset → invites fall back to copyable links, email stages skip |
+| `EMAIL_FROM` | `.framework/functions/adapters/resend-outbound.ts` | Sender identity for outbound email |
+| `OPENAI_API_KEY` | resolved via `env_var` credentials on the `openai` integration; `.framework/functions/_shared/agent-runner.ts` mocks responses when absent | LLM chat/embeddings for agents, pipelines, KB |
+| `LLM_DEFAULT_MODEL` | `.framework/functions/_shared/agent-runner.ts`, `.framework/functions/embeddings.ts` | Default model slug when prompts don't pin one |
+| `NETLIFY_ACCESS_TOKEN`, `NETLIFY_SITE_ID` | `.framework/functions/security.ts` | Push banned IPs to Netlify edge Firewall rules; unset skips the edge layer |
+
+Integration credentials generally use `source: 'env_var'` +
+`value: '<VAR_NAME>'` in `integrations.config.credentials` —
+`resolveCredentials` reads `process.env[value]` server-side
+(`.framework/functions/_shared/resolve-credentials.ts`). Any env var name is
+permitted there.
+
+## Optional — server behavior tuning
+
+| Variable | Read by | Default |
+|---|---|---|
+| `SITE_URL` | `.framework/functions/_shared/middleware.ts` | `Access-Control-Allow-Origin` header; falls back to Netlify's `URL`, then `*` |
+| `URL` | `.framework/functions/_shared/middleware.ts`, `.framework/mcp/` | Netlify auto-set site URL; CORS and MCP base-URL fallback |
+| `ALLOWED_ORIGINS` | `.framework/functions/invites.ts` | extra CORS origins for invite endpoints |
+| `SPINE_IP_RATE_LIMIT` | `.framework/functions/_shared/principal.ts` | per-IP request ceiling for API-key auth; default `300`/60s |
+| `REPO_PATH` | `.framework/functions/_shared/app-manifest.ts`, `.framework/mcp/` | project root for manifest discovery; defaults to `process.cwd()` |
+| `DB_SCHEMA` | `.framework/functions/_shared/db.ts` | PostgREST schema; default `public` (multi-instance installs only) |
+| `EMAIL_WEBHOOK_URL` | outbound adapters | optional inbound-email relay endpoint |
+
+## Client-exposed (`VITE_*`, browser bundle)
+
+| Variable | Read by | Purpose |
+|---|---|---|
+| `VITE_SUPABASE_URL` | `.framework/src/lib/supabase.ts` | Supabase URL for the browser client — required |
+| `VITE_SUPABASE_ANON_KEY` | `.framework/src/lib/supabase.ts` | anon key for the browser client — required, RLS-scoped, safe |
+| `VITE_ENVIRONMENT` | `.framework/src/contexts/AppContext.tsx`, `.framework/src/hooks/useApps.ts` | environment badge (`dev`/`staging`/`prod`) |
+| `VITE_SETUP_MODE` | `.framework/src/App.tsx` | setup-mode UI flag |
+| `VITE_TURNSTILE_SITE_KEY` | `.framework/src/components/auth/TurnstileWidget.tsx` | Cloudflare Turnstile site key on auth pages — public by design |
+| `VITE_APP_NAME` | `.env.example` (branding) | app name for UI/localStorage/webhook headers — prefer `branding.app_name` in `spine.config.json` |
+| `VITE_DB_SCHEMA` | `.env.example` | deprecated multi-instance knob; leave unset |
+
+## CLI / local tooling
+
+| Variable | Read by | Purpose |
+|---|---|---|
+| `SPINE_CLI_API_KEY` | `.framework/cli/context.ts` | API-key auth for remote CLI commands (`items`, `pipelines`, `agents`, `system`) |
+| `SPINE_CLI_JWT` | `.framework/cli/context.ts` | JWT auth alternative for the same commands |
+| `SPINE_CLI_ACCOUNT_ID` | `.framework/cli/context.ts` | default account scope; `--account` overrides |
+| `SPINE_CLI_DEBUG` | `dev.ts`, `init.ts`, `install-app.ts`, `migrate.ts`, `upgrade.ts` | verbose CLI diagnostics |
+| `SPINE_URL`, `SPINE_API_KEY`, `SPINE_FRAMEWORK_API_KEY` | `.framework/mcp/` | MCP server endpoint + key |
+| `OPENAI_BASE_URL`, `LLM_API_KEY`, `OPENAI_API_KEY` | `.framework/mcp/` | MCP-side LLM provider config |
+
+## Consumer-side conventions
+
+Not read by framework runtime code — a convention for agent/tooling
+integrations so the same credential location works everywhere:
+
+| Variable | Read by | Purpose |
+|---|---|---|
+| `SPINE_API_KEY` | agent tooling (`.framework/mcp/` honors it too) | the `sk_…` key an agent sends as `x-api-key` on `/api/*` requests; the user creates a scoped key in Admin → Configs → API Keys |
+
+## Test-only
+
+`SPINE_DEV_URL`, `SPINE_DEV_JWT`, `SPINE_TEST_API_KEY`, `SPINE_TEST_ACCOUNT_ID`,
+`ACCOUNT_ID`, `SERVICE_KEY` — used by `.framework/tests/` fixtures and
+integration suites; never required at runtime.
+
+## Related
+
+- `.env.example` — annotated starter file
+- [Authentication](api/auth.md) — how `x-api-key`/`x-internal-secret`/Bearer resolve
+- [Shared Modules](shared-modules.md)

package/.framework/src/instructions/reference/frontend-sdk.md

@@ -0,0 +1,207 @@
+---
+title: Frontend SDK Reference (@core)
+audience: developers, agents
+kind: reference
+verified_against: bc17374
+verified_on: 2026-11-02
+source_files:
+  - config/vite.config.ts
+  - config/tsconfig.json
+  - .framework/src/lib/api.ts
+  - .framework/src/lib/supabase.ts
+  - .framework/src/lib/utils.ts
+  - .framework/src/lib/registration.ts
+  - .framework/src/lib/branding.ts
+  - .framework/src/hooks/useAppPath.ts
+  - .framework/src/hooks/useApi.ts
+  - .framework/src/hooks/useApps.ts
+  - .framework/src/contexts/AuthContext.tsx
+  - .framework/src/contexts/AppContext.tsx
+  - .framework/src/components/ui/
+  - .framework/src/components/shared/
+  - .framework/src/components/kb/
+  - .framework/src/components/layout/
+  - .framework/src/types/types.ts
+  - .framework/src/types/auth.ts
+---
+
+# Frontend SDK Reference (`@core`)
+
+Custom apps write frontend code against the framework's `@core` import
+surface — the same tree as `.framework/src`, resolved through the bundled
+`.assembled/src`. This page is the contract: what each module exports, what
+it is for, and when to reach for it. Ordered by how often real apps use it.
+
+## Import aliases
+
+Defined in `config/vite.config.ts` (build/dev) and `config/tsconfig.json`
+(types):
+
+| Alias | Resolves to | Use |
+|---|---|---|
+| `@core/*` | `.assembled/src/*` (types: `.framework/src/*`) | **Frontend core.** All imports below. |
+| `@/*` | `.assembled/src/*` | Same tree as `@core` — prefer `@core` in custom apps for clarity. |
+| `@custom/*` | `custom/apps/*` | Cross-app imports; rare. |
+| `@shared/*` | `.framework/functions/_shared/*` | **Server-side only** (Netlify/Deno functions). Never import from a React page — it pulls server-only deps into the frontend bundle. |
+
+The loader mounts custom apps via `import.meta.glob('../../../custom/apps/*/index.tsx')`
+— only `index.tsx` is the entry point; everything else is imported from it.
+
+## 1. `@core/lib/api` — HTTP client (use this for all API calls)
+
+```ts
+import { apiFetch } from '@core/lib/api'
+```
+
+| Export | Contract |
+|---|---|
+| `apiFetch(path, options?) → Promise<Response>` | Authenticated `fetch`. Auto-attaches `Authorization: Bearer <supabase session>` and `X-Account-Id` when set. Adds a `traceparent` header for request tracing. Derives an `x-app-id` hint from the URL's first segment (server validates it against installed apps). Returns the raw `Response` — check `.ok`, then `.json()`. Strips bogus `Bearer null/undefined` headers you pass. On `401` (except `/api/auth` and `/api/admin-data` paths) it fires the registered unauthorized callback. |
+| `setAccountId(id \| null)` / `getAccountId()` | Set/read the account ID sent as `X-Account-Id` on subsequent calls. AuthContext sets this on login; apps rarely touch it. |
+| `getAuthHeaders() → Promise<Record<string,string>>` | The Bearer + `X-Account-Id` header pair, if you need raw headers (e.g. non-fetch transport). |
+| `onUnauthorized(cb) → unsubscribe` | Register a global 401 handler (framework registers the logout redirect). One callback at a time. |
+
+Debug: `localStorage.spine_debug_api = '1'` logs `X-Request-ID` + traceparent per call.
+
+**Do not** call `fetch()` directly against `/api/*` — you'll lose auth,
+account scoping, and trace headers. For runtime record CRUD, `apiFetch` +
+`/api/admin-data` is the only path (see [admin-data](api/admin-data.md)).
+
+## 2. `@core/hooks/useAppPath` — mount-agnostic navigation (required)
+
+```ts
+import { useAppPath } from '@core/hooks/useAppPath'
+const appPath = useAppPath()
+appPath('/tickets')        // → '/my-app/tickets'  (or '/tickets' when route_prefix === '/')
+appPath('/')               // → '/my-app'          (or '/')
+```
+
+Returns a function that prepends the current app's `route_prefix` (trailing
+slash stripped; `'/'` treated as empty). **All app-internal links and
+`navigate()` calls must go through it** — hardcoding `/dashboard` escapes the
+app when it is directory-mounted, and breaks differently when it is
+root-mounted. Alternatively use relative `path`/`to` inside the app's own
+`<Routes>`.
+
+## 3. `@core/components/ui/*` — the component kit
+
+A shadcn-style kit (~60 components) plus framework-level widgets. Import
+per component: `import { Button } from '@core/components/ui/button'`.
+
+**Framework widgets** (higher-level, Spine-aware):
+
+| Component | Purpose |
+|---|---|
+| `DataTable` | Sortable/paginated table |
+| `ItemListView`, `ItemCard` | Record list/card rendering |
+| `Form`, `field`, `input-group` | Form scaffolding (react-hook-form aligned) |
+| `Modal`, `dialog`, `alert-dialog`, `drawer`, `sheet` | Overlays |
+| `RichTextEditor` | Rich text input |
+| `LoadingSpinner`, `spinner`, `skeleton` | Loading states |
+| `chart` | Chart wrappers (recharts) |
+| `sonner` | Toast notifications |
+
+**Plain kit** (pick what you need): `accordion`, `alert`, `aspect-ratio`,
+`avatar`, `badge`, `breadcrumb`, `button`, `button-group`, `calendar`,
+`card`, `carousel`, `checkbox`, `collapsible`, `combobox`, `command`,
+`context-menu`, `direction`, `dropdown-menu`, `empty`, `hover-card`,
+`input`, `input-otp`, `item`, `kbd`, `label`, `menubar`, `native-select`,
+`navigation-menu`, `pagination`, `popover`, `progress`, `radio-group`,
+`resizable`, `scroll-area`, `select`, `separator`, `sidebar`, `slider`,
+`switch`, `table`, `table-primitives`, `tabs`, `textarea`, `toggle`,
+`toggle-group`, `tooltip`.
+
+## 4. `@core/contexts/AuthContext` — who is signed in
+
+```ts
+import { useAuth } from '@core/contexts/AuthContext'
+const { user, isLoading } = useAuth()
+```
+
+`user` is `null` or a `User` (`@core/types/auth`):
+
+| Field | Notes |
+|---|---|
+| `id`, `email`, `full_name` | Person record identity |
+| `account_id` | Currently active account (drives `X-Account-Id`) |
+| `account?` | The Account row |
+| `roles: string[]` | Role slugs — check `includes('system_admin')` etc. |
+| `permissions: string[]` | Resolved permission strings |
+| `is_system_admin?: boolean` | Shortcut for the system-admin role |
+| `status?: string` | `'pending'` users are gated to the pending-approval page |
+| `accessible_accounts?: Account[]` | Accounts the user may switch between |
+
+## 5. `@core/lib/utils` — `cn` + formatters
+
+```ts
+import { cn, formatDateTime, formatCurrency } from '@core/lib/utils'
+```
+
+`cn(...)` = `twMerge(clsx(...))` for conditional Tailwind classes.
+Formatters: `formatDate`, `formatTime`, `formatDateTime`,
+`formatRelativeTime`, `formatFileSize`, `formatCurrency`, `formatNumber`,
+`truncateText`. Use them instead of hand-rolling `toLocaleString` calls so
+dates/money render consistently with the rest of the shell.
+
+## 6. `@core/components/shared` — instant account/entity UI
+
+| Component | Purpose |
+|---|---|
+| `MemberList` | Account members with roles |
+| `InviteManager` | Invite creation/management UI |
+| `AgentView` | AI-agent interaction surface |
+| `FieldRenderer` | Render a `design_schema` field for display/input |
+| `SchemaFields` | Render a whole `design_schema.fields` section |
+
+`FieldRenderer`/`SchemaFields` are how generic pages render schema-driven
+forms — reuse them in custom apps instead of reimplementing field widgets.
+
+## 7. `@core/hooks/useApi` — request state wrappers
+
+Thin React state over `apiFetch`-style calls. All three return
+`{ data, loading, error, ... }` shapes with cancellation and callbacks.
+
+| Hook | Signature | Use |
+|---|---|---|
+| `useApi<T>` | `(apiFn: (params?) => Promise<T>, { immediate?, onSuccess?, onError?, initialData? })` → `{ data, loading, error, execute, reset, refetch }` | One-shot fetch with cancellation |
+| `usePaginatedApi<T>` | `(apiFn: ({page, itemsPerPage, ...}) => Promise<{data, pagination}>, { itemsPerPage? })` → adds `pagination`, `nextPage`/`prevPage` | Server-paginated lists |
+| `useMutation<T, P>` | `(mutateFn: (params: P) => Promise<T>, { onSuccess?, onError?, onSettled? })` → `{ data, loading, error, mutate, reset }` | Create/update/delete calls |
+
+## 8. `@core/components/kb` — knowledge-base widgets
+
+`KBArticleList`, `KBArticleEditor` — list and editing UI for `kb` records.
+Use when an app surfaces framework knowledge rather than its own KB types.
+
+## 9. Layout, app context, client, types
+
+| Import | Exports | Use |
+|---|---|---|
+| `@core/components/layout` | `AppShell`, `Header`, `Sidebar`, `Layout` | Wrap custom pages in the app chrome |
+| `@core/contexts/AppContext` | `useCurrentApp() → AppRecord`, `useAppsRegistry() → { apps, routableApps, loading, error, refetch }`, `AppProvider`, `AppsRegistryProvider` | Current app's manifest row (slug, route_prefix, config, nav_items); the whole registry |
+| `@core/lib/supabase` | `supabase` (browser client), `getCurrentSession`, `getCurrentUser`, `refreshSession` | Direct Supabase access — prefer `apiFetch`/endpoints for record data |
+| `@core/types` | `DesignSchema`, `FieldDefinition`, `View`/`ListView`/`DetailView`, `ItemType`, `Item`, `PaginationParams`, `SortParams`, `FilterParams`, `FormState` | Shared type defs for schema-driven work |
+
+## Other exports — available, unproven
+
+`useEntityList`, `useEntityRecord`, `useSchemaRecord`, `useListSchema`,
+`useForm`, `useBranding`, `useApps` exist in `hooks/`/`lib/` but shipped
+apps do not use them today (they predate or duplicate the surfaces above).
+Treat as internal scaffolding; prefer the documented tiers.
+
+## Boundaries
+
+- **Never import `@core/pages/*` or `@core/apps/*`** from a custom app —
+  admin/internal pages are not SDK surface (one app importing
+  `pages/admin/LogsPage` is a known violation, not a pattern).
+- **Never import `@shared/*` in frontend code** — server-only modules.
+- Framework code never imports from `custom/`; do not rely on your app
+  being reachable from core.
+- For runtime record CRUD, always `/api/admin-data` via `apiFetch` — never
+  bespoke server endpoints (see [admin-data](api/admin-data.md)).
+
+## Related
+
+- [Build a custom page](../tasks/build-a-custom-page.md) — the task doc
+  that uses this surface end to end
+- [Apps and renderers](../concepts/apps-and-renderers.md) — mounting model
+  and `useAppPath`'s role in it
+- [admin-data API](api/admin-data.md) · [errors and envelopes](api/errors-and-envelopes.md)