@everystack/mcp 0.3.0 → 0.3.2

package/dist/index.cjs

@@ -23053,7 +23053,9 @@ function registerClaudeMdPrompt(server) {
                 '   hand-written migrations, "pass your Drizzle schema") instead of the v3 Model flow',
                 "   (`defineModel` \u2192 `everystack db:generate`)? Suggest the current conventions.",
                 "2. **Project drift** \u2014 do the Structure / Commands / package list match what is actually",
-                "   installed now (new packages, a new tier, a new models/ dir)? Suggest updates.",
+                "   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",
+                "   `everystack runbook --check`, suggest the `runbook` prompt.",
                 "3. **Contract-vs-gates drift** \u2014 is it missing any Non-negotiable the cheat gates enforce",
                 "   (data\u2192DB, generated migrations, declared authz, reuse @everystack/ui, secrets boundary)?",
                 "   Suggest adding it, so the human contract and the enforced rules agree.",
@@ -23078,6 +23080,73 @@ function registerClaudeMdPrompt(server) {
   );
 }
 
+// src/prompts/runbook.ts
+function registerRunbookPrompt(server) {
+  server.prompt(
+    "runbook",
+    "Generate or refresh docs/RUNBOOK.md \u2014 the operations manual compiled from the app's detected reality (tier, Models, handlers). Runs `everystack runbook`, then fills empty slots with app narrative (confirm-first). Regenerate after the app grows or an everystack upgrade.",
+    {
+      projectPath: external_exports.string().optional().describe("Absolute path to the project root (where docs/RUNBOOK.md lives)")
+    },
+    async ({ projectPath }) => {
+      const root = projectPath ?? ".";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: [
+                `Generate or refresh docs/RUNBOOK.md for the project at ${root}.`,
+                "",
+                "## What this is",
+                "",
+                "docs/RUNBOOK.md is the per-app operations manual \u2014 how to configure, extend, deploy,",
+                "monitor, and maintain THIS app. It is COMPILED, not authored: `everystack runbook`",
+                "derives it from the app's detected reality (installed packages \u2192 tier, Models,",
+                "handlers, crons) and regenerating after a change diffs in what's new. The division",
+                "of labor: CLAUDE.md is the terse contract (rules); the runbook is procedures.",
+                "",
+                "## Step 1 \u2014 run the compiler",
+                "",
+                `- If ${root}/docs/RUNBOOK.md exists, run \`everystack runbook --diff\` first and show`,
+                "  the human which sections would change.",
+                "- Then run `everystack runbook` to write it. If it reports hand-edited generated",
+                "  sections (a conflict), do NOT reach for --force \u2014 help the human move those words",
+                "  into a slot or the Notes section first, then regenerate. --force only with their",
+                "  explicit ok.",
+                "",
+                "## Step 2 \u2014 fill the EMPTY slots (and only the slots)",
+                "",
+                "The document has two kinds of content, mechanically marked:",
+                "- `<!-- es:gen section=... -->` blocks belong to the compiler. NEVER write inside one \u2014",
+                "  your words would be overwritten on the next regeneration, and the hash check flags it.",
+                "- `<!-- es:slot name=... -->` blocks are the human/agent seam and survive every",
+                "  regeneration. A slot still holding its `_(Fill in: ...)_` placeholder is empty.",
+                "",
+                "For each empty slot, draft content from what you know of the project:",
+                "- `overview` \u2014 what the app is, who it serves, what an operator should know first.",
+                "- `stage-notes` \u2014 deployed URLs per stage, channel-to-stage mapping, release cadence",
+                "  (read `.sst/outputs.json` or ask; do not guess URLs).",
+                "- `notes` \u2014 anything project-specific that fits nowhere else. Leave it if nothing real.",
+                "",
+                "Show the human your draft slot content and let them approve before writing \u2014 the",
+                "runbook is theirs; you assist, you do not own it.",
+                "",
+                "## Step 3 \u2014 verify",
+                "",
+                "Run `everystack runbook --check`: it must exit clean (slot edits never make it stale).",
+                "Tell the human: regenerate any time with `everystack runbook`; CI can enforce currency",
+                "with `--check`; after an everystack upgrade the diff reads as release notes for this app."
+              ].join("\n")
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
 // src/prompts/index.ts
 function registerPrompts(server) {
   registerNewAppPrompt(server);
@@ -23088,6 +23157,7 @@ function registerPrompts(server) {
   registerSecurePrompt(server);
   registerGovernanceSetupPrompt(server);
   registerClaudeMdPrompt(server);
+  registerRunbookPrompt(server);
 }
 
 // src/governance/grounding.ts
@@ -23341,9 +23411,9 @@ var handWrittenMigration = {
   id: "hand-written-migration",
   tier: "framework",
   severity: "deny",
-  guide: "Schema and migrations are generated from your Models \u2014 edit the Model and run db:generate, never hand-write SQL migrations or edit the generated schema.",
-  conform: "everystack db:generate",
-  verify: "everystack db:generate produces no diff (a clean no-op)",
+  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 \u2014 no migration file either way.",
+  conform: "everystack db:generate (tables) \xB7 everystack db:reconcile (functions/views/matviews in db/sql)",
+  verify: "everystack db:generate produces no diff AND everystack db:reconcile --check exits 0",
   detect(ctx) {
     if (ctx.tool !== "Write" && ctx.tool !== "Edit") return null;
     const p = ctx.filePath;
@@ -23635,7 +23705,7 @@ async function runGovernanceCli(argv) {
 }
 
 // src/index.ts
-var version2 = (true ? "0.3.0" : null) ?? "0.3.0-dev";
+var version2 = (true ? "0.3.2" : 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",
@@ -23697,7 +23767,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. Schema changes go through generated migrations (`db:generate`), never hand-written DDL. 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. 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` \u2014 never a hand-written migration either way. 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,9 +19,12 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 - **Data lives in PostgreSQL, served through the API — never bundle data into the app.** A
   large `.json`/`.csv` of computed data in the bundle is wrong; model it and serve it, or
   render an empty state if it does not exist yet.
-- **Schema and migrations are generated from Models.** Declare tables with `defineModel`
-  (in `models/`), run `everystack db:generate`. Never hand-write a SQL migration, never edit
-  the generated `db/schema.ts`. After any change, `db:generate` must be a clean no-op.
+- **Schema changes have two homes; neither is a hand-written migration.** Tables and authz
+  are generated from Models: declare with `defineModel` (in `db/models/`), run
+  `everystack db:generate` — never hand-write a SQL migration, never edit the generated
+  `db/schema.ts`; after any change `db:generate` must be a clean no-op. Functions, views,
+  and matviews are **authored** in `db/sql/` and **deployed** with `everystack db:reconcile`
+  — edit the SQL file, reconcile, done; `db:reconcile --check` must exit 0.
 - **Authorization is declared, not hand-written.** Use `can()` abilities on the Model; they
   compile to RLS + grants. Never hand-write `CREATE POLICY`/`GRANT`. RLS is required.
 - **Reuse `@everystack/ui`.** Do not hand-roll a component that already exists there. Style
@@ -32,12 +35,14 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 
 ## Start Here
 
-- `models/` — `defineModel` tables (the source of truth for schema + authz)
+- `db/models/` — `defineModel` tables (the source of truth for schema + authz)
+- `db/sql/` — functions, views, matviews (authored SQL; deploys via `db:reconcile`)
 - `app/` — Expo Router pages (screens, navigation, API routes)
 - `server/` — Lambda handlers (api.ts, worker.ts, image.ts)
-- `db/` — generated Drizzle schema + migrations (do not edit by hand)
+- `db/schema.generated.ts`, `drizzle/` — generated artifacts (do not edit by hand)
 - `lib/` — shared code (auth context, API client)
 - `sst.config.ts` — AWS infrastructure definition
+- `docs/RUNBOOK.md` — how to operate this app; regenerate with `everystack runbook`
 
 ## Structure
 
@@ -50,6 +55,7 @@ pnpm install                                 # Install dependencies
 pnpm dev                                     # Start the Expo dev server
 pnpm test                                    # Run all tests (TDD)
 everystack db:generate                       # Models → next migration (data + authz)
+everystack db:reconcile --apply              # Deploy functions/views/matviews from db/sql (no migrations)
 everystack db:migrate                        # Apply migrations on the deployed Lambda
 everystack db:seed                           # Seed the database (dev only)
 everystack deploy --stage dev                # Deploy infrastructure (SST)
@@ -66,7 +72,9 @@ Declare tables with `defineModel` (`field`, `can`, relations). A package's full
 `defineModule`; the app composes Modules. `everystack db:generate` compiles them to one
 migration (schema + RLS + grants); `deriveHandlerConfig(models)` derives the API config. You
 never hand-write migrations, RLS, or handler access-control — they are derived, so they cannot
-drift.
+drift. The derived layer (functions, views, matviews) is the exception that proves the rule:
+that SQL is authored, in `db/sql/`, and *deployed* with `db:reconcile` — hand-edits straight
+against the database surface as drift, and a comment-only edit is a no-op.
 
 ### Security over all else
 
@@ -95,7 +103,8 @@ Every feature starts with a failing test. Tests in `__tests__/` mirroring source
 ## What NOT to Do
 
 - 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`.
+- 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`.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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.6",
-    "@everystack/model": "0.3.3"
+    "@everystack/cli": "0.3.14",
+    "@everystack/model": "0.3.4"
   },
   "scripts": {
     "test": "jest",

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

@@ -5,6 +5,10 @@
  * (`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.
+ *
+ * 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.
  */
 
 import { relative } from 'path';
@@ -28,9 +32,9 @@ export const handWrittenMigration: CheatGate = {
   tier: 'framework',
   severity: 'deny',
   guide:
-    'Schema and migrations are generated from your Models — edit the Model and run db:generate, never hand-write SQL migrations or edit the generated schema.',
-  conform: 'everystack db:generate',
-  verify: 'everystack db:generate produces no diff (a clean no-op)',
+    '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',
   detect(ctx: ToolCallContext): string | null {
     if (ctx.tool !== 'Write' && ctx.tool !== 'Edit') return null;
     const p = ctx.filePath;

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 go through generated migrations (`db:generate`), never hand-written DDL. 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. 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_*`.',
   '5. When the user wants to start a new project, run check_environment (phase "local" for dev, "deploy" for deployment) to verify prerequisites.',
   '6. When the user needs to interact with deployed infrastructure, guide them to use the everystack CLI.',
 ].join('\n');

package/src/prompts/claude-md.ts

@@ -64,7 +64,9 @@ export function registerClaudeMdPrompt(server: McpServer): void {
                 '   hand-written migrations, "pass your Drizzle schema") instead of the v3 Model flow',
                 '   (`defineModel` → `everystack db:generate`)? 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.',
+                '   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',
+                '   `everystack runbook --check`, suggest the `runbook` prompt.',
                 '3. **Contract-vs-gates drift** — is it missing any Non-negotiable the cheat gates enforce',
                 '   (data→DB, generated migrations, declared authz, reuse @everystack/ui, secrets boundary)?',
                 '   Suggest adding it, so the human contract and the enforced rules agree.',

package/src/prompts/index.ts

@@ -7,6 +7,7 @@ import { registerDebugPrompt } from './debug.js';
 import { registerSecurePrompt } from './secure.js';
 import { registerGovernanceSetupPrompt } from './governance-setup.js';
 import { registerClaudeMdPrompt } from './claude-md.js';
+import { registerRunbookPrompt } from './runbook.js';
 
 export function registerPrompts(server: McpServer): void {
   registerNewAppPrompt(server);
@@ -17,4 +18,5 @@ export function registerPrompts(server: McpServer): void {
   registerSecurePrompt(server);
   registerGovernanceSetupPrompt(server);
   registerClaudeMdPrompt(server);
+  registerRunbookPrompt(server);
 }

package/src/prompts/runbook.ts

@@ -0,0 +1,77 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/**
+ * `runbook` — generate or refresh docs/RUNBOOK.md, the per-app operations manual.
+ *
+ * The compiler lives in the CLI (`everystack runbook` — db:generate for docs:
+ * detection → sections keyed by the app's reality → es:gen/es:slot merge). This
+ * prompt is the thin agent layer on top: run the compiler, then fill the EMPTY
+ * slots with app-specific narrative the compiler cannot know. Generated blocks
+ * belong to the compiler — the agent never writes inside them.
+ */
+export function registerRunbookPrompt(server: McpServer): void {
+  server.prompt(
+    'runbook',
+    'Generate or refresh docs/RUNBOOK.md — the operations manual compiled from the app\'s detected reality (tier, Models, handlers). Runs `everystack runbook`, then fills empty slots with app narrative (confirm-first). Regenerate after the app grows or an everystack upgrade.',
+    {
+      projectPath: z.string().optional().describe('Absolute path to the project root (where docs/RUNBOOK.md lives)'),
+    },
+    async ({ projectPath }) => {
+      const root = projectPath ?? '.';
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: [
+                `Generate or refresh docs/RUNBOOK.md for the project at ${root}.`,
+                '',
+                '## What this is',
+                '',
+                'docs/RUNBOOK.md is the per-app operations manual — how to configure, extend, deploy,',
+                'monitor, and maintain THIS app. It is COMPILED, not authored: `everystack runbook`',
+                'derives it from the app\'s detected reality (installed packages → tier, Models,',
+                'handlers, crons) and regenerating after a change diffs in what\'s new. The division',
+                'of labor: CLAUDE.md is the terse contract (rules); the runbook is procedures.',
+                '',
+                '## Step 1 — run the compiler',
+                '',
+                `- If ${root}/docs/RUNBOOK.md exists, run \`everystack runbook --diff\` first and show`,
+                '  the human which sections would change.',
+                '- Then run `everystack runbook` to write it. If it reports hand-edited generated',
+                '  sections (a conflict), do NOT reach for --force — help the human move those words',
+                '  into a slot or the Notes section first, then regenerate. --force only with their',
+                '  explicit ok.',
+                '',
+                '## Step 2 — fill the EMPTY slots (and only the slots)',
+                '',
+                'The document has two kinds of content, mechanically marked:',
+                '- `<!-- es:gen section=... -->` blocks belong to the compiler. NEVER write inside one —',
+                '  your words would be overwritten on the next regeneration, and the hash check flags it.',
+                '- `<!-- es:slot name=... -->` blocks are the human/agent seam and survive every',
+                '  regeneration. A slot still holding its `_(Fill in: ...)_` placeholder is empty.',
+                '',
+                'For each empty slot, draft content from what you know of the project:',
+                '- `overview` — what the app is, who it serves, what an operator should know first.',
+                '- `stage-notes` — deployed URLs per stage, channel-to-stage mapping, release cadence',
+                '  (read `.sst/outputs.json` or ask; do not guess URLs).',
+                '- `notes` — anything project-specific that fits nowhere else. Leave it if nothing real.',
+                '',
+                'Show the human your draft slot content and let them approve before writing — the',
+                'runbook is theirs; you assist, you do not own it.',
+                '',
+                '## Step 3 — verify',
+                '',
+                'Run `everystack runbook --check`: it must exit clean (slot edits never make it stale).',
+                'Tell the human: regenerate any time with `everystack runbook`; CI can enforce currency',
+                'with `--check`; after an everystack upgrade the diff reads as release notes for this app.',
+              ].join('\n'),
+            },
+          },
+        ],
+      };
+    },
+  );
+}

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

@@ -19,9 +19,12 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 - **Data lives in PostgreSQL, served through the API — never bundle data into the app.** A
   large `.json`/`.csv` of computed data in the bundle is wrong; model it and serve it, or
   render an empty state if it does not exist yet.
-- **Schema and migrations are generated from Models.** Declare tables with `defineModel`
-  (in `models/`), run `everystack db:generate`. Never hand-write a SQL migration, never edit
-  the generated `db/schema.ts`. After any change, `db:generate` must be a clean no-op.
+- **Schema changes have two homes; neither is a hand-written migration.** Tables and authz
+  are generated from Models: declare with `defineModel` (in `db/models/`), run
+  `everystack db:generate` — never hand-write a SQL migration, never edit the generated
+  `db/schema.ts`; after any change `db:generate` must be a clean no-op. Functions, views,
+  and matviews are **authored** in `db/sql/` and **deployed** with `everystack db:reconcile`
+  — edit the SQL file, reconcile, done; `db:reconcile --check` must exit 0.
 - **Authorization is declared, not hand-written.** Use `can()` abilities on the Model; they
   compile to RLS + grants. Never hand-write `CREATE POLICY`/`GRANT`. RLS is required.
 - **Reuse `@everystack/ui`.** Do not hand-roll a component that already exists there. Style
@@ -32,12 +35,14 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 
 ## Start Here
 
-- `models/` — `defineModel` tables (the source of truth for schema + authz)
+- `db/models/` — `defineModel` tables (the source of truth for schema + authz)
+- `db/sql/` — functions, views, matviews (authored SQL; deploys via `db:reconcile`)
 - `app/` — Expo Router pages (screens, navigation, API routes)
 - `server/` — Lambda handlers (api.ts, worker.ts, image.ts)
-- `db/` — generated Drizzle schema + migrations (do not edit by hand)
+- `db/schema.generated.ts`, `drizzle/` — generated artifacts (do not edit by hand)
 - `lib/` — shared code (auth context, API client)
 - `sst.config.ts` — AWS infrastructure definition
+- `docs/RUNBOOK.md` — how to operate this app; regenerate with `everystack runbook`
 
 ## Structure
 
@@ -50,6 +55,7 @@ pnpm install                                 # Install dependencies
 pnpm dev                                     # Start the Expo dev server
 pnpm test                                    # Run all tests (TDD)
 everystack db:generate                       # Models → next migration (data + authz)
+everystack db:reconcile --apply              # Deploy functions/views/matviews from db/sql (no migrations)
 everystack db:migrate                        # Apply migrations on the deployed Lambda
 everystack db:seed                           # Seed the database (dev only)
 everystack deploy --stage dev                # Deploy infrastructure (SST)
@@ -66,7 +72,9 @@ Declare tables with `defineModel` (`field`, `can`, relations). A package's full
 `defineModule`; the app composes Modules. `everystack db:generate` compiles them to one
 migration (schema + RLS + grants); `deriveHandlerConfig(models)` derives the API config. You
 never hand-write migrations, RLS, or handler access-control — they are derived, so they cannot
-drift.
+drift. The derived layer (functions, views, matviews) is the exception that proves the rule:
+that SQL is authored, in `db/sql/`, and *deployed* with `db:reconcile` — hand-edits straight
+against the database surface as drift, and a comment-only edit is a no-op.
 
 ### Security over all else
 
@@ -95,7 +103,8 @@ Every feature starts with a failing test. Tests in `__tests__/` mirroring source
 ## What NOT to Do
 
 - 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`.
+- 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`.
 - 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.