@synapsor/runner 1.6.1 → 1.6.3

package/docs/auto-boundary-and-scoped-explore.md

@@ -1,6 +1,7 @@
 # Auto Boundary, Scoped Explore, And Protect
 
-Runner 1.6.0 adds a deterministic authoring path for a real application:
+Runner 1.6.3 provides a deterministic, resumable authoring path for a real
+application:
 
 ```text
 Connect staging
@@ -146,6 +147,22 @@ The immutable digest covers the reviewed resources, field permissions,
 relationships, scope, role posture, generation lock, compiler/spec version,
 profile, and every query/privacy budget. Model arguments cannot widen it.
 
+## Try Without An External MCP Host
+
+Workbench can run the first safe read, bounded aggregate, and Protect flow
+directly. The same authority is available through CLI Try:
+
+```bash
+synapsor-runner try call --list --format json
+synapsor-runner try explore --suggested --json
+synapsor-runner try protect --name analytics.protected_analysis --json
+```
+
+Cursor, Claude, Codex, and generic stdio are optional clients, not onboarding
+dependencies. The packed FitFlow gate proves Workbench, CLI Try, and an
+official-SDK generic stdio client produce the same bounded result and denial
+behavior.
+
 ## Add The Authoring Tools To Cursor
 
 After activation, let Runner manage only its own project entry:
@@ -323,16 +340,25 @@ their previous startup, `doctor`, contract, and tool behavior.
 
 ## Verify The Reference Journey
 
-The packaged synthetic fixture is under `examples/auto-boundary-churn`.
+The polished packed-artifact journey is under
+`examples/fitflow-guided-onboarding`. The smaller
+`examples/auto-boundary-churn` fixture remains a compatibility and focused
+aggregate-security gate.
 
 From a source checkout:
 
 ```bash
 corepack pnpm test:auto-boundary-explore
 corepack pnpm test:auto-boundary-explore:packed
+corepack pnpm test:guided-onboarding:packed
 ```
 
-The packed gate proves the PostgreSQL + Next.js + Prisma + Cursor-compatible
-MCP + Workbench flow, all aggregate denial/suppression/budget checks, Protect,
-production Explore absence, protected-capability survival, durable redacted
-audit, and an unchanged source database.
+The packed gates prove the PostgreSQL + Next.js + Prisma + Workbench flow,
+host-neutral CLI/generic-stdio parity, all aggregate
+denial/suppression/budget checks, Protect, production Explore absence,
+protected-capability survival, guided proposal/apply/compensation, verified
+OIDC roles, durable redacted audit, and unchanged source data before every
+authorized mutation.
+
+For the timed first-read, Explore, Protect, proposal, and writeback walkthrough,
+use [Database To First Safe Tool](guided-onboarding.md).

package/docs/capability-authoring.md

@@ -118,6 +118,24 @@ CREATE CAPABILITY billing.propose_late_fee_waiver
 END
 ```
 
