docs: internationalize top-level documentation files to English and backup Korean originals to *.ko.md

BOOTSTRAP.md

@@ -1,103 +1,103 @@
 # BOOTSTRAP.md
 
-본 문서는 `advanced_multi_agent` 오케스트레이션 및 메시징 백플레인 워크플로우를 새로운 프로젝트에 도입하여 이식하고, 새로운 개발자/에이전트가 초기 가동을 시작할 때 수행해야 하는 환경 설정 및 구축 절차를 안내합니다.
+This document guides you through the setup and initialization procedures required to adopt the `advanced_multi_agent` orchestration and messaging backplane workflow in a new project, enabling a new developer or agent to get up and running quickly.
 
-새로운 에이전트는 이 안내서에 기술된 절차를 순차적으로 실행하여 초기 환경을 안정적으로 설정할 수 있습니다.
+A new agent can follow the steps in this guide sequentially to establish a stable and reliable initial environment.
 
 ---
 
-## 1. 프로젝트 구조 이해 (Scaffolding Overview)
+## 1. Scaffolding Overview (Project Structure)
 
-본 프로젝트를 새로운 환경에 복제(Clone)한 후, 핵심 구성 요소들의 위치와 역할을 먼저 파악해야 합니다.
+Before cloning this project into a new environment, you must first understand the locations and roles of its core components:
 
-*   `skills/`: 멀티 에이전트 구동 및 비동기 잡 처리를 수행하는 셸 스크립트 모음
-    *   `lib.sh`: 오케스트레이션의 핵심 셸 함수 및 가상환경(venv) 자동 연동 라이브러리
-    *   `tmux-agent-orchestrate-create/`: 격리된 tmux 에이전트 세션을 시작하는 스크립트
-    *   `tmux-agent-orchestrate-stop/`: 세션을 정상적으로 중지하고 상태를 업데이트하는 스크립트
-    *   `tmux-agent-orchestrate-resume/`: 중지된 에이전트 세션을 이전 대화 상태 그대로 복원하는 스크립트
-    *   `tmux-agent-orchestrate-status/`: 전체 에이전트 세션의 현재 구동 상태를 조회하는 스크립트
-    *   `tmux-agent-orchestrate-monitor/`: tmux 상태와 레지스트리 상태를 동기화하는 모니터 스크립트
-    *   `tmux-agent-orchestrate-delegate-job/`: 비동기 잡 분할 실행 모듈
-        *   `requirements.txt`: Python 의존성 목록 (paho-mqtt, pyyaml)
-        *   `scripts/`: 핵심 비즈니스 로직을 구동하는 Python 스크립트 디렉터리
-            *   `registry.py`: 잡의 등록, 클레임 및 원자적 파일 락 제어 (CLI 지원)
-            *   `job_subscriber.py`: 백그라운드 이벤트 구독기 및 오디팅 로그 생성기
-            *   `publish_event.py`: 실행 상태 및 에러 트랩 시 이벤트 퍼블리셔
-            *   `mqtt_common.py`: 공통 MQTT 브로커 연결 유틸리티
-*   `AGENT.md`: 에이전트 간의 역할 분담(PM, Worker, Reviewer) 및 이벤트 발행 규약 정의
-*   `MESSAGING.md`: 에이전트 간 주고받는 MQTT 메시지 와이어 스킴 가이드라인
+*   `skills/`: A collection of shell scripts that execute multi-agent coordination and asynchronous job processing.
+    *   `lib.sh`: The core orchestration shell functions and virtual environment (venv) auto-loading library.
+    *   `tmux-agent-orchestrate-create/`: Script to launch isolated tmux agent sessions.
+    *   `tmux-agent-orchestrate-stop/`: Script to gracefully stop agent sessions and update states.
+    *   `tmux-agent-orchestrate-resume/`: Script to restore stopped agent sessions back to their previous conversation state.
+    *   `tmux-agent-orchestrate-status/`: Script to query the current running state of all agent sessions.
+    *   `tmux-agent-orchestrate-monitor/`: Monitor script to sync tmux states with the registry.
+    *   `tmux-agent-orchestrate-delegate-job/`: Asynchronous job splitting and delegation module.
+        *   `requirements.txt`: Python dependency list (`paho-mqtt`, `pyyaml`).
+        *   `scripts/`: Python scripts running the core business logic.
+            *   `registry.py`: Job registration, claiming, and atomic file lock control (CLI supported).
+            *   `job_subscriber.py`: Background event subscriber and audit log generator.
+            *   `publish_event.py`: Event publisher for runtime states and error traps.
+            *   `mqtt_common.py`: Common utility for connecting to the MQTT broker.
+*   `AGENT.md`: Definition of agent roles (PM, Worker, Reviewer) and event publication rules.
+*   `MESSAGING.md`: Messaging scheme and wire protocol guidelines for MQTT communication between agents.
 
 ---
 
