@synapsor/runner 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+### Cloud Adoption Loop
+
+- Stages `@synapsor/spec@0.1.4`, `@synapsor/dsl@0.1.4`, and
+  `@synapsor/runner@0.1.11` without publishing them.
+- Adds a seven-file MCP client bundle for Claude Desktop, Cursor, OpenAI Agents
+  SDK, and generic stdio/Streamable HTTP clients, including OpenAI-safe tool
+  aliases.
+- Productizes local and Cloud-generated Runner bundles with placeholder env
+  wiring, validation/run instructions, and no embedded credentials or rows.
+- Adds a network-free adoption quickstart verifier and a real local
+  Runner-to-Cloud-to-ZIP-to-Runner verification path around the flagship
+  `support-plan-credit` contract.
+- Documents the Cloud registry/version/bundle loop and avoids implying managed
+  runner fleets, SAML/SCIM, hosted policy enforcement, or enterprise SLA.
+- Adds `SYNAPSOR_CLOUD_WORKSPACE` support and explicit Cloud push failure tests
+  for authorization, validation, conflict, server, and network outcomes.
+- Corrects `cloud push --help` so it describes the implemented authenticated
+  upload path and the network-free dry-run instead of the removed pre-registry
+  limitation.
+
+## 0.1.10
+
 ### Policy Auto-Approval
 
 - Stages `@synapsor/spec@0.1.3`, `@synapsor/dsl@0.1.3`, and

package/README.md

@@ -6,10 +6,11 @@
 
 Stop giving AI agents `execute_sql()`. Give them reviewed business actions.
 
-Synapsor Runner is an Open-source MCP safety layer for Postgres and MySQL. It
-sits between Claude, Cursor, OpenAI Agents SDK, or another MCP client and your
-database so the model can inspect scoped data and propose changes without
-receiving raw SQL, write credentials, approval tools, or commit authority.
+Synapsor Runner is an open-source, local-first MCP server that exposes reviewed semantic
+capabilities over Postgres and MySQL, stages risky writes as proposals, and
+keeps evidence and replay for agent actions. It sits between Claude, Cursor,
+OpenAI Agents SDK, or another MCP client and your database so the model does
+not receive raw SQL, write credentials, approval tools, or commit authority.
 
 ```text
 Without Synapsor:
@@ -25,9 +26,12 @@ With Synapsor Runner:
 Try the no-database quick demo:
 
 ```bash
-npx @synapsor/runner demo --quick
+npx -y @synapsor/runner demo --quick
 ```
 
+You will see semantic tools instead of raw SQL, an exact proposal rather than
+an immediate write, approval/apply outside MCP, and a receipt/replay record.
+
 ## The Five-Line Model
 
 Your agent talks to Synapsor Runner, not directly to your database.
@@ -70,7 +74,7 @@ Run the guided quick demo first. It does not require Docker, a database, a
 config file, an MCP client, or a Synapsor Cloud account.
 
 ```bash
-npx @synapsor/runner demo --quick
+npx -y @synapsor/runner demo --quick
 ```
 
 In a terminal, it walks through the safety model step by step. In CI, piped
@@ -82,7 +86,7 @@ It does not prove database connectivity. It shows the proposal, evidence, and
 replay flow without giving the runner a database URL.
 
 ```bash