+`billing_lead` is a Synapsor contract role, not a database role or secret. For
+shared or production operation, Runner must resolve that exact role from a
+freshly verified operator identity and separately authorize apply. See
+[Approval Roles And Verified Operator
+Identity](approval-roles-and-operator-identity.md).
+
+Manual apply remains the default. For an eligible direct single-row
+INSERT/UPDATE, a reviewer may additionally place this clause before `END`:
+
+```sql
+ALLOW SUPERVISED WORKER APPLY
+```
+
+It grants only contract-side permission and becomes part of the exact contract
+digest. Automatic execution still requires an independent deployment allowlist
+for that capability and digest; see [Operator-Supervised Automatic
+Apply](supervised-automatic-apply.md).
+
 Compile and validate:
 
 ```bash
@@ -229,6 +247,7 @@ reviewed runner JSON capabilities. Current parity:
 | 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 `execution.supervised_worker` | `ALLOW SUPERVISED WORKER APPLY` | 1.6 | Optional contract-side permission for eligible trusted-worker apply. It does nothing without a separate exact-digest deployment allowlist; old auto-approved proposals remain manual-apply. |
 | 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. |
 | proposal `reversibility` | `REVERSIBLE` | 1.4 | Direct SQL only. Captures a bounded inverse after unambiguous apply; operator `revert` creates a new independently approved proposal. |
 | evidence options | `REQUIRE EVIDENCE` | 0.1 | Detailed evidence sources/handle prefixes are not expressible in DSL yet; use embedded JSON or generated contract JSON for those. |

package/docs/current-scope.md

@@ -2,9 +2,12 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current `1.6` scope:
+Current `1.6.3` scope:
 
 - local semantic MCP tools over Postgres/MySQL without raw SQL tools;
+- one-command, resumable, review-by-exception onboarding from
+  `DATABASE_URL` to a real safe read, bounded exploration, protected named
+  tools, guided write proposals, and host-neutral MCP client setup;
 - deterministic whole-schema Auto Boundary drafting from database metadata,
   statically parsed Prisma/Drizzle schemas, OpenAPI documents, and existing
   Synapsor definitions;
@@ -23,6 +26,10 @@ Current `1.6` scope:
   generated authority explicitly bound to a generation lock;
 - trusted context from environment, verified HTTP claims, Cloud sessions, or
   explicit development-only static values;
+- verified operator decisions through signed local keys or external OIDC/JWKS
+  identity, with exact contract-role matching, token-time/issuer/audience
+  checks, immutable decision evidence, key rotation, and independent approval
+  and apply authority;
 - evidence handles, normalized query audit, proposals, receipts, local replay,
   and read-only lifecycle inspection without copying proposal ids;
 - optional proposal/evidence freshness: live target and declared same-source
@@ -34,6 +41,15 @@ Current `1.6` scope:
   and protocol-v3 exact receipts;
 - opt-in reviewed compensation for supported direct SQL changes, using a
   separate operator proposal and protocol-v4 receipt;
+- default-off operator-supervised automatic apply for exact-digest,
+  contract-permitted single-row INSERT/UPDATE capabilities, with an independent
+  deployment allowlist, fenced worker leases, policy/limit/freshness/source
+  revalidation, hardened writer-posture checks, and explicit UNKNOWN
+  reconciliation;
+- durable redacted proposal/worker/boundary/policy attention events, a
+  coalesced no-ID Workbench inbox, quiet per-sink routing and digests, JSONL
+  development output, signed generic HTTPS webhooks, and an optional
+  exact-capability supervision-sink health gate;
 - safety-wrapped app-owned `http_handler` and `command_handler` executors for
   richer approved business transactions;
 - stdio MCP, authenticated Streamable HTTP MCP, and a legacy JSON-RPC bridge;
@@ -63,6 +79,9 @@ Out of scope:
 - general join planning, many-to-many exploration, arbitrary formulas,
   functions, windows, `HAVING`, subqueries, or statistical privacy guarantees;
 - model-selected tenant/principal, activation, approval, or commit authority;
+- automatic worker execution for DELETE, reversible changes, set writes,
+  app-owned/external effects, or capabilities without deterministic
+  single-row conflict/deduplication and receipt guarantees;
 - UPSERT, DDL, free-form predicates, unbounded writes, or cross-table direct
   transactions;
 - strict atomic freshness for app-owned handlers, APIs, or cross-source

package/docs/cursor-plugin.md

@@ -19,7 +19,7 @@ claim that Cursor Marketplace review has completed.
 
 ## What the plugin installs
 
-- one production stdio MCP server pinned to `@synapsor/runner@1.6.1`;
+- one production stdio MCP server pinned to `@synapsor/runner@1.6.2`;
 - one `/synapsor-protect` agent command;
 - one discoverable Safe Action skill;
 - one file-scoped rule for `synapsor/actions/**/*.ts`;
@@ -80,7 +80,7 @@ Required listing media:
 
 ## Submission checklist
 
-- [ ] Runner 1.6.1 package and plugin version agree.
+- [ ] Runner 1.6.2 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.

package/docs/dsl-json-parity.md

@@ -0,0 +1,75 @@
+# DSL / JSON Parity Matrix
+
+Status: Synapsor contract `0.1`.
+
+`@synapsor/spec` is the canonical contract. `@synapsor/dsl` is an authoring
+layer that compiles into that JSON. `@synapsor/runner` and Synapsor Cloud should
+consume the same contract shape instead of inventing separate semantics.
+
+Author DSL files as `contract.synapsor.sql` when possible so editors provide
+generic SQL highlighting. The legacy `contract.synapsor` suffix remains
+supported, and both filenames compile to the same canonical JSON.
+
+Legend:
+
+- Supported: validated and preserved.
+- Enforced: runtime checks the field before exposing or applying behavior.
+- Preview: accepted as a contract declaration, but not a full local runtime
+  engine.
+- Not supported: fails clearly or is documented as intentionally absent.
+
+| Field / semantic | JSON spec | DSL syntax | Compile output | Runner load | Runner enforcement | C++/Cloud import/export | Cloud push | Tests / notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Context names | Supported | `CREATE AGENT CONTEXT` | Supported | Supported | Referenced by capabilities/workflows | Supported | Supported | Spec, DSL, runner, C++ fixtures |
+| Capability names | Supported | `CREATE CAPABILITY` | Supported | Supported | Exposed as semantic MCP tools | Supported | Supported | Raw SQL/approval/commit tools remain absent |
+| Workflow names | Supported | `CREATE AGENT WORKFLOW` | Supported | Loaded as declaration | Preview only; runner does not execute full DAGs | Supported as declaration | Supported | Do not claim workflow DAG execution |
+| Policy names | Supported | Approval policy emitted by `AUTO APPROVE WHEN` | Preserved where represented | Loaded | Limited/local | Supported/preserved or rejected clearly | Supported | Rich policy packs are Cloud/paid surface |
+| Contract description | Supported in `metadata.description` | Via metadata/examples | Preserved | Preserved | Not behavior-affecting | Supported | Supported | Useful for registry display |
+| Context description | Supported | Preview/partial | Preserved when present | Preserved | Not behavior-affecting | Supported | Supported | Unknown fields fail unless extension-prefixed |
+| Capability description | Supported | `DESCRIPTION '...'` | Supported | Tool metadata | Model-facing description | Supported | Supported | CLI tests inspect generated metadata |
+| Argument description | Supported | `ARG ... DESCRIPTION '...'` | Supported | Input schema | Model-facing schema | Supported | Supported | Required args validated |
+| Returns hint | Supported as `returns_hint` | `RETURNS HINT '...'` | Supported | Tool metadata | Model-facing output guidance | Supported | Supported | Strict DSL warns when missing on proposals |
+| Arg name/type/required | Supported | `ARG name TYPE REQUIRED` | Supported | Input schema | Required/type validation | Supported | Supported | Model trust args rejected |
+| Primary-key lookup | Supported as `lookup.id_from_arg` | `LOOKUP arg BY primary_key` | Supported; non-primary columns fail | Loaded | One fixed primary-key row | Supported | Supported | Compiler rejects `LOOKUP_COLUMN_UNSUPPORTED` rather than rewriting intent |
+| Arg max length | Supported | `MAX LENGTH n` | Supported | Input schema | Enforced where runtime has input schema checks | Supported | Supported | String patterns are not yet supported |
+| Arg numeric bounds | Supported | `ARG amount NUMBER MIN n MAX m` and `BOUND field n..m` | Supported | Input schema/proposal metadata | Enforced before proposal/apply where patch binding is known | Supported | Supported | Numeric-bounds fixture |
+| Arg enum | Supported in JSON | Not expressible in DSL 0.1 | Preserved if in JSON | Loaded into schema | Enforced by schema validation where present | Supported/rejected clearly by validator | Supported | Use canonical JSON when an enum is required |
+| Defaults / nullable | Not stable in 0.1 | Not supported | Fails as unknown core fields | Not supported | Not supported | Rejected unless extension-prefixed | Rejected | Avoid implying defaulted args |
+| Visible fields | Supported | `ALLOW READ ...` | Supported | Read/proposal field map | Only visible fields can be returned | Supported | Supported | Kept-out overlap rejected |
+| Kept-out fields | Supported | `KEEP OUT ...` | Supported | Hidden from tool schemas/results | Must not leak into evidence/replay/proposal surfaces | Supported | Supported | Kept-out conformance fixture |
+| Hidden/model-forbidden fields | Represented by kept-out/trusted bindings | `KEEP OUT`, trusted context bindings | Supported | Supported | Raw table/column args rejected | Supported | Supported | No raw table/column model args |
+| Session/tenant/principal bindings | Canonical `SESSION` plus `ENVIRONMENT`, `HTTP_CLAIM`, `CLOUD_SESSION`, and `STATIC_DEV` | `BIND ... FROM source`, `TENANT BINDING`, `PRINCIPAL BINDING` | Preserved; `--target runner` rejects `SESSION` | Runner rejects `SESSION`; implemented providers load normally | Model cannot supply tenant/principal authority; verified HTTP/Cloud claims remain distinct from process environment | C++/Cloud implements typed `SESSION` | Supported as canonical content | Runner commands fail `SESSION_BINDING_UNSUPPORTED`; no environment fallback |
+| Evidence required | Supported | `REQUIRE EVIDENCE` | Supported | Loaded | Evidence/query audit recorded by runner flows | Supported | Supported | Read/proposal fixtures |
+| Evidence options | Supported as `sources`, `query_audit`, `handle_prefix` | Partial | Preserved when present | Loaded | Query audit/evidence handles where supported | Supported/preserved | Supported | More DSL clauses may be added later |
+| Proposal action | Supported | `PROPOSE ACTION ...` | Supported | Loaded | Proposal created instead of commit | Supported | Supported | Proposal conformance fixture |
+| Allowed write fields | Supported | `ALLOW WRITE ...` | Supported | Loaded | Apply rejects widening beyond reviewed fields | Supported | Supported | Contract-authored apply regression |
+| Patch bindings | Supported | `PATCH field = value/ARG arg` | Supported | Loaded | Direct SQL/app handler payload generation | Supported | Supported | Direct/app-handler tests |
+| Numeric proposal bounds | Supported | `BOUND field min..max` | Supported | Loaded | Out-of-bounds proposals rejected | Supported | Supported | Numeric-bounds rejection test |
+| Transition guards | Supported in JSON | `TRANSITION ...` preview | Preserved | Loaded | Enforced only where runner has enough current-row state | Supported/preserved | Supported | Metadata preservation test |
+| Approval requirement | Supported | `APPROVAL ROLE ...` | Supported | Loaded | Approval remains outside MCP | Supported | Supported | No model-facing approve tool |
+| Approval policy | Supported | `AUTO APPROVE WHEN field <= integer` after `APPROVAL ROLE` | Emits `approval.mode=policy`, `approval.policy`, and `policies[]` approval rules | Loaded | Runner may auto-approve; manual apply remains the default. A separate trusted worker may apply only under the exact-digest dual opt-in below. | Must preserve `approval.policy` and `policies[]` | Supported | Auto-approval conformance fixture |
+| Supervised-worker permission | Optional, default-deny `proposal.execution.supervised_worker = "allowed"` | `ALLOW SUPERVISED WORKER APPLY` | Emits only the contract-side permission | Loaded | Applies nothing by itself. Eligible single-row INSERT/UPDATE may be consumed only when a separate deployment allowlist matches the exact active digest; all guarded checks run again. | Canonical field must be preserved; Cloud/C++ execution is not implied | Registry may preserve; execution support is local Runner-specific | Existing contracts without the field retain their normalization, digest, and manual-apply behavior |
+| Writeback direct SQL | Supported | `WRITEBACK DIRECT SQL` | Supported | Loaded | Guarded single-row INSERT/UPDATE/DELETE | New operation fields require independent Cloud/C++ adoption | New operation fields require independent Cloud/C++ adoption | `test:guarded-crud` on Postgres/MySQL |
+| Bounded set writeback | Supported as operation cardinality, typed selection/batch, row/value caps | `UPDATE|DELETE SET`, fixed `SELECT WHERE`, `INSERT SET`, typed `ITEM FIELD`, `MAX ROWS`, `MAX TOTAL` | Supported | Supported | Fixed/frozen/atomic Postgres/MySQL execution; human approval only; hard cap 100 | Not claimed until independently implemented and verified | Registry may preserve; execution support not claimed | R1-R7 conformance plus `test:bounded-set` |
+| Reviewed reversibility | Supported as `proposal.reversibility.mode = reviewed_inverse` | `REVERSIBLE` | Supported | Supported | Direct SQL only; bounded inverse after unambiguous apply; operator revert creates a new proposal; no model-facing rollback | Canonical field must be preserved; Cloud/C++ execution not claimed until independently verified | Registry may preserve; execution support not claimed | Reversible-change-set conformance plus `test:reversible` |
+| Writeback handler | Supported | `WRITEBACK APP HANDLER EXECUTOR name` | Supported | Loaded | Runner POSTs approved proposal to configured executor | Supported as contract intent | Supported | Handler URL/token stay in runner config, not contract |
+| Idempotency metadata | Supported where represented | Limited | Preserved if present | Loaded | Receipts/idempotency guard local writes | Supported/preserved | Supported | Do not store credentials |
+| x-cloud-* extensions | Supported in documented object locations | Not first-class syntax; JSON preserved | Preserved if present | Loaded/preserved | Not behavior unless known | Preserved or rejected clearly | Supported | Unknown unprefixed fields fail |
+| x-runner-* extensions | Supported | Not first-class syntax; JSON preserved | Preserved if present | Loaded/preserved | Runner-specific where documented | Preserved | Supported | Keep separate from core semantics |
+| x-experimental-* extensions | Supported | Not first-class syntax; JSON preserved | Preserved if present | Loaded/preserved | Experimental only | Preserved | Supported | Do not market as stable |
+| Generated pseudo-syntax | Not supported | `ROOT EXTERNAL`, `JOIN EXTERNAL`, `RETURN ANSWER WITH CITATIONS`, `AUTO MERGE` fail | Fails clearly | Not loaded | Not applicable | Rejected unless promoted to spec | Rejected | These are not public 0.1 DSL |
+| Cloud push dry-run | N/A | N/A | Normalized payload | N/A | No network call | N/A | Supported | `cloud push --dry-run --json` |
+| Cloud push upload | N/A | N/A | Normalized payload POST | N/A | N/A | Cloud validates server-side | Supported | `/v1/control/projects/:project_id/agent-contracts` |
+| Cloud registry versioning | N/A | N/A | N/A | N/A | N/A | Project-scoped registry | Supported | Identical digest is idempotent; changed digest creates new version |
+| Runner bundle export | N/A | N/A | N/A | N/A | N/A | Backend bundle endpoint | Supported as backend foundation | Includes placeholders only, no secrets |
+
+## Current Intentional Limits
+
+The runner can declare workflows in contracts, but it does not execute full
+workflow DAGs, settlement policies, native Synapsor branches, or auto-merge
+logic locally. Those remain Cloud/C++ platform features unless separately
+implemented in the OSS runtime.
+
+Contracts must not contain database URLs, API tokens, private keys, passwords,
+or row data. Local runner config stores environment variable names. Cloud push
+stores normalized contract JSON and audit metadata only.

package/docs/dsl-reference.md

@@ -389,6 +389,7 @@ patched column. Values may be identifiers or quoted strings.
   AUTO APPROVE WHEN amount_cents <= 2500
   LIMIT 20 PER DAY
   LIMIT TOTAL 100000 PER DAY
+  ALLOW SUPERVISED WORKER APPLY
   WRITEBACK DIRECT SQL
 ```
 
