@litfamily/litopencode 1.0.20 → 1.0.22

package/docs/reference-Ko-KR.md

@@ -89,11 +89,14 @@ CI와 비대화형 터미널에서는 자동 질문을 생략하며, 명시한
 새로 설치하거나 초기화하면 계획·검토 및 `lit-loop`는 `openai/gpt-6-astra`/`xhigh`,
 실행·연구 helper는 새 기본값인 `openai/gpt-6-luna`/`max`를 사용합니다. `gpt-6.1-sol`/`xhigh`는
 코딩 리드 대안입니다. `gpt-6-sol`은 이전 세대로 계속 선택할 수 있어 이 모델을 쓰는 기존 설정도 그대로 동작하며,
-같은 추론 수준을 지원하고 `-fast` 별칭은 없습니다. GPT-6 Astra와 GPT-6 Sol은 `low`, `medium`, `high`, `xhigh`, `max`, `ultra`를
-모두 지원합니다. GPT-6 Luna는 `low`, `medium`, `high`, `xhigh`, `max`를 지원하지만 `ultra`는
-지원하지 않습니다. 이전 세대 `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`는 계속 선택할 수 있고,
-현재 호스트 카탈로그에는 이 모델들의 지원 종료일이 등록되어 있지 않습니다. GPT-5.6 Luna는
-`high`와 `max`만 지원하고 `xhigh`는 허용하지 않습니다. 이 제한은 GPT-6 Luna에는 적용되지 않습니다.
+`-fast` 별칭은 없습니다. 모델마다 OpenCode가 그 모델에 내놓는 추론 수준을 그대로 고를 수 있습니다
+(`opencode models openai --verbose`의 `variants`, OpenCode 1.18.35에서 확인). GPT-6 Astra와 GPT-6.1 Sol은
+`low`, `medium`, `high`, `xhigh`, `max`를 지원합니다. GPT-6 Luna, GPT-6 Sol, GPT-5.6 계열은 `none`, `low`,
+`medium`, `high`, `xhigh`, `max`를 지원합니다. `ultra`를 지원하는 모델은 없습니다. `ultra`로 저장된 설정은 `max`로 동작하고, doctor가 `retiredEfforts`에 알려 주며,
+다음 설치가 백업을 남긴 뒤 `max`로 바꿉니다. 선택 메뉴는 모델을 고른
+뒤 그 역할의 추론 수준을 묻고, 모델이 지원하는 수준을 모두 보여 주며, 추천 수준에 표시를 붙여 기본값으로
+둡니다. 지금 설정의 수준이 여전히 지원되면 그 수준이 기본값입니다. 이전 세대 `gpt-5.6-sol`, `gpt-5.6-terra`,
+`gpt-5.6-luna`는 계속 선택할 수 있고, 현재 호스트 카탈로그에는 이 모델들의 지원 종료일이 등록되어 있지 않습니다.
 일반 설치와
 업데이트는 이미 설정된 모델을 보존합니다. 명시적인 `--model-prompt`만 관리 모델 키를 다시 씁니다.
 기존 GPT-5.6 계열의 `-fast` 의미는 유지하지만 `gpt-6-astra-fast` 별칭은 추가하지 않습니다.
@@ -254,24 +257,46 @@ OpenCode 1.18은 `tui.json`이나 `tui.jsonc`의 `plugin` 배열에 적힌 TUI
 
 화면에 그리는 것:
 