-## 2. 환경 설정 파일 생성 (.env)
+## 2. Environment Configuration (.env)
 
-메시징 브로커 설정 및 실행 경로를 설정하기 위해 로컬 환경 설정 파일(`.env`)을 생성하고 수정해야 합니다.
+To set up the messaging broker and execution paths, you must create and modify a local environment configuration file (`.env`).
 
-### 단계 2.1: 자동 생성 스크립트 실행
-프로젝트 루트에서 제공되는 환경 설정 템플릿 복사 스크립트를 실행합니다.
+### Step 2.1: Run the Generation Script
+Run the environment template copy script provided in the project root:
 
 ```bash
-# .env.example를 .env로 자동 복제 (이미 존재하면 덮어쓰지 않고 보호됨)
+# Automatically copy .env.example to .env (does not overwrite if it already exists)
 ./scripts/generate-env.sh
 
-# 만약 강제로 덮어쓰고 백업을 생성하고 싶은 경우:
+# To force overwrite and create a backup of the existing .env:
 ./scripts/generate-env.sh --force
 ```
 
-### 단계 2.2: 환경 변수 수정 및 설정
-생성된 `.env` 파일을 열어 설정을 필요에 따라 구성합니다.
+### Step 2.2: Modify Environment Variables
+Open the generated `.env` file to configure settings as needed.
 
 > [!NOTE]
-> `generate-env.sh`로 생성된 기본 `.env` 파일은 모든 환경 변수 항목이 주석 처리되어 있습니다. 주석 처리된 상태로 둘 경우 로컬 프로젝트 루트를 기준으로 한 상대 경로(`.hermes/` 등) 및 기본 공개 브로커 주소가 자동 지정되므로 그대로 사용하셔도 무방합니다.
+> The default `.env` file generated by `generate-env.sh` has all environment variables commented out. If left commented out, the system defaults to using relative paths (`.hermes/`, etc.) relative to the local project root, and the public MQTT broker. You can use it as-is without uncommenting anything.
 
-1.  **MQTT Broker 설정 (`MQTT_BROKER`)**:
-    *   기본값은 HiveMQ 공개 브로커(`broker.hivemq.com`)로 잡혀 있으나, 보안 및 프라이버시가 중요한 프로덕션 작업 시에는 개인/사설 브로커 주소로 변경할 것을 강력히 권장합니다.
-2.  **인증 정보 (`MQTT_USERNAME`, `MQTT_PASSWORD`)**:
-    *   보안 브로커를 사용하는 경우 `replace_me`로 명시된 곳을 실제 브로커 계정 정보로 변경해 주십시오.
-3.  **경로 관련 변수 (선택 사항)**:
-    *   특정 빌드 시스템이나 호스트 폴더 구조에 맞추어 `AGENT_SESSIONS_YAML` 및 `DELEGATE_JOB_LOGS_DIR` 등의 경로 값을 절대 경로로 오버라이드해야 하는 경우에만 주석을 풀고 기입하십시오.
+1.  **MQTT Broker Setup (`MQTT_BROKER`)**:
+    *   The default broker is HiveMQ's public sandbox broker (`broker.hivemq.com`). However, for production work where security and privacy are critical, we strongly recommend changing this to a private broker address.
+2.  **Authentication Credentials (`MQTT_USERNAME`, `MQTT_PASSWORD`)**:
+    *   If using a secured broker, change the placeholders marked `replace_me` to your actual broker credentials.
+3.  **Path Variables (Optional)**:
+    *   Uncomment and specify absolute paths for variables like `AGENT_SESSIONS_YAML` and `DELEGATE_JOB_LOGS_DIR` only if you need to override the default relative paths to align with specific build systems or host directories.
 
 > [!WARNING]
