@synapsor/runner 1.4.123 → 1.5.3

package/docs/README.md

@@ -23,14 +23,19 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 02 Why Raw SQL Is Dangerous
 
+- [Choose The Smallest Safe Database Boundary](alternatives.md): compare raw
+  database MCP, direct read-only access, hand-built application tools, and
+  Synapsor Runner, including when each is sufficient and what remains outside
+  Runner's protection.
 - [Security Boundary](security-boundary.md): what the model can and cannot see.
 - [Why Synapsor Over Prompt And Application
   Guardrails](why-synapsor-vs-app-guardrails.md): where SQL authority lives,
   what a hand-built semantic tool already gets right, and when the shared
   contract, approval, receipt, and replay layer is worth adopting.
-- [MCP Audit](mcp-audit.md): static review for risky database MCP tools such as
-  `execute_sql`, broad query tools, model-controlled tenant filters, or
-  model-facing approval/commit tools.
+- [MCP Audit](mcp-audit.md): concise static review for risky database MCP tools
+  such as `execute_sql`, broad query tools, model-controlled tenant filters, or
+  model-facing approval/commit tools, plus explicit generation of disabled
+  canonical review candidates.
 
 ## 03 Run The Demo
 
@@ -43,12 +48,19 @@ no-database demo, wire your database, then read deeper concepts.
 ## 04 Connect Your DB
 
 - [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.
+  staging Postgres/MySQL database, generate canonical reviewed artifacts, open
+  the first-action workbench, add the tools to Cursor, and inspect the local
+  activation report.
 - [Use Your Own Database](use-your-own-database.md): short entry point that
   links to the canonical own-database guide.
+- [Fresh-Developer Usability Protocol](fresh-developer-usability.md): the
+  repeatable five-person launch gate, timing rules, safety blockers, and honest
+  reporting template. External participant results are not yet claimed.
 - [Doctor](doctor.md): redacted setup checks, handler probes, direct SQL
   writeback probes, and receipt-table guidance.
+- [Database-Enforced Scope](database-enforced-scope.md): application-level
+  scope, hardened PostgreSQL RLS, tenant-bound credentials/deployments, and
+  honest MySQL alternatives.
 - [Guarded Single-Row CRUD Writeback](guarded-crud-writeback.md): native
   INSERT/UPDATE/DELETE, receipt modes, crash semantics, privileges, and
   reconciliation.
@@ -60,6 +72,18 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 05 Generate Capabilities
 
+- [Connect Your Own
+  Database](getting-started-own-database.md#draft-another-safe-action-with-a-coding-agent):
+  describe one action, let a coding agent complete only the restricted
+  TypeScript draft, validate it deterministically, preview an exact staging
+  Data PR, and activate the reviewed digest outside MCP.
+- [Cursor Plugin](cursor-plugin.md): project-scoped `/synapsor-protect`, Safe
+  Action diagnostics, package verification, and the explicit no-activation
+  boundary.
+- [Reviewed Prisma, Drizzle, And OpenAPI
+  Candidates](schema-api-candidates.md): turn structural developer artifacts
+  into deterministic, disabled canonical review candidates without executing
+  adopter code or inferring authority.
 - [Capability Authoring](capability-authoring.md): define read/proposal
   capabilities, model-facing descriptions, result envelopes, trusted context,
   and writeback guards.
@@ -74,15 +98,28 @@ no-database demo, wire your database, then read deeper concepts.
   and deterministic lint/SARIF output.
 - [Contract Testing](contract-testing.md): adopter-owned static and disposable
   PostgreSQL/MySQL allow/deny/redaction assertions.
+- [Agent Effect Regression](effect-regression.md): provider-neutral,
+  propose-only fixtures that catch changed capability calls, business diffs,
+  policy outcomes, tenant handling, and hidden-field behavior.
 - [Bounded Aggregate Reads](aggregate-reads.md): fixed scalar count/sum/avg,
   tenant scope, suppression, and no-row evidence.
 
 ## 06 Serve MCP
 
+- [Host Compatibility](host-compatibility.md): exact Tested,
+  Protocol-tested, Unsupported, and Unknown claims for Cursor and other MCP
+  hosts, including the inline-review fallback.
+- [Inline Proposal Review With MCP Apps](mcp-apps.md): display-only proposal
+  cards where supported, exact protocol versions, tested compatibility, and
+  secure standalone review fallback.
 - [MCP Client Setup](mcp-client-setup.md): connect Claude, Cursor, VS Code, or
   another stdio MCP client.
 - [MCP Client Configs](mcp-clients.md): complete Claude, Cursor, OpenAI Agents,
   generic stdio, and Streamable HTTP templates.
+- [Client And Framework Recipes](client-recipes.md): one proposal-only
+  support-plan-credit flow for Claude Code, Codex, VS Code, OpenAI Agents,
+  LangChain/LangGraph, Google ADK, LlamaIndex, and generic MCP clients, with
+  explicit evidence labels.
 - `examples/claude-desktop-postgres/`: copy-paste Claude Desktop config for the
   Postgres billing fixture.
 - `examples/cursor-postgres/`: copy-paste Cursor config for the Postgres
@@ -96,6 +133,8 @@ no-database demo, wire your database, then read deeper concepts.
 
 - [Local Mode](local-mode.md): local store, proposals, approval, replay, and
   writeback flow.
+- [Shadow Studies](shadow-studies.md): compare what an agent would propose
+  with explicit authorized outcomes before granting write authority.
 - [Writeback Executors](writeback-executors.md): app-owned writeback handlers
   for approved proposals.
 - [App-Owned Executors](app-owned-executors.md): short entry point for rich

package/docs/alternatives.md

@@ -0,0 +1,122 @@
+# Choose The Smallest Safe Database Boundary
+
+You do not always need Synapsor Runner. Choose the smallest boundary that
+matches the authority and evidence your agent actually needs.
+
+## Decision Summary
+
+| Approach | Good fit | Main boundary | Main trade-off |
+| --- | --- | --- | --- |
+| Direct database MCP | Disposable local data, synthetic demos, or tightly isolated development | Database credential and server implementation | The model can express SQL and may hold broad query authority |
+| Read-only database access | Exploration where database permissions and result exposure are already acceptable | Read-only role, views, RLS, and query controls | Read-only is not data-safe by itself; broad reads can still expose another tenant or sensitive columns |
+| Hand-built application tool | A few stable business operations already owned by one application team | Application endpoint or stored procedure | Your team owns every scope, review, retry, conflict, receipt, and investigation guarantee |
+| Synapsor Runner | Consequential reads or writes needing a shared reviewed boundary | Canonical capabilities plus Runner and database controls | Adds contract and operating machinery; it does not replace database security or application handlers |
+
+## Direct Or Raw Database MCP
+
+A raw database MCP server can be appropriate when all data is synthetic,
+disposable, and isolated from production. It is also useful for a trusted
+developer exploring a local database where arbitrary SQL is the intended
+power.
+
+It is a poor model-facing production boundary when a tool accepts SQL, table
+names, columns, predicates, tenant identifiers, or credentials chosen by the
+model. Prompt instructions and SQL blocklists do not remove that authority.
+Read-only credentials limit writes but can still permit broad or cross-tenant
+reads.
+
+Audit a server before adopting Runner or any other replacement:
+
+```bash
+npx -y @synapsor/runner audit --example dangerous-db-mcp
+npx -y @synapsor/runner audit ./tools-list.json
+```
+
+The audit is a structural review, not a penetration test or certification.
+
+## Read-Only Database Access
+
+Direct read-only access is often sufficient when:
+
+- the agent is used by trusted internal developers;
+- the database role can see only the rows and columns those users may see;
+- restricted views or PostgreSQL row-level security enforce tenant scope;
+- query cost and result size are bounded independently;
+- no proposal, approval, receipt, or replay record is required.
+
+Read-only does not mean harmless. Sensitive fields, cross-tenant records,
+expensive queries, and data useful for later attacks can all be exposed without
+a write. Keep the credential least-privileged and test the database policy as
+the real authorization floor.
+
+## Hand-Built Application Tools
+
+A narrow application endpoint or stored procedure is often the best answer for
+one or two stable operations. Trusted code should choose a fixed parameterized
+query, derive tenant and principal scope from authenticated state, validate
+business rules, and return only the required fields.
+
+This may be enough when one team owns the entire path and does not need a
+shared contract or review ledger. The team must still design and test:
+
+- immutable intent and idempotency under retries;
+- stale-data and concurrent-write conflicts;
+- approval identity and quorum outside the model;
+- exact before/after evidence and affected-row bounds;
+- receipts, investigation, replay, and ambiguous-crash handling.
+
+Runner can also route an approved proposal to an app-owned executor. Use that
+boundary for external side effects, multi-table transactions, free-form
+application logic, and operations the built-in guarded adapters intentionally
+do not support.
+
+## Synapsor Runner
+
+Runner is useful when the model should receive reviewed semantic capabilities
+instead of SQL and the organization needs the same trust mechanics across
+tools or teams:
+
+- trusted tenant and principal values stay outside model arguments;
+- visible and kept-out fields are reviewed in one portable contract;
+- model-facing writes create exact proposals without changing source data;
+- activation, approval, apply, and compensation remain outside MCP;
+- guarded apply rechecks scope, policy, conflict, bounds, and idempotency;
+- evidence, proposal history, receipts, and replay preserve the lifecycle.
+
+This is not magic and it is not a claim that these mechanics cannot be built in
+application code. Runner packages a specific enforcement and evidence model so
+each integration does not invent a subtly different one.
+
+## What Runner Does Not Protect
+
+Runner governs traffic that passes through its reviewed capabilities. It does
+not:
+
+- prevent prompt injection or make arbitrary SQL safe;
+- stop a separate raw database tool, leaked credential, or application bypass;
+- replace PostgreSQL RLS, restricted views, database grants, or network policy;
+- make a deployment compliant with HIPAA, PCI DSS, SOC 2, or another standard;
+- provide backups, disaster recovery, or protection from a trusted host or
+  database administrator;
+- safely infer tenant scope, hidden fields, approval policy, or write authority.
+
+Keep least-privilege roles, RLS or tenant-restricted views, encryption,
+monitoring, tested backups, and application authorization underneath Runner.
+For PostgreSQL, prefer transaction-bound RLS when the topology supports it. For
+MySQL, use restricted views, per-tenant credentials, or isolated deployments
+where required.
+
+## A Practical Evaluation
+
+1. Audit the model-facing tools and identify who chooses SQL, tenant scope,
+   fields, predicates, approval, and commit timing.
+2. Keep direct read-only access if database policy already provides the exact
+   safe boundary and no review lifecycle is needed.
+3. Keep a hand-built tool if it is narrow, well-tested, and its operational
+   guarantees are sufficient.
+4. Try Runner on one consequential staging action when you need an exact Data
+   PR, approval outside the agent, guarded commit, receipt, and replay.
+
+Continue with [Connect Your Own Database](getting-started-own-database.md),
+[Security Boundary](security-boundary.md), or the deeper [build-versus-adopt
+analysis](why-synapsor-vs-app-guardrails.md).

package/docs/capability-authoring.md

@@ -22,6 +22,49 @@ store path, MCP transport settings, and local development flags. The model sees
 semantic capabilities such as `billing.inspect_invoice`, not raw SQL, table
 names, write credentials, approval tools, or commit tools.
 
+## Code-First TypeScript Path
+
+Applications that prefer TypeScript can author the same canonical contract
+through the optional `@synapsor/runner/authoring` frontend:
+
+```ts
+import { defineCapability } from "@synapsor/runner/authoring";
+
+export const waiveLateFee = defineCapability({
+  name: "billing.propose_late_fee_waiver",
+  kind: "proposal",
+  context: "local_operator",
+  source: "app_postgres",
+  subject: { resource: "billing.invoice", primary_key: "id", tenant_key: "tenant_id" },
+  args: {
+    invoice_id: { type: "string", required: true, max_length: 128 },
+    reason: { type: "string", required: true, max_length: 500 },
+  },
+  lookup: { id_from_arg: "invoice_id" },
+  visible_fields: ["id", "tenant_id", "late_fee_cents", "waiver_reason", "updated_at"],
+  kept_out_fields: ["card_token", "internal_risk_note"],
+  evidence: { required: true, query_audit: true },
+  max_rows: 1,
+  proposal: {
+    action: "waive_late_fee",
+    operation: { kind: "update" },
+    allowed_fields: ["late_fee_cents", "waiver_reason"],
+    patch: { late_fee_cents: { fixed: 0 }, waiver_reason: { from_arg: "reason" } },
+    numeric_bounds: { late_fee_cents: { minimum: 0, maximum: 10000 } },
+    conflict_guard: { column: "updated_at" },
+    approval: { mode: "human", required_role: "billing_lead" },
+    writeback: { mode: "direct_sql" },
+  },
+});
+```
+
+Compose typed resources, contexts, capabilities, workflows, and policies with
+`defineContract`, then use `contractJson` to write reviewable canonical JSON.
+`compileContract` validates and normalizes through `@synapsor/spec`; this API
+does not add semantics, raw SQL, or model-controlled predicates. The flagship
+[support/billing action](../examples/support-billing-agent/app/contract.ts)
+uses this frontend. JSON and DSL remain supported and conformance-equivalent.
+
 ## Contract/DSL Path
 
 Write a small DSL contract:
@@ -150,7 +193,7 @@ reviewed runner JSON capabilities. Current parity:
 | arg `minimum` | `ARG amount NUMBER MIN 1` | 0.1.8 | NUMBER args only. |
 | arg `maximum` | `ARG amount NUMBER MAX 2500` | 0.1.8 | NUMBER args only. |
 | arg `max_length` | `ARG reason TEXT MAX LENGTH 500` | 0.1.8 | STRING/TEXT args only. Legacy `MAX 500` is still accepted for existing DSL files, but `MAX LENGTH` is the reviewed spelling. |
-| arg `enum` | Not expressible in DSL yet | 0.1 | Use embedded JSON or generated contract JSON when enum allowlists are required. |
+| arg `enum` | `ARG risk_level STRING ENUM('low', 'medium', 'high') REQUIRED` | 1.4.121 | Supports 1..64 same-type string, number, or boolean values; duplicates and mixed types fail compilation. |
 | proposal `numeric_bounds` | `BOUND column 1..2500`, `BOUND column ..2500`, or `BOUND column 1..` | 0.1.8 | Applies to patched numeric columns. Strict mode warns when a NUMBER arg is patched without arg min/max or a matching `BOUND`. |
 | proposal `transition_guards` | `TRANSITION status ALLOW pending -> approved\|rejected` or `TRANSITION status FROM current_status ALLOW open -> closed` | 0.1.8 | Values are state strings; use `|` for multiple target states. |
 | proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | If omitted, DSL emits an explicit weak-guard acknowledgement. Prefer a real row-version column. |

package/docs/client-recipes.md

@@ -0,0 +1,218 @@
+# Client And Framework Recipes
+
+Every recipe on this page connects to the same reviewed Runner boundary:
+
+- `support.inspect_customer`
+- `support.propose_plan_credit`
+
+The model never receives SQL, database credentials, trusted tenant identity,
+approval, apply, activation, or revert authority. A proposal call returns an
+exact effect with `source_database_changed: false`; a human reviews and applies
+it outside the model-facing client.
+
+Checked-in files live in
+[`examples/support-plan-credit/mcp-client-examples/`](../examples/support-plan-credit/mcp-client-examples/).
+They contain command paths and environment-variable names only.
+
+## Evidence Labels
+
+| Label | Meaning |
+| --- | --- |
+| Host-tested | The named host was exercised manually at the recorded version. |
+| Configuration-tested | The named host's current CLI or config parser accepted the recipe. |
+| Protocol-tested | Runner completed MCP initialization and `tools/list` through the official MCP SDK using the same command/transport. |
+| Recipe-checked | The file is syntax-checked, secret-scanned, and matched to current official framework documentation. Its framework runtime was not executed here. |
+| Unknown | No compatibility claim is made. |
+
+Protocol evidence is not presented as proof of editor UI behavior. Current
+evidence is summarized in [Host Compatibility](host-compatibility.md).
+
+## Shared Preflight
+
+Run from the Runner repository root after supplying your own environment-bound
+staging credentials and trusted scope:
+
+```bash
+npx -y -p @synapsor/runner synapsor-runner tools preview \
+  --config ./examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
+The list must include the two semantic tools above and must not include
+`execute_sql`, approve, apply, commit, activation, or revert tools.
+
+Use this exact proposal input in each client:
+
+```json
+{
+  "customer_id": "CUS-3001",
+  "credit_cents": 2500,
+  "reason": "SLA outage ticket SUP-481"
+}
+```
+
+Expected result: a proposal id, exact before/after effect, evidence handle, and
+`source_database_changed: false`. Review it outside the client in the secured
+Workbench or operator CLI. Do not add an approval or apply MCP server/tool to
+make the client flow feel shorter.
+
+## Cursor
+
+**Status:** configuration-tested and protocol-tested with Cursor 3.7.21 on
+Linux; final manual editor UI verification remains a release gate.
+
+Use Runner's owned project lifecycle:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run \
+  --config ./examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner mcp install cursor --project --yes \
+  --config ./examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner mcp status cursor --project --check-launch
+```
+
+Ask Cursor to inspect `CUS-3001`, then call
+`support.propose_plan_credit` with the shared input. Review the Data PR outside
+the model-facing tool surface.
+
+## Claude Desktop
+
+**Status:** configuration-parsed and protocol-tested; manual Desktop UI
+behavior is not claimed.
+
+Merge
+[`claude-desktop.json`](../examples/support-plan-credit/mcp-client-examples/claude-desktop.json)
+into Claude Desktop's `mcpServers`, restart the app, and verify the exact tool
+list. Then ask for the shared proposal call.
+
+## Claude Code
+
+**Status:** configuration-tested with Claude Code 2.1.216 and
+protocol-tested; a manual model-driven call remains a release gate.
+
+Run the checked command from the repository root:
+
+```bash
+bash ./examples/support-plan-credit/mcp-client-examples/claude-code.sh
+```
+
+Claude Code records project-scoped MCP configuration without embedding source
+credentials. It will print the exact proposal prompt after configuration.
+
+Official source checked 2026-07-20:
+[Claude Code MCP](https://code.claude.com/docs/en/mcp).
+
+## Codex
+
+**Status:** configuration-tested with Codex CLI 0.144.6 and protocol-tested;
+a manual model-driven call remains a release gate.
+
+Merge the contents of
+[`codex.config.toml`](../examples/support-plan-credit/mcp-client-examples/codex.config.toml)
+into the trusted project's `.codex/config.toml`, start Codex from the repository
+root, and ask it to list the Synapsor tools before making the shared proposal
+call.
+
+Official source checked 2026-07-20:
+[Codex MCP configuration](https://developers.openai.com/codex/mcp/).
+
+## VS Code
+
+**Status:** configuration-parsed and protocol-tested; manual VS Code UI
+behavior is not claimed.
+
+Copy or merge
+[`vscode.mcp.json`](../examples/support-plan-credit/mcp-client-examples/vscode.mcp.json)
+into `.vscode/mcp.json`. Start the server from VS Code, inspect the listed
+tools, and ask for the shared proposal call.
+
+Official source checked 2026-07-20:
+[VS Code MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
+
+## OpenAI Agents SDK
+
+**Status:** recipe-checked and underlying stdio/Streamable HTTP protocol-tested.
+The exact SDK examples remain protocol-only until their agent calls are run
+with an owner-supplied model API key.
+
+Install `@openai/agents`, then run either:
+
+- [`openai-agents-stdio.ts`](../examples/support-plan-credit/mcp-client-examples/openai-agents-stdio.ts)
+- [`openai-agents-streamable-http.ts`](../examples/support-plan-credit/mcp-client-examples/openai-agents-streamable-http.ts)
+
+Both examples instruct the agent to inspect the semantic tool list and create
+the shared proposal. OpenAI-safe aliases are enabled where required; canonical
+Synapsor capability names remain in result metadata.
+
+Official source checked 2026-07-20:
+[OpenAI Agents SDK MCP guide](https://openai.github.io/openai-agents-js/guides/mcp/).
+
+## LangChain And LangGraph
+
+**Status:** recipe-checked and protocol-only.
+
+Install `@langchain/mcp-adapters` and run
+[`langchain.mjs`](../examples/support-plan-credit/mcp-client-examples/langchain.mjs).
+It calls `getTools()`, refuses an unsafe tool surface, and invokes the proposal
+tool directly. The returned proposal still requires human review outside the
+agent.
+
+Official source checked 2026-07-20:
+[LangChain JavaScript MCP](https://docs.langchain.com/oss/javascript/langchain/mcp).
+LangGraph can use the same LangChain MCP tools; no Synapsor-specific SDK is
+needed.
+
+## Google ADK
+
+**Status:** recipe-checked and protocol-only.
+
+Install the current Google ADK Python package and run
+[`google-adk.py`](../examples/support-plan-credit/mcp-client-examples/google-adk.py)
+with `GOOGLE_ADK_MODEL` and the provider credential supplied through the
+environment. The `McpToolset` is filtered to the two reviewed Synapsor tools.
+
+Official source checked 2026-07-20:
+[Google ADK MCP tools](https://adk.dev/tools-custom/mcp-tools/).
+
+## LlamaIndex
+
+**Status:** recipe-checked and protocol-only.
+
+Install `llama-index-tools-mcp` and run
+[`llamaindex.py`](../examples/support-plan-credit/mcp-client-examples/llamaindex.py).
+It uses `BasicMCPClient` to list tools and make the shared proposal call without
+requiring a model-provider API.
+
+Official source checked 2026-07-20:
+[LlamaIndex MCP tools](https://developers.llamaindex.ai/python/examples/tools/mcp/).
+
+## Generic MCP Clients
+
+**Status:** protocol-tested through the official TypeScript MCP SDK.
+
+Use:
+
+- [`generic-stdio.mjs`](../examples/support-plan-credit/mcp-client-examples/generic-stdio.mjs)
+- [`generic-streamable-http.mjs`](../examples/support-plan-credit/mcp-client-examples/generic-streamable-http.mjs)
+
+Each script performs MCP initialization, validates `tools/list`, rejects
+model-visible commit authority, and makes the shared proposal call. The HTTP
+script reads its bearer token from `SYNAPSOR_RUNNER_HTTP_TOKEN`; it never embeds
+one.
+
+Official source checked 2026-07-20:
+[Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client).
+
+## Verify The Checked Recipes
+
+```bash
+corepack pnpm test:mcp-client-configs
+```
+
+That deterministic gate syntax-checks and secret-scans every recipe and proves
+the shared stdio tool surface. To additionally make the proposal call against
+the disposable support-plan-credit PostgreSQL fixture, set
+`SYNAPSOR_CLIENT_RECIPES_CALL=1` after exporting the fixture's environment.
+The call creates a proposal but performs no approval or source mutation.

package/docs/contract-testing.md

@@ -11,10 +11,11 @@ synapsor-runner contract test \
   --config ./synapsor.runner.json
 ```
 
-Static mode checks tool exposure, operator-only boundaries, argument limits,
-transition guards, bounded-set caps, and other assertions that do not require a
-database. Add `--live` to call the actual MCP runtime for scoped reads,
-proposals, evidence/replay redaction, and source-unchanged checks.
+Static mode checks tool exposure, operator-only boundaries, trusted scope,
+evidence and approval requirements, exact proposal effects, conflict guards,
+argument limits, transition guards, bounded-set caps, and other assertions that
+do not require a database. Add `--live` to call the actual MCP runtime for
+scoped reads, proposals, evidence/replay redaction, and source-unchanged checks.
 
 ```bash
 synapsor-runner contract test \
@@ -37,9 +38,10 @@ Summary: 6 passed / 0 failed / 6 total
 ```
 
 Supported assertions cover valid scoped tools, cross-tenant denial,
-same-tenant cross-principal denial, kept-out
-fields, argument constraints, transition guards, set caps, unchanged source
-state before approval, and the absence of model-facing approval/writeback.
+same-tenant cross-principal denial, trusted tenant/principal scope, required
+evidence, approval-policy boundaries, kept-out fields, argument constraints,
+transition guards, set caps, unchanged source state before approval, and the
+absence of model-facing approval/writeback.
 Trusted tenant and principal values belong in test setup, not tool arguments.
 
 Use `cross_principal_deny` to prove both the allowed and denied sides of one

package/docs/cursor-plugin.md

@@ -0,0 +1,78 @@
+# Cursor plugin
+
+The Synapsor Cursor plugin is an official-format Cursor plugin under
+`plugins/cursor/synapsor`. It packages the project-scoped Runner MCP server,
+`/synapsor-protect`, and thin Cursor wrappers over Runner's canonical Safe Action
+instructions.
+
+Current implementation evidence was checked against Cursor's public plugin,
+plugin-reference, MCP, and deeplink documentation on 2026-07-20:
+
+- <https://cursor.com/docs/plugins>
+- <https://cursor.com/docs/reference/plugins>
+- <https://cursor.com/docs/mcp>
+- <https://cursor.com/docs/reference/deeplinks>
+
+The locally installed Cursor version used for validation is recorded in
+`development/runner-1.5.3-progress.md`. Protocol/static validation is not a
+claim that Cursor Marketplace review has completed.
+
+## What the plugin installs
+
+- one stdio MCP server pinned to `@synapsor/runner@1.5.3`;
+- one `/synapsor-protect` agent command;
+- one discoverable Safe Action skill;
+- one file-scoped rule for `synapsor/actions/**/*.ts`;
+- no hooks, automatic shell execution, credentials, or activation path.
+
+The MCP entry uses Cursor's documented `${workspaceFolder}` interpolation for
+`synapsor.runner.json` and `.synapsor/local.db`. It exposes only `mcp serve`.
+Approval, apply, activation, commit, and revert remain outside MCP.
+
+## Build and verify
+
+```bash
+corepack pnpm build:cursor-plugin
+corepack pnpm verify:cursor-plugin
+```
+
+The verifier checks the manifest and component formats, version pin, project
+paths, secret-free package contents, command authority boundary, deterministic
+package inventory, disposable local install/reinstall/removal, preservation of
+unrelated Cursor configuration, and paths containing spaces.
+
+## Marketplace listing copy
+
+**Name:** Synapsor
+
+**Short description:** Turn one real application data change into a disabled,
+reviewable MCP action without giving the Cursor agent SQL or commit authority.
+
+**Security summary:** The plugin contains no database credentials or trusted
+identity. Cursor can draft and validate disabled actions. Only a human using the
+secured localhost Workbench can activate a reviewed digest; approval and apply
+remain outside the model-facing MCP surface.
+
+Required listing media:
+
+- committed Synapsor logo from `assets/logo.svg`;
+- screenshot of `/synapsor-protect` producing a disabled draft;
+- screenshot of the Workbench exact-effect review and digest confirmation;
+- 20-to-40-second GIF showing proposal, unchanged source, external approval,
+  guarded receipt, idempotent retry, and stale conflict.
+
+## Submission checklist
+
+- [ ] Runner 1.5.3 package and plugin version agree.
+- [ ] `corepack pnpm verify:cursor-plugin` passes from a clean checkout.
+- [ ] Plugin is manually loaded in current stable Cursor at workspace scope.
+- [ ] `/synapsor-protect` drafts and validates without activation.
+- [ ] Exact Cursor `tools/list` contains only reviewed semantic tools.
+- [ ] Another direct-write MCP server triggers Runner's bypass warning.
+- [ ] Logo and listing media contain no secrets, local paths, or customer data.
+- [ ] Privacy/security copy matches the OSS security boundary.
+- [ ] Public repository and release links resolve.
+- [ ] Owner submits the repository at <https://cursor.com/marketplace/publish>.
+
+The final submission remains an explicit owner action. Do not claim that local
+installation or static validation equals Marketplace approval.