@synapsor/runner 1.6.3 → 1.6.5

package/docs/README.md

@@ -22,6 +22,9 @@ no-database demo, wire your database, then read deeper concepts.
   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.
 
@@ -58,6 +61,9 @@ no-database demo, wire your database, then read deeper concepts.
   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.
@@ -120,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.

package/docs/agent-guided-setup.md

@@ -52,7 +52,7 @@ Run:
 ```bash
 node --version
 test -n "${DATABASE_URL:-}"
-npx -y @synapsor/runner@latest --version
+npx -y @synapsor/runner --version
 ```
 
 Do not run `echo "$DATABASE_URL"` or otherwise reveal its value. Runner
@@ -77,7 +77,7 @@ it into chat, then ask me to continue.
 From the intended project directory, run:
 
 ```bash
-npx -y @synapsor/runner@latest start --from-env DATABASE_URL
+npx -y @synapsor/runner start --from-env DATABASE_URL
 ```
 
 For a fresh interactive project, Runner performs metadata-only inspection,
@@ -118,7 +118,7 @@ The coding agent may verify the active local surface without copying an opaque
 handle:
 
 ```bash
-npx -y @synapsor/runner@latest try call --list --format json
+npx -y @synapsor/runner try call --list --format json
 ```
 
 If no named capability is active yet, that is expected: a temporary local
@@ -134,14 +134,14 @@ for the user.
 After the human activates a protected named capability, run:
 
 ```bash
-npx -y @synapsor/runner@latest try call --list --format json
+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@latest try call <tool-name> --sample --json
+npx -y @synapsor/runner try call <tool-name> --sample --json
 ```
 
 Do not invent tenant or principal arguments. Trusted scope comes from the
@@ -161,7 +161,8 @@ Next: connect the same reviewed tool surface to your MCP client.
 Workbench displays ready-to-copy configurations for:
 
 - Cursor project MCP;
-- Claude-compatible local stdio MCP;
+- Claude Code project MCP and Claude-compatible local stdio MCP;
+- VS Code project MCP;
 - Codex;
 - generic stdio MCP.
 
@@ -171,17 +172,18 @@ authority surface.
 For a terminal-rendered generic configuration, run:
 
 ```bash
-npx -y @synapsor/runner@latest mcp config --absolute-paths
+synapsor-runner mcp config --absolute-paths
 ```
 
-Do not write into a client configuration without explicit user consent. Cursor
-has a separate consent-gated installer:
+Do not write into a client configuration without explicit user consent.
+Cursor, Claude Code, and VS Code have consent-gated project installers:
 
 ```bash
-npx -y @synapsor/runner@latest mcp install cursor --project --dry-run
+synapsor-runner mcp install claude-code --project --dry-run
 ```
 
-Show the dry-run result first. Installation remains a human choice.
+Use `cursor` or `vscode` instead when that is the selected client. Show the
+dry-run result first. Installation remains a human choice.
 
 ## Guided Write Action
 

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

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

@@ -1,6 +1,6 @@
 # Auto Boundary, Scoped Explore, And Protect
 
-Runner 1.6.3 provides a deterministic, resumable authoring path for a real
+Runner 1.6.4 provides a deterministic, resumable authoring path for a real
 application:
 
 ```text
@@ -26,7 +26,14 @@ controls underneath Runner. PostgreSQL deployments should use forced row-level
 security (RLS) where possible; MySQL deployments should use restricted views or
 tenant-bound credentials.
 
-Export the connection and trusted context in the process that Cursor will use:
+The shortest first run accepts a hidden URL paste or asks before reading
+`DATABASE_URL` from a regular project `.env`:
+
+```bash
+npx -y @synapsor/runner start
+```
+
+For an explicit environment-driven staging run:
 
 ```bash
 export DATABASE_URL='postgresql://runner_reader:REPLACE_ME@127.0.0.1:5432/app'
@@ -109,13 +116,19 @@ candidates start disabled. Auto Boundary never replaces an active contract.
 No source rows, credentials, tenant values, or principal values are written to
 these files.
 
+Workbench previews generated DSL with a local deterministic highlighter. It
+distinguishes DSL keywords from reviewer-defined names, strings, numbers,
+comments, and punctuation while preserving byte-identical plain/copy text.
+Rendering uses escaped DOM text and no external CDN; if highlighting fails, the
+same safe plain source remains visible.
+
 ## Review The Boundary
 
 The Workbench requires a human to narrow and confirm:
 
 - development or staging deployment profile;
 - trusted tenant and principal bindings supplied outside model arguments;
