@synapsor/runner 1.6.3 → 1.6.5

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

@@ -14,25 +14,23 @@ review artifacts without sampling source rows or using an LLM.
 
 ## Fast path
 
-Set a dedicated SELECT-only, non-owner database URL plus trusted development
-scope and run the public guided path:
+Run the public guided path:
 
 ```bash
-export DATABASE_URL="<postgres-or-mysql-read-url>"
-export SYNAPSOR_TENANT_ID="<staging-tenant>"
-export SYNAPSOR_PRINCIPAL="<developer-id>"
-npx -y @synapsor/runner@latest start --from-env DATABASE_URL
+npx -y @synapsor/runner start
 ```
 
-A fresh interactive project with no existing config, selector, or automation
-input follows:
+Paste a dedicated SELECT-only, non-owner URL into the hidden prompt, explicitly
+approve a regular project `.env` file for this process, or export
+`DATABASE_URL`. A fresh interactive project with no existing config, selector,
+or automation input follows:
 
 ```text
 inspect the whole selected schema and structured application artifacts
 -> draft disabled public DSL, canonical JSON, tests, and generation lock
 -> review scope, fields, analytics permissions, relationships, and budgets
 -> activate the exact exploration-boundary digest in local Workbench
--> install exactly app.describe_data and app.explore_data in Cursor
+-> install exactly app.describe_data and app.explore_data in your project MCP client
 -> ask a bounded row or PM-style aggregate question against staging
 -> Protect This Query into a disabled named capability
 -> activate that exact digest and remove broad Explore
@@ -43,7 +41,9 @@ It does not print your database URL, put the URL in MCP client config, expose
 `execute_sql`, expose approval/commit tools, or give the model write
 credentials. Before boundary activation it does not read source rows.
 
-`start --from-env` is the shortest public command for first-run onboarding.
+`start` is the shortest public command for first-run onboarding. When
+`DATABASE_URL` is already exported, Runner uses it automatically. Explicit
+`--from-env`, `--schema`, and `--project-root` values always win.
 Read [Database To First Safe Tool](guided-onboarding.md) for the timed guided
 journey and [Auto Boundary, Scoped Explore, And
 Protect](auto-boundary-and-scoped-explore.md) for the complete security
@@ -104,7 +104,7 @@ before using staging or production-like data.
 ## 2. Inspect metadata
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner inspect \
+npx -y @synapsor/runner inspect \
   --engine auto \
   --from-env DATABASE_URL \
   --schema public
@@ -113,13 +113,13 @@ npx -y -p @synapsor/runner synapsor-runner inspect \
 For a disposable staging URL, this also works:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
+npx -y @synapsor/runner inspect "$DATABASE_URL" --engine auto --schema public
 ```
 
 For automation:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner inspect \
+npx -y @synapsor/runner inspect \
   --engine postgres \
   --from-env DATABASE_URL \
   --schema public \
@@ -136,9 +136,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 synapsor-runner recipes list
-npx -y -p @synapsor/runner synapsor-runner recipes show billing.late_fee_waiver
-npx -y -p @synapsor/runner synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+npx -y @synapsor/runner recipes list
+npx -y @synapsor/runner recipes show billing.late_fee_waiver
+npx -y @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
@@ -153,7 +153,7 @@ only the capabilities in your generated `synapsor.runner.json`.
 In an interactive terminal, run the guided wizard:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init --from-env DATABASE_URL --mode read_only --wizard
+npx -y @synapsor/runner init --from-env DATABASE_URL --mode read_only --wizard
 ```
 
 The generated context and capabilities are based on your selections. Synapsor
@@ -241,32 +241,34 @@ There is intentionally no CLI or MCP command a coding agent can use to
 activate the draft. If the host does not refresh `tools/list`, reconnect the
 MCP server after activation as the Workbench instructs.
 
-## 5. Add the reviewed tools to Cursor
+## 5. Add the reviewed tools to your MCP client
 
-After setting trusted environment values, preview and install a project-scoped
-entry without hand-editing `.cursor/mcp.json`:
+After setting trusted environment values, choose Cursor, Claude Code, or VS
+Code and preview a project-scoped entry without hand-editing client JSON:
 
 ```bash
