docs: architecture/tech-stack/conventions 전면 재작성 + Wiki 동기화

.agents/references/architecture.md

@@ -2,58 +2,279 @@
 
 > AI 에이전트는 구현 전 이 문서를 반드시 확인합니다.
 
-## 프로젝트 개요
+## 1. 프로젝트 개요
 
-Antigravity AI 코딩 에이전트의 Discord 연동 시스템.
+**Gravity Control**은 Antigravity AI 코딩 에이전트와 Discord를 실시간으로 연결하는 브릿지 시스템이다.
-- AG Extension ↔ WebSocket Hub ↔ Discord Bot (실시간)
-- AG Extension ↔ 파일 bridge ↔ Collector ↔ Gateway ↔ Discord Bot (레거시)
 
-## 디렉토리 구조
+### 핵심 목적
+- AI 에이전트의 **승인 요청**(코드 실행, 파일 수정 등)을 Discord로 전달하고 사용자 응답을 반환
+- AI 에이전트의 **작업 스냅샷**(대화 요약, 진행 상황)을 Discord에 실시간 표시
+- **코드 리뷰**(diff review) accept/reject을 Discord에서 처리
+- 사용자의 Discord **명령어**(!approve, !reject, !auto 등)를 AG Extension으로 전달
+- **Auto-approve 모드**로 무인 작업 지원
+
+### 시스템 구성
+
+```
+┌────────────────┐     WebSocket     ┌──────────────┐     Discord API     ┌─────────┐
+│  VS Code       │◄──────────────────►│  Hub Server  │◄───────────────────►│ Discord │
+│  AG Extension  │   type:auth/chat   │  (hub.py +   │   discord.py bot    │ 서버    │
+│  (TypeScript)  │   /pending/resp    │   gateway.py)│                     │         │
+└────────────────┘                    └──────────────┘                     └─────────┘
+    ↕ AG SDK (RPC)                         ↕
+┌────────────────┐                    ┌──────────────┐
+│  Antigravity   │                    │  파일 bridge  │ ← 레거시 fallback
+│  AI Engine     │                    │  (bridge.py)  │   (WS 미사용 시)
+└────────────────┘                    └──────────────┘
+```
+
+---
+
+## 2. 디렉토리 구조
 
 ```
 gravity_control/
-├── auth.py              # JWT 토큰 관리
+├── main.py                  # 진입점: Bot + Hub + Watcher 통합 시작
-├── hub.py               # WebSocket Hub (메시지 라우팅, 인스턴스 관리)
+├── config.py                # 환경변수 + .env 로드 (66줄)
-├── bot.py               # Discord 봇 (승인 UI, 채널 관리, Hub 핸들러)
+│
-├── gateway.py           # HTTP REST + /ws endpoint
+├── ── 서버 측 (Python) ──
-├── bridge.py            # 파일 기반 IPC (레거시)
+├── bot.py                   # Discord 봇: 승인 UI, 채널 관리, Hub 핸들러 (1,286줄)
-├── collector.py         # 원격 파일→HTTP 릴레이 (Phase 2 삭제 예정)
+├── hub.py                   # WebSocket Hub: 연결 관리, 메시지 라우팅 (580줄)
-├── watcher.py           # Brain 디렉토리 변경 감시
+├── auth.py                  # JWT 토큰 + registration code 인증 (127줄)
-├── config.py            # 환경변수 설정
+├── gateway.py               # HTTP REST API + /ws endpoint (310줄)
-├── main.py              # 진입점 (Bot + Hub + Watcher 시작)
+├── bridge.py                # 파일 기반 IPC (레거시 fallback) (479줄)
-├── parser.py            # Markdown→Discord 파서
+├── watcher.py               # Brain 디렉토리 변경 감시 (290줄)
+├── parser.py                # Markdown → Discord 변환 (245줄)
+├── collector.py             # 원격 파일→HTTP 릴레이 (Phase 2 삭제 예정) (517줄)
+│
+├── ── Extension 측 (TypeScript) ──
 ├── extension/src/
-│   ├── extension.ts     # 메인 Extension (3,300줄, 점진적 모듈화 진행)
+│   ├── extension.ts         # 메인: SDK init, activate, HTTP bridge (1,290줄)
-│   ├── ws-client.ts     # WSBridgeClient (Hub 연결, 재연결, 메시지 큐)
+│   ├── step-probe.ts        # 폴링 + 응답 처리 + 승인 전략 (1,435줄)
-│   └── sdk/             # Antigravity SDK (로컬 임베드)
+│   │                        #   setupMonitor(), processResponseFile(),
-└── .agents/references/  # AI 에이전트 레퍼런스 문서
+│   │                        #   writePendingApproval(), tryApprovalStrategies()
+│   ├── observer-script.ts   # DOM Observer 스크립트 생성 (698줄)
+│   │                        #   generateApprovalObserverScript()
+│   ├── ws-client.ts         # WSBridgeClient: Hub 연결, 재연결, 큐 (505줄)
+│   ├── step-utils.ts        # Step 파싱 순수 함수 4개 (114줄)
+│   │                        #   extractPlannerText, filterEphemeral,
+│   │                        #   extractToolCommand, extractToolDescription
+│   └── sdk/                 # Antigravity SDK 로컬 임베드
+│       ├── index.js         # SDK 런타임 (4,014줄)
+│       └── index.d.ts       # SDK 타입 정의 (2,297줄)
+│
+├── ── 테스트 ──
+├── tests/
+│   ├── test_ws_hub.py       # Hub WS 연결 테스트
+│   └── test_syntax.py       # Python 구문 검증
+│
+├── ── 문서 / 설정 ──
+├── .env                     # 환경변수 (git 제외)
+├── .agents/references/      # AI 에이전트 레퍼런스
+├── docs/devlog/             # 작업 로그
+└── start_bot.bat            # 윈도우용 봇 시작 스크립트
 ```
 
-## 핵심 모듈
+---
 
-| 모듈 | 역할 | 의존성 |
+## 3. 핵심 모듈 상세
-|------|------|--------|
-| hub.py | WS 연결 관리, 메시지 라우팅, 인스턴스 번호 | auth.py |
-| auth.py | JWT 토큰 생성/검증, registration code | - |
-| bot.py | Discord UI, 승인 처리, 채팅 릴레이 | hub.py, bridge.py, parser.py |
-| gateway.py | HTTP REST API + /ws endpoint | hub.py |
-| ws-client.ts | Extension→Hub WS 클라이언트 | - |
-| extension.ts | AG SDK 연동, step 감시, DOM observer | ws-client.ts, sdk/ |
 
-## 데이터 흐름
+### 3.1 Hub (hub.py) — WebSocket 메시지 허브
+
+**역할**: Extension ↔ Bot 간 실시간 양방향 통신 중계
+
+| 기능 | 설명 |
+|------|------|
+| 연결 관리 | 프로젝트별 다중 인스턴스, 인스턴스 번호 자동 부여 |
+| JWT 인증 | registration_code → JWT 발급 → 이후 토큰 재인증 |
+| 메시지 라우팅 | pending, chat, register, auto_resolve, brain_event |
+| 응답 역라우팅 | request_id → pending_owners → 원본 Extension으로 전달 |
+| Rate limiting | per-connection 100msg/10s |
+| Dedup | msg_id 기반 60s TTL 중복 제거 |
+| Heartbeat | 30s 간격 ping/pong |
+
+**프로토콜**:
+```
+1. Client → Server: {type:"auth", registration_code/token, project, pc}
+2. Server → Client: {type:"auth_ok", conn_id, instance_number, session_token}
+3. 양방향 메시지 교환:
+   - Extension→Hub: pending, chat, register, auto_resolve, brain_event
+   - Hub→Extension: response, command, instance_update, error
+```
+
+### 3.2 Auth (auth.py) — 인증 관리
+
+| 기능 | 설명 |
+|------|------|
+| Registration Code | 사전 공유 코드로 최초 인증 |
+| JWT 발급 | HMAC-SHA256, 24시간 유효 |
+| 토큰 검증 | 만료/위조 감지, 프로젝트+PC 메타데이터 포함 |
+
+### 3.3 Bot (bot.py) — Discord 인터페이스
+
+| 기능 | 설명 |
+|------|------|
+| 승인 UI | Approve/Reject 버튼, diff_review Accept/Reject |
+| Auto-approve | `!auto` 토글, 세션 간 초기화 |
+| 채널 관리 | `#ag-{project}` 자동 채널 매칭 |
+| 스냅샷 전달 | 2000자 초과 시 파일 첨부 |
+| 명령어 | !approve, !reject, !auto, !status, !send |
+| Hub 연동 | on_hub_pending, on_hub_chat, on_hub_register 핸들러 |
+| IDLE 알림 | AI step 종료 시 Discord 알림 |
+
+### 3.4 Extension (extension.ts) — VS Code 확장
+
+| 기능 | 설명 |
+|------|------|
+| AG SDK 연동 | getCascadeStatus, getAllTrajectories RPC |
+| 세션 감지 | activeSessionId 자동 추적 |
+| 프로젝트 자동 감지 | git remote URL 기반 |
+| HTTP bridge | 파일 기반 pending/response 읽기쓰기 (레거시) |
+| WS bridge | WSBridgeClient 통한 Hub 연결 (우선) |
+| Status bar | SDK 상태 + 연결 상태 표시 |
+
+### 3.5 Step Probe (step-probe.ts) — 상태 폴링
+
+`BridgeContext` 인터페이스로 extension.ts와 상태 공유:
+
+| 기능 | 설명 |
+|------|------|
+| setupMonitor | 3초 간격 SDK 폴링, 세션/step 변화 감지 |
+| processResponseFile | Discord 응답 → AG RPC 실행 |
+| writePendingApproval | 승인 요청 파일/WS 전송 |
+| tryApprovalStrategies | 다단계 승인: DOM click → VS Code command → RPC |
+| setupResponseWatcher | response/ 디렉토리 파일 감시 |
+
+**BridgeContext 필드** (14개):
+`bridgePath`, `projectName`, `sdk`, `wsBridge`, `logToFile`, `autoApproveEnabled`, `activeSessionId`, `sentPendingIds`, `deterministicPort`, `recentDiscordSentTexts`, `writeChatSnapshot`, `writeChatSnapshotWithFiles`, `workspaceUri`, `diffReviewMetadata`
+
+### 3.6 WS Client (ws-client.ts) — Hub 클라이언트
+
+| 기능 | 설명 |
+|------|------|
+| 연결 관리 | WebSocket + 자동 재연결 |
+| Backoff | 1s→60s 지수 백오프 + ±30% jitter |
+| 메시지 큐 | 200개 버퍼, 재연결 시 자동 flush |
+| Heartbeat | 25s 간격 ping |
+| 인증 | registration_code 또는 session_token |
+| API | sendPending, sendChat, sendRegister, sendAutoResolve |
+
+### 3.7 Observer Script (observer-script.ts)
+
+AG Webview의 DOM을 관찰하여 승인 버튼을 자동 감지/클릭:
+- MutationObserver로 `.actions-container` 감시
+- 버튼 텍스트 매칭으로 Approve/Reject 자동 실행
+- `postMessage`로 Extension과 통신
+
+### 3.8 Step Utils (step-utils.ts)
+
+순수 함수 4개:
+- `extractPlannerText(content)` — AI 응답 텍스트 추출
+- `filterEphemeral(text)` — 시스템 메시지 필터링
+- `extractToolCommand(content)` — 도구 명령어 추출
+- `extractToolDescription(content)` — 도구 설명 추출
+
+---
+
+## 4. 데이터 흐름
+
+### 4.1 승인 요청 플로우
 
 ```
-    [Extension]
+AG Engine → SDK RPC → Extension(step-probe.ts)
-        │
+  → setupMonitor: WAITING step 감지
-   ┌────┴────┐
+  → writePendingApproval: pending 데이터 생성
-   │ WS Hub  │ ← 실시간 (preferred)
+  → [WS] wsBridge.sendPending() → Hub → Bot → Discord (버튼 UI)
-   │ (ws-client.ts → hub.py)
+  → [파일] bridge/pending/{id}.json (fallback)
-   └────┬────┘
-        │                    ┌─────────────┐
-        ├───────────────────→│  Discord Bot │→ Discord
-        │                    └─────────────┘
-   ┌────┴────┐
-   │파일 bridge│ ← 레거시 fallback
-   │(Collector → Gateway)
-   └─────────┘
 ```
+
+### 4.2 승인 응답 플로우
+
+```
+Discord (사용자 버튼 클릭) → Bot
+  → [Hub connected] Hub.route_response() → WS → Extension
+  → [File fallback] bridge/response/{id}.json → setupResponseWatcher
+  → processResponseFile → tryApprovalStrategies
+     1차: DOM observer script (webview inject)
+     2차: VS Code command (cascade.approveCurrentStep)
+     3차: Direct RPC (acknowledgeCodeActionStep)
+```
+
+### 4.3 채팅 스냅샷 플로우
+
+```
+Extension(step-probe.ts) → 새 step 텍스트 감지
+  → writeChatSnapshot(text) → truncation + dedup
+  → [WS] wsBridge.sendChat() → Hub → Bot → Discord (#ag-{project})
+  → [파일] bridge/pending/ snapshot 파일 (fallback)
+```
+
+### 4.4 Diff Review 플로우
+
+```
+AG Engine → 파일 수정 → Extension(step-probe.ts)
+  → edit_step_indices + modified_files 메타데이터 수집
+  → writePendingApproval (step_type="diff_review")
+  → Discord (Accept all / Reject all 버튼)
+  → 응답 → acknowledgeCodeActionStep RPC
+```
+
+---
+
+## 5. 통신 프로토콜
+
+### 5.1 WebSocket 메시지 타입
+
+**Extension → Hub (upstream)**:
+
+| type | data 필드 | 설명 |
+|------|-----------|------|
+| `auth` | registration_code/token, project, pc | 최초 인증 |
+| `pending` | request_id, command, description, buttons | 승인 요청 |
+| `chat` | content, attached_files, conversation_id | 채팅 스냅샷 |
+| `register` | conversation_id, project_name | 세션 등록 |
+| `auto_resolve` | request_id | 자동 해결 알림 |
+| `brain_event` | (payload) | 브레인 이벤트 |
+| `heartbeat` | - | 연결 유지 |
+
+**Hub → Extension (downstream)**:
+
+| type | data 필드 | 설명 |
+|------|-----------|------|
+| `auth_ok` | conn_id, instance_number, session_token | 인증 성공 |
+| `auth_fail` | reason | 인증 실패 |
+| `response` | request_id, approved, button_index | 승인 응답 |
+| `command` | text, action | Discord 명령어 |
+| `instance_update` | active_count, instances[] | 인스턴스 변경 |
+| `error` | error | 에러 |
+
+### 5.2 BOT_MODE 동작 차이
+
+| 모드 | Watcher | Hub/Gateway | 용도 |
+|------|---------|-------------|------|
+| `local` | ✅ (brain 감시) | ❌ | 로컬 개발 (Extension과 같은 PC) |
+| `gateway` | ❌ | ✅ (port 8585) | 서버 배포 (WS Hub + Gateway) |
+| `remote` | ✅ | ❌ | 원격 브릿지 (레거시 Collector) |
+
+---
+
+## 6. 보안
+
+| 항목 | 구현 |
+|------|------|
+| WS 인증 | Registration Code → JWT (HMAC-SHA256, 24h) |
+| Gateway API | API Key 헤더 (`X-API-Key`) |
+| Rate limit | per-connection 100msg/10s |
+| 메시지 dedup | msg_id 기반 60s TTL |
+| Discord | Bot 토큰 + Guild ID 제한 |
+
+---
+
+## 7. Extension 설정 (VS Code)
+
+| 설정 키 | 설명 | 기본값 |
+|---------|------|--------|
+| `gravityBridge.bridgePath` | Bridge 디렉토리 경로 | `~/.gemini/antigravity/bridge` |
+| `gravityBridge.projectName` | 프로젝트 이름 | git remote 자동 감지 |
+| `gravityBridge.hubUrl` | WebSocket Hub URL | (비어있으면 WS 비활성) |
+| `gravityBridge.registrationCode` | Hub 등록 코드 | (서버에서 발급) |

.agents/references/conventions.md

@@ -4,20 +4,37 @@
 
 ## 네이밍
 
+### Python (서버)
+
 | 대상 | 규칙 | 예시 |
 |------|------|------|
-| 변수/함수 | camelCase | `getUserData()` |
+| 변수/함수 | snake_case | `write_pending_approval()` |
-| 클래스 | PascalCase | `UserService` |
+| 클래스 | PascalCase | `GravityBot`, `WSHub`, `TokenManager` |
-| 상수 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| 상수 | UPPER_SNAKE_CASE | `MAX_MSG_SIZE`, `HEARTBEAT_INTERVAL` |
-| 파일명 | kebab-case | `user-service.js` |
+| 파일명 | snake_case | `hub.py`, `ws_client.py` |
-| CSS 클래스 | kebab-case | `.nav-header` |
+| 로거명 | 모듈명 | `logging.getLogger("hub")` |
+
+### TypeScript (Extension)
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 변수/함수 | camelCase | `writePendingApproval()`, `setupMonitor()` |
+| 클래스 | PascalCase | `WSBridgeClient` |
+| 인터페이스 | PascalCase | `BridgeContext`, `WSPendingData` |
+| 상수 | UPPER_SNAKE_CASE | `MAX_QUEUE_SIZE`, `AUTH_TIMEOUT` |
+| 파일명 | kebab-case | `ws-client.ts`, `step-probe.ts` |
+| export 함수 | camelCase | `initStepProbe()`, `generateApprovalObserverScript()` |
 
 ## 코드 스타일
 
-- 들여쓰기: (2 spaces / 4 spaces / tab)
+| 항목 | Python | TypeScript |
-- 세미콜론: (사용 / 미사용)
+|------|--------|-----------|
-- 따옴표: (single / double)
+| 들여쓰기 | 4 spaces | 4 spaces |
-- 줄바꿈: LF (Unix style)
+| 따옴표 | 쌍따옴표 `"` (f-string 포함) | 작은따옴표 `'` |
+| 세미콜론 | N/A | 사용 |
+| 줄바꿈 | LF (Unix) | CRLF (Windows, git 자동 변환) |
+| 최대 줄 길이 | 120자 권장 | 120자 권장 |
+| 타입 힌트 | 적극 사용 (`-> list[str]`) | strict (`BridgeContext` 인터페이스) |
 
 ## 커밋 메시지
 
@@ -25,21 +42,50 @@
 <type>(<scope>): <description>
 
 type: feat|fix|refactor|test|docs|chore|ci|infra
-scope: (선택)
+scope: server|extension|hub|bot|gateway|bridge (선택)
 ```
 
 **예시:**
-- `feat(server): add WebSocket reconnection logic`
+- `feat(hub): WebSocket Hub 구현 + JWT 인증`
-- `fix(frontend): resolve button overlap on mobile`
+- `refactor(extension): 모듈 분리 (step-probe, observer-script)`
-- `docs: update API documentation`
+- `fix(bot): auto-approve 세션 간 초기화`
+- `docs: architecture.md 전면 재작성`
+
+관련 Vikunja 태스크가 있으면: `feat(hub): WS Hub 구현 #task-395`
 
 ## 주석
 
 - 한국어/영어 혼용 가능
 - TODO 주석: `// TODO: 설명` 형식
+- 섹션 구분: `// ─── Section Name ───` (TypeScript), `# ─── Section ───` (Python)
 - 복잡한 로직에는 반드시 WHY(왜) 주석 추가
+- 함수 docstring: Python은 `"""..."""`, TypeScript는 `/** ... */`
+
+## 모듈 분리 패턴
+
+Extension 모듈 분리 시 사용하는 패턴:
+
+| 패턴 | 용도 | 예시 |
+|------|------|------|
+| **순수 함수 추출** | 외부 상태 참조 없는 함수 | `step-utils.ts` |
+| **독립 스크립트** | 문자열 반환 함수 | `observer-script.ts` |
+| **Context 패턴** | 공유 상태가 많은 함수 그룹 | `step-probe.ts` (BridgeContext) |
+| **클래스 추출** | 자체 상태 + 메서드 | `ws-client.ts` (WSBridgeClient) |
 
 ## 테스트
 
-- 테스트 파일 위치: (예: `__tests__/` 또는 `*.test.js`)
+| 항목 | 위치 | 도구 |
-- 테스트 네이밍: `should [expected behavior] when [condition]`
+|------|------|------|
+| Python 구문 검사 | `tests/test_syntax.py` | `ast.parse` |
+| WS Hub 연결 | `tests/test_ws_hub.py` | `websockets` |
+| TypeScript 컴파일 | `npx tsc --noEmit` | TypeScript compiler |
+| E2E | 수동 (Discord 버튼 클릭) | — |
+
+## 로깅
+
+| 측 | 방식 | 포맷 |
+|----|------|------|
+| Python | `logging.getLogger(name)` | `YYYY-MM-DD HH:MM:SS [name] LEVEL: message` |
+| Extension | `logToFile(msg)` → bridge/log/ | `[HH:MM:SS] message` + `[WS]` prefix |
+| Hub | `[HUB]` prefix | `[HUB] Auth OK: {conn_id} project={project}` |
+| Gateway | `[GATEWAY]` prefix | `[GATEWAY] HTTP API started on {host}:{port}` |

.agents/references/tech-stack.md

@@ -6,44 +6,94 @@
 
 | 항목 | 버전 | 경로/비고 |
 |------|------|-----------| 
-| Python | 3.x (miniforge3) | `C:\ProgramData\miniforge3\envs\gravity_control\python.exe` |
+| Python | 3.12 (miniforge3) | `C:\ProgramData\miniforge3\envs\gravity_control\python.exe` |
 | Node.js | 시스템 설치 | `node`, `npm` (PowerShell에서 `cmd /c npm` 권장) |
-| TypeScript | (Extension) | `extension/src/extension.ts` → `tsc` 빌드 |
+| TypeScript | 5.3+ | `extension/src/*.ts` → `tsc` → `extension/out/*.js` |
 
 > [!IMPORTANT]
 > Python은 **반드시** 위 miniforge3 경로를 사용. WindowsApps의 python stub은 동작하지 않음.
 
-## 프레임워크
+## 프레임워크 & 라이브러리
 
-| 항목 | 버전 | 용도 |
+### Python (서버)
-|------|------|------|
+
-| discord.py | 2.x | Discord 봇 |
+| 패키지 | 버전 | 용도 |
-| watchdog | - | 파일시스템 감시 |
+|--------|------|------|
-| antigravity-sdk | 로컬 | VS Code Extension SDK 연동 |
+| discord.py | 2.x | Discord 봇 (슬래시 명령, 버튼 UI, 이벤트) |
+| aiohttp | 3.x | Gateway HTTP 서버 + WebSocket endpoint |
+| watchdog | - | Brain 디렉토리 파일시스템 감시 |
+| python-dotenv | - | .env 파일 로드 |
+| PyJWT | - | ❌ 미사용 (자체 HMAC-SHA256 구현) |
+
+### TypeScript (Extension)
+
+| 패키지 | 용도 |
+|--------|------|
+| @types/vscode | VS Code Extension API 타입 |
+| @types/node | Node.js 타입 |
+| typescript | 컴파일러 |
+| antigravity-sdk | AG RPC 호출 (로컬 임베드 `sdk/`) |
 
 ## 패키지 관리
 
-- **Python**: pip (`requirements.txt`)
+| 측 | 도구 | 파일 |
-- **Extension**: npm (`extension/package.json`)
+|----|------|------|
+| Python | pip | `requirements.txt` |
+| Extension | npm | `extension/package.json` |
 
-## 개발 도구
+## 개발 도구 & 명령어
 
-| 도구 | 명령어 |
+| 작업 | 명령어 |
 |------|--------|
-| **봇 실행** | `start_bot.bat` 또는 `C:\ProgramData\miniforge3\envs\gravity_control\python.exe main.py` |
+| **봇 실행** | `C:\ProgramData\miniforge3\envs\gravity_control\python.exe main.py` |
-| **Extension 빌드** | `cd extension && cmd /c npm run compile` |
+| **봇 실행 (gateway)** | `.env`에서 `BOT_MODE=gateway` 설정 후 위 명령 |
-| **Extension VSIX** | `cd extension && cmd /c npx vsce package` |
+| **Extension 구문 검사** | `cd extension && npx tsc --noEmit` |
-| **봇 구문 검사** | `C:\ProgramData\miniforge3\envs\gravity_control\python.exe -c "import bot, bridge, config, main"` |
+| **Extension 컴파일** | `cd extension && cmd /c npm run compile` |
+| **Extension VSIX** | `cd extension && npx @vscode/vsce package --no-dependencies` |
+| **Python 구문 검사** | `python -c "import ast; [ast.parse(open(f).read()) for f in ['bot.py','hub.py',...]]"` |
+| **Hub WS 테스트** | `python tests/test_ws_hub.py` (서버 기동 상태에서) |
 
-## 환경 변수
+## 환경 변수 (.env)
+
+### 필수
 
 | 변수명 | 용도 | 기본값 |
 |--------|------|--------|
 | DISCORD_TOKEN | Discord 봇 토큰 | (필수) |
 | DISCORD_GUILD_ID | Discord 서버 ID | (필수) |
+
+### 선택
+
+| 변수명 | 용도 | 기본값 |
+|--------|------|--------|
 | BRAIN_PATH | AG 브레인 경로 | `~/.gemini/antigravity/brain` |
-| BOT_MODE | 봇 모드 (local/remote/gateway) | `local` |
+| BOT_MODE | `local` / `remote` / `gateway` | `local` |
-| REMOTE_BRIDGE_URL | 원격 브릿지 URL | (remote 모드 전용) |
+| DEBOUNCE_SECONDS | Watcher 디바운스 간격 | `5` |
-| GATEWAY_API_KEY | Gateway REST API 인증 키 | (gateway 모드) |
+| PROJECT_NAME | 프로젝트 이름 | `gravity_control` |
-| GRAVITY_HUB_SECRET | WS Hub JWT 서명 시크릿 | (자동생성 가능) |
+
-| GRAVITY_REGISTRATION_CODE | Extension 등록 코드 | (미설정 시 인증 생략) |
+### Gateway 모드 전용
+
+| 변수명 | 용도 | 기본값 |
+|--------|------|--------|
+| GATEWAY_PORT | Gateway HTTP/WS 포트 | `8585` |
+| GATEWAY_API_KEY | REST API 인증 키 | (미설정 시 인증 미사용) |
+| GRAVITY_HUB_SECRET | WS Hub JWT 서명 시크릿 (64char hex) | (미설정 시 인증 생략) |
+| GRAVITY_REGISTRATION_CODE | Extension 등록 코드 (32char hex) | (미설정 시 인증 생략) |
+| REMOTE_BRIDGE_URL | Collector 원격 URL | (remote 모드 전용) |
+
+## Extension VS Code 설정
+
+| 설정 키 | 용도 |
+|---------|------|
+| `gravityBridge.bridgePath` | Bridge 디렉토리 경로 |
+| `gravityBridge.projectName` | 프로젝트 이름 (기본: git remote) |
+| `gravityBridge.hubUrl` | Hub WS URL (예: `ws://localhost:8585/ws`) |
+| `gravityBridge.registrationCode` | Hub 등록 코드 |
+
+## 빌드 산출물
+
+| 항목 | 경로 | 설명 |
+|------|------|------|
+| VSIX | `extension/gravity-bridge-{ver}.vsix` | VS Code 확장 패키지 |
+| JS 출력 | `extension/out/*.js` | TypeScript 컴파일 결과물 |
+| SDK 복사 | `extension/out/sdk/` | compile 시 자동 복사 |