spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/templates/agent/AGENTS.md

@@ -0,0 +1,150 @@
+<!-- spine-framework:begin version={{SPINE_VERSION}} -->
+<!--
+  Framework-owned block. `spine-framework upgrade` replaces everything between
+  the begin/end markers above and below. Keep your own notes outside the markers.
+-->
+
+# Spine Framework — agent rules
+
+You are working in a Spine Framework project. Spine is a multi-tenant, modular
+application platform: framework primitives live under `.framework/` (shipped by
+the `spine-framework` npm package), and everything the project owns lives
+outside it (`custom/`, app packages, project config).
+
+## Core vs. custom boundary
+
+- **Never edit `.framework/`.** It is sealed and overwritten verbatim by
+  `spine-framework upgrade`. Local edits there break the integrity check and
+  are lost on upgrade.
+- Project code lives in `custom/` (`custom/apps/<slug>/`, `custom/functions/`,
+  `custom/migrations/`, `custom/tests/`).
+- Framework code never imports from `custom/`. From custom apps, import core
+  through the `@core/*` alias; from custom functions (post-assembly), import
+  `./_shared/*`.
+- If a change could serve more than one app it may be a framework concern —
+  flag it to the maintainer instead of patching `.framework/` locally.
+
+## Runtime record CRUD — admin-data only
+
+Use the generic `/api/admin-data` endpoint for all runtime record CRUD
+(`items`, `threads`, `messages`, `links`, `attachments`, `watchers`, etc.).
+Do **not** write custom Netlify function wrappers for creating, updating,
+listing, or deleting runtime records — wrappers bypass shared permission,
+type-resolution, audit, and trigger logic. Find-or-create flows call
+`/api/admin-data` directly from the client or a hook. See
+`.framework/src/instructions/reference/api/admin-data.md`.
+
+- **Access:** runtime APIs authenticate with `x-api-key: $SPINE_API_KEY`;
+  ask the user to create a scoped key in Admin → Configs → API Keys if unset.
+
+## design_schema authoring checklist
+
+Every new or changed type needs a valid `design_schema` on its `public.types`
+row; `validation_schema` is generated from it. Spine stamps
+`type.design_schema` into each runtime record at creation, so a missing or
+stale schema breaks permissions, validation, and UI rendering.
+
+**Absolute minimum `design_schema`:**
+
+```json
+{
+  "scope": "account",
+  "fields": {
+    "title": { "data_type": "text", "label": "Title", "required": true, "system": true }
+  },
+  "views": {
+    "default_list": {
+      "type": "list",
+      "display": "table",
+      "label": "List",
+      "fields": {
+        "title": { "sortable": true, "display_type": "text" },
+        "created_at": { "sortable": true, "display_type": "timestamp" }
+      },
+      "default_sort": { "field": "created_at", "direction": "desc" }
+    },
+    "default_detail": {
+      "type": "detail",
+      "label": "Detail",
+      "sections": [
+        { "title": "Details", "fields": { "title": { "display_type": "input" } } }
+      ]
+    }
+  },
+  "record_permissions": {
+    "system-admin": ["create", "read", "update", "delete"]
+  },
+  "functionality": null
+}
+```
+
+- `scope`: `"account"` (default) or `"platform"`. Omitted defaults to account.
+- `fields`: required. Every field needs `data_type`, `label`, `required`.
+- `views`: required for generic apps (`apps.renderer = "generic"`) — at least
+  `default_list` and `default_detail`, referencing real fields with known
+  `display_type` values. Custom apps may omit views if they render everything
+  themselves, but keeping them preserves the generic admin/runtime fallback.
+- `record_permissions`: required. The **base, most restrictive** grant per
+  role; at minimum grant `system-admin`.
+- `functionality`: `null` until automation bindings are confirmed active.
+
+**Permission design rule:** `record_permissions` is the base grant — if a role
+can `read`/`update` a record, every field defaults to read/write.
+`fields.*.permissions` is for **overrides only**: loosen a specific field
+beyond the record grant, or restrict a `system: true` field. Field-level
+actions are `read` and `write` only; `create`/`delete` are record-level.
+
+**Known `data_type` values:** `text`, `textarea`, `rich_text`, `email`,
+`phone`, `url`, `number`, `currency`, `range`, `date`, `datetime`, `boolean`/
+`checkbox`, `select`, `multiselect`, `radio`, `color`, `file`, `image`,
+`json`, `reference`, `address`. `select`/`multiselect`/`radio` require
+`options`; `reference` should set `validation.reference_kind` and
+`validation.reference_type`.
+
+**Known `display_type` values:** `text`, `input`, `textarea`, `rich_text`,
+`select`, `multiselect`, `radio`, `checkbox`/`switch`, `date_picker`,
+`datetime_picker`, `color_picker`, `file_upload`, `image_upload`,
+`range_slider`, `badge`, `timestamp`, `currency`, `number`.
+
+**Before finishing a type change:**
+
+- `slug` is unique per `kind` — duplicates break `resolveTypeId`/`.single()`
+  lookups. Type seeds use `conflict: "kind,slug"` with `inject_app_id: false`.
+- `kind` matches the runtime table (`item`, `thread`, `message`, `link`,
+  `attachment`, `watcher`, `person`, `account`).
+- `system: true` fields live at `record.<field>`; non-system fields at
+  `record.data.<field>`. `system: true` fields restrict `write` to
+  `system-admin` when the record-level grant would allow writes.
+- `ownership`, `is_active`, `icon`, `color` are set on the `types` row.
+- Validate the JSON before saving: `npx spine-framework validate-schema <file>`.
+
+## Where to look — the instruction book
+
+The package ships a markdown instruction book at
+`.framework/src/instructions/`:
+
+- `README.md` — structure, reading order, entity doc template.
+- `guide/` — walkthroughs (`00-orientation.md` → `05-glossary.md`;
+  `03-domain-model.md` covers types/records/apps).
+- `concepts/` — `spine-way.md` (the rules), `core-vs-custom.md`,
+  `design-schema.md`, `permissions.md`, `runtime-records.md`.
+- `reference/` — `design-schema.md`, `cli.md`, `api/admin-data.md`,
+  `env-vars.md`, `app-manifest.md`, `functions/`.
+- `tasks/` — single-goal procedures. `operations/` — admin-UI runbooks.
+- Entity pages: `types.md`, `apps.md`, `roles.md`, `pipelines.md`,
+  `triggers.md`, `timers.md`, `ai-agents.md`, `prompts.md`,
+  `integrations.md`, `api-keys.md`, `deliveries.md`.
+
+Project-level skills for common jobs live in `.devin/skills/spine-*/`.
+
+## Verify before finishing
+
+- `npm run typecheck` — compile the frontend + assembled sources.
+- `npm run test` — vitest unit/API suite.
+- `npm run verify` — integrity check against `.spine-manifest.json`.
+- `npx spine-framework validate-schema <file>` — check a `design_schema` JSON.
+- `npx spine-framework validate-app <dir>` — check an app package.
+- `npx spine-framework doctor` — health + wiring checks.
+<!-- spine-framework:end -->
+
+<!-- Your project rules below this line are never overwritten by spine-framework upgrade -->

