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

package/docs/local-mode.md

@@ -6,17 +6,26 @@ Command model:
 
 - `./scripts/demo-docker.sh` runs the no-install Docker demo.
 - `synapsor <command>` is the public CLI surface.
-- From a source checkout, use `./bin/synapsor <command>` if the global binary is
+- From a source checkout, use `./bin/synapsor-runner <command>` if the global binary is
   not linked yet.
 
+`synapsor-runner demo --quick` creates a fixture ledger for learning and CLI
+verification. In a terminal it walks through the safety model step by step; in
+CI or piped output it prints a short summary and exits without waiting for
+Enter. It does not read or write external Postgres/MySQL. Local mode with
+`synapsor-runner mcp serve`, `synapsor-runner demo`, or an own generated config is the real
+Postgres/MySQL path. Use `synapsor-runner demo inspect` to print the follow-up
+commands for the quick-demo fixture.
+
 Current local-mode foundation:
 
 - strict JSON capability config validation in `packages/config`;
 - local SQLite proposal/event/evidence/query-audit/writeback/replay store in `packages/proposal-store`;
 - local proposal review CLI in `apps/runner`;
-- local localhost proposal review UI through `synapsor ui`;
-- static MCP database risk review with `synapsor audit`;
+- local localhost proposal review UI through `synapsor-runner ui`;
+- static MCP database risk review with `synapsor-runner audit`;
 - local stdio MCP server with semantic read/proposal tools;
+- authenticated HTTP MCP server for app/server agents;
 - MCP resource reads for `synapsor://proposals/*`, `synapsor://evidence/*`, and `synapsor://replay/*`;
 - local approved proposal to `synapsor.writeback-job.v1` job generation;
 - guarded Postgres/MySQL writeback adapters for approved structured jobs.
@@ -29,22 +38,18 @@ engine requirement and the CLI exits early with a clear message on older Node
 versions. The Docker-backed demo remains the recommended path when you do not
 want to change your host Node version.
 
-Commands in this page that use local ledger search/export or `synapsor store`
-require this checkout or package version `0.1.0-alpha.4` or newer while npm
-`@alpha` still points to an older alpha.
-
 ## Initialize a config
 
 Create a starter config without putting credentials in the file:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init --engine postgres --mode review
+npx -y -p @synapsor/runner@alpha synapsor-runner init --engine postgres --mode review
 ```
 
 For MySQL:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init --engine mysql --mode review --output synapsor.mysql.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner init --engine mysql --mode review --output synapsor.mysql.runner.json
 ```
 
 The generated config uses environment-variable names for read/write URLs and trusted context. Edit the table, column, and capability names before serving tools.
@@ -57,14 +62,39 @@ persisted into proposals, evidence, query audit, runner state, or replay.
 For a reviewed own-database setup generated from explicit selections, use:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init --spec onboarding-selection.json --non-interactive
-npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner init --spec onboarding-selection.json --non-interactive
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
 ```
 
 `doctor --config` checks config validation, required environment variables,
 read/write credential separation, metadata visibility for configured targets,
 and the semantic MCP tool boundary without printing credential values.
 
+## Stdio Vs HTTP MCP
+
+Use stdio for local MCP clients that launch Synapsor Runner:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+Use HTTP when your app/server agent connects to a long-running Runner process:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+HTTP defaults to `127.0.0.1:8765`, requires bearer auth by default, and should
+run behind private networking/TLS before production-like exposure. Details:
+[HTTP MCP](http-mcp.md).
+
 ## Local safety modes
 
 The local runner modes are intentionally narrow:
@@ -95,19 +125,19 @@ If neither is set, the CLI uses:
 List proposals:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals list --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./.synapsor/local.db
 ```
 
 Show a proposal:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
 ```
 
 Approve:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals approve wrp_123 \
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve wrp_123 \
   --store ./.synapsor/local.db \
   --actor local_reviewer \
   --yes
@@ -118,7 +148,7 @@ Before approval, the CLI prints the reviewer-critical proposal details: trusted
 Create a guarded writeback job from an approved proposal:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals writeback-job wrp_123 \
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job wrp_123 \
   --store ./.synapsor/local.db \
   --project local \
   --runner local_runner \
@@ -130,7 +160,7 @@ The generated job uses the public `synapsor.writeback-job.v1` protocol and can b
 ```bash
 SYNAPSOR_ENGINE=postgres \
 SYNAPSOR_DATABASE_URL="postgresql://writer:<password>@localhost:5432/app" \
