@synapsor/runner 1.6.3 → 1.6.4

package/docs/reversible-change-sets.md

@@ -1,6 +1,6 @@
 # Reviewed Reversible Change Sets
 
-Synapsor Runner 1.4 can capture a bounded inverse for an opt-in direct database
+Synapsor Runner can capture a bounded inverse for an opt-in direct database
 write. This is **reviewed compensation**, not rollback or database time travel.
 
 The operator flow is deliberately two separate approval loops:

package/docs/reviewed-database-views.md

@@ -0,0 +1,132 @@
+# Reviewed Database Views For Derived Measures
+
+Scoped Explore deliberately has no formula or expression language. The model
+cannot invent ratios, arithmetic, functions, subqueries, or joins. When a
+useful measure needs reviewed database logic, put that logic in a
+database-owned view and expose only the resulting typed column through a named
+Synapsor capability.
+
+The authority split is:
+
+```text
+Database owner reviews formula, joins, cardinality, and base-table scope
+  -> view publishes a small typed row shape
+  -> contract author reviews the view columns and fixed predicate
+  -> Runner applies trusted scope and the named aggregate
+  -> model receives one scalar, never SQL or member rows
+```
+
+This is an explicit escape hatch, not automatic generation. Auto Boundary
+blocks a view whose row identity cannot be proven from catalog metadata. Review
+the view definition, scope, uniqueness, and grants before hand-authoring a
+capability.
+
+## PostgreSQL Hardened Pattern
+
+Use a `security_invoker` view so PostgreSQL checks permissions and row-level
+security (RLS) as the Runner read role, not as the view owner. A
+`security_barrier` also prevents unsafe predicate movement across the view
+boundary.
+
+The retail clean-room fixture defines this reviewed ratio:
+
+```sql
+CREATE VIEW public.reviewed_order_performance
+WITH (security_barrier = true, security_invoker = true) AS
+SELECT
+  orders.id AS order_id,
+  orders.merchant_id,
+  orders.assigned_manager_id,
+  orders.region_id,
+  ROUND(
+    (orders.net_revenue_cents::numeric /
+      NULLIF(orders.gross_revenue_cents, 0)) * 10000
+  )::integer AS net_revenue_retention_basis_points
+FROM public.orders;
+```
+
+The formula is fixed in a reviewed database migration. The model sees only
+`net_revenue_retention_basis_points`. It cannot change the numerator,
+denominator, scale, or source relation.
+
+For `database_scope.mode = "postgres_rls"`, Runner accepts a read view only
+when all of these checks pass:
+
+- the target is a normal PostgreSQL view used for `SELECT`;
+- both `security_invoker=true` and `security_barrier=true` are present;
+- the Runner role is not the view owner, a superuser, or `BYPASSRLS`;
+- every referenced table or nested view can be resolved from the catalog;
+- every referenced base table independently passes the existing FORCE RLS,
+  role, policy-operation, and trusted-setting checks;
+- every nested view passes the same view checks.
+
+An ordinary owner-rights view, an unverifiable dependency, a missing RLS
+setting, or any non-read operation fails closed before MCP serving.
+
+## Named Aggregate
+
+The public DSL fixes the trusted scope, formula output, region, aggregate, and
+minimum cohort:
+
+```sql
+CREATE AGENT CONTEXT retail_analytics_context
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY retail.average_net_revenue_retention_pacific
+  DESCRIPTION 'Return the privacy-suppressed average net-to-gross revenue retention rate for Pacific orders assigned to the trusted manager.'
+  RETURNS HINT 'Returns one scalar average in basis points or a suppression result; never order rows.'
+  USING CONTEXT retail_analytics_context
+  SOURCE retail_postgres
+  ON public.reviewed_order_performance
+  PRIMARY KEY order_id
+  TENANT KEY merchant_id
+  PRINCIPAL SCOPE KEY assigned_manager_id
+  AGGREGATE READ AVG net_revenue_retention_basis_points
+  SELECT WHERE region_id = 'region-pacific'
+  MIN GROUP SIZE 5
+  REQUIRE EVIDENCE
+END
+```
+
+Validate, compile, validate the Runner config, and serve:
+
+```bash
+npx -y @synapsor/runner dsl validate \
+  ./average-retained-revenue.synapsor.sql --strict
+
+npx -y @synapsor/runner dsl compile \
+  ./average-retained-revenue.synapsor.sql \
+  --out ./average-retained-revenue.contract.json \
+  --strict
+
+npx -y @synapsor/runner config validate \
+  --config ./synapsor.runner.json
+
+npx -y @synapsor/runner mcp serve \
+  --config ./synapsor.runner.json
+```
+
+The runnable packaged recipe is under
+`examples/retail-clean-room/view-recipe/`. Its clean-room gate proves that the
+result is exactly `9000` basis points for the trusted fixture scope, includes
+no member rows, and does not change the source database.
+
+## Review Checklist
+
+1. Prove the view has one intended row per counted entity.
+2. Prove joins cannot multiply rows or silently double-count values.
+3. Apply tenant and, where required, principal scope to every base relation.
+4. Keep sensitive source columns out of the view output.
+5. Grant the Runner role only `SELECT` on the view and required base objects.
+6. Test same-tenant other-principal and cross-tenant denial.
+7. Test zero denominators, nulls, rounding, and numeric overflow.
+8. Keep cohort suppression and result limits in the Synapsor capability.
+9. Treat a changed view definition as reviewed authority drift.
+
+For complex or ambiguous calculations, keep the capability disabled until the
+database migration, contract, and expected results have all been reviewed
+together.

