spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/tasks/add-an-integration.md

@@ -0,0 +1,124 @@
+---
+title: Add an integration
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integrations.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/_shared/resolve-credentials.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/migrations/004_core_rpc_and_broker.sql
+---
+
+# Add an integration
+
+## Goal
+
+Create a `public.integrations` row — the config + credentials handle for
+outbound HTTP calls (`integration-outbound`) and inbound webhook routing
+(`integration-routes`). See
+[Integrations and webhooks](../concepts/integrations-and-webhooks.md) for
+the full model.
+
+## Prerequisites
+
+- A `system_admin` login — the integrations function enforces it
+  (`.framework/functions/integrations.ts`, `isSystemAdmin` signal).
+
+## Steps
+
+1. **Choose the integration shape.**
+
+   - `integration_type`: semantic category — `webhook`, `oauth`, `api`,
+     `scheduled_sync` (column comment,
+     `.framework/migrations/004_core_rpc_and_broker.sql`).
+   - `provider`: the vendor name — `stripe`, `openai`, `generic`, …
+     (used as the fallback inbound adapter name).
+   - `slug`: unique per `(app_id, account_id)` —
+     `integrations_app_account_slug_key`
+     (`.framework/migrations/004_core_rpc_and_broker.sql`).
+
+2. **Configure `config` and `credentials`.**
+
+   - `config.outbound_adapter` selects the adapter module for outbound
+     calls — built-ins: `adapters/openai-outbound`,
+     `adapters/generic-webhook-outbound`, `adapters/resend-outbound`
+     (`.framework/functions/integration-outbound.ts`). `action_config.adapter`
+     can override it per call.
+   - `credentials` is a map `{ field: { source, value } }`:
+     `source: "value"` stores a literal secret; `source: "env_var"` resolves
+     `value` as a `process.env` name server-side at call time
+     (`.framework/functions/_shared/resolve-credentials.ts`).
+
+   ```json
+   {
+     "slug": "acme-api", "name": "Acme API",
+     "integration_type": "api", "provider": "acme",
+     "config": {
+       "base_url": "https://api.acme.test",
+       "outbound_adapter": "adapters/generic-webhook-outbound"
+     },
+     "credentials": {
+       "api_token": { "source": "env_var", "value": "ACME_API_TOKEN" }
+     }
+   }
+   ```
+
+   `is_configured` is recomputed on every save — `true` only when every
+   credential entry is present and non-empty
+   (`.framework/functions/integrations.ts`).
+
+3. **Create the integration.** Admin UI → **Configs → Integrations → New**,
+   or `POST /api/integrations` — `name`, `integration_type`, and `provider`
+   required (`.framework/functions/integrations.ts`).
+
+4. **Call it outbound.** `POST /api/integration-outbound` (or a pipeline
+   `http_request`/webhook stage) with `{ integration_slug, action_config }`.
+   `action_config` carries `endpoint`/`url`, `body`, `credential_field`
+   (default `api_token`), `action_slug`, `max_attempts`, and optional
+   `adapter` (`.framework/functions/integration-outbound.ts`).
+   Deliveries land in `webhook_deliveries` with retry bookkeeping — see
+   [integration-outbound reference](../reference/functions/integration-outbound.md).
+
+5. **For inbound**, point senders at `integration-routes` and pick an
+   adapter — see [Add a webhook](./add-a-webhook.md).
+
+## Verify
+
+- `GET /api/integrations?action=list` — `is_configured: true` once every
+  credential resolves.
+- A `webhook_deliveries` row is written per outbound call with
+  `response_status` and retry fields.
+
+## Common mistakes
+
+- **An empty or absent credential means "no auth", not an error.**
+  `execute` skips resolution for an absent entry or an empty
+  `source: "value"` literal and the call goes out without a credential —
+  the stock `generic-http` seed (`{"api_token":{"source":"value","value":""}}`,
+  `.framework/migrations/004_core_rpc_and_broker.sql`) therefore works
+  unauthenticated out of the box. Whether a credential is required is the
+  *adapter's* call: `generic-webhook-outbound` only attaches
+  `Authorization: Bearer` when a credential resolved, while
+  `openai-outbound`/`resend-outbound` throw in `buildRequest`. What still
+  fails hard: an `env_var` entry naming an unset variable
+  (`credential_env_missing`).
+- **Expecting credentials in reads.** Integrations are a protected
+  second-surface table — non-system-admin/machine reads are sanitized to
+  minimal fields; secrets are only resolved server-side
+  (`.framework/functions/_shared/permissions.ts`).
+- **`env_var` pointing at a missing env** — `resolveCredential` throws
+  before the request is sent and emits `integration.credential_*` audit
+  rows.
+- **Slug not unique within `(app_id, account_id)`** — the DB unique
+  constraint rejects it; account-scoped and global rows share the key.
+
+## Reference
+
+- [integrations entity page](../integrations.md) ·
+  [integrations function reference](../reference/functions/integrations.md) ·
+  [integration-outbound reference](../reference/functions/integration-outbound.md) ·
+  [integration-routes reference](../reference/functions/integration-routes.md)
+- [Integrations and webhooks](../concepts/integrations-and-webhooks.md)