-synapsor-runner mcp install cursor --project --dry-run \
+synapsor-runner mcp install claude-code --project --dry-run \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
-synapsor-runner mcp install cursor --project --yes \
+synapsor-runner mcp install claude-code --project --yes \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
-synapsor-runner mcp status cursor --project --check-launch
+synapsor-runner mcp status claude-code --project --check-launch
 ```
 
+Use `cursor` or `vscode` in place of `claude-code` for those clients. Runner
+targets `.cursor/mcp.json`, `.mcp.json`, or `.vscode/mcp.json` as appropriate.
 Runner merges rather than replaces existing MCP servers, creates a backup,
 records an integrity marker, and is idempotent. The entry uses an exact Runner
 version and contains no database URL, trusted tenant/principal value, approval,
 apply, or revert authority. Remove only the Runner-owned entry with:
 
 ```bash
-synapsor-runner mcp uninstall cursor --project --yes
+synapsor-runner mcp uninstall claude-code --project --yes
 ```
 
 See the [host compatibility matrix](host-compatibility.md) for the precise
-Cursor evidence and MCP Apps limitation.
+host evidence and MCP Apps limitations.
 
 ## 6. Inspect local activation evidence
 
@@ -298,7 +300,7 @@ If you already know the reviewed table/action, generate config directly from
 metadata and explicit flags:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --from-env DATABASE_URL \
   --engine postgres \
   --schema public \
@@ -322,7 +324,7 @@ when you want exact capability names in the generated contract.
 For app-owned writeback, replace the direct writer env with a handler executor:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --from-env DATABASE_URL \
   --engine postgres \
   --schema public \
@@ -351,7 +353,7 @@ source primary/unique dedup key; DELETE requires an exact conflict guard and
 safe cascade/trigger inspection:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner onboard db \
+npx -y @synapsor/runner onboard db \
   --from-env DATABASE_URL \
   --table account_credits \
   --mode review \
@@ -370,7 +372,7 @@ but ambiguous post-commit crashes stop for operator reconciliation.
 Or generate from a saved inspection snapshot without reconnecting:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --inspection-json schema-inspection.json \
   --table invoices \
   --namespace billing \
@@ -440,7 +442,7 @@ contain database URLs or passwords.
 ## 6. Generate runner files
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --spec onboarding-selection.json \
   --non-interactive
 ```
@@ -460,16 +462,16 @@ files.
 Generate or refresh MCP client snippets later with:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 Call one generated tool locally before wiring an MCP client:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 `smoke call` uses the same runtime as the MCP server. It records evidence and
@@ -489,8 +491,8 @@ URLs, passwords, approval tools, commit tools, or write credentials.
 ## 7. Validate the config
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner config validate --config synapsor.runner.json
-npx -y -p @synapsor/runner synapsor-runner config show --config synapsor.runner.json --redacted
+npx -y @synapsor/runner config validate --config synapsor.runner.json
+npx -y @synapsor/runner config show --config synapsor.runner.json --redacted
 ```
 
 The config stores environment-variable names, not connection-string values.
@@ -498,7 +500,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 synapsor-runner doctor --config synapsor.runner.json
+npx -y @synapsor/runner doctor --config synapsor.runner.json
 ```
 
 Doctor validates config shape, trusted context env vars, source env vars,
@@ -506,7 +508,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 synapsor-runner doctor --config synapsor.runner.json --json
+npx -y @synapsor/runner doctor --config synapsor.runner.json --json
 ```
 
 ## 8. Serve semantic MCP tools
@@ -516,7 +518,7 @@ 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 synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 Use Streamable HTTP when an app/server agent connects through a standard HTTP
@@ -527,7 +529,7 @@ export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
 export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
-npx -y -p @synapsor/runner synapsor-runner up --serve \
+npx -y @synapsor/runner up --serve \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
@@ -541,7 +543,7 @@ serving.
 The lower-level MCP command starts the same transport directly:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
+npx -y @synapsor/runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
@@ -572,10 +574,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 synapsor-runner proposals list --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
-npx -y -p @synapsor/runner synapsor-runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
+npx -y @synapsor/runner proposals list --store ./.synapsor/local.db
+npx -y @synapsor/runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
+npx -y @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:
@@ -583,7 +585,7 @@ Apply through the trusted worker path with a separate writer credential:
 ```bash
 export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-write-url>"
 SYNAPSOR_ENGINE=postgres \
