@synapsor/runner 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+### Runner Version Invocation
+
+- Stages `@synapsor/runner@0.1.12` without changing or republishing
+  `@synapsor/spec@0.1.4` or `@synapsor/dsl@0.1.4`.
+- Keeps `--version`, `-v`, and `version` stable when an npm/npx wrapper forwards
+  a duplicated `synapsor-runner` executable token.
+- Reads the Runner version from bundled package metadata instead of the
+  invoking project's ambient `npm_package_version` value.
+- Adds source-wrapper and installed-tarball checks for every supported version
+  form and the duplicated-token regression shape.
+
+## 0.1.11
+
+### Cloud Adoption Loop
+
+- Publishes `@synapsor/spec@0.1.4`, `@synapsor/dsl@0.1.4`, and
+  `@synapsor/runner@0.1.11`.
+- 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;AAqED,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.12",
+  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"]);
@@ -8752,7 +8937,7 @@ var referenceDemoEnv = {
   SYNAPSOR_RUNNER_TOKEN: "syn_wbr_demo_local"
 };
 async function main(argv) {
-  const [command, ...rest] = argv;
+  const [command, ...rest] = normalizeCliArgv(argv);
   if (!command || command === "--help" || command === "-h") {
     usage([]);
     return 0;
@@ -8818,6 +9003,11 @@ ${cliCommandName()} --help
 `);
   return 2;
 }
+function normalizeCliArgv(argv) {
+  const [first, ...rest] = argv;
+  if (first === "synapsor-runner" || first === "synapsor") return rest;
+  return argv;
+}
 async function init(args) {
   const answersPath = optionalArg(args, "--answers");
   if (answersPath) {
@@ -10042,18 +10232,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 +10257,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 +10278,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 +10305,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 +12199,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 +12212,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 +12249,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.");
@@ -16535,7 +16787,9 @@ function cliCommandName() {
   return "synapsor-runner";
 }
 async function runnerPackageVersion() {
-  if (process2.env.npm_package_version) return process2.env.npm_package_version;
+  if (typeof package_default.version === "string" && package_default.version.trim()) {
+    return package_default.version.trim();
+  }
   const packageUrl = new URL("../package.json", import.meta.url);
   try {
     const parsed = JSON.parse(await fs3.readFile(packageUrl, "utf8"));
@@ -16622,8 +16876,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