jev-layer 0.1.0 → 0.3.0

package/README.md

@@ -1,126 +1,125 @@
-# jev-layer
-
-[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
-
-Portable **System-1 decision layer for agent harnesses**. jev-layer routes bounded choices and records evidence; the host keeps execution, permissions, approvals, retries, recovery, and final results.
-
-Supported integration examples: **Hermes, OMP, Codex, and generic MCP-compatible agents**.
-
-## Architecture
-
-```text
-+----------------------+      bounded request       +----------------------+
-| Agent harness        | --------------------------> | jev-layer            |
-| Hermes / OMP /       |                            | route / supervise /  |
-| Codex / generic MCP  | <-------------------------- | context filter        |
-+----------+-----------+      decision + id          +----------+-----------+
-           |                                                  |
-           | host validates permissions/approval              |
-           v                                                  v
-+----------+-----------+      execution result       +----------+-----------+
-| Native host executor | --------------------------> | receipts + replay   |
-| owns all side effects|   jev_record_execution     | JSONL, correlation_id|
-+----------------------+                            +----------------------+
-```
-
-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.
-
-## Quick Start
-
-Requirements: Node.js 20 or newer. There are no mandatory runtime dependencies.
-
-```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:
-
-```sh
-jev mcp
-```
-
-To use a provider with credentials, keep keys outside the repository:
-
-```sh
-export JEV_LAYER_PROVIDER=openrouter
-export OPENROUTER_API_KEY='provided-by-your-secret-store'
-jev doctor --project /path/to/workspace
-```
-
-## Core surfaces
-
-- **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.
-- **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.
-
-All optional surfaces are disabled by default:
-
-```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.
-
-### Adding a new harness
-
-The shortest PR path is:
-
-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.
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the adapter contract and [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md) for compatibility rules.
-
-## Browser status
-
-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.
-
-## Security and compatibility
-
-- MIT licensed; see [LICENSE](LICENSE).
-- jev-layer is not a security boundary. Host permissions and approvals are 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.
-- Do not commit credentials, logs containing secrets, `.env` files, or machine-specific paths.
-
-## Verification
-
-```sh
-npm test
-npm run smoke
-npm run fail-open-smoke
-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.
-
-## Release documents
-
-- [CONTRIBUTING.md](CONTRIBUTING.md)
-- [SECURITY.md](SECURITY.md)
-- [RELEASE.md](RELEASE.md)
-- [CHANGELOG.md](CHANGELOG.md)
+<p align="center">
+  <img src="docs/jev-layer-banner.svg" alt="jev-layer — portable System-1 decisions for agent harnesses" width="960">
+</p>
+
+<h1 align="center">jev-layer</h1>
+
+<p align="center">
+  <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">
+  <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>
+  <a href="https://www.npmjs.com/package/jev-layer"><img alt="npm version" src="https://img.shields.io/npm/v/jev-layer?logo=npm&amp;label=npm"></a>
+  <a href="https://github.com/typakon4/jev-layer/releases"><img alt="latest GitHub release" src="https://img.shields.io/github/v/release/typakon4/jev-layer?display_name=tag&amp;sort=semver"></a>
+  <a href="https://github.com/typakon4/jev-layer/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/typakon4/jev-layer"></a>
+</p>
+
+[English](README.md) · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
+
+**Install:** `npm install --global jev-layer`  ·  [Integrate a harness](docs/AGENT-IMPLEMENTATION.md) · [Security model](SECURITY.md)
+
+## What changes
+
+| 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. |
+
+Jev never executes a selected capability. If it is disabled, unavailable, invalid, or inconclusive, control returns to the host's normal path.
+
+## Quick start
+
+Requires Node.js 20 or newer. There are no mandatory runtime dependencies.
+
+```sh
+npm install --global jev-layer
+jev install --project /path/to/workspace
+jev add generic --project /path/to/workspace
+jev doctor --project /path/to/workspace
+```
+
+The default `demo` provider is deterministic and works offline. To run the stdio MCP server directly:
+
+```sh
+jev mcp
+```
+
+## How it fits into a harness
+
+<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>
+
+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`.
+
+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).
+
+## 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` recommends one bounded action from a host observation. The host supplies approval, native execution, and recovery; Jev does not start a browser worker.
+- **Jev 1.14 vision and computer use:** TypeSafe and OpenRouter accept PNG/JPEG screenshots. Opt-in `jev_computer_step` recommends host-declared desktop actions, with visibility-gated Box grounding and host confirmation. The adapter handles each provider's image format. See the [image/computer contract](docs/AGENT-IMPLEMENTATION.md#vision-and-computer-use).
+- **Fail open:** optional Jev surfaces are disabled by default. Jev never widens permissions or guesses execution.
+
+Enable optional surfaces explicitly:
+
+```sh
+JEV_BROWSER_FAST_PATH=1 jev mcp
+JEV_LAYER_PROVIDER=openrouter JEV_COMPUTER_USE=1 jev mcp
+JEV_SUPERVISION=1 jev mcp
+JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json
+```
+
+For provider credentials, keep keys outside the repository:
+
+```sh
+export JEV_LAYER_PROVIDER=openrouter
+export OPENROUTER_API_KEY='provided-by-your-secret-store'
+jev doctor --project /path/to/workspace
+```
+
+## Pick an integration
+
+Examples and adapters live under `integrations/`:
+
+- 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/`
+
+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).
+
+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).
+
+## Boundaries
+
+- 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.
+
+## Verify locally
+
+```sh
+npm test
+npm run smoke
+npm run fail-open-smoke
+npm run clean-install-smoke
+npm pack --dry-run
+```
+
+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.
+
+## Project docs
+
+[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)

package/README.ru.md

@@ -1,117 +1,140 @@
-# jev-layer
-
-[English](README.md) | [Русский](README.ru.md) | [简体中文](README.zh-CN.md)
-
-Портируемый **System-1 слой принятия решений для agent harnesses**. jev-layer маршрутизирует ограниченные решения и сохраняет доказательства; harness сохраняет владение исполнением, разрешениями, подтверждениями, retry, восстановлением и итоговым результатом.
-
-Поддерживаются примеры интеграций **Hermes, OMP, Codex и generic MCP-compatible agents**.
-
-## Архитектура
-
-```text
-+----------------------+       ограниченный запрос  +----------------------+
-| Agent harness        | --------------------------> | jev-layer            |
-| Hermes / OMP /       |                            | route / supervise /  |
-| Codex / generic MCP  | <-------------------------- | context filter        |
-+----------+-----------+       решение + id          +----------+-----------+
-           |                                                  |
-           | host проверяет permissions/approval              |
-           v                                                  v
-+----------+-----------+       результат исполнения +----------+-----------+
-| Native host executor | --------------------------> | receipts + replay   |
-| владеет side effects |   jev_record_execution     | JSONL, correlation_id|
-+----------------------+                            +----------------------+
-```
-
-Jev не исполняет выбранную capability. Доступны детерминированный `demo`, OpenRouter Decisions и TypeSafe; тесты с provider credentials не требуются для обычного CI.
-
-## Быстрый старт
-
-Требуется Node.js 20 или новее. Обязательных runtime-зависимостей нет.
-
-```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` используется только локально и ничего не публикует. Вместо него можно запускать `node /path/to/jev-layer/bin/jev.mjs ...`. Provider по умолчанию — офлайн-детерминированный `demo`.
-
-Для stdio MCP:
-
-```sh
-jev mcp
-```
-
-Секреты должны находиться вне репозитория:
-
-```sh
-export JEV_LAYER_PROVIDER=openrouter
-export OPENROUTER_API_KEY='provided-by-your-secret-store'
-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 эти действия не выполняет.
-- **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.
-
-Опциональные поверхности по умолчанию отключены:
-
-```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
-
-Примеры находятся в `integrations/`:
-
-- `integrations/hermes/`
-- `integrations/omp/`
-- `integrations/codex/`
-- `integrations/template/`
-
-Для release baseline зафиксированы версии OMP `18.2.6`, Hermes `0.21.3` (`b675e6de`) и Codex CLI `0.155.1`, наблюдавшиеся в среде подготовки. Это базовая проверка версий и контрактов, а не полный набор provider/model tests; подробности — в [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
-
-### Добавление нового harness
-
-1. Скопируйте `integrations/template/adapter.mjs`.
-2. Добавьте `integrations/<harness>/` и secret-free config/example.
-3. Вызовите `jev_route`, сохраните `correlation_id`, исполняйте только через native registry host, затем вызовите `jev_record_execution`.
-4. Добавьте offline smoke fixture для успеха, fail-open, отказа в approval и execution receipt.
-5. Зафиксируйте поддерживаемые версии и пройдите CI.
-
-Подробности: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md).
-
-## Статус browser
-
-Надёжность browser fast-path **проверена на текущих real-browser fixtures**: sequencing, visible-link navigation, native select, approval denial и recovery. **Оптимизация производительности остаётся экспериментальной**. Заявлений об ускорении браузера нет.
-
-## Безопасность и совместимость
-
-- Лицензия MIT: [LICENSE](LICENSE).
-- jev-layer не является security boundary. Источник истины для permissions и approvals — host: [SECURITY.md](SECURITY.md).
-- MCP tools, routing decisions, receipts, replay cases и adapter contract сейчас имеют version 1. Изменения должны быть additive и не ломать v1 молча.
-- Не коммитьте credentials, секретные logs, `.env` или machine-specific paths.
-
-## Проверка
-
-```sh
-npm test
-npm run smoke
-npm run fail-open-smoke
-npm run clean-install-smoke
-npm pack --dry-run
-```
-
-GitHub Actions запускает эти проверки на Node.js 20, 22 и 24. Provider-backed тесты требуют отдельного secret-managed окружения и не входят в обычный PR CI.
-
-Документы: [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [RELEASE.md](RELEASE.md) · [CHANGELOG.md](CHANGELOG.md).
+<p align="center">
+  <img src="docs/jev-layer-banner.svg" alt="jev-layer — портируемый System-1 слой решений для agent harnesses" width="960">
+</p>
+
+<h1 align="center">jev-layer</h1>
+
+<p align="center">
+  <strong>Портируемый System-1 слой решений для agent harnesses.</strong><br>
+  Host владеет routing, receipts, replay и fail-open интеграциями.
+</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>
+  <a href="https://www.npmjs.com/package/jev-layer"><img alt="npm version" src="https://img.shields.io/npm/v/jev-layer?logo=npm&amp;label=npm"></a>
+  <a href="https://github.com/typakon4/jev-layer/releases"><img alt="latest GitHub release" src="https://img.shields.io/github/v/release/typakon4/jev-layer?display_name=tag&amp;sort=semver"></a>
+  <a href="https://github.com/typakon4/jev-layer/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/typakon4/jev-layer"></a>
+</p>
+
+[English](README.md) · [Русский](README.ru.md) · [简体中文](README.zh-CN.md)
+
+jev-layer маршрутизирует ограниченные решения и сохраняет доказательства; harness сохраняет владение исполнением, permissions, approvals, retry, восстановлением и итоговым результатом.
+
+> Интегрируете jev-layer в harness? Сначала дайте агенту [Agent implementation guide](docs/AGENT-IMPLEMENTATION.md), а не только ссылку на этот README.
+
+## Архитектура
+
+<p align="center">
+  <img src="docs/architecture.svg" alt="Архитектура: harness отправляет ограниченный запрос в jev-layer; host владеет permissions и execution; receipts поддерживают replay." width="960">
+</p>
+
+Jev не исполняет выбранную capability. Доступны детерминированный `demo`, OpenRouter Decisions и TypeSafe; тесты с provider credentials не требуются для обычного CI.
+
+## Быстрый старт
+
+Требуется Node.js 20 или новее. Обязательных runtime-зависимостей нет.
+
+Установить опубликованный CLI:
+
+```sh
+npm install --global jev-layer
+```
+
+Или использовать локальный 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` используется только локально и ничего не публикует. Вместо него можно запускать `node /path/to/jev-layer/bin/jev.mjs ...`. Provider по умолчанию — офлайн-детерминированный `demo`.
+
+Для stdio MCP:
+
+```sh
+jev mcp
+```
+
+Секреты должны находиться вне репозитория:
+
+```sh
+export JEV_LAYER_PROVIDER=openrouter
+export OPENROUTER_API_KEY='provided-by-your-secret-store'
+jev doctor --project /path/to/workspace
+```
+
+Все три режима (`demo`, `openrouter` и прямой `typesafe`), их endpoints и порядок выбора конфигурации описаны в [руководстве по провайдерам](docs/PROVIDERS.md).
+
+## Основные поверхности
+
+- **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`. 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.
+- **Jev 1.14, зрение и computer use:** TypeSafe и OpenRouter принимают PNG/JPEG-скриншоты; адаптер преобразует формат изображений для каждого API. Опциональный `jev_computer_step` выбирает desktop-действие из набора host; Box-координаты требуют проверки видимости цели и host approval. См. [контракт](docs/AGENT-IMPLEMENTATION.md#vision-and-computer-use).
+- **Fail-open:** при отключённом, недоступном, ошибочном или неубедительном Jev вызове управление возвращается в обычный host path. Jev не расширяет permissions и не угадывает execution.
+
+Опциональные поверхности по умолчанию отключены:
+
+```sh
+JEV_BROWSER_FAST_PATH=1 jev mcp
+JEV_LAYER_PROVIDER=openrouter JEV_COMPUTER_USE=1 jev mcp
+JEV_SUPERVISION=1 jev mcp
+JEV_CONTEXT_FILTER=shadow jev cli --input examples/route-request.json
+```
+
+## Harness adapters
+
+Примеры находятся в `integrations/`:
+
+- `integrations/hermes/` — для active plugin topology и safe change workflow см. [handoff локальному агенту (RU)](docs/HERMES-LOCAL-AGENT-HANDOFF.ru.md).
+- `integrations/omp/`
+- `integrations/codex/`
+- `integrations/template/`
+
+Для release baseline зафиксированы версии OMP `18.2.6`, Hermes `0.21.3` (`b675e6de`) и Codex CLI `0.155.1`, наблюдавшиеся в среде подготовки. Это базовая проверка версий и контрактов, а не полный набор provider/model tests; подробности — в [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
+
+### Добавление нового harness
+
+1. Скопируйте `integrations/template/adapter.mjs`.
+2. Добавьте `integrations/<harness>/` и secret-free config/example.
+3. Вызовите `jev_route`, сохраните `correlation_id`, исполняйте только через native registry host, затем вызовите `jev_record_execution`.
+4. Добавьте offline smoke fixture для успеха, fail-open, отказа в approval и execution receipt.
+5. Зафиксируйте поддерживаемые версии и пройдите CI.
+
+Подробности: [CONTRIBUTING.md](CONTRIBUTING.md), [docs/SCHEMA-VERSIONING.md](docs/SCHEMA-VERSIONING.md).
+
+## Статус browser
+
+Надёжность browser fast-path **проверена на текущих real-browser fixtures**: sequencing, visible-link navigation, native select, approval denial и recovery. **Оптимизация производительности остаётся экспериментальной**. Заявлений об ускорении браузера нет.
+
+## Безопасность и совместимость
+
+- Лицензия MIT: [LICENSE](LICENSE).
+- jev-layer не является security boundary. Источник истины для permissions и approvals — host: [SECURITY.md](SECURITY.md).
+- MCP tools, routing decisions, receipts, replay cases и adapter contract сейчас имеют version 1. Изменения должны быть additive и не ломать v1 молча.
+- Не коммитьте credentials, секретные logs, `.env` или machine-specific paths.
+
+## Проверка
+
+```sh
+npm test
+npm run smoke
+npm run fail-open-smoke
+npm run clean-install-smoke
+npm pack --dry-run
+```
+
+GitHub Actions запускает эти проверки на Node.js 20, 22 и 24. Provider-backed тесты требуют отдельного secret-managed окружения и не входят в обычный PR CI.
+
+Документы: [CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [RELEASE.md](RELEASE.md) · [CHANGELOG.md](CHANGELOG.md) · [Agent implementation guide](docs/AGENT-IMPLEMENTATION.md).