@everystack/mcp 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to `@everystack/mcp` are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.4.8] - 2026-09-07
+
+### Added
+
+- pull a published Task image instead of building it at deploy
+- auto-generated changelogs from conventional commits
+
+### Fixed
+
+- the task image no longer computes the fingerprint it is judged by
+
+### Documentation
+
+- the operator credential is the ops channel only
+- every db verb has a reference entry, and a test says so
+- the disclosed gap names what actually compiles, and a test pins it
+- the last two rollback-point sentences say what the code does; the retargeting edge is named
+
+## [0.4.7] - 2026-08-12
+
+### Fixed
+
+- the guidance taught a model that throws, and the config it replaced
+
+## [0.4.6] - 2026-08-05
+
+### Added
+
+- a cheat gate for stage-name-as-trust-boundary, and the sweep that found two more
+
+## [0.4.5] - 2026-08-05
+
+### Documentation
+
+- the debugging path for a 500 is the request id
+
+## [0.4.4] - 2026-08-01
+
+### Added
+
+- dbTask BYO-VPC support for external/public RDS (0.4.2)
+- scope dbTask SSM param under /sst/<app>/<stage>/ (0.4.3)
+- db:reconcile applies an authz-only change as a regrant, not a matview rebuild (0.4.34)
+- db:authz gets a local venue, and the published bin actually runs
+
+### Fixed
+
+- db:swap stops fighting its own backup, and its snapshot is now a fact
+- soft-delete visibility is declared, never inferred from a column name
+
+## [0.4.2] - 2026-07-23
+
+### Added
+
+- everystack://expo-server-deploy — the Expo Router server app deploy chapter, self-contained
+- db data-movement — restore→Fargate + delete the pg-tools layer
+- expose WAF/caching as an MCP resource — fix the 403-every-PostgREST trap
+
+### Fixed
+
+- deploy resource wires the backups path so db:backup isn't unreachable
+
+## [0.4.0] - 2026-07-10
+
+### Added
+
+- retire db/sql — descriptors are the single home (Brick B7, read-model-everywhere)
+- 0.4.0 guidance — descriptors, safe remote migration, and the real toolset
+
+## [0.3.3] - 2026-07-04
+
+### Fixed
+
+- the gates and generators teach the migration-authority workflow
+
+## [0.3.1] - 2026-07-02
+
+### Added
+
+- governance layer — grounding + cheat gates (0.3.0)
+- scaffold + reconcile the project CLAUDE.md
+- runbook prompt — drive the runbook compiler, fill slots only; cross-link in CLAUDE.md template
+
+## [0.2.2] - 2026-06-18
+
+### Added
+
+- add @everystack/mcp package, IAM docs, .mcp.json
+- start-static beginner flow, check_environment tools, beginner resources
+- S3 origin cache for processed images
+- dual-export OTA updates, SSR validation, eas.json env resolution
+
+### Fixed
+
+- fail closed on cookie auth without allowedOrigins
+
+### Documentation
+
+- scope the SST deploy IAM policy to the app's resources

package/dist/cli.md

@@ -37,11 +37,20 @@ these verbs move a database. Full operational guidance: everystack://database-op
 everystack db:sync            # Make a dev DB match your checkout — state + authz + compute, one verb
 everystack db:generate        # STATE layer (tables) → next migration file (--dry-run prints the SQL, writes nothing)
 everystack db:reconcile       # Deploy the compute layer only (views/matviews/functions/triggers)
+everystack db:refresh         # Refresh the declared matviews in dependency order, credential-free (--only, --verify-nonempty, --list)
 everystack db:check           # CI gate: declared state composes + generated artifacts match regeneration
 everystack db:fingerprint     # Content-address the live base schema vs the Models — MATCH/MISMATCH
 everystack db:diff            # The state edge between two declared states — no DB, CI-pure
+everystack db:build           # Build a database FROM the models and keep it (fresh target only; --database-url, never the env)
+everystack db:pull            # Introspect a live DB → render field() Models: THE on-ramp for an existing database
 ```
 
+**Bringing an existing database in** — `db:pull --stage <s> --abilities live --out db/models`, commit
+what it renders, then `db:plan --stage <s>`. An EMPTY plan means adopted as-is (that commit declares
+the database; every later `db:apply` descends from it). A NON-EMPTY plan is the hardening edge:
+review it, `db:apply` it — no commit declares the database yet, so the reviewed plan is the origin.
+Render from the stage, never from a local restore of a dump.
+
 **Authorization (the brownfield on-ramp + the red team)**
 ```bash
 everystack db:authz:pull      # Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
@@ -78,6 +87,21 @@ everystack db:backup:download <id> --stage X   # Presigned download URL (1h)
 everystack db:restore --from <id> --stage X --confirm   # Restore a backup INTO a stage (destructive)
 ```
 
+**Schema artifacts (build elsewhere, land atomically)**
+```bash
+everystack db:export --schema stats --stage X                      # ONE schema as a fingerprint-stamped .dump (+ .meta.json)
+everystack db:swap --schema stats --from <artifact> --stage X --direct --confirm   # fingerprint gate → confirmed snapshot → restore → one txn → verify; destructive
+```
+`db:swap`'s venue is explicit (`DATABASE_URL` in the env is refused; `--stage` needs `--direct`), and the
+rollback point is confirmed before the restore begins. Full guide: docs/schema-swap.md.
+
+**Roles & health**
+```bash
+everystack db:provision --stage X       # Create the least-privilege role chain (idempotent); --rotate swaps A/B credentials live
+everystack db:doctor --stage X          # Check the DB is least-privilege + RLS-subject (api vs operator connection)
+everystack db:reset --stage dev         # Drop all schemas + re-run migrations (dev only; migration-era apps)
+```
+
 **Local dev databases**
 ```bash
 everystack db:template:refresh          # Build the dev template from declared state + seed
