@synapsor/runner 0.1.0-alpha.3 → 0.1.0-alpha.5

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 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:
@@ -128,10 +133,17 @@ In an interactive terminal, run the guided wizard:
 npx -y -p @synapsor/runner@alpha synapsor 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.
@@ -302,12 +315,31 @@ npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.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 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"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+
+npx -y -p @synapsor/runner@alpha synapsor 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
@@ -349,7 +381,7 @@ payload, not arbitrary model SQL:
 npx -y -p @synapsor/runner@alpha synapsor 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:
 

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 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 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 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.

package/docs/limitations.md

@@ -25,6 +25,8 @@ Synapsor Runner is intentionally narrow in the current alpha.
 - Capability recipes that generate reviewed starter configs.
 - Shadow-mode proposal-vs-human-action comparison.
 - Static MCP database risk review.
+- Local indexed search for proposals, evidence bundles, query audit, writeback
+  receipts, and proposal replay.
 
 ## Runtime Contract
 
@@ -61,6 +63,24 @@ External Postgres/MySQL databases are not branched or merged by Synapsor Runner.
 
 The proposal, evidence, replay, and approval state live in Synapsor Runner locally or in Synapsor Cloud. The external source database changes only when a trusted runner applies an approved writeback job.
 
+Local replay means replay of records captured by the runner:
+
+- trusted context values used by the capability;
+- captured/projected source-row excerpts;
+- query audit fingerprints and redacted parameter metadata;
+- proposal before/proposed diffs;
+- approval/rejection events;
+- guarded writeback jobs;
+- applied/conflict/failed receipts.
+
+It does not mean external Postgres/MySQL time travel. Runner cannot reconstruct
+arbitrary historical rows that were never captured as evidence, and it does not
+provide `AS OF` queries over an external source.
+
+Local search is single-node SQLite search over the local runner store. It is
+useful for local/dev/staging usage. It is not a hosted central evidence ledger,
+not cross-runner aggregation, not RBAC/SSO, and not compliance retention.
+
 Use this wording:
 
 ```text

package/docs/local-mode.md

@@ -9,6 +9,14 @@ Command model:
 - From a source checkout, use `./bin/synapsor <command>` if the global binary is
   not linked yet.
 
+`synapsor 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 mcp serve`, `synapsor demo`, or an own generated config is the real
+Postgres/MySQL path. Use `synapsor 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`;
@@ -17,13 +25,18 @@ Current local-mode foundation:
 - local localhost proposal review UI through `synapsor ui`;
 - static MCP database risk review with `synapsor 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.
 
 Still pending:
 
-- Public-release hardening around the experimental `node:sqlite` dependency.
+The alpha package requires Node >= 22.5.0 because the local evidence/replay
+ledger uses Node's `node:sqlite` runtime. The published package declares that
+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.
 
 ## Initialize a config
 
@@ -57,6 +70,31 @@ npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
 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 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 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:
@@ -164,6 +202,9 @@ 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
 ```
 
 Export replay:
@@ -172,9 +213,67 @@ Export replay:
 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 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 \
+  --tenant acme \
+  --object invoice:INV-3001 \
+  --store ./.synapsor/local.db
+
+synapsor 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
+```
+
+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
+external database read.
+
+This is local indexed search over the runner's SQLite ledger. It is not
+external Postgres/MySQL time travel, not native branching, and not a hosted
+cross-runner audit ledger.
+
+## Local store maintenance
+
+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
+```
+
+`store prune` defaults to dry-run. Use `--yes` only after reviewing the row
+counts it will remove.
 
 ## Boundary
 
@@ -184,7 +283,7 @@ Local mode does not expose `approve_proposal` or `commit_proposal` as model-call
 MCP tool call
   -> reviewed semantic proposal
   -> local store
-  -> human/policy approval outside the model
+  -> human/operator approval outside the model
   -> guarded worker writeback
   -> terminal receipt
   -> replay

package/docs/mcp-audit.md

@@ -41,13 +41,13 @@ 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 --json
+npx -y -p @synapsor/runner@alpha synapsor 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 --json
+npx -y -p @synapsor/runner@alpha synapsor audit https://mcp.example.com --bearer-env MCP_AUDIT_TOKEN --format json
 ```
 
 Stdio MCP server:
@@ -59,14 +59,20 @@ npx -y -p @synapsor/runner@alpha synapsor audit 'stdio:node ./server.mjs' --time
 JSON output:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor audit ./tools-list.json --json
+npx -y -p @synapsor/runner@alpha synapsor 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
 ```
 
 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 --json
+./bin/synapsor audit ./tools-list.json --format json
 ```
 
 ## Supported inputs

package/docs/mcp-client-setup.md

@@ -6,7 +6,10 @@ 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
@@ -24,6 +27,31 @@ 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 mcp serve` |
+| HTTP | Your app/server, Python agent, Node service, or container connects to a long-running Runner service | `synapsor 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 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:
@@ -77,6 +105,17 @@ npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./examples/mcp-post
 
 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 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

package/docs/security-boundary.md

@@ -3,6 +3,23 @@
 Synapsor Runner controls a narrow database path for MCP agents. It does not make
 MCP generally secure and it does not solve prompt injection.
 
+## Least-privilege database access
+
+Use a read-only database user, restricted views, row-level security, and staging
+data where appropriate. Synapsor Runner is not a replacement for database
+permissions.
+
+Database permissions protect the connection. Synapsor Runner shapes the
+model-facing interface: reviewed semantic capabilities, trusted context
+binding, evidence handles, query audit, local inspection, and proposal-first
+writes instead of model-facing commit authority.
+
+If all you need is restricted reads, database permissions are a good start.
+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. Proposal workflows add full replay across evidence,
+approval, writeback receipts, and events.
+
 The model-facing MCP server exposes reviewed semantic tools such as
 `billing.inspect_invoice` and `billing.propose_late_fee_waiver`.