spine-framework 0.4.4 → 0.5.0-rc.4

package/.framework/src/instructions/guide/00-orientation.md

@@ -0,0 +1,106 @@
+---
+title: Orientation — what Spine Framework is
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - package.json
+  - netlify.toml
+  - .env.example
+  - .framework/cli/commands/init.ts
+  - .framework/templates/project.json
+  - .framework/src/components/admin/PageInstructions.tsx
+  - .framework/src/instructions/README.md
+---
+
+# Orientation
+
+Spine Framework is a multi-tenant application platform you install into an npm
+project. It gives you the "boring 80%" of a SaaS product — the infrastructure
+every app needs and nobody wants to rebuild — so your code can be the
+interesting 20%.
+
+## What you get out of the box
+
+- **A typed runtime data layer.** Accounts, people, and typed records (items,
+  threads, messages, links, attachments, watchers) stored in Supabase Postgres,
+  all reachable through one CRUD/permissions API (`.framework/functions/admin-data.ts`).
+- **Auth and tenancy.** Supabase Auth for sign-in, an invite/registration
+  pipeline (`.framework/functions/invites.ts`), hierarchical accounts, and a
+  first-user bootstrap that seeds a system administrator.
+- **RBAC.** Roles plus per-type `record_permissions` evaluated on every request
+  (`.framework/functions/_shared/permissions.ts`).
+- **Automation.** Declarative pipelines, event triggers, timers, integrations,
+  and AI agents — all database rows, all driven by the same runtime
+  (`.framework/functions/_shared/pipeline-runner.ts`,
+  `.framework/functions/_shared/trigger-engine.ts`).
+- **An admin UI.** A schema-driven admin surface at `/spine-framework/admin`
+  built from `.framework/src/apps/admin/index.tsx`, plus generic list/detail
+  pages that render directly from each type's views.
+- **Operations.** API keys for machine principals, delivery tracking, logs,
+  metrics, and pipeline execution history.
+
+The stack is deliberately conventional: a React + Vite frontend, Netlify
+Functions as the API layer, and Supabase (Postgres + Auth) as the database.
+`netlify.toml` points functions at `.assembled/netlify/functions` and publishes
+`dist`; `.env.example` lists the Supabase keys the app needs.
+
+## What `npm install spine-framework` + `npx spine-framework init` gave you
+
+`init` copies a framework-owned file set — declared in
+`.framework/templates/project.json` — into your project: the `.framework/`
+tree (frontend source, Netlify functions, migrations, CLI, seeds, schemas),
+`config/` build files, root `scripts/`, `bin/`, a neutral `spine.config.json`,
+a merged `package.json`, `netlify.toml`, `.gitignore`, and a frozen
+`.spine-manifest.json` recording the hash of every protected file. It also
+creates an empty `custom/` workspace — the one place your code lives.
+
+Two consequences follow:
+
+1. **`.framework/` (plus `config/` and `scripts/`) is sealed.** Every file is
+   hashed into `.spine-manifest.json`; `npx spine-framework upgrade` refuses to
+   overwrite a locally modified tree unless you pass `--force`.
+2. **`custom/` is yours.** Apps, functions, components, and migrations you
+   write go there; the framework never touches it.
+
+See [02-project-map.md](./02-project-map.md) for the full anatomy.
+
+## How this instruction book is organized
+
+This book ships inside the package at `.framework/src/instructions/` and is
+also rendered inside the admin UI — admin pages mount a
+`PageInstructions` sheet that loads these files as raw markdown and renders
+them with `react-markdown` + `remark-gfm`
+(`.framework/src/components/admin/PageInstructions.tsx`). Diagrams are plain
+ASCII; the renderer does not load mermaid.
+
+| Section | Kind | Contents |
+|---|---|---|
+| `guide/` | guide | End-to-end walkthroughs — you are here. |
+| `concepts/` | concept | Mental models (tenancy, permissions, schema). |
+| `tasks/` | task | Single-goal procedures with verification steps. |
+| `reference/` | reference | Exhaustive lookups (env vars, CLI, endpoints). |
+| `operations/` | ui | Admin-UI surfaces and operational runbooks. |
+| `internal/` | mixed | Repo-only notes; exempt from shipped-doc rules. |
+| book root | entity | One file per Spine entity — [types](../types.md), [apps](../apps.md), [roles](../roles.md), [pipelines](../pipelines.md), [triggers](../triggers.md), [timers](../timers.md), [integrations](../integrations.md), [ai-agents](../ai-agents.md), [prompts](../prompts.md), [api-keys](../api-keys.md), [deliveries](../deliveries.md). |
+
+Entity files all use the same seven sections — *What this is for → Fields and
+settings → Minimal configuration → Full configuration → Example → Core files →
+Agent notes* — so once you have read one, you know the shape of all of them.
+
+## How to read it
+
+- **Developers:** read this guide section in order
+  ([install](./01-install-and-first-run.md) →
+  [project map](./02-project-map.md) →
+  [domain model](./03-domain-model.md) →
+  [first app](./04-first-app.md)), then the entity file for whatever you are
+  building, then `reference/` for exact spellings.
+- **Agents:** [03-domain-model.md](./03-domain-model.md) gives you the
+  primitives and how they compose; each entity file's *Agent notes* section
+  lists the mistakes that actually break things; [05-glossary.md](./05-glossary.md)
+  pins down terminology.
+- Every page is verified against the code at the `verified_against` commit in
+  its frontmatter. Where the docs disagree with code, code wins — treat that as
+  a bug and check `Core files` on the relevant entity page.