-- 입력창 아래 agent/model 줄 오른쪽의 단계 칩: `🔥 LIT` 알약 뒤에 `PLAN` › `WORK n/m` › `REVIEW`
-  알약과 다섯 칸 `▰▱` 막대가 붙습니다. 자리가 좁으면 이름부터 덜어 내서, `🔥`와 지금·다음 단계만,
-  더 좁으면 `🔥`와 개수만 남깁니다. 자리는 OpenCode에 저장된 사이드바 설정과 세션 종류(하위 세션에는
-  사이드바가 없음)로 계산합니다. 설정을 아직 읽을 수 없으면 사이드바가 열려 있다고 보고 좁게 잡습니다.
+- 작업 흐름 지도: 어떤 스킬이 돌았는지만이 아니라 지금 LIT 작업 흐름의 어디쯤인지 보여 줍니다.
+  세션마다 단계표 하나를 따릅니다.
+  - 기본 흐름 `interview › plan › work n/m › review › done`
+  - lit-loop의 기준 반복: 단계는 같고, lit-loop나 litgoal 세션이 할 일 대신 목표 기준을 셀 때
+    work 단계가 `criterion n/m`으로 바뀝니다.
+  - litresearch 실행: 세션이 litresearch를 돌리고 있거나 세션이 쓴 실행 폴더가 아직 열려 있으면
+    `decompose › wave n › expand › verify › synthesis`를 따릅니다.
+
+  하지 않고 지나간 단계에는 `–`가 붙습니다. 범위가 정해진 `lit-task`는 계획을 만들지 않으므로 plan
+  단계를 건너뛴 것으로 보여 주고, 했다고 표시하지 않습니다. `review-work` 없이 할 일만 모두 끝내도
+  review는 `–`로 남습니다. 리뷰 명령, 리뷰 막힘, ledger CLI로 끝낸 목표(완료 관문이 리뷰를 포함함)가 있어야
+  완료로 바뀝니다. 에이전트가 직접 쓴 `goals.json`에서 끝났다고 표시한 목표는 관문을 거치지 않았으므로
+  review를 `–`로 둡니다. 지나온 단계는 테마의 primary에서
+  secondary를 거쳐 accent로 가는 색을 차례로 받고, 앞으로 할 단계는 흐리게 그립니다.
+- 입력창 아래 agent/model 줄 오른쪽의 지도 칩: `🔥 LIT` 알약 뒤에 지금 단계 앞뒤를 이어 쓴
+  `plan ✓ › WORK ▰▰▰▱▱▱▱ 3/7 › review`가 붙습니다. 지금 단계는 채운 알약과 일곱 칸 막대로 보입니다.
+  자리가 넉넉하면 지금 하는 일(`⠹ bash · 0:48`)이 뒤따릅니다. 자리가 좁으면 지금 하는 일을 먼저 빼고,
+  다음에는 브랜드와 지난 단계를 빼서 `🔥`, 지금·다음 단계, 다섯 칸 막대만 남기고, 더 좁으면 `🔥`와
+  개수만 남깁니다. 자리는 OpenCode에 저장된 사이드바 설정과 세션 종류(하위 세션에는 사이드바가
+  없음)로 계산합니다. 설정을 아직 읽을 수 없으면 사이드바가 열려 있다고 보고 좁게 잡습니다.
 - 세션 사이드바 맨 위의 미션 패널: 36칸짜리 둥근 상자이고, 위 테두리에 `🔥 LIT ▸ <단계>`, 아래
   테두리에 `n/m criteria`가 붙습니다. 테두리 색이 상태를 보여 줍니다. 일하는 중에는 테마 accent,
   경고가 있으면 warning, 끝나면 success 색입니다. 안에는 두 줄짜리 `LIT`과 그 옆의 작업 이름·상태,
-  굵은 목표 제목, 단계 줄, 1/8칸 블록으로 칠하고 빈 곳은 가는 선으로 둔 그라데이션 막대, 다음 할 일이나
-  아직 통과하지 못한 기준, 기준 목록, 경고, 최근 증거 네 개가 들어갑니다.
+  굵은 목표 제목, 세로 단계 지도가 들어갑니다. 지도에서 지난 단계는 `◆`, 지금 단계는 굵은 `◉`,
+  경고가 걸린 단계는 `⚑`, 남은 단계는 `◇`입니다. 지금 단계까지는 단계 색의 `┃`로, 그 뒤로는 점선
+  `┆`로 잇고, plan 옆에는 저장된 계획의 할 일 수, work 옆에는 `iter k`를 적습니다. 그 아래로 1/8칸
+  블록으로 칠하고 빈 곳은 가는 선으로 둔 그라데이션 막대, 자세히 한 줄 `└ task 3 · next ▸ <항목>`
+  (조사 실행에서는 주장 수와 검증된 수), 지금 하는 일, 기준 목록, 경고, 최근 증거 네 개가 이어집니다.
+- 지금 하는 일: 세션이 돌리고 있는 도구의 이름과 걸린 시간입니다. 실행 중인 도구 part의 이름과 시작
+  시각만 읽고, 입력(명령, 경로, 인자)은 읽지도 보여 주지도 않습니다. 턴이 도는 동안에만 보입니다.
 - 띠(band): 화면 맨 아래에 붙는 상태 카드입니다(OpenCode의 `app_bottom` 자리). 세션과 사이드바
   아래를 모두 가로지릅니다. lit을 쓰든 안 쓰든 세션 내내 보이고, 쉴 때나 일할 때나 똑같이 네 줄이라
   입력창이 움직이지 않습니다.
   - 위 테두리 왼쪽에 `🔥 LIT · <작업 이름>`, 오른쪽에 단계가 붙습니다(`● WORK`, `⚑ review blocked`,
-    `✓ COMPLETE`, lit 턴 전에는 `○ IDLE`).
-  - 첫째 줄은 칩과 같은 알약으로 그린 단계 줄 `PLAN ━ WORK ━ REVIEW`, 1/8칸 막대, 목표의
-    `n/m criteria`, 다음 할 일입니다. 경고가 열려 있는 동안에는 `▸ 다음 일` 자리에 `⚑ <내용>`이
-    들어갑니다. 쉬는 세션에서는 흐린 단계 줄 옆에 프로젝트의 마지막 목표를, 목표가 없으면
-    `add lit to a prompt to start`를 보여 줍니다.
+    `✓ COMPLETE`, lit 턴 전과 세션이 턴을 돌리지 않는 동안에는 `○ IDLE`. 이때는 OpenCode의 `session.status`를
+    읽고, 밝게 켜진 단계가 없습니다).
+  - 첫째 줄은 단계 전체를 이어 쓴 지도 `interview – ━ plan ✓ ━ WORK 3/7 ─ review ─ done`, 1/8칸
+    막대, 목표의 `n/m criteria`(단계가 이미 기준을 세는 기준 반복에서는 빠집니다), 지금 하는 일, 다음 할 일입니다. 경고가 열려 있는 동안에는 지금 하는
+    일과 `▸ 다음 일` 자리에 `⚑ <내용>`이 들어갑니다. 쉬는 세션에서는 흐린 지도 옆에 프로젝트의
+    마지막 목표를, 목표가 없으면 `add lit to a prompt to start`를 보여 줍니다.
   - 둘째 줄은 스킬 칩입니다. 세션에서 실행된 LitOpenCode 스킬이 여러 개 함께 보입니다. 지금 요청에서
     실행된 스킬은 요청이 도는 동안 accent 색 알약으로 밝게 보이고, 새로 들어온 칩에는 빛이 짧게 한 번
     지나갑니다. 턴이 끝나면 흐려져 최근 목록으로 남고(최근 것이 앞), 다시 실행되면 다시 밝아집니다.