package/.framework/templates/agent/skills/spine-add-ai-agent/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: spine-add-ai-agent
+description: "Configure a Spine AI agent — model, tools, guardrails — plus the prompt configs it invokes at runtime."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You configure Spine AI agents and their prompt configs.
+
+## When to invoke
+
+- A pipeline, trigger, or chat surface needs an LLM step.
+- An existing agent needs a new prompt config, tools, or model settings.
+
+## Model
+
+- **AI agent** — reusable model + prompt + tool configuration with guardrails;
+  invoked by pipelines, triggers, and chat interfaces.
+- **Prompt config** — the prompt body, model settings, escalation rules,
+  knowledge sources, available tools, and metadata, selected by slug.
+
+Read the entity docs first: `.framework/src/instructions/ai-agents.md` and
+`.framework/src/instructions/prompts.md`, plus the mental model in
+`.framework/src/instructions/concepts/ai-and-prompts.md`. Procedures live under
+`.framework/src/instructions/tasks/`; observability under
+`.framework/src/instructions/concepts/observability.md` and
+`.framework/src/instructions/operations/`.
+
+## Steps
+
+1. **Design the prompt config.** Write the prompt body and set model,
+   temperature, escalation rules, and which knowledge sources and tools the
+   config exposes. Give it a stable slug — callers select configs by slug.
+2. **Create the agent record** via `/api/admin-data` or app seed. Attach the
+   prompt config slug, the model, the tool allowlist, and guardrails
+   (max tokens, escalation, refusal behavior).
+3. **Wire invocation.** Agents run from pipeline stages (`stage_type` =
+   agent/action slug) or chat surfaces — wire the pipeline with the
+   `spine-add-automation` skill.
+4. **Credentials stay server-side.** Agent API keys live in integrations /
+   env — never in prompt text, frontend code, or committed files. See
+   `.framework/src/instructions/api-keys.md`.
+5. **Verify:** invoke the agent once end-to-end; inspect the interaction log
+   via the observability pages in `.framework/src/instructions/operations/`.
+
+## Rules
+
+- Prompt configs are data, not code — keep them in the DB/seed, not in files.
+- Escalation rules must name a reachable target (role/person) — dead-end
+  escalation silently drops conversations.
+- Guardrail settings belong on the agent record, not inline in prompt text.
+- Verification: one real invocation + doctor `runtime_wiring` pass for the
+  owning pipeline.

