@rch4com/agent-setup 1.18.0 → 1.20.0

package/lib/tui/render.mjs

@@ -19,9 +19,73 @@ const BOLD = `${ESC}[1m`
 const REVERSE = `${ESC}[7m`
 const RESET = `${ESC}[0m`
 
-// 머리글·탭줄·검색줄·구분 공백·바닥글이 차지하는 줄 수.
+// 머리글·탭줄·검색줄·구분 공백·바닥글(한 줄)이 차지하는 줄 수.
+// 바닥글이 두 줄이 되면(footerHeight) 그만큼 더 뺀다.
 const CHROME = 6
 export const LABEL_WIDTH = 24
+// 라벨 열의 상한. 터미널이 넓으면 긴 라벨(`Understand Anything (저장소)`)을
+// 자르지 않도록 열을 늘리되, 힌트 자리(HINT_MIN)는 남긴다. 50칸은 80칸
+// 터미널의 힌트 자리(49칸)보다 커서, 80칸에서는 옛 24칸이 그대로 유지되고
+// 100칸쯤부터 늘기 시작한다 — 좁은 화면에서 라벨을 늘리면 전역 항목의
+// `gemini 없음` 같은 힌트 꼬리가 대신 잘렸다.
+const LABEL_MAX = 40
+const HINT_MIN = 50
+// rows.mjs의 NAME_LIMIT와 같은 규칙 — 넷 이하면 이름, 그보다 많으면 수.
+const NAME_LIMIT = 4
+
+// 행 라벨 열의 폭. 24칸 고정이면 넓은 화면에서도 긴 라벨이 잘렸다. 화면에
+// 있는 가장 긴 라벨까지 늘리되 상한과 힌트 자리를 지킨다.
+export function labelColumn(rows, w) {
+  const longest = Math.max(LABEL_WIDTH, ...rows.filter((r) => r.kind === 'item').map((r) => width(r.label ?? '')))
+  return Math.max(LABEL_WIDTH, Math.min(longest, LABEL_MAX, w - 6 - HINT_MIN))
+}
+
+// 넓은 화면에서는 전체 경로, 자리가 없으면 마지막 디렉터리 이름만.
+function repoLabel(repo, room) {
+  const full = String(repo ?? '')
+  if (width(full) <= room) return full
+  return full.split(/[\\/]/).filter(Boolean).pop() ?? full
+}
+
+// 힌트 항목 사이의 구분자. 카탈로그 문자열이 이 간격으로 항목을 나눈다 —
+// 좁은 폭에서 두 줄로 접을 때 이 경계에서만 끊는다.
+const HINT_SEP = '   '
+
+// 바닥글 힌트를 폭에 맞춰 최대 두 줄로 접는다. 예전에는 한 줄로 두고 뒤를
+// 잘랐는데, 80칸 한국어 화면에서 `Ctrl+A 전체   C…`에서 끊겨 CLI 필터(Ctrl+F)·
+// 상세 펼침(Ctrl+D)·미리보기(Ctrl+O)를 발견할 길이 없었다. 두 줄로도 모자라면
+// 둘째 줄을 자른다 — 세 줄은 목록 지면을 너무 갉아먹는다.
+export function hintLines(hint, room) {
+  const lines = []
+  let cur = ''
+  for (const seg of String(hint ?? '').split(HINT_SEP)) {
+    const next = cur ? `${cur}${HINT_SEP}${seg}` : seg
+    if (cur && width(next) > room) {
+      lines.push(cur)
+      cur = seg
+    } else {
+      cur = next
+    }
+  }
+  if (cur) lines.push(cur)
+  if (lines.length <= 2) return lines
+  return [lines[0], cut(lines.slice(1).join(HINT_SEP), room)]
+}
+
+// 힌트 오른쪽 끝의 종료 키를 뺀 나머지 자리. 8칸도 안 남으면 힌트를 버리고
+// 종료 키만 남긴다(render의 바닥글과 같은 판정).
+function hintRoom(w, t) {
+  return w - width(t('tui.hint.quit')) - 2
+}
+
+// 바닥글 줄 수(1 또는 2). 검색칸·목록 두 포커스의 힌트 중 긴 쪽으로 정한다 —
+// 포커스를 옮길 때마다 목록 높이가 바뀌면 화면이 출렁인다.
+export function footerHeight(columns = 80, t = createT('en')) {
+  const w = Math.max(24, columns - 1)
+  const room = hintRoom(w, t)
+  if (room < 8) return 1
+  return Math.max(hintLines(t('tui.hint.list'), room).length, hintLines(t('tui.hint.search'), room).length)
+}
 
 // 상세 패널은 목록과 화면을 나눠 갖는다. 높이를 커서가 아니라 **터미널
 // 크기로만** 정하는 것이 핵심이다 — 커서를 옮길 때마다 높이가 변하면
@@ -32,16 +96,17 @@ const PANEL_MAX = 12
 // 목록이 3줄 밑으로 내려가는 쪽이 패널이 사라지는 것보다 나쁘다.
 const PANEL_FLOOR = PANEL_MIN + 3
 
-export function panelHeight(height, expanded = false) {
-  const room = Math.max(0, height - CHROME)
+// footer는 바닥글 줄 수(footerHeight)다. 기본 1이면 옛 산식과 같다.
+export function panelHeight(height, expanded = false, footer = 1) {
+  const room = Math.max(0, height - CHROME - (footer - 1))
   if (expanded) return room
   if (room < PANEL_FLOOR) return 0
   return Math.min(PANEL_MAX, Math.max(PANEL_MIN, Math.round(room * PANEL_SHARE)))
 }
 
-export function bodyHeight(height, expanded = false) {
-  const room = Math.max(0, height - CHROME)
-  const panel = panelHeight(height, expanded)
+export function bodyHeight(height, expanded = false, footer = 1) {
+  const room = Math.max(0, height - CHROME - (footer - 1))
+  const panel = panelHeight(height, expanded, footer)
   // 패널이 없을 때는 예전과 같이 최소 3줄을 보장한다.
   return panel === 0 ? Math.max(3, room) : room - panel
 }
@@ -54,19 +119,41 @@ export function reviewBodyHeight(height) {
   return Math.max(3, height - CHROME)
 }
 
-const MARK = { action: '▶', on: '×', off: ' ' }
+// on = 설치돼 있고 그대로 둔다, add = 이번에 새로 고름(설치·보완 설치 예정),
+// remove = 설치돼 있는데 체크를 풀었다(제거 예정), off = 없고 안 고름.
+const MARK = { action: '▶', on: '×', add: '+', remove: '-', off: ' ' }
 
 // 대괄호는 "여러 개 고를 수 있다"는 보편적 신호다 — 한 파일에 한 벌만 놓이는
 // 배타 묶음(커밋 템플릿의 두 언어판)에 그대로 쓰면 화면이 거짓말을 한다.
 // 둥근 괄호로 바꿔 라디오임을 드러낸다. 안쪽 글자는 그대로 둔다: ×는 이미
 // 이 화면이 쓰는 글자라 폭 계산이 검증된 값이고, ●·•는 동아시아 폭이
 // 모호(Ambiguous)해 터미널에 따라 두 칸으로 그려져 열을 밀 수 있다.
+//
+// 표식은 "지금 체크됐나"가 아니라 "Enter를 누르면 무슨 일이 나나"를 말한다.
+// 예전에는 ×가 "설치됨(유지)"과 "새로 고름"에 똑같이 쓰였고, 설치된 항목의
+// 체크를 풀면 빈 칸이 돼 힌트의 '설치됨'과 조합해야 제거 예정임을 알 수
+// 있었다. +·-는 ASCII라 폭이 모호하지 않다(−·±는 동아시아 폭이 모호하다).
+export function changeMark(row, selected) {
+  const on = selected.has(row.id)
+  if (on) return row.status === 'installed' ? MARK.on : MARK.add
+  return row.status === 'absent' ? MARK.off : MARK.remove
+}
+
 function checkbox(row, selected) {
   if (row.kind === 'action') return `[${MARK.action}]`
-  const mark = selected.has(row.id) ? MARK.on : MARK.off
+  const mark = changeMark(row, selected)
   return row.exclusive ? `(${mark})` : `[${mark}]`
 }
 
+// Enter를 누르면 바뀔 항목 수 — engine.planChanges와 같은 판정이다.
+// add는 설치·보완 설치, remove는 제거다.
+export function pendingCounts(state) {
+  const marks = state.rows.filter((r) => r.kind === 'item').map((r) => changeMark(r, state.selected))
+  const add = marks.filter((m) => m === MARK.add).length
+  const remove = marks.filter((m) => m === MARK.remove).length
+  return { add, remove, total: add + remove }
+}
+
 // 탭 줄. 목록이 좁혀졌으면(검색어·CLI 필터 어느 쪽이든) 탭마다 적중 수를
 // 보여 준다 — 검색·필터는 활성 탭 안으로만 걸리므로, 다른 탭에 결과가
 // 있다는 사실을 여기서 알린다. 그래야 필터가 사용자를 빈 탭에 가둬 두고
@@ -109,10 +196,15 @@ export function tabBar(state, { width: limit, color = false, narrowed = false, t
 // 그대로 쓰이는데, 색 코드를 섞으면 ESC 시퀀스가 표시 폭에 끼어든다(폭은
 // 항상 색을 입히기 전에 재야 한다). 칠하는 일은 호출부가 폭 계산을 끝낸
 // 뒤 마지막에 한다.
+//
+// 위치는 CLI 사이에서만 센다. options[0]은 "전체"(null)라 순환 목록에는 있지만
+// 사용자에게는 CLI가 아니다 — 그것까지 세면 `codex (3/11)`처럼 CLI가 열
+// 개인데 열한 번째가 있다고 읽힌다.
 export function filterSegment(state, { t = createT('en'), options = [] } = {}) {
   if (!state.cliFilter) return ''
-  const at = options.indexOf(state.cliFilter)
-  const pos = at === -1 ? '' : ` (${t('tui.filter.position', { current: at + 1, total: options.length })})`
+  const clis = options.filter((o) => o !== null)
+  const at = clis.indexOf(state.cliFilter)
+  const pos = at === -1 ? '' : ` (${t('tui.filter.position', { current: at + 1, total: clis.length })})`
   return `${t('tui.filter.prefix')}${state.cliFilter}${pos}`
 }
 
@@ -157,8 +249,14 @@ export function render(state, opts = {}) {
   const picked = items.filter((r) => state.selected.has(r.id)).length
 
   const title = `agent-installer${dryRun ? ' (dry-run)' : ''}`
-  const counts = t('tui.counts', { picked, total: items.length })
-  const head = cut(`${title}  ${counts}  ${repo}`, w)
+  // 선택 수 옆에 변경 예정 건수를 둔다 — "선택 3 / 전체 106"은 설치 상태의
+  // 합계라 Enter를 누르면 무슨 일이 날지 말해 주지 않는다. 항상 찍는다:
+  // 0건이면 "지금 Enter는 아무것도 안 한다"는 뜻이라 그것대로 정보다.
+  const pending = pendingCounts(state)
+  const marks = pending.total > 0 ? t('tui.pendingMarks', { add: pending.add, remove: pending.remove }) : ''
+  const counts = `${t('tui.counts', { picked, total: items.length })}  ${t('tui.pending', { count: pending.total, marks })}`
+  const repoText = repoLabel(repo, w - width(`${title}  ${counts}  `))
+  const head = cut(`${title}  ${counts}  ${repoText}`, w)
   const searching = String(state.query ?? '').trim() !== ''
   // 목록이 좁혀졌는가 — 검색어·CLI 필터 어느 쪽이든 활성 탭 안에서만 걸리는
   // 좁힘이라, 다른 탭에 뭐가 남았는지 알리는 몫(탭 줄의 shown/total)은
@@ -167,13 +265,14 @@ export function render(state, opts = {}) {
 
   const filter = filterSegment(state, { t, options: cliOptions })
   const lines = [
-    color ? `${BOLD}${title}${RESET}${cut(`  ${counts}  ${repo}`, Math.max(0, w - width(title)))}` : head,
+    color ? `${BOLD}${title}${RESET}${cut(`  ${counts}  ${repoText}`, Math.max(0, w - width(title)))}` : head,
     tabBar(state, { width: w, color, narrowed, t }),
     searchLine(state, { limit: w, color, paint, t, filter }),
     '',
   ]
 
-  const body = bodyHeight(height, detailExpanded)
+  const footer = footerHeight(columns, t)
+  const body = bodyHeight(height, detailExpanded, footer)
   const all = displayList(state)
 
   if (all.length === 0) {
@@ -188,6 +287,7 @@ export function render(state, opts = {}) {
     for (let i = 1; i < body; i++) lines.push('')
   } else {
     const window = all.slice(state.offset, state.offset + body)
+    const labelCol = labelColumn(state.rows, w)
     for (const entry of window) {
       if (entry.type === 'header') {
         const count = entry.shown === entry.total ? `${entry.total}` : `${entry.shown}/${entry.total}`
@@ -199,8 +299,8 @@ export function render(state, opts = {}) {
       }
       const { row, index } = entry
       const here = index === state.cursor
-      const hintWidth = Math.max(0, w - LABEL_WIDTH - 6)
-      const text = cut(`${here ? '❯' : ' '} ${checkbox(row, state.selected)} ${pad(row.label, LABEL_WIDTH)} ${cut(row.hint, hintWidth)}`, w)
+      const hintWidth = Math.max(0, w - labelCol - 6)
+      const text = cut(`${here ? '❯' : ' '} ${checkbox(row, state.selected)} ${pad(row.label, labelCol)} ${cut(row.hint, hintWidth)}`, w)
       lines.push(here ? paint(REVERSE, text) : text)
     }
     for (let i = window.length; i < body; i++) lines.push('')
@@ -208,7 +308,7 @@ export function render(state, opts = {}) {
 
   // 상세 패널 — 목록 아래 고정 자리. 높이가 커서와 무관하므로 목록이
   // 출렁이지 않는다. 지면이 모자라면 panelHeight가 0을 돌려 통째로 빠진다.
-  const panel = panelHeight(height, detailExpanded)
+  const panel = panelHeight(height, detailExpanded, footer)
   if (panel > 0) {
     lines.push(paint(DIM, '─'.repeat(w)))
     const room = panel - 1
@@ -223,13 +323,25 @@ export function render(state, opts = {}) {
   // 빠져나가나"다 — 잘려도 되는 안내와 절대 사라지면 안 되는 안내를 같은
   // 줄에 이어 붙여 두면 늘 후자가 먼저 사라진다. 상태 메시지가 힌트를
   // 대신할 때도 이 자리는 그대로 남는다.
+  //
+  // 바닥글은 footer줄이다(1 또는 2). 힌트는 위에서부터 채우고 종료 키는 항상
+  // 마지막 줄 오른쪽 끝이다. 상태 메시지는 힌트를 통째로 대신하되 마지막
+  // 줄에 놓는다 — 폭이 달라져도 "맨 아랫줄 = 상태 + 종료 키"가 유지된다.
   const hint = state.focus === 'search' ? t('tui.hint.search') : t('tui.hint.list')
   const quit = t('tui.hint.quit')
-  const room = w - width(quit) - 2
+  const room = hintRoom(w, t)
   lines.push('')
-  lines.push(room < 8
-    ? paint(BOLD, cut(quit, w))
-    : `${paint(DIM, pad(status || hint, room))}  ${paint(BOLD, quit)}`)
+  if (room < 8) {
+    for (let i = 1; i < footer; i++) lines.push('')
+    lines.push(paint(BOLD, cut(quit, w)))
+    return lines
+  }
+  const shown = status ? [status] : hintLines(hint, room)
+  while (shown.length < footer) shown.unshift('')
+  shown.slice(0, footer).forEach((text, i) => {
+    const last = i === footer - 1
+    lines.push(last ? `${paint(DIM, pad(text, room))}  ${paint(BOLD, quit)}` : paint(DIM, cut(text, w)))
+  })
   return lines
 }
 
@@ -248,9 +360,15 @@ export function renderReview(changes, opts = {}) {
   // 적용 직전 마지막 화면이다. 일부 CLI에만 들어가는 항목은 여기서도 그 사실을
   // 밝힌다 — 목록에서 지나쳤더라도 되돌릴 수 있는 마지막 지점이다.
   // 전부 지원하는 항목은 조용히 둔다: 경고가 흔해지면 아무도 읽지 않는다.
+  // 목록과 같은 규칙으로 — 넷 이하면 이름을 적는다. 숫자만 있으면 어느
+  // CLI인지 알려고 Esc로 되돌아가야 했다.
   const changeLine = (c) => {
-    const partial = c.item.supports && c.item.supports.length < CLI_IDS.length
-    const cov = partial ? ` · ${t('item.cliCoverage', { covered: c.item.supports.length, total: CLI_IDS.length })}` : ''
+    const supports = c.item.supports
+    const partial = supports && supports.length < CLI_IDS.length
+    const covText = supports?.length > 0 && supports.length <= NAME_LIMIT
+      ? supports.join('·')
+      : t('item.cliCoverage', { covered: supports?.length ?? 0, total: CLI_IDS.length })
+    const cov = partial ? ` · ${covText}` : ''
     return cut(`  ${CHANGE_MARK[c.action] ?? '?'} ${pad(t(`change.${c.action}`), 10)} ${scopedLabel(c.item, t)}${cov}`, w)
   }
 
@@ -305,3 +423,17 @@ export function renderReview(changes, opts = {}) {
   lines.push(paint(DIM, cut(t('tui.review.hint'), w)))
   return lines
 }
+
+// 도움말 화면 — F1. 바닥글 두 줄로는 키의 뜻까지 담을 수 없어, 전체 키를
+// 설명과 함께 한 화면에 편다. 아무 키나 누르면 닫힌다.
+export function renderHelp(opts = {}) {
+  const { width: columns = 80, height = 24, color = false, t = createT('en') } = opts
+  const w = Math.max(24, columns - 1)
+  const paint = (code, text) => (color ? `${code}${text}${RESET}` : text)
+  const lines = [paint(BOLD, cut(t('help.title'), w)), '']
+  for (const line of t('help.lines').split('\n')) lines.push(cut(line, w))
+  while (lines.length < height - 2) lines.push('')
+  lines.push('')
+  lines.push(paint(DIM, cut(t('help.close'), w)))
+  return lines.slice(0, height)
+}

package/lib/tui/rows.mjs

@@ -104,16 +104,38 @@ export function designHint(state, multiProvider = false, t) {
   return parts.filter(Boolean).join(' · ')
 }
 
+// 이름을 나열할 수 있는 최대 CLI 수. 넷까지는 이름(codex·gemini·opencode·copilot)이
+// 80칸 힌트 자리에 들고, 그보다 많으면 "몇 개나 되나"가 더 유용하다.
+const NAME_LIMIT = 4
+
 // 목록 행에 실제로 찍히는 힌트. 80칸 터미널이면 힌트 자리는 49칸(한글 24자)뿐이라,
 // 예전처럼 사유까지 이어 붙이면 뒤쪽이 통째로 잘렸다. 사유·note·detail은
 // 상세 패널이 여러 줄로 편다 — 여기 남는 것은 잘릴 일이 없는 두 가지뿐이다.
+//
+// 커버리지 표기는 탭과 무관하게 한 규칙이다 — 예전에는 plugin 탭만 이름을,
+// 나머지는 수를 찍어 한 화면 안에서 규칙이 바뀌었다. 이제 지원 CLI가 넷
+// 이하면 이름을, 그보다 많으면 `CLI n/N`을 찍는다. 이름을 나열할 때는 이
+// 머신에 없는 CLI(state.excluded — 전역 항목이 detect에서 알린다)를 빼고
+// 따로 적는다: 상세에는 "CLI 없음"이라 하면서 행에는 그 이름이 그대로
+// 찍히면 어느 쪽이 참인지 알 수 없다.
+export function coverageText(item, state, t = createT('en')) {
+  if (!item.supports) return ''
+  if (item.supports.length > NAME_LIMIT || item.supports.length === 0) {
+    return t('item.cliCoverage', { covered: item.supports.length, total: CLI_IDS.length })
+  }
+  const excluded = state?.excluded ?? []
+  const here = item.supports.filter((c) => !excluded.includes(c))
+  const parts = []
+  if (here.length > 0) parts.push(here.join('·'))
+  if (excluded.length > 0) parts.push(t('item.cliMissing', { list: excluded.join('·') }))
+  return parts.join(' · ')
+}
+
 export function agentShortHint(item, state, t = createT('en')) {
   const parts = []
   if (state.status !== 'absent') parts.push(t(`status.${state.status}`))
-  // plugin은 수 대신 이름을 나열한다 — 어느 CLI에 설치되는가가 이 탭에서
-  // 고르는 기준이고, 가장 긴 나열(codex·gemini·opencode·copilot)도 자리에 든다.
-  if (item.category === 'plugin' && item.supports?.length) parts.push(item.supports.join('·'))
-  else if (item.supports) parts.push(t('item.cliCoverage', { covered: item.supports.length, total: CLI_IDS.length }))
+  const cov = coverageText(item, state, t)
+  if (cov) parts.push(cov)
   return parts.join(' · ')
 }
 
@@ -151,11 +173,14 @@ function itemRow({ id, section, label, hint, fullHint = hint, statusDetail = nul
   }
 }
 
-function actionRow({ id, label, hint, run = null, t = createT('en') }) {
+// section 기본값은 작업 탭이다. design.md 동기화처럼 한 탭에만 관계있는
+// 작업은 그 탭을 넘겨 그 자리 맨 위에 놓는다 — 첫 화면의 작업 탭에 design.md
+// 전용 작업이 섞여 있으면 무엇을 위한 화면인지부터 흐려진다.
+function actionRow({ id, label, hint, run = null, section = ACTION_SECTION, t = createT('en') }) {
   return {
     kind: 'action',
     id,
-    section: ACTION_SECTION,
+    section,
     group: null,
     exclusive: null,
     label,
@@ -165,7 +190,7 @@ function actionRow({ id, label, hint, run = null, t = createT('en') }) {
     status: 'absent',
     previewTarget: null,
     run,
-    searchText: `${label} ${hint} ${sectionTerms(t, ACTION_SECTION)}`.toLowerCase(),
+    searchText: `${label} ${hint} ${sectionTerms(t, section)}`.toLowerCase(),
   }
 }
 
@@ -192,8 +217,10 @@ export function buildActions(root, { designItems = [], t = createT('en') } = {})
       run: ({ dryRun, skillMode, log, t: rt }) => runBootstrap(root, { dryRun, skillMode, log, t: rt }),
       t,
     }),
+    // design.md 전용 세 작업은 DESIGN.MD 탭 맨 위에 놓는다.
     actionRow({
       id: 'action.sync.installed',
+      section: 'design',
       label: t('action.sync.installed.label'),
       hint: t('action.sync.installed.hint'),
       run: ({ dryRun, log, t: rt }) => updateInstalled(root, designItems, { dryRun, log, t: rt }),
@@ -201,6 +228,7 @@ export function buildActions(root, { designItems = [], t = createT('en') } = {})
     }),
     actionRow({
       id: 'action.sync.catalog',
+      section: 'design',
       label: t('action.sync.catalog.label'),
       hint: t('action.sync.catalog.hint'),
       run: ({ dryRun, fetchImpl, log, catalogFile, t: rt }) => refreshCatalog({ dryRun, fetchImpl, log, catalogFile, t: rt }),
@@ -208,6 +236,7 @@ export function buildActions(root, { designItems = [], t = createT('en') } = {})
     }),
     actionRow({
       id: 'action.sync.stale',
+      section: 'design',
       label: t('action.sync.stale.label'),
       hint: t('action.sync.stale.hint'),
       run: async ({ dryRun, log, confirm, t: rt }) => {

package/lib/tui/run.mjs

@@ -12,7 +12,7 @@ import {
   createState, setQuery, setFocus, move, moveTab, toggle, toggleVisible, scroll, currentRow, replaceRows, activeTab,
   cycleCliFilter,
 } from './state.mjs'
-import { render, renderReview, bodyHeight } from './render.mjs'
+import { render, renderReview, renderHelp, bodyHeight, footerHeight } from './render.mjs'
 import { createProgress, applyEvent, progressLines } from './progress.mjs'
 import { scopedLabel } from '../labels.mjs'
 
@@ -119,19 +119,36 @@ export async function runTui(root, opts = {}) {
 
   const color = !env.NO_COLOR && stdout.isTTY
   const draw = (lines) => stdout.write(HOME + lines.map((l) => l + CLEAR_LINE).join('\n') + '\n' + CLEAR_DOWN)
+  // 목록 지면은 바닥글 줄 수에 따라 달라진다 — render와 같은 산식을 써야
+  // 스크롤·페이지 이동이 화면과 어긋나지 않는다. t는 언어 행이 갈아끼우므로
+  // 그때그때 다시 잰다.
+  const listHeight = () => bodyHeight(stdout.rows ?? 24, detailExpanded, footerHeight(stdout.columns ?? 80, t))
   const paint = () => {
     const height = stdout.rows ?? 24
-    state = scroll(state, bodyHeight(height, detailExpanded))
+    state = scroll(state, listHeight())
     draw(render(state, {
       width: stdout.columns ?? 80, height, repo: root, dryRun, color, status, t,
       detailExpanded, cliOptions: CLI_OPTIONS,
     }))
   }
+  const paintHelp = () => draw(renderHelp({ width: stdout.columns ?? 80, height: stdout.rows ?? 24, color, t }))
+
+  // 터미널 크기가 바뀌면 지금 떠 있는 화면을 새 크기로 다시 그린다 — 예전에는
+  // 다음 키를 누를 때까지 옛 크기로 남았다. 화면마다 자기 그리기 함수를
+  // redraw에 걸고, 화면 밖(suspend)에서는 null로 둬 아무것도 안 한다.
+  // 테스트의 가짜 stdout에는 on이 없을 수 있어 선택 호출이다.
+  let redraw = paint
+  const onResize = () => {
+    try { redraw?.() } catch { /* 그리기 실패로 루프를 죽이지 않는다 */ }
+  }
+  stdout.on?.('resize', onResize)
 
   // 로그는 화면 안에 우겨넣지 않는다 — 실패 메시지가 길고, 잘리면 진단이 불가능해진다.
   const suspend = async (fn) => {
+    const was = redraw
+    redraw = null
     stdout.write(ALT_OFF + SHOW_CURSOR)
-    try { return await fn() } finally { stdout.write(ALT_ON + HIDE_CURSOR) }
+    try { return await fn() } finally { stdout.write(ALT_ON + HIDE_CURSOR); redraw = was }
   }
   const confirm = async (message) => {
     stdout.write(`\n${message}${t('tui.confirmSuffix')}`)
@@ -201,12 +218,18 @@ export async function runTui(root, opts = {}) {
 
   // 제출 검토 — 적용 직전에 변경 목록을 보여 주고 Enter/Esc만 받는다.
   const review = async (changes) => {
-    for (;;) {
-      draw(renderReview(changes, { width: stdout.columns ?? 80, height: stdout.rows ?? 24, dryRun, color, t }))
-      const key = await keys.next()
-      if (key.ctrl && (key.name === 'c' || key.name === 'q')) return 'quit'
-      if (key.name === 'escape') return 'cancel'
-      if (key.name === 'return' || key.name === 'enter') return 'apply'
+    const paintReview = () => draw(renderReview(changes, { width: stdout.columns ?? 80, height: stdout.rows ?? 24, dryRun, color, t }))
+    redraw = paintReview
+    try {
+      for (;;) {
+        paintReview()
+        const key = await keys.next()
+        if (key.ctrl && (key.name === 'c' || key.name === 'q')) return 'quit'
+        if (key.name === 'escape') return 'cancel'
+        if (key.name === 'return' || key.name === 'enter') return 'apply'
+      }
+    } finally {
+      redraw = paint
     }
   }
 
@@ -225,6 +248,7 @@ export async function runTui(root, opts = {}) {
       width: stdout.columns ?? 80, height: stdout.rows ?? 24, color, dryRun, now: Date.now(), t,
     }))
 
+    redraw = drawProgress
     drawProgress()
     const timer = setInterval(() => { checkAbort(); drawProgress() }, 100)
     // 타이머가 프로세스를 붙잡지 않게 한다 — 화면 갱신은 종료를 미룰 이유가 없다.
@@ -255,6 +279,7 @@ export async function runTui(root, opts = {}) {
       return results
     } finally {
       clearInterval(timer)
+      redraw = paint
     }
   }
 
@@ -284,6 +309,17 @@ export async function runTui(root, opts = {}) {
       }
       if (key.ctrl && key.name === 'd') { detailExpanded = !detailExpanded; continue }
 
+      // F1: 도움말. 바닥글 두 줄로는 키의 뜻까지 담을 수 없다. 아무 키나 닫는다 —
+      // 그 키는 소비만 하고 명령으로 해석하지 않는다(도움말을 닫으려 누른
+      // Space가 항목을 고르면 안 된다).
+      if (key.name === 'f1') {
+        redraw = paintHelp
+        paintHelp()
+        await keys.next()
+        redraw = paint
+        continue
+      }
+
       // ── 검색칸에 포커스: 타이핑이 곧 검색어다(스페이스 포함, 두 단어 검색 가능).
       if (state.focus === 'search') {
         // Esc: 검색어가 있으면 지우고 검색칸에 남는다. 이미 비었으면 목록으로 내려간다.
@@ -319,8 +355,11 @@ export async function runTui(root, opts = {}) {
         continue
       }
       if (key.name === 'down' || (key.ctrl && key.name === 'n')) { state = move(state, 1); continue }
-      if (key.name === 'pageup') { state = move(state, -bodyHeight(stdout.rows ?? 24, detailExpanded)); continue }
-      if (key.name === 'pagedown') { state = move(state, bodyHeight(stdout.rows ?? 24, detailExpanded)); continue }
+      if (key.name === 'pageup') { state = move(state, -listHeight()); continue }
+      if (key.name === 'pagedown') { state = move(state, listHeight()); continue }
+      // 76개짜리 DESIGN.MD 탭에서 끝으로 가려면 PgDn을 여러 번 눌러야 했다.
+      if (key.name === 'home') { state = move(state, -state.filtered.length); continue }
+      if (key.name === 'end') { state = move(state, state.filtered.length); continue }
 
       // 탭 이동 — Tab/Shift+Tab, 좌우 화살표.
       if (key.name === 'tab') { state = moveTab(state, key.shift ? -1 : 1); continue }
@@ -389,6 +428,7 @@ export async function runTui(root, opts = {}) {
     }
   } finally {
     keys.stop()
+    stdout.off?.('resize', onResize)
     stdout.write(ALT_OFF + SHOW_CURSOR)
     stdin.setRawMode(false)
     stdin.pause()

package/lib/tui/state.mjs

@@ -73,13 +73,17 @@ export function activeTab(state) {
 // 탭별 적중 수 — 검색·필터 중에도 어느 탭에 결과가 있는지 한눈에 보이게 한다.
 // total은 필터를 타지 않는다: 분모가 함께 줄면 "이 탭에서 몇 개가 걸러졌나"를
 // 알 수 없다.
+//
+// 항목이 있는 탭은 항목만 센다 — DESIGN.MD 탭 맨 위의 작업 행 셋까지 세면
+// 항목 76개인 탭이 79로 찍혀 머리글의 "전체"와 어긋난다. 작업만 있는 탭은
+// 작업을 센다(0으로 두면 탭이 비어 보인다).
 export function tabCounts(state) {
   const hits = filterRows(state.rows, state.query).filter((r) => matchesCli(r, state.cliFilter))
-  return state.tabs.map((tab) => ({
-    tab,
-    shown: hits.filter((r) => r.section === tab).length,
-    total: state.rows.filter((r) => r.section === tab).length,
-  }))
+  return state.tabs.map((tab) => {
+    const hasItems = state.rows.some((r) => r.section === tab && r.kind === 'item')
+    const pick = (rows) => rows.filter((r) => r.section === tab && (!hasItems || r.kind === 'item'))
+    return { tab, shown: pick(hits).length, total: pick(state.rows).length }
+  })
 }
 
 export function currentRow(state) {

package/lib/update.mjs

@@ -11,9 +11,11 @@ import { RECORD_REL, managedKey, readRecord, toolVersion, writeRecord } from './
 import { LocalizedError, createT, toText } from './i18n/index.mjs'
 
 // git이 유일한 되돌리기 수단이다. 커밋되지 않은 변경 위에 덮어쓰면 사용자가
-// 잃은 것을 복구할 방법이 없다.
+// 잃은 것을 복구할 방법이 없다. 추적되지 않는 파일은 세지 않는다 — 갱신
+// 대상은 기록에 해시가 있는 추적 파일뿐이라, 스크래치 파일 하나가 --force를
+// 막을 이유가 없다.
 function assertCleanWorktree(root) {
-  const out = execFileSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8' })
+  const out = execFileSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=no'], { encoding: 'utf8' })
   if (out.trim()) {
     throw new LocalizedError('error.forceNeedsCleanTree')
   }
@@ -65,10 +67,18 @@ export async function runUpdate(root, opts = {}) {
   const drift = results.filter((r) => r.action === 'drift')
   const updated = results.filter((r) => r.action === 'update')
   const created = results.filter((r) => r.action === 'create')
+  // 어댑터가 격리해 돌려준 실패다. 요약이 갱신·신규·드리프트만 세면 이
+  // 결과는 아무 데도 나오지 않고 종료 코드도 0이라, 링크가 끊긴 채 "갱신
+  // 0건"으로 끝난다. flow.mjs의 bootstrap과 같은 형식으로 보고한다.
+  const failed = results.filter((r) => !r.ok)
 
   if (!dryRun) writeRecord(root, { ...record, managed }, { dryRun, log: say, t })
 
   log('')
+  if (failed.length > 0) {
+    say(t('bootstrap.failures', { count: failed.length }))
+    for (const f of failed) say(`  ✖ ${f.path} — ${toText(t, f.message)}`)
+  }
   say(t('update.summary', { updated: updated.length, created: created.length, drift: drift.length }))
   if (drift.length > 0) {
     say(t('update.driftHeader'))
@@ -81,5 +91,5 @@ export async function runUpdate(root, opts = {}) {
     say(t('update.driftHint'))
   }
 
-  return { results, drift, record: { ...record, managed } }
+  return { results, drift, failed, record: { ...record, managed } }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rch4com/agent-setup",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Repository-scoped bootstrap and optional-item installer for using multiple coding-agent CLIs in one repository | 여러 코딩 에이전트 CLI를 한 저장소에서 함께 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기",
   "keywords": [
     "agents-md",