@synapsor/runner 0.1.0-alpha.15 → 0.1.0-alpha.17

package/dist/runner.mjs

@@ -451,6 +451,7 @@ var SOURCE_KEYS = /* @__PURE__ */ new Set([
   "engine",
   "read_url_env",
   "write_url_env",
+  "read_only",
   "statement_timeout_ms",
   "ssl"
 ]);
@@ -564,6 +565,7 @@ function validateRunnerCapabilityConfig(input) {
   validateTrustedContext(input.trusted_context, input.contexts, input.capabilities, input.mode, strict, errors, warnings);
   validateExecutors(input.executors, input.mode, strict, errors);
   validateCapabilities(input.capabilities, input.sources, input.contexts, input.executors, input.mode, strict, errors, warnings);
+  validateWritebackReadiness(input.sources, input.capabilities, input.mode, errors, warnings);
   scanForForbiddenFields(input, "$", errors);
   return { ok: errors.length === 0, errors, warnings };
 }
@@ -622,14 +624,37 @@ function validateSources(value, mode, strict, errors, warnings) {
     if (source.statement_timeout_ms !== void 0 && !isPositiveInteger(source.statement_timeout_ms)) {
       errors.push({ path: `${path4}.statement_timeout_ms`, code: "INVALID_TIMEOUT", message: "statement_timeout_ms must be a positive integer." });
     }
+    if (source.read_only !== void 0 && typeof source.read_only !== "boolean") {
+      errors.push({ path: `${path4}.read_only`, code: "INVALID_SOURCE_READ_ONLY", message: "read_only must be true or false when provided." });
+    }
+  }
+}
+function validateWritebackReadiness(sources, capabilities, mode, errors, warnings) {
+  if (mode !== "review" || !isRecord(sources) || !Array.isArray(capabilities)) return;
+  capabilities.forEach((capability, index) => {
+    if (!isRecord(capability) || capability.kind !== "proposal") return;
+    const sourceName = isNonEmptyString(capability.source) ? capability.source : void 0;
+    const source = sourceName ? sources[sourceName] : void 0;
+    if (!sourceName || !isRecord(source)) return;
+    const executor = isNonEmptyString(capability.executor) ? capability.executor : "sql_update";
+    const directSql = executor === "sql_update";
+    if (!directSql) return;
+    if (source.read_only === true) {
+      errors.push({
+        path: `$.capabilities[${index}].executor`,
+        code: "READ_ONLY_SOURCE_DIRECT_WRITEBACK",
+        message: `Proposal capability ${String(capability.name ?? index)} uses direct SQL writeback, but source ${sourceName} is marked read_only.`
+      });
+      return;
+    }
     if (source.write_url_env === void 0) {
       warnings.push({
-        path: `${path4}.write_url_env`,
+        path: `$.sources.${sourceName}.write_url_env`,
         code: "WRITEBACK_DISABLED",
-        message: "No write_url_env is configured; review-mode proposal execution cannot apply external DB changes."
+        message: "No write_url_env is configured; direct SQL review-mode proposal execution cannot apply external DB changes."
       });
     }
-  }
+  });
 }
 function validateCloud(value, mode, strict, errors) {
   if (mode !== "cloud") {
@@ -4466,6 +4491,7 @@ import { Pool as Pool3 } from "pg";
 var TENANT_COLUMNS = /* @__PURE__ */ new Set(["tenant_id", "account_id", "organization_id", "org_id", "workspace_id", "customer_id"]);
 var CONFLICT_COLUMNS = /* @__PURE__ */ new Set(["updated_at", "modified_at", "row_version", "version", "lock_version", "etag"]);
 var IMMUTABLE_COLUMNS = /* @__PURE__ */ new Set(["id", "uuid", "created_at", "created_by"]);
+var DEFAULT_RESULT_FORMAT = 2;
 var SENSITIVE_PATTERNS = [
   /password/i,
   /password_hash/i,
@@ -4525,15 +4551,18 @@ function generateRunnerConfigFromSpec(spec) {
   const lookupArg = spec.lookup_arg ?? `${objectName}_id`;
   const inspectToolName = spec.inspect_tool_name ?? `${spec.namespace}.inspect_${objectName}`;
   const proposalToolName = spec.proposal_tool_name ?? `${spec.namespace}.propose_${objectName}_update`;
+  const objectLabel = objectName.replace(/_/g, " ");
   const visibleColumns = unique([spec.primary_key, spec.tenant_key, spec.conflict_column, ...spec.visible_columns].filter((value) => Boolean(value)));
   const readCapability = {
     name: inspectToolName,
     kind: "read",
+    description: spec.inspect_description ?? `Inspect one ${objectLabel} in trusted tenant scope before answering or proposing a change.`,
+    returns_hint: spec.inspect_returns_hint ?? `Returns reviewed ${objectLabel} fields, evidence handle, query audit, and source_database_changed:false.`,
     source: sourceName,
     context: "local_operator",
     target: target(spec),
     args: {
-      [lookupArg]: { type: "string", required: true, max_length: 128 }
+      [lookupArg]: { type: "string", required: true, max_length: 128, description: `${capitalize(objectLabel)} id from the user request or trusted app context.` }
     },
     lookup: { id_from_arg: lookupArg },
     visible_columns: visibleColumns,
@@ -4546,6 +4575,8 @@ function generateRunnerConfigFromSpec(spec) {
     capabilities.push({
       name: proposalToolName,
       kind: "proposal",
+      description: spec.proposal_description ?? `Create a review-required proposal to update one ${objectLabel}. The source database remains unchanged until approval and writeback.`,
+      returns_hint: spec.proposal_returns_hint ?? "Returns a proposal id, exact before/after diff, evidence handle, approval status, and source_database_changed:false.",
       source: sourceName,
       context: "local_operator",
       ...writeback2.executor !== "sql_update" ? { executor: writeback2.executorName } : {},
@@ -4569,12 +4600,14 @@ function generateRunnerConfigFromSpec(spec) {
   const config = {
     version: 1,
     mode,
+    result_format: spec.result_format ?? DEFAULT_RESULT_FORMAT,
     storage: { sqlite_path: "./.synapsor/local.db" },
     sources: {
       [sourceName]: {
         engine: spec.engine,
         read_url_env: readUrlEnv,
         ...mode === "review" && writeUrlEnv ? { write_url_env: writeUrlEnv } : {},
+        ...mode === "review" && writeback2.executor !== "sql_update" && !writeUrlEnv ? { read_only: true } : {},
         statement_timeout_ms: spec.statement_timeout_ms ?? 3e3
       }
     },
@@ -5017,6 +5050,7 @@ function validateSelectionSpec(spec) {
   if (spec.version !== void 0 && spec.version !== 1) throw new Error("onboarding selection version must be 1.");
   if (spec.engine !== "postgres" && spec.engine !== "mysql") throw new Error("selection engine must be postgres or mysql.");
   if (!["read_only", "shadow", "review", void 0].includes(spec.mode)) throw new Error("selection mode must be read_only, shadow, or review.");
+  if (spec.result_format !== void 0 && spec.result_format !== 1 && spec.result_format !== 2) throw new Error("selection result_format must be 1 or 2.");
   if (spec.writeback?.executor && !["sql_update", "http_handler", "command_handler"].includes(spec.writeback.executor)) {
     throw new Error("selection writeback.executor must be sql_update, http_handler, or command_handler.");
   }
@@ -5121,6 +5155,10 @@ function singularize(value) {
 function safeName(value) {
   return value.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "") || "record";
 }
+function capitalize(value) {
+  if (!value) return value;
+  return `${value[0]?.toUpperCase() ?? ""}${value.slice(1)}`;
+}
 function assertSafeIdentifier(identifier) {
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
     throw new Error(`unsafe identifier in selection: ${identifier}`);
@@ -6573,6 +6611,19 @@ var defaultConfigPath = "synapsor.runner.json";
 var defaultStorePath = "./.synapsor/local.db";
 var quickDemoStorePath = "./.synapsor/quick-demo.db";
 var generatedSmokeInputPath = "./.synapsor/smoke-input.json";
+var handlerSecurityWarning = [
+  "IMPORTANT: your app handler owns the final business write.",
+  "Runner creates the proposal and calls your handler only after approval, but your handler must still enforce:",
+  "- tenant/scope check;",
+  "- expected-version or conflict guard;",
+  "- idempotency key;",
+  "- allowed business action;",
+  "- transaction/rollback;",
+  "- safe error receipt.",
+  "",
+  "If you skip those checks, you can reintroduce cross-tenant writes, lost updates, or duplicate writes.",
+  "Use the generated template/helper pattern and keep handler credentials out of MCP."
+].join("\n");
 var handlerTemplateDefinitions = {
   "node-fastify": {
     aliases: ["node", "fastify"],
@@ -6608,6 +6659,15 @@ app.post("/synapsor/writeback", async (request, reply) => {
   }
 
   /*
+   * IMPORTANT: your app handler owns the final business write.
+   * Runner creates the proposal and calls your handler only after approval,
+   * but your handler must still enforce tenant/scope, expected-version or
+   * conflict guard, idempotency key, allowed business action,
+   * transaction/rollback, and safe error receipt.
+   *
+   * If you skip those checks, you can reintroduce cross-tenant writes,
+   * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+   *
    * Put your app-owned transaction here.
    *
    * Examples:
@@ -6665,6 +6725,15 @@ async def synapsor_writeback(body: dict, authorization: str | None = Header(defa
 
     # Put your app-owned transaction here.
     #
+    # IMPORTANT: your app handler owns the final business write.
+    # Runner creates the proposal and calls your handler only after approval,
+    # but your handler must still enforce tenant/scope, expected-version or
+    # conflict guard, idempotency key, allowed business action,
+    # transaction/rollback, and safe error receipt.
+    #
+    # If you skip those checks, you can reintroduce cross-tenant writes,
+    # lost updates, or duplicate writes. Keep handler credentials out of MCP.
+    #
     # Examples:
     # - insert a refund_review row;
     # - insert an account_credit row;
@@ -6716,6 +6785,15 @@ if (request.dry_run) {
 }
 
 /*
+ * IMPORTANT: your app handler owns the final business write.
+ * Runner creates the proposal and calls your handler only after approval,
+ * but your handler must still enforce tenant/scope, expected-version or
+ * conflict guard, idempotency key, allowed business action,
+ * transaction/rollback, and safe error receipt.
+ *
+ * If you skip those checks, you can reintroduce cross-tenant writes,
+ * lost updates, or duplicate writes. Keep handler credentials out of MCP.
+ *
  * Put your app-owned command transaction here.
  *
  * Examples:
@@ -6784,6 +6862,7 @@ ${cliCommandName()} --help
   if (command === "propose") return propose(rest);
   if (command === "audit") return audit(rest);
   if (command === "start") return start(rest);
+  if (command === "up") return up(rest);
   if (command === "runner") return runnerCommand(rest);
   if (command === "cloud") return cloud(rest);
   if (command === "mcp") return mcp(rest);
@@ -6813,11 +6892,16 @@ ${cliCommandName()} --help
   return 2;
 }
 async function init(args) {
+  const answersPath = optionalArg(args, "--answers");
+  if (answersPath) {
+    return initFromAnswers(args, answersPath);
+  }
   const specPath = optionalArg(args, "--spec");
   if (specPath) {
     return initFromSpec(args, specPath);
   }
-  if (args.includes("--wizard") || process2.stdin.isTTY && process2.stdout.isTTY && !args.includes("--starter")) {
+  const scripted = isScriptedOnboardingArgs(args);
+  if (args.includes("--wizard") || process2.stdin.isTTY && process2.stdout.isTTY && !args.includes("--starter") && !scripted) {
     return runInitWizard(args);
   }
   const inspectionJson = optionalArg(args, "--inspection-json");
@@ -6983,12 +7067,49 @@ async function runInitWizard(args, options = {}) {
       if (transitionFromColumns.length > 0) ensureColumnsExist(transitionFromColumns, columns, "transition from");
     }
   }
-  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 inferredObjectName = recipeSpec?.object_name ?? safeObjectName(table.name);
+  const namespace = await askDefault(ask, "Capability namespace", optionalArg(args, "--namespace") ?? recipeSpec?.namespace ?? inferCapabilityNamespace(table.name));
+  const objectName = await askDefault(ask, "Business object name", optionalArg(args, "--object-name") ?? inferredObjectName);
   const lookupArg = await askDefault(ask, "Model-visible object id argument", optionalArg(args, "--lookup-arg") ?? recipeSpec?.lookup_arg ?? `${objectName}_id`);
+  const defaultInspectToolName = recipeSpec?.inspect_tool_name ?? `${namespace}.inspect_${objectName}`;
+  const inspectToolName = await askDefault(
+    ask,
+    "Read capability name",
+    optionalArg(args, "--read-tool") ?? optionalArg(args, "--inspect-tool-name") ?? defaultInspectToolName
+  );
+  const defaultProposalToolName = recipeSpec?.proposal_tool_name ?? `${namespace}.propose_${objectName}_update`;
+  const proposalToolName = mode === "read_only" ? void 0 : await askDefault(
+    ask,
+    "Proposal capability name",
+    optionalArg(args, "--proposal-tool") ?? optionalArg(args, "--proposal-tool-name") ?? defaultProposalToolName
+  );
   const smokeObjectId = await askDefault(ask, "Optional real object id for a first smoke call", optionalArg(args, "--smoke-id") ?? "");
+  const objectLabel = objectName.replace(/_/g, " ");
+  const inspectDescription = await askDefault(
+    ask,
+    "Read capability description",
+    optionalArg(args, "--inspect-description") ?? `Inspect one ${objectLabel} in trusted tenant scope before answering or proposing a change.`
+  );
+  const inspectReturnsHint = await askDefault(
+    ask,
+    "Read capability returns hint",
+    optionalArg(args, "--inspect-returns-hint") ?? `Returns reviewed ${objectLabel} fields, evidence handle, query audit, and source_database_changed:false.`
+  );
+  const proposalDescription = mode === "read_only" ? void 0 : await askDefault(
+    ask,
+    "Proposal capability description",
+    optionalArg(args, "--proposal-description") ?? `Create a review-required proposal to update one ${objectLabel}. The source database remains unchanged until approval and writeback.`
+  );
+  const proposalReturnsHint = mode === "read_only" ? void 0 : await askDefault(
+    ask,
+    "Proposal capability returns hint",
+    optionalArg(args, "--proposal-returns-hint") ?? "Returns a proposal id, exact before/after diff, evidence handle, approval status, and source_database_changed:false."
+  );
+  const resultFormatAnswer = await askChoice(ask, "MCP result envelope", optionalArg(args, "--result-format") ? normalizeResultFormatAnswer(optionalArg(args, "--result-format")) : "v2", ["v2", "v1", "default"]);
+  const resultFormat = resultFormatAnswer === "v1" ? 1 : resultFormatAnswer === "v2" ? 2 : void 0;
   let writeUrlEnv = optionalArg(args, "--write-url-env");
   let writeback2;
+  let generatedHandlerTemplate;
   if (mode === "review") {
     const writebackPath = await askChoice(
       ask,
@@ -7011,6 +7132,12 @@ async function runInitWizard(args, options = {}) {
         ...signingSecretEnv ? { handler_signing_secret_env: signingSecretEnv } : {},
         timeout_ms: positiveIntegerOption(args, "--handler-timeout-ms")
       };
+      const writeTemplate = await askChoice(ask, "Write starter app-owned handler template", args.includes("--skip-handler-template") ? "no" : "yes", ["yes", "no"]);
+      if (writeTemplate === "yes") {
+        const template = await askChoice(ask, "Handler template", optionalArg(args, "--handler-template") ?? "node-fastify", ["node-fastify", "python-fastapi"]);
+        const output = await askDefault(ask, "Handler template output", optionalArg(args, "--handler-output") ?? optionalArg(args, "--handler-template-output") ?? handlerTemplateDefinitions[template].fileName);
+        generatedHandlerTemplate = { name: template, output };
+      }
     } else {
       const commandEnv = await askEnvName(ask, "App-owned command handler env var", optionalArg(args, "--handler-command-env") ?? "SYNAPSOR_APP_WRITEBACK_COMMAND");
       writeback2 = {
@@ -7019,10 +7146,15 @@ async function runInitWizard(args, options = {}) {
         handler_command_env: commandEnv,
         timeout_ms: positiveIntegerOption(args, "--handler-timeout-ms")
       };
+      const writeTemplate = await askChoice(ask, "Write starter app-owned handler template", args.includes("--skip-handler-template") ? "no" : "yes", ["yes", "no"]);
+      if (writeTemplate === "yes") {
+        const output = await askDefault(ask, "Handler template output", optionalArg(args, "--handler-output") ?? optionalArg(args, "--handler-template-output") ?? handlerTemplateDefinitions.command.fileName);
+        generatedHandlerTemplate = { name: "command", output };
+      }
     }
   }
   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 = {
+  let spec = {
     version: 1,
     engine: inspection.engine,
     mode,
@@ -7037,9 +7169,14 @@ async function runInitWizard(args, options = {}) {
     conflict_column: conflictAnswer || void 0,
     namespace,
     object_name: objectName,
-    inspect_tool_name: recipeSpec?.inspect_tool_name,
-    proposal_tool_name: recipeSpec?.proposal_tool_name,
+    inspect_tool_name: inspectToolName,
+    proposal_tool_name: proposalToolName,
+    inspect_description: inspectDescription,
+    inspect_returns_hint: inspectReturnsHint,
+    proposal_description: proposalDescription,
+    proposal_returns_hint: proposalReturnsHint,
     lookup_arg: lookupArg,
+    result_format: resultFormat,
     visible_columns: visibleColumns,
     allowed_columns: allowedColumns,
     patch,
@@ -7055,26 +7192,48 @@ async function runInitWizard(args, options = {}) {
     },
     writeback: writeback2
   };
-  const generated = generateRunnerConfigFromSpec(spec);
-  const generatedCapabilities = generated.config.capabilities;
-  const tools2 = generatedCapabilities.map((capability) => `${capability.name} (${capability.kind})`);
-  const smokeToolName = generatedCapabilities[0]?.name ?? "<inspect_tool>";
+  let generated = generateRunnerConfigFromSpec(spec);
   stdout.write("\nPreview:\n");
-  stdout.write(`  trusted context: tenant from ${tenantEnv}${singleTenantDev ? " (single-tenant dev source)" : tenantAnswer ? ` via ${tenantAnswer}` : ""}; principal from ${principalEnv}
+  printWizardContractPreview(stdout, { spec, generated, engine: inspection.engine, table });
+  if (generatedHandlerTemplate) {
+    stdout.write(`  handler template: ${generatedHandlerTemplate.output}
 `);
-  stdout.write(`  source: ${inspection.engine} ${table.schema}.${table.name}
-`);
-  stdout.write(`  mode: ${mode}
-`);
-  stdout.write(`  writeback path: ${writeback2?.executor ?? (mode === "review" ? "sql_update" : "none")}
-`);
-  stdout.write(`  exposed tools: ${tools2.join(", ")}
+    stdout.write(`${handlerSecurityWarning}
 `);
-  stdout.write("  not exposed: execute_sql, approval tools, commit tools, database URLs, write credentials, model-controlled tenant authority\n");
+  }
+  const editPreview = await askDefault(ask, "Edit visible fields or capability names before writing? Type yes to edit", "no");
+  if (editPreview.toLowerCase() === "yes") {
+    const updatedVisible = parseColumnList(await askDefault(
+      ask,
+      "Final visible columns",
+      spec.visible_columns?.join(",") ?? visibleColumns.join(",")
+    ));
+    ensureColumnsExist(updatedVisible, columns, "visible");
+    const currentReadTool = spec.inspect_tool_name ?? generated.config.capabilities.find((capability) => capability.kind === "read")?.name ?? inspectToolName;
+    const updatedReadTool = await askDefault(ask, "Final read capability name", currentReadTool);
+    const currentProposalTool = spec.proposal_tool_name ?? generated.config.capabilities.find((capability) => capability.kind === "proposal")?.name ?? proposalToolName ?? "";
+    const updatedProposalTool = spec.mode === "read_only" ? void 0 : await askDefault(ask, "Final proposal capability name", currentProposalTool);
+    spec = {
+      ...spec,
+      visible_columns: updatedVisible,
+      inspect_tool_name: updatedReadTool,
+      proposal_tool_name: updatedProposalTool
+    };
+    generated = generateRunnerConfigFromSpec(spec);
+    stdout.write("\nUpdated preview:\n");
+    printWizardContractPreview(stdout, { spec, generated, engine: inspection.engine, table });
+  }
+  const generatedCapabilities = generated.config.capabilities;
+  const smokeToolName = generatedCapabilities[0]?.name ?? "<inspect_tool>";
   const confirmed = await askDefault(ask, "Write generated config and MCP snippets? Type yes to continue", "no");
   if (confirmed.toLowerCase() !== "yes") throw new Error("guided init canceled before writing files");
   const outputPath = outputArg(args) ?? "synapsor.runner.json";
   await writeGeneratedOnboardingFiles(outputPath, generated, args.includes("--force"), { printNext: false });
+  if (generatedHandlerTemplate) {
+    await writeHandlerTemplateFile(generatedHandlerTemplate.name, generatedHandlerTemplate.output, args.includes("--force"));
+    stdout.write(`created ${generatedHandlerTemplate.output}
+`);
+  }
   if (smokeObjectId) {
     await writeGeneratedSmokeInputFile(lookupArg, smokeObjectId, args.includes("--force"));
     stdout.write(`created ${generatedSmokeInputPath}
@@ -7103,9 +7262,42 @@ async function runInitWizard(args, options = {}) {
 `);
   }
   stdout.write(`  3. Serve MCP tools: ${cliCommandName()} mcp serve --config ${outputPath} --store ${defaultStorePath}
+`);
+  stdout.write(`  OpenAI Agents SDK: use ${cliCommandName()} mcp serve-streamable-http --config ${outputPath} --store ${defaultStorePath} --alias-mode openai
 `);
   return 0;
 }
+function printWizardContractPreview(stdout, input) {
+  const capabilities = input.generated.config.capabilities;
+  const tools2 = capabilities.map((capability) => `${capability.name} (${capability.kind})`);
+  const readCapability = capabilities.find((capability) => capability.kind === "read")?.name ?? input.spec.inspect_tool_name ?? "<read_tool>";
+  const proposalCapability = capabilities.find((capability) => capability.kind === "proposal")?.name ?? input.spec.proposal_tool_name;
+  const visibleColumns = input.spec.visible_columns ?? [];
+  const tenantEnv = input.spec.trusted_context?.tenant_id_env ?? "SYNAPSOR_TENANT_ID";
+  const principalEnv = input.spec.trusted_context?.principal_env ?? "SYNAPSOR_PRINCIPAL";
+  const visiblePreview = visibleColumns.length <= 12 ? visibleColumns.join(", ") : `${visibleColumns.slice(0, 12).join(", ")} (+${visibleColumns.length - 12} more)`;
+  stdout.write(`  trusted context: tenant from ${tenantEnv}${input.spec.single_tenant_dev ? " (single-tenant dev source)" : input.spec.tenant_key ? ` via ${input.spec.tenant_key}` : ""}; principal from ${principalEnv}
+`);
+  stdout.write(`  source: ${input.engine} ${input.table.schema}.${input.table.name}
+`);
+  stdout.write(`  primary key: ${input.spec.primary_key}${input.spec.conflict_column ? `; conflict guard: ${input.spec.conflict_column}` : ""}
+`);
+  stdout.write(`  visible fields: ${visiblePreview || "none"}
+`);
+  stdout.write(`  mode: ${input.spec.mode}
+`);
+  stdout.write(`  result envelope: ${input.spec.result_format ? `v${input.spec.result_format}` : "default"}
+`);
+  stdout.write(`  writeback path: ${input.spec.writeback?.executor ?? (input.spec.mode === "review" ? "sql_update" : "none")}
+`);
+  stdout.write(`  read capability: ${readCapability}
+`);
+  if (proposalCapability) stdout.write(`  proposal capability: ${proposalCapability}
+`);
+  stdout.write(`  exposed tools: ${tools2.join(", ")}
+`);
+  stdout.write("  not exposed: execute_sql, approval tools, commit tools, database URLs, write credentials, model-controlled tenant authority\n");
+}
 async function initFromSpec(args, specPath) {
   if (!args.includes("--non-interactive")) {
     throw new Error("init --spec requires --non-interactive so reviewed selections are explicit.");
@@ -7114,9 +7306,123 @@ async function initFromSpec(args, specPath) {
   const force = args.includes("--force");
   const spec = JSON.parse(await fs3.readFile(specPath, "utf8"));
   const generated = generateRunnerConfigFromSpec(spec);
+  if (args.includes("--dry-run")) {
+    process2.stdout.write(`${JSON.stringify(generated.config, null, 2)}
+`);
+    return 0;
+  }
+  await writeGeneratedOnboardingFiles(output, generated, force);
+  return 0;
+}
+async function initFromAnswers(args, answersPath) {
+  const output = outputArg(args) ?? "synapsor.runner.json";
+  const force = args.includes("--force");
+  const raw = JSON.parse(await fs3.readFile(answersPath, "utf8"));
+  const spec = answersToSelectionSpec(raw);
+  const generated = generateRunnerConfigFromSpec(spec);
+  if (args.includes("--dry-run")) {
+    process2.stdout.write(`${JSON.stringify(generated.config, null, 2)}
+`);
+    return 0;
+  }
   await writeGeneratedOnboardingFiles(output, generated, force);
+  await maybeWriteHandlerTemplateForArgs(args, spec.writeback);
   return 0;
 }
+function isScriptedOnboardingArgs(args) {
+  return args.includes("--yes") || args.includes("--non-interactive") || args.includes("--dry-run") || Boolean(optionalArg(args, "--answers")) || Boolean(optionalArg(args, "--inspection-json")) || Boolean(optionalArg(args, "--table"));
+}
+function answersToSelectionSpec(raw) {
+  if (!isRecord6(raw)) throw new Error("--answers file must contain a JSON object");
+  const mode = stringValue(raw.mode) ?? "review";
+  if (!["read_only", "shadow", "review"].includes(mode)) throw new Error("answers.mode must be read_only, shadow, or review");
+  const engine = stringValue(raw.engine) ?? "postgres";
+  if (engine !== "postgres" && engine !== "mysql") throw new Error("answers.engine must be postgres or mysql");
+  const table = requiredAnswerString(raw.table, "table");
+  const objectName = stringValue(raw.object_name) ?? safeObjectName(table);
+  const namespace = stringValue(raw.namespace) ?? inferCapabilityNamespace(table);
+  const writebackRaw = stringValue(raw.writeback) ?? "sql_update";
+  if (!["sql_update", "http_handler", "command_handler"].includes(writebackRaw)) throw new Error("answers.writeback must be sql_update, http_handler, or command_handler");
+  const writeback2 = writebackRaw === "sql_update" ? { executor: "sql_update" } : writebackRaw === "http_handler" ? {
+    executor: "http_handler",
+    handler_url_env: stringValue(raw.handler_url_env) ?? "SYNAPSOR_APP_WRITEBACK_URL",
+    ...stringValue(raw.handler_token_env) ? { handler_token_env: stringValue(raw.handler_token_env) } : {},
+    ...stringValue(raw.handler_signing_secret_env) ? { handler_signing_secret_env: stringValue(raw.handler_signing_secret_env) } : {}
+  } : {
+    executor: "command_handler",
+    handler_command_env: stringValue(raw.handler_command_env) ?? "SYNAPSOR_APP_WRITEBACK_COMMAND"
+  };
+  const patch = parsePatchBindings(arrayOrStringList(raw.patch), "--answers.patch");
+  const allowedColumns = arrayOrStringList(raw.allowed_columns);
+  return {
+    version: 1,
+    engine,
+    mode,
+    source_name: stringValue(raw.source_name),
+    read_url_env: stringValue(raw.read_url_env) ?? stringValue(raw.database_url_env) ?? "DATABASE_URL",
+    write_url_env: writeback2.executor === "sql_update" ? stringValue(raw.write_url_env) ?? "SYNAPSOR_DATABASE_WRITE_URL" : stringValue(raw.write_url_env),
+    schema: requiredAnswerString(raw.schema, "schema"),
+    table,
+    primary_key: requiredAnswerString(raw.primary_key, "primary_key"),
+    tenant_key: stringValue(raw.tenant_column) ?? stringValue(raw.tenant_key),
+    single_tenant_dev: raw.single_tenant_dev === true,
+    conflict_column: stringValue(raw.conflict_column),
+    namespace,
+    object_name: objectName,
+    inspect_tool_name: stringValue(raw.read_tool) ?? stringValue(raw.inspect_tool_name),
+    proposal_tool_name: stringValue(raw.proposal_tool) ?? stringValue(raw.proposal_tool_name),
+    lookup_arg: stringValue(raw.id_arg) ?? stringValue(raw.lookup_arg),
+    inspect_description: stringValue(raw.read_description) ?? stringValue(raw.inspect_description),
+    inspect_returns_hint: stringValue(raw.read_returns_hint) ?? stringValue(raw.inspect_returns_hint),
+    proposal_description: stringValue(raw.proposal_description),
+    proposal_returns_hint: stringValue(raw.proposal_returns_hint),
+    result_format: resultFormatFromAnswerValue(raw.result_format),
+    visible_columns: arrayOrStringList(raw.visible_columns),
+    allowed_columns: allowedColumns.length > 0 ? allowedColumns : void 0,
+    patch,
+    numeric_bounds: parseNumericBoundsInput(arrayOrStringList(raw.patch_bounds ?? raw.numeric_bounds).join(",")),
+    transition_guards: parseTransitionGuardsInput(arrayOrStringList(raw.status_guards ?? raw.transition_guards).join(",")),
+    trusted_context: {
+      tenant_id_env: stringValue(raw.tenant_env) ?? "SYNAPSOR_TENANT_ID",
+      principal_env: stringValue(raw.principal_env) ?? "SYNAPSOR_PRINCIPAL"
+    },
+    approval: {
+      required_role: stringValue(raw.approval_role) ?? "local_reviewer"
+    },
+    writeback: writeback2
+  };
+}
+async function maybeWriteHandlerTemplateForArgs(args, writeback2) {
+  if (!writeback2 || writeback2.executor === "sql_update" || args.includes("--no-emit-handler") || args.includes("--skip-handler-template")) return;
+  if (!args.includes("--emit-handler") && !optionalArg(args, "--handler-template") && !optionalArg(args, "--handler-output") && !optionalArg(args, "--handler-template-output")) return;
+  const defaultTemplate = writeback2.executor === "command_handler" ? "command" : "node-fastify";
+  const template = resolveHandlerTemplateName(optionalArg(args, "--handler-template") ?? defaultTemplate);
+  const output = optionalArg(args, "--handler-output") ?? optionalArg(args, "--handler-template-output") ?? handlerTemplateDefinitions[template].fileName;
+  await writeHandlerTemplateFile(template, output, args.includes("--force"));
+  process2.stdout.write(`created ${output}
+`);
+  process2.stdout.write(`${handlerSecurityWarning}
+`);
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function requiredAnswerString(value, field) {
+  const result = stringValue(value);
+  if (!result) throw new Error(`--answers missing ${field}`);
+  return result;
+}
+function arrayOrStringList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item).trim()).filter(Boolean);
+  if (typeof value === "string") return value.split(",").map((item) => item.trim()).filter(Boolean);
+  return [];
+}
+function resultFormatFromAnswerValue(value) {
+  if (value === void 0 || value === null || value === "" || value === "default") return void 0;
+  if (value === 1 || value === "1" || value === "v1") return 1;
+  if (value === 2 || value === "2" || value === "v2") return 2;
+  throw new Error("result_format must be default, v1, v2, 1, or 2");
+}
 async function initFromInspection(args, inspection, databaseUrlEnv) {
   const tableName = optionalArg(args, "--table");
   if (!tableName) {
@@ -7140,7 +7446,7 @@ async function initFromInspection(args, inspection, databaseUrlEnv) {
     process2.stderr.write(`warning: no database primary-key constraint detected for ${table.schema}.${table.name}; using candidate column ${primaryKey}. Verify uniqueness before enabling writeback.
 `);
   }
-  const tenantKey = optionalArg(args, "--tenant-key") ?? table.suggestions.tenant_columns[0];
+  const tenantKey = optionalArg(args, "--tenant-column") ?? optionalArg(args, "--tenant-key") ?? table.suggestions.tenant_columns[0];
   const singleTenantDev = args.includes("--single-tenant-dev");
   if (!tenantKey && !singleTenantDev) {
     throw new Error(`--tenant-key is required for ${table.schema}.${table.name}, or pass --single-tenant-dev for a reviewed single-tenant dev source.`);
@@ -7163,22 +7469,31 @@ async function initFromInspection(args, inspection, databaseUrlEnv) {
   const allowedColumns = listArg(args, "--allowed-columns") ?? Object.keys(patch);
   const writeback2 = writebackSpecFromArgs(args);
   const sqlWriteback = (writeback2?.executor ?? "sql_update") === "sql_update";
+  const objectName = optionalArg(args, "--object-name") ?? safeObjectName(table.name);
+  const namespace = optionalArg(args, "--namespace") ?? inferCapabilityNamespace(table.name);
   const spec = {
     version: 1,
     engine: inspection.engine,
     mode,
     source_name: optionalArg(args, "--source-name"),
     read_url_env: databaseUrlEnv,
-    write_url_env: sqlWriteback ? optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL" : void 0,
+    write_url_env: sqlWriteback ? optionalArg(args, "--write-url-env") ?? "SYNAPSOR_DATABASE_WRITE_URL" : optionalArg(args, "--write-url-env"),
     schema: table.schema,
     table: table.name,
     primary_key: primaryKey,
     tenant_key: tenantKey,
     single_tenant_dev: singleTenantDev,
     conflict_column: conflictColumn,
-    namespace: optionalArg(args, "--namespace") ?? "source",
-    object_name: optionalArg(args, "--object-name"),
-    lookup_arg: optionalArg(args, "--lookup-arg"),
+    namespace,
+    object_name: objectName,
+    inspect_tool_name: optionalArg(args, "--read-tool") ?? optionalArg(args, "--inspect-tool-name"),
+    proposal_tool_name: optionalArg(args, "--proposal-tool") ?? optionalArg(args, "--proposal-tool-name"),
+    lookup_arg: optionalArg(args, "--id-arg") ?? optionalArg(args, "--lookup-arg"),
+    inspect_description: optionalArg(args, "--read-description") ?? optionalArg(args, "--inspect-description"),
+    inspect_returns_hint: optionalArg(args, "--read-returns-hint") ?? optionalArg(args, "--inspect-returns-hint"),
+    proposal_description: optionalArg(args, "--proposal-description"),
+    proposal_returns_hint: optionalArg(args, "--proposal-returns-hint"),
+    result_format: resultFormatOption(args),
     visible_columns: visibleColumns,
     allowed_columns: allowedColumns,
     patch,
@@ -7194,7 +7509,13 @@ async function initFromInspection(args, inspection, databaseUrlEnv) {
     writeback: writeback2
   };
   const generated = generateRunnerConfigFromSpec(spec);
+  if (args.includes("--dry-run")) {
+    process2.stdout.write(`${JSON.stringify(generated.config, null, 2)}
+`);
+    return 0;
+  }
   await writeGeneratedOnboardingFiles(outputArg(args) ?? "synapsor.runner.json", generated, args.includes("--force"));
+  await maybeWriteHandlerTemplateForArgs(args, writeback2);
   process2.stdout.write(`selected ${table.schema}.${table.name} from ${inspection.engine} inspection
 `);
   process2.stdout.write(`exposed tools: ${generated.config.capabilities.map((capability) => capability.name).join(", ")}
@@ -7410,6 +7731,11 @@ function safeObjectName(tableName) {
   const base = tableName.replace(/[^A-Za-z0-9_]/g, "_").replace(/s$/, "");
   return /^[A-Za-z_]/.test(base) ? base : `record_${base}`;
 }
+function inferCapabilityNamespace(tableName) {
+  const objectName = safeObjectName(tableName);
+  const [firstPart] = objectName.split("_").filter(Boolean);
+  return firstPart ?? objectName;
+}
 function requiredWritebackEngine(args) {
   const value = optionalArg(args, "--engine") ?? firstPositional(args);
   if (value === "postgres" || value === "mysql") return value;
@@ -7514,6 +7840,7 @@ function repeatedArgs(args, flag) {
 }
 function parsePatchFlags(args) {
   const patch = {};
+  Object.assign(patch, parsePatchBindings(repeatedArgs(args, "--patch"), "--patch"));
   for (const binding of repeatedArgs(args, "--patch-fixed")) {
     const [column, ...rest] = binding.split("=");
     const value = rest.join("=");
@@ -7528,8 +7855,27 @@ function parsePatchFlags(args) {
   }
   return patch;
 }
+function parsePatchBindings(bindings, label) {
+  const patch = {};
+  for (const rawBinding of bindings.flatMap((binding) => binding.split(",")).map((item) => item.trim()).filter(Boolean)) {
+    const [column, ...rest] = rawBinding.split("=");
+    const expression = rest.join("=");
+    if (!column || !expression) throw new Error(`${label} must use column=fixed:value or column=arg:name`);
+    const [kind, ...valueParts] = expression.split(":");
+    const value = valueParts.join(":");
+    if (!valueParts.length || !value) throw new Error(`${label} must use column=fixed:value or column=arg:name`);
+    if (kind === "fixed") {
+      patch[column] = { fixed: parseFixedPatchValue(value) };
+    } else if (kind === "arg") {
+      patch[column] = { from_arg: value };
+    } else {
+      throw new Error(`${label} patch kind for ${column} must be fixed or arg`);
+    }
+  }
+  return patch;
+}
 function parseNumericBoundsFlags(args) {
-  return parseNumericBoundsInput(repeatedArgs(args, "--numeric-bound").join(","));
+  return parseNumericBoundsInput([...repeatedArgs(args, "--numeric-bound"), ...repeatedArgs(args, "--patch-bounds")].join(","));
 }
 function parseNumericBoundsInput(input) {
   const bounds = {};
@@ -7561,7 +7907,7 @@ function formatNumericBounds(bounds) {
   return Object.entries(bounds).map(([column, bound]) => `${column}=${bound.minimum ?? ""}:${bound.maximum ?? ""}`).join(",");
 }
 function parseTransitionGuardFlags(args) {
-  return parseTransitionGuardsInput(repeatedArgs(args, "--transition-guard").join(","));
+  return parseTransitionGuardsInput([...repeatedArgs(args, "--transition-guard"), ...repeatedArgs(args, "--status-guards")].join(","));
 }
 function parseTransitionGuardsInput(input) {
   const guards = {};
@@ -9131,9 +9477,211 @@ async function start(args = []) {
   await startPolling(config, adapters, controller.signal);
   return 0;
 }
+async function up(args = []) {
+  const allowed = /* @__PURE__ */ new Set([
+    "--config",
+    "--store",
+    "--transport",
+    "--serve",
+    "--with-handler",
+    "--host",
+    "--port",
+    "--auth-token-env",
+    "--alias-mode",
+    "--tool-name-style",
+    "--openai-tool-aliases",
+    "--result-format",
+    "--handler-check",
+    "--open-ui",
+    "--print-next",
+    "--dry-run",
+    "--dev-no-auth",
+    "--cors-origin",
+    "--allow-concurrent-store"
+  ]);
+  assertKnownOptions(args, allowed, "up");
+  const configPath = optionalArg(args, "--config") ?? defaultConfigPath;
+  const config = await readRuntimeConfig(configPath);
+  const storePath = optionalArg(args, "--store") ?? config.storage?.sqlite_path ?? defaultStorePath;
+  const serveRequested = args.includes("--serve");
+  const transport = optionalArg(args, "--transport") ?? (serveRequested ? "streamable-http" : "stdio");
+  if (transport !== "stdio" && transport !== "streamable-http") {
+    throw new Error("--transport must be stdio or streamable-http");
+  }
+  if (serveRequested && transport === "stdio") {
+    throw new Error("up --serve starts the Streamable HTTP MCP server. Omit --transport or use --transport streamable-http; for stdio, use mcp client-config so the client launches Runner.");
+  }
+  const port = Number(optionalArg(args, "--port") ?? "8766");
+  if (transport === "streamable-http" && (!Number.isInteger(port) || port <= 0 || port > 65535)) {
+    throw new Error("--port must be an integer from 1 to 65535");
+  }
+  const aliasMode = toolNameStyleOption(args);
+  const resultFormat = resultFormatOption(args);
+  const validation = validateRunnerCapabilityConfig(config);
+  if (!validation.ok) {
+    throw new Error(`cannot bring Runner up with invalid config: ${validation.errors.map((error) => `${error.path} ${error.code}`).join("; ")}`);
+  }
+  if (storePath !== ":memory:") {
+    await fs3.mkdir(path3.dirname(path3.resolve(storePath)), { recursive: true });
+  }
+  await assertNoActiveStoreLease(storePath, args.includes("--allow-concurrent-store"), "review-mode up");
+  const boundary = await inspectMcpToolBoundary([
+    "--config",
+    configPath,
+    "--store",
+    storePath,
+    "--alias-mode",
+    aliasMode
+  ]);
+  process2.stdout.write(formatReviewModeUp({
+    aliasMode,
+    authTokenEnv: optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
+    boundary,
+    config,
+    configPath,
+    dryRun: args.includes("--dry-run"),
+    host: optionalArg(args, "--host") ?? "127.0.0.1",
+    openUi: args.includes("--open-ui"),
+    port,
+    resultFormat,
+    serveRequested,
+    storePath,
+    transport
+  }));
+  if (args.includes("--with-handler") || args.includes("--handler-check")) {
+    process2.stdout.write("\nHandler check:\n");
+    const doctorCode = await doctor(["--config", configPath, "--store", storePath, "--check-handlers"]);
+    if (doctorCode !== 0) return doctorCode;
+  }
+  if (args.includes("--dry-run") || !serveRequested) return boundary.ok ? 0 : 1;
+  if (!boundary.ok) return 1;
+  const serveArgs = [
+    "--config",
+    configPath,
+    "--store",
+    storePath,
+    "--host",
+    optionalArg(args, "--host") ?? "127.0.0.1",
+    "--port",
+    String(port),
+    "--auth-token-env",
+    optionalArg(args, "--auth-token-env") ?? "SYNAPSOR_RUNNER_HTTP_TOKEN",
+    "--alias-mode",
+    aliasMode,
+    ...resultFormat ? ["--result-format", String(resultFormat)] : [],
+    ...args.includes("--dev-no-auth") ? ["--dev-no-auth"] : [],
+    ...optionalArg(args, "--cors-origin") ? ["--cors-origin", optionalArg(args, "--cors-origin")] : [],
+    ...args.includes("--allow-concurrent-store") ? ["--allow-concurrent-store"] : []
+  ];
+  return mcpServeStreamableHttp(serveArgs);
+}
+function formatReviewModeUp(input) {
+  const lines = [
+    "Synapsor Runner review-mode up",
+    "",
+    `Config: ${input.configPath}`,
+    `Store: ${input.storePath}`,
+    `Mode: ${input.config.mode}`,
+    `Transport: ${input.transport}`,
+    `Serve now: ${input.serveRequested ? "yes" : "no"}`,
+    `Alias mode: ${input.aliasMode}`,
+    `Result format: ${input.resultFormat ? `v${input.resultFormat}` : configResultFormat(input.config)}`,
+    `Dry run: ${input.dryRun ? "yes" : "no"}`,
+    "",
+    "Model-facing tools:",
+    ...formatUpToolLines(input.boundary),
+    "",
+    "Writeback paths:",
+    ...formatUpWritebackLines(input.config)
+  ];
+  const handlerLines = formatUpHandlerLines(input.config);
+  if (handlerLines.length > 0) {
+    lines.push("", "App-owned handler requirements:", ...handlerLines, "", handlerSecurityWarning);
+  }
+  lines.push("", "Server guidance:");
+  if (input.transport === "stdio") {
+    lines.push(
+      "  stdio mode is launched by an MCP client. This command does not hold a protocol session open.",
+      `  Print client config: ${cliCommandName()} mcp client-config --client claude-desktop --config ${input.configPath} --store ${input.storePath}`,
+      `  Serve command used by clients: ${cliCommandName()} mcp serve --config ${input.configPath} --store ${input.storePath} --alias-mode ${input.aliasMode}`
+    );
+  } else {
+    lines.push(
+      `  Streamable HTTP endpoint: http://${input.host}:${input.port}/mcp`,
+      `  Auth token env: ${input.authTokenEnv} (${process2.env[input.authTokenEnv] ? "set" : "missing"})`,
+      input.serveRequested ? input.dryRun ? "  Status: dry run only; server not started." : "  Status: starting after this checklist." : `  Start command: ${cliCommandName()} up --serve --config ${input.configPath} --store ${input.storePath} --port ${input.port} --auth-token-env ${input.authTokenEnv} --alias-mode ${input.aliasMode}`
+    );
+  }
+  if (input.openUi) {
+    lines.push("", "Local review UI:", `  ${cliCommandName()} ui --open --tour --config ${input.configPath} --store ${input.storePath}`);
+  }
+  lines.push("", "Next commands:", ...formatUpNextCommands(input.config, input.configPath, input.storePath), "");
+  return `${lines.join("\n")}
+`;
+}
+function formatUpToolLines(boundary) {
+  if (boundary.exposures.length === 0) return ["  - (none)"];
+  return boundary.exposures.map((item) => item.isAlias ? `  - ${item.exposedName} -> ${item.canonicalName}` : `  - ${item.exposedName}`);
+}
+function formatUpWritebackLines(config) {
+  const proposals2 = (config.capabilities ?? []).filter((capability) => capability.kind === "proposal");
+  if (proposals2.length === 0) return ["  - no proposal capabilities; this config is read-only from Runner's perspective"];
+  return proposals2.map((capability) => {
+    const executorName = capability.executor ?? "sql_update";
+    if (executorName === "sql_update") {
+      const source = config.sources?.[capability.source];
+      const envName = source?.write_url_env ?? "SYNAPSOR_DATABASE_URL";
+      return `  - ${capability.name}: direct guarded one-row UPDATE via ${envName} (${process2.env[envName] ? "set" : "missing"})`;
+    }
+    const executor = config.executors?.[executorName];
+    return `  - ${capability.name}: app-owned ${String(executor?.type ?? "executor")} ${executorName}`;
+  });
+}
+function formatUpHandlerLines(config) {
+  const lines = [];
+  for (const [name, executor] of Object.entries(config.executors ?? {})) {
+    if (!isRecord6(executor)) continue;
+    if (executor.type === "http_handler") {
+      const urlEnv = typeof executor.url_env === "string" ? executor.url_env : "";
+      const auth = isRecord6(executor.auth) ? executor.auth : void 0;
+      const tokenEnv = typeof auth?.token_env === "string" ? auth.token_env : void 0;
+      const signingSecretEnv = typeof executor.signing_secret_env === "string" ? executor.signing_secret_env : void 0;
+      lines.push(`  - ${name}: http_handler`);
+      if (urlEnv) lines.push(`    url env: ${urlEnv} (${process2.env[urlEnv] ? "set" : "missing"})`);
+      if (tokenEnv) lines.push(`    bearer token env: ${tokenEnv} (${process2.env[tokenEnv] ? "set" : "missing"})`);
+      if (signingSecretEnv) lines.push(`    signing secret env: ${signingSecretEnv} (${process2.env[signingSecretEnv] ? "set" : "missing"})`);
+      if (!signingSecretEnv) lines.push("    signing secret env: not configured (recommended unless loopback-only)");
+    } else if (executor.type === "command_handler") {
+      const commandEnv = typeof executor.command_env === "string" ? executor.command_env : "";
+      lines.push(`  - ${name}: command_handler`);
+      if (commandEnv) lines.push(`    command env: ${commandEnv} (${process2.env[commandEnv] ? "set" : "missing"})`);
+    }
+  }
+  return lines;
+}
+function configResultFormat(config) {
+  return config.result_format === 2 ? "v2" : config.result_format === 1 ? "v1" : "default";
+}
+function formatUpNextCommands(config, configPath, storePath) {
+  const firstTool = (config.capabilities ?? [])[0]?.name ?? "<capability>";
+  const hasHandlers = Object.keys(config.executors ?? {}).length > 0;
+  return [
+    `  - Preview tools: ${cliCommandName()} tools preview --config ${configPath} --store ${storePath}`,
+    `  - Smoke call: ${cliCommandName()} smoke call ${firstTool} --sample --config ${configPath} --store ${storePath}`,
+    `  - List proposals: ${cliCommandName()} proposals list --store ${storePath}`,
+    `  - Show proposal: ${cliCommandName()} proposals show latest --store ${storePath}`,
+    `  - Approve proposal: ${cliCommandName()} proposals approve latest --yes --store ${storePath}`,
+    `  - Apply approved proposal: ${cliCommandName()} apply latest --config ${configPath} --store ${storePath}`,
+    `  - Replay: ${cliCommandName()} replay show latest --store ${storePath}`,
+    `  - Tail events: ${cliCommandName()} events tail --store ${storePath}`,
+    `  - Direct writeback doctor: ${cliCommandName()} doctor --config ${configPath} --check-writeback`,
+    ...hasHandlers ? [`  - Handler doctor: ${cliCommandName()} doctor --config ${configPath} --check-handlers`] : []
+  ];
+}
 async function runnerCommand(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "start") return start(rest);
+  if (subcommand === "up") return up(rest);
   if (subcommand === "doctor") return doctor(rest);
   usage();
   return 2;
@@ -9172,7 +9720,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.15").trim();
+  const runnerVersion = String(parsed.cloud.runner_version || process2.env.npm_package_version || "0.1.0-alpha.17").trim();
   const engines = normalizeEngines(parsed.cloud.engines);
   const capabilities = normalizeCapabilities(parsed.cloud.capabilities);
   const client = new ControlPlaneClient({
@@ -9277,21 +9825,28 @@ async function handlerTemplate(args) {
     return 0;
   }
   const output = outputArg(args) ?? definition.fileName;
-  await writeFileGuarded(output, content, args.includes("--force"));
-  if (name === "command" || output.endsWith(".mjs") || output.endsWith(".js")) {
-    await fs3.chmod(path3.resolve(output), 493).catch(() => void 0);
-  }
+  await writeHandlerTemplateFile(name, output, args.includes("--force"));
   process2.stdout.write(`created ${output}
 `);
-  process2.stdout.write("Review the template and add your app-owned transaction, authorization, idempotency, and conflict checks before using it with approved proposals.\n");
+  process2.stdout.write(`${handlerSecurityWarning}
+`);
   return 0;
 }
+async function writeHandlerTemplateFile(name, output, force) {
+  const definition = handlerTemplateDefinitions[name];
+  await writeFileGuarded(output, definition.content, force);
+  if (name === "command" || output.endsWith(".mjs") || output.endsWith(".js")) {
+    await fs3.chmod(path3.resolve(output), 493).catch(() => void 0);
+  }
+}
 function formatHandlerTemplateList() {
   return [
     "Synapsor app-owned writeback handler templates",
     "",
     ...Object.entries(handlerTemplateDefinitions).map(([name, definition]) => `- ${name}: ${definition.description}`),
     "",
+    handlerSecurityWarning,
+    "",
     "Examples:",
     `  ${cliCommandName()} handler template node-fastify --output ./synapsor-writeback-handler.mjs`,
     `  ${cliCommandName()} handler template python-fastapi --output ./synapsor_writeback_handler.py`,
@@ -9390,8 +9945,10 @@ async function onboard(args) {
   process2.stdout.write("You will inspect metadata, choose one table/view, confirm safety rules, and generate semantic MCP tools without writing JSON by hand.\n\n");
   const outputPath = outputArg(rest) ?? "synapsor.runner.json";
   const storePath = optionalArg(rest, "--store") ?? "./.synapsor/local.db";
-  const result = await runInitWizard(["--wizard", ...rest]);
+  const scripted = isScriptedOnboardingArgs(rest);
+  const result = scripted ? await init(["--non-interactive", ...rest]) : await runInitWizard(["--wizard", ...rest]);
   if (result !== 0) return result;
+  if (rest.includes("--dry-run")) return 0;
   process2.stdout.write("\nValidation:\n");
   const configCode = await configValidate(["--config", outputPath]);
   const smokeCode = await mcpSmoke(["--config", outputPath, "--store", storePath]);
@@ -10040,7 +10597,7 @@ async function assertNoActiveStoreLease(storePath, force, operation) {
     await fs3.rm(storeLeasePath(resolved), { force: true });
     return;
   }
-  const message = `Local store appears active for ${lease.mode}/${lease.transport} (pid ${lease.pid}, started ${lease.started_at}). Refusing ${operation}. Stop the server or rerun with --force if you have verified it is safe.`;
+  const message = `Local store appears active for ${lease.mode}/${lease.transport} (pid ${lease.pid}, started ${lease.started_at}). Refusing ${operation}. Stop the server or rerun with --allow-concurrent-store/--force if you have verified it is safe.`;
   if (!force) throw new Error(message);
   process2.stderr.write(`Warning: ${message}
 `);
@@ -10104,6 +10661,12 @@ function resultFormatOption(args) {
   if (requested === "2" || requested === "v2") return 2;
   throw new Error("--result-format must be v1, 1, v2, or 2");
 }
+function normalizeResultFormatAnswer(value) {
+  if (value === "1" || value === "v1") return "v1";
+  if (value === "2" || value === "v2") return "v2";
+  if (value === "default") return "default";
+  throw new Error("--result-format must be default, v1, 1, v2, or 2");
+}
 async function mcpAudit(args) {
   const format = optionalArg(args, "--format") ?? (args.includes("--json") ? "json" : "text");
   if (!["text", "json", "markdown"].includes(format)) {
@@ -11126,6 +11689,7 @@ async function activity(args) {
 async function events(args) {
   const [subcommand, ...rest] = args;
   if (subcommand === "tail") return eventsTail(rest);
+  if (subcommand === "webhook" || subcommand === "push") return eventsWebhook(rest);
   usage(["events"]);
   return 2;
 }
@@ -11700,6 +12264,75 @@ async function eventsTail(args) {
   });
   return 0;
 }
+async function eventsWebhook(args) {
+  assertKnownOptions(args, eventWebhookAllowedOptions, "events webhook");
+  const url = optionalArg(args, "--url") ?? envValue(optionalArg(args, "--url-env"));
+  if (!url) throw new Error("events webhook requires --url <https://...> or --url-env <ENV>");
+  const endpoint = new URL(url);
+  if (!["http:", "https:"].includes(endpoint.protocol)) throw new Error("events webhook URL must use http or https");
+  const follow = args.includes("--follow");
+  const dryRun = args.includes("--dry-run");
+  const jsonOutput = args.includes("--json");
+  if (follow && jsonOutput) throw new Error("events webhook --follow does not support --json");
+  const storePath = optionalArg(args, "--store");
+  const intervalMs = Number(optionalArg(args, "--interval-ms") ?? "1000");
+  const timeoutMs = Number(optionalArg(args, "--timeout-ms") ?? "5000");
+  const sinceEventId = optionalPositiveIntegerArg(args, "--since-event-id");
+  if (!Number.isFinite(intervalMs) || intervalMs < 250) throw new Error("--interval-ms must be at least 250");
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 250) throw new Error("--timeout-ms must be at least 250");
+  const token = envValue(optionalArg(args, "--auth-token-env"));
+  const filters = eventFiltersFromArgs(args);
+  const seen = /* @__PURE__ */ new Set();
+  const pushOnce = async () => {
+    const store = await openLocalStore(["--store", storePath ?? "./.synapsor/local.db"]);
+    try {
+      const rows = store.listEvents(filters).filter((event) => sinceEventId === void 0 || event.event_id > sinceEventId).sort((left, right) => left.event_id - right.event_id).filter((event) => !seen.has(event.event_id));
+      rows.forEach((event) => seen.add(event.event_id));
+      let delivered = 0;
+      const payloads = [];
+      for (const event of rows) {
+        const payload = localEventWebhookPayload(event, store.path);
+        payloads.push(payload);
+        if (dryRun) {
+          if (!jsonOutput) process2.stdout.write(`${JSON.stringify(payload, null, 2)}
+`);
+        } else {
+          await postLocalEventWebhook(endpoint, payload, { token, timeoutMs });
+          if (!jsonOutput) process2.stdout.write(`pushed event ${event.event_id} ${event.kind} for ${event.proposal_id} to ${redactWebhookUrl(endpoint)}
+`);
+        }
+        delivered += 1;
+      }
+      if (rows.length === 0 && !follow && !jsonOutput) process2.stdout.write(dryRun ? "No local events matched for dry-run.\n" : "No local events matched.\n");
+      return { delivered, payloads };
+    } finally {
+      store.close();
+    }
+  };
+  const first = await pushOnce();
+  if (jsonOutput && !follow) {
+    process2.stdout.write(`${JSON.stringify({ ok: true, dry_run: dryRun, delivered: first.delivered, webhook: redactWebhookUrl(endpoint), events: first.payloads }, null, 2)}
+`);
+  }
+  if (!follow) return 0;
+  await new Promise((resolve) => {
+    const timer = setInterval(() => {
+      void pushOnce().catch((error) => {
+        process2.stderr.write(`events webhook error: ${safeErrorMessage(error)}
+`);
+      });
+    }, intervalMs);
+    const stop = () => {
+      clearInterval(timer);
+      process2.off("SIGINT", stop);
+      process2.off("SIGTERM", stop);
+      resolve();
+    };
+    process2.once("SIGINT", stop);
+    process2.once("SIGTERM", stop);
+  });
+  return 0;
+}
 async function storeStats(args) {
   assertKnownOptions(args, storeStatsAllowedOptions, "store stats");
   const store = await openLocalStore(args);
@@ -11849,6 +12482,15 @@ var eventTailAllowedOptions = /* @__PURE__ */ new Set([
   "--follow",
   "--interval-ms"
 ]);
+var eventWebhookAllowedOptions = /* @__PURE__ */ new Set([
+  ...eventTailAllowedOptions,
+  "--url",
+  "--url-env",
+  "--auth-token-env",
+  "--timeout-ms",
+  "--since-event-id",
+  "--dry-run"
+]);
 var replayShowAllowedOptions = /* @__PURE__ */ new Set([...commonReadOptions, "--proposal", "--replay", "--evidence"]);
 var replayExportAllowedOptions = /* @__PURE__ */ new Set([...replayShowAllowedOptions, "--output", "--out", "--format"]);
 var replayListAllowedOptions = /* @__PURE__ */ new Set([
@@ -12051,6 +12693,17 @@ function eventFiltersFromArgs(args) {
     limit: limitFromArgs(args)
   };
 }
+function optionalPositiveIntegerArg(args, flag) {
+  const value = optionalArg(args, flag);
+  if (!value) return void 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative integer`);
+  return parsed;
+}
+function envValue(name) {
+  if (!name) return void 0;
+  return process2.env[name];
+}
 function linkedProposalFilter(args, store, options = {}) {
   const noLinkedProposal = "__synapsor_no_linked_proposal__";
   const replay2 = optionalArg(args, "--replay");
@@ -12231,8 +12884,8 @@ async function prepareReferenceDemo(args) {
   ].join("\n"));
   const down = spawnSync("docker", ["compose", "-f", composePath, "down", "-v", "--remove-orphans"], { stdio: "inherit", env: process2.env });
   if (down.status !== 0) return down.status ?? 1;
-  const up = spawnSync("docker", ["compose", "-f", composePath, "up", "-d"], { stdio: "inherit", env: process2.env });
-  if (up.status !== 0) return up.status ?? 1;
+  const up2 = spawnSync("docker", ["compose", "-f", composePath, "up", "-d"], { stdio: "inherit", env: process2.env });
+  if (up2.status !== 0) return up2.status ?? 1;
   await waitForReferenceDemoDatabase();
   await fs3.copyFile(path3.join(demoDir, "synapsor.runner.json"), configPath);
   process2.stdout.write([
@@ -12384,6 +13037,10 @@ function firstPositional(args) {
     "--reason",
     "--recipe",
     "--receipt",
+    "--read-tool",
+    "--inspect-tool-name",
+    "--proposal-tool",
+    "--proposal-tool-name",
     "--replay",
     "--runner",
     "--schema",
@@ -13024,6 +13681,48 @@ function formatEventLine(event, details = false) {
   return `${lines.join("\n")}
 `;
 }
+function localEventWebhookPayload(event, storePath) {
+  return {
+    schema_version: "synapsor.local-event-webhook.v1",
+    delivered_at: (/* @__PURE__ */ new Date()).toISOString(),
+    source: {
+      kind: "local_store",
+      store_path: storePath
+    },
+    event
+  };
+}
+async function postLocalEventWebhook(endpoint, payload, options) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+  try {
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json",
+      "user-agent": "synapsor-runner-events-webhook"
+    };
+    if (options.token) headers.authorization = `Bearer ${options.token}`;
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new Error(`webhook returned HTTP ${response.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+    }
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function redactWebhookUrl(endpoint) {
+  const copy = new URL(endpoint.toString());
+  copy.username = "";
+  copy.password = "";
+  copy.search = "";
+  return copy.toString();
+}
 function safeErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -13311,7 +14010,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.15",
+      runner_version: "0.1.0-alpha.17",
       project_id: "token_scope",
       adapter_id: "mcp.your_adapter",
       source_id: "src_replace_me",
@@ -13346,6 +14045,7 @@ function isKnownTopLevelCommand(command) {
     "propose",
     "audit",
     "start",
+    "up",
     "runner",
     "cloud",
     "mcp",
@@ -13388,6 +14088,7 @@ Usage:
 Commands:
   inspect      Inspect a Postgres/MySQL schema
   start        Start guided own-database setup, or no-arg legacy worker polling
+  up           Bring up local review mode guidance/server
   init         Generate a Synapsor capability contract
   mcp          Serve safe semantic tools over MCP
   onboard      One-command own-database setup
@@ -13402,7 +14103,7 @@ Commands:
   query-audit Inspect local query audit records
   receipts    Inspect guarded writeback receipts
   activity    Search local evidence/replay ledger
-  events      Tail local proposal/writeback lifecycle events
+  events      Tail or push local proposal/writeback lifecycle events
   store       Inspect and maintain the local SQLite ledger
   apply        Apply an approved proposal with guarded writeback
   replay       Show what happened
@@ -13411,6 +14112,7 @@ Commands:
 
 Examples:
   ${cmd} start --from-env DATABASE_URL
+  ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db --dry-run
   ${cmd} onboard db --from-env DATABASE_URL
   ${cmd} inspect --from-env DATABASE_URL
   ${cmd} init --wizard --from-env DATABASE_URL
@@ -13420,6 +14122,29 @@ Examples:
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} propose billing.propose_late_fee_waiver --sample
   ${cmd} audit ./synapsor.runner.json
+`,
+    up: `Usage:
+  ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db [--transport stdio|streamable-http]
+  ${cmd} up --serve --config ./synapsor.runner.json --store ./.synapsor/local.db --port 8766 --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+  ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db --handler-check --dry-run
+
+Validate the local Runner config and store, summarize model-facing tools,
+explain direct SQL versus app-owned executor writeback, and print the next
+smoke/approve/apply/replay commands.
+
+With --transport stdio, \`${cmd} up\` prints MCP client wiring because stdio is
+launched by the client. \`${cmd} up --serve\` starts the standard Streamable HTTP
+MCP server after the checklist. Use --with-handler to run the handler doctor
+before serving app-owned writeback configs.
+
+Options:
+  --serve
+  --alias-mode canonical|openai|both
+  --result-format v1|v2
+  --handler-check
+  --with-handler
+  --open-ui
+  --dry-run
 `,
     start: `Usage:
   ${cmd} start --from-env DATABASE_URL [--schema public] [--mode read_only|shadow|review]
@@ -13444,12 +14169,17 @@ Inspect schema metadata without mutating the database or printing credentials.
     init: `Usage:
   ${cmd} init --wizard --from-env DATABASE_URL [--mode read_only|review|shadow] [--out synapsor.runner.json]
   ${cmd} init --engine postgres --url-env DATABASE_URL --mode review --table public.invoices
-  ${cmd} init --inspection-json schema.json --table invoices --mode review --patch-from-arg waiver_reason=reason
-  ${cmd} init --inspection-json schema.json --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL [--handler-signing-secret-env APP_WRITEBACK_SIGNING_SECRET]
+  ${cmd} init --inspection-json schema.json --table invoices --mode review --patch late_fee_cents=fixed:0,waiver_reason=arg:reason
+  ${cmd} init --answers answers.json --yes
+  ${cmd} init --inspection-json schema.json --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL --emit-handler [--handler-signing-secret-env APP_WRITEBACK_SIGNING_SECRET]
 
 Generate a reviewed Synapsor Runner contract. Defaults to read-only in the wizard.
 Review mode writeback choices: sql_update, http_handler, command_handler.
-`,
+If --namespace is omitted, init derives one from the table name instead of using source.*.
+Use --read-tool and --proposal-tool to override the exact model-facing capability names.
+The guided wizard shows a final preview and lets you revise visible fields or capability names before writing files.
+Use --yes/--non-interactive plus explicit flags, or --answers, for script/agent-friendly setup without prompts.
+	`,
     mcp: `Usage:
   ${cmd} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
   ${cmd} mcp serve --transport streamable-http --config ./synapsor.runner.json --store ./.synapsor/local.db --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
@@ -13576,9 +14306,12 @@ The template receives an approved proposal writeback request and must return an
 `,
     onboard: `Usage:
   ${cmd} onboard db --from-env DATABASE_URL [--schema public] [--mode read_only|shadow|review]
-  ${cmd} onboard db --from-env DATABASE_URL --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL
+  ${cmd} onboard db --from-env DATABASE_URL --table invoices --mode review --patch late_fee_cents=fixed:0 --write-url-env SYNAPSOR_DATABASE_WRITE_URL --yes
+  ${cmd} onboard db --from-env DATABASE_URL --table invoices --mode review --writeback http_handler --handler-url-env APP_WRITEBACK_URL --emit-handler --yes
+  ${cmd} onboard db --answers answers.json --yes
 
 Guided own-database setup: inspect schema, choose one object, create trusted context, choose read-only/shadow/review writeback mode, generate semantic tools, validate config, run a tool-boundary smoke check, and print the MCP/UI next steps.
+Use --yes/--non-interactive with explicit flags, or --answers, when CI or an LLM agent must run without prompts.
 `,
     propose: `Usage:
   ${cmd} propose <capability-name> --sample [--config ./synapsor.runner.json] [--store ./.synapsor/local.db]
@@ -13682,12 +14415,15 @@ Search the local SQLite evidence/replay ledger across proposals, evidence, query
 `,
     events: `Usage:
   ${cmd} events tail --store ./.synapsor/local.db
-  ${cmd} events tail --proposal wrp_...
-  ${cmd} events tail --kind writeback_applied
-  ${cmd} events tail --follow --interval-ms 1000
+	  ${cmd} events tail --proposal wrp_...
+	  ${cmd} events tail --kind writeback_applied
+	  ${cmd} events tail --follow --interval-ms 1000
+  ${cmd} events webhook --url http://127.0.0.1:8788/synapsor/events --kind proposal_created
+  ${cmd} events webhook --url-env SYNAPSOR_EVENT_WEBHOOK_URL --auth-token-env SYNAPSOR_EVENT_WEBHOOK_TOKEN --follow
+  ${cmd} events webhook --url http://127.0.0.1:8788/synapsor/events --dry-run
 
-Show local proposal/writeback lifecycle events such as proposal_created, proposal_approved, writeback_applied, writeback_conflict, and writeback_failed.
-`,
+Show or push local proposal/writeback lifecycle events such as proposal_created, proposal_approved, writeback_applied, writeback_conflict, and writeback_failed. Webhook delivery POSTs one local event envelope per event and never exposes database credentials.
+	`,
     store: `Usage:
   ${cmd} store stats --store ./.synapsor/local.db
   ${cmd} store vacuum --store ./.synapsor/local.db