@synapsor/runner 1.5.0 → 1.5.3

package/docs/fresh-developer-usability.md

@@ -0,0 +1,110 @@
+# Fresh-Developer Usability Protocol
+
+Use this protocol with five developers who have not previously used Synapsor.
+It is a launch gate, not an automated test. A maintainer may rehearse the
+protocol, but must not report a participant result unless that person actually
+completed the session.
+
+## Goal
+
+Measure whether a developer can connect an existing supported staging project,
+draft one disabled Safe Action with a coding agent, receive an exact Data PR,
+approve outside the agent, and find the guarded receipt without learning the
+canonical JSON or SQL-like DSL first.
+
+Measure product time separately from the initial package download. Start the
+product timer only after `synapsor-runner --version` succeeds.
+
+## Participant Setup
+
+Provide each participant with:
+
+- a fresh clone of their application or the support-plan-credit reference app;
+- Node 22.13 or newer;
+- a disposable Postgres staging database and least-privilege read/write roles;
+- exported database URLs and trusted tenant/principal values;
+- current stable Cursor, with no existing Synapsor configuration;
+- the README only. Do not give verbal product-architecture instruction.
+
+Never use production credentials or data. Record the OS, Node version, Cursor
+version, package-install method, database engine, and whether the package was
+already cached.
+
+## Tasks
+
+Ask the participant to complete these tasks without a maintainer taking control:
+
+1. Run the four-second synthetic proof and identify whether the model can call
+   `approve`, `apply`, `commit`, or raw SQL.
+2. Connect the staging project and confirm the trusted organization scope.
+3. Tell Cursor one business action to make safe and use the generated
+   `/synapsor-protect` path or exact fallback prompt.
+4. Find the disabled action file and explain why editing it does not activate a
+   tool.
+5. Open the Workbench effect preview and confirm the source row is unchanged.
+6. Explicitly activate the reviewed digest through the operator-controlled UI.
+7. Reconnect Cursor if instructed and create one proposal through the semantic
+   tool.
+8. Review the exact before/after Data PR, approve outside Cursor, and apply it.
+9. Locate the receipt/replay record and explain what happens on retry.
+10. Draft a second disabled action without changing the active tool surface.
+
+Do not rescue a participant until they have been blocked for two minutes. Record
+the exact screen, command, wording, or missing prerequisite that blocked them.
+
+## Measurements
+
+For each participant, record:
+
+| Measure | Target |
+| --- | --- |
+| Installed CLI to first own-data Data PR | under 5 minutes |
+| Installed CLI to first guarded receipt | under 8 minutes |
+| Second disabled action draft after setup | under 2 minutes |
+| Second action ready for explicit activation | under 5 minutes |
+| Handwritten canonical JSON or DSL | none on the happy path |
+| Extra CLI command after Cursor proposal call | none |
+| Unsafe authority exposed to Cursor | none |
+
+Also record every wrong turn, maintainer intervention, misunderstood trust
+boundary, and request for a model-provider key or Synapsor account.
+
+## Pass Criteria
+
+The launch gate passes only when all five participants:
+
+- complete the first Data PR without handwritten JSON or DSL;
+- correctly identify that activation, approval, and apply are outside the
+  model-facing MCP surface;
+- observe unchanged source data before approval;
+- produce one guarded receipt; and
+- expose only the intended semantic read/proposal tools in Cursor.
+
+At least four of five must meet every timing target. Any cross-tenant result,
+hidden-field exposure, pre-approval mutation, automatic activation, raw SQL
+tool, or model-visible commit authority is a release blocker regardless of
+timing.
+
+## Reporting Template
+
+Record one row per real participant:
+
+```text
+Participant:
+Date:
+Environment:
+Cold package download:
+Product timer start:
+First Data PR:
+First receipt:
+Second draft:
+Second activation-ready action:
+Interventions:
+Tool surface observed:
+Safety-boundary explanation:
+Outcome: pass | fail
+```
+
+Until five real sessions are recorded, report this gate as **owner verification
+pending**. Do not infer usability from unit tests, protocol tests, or a
+maintainer-run demo.

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

