@synapsor/runner 1.6.2 → 1.6.4

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

@@ -14,18 +14,16 @@ review artifacts without sampling source rows or using an LLM.
 
 ## Fast path
 
-Set a dedicated SELECT-only, non-owner database URL plus trusted development
-scope and run the public guided path:
+Run the public guided path:
 
 ```bash
-export DATABASE_URL="<postgres-or-mysql-read-url>"
-export SYNAPSOR_TENANT_ID="<staging-tenant>"
-export SYNAPSOR_PRINCIPAL="<developer-id>"
-npx -y -p @synapsor/runner synapsor-runner start --from-env DATABASE_URL
+npx -y @synapsor/runner start
 ```
 
-A fresh interactive project with no existing config, selector, or automation
-input follows:
+Paste a dedicated SELECT-only, non-owner URL into the hidden prompt, explicitly
+approve a regular project `.env` file for this process, or export
+`DATABASE_URL`. A fresh interactive project with no existing config, selector,
+or automation input follows:
 
 ```text
 inspect the whole selected schema and structured application artifacts
@@ -43,10 +41,13 @@ It does not print your database URL, put the URL in MCP client config, expose
 `execute_sql`, expose approval/commit tools, or give the model write
 credentials. Before boundary activation it does not read source rows.
 
-`start --from-env` is the shortest public command for first-run onboarding.
-Read [Auto Boundary, Scoped Explore, And
-Protect](auto-boundary-and-scoped-explore.md) for the complete command and
-security reference.
+`start` is the shortest public command for first-run onboarding. When
+`DATABASE_URL` is already exported, Runner uses it automatically. Explicit
+`--from-env`, `--schema`, and `--project-root` values always win.
+Read [Database To First Safe Tool](guided-onboarding.md) for the timed guided
+journey and [Auto Boundary, Scoped Explore, And
+Protect](auto-boundary-and-scoped-explore.md) for the complete security
+reference.
 
 Established routes remain unchanged. `--table`, `--answers`, `onboard db`,
 explicit `init` flags, existing configs, headless startup, JSON output, and CI
@@ -103,7 +104,7 @@ before using staging or production-like data.
 ## 2. Inspect metadata
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner inspect \
+npx -y @synapsor/runner inspect \
   --engine auto \
   --from-env DATABASE_URL \
   --schema public
@@ -112,13 +113,13 @@ npx -y -p @synapsor/runner synapsor-runner inspect \
 For a disposable staging URL, this also works:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner inspect "$DATABASE_URL" --engine auto --schema public
+npx -y @synapsor/runner inspect "$DATABASE_URL" --engine auto --schema public
 ```
 
 For automation:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner inspect \
+npx -y @synapsor/runner inspect \
   --engine postgres \
   --from-env DATABASE_URL \
   --schema public \
@@ -135,9 +136,9 @@ to your staging table, primary key, tenant key, conflict column, visible fields,
 allowed write fields, and business limits.
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner recipes list
-npx -y -p @synapsor/runner synapsor-runner recipes show billing.late_fee_waiver
-npx -y -p @synapsor/runner synapsor-runner recipes init billing.late_fee_waiver --output synapsor.runner.json
+npx -y @synapsor/runner recipes list
+npx -y @synapsor/runner recipes show billing.late_fee_waiver
+npx -y @synapsor/runner recipes init billing.late_fee_waiver --output synapsor.runner.json
 ```
 
 Use a recipe when the shape is close. Use the guided wizard or explicit flags
@@ -152,7 +153,7 @@ only the capabilities in your generated `synapsor.runner.json`.
 In an interactive terminal, run the guided wizard:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init --from-env DATABASE_URL --mode read_only --wizard
+npx -y @synapsor/runner init --from-env DATABASE_URL --mode read_only --wizard
 ```
 
 The generated context and capabilities are based on your selections. Synapsor
@@ -297,7 +298,7 @@ If you already know the reviewed table/action, generate config directly from
 metadata and explicit flags:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --from-env DATABASE_URL \
   --engine postgres \
   --schema public \