package/.framework/templates/agent/skills/spine-add-automation/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: spine-add-automation
+description: "Add Spine automation — a pipeline with stages, wired to a trigger (event), timer (schedule), or webhook."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You add automation to a Spine project: pipelines (the workflow), triggers
+(the event listener), and timers (the schedule).
+
+## When to invoke
+
+- React to a platform event (`item.created`, `message.sent`, ...).
+- Run a job on an interval, cron schedule, or one-off.
+- Wire an existing pipeline to a new event source.
+
+## Model
+
+- **Pipeline** — multi-step workflow; `stages` is a JSON array the runner
+  executes in order. Each stage's `stage_type` names an `actions` slug.
+- **Trigger** — listens for an event and hands the payload to a pipeline.
+  Config references `type_slug`, `pipeline_slug`/`pipeline_id`, and optionally
+  a `kind`/`entity` scope.
+- **Timer** — invokes a pipeline on `interval`, `cron`, or `once`.
+
+Read the entity docs first: `.framework/src/instructions/pipelines.md`,
+`.framework/src/instructions/triggers.md`, and
+`.framework/src/instructions/timers.md`. The automation model is
+`.framework/src/instructions/concepts/automation.md`; procedures live under
+`.framework/src/instructions/tasks/`.
+
+## Steps
+
+1. **Design the stages.** Each stage = `{ stage_type, config }` where
+   `stage_type` is an existing, active `actions` slug. Check the actions
+   registry before inventing one — a stage referencing a missing action fails
+   the `runtime_wiring` doctor check.
+2. **Create the pipeline row** via `/api/admin-data` or app seed
+   (`seed/pipelines.json`). Keep `is_active` false until stages are verified.
+3. **Wire the source:**
+   - Event → `triggers` row (`event_type`, `pipeline_slug` or `pipeline_id`,
+     `config.filters.type_slug` to scope to a type).
+   - Schedule → `timers` row (`pipeline_id`, interval/cron/once config).
+   - Webhook → the `spine-add-integration` skill.
+4. **Verify wiring:** `npx spine-framework doctor` — the `runtime_wiring`
+   check reports dangling `type_slug`, `pipeline_slug`/`pipeline_id`, and
+   `stage_type` references, plus active pipelines with no stages.
+5. **Watch the run:** deliveries and executions are observable — see the
+   `spine-troubleshoot` skill and `.framework/src/instructions/deliveries.md`.
+
+## Rules
+
+- An active pipeline with no stages completes successfully while doing
+  nothing — always verify `stages` is non-empty.
+- Trigger `config` names entities by table name (`items`); types by slug.
+- Prefer `pipeline_slug` in config so the binding survives ID regeneration.
+- Verification: doctor `runtime_wiring` pass + one real event run observed.

