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

package/docs/MCP_RUNNER_IMPLEMENTATION_PLAN.md

@@ -152,7 +152,7 @@ This plan maps the existing open-source runner repository to the commit-safe dat
 ## Release blockers
 
 - Live hosted Cloud-linked E2E still requires a compatible Synapsor Cloud workspace, adapter, and scoped runner token. A local hosted-compatible Cloud-linked smoke now covers the protocol/API lifecycle against a mock Cloud API and real disposable Postgres writeback.
-- `packages/proposal-store` currently uses Node 22 `node:sqlite`, which is still marked experimental by Node. Before a public runner release, either pin/support that runtime explicitly or replace it with a stable SQLite dependency.
+- `packages/proposal-store` uses Node 22 `node:sqlite`. The alpha package pins Node >= 22.5.0 in `engines` and the package/source wrappers fail early with a clear message on older Node versions. Replacing this with a broader-LTS SQLite dependency remains a future compatibility option.
 - Release docs present: `LICENSE` is Apache License 2.0, and `CONTRIBUTING.md` / `CODE_OF_CONDUCT.md` exist with project-specific safety guidance.
 
 ## Verification log

package/docs/cloud-mode.md

@@ -53,7 +53,7 @@ Cloud mode uses the same MCP server command with a `mode: "cloud"` config:
     "base_url_env": "SYNAPSOR_CLOUD_BASE_URL",
     "runner_token_env": "SYNAPSOR_RUNNER_TOKEN",
     "runner_id": "synapsor_runner_local",
-    "runner_version": "0.1.0-alpha.2",
+    "runner_version": "0.1.0-alpha.4",
     "project_id": "token_scope",
     "adapter_id": "mcp.your_adapter",
     "source_id": "src_replace_me",
@@ -71,7 +71,7 @@ Run:
 ```bash
 SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai" \
 SYNAPSOR_RUNNER_TOKEN="syn_wbr_..." \
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve --config ./synapsor.cloud.json
+npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./synapsor.cloud.json
 ```
 
 Validate the Cloud runner token and source scope before serving tools:
@@ -79,7 +79,7 @@ Validate the Cloud runner token and source scope before serving tools:
 ```bash
 SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai" \
 SYNAPSOR_RUNNER_TOKEN="syn_wbr_..." \
-npx -y -p @synapsor/runner@alpha synapsor-runner cloud connect --config ./synapsor.cloud.json
+npx -y -p @synapsor/runner@alpha synapsor cloud connect --config ./synapsor.cloud.json
 ```
 
 `cloud connect` verifies the runner token, registers the runner id/version, sends engine/capability/source metadata, and posts an initial heartbeat. It does not send Postgres/MySQL URLs, passwords, write credentials, prompts, or table data. The `project_id` field may be the literal `token_scope` because Synapsor Cloud validates the real project/source from the scoped runner token.

package/docs/config-migrations.md

@@ -29,7 +29,7 @@ validation.
 Because version 1 is the only supported schema today, migration is conservative:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner config migrate --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor config migrate --config synapsor.runner.json
 ```
 
 prints that the config is already current and writes nothing.
@@ -37,7 +37,7 @@ prints that the config is already current and writes nothing.
 To write a normalized copy:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner config migrate \
+npx -y -p @synapsor/runner@alpha synapsor config migrate \
   --config synapsor.runner.json \
   --output migrated.json \
   --yes
@@ -47,7 +47,7 @@ To rewrite in place, the command requires an explicit write and creates a
 timestamped backup:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner config migrate \
+npx -y -p @synapsor/runner@alpha synapsor config migrate \
   --config synapsor.runner.json \
   --write \
   --yes

package/docs/demo-transcript.md

@@ -1,73 +1,161 @@
-# First-Run Demo Transcript
+# Demo Transcript
 
-This is the expected high-level transcript for:
+This transcript shows the intended public demo path. Exact timestamps, hashes,
+ports, and generated proposal ids vary.
+
+## Quick demo
 
 ```bash
