@everystack/mcp 0.3.3 → 0.4.0

package/dist/index.cjs

@@ -21631,9 +21631,21 @@ var RESOURCES = [
   {
     uri: "everystack://schema-patterns",
     name: "Schema Design Patterns",
-    description: "Drizzle schema design: pgTable, column types, relations, indexes, timestamps, soft delete, UUID vs serial, migration workflow, drizzle-kit commands.",
+    description: "How to declare TABLES (0.4.0): db/models/ with defineModel (field, can, relations, constraints) \u2014 NOT hand-written pgTable or drizzle-kit. Column types, keys, indexes, timestamps, soft delete, UUID vs serial, the private()/readonly()/deprecated() write surface. Read everystack://derived-objects for views/matviews/functions/triggers, and everystack://database-operations for how it reaches a database.",
     filename: "schema-patterns.md"
   },
+  {
+    uri: "everystack://derived-objects",
+    name: "Derived Objects (Views, Matviews, Functions, Triggers)",
+    description: "How to add or change a view, materialized view, function, trigger, or standalone sequence in 0.4.0 \u2014 declared descriptors (defineView / defineMaterializedView / defineFunction / defineSql / trigger() / defineSequence) on defineModule({ derived }), deployed by db:reconcile (NEVER migrated). Read this whenever a schema needs compute, not just tables. db/sql/ is retired.",
+    filename: "derived-objects.md"
+  },
+  {
+    uri: "everystack://database-operations",
+    name: "Database Operations (migrate, import data, SAFE remote apply)",
+    description: "The operational playbook: local dev (db:sync, db:branch, db:template:refresh), importing data properly (db:seed, db:backfill, ingest pipeline \u2014 never ad-hoc INSERTs), and migrating a REMOTE stage SAFELY (db:check \u2192 db:plan \u2192 db:apply with fingerprint + fast-forward verification; destructive plans require --confirm + snapshot + approvers). Snapshot-first (db:snapshot vs db:backup) and remote data import (db:seed --stage, pipeline:run, db:fork). READ THIS before touching a deployed database.",
+    filename: "database-operations.md"
+  },
   {
     uri: "everystack://deployment",
     name: "Deployment Guide",
@@ -22074,7 +22086,7 @@ function registerNewAppPrompt(server) {
                 "```",
                 `${effectiveName}/`,
                 "\u251C\u2500\u2500 app/              # Expo Router pages",
-                effectiveTier !== "V1" ? "\u251C\u2500\u2500 db/               # Schema, migrations, seed" : "",
+                effectiveTier !== "V1" ? "\u251C\u2500\u2500 db/               # models/ (declared schema), backfills/, seed" : "",
                 "\u251C\u2500\u2500 server/           # Lambda handlers",
                 effectiveTier !== "V1" ? "\u2502   \u2514\u2500\u2500 api.ts        # PostgREST handler" : "",
                 effectiveTier === "V3" ? "\u2502   \u251C\u2500\u2500 worker.ts     # SQS worker handler" : "",
@@ -22085,27 +22097,29 @@ function registerNewAppPrompt(server) {
                 "```",
                 "",
                 effectiveTier !== "V1" ? [
-                  "### 3. Database Schema",
-                  `Create db/schema.ts with tables for the ${description}.`,
+                  "### 3. Database Schema \u2014 declared Models (0.4.0)",
+                  `Declare tables for the ${description} as \`defineModel\` in \`db/models/\` (one file per table).`,
+                  "Do NOT hand-write db/schema.ts or run drizzle-kit \u2014 the schema is DECLARED, then compiled.",
                   "Follow the patterns from everystack://schema-patterns:",
-                  "- UUID primary keys with defaultRandom()",
-                  "- created_at timestamps on all tables",
-                  "- Foreign key references with proper cascading",
-                  "- Relations for both SSR and API query embedding",
+                  "- `field.uuid().primaryKey().defaultRandom()`; `field.timestamptz().defaultNow().notNull()`",
+                  "- Foreign keys via `.references(() => Model)` / relations for SSR + API embedding",
+                  "- Authorization as `can()` abilities ON the Model (compiles to RLS + grants \u2014 never hand-written)",
+                  "- Views/matviews/functions/triggers: descriptors in db/models/derived.ts (everystack://derived-objects)",
+                  "- Compose in db/models/index.ts: `defineModule({ models, derived })`",
                   "",
-                  "### 4. Migrations",
-                  "- Generate: `npx drizzle-kit generate`",
-                  "- Add RLS policies in a custom SQL migration",
-                  "- Reference the RLS templates from everystack://security",
+                  "### 4. Apply the schema",
+                  '- Dev database: `everystack db:sync --database-url "$DATABASE_URL"` (state + authz + compute, one verb)',
+                  "- CI gate: `everystack db:check`",
+                  "- Protected stages: `db:plan` \u2192 `db:apply` (everystack://database-operations)",
+                  "- No hand-written migration, no CREATE POLICY, no GRANT \u2014 all generated from the Models",
                   "",
                   "### 5. Handler Configuration",
                   "Create server/api.ts using createPluginLambdaHandler or createLambdaHandler.",
-                  "Include:",
+                  "The per-table access config (exposedTables, rowOwnership, softDelete, hidden/protected columns,",
+                  "relations) is DERIVED from your Models via `deriveHandlerConfig(models)` \u2014 do not hand-maintain it.",
+                  "Set only the app-level options by hand:",
                   "- auth.verifyToken for JWT verification",
                   "- pgSettings for RLS context injection",
-                  "- exposedTables to limit API surface",
-                  "- rowOwnership for user-scoped mutation control",
-                  "- softDelete for reversible deletes",
                   "",
                   "### 6. Auth Setup",
                   "Read everystack://auth for the full auth flow.",
@@ -22116,7 +22130,7 @@ function registerNewAppPrompt(server) {
                 ].join("\n") : "",
                 "## Validation",
                 "",
-                "After scaffolding, run the project_validate tool to check for common mistakes.",
+                "After scaffolding, run `check_environment` to confirm prerequisites, and `everystack db:check` to confirm the declared schema composes.",
                 "",
                 "## Run Locally",
                 "",
@@ -22168,10 +22182,10 @@ function registerNewAppPrompt(server) {
                 effectiveTier === "V3" ? "- S3 bucket for file uploads" : "",
                 "",
                 "### Deploy",
-                "Read everystack://deployment for the full walkthrough.",
+                "Read everystack://deployment and everystack://database-operations for the full walkthrough.",
                 "1. `pnpm sst deploy --stage dev`",
-                effectiveTier !== "V1" ? "2. `everystack db:migrate`" : "",
-                effectiveTier !== "V1" ? "3. `everystack db:seed` (dev only)" : ""
+                effectiveTier !== "V1" ? "2. `everystack db:plan --stage dev --out dev.plan.json` \u2192 review \u2192 `everystack db:apply --plan dev.plan.json --stage dev`" : "",
+                effectiveTier !== "V1" ? "3. `everystack db:seed --stage dev` (dev only)" : ""
               ].filter(Boolean).join("\n")
             }
           }
@@ -22286,7 +22300,7 @@ var FEATURES = {
     packages: [],
     steps: [
       "Events use PostgreSQL LISTEN/NOTIFY \u2014 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 \u2014 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"
@@ -22317,8 +22331,8 @@ function registerAddFeaturePrompt(server) {
                 `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",
                 "",
@@ -22333,7 +22347,7 @@ pnpm add ${f.packages.join(" ")}
                 "## 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")
             }
@@ -22348,10 +22362,10 @@ pnpm add ${f.packages.join(" ")}
 function registerDesignSchemaPrompt(server) {
   server.prompt(
     "design-schema",
-    "Interactive schema design: plain English description \u2192 Drizzle schema + migrations + RLS policies + handler config + testing checklist.",
+    "Interactive schema design (0.4.0): plain English description \u2192 declared Models (defineModel + can abilities) + derived descriptors + testing checklist. Authz and handler config are DERIVED from the Models, never hand-written.",
     {
       description: external_exports.string().describe('Plain English description of the data model (e.g., "blog with posts, comments, and tags")'),
-      projectPath: external_exports.string().optional().describe("Absolute path to project root (to analyze existing schema)")
+      projectPath: external_exports.string().optional().describe("Absolute path to project root (to read the existing db/models/)")
     },
     async ({ description, projectPath }) => {
       return {
@@ -22363,81 +22377,67 @@ function registerDesignSchemaPrompt(server) {
               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` \u2014 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",
+                "### 1. Models (db/models/<table>.ts \u2014 one file per table)",
                 "",
-                "### 2. SQL Migration with RLS",
+                "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', \u2026)`)",
                 "",
-                "Generate a custom SQL migration that includes:",
+                "### 2. Authorization \u2014 `can()` abilities ON each Model (NOT hand-written RLS)",
                 "",
-                "```sql",
-                "-- For each table:",
-                "ALTER TABLE table_name ENABLE ROW LEVEL SECURITY;",
+                "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:",
                 "",
-                "-- 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;",
-                "",
-                "-- Policies per access pattern:",
-                "-- Public read:",
-                'CREATE POLICY "anon_select" ON table_name FOR SELECT TO anon USING (deleted_at IS NULL);',
-                "",
-                "-- 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 \u2014 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 \u2014 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")
             }
           }
@@ -22451,7 +22451,7 @@ function registerDesignSchemaPrompt(server) {
 function registerDeployPrompt(server) {
   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 \u2192 db:apply, snapshot-first), and verification.",
     {
       stage: external_exports.enum(["dev", "staging", "production"]).describe("Deployment stage"),
       projectPath: external_exports.string().optional().describe("Absolute path to project root")
@@ -22471,8 +22471,8 @@ function registerDeployPrompt(server) {
                 "",
                 "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 \u2192 db:apply, snapshot-first) \u2014 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",
                 "",
@@ -22495,8 +22495,8 @@ function registerDeployPrompt(server) {
                   "### 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",
@@ -22517,10 +22517,19 @@ function registerDeployPrompt(server) {
                 "- SQS queues (V3)",
                 "- IAM roles and policies",
                 "",
-                "### 3. Database Setup (V2+)",
+                "### 2. Database Schema (V2+) \u2014 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) \u2014 REVIEW it`,
+                isProduction ? `everystack db:snapshot --stage ${stage}              # physical RDS snapshot first (instant rollback)` : "",
+                `everystack db:apply --plan ${stage}.plan.json --stage ${stage}   # verify \u2192 apply \u2192 verify`,
+                `#   destructive plans (drops / narrowing types) also need: --confirm + a snapshot + the`,
+                `#   stage's approver set (everystack db:approvers --stage ${stage} --set "\u2026")`,
+                `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",
@@ -22593,9 +22602,8 @@ function registerDebugPrompt(server) {
                 "## 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",
                 "",
@@ -22696,7 +22704,7 @@ function registerDebugPrompt(server) {
                 "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")
             }
           }
@@ -22732,8 +22740,8 @@ function registerSecurePrompt(server) {
                 "",
                 "1. Read everystack://security for the complete security model.",
                 "2. Read everystack://auth for JWT authentication details.",
-                projectPath ? `3. Run project_validate with projectPath="${projectPath}" to find existing security gaps.` : "",
-                projectPath ? `4. Run schema_analyze with projectPath="${projectPath}" to check schema security.` : "",
+                projectPath ? `3. Read the project's \`db/models/\` under "${projectPath}" \u2014 the \`can()\` abilities ARE the authorization; confirm every table declares a read decision.` : "",
+                projectPath ? "4. Run the real security tooling: `everystack db:doctor` (least-privilege + RLS posture), `everystack db:authz:test --stage dev` (the compiled RLS enforces the abilities), and `everystack security:audit`." : "",
                 "",
                 requested.includes("aws") ? [
                   "## AWS IAM Profiles",
@@ -22914,7 +22922,7 @@ function registerSecurePrompt(server) {
                 "",
                 "After setup, verify security:",
                 "",
-                "1. Run project_validate to check for gaps",
+                "1. Run `everystack db:doctor` and `everystack db:authz:test --stage dev` to prove the RLS enforces the declared abilities",
                 "2. Test unauthenticated access returns 401",
                 "3. Test cross-user data isolation with RLS",
                 "4. Verify JWT claims propagate through pgSettings",
@@ -23402,6 +23410,7 @@ function renderFinding(f) {
 var import_path2 = require("path");
 var MIGRATION_SQL = /(?:^|\/)(?:drizzle|migrations)\/[^/]+\.sql$/i;
 var GENERATED_SCHEMA = /schema\.generated\.tsx?$/;
+var RETIRED_DB_SQL = /(?:^|\/)db\/sql\/[^/]+\.sql$/i;
 function rel(ctx, p) {
   try {
     return (0, import_path2.relative)(ctx.cwd, p) || p;
@@ -23413,8 +23422,8 @@ var handWrittenMigration = {
   id: "hand-written-migration",
   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 \u2014 protected stages take `db:plan` \u2192 `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 \u2014 and generated artifacts (schema.generated.ts) are never edited.",
-  conform: "edit db/models/ then `everystack db:sync` (dev) or `db:plan` \u2192 `db:apply` (protected) \xB7 db/sql/ for derived objects \xB7 db/backfills/ for data moves",
+  guide: "Nobody authors migrations. Schema changes have two homes: the WHOLE declared database \u2014 tables/constraints/authz (defineModel) AND functions/views/matviews (defineView/defineMaterializedView/defineFunction/defineSql descriptors) \u2014 lives in db/models/ (edit the declaration, then `everystack db:sync` on dev \u2014 protected stages take `db:plan` \u2192 `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 \u2014 raw-SQL derived objects moved into descriptors. No migration file, ever \u2014 and generated artifacts (schema.generated.ts) are never edited.",
+  conform: "edit db/models/ (Models + derived descriptors) then `everystack db:sync` (dev) or `db:plan` \u2192 `db:apply` (protected) \xB7 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) {
     if (ctx.tool !== "Write" && ctx.tool !== "Edit") return null;
@@ -23422,6 +23431,7 @@ var handWrittenMigration = {
     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 \u2014 db:check refuses hand edits)`;
+    if (RETIRED_DB_SQL.test(p)) return `${rel(ctx, p)} is in the retired db/sql home \u2014 declare it as a descriptor (defineView/defineMaterializedView/defineFunction/defineSql) in db/models/ instead; the CLI verbs fail on this directory`;
     return null;
   }
 };
@@ -23707,7 +23717,7 @@ async function runGovernanceCli(argv) {
 }
 
 // src/index.ts
-var version2 = (true ? "0.3.3" : null) ?? "0.3.0-dev";
+var version2 = (true ? "0.4.0" : null) ?? "0.3.0-dev";
 var INSTRUCTIONS = [
   "You govern how any agent builds everystack \u2014 a self-hosted application stack for Expo apps on AWS.",
   "Your job is not only to advise but to keep the build on-script: the architecture the maintainer",
@@ -23769,7 +23779,7 @@ var 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 \u2014 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 \u2014 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 \u2014 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 \u2014 never bundle large computed data into the app. NOBODY AUTHORS MIGRATIONS. Schema work has two homes: the WHOLE declared database \u2014 tables/constraints/authz (defineModel) AND functions/views/matviews (defineView/defineMaterializedView/defineFunction/defineSql descriptors) \u2014 is DECLARED in `db/models/` (edit the declaration, then `everystack db:sync` moves the dev database to the checkout \u2014 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 \u2014 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/dist/project-claude-md.md

@@ -19,12 +19,14 @@ 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.
-- **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
+- **Nobody authors migrations. Schema work has two homes.** The WHOLE declared database
+  lives in `db/models/`: tables and authz with `defineModel`, and the derived layer —
+  functions, views, matviews — as descriptors (`defineView` / `defineMaterializedView` /
+  `defineFunction` / `defineSql`, triggers via `trigger()` on the model). Edit the
+  declaration, then `everystack db:sync` moves the dev database to your checkout (state +
+  authz + derived, fingerprint-verified). 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
@@ -42,8 +44,8 @@ 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:sync`)
+- `db/models/` — the declared database: `defineModel` tables + derived descriptors
+  (`defineView`/`defineMaterializedView`/`defineFunction`/`defineSql`; 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)
@@ -84,9 +86,9 @@ Declare tables with `defineModel` (`field`, `can`, relations). A package's full
 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; `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
+views, matviews) follows the same rule: descriptors declare the structure (identity, deps,
+authz, security posture), the body stays `sql\`\``, and reconcile *deploys* it — 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.
 
@@ -118,7 +120,8 @@ Every feature starts with a failing test. Tests in `__tests__/` mirroring source
 
 - Don't bundle large data into the app — it lives in the DB, served by the API.
 - Don't hand-write migrations or edit `db/schema.ts` — edit the Model, run `db:generate`;
-  for functions/views/matviews edit `db/sql/` and run `db:reconcile`.
+  for functions/views/matviews edit the descriptors in `db/models/` and run `db:reconcile`
+  (`db/sql/` is retired — the verbs fail on it with the migration path).
 - Don't hand-write RLS — declare `can()` abilities.
 - Don't hand-roll a component that exists in `@everystack/ui`; don't use inline `StyleSheet`.
 - Don't put a secret behind `EXPO_PUBLIC_*` — that ships to the client.