package/docs/reviewed-relationships.md

@@ -0,0 +1,245 @@
+# Reviewed Relationship Paths
+
+Synapsor Runner can answer bounded aggregate questions across related tables
+without exposing a general join planner or SQL. The relationship is authority:
+Runner proposes it from database catalog evidence, a human reviews it, and the
+activated boundary fixes its exact path and semantics.
+
+This feature is part of local, development/staging-only Scoped Explore.
+Production receives only named capabilities created through Protect This Query.
+
+## The Safety Rule
+
+A model may select an already activated relationship **by name**. It cannot
+provide a table name, join key, join type, relationship path, or SQL fragment.
+
+Runner accepts only:
+
+- one to three relationship paths in a protected capability;
+- one or two links per path;
+- inspected foreign-key links whose target key is unique;
+- `many_to_one` cardinality with `max_fan_out: 1`;
+- trusted tenant and, where configured, principal scope on every relation;
+- an explicit human choice for missing related rows.
+
+Runner refuses:
+
+- one-to-many and many-to-many paths;
+- relationships inferred only from similar column names;
+- ambiguous or unproven cardinality;
+- more than two links in one path;
+- a plan using more than three reviewed paths;
+- a relationship whose catalog proof or generation lock is stale;
+- a related table whose trusted scope cannot be enforced;
+- formulas, derived measures, free-form joins, and model-selected identifiers.
+
+These limits permit reviewed star-style analysis. For example, a sales fact can
+group by an activated store path and an activated category path without
+multiplying the counted sales rows.
+
+## Why Fan-Out Matters
+
+Suppose one `sales_facts` row points to one store. Joining the store cannot
+create more sales rows, so the relationship is many-to-one and has a maximum
+fan-out of one.
+
+By contrast, joining a sale to all of its line items can turn one sale into
+several rows. A naive `SUM(sales_facts.amount_cents)` would then overstate
+revenue. Runner refuses that one-to-many path instead of silently returning a
+plausible but wrong number.
+
+## Demand-Driven Review
+
+Auto Boundary may discover more proven relationships than a developer needs.
+They are not all activated automatically.
+
+The intended flow is:
+
+1. Activate the small starter boundary.
+2. Ask a bounded aggregate question.
+3. If the question needs an inactive but catalog-proven path, Runner refuses the
+   plan and identifies the exact path and proof.
+4. Workbench shows that one relationship for operator review.
+5. The operator chooses missing-row semantics when required and activates the
+   exact new boundary digest.
+6. Retry the original question.
+
+The model cannot trigger step 5. Adding the path creates new authority, so it is
+an operator-plane action with a new digest. Existing unrelated confirmations
+remain valid; only dependent review state is invalidated.
+
+## Nullable Links
+
+An optional foreign key requires an explicit business decision:
+
+- `UNMATCHED EXCLUDE`: omit a counted row when its related record is missing;
+- `UNMATCHED KEEP NULL`: keep the counted row and return an empty/null group
+  value for the missing relationship.
+
+This is not cosmetic. The choice can change totals and cohort sizes, so Runner
+does not silently choose it. The decision is stored in the canonical contract
+and bound into its digest.
+
+## DSL Syntax
+
+The SQL-like Domain-Specific Language (DSL) supports a legacy one-hop form and
+the additive path form. Existing legacy contracts retain their canonical bytes
+and digest.
+
+Legacy one-hop form:
+
+```sql
+PROTECTED RELATIONSHIP store
+  ON store_id
+  REFERENCES public.stores.id
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+```
+
+Reviewed path form:
+
+```sql
+PROTECTED RELATIONSHIP store LINK 1
+  ON store_id
+  REFERENCES public.stores.id
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  UNMATCHED EXCLUDE
+
+PROTECTED RELATIONSHIP category LINK 1
+  ON product_id
+  REFERENCES public.products.id
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  UNMATCHED KEEP NULL
+
+PROTECTED RELATIONSHIP category LINK 2
+  ON category_id
+  REFERENCES public.categories.id
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  UNMATCHED EXCLUDE
+```
+
+In that example:
+
+- `store` and `category` are user-defined path names;
+- `LINK 1` and `LINK 2` are DSL keywords and ordered link numbers;
+- `store_id`, `product_id`, and `category_id` are inspected local keys;
+- `public.stores.id`, `public.products.id`, and `public.categories.id` are
+  fixed reviewed targets;
+- `PRIMARY KEY`, `TENANT KEY`, `UNMATCHED EXCLUDE`, and
+  `UNMATCHED KEEP NULL` are DSL syntax;
+- the two `category` declarations form one depth-two path.
+
+Link declarations for one path must be contiguous and ordered. A protected read
+cannot mix the legacy form with the path form.
+
+## Canonical Contract
+
+The path form compiles to public, language-neutral JSON:
+
+```json
+{
+  "protected_read": {
+    "mode": "aggregate",
+    "relationships": [
+      {
+        "name": "category",
+        "links": [
+          {
+            "local_key": "product_id",
+            "schema": "public",
+            "table": "products",
+            "target_key": "id",
+            "primary_key": "id",
+            "tenant_key": "tenant_id",
+            "cardinality": "many_to_one",
+            "max_fan_out": 1,
+            "unmatched_rows": "keep_null"
+          },
+          {
+            "local_key": "category_id",
+            "schema": "public",
+            "table": "categories",
+            "target_key": "id",
+            "primary_key": "id",
+            "tenant_key": "tenant_id",
+            "cardinality": "many_to_one",
+            "max_fan_out": 1,
+            "unmatched_rows": "exclude"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Measures, dimensions, time buckets, and fixed predicates refer to the reviewed
+path name. The canonical Spec is not a generic SQL or analytics Abstract Syntax
+Tree (AST); it represents fixed reviewed authority.
+
+## Scope And Privacy
+
+For every participating relation, Runner injects trusted tenant and configured
+principal predicates outside model arguments. Scope on only the starting table
+is insufficient.
+
+Aggregate privacy controls continue to apply after relationships are added:
+
+- minimum cohort suppression;
+- maximum groups and response size;
+- query, rate, extraction, and differencing budgets;
+- fixed reviewed dimensions and measures;
+- no pagination that bypasses the group bound.
+
+Adding dimensions can make cohorts smaller, so suppression is evaluated on the
+final grouped result. A relationship does not weaken kept-out fields: kept-out
+fields cannot be selected, filtered, grouped, sorted, joined, or counted
+distinctly.
+
+## Protect For Production
+
+Protect This Query freezes the exact reviewed paths, measures, dimensions,
+filters, ordering, limits, scope, and privacy controls into a disabled named
+capability. A human activates its exact digest. Scoped Explore can then be
+disabled; the protected capability remains available.
+
+Production does not advertise broad Explore tools and does not permit the model
+to add relationship authority.
+
+## When A View Is Better
+
+Runner intentionally does not support:
+
+- arbitrary relationship graphs;
+- many-to-many analytics;
+- derived formulas such as `revenue / capacity`;
+- model-defined expressions;
+- general-purpose join planning.
+
+For those cases, create a database view that computes the reviewed business
+meaning, grant Runner's reader access only to the safe projected columns, and
+inspect the view as a new resource. See [Reviewed Database
+Views](reviewed-database-views.md).
+
+This keeps business formulas and complex joins under ordinary database and code
+review while preserving Synapsor's field, scope, budget, proposal, and audit
+boundary.
+
+## Verification
+
+The repository release gates exercise:
+
+```bash
+corepack pnpm test:reviewed-relationships
+corepack pnpm test:auto-boundary-explore:packed
+corepack pnpm test:clean-room:community-solar
+corepack pnpm test:clean-room:retail
+```
+
+The live PostgreSQL and MySQL relationship test proves direct star paths,
+depth-two paths, both nullable-link choices, demand-driven activation, drift
+refusal, per-relation tenant/principal scope, suppression, and rejection of a
+deliberately wrong fan-out relationship.

package/docs/rfcs/006-reviewed-reversible-change-sets.md

@@ -1,6 +1,6 @@
 # RFC 006: Reviewed Reversible Change Sets
 
-Status: implemented and verified for the prepared Runner 1.4 release line
+Status: implemented (originally verified for the Runner 1.4 release line)
 
 ## Problem
 

package/docs/runner-bundles.md

@@ -41,11 +41,11 @@ cd ./synapsor-runner-bundle
 cp .env.example .env
 set -a && . ./.env && set +a
 
-npx -y -p @synapsor/runner synapsor-runner contract validate ./synapsor.contract.json
-npx -y -p @synapsor/runner synapsor-runner config validate --config ./synapsor.runner.json
-npx -y -p @synapsor/runner synapsor-runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
-npx -y -p @synapsor/runner synapsor-runner cloud connect --config ./synapsor.cloud.json
-npx -y -p @synapsor/runner synapsor-runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner contract validate ./synapsor.contract.json
+npx -y @synapsor/runner config validate --config ./synapsor.runner.json
+npx -y @synapsor/runner tools preview --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner cloud connect --config ./synapsor.cloud.json
+npx -y @synapsor/runner mcp serve --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 For proposal contracts, run the trusted worker in a separate
@@ -53,14 +53,14 @@ operator-controlled terminal:
 
 ```bash
 set -a && . ./.env && set +a
