claude-token-saver 2.12.0 → 2.13.1

package/README.en.md

@@ -1,13 +1,33 @@
 [한국어](./README.md) · **English**
 
+[![DeepPulse YouTube](https://img.shields.io/badge/YouTube-@deeppulse-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@deeppulse)
+[![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
+
 # claude-token-saver
 
 > Renamed from `claude-cache-monitor` in v2.0. Existing users — see [Migration](#migration-from-claude-cache-monitor).
 
 A CLI to **diagnose and save tokens on Claude Code**. Cache hit rate, TTL countdown, 1M-context detection, 5h/7d cap warnings — all in one statusline chip.
 
+![statusline example](./docs/statusline.png)
+
 📺 [Launch Short (60s)](https://www.youtube.com/shorts/RaD8qMsPTnA)
 
+## Real-world impact — harness 5/5 + ratchet adoption
+
+![claude-token-saver before/after](./docs/harness-impact.png)
+
+Author's own Claude Code logs, normalized **per user message**, before/after adopting harness rules on 2026-05-02 (Opus 4.7 pricing):
+
+| metric | before (7d / 739 msgs) | after (2d / 157 msgs) | Δ |
+|---|---:|---:|---:|
+| cost / user message | $2.345 | $1.910 | **−18.6%** |
+| output tokens / user message | 7,391 | 6,052 | −18.1% |
+| assistant turns / user message | 9.73 | 8.83 | −9.2% |
+| tool calls / user message | 5.72 | 5.25 | −8.2% |
+
+> ⚠️ **Sample caveats** — POST window is only 2 days (157 msgs); statistical confidence is low. The work topic mix differs week to week (PRE week was video-script production with long pasted text, POST week was package release with short directives), so the tool/harness effect is not cleanly isolated. Refresh planned around **2026-05-09** once 5 more days of POST data are in.
+
 ---
 
 ## Install
@@ -148,6 +168,31 @@ All of the commands below run in your **shell (terminal)**. Inside a Claude Code
 | `--segments=…` | Limit statusline segments (e.g. `model,five_hour,seven_day,saved`) | all |
 | `--install-hook` / `--uninstall-hook` | Manage the PostToolUse hook | – |
 
+## 🅷 Harness mode
+
+Bootstrap five engineering principles (Ratchet, Evidence, PEV, Structured Task, Default Safe Path) into your project's `CLAUDE.md` with one command, then watch the statusline track your score (`🅷 5/5`). When the same error keeps recurring, a `🅷⚠ ratchet?` nudge appears.
+
+```bash
+claude-token-saver harness init                # writes CLAUDE.md (5 sections) + .claude/ratchet.md
+claude-token-saver harness check               # current score
+claude-token-saver harness promote <N>         # turn statusline warning #N into a one-line ratchet rule
+claude-token-saver harness list                # list registered ratchet rules with numbers
+claude-token-saver harness rm <N>              # delete rule N (auto .bak backup)
+claude-token-saver harness uninit              # remove the harness block (other CLAUDE.md content preserved)
+claude-token-saver harness off | on            # toggle the 🅷 chip
+```
+
+### ⚠️ `harness rm` — handle with care
+
+The whole point of the ratchet is **one-direction accumulation**. Deleting rules casually means the same mistakes start re-occurring. **Before deleting, ask**:
+
+- **Is the rule too broad and blocking valid cases?** → ❌ delete ✅ **narrow the condition instead**
+  - e.g. `"no hardcoded values"` → `"no hardcoded values outside tests"`
+- **Is the rule too narrow and almost never firing?** → ❌ delete ✅ **leave it** (zero cost)
+- **Genuinely wrong rule?** → ✅ delete then
+
+Most "over-ratcheting" complaints turn out to be **rules that weren't phrased tightly enough**. Open `.claude/ratchet.md` and refine the condition first; deletion is the last resort. An auto `.bak` is left behind, but **the session context that made the rule earn its place is not recoverable**.
+
 ## Spike issue codes
 
 | Code | Meaning |
@@ -209,6 +254,13 @@ Node.js ≥ 18 · macOS / Windows / Linux / WSL · zero dependencies.
 
 ## Release notes
 
+### v2.13.1 (2026-05-04)
+- README now opens with the actual statusline screenshot and a "harness 5/5 + ratchet — before/after" impact chart, with daily/monthly/yearly cost-savings impact card. Author's own logs show −18.6% cost / user message, −9.2% assistant turns. Sample caveats, work-topic confound, and refresh schedule (2026-05-09) called out.
+- npm package metadata cleaned up (homepage / bugs / author) — package page now links to the DeepPulse YouTube channel.
+
+### v2.11.0 (2026-05-02)
+- Added `harness list` / `harness rm <N>` to view registered ratchet rules with numbers and delete individually (auto `.bak` backup). The CLI prompts users to "narrow the condition first" before deleting; see [⚠️ `harness rm` — handle with care](#️-harness-rm--handle-with-care).
+
 ### v2.9.4 (2026-04-27)
 - README now opens with a Node.js prerequisite block (macOS / Windows / Linux). First-time visitors arriving from GitHub no longer hit `npm: command not found` with no guidance. Also flags the `sudo` global-install trap where postinstall writes the Skill under root's home instead of the user's.
 

package/README.md

@@ -1,13 +1,33 @@
 **한국어** · [English](./README.en.md)
 
+[![DeepPulse YouTube](https://img.shields.io/badge/YouTube-@deeppulse-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/@deeppulse)
+[![npm](https://img.shields.io/npm/v/claude-token-saver.svg)](https://www.npmjs.com/package/claude-token-saver)
+
 # claude-token-saver
 
 > v2.0에서 `claude-cache-monitor` → `claude-token-saver`로 이름이 바뀌었습니다. 기존 사용자는 아래 [마이그레이션](#마이그레이션-claude-cache-monitor에서) 항목을 참고하세요.
 
 Claude Code의 **토큰 사용량을 진단·절약**하는 CLI. 캐시 히트율, TTL 카운트다운, 1M 컨텍스트 감지, 5h/7d 한도 경고를 statusline 한 줄로 보여줍니다.
 
+![statusline 예시](./docs/statusline.png)
+
 📺 [출시 영상 (60초)](https://www.youtube.com/shorts/RaD8qMsPTnA)
 
+## 실제 효과 — harness 5/5 + ratchet 적용 전후
+
+![claude-token-saver 설치 전/후 효과](./docs/harness-impact.png)
+
+저자 본인의 Claude Code 사용 로그를 **사용자 메시지 1건당**으로 정규화해 비교한 결과 (2026-05-02 적용 시점, Opus 4.7 가격 기준):
+
+| 메트릭 | 설치 전 (7일 / 739msg) | 설치 후 (2일 / 157msg) | 변화 |
+|---|---:|---:|---:|
+| 메시지당 비용 | $2.345 | $1.910 | **−18.6%** |
+| 메시지당 출력 토큰 | 7,391 | 6,052 | −18.1% |
+| 메시지당 assistant 왕복 | 9.73 | 8.83 | −9.2% |
+| 메시지당 도구 호출 | 5.72 | 5.25 | −8.2% |
+
+> ⚠️ **샘플 주의** — POST 데이터는 2일치(157 msgs)로 통계적 의미가 약하고, 그 주에 무슨 작업을 했냐(긴 텍스트 vs 짧은 지시)가 결과에 섞여 있습니다. 5일치가 더 쌓이는 **2026-05-09경** 같은 분석을 다시 돌려 갱신할 예정입니다.
+
 ---
 
 ## 설치
@@ -194,6 +214,10 @@ Node.js ≥ 18 · macOS / Linux / Windows / WSL · 의존성 0.
 
 ## 릴리스 노트
 
+### v2.13.1 (2026-05-04)
+- README에 실제 statusline 스크린샷과 "harness 5/5 + ratchet 적용 전후 효과" 차트 추가. 자체 사용 로그 기준 메시지당 비용 −18.6%, assistant 왕복 −9.2%, 일/월/년 환산 비용 절감 임팩트 카드 포함. 샘플 주의사항·작업 토픽 변수·갱신 일정(2026-05-09) 명시.
+- npm 패키지 메타데이터(homepage / bugs / author) 정비 — DeepPulse YouTube 채널 링크 노출.
+
 ### v2.11.0 (2026-05-02)
 - `harness list` / `harness rm <N>` 추가. 등록된 ratchet 룰을 번호로 보고 개별 삭제 가능 (자동 `.bak` 백업). 삭제 전 "조건을 좁혀서 다듬기" 우선 검토 안내가 CLI에 표시됩니다. README의 [⚠️ 주의 — `harness rm`은 신중하게](#️-주의--harness-rm은-신중하게) 항목 참고.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.12.0",
+  "version": "2.13.1",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
@@ -36,5 +36,10 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rootstudioyaml/claude-token-saver.git"
-  }
+  },
+  "homepage": "https://www.youtube.com/@deeppulse",
+  "bugs": {
+    "url": "https://github.com/rootstudioyaml/claude-token-saver/issues"
+  },
+  "author": "DeepPulse (https://www.youtube.com/@deeppulse)"
 }