@bglocation/tune-context 1.0.1 → 2.0.0

package/.claude-plugin/marketplace.json

@@ -1,5 +1,6 @@
 {
   "name": "bglocation",
+  "description": "Context-engineering tooling for Claude Code from bglocation — token-saving doctrine, configurators and semantic-search wiring.",
   "owner": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"
@@ -9,7 +10,7 @@
       "name": "tune-context",
       "source": "./",
       "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-      "version": "1.0.1",
+      "version": "2.0.0",
       "author": {
         "name": "Szymon Walczak",
         "url": "https://bglocation.dev"

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "tune-context",
   "displayName": "tune-context",
   "description": "Context-efficiency configurator for Claude Code: doctrine skills (token-efficiency, caveman, cdd, phase-workflow) plus a tune-context configurator that scaffolds a lean CLAUDE.md, subagents, settings and hooks.",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -0,0 +1,252 @@
+# Changelog
+
+All notable changes to `@bglocation/tune-context` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] — 2026-07-25
+
+Three hardening epics' worth of work plus the first new feature since 1.0: a
+reminder that measures what a session actually costs. **The major bump is for
+one breaking change** — `tune-context` with no subcommand no longer runs `init`
+(see below). Everything else is additive; see "Upgrading from 1.1.0" at the end.
+
+### Added
+
+- **Context-size reminder** (`hooks/context-reminder.mjs`, `UserPromptSubmit`).
+  Claude can't see its own context usage — nothing in a turn reports how many
+  tokens are being re-sent, and Claude Code has no timer or threshold event — so
+  this hook reads the tail of the session transcript, sums the tokens actually
+  re-sent, and once that passes a PO-frozen **120k** injects one short note
+  suggesting `/compact`. Fires **once per crossing**, re-arming only after a
+  compaction-sized drop: the note costs tokens on the turn it appears in, so
+  nagging every prompt would spend exactly what the tool saves (measured on a
+  12.6h session: 4 reminders total). Reminds on *size*, not "phase boundary" —
+  size is measurable, a phase boundary is a judgment, so the reminder hands the
+  timing call to the model and tells it to stay quiet mid-task. Override with
+  `TUNE_CONTEXT_REMIND_TOKENS`; remove the `UserPromptSubmit` entry to disable.
+  (TASK-079)
+
+### Fixed
+
+- **Plugin-shaped hook commands no longer misread as broken.** `cli/verify.mjs`
+  treated any registered command it couldn't resolve to an installed file as
+  stray or dead — including a plugin's own `${CLAUDE_PLUGIN_ROOT}`-based
+  registration, which it was never meant to check. Now reported as its own
+  always-ok informational line instead. (EPIC-008 / TASK-072)
+- **Adoption report no longer prints a false churn verdict over doubled
+  events.** Running the plugin and `tune-context init` together on one repo
+  registers each hook twice, so every event logs twice — this previously
+  surfaced as spurious "elevated re-read churn." The report now detects a
+  near-duplicate signature (records identical on session/tool/lever/detail
+  within a measured 100ms window, at ≥10% of assessable records) and withholds
+  the re-read-churn verdict instead of printing a number the doubling would
+  have faked. Thresholds are frozen from two independent real logs, not
+  guessed — a naively "safe" 1000ms window was shown to swallow real churn
+  instead. (EPIC-008 / TASK-072)
+- **Generated commands now match the detected package manager exactly.**
+  `CLAUDE.md` and `permissions.allow` used to assume npm-style `run` commands
+  regardless of lockfile. Now derived from one `runCmd(packageManager, script)`
+  table: npm/pnpm use `npm run build` / `pnpm run build` (`test` keeps its
+  shorthand), yarn uses the bare short form for all three — `yarn build`,
+  `yarn test`, `yarn lint` (PO decision). (EPIC-008 / TASK-073)
+- **`disabledMcpjsonServers` is now honoured.** A project `.mcp.json` server a
+  user rejected via `disabledMcpjsonServers` (in any settings file) no longer
+  gets a `permissions.allow` rule or a `CLAUDE.md` mention — previously
+  `tune-context init` wired it in regardless. Three neighbouring keys
+  (`enabledMcpjsonServers`, `allowedMcpServers`, `deniedMcpServers`) are
+  deliberately not treated as equivalent, verified against docs rather than
+  guessed — each would need introspection this CLI doesn't have.
+  (EPIC-008 / TASK-075)
+- **PreCompact snapshot files could collide across projects.** `state/` keyed
+  snapshots by a human-readable slug of `cwd` alone, which is not injective —
+  `/home/a/b` and `/home/a-b` (also `.`/`_` variants) slugged to the same
+  filename, so `SessionStart(compact)` could reinject one project's git state
+  into an unrelated session. A short hash of the real `cwd` is now appended to
+  the filename. **Breaking for `state/` only**: snapshots written under the old
+  filename shape are orphaned (harmless — a snapshot is only ever valid for the
+  one compaction right after it) rather than reused; the new retention policy
+  below cleans them up over time. (EPIC-008 / TASK-076)
+- **`pre-compact-snapshot.mjs` could exit non-zero.** Brought to parity with
+  `adoption-log.mjs`: an unwritable state directory (read-only volume,
+  misdirected `CLAUDE_CONFIG_DIR`) now fails the snapshot silently instead of
+  surfacing a nonzero exit from a hook at the exact moment a session is
+  compacting under context pressure. (EPIC-008 / TASK-076)
+- **Manual hook-install instructions now produce a working hook.** README
+  pointed at the raw `settings.json.tmpl`, which still has an unsubstituted
+  `{{HOOKS_DIR}}` placeholder and no instruction to replace it — followed
+  literally, the hook command was `node "{{HOOKS_DIR}}/adoption-log.mjs"` and
+  silently never ran. Replaced with a ready-to-paste `settings.json` snippet.
+  (EPIC-008 / TASK-078)
+- **Plugin-only installs now get a working `tune-context` command.** Claude
+  Code exposes `bin/` files under their literal filename — confirmed against
+  current docs, no extension-stripping — so `bin/tune-context.mjs` only ever
+  produced a bare `tune-context.mjs`. A plugin-only install (no
+  `npm install -g`) got "command not found" for the command README documents.
+  Added an extensionless `bin/tune-context` alias so both channels give the
+  identical command. (EPIC-008 / TASK-078)
+- **`tune-context --cwd` (no value) no longer crashes with a Node stacktrace.**
+  `resolve(undefined)` used to throw `ERR_INVALID_ARG_TYPE` straight to the
+  terminal; now reports "Missing value for `--cwd`" plus usage, on stderr,
+  exit 1. **Breaking:** an unrecognized *or missing* subcommand is now also
+  rejected the same way instead of silently running `init` — `init` is the
+  only accepted subcommand. README never documented calling this tool with no
+  arguments; every example already used explicit `init`. (EPIC-008 / TASK-078)
+
+### Changed
+
+- **One source of truth for `CLAUDE_CONFIG_DIR` resolution.** `cli/detect.mjs`'s
+  `claudeDirs()` now delegates the `CLAUDE_CONFIG_DIR || ~/.claude` rule to
+  `hooks/config-dir.mjs`'s `claudeBaseDir()` instead of re-implementing it —
+  the two could previously drift apart. No behavior change.
+  (EPIC-008 / TASK-074)
+- **Removed a dead `permissions` block from the settings template.**
+  `settings.json.tmpl` carried a `permissions.allow` block nothing ever read —
+  the CLI merges its own, computed from the detected stack, straight into the
+  *project's* settings instead. PO-approved removal. (EPIC-008 / TASK-074)
+- **`bin/tune-context.mjs`'s header states its real scope.** No longer reads
+  as a full twin of the `/tune-context` skill — names the two steps it
+  deliberately can't do (merging in a semantic-search MCP server, wiki-lever
+  wiring) instead of leaving the gap unstated. (EPIC-008 / TASK-075)
+
+### Added
+
+- **`state/` retention.** Snapshots untouched for 30 days are pruned on the
+  next PreCompact write anywhere on the machine — `state/` is one shared
+  directory across all projects, so any project's compaction sweeps it, not
+  only the project being written; the snapshot just written is never a prune
+  candidate. Previously `state/` was the only tune-context artifact with no
+  cleanup policy. (EPIC-008 / TASK-076)
+- **`tune-context --version`** (also `-v`), printing the bare number so
+  `$(tune-context --version)` is directly comparable. Read from the shipped
+  `package.json` — the same file `verify:plugin` cross-checks against
+  `plugin.json` and `marketplace.json`, so the CLI can't report a version the
+  manifests disagree with.
+- **README: "Keeping context lean while you work".** The tool configures a
+  lean setup, but shedding accumulated context stays a deliberate, recurring
+  act — `/compact` when a thread closes, `/clear` when switching tasks — and
+  the README never said so. Includes what the PreCompact/SessionStart pair
+  does and does not preserve across a compaction.
+- **`token-efficiency` §6 recommends `eval/adoption-report.mjs`.** Previously
+  the section on measuring whether doctrine is actually used pointed only at
+  `rag-usage`, a different package's tool — silent about the one instrument
+  this repo ships for the same purpose. (EPIC-008 / TASK-078)
+
+### Testing / packaging
+
+- **Unit test harness for the CLI.** `npm test` now also exercises
+  `cli/managed-block.mjs`, `cli/generate.mjs`, `cli/verify.mjs` and
+  `cli/detect.mjs` directly — previously only reachable end-to-end through
+  `smoke:init` — plus a structural guard that fails when a `cli/` export has
+  nothing importing it. (EPIC-008 / TASK-077)
+- **`verify:plugin` and `verify:pack` now guard `bin/` and
+  `eval/adoption-report.mjs`.** Both were tracked by git accidentally, not by
+  contract, despite README telling a plugin-only or npm install to run them —
+  a clone or tarball missing either would previously pass both checks anyway.
+  (EPIC-008 / TASK-078)
+
+### Upgrading from 1.1.0
+
+Re-running `tune-context init` over a 1.1.0 install is safe and was verified
+end-to-end: hook entries are not duplicated, unrelated `settings.json` keys and
+hand-written `CLAUDE.md` content are untouched, and your own
+`permissions.allow` rules are kept.
+
+Two leftovers are deliberate, because removing them would break "never
+clobber" — tune-context cannot tell its own past output from a rule you added
+on purpose:
+
+- **pnpm/yarn projects**: the npm-style rules 1.1.0 wrote (`Bash(npm test:*)`
+  and friends) stay in `.claude/settings.json` alongside the correct new ones
+  (`Bash(pnpm test:*)`). Harmless — an unused allow rule grants nothing extra
+  for a command you never run — but safe to delete by hand.
+- **PreCompact snapshots** under `<config dir>/tune-context/state/` written
+  before this release keep their old filenames and are ignored. The new
+  30-day retention deletes them on its own; no action needed.
+
+## [1.1.0] — 2026-07-24
+
+Two hardening epics land together: consistent `CLAUDE_CONFIG_DIR` support with the
+guards to keep it honest (EPIC-006), and an adoption report that only claims what
+the log can actually support (EPIC-007). Default-path behavior is unchanged — no
+action needed on upgrade.
+
+### Added
+
+- **`CLAUDE_CONFIG_DIR` honored across the whole hook lifecycle.** Setting Claude
+  Code's `CLAUDE_CONFIG_DIR` now moves *everything* user-level under the override —
+  not just the config dir, but registered hook command paths and hook **state**
+  (PreCompact snapshots, adoption log) too. Previously the override leaked: scripts
+  landed under `/x/`, but hook commands and state still pointed at `~/.claude`.
+  Documented in the README with a per-path table. (EPIC-006 / TASK-064, TASK-067)
+- **Golden-fixture test harness** for the adoption report's pure functions
+  (`parseLog` / `aggregate` / `formatReport`), run by `npm test` and wired into the
+  `prepublishOnly` gate. Deliberately wrong aggregation now fails a fixture instead
+  of shipping. (EPIC-007 / TASK-068)
+- **edit:read ratio** in the adoption report — a partial, *ungraded* proxy for
+  doctrine applied as method (narrow reads, contracts-first edits), the discipline
+  that leaves no `Skill` tool call to count. (EPIC-007 / TASK-071)
+
+### Changed
+
+- **`verify` cross-checks hook wiring.** `cli/verify.mjs` now confirms each
+  registered hook command points at the file actually installed — checking *all*
+  matching entries, not just the first — so a dead or mis-pointed duplicate fails
+  red instead of passing on a partial match. (EPIC-006 / TASK-065)
+- **Adoption report splits code search from shell plumbing.** Semantic search (RAG)
+  and the Grep tool count as code search; `grep`/`find` inside Bash is reported
+  separately and kept out of the RAG share. Removes the "RAG 0%" false negative on
+  logs that were only ever doing operational greps. (EPIC-007 / TASK-069)
+- **The adoption verdict is now earned.** RAG and doctrine-skill judgments are
+  withheld below a PO-frozen floor of 3 distinct sessions ("insufficient signal"
+  instead of a confident ✗ over one atypical session). A lever the log genuinely
+  can't distinguish — RAG installed-but-unused vs not installed, or method-level
+  doctrine that leaves no tool call — is reported neutrally, never as a false ✗.
+  (EPIC-007 / TASK-070, TASK-071)
+
+### Fixed
+
+- **Manual hook-install docs were incomplete.** README / SKILL.md now instruct
+  copying `hooks/config-dir.mjs` alongside `hooks/adoption-log.mjs` — the latter
+  imports the former, so a by-hand install following the old docs threw
+  `Cannot find module`. (EPIC-006)
+- **No more false churn/verdict lines over empty data.** The adoption report no
+  longer prints "elevated re-read churn" for a zero-read log, and no longer dangles
+  a "see verdict below" pointer when the verdict section has nothing to say.
+  (EPIC-007 / TASK-070, TASK-071)
+
+### Testing / packaging
+
+- `smoke:init` now exercises **both** the default `$HOME` and the
+  `CLAUDE_CONFIG_DIR` override paths, asserting hook state round-trips in each.
+  (EPIC-006 / TASK-066)
+- `npm test` (the golden-fixture suite) runs first in `prepublishOnly`, ahead of
+  `verify:pack` / `verify:plugin` / `smoke:init` — cheapest gate, fails fastest.
+  (EPIC-007 / TASK-068)
+
+## [1.0.1] — 2026-07-23
+
+### Fixed
+
+- Stop shipping the dev-only MCP config (`.mcp.json`, `rag.config.json`) to plugin
+  installers. Because the repo root doubles as the plugin root, a tracked
+  `.mcp.json` would force every marketplace install to load a `rag` server pointing
+  at a binary and index the installer doesn't have — breaking the "RAG is optional,
+  detected never assumed" contract. Now enforced by `verify:plugin`.
+
+## [1.0.0] — 2026-07-23
+
+### Added
+
+- Initial dual-channel release under `@bglocation`: a Claude Code **plugin**
+  (marketplace) and an **npm CLI** (`tune-context init`), from one self-contained
+  repo. Ships the doctrine skills (`token-efficiency`, `caveman`, `cdd`,
+  `phase-workflow`), the `tune-context` configurator (skill + deterministic CLI
+  twin with a never-clobber managed-block contract), right-sized subagents
+  (`explore-cheap`, `reviewer`), the PreCompact / SessionStart / PostToolUse hook
+  suite, and the adoption report (`eval/adoption-report.mjs`).
+
+[1.1.0]: https://gitlab.com/bglocation/tune-context/-/tags/v1.1.0
+[1.0.1]: https://gitlab.com/bglocation/tune-context/-/tags/v1.0.1
+[1.0.0]: https://gitlab.com/bglocation/tune-context/-/tags/v1.0.0

package/README.md

@@ -15,7 +15,7 @@ tune-context/
 ├── .claude-plugin/plugin.json   # Claude Code plugin manifest
 ├── skills/            # token-efficiency, caveman, cdd, phase-workflow, tune-context (+ templates/)
 ├── agents/            # explore-cheap, reviewer (model right-sizing)
-├── hooks/             # PreCompact state-doc, SessionStart re-inject, PostToolUse adoption log + hooks.json
+├── hooks/             # PreCompact state-doc, SessionStart re-inject, adoption log, context reminder + hooks.json
 ├── bin/ + cli/        # `tune-context init` — deterministic detect → generate → verify
 ├── eval/              # adoption-report.mjs (the rag-usage analog)
 └── scripts/           # verify-pack, smoke-init, sync-tune-context (dev/maintenance)
@@ -70,8 +70,9 @@ then generates a lean project `CLAUDE.md`, wires the doctrine skills, and merges
 hooks + permissions — idempotently, never clobbering hand-written content. This is
 the full-fidelity path (it also handles wiki wiring and semantic-search detection).
 
-**2. CLI `tune-context init`.** The deterministic, no-model twin of the skill — same
-managed-block rules, same never-clobber guarantee. Good for CI or scripted setup:
+**2. CLI `tune-context init`.** The deterministic **subset** of the skill — same
+managed-block rules, same never-clobber guarantee, no model in the loop. Good for
+CI or scripted setup:
 
 ```bash
 npx -p @bglocation/tune-context tune-context init           # runs in the current repo
@@ -83,6 +84,15 @@ node bin/tune-context.mjs init --cwd /path/to/your/repo
 It prints what it detected, what it synced/merged, and a verification report; a
 second run is a no-op.
 
+Two steps of the skill have **no CLI equivalent**, because each needs judgment a
+deterministic tool cannot supply — run `/tune-context` if you want them:
+
+| Step | Skill | CLI |
+|---|---|---|
+| Project `CLAUDE.md`, doctrine skills, hooks, permissions | ✅ | ✅ |
+| Merge `.mcp.json` — add a semantic-search server if none was detected | ✅ | ❌ reads it, never writes it |
+| Wiki lever — RAG segment vs its own MCP vs a plain pointer | ✅ | ❌ not detected, not wired |
+
 **3. Plugin install.** Load the plugin so the skills, agents and hooks are available
 in every session. The best UX is the **marketplace** — install once, get updates
 with `/plugin marketplace update`:
@@ -110,25 +120,124 @@ The plugin manifest (`.claude-plugin/plugin.json`) and hook wiring
 automatically; `bin/tune-context` is added to `PATH` while the plugin is enabled.
 The marketplace catalog is [`.claude-plugin/marketplace.json`](.claude-plugin/marketplace.json).
 
+### `CLAUDE_CONFIG_DIR`
+
+By default the CLI reads and writes Claude config under `~/.claude` (and
+`~/.claude.json`). If you set Claude Code's `CLAUDE_CONFIG_DIR`, `tune-context
+init` honors it consistently — everything user-level moves under the override:
+
+| What | Default | With `CLAUDE_CONFIG_DIR=/x` |
+|---|---|---|
+| doctrine skills / agents / hook scripts | `~/.claude/…` | `/x/…` |
+| `settings.json` (hooks + gating) | `~/.claude/settings.json` | `/x/settings.json` |
+| MCP-server detection (`.claude.json`) | `~/.claude.json` | `/x/.claude.json` |
+| registered hook command paths | `$HOME/.claude/hooks/…` | `/x/hooks/…` |
+| hook state (PreCompact snapshot, adoption log) | `~/.claude/tune-context/…` | `/x/tune-context/…` |
+
+Without the override the generated `settings.json` keeps the portable
+`$HOME/.claude/hooks/…` form (expanded when the hook fires, so it travels between
+machines). Under the override it's baked to the literal `/x/hooks/…` — where the
+scripts actually land. Useful for shared accounts, containers, and test isolation.
+
+## Keeping context lean while you work
+
+Setup is the cheap half. The recurring half is **shedding context you no longer
+need** — and that stays a manual, deliberate act, because only you know when a
+piece of work is actually finished.
+
+Every turn re-sends the whole conversation as input. A session that has been
+running for hours pays for its early exploration on *every* later request, long
+after that detail stopped being useful. So:
+
+| When | Do | Why |
+|---|---|---|
+| A work thread closes (feature done, bug fixed) | `/compact` | Keeps the conclusions, drops the raw tool output that led to them |
+| Switching to unrelated work | `/clear` | Nothing from the old task is worth carrying — `/compact` would still keep a summary of it |
+| Long session, no natural break yet | `/compact` anyway | Waiting for auto-compact means paying full price right up to the limit |
+
+tune-context softens the cost of compacting rather than replacing it: its
+`PreCompact` hook snapshots your branch, dirty files and recent commits, and the
+`SessionStart(compact)` hook injects that back afterwards — so the mechanical
+state survives even though the transcript doesn't. Judgment calls and open
+threads do **not** survive; write those down before compacting if they matter.
+
+### The reminder is automatic
+
+Claude cannot see its own context usage — nothing in a turn tells the model how
+many tokens it is re-sending, and Claude Code has no timer or context-threshold
+hook event. So `context-reminder.mjs` (registered under `UserPromptSubmit`)
+supplies the missing measurement: it reads the tail of the session transcript,
+sums the tokens actually re-sent, and once that passes **120,000** it injects a
+single short note suggesting `/compact`.
+
+- **Once per crossing, not per prompt.** The note itself costs tokens on the turn
+  it appears in, so it re-arms only after a compaction-sized drop. Measured on a
+  12.6-hour session: 4 reminders total.
+- **The model picks the moment.** The reminder tells Claude to stay quiet
+  mid-task and raise it when the thread closes — the hook can measure size, but
+  only the model can see whether you're mid-refactor.
+- **Raise it for a large context window:** `export TUNE_CONTEXT_REMIND_TOKENS=400000`.
+  120k is ~60% of a standard 200k window; the transcript doesn't record the window
+  size, so this can't be auto-scaled.
+- **Turn it off:** delete the `UserPromptSubmit` entry from `settings.json`.
+
+Depth lives in the `phase-workflow` and `token-efficiency` skills (both installed
+by `tune-context init`), not here.
+
 ## Measuring adoption (does the doctrine actually get used?)
 `hooks/adoption-log.mjs` logs one JSONL line per event to
-`~/.claude/tune-context/adoption.jsonl`, and `eval/adoption-report.mjs` turns that
-into a report: RAG vs grep, doctrine skills, subagents, re-read churn — with a
-verdict per lever. It's registered under two Claude Code hook events —
+`~/.claude/tune-context/adoption.jsonl` by default (under `CLAUDE_CONFIG_DIR`, the
+override's `tune-context/adoption.jsonl` — see above), and `eval/adoption-report.mjs`
+turns that into a report — code search (semantic RAG vs the Grep tool, with
+shell-plumbing greps kept out of the RAG share), doctrine skills, subagents, and
+re-read churn — closing with an *earned* verdict: withheld below a PO-frozen floor of
+distinct sessions, and never a false ✗ for a lever the log can't see (RAG
+installed-but-unused vs not installed; method-level doctrine that leaves no tool call).
+It's registered under two Claude Code hook events —
 `PostToolUse` (every tool call) and `SubagentStart` (subagent spawns, which aren't
 regular tools).
 
+**Using both the plugin and `tune-context init` (CLI) on the same repo** registers
+the hook twice — once per channel — so every event logs twice. This is harmless
+(same script, same log, just doubled counts) and the report detects it: past a
+measured share of near-duplicate pairs it withholds the re-read-churn verdict
+instead of printing a number the doubling would have faked.
+
 ### Turn it on
 
 1. **Install the hook.** Either run **`/tune-context`** in your repo (it copies the
    script to `~/.claude/hooks/` and merges the hook entries into `settings.json`
    for you), or do it by hand:
-   - copy `hooks/adoption-log.mjs` → `~/.claude/hooks/adoption-log.mjs` (needs
-     Node ≥ 18 on `PATH`);
-   - add the `PostToolUse` **and** `SubagentStart` blocks from
-     [`skills/tune-context/templates/settings.json.tmpl`](skills/tune-context/templates/settings.json.tmpl)
-     to your `settings.json` — `~/.claude/settings.json` for every project, or a
-     repo's `.claude/settings.json` for just that one.
+   - copy `hooks/adoption-log.mjs` **and** `hooks/config-dir.mjs` (it imports the
+     latter for the log path) → `~/.claude/hooks/` (needs Node ≥ 18 on `PATH`);
+   - merge this into your `settings.json` — `~/.claude/settings.json` for every
+     project, or a repo's `.claude/settings.json` for just that one (if the file
+     doesn't exist yet, this can be the whole thing):
+     ```json
+     {
+       "hooks": {
+         "PostToolUse": [
+           {
+             "matcher": "*",
+             "hooks": [
+               { "type": "command", "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\"" }
+             ]
+           }
+         ],
+         "SubagentStart": [
+           {
+             "matcher": "*",
+             "hooks": [
+               { "type": "command", "command": "node \"$HOME/.claude/hooks/adoption-log.mjs\"" }
+             ]
+           }
+         ]
+       }
+     }
+     ```
+     Using `CLAUDE_CONFIG_DIR`? Replace `$HOME/.claude/hooks` with the literal
+     override path instead — `$HOME` is not expanded there (see
+     [`CLAUDE_CONFIG_DIR`](#claude_config_dir) above).
 
 2. **No reload needed.** Claude Code watches the settings files, so the new hooks
    go live within a few seconds of saving — **you do not need to reload VSCode,
@@ -137,7 +246,8 @@ regular tools).
    the `/hooks` command.
 
 3. **Just work.** Every tool call and subagent run now appends a line to
-   `~/.claude/tune-context/adoption.jsonl` (created on first write).
+   `~/.claude/tune-context/adoption.jsonl` by default (created on first write; under
+   `CLAUDE_CONFIG_DIR` it's the override's `tune-context/adoption.jsonl` instead).
 
 4. **Read the report** any time, from this checkout (or the installed package):
    ```bash
@@ -147,13 +257,16 @@ regular tools).
 
 **Stop / opt out:** delete the `PostToolUse` + `SubagentStart` entries from
 `settings.json` (watcher picks that up too). The log stays local under
-`~/.claude/tune-context/` and records only tool names, file paths, and
-skill/agent names — never full Bash command strings.
+`~/.claude/tune-context/` (or the `CLAUDE_CONFIG_DIR` override) and records only
+tool names, file paths, and skill/agent names — never full Bash command strings.
 
 **Honest scope:** this is a *behavioral proxy*, not a bill. Token cost lands only
 in OTEL (`CLAUDE_CODE_ENABLE_TELEMETRY=1` → `claude_code.cost.usage`, needs a
 collector), never a hook; and caveman is an output style with no tool call, so it
-can't be counted this way.
+can't be counted this way. Doctrine applied as *method* — narrow reads,
+contracts-first edits, delegation — is only partly visible too: no `Skill` call,
+but its trace shows up in the report's edit:read ratio, so the verdict never
+reads zero `Skill` calls as "unused."
 
 ### Getting real cost (OTEL) — outside tune-context
 

package/bin/tune-context

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// Extensionless alias so the plugin channel's bin/ PATH entry gives the same
+// `tune-context` command the npm channel already provides via package.json's
+// `bin` field. Claude Code exposes bin/ files under their literal filename —
+// no extension-stripping — so without this file, a plugin-only install
+// (no `npm install -g`) only offers `tune-context.mjs` (TASK-078). Real logic
+// stays in tune-context.mjs; this just re-executes it against the same
+// process.argv.
+import { main } from './tune-context.mjs';
+
+main();