@@ -88,6 +112,7 @@ everystack db:fork --from-stage src --stage tgt --confirm   # Fork a deployed st
 **Data**
 ```bash
 everystack db:seed --stage dev          # Declarative seed script (dev only; refuses on production)
+everystack db:exec fix.sql --stage X    # Credential-free DML-only write, one txn; ANY schema change rolls it back (--confirm on prod-tier)
 everystack db:backfill --apply          # One-shot data moves from db/backfills/*.sql (own record)
 everystack pipeline:run --stage X       # Ingest pipeline (credential-free in the ops Lambda)
 everystack db:migrate                   # Run the generated migration on a deployed stage via Lambda invoke

package/dist/core.md

@@ -104,7 +104,7 @@ const handler = createHandler(db, schema, {
   protectedFields: { profiles: ['role'] },      // Strip from writes
   rowOwnership: { posts: { column: 'authorId', userField: 'sub' } },
   hooks: { posts: { beforeCreate: async (body, user) => ({ ...body, authorId: user?.sub }) } },
-  softDelete: { column: 'deletedAt', tables: ['posts'] },
+  softDelete: { column: 'deletedAt', tables: ['posts'] },  // Models: derived, don't hand-write
   maxEmbedDepth: 3,
   maxLimit: 1000,
 });

package/dist/database-operations.md

@@ -133,11 +133,28 @@ the database URL**. `db:apply` verifies → applies → verifies, and **refuses*
 
 - **the live fingerprint still equals `plan.from`** (the concurrency lock — nobody changed
   the target since you minted the plan; if they did, re-mint), AND
+- **the schema's default privileges still hash to `plan.defaultAclHash`** (an
+  `ALTER DEFAULT PRIVILEGES` since minting changes what a created object lands with; the
+  refusal happens BEFORE dispatch, nothing lands — re-mint), AND
 - **your checkout descends from the commit that declares the target's state** (the
   fast-forward rule — "rebase first"; a stale checkout can't silently revert merged work).
+  When NO commit on any ref declares the live state — an existing database being hardened
+  in, or a stage hand-edited since its last apply — that is PROVEN drift over a full, current
+  clone, and it PASSES: the reviewed plan is the origin every later apply descends from,
+  recorded on the `schema_log` row. Shallow or behind-remote clones are UNVERIFIABLE and
+  refuse with a fetch runbook.
 
 Every refusal is recorded in `everystack.schema_log`. `--database-url` is local-dev-only;
-protected stages always go through `--stage`.
+protected stages always go through `--stage`. Every refusal is **staleness** (re-mint, never
+a flag) or **intent** (a named attestation, `--confirm`, an approver) — there is no `--force`.
+
+The plan's `to` is the FULL endpoint: it carries the grants of roles your models do not
+govern (a BI reader, an ETL role) through unchanged, so on a brownfield stage an empty plan
+prints `from == to` and still names those roles and the baseline that admitted them.
+
+**After upgrading the CLI, redeploy the stage before a staged apply.** `db:apply --stage`
+is a wire contract between the CLI and the ops Lambda; a version-skewed Lambda is refused
+before any write, with the redeploy named.
 
 ### 5. Destructive plans carry more gates
 
@@ -145,8 +162,15 @@ A plan is DESTRUCTIVE if it drops (table/column/type) or narrows a type (a lossy
 `SET DATA TYPE`). Those additionally require, all of them:
 
 - **`--confirm`** — always, explicitly.
-- **A snapshot** — taken automatically via `db:backup` when you pass `--stage` (or supply
-  one with `--snapshot-ref`). No snapshot, no destructive apply.
+- **A confirmed rollback point** — on a stage that exposes `databaseInstanceId`, a physical RDS
+  snapshot taken and waited to `available` before the write (the default); otherwise a logical
+  `db:backup` waited to completion; or one you attest with `--snapshot-ref <id>`. No rollback
+  point, no destructive apply.
+- **The `--direct` lane.** The ops-Lambda lane (`--stage X` alone) REFUSES destructive plans
+  outright. Run them `--stage X --direct`: the CLI resolves the stage's operator connection
+  from its ops Lambda, holds it in memory only (never on argv), and runs the full ceremony
+  on one real connection with an unbounded clock. `--database-url` is not the venue for a
+  deployed stage's destruction.
 - **The stage's approver set** — if declared, `db:apply` verifies the caller's AWS identity
   (STS) against it. Set it with `db:approvers`:
   ```bash
@@ -178,11 +202,13 @@ everystack db:backups   --stage production      # list logical backups
 everystack db:backup:download <id> --stage production   # presigned download URL (1h)
 ```
 
-**RDS snapshot first?** For a destructive apply, `db:apply` already forces a logical backup —
-you cannot destroy without one. But before any large or risky migration on a stage that
-holds real data, take a **physical `db:snapshot` first** as well: it is instant, it captures
-the whole instance, and restoring it is the fastest path back if something the plan didn't
-foresee goes wrong. Cheap insurance; take it.
+**RDS snapshot first?** A destructive `db:apply` confirms a rollback point BEFORE it writes: on
+a stage exposing `databaseInstanceId` that is a physical RDS snapshot waited to `available`
+(the default), otherwise a logical `db:backup` waited to completion, or one you attest with
+`--snapshot-ref <id>`. The only way to destroy without one is to say so on the record with
+`--snapshot none`. So a separate `db:snapshot` first is redundant on the default lane — take one
+before a large or risky migration only when the stage has no `databaseInstanceId`, or when you
+want a named restore point that outlives the apply.
 
 ## Importing data into a REMOTE stage
 
@@ -207,22 +233,30 @@ can't dump production. `--database-url` exists only for local dev databases you
 ## Command index
 
 ```bash
+# Bring an existing database in:
+everystack db:pull --stage X --abilities live --out db/models   # render field() Models from live; commit; then db:plan (EMPTY = adopted)
+
 # Declare (edit files), then:
 everystack db:sync            # dev DB ← your checkout (state + compute), one verb
 everystack db:reconcile       # compute layer only (views/matviews/functions/triggers)
+everystack db:refresh         # repopulate the declared matviews in dependency order (credential-free)
 everystack db:generate        # STATE layer → migration file / --apply / --dry-run
+everystack db:build --database-url "$FRESH"   # build a database FROM the models and keep it (empty target only)
 everystack db:check           # CI gate: declared state composes; artifacts match
 everystack db:fingerprint     # content-address live schema vs models — MATCH/MISMATCH
 
 # Reach a protected stage safely:
 everystack db:plan --stage X --out X.plan.json     # mint a reviewable edge (read-only)
 everystack db:apply --plan X.plan.json --stage X   # verify → apply → verify (credential-free)
+everystack db:apply --plan X.plan.json --stage X --direct --confirm   # a DESTRUCTIVE plan: the direct lane, full ceremony
 everystack db:approvers --stage X --set "…"        # who may run destructive applies
 
-# Back up / restore:
+# Back up / restore / move a schema:
 everystack db:snapshot --stage X    # physical RDS snapshot (instant DR)
 everystack db:backup   --stage X    # logical pg_dump → S3
 everystack db:restore --from <id> --stage X --confirm
+everystack db:export --schema stats --stage X                    # ONE schema as a fingerprint-stamped artifact
+everystack db:swap --schema stats --from <artifact> --stage X --direct --confirm   # land it atomically (destructive)
 
 # Local dev databases:
 everystack db:template:refresh      # build the dev template from declared state + seed
@@ -230,6 +264,7 @@ everystack db:branch                # per-branch dev DB from the template
 
 # Data:
 everystack db:seed --stage dev      # declarative seed (dev only)
+everystack db:exec fix.sql --stage X   # credential-free DML-only write, one txn (any schema change rolls it back)
 everystack db:backfill --apply      # one-shot data moves (db/backfills/*.sql)
 everystack pipeline:run --stage X   # ingest pipeline (credential-free)
 everystack db:fork --from-stage prod --stage feature --confirm   # copy a stage's data