-./scripts/try-synapsor.sh
+npx -y -p @synapsor/runner@alpha synapsor demo --quick
 ```
 
-Exact timings and log paths vary.
+The local-ledger fixture output below requires this checkout or package version
+`0.1.0-alpha.4` or newer.
+
+Expected shape:
 
 ```text
-Synapsor Runner first-run demo
+Synapsor Runner quick demo
 
-You are about to see an MCP agent propose a database change without receiving SQL or write credentials.
-Full logs will be written to: ./.synapsor/logs/try-synapsor-<timestamp>.log
+This is a fixture-only first look. It does not start Docker, connect a database,
+or require an MCP client. It writes an inspectable local ledger fixture to:
+./.synapsor/quick-demo.db
 
-Step 1: MCP tools exposed
-  In this fixture, the model sees semantic tools such as billing.inspect_invoice and billing.propose_late_fee_waiver.
+Raw MCP shape:
+execute_sql(sql: string)
+Risk: the model can write arbitrary SQL with database authority.
 
-Step 2: Agent inspects business object
-Step 3: Agent proposes change
-Step 4: Source DB changed: No
-Step 5: Human approval outside MCP
-Step 6: Trusted runner applies guarded writeback
-Step 7: Replay explains what happened
-Step 8: Extra safety checks catch stale rows and unsafe tools
+Synapsor shape:
+billing.inspect_invoice(invoice_id)
+billing.propose_late_fee_waiver(invoice_id, reason)
 
-Running the disposable Docker proof. This can take a few minutes...
+Agent requested:
+billing.propose_late_fee_waiver(invoice_id="INV-3001", reason="approved support waiver")
 
-Success. You saw the Synapsor commit boundary.
+Trusted context:
+tenant_id = acme
+principal = support.agent
 
-In the included fixture, the model got:
-* billing.inspect_invoice
-* billing.propose_late_fee_waiver
+Proposal:
+invoice.late_fee_cents: 5500 -> 0
 
-The model did not get:
-* execute_sql
-* write credentials
-* approve/commit tools
+Source DB changed:
+no
 
