claude-token-saver 3.19.0 → 3.20.1

package/README.en.md

@@ -4,54 +4,64 @@
 
 # claude-token-saver
 
-## 🔀 Routing saved — the reason this tool exists
+**Moves the easy work your expensive model keeps repeating onto cheaper ones, and shows what that actually saved — measured, in your statusline.** Zero dependencies, one-line install.
 
 ![statusline example — routing savings on row 1, diagnostics on row 2](./docs/statusline.png)
 
-**That figure on the first statusline row is the headline metric.** It is money actually saved by moving the easy work your expensive model kept repeating onto cheaper ones, and right beside it is which model that money moved off, and onto what.
+```bash
+npm i -g claude-token-saver
+```
 
-The other half of the savings comes from the **🅷 Harness and ratchet**. The harness blocks the habits that waste the most tokens — completion claims with no evidence, skipped verification — with five principles, and the ratchet freezes each error you hit into a rule so it does not recur. The measured −18.6% figure below comes from adopting those two, not from routing ([details](#real-world-impact--beforeafter-report)); routing savings sit on top of it. One install sets up all three.
+## Three parts, working together
 
-It is not an estimate or a marketing number: it comes out of a **ledger**. For every delegated subagent run it records
+| | What it does | Effect |
+|---|---|---|
+| 🔀 **Routing** | Delegates recurring easy work to cheaper models | Savings recorded per run in a ledger |
+| 🅷 **Harness** | Blocks the token-burning habits: unevidenced "done", skipped verification (5 principles) | **−18.6% cost** ([measured](#real-world-impact--beforeafter-report)) |
+| ⚙️ **Ratchet** | Freezes each error you hit into a rule | Same mistake stops recurring |
+
+One install sets up all three. The measured −18.6% comes from the harness and ratchet; routing savings sit on top of it.
 
-- **before** — the model that handled this category before the rule existed
-- **after** — the model that actually ran it
-- **the gap** — the same token counts priced against both
+## 🔀 The savings figure is a ledger entry, not an estimate
 
-so `route-scan savings` traces **every dollar back to the rule that produced it.**
+Every delegated run is recorded like this:
+
+```
+   before             after          gap
+  claude-opus-5  →  haiku-4-5   =   $0.57
+  (the model         (what          (same token counts,
+   handling this      actually       priced against
+   before the rule)   ran it)        both models)
+```
 
 ```bash
-$ claude-token-saver route-scan savings
+$ claude-token-saver route-scan savings      # trace every dollar back to its rule
 
 🔀 Routing saved, lifetime $2.09  (last 7d $1.40 · 30d $2.09)
 
 By model change:
-  claude-fable-5 → claude-sonnet-5           —  1 run, $0.72
-  claude-opus-5 → claude-haiku-4-5           —  1 run, $0.57
+  claude-fable-5 → claude-sonnet-5   —  1 run, $0.72
+  claude-opus-5 → claude-haiku-4-5   —  1 run, $0.57
 
 By run (newest first):
   2026-08-22    $0.51  claude-fable-5 → claude-haiku-4-5
             rule: T2|paste|-Users-me-projects-my-app
 ```
 
-**Counting honestly is the design principle.** Delegations no registered rule covers — `Explore`, your own agents, a plugin's subagents — were not routed by this tool, so they are **excluded**. When the pricing table cannot recognize a model id, the run is **dropped** rather than priced wrong. The number may be small, but it is real.
+**What is excluded** — an honest number beats a big one:
 
-```bash
-npm i -g claude-token-saver   # postinstall auto-registers the statusline + Skill
-```
+- Delegations no registered rule covers (`Explore`, your own agents, plugin subagents): this tool did not route them.
+- Model ids the pricing table cannot recognize: the run is dropped rather than priced wrong.
 
 ---
 
-## ⚡ Why — the 30-second pitch
+## ⚡ What else the statusline catches
 
 | | |
 |---|---|
-| 🔀 **Measured routing savings** | Every delegated run's saving is recorded in a ledger → lifetime total plus the model-change breakdown on statusline row 1 (audit it all with `route-scan savings`) |
-| 🎯 **Model-fitting delegation** | Classifies the easy work your expensive model (opus/fable) keeps repeating into tiers (T0/T1/T2) → promotes haiku/sonnet delegation rules, auto-applied from the next session |
-| 💸 **−18.6% measured cost** | Cost per user message $2.35 → $1.91 after adopting harness+ratchet (author's logs, [details](#real-world-impact--beforeafter-report)) |
-| 🚨 **No surprise rate limits** | Instant warning when the 5H/7D window hits 90% + `handoff` to back up your work |
-| 🧠 **Cache waste detection** | Hit rate, TTL countdown, 1M-context detection — token spikes diagnosed with issue codes |
-| 🅷 **Stop repeating mistakes** | Recurring errors get promoted to ratchet rules — auto-applied from the next session |
+| 🚨 **No surprise rate limits** | Warns when the 5H/7D window hits 90%; `handoff` backs up your work |
+| 🧠 **Cache waste detection** | Hit rate, TTL, 1M-context detection — spikes diagnosed with issue codes |
+| 🇰🇷 **Korean writing guidance** | Enabled automatically on a Korean locale ([below](#-korean-writing-guidance)) |
 
 ## Not a router — 60 seconds
 
@@ -369,6 +379,9 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.20.0 (2026-08-22)
+- **The README opening is now scannable** — prose replaced by a one-line summary, the screenshot, and the install command up top. The three parts (routing, harness, ratchet) are a table; how a saving is computed (before → after → gap) is a diagram. The old 30-second pitch table, which repeated all of it, now lists only what the statusline additionally catches.
+
 ### v3.19.0 (2026-08-22)
 - **Korean writing guidance** — corrects how Claude writes Korean (dropped sentence parts, noun-stopped sentences, translationese, em-dash overuse), injected once per session. Claude Code's output styles occupy a single global slot and must be configured per machine; this ships the guidance in the package and delivers it through the SessionStart hook already installed, so it **applies in every project and leaves the output-style slot free.** Text vendored from [fluent-korean](https://github.com/snflkd/fluent-korean) (Copyright (c) 2026 snflkd, MIT), license included.
 - **Decided at install time** — a Korean system locale turns it on; anything else leaves it off. Your own on/off choice is preserved, so upgrades never override it. Skip with `CTS_NO_KOREAN=1`; a `가` chip shows in the statusline when active.

package/README.md

@@ -4,54 +4,64 @@
 
 # claude-token-saver
 
-## 🔀 Routing saved: 이 도구가 존재하는 이유
+**비싼 모델이 반복하던 쉬운 작업을 싼 모델로 내려보내고, 그렇게 아낀 금액을 statusline에 실측으로 보여 줍니다.** 의존성 0, 설치 한 줄.
 
 ![statusline 예시. 첫째 줄은 라우팅 절감액이고 둘째 줄은 진단 칩입니다](./docs/statusline.png)
 
-**statusline 첫째 줄의 이 금액이 이 도구의 대표 지표입니다.** 비싼 모델이 반복해서 처리해 온 쉬운 작업을 더 싼 모델에 넘겨서 **실제로 절감한 비용**이며, 그 옆에는 어느 모델에서 어느 모델로 작업이 옮겨 가면서 그 금액이 발생했는지가 함께 표시됩니다.
+```bash
+npm i -g claude-token-saver
+```
+
+## 세 가지가 함께 돌아갑니다
+
+| | 하는 일 | 효과 |
+|---|---|---|
+| 🔀 **라우팅** | 반복되는 쉬운 작업을 더 싼 모델에 위임 | 절감액을 원장에 실측 기록 |
+| 🅷 **Harness** | 증거 없는 완료 보고·검증 생략 차단 (5원칙) | **비용 −18.6%** ([실측](#실제-효과-도입-전후-리포트)) |
+| ⚙️ **Ratchet** | 한 번 겪은 에러를 룰로 고정 | 같은 실수 재발 차단 |
 
-이 금액을 만들어 내는 나머지 절반은 **🅷 Harness와 ratchet**입니다. Harness는 증거 없는 완료 보고와 검증 생략처럼 토큰을 가장 많이 낭비하는 습관을 다섯 가지 원칙으로 막고, ratchet은 한 번 겪은 에러를 룰로 굳혀 같은 실수를 반복하지 않게 합니다. 실제로 비용을 18.6% 줄인 실측치는 라우팅이 아니라 이 두 가지를 도입한 전후를 비교한 값입니다([상세](#실제-효과-도입-전후-리포트)). 라우팅 절감액은 그 위에 얹히는 몫이며, 세 기능은 설치 한 번으로 함께 적용됩니다.
+설치 한 번이면 셋 다 적용됩니다. 실측 −18.6%는 Harness와 ratchet의 몫이고, 라우팅 절감액은 그 위에 얹힙니다.
 
-이 숫자는 추정치나 홍보 문구가 아니라 **원장(ledger)에 기록된 실측값입니다.** 위임된 서브에이전트 실행 하나하나마다 다음 세 가지를 기록합니다.
+## 🔀 절감액은 추정이 아니라 원장 기록입니다
 
-- **기준 모델(before):** 룰을 승격하기 전에 그 유형을 실제로 처리하던 모델입니다.
-- **실행 모델(after):** 그 작업을 실제로 처리한 모델입니다.
-- **차액:** 동일한 토큰량에 두 모델의 가격표를 각각 적용해 계산한 값입니다.
+위임된 실행 하나하나를 이렇게 기록합니다.
 
-그래서 `route-scan savings` 명령 한 번이면 **모든 금액을 어떤 룰이 만들어 냈는지까지 거슬러 확인할 수 있습니다.**
+```
+   기준 모델          실행 모델         차액
+  claude-opus-5  →  haiku-4-5   =   $0.57
+  (룰 승격 전         (실제로         (같은 토큰량에
+   이 유형을           처리한          두 모델 가격표를
+   처리하던 모델)      모델)           각각 적용)
+```
 
 ```bash
-$ claude-token-saver route-scan savings
+$ claude-token-saver route-scan savings      # 모든 금액을 룰 단위까지 역추적
 
 🔀 라우팅 절감 누적 $2.09  (최근 7일 $1.40 · 30일 $2.09)
 
 모델 이동별:
-  claude-fable-5 → claude-sonnet-5           —  1회, $0.72
-  claude-opus-5 → claude-haiku-4-5           —  1회, $0.57
+  claude-fable-5 → claude-sonnet-5   —  1회, $0.72
+  claude-opus-5 → claude-haiku-4-5   —  1회, $0.57
 
 실행별 (최근순):
   2026-08-22    $0.51  claude-fable-5 → claude-haiku-4-5
             룰: T2|paste|-Users-me-projects-my-app
 ```
 
-**정직하게 집계하는 것이 이 도구의 설계 원칙입니다.** 등록된 룰이 담당하지 않는 위임(`Explore`, 사용자가 직접 만든 에이전트, 플러그인이 제공하는 에이전트)은 이 도구가 라우팅한 결과가 아니므로 **금액에서 제외합니다.** 가격표가 모델명을 인식하지 못하는 경우에도 틀린 금액을 표시하는 대신 **그 실행을 집계에서 제외합니다.** 그래서 금액이 작게 나올 수는 있어도, 표시되는 값은 언제나 실제로 절감한 금액입니다.
+**집계에서 빼는 것들** — 정직한 숫자가 작은 숫자보다 낫기 때문입니다.
 
-```bash
-npm i -g claude-token-saver   # postinstall이 statusline + Skill 자동 등록
-```
+- 등록된 룰이 담당하지 않는 위임(`Explore`, 직접 만든 에이전트, 플러그인 에이전트): 이 도구가 라우팅한 결과가 아닙니다.
+- 가격표가 인식하지 못하는 모델명: 틀린 금액을 쓰느니 그 실행을 뺍니다.
 
 ---
 
-## ⚡ 왜 쓰는가: 30초 요약
+## ⚡ 그 밖에 statusline이 잡아 주는 것
 
 | | |
 |---|---|
-| 🔀 **라우팅 절감액 실측** | 위임으로 절감한 금액을 실행 단위로 원장에 기록하고, statusline 첫째 줄에 누적액과 모델 이동 내역을 함께 표시합니다 (`route-scan savings`로 전수 확인) |
-| 🎯 **모델 피팅 위임** | 상위 모델(opus·fable)이 반복 처리해 온 쉬운 작업을 티어(T0/T1/T2)로 분류한 뒤 haiku·sonnet 위임 룰로 승격하고, 다음 세션부터 자동으로 적용합니다 |
-| 💸 **비용 실측 −18.6%** | harness와 ratchet을 도입하기 전후로 사용자 메시지당 비용이 $2.35에서 $1.91로 줄었습니다 (저자의 실사용 로그, [상세](#실제-효과-도입-전후-리포트)) |
-| 🚨 **한도 초과 예방** | 5시간·7일 rate-limit 윈도가 90%에 도달하면 즉시 경고하고, `handoff`로 진행 중인 작업을 백업합니다 |
-| 🧠 **캐시 낭비 감지** | 히트율과 TTL 카운트다운, 1M 컨텍스트 사용 여부를 자동으로 감지해 토큰이 급증한 원인을 코드로 진단합니다 |
-| 🅷 **같은 실수 차단** | 반복되는 에러를 감지해 ratchet 룰로 승격하고, 다음 세션부터 자동으로 적용합니다 |
+| 🚨 **한도 초과 예방** | 5시간·7일 rate-limit 윈도가 90%에 닿으면 경고하고, `handoff`로 작업을 백업합니다 |
+| 🧠 **캐시 낭비 감지** | 히트율·TTL·1M 컨텍스트를 감지해 토큰 급증 원인을 코드로 진단합니다 |
+| 🇰🇷 **한국어 문체 교정** | 한국어 환경이면 자동으로 켜집니다 ([아래](#-한국어-문체-지침)) |
 
 ## 라우터가 아닙니다: 60초 설명
 
@@ -335,6 +345,9 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.20.0 (2026-08-22)
+- **README 첫 화면을 훑어 읽을 수 있게 다시 짰습니다** — 설명 문단을 걷어내고 한 줄 요약, 스크린샷, 설치 명령을 앞에 두었습니다. 라우팅·Harness·ratchet 세 기능은 표로, 절감액 계산 방식(기준 모델 → 실행 모델 → 차액)은 도식으로 바꿨습니다. 뒤에서 같은 내용을 반복하던 "30초 요약" 표는 statusline이 추가로 잡아 주는 항목만 남겨 정리했습니다.
+
 ### v3.19.0 (2026-08-22)
 - **한국어 문체 지침 기능을 추가했습니다** — Claude가 한국어를 쓸 때 나타나는 문체 결함(문장 성분 생략, 명사형 종결, 번역체, 엠대시 남용)을 교정하는 지침을 세션 시작 시 한 번 주입합니다. Claude Code의 output style은 전역 슬롯 하나를 차지하고 머신마다 설정해야 하지만, 이 기능은 지침을 패키지에 담고 이미 설치된 SessionStart 훅으로 전달하므로 **CLI가 설치된 모든 프로젝트에 적용되며 output style 슬롯은 비워 둡니다.** 지침 원문은 [fluent-korean](https://github.com/snflkd/fluent-korean)(Copyright (c) 2026 snflkd, MIT)에서 가져왔고 라이선스 전문을 함께 배포합니다.
 - **설치와 동시에 결정됩니다** — 시스템 로캘이 한국어이면 설치 시 자동으로 켜지고, 아니면 꺼 둡니다. 직접 켜거나 끈 뒤에는 그 선택을 유지하므로 업데이트가 사용자의 결정을 되돌리지 않습니다. `CTS_NO_KOREAN=1`로 건너뛸 수 있고, 켜져 있으면 statusline에 `가` 칩이 표시됩니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.19.0",
+  "version": "3.20.1",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/formatters/statusline.js

@@ -145,11 +145,12 @@ export function pickCapWarn(caps) {
 function buildKoreanSeg(c, isIcon, verbose) {
   try {
     if (!koreanStyleEnabled()) return null;
-    // Deliberately quiet (gray, one syllable): this is a "yes, it is on"
+    // Deliberately quiet (gray, one glyph): this is a "yes, it is on"
     // confirmation, not a warning. Without it a silently-failed hook looks
     // exactly like a working one, because the style only shows up when the
-    // model happens to write Korean.
-    if (isIcon) return `${c(GRAY)}${verbose ? '가 Korean style' : '가'}${c(RESET)}`;
+    // model happens to write Korean. The icon says "writing guidance", not
+    // "Korean" — the verbose label already carries the language.
+    if (isIcon) return `${c(GRAY)}${verbose ? '✍️ Korean style' : '✍️'}${c(RESET)}`;
     return `${c(GRAY)}Korean style${c(RESET)}`;
   } catch {
     return null;