refactor: move gRPC_Based_Interface/ into docs/ and add new docs

docs/gRPC_Based_Interface/USECASES.md

@@ -25,7 +25,7 @@
 
 이 3-tier 사이를 관통하는 에이전트 간 통신은 같은 머신 위의 함수 호출이 아니라 **상이한 운영체제·언어·전력·연결성을 가진 원격 디바이스들 사이의 다중 홉 프로토콜** 이다. 본 연구는 엣지 AIoT 시나리오에서 gRPC가 어느 tier 사이에서 가장 효과적이고, 어느 tier에서는 별도 보완이 필요한지를 4대 사용 사례와 함께 분석한다.
 
-![Figure 1. 엣지 AIoT 3-tier 물리적 분산 구조 — 자원/네트워크/보안 강도 비교|739](fig1_three_tier.svg)
+![Figure 1. 엣지 AIoT 3-tier 물리적 분산 구조 — 자원/네트워크/보안 강도 비교|739](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/fig1_three_tier.svg)
 
 ---
 
@@ -48,7 +48,7 @@
 
 엣지 AIoT의 3-tier 분산 구조 위에서 동작하는 4대 대표 사용 사례는 다음과 같다. 각 사례는 **자신만의 디바이스 조합·통신 요구·제약**을 갖는다.
 
-![Figure 2. 엣지 AIoT 4대 사용 사례 콜라주 — Smart Factory, Smart Building, V2X, Healthcare](edge_aiot_usecases_overview.png)
+![Figure 2. 엣지 AIoT 4대 사용 사례 콜라주 — Smart Factory, Smart Building, V2X, Healthcare](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/edge_aiot_usecases_overview.png)
 
 ### 사례 ① 스마트 팩토리 (Industry 4.0)
 **배치**: T1(중앙 PM·품질분석·예지정비 에이전트) ↔ T2(엣지 컨트롤러, 라인별) ↔ T3(다수 AGV·협동로봇·CCTV·진동 센서).
@@ -60,7 +60,7 @@
 | T3 센서 ↔ T2 | 텔레메트리 다수 팬인 | 동시 10k 노드, 1Hz/노드 |
 | T3 로봇 ↔ T1 (직접) | OTA 펌웨어, 원격 진단 | 결함 내성 다운로드 |
 
-![Figure 3. 스마트 팩토리 — 3-tier vertical 협업, gRPC Bidi 합의 + MQTT fan-in](smart_factory_aiot.png)
+![Figure 3. 스마트 팩토리 — 3-tier vertical 협업, gRPC Bidi 합의 + MQTT fan-in](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/smart_factory_aiot.png)
 
 ### 사례 ② 스마트 빌딩 / 스마트 그리드 / 에너지
 **배치**: T1(빌딩 에너지 최적화·DR 에이전트) ↔ T2(빌딩별 또는 변전소별 엣지) ↔ T3(수만 개의 HVAC·조명·PV 인버터·스마트 미터).
@@ -69,7 +69,7 @@
 - **T2 ↔ T1**: 비-실시간 분석·명령下发, 4G/유선
 - **엣지-로컬 합의**: 빌딩 내 HVAC 협업(피크 절감), < 100ms 응답
 
-![Figure 4. 스마트 빌딩/에너지 — HVAC·PV·미터의 LoRa·MQTT·gRPC 혼합 통신](smart_building_energy.png)
+![Figure 4. 스마트 빌딩/에너지 — HVAC·PV·미터의 LoRa·MQTT·gRPC 혼합 통신](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/smart_building_energy.png)
 
 ### 사례 ③ 커넥티드 차량 / V2X
 **배치**: T1(클라우드 텔레매틱스·HD맵·원격 진단) ↔ T2(RSU·로드사이드 유닛·5G MEC) ↔ T3(차량 내 ECU·레이더·카메라).
@@ -85,7 +85,7 @@
 - **T2 ↔ T1**: 일간 업로드, 비실시간
 - **긴급 이벤트**: 부정맥·낙상 감지 시 < 1s T1 알림
 