@@ -321,7 +322,7 @@ when you want exact capability names in the generated contract.
 For app-owned writeback, replace the direct writer env with a handler executor:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --from-env DATABASE_URL \
   --engine postgres \
   --schema public \
@@ -350,7 +351,7 @@ source primary/unique dedup key; DELETE requires an exact conflict guard and
 safe cascade/trigger inspection:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner onboard db \
+npx -y @synapsor/runner onboard db \
   --from-env DATABASE_URL \
   --table account_credits \
   --mode review \
@@ -369,7 +370,7 @@ but ambiguous post-commit crashes stop for operator reconciliation.
 Or generate from a saved inspection snapshot without reconnecting:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --inspection-json schema-inspection.json \
   --table invoices \
   --namespace billing \
@@ -439,7 +440,7 @@ contain database URLs or passwords.
 ## 6. Generate runner files
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init \
+npx -y @synapsor/runner init \
   --spec onboarding-selection.json \
   --non-interactive
 ```
@@ -459,16 +460,16 @@ files.
 Generate or refresh MCP client snippets later with:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner mcp config generic --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner mcp config claude-desktop --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner mcp config cursor --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 Call one generated tool locally before wiring an MCP client:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner smoke call --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 `smoke call` uses the same runtime as the MCP server. It records evidence and
@@ -488,8 +489,8 @@ URLs, passwords, approval tools, commit tools, or write credentials.
 ## 7. Validate the config
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner config validate --config synapsor.runner.json
-npx -y -p @synapsor/runner synapsor-runner config show --config synapsor.runner.json --redacted
+npx -y @synapsor/runner config validate --config synapsor.runner.json
+npx -y @synapsor/runner config show --config synapsor.runner.json --redacted
 ```
 
 The config stores environment-variable names, not connection-string values.
@@ -497,7 +498,7 @@ The config stores environment-variable names, not connection-string values.
 Run doctor after setting the referenced environment variables:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json
+npx -y @synapsor/runner doctor --config synapsor.runner.json
 ```
 
 Doctor validates config shape, trusted context env vars, source env vars,
@@ -505,7 +506,7 @@ read/write credential separation, table/column metadata when the read URL is
 available, and the semantic MCP tool boundary. Use JSON for automation:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json --json
+npx -y @synapsor/runner doctor --config synapsor.runner.json --json
 ```
 
 ## 8. Serve semantic MCP tools
@@ -515,7 +516,7 @@ Use stdio when a local MCP client can launch Synapsor Runner:
 ```bash
 export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
-npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 Use Streamable HTTP when an app/server agent connects through a standard HTTP
@@ -526,7 +527,7 @@ export SYNAPSOR_TENANT_ID="acme"
 export SYNAPSOR_PRINCIPAL="local_operator"
 export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
-npx -y -p @synapsor/runner synapsor-runner up --serve \
+npx -y @synapsor/runner up --serve \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
@@ -540,7 +541,7 @@ serving.
 The lower-level MCP command starts the same transport directly:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner mcp serve-streamable-http \
+npx -y @synapsor/runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
@@ -571,10 +572,10 @@ tools, commit tools, database URLs, write credentials, or tenant authority.
 Proposal tools leave the source database unchanged. Review locally:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner proposals list --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
-npx -y -p @synapsor/runner synapsor-runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
+npx -y @synapsor/runner proposals list --store ./.synapsor/local.db
+npx -y @synapsor/runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner proposals approve wrp_123 --store ./.synapsor/local.db --actor local_reviewer --yes
+npx -y @synapsor/runner proposals writeback-job wrp_123 --store ./.synapsor/local.db --output job.json
 ```
 
 Apply through the trusted worker path with a separate writer credential:
