From d9fc08456da730e69334cbc50d20f24a9373cc5d Mon Sep 17 00:00:00 2001
From: Firat Sertgoz <f@nuff.tech>
Date: Sun, 19 Apr 2026 22:16:11 +0300
Subject: [PATCH] docs(engine): clarify ENGINE_V2 opt-in startup

---
 .env.example                            |  2 ++
 README.ja.md                            | 17 ++++++++++++++---
 README.ko.md                            | 17 ++++++++++++++---
 README.md                               |  9 +++++++--
 README.ru.md                            | 17 ++++++++++++++---
 README.zh-CN.md                         | 17 ++++++++++++++---
 docs/internal/engine-v2-architecture.md | 10 +++++++++-
 7 files changed, 74 insertions(+), 15 deletions(-)

diff --git a/.env.example b/.env.example
index f81b1d69766..d2afe9768fd 100644
--- a/.env.example
+++ b/.env.example
@@ -173,6 +173,8 @@ HTTP_WEBHOOK_SECRET=your-webhook-secret
 # SIGNAL_IGNORE_STORIES=true
 
 # Agent Settings
+# Engine v2 is opt-in. Set this to true to route messages through the new engine.
+# ENGINE_V2=true
 AGENT_NAME=ironclaw
 AGENT_MAX_PARALLEL_JOBS=5
 AGENT_JOB_TIMEOUT_SECS=3600
diff --git a/README.ja.md b/README.ja.md
index cc6e31b4110..2a3fb073ef5 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -279,15 +279,26 @@ WASM ──► 許可リスト ──► リーク    ──► 認証情報 ─
 
 ## 使い方
 
+Engine v2 は現在オプトインです。従来のエージェントループではなく新しいエンジンを使いたい場合は、IronClaw を `ENGINE_V2=true` 付きで起動してください。
+
 ```bash
 # 初回セットアップ（データベース、認証などを設定）
 ironclaw onboard
 
-# インタラクティブREPLを起動
+# インストール済みバイナリを起動
+ironclaw
+
+# Engine v2 でインストール済みバイナリを起動
+ENGINE_V2=true ironclaw
+
+# ソースからインタラクティブREPLを起動
 cargo run
 
-# デバッグログ付き
-RUST_LOG=ironclaw=debug cargo run
+# ソースから Engine v2 のインタラクティブREPLを起動
+ENGINE_V2=true cargo run
+
+# Engine v2 をデバッグログ付きで起動
+ENGINE_V2=true RUST_LOG=ironclaw=debug cargo run
 ```
 
 ## 開発
diff --git a/README.ko.md b/README.ko.md
index 903b8d1c2a1..d4191edde8c 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -286,15 +286,26 @@ WASM ──► 화이트리스트 ──► 누출 스캔 ──► 자격 증
 
 ## 사용법
 
+Engine v2는 현재 옵트인입니다. 기존 에이전트 루프 대신 새 엔진을 사용하려면 `ENGINE_V2=true`를 설정해서 IronClaw를 시작하세요.
+
 ```bash
 # 첫 설정 (데이터베이스, 인증 등 구성)
 ironclaw onboard
 
-# 대화형 REPL 시작
+# 설치된 바이너리 시작
+ironclaw
+
+# Engine v2로 설치된 바이너리 시작
+ENGINE_V2=true ironclaw
+
+# 소스에서 대화형 REPL 시작
 cargo run
 
-# 디버그 로깅 사용
-RUST_LOG=ironclaw=debug cargo run
+# 소스에서 Engine v2 대화형 REPL 시작
+ENGINE_V2=true cargo run
+
+# Engine v2를 디버그 로깅과 함께 시작
+ENGINE_V2=true RUST_LOG=ironclaw=debug cargo run
 ```
 
 ## 개발
diff --git a/README.md b/README.md
index c99e0f4b561..a9b9a370fe4 100644
--- a/README.md
+++ b/README.md
@@ -286,6 +286,8 @@ External content passes through multiple security layers:
 
 ## Usage
 
