spine-framework 0.4.4 → 0.5.0-rc.4

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,57 @@
+---
+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.

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.

package/.framework/src/instructions/api-keys.md

@@ -0,0 +1,87 @@
+---
+title: API Keys
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/api-keys.ts
+  - .framework/functions/_shared/hash-api-key.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/logging.ts
+  - .framework/src/pages/admin/APIKeysPage.tsx
+  - .framework/src/pages/admin/APIKeyDetailPage.tsx
+---
+
+## What this is for
+
+An **API key** authenticates callers to Spine — integrations, MCP servers, CLI tooling, and service-to-service calls. A key controls which callers are accepted, how fast they can call, and which permissions they carry.
+
+## Fields and settings
+
+- **Name** *(required)* — human-readable label; missing name blocks creation.
+- **Integration ID** — optional UUID of the integration this key serves.
+- **App ID** — optional UUID/slug of the owning app (server resolves slugs via `resolveAppUuid`).
+- **Key Type** — `inbound` (external callers into Spine), `outbound` (Spine calling out), `internal` (service-to-service), `cli` (scripts/tooling). Determines how the key is validated.
+- **Key Prefix** — derived server-side: the raw key is `sk_<uuid>` and `key_prefix` stores its first 8 characters for lookup. Not a form field.
+- **Rate Limit (requests/min)** — `rate_limit`, UI range 1–10000. Enforced per key inside `rate_limit_window_seconds` (default 60s, overridable via key `config`). An unset/`0` value falls back to the default 100 — it does not block requests.
+- **Expires At** — optional date; after it the key is rejected.
+- **Machine Type** — machine principal type, e.g. `integration`.
+- **Internal** — marks the key for internal service-to-service use.
+- **Active** — inactive keys are rejected on every call.
+- **Permissions / Scopes / Metadata (JSON)** — `permissions` and `scopes` are string arrays (validated against required permissions on `action=validate`); `metadata` is free-form. Invalid JSON fails creation.
+
+**Downstream effects**
+
+- The gateway validates `key_prefix` + `key_hash` on every call — inactive, expired, or over-limit keys are rejected.
+- The raw key is returned **once** at create (`raw_key` in the response envelope). It is never stored or returned again — `key_value`/`key_hash` are stripped from all API responses (S-001/F-040).
+- The API has no update action (list/get/create plus `validate`, `revoke`, `usage-logs`) — rotate = create new + revoke old.
+- Keys still referenced in local MCP configs or scripts fail immediately when revoked/deactivated.
+
+## Minimal configuration
+
+```json
+{
+  "name": "CI deploy key",
+  "key_type": "cli",
+  "rate_limit": 60,
+  "is_active": true
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Workbench MCP",
+  "key_type": "inbound",
+  "app_id": "workbench",
+  "rate_limit": 600,
+  "expires_at": "2027-01-01",
+  "machine_type": "integration",
+  "is_active": true,
+  "permissions": ["admin-data:read"],
+  "scopes": ["admin-data:read", "logs:read"],
+  "metadata": { "env": "dev" }
+}
+```
+
+## Example
+
+A local MCP server authenticates with an `inbound` key scoped to read-only admin-data calls; a separate `cli` key (low rate limit) backs the `spine-framework` CLI. A leaked key gets rotated by creating a replacement and revoking the old one — the audit found a plaintext-stored legacy key and deactivated it (S-001/S-003).
+
+## Core files
+
+- `.framework/functions/api-keys.ts` — API (create/list/get + `validate`/`revoke`/`usage-logs` actions; mints `sk_<uuid>` raw key)
+- `.framework/functions/_shared/hash-api-key.ts` — `hashApiKey`, `verifyApiKey` (pbkdf2), `omitSecretFields` (strips `key_value`/`key_hash`)
+- `.framework/functions/_shared/logging.ts` — `resolveAppUuid` (app slug → UUID on create)
+- `.framework/functions/_shared/principal.ts` — per-request key resolution (`x-api-key` → prefix lookup → pbkdf2 verify → per-key + per-IP rate limit)
+- `.framework/cli/context.ts` — CLI auth path (F-042)
+- `.framework/src/pages/admin/APIKeysPage.tsx` / `APIKeyDetailPage.tsx` — admin UI
+- Table: `public.api_keys`
+
+## Agent notes
+
+- Copy `raw_key` at creation — there is no "show key" later. Treat any key whose value was ever visible as burned.
+- Prefer short `expires_at` + documented `metadata.env` over long-lived keys.
+- `key_type: cli` + a `permissions` array is the documented path for scripted/agent access (see S-002 — a first-class scriptable login is still pending).