-npx @synapsor/runner demo inspect
+npx -y @synapsor/runner demo inspect
 ```
 
 Then choose one path:
@@ -129,6 +133,13 @@ are a good start. Use Runner when you need the agent-facing boundary around
 those reads, or when database-backed actions must become proposals before any
 durable write happens.
 
+## More Than A Tool Proxy
+
+Synapsor is intentionally more than an MCP wrapper. The public packages include
+a versioned contract, DSL compiler, schema validation, conformance fixtures,
+Runner enforcement, proposal/evidence/replay artifacts, Cloud registry push,
+and C++/Cloud round-trip verification.
+
 ## Connect Your Postgres Or MySQL
 
 Use a staging or disposable database first:
@@ -310,6 +321,16 @@ See [`docs/dsl-json-parity.md`](docs/dsl-json-parity.md) for the current
 field-by-field support matrix across JSON spec, DSL, runner enforcement,
 C++/Cloud compatibility, and Cloud push.
 
+After a real push, open **Contract registry** in Synapsor Cloud to inspect the
+immutable version, semantic capabilities, workflows, visible and kept-out
+fields, policy references, warnings, and registry audit events. Downloading a
+runner bundle returns the same normalized contract with placeholder local
+wiring and ready-to-copy MCP configs.
+
+- [Cloud push](docs/cloud-push.md)
+- [Runner bundles](docs/runner-bundles.md)
+- [MCP client configs](docs/mcp-clients.md)
+
 Your `synapsor.runner.json` supplies local wiring: database env var names,
 SQLite store path, MCP transport settings, and local debug options. The
 contract supplies the portable meaning: contexts, capabilities, evidence,
@@ -953,8 +974,9 @@ per lifecycle event; it is not a hosted central ledger.
 
 This is local indexed search for local/dev/staging usage. It is not a hosted
 central ledger, not RBAC/SSO, not cross-runner search, and not compliance
-retention. Synapsor Cloud is the upgrade path for central searchable audit,
-team governance, retention, and production operations.
+retention. Synapsor Cloud adds a shared contract registry and enabled hosted
+activity/evidence surfaces; confirm retention and production operations for
+the specific design-partner deployment.
 
 ## Connect Claude, Cursor, Or Another MCP Client
 
@@ -1217,24 +1239,25 @@ internals.
 
 | Need | Synapsor Runner | Synapsor Cloud |
 | --- | --- | --- |
-| Local MCP server | Yes | Managed |
-| Local trusted context bindings | Yes | Org/session integrated |
+| Local MCP server | Yes | Contracts export back to Runner; a managed fleet is not claimed |
+| Local trusted context bindings | Yes | Contract bindings are registered; hosted session behavior is pilot-specific |
 | Local semantic capabilities | Yes | Hosted registry + versioning |
 | Local evidence/proposal/replay | Yes | Central searchable ledger |
-| Local approval | CLI/UI | Multi-user approvals |
-| Writeback | Guarded single-row `UPDATE` | Managed production orchestration |
+| Local approval | CLI/UI | Existing team approval surfaces where enabled for a pilot |
+| Writeback | Guarded single-row `UPDATE` | Cloud-linked jobs exist; managed production orchestration is not claimed |
 | MCP risk audit | Static/local | Continuous/org-wide |
-| RBAC/SSO | No | Yes |
-| Policy packs | No/basic | Yes |
-| Workflow builder | No | Yes |
+| RBAC/SSO | No | RBAC where configured; SAML/SCIM are not in this beta |
+| Policy packs | Local reviewed subset | Registry preserves policies; hosted enforcement is not implied |
+| Workflow builder | No | Existing Cloud authoring surfaces; full public DAG parity is not claimed |
 | Native branches/time travel | No | Yes |
 | Settlement policies | No | Yes |
-| Compliance exports | No | Yes |
-| Production support/SLA | No | Yes |
+| Compliance exports | No | Audit/retention primitives exist; legal hold/certification are not claimed |
+| Production support/SLA | No | Design-partner support; no enterprise SLA is claimed |
 
-The runner is useful by itself for local/staging safety. Synapsor Cloud is for
-teams, production governance, central audit, managed runners, enterprise
-controls, and proprietary Synapsor platform features.
+The runner is useful by itself for local/staging safety. Synapsor Cloud adds a
+shared contract registry, immutable versions, downloadable Runner bundles, and
+existing team activity/evidence/approval surfaces where enabled. Managed
+runners, SAML/SCIM, legal hold, and an enterprise SLA remain future work.
 
 Portable contracts can be checked locally before Cloud import:
 
@@ -1251,7 +1274,7 @@ synapsor-runner cloud push ./synapsor.contract.json \
 
 ## Current Limitations
 
-Supported in the current alpha:
+Supported in the current `0.1.x` line:
 
 - stdio MCP server;
 - authenticated HTTP MCP server for app/server deployments;
@@ -1327,9 +1350,10 @@ Synapsor name, logo, hosted cloud service, or proprietary Synapsor platform
 features. See [docs/licensing.md](docs/licensing.md) and
 [TRADEMARKS.md](TRADEMARKS.md).
 
-Synapsor Cloud, hosted governance, managed runners, advanced policy/workflow
-engines, enterprise controls, and native Synapsor DBMS/C++ internals remain
-proprietary.
+Synapsor Cloud, hosted governance, advanced policy/workflow engines, enterprise
+controls, and native Synapsor DBMS/C++ internals are outside this Apache-2.0
+repository. Managed runners and other hosted features, where offered, are
+proprietary and are not implied by the OSS package.
 
 ## Developer And Contributor Commands
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAoP,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAoB1Y,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAE/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AA6U3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyD1D;AA+DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2TjB;AA+tED,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAS/H"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAYA,OAAO,EAAoP,KAAK,WAAW,EAA2F,MAAM,6BAA6B,CAAC;AAoB1Y,OAAO,EAA6G,KAAK,YAAY,EAAwB,MAAM,2BAA2B,CAAC;AAE/L,OAAO,EAOL,KAAK,gBAAgB,EAEtB,MAAM,mCAAmC,CAAC;AAgV3C,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyD1D;AA+DD,KAAK,SAAS,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9E,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CACvC,GACL,OAAO,CAAC,MAAM,CAAC,CA2TjB;AAowED,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAS/H"}

package/dist/runner.mjs

@@ -8436,6 +8436,191 @@ function stringOrDefault(value, fallback) {
   return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
 
+// apps/runner/package.json
+var package_default = {
+  name: "@synapsor/runner",
+  version: "0.1.11",
+  description: "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
+  license: "Apache-2.0",
+  type: "module",
+  bin: {
+    "synapsor-runner": "dist/cli.js"
+  },
+  files: [
+    "dist/cli.js",
+    "dist/cli.d.ts",
+    "dist/cli.d.ts.map",
+    "dist/local-ui.d.ts",
+    "dist/local-ui.d.ts.map",
+    "dist/runner.mjs",
+    "docs/**/*.md",
+    "examples/dangerous-mcp-tools.json",
+    "examples/app-owned-writeback/**",
+    "examples/claude-desktop-postgres/**",
+    "examples/cursor-postgres/**",
+    "examples/mcp-postgres-billing-app-handler/**",
+    "examples/mysql-refund-agent/**",
+    "examples/openai-agents-http/**",
+    "examples/openai-agents-stdio/**",
+    "examples/raw-sql-vs-synapsor/**",
+    "examples/reference-support-billing-app/**",
+    "examples/support-plan-credit/**",
+    "examples/support-billing-agent/**",
+    "fixtures/**",
+    "schemas/**",
+    "recipes/**/*.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "TRADEMARKS.md"
+  ],
+  keywords: [
+    "mcp",
+    "postgres",
+    "mysql",
+    "ai-agents",
+    "sql-safety",
+    "database-safety",
+    "openai-agents",
+    "claude",
+    "cursor",
+    "writeback",
+    "replay",
+    "model-context-protocol"
+  ],
+  engines: {
+    node: ">=22.5.0"
+  },
+  scripts: {
+    build: "tsc -b && node ../../scripts/build-runner-package.mjs",
+    prepack: "cd ../.. && corepack pnpm build:runner-package",
+    test: "vitest run"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    mysql2: "^3.11.0",
+    pg: "^8.13.0",
+    zod: "^3.25.0"
+  },
+  devDependencies: {
+    typescript: "^5.7.0",
+    vitest: "^3.2.0"
+  },
+  homepage: "https://synapsor.ai",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/Synapsor/Synapsor-Runner.git"
+  },
+  bugs: {
+    url: "https://synapsor.ai/contact"
+  },
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// packages/dsl/package.json
+var package_default2 = {
+  name: "@synapsor/dsl",
+  version: "0.1.4",
+  description: "Preview SQL-like Synapsor authoring DSL compiler for canonical @synapsor/spec contracts.",
+  license: "Apache-2.0",
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  bin: {
+    "synapsor-dsl": "dist/cli.js"
+  },
+  files: [
+    "dist/**",
+    "examples/**",
+    "README.md",
+    "package.json"
+  ],
+  scripts: {
+    build: "tsc -b",
+    test: "vitest run"
+  },
+  dependencies: {
+    "@synapsor/spec": "workspace:^0.1.4"
+  },
+  devDependencies: {
+    typescript: "^5.7.0",
+    vitest: "^3.2.0"
+  },
+  keywords: [
+    "synapsor",
+    "dsl",
+    "ai-agents",
+    "mcp",
+    "database-safety"
+  ],
+  engines: {
+    node: ">=22.5.0"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/Synapsor/Synapsor-Runner.git",
+    directory: "packages/dsl"
+  },
+  homepage: "https://github.com/Synapsor/Synapsor-Runner/tree/main/packages/dsl#readme",
+  bugs: {
+    url: "https://github.com/Synapsor/Synapsor-Runner/issues"
+  }
+};
+
+// packages/spec/package.json
+var package_default3 = {
+  name: "@synapsor/spec",
+  version: "0.1.4",
+  description: "Canonical Synapsor contract schemas, types, validation, and conformance fixtures.",
+  license: "Apache-2.0",
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  bin: {
+    "synapsor-spec": "dist/cli.js"
+  },
+  files: [
+    "dist/**",
+    "schemas/**",
+    "examples/**",
+    "fixtures/**",
+    "README.md",
+    "package.json"
+  ],
+  scripts: {
+    build: "tsc -b",
+    test: "vitest run"
+  },
+  keywords: [
+    "synapsor",
+    "ai-agents",
+    "mcp",
+    "database-safety",
+    "contracts"
+  ],
+  engines: {
+    node: ">=22.5.0"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/Synapsor/Synapsor-Runner.git",
+    directory: "packages/spec"
+  },
+  homepage: "https://github.com/Synapsor/Synapsor-Runner/tree/main/packages/spec#readme",
+  bugs: {
+    url: "https://github.com/Synapsor/Synapsor-Runner/issues"
+  }
+};
+
 // apps/runner/src/cli.ts
 var adapters = { postgres: postgresAdapter, mysql: mysqlAdapter };
 var handlerReceiptStatuses = /* @__PURE__ */ new Set(["applied", "already_applied", "conflict", "failed"]);
@@ -10042,18 +10227,21 @@ async function contractBundle(args) {
   const firstSource = firstCapability?.source ?? "local_postgres";
   const engine = inferContractBundleEngine(contract);
   const readUrlEnv = engine === "mysql" ? "SYNAPSOR_DATABASE_READ_URL" : "SYNAPSOR_DATABASE_READ_URL";
+  const hasProposals = contract.capabilities.some((capability) => capability.kind === "proposal");
+  const sourceConfig = {
+    engine,
+    read_url_env: readUrlEnv,
+    statement_timeout_ms: 3e3
+  };
+  if (hasProposals) sourceConfig.write_url_env = "SYNAPSOR_DATABASE_WRITE_URL";
   const runnerConfig = {
     version: 1,
-    mode: contract.capabilities.some((capability) => capability.kind === "proposal") ? "review" : "read_only",
+    mode: hasProposals ? "review" : "read_only",
     result_format: 2,
     storage: { sqlite_path: "./.synapsor/local.db" },
     contracts: ["./synapsor.contract.json"],
     sources: {
-      [firstSource]: {
-        engine,
-        read_url_env: readUrlEnv,
-        statement_timeout_ms: 3e3
-      }
+      [firstSource]: sourceConfig
     }
   };
   await fs3.mkdir(outDir, { recursive: true });
@@ -10064,11 +10252,9 @@ async function contractBundle(args) {
 `, "utf8");
   await fs3.writeFile(path3.join(outDir, ".env.example"), bundleEnvExample(contract, readUrlEnv, engine), "utf8");
   await fs3.writeFile(path3.join(outDir, "README.md"), bundleReadme(contract), "utf8");
