spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/src/instructions/guide/04-first-app.md

@@ -0,0 +1,227 @@
+---
+title: Build your first app
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/types.ts
+  - .framework/functions/apps.ts
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/schema-utils.ts
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - .framework/src/components/app-shell/GenericListPage.tsx
+  - .framework/src/components/app-shell/GenericDetailPage.tsx
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/contexts/AppContext.tsx
+  - .framework/src/lib/api.ts
+  - .framework/cli/commands/create-app.ts
+  - .framework/cli/commands/generate.ts
+  - .framework/cli/commands/install-app.ts
+---
+
+# Build your first app
+
+The smallest useful Spine app is one type + one app row — no code at all.
+This walkthrough builds a `task` tracker end to end, then adds a custom page
+and a pipeline. You need a `system_admin` login (see
+[01-install-and-first-run.md](./01-install-and-first-run.md)) — app creation
+is restricted to system admins (`.framework/functions/apps.ts`).
+
+## Step 1 — define the type
+
+Admin UI → **Configs → Types → New** (or `POST /api/types`). Set:
+
+- **Kind**: `item` — records land in `public.items`.
+- **Slug**: `task` — unique within `kind`; callers resolve types by it.
+- **Design schema** — the fields, views, and permissions below.
+
+```json
+{
+  "scope": "account",
+  "fields": {
+    "title":    { "data_type": "text",   "label": "Title",    "required": true,  "system": true },
+    "status":   { "data_type": "select", "label": "Status",   "required": true,
+                  "options": ["todo", "doing", "done"] },
+    "priority": { "data_type": "select", "label": "Priority", "required": false,
+                  "options": ["low", "normal", "high"] },
+    "notes":    { "data_type": "textarea", "label": "Notes",  "required": false }
+  },
+  "views": {
+    "default_list": {
+      "type": "list", "display": "table", "label": "Tasks",
+      "fields": {
+        "title":      { "sortable": true, "display_type": "text" },
+        "status":     { "sortable": true, "display_type": "badge" },
+        "priority":   { "sortable": true, "display_type": "badge" },
+        "created_at": { "sortable": true, "display_type": "timestamp" }
+      },
+      "default_sort": { "field": "created_at", "direction": "desc" }
+    },
+    "default_detail": {
+      "type": "detail", "label": "Task",
+      "sections": [
+        { "title": "Core",
+          "fields": {
+            "title":    { "display_type": "input" },
+            "status":   { "display_type": "select" },
+            "priority": { "display_type": "select" },
+            "notes":    { "display_type": "textarea" }
+          } }
+      ]
+    }
+  },
+  "record_permissions": {
+    "system_admin": ["create", "read", "update", "delete"],
+    "engineering":  ["create", "read", "update"]
+  },
+  "functionality": null
+}
+```
+
+On save, `validation_schema` is regenerated from `design_schema` by the types
+API (`.framework/functions/types.ts`,
+`.framework/functions/_shared/schema-utils.ts`) — you never write it yourself.
+The rules that matter here: `select` fields need `options`; `title` is
+`system: true` so it maps to the `items.title` column while `status`,
+`priority`, and `notes` live in `items.data`; `record_permissions` is the base
+grant evaluated on every `/api/admin-data` call, and its keys are matched
+**verbatim** against `roles.slug` — so use real seeded slugs (`system_admin`,
+`engineering`, `support`, …); a nonexistent or misspelled slug silently grants
+nothing (`.framework/functions/_shared/permissions.ts`).
+
+## Step 2 — register the app
+
+Admin UI → **Configs → Apps → New** (or `POST /api/apps`):
+
+```json
+{
+  "slug": "taskboard",
+  "name": "Taskboard",
+  "route_prefix": "/taskboard",
+  "renderer": "generic",
+  "min_role": "engineering",
+  "is_active": true,
+  "nav_items": [
+    { "id": "tasks", "label": "Tasks", "path": "tasks", "type_slug": "task" }
+  ]
+}
+```
+
+`route_prefix` mounts the app at `/taskboard`; `renderer: "generic"` tells the
+router to use `GenericAppShell`; each `nav_items` entry with a `type_slug`
+gets list, `new`, and `:id` routes rendered from the type's views
+(`.framework/src/components/app-shell/GenericAppShell.tsx`,
+`GenericListPage.tsx`, `GenericDetailPage.tsx`). An app is routable when it
+has a `route_prefix` and a renderer other than `none`
+(`.framework/src/contexts/AppContext.tsx`).
+
+Sign out/in (or wait for the apps registry refetch) and `/taskboard` renders
+the Tasks list — create, edit, sort, and detail all work with zero code.
+
+## Step 3 — add custom UI
+
+When the generic views are not enough, switch `renderer` to `custom` and put
+your code where the loader looks for it:
+
+```bash
+npx spine-framework create-app taskboard --role engineering
+```
+
+This scaffolds `custom/apps/taskboard/` with `manifest.json`, `index.tsx`
+(a React Router stub), and `components/`, and registers the `apps` row with
+`renderer: 'custom'` (`.framework/cli/commands/create-app.ts` — if the row
+already exists it skips the insert). `CustomAppLoader` lazy-loads
+`custom/apps/taskboard/index.tsx` via `import.meta.glob`
+(`.framework/src/components/CustomAppLoader.tsx`), so edit the component, then:
+
+```bash
+npm run dev:netlify   # assemble runs automatically; or: npm run assemble && netlify dev
+```
+
+Your app is a normal React app under the `/taskboard/*` route, inside
+`AppWrapper`. Custom functions go in `custom/functions/` (prefix filenames
+`custom_` — assembly hard-fails on basename collisions with framework
+functions; see [02-project-map.md](./02-project-map.md)).
+
+## Step 4 — CRUD via `/api/admin-data`
+
+Custom pages use the same endpoint as the generic renderer — never write a
+bespoke CRUD function:
+
+```ts
+import { apiFetch } from '@core/lib/api'   // assembled alias → .framework/src
+
+// list
+await apiFetch('/api/admin-data?action=list&entity=items&type_slug=task&limit=50')
+
+// create — type_slug resolves the type; non-system fields go in `data`
+await apiFetch('/api/admin-data?action=create', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    entity: 'items',
+    type_slug: 'task',
+    title: 'Ship the docs',
+    data: { status: 'todo', priority: 'high' }
+  })
+})
+
+// update — entity + id are query params; the body is the field patch
+await apiFetch('/api/admin-data?action=update&entity=items&id=<uuid>', {
+  method: 'PATCH',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ data: { status: 'doing' } })
+})
+
+// remove — soft-deletes (is_active = false) unless soft=false is passed
+await apiFetch(`/api/admin-data?action=remove&entity=items&id=<uuid>`, { method: 'DELETE' })
+```
+
+`apiFetch` (`.framework/src/lib/api.ts`) attaches the Supabase Bearer token and
+the `X-Account-Id` header; `admin-data` resolves `task` → its `type_id`,
+stamps `design_schema`/`validation_schema` onto the new record, evaluates
+`record_permissions` for the caller's role, writes, and fires
+`item_created` triggers (`.framework/functions/admin-data.ts`).
+
+## Step 5 — wire a pipeline
+
+1. Admin UI → **Configs → Pipelines → New**: name it, `trigger_type` =
+   `event`, `stages` = e.g. a `send_notification` stage
+   (`.framework/functions/_shared/pipeline-runner.ts` has the built-in
+   `stage_type` list).
+2. Admin UI → **Configs → Triggers → New**: `event_type` = `item_created`,
+   `pipeline_id` = the pipeline from step 1, `config.type_slug` = `task` to
+   scope it (`.framework/functions/_shared/trigger-engine.ts`).
+3. Ensure `INTERNAL_INVOKE_SECRET` is set — trigger dispatch POSTs to the
+   `pipeline-runner-background` function and silently no-ops without it.
+4. Create a task → the trigger queues a `pipeline_executions` row and the
+   background runner executes the stages; watch it under
+   **Observability → Executions**.
+
+## Gaps
+
+- **`npx spine-framework generate` was removed.** The old scaffold wrote
+  stubs to a `v2-custom/` tree with `../v2-core/...` imports and a legacy
+  `design_schema` shape (`type`/`layout` instead of `data_type`/`views`). It
+  now prints migration guidance and exits 1
+  (`.framework/cli/commands/generate.ts`). Author types in the admin UI or via
+  `/api/types` instead.
+- **`create-app` defaults `--role member`.** `member` and `member_admin`
+  are seeded by `.framework/migrations/073_seed_member_roles.sql` (003
+  seeds `system_admin`, `engineering`, `engineering_admin`, `product`,
+  `docs`, `qa`, `devops`, `management`, `sales`, `csm`, `tam`, `support`,
+  `support_admin`), so the default is valid on current installs. On a
+  database that predates 073, pass `--role` a slug that exists in your
+  `roles` table or create the role first.
+- **`create-app` scaffold is minimal** — a `Routes` stub only. There is no
+  generated CRUD page, `admin-data` hook, or seed block in the manifest it
+  writes; the pattern in Step 4 is the integration contract.
+- **Generic renderer is list/detail only.** `GenericAppShell` generates routes
+  solely for nav items carrying `type_slug`; a nav item without one renders a
+  sidebar button that navigates nowhere routable. Dashboards, wizards, or
+  bespoke layouts require `renderer: 'custom'`.
+- **No packaged example app ships in the npm package** — `custom/` is created
+  empty by `init`, so there is no reference implementation to copy inside an
+  installed project.

