spine-framework 0.4.3 → 0.5.0-rc.4

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/functions/account-nodes.md

@@ -0,0 +1,75 @@
+---
+title: account-nodes
+audience: both
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/account-nodes.ts
+  - .framework/functions/_shared/middleware.ts
+  - .framework/public/_redirects
+---
+
+# account-nodes
+
+## What it does
+
+Returns one account ("node") plus its position in the account hierarchy:
+ancestors, direct children, and full descendants. Used to render account
+trees and breadcrumb navigation.
+
+## Route and methods
+
+`/.netlify/functions/account-nodes`, reachable as
+`GET /api/account-nodes?node_id=<uuid>` (`/api/*` →
+`/.netlify/functions/:splat`). The handler performs no method check — any
+HTTP method with the query parameter works.
+
+## Authentication
+
+Standard `createHandler`: `x-api-key`, internal secret, or
+`Bearer <jwt>` required; anonymous is rejected with 401. Queries run on
+`ctx.db`, so human callers see only what row-level security allows; machine
+and system principals use the service role.
+
+## Request contract
+
+One query parameter:
+
+- `node_id` — required, the `accounts.id` to center the lookup on.
+
+## Response contract
+
+`{ node, ancestors, children, descendants }` inside the standard
+`{ data, error, meta }` envelope:
+
+- `node` — the account row's embedded `type` (`{ type: { id, slug, name,
+  icon, color } }`); the account's own columns are not selected.
+- `ancestors` — rows returned by the `get_account_ancestors` RPC, else `[]`.
+- `children` — active `accounts` rows with `parent_id = node_id`, each
+  shaped `{ type: {...} }`, ordered by `display_name`.
+- `descendants` — rows returned by the `get_account_descendants` RPC, else `[]`.
+
+## Side effects
+
+None — read-only. A `request.get` span is emitted by the middleware like
+every `createHandler` call.
+
+## Errors
+
+| Condition | HTTP | Message |
+|---|---|---|
+| Missing `node_id` | 500 | `node_id is required` |
+| No active account with that id | 500 | `Account node not found` |
+| RPC/query failure | 500 | underlying PostgREST message |
+
+## Agent notes
+
+- The `select` on `node` and `children` contains only the embedded `type`
+  relation — do not expect `display_name`, `slug`, or other account
+  columns on those payloads; fetch the account itself via
+  `/api/admin-data?entity=accounts&id=…` when you need them.
+- `ancestors`/`descendants` come from database functions; their row shape
+  is whatever the RPC returns, not the `{ type }` shape used for `node`.
+- Inactive accounts are filtered from `node` and `children`
+  (`is_active = true`) but RPC results are whatever the functions return.