typakon4 · typakon4 · Sep 25, 2026 · Sep 21, 2026 · Sep 21, 2026 · Sep 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -22,6 +22,8 @@ First public-release candidate. This version is prepared but has not been pushed
 - `jev_record_execution` and append-only JSONL routing/execution receipts joined by `correlation_id`.
 - Offline replay/evaluation without host execution calls.
 - Opt-in supervision judgments with deterministic host policy.
+- Opt-in, report-only `jev_model_route` with correlated execution outcomes and a local evidence report.
+- Hermes plugin integration with profile-scoped OpenRouter secret resolution, replay receipts, model-route correlation, and a local-agent handoff guide.
 - Opt-in deterministic context filtering (`shadow` and `conservative`).
 - Explicit capability discovery for skills, MCP, CLI, DSH, tools, subagents, and models.
 - Experimental, opt-in browser fast-path over host-supplied observations.

diff --git a/README.md b/README.md
@@ -5,13 +5,11 @@
 <h1 align="center">jev-layer</h1>
 
 <p align="center">
-  <strong>Portable System-1 decision layer for agent harnesses.</strong><br>
-  Host-owned routing, receipts, replay, and fail-open integrations.
+  <strong>Let an agent make a bounded choice without handing it control.</strong><br>
+  Jev recommends. Your harness still checks permissions and executes.
 </p>
 
-<p align="center">
-  Hermes · OMP · Codex · generic MCP
-</p>
+<p align="center">Hermes · OMP · Codex · generic MCP</p>
 
 <p align="center">
   <a href="https://github.com/typakon4/jev-layer/actions/workflows/ci.yml?query=branch%3Amain"><img alt="CI status" src="https://github.com/typakon4/jev-layer/actions/workflows/ci.yml/badge.svg?branch=main"></a>
@@ -22,110 +20,93 @@
 
 [English](README.md) · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
 
-jev-layer routes bounded choices and records evidence; the host keeps execution, permissions, approvals, retries, recovery, and final results.
-
-> Integrating jev-layer into a harness? Start with the [Agent implementation guide](docs/AGENT-IMPLEMENTATION.md), not this README alone.
-
-## Architecture
+**Install:** `npm install --global jev-layer`  ·  [Integrate a harness](docs/AGENT-IMPLEMENTATION.md) · [Security model](SECURITY.md)
 
-<p align="center">
-  <img src="docs/architecture.svg" alt="Architecture: agent harnesses send bounded requests to jev-layer; the host owns permissions and execution; receipts support replay." width="960">
-</p>
+## What changes
 
-Jev never executes a selected capability. A provider can be deterministic `demo`, OpenRouter Decisions, or TypeSafe; provider-backed tests are not required for normal CI.
+| Without Jev | With Jev |
+| --- | --- |
+| Your harness follows its existing path to choose a capability. | The harness can ask `jev_route` to choose from a bounded set it supplies. |
+| Your harness owns permissions, approvals, and execution. | Your harness still owns permissions, approvals, and execution. |
+| Execution results stay in the host's normal workflow. | The host can attach the result to the decision with `jev_record_execution` and replay cases offline. |
 
-## Quick Start
+Jev never executes a selected capability. If it is disabled, unavailable, invalid, or inconclusive, control returns to the host's normal path.
 
-Requirements: Node.js 20 or newer. There are no mandatory runtime dependencies.
+## Quick start
 
-Install the published CLI:
+Requires Node.js 20 or newer. There are no mandatory runtime dependencies.
 
 ```sh
 npm install --global jev-layer
-```
-
-Or use a local clone:
-
-```sh
-npm install
-npm link
 jev install --project /path/to/workspace
 jev add generic --project /path/to/workspace
 jev doctor --project /path/to/workspace
 ```
 
-`npm link` is local only. It does not publish the package. Use `node /path/to/jev-layer/bin/jev.mjs ...` instead if a global link is not wanted. The default `demo` provider is offline and deterministic.
-
-To call the stdio MCP server directly:
+The default `demo` provider is deterministic and works offline. To run the stdio MCP server directly:
 
 ```sh
 jev mcp
 ```
 
