@synapsor/runner 1.6.2 → 1.6.4

package/docs/README.md

@@ -18,6 +18,13 @@ no-database demo, wire your database, then read deeper concepts.
   you adopt Runner.
 - [README](../README.md): audit-first proof, no-database demo, safety diagram,
   and the shortest own-database path.
+- [Database To First Safe Tool](guided-onboarding.md): one public command,
+  five-minute first read, ten-minute Explore to Protect, fifteen-minute
+  proposal, resumable setup, guarded development writeback, and host-neutral
+  client handoff.
+- [Workbench Ask With Your Model](workbench-ask.md): optional local OpenAI,
+  Anthropic, and custom-provider chat over the exact reviewed tool surface,
+  with direct-egress consent, session-only credentials, and no added authority.
 - [Troubleshooting First Run](troubleshooting-first-run.md): common first-run
   failures, redacted diagnostics, and fixes.
 
@@ -47,11 +54,16 @@ no-database demo, wire your database, then read deeper concepts.
 
 ## 04 Connect Your DB
 
+- [Database To First Safe Tool](guided-onboarding.md): the complete
+  review-by-exception golden path using the packed npm package.
 - [Auto Boundary, Scoped Explore, And
   Protect](auto-boundary-and-scoped-explore.md): deterministically inspect a
   whole staging application, review one digest-bound boundary, ask bounded row
   and PM-style aggregate questions in Cursor, and turn a useful query into a
   disabled named production capability.
+- [Workbench Ask With Your Model](workbench-ask.md): use the same reviewed
+  tools from Workbench without requiring Cursor or giving the model activation,
+  approval, or apply authority.
 - [Connect Your Own Database](getting-started-own-database.md): inspect a
   staging Postgres/MySQL database through the new whole-schema path or an
   established one-object/headless route.
@@ -95,6 +107,9 @@ no-database demo, wire your database, then read deeper concepts.
 - [Capability Authoring](capability-authoring.md): define read/proposal
   capabilities, model-facing descriptions, result envelopes, trusted context,
   and writeback guards.
+- [Approval Roles And Verified Operator Identity](approval-roles-and-operator-identity.md):
+  trace `APPROVAL ROLE` through IdP claims, immutable approval evidence, and
+  the independent apply-role decision.
 - [DSL Reference](dsl-reference.md): complete supported grammar, clause order,
   compiled meaning, and constraints.
 - [Runner Config Reference](runner-config-reference.md): every public wiring
@@ -111,9 +126,17 @@ no-database demo, wire your database, then read deeper concepts.
   policy outcomes, tenant handling, and hidden-field behavior.
 - [Bounded Aggregate Reads](aggregate-reads.md): fixed production scalar
   aggregates plus the separate authoring-only reviewed aggregate Explore path.
+- [Reviewed Relationship Paths](reviewed-relationships.md): catalog-proven
+  star/depth-two aggregate paths, demand-driven operator review, nullable-link
+  semantics, per-relation scope, and the permanent no-general-join boundary.
+- [Reviewed Database Views](reviewed-database-views.md): expose a reviewed
+  derived measure without adding formulas or SQL to the model-facing planner.
 
 ## 06 Serve MCP
 
+- [Workbench Ask With Your Model](workbench-ask.md): optional secured-loopback
+  client, provider matrix, key/egress lifecycle, endpoint controls, and exact
+  parity with the normal MCP runtime.
 - [Host Compatibility](host-compatibility.md): exact Tested,
   Protocol-tested, Unsupported, and Unknown claims for Cursor and other MCP
   hosts, including the inline-review fallback.
@@ -141,6 +164,14 @@ no-database demo, wire your database, then read deeper concepts.
 
 - [Local Mode](local-mode.md): local store, proposals, approval, replay, and
   writeback flow.
