docs: restructure README (EN/JA) for readability

README.ja.md

@@ -1,74 +1,26 @@
 # Roboppi
 
-[English](README.md) | 日本語
+<p align="center">
+  <img src="assets/roboppi-hero.png" alt="Roboppi" width="900" />
+</p>
 
-Roboppi（ろぼっぴ）は、エージェント（worker）の実行を安全に制御するための「実行制御ランタイム」です。
+[English](README.md) | 日本語
 
-Roboppi 自身が「エージェントとして仕事をする」ことは目的にしません。外部の worker CLI（OpenCode / Claude Code / Codex CLI / シェル）に重い作業（編集/コマンド/テスト）を委譲し、Roboppi は安全の不変条件（止める/制限する/観測する/隔離する）を強制します。
+Roboppi（ろぼっぴ）は、エージェント（worker）の実行を安全に制御するための「実行制御ランタイム」です。Roboppi 自身がエージェントとして仕事をするのではなく、外部の worker CLI（OpenCode / Claude Code / Codex CLI / シェル）に重い作業を委譲し、安全の不変条件（止める・制限する・観測する・隔離する）を強制します。
 
 注意: 主な CLI/バイナリ名は `roboppi` です。
 - 環境変数/状態ディレクトリ: `ROBOPPI_` / `.roboppi-loop/` を使います。
 
-## Roboppiでできること（Capabilities）
-
-実行制御（Core ランタイム）:
-
-- ハードな予算制約: timeout / max attempts / concurrency / RPS /（任意で）cost cap
-- エンドツーエンドのキャンセル: Job -> Permit -> Worker を AbortSignal で伝播（best-effort で SIGTERM -> SIGKILL）
-- 失敗の封じ込め: circuit breaker + backpressure（過負荷時の reject/defer/degrade）
-- プロセス隔離: heavy work を別プロセスに委譲して blast radius を限定
-- 監査性: 構造化ログ + アーティファクト（stdout/stderr の要約、diff/patch、実行コマンド、時間など）
-
-ワークフロー（YAML オーケストレーション）:
-
-- 複数ステップの DAG 実行（`depends_on`）と並列度制御（`concurrency`）
-- `context/` を使ったファイルベースの成果物受け渡し（`outputs` / `inputs`）
-- 失敗ポリシー（`retry` / `continue` / `abort`）と自動リトライ
-- `completion_check` + `max_iterations` による「完了するまでループ」
-- （任意）ループ収束ガード: 停滞検知 + スコープ/差分予算（`allowed_paths`, `max_changed_files`）
-
-自動化（Daemon モード）:
-
-- interval/cron/fswatch/webhook/command のイベントで workflow を常駐実行
-- evaluate/analyze ゲート（条件成立時だけ LLM/worker を走らせる）
-- supervised 実行: Supervisor -> Core -> Worker のプロセスツリーを IPC で維持（socket transport あり）
-
-リポジトリ安全（git workspace）:
+## 特徴
 
-- base branch の決定を固定化し、起動時 SHA を記録（追跡/再現性）
-- Branch Lock: 実行中の repo/branch ドリフトを step 実行前に fail-fast
-- Protected branch guard: `main` などへの直接編集をデフォルトでブロック（明示 override が必要）
-
-拡張性:
-
-- `WorkerAdapter` インタフェースで worker を追加
-- agent catalog（`agents.yaml`）で `step.agent` による再利用プロファイル
-
-スケジューリング（参照実装）:
-
-- 優先度付きジョブキュー（interactive vs batch）
-- idempotency key による重複制御（`coalesce` / `latest-wins` / `reject`）
-- リトライポリシー（指数バックオフ + jitter）と DLQ
-- Core を起動/監視する Supervisor（クラッシュ/ハング対策）
-
-## アーキテクチャ（概要）
-
-Roboppi は 3 層構造として設計されています。
-
-```
-Supervisor / Runner（policy, 親プロセス）
-  -> Core（mechanism, 子プロセス）
-      -> Worker プロセス（外部 CLI）
-```
-
-- Core が安全の不変条件（permits, budgets, cancellation, cutoffs）を保持します。
-- policy（順序、リトライ、重複制御など）は Supervisor/Runner 側に寄せて差し替え可能にします。
-- Core と Supervisor は JSON Lines IPC で通信します。
-
-設計資料:
-
-- `docs/design.md`
-- `docs/guide/architecture.md`
+- ハードな予算制約 -- timeout / max attempts / concurrency / RPS / cost cap
+- エンドツーエンドのキャンセル -- Job -> Permit -> Worker を AbortSignal で伝播
+- 失敗の封じ込め -- circuit breaker + backpressure による過負荷制御
+- プロセス隔離 -- heavy work を別プロセスに委譲して blast radius を限定
+- YAML ワークフロー -- DAG 実行、並列度制御、ループ完了判定、失敗ポリシー
+- Daemon モード -- interval/cron/fswatch/webhook で workflow を常駐実行
+- ブランチ安全 -- base branch 固定、Branch Lock、保護ブランチガード
+- 構造化ログとアーティファクト -- stdout/stderr 要約、diff/patch、実行コマンド、時間
 
 ## インストール
 
