@pcircle/memesh 4.4.0 → 4.5.1

package/dist/core/doctor.js

@@ -3,15 +3,18 @@ import path from 'path';
 import { createHash } from 'crypto';
 import { createRequire } from 'module';
 import { pathToFileURL } from 'url';
-import { detectCapabilities, getConfigPath } from './config.js';
-import { embedText, isOnnxModelCached } from './embedder.js';
+import { detectCapabilities, getConfigPath, isTranscriptMiningEnabled, readConfig } from './config.js';
+import { embedText } from './embedder.js';
 import { probeProvider } from './llm-validator.js';
 import { openDatabase, closeDatabase, getPendingReindexInfo, isDatabaseOpen } from '../db.js';
 import { getUpdateCheck } from './version-check.js';
 import { getCurrentInstallChannel, getInstallChannelSupport } from './install-channel.js';
 import { getInstallRecord } from './install-id.js';
-import { getDbPath, memeshDir } from './paths.js';
+import { getDbPath, memeshDir, getProjectName } from './paths.js';
+import { lastTranscriptMineAt } from './transcript-source.js';
 import { UNSPACED_SCRIPT_GLOB_RUN3 } from '../storage/fts-index.js';
+import { MemeshDatabase } from '../storage/sqlite.js';
+import { AUTO_CAPTURE_TAG } from './types.js';
 const EMBEDDING_PROBE_TIMEOUT_MS = 15000;
 const EXPECTED_HOOK_TYPES = ['PreToolUse', 'SessionStart', 'PostToolUse', 'Stop', 'PreCompact'];
 const LOCALE_README_FILES = [
@@ -53,7 +56,7 @@ function inspectLocaleReadmeParity(packageRoot, existsSyncImpl, readFileSyncImpl
         englishCount = countH2Headings(readFileSyncImpl(englishPath, 'utf8'));
     }
     catch (err) {
-        return createCheck('readme_locale_parity', 'README locale parity', 'warn', `Could not read README.md: ${err instanceof Error ? err.message : String(err)}`);
+        return createCheck('readme_locale_parity', 'README locale parity', 'warn', `Could not read README.md: ${err instanceof Error ? err.message : String(err)}`, undefined, { code: 'readme-parity.unreadable', params: { detail: err instanceof Error ? err.message : String(err) } });
     }
     const missing = [];
     const drift = [];
@@ -86,13 +89,13 @@ function inspectLocaleReadmeParity(packageRoot, existsSyncImpl, readFileSyncImpl
             .join(', ');
         parts.push(`H2 count drift (English=${englishCount}): ${driftDetail}`);
     }
-    return createCheck('readme_locale_parity', 'README locale parity', 'warn', parts.join('; '), `Re-sync the listed READMEs against README.md so section structure matches (±${LOCALE_H2_TOLERANCE} H2 tolerated to absorb translation collapse).`);
+    return createCheck('readme_locale_parity', 'README locale parity', 'warn', parts.join('; '), `Re-sync the listed READMEs against README.md so section structure matches (±${LOCALE_H2_TOLERANCE} H2 tolerated to absorb translation collapse).`, { code: 'readme-parity.drift', params: { detail: parts.join('; '), tolerance: LOCALE_H2_TOLERANCE } });
 }
 function resolveDatabasePath() {
     return getDbPath();
 }
