@synapsor/runner 1.6.2 → 1.6.4

package/docs/human-attention-notifications.md

@@ -0,0 +1,367 @@
+# Human Attention And Notifications
+
+Runner keeps the full lifecycle in its ledger and secured Workbench. External
+notifications are a quiet interruption channel for meaningful human attention,
+not a copy of every state transition.
+
+Notifications are additive, local-first, and disabled by default. Runner needs
+no webhook, network connection, Cloud account, or continuously running
+dispatcher for its existing proposal, approval, apply, receipt, and replay
+flows.
+
+## Architecture
+
+```text
+authoritative ledger transition
+  -> immutable attention event in the same store transaction
+  -> coalesced Human Attention item
+  -> separately operated dispatcher
+  -> configured JSONL or signed webhook sink
+  -> authenticated human opens Workbench
+  -> existing approval/recovery control handles the item
+```
+
+An event informs. It never authorizes. A webhook response, delivery receipt,
+inbox acknowledgement, or notification replay cannot activate a capability,
+approve a proposal, apply a write, cancel work, or resolve an unknown database
+outcome.
+
+SQLite and shared PostgreSQL runtime stores retain the same event identities,
+attention projection, acknowledgement, and delivery state.
+
+## Quiet Default
+
+Under the default route, successful activity remains visible in the ledger,
+Workbench timeline, CLI, metrics, and optional digest, but does not interrupt a
+human.
+
+No immediate external notification is sent by default for:
+
+- proposal creation, policy auto-approval, approval, or queueing;
+- a worker lease or individual retry;
+- successful manual or automatic apply;
+- an isolated conflict that Runner handled safely;
+- planned worker start, pause, resume, drain, or stop;
+- capability activation by the same operator.
+
+Immediate delivery defaults to states where timely attention matters:
+
+- human approval required;
+- UNKNOWN transaction outcome or reconciliation required;
+- dead-letter work;
+- sustained worker-health failure;
+- queue depth/age crossing an operator threshold;
+- schema drift or stale digest blocking authority;
+- invalidated writer credential posture;
+- critical policy/limit failure;
+- an approved proposal approaching expiry while action is still possible.
+
+Informational success events can be sent only through an explicit all-events
+route or periodic digest.
+
+## Events And Attention Items
+
+Events are immutable audit facts. Attention items are durable incident
+projections over related events.
+
+For example, ten proposals requiring the same role can produce ten immutable
+events but one item saying that ten proposals need review. Repeated worker
+failures, queue backlog, or the same schema-drift condition update one item and
+its occurrence count. Retry attempts stay internal until the configured
+attempt/duration threshold is crossed.
+
+Attention states are:
+
+- `open`;
+- `acknowledged`;
+- `resolved`;
+- `expired`.
+
+Acknowledgement means only that a verified operator saw the item. It is not
+approval or resolution.
+
+## Configure Sinks
+
+This operator-owned config enables one signed webhook and one optional
+development JSONL stream:
+
+```json
+{
+  "notifications": {
+    "enabled": true,
+    "workbench_url_env": "SYNAPSOR_WORKBENCH_URL",
+    "sinks": [
+      {
+        "id": "operations",
+        "type": "webhook",
+        "enabled": true,
+        "url_env": "SYNAPSOR_NOTIFY_WEBHOOK_URL",
+        "signing_secret_env": "SYNAPSOR_NOTIFY_SIGNING_SECRET",
+        "minimum_severity": "warning",
+        "events": [
+          "proposal.review_required",
+          "worker.dead_lettered",
+          "worker.unknown_outcome",
+          "worker.reconciliation_required",
+          "schema.drift_detected"
+        ],
+        "capabilities": ["billing.propose_small_credit"],
+        "environments": ["staging", "production"],
+        "delivery": "immediate",
+        "max_attempts": 5,
+        "timeout_ms": 3000,
+        "max_response_bytes": 1024,
+        "replay_window_seconds": 300,
+        "allow_private_destinations": false,
+        "recovery_notifications": false,
+        "budgets": {
+          "per_minute": 10,
+          "per_hour": 100,
+          "immediate_informational_per_hour": 0,
+          "aggregation_window_seconds": 300,
+          "cooldown_seconds": 600,
+          "max_unresolved_reminders": 3,
+          "digest_cadence_minutes": 1440,
+          "escalation_delay_seconds": 60,
+          "retry_attempt_threshold": 3,
+          "degraded_duration_seconds": 120,
+          "queue_depth_threshold": 100,
+          "queue_age_seconds": 300
+        },
+        "quiet_hours": {
+          "start_utc_hour": 22,
+          "end_utc_hour": 7
+        }
+      },
+      {
+        "id": "development",
+        "type": "jsonl",
+        "enabled": false,
+        "destination": "stdout",
+        "minimum_severity": "informational",
+        "delivery": "all"
+      }
+    ]
+  }
+}
+```
+
+Set values only in the operator environment:
+
+```bash
+export SYNAPSOR_WORKBENCH_URL=https://runner-ops.example.internal
+export SYNAPSOR_NOTIFY_WEBHOOK_URL=https://events.example.com/synapsor
+export SYNAPSOR_NOTIFY_SIGNING_SECRET='at-least-32-random-bytes'
+```
+
+The config stores environment-variable names, not URLs or secrets. Events never
+contain credentials, database URLs, SQL, source rows, aggregate group results,
+kept-out fields, trusted tenant/principal values, sensitive arguments, or
+authority tokens.
+
+## Route By Destination
+
+Every sink has its own event, severity, capability, environment, and delivery
+route. A practical split is:
+
+| Sink | Route |
+| --- | --- |
+| Workbench | Complete event and attention history |
+| Team chat webhook | Review-required and operational warnings |
+| Incident webhook | UNKNOWN, reconciliation, dead letter, sustained worker failure |
+| Email-provider webhook | Daily digest |
+| Audit webhook | Explicit all-events redacted stream |
+
+The ledger and Workbench remain the source of truth.
+
+## Operate Without Copying IDs
+
+Inspect the highest-priority item:
+
+```bash
+synapsor-runner attention list --config ./synapsor.runner.json
+synapsor-runner attention show --config ./synapsor.runner.json
+```
+
+Use `attention show <attention_id>` only when selecting a specific item. JSON
+automation is available with `--json`.
+
+Acknowledgement is explicit:
+
+```bash
+synapsor-runner attention acknowledge --actor alice \
+  --config ./synapsor.runner.json
+```
+
+Production acknowledgement follows configured verified operator identity and is
+cryptographically bound to the exact item digest and occurrence.
+
+Inspect and test delivery:
+
+```bash
+synapsor-runner notifications status --config ./synapsor.runner.json
+synapsor-runner notifications test --sink operations \
+  --config ./synapsor.runner.json
+synapsor-runner notifications dispatch --sink operations --limit 20 \
+  --config ./synapsor.runner.json
+```
+
+`notifications test` sends an unmistakable synthetic event containing no
+database or proposal data. Opening Workbench, installing Runner, and starting
+MCP never start outbound delivery.
+
+Requeue one dead-letter delivery:
+
+```bash
+synapsor-runner notifications replay latest --yes \
+  --reason "Webhook repaired and synthetic test passed" \
+  --config ./synapsor.runner.json
+```
+
+This replays only the immutable redacted notification. It does not replay an
+approval or database mutation. Replay is an operator recovery action and
+requires the configured `signed_key` or `jwt_oidc` identity. Runner binds the
+verified decision to the exact delivery revision and records a redacted
+immutable `notification.replayed` audit event.
+
+## Webhook Contract
+
+Runner sends a CloudEvents 1.0 structured JSON body with content type
+`application/cloudevents+json`. Important headers are:
+
+```text
+X-Synapsor-Event-Id
+X-Synapsor-Timestamp
+X-Synapsor-Signature-Version: v1
+X-Synapsor-Signature: sha256=<hex HMAC>
+```
+
+The HMAC-SHA-256 input is the UTF-8 string
+`v1.<timestamp>.<event-id>.<exact-body>`. Receivers must:
+
+1. Require signature version `v1`.
+2. Reject timestamps outside the configured replay window.
+3. Verify the HMAC with a timing-safe comparison.
+4. Deduplicate the stable event ID.
+5. Return only a bounded transport acknowledgement.
+
+Runner ignores response content. A receiver cannot return a command.
+
+A minimal Node receiver can verify the exact bytes before parsing JSON:
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export function verifySynapsorWebhook(rawBody, headers, secret, now = Date.now()) {
+  const eventId = headers["x-synapsor-event-id"];
+  const timestamp = headers["x-synapsor-timestamp"];
+  const version = headers["x-synapsor-signature-version"];
+  const suppliedHeader = headers["x-synapsor-signature"];
+  if (!eventId || !timestamp || version !== "v1" || !suppliedHeader?.startsWith("sha256=")) {
+    return false;
+  }
+
+  const timestampSeconds = Number(timestamp);
+  const ageMs = Math.abs(now - timestampSeconds * 1000);
+  if (!Number.isSafeInteger(timestampSeconds) || ageMs > 300_000) return false;
+
+  const expected = Buffer.from(
+    createHmac("sha256", secret)
+      .update(`v1.${timestamp}.${eventId}.${rawBody}`, "utf8")
+      .digest("hex"),
+    "hex",
+  );
+  const supplied = Buffer.from(suppliedHeader.slice("sha256=".length), "hex");
+  return expected.length === supplied.length && timingSafeEqual(expected, supplied);
+}
+```
+
+Read the request as raw UTF-8 bytes for verification; reserializing parsed JSON
+changes the signed body. Store the event ID for at least the replay window and
+reject a duplicate before processing it.
+
+The structured body resembles:
+
+```json
+{
+  "specversion": "1.0",
+  "id": "aev_...",
+  "type": "ai.synapsor.worker.reconciliation_required",
+  "source": "urn:synapsor:runner:production",
+  "time": "2026-07-25T00:00:00.000Z",
+  "datacontenttype": "application/json",
+  "subject": "billing.propose_small_credit",
+  "data": {
+    "schema_version": "synapsor.notification.v1",
+    "severity": "critical",
+    "environment": "production",
+    "capability": "billing.propose_small_credit",
+    "contract_digest": "sha256:...",
+    "summary": "A guarded apply needs operator reconciliation.",
+    "workbench_url": "https://runner-ops.example.internal/attention/att_..."
+  }
+}
+```
+
+The Workbench URL identifies an item but carries no approval or recovery
+authority. The operator must authenticate normally.
+
+HTTPS is required by default. Redirects and unsafe loopback, link-local,
+metadata, multicast, unspecified, private, and rebinding destinations are
+refused. Intentional private destinations require both
+`allow_private_destinations: true` and an exact `private_host_allowlist`.
+
+## Delivery And Noise Guarantees
+
+Delivery is at least once. Sink-specific records use atomic leases, fencing,
+bounded retries, jittered backoff, timeout, maximum attempts, and dead-letter
+state. Repeated delivery cannot repeat proposal authority or source mutation.
+
+When a non-critical budget is exhausted, Runner preserves every event, updates
+the Workbench item, and suppresses or batches external messages. Critical events
+bypass ordinary quiet hours and budgets but still coalesce under a separate
+bounded emergency ceiling.
+
+Optional digests report redacted counts for proposals, auto-approval, apply,
+review-required work, conflicts, retries, dead letters, limits, queue age, and
+unresolved critical items. They link to authenticated Workbench detail.
+
+Recovery messages are off by default. When an incident resolves, Workbench is
+updated; an external recovery message is sent only when that sink explicitly
+enables `recovery_notifications` or the critical-route policy requires it.
+
+## Retry And Dead-Letter Runbook
+
+1. Run `notifications status --json` and inspect sink health, pending delivery,
+   and dead-letter counts.
+2. Open the corresponding Workbench attention item. Confirm the authoritative
+   proposal/worker state before changing delivery.
+3. Repair the operator-owned destination, DNS policy, TLS, or secret rotation.
+4. Send `notifications test --sink <id>`; it contains no database data.
+5. Run `notifications dispatch --sink <id> --limit 20` to drain eligible work.
+6. Replay a dead-letter delivery only with
+   `notifications replay <delivery_id> --yes --reason "<why replay is safe>"`.
+
+Replay preserves the original immutable event ID. It cannot re-run the database
+operation. The exact recovery decision must be verified through the configured
+operator identity. A still-failing sink remains observable and does not rewrite
+the underlying proposal outcome.
+
+## Supervised Worker Health Gate
+
+An exact supervised-worker capability may list:
+
+```json
+{
+  "required_attention_sinks": ["operations"]
+}
+```
+
+If every required sink is unhealthy or untested, an otherwise eligible
+policy-approved production write remains queued. Workbench explains that
+operator visibility is unavailable. A healthy sink does not approve anything;
+after recovery, the worker still repeats every ordinary digest, policy, scope,
+freshness, limit, credential, lease, and guarded-write check.
+
+See [Operator-Supervised Automatic
+Apply](supervised-automatic-apply.md) for the execution boundary.

package/docs/limitations.md

@@ -1,11 +1,14 @@
 # Limitations
 
-Synapsor Runner is intentionally narrow. Version 1.6 adds deterministic
-whole-application boundary drafting and a local authoring-only Explore ->
-Protect path on top of guarded writes. Version 1.6.1 also adds opt-in
-proposal/evidence freshness for exact same-source direct-SQL proposals. It does
-not turn Runner into a generic database query tool, claim Synapsor Cloud scale,
-or claim an enterprise SLA.
+Synapsor Runner is intentionally narrow. It combines deterministic
+whole-application boundary drafting, local authoring-only Explore -> Protect,
+guarded writes, opt-in proposal/evidence freshness, verified operator identity,
+default-off supervised execution, and quiet human-attention delivery. Reviewed
+aggregate paths are limited to proven star/depth-two many-to-one relationships,
+not a general join planner. Optional local Workbench Ask is a client of the
+existing reviewed tools; the complete no-model path remains the default.
+Runner does not become a generic database query tool, Synapsor Cloud, or an
+enterprise SLA.
 
 ## Supported
 
@@ -15,8 +18,9 @@ or claim an enterprise SLA.
 - Optional shared Postgres proposal/evidence/replay runtime store for MCP serving.
 - Asymmetric claim-bound Streamable HTTP sessions and explicit readiness.
 - Native Postgres/MySQL source pools and operational/fleet-wide rate limits.
-- Verified operator approval through CLI, optional distinct-reviewer quorum,
-  and shared local review UI reads.
+- Verified operator approval through CLI or the secured local Workbench,
+  optional distinct-reviewer quorum, separate apply authority, and
+  proposal-centered lifecycle inspection.
 - Optional live target and explicitly declared supporting-row freshness checks
   before every approval, with immutable proof binding and final transactional
   revalidation for PostgreSQL/MySQL direct SQL writeback.
@@ -59,10 +63,20 @@ or claim an enterprise SLA.
   existing Synapsor definitions. Generated authority starts disabled.
 - Local development/staging Scoped Explore through exactly
   `app.describe_data` and `app.explore_data`, with no SQL-string argument.
+- Optional development/staging loopback Workbench Ask through OpenAI,
+  Anthropic, or a configured OpenAI-compatible endpoint. Provider calls use the
+  exact active MCP/runtime surface, explicit direct-egress consent, in-memory
+  credential/history state, fixed tool/time/size/token bounds, and
+  proposal-only write behavior.
 - Reviewed PM-style aggregate Explore with `count`, `count_distinct`, `sum`,
   `avg`, categorical dimensions, fixed time buckets, typed filters, bounded
-  top-N, optional one-hop proven many-to-one relationships, cohort suppression,
-  and durable extraction/differencing budgets.
+  top-N, up to three reviewed relationship paths of at most two proven
+  many-to-one links each, cohort suppression, and durable
+  extraction/differencing budgets.
+- Demand-driven operator review for an exact catalog-proven relationship,
+  including an explicit missing-row choice for nullable links. The model cannot
+  activate a relationship, and every participating relation receives trusted
+  tenant/principal scope.
 - Protect This Query to public DSL, canonical JSON, tests, and a disabled named
   capability that survives Explore shutdown after exact-digest activation.
 - Generation-lock drift detection for generated authority. Manually authored
@@ -75,6 +89,13 @@ or claim an enterprise SLA.
   and scoped tamper-evident JSON/Markdown/PDF ledger reports.
 - Off-by-default graduated-trust recommendations that require verified operator
   review and explicit artifact export without activation.
+- Default-off operator-supervised apply for eligible exact-row direct
+  `INSERT`/`UPDATE`, requiring both public contract permission and an
+  independent deployment allowlist for the exact active digest. It reuses
+  guarded apply and preserves legacy `AUTO APPROVE` as manual-apply.
+- Durable redacted human-attention events, a coalesced Workbench inbox,
+  no-ID CLI inspection, optional JSONL output, and signed generic HTTPS
+  webhooks with quiet routing, budgets, digests, and safe delivery replay.
 
 ## Runtime Contract
 
@@ -105,16 +126,25 @@ truth for the model-facing tools.
 - Inferred compensation for app-owned handlers or external effects.
 - General restoration of hard-deleted rows, cascades, or trigger side effects.
 - Model-callable approval or commit tools.
+- Model-callable worker, notification-routing, acknowledgement, recovery, or
+  reconciliation controls.
 - Generic MCP firewall behavior.
 - Prompt-injection prevention.
 - Unbounded/high-throughput or multi-region ledger scale.
 - Managed fleet, SLA, compliance certification, or production support guarantee.
 - Production, shared HTTP, remote, or non-loopback Scoped Explore.
+- Production, shared HTTP, remote, or non-loopback Workbench Ask; model-facing
+  provider configuration; Synapsor-relayed provider traffic; durable chat
+  history; automatic provider retries; exact monetary spend enforcement; or
+  universal compatibility with OpenAI-compatible servers.
+- Automatic supervised execution for hard DELETE, reversible changes, bounded
+  sets, app-owned/external effects, or writes without deterministic conflict,
+  deduplication, freshness, and receipt authority.
 - Arbitrary aggregate expressions, dynamic identifiers, unrestricted joins,
   many-to-many joins, formulas, window functions, subqueries, `HAVING`,
-  user-defined functions, or a statistical privacy guarantee. Version 1.6
-  supports only the explicitly reviewed authoring cube described above and
-  fixed protected named capabilities produced from it.
+  user-defined functions, or a statistical privacy guarantee. Runner supports
+  only the explicitly reviewed authoring cube described above and fixed
+  protected named capabilities produced from it.
 - Automatic policy widening or activation from graduated-trust metrics.
 - Immutable/WORM compliance storage from the local report exporter.
 
@@ -149,6 +179,12 @@ jobs. Mixed-minor v3/v4 rolling compensation is not claimed.
 See [Running A Small Runner
 Fleet](running-a-runner-fleet.md).
 
+Workbench Ask token accounting uses provider-reported usage. A provider that
+omits or misreports usage cannot provide exact token or monetary enforcement.
+Runner still enforces request/response, tool-result, iteration, history, and
+wall-clock bounds. A provider outage does not disable the no-model composer or
+external MCP path. See [Workbench Ask With Your Model](workbench-ask.md).
+
 Use this wording:
 
 ```text