+Engine v2 is opt-in right now. If you want to run the new engine instead of the legacy agent loop, start IronClaw with `ENGINE_V2=true`. See [Engine v2 architecture](docs/internal/engine-v2-architecture.md#enabling-engine-v2) for more details.
+
 ```bash
 # First-time setup (configures database, auth, etc.)
 ironclaw onboard
@@ -293,8 +295,11 @@ ironclaw onboard
 # Start interactive REPL
 cargo run
 
-# With debug logging
-RUST_LOG=ironclaw=debug cargo run
+# Start interactive REPL with engine v2
+ENGINE_V2=true cargo run
+
+# Engine v2 with debug logging
+ENGINE_V2=true RUST_LOG=ironclaw=debug cargo run
 ```
 
 ## Development
diff --git a/README.ru.md b/README.ru.md
index 06689c04d59..a01bc71c34d 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -281,15 +281,26 @@ WASM ──► Валидатор ──► Сканер ───► Инъек
 
 ## Использование
 
+Сейчас engine v2 включается отдельно. Если вы хотите запускать новый движок вместо устаревшего цикла агента, запускайте IronClaw с `ENGINE_V2=true`.
+
 ```bash
 # Первоначальная настройка (БД, аутентификация и т.д.)
 ironclaw onboard
 
-# Запуск интерактивного REPL
+# Запуск установленного бинарника
+ironclaw
+
+# Запуск установленного бинарника с engine v2
+ENGINE_V2=true ironclaw
+
+# Запуск интерактивного REPL из исходников
 cargo run
 
-# С отладочными логами
-RUST_LOG=ironclaw=debug cargo run
+# Запуск интерактивного REPL из исходников с engine v2
+ENGINE_V2=true cargo run
+
+# Engine v2 с отладочными логами
+ENGINE_V2=true RUST_LOG=ironclaw=debug cargo run
 ```
 
 ## Разработка
diff --git a/README.zh-CN.md b/README.zh-CN.md
index d840793b618..f41cfccfda7 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -277,15 +277,26 @@ WASM ──► 白名单  ──► 泄露扫描 ──► 凭据  ──► 执
 
 ## 使用方式
 
+Engine v2 当前需要显式开启。如果你想运行新的引擎而不是旧的代理循环，请在启动 IronClaw 时设置 `ENGINE_V2=true`。
+
 ```bash
 # 首次设置（配置数据库、认证等）
 ironclaw onboard
 
-# 启动交互式 REPL
+# 启动已安装的二进制
+ironclaw
+
+# 使用 Engine v2 启动已安装的二进制
+ENGINE_V2=true ironclaw
+
+# 从源码启动交互式 REPL
 cargo run
 
-# 启用调试日志
-RUST_LOG=ironclaw=debug cargo run
+# 从源码启动 Engine v2 交互式 REPL
+ENGINE_V2=true cargo run
+
+# 使用 Engine v2 并启用调试日志
+ENGINE_V2=true RUST_LOG=ironclaw=debug cargo run
 ```
 
 ## 开发
diff --git a/docs/internal/engine-v2-architecture.md b/docs/internal/engine-v2-architecture.md
index 535d84d6a11..da786f04039 100644
--- a/docs/internal/engine-v2-architecture.md
+++ b/docs/internal/engine-v2-architecture.md
@@ -116,7 +116,15 @@ The bridge connects the engine to existing IronClaw infrastructure:
 
 ### Enabling Engine v2
 
-Set `ENGINE_V2=true` environment variable. The router in `src/bridge/router.rs` intercepts messages and routes them through the engine instead of the v1 agent loop.
+Set `ENGINE_V2=true` in the environment. Without it, IronClaw keeps using the legacy v1 agent loop. The router in `src/bridge/router.rs` intercepts messages and routes them through the engine instead of the v1 agent loop.
+
+```bash
+# Installed binary
+ENGINE_V2=true ironclaw
+
+# Run from source
+ENGINE_V2=true cargo run
+```
 
 For trace debugging set `IRONCLAW_RECORD_TRACE=1`. Engine v2 reuses the host crate's `RecordingLlm` (see `src/llm/recording.rs`) — the engine's `LlmBackend` is wired to the same provider chain, so LLM interactions are captured in the standard `trace_*.json` fixture file (configurable via `IRONCLAW_TRACE_OUTPUT`). There is no separate engine trace file.