@jhizzard/termdeck 1.0.0 → 1.0.2

package/packages/server/src/setup/mnestra-migrations/016_mnestra_doctor_probes.sql

@@ -0,0 +1,117 @@
+-- Mnestra v0.4.1 — `mnestra doctor` SECURITY DEFINER probe wrappers
+--
+-- Sprint 51.5 T2 (TermDeck). Adds five SECURITY DEFINER helper functions
+-- so the `mnestra doctor` subcommand (running under the supabase
+-- service_role) can probe `cron.job_run_details`, `cron.job`, `vault.secrets`,
+-- `information_schema.columns`, and `pg_proc` without granting raw schema
+-- access to service_role.
+--
+-- Why SECURITY DEFINER: by default `cron.*` and `vault.*` are owned by
+-- the `postgres` role and unreadable from service_role. The classical
+-- alternative is to `grant usage on schema cron to service_role; grant
+-- select on cron.job_run_details to service_role; …` — broader privilege
+-- expansion than this lane needs. SECURITY DEFINER lets us read exactly
+-- what the doctor needs without exposing the entire cron/vault surface.
+--
+-- Idempotent: every function uses CREATE OR REPLACE; every GRANT is
+-- safe to re-run. No data mutation. Safe to re-apply on every install.
+
+-- ── 1. cron.job_run_details lookup ───────────────────────────────────────
+--
+-- Returns the most recent N runs of a named cron job, projecting only
+-- the columns the doctor needs (status, start/end timestamps, return
+-- message). The doctor parses `return_message` for the rumen-tick /
+-- graph-inference all-zeros pattern.
+
+create or replace function mnestra_doctor_cron_runs(
+  p_jobname text,
+  p_limit   int default 10
+)
+returns table (
+  jobname        text,
+  status         text,
+  start_time     timestamptz,
+  end_time       timestamptz,
+  return_message text
+)
+language sql
+security definer
+set search_path = cron, public
+as $$
+  select j.jobname, d.status, d.start_time, d.end_time, d.return_message
+  from cron.job_run_details d
+  join cron.job j on j.jobid = d.jobid
+  where j.jobname = p_jobname
+  order by d.start_time desc
+  limit greatest(coalesce(p_limit, 10), 1);
+$$;
+
+-- ── 2. column existence probe (public schema only) ───────────────────────
+
+create or replace function mnestra_doctor_column_exists(
+  p_table  text,
+  p_column text
+)
+returns boolean
+language sql
+security definer
+set search_path = public
+as $$
+  select exists (
+    select 1
+    from information_schema.columns
+    where table_schema = 'public'
+      and table_name   = p_table
+      and column_name  = p_column
+  );
+$$;
+
+-- ── 3. RPC / function existence probe ────────────────────────────────────
+
+create or replace function mnestra_doctor_rpc_exists(p_name text)
+returns boolean
+language sql
+security definer
+set search_path = public
+as $$
+  select exists (
+    select 1
+    from pg_proc p
+    join pg_namespace n on n.oid = p.pronamespace
+    where p.proname = p_name
+      and n.nspname = 'public'
+  );
+$$;
+
+-- ── 4. cron.job existence probe (does the named job exist at all) ───────
+
+create or replace function mnestra_doctor_cron_job_exists(p_jobname text)
+returns boolean
+language sql
+security definer
+set search_path = cron, public
+as $$
+  select exists (select 1 from cron.job where jobname = p_jobname);
+$$;
+
+-- ── 5. vault.secrets existence probe (no value disclosure) ──────────────
+--
+-- Existence-only — never returns the secret value. The doctor only needs
+-- to know whether the named vault entry was created during stack install.
+
+create or replace function mnestra_doctor_vault_secret_exists(p_name text)
+returns boolean
+language sql
+security definer
+set search_path = vault, public
+as $$
+  select exists (select 1 from vault.secrets where name = p_name);
+$$;
+
+-- ── 6. Grants ────────────────────────────────────────────────────────────
+
+grant execute on function mnestra_doctor_cron_runs(text, int)             to service_role;
+grant execute on function mnestra_doctor_column_exists(text, text)        to service_role;
+grant execute on function mnestra_doctor_rpc_exists(text)                 to service_role;
+grant execute on function mnestra_doctor_cron_job_exists(text)            to service_role;
+grant execute on function mnestra_doctor_vault_secret_exists(text)        to service_role;

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/server/src/setup/preconditions.js

