@everystack/mcp 0.3.3 → 0.4.0

package/dist/schema-patterns.md

@@ -1,167 +1,153 @@
 # Schema Design Patterns
 
-> Drizzle schema design, migrations, and RLS setup for everystack apps.
+> Declaring TABLES with `defineModel` in `db/models/` — fields, authz, relations, indexes.
 
 ## When to Use
-Read this when designing your database schema or adding tables to an existing app.
+Read this when designing your database schema or adding tables to an existing app. This
+resource covers **tables** (`defineModel`). For the derived layer —
+views, materialized views, functions, triggers, standalone sequences — read
+`everystack://derived-objects` (they deploy via `db:reconcile`, not migrations). For the
+operational verbs that move a database (`db:sync`, `db:generate`, `db:plan`/`db:apply`,
+`db:check`), read `everystack://database-operations`.
 
 ## Schema Location
 
-Schemas live in `db/schema.ts` (or `db/schema/` directory for larger apps). This file is the single source of truth for both the handler and SSR.
+The whole declared database lives in `db/models/` — one `defineModel` per table, composed
+onto a `defineModule`. This is the single source of truth for the handler, SSR, RLS, and
+grants. You do **not** hand-write `db/schema.ts`, and you do **not** run
+`drizzle-kit generate`/`drizzle-kit migrate` — the Model is authored, and everystack
+generates the migration (`db:generate`) and the typed artifact (`db/schema.generated.ts`,
+never edited). Never hand-write a SQL migration.
 
 ## Basic Table
 
 ```typescript
-import { pgTable, serial, text, integer, timestamp, uuid } from 'drizzle-orm/pg-core';
-
-export const posts = pgTable('posts', {
-  id: uuid('id').defaultRandom().primaryKey(),
-  body: text('body').notNull(),
-  authorId: uuid('author_id').notNull().references(() => users.id),
-  status: text('status').default('draft').notNull(),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-  updatedAt: timestamp('updated_at').defaultNow().notNull(),
-  deletedAt: timestamp('deleted_at'),
+import { defineModel, field, can } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: {
+    id: field.uuid().primaryKey().defaultRandom(),
+    body: field.text().notNull(),
+    authorId: field.uuid().notNull().references('users', 'id'),
+    status: field.text().notNull().default('draft'),
+    createdAt: field.timestamptz().notNull().defaultNow(),
+    updatedAt: field.timestamptz().notNull().defaultNow(),
+    deletedAt: field.timestamptz(),
+  },
+  abilities: [can('read'), can('create'), can('update'), can('delete')],
 });
 ```
 
+Column names are `snake_case` in the database; the field key is the app-side name — the
+generator maps `authorId` → `author_id` for you.
+
 ## Common Patterns
 
 ### UUID vs Serial Primary Keys
 Prefer UUID for user-facing IDs (prevents enumeration attacks). Use serial for internal-only tables.
 
 ```typescript
-id: uuid('id').defaultRandom().primaryKey(),  // Preferred for API-exposed tables
-id: serial('id').primaryKey(),                 // OK for internal tables
+id: field.uuid().primaryKey().defaultRandom(),  // Preferred for API-exposed tables
+id: field.serial().primaryKey(),                 // OK for internal tables
 ```
 
 ### Timestamps
 Always include `createdAt` and `updatedAt`:
 ```typescript
-createdAt: timestamp('created_at').defaultNow().notNull(),
-updatedAt: timestamp('updated_at').defaultNow().notNull(),
+createdAt: field.timestamptz().notNull().defaultNow(),
+updatedAt: field.timestamptz().notNull().defaultNow(),
 ```
 
 ### Soft Delete
 Add `deletedAt` for soft-deletable tables:
 ```typescript
-deletedAt: timestamp('deleted_at'),
+deletedAt: field.timestamptz(),
 ```
 Configure in handler: `softDelete: { column: 'deletedAt', tables: ['posts'] }`.
 
 ### Foreign Keys
 ```typescript
-authorId: uuid('author_id').notNull().references(() => users.id),
+authorId: field.uuid().notNull().references('users', 'id'),
 ```
 
 ### Enums
 ```typescript
-import { pgEnum } from 'drizzle-orm/pg-core';
-
-export const roleEnum = pgEnum('role', ['user', 'admin']);
-
-export const users = pgTable('users', {
-  role: roleEnum('role').default('user').notNull(),
-});
+role: field.enum('role', ['user', 'admin']).notNull().default('user'),
 ```
 
-## Relations (Drizzle)
+## Relations
 
