@everystack/mcp 0.3.0 → 0.3.1

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
@@ -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.1" : 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",

package/dist/project-claude-md.md

@@ -38,6 +38,7 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 - `db/` — generated Drizzle schema + migrations (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
 

package/package.json

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

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

@@ -38,6 +38,7 @@ These are enforced (everystack cheat gates) and load-bearing. Do not work around
 - `db/` — generated Drizzle schema + migrations (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