@@ -422,6 +423,15 @@ leaves the proposal in `pending_review` and records
 `policy_auto_approval_deferred` with observed, proposed, and projected values.
 It does not reject or auto-apply the proposal.
 
+`ALLOW SUPERVISED WORKER APPLY` is an optional contract-side execution
+permission. It compiles to
+`execution: { "supervised_worker": "allowed" }` and changes the contract
+digest. It does not start a worker or turn `AUTO APPROVE` into auto-apply.
+Runner also requires a deployment allowlist for the exact capability/digest
+and accepts only the narrower eligible single-row direct INSERT/UPDATE shapes.
+See [Operator-Supervised Automatic
+Apply](supervised-automatic-apply.md).
+
 Writeback forms:
 
 | Clause | Meaning |

package/docs/fresh-developer-usability.md

@@ -1,110 +1,185 @@
 # Fresh-Developer Usability Protocol
 
-Use this protocol with five developers who have not previously used Synapsor.
-It is a launch gate, not an automated test. A maintainer may rehearse the
-protocol, but must not report a participant result unless that person actually
-completed the session.
+This is the owner-observation script for Runner 1.6.3. Give it to a
+database-familiar developer who has not used Synapsor. Automated tests prove
+the mechanics; this protocol checks whether the product is understandable.
+
+Do not report a participant result unless that person actually completed the
+session.
 
 ## Goal
 