-npx -y -p @synapsor/runner@alpha synapsor apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 Passing `--store` records the terminal `synapsor.execution-receipt.v1` locally. Replay then links the proposal, approval, writeback job, applied/conflict/failed receipt, evidence, and query audit.
@@ -138,7 +168,7 @@ Passing `--store` records the terminal `synapsor.execution-receipt.v1` locally.
 Reject:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals reject wrp_123 \
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals reject wrp_123 \
   --store ./.synapsor/local.db \
   --reason "policy evidence is incomplete" \
   --yes
@@ -155,7 +185,7 @@ Shadow-mode proposals are inspectable through `proposals show` and `replay show`
 Start a localhost-only review UI:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor ui --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner ui --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 The UI shows setup summary, semantic tools, proposal states, exact diffs,
@@ -171,50 +201,56 @@ tools, MCP commit tools, or controls that widen configured tables/columns.
 Show replay:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor replay show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor replay show --proposal wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor replay show --replay replay_wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor replay show --evidence ev_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay show --proposal wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay show --replay replay_wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner replay show --evidence ev_123 --store ./.synapsor/local.db
 ```
 
 Export replay:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor replay export wrp_123 \
+npx -y -p @synapsor/runner@alpha synapsor-runner replay export wrp_123 \
   --store ./.synapsor/local.db \
   --output replay.json
 
-npx -y -p @synapsor/runner@alpha synapsor replay export --proposal wrp_123 \
+npx -y -p @synapsor/runner@alpha synapsor-runner replay export --proposal wrp_123 \
   --format markdown \
   --store ./.synapsor/local.db \
   --output replay.md
 ```
 
 Replay records include proposal metadata, before/after diff, events, writeback receipts, evidence summaries, and query audit rows currently stored for the proposal.
+Human output is concise by default. Use `--details` for reviewer metadata or
+`--json` for complete machine-readable records.
 
 ## Local evidence, query audit, and receipts
 
 The local SQLite store is also searchable without relying on `latest`:
 
 ```bash
-synapsor activity search \
+synapsor-runner activity search \
   --tenant acme \
   --object invoice:INV-3001 \
   --store ./.synapsor/local.db
 
-synapsor evidence list \
+synapsor-runner evidence list \
   --tenant acme \
   --capability billing.inspect_invoice \
   --source app_postgres \
   --table invoices \
   --store ./.synapsor/local.db
 
-synapsor evidence show ev_123 --store ./.synapsor/local.db
-synapsor query-audit list --evidence ev_123 --store ./.synapsor/local.db
-synapsor receipts list --proposal wrp_123 --store ./.synapsor/local.db
-synapsor receipts show <receipt_id> --store ./.synapsor/local.db
+synapsor-runner evidence show ev_123 --store ./.synapsor/local.db
+synapsor-runner query-audit list --evidence ev_123 --store ./.synapsor/local.db
+synapsor-runner receipts list --proposal wrp_123 --store ./.synapsor/local.db
+synapsor-runner receipts show <receipt_id> --store ./.synapsor/local.db
 ```
 
+Default inspection output is intentionally short. Add `--details` when you need
+target URIs, primary keys, proposal hash/version, conflict guards, query
+fingerprints, event timestamps, or receipt internals.
+
 Read-only MCP tools record evidence bundles and query-audit rows and return an
 evidence handle. Use `evidence show`, `evidence list`, and `query-audit list`
 to inspect those captured rows and fingerprints later without rerunning the
