docs: 세션 종료 — devlog 2026-03-21 (3건) + known-issues singleByPath + entry

.agent/references/known-issues.md

@@ -165,3 +165,9 @@
 - **원인**: 블로그 포스트 제목에 에피소드 번호 없음 → `discovered_ep = None` → line 761/777 스킵 조건(`is not None`) 전부 False → 무조건 다운로드. `_extract_archive`도 기존 파일 존재 체크 없이 덮어씀
 - **해결**: (1) `discovered_ep is None` + 모든 영상 에피소드에 자막 있으면 URL 페치 자체 스킵 (2) ZIP 해제 시 `out_path.exists()` 체크
 - **주의**: 에피소드 기반 스킵은 `discovered_ep`와 `sub.episode` 모두 None이면 완전 무력화. 반드시 **보충 체크** 필요
+
+### [2026-03-21] wiki — singleByPath 미존재 페이지 에러
+- **증상**: `upsert_page("new/path")` 호출 시 `RuntimeError: Wiki.js API 오류: This page does not exist`
+- **원인**: Wiki.js `singleByPath` 쿼리는 미존재 페이지에 대해 null 대신 **GraphQL error**를 반환. 기존 `list_pages()` → 루프 패턴은 이 문제 없었음
+- **해결**: `find_page()`에서 `RuntimeError` catch → `"does not exist"` 포함 시 `None` 반환. `wiki_debate.py`도 `_query()`에서 동일 처리
+- **주의**: Wiki.js GraphQL API는 not-found를 에러로 처리하는 경우가 있음. 새 쿼리 추가 시 반드시 미존재 케이스 테스트

docs/devlog/2026-03-21.md

@@ -1,4 +1,5 @@
 | # | 시간 | 작업 | 커밋 | 상태 |
 |----|------|------|------|------|
 | 001 | 12:00 | 자막 다운로드 Flow 정밀검증 — 과다 다운로드/리네임 미실행/오류 표현 5건 수정 | `94fb4e6` | ✅ |
-| 002 | 20:50 | debate-agent 분산 토론 시스템 — Wiki.js 기반 통신, AG 프로젝트 스캐폴딩, handler 리팩토링 | `9fedba3` | ✅ |
+| 002 | 20:50 | debate-agent 분산 토론 시스템 — Wiki.js 기반 통신, AG 프로젝트 스캐폴딩, handler 리팩토링 | `cbc9db0` | ✅ |
+| 003 | 21:00 | singleByPath 미존재 페이지 에러 처리 + 설계서 v5 업데이트 + Wiki 업로드 | `4352a6a` | ✅ |

docs/devlog/entries/20260321-002.md

@@ -0,0 +1,24 @@
+# debate-agent 분산 토론 시스템 구현
+
+- **시간**: 2026-03-21 20:00~21:00
+- **Commit**: `cbc9db0`, `4352a6a`
+- **Vikunja**: #490 (E2E 테스트) → 미완료, #387 (Debate Room) → 진행중
+
+## 결정 사항
+
+1. **독립 orchestrator 포기 → variet-agent 봇 내부 유지**
+   - 처음에는 별도 orchestrator 프로세스(Option B)를 고려했으나
+   - 기존 debate_handler.py가 Discord 봇 안에 있어야 시그널 전송/감지가 자연스러움
+   - I/O만 로컬 파일 → Wiki.js로 교체하면 충분
+
+2. **Wiki.js singleByPath O(1) 조회**
+   - 기존 find_page()는 list_pages() 전체 리스트 → 루프 검색 (O(N))
+   - singleByPath 쿼리로 교체 시 미존재 페이지가 null이 아닌 GraphQL error 반환
+   - 반드시 try/except 처리 필요 (known-issues 등록됨)
+
+3. **AG 프로젝트 소스 관리 위치**
+   - `variet-agent/debate-agent/` 하위에 배치 (git 추적)
+   - `Desktop/debate-agent/`에 배포하여 AG가 프로젝트로 열 수 있게
+
+## 미완료
+- **#490** E2E 테스트: 봇에서 `!debate` → AG `/start` 전체 흐름 검증