package/dist/expo-server-deploy.md

@@ -254,8 +254,53 @@ Two requirements on the AWS side:
 - **Deploy IAM (`>= 0.4.3`):** dbTask writes its operator-URL SecureString to
   `/sst/<app>/<stage>/DbTaskOperatorUrl`, under the `parameter/sst/*` prefix an SST deploy role is
   already scoped to. A least-privilege deploy principal also needs ECS (cluster + task-def),
-  ECR (auth + repo push), EC2 `Describe*` (subnets/SGs), and `logs:CreateLogGroup` for the task's
-  log group. Override the param path with `paramName` to fit a different scoped prefix.
+  EC2 `Describe*` (subnets/SGs), and `logs:CreateLogGroup` for the task's log group. Override the
+  param path with `paramName` to fit a different scoped prefix. (ECR auth + repo push is needed
+  only with `build: true` — see below. The default pulls a published image and pushes nothing.)
+
+### The Task image — no Docker on the deploy machine
+
+`dbTask` pulls a **published, digest-pinned** image by default, so `everystack deploy` needs no
+Docker daemon. Earlier versions built the image locally on every deploy: a daemon that died
+mid-run took the deploy down *after* other resources had already changed.
+
+The image is a public GHCR package, so Fargate pulls it with no credential — nothing to rotate,
+and no registry token in your AWS account. It carries no secret; the operator URL still arrives at
+container start via ECS `secrets`/`valueFrom`.
+
+```typescript
+dbTask({ sst, aws }, 'DbTask', { vpc, adminDatabaseUrl, pgMajor: 16 });      // pulls, no Docker
+dbTask({ sst, aws }, 'DbTask', { …, build: true });                          // builds locally
+dbTask({ sst, aws }, 'DbTask', { …, image: 'my-mirror/db-task@sha256:…' });  // your own copy
+```
+
+- **`pgMajor` selects the image.** A major with no published image is REFUSED at deploy-plan time,
+  before any resource is created — it never silently falls back to a local build, because a silent
+  fallback is how the invisible Docker dependency came back.
+- **`build: true`** is the escape hatch for a custom entrypoint or an unpublished major. It needs a
+  Docker daemon, and it checks for one up front rather than failing at the build step.
+- **`image`** takes any reference verbatim: a mirror, an air-gapped copy, a digest you pinned.
+- **Pinned by digest, never by tag.** A tag can be repointed at different bytes after a deploy was
+  reviewed; `repo@sha256:…` is the same bytes forever.
+- **`architecture` costs nothing on the pull path.** The published image is a multi-arch manifest,
+  so the registry resolves arm64 vs x86_64 at pull time regardless of your machine. Only
+  `build: true` re-couples the image to the deploy machine's architecture.
+
+**The image is an appliance — it runs pg binaries, it does not compute policy.** A backup's
+fingerprint (what the destructive-apply gate compares against `plan.from`) is computed by the CLI,
+before and after the dump, and passed into the task. The task never computes one. A published,
+digest-pinned image that computed it would be running CLI internals frozen at publish time while
+your checkout moved on, and the skew would surface only when the gate trusted a fingerprint your
+CLI would have computed differently.
+
+Two consequences:
+
+- **`everystack db:backup` can now refuse.** If the schema changes during the dump, the artifact is
+  retracted — a dump spanning a migration matches neither endpoint, so it is not a safety net.
+  `db:fork` and `db:swap --snapshot logical` take the same path.
+- **Upgrade the CLI and the ops function together.** The ops action refuses a backup that arrives
+  with no fingerprint, so an older `@everystack/cli` against a newer deploy fails with a named
+  error telling you to upgrade. It does not silently write an unstamped artifact.
 
 **Keep `publicIp`, never `public: true`.** SST marks `publicIp` `@deprecated` in favor of `public`,
 but do NOT swap it here: `public: true` attaches an inbound security group open to `0.0.0.0/0` on

package/dist/handler-options.md

@@ -100,6 +100,7 @@ maxLimit: 1000,        // Max ?limit= value (default: 10000)
 ### Other
 ```typescript
 softDelete: { column: 'deletedAt', tables: ['posts'] },  // DELETE -> UPDATE SET deletedAt
+// ^ With Models this is DERIVED from each model's `softDelete: true` — do not hand-write it.
 naming: 'snake_case',  // Response key format ('camelCase' default)
 ```
 

package/dist/index.cjs

