@jhizzard/termdeck-stack 0.3.3 → 0.4.1

package/assets/hooks/README.md

@@ -0,0 +1,132 @@
+# TermDeck session-end memory hook
+
+The `@jhizzard/termdeck-stack` installer can drop `memory-session-end.js`
+into `~/.claude/hooks/` and wire it into `~/.claude/settings.json` under
+`hooks.Stop`. The installer prompts you before doing this; default is
+yes.
+
+## What the hook does
+
+On every Claude Code session close, Claude Code fires its `Stop` hook
+with a JSON payload on stdin:
+
+```json
+{ "transcript_path": "/path/to/session.jsonl", "cwd": "/path/where/you/were/working", "session_id": "..." }
+```
+
+The hook:
+
+1. Skips transcripts smaller than 5 KB (no signal in tiny sessions —
+   override via `TERMDECK_HOOK_MIN_BYTES`).
+2. Validates env vars (`SUPABASE_URL`, `SUPABASE_SERVICE_KEY`,
+   `OPENAI_API_KEY`); if any are missing, logs the missing list and
+   exits cleanly without blocking the session close.
+3. Detects the project from `cwd` against a built-in regex table; falls
+   back to `"global"` when nothing matches. **The default table is
+   intentionally empty** — see "Customizing the project map" below to
+   add your own entries.
+4. Builds a coarse session summary from the last ~30 messages of the
+   transcript (~7 KB cap to stay inside OpenAI's embedding-input
+   budget).
+5. Embeds the summary via OpenAI `text-embedding-3-small` (1,536-dim).
+6. POSTs **one row** to Supabase `/rest/v1/memory_items` with
+   `source_type='session_summary'`.
+7. Logs every step to `~/.claude/hooks/memory-hook.log`.
+
+The hook is **fail-soft**: any error (network, parse, env-var-missing,
+malformed transcript) is logged and the hook exits 0. Claude Code's
+session close is never blocked.
+
+## Required environment
+
+The hook needs three env vars at run time:
+
+| Var | What | How to set |
+|---|---|---|
+| `SUPABASE_URL` | Your Supabase project URL (e.g. `https://abc.supabase.co`) | `~/.termdeck/secrets.env` (Tier 2) |
+| `SUPABASE_SERVICE_KEY` | Service-role key with INSERT on `memory_items`. **Not the anon key.** | `~/.termdeck/secrets.env` |
+| `OPENAI_API_KEY` | OpenAI key for embedding inference | `~/.termdeck/secrets.env` or your shell |
+
+Claude Code propagates the parent shell's environment into hook
+processes, so anything in your shell init or
+`~/.termdeck/secrets.env` (sourced by `scripts/start.sh` /
+`npx @jhizzard/termdeck`) is visible to the hook.
+
+If any of the three is missing the log line will name them:
+
+```
+[2026-04-27T21:30:00.000Z] env-var-missing: OPENAI_API_KEY — set these in ~/.termdeck/secrets.env or your shell to enable Mnestra ingestion. Skipping.
+```
+
+## Customizing the project map
+
+The hook ships with an **empty `PROJECT_MAP`** by default — every
+session lands under `project: 'global'` until you add entries. To add
+your own:
+
+1. Open `~/.claude/hooks/memory-session-end.js` after the installer
+   has dropped it.
+2. Find the `PROJECT_MAP` array near the top of the file.
+3. Add one entry per project; each entry is `{ pattern, project }`
+   where `pattern` is a regex matched against `cwd`:
+
+```js
+const PROJECT_MAP = [
+  { pattern: /\/PVB\//i,           project: 'pvb' },
+  { pattern: /\/my-startup\//i,    project: 'my-startup' },
+  { pattern: /chopin-nashville/i,  project: 'chopin-nashville' },
+];
+```
+
+First match wins. Iteration order is array order, so put more specific
+patterns first. Anything that doesn't match falls through to
+`'global'`.
+
+The map is local-only — it's never sent to any service. Editing it
+takes effect on the next Claude Code session close (no restart
+needed).
+
+## Coexistence with Joshua's `rag-system` hook
+
+If you have Joshua's private `rag-system` repo and his rag-system-based
+session hook installed, this bundled hook and that one can coexist:
+
+- The bundled hook writes `source_type='session_summary'` — one row
+  per session, summary-only.
+- The `rag-system` hook writes `source_type='fact'` — multiple rows
+  per session via Claude Haiku fact extraction + dedup.
+
+Different `source_type` values mean the two paths don't dedup against
+each other. If both are installed at the same path
+(`~/.claude/hooks/memory-session-end.js`) the installer will prompt
+before overwriting; choose accordingly.
+
+## How to disable
+
+Two options:
+
+1. Edit `~/.claude/settings.json` and remove the entry under
+   `hooks.Stop` that references `memory-session-end.js`. Leave the
+   file in place; it simply won't fire.
+2. Or delete `~/.claude/hooks/memory-session-end.js` AND remove the
+   `settings.json` entry. (Removing only the file leaves a broken
+   `command` in settings — Claude Code will log a missing-file error
+   on every session close.)
+
+Re-running `npx @jhizzard/termdeck-stack` after disabling will
+re-prompt to install. Decline at the prompt to stay opted out.
+
+## Optional flags
+
+| Env var | Effect |
+|---|---|
+| `TERMDECK_HOOK_DEBUG=1` | Verbose `[debug]` lines in the log |
+| `TERMDECK_HOOK_MIN_BYTES=10000` | Override the 5 KB skip threshold |
+
+## Log file
+
+`~/.claude/hooks/memory-hook.log` accumulates one line per session
+event (skips, errors, ingests). The hook never rotates it. If it
+grows unwieldy you can truncate it
+(`: > ~/.claude/hooks/memory-hook.log`) without affecting hook
+behavior.

