@everystack/mcp 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,94 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerResources } from './resources/index.js';
+import { registerTools } from './tools/index.js';
+import { registerPrompts } from './prompts/index.js';
+import { GOVERNANCE_COMMANDS, runGovernanceCli } from './governance/cli.js';
+const version = (typeof __MCP_VERSION__ === 'string' ? __MCP_VERSION__ : null) ?? '0.3.0-dev';
+const INSTRUCTIONS = [
+    'You govern how any agent builds everystack — 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',
+    'set up (Models/Modules, generated migrations, the ui package, the secrets boundary) is the way,',
+    'and the training-consensus shortcut (bundle the JSON, hand-write the migration, hand-roll a',
+    'component) is the cheat. The cheat gates enforce this structurally; you reinforce it in guidance.',
+    '',
+    '## Governance setup (do this once, early)',
+    '',
+    'This server is the knowledge + helpful path. The ENFORCEMENT (grounding gate + cheat gates) runs',
+    'as Claude Code hooks, NOT from this server alone. If the hooks are not installed, none of the',
+    'gates fire — so check and offer to install them at the start of work on an everystack project:',
+    '1. Look for the everystack governance hooks in the project\'s `.claude/settings.json` (a',
+    '   `hooks` block whose commands call `everystack-mcp gate`/`context`/`mark`/`validate`).',
+    '2. If they are absent, read this package\'s `hooks.example.json` and `docs/governance-setup.md`',
+    '   (in @everystack/mcp), then OFFER to merge the `hooks` block into `.claude/settings.json`.',
+    '3. NEVER install them silently — hooks run a shell command on every tool call. Show the human',
+    '   the exact block and the command form (workspace `npx tsx packages/mcp/src/index.ts <sub>` vs',
+    '   installed `everystack-mcp <sub>`), and let them confirm.',
+    '4. The `governance_setup` prompt produces the exact block for the current project.',
+    '',
+    '## The project contract (CLAUDE.md)',
+    '',
+    'The grounding gate has nothing to enforce without a project `CLAUDE.md` — and writing one is',
+    'what turns grounding ON (the nearest project CLAUDE.md is auto-required reading). Early in any',
+    'everystack project, ensure a CLAUDE.md exists AND is current:',
+    '- If it is missing, offer to scaffold it (the `claude_md` prompt; template at',
+    '  everystack://project-claude-md). It carries the non-negotiables the cheat gates enforce.',
+    '- If it exists, it is a living contract — as the project adds packages, models, or a tier, it',
+    '  drifts. Offer to reconcile it (also `claude_md`): suggest updates against the project reality',
+    '  and the current conventions, confirm-first, and never clobber the human\'s own content.',
+    '',
+    '## Beginner Detection',
+    '',
+    'Detect the user\'s experience level from context:',
+    '- If the user describes an app idea without technical terms, has no existing project, or asks basic questions ("how do I start?", "I want to build..."), treat them as a BEGINNER.',
+    '- If the user references specific packages, tiers (V1/V2/V3), tools (Drizzle, PostgREST, SST), or has an existing everystack project, treat them as a DEVELOPER.',
+    '',
+    '## Beginner Flow',
+    '',
+    'For beginners:',
+    '1. Read everystack://getting-started first. This is your guide for how to talk to beginners.',
+    '2. Ask what they want to build. Listen to their idea before anything technical. Do NOT categorize into tiers or ask them to choose V1/V2/V3.',
+    '3. Run check_environment with phase "local". Only V1 prerequisites matter now (Node.js, git, pnpm). PostgreSQL is NOT needed yet.',
+    '   Do NOT require AWS tools (AWS CLI, credentials, SST) upfront. The user will build and run locally first.',
+    '4. Walk through installing missing prerequisites ONE AT A TIME. Do not list them all at once. Install the first missing tool, confirm it works, then move to the next.',
+    '5. Create a stock Expo app: `npx create-expo-app@latest`, install V1 packages (`@everystack/server`, `@everystack/cli`, `@everystack/ui`), and `pnpm add -D sst`.',
+    '6. Run `npx expo start`. Read everystack://first-run for the walkthrough. The first milestone is seeing the app running in a browser.',
+    '7. Build together. Discuss what the app should look like. Create screens, navigation, components. Everything is static and visual.',
+    '8. When a feature needs user accounts or saved data, read everystack://adding-database. This introduces PostgreSQL, the API handler, auth, and database setup step by step.',
+    '9. When a feature needs file uploads or background tasks, add the relevant packages incrementally (everystack://storage, everystack://jobs, everystack://images).',
+    '10. When the user is ready to deploy to the internet, run check_environment with phase "deploy" and walk through AWS setup.',
+    '    For AWS credentials specifically, read everystack://aws-setup and walk them through account creation and IAM setup step by step.',
+    '11. Never use jargon without explaining it. "Lambda" is "the server that runs your code." "S3" is "file storage." "RDS" is "the database server." "CloudFront" is "the CDN that makes your app fast worldwide."',
+    '',
+    '## Developer Flow',
+    '',
+    'For experienced developers:',
+    '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_*`.',
+    '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');
+async function startServer() {
+    const server = new McpServer({ name: '@everystack/mcp', version }, { instructions: INSTRUCTIONS });
+    registerResources(server);
+    registerTools(server);
+    registerPrompts(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+async function main() {
+    const sub = process.argv[2];
+    // Hook-shim CLI: `everystack-mcp <context|gate|mark|validate|report>` reads hook JSON on stdin.
+    if (sub && GOVERNANCE_COMMANDS.includes(sub)) {
+        await runGovernanceCli(process.argv.slice(2));
+        return;
+    }
+    // Default: the stdio MCP server.
+    await startServer();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/project-claude-md.md

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

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAddFeaturePrompt(server: McpServer): void;
+//# sourceMappingURL=add-feature.d.ts.map

package/dist/prompts/add-feature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-feature.d.ts","sourceRoot":"","sources":["../../src/prompts/add-feature.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmHzE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+ChE"}

package/dist/prompts/add-feature.js

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+const FEATURES = {
+    auth: {
+        resource: 'everystack://auth',
+        packages: ['@everystack/auth'],
+        steps: [
+            'Install @everystack/auth',
+            'Create auth handlers with createAuthHandlers(db, schema, jwtSecret)',
+            'Add auth routes to Lambda handler (signup, signin, refresh, verify, signout)',
+            'Create lib/auth-context.tsx with AuthProvider and useAuth hook',
+            'Add pgSettings to handler config for RLS claim injection',
+            'Add signup and signin screens in app/',
+            'Set JwtSecret via SST secrets: `pnpm sst secret set JwtSecret "$(openssl rand -base64 32)" --stage dev`',
+        ],
+    },
+    jobs: {
+        resource: 'everystack://jobs',
+        packages: ['@everystack/jobs'],
+        steps: [
+            'Install @everystack/jobs',
+            'Create server/worker.ts with createWorkerHandler',
+            'Define job types and handlers',
+            'Add SQS queue to sst.config.ts',
+            'Create job adapter: createJobAdapter({ type: "sqs", queueUrl: Resource.Jobs.url })',
+            'Publish jobs from API handlers: jobClient.publish(type, payload)',
+            'Add dead letter queue for failed jobs',
+        ],
+    },
+    storage: {
+        resource: 'everystack://storage',
+        packages: ['@everystack/storage'],
+        steps: [
+            'Install @everystack/storage',
+            'Add S3 bucket for uploads to sst.config.ts',
+            'Add storagePlugin to handler plugins with MIME type validation',
+            'Add uploads table to schema (or use @everystack/storage/schema)',
+            'Client flow: request presigned URL → upload to S3 → confirm upload',
+            'Configure CDN delivery for public files',
+        ],
+    },
+    images: {
+        resource: 'everystack://images',
+        packages: ['@everystack/images'],
+        steps: [
+            'Install @everystack/images',
+            'Create server/image.ts with createImageHandler',
+            'Add image Lambda to sst.config.ts (needs sharp layer)',
+            'Add image_variants table to schema',
+            'Configure variant generation (thumb, medium, large)',
+            'Set up CDN delivery with format negotiation (WebP, AVIF)',
+        ],
+    },
+    admin: {
+        resource: 'everystack://admin',
+        packages: ['@everystack/admin'],
+        steps: [
+            'Install @everystack/admin',
+            'Create admin page in app/ using AdminRoot and AdminLayout',
+            'Define resource configs for each table (fields, columns, actions)',
+            'Use EverystackAdapter for API integration',
+            'Add admin role check to protect admin routes',
+            'Add dashboard RPCs via createAllDashboardRpcs',
+        ],
+    },
+    logging: {
+        resource: 'everystack://logging',
+        packages: ['@everystack/logging'],
+        steps: [
+            'Install @everystack/logging',
+            'Add loggingPlugin to handler plugins',
+            'Add logging schema tables to your schema exports',
+            'Configure S3 log storage in sst.config.ts',
+            'Add client SDK: createLoggingClient for crash reports and analytics',
+            'Add admin dashboard RPCs for log viewing',
+        ],
+    },
+    security: {
+        resource: 'everystack://security-device',
+        packages: ['@everystack/security'],
+        steps: [
+            'Install @everystack/security',
+            'Set up Apple App Attest (requires iOS 14+, real device)',
+            'Set up Google Play Integrity (requires Google Play Services)',
+            'Generate RS256 device keys on client',
+            'Add device attestation verification to auth flow',
+            'Store device keys in secure enclave/keystore',
+        ],
+    },
+    ssr: {
+        resource: 'everystack://ssr',
+        packages: [],
+        steps: [
+            'SSR is built into @everystack/server — no extra packages needed',
+            'Create SSR loader functions that query Drizzle directly',
+            'Add getWebHandler to Lambda for HTML rendering',
+            'Set up JSON-LD structured data for SEO',
+            'Add OG meta tags for social sharing',
+            'Configure cache headers per route',
+        ],
+    },
+    events: {
+        resource: 'everystack://events',
+        packages: [],
+        steps: [
+            'Events use PostgreSQL LISTEN/NOTIFY — built into the database',
+            'Create database trigger functions for table change notifications',
+            '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',
+        ],
+    },
+};
+export function registerAddFeaturePrompt(server) {
+    server.prompt('add-feature', 'Add an everystack feature to an existing project. Provides step-by-step instructions for auth, jobs, storage, images, admin, logging, security, SSR, or events.', {
+        feature: z.enum(['auth', 'jobs', 'storage', 'images', 'admin', 'logging', 'security', 'ssr', 'events'])
+            .describe('Feature to add'),
+        projectPath: z.string().optional().describe('Absolute path to project root'),
+    }, async ({ feature, projectPath }) => {
+        const f = FEATURES[feature];
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: [
+                            `Add ${feature} to ${projectPath ? 'the project at ' + projectPath : 'my everystack project'}.`,
+                            '',
+                            '## Instructions',
+                            '',
+                            `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.` : '',
+                            '',
+                            '## Steps',
+                            '',
+                            ...f.steps.map((s, i) => `${i + 1}. ${s}`),
+                            '',
+                            f.packages.length > 0 ? `## Install\n\n\`\`\`bash\npnpm add ${f.packages.join(' ')}\n\`\`\`` : '',
+                            '',
+                            '## After Setup',
+                            '',
+                            '- Run tests to verify the integration',
+                            '- Run project_validate to check for configuration issues',
+                            '- Read the relevant resource docs for advanced configuration',
+                        ].filter(Boolean).join('\n'),
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/prompts/claude-md.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * `claude_md` — create or reconcile the project's CLAUDE.md.
+ *
+ * The CLAUDE.md is the project contract. Writing it activates the grounding gate
+ * (the nearest project CLAUDE.md is auto-required). But a contract is a living
+ * document — it drifts from reality as the project grows. So this prompt is
+ * bidirectional: scaffold it when missing, and review + suggest updates when it
+ * exists (a drift check on the contract itself), never clobbering human content.
+ */
+export declare function registerClaudeMdPrompt(server: McpServer): void;
+//# sourceMappingURL=claude-md.d.ts.map

package/dist/prompts/claude-md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-md.d.ts","sourceRoot":"","sources":["../../src/prompts/claude-md.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAiF9D"}

package/dist/prompts/claude-md.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+/**
+ * `claude_md` — create or reconcile the project's CLAUDE.md.
+ *
+ * The CLAUDE.md is the project contract. Writing it activates the grounding gate
+ * (the nearest project CLAUDE.md is auto-required). But a contract is a living
+ * document — it drifts from reality as the project grows. So this prompt is
+ * bidirectional: scaffold it when missing, and review + suggest updates when it
+ * exists (a drift check on the contract itself), never clobbering human content.
+ */
+export function registerClaudeMdPrompt(server) {
+    server.prompt('claude_md', 'Create or keep the project CLAUDE.md current. Missing → scaffold from the everystack contract. Exists → review against the project reality + the cheat-gate rules and suggest updates (confirm-first, never clobber). Writing it activates the grounding gate.', {
+        projectPath: z.string().optional().describe('Absolute path to the project root (where CLAUDE.md lives)'),
+    }, async ({ projectPath }) => {
+        const root = projectPath ?? '.';
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: [
+                            `Create or reconcile the CLAUDE.md for the project at ${root}.`,
+                            '',
+                            '## Why this matters',
+                            '',
+                            'CLAUDE.md is this project\'s contract. The grounding gate auto-requires the nearest',
+                            'project CLAUDE.md — so writing it is what turns grounding ON (the agent must read it',
+                            'before editing). A contract also drifts as the project grows, so it must be kept current.',
+                            '',
+                            '## Step 1 — detect the project reality',
+                            '',
+                            `- Read ${root}/package.json: which @everystack/* packages are installed (tier: V1 server/cli/ui;`,
+                            '  V2 adds api/auth/admin/logging/security/query; V3 adds jobs/storage/images).',
+                            `- Check for a models/ directory (defineModel files) and a db/ directory.`,
+                            `- Note the project name and what the app does.`,
+                            '',
+                            '## Step 2 — read the template',
+                            '',
+                            'Read the everystack://project-claude-md resource. It is the everystack contract: the',
+                            'Non-negotiables (which mirror the cheat gates), Key Principles, Commands, and the',
+                            'What NOT to Do list. Fill {PROJECT_NAME}, {ONE_LINE_DESCRIPTION}, {ANNOTATED_DIRECTORY_TREE}',
+                            'and tailor Structure/Commands to the packages actually installed.',
+                            '',
+                            `## Step 3 — does ${root}/CLAUDE.md already exist?`,
+                            '',
+                            '### If it does NOT exist → scaffold',
+                            '',
+                            `- Write ${root}/CLAUDE.md from the template, tailored to the detected reality.`,
+                            '- Keep it tight and load-bearing — a wall of prose gets read as scenery. Lead with the',
+                            '  Non-negotiables.',
+                            '- Tell the human: this activates the grounding gate; new sessions must read it first.',
+                            '',
+                            '### If it EXISTS → review and suggest updates (DO NOT clobber)',
+                            '',
+                            'Reconcile the existing CLAUDE.md against three things, and propose a concrete diff:',
+                            '1. **Framework drift** — does it teach superseded ways (e.g. `drizzle-kit generate`,',
+                            '   hand-written migrations, a migration journal, "pass your Drizzle schema") instead of',
+                            '   the migration-authority flow (`defineModel` in db/models/ → `everystack db:sync` on',
+                            '   dev; `db:plan` → `db:apply` on protected stages; `db:check` in CI; data moves in',
+                            '   db/backfills/ via `db:backfill`)? Suggest the current conventions.',
+                            '2. **Project drift** — do the Structure / Commands / package list match what is actually',
+                            '   installed now (new packages, a new tier, a new models/ dir)? Suggest updates. Also',
+                            '   check the operations manual: if docs/RUNBOOK.md is missing, or stale per',
+                            '   `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.',
+                            '',
+                            'Rules for reconciling:',
+                            '- **Preserve all human/project-specific content** — project rules, domain notes, the',
+                            '  REQUIRED-READS line. Only update the framework/structure/commands sections and flag gaps.',
+                            '- **Propose, then confirm.** Show the human the suggested changes (a diff) and let them',
+                            '  approve before writing. The CLAUDE.md is theirs; you assist, you do not own it.',
+                            '- **Only flag real drift**, not cosmetic rewording.',
+                            '',
+                            '## Step 4 — confirm',
+                            '',
+                            'After writing/updating, confirm the file is at the project root so the grounding gate',
+                            'picks it up, and summarize what changed.',
+                        ].join('\n'),
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/prompts/debug.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDebugPrompt(server: McpServer): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/prompts/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/prompts/debug.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoI3D"}

package/dist/prompts/debug.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+export function registerDebugPrompt(server) {
+    server.prompt('debug', 'Systematic debugging for common everystack issues. Provides diagnostic steps based on the symptom.', {
+        symptom: z.string().describe('Description of the problem (e.g., "401 on all API requests", "RLS blocking reads", "Lambda timeout")'),
+        projectPath: z.string().optional().describe('Absolute path to project root'),
+    }, async ({ symptom, projectPath }) => {
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: [
+                            `Debug this issue: ${symptom}`,
+                            '',
+                            '## 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.` : '',
+                            '',
+                            '## Diagnostic Framework',
+                            '',
+                            'Work through these categories systematically:',
+                            '',
+                            '### 1. Authentication Issues (401/403)',
+                            '',
+                            'If the symptom involves authentication or authorization:',
+                            '',
+                            '- **Check token flow:**',
+                            '  - Is the JWT being sent in the Authorization header?',
+                            '  - Is the token expired? Decode at jwt.io and check `exp`',
+                            '  - Does `auth.verifyToken` return a valid payload?',
+                            '',
+                            '- **Check publicRoutes:**',
+                            '  - Is the route supposed to be public? Check `auth.publicRoutes` in handler config',
+                            '  - Is the RPC in `auth.publicRpc`?',
+                            '',
+                            '- **Check pgSettings:**',
+                            '  - Is `pgSettings` configured in the handler?',
+                            '  - Does it set `role` and `request.jwt.claims`?',
+                            '  - Test with: `SELECT current_setting(\'request.jwt.claims\', true);`',
+                            '',
+                            '### 2. RLS Issues (empty results, permission denied)',
+                            '',
+                            'Read everystack://security for RLS debugging.',
+                            '',
+                            '- **Check RLS is enabled:**',
+                            '  ```sql',
+                            '  SELECT tablename, rowsecurity FROM pg_tables WHERE schemaname = \'public\';',
+                            '  ```',
+                            '',
+                            '- **Check policies exist:**',
+                            '  ```sql',
+                            '  SELECT * FROM pg_policies WHERE schemaname = \'public\';',
+                            '  ```',
+                            '',
+                            '- **Test as specific role:**',
+                            '  ```sql',
+                            '  SET LOCAL ROLE authenticated;',
+                            '  SELECT set_config(\'request.jwt.claims\', \'{"sub":"user-id","role":"authenticated"}\', true);',
+                            '  SELECT * FROM your_table;',
+                            '  ```',
+                            '',
+                            '- **Common RLS mistakes:**',
+                            '  - Policy references wrong claim path (sub vs user_id)',
+                            '  - USING clause doesn\'t match the data (e.g., UUID vs text comparison)',
+                            '  - Missing policy for the operation (SELECT exists but not INSERT)',
+                            '  - Forgot `WITH CHECK` on INSERT/UPDATE policies',
+                            '',
+                            '### 3. Query Issues (wrong data, missing relations)',
+                            '',
+                            'Read everystack://query-protocol for filter syntax.',
+                            '',
+                            '- **Check relations config:**',
+                            '  - Does the handler `relations` config match the Drizzle schema relations?',
+                            '  - Is the relation direction correct (from/to)?',
+                            '',
+                            '- **Check column names:**',
+                            '  - Handler uses camelCase by default. Database uses snake_case.',
+                            '  - Check `naming` option in handler config.',
+                            '',
+                            '### 4. Deployment Issues',
+                            '',
+                            'Read everystack://deployment and everystack://cli.',
+                            '',
+                            '- **Lambda errors:**',
+                            '  ```bash',
+                            '  everystack logs:errors --stage dev',
+                            '  everystack logs:tail --stage dev',
+                            '  ```',
+                            '',
+                            '- **Database connection:**',
+                            '  ```bash',
+                            '  everystack db:psql --stage dev',
+                            '  everystack diag --stage dev',
+                            '  ```',
+                            '',
+                            '- **Common deployment issues:**',
+                            '  - Missing secrets: `pnpm sst secret list --stage dev`',
+                            '  - VPC configuration: Lambda can\'t reach RDS without proper VPC setup',
+                            '  - Bundle size: Check if unnecessary packages are bundled',
+                            '',
+                            '### 5. Performance Issues',
+                            '',
+                            '- **Slow queries:**',
+                            '  - Check for missing indexes on filtered/joined columns',
+                            '  - Check `maxLimit` and `maxEmbedDepth` in handler config',
+                            '  - Use `EXPLAIN ANALYZE` on slow queries',
+                            '',
+                            '- **Cold starts:**',
+                            '  - Minimize Lambda bundle size',
+                            '  - Use provisioned concurrency for production',
+                            '',
+                            '## Resolution',
+                            '',
+                            'After diagnosing:',
+                            '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',
+                        ].filter(Boolean).join('\n'),
+                    },
+                },
+            ],
+        };
+    });
+}

package/dist/prompts/deploy.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDeployPrompt(server: McpServer): void;
+//# sourceMappingURL=deploy.d.ts.map

package/dist/prompts/deploy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.d.ts","sourceRoot":"","sources":["../../src/prompts/deploy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0H5D"}