triflux 2.2.0 → 2.4.0

package/bin/tfx-doctor.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // tfx-doctor — triflux doctor 바로가기
 import { dirname } from "path";
 import { fileURLToPath } from "url";

package/bin/tfx-setup.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // tfx-setup — triflux setup 바로가기
 import { dirname } from "path";
 import { fileURLToPath } from "url";

package/bin/triflux.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // triflux CLI — setup, doctor, version
-import { copyFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync } from "fs";
+import { copyFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
 import { execSync } from "child_process";
@@ -246,9 +246,98 @@ function cmdSetup() {
   console.log(`\n${DIM}설치 위치: ${CLAUDE_DIR}${RESET}\n`);
 }
 
-function cmdDoctor() {
-  console.log(`\n  ${AMBER}${BOLD}⬡ triflux doctor${RESET} ${VER}\n`);
+function cmdDoctor(options = {}) {
+  const { fix = false, reset = false } = options;
+  const modeLabel = reset ? ` ${RED}--reset${RESET}` : fix ? ` ${YELLOW}--fix${RESET}` : "";
+  console.log(`\n  ${AMBER}${BOLD}⬡ triflux doctor${RESET} ${VER}${modeLabel}\n`);
   console.log(`  ${LINE}`);
+
+  // ── reset 모드: 캐시 전체 초기화 ──
+  if (reset) {
+    section("Cache Reset");
+    const cacheDir = join(CLAUDE_DIR, "cache");
+    const resetFiles = [
+      "claude-usage-cache.json",
+      ".claude-refresh-lock",
+      "codex-rate-limits-cache.json",
+      "gemini-quota-cache.json",
+      "gemini-project-id.json",
+      "gemini-session-cache.json",
+      "gemini-rpm-tracker.json",
+      "sv-accumulator.json",
+      "mcp-inventory.json",
+      "cli-issues.jsonl",
+      "triflux-update-check.json",
+    ];
+    let cleared = 0;
+    for (const name of resetFiles) {
+      const fp = join(cacheDir, name);
+      if (existsSync(fp)) {
+        try { unlinkSync(fp); cleared++; ok(`삭제됨: ${name}`); }
+        catch (e) { fail(`삭제 실패: ${name} — ${e.message}`); }
+      }
+    }
+    if (cleared === 0) {
+      ok("삭제할 캐시 파일 없음 (이미 깨끗함)");
+    } else {
+      console.log("");
+      ok(`${BOLD}${cleared}개${RESET} 캐시 파일 초기화 완료`);
+    }
+    info("다음 세션 시작 시 캐시가 새로 생성됩니다");
+    console.log(`\n  ${LINE}`);
+    console.log(`  ${GREEN_BRIGHT}${BOLD}✓ 캐시 초기화 완료${RESET}\n`);
+    return;
+  }
+
+  // ── fix 모드: 파일 동기화 + 캐시 정리 후 진단 ──
+  if (fix) {
+    section("Auto Fix");
+    syncFile(
+      join(PKG_ROOT, "scripts", "cli-route.sh"),
+      join(CLAUDE_DIR, "scripts", "cli-route.sh"),
+      "cli-route.sh"
+    );
+    syncFile(
+      join(PKG_ROOT, "hud", "hud-qos-status.mjs"),
+      join(CLAUDE_DIR, "hud", "hud-qos-status.mjs"),
+      "hud-qos-status.mjs"
+    );
+    // 스킬 동기화
+    const fSkillsSrc = join(PKG_ROOT, "skills");
+    const fSkillsDst = join(CLAUDE_DIR, "skills");
+    if (existsSync(fSkillsSrc)) {
+      let sc = 0, st = 0;
+      for (const name of readdirSync(fSkillsSrc)) {
+        const src = join(fSkillsSrc, name, "SKILL.md");
+        const dst = join(fSkillsDst, name, "SKILL.md");
+        if (!existsSync(src)) continue;
+        st++;
+        const dstDir = dirname(dst);
+        if (!existsSync(dstDir)) mkdirSync(dstDir, { recursive: true });
+        if (!existsSync(dst)) { copyFileSync(src, dst); sc++; }
+        else if (readFileSync(src, "utf8") !== readFileSync(dst, "utf8")) { copyFileSync(src, dst); sc++; }
+      }
+      if (sc > 0) ok(`스킬: ${sc}/${st}개 업데이트됨`);
+      else ok(`스킬: ${st}개 최신 상태`);
+    }
+    // 에러/스테일 캐시 정리
+    const fCacheDir = join(CLAUDE_DIR, "cache");
+    const staleNames = ["claude-usage-cache.json", ".claude-refresh-lock", "codex-rate-limits-cache.json"];
+    let cleaned = 0;
+    for (const name of staleNames) {
+      const fp = join(fCacheDir, name);
+      if (!existsSync(fp)) continue;
+      try {
+        const parsed = JSON.parse(readFileSync(fp, "utf8"));
+        if (parsed.error || name.startsWith(".")) { unlinkSync(fp); cleaned++; ok(`에러 캐시 정리: ${name}`); }
+      } catch { try { unlinkSync(fp); cleaned++; ok(`손상된 캐시 정리: ${name}`); } catch {} }
+    }
+    if (cleaned === 0) info("에러 캐시 없음");
+    console.log(`\n  ${LINE}`);
+    info("수정 완료 — 아래 진단 결과를 확인하세요");
+    console.log("");
+  }
+
   let issues = 0;
 
   // 1. cli-route.sh
@@ -673,6 +762,8 @@ ${updateNotice}
 
     ${WHITE_BRIGHT}tfx setup${RESET}      ${GRAY}파일 동기화 + HUD 설정${RESET}
     ${WHITE_BRIGHT}tfx doctor${RESET}     ${GRAY}CLI 진단 + 이슈 확인${RESET}
+    ${DIM}  --fix${RESET}        ${GRAY}진단 + 자동 수정${RESET}
+    ${DIM}  --reset${RESET}      ${GRAY}캐시 전체 초기화${RESET}
     ${WHITE_BRIGHT}tfx update${RESET}     ${GRAY}최신 버전으로 업데이트${RESET}
     ${WHITE_BRIGHT}tfx list${RESET}       ${GRAY}설치된 스킬 목록${RESET}
     ${WHITE_BRIGHT}tfx version${RESET}    ${GRAY}버전 표시${RESET}
@@ -683,6 +774,7 @@ ${updateNotice}
     ${WHITE_BRIGHT}/tfx-codex${RESET}      ${GRAY}Codex 전용 모드${RESET}
     ${BLUE}/tfx-gemini${RESET}     ${GRAY}Gemini 전용 모드${RESET}
     ${AMBER}/tfx-setup${RESET}      ${GRAY}HUD 설정 + 진단${RESET}
+    ${YELLOW}/tfx-doctor${RESET}     ${GRAY}진단 + 수리 + 캐시 초기화${RESET}
 
   ${LINE}
   ${GRAY}github.com/tellang/triflux${RESET}
@@ -695,7 +787,12 @@ const cmd = process.argv[2] || "help";
 
 switch (cmd) {
   case "setup":   cmdSetup(); break;
-  case "doctor":  cmdDoctor(); break;
+  case "doctor": {
+    const fix = process.argv.includes("--fix");
+    const reset = process.argv.includes("--reset");
+    cmdDoctor({ fix, reset });
+    break;
+  }
   case "update":  cmdUpdate(); break;
   case "list": case "ls": cmdList(); break;
   case "version": case "--version": case "-v": cmdVersion(); break;

package/hud/hud-qos-status.mjs

@@ -7,7 +7,7 @@ import https from "node:https";
 import { createHash } from "node:crypto";
 import { spawn, execSync } from "node:child_process";
 
-const VERSION = "1.9";
+const VERSION = "2.0";
 
 // ============================================================================
 // ANSI 색상 (OMC colors.js 스키마 일치)
@@ -109,7 +109,15 @@ const ACCOUNTS_STATE_PATH = join(homedir(), ".omc", "state", "cli_accounts_state
 const CLAUDE_CREDENTIALS_PATH = join(homedir(), ".claude", ".credentials.json");
 const CLAUDE_USAGE_CACHE_PATH = join(homedir(), ".claude", "cache", "claude-usage-cache.json");
 const OMC_PLUGIN_USAGE_CACHE_PATH = join(homedir(), ".claude", "plugins", "oh-my-claudecode", ".usage-cache.json");
-const CLAUDE_USAGE_STALE_MS = 5 * 60 * 1000; // 5분 캐시 (OMC 플러그인과 API 충돌 방지)
+const CLAUDE_USAGE_STALE_MS_SOLO = 5 * 60 * 1000; // OMC 없을 때: 5분 캐시
+const CLAUDE_USAGE_STALE_MS_WITH_OMC = 15 * 60 * 1000; // OMC 있을 때: 15분 (OMC가 30초마다 갱신)
+
+// OMC 활성 여부에 따라 캐시 TTL 동적 결정
+function getClaudeUsageStaleMs() {
+  return existsSync(OMC_PLUGIN_USAGE_CACHE_PATH)
+    ? CLAUDE_USAGE_STALE_MS_WITH_OMC
+    : CLAUDE_USAGE_STALE_MS_SOLO;
+}
 const CLAUDE_USAGE_429_BACKOFF_MS = 10 * 60 * 1000; // 429 에러 시 10분 backoff
 const CLAUDE_USAGE_ERROR_BACKOFF_MS = 3 * 60 * 1000; // 기타 에러 시 3분 backoff
 const CLAUDE_API_TIMEOUT_MS = 10_000;
@@ -263,7 +271,13 @@ function selectTier(stdin, claudeUsage = null) {
 
   // 1) 명시적 tier 강제 설정
   const forcedTier = hudConfig?.tier;
-  if (["full", "normal", "compact", "nano"].includes(forcedTier)) return forcedTier;
+  if (["full", "normal", "compact", "nano", "micro"].includes(forcedTier)) return forcedTier;
+
+  // 1.5) maxLines=1 → micro (1줄 모드: 알림 배너/분할화면 대응)
+  if (Number(hudConfig?.lines) === 1) return "micro";
+
+  // 1.6) 분할화면 감지: 열 < 80이면 micro (COMPACT_MODE보다 우선)
+  if ((getTerminalColumns() || 120) < 80) return "micro";
 
   // 2) 기존 모드 플래그 존중
   if (MINIMAL_MODE) return "nano";
@@ -275,6 +289,7 @@ function selectTier(stdin, claudeUsage = null) {
   // 4) 터미널 행/열에서 상태영역 예산 추정
   const rows = getTerminalRows();
   const cols = getTerminalColumns() || 120;
+
   let budget;
   if (rows >= 40) budget = 6;
   else if (rows >= 35) budget = 5;
@@ -285,6 +300,7 @@ function selectTier(stdin, claudeUsage = null) {
 
   // 5) 인디케이터 줄 추정
   let indicatorRows = 1; // bypass permissions (거의 항상 표시)
+  indicatorRows += 1; // 선행 개행 가드 (알림 배너 우회용 빈 줄)
   const contextPercent = getContextPercent(stdin);
   if (contextPercent >= 85) indicatorRows += 1; // "Context low" 배너
   // Claude Code 사용량 경고 (노란색 배너: "You've used X% of your ... limit")
@@ -301,7 +317,8 @@ function selectTier(stdin, claudeUsage = null) {
     const totalVisualRows = (3 * visualRowsPerLine) + indicatorRows;
     if (totalVisualRows <= budget) return tier;
   }
-  return "nano";
+  // 어떤 tier도 budget에 안 맞으면 micro (1줄 모드)
+  return "micro";
 }
 
 // full tier 전용: 게이지 바 접두사 (normal 이하 tier에서는 빈 문자열)
@@ -415,6 +432,50 @@ function renderAlignedRows(rows) {
   });
 }
 
+// micro tier: 모든 프로바이더를 1줄로 압축 (알림 배너/분할화면 대응)
+// 형식: c:16/3 x:5/2 g:∞ sv:143% ctx:53%
+function getMicroLine(stdin, claudeUsage, codexBuckets, geminiSession, geminiBucket, combinedSvPct) {
+  const ctx = getContextPercent(stdin);
+
+  // Claude 5h/1w
+  const cF = claudeUsage ? clampPercent(claudeUsage.fiveHourPercent ?? 0) : null;
+  const cW = claudeUsage ? clampPercent(claudeUsage.weeklyPercent ?? 0) : null;
+  const cVal = cF != null
+    ? `${colorByProvider(cF, `${cF}`, claudeOrange)}${dim("/")}${colorByProvider(cW, `${cW}`, claudeOrange)}`
+    : dim("--/--");
+
+  // Codex 5h/1w
+  let xVal = dim("--/--");
+  if (codexBuckets) {
+    const mb = codexBuckets.codex || codexBuckets[Object.keys(codexBuckets)[0]];
+    if (mb) {
+      const xF = isResetPast(mb.primary?.resets_at) ? 0 : clampPercent(mb.primary?.used_percent ?? 0);
+      const xW = isResetPast(mb.secondary?.resets_at) ? 0 : clampPercent(mb.secondary?.used_percent ?? 0);
+      xVal = `${colorByProvider(xF, `${xF}`, codexWhite)}${dim("/")}${colorByProvider(xW, `${xW}`, codexWhite)}`;
+    }
+  }
+
+  // Gemini
+  let gVal;
+  if (geminiBucket) {
+    const gU = clampPercent(geminiBucket.usedPercent ?? 0);
+    gVal = colorByProvider(gU, `${gU}`, geminiBlue);
+  } else if ((geminiSession?.total || 0) > 0) {
+    gVal = geminiBlue("\u221E");
+  } else {
+    gVal = dim("--");
+  }
+
+  // sv (trimmed)
+  const sv = formatSvPct(combinedSvPct || 0).trim();
+
+  return `${bold(claudeOrange("c"))}${dim(":")}${cVal} ` +
+    `${bold(codexWhite("x"))}${dim(":")}${xVal} ` +
+    `${bold(geminiBlue("g"))}${dim(":")}${gVal} ` +
+    `${dim("sv:")}${sv} ` +
+    `${dim("ctx:")}${colorByPercent(ctx, `${ctx}%`)}`;
+}
+
 function clampPercent(value) {
   const numeric = Number(value);
   if (!Number.isFinite(numeric)) return 0;
@@ -444,7 +505,9 @@ function normalizeTimeToken(value) {
 
 function formatTimeCell(value) {
   const text = normalizeTimeToken(value);
-  return `(${text.padStart(TIME_CELL_INNER_WIDTH, "0")})`;
+  // 시간값(숫자 포함)은 0패딩, 비시간값(n/a 등)은 공백패딩
+  const padChar = /\d/.test(text) ? "0" : " ";
+  return `(${text.padStart(TIME_CELL_INNER_WIDTH, padChar)})`;
 }
 
 // 주간(d/h) 전용 — 최대 7d00h(5자)이므로 공백 불필요
@@ -635,7 +698,7 @@ function readClaudeUsageSnapshot() {
 
   // 1차: 자체 캐시에 유효 데이터가 있는 경우
   if (cache?.data) {
-    const isFresh = ageMs < CLAUDE_USAGE_STALE_MS;
+    const isFresh = ageMs < getClaudeUsageStaleMs();
     return { data: cache.data, shouldRefresh: !isFresh };
   }
 
@@ -651,10 +714,9 @@ function readClaudeUsageSnapshot() {
         writeClaudeUsageCache(omcCache.data);
         return { data: omcCache.data, shouldRefresh: false };
       }
-      // stale OMC fallback 또는 기본 0%
+      // stale OMC fallback 또는 null (--% 플레이스홀더 표시, 가짜 0% 방지)
       const staleData = omcCache?.data?.fiveHourPercent != null ? stripStaleResets(omcCache.data) : null;
-      const fallback = staleData || { fiveHourPercent: 0, weeklyPercent: 0, fiveHourResetsAt: null, weeklyResetsAt: null };
-      return { data: fallback, shouldRefresh: false };
+      return { data: staleData, shouldRefresh: false };
     }
   }
 
@@ -665,14 +727,14 @@ function readClaudeUsageSnapshot() {
     const omcAge = Number.isFinite(omcCache.timestamp) ? Date.now() - omcCache.timestamp : Number.MAX_SAFE_INTEGER;
     if (omcAge < OMC_CACHE_MAX_AGE_MS) {
       writeClaudeUsageCache(omcCache.data);
-      return { data: omcCache.data, shouldRefresh: omcAge > CLAUDE_USAGE_STALE_MS };
+      return { data: omcCache.data, shouldRefresh: omcAge > getClaudeUsageStaleMs() };
     }
     // stale이어도 data: null보다는 오래된 데이터를 fallback으로 표시
     return { data: stripStaleResets(omcCache.data), shouldRefresh: true };
   }
 
-  // 캐시/fallback 모두 없음: 기본 0% 표시 + 리프레시 시도 (--% 방지)
-  return { data: { fiveHourPercent: 0, weeklyPercent: 0, fiveHourResetsAt: null, weeklyResetsAt: null }, shouldRefresh: true };
+  // 캐시/fallback 모두 없음: null 반환 → --% 플레이스홀더 + 리프레시 시도
+  return { data: null, shouldRefresh: true };
 }
 
 function writeClaudeUsageCache(data, errorInfo = null) {
@@ -732,7 +794,7 @@ function scheduleClaudeUsageRefresh() {
     const omcCache = readJson(OMC_PLUGIN_USAGE_CACHE_PATH, null);
     if (omcCache?.data?.fiveHourPercent != null) {
       const omcAge = Number.isFinite(omcCache.timestamp) ? Date.now() - omcCache.timestamp : Infinity;
-      if (omcAge < CLAUDE_USAGE_STALE_MS) {
+      if (omcAge < getClaudeUsageStaleMs()) {
         writeClaudeUsageCache(omcCache.data); // HUD 캐시에 복사만
         return;
       }
@@ -751,7 +813,7 @@ function scheduleClaudeUsageRefresh() {
 
   try {
     const child = spawn(process.execPath, [scriptPath, CLAUDE_REFRESH_FLAG], {
-      detached: true,
+      detached: process.platform !== "win32",
       stdio: "ignore",
       windowsHide: true,
     });
@@ -1050,7 +1112,7 @@ function scheduleGeminiQuotaRefresh(accountId) {
       process.execPath,
       [scriptPath, GEMINI_REFRESH_FLAG, "--account", accountId || "gemini-main"],
       {
-        detached: true,
+        detached: process.platform !== "win32",
         stdio: "ignore",
         windowsHide: true,
       },
@@ -1082,7 +1144,7 @@ function scheduleCodexRateLimitRefresh() {
   if (!scriptPath) return;
   try {
     const child = spawn(process.execPath, [scriptPath, CODEX_REFRESH_FLAG], {
-      detached: true,
+      detached: process.platform !== "win32",
       stdio: "ignore",
       windowsHide: true,
     });
@@ -1113,7 +1175,7 @@ function scheduleGeminiSessionRefresh() {
   if (!scriptPath) return;
   try {
     const child = spawn(process.execPath, [scriptPath, GEMINI_SESSION_REFRESH_FLAG], {
-      detached: true,
+      detached: process.platform !== "win32",
       stdio: "ignore",
       windowsHide: true,
     });
@@ -1486,6 +1548,14 @@ async function main() {
   // 인디케이터 인식 tier 선택 (stdin + Claude 사용량 기반)
   CURRENT_TIER = selectTier(stdin, claudeUsageSnapshot.data);
 
+  // micro tier: 1줄 모드 (알림 배너/분할화면 대응)
+  if (CURRENT_TIER === "micro") {
+    const microLine = getMicroLine(stdin, claudeUsageSnapshot.data, codexBuckets,
+      geminiSession, geminiBucket, combinedSvPct);
+    process.stdout.write(`\x1b[0m${microLine}\n`);
+    return;
+  }
+
   const codexQuotaData = codexBuckets ? { type: "codex", buckets: codexBuckets } : null;
   const geminiQuotaData = { type: "gemini", quotaBucket: geminiBucket, session: geminiSession };
 
@@ -1509,12 +1579,13 @@ async function main() {
     if (!geminiActive) outputLines[2] = `${DIM}${stripAnsi(outputLines[2])}${RESET}`;
   }
 
-  // Context low 메시지 뒤에 HUD가 분리되도록 선행 개행 추가
+  // 선행 개행: 알림 배너(노란 글씨)가 빈 첫 줄에 오도록 → HUD 내용 보호
+  // Context low(≥85%) 시 추가 개행으로 배너 분리
   const contextPercent = getContextPercent(stdin);
-  const contextLowPrefix = contextPercent >= 85 ? "\n" : "";
+  const leadingBreaks = contextPercent >= 85 ? "\n\n" : "\n";
   // 줄별 RESET: Claude Code TUI 스타일 간섭 방지 (색상 밝기 버그 수정)
   const resetedLines = outputLines.map(line => `\x1b[0m${line}`);
-  process.stdout.write(`${contextLowPrefix}${resetedLines.join("\n")}\n`);
+  process.stdout.write(`${leadingBreaks}${resetedLines.join("\n")}\n`);
 }
 
 main().catch(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/skills/tfx-auto/SKILL.md

@@ -656,3 +656,10 @@ t3 → t4 (t3-implementation.md, 4.1KB)
 |------|------|
 | `~/.claude/scripts/cli-route.sh` | CLI 라우팅 래퍼 (필수) |
 | `/omc-teams` | tmux 기반 CLI 워커 (별도) |
+
+## Troubleshooting
+
+CLI 실행 오류나 HUD 문제 발생 시:
+1. `/tfx-doctor` — 진단 실행
+2. `/tfx-doctor --fix` — 자동 수정
+3. `/tfx-doctor --reset` — 캐시 초기화

package/skills/tfx-codex/SKILL.md

@@ -1,12 +1,12 @@
----
-name: tfx-codex
-description: Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다.
-triggers:
-  - tfx-codex
-argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""
----
-
-# tfx-codex — Codex-Only 오케스트레이터
+---
+name: tfx-codex
+description: Codex-Only 오케스트레이터. tfx-auto 워크플로우를 Codex 전용으로 고정합니다.
+triggers:
+  - tfx-codex
+argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""
+---
+
+# tfx-codex — Codex-Only 오케스트레이터
 
 > Codex CLI만 사용하여 모든 외부 CLI 작업을 라우팅합니다.
 > Gemini CLI가 없는 환경에서 사용합니다.
@@ -59,3 +59,10 @@ argument-hint: "\"작업 설명\" | N:codex \"작업 설명\""
 
 - [Codex CLI](https://github.com/openai/codex): `npm install -g @openai/codex`
 - Gemini CLI 불필요
+
+## Troubleshooting
+
+문제가 발생하면:
+1. `/tfx-doctor` — 진단 실행
+2. `/tfx-doctor --fix` — 자동 수정
+3. `/tfx-doctor --reset` — 캐시 초기화 (HUD 이상 시)

package/skills/tfx-doctor/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: tfx-doctor
+description: >
+  triflux 진단 및 수리 도구. CLI 미발견, HUD 미표시, 캐시 오류,
+  스킬 미설치 등 문제를 진단하고 자동 수정합니다.
+  Use when: not working, broken, error, 안 돼, 이상해, 에러, 캐시, reset
+triggers:
+  - tfx-doctor
+argument-hint: "[--fix|--reset]"
+---
+
+# tfx-doctor — triflux 진단 및 수리
+
+> 뭔가 안 될 때, HUD가 이상할 때, CLI가 안 보일 때 실행하세요.
+
+## 사용법
+
+```
+/tfx-doctor            ← 진단만 (읽기 전용)
+/tfx-doctor --fix      ← 진단 + 자동 수정
+/tfx-doctor --reset    ← 캐시 전체 초기화
+```
+
+## 동작
+
+### 기본 모드 (`/tfx-doctor`)
+
+`triflux doctor`를 실행하여 다음을 진단합니다:
+
+- cli-route.sh 설치 상태
+- HUD 설치 및 설정 상태
+- Codex/Gemini/Claude CLI 경로 (크로스 셸)
+- 스킬 설치 상태
+- 플러그인 등록 상태
+- MCP 인벤토리 캐시
+- CLI 이슈 트래커
+
+### 수정 모드 (`/tfx-doctor --fix`)
+
+진단 전에 자동 수정을 시도합니다:
+
+1. cli-route.sh, HUD, 스킬 파일 재동기화
+2. 에러/손상된 캐시 파일 정리
+3. 수정 완료 후 전체 진단 실행 → 결과 보고
+
+### 초기화 모드 (`/tfx-doctor --reset`)
+
+HUD 캐시 및 모든 triflux 관련 캐시를 전체 삭제합니다:
+
+| 삭제 대상 | 설명 |
+|-----------|------|
+| claude-usage-cache.json | Claude 사용량 캐시 |
+| codex-rate-limits-cache.json | Codex 레이트 리밋 캐시 |
+| gemini-quota/session/rpm cache | Gemini 할당량/세션/RPM 캐시 |
+| sv-accumulator.json | 절약량 누적 캐시 |
+| mcp-inventory.json | MCP 서버 인벤토리 |
+| cli-issues.jsonl | CLI 이슈 로그 |
+| triflux-update-check.json | 업데이트 확인 캐시 |
+| .claude-refresh-lock | 리프레시 락 파일 |
+
+초기화 후 다음 세션에서 캐시가 새로 생성됩니다.
+
+## 실행 방법
+
+```bash
+# 진단만
+Bash("triflux doctor")
+
+# 진단 + 자동 수정
+Bash("triflux doctor --fix")
+
+# 캐시 전체 초기화
+Bash("triflux doctor --reset")
+```
+
+결과를 사용자에게 보고합니다.
+
+## 자동 제안 트리거
+
+사용자가 다음과 같이 말하면 이 스킬 실행을 고려하세요:
+
+- "HUD가 안 보여" / "HUD 이상해" / "상태줄이 안 나와"
+- "codex/gemini가 안 돼" / "CLI 안 됨"
+- "캐시 초기화" / "리셋" / "reset"
+- "triflux 안 돼" / "뭔가 안 돼" / "에러"
+
+## 에러 처리
+
+| 상황 | 처리 |
+|------|------|
+| 캐시 디렉토리 없음 | 정상 — 삭제할 파일 없음 보고 |
+| 파일 삭제 권한 없음 | 수동 삭제 안내 |
+| --fix 후에도 이슈 남음 | Codex/Gemini 설치는 수동 필요 안내 |

package/skills/tfx-gemini/SKILL.md

@@ -1,12 +1,12 @@
----
-name: tfx-gemini
-description: Gemini-Only 오케스트레이터. tfx-auto 워크플로우를 Gemini 전용으로 고정합니다.
-triggers:
-  - tfx-gemini
-argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""
----
-
-# tfx-gemini — Gemini-Only 오케스트레이터
+---
+name: tfx-gemini
+description: Gemini-Only 오케스트레이터. tfx-auto 워크플로우를 Gemini 전용으로 고정합니다.
+triggers:
+  - tfx-gemini
+argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""
+---
+
+# tfx-gemini — Gemini-Only 오케스트레이터
 
 > Gemini CLI만 사용하여 모든 외부 CLI 작업을 라우팅합니다.
 > Codex CLI가 없는 환경에서 사용합니다.
@@ -76,3 +76,10 @@ argument-hint: "\"작업 설명\" | N:gemini \"작업 설명\""
 
 - [Gemini CLI](https://github.com/google-gemini/gemini-cli): `npm install -g @google/gemini-cli`
 - Codex CLI 불필요
+
+## Troubleshooting
+
+문제가 발생하면:
+1. `/tfx-doctor` — 진단 실행
+2. `/tfx-doctor --fix` — 자동 수정
+3. `/tfx-doctor --reset` — 캐시 초기화 (HUD 이상 시)

package/skills/tfx-setup/SKILL.md

@@ -1,12 +1,12 @@
----
-name: tfx-setup
-description: triflux 초기 설정 및 진단을 수행합니다.
-triggers:
-  - tfx-setup
-argument-hint: "[doctor]"
----
-
-# tfx-setup — triflux 초기 설정 및 진단
+---
+name: tfx-setup
+description: triflux 초기 설정 및 진단을 수행합니다.
+triggers:
+  - tfx-setup
+argument-hint: "[doctor]"
+---
+
+# tfx-setup — triflux 초기 설정 및 진단
 
 > 설치 후 최초 1회 실행 권장. HUD 설정, CLI 확인, 전체 진단을 수행합니다.
 
@@ -95,3 +95,10 @@ Bash("triflux doctor")
 | `settings.json` 파싱 실패 | 백업 생성 후 새로 작성 |
 | 기존 statusLine이 다른 HUD | 사용자에게 덮어쓸지 확인 |
 | node.exe 경로에 공백 | 큰따옴표로 감싸기 |
+
+## Troubleshooting
+
+설정 후에도 문제가 있으면:
+1. `/tfx-doctor` — 상세 진단 실행
+2. `/tfx-doctor --fix` — 파일 동기화 + 캐시 정리
+3. `/tfx-doctor --reset` — 캐시 전체 초기화 (HUD 이상 시)