package/.framework/src/instructions/tasks/build-a-custom-page.md

@@ -0,0 +1,118 @@
+---
+title: Build a custom page
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/components/AppWrapper.tsx
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - .framework/src/lib/api.ts
+  - .framework/cli/commands/create-app.ts
+  - scripts/assemble.sh
+---
+
+# Build a custom page
+
+## Goal
+
+Ship a React page inside a custom app (`renderer: 'custom'`) instead of the
+generic list/detail renderer. See
+[Apps and renderers](../concepts/apps-and-renderers.md) for the model.
+
+## When to go custom
+
+Stay on `renderer: 'generic'` when the app is CRUD over typed records — the
+generic renderer gives you list/detail/create/sort/permission-aware editing
+for free from `views.default_list` / `views.default_detail`. Go custom for
+dashboards, wizards, bespoke layouts, or anything not expressible as
+schema-driven list/detail — `GenericAppShell` only generates routes for
+nav items carrying `type_slug`
+(`.framework/src/components/app-shell/GenericAppShell.tsx`).
+
+## Steps
+
+1. **Scaffold the app** (or reuse one):
+
+   ```bash
+   npx spine-framework create-app <slug> --role <role-slug>
+   ```
+
+   Writes `custom/apps/<slug>/` with `manifest.json`, `index.tsx`, and
+   `components/`, and inserts the `apps` row with `renderer: 'custom'`
+   (`.framework/cli/commands/create-app.ts`). Pass `--role` a slug
+   that exists in `roles` — the default `member` is seeded by
+   `073_seed_member_roles.sql`.
+
+2. **Add pages under `custom/apps/<slug>/pages/`.** `CustomAppLoader`
+   lazy-imports only `custom/apps/<slug>/index.tsx`
+   (`import.meta.glob('../../../custom/apps/*/index.tsx')`,
+   `.framework/src/components/CustomAppLoader.tsx`) — `index.tsx`
+   default-exports the component (usually its own `<Routes>`) and imports
+   the page components itself.
+
+   ```tsx
+   // custom/apps/<slug>/pages/DashboardPage.tsx
+   export default function DashboardPage() { /* ... */ }
+   ```
+
+3. **Set the app row.** `renderer: 'custom'`, `route_prefix: '/<slug>'`,
+   `min_role` / `required_roles`, `nav_items` for the sidebar. `AppWrapper`
+   enforces auth + role before mounting your app
+   (`.framework/src/components/AppWrapper.tsx`).
+
+4. **Fetch data through `/api/admin-data`** — never write a bespoke CRUD
+   function:
+
+   ```ts
+   import { apiFetch } from '@core/lib/api'
+
+   const res = await apiFetch(
+     '/api/admin-data?action=list&entity=items&type_slug=ticket&limit=50')
+   const { data } = await res.json()
+   ```
+
+   `apiFetch` attaches the Supabase Bearer token and the `X-Account-Id`
+   header (`.framework/src/lib/api.ts`). Find-or-create related records
+   (e.g. a thread for a work item) through the same endpoint — see
+   [Build your first app — Step 4](../guide/04-first-app.md) for the full
+   call shapes.
+
+5. **Rebuild and run.** `npm run assemble` (or `npm run dev` / `dev:netlify`,
+   which run assembly automatically). Custom functions go in
+   `custom/functions/` prefixed `custom_` — assembly hard-fails on a
+   basename collision with a framework function
+   (`scripts/assemble-functions.sh`).
+
+## Verify
+
+- Navigate to `/<slug>` — `CustomAppLoader` resolves your `index.tsx`
+  (a missing entry shows the `App "<slug>" not found` error naming the
+  expected path).
+- `GET /api/apps?action=get&slug=<slug>` shows `renderer: 'custom'` and the
+  right `route_prefix`.
+- `npm run typecheck` compiles the page.
+
+## Common mistakes
+
+- **A bespoke CRUD endpoint.** Custom Netlify functions that
+  create/update/list runtime records bypass `admin-data`'s permission,
+  type-resolution, audit, and trigger logic — call `/api/admin-data` from
+  the client instead (see [Write a function](./write-a-function.md) for the
+  cases where a custom function *is* allowed).
+- **Forgetting `index.tsx` is the only entry.** New pages in `pages/` are
+  invisible until `index.tsx` routes to them.
+- **`type_slug` nav items on a custom app** — they only do something under
+  the generic renderer; use plain `path` nav items and route them yourself.
+- **Editing before re-assembling** — `CustomAppLoader`'s glob is evaluated
+  at build time; new files need an assemble/dev restart.
+
+## Reference
+
+- [Apps and renderers](../concepts/apps-and-renderers.md) ·
+  [Runtime records](../concepts/runtime-records.md)
+- [App manifest reference](../reference/app-manifest.md) ·
+  [admin-data function reference](../reference/functions/admin-data.md)
+- [Build your first app](../guide/04-first-app.md) ·
+  [Anatomy of an installed project](../guide/02-project-map.md)