package/assets/hooks/memory-session-end.js

@@ -0,0 +1,238 @@
+/**
+ * TermDeck session-end memory hook (Mnestra-direct, no rag-system dependency).
+ *
+ * Vendored into ~/.claude/hooks/memory-session-end.js by @jhizzard/termdeck-stack.
+ * Wired into ~/.claude/settings.json under hooks.Stop. Fires on Claude Code Stop event.
+ *
+ * Behavior:
+ *   1. Reads {transcript_path, cwd, session_id} from stdin (Claude Code Stop payload).
+ *   2. Skips small transcripts (< MIN_TRANSCRIPT_BYTES, default 5KB).
+ *   3. Validates env vars; logs and exits cleanly if any required key is missing.
+ *   4. Detects project from cwd against PROJECT_MAP (else "global"). Extend the
+ *      map by editing the array below — see assets/hooks/README.md for guidance.
+ *   5. Builds a coarse session summary from the transcript (last ~30 message excerpts).
+ *   6. Embeds the summary via OpenAI text-embedding-3-small.
+ *   7. POSTs ONE row to Supabase /rest/v1/memory_items with source_type='session_summary'.
+ *   8. Logs every step to ~/.claude/hooks/memory-hook.log.
+ *
+ * Required env vars (validated at entry):
+ *   - SUPABASE_URL              e.g. https://luvvbrpaopnblvxdxwzb.supabase.co
+ *   - SUPABASE_SERVICE_KEY      service-role key (NOT the anon key — needs INSERT on memory_items)
+ *   - OPENAI_API_KEY            sk-... for text-embedding-3-small
+ *
+ * Optional:
+ *   - TERMDECK_HOOK_DEBUG=1            verbose logging
+ *   - TERMDECK_HOOK_MIN_BYTES=5000     transcript size threshold
+ *
+ * Fail-soft contract: any error (network, parse, env-var-missing, malformed transcript)
+ * logs and exits 0. Never blocks Claude Code session close.
+ *
+ * Co-existence with Joshua's personal rag-system hook: this bundled hook writes
+ * source_type='session_summary' (one row per session). Joshua's personal hook
+ * writes source_type='fact' (multiple rows from extractFacts pipeline). Different
+ * source_types coexist in memory_items without dedup collisions.
+ */
+
+'use strict';
+
+const { existsSync, statSync, appendFileSync, readFileSync } = require('fs');
+const { join } = require('path');
+const os = require('os');
+
+const LOG_FILE = join(os.homedir(), '.claude', 'hooks', 'memory-hook.log');
+
+// PROJECT_MAP — minimal default. Users extend by adding entries to this array.
+// Patterns match against the cwd reported by Claude Code at Stop time.
+// First match wins; falls through to "global".
+const PROJECT_MAP = [
+  // Example entries — uncomment + edit, or add your own:
+  // { pattern: /\/myproject\//i,        project: 'my-project' },
+  // { pattern: /work-stuff/i,           project: 'work' },
+];
+
+const MIN_TRANSCRIPT_BYTES = parseInt(process.env.TERMDECK_HOOK_MIN_BYTES || '5000', 10);
+const DEBUG = process.env.TERMDECK_HOOK_DEBUG === '1';
+
+function log(msg) {
+  try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] ${msg}\n`); }
+  catch (_) { /* fail-soft */ }
+}
+function debug(msg) { if (DEBUG) log(`[debug] ${msg}`); }
+
+function detectProject(cwd) {
+  for (const { pattern, project } of PROJECT_MAP) {
+    if (pattern.test(cwd)) return project;
+  }
+  return 'global';
+}
+
+function readEnv() {
+  const required = ['SUPABASE_URL', 'SUPABASE_SERVICE_KEY', 'OPENAI_API_KEY'];
+  const missing = required.filter((k) => !process.env[k]);
+  if (missing.length) {
+    log(`env-var-missing: ${missing.join(', ')} — set these in ~/.termdeck/secrets.env or your shell to enable Mnestra ingestion. Skipping.`);
+    return null;
+  }
+  return {
+    supabaseUrl: process.env.SUPABASE_URL.replace(/\/$/, ''),
+    supabaseKey: process.env.SUPABASE_SERVICE_KEY,
+    openaiKey: process.env.OPENAI_API_KEY,
+  };
+}
+
+function buildSummary(transcriptPath) {
+  let raw;
+  try { raw = readFileSync(transcriptPath, 'utf8'); }
+  catch (e) { log(`read-transcript-failed: ${e.message}`); return null; }
+
+  const lines = raw.split('\n').filter(Boolean);
+  const messages = [];
+  for (const line of lines) {
+    let msg;
+    try { msg = JSON.parse(line); } catch (_) { continue; }
+    const role = msg?.message?.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const content = msg.message.content;
+    let text = '';
+    if (typeof content === 'string') text = content;
+    else if (Array.isArray(content)) {
+      text = content.filter((c) => c && c.type === 'text').map((c) => c.text).join(' ');
+    }
+    if (text) messages.push({ role, content: text.slice(0, 400) });
+  }
+
+  if (messages.length < 5) {
+    debug(`session-too-short: ${messages.length} messages, skipping`);
+    return null;
+  }
+
+  const tail = messages.slice(-30);
+  const summary =
+    `Session with ${messages.length} messages.\n\n` +
+    tail.map((m) => `[${m.role}] ${m.content}`).join('\n');
+  // OpenAI text-embedding-3-small accepts up to 8192 tokens (~32K chars).
+  // 7000 chars is a safe headroom that survives multibyte expansion.
+  return summary.slice(0, 7000);
+}
+
+async function embedText(text, openaiKey) {
+  try {
+    const res = await fetch('https://api.openai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${openaiKey}`,
+      },
+      body: JSON.stringify({ model: 'text-embedding-3-small', input: text }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      log(`openai-embed-failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+      return null;
+    }
+    const data = await res.json();
+    return data?.data?.[0]?.embedding || null;
+  } catch (e) {
+    log(`openai-embed-exception: ${e.message}`);
+    return null;
+  }
+}
+
+async function postMemoryItem({ supabaseUrl, supabaseKey, content, embedding, project, sessionId }) {
+  try {
+    const res = await fetch(`${supabaseUrl}/rest/v1/memory_items`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'apikey': supabaseKey,
+        'Authorization': `Bearer ${supabaseKey}`,
+        'Prefer': 'return=minimal',
+      },
+      body: JSON.stringify({
+        content,
+        embedding: `[${embedding.join(',')}]`,
+        source_type: 'session_summary',
+        category: 'workflow',
+        project,
+        source_session_id: sessionId || null,
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      log(`supabase-insert-failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    log(`supabase-insert-exception: ${e.message}`);
+    return false;
+  }
+}
+
+async function processStdinPayload(input) {
+  let data;
+  try { data = JSON.parse(input); }
+  catch (e) { log(`parse-stdin-failed: ${e.message}`); return; }
+
+  const transcriptPath = data.transcript_path;
+  const cwd = data.cwd || '';
+  const sessionId =
+    data.session_id ||
+    (transcriptPath ? transcriptPath.split('/').pop().replace('.jsonl', '') : null);
+
+  if (!transcriptPath) { log('no-transcript-path: skipping'); return; }
+
+  let stat;
+  try { stat = statSync(transcriptPath); }
+  catch (e) { log(`cannot-stat-transcript: ${transcriptPath} — ${e.message}`); return; }
+
+  if (stat.size < MIN_TRANSCRIPT_BYTES) {
+    debug(`small-transcript: ${stat.size} bytes < ${MIN_TRANSCRIPT_BYTES}, skipping`);
+    return;
+  }
+
+  const env = readEnv();
+  if (!env) return;
+
+  const project = detectProject(cwd);
+  debug(`project="${project}", session=${sessionId}`);
+
+  const summary = buildSummary(transcriptPath);
+  if (!summary) return;
+
+  const embedding = await embedText(summary, env.openaiKey);
+  if (!embedding) return;
+
+  const ok = await postMemoryItem({
+    supabaseUrl: env.supabaseUrl,
+    supabaseKey: env.supabaseKey,
+    content: summary,
+    embedding,
+    project,
+    sessionId,
+  });
+
+  if (ok) log(`ingested: project="${project}" session=${sessionId} bytes=${summary.length}`);
+}
+
+// Module-export contract for testability. When run as a script (require.main === module),
+// read stdin and process. When require()d (tests), expose helpers.
+if (require.main === module) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    processStdinPayload(input).catch((e) => log(`hook-error: ${e.message}`));
+  });
+} else {
+  module.exports = {
+    PROJECT_MAP,
+    detectProject,
+    readEnv,
+    buildSummary,
+    embedText,
+    postMemoryItem,
+    processStdinPayload,
+    LOG_FILE,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck-stack",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "One-command installer for the TermDeck developer memory stack: TermDeck + Mnestra + Rumen + Supabase MCP",
   "bin": {
     "termdeck-stack": "./src/index.js"
@@ -8,6 +8,7 @@
   "main": "./src/index.js",
   "files": [
     "src/**",
+    "assets/**",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/src/index.js

@@ -29,6 +29,16 @@ const path = require('node:path');
 const readline = require('node:readline/promises');
 const { spawn, spawnSync } = require('node:child_process');
 
+const mcpConfigLib = require('./mcp-config');
+const {
+  CLAUDE_MCP_PATH_CANONICAL,
+  CLAUDE_MCP_PATH_LEGACY,
+  readMcpServers,
+  mergeMcpServers,
+  writeMcpServers,
+  migrateLegacyIfPresent,
+} = mcpConfigLib;
+
 const ANSI = {
   green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', blue: '\x1b[34m',
   cyan: '\x1b[36m', magenta: '\x1b[35m', dim: '\x1b[2m', bold: '\x1b[1m',
@@ -36,7 +46,13 @@ const ANSI = {
 };
 
 const HOME = os.homedir();
-const MCP_CONFIG = path.join(HOME, '.claude', 'mcp.json');
+const MCP_CONFIG = CLAUDE_MCP_PATH_CANONICAL;
+const SETTINGS_JSON = path.join(HOME, '.claude', 'settings.json');
+const HOOK_DEST_DIR = path.join(HOME, '.claude', 'hooks');
+const HOOK_DEST = path.join(HOOK_DEST_DIR, 'memory-session-end.js');
+const HOOK_SOURCE = path.join(__dirname, '..', 'assets', 'hooks', 'memory-session-end.js');
+const HOOK_COMMAND = 'node ~/.claude/hooks/memory-session-end.js';
+const HOOK_TIMEOUT_SECONDS = 30;
 
 const LAYERS = [
   {
@@ -249,36 +265,40 @@ async function installLayers(plan, opts) {
   return failures;
 }
 
-// ── ~/.claude/mcp.json wiring ───────────────────────────────────────
-
-function readMcpConfig() {
-  if (!fs.existsSync(MCP_CONFIG)) return { mcpServers: {} };
-  try {
-    const parsed = JSON.parse(fs.readFileSync(MCP_CONFIG, 'utf8'));
-    if (!parsed.mcpServers) parsed.mcpServers = {};
-    return parsed;
-  } catch (_e) {
-    return { mcpServers: {} };
-  }
-}
-
-function writeMcpConfig(cfg) {
-  fs.mkdirSync(path.dirname(MCP_CONFIG), { recursive: true });
-  fs.writeFileSync(MCP_CONFIG, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
-}
+// ── ~/.claude.json wiring ───────────────────────────────────────────
+//
+// Sprint 36 T2: writes go to ~/.claude.json (the path Claude Code v2.1.119+
+// actually reads). On install, any entries living in the legacy
+// ~/.claude/mcp.json are merged forward — the legacy file is left in place
+// so users who pin other tooling to it keep working.
 
 function wireMcpEntries(plan, opts) {
   if (opts.dryRun) {
-    process.stdout.write(`${ANSI.bold}Would wire ~/.claude/mcp.json (dry-run skipped)${ANSI.reset}\n\n`);
+    process.stdout.write(`${ANSI.bold}Would wire ${MCP_CONFIG} (dry-run skipped)${ANSI.reset}\n\n`);
     return;
   }
-  const cfg = readMcpConfig();
+
+  // Step 1: forward-migrate any legacy entries, current always wins.
+  const migration = migrateLegacyIfPresent({ canonicalPath: MCP_CONFIG, legacyPath: CLAUDE_MCP_PATH_LEGACY });
+
+  // Step 2: re-read the canonical file (may have just been written by the
+  // migration) and apply our additions.
+  const current = readMcpServers(MCP_CONFIG);
+  if (current.malformed) {
+    process.stdout.write(
+      `${ANSI.red}✗${ANSI.reset} ${MCP_CONFIG} is malformed (${current.error || 'parse error'}); ` +
+      `not modified — fix the JSON and re-run.\n\n`
+    );
+    return;
+  }
+  const servers = { ...current.servers };
   const installedTiers = new Set(plan.map((l) => l.tier));
   const additions = [];
   const keptExisting = [];
 
-  if (installedTiers.has(2) && !cfg.mcpServers.mnestra) {
-    cfg.mcpServers.mnestra = {
+  if (installedTiers.has(2) && !servers.mnestra) {
+    servers.mnestra = {
+      type: 'stdio',
       command: 'mnestra',
       env: {
         SUPABASE_URL: '${SUPABASE_URL}',
@@ -287,12 +307,13 @@ function wireMcpEntries(plan, opts) {
       },
     };
     additions.push('mnestra');
-  } else if (cfg.mcpServers.mnestra) {
+  } else if (servers.mnestra) {
     keptExisting.push('mnestra');
   }
 
-  if (installedTiers.has(4) && !cfg.mcpServers.supabase) {
-    cfg.mcpServers.supabase = {
+  if (installedTiers.has(4) && !servers.supabase) {
+    servers.supabase = {
+      type: 'stdio',
       command: 'npx',
       args: ['-y', '@supabase/mcp-server-supabase@latest'],
       env: {
@@ -300,19 +321,215 @@ function wireMcpEntries(plan, opts) {
       },
     };
     additions.push('supabase');
-  } else if (cfg.mcpServers.supabase) {
+  } else if (servers.supabase) {
     keptExisting.push('supabase');
   }
 
-  if (additions.length === 0 && keptExisting.length === 0) return;
+  const migrated = (migration && migration.migrated) || [];
+  if (additions.length === 0 && keptExisting.length === 0 && migrated.length === 0) return;
 
-  process.stdout.write(`${ANSI.bold}Wiring ~/.claude/mcp.json...${ANSI.reset}\n`);
+  process.stdout.write(`${ANSI.bold}Wiring ${MCP_CONFIG}...${ANSI.reset}\n`);
+  if (migrated.length > 0) {
+    statusLine(
+      `${ANSI.cyan}↑${ANSI.reset}`,
+      `migrated ${migrated.length} entr${migrated.length === 1 ? 'y' : 'ies'} from legacy`,
+      `${migrated.join(', ')} (legacy ${CLAUDE_MCP_PATH_LEGACY} left in place)`,
+    );
+  }
   for (const name of additions) statusLine(`${ANSI.green}+${ANSI.reset}`, `${name} entry`, 'added');
   for (const name of keptExisting) statusLine(`${ANSI.dim}=${ANSI.reset}`, `${name} entry`, 'already present, kept as-is');
-  if (additions.length > 0) writeMcpConfig(cfg);
+  if (additions.length > 0) writeMcpServers(MCP_CONFIG, servers);
   process.stdout.write('\n');
 }
 
+// Test hook — exposed so unit tests can drive the merge primitives without
+// spawning a full installer. Not part of the public CLI surface.
+const _mcpInternals = {
+  readMcpServers,
+  mergeMcpServers,
+  writeMcpServers,
+  migrateLegacyIfPresent,
+};
+
+// ── Session-end hook bundling ───────────────────────────────────────
+
+// Returns true if the given hook-entry's `command` string references our
+// session-end hook file. Substring match is robust to `~` vs `$HOME` vs
+// absolute paths.
+function _isSessionEndHookEntry(entry) {
+  return entry && typeof entry.command === 'string'
+    && entry.command.includes('memory-session-end.js');
+}
+
+// Pure: merges our Stop entry into the given settings object. Idempotent.
+// Returns { settings, status } where status is 'already-installed' or
+// 'installed'. Mutates the input.
+function _mergeSessionEndHookEntry(settings, opts = {}) {
+  const command = opts.command || HOOK_COMMAND;
+  const timeout = opts.timeout != null ? opts.timeout : HOOK_TIMEOUT_SECONDS;
+
+  if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
+  if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
+
+  for (const group of settings.hooks.Stop) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    if (group.hooks.some(_isSessionEndHookEntry)) {
+      return { settings, status: 'already-installed' };
+    }
+  }
+
+  const entry = { type: 'command', command, timeout };
+  const emptyMatcher = settings.hooks.Stop.find(
+    (g) => g && g.matcher === '' && Array.isArray(g.hooks)
+  );
+  if (emptyMatcher) {
+    emptyMatcher.hooks.push(entry);
+  } else {
+    settings.hooks.Stop.push({ matcher: '', hooks: [entry] });
+  }
+  return { settings, status: 'installed' };
+}
+
+function _readSettingsJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { settings: {}, status: 'no-file' };
+  }
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    if (raw.trim() === '') return { settings: {}, status: 'empty' };
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { settings: {}, status: 'malformed', error: 'top-level must be an object' };
+    }
+    return { settings: parsed, status: 'ok' };
+  } catch (e) {
+    return { settings: {}, status: 'malformed', error: e.message };
+  }
+}
+
+function _writeSettingsJson(filePath, settings) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+}
+
+// Compares two file contents byte-for-byte. Returns 'identical', 'different',
+// or 'missing-dest'.
+function _compareHookFiles(srcPath, destPath) {
+  if (!fs.existsSync(destPath)) return 'missing-dest';
+  const a = fs.readFileSync(srcPath);
+  const b = fs.readFileSync(destPath);
+  return a.equals(b) ? 'identical' : 'different';
+}
+
+async function promptYesNo({ question, defaultYes = true }) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const suffix = defaultYes ? '(Y/n)' : '(y/N)';
+  const ans = (await rl.question(`  ${question} ${suffix} `)).trim().toLowerCase();
+  rl.close();
+  if (ans === '') return defaultYes;
+  return ans === 'y' || ans === 'yes';
+}
+
+// Orchestrator: prompt → file copy → settings.json merge.
+// Exposed so tests can drive it with explicit paths and a stub prompt.
+async function installSessionEndHook(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const sourcePath = opts.sourcePath || HOOK_SOURCE;
+  const destPath = opts.destPath || HOOK_DEST;
+  const settingsPath = opts.settingsPath || SETTINGS_JSON;
+  // promptInstall: () => Promise<boolean>; defaults to Y.
+  // promptOverwrite: () => Promise<boolean>; defaults to N.
+  const promptInstall = opts.promptInstall
+    || (() => promptYesNo({ question: "Install TermDeck's session-end memory hook?", defaultYes: true }));
+  const promptOverwrite = opts.promptOverwrite
+    || (() => promptYesNo({
+      question: `Existing hook found at ${destPath}. Overwrite?`,
+      defaultYes: false,
+    }));
+
+  rule();
+  process.stdout.write(`${ANSI.bold}Session-end memory hook${ANSI.reset}\n`);
+  process.stdout.write(`${ANSI.dim}  Fires on every Claude Code session close to summarize the session into Mnestra.${ANSI.reset}\n\n`);
+
+  const userWantsInstall = opts.assumeYes ? true
+    : opts.assumeNo ? false
+    : await promptInstall();
+
+  if (!userWantsInstall) {
+    statusLine(`${ANSI.dim}─${ANSI.reset}`, 'session-end hook', 'skipped (user declined)');
+    process.stdout.write('\n');
+    return { fileStatus: 'declined', settingsStatus: 'declined' };
+  }
+
+  // 1. File copy.
+  let fileStatus;
+  const cmp = _compareHookFiles(sourcePath, destPath);
+  if (cmp === 'missing-dest') {
+    if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would copy hook to ${destPath}`);
+      fileStatus = 'would-copy';
+    } else {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(sourcePath, destPath);
+      fs.chmodSync(destPath, 0o644);
+      statusLine(`${ANSI.green}+${ANSI.reset}`, 'hook file', `copied to ${destPath}`);
+      fileStatus = 'copied';
+    }
+  } else if (cmp === 'identical') {
+    statusLine(`${ANSI.dim}=${ANSI.reset}`, 'hook file', 'already present, identical contents');
+    fileStatus = 'already-current';
+  } else {
+    // different
+    const overwrite = opts.assumeYes ? false // --yes preserves existing on overwrite
+      : opts.forceOverwrite ? true
+      : await promptOverwrite();
+    if (!overwrite) {
+      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'hook file', `existing kept (differs from vendored copy)`);
+      fileStatus = 'kept-existing';
+    } else if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would overwrite ${destPath}`);
+      fileStatus = 'would-overwrite';
+    } else {
+      fs.copyFileSync(sourcePath, destPath);
+      fs.chmodSync(destPath, 0o644);
+      statusLine(`${ANSI.green}↻${ANSI.reset}`, 'hook file', `overwrote ${destPath}`);
+      fileStatus = 'overwritten';
+    }
+  }
+
+  // 2. Settings.json merge.
+  const read = _readSettingsJson(settingsPath);
+  let settingsStatus;
+  if (read.status === 'malformed') {
+    statusLine(`${ANSI.red}✗${ANSI.reset}`, 'settings.json', `malformed (${read.error}); not modified`);
+    settingsStatus = 'malformed';
+  } else {
+    const merged = _mergeSessionEndHookEntry(read.settings);
+    if (merged.status === 'already-installed') {
+      statusLine(`${ANSI.dim}=${ANSI.reset}`, 'settings.json Stop hook', 'already installed');
+      settingsStatus = 'already-installed';
+    } else if (dryRun) {
+      statusLine(`${ANSI.yellow}↩${ANSI.reset}`, '(dry-run)', `would merge Stop hook into ${settingsPath}`);
+      settingsStatus = 'would-install';
+    } else {
+      _writeSettingsJson(settingsPath, merged.settings);
+      statusLine(`${ANSI.green}+${ANSI.reset}`, 'settings.json Stop hook', 'merged');
+      settingsStatus = 'installed';
+    }
+  }
+
+  process.stdout.write('\n');
+  if (!dryRun && (fileStatus === 'copied' || settingsStatus === 'installed')) {
+    process.stdout.write(`  ${ANSI.dim}Hook installed at ${destPath}.${ANSI.reset}\n`);
+    process.stdout.write(`  ${ANSI.dim}It runs on every Claude Code session close to summarize the session into Mnestra.${ANSI.reset}\n`);
+    process.stdout.write(`  ${ANSI.dim}See assets/hooks/README.md in @jhizzard/termdeck-stack for details.${ANSI.reset}\n\n`);
+  }
+
+  return { fileStatus, settingsStatus };
+}
+
 // ── Next steps ──────────────────────────────────────────────────────
 
 function printNextSteps(plan, opts) {
@@ -405,6 +622,13 @@ async function main(argv) {
   // "already had everything but never set up Claude Code MCP" case.
   wireMcpEntries(wantedLayers, { dryRun: args.dryRun });
 
+  // Bundle the session-end memory hook (default-on, opt-in via prompt).
+  // --yes accepts the install but preserves any existing differing hook.
+  await installSessionEndHook({
+    dryRun: args.dryRun,
+    assumeYes: args.yes,
+  });
+
   printNextSteps(wantedLayers, { dryRun: args.dryRun });
 
   if (failures > 0) {
@@ -422,3 +646,16 @@ if (require.main === module) {
 }
 
 module.exports = main;
+module.exports._mergeSessionEndHookEntry = _mergeSessionEndHookEntry;
+module.exports._readSettingsJson = _readSettingsJson;
+module.exports._writeSettingsJson = _writeSettingsJson;
+module.exports._isSessionEndHookEntry = _isSessionEndHookEntry;
+module.exports._compareHookFiles = _compareHookFiles;
+module.exports.installSessionEndHook = installSessionEndHook;
+module.exports.HOOK_COMMAND = HOOK_COMMAND;
+module.exports.HOOK_TIMEOUT_SECONDS = HOOK_TIMEOUT_SECONDS;
+module.exports.HOOK_SOURCE = HOOK_SOURCE;
+module.exports._mcpInternals = _mcpInternals;
+module.exports.MCP_CONFIG_PATH = MCP_CONFIG;
+module.exports.CLAUDE_MCP_PATH_CANONICAL = CLAUDE_MCP_PATH_CANONICAL;
+module.exports.CLAUDE_MCP_PATH_LEGACY = CLAUDE_MCP_PATH_LEGACY;

package/src/mcp-config.js

@@ -0,0 +1,138 @@
+'use strict';
+
+// Canonical schema/CRUD for the Claude Code MCP server config.
+//
+// SIBLING COPY of packages/cli/src/mcp-config.js. Two physical copies
+// exist so each published npm package (@jhizzard/termdeck and
+// @jhizzard/termdeck-stack) stays self-contained — the stack-installer's
+// `files` field publishes only `src/**` and cannot require() into the
+// CLI package. Same exports, same semantics. Keep in sync.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CLAUDE_MCP_PATH_CANONICAL = path.join(os.homedir(), '.claude.json');
+const CLAUDE_MCP_PATH_LEGACY = path.join(os.homedir(), '.claude', 'mcp.json');
+
+function readMcpServers(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { servers: {}, raw: {}, missing: true, malformed: false };
+  }
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: err.message };
+  }
+  if (text.trim() === '') {
+    return { servers: {}, raw: {}, missing: false, malformed: false };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: err.message };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: 'top-level must be an object' };
+  }
+  const servers = (parsed.mcpServers && typeof parsed.mcpServers === 'object' && !Array.isArray(parsed.mcpServers))
+    ? parsed.mcpServers
+    : {};
+  return { servers, raw: parsed, missing: false, malformed: false };
+}
+
+function mergeMcpServers(currentServers, legacyServers) {
+  const out = {};
+  const legacy = (legacyServers && typeof legacyServers === 'object') ? legacyServers : {};
+  const current = (currentServers && typeof currentServers === 'object') ? currentServers : {};
+  for (const [name, entry] of Object.entries(legacy)) {
+    out[name] = entry;
+  }
+  for (const [name, entry] of Object.entries(current)) {
+    out[name] = entry;
+  }
+  return out;
+}
+
+function writeMcpServers(filePath, servers) {
+  const existing = readMcpServers(filePath);
+  const next = (existing.malformed || existing.missing)
+    ? {}
+    : { ...existing.raw };
+  next.mcpServers = servers || {};
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+  try { fs.chmodSync(filePath, 0o600); } catch (_e) { /* best-effort */ }
+}
+
+function migrateLegacyIfPresent(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const canonicalPath = opts.canonicalPath || CLAUDE_MCP_PATH_CANONICAL;
+  const legacyPath = opts.legacyPath || CLAUDE_MCP_PATH_LEGACY;
+
+  const canonical = readMcpServers(canonicalPath);
+  const legacy = readMcpServers(legacyPath);
+
+  const malformed = {};
+  if (canonical.malformed) malformed.canonical = canonical.error || true;
+  if (legacy.malformed) malformed.legacy = legacy.error || true;
+
+  if (legacy.missing || legacy.malformed) {
+    return {
+      migrated: [],
+      kept: [],
+      wrote: false,
+      canonicalPath,
+      legacyPath,
+      malformed: Object.keys(malformed).length ? malformed : undefined,
+    };
+  }
+
+  const migrated = [];
+  const kept = [];
+  const merged = { ...canonical.servers };
+  for (const [name, entry] of Object.entries(legacy.servers)) {
+    if (Object.prototype.hasOwnProperty.call(canonical.servers, name)) {
+      kept.push(name);
+    } else {
+      merged[name] = entry;
+      migrated.push(name);
+    }
+  }
+
+  if (migrated.length === 0) {
+    return {
+      migrated: [],
+      kept,
+      wrote: false,
+      canonicalPath,
+      legacyPath,
+      malformed: Object.keys(malformed).length ? malformed : undefined,
+    };
+  }
+
+  if (!dryRun) writeMcpServers(canonicalPath, merged);
+
+  return {
+    migrated,
+    kept,
+    wrote: !dryRun,
+    canonicalPath,
+    legacyPath,
+    malformed: Object.keys(malformed).length ? malformed : undefined,
+  };
+}
+
+module.exports = {
+  CLAUDE_MCP_PATH_CANONICAL,
+  CLAUDE_MCP_PATH_LEGACY,
+  readMcpServers,
+  mergeMcpServers,
+  writeMcpServers,
+  migrateLegacyIfPresent,
+};