@synapsor/runner 1.5.0 → 1.5.4

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
@@ -45,10 +49,13 @@ developer path. Streamable HTTP implements MCP initialize/session behavior over
 an authenticated `/mcp` endpoint. The JSON-RPC bridge is intentionally smaller
 and does not implement MCP initialize/session behavior.
 
-HTTP requires bearer auth by default:
+HTTP requires Bearer authentication by default. `Bearer` is the HTTP
+presentation scheme; for this loopback example it carries one opaque random
+endpoint token, not a user identity or JWT. The operator generates it and
+provisions the same environment value to Runner and the authorized client:
 
 ```bash
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
 npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
@@ -84,8 +91,10 @@ npx -y -p @synapsor/runner synapsor-runner tools preview \
   --alias-mode openai
 ```
 
-Use private networking/TLS before exposing HTTP MCP beyond localhost. Details:
-[HTTP MCP](http-mcp.md).
+Do not distribute one opaque token to unrelated users or tenants. A
+non-loopback service also needs direct TLS or an explicitly trusted TLS proxy;
+a shared service uses short-lived signed JWTs issued by your identity provider,
+with tenant/principal bound from verified claims. Details: [HTTP MCP](http-mcp.md).
 
 ## Generate A Client Snippet
 
@@ -138,8 +147,10 @@ npx -y -p @synapsor/runner synapsor-runner mcp configure \
 When the destination already exists, Synapsor Runner creates a timestamped
 backup before writing. Noninteractive scripts must add `--yes`.
 
-The command writes only the local stdio MCP command and args. It does not write
-database URLs or passwords into the client config.
+The command writes only command arguments and, for HTTP clients, credential
+environment references plus external authorization metadata. It never writes
+database URLs, passwords, token values, client secrets, or refresh tokens into
+the generated client config.
 
 No separate Apps flag is required. A compatible host discovers
 `ui://synapsor/proposal-review.html` from proposal-tool metadata. The app can
@@ -161,8 +172,6 @@ the current `latest` release.
 For standard app/server HTTP MCP mode:
 
 ```bash
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
-
 npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./examples/mcp-postgres-billing/synapsor.runner.json \
   --store ./.synapsor/local.db \
@@ -170,6 +179,8 @@ npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
 ```
 
 For the smaller JSON-RPC bridge, use `synapsor-runner mcp serve-http` instead.
+The bridge is not standard Streamable HTTP and cannot provide claim-bound MCP
+sessions, so do not use it for a shared identity deployment.
 
 ## Generic stdio Client
 
@@ -191,9 +202,9 @@ For the smaller JSON-RPC bridge, use `synapsor-runner mcp serve-http` instead.
         "./.synapsor/local.db"
       ],
       "env": {
-        "BILLING_POSTGRES_READ_URL": "postgresql://synapsor_reader:...@localhost:55433/synapsor_runner_mcp_billing",
-        "SYNAPSOR_TENANT_ID": "acme",
-        "SYNAPSOR_PRINCIPAL": "local_billing_agent"
+        "BILLING_POSTGRES_READ_URL": "${BILLING_POSTGRES_READ_URL}",
+        "SYNAPSOR_TENANT_ID": "${SYNAPSOR_TENANT_ID}",
+        "SYNAPSOR_PRINCIPAL": "${SYNAPSOR_PRINCIPAL}"
       }
     }
   }
@@ -261,6 +272,12 @@ examples/mcp-client-configs/vscode.json
 
 Each example uses the same stdio command/args/env structure. Replace the placeholder environment variables in your client settings or shell environment.
 