-function createCheck(id, label, status, summary, fix) {
-    return { id, label, status, summary, fix };
+function createCheck(id, label, status, summary, fix, i18n) {
+    return { id, label, status, summary, fix, code: i18n?.code, params: i18n?.params };
 }
 function createInfo(id, label, summary, fix) {
     return { id, label, status: 'pass', summary, fix, informational: true };
@@ -120,24 +123,32 @@ function inspectConfigFile(existsSyncImpl, readFileSyncImpl, getConfigPathImpl)
     }
     const parsed = parseJsonFile(configPath, readFileSyncImpl);
     if (!parsed.ok) {
-        return createCheck('config', 'Config', 'fail', `Config file is invalid JSON at ${configPath}.`, `Fix or remove ${configPath}, then run \`memesh config list\` to confirm it loads cleanly.`);
+        return createCheck('config', 'Config', 'fail', `Config file is invalid JSON at ${configPath}.`, `Fix or remove ${configPath}, then run \`memesh config list\` to confirm it loads cleanly.`, { code: 'config.invalid-json', params: { path: configPath } });
     }
     return createCheck('config', 'Config', 'pass', `Config file is readable at ${configPath}.`);
 }
 function inspectMcpConfig(packageRoot, existsSyncImpl, readFileSyncImpl) {
     const mcpPath = path.join(packageRoot, '.mcp.json');
     if (!existsSyncImpl(mcpPath)) {
-        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json is missing.', 'Restore `.mcp.json` from the package or reinstall MeMesh.');
+        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json is missing.', 'Restore `.mcp.json` from the package or reinstall MeMesh.', { code: 'mcp-config.missing' });
     }
     const parsed = parseJsonFile(mcpPath, readFileSyncImpl);
     if (!parsed.ok) {
-        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json is not valid JSON.', `Fix ${mcpPath} so Claude Code can read the MCP server definition.`);
+        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json is not valid JSON.', `Fix ${mcpPath} so Claude Code can read the MCP server definition.`, { code: 'mcp-config.invalid-json', params: { path: mcpPath } });
     }
     const server = parsed.value.mcpServers?.memesh;
     if (!server || typeof server.command !== 'string') {
-        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json does not define a usable `memesh` MCP server entry.', 'Reinstall MeMesh or restore the `mcpServers.memesh` entry in `.mcp.json`.');
+        return createCheck('mcp-config', 'MCP config', 'fail', '.mcp.json does not define a usable `memesh` MCP server entry.', 'Reinstall MeMesh or restore the `mcpServers.memesh` entry in `.mcp.json`.', { code: 'mcp-config.no-entry' });
     }
-    return createCheck('mcp-config', 'MCP config', 'pass', '.mcp.json is present and defines the memesh MCP server.');
+    const args = Array.isArray(server.args) ? server.args : [];
+    const entry = typeof args[0] === 'string' ? args[0] : null;
+    if (entry) {
+        const resolved = path.resolve(entry.replaceAll('${CLAUDE_PLUGIN_ROOT}', packageRoot));
+        if (!existsSyncImpl(resolved)) {
+            return createCheck('mcp-config', 'MCP config', 'fail', `.mcp.json starts \`${entry}\`, and that file is not in this install — so every memesh MCP tool fails to start.`, 'Reinstall MeMesh; if you edited `.mcp.json` by hand, point it back at `${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js`.', { code: 'mcp-config.entry-missing', params: { entry, resolved } });
+        }
+    }
+    return createCheck('mcp-config', 'MCP config', 'pass', '.mcp.json is present, defines the memesh MCP server, and the script it starts exists.');
 }
 function extractHookScriptPaths(hooksConfig, packageRoot) {
     const hooks = hooksConfig.hooks;
@@ -160,32 +171,32 @@ function inspectHooksConfig(packageRoot, platform, existsSyncImpl, readFileSyncI
     const hooksPath = path.join(packageRoot, 'hooks', 'hooks.json');
     if (!existsSyncImpl(hooksPath)) {
         return [
-            createCheck('hooks-config', 'Hooks config', 'fail', 'hooks/hooks.json is missing.', 'Restore `hooks/hooks.json` from the package or reinstall MeMesh.'),
+            createCheck('hooks-config', 'Hooks config', 'fail', 'hooks/hooks.json is missing.', 'Restore `hooks/hooks.json` from the package or reinstall MeMesh.', { code: 'hooks-config.missing' }),
         ];
     }
     const parsed = parseJsonFile(hooksPath, readFileSyncImpl);
     if (!parsed.ok) {
         return [
-            createCheck('hooks-config', 'Hooks config', 'fail', 'hooks/hooks.json is not valid JSON.', `Fix ${hooksPath} so Claude Code can load the hook definitions.`),
+            createCheck('hooks-config', 'Hooks config', 'fail', 'hooks/hooks.json is not valid JSON.', `Fix ${hooksPath} so Claude Code can load the hook definitions.`, { code: 'hooks-config.invalid-json', params: { path: hooksPath } }),
         ];
     }
     const hookTypes = Object.keys(parsed.value.hooks ?? {});
     const missingTypes = EXPECTED_HOOK_TYPES.filter((type) => !hookTypes.includes(type));
     const configCheck = missingTypes.length > 0
-        ? createCheck('hooks-config', 'Hooks config', 'fail', `hooks/hooks.json is missing expected hook types: ${missingTypes.join(', ')}.`, 'Restore the shipped hook configuration or reinstall MeMesh.')
+        ? createCheck('hooks-config', 'Hooks config', 'fail', `hooks/hooks.json is missing expected hook types: ${missingTypes.join(', ')}.`, 'Restore the shipped hook configuration or reinstall MeMesh.', { code: 'hooks-config.missing-types', params: { types: missingTypes.join(', ') } })
         : createCheck('hooks-config', 'Hooks config', 'pass', `hooks/hooks.json is present with ${hookTypes.length} hook types configured.`);
     const scriptPaths = extractHookScriptPaths(parsed.value, packageRoot);
     if (scriptPaths.length === 0) {
         return [
             configCheck,
-            createCheck('hook-scripts', 'Hook scripts', 'fail', 'hooks/hooks.json parsed, but yields zero hook script commands — hooks can never fire.', 'Restore the shipped hook configuration or reinstall MeMesh.'),
+            createCheck('hook-scripts', 'Hook scripts', 'fail', 'hooks/hooks.json parsed, but yields zero hook script commands — hooks can never fire.', 'Restore the shipped hook configuration or reinstall MeMesh.', { code: 'hook-scripts.none' }),
         ];
     }
     const missingScripts = scriptPaths.filter((scriptPath) => !existsSyncImpl(scriptPath));
     if (missingScripts.length > 0) {
         return [
             configCheck,
-            createCheck('hook-scripts', 'Hook scripts', 'fail', `Missing hook scripts: ${missingScripts.map((entry) => path.relative(packageRoot, entry)).join(', ')}.`, 'Restore the missing files from the package or reinstall MeMesh.'),
+            createCheck('hook-scripts', 'Hook scripts', 'fail', `Missing hook scripts: ${missingScripts.map((entry) => path.relative(packageRoot, entry)).join(', ')}.`, 'Restore the missing files from the package or reinstall MeMesh.', { code: 'hook-scripts.missing', params: { files: missingScripts.map((entry) => path.relative(packageRoot, entry)).join(', ') } }),
         ];
     }
     if (platform !== 'win32') {
@@ -196,7 +207,7 @@ function inspectHooksConfig(packageRoot, platform, existsSyncImpl, readFileSyncI
         if (nonExecutable.length > 0) {
             return [
                 configCheck,
-                createCheck('hook-scripts', 'Hook scripts', 'fail', `Hook scripts are not executable: ${nonExecutable.map((entry) => path.relative(packageRoot, entry)).join(', ')}.`, 'Run `npm run build` from the repo checkout or `chmod +x scripts/hooks/*.js` for a local repair.'),
+                createCheck('hook-scripts', 'Hook scripts', 'fail', `Hook scripts are not executable: ${nonExecutable.map((entry) => path.relative(packageRoot, entry)).join(', ')}.`, 'Run `npm run build` from the repo checkout or `chmod +x scripts/hooks/*.js` for a local repair.', { code: 'hook-scripts.not-executable', params: { files: nonExecutable.map((entry) => path.relative(packageRoot, entry)).join(', ') } }),
             ];
         }
     }
@@ -205,84 +216,170 @@ function inspectHooksConfig(packageRoot, platform, existsSyncImpl, readFileSyncI
         createCheck('hook-scripts', 'Hook scripts', 'pass', `All ${scriptPaths.length} hook scripts are present${platform === 'win32' ? '' : ' and executable'}.`),
     ];
 }
-function inspectHookWiring(existsSyncImpl, readFileSyncImpl, memeshDir, packageRoot) {
+function inspectHookWiring(existsSyncImpl, readFileSyncImpl, memeshDir, installChannel) {
     const markerPath = path.join(memeshDir, 'install-hooks.json');
     if (!existsSyncImpl(markerPath)) {
-        if (packageRoot) {
-            const pluginManifest = path.join(packageRoot, '.claude-plugin', 'plugin.json');
-            if (existsSyncImpl(pluginManifest)) {
-                return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'pass', 'Wired via Claude Code plugin runtime (.claude-plugin/plugin.json present). The install-hooks marker is not used on this install path.');
-            }
+        if (installChannel === 'plugin-marketplace') {
+            return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'pass', 'Wired via the Claude Code plugin runtime (this is a plugin-marketplace install). The install-hooks marker is not used on this install path.');
         }
-        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'warn', 'No install-hooks marker found. memesh\'s session-summary, pre-edit-recall, and other hooks may not be firing for Claude Code sessions — the auto-capture / lesson-generation flow is silent without them.', 'Run `memesh install-hooks` to wire memesh into ~/.claude/settings.json (one-time setup). Then `memesh doctor` to confirm.');
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'warn', 'memesh is not connected to Claude Code yet, so nothing gets remembered automatically from your sessions.', 'Run `memesh install-hooks` once to connect it, then `memesh doctor` to confirm.', { code: 'hook-wiring.no-marker' });
     }
     const parsed = parseJsonFile(markerPath, readFileSyncImpl);
     if (!parsed.ok) {
-        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'warn', `install-hooks marker at ${markerPath} is unreadable.`, 'Re-run `memesh install-hooks` to refresh the marker.');
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'warn', `install-hooks marker at ${markerPath} is unreadable.`, 'Re-run `memesh install-hooks` to refresh the marker.', { code: 'hook-wiring.marker-unreadable', params: { path: markerPath } });
     }
     const marker = parsed.value;
     if (typeof marker.settings_path !== 'string') {
-        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'warn', 'install-hooks marker is malformed (missing settings_path).', 'Re-run `memesh install-hooks`.');
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'warn', 'install-hooks marker is malformed (missing settings_path).', 'Re-run `memesh install-hooks`.', { code: 'hook-wiring.marker-malformed' });
     }
     if (!existsSyncImpl(marker.settings_path)) {
-        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `Marker recorded settings at ${marker.settings_path} but the file no longer exists. Hooks are not wired.`, 'Re-run `memesh install-hooks`.');
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `Marker recorded settings at ${marker.settings_path} but the file no longer exists. Hooks are not wired.`, 'Re-run `memesh install-hooks`.', { code: 'hook-wiring.settings-missing', params: { path: String(marker.settings_path) } });
     }
     const settingsParsed = parseJsonFile(marker.settings_path, readFileSyncImpl);
     if (!settingsParsed.ok) {
-        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `${marker.settings_path} is no longer valid JSON.`, 'Restore from your ~/.claude backups or re-create with `memesh install-hooks`.');
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `${marker.settings_path} is no longer valid JSON.`, 'Restore from your ~/.claude backups or re-create with `memesh install-hooks`.', { code: 'hook-wiring.settings-invalid', params: { path: String(marker.settings_path) } });
     }
