@synapsor/runner 1.6.2 → 1.6.4

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.4` 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;
@@ -12,9 +15,17 @@ Current `1.6` scope:
   and generation locks; no generated authority activates itself;
 - local development/staging Scoped Explore through exactly two temporary MCP
   tools, using typed row plans or a reviewed PM-style analytical cube;
+- optional secured-loopback Workbench Ask over the exact same active tool
+  registry, with OpenAI, Anthropic, or a configured OpenAI-compatible endpoint,
+  digest-bound direct-egress consent, in-memory credentials/history, bounded
+  provider loops, and proposal-only writes;
 - aggregate `count`, reviewed `count_distinct`, `sum`, `avg`, reviewed
   dimensions and day/week/month buckets, typed filters, bounded top-N, and at
-  most one proven many-to-one relationship;
+  most three activated star/depth-two relationship paths, each containing one
+  or two proven many-to-one links with fan-out one;
+- demand-driven operator review for an exact inactive catalog-proven path,
+  explicit nullable-link semantics, per-relation trusted scope, and fail-closed
+  rejection of one-to-many, many-to-many, stale, or ambiguous paths;
 - cohort suppression plus durable extraction, differencing, rate, query,
   response, and complexity limits;
 - Protect This Query from a successful local plan to public DSL, canonical
@@ -23,6 +34,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 +49,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;
@@ -60,9 +84,15 @@ Out of scope:
 
 - raw `execute_sql`, SQL strings, model-generated SQL, or arbitrary identifiers;
 - production Scoped Explore or a general-purpose analytics/query AST;
+- production/shared/remote Ask, model-selected provider configuration,
+  Synapsor-relayed model calls, persisted chat history, or a claim that every
+  OpenAI-compatible server is supported;
 - 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

@@ -6,7 +6,7 @@ The Synapsor Cursor plugin is an official-format Cursor plugin under
 instructions.
 
 Current implementation evidence was checked against Cursor's public plugin,
-plugin-reference, MCP, and deeplink documentation on 2026-07-20:
+plugin-reference, MCP, and deeplink documentation on 2026-07-25:
 
 - <https://cursor.com/docs/plugins>
 - <https://cursor.com/docs/reference/plugins>
@@ -14,12 +14,12 @@ plugin-reference, MCP, and deeplink documentation on 2026-07-20:
 - <https://cursor.com/docs/reference/deeplinks>
 
 The locally installed Cursor version used for validation is recorded in
-`development/runner-1.6.0-progress.md`. Protocol/static validation is not a
+`development/runner-1.6.4-progress.md`. Protocol/static validation is not a
 claim that Cursor Marketplace review has completed.
 
 ## What the plugin installs
 
-- one production stdio MCP server pinned to `@synapsor/runner@1.6.2`;
+- one production stdio MCP server pinned to `@synapsor/runner@1.6.4`;
 - one `/synapsor-protect` agent command;
 - one discoverable Safe Action skill;
 - one file-scoped rule for `synapsor/actions/**/*.ts`;

package/docs/database-enforced-scope.md

@@ -106,6 +106,12 @@ attested. Required properties include:
 - `INSERT` has a suitable `WITH CHECK` expression;
 - `UPDATE` has both `USING` and `WITH CHECK`.
 
+For read-only PostgreSQL views, hardened mode additionally requires
+`security_invoker=true` and `security_barrier=true`, a non-owner/non-bypass
+Runner role, and successful recursive attestation of every referenced base
+relation. See [Reviewed Database Views](reviewed-database-views.md). Ordinary
+owner-rights or unverifiable views fail closed.
+
 ### Example PostgreSQL policy
 
 Use a non-owner read role and a separate non-owner write role. Adapt names and

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

@@ -222,7 +222,8 @@ The protected clauses mean:
 | `PROTECTED READ ROWS` / `AGGREGATE` | Selects a frozen row or aggregate protected-read shape. |
 | `BOUNDARY DIGEST sha256:...` | Binds the capability to the exact human-activated exploration authority. |
 | `GENERATION LOCK sha256:...` | Binds it to the reviewed schema, role/grant/RLS posture, compiler, and Spec fingerprint. |
-| `PROTECTED RELATIONSHIP name ON local_key REFERENCES schema.table.target_key PRIMARY KEY pk TENANT KEY tenant [PRINCIPAL SCOPE KEY principal]` | Freezes at most one inspected, reviewed many-to-one path with fan-out one. |
+| `PROTECTED RELATIONSHIP name ON local_key REFERENCES schema.table.target_key PRIMARY KEY pk TENANT KEY tenant [PRINCIPAL SCOPE KEY principal]` | Legacy one-hop form. It freezes one inspected, reviewed many-to-one path with fan-out one and cannot be mixed with `LINK` declarations. |
+| `PROTECTED RELATIONSHIP name LINK 1|2 ON local_key REFERENCES schema.table.target_key PRIMARY KEY pk TENANT KEY tenant [PRINCIPAL SCOPE KEY principal] UNMATCHED EXCLUDE|KEEP NULL` | Additive path form. Up to three user-named paths may contain one or two contiguous, ordered many-to-one links. Missing-row semantics are explicit and digest-bound. |
 | `PROTECTED FILTER field OP FIXED value` | Freezes a reviewed literal. `OP` is `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE`, or bounded fixed-list `IN`. |
 | `PROTECTED FILTER field OP ARG name` | Allows only one declared typed/bounded argument at that reviewed literal position. |
 | `ALLOW READ ...` / `ROW ORDER BY ...` | Freezes row projection and up to three fixed sort fields for row mode. |
@@ -241,6 +242,16 @@ not have to transcribe digests or limits. The generated DSL compiles through
 canonical Spec. Existing contracts with no `protected_read` field normalize
 and hash exactly as before.
 
+In a `PROTECTED RELATIONSHIP` declaration, `name`, the keys, and the
+`schema.table.target_key` reference are user-reviewed identifiers generated
+from inspected database evidence. `PROTECTED RELATIONSHIP`, `LINK`, `ON`,
+`REFERENCES`, `PRIMARY KEY`, `TENANT KEY`, `PRINCIPAL SCOPE KEY`, and
+`UNMATCHED` are DSL keywords. `LINK 1` starts a path and optional `LINK 2`
+continues that same path. `UNMATCHED EXCLUDE` removes a counted row whose
+optional relationship is missing; `UNMATCHED KEEP NULL` retains it with an
+empty group value. See [Reviewed Relationship
+Paths](reviewed-relationships.md) for the compiled JSON and runtime guarantees.
+
 Protected row and aggregate capabilities can be served after exact-digest
 activation even when temporary Scoped Explore is disabled. Production never
 needs or advertises `app.explore_data`. See [Auto Boundary, Scoped Explore, And
@@ -389,6 +400,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 +434,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.4. 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 --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;
+- a SELECT-only, non-owner connection URL available for hidden paste or an
+  explicitly approved project `.env` file;
+- 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 start
+```
 
-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.4-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.”