Alpenj · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/2ARM_ROBOT/README.md b/2ARM_ROBOT/README.md
@@ -6,6 +6,23 @@
 
 [포트폴리오·이력서](https://julianjeonresume.netlify.app/) · [CUSTOM ACT V1 상세](docs/CUSTOM_ACT_V1_KO.md) · [그림·영상](https://julianjeonresume.netlify.app/research/custom-act-v1/) · [이전 조작 연구](docs/RESEARCH_SUMMARY_KO.md) · [실물 검토 브랜치](https://github.com/Alpenj/DAPIER/tree/pro/sweepick-review-20261015/2ARM_ROBOT/sweepick)
 
+
+![CUSTOM ACT V1의 대표 SIM 실행과 손목 RGB 관측](../docs/media/custom-act-sim.gif)
+
+<sub>고정 epoch30 · Test mid00_01 · [원본 영상](https://julianjeonresume.netlify.app/assets/custom-act-v1/sim-test-mid00_01.mp4) · [수집 외형](../docs/media/collection-appearances.png) · [학습 곡선](../docs/media/training-curves.png) · [영상·그림 출처](../docs/media/README.md)</sub>
+
+[핵심 결과](#custom-act-v1-데이터에서-실행까지) · [시스템 구성](#시스템-구성) · [실물 연동](#실물-데이터와-실행기-연동) · [코드 위치](#구성과-코드-위치) · [실행 안내](#실행-안내와-과거-실습) · [문서 목록](docs/README.md)
+
+## 시스템 구성
+
+관측과 행동의 단위·순서·시각을 맞추고, 학습된 정책의 출력을 실행 기록과 대조한다. 아래는 연구와 실행의 역할 구분이다. 검토 브랜치의 실물 실행기와 공개 `main`의 연구 코드는 아래 코드 위치에서 따로 연결한다.
+
+![SWEEPICK 관측·학습·명령·SIM 평가와 실물 연동 구성](../docs/media/sweepick-system.png)
+
+[구성도 소스](../docs/media/sweepick-system.mmd)
+
+이동 베이스의 전면 Astra RGB-D는 Visual SLAM, 작업공간 OS30A RGB-D와 손목 RGB는 조작 관측에 사용한다. 센서의 역할과 관절·좌표 계약을 구분해 연결한다.
+
 ## CUSTOM ACT V1: 데이터에서 실행까지
 
 학습 손실만으로 로봇의 작업 완료를 판단하기 어려웠다. 시연을 어떤 기준으로 나누었는지, 정책이 어떤 관측을 받는지, 예측한 행동 청크가 실제 명령으로 어떻게 이어지는지를 함께 기록했다.
@@ -14,11 +31,18 @@
 |---|---|---|
 | 데이터 수집 | 원본 113개 궤적의 동작을 유지하며 손목 RGB의 물체색·배경·테이블 텍스처·조명을 5개 외형으로 구성. 관측·상태·명령·시각 정합 확인 | 565개 뷰. 궤적 train/val/test=59/29/25, 뷰=295/145/125. 같은 궤적의 외형은 동일 분할 유지 |
 | 학습 | 양손목 RGB·head PCD·관절 상태를 입력으로 사용하는 ACT 학습 | 200 epoch 완료. best validation은 epoch103, prior normalized L1=0.01553 |
-| 추론 | 별도로 고정한 epoch30 체크포인트, temporal ensemble ON(k=0.01)으로 SIM 폐루프 평가 | 143개 위치 각 1회 중 132회 완료(92.3%). Test 위치는 27/31(87.1%) |
+| 추론 | 별도로 고정한 epoch30 체크포인트, temporal ensemble ON(k=0.01)으로 SIM 폐루프 평가 | 143개 위치 각 1회, 132/143 완료(92.3%). Test 위치는 27/31(87.1%) |
 | 분석 | 예측 청크의 target 시점·가중치·관절 명령·실측값·phase·영상 연결 | 실패 11회 중 grasp/lift 7회, stow 4회. 청크 집계 결과를 저장 CSV에서 재구성해 확인 |
 
 폐루프 완료 기준은 **30 mm 이상 Lift → Stow → 물리 2초 Hold**다. 외형은 랜덤화하고 물체 크기(40 mm)·yaw·물성·카메라 보정은 고정했다. 위 92.3%는 이 SIM 조작 평가의 관측값이다. 200 epoch 최종 모델의 폐루프 결과, 실물 성공률이나 전체 청소 시나리오 성공률과 합산하지 않는다.
 
+
+## 실패를 조사한 방법
+
+학습 손실과 작업 완료를 따로 확인했다. 고정 epoch30 SIM 평가에서 완료하지 못한 11회는 grasp/lift 7회와 stow 4회로 나눴다. 예측값만 보고 원인을 정하지 않고 query·target 시점, 집계 가중치, 실제 전송 명령, 실측 관절과 영상을 같은 시간축에서 읽었다.
+
+기존 first-action-only 실행과 temporal ensemble의 차이도 저장 CSV로 재구성했다. 한 위치의 ON/OFF 비교와 저장 데이터의 정합성 검사는 전체 성능 향상이나 새 실물 성공률로 계산하지 않았다. [청크 집계와 비교 조건](docs/CUSTOM_ACT_V1_KO.md#4-분석--예측-청크가-명령이-되는-과정을-추적했다)에 검사 수치와 한계를 남겼다.
+
 ## 실물 데이터와 실행기 연동
 
 | 트랙 | 확인된 결과 | 지표의 의미 |
@@ -30,7 +54,7 @@
 
 10/08의 첫 무인 왼팔 집기, 10/18~23의 약170회 자동 교사 실행, 10/23의 ACT 접근 뒤 교사 마무리 기록은 위 후속 실험에 이르는 개발 이력이다. 10/26까지의 TJJ 실물 기록에서 ACT 단독 집기 완료는 관찰되지 않았다. 신규 CUSTOM ACT V1 SIM 폐루프 완료와 이 실물 기록을 혼동하지 않는다.
 
-10/27의 새 IR2 정지 shadow는 양팔 각300 prefix를 30초 동안 확인했고 위반0·모터쓰기0이었다. 기록상 full180s=false/all_pass=false이므로 전체 검증 통과로 표시하지 않는다. 최신 후속 노트3개는 [연구 노트 입구](https://www.notion.so/4065788b5ed1810aaec9c710b0d9e288)(접근 권한 필요)에서 연결한다.
+10/27의 새 IR2 정지 shadow는 양팔 각300 prefix를 30초 동안 확인했고 위반0·모터쓰기0이었다. 기록상 full180s=false/all_pass=false이므로 전체 검증 통과로 표시하지 않는다. 공개 가능한 조건과 후속 요약은 [CUSTOM ACT V1 실물 연동 기록](docs/CUSTOM_ACT_V1_KO.md#실물-연동과-후속-기록)에 모았다.
 
 10/16 이후 상체 실행기는 이동 베이스를 직접 움직이지 않고 정지 요청을 전달한다. 모듈을 나눈 실행 구조는 본인의 Visual SLAM 직접 설계·구현 경험을 축소하는 의미가 아니다. 이동·도킹 공동 코드의 출처와 변경 이력도 유지한다.
 
@@ -76,4 +100,4 @@ PR 상태 확인일은 2026-10-08이다. 연구 PR을 닫은 것과 `main`에
 
 외부 라이브러리와 자산은 각 폴더의 출처·라이선스를 따른다. Visual SLAM의 직접 설계·구현 경험과 공동 저장소의 외부·팀 기여 이력을 함께 보존한다.
 
-문서 갱신: 2026-10-27. 새 CUSTOM ACT V1의 수집·학습·SIM 평가·분석을 추가하고 기존 실물·코드·후보 PR 기록은 보존했다. 런타임·물리 파라미터·보정값·테스트·의존성은 변경하지 않았다.
+문서 구성 갱신: 2026-10-28. 실험 기록 기준: 2026-10-27. 새 CUSTOM ACT V1의 수집·학습·SIM 평가·분석을 추가하고 기존 실물·코드·후보 PR 기록은 보존했다. 런타임·물리 파라미터·보정값·테스트·의존성은 변경하지 않았다.
diff --git a/2ARM_ROBOT/docs/CUSTOM_ACT_V1_KO.md b/2ARM_ROBOT/docs/CUSTOM_ACT_V1_KO.md
@@ -4,7 +4,7 @@ SWEEPICK에서 학습 정책을 적용할 때, 낮은 예측 손실만으로는
 
 **ACT는 팀원과 공동 개발·검증했다. 전형주 주 담당은 모방학습·시뮬레이션·Sim-to-Real·데이터 검증이며, Visual SLAM도 직접 설계·구현했다.** 아래 ACT 수치는 공동 실험 결과다. 개인 담당 경험과 연결해 설명하되, 외부 ACT·RoboTwin 구현과 팀 기여의 출처도 함께 남긴다.
 
-[프로젝트](../README.md) · [그림·영상으로 보기](https://julianjeonresume.netlify.app/research/custom-act-v1/) · [Notion 연구 노트](https://www.notion.so/4065788b5ed1810aaec9c710b0d9e288)(접근 권한 필요) · [이전 접촉·계획 연구](RESEARCH_SUMMARY_KO.md)
+[프로젝트](../README.md) · [그림·영상으로 보기](https://julianjeonresume.netlify.app/research/custom-act-v1/) · [공개 후속 요약](#실물-연동과-후속-기록)(접근 권한 필요) · [이전 접촉·계획 연구](RESEARCH_SUMMARY_KO.md)
 
 ## 1. 데이터 수집 — 동작을 보존하고 외형을 바꿨다
 
@@ -19,7 +19,7 @@ SWEEPICK에서 학습 정책을 적용할 때, 낮은 예측 손실만으로는
 
 관절 상태·명령·시각·물체 pose와 head depth/PCD가 같은지 검사했다. 한 궤적의 외형 변형은 같은 분할에 묶어, 같은 동작이 학습과 평가에 나뉘어 들어가지 않게 했다. 정책 입력은 관절q·head PCD·양손목 RGB이며, 정답 행동·phase·물체 정답pose를 추론 입력에서 제외했다.
 
-![동일 궤적의 다섯 외형](https://julianjeonresume.netlify.app/assets/custom-act-v1/collection-appearances.png)
+![동일 궤적의 다섯 외형](../../docs/media/collection-appearances.png)
 
 ## 2. 학습 — 학습 곡선과 작업 완료를 따로 확인했다
 
@@ -32,7 +32,7 @@ shared wrist ResNet18+1×1 projection, hidden256, chunk20, state/action12, KL10,
 
 최저 검증 손실은 epoch103에서 나왔다. 이200 epoch 실행의 최종·best 모델은 원본 묶음에서 폐루프 평가되지 않았다. 다음 절의 작업 완료율은 별도로 고정한 epoch30 체크포인트의 결과다.
 
-![학습·검증 손실과 재개 구간](https://julianjeonresume.netlify.app/assets/custom-act-v1/training-curves.png)
+![학습·검증 손실과 재개 구간](../../docs/media/training-curves.png)
 
 ## 3. 추론 — 고정한 모델로143개 위치를 실행했다
 
@@ -70,9 +70,7 @@ SWEEPICK의 물체 이동·청소·저전력 복귀·도킹·충전 흐름은
 
 10/27 후속 노트는 ACT30과 실물 실행기의 관측·12축 절대행동 계약, 앙상블·STOP·feedback·파지 증거 경로를 정리한다. 저장 앙상블 비교와 코드 검사는 새 실물 파지 결과가 아니다. 새IR2는30초 정지 shadow, 양팔 각300 prefix, 위반0·모터쓰기0이며 full180s=false/all_pass=false다. 이전180초 G4 UNKNOWN 기록도 그대로 보존한다.
 
-- [SIM+실물 공동 학습·실행기 정합](https://www.notion.so/4065788b5ed1818f9df0dd925ddecff4)
-- [절대행동·STOP·feedback·파지 증거 경로](https://www.notion.so/4065788b5ed18153ba4cde8a49e0c1f1)
-- [IR2 정지 shadow 읽기 기록](https://www.notion.so/4065788b5ed181329e50ed6501a5942a)
+공개 후속 요약은 위 기록과 [프로젝트의 실물 트랙](../README.md#실물-데이터와-실행기-연동)에서 읽을 수 있다. 비공개 원본 노트의 주소·원시 로그·개인 장치 정보는 공개하지 않는다.
 
 ## 출처와 재검증 범위
 
@@ -87,3 +85,5 @@ SWEEPICK의 물체 이동·청소·저전력 복귀·도킹·충전 흐름은
 공개 CSV·JSON은 평가 조건과 결과에 필요한 필드만 골랐다. 원시 데이터·학습 tensor·개인 장치 경로는 포함하지 않는다. 공식 ACT/RoboTwin 등 외부 구현의 출처·라이선스는 기존 코드와 원자료에 따른다. 이 문서는 담당 경험과 프로젝트 실험을 연결한 연구 요약이며 공동 데이터·외부 라이브러리 전체의 단독 저작을 주장하지 않는다.
 
 갱신2026-10-27. 저장 기록을 재계산·대조했으며, 이 문서 작업 중 시뮬레이터나 실물 로봇을 새로 실행하지 않았다.
+
+문서 연결 정리: 2026-10-28. 위 실험 기록의 기준일과 결과는 유지했다.
diff --git a/2ARM_ROBOT/docs/README.md b/2ARM_ROBOT/docs/README.md
@@ -1,10 +1,25 @@
-# 프로젝트 문서
+# SWEEPICK 문서 안내
 
-현재 실물 정본은 SO-101 양팔 + TurtleBot3 Waffle Pi + H201 top-view + 전면 Astra S + 좌우
-wrist RGB다. 장치명·역할·stable alias는 [`../config/hardware_roles.json`](../config/hardware_roles.json),
-현재 MuJoCo 실행은 [`../sim/mobile_dual_so101/README.md`](../sim/mobile_dual_so101/README.md)를
-우선한다. 제목에 JDcobot이 있거나 2026-08의 Astra Pro 단일 카메라를 전제로 한 문서는 초기
-연구·회귀 자료이며 현재 실물 명령 근거가 아니다.
+처음 읽는다면 최신 요약에서 시작한 뒤, 확인하려는 코드와 실험의 날짜로 내려간다. 아래 과거 문서는 당시 장비·소스 revision의 기록으로 보존한다.
+
+## 지금 읽을 문서
+
+| 질문 | 문서·근거 |
+|---|---|
+| 어떤 로봇이고 무엇을 담당했는가? | [SWEEPICK 개요·구성·기여](../README.md) |
+| 데이터를 어떻게 나누고 ACT를 평가했는가? | [CUSTOM ACT V1](CUSTOM_ACT_V1_KO.md) |
+| 실제 143개 위치 결과를 볼 수 있는가? | [위치별 CSV](evidence/custom_act_v1_20261027_positions.csv) · [조건·집계 JSON](evidence/custom_act_v1_20261027_summary.json) |
+| 모델·접촉·경로 검증은 어디에 있는가? | [이전 조작 연구와 고정 후보](RESEARCH_SUMMARY_KO.md) |
+| Python 연구와 C++ 실행 경계는 무엇인가? | [연구 계층](../research/README.md) · [제어 계약](../../contracts/README.md) |
+| 교육 코드부터 읽으려면? | [교육·실습 안내](../../docs/LEARNING_GUIDE_KO.md) |
+
+## 장비 구성과 날짜
+
+최근 조작 연구는 **SO-101 양팔·PGripper, 작업공간 OS30A RGB-D와 양손목 RGB**, 이동 베이스 전면 중앙의 **Astra RGB-D**를 구분한다. [프로젝트의 장비 설명](../README.md#장비-역할과-과거-설정)을 먼저 읽는다.
+
+[`hardware_roles.json`](../config/hardware_roles.json)의 `effective_date=2026-09-03`과 H201 top-view는 **당시 구성**이다. 이전 Astra Pro 단일 카메라, JDcobot, 박스·신발 과제 문서도 현재 설정으로 바꿔 읽지 않는다. 문서를 최신화했다고 런타임·보정값이 갱신된 것은 아니다.
+
+## 이전 설계·실습·연구 기록
 
 - [`requirements-ledger.md`](requirements-ledger.md): 현재 확정·미확정 요구사항 원장
 - [`PHASE0_HANDOFF.md`](PHASE0_HANDOFF.md): Ubuntu ROS 2 PC 개발 인수인계
@@ -34,5 +49,5 @@ wrist RGB다. 장치명·역할·stable alias는 [`../config/hardware_roles.json
 - [`2026-09-04-depth-box-pregrasp.md`](2026-09-04-depth-box-pregrasp.md): H201 depth 박스 pose, 앞날개 오른팔 IK·손목 RGB 보정, teleop→ACT episode 검증 기록
 - [`research/MOBILE_DUAL_SO101_EXECUTION_LEDGER_20260902.md`](research/MOBILE_DUAL_SO101_EXECUTION_LEDGER_20260902.md): PR #40을 고정한 뒤 별도 브랜치에서 진행하는 양팔 박스·신발 미션의 단계별 구현·검증·학습 원장
 
-팀의 현재 결정은 `ACT baseline + DYNA-lite + 4주차 이후 보조학습
+아래 문서 작성 당시의 팀 결정은 `ACT baseline + DYNA-lite + 4주차 이후 보조학습
 go/no-go`다. 조사 참고자료의 전체 SLIM/DYNA 구성을 무조건 적용하지 않는다.
diff --git a/2ARM_ROBOT/research/README.md b/2ARM_ROBOT/research/README.md
@@ -21,6 +21,18 @@ sequence, TTL, limit, interlock과 실행 허가를 다시 검사한다.
 남긴 `source_monotonic_ns`는 trace용이고, C++ 수신기가 자신의 monotonic clock으로
 `ttl_ns`를 시작한다.
 
+## 읽는 순서
+
+| 순서 | 코드 | 확인할 내용 |
+|---|---|---|
+| 1 | [관측 출처](src/dapier_research/observation_contract.py) | 실제 센서 관측과 시뮬레이터 정답을 구분하는 경계 |
+| 2 | [깊이 기반 목표](src/dapier_research/vision_target.py) | 깊이·카메라 내부 파라미터·좌표 변환으로 목표 계산 |
+| 3 | [제어 제안](src/dapier_research/control_intent.py) | 관절 명령의 형태·시간·단위와 실행 권한 구분 |
+| 4 | [지역화 replay](src/dapier_research/localization_replay.py) | 누락·지연·재지역화 때 멈춤과 재계획 판단 |
+| 5 | [테스트](test/) | 장비 없는 입력·실패 조건 검사 |
+
+[SWEEPICK 전체 구성](../README.md) · [CUSTOM ACT V1 결과](../docs/CUSTOM_ACT_V1_KO.md) · [교육·실습 안내](../../docs/LEARNING_GUIDE_KO.md)
+
 ## RGB-D target geometry
 
 [`vision_target.py`](src/dapier_research/vision_target.py)는 detector mask와 aligned