@@ -28,11 +28,11 @@ inspect your schema
 -> choose one table/view
 -> choose trusted scope and visible fields
 -> optionally choose proposal/writeback rules
--> generate synapsor.runner.json
+-> generate synapsor.runner.json + canonical synapsor.contract.json
 -> preview MCP tools exposed to the model
 -> run a local smoke check of the tool boundary
 -> optionally write .synapsor/smoke-input.json for one real row
--> print mcp serve and local UI commands
+-> open the secured localhost first-action workbench in an interactive terminal
 ```
 
 It does not print your database URL, put the URL in MCP client config, expose
@@ -43,6 +43,11 @@ credentials.
 `onboard db --from-env DATABASE_URL` is the same explicit path if you prefer the
 older command name in scripts.
 
+Interactive `start` opens the focused local workbench after config validation
+and an MCP boundary handshake. Use `--no-open` for CI or scripts. That handshake
+proves the reviewed tool surface; the workbench's **Test** step remains pending
+until a real scoped read is recorded in the local ledger.
+
 During the wizard, provide the optional sample object id if you know one safe
 row in the selected table. Runner writes `./.synapsor/smoke-input.json` with
 that id and prints the exact `smoke call` command. If you skip it, use
@@ -186,6 +191,95 @@ The wizard:
 - writes the generated config, `.env.example`, and MCP client snippets only
   after final confirmation.
 
+The generated action is explicit about its activation state. Read-only and
+shadow actions cannot commit. Review/writeback generation requires final
+confirmation (`--yes` in a noninteractive command) and still gives the model no
+approval or apply tool.
+
+### Draft another Safe Action with a coding agent
+
+After a reviewed read capability exists, describe one business action instead
+of hand-authoring a complete contract:
+
+```bash
+synapsor-runner start \
+  --action plan_credit \
+  --description "Propose one reviewed customer plan credit" \
+  --based-on support.inspect_customer
+```
+
+Runner writes `synapsor/actions/support.propose_plan_credit.ts` and scoped
+agent instructions. The file is an inert scaffold. It contains explicit
+authority questions for trusted scope, visible and kept-out fields, allowed
+effect, conflict guard, bounds, approval, and executor. Creating or editing it
+does not change the active contract or MCP tool list.
+
+Give the exact prompt printed by the command to Cursor or another coding
+agent. The agent may inspect project/schema evidence, complete the restricted
+TypeScript object, and run deterministic validation:
+
+```bash
+synapsor-runner action validate \
+  ./synapsor/actions/support.propose_plan_credit.ts
+```
+
+Runner statically parses rather than imports the file. A successful validation
+writes a digest-addressed **disabled draft**, a plain-language explanation,
+and exact static allow/deny/effect tests under `.synapsor/drafts/`. It cannot
+activate a tool.
+
+In the secured Workbench, run **Preview exact staging Data PR**. The preview
+may perform the reviewed scoped read and write proposal evidence to the local
+ledger, but it cannot mutate the source. Review the exact effect, type
+`ACTIVATE` plus the complete displayed digest, and confirm activation yourself.
+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
+
+After setting trusted environment values, preview and install a project-scoped
+entry without hand-editing `.cursor/mcp.json`:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp install cursor --project --yes \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+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
+```
+
+See the [host compatibility matrix](host-compatibility.md) for the precise
+Cursor evidence and MCP Apps limitation.
+
+## 6. Inspect local activation evidence
+
+Runner records bounded timing milestones locally. It does not transmit them:
+
+```bash
+synapsor-runner activation show \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner activation export \
+  --out ./.synapsor/activation-report.json
+```
+
+Product activation time begins after package installation; initial npm
+resolution/download/cache time is measured separately when evaluating cold
+`npx` behavior. The report contains milestone timing/status only, not source
+rows, object IDs, tenant IDs, credentials, or project paths.
+
 For proposal modes, the current runner supports explicit field-update mappings such as:
 
 ```text

package/docs/host-compatibility.md

@@ -0,0 +1,59 @@
+# 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
+that a specific editor renders an extension or protects app-only controls.
+
+| Host/surface | Status | Evidence and boundary |
+| --- | --- | --- |
+| Cursor project `.cursor/mcp.json` lifecycle | Tested | Runner install/status/uninstall tests cover preview, merge, backup, idempotency, ownership, tamper refusal, paths with spaces, and exact-version `npx` wiring. Local Cursor version observed: 3.7.21 (`517f696d8ab6c53eb04fbfdaae705cd146bf3460`, x64). |
+| Cursor stdio Runner launch and `tools/list` | Protocol-tested | `mcp status cursor --project --check-launch` executes the generated command and checks the exact reviewed tools through the official MCP client transport. A final manual Cursor UI pass is still required for a release claim tied to that host version. |
+| Cursor MCP Apps inline proposal card | Unknown | Runner advertises the standard display-only resource metadata, but current stable Cursor rendering and app-only authority guarantees have not been reproduced. Use the secured localhost workbench or operator CLI. |
+| Cursor approval/apply/revert through MCP | Unsupported | Intentionally absent. Cursor may auto-run model-facing tools; commit authority therefore stays outside MCP regardless of host settings. |
+| Generic Add to Cursor deep link | Unsupported | Runner does not generate a link because no current documented generic server payload has been verified end to end. Project install is the supported path. |
+| 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. |
+| 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. |
+| 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
+
+Current Cursor documentation supports project MCP configuration in
+`.cursor/mcp.json`. Runner manages only its `synapsor` entry:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run
+synapsor-runner mcp install cursor --project --yes
+synapsor-runner mcp status cursor --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.
+
+Primary references:
+
+- [Cursor MCP documentation](https://cursor.com/docs/context/mcp)
+- [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)
+
+All adjacent-host source links, runnable snippets, shared proposal input, and
+verification commands are in [Client And Framework Recipes](client-recipes.md).
+
+## Authority Fallback
+
+Hosts without a verified app-only human-control boundary receive the same
+structured/text proposal result and can open the secured loopback workbench.
+Approval, rejection, apply, compensation, policy activation, trusted identity,
+and credentials never enter model-visible `tools/list`. Runner does not infer
+host safety from a product name or user-agent string.
+
+Runner currently exposes tools, not MCP prompts or an elicitation-based
+approval flow. First-run setup and approval do not depend on optional host
+prompt/elicitation support.

package/docs/local-mode.md

@@ -32,11 +32,12 @@ Current local-mode foundation:
 
 Runtime requirement:
 
-The stable 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.
+The stable package requires Node >= 22.13.0 because the local evidence/replay
+ledger uses Node's unflagged `node:sqlite` runtime. Earlier Node 22 releases
+require an experimental flag and are not supported. 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
 

package/docs/mcp-audit.md

@@ -8,7 +8,10 @@ available for users who look for the command under the MCP namespace.
 From a source checkout, use `./bin/synapsor-runner ...` if the global binary is not
 linked yet.
 
-It does not call business tools. It only inspects names, descriptions, input schemas, output schemas, annotations, and examples when those are present.
+Static mode does not launch configured MCP servers or call business tools. It
+only inspects names, descriptions, input schemas, output schemas, annotations,
+and examples when those are present. An explicitly consented live check calls
+only `initialize` and `tools/list` on one named server.
 
 Every report includes this disclaimer:
 
@@ -86,6 +89,36 @@ Markdown output for issues, PRs, or security review notes:
 npx -y -p @synapsor/runner synapsor-runner audit --example dangerous-db-mcp --format markdown
 ```
 