+    const CAPTURE_EVENTS = new Set(['Stop', 'PostToolUse', 'PreCompact']);
     const hooks = settingsParsed.value.hooks;
     let hasMemeshHook = false;
+    let hasCaptureHook = false;
+    let missingScript = null;
     if (hooks && typeof hooks === 'object') {
-        for (const entries of Object.values(hooks)) {
+        for (const [event, entries] of Object.entries(hooks)) {
             if (!Array.isArray(entries))
                 continue;
             for (const entry of entries) {
                 const cmds = entry.hooks;
                 if (!Array.isArray(cmds))
                     continue;
-                if (cmds.some((c) => c._memesh === true)) {
+                for (const c of cmds) {
+                    const cmd = c;
+                    if (cmd._memesh !== true)
+                        continue;
                     hasMemeshHook = true;
-                    break;
+                    if (CAPTURE_EVENTS.has(event))
+                        hasCaptureHook = true;
+                    if (missingScript === null && typeof cmd.command === 'string'
+                        && path.isAbsolute(cmd.command) && !existsSyncImpl(cmd.command)) {
+                        missingScript = cmd.command;
+                    }
                 }
             }
-            if (hasMemeshHook)
-                break;
         }
     }
+    if (missingScript !== null) {
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `A wired memesh hook points at ${missingScript}, which no longer exists — the agent invokes a missing file on every matching event. This is usually residue from an upgrade that retired the hook.`, 'Run `memesh install-hooks` to re-wire (it now removes retired entries), then restart your agent.', { code: 'hook-wiring.script-missing', params: { path: missingScript } });
+    }
     if (!hasMemeshHook) {
-        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `Marker recorded a memesh install at ${marker.settings_path}, but no _memesh:true hook entries are present anymore. Settings drifted (manual edit?) or memesh was uninstalled out-of-band.`, 'Re-run `memesh install-hooks` to re-wire.');
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `Marker recorded a memesh install at ${marker.settings_path}, but no _memesh:true hook entries are present anymore. Settings drifted (manual edit?) or memesh was uninstalled out-of-band.`, 'Re-run `memesh install-hooks` to re-wire.', { code: 'hook-wiring.entries-removed', params: { path: String(marker.settings_path) } });
     }
     if (typeof marker.plugin_root === 'string' && !existsSyncImpl(marker.plugin_root)) {
-        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `Hook commands point at ${marker.plugin_root}, which no longer exists (likely after an npm-global path change).`, 'Re-run `memesh install-hooks` to refresh paths.');
+        return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'fail', `Hook commands point at ${marker.plugin_root}, which no longer exists (likely after an npm-global path change).`, 'Re-run `memesh install-hooks` to refresh paths.', { code: 'hook-wiring.root-moved', params: { path: String(marker.plugin_root) } });
     }
-    return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'pass', `Wired in ${marker.settings_path} (scope: ${marker.scope ?? 'user'}, version: ${marker.version ?? 'unknown'}).`);
+    return createCheck('hook-wiring', 'Hooks wired into Claude Code', 'pass', `Wired in ${marker.settings_path} (scope: ${marker.scope ?? 'user'}, version: ${marker.version ?? 'unknown'}).`, undefined, { params: { captureWired: hasCaptureHook ? 1 : 0 } });
 }
