spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/hooks/useEntityList.ts

@@ -13,16 +13,15 @@
 import { useState, useEffect, useCallback } from 'react'
 import { useApi } from './useApi'
 import { apiFetch } from '../lib/api'
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:module_header:module_header"]
 // CIL[DOC-VECTOR type="context" content="purpose='Provide React and API imports for the useEntityList hook'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:module_header:module_header"]
 
 
-// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:MinimalEntityListConfig:interface" type="interface" identity="MinimalEntityListConfig" parent="~/.framework/src/hooks/useEntityList.ts"]
 // CIL[DOC-AUDIENCE audience="internal"]
 // CIL[DOC-MACRO purpose="Define the minimal configuration shape for useEntityList"]
 // CIL[DOC-RESPONSIBILITY responsibility="Describe required and optional list configuration fields"]
@@ -31,6 +30,7 @@ import { apiFetch } from '../lib/api'
 // CIL[DOC-MICRO logic_summary="Declares entity, optional typeSlug, API endpoint/listAction, and default sort settings" notable_decisions="list.defaultSort is required"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stable]
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:MinimalEntityListConfig:interface" type="interface" identity="MinimalEntityListConfig" parent="~/.framework/src/hooks/useEntityList.ts"]
 interface MinimalEntityListConfig {
   entity: string
   typeSlug?: string
@@ -42,16 +42,15 @@ interface MinimalEntityListConfig {
     defaultSort: { field: string; direction: 'asc' | 'desc' }
   }
 }
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:MinimalEntityListConfig:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Define the minimal configuration shape for useEntityList'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:MinimalEntityListConfig:interface"]
 
 
-// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:UseEntityListReturn:interface" type="interface" identity="UseEntityListReturn" parent="~/.framework/src/hooks/useEntityList.ts"]
 // CIL[DOC-AUDIENCE audience="internal"]
 // CIL[DOC-MACRO purpose="Define the return shape for useEntityList"]
 // CIL[DOC-RESPONSIBILITY responsibility="Expose state and controls returned by the useEntityList hook"]