package/.framework/templates/agent/skills/spine-add-integration/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: spine-add-integration
+description: "Connect Spine to an external service — integration record, credentials, and inbound webhook wiring to a pipeline."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You connect a Spine project to external services: outbound integrations
+(OpenAI, SendGrid, generic HTTP) and inbound webhooks.
+
+## When to invoke
+
+- A pipeline stage or app needs to call an external service.
+- An external service needs to push events into Spine (webhook).
+- Credentials for an existing integration need to rotate or move scope.
+
+## Model
+
+- **Integration** — a record naming the adapter (`openai`, `sendgrid`,
+  `http`, ...), runtime config, and credentials; callers invoke it by slug.
+- **Deliveries** — the outbound delivery log: every attempt, status, retries,
+  and response; the primary debugging surface.
+
+Read `.framework/src/instructions/integrations.md`,
+`.framework/src/instructions/deliveries.md`,
+`.framework/src/instructions/api-keys.md`, and the model in
+`.framework/src/instructions/concepts/integrations-and-webhooks.md` before
+configuring anything. Route-level details live under
+`.framework/src/instructions/reference/functions/integration-routes.md` and
+`.framework/src/instructions/reference/functions/integration-outbound.md`.
+
+## Steps
+
+1. **Choose the adapter.** Check the integrations entity doc for supported
+   adapters and their config keys — a generic `http` adapter covers services
+   without a named one.
+2. **Create the integration record** via `/api/admin-data` or app seed. Store
+   credentials on the record's credential fields — service keys never appear
+   in frontend code, prompt text, or committed env files.
+3. **Outbound calls:** pipelines and functions resolve the integration by
+   slug and send; attempts land in `deliveries` with status and response.
+4. **Inbound webhooks:** expose the endpoint, verify signatures/secrets, then
+   hand the normalized payload to a pipeline — wire it with the
+   `spine-add-automation` skill.
+5. **Verify:**
+   - Outbound — trigger one call and confirm a `deliveries` row shows
+     `status` success; inspect response body on failure.
+   - Inbound — send a test webhook, confirm the pipeline ran and the event
+     was recorded.
+   - `npx spine-framework doctor` — `runtime_wiring` must stay clean.
+
+## Rules
+
+- Never hardcode credentials in code, seeds, or `VITE_*` vars — backend only.
+- One integration record per service+scope; callers always reference by slug.
+- Retries are the platform's job — do not loop or re-send in app code.
+- Verification: one real delivery observed in `deliveries` + webhook round
+  trip for inbound flows.

