@everystack/cli 0.3.11 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -37,6 +37,10 @@
       "types": "./src/cli/audit-source-api.ts",
       "default": "./src/cli/audit-source-api.ts"
     },
+    "./runbook": {
+      "types": "./src/cli/runbook/index.ts",
+      "default": "./src/cli/runbook/index.ts"
+    },
     "./client": {
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"

package/src/cli/commands/audit.ts

@@ -11,6 +11,7 @@
 import { resolveConfig, opsFunction } from '../config.js';
 import { runBundleAudit, runBundleWeightAudit, reportBundleAudit } from './bundle.js';
 import { runUiAudit, reportUiAudit } from './ui-audit.js';
+import { checkRunbook } from './runbook.js';
 import { resolveWeightBudget } from '../bundle-weight.js';
 import { runSecurityProbe, reportProbeResults } from './security-probe.js';
 import { auditDeployedSql, printReport, loadWaivers } from './security.js';
@@ -105,6 +106,25 @@ export async function auditCommand(flags: Record<string, string>): Promise<void>
     warn(`ui:audit skipped: ${err.message}`);
   }
 
+  // --- runbook --check (docs currency) — advisory, never gates -------------
+  // A stale operations manual must not block a deploy; it just gets named.
+  // Skipped silently when the cwd isn't an everystack app (remote-only audits).
+  try {
+    const check = await checkRunbook(flags['ui-dir'] || '.');
+    console.log('');
+    info('── runbook ──────────────────────────────────────────────────');
+    if (check.status === 'current') {
+      success('docs/RUNBOOK.md is current.');
+    } else if (check.status === 'missing') {
+      warn('docs/RUNBOOK.md is missing — generate it with `everystack runbook` (advisory; does not gate).');
+    } else {
+      warn('docs/RUNBOOK.md is stale — regenerate with `everystack runbook` (advisory; does not gate).');
+    }
+    ran.push('runbook (advisory)');
+  } catch {
+    // not an everystack project dir — nothing to check
+  }
+
   // --- audit:lighthouse (perf/SEO) — opt-in; heavy and informational -------
   if (flags.lighthouse) {
     console.log('');

package/src/cli/commands/runbook.ts

@@ -0,0 +1,175 @@
+/**
+ * `everystack runbook` — compile docs/RUNBOOK.md, the per-app operations manual.
+ *
+ * db:generate for documentation (docs/plans/everystack-runbook.md): pure
+ * detection → templates keyed by the app's reality → es:gen/es:slot merge that
+ * preserves human words. The pure core lives in ../runbook/; this shell is the
+ * IO: read the old file, load the app's Models for the data-model chapter,
+ * write/check/diff, map to exit codes.
+ *
+ *   everystack runbook            generate or update (slot content preserved)
+ *   everystack runbook --check    exit 1 if regeneration would change the file
+ *   everystack runbook --diff     name the sections that would change; write nothing
+ *   everystack runbook --force    overwrite hand-edits inside generated blocks
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { detectProjectReality } from '../runbook/detect.js';
+import { generateRunbook, type RunbookResult } from '../runbook/generate.js';
+import { renderDataModelSection } from '../runbook/model-section.js';
+import { parseRunbook, sha8 } from '../runbook/markers.js';
+import { fail, info, step, success, warn } from '../output.js';
+
+const OUT_REL = path.join('docs', 'RUNBOOK.md');
+
+/** This package's version, for the provenance stamp. tsx polyfills __dirname in ESM; ts-jest is CJS. */
+function cliVersion(): string {
+  try {
+    const dir = eval('__dirname') as string;
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, '..', '..', '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/** Import the app's Model barrel for the data-model chapter. Absent or unloadable → honest warning, no chapter. */
+async function loadDataModel(root: string, hasIndex: boolean): Promise<{ dataModel: string | null; warning: string | null }> {
+  if (!hasIndex) return { dataModel: null, warning: null };
+  const barrel = path.join(root, 'models', 'index.ts');
+  try {
+    const mod = await import(pathToFileURL(barrel).href);
+    const models = mod.models ?? mod.default;
+    if (!Array.isArray(models)) {
+      return { dataModel: null, warning: `models/index.ts exports no \`models\` array — data-model chapter skipped.` };
+    }
+    return { dataModel: renderDataModelSection(models), warning: null };
+  } catch (err: any) {
+    return {
+      dataModel: null,
+      warning: `Could not load models from ${barrel} (${err.message}) — data-model chapter skipped.`,
+    };
+  }
+}
+
+export interface RunbookRun {
+  outPath: string;
+  oldText: string | null;
+  result: RunbookResult;
+  modelWarning: string | null;
+}
+
+/** Result-producing core, shared by the command, `--check`, and the `audit` capstone. */
+export async function runRunbook(root: string): Promise<RunbookRun> {
+  const reality = detectProjectReality(root);
+  const { dataModel, warning } = await loadDataModel(reality.root, reality.models.hasIndex);
+  const outPath = path.join(reality.root, OUT_REL);
+  const oldText = fs.existsSync(outPath) ? fs.readFileSync(outPath, 'utf8') : null;
+  const result = generateRunbook(reality, { cliVersion: cliVersion(), dataModel }, oldText ?? undefined);
+  return { outPath, oldText, result, modelWarning: warning };
+}
+
+export interface RunbookCheck {
+  status: 'missing' | 'stale' | 'current';
+  conflicts: string[];
+}
+
+/** Is docs/RUNBOOK.md current? Pure read — writes nothing. */
+export async function checkRunbook(root: string): Promise<RunbookCheck> {
+  const { oldText, result } = await runRunbook(root);
+  if (oldText === null) return { status: 'missing', conflicts: [] };
+  return { status: result.changed ? 'stale' : 'current', conflicts: result.conflicts };
+}
+
+export interface RunbookDiffSummary {
+  added: string[];
+  removed: string[];
+  changed: string[];
+}
+
+/** Section-level diff: which gen blocks a regeneration would add, remove, or rewrite. */
+export function diffSummary(oldText: string, newText: string): RunbookDiffSummary {
+  const genShas = (text: string) =>
+    new Map(
+      parseRunbook(text).blocks.flatMap((b) => (b.kind === 'gen' ? [[b.id, sha8(b.content)] as const] : [])),
+    );
+  const before = genShas(oldText);
+  const after = genShas(newText);
+  return {
+    added: [...after.keys()].filter((id) => !before.has(id)),
+    removed: [...before.keys()].filter((id) => !after.has(id)),
+    changed: [...after.keys()].filter((id) => before.has(id) && before.get(id) !== after.get(id)),
+  };
+}
+
+export async function runbookCommand(flags: Record<string, string>): Promise<void> {
+  const root = flags.dir || '.';
+  let run: RunbookRun;
+  try {
+    run = await runRunbook(root);
+  } catch (err: any) {
+    fail(err.message);
+    process.exit(1);
+  }
+  if (run.modelWarning) warn(run.modelWarning);
+  const rel = path.relative(process.cwd(), run.outPath) || OUT_REL;
+
+  if ('check' in flags) {
+    if (run.oldText === null) {
+      fail(`${rel} is missing — run \`everystack runbook\` to generate it.`);
+      process.exit(1);
+    }
+    if (run.result.conflicts.length) {
+      warn(`Hand-edited generated section(s): ${run.result.conflicts.join(', ')} — move those words to a slot or Notes.`);
+    }
+    if (run.result.changed) {
+      fail(`${rel} is stale — run \`everystack runbook\` to regenerate.`);
+      process.exit(1);
+    }
+    success(`${rel} is current.`);
+    process.exit(0);
+  }
+
+  if ('diff' in flags) {
+    if (run.oldText === null) {
+      info(`${rel} does not exist yet — \`everystack runbook\` would create it.`);
+      process.exit(0);
+    }
+    if (!run.result.changed) {
+      success(`${rel} is current — nothing would change.`);
+      process.exit(0);
+    }
+    const summary = diffSummary(run.oldText, run.result.text);
+    if (summary.added.length) info(`sections added:   ${summary.added.join(', ')}`);
+    if (summary.removed.length) info(`sections removed: ${summary.removed.join(', ')}`);
+    if (summary.changed.length) info(`sections updated: ${summary.changed.join(', ')}`);
+    if (run.result.conflicts.length) {
+      warn(`hand-edits that would be overwritten: ${run.result.conflicts.join(', ')} (regenerate with --force)`);
+    }
+    process.exit(0);
+  }
+
+  // default: write
+  if (run.result.conflicts.length && !('force' in flags)) {
+    fail(
+      `Generated section(s) were hand-edited: ${run.result.conflicts.join(', ')}. ` +
+        'Move those words into a slot or the Notes section, or rerun with --force to overwrite them.',
+    );
+    process.exit(1);
+  }
+  if (run.oldText !== null && !run.result.changed) {
+    success(`${rel} is already current.`);
+    process.exit(0);
+  }
+  step(`Writing ${rel} ...`);
+  fs.mkdirSync(path.dirname(run.outPath), { recursive: true });
+  fs.writeFileSync(run.outPath, run.result.text);
+  success(
+    run.oldText === null
+      ? `${rel} generated. Fill the marked slots (overview, stage-notes, notes) — they survive every regeneration.`
+      : `${rel} regenerated. Slot content preserved.`,
+  );
+  process.exit(0);
+}

package/src/cli/index.ts

@@ -26,6 +26,7 @@ import { bundleAnalyzeCommand, bundleAuditCommand } from './commands/bundle.js';
 import { auditLighthouseCommand } from './commands/lighthouse.js';
 import { auditCommand } from './commands/audit.js';
 import { uiAuditCommand } from './commands/ui-audit.js';
+import { runbookCommand } from './commands/runbook.js';
 import { fail } from './output.js';
 
 const args = process.argv.slice(2);
@@ -242,6 +243,9 @@ async function main() {
       await uiAuditCommand(positional, flags);
       break;
     }
+    case 'runbook':
+      await runbookCommand(flags);
+      break;
     case 'secrets': {
       // secrets <subcommand> [positional...] [--flags]
       // Extract positional args: everything after subcommand that isn't a flag or flag value
@@ -305,6 +309,7 @@ Usage:
   everystack audit:lighthouse  [--stage <name>] [--host <url>] [--runs 3] [--path /] [--json out.json]  Mobile Lighthouse (perf/a11y/bp/seo), median over N runs
   everystack bundle:audit      [url|--dir <export>] [--stage <name>] [--values-from <.env>] [--leak-only] [--max-file-mb N] [--max-total-mb N] [--max-js-mb N] [--max-data-mb N]  Audit a bundle for leaked secrets AND weight (oversized assets, data that belongs in the DB, JS bloat) AND UI design-bloat (style repetition + hardcoded colors). A URL/stage weighs the remote bundle (assets sized via HEAD, no download); --dir scans a local export; --leak-only skips the weight gate
   everystack ui:audit          [dir] [--ui-repeat N] [--ui-color-repeat N]  Source-side UI design-bloat: styles copy-pasted across call sites, hardcoded colors that should be tokens, raw primitives reimplementing a ui component, oversized components, duplicated JSX. Located + fixable; advisory, never gates
+  everystack runbook           [--dir <root>] [--check] [--diff] [--force]  Compile docs/RUNBOOK.md, the per-app operations manual, from the app's detected reality (tier, Models, handlers). Regenerate after the app grows or an everystack upgrade; slot content survives. --check exits 1 if stale (CI); --diff names the sections that would change
   everystack certs:generate    [--output ./certs]
   everystack certs:configure   [--input ./certs] [--keyid main]
   everystack cache:purge       [--stage <name>]                  Bust all cached content (global epoch)

package/src/cli/runbook/detect.ts

@@ -0,0 +1,127 @@
+/**
+ * detectProjectReality — the runbook compiler's input, R0 of the runbook plan
+ * (docs/plans/everystack-runbook.md).
+ *
+ * Pure, local filesystem reads over a consumer app's root: which @everystack/*
+ * packages are installed (→ tier), whether Models/handlers/crons/migrations exist.
+ * No network, no AWS — purity is what makes `runbook --check` trustworthy in CI.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export type Tier = 'V1' | 'V2' | 'V3';
+
+export interface ProjectReality {
+  root: string;
+  /** package.json name. */
+  name: string;
+  tier: Tier;
+  /** Installed @everystack/* short names, sorted (e.g. ['api', 'cli', 'server']). */
+  packages: string[];
+  /** True when the app has a database story: models declared, a db/ dir, or the api package. */
+  hasDatabase: boolean;
+  models: {
+    /** Relative dir ('models') or null when absent. */
+    dir: string | null;
+    /** Model files (\.ts, excluding index.ts), sorted. */
+    files: string[];
+    hasIndex: boolean;
+  };
+  handlers: { api: boolean; worker: boolean; image: boolean };
+  /** Cron handler filenames under server/cron/, sorted. */
+  crons: string[];
+  hasSstConfig: boolean;
+  /** Expo Router app/ directory present. */
+  hasExpoApp: boolean;
+  /** Relative migrations dir ('drizzle' or 'db/migrations') or null. */
+  migrationsDir: string | null;
+}
+
+const V2_PACKAGES = new Set(['api', 'auth', 'admin', 'logging', 'security', 'query']);
+const V3_PACKAGES = new Set(['jobs', 'storage', 'images']);
+
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function listTs(dir: string): string[] {
+  if (!isDir(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.ts') || f.endsWith('.tsx'))
+    .sort();
+}
+
+export function detectProjectReality(root: string): ProjectReality {
+  const abs = path.resolve(root);
+  const pkgPath = path.join(abs, 'package.json');
+  if (!isFile(pkgPath)) {
+    throw new Error(`No package.json at ${abs} — run from the app root (or pass it).`);
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const deps: Record<string, string> = {
+    ...(pkg.dependencies ?? {}),
+    ...(pkg.devDependencies ?? {}),
+  };
+  const packages = Object.keys(deps)
+    .filter((d) => d.startsWith('@everystack/'))
+    .map((d) => d.slice('@everystack/'.length))
+    .sort();
+  if (packages.length === 0) {
+    throw new Error(`${pkgPath} has no @everystack/* dependencies — not an everystack app.`);
+  }
+
+  const tier: Tier = packages.some((p) => V3_PACKAGES.has(p))
+    ? 'V3'
+    : packages.some((p) => V2_PACKAGES.has(p))
+      ? 'V2'
+      : 'V1';
+
+  const modelsDir = path.join(abs, 'models');
+  const modelFiles = listTs(modelsDir).filter((f) => f !== 'index.ts');
+  const models = {
+    dir: isDir(modelsDir) ? 'models' : null,
+    files: modelFiles,
+    hasIndex: isFile(path.join(modelsDir, 'index.ts')),
+  };
+
+  const handlers = {
+    api: isFile(path.join(abs, 'server', 'api.ts')),
+    worker: isFile(path.join(abs, 'server', 'worker.ts')),
+    image: isFile(path.join(abs, 'server', 'image.ts')),
+  };
+  const crons = listTs(path.join(abs, 'server', 'cron'));
+
+  const migrationsDir = isDir(path.join(abs, 'drizzle'))
+    ? 'drizzle'
+    : isDir(path.join(abs, 'db', 'migrations'))
+      ? 'db/migrations'
+      : null;
+
+  return {
+    root: abs,
+    name: typeof pkg.name === 'string' && pkg.name ? pkg.name : path.basename(abs),
+    tier,
+    packages,
+    hasDatabase: models.files.length > 0 || isDir(path.join(abs, 'db')) || packages.includes('api'),
+    models,
+    handlers,
+    crons,
+    hasSstConfig: isFile(path.join(abs, 'sst.config.ts')),
+    hasExpoApp: isDir(path.join(abs, 'app')),
+    migrationsDir,
+  };
+}

package/src/cli/runbook/generate.ts

@@ -0,0 +1,81 @@
+/**
+ * generateRunbook — compile + merge, the runbook's db:generate.
+ *
+ * Fresh: reality → structure → text. Regenerate: the new structure defines the
+ * document; filled slot content carries over by name; content whose home
+ * disappeared (removed slots, text pasted outside any block) moves into Notes
+ * rather than being dropped; hand-edits inside generated blocks surface as
+ * conflicts (the caller decides whether to overwrite). Deterministic and
+ * idempotent: unchanged project → byte-identical output.
+ */
+
+import type { ProjectReality } from './detect.js';
+import { parseRunbook, composeRunbook, sha8, type Block } from './markers.js';
+import { buildStructure, headerStamp, PLACEHOLDER_PREFIX, type RunbookContext } from './sections.js';
+
+export interface RunbookResult {
+  text: string;
+  /** Section ids whose generated content was hand-edited in the old file. */
+  conflicts: string[];
+  /** False when the output is byte-identical to the provided old text. */
+  changed: boolean;
+}
+
+function isFilled(content: string): boolean {
+  const trimmed = content.trim();
+  return trimmed !== '' && !trimmed.startsWith(PLACEHOLDER_PREFIX);
+}
+
+export function generateRunbook(
+  reality: ProjectReality,
+  ctx: RunbookContext,
+  oldText?: string,
+): RunbookResult {
+  const blocks = buildStructure(reality, ctx);
+  const conflicts: string[] = [];
+
+  if (oldText !== undefined) {
+    const old = parseRunbook(oldText);
+
+    for (const b of old.blocks) {
+      if (b.kind === 'gen' && b.recordedSha && sha8(b.content) !== b.recordedSha) {
+        conflicts.push(b.id);
+      }
+    }
+
+    const oldSlots = new Map(
+      old.blocks.flatMap((b) => (b.kind === 'slot' ? [[b.name, b.content] as const] : [])),
+    );
+    const newSlotNames = new Set(blocks.flatMap((b) => (b.kind === 'slot' ? [b.name] : [])));
+
+    // Content with no home in the new structure is carried into Notes, never dropped.
+    const carries: string[] = [];
+    for (const [name, content] of oldSlots) {
+      if (!newSlotNames.has(name) && isFilled(content)) {
+        carries.push(`_Carried from removed slot \`${name}\`:_\n\n${content.trim()}`);
+      }
+    }
+    for (const orphan of old.orphans) {
+      carries.push(orphan);
+    }
+
+    for (const b of blocks) {
+      if (b.kind !== 'slot') continue;
+      const oldContent = oldSlots.get(b.name);
+      if (oldContent !== undefined && isFilled(oldContent)) b.content = oldContent;
+      if (b.name === 'notes' && carries.length > 0) {
+        const base = isFilled(b.content) ? [b.content] : [];
+        b.content = [...base, ...carries].join('\n\n');
+      }
+    }
+  }
+
+  const text = composeRunbook(headerStamp(reality, ctx), blocks);
+  return {
+    text,
+    conflicts,
+    changed: oldText === undefined ? true : text !== oldText,
+  };
+}
+
+export type { Block };

package/src/cli/runbook/index.ts

@@ -0,0 +1,20 @@
+/**
+ * `@everystack/cli/runbook` — the programmatic surface of the runbook compiler.
+ *
+ * db:generate for documentation (docs/plans/everystack-runbook.md): detect the
+ * app's reality, compile section templates keyed by it, merge over the existing
+ * docs/RUNBOOK.md preserving human slot content. Everything here is pure and
+ * local (no network, no AWS) except the thin IO in runRunbook/checkRunbook, so
+ * a consumer can assert runbook currency in their own tests/CI:
+ *
+ *   const { status } = await checkRunbook('.');
+ *   expect(status).toBe('current');
+ */
+
+export * from './detect.js';
+export * from './markers.js';
+export * from './sections.js';
+export * from './generate.js';
+export * from './model-section.js';
+export { runRunbook, checkRunbook, diffSummary } from '../commands/runbook.js';
+export type { RunbookRun, RunbookCheck, RunbookDiffSummary } from '../commands/runbook.js';

package/src/cli/runbook/markers.ts

@@ -0,0 +1,96 @@
+/**
+ * Runbook marker format — the mechanical seam between compiler-owned and
+ * human-owned content (docs/plans/everystack-runbook.md).
+ *
+ *   <!-- es:gen section=<id> sha=<sha8> -->   compiler-owned, replaced wholesale
+ *   <!-- es:slot name=<name> -->              human/agent-owned, preserved verbatim
+ *
+ * Markers are HTML comments, invisible in rendered markdown. Each gen block
+ * records the sha8 of its own content; a mismatch on re-parse means someone
+ * hand-edited a generated section — surfaced as a conflict, never silently lost.
+ */
+
+import crypto from 'node:crypto';
+
+export type Block =
+  | { kind: 'gen'; id: string; content: string; recordedSha?: string }
+  | { kind: 'slot'; name: string; content: string };
+
+export interface ParsedRunbook {
+  /** The provenance stamp line, or null if the file has none. */
+  header: string | null;
+  blocks: Block[];
+  /** Non-empty text found outside any block — carried into Notes on merge. */
+  orphans: string[];
+}
+
+export function sha8(content: string): string {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 8);
+}
+
+const HEADER_RE = /^<!-- everystack-runbook .* -->$/;
+const GEN_OPEN_RE = /^<!-- es:gen section=(\S+) sha=([0-9a-f]+) -->$/;
+const GEN_CLOSE = '<!-- /es:gen -->';
+const SLOT_OPEN_RE = /^<!-- es:slot name=(\S+) -->$/;
+const SLOT_CLOSE = '<!-- /es:slot -->';
+
+export function parseRunbook(text: string): ParsedRunbook {
+  const lines = text.split('\n');
+  const blocks: Block[] = [];
+  const orphans: string[] = [];
+  let header: string | null = null;
+  let orphanRun: string[] = [];
+
+  const flushOrphans = () => {
+    const chunk = orphanRun.join('\n').trim();
+    if (chunk) orphans.push(chunk);
+    orphanRun = [];
+  };
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (header === null && blocks.length === 0 && HEADER_RE.test(line)) {
+      header = line;
+      i++;
+      continue;
+    }
+    const gen = line.match(GEN_OPEN_RE);
+    const slot = gen ? null : line.match(SLOT_OPEN_RE);
+    if (gen || slot) {
+      flushOrphans();
+      const close = gen ? GEN_CLOSE : SLOT_CLOSE;
+      const content: string[] = [];
+      i++;
+      while (i < lines.length && lines[i] !== close) {
+        content.push(lines[i]);
+        i++;
+      }
+      // A missing close marker means a mangled file; treat the run as content anyway.
+      const body = content.join('\n');
+      if (gen) {
+        blocks.push({ kind: 'gen', id: gen[1], content: body, recordedSha: gen[2] });
+      } else {
+        blocks.push({ kind: 'slot', name: slot![1], content: body });
+      }
+      i++; // past the close marker
+      continue;
+    }
+    orphanRun.push(line);
+    i++;
+  }
+  flushOrphans();
+  return { header, blocks, orphans };
+}
+
+export function composeRunbook(header: string, blocks: Block[]): string {
+  const parts = [header];
+  for (const b of blocks) {
+    if (b.kind === 'gen') {
+      parts.push(`<!-- es:gen section=${b.id} sha=${sha8(b.content)} -->\n${b.content}\n${GEN_CLOSE}`);
+    } else {
+      parts.push(`<!-- es:slot name=${b.name} -->\n${b.content}\n${SLOT_CLOSE}`);
+    }
+  }
+  return parts.join('\n\n') + '\n';
+}

package/src/cli/runbook/sections.ts

@@ -0,0 +1,303 @@
+/**
+ * Runbook sections — templates keyed by the app's detected reality.
+ *
+ * Each section renders procedure-sized markdown (short prose + exact commands),
+ * conditioned on what the app actually has: a V1 static app gets no database
+ * chapter; crons render only the cron files that exist. Templates version with
+ * the cli package — upgrading everystack and regenerating diffs in what's new.
+ *
+ * Deliberately deterministic: same ProjectReality (+ optional data-model
+ * markdown) → same blocks, so `runbook --check` is trustworthy in CI.
+ */
+
+import type { ProjectReality } from './detect.js';
+import type { Block } from './markers.js';
+
+export interface RunbookContext {
+  cliVersion: string;
+  /** Pre-rendered "Your data model" markdown (from the app's Models), or null/absent. */
+  dataModel?: string | null;
+}
+
+/** All slot placeholders share this prefix — a slot still starting with it counts as unfilled. */
+export const PLACEHOLDER_PREFIX = '_(Fill in:';
+
+export function headerStamp(reality: ProjectReality, ctx: RunbookContext): string {
+  return `<!-- everystack-runbook cli:${ctx.cliVersion} tier:${reality.tier} packages:${reality.packages.join(',')} models:${reality.models.files.length} -->`;
+}
+
+function gen(id: string, lines: string[]): Block {
+  return { kind: 'gen', id, content: lines.join('\n') };
+}
+
+function slot(name: string, placeholder: string): Block {
+  return { kind: 'slot', name, content: placeholder };
+}
+
+const has = (r: ProjectReality, pkg: string) => r.packages.includes(pkg);
+
+function title(r: ProjectReality): Block {
+  return gen('title', [
+    `# Runbook — ${r.name}`,
+    '',
+    '> How to operate this app: configure, extend, deploy, monitor, maintain.',
+    `> Compiled by \`everystack runbook\` from the app's detected reality (tier ${r.tier}).`,
+    '> Generated sections belong to the compiler — change the app and regenerate;',
+    '> your words live in the marked slots and survive every regeneration.',
+  ]);
+}
+
+function prerequisites(r: ProjectReality): Block {
+  const lines = [
+    '## Prerequisites & configuration',
+    '',
+    '- Node 22+ and pnpm. Install dependencies: `pnpm install`.',
+    '- AWS credentials for the deploy profile (SST resolves them at deploy time).',
+    '- Secrets are per stage, stored in SSM — never in a committed `.env`:',
+    '  - `everystack secrets list --stage dev`',
+    '  - `everystack secrets set KEY "value" --stage dev`',
+    '  - `everystack secrets import .env.production --stage production`',
+    '- Never put a secret behind an `EXPO_PUBLIC_*` name — those compile into the',
+    '  client bundle forever. `everystack bundle:audit` will catch it; don\'t make it.',
+  ];
+  return gen('prerequisites', lines);
+}
+
+function projectMap(r: ProjectReality): Block {
+  const lines = ['## Project map', ''];
+  if (r.hasExpoApp) lines.push('- `app/` — Expo Router screens, navigation, API routes');
+  if (r.models.dir) {
+    lines.push(
+      `- \`${r.models.dir}/\` — \`defineModel\` tables (${r.models.files.length} model(s); the source of truth for schema + authz)`,
+    );
+  }
+  if (r.hasDatabase) lines.push('- `db/` — generated Drizzle schema (never edit by hand)');
+  if (r.migrationsDir) lines.push(`- \`${r.migrationsDir}/\` — generated migrations`);
+  if (r.handlers.api || r.handlers.worker || r.handlers.image || r.crons.length) {
+    const parts = [
+      r.handlers.api ? 'api.ts' : null,
+      r.handlers.worker ? 'worker.ts' : null,
+      r.handlers.image ? 'image.ts' : null,
+      r.crons.length ? 'cron/' : null,
+    ].filter(Boolean);
+    lines.push(`- \`server/\` — Lambda handlers (${parts.join(', ')})`);
+  }
+  if (r.hasSstConfig) lines.push('- `sst.config.ts` — AWS infrastructure definition');
+  lines.push('- `docs/RUNBOOK.md` — this file; regenerate with `everystack runbook`');
+  return gen('project-map', lines);
+}
+
+function dailyWorkflow(): Block {
+  return gen('daily-workflow', [
+    '## Daily workflow',
+    '',
+    '- `pnpm dev` — start the Expo dev server',
+    '- `pnpm test` — run the tests; every feature starts with a failing test',
+    '- Conventional commits (`feat:`, `fix:`, `chore:`, `docs:`); tests pass before commit',
+  ]);
+}
+
+function deploy(r: ProjectReality): Block {
+  const lines = [
+    '## Deploy & release',
+    '',
+    'Two release paths — know which one a change needs:',
+    '',
+    '- `everystack deploy --stage dev` — deploy infrastructure + server code (SST).',
+    '  Needed when server code, `sst.config.ts`, or native configuration changes.',
+    '- `everystack update --channel production --message "..."` — publish an OTA update',
+    '  (JS and assets only, no redeploy). The path for app-code changes.',
+    '- `everystack channels list` — see the channels that exist.',
+  ];
+  if (r.hasDatabase) {
+    lines.push('', 'After a deploy that includes new migrations: `everystack db:migrate --stage <name>`.');
+  }
+  return gen('deploy', lines);
+}
+
+function extend(r: ProjectReality): Block {
+  const lines = [
+    '## Extend the app the right way',
+    '',
+    'These paths match the enforced gates — the routes that are hard to do wrong:',
+    '',
+  ];
+  if (r.models.dir) {
+    lines.push(
+      '- **Add a table or field:** edit the Model in `models/`, run `everystack db:generate`,',
+      '  review the emitted migration, then `everystack db:migrate`. Never hand-write a SQL',
+      '  migration, never edit `db/schema.ts` — after any change `db:generate` must be a clean no-op.',
+      '- **Change who can read/write:** declare `can()` abilities on the Model — they compile',
+      '  to RLS + grants. Never hand-write `CREATE POLICY` or `GRANT`.',
+    );
+  } else if (r.hasDatabase) {
+    lines.push(
+      '- **Schema changes:** migrate to Models (`everystack db:pull` writes `models/` from the',
+      '  live database), then the flow is: edit Model → `everystack db:generate` → `db:migrate`.',
+    );
+  }
+  if (r.handlers.api) {
+    lines.push('- **Add an endpoint:** an `rpc` on the handler in `server/api.ts`.');
+  }
+  lines.push(
+    '- **Add a screen:** keep it thin — routing and composition only; reusable UI in shared',
+    '  components, logic in `lib/`. `everystack ui:audit` flags drift.',
+  );
+  if (r.hasDatabase) {
+    lines.push(
+      '- **Add data:** it lives in PostgreSQL, served by the API. Never bundle a data file',
+      '  into the app — `bundle:audit` gates it.',
+    );
+  } else {
+    lines.push(
+      '- **Need persistence or user accounts?** That is the V2 tier: add `@everystack/api` and',
+      '  `@everystack/auth`, declare Models, and regenerate this runbook for the database chapters.',
+    );
+  }
+  return gen('extend', lines);
+}
+
+function database(r: ProjectReality): Block {
+  return gen('database', [
+    '## Database operations',
+    '',
+    '- `everystack db:generate` — compile Models → next migration (schema + RLS + grants)',
+    '- `everystack db:migrate --stage <name>` — apply migrations on the deployed Lambda',
+    '- `everystack db:seed --stage dev` — seed the database (dev only)',
+    '- `everystack db:psql --stage dev` — psql into the stage database (credentials never exposed)',
+    '- `everystack db:doctor` — verify the security posture (RLS, roles, search_path)',
+    '',
+    'Backups & recovery:',
+    '',
+    '- `everystack db:backup [--stage <name>]` / `db:backups` — logical pg_dump to the private backups bucket',
+    '- `everystack db:restore --from <id> --confirm` — **destructive**: overwrites the stage database',
+    '- `everystack db:snapshot` / `db:snapshots` — physical RDS snapshot (instant DR)',
+  ]);
+}
+
+function auth(): Block {
+  return gen('auth', [
+    '## Auth operations',
+    '',
+    '- JWT auth with refresh tokens; tokens are minted server-side, never in the client.',
+    '- Rotating the JWT secret: `everystack secrets set JwtSecret <new> --stage <name>` then',
+    '  redeploy — existing sessions invalidate and users sign in again. Plan the window.',
+    '- OAuth provider credentials are per-stage secrets (`everystack secrets list` to see names).',
+  ]);
+}
+
+function monitoring(r: ProjectReality): Block {
+  const lines = [
+    '## Monitoring',
+    '',
+    '- `everystack logs:errors --stage <name>` — recent server errors with cause + stack (start here for any 5xx)',
+    '- `everystack logs:tail --stage <name>` — follow live logs',
+    '- `everystack logs:query --stage <name>` — search structured logs',
+  ];
+  if (has(r, 'admin')) {
+    lines.push('- Admin dashboard — Logs, Crashes, Issues, and Health screens over the same data');
+  }
+  return gen('monitoring', lines);
+}
+
+function security(): Block {
+  return gen('security', [
+    '## Security maintenance',
+    '',
+    'Run before a production deploy and after any migration:',
+    '',
+    '- `everystack security:audit` — white-box audit of the SQL surface',
+    '- `everystack db:doctor` — RLS, roles, and posture check',
+    '- `everystack db:authz:diff` — declared abilities vs live grants/policies',
+    '- `everystack security:probe --stage <name>` — live probing of the deployed surface',
+  ]);
+}
+
+function workers(r: ProjectReality): Block {
+  const lines = [
+    '## Workers & queues',
+    '',
+    '- Background jobs run on SQS workers (`server/worker.ts`); failed jobs land in the',
+    '  dead-letter queue — check it when work goes missing.',
+  ];
+  if (r.crons.length) {
+    lines.push(`- Scheduled work in \`server/cron/\`: ${r.crons.map((c) => `\`${c}\``).join(', ')}`);
+  }
+  return gen('workers', lines);
+}
+
+function storageImages(r: ProjectReality): Block {
+  const lines = ['## Storage & images', ''];
+  if (has(r, 'storage')) {
+    lines.push('- File uploads use presigned S3 URLs (`@everystack/storage`); ownership is enforced server-side.');
+  }
+  if (has(r, 'images') || r.handlers.image) {
+    lines.push('- Images are processed on demand (`server/image.ts`) and delivered via the CDN.');
+  }
+  lines.push('- `everystack cache:purge` after replacing public assets in place.');
+  return gen('storage-images', lines);
+}
+
+function audits(): Block {
+  return gen('audits', [
+    '## Keep it healthy',
+    '',
+    '- `everystack audit --stage <name>` — the capstone: security + bundle + ui checks, one exit code',
+    '- `everystack bundle:audit <url>` — secret/data leaks + bundle weight on what actually ships',
+    '- `everystack ui:audit` — source-side design bloat (advisory, `file:line` + fix)',
+    '- `everystack audit:lighthouse` — perf/SEO (informational)',
+    '- `everystack runbook --check` — is this document current?',
+  ]);
+}
+
+function troubleshoot(r: ProjectReality): Block {
+  const lines = [
+    '## Troubleshoot',
+    '',
+    '- `everystack diag` — environment + deployed-stack diagnosis',
+    '- Dev server misbehaving: restart with a clear cache — `npx expo start -c`',
+  ];
+  if (has(r, 'logging')) {
+    lines.push('- Deployed 5xx: `everystack logs:errors --stage <name>` first — it carries cause + stack.');
+  }
+  return gen('troubleshoot', lines);
+}
+
+/** The full ordered structure for a detected reality. Deterministic. */
+export function buildStructure(reality: ProjectReality, ctx: RunbookContext): Block[] {
+  const blocks: Block[] = [
+    title(reality),
+    slot(
+      'overview',
+      '_(Fill in: what this app is, who it serves, anything an operator should know first. An agent connected to the everystack MCP can fill this via the `runbook` prompt.)_',
+    ),
+    prerequisites(reality),
+    projectMap(reality),
+    dailyWorkflow(),
+    deploy(reality),
+    slot(
+      'stage-notes',
+      '_(Fill in: deployed URLs per stage, channel-to-stage mapping, release cadence.)_',
+    ),
+    extend(reality),
+  ];
+  if (reality.hasDatabase) {
+    blocks.push(database(reality));
+    if (ctx.dataModel) blocks.push({ kind: 'gen', id: 'data-model', content: ctx.dataModel });
+  }
+  if (has(reality, 'auth')) blocks.push(auth());
+  if (has(reality, 'logging')) blocks.push(monitoring(reality));
+  if (reality.hasDatabase) blocks.push(security());
+  if (has(reality, 'jobs') || reality.handlers.worker) blocks.push(workers(reality));
+  if (has(reality, 'storage') || has(reality, 'images') || reality.handlers.image) {
+    blocks.push(storageImages(reality));
+  }
+  blocks.push(audits(), troubleshoot(reality));
+  blocks.push(
+    slot(
+      'notes',
+      '_(Fill in: anything project-specific that does not fit a generated section — escalation contacts, oddities, tribal knowledge.)_',
+    ),
+  );
+  return blocks;
+}