-  await fs3.writeFile(path3.join(outDir, "mcp-client-examples", "generic-stdio.json"), `${JSON.stringify({
-    command: cliCommandName(),
-    args: ["mcp", "serve", "--config", "./synapsor.runner.json", "--store", "./.synapsor/local.db"]
-  }, null, 2)}
-`, "utf8");
+  for (const [name, content] of Object.entries(bundleMcpClientExamples())) {
+    await fs3.writeFile(path3.join(outDir, "mcp-client-examples", name), content, "utf8");
+  }
   process2.stdout.write(`created runner bundle: ${outDir}
 `);
   process2.stdout.write("No database URLs, write credentials, tokens, or customer rows were included.\n");
@@ -10087,6 +10273,7 @@ function bundleEnvExample(contract, readUrlEnv, engine) {
     "# Fill these locally. Do not commit real values.",
     `# Set ${readUrlEnv} to your read-only ${engine === "mysql" ? "MySQL" : "Postgres"} URL.`,
     `${readUrlEnv}=`,
+    ...contract.capabilities.some((capability) => capability.kind === "proposal") ? ["# Optional: separate least-privilege write URL for guarded direct UPDATE writeback.", "SYNAPSOR_DATABASE_WRITE_URL="] : [],
     `${tenantBinding?.key ?? "SYNAPSOR_TENANT_ID"}=acme`,
     `${principalBinding?.key ?? "SYNAPSOR_PRINCIPAL"}=local_operator`,
     ""
@@ -10113,12 +10300,70 @@ function bundleReadme(contract) {
     "```bash",
     "cp .env.example .env",
     "# edit .env, then export the values in your shell",
-    `${cliCommandName()} contract validate ./synapsor.contract.json`,
-    `${cliCommandName()} mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db`,
+    "set -a && . ./.env && set +a",
+    "npx -y -p @synapsor/runner synapsor-runner contract validate ./synapsor.contract.json",
+    "npx -y -p @synapsor/runner synapsor-runner config validate --config ./synapsor.runner.json",
+    "npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db",
+    "npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db",
+    "```",
+    "",
+    "Approval and apply remain outside the model-facing MCP catalog. Inspect local history with:",
+    "",
+    "```bash",
+    "npx -y -p @synapsor/runner synapsor-runner replay show latest --store ./.synapsor/local.db",
+    "npx -y -p @synapsor/runner synapsor-runner cloud push ./synapsor.contract.json --dry-run",
     "```",
     ""
   ].join("\n");
 }