@@ -582,7 +583,7 @@ Apply through the trusted worker path with a separate writer credential:
 ```bash
 export SYNAPSOR_DATABASE_WRITE_URL="<postgres-or-mysql-write-url>"
 SYNAPSOR_ENGINE=postgres \
-npx -y -p @synapsor/runner synapsor-runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner apply --job job.json --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 For `apply --job ... --config ...`, Runner reads the write credential from the
@@ -596,7 +597,7 @@ from environment variables, and the handler receives a structured proposal/job
 payload, not arbitrary model SQL:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner apply --proposal wrp_123 --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 See [Writeback Executors](writeback-executors.md).
@@ -604,8 +605,8 @@ See [Writeback Executors](writeback-executors.md).
 Replay afterward:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
+npx -y @synapsor/runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner replay export wrp_123 --store ./.synapsor/local.db --output replay.json
 ```
 
 ## Boundary

package/docs/guarded-crud-writeback.md

@@ -119,6 +119,12 @@ APPROVAL ROLE billing_reviewer
 WRITEBACK DIRECT SQL
 ```
 
+The role requirement is enforced against verified operator identity outside
+MCP; it is not a PostgreSQL role or model argument. Apply has its own role
+gate. See [Approval Roles And Verified Operator
+Identity](approval-roles-and-operator-identity.md) for the complete tested
+OIDC/JWKS and signed-key paths.
+
 Guarded `INSERT` needs a source-unique, Runner-supplied dedup identity:
 
 ```sql
@@ -212,6 +218,19 @@ Resolution appends immutable events and a reconciliation receipt. It does not
 rewrite history or retry the source mutation. Configured production operator
 identity is required when enabled.
 
+## Optional supervised execution
+
+Manual apply remains the default, including for `AUTO APPROVE`. Runner can
+optionally let a separately trusted worker consume approved single-row
+`INSERT`/`UPDATE` proposals, but only after contract permission and an
+independent deployment allowlist bind the exact active digest. The worker
+reuses this same guarded path and repeats current source/evidence, policy,
+limit, writer-posture, receipt, and lease checks immediately before apply.
+
+Hard `DELETE`, reversible actions, app-owned executors, and multi-row writes
+are not eligible for the first automatic path. See
+[Operator-Supervised Automatic Apply](supervised-automatic-apply.md).
+
 ## Verification
 
 The repository includes a disposable Postgres/MySQL test that proves every

package/docs/guided-onboarding.md