package/.framework/src/instructions/guide/05-glossary.md

@@ -0,0 +1,183 @@
+---
+title: Glossary
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/migrations/001_core_schema.sql
+  - .framework/migrations/004_core_rpc_and_broker.sql
+  - .framework/migrations/011_spine_system_account.sql
+  - .framework/migrations/020_schema_reconciliation.sql
+  - .framework/functions/admin-data.ts
+  - .framework/functions/_shared/principal.ts
+  - .framework/functions/_shared/permissions.ts
+  - .framework/functions/_shared/trigger-engine.ts
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/functions/system-cron.ts
+  - .framework/cli/lib/project-files.ts
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/src/components/app-shell/GenericAppShell.tsx
+  - scripts/assemble.sh
+  - scripts/assemble-frontend.sh
+  - scripts/assemble-functions.sh
+---
+
+# Glossary
+
+The Spine vocabulary, in dependency order. Terms in **bold** are defined
+elsewhere on this page or in the [domain model](./03-domain-model.md).
+
+## Identity
+
+**account** — a tenant boundary (`public.accounts`). Every runtime record is
+scoped to an `account_id`; accounts nest via `parent_id` with the
+`account_paths` closure table for descendant lookups. The seeded `spine-system`
+account is the platform root (see **scope**).
+
+**person** — a human user (`public.people`), linked to Supabase `auth.users`
+by `auth_uid` and placed in one account with one role. Non-first,
+non-invited signups have no account until registration placement assigns one.
+
+**principal** — the resolved identity attached to a request (`ctx.principal`),
+computed per call by `.framework/functions/_shared/principal.ts`. One of:
+`human` (Bearer JWT → person), `machine` (`x-api-key` header → API key, or
+internal cron/trigger principal), `system` (internal invoke), or `anonymous`.
+Carries `id`, `type`, `accountId`, `roles`, `scopes`, and provenance.
+
+**role** — a named permission set (`public.roles`, unique `slug`) assigned to
+a person. Roles are referenced throughout `design_schema.record_permissions`.
+`system_admin` is the seeded superuser role; roles ending in `_admin` can
+manage invites/members within their own account.
+
+## Schema
+
+**type** — the schema definition for a record kind (`public.types`), unique
+per `(kind, slug)`. Carries `design_schema` (generated into
+`validation_schema`), `ownership` (`system` | `app` | `tenant`), `icon`,
+`color`, `is_active`.
+
+**design_schema** — the authoring-format JSON on a type: `fields`, `views`,
+`record_permissions`, `scope`, `functionality`. See [types](../types.md) and
+the worked example in [04-first-app.md](./04-first-app.md).
+
+**validation_schema** — the runtime-format schema derived from
+`design_schema` on every save by `.framework/functions/types.ts` /
+`.framework/functions/_shared/schema-utils.ts`. Read-only; used to validate
+record writes.
+
+**kind** — which runtime table a type governs: `item`, `thread`, `message`,
+`link`, `attachment`, `watcher`, `account`, `person` (the `ENTITY_TO_KIND`
+map in `.framework/functions/admin-data.ts`).
+
+**runtime record** — a row in one of the typed tables (`items`, `threads`,
+`messages`, `links`, `attachments`, `watchers`, `accounts`, `people`). Always
+has `type_id`, `account_id`, `data` jsonb, and the `design_schema`/
+`validation_schema` stamped at creation.
+
+**system field** — a `design_schema` field flagged `system: true`, stored as
+a real table column and read as `record.<field>` (e.g. `title` →
+`items.title`). Non-system fields live in `data` and read as
+`record.data.<field>` (split implemented in
+`.framework/src/components/app-shell/GenericDetailPage.tsx`).
+
+## Apps
+
+**app** — a registered application (`public.apps`): `slug`, `route_prefix`,
+`renderer`, `nav_items`, `min_role`/`required_roles`, `config`, `is_active`,
+`is_system`. Appears in the authenticated router when it has a
+`route_prefix` and `renderer != 'none'`
+(`.framework/src/contexts/AppContext.tsx`).
+
+**renderer** — how an app's UI is produced. `generic` = schema-driven shell
+(`GenericAppShell` renders `nav_items` → list/detail pages from type views).
+`custom` = lazy-loaded React entry (`custom/apps/<slug>/index.tsx`, falling
+back to `.framework/src/apps/<slug>/index.tsx`) via
+`.framework/src/components/CustomAppLoader.tsx`. `none` = registry-only, not
+routed.
+
+**manifest** — two meanings, both frozen JSON contracts: (a) an app
+`manifest.json` in `custom/apps/<slug>/` declaring routes, `nav_items`,
+`required_roles`, `registration`, and a `seed` block consumed by
+`install-app`/`seed-app`/`update-db-app`
+(`.framework/cli/commands/install-app.ts`); (b) `.spine-manifest.json`, the
+project's frozen integrity manifest of per-file sha256 hashes
+(`.framework/cli/lib/project-files.ts`).
+
+## Automation
+
+**pipeline** — a multi-step workflow (`public.pipelines`, `stages` jsonb)
+executed by `runPipeline` in
+`.framework/functions/_shared/pipeline-runner.ts`. Each stage's `stage_type`
+maps to a `public.actions` row or a built-in handler (`http_request`,
+`send_notification`, `agent_inference`, `query_items`, …).
+
+**trigger** — an event subscription (`public.triggers`): `event_type` +
+`pipeline_id` + optional `config` filters. `admin-data` emits
+`<entity>_<created|updated|deleted>` events (e.g. `item_created`); matching
+triggers enqueue an execution and dispatch the pipeline via the
+`pipeline-runner-background` function (requires `INTERNAL_INVOKE_SECRET`).
+
+**timer** — a schedule (`public.timers`): `timer_type`
+(`interval` | `cron` | `once`) + `pipeline_id`. The `trigger-scheduler`
+Netlify scheduled function (every minute, `netlify.toml`) runs `system-cron`,
+which runs due timers through `runPipeline` under a `timer:*` principal.
+
+**integration** — a named external connection (`public.integrations`):
+adapter slug + `config` + `credentials` (`env_var` reference or literal
+`value`). Inbound webhooks arrive via `integration-routes`; outbound calls
+via `integration-outbound` write **deliveries**.
+
+## AI
+
+**prompt config** — a named, versioned prompt template
+(`public.prompt_configs`) referenced by AI agents and pipeline stages.
+
+**AI agent** — a reusable model + prompt + tool configuration
+(`public.ai_agents`), invocable via `/api/ai-agents?action=run` or the
+`agent_inference` pipeline stage.
+
+**embedding** — a pgvector embedding (`public.embeddings`) queried through
+the `match_embeddings`/`search_similar_embeddings` RPCs; backs semantic
+search and knowledge stages.
+
+## Access and delivery
+
+**API key** — a machine credential (`public.api_keys`) presented as the
+`x-api-key` header; resolved by prefix and verified against a stored hash
+(`.framework/functions/_shared/principal.ts`,
+`.framework/functions/_shared/hash-api-key.ts`). Has `rate_limit` and usage
+logged in `api_key_usage_logs`.
+
+**delivery** — an outbound delivery attempt record
+(`public.webhook_deliveries`) written by `integration-outbound`; retried by
+`retry-deliveries` inside `system-cron`. See [deliveries](../deliveries.md).
+
+**execution** — a run record: `pipeline_executions` for pipelines,
+`trigger_executions` for trigger fires, `schedule_executions` for scheduled
+actions. Statuses progress `queued` → `running` → `completed`/`failed`.
+
+**audit log** — privileged-action events written by `emitAudit`
+(`.framework/functions/_shared/audit.ts`) plus the `public.logs` stream —
+e.g. `trigger.fired`, `app.created`, `app.version_updated`.
+
+## Project layout
+
+**scope** — `design_schema.scope`: `account` (records belong to the caller's
+tenant, the default) or `platform` (`admin-data` re-anchors created records
+to the `spine-system` account).
+
+**assembled** — `.assembled/`, the generated build tree:
+`.assembled/src` (framework frontend + verbatim `custom/apps/<slug>/`) and
+`.assembled/netlify/functions` (flattened functions for Netlify), produced by
+`npm run assemble` (`scripts/assemble.sh`).
+
+**`.framework/`** — the sealed, framework-owned tree vendored into your
+project. Checksummed in `.spine-manifest.json`; overwritten by
+`npx spine-framework upgrade`. See
+[02-project-map.md](./02-project-map.md).
+
+**CIL** — the Code Intelligence Layer: Spine's code-intelligence subsystem
+(ingested code chunks, embeddings, and a searchable project graph) surfaced
+under the admin `cil` pages (`.framework/src/pages/admin/cil/`). Optional;
+your apps do not depend on it.