@@ -280,8 +305,8 @@ OpenCode 1.18은 `tui.json`이나 `tui.jsonc`의 `plugin` 배열에 적힌 TUI
     붙습니다.
 
   하위(subagent) 세션에서는 부모 세션의 카드를 `· in lane`과 함께 보여 주고, 홈 화면에는 띠가
-  없습니다. 폭이 좁으면 줄마다 덜 중요한 것부터 덜어 냅니다. 단계 줄은 다음 할 일 글자, 막대 길이,
-  막대, 기준 개수, 단계 이름 순서로, 아래 테두리는 브랜치, 시간, context 사용량 순서로 뺍니다. 줄을
+  없습니다. 폭이 좁으면 줄마다 덜 중요한 것부터 덜어 냅니다. 단계 줄은 지금 하는 일과 다음 할 일
+  글자, 막대 길이, 막대, 기준 개수를 차례로 빼고, 마지막에는 지금 단계만 남깁니다. 아래 테두리는 브랜치, 시간, context 사용량 순서로 뺍니다. 줄을
   넘기지는 않습니다. 완료 순간도 여기서 함께 보입니다.
 - 홈 화면 입력창 아래, OpenCode 팁 다음 줄: `🔥 lit ready · last: <목표> ✓ n/m`. 프로젝트 ledger에
   목표가 있을 때만 보입니다.
@@ -289,9 +314,14 @@ OpenCode 1.18은 `tui.json`이나 `tui.jsonc`의 `plugin` 배열에 적힌 TUI
   때문입니다. 알파가 0인 테마 바탕(system, lucent-orng)은 검게 칠하지 않고 비워 둡니다.
 - 관문 사건마다 토스트 하나: 계획 저장 또는 저장 실패, 목표 설정, 기준 통과, 리뷰 막힘과 해결, 완료.
   한 번에 여러 사건이 생기면 가장 급한 것 하나로 합칩니다.
-- 목표가 끝나거나 할 일이 모두 끝나면 1.2초 안에 끝나는 완료 순간을 보여 줍니다. 테두리가 초록으로
-  바뀌고 막대가 끝까지 차며, `WORK`와 `REVIEW`가 차례로 완료로 바뀝니다. 브랜드에 빛이 한 번 지나가고,
-  패널 안으로 불씨가 올라가며, `COMPLETE`가 살짝 넘쳤다가 제자리로 옵니다.
+- 목표가 끝나거나, 할 일이 모두 끝나거나, 조사 실행이 보고서를 쓰면 1.2초 안에 끝나는 완료 순간을
+  보여 줍니다. 테두리가 초록으로 바뀌고 막대가 끝까지 차며, 돌던 단계와 그 뒤 단계가 60ms 간격으로
+  차례로 완료로 바뀝니다. 브랜드에 빛이 한 번 지나가고, 패널 안으로 불씨가 올라가며, `COMPLETE`가
+  살짝 넘쳤다가 제자리로 옵니다.
+- 같은 순간에 켤 때만 울리는 끝 알림: OpenCode의 `attention.notify`로 데스크톱 알림과 호스트의
+  `done` 소리를 보냅니다. 기본은 꺼져 있고, 켜는 법은 아래 옵션에 있습니다. 실제로 울릴지는 OpenCode
+  자체의 `attention` 설정이 정합니다. 이 설정은 tui.json에서 `"attention": { "enabled": true }`로 켜기
+  전까지 꺼져 있고, 꺼져 있으면 OpenCode가 `attention_disabled`로 답합니다.
 
 데이터는 이미 있는 것만 읽고, TUI를 위해 새로 쓰는 파일은 없습니다.
 