-> **보안 모드 기본값 안내**:
-> 시스템의 기본 설정은 **무인증 PoC 모드**입니다. 잡 등록 시 `auth_token`이 명시적으로 주입되지 않으면(또는 `null`인 경우) HMAC 서명 검증이 생략됩니다.
-> 공개 브로커 사용 환경이나 실제 프로덕션 단계에서는 잡 등록 시 `auth_token`을 고유 난수값으로 생성 및 주입하여 HMAC 보안 서명을 활성화해야 합니다. (자세한 보안 규약은 [MESSAGING.md](./MESSAGING.md) 및 [AGENT.md](./AGENT.md)의 `2.3 보안 프로토콜` 섹션을 참조하십시오. 현재 CLI를 통한 자동 토큰 생성/주입 기능 지원은 향후 로드맵의 `FW-N6` 과제로 처리 예정입니다.)
+> **Security Mode Default Warning**:
+> The system's default setting is the **unauthenticated PoC mode**. If an `auth_token` is not explicitly provided (or is `null`) during job registration, HMAC signature verification is skipped.
+> In a public broker environment or production phase, you must generate and inject a unique random `auth_token` during job registration to enable HMAC signature security. (For detailed security protocols, refer to section `2.3 Security Protocol` in [MESSAGING.md](./MESSAGING.md) and [AGENT.md](./AGENT.md). Automated token generation and injection via CLI is on the roadmap under task `FW-N6`.)
 
 ---
 
-## 3. 의존성 및 가상환경 설정 (Venv Setup)
+## 3. Dependency and Virtualenv Setup
 
-오케스트레이션 및 MQTT 메시징을 구동하기 위한 Python 3 의존성을 설정합니다.
+Set up the Python 3 dependencies required to run the orchestration and MQTT messaging backplane.
 
-### 단계 3.1: Python 가상환경 구축
-프로젝트 루트에서 `.venv` 가상환경을 생성하고 활성화합니다.
+### Step 3.1: Build Python Virtual Environment
+Create and activate a `.venv` virtual environment in the project root:
 
 ```bash
-# 가상환경 생성
+# Create virtual environment
 python3 -m venv .venv
 
-# 가상환경 활성화
+# Activate virtual environment
 source .venv/bin/activate
 ```
 
-### 단계 3.2: 의존성 패키지 설치
-`tmux-agent-orchestrate-delegate-job` 디렉터리에 기재된 `requirements.txt` 의존성 목록을 가상환경에 설치합니다.
+### Step 3.2: Install Dependency Packages
+Install the required packages listed in `requirements.txt` under `tmux-agent-orchestrate-delegate-job`:
 
 ```bash
-# 의존성 패키지(pyyaml, paho-mqtt 등) 설치
+# Install dependencies (pyyaml, paho-mqtt, etc.)
 pip install -r skills/tmux-agent-orchestrate-delegate-job/requirements.txt
 ```
 
 ---
 
-## 4. 디렉터리 준비 및 보안 감시 가이드
+## 4. Directory Structure and Security Audit Guide
 
-에이전트 제어 상태 및 잡 기록을 위해 로컬 레지스트리 디렉터리가 정상적으로 생성되었는지 확인합니다.
+Ensure that the local registry directories required to track agent states and jobs are successfully created:
 
-1.  **필수 로컬 디렉터리 구조**:
-    *   `.hermes/jobs/`: 등록된 비동기 잡의 세부 메타데이터가 파일 형태로 저장되는 디렉터리
-    *   `.hermes/delegate_job_logs/`: 에이전트가 발행하는 모든 백플레인 이벤트 흐름이 기록되는 audit log (`events.ndjson`) 보존 디렉터리
-2.  **Git 커밋 제어 (.gitignore)**:
-    *   새 프로젝트 초기화 시 아래 파일들이 절대 리포지토리에 커밋되지 않도록 `.gitignore` 상태를 점검합니다. `!.env.example` 예외 처리가 유지되어야 템플릿이 보존됩니다:
+1.  **Required Directory Structure**:
+    *   `.hermes/jobs/`: Holds detailed metadata files for registered asynchronous jobs.
+    *   `.hermes/delegate_job_logs/`: Holds the audit logs (`events.ndjson`) for all backplane events published by agents.
+2.  **Git Ignore Configuration (`.gitignore`)**:
+    *   When initializing a new project, verify that the following entries are configured in `.gitignore` to prevent committing local runtimes to the repository. The exception `!.env.example` must be kept to preserve the template:
         ```text
         .env
         .env.*
@@ -110,56 +110,57 @@ pip install -r skills/tmux-agent-orchestrate-delegate-job/requirements.txt
 
 ---
 
-## 5. 실행 환경 검증 및 부트스트랩 테스트
+## 5. Execution Verification and Bootstrap Tests
 
-환경 구축이 오작동 없이 안전하게 완료되었는지 아래의 체크리스트를 실행해 검증합니다.
+To verify that the environment has been successfully built without runtime errors, run the following verification checklist.
 
 > [!IMPORTANT]
-> 아래의 모든 검증 명령은 반드시 **프로젝트 루트 디렉터리**(`.hermes/` 디렉터리가 직접 보이는 위치)에서 실행해야 합니다. 잡 레지스트리 디렉터리 기본 경로가 프로젝트 루트 하위의 `./.hermes/jobs` 상대 경로를 기준으로 탐색되기 때문입니다.
+> All verification commands below must be executed from the **project root directory** (where the `.hermes/` directory is directly visible). This is because the default job registry path resolved by scripts is relative to the current working directory under `./.hermes/jobs`.
 
-### 검증 테스트 1: 잡 레지스트리 정상 구동 여부
-Python 스크립트 및 venv 라이브러리가 올바르게 로드되는지 확인하기 위해 잡 목록을 조회합니다.
+### Verification Test 1: Registry Script Load Check
+Verify that the Python scripts and virtual environment libraries load correctly by listing jobs:
 
 ```bash