-- included resources and one-hop relationships;
+- included resources and catalog-proven relationship paths;
 - selectable fields;
 - filterable fields and allowed operators;
 - sortable and groupable fields;
@@ -163,23 +176,55 @@ dependencies. The packed FitFlow gate proves Workbench, CLI Try, and an
 official-SDK generic stdio client produce the same bounded result and denial
 behavior.
 
-## Add The Authoring Tools To Cursor
+## Optional Workbench Ask Client
+
+After the no-model composer succeeds, Workbench can optionally send a
+plain-language question to a developer-selected model provider. This adds a
+client, not authority:
+
+```text
+provider request
+  -> exact active Workbench tool registry
+  -> official MCP SDK
+  -> existing Scoped Explore/runtime validator
+  -> reviewed bounded result or refusal
+```
+
+While Explore is active, the provider sees only `app.describe_data` and
+`app.explore_data`. After Protect and Explore shutdown, it sees only activated
+named capabilities. It never receives Protect, activation, approval, apply,
+worker, notification, recovery, credential, or filesystem tools.
+
+Provider/model/origin and the exact authority digest require explicit
+direct-egress acknowledgement. Keys come from the local Runner process
+environment or a session-only masked paste; configuration and history remain
+in memory and are cleared on request or shutdown. Ask is restricted to secured
+loopback Workbench in development/staging and is absent from production and
+shared/remote surfaces.
+
+The no-model composer, CLI Try, and external MCP routes remain fully supported
+when no provider is configured or a provider is unavailable. See [Workbench
+Ask With Your Model](workbench-ask.md).
+
+## Add The Authoring Tools To A Project MCP Client
 
 After activation, let Runner manage only its own project entry:
 
 ```bash
-synapsor-runner mcp install cursor \
+synapsor-runner mcp install claude-code \
   --project \
   --authoring \
   --project-root . \
   --yes
 
-synapsor-runner mcp status cursor --project
+synapsor-runner mcp status claude-code --project
 ```
 
-The Cursor config contains command paths and package identity, not database
-URLs, credential values, tenant values, or principal values. Authoring mode
-uses local stdio and advertises exactly:
+Use `cursor` or `vscode` instead of `claude-code` for those clients. Runner
+manages `.cursor/mcp.json`, `.mcp.json`, or `.vscode/mcp.json` and preserves
+unrelated entries. The client config contains command paths and package
+identity, not database URLs, credential values, tenant values, or principal
+values. Authoring mode uses local stdio and advertises exactly:
 
 ```text
 app.describe_data
@@ -219,8 +264,9 @@ analytics database tool. It supports:
 - bounded top-N results;
 - at most two reviewed time ranges;
 - one resource by default;
-- at most one inspected, reviewed many-to-one foreign-key path with maximum
-  fan-out one.
+- up to three activated relationship paths in one plan;
+- one or two inspected, reviewed many-to-one foreign-key links per path, each
+  with maximum fan-out one.
 
 It does not support arbitrary `DISTINCT`, `HAVING`, formulas, window functions,
 unions, nested queries, many-to-many joins, system catalogs, user-defined
@@ -228,6 +274,14 @@ functions, or a general join planner. Scope is enforced independently on every
 participating relation. Runner refuses a plan when cardinality, fan-out,
 counted entity, or scope cannot be proven.
 
+Auto Boundary does not activate every discovered path. When a useful question
+needs one inactive but catalog-proven path, Runner refuses the plan and stages
+that exact path for operator review. Workbench shows the foreign-key proof and,
+for optional links, requires an explicit choice between excluding the unmatched
+counted row and keeping it with an empty group value. Activating the new exact
+digest is an operator-plane action; the model cannot perform it. See
+[Reviewed Relationship Paths](reviewed-relationships.md).
+
 Before returning groups, Runner enforces the reviewed minimum cohort size.
 Small groups are suppressed and revealing totals are withheld. Durable
 per-session extraction and differencing budgets block repeated slightly
@@ -280,7 +334,7 @@ handles.
 
 Choose the useful query in Workbench. Protect freezes:
 
-- resources and reviewed relationship path;
+- resources and reviewed relationship paths;
 - counted entity, measures, dimensions, and bucket structure;
 - filters, ordering, top-N, and comparison shape;
 - tenant/principal as trusted bindings;
@@ -306,16 +360,18 @@ join-safety, deny, drift, and boundary tests. It becomes active only after a
 human reviews and confirms its exact contract digest outside MCP.
 
 When activation disables temporary Explore, the named capability remains
-available. Update Cursor from authoring mode to the production config:
+available. Update the selected project client from authoring mode to the
+production config:
 
 ```bash