@@ -230,10 +266,10 @@ The local ledger is a developer/staging SQLite file. You can inspect, compact,
 or prune it without touching your source Postgres/MySQL database:
 
 ```bash
-synapsor store stats --store ./.synapsor/local.db
-synapsor store vacuum --store ./.synapsor/local.db
-synapsor store prune --store ./.synapsor/local.db --older-than 30d --dry-run
-synapsor store prune --store ./.synapsor/local.db --older-than 30d --yes
+synapsor-runner store stats --store ./.synapsor/local.db
+synapsor-runner store vacuum --store ./.synapsor/local.db
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
+synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --yes
 ```
 
 `store prune` defaults to dry-run. Use `--yes` only after reviewing the row
@@ -286,7 +322,7 @@ For CI or direct verification, use:
 corepack pnpm test:mcp-local
 ```
 
-It launches the official MCP stdio client transport against `synapsor mcp serve`, exercises the Postgres billing, Postgres support, and MySQL orders examples, checks that source rows are unchanged before approval, approves locally, generates versioned writeback jobs, applies them, retries idempotently, and then proves stale-row conflict:
+It launches the official MCP stdio client transport against `synapsor-runner mcp serve`, exercises the Postgres billing, Postgres support, and MySQL orders examples, checks that source rows are unchanged before approval, approves locally, generates versioned writeback jobs, applies them, retries idempotently, and then proves stale-row conflict:
 
 ```text
 The business state changed after the agent saw it, so Synapsor refused to commit.

package/docs/mcp-audit.md

@@ -1,11 +1,11 @@
 # MCP database risk review
 
-`npx -y -p @synapsor/runner@alpha synapsor audit <target>` performs a
+`npx -y -p @synapsor/runner@alpha synapsor-runner audit <target>` performs a
 static MCP database risk review over an exported tool manifest, a remote MCP
 `tools/list` endpoint, or a stdio MCP server. The `mcp audit` subcommand is also
 available for users who look for the command under the MCP namespace.
 
-From a source checkout, use `./bin/synapsor ...` if the global binary is not
+From a source checkout, use `./bin/synapsor-runner ...` if the global binary is not
 linked yet.
 
 It does not call business tools. It only inspects names, descriptions, input schemas, output schemas, annotations, and examples when those are present.
@@ -23,13 +23,9 @@ MCP annotations are treated as hints, not enforcement.
 Built-in database MCP risk example:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp
+npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp
 ```
 
-Markdown output requires this checkout or package version `0.1.0-alpha.4` or
-newer. Check `npm view @synapsor/runner@alpha version` before promoting npm
-snippets publicly.
-
 This bundled example does not require a source checkout or local examples file.
 It audits a deliberately risky database MCP shape with `execute_sql`,
 `run_query`, model-callable approval/update/delete tools, arbitrary
@@ -38,45 +34,45 @@ table/column inputs, and model-controlled tenant/principal fields.
 Human-readable output:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit ./tools-list.json
+npx -y -p @synapsor/runner@alpha synapsor-runner audit ./tools-list.json
 ```
 
 Remote `tools/list` endpoint with a bearer token kept in the environment:
 
 ```bash
 SYNAPSOR_MCP_AUDIT_BEARER="..." \
-npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --format json
+npx -y -p @synapsor/runner@alpha synapsor-runner audit https://mcp.example.com --format json
 ```
 
 Remote endpoint with a custom bearer-token environment variable:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
+npx -y -p @synapsor/runner@alpha synapsor-runner audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
 ```
 
 Stdio MCP server:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit 'stdio:node ./server.mjs' --timeout-ms 5000
+npx -y -p @synapsor/runner@alpha synapsor-runner audit 'stdio:node ./server.mjs' --timeout-ms 5000
 ```
 
 JSON output:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit ./tools-list.json --format json
+npx -y -p @synapsor/runner@alpha synapsor-runner audit ./tools-list.json --format json
 ```
 
 Markdown output for issues, PRs, or security review notes:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit --example dangerous-db-mcp --format markdown
+npx -y -p @synapsor/runner@alpha synapsor-runner audit --example dangerous-db-mcp --format markdown
 ```
 
 During local development, the repo-local wrapper can run the same command:
 
 ```bash
-./bin/synapsor audit ./tools-list.json
-./bin/synapsor audit ./tools-list.json --format json
+./bin/synapsor-runner audit ./tools-list.json
+./bin/synapsor-runner audit ./tools-list.json --format json
 ```
 
 ## Supported inputs