-Measure whether a developer can connect an existing supported staging project,
-draft one disabled Safe Action with a coding agent, receive an exact Data PR,
-approve outside the agent, and find the guarded receipt without learning the
-canonical JSON or SQL-like DSL first.
+Starting from an empty directory and a synthetic or disposable staging
+database, the participant should reach:
+
+```text
+Connect -> Review -> Try -> Explore -> Protect -> Propose
+```
+
+They must do so without raw SQL, hand-authored config/DSL/JSON/DDL, an account,
+Cloud, Cursor, a model key, or maintainer instruction.
 
-Measure product time separately from the initial package download. Start the
-product timer only after `synapsor-runner --version` succeeds.
+Measure product time separately from initial npm download. Start the timer
+after this succeeds:
 
-## Participant Setup
+```bash
+npx -y @synapsor/runner@latest --version
+```
+
+## Setup
 
-Provide each participant with:
+Provide:
 
-- a fresh clone of their application or the support-plan-credit reference app;
 - Node 22.13 or newer;
-- a disposable Postgres staging database and least-privilege read/write roles;
-- exported database URLs and trusted tenant/principal values;
-- current stable Cursor, with no existing Synapsor configuration;
-- the README only. Do not give verbal product-architecture instruction.
-
-Never use production credentials or data. Record the OS, Node version, Cursor
-version, package-install method, database engine, and whether the package was
-already cached.
-
-## Tasks
-
-Ask the participant to complete these tasks without a maintainer taking control:
-
-1. Run the four-second synthetic proof and identify whether the model can call
-   `approve`, `apply`, `commit`, or raw SQL.
-2. Connect the staging project and confirm the trusted organization scope.
-3. Tell Cursor one business action to make safe and use the generated
-   `/synapsor-protect` path or exact fallback prompt.
-4. Find the disabled action file and explain why editing it does not activate a
-   tool.
-5. Open the Workbench effect preview and confirm the source row is unchanged.
-6. Explicitly activate the reviewed digest through the operator-controlled UI.
-7. Reconnect Cursor if instructed and create one proposal through the semantic
-   tool.
-8. Review the exact before/after Data PR, approve outside Cursor, and apply it.
-9. Locate the receipt/replay record and explain what happens on retry.
-10. Draft a second disabled action without changing the active tool surface.
-
-Do not rescue a participant until they have been blocked for two minutes. Record
-the exact screen, command, wording, or missing prerequisite that blocked them.
+- the packaged synthetic FitFlow fixture or equivalent disposable staging
+  Postgres;
+- an exported `DATABASE_URL` using a SELECT-only, non-owner role;
+- exported synthetic `SYNAPSOR_TENANT_ID` and `SYNAPSOR_PRINCIPAL`;
+- the README only;
+- no existing Synapsor project files.
 