package/.framework/src/instructions/integrations.md

@@ -0,0 +1,96 @@
+---
+title: Integrations
+audience: both
+kind: entity
+verified_against: e13127d
+verified_on: 2026-10-30
+source_files:
+  - .framework/functions/integrations.ts
+  - .framework/functions/integration-outbound.ts
+  - .framework/functions/integration-routes.ts
+  - .framework/functions/_shared/resolve-credentials.ts
+  - .framework/src/pages/admin/IntegrationsPage.tsx
+  - .framework/src/pages/admin/IntegrationDetailPage.tsx
+---
+
+## What this is for
+
+An **integration** connects Spine to an external service (OpenAI, Resend, a generic HTTP endpoint, a database, ...). The record stores the provider, runtime `config` (including which adapter handles calls), and `credentials`. Pipelines and app code reference the integration by slug.
+
+## Fields and settings
+
+- **Name** *(required)* — display name. The slug is **derived from it** server-side (`OpenAI` → `openai`); pass `slug` in the body only to override.
+- **Type** *(required)* — select: `webhook`, `api`, `database`, `file`, `custom`. Categorizes the integration; the create form pre-fills sensible `config`/`credentials` templates per type.
+- **Provider** *(required)* — free-text provider name (e.g. `openai`, `resend`, `postgres`).
+- **Version** — string, default `1.0.0`.
+- **Config (JSON)** — adapter and runtime settings. The adapter is named **here**, not as a top-level field: `config.outbound_adapter` (or `config.inbound_adapter` for inbound webhooks) points at an adapter module such as `adapters/openai-outbound`.
+- **Credentials (JSON)** — secrets keyed by field name, each `{ "source": "env_var" | "value", "value": "..." }`. `source: "env_var"` resolves the named env var inside the function runtime; `source: "value"` stores the literal secret in the DB. The credential field callers read defaults to `api_token`.
+- **Configured** — computed, read-only. `is_configured` is re-derived on every save from `credentials` (all entries must resolve); the UI shows it as Configured/Pending.
+- **App ID** — select, optional. Owning app; blank = account-scoped.
+- **Active** — boolean. Inactive integrations fail closed — callers get an error, not a fallback.
+- **Description / Metadata** — optional notes and free-form data.
+
+**Downstream effects**
+
+- `env_var` credentials are resolved inside the function runtime — the variable must exist in the deployed env or calls fail at request time (`credential_env_missing`), not at save time. `source: "value"` persists the literal secret — prefer `env_var` for anything real.
+- An absent or explicitly-empty (`source: "value"`, `value: ""`) credential entry means "call without auth" — the outbound broker sends no credential and the adapter decides whether one is required (the seeded `generic-http` integration works unauthenticated out of the box this way).
+- Built-in outbound adapters: `adapters/openai-outbound`, `adapters/generic-webhook-outbound`, `adapters/resend-outbound`. Any other adapter path is dynamically imported — a typo saves fine but fails on first call.
+- Outbound calls create a `webhook_deliveries` row (`pending`, `max_attempts` default 3 or `config.retry_policy.max_attempts`) and show up under Deliveries.
+- Apps declare `integration_deps`; installing an app without its integrations leaves features broken until the records exist.
+- The list/detail APIs use `adminDb` for system admins — integrations exist per account and per system scope.
+
+## Minimal configuration
+
+```json
+{
+  "name": "OpenAI",
+  "integration_type": "api",
+  "provider": "openai",
+  "is_active": true,
+  "config": {
+    "outbound_adapter": "adapters/openai-outbound",
+    "model": "gpt-4o"
+  },
+  "credentials": { "api_token": { "source": "env_var", "value": "OPENAI_API_KEY" } }
+}
+```
+
+## Full configuration
+
+```json
+{
+  "name": "Outbound webhook",
+  "integration_type": "api",
+  "provider": "custom",
+  "version": "1.2.0",
+  "is_active": true,
+  "config": {
+    "outbound_adapter": "adapters/generic-webhook-outbound",
+    "base_url": "https://hooks.example.com",
+    "timeout_ms": 10000,
+    "retry_policy": { "max_attempts": 5 }
+  },
+  "credentials": { "api_token": { "source": "env_var", "value": "ACME_HOOK_TOKEN" } },
+  "metadata": { "owner": "platform" }
+}
+```
+
+## Example
+
+A support app lists `integration_deps: ["openai"]` — the AI agents resolve the `openai` integration by slug for model calls (credential field `api_token`), and a second integration (`config.outbound_adapter: "adapters/generic-webhook-outbound"`) delivers outbound ticket events, each attempt logged under Deliveries.
+
+## Core files
+
+- `.framework/functions/integrations.ts` — API (list/get/create/update; `is_configured` computed on write; non-admin reads are sanitized)
+- `.framework/functions/integration-outbound.ts` — outbound broker (adapter registry, delivery rows, retry math)
+- `.framework/functions/integration-routes.ts` — inbound webhook entry
+- `.framework/functions/_shared/resolve-credentials.ts` — `env_var`/`value` credential resolution
+- `.framework/src/pages/admin/IntegrationsPage.tsx` / `IntegrationDetailPage.tsx` — admin UI (per-type config templates on the detail form)
+- Table: `public.integrations`
+
+## Agent notes
+
+- Credentials shape is `{ "api_token": { "source": "env_var", "value": "OPENAI_API_KEY" } }` — nested `source`/`value` objects, not `{ "env_var": "..." }`. The latter saves but never resolves.
+- Never put real secrets in `credentials.*.value` with `source: "value"` in seeds or docs — always `env_var`.
+- There is no top-level `adapter` or `configuration` column — the field is `config`, and the adapter lives at `config.outbound_adapter` / `config.inbound_adapter`.
+- After changing credentials, the broker picks them up on the next call — no cache flush needed.

