claude-token-saver 3.21.0 → 3.21.1

package/README.en.md

@@ -61,7 +61,7 @@ By run (newest first):
 |---|---|
 | 🚨 **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)) |
+| 🇰🇷 **Korean writing guidance** | Offered at install time, defaulting to your locale ([below](#-korean-writing-guidance)) |
 
 ## Not a router — 60 seconds
 
@@ -103,7 +103,9 @@ npm i -g claude-token-saver
 
 The statusline appears at the bottom of Claude Code right away. If auto-registration was skipped (`--ignore-scripts`, sudo, sandboxed installs), run `claude-token-saver install`.
 
-One install sets up everything: **statusline, Skill, SessionStart hook, the 🅷 Harness (5 principles), and a first route-scan.** The harness is **appended** to `~/.claude/CLAUDE.md` as a marked block (your existing content is backed up and preserved) and is left alone if one is already there. Skip it with `CTS_NO_HARNESS=1 npm i -g claude-token-saver`; undo it with `claude-token-saver harness uninit --global`.
+One install sets up everything: **statusline, Skill, SessionStart hook, the 🅷 Harness (5 principles), and a first route-scan.** The harness and the Korean writing guidance **show what they add and ask before enabling it.** The harness is **appended** to `~/.claude/CLAUDE.md` as a marked block (your existing content is backed up and preserved) and is left alone if one is already there.
+
+Outside a terminal — npm `postinstall`, CI, piped stdin — the question is skipped and the old defaults apply. Use `--yes` or `--no-input` to skip it deliberately, `CTS_NO_HARNESS=1 npm i -g claude-token-saver` to skip the harness entirely, and `claude-token-saver harness uninit --global` to undo it.
 
 > ⚠️ Avoid `sudo` global installs — the Skill lands in root's `~/.claude` instead of yours. Use nvm/fnm/Volta or `npm config set prefix ~/.npm-global`.
 
@@ -291,9 +293,31 @@ claude-token-saver korean off      # off
 
 Claude Code's output styles can do the same thing, but an output style is **a single global slot**: turning it on takes that slot away from anything else and has to be configured per machine. This ships the guidance inside the package and delivers it through the SessionStart hook that is already installed, so it **applies wherever the CLI is installed and leaves the output-style slot free.** It survives `/clear`, because the hook fires again.
 
-Cost is **~1.5k tokens per session, injected once at session start rather than per turn**, and covered by the prompt cache from the second request on. When it is on, a `가` chip appears in the statusline.
+Cost is **~1.5k tokens per session, injected once at session start rather than per turn**, and covered by the prompt cache from the second request on. When it is on, a `✍️` chip appears in the statusline.
+
+### Before and after
+
+From a real pipeline (yaml-sns-agent), where a Slack bot shells out to `claude -p` to investigate the repository and answers in a thread. The guidance was toggled off and then on, with the same question both times: "explain in three Korean sentences how to narrow down a render failure."
+
+**Before** (guidance off)
+
+> 렌더 실패 원인 좁히기 3단계: 먼저 `hn:still --check`로 스틸이 명세보다 최신인지(FRESH/STALE) 확인 — STALE이면 재생성 안 해서 옛 자산으로 렌더 시도한 게 원인. 다음 caption-blocks가 최신 나레이션과 단어열 일치하는지 직접 대조 — TTS 재생성 후 blocks 재생성 빠지면 자막·음성 어긋나 렌더 깨짐.
+
+**After** (guidance on)
 
-**The default is decided at install time.** A Korean system locale (`ko_KR` and friends; on macOS the system setting is checked too) turns it on; anything else leaves it off, so users who never write Korean are not billed 1.5k tokens a session. **Once you have turned it on or off yourself, that choice sticks — an upgrade never overrides it.** Install with `CTS_NO_KOREAN=1` to skip the automatic decision.
+> 먼저 `hn:still --check` 돌려 스틸이 명세보다 최신인지 확인한다. STALE이면 재생성 안 해서 생긴 문제.
+>
+> 다음 caption-blocks가 captions.json 단어열과 일치하는지 본다. 내레이션 재TTS 후 blocks 재생성 빠지면 옛 자막이 새 음성 위에 뜬다.
+
+Three things change. Clauses chained with em dashes become separate sentences, so one sentence carries one fact. Noun-stopped phrases (확인, 대조, 렌더 깨짐 — "check", "compare", "render breaks") become predicates (확인한다, 본다, 뜬다), which makes it explicit that these are steps to take. And the particles come back where they had been dropped, so subject and object are legible on the first read.
+
+The technical content is identical in both. The guidance touches sentence construction only, not judgement or accuracy: the answer does not change, it just stops needing a second read. In a channel people scroll through, that difference cuts follow-up questions — and the tokens those follow-ups would have cost.
+
+### Asked at install time
+
+The install **prints what the guidance changes, its per-session cost and its source, then asks.** A Korean system locale (`ko_KR` and friends; on macOS the system setting is checked too) makes the question default to yes; anything else defaults to no, so users who never write Korean are not billed 1.5k tokens a session. The locale is only a default, so an English-locale machine used for Korean work can still turn it on right there.
+
+Installs with nobody attached — npm `postinstall`, CI, piped stdin — skip the question and apply the locale default, because a blocked prompt hangs the install. In that case, if the locale is not Korean the setting is **left undecided rather than recorded**, so a later run at a terminal still gets to ask. Use `--yes` or `--no-input` to force the non-interactive path, or `CTS_NO_KOREAN=1` to skip the feature entirely. **Once you have turned it on or off yourself, that choice sticks — an upgrade never overrides it.**
 
 > **Source and license**
 > The guidance text comes from [fluent-korean](https://github.com/snflkd/fluent-korean). Copyright (c) 2026 snflkd, MIT License.
@@ -379,12 +403,17 @@ Also update `statusLine.command` in `~/.claude/settings.json` to `claude-token-s
 
 ## Release notes
 
+### v3.21.0 (2026-08-22)
+- **The install shows what it is about to enable, then asks** — the harness 5 principles and the Korean writing guidance used to be switched on by the installer, leaving the user with the result rather than the choice. The install now prints the five principle headings, and for the Korean guidance what it changes plus its per-session cost and source, before asking. Locale detection is demoted from an answer to the question's default, so an English-locale machine used for Korean work can enable it on the spot.
+- **Unattended installs behave exactly as before** — npm `postinstall`, CI, piped stdin and `CTS_NO_INPUT=1` skip the question and apply the old defaults, because a blocked prompt hangs an install. `--yes` and `--no-input` force that path explicitly. A non-interactive install on a non-Korean machine now leaves the setting undecided instead of recording an answer nobody gave, so a later run at a terminal still asks.
+- **The Korean-guidance statusline chip is now `✍️`, not `가`** — every other chip is an emoji, so a bare syllable read as a stray character rather than a status indicator.
+
 ### 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.
+- **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`. (From v3.21.0 the install asks instead of deciding for you.)
 - **Corrected an overstated README claim** — routing savings were described as "the whole product", but the measured −18.6% comes from the harness and ratchet. The relationship between the three is now stated accurately.
 
 ### v3.18.0 (2026-08-22)

package/README.md

@@ -102,7 +102,9 @@ npm i -g claude-token-saver
 
 설치하면 Claude Code 화면 하단에 statusline이 곧바로 나타납니다. `--ignore-scripts` 옵션이나 sudo 사용 등으로 자동 등록이 되지 않았다면 `claude-token-saver install`을 실행해 직접 등록하십시오.
 
-설치 한 번으로 **statusline과 Skill, SessionStart 훅, 🅷 Harness(5원칙), 최초 route-scan이** 모두 준비됩니다. Harness는 `~/.claude/CLAUDE.md`에 표시가 붙은 블록으로 **추가되며**, 기존에 작성해 둔 내용은 백업한 뒤 그대로 보존합니다. 이미 설정되어 있는 경우에는 아무것도 바꾸지 않습니다. 자동 설정을 원하지 않으면 `CTS_NO_HARNESS=1 npm i -g claude-token-saver`로 건너뛸 수 있고, 이미 적용한 설정을 되돌리려면 `claude-token-saver harness uninit --global`을 실행하십시오.
+설치 한 번으로 **statusline과 Skill, SessionStart 훅, 🅷 Harness(5원칙), 최초 route-scan이** 모두 준비됩니다. Harness와 한국어 문체 지침은 **무엇이 추가되는지 보여 준 뒤 켤지 물어봅니다.** Harness는 `~/.claude/CLAUDE.md`에 표시가 붙은 블록으로 **추가되며**, 기존에 작성해 둔 내용은 백업한 뒤 그대로 보존합니다. 이미 설정되어 있는 경우에는 아무것도 바꾸지 않습니다.
+
+터미널이 아닌 환경(npm의 `postinstall`, CI, 파이프 입력)에서는 질문을 건너뛰고 기존 기본값을 적용합니다. 질문 없이 진행하려면 `--yes`나 `--no-input`, 아예 건너뛰려면 `CTS_NO_HARNESS=1 npm i -g claude-token-saver`를 쓰십시오. 이미 적용한 설정을 되돌리려면 `claude-token-saver harness uninit --global`을 실행하십시오.
 
 > ⚠️ sudo로 글로벌 설치를 하면 Skill이 사용자 계정이 아니라 root의 `~/.claude`에 등록되는 함정이 있습니다. nvm이나 fnm, Volta를 사용해 사용자 영역에 설치하기를 권장합니다.
 
@@ -281,9 +283,31 @@ claude-token-saver korean off      # 끄기
 
 Claude Code의 output style로도 같은 일을 할 수 있지만, output style은 **전역 슬롯 하나**라서 켜는 순간 다른 스타일을 못 쓰게 되고 머신마다 따로 설정해야 합니다. 이 기능은 지침을 패키지에 담고 이미 설치된 SessionStart 훅으로 전달하므로, **CLI가 설치된 모든 프로젝트에 적용되며 output style 슬롯은 비워 둡니다.** `/clear` 이후에도 훅이 다시 실행되어 유지됩니다.
 
-비용은 **세션당 약 1,500 토큰이며 매 턴이 아니라 세션 시작에 한 번만** 주입됩니다. 두 번째 요청부터는 프롬프트 캐시에 올라가므로 추가 부담이 거의 없습니다. 켜져 있으면 statusline에 `가` 칩이 표시됩니다.
+비용은 **세션당 약 1,500 토큰이며 매 턴이 아니라 세션 시작에 한 번만** 주입됩니다. 두 번째 요청부터는 프롬프트 캐시에 올라가므로 추가 부담이 거의 없습니다. 켜져 있으면 statusline에 `✍️` 칩이 표시됩니다.
+
+### 적용 전후 비교
+
+슬랙 봇이 `claude -p`로 저장소를 조사하고 결과를 스레드에 답하는 실제 파이프라인(yaml-sns-agent)에서, 지침만 껐다 켜고 같은 질문을 던진 결과입니다. 질문은 "렌더가 실패했을 때 원인을 어떻게 좁히는지 한국어 3문장으로 설명해라"였습니다.
+
+**이전** (지침 꺼짐)
+
+> 렌더 실패 원인 좁히기 3단계: 먼저 `hn:still --check`로 스틸이 명세보다 최신인지(FRESH/STALE) 확인 — STALE이면 재생성 안 해서 옛 자산으로 렌더 시도한 게 원인. 다음 caption-blocks가 최신 나레이션과 단어열 일치하는지 직접 대조 — TTS 재생성 후 blocks 재생성 빠지면 자막·음성 어긋나 렌더 깨짐.
+
+**이후** (지침 켜짐)
 
-**설치할 때 자동으로 결정됩니다.** 시스템 로캘이 한국어이면(`ko_KR` 등, macOS는 시스템 설정까지 확인) 설치와 동시에 켜지고, 한국어 환경이 아니면 꺼진 채로 둡니다. 한국어를 쓰지 않는 사용자에게 세션마다 1,500 토큰을 청구하지 않기 위한 판단입니다. **한 번이라도 직접 켜거나 끈 뒤에는 그 선택을 유지하므로, 업데이트 설치가 사용자의 결정을 되돌리지 않습니다.** 자동 설정을 원하지 않으면 `CTS_NO_KOREAN=1`을 붙여 설치하십시오.
+> 먼저 `hn:still --check` 돌려 스틸이 명세보다 최신인지 확인한다. STALE이면 재생성 안 해서 생긴 문제.
+>
+> 다음 caption-blocks가 captions.json 단어열과 일치하는지 본다. 내레이션 재TTS 후 blocks 재생성 빠지면 옛 자막이 새 음성 위에 뜬다.
+
+바뀐 지점은 세 가지입니다. 첫째, 엠대시로 이어 붙이던 절이 마침표로 끊어져 한 문장이 한 가지 사실만 전달합니다. 둘째, "확인", "대조", "렌더 깨짐" 같은 명사형 종결이 "확인한다", "본다", "뜬다"처럼 서술어로 바뀌어 무엇을 하라는 것인지가 분명해집니다. 셋째, "자막·음성 어긋나"처럼 조사가 빠진 자리에 조사가 돌아와 어떤 성분이 주어이고 목적어인지 읽는 즉시 잡힙니다.
+
+기술적 내용은 양쪽이 동일합니다. 지침은 판단이나 정확도가 아니라 문장의 완성도에만 관여하므로, 답이 달라지는 것이 아니라 같은 답을 다시 읽지 않아도 되는 형태로 만들어 줍니다. 슬랙처럼 사람이 스크롤하며 읽는 채널에서는 이 차이가 되묻는 횟수를 줄이고, 되묻지 않는 만큼 토큰도 아낍니다.
+
+### 설치할 때 물어봅니다
+
+설치 과정에서 **지침의 내용과 세션당 비용, 출처를 먼저 보여 준 다음 켤지 물어봅니다.** 시스템 로캘이 한국어이면(`ko_KR` 등, macOS는 시스템 설정까지 확인) 질문의 기본값이 "켬"이 되고, 한국어 환경이 아니면 기본값이 "끔"입니다. 로캘은 답이 아니라 기본값일 뿐이므로 영어 로캘에서 한국어로 작업하는 경우에도 그 자리에서 켤 수 있습니다.
+
+npm의 `postinstall`이나 CI처럼 사람이 붙어 있지 않은 설치에서는 질문을 건너뛰고 로캘 기본값을 그대로 적용합니다. 프롬프트가 멈춰 서면 설치 자체가 걸리기 때문입니다. 이때 로캘이 한국어가 아니면 **설정을 저장하지 않고 미결정으로 남겨 두므로**, 나중에 터미널에서 다시 설치하면 그때 물어봅니다. 질문 없이 기본값으로 넘기려면 `--yes`나 `--no-input`을, 기능 자체를 건너뛰려면 `CTS_NO_KOREAN=1`을 쓰십시오. **한 번이라도 직접 켜거나 끈 뒤에는 그 선택을 유지하므로, 업데이트 설치가 사용자의 결정을 되돌리지 않습니다.**
 
 > **출처와 라이선스**
 > 지침 원문은 [fluent-korean](https://github.com/snflkd/fluent-korean)에서 가져왔습니다. Copyright (c) 2026 snflkd, MIT License.
@@ -345,12 +369,17 @@ npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
 
 ## 릴리스 노트
 
+### v3.21.0 (2026-08-22)
+- **설치가 무엇을 켜는지 보여 준 뒤 물어봅니다** — 지금까지는 🅷 Harness 5원칙과 한국어 문체 지침을 설치가 스스로 켰고, 사용자는 결과만 볼 수 있었습니다. 이제 harness는 다섯 원칙의 제목을, 한국어 지침은 바꾸는 내용과 세션당 비용과 출처를 먼저 출력한 다음 켤지 묻습니다. 로캘 감지는 답이 아니라 질문의 기본값으로 내려왔으므로, 영어 로캘에서 한국어로 작업하는 경우에도 그 자리에서 켤 수 있습니다.
+- **사람이 붙어 있지 않은 설치는 예전대로 동작합니다** — npm의 `postinstall`, CI, 파이프 입력, `CTS_NO_INPUT=1`에서는 질문을 건너뛰고 기존 기본값을 그대로 적용합니다. 프롬프트가 멈춰 서면 설치가 걸리기 때문입니다. `--yes`와 `--no-input`으로 직접 강제할 수도 있습니다. 비대화형이면서 로캘이 한국어가 아닌 경우에는 설정을 저장하지 않고 미결정으로 남겨 두므로, 나중에 터미널에서 설치하면 그때 물어봅니다.
+- **statusline의 한국어 지침 칩을 `가`에서 `✍️`로 바꿨습니다** — 다른 칩이 모두 이모지라서 음절 하나가 상태 표시가 아니라 잘못 섞여 들어간 글자로 보였습니다.
+
 ### 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에 `가` 칩이 표시됩니다.
+- **설치와 동시에 결정됩니다** — 시스템 로캘이 한국어이면 설치 시 자동으로 켜지고, 아니면 꺼 둡니다. 직접 켜거나 끈 뒤에는 그 선택을 유지하므로 업데이트가 사용자의 결정을 되돌리지 않습니다. `CTS_NO_KOREAN=1`로 건너뛸 수 있습니다(v3.21.0부터는 설치가 묻습니다).
 - **README의 과장된 설명을 바로잡았습니다** — 라우팅 절감액을 "이 도구의 전부"라고 적었으나, 실측 −18.6%는 Harness와 ratchet을 도입한 효과입니다. 세 기능의 관계를 정확히 다시 썼습니다.
 
 ### v3.18.0 (2026-08-22)

package/bin/cli.js

@@ -10,6 +10,8 @@
  *   npx claude-token-saver --format csv       # CSV output
  *   npx claude-token-saver --project myproj   # filter by project
  *   npx claude-token-saver route-scan         # detect recurring easy work → haiku-delegation candidates
+ *   npx claude-token-saver install            # set up skill/hooks/statusline; asks about harness + Korean guidance
+ *   npx claude-token-saver install --yes      # take the defaults without asking (same as --no-input)
  *   npx claude-token-saver --install-hook     # install PostToolUse hook
  *   npx claude-token-saver --uninstall-hook   # remove hook
  *   npx claude-token-saver --hook-run         # internal: called by hook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.21.0",
+  "version": "3.21.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/commands/install.js

@@ -5,6 +5,8 @@
  * a legacy command file is removed automatically. Cross-platform.
  *   claude-token-saver install              # install/update the skill
  *   claude-token-saver install --force      # overwrite existing skill file
+ *   claude-token-saver install --yes        # take the defaults instead of asking
+ *   claude-token-saver install --no-input   # same as --yes; also implied by CTS_NO_INPUT=1
  */
 
 import { debug } from '../debug.js';