-![Figure 5. 헬스케어/원격 모니터링 — 환자 웨어러블·병원 엣지·EHR 클라우드 워크플로우](healthcare_aiot.png)
+![Figure 5. 헬스케어/원격 모니터링 — 환자 웨어러블·병원 엣지·EHR 클라우드 워크플로우](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/healthcare_aiot.png)
 
 **공통 통신 요구 5가지**: ① 타입 안전 ② 단방향·양방향 스트리밍 ③ 단절·핸드오버 내성 ④ 디바이스 attestation ⑤ 광역 관측성. 단 4가지 사례는 **각각 다른 우선순위**를 가진다.
 
@@ -104,7 +104,7 @@
 
 **직렬화 포맷 정량 비교** (예시적 추정치)¹:
 
-![Figure 10. gRPC vs REST 정량 비교 — 페이로드 크기 및 CPU 파싱 시간|942](fig6_benchmark.svg)
+![Figure 10. gRPC vs REST 정량 비교 — 페이로드 크기 및 CPU 파싱 시간|942](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/fig6_benchmark.svg)
 
 ¹ Illustrative Estimates. 페이로드 복잡도·라이브러리 버전·런타임 구현에 따라 변동.
 
@@ -140,7 +140,7 @@
 | **Client Streaming** | T3 → T2 다수 센서 배치 업로드, OTA 펌웨어 청크 |
 | **Bidi Streaming** | T2↔T2 엣지 합의, T3↔T2 차량/로봇 실시간 협업 |
 
-![Figure 6. gRPC 4대 RPC 모드 — Unary / Server / Client / Bidi Streaming의 엣지 AIoT 매핑|942](fig3_rpc_modes.svg)
+![Figure 6. gRPC 4대 RPC 모드 — Unary / Server / Client / Bidi Streaming의 엣지 AIoT 매핑|942](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/fig3_rpc_modes.svg)
 
 ### 5.3 엣지 AIoT 환경에서의 약점과 보완 패턴
 
@@ -159,7 +159,7 @@
 
 본 절은 본 연구의 핵심 제안인 **2-tier 프로토콜 아키텍처** 를 제시한다. 단일 프로토콜이 아닌 **tier별 최적 프로토콜을 혼용**하고, T2 엣지 게이트웨이가 변환·집계·인증을 책임지는 구조다.
 
-![Figure 7. 2-tier 프로토콜 아키텍처 — T1↔T2 gRPC/QUIC, T2↔T3 MQTT/CoAP/C-V2X, T2 게이트웨이 6대 책임|933](fig2_two_tier_protocol.svg)
+![Figure 7. 2-tier 프로토콜 아키텍처 — T1↔T2 gRPC/QUIC, T2↔T3 MQTT/CoAP/C-V2X, T2 게이트웨이 6대 책임|933](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/fig2_two_tier_protocol.svg)
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
@@ -222,7 +222,7 @@ T1↔T2 무선 구간에서 송신 측 버퍼가 차면 `WINDOW_SIZE=0` 프레
 
 T3↔T2↔T1의 텔레메트리 스트리밍(사례 ①②④)이 중간에 끊기면, gRPC 서버는 **Resume Token**(마지막 전송 위치)을 발급한다. 클라이언트는 재연결 시 `Resume-Token` Metadata를 첨부해 이어받는다. 이 패턴은 gRPC Interceptor에 캡슐화되어 모바일·엣지·MCU의 일시 단절을 흡수한다.
 
-![Figure 8. Resume Token 시퀀스 — T3/T2 단절-재접속 시 스트리밍 위치 보존|942](fig5_resume_token.svg)
+![Figure 8. Resume Token 시퀀스 — T3/T2 단절-재접속 시 스트리밍 위치 보존|942](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/fig5_resume_token.svg)
 
 ### 7.4 명시적 Deadline
 T3 디바이스는 네트워크 품질을 신뢰할 수 없다. `ClientContext`에 `Deadline`을 인터셉터에서 강제 주입해 단절 시 무한 대기를 방지한다. 디바이스 클래스별 기본 deadline 정책을 다르게 적용한다(예: AGV V2V 50ms, IoT 텔레메트리 5s).