package/.framework/src/instructions/internal/cil-markers.md

@@ -0,0 +1,83 @@
+---
+title: "CIL markers and generated doc tags"
+audience: developers, agents
+kind: reference
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/functions/_shared/pipeline-runner.ts
+  - .framework/scripts/cil-migrate-markers.ts
+  - AGENTS.md
+---
+
+# CIL markers and generated doc tags
+
+Files throughout `.framework/` — `src`, `functions`, `cli`, `migrations` —
+carry dense comment blocks that look like this:
+
+```ts
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/pipeline-runner.ts:isuuid:function" type="function" identity="isUuid" parent="~/.framework/functions/_shared/pipeline-runner.ts"]
+// CIL[DOC-MACRO purpose="isUuid function"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+function isUuid(v: string | undefined | null): v is string { ... }
+// CIL[END stable_id="~/.framework/functions/_shared/pipeline-runner.ts:isuuid:function"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+```
+
+and generated JSDoc like this:
+
+```ts
+/**
+ * Validates whether a given string is a properly formatted UUID.
+ * @inputSpec   - v: string — the value to be checked
+ * @outputSpec  v is string — true if the value is a valid UUID
+ * @sideEffects none
+ * @stability   stable
+ * @calls       UUID_RE.test
+ * @cil-generated
+ */
+```
+
+## What they are
+
+**CIL** (Code Intelligence Layer) is the repository's internal
+code-indexing tooling — it chunks the codebase into addressable units,
+attaches generated documentation, and keeps embeddings in sync for semantic
+search inside the monorepo. The comments are its on-disk metadata:
+
+- `// CIL[BEGIN ...]` / `// CIL[END ...]` — delimit one tracked code chunk.
+  `stable_id` is the chunk's durable identity
+  (`<file>:<slug>:<kind>`); `type`, `identity`, and `parent` describe it.
+- `// CIL[DOC-* …]` — generated or curated facts about the chunk:
+  `DOC-MACRO` (purpose), `DOC-RESPONSIBILITY`, `DOC-CONTEXT`
+  (module/layer/related files), `DOC-CONTRACT` (inputs/outputs/errors/
+  side_effects), `DOC-MICRO` (logic summary, notable decisions),
+  `DOC-CONFIDENCE` (pass + score), `DOC-STABILITY`, `DOC-AUDIENCE`,
+  `DOC-PARAM`, `DOC-NOTE`, and `DOC-LEARNING`.
+- `// CIL[DOC-VECTOR type="…" content="…" status="…"]` — the payload that
+  becomes a search embedding (types include `context`, `blast_radius`,
+  `constraint`, `configuration`, `implementation_pattern`, `user_journey`).
+  `status="ready"` means it was generated; **`status="pending_human_input"`
+  means the field is intentionally blank until an author fills it** — it is
+  not an error and not a warning about the code itself.
+- JSDoc tags `@macro`, `@micro`, `@inputSpec`, `@outputSpec`, `@sideEffects`,
+  `@calls`, `@seeAlso`, `@errorHandling`, `@stability`, `@module`, `@layer`,
+  `@audience`, `@cil-generated` mirror the same metadata in human-readable
+  form; `@cil-generated` marks text written by the pipeline rather than a
+  person.
+
+## What they mean for you
+
+- **Safe to ignore.** They are comments; they have no runtime effect, no API
+  surface, and no effect on how you build apps on Spine. CIL is maintainer
+  tooling, not a framework feature.
+- **Read them as hints, not truth.** `DOC-*` summaries and JSDoc are
+  generated interpretation — usually accurate, occasionally stale. The code
+  is the authority; treat the tags like any other doc comment.
+- **In framework files, leave them in place.** Editing or deleting markers by
+  hand is harmless locally but gets rebuilt/renumbered the next time the
+  repo's marker tooling runs (see `cil:migrate-markers` /
+  `.framework/scripts/cil-migrate-markers.ts`). In your own `custom/` code
+  you're free to add or omit them — nothing requires them.
+- The contributor-facing conventions live in the repo's `AGENTS.md`; this
+  page is only the legend for readers who meet the markers in shipped source.