-## Measurements
+Never use production credentials or data. Record OS, Node version, package
+cache state, database engine, and whether an external document was opened.
 
-For each participant, record:
+## Participant Prompt
 
-| Measure | Target |
-| --- | --- |
-| Installed CLI to first own-data Data PR | under 5 minutes |
-| Installed CLI to first guarded receipt | under 8 minutes |
-| Second disabled action draft after setup | under 2 minutes |
-| Second action ready for explicit activation | under 5 minutes |
-| Handwritten canonical JSON or DSL | none on the happy path |
-| Extra CLI command after Cursor proposal call | none |
-| Unsafe authority exposed to Cursor | none |
+Say only:
+
+```text
+Set up Synapsor for this staging application. Reach one safe read, ask one
+bounded aggregate question you have not seen before, protect that analysis as
+a reusable tool, and create one safe write proposal. Explain what the model can
+and cannot do as you go.
+```
 
-Also record every wrong turn, maintainer intervention, misunderstood trust
-boundary, and request for a model-provider key or Synapsor account.
+Do not explain Synapsor’s architecture first.
 
-## Pass Criteria
+## Starting Command
 
-The launch gate passes only when all five participants:
+The participant should find and run:
 
-- complete the first Data PR without handwritten JSON or DSL;
-- correctly identify that activation, approval, and apply are outside the
-  model-facing MCP surface;
-- observe unchanged source data before approval;
-- produce one guarded receipt; and
-- expose only the intended semantic read/proposal tools in Cursor.
+```bash
+npx -y @synapsor/runner@latest start --from-env DATABASE_URL
+```
 
