docs(engine): clarify ENGINE_V2 opt-in startup (#2694)

.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

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
 ```
 
 ## 開発

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
 ```
 
 ## 개발

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

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
 ```
 
 ## Разработка

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
 ```
 
 ## 开发

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.