-```typescript
-import { relations } from 'drizzle-orm';
+Declare relations on the Model — the generator emits both the Drizzle relations (used by
+the relational query API, `db.query.posts.findMany({ with: { author: true } })`) and the
+handler's embedding config, so they can't drift apart.
 
-export const postsRelations = relations(posts, ({ one, many }) => ({
-  author: one(users, { fields: [posts.authorId], references: [users.id] }),
-  comments: many(comments),
-}));
+```typescript
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  relations: {
+    author: { model: 'users', from: 'authorId', to: 'id' },
+    comments: { model: 'comments', from: 'id', to: 'postId', many: true },
+  },
+  abilities: [can('read')],
+});
 ```
 
-Drizzle relations are used by the relational query API (`db.query.posts.findMany({ with: { author: true } })`). The handler also needs its own `relations` config for embedding.
-
 ## Indexes
 
 ```typescript
-import { index, uniqueIndex } from 'drizzle-orm/pg-core';
-
-export const posts = pgTable('posts', {
-  // columns...
-}, (table) => [
-  index('posts_author_id_idx').on(table.authorId),
-  uniqueIndex('posts_slug_idx').on(table.slug),
-]);
+import { defineModel, field, can, index } from '@everystack/model';
+
+export const Post = defineModel('posts', {
+  fields: { /* … */ },
+  indexes: [
+    index(['authorId']),
+    index(['slug']).unique(),
+  ],
+  abilities: [can('read')],
+});
 ```
 
-## Migration Workflow
-
-```bash
-# Generate migration from schema changes
-npx drizzle-kit generate
-
-# Apply migrations locally
-npx drizzle-kit migrate
+## Authorization is declared, not migrated
 
-# Apply migrations on deployed Lambda
-everystack db:migrate
-```
+You never hand-write `CREATE ROLE`, `GRANT`, or `CREATE POLICY`. Abilities on the Model
+compile to grants + RLS, and `db:sync`/`db:apply` deploy them. `can('read')` grants `anon`
++ `authenticated`; `can('read', { role: 'admin' })` narrows to a role. RLS is required —
+the CI gate (`db:check`) refuses a table without it. See `everystack://security` for the
+policy patterns the abilities compile to.
 
-Migration files go in `drizzle/` directory. Each migration is a SQL file.
-
-### RLS Migration Template
-
-After creating tables, add a migration for roles and policies:
-
-```sql
--- Create roles (idempotent)
-DO $$ BEGIN
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticator') THEN
-    CREATE ROLE authenticator LOGIN NOINHERIT;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'anon') THEN
-    CREATE ROLE anon NOLOGIN;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'authenticated') THEN
-    CREATE ROLE authenticated NOLOGIN;
-  END IF;
-  IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'admin') THEN
-    CREATE ROLE admin NOLOGIN;
-  END IF;
-END $$;
-
-GRANT anon TO authenticator;
-GRANT authenticated TO authenticator;
-GRANT admin TO authenticator;
-
--- Table grants
-GRANT USAGE ON SCHEMA public TO anon, authenticated, admin;
-GRANT SELECT ON posts TO anon;
-GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO authenticated;
-GRANT SELECT, INSERT, UPDATE, DELETE ON posts TO admin;
-
--- Enable RLS
-ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
-ALTER TABLE posts FORCE ROW LEVEL SECURITY;
-
--- Policies (see everystack://security for templates)
+```typescript
+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' }),
+  ],
+});
 ```
 
 ## Handler Config for Schema
 
+The handler config is **derived** from the Models (`deriveHandlerConfig(models)`), so
+`exposedTables`, `hiddenColumns`, `protectedFields`, and `relations` come from the
+declarations rather than a hand-kept parallel list:
+
 ```typescript
