@jhizzard/termdeck 0.7.2 → 0.8.0

package/packages/cli/src/init-mnestra.js

@@ -11,9 +11,10 @@
 //      or migration failure doesn't lose the user's typed-in keys.
 //   3. Connect via `pg` using the direct URL
 //   4. Apply the six bundled Mnestra migrations in order
-//   5. Update ~/.termdeck/config.yaml to enable RAG + point at ${VAR} refs
-//      (only after migrations apply cleanly — otherwise the server would
-//      try to use an incomplete schema on next startup)
+//   5. Update ~/.termdeck/config.yaml — set rag.enabled: false (MCP-only
+//      default; opt into TermDeck-side RAG via dashboard toggle) and point
+//      at ${VAR} refs (only after migrations apply cleanly — otherwise the
+//      server would try to use an incomplete schema on next startup)
 //   6. Verify with a memory_status_aggregation() call
 //
 // Flags:
@@ -74,7 +75,8 @@ const HELP = [
   '  2. Writes ~/.termdeck/secrets.env IMMEDIATELY (merge-aware) so a later',
   '     pg connect or migration failure does not lose what you typed in.',
   '  3. Connects to Postgres and applies the six Mnestra schema + RPC migrations.',
-  '  4. Updates ~/.termdeck/config.yaml to enable RAG and reference ${VAR} keys.',
+  '  4. Updates ~/.termdeck/config.yaml — sets rag.enabled: false (MCP-only',
+  '     default) and references ${VAR} keys for credentials.',
   '  5. Verifies the Mnestra store is reachable via memory_status_aggregation().',
   '',
   'Every secret stays on your machine. Nothing is ever printed once entered.',
@@ -180,7 +182,8 @@ This wizard configures TermDeck's Tier 2 memory layer (Mnestra) by:
   5. Writing ~/.termdeck/secrets.env (before any database work, so a
      pg failure cannot lose what you typed in)
   6. Connecting to Postgres + applying six SQL migrations
-  7. Updating ~/.termdeck/config.yaml to enable RAG (only after
+  7. Updating ~/.termdeck/config.yaml — rag.enabled: false (MCP-only
+     default; toggle in dashboard later) with \${VAR} refs (only after
      migrations apply cleanly)
   8. Verifying the connection with a memory_status call
 
@@ -410,11 +413,27 @@ function writeSecretsFile(inputs, dryRun) {
   ok();
 }
 
+// MCP-only is the default starting v0.7.3. Mnestra's MCP server populates
+// `memory_items` whenever an AI worker calls memory_remember / memory_recall,
+// so the dashboard's Flashback queries work out of the box. The TermDeck-side
+// RAG event tables (mnestra_session_memory / mnestra_project_memory /
+// mnestra_developer_memory / mnestra_commands) stay off until the user opts
+// in via the dashboard or by editing config.yaml. This matches Joshua's
+// daily-driver setup and avoids the v0.7.2-and-earlier asymmetry that hit
+// Brad's box on 2026-04-27 (default `enabled: true` against tables no init
+// path created → 404 cascade → silent RAG drop).
 function writeYamlConfig(dryRun) {
-  step('Updating ~/.termdeck/config.yaml (rag.enabled: true)...');
+  process.stdout.write(
+    '\nSetup mode: MCP-only (default)\n' +
+    '  Mnestra MCP tools fill memory_items via memory_remember / memory_recall.\n' +
+    '  TermDeck event tables (session / project / developer) stay OFF by default.\n' +
+    '  Enable later: toggle in dashboard at http://localhost:3000/#config\n' +
+    '  or set rag.enabled: true in ~/.termdeck/config.yaml.\n\n'
+  );
+  step('Updating ~/.termdeck/config.yaml (rag.enabled: false, MCP-only default)...');
   if (dryRun) { ok('(dry-run)'); return; }
   const r = yaml.updateRagConfig({
-    enabled: true,
+    enabled: false,
     supabaseUrl: '${SUPABASE_URL}',
     supabaseKey: '${SUPABASE_SERVICE_ROLE_KEY}',
     openaiApiKey: '${OPENAI_API_KEY}',
@@ -428,6 +447,11 @@ function printNextSteps() {
   process.stdout.write(`
 Mnestra is configured.
 
+Setup mode: MCP-only (default) — TermDeck-side RAG event tables are off.
+To enable session / project / developer memory tables, toggle in the dashboard
+at http://localhost:3000/#config or set rag.enabled: true in
+~/.termdeck/config.yaml and restart TermDeck.
+
 Next steps:
   1. Restart TermDeck: termdeck
   2. Flashback will fire automatically on panel errors

package/packages/cli/src/init-rumen.js

@@ -38,6 +38,12 @@ const {
   preconditions
 } = require(SETUP_DIR);
 
+const {
+  CLAUDE_MCP_PATH_CANONICAL,
+  readMcpServers,
+  writeMcpServers,
+} = require('./mcp-config');
+
 // Pinned fallback used only when the npm registry is unreachable. Bump this
 // when you republish @jhizzard/rumen and can't (or won't) rely on `npm view`
 // at deploy time. The wizard prefers the live registry answer — this value
@@ -470,28 +476,29 @@ async function applySchedule(projectRef, secrets, dryRun) {
   }
 }
 
-// Backfill SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json's Supabase MCP
+// Backfill SUPABASE_ACCESS_TOKEN into ~/.claude.json's Supabase MCP
 // server entry. Background: the meta-installer (`@jhizzard/termdeck-stack`)
 // writes `SUPABASE_ACCESS_TOKEN: 'SUPABASE_PAT_HERE'` as a literal
 // placeholder when it wires the Supabase MCP entry. The user is expected
 // to replace it after install. v0.6.4 unblocked the Rumen install path by
 // telling users to `export SUPABASE_ACCESS_TOKEN=sbp_...` in their shell —
 // but that token only got used for `supabase link`, never propagated into
-// `~/.claude/mcp.json`. So Brad's Claude Code was talking to a Supabase
-// MCP server with a placeholder token. He had to update the JSON file
-// manually. Reported 2026-04-26 — Brad's quote: "the token hadn't been
-// written to the Json file which we updated manually, but you may want
-// to put that in the patch at some point."
+// the MCP config. So Brad's Claude Code was talking to a Supabase MCP
+// server with a placeholder token. Reported 2026-04-26.
+//
+// Sprint 36 T2: default target moved from ~/.claude/mcp.json (legacy) to
+// ~/.claude.json (canonical — what Claude Code v2.1.119+ actually reads).
+// Internal write goes through writeMcpServers so the ~55 unrelated
+// top-level keys Claude Code stores in ~/.claude.json (oauthAccount,
+// projects, installMethod, …) are preserved byte-equivalent.
 //
-// This helper closes the loop. Idempotent and conservative:
-//   - Only runs if process.env.SUPABASE_ACCESS_TOKEN is set
+// Idempotent and conservative:
+//   - Only runs if a token is provided via env or arg
 //   - Only updates when the existing value is the literal placeholder
 //     'SUPABASE_PAT_HERE' — preserves any real token the user already set
-//   - No-op when ~/.claude/mcp.json doesn't exist (user never ran the
-//     meta-installer's Tier 4) or when there's no `supabase` MCP entry
+//   - No-op when the file doesn't exist or has no `supabase` entry
 //   - No-op (with a soft warning) when the JSON is malformed
-//   - Atomic write via tmp-and-rename; mode 0600 to match the file's
-//     existing permissions (it already holds the placeholder)
+//   - Atomic write via tmp-and-rename; mode 0600
 //   - All other mcpServers entries preserved verbatim
 //
 // Returns one of: { status: 'updated', path }, { status: 'already-set', path },
@@ -502,24 +509,15 @@ function wireAccessTokenInMcpJson({ token, mcpJsonPath, _testFs } = {}) {
   const tokenValue = token || process.env.SUPABASE_ACCESS_TOKEN;
   if (!tokenValue) return { status: 'no-token-in-env' };
 
-  const targetPath = mcpJsonPath || path.join(os.homedir(), '.claude', 'mcp.json');
+  const targetPath = mcpJsonPath || CLAUDE_MCP_PATH_CANONICAL;
   if (!fsImpl.existsSync(targetPath)) return { status: 'no-file' };
 
-  let raw;
-  try {
-    raw = fsImpl.readFileSync(targetPath, 'utf-8');
-  } catch (err) {
-    return { status: 'malformed', path: targetPath, error: err.message };
-  }
-
-  let cfg;
-  try {
-    cfg = JSON.parse(raw);
-  } catch (err) {
-    return { status: 'malformed', path: targetPath, error: err.message };
+  const read = readMcpServers(targetPath);
+  if (read.malformed) {
+    return { status: 'malformed', path: targetPath, error: read.error };
   }
 
-  const supabaseEntry = cfg && cfg.mcpServers && cfg.mcpServers.supabase;
+  const supabaseEntry = read.servers && read.servers.supabase;
   if (!supabaseEntry || typeof supabaseEntry !== 'object') {
     return { status: 'no-supabase-entry', path: targetPath };
   }
@@ -528,16 +526,15 @@ function wireAccessTokenInMcpJson({ token, mcpJsonPath, _testFs } = {}) {
   const current = supabaseEntry.env.SUPABASE_ACCESS_TOKEN;
   if (current === tokenValue) return { status: 'already-set', path: targetPath };
   if (current && current !== 'SUPABASE_PAT_HERE') {
-    // User has set a real token already — don't touch it.
     return { status: 'already-set', path: targetPath };
   }
 
   supabaseEntry.env.SUPABASE_ACCESS_TOKEN = tokenValue;
 
-  const tmpPath = `${targetPath}.tmp.${process.pid}`;
-  fsImpl.writeFileSync(tmpPath, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
-  fsImpl.renameSync(tmpPath, targetPath);
-  try { fsImpl.chmodSync(targetPath, 0o600); } catch (_e) { /* best-effort */ }
+  // writeMcpServers re-reads `targetPath` to preserve every top-level key
+  // (oauthAccount, projects, installMethod, …) that Claude Code owns. Only
+  // .mcpServers gets replaced with our mutated map.
+  writeMcpServers(targetPath, read.servers);
 
   return { status: 'updated', path: targetPath };
 }
@@ -608,14 +605,14 @@ async function main(argv) {
 
   if (!(await link(projectRef, flags.dryRun))) return 4;
 
-  // Backfill SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json now that
+  // Backfill SUPABASE_ACCESS_TOKEN into ~/.claude.json now that
   // `supabase link` succeeded (the token is verified-real). The
   // meta-installer wrote a literal 'SUPABASE_PAT_HERE' placeholder
   // there during Tier 4 install — this closes that loop.
   if (!flags.dryRun) {
     const r = wireAccessTokenInMcpJson();
     if (r.status === 'updated') {
-      step('Backfilled SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json...');
+      step(`Backfilled SUPABASE_ACCESS_TOKEN into ${r.path}...`);
       ok();
     } else if (r.status === 'malformed') {
       process.stderr.write(

package/packages/cli/src/mcp-config.js

@@ -0,0 +1,174 @@
+'use strict';
+
+// Canonical schema/CRUD for the Claude Code MCP server config.
+//
+// Sprint 36 T2: Claude Code v2.1.119+ reads its MCP config from
+// ~/.claude.json (top-level `mcpServers` key, alongside ~55 other internal
+// keys it owns). Earlier installs wrote to ~/.claude/mcp.json, which the
+// current Claude Code never reads. Fresh users hit this as "the install is
+// broken" — Mnestra was wired into the wrong file.
+//
+// This module is the single source of truth for path constants and the
+// read-modify-write helpers all installer/CLI code paths use. Two physical
+// copies exist (this one + packages/stack-installer/src/mcp-config.js) so
+// each published npm package stays self-contained. The stack-installer
+// copy must stay in sync with this one — same exports, same semantics.
+
+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');
+
+// readMcpServers(filePath) → { servers, raw, missing, malformed, error }
+//
+//   servers   the .mcpServers map (always an object, never undefined)
+//   raw       the full parsed top-level object (for structure-preserving
+//             write-back). Empty object on missing/malformed.
+//   missing   true when the file doesn't exist
+//   malformed true when the file exists but JSON.parse failed
+//   error     parse error message when malformed
+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 };
+}
+
+// mergeMcpServers(currentServers, legacyServers) → merged map
+//
+// Current wins on key collision — current is the source of truth, legacy
+// is a migration source. Both inputs are tolerated as null/undefined.
+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;
+}
+
+// writeMcpServers(filePath, servers) — atomic, structure-preserving.
+//
+// If the file exists with other top-level keys (the common case for
+// ~/.claude.json), only `.mcpServers` is replaced; everything else
+// survives byte-equivalent through JSON.parse → JSON.stringify. If the
+// file is missing or empty, writes a minimal `{ mcpServers: {...} }`.
+// Atomic via tmp-and-rename. Mode 0600.
+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 */ }
+}
+
+// migrateLegacyIfPresent({ dryRun, canonicalPath, legacyPath })
+//   → { migrated, kept, wrote, canonicalPath, legacyPath, malformed }
+//
+//   migrated  array of server names copied from legacy → canonical
+//   kept      array of names that existed in both (canonical wins,
+//             legacy version skipped)
+//   wrote     true if the canonical file was written
+//   malformed { canonical?: error, legacy?: error } when either parse failed
+//
+// Idempotent: a second invocation with no new legacy entries returns
+// migrated: []. Never deletes or modifies the legacy file.
+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,
+};

package/packages/cli/src/stack.js

@@ -22,6 +22,16 @@ const SECRETS_FILE = path.join(CONFIG_DIR, 'secrets.env');
 const DEFAULT_MNESTRA_PORT = parseInt(process.env.MNESTRA_PORT || '37778', 10);
 const MNESTRA_LOG = path.join(os.tmpdir(), 'termdeck-mnestra.log');
 
+// Sprint 36: Claude Code v2.1.119+ reads MCP servers from ~/.claude.json
+// (canonical). The legacy ~/.claude/mcp.json is still accepted by older
+// versions. Detection checks BOTH; T2 migrates writes to the canonical path.
+// Exported so T2 (init-rumen, stack-installer, supabase-mcp) and any other
+// caller stays in sync — single source of truth for "where does Claude Code
+// look for MCP entries today".
+const CLAUDE_MCP_PATH_CANONICAL = path.join(HOME, '.claude.json');
+const CLAUDE_MCP_PATH_LEGACY = path.join(HOME, '.claude', 'mcp.json');
+const CLAUDE_MCP_PATHS = [CLAUDE_MCP_PATH_CANONICAL, CLAUDE_MCP_PATH_LEGACY];
+
 const ANSI = {
   green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', blue: '\x1b[34m',
   dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m',
@@ -51,6 +61,23 @@ function subNote(msg) {
   process.stdout.write(`  ${ANSI.dim}└ ${msg}${ANSI.reset}\n`);
 }
 
+// Sprint 36: scan both Claude Code MCP config paths for a Mnestra entry.
+// Returns true if either file parses and contains the substring "mnestra"
+// anywhere in its JSON (covers top-level mcpServers.mnestra AND per-project
+// blocks). Malformed JSON or missing files count as "no entry" — the hint
+// will fire and tell the user to run the installer, which is the desired
+// recovery for both states.
+function hasMnestraMcpEntry() {
+  for (const p of CLAUDE_MCP_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (JSON.stringify(j).includes('mnestra')) return true;
+    } catch (_e) { /* malformed — skip, treat as missing */ }
+  }
+  return false;
+}
+
 // ── Args ─────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -181,11 +208,32 @@ function isPidTermDeck(pid) {
   return /packages\/cli\/src\/index\.js|termdeck/.test(r.stdout || '');
 }
 
+// Liveness probe — a TermDeck that answers /api/sessions with a JSON array is
+// not stale; it's the orchestrator's live server, and killing it cascades to
+// every child PTY. On 2026-04-27 this caused two Sprint 36 server-kill
+// incidents (lane workers triggering reclaimPort against the live :3000).
+async function isTermDeckLive(port) {
+  try {
+    const j = await httpJson(`http://localhost:${port}/api/sessions`, 1500);
+    return Array.isArray(j);
+  } catch (_e) {
+    return false;
+  }
+}
+
 async function reclaimPort(port) {
   const pids = lsofPids(port);
   if (pids.length === 0) return { reclaimed: false, blockerPids: [] };
   const termdeckPids = pids.filter(isPidTermDeck);
   if (termdeckPids.length === 0) return { reclaimed: false, blockerPids: pids };
+
+  // Self-recognition guard: never kill a responsive TermDeck. Use --port to
+  // start a second instance instead.
+  if (await isTermDeckLive(port)) {
+    subNote(`TermDeck on port ${port} is live (PIDs: ${termdeckPids.join(' ')}) — not killing. Use --port <other> to start a second instance.`);
+    return { reclaimed: false, blockerPids: termdeckPids, alreadyLive: true };
+  }
+
   for (const pid of termdeckPids) {
     try { process.kill(pid, 'SIGTERM'); } catch (_e) { /* already dead */ }
   }
@@ -449,17 +497,11 @@ async function main(rawArgs) {
 
   const mnestra = await startMnestra({ skip: args.noMnestra });
 
-  // MCP config hint
-  if (mnestra.active) {
-    const mcpPath = path.join(HOME, '.claude', 'mcp.json');
-    let needsHint = !fs.existsSync(mcpPath);
-    if (!needsHint) {
-      try {
-        const j = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
-        if (!JSON.stringify(j).includes('mnestra')) needsHint = true;
-      } catch (_e) { needsHint = true; }
-    }
-    if (needsHint) subNote(`Hint: add a 'mnestra' entry to ~/.claude/mcp.json for Claude Code`);
+  // Sprint 36: MCP-absence hint. Claude Code v2.1.119+ reads from
+  // ~/.claude.json; legacy versions read ~/.claude/mcp.json. Mnestra is
+  // "wired" if EITHER file mentions it — otherwise the hint fires.
+  if (mnestra.active && !hasMnestraMcpEntry()) {
+    subNote(`TermDeck doesn't see Mnestra wired in Claude Code yet. Run: npx @jhizzard/termdeck-stack`);
   }
 
   const rumen = await checkRumen();
@@ -482,3 +524,11 @@ module.exports = function (argv) {
     return 1;
   });
 };
+
+// Sprint 36: shared MCP-config path constants. Other CLI/installer modules
+// (T2's lane: init-rumen.js, stack-installer, supabase-mcp.js) import from
+// here so the canonical-vs-legacy decision lives in exactly one file.
+module.exports.CLAUDE_MCP_PATH_CANONICAL = CLAUDE_MCP_PATH_CANONICAL;
+module.exports.CLAUDE_MCP_PATH_LEGACY = CLAUDE_MCP_PATH_LEGACY;
+module.exports.CLAUDE_MCP_PATHS = CLAUDE_MCP_PATHS;
+module.exports.hasMnestraMcpEntry = hasMnestraMcpEntry;

package/packages/client/public/app.js

@@ -25,6 +25,7 @@
     async function init() {
       // Load config
       state.config = await api('GET', '/api/config');
+      updateRagIndicator();
 
       // Populate project dropdown
       const sel = document.getElementById('promptProject');
@@ -247,6 +248,16 @@
             case 'status_broadcast':
               updateGlobalStats(msg.sessions);
               break;
+            case 'config_changed':
+              // Sprint 36 T3 Deliverable A: server-broadcast on PATCH /api/config.
+              // Each open panel WebSocket receives one copy; the handler is
+              // idempotent so multiple receipts settle the same state.
+              if (msg.config) {
+                state.config = { ...state.config, ...msg.config };
+                if (typeof renderSettingsPanel === 'function') renderSettingsPanel();
+                if (typeof updateRagIndicator === 'function') updateRagIndicator();
+              }
+              break;
           }
         } catch (err) { console.error('[client] ws message parse failed:', err); }
       };
@@ -2299,8 +2310,17 @@
       // Explicitly show the spotlight. CSS default is `display:none` so the
       // 9999px box-shadow doesn't darken the page before/after a tour runs.
       document.getElementById('tourSpotlight').style.display = 'block';
-      await ensurePanelForTour();
-      renderTourStep();
+      // Defensive cleanup: if ensurePanelForTour or renderTourStep throws
+      // after the spotlight is shown, the 9999px box-shadow stays up with no
+      // tooltip on top — that's the "dark veil" symptom users hit with no
+      // visible way out. Roll back to a clean state on any failure.
+      try {
+        await ensurePanelForTour();
+        renderTourStep();
+      } catch (err) {
+        console.error('[tour] start failed, rolling back:', err);
+        endTour();
+      }
     }
 
     function nextTourStep() {
@@ -2523,6 +2543,7 @@
             <button type="button" class="setup-close" id="setupClose" aria-label="Close">×</button>
           </header>
           <div class="setup-body">
+            <div class="setup-settings" id="setupSettings"></div>
             <div class="setup-tiers" id="setupTiers">
               <div class="setup-loading">Checking tier status…</div>
             </div>
@@ -2553,6 +2574,7 @@
       ensureSetupModal();
       document.getElementById('setupModal').classList.add('open');
       setupModalOpen = true;
+      renderSettingsPanel();
       await refreshSetupStatus();
     }
 
@@ -2562,6 +2584,96 @@
       setupModalOpen = false;
     }
 
+    // ===== Settings panel inside the setup modal (Sprint 36 T3 Deliverable A) =====
+    // Renders the writable subset of /api/config — currently just the RAG toggle.
+    // Body is mutated in place; the panel is idempotent so config_changed WS
+    // events can call it without reflow flicker.
+    function renderSettingsPanel() {
+      const el = document.getElementById('setupSettings');
+      if (!el) return;
+      const cfg = state.config || {};
+      const intent = !!cfg.ragConfigEnabled;
+      const effective = !!cfg.ragEnabled;
+      const supabaseConfigured = !!cfg.ragSupabaseConfigured;
+
+      // Mismatch: user enabled RAG in config but Supabase isn't wired → show
+      // a hint so the toggle's "ON but not pushing" state is explainable.
+      const mismatch = intent && !effective && !supabaseConfigured;
+
+      const offCopy = 'MCP-only mode. Memory tools available through Claude Code; the in-CLI <code>termdeck flashback</code> command and the hybrid search are disabled. Faster boot, slimmer surface.';
+      const onCopy = 'Enables <code>termdeck flashback</code> and the in-CLI hybrid search. Requires a Mnestra connection at boot — adds a few hundred ms to startup.';
+
+      el.innerHTML = `
+        <div class="settings-section">
+          <h4 class="settings-heading">RAG mode</h4>
+          <div class="settings-row">
+            <label class="toggle" for="settingsRagToggle">
+              <input type="checkbox" id="settingsRagToggle" ${intent ? 'checked' : ''}>
+              <span class="toggle-track" aria-hidden="true"><span class="toggle-thumb"></span></span>
+              <span class="toggle-label">${intent ? 'On' : 'Off'}</span>
+            </label>
+            <p class="settings-copy">${intent ? onCopy : offCopy}</p>
+          </div>
+          ${mismatch ? `
+            <div class="settings-warn">
+              RAG is enabled in <code>config.yaml</code> but Supabase isn't configured yet, so it isn't actually pushing.
+              Configure Tier 2 below or run <code>npx @jhizzard/termdeck-stack</code>.
+            </div>
+          ` : ''}
+        </div>
+      `;
+
+      const toggle = document.getElementById('settingsRagToggle');
+      if (toggle) {
+        toggle.addEventListener('change', async (e) => {
+          const desired = !!e.target.checked;
+          // Optimistic UI: lock the toggle while the round-trip is in flight.
+          toggle.disabled = true;
+          try {
+            const updated = await api('PATCH', '/api/config', { rag: { enabled: desired } });
+            state.config = { ...state.config, ...updated };
+            renderSettingsPanel();
+            updateRagIndicator();
+          } catch (err) {
+            console.error('[settings] PATCH /api/config failed:', err);
+            // Revert: refetch and re-render.
+            try {
+              state.config = await api('GET', '/api/config');
+              renderSettingsPanel();
+            } catch {}
+          } finally {
+            const t = document.getElementById('settingsRagToggle');
+            if (t) t.disabled = false;
+          }
+        });
+      }
+    }
+
+    // Topbar RAG indicator. The #stat-rag stub in index.html was hidden by
+    // Sprint 9 T2; re-purpose it as a live state line so users can see, at a
+    // glance, what the toggle is doing without opening Settings each time.
+    function updateRagIndicator() {
+      const el = document.getElementById('stat-rag');
+      if (!el) return;
+      const cfg = state.config || {};
+      const intent = !!cfg.ragConfigEnabled;
+      const effective = !!cfg.ragEnabled;
+      el.style.display = '';
+      if (effective) {
+        el.textContent = 'RAG · on';
+        el.className = 'topbar-stat rag-on';
+        el.title = 'Mnestra hybrid search + termdeck flashback enabled';
+      } else if (intent) {
+        el.textContent = 'RAG · pending';
+        el.className = 'topbar-stat rag-pending';
+        el.title = 'RAG enabled in config.yaml but Supabase not wired — see Settings';
+      } else {
+        el.textContent = 'RAG · mcp-only';
+        el.className = 'topbar-stat rag-off';
+        el.title = 'MCP-only mode; toggle in Settings to enable';
+      }
+    }
+
     async function refreshSetupStatus() {
       const tiersEl = document.getElementById('setupTiers');
       const subtitle = document.getElementById('setupSubtitle');