@synapsor/runner 0.1.0-alpha.4 → 0.1.0-alpha.5

package/dist/runner.mjs

@@ -1180,6 +1180,7 @@ function isRecord(value) {
 // packages/mcp-server/src/index.ts
 import crypto from "node:crypto";
 import fs from "node:fs";
+import { createServer } from "node:http";
 import path from "node:path";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -2684,7 +2685,7 @@ function createMcpRuntime(config, options = {}) {
 }
 function createSynapsorMcpServer(runtime) {
   const server = new McpServer(
-    { name: "synapsor-runner", version: "0.1.0-alpha.4" },
+    { name: "synapsor-runner", version: "0.1.0-alpha.5" },
     { capabilities: { tools: {}, resources: {} } }
   );
   if (runtime.config.mode === "cloud") {
@@ -2778,6 +2779,233 @@ async function serveStdio(options = {}) {
     process.once("SIGTERM", close);
   });
 }
+async function startHttpMcpServer(options = {}) {
+  const host = options.host ?? "127.0.0.1";
+  const port = options.port ?? 8765;
+  const authTokenEnv = options.authTokenEnv ?? "SYNAPSOR_RUNNER_HTTP_TOKEN";
+  const env = options.env ?? process.env;
+  const devNoAuth = options.devNoAuth === true;
+  if (devNoAuth && !isLoopbackHost(host)) {
+    throw new McpRuntimeError("HTTP_DEV_NO_AUTH_UNSAFE_HOST", "--dev-no-auth is only allowed with localhost or 127.0.0.1.");
+  }
+  const authToken = devNoAuth ? void 0 : env[authTokenEnv];
+  if (!devNoAuth && !authToken) {
+    throw new McpRuntimeError("HTTP_AUTH_TOKEN_MISSING", `${authTokenEnv} is not set. HTTP MCP requires bearer auth by default.`);
+  }
+  const config = options.config ?? loadRuntimeConfigFromFile(options.configPath);
+  const cloudTools = config.mode === "cloud" ? await fetchCloudToolMetadata(config, env) : void 0;
+  const runtime = createMcpRuntime(config, {
+    env,
+    storePath: options.storePath,
+    readRow: options.readRow,
+    cloudTools
+  });
+  const server = createServer((request, response) => {
+    void handleHttpMcpRequest({
+      request,
+      response,
+      runtime,
+      authToken,
+      devNoAuth,
+      corsOrigin: options.corsOrigin
+    });
+  });
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, host, () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+  } catch (error) {
+    runtime.close();
+    throw error;
+  }
+  const address = server.address();
+  const actualHost = address.address === "::" ? host : address.address;
+  const actualPort = address.port;
+  const url = `http://${actualHost}:${actualPort}/mcp`;
+  if (options.log !== false) {
+    const log = options.log ?? process.stderr;
+    log.write(`Synapsor Runner HTTP MCP listening on ${url}
+`);
+    log.write(devNoAuth ? "Auth: disabled for localhost development only\n" : `Auth: bearer token from ${authTokenEnv}
+`);
+    log.write(`Config: ${options.configPath ?? "synapsor.runner.json"}
+`);
+    log.write(`Store: ${options.storePath ?? config.storage?.sqlite_path ?? "./.synapsor/local.db"}
+`);
+  }
+  return {
+    host: actualHost,
+    port: actualPort,
+    url,
+    close: () => closeHttpServer(server, runtime)
+  };
+}
+async function handleHttpMcpRequest(input) {
+  const { request, response, runtime, authToken, devNoAuth, corsOrigin } = input;
+  try {
+    setCommonHttpHeaders(response, corsOrigin);
+    if (request.method === "OPTIONS" && corsOrigin) {
+      response.statusCode = 204;
+      response.end();
+      return;
+    }
+    const url = new URL(request.url ?? "/", "http://localhost");
+    if (request.method === "GET" && url.pathname === "/healthz") {
+      writeJson(response, 200, {
+        ok: true,
+        transport: "http",
+        tools: runtime.listTools().length,
+        mode: runtime.config.mode
+      });
+      return;
+    }
+    if (url.pathname !== "/mcp") {
+      writeJson(response, 404, { ok: false, error: "not_found" });
+      return;
+    }
+    if (request.method !== "POST") {
+      writeJson(response, 405, { ok: false, error: "method_not_allowed" });
+      return;
+    }
+    if (!devNoAuth && !validBearerToken(request.headers.authorization, authToken ?? "")) {
+      writeJson(response, 401, { ok: false, error: "unauthorized" });
+      return;
+    }
+    const body = await readRequestBody(request);
+    const payload = JSON.parse(body);
+    if (!isRecord3(payload)) {
+      writeJson(response, 400, jsonRpcError(null, -32600, "JSON-RPC request must be an object."));
+      return;
+    }
+    const id = payload.id ?? null;
+    const method = typeof payload.method === "string" ? payload.method : void 0;
+    if (!method) {
+      writeJson(response, 400, jsonRpcError(id, -32600, "JSON-RPC method is required."));
+      return;
+    }
+    const result = await handleHttpJsonRpcMethod(runtime, method, isRecord3(payload.params) ? payload.params : {});
+    writeJson(response, 200, {
+      jsonrpc: "2.0",
+      id,
+      result: sanitizeHttpPayload(result, authToken)
+    });
+  } catch (error) {
+    const message = sanitizeHttpError(error, authToken);
+    writeJson(response, 200, jsonRpcError(null, -32e3, message));
+  }
+}
+async function handleHttpJsonRpcMethod(runtime, method, params) {
+  if (method === "tools/list") {
+    return {
+      tools: runtime.listTools().map(httpToolMetadata)
+    };
+  }
+  if (method === "tools/call") {
+    const name = typeof params.name === "string" ? params.name : void 0;
+    if (!name) throw new McpRuntimeError("HTTP_TOOL_NAME_REQUIRED", "tools/call requires params.name.");
+    const args = isRecord3(params.arguments) ? params.arguments : isRecord3(params.args) ? params.args : {};
+    return await toolCallResult(runtime, name, args);
+  }
+  if (method === "resources/read") {
+    const uri = typeof params.uri === "string" ? params.uri : void 0;
+    if (!uri) throw new McpRuntimeError("HTTP_RESOURCE_URI_REQUIRED", "resources/read requires params.uri.");
+    return resourceResult(uri, runtime.readResource);
+  }
+  throw new McpRuntimeError("HTTP_JSONRPC_METHOD_UNSUPPORTED", `Unsupported MCP HTTP method: ${method}`);
+}
+function httpToolMetadata(tool) {
+  return {
+    name: tool.name,
+    title: tool.title,
+    description: tool.description,
+    inputSchema: tool.input_schema,
+    annotations: {
+      ...tool.annotations,
+      raw_sql_exposed: false,
+      approval_or_commit_tool: false
+    },
+    _meta: {
+      "synapsor.raw_sql_exposed": false,
+      "synapsor.approval_tool": false,
+      "synapsor.database_credentials_exposed": false,
+      "synapsor.model_controlled_tenant_authority": false
+    }
+  };
+}
+function validBearerToken(header, expected) {
+  if (!header?.startsWith("Bearer ")) return false;
+  const actual = header.slice("Bearer ".length);
+  const actualBuffer = Buffer.from(actual);
+  const expectedBuffer = Buffer.from(expected);
+  return actualBuffer.length === expectedBuffer.length && crypto.timingSafeEqual(actualBuffer, expectedBuffer);
+}
+function setCommonHttpHeaders(response, corsOrigin) {
+  response.setHeader("content-type", "application/json; charset=utf-8");
+  if (corsOrigin) {
+    response.setHeader("access-control-allow-origin", corsOrigin);
+    response.setHeader("access-control-allow-methods", "POST, GET, OPTIONS");
+    response.setHeader("access-control-allow-headers", "authorization, content-type");
+  }
+}
+function writeJson(response, statusCode, payload) {
+  response.statusCode = statusCode;
+  response.end(`${JSON.stringify(payload, null, 2)}
+`);
+}
+async function readRequestBody(request) {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    bytes += buffer.length;
+    if (bytes > 1024 * 1024) {
+      throw new McpRuntimeError("HTTP_BODY_TOO_LARGE", "HTTP MCP request body exceeds 1 MiB.");
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function jsonRpcError(id, code, message) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: { code, message }
+  };
+}
+function sanitizeHttpError(error, authToken) {
+  const raw = error instanceof Error ? error.message : String(error);
+  return sanitizeHttpString(raw, authToken);
+}
+function sanitizeHttpPayload(value, authToken) {
+  if (typeof value === "string") return sanitizeHttpString(value, authToken);
+  if (Array.isArray(value)) return value.map((item) => sanitizeHttpPayload(item, authToken));
+  if (isRecord3(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, sanitizeHttpPayload(item, authToken)]));
+  }
+  return value;
+}
+function sanitizeHttpString(value, authToken) {
+  let redacted = value.replace(/(?:postgres(?:ql)?|mysql):\/\/[^\s"']+/gi, "[redacted-database-url]");
+  if (authToken) redacted = redacted.split(authToken).join("[redacted-token]");
+  return redacted;
+}
+function isLoopbackHost(host) {
+  return host === "127.0.0.1" || host === "localhost" || host === "::1";
+}
+async function closeHttpServer(server, runtime) {
+  await new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  }).finally(() => {
+    runtime.close();
+  });
+}
 async function toolCallResult(runtime, toolName, args) {
   try {
     const structuredContent = await runtime.callTool(toolName, args);
@@ -4863,7 +5091,7 @@ async function startPolling(config, adapters2, signal) {
 // apps/runner/src/local-ui.ts
 import crypto4 from "node:crypto";
 import fs2 from "node:fs/promises";
-import { createServer } from "node:http";
+import { createServer as createServer2 } from "node:http";
 import path2 from "node:path";
 async function startLocalUiServer(options = {}) {
   const host = options.host ?? "127.0.0.1";
@@ -4874,7 +5102,7 @@ async function startLocalUiServer(options = {}) {
   const storePath = path2.resolve(options.storePath ?? "./.synapsor/local.db");
   const token = options.token ?? crypto4.randomBytes(24).toString("base64url");
   const csrfToken = options.csrfToken ?? crypto4.randomBytes(24).toString("base64url");
-  const server = createServer(async (request, response) => {
+  const server = createServer2(async (request, response) => {
     try {
       await handleRequest({ request, response, configPath, storePath, token, csrfToken, tour: options.tour === true });
     } catch (error) {
@@ -5940,7 +6168,9 @@ async function runInitWizard(args, options = {}) {
   const ask = options.ask ?? askTtyQuestion;
   const stdout = options.stdout ?? process2.stdout;
   stdout.write("Synapsor Runner guided init\n");
-  stdout.write("Use a staging or disposable Postgres/MySQL database first. The wizard stores environment-variable names, not credentials.\n\n");
+  stdout.write("Use a staging or disposable Postgres/MySQL database first. The wizard stores environment-variable names, not credentials.\n");
+  stdout.write("Flow: inspect database -> create trusted context -> create capability -> expose MCP tool.\n\n");
+  stdout.write("Step 1: Inspect database metadata\n");
   const engineInput = await askChoice(ask, "Engine", optionalArg(args, "--engine") ?? "auto", ["postgres", "mysql", "auto"]);
   const databaseInput = databaseInputFromArgs(args);
   if (databaseInput.inlineUrl) {
@@ -5963,21 +6193,27 @@ async function runInitWizard(args, options = {}) {
     stdout.write(`  - ${table2.schema}.${table2.name} (${table2.type}, pk=${table2.primary_key.join(",") || "none"}, tenant=${table2.suggestions.tenant_columns.join(",") || "none"})
 `);
   }
-  const tableName = await askDefault(ask, "Table/view for this capability", optionalArg(args, "--table") ?? tables[0]?.name ?? "");
+  stdout.write("\nStep 2: Create trusted context\n");
+  stdout.write("Choose the source object and trusted scope. Tenant and principal values come from your backend/session, not from the model.\n");
+  const tableName = await askDefault(ask, "Source table/view for this context", optionalArg(args, "--table") ?? tables[0]?.name ?? "");
   const table = findInspectionTable(inspection, tableName, schema);
   if (!table) throw new Error(`table not found in inspection: ${schema}.${tableName}`);
   const columns = table.columns.map((column) => column.name);
   const primaryKey = await askColumn(ask, "Primary-key column", optionalArg(args, "--primary-key") ?? table.primary_key[0] ?? inferPrimaryKeyCandidate(table), columns);
   const suggestedTenant = optionalArg(args, "--tenant-key") ?? table.suggestions.tenant_columns[0];
-  const tenantAnswer = await askDefault(ask, "Tenant/scope column. Leave blank only for a reviewed single-tenant dev source", suggestedTenant ?? "");
+  const tenantAnswer = await askDefault(ask, "Trusted tenant/scope column", suggestedTenant ?? "");
   const singleTenantDev = !tenantAnswer && (await askDefault(ask, "No tenant column selected. Type yes to mark this as a single-tenant dev source", "no")).toLowerCase() === "yes";
   if (!tenantAnswer && !singleTenantDev) throw new Error("tenant/scope column is required unless single-tenant dev source is explicitly confirmed");
   if (tenantAnswer && !columns.includes(tenantAnswer)) throw new Error(`tenant column ${tenantAnswer} does not exist on ${table.schema}.${table.name}`);
-  const mode = await askChoice(ask, "Mode", optionalArg(args, "--mode") ?? "read_only", ["read_only", "shadow", "review"]);
+  const tenantEnv = await askEnvName(ask, "Trusted tenant env var", optionalArg(args, "--tenant-env") ?? "SYNAPSOR_TENANT_ID");
+  const principalEnv = await askEnvName(ask, "Trusted principal env var", optionalArg(args, "--principal-env") ?? "SYNAPSOR_PRINCIPAL");
+  stdout.write("\nStep 3: Create capability\n");
+  stdout.write("Name the semantic tool the model can call. Table, key, visible fields, and mode define what that capability can do.\n");
+  const mode = await askChoice(ask, "Capability mode", optionalArg(args, "--mode") ?? "read_only", ["read_only", "shadow", "review"]);
   const conflictAnswer = mode === "read_only" ? optionalArg(args, "--conflict-column") ?? "" : await askDefault(ask, "Conflict/version column", optionalArg(args, "--conflict-column") ?? table.suggestions.conflict_columns[0] ?? "");
   if (conflictAnswer && !columns.includes(conflictAnswer)) throw new Error(`conflict column ${conflictAnswer} does not exist on ${table.schema}.${table.name}`);
   const defaultVisible = table.suggestions.default_visible_columns.join(",");
-  let visibleColumns = parseColumnList(await askDefault(ask, "Read-visible columns", optionalArg(args, "--visible-columns") ?? defaultVisible));
+  let visibleColumns = parseColumnList(await askDefault(ask, "Capability read-visible columns", optionalArg(args, "--visible-columns") ?? defaultVisible));
   ensureColumnsExist(visibleColumns, columns, "visible");
   if (mode !== "read_only" && !conflictAnswer) {
     const weak = await askDefault(ask, "No conflict/version column selected. Type yes to continue with a weak guard", "no");
@@ -6045,8 +6281,6 @@ async function runInitWizard(args, options = {}) {
   const namespace = await askDefault(ask, "Capability namespace", optionalArg(args, "--namespace") ?? recipeSpec?.namespace ?? "source");
   const objectName = await askDefault(ask, "Business object name", optionalArg(args, "--object-name") ?? recipeSpec?.object_name ?? safeObjectName(table.name));
   const lookupArg = await askDefault(ask, "Model-visible object id argument", optionalArg(args, "--lookup-arg") ?? recipeSpec?.lookup_arg ?? `${objectName}_id`);
-  const tenantEnv = await askEnvName(ask, "Trusted tenant env var", optionalArg(args, "--tenant-env") ?? "SYNAPSOR_TENANT_ID");
-  const principalEnv = await askEnvName(ask, "Trusted principal env var", optionalArg(args, "--principal-env") ?? "SYNAPSOR_PRINCIPAL");
   const writeUrlEnv = mode === "review" ? await askEnvName(ask, "Write URL env var for trusted apply path", optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL") : optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL";
   const approvalRole = mode === "read_only" ? "local_reviewer" : await askDefault(ask, "Required approval role", optionalArg(args, "--approval-role") ?? recipeSpec?.approval?.required_role ?? "local_reviewer");
   const spec = {
@@ -6084,6 +6318,8 @@ async function runInitWizard(args, options = {}) {
   const generated = generateRunnerConfigFromSpec(spec);
   const tools2 = generated.config.capabilities.map((capability) => `${capability.name} (${capability.kind})`);
   stdout.write("\nPreview:\n");
+  stdout.write(`  trusted context: tenant from ${tenantEnv}${singleTenantDev ? " (single-tenant dev source)" : tenantAnswer ? ` via ${tenantAnswer}` : ""}; principal from ${principalEnv}
+`);
   stdout.write(`  source: ${inspection.engine} ${table.schema}.${table.name}
 `);
   stdout.write(`  mode: ${mode}
@@ -7741,7 +7977,7 @@ async function cloudConnect(args) {
     return 1;
   }
   const runnerId = String(parsed.cloud.runner_id || process2.env.SYNAPSOR_RUNNER_ID || "synapsor_runner_local").trim();
-  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.4").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.5").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -7791,6 +8027,7 @@ async function cloudConnect(args) {
 async function mcp(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "serve") return mcpServe(rest);
+  if (subcommand === "serve-http") return mcpServeHttp(rest);
   if (subcommand === "audit") return mcpAudit(rest);
   if (subcommand === "config") return mcpConfig(rest);
   if (subcommand === "configure") return mcpConfigure(rest);
@@ -7836,17 +8073,91 @@ async function onboard(args) {
 }
 async function demo(args) {
   const [subcommand] = args;
+  if (subcommand === "inspect") return demoInspect(args.slice(1));
   if (subcommand && !subcommand.startsWith("-") && subcommand !== "reference-support-billing") {
     usage(["demo"]);
     return 2;
   }
-  if (args.includes("--quick")) return quickDemo();
+  if (args.includes("--quick")) return quickDemo(args);
   return prepareReferenceDemo(args);
 }
-async function quickDemo() {
+async function quickDemo(args) {
+  const allowed = /* @__PURE__ */ new Set(["--quick", "--guided", "--no-interactive", "--details", "--json"]);
+  assertKnownOptions(args, allowed, "demo --quick");
   const seeded = await seedQuickDemoStore(quickDemoStorePath);
-  process2.stdout.write([
-    "Synapsor Runner quick demo",
+  const summary = quickDemoSummary(seeded);
+  if (args.includes("--json")) {
+    process2.stdout.write(`${JSON.stringify(summary, null, 2)}
+`);
+    return 0;
+  }
+  if (args.includes("--details")) {
+    process2.stdout.write(formatQuickDemoDetails(seeded));
+    return 0;
+  }
+  const canPauseForInput = Boolean(process2.stdin.isTTY && process2.stdout.isTTY && !process2.env.CI && !process2.env.VITEST);
+  const forceConcise = args.includes("--no-interactive");
+  const forceGuided = args.includes("--guided") && !forceConcise;
+  const shouldGuide = forceGuided || canPauseForInput && !forceConcise;
+  if (shouldGuide) {
+    await runGuidedQuickDemo(seeded, { pause: canPauseForInput });
+    return 0;
+  }
+  process2.stdout.write(formatQuickDemoConcise(seeded));
+  return 0;
+}
+async function demoInspect(args) {
+  const allowed = /* @__PURE__ */ new Set(["--npx", "--json"]);
+  assertKnownOptions(args, allowed, "demo inspect");
+  const seeded = await seedQuickDemoStore(quickDemoStorePath);
+  const commands = quickDemoInspectCommands(args.includes("--npx"));
+  if (args.includes("--json")) {
+    process2.stdout.write(`${JSON.stringify({ ...quickDemoSummary(seeded), commands }, null, 2)}
+`);
+    return 0;
+  }
+  process2.stdout.write(formatQuickDemoInspect(commands));
+  return 0;
+}
+function quickDemoSummary(seeded) {
+  return {
+    mode: "fixture_only",
+    store: quickDemoStorePath,
+    proposal_id: seeded.proposal_id,
+    evidence_bundle_id: seeded.evidence_bundle_id,
+    replay_id: seeded.replay_id,
+    model_tool: "billing.propose_late_fee_waiver",
+    business_object: "invoice:INV-3001",
+    proposed_change: { late_fee_cents: { before: 5500, after: 0 } },
+    source_database_changed: false,
+    approval: "required outside MCP"
+  };
+}
+function formatQuickDemoConcise(seeded) {
+  void seeded;
+  return [
+    "Synapsor quick demo complete.",
+    "",
+    "The model asked to waive a late fee:",
+    'billing.propose_late_fee_waiver(invoice_id="INV-3001")',
+    "",
+    "Result:",
+    "* proposal created",
+    "* source DB changed: no",
+    "* approval required outside MCP",
+    "* evidence + replay saved locally",
+    "",
+    "Local ledger:",
+    quickDemoStorePath,
+    "",
+    "Next:",
+    `${cliCommandName()} demo inspect`,
+    ""
+  ].join("\n");
+}
+function formatQuickDemoDetails(seeded) {
+  return [
+    "Synapsor Runner quick demo is ready.",
     "",
     "This is a fixture-only first look. It does not start Docker, connect a database,",
     "or require an MCP client. It writes an inspectable local ledger fixture to:",
@@ -7881,25 +8192,209 @@ async function quickDemo() {
     "",
     "Replay:",
     `${seeded.replay_id} captures the local proposal, evidence handle, query audit, and events.`,
+    `Proposal id: ${seeded.proposal_id}`,
+    `Evidence id: ${seeded.evidence_bundle_id}`,
+    "",
+    "What this proves:",
+    "* The model gets a business tool, not raw SQL.",
+    "* The model created a proposal, not a write.",
+    "* Source DB changed: no.",
+    "* You can inspect evidence and replay locally.",
     "",
-    "Inspect this local fixture:",
-    `${cliCommandName()} proposals show latest --store ${quickDemoStorePath}`,
-    `${cliCommandName()} evidence show ${seeded.evidence_bundle_id} --store ${quickDemoStorePath}`,
-    `${cliCommandName()} activity search --object invoice:INV-3001 --store ${quickDemoStorePath}`,
-    `${cliCommandName()} replay show --proposal ${seeded.proposal_id} --store ${quickDemoStorePath}`,
+    "Try:",
+    `1. ${cliCommandName()} proposals show latest --store ${quickDemoStorePath}`,
+    `2. ${cliCommandName()} activity search --object invoice:INV-3001 --store ${quickDemoStorePath}`,
+    `3. ${cliCommandName()} replay show latest --store ${quickDemoStorePath}`,
     "",
-    "Approve the fixture outside MCP:",
-    `${cliCommandName()} proposals approve latest --yes --store ${quickDemoStorePath}`,
-    `${cliCommandName()} replay show latest --store ${quickDemoStorePath}`,
+    "For full reviewer detail:",
+    `${cliCommandName()} replay show latest --details --store ${quickDemoStorePath}`,
     "",
     "For real guarded writeback against disposable Postgres:",
     `${cliCommandName()} demo`,
+    ""
+  ].join("\n");
+}
+async function runGuidedQuickDemo(seeded, options) {
+  const screens = quickDemoGuidedScreens(seeded);
+  for (const [index, screen] of screens.entries()) {
+    printStep(screen.title, screen.body, index + 1, screens.length);
+    if (index < screens.length - 1) {
+      await waitForEnter("Press Enter to continue...", options);
+    }
+  }
+}
+function quickDemoGuidedScreens(seeded) {
+  return [
+    {
+      title: "Synapsor Runner quick demo",
+      body: [
+        "This teaches the Synapsor safety model without Docker, a database, or an MCP client.",
+        "",
+        "It also creates a local fixture ledger you can inspect."
+      ]
+    },
+    {
+      title: "The risky default",
+      body: [
+        "Many database MCP demos expose this:",
+        "",
+        "execute_sql(sql: string)",
+        "",
+        "That means the model can receive database authority directly."
+      ]
+    },
+    {
+      title: "The Synapsor boundary",
+      body: [
+        "Synapsor gives the model business tools instead:",
+        "",
+        "billing.inspect_invoice(invoice_id)",
+        "billing.propose_late_fee_waiver(invoice_id, reason)",
+        "",
+        "The model can ask for a business change.",
+        "It cannot commit the write."
+      ]
+    },
+    {
+      title: "What the agent requested",
+      body: [
+        'billing.propose_late_fee_waiver(invoice_id="INV-3001")',
+        "",
+        "Proposed change:",
+        "late_fee_cents: 5500 -> 0",
+        "",
+        "Source DB changed:",
+        "no"
+      ]
+    },
+    {
+      title: "What Synapsor saved",
+      body: [
+        "Synapsor saved:",
+        "",
+        "- proposal: what the model requested",
+        "- evidence: what data supported it",
+        "- query audit: what was read",
+        "- replay: what happened later",
+        "",
+        `Proposal: ${seeded.proposal_id}`,
+        `Evidence: ${seeded.evidence_bundle_id}`,
+        `Replay: ${seeded.replay_id}`,
+        "",
+        "Local ledger:",
+        quickDemoStorePath
+      ]
+    },
+    {
+      title: "Inspect it",
+      body: [
+        "Run this next:",
+        "",
+        "npx -y -p @synapsor/runner@alpha synapsor demo inspect",
+        "",
+        "demo inspect shows the proposal, evidence, activity search, and replay commands.",
+        "",
+        "If installed globally, use:",
+        "synapsor demo inspect"
+      ]
+    },
+    {
+      title: "Next paths",
+      body: [
+        "Full disposable Postgres demo:",
+        `${cliCommandName()} demo`,
+        "",
+        "Audit risky MCP database tools:",
+        `${cliCommandName()} audit --example dangerous-db-mcp`,
+        "",
+        "Use your own staging DB:",
+        'export DATABASE_URL="postgres://..."',
+        `${cliCommandName()} inspect --from-env DATABASE_URL`,
+        "",
+        "Done. You just saw Synapsor's core boundary: business tools for the model, approval/writeback outside the model, and replay for inspection."
+      ]
+    }
+  ];
+}
+function printStep(title, body, index, total) {
+  const divider = "------------------------------------------------------------";
+  process2.stdout.write([
+    "",
+    divider,
+    `Step ${index}/${total}: ${title}`,
+    divider,
     "",
-    "Audit risky MCP database tools:",
-    `${cliCommandName()} audit --example dangerous-db-mcp`,
+    ...body,
     ""
   ].join("\n"));
-  return 0;
+}
+async function waitForEnter(message, options) {
+  if (!options.pause) {
+    process2.stdout.write(`${message}
+`);
+    return;
+  }
+  const rl = readline.createInterface({ input: process2.stdin, output: process2.stdout });
+  try {
+    await rl.question(`${message} `);
+  } finally {
+    rl.close();
+  }
+}
+function quickDemoInspectCommands(useNpx) {
+  const cmd = useNpx ? "npx -y -p @synapsor/runner@alpha synapsor" : cliCommandName();
+  return [
+    {
+      label: "Proposal summary",
+      description: "See what the model asked to change.",
+      command: `${cmd} proposals show latest --store ${quickDemoStorePath}`
+    },
+    {
+      label: "Evidence",
+      description: "Inspect rows and evidence items captured for the proposal.",
+      command: `${cmd} evidence show ev_quick_INV_3001 --store ${quickDemoStorePath}`
+    },
+    {
+      label: "Activity search",
+      description: "Find the local ledger records for invoice INV-3001.",
+      command: `${cmd} activity search --object invoice:INV-3001 --store ${quickDemoStorePath}`
+    },
+    {
+      label: "Replay",
+      description: "Replay the local proposal/evidence/audit story.",
+      command: `${cmd} replay show latest --store ${quickDemoStorePath}`
+    },
+    {
+      label: "Approve outside MCP",
+      description: "Approve the proposal through the local operator boundary.",
+      command: `${cmd} proposals approve latest --yes --store ${quickDemoStorePath}`
+    },
+    {
+      label: "Full Docker-backed demo",
+      description: "Run the disposable Postgres-backed proof.",
+      command: `${cmd} demo`
+    },
+    {
+      label: "Audit risky MCP database tools",
+      description: "Review common dangerous MCP tool shapes.",
+      command: `${cmd} audit --example dangerous-db-mcp`
+    }
+  ];
+}
+function formatQuickDemoInspect(commands) {
+  return [
+    "Quick demo inspection",
+    "",
+    "Local ledger:",
+    quickDemoStorePath,
+    "",
+    ...commands.flatMap((item, index) => [
+      `${index + 1}. ${item.label}`,
+      `   ${item.description}`,
+      `   ${item.command}`,
+      ""
+    ])
+  ].join("\n");
 }
 async function seedQuickDemoStore(storePath) {
   const resolved = path3.resolve(storePath);
@@ -8062,6 +8557,41 @@ async function mcpServe(args) {
   });
   return 0;
 }
+async function mcpServeHttp(args) {
+  const configPath = optionalArg(args, "--config") ?? process2.env.SYNAPSOR_MCP_CONFIG;
+  const readOnly = args.includes("--read-only");
+  const config = readOnly ? { ...await readRuntimeConfig(configPath ?? defaultConfigPath), mode: "read_only" } : void 0;
+  const host = optionalArg(args, "--host") ?? "127.0.0.1";
+  const port = Number(optionalArg(args, "--port") ?? "8765");
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error("--port must be an integer from 1 to 65535");
+  }
+  if (host === "0.0.0.0") {
+    process2.stderr.write("Warning: binding Synapsor Runner HTTP MCP to 0.0.0.0 exposes model-facing tools on the network. Use TLS, private networking, authentication, and rate limits.\n");
+  }
+  const server = await startHttpMcpServer({
+    configPath,
+    config,
+    storePath: optionalArg(args, "--store") ?? process2.env.SYNAPSOR_LOCAL_STORE,
+    host,
+    port,
+    authTokenEnv: optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
+    devNoAuth: args.includes("--dev-no-auth"),
+    corsOrigin: optionalArg(args, "--cors-origin")
+  });
+  process2.stderr.write("Press Ctrl+C to stop.\n");
+  await new Promise((resolve) => {
+    const stop = async () => {
+      process2.off("SIGINT", stop);
+      process2.off("SIGTERM", stop);
+      await server.close();
+      resolve();
+    };
+    process2.once("SIGINT", stop);
+    process2.once("SIGTERM", stop);
+  });
+  return 0;
+}
 async function mcpAudit(args) {
   const format = optionalArg(args, "--format") ?? (args.includes("--json") ? "json" : "text");
   if (!["text", "json", "markdown"].includes(format)) {
@@ -9018,6 +9548,7 @@ async function proposalsList(args) {
   }
 }
 async function proposalsShow(args) {
+  assertKnownOptions(args, showAllowedOptions, "proposals show");
   const proposalId = positional(args, 0);
   if (!proposalId) throw new Error("proposals show requires <proposal_id>");
   const store = await openLocalStore(args);
@@ -9030,12 +9561,12 @@ async function proposalsShow(args) {
     if (args.includes("--json")) {
       process2.stdout.write(`${JSON.stringify(payload, null, 2)}
 `);
-    } else {
+    } else if (showDetails(args)) {
       process2.stdout.write(formatProposalDetail(proposal, evidence2?.items.length));
-      for (const event of payload.events) {
-        process2.stdout.write(`event ${event.event_id}: ${event.kind} by ${event.actor} at ${event.created_at}
-`);
-      }
+      process2.stdout.write(formatProposalEventDetail(payload.events));
+      if (args.includes("--debug")) process2.stdout.write(formatProposalDebug(proposal, optionalArg(args, "--store")));
+    } else {
+      process2.stdout.write(formatProposalFirstLook(proposal, evidence2?.items.length, proposalId, storeOptionSuffix(args)));
     }
     return 0;
   } finally {
@@ -9151,7 +9682,8 @@ async function evidenceShow(args) {
     if (!evidence2) throw new Error(`evidence bundle not found: ${evidenceId}`);
     if (args.includes("--json")) process2.stdout.write(`${JSON.stringify(evidence2, null, 2)}
 `);
-    else process2.stdout.write(formatEvidenceDetail(evidence2));
+    else if (showDetails(args)) process2.stdout.write(formatEvidenceDetail(evidence2));
+    else process2.stdout.write(formatEvidenceFirstLook(evidence2, storeOptionSuffix(args)));
     return 0;
   } finally {
     store.close();
@@ -9187,7 +9719,7 @@ async function queryAuditList(args) {
     if (args.includes("--json")) process2.stdout.write(`${JSON.stringify({ query_audit: rows }, null, 2)}
 `);
     else if (rows.length === 0) process2.stdout.write("No query audit records found.\n");
-    else for (const row of rows) process2.stdout.write(formatQueryAuditSummary(row));
+    else for (const row of rows) process2.stdout.write(formatQueryAuditSummary(row, showDetails(args), storeOptionSuffix(args)));
     return 0;
   } finally {
     store.close();
@@ -9203,7 +9735,7 @@ async function queryAuditShow(args) {
     if (!row) throw new Error(`query audit record not found: ${auditId}`);
     if (args.includes("--json")) process2.stdout.write(`${JSON.stringify(row, null, 2)}
 `);
-    else process2.stdout.write(formatQueryAuditDetail(row));
+    else process2.stdout.write(showDetails(args) ? formatQueryAuditDetail(row) : formatQueryAuditFirstLook(row, storeOptionSuffix(args)));
     return 0;
   } finally {
     store.close();
@@ -9254,7 +9786,7 @@ async function receiptsShow(args) {
     if (!receipt) throw new Error(`writeback receipt not found: ${receiptId}`);
     if (args.includes("--json")) process2.stdout.write(`${JSON.stringify(receipt, null, 2)}
 `);
-    else process2.stdout.write(formatReceiptDetail(receipt));
+    else process2.stdout.write(showDetails(args) ? formatReceiptDetail(receipt) : formatReceiptFirstLook(receipt, storeOptionSuffix(args)));
     return 0;
   } finally {
     store.close();
@@ -9295,8 +9827,11 @@ async function replayShow(args) {
     if (args.includes("--json")) {
       process2.stdout.write(`${JSON.stringify(replayRecord, null, 2)}
 `);
-    } else {
+    } else if (showDetails(args)) {
       process2.stdout.write(formatReplayDetail(replayRecord));
+      if (args.includes("--debug")) process2.stdout.write(formatReplayDebug(replayRecord, optionalArg(args, "--store")));
+    } else {
+      process2.stdout.write(formatReplayFirstLook(replayRecord, storeOptionSuffix(args)));
     }
     return 0;
   } finally {
@@ -9363,7 +9898,8 @@ async function activitySearch(args) {
       process2.stdout.write(`Found ${sorted.length} local interaction${sorted.length === 1 ? "" : "s"}
 
 `);
-      sorted.forEach((item, index) => process2.stdout.write(formatActivityItem(item, index + 1)));
+      sorted.forEach((item, index) => process2.stdout.write(formatActivityItem(item, index + 1, showDetails(args))));
+      process2.stdout.write(formatActivityNext(sorted, storeOptionSuffix(args)));
     }
     return 0;
   } finally {
@@ -9418,7 +9954,7 @@ async function storePrune(args) {
     store.close();
   }
 }
-var commonReadOptions = /* @__PURE__ */ new Set(["--store", "--json"]);
+var commonReadOptions = /* @__PURE__ */ new Set(["--store", "--json", "--details", "--debug"]);
 var showAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions]);
 var exportAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--output", "--out", "--format", "--evidence", "--audit"]);
 var proposalListAllowedOptions = /* @__PURE__ */ new Set([
@@ -9956,11 +10492,13 @@ function firstPositional(args) {
     "--approval-role",
     "--actor",
     "--action",
+    "--auth-token-env",
     "--audit",
     "--bearer-env",
     "--capability",
     "--config",
     "--conflict-column",
+    "--cors-origin",
     "--database-url-env",
     "--destination",
     "--engine",
@@ -10098,6 +10636,38 @@ function formatProposalSummary(proposal) {
     `  tenant: ${proposal.tenant_id}  source changed: ${proposal.source_database_mutated ? "yes" : "no"}`
   ].join("\n") + "\n";
 }
+function formatProposalFirstLook(proposal, storedEvidenceItemCount, proposalRef, storeSuffix) {
+  const evidenceItems = storedEvidenceItemCount ?? proposal.change_set.evidence.items?.length ?? 0;
+  return [
+    `Proposal ${proposal.proposal_id}`,
+    `Status: ${humanStatus(proposal.state)}`,
+    "",
+    "Agent requested:",
+    proposal.action,
+    "",
+    "Business object:",
+    `${proposal.business_object} ${proposal.object_id}`,
+    "",
+    "Proposed change:",
+    ...formatChangeLines(proposal).map((line) => line.replace(/^  /, "")),
+    "",
+    "Source DB changed:",
+    proposal.source_database_mutated ? "yes" : "no",
+    "",
+    "Approval:",
+    approvalBoundary(proposal),
+    "",
+    "Evidence:",
+    `${proposal.change_set.evidence.bundle_id}${evidenceItems > 0 ? ` (${plural(evidenceItems, "item")})` : ""}`,
+    "",
+    "Next:",
+    ...proposalNextCommands(proposal, proposalRef, storeSuffix).map((command) => `${command}`),
+    "",
+    "More detail:",
+    `${cliCommandName()} proposals show ${proposalRef} --details${storeSuffix}`,
+    ""
+  ].join("\n");
+}
 function formatProposalDetail(proposal, storedEvidenceItemCount) {
   const changeSet = proposal.change_set;
   const conflictGuard = changeSet.guards.expected_version;
@@ -10105,13 +10675,15 @@ function formatProposalDetail(proposal, storedEvidenceItemCount) {
   const approvalStatus = currentApprovalStatus(proposal);
   const writebackStatus = currentWritebackStatus(proposal);
   return [
-    `proposal: ${proposal.proposal_id}`,
-    `state: ${proposal.state}`,
-    `action: ${proposal.action}`,
+    `Proposal details: ${proposal.proposal_id}`,
+    "",
+    "Review details:",
     `principal: ${changeSet.principal.id} (${changeSet.principal.source})`,
     `tenant: ${proposal.tenant_id}`,
     `target: ${proposal.source_kind}:${proposal.source_id}/${proposal.source_schema}.${proposal.source_table}/${proposal.object_id}`,
     `primary key: ${changeSet.source.primary_key.column}=${formatScalar(changeSet.source.primary_key.value)}`,
+    `status: ${proposal.state}`,
+    `action: ${proposal.action}`,
     `approval: ${approvalStatus}${changeSet.approval.required_role ? ` required role ${changeSet.approval.required_role}` : ""}`,
     `proposal hash: ${proposal.proposal_hash}`,
     `proposal version: ${proposal.proposal_version}`,
@@ -10120,14 +10692,29 @@ function formatProposalDetail(proposal, storedEvidenceItemCount) {
     `evidence: ${changeSet.evidence.bundle_id}  query ${changeSet.evidence.query_fingerprint}  items ${evidenceItems}`,
     `writeback: ${writebackStatus} via ${changeSet.writeback.mode}`,
     `source database changed: ${proposal.source_database_mutated ? "yes" : "no"}`,
-    "diff:",
-    ...Object.keys(changeSet.patch).map((column) => {
-      const before = changeSet.before[column];
-      const proposed = changeSet.after[column];
-      return `  ${column}: ${JSON.stringify(before)} -> ${JSON.stringify(proposed)}`;
-    })
+    "",
+    "Diff:",
+    ...formatChangeLines(proposal)
+  ].join("\n") + "\n";
+}
+function formatProposalEventDetail(events) {
+  if (events.length === 0) return "Events:\n  none\n";
+  return [
+    "Events:",
+    ...events.map((event) => `  event ${event.event_id}: ${event.kind} by ${event.actor} at ${event.created_at}`)
   ].join("\n") + "\n";
 }
+function formatProposalDebug(proposal, storePath) {
+  return [
+    "Debug:",
+    `store: ${storePath ?? process2.env.SYNAPSOR_LOCAL_STORE ?? "./.synapsor/local.db"}`,
+    `interaction id: ${proposal.interaction_id ?? "none"}`,
+    `tool call id: ${proposal.tool_call_id ?? "none"}`,
+    `source kind: ${proposal.source_kind}`,
+    `writeback mode: ${proposal.change_set.writeback.mode}`,
+    ""
+  ].join("\n");
+}
 function formatEvidenceSummary(evidence2) {
   return [
     `${evidence2.created_at}  ${evidence2.evidence_bundle_id}`,
@@ -10135,6 +10722,35 @@ function formatEvidenceSummary(evidence2) {
     `  source: ${evidence2.source_id ?? "unknown"}/${evidence2.source_table ?? "unknown"}  object: ${evidence2.business_object ?? "object"}:${evidence2.object_id ?? "unknown"}`
   ].join("\n") + "\n";
 }
+function formatEvidenceFirstLook(evidence2, storeSuffix) {
+  const object = evidence2.business_object && evidence2.object_id ? `${evidence2.business_object} ${evidence2.object_id}` : "not linked";
+  const lines = [
+    `Evidence ${evidence2.evidence_bundle_id}`,
+    "",
+    "Used for:",
+    evidence2.capability ?? "unknown capability",
+    object,
+    "",
+    "Captured:",
+    plural(evidence2.items.length, "evidence item"),
+    plural(evidence2.query_audit.length, "query audit record"),
+    "",
+    "Source:",
+    `${evidence2.source_id ?? "unknown"} / ${evidence2.source_table ?? "unknown"}`,
+    "",
+    "Rows:",
+    ...evidence2.items.flatMap((item, index) => formatEvidenceItem(item, index + 1)),
+    "",
+    "Next:",
+    `  ${cliCommandName()} query-audit list --evidence ${evidence2.evidence_bundle_id}${storeSuffix}`,
+    ...evidence2.proposal_id ? [`  ${cliCommandName()} replay show --proposal ${evidence2.proposal_id}${storeSuffix}`] : [],
+    "",
+    "More detail:",
+    `  ${cliCommandName()} evidence show ${evidence2.evidence_bundle_id} --details${storeSuffix}`
+  ];
+  return `${lines.join("\n")}
+`;
+}
 function formatEvidenceDetail(evidence2) {
   const audit2 = evidence2.query_audit[0];
   const lines = [
@@ -10166,9 +10782,16 @@ function formatEvidenceItem(item, index) {
   const title = stringField(payload, "kind") ?? "item";
   const primaryKey = isRecord6(payload.primary_key) ? payload.primary_key : void 0;
   const heading = primaryKey ? `* ${title} ${formatScalar(primaryKey.value)}` : `* ${title} ${index}`;
-  const rows = Object.entries(visibleRow).filter(([key]) => !["kind", "source_id", "table", "primary_key", "tenant"].includes(key)).slice(0, 12).map(([key, value]) => `  ${key}: ${formatScalar(value)}`);
+  const rows = Object.entries(visibleRow).filter(([key]) => !["kind", "source_id", "table", "primary_key", "tenant"].includes(key)).flatMap(([key, value]) => formatEvidenceFieldLines(key, value)).slice(0, 12);
   return [heading, ...rows.length ? rows : ["  (no scalar preview fields)"]];
 }
+function formatEvidenceFieldLines(key, value) {
+  if (isRecord6(value)) {
+    const nested = Object.entries(value).filter(([, nestedValue]) => nestedValue === null || ["string", "number", "boolean"].includes(typeof nestedValue)).slice(0, 6).map(([nestedKey, nestedValue]) => `  ${key}.${nestedKey}: ${formatScalar(nestedValue)}`);
+    return nested.length ? nested : [`  ${key}: [object]`];
+  }
+  return [`  ${key}: ${formatScalar(value)}`];
+}
 function formatEvidenceMarkdown(evidence2) {
   return [
     `# Evidence ${evidence2.evidence_bundle_id}`,
@@ -10195,12 +10818,34 @@ function formatEvidenceMarkdown(evidence2) {
     "```"
   ].join("\n") + "\n";
 }
-function formatQueryAuditSummary(row) {
-  return [
+function formatQueryAuditSummary(row, details = false, storeSuffix = "") {
+  const lines = [
     `${row.created_at}  audit ${row.audit_id}`,
-    `  source: ${row.source_id}/${row.table_name}  rows: ${row.row_count}  query: ${row.query_fingerprint}`,
-    `  proposal: ${row.proposal_id ?? "none"}  evidence: ${row.evidence_bundle_id ?? "none"}`
-  ].join("\n") + "\n";
+    `  source: ${row.source_id}/${row.table_name}  rows: ${row.row_count}`,
+    `  proposal: ${row.proposal_id ?? "none"}  evidence: ${row.evidence_bundle_id ?? "none"}`,
+    ...details ? [`  query fingerprint: ${row.query_fingerprint}`] : [],
+    `  detail: ${cliCommandName()} query-audit show ${row.audit_id}${details ? "" : " --details"}${storeSuffix}`
+  ];
+  return lines.join("\n") + "\n";
+}
+function formatQueryAuditFirstLook(row, storeSuffix) {
+  return [
+    `Query audit ${row.audit_id}`,
+    "",
+    "Read:",
+    `${row.source_id}/${row.table_name}`,
+    "",
+    "Rows returned:",
+    String(row.row_count ?? "unknown"),
+    "",
+    "Linked records:",
+    `proposal: ${row.proposal_id ?? "none"}`,
+    `evidence: ${row.evidence_bundle_id ?? "none"}`,
+    "",
+    "More detail:",
+    `${cliCommandName()} query-audit show ${row.audit_id} --details${storeSuffix}`,
+    ""
+  ].join("\n");
 }
 function formatQueryAuditDetail(row) {
   const payload = isRecord6(row.payload) ? row.payload : {};
@@ -10228,6 +10873,33 @@ function formatReceiptSummary(receipt) {
     `  idempotency: ${receipt.idempotency_key}  source changed: ${receipt.source_database_mutated ? "yes" : "no"}`
   ].join("\n") + "\n";
 }
+function formatReceiptFirstLook(receipt, storeSuffix) {
+  const checks = receipt.status === "applied" ? ["primary key matched", "tenant guard matched", "allowed columns only", "conflict guard passed"] : receipt.status === "conflict" ? ["primary key matched", "tenant guard matched", "conflict guard blocked stale write"] : ["guarded writeback did not apply"];
+  return [
+    `Receipt ${formatReceiptId(receipt.receipt_id)}`,
+    `Status: ${humanStatus(receipt.status)}`,
+    "",
+    "Proposal:",
+    receipt.proposal_id,
+    "",
+    "Writeback:",
+    "guarded single-row update",
+    "",
+    "Checks:",
+    ...checks.map((check) => `${check}`),
+    `affected rows: ${receipt.receipt.rows_affected}`,
+    "",
+    "Source DB changed:",
+    receipt.source_database_mutated ? "yes" : "no",
+    "",
+    "Next:",
+    `${cliCommandName()} replay show --proposal ${receipt.proposal_id}${storeSuffix}`,
+    "",
+    "More detail:",
+    `${cliCommandName()} receipts show ${receipt.receipt_id} --details${storeSuffix}`,
+    ""
+  ].join("\n");
+}
 function formatReceiptDetail(receipt) {
   return [
     `Receipt: ${receipt.receipt_id}`,
@@ -10253,13 +10925,53 @@ function formatReplaySummary(row) {
     `  tenant: ${row.tenant_id}  capability: ${row.capability}  object: ${row.business_object}:${row.object_id}`
   ].join("\n") + "\n";
 }
-function formatReplayDetail(replay2) {
+function formatReplayFirstLook(replay2, storeSuffix) {
+  const proposal = replay2.proposal;
   const evidenceItems = replay2.evidence.reduce((count, item) => {
     const evidence2 = item;
     return count + (Array.isArray(evidence2.items) ? evidence2.items.length : 0);
   }, 0);
+  const latestReceipt = replay2.receipts.at(-1);
+  const writebackStatus = latestReceipt ? humanStatus(latestReceipt.status) : humanStatus(currentWritebackStatus(proposal));
+  const approvalLine = proposal.state === "pending_review" ? "Approval is still pending" : `Proposal is ${humanStatus(proposal.state)}`;
   return [
     `Replay ${replay2.replay_id}`,
+    "",
+    "What happened:",
+    `1. Agent called ${proposal.action}`,
+    `2. Runner read ${proposal.business_object} ${proposal.object_id} under tenant ${proposal.tenant_id}`,
+    `3. Runner created evidence bundle ${proposal.change_set.evidence.bundle_id}`,
+    "4. Runner created a proposal",
+    `5. Source DB changed: ${proposal.source_database_mutated ? "yes" : "no"}`,
+    `6. ${approvalLine}`,
+    "",
+    "Proposed change:",
+    ...formatChangeLines(proposal).map((line) => line.replace(/^  /, "")),
+    "",
+    "Evidence:",
+    plural(replay2.query_audit.length, "query audit record"),
+    plural(evidenceItems, "evidence item"),
+    "",
+    "Writeback:",
+    writebackStatus,
+    ...latestReceipt ? [`source DB changed after writeback: ${latestReceipt.source_database_mutated ? "yes" : "no"}`] : [],
+    "",
+    "Next:",
+    `  ${cliCommandName()} evidence show ${proposal.change_set.evidence.bundle_id}${storeSuffix}`,
+    ...proposal.state === "pending_review" ? [`  ${cliCommandName()} proposals approve ${proposal.proposal_id} --yes${storeSuffix}`] : [],
+    "",
+    "More detail:",
+    `  ${cliCommandName()} replay show --proposal ${proposal.proposal_id} --details${storeSuffix}`,
+    ""
+  ].join("\n");
+}
+function formatReplayDetail(replay2) {
+  const evidenceItems = replay2.evidence.reduce((count, item) => {
+    const evidence2 = item;
+    return count + (Array.isArray(evidence2.items) ? evidence2.items.length : 0);
+  }, 0);
+  return [
+    `Replay details ${replay2.replay_id}`,
     formatProposalDetail(replay2.proposal, evidenceItems).trimEnd(),
     `events: ${replay2.events.length}`,
     ...replay2.events.map((event) => `  ${event.kind} by ${event.actor} at ${event.created_at}`),
@@ -10271,6 +10983,16 @@ function formatReplayDetail(replay2) {
     ...replay2.query_audit.map((record) => `  audit ${record.audit_id}: ${record.source_id}/${record.table_name} rows ${record.row_count}`)
   ].join("\n") + "\n";
 }
+function formatReplayDebug(replay2, storePath) {
+  return [
+    "Debug:",
+    `store: ${storePath ?? process2.env.SYNAPSOR_LOCAL_STORE ?? "./.synapsor/local.db"}`,
+    `generated at: ${replay2.generated_at}`,
+    `event ids: ${replay2.events.map((event) => event.event_id).join(", ") || "none"}`,
+    `receipt ids: ${replay2.receipts.map((receipt) => receipt.receipt_id).join(", ") || "none"}`,
+    ""
+  ].join("\n");
+}
 function formatReplayMarkdown(replay2) {
   const proposal = replay2.proposal;
   const principal = proposal.change_set.principal.id;
@@ -10402,7 +11124,7 @@ function activityFromReceipt(receipt) {
     source_database_mutated: receipt.source_database_mutated
   };
 }
-function formatActivityItem(item, index) {
+function formatActivityItem(item, index, details = false) {
   const lines = [
     `${index}. ${item.created_at}`,
     `   kind: ${item.kind}`,
@@ -10412,14 +11134,35 @@ function formatActivityItem(item, index) {
     ...item.proposal ? [`   proposal: ${item.proposal}`] : [],
     ...item.evidence ? [`   evidence: ${item.evidence}`] : [],
     ...item.query_audit ? [`   query audit: ${item.query_audit}`] : [],
-    ...item.query_fingerprint ? [`   query fingerprint: ${item.query_fingerprint}`] : [],
+    ...details && item.query_fingerprint ? [`   query fingerprint: ${item.query_fingerprint}`] : [],
     ...item.receipt ? [`   receipt: ${item.receipt}`] : [],
-    ...item.status ? [`   status: ${item.status}`] : [],
+    ...item.status ? [`   status: ${humanStatus(String(item.status))}`] : [],
     ...item.replay ? [`   replay: ${item.replay}`] : [],
     ""
   ];
   return lines.join("\n");
 }
+function formatActivityNext(items, storeSuffix) {
+  const first = items[0];
+  if (!first) return "";
+  const proposal = stringField(first, "proposal");
+  const replayId = stringField(first, "replay");
+  const evidence2 = stringField(first, "evidence");
+  const lines = ["Next:"];
+  if (proposal) {
+    lines.push(`${cliCommandName()} proposals show ${proposal}${storeSuffix}`);
+    lines.push(`${cliCommandName()} replay show --proposal ${proposal}${storeSuffix}`);
+  } else if (replayId) {
+    lines.push(`${cliCommandName()} replay show --replay ${replayId}${storeSuffix}`);
+  } else if (evidence2) {
+    lines.push(`${cliCommandName()} evidence show ${evidence2}${storeSuffix}`);
+  } else {
+    lines.push(`${cliCommandName()} activity search --details${storeSuffix}`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}
+`;
+}
 function formatStoreStats(stats) {
   return [
     `Local store: ${stats.path}`,
@@ -10521,6 +11264,60 @@ function currentWritebackStatus(proposal) {
   if (proposal.state === "failed") return "failed";
   return proposal.change_set.writeback.status;
 }
+function showDetails(args) {
+  return args.includes("--details") || args.includes("--debug");
+}
+function storeOptionSuffix(args) {
+  const storePath = optionalArg(args, "--store");
+  return storePath ? ` --store ${storePath}` : "";
+}
+function humanStatus(value) {
+  const normalized = value.replace(/_/g, " ");
+  if (normalized === "pending review") return "pending review";
+  if (normalized === "not applied") return "not applied";
+  return normalized;
+}
+function plural(count, label) {
+  return `${count} ${label}${count === 1 ? "" : "s"}`;
+}
+function formatReceiptId(receiptId) {
+  return `rct_${String(receiptId).padStart(6, "0")}`;
+}
+function approvalBoundary(proposal) {
+  if (proposal.state === "pending_review") return "required outside MCP";
+  if (proposal.state === "approved" || proposal.state === "pending_worker") return "approved outside MCP; waiting for trusted worker";
+  if (proposal.state === "applied") return "approved outside MCP; writeback applied";
+  if (proposal.state === "conflict") return "approved outside MCP; writeback blocked by conflict guard";
+  if (proposal.state === "failed") return "approved outside MCP; writeback failed safely";
+  if (proposal.state === "rejected") return "rejected outside MCP";
+  return humanStatus(proposal.state);
+}
+function proposalNextCommands(proposal, proposalRef, storeSuffix) {
+  if (proposal.state === "pending_review") {
+    return [
+      `${cliCommandName()} proposals approve ${proposalRef} --yes${storeSuffix}`,
+      `${cliCommandName()} replay show ${proposalRef === "latest" ? "latest" : `--proposal ${proposal.proposal_id}`}${storeSuffix}`
+    ];
+  }
+  if (proposal.state === "approved" || proposal.state === "pending_worker") {
+    return [
+      `${cliCommandName()} replay show --proposal ${proposal.proposal_id}${storeSuffix}`
+    ];
+  }
+  return [
+    `${cliCommandName()} replay show --proposal ${proposal.proposal_id}${storeSuffix}`
+  ];
+}
+function formatChangeLines(proposal) {
+  const changeSet = proposal.change_set;
+  const columns = Object.keys(changeSet.patch);
+  if (columns.length === 0) return ["  (no changed columns)"];
+  return columns.map((column) => {
+    const before = changeSet.before[column];
+    const proposed = changeSet.after[column];
+    return `  ${column}: ${formatScalar(before)} -> ${formatScalar(proposed)}`;
+  });
+}
 function formatShadowComparison(comparison) {
   return [
     `shadow comparison: ${comparison.proposal_id}`,
@@ -10638,7 +11435,7 @@ function starterCloudConfig() {
       base_url_env: "SYNAPSOR_CLOUD_BASE_URL",
       runner_token_env: "SYNAPSOR_RUNNER_TOKEN",
       runner_id: "synapsor_runner_local",
-      runner_version: "0.1.0-alpha.4",
+      runner_version: "0.1.0-alpha.5",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",
@@ -10747,16 +11544,31 @@ Generate a reviewed Synapsor Runner contract. Defaults to read-only in the wizar
 `,
     mcp: `Usage:
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+  ${cmd} mcp serve-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
   ${cmd} mcp config --absolute-paths --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} mcp audit --example dangerous-db-mcp
   ${cmd} mcp audit ./tools-list.json
 
+Use stdio for local MCP clients that launch the runner. Use authenticated HTTP for app/server deployments.
 MCP clients see semantic tools. They do not receive raw SQL, write credentials, approval tools, or commit tools.
 `,
     "mcp serve": `Usage:
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db [--read-only] [--local]
 
-Start the stdio MCP server. Startup logs stay off stdout so the MCP protocol remains clean.
+Start the stdio MCP server for local MCP clients such as Claude Desktop, Cursor, or local agent tools. Startup logs stay off stdout so the MCP protocol remains clean.
+`,
+    "mcp serve-http": `Usage:
+  export SYNAPSOR_RUNNER_HTTP_TOKEN=...
+  ${cmd} mcp serve-http --config ./synapsor.runner.json --store ./.synapsor/local.db [--host 127.0.0.1] [--port 8765] [--auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN]
+
+Start the HTTP MCP server for app/server deployments. Bearer auth is required by default.
+
+Security:
+  - Defaults to 127.0.0.1:8765.
+  - Refuses to start if the auth token env var is missing.
+  - Use --dev-no-auth only for localhost development.
+  - If binding to 0.0.0.0, use TLS, private networking, authentication, and rate limits.
+  - Optional CORS: --cors-origin http://localhost:3000
 `,
     "mcp config": `Usage:
   ${cmd} mcp config [claude-desktop|cursor|generic|vscode] [--absolute-paths] [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
@@ -10795,33 +11607,37 @@ Static MCP/database risk review only. This is not a security guarantee.
 Validate local config, environment bindings, semantic tool boundary, source metadata when reachable, and local store stats. Reports are redacted; do not paste secrets into issues.
 `,
     proposals: `Usage:
-  ${cmd} proposals list [--tenant acme] [--capability billing.propose_late_fee_waiver] [--object invoice:INV-3001] [--status applied]
-  ${cmd} proposals show latest
-  ${cmd} proposals approve latest --yes
-  ${cmd} proposals reject latest --reason "..."
+	  ${cmd} proposals list [--tenant acme] [--capability billing.propose_late_fee_waiver] [--object invoice:INV-3001] [--status applied]
+	  ${cmd} proposals show latest
+	  ${cmd} proposals show latest --details
+	  ${cmd} proposals approve latest --yes
+	  ${cmd} proposals reject latest --reason "..."
 
-Review decisions happen outside the model-facing MCP tool surface.
-`,
+	Review decisions happen outside the model-facing MCP tool surface. Human output is concise by default; use --details for reviewer metadata or --json for complete records.
+	`,
     evidence: `Usage:
-  ${cmd} evidence list [--tenant acme] [--capability billing.inspect_invoice] [--object invoice:INV-3001]
-  ${cmd} evidence show ev_...
-  ${cmd} evidence export ev_... --format json --output evidence.json
+	  ${cmd} evidence list [--tenant acme] [--capability billing.inspect_invoice] [--object invoice:INV-3001]
+	  ${cmd} evidence show ev_...
+	  ${cmd} evidence show ev_... --details
+	  ${cmd} evidence export ev_... --format json --output evidence.json
   ${cmd} evidence export ev_... --format markdown --output evidence.md
 
 Inspect captured local evidence bundles and query-audit links without rerunning external DB reads.
 `,
     "query-audit": `Usage:
-  ${cmd} query-audit list [--evidence ev_...] [--source app_postgres] [--table invoices]
-  ${cmd} query-audit show <audit_id>
-  ${cmd} query-audit export <audit_id> --format json --output audit.json
+	  ${cmd} query-audit list [--evidence ev_...] [--source app_postgres] [--table invoices]
+	  ${cmd} query-audit show <audit_id>
+	  ${cmd} query-audit show <audit_id> --details
+	  ${cmd} query-audit export <audit_id> --format json --output audit.json
 
 Inspect local query fingerprints, table names, row counts, and redacted-parameter metadata.
 `,
     receipts: `Usage:
-  ${cmd} receipts list [--proposal wrp_...] [--status applied]
-  ${cmd} receipts show <receipt_id>
+	  ${cmd} receipts list [--proposal wrp_...] [--status applied]
+	  ${cmd} receipts show <receipt_id>
+	  ${cmd} receipts show <receipt_id> --details
 
-Inspect guarded writeback receipts recorded by the trusted runner path.
+	Inspect guarded writeback receipts recorded by the trusted runner path. Use --details for idempotency keys, receipt hashes, and runner metadata.
 `,
     apply: `Usage:
   ${cmd} apply latest [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
@@ -10831,18 +11647,20 @@ Apply an approved proposal through guarded writeback. Requires a trusted write c
 `,
     replay: `Usage:
   ${cmd} replay list [--tenant acme] [--object invoice:INV-3001]
-  ${cmd} replay show latest
-  ${cmd} replay show --proposal wrp_...
+	  ${cmd} replay show latest
+	  ${cmd} replay show latest --details
+	  ${cmd} replay show --proposal wrp_...
   ${cmd} replay show --replay replay_wrp_...
   ${cmd} replay show --evidence ev_...
   ${cmd} replay export --proposal wrp_... --format json --output replay.json
   ${cmd} replay export --proposal wrp_... --format markdown --output replay.md
 
-Show evidence, proposal events, receipts, and replay state without rerunning side effects.
+	Show evidence, proposal events, receipts, and replay state without rerunning side effects. Human output is concise by default; use --details for reviewer metadata or --json for complete records.
 `,
     activity: `Usage:
-  ${cmd} activity search --tenant acme --object invoice:INV-3001
-  ${cmd} activity search --capability billing.propose_late_fee_waiver --from 2026-06-01 --to 2026-06-23
+	  ${cmd} activity search --tenant acme --object invoice:INV-3001
+	  ${cmd} activity search --tenant acme --object invoice:INV-3001 --details
+	  ${cmd} activity search --capability billing.propose_late_fee_waiver --from 2026-06-01 --to 2026-06-23
 
 Search the local SQLite evidence/replay ledger across proposals, evidence, query audit, receipts, and replay records.
 `,
@@ -10857,9 +11675,14 @@ Local store maintenance only. Prune defaults to dry-run and never touches your s
     demo: `Usage:
 	  ${cmd} demo [--force]
 	  ${cmd} demo --quick
+	  ${cmd} demo --quick --guided
+	  ${cmd} demo --quick --no-interactive
+	  ${cmd} demo --quick --details
+	  ${cmd} demo inspect
+	  ${cmd} demo inspect --npx
 
 	Start a disposable local Postgres demo and write ./synapsor.runner.json for the first-run flow.
-	Use --quick for a fixture-only 15-second explanation and local ledger seed with no Docker startup.
+	Use --quick for a fixture-only guided walkthrough and local ledger seed with no Docker startup. Use demo inspect to print follow-up commands for the quick-demo fixture.
 	`,
     ui: `Usage:
   ${cmd} ui [--tour] [--config synapsor.runner.json] [--store ./.synapsor/local.db]