package/.framework/src/instructions/tasks/document-your-app.md

@@ -0,0 +1,117 @@
+---
+title: Document your app
+audience: developers, agents
+kind: task
+verified_against: b3b3ae0
+verified_on: 2026-11-01
+source_files:
+  - .framework/cli/commands/install-app.ts
+  - .framework/cli/commands/validate-app.ts
+  - .framework/src/instructions/internal/docs-contract.md
+  - .framework/templates/agent/AGENTS.md
+---
+
+# Document your app
+
+## Goal
+
+Give your app the same agent-legible documentation the framework ships —
+so a cold agent (or a future teammate) can install it, understand it, and
+work in it without reading every file. The contract: a small instruction
+book inside the app plus namespaced Devin skills, kept in sync by the same
+capture rule as the core book.
+
+## Steps
+
+1. **Create the app's instruction book** at
+   `custom/apps/<slug>/src/instructions/` — "book-lite": the same layer
+   structure, shrunk to app scale:
+
+   ```
+   src/instructions/
+   ├── README.md              # what the app is + the doc map (kind: index)
+   ├── entities/              # one page per seeded type (or per type family)
+   │   └── ticketing.md
+   ├── tasks/                 # the jobs someone does in/with this app
+   │   └── install.md
+   └── reference/
+       └── functions.md       # the app's custom_* functions
+   ```
+
+   Every page carries the same frontmatter as the core book — `title`,
+   `audience`, `kind`, `verified_against`, `verified_on`, and
+   `source_files` pointing at **the app's own** functions/seeds/pages. That
+   frontmatter is what makes your docs drift-checkable later.
+
+2. **Author skills where they live.** App skills go in
+   `custom/.devin/skills/<prefix>_<kebab-name>/SKILL.md` — the discovered,
+   invocable location. Directory name = SKILL.md `name:` field = the skill's
+   identity. The `<prefix>_` namespace keeps your skills separate from
+   framework `spine-*` skills and makes uninstall deterministic.
+
+3. **Declare the prefix in `manifest.json`:**
+
+   ```json
+   "agent": { "skill_prefix": "ao" }
+   ```
+
+   `^[a-z][a-z0-9]{0,7}$`, unique across installed apps (the installer
+   checks). Convention: initials of the slug — `answer-once` → `ao`,
+   `demo` → `d`.
+
+4. **Stage assets for packaging** under `agent/` in the app directory —
+   the installer maps them to their destinations:
+
+   | Package path | Installed to |
+   |---|---|
+   | `agent/skills/<prefix>_*/` | `custom/.devin/skills/<prefix>_*/` |
+   | `agent/instructions/**` | `custom/apps/<slug>/src/instructions/` |
+
+   The package's `files` array in `package.json` must list `agent/`
+   (npm only packs declared entries) — plus everything else the installer
+   copies (`seed/`, `standalone.config.json`, `docs/`, …).
+
+   For in-project development you edit the live copies directly
+   (`custom/.devin/skills/`, `custom/apps/<slug>/src/instructions/`); copy
+   them into `agent/` when packaging. `validate-app` warns if the staged
+   and live copies drift.
+
+5. **Validate** with `npx spine-framework validate-app <dir>` — checks the
+   `agent` block, prefix rules, and SKILL.md name/dir equality.
+
+## Verify
+
+- `custom/.devin/skills/<prefix>_*/SKILL.md` files are invocable in a fresh
+  agent session.
+- `custom/apps/<slug>/src/instructions/README.md` exists and links the
+  rest.
+- A fresh agent session asked "work in this app" finds the book via the
+  AGENTS.md pointer line without being told the path.
+
+## Common mistakes
+
+- **Skills inside the app dir** — `custom/apps/<slug>/.devin/` is *not*
+  discovered by agent tooling; `custom/.devin/skills/` is. Authored in the
+  app dir they become docs, not skills.
+- **Missing `agent.skill_prefix`** — the installer fails closed when
+  `agent/skills/` exists without it; declare it even with one skill.
+- **Prefix collisions** — two installed apps sharing a prefix fails at
+  install. Keep prefixes short and slug-derived.
+- **`agent/` missing from `files`** — the tarball silently drops your
+  staged assets and the installer has nothing to sync. List `agent/` (and
+  `seed/`, `standalone.config.json`, …) in `package.json`'s `files`.
+- **`src/` for code** — `src/` inside an app is *instructions-only*; the
+  loader only globs `custom/apps/*/index.tsx`. App code stays in
+  `pages/`, `components/`, `hooks/`, `utils/`, `lib/`.
+- **Docs written once and abandoned** — the capture contract applies to
+  your app too: every change to the app updates its `src/instructions/`
+  in the same commit.
+
+## Reference
+
+- [Docs contract](../internal/docs-contract.md) — the doctrine and the
+  capture rule this recipe implements
+- [App manifest reference](../reference/app-manifest.md) — the `agent`
+  block
+- [Package and install an app](package-and-install-an-app.md) — the
+  install/update/uninstall mechanics

