@viloforge/vfkb 0.2.1

package/dist/index-store.js

@@ -0,0 +1,101 @@
+// Pluggable read index (ADR-0013). v1 default = pure-JS in-memory, rebuilt from
+// JSONL (source of truth). A better-sqlite3 FTS5 backend is an OPTIONAL future
+// implementation behind this same interface — the engine never hard-depends on it.
+//
+// Freshness (ADR-0014): the index compares a content-derived token before serving
+// and rebuilds on mismatch (rebuild-on-doubt — cheap because in-memory + small).
+import { contentHash, materialize, readMeta, readRecords } from './storage.js';
+// Light suffix stripping (NOT a full Porter stemmer) so a natural-language query
+// term lexically matches the stored wording: hanging/hangs -> hang,
+// silently/silent -> silent. Found load-bearing by the devops-kb live turn — the
+// agent phrased "hanging silent" while the entry said "hangs silently", so the
+// relevant gotcha scored ~0 and was never surfaced. Conservative: min stem length
+// 3, longest suffix first; mismatches it can't resolve (running/runs) are accepted
+// for v1 — the real robustness fix is the deferred semantic reranker (ADR-0012).
+function stem(t) {
+    for (const suf of ['ing', 'ed', 'ly', 'es', 's']) {
+        if (t.length - suf.length >= 3 && t.endsWith(suf))
+            return t.slice(0, -suf.length);
+    }
+    return t;
+}
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1)
+        .map(stem);
+}
+// Distinct stemmed terms in a query — the denominator for RFC-001's relevance
+// floor (matched / queryTermCount). Shares the tokenizer/stemmer with searchScored
+// so the floor and the search agree on what a "term" is.
+export function queryTermCount(query) {
+    return new Set(tokenize(query)).size;
+}
+export class InMemoryIndex {
+    entries = [];
+    token = '';
+    constructor() {
+        this.rebuild();
+    }
+    rebuild() {
+        this.entries = materialize(readRecords());
+        this.token = contentHash(this.entries);
+    }
+    // Rebuild iff the persisted content token differs from what we hold.
+    // The meta hash is authoritative when present; else recompute from JSONL
+    // (covers a git pull that changed entries.jsonl but not the sidecar).
+    ensureFresh() {
+        const persisted = readMeta()?.content_hash ?? contentHash();
+        if (persisted !== this.token)
+            this.rebuild();
+    }
+    all() {
+        this.ensureFresh();
+        return this.entries;
+    }
+    get(id) {
+        this.ensureFresh();
+        return this.entries.find((e) => e.id === id);
+    }
+    // Stage-1 relevance: stemmed term-overlap count over text + tags — NOT BM25
+    // (no IDF, no length normalization; the score is # of entry tokens matching a
+    // query term). Adequate as a candidate signal at per-project scale; semantic
+    // ranking is the deferred EmbeddingReranker (ADR-0012/0016). The envelope-aware
+    // Heuristic reranker is a separate Stage-2 applied to these candidates.
+    searchScored(query, k = 30) {
+        this.ensureFresh();
+        const terms = new Set(tokenize(query));
+        if (terms.size === 0)
+            return [];
+        return this.entries
+            .map((entry) => {
+            // tags may be absent on legacy or externally-projected entries (e.g. vfwb's
+            // lossy projection into .vfkb) — never let a tagless entry crash search.
+            const hay = tokenize(entry.text + ' ' + (entry.tags ?? []).join(' '));
+            let score = 0;
+            const hit = new Set();
+            for (const t of hay)
+                if (terms.has(t)) {
+                    score++;
+                    hit.add(t);
+                }
+            return { entry, score, matched: hit.size };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => b.score - a.score || b.entry.updated.localeCompare(a.entry.updated))
+            .slice(0, k);
+    }
+    search(query, k = 30) {
+        return this.searchScored(query, k).map((x) => x.entry);
+    }
+    freshnessToken() {
+        return this.token;
+    }
+}
+// ADR-0013: select the index backend. v1 always returns the pure-JS in-memory
+// index (zero native deps). A future SQLite/FTS5 backend would be auto-detected
+// here and fall back to in-memory if the native module is absent.
+export function selectIndex() {
+    return new InMemoryIndex();
+}

package/dist/init.js

@@ -0,0 +1,264 @@
+// FR-1 (ADR-0030) — `vfkb init [project]`: idempotently scaffold a CONSUMER repo
+// so a session there runs on vfkb automatically. Writes the auto-layer wiring in
+// the portable `$VFKB_HOME` form (FR-2), the .gitignore stanza, an empty brain,
+// and a parameterized "how we track work HERE" snippet. Re-running is safe: each
+// piece is created-if-absent / merged-if-present, and a brain is NEVER clobbered.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { writeManifest } from './manifest.js';
+const AGENTS_MARKER = '<!-- vfkb:how-we-track-work -->';
+const BOOTSTRAP_REL = '.vfkb/bin/bootstrap.mjs';
+// The wiring entry-point is a COMMITTED, RELATIVE bootstrap (ADR-0031) — always
+// resolvable in any clone. The bootstrap resolves the real engine via $VFKB_HOME
+// at runtime and degrades gracefully (a clear banner, never a crash/blocked write)
+// when it is unset. This also avoids depending on `${VFKB_HOME}` arg-expansion.
+function mcpConfig(project) {
+    return {
+        command: 'node',
+        args: [BOOTSTRAP_REL, 'mcp'],
+        env: { VFKB_DATA_DIR: '.vfkb', VFKB_PROJECT: project },
+    };
+}
+// Anchor hook paths to the project root Claude Code injects into the hook env
+// ($CLAUDE_PROJECT_DIR), defaulting to the CWD-relative form when it is unset so the
+// wiring never regresses. Hooks run in the SESSION's cwd — which is NOT guaranteed to
+// be the repo root (it follows `cd`) — so the bare-relative `node .vfkb/bin/bootstrap.mjs`
+// threw MODULE_NOT_FOUND the moment a session cd'd out of the root (issue #22, ADR-0035).
+// $CLAUDE_PROJECT_DIR is CWD-independent (empirically verified) and hook commands are
+// shell-run, so `${VAR:-.}` parameter-expansion resolves. (The MCP server in .mcp.json
+// stays relative — it is spawned once at session start with cwd=root, not re-invoked.)
+function hookCommand(project, sub) {
+    const root = '${CLAUDE_PROJECT_DIR:-.}';
+    return `VFKB_DATA_DIR=${root}/.vfkb VFKB_PROJECT=${project} node ${root}/${BOOTSTRAP_REL} cli hook ${sub}`;
+}
+// The bootstrap source, written verbatim into the consumer repo. Self-contained
+// (no engine import — it must run even when the engine is unresolvable). Bump
+// BOOTSTRAP_VERSION on a change so `vfkb init` upgrades an older one in place.
+const BOOTSTRAP_VERSION = 2;
+const BOOTSTRAP_SRC = `#!/usr/bin/env node
+// vfkb engine bootstrap (ADR-0031) — vfkb-bootstrap-version: ${BOOTSTRAP_VERSION}
+// Committed at a RELATIVE path so it is always resolvable. Resolves the real
+// engine via $VFKB_BUNDLE_DIR at runtime; degrades GRACEFULLY (clear, actionable
+// message; never breaks the session) when it is unset or the bundles are missing.
+// DO NOT hand-edit — regenerated by \`vfkb init\`.
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+const mode = process.argv[2] === 'mcp' ? 'mcp' : 'cli';
+const passthrough = process.argv.slice(3);
+// VFKB_BUNDLE_DIR is canonical; VFKB_HOME is a kept-working deprecated alias.
+const home = process.env.VFKB_BUNDLE_DIR || process.env.VFKB_HOME;
+const engine = mode === 'mcp' ? 'vfkb-mcp.mjs' : 'vfkb.mjs';
+const enginePath = home ? join(home, engine) : '';
+
+const FIX =
+  'vfkb is INACTIVE: VFKB_BUNDLE_DIR is not set (or its bundles are missing). ' +
+  'Fix: build the bundles in the vfkb repo (\\\`npm run build:bundles\\\`) and ' +
+  '\\\`export VFKB_BUNDLE_DIR=/path/to/vfkb/dist/bundles\\\` (see docs/CONSUMER-ONBOARDING.md). ' +
+  'Then run \\\`vfkb doctor\\\` to verify.';
+
+if (!home || !existsSync(enginePath)) {
+  // SessionStart: inform the user via the injection channel (a valid hook payload).
+  if (mode === 'cli' && passthrough[1] === 'session-start') {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: '⚠️ ' + FIX },
+    }));
+    process.exit(0);
+  }
+  // PreToolUse / Stop / MCP: note it, but NEVER block writes or crash the turn.
+  process.stderr.write('vfkb-bootstrap: ' + FIX + '\\n');
+  process.exit(0);
+}
+
+// Resolved — run the real engine transparently (stdio passed through).
+const r = spawnSync('node', [enginePath, ...passthrough], { stdio: 'inherit' });
+process.exit(r.status == null ? 0 : r.status);
+`;
+function settingsHooks(project) {
+    return {
+        SessionStart: [{ hooks: [{ type: 'command', command: hookCommand(project, 'session-start') }] }],
+        PreToolUse: [
+            { matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: hookCommand(project, 'pre-tool-use') }] },
+        ],
+        Stop: [{ hooks: [{ type: 'command', command: hookCommand(project, 'stop') }] }],
+        SessionEnd: [{ hooks: [{ type: 'command', command: hookCommand(project, 'session-end') }] }],
+    };
+}
+function agentsSnippet(project) {
+    return `${AGENTS_MARKER}
+## How we track work HERE — vfkb
+
+This repo uses **vfkb** as its knowledge substrate (project \`${project}\`). Knowledge is recorded
+**deliberately, through the engine** — never by hand-editing \`.vfkb/\` (a PreToolUse hook gates that).
+
+- **Session start** injects the resume digest + knowledge bundle automatically (SessionStart hook).
+- **Record knowledge** with the \`mcp__vfkb__kb_add\` tool (or \`node .vfkb/bin/bootstrap.mjs cli add …\`):
+  \`decision\`, \`fact\`, \`gotcha\`, \`pattern\`, \`link\` — put a decision's rationale in its text.
+  **Capture load-bearing decisions immediately — don't defer.**
+- Only \`.vfkb/entries.jsonl\`, \`.vfkb/manifest.json\`, and \`.vfkb/bin/\` are committed;
+  \`.vfkb/index-meta.json\`, \`.sessions/\`, \`.signals/\` are derived/gitignored.
+
+Two env vars: **\`VFKB_DATA_DIR\`** = this repo's brain (\`.vfkb\`, set by the wiring) · **\`VFKB_BUNDLE_DIR\`**
+= the shared vfkb engine bundles — set it once per machine, e.g. \`export VFKB_BUNDLE_DIR=/path/to/vfkb/dist/bundles\`.
+If it is unset, a session-start banner tells you; run \`vfkb doctor\` to check.
+`;
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeJson(path, value) {
+    writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}
+function eventHasVfkb(arr) {
+    return JSON.stringify(arr ?? '').includes(BOOTSTRAP_REL);
+}
+export function initProject(root, opts = {}) {
+    const project = opts.project || basename(root) || 'project';
+    const changes = [];
+    // 1. Empty brain — NEVER clobber an existing one.
+    const brainDir = join(root, '.vfkb');
+    const entries = join(brainDir, 'entries.jsonl');
+    if (!existsSync(entries)) {
+        mkdirSync(brainDir, { recursive: true });
+        writeFileSync(entries, '');
+        changes.push({ path: '.vfkb/entries.jsonl', action: 'created' });
+    }
+    else {
+        changes.push({ path: '.vfkb/entries.jsonl', action: 'skipped' });
+    }
+    // 1b. Brain↔engine version stamp (FR-4) — committed, engine-written.
+    changes.push({ path: '.vfkb/manifest.json', action: writeManifest(brainDir) });
+    // 1c. The committed bootstrap entry-point (ADR-0031) — write if absent or stale.
+    {
+        const binDir = join(brainDir, 'bin');
+        const path = join(binDir, 'bootstrap.mjs');
+        const existed = existsSync(path);
+        const same = existed && readFileSync(path, 'utf8') === BOOTSTRAP_SRC;
+        if (same) {
+            changes.push({ path: BOOTSTRAP_REL, action: 'skipped' });
+        }
+        else {
+            mkdirSync(binDir, { recursive: true });
+            writeFileSync(path, BOOTSTRAP_SRC);
+            changes.push({ path: BOOTSTRAP_REL, action: existed ? 'updated' : 'created' });
+        }
+    }
+    // 2. .mcp.json — register the vfkb MCP server (merge, keep other servers).
+    {
+        const path = join(root, '.mcp.json');
+        const existed = existsSync(path);
+        const cfg = readJson(path) ?? {};
+        cfg.mcpServers = cfg.mcpServers ?? {};
+        const desired = mcpConfig(project);
+        const same = JSON.stringify(cfg.mcpServers.vfkb) === JSON.stringify(desired);
+        if (same) {
+            changes.push({ path: '.mcp.json', action: 'skipped' });
+        }
+        else {
+            cfg.mcpServers.vfkb = desired;
+            writeJson(path, cfg);
+            changes.push({ path: '.mcp.json', action: existed ? 'updated' : 'created' });
+        }
+    }
+    // 3. .claude/settings.json — the four hooks (merge per-event; don't duplicate).
+    // Drop any pre-existing vfkb entry and re-append the current form: this UPGRADES an
+    // older CWD-relative hook to the anchored one (issue #22) while keeping user hooks.
+    {
+        const dir = join(root, '.claude');
+        const path = join(dir, 'settings.json');
+        const existed = existsSync(path);
+        const cfg = readJson(path) ?? {};
+        cfg.hooks = cfg.hooks ?? {};
+        const want = settingsHooks(project);
+        let touched = false;
+        for (const event of Object.keys(want)) {
+            const raw = cfg.hooks[event];
+            const cur = Array.isArray(raw) ? raw : raw ? [raw] : [];
+            const others = cur.filter((e) => !eventHasVfkb(e)); // keep non-vfkb (user) hooks
+            const desired = [...others, ...want[event]];
+            if (JSON.stringify(cur) === JSON.stringify(desired))
+                continue; // already current form
+            cfg.hooks[event] = desired;
+            touched = true;
+        }
+        if (touched) {
+            mkdirSync(dir, { recursive: true });
+            writeJson(path, cfg);
+            changes.push({ path: '.claude/settings.json', action: existed ? 'updated' : 'created' });
+        }
+        else {
+            changes.push({ path: '.claude/settings.json', action: 'skipped' });
+        }
+    }
+    // 4. .gitignore — the derived/operational stanza (append once).
+    {
+        const path = join(root, '.gitignore');
+        const lines = ['.vfkb/index-meta.json', '.vfkb/.sessions/', '.vfkb/.signals/'];
+        const existed = existsSync(path);
+        const cur = existed ? readFileSync(path, 'utf8') : '';
+        const missing = lines.filter((l) => !cur.split(/\r?\n/).includes(l));
+        if (missing.length === 0) {
+            changes.push({ path: '.gitignore', action: 'skipped' });
+        }
+        else {
+            const prefix = cur && !cur.endsWith('\n') ? '\n' : '';
+            const block = `${prefix}${cur ? '\n' : ''}# vfkb — derived/operational (only .vfkb/entries.jsonl is committed)\n${missing.join('\n')}\n`;
+            writeFileSync(path, cur + block);
+            changes.push({ path: '.gitignore', action: existed ? 'updated' : 'created' });
+        }
+    }
+    // 4b. .gitattributes — merge=union for the append-only brain (ADR-0041), so
+    // parallel branches that both appended entries union-merge instead of conflicting.
+    // Append once; never touches the consumer's other attributes. (GitHub's server-side
+    // merge ignores it — a local `git merge` remains the documented fallback, ADR-0041.)
+    {
+        const path = join(root, '.gitattributes');
+        const line = '.vfkb/entries.jsonl merge=union';
+        const existed = existsSync(path);
+        const cur = existed ? readFileSync(path, 'utf8') : '';
+        if (cur.split(/\r?\n/).includes(line)) {
+            changes.push({ path: '.gitattributes', action: 'skipped' });
+        }
+        else {
+            const prefix = cur && !cur.endsWith('\n') ? '\n' : '';
+            const block = `${prefix}${cur ? '\n' : ''}# vfkb — the append-only brain unions across branches (ADR-0041)\n${line}\n`;
+            writeFileSync(path, cur + block);
+            changes.push({ path: '.gitattributes', action: existed ? 'updated' : 'created' });
+        }
+    }
+    // 5. AGENTS.md — the parameterized "how we track work HERE" snippet (append once).
+    {
+        const path = join(root, 'AGENTS.md');
+        const existed = existsSync(path);
+        const cur = existed ? readFileSync(path, 'utf8') : '';
+        if (cur.includes(AGENTS_MARKER)) {
+            changes.push({ path: 'AGENTS.md', action: 'skipped' });
+        }
+        else {
+            const sep = cur && !cur.endsWith('\n') ? '\n\n' : cur ? '\n' : '';
+            writeFileSync(path, cur + sep + agentsSnippet(project));
+            changes.push({ path: 'AGENTS.md', action: existed ? 'updated' : 'created' });
+        }
+    }
+    return changes;
+}
+// The one step init cannot do for you (printed by the CLI).
+export function approvalNotice(project) {
+    return [
+        `vfkb wired for project "${project}".`,
+        '',
+        'Next (one-time, manual):',
+        '  1. Set $VFKB_BUNDLE_DIR once per machine to the vfkb bundles dir, e.g.:',
+        '       export VFKB_BUNDLE_DIR=/path/to/vfkb/dist/bundles   # (run `npm run build:bundles` in the vfkb repo)',
+        '  2. Start `claude` in this repo and APPROVE the project MCP server + hooks when prompted (once).',
+        '  3. Commit the wiring + the empty brain: git add .mcp.json .claude .gitignore .gitattributes .vfkb AGENTS.md',
+    ].join('\n');
+}

package/dist/init.test.js

@@ -0,0 +1,148 @@
+// FR-1 (ADR-0030) inner gate — `vfkb init` scaffolds a consumer repo correctly
+// and is IDEMPOTENT (re-running changes nothing, never clobbers a brain, never
+// duplicates the .gitignore stanza or the AGENTS.md snippet). The agent-driven
+// consumer-onboarding L4 scenario is the capability-level DoD (ADR-0029).
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { initProject } from './init.js';
+let root;
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), 'vfkb-init-'));
+});
+const read = (p) => readFileSync(join(root, p), 'utf8');
+describe('vfkb init (FR-1)', () => {
+    it('scaffolds the portable wiring, gitignore stanza, empty brain, and snippet', () => {
+        const changes = initProject(root, { project: 'demo' });
+        const actions = Object.fromEntries(changes.map((c) => [c.path, c.action]));
+        expect(actions['.vfkb/entries.jsonl']).toBe('created');
+        expect(actions['.vfkb/manifest.json']).toBe('created');
+        expect(actions['.mcp.json']).toBe('created');
+        expect(actions['.claude/settings.json']).toBe('created');
+        expect(actions['.vfkb/bin/bootstrap.mjs']).toBe('created');
+        expect(actions['.gitignore']).toBe('created');
+        expect(actions['AGENTS.md']).toBe('created');
+        // .mcp.json — via the committed relative bootstrap (ADR-0031), project from the arg.
+        const mcp = JSON.parse(read('.mcp.json'));
+        expect(mcp.mcpServers.vfkb.args).toEqual(['.vfkb/bin/bootstrap.mjs', 'mcp']);
+        expect(mcp.mcpServers.vfkb.env).toEqual({ VFKB_DATA_DIR: '.vfkb', VFKB_PROJECT: 'demo' });
+        // .claude/settings.json — the three hooks, via the bootstrap, no relative dist/ path.
+        const settings = JSON.parse(read('.claude/settings.json'));
+        expect(Object.keys(settings.hooks).sort()).toEqual([
+            'PreToolUse',
+            'SessionEnd',
+            'SessionStart',
+            'Stop',
+        ]);
+        expect(settings.hooks.SessionEnd[0].hooks[0].command).toContain('cli hook session-end');
+        const blob = JSON.stringify(settings);
+        expect(blob).toContain('.vfkb/bin/bootstrap.mjs cli hook');
+        expect(blob).toContain('VFKB_PROJECT=demo');
+        expect(blob).not.toContain('dist/cli.js');
+        expect(settings.hooks.PreToolUse[0].matcher).toBe('Write|Edit|MultiEdit');
+        // issue #22 / ADR-0035 — hooks anchor to $CLAUDE_PROJECT_DIR (CWD-independent),
+        // NOT a bare CWD-relative path that breaks when the session cd's out of the root.
+        expect(blob).toContain('${CLAUDE_PROJECT_DIR:-.}/.vfkb/bin/bootstrap.mjs');
+        expect(blob).toContain('VFKB_DATA_DIR=${CLAUDE_PROJECT_DIR:-.}/.vfkb');
+        expect(blob).not.toContain('node .vfkb/bin/bootstrap.mjs'); // the old bare-relative form
+        // the bootstrap is a committed, self-contained guard.
+        const boot = read('.vfkb/bin/bootstrap.mjs');
+        expect(boot).toContain('VFKB_BUNDLE_DIR');
+        expect(boot).not.toContain("from './"); // no engine import — must run standalone
+        // version stamp (FR-4).
+        expect(JSON.parse(read('.vfkb/manifest.json')).schema_version).toBe(1);
+        // empty brain + gitignore stanza + snippet marker.
+        expect(read('.vfkb/entries.jsonl')).toBe('');
+        expect(read('.gitignore')).toContain('.vfkb/.sessions/');
+        expect(read('AGENTS.md')).toContain('How we track work HERE');
+    });
+    it('defaults the project name to the directory basename', () => {
+        initProject(root, {});
+        const mcp = JSON.parse(read('.mcp.json'));
+        expect(mcp.mcpServers.vfkb.env.VFKB_PROJECT).toBe(root.split('/').pop());
+    });
+    it('is idempotent — a second run changes nothing and does not duplicate', () => {
+        initProject(root, { project: 'demo' });
+        const second = initProject(root, { project: 'demo' });
+        expect(second.every((c) => c.action === 'skipped')).toBe(true);
+        // gitignore stanza appears exactly once.
+        const gi = read('.gitignore');
+        expect(gi.split('.vfkb/.sessions/').length - 1).toBe(1);
+        // snippet marker appears exactly once.
+        const agents = read('AGENTS.md');
+        expect(agents.split('vfkb:how-we-track-work').length - 1).toBe(1);
+    });
+    it('emits the ADR-0041 merge=union attribute for the brain, append-once (V2-3 consumer follow-up)', () => {
+        const changes = initProject(root, { project: 'demo' });
+        expect(changes.find((c) => c.path === '.gitattributes')?.action).toBe('created');
+        expect(read('.gitattributes')).toContain('.vfkb/entries.jsonl merge=union');
+        // appends to an existing .gitattributes without touching its content…
+        writeFileSync(join(root, '.gitattributes'), '*.png binary\n');
+        const again = initProject(root, { project: 'demo' });
+        expect(again.find((c) => c.path === '.gitattributes')?.action).toBe('updated');
+        const ga = read('.gitattributes');
+        expect(ga).toContain('*.png binary');
+        expect(ga.split('.vfkb/entries.jsonl merge=union').length - 1).toBe(1);
+        // …and is idempotent once present.
+        const third = initProject(root, { project: 'demo' });
+        expect(third.find((c) => c.path === '.gitattributes')?.action).toBe('skipped');
+    });
+    it('never clobbers an existing brain', () => {
+        initProject(root, { project: 'demo' });
+        writeFileSync(join(root, '.vfkb', 'entries.jsonl'), '{"id":"keep"}\n');
+        const again = initProject(root, { project: 'demo' });
+        expect(again.find((c) => c.path === '.vfkb/entries.jsonl')?.action).toBe('skipped');
+        expect(read('.vfkb/entries.jsonl')).toContain('keep');
+    });
+    it('merges into an existing .mcp.json without dropping other servers', () => {
+        writeFileSync(join(root, '.mcp.json'), JSON.stringify({ mcpServers: { other: { command: 'x' } } }));
+        initProject(root, { project: 'demo' });
+        const mcp = JSON.parse(read('.mcp.json'));
+        expect(mcp.mcpServers.other).toEqual({ command: 'x' });
+        expect(mcp.mcpServers.vfkb).toBeDefined();
+    });
+    it('upgrades an existing CWD-relative vfkb hook to the anchored form, keeping user hooks (issue #22)', () => {
+        const dir = join(root, '.claude');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'settings.json'), JSON.stringify({
+            hooks: {
+                Stop: [
+                    { hooks: [{ type: 'command', command: 'echo user-hook' }] }, // a user's own hook — must survive
+                    { hooks: [{ type: 'command', command: 'VFKB_DATA_DIR=.vfkb VFKB_PROJECT=demo node .vfkb/bin/bootstrap.mjs cli hook stop' }] },
+                ],
+            },
+        }));
+        const changes = initProject(root, { project: 'demo' });
+        expect(changes.find((c) => c.path === '.claude/settings.json')?.action).toBe('updated');
+        const settings = JSON.parse(read('.claude/settings.json'));
+        const cmds = settings.hooks.Stop.map((e) => e.hooks[0].command);
+        expect(cmds).toContain('echo user-hook'); // user hook preserved
+        expect(cmds.some((c) => c.includes('${CLAUDE_PROJECT_DIR:-.}/.vfkb/bin/bootstrap.mjs cli hook stop'))).toBe(true);
+        expect(cmds).not.toContain('VFKB_DATA_DIR=.vfkb VFKB_PROJECT=demo node .vfkb/bin/bootstrap.mjs cli hook stop'); // old form gone
+        // and re-running is now idempotent on the upgraded form
+        const again = initProject(root, { project: 'demo' });
+        expect(again.find((c) => c.path === '.claude/settings.json')?.action).toBe('skipped');
+    });
+    it('the emitted hook resolves from a foreign CWD; the old bare-relative form does not (issue #22 DoD)', () => {
+        initProject(root, { project: 'demo' });
+        const settings = JSON.parse(read('.claude/settings.json'));
+        const anchored = settings.hooks.SessionStart[0].hooks[0].command;
+        const foreign = mkdtempSync(join(tmpdir(), 'vfkb-cwd-')); // a dir that is NOT the repo root
+        const env = { ...process.env, CLAUDE_PROJECT_DIR: root };
+        delete env.VFKB_BUNDLE_DIR; // force the bootstrap's graceful INACTIVE path (no engine needed)
+        delete env.VFKB_HOME;
+        // Anchored form: the bootstrap is FOUND despite the foreign CWD -> emits the
+        // SessionStart INACTIVE payload and exits 0.
+        const ok = spawnSync('sh', ['-c', anchored], { cwd: foreign, env, encoding: 'utf8' });
+        expect(ok.status).toBe(0);
+        expect(ok.stdout).toContain('INACTIVE');
+        // Contrast (proves the bug + that this gate CAN fail): the old bare-relative form
+        // from the same foreign CWD -> MODULE_NOT_FOUND, non-zero exit.
+        const bare = 'VFKB_DATA_DIR=.vfkb VFKB_PROJECT=demo node .vfkb/bin/bootstrap.mjs cli hook session-start';
+        const bad = spawnSync('sh', ['-c', bare], { cwd: foreign, env, encoding: 'utf8' });
+        expect(bad.status).not.toBe(0);
+        expect(bad.stderr).toMatch(/Cannot find module|MODULE_NOT_FOUND/);
+    });
+});