@@ -0,0 +1,399 @@
+# Guided Onboarding: Database To First Safe Tool
+
+This is the shortest path from an existing staging Postgres/MySQL database to
+one useful agent tool. It requires no Synapsor account, Cloud login, database
+replication, global install, MCP host, model API key, or hand-authored config,
+DSL, JSON, SQL, DDL, or grants.
+
+## The One-Minute Mental Model
+
+Synapsor is creating the small set of database powers your agent may use. It
+does not give the agent SQL access.
+
+- Reads return only fields a human reviewed, under tenant and principal scope
+  supplied outside model arguments.
+- Scoped Explore is a temporary local development/staging authoring tool.
+- Protect turns one useful analysis into a narrow named capability.
+- A model-facing write call creates an exact proposal. It does not commit.
+- The model cannot activate authority, approve a proposal, or apply a write.
+- A trusted operator or worker rechecks the effect and records a receipt.
+
+## Before You Start
+
+Use a disposable or staging database and a dedicated SELECT-only, non-owner
+credential. Keep row-level security, restricted views, or tenant-bound
+credentials underneath Runner where available.
+
+Do not put a database URL in project documentation or chat. The shortest path
+uses a hidden terminal prompt:
+
+```bash
+npx -y @synapsor/runner start
+```
+
+Runner can also use an already-exported `DATABASE_URL`. When a regular `.env`
+or `.env.local` file exists, it asks before reading that file and holds the
+selected value only for the current Runner/Workbench process. The URL is not
+written to generated artifacts or the ledger. Runner requires Node 22.13 or
+newer.
+
+## One Command To Workbench
+
+Run this from an empty project directory or your application root:
+
+```bash
+npx -y @synapsor/runner start
+```
+
+The command automatically:
+
+1. checks the database and credential posture;
+2. inspects schema metadata without sampling source rows;
+3. statically reads supported Prisma, Drizzle, OpenAPI, and existing Synapsor
+   definitions when present;
+4. drafts disabled public DSL, canonical JSON, tests, and a generation lock;
+5. creates a valid zero-authority Runner config and local SQLite ledger;
+6. validates every generated artifact;
+7. opens one secured loopback Workbench URL.
+
+Before human activation, the agent has no generated authority and no source row
+has been read. On an explicitly asserted personal development database,
+Workbench offers a fast lane:
+
+1. confirm the database is your own development or disposable test data;
+2. provide the trusted tenant/principal scope for this in-memory session;
+3. inspect the one-resource summary and select **Activate this narrow read and
+   show a real result**.
+
+The single gesture is recorded against the exact boundary digest. Runner
+rechecks schema and read-only role posture, activates one resource with no
+relationships, keeps sensitive and uncertain fields out, and runs one real
+bounded aggregate read. Shared, staging, production-like, remote, widening, and
+write paths do not use this shortcut.
+
+Running the same command again resumes. Resume and Try do not rescan, rewrite
+files, or change a digest. Rescan and destructive Start over remain explicit
+human choices.
+
+Workbench requires no additional terminal command. If you choose the CLI
+fallbacks below after the first success, install Runner once:
+
+```bash
+npm install -g @synapsor/runner
+```
+
+The remaining examples then use `synapsor-runner` directly instead of
+reacquiring the npm package for every command.
+
+## Five Minutes: First Safe Read
+
+The full Workbench path starts with an overview, not a permission matrix. It
+shows:
+
+- database and framework evidence found;
+- resources inspected;
+- fields already kept out;
+- unresolved sensitive fields;
+- row identity;
+- tenant and principal scope;
+- database-role and RLS posture;
+- ready and blocked capabilities.
+
+Review only the exceptions. Routine conservative defaults are already applied.
+There is no global “approve everything” control.
+
+For each selected resource, confirm the exact primary/unique row identity,
+trusted scope, visible fields, kept-out fields, and any aggregate-only fields.
+Then sign the displayed digest. Changing a reviewed decision creates a new
+disabled digest.
+
+Choose **Try first safe read**. Runner calls the real local runtime and shows:
+
+```text
+Your first safe tool is working.
+
+Tool: <domain>.inspect_<resource>
+Agent can see: <reviewed fields>
+Agent cannot see: <kept-out fields>
+Tenant scope: trusted outside model arguments
+Principal scope: trusted outside model arguments
+Source database changed: no
+```
+
+CLI fallback:
+
+```bash
+synapsor-runner try call --list --format json
+synapsor-runner try call <returned-tool-name> --sample --json
+```
+
+The second command is for an activated named tool with valid generated sample
+input. It does not invent tenant or principal values.
+
+## Optional: Ask Through Your Own Model
+
+The no-model Workbench composer is already complete; a provider key is never
+required for onboarding. If you want a chat surface before installing Cursor
+or another MCP client, open **Analyze -> Ask with your model**.
+
+Workbench shows the exact reviewed tools first. Select OpenAI, Anthropic, or a
+custom OpenAI-compatible endpoint, choose a named environment credential or a
+session-only masked paste, and acknowledge that reviewed visible data may go
+directly to that provider. Synapsor does not relay it.
+
+The provider can request only the displayed tools. It cannot choose trusted
+scope, activate or Protect authority, approve or apply a proposal, or configure
+Runner. A write request produces the same inert proposal as external MCP:
+
+```text
+Proposal only
+Source database changed: no
+The model cannot approve or apply this proposal.
+```
+
+Changing the provider, model, endpoint, runtime config, or reviewed boundary
+requires a new egress acknowledgement. Select **Clear** to cancel and discard
+the in-memory provider configuration and conversation. See [Workbench Ask With
+Your Model](workbench-ask.md) for key handling, endpoint security, fixed bounds,
+the tested provider matrix, and the full no-model alternative.
+
+## Ten Minutes: Explore And Protect
+
+Scoped Explore is available only after its exact local authoring boundary is
+activated. It is absent from production, unknown-profile, remote, shared HTTP,
+and non-loopback `tools/list`.
+
+In Workbench, choose **Ask an aggregate question**. Select only reviewed
+resources, dimensions, measures, filters, and time buckets. No SQL or plan JSON
+is required.
+
+The first release supports bounded:
+
+- `count` and reviewed `count_distinct`;
+- `sum` and `avg` over reviewed numeric measures;
+- reviewed categorical dimensions;
+- day, week, and month buckets;
+- typed filters and bounded top-N;
+- up to three activated relationship paths, each containing one or two
+  catalog-proven many-to-one links with fan-out one.
+
+If a question needs an inactive but proven path, Runner refuses it and
+Workbench offers only that exact path for operator review. The model cannot
+activate it. Optional links require an explicit missing-row choice because
+excluding a row versus retaining an empty group can change business totals.
+See [Reviewed Relationship Paths](reviewed-relationships.md).
+
+Minimum cohorts, group limits, response limits, query limits, extraction
+budgets, and anti-differencing budgets are fixed by the activated boundary.
+Small groups are suppressed. Results describe changes or contributors; they do
+not prove causation.
+
+CLI fallback for the Workbench-suggested aggregate:
+
+```bash
+synapsor-runner try explore --suggested --json
+```
+
+Choose **Protect this analysis** directly on the successful result. Runner
+freezes its reviewed resources, measures, grouping, time bucket, ordering,
+scope, suppression, and limits into:
+
+```text
+synapsor/protected/drafts/<namespace>__<name>/capability.synapsor.sql
+synapsor/protected/drafts/<namespace>__<name>/synapsor.contract.json
+synapsor/protected/drafts/<namespace>__<name>/contract-tests.json
+```
+
+The capability remains disabled until a human activates its exact digest.
+Disabling Scoped Explore does not remove the protected named capability.
+
+Workbench renders generated `.synapsor.sql` with local deterministic syntax
+highlighting. Keywords, names chosen by the author, strings, numbers, comments,
+and punctuation are visually distinct. The copy/plain-text value remains
+byte-identical to the generated file; highlighting loads no CDN and escaped
+source text never becomes HTML.
+
+CLI fallback, without copying an opaque query handle:
+
+```bash
+synapsor-runner try protect \
+  --name analytics.reviewed_weekly_summary \
+  --json
+```
+
+## Fifteen Minutes: First Proposal
+
+After the first read, choose **Add a safe action**. Schema metadata supplies
+structure, never business permission. The human specifies:
+
+1. the business action;
+2. target resource and exact row identity;
+3. fields that may change;
+4. allowed values, transitions, and numeric bounds;
+5. trusted tenant and principal scope;
+6. conflict/version guard;
+7. approval role;
+8. optional small bounded auto-approval;
+9. per-operation and daily limits;
+10. optional reviewed compensation.
+
+Runner generates public DSL, canonical JSON, tests, an exact-effect preview,
+and a disabled action. Unsupported or unsafe combinations fail closed. In
+particular, DELETE, bounded-set, quorum, auto-approval, and reversibility cannot
+be combined beyond what the canonical DSL supports.
+
+After exact-digest human activation, call the named proposal tool in Workbench
+or through the host-neutral Try path. The result must say:
+
+```text
+Proposal created.
+Source database changed: no.
+The model cannot approve or apply this proposal.
+```
+
+Inspect the latest lifecycle without copying a proposal ID:
+
+```bash
+synapsor-runner lifecycle --details
+```
+
+Approval and apply stay outside MCP:
+
+```bash
+synapsor-runner proposals approve latest --yes
+synapsor-runner apply latest
+synapsor-runner lifecycle show latest --details
+```
+
+Production should use a verified signed-key or OIDC operator identity rather
+than unverified development identity. See [Approval Roles And Verified
+Operator Identity](approval-roles-and-operator-identity.md).
+
+These commands show the default human-approval/manual-apply path. A production
+operator can separately opt an eligible action into exact-digest supervised
+execution. That does not give the model an apply tool: the model creates a
+bounded proposal, reviewed policy may approve it, and a separately trusted
+worker repeats all guards before any later source mutation. Existing
+`AUTO APPROVE` contracts remain manual-apply unless both opt-ins are present.
+See [Operator-Supervised Automatic
+Apply](supervised-automatic-apply.md).
+
+## Guarded Development Writeback Setup
+
+Preview is always the default:
+
+```bash
+synapsor-runner writeback setup \
+  --profile staging \
+  --json
+```
+
+The response contains one immutable plan digest and exact setup SQL, objects,
+grants, receipt mode, and next action.
+
+- `runner_ledger`: no Synapsor receipt table or receipt grant is added to the
+  source database.
+- `source_db` + `auto_migrate`: verifies the configured idempotent first-use
+  path using the trusted writer.
+- `source_db` + `precreated`: requires a separate setup/admin URL environment
+  name and exact steady-state writer role.
+- app-owned handlers receive no unnecessary source receipt setup.
+
+DDL apply is refused for missing, unknown, or production profiles. In
+development/staging, it requires the exact displayed confirmation:
+
+```bash
+synapsor-runner writeback setup \
+  --profile staging \
+  --writer-role '<steady-state-writer-role>' \
+  --setup-url-env SYNAPSOR_SETUP_DATABASE_URL \
+  --apply \
+  --confirm 'APPLY WRITEBACK SETUP sha256:<reviewed-plan-digest>'
+```
+
+Never reuse the model/read credential as the elevated setup connection.
+
+## Connect An MCP Client
+
+Workbench generates ready-to-copy Cursor, Claude, Codex, and generic stdio
+snippets for the same reviewed authority. Stdio opens no network listener and
+needs no HTTP bearer credential.
+
+Render the generic snippet:
+
+```bash
+synapsor-runner mcp config --absolute-paths
+```
+
+Preview a project-scoped Cursor change:
+
+```bash
+synapsor-runner mcp install cursor --project --dry-run
+```
+
+No client config contains database URLs, trusted scope values, approval,
+activation, apply, or revert authority.
+
+## Machine-Readable Output
+
+Commands that support machine output write exactly one JSON value to stdout.
+Operational logs and diagnostics use stderr:
+
+```bash
+synapsor-runner try explore --suggested --json | jq -e .
+```
+
+On a process-level failure, JSON output uses:
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "COMMAND_REJECTED",
+    "message": "Safe redacted explanation"
+  },
+  "recovery": {
+    "state_preserved": "What remains intact",
+    "source_database_changed": null,
+    "next_action": "One exact next action"
+  }
+}
+```
+
+`null` means Runner cannot honestly infer the source mutation outcome from a
+generic command exception. Operation-specific receipts and reconciliation
+states remain authoritative.
+
+## Before And After
+
+The earlier manual path could require roughly thirteen disconnected steps:
+inspect, compile, create config, validate, doctor, initialize a store, start
+Workbench, generate MCP config, create receipt DDL/grants, run a smoke call,
+approve, and apply.
+
+The guided path through the first proposal uses:
+
+- one public shell command;
+- deliberate Workbench review and activation;
+- no manual file edits;
+- no external documentation search;
+- no Cursor requirement.
+
+The packed FitFlow gate records the exact command count, human decisions, and
+timings in `development/runner-1.6.4-fitflow-results.json`.
+
+## Visual Reference
+
+Repository screenshots cover desktop, mobile, light, dark, loading, blocked,
+stale, failure, empty Protect, unavailable-action, optional Ask, refusal, and
+proposal-only states:
+
+- [Desktop overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-overview-desktop-light.png)
+- [Mobile overview](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-overview-mobile-light.png)
+- [Blocked identity review](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-blocked-identity.png)
+- [Stale/failure recovery](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-visual/workbench-keyboard-stale-failure.png)
+- [Ask kept-out-field refusal](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-retail-visual/05c-ask-refusal.png)
+- [Ask proposal-only result](https://github.com/Synapsor/Synapsor-Runner/blob/main/development/runner-1.6.4-community-solar-visual/13b-ask-proposal-only.png)
+
+For common blocked states and one-action recovery commands, use
+[Troubleshooting First Run](troubleshooting-first-run.md).