-To use a provider with credentials, keep keys outside the repository:
+## How it fits into a harness
 
-```sh
-export JEV_LAYER_PROVIDER=openrouter
-export OPENROUTER_API_KEY='provided-by-your-secret-store'
-jev doctor --project /path/to/workspace
-```
+<p align="center">
+  <img src="docs/architecture.svg" alt="Architecture: agent harnesses send bounded requests to jev-layer; the host owns permissions and execution; receipts support replay." width="960">
+</p>
 
-All three modes (`demo`, `openrouter`, and direct `typesafe`), their endpoints, and configuration precedence are documented in the [provider guide](docs/PROVIDERS.md).
+1. The host sends Jev a request and the candidate capabilities it already allows.
+2. Jev returns a bounded recommendation. The host checks it against its own registry and permissions.
+3. The host decides whether to execute, then can record what happened against the original `correlation_id`.
 
-## Core surfaces
+A provider can be deterministic `demo`, OpenRouter Decisions, or TypeSafe. Provider-backed tests are not required for normal CI; see the [provider guide](docs/PROVIDERS.md).
 
-- **Routing:** `jev_route` selects one capability from the host-supplied candidate set. Selection is advisory; the host validates the id and permissions.
-- **Receipts/replay:** `jev_record_execution` joins the host result to the original `correlation_id`. JSONL cases live in `.jev/replay/cases.jsonl` and can be evaluated offline with `npm run replay:evaluate`.
-- **Supervision:** `jev_supervise` returns bounded work-state judgments; deterministic host policy maps them to `continue`, `verify`, `retry`, `finish`, or `escalate`. Jev does not perform those actions.
+## What else it can do
+
+- **Supervision:** `jev_supervise` returns bounded work-state judgments. The host decides whether to continue, verify, retry, finish, or escalate.
+- **Model routing:** `jev_model_route` recommends one host-declared model profile for a future call. It is advisory only; the host measures outcomes before changing provider or model settings. Correlated receipts can be reviewed with `npm run model-route:report -- /path/to/cases.jsonl`.
+- **Shadow compaction:** `jev_shadow_compaction` produces report-only keep/drop candidates for host-supplied context. It does not summarize, mutate, or delete context, and keeps pinned evidence on provider failure.
 - **Context filtering:** optional deterministic `shadow` or `conservative` filtering reduces stale context without LLM summarization.
-- **Experimental browser fast-path:** `jev_browser_step` chooses one bounded action from a host observation. The host supplies observations, approval, native execution, and recovery. It is opt-in and does not start a browser worker.
-- **Fail-open:** disabled, unavailable, invalid, or inconclusive Jev calls return control to the host's normal path. Jev never widens permissions or guesses execution.
+- **Experimental browser fast-path:** `jev_browser_step` recommends one bounded action from a host observation. The host supplies approval, native execution, and recovery; Jev does not start a browser worker.
+- **Fail open:** optional Jev surfaces are disabled by default. Jev never widens permissions or guesses execution.
 
-All optional surfaces are disabled by default:
+Enable optional surfaces explicitly:
 
 ```sh
 JEV_BROWSER_FAST_PATH=1 jev mcp
 JEV_SUPERVISION=1 jev mcp
 JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json
 ```
 