-npx -y -p @synapsor/runner synapsor-runner start --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner start --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 After an MCP tool creates a local proposal, sync its reviewed diff and safe
 references to Cloud:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner cloud sync latest \
+npx -y @synapsor/runner cloud sync latest \
   --config ./synapsor.cloud.json \
   --store ./.synapsor/local.db
 ```

package/docs/schema-api-candidates.md

@@ -1,6 +1,6 @@
 # Reviewed Candidates From Prisma, Drizzle, And OpenAPI
 
-Runner 1.6.0 uses these same bounded static parsers as evidence in the
+Runner 1.6.4 uses these same bounded static parsers as evidence in the
 whole-application [Auto Boundary](auto-boundary-and-scoped-explore.md) flow.
 The database catalog remains authoritative for database structure; Prisma,
 Drizzle, OpenAPI, and existing Synapsor definitions contribute deterministic

package/docs/security-boundary.md

@@ -42,6 +42,36 @@ The model does not receive:
 - MCP endpoint tokens, JWTs, refresh tokens, client secrets, or TLS keys;
 - trusted tenant or principal authority as ordinary model arguments.
 
+## Optional Workbench model client
+
+Workbench Ask is a local client of that same reviewed surface, not another
+policy engine. It is available only from authenticated loopback Workbench in an
+explicit development/staging profile. Its provider may request only the exact
+active named capabilities plus valid local authoring tools. The request is
+dispatched through the official MCP SDK and the existing typed-plan/runtime
+validators; there is no parallel query or mutation executor.
+
+The operator chooses provider, model, endpoint, and credential source and
+acknowledges direct egress for the current authority digest. No model output can
+change those values. Provider credentials and bounded conversation state stay
+in local server memory and are not written to the project, ledger, browser
+storage, logs, evidence, receipts, or replay. Reviewed tool results may be sent
+directly to the provider after consent; Synapsor does not relay them.
+
+Official remote providers use fixed HTTPS origins. Custom remote endpoints
+require HTTPS; plaintext is restricted to loopback. Redirects are refused,
+resolved destinations are checked and pinned on every connection, and
+private/link-local/metadata/special remote addresses are blocked. Unknown
+tools, malformed arguments/responses, authority drift, oversized data, time or
+tool-loop exhaustion, and reported source mutation fail closed.
+
+Provider prose remains untrusted. A write tool can create only the normal inert
+proposal, and the Workbench directs the human to the separate operator path.
+Ask never receives activation, Protect, approval, apply, worker, notification,
+attention, or reconciliation tools. It is absent from production,
+unknown-profile, shared, remote, and non-loopback surfaces. See [Workbench Ask
+With Your Model](workbench-ask.md).
+
 ## Network transport and identity
 
 Local stdio is the preferred one-client path. The MCP client launches Runner and

package/docs/troubleshooting-first-run.md

@@ -3,26 +3,26 @@
 Run the friendly doctor first:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner doctor --first-run
+npx -y @synapsor/runner doctor --first-run
 ```
 
 Use JSON for automation:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner doctor --first-run --json
