claude-faf-mcp 5.7.2 → 5.9.0

package/CHANGELOG.md

@@ -1,5 +1,5 @@
-<!-- faf: claude-faf-mcp | TypeScript | mcp-server | FAF MCP server for Claude Desktop — persistent project context, 32 tools -->
-<!-- faf: doc=changelog | latest=v5.7.2 | canonical=project.faf | family=FAF -->
+<!-- faf: claude-faf-mcp | TypeScript | mcp-server | FAF MCP server for Claude Desktop — persistent project context, 35 tools -->
+<!-- faf: doc=changelog | latest=v5.9.0 | canonical=project.faf | family=FAF -->
 
 # Changelog
 
@@ -11,11 +11,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-**Interop now enhances your files.** The same solid, structured `.faf` data is prefixed to the top of your context files for rapid AI consumption upfront — and your Markdown stays in the instruction lane.
+## [5.9.0] - 2026-06-12 — The Sourced Edition
+
+**Every answer comes from one source.** claude-faf-mcp now composes faf-cli's single-source engines — the 6Ws interview and Turbo-Cat detection — instead of carrying its own copies that drift. Fills come from real evidence or stay honestly empty; nothing is guessed. FAF don't lie, by construction.
 
 ### Changed
 
-- **Non-destructive interop.** `faf_agents`, `faf_gemini`, `faf_cursor`, and `faf_sync` now inject a structured `.faf` block at the top of AGENTS.md, GEMINI.md, .cursorrules, and CLAUDE.md and preserve everything you've written below. Re-runs update the block in place (idempotent); existing faf-generated files upgrade cleanly in one pass.
+- **`faf_go` composes the canonical interview.** The guided interview is now sourced from faf-cli's public `INTERVIEW` / `interviewForMissing` (shipped in faf-cli 6.9.0) — the hand-maintained local question registry is deleted, so question text and options can never drift from the kernel. Only missing AND active slots are asked (`slotignored` is skipped), so the full canonical set never means more questions on screen.
+- **Turbo-Cat detection composes faf-cli.** `faf_formats` and `faf_auto` now use faf-cli's single-source Turbo-Cat (`turboCatScan` / `turboCatSlots`, ~200 formats; faf-cli 6.10.1) — the local 25-entry copy (`discoverFormatsInternal`) is deleted. Detection that's correct and can't drift: a server with an `mcpb` `manifest.json` is detected as what it is, not mis-flagged as a Chrome extension.
+- **The `/faf` prompt drives to a *verified* 100%, and maintains it.** It now runs `faf_trust` to attest the score with the `✪` parity receipt, offers `faf_setup` to keep 100% fresh every session, and reports the quiet `✪` seal. Its lead rule: fill only from sourced evidence — never guess; hand the human, plainly, only what only they can answer.
+
+### Removed
+
+- **The v5 guessing extractor.** The legacy human-context extractor inferred slots from the project name / tech stack (writing `INFERRED`/`DEFAULT` placeholders into empty slots). Removed; replaced by a sourced-or-empty README extractor, verified by a test that proves it cannot fabricate. No-guess is now structural, not accidental.
+
+35 tools live. 567 tests, 0 fail. Composes faf-cli `^6.10.1`.
+
+## [5.8.0] - 2026-06-11 — The Trust Edition
+
+**Claude Code-native context that just works.** Five pillars, one theme: the experience an agent can parse and a human can read (quiet + typed), the proof a third party can verify (parity hash + ✪ receipt), and the integration that earns "native" (the session hook). Plus enhanced interop — your files get enhanced, never replaced.
+
+### Added
+
+- **Native SessionStart hook (`--session-refresh`).** One cheap, deterministic action at every Claude Code session start: refresh CLAUDE.md's faf-managed block from project.faf, then hand over the baton — a one-line heartbeat carrying the quiet-ladder seal and score (`faf: context ✪ 100% — fresh`). Freshness-gated (no write, no mtime churn when current), never throws, always exit 0; non-faf directories stay fully silent.
+- **`faf_setup` (tool #35).** The explicit hook installer. Preview by default — shows the exact settings JSON and path, writes nothing; `confirm: true` merges non-destructively into the project's `.claude/settings.json` (every existing key and hook preserved, idempotent); `remove: true` takes out exactly the faf hook. Malformed settings are surfaced, never overwritten.
+- **Determinism parity hash.** `faf_score` (and `faf_trust`) now carry an engine-agnostic `parity` receipt: a SHA-256 over the canonical score projection, bound to the input bytes — any conformant engine (faf-cli, the Rust kernel, this server) reproduces it, and a third party can verify `sha256(projection) === parityHash`. Falsifiable, not self-asserted.
+- **The ✪ trust receipt.** `faf_trust` emits a render-identical, no-emoji, self-verifying score+parity artifact (text + structuredContent) — a receipt that means the same thing in a terminal, a CI log, and a report.
+- **Typed structured output across the data tools.** `faf_context`, `faf_list`, `faf_formats`, `faf_dna`, `faf_doctor`, `faf_check` join `faf_score`/`faf_status` with `outputSchema` + `structuredContent` on every return path (text retained for back-compat).
+
+### Changed
+
+- **Quiet output, everywhere, always.** Tool results and descriptions carry no emoji — plain, parseable, scriptable. Tier glyphs use the quiet ladder `♡ ○ ● ◇ ◆ ★ ✪` (geometric symbols, render-identical); ✪ is the Trophy seal. One predictable output format, no toggle.
+- **The generated CLAUDE.md block is quiet too.** The native faf→CLAUDE.md renderer now emits the canonical format (`What This Is / Stack / Context`) — no emoji, no brand voice — matching faf-cli's export, since the session hook makes that block part of every session's context. `slotignored` slots stay invisible.
+
+### Fixed
+
+- **Enhanced interop — your files are enhanced, never replaced.** The interop tools (`faf_agents`, `faf_gemini`, `faf_cursor`, `faf_sync`) overwrote AGENTS.md, GEMINI.md, .cursorrules, and CLAUDE.md wholesale — anything you'd written was lost. Now every write goes through a non-destructive injector: a structured `.faf` block owns the top of the file, everything you've written below is preserved, re-runs update the block in place (idempotent), and existing faf-generated files upgrade cleanly in one pass. A build-failing write-guard makes the old behavior impossible to reintroduce.
+- **`faf_trust` works again.** It shelled out to a `faf trust` subcommand that no longer exists in faf-cli (every call errored); now a self-contained local attestation.
+
+35 tools live. 547 tests, 0 fail.
 
 ## [5.7.2] - 2026-06-11 — The Canonical Edition
 

package/CLAUDE.md

@@ -1,3 +1,4 @@
+<!-- faf:start -->
 <!-- faf: claude-faf-mcp | TypeScript | mcp | Persistent project context for Claude — define once, never re-explain -->
 <!-- faf: claim=project.faf | family=FAF -->
 
@@ -28,4 +29,5 @@ Persistent project context for Claude — define once, never re-explain
 
 ---
 
-*STATUS: BI-SYNC ACTIVE — 2026-06-10T01:27:09.822Z*
+*STATUS: BI-SYNC ACTIVE — 2026-06-12T16:18:54.214Z*
+<!-- faf:end -->

package/README.md

@@ -1,7 +1,7 @@
-<!-- faf: claude-faf-mcp | TypeScript | mcp-server | FAF MCP server for Claude — persistent project context, 32 tools -->
+<!-- faf: claude-faf-mcp | TypeScript | mcp-server | FAF MCP server for Claude — persistent project context, 35 tools -->
 <!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->
 
-# claude-faf-mcp — The Canonical Edition
+# claude-faf-mcp — The Sourced Edition
 
 [![npm version](https://img.shields.io/npm/v/claude-faf-mcp?color=00CCFF)](https://www.npmjs.com/package/claude-faf-mcp)
 [![FAF Trophy 100%](https://img.shields.io/badge/FAF-%F0%9F%8F%86%20100%25-000000?labelColor=FF6B35)](https://faf.one)
@@ -26,9 +26,11 @@
 
 > ⚡ **New: `/faf` prompt** — type `/faf` in Claude Desktop. It checks your project, scores it, drives it to 100%, and syncs. Relentlessly. One command.
 
-> 🏆 **v5.7.2 — The Canonical Edition.** Security patch — caller-supplied `path` arguments are now confined: reads are restricted to `.faf` / `.fafm` context files and file ops to the project root (override with `FAF_ALLOWED_ROOTS`), closing an arbitrary local file read. Built on the Canonical foundation: typed structured output (`structuredContent` + output schemas), edge-direct remote, 32 must-have tools.
+> 🏆 **v5.9.0 — The Sourced Edition.** Every answer comes from one source. `faf_go` and Turbo-Cat detection now **compose faf-cli's single-source engines** instead of carrying their own copies — fills come from real evidence or stay honestly empty, nothing guessed. The legacy guessing extractor is gone; the `/faf` prompt drives to a *verified* 100% (`faf_trust` + `✪` parity receipt) and keeps it fresh. FAF don't lie, by construction.
 
-32 MCP tools. IANA-registered formats (`application/vnd.faf+yaml` · `application/vnd.fafm+yaml`). 2,538 test executions per push.
+> 🏆 **v5.8.0 — The Trust Edition.** Claude Code-native context that just works. A native SessionStart hook opens every session with fresh context and a one-line `✪` heartbeat (`faf: context ✪ 100% — fresh`); tool output is quiet (no emoji, parseable) and typed (`structuredContent` everywhere); every score carries a deterministic parity hash any engine reproduces, sealed in a self-verifying `✪` receipt. Installed explicitly via `faf_setup` — preview first, your settings preserved. Built on the Canonical foundation: path-confined file access, edge-direct remote, 35 tools.
+
+35 MCP tools. IANA-registered formats (`application/vnd.faf+yaml` · `application/vnd.fafm+yaml`). 1,701 test executions per push.
 
 ---
 
@@ -82,9 +84,9 @@ Same `.faf`, every surface — Claude, Gemini, Grok, Cursor. **[faf-cli on npm
 
 **Click** — one-click `.mcpb`
 
-[**⬇ Download `claude-faf-mcp-5.7.2.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/latest/download/claude-faf-mcp-5.7.2.mcpb)
+[**⬇ Download `claude-faf-mcp-5.9.0.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/latest/download/claude-faf-mcp-5.9.0.mcpb)
 
-Double-click. **No terminal. No JSON config. 32 tools live in 10 seconds.**
+Double-click. **No terminal. No JSON config. 35 tools live in 10 seconds.**
 
 **Copy** — paste-prompt to Claude
 
@@ -246,7 +248,7 @@ Same `project.faf`. Same scoring. Same result. Different execution layer.
 
 ## Quality
 
-423 tests · 13 suites · 6 platforms (ubuntu/macos/windows × Node 18/20)
+567 tests · 26 suites · 3 platforms (bun on ubuntu/macos/windows)
 
 **[CI Dashboard →](https://github.com/Wolfe-Jam/claude-faf-mcp/actions/workflows/ci.yml)**
 

package/dist/src/faf-core/commands/bi-sync.d.ts

@@ -22,7 +22,13 @@ export interface BiSyncResult {
     message: string;
 }
 /**
- * 🔄 Convert project.faf YAML content to CLAUDE.md Markdown format
+ * Convert project.faf YAML content to CLAUDE.md Markdown — QUIET format
+ * (Trust Edition P1 applied to the generated artifact, not just tool output).
+ *
+ * The block this renders is injected into the file Claude READS every session,
+ * so it is plain, parseable context: no emoji, no brand voice (that lives in
+ * marketing), nothing the consuming model has to skip over. Mirrors the
+ * canonical faf-cli CLAUDE.md export shape: What This Is / Stack / Context.
  */
 export declare function fafToClaudeMd(fafContent: string): string;
 /**

package/dist/src/faf-core/commands/bi-sync.js

@@ -48,56 +48,63 @@ const agents_js_1 = require("./agents.js");
 const inject_1 = require("../inject");
 const cursor_js_1 = require("./cursor.js");
 const gemini_js_1 = require("./gemini.js");
+/** A slot value that carries real content (not empty, not slotignored). */
+function filled(v) {
+    return typeof v === 'string' && v.trim() !== '' && v.trim() !== 'slotignored';
+}
+/** snake_case slot key → Title Case label (main_language → Main Language). */
+function labelOf(key) {
+    return key.split('_').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
 /**
- * 🔄 Convert project.faf YAML content to CLAUDE.md Markdown format
+ * Convert project.faf YAML content to CLAUDE.md Markdown — QUIET format
+ * (Trust Edition P1 applied to the generated artifact, not just tool output).
+ *
+ * The block this renders is injected into the file Claude READS every session,
+ * so it is plain, parseable context: no emoji, no brand voice (that lives in
+ * marketing), nothing the consuming model has to skip over. Mirrors the
+ * canonical faf-cli CLAUDE.md export shape: What This Is / Stack / Context.
  */
 function fafToClaudeMd(fafContent) {
     try {
         const fafData = (0, yaml_1.parse)(fafContent);
-        let claudeMd = `# 🏎️ CLAUDE.md - ${fafData.project?.name || 'Project'} Persistent Context & Intelligence\n\n`;
-        // Project State
-        if (fafData.project) {
-            claudeMd += `## PROJECT STATE: ${fafData.context_quality?.overall_assessment || 'ACTIVE'} 🚀\n`;
-            if (fafData.project.goal) {
-                claudeMd += `**Current Position:** ${fafData.project.goal}\n`;
-            }
-            claudeMd += `**Tyre Compound:** ULTRASOFT C5 (Maximum Performance)\n\n`;
-            claudeMd += `---\n\n`;
+        const name = fafData.project?.name || 'Project';
+        const lines = [`# CLAUDE.md — ${name}`, ''];
+        // What This Is — the one-line identity.
+        const what = fafData.project?.goal || fafData.instant_context?.what_building;
+        if (filled(what)) {
+            lines.push('## What This Is', '', what, '');
         }
-        // Core Context
-        claudeMd += `## 🎨 CORE CONTEXT\n\n`;
-        if (fafData.project) {
-            claudeMd += `### Project Identity\n`;
-            claudeMd += `- **Name:** ${fafData.project.name || 'Unknown'}\n`;
-            if (fafData.instant_context?.tech_stack) {
-                claudeMd += `- **Stack:** ${fafData.instant_context.tech_stack}\n`;
-            }
-            claudeMd += `- **Quality:** F1-INSPIRED (Championship Performance)\n\n`;
+        // Stack — every filled slot, slotignored stays invisible (the What-Not).
+        const stackEntries = [];
+        if (filled(fafData.project?.main_language)) {
+            stackEntries.push(`- **Language:** ${fafData.project.main_language}`);
         }
-        // Technical Context
-        if (fafData.instant_context) {
-            claudeMd += `### Technical Architecture\n`;
-            if (fafData.instant_context.what_building) {
-                claudeMd += `- **What Building:** ${fafData.instant_context.what_building}\n`;
-            }
-            if (fafData.instant_context.main_language) {
-                claudeMd += `- **Main Language:** ${fafData.instant_context.main_language}\n`;
+        else if (filled(fafData.instant_context?.main_language)) {
+            stackEntries.push(`- **Language:** ${fafData.instant_context.main_language}`);
+        }
+        if (fafData.stack && typeof fafData.stack === 'object') {
+            for (const [key, value] of Object.entries(fafData.stack)) {
+                if (filled(value))
+                    stackEntries.push(`- **${labelOf(key)}:** ${value}`);
             }
-            claudeMd += `\n`;
         }
-        // Context Quality
-        if (fafData.context_quality) {
-            claudeMd += `### 📊 Context Quality Status\n`;
-            claudeMd += `- **Overall Assessment:** ${fafData.context_quality.overall_assessment || 'Good'}\n`;
-            claudeMd += `- **Last Updated:** ${new Date().toISOString().split('T')[0]}\n\n`;
+        if (stackEntries.length === 0 && filled(fafData.instant_context?.tech_stack)) {
+            stackEntries.push(`- **Stack:** ${fafData.instant_context.tech_stack}`);
+        }
+        if (stackEntries.length > 0) {
+            lines.push('## Stack', '', ...stackEntries, '');
+        }
+        // Context — the 6Ws, exactly as authored.
+        const sixWs = ['who', 'what', 'why', 'where', 'when', 'how'];
+        const contextEntries = sixWs
+            .filter((w) => filled(fafData.human_context?.[w]))
+            .map((w) => `- **${labelOf(w)}:** ${fafData.human_context[w]}`);
+        if (contextEntries.length > 0) {
+            lines.push('## Context', '', ...contextEntries, '');
         }
-        // Championship Footer
-        claudeMd += `---\n\n`;
-        claudeMd += `**STATUS: BI-SYNC ACTIVE 🔗 - Synchronized with .faf context!**\n\n`;
-        claudeMd += `*Last Sync: ${new Date().toISOString()}*\n`;
-        claudeMd += `*Sync Engine: F1-Inspired Software Engineering*\n`;
-        claudeMd += `*🏎️⚡️_championship_sync*\n`;
-        return claudeMd;
+        lines.push('---', '', `*STATUS: BI-SYNC ACTIVE — ${new Date().toISOString()}*`, '');
+        return lines.join('\n');
     }
     catch (error) {
         throw new Error(`Failed to convert .faf to CLAUDE.md: ${error instanceof Error ? error.message : String(error)}`);

package/dist/src/faf-core/commands/session-refresh.d.ts

@@ -0,0 +1,13 @@
+export type SessionRefreshAction = 'fresh' | 'refreshed' | 'created' | 'no-faf' | 'error';
+export interface SessionRefreshResult {
+    action: SessionRefreshAction;
+    /** The one-line heartbeat for SessionStart stdout (joins session context) — '' only for no-faf. */
+    message: string;
+}
+/**
+ * Refresh CLAUDE.md from project.faf in `projectDir` (defaults to cwd — Claude
+ * Code runs hooks with cwd at the project root). Never throws: a hook must not
+ * break a session. No deep search — the hook is fast and predictable or it is
+ * nothing.
+ */
+export declare function sessionRefresh(projectDir?: string): Promise<SessionRefreshResult>;

package/dist/src/faf-core/commands/session-refresh.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionRefresh = sessionRefresh;
+/**
+ * Session refresh — Trust Edition Pillar 5 (the hook action).
+ *
+ * What the Claude Code SessionStart hook runs: ONE cheap, deterministic action —
+ * refresh CLAUDE.md's faf-managed block from project.faf, non-destructively —
+ * then hand over the baton: a ONE-LINE heartbeat carrying the ✪-ladder seal and
+ * score. The line is a relay — it proves the native integration is alive (a
+ * silent hook is indistinguishable from a broken one) and it grounds the model
+ * ("a current .faf exists, score N%, don't re-derive the project").
+ *
+ * Freshness gate: if CLAUDE.md already carries the faf markers and is at least
+ * as new as project.faf, nothing is WRITTEN — no write, no mtime churn — but
+ * the heartbeat still speaks. Only non-faf directories stay fully silent: the
+ * hook never talks where it has no business.
+ */
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
+const inject_1 = require("../inject");
+const bi_sync_1 = require("./bi-sync");
+const receipt_1 = require("../../trust/receipt");
+/** Score the .faf via the truthful single-source kernel; '' when unscorable (heartbeat survives). */
+async function scoreLine(fafContent) {
+    try {
+        const { scoreFafYaml } = await import('../../utils/faf-cli-bridge.js').then((m) => m.fafCli);
+        const result = scoreFafYaml(fafContent);
+        const score = Math.round(result.score);
+        return `${(0, receipt_1.sealForScore)(score)} ${score}%`;
+    }
+    catch {
+        return ''; // no kernel, no score — the heartbeat still beats
+    }
+}
+/**
+ * Refresh CLAUDE.md from project.faf in `projectDir` (defaults to cwd — Claude
+ * Code runs hooks with cwd at the project root). Never throws: a hook must not
+ * break a session. No deep search — the hook is fast and predictable or it is
+ * nothing.
+ */
+async function sessionRefresh(projectDir = process.cwd()) {
+    try {
+        const fafPath = path.join(projectDir, 'project.faf');
+        let fafStat;
+        try {
+            fafStat = await fs_1.promises.stat(fafPath);
+        }
+        catch {
+            return { action: 'no-faf', message: '' }; // not a .faf project — silently not our session
+        }
+        const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+        let claudeStat = null;
+        let claudeContent = null;
+        try {
+            claudeStat = await fs_1.promises.stat(claudeMdPath);
+            claudeContent = await fs_1.promises.readFile(claudeMdPath, 'utf-8');
+        }
+        catch {
+            /* CLAUDE.md does not exist yet */
+        }
+        const fafContent = await fs_1.promises.readFile(fafPath, 'utf-8');
+        const seal = await scoreLine(fafContent);
+        // Freshness gate: markers present + CLAUDE.md at least as new as project.faf
+        // → no WRITE (no mtime churn), but the heartbeat still hands over the baton.
+        if (claudeStat && claudeContent !== null && claudeContent.includes(inject_1.FAF_START) && claudeStat.mtimeMs >= fafStat.mtimeMs) {
+            return { action: 'fresh', message: `faf: context ${seal ? `${seal} — ` : ''}fresh`.replace('  ', ' ') };
+        }
+        const block = (0, bi_sync_1.fafToClaudeMd)(fafContent);
+        await (0, inject_1.injectFafBlock)(claudeMdPath, block);
+        return claudeStat === null
+            ? { action: 'created', message: `faf: CLAUDE.md created${seal ? ` — ${seal}` : ''}` }
+            : { action: 'refreshed', message: `faf: context refreshed${seal ? ` — ${seal}` : ''}` };
+    }
+    catch (error) {
+        // Never break a session start. Quiet diagnostic on stderr is the caller's call.
+        return {
+            action: 'error',
+            message: `faf: session refresh skipped (${error instanceof Error ? error.message : String(error)})`,
+        };
+    }
+}
+//# sourceMappingURL=session-refresh.js.map

package/dist/src/faf-core/commands/setup-hook.d.ts

@@ -0,0 +1,32 @@
+/** The fingerprint by which we recognise OUR hook (and only ours). */
+export declare const HOOK_FINGERPRINT = "claude-faf-mcp --session-refresh";
+/** The command the SessionStart hook runs. npx resolves local or global installs. */
+export declare const HOOK_COMMAND = "npx -y claude-faf-mcp --session-refresh";
+/** The exact entry merged into settings.hooks.SessionStart. */
+export declare function buildHookEntry(): {
+    hooks: Array<{
+        type: 'command';
+        command: string;
+    }>;
+};
+export interface SetupHookResult {
+    action: 'preview' | 'installed' | 'already-installed' | 'removed' | 'not-installed' | 'error';
+    settingsPath: string;
+    /** The full settings object as it would be / has been written (preview + writes). */
+    settings?: Record<string, unknown>;
+    message: string;
+}
+/** Pure merge: existing settings + our hook appended (no mutation of input). */
+export declare function mergeHookIntoSettings(existing: Record<string, unknown>): Record<string, unknown>;
+/** Pure removal: strips exactly OUR hook entries; prunes only what emptied. */
+export declare function removeHookFromSettings(existing: Record<string, unknown>): Record<string, unknown>;
+/**
+ * The faf_setup flow.
+ *  - no flags        → PREVIEW: show the exact JSON, write NOTHING
+ *  - confirm: true   → non-destructive merge into .claude/settings.json
+ *  - remove: true    → take out exactly our hook
+ */
+export declare function setupSessionHook(projectDir: string, opts?: {
+    confirm?: boolean;
+    remove?: boolean;
+}): Promise<SetupHookResult>;

package/dist/src/faf-core/commands/setup-hook.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOOK_COMMAND = exports.HOOK_FINGERPRINT = void 0;
+exports.buildHookEntry = buildHookEntry;
+exports.mergeHookIntoSettings = mergeHookIntoSettings;
+exports.removeHookFromSettings = removeHookFromSettings;
+exports.setupSessionHook = setupSessionHook;
+/**
+ * faf_setup — Trust Edition Pillar 5 (the explicit installer).
+ *
+ * Installs the SessionStart refresh hook into the PROJECT's
+ * `.claude/settings.json` — and only with the caller's explicit confirm.
+ * The tool SHOWS the exact JSON it will write before it writes anything;
+ * the merge is non-destructive ("enhance, never replace" applied to
+ * settings): every existing key and every existing hook is preserved,
+ * ours is appended once, and re-runs are idempotent. `remove` takes out
+ * exactly ours and nothing else.
+ *
+ * JSON has no comment markers, so injectFafBlock cannot own a block here —
+ * the structured merge below is the JSON equivalent: parse, preserve, append.
+ */
+const path = __importStar(require("path"));
+const fs_1 = require("fs");
+/** The fingerprint by which we recognise OUR hook (and only ours). */
+exports.HOOK_FINGERPRINT = 'claude-faf-mcp --session-refresh';
+/** The command the SessionStart hook runs. npx resolves local or global installs. */
+exports.HOOK_COMMAND = `npx -y ${exports.HOOK_FINGERPRINT}`;
+/** The exact entry merged into settings.hooks.SessionStart. */
+function buildHookEntry() {
+    return { hooks: [{ type: 'command', command: exports.HOOK_COMMAND }] };
+}
+function hasOurHook(settings) {
+    const sessionStart = settings?.hooks?.SessionStart;
+    if (!Array.isArray(sessionStart))
+        return false;
+    return sessionStart.some((m) => Array.isArray(m?.hooks) && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(exports.HOOK_FINGERPRINT)));
+}
+async function readSettings(settingsPath) {
+    try {
+        const raw = await fs_1.promises.readFile(settingsPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('settings.json is not a JSON object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return {};
+        throw error; // malformed JSON etc. — surface it, never overwrite what we can't parse
+    }
+}
+/** Pure merge: existing settings + our hook appended (no mutation of input). */
+function mergeHookIntoSettings(existing) {
+    const merged = { ...existing };
+    const hooks = { ...(existing.hooks ?? {}) };
+    const sessionStart = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
+    sessionStart.push(buildHookEntry());
+    hooks.SessionStart = sessionStart;
+    merged.hooks = hooks;
+    return merged;
+}
+/** Pure removal: strips exactly OUR hook entries; prunes only what emptied. */
+function removeHookFromSettings(existing) {
+    const merged = { ...existing };
+    const hooks = { ...(existing.hooks ?? {}) };
+    const sessionStart = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    const kept = sessionStart
+        .map((m) => {
+        if (!Array.isArray(m?.hooks))
+            return m;
+        const remaining = m.hooks.filter((h) => !(typeof h?.command === 'string' && h.command.includes(exports.HOOK_FINGERPRINT)));
+        return remaining.length === m.hooks.length ? m : { ...m, hooks: remaining };
+    })
+        .filter((m) => !Array.isArray(m?.hooks) || m.hooks.length > 0);
+    if (kept.length > 0)
+        hooks.SessionStart = kept;
+    else
+        delete hooks.SessionStart;
+    if (Object.keys(hooks).length > 0)
+        merged.hooks = hooks;
+    else
+        delete merged.hooks;
+    return merged;
+}
+/**
+ * The faf_setup flow.
+ *  - no flags        → PREVIEW: show the exact JSON, write NOTHING
+ *  - confirm: true   → non-destructive merge into .claude/settings.json
+ *  - remove: true    → take out exactly our hook
+ */
+async function setupSessionHook(projectDir, opts = {}) {
+    const settingsPath = path.join(projectDir, '.claude', 'settings.json');
+    try {
+        const existing = await readSettings(settingsPath);
+        const installed = hasOurHook(existing);
+        if (opts.remove) {
+            if (!installed) {
+                return { action: 'not-installed', settingsPath, message: 'No faf SessionStart hook found — nothing to remove.' };
+            }
+            const next = removeHookFromSettings(existing);
+            await fs_1.promises.writeFile(settingsPath, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+            return { action: 'removed', settingsPath, settings: next, message: 'faf SessionStart hook removed. Everything else in settings.json untouched.' };
+        }
+        if (installed) {
+            return { action: 'already-installed', settingsPath, settings: existing, message: 'faf SessionStart hook already installed — nothing to do (idempotent).' };
+        }
+        const next = mergeHookIntoSettings(existing);
+        if (!opts.confirm) {
+            return {
+                action: 'preview',
+                settingsPath,
+                settings: next,
+                message: `PREVIEW — nothing written. This is exactly what ${settingsPath} would become. ` +
+                    `Run faf_setup again with confirm: true to install, or copy the hooks block in by hand.`,
+            };
+        }
+        await fs_1.promises.mkdir(path.dirname(settingsPath), { recursive: true });
+        await fs_1.promises.writeFile(settingsPath, JSON.stringify(next, null, 2) + '\n', 'utf-8');
+        return {
+            action: 'installed',
+            settingsPath,
+            settings: next,
+            message: 'faf SessionStart hook installed. Every Claude Code session in this project now starts with fresh context.',
+        };
+    }
+    catch (error) {
+        return {
+            action: 'error',
+            settingsPath,
+            message: `faf_setup failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+//# sourceMappingURL=setup-hook.js.map

package/dist/src/faf-core/extract/sourced-readme-context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sourced README context — the honest human-context (6W) extractor.
+ *
+ * This REPLACES the retired v5 RelentlessContextExtractor, which inferred slots
+ * from the project name / tech stack (an `INFERRED`/`DEFAULT` tier) and so could
+ * write a guessed value into an empty slot. That violated the FAF doctrine:
+ * FAF don't lie. This extractor follows the same rule as Turbo-Cat (stack slots
+ * from real formats) and faf-cli's v6 `relentlessContext` (human slots, sourced):
+ *
+ *   Fill a slot ONLY from evidence present in the README. No inference, no
+ *   defaults, no placeholders. Every field starts null and is set only on a
+ *   real pattern match. No match → the slot stays empty, to be handed to the
+ *   human (e.g. via faf_go). An honest empty beats a guessed fill.
+ *
+ * Sourced-but-partial by design: the patterns are deliberately conservative.
+ * Missing a fillable slot (false negative) is acceptable; fabricating one
+ * (false positive) is not.
+ */
+export interface SixWs {
+    who: string | null;
+    what: string | null;
+    why: string | null;
+    where: string | null;
+    when: string | null;
+    how: string | null;
+}
+/**
+ * Extract the 6 human-context slots from README text. Sourced-or-empty: a slot
+ * is filled only from a pattern match in `content`, never inferred.
+ */
+export declare function extractSixWsFromReadme(content: string): SixWs;