+- [Operator-Supervised Automatic Apply](supervised-automatic-apply.md):
+  separate approval from execution, require contract and deployment opt-in for
+  one exact digest, run the trusted worker, and understand revalidation,
+  eligibility, retries, controls, and UNKNOWN outcomes.
+- [Human Attention And Notifications](human-attention-notifications.md):
+  durable attention events, the no-ID Workbench inbox, quiet defaults,
+  coalescing and digests, signed generic webhooks, delivery recovery, and the
+  optional supervision-health gate.
 - [Shadow Studies](shadow-studies.md): compare what an agent would propose
   with explicit authorized outcomes before granting write authority.
 - [Writeback Executors](writeback-executors.md): app-owned writeback handlers
@@ -162,8 +193,11 @@ no-database demo, wire your database, then read deeper concepts.
 - [Store Lifecycle](store-lifecycle.md): active-store leases, prune safety,
   deleted-store behavior, and concurrent server guardrails.
 - `synapsor-runner activity search`, `evidence`, `query-audit`, `receipts`,
-  `events tail`, and `events webhook`: local evidence, audit, receipt, replay,
-  and lifecycle inspection.
+  `events tail`, `attention show`, and `notifications status`: local evidence,
+  audit, receipt, replay, complete lifecycle history, and human-attention
+  inspection. The legacy development lifecycle webhook remains documented in
+  [Local Mode](local-mode.md); production attention delivery uses the signed,
+  quiet notification pipeline.
 - `examples/mysql-refund-agent/`: MySQL order/refund review example using the
   same proposal, approval, guarded writeback, and replay loop.
 - [Scoped Ledger Reports](compliance-reports.md): object/principal JSON,

package/docs/agent-guided-setup.md