+npx -y @synapsor/runner doctor --first-run --json
 ```
 
 ## Guided Recovery Contract
 
-Runner 1.6.3 failures should tell you what failed, why the boundary stopped,
+Runner 1.6.4 failures should tell you what failed, why the boundary stopped,
 what state remains, and one next action. Do not delete the project or add
 `--force` merely to recover.
 
 | Failure | State preserved | One next action |
 | --- | --- | --- |
-| Database connection or metadata inspection failed | Existing project/review files and source rows | Fix the exported URL/network without printing the credential, then rerun `npx -y @synapsor/runner@latest start --from-env DATABASE_URL`. |
+| Database connection or metadata inspection failed | Existing project/review files and source rows | Fix the URL/network without printing the credential, then rerun `npx -y @synapsor/runner start`. |
 | Read role is writable, owner, superuser, `BYPASSRLS`, or unverifiable | Disabled metadata draft; no source-row Explore | Supply a verifiably SELECT-only non-owner staging role, then rerun the same `start` command. |
-| Schema or project choice is ambiguous | Existing files; no authority activation | Rerun with the exact reviewed schema, for example `npx -y @synapsor/runner@latest start --from-env DATABASE_URL --schema public`. |
+| Schema or project choice is ambiguous | Existing files; no authority activation | Rerun with the exact reviewed schema, for example `npx -y @synapsor/runner start --schema public`. |
 | Tenant or principal scope is unresolved | Conservative blocked resource decisions | Open the same Workbench URL and resolve the highlighted scope exception. |
 | Sensitive field remains unresolved | Field stays kept out; active tools unchanged | Open Workbench **Exceptions** and record one reviewed field decision. |
 | Row identifier is missing/composite/ambiguous | Resource remains blocked | Select a source-proven single-column primary/unique identity or keep the resource blocked. |
@@ -33,6 +33,9 @@ what state remains, and one next action. Do not delete the project or add
 | Config mode is missing/invalid | Config and source database are unchanged | Set `mode` to `read_only`, `shadow`, `review`, or `cloud`, then rerun `synapsor-runner config validate --json`. |
 | Config contains an unknown field | Config and source database are unchanged | Remove or correct the reported JSON path, then rerun `synapsor-runner config validate --json`. |
 | Workbench port is occupied | Review files, ledger, and source database | Rerun `synapsor-runner ui --open`; the default selects a free loopback port. |
+| Workbench Ask is missing | Reviewed project remains usable through no-model Workbench/CLI/MCP | Use authenticated loopback Workbench with an explicit development/staging profile and at least one active reviewed tool. |
+| Ask provider/key fails | Boundary, no-model composer, and external MCP remain usable | Check the exported key name, provider/model access, and local DNS/TLS; then retry without changing authority. |
+| Ask says authority changed | Previous consent is invalid; active reviewed tools remain unchanged | Inspect the new tool/digest summary and acknowledge direct egress again. |
 | Writeback setup fails | Config and reviewed plan; transactional setup rolls back | Rerun `synapsor-runner writeback setup --profile staging --json` and review the reported prerequisite. |
 | Writer role/setup URL is missing | No DDL or grant was applied | Rerun the preview with `--writer-role <role> --setup-url-env <ADMIN_URL_ENV>`. |
 | No supported write candidate exists | Read boundary remains active; no write authority | Use **Add a safe action** on a writable base table with a proven identity/version field, or retain read-only mode. |
@@ -49,9 +52,10 @@ outcome; inspect the durable receipt/reconciliation state rather than guessing.
 
 ## Fresh Start Did Not Enter Auto Boundary
 
-Auto Boundary is the default only for a fresh interactive `start --from-env`
-with no existing config, selector, answers file, machine-output flag, or other
-automation input. This preserves every established 1.x route.
+Auto Boundary is the default only for a fresh interactive `start` with no
+existing config, selector, answers file, machine-output flag, or other
+automation input. An exported `DATABASE_URL` is implied; explicit connection
+and schema flags still win. This preserves every established 1.x route.
 
 Check the generated state:
 
@@ -93,6 +97,42 @@ A write-capable, owner, superuser, `BYPASSRLS`, or unverifiable credential may
 still inspect metadata with a warning. It cannot enable source-row Explore.
 Use a dedicated staging reader instead of weakening this check.
 
+## Workbench Ask Is Missing Or Refused
+
+Ask is optional and follows a stricter local profile boundary. It appears only
+in authenticated loopback Workbench for explicit `development` or `staging`
+projects with at least one reviewed tool. Production, unknown, shared, remote,
+and non-loopback surfaces intentionally omit it.
+
+Normal Runner and MCP execution do not automatically source `.env`. Fresh
+interactive `start` may read a regular project `.env` only after explicit
+consent and keeps the selected database URL in that process. For the optional
+model provider, export the key in the same shell that launches Workbench, then
+select **Read an environment variable** and enter only the variable name. A
+session-only masked paste is also supported.
+
+Provider errors are redacted and do not disable the no-model composer:
+
+- `ASK_KEY_REQUIRED`: export the selected key or use the masked session paste;
+- `ASK_AUTHORITY_CHANGED`: review the current tools/digest and acknowledge
+  direct egress again;
+- `ASK_PROVIDER_UNAVAILABLE`: verify provider availability, key/model access,
+  and local DNS/TLS, then retry;
+- `ASK_PROVIDER_REDIRECT_REFUSED`: use the final fixed endpoint; Runner never
+  forwards credentials across redirects;
+- `ASK_PROVIDER_DESTINATION_REFUSED`: the host resolved to a private, special,
+  metadata, or otherwise disallowed remote address;
+- `ASK_REMOTE_HTTPS_REQUIRED`: remote custom endpoints require HTTPS; HTTP is
+  accepted only on loopback;
+- `ASK_TOOL_REQUIRED`: the provider answered from prose without using a
+  reviewed Synapsor tool;
+- `ASK_UNKNOWN_TOOL` or `ASK_OPERATOR_TOOL_REFUSED`: the provider requested
+  authority outside the displayed tool surface.
+
+Select **Clear** after a session to cancel active work and discard in-memory
+provider configuration/history. See [Workbench Ask With Your
+Model](workbench-ask.md).
+
 ## Cursor Has Production Tools Instead Of Authoring Tools
 
 Install the managed local authoring entry only after boundary activation:
@@ -327,13 +367,13 @@ Own-database MCP setup needs a reviewed config before serving tools.
 Fix:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner init --from-env DATABASE_URL --mode review --wizard
+npx -y @synapsor/runner init --from-env DATABASE_URL --mode review --wizard
 ```
 
 Or pass an example config:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner tools preview --config ./examples/mcp-postgres-billing/synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 ## SQLite Store Missing