@@ -302,16 +332,36 @@ OpenCode 1.18은 `tui.json`이나 `tui.jsonc`의 `plugin` 배열에 적힌 TUI
   동안 마지막 사용자 메시지 이후에 실행된 것을 뜻합니다.
 - `lit`이 모드를 켜거나 명령이 실행될 때(`save-plan` 포함) 이 플러그인이 사용자 메시지 part에 붙이는
   `metadata.litopencode` 표시. 표시가 없는 세션은 쉬는 상태로 보고, 기본 `lit-loop` agent여도 칩과
-  패널을 숨깁니다.
+  패널을 숨깁니다. `/litresearch` 같은 슬래시 명령은 OpenCode의 명령 hook으로 지도에 표시되므로
+  `litopencode install`이 쓰는 명령 파일이 있어야 합니다. `plugin` 항목만 있으면 OpenCode가 이를
+  평범한 글로 보내고, 지도에는 아무것도 표시되지 않습니다.
 - 세션의 OpenCode 할 일 목록(진행도와 다음 항목), 상태(재시도), 대기 중인 권한 요청과 질문, 마지막
   assistant 메시지 기준 context 사용량(75%부터 주황).
 - 프로젝트 루트의 `.litopencode/litgoal/lit-loop/goals.json`. 심볼릭 링크와 1 MiB가 넘는 파일은 읽지
-  않습니다. 세션의 첫 lit 턴보다 먼저 마지막으로 바뀐 목표는 이전 작업으로 보고 빼 둡니다.
+  않습니다. CLI가 쓰는 ledger 형태(`goals`와 `activeGoalId`) 말고도 에이전트가 직접 쓴 형태, 곧 맨 위의
+  목표 하나, `goal` 아래의 목표, `goals` 목록의 마지막 항목도 읽고, `completed`나 `done`은 통과한 기준이나
+  끝난 목표로 셉니다. 세션의 첫 lit 턴보다 먼저 마지막으로 바뀐 목표는 이전 작업으로 보고 빼 둡니다. 목표의
+  checkpoint 수가 기준 반복의 iter 수가 됩니다.
+- `/start-work`가 남기는 범위 작업 기록 `.litopencode/litgoal/lit-loop/work-schema-3.json`. 이 세션의
+  것이고 취소되지 않았을 때만 읽습니다. `work.progressed` 기록 수가 work 단계의 iter 수가 되고, 기록이
+  가리키는 계획 파일에서 맨 앞에 붙은 `- [ ]` / `- [x]` 줄을 세어 할 일 수와 다음 항목을 얻습니다.
+  계획 파일은 프로젝트 루트 안의 일반 파일일 때만 읽습니다.
+- `.litopencode/litgoal/lit-loop/research/` 아래에서 가장 최근에 쓴 실행 폴더. `report.md`가 있으면
+  synthesis, `claim-graph.jsonl`에 관문 결과(`verified`, `abstained`, `unresolved`, `refuted`)가 붙은
+  주장이 있으면 verify, `journal.md`의 마지막 제목이 `EXPAND`로 시작하면 expand, 주장이 있으면 wave(가장
+  큰 `wave` 값이나 `## Wave` 제목 수로 번호를 붙임), 아무것도 없으면 decompose입니다. 세션의 첫 lit
+  턴보다 먼저 쓴 폴더는 이전 작업으로 봅니다.
+- 지금 하는 일을 위해 세션의 마지막 assistant 메시지에서 실행 중인 도구 part. 도구 이름과 `time.start`만
+  씁니다.
 
 움직임은 전환이 일어나는 동안에만 짧은 프레임 타이머로 돌고 끝나면 멈춥니다. 새 줄과 알약은
 ease-out-back으로 160ms씩, 60ms 간격으로 들어오고, 막대는 300ms에 차오릅니다. 경고 줄은 220ms에