+These checked-in desktop examples use stdio, which is the recommended local
+path for Claude Desktop, Cursor, and VS Code. The OpenAI Agents SDK recipe is
+syntax-checked, and the HTTP endpoint is interoperability-tested with the
+official MCP TypeScript client; repository CI does not claim to exercise an
+identity-provider login inside every third-party host.
+
 Do not add a write database URL to the MCP server environment unless you are intentionally running a local review/writeback demo. For normal read/proposal tool calls, use the read URL and trusted context values only.
 
 Before documenting a client UI as officially tested, verify:

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:
@@ -86,19 +115,25 @@ metadata preserves the canonical dotted Synapsor capability name.
 ## Streamable HTTP
 
 ```bash
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
+
 synapsor-runner mcp serve \
   --transport streamable-http \
   --alias-mode openai \
   --host 127.0.0.1 \
   --port 8766 \
   --config ./synapsor.runner.json \
-  --store ./.synapsor/local.db
+  --store ./.synapsor/local.db \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
 Connect a standard Streamable HTTP MCP client to
-`http://127.0.0.1:8766/mcp`. Keep it on loopback for local development. For a
-network deployment, terminate TLS, require authentication, restrict network
-access, and follow the [production guide](production.md).
+`http://127.0.0.1:8766/mcp` with `Authorization: Bearer` loaded from the same
+protected environment value. Keep it on loopback for local development. A
+non-loopback listener refuses to bind without direct TLS, an explicitly trusted
+TLS proxy, or authenticated emergency break glass. Shared deployments require
+identity-provider-issued signed claims. Follow [HTTP MCP](http-mcp.md) and the
+[production guide](production.md).
 
 Use `--alias-mode openai` for the OpenAI Agents SDK. Omit it for clients that
 accept canonical dotted names, or use `--alias-mode both` only during a planned

package/docs/openai-agents-sdk.md

@@ -8,7 +8,7 @@ surface.
 ## Start Runner
 
 ```bash
-export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-local-token"
+export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
 npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
@@ -17,6 +17,11 @@ npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
   --alias-mode openai
 ```
 
+For this loopback/single-service example, the operator provisions that same
+opaque value to the Runner process and the Python client through protected
+environment injection. HTTP `Bearer` describes how the credential is sent; it
+does not make the opaque value a JWT, and Runner does not issue it.
+
 `--alias-mode openai` is important because OpenAI function/tool names cannot
 contain dots. Runner exposes names such as `billing__inspect_invoice` to the
 model and maps calls back to canonical Synapsor capability names such as
@@ -28,7 +33,8 @@ model and maps calls back to canonical Synapsor capability names such as
 npx -y -p @synapsor/runner synapsor-runner mcp client-config \
   --client openai-agents \
   --config ./synapsor.runner.json \
-  --store ./.synapsor/local.db
+  --store ./.synapsor/local.db \
+  --client-access-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
 ```
 
 The generated output includes:
@@ -41,6 +47,14 @@ The generated output includes:
 It does not include database URLs, passwords, write credentials, API keys, or
 bearer token values.
 
+For a shared deployment, configure `http_claims`, asymmetric `session_auth`, and
+`http_security.oauth_resource`, then use a separate env name such as
+`SYNAPSOR_MCP_ACCESS_TOKEN`. Your configured identity provider issues that
+short-lived token for the protected-resource audience; Runner validates it on
+every request but never stores end-user passwords or issues/refreshes tokens.
+The generated client URL is the configured HTTPS protected resource. See
+[HTTP MCP](http-mcp.md) for the complete profile and TLS/proxy requirements.
+
 ## Sanity Check
 
 Before giving the agent a real task, ask it to inspect one known object and

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

package/docs/production.md

@@ -421,6 +421,36 @@ synapsor-runner activity search --proposal wrp_... --store ./.synapsor/local.db
 
 ## Deployment Recipes
 
+### Networked MCP boundary
+
+Prefer stdio when one local client can launch Runner. For Streamable HTTP,
+choose the deployment profile before binding:
+
+- loopback: authenticated opaque endpoint token by default;
+- remote single-tenant: direct TLS or an explicitly trusted TLS proxy, plus one
+  high-entropy rotated service token;
+- shared multi-user/tenant: direct TLS or trusted proxy, asymmetric signed JWT
+  sessions, exact issuer/audience/resource, verified tenant/principal claims,
+  and RFC 9728 protected-resource metadata.
+
+An opaque token is generated by the operator and provisioned to server and
+authorized client through environment/secret-manager injection. Runner does not
+issue it. In a shared deployment, the configured external identity provider
+issues short-lived access tokens; Runner verifies them but does not store user
+passwords or issue refresh tokens. See [HTTP MCP](http-mcp.md) before exposing a
+listener outside loopback.
+
+Run the transport-specific doctor check before serving:
+
+```bash
+synapsor-runner doctor \
+  --config ./synapsor.runner.json \
+  --transport streamable-http \
+  --host 0.0.0.0 \
+  --trusted-tls-proxy \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+```
+
 ### Docker Compose Shape
 
 Use Compose to run the MCP server next to your app and database network. Keep
@@ -436,14 +466,20 @@ export SYNAPSOR_SECRET_MAP='{
 }'
 
 synapsor-runner mcp serve-streamable-http \
+  --host 0.0.0.0 \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
+  --trusted-tls-proxy \
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
   --secrets-provider aws-secretsmanager-cli \
   --secret-map-env SYNAPSOR_SECRET_MAP
 ```
 
 The AWS provider shells out to `aws secretsmanager get-secret-value`; the runner
