@synapsor/runner 1.5.0 → 1.5.4

package/docs/README.md

@@ -23,6 +23,10 @@ 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,
@@ -44,10 +48,14 @@ 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
@@ -64,6 +72,14 @@ 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
@@ -90,6 +106,9 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 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.
@@ -97,6 +116,10 @@ no-database demo, wire your database, then read deeper concepts.
   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

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:
@@ -153,7 +196,8 @@ reviewed runner JSON capabilities. Current parity:
 | 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. |
+| proposal `conflict_guard` | `CONFLICT GUARD updated_at` | 0.1 | Required for ordinary UPDATE authoring. It compiles to an exact version-column check. Omission fails instead of silently weakening concurrency protection. |
+| proposal weak `conflict_guard` | `CONFLICT GUARD WEAK ROW HASH ACKNOWLEDGED` | 1.4.4 | Explicit legacy escape hatch for an ordinary single-row source-DB UPDATE only. It hashes the captured projection and may miss concurrent changes outside that projection. It is rejected for DELETE, reversible writes, bounded sets, and Runner-ledger authority. |
 | proposal `approval` | `APPROVAL ROLE billing_lead` | 0.1 | Local mode records the required role; enforcement is still outside the model-facing MCP tool. |
 | proposal `approval.required_approvals` | `REQUIRE 2 APPROVALS` | 1.1 | Optional 1..10 distinct-reviewer quorum; defaults to 1. |
 | proposal `writeback` | `WRITEBACK DIRECT SQL`, `WRITEBACK APP HANDLER EXECUTOR name`, `WRITEBACK CLOUD WORKER`, `WRITEBACK NONE` | 0.1.7 | Handler URLs/tokens stay in `synapsor.runner.json`; contracts carry only the handler name. |
@@ -480,6 +524,8 @@ Canonical Synapsor names use dots, such as `billing.inspect_invoice`. Some
 clients require function-safe names. Use:
 
 ```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+
 synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
@@ -490,6 +536,8 @@ synapsor-runner mcp serve-streamable-http \
 The model sees aliases such as `billing__inspect_invoice`. Runner includes the
 canonical name in tool metadata and descriptions so audit/replay still use the
 real capability name.
+This loopback token is opaque endpoint access, not tenant identity. See
+[HTTP MCP](http-mcp.md) before using a network listener.
 
 ## Why Not `execute_sql`
 

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/cloud-mode.md

@@ -19,6 +19,24 @@ The local Runner still keeps database credentials in your environment. MCP
 client config snippets contain command paths and Runner arguments, not database
 URLs or write credentials.
 
+Keep Cloud and MCP credentials distinct:
+
+| Credential | Purpose | Issuer/provisioner | Never substitutes for |
+| --- | --- | --- | --- |
+| Cloud user session | Human control-panel/CLI identity and subscription/RBAC checks | Synapsor Cloud identity system | MCP tenant identity or database access |
+| Cloud service/API key | Contract push and scoped Cloud administration | Synapsor Cloud | MCP endpoint access |
+| Source-scoped Runner token | Runner registration, heartbeat, lease, activity, and result calls for one Cloud source | Synapsor Cloud Connect Runner flow | Model-facing MCP access or operator approval |
+| Opaque MCP endpoint token | Loopback or explicitly single-tenant HTTP endpoint access | Customer operator/secret manager | User/tenant identity |
+| Signed MCP access JWT | Shared HTTP client identity and verified tenant/principal claims | Customer identity provider/authorization server | Cloud subscription credential or DB role |
+| Operator credential | Activation, approval, apply, reconcile, dead-letter, and revert authority | Customer operator identity system | Model-facing MCP capability |
+| Database/handler credential | Local read or trusted post-approval effect | Customer secret manager/database/application | Cloud or MCP authentication |
+
+Cloud-linked mode does not require networked MCP: a desktop client can still
+launch the local Runner over stdio. If the local Runner exposes Streamable HTTP,
+the same [HTTP MCP](http-mcp.md) channel and identity profiles apply. Cloud API
+keys and source-scoped Runner tokens are never accepted as shortcuts for MCP
+session authentication.
+
 ## Trust Boundary
 
 ```text

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.

package/docs/database-enforced-scope.md

@@ -11,6 +11,10 @@ from model arguments. Choose the database enforcement mode deliberately:
 
 These modes are defense in depth, not substitutes for least-privilege roles,
 restricted views, application authorization, or staging-first validation.
+HTTP endpoint authentication is another independent layer: it establishes who
+may call Runner and, for signed shared sessions, which trusted tenant/principal
+claims are bound. It does not turn `application_scope` into database-enforced
+isolation. See [HTTP MCP](http-mcp.md).
 
 ## Default: Application-Level Scope
 
@@ -49,6 +53,10 @@ with environment-bound capabilities.
 For shared production HTTP, prefer asymmetric JWT verification so Runner holds
 only public verification material. HS256 remains useful for local development
 and controlled deployments but gives Runner access to the signing secret.
+Also declare `http_security.deployment: shared`, an exact HTTPS
+audience/protected resource, a direct-TLS or trusted-proxy channel, and exact
+Host/Origin policy. A static endpoint token cannot supply shared tenant or
+principal identity.
 
 Run `doctor --json` or `tools preview --json` to inspect the effective
 per-source assurance mode and trusted-context binding. Server startup prints