package/docs/local-mode.md

@@ -44,13 +44,13 @@ when you do not want to change your host Node version.
 Create a starter config without putting credentials in the file:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init --engine postgres --mode review
+npx -y @synapsor/runner init --engine postgres --mode review
 ```
 
 For MySQL:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init --engine mysql --mode review --output synapsor.mysql.runner.json
+npx -y @synapsor/runner init --engine mysql --mode review --output synapsor.mysql.runner.json
 ```
 
 The generated config uses environment-variable names for read/write URLs and trusted context. Edit the table, column, and capability names before serving tools.
@@ -63,8 +63,8 @@ persisted into proposals, evidence, query audit, runner state, or replay.
 For a reviewed own-database setup generated from explicit selections, use:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init --spec onboarding-selection.json --non-interactive
-npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json
+npx -y @synapsor/runner init --spec onboarding-selection.json --non-interactive
+npx -y @synapsor/runner doctor --config synapsor.runner.json
 ```
 
 `doctor --config` checks config validation, required environment variables,
@@ -76,7 +76,7 @@ and the semantic MCP tool boundary without printing credential values.
 Use stdio for local MCP clients that launch Synapsor Runner:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner mcp serve \
+npx -y @synapsor/runner mcp serve \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
 ```
@@ -87,7 +87,7 @@ MCP client:
 ```bash
 export SYNAPSOR_RUNNER_HTTP_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))')"
 
-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
@@ -131,19 +131,19 @@ If neither is set, the CLI uses:
 List proposals:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner proposals list --store ./.synapsor/local.db
+npx -y @synapsor/runner proposals list --store ./.synapsor/local.db
 ```
 
 Show a proposal:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner proposals show wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner proposals show wrp_123 --store ./.synapsor/local.db
 ```
 
 Check a freshness-enabled proposal without copying its id:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner proposals check-freshness latest \
+npx -y @synapsor/runner proposals check-freshness latest \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db
 ```
