@synapsor/runner 0.1.9 → 0.1.11

package/docs/README.md

@@ -49,6 +49,8 @@ then read the concepts once the safety boundary is visible.
 
 - [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.
 - `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 +98,10 @@ then read the concepts once the safety boundary is visible.
   scope, database roles, receipt grants, local ledger backup, restart behavior,
   Docker/systemd shapes, TLS, and release-gate expectations.
 - [Cloud Mode](cloud-mode.md): what stays local and what Cloud-linked mode adds.
+- [Cloud Push](cloud-push.md): register a validated local contract in the
+  versioned Cloud registry.
+- [Runner Bundles](runner-bundles.md): download the same immutable contract and
+  its local MCP wiring from Cloud.
 - [Release Notes](release-notes.md): release history and behavior changes.
 - [Release Policy](release-policy.md): stable gates and publish verification.
 - [Licensing](licensing.md): Apache-2.0 scope, trademark boundary, and what is

package/docs/cloud-mode.md

@@ -6,6 +6,8 @@ guarded writeback, or replay.
 
 Cloud-linked mode is for teams that need a shared control plane:
 
+- versioned canonical contract registry and server-computed digests;
+- Cloud-to-local runner bundle downloads;
 - team approvals and RBAC;
 - hosted evidence/replay search;
 - runner registration and heartbeat;
@@ -17,6 +19,22 @@ The local runner still keeps database credentials in your environment. MCP
 client config snippets should contain command paths and runner arguments, not
 database URLs or write credentials.
 
+Push and retrieve the portable contract without moving database credentials
+into Cloud:
+
+```bash
+synapsor-runner cloud push ./synapsor.contract.json --dry-run
+synapsor-runner cloud push ./synapsor.contract.json \
+  --workspace "$SYNAPSOR_WORKSPACE_ID" \
+  --name support-plan-credit
+```
+
+See [Cloud Push](cloud-push.md) and [Runner Bundles](runner-bundles.md).
+
+Cloud registry storage preserves approval policies but does not, by itself,
+mean hosted policy enforcement is enabled. Local Runner enforcement and hosted
+Cloud approval enforcement are separate runtime boundaries.
+
 Run the local smoke for this mode with:
 
 ```bash

package/docs/cloud-push.md

@@ -0,0 +1,54 @@
+# Push A Contract To Synapsor Cloud
+
+Cloud push registers the same canonical contract that you validate and run
+locally. Cloud stores a normalized immutable version, computes its digest,
+records the actor, and makes the safety boundary visible in the workspace
+registry.
+
+## Preview Without A Network Call
+
+```bash
+synapsor-runner cloud push ./synapsor.contract.json --dry-run
+synapsor-runner cloud push ./synapsor.contract.json --dry-run --json
+```
+
+Dry-run validates and normalizes locally. It performs no network request.
+
+## Push
+
+```bash
+export SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai"
+export SYNAPSOR_CLOUD_TOKEN="<workspace-scoped-token>"
+export SYNAPSOR_WORKSPACE_ID="<workspace-id>"
+
+synapsor-runner cloud push ./synapsor.contract.json \
+  --name support-plan-credit
+```
+
+The response includes the contract id, immutable version id, server-computed
+digest, summary counts, status, and registry path. Identical normalized content
+is idempotent; changed content creates the next version.
+
+Tokens are sent in the authorization header and are never part of the contract.
+Database URLs, passwords, private keys, and model-controlled tenant bindings
+are rejected by server-side validation.
+
+`SYNAPSOR_CLOUD_WORKSPACE` is accepted as an alias for
+`SYNAPSOR_WORKSPACE_ID`. Explicit `--workspace` wins over environment values.
+
+Cloud push fails before upload when local validation fails. HTTP failures are
+reported distinctly for invalid/expired tokens (`401`), insufficient workspace
+permission (`403`), missing workspace/API paths (`404`), registry conflicts
+(`409`), server validation (`422`), and Cloud/network failures. Error output
+does not echo the bearer token.
+
+## Cloud To Local
+
+Open **Contract registry** in the workspace, choose a version, and download its
+runner bundle. The ZIP contains the normalized contract, local runner wiring,
+placeholder environment file, README, and MCP client examples. It contains no
+live credentials or table rows.
+
+Cloud currently preserves approval policy definitions in the contract and
+bundle. Hosted approval-policy enforcement remains a separate Cloud feature;
+do not infer it from registry storage alone.

package/docs/current-scope.md

@@ -2,7 +2,7 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current alpha scope:
+Current `0.1.x` scope:
 
 - local semantic MCP tools for Postgres/MySQL-backed business actions;
 - schema inspection and guided config generation;

package/docs/local-mode.md

@@ -345,7 +345,7 @@ For CI or direct verification, use:
 corepack pnpm test:mcp-local
 ```
 
-It launches the official MCP stdio client transport against `synapsor-runner mcp serve`, exercises the Postgres billing, Postgres support, and MySQL orders examples, checks that source rows are unchanged before approval, approves locally, generates versioned writeback jobs, applies them, retries idempotently, and then proves stale-row conflict:
+It launches the official MCP stdio client transport against `synapsor-runner mcp serve`, exercises the Postgres billing, Postgres support, MySQL orders, and support plan-credit examples, checks that source rows are unchanged before approval, approves locally, generates versioned writeback jobs, applies them, retries idempotently, and then proves stale-row conflict:
 
 ```text
 The business state changed after the agent saw it, so Synapsor refused to commit.
@@ -360,14 +360,15 @@ corepack pnpm test:live-apply
 Prerequisites:
 
 - Docker daemon running;
-- local ports `55433`, `55434`, and `53307` available;
+- local ports `55433`, `55434`, `55438`, and `53307` available;
 - no Synapsor Cloud account, API key, hosted workspace, or production database.
 
 Expected output:
 
-- disposable Postgres billing, Postgres support, and MySQL orders containers start;
+- disposable Postgres billing, Postgres support, support plan-credit, and MySQL orders containers start;
 - MCP `tools/list` exposes reviewed semantic tools, not raw SQL;
 - proposal calls create exact before/after diffs while source rows remain unchanged;
+- the support plan-credit scenario proves `$25` policy auto-approval, `$100` human approval, and `$1000` bound rejection;
 - local approval happens outside MCP;
 - guarded writeback applies approved jobs and records receipts/replay;
 - idempotent retry returns the existing receipt;

package/docs/mcp-clients.md

@@ -0,0 +1,123 @@
+# MCP Client Configs
+
+Synapsor Runner exposes reviewed semantic tools over standard MCP. The model
+receives inspect/propose capabilities; it does not receive raw SQL, database
+credentials, approval commands, or apply commands.
+
+The complete copy-paste templates live in:
+
+- [`examples/support-plan-credit/mcp-client-examples/`](../examples/support-plan-credit/mcp-client-examples/)
+- every local `synapsor-runner contract bundle` output;
+- every downloadable Synapsor Cloud runner bundle.
+
+Before connecting a client, validate the local boundary:
+
+```bash
+synapsor-runner config validate --config ./synapsor.runner.json
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+Set database and trusted-context values in the environment that launches the
+MCP process. Keep real URLs and tokens in your shell or secret manager, not in
+the checked-in client JSON.
+
+## Stdio
+
+Use stdio for Claude Desktop, Cursor, and other local MCP clients:
+
+```json
+{
+  "command": "npx",
+  "args": [
+    "-y", "-p", "@synapsor/runner", "synapsor-runner",
+    "mcp", "serve", "--config", "./synapsor.runner.json",
+    "--store", "./.synapsor/local.db"
+  ]
+}
+```
+
+Relative paths are resolved from the MCP client's working directory. Use the
+project template when the client starts in your repository; replace the marked
+bundle path in the global template when it does not.
+
+### Claude Desktop
+
+1. Open Claude Desktop settings and choose the developer option to edit its MCP
+   configuration.
+2. Merge `claude-desktop.json` into the existing `mcpServers` object.
+3. Replace the marked working directory or use absolute paths when Claude does
+   not start in the bundle directory.
+4. Restart Claude Desktop completely, then confirm the two semantic tools are
+   listed.
+
+Claude Desktop launched from a graphical session may not inherit your terminal
+environment. Supply the required env values through the OS process environment
+or a local secret-manager wrapper; do not paste production credentials into a
+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.
+
+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.
+
+### OpenAI Agents SDK
+
+Install the SDK in your agent project and run either TypeScript template:
+
+```bash
+npm install @openai/agents
+```
+
+OpenAI function names cannot contain dots. The stdio template therefore starts
+Runner with `--alias-mode openai`; model-visible names use `__`, while result
+metadata preserves the canonical dotted Synapsor capability name.
+
+## Streamable HTTP
+
+```bash
+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
+```
+
+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).
+
+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
+migration where duplicate canonical/alias tools are acceptable.
+
+## Verify The Boundary
+
+```bash
+synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+synapsor-runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+The preview must list semantic capabilities and must not list `execute_sql`,
+approval/apply tools, database URLs, write credentials, or model-controlled
+tenant authority.
+
+## Troubleshooting
+
+- `ENOENT` or missing config: use absolute config/store paths.
+- empty tool list: run `contract validate`, then `tools preview` against the
+  exact config used by the client.
+- database connection failure: verify the client process received the read URL
+  and trusted tenant/principal env values.
+- OpenAI rejects a dotted name: start Runner with `--alias-mode openai`.
+- HTTP `initialize` failure: use `mcp serve --transport streamable-http`, not
+  the legacy `serve-http` JSON-RPC bridge.
+- no ready message: inspect client stderr; Runner keeps stdout protocol-clean.

package/docs/release-notes.md

@@ -12,6 +12,36 @@ for the Synapsor Cloud CLI.
 
 ## Unreleased
 
+Prepared package versions: `@synapsor/spec@0.1.4`,
+`@synapsor/dsl@0.1.4`, and `@synapsor/runner@0.1.11`. Nothing in this section
+is published until the manual release commands are run.
+
+### Cloud Adoption Loop
+
+- Adds complete Claude, Cursor, OpenAI Agents SDK, and generic MCP templates to
+  local and Cloud-generated Runner bundles.
+- Adds a flagship adoption verifier and a real local Cloud registry/version/ZIP
+  bundle round trip.
+- Expands the `support-plan-credit` walkthrough from no-database validation to
+  Docker-backed policy tiers, MCP setup, Cloud push, bundle download, replay,
+  cleanup, and troubleshooting.
+- Supports `SYNAPSOR_CLOUD_WORKSPACE` and verifies distinct 401/403/404/409/422,
+  server, and network errors without exposing tokens.
+- Clarifies that Cloud registry/versioning is beta-ready while managed runners,
+  SAML/SCIM, hosted policy enforcement, legal hold, and enterprise SLA are not
+  part of this release.
+- Corrects `cloud push --help` to describe the real authenticated registry
+  upload and network-free dry-run behavior.
+
+## 0.1.10
+
+### Policy Auto-Approval
+
+- Adds portable approval-policy references and threshold rules.
+- Adds DSL `AUTO APPROVE WHEN field <= integer` and the three-tier
+  `support-plan-credit` example: policy approval, operator review, and bound
+  rejection.
+
 ## 0.1.9
 
 ### CLI Hygiene

package/docs/runner-bundles.md

@@ -0,0 +1,59 @@
+# Runner Bundles
+
+A runner bundle is the portable Cloud-to-local side of the canonical loop:
+
+```text
+local DSL/spec -> cloud push -> immutable registry version -> runner bundle -> local Runner
+```
+
+Every bundle contains:
+
+```text
+synapsor.contract.json
+synapsor.runner.json
+.env.example
+README.md
+mcp-client-examples/
+  claude-desktop.json
+  cursor-project.mcp.json
+  cursor-global.mcp.json
+  openai-agents-stdio.ts
+  openai-agents-streamable-http.ts
+  generic-stdio.json
+  generic-streamable-http.json
+```
+
+It never contains database passwords, write credentials, live API tokens,
+private keys, customer rows, or machine-specific local paths.
+
+## Create Locally
+
+```bash
+synapsor-runner contract bundle ./synapsor.contract.json \
+  --out ./synapsor-runner-bundle
+```
+
+## Run A Downloaded Bundle
+
+```bash
+cd ./synapsor-runner-bundle
+cp .env.example .env
+set -a && . ./.env && set +a
+
+npx -y -p @synapsor/runner synapsor-runner contract validate ./synapsor.contract.json
+npx -y -p @synapsor/runner synapsor-runner config validate --config ./synapsor.runner.json
+npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+```
+
+For the OpenAI Agents SDK, use the included TypeScript examples. Their stdio
+command enables `--alias-mode openai`; the Streamable HTTP example includes the
+matching server command. Claude, Cursor, and generic templates use canonical
+dotted capability names.
+
+Approval and writeback remain outside the model-facing MCP tool surface. Use
+`proposals`, `apply`, `receipts`, and `replay` from a trusted operator shell.
+
+The bundle's `.env.example` contains names and placeholders only. Fill it for a
+local or staging source, source it into the shell or process that launches your
+MCP client, and keep the resulting `.env` out of source control.

package/examples/support-plan-credit/.env.example

@@ -0,0 +1,10 @@
+# Disposable Docker example credentials only. Do not reuse in staging or production.
+PLAN_CREDIT_POSTGRES_READ_URL=postgresql://synapsor_reader:synapsor_reader_password@127.0.0.1:55438/synapsor_runner_plan_credit
+PLAN_CREDIT_POSTGRES_WRITE_URL=postgresql://synapsor_writer:synapsor_writer_password@127.0.0.1:55438/synapsor_runner_plan_credit
+SYNAPSOR_TENANT_ID=acme
+SYNAPSOR_PRINCIPAL=local_support_agent
+
+# Optional Cloud registry upload. Keep real values outside git.
+SYNAPSOR_CLOUD_BASE_URL=
+SYNAPSOR_CLOUD_TOKEN=
+SYNAPSOR_WORKSPACE_ID=

package/examples/support-plan-credit/README.md

@@ -0,0 +1,273 @@
+# Support Plan Credit Example
+
+This example shows three enforcement tiers on one support action:
+
+- `$25` (`2500` cents): policy-approved, then applied locally through guarded writeback.
+- `$100` (`10000` cents): saved as `pending_review` until a local operator approves.
+- `$1000` (`100000` cents): rejected before proposal creation by the contract bound.
+
+## Prerequisites
+
+- Docker
+- Node 22.5+
+- Port `55438` available
+
+Install the stable CLI once for the commands below:
+
+```bash
+npm install --global @synapsor/runner
+synapsor-runner --version
+```
+
+When working from this source checkout, use `corepack pnpm runner` in place of
+`synapsor-runner`.
+
+## No-Database Check
+
+Validate the authored boundary before starting Docker:
+
+```bash
+synapsor-runner dsl compile examples/support-plan-credit/contract.synapsor \
+  --out /tmp/support-plan-credit.contract.json \
+  --strict
+synapsor-runner contract validate /tmp/support-plan-credit.contract.json
+synapsor-runner config validate \
+  --config examples/support-plan-credit/synapsor.runner.json
+synapsor-runner cloud push /tmp/support-plan-credit.contract.json \
+  --dry-run \
+  --workspace local-preview \
+  --name support-plan-credit
+```
+
+This compiles, validates, and previews the Cloud payload without opening a
+network connection or connecting to a database. From a source checkout,
+`corepack pnpm verify:adoption` runs this boundary check plus the no-database
+quick demo and MCP config validation.
+
+## Quick Start
+
+```bash
+docker compose -f examples/support-plan-credit/docker-compose.yml up -d
+
+set -a
+. examples/support-plan-credit/.env.example
+set +a
+
+synapsor-runner tools preview \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+
+# Run this in a second terminal if you want to attach an MCP client.
+synapsor-runner mcp serve \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
+The checked-in `.env.example` contains disposable localhost Docker credentials
+only. Never reuse them for staging or production.
+
+## Walkthrough
+
+Inspect the customer first:
+
+```bash
+synapsor-runner smoke call support.inspect_customer \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001"}'
+```
+
+Propose a `$25` credit:
+
+```bash
+synapsor-runner propose support.propose_plan_credit \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001","credit_cents":2500,"reason":"SLA outage ticket SUP-481"}'
+```
+
+`proposals show` displays `policy:support_propose_plan_credit_auto_approval`.
+The proposal is approved, but it is not applied until the local writeback step:
+
+```bash
+synapsor-runner proposals show latest --store ./tmp/support-plan-credit/local.db
+synapsor-runner apply latest \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner receipts list --proposal <proposal_id> --store ./tmp/support-plan-credit/local.db
+```
+
+Propose a `$100` credit:
+
+```bash
+synapsor-runner propose support.propose_plan_credit \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001","credit_cents":10000,"reason":"larger support credit"}'
+
+synapsor-runner proposals approve latest --yes --store ./tmp/support-plan-credit/local.db
+synapsor-runner apply latest \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
+Propose a `$1000` credit:
+
+```bash
+synapsor-runner propose support.propose_plan_credit \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db \
+  --json '{"customer_id":"CUS-3001","credit_cents":100000,"reason":"too large"}'
+```
+
+The contract bound rejects it before a proposal row exists.
+
+Replay and stale-row checks:
+
+```bash
+synapsor-runner replay export --proposal latest --store ./tmp/support-plan-credit/local.db --output ./tmp/support-plan-credit/replay.json
+synapsor-runner apply latest --config examples/support-plan-credit/synapsor.runner.json --store ./tmp/support-plan-credit/local.db
+```
+
+The live smoke test mutates `updated_at` before apply and proves stale proposals
+return `VERSION_CONFLICT` without changing the source row.
+
+Run the complete Docker-backed scenario, including all three policy tiers and
+the stale-row conflict:
+
+```bash
+corepack pnpm test:live-apply
+```
+
+## What The Agent Never Sees
+
+The contract keeps these fields out:
+
+- `card_token`
+- `raw_payment_method`
+- `internal_risk_score`
+- `private_notes`
+
+`tools preview` should show only:
+
+```text
+support.inspect_customer
+support.propose_plan_credit
+auto-approval: enabled
+```
+
+No raw SQL, approval tools, commit tools, write credentials, or model-controlled
+tenant authority are exposed to MCP.
+
+Representative outputs are checked in under [`expected-output/`](expected-output/)
+so you can compare the tool boundary, proposal, receipt, replay, and Cloud push
+shape without guessing which state should change.
+
+## Connect An MCP Client
+
+Copy the matching template from [`mcp-client-examples/`](mcp-client-examples/):
+
+- Claude Desktop: `claude-desktop.json`
+- Cursor project/global: `cursor-project.mcp.json`, `cursor-global.mcp.json`
+- OpenAI Agents SDK: stdio and Streamable HTTP TypeScript examples
+- generic MCP: stdio and Streamable HTTP JSON examples
+
+For Streamable HTTP, run:
+
+```bash
+synapsor-runner mcp serve \
+  --transport streamable-http \
+  --alias-mode openai \
+  --host 127.0.0.1 \
+  --port 8766 \
+  --config examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+```
+
+The OpenAI client receives `support__inspect_customer` and
+`support__propose_plan_credit`; Runner preserves the dotted canonical names in
+tool metadata and results. For Claude, Cursor, or generic MCP clients, omit
+`--alias-mode openai` to expose `support.inspect_customer` and
+`support.propose_plan_credit`. Approval and apply remain outside MCP.
+
+## How The Policy Is Governed
+
+The auto-approval policy lives in `contract.synapsor`:
+
+```sql
+AUTO APPROVE WHEN plan_credit_cents <= 2500
+```
+
+That compiles into `synapsor.contract.json` as a reviewed approval policy. It is
+stored in git, validated by `@synapsor/spec`, and included in Cloud push payloads.
+
+To disable local policy approval without changing the contract:
+
+```json
+{
+  "approvals": {
+    "disable_auto_approval": true
+  }
+}
+```
+
+Auto-approval never applies the write. It only records an approval row and audit
+event with actor `policy:<policy_name>`.
+
+## Cloud
+
+Dry-run the Cloud payload:
+
+```bash
+synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json --dry-run
+```
+
+Real push uses your Cloud env vars:
+
+```bash
+export SYNAPSOR_CLOUD_BASE_URL="https://api.synapsor.ai"
+export SYNAPSOR_CLOUD_TOKEN="<workspace-scoped-token>"
+export SYNAPSOR_WORKSPACE_ID="<workspace_id>"
+
+synapsor-runner cloud push examples/support-plan-credit/synapsor.contract.json \
+  --name support-plan-credit
+```
+
+After push, Cloud can return the registered version and a runner bundle with
+placeholder env names:
+
+```bash
+curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>"
+
+curl -H "Authorization: Bearer $SYNAPSOR_CLOUD_TOKEN" \
+  "$SYNAPSOR_CLOUD_BASE_URL/v1/control/projects/$SYNAPSOR_WORKSPACE_ID/agent-contracts/<contract_id>/versions/<version_id>/runner-bundle?download=1" \
+  -o support-plan-credit-runner-bundle.zip
+```
+
+The push response supplies `<contract_id>` and `<version_id>`. The Cloud
+workspace also exposes the same download from **Contract registry**.
+
+No Cloud account is needed to run this local example.
+
+## Clean Up
+
+```bash
+docker compose -f examples/support-plan-credit/docker-compose.yml down -v
+rm -rf ./tmp/support-plan-credit
+```
+
+## Troubleshooting
+
+- `synapsor-runner: command not found`: install `@synapsor/runner` globally or
+  use `corepack pnpm runner` from this repository.
+- port `55438` is busy: stop the previous example container or change the
+  published port and both URLs in `.env.example` together.
+- missing table/connection: wait for the Docker health check, then rerun the
+  command from the repository root with the `.env.example` values exported.
+- OpenAI rejects dotted tool names: start the MCP server with
+  `--alias-mode openai` and use the OpenAI template.
+- proposal stays pending: `$100` intentionally requires
+  `proposals approve`; only the `$25` tier is policy-approved.
+- apply reports a conflict: the row changed after the proposal read. Inspect
+  the new row, create a fresh proposal, and do not bypass the version guard.