-npx -y -p @synapsor/runner synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 For `apply --job ... --config ...`, Runner reads the write credential from the
@@ -597,7 +599,7 @@ from environment variables, and the handler receives a structured proposal/job
 payload, not arbitrary model SQL:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 See [Writeback Executors](writeback-executors.md).
@@ -605,8 +607,8 @@ See [Writeback Executors](writeback-executors.md).
 Replay afterward:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
+npx -y @synapsor/runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
 ```
 
 ## Boundary

package/docs/guided-onboarding.md

@@ -24,23 +24,25 @@ Use a disposable or staging database and a dedicated SELECT-only, non-owner
 credential. Keep row-level security, restricted views, or tenant-bound
 credentials underneath Runner where available.
 
-Export credentials in the launching shell. Do not put their values in project
-files or chat:
+Do not put a database URL in project documentation or chat. The shortest path
+uses a hidden terminal prompt:
 
 ```bash
-export DATABASE_URL='<staging read-only URL>'
-export SYNAPSOR_TENANT_ID='<staging tenant>'
-export SYNAPSOR_PRINCIPAL='<staging principal>'
+npx -y @synapsor/runner start
 ```
 
-Runner requires Node 22.13 or newer.
+Runner can also use an already-exported `DATABASE_URL`. When a regular `.env`
+or `.env.local` file exists, it asks before reading that file and holds the
+selected value only for the current Runner/Workbench process. The URL is not
+written to generated artifacts or the ledger. Runner requires Node 22.13 or
+newer.
 
 ## One Command To Workbench
 
 Run this from an empty project directory or your application root:
 
 ```bash
-npx -y @synapsor/runner@latest start --from-env DATABASE_URL
+npx -y @synapsor/runner start
 ```
 
 The command automatically:
@@ -55,15 +57,38 @@ The command automatically:
 7. opens one secured loopback Workbench URL.
 
 Before human activation, the agent has no generated authority and no source row
-has been read.
+has been read. On an explicitly asserted personal development database,
+Workbench offers a fast lane:
+
+1. confirm the database is your own development or disposable test data;
+2. provide the trusted tenant/principal scope for this in-memory session;
+3. inspect the one-resource summary and select **Activate this narrow read and
+   show a real result**.
+
+The single gesture is recorded against the exact boundary digest. Runner
+rechecks schema and read-only role posture, activates one resource with no
+relationships, keeps sensitive and uncertain fields out, and runs one real
+bounded aggregate read. Shared, staging, production-like, remote, widening, and
+write paths do not use this shortcut.
 
 Running the same command again resumes. Resume and Try do not rescan, rewrite
 files, or change a digest. Rescan and destructive Start over remain explicit
 human choices.
 
+Workbench requires no additional terminal command. If you choose the CLI
+fallbacks below after the first success, install Runner once:
+
+```bash
+npm install -g @synapsor/runner
+```
+
+The remaining examples then use `synapsor-runner` directly instead of
+reacquiring the npm package for every command.
+
 ## Five Minutes: First Safe Read
 
-Workbench starts with an overview, not a permission matrix. It shows:
+The full Workbench path starts with an overview, not a permission matrix. It
+shows:
 
 - database and framework evidence found;
 - resources inspected;
@@ -98,13 +123,40 @@ Source database changed: no
 CLI fallback:
 
 ```bash
