@synapsor/runner 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,32 @@
 # Synapsor Runner
 
-Safe database tools for AI agents.
+[![npm version](https://img.shields.io/npm/v/@synapsor/runner.svg)](https://www.npmjs.com/package/@synapsor/runner)
+[![license: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![ci](https://github.com/synapsor-ai/synapsor-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/synapsor-ai/synapsor-runner/actions/workflows/ci.yml)
 
-Turn Postgres/MySQL into reviewed MCP capabilities, not raw SQL. Synapsor
-Runner lets an MCP agent inspect scoped data and request database-backed
-business actions without receiving raw SQL, write credentials, approval tools,
-or commit tools.
+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.
+
+```text
+Without Synapsor:
+  agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")
+           # raw write path, model-controlled scope, easy tenant mistake
+
+With Synapsor Runner:
+  agent -> billing.propose_late_fee_waiver(invoice_id, reason)
+           # proposal only
+  human approves -> guarded writeback applies exactly one change
+```
+
+Try the no-database quick demo:
+
+```bash
+npx @synapsor/runner demo --quick
+```
 
 ## The Five-Line Model
 
@@ -15,60 +36,6 @@ It can suggest: saved proposals with evidence and exact diffs.
 It cannot commit: approval and writeback happen outside the model-facing tool.
 After writeback, Runner keeps receipts and replay so you can inspect what happened.
 
-## Four Terms
-
-- Capability: a tool you define in config, such as `billing.inspect_invoice`
-  or `billing.propose_late_fee_waiver`. The agent only sees capabilities.
-- Proposal: the agent's suggested database-backed change. It is saved, not
-  applied.
-- Writeback: the moment an approved proposal actually changes the database.
-- Executor: your app's writeback handler for anything richer than a guarded
-  one-row update.
-
-You install only `@synapsor/runner`. There is no separate handler package to
-install. A handler is your app's endpoint or script for rich approved writes;
-Runner includes templates and examples to help you build one.
-
-## Who Does What
-
-You write the config: sources, trusted context, capabilities, visible fields,
-proposal fields, and guards. For rich writes, you also write a small handler.
-
-Synapsor Runner serves the MCP tools, stores evidence/proposals/receipts,
-enforces tenant, column, version, and idempotency guards, routes writeback, and
-keeps the replay log. You do not rebuild the safety loop yourself.
-
-## The Writeback Rule
-
-One-row update to an existing row: Runner can do guarded direct writeback.
-Anything else, such as inserting a row, touching two tables, or emitting an
-event: your app-owned executor does it after approval.
-
-## How An External Handler Works
-
-Some changes are too rich for Runner's one-row writeback: insert a credit row,
-touch two tables, or emit an event. For those, you run a small endpoint. The
-flow is:
-
-```text
-agent proposes
--> human approves outside MCP
--> Runner POSTs the approved change to your endpoint
--> your code writes it in its own transaction and returns a receipt
-```
-
-The model never touches this code. You are the last line of defense: Runner
-hands you the tenant, expected row version, and idempotency key, and your
-handler must re-check all three. Skipping those checks reintroduces
-cross-tenant writes, lost updates, or duplicate writes. Start from
-`synapsor-runner handler template ...` instead of hand-rolling the safety checks.
-
-## Deliberate Limits
-
-Runner does not expose raw SQL, write credentials, approval tools, or commit
-tools to the model. Direct Runner writeback does not do generic `INSERT`,
-`DELETE`, `UPSERT`, DDL, or multi-row SQL. Those are app-owned executor jobs.
-
 ```text
 AI agent or MCP client
 (Claude, Cursor, OpenAI Agents SDK, LangGraph)
@@ -97,23 +64,13 @@ Your database stays the source of truth. Synapsor Runner owns the
 model-facing boundary: what the agent can read, what it can propose, what
 evidence is saved, and what can later be reviewed or replayed.
 
-## What Runner Does
-
-When an agent uses Runner:
-
-- the model gets reviewed capabilities, not raw database authority;
-- reads produce evidence handles and query audit;
-- writes become proposals, not direct mutations;
-- approval and writeback happen outside the model-facing MCP surface;
-- replay shows what the agent saw, proposed, and what was applied or blocked.
-
 ## Start Here
 
 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 -y -p @synapsor/runner synapsor-runner demo --quick
+npx @synapsor/runner demo --quick
 ```
 
 In a terminal, it walks through the safety model step by step. In CI, piped
@@ -125,44 +82,189 @@ It does not prove database connectivity. It shows the proposal, evidence, and
 replay flow without giving the runner a database URL.
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner demo inspect
+npx @synapsor/runner demo inspect
 ```
 
-Human output is concise by default. Use `--details` for reviewer metadata or
-`--json` for complete machine-readable records.
-
-Useful quick-demo modes:
+Then choose one path:
 
-```bash
-synapsor-runner demo --quick --guided
-synapsor-runner demo --quick --no-interactive
-synapsor-runner demo --quick --details
-synapsor-runner demo inspect --npx
+```text
+Full disposable proof -> npx -y -p @synapsor/runner synapsor-runner demo
+Inspect MCP risk       -> npx -y -p @synapsor/runner synapsor-runner audit --example dangerous-db-mcp
 ```
 
-Then choose one path:
+## Why Not Just Build This Yourself?
+
+You can build the outline in an afternoon:
 
 ```text
-Full disposable proof  -> npx -y -p @synapsor/runner synapsor-runner demo
-Your own staging DB    -> export DATABASE_URL=... then run the inspect command below
-MCP risk review        -> npx -y -p @synapsor/runner synapsor-runner audit --example dangerous-db-mcp
+model calls a function
+-> app stores a pending change
+-> human approves
+-> app runs SQL
+```
+
+That is useful, but it is not the safety layer. The repeated hard parts are
+tenant scope, no raw SQL exposure, evidence, query audit, exact diffs,
+approval outside the model-facing tool surface, idempotency, stale-row conflict
+checks, affected-row checks, receipts, and replay.
+
+Synapsor Runner gives you those pieces as a local runtime:
+
+- reviewed semantic capabilities instead of `execute_sql`;
+- trusted tenant/principal/object bindings from your server-side context;
+- scoped reads with evidence handles and query audit;
+- saved proposals with exact before/after changes;
+- approval and writeback commands that are not exposed to the model;
+- guarded direct writeback for one-row updates;
+- app-owned executors for richer writes;
+- idempotency receipts and replay so you can inspect what happened later.
+
+If all you need is restricted reads, a read-only database user and safe views
+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.
+
+## Connect Your Postgres Or MySQL
+
+Use a staging or disposable database first:
+
+```bash
+export DATABASE_URL="postgres://readonly:...@localhost:5432/app"
+npx -y -p @synapsor/runner synapsor-runner start --from-env DATABASE_URL
 ```
 
-For your own database, do this before wiring Claude, Cursor, OpenAI Agents SDK,
-or another MCP client:
+The first-run path is:
 
 ```text
-1. Generate the config with start/init/onboard.
+1. Inspect schema and generate a reviewed config with start/init/onboard.
 2. Run tools preview to confirm no raw SQL or write credentials are exposed.
 3. Run smoke call against one generated inspect tool.
-4. Only then run up --serve or mcp serve.
+4. Start review mode with up --serve or mcp serve.
+5. Inspect, propose, approve, apply, and replay from the local ledger.
+```
+
+Useful commands after setup:
+
+```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
+synapsor-runner up --serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+If you already have a canonical `synapsor.contract.json` from the DSL, Cloud,
+or the C++ exporter, keep it as the source of truth and reference it from local
+runner wiring:
+
+```json
+{
+  "version": 1,
+  "mode": "review",
+  "contracts": ["./synapsor.contract.json"],
+  "sources": {
+    "local_postgres": {
+      "engine": "postgres",
+      "read_url_env": "DATABASE_URL"
+    }
+  },
+  "storage": {
+    "sqlite_path": "./.synapsor/local.db"
+  }
+}
+```
+
+Preview the model-facing tool surface before connecting an MCP client:
+
+```bash
+synapsor-runner contract validate ./synapsor.contract.json
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+## What Runner Does
+
+When an agent uses Runner:
+
+- the model gets reviewed capabilities, not raw database authority;
+- reads produce evidence handles and query audit;
+- writes become proposals, not direct mutations;
+- approval and writeback happen outside the model-facing MCP surface;
+- replay shows what the agent saw, proposed, and what was applied or blocked.
+
+## Four Terms
+
+- Capability: a tool you define in config, such as `billing.inspect_invoice`
+  or `billing.propose_late_fee_waiver`. The agent only sees capabilities.
+- Proposal: the agent's suggested database-backed change. It is saved, not
+  applied.
+- Writeback: the moment an approved proposal actually changes the database.
+- Executor: your app's writeback handler for anything richer than a guarded
+  one-row update.
+
+You install only `@synapsor/runner`. There is no separate handler package to
+install. A handler is your app's endpoint or script for rich approved writes;
+Runner includes templates and examples to help you build one.
+
+## Who Does What
+
+You write the config: sources, trusted context, capabilities, visible fields,
+proposal fields, and guards. For rich writes, you also write a small handler.
+
+Synapsor Runner serves the MCP tools, stores evidence/proposals/receipts,
+enforces tenant, column, version, and idempotency guards, routes writeback, and
+keeps the replay log. You do not rebuild the safety loop yourself.
+
+## The Writeback Rule
+
+One-row update to an existing row: Runner can do guarded direct writeback.
+Anything else, such as inserting a row, touching two tables, or emitting an
+event: your app-owned executor does it after approval.
+
+## How An External Handler Works
+
+Some changes are too rich for Runner's one-row writeback: insert a credit row,
+touch two tables, or emit an event. For those, you run a small endpoint. The
+flow is:
+
+```text
+agent proposes
+-> human approves outside MCP
+-> Runner POSTs the approved change to your endpoint
+-> your code writes it in its own transaction and returns a receipt
+```
+
+The model never touches this code. You are the last line of defense: Runner
+hands you the tenant, expected row version, and idempotency key, and your
+handler must re-check all three. Skipping those checks reintroduces
+cross-tenant writes, lost updates, or duplicate writes. Start from
+`synapsor-runner handler template ...` instead of hand-rolling the safety checks.
+
+## Deliberate Limits
+
+Runner does not expose raw SQL, write credentials, approval tools, or commit
+tools to the model. Direct Runner writeback does not do generic `INSERT`,
+`DELETE`, `UPSERT`, DDL, or multi-row SQL. Those are app-owned executor jobs.
+
+## Command Name
+
+```bash
+npm install -g @synapsor/runner
+synapsor-runner demo --quick
 ```
 
 `synapsor-runner` is the public command for this OSS runner. `synapsor` is
-reserved for the Synapsor Cloud CLI.
+reserved for the Synapsor Cloud CLI. If you install the package globally, you
+can drop the `npx -y -p @synapsor/runner` prefix.
+
+Contributor note: during development, test local changes with
+`./bin/synapsor-runner ...` or a packed tarball. `npx -p @synapsor/runner ...`
+only tests the currently published package, not unpublished local source
+changes.
 
 Authoring reference:
 
+- [Migrating To `@synapsor/spec`](docs/migrating-to-synapsor-spec.md):
+  split portable contract semantics from local runner wiring.
+- [Conformance Fixtures](docs/conformance.md): how the shared fixture suite
+  keeps Runner and Cloud/C++ contract semantics from drifting.
 - [Capability Authoring](docs/capability-authoring.md): read/proposal tools,
   model-facing descriptions, result envelope v2, trusted context, and writeback
   guards.
@@ -171,7 +273,7 @@ Authoring reference:
 - [JSON Schema](schemas/synapsor.runner.schema.json): editor validation for
   `synapsor.runner.json`.
 
-## Current Alpha Details
+## Operational Details
 
 These are current alpha requirements, not hidden behavior:
 
@@ -206,12 +308,64 @@ These are current alpha requirements, not hidden behavior:
   `synapsor-runner doctor --config synapsor.runner.json --check-handlers` to
   check handler env vars and network reachability without applying a proposal.
 
+## Run The Full Disposable Demo
+
+The full demo requires Docker. It starts a disposable local Postgres-backed app
+and proves the proposal-first write path:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner demo
+```
+
+After the demo prints its generated config and store path, run the happy path it
+prints. The shape is:
+
+```bash
+synapsor-runner propose billing.propose_late_fee_waiver --sample
+synapsor-runner proposals show latest
+synapsor-runner proposals approve latest --yes
+synapsor-runner apply latest
+synapsor-runner replay show latest
+synapsor-runner replay show latest --details
+```
+
+What you should see:
+
+```text
+Agent called:
+billing.propose_late_fee_waiver
+
+Proposal created:
+invoice.late_fee_cents
+5500 -> 0
+
+Source DB changed:
+no
+
+Approval:
+required outside MCP
+
+After approval:
+guarded writeback applied
+
+Replay:
+saved
+```
+
+That is the core point: the model can ask for a database-backed business
+change, but durable state changes only after reviewed approval and guarded
+writeback.
+
 ## Connect Your Own Staging Database
 
-Put a read-only connection string in the environment:
+Use this after the quick demo makes sense. Start with staging, a disposable
+database, or a least-privilege view. Do not start with your most sensitive
+production database.
+
+Put the read-only connection string in an environment variable:
 
 ```bash
-export DATABASE_URL="postgresql://readonly_user:password@localhost:5432/app"
+export DATABASE_URL="postgresql://readonly_user:password@host:5432/app?sslmode=require"
 ```
 
 For disposable dev RDS fixtures only, use `sslmode=no-verify` if your local
@@ -238,20 +392,6 @@ call immediately and stores the evidence/query audit in the local ledger. If
 those env vars are missing, it prints the exact command to run after you set
 them from `.env.example`.
 
-The end-to-end shape is:
-
-```text
-1. Put your read-only DB URL in DATABASE_URL.
-2. Run start --from-env DATABASE_URL.
-3. Choose one table/view and the safe fields agents may see.
-4. Preview the generated capabilities.
-5. Serve them over MCP to Claude, Cursor, OpenAI Agents SDK, or your app.
-6. For writes, approve a proposal outside MCP before writeback.
-```
-
-The generated config is just the safety contract. A small reviewed version
-looks like this:
-
 Bring the generated review-mode workspace up with one command:
 
 ```bash
@@ -301,6 +441,20 @@ so `config validate` does not warn that direct SQL writeback is disabled.
 You can also pass `--answers ./answers.json --yes` for a fully declarative
 setup file.
 
+The end-to-end shape is:
+
+```text
+1. Put your read-only DB URL in DATABASE_URL.
+2. Run start --from-env DATABASE_URL.
+3. Choose one table/view and the safe fields agents may see.
+4. Preview the generated capabilities.
+5. Serve them over MCP to Claude, Cursor, OpenAI Agents SDK, or your app.
+6. For writes, approve a proposal outside MCP before writeback.
+```
+
+The generated config is just the safety contract. A small reviewed version
+looks like this:
+
 ```json
 {
   "version": 1,
@@ -371,6 +525,17 @@ The agent sees `billing.inspect_invoice` and
 `billing.propose_late_fee_waiver`. It does not see the database URL, writer
 credential, raw SQL, approval command, or commit command.
 
+Prefer the step-by-step commands if you want to inspect each stage manually:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner inspect \
+  --engine auto \
+  --from-env DATABASE_URL \
+  --schema public
+
+npx -y -p @synapsor/runner synapsor-runner init --wizard --from-env DATABASE_URL --mode read_only
+```
+
 The wizard creates this local flow:
 
 ```text
@@ -380,45 +545,55 @@ trusted context -> capability -> MCP tool
 It asks which table/view backs the context, which tenant/scope column and
 backend session env vars are trusted, which fields are visible, and what
 semantic capability name to expose. Before writing files, it shows a final
-preview and lets you revise visible fields or capability names.
+preview and lets you revise visible fields or capability names. It writes
+`synapsor.runner.json`, `.env.example`, and MCP client snippets. It does not put
+your database URL in the MCP client config.
+
+Preview the tools:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
-  --wizard \
-  --engine auto \
-  --from-env DATABASE_URL \
-  --schema public \
-  --mode read_only
+npx -y -p @synapsor/runner synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
 ```
 
-Preview and serve the semantic tools:
+Call one generated tool locally before wiring an MCP client:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner tools preview \
+npx -y -p @synapsor/runner synapsor-runner smoke call \
+  <generated.inspect_tool_name> \
+  --input ./.synapsor/smoke-input.json \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
+```
 
+`smoke call` uses the same runtime as MCP, records evidence/query audit or a
+proposal in the local store, and then prints the evidence/proposal/replay
+commands to inspect what happened. If you skipped the optional smoke input in
+the wizard, pass one real row id instead:
+
+```bash
 npx -y -p @synapsor/runner synapsor-runner smoke call \
   <generated.inspect_tool_name> \
-  --input ./.synapsor/smoke-input.json \
+  --json '{"<lookup_arg>":"<real_id>"}' \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
+```
 
+Serve the semantic MCP tools locally:
+
+```bash
 npx -y -p @synapsor/runner synapsor-runner mcp serve \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
 ```
 
-`smoke call` uses the same runtime as MCP, records evidence/query audit or a
-proposal in the local store, and prints the evidence/proposal/replay commands
-to inspect what happened. If you skipped the optional smoke input in the
-wizard, pass `--json '{"<lookup_arg>":"<real_id>"}'` instead.
-
-## Two Ways To Run MCP
+## Three Ways To Run MCP
 
 Use stdio when the MCP client runs locally and can launch Synapsor Runner. Use
-HTTP when your agent service runs as an app/server and connects to a
-long-running Runner process.
+Streamable HTTP when a standard HTTP MCP client connects to a long-running
+Runner process. Use the JSON-RPC bridge only when you want simple POST calls
+from your own app/server wrapper.
 
 Local MCP clients:
 
@@ -460,7 +635,8 @@ synapsor-runner up --serve \
   --alias-mode openai
 ```
 
-Equivalent unified command:
+The same Streamable HTTP server can also be started through the unified serve
+command:
 
 ```bash
 synapsor-runner mcp serve \
@@ -500,86 +676,61 @@ examples/openai-agents-stdio/
 examples/openai-agents-http/
 ```
 
-Use `--mode review` only when you are ready to create proposal tools and test
-guarded writeback with a separate trusted write credential.
-
-## Sanity Check The Agent Connection
+Detailed setup: [docs/openai-agents-sdk.md](docs/openai-agents-sdk.md).
 
-Before asking an agent to solve a real task, confirm it can call a Runner tool:
+Use `--mode review` only when you are ready to create proposal tools and test
+guarded writeback. Review mode needs an approved write path and a separate
+trusted write credential; the model-facing read URL should stay least
+privilege.
 
-```bash
-synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
-```
+## Audit Your MCP Database Tools
 
-For OpenAI-facing clients:
+`synapsor-runner audit` is a static MCP/database risk review. It is useful even before
+you adopt the full runner.
 
 ```bash
-synapsor-runner tools preview \
-  --config ./synapsor.runner.json \
-  --store ./.synapsor/local.db \
-  --alias-mode openai
+synapsor-runner audit --example dangerous-db-mcp
+synapsor-runner audit --example dangerous-db-mcp --format markdown
+synapsor-runner audit ./synapsor.runner.json
+synapsor-runner audit --mcp-config ./claude_desktop_config.json
+synapsor-runner audit --stdio "node ./my-db-mcp-server.js"
 ```
 
-Then ask the agent:
+The built-in example runs without cloning this repository or downloading an
+examples file. File-based audits still work when you have your own exported MCP
+tool manifest.
 
-```text
-Use the Synapsor Runner MCP tool to inspect invoice INV-3001.
-Do not answer from memory.
-Return the tool name called, the evidence handle, and whether raw SQL was available.
-```
-
-Expected result: the agent calls a semantic tool, returns an evidence handle or
-local ledger reference, and says raw SQL/write/approval tools were not
-available. If it gives generic advice or unrelated prose without a tool call,
-Runner is not connected yet.
-
-The disposable reference app includes proposal-first write examples for:
-
-- `billing.propose_late_fee_waiver`
-- `support.propose_plan_credit`
-- `orders.propose_status_change`
-
-Each tool creates evidence, a before/after diff, and a proposal. The source
-database remains unchanged until approval outside MCP and guarded writeback.
-
-For a longer local session, you can install the package globally:
-
-```bash
-npm install -g @synapsor/runner
-```
+It looks for patterns such as:
 
-## Stable Compatibility Promise
+- arbitrary SQL tools;
+- broad database write tools;
+- model-facing approval/commit tools;
+- missing tenant/principal context;
+- dangerous tool names;
+- unclear parameter schemas;
+- mutation tools without proposal/approval.
 
-Starting with `0.1.0`, Synapsor Runner keeps the documented `synapsor-runner`
-binary, `synapsor.runner.json` schema version `1`, result envelope v2, stdio
-MCP, Streamable HTTP MCP, MCP client snippets, proposal/approval/writeback
-inspection commands, direct SQL writeback contract, and app-owned executor
-contract compatible through the `0.1.x` line unless a release note marks a
-deprecation first.
-
-Stable does not mean production SLA, hosted Cloud features, compliance
-certification, physical Postgres/MySQL branching, generic SQL writeback, or
-support for undocumented local SQLite internals.
-
-## Runtime Flow
-
-The local runner keeps the model-facing tool call separate from approval and
-writeback:
+Example finding:
 
 ```text
-MCP tool call
--> trusted context
--> scoped read
--> evidence
--> proposal diff
--> approval outside the model
--> guarded writeback
--> receipt/replay
+Risk: high
+
+Found:
+- execute_sql appears to expose arbitrary database access.
+- approve_refund appears to let the model approve a durable write.
+- update_customer appears to mutate state without a proposal boundary.
+- No trusted tenant/principal context was detected.
+
+Suggested safer shape:
+- billing.inspect_invoice
+- billing.propose_late_fee_waiver
+- approval outside MCP
+- guarded writeback after approval
+
+Note:
+This is a static risk review, not a security guarantee.
 ```
 
-Your Postgres/MySQL database remains the source of truth. The runner stores
-local proposals, evidence, receipts, and replay data in a local SQLite store.
-
 ## Why Not Just Use A Read-Only Database User?
 
 You should use one.
@@ -606,47 +757,30 @@ Use Synapsor Runner when you also want the agent-facing layer: semantic tools,
 trusted context, evidence handles, query audit, local inspection, and
 proposal-first writes.
 
-## Fixture Benchmark
-
-Run the included MCP efficiency fixture:
+## Find Evidence And Replay
 
-```bash
-synapsor-runner benchmark mcp-efficiency
-```
+The commands in this section require this checkout or an alpha package that
+includes the local-ledger CLI surface.
 
-Current fixture result for the late-fee-waiver workflow:
+Synapsor Runner writes a local evidence/replay ledger to SQLite. Use it to
+answer questions such as:
 
 ```text
-Generic database MCP reference:
-  exposed tools: 4
-  scripted tool calls: 5
-  raw SQL exposed: yes
-  approval separated: no
-  stale-row conflict checked: no
-
-Synapsor Runner semantic path:
-  exposed tools: 2
-  scripted tool calls: 2
-  raw SQL exposed: no
-  approval separated: yes
-  stale-row conflict checked: yes
+What did the agent see and do for invoice INV-3001?
 ```
 
-The fixture tokenizer is deterministic and repeatable for this package. It is
-not a model billing tokenizer and not a universal token-savings claim.
-
-## Find Evidence And Replay
-
-The commands in this section require this checkout or an alpha package that
-includes the local-ledger CLI surface.
-
-The runner stores a local SQLite evidence/replay ledger. Search it without
-relying on `latest`:
+Search the local activity ledger:
 
 ```bash
 synapsor-runner activity search --tenant acme --object invoice:INV-3001
+synapsor-runner activity search --capability billing.propose_late_fee_waiver --from 2026-06-01 --to 2026-06-23
 synapsor-runner events tail --store ./.synapsor/local.db
 synapsor-runner events webhook --url http://127.0.0.1:8788/synapsor/events --kind proposal_created --store ./.synapsor/local.db
+```
+
+Inspect the linked records:
+
+```bash
 synapsor-runner proposals list --tenant acme --object invoice:INV-3001 --status approved
 synapsor-runner evidence show ev_...
 synapsor-runner query-audit list --evidence ev_...
@@ -656,16 +790,17 @@ synapsor-runner replay show --proposal wrp_...
 synapsor-runner replay show --replay replay_wrp_...
 ```
 
-Default inspection output is meant for first-run clarity. Add `--details` for
+The default views answer what happened, whether the source DB changed, the
+current status, and the next command to run. Add `--details` when you need
 target URIs, primary keys, proposal hash/version, conflict guards, query
-fingerprints, event timestamps, and receipt internals.
+fingerprints, event timestamps, or receipt internals.
 
-Export captured evidence or proposal replay:
+Export replay or evidence for review:
 
 ```bash
-synapsor-runner evidence export ev_... --format markdown --output evidence.md
 synapsor-runner replay export --proposal wrp_... --format json --output replay.json
 synapsor-runner replay export --proposal wrp_... --format markdown --output replay.md
+synapsor-runner evidence export ev_... --format markdown --output evidence.md
 ```
 
 Create a redacted local diagnostic report:
@@ -690,16 +825,171 @@ synapsor-runner store reset --store ./.synapsor/local.db --yes
 bridges, or app-local notifications. It POSTs one redacted local event envelope
 per lifecycle event; it is not a hosted central ledger.
 
-This is local indexed search for local/dev/staging usage. It is not external
-database time travel, not cross-runner search, and not hosted compliance
-retention.
+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.
+
+## Connect Claude, Cursor, Or Another MCP Client
+
+Generate a local MCP client snippet:
+
+```bash
+synapsor-runner mcp config --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Use a specific client shape when needed:
+
+```bash
+synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner mcp config vscode --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner mcp client-config --client openai-agents --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+The generated config references the local runner command. It does not include:
+
+- database URL;
+- database password;
+- write credentials;
+- approval tools;
+- commit/apply tools.
+
+## Sanity Check The Agent Connection
+
+After you connect Claude, Cursor, OpenAI Agents SDK, or another MCP client, run
+one tiny tool-call test before asking the agent to solve a real task.
+
+First preview the tools Runner will expose:
+
+```bash
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+For OpenAI-facing clients, preview the model-visible aliases:
+
+```bash
+synapsor-runner tools preview \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --alias-mode openai
+```
+
+Example:
+
+```text
+Exposed to MCP:
+  - billing__inspect_invoice -> billing.inspect_invoice
+```
+
+Then ask the agent:
+
+```text
+Use the Synapsor Runner MCP tool to inspect invoice INV-3001.
+Do not answer from memory.
+Return the tool name called, the evidence handle, and whether raw SQL was available.
+```
+
+For your own database, replace `invoice INV-3001` with one real object ID and
+the semantic tool name from `tools preview`.
+
+Expected result:
+
+- the agent calls a Synapsor Runner tool such as `billing.inspect_invoice`;
+- the response includes an evidence handle or local ledger reference;
+- the agent says raw SQL/write/approval tools were not available.
+
+If the agent gives generic advice, a freeform summary, or unrelated planning
+text without a tool call or evidence handle, Runner is not in the loop yet. Fix
+the MCP client config, restart the client, confirm trusted context environment
+variables are set, and rerun `synapsor-runner tools preview`.
+
+## What The Model Gets
+
+The model gets reviewed semantic capabilities from `synapsor.runner.json`, for
+example:
+
+```text
+billing.inspect_invoice
+billing.propose_late_fee_waiver
+support.inspect_ticket
+support.propose_plan_credit
+orders.inspect_order
+orders.propose_status_change
+```
+
+These are business tools with trusted scope, visible fields, evidence rules,
+proposal boundaries, and writeback guards.
+
+## Fixture Benchmark
+
+Run the included MCP efficiency fixture:
+
+```bash
+synapsor-runner benchmark mcp-efficiency
+```
+
+Current fixture result for the late-fee-waiver workflow:
+
+```text
+Generic database MCP reference:
+  exposed tools: 4
+  scripted tool calls: 5
+  raw SQL exposed: yes
+  approval separated: no
+  stale-row conflict checked: no
+
+Synapsor Runner semantic path:
+  exposed tools: 2
+  scripted tool calls: 2
+  raw SQL exposed: no
+  approval separated: yes
+  stale-row conflict checked: yes
+```
+
+The fixture tokenizer is deterministic and repeatable for this repo. It is not
+a model billing tokenizer and not a universal token-savings claim.
+
+## Safe Write Examples
+
+The disposable reference app includes three proposal-first write shapes:
+
+- `billing.propose_late_fee_waiver`: waive a late fee after evidence and review.
+- `support.propose_plan_credit`: propose a bounded customer credit for a support case.
+- `orders.propose_status_change`: move an order through an allowlisted status transition.
+
+Each tool creates evidence, a before/after diff, and a local proposal. The
+source database is unchanged until approval outside MCP and guarded writeback.
+
+## What The Model Never Gets
+
+Synapsor Runner does not expose:
+
+```text
+execute_sql
+raw_sql
+query_database
+database URLs
+write credentials
+approval tools
+commit/apply tools
+arbitrary table names
+arbitrary column names
+model-controlled tenant authority
+direct write access
+```
+
+Approval and writeback stay outside the model-facing MCP tool surface.
 
 ## App-Owned Writeback
 
-Use direct guarded DB writeback for simple local/staging single-row updates. If
-your application service already owns business writes, configure an
-`http_handler` or `command_handler` executor. Approval still happens outside
-MCP, and the handler returns an applied/conflict/failed receipt for replay.
+Direct guarded DB writeback is useful for local/staging demos and simple
+single-row updates. If your application service already owns business writes,
+configure an `http_handler` or `command_handler` executor instead.
+
+The flow stays the same: model-facing MCP creates a proposal, approval happens
+outside MCP, Synapsor Runner sends an approved job to your app handler, and the
+handler returns an applied/conflict/failed receipt for replay.
 
 > **Important:** your app handler owns the final business write. Runner creates
 > the proposal and calls your handler only after approval, but your handler must
@@ -708,10 +998,17 @@ MCP, and the handler returns an applied/conflict/failed receipt for replay.
 > error receipts. If you skip those checks, you can reintroduce cross-tenant
 > writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
 
-Starter handlers are included under `examples/app-owned-writeback`.
-The packaged app-owned billing example also includes a bundled
-`synapsor-handler.mjs` helper shim. There is no separate handler package to
-install.
+Details: [docs/writeback-executors.md](docs/writeback-executors.md). Starter
+handlers live in [examples/app-owned-writeback](examples/app-owned-writeback).
+The runner npm package includes handler templates and the
+`examples/mcp-postgres-billing-app-handler/synapsor-handler.mjs` bundled helper
+shim. These show bearer/HMAC auth, tenant scope, expected-version guards,
+idempotency, transaction rollback, and safe receipts around your business
+effect. There is no separate handler package to install.
+The full Postgres billing example in
+[examples/mcp-postgres-billing-app-handler](examples/mcp-postgres-billing-app-handler)
+shows `billing.propose_account_credit` creating a proposal first, then inserting
+an `account_credits` row through an app-owned HTTP handler after approval.
 You can also generate a starter handler directly:
 
 ```bash
@@ -726,16 +1023,224 @@ needs permission for that receipt table or an administrator must pre-create and
 grant it. Use app-owned handlers when you do not want Runner creating receipt
 tables in your application schema.
 
-## Command Name
+## Safety Model
+
+```text
+MCP client
+-> Synapsor Runner
+-> semantic capability
+-> trusted tenant/principal context
+-> scoped DB read
+-> evidence-backed proposal
+-> approval outside MCP
+-> guarded writeback
+-> receipt and replay
+```
+
+Current boundaries:
+
+- no generic SQL tools;
+- no model-facing approval or apply tools;
+- tenant/principal scoping is enforced;
+- allowed columns are enforced;
+- primary-key targeting is required;
+- conflict/version guards are available;
+- idempotency keys are used;
+- affected row count is checked;
+- direct DB writeback is limited to guarded single-row `UPDATE`.
+
+## Safety Checks It Catches
+
+After the happy path, use the demo and tests to inspect failure cases:
+
+- stale-row conflict;
+- missing tenant context;
+- disallowed write column;
+- model-facing commit or approval tool;
+- arbitrary SQL tool.
+
+The important stale-row case:
+
+```text
+The row changed after the agent saw it.
+Result: conflict
+Source DB changed by Synapsor: no
+```
+
+Conflict handling is a safety check, not the first demo payoff.
+
+## Local Features
+
+| Feature | Runner version |
+| --- | --- |
+| Context bindings | Trusted tenant/principal from env, static dev config, HTTP claims, or cloud session |
+| Capabilities | Local semantic MCP tools from `synapsor.runner.json` |
+| Evidence | Local evidence bundles and query audit records |
+| Proposals | Local before/after change sets |
+| Approval | Local CLI/UI approval outside MCP |
+| Writeback | Guarded single-row `UPDATE` for Postgres/MySQL |
+| Replay | Local replay of proposal, evidence, events, receipts, and query audit |
+| MCP audit | Static risk review for MCP database tools |
+
+The runner intentionally does not include full Synapsor Cloud/DBMS features such
+as workflow DAGs, native branches, time travel, settlement policies, governed
+memory, RBAC/SSO, hosted evidence ledger, managed runners, CDC, or C++ DBMS
+internals.
+
+## Local Runner Vs Synapsor Cloud
+
+| Need | Synapsor Runner | Synapsor Cloud |
+| --- | --- | --- |
+| Local MCP server | Yes | Managed |
+| Local trusted context bindings | Yes | Org/session integrated |
+| 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 |
+| MCP risk audit | Static/local | Continuous/org-wide |
+| RBAC/SSO | No | Yes |
+| Policy packs | No/basic | Yes |
+| Workflow builder | No | Yes |
+| Native branches/time travel | No | Yes |
+| Settlement policies | No | Yes |
+| Compliance exports | No | Yes |
+| Production support/SLA | No | Yes |
+
+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.
+
+## Current Limitations
+
+Supported in the current alpha:
+
+- stdio MCP server;
+- authenticated HTTP MCP server for app/server deployments;
+- Postgres/MySQL inspection;
+- semantic read tools;
+- evidence-backed proposals;
+- local approval outside MCP;
+- guarded single-row `UPDATE`;
+- local SQLite evidence/proposal/replay store;
+- tenant, primary-key, allowed-column, idempotency, and conflict guards;
+- static MCP risk audit.
+
+Not supported:
+
+- raw `execute_sql`;
+- model-generated SQL;
+- DDL;
+- INSERT;
+- DELETE;
+- UPSERT;
+- multi-row writes;
+- stored procedures;
+- physical branching of external Postgres/MySQL;
+- full Synapsor workflow DAG execution;
+- `CREATE AGENT WORKFLOW`;
+- Synapsor SQL generation;
+- auto-merge or settlement-policy semantics;
+- model-callable approval or commit tools;
+- general prompt-injection prevention;
+- production SLA or compliance certification.
+
+Complete limits: [docs/limitations.md](docs/limitations.md).
+
+Security boundary: [docs/security-boundary.md](docs/security-boundary.md).
+
+Single-node production-candidate runbook:
+[docs/production.md](docs/production.md).
+
+Release notes and stable-tag policy:
+[docs/release-notes.md](docs/release-notes.md).
+
+## Stable Compatibility Promise
+
+Starting with `0.1.0`, Synapsor Runner keeps the following surfaces compatible
+through the `0.1.x` line unless a release note explicitly marks a deprecation
+first:
+
+- the `synapsor-runner` binary name and README quickstart commands;
+- `synapsor.runner.json` schema version `1` for documented fields;
+- result envelope v2 for new configs, with the documented v1 opt-out;
+- stdio MCP and Streamable HTTP MCP command surfaces;
+- generated MCP client snippets for documented clients;
+- proposal, approval, guarded writeback, receipt, evidence, query-audit, and
+  replay inspection commands;
+- direct SQL writeback and app-owned executor contracts documented in this
+  README and `docs/writeback-executors.md`.
+
+Stable does not mean production SLA, hosted Cloud features, compliance
+certification, physical Postgres/MySQL branching, generic SQL writeback, or
+support for undocumented local SQLite internals. Those limits remain explicit
+in [docs/limitations.md](docs/limitations.md).
+
+## License
+
+Synapsor Runner is open source under the Apache License 2.0 (`Apache-2.0`).
+
+Apache-2.0 applies to this runner repo. It does not grant rights to the
+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.
+
+## Developer And Contributor Commands
+
+Public docs use `synapsor-runner`. During source-checkout development, if the
+global binary is not linked yet, use `./bin/synapsor-runner ...` or
+`corepack pnpm runner ...`.
+
+Helper scripts are wrappers and development conveniences, not the main product
+interface:
+
+```bash
+./scripts/try-synapsor.sh
+./scripts/demo-docker.sh
+./scripts/open-demo-ui.sh
+./scripts/use-your-db.sh
+./scripts/mcp-config.sh
+```
+
+Contributor checks:
+
+```bash
+corepack pnpm install
+./scripts/verify-release-gate.sh
+```
+
+After a manual alpha publish, verify the public npm package:
+
+```bash
+VERIFY_PUBLISHED_ALPHA=1 ./scripts/verify-release-gate.sh 0.1.0-alpha.17
+```
+
+After a manual stable publish/promotion, verify `latest`:
+
+```bash
+./scripts/verify-published-stable.sh 0.1.0
+```
+
+## Repository Map
 
-This package installs `synapsor-runner` as the OSS runner binary. The `synapsor`
-command is reserved for the Synapsor Cloud CLI.
+- `apps/runner`: CLI entrypoint and local UI.
+- `packages/mcp-server`: stdio/HTTP MCP server and configured tool runtime.
+- `packages/schema-inspector`: Postgres/MySQL metadata inspection and config generation.
+- `packages/proposal-store`: local SQLite evidence/proposal/replay store.
+- `packages/postgres`, `packages/mysql`: guarded writeback adapters.
+- `packages/worker-core`: shared runner orchestration.
+- `recipes`: optional starter contracts.
+- `examples`: disposable local demos and reference app.
+- `docs`: focused setup, MCP, security, troubleshooting, and limitation docs.
 
-## Scope
+## Community
 
-This package is an alpha local runner. It is not Synapsor Cloud, not the
-Synapsor DBMS, not a physical branch engine for Postgres/MySQL, and not a
-general MCP security platform.
+Synapsor Runner is maintained by Synapsor.
 
-See the full repository README and docs for Docker demos, MCP client setup,
-configuration recipes, security boundaries, and release notes.
+- Website: https://synapsor.ai
+- Docs: https://synapsor.ai/docs
+- License: Apache License 2.0 (`Apache-2.0`)
+- Issues: use GitHub Issues