+Inspect a project-scoped Cursor configuration without launching anything:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner audit \
+  --mcp-config ./.cursor/mcp.json \
+  --format markdown
+```
+
+Static client-config output marks every server without supplied tool metadata
+as `requires_operator_verification`. To query one reviewed stdio command, name
+that exact server and give explicit consent:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner audit \
+  --mcp-config ./.cursor/mcp.json \
+  --live-server synapsor \
+  --yes \
+  --format json
+```
+
+Runner does not use a shell and refuses unresolved interpolation. For Cursor's
+documented `${workspaceFolder}` token, a config under `.cursor/mcp.json`
+resolves against the project root. Live mode executes no business, approval,
+apply, commit, or revert tool. It cannot prove the selected server is secure.
+
+The bypass check matters after installing Runner: another model-visible MCP
+server may still expose `execute_sql` or a direct write. Synapsor cannot govern
+calls routed around Runner. Audit reports the server and observed tool names,
+but never removes or rewrites unrelated MCP configuration automatically.
+
 During local development, the repo-local wrapper can run the same command:
 
 ```bash
@@ -104,6 +137,19 @@ npx -y -p @synapsor/runner synapsor-runner audit generate \
   --output ./synapsor-audit-candidates
 ```
 
+Open the same blocked candidate directly in the secured local review
+workbench:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner audit generate \
+  ./tools-list.json \
+  --output ./synapsor-audit-candidates \
+  --open-ui
+```
+
+This does not activate the candidate. The generated Runner config has no source
+and every proposal writeback is `none`.
+
 The generator uses the same parser and findings as `audit`. It writes:
 
 - a canonical `@synapsor/spec` contract;
@@ -147,7 +193,33 @@ The audit accepts common exported shapes:
 
 It also scans nested `adapter`, `mcpServers`, and `servers` blocks when they include tool metadata.
 
-For live targets, the audit calls only JSON-RPC `tools/list`. It does not call business tools, approval tools, commit tools, or writeback tools.
+For live stdio targets, the audit performs MCP `initialize`, then calls only
+JSON-RPC `tools/list`. Remote URL mode calls `tools/list`. It does not call
+business tools, approval tools, commit tools, or writeback tools.
+
+Checked-in deterministic fixtures live under
+[`fixtures/mcp-audit`](../fixtures/mcp-audit). The repository's
+[`mcp-audit` GitHub Actions workflow](https://github.com/Synapsor/Synapsor-Runner/blob/main/.github/workflows/mcp-audit.yml)
+builds the package, proves the dangerous fixture is detected, emits SARIF for
+the reviewed proposal fixture, validates the SARIF shape, and uploads the
+artifacts. Code-scanning upload runs only outside pull requests so forks do not
+receive write authority.
+
+## Model-authority map
+
+Every text, JSON, Markdown, and SARIF report records structural evidence for:
+
+- semantic reads and semantic proposals;
+- direct writes and raw SQL/query authority;
+- arbitrary identifier and model-controlled trust inputs;
+- model-visible approval/apply/commit/revert authority;
+- structured output and observable conflict/idempotency signals;
+- controls that require an operator or sit outside static audit visibility.
+
+Statuses are `observed`, `not_observed`, `requires_operator_verification`, or
+`outside_static_audit_visibility`. These are evidence labels, not a numerical
+security score. `not_observed` means only that the supplied metadata did not
+show the authority. It is not proof of absence at runtime.
 
 ## Findings
 
@@ -164,6 +236,85 @@ The audit flags database-commit risks such as:
 - ambiguous read/write tool boundaries;
 - missing business descriptions, annotations, or fixture examples.
 
+### Finding remediation index
+
+The report carries one stable remediation URL for every finding. These anchors
+are intentionally durable for JSON, Markdown, SARIF, pull requests, and code
+scanning.
+
+<a id="finding-generic-sql-tool"></a>
+<a id="finding-write-tool-accepts-arbitrary-sql"></a>
+<a id="finding-arbitrary-identifier-input"></a>
+<a id="finding-arbitrary-predicate-input"></a>
+
+#### Raw SQL, arbitrary identifiers, and free-form predicates
+
+Replace generic SQL/query tools and model-selected schemas, tables, databases,
+columns, filters, predicates, or WHERE clauses with a reviewed semantic
+capability. Fixed identifiers and row-selection rules belong in the contract;
+model inputs carry bounded business values only.
+
+<a id="finding-model-controlled-trust-scope"></a>
+
+#### Model-controlled trust scope
+
+Bind tenant, principal, source, allowed fields, approval identity, and conflict
+authority from verified context outside model arguments. Retain database RLS,
+restricted views, and least-privilege roles underneath Runner.
+
+<a id="finding-model-callable-commit-or-approval"></a>
+<a id="finding-write-without-proposal-boundary"></a>
+<a id="finding-mcp-bypass-direct-authority"></a>
+
+#### Missing review boundary or bypass
+
+Expose an immutable proposal rather than direct mutation. Keep activation,
+approval, apply, commit, and revert outside MCP. Disable or independently
+constrain another model-visible server that bypasses Runner; Synapsor cannot
+govern calls made through that server.
+
+<a id="finding-no-idempotency-field"></a>
+<a id="finding-no-conflict-guard"></a>
+<a id="finding-ambiguous-read-write-tool"></a>
+
+#### Retry, stale-state, and mixed-authority gaps
+
+Separate reads from proposals and require stable operation identity,
+idempotency receipts, an exact conflict/version guard, and an affected-row
+bound before trusted writeback.
+
+<a id="finding-no-structured-output-schema"></a>
+
+#### Missing structured output
+
+Publish typed results that distinguish reads, pending proposals, conflicts,
+failures, receipts, evidence, replay, and retry guidance without parsing prose.
+
+<a id="finding-missing-business-description"></a>
+<a id="finding-missing-risk-annotations"></a>
+<a id="finding-missing-test-fixture"></a>
+
+#### Reviewability gaps
+
+Add a reviewer-readable business description, honest read/destructive hints,
+and a non-production fixture. Annotations are vocabulary for clients, not an
+enforcement boundary.
+
+<a id="finding-mcp-server-tool-surface-unverified"></a>
+
+#### Unverified configured server
+
+Export that server's `tools/list`, or run the exact named `--live-server` check
+after reviewing its configured command. Static client configuration does not
+reveal the actual tool catalog.
+
+<a id="finding-no-tools-found"></a>
+
+#### No tools found
+
+Provide an exported `tools/list` response, a supported manifest, a Runner
+config, or an explicitly consented live target.
+
 ## Recommended target shape
 
 A safer model-facing database MCP tool should look like a reviewed semantic proposal capability:
@@ -205,6 +356,19 @@ A safer model-facing database MCP tool should look like a reviewed semantic prop
 
 Trusted values such as tenant, principal, source, allowed columns, approval identity, row-version guard, and database credentials must come from Synapsor/runner context, not from model-facing arguments.
 
+To turn an identified business write into a disabled reviewed action, continue
+with the Safe Action Composer:
+
+```bash
+synapsor-runner start \
+  --action refund_order \
+  --description "Propose one reviewed order refund"
+```
+
+The generated TypeScript action remains disabled. A coding agent may complete
+and validate it; only a human can activate its exact digest in the secured
+localhost Workbench.
+
 ## Related Fixture Benchmark
 
 `synapsor-runner benchmark mcp-efficiency` compares a fixed generic database

package/docs/mcp-client-setup.md

@@ -11,6 +11,10 @@ or SDK. The simplest local-client contract is stdio. Standard HTTP MCP is
 available through Streamable HTTP when your agent connects to a long-running
 Runner service.
 
+The checked [Client And Framework Recipes](client-recipes.md) use one shared
+`support.propose_plan_credit` flow and distinguish host evidence from standard
+MCP protocol evidence.
+
 Proposal tools also advertise a standard display-only
 [MCP App](mcp-apps.md). Supporting hosts discover it from tool metadata;
 other clients keep the same text/JSON proposal result. Approval and apply

package/docs/mcp-clients.md

@@ -15,6 +15,11 @@ The complete copy-paste templates live in:
 - every local `synapsor-runner contract bundle` output;
 - every downloadable Synapsor Cloud runner bundle.
 
+For one shared proposal call across Claude Code, Codex, VS Code, OpenAI Agents,
+LangChain/LangGraph, Google ADK, LlamaIndex, and generic MCP clients, see
+[Client And Framework Recipes](client-recipes.md). Each recipe states whether
+it is host-tested, configuration-tested, protocol-tested, or recipe-only.
+
 Before connecting a client, validate the local boundary:
 
 ```bash