-synapsor-runner mcp install cursor \
+synapsor-runner mcp install claude-code \
   --project \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
   --yes
 ```
 
+Again, substitute `cursor` or `vscode` for the selected client.
 Production then advertises only reviewed named capabilities. It does not
 advertise `app.explore_data`.
 

package/docs/capability-authoring.md

@@ -406,8 +406,8 @@ surface.
 ### Optional Live Freshness
 
 The proposal's exact `conflict_guard` already protects its target at apply.
-Runner 1.6.1 can additionally recheck that target before local approval and can
-bind explicitly reviewed supporting rows to both approval and apply.
+Runner can additionally recheck that target before local approval and bind
+explicitly reviewed supporting rows to both approval and apply.
 
 This is deployment wiring, not DSL or canonical contract syntax:
 

package/docs/client-recipes.md

@@ -33,7 +33,7 @@ Run from the Runner repository root after supplying your own environment-bound
 staging credentials and trusted scope:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner tools preview \
+npx -y @synapsor/runner tools preview \
   --config ./examples/support-plan-credit/synapsor.runner.json \
   --store ./tmp/support-plan-credit/local.db
 ```
@@ -89,17 +89,30 @@ list. Then ask for the shared proposal call.
 
 ## Claude Code
 
-**Status:** configuration-tested with Claude Code 2.1.216 and
+**Status:** managed project configuration-tested with Claude Code 2.1.220 and
 protocol-tested; a manual model-driven call remains a release gate.
 
-Run the checked command from the repository root:
+Use Runner's owned project lifecycle:
 
 ```bash
-bash ./examples/support-plan-credit/mcp-client-examples/claude-code.sh
+synapsor-runner mcp install claude-code --project --dry-run \
+  --config ./examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner mcp install claude-code --project --yes \
+  --config ./examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner mcp status claude-code --project --check-launch
 ```
 