@@ -0,0 +1,239 @@
+# Agent-Guided Synapsor Setup
+
+This guide lets Claude Code, Codex, Cursor, or another coding agent help a
+developer set up Synapsor Runner without taking over a human security decision.
+It uses the same local-first flow a developer runs directly. No Synapsor
+account, Cloud login, model API key, global installation, or database
+replication is required.
+
+## Copyable Prompt
+
+```text
+Set up Synapsor Runner for this project.
+
+Use DATABASE_URL from my environment. Run the setup yourself and explain each
+step briefly. Stop only when I must review the data boundary or make another
+human-authority decision. Never ask me to paste credentials into chat, and
+never activate, approve, or apply anything for me.
+
+Finish by driving one safe tool, showing what the agent can and cannot access,
+and giving me the MCP configuration for my client.
+```
+
+## Rules For The Coding Agent
+
+The coding agent may inspect project files, check tool availability, run the
+documented CLI, explain failures, and resume completed work.
+
+The coding agent must not:
+
+- ask the user to paste a database URL, password, token, or private key into
+  chat;
+- print or persist the value of `DATABASE_URL` or another credential;
+- choose a tenant or principal boundary;
+- decide that a sensitive or uncertain field is safe to expose;
+- activate an exploration boundary or named capability;
+- approve, reject, apply, reconcile, or revert a proposal;
+- run writeback setup with `--apply`;
+- weaken a failed role, RLS, schema-lock, profile, or transport check;
+- replace an existing generated project or use `--force` without a human
+  choosing the destructive path;
+- fetch or execute setup code other than the documented npm package command.
+
+The model-facing MCP surface never contains activation, approval, or apply
+tools. A coding agent operating the terminal must preserve the same separation.
+
+## Guided Procedure
+
+### 1. Verify Local Prerequisites
+
+Run:
+
+```bash
+node --version
+test -n "${DATABASE_URL:-}"
+npx -y @synapsor/runner --version
+```
+
+Do not run `echo "$DATABASE_URL"` or otherwise reveal its value. Runner
+requires Node 22.13 or newer.
+
+Report one sentence:
+
+```text
+Node, the Runner package, and an exported DATABASE_URL are available.
+Next: inspect metadata and open the local boundary review.
+```
+
+If `DATABASE_URL` is absent, stop and say:
+
+```text
+DATABASE_URL is not exported in this shell. Export it locally, without pasting
+it into chat, then ask me to continue.
+```
+
+### 2. Start Or Resume The Guided Project
+
+From the intended project directory, run:
+
+```bash
+npx -y @synapsor/runner start --from-env DATABASE_URL
+```
+
+For a fresh interactive project, Runner performs metadata-only inspection,
+creates disabled review artifacts, validates the generated project, initializes
+the local ledger, and starts the secured loopback Workbench. It prints one
+local URL if a browser cannot be opened.
+
+For an existing guided project, the same command resumes it. Resume and Try do
+not rescan the database, rewrite files, or change a digest. Do not add
+`--force`. A schema rescan or reset is a separate human choice in Workbench.
+
+Report:
+
+```text
+Runner created or resumed a disabled local boundary. No source rows were read
+and the database was not changed.
+Next: review the security exceptions in Workbench.
+```
+
+Then stop. The human must review:
+
+- fields kept out and fields still uncertain;
+- exact row identity;
+- trusted tenant and principal scope;
+- aggregate-safe dimensions and measures;
+- database-role and RLS posture;
+- the exact digest being activated.
+
+Do not click or call activation endpoints for the user.
+
+### 3. Continue After Human Activation
+
+After the user confirms that Workbench shows an active reviewed boundary,
+continue in the same Workbench session. The built-in Explore form performs the
+first bounded read and PM-style aggregate without SQL or plan JSON.
+
+The coding agent may verify the active local surface without copying an opaque
+handle:
+
+```bash
+npx -y @synapsor/runner try call --list --format json
+```
+
+If no named capability is active yet, that is expected: a temporary local
+Scoped Explore boundary is not a production named tool. Ask the user to run the
+suggested aggregate in Workbench and select **Protect this analysis**.
+
+Protect creates public DSL, canonical JSON, tests, and a disabled named
+capability. Stop again for exact-digest human activation. Do not activate it
+for the user.
+
+### 4. Verify The First Named Tool
+
+After the human activates a protected named capability, run:
+
+```bash
+npx -y @synapsor/runner try call --list --format json
+```
+
+Use the tool name returned by that command. For a tool with generated sample
+input, run:
+
+```bash
+npx -y @synapsor/runner try call <tool-name> --sample --json
+```
+
+Do not invent tenant or principal arguments. Trusted scope comes from the
+reviewed environment/session binding outside model input.
+
+Report:
+
+```text
+Your first safe named tool is working.
+The result used only reviewed fields and trusted scope.
+Source database changed: no.
+Next: connect the same reviewed tool surface to your MCP client.
+```
+
+### 5. Present MCP Setup
+
+Workbench displays ready-to-copy configurations for:
+
+- Cursor project MCP;
+- Claude-compatible local stdio MCP;
+- Codex;
+- generic stdio MCP.
+
+All hosts launch the same reviewed Runner project. None receives a broader
+authority surface.
+
+For a terminal-rendered generic configuration, run:
+
+```bash
+npx -y @synapsor/runner mcp config --absolute-paths
+```
+
+Do not write into a client configuration without explicit user consent. Cursor
+has a separate consent-gated installer:
+
+```bash
+npx -y @synapsor/runner mcp install cursor --project --dry-run
+```
+
+Show the dry-run result first. Installation remains a human choice.
+
+## Guided Write Action
+
+After the first safe read, Workbench can generate one bounded write action.
+Schema structure supplies candidates only. The human decides business intent,
+allowed fields, values or transitions, trusted scope, version guard, reviewer,
+limits, optional bounded policy approval, receipt mode, and compensation.
+
+The generated action starts disabled. Its first model-facing call creates an
+exact proposal and must say:
+
+```text
+Proposal created.
+Source database changed: no.
+The model cannot approve or apply this proposal.
+```
+
+Stop at action activation, proposal approval, writeback setup, apply, and
+revert. Those are human or trusted-operator decisions outside MCP.
+
+Manual apply is the default. An operator may separately configure
+digest-bound supervised execution for eligible production actions. In that
+mode, the response must disclose that reviewed policy may approve and a trusted
+worker may later apply the proposal without a per-request click. The coding
+agent still cannot enable, start, pause, configure, or control that worker. See
+[Operator-Supervised Automatic Apply](supervised-automatic-apply.md).
+
+## Recovery
+
+Use the one next action Runner prints. Preserve the current project and review
+state.
+
+| Failure | Required response |
+| --- | --- |
+| Connection failed | Confirm the local environment variable and network path without printing the credential, then rerun `start`. |
+| Privileged, writable, owner, `BYPASSRLS`, or unverifiable read role | Stop source-row exploration. Ask the user to supply a verifiably read-only role. |
+| Tenant, principal, or row identity unresolved | Stop and direct the human to the highlighted Workbench exception. |
+| Sensitive field blocked | Keep it out unless a human records a reasoned field decision. |
+| Existing generated project | Run the same `start` command and choose Resume. Do not use `--force`. |
+| Stale generation lock | Preserve active named capabilities; choose Rescan and review changes. |
+| Workbench port unavailable | Use the single alternate loopback URL Runner prints or free the occupied local port. |
+| Writeback prerequisites missing | Keep the proposal unchanged. Use `writeback setup` for a preview only and stop for human review. |
+
+## What The Developer Should Understand
+
+At the end, ask the developer to explain these four facts:
+
+1. The model never receives raw SQL authority.
+2. Reads are limited to reviewed fields under trusted tenant and principal
+   scope.
+3. Model-facing writes create proposals rather than committing changes.
+4. The model cannot activate authority, approve proposals, or apply writes.
+
+If any answer is unclear, reopen the Workbench Overview. Do not expand authority
+to make onboarding appear successful.