@@ -241,7 +241,7 @@ gRPC TLS 핸드셰이크 시 SAN의 SPIFFE ID를 즉시 확인해 비인가 디
 
 ### 8.2 2계층 통신 제어: Service Mesh + Interceptor
 
-![Figure 9. 2계층 통신 제어 — Service Mesh(인프라) + gRPC Interceptor(앱) 관심사 분리|942](fig4_two_layer_governance.svg)
+![Figure 9. 2계층 통신 제어 — Service Mesh(인프라) + gRPC Interceptor(앱) 관심사 분리|942](lab/canary_projects/multi-agent-paper/docs/gRPC_Based_Interface/figures/fig4_two_layer_governance.svg)
 
 | 계층 | 통제 항목 | 엣지 AIoT 적용 |
 |------|----------|----------------|

docs/herdr_manual/herdr_guide.md

@@ -0,0 +1,127 @@
+# Herdr 사용 가이드
+
+## 소개
+
+Herdr는 "코딩 에이전트를 위한 tmux"라고 볼 수 있는 터미널 워크스페이스 매니저(agent multiplexer)입니다. 여러 AI 코딩 에이전트(Claude Code, Codex 등)를 각각 실제 터미널 pane에서 실행하면서, 어떤 에이전트가 작업 중인지 / 입력을 기다리는지(blocked) / 끝났는지를 사이드바에서 한눈에 확인할 수 있고, detach해도 백그라운드에서 계속 실행됩니다. Rust로 작성된 로컬 바이너리이며 별도의 GUI 앱이나 클라우드 계정이 필요 없습니다.
+
+공식 사이트: [herdr.dev](https://herdr.dev)
+
+## 주요 사용사례
+
+- 여러 에이전트를 동시에 병렬로 실행하며 상태만 사이드바에서 훑어보기
+- SSH나 휴대폰으로 원격 접속해 백그라운드 세션에 이어 붙기 (detach/reattach)
+- 소켓 API/CLI로 스크립트나 다른 에이전트(오케스트레이터)가 에이전트에 명령을 넣고 결과를 읽어오는 자동화
+- 서버 재시작 후에도 에이전트 네이티브 세션을 복원해서 이어가기 (Claude Code, Codex 등 통합 시)
+- 하나의 워크스페이스(프로젝트) 안에서 여러 개의 서로 다른 workspace/session으로 완전히 격리된 작업 공간 운용
+
+## 개념 정리
+
+| 개념 | 설명 |
+|---|---|
+| Session | 지속되는 Herdr 서버 하나(런타임 인스턴스). `herdr`는 기본 세션에 붙고, `herdr --session <name>`으로 named session을 launch-or-attach 할 수 있음 |
+| Workspace | 세션 안의 최상위 프로젝트 컨테이너. 보통 repo/작업 단위로 하나씩 |
+| Tab | workspace 안의 레이아웃 |
+| Pane | 실제 터미널 하나 |
+| Agent | Herdr가 pane 안에서 인식하는 프로세스 (Claude Code, Codex 등). 상태: blocked/working/done/idle/unknown |
+| Channel | Herdr 바이너리 자체의 업데이트 트랙 (stable/preview) — session과 무관한 별개 개념 |
+
+## 주요 단축키
+
+prefix 키 기본값은 `ctrl+b`. `prefix+?`로 언제든 전체 목록 확인 가능.
+
+가장 먼저 배울 5가지:
+
+| 동작 | 키 |
+|---|---|
+| 새 탭 | `prefix+c` |
+| 좌우/상하 분할 | `prefix+v` / `prefix+minus` |
+| 패널 이동 | `prefix+h/j/k/l` |
+| 워크스페이스 탐색 | `prefix+w` |
+| detach (세션 유지) | `prefix+q` |
+
+추가 자주 쓰는 것:
+
+| 동작 | 키 |
+|---|---|
+| 패널 확대(zoom) | `prefix+z` |
+| 패널 닫기 | `prefix+x` |
+| 카피 모드 | `prefix+[` |
+| 다음/이전 탭 | `prefix+n` / `prefix+p` |
+| 새 워크스페이스 | `prefix+shift+n` |
+| 사이드바 토글 | `prefix+b` |
+
+마우스만으로도 클릭/드래그/우클릭 메뉴로 대부분 조작 가능 (mouse-native).
+
+## 실습: 세션 생성 → Claude 실행 → 소켓으로 프롬프트 전달 → 결과 확인
+
+### 1. 현재 디렉터리를 cwd로 하는 새 세션 `new_session` 생성
+
+```bash
+cd <현재 작업 디렉터리>
+herdr --session new_session
+```
+
+Herdr의 세션은 launch-or-attach 모델이라 이 한 줄로 세션이 없으면 생성하고 동시에 attach까지 됩니다.
+
+### 2. 생성된 세션에서 Claude 실행
+
+attach된 pane 안에서:
+
+```bash
+claude
+```
+
+(테스트용으로 권한 프롬프트를 건너뛰려면 `claude --dangerously-skip-permissions`. 신뢰된 환경에서만 사용 권장.)
+
+### 3. 다른 터미널에서 herdr 명령으로 프롬프트 전달 (직접 타이핑 아님)
+
+새 터미널에서 에이전트 목록과 pane_id 확인:
+
+```bash
+herdr --session new_session agent list
+herdr --session new_session agent get claude
+```
+
+텍스트 입력 + Enter 제출을 원자적으로 수행:
+
+```bash
+herdr --session new_session pane run <pane_id> "정렬 프로그램을 작성해줘"
+```
+
+### 4. Claude의 결과 화면 출력
+
+완료될 때까지 기다렸다가 읽기:
+
+```bash
+herdr --session new_session wait agent-status <pane_id> --status idle
+herdr --session new_session pane read <pane_id> --source recent --lines 150
+```
+
+현재 화면만 바로 보기:
+
+```bash
+herdr --session new_session pane read <pane_id> --source visible --lines 80
+```
+
+`--session new_session`을 매번 붙이는 대신 `export HERDR_SESSION=new_session`으로 환경변수를 설정하면 이후 명령에서 생략 가능합니다.
+
+## 참고: 다중 workspace 간 에이전트 제어
+
+Herdr의 소켓 API/CLI는 workspace 단위로 격리되지 않고 세션 전체가 하나의 소켓을 공유합니다. `pane_id`가 `w1:p1` 같은 전역 ID라서, 지금 어느 workspace에 있든 다른 workspace의 에이전트를 `agent send`, `agent read`, `wait agent-status`, `pane run` 등으로 그대로 제어할 수 있습니다.
+
+```bash
+herdr workspace create --cwd ~/project --label claude-test
+herdr workspace list                      # 방금 만든 workspace_id 확인
+herdr agent start claude-test --workspace <workspace_id> -- claude
+herdr agent send claude-test "테스트"
+herdr wait agent-status claude-test --status idle
+```
+
+## 출처
+
+- [herdr.dev/docs](https://herdr.dev/docs/)
+- [herdr.dev/docs/cli-reference](https://herdr.dev/docs/cli-reference/)
+- [herdr.dev/docs/socket-api](https://herdr.dev/docs/socket-api/)
+- [herdr.dev/docs/keyboard](https://herdr.dev/docs/keyboard/)
+- [herdr.dev/docs/agents](https://herdr.dev/docs/agents/)
+- [herdr.dev/docs/persistence-remote](https://herdr.dev/docs/persistence-remote/)