@everystack/mcp 0.3.2 → 0.3.3

package/dist/tools/schema-analyze.js

@@ -0,0 +1,336 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Extract a brace-balanced block starting from an opening brace.
+ */
+function extractBraceBlock(source, openIndex) {
+    let depth = 0;
+    for (let i = openIndex; i < source.length; i++) {
+        if (source[i] === '{')
+            depth++;
+        if (source[i] === '}')
+            depth--;
+        if (depth === 0)
+            return source.slice(openIndex + 1, i);
+    }
+    return source.slice(openIndex + 1);
+}
+/**
+ * Parse pgTable declarations from a TypeScript source file.
+ * Uses regex + brace-depth extraction to handle nested objects (e.g., { withTimezone: true }).
+ */
+function parseTables(source, file) {
+    const tables = [];
+    // Find each pgTable declaration
+    const headerRegex = /export\s+const\s+(\w+)\s*=\s*pgTable\(\s*['"]([^'"]+)['"]\s*,\s*\{/g;
+    let match;
+    while ((match = headerRegex.exec(source)) !== null) {
+        const exportName = match[1];
+        const dbName = match[2];
+        // The opening brace position is at the end of the match minus 1
+        const openBrace = match.index + match[0].length - 1;
+        const columnsBlock = extractBraceBlock(source, openBrace);
+        const columns = parseColumns(columnsBlock);
+        tables.push({ name: dbName, exportName, columns, file });
+    }
+    return tables;
+}
+function parseColumns(block) {
+    const columns = [];
+    // Match: columnName: type('db_name', ...optional args...)...chain...
+    // The type call may have extra args after the string (e.g., timestamp('x', { withTimezone: true }))
+    const colRegex = /(\w+)\s*:\s*(\w+)\(\s*['"]([^'"]+)['"][^)]*\)([\s\S]*?)(?=\n\s*\w+\s*:|$)/g;
+    let match;
+    while ((match = colRegex.exec(block)) !== null) {
+        const name = match[1];
+        const type = match[2];
+        const dbName = match[3];
+        const rest = match[4];
+        const modifiers = [];
+        if (rest.includes('.primaryKey()'))
+            modifiers.push('primaryKey');
+        if (rest.includes('.notNull()'))
+            modifiers.push('notNull');
+        if (rest.includes('.unique()'))
+            modifiers.push('unique');
+        if (rest.includes('.defaultNow()'))
+            modifiers.push('defaultNow');
+        if (rest.includes('.defaultRandom()'))
+            modifiers.push('defaultRandom');
+        if (rest.includes('.default('))
+            modifiers.push('default');
+        if (rest.includes('.references('))
+            modifiers.push('references');
+        columns.push({ name, dbName, type, modifiers });
+    }
+    return columns;
+}
+/**
+ * Parse relations() declarations from source.
+ */
+function parseRelations(source) {
+    const relations = [];
+    // Match: export const nameRelations = relations(tableName, ({ one, many }) => ({
+    const relBlockRegex = /export\s+const\s+\w+\s*=\s*relations\(\s*(\w+)\s*,\s*\(\s*\{[^}]*\}\s*\)\s*=>\s*\(\{([\s\S]*?)\}\)\s*\)/g;
+    let blockMatch;
+    while ((blockMatch = relBlockRegex.exec(source)) !== null) {
+        const table = blockMatch[1];
+        const body = blockMatch[2];
+        // Match individual relations: name: one(target, { fields: [...], references: [...] })
+        const relRegex = /(\w+)\s*:\s*(one|many)\(\s*(\w+)(?:\s*,\s*\{([^}]*)\})?\s*\)/g;
+        let relMatch;
+        while ((relMatch = relRegex.exec(body)) !== null) {
+            const name = relMatch[1];
+            const type = relMatch[2];
+            const target = relMatch[3];
+            const opts = relMatch[4] || '';
+            const fields = [];
+            const references = [];
+            // Parse fields: [table.column]
+            const fieldsMatch = opts.match(/fields:\s*\[([^\]]+)\]/);
+            if (fieldsMatch) {
+                fields.push(...fieldsMatch[1].split(',').map((f) => f.trim().replace(/.*\./, '')));
+            }
+            const refsMatch = opts.match(/references:\s*\[([^\]]+)\]/);
+            if (refsMatch) {
+                references.push(...refsMatch[1].split(',').map((r) => r.trim().replace(/.*\./, '')));
+            }
+            const nameMatch = opts.match(/relationName:\s*['"]([^'"]+)['"]/);
+            relations.push({
+                name,
+                table: target,
+                type,
+                fields,
+                references,
+                ...(nameMatch ? { relationName: nameMatch[1] } : {}),
+            });
+        }
+    }
+    return relations;
+}
+/**
+ * Parse handler configuration from the server handler/plugin file.
+ */
+function parseHandlerConfig(source) {
+    const config = {};
+    // exposedTables
+    const exposedMatch = source.match(/exposedTables:\s*\[([\s\S]*?)\]/);
+    if (exposedMatch) {
+        config.exposedTables = exposedMatch[1]
+            .match(/['"]([^'"]+)['"]/g)
+            ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+    }
+    // hiddenColumns
+    const hiddenMatch = source.match(/hiddenColumns:\s*\{([\s\S]*?)\}/);
+    if (hiddenMatch) {
+        config.hiddenColumns = {};
+        const entries = hiddenMatch[1].matchAll(/(\w+):\s*\[([\s\S]*?)\]/g);
+        for (const entry of entries) {
+            config.hiddenColumns[entry[1]] = entry[2]
+                .match(/['"]([^'"]+)['"]/g)
+                ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+        }
+    }
+    // protectedFields
+    const protectedMatch = source.match(/protectedFields:\s*\{([\s\S]*?)\}/);
+    if (protectedMatch) {
+        config.protectedFields = {};
+        const entries = protectedMatch[1].matchAll(/(\w+):\s*\[([\s\S]*?)\]/g);
+        for (const entry of entries) {
+            config.protectedFields[entry[1]] = entry[2]
+                .match(/['"]([^'"]+)['"]/g)
+                ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+        }
+    }
+    // rowOwnership — scan for entries after the rowOwnership key
+    if (/rowOwnership\s*:/.test(source)) {
+        config.rowOwnership = {};
+        // Extract everything from rowOwnership: { to the matching closing }
+        const startIdx = source.indexOf('rowOwnership');
+        if (startIdx !== -1) {
+            // Find the opening brace
+            const braceStart = source.indexOf('{', startIdx);
+            if (braceStart !== -1) {
+                // Find the matching closing brace (handle one level of nesting)
+                let depth = 0;
+                let braceEnd = braceStart;
+                for (let i = braceStart; i < source.length; i++) {
+                    if (source[i] === '{')
+                        depth++;
+                    if (source[i] === '}')
+                        depth--;
+                    if (depth === 0) {
+                        braceEnd = i;
+                        break;
+                    }
+                }
+                const block = source.slice(braceStart + 1, braceEnd);
+                const entryRegex = /(\w+):\s*\{\s*column:\s*['"]([^'"]+)['"]\s*,\s*userField:\s*['"]([^'"]+)['"]\s*\}/g;
+                const entries = block.matchAll(entryRegex);
+                for (const entry of entries) {
+                    config.rowOwnership[entry[1]] = { column: entry[2], userField: entry[3] };
+                }
+            }
+        }
+    }
+    // softDelete
+    const softDeleteMatch = source.match(/softDelete:\s*\{[\s\S]*?tables:\s*\[([\s\S]*?)\]/);
+    if (softDeleteMatch) {
+        config.softDelete = {
+            tables: softDeleteMatch[1]
+                .match(/['"]([^'"]+)['"]/g)
+                ?.map((s) => s.replace(/['"]/g, '')) ?? [],
+        };
+    }
+    // pgSettings
+    config.pgSettings = /pgSettings\s*:/.test(source);
+    // publicRoutes
+    const publicRoutesMatch = source.match(/publicRoutes:\s*\[([\s\S]*?)\]/);
+    if (publicRoutesMatch) {
+        config.publicRoutes = publicRoutesMatch[1]
+            .match(/['"]([^'"]+)['"]/g)
+            ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+    }
+    // publicRpc
+    const publicRpcMatch = source.match(/publicRpc:\s*\[([\s\S]*?)\]/);
+    if (publicRpcMatch) {
+        config.publicRpc = publicRpcMatch[1]
+            .match(/['"]([^'"]+)['"]/g)
+            ?.map((s) => s.replace(/['"]/g, '')) ?? [];
+    }
+    return config;
+}
+export function analyzeSchema(projectPath) {
+    const issues = [];
+    const suggestions = [];
+    const allTables = [];
+    const allRelations = [];
+    // Find schema files
+    const dbDir = join(projectPath, 'db');
+    const schemaFiles = [];
+    if (existsSync(dbDir)) {
+        try {
+            const files = readdirSync(dbDir);
+            for (const f of files) {
+                if (f.endsWith('.ts') && !f.endsWith('.test.ts') && !f.startsWith('seed')) {
+                    schemaFiles.push(join(dbDir, f));
+                }
+            }
+        }
+        catch {
+            // ignore read errors
+        }
+    }
+    if (schemaFiles.length === 0) {
+        return {
+            tables: [],
+            relations: [],
+            handlerConfig: null,
+            issues: ['No schema files found in db/ directory'],
+            suggestions: ['Create db/schema.ts with your Drizzle pgTable definitions'],
+        };
+    }
+    // Parse each schema file
+    for (const file of schemaFiles) {
+        try {
+            const source = readFileSync(file, 'utf-8');
+            const relativePath = file.replace(projectPath + '/', '');
+            allTables.push(...parseTables(source, relativePath));
+            allRelations.push(...parseRelations(source));
+        }
+        catch {
+            issues.push(`Failed to read ${file}`);
+        }
+    }
+    // Find and parse handler config
+    let handlerConfig = null;
+    const handlerCandidates = [
+        'server/plugins/api.ts',
+        'server/api.ts',
+        'server/handler.ts',
+        'server/index.ts',
+    ];
+    for (const candidate of handlerCandidates) {
+        const fullPath = join(projectPath, candidate);
+        if (existsSync(fullPath)) {
+            try {
+                const source = readFileSync(fullPath, 'utf-8');
+                if (source.includes('createHandler')) {
+                    handlerConfig = parseHandlerConfig(source);
+                    break;
+                }
+            }
+            catch {
+                // continue to next candidate
+            }
+        }
+    }
+    // Cross-reference analysis
+    if (handlerConfig?.exposedTables) {
+        const tableNames = allTables.map((t) => t.name);
+        for (const exposed of handlerConfig.exposedTables) {
+            // Check both db name and export name
+            const found = allTables.some((t) => t.name === exposed || t.exportName === exposed);
+            if (!found) {
+                issues.push(`exposedTables includes '${exposed}' but no matching pgTable definition found in schema`);
+            }
+        }
+        // Tables defined but not exposed
+        for (const table of allTables) {
+            if (!handlerConfig.exposedTables.includes(table.name) &&
+                !handlerConfig.exposedTables.includes(table.exportName)) {
+                suggestions.push(`Table '${table.name}' is defined in schema but not in exposedTables — intentional?`);
+            }
+        }
+    }
+    // Check for soft delete columns
+    if (handlerConfig?.softDelete?.tables) {
+        for (const tableName of handlerConfig.softDelete.tables) {
+            const table = allTables.find((t) => t.name === tableName || t.exportName === tableName);
+            if (table) {
+                const hasDeletedAt = table.columns.some((c) => c.name === 'deletedAt' || c.dbName === 'deleted_at');
+                if (!hasDeletedAt) {
+                    issues.push(`Table '${tableName}' is in softDelete.tables but has no deletedAt column`);
+                }
+            }
+        }
+    }
+    // Check for rowOwnership references
+    if (handlerConfig?.rowOwnership) {
+        for (const [tableName, ownership] of Object.entries(handlerConfig.rowOwnership)) {
+            const table = allTables.find((t) => t.name === tableName || t.exportName === tableName);
+            if (table) {
+                const hasCol = table.columns.some((c) => c.name === ownership.column || c.dbName === ownership.column);
+                if (!hasCol) {
+                    issues.push(`rowOwnership for '${tableName}' references column '${ownership.column}' which doesn't exist`);
+                }
+            }
+        }
+    }
+    // pgSettings check
+    if (!handlerConfig?.pgSettings && allTables.length > 0) {
+        suggestions.push('No pgSettings configured — RLS policies cannot read JWT claims without it');
+    }
+    // Tables without primary keys
+    for (const table of allTables) {
+        const hasPk = table.columns.some((c) => c.modifiers.includes('primaryKey'));
+        if (!hasPk) {
+            // Could be a composite primary key (defined in table config, not column)
+            suggestions.push(`Table '${table.name}' — no single-column primaryKey() detected (may use composite key)`);
+        }
+    }
+    // Tables with timestamps
+    for (const table of allTables) {
+        const hasCreatedAt = table.columns.some((c) => c.dbName === 'created_at');
+        if (!hasCreatedAt) {
+            suggestions.push(`Table '${table.name}' has no created_at column — recommended for audit`);
+        }
+    }
+    return {
+        tables: allTables,
+        relations: allRelations,
+        handlerConfig,
+        issues,
+        suggestions,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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>",
@@ -40,8 +40,8 @@
     "tsx": "4.21.0",
     "typescript": "5.9.3",
     "zod": "3.25.67",
-    "@everystack/cli": "0.3.14",
-    "@everystack/model": "0.3.4"
+    "@everystack/cli": "0.3.27",
+    "@everystack/model": "0.3.6"
   },
   "scripts": {
     "test": "jest",

package/src/gates/detectors/hand-written-migration.ts

@@ -1,14 +1,23 @@
 /**
  * Cheat: hand-writing a migration or editing the generated schema.
  *
- * In v3 the schema and its migrations are *generated* from the Models
- * (`db:generate`). A hand-written `.sql` migration or a hand-edit to the generated
- * `db/schema.ts` drifts the database from the Models — the migration the CLI would
- * write next is no longer a clean no-op. Pure path check; no IO.
+ * Under the migration-authority workflow nobody authors migrations at all:
+ * the Models declare the state, `db:sync` moves a dev database to it,
+ * protected stages take fingerprint-verified plans (`db:plan` → `db:apply`),
+ * and CI (`db:check`) refuses generated artifacts that don't match
+ * regeneration. A hand-written `.sql` migration or a hand-edit to
+ * `db/schema.generated.ts` drifts the database from the Models. Pure path
+ * check; no IO.
  *
- * Note the layer split: SQL under `db/sql/` is the DERIVED layer (functions,
- * views, matviews) and is legitimately authored — it deploys via `db:reconcile`,
- * not through migrations, so this gate deliberately does not match it.
+ * The homes that ARE legitimately authored — this gate deliberately matches
+ * none of them:
+ *   - `db/models/` — the Models themselves (the source of truth).
+ *   - `db/sql/` — the DERIVED layer (functions/views/matviews), deployed
+ *     via `db:reconcile`/`db:sync`.
+ *   - `db/backfills/` — one-shot DATA jobs, run via `db:backfill` (content-
+ *     addressed, own record, never a schema side effect).
+ *   - `db/schema.ts` — the thin hand-maintained barrel that re-exports the
+ *     generated schema plus package-owned schemas.
  */
 
 import { relative } from 'path';
@@ -16,8 +25,8 @@ import type { CheatGate, ToolCallContext } from '../types.js';
 
 /** A `.sql` file under a migrations/drizzle directory — these are generated, never authored. */
 const MIGRATION_SQL = /(?:^|\/)(?:drizzle|migrations)\/[^/]+\.sql$/i;
-/** The generated Drizzle schema mirror. */
-const GENERATED_SCHEMA = /(?:^|\/)(?:db|drizzle)\/schema\.ts$/;
+/** The generated drizzle schema artifact (any location — monorepos relocate it via --schema-out). */
+const GENERATED_SCHEMA = /schema\.generated\.tsx?$/;
 
 function rel(ctx: ToolCallContext, p: string): string {
   try {
@@ -32,15 +41,15 @@ export const handWrittenMigration: CheatGate = {
   tier: 'framework',
   severity: 'deny',
   guide:
-    'Schema changes have two homes, neither is a hand-written migration: tables/constraints/authz are generated from your Models (edit the Model, run db:generate); functions, views, and matviews are authored in db/sql/ and DEPLOYED with db:reconcile — no migration file either way.',
-  conform: 'everystack db:generate (tables) · everystack db:reconcile (functions/views/matviews in db/sql)',
-  verify: 'everystack db:generate produces no diff AND everystack db:reconcile --check exits 0',
+    'Nobody authors migrations. Schema changes have three homes: tables/constraints/authz are declared in db/models/ (edit the Model, then `everystack db:sync` on dev — protected stages take `db:plan` → `db:apply`); functions/views/matviews are authored in db/sql/ (deployed by db:reconcile/db:sync); one-shot DATA moves are authored in db/backfills/*.sql (run via db:backfill, never as a schema side effect). No migration file, ever — and generated artifacts (schema.generated.ts) are never edited.',
+  conform: 'edit db/models/ then `everystack db:sync` (dev) or `db:plan` → `db:apply` (protected) · db/sql/ for derived objects · db/backfills/ for data moves',
+  verify: 'everystack db:check passes (declared state composes; generated artifacts match regeneration) AND everystack db:fingerprint reports MATCH',
   detect(ctx: ToolCallContext): string | null {
     if (ctx.tool !== 'Write' && ctx.tool !== 'Edit') return null;
     const p = ctx.filePath;
     if (!p) return null;
     if (MIGRATION_SQL.test(p)) return `${rel(ctx, p)} is a SQL migration being written by hand`;
-    if (GENERATED_SCHEMA.test(p)) return `${rel(ctx, p)} is generated from your Models`;
+    if (GENERATED_SCHEMA.test(p)) return `${rel(ctx, p)} is a generated artifact (compiled from your Models — db:check refuses hand edits)`;
     return null;
   },
 };

package/src/index.ts

@@ -71,7 +71,7 @@ const INSTRUCTIONS = [
   '1. Read everystack://core for architecture and conventions.',
   '2. Read everystack://security before any deployment or auth guidance.',
   '3. Load detail resources on demand when the user asks about specific features.',
-  '4. Data lives in PostgreSQL via Models/Modules and is served through the API — never bundle large computed data into the app. Schema changes have two homes: tables/authz are generated from Models (`db:generate`); functions, views, and matviews are authored in `db/sql/` and deployed with `db:reconcile` — never a hand-written migration either way. Reuse `@everystack/ui` components; never put secret values behind `EXPO_PUBLIC_*`.',
+  '4. Data lives in PostgreSQL via Models/Modules and is served through the API — never bundle large computed data into the app. NOBODY AUTHORS MIGRATIONS. Schema work has three homes: tables/constraints/authz are DECLARED in `db/models/` (edit the Model, then `everystack db:sync` moves the dev database to the checkout — verified by fingerprint); functions/views/matviews are authored in `db/sql/` (deployed by `db:reconcile`/`db:sync`); one-shot DATA moves are authored in `db/backfills/*.sql` (run via `db:backfill`, never as a schema side effect). Protected stages never take a sync: `db:plan` mints a reviewable, fingerprint-pinned edge and `db:apply` verifies at both ends — the checkout must descend from the commit declaring the target\'s state ("rebase first"), and destructive plans are confirmed, snapshotted, and approver-gated (`db:approvers`). CI runs `everystack db:check` (the merged declared state must compose; generated artifacts must match regeneration byte-for-byte). Per-branch dev databases: `db:template:refresh` + `db:branch`; deployed feature stages fork data with `db:fork`. Reuse `@everystack/ui` components; never put secret values behind `EXPO_PUBLIC_*`.',
   '5. When the user wants to start a new project, run check_environment (phase "local" for dev, "deploy" for deployment) to verify prerequisites.',
   '6. When the user needs to interact with deployed infrastructure, guide them to use the everystack CLI.',
 ].join('\n');

package/src/prompts/claude-md.ts

@@ -61,8 +61,10 @@ export function registerClaudeMdPrompt(server: McpServer): void {
                 '',
                 'Reconcile the existing CLAUDE.md against three things, and propose a concrete diff:',
                 '1. **Framework drift** — does it teach superseded ways (e.g. `drizzle-kit generate`,',
-                '   hand-written migrations, "pass your Drizzle schema") instead of the v3 Model flow',
-                '   (`defineModel` → `everystack db:generate`)? Suggest the current conventions.',
+                '   hand-written migrations, a migration journal, "pass your Drizzle schema") instead of',
+                '   the migration-authority flow (`defineModel` in db/models/ → `everystack db:sync` on',
+                '   dev; `db:plan` → `db:apply` on protected stages; `db:check` in CI; data moves in',
+                '   db/backfills/ via `db:backfill`)? Suggest the current conventions.',
                 '2. **Project drift** — do the Structure / Commands / package list match what is actually',
                 '   installed now (new packages, a new tier, a new models/ dir)? Suggest updates. Also',
                 '   check the operations manual: if docs/RUNBOOK.md is missing, or stale per',

package/src/resources/project-claude-md.md

@@ -19,12 +19,19 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 - **Data lives in PostgreSQL, served through the API — never bundle data into the app.** A
   large `.json`/`.csv` of computed data in the bundle is wrong; model it and serve it, or
   render an empty state if it does not exist yet.
-- **Schema changes have two homes; neither is a hand-written migration.** Tables and authz
-  are generated from Models: declare with `defineModel` (in `db/models/`), run
-  `everystack db:generate` — never hand-write a SQL migration, never edit the generated
-  `db/schema.ts`; after any change `db:generate` must be a clean no-op. Functions, views,
-  and matviews are **authored** in `db/sql/` and **deployed** with `everystack db:reconcile`
-  — edit the SQL file, reconcile, done; `db:reconcile --check` must exit 0.
+- **Nobody authors migrations. Schema work has three homes.** Tables and authz are DECLARED
+  in `db/models/` with `defineModel` — edit the Model, then `everystack db:sync` moves the
+  dev database to your checkout (state + authz + derived, fingerprint-verified). Functions,
+  views, and matviews are **authored** in `db/sql/` and deployed by `db:reconcile`/`db:sync`.
+  One-shot DATA moves are authored in `db/backfills/*.sql` and run via `everystack
+  db:backfill` — deliberately, never as a schema side effect. Never hand-write a SQL
+  migration, never edit `db/schema.generated.ts`; `everystack db:check` must pass (the CI
+  gate: the declared state composes, generated artifacts match regeneration).
+- **Protected stages take plans, not syncs.** `everystack db:plan` mints a reviewable edge
+  pinned by fingerprints at both ends; `db:apply` verifies before and after, requires the
+  checkout to descend from the commit declaring the target's state ("rebase first"), and
+  gates destructive plans: `--confirm` always, snapshot always, the stage's approver set
+  (`db:approvers`) when declared.
 - **Authorization is declared, not hand-written.** Use `can()` abilities on the Model; they
   compile to RLS + grants. Never hand-write `CREATE POLICY`/`GRANT`. RLS is required.
 - **Reuse `@everystack/ui`.** Do not hand-roll a component that already exists there. Style
@@ -36,10 +43,11 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 ## Start Here
 
 - `db/models/` — `defineModel` tables (the source of truth for schema + authz)
-- `db/sql/` — functions, views, matviews (authored SQL; deploys via `db:reconcile`)
+- `db/sql/` — functions, views, matviews (authored SQL; deploys via `db:reconcile`/`db:sync`)
+- `db/backfills/` — one-shot data jobs (authored SQL; run via `db:backfill`, own record)
 - `app/` — Expo Router pages (screens, navigation, API routes)
 - `server/` — Lambda handlers (api.ts, worker.ts, image.ts)
-- `db/schema.generated.ts`, `drizzle/` — generated artifacts (do not edit by hand)
+- `db/schema.generated.ts` — generated artifact (never edit; `db:check` refuses drift)
 - `lib/` — shared code (auth context, API client)
 - `sst.config.ts` — AWS infrastructure definition
 - `docs/RUNBOOK.md` — how to operate this app; regenerate with `everystack runbook`
@@ -54,9 +62,12 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 pnpm install                                 # Install dependencies
 pnpm dev                                     # Start the Expo dev server
 pnpm test                                    # Run all tests (TDD)
-everystack db:generate                       # Models → next migration (data + authz)
-everystack db:reconcile --apply              # Deploy functions/views/matviews from db/sql (no migrations)
-everystack db:migrate                        # Apply migrations on the deployed Lambda
+everystack db:sync                           # Dev edit loop: the database follows your checkout (state + authz + derived)
+everystack db:check                          # CI gate: declared state composes; generated artifacts match regeneration
+everystack db:plan | db:apply                # Protected stages: reviewable, fingerprint-verified edges
+everystack db:branch                         # Per-git-branch dev DB from the seeded template (db:template:refresh builds it)
+everystack db:backfill --apply               # Run one-shot data jobs from db/backfills/ (own record)
+everystack db:generate                       # Models → the diff as SQL (review surface)
 everystack db:seed                           # Seed the database (dev only)
 everystack deploy --stage dev                # Deploy infrastructure (SST)
 everystack update --channel production        # OTA update (no redeploy)
@@ -69,12 +80,15 @@ everystack bundle:audit <url>                # Audit a deployed bundle (weight +
 ### Models are the source of truth (v3)
 
 Declare tables with `defineModel` (`field`, `can`, relations). A package's full DB slice is a
-`defineModule`; the app composes Modules. `everystack db:generate` compiles them to one
-migration (schema + RLS + grants); `deriveHandlerConfig(models)` derives the API config. You
+`defineModule`; the app composes Modules. The database's own schema is the authority — the
+live state is content-addressed (`db:fingerprint`), and every apply verifies against it. You
 never hand-write migrations, RLS, or handler access-control — they are derived, so they cannot
-drift. The derived layer (functions, views, matviews) is the exception that proves the rule:
-that SQL is authored, in `db/sql/`, and *deployed* with `db:reconcile` — hand-edits straight
-against the database surface as drift, and a comment-only edit is a no-op.
+drift; `deriveHandlerConfig(models)` derives the API config. The derived layer (functions,
+views, matviews) is the exception that proves the rule: that SQL is authored, in `db/sql/`,
+and *deployed* by reconcile — hand-edits straight against the database surface as drift, and a
+comment-only edit is a no-op. Contraction is a two-step ceremony: `field.deprecated()` first
+(the column stays readable, new writes are rejected, generated types strike it through), the
+physical drop later — a destructive plan, confirmed, snapshotted, approver-gated.
 
 ### Security over all else