@jhizzard/termdeck 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"
@@ -11,6 +11,7 @@
     "packages/cli/templates/**",
     "packages/server/src/**",
     "packages/client/public/**",
+    "packages/stack-installer/assets/hooks/**",
     "config/config.example.yaml",
     "config/secrets.env.example",
     "config/transcript-migration.sql",

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

@@ -481,6 +481,92 @@ function writeYamlConfig(dryRun) {
   else ok();
 }
 
+// Sprint 51.6 T3 — hook upgrade gap fix.
+//
+// Codex's Sprint 51.6 GAP at 20:11 ET surfaced this: the bundled session-end
+// hook ships in `packages/stack-installer/assets/hooks/memory-session-end.js`,
+// and `npm install -g @jhizzard/termdeck@latest` lands the new bundled file
+// in node_modules — but `termdeck init --mnestra` never touched
+// ~/.claude/hooks/memory-session-end.js. The user's daily-driver kept
+// running the OLD installed copy forever. v1.0.2 closes that gap by adding
+// this refresh step to init --mnestra. The version stamp in the bundled
+// hook (// @termdeck/stack-installer-hook v<N>) gates the overwrite — only
+// strictly-newer bundled stamps trigger a refresh, so a hand-edited
+// installed file with v=current stays put.
+//
+// Backup is best-effort timestamped: `<dest>.bak.<YYYYMMDDhhmmss>`. Matches
+// the pattern Joshua already had on disk from earlier stack-installer runs.
+function refreshBundledHookIfNewer(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const HOME = require('os').homedir();
+  const HOOK_DEST = opts.destPath || path.join(HOME, '.claude', 'hooks', 'memory-session-end.js');
+  // Sprint 51.6 T4-CODEX audit 20:28 ET fix: bundled hook source must be on
+  // a path that ships in @jhizzard/termdeck's npm tarball. Root package.json
+  // includes `packages/stack-installer/assets/hooks/**` (added 51.6 T3) so
+  // this path resolves both in the monorepo and in the published tarball.
+  const HOOK_SOURCE = opts.sourcePath
+    || path.join(__dirname, '..', '..', 'stack-installer', 'assets', 'hooks', 'memory-session-end.js');
+  const SIG_RE = /@termdeck\/stack-installer-hook\s+v(\d+)/;
+  const TERMDECK_MARKERS = [
+    /TermDeck session-end memory hook/,
+    /@jhizzard\/termdeck-stack/,
+    /Vendored into ~\/\.claude\/hooks\/memory-session-end\.js by @jhizzard/i,
+  ];
+
+  function readHead(p) {
+    try { return fs.readFileSync(p, 'utf8').slice(0, 4096); }
+    catch (_) { return null; }
+  }
+  function readVersion(p) {
+    const head = readHead(p);
+    if (!head) return null;
+    const m = head.match(SIG_RE);
+    return m ? parseInt(m[1], 10) : null;
+  }
+  function looksTermdeckManaged(p) {
+    const head = readHead(p);
+    if (!head) return false;
+    return TERMDECK_MARKERS.some((m) => m.test(head));
+  }
+
+  if (!fs.existsSync(HOOK_SOURCE)) {
+    return { status: 'no-bundled', message: 'bundled hook source not found' };
+  }
+  const bundled = readVersion(HOOK_SOURCE);
+  if (bundled === null) {
+    return { status: 'bundled-unsigned', message: 'bundled hook missing version stamp; skipping refresh' };
+  }
+  if (!fs.existsSync(HOOK_DEST)) {
+    if (dryRun) return { status: 'would-install', bundled };
+    fs.mkdirSync(path.dirname(HOOK_DEST), { recursive: true });
+    fs.copyFileSync(HOOK_SOURCE, HOOK_DEST);
+    fs.chmodSync(HOOK_DEST, 0o644);
+    return { status: 'installed', bundled };
+  }
+  const installed = readVersion(HOOK_DEST);
+  if (installed !== null && installed >= bundled) {
+    return { status: 'up-to-date', installed, bundled };
+  }
+  // Sprint 51.6 T4-CODEX audit 20:23 ET safety gate: an unsigned installed
+  // hook gets refreshed ONLY if it looks TermDeck-managed (carries one of
+  // the docstring markers from a prior bundled cut). A genuinely custom
+  // user hook with no TermDeck fingerprint stays put.
+  if (installed === null && !looksTermdeckManaged(HOOK_DEST)) {
+    return {
+      status: 'custom-hook-preserved',
+      message: 'installed hook lacks TermDeck-managed markers; keeping as-is. Re-run with --force-overwrite to bypass.',
+      bundled,
+    };
+  }
+  if (dryRun) return { status: 'would-refresh', from: installed, to: bundled };
+  const stamp = new Date().toISOString().replace(/[-:T.Z]/g, '').slice(0, 14);
+  const backup = `${HOOK_DEST}.bak.${stamp}`;
+  try { fs.copyFileSync(HOOK_DEST, backup); } catch (_) { /* best-effort */ }
+  fs.copyFileSync(HOOK_SOURCE, HOOK_DEST);
+  fs.chmodSync(HOOK_DEST, 0o644);
+  return { status: 'refreshed', from: installed, to: bundled, backup };
+}
+
 function printNextSteps() {
   process.stdout.write(`
 Mnestra is configured.
@@ -578,6 +664,27 @@ async function main(argv) {
     await applyMigrations(client, false);
     await runMnestraAudit(client, inputs.projectUrl.projectRef, false);
     writeYamlConfig(false);
+    // Sprint 51.6 T3: refresh ~/.claude/hooks/memory-session-end.js when the
+    // bundled hook's version stamp is newer than the installed copy. Closes
+    // the upgrade gap where bundled fixes never reached users' machines via
+    // the standard `npm install -g @jhizzard/termdeck@latest && termdeck
+    // init --mnestra` path. Best-effort, timestamped backup, fail-soft.
+    step('Refreshing ~/.claude/hooks/memory-session-end.js (if bundled is newer)...');
+    try {
+      const r = refreshBundledHookIfNewer({ dryRun: false });
+      if (r.status === 'refreshed') {
+        ok(`refreshed v${r.from ?? 0} → v${r.to} (backup: ${path.basename(r.backup)})`);
+      } else if (r.status === 'installed') {
+        ok(`installed v${r.bundled} (no prior copy)`);
+      } else if (r.status === 'up-to-date') {
+        ok(`up-to-date (v${r.installed})`);
+      } else {
+        ok(`(${r.status}${r.message ? ': ' + r.message : ''})`);
+      }
+    } catch (err) {
+      // Don't abort init for a hook-refresh failure — log + continue.
+      process.stdout.write(`    ! hook refresh failed: ${err.message} (continuing)\n`);
+    }
     // v0.6.9: post-write outcome verification. Confirms each migration's
     // expected schema bits actually landed — including memory_items.
     // source_session_id (the v0.6.5 column whose absence cascaded into
@@ -623,3 +730,5 @@ if (require.main === module) {
 }
 
 module.exports = main;
+// Sprint 51.6 T3 — exported for tests/init-mnestra-hook-refresh.test.js.
+module.exports.refreshBundledHookIfNewer = refreshBundledHookIfNewer;

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

@@ -337,14 +337,21 @@ async function runRumenAudit(projectRef, secrets, dryRun) {
       pgClient: client,
       projectRef
     });
-    if (result.applied.length === 0 && result.errors.length === 0) {
+    if (result.applied.length === 0 && result.errors.length === 0 && result.skipped.length === 0) {
       ok(`(install up to date — ${result.probed.length} probes all present)`);
       return true;
     }
-    ok(`(probed ${result.probed.length}, applied ${result.applied.length})`);
+    ok(`(probed ${result.probed.length}, applied ${result.applied.length}, skipped ${result.skipped.length})`);
     for (const name of result.applied) {
       process.stdout.write(`    ✓ applied ${name}\n`);
     }
+    // Sprint 51.6 T3 — Bug D: surface skipped[] entries (functionSource
+    // probes that detected drift but can't auto-redeploy from audit). The
+    // wizard will redeploy below in the deployFunctions step, which fixes
+    // the drift; this print just makes the diagnosis visible.
+    for (const s of result.skipped) {
+      process.stdout.write(`    ⊘ skipped ${s.name}: ${s.reason}\n`);
+    }
     for (const e of result.errors) {
       process.stdout.write(`    ! ${e.name}: ${e.error}\n`);
     }
@@ -363,7 +370,20 @@ async function runRumenAudit(projectRef, secrets, dryRun) {
 // copied verbatim. If a future function adds a placeholder, list it here.
 const FUNCTIONS_WITH_VERSION_PLACEHOLDER = new Set(['rumen-tick']);
 
-function deployFunctions(rumenVersion, dryRun) {
+// Sprint 51.6 T3 — `projectRef` is required and passed explicitly to every
+// `supabase functions deploy` invocation as `--project-ref <ref>`. Brad's
+// 2026-05-03 jizzard-brain install hit Bug C: `supabase link --project-ref`
+// runs successfully (audit-upgrade probes confirm the link is live), but a
+// few subprocess calls later `supabase functions deploy` errors with
+// `Cannot find project ref. Have you run supabase link?` because the link
+// state persists per-cwd in supabase/config.toml and the staged-functions
+// directory has none. Threading --project-ref through dodges link-state
+// coupling entirely. The flag is supported by supabase CLI v1.x and v2.x.
+function deployFunctions(rumenVersion, projectRef, dryRun) {
+  if (!projectRef || typeof projectRef !== 'string') {
+    fail('deployFunctions: projectRef is required (Sprint 51.6 T3 — explicit --project-ref to dodge subprocess link-state isolation)');
+    return false;
+  }
   const fnNames = migrations.listRumenFunctions();
   if (fnNames.length === 0) {
     fail('no Rumen Edge Function source found in bundled setup or @jhizzard/rumen package');
@@ -390,10 +410,14 @@ function deployFunctions(rumenVersion, dryRun) {
   ok();
 
   for (const name of fnNames) {
-    step(`Running: supabase functions deploy ${name} --no-verify-jwt...`);
-    const r = runShell('supabase', ['functions', 'deploy', name, '--no-verify-jwt'], {
-      cwd: stage
-    });
+    // Sprint 51.6 T3 — `--project-ref <ref>` explicit, dodging supabase
+    // link-state subprocess isolation (Bug C, Brad's 2026-05-03 install).
+    step(`Running: supabase functions deploy ${name} --project-ref ${projectRef} --no-verify-jwt...`);
+    const r = runShell('supabase', [
+      'functions', 'deploy', name,
+      '--project-ref', projectRef,
+      '--no-verify-jwt',
+    ], { cwd: stage });
     if (!r.ok) {
       fail(`deploy of ${name} failed (exit ${r.code})`);
       return false;
@@ -997,7 +1021,7 @@ async function main(argv) {
     process.stderr.write(`  ! falling back to pinned FALLBACK_RUMEN_VERSION=${FALLBACK_RUMEN_VERSION}\n`);
   }
 
-  if (!deployFunctions(resolved.version, flags.dryRun)) return 6;
+  if (!deployFunctions(resolved.version, projectRef, flags.dryRun)) return 6;
 
   // Sprint 51.5 T3: install-time prompt for AI edge classification. Sets
   // secrets.GRAPH_LLM_CLASSIFY in-memory; the per-secret loop below picks
@@ -1042,6 +1066,9 @@ module.exports._wireAccessTokenInMcpJson = wireAccessTokenInMcpJson;
 // Sprint 43 T3: stage helper exposed so init-rumen-deploy.test.js can pin
 // the multi-function staging contract without shelling out to `supabase`.
 module.exports._stageRumenFunctions = stageRumenFunctions;
+// Sprint 51.6 T3 — exported for tests/init-rumen-project-ref.test.js so the
+// --project-ref invariant can be asserted without spawning a real shell.
+module.exports._deployFunctions = deployFunctions;
 // Sprint 51.5 T3: per-secret CLI loop, Vault SQL-Editor URL builder, and
 // Vault-secret ensure helper exposed for tests/init-rumen-secrets-per-call,
 // init-rumen-graph-llm, and init-rumen-vault-deeplinks.

package/packages/server/src/setup/audit-upgrade.js

@@ -117,6 +117,23 @@ const PROBES = Object.freeze([
       "  and column_name = 'source_agent' limit 1",
     presentWhen: 'rowReturned'
   },
+  {
+    // Sprint 51.6 T3 — bundled session-end hook (TermDeck v1.0.2+) writes
+    // the rich rag-system column set to memory_sessions; canonical engram
+    // mig 001 only ships (id, project, summary, metadata, created_at).
+    // Probe for memory_sessions.session_id (the most distinctive of the
+    // mig-017 columns) and apply mig 017 if absent. Idempotent on petvetbid
+    // where the columns are already present from hand-applied DDL.
+    name: 'memory_sessions.session_id',
+    kind: 'mnestra',
+    migrationFile: '017_memory_sessions_session_metadata.sql',
+    probeSql:
+      "select 1 as present from information_schema.columns " +
+      "where table_schema = 'public' " +
+      "  and table_name = 'memory_sessions' " +
+      "  and column_name = 'session_id' limit 1",
+    presentWhen: 'rowReturned'
+  },
   {
     name: 'rumen-tick cron schedule',
     kind: 'rumen',
@@ -134,6 +151,38 @@ const PROBES = Object.freeze([
     probeSql:
       "select 1 as present from cron.job where jobname = 'graph-inference-tick' limit 1",
     presentWhen: 'rowReturned'
+  },
+  // Sprint 51.6 T3 — Brad's Bug D: function-existence probes (cron schedule
+  // checks for jobname presence) are not enough. The deployed Edge Function
+  // SOURCE may be stale even when the cron job and function both exist.
+  // jizzard-brain on 2026-05-03: deployed rumen-tick was missing the
+  // SUPABASE_DB_URL fallback that Sprint 51.5 T1 added; cron probe said
+  // "present", source was old. The marker check below detects that drift.
+  //
+  // probeKind 'functionSource' triggers a Management API fetch instead of a
+  // pgClient.query. Bumps to skipped[] (not missing[]) when drift is
+  // detected — the corresponding "apply" is a redeploy via init-rumen's
+  // deployFunctions, not an SQL migration. The wizard shows skipped[]
+  // entries with their probeError, prompting the user to re-run init.
+  //
+  // Maintenance: bump `requiredMarker` whenever a new feature is added to
+  // the bundled function source that is meaningful enough to gate redeploys
+  // on. The marker should be a string unique to the post-change version.
+  {
+    name: 'rumen-tick deployed source has SUPABASE_DB_URL fallback',
+    kind: 'rumen',
+    probeKind: 'functionSource',
+    functionSlug: 'rumen-tick',
+    requiredMarker: "Deno.env.get('SUPABASE_DB_URL')",
+    presentWhen: 'sourceMatch'
+  },
+  {
+    name: 'graph-inference deployed source has SUPABASE_DB_URL fallback',
+    kind: 'rumen',
+    probeKind: 'functionSource',
+    functionSlug: 'graph-inference',
+    requiredMarker: "Deno.env.get('SUPABASE_DB_URL')",
+    presentWhen: 'sourceMatch'
   }
 ]);
 
@@ -147,8 +196,68 @@ function resolveMigrationFile(target, files) {
   return files.find((f) => path.basename(f) === wanted) || null;
 }
 
+// Sprint 51.6 T3 — Bug D: Edge Function source-drift detection.
+//
+// Fetches the deployed Edge Function body from Supabase Management API and
+// looks for a marker string the bundled source contains. Returns absent
+// (with probeError) when the marker is missing — meaning the deployed
+// function is older than the bundle and should be redeployed.
+//
+// Requires:
+//   - projectRef passed through from auditUpgrade()
+//   - SUPABASE_ACCESS_TOKEN in env (a personal access token, format `sbp_*`)
+// Fail-soft when either is missing — recorded as probeError, treated as
+// absent. The audit caller decides whether to surface to the user.
+async function probeFunctionSource(target, { projectRef, fetchImpl }) {
+  const fn = fetchImpl || (typeof globalThis !== 'undefined' ? globalThis.fetch : undefined);
+  if (typeof fn !== 'function') {
+    return { present: false, probeError: 'no fetch implementation available' };
+  }
+  if (!projectRef) {
+    return { present: false, probeError: 'projectRef required for functionSource probe' };
+  }
+  const accessToken = process.env.SUPABASE_ACCESS_TOKEN;
+  if (!accessToken) {
+    return {
+      present: false,
+      probeError: 'SUPABASE_ACCESS_TOKEN not set; cannot fetch deployed function body. Set the personal access token (`supabase login` writes it to ~/.supabase/access-token) to enable function-source drift detection.',
+    };
+  }
+  let res;
+  try {
+    res = await fn(
+      `https://api.supabase.com/v1/projects/${projectRef}/functions/${target.functionSlug}/body`,
+      { headers: { 'Authorization': `Bearer ${accessToken}` } }
+    );
+  } catch (err) {
+    return { present: false, probeError: `Management API fetch failed: ${err.message}` };
+  }
+  if (!res.ok) {
+    return {
+      present: false,
+      probeError: `Management API returned HTTP ${res.status} for ${target.functionSlug}/body — function may not be deployed yet, or access token lacks permission.`
+    };
+  }
+  let body;
+  try { body = await res.text(); }
+  catch (err) { return { present: false, probeError: `body decode failed: ${err.message}` }; }
+
+  if (target.requiredMarker && body.includes(target.requiredMarker)) {
+    return { present: true };
+  }
+  return {
+    present: false,
+    probeError: `deployed ${target.functionSlug} source missing marker (${JSON.stringify(target.requiredMarker)}) — re-run \`termdeck init --rumen\` to redeploy from bundled source.`,
+  };
+}
+
 // Run a probe and decide present/absent based on the probe's contract.
-async function probeOne(pgClient, target) {
+// Sprint 51.6 T3: dispatches by target.probeKind. Default is the legacy
+// pgClient.query path; 'functionSource' calls probeFunctionSource (HTTP).
+async function probeOne(pgClient, target, ctx = {}) {
+  if (target.probeKind === 'functionSource') {
+    return probeFunctionSource(target, ctx);
+  }
   let result;
   try {
     result = await pgClient.query(target.probeSql);
@@ -233,7 +342,8 @@ async function auditUpgrade({
   projectRef,
   dryRun = false,
   probes,
-  _migrations
+  _migrations,
+  _fetch
 } = {}) {
   if (!pgClient || typeof pgClient.query !== 'function') {
     throw new Error('auditUpgrade: pgClient with .query() is required');
@@ -255,11 +365,23 @@ async function auditUpgrade({
 
   for (const target of targets) {
     probed.push(target.name);
-    const probeResult = await probeOne(pgClient, target);
+    const probeResult = await probeOne(pgClient, target, { projectRef, fetchImpl: _fetch });
     if (probeResult.present) {
       present.push(target.name);
       continue;
     }
+
+    // Sprint 51.6 T3 — Bug D: functionSource probes go to skipped[] (not
+    // missing[]). The corresponding fix is a re-run of `init --rumen` which
+    // calls deployFunctions; audit-upgrade does not auto-redeploy.
+    if (target.probeKind === 'functionSource') {
+      skipped.push({
+        name: target.name,
+        reason: probeResult.probeError || 'function source drift — redeploy via init --rumen',
+      });
+      continue;
+    }
+
     missing.push(target.name);
 
     if (dryRun) continue;
@@ -297,6 +419,7 @@ module.exports = {
   // Test surface — kept exported so audit-upgrade.test.js can pin probe
   // selection / apply pathway behavior without needing a live pg client.
   _probeOne: probeOne,
+  _probeFunctionSource: probeFunctionSource,
   _applyOne: applyOne,
   _resolveMigrationFile: resolveMigrationFile
 };

package/packages/server/src/setup/mnestra-migrations/017_memory_sessions_session_metadata.sql

@@ -0,0 +1,94 @@
+-- Migration 017 — memory_sessions session metadata columns.
+--
+-- Sprint 51.6 T3 (TermDeck v1.0.2 hotfix wave). Brings the canonical engram
+-- memory_sessions schema in line with the rag-system writer's column set so
+-- TermDeck's bundled session-end hook can write a uniform shape on both
+-- fresh-canonical installs and Joshua's daily-driver petvetbid (where the
+-- columns were already added by hand when rag-system bootstrap ran).
+--
+-- Why: until v1.0.2 the bundled hook only wrote memory_items. The actual
+-- memory_sessions writer was Joshua's PRIOR personal hook at
+-- ~/Documents/Graciella/rag-system/hooks/memory-session-end.js, which spawned
+-- ~/Documents/Graciella/rag-system/src/scripts/process-session.ts; that script
+-- INSERTed memory_sessions rows with this richer column set. When the
+-- TermDeck stack-installer overwrote the personal hook on 2026-05-02, the
+-- writer disappeared and memory_sessions stopped accumulating. v1.0.2's
+-- bundled hook gains a memory_sessions write path; this migration ensures
+-- the schema it expects exists everywhere.
+--
+-- Idempotent — safe on:
+--   1. petvetbid (where these columns are already present from hand-applied
+--      DDL Joshua ran when setting up rag-system; the IF NOT EXISTS guards
+--      no-op on every column).
+--   2. Fresh canonical installs that ran migrations 001-016 only (the canonical
+--      engram set, which left memory_sessions at the minimal mig-001 shape).
+--   3. Re-runs of this migration — every operation is guarded.
+--
+-- The unique constraint on session_id is wrapped in a do-block because
+-- ADD CONSTRAINT does not support IF NOT EXISTS in PostgreSQL. Joshua's
+-- petvetbid already has the constraint as memory_sessions_session_id_key
+-- (auto-named by the rag-system bootstrap); this block detects that name
+-- and skips re-adding.
+--
+-- session_id is added NULLABLE on canonical installs even though petvetbid's
+-- existing constraint is NOT NULL. Adding NOT NULL via ALTER TABLE on a
+-- table with existing rows would fail; the bundled hook always supplies
+-- session_id at write time, so nullability is non-blocking. A future sprint
+-- may tighten to NOT NULL with a DEFAULT after a backfill pass.
+
+-- Defensive: vector extension must already be installed (migration 001
+-- requires it for memory_items.embedding). If it's somehow missing this
+-- ADD COLUMN errors, surfacing the real environment issue rather than
+-- silently skipping the embedding column.
+
+alter table public.memory_sessions
+  add column if not exists session_id text,
+  add column if not exists summary_embedding vector(1536),
+  add column if not exists started_at timestamptz,
+  add column if not exists ended_at timestamptz,
+  add column if not exists duration_minutes integer,
+  add column if not exists messages_count integer default 0,
+  add column if not exists facts_extracted integer default 0,
+  add column if not exists files_changed jsonb default '[]'::jsonb,
+  add column if not exists topics jsonb default '[]'::jsonb,
+  add column if not exists transcript_path text;
+
+-- Unique constraint on session_id. Skip if any unique constraint on
+-- (session_id) is already in place — covers both the canonical name
+-- memory_sessions_session_id_key and any alternate name from a manual
+-- ALTER TABLE Joshua may have run on petvetbid.
+do $$
+declare
+  has_unique boolean;
+begin
+  select exists (
+    select 1
+    from pg_constraint c
+    join pg_class t on t.oid = c.conrelid
+    join pg_namespace n on n.oid = t.relnamespace
+    where n.nspname = 'public'
+      and t.relname = 'memory_sessions'
+      and c.contype = 'u'
+      and (
+        select array_agg(att.attname order by att.attnum)
+        from unnest(c.conkey) as colnum
+        join pg_attribute att on att.attrelid = c.conrelid and att.attnum = colnum
+      ) = ARRAY['session_id']::name[]
+  ) into has_unique;
+
+  if not has_unique then
+    alter table public.memory_sessions
+      add constraint memory_sessions_session_id_key unique (session_id);
+  end if;
+end $$;
+
+-- HNSW index on summary_embedding for future similarity search. Idempotent.
+-- Cost on insert is negligible; cost on backfill is one-time.
+create index if not exists memory_sessions_summary_embedding_hnsw_idx
+  on public.memory_sessions using hnsw (summary_embedding vector_cosine_ops)
+  with (m = 16, ef_construction = 64);
+
+-- Helpful covering index for time-range scans (used by Flashback / rumen
+-- queries that filter by ended_at). Idempotent.
+create index if not exists memory_sessions_ended_at_idx
+  on public.memory_sessions(ended_at desc nulls last);

package/packages/stack-installer/README.md

@@ -0,0 +1,73 @@
+# @jhizzard/termdeck-stack
+
+One-command installer for the TermDeck developer memory stack.
+
+```
+npx @jhizzard/termdeck-stack
+```
+
+## What gets installed
+
+| Layer | Package | What it does |
+|-------|---------|--------------|
+| 1 | `@jhizzard/termdeck` | Browser terminal multiplexer with metadata overlays and Flashback recall toasts |
+| 2 | `@jhizzard/mnestra` | pgvector memory store + MCP server. Lights up Flashback. Provides `memory_*` tools to Claude Code, Cursor, Windsurf |
+| 3 | `@jhizzard/rumen` | Async learning loop on a Supabase Edge Function cron. Synthesizes cross-project insights |
+| 4 | `@supabase/mcp-server-supabase` | MCP that lets the TermDeck setup wizard provision your Supabase project automatically |
+
+The wizard:
+
+1. Prints the four-layer overview so you see what you're agreeing to.
+2. Detects which pieces are already on your machine.
+3. Asks which tier you want (default: 4 — full stack).
+4. Runs `npm install -g` for the missing pieces.
+5. Merges Mnestra and Supabase MCP entries into `~/.claude/mcp.json` — preserving any existing MCP servers.
+6. Prints the next steps (Supabase PAT, credentials, `termdeck` to start).
+
+## Modes
+
+```
+npx @jhizzard/termdeck-stack             # interactive
+npx @jhizzard/termdeck-stack --tier 4    # unattended
+npx @jhizzard/termdeck-stack --dry-run   # print plan, don't install
+npx @jhizzard/termdeck-stack --yes       # accept defaults (combine with --tier)
+```
+
+## Known limitations
+
+Tier 3 (Rumen) currently still requires one manual command after the
+installer finishes:
+
+```
+termdeck init --rumen
+```
+
+That command deploys the Rumen Supabase Edge Function, applies the
+migration, and installs the `pg_cron` schedule. Auto-running it from
+the meta-installer is queued — until then the wizard prints it as an
+explicit next step.
+
+## Version vs. the rest of the stack
+
+This package's version tracks the meta-installer surface, not the
+underlying packages. Each layer ships on its own release cadence:
+
+| Package | Where to look |
+|---------|---------------|
+| `@jhizzard/termdeck` | https://www.npmjs.com/package/@jhizzard/termdeck |
+| `@jhizzard/mnestra` | https://www.npmjs.com/package/@jhizzard/mnestra |
+| `@jhizzard/rumen` | https://www.npmjs.com/package/@jhizzard/rumen |
+
+The installer always pulls each layer's `latest` dist-tag, so a fresh
+`npx @jhizzard/termdeck-stack` run picks up the most recent published
+version of every layer regardless of this package's own version.
+
+## Why this exists
+
+The TermDeck stack used to be a 15-step install: provision Supabase, run six SQL migrations, mint API keys, paste them into `secrets.env`, edit `config.yaml`, install Mnestra globally, deploy Rumen, install the Supabase MCP, wire `~/.claude/mcp.json`. Most testers bounced before step 5.
+
+This installer collapses every step that's a `npm install -g` into one command, then drops the user at the doorstep of the in-browser setup wizard (which handles credentials).
+
+## License
+
+MIT