-At least four of five must meet every timing target. Any cross-tenant result,
-hidden-field exposure, pre-approval mutation, automatic activation, raw SQL
-tool, or model-visible commit authority is a release blocker regardless of
-timing.
+No other shell command should be required through the first proposal. The
+participant may use Workbench for all human review and Try steps.
+
+## Observation Tasks
+
+Record whether the participant can:
+
+1. identify the database, inspected resources, and current authority state;
+2. explain why no source row was read before activation;
+3. find fields Runner kept out and unresolved high-risk exceptions;
+4. confirm row identity, tenant scope, and principal scope;
+5. activate only the displayed reviewed digest;
+6. drive one real safe read and state which fields were visible;
+7. explain that the result came from a named capability or temporary
+   authoring-only Explore authority;
+8. ask one unfamiliar PM-style aggregate without SQL or plan JSON;
+9. understand a cohort-suppression or reviewed-boundary refusal;
+10. recover from one intentionally blocked request using the displayed single
+    next action;
+11. Protect the useful result without copying an opaque handle;
+12. explain why the protected capability is still disabled;
+13. activate that exact digest and confirm Explore can be disabled while the
+    named capability remains;
+14. choose **Add a safe action** and define one bounded single-row business
+    proposal;
+15. explain why schema structure did not grant business write authority;
+16. call the action and confirm the source database is unchanged;
+17. find the proposal, exact effect, required approval, receipt mode, and
+    conflict guard;
+18. explain who may activate, approve, and apply.
+
+Do not rescue the participant until they have been blocked for two minutes.
+Record the exact screen, wording, or prerequisite that blocked them.
+
+## Required Comprehension Check
+
+Ask the participant to explain these four facts in their own words:
+
+1. The model does not receive raw SQL.
+2. Reads use reviewed fields and trusted tenant/principal scope.
+3. Model-facing writes create proposals instead of committing.
+4. The model cannot activate, approve, or apply.
+
+Any incorrect answer is a usability failure even when the commands worked.
 