-Next:
+Approval:
+required outside MCP
+
+Replay:
+replay_wrp_quick_INV_3001 captures the local proposal, evidence handle, query audit, and events.
+```
 
-1. Open proposal UI:
-   npx -y -p @synapsor/runner@alpha synapsor-runner ui --tour --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+Inspect the fixture:
+
+```bash
+synapsor proposals show latest --store ./.synapsor/quick-demo.db
+synapsor activity search --object invoice:INV-3001 --store ./.synapsor/quick-demo.db
+synapsor replay show latest --store ./.synapsor/quick-demo.db
+```
 
-2. Run the reference app:
-   corepack pnpm demo:reference
+## Full Docker-backed demo
 
-3. Generate MCP client config:
-   npx -y -p @synapsor/runner@alpha synapsor-runner mcp config --absolute-paths --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+Start the disposable local Postgres demo:
 
-4. Use your own staging Postgres/MySQL:
-   export DATABASE_URL='<postgres-or-mysql-read-url>'
-   npx -y -p @synapsor/runner@alpha synapsor-runner inspect --from-env DATABASE_URL
-   npx -y -p @synapsor/runner@alpha synapsor-runner init --wizard --from-env DATABASE_URL
+```bash
+synapsor demo
 ```
 
-The full log should include the lower-level proof:
-
-- local MCP Postgres example passed;
-- local MCP MySQL example passed;
-- `ACCEPT semantic tools present`;
-- `ACCEPT execute_sql approval and commit tools absent`;
-- `ACCEPT proposal created successfully`;
-- `ACCEPT source row unchanged after proposal`;
-- `ACCEPT approval happened outside MCP`;
-- `ACCEPT guarded writeback applied`;
-- retry was idempotent;
-- `ACCEPT stale-row conflict detected`;
-- `ACCEPT replay export contains applied receipt`.
-
-The first-run script fails if the log appears to contain database URLs,
-fixture passwords, or bearer tokens.
+Expected shape:
+
+```text
+Synapsor Runner demo
+
+Raw database MCP tools can hand the model SQL and write authority.
+Synapsor Runner exposes semantic capabilities instead:
+  billing.inspect_invoice
+  billing.propose_late_fee_waiver
+
+Demo flow:
+proposal first -> source unchanged -> approval outside MCP -> guarded writeback -> replay
+
+Starting disposable Postgres fixture...
+Synapsor Runner demo is ready.
+```
+
+Create the proposal the MCP tool would create:
+
+```bash
+synapsor propose billing.propose_late_fee_waiver --sample
+```
+
+Expected shape:
+
+```text
+Proposal created
+Capability: billing.propose_late_fee_waiver
+Proposal: wrp_...
+Status: review_required
+Source database changed: no
+```
+
+Review and approve outside MCP:
+
+```bash
+synapsor proposals show latest
+synapsor proposals approve latest --yes
+```
+
+Apply through guarded writeback:
+
+```bash
+synapsor apply latest
+```
+
+Expected shape:
+
+```text
+Guarded writeback applied.
+Proposal: wrp_...
+Status: applied
+Rows affected: 1
+Source database mutated: yes
+```
+
+Search by business object:
+
+```bash
+synapsor activity search --object invoice:INV-3001
+```
+
+Expected shape:
+
+```text
+Found local interactions
+
+kind: proposal
+capability: billing.propose_late_fee_waiver
+object: invoice:INV-3001
+proposal: wrp_...
+evidence: ev_...
+status: applied
+replay: replay_wrp_...
+```
+
+Export a copy-pasteable review artifact:
+
+```bash
+synapsor replay export --proposal wrp_... --format markdown --output replay.md
+```
+
+The Markdown includes:
+
+- what the agent requested;
+- trusted tenant/principal context;
+- captured evidence and query audit;
+- exact proposed diff;
+- approval event;
+- guarded writeback receipt;
+- replay note explaining this is local captured interaction replay, not
+  external database time travel.
+
+The full demo should show the happy path before the stale-row conflict path.

package/docs/first-10-minutes.md

@@ -1,7 +1,32 @@
 # First 10 Minutes
 
-This path is for a developer who cloned Synapsor Runner and wants to understand
-the product without reading the full docs first.
+This path is for a developer who wants to understand Synapsor Runner without
+reading the full docs first.
+
+## Fastest First Look
+
+If you only want the 15-second value proof and have Node >= 22.5.0:
+
+```bash
+npx -y -p @synapsor/runner@alpha synapsor demo --quick
+```
+
+The local-ledger quick fixture requires this checkout or package version
+`0.1.0-alpha.4` or newer. If `npm view @synapsor/runner@alpha version` reports
+an older alpha, run `./bin/synapsor demo --quick` from this checkout until the
+next alpha is published.
+
+That command does not require Docker, a database, a config file, an MCP client,
+or a Synapsor Cloud account. It seeds `./.synapsor/quick-demo.db` with a local
+proposal/evidence/replay fixture you can inspect:
+
+```bash
+synapsor activity search --object invoice:INV-3001 --store ./.synapsor/quick-demo.db
+synapsor replay show latest --store ./.synapsor/quick-demo.db
+```
+
+Use the Docker-backed path below when you want the full disposable
+Postgres/MySQL proof with guarded writeback.
 
 ## What You Need
 
@@ -70,7 +95,7 @@ authority.
 ## Next Command 1: Open The Local UI
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner ui --tour \
+npx -y -p @synapsor/runner@alpha synapsor ui --tour \
   --config ./examples/mcp-postgres-billing/synapsor.runner.json \
   --store ./.synapsor/local.db
 ```