package/.framework/src/instructions/tasks/package-and-install-an-app.md

@@ -0,0 +1,136 @@
+---
+title: Package and install an app
+audience: developers, agents
+kind: task
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/cli/commands/install-app.ts
+  - .framework/cli/commands/validate-app.ts
+  - .framework/functions/_shared/app-manifest.ts
+  - .framework/cli/commands/migrate.ts
+---
+
+# Package and install an app
+
+## Goal
+
+Package a `custom/apps/<slug>/` directory as an npm package and install it
+into a Spine project — files copied, `apps` row upserted, migrations run,
+seeds applied. Field-level manifest semantics are in
+[App manifest reference](../reference/app-manifest.md) and
+[Seeds reference](../reference/seeds.md).
+
+## Steps
+
+1. **Author `manifest.json`.** Required fields the installer validates:
+   `slug` (must equal the directory name and match
+   `^[a-z][a-z0-9-]*$`), plus `name`, `route_prefix`, `renderer`,
+   `min_role` / `required_roles`, `nav_items`, `config`, `registration`.
+   See [App manifest reference](../reference/app-manifest.md) for every
+   field.
+
+2. **Author seed files.** The `seed` block is a list of
+   `{ file, table, conflict, inject_app_id?, ignore_duplicates?, permissions_patch? }`
+   entries, each pointing at a JSON file of rows
+   (`.framework/cli/commands/install-app.ts`):
+
+   - `conflict` — the `onConflict` column list for the upsert. Types use
+     `conflict: "kind,slug"` with `inject_app_id: false` — types are
+     **global**, not duplicated per install.
+   - `inject_app_id` — stamps `app_id` on each seeded row (default `true`);
+     set `false` for global tables like `types`.
+   - `ignore_duplicates` — `ignoreDuplicates` on the upsert; `types` rows
+     always get it (`.framework/cli/commands/install-app.ts`).
+   - `permissions_patch` — a types-table entry that merges
+     `record_permissions` into existing design schemas instead of
+     overwriting; ranks just after `types` in apply order.
+   - If no `seed` array is declared, the conventional files
+     `seed/roles.json`, `seed/types.json`, `seed/link-types.json` are used
+     (`.framework/cli/commands/install-app.ts`).
+
+   Seeds apply in dependency order — `roles`, `types`, `link_types`,
+   `actions`, `ai_agents`, `prompt_configs`, `pipelines`, `triggers` —
+   regardless of declaration order
+   (`.framework/cli/commands/install-app.ts`). Pipeline seeds are
+   validated against `public.actions` stage slugs, and trigger seeds
+   resolve `pipeline_slug` → `pipeline_id`.
+
+3. **Package it.** Ship the app directory as an npm package — declare
+   every shippable entry in `package.json`'s `files` array (npm packs
+   nothing else). Include `index.tsx`, `manifest.json`, and optionally `pages/`,
+   `components/`, `hooks/`, `utils/`, `functions/`, `seed/`, `public/` —
+   the installer copies a fixed allowlist (`APP_COPY_ENTRIES` in
+   `.framework/cli/commands/install-app.ts`: those dirs plus `lib/`,
+   `views/`, `docs/`, `api/`, `installer/`, `mcp/`, `migrations*`,
+   `tests/`, `standalone.config.json`, `agent/`). `agent/` is staged —
+   `agent/skills/` lands at `custom/.devin/skills/` (requires
+   `manifest.agent.skill_prefix`) and `agent/instructions/` lands at
+   `custom/apps/<slug>/src/instructions/`; see
+   [App manifest reference](../reference/app-manifest.md). Validate locally
+   with `npx spine-framework validate-app`.
+
+4. **Install.**
+
+   ```bash
+   npx spine-framework install-app <package>
+   ```
+
+   Flow: `npm install <package>` → resolve slug → copy files to
+   `custom/apps/<slug>/` (a reinstall preserves the local `manifest.json`)
+   → `runMigrations` → `seedApp` → sync the `registration` block into
+   `apps.config` and `spine.config.json`
+   (`.framework/cli/commands/install-app.ts`). Requires
+   `SUPABASE_URL` + `SUPABASE_DB_PASSWORD` + `SUPABASE_SERVICE_ROLE_KEY`;
+   `--no-seed` skips all DB work.
+
+5. **Update paths.**
+
+   - `update-app <package>` — `npm install @latest` + copy files + sync
+     registration. **It does not re-run migrations or seeds.**
+   - `update-db-app <slug>` — upserts the `apps` row from the local
+     `manifest.json` and syncs registration; no npm, no file changes.
+   - `seed-app <slug>` — re-runs just the seed block for a local app;
+     `--reconcile-owned-types` interactively updates `manifest.owned_types`
+     slugs whose DB `design_schema` drifted from the seed.
+
+6. **Uninstall.** `uninstall-app <package>` removes
+   `custom/apps/<slug>/`, removes the app's skills
+   (`custom/.devin/skills/<prefix>_*` when `manifest.agent.skill_prefix`
+   is declared), and runs `npm uninstall` — and nothing else. The
+   `--keep-data` flag is parsed but never read: seeded rows are **not**
+   deleted either way (`.framework/cli/commands/install-app.ts`).
+
+## Verify
+
+- `npx spine-framework status` lists the installed app and version.
+- `GET /api/apps?action=get&slug=<slug>` shows the upserted row;
+  `migrations status` shows migration state.
+- Seeded rows exist: `GET /api/types?action=list` (or the seeded table's
+  endpoint) includes the app's types/roles.
+
+## Common mistakes
+
+- **Types not global.** Forgetting `inject_app_id: false` on a types seed
+  injects `app_id` into global type rows — and `conflict: "kind,slug"`
+  means a second app with the same slug silently skips or errors on
+  schema drift. Prefix slugs.
+- **Expecting `uninstall --keep-data` to matter** — it is a no-op; seeded
+  rows always survive uninstall.
+- **`update-app` doesn't re-seed** — new seed rows in the package never
+  reach the DB; run `seed-app <slug>` or `update-db-app` after.
+- **Seed rows referencing unseeded slugs** — `owned_types`,
+  `pipeline_slug`, and `send_notification` recipients are validated
+  fail-closed before any DB writes; fix the manifest, don't retry.
+- **`SUPABASE_URL` must be a hosted `https://<ref>.supabase.co` URL** —
+  the migrator rejects anything else before connecting
+  (`.framework/cli/commands/migrate.ts`).
+
+## Reference
+
+- [App manifest reference](../reference/app-manifest.md) ·
+  [Seeds reference](../reference/seeds.md) ·
+  [CLI reference](../reference/cli.md) ·
+  [spine.config.json reference](../reference/spine-config.md)
+- [Apps and renderers](../concepts/apps-and-renderers.md) ·
+  [Write a migration](./write-a-migration.md)