-function inspectHookActivity(openDatabaseImpl, closeDatabaseImpl, existsSyncImpl = fs.existsSync, statSyncImpl = fs.statSync) {
+function inspectHookActivity(openDatabaseImpl, closeDatabaseImpl, existsSyncImpl = fs.existsSync, statSyncImpl = fs.statSync, wiringPresent = true) {
+    const TITLE = 'Hook activity';
+    const captureOff = autoCaptureOffSource();
+    if (captureOff === 'config') {
+        return createCheck('hook-activity', TITLE, 'pass', 'Automatic capture is turned off (config autoCapture: false) — deliberately, so hook silence is expected. Re-enable it to resume capturing sessions.', undefined, { code: 'hook-activity.disabled' });
+    }
+    if (captureOff === 'env') {
+        return createCheck('hook-activity', TITLE, 'pass', 'Automatic capture is turned off by MEMESH_AUTO_CAPTURE=false in this shell\'s environment. Doctor can only see its own environment — if your agent runs without this variable, capture there is unaffected.', undefined, { code: 'hook-activity.disabled-env' });
+    }
     let db = null;
     try {
         db = openDatabaseImpl();
-        const row = db.prepare(`SELECT COUNT(*) as c FROM entities
-       WHERE type IN ('session-insight', 'session-summary', 'commit', 'lesson_learned')
-         AND created_at > datetime('now', '-24 hours')`).get();
-        const count = row?.c ?? 0;
-        if (count === 0) {
-            const markerPath = path.join(memeshDir(), 'install-hooks.json');
-            if (existsSyncImpl(markerPath)) {
-                try {
-                    const ageMs = Date.now() - statSyncImpl(markerPath).mtimeMs;
-                    if (ageMs < 24 * 60 * 60 * 1000) {
-                        return createCheck('hook-activity', 'Hook activity (last 24h)', 'pass', 'Hooks wired recently — no captureable sessions yet (this is normal for a fresh install).');
-                    }
+        const hookRunsTablePresent = !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'hook_runs'").get();
+        const rows = hookRunsTablePresent
+            ? db.prepare(`SELECT hook, last_run_at FROM hook_runs`).all()
+            : [];
+        const captured = db.prepare(`SELECT COUNT(DISTINCT e.id) as c FROM entities e
+       JOIN tags t ON t.entity_id = e.id
+       WHERE t.tag = ?
+         AND e.created_at > datetime('now', '-24 hours')`).get(AUTO_CAPTURE_TAG)?.c ?? 0;
+        const since = db.prepare("SELECT value FROM memesh_metadata WHERE key = 'hook_runs_since'").get()?.value;
+        const measuringHours = since !== undefined ? hoursSince(since) : null;
+        const SKEW_TOLERANCE_H = 5 / 60;
+        const KNOWN_HOOKS = new Set(['session-summary', 'post-commit', 'pre-compact']);
+        const ages = new Map();
+        for (const r of rows) {
+            if (!KNOWN_HOOKS.has(r.hook))
+                continue;
+            const age = hoursSince(r.last_run_at);
+            ages.set(r.hook, age !== null && age >= -SKEW_TOLERANCE_H ? Math.max(age, 0) : null);
+        }
+        if (ages.size > 0) {
+            const capturedTail = captured > 0
+                ? `${captured} memor${captured === 1 ? 'y' : 'ies'} captured in the last 24h.`
+                : 'Nothing was worth saving in that time, which is normal — the loop still ran.';
+            const staleUnknown = (hook) => createCheck('hook-activity', TITLE, 'fail', `The ${hook} hook's last-run timestamp cannot be read (corrupt, or stamped by a machine with a wrong clock). ` +
+                'Capture health is unknown, which is not the same as healthy.', 'End one work session, then re-run `memesh doctor` — a fresh run overwrites the bad timestamp.', { code: 'hook-activity.stale-unknown', params: { hook } });
+            const stale = (hook, age, status) => createCheck('hook-activity', TITLE, status, `The ${hook} hook last ran ${formatHoursAgo(Math.ceil(age))}. ` +
+                'If you have worked since then, capture has stopped and nothing from those sessions was saved.', 'Restart your agent, then end one session and re-run `memesh doctor`. If it does not recover, run `memesh install-hooks`.', { code: 'hook-activity.stale', params: { hook, hours: Math.ceil(age) } });
+            const ssAge = ages.has('session-summary') ? ages.get('session-summary') : undefined;
+            if (ssAge === null)
+                return staleUnknown('session-summary');
+            if (ssAge !== undefined) {
+                if (ssAge <= 24) {
+                    return createCheck('hook-activity', TITLE, 'pass', `The session-summary hook last ran ${formatHoursAgo(ssAge)} — auto-capture is alive. ${capturedTail}`);
+                }
+                if (ssAge <= 72)
+                    return stale('session-summary', ssAge, 'warn');
+                const ccWrites = db.prepare(`SELECT COUNT(*) as c FROM entities
+           WHERE created_at > datetime('now', '-72 hours')
+             AND json_valid(metadata)
+             AND json_extract(metadata, '$.provenance.source_host') = 'claude-code'`).get()?.c ?? 0;
+                if (ccWrites > 0)
+                    return stale('session-summary', ssAge, 'fail');
+                return createCheck('hook-activity', TITLE, 'warn', `The session-summary hook last ran ${formatHoursAgo(Math.ceil(ssAge))}, and no Claude Code writes landed in the last 3 days either. If this machine has moved to another agent (Codex / Gemini), this is expected; if you still use Claude Code here, capture has stopped.`, 'If you still use Claude Code on this machine: restart it, end one session, and re-run `memesh doctor`. If it does not recover, run `memesh install-hooks`.', { code: 'hook-activity.stale-unconfirmed', params: { hook: 'session-summary', hours: Math.ceil(ssAge) } });
+            }
+            const known = [...ages.entries()].filter((e) => e[1] !== null);
+            if (known.length === 0) {
+                const [hook] = [...ages.keys()].sort();
+                return staleUnknown(hook);
+            }
+            const [freshestHook, freshestAge] = known.sort((a, b) => a[1] - b[1])[0];
+            if (freshestAge <= 24) {
+                if (measuringHours !== null && measuringHours > 72) {
+                    return createCheck('hook-activity', TITLE, 'warn', `The ${freshestHook} hook is stamping (last ran ${formatHoursAgo(freshestAge)}), but the session-summary hook has never run once in the ${Math.round(measuringHours)} hours since tracking began — session capture may be broken while commit capture hides it.`, 'End one work session and re-run `memesh doctor`. If session-summary still has not run, run `memesh install-hooks` and restart your agent.', { code: 'hook-activity.stop-silent', params: { hook: freshestHook, hours: Math.round(measuringHours) } });
                 }
-                catch { }
+                return createCheck('hook-activity', TITLE, 'pass', `The ${freshestHook} hook last ran ${formatHoursAgo(freshestAge)} — auto-capture is alive. ` +
+                    `(session-summary has not stamped yet — expected until a session with real work ends.) ${capturedTail}`);
             }
-            return createCheck('hook-activity', 'Hook activity (last 24h)', 'warn', 'No memesh-attributed entities (session-insight, session-summary, commit, lesson_learned) in the past 24 hours. Hooks may be wired but not firing — likely a Claude Code restart is needed, or the agentic-loop guard is filtering all sessions.', 'Open a Claude Code session that uses ≥3 tools and ends naturally (not user_interrupt), or commit something. Then run `memesh doctor` again.');
+            return stale(freshestHook, freshestAge, 'warn');
+        }
+        if (since !== undefined && (measuringHours === null || measuringHours < 0)) {
+            return createCheck('hook-activity', TITLE, 'pass', 'The hook-run tracking marker is unreadable — it will be re-stamped automatically the next time the database is opened for writing (any session, commit, or memesh command does it). Tracking restarts then.');
         }
-        return createCheck('hook-activity', 'Hook activity (last 24h)', 'pass', `${count} memesh-attributed entit${count === 1 ? 'y' : 'ies'} captured in the past 24h — auto-capture loop is alive.`);
+        if (measuringHours === null || measuringHours < 24) {
+            return createCheck('hook-activity', TITLE, 'pass', 'Hook-run tracking has only just started on this database — the first work session will fill it in.');
+        }
+        const markerPath = path.join(memeshDir(), 'install-hooks.json');
+        if (existsSyncImpl(markerPath)) {
+            try {
+                if (Date.now() - statSyncImpl(markerPath).mtimeMs < 24 * 60 * 60 * 1000) {
+                    return createCheck('hook-activity', TITLE, 'pass', 'Hooks were wired in the last day and no session has ended yet — normal for a fresh install.');
+                }
+            }
+            catch { }
+        }
+        const legacyCaptured = db.prepare(`SELECT COUNT(DISTINCT e.id) as c FROM entities e
+       JOIN tags t ON t.entity_id = e.id
+       WHERE t.tag = ?
+         AND e.created_at > ?`).get(AUTO_CAPTURE_TAG, since)?.c ?? 0;
+        if (legacyCaptured > 0) {
+            return createCheck('hook-activity', TITLE, 'warn', `No hook has stamped the heartbeat, but ${legacyCaptured} auto-capture memor${legacyCaptured === 1 ? 'y' : 'ies'} landed since tracking began — hooks from a version before heartbeat tracking are probably still running.`, 'Update the memesh hooks to the current version (plugin installs: `/plugin update memesh`; npm installs: `memesh install-hooks`), then restart your agent.', { code: 'hook-activity.never-ran-legacy', params: { captured: legacyCaptured } });
+        }
+        if (!wiringPresent) {
+            return createCheck('hook-activity', TITLE, 'warn', 'No capture hook has ever run — and no capture hook (Stop / PostToolUse / PreCompact) is confirmed wired on this machine, so there is nothing to run.', 'If you want automatic capture, run `memesh install-hooks`. If this install is MCP-only (Codex / Gemini), this is expected and safe to ignore.', { code: 'hook-activity.not-wired' });
+        }
+        return createCheck('hook-activity', TITLE, 'fail', `No capture hook has run since tracking began ${formatHoursAgo(measuringHours)}. ` +
+            'Hook wiring is in place, so they should be executing and are not — nothing is being remembered.', 'Run `memesh doctor` after ending one work session. If this still says no hook has run, run `memesh install-hooks` and restart your agent.', { code: 'hook-activity.never-ran', params: { hours: Math.round(measuringHours) } });
     }
     catch (err) {
-        return createCheck('hook-activity', 'Hook activity (last 24h)', 'warn', `Could not query the database: ${err instanceof Error ? err.message : String(err)}`);
+        const detail = err instanceof Error ? err.message : String(err);
+        return createCheck('hook-activity', TITLE, 'fail', `Could not read hook activity from the database: ${detail}. Capture health is unknown, which is not the same as healthy.`, 'Run `memesh doctor --verbose` for the full error, and check that ~/.memesh is readable and not out of disk.', { code: 'hook-activity.query-failed', params: { detail } });
     }
     finally {
         try {
@@ -292,6 +389,44 @@ function inspectHookActivity(openDatabaseImpl, closeDatabaseImpl, existsSyncImpl
         catch { }
     }
 }
+function autoCaptureOffSource() {
+    const envVal = process.env.MEMESH_AUTO_CAPTURE;
+    if (envVal === 'false')
+        return 'env';
+    if (envVal === 'true')
+        return null;
+    try {
+        return readConfig().autoCapture === false ? 'config' : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hoursSince(sqliteTimestamp) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/.exec(sqliteTimestamp ?? '');
+    if (!m)
+        return null;
+    const then = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]);
+    if (!Number.isFinite(then))
+        return null;
+    const d = new Date(then);
+    if (d.getUTCFullYear() !== +m[1] || d.getUTCMonth() !== +m[2] - 1 || d.getUTCDate() !== +m[3]
+        || d.getUTCHours() !== +m[4] || d.getUTCMinutes() !== +m[5] || d.getUTCSeconds() !== +m[6])
+        return null;
+    return (Date.now() - then) / (60 * 60 * 1000);
+}
+function formatHoursAgo(hours) {
+    if (hours === null || !Number.isFinite(hours) || hours < 0)
+        return 'at an unknown time';
+    if (hours < 1)
+        return 'less than an hour ago';
+    if (hours < 48) {
+        const h = Math.round(hours);
+        return `${h} hour${h === 1 ? '' : 's'} ago`;
+    }
+    const d = Math.round(hours / 24);
+    return `${d} day${d === 1 ? '' : 's'} ago`;
+}
 function defaultResolveShellMemesh() {
     try {
         const cmd = process.platform === 'win32' ? 'where' : 'which';
@@ -305,12 +440,23 @@ function defaultResolveShellMemesh() {
         return null;
     }
 }
+const RUNTIME_TOO_OLD = 'memesh:node-sqlite-too-old';
 function defaultNativeBindingProbe(packageRoot) {
     try {
-        const localRequire = createRequire(pathToFileURL(path.join(packageRoot, 'package.json')).href);
-        const Database = localRequire('better-sqlite3');
-        const probe = new Database(':memory:');
-        probe.close();
+        const probe = new MemeshDatabase(':memory:', { allowExtension: true });
+        try {
+            if (typeof probe.enableLoadExtension !== 'function') {
+                return { ok: false, message: `${RUNTIME_TOO_OLD}: node:sqlite in ${process.version} has no enableLoadExtension` };
+            }
+            probe.enableLoadExtension(true);
+            const localRequire = createRequire(pathToFileURL(path.join(packageRoot, 'package.json')).href);
+            const sqliteVec = localRequire('sqlite-vec');
+            sqliteVec.load(probe);
+            probe.prepare('SELECT vec_version()').get();
+        }
+        finally {
+            probe.close();
+        }
         return { ok: true };
     }
     catch (err) {
@@ -356,7 +502,7 @@ export function inspectNodeRuntime(packageRoot, existsSyncImpl, readFileSyncImpl
     }
     if (!ok) {
         return createCheck('node-runtime', 'Node runtime', 'fail', `${facts} This package requires Node ${declared}, so this runtime is BELOW the ` +
-            `supported floor. Native modules and hooks may fail in ways that look unrelated.`, `Upgrade Node to ${declared.replace(/^>=\s*/, '')} or newer, then run \`memesh doctor\` again.`);
+            `supported floor. Native modules and hooks may fail in ways that look unrelated.`, `Upgrade Node to ${declared.replace(/^>=\s*/, '')} or newer, then run \`memesh doctor\` again.`, { code: 'node-runtime.too-old', params: { detail: facts, required: declared.replace(/^>=\s*/, '') } });
     }
     return createCheck('node-runtime', 'Node runtime', 'pass', `${facts} Meets the required range ${declared}.`);
 }
@@ -372,20 +518,16 @@ export function hasBuiltInSqlite() {
 function inspectNativeBinding(packageRoot, _existsSyncImpl, probeImpl = defaultNativeBindingProbe) {
     const result = probeImpl(packageRoot);
     if (result.ok) {
-        return createCheck('native-binding', 'Native SQLite binding', 'pass', 'better-sqlite3 native binding loads cleanly (Database probe succeeded).');
+        return createCheck('native-binding', 'SQLite and vector search', 'pass', 'node:sqlite opened a database and sqlite-vec loaded (probe succeeded).');
+    }
+    if (result.message.startsWith(RUNTIME_TOO_OLD)) {
+        return createCheck('native-binding', 'SQLite and vector search', 'fail', `The node:sqlite in this Node (${process.version}) is too old for memesh — it cannot load the vector-search extension. The complete version arrived in Node 22.13.`, 'Upgrade Node to 22.13 or newer, then re-run `memesh doctor`.', { code: 'native-binding.node-too-old', params: { version: process.version } });
     }
-    const isMissingBinding = /bindings file|locate the bindings/i.test(result.message);
     const isMissingPackage = /MODULE_NOT_FOUND|Cannot find module/i.test(result.message);
     if (isMissingPackage) {
-        return createCheck('native-binding', 'Native SQLite binding', 'fail', 'better-sqlite3 is not installed (Node could not resolve the module from any '
-            + 'parent node_modules). Memesh hooks and database operations will not work.', `Run: npm install   (in the directory that depends on @pcircle/memesh)`);
-    }
-    if (isMissingBinding) {
-        return createCheck('native-binding', 'Native SQLite binding', 'fail', 'better-sqlite3 is installed but the native binding (.node file) is missing. '
-            + 'Hooks will silently skip-and-exit, and auto-capture will NOT write any entities. '
-            + 'This is the plugin-marketplace silent-dropout class of bug.', `Run: cd "${packageRoot}" && npm rebuild better-sqlite3   (or "npm install --omit=dev" for a clean reinstall)`);
+        return createCheck('native-binding', 'SQLite and vector search', 'warn', 'sqlite-vec is not installed, so memesh cannot search by meaning. Memories are still saved, and still found by keyword.', 'Run: npm install   (in the directory that depends on @pcircle/memesh)', { code: 'native-binding.not-installed' });
     }
-    return createCheck('native-binding', 'Native SQLite binding', 'fail', `better-sqlite3 failed to load: ${result.message}`, `Run: cd "${packageRoot}" && npm rebuild better-sqlite3`);
+    return createCheck('native-binding', 'SQLite and vector search', 'warn', `sqlite-vec could not be loaded: ${result.message}. Memories are still saved and found by keyword; only search by meaning is off.`, `Run: cd "${packageRoot}" && npm install --omit=dev`, { code: 'native-binding.load-failed', params: { detail: result.message, root: packageRoot } });
 }
 function inspectShellCli(installChannel, packageRoot, resolveShellMemeshImpl) {
     const shellPath = resolveShellMemeshImpl();
@@ -401,7 +543,7 @@ function inspectShellCli(installChannel, packageRoot, resolveShellMemeshImpl) {
     }
     if (installChannel === 'plugin-marketplace') {
         return createCheck('shell-cli', 'Shell CLI on PATH', 'warn', 'Plugin is installed but `memesh` is not on the shell PATH. Typing `memesh` in a regular terminal will report `command not found`. '
-            + 'Claude Code MCP / hooks / `/memesh` skill still work — this only affects standalone shell usage and other MCP clients (Cursor, Cline, etc.).', 'Run `npm install -g @pcircle/memesh` to add the shell CLI. Both paths coexist; they share the same `~/.memesh/knowledge-graph.db`.');
+            + 'Claude Code MCP / hooks / `/memesh` skill still work — this only affects standalone shell usage and other MCP clients (Cursor, Cline, etc.).', 'Run `npm install -g @pcircle/memesh` to add the shell CLI. Both paths coexist; they share the same `~/.memesh/knowledge-graph.db`.', { code: 'shell-cli.not-on-path' });
     }
     return createCheck('shell-cli', 'Shell CLI on PATH', 'pass', shellPath
         ? `\`memesh\` resolves to ${shellPath}.`
@@ -410,14 +552,14 @@ function inspectShellCli(installChannel, packageRoot, resolveShellMemeshImpl) {
 function inspectDashboardArtifact(packageRoot, existsSyncImpl) {
     const dashboardPath = path.join(packageRoot, 'dashboard', 'dist', 'index.html');
     if (!existsSyncImpl(dashboardPath)) {
-        return createCheck('dashboard', 'Dashboard artifact', 'fail', 'dashboard/dist/index.html is missing.', 'Build the dashboard with `cd dashboard && npm install && npm run build`, then run `npm run build` at the repo root if needed.');
+        return createCheck('dashboard', 'Dashboard artifact', 'fail', 'dashboard/dist/index.html is missing.', 'Build the dashboard with `cd dashboard && npm install && npm run build`, then run `npm run build` at the repo root if needed.', { code: 'dashboard.missing' });
     }
     return createCheck('dashboard', 'Dashboard artifact', 'pass', 'dashboard/dist/index.html is present.');
 }
 async function inspectUpdateStatus(packageVersion, getUpdateCheckImpl, installSupport) {
     const update = await getUpdateCheckImpl(packageVersion, { preferFresh: false });
     if (!update) {
-        return createCheck('update-status', 'Update status', 'warn', 'No successful cached npm update check is available yet.', 'Run `memesh status` once while online to populate update status.');
+        return createCheck('update-status', 'Update status', 'warn', 'memesh has not been able to check for newer versions yet, so it cannot tell you whether an update exists.', 'Run `memesh status` once while connected to the internet — that stores the answer and this notice goes away.', { code: 'update-status.no-cache' });
     }
     if (update.currentVersionDeprecated && update.deprecationMessage) {
         const target = update.latestVersion && update.latestVersion !== packageVersion
@@ -439,10 +581,10 @@ async function inspectUpdateStatus(packageVersion, getUpdateCheckImpl, installSu
         else {
             fix = `Upgrade via your install method (see \`memesh status\`).`;
         }
-        return createCheck('update-status', 'Update status', 'fail', `Installed version ${packageVersion} is DEPRECATED by maintainers: ${update.deprecationMessage}`, fix);
+        return createCheck('update-status', 'Update status', 'fail', `Installed version ${packageVersion} is DEPRECATED by maintainers: ${update.deprecationMessage}`, fix, { code: 'update-status.deprecated', params: { version: packageVersion, detail: update.deprecationMessage ?? '' } });
     }
     if (update.freshness === 'unavailable') {
-        return createCheck('update-status', 'Update status', 'warn', 'No successful cached npm update check is available yet.', 'Run `memesh status` once while online to populate update status.');
+        return createCheck('update-status', 'Update status', 'warn', 'memesh has not been able to check for newer versions yet, so it cannot tell you whether an update exists.', 'Run `memesh status` once while connected to the internet — that stores the answer and this notice goes away.', { code: 'update-status.no-cache' });
     }
     if (update.checkSucceeded && update.lastError) {
         const hasUpdate = Boolean(update.updateAvailable && update.latestVersion);
@@ -465,11 +607,14 @@ async function inspectUpdateStatus(packageVersion, getUpdateCheckImpl, installSu
             upgradeHint = '';
         }
         const fix = `Run \`memesh status\` while online to retry the deprecation lookup${upgradeHint}.`;
-        return createCheck('update-status', 'Update status', 'warn', summary, fix);
+        return createCheck('update-status', 'Update status', 'warn', summary, fix, {
+            code: 'update-status.deprecation-unknown',
+            params: { version: packageVersion, detail: update.lastError ?? '' },
+        });
     }
     if (update.updateAvailable && update.latestVersion) {
         if (packageVersion < update.latestVersion) {
-            return createCheck('update-status', 'Update status', 'warn', `Update available: ${update.latestVersion} (current: ${packageVersion})`, `Run 'memesh update' to upgrade`);
+            return createCheck('update-status', 'Update status', 'warn', `Update available: ${update.latestVersion} (current: ${packageVersion})`, `Run 'memesh update' to upgrade`, { code: 'update-status.update-available', params: { latest: update.latestVersion, current: packageVersion } });
         }
         else {
             return createCheck('update-status', 'Update status', 'pass', `Running pre-release version (${packageVersion}), npm latest is ${update.latestVersion}`);
@@ -477,35 +622,37 @@ async function inspectUpdateStatus(packageVersion, getUpdateCheckImpl, installSu
     }
     return createCheck('update-status', 'Update status', update.freshness === 'stale' ? 'warn' : 'pass', `Version ${packageVersion} is current${update.freshness === 'stale' ? ', but cached update data is stale.' : '.'}`, update.freshness === 'stale'
         ? 'Run `memesh status` while online to refresh cached update metadata.'
+        : undefined, update.freshness === 'stale'
+        ? { code: 'update-status.stale', params: { version: packageVersion } }
         : undefined);
 }
 async function inspectHttpProbe(httpBaseUrl, fetchImpl) {
     try {
         const response = await fetchImpl(`${httpBaseUrl.replace(/\/$/, '')}/v1/health`);
         if (!response.ok) {
-            return createCheck('http-probe', 'HTTP probe', 'warn', `HTTP server responded with ${response.status} at ${httpBaseUrl}.`, 'Run `memesh serve` and check the logs, then retry `memesh doctor --probe-http`.');
+            return createCheck('http-probe', 'HTTP probe', 'warn', `HTTP server responded with ${response.status} at ${httpBaseUrl}.`, 'Run `memesh serve` and check the logs, then retry `memesh doctor --probe-http`.', { code: 'http-probe.bad-status', params: { status: response.status, url: httpBaseUrl } });
         }
         return createCheck('http-probe', 'HTTP probe', 'pass', `HTTP server is reachable at ${httpBaseUrl}.`);
     }
     catch {
-        return createCheck('http-probe', 'HTTP probe', 'warn', `No running HTTP server detected at ${httpBaseUrl}.`, 'Start the local server with `memesh serve` if you want dashboard and HTTP API verification.');
+        return createCheck('http-probe', 'HTTP probe', 'warn', `No running HTTP server detected at ${httpBaseUrl}.`, 'Start the local server with `memesh serve` if you want dashboard and HTTP API verification.', { code: 'http-probe.no-server', params: { url: httpBaseUrl } });
     }
 }
 function verifySkillsManifest(packageRoot, existsSyncImpl, readFileSyncImpl) {
     const manifestPath = path.join(packageRoot, 'dist', 'skills-manifest.json');
     if (!existsSyncImpl(manifestPath)) {
-        return createCheck('skills-manifest', 'Skills + hooks integrity', 'warn', 'No skills-manifest.json found. This is normal for source checkouts — packaged installs ship the manifest.', 'Run `npm run build` to regenerate, or reinstall via `npm install -g @pcircle/memesh`.');
+        return createCheck('skills-manifest', 'Skills + hooks integrity', 'warn', 'No skills-manifest.json found. This is normal for source checkouts — packaged installs ship the manifest.', 'Run `npm run build` to regenerate, or reinstall via `npm install -g @pcircle/memesh`.', { code: 'skills-manifest.missing-dev' });
     }
     let manifest;
     try {
         manifest = JSON.parse(readFileSyncImpl(manifestPath, 'utf8'));
     }
     catch (err) {
-        return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', `skills-manifest.json is unreadable (${err instanceof Error ? err.message : 'parse error'}).`, 'Reinstall the package: `npm install -g @pcircle/memesh`. If the problem persists open an issue.');
+        return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', `skills-manifest.json is unreadable (${err instanceof Error ? err.message : 'parse error'}).`, 'Reinstall the package: `npm install -g @pcircle/memesh`. If the problem persists open an issue.', { code: 'skills-manifest.unreadable', params: { detail: err instanceof Error ? err.message : 'parse error' } });
     }
     const entries = manifest.entries ?? [];
     if (entries.length === 0) {
-        return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', 'skills-manifest.json contains zero entries.', 'Reinstall the package: `npm install -g @pcircle/memesh`.');
+        return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', 'skills-manifest.json contains zero entries.', 'Reinstall the package: `npm install -g @pcircle/memesh`.', { code: 'skills-manifest.empty' });
     }
     const mismatches = [];
     const missing = [];
@@ -534,7 +681,7 @@ function verifySkillsManifest(packageRoot, existsSyncImpl, readFileSyncImpl) {
         missing.length > 0 ? `${missing.length} missing: ${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ` (+${missing.length - 3} more)` : ''}` : null,
         mismatches.length > 0 ? `${mismatches.length} tampered: ${mismatches.slice(0, 3).join(', ')}${mismatches.length > 3 ? ` (+${mismatches.length - 3} more)` : ''}` : null,
     ].filter(Boolean).join('; ');
-    return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', `Manifest verification failed: ${detail}.`, 'Reinstall the package: `npm install -g @pcircle/memesh`. If the problem reproduces on a fresh install, open a security issue at https://github.com/PCIRCLE-AI/memesh-llm-memory/security.');
+    return createCheck('skills-manifest', 'Skills + hooks integrity', 'fail', `Manifest verification failed: ${detail}.`, 'Reinstall the package: `npm install -g @pcircle/memesh`. If the problem reproduces on a fresh install, open a security issue at https://github.com/PCIRCLE-AI/memesh-llm-memory/security.', { code: 'skills-manifest.verify-failed', params: { detail } });
 }
 async function inspectConfigParse(getConfigPathImpl, existsSyncImpl, readFileSyncImpl) {
     const configPath = getConfigPathImpl();
@@ -545,13 +692,13 @@ async function inspectConfigParse(getConfigPathImpl, existsSyncImpl, readFileSyn
         const raw = readFileSyncImpl(configPath, 'utf8');
         const parsed = JSON.parse(raw);
         if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            return createCheck('config_parse', 'Config parses', 'fail', `${configPath} parsed but is not a JSON object — every setting is being ignored.`, `Fix or remove ${configPath}, then re-run memesh doctor.`);
+            return createCheck('config_parse', 'Config parses', 'fail', `${configPath} parsed but is not a JSON object — every setting is being ignored.`, `Fix or remove ${configPath}, then re-run memesh doctor.`, { code: 'config-parse.not-object', params: { path: configPath } });
         }
         return createCheck('config_parse', 'Config parses', 'pass', `${configPath} is valid JSON and its settings are in effect.`);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        return createCheck('config_parse', 'Config parses', 'fail', `${configPath} could not be read or parsed (${msg}). Every setting in it — LLM provider, fallbacks, embedder — is being silently ignored right now.`, `Fix the JSON or remove the file to fall back to defaults: mv ${configPath} ${configPath}.bak`);
+        return createCheck('config_parse', 'Config parses', 'fail', `${configPath} could not be read or parsed (${msg}). Every setting in it — LLM provider, fallbacks, embedder — is being silently ignored right now.`, `Fix the JSON or remove the file to fall back to defaults: mv ${configPath} ${configPath}.bak`, { code: 'config-parse.unreadable', params: { path: configPath, detail: msg } });
     }
 }
 async function inspectEmbeddingProbe(capabilities, probeCapabilities, embedTextImpl) {
@@ -559,13 +706,7 @@ async function inspectEmbeddingProbe(capabilities, probeCapabilities, embedTextI
         return createInfo('embeddings_probe', 'Embeddings work', 'No neural embedder configured — recall runs on FTS5 keyword search alone. That is a supported mode, not a fault.');
     }
     if (!probeCapabilities) {
-        const isLocal = capabilities.embeddings === 'onnx';
-        if (!isLocal) {
-            return createInfo('embeddings_probe', 'Embeddings work', `NOT VERIFIED. Config names "${capabilities.embeddings}", but generating a test embedding is a network call (billed on hosted providers) so it was not made — a revoked key or an unreachable host would look identical to a healthy setup here.`, 'Run: memesh doctor --probe   (generates one test embedding to confirm)');
-        }
-        if (!isOnnxModelCached()) {
-            return createInfo('embeddings_probe', 'Embeddings work', `NOT VERIFIED. Config names "onnx" but the model is not in the local cache yet, and probing would download ~90 MB — which a diagnostic command must not do on its own.`, 'Run: memesh doctor --probe   (downloads the model once, then verifies)');
-        }
+        return createInfo('embeddings_probe', 'Embeddings work', `NOT VERIFIED. Config names "${capabilities.embeddings}", but generating a test embedding is a network call (billed on hosted providers) so it was not made — a revoked key or an unreachable host would look identical to a healthy setup here.`, 'Run: memesh doctor --probe   (generates one test embedding to confirm)');
     }
     let timer;
     try {
@@ -576,13 +717,13 @@ async function inspectEmbeddingProbe(capabilities, probeCapabilities, embedTextI
             }),
         ]);
         if (!vector || vector.length === 0) {
-            return createCheck('embeddings_probe', 'Embeddings work', 'warn', `Config selects "${capabilities.embeddings}" but generating a test embedding returned nothing. Semantic recall is degraded to FTS5-only; keyword search still works.`, 'Run: memesh doctor --probe for detail, or check network access to the embedding provider.');
+            return createCheck('embeddings_probe', 'Embeddings work', 'warn', `Config selects "${capabilities.embeddings}" but generating a test embedding returned nothing. Semantic recall is degraded to FTS5-only; keyword search still works.`, 'Run: memesh doctor --probe for detail, or check network access to the embedding provider.', { code: 'embeddings.empty', params: { provider: String(capabilities.embeddings) } });
         }
         return createCheck('embeddings_probe', 'Embeddings work', 'pass', `Generated a ${vector.length}-dim test embedding via "${capabilities.embeddings}".`);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        return createCheck('embeddings_probe', 'Embeddings work', 'warn', `Config selects "${capabilities.embeddings}" but the embedder threw (${msg}). Semantic recall is degraded to FTS5-only.`, 'Check the embedding provider is reachable, or set: memesh config set embedder.provider onnx');
+        return createCheck('embeddings_probe', 'Embeddings work', 'warn', `Config selects "${capabilities.embeddings}" but the embedder threw (${msg}). Semantic recall is degraded to FTS5-only.`, 'Check the embedding provider is reachable (e.g. run `ollama serve`), or remove embedder config to use keyword-only search.', { code: 'embeddings.threw', params: { provider: String(capabilities.embeddings), detail: msg } });
     }
     finally {
         clearTimeout(timer);
@@ -601,11 +742,11 @@ async function inspectLlmProbe(capabilities, probeCapabilities, probeProviderImp
         if (result.valid) {
             return createCheck('llm_probe', 'LLM reachable', 'pass', `${llm.provider} answered a live probe.`);
         }
-        return createCheck('llm_probe', 'LLM reachable', 'fail', `${llm.provider} is configured but did not answer: ${result.error ?? 'unknown error'}. Every LLM-backed feature is silently doing nothing.`, 'Check the API key / host, then re-run: memesh doctor --probe');
+        return createCheck('llm_probe', 'LLM reachable', 'fail', `${llm.provider} is configured but did not answer: ${result.error ?? 'unknown error'}. Every LLM-backed feature is silently doing nothing.`, 'Check the API key / host, then re-run: memesh doctor --probe', { code: 'llm.unreachable', params: { provider: llm.provider, detail: result.error ?? 'unknown error' } });
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        return createCheck('llm_probe', 'LLM reachable', 'fail', `${llm.provider} probe threw: ${msg}. Every LLM-backed feature is silently doing nothing.`, 'Check the API key / host, then re-run: memesh doctor --probe');
+        return createCheck('llm_probe', 'LLM reachable', 'fail', `${llm.provider} probe threw: ${msg}. Every LLM-backed feature is silently doing nothing.`, 'Check the API key / host, then re-run: memesh doctor --probe', { code: 'llm.threw', params: { provider: llm.provider, detail: msg } });
     }
 }
 function summarizeOverallStatus(checks) {
@@ -627,7 +768,7 @@ export async function runDoctor(options) {
     const installSupport = getInstallChannelSupportImpl(install);
     checks.push(createCheck('install-channel', 'Install method', install === 'unknown' ? 'warn' : 'pass', `Install method detected: ${installSupport.label}.`, install === 'unknown'
         ? 'If this is a source checkout, run MeMesh from the repo root. If this is a packaged install, reinstall with `npm install -g @pcircle/memesh`.'
-        : undefined));
+        : undefined, install === 'unknown' ? { code: 'install-channel.unknown' } : undefined));
     const databasePath = resolveDatabasePath();
     const dbChecks = [];
     try {
@@ -647,12 +788,12 @@ export async function runDoctor(options) {
                 dbChecks.push(createCheck('fts_segmentation', 'Keyword index segmentation', 'warn', `The keyword index holds ${unsegmented.c} unsegmented term(s), so some memories are only ` +
                     `findable by their exact full text. This happens when an older build wrote to a database ` +
                     `that a newer one had already migrated — the version marker only moves forward, so the ` +
-                    `automatic rebuild cannot notice. Re-run doctor after the rebuild: this count should be 0.`, `Run 'memesh reindex --fts' to rebuild the keyword index.`));
+                    `automatic rebuild cannot notice. Re-run doctor after the rebuild: this count should be 0.`, `Run 'memesh reindex --fts' to rebuild the keyword index.`, { code: 'fts.unsegmented', params: { count: unsegmented.c } }));
             }
         }
         const pendingReindex = getPendingReindexInfo();
         if (pendingReindex) {
-            dbChecks.push(createCheck('vector_index', 'Vector Index', 'warn', `Search index needs rebuilding (embedding configuration changed)`, `Run 'memesh reindex' to fix. This will restore full search functionality.`));
+            dbChecks.push(createCheck('vector_index', 'Vector Index', 'warn', `Search index needs rebuilding (embedding configuration changed)`, `Run 'memesh reindex' to fix. This will restore full search functionality.`, { code: 'vector-index.stale' }));
         }
     }
     catch (err) {
@@ -708,7 +849,7 @@ export async function runDoctor(options) {
             }
         }
         dbChecks.length = 0;
-        dbChecks.push(createCheck('database', 'Database', 'fail', diagnosis, fix));
+        dbChecks.push(createCheck('database', 'Database', 'fail', diagnosis, fix, { code: 'database.broken', params: { detail: diagnosis } }));
     }
     finally {
         checks.push(...dbChecks);
@@ -721,8 +862,11 @@ export async function runDoctor(options) {
     checks.push(inspectConfigFile(existsSyncImpl, readFileSyncImpl, getConfigPathImpl));
     checks.push(inspectMcpConfig(packageRoot, existsSyncImpl, readFileSyncImpl));
     checks.push(...inspectHooksConfig(packageRoot, platform, existsSyncImpl, readFileSyncImpl, statSyncImpl));
-    checks.push(inspectHookWiring(existsSyncImpl, readFileSyncImpl, memeshDir(), packageRoot));
-    checks.push(inspectHookActivity(openDatabaseImpl, safeCloseDatabaseImpl, existsSyncImpl, statSyncImpl));
+    const wiring = inspectHookWiring(existsSyncImpl, readFileSyncImpl, memeshDir(), install);
+    checks.push(wiring);
+    const captureWired = wiring.status === 'pass'
+        && (wiring.params === undefined || wiring.params.captureWired === 1);
+    checks.push(inspectHookActivity(openDatabaseImpl, safeCloseDatabaseImpl, existsSyncImpl, statSyncImpl, captureWired));
     checks.push(inspectDashboardArtifact(packageRoot, existsSyncImpl));
     checks.push(inspectNodeRuntime(packageRoot, existsSyncImpl, readFileSyncImpl));
     checks.push(inspectNativeBinding(packageRoot, existsSyncImpl, nativeBindingProbeImpl));
@@ -730,6 +874,16 @@ export async function runDoctor(options) {
     checks.push(verifySkillsManifest(packageRoot, existsSyncImpl, readFileSyncImpl));
     const capabilities = detectCapabilitiesImpl();
     checks.push(createInfo('capabilities', 'Capabilities (configured)', `Search level ${capabilities.searchLevel} (${capabilities.searchLevel === 1 ? 'Smart Mode' : 'Core'}); embeddings: ${capabilities.embeddings}; LLM: ${capabilities.llm ? `${capabilities.llm.provider} (${capabilities.llm.model ?? 'default'})` : 'not configured'}. Configured values only — see the probe rows below for what actually works.`));
+    if (!isTranscriptMiningEnabled()) {
+        checks.push(createInfo('transcript-mining', 'Scheduled transcript mining', 'Off (opt-in). memesh can mine this project\'s Claude Code session transcripts for decisions and lessons and STAGE them for your review. Turn it on with `memesh config set transcriptMining true`, then have a scheduler (cron/launchd) run `memesh dream run --from-transcripts --if-due` — it self-throttles and stages only, so nothing enters your graph without `dream accept`.'));
+    }
+    else {
+        const last = lastTranscriptMineAt(getProjectName(process.cwd()));
+        const when = last === null
+            ? 'not yet run for this project'
+            : `last mined ${((Date.now() - last) / 3600_000).toFixed(1)}h ago`;
+        checks.push(createInfo('transcript-mining', 'Scheduled transcript mining', `On for this project — ${when}. Have a scheduler run \`memesh dream run --from-transcripts --if-due\`; it mines when due (default every 24h) and stages proposals. Review the queue with \`memesh dream list\`.`));
+    }
     checks.push(await inspectConfigParse(getConfigPathImpl, existsSyncImpl, readFileSyncImpl));
     checks.push(await inspectEmbeddingProbe(capabilities, probeCapabilities, embedTextImpl));
     checks.push(await inspectLlmProbe(capabilities, probeCapabilities, probeProviderImpl));