-Claude Code records project-scoped MCP configuration without embedding source
-credentials. It will print the exact proposal prompt after configuration.
+Runner merges only `mcpServers.synapsor` into the project `.mcp.json`, creates
+a backup, pins the exact Runner version, and never embeds source credentials.
+Restart or open a new Claude Code project session, approve the project server
+when prompted, and make the shared proposal call. Remove only Runner's intact
+entry with `synapsor-runner mcp uninstall claude-code --project --yes`.
+
+The older checked shell recipe remains available for users who intentionally
+prefer Claude Code's own configuration command:
+[`claude-code.sh`](../examples/support-plan-credit/mcp-client-examples/claude-code.sh).
 
 Official source checked 2026-07-20:
 [Claude Code MCP](https://code.claude.com/docs/en/mcp).
@@ -120,13 +133,29 @@ Official source checked 2026-07-20:
 
 ## VS Code
 
-**Status:** configuration-parsed and protocol-tested; manual VS Code UI
-behavior is not claimed.
+**Status:** managed project configuration-tested with VS Code 1.123.0 and
+protocol-tested; manual VS Code UI behavior is not claimed.
+
+Use Runner's owned project lifecycle:
+
+```bash
+synapsor-runner mcp install vscode --project --dry-run \
+  --config ./examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner mcp install vscode --project --yes \
+  --config ./examples/support-plan-credit/synapsor.runner.json \
+  --store ./tmp/support-plan-credit/local.db
+synapsor-runner mcp status vscode --project --check-launch
+```
+
+Runner merges only `servers.synapsor` into `.vscode/mcp.json`, preserves JSONC
+comments and trailing commas, creates a backup, and pins the exact Runner
+version. Reload the VS Code window, start the server, inspect the listed tools,
+and ask for the shared proposal call. Remove only Runner's intact entry with
+`synapsor-runner mcp uninstall vscode --project --yes`.
 
-Copy or merge
-[`vscode.mcp.json`](../examples/support-plan-credit/mcp-client-examples/vscode.mcp.json)
-into `.vscode/mcp.json`. Start the server from VS Code, inspect the listed
-tools, and ask for the shared proposal call.
+The checked standalone template remains available at
+[`vscode.mcp.json`](../examples/support-plan-credit/mcp-client-examples/vscode.mcp.json).
 
 Official source checked 2026-07-20:
 [VS Code MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers).

package/docs/cloud-mode.md

@@ -88,17 +88,17 @@ cp .env.example .env
 # Fill the placeholders in .env, including the one-time Runner token.
 set -a && . ./.env && set +a
 
-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 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
 ```
 
 Run the trusted worker in a second operator-controlled terminal:
 
 ```bash
 set -a && . ./.env && set +a
-npx -y -p @synapsor/runner synapsor-runner runner start --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner runner start --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 For deployment checks or an operator-controlled single claim cycle, use the
@@ -107,13 +107,13 @@ Cloud-approved job and still rechecks the local contract, proposal, tenant,
 version, bounds, and idempotency guards:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner runner start --once --config ./synapsor.runner.json --store ./.synapsor/local.db
+npx -y @synapsor/runner runner start --once --config ./synapsor.runner.json --store ./.synapsor/local.db
 ```
 
 When a local proposal exists:
 
 ```bash
-npx -y -p @synapsor/runner synapsor-runner cloud sync latest --config ./synapsor.cloud.json --store ./.synapsor/local.db
+npx -y @synapsor/runner cloud sync latest --config ./synapsor.cloud.json --store ./.synapsor/local.db
 ```
 
 See [Cloud Push](cloud-push.md) and [Runner Bundles](runner-bundles.md).

package/docs/conformance.md

@@ -64,9 +64,12 @@ bound to a required trusted principal and AND-composed with tenant scope. Run
 same-tenant denial and shared-ledger evidence-handle isolation.
 The protected-read parity fixture proves digest- and generation-lock-bound
 named reads, fixed predicates, reviewed measures/dimensions/time buckets,
-one-hop many-to-one limits, suppression, response/query/extraction/
-differencing budgets, and rejection of raw SQL or model-controlled trusted
-scope. `corepack pnpm test:auto-boundary-explore:packed` proves the complete
+catalog-proven one-hop/star/depth-two many-to-one limits, suppression,
+response/query/extraction/differencing budgets, and rejection of raw SQL or
+model-controlled trusted scope. `corepack pnpm test:reviewed-relationships`
+proves direct and depth-two paths, per-relation scope, nullable semantics,
+demand-driven activation, and fan-out refusal on live PostgreSQL/MySQL.
+`corepack pnpm test:auto-boundary-explore:packed` proves the complete
 authoring-to-production behavior through packed public artifacts.
 
 Additional 0.1 parity coverage currently lives in tests and verification

package/docs/current-scope.md

@@ -2,7 +2,7 @@
 
 The canonical scope page is [Current Limitations](limitations.md).
 
-Current `1.6.3` 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
@@ -15,9 +15,17 @@ Current `1.6.3` 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
@@ -76,6 +84,9 @@ 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;

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-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

package/docs/fresh-developer-usability.md

@@ -1,6 +1,6 @@
 # Fresh-Developer Usability Protocol
 
-This is the owner-observation script for Runner 1.6.3. Give it to a
+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.
 
@@ -23,7 +23,7 @@ Measure product time separately from initial npm download. Start the timer
 after this succeeds:
 
 ```bash
-npx -y @synapsor/runner@latest --version
+npx -y @synapsor/runner --version
 ```
 
 ## Setup
@@ -33,8 +33,8 @@ Provide:
 - Node 22.13 or newer;
 - the packaged synthetic FitFlow fixture or equivalent disposable staging
   Postgres;
-- an exported `DATABASE_URL` using a SELECT-only, non-owner role;
-- exported synthetic `SYNAPSOR_TENANT_ID` and `SYNAPSOR_PRINCIPAL`;
+- 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.
 
@@ -59,7 +59,7 @@ Do not explain Synapsor’s architecture first.
 The participant should find and run:
 
 ```bash
-npx -y @synapsor/runner@latest start --from-env DATABASE_URL
+npx -y @synapsor/runner start
 ```
 
 No other shell command should be required through the first proposal. The
@@ -177,7 +177,7 @@ The automated packed FitFlow run records deterministic timing and interaction
 evidence in:
 
 ```text
-development/runner-1.6.3-fitflow-results.json
+development/runner-1.6.4-fitflow-results.json
 ```
 
 That evidence does not substitute for a first-time participant. Until a real