-# 가상환경(.venv) 파이썬 인터프리터를 사용하여 실행
+# Run using the python interpreter in the virtual environment
 .venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py list
 ```
-*   **출력 기대 결과**: 에러 메시지 없이 빈 JSON 배열 `[]` 또는 현재 등록된 pending/running 잡 목록이 성공적으로 출력되어야 합니다.
+*   **Expected Output**: The command should exit successfully and print an empty JSON array `[]` (or a list of pending/running jobs if any exist) without any python traceback errors.
 
-### 검증 테스트 2: MQTT 연결 브로커 핸드셰이크 테스트
-브로커와의 송수신 통신망 상태를 확인하고, 이벤트 생명주기 및 멱등성이 온전히 작동하는지 실측 검증합니다.
+### Verification Test 2: MQTT Broker Connection Handshake Test
+Test the end-to-end communication through the broker to verify that events are published and received correctly:
 
 ```bash
-# 1. 테스트용 임시 잡 등록 및 발급된 8자리 Hex 잡 ID 획득
+# 1. Register a temporary test job and capture its 8-character Hex Job ID
 JID=$(.venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/registry.py register \
   --agent "test-agent" \
   --prompt "Bootstrap check command" \
   --timeout 120)
 echo "Generated Job ID: $JID"
 
-# 2. 획득한 잡 ID에 대해 백그라운드 이벤트 구독기(Subscriber) 구동
+# 2. Run the background event subscriber (Subscriber) for this Job ID
 .venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/job_subscriber.py --job "$JID" &
 
-# 3. 구독자의 MQTT Broker 소켓 연결 및 수신부 초기화 완료를 보장하기 위해 2초 대기
+# 3. Wait 2 seconds to allow the Subscriber to establish its MQTT socket connection
 sleep 2
 
-# 4. 테스트 시작 이벤트 발행 (Subscribe-before-Publish 원칙 준수)
+# 4. Publish a start event (adhering to the Subscribe-before-Publish rule)
 .venv/bin/python3 skills/tmux-agent-orchestrate-delegate-job/scripts/publish_event.py \
   --job "$JID" \
   --event started \
   --detail "Bootstrap MQTT verification connection check"
 
-# 5. 이벤트 수신이 터미널(stdout) 및 .hermes/delegate_job_logs/events.ndjson 로그 파일에 정상 기록되는지 확인
+# 5. Verify that the event is printed to stdout and written to the audit log:
+#    .hermes/delegate_job_logs/events.ndjson
 
-# 6. 검증 완료 후 백그라운드 프로세스 종료 및 테스트 잡 레코드 수동 정리
+# 6. Stop the background subscriber and clean up the test job records
 kill %1
 rm -f ".hermes/jobs/$JID.json" ".hermes/jobs/$JID.lock"
 ```
 
 ---
 
-## 6. 에이전트 온보딩 가이드 (New Agent Onboarding)
+## 6. Onboarding Collaborating Agents (New Agent Onboarding)
 
-본 환경 구축을 무사히 마쳤다면, 협업하는 에이전트는 즉시 프로젝트 루트에 있는 **[AGENT.md](./AGENT.md)** 문서를 읽어야 합니다.
+Once the setup is verified, onboarding agents should immediately read the **[AGENT.md](./AGENT.md)** guidelines in the project root.
 
-해당 문서에는 에이전트가 각 역할(PM, Worker, Reviewer)로 구동될 때 지켜야 할 **수술적 변경 규칙, 교차 검증 통과 규약, Tmux 뷰포트 유실 방지를 위한 스냅샷 패턴** 등이 서술되어 있어 안정적인 멀티 에이전트 워크플로우에 즉시 기여할 수 있도록 돕습니다.
+The guidelines describe essential workflows—such as **surgical change constraints, cross-verification review loops, and pane snapshotting to prevent viewport truncation**—allowing new agents to quickly and safely integrate with the multi-agent workflow.