@@ -52,6 +52,23 @@ function extensionsDashboardUrl(secrets) {
   return `https://supabase.com/dashboard/project/${parsed.projectRef}/database/extensions`;
 }
 
+// Sprint 51.5 T3: Build a SQL-Editor deeplink that pre-fills a
+// vault.create_secret() call. Used when the audit's vault probe finds the
+// secret missing and the wizard's auto-apply step (init-rumen.js
+// `ensureVaultSecrets`) was unable to create it via pgRunner. The Vault
+// dashboard panel was quietly removed/relocated in current Supabase UIs
+// (Brad 2026-05-03 takeaway #2; INSTALLER-PITFALLS.md Class B), so SQL
+// Editor is the working manual surface.
+function vaultSqlEditorUrl(secrets, secretName, secretValue) {
+  if (!secrets || !secrets.SUPABASE_URL) return null;
+  const parsed = supabaseUrlHelper.parseProjectUrl(secrets.SUPABASE_URL);
+  if (!parsed.ok) return null;
+  const value = String(secretValue == null ? '' : secretValue).replace(/'/g, "''");
+  const name = String(secretName == null ? '' : secretName).replace(/'/g, "''");
+  const sql = `select vault.create_secret('${value}', '${name}');`;
+  return `https://supabase.com/dashboard/project/${parsed.projectRef}/sql/new?content=${encodeURIComponent(sql)}`;
+}
+
 // Render a single gap into 2-3 lines of CLI output (one indented hint per
 // non-empty `hint` line). Format aligned with the rest of the wizard's
 // step lines.
@@ -206,14 +223,28 @@ async function auditRumenPreconditions({ secrets, env, _pgClient } = {}) {
           'If permission is denied, the Vault is not accessible to this connection — double-check secrets.env.'
       });
     } else if (!vault.ok) {
+      // Sprint 51.5 T3: the Supabase Vault dashboard panel was quietly removed
+      // / relocated in current Supabase UIs (Brad 2026-05-03 takeaway #2;
+      // INSTALLER-PITFALLS.md Class B). The wizard's `ensureVaultSecrets`
+      // step (init-rumen.js) auto-creates this key via pgRunner when the
+      // user's connection has vault.create_secret privileges; this hint only
+      // fires when auto-apply also failed, in which case the SQL Editor is
+      // the working manual surface. Build a project-specific deeplink when
+      // we can derive the project ref so the user gets one click instead of
+      // a "find the SQL Editor yourself" instruction.
+      const sqlEditorUrl = vaultSqlEditorUrl(secrets, 'rumen_service_role_key',
+        '<paste your service_role JWT from Project Settings → API>');
+      const sqlEditorLine = sqlEditorUrl
+        ? `  Open: ${sqlEditorUrl}\n  Replace the placeholder with your service_role key from Project Settings → API, then click Run.`
+        : '  Open the Supabase SQL Editor and run:\n' +
+          "    select vault.create_secret('<service_role JWT>', 'rumen_service_role_key');";
       gaps.push({
         key: 'rumen_service_role_key',
         message: 'Vault secret "rumen_service_role_key" is missing',
         hint:
-          'Create it in the Supabase dashboard:\n' +
-          '  Project Settings → Vault → New secret\n' +
-          '  Name: rumen_service_role_key  (exact, case-sensitive)\n' +
-          '  Value: your service_role key from Project Settings → API\n' +
+          "The wizard tries to auto-create this via vault.create_secret() and only surfaces this hint when auto-apply also failed.\n" +
+          'Create it manually via the SQL Editor (the Vault dashboard panel was removed in current Supabase UIs):\n' +
+          sqlEditorLine + '\n' +
           '(The pg_cron schedule calls the Edge Function with this key as the bearer token.)'
       });
     }
