@bglocation/tune-context 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+  "name": "bglocation",
+  "owner": {
+    "name": "Szymon Walczak",
+    "url": "https://bglocation.dev"
+  },
+  "plugins": [
+    {
+      "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.0",
+      "author": {
+        "name": "Szymon Walczak",
+        "url": "https://bglocation.dev"
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "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.0",
+  "author": {
+    "name": "Szymon Walczak",
+    "url": "https://bglocation.dev"
+  },
+  "homepage": "https://bglocation.dev",
+  "repository": "https://gitlab.com/bglocation/tune-context",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "context-engineering",
+    "token-efficiency",
+    "configurator",
+    "skills"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Szymon Walczak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# tune-context
+
+Context-efficiency configurator for Claude Code — the doctrine (token-saving
+working methods) packaged as **skills**, plus a `tune-context` configurator that
+scaffolds a cost-optimal, high-quality setup (lean CLAUDE.md + skills + subagents
++ settings + hooks + MCP).
+
+**Self-contained** — zero dependency on any host repo. Ships two ways: a Claude
+Code **plugin** and an **npm CLI** (`tune-context init`), both under
+`@bglocation`. Incubated inside the [`code-search-mcp`](https://gitlab.com/bglocation/code-search-mcp)
+project, now extracted to its own repository.
+
+```
+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
+├── 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)
+```
+
+## Quick start
+
+Node ≥ 18, no build step. From the repo you want to configure:
+
+```bash
+# Configure this repo — deterministic, no Claude session needed
+npx -p @bglocation/tune-context tune-context init
+```
+
+> The `-p <pkg> tune-context` form is deliberate: the package is **scoped**
+> (`@bglocation/…`) and its bin (`tune-context`) doesn't match the scope, so a
+> bare `npx @bglocation/tune-context` can fail to resolve the command. `-p`
+> installs the package and names the bin explicitly.
+
+That single command detects the stack + MCP servers, writes a lean `CLAUDE.md`,
+syncs the doctrine skills/agents/hooks into `~/.claude/`, merges hooks and
+permissions, and prints a verification report. It's idempotent — safe to re-run.
+
+Install it globally if you'll use it across repos:
+
+```bash
+npm install -g @bglocation/tune-context
+tune-context init            # in any repo
+```
+
+Prefer the model-driven path? Install the plugin and use the skill — it does the
+same thing plus wiki wiring and richer MCP detection:
+
+```bash
+claude --plugin-dir "$(npm root -g)/@bglocation/tune-context"   # global install
+# then, inside a session in the repo you want to configure:
+/tune-context
+```
+
+The section below breaks down all three entry points and when to use each.
+
+## Install & run
+
+Three entry points, same doctrine. Pick whichever fits how you work:
+
+**1. `/tune-context` skill (recommended).** With the plugin installed (below), run
+`/tune-context` in any repo. It detects the stack, MCP servers and existing config,
+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:
+
+```bash
+npx -p @bglocation/tune-context tune-context init           # runs in the current repo
+npx -p @bglocation/tune-context tune-context init --cwd .    # explicit target dir
+# from a checkout (dev):
+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.
+
+**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`:
+
+```text
+/plugin marketplace add https://gitlab.com/bglocation/tune-context
+/plugin install tune-context@bglocation
+```
+
+Or point Claude at a directory directly (no marketplace):
+
+```bash
+claude --plugin-dir "$(npm root -g)/@bglocation/tune-context"   # global npm install
+claude --plugin-dir /path/to/tune-context                       # or a local checkout
+```
+
+The plugin manifest (`.claude-plugin/plugin.json`) and hook wiring
+(`hooks/hooks.json`, via `${CLAUDE_PLUGIN_ROOT}`) register the four hook events
+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).
+
+## 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 —
+`PostToolUse` (every tool call) and `SubagentStart` (subagent spawns, which aren't
+regular tools).
+
+### 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.
+
+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,
+   restart the extension, or start a new session.** Only if nothing shows up after
+   a few seconds, restart the session to force a reload. Check what's active with
+   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).
+
+4. **Read the report** any time, from this checkout (or the installed package):
+   ```bash
+   node eval/adoption-report.mjs            # default log location
+   node eval/adoption-report.mjs --log <path>
+   ```
+
+**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.
+
+**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.
+
+### Getting real cost (OTEL) — outside tune-context
+
+tune-context does not set this up for you (deliberate — see TASK-062: it needs
+infra this tool stays zero-infra without). If you want actual dollars instead of
+the behavioral proxy above:
+
+```bash
+export CLAUDE_CODE_ENABLE_TELEMETRY=1     # off by default
+export OTEL_METRICS_EXPORTER=prometheus   # NOT console — console is CLI-only and
+                                           # conflicts with the SDK/message stream
+                                           # a VSCode-extension session may use
+export OTEL_METRIC_EXPORT_INTERVAL=1000   # default 60000ms; short sessions can
+                                           # exit before ever exporting
+```
+
+Start a new Claude Code session with those set (must be inherited at launch —
+e.g. exported in the shell profile before opening VSCode, not just typed into an
+in-editor terminal), work for a bit, then:
+
+```bash
+curl -s http://localhost:9464/metrics | grep claude_code
+```
+
+Look for **`claude_code.cost.usage`** (USD, carries `session.id`) and
+**`claude_code.token.usage`** (token counts). No collector needed just to see the
+numbers — `curl` against the local Prometheus endpoint is enough; wire a real
+Prometheus/Grafana at that endpoint only if you want history instead of a
+point-in-time read. Traces (`OTEL_TRACES_EXPORTER=otlp`) need an extra
+`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` flag and aren't needed just for cost.
+
+## Design principles
+- **Minimal always-on**, depth on-demand: thin CLAUDE.md points at skills; skill
+  *bodies* load only when invoked (progressive disclosure).
+- **`@import` is not a cost lever** — it is inlined in full. Reduce via skills.
+- **Right-size the model per role** (subagent `model:`).
+- **Caveman targets output** (uncached, ~4–5× input); skills/subagents target the
+  window.
+
+## Local dogfooding
+`node scripts/sync-tune-context.mjs` mirrors `skills/`, `agents/` and `hooks/`
+into `~/.claude/` (hooks get `chmod 755`). Source of truth stays here. Skills take
+effect on the next Claude Code session; hooks are hot-reloaded by the settings
+file watcher (once their `settings.json` entries exist).
+
+## Related — the `@bglocation` toolbelt
+- **[`@bglocation/code-search-mcp`](https://gitlab.com/bglocation/code-search-mcp)**
+  — semantic code index (RAG) + MCP server. The strongest lever tune-context
+  detects and wires: search by meaning instead of `grep`, read only the returned
+  spans. tune-context runs fine without it, but recommends it when no
+  semantic-search MCP is present.
+- **[bglocation.dev](https://bglocation.dev)** — the rest of the toolbelt.

package/agents/explore-cheap.md

@@ -0,0 +1,18 @@
+---
+name: explore-cheap
+description: Cheap read-only fan-out for broad code/file searches — "where is everything about X", naming-convention hunts, locating code across many files. Returns a tight conclusion, not raw dumps. Use instead of grepping many files in the main session.
+tools: Read, Grep, Glob
+model: haiku
+---
+
+# explore-cheap
+
+Read-only search fan-out on a cheap model. You sweep many files and return a
+tight conclusion — the main session pays for the answer, not the search.
+
+- Locate code/config across the repo; map naming conventions; find all call sites.
+- Read excerpts, not whole files. Report `path:line` references plus a short synthesis.
+- **Read-only:** never edit, run builds, or change anything.
+- You do file-level search (grep/glob). Semantic "where/why is X" search is the
+  main session's job (`search_codebase`); you handle the exhaustive sweeps it
+  would rather not pull into its context.

package/agents/reviewer.md

@@ -0,0 +1,18 @@
+---
+name: reviewer
+description: Reviews a diff or a slice of code for correctness bugs and clear simplifications — judgment work, not mechanical search. Returns findings ranked by severity with rationale. Use for a second-pass review before committing non-trivial changes.
+tools: Read, Grep, Glob, Bash
+model: fable
+---
+
+# reviewer
+
+Second-pass review on a strong model — this is judgment, so it is worth the
+better model (right-sizing: cheap for search, strong for review). For the hardest
+reviews, override to `opus` per invocation.
+
+- Correctness bugs first, then clear simplifications / reuse.
+- Read the diff and enough surrounding code to judge — don't rewrite, report.
+- Return findings ranked by severity, each with a one-line rationale and a
+  `path:line` anchor.
+- Prefer `git diff` over re-reading whole files.

package/bin/tune-context.mjs

@@ -0,0 +1,89 @@
+#!/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.
+import { readFileSync } 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 {
+  buildPermissionsAllow,
+  generateProjectClaudeMd,
+  generateUserClaudeMd,
+  installDoctrine,
+  mergeHooks,
+  mergePermissions,
+} from '../cli/generate.mjs';
+import { verify } from '../cli/verify.mjs';
+
+const HOOK_EVENTS = [
+  { event: 'PreCompact', scriptName: 'pre-compact-snapshot.mjs' },
+  { event: 'SessionStart', scriptName: 'session-start-reinject.mjs' },
+  { event: 'PostToolUse', scriptName: 'adoption-log.mjs' },
+  { event: 'SubagentStart', scriptName: 'adoption-log.mjs' },
+];
+
+function usage() {
+  console.log(`tune-context init — configure this repo for token-efficient Claude Code use.
+
+Usage:
+  tune-context init [--cwd <dir>]
+  tune-context --help
+`);
+}
+
+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);
+  const detection = { stack, mcpServers };
+
+  const synced = installDoctrine(pkgRoot, claudeDir);
+  const userClaudeMd = generateUserClaudeMd(claudeDir, templatesDir);
+  const projectClaudeMd = generateProjectClaudeMd(cwd, detection, templatesDir);
+
+  const settingsTemplate = JSON.parse(readFileSync(join(templatesDir, 'settings.json.tmpl'), 'utf8'));
+  const hooksAdded = mergeHooks(existing.userSettingsJson, { hooks: settingsTemplate.hooks });
+  const permissionsAllow = buildPermissionsAllow(detection);
+  const permissionsAdded = mergePermissions(existing.projectSettingsJson, permissionsAllow);
+
+  const result = verify({
+    claudeDir,
+    userSettingsPath: existing.userSettingsJson,
+    projectSettingsPath: existing.projectSettingsJson,
+    expectedHookCommands: HOOK_EVENTS,
+    expectedPermissions: permissionsAllow,
+  });
+
+  console.log(`tune-context init — ${cwd}\n`);
+  console.log(`Stack: ${stack.ecosystem}${stack.name ? ` (${stack.name})` : ''}${stack.monorepo ? ', monorepo' : ''}`);
+  if (stack.undetectedCommands) {
+    console.log('  build/test/lint commands not detected for this ecosystem — filled with TODO placeholders in CLAUDE.md.');
+  }
+  console.log(`\nDoctrine synced to ${claudeDir}: ${synced.length} item(s)`);
+  console.log(`User CLAUDE.md: ${userClaudeMd.changed ? 'written' : `skipped (${userClaudeMd.skipped})`}`);
+  console.log(`Project CLAUDE.md: ${projectClaudeMd.changed ? `updated ${projectClaudeMd.path}` : 'already up to date'}`);
+  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'}`);
+
+  console.log(`\nVerify: ${result.ok ? 'OK' : 'FAILED'}`);
+  for (const check of result.checks) {
+    console.log(`  ${check.ok ? '✓' : '✗'} ${check.name}${check.detail ? ` — ${check.detail}` : ''}`);
+  }
+  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);
+}

package/cli/detect.mjs

@@ -0,0 +1,114 @@
+// Read-only detection: stack, existing config, MCP servers across every
+// scope. Facts over guesses — every value here is read from a real file, none
+// invented. Mirrors skills/tune-context/SKILL.md §1 "Detect".
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve the base Claude config directory, honoring CLAUDE_CONFIG_DIR. */
+export function claudeDirs() {
+  const override = process.env.CLAUDE_CONFIG_DIR;
+  return {
+    claudeDir: override || join(homedir(), '.claude'),
+    claudeJsonPath: override ? join(override, '.claude.json') : join(homedir(), '.claude.json'),
+  };
+}
+
+/** Package manager / language / verified scripts / monorepo shape. Facts only — no guessed commands. */
+export function detectStack(cwd) {
+  const pkgPath = join(cwd, 'package.json');
+  const pkg = readJson(pkgPath);
+  if (pkg) {
+    const scripts = pkg.scripts || {};
+    const monorepo = Boolean(
+      pkg.workspaces || existsSync(join(cwd, 'pnpm-workspace.yaml')) || existsSync(join(cwd, 'turbo.json')) || existsSync(join(cwd, 'nx.json')),
+    );
+    return {
+      ecosystem: 'node',
+      name: pkg.name || null,
+      packageManager: existsSync(join(cwd, 'pnpm-lock.yaml'))
+        ? 'pnpm'
+        : existsSync(join(cwd, 'yarn.lock'))
+          ? 'yarn'
+          : 'npm',
+      buildCmd: scripts.build ? 'npm run build' : null,
+      testCmd: scripts.test ? 'npm test' : null,
+      lintCmd: scripts.lint ? 'npm run lint' : null,
+      monorepo,
+    };
+  }
+  for (const [file, ecosystem] of [
+    ['pyproject.toml', 'python'],
+    ['go.mod', 'go'],
+    ['Cargo.toml', 'rust'],
+  ]) {
+    if (existsSync(join(cwd, file))) {
+      return { ecosystem, name: null, packageManager: null, buildCmd: null, testCmd: null, lintCmd: null, monorepo: false, undetectedCommands: true };
+    }
+  }
+  return { ecosystem: 'unknown', name: null, packageManager: null, buildCmd: null, testCmd: null, lintCmd: null, monorepo: false, undetectedCommands: true };
+}
+
+/** Existing config files this run must merge into, never clobber. */
+export function detectExistingConfig(cwd) {
+  const { claudeDir } = claudeDirs();
+  return {
+    projectClaudeMd: existsSync(join(cwd, 'CLAUDE.md')) ? join(cwd, 'CLAUDE.md') : null,
+    userClaudeMd: existsSync(join(claudeDir, 'CLAUDE.md')) ? join(claudeDir, 'CLAUDE.md') : null,
+    projectMcpJson: existsSync(join(cwd, '.mcp.json')) ? join(cwd, '.mcp.json') : null,
+    projectSettingsJson: join(cwd, '.claude', 'settings.json'),
+    userSettingsJson: join(claudeDir, 'settings.json'),
+  };
+}
+
+/** Heuristic only — classifies by server name/command, does not introspect tools/list. */
+function classifyMcpServer(name, config) {
+  const haystack = [name, config?.command, ...(config?.args || [])].filter(Boolean).join(' ').toLowerCase();
+  if (/search|rag|embed|semantic|vector/.test(haystack)) return 'semantic code search';
+  if (/wiki|confluence|notion|docs?\b/.test(haystack)) return 'wiki / docs';
+  if (/postgres|mysql|sqlite|mongo|\bsql\b|\bdb\b/.test(haystack)) return 'database';
+  if (/git(hub|lab)?|issue|jira/.test(haystack)) return 'VCS / issues';
+  return 'unknown';
+}
+
+/**
+ * Every MCP server visible to this project, across all three scopes, each
+ * tagged with scope + a heuristic classification (name/command keywords —
+ * NOT a tools/list introspection; treat as a starting point, not ground truth).
+ */
+export function detectMcpServers(cwd) {
+  const { claudeJsonPath } = claudeDirs();
+  const servers = [];
+
+  const projectMcp = readJson(join(cwd, '.mcp.json'));
+  for (const [name, config] of Object.entries(projectMcp?.mcpServers || {})) {
+    servers.push({ scope: 'project', name, classification: classifyMcpServer(name, config) });
+  }
+
+  const claudeJson = readJson(claudeJsonPath);
+  for (const [name, config] of Object.entries(claudeJson?.mcpServers || {})) {
+    servers.push({ scope: 'user', name, classification: classifyMcpServer(name, config) });
+  }
+  const projectEntry = claudeJson?.[cwd];
+  for (const [name, config] of Object.entries(projectEntry?.mcpServers || {})) {
+    servers.push({ scope: 'local', name, classification: classifyMcpServer(name, config) });
+  }
+
+  return servers;
+}
+
+/** MCP gating keys from a settings.json — narrows which detected servers are actually reachable. */
+export function detectMcpGating(settingsJsonPath) {
+  const settings = readJson(settingsJsonPath);
+  if (!settings) return null;
+  const { enabledMcpjsonServers, disabledMcpjsonServers, allowedMcpServers, deniedMcpServers } = settings;
+  return { enabledMcpjsonServers, disabledMcpjsonServers, allowedMcpServers, deniedMcpServers };
+}

package/cli/generate.mjs

@@ -0,0 +1,123 @@
+// Idempotent generation: project CLAUDE.md (managed block), user CLAUDE.md
+// (only if missing), doctrine skills/agents/hooks, and settings.json merges
+// (hooks as a set keyed by command, permissions.allow as a union). Never
+// clobbers hand-written content. Mirrors SKILL.md §2 "Generate".
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { syncDoctrine } from './sync-doctrine.mjs';
+import { upsertManagedBlock } from './managed-block.mjs';
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, obj) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(obj, null, 2)}\n`);
+}
+
+function fillTemplate(template, slots) {
+  let out = template;
+  for (const [key, value] of Object.entries(slots)) {
+    out = out.replaceAll(`{{${key}}}`, value);
+  }
+  return out;
+}
+
+/** Extract the managed-block inner content from a project CLAUDE.md template file. */
+function templateInnerBlock(templatePath) {
+  const raw = readFileSync(templatePath, 'utf8');
+  const start = raw.indexOf('<!-- >>> tune-context (managed) >>>');
+  const end = raw.indexOf('<!-- <<< tune-context (managed) <<< -->');
+  const startLineEnd = raw.indexOf('\n', start) + 1;
+  return raw.slice(startLineEnd, end).trimEnd();
+}
+
+export function generateProjectClaudeMd(cwd, detection, templatesDir) {
+  const templatePath = join(templatesDir, 'CLAUDE.md.project.tmpl');
+  const inner = templateInnerBlock(templatePath);
+
+  const mcpRules = detection.mcpServers.length
+    ? detection.mcpServers.map((s) => `- \`${s.name}\` (${s.scope}, ${s.classification}) — see token-efficiency skill for the matching rule.`).join('\n')
+    : '<!-- fill in: no MCP server detected — none, or add one -->';
+
+  const filled = fillTemplate(inner, {
+    PROJECT_NAME: detection.stack.name || '<!-- fill in: project name -->',
+    ONE_LINE_WHAT_THIS_IS: '<!-- fill in: one sentence, what this project is -->',
+    BUILD_CMD: detection.stack.buildCmd || '# no build script detected — fill in or delete this line',
+    TEST_CMD: detection.stack.testCmd || '# no test script detected — fill in or delete this line',
+    LINT_CMD: detection.stack.lintCmd || '# no lint script detected — fill in or delete this line',
+    RUN_NOTES: detection.stack.monorepo ? '<!-- monorepo detected — note which package/workspace to run commands from -->' : '',
+    MCP_RULES: mcpRules,
+    ARCHITECTURE_BULLETS: '<!-- fill in: 3-6 lines, module -> responsibility -->',
+    CONVENTIONS: '<!-- fill in: only rules that bite -->',
+  });
+
+  const path = join(cwd, 'CLAUDE.md');
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+  const { content, changed } = upsertManagedBlock(existing, filled);
+  if (changed) writeFileSync(path, content);
+  return { path, changed };
+}
+
+export function generateUserClaudeMd(claudeDir, templatesDir) {
+  const path = join(claudeDir, 'CLAUDE.md');
+  if (existsSync(path)) return { path, changed: false, skipped: 'already exists — never overwrite a user-tuned file' };
+  const templatePath = join(templatesDir, 'CLAUDE.md.user.tmpl');
+  mkdirSync(claudeDir, { recursive: true });
+  writeFileSync(path, readFileSync(templatePath, 'utf8'));
+  return { path, changed: true };
+}
+
+export function installDoctrine(pkgRoot, claudeDir) {
+  return syncDoctrine(pkgRoot, claudeDir);
+}
+
+/** Merge the hooks template into a settings.json, keyed by `command` so a second run is a no-op. */
+export function mergeHooks(settingsPath, hooksTemplate) {
+  const settings = readJson(settingsPath, {});
+  settings.hooks = settings.hooks || {};
+  const added = [];
+  for (const [event, groups] of Object.entries(hooksTemplate.hooks)) {
+    settings.hooks[event] = settings.hooks[event] || [];
+    for (const group of groups) {
+      for (const hook of group.hooks) {
+        const alreadyPresent = settings.hooks[event].some((g) => g.hooks?.some((h) => h.command === hook.command));
+        if (!alreadyPresent) {
+          settings.hooks[event].push(group);
+          added.push(`${event}: ${hook.command}`);
+        }
+      }
+    }
+  }
+  if (added.length) writeJson(settingsPath, settings);
+  return added;
+}
+
+/** Union permissions.allow with the detected commands — dedupe, never remove entries. */
+export function mergePermissions(settingsPath, allowEntries) {
+  const settings = readJson(settingsPath, {});
+  settings.permissions = settings.permissions || {};
+  const existing = settings.permissions.allow || [];
+  const merged = [...new Set([...existing, ...allowEntries])];
+  const added = allowEntries.filter((e) => !existing.includes(e));
+  if (added.length) {
+    settings.permissions.allow = merged;
+    writeJson(settingsPath, settings);
+  }
+  return added;
+}
+
+export function buildPermissionsAllow(detection) {
+  const allow = ['Bash(git status:*)', 'Bash(git diff:*)', 'Bash(git log:*)'];
+  if (detection.stack.buildCmd) allow.push(`Bash(${detection.stack.buildCmd}:*)`);
+  if (detection.stack.testCmd) allow.push(`Bash(${detection.stack.testCmd}:*)`);
+  if (detection.stack.lintCmd) allow.push(`Bash(${detection.stack.lintCmd}:*)`);
+  for (const server of detection.mcpServers) allow.push(`mcp__${server.name}__*`);
+  return allow;
+}

package/cli/managed-block.mjs

@@ -0,0 +1,26 @@
+// Idempotent managed-block merge for CLAUDE.md — replace only what's between
+// the markers; hand-written content outside them is never touched. If the
+// markers are absent, append a fresh block instead of rewriting the file.
+export const START_MARKER = '<!-- >>> tune-context (managed) >>>';
+export const END_MARKER = '<!-- <<< tune-context (managed) <<< -->';
+
+/**
+ * @param {string|null} existing - current file content, or null if the file doesn't exist yet
+ * @param {string} innerBlock - the freshly generated managed content (without markers)
+ * @returns {{content: string, changed: boolean}}
+ */
+export function upsertManagedBlock(existing, innerBlock) {
+  const block = `${START_MARKER}\n${innerBlock}\n${END_MARKER}`;
+  if (existing == null) {
+    return { content: `${block}\n`, changed: true };
+  }
+  const startIdx = existing.indexOf(START_MARKER);
+  const endIdx = existing.indexOf(END_MARKER);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const next = existing.slice(0, startIdx) + block + existing.slice(endIdx + END_MARKER.length);
+    return { content: next, changed: next !== existing };
+  }
+  const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+  const next = `${existing}${sep}\n${block}\n`;
+  return { content: next, changed: true };
+}