@synapsor/runner 0.1.0 → 0.1.1

package/docs/README.md

@@ -1,74 +1,109 @@
 # Synapsor Runner Docs
 
-Start with the README. Use these docs only when you need the next level of
-detail.
+Start with the README. Use this index when you need the task-specific next
+step. The order is intentional: run something first, wire your database second,
+then read the concepts once the safety boundary is visible.
 
-## First Setup
+## 01 Quickstart
+
+- [README](../README.md): wedge, no-DB quick demo, five-line model, and the
+  shortest own-database path.
+- [Troubleshooting First Run](troubleshooting-first-run.md): common first-run
+  failures, redacted diagnostics, and fixes.
+
+## 02 Why Raw SQL Is Dangerous
+
+- [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [MCP Audit](mcp-audit.md): static review for risky database MCP tools such as
+  `execute_sql`, broad query tools, model-controlled tenant filters, or
+  model-facing approval/commit tools.
+
+## 03 Run The Demo
+
+- `examples/support-billing-agent/`: flagship support/billing agent demo with
+  `make demo`, expected output, and the raw-SQL-vs-Synapsor contrast.
+- `examples/raw-sql-vs-synapsor/`: no-database fear/fix demo.
+- `examples/reference-support-billing-app/`: shared fixture used by the
+  flagship demo and package smoke tests.
+
+## 04 Connect Your DB
 
 - [Connect Your Own Database](getting-started-own-database.md): inspect a
   staging Postgres/MySQL database, generate `synapsor.runner.json`, preview
   semantic tools, and serve them over MCP.
 - [Use Your Own Database](use-your-own-database.md): short entry point that
   links to the canonical own-database guide.
+- [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
+  writeback probes, and receipt-table guidance.
+
+## 05 Generate Capabilities
+
+- [Capability Authoring](capability-authoring.md): define read/proposal
+  capabilities, model-facing descriptions, result envelopes, trusted context,
+  and writeback guards.
+- [Recipes](recipes.md): starter business-capability templates.
+- [JSON Schema](../schemas/synapsor.runner.schema.json): editor validation for
+  `synapsor.runner.json`.
+
+## 06 Serve MCP
+
 - [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
   another stdio MCP client.
+- `examples/claude-desktop-postgres/`: copy-paste Claude Desktop config for the
+  Postgres billing fixture.
+- `examples/cursor-postgres/`: copy-paste Cursor config for the Postgres
+  billing fixture.
 - [HTTP MCP](http-mcp.md): run Synapsor Runner as an authenticated HTTP MCP
   service for app/server agents.
 - [OpenAI Agents SDK](openai-agents-sdk.md): use Streamable HTTP MCP with
   OpenAI-safe tool aliases.
-- [Capability Authoring](capability-authoring.md): define read/proposal
-  capabilities, model-facing descriptions, result envelopes, trusted context,
-  and writeback guards. JSON Schema:
-  `../schemas/synapsor.runner.schema.json`.
-- [Result Envelope v2](result-envelope-v2.md): the generated-config default
-  `ok`/`summary`/`data`/`proposal`/`error` response shape for MCP tools.
-- [Handler Helper](handler-helper.md): TypeScript helper for safe app-owned
-  rich-write handlers.
-- RFC source context:
-  [001 result envelope](rfcs/001-result-envelope-v2.md),
-  [002 handler helper](rfcs/002-app-owned-handler-helper.md),
-  [003 integrator teardown](rfcs/003-integrator-feedback-teardown.md).
 
-## Safety And Operations
+## 07 Propose, Approve, Apply
 
-- [Security Boundary](security-boundary.md): what the model can and cannot see.
-- [Current Limitations](limitations.md): current alpha scope.
-- [Current Scope](current-scope.md): compact alpha scope summary.
-- [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
-- [Release Notes](release-notes.md): alpha behavior, breaking changes, and the
-  stable release policy.
-- [Release Policy](release-policy.md): alpha expectations, stable gates,
-  result envelope migration, and publish verification.
-- [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is
-  not included in this runner repo.
-- [Dependency License Inventory](dependency-license-inventory.md): current
-  dependency license summary for release review.
-- [Troubleshooting First Run](troubleshooting-first-run.md): common setup
-  failures and fixes.
-- [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
-  writeback probes, and receipt-table guidance.
 - [Local Mode](local-mode.md): local store, proposals, approval, replay, and
   writeback flow.
-- [Store Lifecycle](store-lifecycle.md): active-store leases, prune safety,
-  deleted-store behavior, and concurrent server guardrails.
-
-## Features
-
-- [MCP Audit](mcp-audit.md): static risk review for database MCP tools.
-- [Recipes](recipes.md): starter business-capability templates.
 - [Writeback Executors](writeback-executors.md): app-owned writeback handlers
   for approved proposals.
 - [App-Owned Executors](app-owned-executors.md): short entry point for rich
   business transactions handled by your app.
-- `synapsor-runner events tail` and `events webhook`: local lifecycle events
-  such as `proposal_created`, `proposal_approved`, `writeback_applied`, and
-  `writeback_conflict`.
+- [Handler Helper](handler-helper.md): TypeScript helper for safe app-owned
+  rich-write handlers.
 
-Useful examples:
+## 08 Replay And Audit
 
-- `examples/mcp-postgres-billing-app-handler/`: disposable Postgres app showing
-  guarded SQL writeback and app-owned account-credit execution side by side.
+- [Result Envelope v2](result-envelope-v2.md): stable
+  `ok`/`summary`/`data`/`proposal`/`error` MCP tool results.
+- [Store Lifecycle](store-lifecycle.md): active-store leases, prune safety,
+  deleted-store behavior, and concurrent server guardrails.
+- `synapsor-runner activity search`, `evidence`, `query-audit`, `receipts`,
+  `events tail`, and `events webhook`: local evidence, audit, receipt, replay,
+  and lifecycle inspection.
+- `examples/mysql-refund-agent/`: MySQL order/refund review example using the
+  same proposal, approval, guarded writeback, and replay loop.
+
+## 09 App-Owned Handlers
+
+- [Writeback Executors](writeback-executors.md): call direction, endpoint
+  contract, receipt shape, and the requirement to re-check tenant/scope,
+  expected version, idempotency, and allowed action inside your handler.
+- [Handler Helper](handler-helper.md): helper API and examples.
+
+## 10 Concepts
+
+- [Current Scope](current-scope.md): compact v0.1 scope summary.
+- [Current Limitations](limitations.md): intentional safety limits.
+- [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
+- [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
+  not included in this runner repo.
+- [Dependency License Inventory](dependency-license-inventory.md): current
+  dependency license summary for release review.
+- RFC source context:
+  [001 result envelope](rfcs/001-result-envelope-v2.md),
+  [002 handler helper](rfcs/002-app-owned-handler-helper.md),
+  [003 integrator teardown](rfcs/003-integrator-feedback-teardown.md).
 
-The public docs intentionally stay small. Historical implementation reports,
-release checklists, and internal planning notes are not part of the public
+The public docs intentionally stay task-first. Historical implementation
+reports, release checklists, and internal planning notes are not part of the
 getting-started path.

package/docs/release-notes.md

@@ -10,6 +10,27 @@ npx -y -p @synapsor/runner synapsor-runner demo --quick
 The OSS runner command is `synapsor-runner`. The `synapsor` command is reserved
 for the Synapsor Cloud CLI.
 
+## 0.1.1
+
+### OSS Launch Readiness
+
+- Reworked the README and packaged npm README so the first screen leads with
+  the `execute_sql` risk, the reviewed-business-action alternative, badges, and
+  the no-database quick demo.
+- Added the self-contained `examples/support-billing-agent/` flagship demo with
+  schema, seed data, reviewed contract, app-boundary note, one-command
+  `make demo`, and the exact support/billing model-facing tool list.
+- Added copy-paste example entry points for raw SQL vs Synapsor, Claude
+  Desktop, Cursor, OpenAI Agents SDK over Streamable HTTP and stdio, and MySQL
+  refund review.
+- Added agent-native repo guidance files and verified that an agent can create
+  an inspect/propose capability with the non-interactive CLI without reading
+  generated `dist/` files.
+- Restructured the docs index into a task-first path and added release-gate
+  repo hygiene assets.
+- Hardened package building so generated `.synapsor` local ledgers are not
+  included in npm examples.
+
 ## 0.1.0
 
 ### Stable Channel

package/examples/claude-desktop-postgres/Makefile

@@ -0,0 +1,6 @@
+.PHONY: config
+
+config:
+	cd ../.. && corepack pnpm runner mcp config claude-desktop \
+	  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
+	  --store ./.synapsor/local.db

package/examples/claude-desktop-postgres/README.md

@@ -0,0 +1,40 @@
+# Claude Desktop + Postgres
+
+This example prints a Claude Desktop MCP config for a reviewed Postgres-backed
+Synapsor Runner capability set.
+
+It uses the local `examples/mcp-postgres-billing/synapsor.runner.json` fixture.
+The config contains command paths and environment variable names only; it does
+not include database URLs or write credentials.
+
+## Run
+
+```bash
+make config
+```
+
+Expected output includes:
+
+```json
+{
+  "mcpServers": {
+    "synapsor": {
+      "command": "...",
+      "args": ["...", "mcp", "serve", "..."]
+    }
+  }
+}
+```
+
+Then paste the JSON into Claude Desktop's MCP settings and set these
+environment variables in the client environment:
+
+```bash
+export BILLING_POSTGRES_READ_URL="postgres://readonly:..."
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_billing_agent"
+```
+
+The model sees semantic tools such as `billing.inspect_invoice` and
+`billing.propose_late_fee_waiver`; it does not see raw SQL or approval/commit
+tools.

package/examples/cursor-postgres/Makefile

@@ -0,0 +1,6 @@
+.PHONY: config
+
+config:
+	cd ../.. && corepack pnpm runner mcp config cursor \
+	  --config ./examples/mcp-postgres-billing/synapsor.runner.json \
+	  --store ./.synapsor/local.db

package/examples/cursor-postgres/README.md

@@ -0,0 +1,30 @@
+# Cursor + Postgres
+
+This example prints a Cursor MCP config for a reviewed Postgres-backed Synapsor
+Runner capability set.
+
+It uses the local `examples/mcp-postgres-billing/synapsor.runner.json` fixture.
+The config contains command paths and environment variable names only; it does
+not include database URLs or write credentials.
+
+## Run
+
+```bash
+make config
+```
+
+Expected output includes a Cursor-compatible `mcpServers.synapsor` entry that
+launches:
+
+```text
+synapsor-runner mcp serve --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Set the database and trusted-context variables in the environment that launches
+Cursor:
+
+```bash
+export BILLING_POSTGRES_READ_URL="postgres://readonly:..."
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_billing_agent"
+```

package/examples/mysql-refund-agent/Makefile

@@ -0,0 +1,4 @@
+.PHONY: demo
+
+demo:
+	cd ../.. && corepack pnpm test:mcp-local

package/examples/mysql-refund-agent/README.md

@@ -0,0 +1,36 @@
+# MySQL Refund Agent
+
+This example points at the MySQL order/refund fixture and proves Synapsor
+Runner is not Postgres-only.
+
+The reviewed tools are:
+
+- `orders.inspect_order`
+- `orders.propose_refund_review`
+- `orders.propose_status_change`
+
+The refund proposal updates only review fields on one existing order. It does
+not issue money movement, call a payment provider, or expose a generic SQL
+tool.
+
+## Run
+
+```bash
+make demo
+```
+
+Expected output includes the shared local MCP smoke passing for the MySQL orders
+scenario:
+
+```text
+MySQL orders
+ACCEPT execute_sql approval and commit tools absent
+```
+
+The source database remains unchanged until a proposal is approved outside MCP
+and applied through guarded writeback.
+
+## Underlying Fixture
+
+This folder wraps `../mcp-mysql-orders/`, which contains the Docker compose
+file, seed SQL, and `synapsor.runner.json` contract.

package/examples/openai-agents-http/Makefile

@@ -0,0 +1,6 @@
+.PHONY: smoke
+
+smoke:
+	python3 -m py_compile agent.py
+	npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http --help >/dev/null
+	@printf '%s\n' "OpenAI Agents Streamable HTTP example smoke passed."

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

@@ -20,6 +20,20 @@ metadata and maps calls back to the canonical Synapsor capability.
 The model still sees a semantic action. It does not receive raw SQL, database
 URLs, write credentials, approval tools, or commit tools.
 
+## Smoke Check
+
+Run this without an OpenAI API key:
+
+```bash
+make smoke
+```
+
+Expected output:
+
+```text
+OpenAI Agents Streamable HTTP example smoke passed.
+```
+
 ## Terminal 1: Start Synapsor Runner HTTP MCP
 
 ```bash

package/examples/openai-agents-stdio/Makefile

@@ -0,0 +1,6 @@
+.PHONY: smoke
+
+smoke:
+	python3 -m py_compile agent.py
+	npx -y -p @synapsor/runner synapsor-runner mcp serve --help >/dev/null
+	@printf '%s\n' "OpenAI Agents stdio example smoke passed."

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

@@ -11,6 +11,20 @@ it. The model
 does not receive raw SQL, database URLs, write credentials, approval tools, or
 commit tools.
 
+## Smoke Check
+
+Run this without an OpenAI API key:
+
+```bash
+make smoke
+```
+
+Expected output:
+
+```text
+OpenAI Agents stdio example smoke passed.
+```
+
 ## Prerequisites
 
 Generate `synapsor.runner.json` first:

package/examples/raw-sql-vs-synapsor/Makefile

@@ -0,0 +1,11 @@
+.PHONY: demo
+
+demo:
+	@printf '%s\n' "Unsafe shortcut:"
+	@printf '%s\n' '  agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")'
+	@printf '%s\n' ""
+	@printf '%s\n' "Synapsor quick proof:"
+	npx -y @synapsor/runner demo --quick --no-interactive
+	@printf '%s\n' ""
+	@printf '%s\n' "Risk audit example:"
+	npx -y @synapsor/runner audit --example dangerous-db-mcp --format markdown

package/examples/raw-sql-vs-synapsor/README.md

@@ -0,0 +1,41 @@
+# Raw SQL vs Synapsor
+
+This minimal example shows the fear and the fix without requiring Docker, an
+agent SDK, or a database.
+
+## Run
+
+```bash
+make demo
+```
+
+Expected output includes:
+
+```text
+execute_sql
+Synapsor quick demo complete.
+proposal created
+source DB changed: no
+approval required outside MCP
+```
+
+The raw-SQL shortcut is:
+
+```text
+agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")
+```
+
+The Synapsor path is:
+
+```text
+agent -> billing.propose_late_fee_waiver(...)
+human approves outside MCP
+guarded writeback applies exactly one row
+replay records what happened
+```
+
+## Why This Exists
+
+Use this folder when you want to show the core idea quickly. It is not a full
+database fixture; the full support/billing walkthrough lives in
+`../support-billing-agent/`.

package/examples/support-billing-agent/Makefile

@@ -0,0 +1,19 @@
+.PHONY: demo unsafe clean
+
+demo:
+	cd ../.. && examples/support-billing-agent/scripts/run-demo.sh
+
+unsafe:
+	@printf '%s\n' "Unsafe raw-SQL shortcut this demo avoids:"
+	@printf '%s\n' ""
+	@printf '%s\n' '  agent -> execute_sql("UPDATE invoices SET late_fee_cents = 0 WHERE status = '\''overdue'\''")'
+	@printf '%s\n' ""
+	@printf '%s\n' "Why it is risky:"
+	@printf '%s\n' "  - the model controls SQL shape and scope"
+	@printf '%s\n' "  - tenant filters can be omitted or hallucinated"
+	@printf '%s\n' "  - there is no proposal, approval boundary, conflict receipt, or replay"
+	@printf '%s\n' ""
+	@printf '%s\n' "Run 'make demo' to see the Synapsor path: semantic tool -> proposal -> approval -> guarded writeback -> replay."
+
+clean:
+	docker compose down -v --remove-orphans

package/examples/support-billing-agent/README.md

@@ -0,0 +1,89 @@
+# Support/Billing Agent Demo
+
+This is the flagship Synapsor Runner demo.
+
+It uses a disposable Postgres support/billing app and shows the full loop:
+
+```text
+agent inspects scoped evidence
+-> agent creates a proposal
+-> source database is unchanged
+-> human approves outside MCP
+-> guarded writeback applies exactly one row
+-> replay shows evidence, diff, approval, receipt, and conflict behavior
+```
+
+## Run It
+
+From this folder:
+
+```bash
+make demo
+```
+
+Expected end state:
+
+```text
+Reference support/billing app smoke passed.
+```
+
+The model-facing tools are exactly:
+
+- `support.inspect_ticket`
+- `support.propose_plan_credit`
+- `billing.inspect_invoice`
+- `billing.propose_late_fee_waiver`
+
+The demo proves:
+
+- the model-facing tool list contains semantic capabilities such as
+  `billing.inspect_invoice` and `billing.propose_late_fee_waiver`;
+- the model does not receive `execute_sql`, approval tools, commit/apply tools,
+  database URLs, write credentials, arbitrary table names, arbitrary column
+  names, or tenant authority;
+- proposals do not mutate the source database;
+- approved writeback uses tenant, primary-key, allowed-column,
+  idempotency, and `updated_at` conflict guards;
+- replay contains the evidence and writeback receipt.
+
+## Compare The Unsafe Shortcut
+
+To see why the boundary matters:
+
+```bash
+make unsafe
+```
+
+That target prints the raw-SQL shape this demo avoids. It does not mutate the
+fixture; it shows the path an MCP client should not expose to the model:
+
+```text
+execute_sql("UPDATE invoices SET late_fee_cents = 0 ...")
+```
+
+Use `make demo` for the real proposal, approval, writeback, idempotent retry,
+stale-row conflict, and replay proof.
+
+## What This Wraps
+
+This folder is self-contained for readers and agents looking for the canonical
+support/billing demo. The smoke logic is shared with the reference fixture so
+the product-facing walkthrough and package tests exercise the same safety
+checks.
+
+Relevant files:
+
+- `db/schema.sql`
+- `db/seed.sql`
+- `synapsor.runner.json`
+- `scripts/run-demo.sh`
+- `app/README.md`
+
+## Stop And Clean Up
+
+The demo script cleans up its disposable Docker database automatically. If you
+interrupt it, run:
+
+```bash
+make clean
+```

package/examples/support-billing-agent/app/README.md

@@ -0,0 +1,13 @@
+# App Surface
+
+This folder marks the customer application boundary for the flagship demo.
+
+The model talks to Synapsor Runner MCP tools. It does not receive application
+write credentials or direct SQL authority. After approval, the trusted runner
+uses the reviewed `synapsor.runner.json` contract to apply the one-row
+writeback with tenant, primary-key, allowed-column, idempotency, and
+`updated_at` conflict guards.
+
+For richer app actions, such as inserting a credit ledger row and emitting an
+event, use the app-owned handler examples in `../app-owned-writeback/` and
+`../mcp-postgres-billing-app-handler/`.

package/examples/support-billing-agent/db/schema.sql

@@ -0,0 +1,91 @@
+CREATE TABLE IF NOT EXISTS public.tenants (
+  id text PRIMARY KEY,
+  name text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.customers (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  name text NOT NULL,
+  email text,
+  plan text NOT NULL,
+  plan_credit_cents integer NOT NULL DEFAULT 0,
+  credit_reason text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.support_tickets (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  subject text NOT NULL,
+  status text NOT NULL,
+  resolution_note text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.invoices (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  status text NOT NULL,
+  balance_cents integer NOT NULL,
+  late_fee_cents integer NOT NULL,
+  waiver_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.credits (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  invoice_id text REFERENCES public.invoices(id),
+  amount_cents integer NOT NULL,
+  reason text NOT NULL,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.agent_actions (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  action_type text NOT NULL,
+  target_type text NOT NULL,
+  target_id text NOT NULL,
+  proposal_id text,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.orders (
+  id text PRIMARY KEY,
+  tenant_id text NOT NULL REFERENCES public.tenants(id),
+  customer_id text NOT NULL REFERENCES public.customers(id),
+  status text NOT NULL,
+  status_change_reason text,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_reader') THEN
+    CREATE ROLE synapsor_reader LOGIN PASSWORD 'synapsor_reader_password';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'synapsor_writer') THEN
+    CREATE ROLE synapsor_writer LOGIN PASSWORD 'synapsor_writer_password';
+  END IF;
+END
+$$;
+
+GRANT CONNECT ON DATABASE synapsor_support_billing_agent TO synapsor_reader, synapsor_writer;
+GRANT USAGE ON SCHEMA public TO synapsor_reader, synapsor_writer;
+GRANT CREATE ON SCHEMA public TO synapsor_writer;
+GRANT SELECT ON public.tenants, public.customers, public.support_tickets, public.invoices, public.credits, public.agent_actions, public.orders TO synapsor_reader, synapsor_writer;
+GRANT UPDATE (plan_credit_cents, credit_reason, updated_at) ON public.customers TO synapsor_writer;
+GRANT UPDATE (status, resolution_note, updated_at) ON public.support_tickets TO synapsor_writer;
+GRANT UPDATE (late_fee_cents, waiver_reason, updated_at) ON public.invoices TO synapsor_writer;
+GRANT UPDATE (status, status_change_reason, updated_at) ON public.orders TO synapsor_writer;