@@ -151,13 +151,19 @@ npx -y -p @synapsor/runner synapsor-runner proposals check-freshness latest \
 Approve:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner proposals approve wrp_123 \
+npx -y @synapsor/runner proposals approve wrp_123 \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --actor local_reviewer \
   --yes
 ```
 
+The `--actor` example is the unverified local-development path. Shared and
+production operation should require `signed_key` or `jwt_oidc`, resolve the
+contract's exact role from verified identity, and authorize apply separately.
+See [Approval Roles And Verified Operator
+Identity](approval-roles-and-operator-identity.md).
+
 Before approval, the CLI prints the reviewer-critical proposal details: trusted principal, tenant, target row, primary key, required role, proposal hash/version, allowed columns, conflict guard, evidence bundle/query fingerprint, writeback boundary, source mutation state, and exact before/after diff. Interactive approval still requires typing `yes`; noninteractive scripts must pass `--yes`.
 
 When `proposal_freshness` is configured for that capability, approval also
@@ -171,7 +177,7 @@ revalidates again because source data can change after approval. See
 Create a guarded writeback job from an approved proposal:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner proposals writeback-job wrp_123 \
+npx -y @synapsor/runner proposals writeback-job wrp_123 \
   --store ./.synapsor/local.db \
   --project local \
   --runner local_runner \
@@ -183,7 +189,7 @@ The generated job uses the public `synapsor.writeback-job.v1` protocol and can b
 ```bash
 export SYNAPSOR_DATABASE_WRITE_URL="postgresql://writer:<password>@localhost:5432/app"
 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
 ```
 
 When `--config` is passed, direct SQL writeback reads the writer connection from
@@ -195,7 +201,7 @@ Passing `--store` records the terminal `synapsor.execution-receipt.v1` locally.
 Reject:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner proposals reject wrp_123 \
+npx -y @synapsor/runner proposals reject wrp_123 \
   --store ./.synapsor/local.db \
   --reason "policy evidence is incomplete" \
   --yes
@@ -216,7 +222,7 @@ pilot, use [Shadow Studies](shadow-studies.md).
 Start a localhost-only review UI:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner ui --config synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner ui --config synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 The UI shows setup summary, semantic tools, proposal states, exact diffs,
@@ -234,20 +240,20 @@ tools, MCP commit tools, or controls that widen configured tables/columns.
 Show replay:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner replay show wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner replay show --proposal wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner replay show --replay replay_wrp_123 --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner replay show --evidence ev_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner replay show wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner replay show --proposal wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner replay show --replay replay_wrp_123 --store ./.synapsor/local.db
+npx -y @synapsor/runner replay show --evidence ev_123 --store ./.synapsor/local.db
 ```
 
 Export replay:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner replay export wrp_123 \