package/docs/mcp-client-setup.md

@@ -6,10 +6,13 @@ The primary local proof path is still the one-command Docker demo:
 ./scripts/demo-docker.sh
 ```
 
-Use this page after that demo passes and you want to attach a local MCP client. The tested integration contract here is stdio. Client-specific UIs change, so the checked-in examples verify config shape and `tools/list`, not every client screen.
+Use this page after that demo passes and you want to attach a local MCP client.
+The tested local-client contract here is stdio. HTTP MCP is available for
+app/server deployments where your agent connects to a long-running Runner
+service.
 
 Command examples use the published alpha package through `npx`. From a source
-checkout, use `./bin/synapsor ...` only when you intentionally want the local
+checkout, use `./bin/synapsor-runner ...` only when you intentionally want the local
 source wrapper.
 
 Checked examples live in:
@@ -24,12 +27,37 @@ Validate them with:
 corepack pnpm test:mcp-client-configs
 ```
 
+## Stdio Vs HTTP MCP
+
+| Mode | Use when | Command |
+| --- | --- | --- |
+| stdio | Claude Desktop, Cursor, VS Code, or another local MCP client can launch Synapsor Runner | `synapsor-runner mcp serve` |
+| HTTP | Your app/server, Python agent, Node service, or container connects to a long-running Runner service | `synapsor-runner mcp serve-http` |
+
+Stdio keeps the MCP protocol on process stdin/stdout and is the simplest local
+developer path. HTTP uses JSON-RPC over an authenticated `/mcp` endpoint and is
+better for app/server deployments.
+
+HTTP requires bearer auth by default:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+Use private networking/TLS before exposing HTTP MCP beyond localhost. Details:
+[HTTP MCP](http-mcp.md).
+
 ## Generate A Client Snippet
 
 Print a snippet without modifying any client files:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp config claude-desktop \
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
 ```
@@ -47,13 +75,13 @@ vscode
 The older form is still supported:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp configure --client claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp configure --client claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 Write is opt-in and requires an explicit destination:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp configure \
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp configure \
   --client cursor \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
@@ -72,17 +100,28 @@ database URLs or passwords into the client config.
 From the runner repository:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 For the alpha package, keep the package tag explicit in client configuration.
 
+For app/server HTTP mode:
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
+  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
 ## Generic stdio Client
 
 ```json
 {
   "mcpServers": {
-    "synapsor": {
+    "synapsor-runner": {
       "command": "npx",
       "args": [
         "-y",
@@ -148,8 +187,8 @@ Before documenting a client UI as officially tested, verify:
 ## Troubleshooting
 
 - Server not listed: check the command path, working directory, and config path.
-- Tool schema mismatch: run `synapsor audit <exported-tools.json>`.
+- Tool schema mismatch: run `synapsor-runner audit <exported-tools.json>`.
 - Missing trusted context: set `SYNAPSOR_TENANT_ID` and `SYNAPSOR_PRINCIPAL`, or use the environment variables configured in `trusted_context.values`.
 - Database unavailable: verify the read credential and host access.
-- Proposal waiting review: approve outside the model with `synapsor proposals approve`.
+- Proposal waiting review: approve outside the model with `synapsor-runner proposals approve`.
 - Stale-row conflict: inspect replay; the source row changed after the proposal was created, so the guarded worker refused to commit.

package/docs/recipes.md

@@ -9,20 +9,20 @@ tenant key, conflict column, and business limits.
 List recipes:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor recipes list
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes list
 ```
 
 Inspect one:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor recipes show billing.late_fee_waiver
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show billing.late_fee_waiver
 ```
 
 Initialize a starter config:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor recipes init billing.late_fee_waiver --output synapsor.runner.json
-npx -y -p @synapsor/runner@alpha synapsor config validate --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
 ```
 
 Built-in recipes are JSON files under `recipes/`. They are starter data, not
@@ -31,8 +31,8 @@ domain, and initialize from your file:
 
 ```bash
 cp recipes/billing.late_fee_waiver.json my-recipe.json
-npx -y -p @synapsor/runner@alpha synapsor recipes show ./my-recipe.json
-npx -y -p @synapsor/runner@alpha synapsor recipes init ./my-recipe.json --output synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show ./my-recipe.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init ./my-recipe.json --output synapsor.runner.json
 ```
 
 Available recipes:

package/docs/security-boundary.md

@@ -76,7 +76,7 @@ database identifiers such as `../private`, `id/../../tenant_id`, or
 `status; DROP TABLE tickets` before adapter execution. Local CLI file paths
 remain explicit user-provided paths; they are not model-facing authority.
 
-Local review can happen through the CLI or `synapsor ui`. The UI is a localhost
+Local review can happen through the CLI or `synapsor-runner ui`. The UI is a localhost
 review surface with a per-run session token and CSRF protection for
 approve/reject actions. It does not expose raw SQL, database URLs, write
 credentials, approval tools, commit tools, or controls that widen reviewed

package/docs/troubleshooting-first-run.md

@@ -3,13 +3,13 @@
 Run the friendly doctor first:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor doctor --first-run
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --first-run
 ```
 
 Use JSON for automation:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor doctor --first-run --json
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --first-run --json
 ```
 
 ## Docker Missing
@@ -128,13 +128,13 @@ Own-database MCP setup needs a reviewed config before serving tools.
 Fix:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init --from-env DATABASE_URL --mode review --wizard
+npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode review --wizard
 ```
 
 Or pass an example config:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 ## SQLite Store Missing
@@ -180,7 +180,7 @@ Fix:
 
 ```bash
 export SYNAPSOR_DATABASE_READ_URL="<read-only-url>"
-npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json
 ```
 
 ## Read/Write Credential Split Failed
@@ -216,7 +216,7 @@ Fix:
 Regenerate the snippet:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp config claude-desktop \
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
   --absolute-paths \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db

package/docs/writeback-executors.md

@@ -59,7 +59,7 @@ literal values.
 Run after approval:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor apply \
+npx -y -p @synapsor/runner@alpha synapsor-runner apply \
   --proposal wrp_123 \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db

package/examples/openai-agents-http/README.md

@@ -0,0 +1,55 @@
+# OpenAI Agents SDK + Synapsor Runner over HTTP
+
+This example shows an OpenAI Agents SDK app calling a long-running Synapsor
+Runner HTTP MCP service.
+
+Use HTTP when your agent runs as an app/server and should connect to Runner
+over a local/private network endpoint instead of launching a stdio child
+process.
+
+Native HTTP MCP client support can vary by SDK version. This example is honest
+about that: it uses the OpenAI Agents SDK for the agent and wraps Synapsor's
+HTTP MCP JSON-RPC endpoint as an OpenAI function tool.
+
+The model still sees a semantic action. It does not receive raw SQL, database
+URLs, write credentials, approval tools, or commit tools.
+
+## Terminal 1: Start Synapsor Runner HTTP MCP
+
+```bash
+export DATABASE_URL="<postgres-or-mysql-read-url>"
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="openai_agent_demo"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+## Terminal 2: Run The Agent
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+
+export OPENAI_API_KEY="..."
+export SYNAPSOR_RUNNER_HTTP_URL="http://127.0.0.1:8765/mcp"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
+export SYNAPSOR_INVOICE_ID="INV-3001"
+
+python agent.py
+```
+
+Expected behavior:
+
+- the agent calls `billing.inspect_invoice` through Synapsor HTTP MCP;
+- Synapsor applies trusted tenant/principal context from the server process;
+- the response includes scoped data and evidence handles;
+- no SQL/write/approval tool is exposed to the model;
+- evidence/query audit are saved in the local Runner store.
+
+For production-like deployment, keep HTTP MCP behind private networking/TLS,
+bearer auth, and rate limits. See [HTTP MCP](../../docs/http-mcp.md).