@@ -201,7 +153,72 @@ ROBOPPI_ROOT="$ROBOPPI_ROOT" bun run --cwd "$ROBOPPI_ROOT" src/workflow/run.ts \
 - workflow は target workspace 内に `.roboppi-loop/` と `context/` を作ります（通常は gitignore 推奨）。
 - PR 作成は `.roboppi-loop/enable_pr` による opt-in です。
 
-## Workflow YAML の最小例
+## アーキテクチャ（概要）
+
+Roboppi は 3 層構造として設計されています。
+
+```
+Supervisor / Runner（policy, 親プロセス）
+  -> Core（mechanism, 子プロセス）
+      -> Worker プロセス（外部 CLI）
+```
+
+- Core が安全の不変条件（permits, budgets, cancellation, cutoffs）を保持します。
+- policy（順序、リトライ、重複制御など）は Supervisor/Runner 側に寄せて差し替え可能にします。
+- Core と Supervisor は JSON Lines IPC で通信します。
+
+設計資料:
+
+- `docs/design.md`
+- `docs/guide/architecture.md`
+
+---
+
+## リファレンス
+
+### 機能の詳細
+
+**実行制御（Core ランタイム）:**
+
+- ハードな予算制約: timeout / max attempts / concurrency / RPS /（任意で）cost cap
+- エンドツーエンドのキャンセル: Job -> Permit -> Worker を AbortSignal で伝播（best-effort で SIGTERM -> SIGKILL）
+- 失敗の封じ込め: circuit breaker + backpressure（過負荷時の reject/defer/degrade）
+- プロセス隔離: heavy work を別プロセスに委譲して blast radius を限定
+- 監査性: 構造化ログ + アーティファクト（stdout/stderr の要約、diff/patch、実行コマンド、時間など）
+
+**ワークフロー（YAML オーケストレーション）:**
+
+- 複数ステップの DAG 実行（`depends_on`）と並列度制御（`concurrency`）
+- `context/` を使ったファイルベースの成果物受け渡し（`outputs` / `inputs`）
+- 失敗ポリシー（`retry` / `continue` / `abort`）と自動リトライ
+- `completion_check` + `max_iterations` による「完了するまでループ」
+- （任意）ループ収束ガード: 停滞検知 + スコープ/差分予算（`allowed_paths`, `max_changed_files`）
+
+**自動化（Daemon モード）:**
+
+- interval/cron/fswatch/webhook/command のイベントで workflow を常駐実行
+- evaluate/analyze ゲート（条件成立時だけ LLM/worker を走らせる）
+- supervised 実行: Supervisor -> Core -> Worker のプロセスツリーを IPC で維持（socket transport あり）
+
+**リポジトリ安全（git workspace）:**
+
+- base branch の決定を固定化し、起動時 SHA を記録（追跡/再現性）
+- Branch Lock: 実行中の repo/branch ドリフトを step 実行前に fail-fast
+- Protected branch guard: `main` などへの直接編集をデフォルトでブロック（明示 override が必要）
+
+**拡張性:**
+
+- `WorkerAdapter` インタフェースで worker を追加
+- agent catalog（`agents.yaml`）で `step.agent` による再利用プロファイル
+
+**スケジューリング（参照実装）:**
+
+- 優先度付きジョブキュー（interactive vs batch）
+- idempotency key による重複制御（`coalesce` / `latest-wins` / `reject`）
+- リトライポリシー（指数バックオフ + jitter）と DLQ
+- Core を起動/監視する Supervisor（クラッシュ/ハング対策）
+
+### Workflow YAML の最小例
 
 ```yaml
 name: build-test
@@ -228,7 +245,7 @@ steps:
 
 詳細: `docs/guide/workflow.md`
 
-## Agent Catalog（再利用できるエージェント定義）
+### Agent Catalog（再利用できるエージェント定義）
 
 同じ worker/model/capabilities/base-instructions を繰り返す場合、外部 YAML（agent catalog）にまとめられます。
 
@@ -258,7 +275,7 @@ steps:
 - `docs/guides/agents.md`
 - `docs/guides/agents.ja.md`
 
-## ブランチ安全（git workspace）
+### ブランチ安全（git workspace）
 
 git repo に対する workflow 実行向けに、base branch 解決 / Branch Lock / 保護ブランチガードを提供します。
 
@@ -273,7 +290,7 @@ git repo に対する workflow 実行向けに、base branch 解決 / Branch Loc
 - `docs/guides/branch.md`
 - `docs/guides/branch.ja.md`
 
-## Supervised IPC transport（supervised 実行）
+### Supervised IPC transport（supervised 実行）
 
 supervised 実行では runner/daemon が Core 子プロセスを起動し、IPC 経由で step を委譲します。
 

README.md

@@ -6,73 +6,21 @@
 
 English | [日本語](README.ja.md)
 
-Roboppi (ろぼっぴ, pronounced "roh-boh-pee") is an execution-control runtime for agentic workers.
-
-It does not try to be "the agent". It enforces safety invariants around external worker CLIs (OpenCode / Claude Code / Codex CLI / plain shell), so your automation stops when it should, stays within budgets, and leaves a trail you can audit.
+Roboppi (ろぼっぴ, pronounced "roh-boh-pee") is an execution-control runtime for agentic workers. It does not try to be "the agent" — it enforces safety invariants around external worker CLIs (OpenCode / Claude Code / Codex CLI / plain shell), so your automation stops when it should, stays within budgets, and leaves a trail you can audit.
 
 Note: the primary CLI/binary name is `roboppi`.
 - Env vars/state dirs: use `ROBOPPI_` / `.roboppi-loop/`.
 
-## What Roboppi Can Do (Capabilities)
-
-Execution control (Core runtime):
-
-- Enforce hard budgets: timeouts, max attempts, concurrency, RPS, optional cost caps
-- End-to-end cancellation: Job -> Permit -> Worker via AbortSignal (best-effort SIGTERM -> SIGKILL)
-- Failure containment: circuit breakers + backpressure responses under overload
-- Process isolation: delegate heavy work to separate worker processes (limit blast radius)
-- Auditability: structured logs + artifacts (stdout/stderr summaries, diffs/patches, executed commands, timings)
-
-Workflow orchestration (YAML):
-
-- Run multi-step DAG workflows (`depends_on`) with optional parallelism (`concurrency`)
-- Pass files between steps with declared `outputs`/`inputs` via a `context/` directory
-- Automatic step retries and failure policy (`retry` / `continue` / `abort`)
-- Loop until complete with `completion_check` + `max_iterations`
-- Optional convergence guard for loops: stall detection + scope/diff budgets (`allowed_paths`, `max_changed_files`)
-
-Automation (Daemon mode):
-
-- Run workflows on interval/cron/fswatch/webhook/command events
-- Optional evaluate/analyze gates (run LLM work only when conditions are met)
-- Supervised execution: Supervisor -> Core -> Worker process tree via IPC (socket-based transport available)
-
-Repo safety (git workspaces):
-
-- Deterministic base branch resolution (records base commit SHA)
-- Branch Lock drift detection (fail-fast before a step runs)
-- Protected-branch guard to avoid direct edits on `main` (override must be explicit)
-
-Extensibility:
-
-- Add worker adapters behind a unified `WorkerAdapter` interface
-- Reusable agent profiles via agent catalogs (`agents.yaml`) referenced by `step.agent`
-
-Scheduling (reference implementation):
-
-- Prioritized job queue (interactive vs batch)
-- Deduplication via idempotency keys (`coalesce` / `latest-wins` / `reject`)
-- Retry policy (exponential backoff + jitter) + DLQ storage
-- Supervisor that launches/monitors the Core process (crash/hang handling)
-
-## Architecture (High Level)
+## Features at a Glance
 
-Roboppi is designed as a 3-layer system:
-
-```
-Supervisor / Runner (policy, parent process)
-  -> Core (mechanism, child process)
-      -> Worker processes (external CLIs)
-```
-
-- Core owns safety invariants (permits, budgets, cancellation, cutoffs).
-- Policy (ordering, retries, dedup strategy) stays swappable at the supervisor/runner level.
-- Core and supervisor communicate over JSON Lines IPC.
-
-Design docs:
-
-- `docs/design.md`
-- `docs/guide/architecture.md`
+- **Hard budget enforcement** — timeouts, max attempts, concurrency, RPS, cost caps
+- **End-to-end cancellation** — Job to Permit to Worker via AbortSignal (SIGTERM then SIGKILL)
+- **Failure containment** — circuit breakers and backpressure under overload
+- **Process isolation** — delegate heavy work to separate worker processes, limiting blast radius
+- **YAML workflow orchestration** — multi-step DAGs with parallelism, retries, and loop-until-complete
+- **Daemon mode** — trigger workflows on interval, cron, fswatch, webhook, or command events
+- **Branch safety** — base-branch resolution, drift detection, and protected-branch guards
+- **Extensible worker adapters** — unified interface for OpenCode, Claude Code, Codex CLI, and custom agents
 
 ## Install
 
@@ -208,7 +156,72 @@ Notes:
 - The workflow writes state/artifacts under `.roboppi-loop/` and `context/` inside the target workspace (typically gitignored).
 - PR creation is opt-in via `.roboppi-loop/enable_pr`.
 
-## Workflow YAML At A Glance
+## Architecture
+
+Roboppi is designed as a 3-layer system:
+
+```
+Supervisor / Runner (policy, parent process)
+  -> Core (mechanism, child process)
+      -> Worker processes (external CLIs)
+```
+
+- Core owns safety invariants (permits, budgets, cancellation, cutoffs).
+- Policy (ordering, retries, dedup strategy) stays swappable at the supervisor/runner level.
+- Core and supervisor communicate over JSON Lines IPC.
+
+Design docs:
+
+- `docs/design.md`
+- `docs/guide/architecture.md`
+
+---
+
+## Reference
+
+### Capabilities in Detail
+
+**Execution control (Core runtime):**
+
+- Enforce hard budgets: timeouts, max attempts, concurrency, RPS, optional cost caps
+- End-to-end cancellation: Job -> Permit -> Worker via AbortSignal (best-effort SIGTERM -> SIGKILL)
+- Failure containment: circuit breakers + backpressure responses under overload
+- Process isolation: delegate heavy work to separate worker processes (limit blast radius)
+- Auditability: structured logs + artifacts (stdout/stderr summaries, diffs/patches, executed commands, timings)
+
+**Workflow orchestration (YAML):**
+
+- Run multi-step DAG workflows (`depends_on`) with optional parallelism (`concurrency`)
+- Pass files between steps with declared `outputs`/`inputs` via a `context/` directory
+- Automatic step retries and failure policy (`retry` / `continue` / `abort`)
+- Loop until complete with `completion_check` + `max_iterations`
+- Optional convergence guard for loops: stall detection + scope/diff budgets (`allowed_paths`, `max_changed_files`)
+
+**Automation (Daemon mode):**
+
+- Run workflows on interval/cron/fswatch/webhook/command events
+- Optional evaluate/analyze gates (run LLM work only when conditions are met)
+- Supervised execution: Supervisor -> Core -> Worker process tree via IPC (socket-based transport available)
+
+**Repo safety (git workspaces):**
+
+- Deterministic base branch resolution (records base commit SHA)
+- Branch Lock drift detection (fail-fast before a step runs)
+- Protected-branch guard to avoid direct edits on `main` (override must be explicit)
+
+**Extensibility:**
+
+- Add worker adapters behind a unified `WorkerAdapter` interface
+- Reusable agent profiles via agent catalogs (`agents.yaml`) referenced by `step.agent`
+
+**Scheduling (reference implementation):**
+
+- Prioritized job queue (interactive vs batch)
+- Deduplication via idempotency keys (`coalesce` / `latest-wins` / `reject`)
+- Retry policy (exponential backoff + jitter) + DLQ storage
+- Supervisor that launches/monitors the Core process (crash/hang handling)
+
+### Workflow YAML At A Glance
 
 Minimal example:
 
@@ -237,7 +250,7 @@ For loops:
 
 See `docs/guide/workflow.md` for the full schema.
 
-## Agent Catalogs (Reusable Agent Profiles)
+### Agent Catalogs (Reusable Agent Profiles)
 
 If you repeat the same worker/model/capabilities/base-instructions across steps, define an agent catalog:
 
@@ -267,7 +280,7 @@ Docs:
 - `docs/guides/agents.md`
 - `docs/guides/agents.ja.md`
 
-## Branch Safety (Git Workspaces)
+### Branch Safety (Git Workspaces)
 
 For workflows that operate on git repos, Roboppi provides base-branch resolution, Branch Lock drift detection, and protected-branch guards.
 
@@ -282,7 +295,7 @@ Docs:
 - `docs/guides/branch.md`
 - `docs/guides/branch.ja.md`
 
-## Supervised IPC Transport (For `--supervised`)
+### Supervised IPC Transport (For `--supervised`)
 
 Workflows/daemon run supervised by default. In supervised mode, the runner starts a Core child process and delegates steps over IPC.