@@ -384,6 +415,7 @@ module.exports = {
   printAuditReport,
   printVerifyReport,
   extensionsDashboardUrl,
+  vaultSqlEditorUrl,
   // Test surface
   _probeSupabaseAuth: probeSupabaseAuth,
   _safeQuery: safeQuery

package/packages/server/src/setup/rumen/functions/graph-inference/index.ts

@@ -343,9 +343,13 @@ export async function runGraphInference(sql: Sql): Promise<InferenceSummary> {
 }
 
 serve(async (_req: Request) => {
-  const url = Deno.env.get('DATABASE_URL');
+  // Supabase Edge Runtime auto-injects SUPABASE_DB_URL as a built-in env var.
+  // Falling back to it removes one whole category of "where do I get the DB
+  // connection string" from the install wizard. Brad surfaced this 2026-05-03
+  // after hand-patching all four of his deployed copies.
+  const url = Deno.env.get('DATABASE_URL') ?? Deno.env.get('SUPABASE_DB_URL');
   if (!url) {
-    console.error('[graph-inference] DATABASE_URL not set in Edge Function secrets');
+    console.error('[graph-inference] DATABASE_URL / SUPABASE_DB_URL not set in Edge Function secrets');
     return new Response(
       JSON.stringify({ ok: false, error: 'DATABASE_URL not set' }),
       { status: 500, headers: { 'Content-Type': 'application/json' } },

package/packages/server/src/setup/rumen/functions/rumen-tick/index.ts

@@ -31,9 +31,13 @@ import { runRumenJob, createPoolFromUrl } from 'npm:@jhizzard/rumen@__RUMEN_VERS
 declare const Deno: { env: { get: (k: string) => string | undefined } };
 
 serve(async (_req: Request) => {
-  const url = Deno.env.get('DATABASE_URL');
+  // Supabase Edge Runtime auto-injects SUPABASE_DB_URL as a built-in env var.
+  // Falling back to it removes one whole category of "where do I get the DB
+  // connection string" from the install wizard. Brad surfaced this 2026-05-03
+  // after hand-patching all four of his deployed copies.
+  const url = Deno.env.get('DATABASE_URL') ?? Deno.env.get('SUPABASE_DB_URL');
   if (!url) {
-    console.error('[rumen] DATABASE_URL not set in Edge Function secrets');
+    console.error('[rumen] DATABASE_URL / SUPABASE_DB_URL not set in Edge Function secrets');
     return new Response(
       JSON.stringify({
         ok: false,

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

package/packages/stack-installer/assets/hooks/README.md

@@ -0,0 +1,172 @@
+# 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_ROLE_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_ROLE_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.
+
+**From v0.17.0**, the TermDeck server also merges
+`~/.termdeck/secrets.env` directly into every PTY-spawned shell — so any
+Claude Code panel launched inside TermDeck inherits `SUPABASE_URL` /
+`SUPABASE_SERVICE_ROLE_KEY` / `OPENAI_API_KEY` even if the user's
+parent shell never sourced the file. Concrete values in
+`process.env` still win (parent-shell env takes precedence over the
+file fallback). Standalone Claude Code launches outside TermDeck
+still rely on the parent shell having sourced the file — for those,
+the wizard can offer a one-line `~/.zshrc` source addition.
+
+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`.
+
+### Order matters: most-specific-first
+
+`detectProject(cwd)` returns the **first** matching entry. If a deep
+project lives under a broader parent dir, the deep pattern must come
+first or the parent will swallow it. This bug bit the TermDeck team in
+Sprint 41 — every cwd under a `ChopinNashville/` parent was getting
+tagged `chopin-nashville` because the parent-dir pattern came before
+each sub-project's specific pattern.
+
+Example showing the right ordering:
+
+```js
+const PROJECT_MAP = [
+  // Specific code projects under a common parent — these MUST appear
+  // before the parent-dir catch-all below.
+  { pattern: /\/MyOrg\/SideProjects\/widget-app/i,  project: 'widget-app' },
+  { pattern: /\/MyOrg\/SideProjects\/scheduler/i,   project: 'scheduler' },
+  { pattern: /\/MyOrg\/2026\/festival\/podium/i,    project: 'podium' },
+  { pattern: /\/MyOrg\/2026\/festival/i,            project: 'festival' },
+
+  // Other top-level projects.
+  { pattern: /\/PVB\//i,                            project: 'pvb' },
+
+  // Catch-all for the parent dir — only matches when no specific
+  // project above matched first.
+  { pattern: /\/MyOrg(\/|$)/i,                      project: 'myorg-ops' },
+];
+```
+
+For a worked example of a real production taxonomy (with explicit
+priority ordering, alias documentation, and a structural-invariant
+test), see [`docs/PROJECT-TAXONOMY.md`](https://github.com/jhizzard/termdeck/blob/main/docs/PROJECT-TAXONOMY.md)
+in the TermDeck repo.
+
+### Other rules
+
+- 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).
+- Anything that doesn't match falls through to `'global'`.
+- Adopt the module-export contract (`module.exports = { detectProject, PROJECT_MAP }`)
+  if you want to write a unit test that exercises your taxonomy. The
+  bundled hook already does this; if you copy-paste a custom hook,
+  preserve the `if (require.main === module)` guard around the stdin
+  reader so `require()` doesn't hang.
+
+## 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.