-## Reporting Template
+## Measurements
 
-Record one row per real participant:
+| Measure | Release target |
+| --- | --- |
+| First schema summary | at most 60 seconds |
+| First safe read | at most 3 minutes |
+| First PM-style aggregate | at most 5 minutes |
+| First protected named capability | at most 8 minutes |
+| First guided proposal | at most 10 minutes |
+| Shell commands through first proposal | at most 3; golden target is 1 |
+| Manual project-file edits | 0 |
+| External documentation searches | 0 |
+| Raw SQL or plan JSON composed | 0 |
+| Opaque handles copied | 0 |
+| Screens with multiple primary next actions | 0 |
+| Unsafe authority exposed to a model | 0 |
+
+Also record clicks, deliberate human security decisions, wrong turns,
+maintainer interventions, and whether resuming the first command changed any
+file or digest.
+
+For a realistic 30–50-table schema, the first useful result must still complete
+within five minutes through review by exception. A blind bulk-approval control
+is an automatic failure.
+
+## Safety Blockers
+
+Stop and fail the release for any:
+
+- cross-tenant or cross-principal result;
+- kept-out-field exposure;
+- source-row read before activation;
+- source mutation before approval;
+- automatic activation;
+- raw SQL/SQL-string/model-generated identifier;
+- model-visible activation, approval, apply, commit, setup, or revert;
+- production or remote Scoped Explore tool;
+- write-capable/owner/superuser/`BYPASSRLS` Explore credential;
+- discarded review state after a recoverable failure.
+
+## Recording Template
 
 ```text
 Participant:
 Date:
 Environment:
-Cold package download:
+Package cached: yes | no
 Product timer start:
-First Data PR:
-First receipt:
-Second draft:
-Second activation-ready action:
+Schema summary:
+First safe read:
+First aggregate:
+Protected capability:
+First proposal:
+Shell commands:
+Workbench primary actions:
+Human authority decisions:
+Manual file edits:
+External docs opened:
+Blocked-request recovery:
 Interventions:
-Tool surface observed:
-Safety-boundary explanation:
+Four-part explanation:
 Outcome: pass | fail
 ```
 
-Until five real sessions are recorded, report this gate as **owner verification
-pending**. Do not infer usability from unit tests, protocol tests, or a
-maintainer-run demo.
+## Maintainer Evidence
+
+The automated packed FitFlow run records deterministic timing and interaction
+evidence in:
+
+```text
+development/runner-1.6.3-fitflow-results.json
+```
+
+That evidence does not substitute for a first-time participant. Until a real
+session is recorded, report **owner observation pending**, not “developer
+usability proven.”

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

@@ -21,7 +21,7 @@ scope and run the public guided path:
 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@latest start --from-env DATABASE_URL
 ```
 
 A fresh interactive project with no existing config, selector, or automation
@@ -44,9 +44,10 @@ It does not print your database URL, put the URL in MCP client config, expose
 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.
+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

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