@@ -62,15 +67,39 @@ repository file.
 
 ### Cursor
 
-For one repository, place the project template at `.cursor/mcp.json`. For a
-global setup, merge `cursor-global.mcp.json` through Cursor's MCP settings and
-replace every `<absolute-path-to-bundle>` marker. Restart the MCP server from
-Cursor settings after editing.
+Prefer Runner's owned project lifecycle for one repository:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp install cursor --project --yes \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+Runner previews the merge, backs up an existing `.cursor/mcp.json`, preserves
+other MCP servers/settings, writes an exact-version `npx` invocation, and
+tracks only its own entry with an integrity marker. Repeating install is
+idempotent. `mcp uninstall cursor --project --yes` removes only that intact,
+Runner-owned entry and also creates a backup.
+
+For global setup, merge `cursor-global.mcp.json` through Cursor's MCP settings
+and replace every `<absolute-path-to-bundle>` marker. Restart the MCP server
+from Cursor settings after editing.
 
 The model-facing list should contain only the contract's inspect/propose tools.
 If Cursor reports a missing config or store, use absolute paths and rerun
 `tools preview` from the same working directory.
 
+Cursor can be configured to auto-run model-facing tools. Synapsor therefore
+never exposes approval, apply, revert, policy activation, trusted identity, or
+credentials as MCP tools. Inline MCP App review is not assumed for Cursor; use
+the secured localhost workbench or operator CLI. No Add to Cursor deep link is
+generated because Runner has not verified a currently documented generic
+payload for this server. See [Host Compatibility](host-compatibility.md).
+
 ### OpenAI Agents SDK
 
 Install the SDK in your agent project and run either TypeScript template:

package/docs/oss-vs-cloud.md

@@ -22,6 +22,7 @@ runtime stay local.
 | Contract source | Local files reviewed in Git | Shared registry with immutable versions and digests |
 | Trusted context | Local environment/session bindings | Registered bindings plus deployment-specific Cloud session context |
 | Capabilities | Local semantic MCP tools | Registry, version history, and capability inspection |
+| Safe Action activation | Explicit digest-confirmed local Workbench activation after a source-unchanged staging Data PR | Governed Cloud activation and immutable registry version; local coding agents still cannot activate |
 | Evidence and replay | Local SQLite ledger by default; optional shared Postgres runtime store | Redacted shared chronology and references; full evidence payload stays local by default |
 | Approval | Local CLI or localhost UI | Human-authenticated shared approval inbox; unavailable to MCP/Runner tokens |
 | Writeback | Guarded one-row CRUD, fixed/frozen bounded sets, or app-owned executor | Durable approval/job/lease coordination; the local Runner rechecks and executes |
@@ -36,6 +37,8 @@ runtime stay local.
 - direct access to Postgres or MySQL;
 - the process that executes guarded writeback;
 - local development ledgers when Cloud linkage is not enabled.
+- local disabled Safe Action drafts, project agent instructions, and source
+  database preview/writeback execution.
 
 Cloud contract registration does not require uploading database credentials or
 business rows. A Runner bundle contains the normalized contract, placeholder