-걸쳐 들어오고 색은 140ms 동안 넘어가며, 빛이 지나가는 데는 400ms가 걸립니다. lit 세션이
-열려 있는 동안만 2초마다 목표 ledger를 다시 읽고, 쉬는 세션은 읽지 않습니다. 색은 지금 OpenCode
+걸쳐 들어오고 색은 140ms 동안 넘어가며, 빛이 지나가는 데는 400ms가 걸립니다. 지도가 다음 단계로
+넘어가면 옛 단계와 새 단계 사이의 세로 선이 위에서 아래로 60ms 간격으로 차오르고, 지금 단계 알약이
+한 번 빛납니다. 계속 도는 움직임은 없습니다. 지금 하는 일은 미끄러져 들어오지 않고 제자리에서
+바뀌며, 도구가 도는 동안에만 걸린 시간이 1초에 한 번 바뀝니다. 도는 도구가 없으면 타이머도
+없습니다. lit 세션이 열려 있는 동안만 2초마다 목표 ledger, 범위 작업 기록, 조사 폴더를 다시 읽고,
+쉬는 세션은 읽지 않습니다. 색은 지금 OpenCode
 테마에서 가져옵니다. 움직임을 끄려면 `tui.json`에 `["@litfamily/litopencode@<version>", { "motion": false }]`
 처럼 적고, 플러그인 자체를 끄려면 OpenCode 플러그인 관리자나 `plugin_enabled`에서 id `litopencode`를 끕니다.
 
@@ -322,6 +372,11 @@ ease-out-back으로 160ms씩, 60ms 간격으로 들어오고, 막대는 300ms에
   목표가 있는 동안 카드는 네 줄로 고정되어, 경고가 생기거나 사라져도 입력창이 움직이지 않습니다.
   카드는 기본으로 꺼져 있습니다.
 
+끝 알림도 같은 객체에 적으며, 적지 않으면 꺼져 있습니다.
+
+- `{ "notify": true }`는 미션이 끝날 때 데스크톱 알림을 보내고 `done` 소리를 냅니다.
+- `{ "notify": { "sound": false } }`는 알림만, `{ "notify": { "desktop": false } }`는 소리만 남깁니다.
+
 다른 터미널에서 쓴 ledger(예: `litopencode record-evidence`)는 OpenCode 이벤트를 만들지 않습니다.
 그래서 2초마다 도는 공용 ledger 확인이 이를 잡고, 칩·패널·띠가 같은 프레임 시계로 함께 바뀝니다.
 
@@ -362,7 +417,7 @@ OpenCode는 세션이 바쁜 동안 들어온 `summarize` 호출을 줄 세웠
 
 ### Doctor
 
-`litopencode doctor`의 출력에 `autoHandoff` 블록이 추가됩니다. 실제로 적용되는 스위치와 퍼센트, 각각의 출처, 상태 파일 경로, 두 변수 이름, 호스트의 압축 지점, `warnings`가 들어 있습니다. 호스트 지점은 LitOpenCode가 설치하는 창(372,000토큰, 압축은 334,800토큰, 곧 90%)에서만 알 수 있습니다. 그 지점과 같거나 높은 퍼센트는 OpenCode가 먼저 압축하므로 경고가 납니다. 다른 모델은 창과 여유분을 호스트가 정하므로 doctor가 숫자를 내놓지 않습니다.
+`litopencode doctor`의 출력에 `autoHandoff` 블록이 추가됩니다. 플러그인과 같은 프로젝트(작업 폴더 위의 git 루트, 없으면 그 폴더)에서 읽습니다. 실제로 적용되는 스위치와 퍼센트, 각각의 출처, 프로젝트, 상태 파일 경로, 두 변수 이름, 호스트의 압축 지점, `warnings`가 들어 있습니다. 호스트 지점은 LitOpenCode가 설치하는 창(372,000토큰, 압축은 334,800토큰, 곧 90%)에서만 알 수 있습니다. 그 지점과 같거나 높은 퍼센트는 OpenCode가 먼저 압축하므로 경고가 납니다. 다른 모델은 창과 여유분을 호스트가 정하므로 doctor가 숫자를 내놓지 않습니다.
 
 ### 디스크에 남는 것
 

package/docs/reference.md

@@ -91,11 +91,15 @@ may use a different provider. New installs default to GPT-6 Astra/xhigh for lead
 review roles; GPT-6.1 Sol/xhigh (`gpt-6.1-sol`) is the coding-lead alternative, and GPT-6 Luna/max is the helper
 default for execution, research, and ordinary workers. `gpt-6-sol` stays selectable as the previous
 generation, so existing configs that name it keep working; it accepts the same efforts and has no `-fast` alias.
-GPT-6 Astra and Sol accept `low`, `medium`, `high`, `xhigh`, `max`, and `ultra`. GPT-6 Luna accepts
-`low`, `medium`, `high`, `xhigh`, and `max`, but not `ultra`. The previous-generation
+Each model offers exactly the reasoning efforts OpenCode lists for it (the model's `variants` in
+`opencode models openai --verbose`, checked on OpenCode 1.18.35). GPT-6 Astra and GPT-6.1 Sol accept
+`low`, `medium`, `high`, `xhigh`, and `max`. GPT-6 Luna, GPT-6 Sol, and the GPT-5.6 rows accept `none`,
+`low`, `medium`, `high`, `xhigh`, and `max`. No model accepts `ultra`; a saved `ultra` route runs as `max`,
+doctor lists it under `retiredEfforts`, and the next install rewrites it to `max` after a backup. After each model the picker
+asks for that role's effort, lists every effort the model accepts, marks the recommended one, and
+defaults to it, or to the current route's effort when that is still offered. The previous-generation
 `gpt-5.6-sol`, `gpt-5.6-terra`, and `gpt-5.6-luna` remain selectable, and the current host catalog
-has no retirement metadata for them. GPT-5.6 Luna accepts only `high` and `max`; `xhigh` remains
-unsupported for that model. This previous-generation restriction does not apply to GPT-6 Luna.
+has no retirement metadata for them.
 xAI rows are the reasoning-capable Grok models from the host catalog, `grok-4.6` first.
 `--subagent-model <provider/id>` and `--subagent-effort <e>` set the helper route from flags.
 Legacy OpenAI `<id>-fast` aliases remain accepted and policy-checked as their base ids;
@@ -355,26 +359,51 @@ package exports its TUI module as `@litfamily/litopencode/tui` (`dist/tui.js`, p
 
 What it draws:
 
-- A phase chip on the right of the prompt's agent/model row: a `🔥 LIT` pill, then `PLAN` ›
-  `WORK n/m` › `REVIEW` pills and a five-segment `▰▱` bar. When the row is narrower it drops the
-  labels first: `🔥` with the current and next phase, then `🔥` with only the count. The room comes
-  from OpenCode's stored sidebar setting and the session kind (a child session has no sidebar); when
-  the setting cannot be read yet, the chip assumes the sidebar is open and stays narrower.
+- A workflow map, so the session shows where it is in the LIT workflow and not only which skill
+  fired. Each session follows one stage table:
+  - the main chain `interview › plan › work n/m › review › done`;
+  - lit-loop's criterion loop, the same stages with the work stage reading `criterion n/m`, when a
+    lit-loop or litgoal session counts goal criteria rather than tasks;
+  - a litresearch run, `decompose › wave n › expand › verify › synthesis`, while the session runs
+    litresearch or a run folder it wrote is still open.
+
+  A stage the session moved past without doing reads `–`: a bounded `lit-task` makes no plan, so its
+  plan stage is skipped, never claimed, and finishing every todo without `review-work` leaves review
+  at `–`. A review command, a review blocker or a goal completed through the ledger CLI (whose gate
+  includes review) marks it done; a goal the agent marks complete in a hand-written `goals.json`
+  passed no gate and leaves review at `–`. Stages behind the running one take their place on a colour
+  ramp from the theme's primary through secondary to accent; stages ahead are muted.
+- A map chip on the right of the prompt's agent/model row: a `🔥 LIT` pill and the breadcrumb around
+  the running stage, `plan ✓ › WORK ▰▰▰▱▱▱▱ 3/7 › review`, with the running stage as a filled pill and a
+  seven-cell bar. When the row has room the live step follows (`⠹ bash · 0:48`). Narrower, it drops
+  the live step, then the brand and the stage behind (`🔥` with the running and next stage and a
+  five-cell bar), then everything but `🔥` and the count. The room comes from OpenCode's stored
+  sidebar setting and the session kind (a child session has no sidebar); when the setting cannot be
+  read yet, the chip assumes the sidebar is open and stays narrower.
 - A mission panel at the top of the session sidebar, in a 36-cell rounded box titled
-  `🔥 LIT ▸ <PHASE>` with `n/m criteria` in the bottom border. The border carries the state: the
+  `🔥 LIT ▸ <STAGE>` with `n/m criteria` in the bottom border. The border carries the state: the
   theme accent while working, the warning colour on a warning, the success colour when complete.
   Inside: a two-row `LIT` with the discipline and a status beside it, the goal title in bold, the
-  phase line, a gradient bar drawn in eighth-cell blocks over a thin rule, the next todo or open
-  criterion, the criteria, warnings, and the last four evidence events.
+  vertical stage map (`◆` behind, `◉` running in bold, `⚑` flagged, `◇` ahead, joined by `┃`
+  connectors in the ramp colour up to the running stage and dotted `┆` after it, with the saved
+  plan's task count beside plan and `iter k` beside work), a gradient bar drawn in eighth-cell
+  blocks over a thin rule, the detail line `└ task 3 · next ▸ <item>` (a research run shows its claim
+  and verified counts instead), the live step, the criteria, warnings, and the last four evidence
+  events.
+- The live step: the name of the tool the session is running and how long it has run, read from the
+  running tool part's name and start time. Its input (commands, paths, arguments) is never read or
+  shown. It appears only while the turn runs.
 - A band: a status card along the bottom of the screen (OpenCode's `app_bottom` slot), under the
   session and the sidebar alike. It is on screen for the whole session, lit or not, and keeps the
   same four rows idle or working, so the prompt never moves:
   - the top border carries `🔥 LIT · <discipline>` on the left and the phase on the right
-    (`● WORK`, `⚑ review blocked`, `✓ COMPLETE`, or `○ IDLE` before any lit turn);
-  - row one is the phase track `PLAN ━ WORK ━ REVIEW` in the chip's pills, an eighth-block bar,
-    `n/m criteria` for the goal and the next task. While a warning is open, `⚑ <text>` takes the
-    place of `▸ next`. An idle session shows the dim track with the project's last goal, or
-    `add lit to a prompt to start`;
+    (`● WORK`, `⚑ review blocked`, `✓ COMPLETE`, or `○ IDLE` before any lit turn and whenever the
+    session is not running a turn, read from OpenCode's own `session.status`; at rest no step is lit);
+  - row one is the whole stage map as a breadcrumb, `interview – ━ plan ✓ ━ WORK 3/7 ─ review ─ done`,
+    an eighth-block bar, `n/m criteria` for the goal (left out in the criterion loop, whose stage
+    already counts them), the live step and the next task. While a
+    warning is open, `⚑ <text>` takes the place of the live step and `▸ next`. An idle session shows
+    the dim map with the project's last goal, or `add lit to a prompt to start`;
   - row two holds the skill chips: every LitOpenCode skill that fired in the session, several at
     once. Skills fired by the current request are bright accent pills while it runs, and a new one
     gets a short light sweep as it arrives; when the turn ends they dim and stay as the recent list,
@@ -383,8 +412,8 @@ What it draws:
     (`⟳ 7m`) and the git branch.
 
   A subagent session shows its parent's card with `· in lane`; the home screen has no band. When the
-  card is narrow each row drops its own low-priority parts: the track drops the next-task text, bar
-  width, the bar, the criteria count and then the step labels; the bottom border drops the branch,
+  card is narrow each row drops its own low-priority parts: the track drops the live step and
+  next-task text, bar width, the bar, the criteria count and then every stage but the running one; the bottom border drops the branch,
   then the time, then the context use. It never wraps. The completion moment plays here too.
 - A line under the home prompt, after OpenCode's tips: `🔥 lit ready · last: <goal> ✓ n/m`. It
   appears only when the project ledger holds a goal.
@@ -394,9 +423,14 @@ What it draws:
 - One toast per refresh for a gate event: plan saved or not saved, goal set, criterion passed,
   review blocker opened or resolved, and completion. Several events at once collapse into the most
   urgent one.
-- A completion moment of at most 1.2 seconds when the goal completes or every todo is done: the
-  border turns green, the bar fills, `WORK` then `REVIEW` turn done, a light sweep crosses the brand,
-  embers rise through the panel and `COMPLETE` pops in with a small overshoot before it settles.
+- A completion moment of at most 1.2 seconds when the goal completes, every todo is done or a
+  research run writes its report: the border turns green, the bar fills, the stage that was running
+  and each stage after it turn done 60 ms apart, a light sweep crosses the brand, embers rise
+  through the panel and `COMPLETE` pops in with a small overshoot before it settles.
+- An opt-in finish alert at that same moment, through OpenCode's `attention.notify`: a desktop
+  notification and the host's `done` sound. It is off by default; see the options below. OpenCode's
+  own `attention` setting still decides whether anything plays, and it is off until tui.json turns
+  it on (`"attention": { "enabled": true }`); without it OpenCode answers `attention_disabled`.
 
 Where the data comes from, with nothing new written for the TUI:
 
@@ -407,17 +441,40 @@ Where the data comes from, with nothing new written for the TUI:
   "Current" means fired since the latest user message while the session is busy.
 - The `metadata.litopencode` marks this plugin already attaches to user-message parts when `lit`
   activates a mode or a command runs (`save-plan` included). A session with no mark is idle and the
-  chip and panel stay hidden, even on the default `lit-loop` agent.
+  chip and panel stay hidden, even on the default `lit-loop` agent. Slash commands such as
+  `/litresearch` mark the map through OpenCode's command hook, so they need the command files
+  `litopencode install` writes; with only a `plugin` entry OpenCode sends them as plain text, which
+  marks nothing.
 - OpenCode's todo list for the session (progress and next item), its status (retry), pending
   permissions and questions, and context use from the last assistant message (amber at 75%).
 - `.litopencode/litgoal/lit-loop/goals.json` under the project root. Symbolic links and files over
-  1 MiB are ignored. A goal last updated before the session's first lit turn is treated as earlier
-  work and left out.
+  1 MiB are ignored. Besides the ledger shape the CLI writes (`goals` with `activeGoalId`), it reads
+  what an agent writes by hand: one goal at the top, a goal under `goal`, or the last entry of a
+  `goals` list, with `completed` or `done` counted as a passed criterion or a complete goal. A goal
+  last updated before the session's first lit turn is treated as earlier work and left out. Its
+  checkpoints are the loop family's iterations.
+- `.litopencode/litgoal/lit-loop/work-schema-3.json`, the bounded work record `/start-work` keeps,
+  when it belongs to this session and is not cancelled: its `work.progressed` turns are the work
+  stage's iterations, and the plan file it names gives the task count and next item from its
+  column-zero `- [ ]` / `- [x]` rows. The plan is read only when it is a regular file inside the
+  project root.
+- The most recently written run folder under `.litopencode/litgoal/lit-loop/research/`: a
+  `report.md` means synthesis, a claim in `claim-graph.jsonl` with a gate result (`verified`,
+  `abstained`, `unresolved`, `refuted`) means verify, a `journal.md` whose last heading starts with
+  `EXPAND` means expand, claims mean a wave (numbered by the highest `wave` field or `## Wave`
+  heading), and nothing yet means decompose. A folder last written before the session's first lit
+  turn is earlier work.
+- The running tool part of the session's latest assistant message, for the live step: its tool name
+  and `time.start` only.
 
 Motion runs on a short frame timer only while a transition plays and stops afterwards: new rows
 and pills slide in with ease-out-back, 160 ms each and 60 ms apart; the bar fills in 300 ms; a
-warning row slides in over 220 ms and colours cross-fade in 140 ms; the light sweep takes 400 ms. While a
-lit session is open the panel re-reads the goal ledger every two seconds; an idle session does not.
+warning row slides in over 220 ms and colours cross-fade in 140 ms; the light sweep takes 400 ms.
+When the map moves forward, the connectors between the old and new stage fill top to bottom 60 ms
+apart and the running pill flashes once; nothing loops. The live step changes in place without a
+slide-in, and while a tool runs its elapsed time ticks once a second; with no tool running there is
+no timer at all. While a lit session is open the panel re-reads the goal ledger, the bounded work
+record and the research folder every two seconds; an idle session does not.
 Colours come from the active OpenCode theme. Set `["@litfamily/litopencode@<version>", { "motion": false }]`
 in `tui.json` to keep it static, or turn the plugin off by id `litopencode` in OpenCode's plugin
 manager or with `plugin_enabled`.
@@ -429,6 +486,13 @@ Band options go in the same options object:
   the next task and the goal. While a goal exists the card keeps a fixed four rows, so a warning arriving or
   clearing never moves the prompt. The card is off by default.
 
+The finish alert goes in the same object and is off unless set:
+
+- `{ "notify": true }` sends a desktop notification and plays the `done` sound when a mission
+  completes.
+- `{ "notify": { "sound": false } }` keeps only the notification; `{ "notify": { "desktop": false } }`
+  keeps only the sound.
+
 A ledger written from another terminal (for example `litopencode record-evidence`) raises no
 OpenCode event, so the shared two-second ledger check picks it up; the chip, the panel and the band
 then change on the same frame clock.
@@ -471,7 +535,7 @@ The order is environment, then saved setting, then config file, then the default
 
 ### Doctor
 
-`litopencode doctor` adds an `autoHandoff` block: the effective switch and percent, where each came from, the state file path, the two variable names, the host compaction point, and `warnings`. The host point is known for the window LitOpenCode installs (372,000 tokens with compaction at 334,800, which is 90%). A percent at or above it produces a warning, because OpenCode would compact first. For other models the host decides the window and the reserve, so doctor reports no number.
+`litopencode doctor` adds an `autoHandoff` block, read from the same project the plugin uses (the git root above the working directory, or the directory itself): the effective switch and percent, where each came from, the project, the state file path, the two variable names, the host compaction point, and `warnings`. The host point is known for the window LitOpenCode installs (372,000 tokens with compaction at 334,800, which is 90%). A percent at or above it produces a warning, because OpenCode would compact first. For other models the host decides the window and the reserve, so doctor reports no number.
 
 ### What is written
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litopencode",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Workflow plugin for OpenCode: add lit to a prompt and the work is planned, built, checked and written down so the next session can pick it up.",
   "keywords": [
     "opencode",