@everystack/mcp 0.3.2 → 0.4.0

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.4.0",
   "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.4.2",
+    "@everystack/model": "0.4.1"
   },
   "scripts": {
     "test": "jest",

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

@@ -1,14 +1,27 @@
 /**
  * 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 AND the derived-layer descriptors (defineView /
+ *     defineMaterializedView / defineFunction / defineSql / trigger()) — the
+ *     whole declared database, 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.
+ *
+ * `db/sql/` is RETIRED (B7, read-model-everywhere): raw-SQL derived objects
+ * moved into descriptors. A write there is flagged — the CLI verbs fail on the
+ * directory too; this gate just says so before the file lands.
  */
 
 import { relative } from 'path';
@@ -16,8 +29,10 @@ 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?$/;
+/** The retired raw-SQL derived home — descriptors in db/models are the single home now. */
+const RETIRED_DB_SQL = /(?:^|\/)db\/sql\/[^/]+\.sql$/i;
 
 function rel(ctx: ToolCallContext, p: string): string {
   try {
@@ -32,15 +47,16 @@ 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 two homes: the WHOLE declared database — tables/constraints/authz (defineModel) AND functions/views/matviews (defineView/defineMaterializedView/defineFunction/defineSql descriptors) — lives in db/models/ (edit the declaration, then `everystack db:sync` on dev — protected stages take `db:plan` → `db:apply`); one-shot DATA moves are authored in db/backfills/*.sql (run via db:backfill, never as a schema side effect). db/sql/ is retired — raw-SQL derived objects moved into descriptors. No migration file, ever — and generated artifacts (schema.generated.ts) are never edited.',
+  conform: 'edit db/models/ (Models + derived descriptors) then `everystack db:sync` (dev) or `db:plan` → `db:apply` (protected) · 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)`;
+    if (RETIRED_DB_SQL.test(p)) return `${rel(ctx, p)} is in the retired db/sql home — declare it as a descriptor (defineView/defineMaterializedView/defineFunction/defineSql) in db/models/ instead; the CLI verbs fail on this directory`;
     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 two homes: the WHOLE declared database — tables/constraints/authz (defineModel) AND functions/views/matviews (defineView/defineMaterializedView/defineFunction/defineSql descriptors) — is DECLARED in `db/models/` (edit the declaration, then `everystack db:sync` moves the dev database to the checkout — verified by fingerprint; the derived layer deploys via `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/add-feature.ts

@@ -105,7 +105,7 @@ const FEATURES: Record<string, { resource: string; packages: string[]; steps: st
     packages: [],
     steps: [
       'Events use PostgreSQL LISTEN/NOTIFY — built into the database',
-      'Create database trigger functions for table change notifications',
+      'Declare the NOTIFY trigger the descriptor way (everystack://derived-objects): a defineFunction returning trigger, wired via trigger() on the Model — never a hand-written SQL trigger or a db/sql file',
       'Set up a listener Lambda with persistent database connection',
       'Add WebSocket fan-out for client delivery',
       'Use the useSignal hook in React components for real-time updates',
@@ -139,8 +139,8 @@ export function registerAddFeaturePrompt(server: McpServer): void {
                 `1. Read the ${f.resource} resource for full documentation.`,
                 '2. Read everystack://core for architecture context.',
                 feature === 'auth' || feature === 'security' ? '3. Read everystack://security for the security model.' : '',
-                projectPath ? `4. Run the project_status tool with projectPath="${projectPath}" to understand the current state.` : '',
-                projectPath ? `5. Run the project_validate tool with projectPath="${projectPath}" after making changes.` : '',
+                projectPath ? `4. Read the project's CLAUDE.md and structure under "${projectPath}" to understand the current state.` : '',
+                projectPath ? '5. After changes: `pnpm test`, and if the schema changed, `everystack db:check`.' : '',
                 '',
                 '## Steps',
                 '',
@@ -151,7 +151,7 @@ export function registerAddFeaturePrompt(server: McpServer): void {
                 '## After Setup',
                 '',
                 '- Run tests to verify the integration',
-                '- Run project_validate to check for configuration issues',
+                '- If the schema changed, run `everystack db:check`',
                 '- Read the relevant resource docs for advanced configuration',
               ].filter(Boolean).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/prompts/debug.ts

@@ -22,9 +22,8 @@ export function registerDebugPrompt(server: McpServer): void {
                 '## Instructions',
                 '',
                 '1. Read everystack://core for architecture context.',
-                projectPath ? `2. Run project_status with projectPath="${projectPath}" to understand the project.` : '',
-                projectPath ? `3. Run project_validate with projectPath="${projectPath}" to find configuration issues.` : '',
-                projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to check schema/handler alignment.` : '',
+                projectPath ? `2. Read the project's CLAUDE.md and \`db/models/\` under "${projectPath}" to understand its schema and conventions.` : '',
+                projectPath ? '3. If the issue is schema/database-related, run `everystack db:check` (declared state composes) and `everystack db:fingerprint` (live schema matches the Models) to localize drift.' : '',
                 '',
                 '## Diagnostic Framework',
                 '',
@@ -125,7 +124,7 @@ export function registerDebugPrompt(server: McpServer): void {
                 '1. Identify the root cause',
                 '2. Propose a fix with the specific code change',
                 '3. Verify the fix resolves the issue',
-                '4. Run project_validate to ensure no new issues were introduced',
+                '4. Run `pnpm test` and (for schema changes) `everystack db:check` to ensure no new issues were introduced',
               ].filter(Boolean).join('\n'),
             },
           },

package/src/prompts/deploy.ts

@@ -4,7 +4,7 @@ import { z } from 'zod';
 export function registerDeployPrompt(server: McpServer): void {
   server.prompt(
     'deploy',
-    'Step-by-step deployment walkthrough for a specific stage. Covers AWS credentials, SST deploy, migrations, and verification.',
+    'Step-by-step deployment walkthrough for a specific stage. Covers AWS credentials, SST deploy, the SAFE schema flow (db:plan → db:apply, snapshot-first), and verification.',
     {
       stage: z.enum(['dev', 'staging', 'production']).describe('Deployment stage'),
       projectPath: z.string().optional().describe('Absolute path to project root'),
@@ -25,8 +25,8 @@ export function registerDeployPrompt(server: McpServer): void {
                 '',
                 '1. Read everystack://deployment for infrastructure setup.',
                 '2. Read everystack://security for AWS credential setup and deployment checklist.',
-                projectPath ? `3. Run project_validate with projectPath="${projectPath}" to check for issues before deploying.` : '',
-                projectPath ? `4. Run project_status with projectPath="${projectPath}" to see current deployment state.` : '',
+                '3. Read everystack://database-operations for the SAFE schema-migration flow (db:plan → db:apply, snapshot-first) — a protected stage is NOT migrated with db:migrate.',
+                projectPath ? `4. Run check_environment with projectPath="${projectPath}" to confirm prerequisites (Node, SST, AWS credentials) before deploying.` : '',
                 '',
                 '## Pre-Deploy Checklist',
                 '',
@@ -49,8 +49,8 @@ export function registerDeployPrompt(server: McpServer): void {
                   '### Production Safety',
                   '',
                   '- [ ] All tests pass: `pnpm test`',
-                  '- [ ] No security warnings: run project_validate',
-                  '- [ ] RLS policies are in place for all tables',
+                  '- [ ] `everystack db:check` passes (declared state composes; generated artifacts match)',
+                  '- [ ] RLS is declared via `can()` abilities on every Model (compiles to policies + grants)',
                   '- [ ] pgSettings is configured in handler',
                   '- [ ] No hardcoded secrets in source',
                   '- [ ] .env files are not committed',
@@ -71,10 +71,19 @@ export function registerDeployPrompt(server: McpServer): void {
                 '- SQS queues (V3)',
                 '- IAM roles and policies',
                 '',
-                '### 3. Database Setup (V2+)',
+                '### 2. Database Schema (V2+) — the SAFE flow',
+                '',
+                'A protected stage is migrated by minting a reviewable plan and applying it credential-free',
+                '(the operator never holds the database URL). See everystack://database-operations.',
                 '```bash',
-                `everystack db:migrate --stage ${stage}`,
-                stage === 'dev' ? `everystack db:seed --stage ${stage}  # dev only` : '',
+                `everystack db:check                                  # gate: declared state composes`,
+                `everystack db:plan --stage ${stage} --out ${stage}.plan.json    # mint the edge (read-only) — REVIEW it`,
+                isProduction ? `everystack db:snapshot --stage ${stage}              # physical RDS snapshot first (instant rollback)` : '',
+                `everystack db:apply --plan ${stage}.plan.json --stage ${stage}   # verify → apply → verify`,
+                `#   destructive plans (drops / narrowing types) also need: --confirm + a snapshot + the`,
+                `#   stage's approver set (everystack db:approvers --stage ${stage} --set "…")`,
+                `everystack db:reconcile --check --stage ${stage}      # confirm the compute layer (views/matviews/functions) matches`,
+                stage === 'dev' ? `everystack db:seed --stage ${stage}                  # dev only` : '',
                 '```',
                 '',
                 '### 4. Verify',