-npx -y @synapsor/runner@latest try call --list --format json
-npx -y @synapsor/runner@latest try call <returned-tool-name> --sample --json
+synapsor-runner try call --list --format json
+synapsor-runner try call <returned-tool-name> --sample --json
 ```
 
 The second command is for an activated named tool with valid generated sample
 input. It does not invent tenant or principal values.
 
+## Optional: Ask Through Your Own Model
+
+The no-model Workbench composer is already complete; a provider key is never
+required for onboarding. If you want a chat surface before installing Cursor
+or another MCP client, open **Analyze -> Ask with your model**.
+
+Workbench shows the exact reviewed tools first. Select OpenAI, Anthropic, or a
+custom OpenAI-compatible endpoint, choose a named environment credential or a
+session-only masked paste, and acknowledge that reviewed visible data may go
+directly to that provider. Synapsor does not relay it.
+
+The provider can request only the displayed tools. It cannot choose trusted
+scope, activate or Protect authority, approve or apply a proposal, or configure
+Runner. A write request produces the same inert proposal as external MCP:
+
+```text
+Proposal only
+Source database changed: no
+The model cannot approve or apply this proposal.
+```
+
+Changing the provider, model, endpoint, runtime config, or reviewed boundary
+requires a new egress acknowledgement. Select **Clear** to cancel and discard
+the in-memory provider configuration and conversation. See [Workbench Ask With
+Your Model](workbench-ask.md) for key handling, endpoint security, fixed bounds,
+the tested provider matrix, and the full no-model alternative.
+
 ## Ten Minutes: Explore And Protect
 
 Scoped Explore is available only after its exact local authoring boundary is
@@ -122,7 +174,14 @@ The first release supports bounded:
 - reviewed categorical dimensions;
 - day, week, and month buckets;
 - typed filters and bounded top-N;
-- at most one reviewed many-to-one relationship.
+- up to three activated relationship paths, each containing one or two
+  catalog-proven many-to-one links with fan-out one.
+
+If a question needs an inactive but proven path, Runner refuses it and
+Workbench offers only that exact path for operator review. The model cannot
+activate it. Optional links require an explicit missing-row choice because
+excluding a row versus retaining an empty group can change business totals.
+See [Reviewed Relationship Paths](reviewed-relationships.md).
 
 Minimum cohorts, group limits, response limits, query limits, extraction
 budgets, and anti-differencing budgets are fixed by the activated boundary.
@@ -132,7 +191,7 @@ not prove causation.
 CLI fallback for the Workbench-suggested aggregate:
 
 ```bash
-npx -y @synapsor/runner@latest try explore --suggested --json
+synapsor-runner try explore --suggested --json
 ```
 
 Choose **Protect this analysis** directly on the successful result. Runner
@@ -148,10 +207,16 @@ synapsor/protected/drafts/<namespace>__<name>/contract-tests.json
 The capability remains disabled until a human activates its exact digest.
 Disabling Scoped Explore does not remove the protected named capability.
 
+Workbench renders generated `.synapsor.sql` with local deterministic syntax
+highlighting. Keywords, names chosen by the author, strings, numbers, comments,
+and punctuation are visually distinct. The copy/plain-text value remains
+byte-identical to the generated file; highlighting loads no CDN and escaped
+source text never becomes HTML.
+
 CLI fallback, without copying an opaque query handle:
 
 ```bash
-npx -y @synapsor/runner@latest try protect \
+synapsor-runner try protect \
   --name analytics.reviewed_weekly_summary \
   --json
 ```
@@ -189,15 +254,15 @@ The model cannot approve or apply this proposal.
 Inspect the latest lifecycle without copying a proposal ID:
 
 ```bash
-npx -y @synapsor/runner@latest lifecycle --details
+synapsor-runner lifecycle --details
 ```
 
 Approval and apply stay outside MCP:
 
 ```bash
-npx -y @synapsor/runner@latest proposals approve latest --yes
-npx -y @synapsor/runner@latest apply latest
-npx -y @synapsor/runner@latest lifecycle show latest --details
+synapsor-runner proposals approve latest --yes
+synapsor-runner apply latest
+synapsor-runner lifecycle show latest --details
 ```
 
 Production should use a verified signed-key or OIDC operator identity rather
@@ -218,7 +283,7 @@ Apply](supervised-automatic-apply.md).
 Preview is always the default:
 
 ```bash
-npx -y @synapsor/runner@latest writeback setup \
+synapsor-runner writeback setup \
   --profile staging \
   --json
 ```
@@ -238,7 +303,7 @@ DDL apply is refused for missing, unknown, or production profiles. In
 development/staging, it requires the exact displayed confirmation:
 
 ```bash