package/docs/aggregate-reads.md

@@ -61,11 +61,20 @@ suppression reduces single-record inference; it does not solve every statistical
 inference risk. Review the underlying view, database role, and aggregation
 policy as well.
 
+For a derived measure, keep formulas and joins out of the model-facing grammar.
+Define them in a reviewed database view and expose only a typed view column
+through the fixed aggregate capability. The complete hardened PostgreSQL
+pattern and runnable retail example are in [Reviewed Database Views For Derived
+Measures](reviewed-database-views.md).
+
 Scoped Aggregate Explore reuses and extends this suppression machinery. Its
 reviewed boundary additionally fixes aggregate-safe measures,
 `count_distinct` identifiers, dimensions, day/week/month buckets, typed
-filters, optional one-hop proven many-to-one relationships, maximum groups,
-response/query/rate limits, and durable extraction/differencing budgets. A
-field may be approved for `count_distinct` while its raw values remain hidden.
-Production receives only the protected named capability; broad Explore is
-absent from production `tools/list`.
+filters, up to three activated relationship paths (one or two proven
+many-to-one links per path), maximum groups, response/query/rate limits, and
+durable extraction/differencing budgets. A field may be approved for
+`count_distinct` while its raw values remain hidden. Relationship paths remain
+catalog-proven, operator-activated authority; the model cannot supply join
+identifiers or activate an inactive path. See [Reviewed Relationship
+Paths](reviewed-relationships.md). Production receives only the protected named
+capability; broad Explore is absent from production `tools/list`.

package/docs/app-owned-executors.md

@@ -24,12 +24,11 @@ the receipt, and includes the result in replay.
 > error receipts. If you skip those checks, you can reintroduce cross-tenant
 > writes, lost updates, or duplicate writes. Keep handler credentials out of MCP.
 
-Runner 1.6.1 strict `proposal_freshness` is limited to same-database direct SQL
-writeback. Runner rejects it for `http_handler`, `command_handler`, and
-cross-source dependencies because a local preflight cannot be atomic with an
-effect executed elsewhere. If supporting evidence matters, the app handler
-must lock and re-read those rows inside its own business transaction and fail
-closed on drift. See
+Strict `proposal_freshness` is limited to same-database direct SQL writeback.
+Runner rejects it for `http_handler`, `command_handler`, and cross-source
+dependencies because a local preflight cannot be atomic with an effect executed
+elsewhere. If supporting evidence matters, the app handler must lock and re-read
+those rows inside its own business transaction and fail closed on drift. See
 [Proposal And Evidence Freshness](proposal-evidence-freshness.md).
 
 A handler is your application endpoint or script. It is not a second Synapsor