-createHandler(db, schema, {
-  exposedTables: ['posts', 'profiles'],  // Only these are API-accessible
-  hiddenColumns: { users: ['passwordHash', 'resetToken'] },
-  protectedFields: { profiles: ['role', 'deletedAt'] },
-  relations: {
-    posts: { author: { table: 'users', from: 'authorId', to: 'id' } },
-  },
-});
+import { deriveHandlerConfig } from '@everystack/model';
+import { models } from '../db/models';
+
+createHandler(db, schema, deriveHandlerConfig(models));
 ```
 
 ## Gotchas
 
-- Drizzle column names (camelCase) and SQL column names (snake_case) are both specified: `authorId: uuid('author_id')`
-- The handler's `relations` config uses Drizzle property names, not SQL column names
-- `exposedTables` uses Drizzle table variable names, not SQL table names
-- Always run `drizzle-kit generate` after schema changes
-- RLS migration must be run AFTER table creation migration
-- Connect as `authenticator` in production (never RDS master/superuser)
+- Field keys are app-side names (camelCase); the database column is `snake_case` — the
+  generator maps `authorId` → `author_id`.
+- Edit the Model, then move the database with `db:sync` (dev) or `db:generate` +
+  `db:plan`/`db:apply` (protected stages). Never run `drizzle-kit generate`.
+- RLS and grants are declared with `can()`, never hand-written; `db:check` fails a table
+  without RLS.
+- `db/schema.generated.ts` is a generated artifact — never edit it; `db:check` refuses
+  drift.
+- Connect as `authenticator` in production (never RDS master/superuser).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.3.3",
+  "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.27",
-    "@everystack/model": "0.3.6"
+    "@everystack/cli": "0.4.2",
+    "@everystack/model": "0.4.1"
   },
   "scripts": {
     "test": "jest",

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

@@ -11,13 +11,17 @@
  *
  * 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/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';
@@ -27,6 +31,8 @@ import type { CheatGate, ToolCallContext } from '../types.js';
 const MIGRATION_SQL = /(?:^|\/)(?:drizzle|migrations)\/[^/]+\.sql$/i;
 /** 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 {
@@ -41,8 +47,8 @@ export const handWrittenMigration: CheatGate = {
   tier: 'framework',
   severity: 'deny',
   guide:
-    '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',
+    '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;
@@ -50,6 +56,7 @@ export const handWrittenMigration: CheatGate = {
     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 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. 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_*`.',
+  '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/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',

package/src/prompts/design-schema.ts