package/.framework/templates/agent/skills/spine-architect/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: spine-architect
+description: "Orient on the Spine Way before building or changing anything in a Spine project; evaluate proposals and advise core-vs-custom placement."
+allowed-tools:
+  - read
+  - find_file_by_name
+  - grep
+---
+
+You are the Spine Framework Architect. Help a developer understand the Spine Way and choose the correct primitives and patterns before writing code.
+
+## When to invoke
+
+- At the start of any Spine-related task.
+- When unsure whether a change belongs in `.framework/` or `custom/`.
+- When you need to know which primitive, type, function, or guide applies.
+- Before creating a new app, type, function, component, migration, pipeline, or AI agent.
+- When asked to evaluate a proposal against the Spine Way.
+
+## Orientation workflow
+
+1. **Read the orientation docs**
+   - `.framework/src/instructions/README.md` — book structure and reading order.
+   - `.framework/src/instructions/guide/03-domain-model.md` — types, records, apps, how the pieces fit.
+   - `.framework/src/instructions/concepts/spine-way.md` — the fundamental rules.
+   - `.framework/src/instructions/concepts/core-vs-custom.md` — the ownership boundary.
+   - The boundary rules also live in the project `AGENTS.md` framework block.
+
+2. **Identify the task family**
+   Ask clarifying questions until one of these applies:
+   - new custom app → see `spine-new-app` skill
+   - new type / design schema → see `spine-new-type` and `spine-schema` skills
+   - new function → see `spine-new-function` skill
+   - new migration → see `spine-migration` skill
+   - new pipeline / trigger / timer → see `spine-add-automation` skill
+   - new AI agent / prompt config → see `spine-add-ai-agent` skill
+   - new integration / webhook → see `spine-add-integration` skill
+   - install an app package → see `spine-install-app` skill
+   - change to existing code → map the blast radius first
+
+3. **Read the relevant pages**
+   - Entity docs: `.framework/src/instructions/types.md`, `apps.md`, `roles.md`, `pipelines.md`, `triggers.md`, `timers.md`, `ai-agents.md`, `prompts.md`, `integrations.md`.
+   - Procedures: `.framework/src/instructions/tasks/`; exact spellings: `.framework/src/instructions/reference/` (notably `design-schema.md`, `cli.md`, `api/admin-data.md`).
+   - Concept pages for the domain at hand under `.framework/src/instructions/concepts/`.
+
+4. **Apply the Spine Way checklist**
+   - Core vs. custom boundary (never edit `.framework/` — it is upgrade-overwritten).
+   - `@core/*` aliases from custom apps; `./_shared/*` inside functions post-assembly.
+   - Apps register through `public.apps` + `manifest.json`, installed via `install-app`.
+   - Runtime record CRUD goes through `/api/admin-data` — never custom wrappers.
+   - Behavior is declared in `design_schema`; `validation_schema` is generated.
+   - `record_permissions` is the base grant; field permissions are overrides only.
+   - Migrations are idempotent, ordered, and additive.
+   - `system: true` fields live at `record.<field>`; others at `record.data.<field>`.
+   - Secrets and service keys stay on the backend.
+
+5. **Recommend a path**
+   Return: where the change lives (core vs custom, which app/dir), which
+   primitives are involved, which guides to follow, open questions, and the
+   verification step before finishing (`npm run typecheck`, `npm run test`).
+
+## Evaluating a proposal against the Spine Way
+
+When asked "is this a good idea?", output this structure:
+
+- **Verdict**: `approve` | `review` | `reject`
+- **Observations**: one line per relevant fundamental (the checklist above),
+  noting how the proposal conforms or violates.
+- **Recommendation**: the smallest conforming path, or what to change.
+
+`reject` when the proposal edits `.framework/`, wraps runtime CRUD in custom
+endpoints, or stores secrets client-side. `review` when placement, schema, or
+permission design is unclear. `approve` when every relevant fundamental holds.
+
+## Advising core vs. custom
+
+- `.framework/` — data model, auth, permissions, migrations, shared runtime,
+  generic components. Could more than one app use it? Then it is a framework
+  concern; flag it to the maintainer rather than editing core locally.
+- `custom/` — product-specific workflows, pages, seed data, app functions.
+
+## Rules
+
+- Do not write code until the approach is confirmed.
+- Do not assume facts not in the framework docs; if docs conflict with code on disk, trust the code and note it.
+- Always end with a clear next action for the user to confirm or redirect.

