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

package/docs/README.md

@@ -1,56 +1,34 @@
 # Synapsor Runner Docs
 
-Start with the practical paths, not the internals.
-
-## Try The Local Trust Loop
-
-```bash
-./scripts/try-synapsor.sh
-```
-
-This runs disposable Postgres/MySQL fixtures and proves the core loop:
-
-```text
-MCP tool call
--> trusted context
--> scoped read
--> evidence
--> proposal diff
--> approval outside MCP
--> guarded commit or stale-row conflict
--> receipt/replay
-```
-
-Read: [First 10 Minutes](first-10-minutes.md).
-
-## Use Your Own Staging Postgres/MySQL
-
-```bash
-export DATABASE_URL="<postgres-or-mysql-read-url>"
-./scripts/use-your-db.sh
-```
-
-This inspects your schema, opens the guided setup, generates
-`synapsor.runner.json`, previews the semantic MCP tools, and prints the
-`mcp serve` and local UI commands.
-
-For disposable dev RDS databases with local CA issues:
-
-```bash
-./scripts/use-your-db.sh --allow-insecure-ssl
-```
-
-Use certificate verification with the database CA bundle for real staging or
-production-like databases.
-
-Read: [Connect Your Own Database](getting-started-own-database.md).
-
-## Important References
-
-- [Schema Inspection](schema-inspection.md)
-- [MCP Client Setup](mcp-client-setup.md)
-- [Capability Config](capability-config.md)
-- [Local UI](local-ui.md)
-- [Writeback Executors](writeback-executors.md)
-- [Security Boundary](security-boundary.md)
-- [Current Scope And Limitations](limitations.md)
+Start with the README. Use these docs only when you need the next level of
+detail.
+
+## First Setup
+
+- [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.
+- [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
+  another stdio MCP client.
+- [HTTP MCP](http-mcp.md): run Synapsor Runner as an authenticated HTTP MCP
+  service for app/server agents.
+
+## Safety And Operations
+
+- [Security Boundary](security-boundary.md): what the model can and cannot see.
+- [Current Limitations](limitations.md): current alpha scope.
+- [Troubleshooting First Run](troubleshooting-first-run.md): common setup
+  failures and fixes.
+- [Local Mode](local-mode.md): local store, proposals, approval, replay, and
+  writeback flow.
+
+## 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.
+
+The public docs intentionally stay small. Historical implementation reports,
+release checklists, and internal planning notes are not part of the public
+getting-started path.

package/docs/getting-started-own-database.md

@@ -7,6 +7,11 @@ Do not start with your most sensitive production database. The current alpha
 runner is a local commit-safety runtime for reviewed single-row business
 actions, not a production certification.
 
+If you only ran `synapsor-runner demo --quick`, you have tested the fixture-only
+teaching path and local ledger commands. This page is the real own-database
+path: it inspects your Postgres/MySQL metadata and generates reviewed semantic
+tools from your selections.
+
 ## Fast path
 
 Set one read-only database URL and run the wrapper from this repo:
@@ -33,7 +38,7 @@ It does not print your database URL, put the URL in MCP client config, expose
 credentials.
 
 The rest of this page shows the same flow step by step using the public
-`synapsor ...` CLI. From a source checkout, use `./bin/synapsor ...` if the
+`synapsor-runner ...` CLI. From a source checkout, use `./bin/synapsor-runner ...` if the
 global binary is not linked yet.
 
 ## 1. Put the read URL in an environment variable
@@ -76,7 +81,7 @@ other trusted database TLS setup.
 ## 2. Inspect metadata
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor inspect \
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
   --engine auto \
   --from-env DATABASE_URL \
   --schema public
@@ -85,13 +90,13 @@ npx -y -p @synapsor/runner@alpha synapsor inspect \
 For a disposable staging URL, this also works:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor inspect "$DATABASE_URL" --engine auto --schema public
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
 ```
 
 For automation:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor inspect \
+npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
   --engine postgres \
   --from-env DATABASE_URL \
   --schema public \
@@ -108,9 +113,9 @@ to your staging table, primary key, tenant key, conflict column, visible fields,
 allowed write fields, and business limits.
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor recipes list
-npx -y -p @synapsor/runner@alpha synapsor recipes show billing.late_fee_waiver
-npx -y -p @synapsor/runner@alpha synapsor recipes init billing.late_fee_waiver --output synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes list
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes show billing.late_fee_waiver
+npx -y -p @synapsor/runner@alpha synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
 ```
 
 Use a recipe when the shape is close. Use the guided wizard or explicit flags
@@ -125,13 +130,20 @@ only the capabilities in your generated `synapsor.runner.json`.
 In an interactive terminal, run the guided wizard:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init --from-env DATABASE_URL --mode read_only --wizard
+npx -y -p @synapsor/runner@alpha synapsor-runner init --from-env DATABASE_URL --mode read_only --wizard
 ```
 
-The generated capabilities are based on your selections. Synapsor Runner does
-not force billing, support, order, or any other built-in domain. You choose the
-namespace, object name, lookup argument, visible fields, proposal fields, guards,
-and approval role.
+The generated context and capabilities are based on your selections. Synapsor
+Runner does not force billing, support, order, or any other built-in domain.
+The local shape is:
+
+```text
+trusted context -> capability -> MCP tool
+```
+
+You choose the source object, trusted tenant/principal bindings, namespace,
+object name, lookup argument, visible fields, proposal fields, guards, and
+approval role.
 
 Start with `read_only` to prove safe database reads first. Use `--mode review`
 when you are ready to create proposal tools and guarded writeback setup.
@@ -141,9 +153,10 @@ The wizard:
 - asks for the engine and read URL environment-variable name;
 - tests read connectivity through schema inspection;
 - lists discovered schemas and tables/views;
-- asks you to confirm primary key, tenant/scope column, conflict/version
-  column, visible columns, mode, semantic names, trusted context env vars, and
-  proposal patch mappings;
+- asks which source object backs the local context;
+- asks which tenant/scope column and backend session env vars are trusted;
+- asks you to confirm primary key, conflict/version column, visible columns,
+  mode, semantic capability names, and proposal patch mappings;
 - previews the MCP tools and what is not exposed;
 - writes the generated config, `.env.example`, and MCP client snippets only
   after final confirmation.
@@ -161,7 +174,7 @@ If you already know the reviewed table/action, generate config directly from
 metadata and explicit flags:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init \
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
   --from-env DATABASE_URL \
   --engine postgres \
   --schema public \
@@ -180,7 +193,7 @@ npx -y -p @synapsor/runner@alpha synapsor init \
 Or generate from a saved inspection snapshot without reconnecting:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init \
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
   --inspection-json schema-inspection.json \
   --table invoices \
   --namespace billing \
@@ -248,7 +261,7 @@ contain database URLs or passwords.
 ## 6. Generate runner files
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor init \
+npx -y -p @synapsor/runner@alpha synapsor-runner init \
   --spec onboarding-selection.json \
   --non-interactive
 ```
@@ -268,10 +281,10 @@ files.
 Generate or refresh MCP client snippets later with:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 The snippets contain the local command and args. They must not contain database
@@ -280,8 +293,8 @@ URLs, passwords, approval tools, commit tools, or write credentials.
 ## 7. Validate the config
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor config validate --config synapsor.runner.json
-npx -y -p @synapsor/runner@alpha synapsor config show --config synapsor.runner.json --redacted
+npx -y -p @synapsor/runner@alpha synapsor-runner config validate --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor-runner config show --config synapsor.runner.json --redacted
 ```
 
 The config stores environment-variable names, not connection-string values.
@@ -289,7 +302,7 @@ The config stores environment-variable names, not connection-string values.
 Run doctor after setting the referenced environment variables:
 
 ```bash
-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
 ```
 
 Doctor validates config shape, trusted context env vars, source env vars,
@@ -297,17 +310,36 @@ read/write credential separation, table/column metadata when the read URL is
 available, and the semantic MCP tool boundary. Use JSON for automation:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json --json
+npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config synapsor.runner.json --json
 ```
 
 ## 8. Serve semantic MCP tools
 
+Use stdio when a local MCP client can launch Synapsor Runner:
+
+```bash
+export SYNAPSOR_TENANT_ID="acme"
+export SYNAPSOR_PRINCIPAL="local_operator"
+npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Use HTTP when an app/server agent connects to a long-running Runner process:
+
 ```bash
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
-npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+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` and requires bearer auth by default. Use
+private networking/TLS before exposing it beyond localhost. See
+[HTTP MCP](http-mcp.md).
+
 The model-facing MCP server exposes semantic tools such as:
 
 ```text
@@ -325,10 +357,10 @@ tools, commit tools, database URLs, write credentials, or tenant authority.
 Proposal tools leave the source database unchanged. Review locally:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor proposals list --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor proposals show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
-npx -y -p @synapsor/runner@alpha synapsor proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals list --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
+npx -y -p @synapsor/runner@alpha synapsor-runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
 ```
 
 Apply through the trusted worker path with a separate writer credential:
@@ -337,7 +369,7 @@ Apply through the trusted worker path with a separate writer credential:
 export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-write-url>"
 SYNAPSOR_ENGINE=postgres \
 SYNAPSOR_DATABASE_URL="$SYNAPSOR_DATABASE_WRITE_URL" \
-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
 ```
 
 If your application/API should own the business write, use an `http_handler`
@@ -346,16 +378,16 @@ from environment variables, and the handler receives a structured proposal/job
 payload, not arbitrary model SQL:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
-See `docs/writeback-executors.md`.
+See [Writeback Executors](writeback-executors.md).
 
 Replay afterward:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor replay show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner@alpha synapsor replay export wrp_123 --store ./.synapsor/local.db --output replay.json
+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 export wrp_123 --store ./.synapsor/local.db --output replay.json
 ```
 
 ## Boundary

package/docs/http-mcp.md

@@ -0,0 +1,200 @@
+# HTTP MCP
+
+Use HTTP MCP when an app, server-side agent, container, or Python/Node process
+needs to connect to a long-running Synapsor Runner service.
+
+Use stdio MCP when a local MCP client such as Claude Desktop, Cursor, or a
+local agent tool can launch Synapsor Runner directly.
+
+## Start The HTTP Server
+
+```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+synapsor-runner mcp serve-http \
+  --host 127.0.0.1 \
+  --port 8765 \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
+Defaults:
+
+```text
+host: 127.0.0.1
+port: 8765
+auth: bearer token required
+cors: disabled
+```
+
+Startup output prints the URL, config path, store path, and token environment
+variable name. It does not print token values or database URLs.
+
+## Health Check
+
+```bash
+curl -i http://127.0.0.1:8765/healthz
+```
+
+The health endpoint is secret-free:
+
+```json
+{
+  "ok": true,
+  "transport": "http",
+  "tools": 1,
+  "mode": "read_only"
+}
+```
+
+## List Tools
+
+Unauthorized requests fail:
+
+```bash
+curl -i \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
+  http://127.0.0.1:8765/mcp
+```
+
+Authorized requests include the bearer token:
+
+```bash
+curl -i \
+  -H "Authorization: Bearer dev-local-token" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
+  http://127.0.0.1:8765/mcp
+```
+
+The tool catalog should contain semantic tools such as:
+
+```text
+billing.inspect_invoice
+billing.propose_late_fee_waiver
+```
+
+It should not contain:
+
+```text
+execute_sql
+raw_sql
+approval tools
+commit/apply tools
+database URLs
+write credentials
+model-controlled tenant authority
+arbitrary table or column names
+```
+
+## Call A Tool
+
+```bash
+curl -i \
+  -H "Authorization: Bearer dev-local-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+      "name": "billing.inspect_invoice",
+      "arguments": { "invoice_id": "INV-3001" }
+    }
+  }' \
+  http://127.0.0.1:8765/mcp
+```
+
+The response includes scoped data, trusted context, evidence handles, and
+`source_database_mutated: false`. The agent still does not receive SQL,
+database credentials, or approval/commit authority.
+
+## Read Evidence Or Replay Resources
+
+Use `resources/read` with a `synapsor://...` handle returned by a tool call:
+
+```bash
+curl -i \
+  -H "Authorization: Bearer dev-local-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "resources/read",
+    "params": { "uri": "synapsor://evidence/ev_..." }
+  }' \
+  http://127.0.0.1:8765/mcp
+```
+
+## CORS
+
+CORS is disabled by default. If a local browser app needs access during
+development, allow one explicit origin:
+
+```bash
+synapsor-runner mcp serve-http \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db \
+  --cors-origin http://localhost:3000
+```
+
+Do not use wildcard CORS for a model-facing database tool service.
+
+## Network Exposure
+
+Synapsor Runner binds to `127.0.0.1` by default.
+
+If you explicitly bind to all interfaces:
+
+```bash
+synapsor-runner mcp serve-http --host 0.0.0.0
+```
+
+the CLI prints a warning. Treat this as a production-like service:
+
+- keep bearer auth enabled;
+- use TLS or a trusted reverse proxy;
+- prefer private networking;
+- add rate limits and request-size limits at the edge;
+- do not log request bodies by default;
+- rotate the bearer token if it is exposed.
+
+`--dev-no-auth` is accepted only on `localhost` or `127.0.0.1`. It fails closed
+with `--host 0.0.0.0`.
+
+## Trusted Context
+
+Tenant and principal values must come from trusted configuration such as
+environment variables or a server-side session. HTTP request arguments cannot
+override trusted fields such as:
+
+```text
+tenant_id
+principal
+principal_id
+project_id
+source_id
+allowed_columns
+approval_identity
+```
+
+Use `read_only` mode first. Proposal/review mode should use a separate trusted
+write path and a separate write credential. The model-facing HTTP MCP endpoint
+must not receive write credentials.
+
+## OpenAI Agents SDK
+
+See:
+
+```text
+examples/openai-agents-http/
+examples/openai-agents-stdio/
+```
+
+The stdio example uses the MCP client integration from the OpenAI Agents SDK
+when available. The HTTP example uses a minimal JSON-RPC client wrapped as an
+OpenAI function tool because native HTTP MCP client support can vary by SDK
+version. The boundary is the same: the agent calls a semantic Synapsor tool,
+not raw SQL.