@@ -4,10 +4,10 @@ import { z } from 'zod';
 export function registerDesignSchemaPrompt(server: McpServer): void {
   server.prompt(
     'design-schema',
-    'Interactive schema design: plain English description → Drizzle schema + migrations + RLS policies + handler config + testing checklist.',
+    'Interactive schema design (0.4.0): plain English description → declared Models (defineModel + can abilities) + derived descriptors + testing checklist. Authz and handler config are DERIVED from the Models, never hand-written.',
     {
       description: z.string().describe('Plain English description of the data model (e.g., "blog with posts, comments, and tags")'),
-      projectPath: z.string().optional().describe('Absolute path to project root (to analyze existing schema)'),
+      projectPath: z.string().optional().describe('Absolute path to project root (to read the existing db/models/)'),
     },
     async ({ description, projectPath }) => {
       return {
@@ -19,81 +19,67 @@ export function registerDesignSchemaPrompt(server: McpServer): void {
               text: [
                 `Design a database schema for: ${description}`,
                 '',
+                'IMPORTANT (0.4.0): you declare the schema, you do NOT hand-write it. Tables are',
+                '`defineModel` in `db/models/`; authorization is `can()` abilities on the Model that',
+                'COMPILE to RLS + grants; the handler config is DERIVED from the Models. Never hand-write',
+                '`db/schema.ts`, a SQL migration, `CREATE POLICY`, or `GRANT` — those are generated.',
+                '',
                 '## Instructions',
                 '',
-                '1. Read everystack://schema-patterns for Drizzle schema conventions.',
-                '2. Read everystack://security for RLS policy patterns.',
-                '3. Read everystack://handler-options for handler configuration.',
-                projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to understand the existing schema.` : '',
+                '1. Read everystack://schema-patterns for how to declare TABLES (defineModel, field, can, relations).',
+                '2. Read everystack://derived-objects IF the model needs views, materialized views, functions, or triggers.',
+                '3. Read everystack://security for the authorization model (how can() abilities become RLS + grants).',
+                '4. Read everystack://database-operations for how the declaration reaches a database (db:sync on dev).',
+                projectPath ? `5. Read the existing \`db/models/\` under "${projectPath}" to match its conventions before adding to it.` : '',
                 '',
                 '## Deliverables',
                 '',
                 'Generate ALL of the following:',
                 '',
-                '### 1. Drizzle Schema (db/schema.ts)',
-                '',
-                'Follow these conventions:',
-                '- UUID primary keys: `uuid(\'id\').primaryKey().defaultRandom()`',
-                '- Timestamps: `timestamp(\'created_at\', { withTimezone: true }).defaultNow().notNull()`',
-                '- Soft delete columns: `deletedAt` + `deletedBy` on user-facing tables',
-                '- Foreign keys with `.references(() => table.column)`',
-                '- Export all tables as named exports',
-                '- Add Drizzle `relations()` for SSR query building and API embedding',
-                '',
-                '### 2. SQL Migration with RLS',
-                '',
-                'Generate a custom SQL migration that includes:',
+                '### 1. Models (db/models/<table>.ts — one file per table)',
                 '',
-                '```sql',
-                '-- For each table:',
-                'ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;',
+                '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 opts the table into soft-delete',
+                '- 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\', …)`)',
                 '',
-                '-- Grant minimum required access per role:',
-                'GRANT SELECT ON table_name TO anon;',
-                'GRANT SELECT, INSERT, UPDATE, DELETE ON table_name TO authenticated;',
-                'GRANT ALL ON table_name TO admin;',
+                '### 2. Authorization — `can()` abilities ON each Model (NOT hand-written RLS)',
                 '',
-                '-- Policies per access pattern:',
-                '-- Public read:',
-                'CREATE POLICY "anon_select" ON table_name FOR SELECT TO anon USING (deleted_at IS NULL);',
+                'Declare the access pattern as abilities; the compiler emits the RLS policies and GRANTs.',
+                'Every table MUST make its read decision or `db:check` fails it:',
                 '',
-                '-- Own rows only:',
-                'CREATE POLICY "own_rows" ON table_name FOR ALL TO authenticated',
-                '  USING (user_id = current_setting(\'request.jwt.claims\', true)::json->>\'sub\');',
-                '',
-                '-- Admin full access:',
-                'CREATE POLICY "admin_all" ON table_name FOR ALL TO admin USING (true);',
+                '```ts',
+                'abilities: [',
+                "  can('read'),                              // public read (anon + authenticated)",
+                "  can('read', { owner: 'authorId' }),       // rows the caller owns",
+                "  can('manage', { owner: 'authorId' }),     // owner can write their own rows",
+                "  can('read', { role: 'admin' }),           // a specific role only",
+                '],',
                 '```',
                 '',
-                'Adapt the policies to the specific access patterns for each table.',
+                'A private/operational table declares `private: true` (generated, but not a generic-API',
+                'resource). Row ownership, soft-delete, hidden/protected columns, and relations are all',
+                'DERIVED from the Model into the handler config — do not write a createHandler options blob',
+                'by hand.',
                 '',
-                '### 3. Handler Configuration',
+                '### 3. Derived objects (only if the model needs compute)',
                 '',
-                'Generate the createHandler() config snippet:',
-                '- `exposedTables`: only tables that should be API-accessible',
-                '- `relations`: for embedding related data in API queries',
-                '- `rowOwnership`: for user-scoped tables',
-                '- `softDelete`: for tables with deletedAt columns',
-                '- `protectedFields`: fields users cannot set directly (role, deletedAt)',
-                '- `hiddenColumns`: sensitive columns not returned in API responses',
+                'If the design needs a view, materialized view, function, or trigger, declare it as a',
+                'descriptor in `db/models/derived.ts` per everystack://derived-objects — NOT as a SQL',
+                'migration. Wire them on `defineModule({ models, derived })`.',
                 '',
-                '### 4. Testing Checklist',
+                '### 4. Testing + apply checklist',
                 '',
-                'Generate a testing checklist:',
-                '- [ ] Anonymous users can read public data',
-                '- [ ] Anonymous users cannot write any data',
-                '- [ ] Authenticated users can only read/write their own data',
+                '- [ ] Every table declares a read ability or `private: true` (db:check gate)',
+                '- [ ] Anonymous users can read only what `can(\'read\')` (no owner/role) allows',
+                '- [ ] Owner-scoped rows are invisible and unwritable across users (IDOR)',
                 '- [ ] Soft-deleted rows are hidden from normal queries',
-                '- [ ] Admin users can access all data',
-                '- [ ] Foreign key constraints prevent orphaned rows',
-                '- [ ] RLS policies work with pgSettings claim injection',
-                '',
-                'Test each RLS policy with:',
-                '```sql',
-                'SET LOCAL ROLE authenticated;',
-                "SELECT set_config('request.jwt.claims', '{\"sub\": \"user-uuid\", \"role\": \"authenticated\"}', true);",
-                'SELECT * FROM table_name; -- should only return own rows',
-                '```',
+                '- [ ] `everystack db:sync --database-url "$DATABASE_URL"` applies cleanly on a dev DB',
+                '- [ ] `everystack db:check` passes (declared state composes; generated artifacts match)',
+                '- [ ] `everystack db:authz:test --stage dev` proves the compiled RLS enforces the abilities',
               ].filter(Boolean).join('\n'),
             },
           },