package/.framework/src/instructions/apps.md

@@ -0,0 +1,77 @@
+---
+title: Apps
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/apps.ts
+  - .framework/src/pages/admin/AppsPage.tsx
+  - .framework/src/pages/admin/AppDetailPage.tsx
+  - .framework/migrations/003_core_system_data.sql
+  - .framework/migrations/013_get_account_apps_role_filter.sql
+---
+
+## What this is for
+
+An **app** is a registered application in Spine. The registry controls navigation visibility, who can open the app (min role), how it renders (generic vs custom), and the JSON configuration the app or its types consume at runtime.
+
+## Fields and settings
+
+- **Name** — string. Display name in the app switcher and registry.
+- **Slug** — string. Unique identifier; set at creation, rarely changed. Routes and API scoping depend on it.
+- **Description** — string, optional. Short text shown in the app list.
+- **App Type** — select: `system`, `custom`, `marketplace`. Drives how the platform treats the app.
+- **Source** — select: `system`, `custom`, `marketplace`. Tracks where the package came from.
+- **Min Role** — select: `member`, `admin`, `owner`. Lowest role that can see/open the app.
+- **Version** — string. Current version shown in the registry.
+- **Active** — boolean. Inactive apps are hidden and cannot be opened.
+- **System** — boolean. Protects the app from tenant-level deletion.
+- **Icon / Color** — UI presentation for the app tile.
+- **Route Prefix** — string, optional. URL prefix (defaults to `/slug`).
+- **Renderer** — select: `generic` (renders list/detail from type `design_schema.views`), `custom` (app renders its own pages), `none`.
+- **Config (JSON)** — `config` column; runtime config for the app or its generic renderer.
+- **Nav Items (JSON)** — array of navigation items for the app shell.
+- **Integration Deps (JSON)** — array of integration slugs the app depends on.
+- **Metadata (JSON)** — free-form metadata.
+
+**Downstream effects**
+
+- The app shell reads `slug`, `route_prefix`, `min_role`, `is_active`, `icon`, `color`, `nav_items` to build navigation and gate access.
+- `renderer = generic` requires every served type to have complete `views` in its `design_schema`.
+- `min_role` raises the floor for the whole app — setting `admin` hides it from members even if record permissions would allow reads.
+
+## Minimal configuration
+
+```json
+{
+  "slug": "my-app",
+  "name": "My App",
+  "app_type": "custom",
+  "source": "custom",
+  "renderer": "custom",
+  "is_active": true,
+  "min_role": "member"
+}
+```
+
+## Full configuration
+
+Adds `version`, `icon`, `color`, `route_prefix`, `config` (feature flags, default views), `nav_items` (grouped sidebar entries), `integration_deps` (e.g. `["openai", "sendgrid"]`), and `metadata` (author, homepage, tags).
+
+## Example
+
+A support app registers with `renderer: "custom"`, `route_prefix: "/answer-once"`, `min_role: "member"`, and `integration_deps: ["openai"]` — the admin renders its own pages but still uses `/api/admin-data` for record CRUD and `types` for its ticket/thread types.
+
+## Core files
+
+- `.framework/functions/apps.ts` — API (list/get/create/update/delete)
+- `.framework/src/pages/admin/AppsPage.tsx` / `AppDetailPage.tsx` — admin UI
+- `.framework/src/components/app-shell/` — shell, generic renderer, app registry
+- Table: `public.apps` (+ `get_account_apps` RPC for counts)
+
+## Agent notes
+
+- `renderer = "custom"` still needs `fields` + `record_permissions` on its types so `admin-data` can stamp and validate records.
+- Slug appears in API envelopes and `x-app-id` headers — renaming an in-use slug breaks logging attribution and callers.
+- `marketplace` as a type/source value is under review (F-031) — prefer `custom` for new apps.