spine-framework 0.4.4 → 0.5.0-rc.5

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: b3b3ae0
+verified_on: 2026-11-01
+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 where the app mounts (defaults to `/slug`). `"/"` mounts the app at the site root (exactly one app may own it; the app must render its own not-found); nested prefixes like `/crm/sales` work longest-first. `/spine-framework/*` is reserved. See [Apps and Renderers → Mounting](concepts/apps-and-renderers.md#mounting-directory-or-root).
+- **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.

package/.framework/src/instructions/concepts/ai-and-prompts.md

@@ -0,0 +1,150 @@
+---
+title: "AI agents, prompt configs, and embeddings"
+audience: developers, agents
+kind: concept
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/ai-agents.ts
+  - .framework/functions/prompt-configs.ts
+  - .framework/functions/embeddings.ts
+  - .framework/functions/ai-interactions.ts
+  - .framework/functions/_shared/agent-runner.ts
+  - .framework/functions/_shared/llm.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/migrations/034_match_embeddings_knn.sql
+  - .framework/migrations/044_match_embeddings_filtered_knn.sql
+---
+
+# AI agents, prompt configs, and embeddings
+
+Three config entities shape Spine's AI behavior:
+
+- An **AI agent** (`public.ai_agents`) is the *who*: a named model + system
+  prompt + tool set + guardrails.
+- A **prompt config** (`public.prompt_configs`) is the *how*: the prompt
+  template, model parameters, retrieval sources, and escalation policy applied
+  to a conversation.
+- An **embedding** (`public.embeddings`) is the *memory*: per-document vector
+  rows that semantic retrieval searches over.
+
+All three are ordinary admin-data-managed rows: `ai-agents` and
+`prompt-configs` expose CRUD via their own functions, and the conversational
+runtime lives in `.framework/functions/_shared/agent-runner.ts`.
+
+## Agent configuration
+
+`ai-agents` (`.framework/functions/ai-agents.ts`) stores, per row:
+
+- `name` + `agent_type` — required (`chat`, `analysis`, `automation`,
+  `custom` in the admin UI).
+- `model_config` — `{ model, temperature, max_tokens, tools }`. At inference
+  time the model resolves as `model_config.model || LLM_DEFAULT_MODEL ||
+  'gpt-4o'`; `model_config.tools` is passed through as OpenAI tool definitions
+  with `tool_choice: 'auto'`.
+- `system_prompt` — concatenated with the prompt config's `system_prompt`
+  (agent first) to form the system message.
+- `tools`, `capabilities`, `constraints`, `metadata` — `metadata
+  .default_prompt_config_id` is the fallback used when the thread doesn't
+  stamp its own `prompt_config_id`.
+- `is_active` — inactive agents fail `resolveAgentConfig` lookup.
+
+## Prompt configs and templating
+
+`prompt-configs` (`.framework/functions/prompt-configs.ts`) carries the fields
+the runner consumes per turn: `system_prompt`, `context_template`, `model`
+(default `gpt-4o`), `temperature` (0.7), `max_tokens` (4000),
+`is_multi_turn` (true), `max_history_messages` (20), `confidence_threshold`,
+`escalation_action` / `escalation_target`, `output_mode` / `output_field`,
+`requires_review`, `knowledge_sources`, `available_tools`, and
+`tool_constraints`.
+
+`context_template` supports exactly two placeholders, substituted in
+`buildContext`: `{{user_message}}` (the inbound text, truncated to 4000 chars)
+and `{{conversation_history}}` (prior messages rendered as
+`Customer:`/`Agent:` lines, truncated to 4000 chars).
+
+## How a thread resolves its agent and prompt
+
+`resolveAgentConfig` in `.framework/functions/_shared/agent-runner.ts`:
+
+1. Reads the thread (`threads`, joined with its `types` row).
+2. Agent id comes from `thread.data.agent_id`, falling back to the thread
+   type's `design_schema.default_agent_id`. No agent → the run aborts.
+3. Prompt config id comes from `thread.data.prompt_config_id`, falling back to
+   `agent.metadata.default_prompt_config_id`.
+4. Both rows must be `is_active`.
+
+`buildContext` then assembles the model input: combined system prompt, the
+rendered `context_template`, retrieved knowledge excerpts (numbered `[n]` and
+explicitly marked *untrusted* — the prompt instructs the model to treat them as
+evidence, never instructions), `## Conversation History`, `## Tool Results`,
+the filtered `available_tools` list, and finally `## Current Message` with a
+prompt-injection warning.
+
+## Invoking an agent
+
+The interactive path is `POST /api/ai-agents?action=run` with `{ thread_id,
+user_message, mode }` — `mode` is `step`, `complete`, or `episode` (default
+`complete`). Before any tokens are spent the handler runs a prompt-injection
+preflight (`detectInjection`); the app's `security.prompt_injection` setting
+chooses `off` | `flag` (default) | `block`. Each claimed run debits the
+`agent_step` rate limit.
+
+Inside a run, `runAgent`/`runAgentStep` build context, call inference, dispatch
+any `tool_calls` the model returns through `executeToolAction`, persist the
+outbound `messages` row stamped with `agent_id` and `prompt_config_id`, and
+manage the episode lease (see [concurrency](./concurrency-and-idempotency.md)).
+
+Pipelines reach AI through stage types, not the `run` action:
+
+- `agent_inference` — POSTs `{ context, model, temperature, max_tokens }` to
+  `config.webhook_url` via `integration-outbound` (`generic-http`); without a
+  `webhook_url` it returns a mock response.
+- `search_knowledge` — retrieval over knowledge sources for the stage config's
+  `query`.
+- `generate_embeddings` / `revoke_embeddings` / `kb_ingest` / `kb_revoke` /
+  `create_interaction` — delegate to the `embeddings`, `kb`, and
+  `ai-interactions` functions described below.
+
+## The LLM call itself
+
+`_shared/llm.ts` does not hold API keys. `callOpenAI` routes every request
+through `integration-outbound` with `integration_slug: 'openai'` and
+`credential_field: 'api_token'` — credentials come from the `integrations`
+table like any other outbound call. `callOpenAIChat` defaults to
+`gpt-4o-mini`/0.7/4000 tokens, overridable per call and via
+`integration.config.models.chat` / `.embedding`. When no OpenAI integration or
+credential exists, inference returns a clearly-marked mock response rather than
+failing.
+
+## Embeddings and retrieval
+
+`embeddings` (`.framework/functions/embeddings.ts`) manages the
+`public.embeddings` vector store:
+
+- `action=generate` builds embeddable text per **vector type**. The type's
+  `design_schema.vector_types` decides which builders run — default
+  `['semantic', 'structure']`; registered builders also cover `intent`,
+  `cause`, `procedure`, `outcome`, `context`, and `error_signal`. Each vector
+  type occupies a fixed `chunk_index` slot so concurrent types never collide
+  on the unique constraint, and unchanged content is skipped by hash.
+- `action=revoke` sets `revoked_at` on a document's vectors; `action=approve`
+  sets `approved_at` and clears revocation.
+- `action=search-similar` calls the `match_embeddings` RPC (pgvector KNN,
+  defined in migrations `034`/`044`) with `query_embedding`, `match_count`,
+  `similarity_threshold`, and optional account/vector-type/item-type/document
+  filters.
+- `action=search-semantic` is a Postgres `websearch` full-text query over the
+  `content` column — the lexical complement to vector search.
+
+## Interaction records
+
+`ai-interactions` (`.framework/functions/ai-interactions.ts`) writes the
+feedback/observability side of the loop as `items` rows (default type
+`ai_feedback_record`, overridable via `type_slug`; the call returns
+`{ skipped: true }` when the type isn't installed). Actions:
+`submit_feedback`, `create_interaction` (what the pipeline stage calls — it
+stamps `thread_id`, `ai_message_id`, `retrieved_sources`, `ai_confidence`,
+`kb_candidate`, and review fields), `update_interaction`,
+`create_cil_proposal`, and `list`.

package/.framework/src/instructions/concepts/apps-and-renderers.md

@@ -0,0 +1,228 @@
+---
+title: Apps and Renderers
+audience: developers, agents
+kind: concept
+verified_against: b3b3ae0
+verified_on: 2026-11-01
+source_files:
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/013_get_account_apps_role_filter.sql
+  - .framework/migrations/014_apps_required_roles.sql
+  - .framework/src/App.tsx
+  - .framework/src/components/AppWrapper.tsx
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - .framework/src/components/app-shell/GenericListPage.tsx
+  - .framework/src/components/app-shell/GenericDetailPage.tsx
+  - .framework/functions/_shared/app-manifest.ts
+  - .framework/functions/apps.ts
+  - .framework/cli/commands/create-app.ts
+  - .framework/cli/commands/install-app.ts
+---
+
+# Apps and Renderers
+
+An app in Spine is a **row in `public.apps`** plus — for apps that render their
+own UI — a directory of code. The registry row decides where the app mounts,
+who can open it, and *how* it renders. The `renderer` column is the fork in
+the road.
+
+## The registry row
+
+`.framework/migrations/001_core_schema.sql` defines `public.apps`: unique
+`slug`, `name`, `route_prefix`, `renderer` (CHECK constraint:
+`'generic' | 'custom' | 'none'`), `min_role`, `required_roles` (added in
+migration 014), `nav_items`, `config`, `integration_deps`, `metadata`,
+`is_active`, `is_system`, `owner_account_id`, domains.
+
+- `route_prefix` (defaults to `/<slug>`) is where the SPA mounts the app —
+  `.framework/src/App.tsx` builds a `<Route>` per active app.
+- `is_active: false` removes the app from navigation and routing.
+- `is_system: true` protects the row from tenant-level deletion.
+
+## Mounting: directory or root
+
+`route_prefix` is the whole mount contract. Every routable app
+(`route_prefix != null`, `renderer !== 'none'`) becomes a
+`<Route path="<prefix>/*">` in `.framework/src/App.tsx`:
+
+- **Directory mount** — `"/portal"` → the app owns `/portal/*`.
+- **Root mount** — `"/"` → the app owns `/*` and renders directly at `/` for
+  non-admin users.
+- **Nested mount** — `"/crm/sales"` works mechanically (`/crm/sales/*`);
+  prefixes sort longest-first, so `/crm/sales` wins over `/crm`. Supported
+  but unusual.
+
+### Host-keyed mount overrides
+
+`prod_domain` + `prod_route_prefix` (and the `preview_` pair for
+`VITE_ENVIRONMENT=preview`) let one row mount differently per hostname
+(`.framework/src/lib/app-mount.ts`, resolved in `useApps`/`AppContext` before
+records reach the router):
+
+- Host matches `prod_domain` → app mounts at `prod_route_prefix` (or
+  `route_prefix` when no override is set).
+- Host doesn't match, override set → still routable at `route_prefix`.
+- Host doesn't match, no override → filtered out (legacy domain-lock).
+
+So `route_prefix: "/demo"` + `prod_domain: "demo.example.com"` +
+`prod_route_prefix: "/"` serves the app at `/` on its own site while it
+stays at `/demo` everywhere else. `manifest.json` carries all four fields;
+`validate-app` requires the matching domain whenever an override prefix is
+declared. The unique index `idx_apps_route_prefix_domain` allows `/` per
+prod domain.
+
+Rules that are easy to get wrong:
+
+- **Exactly one app may own `/`.** Two root-mounted apps both compile to
+  `/*` and resolution order silently decides which renders — the registry
+  does not prevent this; don't create it.
+- **A root-mounted app shadows the global not-found page.** Its `/*` route
+  matches every path the more-specific routes don't, so the app must render
+  its own not-found for unknown internal paths (a catch-all
+  `<Route path="*">` inside its `index.tsx` routes).
+- **`system_admin` always lands on `/spine-framework/admin`.**
+  Root-mounting changes what *members* see at `/`, not admins. Non-admin
+  landing at `/`: root-mounted app if one exists → else redirect to the
+  first app's prefix → else `NoAppPage`.
+- **App-internal navigation must be mount-agnostic.** Use
+  `useAppPath()` from `@core/hooks/useAppPath` (or relative paths inside the
+  app's `<Routes>`) for every link and `navigate()` call — it returns the
+  prefix (`''` when mounted at `/`). A hardcoded `navigate('/dashboard')`
+  escapes a directory-mounted app. See [Frontend SDK](../reference/frontend-sdk.md).
+- **`nav_items[].path` accepts two forms** (`GenericAppShell` navigates
+  absolute paths verbatim and prefixes relative ones): absolute
+  *including* the prefix (`/taskboard/tasks`) or relative (`tasks` →
+  resolved to `/taskboard/tasks`). The broken form is absolute *without*
+  the prefix (`/tasks` escapes the app). For a root-mounted app the
+  absolute form is simply `/…`.
+- **`/spine-framework/*` is reserved** (admin, API docs, CLI pages mount
+  there ahead of app routes). Never pick a colliding prefix.
+- **Apps are always behind login.** `is_public`/`auth_required` exist on
+  the manifest, but the unauthenticated router only serves auth pages —
+  a root-mounted app is not a public site mechanism.
+
+Change the mount point via `manifest.route_prefix` + `update-db-app <slug>`
+(or the admin app detail page). On package reinstall the local
+`manifest.json` is preserved, so the file is the durable source.
+
+## Role gating
+
+Two layers decide who sees an app:
+
+- Server side, `get_account_apps` filters the app list by the caller's role
+  slugs (`.framework/functions/apps.ts`;
+  `.framework/migrations/013_get_account_apps_role_filter.sql`).
+- Client side, `AppWrapper` computes `required_roles` (falling back to
+  `[min_role]`) and renders an access-denied screen unless the user holds
+  `system_admin` or one of those roles (`.framework/src/components/AppWrapper.tsx`).
+
+This gates *opening the app*; it does not replace record-level
+`record_permissions` on the data underneath.
+
+## `renderer = 'generic'`
+
+The platform renders the app's list and detail pages for you, straight from
+each type's `design_schema.views`:
+
+- `App.tsx` mounts `GenericAppShell` for `renderer === 'generic'` apps.
+- `GenericAppShell` builds the sidebar from the app's `nav_items` and, for
+  every nav item carrying `type_slug` (and optional `view`), generates
+  list/detail/new routes backed by `GenericListPage` and
+  `GenericDetailPage`.
+- `GenericListPage` turns `views.default_list` (or the nav item's named view)
+  into sortable columns; `GenericDetailPage` renders `views.default_detail`
+  sections with per-field read/write awareness.
+
+**What you get for free:** a working list page, detail page, create/edit form,
+sorting, filters, field-type rendering, and permission-aware editing — with
+zero app code. **What it costs:** every type the app serves must have complete
+`fields`, `views.default_list`, and `views.default_detail`, or the pages fail
+with "No schema available" / schema-load errors. See
+[Design Schema](design-schema.md).
+
+## `renderer = 'custom'`
+
+The app ships its own React code under `custom/apps/<slug>/` (a
+project-owned directory, not part of the framework package). `App.tsx` mounts
+`CustomAppLoader`, which resolves the app through an
+`import.meta.glob('custom/apps/*/index.tsx')` — the app's `index.tsx` is its
+entry point and default-exports the routed component (the `create-app`
+scaffold generates exactly this shape).
+
+A custom app renders its own pages but still uses the platform for data:
+`/api/admin-data` for runtime CRUD, `/api/types` for schemas. Custom apps
+must never write their own CRUD wrappers — that bypasses permissions,
+validation, audit, and triggers (see [Runtime Records](runtime-records.md)).
+
+`renderer = 'none'` registers the app (data, types, integrations) with no UI
+surface.
+
+## The manifest
+
+`custom/apps/<slug>/manifest.json` is the app's declarative half, validated by
+`loadManifest` in `.framework/functions/_shared/app-manifest.ts` (the
+`AppManifest` interface is the contract):
+
+```json
+{
+  "name": "My App",
+  "slug": "my-app",
+  "description": "…",
+  "version": "1.0.0",
+  "required_roles": ["member"],
+  "route_prefix": "/my-app",
+  "renderer": "custom",
+  "routes": ["/my-app", "/my-app/dashboard"],
+  "nav_items": [{ "title": "Dashboard", "path": "/my-app/dashboard", "icon": "LayoutDashboard", "order": 1 }],
+  "features": [],
+  "dependencies": [],
+  "entry_point": "./index.tsx",
+  "is_public": false,
+  "auth_required": true
+}
+```
+
+Validated requirements: non-empty `name`, `slug` matching
+`^[a-z][a-z0-9-]*$` (and equal to the directory name for discovery), and
+`required_roles` as an array of strings. Optional keys the install flow also
+honors: `config` (merged onto the apps row), `seed` (declared seed entries),
+`owned_types`, `registration`, `metadata`, `min_role`,
+`preview_domain`/`prod_domain`.
+
+## Install and seed flow
+
+Two paths put an app on disk and in the registry:
+
+- **`npx spine-framework create-app <slug>`** — scaffolds
+  `custom/apps/<slug>/` (`manifest.json` + `index.tsx` + `components/`) and
+  inserts a `public.apps` row with `renderer: 'custom'` and
+  `route_prefix: /<slug>` (`.framework/cli/commands/create-app.ts`).
+- **`npx spine-framework install-app <package>`** — copies a packaged app into
+  `custom/apps/<slug>/`, runs migrations, then `seedApp`:
+  - upserts the `apps` row from the manifest (`appRowPayload`: name,
+    description, version, nav_items, route_prefix, renderer, required_roles,
+    min_role, config merge, metadata);
+  - applies seed files in dependency order — conventional
+    `seed/roles.json` → `roles` (conflict `slug`), `seed/types.json` →
+    `types` (conflict `kind,slug`, **no** `app_id` injection,
+    `ignoreDuplicates`) — plus any `manifest.seed` entries;
+  - refuses to overwrite a `types` row whose `design_schema` differs from the
+    seed unless the slug is declared in `manifest.owned_types` and
+    `--reconcile-owned-types` was passed (types are global — see
+    [Scope and Accounts](scope-and-accounts.md));
+  - syncs the `registration` block into `spine.config.json` (the project-owned
+    config file at the project root).
+- **`update-db-app <slug>`** re-syncs a local `manifest.json` to the DB without
+  touching files; **`seed-app <slug>`** re-runs seeds;
+  **`uninstall-app`** removes the app (`--keep-data` preserves seeded rows).
+  All in `.framework/cli/commands/install-app.ts`.
+
+## The practical split
+
+Use `generic` when the app is "records in, records out" — lists, detail forms,
+admin-style editing — and keep views accurate. Use `custom` when the UX is a
+product surface (dashboards, wizards, bespoke layouts) and treat the manifest
+as your app's contract: registration, roles, seeds, nav. Either way, types and
+`design_schema` do the data modeling — the renderer only decides who draws the
+pixels.