-## Harness adapters
-
-Current examples live under `integrations/`:
-
-- `integrations/hermes/`
-- `integrations/omp/`
-- `integrations/codex/`
-- `integrations/template/`
-
-The release baseline records OMP `18.2.6`, Hermes `0.21.3` (`b675e6de`), and Codex CLI `0.155.1` observed in the preparation environment. This is a version/contract baseline, not a claim of full provider/model coverage; see [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
-
-Adapters are intentionally thin. They may call the CLI or stdio MCP, but the host must retain native capability lookup, permissions, approvals, execution, retries, recovery, and final output.
+For provider credentials, keep keys outside the repository:
 
-### Adding a new harness
+```sh
+export JEV_LAYER_PROVIDER=openrouter
+export OPENROUTER_API_KEY='provided-by-your-secret-store'
+jev doctor --project /path/to/workspace
+```
 
-The shortest PR path is:
+## Pick an integration
 
-1. copy `integrations/template/adapter.mjs`;
-2. add `integrations/<harness>/` and a secret-free config/example;
-3. call `jev_route`, preserve `correlation_id`, execute only through the host registry, then call `jev_record_execution`;
-4. add an offline smoke fixture for success, fail-open, approval denial, and execution receipt;
-5. document supported versions and run CI.
+Examples and adapters live under `integrations/`:
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the adapter contract and [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md) for compatibility rules.
+- Hermes: `integrations/hermes/` (see the [local-agent handoff guide](docs/HERMES-LOCAL-AGENT-HANDOFF.ru.md))
+- OMP: `integrations/omp/`
+- Codex: `integrations/codex/`
+- Another harness: start from `integrations/template/`
 
-## Browser status
+Adapters stay thin. The host retains native capability lookup, permissions, approvals, execution, retries, recovery, and final output. For the adapter contract, see [CONTRIBUTING.md](CONTRIBUTING.md). For compatibility rules, see [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md).
 
-Browser fast-path **reliability is validated against the current real-browser fixtures**, including action sequencing, visible-link navigation, native select execution, approval denial, and recovery. **Performance optimization remains experimental**. No browser speedup claim is made.
+The release baseline records OMP `18.2.6`, Hermes `0.21.3` (`b675e6de`), and Codex CLI `0.155.1` observed in the preparation environment. This is a version/contract baseline, not a claim of full provider/model coverage; see [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
 
-## Security and compatibility
+## Boundaries
 
-- MIT licensed; see [LICENSE](LICENSE).
-- jev-layer is not a security boundary. Host permissions and approvals are authoritative; see [SECURITY.md](SECURITY.md).
+- jev-layer is not a security boundary. Host permissions and approvals remain authoritative; see [SECURITY.md](SECURITY.md).
 - Schema, MCP tool, receipt, replay, and adapter contracts are currently version 1. Prefer additive changes; do not break v1 silently.
+- Browser fast-path reliability is validated against current real-browser fixtures. Performance optimization remains experimental; no browser speedup claim is made.
 - Do not commit credentials, logs containing secrets, `.env` files, or machine-specific paths.
 
-## Verification
+## Verify locally
 
 ```sh
 npm test
@@ -135,12 +116,8 @@ npm run clean-install-smoke
 npm pack --dry-run
 ```
 
-The GitHub Actions matrix runs these checks on Node.js 20, 22, and 24. Provider-backed tests require an explicitly configured secret-managed environment and are not part of ordinary PR CI.
+GitHub Actions runs these checks on Node.js 20, 22, and 24. Provider-backed tests require a secret-managed environment and are not part of ordinary PR CI.
 
-## Release documents
+## Project docs
 
-- [CONTRIBUTING.md](CONTRIBUTING.md)
-- [SECURITY.md](SECURITY.md)
-- [RELEASE.md](RELEASE.md)
-- [CHANGELOG.md](CHANGELOG.md)
-- [Agent implementation guide](docs/AGENT-IMPLEMENTATION.md)
+[Agent implementation guide](docs/AGENT-IMPLEMENTATION.md) · [Providers](docs/PROVIDERS.md) · [Compatibility](docs/COMPATIBILITY.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Release](RELEASE.md) · [Changelog](CHANGELOG.md)
diff --git a/README.ru.md b/README.ru.md
@@ -76,7 +76,9 @@ jev doctor --project /path/to/workspace
 
 - **Routing:** `jev_route` выбирает одну capability из набора, предоставленного host. Host повторно проверяет id и permissions.
 - **Receipts/replay:** `jev_record_execution` связывает результат host с исходным `correlation_id`. JSONL-файлы находятся в `.jev/replay/cases.jsonl` и проверяются офлайн через `npm run replay:evaluate`.
-- **Supervision:** `jev_supervise` возвращает ограниченные judgments о состоянии работы; детерминированная host policy преобразует их в `continue`, `verify`, `retry`, `finish` или `escalate`. Jev эти действия не выполняет.
+- **Supervision:** `jev_supervise` возвращает ограниченные judgments о состоянии работы; детерминированная host policy преобразует их в `continue`, `verify`, `retry`, `finish` или `escalate`. Receipt хранит детерминированный `evidence_state`: `present`, `missing` или `contradictory`. Противоречивые evidence не могут привести к `finish`. Jev эти действия не выполняет.
+- **Model routing:** `jev_model_route` возвращает одну рекомендацию из model profiles, которые объявил host, для следующего model call. Это только shadow: прежде чем менять provider/model setting, host обязан измерить outcome, retry, latency и cost. Решение связывается с последующим `jev_record_execution` по `correlation_id`; host записывает `result.model_route = { actual_model_id, retry_count, outcome }`, затем `npm run model-route:report -- /path/to/cases.jsonl` строит read-only evidence report.
+- **Shadow compaction:** `jev_shadow_compaction` делает пакетный консервативный report с keep/drop-кандидатами для context, который передал host. Он никогда не меняет, не суммаризирует и не удаляет context; path, error, command и requirement pin-ятся до provider review, а provider failure оставляет все остальные items.
 - **Context filtering:** опциональная детерминированная фильтрация `shadow` или `conservative` убирает устаревший context без LLM-суммаризации.
 - **Experimental browser fast-path:** `jev_browser_step` выбирает одно ограниченное действие из observation host. Host предоставляет observation, approval, native execution и recovery.
 - **Fail-open:** при отключённом, недоступном, ошибочном или неубедительном Jev вызове управление возвращается в обычный host path. Jev не расширяет permissions и не угадывает execution.
@@ -93,7 +95,7 @@ JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json
 
 Примеры находятся в `integrations/`:
 
-- `integrations/hermes/`
+- `integrations/hermes/` — для active plugin topology и safe change workflow см. [handoff локальному агенту (RU)](docs/HERMES-LOCAL-AGENT-HANDOFF.ru.md).
 - `integrations/omp/`
 - `integrations/codex/`
 - `integrations/template/`

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -76,7 +76,8 @@ jev doctor --project /path/to/workspace
 
 - **Routing：** `jev_route` 从 host 提供的候选集合中选择一个 capability。host 会再次验证 id 和权限。
 - **Receipts/replay：** `jev_record_execution` 使用原始 `correlation_id` 关联 host 结果。JSONL 位于 `.jev/replay/cases.jsonl`，可用 `npm run replay:evaluate` 离线评估。
-- **Supervision：** `jev_supervise` 返回有界的工作状态判断；确定性的 host policy 将其映射为 `continue`、`verify`、`retry`、`finish` 或 `escalate`。Jev 不执行这些动作。
+- **Supervision：** `jev_supervise` 返回有界的工作状态判断；确定性的 host policy 将其映射为 `continue`、`verify`、`retry`、`finish` 或 `escalate`。receipt 记录确定性的 `evidence_state`：`present`、`missing` 或 `contradictory`；矛盾证据不能导致 `finish`。Jev 不执行这些动作。
+- **Shadow compaction：** `jev_shadow_compaction` 为 host 提供的 context 生成批量、保守、只报告的 keep/drop 候选。它不会修改、总结或删除 context；path、error、command 和 requirement 在 provider review 前被保留，provider 失败时保留所有其他 items。
 - **Context filtering：** 可选的确定性 `shadow` 或 `conservative` 过滤器减少过期 context，不使用 LLM 摘要。
 - **Experimental browser fast-path：** `jev_browser_step` 根据 host observation 选择一个有界浏览器动作。observation、审批、原生执行和恢复都由 host 提供。
 - **Fail-open：** Jev 被禁用、不可用、出错或无法确定时，控制权返回 host 的正常路径。Jev 不扩大权限，也不猜测执行。