@@ -60,6 +59,7 @@ interface MinimalEntityListConfig {
 // CIL[DOC-MICRO logic_summary="Declares data, loading, error, refetch, filters, sort, and pagination state accessors" notable_decisions=""]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stable]
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:UseEntityListReturn:interface" type="interface" identity="UseEntityListReturn" parent="~/.framework/src/hooks/useEntityList.ts"]
 interface UseEntityListReturn {
   data: any[]
   loading: boolean
@@ -77,15 +77,14 @@ interface UseEntityListReturn {
     total: number
   }
 }
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:UseEntityListReturn:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Define the return shape for useEntityList'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:UseEntityListReturn:interface"]
 
-// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:useEntityList:hook" type="hook" identity="useEntityList" parent="~/.framework/src/hooks/useEntityList.ts"]
 // CIL[DOC-AUDIENCE audience="internal"]
 // CIL[DOC-MACRO purpose="Fetch and manage a paginated, sortable, filterable list of entities"]
 // CIL[DOC-RESPONSIBILITY responsibility="Manage list state, build API query parameters, and expose list controls"]
@@ -94,6 +93,7 @@ interface UseEntityListReturn {
 // CIL[DOC-MICRO logic_summary="Computes URL parameters from filters, sort, and pagination; fetches via apiFetch; resets page on filter changes" notable_decisions="Defaults sort to created_at descending; resets page to 1 when filters change"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stable]
+// CIL[BEGIN stable_id="~/.framework/src/hooks/useEntityList.ts:useEntityList:hook" type="hook" identity="useEntityList" parent="~/.framework/src/hooks/useEntityList.ts"]
 export function useEntityList(
   entity: string,
   config: MinimalEntityListConfig | null
@@ -122,7 +122,10 @@ export function useEntityList(
     
     Object.entries(filters).forEach(([key, value]) => {
       if (value !== undefined && value !== '' && value !== 'all') {
-        params.append(key, value.toString())
+        // data.<field> is the documented way to filter on non-system fields;
+        // PostgREST needs the ->> operator form.
+        const paramKey = key.startsWith('data.') ? `data->>${key.slice(5)}` : key
+        params.append(paramKey, value.toString())
       }
     })
     
@@ -172,10 +175,10 @@ export function useEntityList(
     }
   }
 }
+// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:useEntityList:hook"]
 // CIL[DOC-VECTOR type="context" content="purpose='Fetch and manage a paginated, sortable, filterable list of entities'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/hooks/useEntityList.ts:useEntityList:hook"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]

package/.framework/src/hooks/useListSchema.ts

@@ -1,55 +1,88 @@
 // CIL[BEGIN stable_id="~/.framework/src/hooks/useListSchema.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/hooks/useListSchema.ts"]
-// CIL[DOC-AUDIENCE audience="frontend"]
-// CIL[DOC-CONTEXT module="useListSchema" layer="hooks" related_files=".framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="React hooks, apiFetch and DesignSchema/View imports available to the module" errors="none" side_effects="none"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-MACRO purpose="React hook module for loading entity list design schemas"]
-// CIL[DOC-MICRO logic_summary="Imports useState, useEffect, apiFetch and local DesignSchema/View types" notable_decisions="[]"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide the useListSchema hook and its option/result type definitions"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * @module   useListSchema
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * This module provides hooks for managing and interacting with list schemas in the application. It utilizes React's state and effect hooks to fetch and update schema data from an API. INVARIANT: The component using this hook must be wrapped in a provider that supplies the necessary context for API calls.
+ *
+ * @seeAlso apiFetch (handles API requests).
+ * @seeAlso DesignSchema (defines the structure of the schema data).
+ * @seeAlso View (represents the UI components that utilize the schema).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 import { useState, useEffect } from 'react'
 import { apiFetch } from '../lib/api'
 import { DesignSchema, View } from '../types/types'
-// CIL[DOC-VECTOR type="context" content="purpose='React hook module for loading entity list design schemas'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/hooks/useListSchema.ts:module_header:module_header"]
 
 
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/hooks/useListSchema.ts:UseListSchemaOptions:interface" type="interface" identity="UseListSchemaOptions" parent="~/.framework/src/hooks/useListSchema.ts"]
-// CIL[DOC-MACRO purpose="Defines the input options for the useListSchema hook"]
-// CIL[DOC-RESPONSIBILITY responsibility="Declare entity and optional viewSlug used to resolve the list schema"]
-// CIL[DOC-CONTEXT module="useListSchema" layer="hooks" related_files=".framework/src/hooks/useListSchema.ts,.framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-CONTRACT inputs="N/A" outputs="N/A" errors="N/A" side_effects="N/A"]
-// CIL[DOC-MICRO logic_summary="entity: string and viewSlug?: string" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The UseListSchemaOptions interface defines the options for using a list schema in the framework, allowing for the specification of an entity and an optional view slug for enhanced flexibility in list management.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 interface UseListSchemaOptions {
   entity: string
   viewSlug?: string
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the input options for the useListSchema hook'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/hooks/useListSchema.ts:UseListSchemaOptions:interface"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/hooks/useListSchema.ts:UseListSchemaResult:interface" type="interface" identity="UseListSchemaResult" parent="~/.framework/src/hooks/useListSchema.ts"]
-// CIL[DOC-MACRO purpose="Defines the return shape of the useListSchema hook"]
-// CIL[DOC-RESPONSIBILITY responsibility="Declare schema, view, loading state, error and refetch callback"]
-// CIL[DOC-CONTEXT module="useListSchema" layer="hooks" related_files=".framework/src/hooks/useListSchema.ts,.framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-CONTRACT inputs="N/A" outputs="N/A" errors="N/A" side_effects="N/A"]
-// CIL[DOC-MICRO logic_summary="schema, view, loading, error and refetch fields" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The UseListSchemaResult interface defines the structure of the result returned by the useListSchema hook, which is used to manage and retrieve schema data in a React application. It provides information about the loading state, any errors, and a method to refetch the data.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 interface UseListSchemaResult {
   schema: DesignSchema | null
   view: View | null
@@ -57,22 +90,39 @@ interface UseListSchemaResult {
   error: string | null
   refetch: () => void
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the return shape of the useListSchema hook'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/hooks/useListSchema.ts:UseListSchemaResult:interface"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/hooks/useListSchema.ts:useListSchema:hook" type="hook" identity="useListSchema" parent="~/.framework/src/hooks/useListSchema.ts"]
-// CIL[DOC-CONTEXT module="useListSchema" layer="hooks" related_files=".framework/src/hooks/useListSchema.ts,.framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-CONTRACT inputs="options: UseListSchemaOptions" outputs="UseListSchemaResult" errors="Network or API errors set the error string" side_effects="Calls apiFetch on mount and when entity/viewSlug changes; updates local state"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-MACRO purpose="React hook that loads the design schema and view definition for an entity list"]
-// CIL[DOC-MICRO logic_summary="Fetches a sample record to read stamped design_schema; falls back to type lookup and generic fallback views; supports JWT retry" notable_decisions="[]"]
-// CIL[DOC-RESPONSIBILITY responsibility="Fetch and resolve the list design schema and selected view for a given entity"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The useListSchema hook fetches and manages the schema and view for a specified entity in a list format, handling loading states and errors while providing a fallback schema if no data is available.
+ *
+ * @macro       Custom React hook for managing entity list schemas.
+ * @micro       Utilizes asynchronous API calls to fetch data and updates state based on the response.
+ * @inputSpec
+ *   - options: UseListSchemaOptions (required) — configuration options including entity and optional viewSlug.
+ * @outputSpec  UseListSchemaResult — an object containing schema, view, loading state, and error message.
+ * @throws      Error — failed to fetch sample record or invalid authentication.
+ * @sideEffects API calls to /api/admin-data and /api/types for fetching schema data.
+ * @stability   internal
+ * @calls       apiFetch
+ * @errorHandling Retries fetching schema on specific authentication errors.
+ * @cil-generated
+ */
 export function useListSchema(options: UseListSchemaOptions): UseListSchemaResult {
   const { entity, viewSlug = 'default_list' } = options
   
@@ -149,12 +199,12 @@ export function useListSchema(options: UseListSchemaOptions): UseListSchemaResul
         let resolvedSchema: DesignSchema | null = null
 
         if (kind) {
-          const typeResp = await apiFetch(`/api/types?kind=${kind}&limit=1`)
+          const typeResp = await apiFetch(`/api/types?action=list&kind=${kind}`)
           if (typeResp.ok) {
             const typeData = await typeResp.json()
-            const typeRecord = typeData.data?.[0]
-            if (typeRecord?.design_schema) {
-              resolvedSchema = typeRecord.design_schema as DesignSchema
+            const typeRecords = Array.isArray(typeData.data) ? typeData.data : []
+            if (typeRecords.length === 1 && typeRecords[0]?.design_schema) {
+              resolvedSchema = typeRecords[0].design_schema as DesignSchema
             }
           }
         }
@@ -243,10 +293,10 @@ export function useListSchema(options: UseListSchemaOptions): UseListSchemaResul
     refetch: fetchSchema
   }
 }
-// CIL[DOC-VECTOR type="context" content="purpose='React hook that loads the design schema and view definition for an entity list'; No verified external callers; imports: .framework/src/lib/api.ts,.framework/src/types/types.ts"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/hooks/useListSchema.ts:useListSchema:hook"]
+// CIL[END stable_id="~/.framework/src/hooks/useListSchema.ts:useListSchema:hook"]
+
+
+
+
+
+

package/.framework/src/instructions/README.md

@@ -0,0 +1,74 @@
+---
+title: Spine Instruction Book
+audience: developers, agents
+kind: index
+verified_against: 4d9d52a
+verified_on: 2026-10-29
+source_files:
+  - .framework/src/instructions/
+---
+
+# Spine Instruction Book
+
+This directory is the instruction book shipped with the `spine-framework` npm
+package. It is written for two readers: **developers** building on Spine, and
+**agents** (human or AI) operating a Spine deployment. Every file must pass
+`npm run docs:lint` — see `docs/audit/docs-spec.md` in the repo for the
+authoring spec.
+
+## Structure
+
+| Section | Kind | Contents |
+|---|---|---|
+| `guide/` | guide | End-to-end walkthroughs (install, first app, deploy). |
+| `concepts/` | concept | Mental models — tenancy, permissions, types, runtime vs config. |
+| `tasks/` | task | Single-goal procedures with prerequisites and verification steps. |
+| `reference/` | reference | Exhaustive lookups — env vars, CLI commands, API endpoints, schema enums. |
+| `operations/` | ui | Admin-UI pages and operational runbooks. |
+| `internal/` | * | Repo-only/internal docs; exempt from the archived-docs and CIL-tooling reference rules. |
+| *(root)* | entity | One file per Spine entity (`types`, `apps`, `roles`, …). |
+
+## Reading order — developers
+
+1. `guide/` getting-started, then `concepts/` tenancy & permissions.
+2. The `entity` files for the types you will create (`types.md` first).
+3. `tasks/` for the specific job at hand; `reference/` for exact spellings.
+
+## Reading order — agents
+
+1. `concepts/` — know what a Spine account, type, and record are.
+2. `entity` files — the 7-section template below tells you what each entity is
+   for, its fields, minimal/full configuration, a worked example, the core
+   files, and agent-specific cautions.
+3. `operations/` — how to drive the admin UI; `internal/` — repo-only notes.
+
+## The 7-section entity template
+
+Every `entity` or `ui` doc uses the same seven `##` sections, in order:
+
+1. `## What this is for`
+2. `## Fields and settings`
+3. `## Minimal configuration`
+4. `## Full configuration`
+5. `## Example`
+6. `## Core files`
+7. `## Agent notes`
+
+`docs-lint` enforces the heading set verbatim.
+
+## Key pages
+
+- Building frontend: [Frontend SDK (`@core`)](reference/frontend-sdk.md) —
+  every importable module, contract-ordered by real usage.
+- Registering/mounting apps:
+  [tasks/register-an-app](tasks/register-an-app.md) +
+  [Mounting](concepts/apps-and-renderers.md#mounting-directory-or-root).
+- App-shipped docs/skills: [tasks/document-your-app](tasks/document-your-app.md).
+
+## `internal/` — the doctrine
+
+`internal/docs-contract.md` is the editorial contract for this book — the
+test rule (every miss is a doc bug), the capture contract (docs are part of
+every code change, core and custom), the layer taxonomy, and the cold-agent
+acceptance matrix that regression-tests the book. Read it before adding or
+restructuring pages.

package/.framework/src/instructions/accounts.md

@@ -0,0 +1,97 @@
+---
+title: Accounts
+audience: both
+kind: entity
+verified_against: b3b3ae0
+verified_on: 2026-11-01
+source_files:
+  - .framework/migrations/001_core_schema.sql
+  - .framework/functions/account-nodes.ts
+  - .framework/src/lib/api.ts
+  - .framework/src/lib/registration.ts
+  - .framework/cli/commands/install-app.ts
+---
+
+# Accounts
+
+## What this is for
+
+An **account** is the tenant boundary — nearly every scoped row in the
+database hangs off one `account_id`. Accounts form hierarchies (a parent
+account plus descendants), and a person may access several accounts and
+switch between them. Record `scope: "account"` in a type's `design_schema`
+means "rows belong to the active account"; `scope: "platform"` means the
+spine-system account.
+
+## Fields and settings
+
+| Column | Notes |
+|---|---|
+| `slug` | UNIQUE — stable identifier (`spine-system` is the platform account). |
+| `display_name` | Human name shown in the account switcher. |
+| `parent_id` | FK → `accounts` — places this account in the hierarchy. |
+| `type_id` | Accounts are typed records; the type's `design_schema` governs `data`. |
+| `data` | jsonb — type-defined fields. |
+| `logs_retention_days`, `observability_retention_days` | Per-account retention knobs. |
+
+**Hierarchy mechanics**
+
+- `account_paths` is the closure table (`ancestor_id`, `descendant_id`,
+  `depth`) — ancestors/descendants resolve via
+  `get_account_ancestors`/`get_accessible_accounts` RPCs, not recursive
+  queries you write.
+- `GET /api/account-nodes?node_id=<id>` returns a node with its
+  `type:types(...)` join, ancestors, and children — the admin tree view's
+  data source.
+
+**The active account**
+
+- The client sends `X-Account-Id` on every `apiFetch` (set by AuthContext
+  via `setAccountId`). Server-side `ctx.accountId` scopes reads/writes and
+  `current_actor_id()`-based RLS.
+- `user.accessible_accounts` lists the accounts a person may switch
+  between; switching is a client-side `setAccountId` change, not a
+  re-login.
+
+**App-driven placement**
+
+- A manifest `registration` block decides where new accounts/people land:
+  `account_strategy: 'new' | 'existing'`, `parent_account`,
+  `target_account`, `default_workspace_name`. The installer syncs it to
+  `apps.config.registration` + `spine.config.json` (see
+  [App manifest reference](reference/app-manifest.md)).
+
+## Minimal configuration
+
+`slug`, `display_name`, `type_id`, plus `parent_id` when it isn't a root
+account.
+
+## Full configuration
+
+Adds `data` fields from the account type's `design_schema`, retention
+settings, and hierarchy position via `parent_id`/`account_paths`.
+
+## Example
+
+A white-label app registers with `account_strategy: 'new'` +
+`parent_account: 'spine-system'`: each new customer signup provisions a
+child account under the platform account; support staff in the parent see
+all children through the account switcher while customers stay scoped.
+
+## Core files
+
+- `.framework/migrations/001_core_schema.sql` — `accounts` +
+  `account_paths` closure table
+- `.framework/functions/account-nodes.ts` — node + ancestors + children API
+- `.framework/src/lib/api.ts` — `X-Account-Id` on every request
+- `.framework/src/lib/registration.ts` — signup → placement
+- `.framework/cli/commands/install-app.ts` — `registration` → config sync
+
+## Agent notes
+
+- Scope confusion is the #1 tenancy bug: a record created under the wrong
+  `account_id` is invisible to the right users — always confirm which
+  account is active before writing.
+- `spine-system` is the platform account; `scope: "platform"` types and
+  system roles live there. Do not put tenant data in it.
+- Never hand-maintain `account_paths` — it is derived from `parent_id`.

package/.framework/src/instructions/ai-agents.md

@@ -0,0 +1,69 @@
+---
+title: AI Agents
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/ai-agents.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/src/pages/admin/AIAgentsPage.tsx
+  - .framework/src/pages/admin/AIAgentDetailPage.tsx
+---
+
+## What this is for
+
+An **AI agent** is a reusable model + prompt + tool configuration that Spine invokes from pipelines, triggers, and chat interfaces. It defines how an LLM behaves, which tools it can call, and its guardrails.
+
+## Fields and settings
+
+- **Name** — string. Display name used in lists and by callers; required.
+- **Type** — select: `chat`, `analysis`, `automation`, `custom`. Categorizes and routes the agent; defaults to `chat`.
+- **Model** — string. Stored in `model_config.model`. Blank falls back to `LLM_DEFAULT_MODEL` env then `gpt-4o` at inference time — set it explicitly so the behavior isn't env-dependent.
+- **Max Tokens** — number. Maximum response length; empty values can cause provider errors.
+- **Temperature** — number 0–2. Lower = deterministic, higher = random; out-of-range values may be rejected by the provider.
+- **Description** — string, optional.
+- **System Prompt** — text. The agent's personality, instructions, and constraints. Empty = no system message sent.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Tools (one per line)** — newline-separated tool names the agent may invoke. Names must match registered tools exactly.
+- **Capabilities / Constraints / Metadata (JSON)** — optional objects: feature flags, guardrails, free-form metadata. Invalid JSON blocks save.
+- **Active** — checkbox. Inactive agents are hidden from callers and cannot be invoked.
+
+**Downstream effects**
+
+- Pipelines, triggers, and chat UIs reference agents by ID — changing the model changes their output everywhere.
+- Tool names must match the tool registry exactly; unknown names produce runtime errors when invoked.
+- `system_prompt` composes with the caller's prompt config — conflicting instructions between the two cause unpredictable behavior.
+
+## Minimal configuration
+
+```json
+{
+  "name": "Triage agent",
+  "agent_type": "automation",
+  "model_config": { "model": "gpt-4o", "temperature": 0.3, "max_tokens": 2000 },
+  "system_prompt": "You classify inbound support tickets...",
+  "is_active": true
+}
+```
+
+## Full configuration
+
+Adds `tools` (the registered tool names the agent may call), `capabilities` (e.g. `{ "json_mode": true, "streaming": false }`), `constraints` (e.g. `{ "max_tool_calls": 5, "disallowed": ["delete"] }`), and `metadata`.
+
+## Example
+
+A support app's triage agent (`agent_type: "automation"`, low temperature) classifies new tickets and calls a `set_field` tool to tag them; its companion chat agent (`agent_type: "chat"`, higher temperature, `tools: [search_kb]`) drafts replies for human review.
+
+## Core files
+
+- `.framework/functions/ai-agents.ts` — API
+- `.framework/functions/ai-interactions.ts` — invocation/interaction records
+- `.framework/src/pages/admin/AIAgentsPage.tsx` / `AIAgentDetailPage.tsx` — admin UI
+- Table: `public.ai_agents`
+
+## Agent notes
+
+- The detail form stores model settings under `model_config` — a flat `model` field on the record will be ignored by callers.
+- Pair agents with a `prompt_configs` entry for the prompt body; the agent record holds behavior, the prompt config holds text.
+- Validate JSON fields before saving — a parse failure silently keeps the previous config.

package/.framework/src/instructions/alerts.md

@@ -0,0 +1,80 @@
+---
+title: Threshold Alerts
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/pages/admin/AlertsConfigPage.tsx
+  - .framework/functions/admin-data.ts
+  - .framework/functions/system-cron.ts
+  - .framework/functions/observability.ts
+---
+
+## What this is for
+
+**Threshold Alerts** (`/spine-framework/admin/observability/alerts`) manages alert rules over platform metrics. Each alert is a runtime `items` record of type `threshold_alert`, edited through the generic `admin-data` API. `system-cron` evaluates them every tick; a breach emits a `threshold.breached` log event (visible under Logs and on the Observability dashboard) and can invoke a linked pipeline.
+
+## Fields and settings
+
+- **Title / Description** — record `title` and `description` shown in the list.
+- **Status** — `active` or `inactive`; toggled per-row (writes both `status` and `data.is_active`).
+- **Metric** (`data.metric`) — `error_rate` (%), `latency_p95` (ms), or `pipeline_failure_rate` (%).
+- **Operator** (`data.operator`) — `gt` (>) or `lt` (<).
+- **Value** (`data.value`) — the threshold number, in the metric's unit.
+- **Window** (`data.window_minutes`) — lookback window the metric is computed over.
+- **Pipeline** (`data.pipeline_id`) — optional pipeline invoked when the threshold is breached; populated from `/api/pipelines?action=list`.
+- Stats cards — Total, Active, Inactive, With Pipeline.
+
+**Downstream effects**
+
+- Alerts are plain `items` records — create/edit/delete goes through `/api/admin-data?entity=items` with `type_id: "threshold_alert"`, so they inherit the type's `record_permissions` and validation.
+- `system-cron` evaluates each active alert every tick against the observability metrics; breaching emits `threshold.breached` log events.
+- An alert without a `pipeline_id` still logs breach events — the pipeline link is what turns a breach into an action.
+- Deleting an alert hard-removes the record; there is no history table beyond `logs`.
+
+## Minimal configuration
+
+```
+Title: High error rate
+data.metric: error_rate · data.operator: gt · data.value: 5
+data.window_minutes: 60 · is_active: true
+```
+
+## Full configuration
+
+```json
+{
+  "type_id": "threshold_alert",
+  "title": "P95 latency above 2s",
+  "description": "Page on sustained slow requests",
+  "status": "active",
+  "data": {
+    "metric": "latency_p95",
+    "operator": "gt",
+    "value": 2000,
+    "window_minutes": 30,
+    "pipeline_id": "<pipeline uuid>",
+    "is_active": true
+  }
+}
+```
+
+## Example
+
+A platform team keeps three alerts: `error_rate > 5% / 60min` paging the on-call pipeline, `latency_p95 > 2000ms / 30min` opening an incident thread, and `pipeline_failure_rate > 10% / 15min` running a diagnostics pipeline that snapshots recent executions.
+
+## Core files
+
+- `.framework/src/pages/admin/AlertsConfigPage.tsx` — this page (modal create/edit, toggle, delete)
+- `.framework/functions/admin-data.ts` — CRUD backend (`entity=items`, `type_id=threshold_alert`)
+- `.framework/functions/system-cron.ts` — per-tick threshold evaluation, emits `threshold.breached`
+- `.framework/functions/observability.ts` — `error_rate`/`latency_percentiles`/`pipeline_stats` metrics the alerts compare against
+- Table: `public.items` rows of type `threshold_alert`
+
+## Agent notes
+
+- The type slug is `threshold_alert` and the config lives under `data.*` — do not confuse it with the `pipelines`/`triggers` config tables.
+- `status` and `data.is_active` are written together by the toggle; editing the record elsewhere can desync them — the evaluator reads `data.is_active`.
+- Breach events are the audit trail: filter Logs by `threshold.breached` to see when and how often an alert fired.
+- There is no dedupe/cooldown field — a breached metric re-fires each tick; build any cooldown into the linked pipeline.