-npx -y @synapsor/runner@latest writeback setup \
+synapsor-runner writeback setup \
   --profile staging \
   --writer-role '<steady-state-writer-role>' \
   --setup-url-env SYNAPSOR_SETUP_DATABASE_URL \
@@ -250,20 +315,22 @@ Never reuse the model/read credential as the elevated setup connection.
 
 ## Connect An MCP Client
 
-Workbench generates ready-to-copy Cursor, Claude, Codex, and generic stdio
-snippets for the same reviewed authority. Stdio opens no network listener and
-needs no HTTP bearer credential.
+Workbench generates ready-to-copy Cursor, Claude Code/Desktop, VS Code, Codex,
+and generic stdio snippets for the same reviewed authority. Stdio opens no
+network listener and needs no HTTP bearer credential.
 
 Render the generic snippet:
 
 ```bash
-npx -y @synapsor/runner@latest mcp config --absolute-paths
+synapsor-runner mcp config --absolute-paths
 ```
 
-Preview a project-scoped Cursor change:
+Preview a managed project change for the client you use:
 
 ```bash
-npx -y @synapsor/runner@latest mcp install cursor --project --dry-run
+synapsor-runner mcp install claude-code --project --dry-run
+synapsor-runner mcp install cursor --project --dry-run
+synapsor-runner mcp install vscode --project --dry-run
 ```
 
 No client config contains database URLs, trusted scope values, approval,
@@ -275,7 +342,7 @@ Commands that support machine output write exactly one JSON value to stdout.
 Operational logs and diagnostics use stderr:
 
 ```bash
-npx -y @synapsor/runner@latest try explore --suggested --json | jq -e .
+synapsor-runner try explore --suggested --json | jq -e .
 ```
 
 On a process-level failure, JSON output uses:
@@ -315,17 +382,20 @@ The guided path through the first proposal uses:
 - no Cursor requirement.
 
 The packed FitFlow gate records the exact command count, human decisions, and
-timings in `development/runner-1.6.3-fitflow-results.json`.
+timings in `development/runner-1.6.4-fitflow-results.json`.
 
 ## Visual Reference
 
 Repository screenshots cover desktop, mobile, light, dark, loading, blocked,
-stale, failure, empty Protect, and unavailable-action states:
-
-- [Desktop overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-overview-desktop-light.png)
-- [Mobile overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-overview-mobile-light.png)
-- [Blocked identity review](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-blocked-identity.png)
-- [Stale/failure recovery](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.3-visual/workbench-keyboard-stale-failure.png)
+stale, failure, empty Protect, unavailable-action, optional Ask, refusal, and
+proposal-only states:
+
+- [Desktop overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-overview-desktop-light.png)
+- [Mobile overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-overview-mobile-light.png)
+- [Blocked identity review](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-blocked-identity.png)
+- [Stale/failure recovery](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-keyboard-stale-failure.png)
+- [Ask kept-out-field refusal](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-retail-visual/05c-ask-refusal.png)
+- [Ask proposal-only result](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-community-solar-visual/13b-ask-proposal-only.png)
 
 For common blocked states and one-action recovery commands, use
 [Troubleshooting First Run](troubleshooting-first-run.md).

package/docs/host-compatibility.md

@@ -1,7 +1,7 @@
 # MCP Host Compatibility
 
 This matrix separates host evidence from protocol evidence. It was last
-reviewed on 2026-07-20. A working MCP SDK handshake is not presented as proof
+reviewed on 2026-07-25. A working MCP SDK handshake is not presented as proof
 that a specific editor renders an extension or protects app-only controls.
 
 | Host/surface | Status | Evidence and boundary |
@@ -14,32 +14,45 @@ that a specific editor renders an extension or protects app-only controls.
 | Generic stdio MCP client | Protocol-tested | Official MCP SDK initialization, tool listing, calls, resources, and display-only Apps metadata are covered in the suite. |
 | Generic Streamable HTTP MCP client | Protocol-tested | Official MCP SDK sessions, signed context, secret rotation, JWKS, mTLS, aliases, and session isolation are covered. |
 | Claude Desktop | Protocol-tested | Packaged stdio configuration and MCP transport are tested; manual host UI behavior varies by version and remains a release checklist item. |