+npx -y @synapsor/runner replay export wrp_123 \
   --store ./.synapsor/local.db \
   --output replay.json
 
-npx -y -p @synapsor/runner synapsor-runner replay export --proposal wrp_123 \
+npx -y @synapsor/runner replay export --proposal wrp_123 \
   --format markdown \
   --store ./.synapsor/local.db \
   --output replay.md
@@ -301,6 +307,8 @@ or prune it without touching your source Postgres/MySQL database:
 ```bash
 synapsor-runner store stats --store ./.synapsor/local.db
 synapsor-runner events tail --store ./.synapsor/local.db
+synapsor-runner attention show --store ./.synapsor/local.db
+synapsor-runner notifications status --store ./.synapsor/local.db
 synapsor-runner events webhook --url http://127.0.0.1:8788/synapsor/events --kind proposal_created --store ./.synapsor/local.db
 synapsor-runner store vacuum --store ./.synapsor/local.db
 synapsor-runner store prune --store ./.synapsor/local.db --older-than 30d --dry-run
@@ -316,8 +324,14 @@ running local store.
 
 `events webhook` pushes the same local lifecycle events to a local/dev/staging
 HTTP endpoint, one event envelope per POST. Use it for a review UI, Slack bridge,
-or app-local notification path when polling is awkward. It is not a hosted
-central ledger and does not expose database credentials.
+or app-local compatibility path when polling is awkward. It is not the
+production human-attention dispatcher.
+
+For durable coalesced incidents, quiet defaults, budgets/digests, signed HTTPS
+delivery, replay protection, sink health, and the no-ID Workbench inbox, use
+`attention` and `notifications`. See [Human Attention And
+Notifications](human-attention-notifications.md). Neither notification path
+becomes approval or apply authority.
 
 `store prune` defaults to dry-run. `store reset` requires `--yes` and removes
 only the local SQLite ledger files. MCP server modes write a small active-store