@@ -379,7 +419,7 @@ Fix:
 
 ```bash
 export SYNAPSOR_DATABASE_READ_URL="<read-only-url>"
-npx -y -p @synapsor/runner synapsor-runner doctor --config synapsor.runner.json
+npx -y @synapsor/runner doctor --config synapsor.runner.json
 ```
 
 ## Read/Write Credential Split Failed
@@ -491,7 +531,7 @@ Fix:
 Regenerate the snippet:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner mcp config claude-desktop \
+npx -y @synapsor/runner mcp config claude-desktop \
   --absolute-paths \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db

package/docs/use-your-own-database.md

@@ -10,9 +10,11 @@ model.
 Short path:
 
 ```bash
-export DATABASE_URL="postgresql://readonly_user:password@host:5432/app?sslmode=require"
-npx -y -p @synapsor/runner synapsor-runner start --from-env DATABASE_URL --schema public
+npx -y @synapsor/runner start
 ```
 
-Runner stores environment-variable names in `synapsor.runner.json`, not database
-URLs. Keep credentials in your shell, process manager, or secret manager.
+Paste a read-only URL into the hidden prompt, explicitly approve a regular
+project `.env` file for this process, or export `DATABASE_URL`. PostgreSQL
+defaults to `public`; explicit `--from-env`, `--schema`, and `--project-root`
+flags remain available and always win. Runner stores environment-variable names
+in `synapsor.runner.json`, not database URLs.