package/.framework/src/instructions/guide/01-install-and-first-run.md

@@ -0,0 +1,253 @@
+---
+title: Install and first run
+audience: developers, agents
+kind: guide
+verified_against: d0c49d4
+verified_on: 2026-10-30
+source_files:
+  - .framework/cli/commands/init.ts
+  - .framework/cli/lib/project-files.ts
+  - .framework/templates/project.json
+  - .framework/templates/spine.config.neutral.json
+  - .framework/cli/commands/migrate.ts
+  - .framework/cli/commands/bootstrap.ts
+  - .env.example
+  - netlify.toml
+  - scripts/dev-netlify.sh
+  - scripts/netlify-dev-wrapper.sh
+  - config/vite.config.ts
+  - .framework/public/_redirects
+  - .framework/src/App.tsx
+  - .framework/src/pages/SetupPage.tsx
+  - .framework/src/pages/auth/RegisterPage.tsx
+  - .framework/functions/invites.ts
+  - .framework/migrations/052_registration_security.sql
+---
+
+# Install and first run
+
+Prerequisites: Node ≥ 22.13 and npm ≥ 10 (recorded in `.spine-manifest.json`
+by init), a Supabase project, and (for local dev) the Netlify CLI — pinned as a
+devDependency, so `npm install` puts it in `node_modules`.
+
+## Step 1 — scaffold
+
+```bash
+npm install spine-framework
+npx spine-framework init          # or: init <dir>
+```
+
+Tarball/pre-release installs work the same way: `npm i
+./spine-framework-<ver>.tgz` — `init` keeps the `file:` spec in
+`package.json` rather than overwriting it with a registry version.
+
+`init` (`.framework/cli/commands/init.ts`) copies the framework-owned file set
+declared by `.framework/templates/project.json` into the target directory:
+
+- **`.framework/`** — `cli`, `functions`, `migrations`, `public`, `schemas`,
+  `scripts`, `seeds`, `src`, `tests`, `docs`, `templates`, plus `index.html`
+  and `README.md`.
+- **`config/`** — `vite.config.ts`, the tsconfig family, `tailwind.config.cjs`,
+  `postcss.config.cjs`, `components.json`.
+- **Root files** — the shipped `scripts/*.sh` / `*.mts` / `verify-install.ts`
+  set, `bin/`, `vitest.config.ts`, `.env.example`, `LICENSE.md`.
+- **`custom/`** — the empty workspace `init` creates for your code:
+  `custom/apps`, `custom/functions`, `custom/components`,
+  `custom/migrations`, `custom/tests`.
+- **Generated files** — `package.json` (your name, framework scripts, the
+  framework's dependency set inlined, plus an exact `spine-framework` pin),
+  `package-lock.json` (when the package ships the verified lock template),
+  `.gitignore`, `netlify.toml`, a neutral `spine.config.json`, and the frozen
+  `.spine-manifest.json` integrity manifest.
+- **Agent assets** — `AGENTS.md` (the framework-owned rules block between the
+  `spine-framework:begin/end` markers — refreshed on upgrade; keep your own
+  notes outside the markers) and `.devin/skills/spine-*/` task skills, synced
+  from `.framework/templates/agent/`. These are hashed into the manifest's
+  `agent_files` map rather than `files`.
+
+`init` is deliberately file-only: it does **not** run `npm install`, write
+`.env`, or touch any database or network resource. It refuses to run into a
+directory that already has `.framework/` — that is what
+`npx spine-framework upgrade` is for.
+
+## Step 2 — `.env`
+
+```bash
+cp .env.example .env
+```
+
+Required for a working install (`.env.example` has the full list):
+
+| Variable | Used by |
+|---|---|
+| `VITE_SUPABASE_URL`, `VITE_SUPABASE_ANON_KEY` | the browser app (`.framework/src/lib/supabase.ts`) |
+| `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_ANON_KEY` | Netlify functions (service-role + user-scoped clients) |
+| `SUPABASE_DB_PASSWORD` | `npx spine-framework migrate` — connects directly to `db.<project-ref>.supabase.co:5432` as `postgres` (`.framework/cli/commands/migrate.ts`) |
+| `APP_BASE_URL` | invite links and auth redirects (`http://localhost:8888` in dev) |
+
+Where to find them: the URL and both keys are on one page — **Supabase
+Dashboard → Project Settings → API Keys** (older dashboards: Settings →
+API / Data API); `SUPABASE_DB_PASSWORD` is under **Project Settings →
+Database**. Current dashboards issue new-style keys: the **Publishable
+key** (`sb_publishable_…`) is the anon key and a **Secret key**
+(`sb_secret_…`) is the service-role key — set `*_ANON_KEY` /
+`SUPABASE_SERVICE_ROLE_KEY` to them directly. Legacy `anon`/`service_role`
+JWTs work identically (verified end-to-end on a hosted project:
+`signInWithPassword`, `auth.admin.createUser`, and PostgREST all accept the
+new formats).
+
+Optional but worth knowing early: `RESEND_API_KEY` (invite/notification
+email), `OPENAI_API_KEY` (AI stage types), `VITE_TURNSTILE_SITE_KEY` (bot
+protection on auth pages), `SCHEDULER_API_KEY` (system-cron HTTP guard), and
+`INTERNAL_INVOKE_SECRET` — **required for trigger-dispatched pipelines**: if it
+is unset, triggers write a `queued` execution row but the pipeline runner is
+never invoked (`.framework/functions/_shared/trigger-engine.ts`).
+
+## Step 3 — install deps and verify
+
+```bash
+npm install
+npm run verify     # scripts/verify-integrity.sh — checks the tree against .spine-manifest.json
+```
+
+Expect `npm audit` findings — the pinned dependency set (mostly the
+`netlify-cli` devDependency tree) carries known advisories, and the count
+jumps between the tarball-only install and the full post-init install. The
+shipped `package-lock.json` template is the verified set: do **not** run
+`npm audit fix`, which moves pinned versions the manifest was generated
+against. Findings are tracked upstream, not per-project.
+
+## Step 4 — migrate the database
+
+```bash
+npx spine-framework migrate
+```
+
+This applies every `.framework/migrations/*.sql` file (and anything in
+`custom/migrations/`, unless `--framework-only`) in order, recording each in a
+`_spine_migrations` table so reruns are idempotent (`--dry-run` shows pending
+files without applying them). File numbering is non-contiguous — retired
+migrations are removed from the package rather than renumbered, so gaps are
+expected and only lexical order matters. The core migration seeds the `system_admin`
+role, the `spine-core` and `admin` apps, the `spine-system` account, and the
+core runtime types (`.framework/migrations/003_core_system_data.sql`,
+`.framework/migrations/011_spine_system_account.sql`).
+
+## Step 5 — run it
+
+```bash
+npm run dev:netlify
+```
+
+`dev:netlify` runs `npm run assemble` first (via `predev:netlify`) and then
+`scripts/dev-netlify.sh`, which cleans stale processes and launches the pinned
+`netlify dev`. Netlify serves the site on **http://localhost:8888** and starts
+the Vite dev server on 3001 via `scripts/netlify-dev-wrapper.sh`.
+**Wait for the "Local dev server ready" banner** — the first `dev:netlify`
+run bundles ~80 functions and can take a couple of minutes before the banner
+appears; this is normal, not a hang. Early requests during function bundling
+can crash the dev server (noted in `scripts/dev-netlify.sh`).
+
+Ports are **fixed**: `netlify dev` must bind 8888 and Vite 3001 — both are
+set in manifest-protected files (`netlify.toml` `[dev]` port/targetPort,
+`config/vite.config.ts`), and there is no supported alternate-port
+configuration. Moving only one side breaks the `/api` proxy and can
+silently cross-connect two Spine projects on the same machine. Check the
+ports are free first (`lsof -i :8888 -i :3001`): `dev-netlify.sh` cleans up
+stale processes it owns but will not kill an unrelated server holding the
+port — a second Spine project's dev stack is the usual culprit; stop that
+one yourself.
+
+Ignore `Failed to fetch AI Gateway token … Unauthorized` in `netlify dev`
+output — that is the Netlify CLI's own AI feature probing your Netlify
+account, unrelated to Spine.
+
+Two URL spaces matter:
+
+- `/api/*` → `/.netlify/functions/:splat`. In dev this is the Vite proxy to
+  `localhost:8888` (`config/vite.config.ts`); in production it is the
+  `_redirects` rule in `.framework/public/_redirects`.
+- Everything else → the React SPA.
+
+`npm run dev` alone starts *only* Vite on 3001 — fine for frontend work, but
+`/api/*` calls still proxy to 8888, so functions need `netlify dev` running.
+
+## First admin — browser-free bootstrap (recommended for automation)
+
+```bash
+npx spine-framework bootstrap --email you@example.com --password '<pick-one>'
+```
+
+This is the scriptable path (`S-002`): it creates the first `system_admin`
+person bound to the `spine-system` account — the same row shape the
+`handle_new_auth_user` trigger writes on registration — creates a confirmed
+auth user through `auth.admin.createUser(email_confirm: true)`, and mints a
+`sk_` API key, all without a browser. The raw key is printed **once**; only
+its PBKDF2 hash is stored. `--scope <scope>` (repeatable) narrows the key —
+the default `*:*` resolves to the `system_admin` role on the machine
+principal. Omit `--email`/`--password` and the person record is created
+DB-only (no UI login; the minted key still works for `x-api-key` callers).
+The command is idempotent: when a `system_admin` already exists in
+`spine-system` it skips person creation and just mints another key
+(`.framework/cli/commands/bootstrap.ts`).
+
+## First login — what actually happens
+
+Alternatively, register in the browser. The real flow, as the code
+implements it:
+
+1. An unauthenticated visitor is redirected to `/login`
+   (`.framework/src/App.tsx`). If `VITE_SETUP_MODE=true` is set, the `/` route
+   instead shows a static `SetupPage` listing the same steps as this page
+   (`.framework/src/pages/SetupPage.tsx`).
+2. Go to `/register` and create an account. **The first user to register gets
+   `system_admin`**: the `handle_new_auth_user` database trigger detects an
+   empty `people` table and binds the new person to the `spine-system` account
+   with the `system_admin` role
+   (`.framework/migrations/052_registration_security.sql`). If the seeds are
+   missing, registration raises instead of creating a rootless user.
+3. Non-first, non-invited signups get **no account and no role** — placement
+   happens when `complete-registration` runs the server-side RPC
+   (`.framework/functions/invites.ts`). An authenticated user without an
+   account is routed to `/register?resume=1` until placement finishes, never
+   to a 404 (`.framework/src/App.tsx`).
+4. After login, a `system_admin` lands on `/spine-framework/admin` — the
+   schema-driven admin app from `.framework/src/apps/admin/index.tsx`. Other
+   users land on the first app their role can see, or `NoAppPage` when nothing
+   is routable.
+
+## Giving your agent access
+
+The verified path for letting an agent (or any machine caller) reach the
+runtime API:
+
+1. **Bootstrap an admin + key** — one step, no browser: `npx
+   spine-framework bootstrap` (see "First admin" above) both creates the
+   `system_admin` and prints a `sk_` key. The browser alternative: register
+   at `/register` (first user becomes `system_admin`), then create a scoped
+   key under **Admin → Configs → API Keys**. Either way the raw key is shown
+   **once** — copy it immediately (`.framework/functions/api-keys.ts`).
+2. **Give the key to the agent** as the environment variable `SPINE_API_KEY`.
+   Agents send `x-api-key: sk_…` on `/api/*` requests; the header resolves to
+   a machine principal carrying the key's scopes and account binding
+   (`.framework/functions/_shared/principal.ts`). Turnstile is not in this
+   path — bot protection only guards the human auth pages.
+
+**Caveat:** for the browser path, Supabase **email confirmation must be
+off** in the project (Auth → Providers), or the first registrant cannot sign
+in without access to a real inbox. `bootstrap` is unaffected — it creates
+the auth user with `email_confirm: true` through the service role.
+
+## Gaps
+
+- **`npx spine-framework dev` runs the same flow as the package scripts** —
+  `scripts/assemble.sh`, then Vite via `config/vite.config.ts` (`--netlify`
+  for the full `netlify dev` stack on :8888). `npm run dev` /
+  `npm run dev:netlify` remain the canonical entry points.
+- **`bootstrap` covers first-run provisioning only.** Subsequent admins are
+  added through the invite flow in the admin app (or another `bootstrap`
+  run, which skips person creation and only mints a new key).
+- **Timers only tick under the Netlify scheduler.** `trigger-scheduler` is a
+  scheduled function (`* * * * *` in `netlify.toml`); pipelines triggered by
+  timers do not run without it, and trigger dispatch additionally needs
+  `INTERNAL_INVOKE_SECRET` (see Step 2).

package/.framework/src/instructions/guide/02-project-map.md

@@ -0,0 +1,147 @@
+---
+title: Anatomy of an installed project
+audience: developers, agents
+kind: guide
+verified_against: f69c37d
+verified_on: 2026-10-29
+source_files:
+  - .framework/templates/project.json
+  - .framework/cli/commands/init.ts
+  - .framework/cli/commands/upgrade.ts
+  - .framework/cli/lib/project-files.ts
+  - scripts/checksum-manifest.mts
+  - scripts/verify-integrity.sh
+  - scripts/assemble.sh
+  - scripts/assemble-frontend.sh
+  - scripts/assemble-functions.sh
+  - config/vite.config.ts
+  - netlify.toml
+  - .framework/cli/commands/create-app.ts
+  - .framework/cli/commands/install-app.ts
+  - .framework/src/components/CustomAppLoader.tsx
+  - .framework/schemas/spine.config.schema.json
+---
+
+# Anatomy of an installed project
+
+A Spine project is two concentric layers: a **sealed framework layer** the
+package owns and overwrites on upgrade, and a **customer layer** the framework
+never writes to.
+
+```
+my-project/
+├─ .framework/            # SEALED — framework source, vendored by init/upgrade
+│  ├─ cli/                #   the spine-framework CLI source
+│  ├─ functions/          #   Netlify functions (the whole API surface)
+│  ├─ migrations/         #   SQL migrations applied by `migrate`
+│  ├─ public/             #   static assets + _redirects
+│  ├─ schemas/            #   spine.config.schema.json
+│  ├─ scripts/ seeds/ docs/ templates/
+│  ├─ src/                #   React frontend + admin app + this book
+│  └─ tests/
+├─ config/                # SEALED — build config (vite, tsconfig, tailwind…)
+├─ scripts/               # SEALED — assemble/verify/dev shell scripts
+├─ bin/                   # SEALED — spine-framework bin shims
+├─ custom/                # YOURS — apps, functions, components, migrations, tests
+├─ .assembled/            # GENERATED — build output, never edit
+├─ .spine-manifest.json   # GENERATED — frozen integrity manifest
+├─ spine.config.json      # YOURS — branding + registration policy
+├─ netlify.toml           # mixed — framework blocks + your custom_* sections
+├─ package.json           # merged — framework scripts/deps + your own
+└─ .env                   # YOURS — secrets; never written by the framework
+```
+
+## The sealed layer
+
+The file set is declared in `.framework/templates/project.json`
+(`framework_dirs`, `framework_files`, `config_files`, `root_scripts`, `bin`)
+and every protected file's sha256 is recorded in `.spine-manifest.json` — the
+protected trees are `.framework`, `config`, `scripts`, and `bin`
+(`scripts/checksum-manifest.mts`, `PROTECTED_DIRS`).
+
+- `npm run verify` (`scripts/verify-integrity.sh` → `scripts/verify-manifest.mts`)
+  re-hashes the tree and fails on drift. `SPINE_INTEGRITY=warn` downgrades to
+  warnings.
+- `npx spine-framework upgrade` re-syncs the sealed layer to the
+  `spine-framework` version installed in `node_modules`
+  (`.framework/cli/commands/upgrade.ts`). It first verifies the tree against
+  the manifest and **aborts on any locally modified or missing protected file**
+  unless `--force` is passed — so do not edit `.framework/`, `config/`,
+  `scripts/`, or `bin/`; changes there are destroyed on the next upgrade
+  anyway.
+- Deletions on upgrade are confined to `.framework/`; sealed files dropped
+  upstream outside it are left in place with a warning.
+
+## `custom/` — your code
+
+`init` creates `custom/apps`, `custom/functions`, `custom/components`,
+`custom/migrations`, and `custom/tests` (`.framework/cli/commands/init.ts`).
+Everything in it is yours: not integrity-tracked, never touched by upgrade.
+
+- **Custom apps** live at `custom/apps/<slug>/`.
+  `npx spine-framework create-app <slug>` scaffolds `manifest.json`,
+  `index.tsx`, and `components/`, then inserts the `apps` row with
+  `renderer: 'custom'` (`.framework/cli/commands/create-app.ts`).
+  `CustomAppLoader` resolves the UI via
+  `import.meta.glob('../../../custom/apps/*/index.tsx')`
+  (`.framework/src/components/CustomAppLoader.tsx`), and the Vite alias
+  `@custom` points at `custom/apps` (`config/vite.config.ts`).
+- **Custom functions** live at `custom/functions/` or inside an app at
+  `custom/apps/<slug>/functions/`; assembly merges them into the flat
+  functions directory and hard-fails on basename collisions with framework
+  functions (`scripts/assemble-functions.sh`). Name yours `custom_*`.
+- **Custom migrations** in `custom/migrations/` run with
+  `npx spine-framework migrate` (skip them with `--framework-only`).
+- **Packaged apps** installed via `npx spine-framework install-app <pkg>` also
+  land under `custom/apps/<slug>/`; their `manifest.json` can seed types,
+  roles, pipelines, and registration policy into the database
+  (`.framework/cli/commands/install-app.ts`).
+
+## `.assembled/` — build output
+
+`npm run assemble` (`scripts/assemble.sh`) produces `.assembled/` fresh on
+every dev start and build:
+
+- `.assembled/src` — the framework frontend plus each `custom/apps/<slug>/`
+  copied verbatim (never basename-flattened), plus the fixed-up `index.html`
+  (`scripts/assemble-frontend.sh`). Vite builds and serves from here.
+- `.assembled/netlify/functions` — framework + custom functions flattened into
+  the single directory Netlify requires (`netlify.toml`
+  `functions.directory`); duplicate basenames are a hard error, not a
+  last-wins overwrite (`scripts/assemble-functions.sh`).
+
+Never edit `.assembled/` — it is regenerated and deleted freely.
+
+## `.spine-manifest.json` — the integrity contract
+
+Written by `init` and regenerated by `upgrade`
+(`.framework/cli/lib/project-files.ts` → `writeFrozenManifest`): the package
+version (`framework_version`), the framework-owned dependency list, a tree
+digest, and a sha256 per protected file. It is the input to `npm run verify`
+and to upgrade's local-modification check.
+
+## `spine.config.json` — project runtime config
+
+Customer-owned; `init` seeds the neutral template
+(`.framework/templates/spine.config.neutral.json`) and
+`install-app`/`update-db-app` merge per-app registration policy into it
+(`.framework/cli/commands/install-app.ts`). It carries `branding` and the
+`registration` block that drives signup routing/role assignment — schema at
+`.framework/schemas/spine.config.schema.json`. Upgrade never writes it.
+
+## `netlify.toml` and `package.json` — mixed ownership
+
+- `netlify.toml`: framework blocks are rewritten on upgrade, but
+  `[functions."custom_*"]` sections are treated as app-owned and preserved
+  verbatim (`.framework/cli/lib/project-files.ts` → `splitNetlifyToml` /
+  `renderNetlifyToml`). Scheduled custom functions belong there.
+- `package.json`: framework-owned scripts and dependencies are merged in and
+  `spine-framework` pinned exactly; your own scripts and deps are preserved.
+  Upgrade removes a dependency only if the previous framework version owned it
+  and the new one does not.
+
+## `.env` — yours, always
+
+No framework command writes `.env`; it is gitignored and excluded from the
+file set (`.framework/templates/project.json` `exclude_globs`). `.env.example`
+ships as the documented baseline.