package/.framework/src/instructions/tasks/register-an-app.md

@@ -0,0 +1,137 @@
+---
+title: Register an app
+audience: developers, agents
+kind: task
+verified_against: b3b3ae0
+verified_on: 2026-11-01
+source_files:
+  - .framework/cli/commands/create-app.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/functions/apps.ts
+  - .framework/functions/_shared/app-manifest.ts
+  - .framework/src/App.tsx
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+---
+
+# Register an app
+
+## Goal
+
+Put an app in the `public.apps` registry so it appears in navigation, mounts
+at a route, and renders — either by the generic renderer (schema-driven) or
+by your own code (`custom/apps/<slug>/`).
+
+Two decisions up front:
+
+1. **Renderer** — `generic` (platform draws list/detail pages from each
+   type's `design_schema.views`) or `custom` (your `index.tsx` draws
+   everything). `none` registers data/types with no UI.
+2. **Mount point (`route_prefix`)** — where the app lives in the URL space:
+   `/my-app` (default), `/` (site root), or a nested prefix. See
+   [Mounting](../concepts/apps-and-renderers.md#mounting-directory-or-root)
+   for the full rules — the short version:
+
+   | Mount | Effect |
+   |---|---|
+   | `/my-app` (default) | App owns `/my-app/*`. Safe default. |
+   | `/` | App owns `/*`; renders at `/` for non-admins. **One app only** — must render its own not-found for unknown paths. |
+   | `/crm/sales` | Nested; longest-prefix-first. Works, rarely needed. |
+
+## Steps
+
+### Option A — scaffold a custom app
+
+```bash
+npx spine-framework create-app <slug>
+```
+
+Creates `custom/apps/<slug>/` (`manifest.json` + `index.tsx` +
+`components/`) and inserts the `apps` row with `renderer: 'custom'` and
+`route_prefix: /<slug>` (`.framework/cli/commands/create-app.ts`).
+
+Then edit `custom/apps/<slug>/manifest.json` — set `route_prefix`,
+`required_roles`, `nav_items`, and `routes`. Sync to the DB:
+
+```bash
+npx spine-framework update-db-app <slug>
+```
+
+### Option B — register a generic app
+
+Generic apps are registry rows plus nav items — no app directory is needed
+(the shell renders from type schemas):
+
+1. Ensure every type the app will serve has complete `design_schema` —
+   `fields`, `views.default_list`, `views.default_detail` (see
+   [Design schema](../concepts/design-schema.md)).
+2. Create the `apps` row — via the admin UI (Admin → Apps → New) or the API:
+
+   ```ts
+   await apiFetch('/api/apps?action=create', {
+     method: 'POST',
+     body: JSON.stringify({
+       slug: 'taskboard', name: 'Taskboard',
+       renderer: 'generic',
+       route_prefix: '/taskboard',
+       min_role: 'member',
+       is_active: true,
+       nav_items: [
+         { title: 'Tasks', path: '/taskboard/tasks', type_slug: 'task', order: 1 }
+       ]
+     })
+   })
+   ```
+
+   `nav_items` entries carrying `type_slug` (and optional `view`) get
+   generated list/detail/new routes. Omit `view` to use `default_list` +
+   `default_detail` — a nav item cannot pick list and detail views
+   independently ([manifest reference](../reference/app-manifest.md)).
+3. Log out/in (or refresh) so the registry reloads.
+
+### Option C — install a packaged app
+
+```bash
+npx spine-framework install-app <package>
+```
+
+The package's `manifest.json` declares `route_prefix` and everything else —
+see [Package and install an app](package-and-install-an-app.md).
+
+## Verify
+
+- `GET /api/apps?action=get&slug=<slug>` returns the row with your
+  `route_prefix`, `renderer`, `nav_items`.
+- Navigating to `<route_prefix>` renders the app (generic: list page;
+  custom: your `index.tsx`). For `/`, members land on it directly;
+  `system_admin` still lands on `/spine-framework/admin`.
+- `useAppPath`-built links inside the app resolve correctly at the chosen
+  mount point.
+
+## Common mistakes
+
+- **Two apps mounted at `/`** — both compile to `/*`; ordering silently
+  decides which renders. The registry won't stop you; don't do it.
+- **Root app with no internal not-found** — a `/`-mounted `/*` shadows the
+  global `*` route; unmatched paths inside the app show blank/error instead
+  of your 404. Add `<Route path="*" element={...}>` in the app's routes.
+- **Hardcoded paths** — `navigate('/tasks')` or `to="/tasks"` escapes a
+  directory-mounted app. Use `useAppPath()` from `@core/hooks/useAppPath`
+  or relative routes.
+- **`nav_items` absolute paths missing the prefix** — `/tasks` navigates
+  outside the app and 404s. Use either `/taskboard/tasks` (absolute
+  incl. prefix) or `tasks` (relative — the shell prefixes it).
+- **Expecting public access** — `is_public`/`auth_required` exist on the
+  manifest but are not wired into the unauthenticated router; every app is
+  behind login.
+- **Generic app, thin schema** — `renderer: 'generic'` with types lacking
+  `views.default_list`/`default_detail` renders "No schema available."
+
+## Reference
+
+- [Apps and renderers](../concepts/apps-and-renderers.md) — mounting model,
+  role gating, renderer semantics
+- [Apps](../apps.md) — the registry entity page
+- [App manifest reference](../reference/app-manifest.md) — every manifest
+  field incl. `route_prefix`, `nav_items`, `registration`
+- [Build a custom page](build-a-custom-page.md) ·
+  [Frontend SDK](../reference/frontend-sdk.md) — `useAppPath`, `apiFetch`