@@ -22411,9 +22411,12 @@ function registerDesignSchemaPrompt(server) {
                 "Declare each table with `defineModel`, following these conventions:",
                 "- UUID primary keys: `id: field.uuid().primaryKey().defaultRandom()`",
                 "- Timestamps: `createdAt: field.timestamptz().defaultNow().notNull()`",
-                "- Soft delete: a `deletedAt: field.timestamptz()` field PLUS `softDelete: true` \u2014 the flag is what",
-                "  excludes soft-deleted rows from public reads and the data API. The field alone does nothing:",
-                "  visibility is declared, never inferred from a column name",
+                "- Soft delete: a `deletedAt: field.timestamptz()` field PLUS `softDelete: true` \u2014 the field alone",
+                "  does nothing. The flag decides DURABILITY (true makes DELETE mark deleted_at instead of",
+                "  destroying the row, and hides marked rows from the data API) and, where there is a public",
+                "  read, VISIBILITY (deleted_at IS NULL in the anon policy). defineModel REFUSES to guess on any",
+                "  model with deletedAt that has a public read or can be deleted from, so it throws at import if",
+                "  you omit it. Never hand-write the handler softDelete config \u2014 it is derived from this flag",
                 "- Foreign keys via relations: `field.uuid().references(() => Author)` / `belongsTo`/`hasMany`",
                 "- Sensitive columns: `.private()` (hidden from the API); write-guarded: `.readonly()`",
                 "- Named exports (PascalCase model var, e.g. `export const Post = defineModel('posts', \u2026)`)",
@@ -23761,7 +23764,7 @@ async function runGovernanceCli(argv) {
 }
 
 // src/index.ts
-var version2 = (true ? "0.4.6" : null) ?? "0.3.0-dev";
+var version2 = (true ? "0.4.8" : null) ?? "0.3.0-dev";
 var INSTRUCTIONS = [
   "You govern how any agent builds everystack \u2014 a self-hosted application stack for Expo apps on AWS.",
   "Your job is not only to advise but to keep the build on-script: the architecture the maintainer",

package/dist/schema-patterns.md

@@ -34,6 +34,9 @@ export const Post = defineModel('posts', {
     updatedAt: field.timestamptz().notNull().defaultNow(),
     deletedAt: field.timestamptz(),
   },
+  // Required here, not optional: this model has a `deletedAt` field AND grants DELETE, so
+  // `defineModel` refuses to guess. See Soft Delete below for what each value means.
+  softDelete: true,
   abilities: [can('read'), can('create'), can('update'), can('delete')],
 });
 ```
@@ -59,11 +62,34 @@ updatedAt: field.timestamptz().notNull().defaultNow(),
 ```
 
 ### Soft Delete
-Add `deletedAt` for soft-deletable tables:
+The field alone does nothing. Declare BOTH — the column and what it means:
 ```typescript
 deletedAt: field.timestamptz(),
+softDelete: true,   // on the model, beside `fields` — NOT in the handler
 ```
-Configure in handler: `softDelete: { column: 'deletedAt', tables: ['posts'] }`.
+
+**`defineModel` REFUSES to guess** when a model has `deletedAt` and either a public read or a
+way to DELETE (`can('delete')`, `can('manage')` — which is "all actions" — or a `privileges`
+DELETE grant). Omit the line on such a model and it throws at import.
+
+It is declared because it changes two different things, and neither default is safe:
+
+- **Durability, on every model** — `true` makes a `DELETE` mark `deleted_at` instead of
+  removing the row, and then hides marked rows from the data API's reads and updates. `false`
+  makes `DELETE` permanent.
+- **Visibility, only where there is a public read** — `true` AND-s `deleted_at IS NULL` into
+  the anon policy. On an owner-scoped or admin-only model the compiled SQL is identical either
+  way, so the durability half is the one that matters there.
+
+Pick `true` if the row is meant to survive its own deletion — anything with a cleanup or purge
+job, an audit trail, or rows other tables reference. Pick `false` if `deleted_at` here is
+audit-only and a `DELETE` really should remove the row. Getting this wrong is not cosmetic: a
+table whose S3 cleanup job finds work by `deleted_at IS NOT NULL` orphans every file it should
+have purged if the row is hard-deleted instead.
+
+**Do not hand-write the handler's `softDelete: { column, tables }`.** With Models, the handler
+config is DERIVED from this flag (`deriveHandlerConfig`), so writing both is how the two drift
+apart — and a hand-written list silently losing a table is exactly how this bug shipped.
 
 ### Foreign Keys
 ```typescript
@@ -120,13 +146,37 @@ export const Post = defineModel('posts', {
   fields: { /* … */ },
   abilities: [
     can('read'),                              // anon + authenticated
-    can('create', { role: 'authenticated' }),
-    can('update', { role: 'authenticated', own: 'authorId' }),  // row ownership
-    can('delete', { role: 'admin' }),
+    can('create', { role: 'authenticated' }), // signed-in users insert rows THEY OWN — the model has an owner (below), so WITH CHECK (author_id = caller)
+    can('update', { owner: 'authorId' }),     // row ownership: only the author, via RLS
+    can('manage', { role: 'admin' }),         // the admin bypass: one ALL policy, true/true
   ],
 });
 ```
 
+**How a write compiles — read this before naming a role.** A write ability is a GRANT plus an
+RLS policy, and RLS is on for every model with abilities, so a grant with no policy is dead:
+an INSERT fails loudly (`new row violates row-level security policy`), while an UPDATE or
+DELETE with no policy affects **0 rows silently** — no error, nothing changes.
+
+- `owner:` / `via:` writes compile the owner-checked policy (`<t>_insert_own`, `_update_own`,
+  `_delete_own`) for `authenticated`. On such a model a bare `can('create')` or
+  `can('create', { role: 'authenticated' })` is ALSO the owner-checked insert — the example above.
+- `can('manage', { role: 'admin' })` is the admin bypass: one `ALL` policy, `true`/`true`.
+- **Known gap (cli 0.4.80):** a role-scoped or bare write with NO owner on the model and no
+  `where:` — `can('create', { role: 'authenticated' })` on an owner-less table, `can('delete',
+  { role: 'admin' })`, `can('manage', { role: 'editor' })` — compiles the grant and NO policy. It
+  reads as access and grants none. A vacuous `where: sql\`true\`` does NOT help: the compiler
+  discards a `true` predicate and still emits nothing. What compiles today: `owner:` / `via:`
+  for row-scoped writes; `can('manage', { role: 'admin' })` for the admin bypass; and, for
+  `authenticated` only, a real (non-vacuous) `where:` on a `create`/`update`/`delete`, which
+  compiles a predicate-only policy for `authenticated`. There is no in-model spelling for a
+  role-wide write by any other role — and do not try a `where:` on another role's write: the
+  write compiler never reads the declared role, so `can('update', { role: 'editor', where })`
+  grants editor and lands the predicate on the **`authenticated`** policy. Run that write on the
+  trusted admin connection until the write-policy matrix ships.
+- `check:` is the WITH CHECK half verbatim — it REPLACES the owner term, it does not narrow it —
+  so a `check:` on an owner model must carry the owner term itself.
+
 ## Handler Config for Schema
 
 The handler config is **derived** from the Models (`deriveHandlerConfig(models)`), so

package/dist/security.md

@@ -80,6 +80,56 @@ GRANT admin TO authenticator;
 
 Why `NOINHERIT`: authenticator has zero privileges. All access comes through the granted roles. This prevents accidental privilege leakage.
 
+### The Two Credential Channels
+
+There are exactly two database credentials, and they are not interchangeable.
+
+| | Role | Used by | Never |
+| --- | --- | --- | --- |
+| `DATABASE_URL` | `authenticator` (least privilege) | The app plane. Every request-serving read and write, always through `withRole` / `pgSettings`. | — |
+| `ADMIN_DATABASE_URL` | `migrator` (owns the schema) | The ops channel ONLY: migrate, seed, console, backup. | **Never held by request-serving code.** |
+
+**The rule: the operator credential is the ops channel only.** It owns the schema, so RLS
+does not apply to it. A request handler holding that credential has unrestricted database
+access, and every RLS policy you wrote is decoration. RLS is only fail-closed once the
+credentials are split — a single privileged URL means every policy fails *open*.
+
+This is the mistake to watch for, because it does not look like one. `createAdminDb()` and
+`getAdminSql()` are easy to reach from app code and will work. Working is exactly the
+problem: the failure is silent and total.
+
+#### Trusted writes: use a service role, not the operator credential
+
+Some writes legitimately need to bypass a user's RLS scope — issuing a credential at signup,
+recording a webhook, a background reconcile. **Do not reach for `ADMIN_DATABASE_URL`.** The
+lawful pattern is a NOLOGIN service role, granted to `authenticator`, entered through
+`withRole` *after* the handler has done its own authorization:
+
+```sql
+-- A NOLOGIN role with exactly the privileges the trusted lane needs, and no more.
+CREATE ROLE service NOLOGIN;
+GRANT service TO authenticator;
+
+GRANT SELECT, INSERT, UPDATE ON credentials TO service;
+-- Give it a policy, or leave the table RLS-enabled with a policy that admits `service`.
+```
+
+```typescript
+// The handler authorizes FIRST — the role is never derived from the token.
+if (!(await mayIssueCredential(user))) throw new HttpError(403);
+
+await withRole(sql, 'service', { sub: user.sub, role: 'service' }, async (tx) => {
+  await tx`INSERT INTO credentials ${tx(row)}`;
+});
+```
+
+Note that `roleFor()` returns only `anon` and `authenticated` — the roles a token may
+produce. `service` is never returned from a token, so a forged or absent JWT cannot reach it.
+Server code sets it explicitly, on the same least-privilege connection, after its own check.
+
+The result: the trusted lane is scoped to the privileges that lane actually needs, and it is
+still on the app plane. The operator credential stays in the ops channel where it belongs.
+
 ### Table Grants
 
 ```sql
@@ -260,6 +310,12 @@ RESET ROLE;
 - [ ] ENABLE + FORCE ROW LEVEL SECURITY on all public tables
 - [ ] Write RLS policies per table x role
 - [ ] Connect as `authenticator` (never use RDS master/superuser in production)
+- [ ] Split the credentials: `DATABASE_URL` = authenticator, `ADMIN_DATABASE_URL` = migrator
+- [ ] No request-serving code holds the operator credential — grep the server for
+      `createAdminDb` / `getAdminSql` and confirm every hit is an ops path (migrate, seed,
+      console, backup), not a request handler
+- [ ] Trusted writes go through a NOLOGIN service role via `withRole`, not the operator
+      credential
 - [ ] Test: SET ROLE authenticated; SELECT returns only expected rows
 - [ ] Test: a 500 returns only `error` and `requestId` — no relation or column names
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Governance layer that governs how any agent builds everystack — grounding, cheat gates, and Model-aware tooling over MCP",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -19,10 +19,12 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     }
@@ -40,9 +42,9 @@
     "tsx": "4.21.0",
     "typescript": "5.9.3",
     "zod": "3.25.67",
-    "@everystack/cli": "0.4.49",
-    "@everystack/model": "0.4.13",
-    "@everystack/server": "0.4.19"
+    "@everystack/cli": "0.4.80",
+    "@everystack/server": "0.4.30",
+    "@everystack/model": "0.4.17"
   },
   "scripts": {
     "test": "jest",

package/src/prompts/design-schema.ts

@@ -41,9 +41,12 @@ export function registerDesignSchemaPrompt(server: McpServer): void {
                 'Declare each table with `defineModel`, following these conventions:',
                 '- UUID primary keys: `id: field.uuid().primaryKey().defaultRandom()`',
                 '- Timestamps: `createdAt: field.timestamptz().defaultNow().notNull()`',
-                '- Soft delete: a `deletedAt: field.timestamptz()` field PLUS `softDelete: true` — the flag is what',
-                '  excludes soft-deleted rows from public reads and the data API. The field alone does nothing:',
-                '  visibility is declared, never inferred from a column name',
+                '- Soft delete: a `deletedAt: field.timestamptz()` field PLUS `softDelete: true` — the field alone',
+                '  does nothing. The flag decides DURABILITY (true makes DELETE mark deleted_at instead of',
+                '  destroying the row, and hides marked rows from the data API) and, where there is a public',
+                '  read, VISIBILITY (deleted_at IS NULL in the anon policy). defineModel REFUSES to guess on any',
+                '  model with deletedAt that has a public read or can be deleted from, so it throws at import if',
+                '  you omit it. Never hand-write the handler softDelete config — it is derived from this flag',
                 '- Foreign keys via relations: `field.uuid().references(() => Author)` / `belongsTo`/`hasMany`',
                 '- Sensitive columns: `.private()` (hidden from the API); write-guarded: `.readonly()`',
                 '- Named exports (PascalCase model var, e.g. `export const Post = defineModel(\'posts\', …)`)',

package/src/resources/cli.md

@@ -37,11 +37,20 @@ these verbs move a database. Full operational guidance: everystack://database-op
 everystack db:sync            # Make a dev DB match your checkout — state + authz + compute, one verb
 everystack db:generate        # STATE layer (tables) → next migration file (--dry-run prints the SQL, writes nothing)
 everystack db:reconcile       # Deploy the compute layer only (views/matviews/functions/triggers)
+everystack db:refresh         # Refresh the declared matviews in dependency order, credential-free (--only, --verify-nonempty, --list)
 everystack db:check           # CI gate: declared state composes + generated artifacts match regeneration
 everystack db:fingerprint     # Content-address the live base schema vs the Models — MATCH/MISMATCH
 everystack db:diff            # The state edge between two declared states — no DB, CI-pure
+everystack db:build           # Build a database FROM the models and keep it (fresh target only; --database-url, never the env)
+everystack db:pull            # Introspect a live DB → render field() Models: THE on-ramp for an existing database
 ```
 
+**Bringing an existing database in** — `db:pull --stage <s> --abilities live --out db/models`, commit
+what it renders, then `db:plan --stage <s>`. An EMPTY plan means adopted as-is (that commit declares
+the database; every later `db:apply` descends from it). A NON-EMPTY plan is the hardening edge:
+review it, `db:apply` it — no commit declares the database yet, so the reviewed plan is the origin.
+Render from the stage, never from a local restore of a dump.
+
 **Authorization (the brownfield on-ramp + the red team)**
 ```bash
 everystack db:authz:pull      # Introspect live authz (rls/grants/policies/secdef) → reviewable contract files
@@ -78,6 +87,21 @@ everystack db:backup:download <id> --stage X   # Presigned download URL (1h)
 everystack db:restore --from <id> --stage X --confirm   # Restore a backup INTO a stage (destructive)
 ```
 
+**Schema artifacts (build elsewhere, land atomically)**
+```bash
+everystack db:export --schema stats --stage X                      # ONE schema as a fingerprint-stamped .dump (+ .meta.json)
+everystack db:swap --schema stats --from <artifact> --stage X --direct --confirm   # fingerprint gate → confirmed snapshot → restore → one txn → verify; destructive
+```
+`db:swap`'s venue is explicit (`DATABASE_URL` in the env is refused; `--stage` needs `--direct`), and the
+rollback point is confirmed before the restore begins. Full guide: docs/schema-swap.md.
+
+**Roles & health**
+```bash
+everystack db:provision --stage X       # Create the least-privilege role chain (idempotent); --rotate swaps A/B credentials live
+everystack db:doctor --stage X          # Check the DB is least-privilege + RLS-subject (api vs operator connection)
+everystack db:reset --stage dev         # Drop all schemas + re-run migrations (dev only; migration-era apps)
+```
+
 **Local dev databases**
 ```bash
 everystack db:template:refresh          # Build the dev template from declared state + seed
@@ -88,6 +112,7 @@ everystack db:fork --from-stage src --stage tgt --confirm   # Fork a deployed st
 **Data**
 ```bash
 everystack db:seed --stage dev          # Declarative seed script (dev only; refuses on production)
+everystack db:exec fix.sql --stage X    # Credential-free DML-only write, one txn; ANY schema change rolls it back (--confirm on prod-tier)
 everystack db:backfill --apply          # One-shot data moves from db/backfills/*.sql (own record)
 everystack pipeline:run --stage X       # Ingest pipeline (credential-free in the ops Lambda)
 everystack db:migrate                   # Run the generated migration on a deployed stage via Lambda invoke

package/src/resources/core.md

@@ -104,7 +104,7 @@ const handler = createHandler(db, schema, {
   protectedFields: { profiles: ['role'] },      // Strip from writes
   rowOwnership: { posts: { column: 'authorId', userField: 'sub' } },
   hooks: { posts: { beforeCreate: async (body, user) => ({ ...body, authorId: user?.sub }) } },
-  softDelete: { column: 'deletedAt', tables: ['posts'] },
+  softDelete: { column: 'deletedAt', tables: ['posts'] },  // Models: derived, don't hand-write
   maxEmbedDepth: 3,
   maxLimit: 1000,
 });

package/src/resources/database-operations.md

@@ -133,11 +133,28 @@ the database URL**. `db:apply` verifies → applies → verifies, and **refuses*
 
 - **the live fingerprint still equals `plan.from`** (the concurrency lock — nobody changed
   the target since you minted the plan; if they did, re-mint), AND
+- **the schema's default privileges still hash to `plan.defaultAclHash`** (an
+  `ALTER DEFAULT PRIVILEGES` since minting changes what a created object lands with; the
+  refusal happens BEFORE dispatch, nothing lands — re-mint), AND
 - **your checkout descends from the commit that declares the target's state** (the
   fast-forward rule — "rebase first"; a stale checkout can't silently revert merged work).
+  When NO commit on any ref declares the live state — an existing database being hardened
+  in, or a stage hand-edited since its last apply — that is PROVEN drift over a full, current
+  clone, and it PASSES: the reviewed plan is the origin every later apply descends from,
+  recorded on the `schema_log` row. Shallow or behind-remote clones are UNVERIFIABLE and
+  refuse with a fetch runbook.
 
 Every refusal is recorded in `everystack.schema_log`. `--database-url` is local-dev-only;
-protected stages always go through `--stage`.
+protected stages always go through `--stage`. Every refusal is **staleness** (re-mint, never
+a flag) or **intent** (a named attestation, `--confirm`, an approver) — there is no `--force`.
+
+The plan's `to` is the FULL endpoint: it carries the grants of roles your models do not
+govern (a BI reader, an ETL role) through unchanged, so on a brownfield stage an empty plan
+prints `from == to` and still names those roles and the baseline that admitted them.
+
+**After upgrading the CLI, redeploy the stage before a staged apply.** `db:apply --stage`
+is a wire contract between the CLI and the ops Lambda; a version-skewed Lambda is refused
+before any write, with the redeploy named.
 
 ### 5. Destructive plans carry more gates
 
@@ -145,8 +162,15 @@ A plan is DESTRUCTIVE if it drops (table/column/type) or narrows a type (a lossy
 `SET DATA TYPE`). Those additionally require, all of them:
 
 - **`--confirm`** — always, explicitly.
-- **A snapshot** — taken automatically via `db:backup` when you pass `--stage` (or supply
-  one with `--snapshot-ref`). No snapshot, no destructive apply.
+- **A confirmed rollback point** — on a stage that exposes `databaseInstanceId`, a physical RDS
+  snapshot taken and waited to `available` before the write (the default); otherwise a logical
+  `db:backup` waited to completion; or one you attest with `--snapshot-ref <id>`. No rollback
+  point, no destructive apply.
+- **The `--direct` lane.** The ops-Lambda lane (`--stage X` alone) REFUSES destructive plans
+  outright. Run them `--stage X --direct`: the CLI resolves the stage's operator connection
+  from its ops Lambda, holds it in memory only (never on argv), and runs the full ceremony
+  on one real connection with an unbounded clock. `--database-url` is not the venue for a
+  deployed stage's destruction.
 - **The stage's approver set** — if declared, `db:apply` verifies the caller's AWS identity
   (STS) against it. Set it with `db:approvers`:
   ```bash
@@ -178,11 +202,13 @@ everystack db:backups   --stage production      # list logical backups
 everystack db:backup:download <id> --stage production   # presigned download URL (1h)
 ```
 
-**RDS snapshot first?** For a destructive apply, `db:apply` already forces a logical backup —
-you cannot destroy without one. But before any large or risky migration on a stage that
-holds real data, take a **physical `db:snapshot` first** as well: it is instant, it captures
-the whole instance, and restoring it is the fastest path back if something the plan didn't
-foresee goes wrong. Cheap insurance; take it.
+**RDS snapshot first?** A destructive `db:apply` confirms a rollback point BEFORE it writes: on
+a stage exposing `databaseInstanceId` that is a physical RDS snapshot waited to `available`
+(the default), otherwise a logical `db:backup` waited to completion, or one you attest with
+`--snapshot-ref <id>`. The only way to destroy without one is to say so on the record with
+`--snapshot none`. So a separate `db:snapshot` first is redundant on the default lane — take one
+before a large or risky migration only when the stage has no `databaseInstanceId`, or when you
+want a named restore point that outlives the apply.
 
 ## Importing data into a REMOTE stage
 
@@ -207,22 +233,30 @@ can't dump production. `--database-url` exists only for local dev databases you
 ## Command index
 
 ```bash
+# Bring an existing database in:
+everystack db:pull --stage X --abilities live --out db/models   # render field() Models from live; commit; then db:plan (EMPTY = adopted)
+
 # Declare (edit files), then:
 everystack db:sync            # dev DB ← your checkout (state + compute), one verb
 everystack db:reconcile       # compute layer only (views/matviews/functions/triggers)
+everystack db:refresh         # repopulate the declared matviews in dependency order (credential-free)
 everystack db:generate        # STATE layer → migration file / --apply / --dry-run
+everystack db:build --database-url "$FRESH"   # build a database FROM the models and keep it (empty target only)
 everystack db:check           # CI gate: declared state composes; artifacts match
 everystack db:fingerprint     # content-address live schema vs models — MATCH/MISMATCH
 
 # Reach a protected stage safely:
 everystack db:plan --stage X --out X.plan.json     # mint a reviewable edge (read-only)
 everystack db:apply --plan X.plan.json --stage X   # verify → apply → verify (credential-free)
+everystack db:apply --plan X.plan.json --stage X --direct --confirm   # a DESTRUCTIVE plan: the direct lane, full ceremony
 everystack db:approvers --stage X --set "…"        # who may run destructive applies
 
-# Back up / restore:
+# Back up / restore / move a schema:
 everystack db:snapshot --stage X    # physical RDS snapshot (instant DR)
 everystack db:backup   --stage X    # logical pg_dump → S3
 everystack db:restore --from <id> --stage X --confirm
+everystack db:export --schema stats --stage X                    # ONE schema as a fingerprint-stamped artifact
+everystack db:swap --schema stats --from <artifact> --stage X --direct --confirm   # land it atomically (destructive)
 
 # Local dev databases:
 everystack db:template:refresh      # build the dev template from declared state + seed
@@ -230,6 +264,7 @@ everystack db:branch                # per-branch dev DB from the template
 
 # Data:
 everystack db:seed --stage dev      # declarative seed (dev only)
+everystack db:exec fix.sql --stage X   # credential-free DML-only write, one txn (any schema change rolls it back)
 everystack db:backfill --apply      # one-shot data moves (db/backfills/*.sql)
 everystack pipeline:run --stage X   # ingest pipeline (credential-free)
 everystack db:fork --from-stage prod --stage feature --confirm   # copy a stage's data

package/src/resources/expo-server-deploy.md

@@ -254,8 +254,53 @@ Two requirements on the AWS side:
 - **Deploy IAM (`>= 0.4.3`):** dbTask writes its operator-URL SecureString to
   `/sst/<app>/<stage>/DbTaskOperatorUrl`, under the `parameter/sst/*` prefix an SST deploy role is
   already scoped to. A least-privilege deploy principal also needs ECS (cluster + task-def),
-  ECR (auth + repo push), EC2 `Describe*` (subnets/SGs), and `logs:CreateLogGroup` for the task's
-  log group. Override the param path with `paramName` to fit a different scoped prefix.
+  EC2 `Describe*` (subnets/SGs), and `logs:CreateLogGroup` for the task's log group. Override the
+  param path with `paramName` to fit a different scoped prefix. (ECR auth + repo push is needed
+  only with `build: true` — see below. The default pulls a published image and pushes nothing.)
+
+### The Task image — no Docker on the deploy machine
+
+`dbTask` pulls a **published, digest-pinned** image by default, so `everystack deploy` needs no
+Docker daemon. Earlier versions built the image locally on every deploy: a daemon that died
+mid-run took the deploy down *after* other resources had already changed.
+
+The image is a public GHCR package, so Fargate pulls it with no credential — nothing to rotate,
+and no registry token in your AWS account. It carries no secret; the operator URL still arrives at
+container start via ECS `secrets`/`valueFrom`.
+
+```typescript
+dbTask({ sst, aws }, 'DbTask', { vpc, adminDatabaseUrl, pgMajor: 16 });      // pulls, no Docker
+dbTask({ sst, aws }, 'DbTask', { …, build: true });                          // builds locally
+dbTask({ sst, aws }, 'DbTask', { …, image: 'my-mirror/db-task@sha256:…' });  // your own copy
+```
+
+- **`pgMajor` selects the image.** A major with no published image is REFUSED at deploy-plan time,
+  before any resource is created — it never silently falls back to a local build, because a silent
+  fallback is how the invisible Docker dependency came back.
+- **`build: true`** is the escape hatch for a custom entrypoint or an unpublished major. It needs a
+  Docker daemon, and it checks for one up front rather than failing at the build step.
+- **`image`** takes any reference verbatim: a mirror, an air-gapped copy, a digest you pinned.
+- **Pinned by digest, never by tag.** A tag can be repointed at different bytes after a deploy was
+  reviewed; `repo@sha256:…` is the same bytes forever.
+- **`architecture` costs nothing on the pull path.** The published image is a multi-arch manifest,
+  so the registry resolves arm64 vs x86_64 at pull time regardless of your machine. Only
+  `build: true` re-couples the image to the deploy machine's architecture.
+
+**The image is an appliance — it runs pg binaries, it does not compute policy.** A backup's
+fingerprint (what the destructive-apply gate compares against `plan.from`) is computed by the CLI,
+before and after the dump, and passed into the task. The task never computes one. A published,
+digest-pinned image that computed it would be running CLI internals frozen at publish time while
+your checkout moved on, and the skew would surface only when the gate trusted a fingerprint your
+CLI would have computed differently.
+
+Two consequences:
+
+- **`everystack db:backup` can now refuse.** If the schema changes during the dump, the artifact is
+  retracted — a dump spanning a migration matches neither endpoint, so it is not a safety net.
+  `db:fork` and `db:swap --snapshot logical` take the same path.
+- **Upgrade the CLI and the ops function together.** The ops action refuses a backup that arrives
+  with no fingerprint, so an older `@everystack/cli` against a newer deploy fails with a named
+  error telling you to upgrade. It does not silently write an unstamped artifact.
 
 **Keep `publicIp`, never `public: true`.** SST marks `publicIp` `@deprecated` in favor of `public`,
 but do NOT swap it here: `public: true` attaches an inbound security group open to `0.0.0.0/0` on

package/src/resources/handler-options.md

@@ -100,6 +100,7 @@ maxLimit: 1000,        // Max ?limit= value (default: 10000)
 ### Other
 ```typescript
 softDelete: { column: 'deletedAt', tables: ['posts'] },  // DELETE -> UPDATE SET deletedAt
+// ^ With Models this is DERIVED from each model's `softDelete: true` — do not hand-write it.
 naming: 'snake_case',  // Response key format ('camelCase' default)
 ```
 

package/src/resources/schema-patterns.md

@@ -34,6 +34,9 @@ export const Post = defineModel('posts', {
     updatedAt: field.timestamptz().notNull().defaultNow(),
     deletedAt: field.timestamptz(),
   },
+  // Required here, not optional: this model has a `deletedAt` field AND grants DELETE, so
+  // `defineModel` refuses to guess. See Soft Delete below for what each value means.
+  softDelete: true,
   abilities: [can('read'), can('create'), can('update'), can('delete')],
 });
 ```
@@ -59,11 +62,34 @@ updatedAt: field.timestamptz().notNull().defaultNow(),
 ```
 
 ### Soft Delete
-Add `deletedAt` for soft-deletable tables:
+The field alone does nothing. Declare BOTH — the column and what it means:
 ```typescript
 deletedAt: field.timestamptz(),
+softDelete: true,   // on the model, beside `fields` — NOT in the handler
 ```
-Configure in handler: `softDelete: { column: 'deletedAt', tables: ['posts'] }`.
+
+**`defineModel` REFUSES to guess** when a model has `deletedAt` and either a public read or a
+way to DELETE (`can('delete')`, `can('manage')` — which is "all actions" — or a `privileges`
+DELETE grant). Omit the line on such a model and it throws at import.
+
+It is declared because it changes two different things, and neither default is safe:
+
+- **Durability, on every model** — `true` makes a `DELETE` mark `deleted_at` instead of
+  removing the row, and then hides marked rows from the data API's reads and updates. `false`
+  makes `DELETE` permanent.
+- **Visibility, only where there is a public read** — `true` AND-s `deleted_at IS NULL` into
+  the anon policy. On an owner-scoped or admin-only model the compiled SQL is identical either
+  way, so the durability half is the one that matters there.
+
+Pick `true` if the row is meant to survive its own deletion — anything with a cleanup or purge
+job, an audit trail, or rows other tables reference. Pick `false` if `deleted_at` here is
+audit-only and a `DELETE` really should remove the row. Getting this wrong is not cosmetic: a
+table whose S3 cleanup job finds work by `deleted_at IS NOT NULL` orphans every file it should
+have purged if the row is hard-deleted instead.
+
+**Do not hand-write the handler's `softDelete: { column, tables }`.** With Models, the handler
+config is DERIVED from this flag (`deriveHandlerConfig`), so writing both is how the two drift
+apart — and a hand-written list silently losing a table is exactly how this bug shipped.
 
 ### Foreign Keys
 ```typescript
@@ -120,13 +146,37 @@ export const Post = defineModel('posts', {
   fields: { /* … */ },
   abilities: [
     can('read'),                              // anon + authenticated
-    can('create', { role: 'authenticated' }),
-    can('update', { role: 'authenticated', own: 'authorId' }),  // row ownership
-    can('delete', { role: 'admin' }),
+    can('create', { role: 'authenticated' }), // signed-in users insert rows THEY OWN — the model has an owner (below), so WITH CHECK (author_id = caller)
+    can('update', { owner: 'authorId' }),     // row ownership: only the author, via RLS
+    can('manage', { role: 'admin' }),         // the admin bypass: one ALL policy, true/true
   ],
 });
 ```
 
+**How a write compiles — read this before naming a role.** A write ability is a GRANT plus an
+RLS policy, and RLS is on for every model with abilities, so a grant with no policy is dead:
+an INSERT fails loudly (`new row violates row-level security policy`), while an UPDATE or
+DELETE with no policy affects **0 rows silently** — no error, nothing changes.
+
+- `owner:` / `via:` writes compile the owner-checked policy (`<t>_insert_own`, `_update_own`,
+  `_delete_own`) for `authenticated`. On such a model a bare `can('create')` or
+  `can('create', { role: 'authenticated' })` is ALSO the owner-checked insert — the example above.
+- `can('manage', { role: 'admin' })` is the admin bypass: one `ALL` policy, `true`/`true`.
+- **Known gap (cli 0.4.80):** a role-scoped or bare write with NO owner on the model and no
+  `where:` — `can('create', { role: 'authenticated' })` on an owner-less table, `can('delete',
+  { role: 'admin' })`, `can('manage', { role: 'editor' })` — compiles the grant and NO policy. It
+  reads as access and grants none. A vacuous `where: sql\`true\`` does NOT help: the compiler
+  discards a `true` predicate and still emits nothing. What compiles today: `owner:` / `via:`
+  for row-scoped writes; `can('manage', { role: 'admin' })` for the admin bypass; and, for
+  `authenticated` only, a real (non-vacuous) `where:` on a `create`/`update`/`delete`, which
+  compiles a predicate-only policy for `authenticated`. There is no in-model spelling for a
+  role-wide write by any other role — and do not try a `where:` on another role's write: the
+  write compiler never reads the declared role, so `can('update', { role: 'editor', where })`
+  grants editor and lands the predicate on the **`authenticated`** policy. Run that write on the
+  trusted admin connection until the write-policy matrix ships.
+- `check:` is the WITH CHECK half verbatim — it REPLACES the owner term, it does not narrow it —
+  so a `check:` on an owner model must carry the owner term itself.
+
 ## Handler Config for Schema
 
 The handler config is **derived** from the Models (`deriveHandlerConfig(models)`), so

package/src/resources/security.md

@@ -80,6 +80,56 @@ GRANT admin TO authenticator;
 
 Why `NOINHERIT`: authenticator has zero privileges. All access comes through the granted roles. This prevents accidental privilege leakage.
 
+### The Two Credential Channels
+
+There are exactly two database credentials, and they are not interchangeable.
+
+| | Role | Used by | Never |
+| --- | --- | --- | --- |
+| `DATABASE_URL` | `authenticator` (least privilege) | The app plane. Every request-serving read and write, always through `withRole` / `pgSettings`. | — |
+| `ADMIN_DATABASE_URL` | `migrator` (owns the schema) | The ops channel ONLY: migrate, seed, console, backup. | **Never held by request-serving code.** |
+
+**The rule: the operator credential is the ops channel only.** It owns the schema, so RLS
+does not apply to it. A request handler holding that credential has unrestricted database
+access, and every RLS policy you wrote is decoration. RLS is only fail-closed once the
+credentials are split — a single privileged URL means every policy fails *open*.
+
+This is the mistake to watch for, because it does not look like one. `createAdminDb()` and
+`getAdminSql()` are easy to reach from app code and will work. Working is exactly the
+problem: the failure is silent and total.
+
+#### Trusted writes: use a service role, not the operator credential
+
+Some writes legitimately need to bypass a user's RLS scope — issuing a credential at signup,
+recording a webhook, a background reconcile. **Do not reach for `ADMIN_DATABASE_URL`.** The
+lawful pattern is a NOLOGIN service role, granted to `authenticator`, entered through
+`withRole` *after* the handler has done its own authorization:
+
+```sql
+-- A NOLOGIN role with exactly the privileges the trusted lane needs, and no more.
+CREATE ROLE service NOLOGIN;
+GRANT service TO authenticator;
+
+GRANT SELECT, INSERT, UPDATE ON credentials TO service;
+-- Give it a policy, or leave the table RLS-enabled with a policy that admits `service`.
+```
+
+```typescript
+// The handler authorizes FIRST — the role is never derived from the token.
+if (!(await mayIssueCredential(user))) throw new HttpError(403);
+
+await withRole(sql, 'service', { sub: user.sub, role: 'service' }, async (tx) => {
+  await tx`INSERT INTO credentials ${tx(row)}`;
+});
+```
+
+Note that `roleFor()` returns only `anon` and `authenticated` — the roles a token may
+produce. `service` is never returned from a token, so a forged or absent JWT cannot reach it.
+Server code sets it explicitly, on the same least-privilege connection, after its own check.
+
+The result: the trusted lane is scoped to the privileges that lane actually needs, and it is
+still on the app plane. The operator credential stays in the ops channel where it belongs.
+
 ### Table Grants
 
 ```sql
@@ -260,6 +310,12 @@ RESET ROLE;
 - [ ] ENABLE + FORCE ROW LEVEL SECURITY on all public tables
 - [ ] Write RLS policies per table x role
 - [ ] Connect as `authenticator` (never use RDS master/superuser in production)
+- [ ] Split the credentials: `DATABASE_URL` = authenticator, `ADMIN_DATABASE_URL` = migrator
+- [ ] No request-serving code holds the operator credential — grep the server for
+      `createAdminDb` / `getAdminSql` and confirm every hit is an ops path (migrate, seed,
+      console, backup), not a request handler
+- [ ] Trusted writes go through a NOLOGIN service role via `withRole`, not the operator
+      credential
 - [ ] Test: SET ROLE authenticated; SELECT returns only expected rows
 - [ ] Test: a 500 returns only `error` and `requestId` — no relation or column names