+function bundleMcpClientExamples() {
+  const packageArgs = ["-y", "-p", "@synapsor/runner", "synapsor-runner"];
+  const stdioArgs = [...packageArgs, "mcp", "serve", "--config", "./synapsor.runner.json", "--store", "./.synapsor/local.db"];
+  const server = { command: "npx", args: stdioArgs };
+  const json = (value) => `${JSON.stringify(value, null, 2)}
+`;
+  return {
+    "claude-desktop.json": json({ mcpServers: { "synapsor-runner": server } }),
+    "cursor-project.mcp.json": json({ mcpServers: { "synapsor-runner": { type: "stdio", ...server } } }),
+    "cursor-global.mcp.json": json({
+      mcpServers: {
+        "synapsor-runner": {
+          type: "stdio",
+          command: "npx",
+          args: [...packageArgs, "mcp", "serve", "--config", "<absolute-path-to-bundle>/synapsor.runner.json", "--store", "<absolute-path-to-bundle>/.synapsor/local.db"]
+        }
+      }
+    }),
+    "generic-stdio.json": json({ name: "synapsor-runner", transport: "stdio", ...server }),
+    "generic-streamable-http.json": json({ name: "synapsor-runner", transport: "streamable-http", url: "http://127.0.0.1:8766/mcp" }),
+    "openai-agents-stdio.ts": `import { Agent, MCPServerStdio, run } from "@openai/agents";
+
+const synapsor = new MCPServerStdio({
+  name: "Synapsor Runner",
+  fullCommand: "npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db --alias-mode openai",
+});
+await synapsor.connect();
+try {
+  const agent = new Agent({ name: "Reviewed database agent", instructions: "Use only Synapsor business tools. Inspect evidence before proposing a change.", mcpServers: [synapsor] });
+  console.log((await run(agent, "Inspect the customer and propose a safe next action.")).finalOutput);
+} finally {
+  await synapsor.close();
+}
+`,
+    "openai-agents-streamable-http.ts": `import { Agent, MCPServerStreamableHttp, run } from "@openai/agents";
+
+// Start Runner separately with: synapsor-runner mcp serve --transport streamable-http --alias-mode openai --config ./synapsor.runner.json --store ./.synapsor/local.db
+const synapsor = new MCPServerStreamableHttp({ name: "Synapsor Runner", url: "http://127.0.0.1:8766/mcp" });
+await synapsor.connect();
+try {
+  const agent = new Agent({ name: "Reviewed database agent", instructions: "Use only Synapsor business tools. Inspect evidence before proposing a change.", mcpServers: [synapsor] });
+  console.log((await run(agent, "Inspect the customer and propose a safe next action.")).finalOutput);
+} finally {
+  await synapsor.close();
+}
+`
+  };
+}
 async function configValidate(args) {
   const configPath = optionalArg(args, "--config") ?? "synapsor.runner.json";
   const result = await validateConfigFile(configPath);
@@ -11949,7 +12194,7 @@ async function cloudPush(args) {
   if (!target2) throw new Error("cloud push requires <synapsor.contract.json>");
   const parsed = JSON.parse(await fs3.readFile(target2, "utf8"));
   const contract = normalizeContract(parsed);
-  const workspace = (optionalArg(args, "--workspace") ?? optionalArg(args, "--project") ?? process2.env.SYNAPSOR_WORKSPACE_ID ?? process2.env.SYNAPSOR_PROJECT_ID ?? "").trim();
+  const workspace = (optionalArg(args, "--workspace") ?? optionalArg(args, "--project") ?? process2.env.SYNAPSOR_CLOUD_WORKSPACE ?? process2.env.SYNAPSOR_WORKSPACE_ID ?? process2.env.SYNAPSOR_PROJECT_ID ?? "").trim();
   const name = (optionalArg(args, "--name") ?? contract.metadata?.name ?? "").trim();
   const description = (optionalArg(args, "--description") ?? contract.metadata?.description ?? "").trim();
   const idempotencyKey = optionalArg(args, "--idempotency-key");
@@ -11962,7 +12207,9 @@ async function cloudPush(args) {
     description,
     source: "runner",
     source_versions: {
-      "@synapsor/runner": process2.env.npm_package_version ?? "unknown"
+      "@synapsor/spec": package_default3.version,
+      "@synapsor/dsl": package_default2.version,
+      "@synapsor/runner": process2.env.npm_package_version ?? package_default.version
     },
     activate: args.includes("--activate"),
     idempotency_key: idempotencyKey,
@@ -11997,7 +12244,7 @@ async function cloudPush(args) {
   const apiUrl = (optionalArg(args, "--api-url") ?? process2.env.SYNAPSOR_CLOUD_BASE_URL ?? "").trim();
   const token = (optionalArg(args, "--token") ?? process2.env.SYNAPSOR_CLOUD_TOKEN ?? process2.env.SYNAPSOR_RUNNER_TOKEN ?? "").trim();
   if (!workspace) {
-    throw new Error("cloud push upload requires --workspace <project_id> or SYNAPSOR_WORKSPACE_ID/SYNAPSOR_PROJECT_ID.");
+    throw new Error("cloud push upload requires --workspace <project_id> or SYNAPSOR_CLOUD_WORKSPACE/SYNAPSOR_WORKSPACE_ID/SYNAPSOR_PROJECT_ID.");
   }
   if (!apiUrl || !token) {
     throw new Error("cloud push upload requires --api-url plus --token/SYNAPSOR_CLOUD_TOKEN. Use --dry-run for local validation without a network call.");
@@ -16622,8 +16869,9 @@ instead of being ignored.
   ${cmd} cloud push ./synapsor.contract.json --dry-run [--workspace <id>] [--name <registry-name>]
 
 cloud push validates and normalizes the contract locally, then prints the
-payload summary. Upload is intentionally not reported as successful until a
-real Cloud registry endpoint is wired.
+payload summary. With --dry-run it makes no network request. Without --dry-run
+it uploads to the authenticated Cloud registry and reports the stored contract,
+version, digest, and registry URL returned by the server.
 `,
     up: `Usage:
   ${cmd} up --config ./synapsor.runner.json --store ./.synapsor/local.db [--transport stdio|streamable-http]

package/docs/README.md

@@ -49,6 +49,8 @@ then read the concepts once the safety boundary is visible.
 
 - [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
   another stdio MCP client.
+- [MCP Client Configs](mcp-clients.md): complete Claude, Cursor, OpenAI Agents,
+  generic stdio, and Streamable HTTP templates.
 - `examples/claude-desktop-postgres/`: copy-paste Claude Desktop config for the
   Postgres billing fixture.
 - `examples/cursor-postgres/`: copy-paste Cursor config for the Postgres
@@ -96,6 +98,10 @@ then read the concepts once the safety boundary is visible.
   scope, database roles, receipt grants, local ledger backup, restart behavior,
   Docker/systemd shapes, TLS, and release-gate expectations.
 - [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
+- [Cloud Push](cloud-push.md): register a validated local contract in the
+  versioned Cloud registry.
+- [Runner Bundles](runner-bundles.md): download the same immutable contract and
+  its local MCP wiring from Cloud.
 - [Release Notes](release-notes.md): release history and behavior changes.
 - [Release Policy](release-policy.md): stable gates and publish verification.
 - [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is

package/docs/cloud-mode.md

@@ -6,6 +6,8 @@ guarded writeback, or replay.
 
 Cloud-linked mode is for teams that need a shared control plane:
 
+- versioned canonical contract registry and server-computed digests;
+- Cloud-to-local runner bundle downloads;
 - team approvals and RBAC;
 - hosted evidence/replay search;
 - runner registration and heartbeat;
@@ -17,6 +19,22 @@ The local runner still keeps database credentials in your environment. MCP
 client config snippets should contain command paths and runner arguments, not
 database URLs or write credentials.
 
+Push and retrieve the portable contract without moving database credentials
+into Cloud:
+
+```bash
+synapsor-runner cloud push ./synapsor.contract.json --dry-run
+synapsor-runner cloud push ./synapsor.contract.json \
+  --workspace "$SYNAPSOR_WORKSPACE_ID" \
+  --name support-plan-credit
+```
+
+See [Cloud Push](cloud-push.md) and [Runner Bundles](runner-bundles.md).
+
+Cloud registry storage preserves approval policies but does not, by itself,
+mean hosted policy enforcement is enabled. Local Runner enforcement and hosted
+Cloud approval enforcement are separate runtime boundaries.
+
 Run the local smoke for this mode with:
 
 ```bash

package/docs/cloud-push.md

@@ -0,0 +1,54 @@
+# Push A Contract To Synapsor Cloud
+
+Cloud push registers the same canonical contract that you validate and run
+locally. Cloud stores a normalized immutable version, computes its digest,
+records the actor, and makes the safety boundary visible in the workspace
+registry.
+
+## Preview Without A Network Call
+
+```bash
+synapsor-runner cloud push ./synapsor.contract.json --dry-run
+synapsor-runner cloud push ./synapsor.contract.json --dry-run --json
+```
+
+Dry-run validates and normalizes locally. It performs no network request.
+
+## Push
+
+```bash
+export SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai"
+export SYNAPSOR_CLOUD_TOKEN="<workspace-scoped-token>"
+export SYNAPSOR_WORKSPACE_ID="<workspace-id>"
+
+synapsor-runner cloud push ./synapsor.contract.json \
+  --name support-plan-credit
+```
+
+The response includes the contract id, immutable version id, server-computed
+digest, summary counts, status, and registry path. Identical normalized content
+is idempotent; changed content creates the next version.
+
+Tokens are sent in the authorization header and are never part of the contract.
+Database URLs, passwords, private keys, and model-controlled tenant bindings
+are rejected by server-side validation.
+
+`SYNAPSOR_CLOUD_WORKSPACE` is accepted as an alias for
+`SYNAPSOR_WORKSPACE_ID`. Explicit `--workspace` wins over environment values.
+
+Cloud push fails before upload when local validation fails. HTTP failures are
+reported distinctly for invalid/expired tokens (`401`), insufficient workspace
+permission (`403`), missing workspace/API paths (`404`), registry conflicts
+(`409`), server validation (`422`), and Cloud/network failures. Error output
+does not echo the bearer token.
+
+## Cloud To Local
+
+Open **Contract registry** in the workspace, choose a version, and download its
+runner bundle. The ZIP contains the normalized contract, local runner wiring,
+placeholder environment file, README, and MCP client examples. It contains no
+live credentials or table rows.
+
+Cloud currently preserves approval policy definitions in the contract and
+bundle. Hosted approval-policy enforcement remains a separate Cloud feature;
+do not infer it from registry storage alone.

package/docs/current-scope.md

@@ -2,7 +2,7 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current alpha scope:
+Current `0.1.x` scope:
 
 - local semantic MCP tools for Postgres/MySQL-backed business actions;
 - schema inspection and guided config generation;

package/docs/mcp-clients.md

@@ -0,0 +1,123 @@
+# MCP Client Configs
+
+Synapsor Runner exposes reviewed semantic tools over standard MCP. The model
+receives inspect/propose capabilities; it does not receive raw SQL, database
+credentials, approval commands, or apply commands.
+
+The complete copy-paste templates live in:
+
+- [`examples/support-plan-credit/mcp-client-examples/`](../examples/support-plan-credit/mcp-client-examples/)
+- every local `synapsor-runner contract bundle` output;
+- every downloadable Synapsor Cloud runner bundle.
+
+Before connecting a client, validate the local boundary:
+
+```bash
+synapsor-runner config validate --config ./synapsor.runner.json
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Set database and trusted-context values in the environment that launches the
+MCP process. Keep real URLs and tokens in your shell or secret manager, not in
+the checked-in client JSON.
+
+## Stdio
+
+Use stdio for Claude Desktop, Cursor, and other local MCP clients:
+
+```json
+{
+  "command": "npx",
+  "args": [
+    "-y", "-p", "@synapsor/runner", "synapsor-runner",
+    "mcp", "serve", "--config", "./synapsor.runner.json",
+    "--store", "./.synapsor/local.db"
+  ]
+}
+```
+
+Relative paths are resolved from the MCP client's working directory. Use the
+project template when the client starts in your repository; replace the marked
+bundle path in the global template when it does not.
+
+### Claude Desktop
+
+1. Open Claude Desktop settings and choose the developer option to edit its MCP
+   configuration.
+2. Merge `claude-desktop.json` into the existing `mcpServers` object.
+3. Replace the marked working directory or use absolute paths when Claude does
+   not start in the bundle directory.
+4. Restart Claude Desktop completely, then confirm the two semantic tools are
+   listed.
+
+Claude Desktop launched from a graphical session may not inherit your terminal
+environment. Supply the required env values through the OS process environment
+or a local secret-manager wrapper; do not paste production credentials into a
+repository file.
+
+### Cursor
+
+For one repository, place the project template at `.cursor/mcp.json`. For a
+global setup, merge `cursor-global.mcp.json` through Cursor's MCP settings and
+replace every `<absolute-path-to-bundle>` marker. Restart the MCP server from
+Cursor settings after editing.
+
+The model-facing list should contain only the contract's inspect/propose tools.
+If Cursor reports a missing config or store, use absolute paths and rerun
+`tools preview` from the same working directory.
+
+### OpenAI Agents SDK
+
+Install the SDK in your agent project and run either TypeScript template:
+
+```bash
+npm install @openai/agents
+```
+
+OpenAI function names cannot contain dots. The stdio template therefore starts
+Runner with `--alias-mode openai`; model-visible names use `__`, while result
+metadata preserves the canonical dotted Synapsor capability name.
+
+## Streamable HTTP
+
+```bash
+synapsor-runner mcp serve \
+  --transport streamable-http \
+  --alias-mode openai \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Connect a standard Streamable HTTP MCP client to
+`http://127.0.0.1:8766/mcp`. Keep it on loopback for local development. For a
+network deployment, terminate TLS, require authentication, restrict network
+access, and follow the [production guide](production.md).
+
+Use `--alias-mode openai` for the OpenAI Agents SDK. Omit it for clients that
+accept canonical dotted names, or use `--alias-mode both` only during a planned
+migration where duplicate canonical/alias tools are acceptable.
+
+## Verify The Boundary
+
+```bash
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+The preview must list semantic capabilities and must not list `execute_sql`,
+approval/apply tools, database URLs, write credentials, or model-controlled
+tenant authority.
+
+## Troubleshooting
+
+- `ENOENT` or missing config: use absolute config/store paths.
+- empty tool list: run `contract validate`, then `tools preview` against the
+  exact config used by the client.
+- database connection failure: verify the client process received the read URL
+  and trusted tenant/principal env values.
+- OpenAI rejects a dotted name: start Runner with `--alias-mode openai`.
+- HTTP `initialize` failure: use `mcp serve --transport streamable-http`, not
+  the legacy `serve-http` JSON-RPC bridge.
+- no ready message: inspect client stderr; Runner keeps stdout protocol-clean.

package/docs/release-notes.md

@@ -12,6 +12,36 @@ for the Synapsor Cloud CLI.
 
 ## Unreleased
 
+Prepared package versions: `@synapsor/spec@0.1.4`,
+`@synapsor/dsl@0.1.4`, and `@synapsor/runner@0.1.11`. Nothing in this section
+is published until the manual release commands are run.
+
+### Cloud Adoption Loop
+
+- Adds complete Claude, Cursor, OpenAI Agents SDK, and generic MCP templates to
+  local and Cloud-generated Runner bundles.
+- Adds a flagship adoption verifier and a real local Cloud registry/version/ZIP
+  bundle round trip.
+- Expands the `support-plan-credit` walkthrough from no-database validation to
+  Docker-backed policy tiers, MCP setup, Cloud push, bundle download, replay,
+  cleanup, and troubleshooting.
+- Supports `SYNAPSOR_CLOUD_WORKSPACE` and verifies distinct 401/403/404/409/422,
+  server, and network errors without exposing tokens.
+- Clarifies that Cloud registry/versioning is beta-ready while managed runners,
+  SAML/SCIM, hosted policy enforcement, legal hold, and enterprise SLA are not
+  part of this release.
+- Corrects `cloud push --help` to describe the real authenticated registry
+  upload and network-free dry-run behavior.
+
+## 0.1.10
+
+### Policy Auto-Approval
+
+- Adds portable approval-policy references and threshold rules.
+- Adds DSL `AUTO APPROVE WHEN field <= integer` and the three-tier
+  `support-plan-credit` example: policy approval, operator review, and bound
+  rejection.
+
 ## 0.1.9
 
 ### CLI Hygiene

package/docs/runner-bundles.md

@@ -0,0 +1,59 @@
+# Runner Bundles
+
+A runner bundle is the portable Cloud-to-local side of the canonical loop:
+
+```text
+local DSL/spec -> cloud push -> immutable registry version -> runner bundle -> local Runner
+```
+
+Every bundle contains:
+
+```text
+synapsor.contract.json
+synapsor.runner.json
+.env.example
+README.md
+mcp-client-examples/
+  claude-desktop.json
+  cursor-project.mcp.json
+  cursor-global.mcp.json
+  openai-agents-stdio.ts
+  openai-agents-streamable-http.ts
+  generic-stdio.json
+  generic-streamable-http.json
+```
+
+It never contains database passwords, write credentials, live API tokens,
+private keys, customer rows, or machine-specific local paths.
+
+## Create Locally
+
+```bash
+synapsor-runner contract bundle ./synapsor.contract.json \
+  --out ./synapsor-runner-bundle
+```
+
+## Run A Downloaded Bundle
+
+```bash
+cd ./synapsor-runner-bundle
+cp .env.example .env
+set -a && . ./.env && set +a
+
+npx -y -p @synapsor/runner synapsor-runner contract validate ./synapsor.contract.json
+npx -y -p @synapsor/runner synapsor-runner config validate --config ./synapsor.runner.json
+npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+For the OpenAI Agents SDK, use the included TypeScript examples. Their stdio
+command enables `--alias-mode openai`; the Streamable HTTP example includes the
+matching server command. Claude, Cursor, and generic templates use canonical
+dotted capability names.
+
+Approval and writeback remain outside the model-facing MCP tool surface. Use
+`proposals`, `apply`, `receipts`, and `replay` from a trusted operator shell.
+
+The bundle's `.env.example` contains names and placeholders only. Fill it for a
+local or staging source, source it into the shell or process that launches your
+MCP client, and keep the resulting `.env` out of source control.

package/examples/support-plan-credit/.env.example

@@ -0,0 +1,10 @@
+# Disposable Docker example credentials only. Do not reuse in staging or production.
+PLAN_CREDIT_POSTGRES_READ_URL=postgresql://synapsor_reader:synapsor_reader_password@127.0.0.1:55438/synapsor_runner_plan_credit
+PLAN_CREDIT_POSTGRES_WRITE_URL=postgresql://synapsor_writer:synapsor_writer_password@127.0.0.1:55438/synapsor_runner_plan_credit
+SYNAPSOR_TENANT_ID=acme
+SYNAPSOR_PRINCIPAL=local_support_agent
+
+# Optional Cloud registry upload. Keep real values outside git.
+SYNAPSOR_CLOUD_BASE_URL=
+SYNAPSOR_CLOUD_TOKEN=
+SYNAPSOR_WORKSPACE_ID=

package/examples/support-plan-credit/README.md

@@ -12,15 +12,46 @@ This example shows three enforcement tiers on one support action:
 - Node 22.5+
 - Port `55438` available
 
+Install the stable CLI once for the commands below:
+
+```bash
+npm install --global @synapsor/runner
+synapsor-runner --version
+```
+
+When working from this source checkout, use `corepack pnpm runner` in place of
+`synapsor-runner`.
+
+## No-Database Check
+
+Validate the authored boundary before starting Docker:
+
+```bash
+synapsor-runner dsl compile examples/support-plan-credit/contract.synapsor \
+  --out /tmp/support-plan-credit.contract.json \
+  --strict
+synapsor-runner contract validate /tmp/support-plan-credit.contract.json
+synapsor-runner config validate \
+  --config examples/support-plan-credit/synapsor.runner.json
+synapsor-runner cloud push /tmp/support-plan-credit.contract.json \
+  --dry-run \
+  --workspace local-preview \
+  --name support-plan-credit
+```
+
+This compiles, validates, and previews the Cloud payload without opening a
+network connection or connecting to a database. From a source checkout,
+`corepack pnpm verify:adoption` runs this boundary check plus the no-database
+quick demo and MCP config validation.
+
 ## Quick Start
 
 ```bash
 docker compose -f examples/support-plan-credit/docker-compose.yml up -d
 
-export PLAN_CREDIT_POSTGRES_READ_URL="postgresql://synapsor_reader:synapsor_reader_password@localhost:55438/synapsor_runner_plan_credit"
-export PLAN_CREDIT_POSTGRES_WRITE_URL="postgresql://synapsor_writer:synapsor_writer_password@localhost:55438/synapsor_runner_plan_credit"
-export SYNAPSOR_TENANT_ID="acme"
-export SYNAPSOR_PRINCIPAL="local_support_agent"
+set -a
+. examples/support-plan-credit/.env.example
+set +a
 
 synapsor-runner tools preview \
   --config examples/support-plan-credit/synapsor.runner.json \
@@ -32,6 +63,9 @@ synapsor-runner mcp serve \
   --store ./tmp/support-plan-credit/local.db
 ```
 
+The checked-in `.env.example` contains disposable localhost Docker credentials
+only. Never reuse them for staging or production.
+
 ## Walkthrough
 
 Inspect the customer first:
@@ -98,6 +132,13 @@ synapsor-runner apply latest --config examples/support-plan-credit/synapsor.runn
 The live smoke test mutates `updated_at` before apply and proves stale proposals
 return `VERSION_CONFLICT` without changing the source row.
 
+Run the complete Docker-backed scenario, including all three policy tiers and
+the stale-row conflict:
+
+```bash
+corepack pnpm test:live-apply
+```
+
 ## What The Agent Never Sees
 
 The contract keeps these fields out:
@@ -118,6 +159,37 @@ auto-approval: enabled
 No raw SQL, approval tools, commit tools, write credentials, or model-controlled
 tenant authority are exposed to MCP.
 
+Representative outputs are checked in under [`expected-output/`](expected-output/)
+so you can compare the tool boundary, proposal, receipt, replay, and Cloud push
+shape without guessing which state should change.
+
+## Connect An MCP Client
+
+Copy the matching template from [`mcp-client-examples/`](mcp-client-examples/):
+
+- Claude Desktop: `claude-desktop.json`
+- Cursor project/global: `cursor-project.mcp.json`, `cursor-global.mcp.json`
+- OpenAI Agents SDK: stdio and Streamable HTTP TypeScript examples
+- generic MCP: stdio and Streamable HTTP JSON examples
+
+For Streamable HTTP, run:
+
+```bash
+synapsor-runner mcp serve \
+  --transport streamable-http \
+  --alias-mode openai \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
+The OpenAI client receives `support__inspect_customer` and
+`support__propose_plan_credit`; Runner preserves the dotted canonical names in
+tool metadata and results. For Claude, Cursor, or generic MCP clients, omit
+`--alias-mode openai` to expose `support.inspect_customer` and
+`support.propose_plan_credit`. Approval and apply remain outside MCP.
+
 ## How The Policy Is Governed
 
 The auto-approval policy lives in `contract.synapsor`:
@@ -153,11 +225,11 @@ synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json -
 Real push uses your Cloud env vars:
 
 ```bash
-export SYNAPSOR_CONTROL_PLANE_URL="https://api.synapsor.ai"
-export SYNAPSOR_RUNNER_TOKEN="syn_wbr_..."
+export SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai"
+export SYNAPSOR_CLOUD_TOKEN="<workspace-scoped-token>"
+export SYNAPSOR_WORKSPACE_ID="<workspace_id>"
 
 synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json \
-  --workspace <workspace_id> \
   --name support-plan-credit
 ```
 
@@ -166,11 +238,36 @@ placeholder env names:
 
 ```bash
 curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
-  "$SYNAPSOR_CONTROL_PLANE_URL/v1/control/projects/<workspace_id>/agent-contracts/support-plan-credit/versions/latest"
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>"
 
 curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
-  "$SYNAPSOR_CONTROL_PLANE_URL/v1/control/projects/<workspace_id>/agent-contracts/support-plan-credit/runner-bundle" \
-  -o support-plan-credit-runner-bundle.json
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>/runner-bundle?download=1" \
+  -o support-plan-credit-runner-bundle.zip
 ```
 
+The push response supplies `<contract_id>` and `<version_id>`. The Cloud
+workspace also exposes the same download from **Contract registry**.
+
 No Cloud account is needed to run this local example.
+
+## Clean Up
+
+```bash
+docker compose -f examples/support-plan-credit/docker-compose.yml down -v
+rm -rf ./tmp/support-plan-credit
+```
+
+## Troubleshooting
+
+- `synapsor-runner: command not found`: install `@synapsor/runner` globally or
+  use `corepack pnpm runner` from this repository.
+- port `55438` is busy: stop the previous example container or change the
+  published port and both URLs in `.env.example` together.
+- missing table/connection: wait for the Docker health check, then rerun the
+  command from the repository root with the `.env.example` values exported.
+- OpenAI rejects dotted tool names: start the MCP server with
+  `--alias-mode openai` and use the OpenAI template.
+- proposal stays pending: `$100` intentionally requires
+  `proposals approve`; only the `$25` tier is policy-approved.
+- apply reports a conflict: the row changed after the proposal read. Inspect
+  the new row, create a fresh proposal, and do not bypass the version guard.

package/examples/support-plan-credit/expected-output/cloud-push-response.json

@@ -0,0 +1,9 @@
+{
+  "ok": true,
+  "contract_id": "act_support_plan_credit_example",
+  "contract_version_id": "act_support_plan_credit_example_v1",
+  "version_number": 1,
+  "status": "draft",
+  "digest": "sha256:<server-computed-digest>",
+  "registry_url": "/workspace/contracts?contract=<contract_id>"
+}

package/examples/support-plan-credit/expected-output/proposal-created.json

@@ -0,0 +1,23 @@
+{
+  "proposal_id": "wrp_example_low_risk_credit",
+  "capability": "support.propose_plan_credit",
+  "status": "approved",
+  "approval_actor": "policy:support_propose_plan_credit_auto_approval",
+  "target": {
+    "table": "customers",
+    "id": "CUS-3001",
+    "tenant_id": "acme"
+  },
+  "change_set": {
+    "plan_credit_cents": {
+      "before": 0,
+      "after": 2500
+    },
+    "credit_reason": {
+      "before": null,
+      "after": "SLA outage ticket SUP-481"
+    }
+  },
+  "source_database_changed": false,
+  "evidence_handle": "evidence://local/example-plan-credit"
+}

package/examples/support-plan-credit/expected-output/receipt.json

@@ -0,0 +1,13 @@
+{
+  "receipt_id": "rct_example_plan_credit",
+  "proposal_id": "wrp_example_low_risk_credit",
+  "status": "applied",
+  "rows_affected": 1,
+  "guards": {
+    "tenant": "passed",
+    "primary_key": "passed",
+    "allowed_columns": "passed",
+    "expected_version": "passed",
+    "idempotency": "passed"
+  }
+}

package/examples/support-plan-credit/expected-output/replay-summary.json

@@ -0,0 +1,13 @@
+{
+  "proposal_id": "wrp_example_low_risk_credit",
+  "events": [
+    "scoped_read",
+    "evidence_saved",
+    "proposal_created",
+    "policy_approved",
+    "guarded_writeback_applied",
+    "receipt_recorded"
+  ],
+  "source_database_changed_before_approval": false,
+  "final_status": "applied"
+}

package/examples/support-plan-credit/expected-output/tools-preview.txt

@@ -0,0 +1,15 @@
+Synapsor tools preview: ok
+
+Exposed to MCP:
+  - support.inspect_customer
+  - support.propose_plan_credit
+
+Not exposed to MCP:
+  - execute_sql / raw query tools
+  - approval tools
+  - commit/apply tools
+  - database URLs
+  - write credentials
+  - model-controlled tenant authority
+
+auto-approval: enabled

package/examples/support-plan-credit/mcp-client-examples/claude-desktop.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@synapsor/runner",
+        "synapsor-runner",
+        "mcp",
+        "serve",
+        "--config",
+        "examples/support-plan-credit/synapsor.runner.json",
+        "--store",
+        "./tmp/support-plan-credit/local.db"
+      ],
+      "cwd": "<absolute-path-to-Synapsor-Runner>"
+    }
+  }
+}

package/examples/support-plan-credit/mcp-client-examples/cursor-global.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@synapsor/runner",
+        "synapsor-runner",
+        "mcp",
+        "serve",
+        "--config",
+        "<absolute-path-to-Synapsor-Runner>/examples/support-plan-credit/synapsor.runner.json",
+        "--store",
+        "<absolute-path-to-Synapsor-Runner>/tmp/support-plan-credit/local.db"
+      ]
+    }
+  }
+}

package/examples/support-plan-credit/mcp-client-examples/cursor-project.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "synapsor-runner": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@synapsor/runner",
+        "synapsor-runner",
+        "mcp",
+        "serve",
+        "--config",
+        "examples/support-plan-credit/synapsor.runner.json",
+        "--store",
+        "./tmp/support-plan-credit/local.db"
+      ]
+    }
+  }
+}

package/examples/support-plan-credit/mcp-client-examples/generic-stdio.json

@@ -0,0 +1,17 @@
+{
+  "name": "synapsor-runner",
+  "transport": "stdio",
+  "command": "npx",
+  "args": [
+    "-y",
+    "-p",
+    "@synapsor/runner",
+    "synapsor-runner",
+    "mcp",
+    "serve",
+    "--config",
+    "examples/support-plan-credit/synapsor.runner.json",
+    "--store",
+    "./tmp/support-plan-credit/local.db"
+  ]
+}

package/examples/support-plan-credit/mcp-client-examples/generic-streamable-http.json

@@ -0,0 +1,5 @@
+{
+  "name": "synapsor-runner",
+  "transport": "streamable-http",
+  "url": "http://127.0.0.1:8766/mcp"
+}

package/examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts

@@ -0,0 +1,19 @@
+import { Agent, MCPServerStdio, run } from "@openai/agents";
+
+const synapsor = new MCPServerStdio({
+  name: "Synapsor Runner",
+  fullCommand: "npx -y -p @synapsor/runner synapsor-runner mcp serve --config examples/support-plan-credit/synapsor.runner.json --store ./tmp/support-plan-credit/local.db --alias-mode openai",
+});
+
+await synapsor.connect();
+try {
+  const agent = new Agent({
+    name: "Support operations agent",
+    instructions: "Use only Synapsor business tools. Inspect evidence before proposing a plan credit.",
+    mcpServers: [synapsor],
+  });
+  const result = await run(agent, "Inspect customer CUS-3001 and propose a $25 plan credit for SLA outage ticket SUP-481.");
+  console.log(result.finalOutput);
+} finally {
+  await synapsor.close();
+}

package/examples/support-plan-credit/mcp-client-examples/openai-agents-streamable-http.ts

@@ -0,0 +1,20 @@
+import { Agent, MCPServerStreamableHttp, run } from "@openai/agents";
+
+// Start Runner with --alias-mode openai so model-visible tool names are valid OpenAI function names.
+const synapsor = new MCPServerStreamableHttp({
+  name: "Synapsor Runner",
+  url: "http://127.0.0.1:8766/mcp",
+});
+
+await synapsor.connect();
+try {
+  const agent = new Agent({
+    name: "Support operations agent",
+    instructions: "Use only Synapsor business tools. Inspect evidence before proposing a plan credit.",
+    mcpServers: [synapsor],
+  });
+  const result = await run(agent, "Inspect customer CUS-3001 and propose a $25 plan credit for SLA outage ticket SUP-481.");
+  console.log(result.finalOutput);
+} finally {
+  await synapsor.close();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapsor/runner",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Stop giving AI agents execute_sql; expose reviewed Postgres/MySQL MCP actions with proposals, approval, writeback, and replay.",
   "license": "Apache-2.0",
   "type": "module",