-logs only how many target env vars were loaded or skipped.
+logs only how many target env vars were loaded or skipped. This command assumes
+`http_security.deployment: single_tenant`, an exact `allowed_hosts` list, and a
+TLS proxy on a private hop. Use asymmetric claim-bound identity instead for a
+shared user/tenant service.
 
 ```yaml
 services:
@@ -453,22 +489,30 @@ services:
     command: >
       sh -lc "npm install -g @synapsor/runner &&
       synapsor-runner up --review --config /config/synapsor.runner.json
-      --store /data/local.db --host 0.0.0.0 --port 8766"
+      --store /data/local.db --host 0.0.0.0 --port 8766
+      --trusted-tls-proxy --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN"
     environment:
       SYNAPSOR_DATABASE_READ_URL: ${SYNAPSOR_DATABASE_READ_URL}
       SYNAPSOR_DATABASE_WRITE_URL: ${SYNAPSOR_DATABASE_WRITE_URL}
       SYNAPSOR_TENANT_ID: ${SYNAPSOR_TENANT_ID}
       SYNAPSOR_PRINCIPAL: ${SYNAPSOR_PRINCIPAL}
+      SYNAPSOR_RUNNER_HTTP_TOKEN: ${SYNAPSOR_RUNNER_HTTP_TOKEN}
     volumes:
       - ./synapsor.runner.json:/config/synapsor.runner.json:ro
       - synapsor-runner-data:/data
-    ports:
-      - "8766:8766"
+    expose:
+      - "8766"
 
 volumes:
   synapsor-runner-data:
 ```
 
+This shape deliberately does not publish the Runner port to the host. Put a
+TLS-terminating proxy on the same private container network, publish only that
+proxy, preserve the reviewed external Host, and prevent direct client access to
+Runner. If Runner itself owns TLS, replace `--trusted-tls-proxy` with protected
+`--tls-cert-env`/`--tls-key-env` PEM references.
+
 ### systemd Shape
 
 ```ini
@@ -491,10 +535,20 @@ PrivateTmp=true
 WantedBy=multi-user.target
 ```
 
-Put database credentials in `/etc/synapsor-runner.env` or your system secret
-manager, not in `synapsor.runner.json`.
+Put database credentials and the random loopback endpoint token in
+`/etc/synapsor-runner.env` or your system secret manager, not in
+`synapsor.runner.json`. The systemd command binds loopback, so a local trusted
+proxy may connect to it without exposing cleartext Bearer traffic on the
+network.
 
-## TLS And SSL
+## TLS, mTLS, And Database SSL
+
+For MCP HTTP, Runner-owned TLS reads certificate/key PEM only from named
+environment variables. Optional mTLS verifies client certificates against an
+explicit CA and supplements Bearer authentication; it does not replace
+per-session tenant/principal identity in a shared service. A trusted proxy must
+be protected from direct bypass and must not inject forwarded tenant/principal
+headers as authority.
 
 For staging or production-like databases:
 
@@ -507,6 +561,17 @@ For staging or production-like databases:
 For disposable local Docker fixtures, `sslmode=disable` is acceptable when the
 database is bound to loopback and contains only test data.
 
+Rotate credentials independently:
+
+- opaque endpoint token: active plus at most one previous env during rollout;
+- HS256 session key: active plus one previous key, only for controlled use;
+- asymmetric JWT key: publish a new `kid`, honor bounded JWKS cache/cooldown,
+  then retire the old public key after clients rotate;
+- TLS certificate and mTLS client CA: roll protected PEM material and restart
+  instances without changing tenant identity;
+- database and handler credentials: rotate their separate env/secret-manager
+  entries without reusing an MCP or Cloud credential.
+
 ## Health And Doctor
 
 Run these before exposing tools to an agent: