release: v0.2.2 업데이트 및 critical release gates

[luke-n-alpha]

목표

v0.2.2의 사용자 변경사항과 미해결 release gate를 한곳에서 추적한다. 열린 P0-critical은 완료 증거 없이 릴리스에서 제외하거나 닫지 않는다.

사용자 변경사항

• feat(v0.2.2): OpenAI provider에 custom Host/Base URL 설정 추가 #475 OpenAI provider custom Host/Base URL 지원
• fix(i18n): apply locale before first render and remove mixed/broken language UI #437 저장 locale 첫 렌더 적용 및 혼합/깨진 번역 UI 제거
• feat(shell): 도구 실행 권한 팝업에 공통 단축키 추가 #477 도구 실행 권한 팝업 공통 단축키
• fix(chat/voice): thinking을 일반 응답과 분리하고 발화에서 제외 #479 thinking 분리 및 음성 발화 제외
• refactor(voice): LLM→TTS 발화 텍스트 정규화 필터 단일화 #480 LLM→TTS 발화 텍스트 정규화 필터 단일화
• regression(voice): 발화가 다시 째지고 순간적으로 튀는 현상 #478 발화 째짐 및 순간적인 튐 회귀
• Radio DJ/BGM 재생 사실 보고 양방향 오류 — 늦은 시작=거짓 실패 발화, 임베드 차단=침묵 #430 YouTube 음악 실제 재생 상태와 AI 관측 불일치
• feat(workspace): Herdr terminal path to FileTree/viewer focus round-trip #432 Herdr 경로 modifier-click → Workspace viewer 연결
• feat(chat): LLM Markdown·코드 블록·Mermaid 응답 렌더링 #483 LLM Markdown·코드 블록·Mermaid 채팅 렌더링
• feat(workspace): MP3·WAV·MP4 미디어 파일 뷰어 #482 Workspace MP3·WAV·MP4 미디어 뷰어

v0.2.2 후보 기능

• epic(multimodal): Shell 시각 입력과 이미지 이해·생성 도구/스킬 경계 구축 #481 Shell 시각 입력과 이미지 이해·생성 도구/스킬 경계

Critical release gates

• fix(apps): 설치·목록·삭제 디렉터리 불일치로 앱이 보이지 않고 제거되지 않는 회귀 #472 앱 install/list/remove 저장 경로 통일 — 구현 후 Windows packaged lifecycle 검증 필요
• clean-install(MX250): herdr VC++ 런타임 미탐색 + 대화 0토큰 + NVA 크롭 #448 clean Windows install 통합 수용 — 첫 로그인/대화, Herdr, NVA, VoxCPM2, uninstall/reinstall 검증 필요

릴리스 판정

• P0-critical 열린 이슈 0건 또는 명시적인 릴리스 제외 결정 기록
• Windows 패키지 대상 항목에 실제 설치본 증거와 SHA-256 기록
• 변경사항이 최종 release notes/CHANGELOG에 반영됨
• 회귀 테스트와 빌드 검증 통과

[luke-n-alpha]

2026-08-23 열린 이슈 감사

P0-critical — 둘 다 실제 미해결

• fix(apps): 설치·목록·삭제 디렉터리 불일치로 앱이 보이지 않고 제거되지 않는 회귀 #472: 구현 커밋은 있으나 Windows packaged install → relaunch → remove 및 legacy migration 실기 검증이 남음.
• clean-install(MX250): herdr VC++ 런타임 미탐색 + 대화 0토큰 + NVA 크롭 #448: clean Windows 통합 수용이 실패한 뒤 열린 상태이며, 자동/Linux 증거만으로 닫지 않는다고 명시됨.

따라서 두 건 모두 v0.2.2 milestone에 포함했고 release blocker로 유지한다.

P1-high 추가 검토 후보 (아직 v0.2.2 확정 범위 아님)

• fix(settings): Ollama custom credentials/model and Naia auth sync #469: Ollama custom credentials/model 및 Naia auth 동기화
• fix(voice): recover stale Naia credentials when VoxCPM2 activation returns 401 #470: VoxCPM2 activation 401 시 stale Naia credentials 복구
• feat(store): 권리 검증형 앱 설치·업데이트·삭제·재설치 런타임 #473: 권리 검증형 앱 설치·업데이트·삭제·재설치 런타임

#469는 이번 OpenAI Host 요청과 인접하지만 별도 provider/auth 범위이고, #470·#473은 각각 #448·#472와 연관된다. 릴리스 범위 확정 시 별도로 milestone 편입 여부를 결정한다.

Translation

열린 translation 이슈 중 제품 결함은 #437 하나다. #7, #8은 커뮤니티 번역용 P3 문서/라벨 이슈라 이번 release gate에서 제외했다.

[luke-n-alpha]

0.2.2 스코프에 #484 추가 요청 — naia = naia-shell alias 등록 + naia <file> 에디터 열기, 기존 naia(디스코드 게이트웨이 모니터링 도구) 개명.

셸 exe·업데이터·기존 설치본은 건드리지 않는 저비용안입니다. 사용자 확보 시작 전 마지막 저비용 타이밍이라 이번 릴리즈에 태웁니다. 상세 설계·검증 기준은 #484 참조.

---

🤖 Written with AI assistance. If anything looks off, please ping @luke-n-alpha or open a discussion.

[luke-n-alpha]

2026-08-23 v0.2.2 신규 이슈 전수 감사 (#477–#484 및 추가 편입분)

Release blocker / 결함

• clean-install(MX250): herdr VC++ 런타임 미탐색 + 대화 0토큰 + NVA 크롭 #448 P0 — Windows clean-install 통합 수용 실패 상태. 최상위 release gate.
• fix(apps): 설치·목록·삭제 디렉터리 불일치로 앱이 보이지 않고 제거되지 않는 회귀 #472 P0 — 앱 저장 경로 수정 후 Windows packaged lifecycle 검증 필요.
• regression(voice): 발화가 다시 째지고 순간적으로 튀는 현상 #478 P1 — 음성 찢어짐/튐 회귀. 아직 재현 오디오·원인 레이어 증거가 없어 조사 단계.
• fix(chat/voice): thinking을 일반 응답과 분리하고 발화에서 제외 #479 P1 — thinking이 일반 답변/TTS에 섞이는 결함. #480보다 먼저 경계를 확정해야 함.
• fix(i18n): apply locale before first render and remove mixed/broken language UI #437 P1 — 번역 구현 후 Windows 첫 렌더와 한글 glyph 실기 검증 필요.
• Radio DJ/BGM 재생 사실 보고 양방향 오류 — 늦은 시작=거짓 실패 발화, 임베드 차단=침묵 #430 P1 — BGM 실제 재생 상태와 AI 보고 불일치. Shell/Agent 교차 저장소 변경 필요.

확정 사용자 기능

• feat(v0.2.2): OpenAI provider에 custom Host/Base URL 설정 추가 #475 P2 — OpenAI custom Host/Base URL.
• feat(shell): 도구 실행 권한 팝업에 공통 단축키 추가 #477 P1 — 권한 팝업 공통 단축키.
• refactor(voice): LLM→TTS 발화 텍스트 정규화 필터 단일화 #480 P1 — TTS 텍스트 정규화 단일화. #479와 #483의 공통 기반.
• feat(workspace): MP3·WAV·MP4 미디어 파일 뷰어 #482 P1 — MP3/WAV/MP4 Workspace viewer. 신규 dependency 도입 전 native media 대비 검토 필요.
• feat(chat): LLM Markdown·코드 블록·Mermaid 응답 렌더링 #483 P1 — 채팅 Markdown/code/Mermaid. refactor(voice): LLM→TTS 발화 텍스트 정규화 필터 단일화 #480 및 기존 Workspace Mermaid #128과 경계 공유.
• [0.2.2] naia = naia-shell alias 등록 + naia <file> 에디터 열기, 기존 naia(디스코드 게이트웨이 모니터링) 개명 #484 P1 — naia Shell alias와 naia <file> 열기, 기존 gateway 명령 개명. 본문에 포함 확정이나 milestone/labels가 누락돼 있어 이번 감사에서 보정함.

구현 완료 후 native acceptance 잔여

• feat(workspace): Herdr terminal path to FileTree/viewer focus round-trip #432 P2 — terminal path → FileTree/viewer 왕복. main 구현 완료, packaged-native 확인만 남음.

범위 확정 필요

• epic(multimodal): Shell 시각 입력과 이미지 이해·생성 도구/스킬 경계 구축 #481 P2 epic — 이미지 이해·생성 전체 경계. 본문은 “v0.2.2 후보”인데 milestone에는 이미 편입됨. 범위가 크므로 0.2.2에서 전체 구현인지, 하위 설계/기반만인지 명시해야 함.

의존 순서

1. fix(chat/voice): thinking을 일반 응답과 분리하고 발화에서 제외 #479 thinking 분리 → refactor(voice): LLM→TTS 발화 텍스트 정규화 필터 단일화 #480 공통 발화 필터 → feat(chat): LLM Markdown·코드 블록·Mermaid 응답 렌더링 #483 Markdown/Mermaid 렌더링
2. feat(workspace): Herdr terminal path to FileTree/viewer focus round-trip #432 기존 file-open 경로 검증 → [0.2.2] naia = naia-shell alias 등록 + naia <file> 에디터 열기, 기존 naia(디스코드 게이트웨이 모니터링) 개명 #484 CLI/second-instance file open 연결
3. #448이 clean-install 상위 수용 게이트로 fix(i18n): apply locale before first render and remove mixed/broken language UI #437/fix(apps): 설치·목록·삭제 디렉터리 불일치로 앱이 보이지 않고 제거되지 않는 회귀 #472 및 음성 관련 결과를 최종 검증

현재 열린 항목은 모두 구현 PR 연결이 없으며, #432만 main 반영 코멘트가 있고 native acceptance가 남아 있다.

[luke-n-alpha]

v0.2.2 순차 작업 현황입니다.\n\n구현 PR:\n- Shell 통합: #485\n- BGM agent: nextain/naia-agent#110\n- naia-gateway managed launcher: nextain/alpha-adk#29\n\n자동 검증:\n- 기능군 13 files / 132 passed\n- P0/P1 Linux automation 149 passed / Windows-only 8 skipped\n- TypeScript typecheck 통과\n- agent 6 passed, alpha 18 passed / Windows-only 3 skipped\n\n남은 release gates:\n- #432 #437 #448 #472 packaged Windows native acceptance\n- #481 범위 분해 및 v0.2.2 포함 여부 결정\n- Rust packaging은 pinned clean naia-agent source 무결성 조건 때문에 우회하지 않음\n- #478 VoxCPM2 음성 갈라짐은 요청대로 별도 트랙\n\n따라서 아직 0.2.2 버전 bump/완료 선언은 하지 않았습니다.

[luke-n-alpha]

v0.2.2 범위 추가 (2026-08-28 결정): BGM 유튜브 즐겨찾기 저장소 이전

문제

유튜브 즐겨찾기가 webview localStorage("yt-bgm-favorites")에 저장되어 워크스페이스(naia-settings)와 무관하게 앱 프로필에 갇힌다. 재설치·업데이트·개발빌드↔설치본 전환 시 유실. 2026-08-28 Windows v0.2.1 설치본에서 즐겨찾기 공백으로 실측 확인 (alpha-adk 워크스페이스에 즐겨찾기 데이터 없음 — 저장 위치가 워크스페이스가 아니기 때문).

코드 위치

• packages/shell/src/components/BgmPlayer.tsx:141 — const FAV_KEY = "yt-bgm-favorites" (localStorage 읽기/쓰기)
• packages/shell/src/lib/bgm-skill.ts:164,173 — localStorage.getItem("yt-bgm-favorites") (favorites_play 스킬 경로)

왜 0.2.2인가

사용자 데이터다. 출시본이 퍼질수록 localStorage에 쌓이는 즐겨찾기가 늘어나고, 늦게 이전할수록 마이그레이션 부담과 유실 리스크가 커진다. 지금이 가장 싸게 고칠 수 있는 시점.

작업

• 저장소를 naia-settings(워크스페이스 SoT)로 이전 — ui-config 계열과 동일한 로딩 경로
• 기존 localStorage 데이터 1회 마이그레이션 (있으면 이전 후 정리)
• BgmPlayer와 bgm-skill 두 읽기 경로 모두 교체 + 기존 즐겨찾기 재생/추가/삭제 스킬 회귀 테스트

관련: #506 (v0.2.3 계획 — 본 항목은 0.2.3에서 0.2.2로 이동)

[luke-n-alpha]

v0.2.2 범위 추가 (2026-08-28, 사용자 실사용 리포트): 유튜브 BGM 재생 시 배경이 검은 화면으로 대체되는 버그

증상 (Windows v0.2.1 설치본)

1. 설정에서 배경 비디오 표시 활성(= BGM "배경 비디오 표시" 체크, 기본값 true)
2. 유튜브 BGM 플레이어 재생
3. 기존 배경(backgroundVideo)이 사라지고 검은 화면 위에서 오디오만 재생됨 — 유튜브 배경 영상이 렌더링되지 않음

코드 경로

• packages/shell/src/components/BgmPlayer.tsx:216-221 — 재생 시 setBackgroundVideoUrl/setBackgroundMediaType("iframe")로 아바타 스토어 배경을 YouTube iframe으로 교체
• packages/shell/src/components/BgmPlayer.tsx:248-250, 837-849 — showYoutubeBackground → data-bgm-youtube-background visible/hidden 토글
• 증상 = 기존 배경 제거는 수행됐으나 교체된 iframe이 흑색 → 교체 실패 시 원복 없음

원인 가설 (검증 필요)

패키지된 webview 오리진(tauri://localhost 계열)에서 YouTube embed가 거부되어 iframe이 흑색 렌더링될 가능성. dev(http://localhost)에서는 정상일 수 있어 릴리스 검증에서 누락되기 쉬운 유형.

작업

• 설치본에서 재현 및 원인 확정 (embed 거부 vs CSP vs 로딩 실패)
• iframe 배경 로딩 실패 시 기존 배경으로 폴백 (검은 화면 금지 — 실패를 숨기지 말고 원복)
• "배경 비디오 표시" OFF 시 기존 배경 유지 경로 회귀 확인
• 패키지드 빌드 기준 검증 (dev 통과만으로 종결 금지)

관련: 같은 릴리스의 BGM 즐겨찾기 이전 항목(위 코멘트), #506(v0.2.3)

[luke-n-alpha]

v0.2.1 이후 main 실측 정리 (2026-08-28)

기준: merge-base(main, release/0.2.1-windows) = 4e2bca93 이후 origin/main 커밋 10건 + main의 releases/v0.2.2.yaml(2026-08-23).

A. 본문 체크리스트 ↔ 릴리스 노트 대조

구현 완료 — 노트에 반영됨 (검증 후 체크 가능): #475, #477, #479, #480, #482, #483, #430, #432, #437, #472 (전부 releases/v0.2.2.yaml에 항목 존재. 주 구현 커밋: ed34386a 롤업 외)

본문에 있으나 노트에서 명시 제외: #478 (발화 째짐) — 노트 summary가 "VoxCPM2 음성 갈라짐은 별도 추적, 본 릴리스 노트에 미포함"으로 못박음. 본문 체크리스트에서 0.2.2 제외 여부 결정 필요.

노트에 있으나 본문 체크리스트에 없음 (본문 추가 권장):

• feat(agent): Wire Memory System into Naia Shell — real user integration #174 — 워크스페이스 격리 영속 Naia Memory (한국어 오프라인 시맨틱 검색 + 키워드 폴백)
• [0.2.2] naia = naia-shell alias 등록 + naia <file> 에디터 열기, 기존 naia(디스코드 게이트웨이 모니터링) 개명 #484 — naia 셸 명령 등록 + 파일 열기 + Discord 런처 naia-gateway 개명
• fix(workspace): Herdr 중단 시에도 파일 트리를 독립적으로 로드 #492 — Herdr 중단/무응답 시 워크스페이스 파일 트리 독립 로딩
• feat(youtube): 배경 비디오 표시를 끄고 오디오만 재생하는 옵션 #493 — YouTube 배경 비디오 숨김(오디오 유지) 옵션
• fix(youtube): 재생 중 음표 애니메이션이 동작하지 않는 회귀 #494 — 음표 인디케이터를 실제 재생 이벤트 기준으로
• fix(youtube): 재생 상태에 맞는 Play/Stop 다음 동작 버튼 표시 #495 — 재생 중 정지 버튼 / 정지 후 재생 버튼

B. 노트에 없는 main 변경 (노트 반영 여부 결정 필요)

• 241dcf0e feat(gemini): 최신 모델·가격 반영
• b7145a08 macOS Universal 앱 빌드 검증
• dfa33eb1 fix(voice): managed host activation 복구
• 16a0064e ci(release): Windows 번들 페이로드 서명
• 9450bb85 Store regression 준비 / 7bd24008·7aa90a8e·a55e2588 메모리 저장 경계·v0.2.2 프리즈(fix(release): freeze Naia Memory for v0.2.2 #496, [bug] workspace: session status logic incomplete — error state never set, stale data on watcher restart #108)

C. 오늘 추가 결정된 항목 (위 코멘트 2건)

• 유튜브 즐겨찾기 localStorage → naia-settings 이전 (사용자 데이터 — 늦출수록 비쌈)
• BGM 배경 검은 화면 수정 — Radio DJ/BGM 재생 사실 보고 양방향 오류 — 늦은 시작=거짓 실패 발화, 임베드 차단=침묵 #430(임베드 차단 보고)·feat(youtube): 배경 비디오 표시를 끄고 오디오만 재생하는 옵션 #493(배경 숨김 옵션)과 인접하지만 별개 증상(표시 ON인데 흑색 + 원복 없음). v0.2.2 빌드에서 재현 재확인 필요 (v0.2.1 설치본 기준 리포트)

D. 정정

#506·#190에 기록한 "naia CLI 부재" 분석은 v0.2.1 설치본 기준이며, main에는 #484로 이미 구현되어 0.2.2에 포함된다. 0.2.3 진입 경로 범위는 OS 파일 연결(#190) + 0.2.2 CLI 출고 검증으로 축소 조정함(#506 본문 수정).