-| Claude Code | Configuration-tested and protocol-tested | Claude Code 2.1.216 accepted the secret-free stdio configuration through `mcp add-json`; the same command completed MCP `tools/list`. A manual model-driven proposal call remains a release gate. |
+| Claude Code project `.mcp.json` lifecycle | Configuration-tested and protocol-tested | Runner install/status/uninstall tests cover preview, merge, backup, idempotency, ownership, tamper refusal, exact-version wiring, and the exact reviewed `tools/list`. Local Claude Code version observed: 2.1.220. A manual model-driven proposal call remains a release gate. |
 | Codex | Configuration-tested and protocol-tested | Codex CLI 0.144.6 accepted the secret-free stdio configuration through `codex mcp add`; the same command completed MCP `tools/list`. A manual model-driven proposal call remains a release gate. |
-| VS Code | Protocol-tested | The checked `.vscode/mcp.json` shape is parsed and the same stdio command completes MCP `tools/list`; manual editor UI behavior is not claimed. |
+| VS Code project `.vscode/mcp.json` lifecycle | Configuration-tested and protocol-tested | Runner install/status/uninstall tests cover JSONC-preserving merge, backup, idempotency, ownership, tamper refusal, exact-version wiring, and the exact reviewed `tools/list`. Local VS Code version observed: 1.123.0. Manual editor UI behavior is not claimed. |
 | OpenAI Agents SDK | Recipe-checked and protocol-tested | Packaged stdio/Streamable HTTP examples are syntax/safety checked and OpenAI-safe aliases are protocol-tested. The exact SDK agent call remains protocol-only until run with an owner-supplied API key. |
 | LangChain/LangGraph | Recipe-checked, protocol-only | The current `@langchain/mcp-adapters` recipe lists tools, rejects unsafe authority, and calls the proposal tool. The framework runtime has not been executed in this release environment. |
 | Google ADK | Recipe-checked, protocol-only | The current `McpToolset`/`StdioConnectionParams` recipe exposes only the two reviewed tools. The framework runtime has not been executed in this release environment. |
 | LlamaIndex | Recipe-checked, protocol-only | The current `BasicMCPClient` recipe lists tools and calls the proposal tool. The framework runtime has not been executed in this release environment. |
 
-## Cursor Project Setup
+## Managed Project Setup
 
-Current Cursor documentation supports project MCP configuration in
-`.cursor/mcp.json`. Runner manages only its `synapsor` entry:
+Runner manages only its `synapsor` entry in each supported project-local
+configuration:
 
 ```bash
 synapsor-runner mcp install cursor --project --dry-run
-synapsor-runner mcp install cursor --project --yes
-synapsor-runner mcp status cursor --project --check-launch
+synapsor-runner mcp install claude-code --project --dry-run
+synapsor-runner mcp install vscode --project --dry-run
+
+synapsor-runner mcp install claude-code --project --yes
+synapsor-runner mcp status claude-code --project --check-launch
 ```
 
-The generated entry contains command paths only. Database credentials and
-trusted tenant/principal values must come from the environment that launches
-Runner. Other Cursor MCP servers and settings are preserved.
+Cursor uses `.cursor/mcp.json` and `mcpServers`; Claude Code uses `.mcp.json`
+and `mcpServers`; VS Code uses `.vscode/mcp.json` and `servers`. The generated
+entry contains command paths and an exact package version only. Database
+credentials and trusted tenant/principal values must come from the environment
+that launches Runner. Other servers and project settings are preserved.
+
+`--dry-run` never writes. An approved install creates a backup and an integrity
+marker. A repeated install is idempotent; uninstall removes only an unchanged,
+Runner-owned entry. Claude Code still requires its own human project-server
+approval, and VS Code still requires the operator to reload/start the server.
+Those host actions do not grant Synapsor approval or commit authority.
 
 Primary references:
 
 - [Cursor MCP documentation](https://cursor.com/docs/context/mcp)
+- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
+- [VS Code MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers)
 - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
 - [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx)