@bglocation/tune-context 1.1.0 → 2.0.1

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "bglocation",
-  "description": "Context-engineering tooling for Claude Code from bglocation — token-saving doctrine, configurators and semantic-search wiring.",
+  "description": "Context-engineering tooling for Claude Code from bglocation \u2014 token-saving doctrine, configurators and semantic-search wiring.",
   "owner": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"
@@ -10,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.1.0",
+      "version": "2.0.1",
       "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.1.0",
+  "version": "2.0.1",
   "author": {
     "name": "Szymon Walczak",
     "url": "https://bglocation.dev"

package/CHANGELOG.md

@@ -5,6 +5,206 @@ 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.1] — 2026-07-26
+
+### Fixed
+
+- **The npm-installed CLI did nothing at all in 2.0.0.** `npm i -g` puts the
+  `bin` entry on PATH as a symlink named `tune-context`, with no extension, but
+  2.0.0's entry-point guard tested `process.argv[1].endsWith('tune-context.mjs')`.
+  That is false for the symlink, so `main()` never ran: every command —
+  `init`, `--version`, `--help` — exited 0 without printing a byte or touching a
+  file. Now compares resolved real paths, which holds for the npm symlink, a
+  direct `.mjs` invocation, the extensionless `bin/tune-context` wrapper (still
+  exactly one run, not two) and `import` from a test.
+- Only the npm channel was affected. Plugin installs call `bin/tune-context`,
+  which invokes `main()` itself, and the hooks are always registered by literal
+  path — both kept working.
+
+### Testing
+
+- The suite spawned `.../bin/tune-context.mjs` everywhere, which is the one shape
+  no user ever runs; that is why 119 green tests said nothing about a completely
+  dead CLI. Added a test that installs the binary the way npm does — through an
+  extensionless symlink — and asserts a silent exit 0 is a failure.
+
+### Upgrading from 2.0.0 (npm channel)
+
+Upgrading is not enough on its own. If you ran `tune-context init` under 2.0.0
+it exited 0 and looked like it worked, but **nothing was installed** — so
+`~/.claude/hooks/context-reminder.mjs` is missing and the `UserPromptSubmit`
+hook was never registered. Re-run it after upgrading:
+
+```bash
+npm i -g @bglocation/tune-context@2.0.1
+tune-context --version    # must print 2.0.1 — silence means the upgrade did not take
+tune-context init
+```
+
+The `init` is idempotent and additive: it never removes a hook or permission
+entry, and never touches content outside the managed blocks. Plugin-only
+installs were unaffected and need nothing.
+
+## [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

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`:
@@ -129,6 +139,51 @@ Without the override the generated `settings.json` keeps the portable
 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` by default (under `CLAUDE_CONFIG_DIR`, the
@@ -142,6 +197,12 @@ 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
@@ -149,10 +210,34 @@ regular tools).
    for you), or do it by hand:
    - 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`);
-   - 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.
+   - 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,

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();

package/bin/tune-context.mjs

@@ -1,10 +1,25 @@
 #!/usr/bin/env node
 // tune-context init — deterministic detect -> generate -> verify.
-// This is the CLI/plugin-bin twin of skills/tune-context/SKILL.md: same
-// managed-block rules, same "never clobber" guarantee, no model in the loop.
+//
+// This is the deterministic SUBSET of skills/tune-context/SKILL.md, not a full
+// twin of it. What it shares: the same managed-block rules and the same "never
+// clobber" guarantee. What it deliberately omits, because each needs judgment
+// a no-model-in-the-loop CLI cannot have (TASK-075):
+//
+//   • SKILL.md §2 step 4 — merging `.mcp.json` to add a semantic-search server
+//     when none was detected. Choosing *which* server to add for this repo is a
+//     judgment call; the CLI reads `.mcp.json` but never writes it.
+//   • SKILL.md §2 step 7 — wiring the wiki lever (RAG segment vs its own MCP vs
+//     a plain pointer). That choice depends on where the docs actually live and
+//     how they are hosted, which the CLI does not attempt to detect.
+//
+// "No model in the loop" is the feature here, not a gap — but the gap has to be
+// stated, or a CLI user cannot know what they did not get. Run the skill
+// (/tune-context) for the full pass.
+import { readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { claudeDirs, detectExistingConfig, detectMcpServers, detectStack } from '../cli/detect.mjs';
+import { claudeDirs, detectExistingConfig, detectMcpServers, detectRejectedMcpServers, detectStack } from '../cli/detect.mjs';
 import {
   buildPermissionsAllow,
   generateProjectClaudeMd,
@@ -21,26 +36,83 @@ const HOOK_EVENTS = [
   { event: 'SessionStart', scriptName: 'session-start-reinject.mjs' },
   { event: 'PostToolUse', scriptName: 'adoption-log.mjs' },
   { event: 'SubagentStart', scriptName: 'adoption-log.mjs' },
+  { event: 'UserPromptSubmit', scriptName: 'context-reminder.mjs' },
 ];
 
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * Version straight from the shipped package.json — one source of truth, the
+ * same file verify:plugin cross-checks against plugin.json/marketplace.json,
+ * so `--version` can never drift from what the manifests claim. Both channels
+ * ship it: npm always includes package.json in the tarball, and the plugin
+ * channel is a git clone of this repo (guarded in verify-plugin's REQUIRE).
+ */
+export function readVersion() {
+  return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+}
+
 function usage() {
-  console.log(`tune-context init — configure this repo for token-efficient Claude Code use.
+  return `tune-context init — configure this repo for token-efficient Claude Code use.
 
 Usage:
   tune-context init [--cwd <dir>]
   tune-context --help
-`);
+  tune-context --version
+`;
+}
+
+// Pure so it is unit-testable without spawning a process. `init` is the ONLY
+// accepted command — no bare-args shortcut (PO decision 2026-07-25, TASK-078):
+// README never once documents calling this without it, and accepting anything
+// un-checked is exactly how a subcommand typo used to silently run init
+// against the wrong repo instead of failing loud.
+export function parseArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return { mode: 'help' };
+  // Before the command check, like --help: `--version` is a query about the
+  // tool, not an operation on a repo, so it must not require a subcommand.
+  if (argv.includes('--version') || argv.includes('-v')) return { mode: 'version' };
+  const [command, ...rest] = argv;
+  if (command !== 'init') {
+    return {
+      mode: 'error',
+      message: command === undefined ? 'Missing command: init' : `Unknown command: ${command}`,
+    };
+  }
+  const cwdFlagIdx = rest.indexOf('--cwd');
+  if (cwdFlagIdx === -1) return { mode: 'init', cwd: process.cwd() };
+  const value = rest[cwdFlagIdx + 1];
+  // Undefined (last arg) or another flag (e.g. `--cwd --foo`) both mean "no
+  // value was actually given" — resolve(undefined) used to throw a raw
+  // ERR_INVALID_ARG_TYPE with a Node stacktrace instead of a usage message.
+  if (value === undefined || value.startsWith('-')) {
+    return { mode: 'error', message: 'Missing value for --cwd' };
+  }
+  return { mode: 'init', cwd: resolve(value) };
 }
 
 function runInit(cwd) {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const pkgRoot = resolve(here, '..');
   const templatesDir = join(pkgRoot, 'skills', 'tune-context', 'templates');
   const { claudeDir } = claudeDirs();
 
   const stack = detectStack(cwd);
   const existing = detectExistingConfig(cwd);
-  const mcpServers = detectMcpServers(cwd);
+
+  // A server the user rejected out of .mcp.json must not get an
+  // `mcp__<server>__*` permission rule, nor a CLAUDE.md line advertising a
+  // lever this session does not have (TASK-075). Rejection applies ONLY to
+  // project-scope servers — see detectRejectedMcpServers for why user- and
+  // local-scope servers are out of its reach.
+  const allMcpServers = detectMcpServers(cwd);
+  const rejectedNames = detectRejectedMcpServers([
+    existing.userSettingsJson,
+    existing.projectSettingsJson,
+    existing.projectSettingsLocalJson,
+  ]);
+  const isRejected = (s) => s.scope === 'project' && rejectedNames.has(s.name);
+  const mcpServers = allMcpServers.filter((s) => !isRejected(s));
+  const rejectedServers = allMcpServers.filter(isRejected);
+
   const detection = { stack, mcpServers };
 
   const synced = installDoctrine(pkgRoot, claudeDir);
@@ -71,6 +143,10 @@ function runInit(cwd) {
   console.log(`Hooks merged into ${existing.userSettingsJson}: ${hooksAdded.length ? hooksAdded.join(', ') : 'already present'}`);
   console.log(`Permissions merged into ${existing.projectSettingsJson}: ${permissionsAdded.length ? permissionsAdded.join(', ') : 'already present'}`);
   console.log(`MCP servers detected: ${mcpServers.length ? mcpServers.map((s) => `${s.name} (${s.scope}, ${s.classification})`).join(', ') : 'none'}`);
+  // Surfaced, never silent: skipping a server is a decision the user should see.
+  if (rejectedServers.length) {
+    console.log(`  skipped (rejected via disabledMcpjsonServers): ${rejectedServers.map((s) => s.name).join(', ')} — no permission rule, no CLAUDE.md line`);
+  }
 
   console.log(`\nVerify: ${result.ok ? 'OK' : 'FAILED'}`);
   for (const check of result.checks) {
@@ -79,11 +155,55 @@ function runInit(cwd) {
   if (!result.ok) process.exitCode = 1;
 }
 
-const args = process.argv.slice(2);
-if (args.includes('--help') || args.includes('-h')) {
-  usage();
-} else {
-  const cwdFlagIdx = args.indexOf('--cwd');
-  const cwd = cwdFlagIdx !== -1 ? resolve(args[cwdFlagIdx + 1]) : process.cwd();
-  runInit(cwd);
+export function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.mode === 'help') {
+    console.log(usage());
+  } else if (parsed.mode === 'version') {
+    // Bare number, no prefix or banner — this is what a script greps.
+    console.log(readVersion());
+  } else if (parsed.mode === 'error') {
+    // Usage on stderr + exit 1, never a stacktrace, and — because this whole
+    // branch returns before runInit() is ever called — no config file is
+    // touched on an invalid invocation (TASK-078).
+    process.stderr.write(`${parsed.message}\n\n${usage()}`);
+    process.exitCode = 1;
+  } else {
+    runInit(parsed.cwd);
+  }
+}
+
+/**
+ * True only when THIS file is the process entry point, so importing it for
+ * parseArgs/main (tests, or the extensionless bin/tune-context wrapper) never
+ * runs the CLI as a side effect of the import.
+ *
+ * Deliberately NOT a filename-suffix test on argv[1]. npm installs the
+ * package.json `bin` entry as a symlink named `tune-context` — no extension —
+ * so `argv[1].endsWith('tune-context.mjs')` was false for every real npm-channel
+ * invocation: main() never ran and the CLI exited 0 in total silence. That
+ * shipped in 2.0.0 (see the symlink test in test/bin-tune-context.test.mjs);
+ * the whole suite missed it because tests and smoke:init both spawn the full
+ * `.../bin/tune-context.mjs` path, which is the one shape a user never uses.
+ *
+ * Comparing resolved real paths holds for all four shapes: direct `.mjs`
+ * invocation, the npm symlink (resolves THROUGH the link to this file), the
+ * extensionless wrapper (a different real path, so this stays false and the
+ * wrapper's own main() call is the single entry — no double run), and `import`
+ * from a test (argv[1] is the test runner). realpathSync on both sides also
+ * survives a symlinked package dir, as `npm link` and nvm both produce.
+ */
+function isEntryPoint() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    // argv[1] can name something unresolvable (deleted, or a bare `-`); a CLI
+    // that cannot identify its own entry point must stay silent, not crash.
+    return false;
+  }
+}
+
+if (isEntryPoint()) {
+  main();
 }