package/.framework/templates/agent/skills/spine-install-app/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: spine-install-app
+description: "Install a Spine app package via install-app — npm package → custom/apps/<slug>, seed data, manifest DB registration."
+allowed-tools:
+  - read
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You install Spine app packages into the project's `custom/apps/` workspace.
+
+## When to invoke
+
+- Install an app package (first-party or third-party) into `custom/apps/`.
+- Update an installed app's code from npm.
+- Sync a local `manifest.json` change (route_prefix, nav_items, registration)
+  to the database.
+
+## Commands
+
+```bash
+# Install an app from npm (first time)
+npx spine-framework install-app spine-framework-<slug>
+npx spine-framework install-app spine-framework-<slug>@<tag>   # pre-release
+
+# Update app code from npm (local manifest.json is preserved)
+npx spine-framework update-app spine-framework-<slug>
+
+# Push local manifest.json changes to the DB — no npm involved
+npx spine-framework update-db-app <slug>
+
+# Validate an app package before publishing
+npx spine-framework validate-app custom/apps/<slug>
+
+# Uninstall
+npx spine-framework uninstall-app spine-framework-<slug>
+```
+
+## What install does
+
+1. Copies app files into `custom/apps/<slug>/` per the package's
+   `manifest.json`.
+2. Runs the manifest `seed` block — generic upserts into the declared tables
+   using each entry's `conflict` key (idempotent; safe to re-run).
+3. Copies app migrations (if any) — apply with
+   `npx spine-framework migrate`.
+4. Registers the app row (`apps.slug`, `route_prefix`, `app_type`,
+   `renderer`) and merges `registration` into `spine.config.json`.
+
+## Critical safeguards
+
+- The manifest + seed contract is documented in
+  `.framework/src/instructions/reference/app-manifest.md` and
+  `.framework/src/instructions/reference/seeds.md`.
+- **Never** delete existing `custom/apps/`, `custom/functions/`, or
+  `custom/migrations/` content — installs are additive.
+- After first install, `manifest.json` belongs to the project — npm updates
+  preserve it; push changes with `update-db-app`.
+- `routes`/`nav_items` are root-relative — they must not include
+  `route_prefix`.
+
+## Verification
+
+```bash
+npx spine-framework validate-app custom/apps/<slug>
+npx spine-framework doctor          # runtime_wiring + health
+npm run verify                      # frozen integrity intact
+```
+
+Report what was installed, which seeds ran, and any conflicts needing manual
+resolution.

package/.framework/templates/agent/skills/spine-migration/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: spine-migration
+description: "Write a Spine database migration — ordered naming, idempotent SQL, ledger-aware, and safe for upgrade."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You write database migrations that run safely across fresh installs and
+existing deployments.
+
+## When to invoke
+
+- A schema change is needed (table, column, index, RLS policy, function).
+- An app needs seed-time or post-install data changes.
+
+## Placement
+
+- Framework migrations live in `.framework/migrations/` — **never edit them**;
+  they are framework-owned and upgrade-overwritten.
+- Project/app migrations live in `custom/migrations/` (or the app's own
+  `migrations/` dir). Apply with `npx spine-framework migrate`.
+
+## Naming and ordering
+
+- Files are `NNN_description.sql` with unique zero-padded numeric prefixes —
+  they apply in lexical order.
+- Check the highest existing prefix before numbering yours.
+
+## Idempotency checklist
+
+Every migration must be safe to run twice:
+
+- `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`,
+  `DROP ... IF EXISTS`.
+- `ON CONFLICT DO NOTHING` (or an explicit upsert) for seed/lookup rows.
+- `DROP POLICY IF EXISTS` before `CREATE POLICY` (policies have no
+  `IF NOT EXISTS`).
+- Conditional `DO $$ ... $$` blocks for column adds and other
+  existence-dependent DDL.
+- Never depend on IDs or timestamps generated at author time — use slugs or
+  stable keys to locate rows.
+
+## RLS rules
+
+- Every tenant/account-scoped table must have RLS enabled with policies using
+  the platform's actor/account helper functions.
+- Read `.framework/src/instructions/roles.md`,
+  `.framework/src/instructions/concepts/permissions.md`, and
+  `.framework/src/instructions/reference/database.md` before writing policies.
+- `adminDb` bypasses RLS — use it only where bypass is intended.
+- Idempotency model: `.framework/src/instructions/concepts/concurrency-and-idempotency.md`.
+
+## Steps
+
+1. Confirm the change cannot be expressed as `design_schema` or seed data —
+   migrations are for physical schema and structural data only.
+2. Pick the next `NNN` prefix in `custom/migrations/`.
+3. Write idempotent SQL per the checklist; wrap data backfills in
+   `DO $$ ... $$` so reruns are no-ops.
+4. Apply: `npx spine-framework migrate`. The migration ledger records applied
+   versions — a migration that fails halfway must be re-runnable.
+5. Verify: rerun `migrate` (must be a no-op), then
+   `npx spine-framework doctor` for the migrations check.
+
+## Rules
+
+- Migrations are additive — do not rewrite already-applied files.
+- No `.framework/migrations/` edits; upstream changes arrive via upgrade.
+- Destructive changes (drops, renames) get a written migration plan and
+  confirmation before running.