@@ -97,7 +122,7 @@ The reference app uses a disposable support/billing Postgres database and proves
 ## Next Command 3: Generate MCP Client Config
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner mcp config claude-desktop \
+npx -y -p @synapsor/runner@alpha synapsor mcp config claude-desktop \
   --absolute-paths \
   --config ./examples/mcp-postgres-billing/synapsor.runner.json \
   --store ./.synapsor/local.db
@@ -110,7 +135,7 @@ tools, commit tools, or write credentials.
 Verify the configured tool boundary with:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner tools preview \
+npx -y -p @synapsor/runner@alpha synapsor tools preview \
   --config ./examples/mcp-postgres-billing/synapsor.runner.json \
   --store ./.synapsor/local.db
 ```

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

@@ -76,7 +76,7 @@ other trusted database TLS setup.
 ## 2. Inspect metadata
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+npx -y -p @synapsor/runner@alpha synapsor inspect \
   --engine auto \
   --from-env DATABASE_URL \
   --schema public
@@ -85,13 +85,13 @@ npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
 For a disposable staging URL, this also works:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
+npx -y -p @synapsor/runner@alpha synapsor inspect "$DATABASE_URL" --engine auto --schema public
 ```
 
 For automation:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner inspect \
+npx -y -p @synapsor/runner@alpha synapsor inspect \
   --engine postgres \
   --from-env DATABASE_URL \
   --schema public \
@@ -108,9 +108,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-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
+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
 ```
 
 Use a recipe when the shape is close. Use the guided wizard or explicit flags
@@ -125,7 +125,7 @@ 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-runner init --from-env DATABASE_URL --mode read_only --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
@@ -161,7 +161,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-runner init \
+npx -y -p @synapsor/runner@alpha synapsor init \
   --from-env DATABASE_URL \
   --engine postgres \
   --schema public \
@@ -180,7 +180,7 @@ npx -y -p @synapsor/runner@alpha synapsor-runner init \
 Or generate from a saved inspection snapshot without reconnecting:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init \
+npx -y -p @synapsor/runner@alpha synapsor init \
   --inspection-json schema-inspection.json \
   --table invoices \
   --namespace billing \
@@ -248,7 +248,7 @@ contain database URLs or passwords.
 ## 6. Generate runner files
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner init \
+npx -y -p @synapsor/runner@alpha synapsor init \
   --spec onboarding-selection.json \
   --non-interactive
 ```
@@ -268,10 +268,10 @@ files.
 Generate or refresh MCP client snippets later with:
 
 ```bash
-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
+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
 ```
 
 The snippets contain the local command and args. They must not contain database
@@ -280,8 +280,8 @@ URLs, passwords, approval tools, commit tools, or write credentials.
 ## 7. Validate the config
 
 ```bash
-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
+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
 ```
 
 The config stores environment-variable names, not connection-string values.
@@ -289,7 +289,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-runner doctor --config synapsor.runner.json
+npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json
 ```
 
 Doctor validates config shape, trusted context env vars, source env vars,
@@ -297,7 +297,7 @@ 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-runner doctor --config synapsor.runner.json --json
+npx -y -p @synapsor/runner@alpha synapsor doctor --config synapsor.runner.json --json
 ```
 
 ## 8. Serve semantic MCP tools
@@ -305,7 +305,7 @@ npx -y -p @synapsor/runner@alpha synapsor-runner doctor --config 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
+npx -y -p @synapsor/runner@alpha synapsor mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 The model-facing MCP server exposes semantic tools such as:
@@ -325,10 +325,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-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
+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
 ```
 
 Apply through the trusted worker path with a separate writer credential:
@@ -337,7 +337,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-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor 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,7 +346,7 @@ from environment variables, and the handler receives a structured proposal/job
 payload, not arbitrary model SQL:
 
 ```bash
-npx -y -p @synapsor/runner@alpha synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner@alpha synapsor apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 See `docs/writeback-executors.md`.
@@ -354,8 +354,8 @@ See `docs/writeback-executors.md`.
 Replay afterward:
 
 ```bash
-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
+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
 ```
 
 ## Boundary

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