package/.framework/templates/agent/skills/spine-new-app/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: spine-new-app
+description: "Scaffold a new Spine app — types + design_schema, app package skeleton, manifest.json, seed files, and registration."
+allowed-tools:
+  - read
+  - write
+  - edit
+  - exec
+  - grep
+  - find_file_by_name
+---
+
+You scaffold a new Spine app into `custom/apps/<slug>/` following the app
+package contract.
+
+## When to invoke
+
+- The user wants a new application on top of Spine.
+- An existing app needs a new section and the app contract must be honored.
+
+## Prerequisites
+
+- Read `.framework/src/instructions/apps.md` (the `apps` entity),
+  `.framework/src/instructions/concepts/apps-and-renderers.md`, the app
+  walkthrough `.framework/src/instructions/guide/04-first-app.md`, and the
+  manifest contract `.framework/src/instructions/reference/app-manifest.md`.
+- Decide `app_type`: `full` (UI + functions), `ui` (frontend only),
+  `backend` (functions only), `data` (schema/seed only).
+- Decide `renderer`: `generic` renders from `design_schema.views` with no
+  custom pages; `custom` requires `index.tsx` + `pages/`.
+
+## Steps
+
+1. **Types first.** Each app-owned entity needs a row in `public.types` with a
+   valid `design_schema` (use the `spine-new-type` / `spine-schema` skills).
+   Slugs are global per `kind` — check existing types before naming.
+
+2. **Scaffold the package** at `custom/apps/<slug>/`:
+   - `package.json` — name `spine-framework-<slug>`, `"private": false`,
+     `version` matching `manifest.json`, a `spine` block
+     (`{ "type": "app", "slug", "manifestPath" }`), and `files` listing every
+     directory that exists.
+   - `manifest.json` — `name`, `slug`, `version`, `app_type`, `route_prefix`,
+     `required_roles`, `entry_point`, `sidebar_component`, `seed`, and
+     `registration` when the app supports self-registration.
+   - `index.tsx` — default-exported root component (full/ui apps).
+   - `pages/` — route-mapped page components (full/ui apps).
+   - `functions/` — Netlify handlers (full/backend apps).
+   - `seed/` — JSON arrays; no `id`/`app_id` fields (the framework injects
+     them). Every file declared in the `seed` block with `file`, `table`,
+     `conflict`.
+
+3. **Routes are root-relative.** `routes` and `nav_items` must NOT include
+   `route_prefix`; links inside the app use `useAppPath()`.
+
+4. **Validate:** `npx spine-framework validate-app custom/apps/<slug>` —
+   fix every error before publishing or installing.
+
+5. **Install/dev:** `npx spine-framework install-app <pkg>` installs from npm;
+   `npx spine-framework update-db-app <slug>` pushes manifest changes to the DB.
+
+## Rules
+
+- Never hand-edit `.framework/`; the app contract is data + custom code only.
+- Keep `package.json` and `manifest.json` versions in lockstep.
+- Seed files must be idempotent — reruns must not duplicate rows.
+- Verification: `validate-app` clean, `npm run typecheck`, `npm run test`.