@gamaze/hicortex 0.7.1 → 0.10.0

package/dist/init.js

@@ -12,20 +12,29 @@
  * Actions:
  *   - Install persistent daemon (launchd/systemd)
  *   - Register MCP server in CC settings
- *   - Inject CLAUDE.md learnings block
+ *   - Install CC SessionStart hook for query-time lessons
+ *   - Strip old static CLAUDE.md learnings block if present
  *   - Install CC custom commands (/learn, /hicortex-activate)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvFile = parseEnvFile;
+exports.generateAuthToken = generateAuthToken;
+exports.persistAuthToken = persistAuthToken;
+exports.installSessionStartHook = installSessionStartHook;
 exports.runInit = runInit;
+exports.resolveNightlyHour = resolveNightlyHour;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
 const node_readline_1 = require("node:readline");
+const node_crypto_1 = require("node:crypto");
+const claude_md_js_1 = require("./claude-md.js");
 const HICORTEX_HOME = (0, node_path_1.join)((0, node_os_1.homedir)(), ".hicortex");
 const CC_SETTINGS = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "settings.json");
 const CC_COMMANDS_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "commands");
 const OC_CONFIG = (0, node_path_1.join)((0, node_os_1.homedir)(), ".openclaw", "openclaw.json");
+const HERMES_HOME = process.env.HERMES_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), ".hermes");
 const DEFAULT_PORT = 8787;
 async function detect() {
     const result = {
@@ -33,6 +42,7 @@ async function detect() {
         remoteServer: false,
         ocPlugin: false,
         ccMcpRegistered: false,
+        hermesFound: false,
         existingDb: false,
     };
     // Check local server
@@ -64,6 +74,8 @@ async function detect() {
         }
         catch { /* not reachable */ }
     }
+    // Check Hermes
+    result.hermesFound = (0, node_fs_1.existsSync)(HERMES_HOME);
     // Check OC plugin
     try {
         const raw = (0, node_fs_1.readFileSync)(OC_CONFIG, "utf-8");
@@ -121,10 +133,15 @@ function registerCcMcp(serverUrl) {
         console.log(`  ⚠ claude CLI registration failed (${msg}), writing ~/.claude.json directly`);
         const claudeJsonPath = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude.json");
         let config = {};
-        try {
-            config = JSON.parse((0, node_fs_1.readFileSync)(claudeJsonPath, "utf-8"));
+        if ((0, node_fs_1.existsSync)(claudeJsonPath)) {
+            try {
+                config = JSON.parse((0, node_fs_1.readFileSync)(claudeJsonPath, "utf-8"));
+            }
+            catch {
+                console.log(`  ⚠ ${claudeJsonPath} exists but is not valid JSON — skipping MCP registration. Fix the file, then re-run init or run: claude mcp add hicortex --transport sse ${serverUrl}/sse`);
+                return;
+            }
         }
-        catch { /* create new */ }
         if (!config.mcpServers)
             config.mcpServers = {};
         config.mcpServers.hicortex = {
@@ -139,10 +156,15 @@ function registerCcMcp(serverUrl) {
 }
 function allowHicortexTools() {
     let settings = {};
-    try {
-        settings = JSON.parse((0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8"));
+    if ((0, node_fs_1.existsSync)(CC_SETTINGS)) {
+        try {
+            settings = JSON.parse((0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8"));
+        }
+        catch {
+            console.log(`  ⚠ ${CC_SETTINGS} exists but is not valid JSON — skipping tool permissions. Fix the file, then re-run init or add "mcp__hicortex__*" to permissions.allow manually.`);
+            return;
+        }
     }
-    catch { /* create new */ }
     if (!settings.permissions)
         settings.permissions = {};
     const perms = settings.permissions;
@@ -205,15 +227,15 @@ Becomes a call to hicortex_ingest with:
     else {
         (0, node_fs_1.writeFileSync)(learnPath, learnContent);
     }
-    // /hicortex-activate command
+    // /hicortex-activate command — registers a commercial license key for display in status
     const activateContent = `---
 name: hicortex-activate
-description: Activate a Hicortex license key for unlimited memory. Use after purchasing at hicortex.gamaze.com.
+description: Register a Hicortex commercial license key. Personal and noncommercial use is free; commercial use requires a per-seat license from hicortex.gamaze.com.
 argument-hint: <license-key>
 allowed-tools: Bash(mkdir:*), Bash(echo:*), Bash(launchctl:*), Bash(systemctl:*), Bash(curl:*), mcp__hicortex__hicortex_ingest, mcp__hicortex__hicortex_search, mcp__hicortex__hicortex_context, mcp__hicortex__hicortex_lessons
 ---
 
-# Activate Hicortex License
+# Register Hicortex Commercial License
 
 ## If key provided (e.g. /hicortex-activate hctx-abc123)
 
@@ -236,23 +258,122 @@ On Linux:
 systemctl --user restart hicortex
 \`\`\`
 
-3. Verify the server is back:
+3. Verify the key is recognised:
 \`\`\`bash
-curl -s http://127.0.0.1:8787/health
+hicortex status
 \`\`\`
 
-4. Tell the user: "License activated! Hicortex now has unlimited memory."
+4. Tell the user: "Commercial license registered. The license tier will appear in \`hicortex status\`."
 
 ## If no key provided
 
-Tell them: "Get a license key at https://hicortex.gamaze.com/ — after purchase, you'll receive your key by email. Then tell me the key and I'll activate it."
+Tell them: "Hicortex is free for personal and noncommercial use. Commercial use requires a per-seat license — see https://hicortex.gamaze.com/. After purchase you will receive a key; pass it here and I'll register it."
 `;
     (0, node_fs_1.writeFileSync)((0, node_path_1.join)(CC_COMMANDS_DIR, "hicortex-activate.md"), activateContent);
     console.log(`  ✓ Installed /learn and /hicortex-activate commands in ${CC_COMMANDS_DIR}`);
 }
+// ---------------------------------------------------------------------------
+// Hermes setup
+// ---------------------------------------------------------------------------
+function setupHermes(serverUrl, authToken) {
+    const pluginSource = (0, node_path_1.join)(__dirname, "..", "hermes-plugin", "hicortex");
+    if (!(0, node_fs_1.existsSync)(pluginSource)) {
+        console.log("  ⚠ Hermes plugin not found in package — skipping Hermes setup");
+        return;
+    }
+    const pluginsDir = (0, node_path_1.join)(HERMES_HOME, "plugins", "hicortex");
+    (0, node_fs_1.mkdirSync)(pluginsDir, { recursive: true });
+    // Copy plugin files
+    const pluginFiles = (0, node_fs_1.readdirSync)(pluginSource);
+    for (const f of pluginFiles) {
+        const src = (0, node_path_1.join)(pluginSource, f);
+        if ((0, node_fs_1.statSync)(src).isFile()) {
+            (0, node_fs_1.copyFileSync)(src, (0, node_path_1.join)(pluginsDir, f));
+        }
+    }
+    console.log(`  ✓ Copied Hermes plugin to ${pluginsDir}`);
+    // Write plugin config.json (server URL only). The auth token is a SECRET and
+    // is deliberately NOT written here — `hermes memory setup` routes it to
+    // $HERMES_HOME/.env, and localhost bypasses auth entirely. Capture threshold
+    // omitted → the plugin's own default applies.
+    const config = { hicortex_url: serverUrl };
+    const configPath = (0, node_path_1.join)(pluginsDir, "config.json");
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+    console.log(`  ✓ Plugin config → ${serverUrl}`);
+    // For profile-based setups, symlink the shared plugin into each profile's
+    // plugin dir (non-destructive). Discovery scans $HERMES_HOME/plugins/, so
+    // this is belt-and-suspenders for profile-scoped installs.
+    const profilesDir = (0, node_path_1.join)(HERMES_HOME, "profiles");
+    if ((0, node_fs_1.existsSync)(profilesDir)) {
+        let profiles = [];
+        try {
+            profiles = (0, node_fs_1.readdirSync)(profilesDir).filter((d) => {
+                try {
+                    return (0, node_fs_1.statSync)((0, node_path_1.join)(profilesDir, d)).isDirectory() && !d.startsWith("_") && !d.startsWith(".");
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        catch { /* no profiles dir readable */ }
+        for (const profile of profiles) {
+            const profPluginsDir = (0, node_path_1.join)(profilesDir, profile, "plugins");
+            const symlinkPath = (0, node_path_1.join)(profPluginsDir, "hicortex");
+            (0, node_fs_1.mkdirSync)(profPluginsDir, { recursive: true });
+            try {
+                (0, node_fs_1.rmSync)(symlinkPath, { recursive: true, force: true });
+            }
+            catch { /* not present */ }
+            try {
+                (0, node_fs_1.symlinkSync)(pluginsDir, symlinkPath);
+            }
+            catch (e) {
+                console.log(`  ⚠ Symlink failed for ${profile} (${e instanceof Error ? e.message : e}) — copy manually if needed`);
+            }
+        }
+    }
+    // Activation is left to Hermes' own tooling. We NEVER edit config.yaml —
+    // Hermes' `memory setup` discovers this plugin automatically and writes the
+    // config with its own YAML-aware writer (routing the token to .env).
+    const isRemote = !(serverUrl.includes("127.0.0.1") || serverUrl.includes("localhost"));
+    console.log("  → Activate with:  hermes memory setup   (select 'hicortex')");
+    if ((0, node_fs_1.existsSync)(profilesDir)) {
+        console.log("    Run once per profile if you use Hermes profiles.");
+    }
+    if (isRemote) {
+        console.log("    Remote server: enter the auth token when prompted (stored in $HERMES_HOME/.env).");
+    }
+}
+/**
+ * Parse a KEY=VALUE env file (e.g. ~/.hermes/.env or ~/.claude/settings.json env block).
+ * Handles: comments (#), quoted values, empty lines.
+ * Exported for testability.
+ */
+function parseEnvFile(content) {
+    const result = {};
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eqIdx = line.indexOf("=");
+        if (eqIdx === -1)
+            continue;
+        const key = line.slice(0, eqIdx).trim();
+        if (!key)
+            continue;
+        let value = line.slice(eqIdx + 1).trim();
+        // Strip matching surrounding quotes (single or double)
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
 /**
  * Read LLM config from OC's openclaw.json + auth-profiles.json.
- * Used as fallback when no env vars are set (e.g. Claude Max subscription users).
  */
 function readOcLlmConfig() {
     try {
@@ -299,9 +420,30 @@ function readOcLlmConfig() {
         return null;
     }
 }
+/** Merge candidates by (key, provider) — concatenate source labels. */
+function mergeByKey(candidates) {
+    const seen = new Map();
+    for (const c of candidates) {
+        const dedupeKey = `${c.provider}::${c.key}`;
+        const existing = seen.get(dedupeKey);
+        if (existing) {
+            for (const s of c.sources) {
+                if (!existing.sources.includes(s))
+                    existing.sources.push(s);
+            }
+        }
+        else {
+            seen.set(dedupeKey, { ...c, sources: [...c.sources] });
+        }
+    }
+    return [...seen.values()];
+}
 /**
  * Detect or ask for LLM config and persist to ~/.hicortex/config.json.
  * The daemon can't inherit shell env vars, so we persist here.
+ * LLM choice is always user-controlled: candidates are detected and presented
+ * as a numbered list; the user picks one. Nothing is auto-applied.
+ * If the user cancels, the server runs recall-only (no LLM).
  */
 async function persistLlmConfig() {
     const configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
@@ -316,16 +458,18 @@ async function persistLlmConfig() {
         console.log(`  ✓ LLM config already configured`);
         return;
     }
-    // Auto-detect all available LLM options
+    // -------------------------------------------------------------------------
+    // Detect candidates from all harnesses on this machine
+    // -------------------------------------------------------------------------
+    const { findClaudeBinary } = await import("./llm.js");
     const options = [];
-    // 1. Check Ollama (local models — best for privacy and quality)
+    // 1. Ollama local models (LOCAL)
     const ollamaModels = detectOllamaModels();
     if (ollamaModels.length > 0) {
-        // Pick the largest model — only recommend if >= 7GB (~7b+ parameter models)
         const best = ollamaModels[0]; // already sorted by size desc
         const goodEnough = best.sizeGb >= 7;
         options.push({
-            label: `Ollama ${best.name} (local${best.sizeGb ? `, ${best.sizeGb}GB` : ""}${goodEnough ? "" : ", small model"})`,
+            label: `Ollama ${best.name} (local${best.sizeGb ? `, ${best.sizeGb}GB` : ""}${goodEnough ? "" : ", small model"}) [LOCAL]`,
             recommended: goodEnough,
             save: () => {
                 config.llmBackend = "ollama";
@@ -334,10 +478,9 @@ async function persistLlmConfig() {
                 saveConfig(configPath, config);
             },
         });
-        // Add other models if available
         for (const m of ollamaModels.slice(1, 3)) {
             options.push({
-                label: `Ollama ${m.name} (local${m.sizeGb ? `, ${m.sizeGb}GB` : ""})`,
+                label: `Ollama ${m.name} (local${m.sizeGb ? `, ${m.sizeGb}GB` : ""}) [LOCAL]`,
                 save: () => {
                     config.llmBackend = "ollama";
                     config.llmBaseUrl = "http://localhost:11434";
@@ -347,12 +490,11 @@ async function persistLlmConfig() {
             });
         }
     }
-    // 2. Check Claude CLI
-    const { findClaudeBinary } = await import("./llm.js");
+    // 2. Claude CLI binary (CLOUD — subscription)
     const claudePath = findClaudeBinary();
     if (claudePath) {
         options.push({
-            label: "Claude CLI (subscription, Haiku model)",
+            label: `Claude CLI — ${claudePath} (subscription, cloud)`,
             recommended: ollamaModels.length === 0,
             save: () => {
                 config.llmBackend = "claude-cli";
@@ -360,58 +502,94 @@ async function persistLlmConfig() {
             },
         });
     }
-    // 3. Check env vars
-    if (process.env.ANTHROPIC_API_KEY) {
-        options.push({
-            label: "Anthropic API (from ANTHROPIC_API_KEY)",
-            save: () => {
-                config.llmApiKey = process.env.ANTHROPIC_API_KEY;
-                config.llmBaseUrl = process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com";
-                config.llmProvider = "anthropic";
-                saveConfig(configPath, config);
-            },
-        });
+    // 3. API key candidates: collect from all harness sources, then dedup.
+    const apiKeyCandidates = [];
+    // Helper: note a detected key from a given source
+    function noteKey(key, provider, baseUrl, sourceLabel, model) {
+        if (!key)
+            return;
+        apiKeyCandidates.push({ key, provider, baseUrl, sources: [sourceLabel], model });
     }
-    if (process.env.OPENAI_API_KEY) {
-        options.push({
-            label: "OpenAI API (from OPENAI_API_KEY)",
-            save: () => {
-                config.llmApiKey = process.env.OPENAI_API_KEY;
-                config.llmBaseUrl = process.env.OPENAI_BASE_URL ?? "https://api.openai.com";
-                config.llmProvider = "openai";
-                saveConfig(configPath, config);
-            },
-        });
+    // Process env vars (detection only — not silent defaults)
+    const envProviders = [
+        { envKey: "ANTHROPIC_API_KEY", provider: "anthropic", baseUrlEnv: "ANTHROPIC_BASE_URL", defaultBaseUrl: "https://api.anthropic.com" },
+        { envKey: "OPENAI_API_KEY", provider: "openai", baseUrlEnv: "OPENAI_BASE_URL", defaultBaseUrl: "https://api.openai.com" },
+        { envKey: "GOOGLE_API_KEY", provider: "google", defaultBaseUrl: "https://generativelanguage.googleapis.com/v1beta" },
+    ];
+    for (const ep of envProviders) {
+        const val = process.env[ep.envKey];
+        if (val) {
+            const baseUrl = (ep.baseUrlEnv ? process.env[ep.baseUrlEnv] : undefined) ?? ep.defaultBaseUrl;
+            noteKey(val, ep.provider, baseUrl, "from environment, cloud");
+        }
     }
-    // 4. Check OC auth-profiles
+    // Hermes .env file (read-only parsing, no editing)
+    try {
+        const hermesEnvPath = (0, node_path_1.join)(HERMES_HOME, ".env");
+        const hermesEnvContent = (0, node_fs_1.readFileSync)(hermesEnvPath, "utf-8");
+        const hermesEnv = parseEnvFile(hermesEnvContent);
+        const openaiBase = hermesEnv["OPENAI_BASE_URL"];
+        for (const ep of envProviders) {
+            const val = hermesEnv[ep.envKey];
+            if (val) {
+                const baseUrl = (ep.baseUrlEnv && hermesEnv[ep.baseUrlEnv])
+                    ? hermesEnv[ep.baseUrlEnv]
+                    : (openaiBase && ep.provider === "openai" ? openaiBase : ep.defaultBaseUrl);
+                noteKey(val, ep.provider, baseUrl, "detected in Hermes .env, cloud");
+            }
+        }
+    }
+    catch { /* no Hermes .env or unreadable — skip */ }
+    // Claude Code settings.json env block (read-only parsing)
+    try {
+        const ccSettings = JSON.parse((0, node_fs_1.readFileSync)(CC_SETTINGS, "utf-8"));
+        const ccEnv = ccSettings?.env ?? {};
+        for (const ep of envProviders) {
+            const val = ccEnv[ep.envKey];
+            if (typeof val === "string" && val) {
+                const baseUrl = (ep.baseUrlEnv && typeof ccEnv[ep.baseUrlEnv] === "string")
+                    ? ccEnv[ep.baseUrlEnv]
+                    : ep.defaultBaseUrl;
+                noteKey(val, ep.provider, baseUrl, "detected in Claude Code settings, cloud");
+            }
+        }
+    }
+    catch { /* no CC settings or unreadable — skip */ }
+    // OpenClaw auth-profiles (existing helper)
     const ocLlm = readOcLlmConfig();
     if (ocLlm) {
+        noteKey(ocLlm.apiKey, ocLlm.provider, ocLlm.baseUrl, "detected in OpenClaw config, cloud", ocLlm.model);
+    }
+    // Deduplicate by (provider, key) and build options
+    for (const candidate of mergeByKey(apiKeyCandidates)) {
+        const sourceStr = candidate.sources.join(", ");
+        const modelStr = candidate.model ? ` — ${candidate.model}` : "";
         options.push({
-            label: `OpenClaw (${ocLlm.provider}/${ocLlm.model ?? "default"})`,
+            label: `${candidate.provider}${modelStr} (${sourceStr})`,
             save: () => {
-                config.llmApiKey = ocLlm.apiKey;
-                config.llmBaseUrl = ocLlm.baseUrl;
-                config.llmProvider = ocLlm.provider;
-                if (ocLlm.model)
-                    config.llmModel = ocLlm.model;
+                config.llmApiKey = candidate.key;
+                config.llmBaseUrl = candidate.baseUrl;
+                config.llmProvider = candidate.provider;
+                if (candidate.model)
+                    config.llmModel = candidate.model;
                 saveConfig(configPath, config);
             },
         });
     }
-    // 5. Always offer manual entry and cancel
+    // 4. Manual entry (always available)
     options.push({
-        label: "Other provider (requires API key)",
+        label: "Enter provider manually (API key required)",
         save: async () => {
             console.log("\n  Providers: Anthropic, OpenAI, Google, OpenRouter, or any OpenAI-compatible endpoint");
             const baseUrl = await ask("  Provider base URL: ");
             if (!baseUrl) {
-                console.log("  ⚠ Cancelled.");
-                process.exit(0);
+                console.log("  Cancelled — server will run recall-only until you re-run init.");
+                return;
             }
             const apiKey = await ask("  API key: ");
             if (!apiKey) {
-                console.log("  ⚠ Cancelled.");
-                process.exit(0);
+                console.log("  Cancelled — server will run recall-only until you re-run init.");
+                return;
             }
             const model = await ask("  Model name (optional): ");
             config.llmApiKey = apiKey;
@@ -421,30 +599,51 @@ async function persistLlmConfig() {
             saveConfig(configPath, config);
         },
     });
+    // 5. Skip / recall-only (always available)
     options.push({
-        label: "Cancel installation",
+        label: "Skip — run recall-only for now (configure later with: npx @gamaze/hicortex init)",
         save: () => {
-            console.log("\n  Hicortex requires an LLM to function. Installation cancelled.");
-            process.exit(0);
+            // Intentionally leave no LLM config — server starts recall-only.
         },
     });
-    // Find recommended index
+    // -------------------------------------------------------------------------
+    // Always prompt — never auto-apply even if exactly one candidate detected
+    // -------------------------------------------------------------------------
+    // Non-interactive stdin (piped/scripted init): a readline EOF resolves as ""
+    // and would silently select the recommended default — an auto-apply. LLM
+    // choice is user-controlled by design: skip instead.
+    if (!process.stdin.isTTY) {
+        console.log("  ⚠ Non-interactive stdin — skipping LLM selection (user-controlled by design).\n" +
+            "    The server runs recall-only until you configure an LLM: re-run `hicortex init`\n" +
+            "    interactively, or set llmBackend/llmBaseUrl/llmApiKey in ~/.hicortex/config.json.");
+        return;
+    }
     const recommendedIdx = options.findIndex(o => o.recommended);
     const defaultIdx = recommendedIdx >= 0 ? recommendedIdx : 0;
-    // Display
-    console.log("\n  LLM for nightly distillation:\n");
+    console.log("\n  LLM for nightly distillation and consolidation:\n");
+    if (options.length === 2) {
+        // Only "manual" and "skip" — nothing detected
+        console.log("  No LLM detected automatically on this machine.");
+    }
     for (let i = 0; i < options.length; i++) {
         const marker = i === defaultIdx ? " (recommended)" : "";
         console.log(`    ${i + 1}. ${options[i].label}${marker}`);
     }
     const choice = await ask(`\n  Choice [${defaultIdx + 1}]: `);
-    const selected = choice ? parseInt(choice, 10) - 1 : defaultIdx;
-    if (selected < 0 || selected >= options.length) {
-        console.log("  Invalid choice.");
-        process.exit(1);
+    const selectedIdx = choice.trim() ? parseInt(choice.trim(), 10) - 1 : defaultIdx;
+    if (isNaN(selectedIdx) || selectedIdx < 0 || selectedIdx >= options.length) {
+        console.log("  Invalid choice — server will run recall-only until you re-run init.");
+        return;
+    }
+    await options[selectedIdx].save();
+    const selectedLabel = options[selectedIdx].label;
+    if (selectedLabel.startsWith("Skip")) {
+        console.log("  No LLM configured — server will run recall-only (search/lessons/context work).\n" +
+            "  To enable capture and consolidation later, run: npx @gamaze/hicortex init");
+    }
+    else {
+        console.log(`  ✓ LLM configured: ${selectedLabel}`);
     }
-    await options[selected].save();
-    console.log(`  ✓ LLM configured: ${options[selected].label}`);
 }
 function detectOllamaModels() {
     try {
@@ -470,6 +669,34 @@ function saveConfig(configPath, config) {
     (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
     (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
 }
+/**
+ * Generate a random auth token in the format hctx-<32 hex chars>.
+ * Exported for testability.
+ */
+function generateAuthToken() {
+    return `hctx-${(0, node_crypto_1.randomBytes)(16).toString("hex")}`;
+}
+/**
+ * Ensure a server-mode auth token exists in config.json.
+ * Generates and saves one if absent. Never overwrites an existing token.
+ * Returns the token (existing or newly generated).
+ * Exported for testability.
+ */
+function persistAuthToken(configPath) {
+    let config = {};
+    try {
+        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    }
+    catch { /* new file */ }
+    if (config.authToken && typeof config.authToken === "string") {
+        return { token: config.authToken, generated: false };
+    }
+    const token = generateAuthToken();
+    config.authToken = token;
+    (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
+    (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(config, null, 2));
+    return { token, generated: true };
+}
 /**
  * Determine the npm package specifier for the daemon.
  * Uses tag-based resolution so restarts pick up new versions automatically.
@@ -494,16 +721,15 @@ function getPackageSpec() {
 }
 function installDaemon() {
     const os = (0, node_os_1.platform)();
-    const npxPath = findNpxPath();
-    const packageSpec = getPackageSpec();
+    const binaryArgs = resolveBinaryArgs();
     if (os === "darwin") {
-        return installLaunchd(npxPath, packageSpec);
+        return installLaunchd(binaryArgs);
     }
     else if (os === "linux") {
-        return installSystemd(npxPath, packageSpec);
+        return installSystemd(binaryArgs);
     }
     else {
-        console.log(`  ⚠ Unsupported platform: ${os}. Start the server manually: npx ${packageSpec} server`);
+        console.log(`  ⚠ Unsupported platform: ${os}. Start the server manually: ${[...binaryArgs, "server"].join(" ")}`);
         return false;
     }
 }
@@ -515,11 +741,100 @@ function findNpxPath() {
         return "/usr/local/bin/npx";
     }
 }
-function installLaunchd(npxPath, packageSpec) {
+/**
+ * Resolve the absolute path of the hicortex binary.
+ * For global npm installs (e.g. /usr/bin/hicortex) this is the binary itself.
+ * For dev/npx installs, falls back to `npx <packageSpec> <command>` form.
+ * Returns an array: [binaryPath] for global, or [npxPath, "-y", packageSpec] for npx.
+ */
+function resolveBinaryArgs() {
+    try {
+        const bin = (0, node_child_process_1.execSync)("which hicortex", { encoding: "utf-8" }).trim();
+        if (bin)
+            return [bin];
+    }
+    catch { /* not in PATH as a global binary */ }
+    const npxPath = findNpxPath();
+    const packageSpec = getPackageSpec();
+    return [npxPath, "-y", packageSpec];
+}
+/**
+ * Install (or verify) the CC SessionStart hook that runs `hicortex lessons-context`.
+ * The hook fetches lessons from the configured server at session start and injects
+ * them as context — replacing the old static CLAUDE.md block.
+ *
+ * Idempotent: skips if a SessionStart hook containing "lessons-context" already exists.
+ * Uses JSON.parse/JSON.stringify to safely merge into ~/.claude/settings.json.
+ *
+ * @param settingsPath Override for the settings.json path (used in tests; defaults to CC_SETTINGS).
+ */
+function installSessionStartHook(settingsPath) {
+    const targetPath = settingsPath ?? CC_SETTINGS;
+    const binaryArgs = resolveBinaryArgs();
+    // Build the command string: "/path/to/hicortex lessons-context" or "npx -y @gamaze/hicortex lessons-context"
+    const command = [...binaryArgs, "lessons-context"].join(" ");
+    let settings = {};
+    if ((0, node_fs_1.existsSync)(targetPath)) {
+        try {
+            settings = JSON.parse((0, node_fs_1.readFileSync)(targetPath, "utf-8"));
+        }
+        catch {
+            // File exists but is malformed — do NOT overwrite (would destroy the user's entire CC config).
+            console.log(`  ⚠ ${targetPath} exists but is not valid JSON — skipping SessionStart hook.`);
+            console.log(`    Fix the file, then re-run init, or add the hook manually:`);
+            console.log(`    command: "${command}"`);
+            return;
+        }
+    }
+    // Ensure hooks object and SessionStart array exist
+    if (!settings.hooks || typeof settings.hooks !== "object") {
+        settings.hooks = {};
+    }
+    const hooks = settings.hooks;
+    if (!Array.isArray(hooks.SessionStart)) {
+        hooks.SessionStart = [];
+    }
+    const sessionStart = hooks.SessionStart;
+    // Idempotent: skip if any existing entry's command contains "lessons-context"
+    const alreadyInstalled = sessionStart.some((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return false;
+        const e = entry;
+        // CC hook format: { hooks: [{ type: "command", command: "..." }] }
+        if (Array.isArray(e.hooks)) {
+            return e.hooks.some((h) => {
+                if (typeof h !== "object" || h === null)
+                    return false;
+                const hook = h;
+                return typeof hook.command === "string" && hook.command.includes("lessons-context");
+            });
+        }
+        return false;
+    });
+    if (alreadyInstalled) {
+        console.log(`  ✓ SessionStart hook already installed`);
+        return;
+    }
+    sessionStart.push({
+        hooks: [{ type: "command", command, timeout: 10 }],
+    });
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(targetPath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(targetPath, JSON.stringify(settings, null, 2));
+    console.log(`  ✓ Installed SessionStart hook: ${command}`);
+}
+function installLaunchd(binaryArgs) {
     const plistDir = (0, node_path_1.join)((0, node_os_1.homedir)(), "Library", "LaunchAgents");
     const plistPath = (0, node_path_1.join)(plistDir, "com.gamaze.hicortex.plist");
     const logPath = (0, node_path_1.join)(HICORTEX_HOME, "server.log");
     const errLogPath = (0, node_path_1.join)(HICORTEX_HOME, "server-err.log");
+    // Build ProgramArguments as individual <string> elements.
+    const programArgs = [...binaryArgs, "server"]
+        .map((a) => `    <string>${a}</string>`)
+        .join("\n");
+    // PATH must start with the binary's own directory so the sibling node
+    // binary (correct version for nvm installs) is found first.
+    // launchd has no PATH by default; without this, node itself won't be found.
+    const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -528,10 +843,7 @@ function installLaunchd(npxPath, packageSpec) {
   <string>com.gamaze.hicortex</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${npxPath}</string>
-    <string>-y</string>
-    <string>${packageSpec}</string>
-    <string>server</string>
+${programArgs}
   </array>
   <key>KeepAlive</key>
   <true/>
@@ -544,7 +856,7 @@ function installLaunchd(npxPath, packageSpec) {
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${(0, node_path_1.dirname)(npxPath)}:/usr/local/bin:/usr/bin:/bin</string>
+    <string>${binDir}:/usr/local/bin:/usr/bin:/bin</string>
   </dict>
 </dict>
 </plist>`;
@@ -566,20 +878,23 @@ function installLaunchd(npxPath, packageSpec) {
         return false;
     }
 }
-function installSystemd(npxPath, packageSpec) {
+function installSystemd(binaryArgs) {
     const unitDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "systemd", "user");
     const servicePath = (0, node_path_1.join)(unitDir, "hicortex.service");
+    const execStart = [...binaryArgs, "server"].join(" ");
+    // PATH must start with the binary's own directory (see installLaunchd for rationale).
+    const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
     const service = `[Unit]
 Description=Hicortex MCP server — long-term memory for AI agents
 
 [Service]
 Type=simple
-ExecStart=${npxPath} -y ${packageSpec} server
+ExecStart=${execStart}
 Restart=on-failure
 RestartSec=10
 StandardOutput=journal
 StandardError=journal
-Environment=PATH=${(0, node_path_1.dirname)(npxPath)}:/usr/local/bin:/usr/bin:/bin
+Environment=PATH=${binDir}:/usr/local/bin:/usr/bin:/bin
 
 [Install]
 WantedBy=default.target
@@ -629,6 +944,8 @@ async function runInit(options = {}) {
         console.log(`  • Remote server at ${d.remoteServerUrl} (${d.memoryCount ?? "?"} memories)`);
     if (d.ocPlugin)
         console.log("  • OpenClaw plugin installed");
+    if (d.hermesFound)
+        console.log(`  • Hermes found at ${HERMES_HOME}`);
     if (d.ccMcpRegistered)
         console.log("  • CC MCP already registered");
     if (d.existingDb)
@@ -658,8 +975,10 @@ async function runInit(options = {}) {
         actions.push("Install Hicortex server daemon");
     if (!d.ccMcpRegistered)
         actions.push("Register MCP server in CC settings");
+    if (d.hermesFound)
+        actions.push("Install Hermes plugin + configure");
     actions.push("Install /learn and /hicortex-activate commands");
-    actions.push("Add Hicortex Learnings block to CLAUDE.md");
+    actions.push("Install SessionStart hook (query-time lessons)");
     if (actions.length === 0) {
         console.log("Everything is already configured. Nothing to do.");
         return;
@@ -676,6 +995,20 @@ async function runInit(options = {}) {
     // Phase 3: Execute
     // Persist LLM config for the daemon
     await persistLlmConfig();
+    // Generate and persist auth token (upgrade-safe: never overwrites existing token).
+    const configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
+    const { token: authToken, generated: tokenGenerated } = persistAuthToken(configPath);
+    if (tokenGenerated) {
+        console.log(`\n  Auth token for clients: ${authToken}`);
+        console.log(`  (stored in ~/.hicortex/config.json — also shown by \`hicortex status\`)\n`);
+    }
+    else {
+        console.log(`  ✓ Auth token already configured`);
+    }
+    // Install the nightly job (capture via localhost /distill + consolidation).
+    // Without it a server-mode install never captures or consolidates — the
+    // daemon only serves recall + /distill. Skips if a schedule already exists.
+    installNightlyCron(resolveNightlyHour("server"));
     // Install daemon if needed
     if (!d.localServer && !d.remoteServer) {
         installDaemon();
@@ -704,41 +1037,31 @@ async function runInit(options = {}) {
     allowHicortexTools();
     // Install CC commands
     installCcCommands();
-    // Inject CLAUDE.md (only if server has a DB we can read)
-    // For now, just create the block with agent guidance and no lessons
-    // Lessons will populate on first nightly run
-    const claudeMdPath = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
-    if (!(0, node_fs_1.existsSync)(claudeMdPath) || !(0, node_fs_1.readFileSync)(claudeMdPath, "utf-8").includes("HICORTEX-LEARNINGS")) {
-        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(claudeMdPath), { recursive: true });
-        let content = "";
-        try {
-            content = (0, node_fs_1.readFileSync)(claudeMdPath, "utf-8");
-        }
-        catch { /* new file */ }
-        const block = [
-            "<!-- HICORTEX-LEARNINGS:START -->",
-            "## Hicortex Memory",
-            "",
-            "You have access to long-term memory via Hicortex MCP tools. Use `hicortex_search` when you need context from past sessions, decisions, or prior work. Use `hicortex_context` at session start to recall recent project state. Use `hicortex_ingest` to save important decisions or learnings. Sessions are auto-captured nightly.",
-            "<!-- HICORTEX-LEARNINGS:END -->",
-        ].join("\n");
-        if (content.length > 0 && !content.endsWith("\n"))
-            content += "\n";
-        if (content.length > 0)
-            content += "\n";
-        content += block + "\n";
-        (0, node_fs_1.writeFileSync)(claudeMdPath, content);
-        console.log(`  ✓ Added Hicortex Learnings block to ${claudeMdPath}`);
+    // Setup Hermes if detected
+    if (d.hermesFound) {
+        // localhost bypass makes the token optional for co-located installs;
+        // pass it for remote setups so setupHermes can include it in its instructions.
+        const isLocal = serverUrl.includes("127.0.0.1") || serverUrl.includes("localhost");
+        setupHermes(serverUrl, isLocal ? "" : authToken);
     }
-    else {
-        console.log(`  ✓ CLAUDE.md already has Hicortex Learnings block`);
+    // Install CC SessionStart hook for query-time lesson injection.
+    // Lessons are now fetched live at session start — no static CLAUDE.md block needed.
+    installSessionStartHook();
+    // Strip the old static lessons block from CLAUDE.md (0.9.0 migration).
+    // Lessons are now delivered via the SessionStart hook instead.
+    const claudeMdPath = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
+    if ((0, claude_md_js_1.removeLessonsBlock)(claudeMdPath)) {
+        console.log(`  ✓ Removed old static lessons block from ${claudeMdPath} — lessons now injected at session start`);
     }
     console.log("\n✓ Hicortex setup complete!\n");
     console.log("Next steps:");
-    console.log("  1. Restart Claude Code to pick up the new MCP server");
-    console.log("  2. Ask your agent: 'What Hicortex tools do you have?'");
-    console.log("  3. Try /learn to save something to long-term memory");
-    console.log(`  4. Check server: curl ${serverUrl}/health`);
+    console.log("  1. Restart Claude Code to pick up the new MCP server and SessionStart hook");
+    if (d.hermesFound) {
+        console.log("  2. Activate the Hermes plugin: run `hermes memory setup`, select 'hicortex', then restart the gateway(s)");
+    }
+    console.log("  3. Ask your agent: 'What Hicortex tools do you have?'");
+    console.log("  4. Try /learn to save something to long-term memory");
+    console.log(`  5. Check server: curl ${serverUrl}/health`);
 }
 // ---------------------------------------------------------------------------
 // Client Mode Init
@@ -761,22 +1084,22 @@ async function runClientInit(serverUrl) {
         console.error(`\n  Make sure the Hicortex server is running and accessible.`);
         process.exit(1);
     }
-    // Step 2: Auth — try default token first, prompt only if rejected
-    const DEFAULT_AUTH_TOKEN = "hctx-default-token";
-    let authToken = DEFAULT_AUTH_TOKEN;
+    // Step 2: Auth — probe with no token; if 401, ask the user.
+    // The server's token is shown by `hicortex status` on the server box,
+    // or readable from ~/.hicortex/config.json on that machine.
+    let authToken = "";
     try {
         const probe = await fetch(`${serverUrl}/ingest`, {
             method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "Authorization": `Bearer ${DEFAULT_AUTH_TOKEN}`,
-            },
+            headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ content: "" }),
             signal: AbortSignal.timeout(5000),
         });
         if (probe.status === 401) {
-            // Server uses a custom token — ask the user
-            const tokenAnswer = await ask("\nServer uses a custom auth token. Enter token: ");
+            // Server requires a token — ask the user where to get it
+            console.log("\n  Server requires an auth token.");
+            console.log("  Find it on the server: run `hicortex status`, or read ~/.hicortex/config.json");
+            const tokenAnswer = await ask("  Enter token: ");
             authToken = tokenAnswer.trim();
             if (!authToken) {
                 console.error("  ✗ Auth token required but not provided.");
@@ -796,99 +1119,128 @@ async function runClientInit(serverUrl) {
                 console.error("  ✗ Auth token rejected by server.");
                 process.exit(1);
             }
-            console.log("  ✓ Custom auth token verified");
+            console.log("  ✓ Auth token verified");
         }
         else {
-            console.log("  ✓ Server connected (default auth)");
+            console.log("  ✓ Server connected (no auth required from localhost)");
         }
     }
     catch {
-        // Probe failed but health passed — continue with default token
+        // Probe failed but health passed — continue without token
     }
-    // Step 3: Configure LLM for local distillation
-    console.log("\nConfigure LLM for local session distillation:");
-    await persistLlmConfig();
-    // Step 4: Save client config
+    // Client mode needs no LLM — capture is denoise-only; the server distills.
+    // Step 3: Save client config
     (0, node_fs_1.mkdirSync)(HICORTEX_HOME, { recursive: true });
     const configPath = (0, node_path_1.join)(HICORTEX_HOME, "config.json");
     let config = {};
-    try {
-        config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+    if ((0, node_fs_1.existsSync)(configPath)) {
+        try {
+            config = JSON.parse((0, node_fs_1.readFileSync)(configPath, "utf-8"));
+        }
+        catch {
+            console.log(`  ⚠ ${configPath} exists but is not valid JSON — starting with empty config (licenseKey and LLM settings may need to be re-entered).`);
+        }
     }
-    catch { }
     config.mode = "client";
     config.serverUrl = serverUrl;
     if (authToken)
         config.authToken = authToken;
     saveConfig(configPath, config);
     console.log(`  ✓ Client config saved to ${configPath}`);
-    // Step 5: Register CC MCP pointing to remote server
+    // Step 4: Register CC MCP pointing to remote server
     if (authToken) {
         // Write directly with auth header
         const claudeJsonPath = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude.json");
         let claudeConfig = {};
-        try {
-            claudeConfig = JSON.parse((0, node_fs_1.readFileSync)(claudeJsonPath, "utf-8"));
+        let claudeJsonOk = true;
+        if ((0, node_fs_1.existsSync)(claudeJsonPath)) {
+            try {
+                claudeConfig = JSON.parse((0, node_fs_1.readFileSync)(claudeJsonPath, "utf-8"));
+            }
+            catch {
+                console.log(`  ⚠ ${claudeJsonPath} exists but is not valid JSON — skipping MCP registration. Fix the file, then re-run init or run: claude mcp add hicortex --transport sse ${serverUrl}/sse`);
+                claudeJsonOk = false;
+            }
+        }
+        if (claudeJsonOk) {
+            if (!claudeConfig.mcpServers)
+                claudeConfig.mcpServers = {};
+            claudeConfig.mcpServers.hicortex = {
+                type: "sse",
+                url: `${serverUrl}/sse`,
+                headers: { "Authorization": `Bearer ${authToken}` },
+            };
+            (0, node_fs_1.writeFileSync)(claudeJsonPath, JSON.stringify(claudeConfig, null, 2));
+            console.log(`  ✓ Registered MCP server with auth`);
         }
-        catch { }
-        if (!claudeConfig.mcpServers)
-            claudeConfig.mcpServers = {};
-        claudeConfig.mcpServers.hicortex = {
-            type: "sse",
-            url: `${serverUrl}/sse`,
-            headers: { "Authorization": `Bearer ${authToken}` },
-        };
-        (0, node_fs_1.writeFileSync)(claudeJsonPath, JSON.stringify(claudeConfig, null, 2));
-        console.log(`  ✓ Registered MCP server with auth`);
     }
     else {
         registerCcMcp(serverUrl);
     }
     allowHicortexTools();
-    // Step 6: Install CC commands
+    // Step 5: Install CC commands
     installCcCommands();
-    // Step 7: Inject CLAUDE.md learnings block
+    // Step 6: Install SessionStart hook for query-time lessons.
+    installSessionStartHook();
+    // Strip the old static CLAUDE.md lessons block if present (0.9.0 migration).
     const claudeMdPath = (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude", "CLAUDE.md");
-    if (!(0, node_fs_1.existsSync)(claudeMdPath) || !(0, node_fs_1.readFileSync)(claudeMdPath, "utf-8").includes("HICORTEX-LEARNINGS")) {
-        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(claudeMdPath), { recursive: true });
-        let content = "";
-        try {
-            content = (0, node_fs_1.readFileSync)(claudeMdPath, "utf-8");
-        }
-        catch { }
-        const block = [
-            "<!-- HICORTEX-LEARNINGS:START -->",
-            "## Hicortex Memory",
-            "",
-            "You have access to long-term memory via Hicortex MCP tools. Use `hicortex_search` when you need context from past sessions, decisions, or prior work. Use `hicortex_context` at session start to recall recent project state. Use `hicortex_ingest` to save important decisions or learnings. Sessions are auto-captured nightly.",
-            "<!-- HICORTEX-LEARNINGS:END -->",
-        ].join("\n");
-        if (content.length > 0 && !content.endsWith("\n"))
-            content += "\n";
-        if (content.length > 0)
-            content += "\n";
-        content += block + "\n";
-        (0, node_fs_1.writeFileSync)(claudeMdPath, content);
-        console.log(`  ✓ Added Hicortex Learnings block`);
-    }
-    // Step 8: Install nightly cron (distill locally, POST to server)
-    installNightlyCron();
+    if ((0, claude_md_js_1.removeLessonsBlock)(claudeMdPath)) {
+        console.log(`  ✓ Removed old static lessons block from CLAUDE.md — lessons now injected at session start`);
+    }
+    // Step 7: Install nightly cron (denoise locally, POST to server /distill)
+    installNightlyCron(resolveNightlyHour("client"));
+    // Step 8: Setup Hermes if detected
+    if ((0, node_fs_1.existsSync)(HERMES_HOME)) {
+        console.log("\nHermes detected — installing plugin...");
+        setupHermes(serverUrl, authToken);
+    }
     console.log("\n✓ Hicortex client setup complete!\n");
     console.log("How it works:");
     console.log("  • MCP tools (search, context, ingest) talk to the remote server");
-    console.log("  • Nightly pipeline distills CC transcripts locally, POSTs memories to server");
+    console.log("  • Nightly pipeline denoises CC transcripts, POSTs to server for distillation");
+    console.log("  • Lessons fetched live at each CC session start (SessionStart hook)");
     console.log("  • No local database — all memories stored on the server");
+    if ((0, node_fs_1.existsSync)(HERMES_HOME)) {
+        console.log("  • Hermes plugin installed — run `hermes memory setup` (select 'hicortex') + restart gateway(s) to activate");
+    }
     console.log(`\nServer: ${serverUrl}`);
-    console.log("Restart Claude Code to activate.");
+    console.log("Restart your agents to activate.");
 }
-function installNightlyCron() {
-    const npxPath = findNpxPath();
-    const packageSpec = getPackageSpec();
+/**
+ * Resolve the nightly hour (0–23, local time) for the generated schedule.
+ * Priority: `nightlyHour` in ~/.hicortex/config.json → mode default.
+ * Defaults: client 02:00, server 03:00 — staggered so that in mixed fleets
+ * clients push their sessions before the server's capture + consolidation run.
+ */
+function resolveNightlyHour(mode, configDir = HICORTEX_HOME) {
+    try {
+        const config = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(configDir, "config.json"), "utf-8"));
+        const h = config.nightlyHour;
+        if (typeof h === "number" && Number.isInteger(h) && h >= 0 && h <= 23)
+            return h;
+    }
+    catch { /* no config yet — use the default */ }
+    return mode === "server" ? 3 : 2;
+}
+function installNightlyCron(hour) {
+    const binaryArgs = resolveBinaryArgs();
     const os = (0, node_os_1.platform)();
+    const hh = String(hour).padStart(2, "0");
+    // PATH must start with the binary's own directory (see installLaunchd for rationale).
+    const binDir = (0, node_path_1.dirname)(binaryArgs[0]);
     if (os === "darwin") {
         const plistDir = (0, node_path_1.join)((0, node_os_1.homedir)(), "Library", "LaunchAgents");
         const plistPath = (0, node_path_1.join)(plistDir, "com.gamaze.hicortex-nightly.plist");
         const logPath = (0, node_path_1.join)(HICORTEX_HOME, "nightly.log");
+        // Never overwrite an existing schedule — users tune these (multi-slot
+        // capture windows, quiet hours). Fresh installs only.
+        if ((0, node_fs_1.existsSync)(plistPath)) {
+            console.log(`  ✓ Nightly cron already installed — leaving existing schedule as-is`);
+            return;
+        }
+        const programArgs = [...binaryArgs, "nightly"]
+            .map((a) => `    <string>${a}</string>`)
+            .join("\n");
         const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -897,15 +1249,12 @@ function installNightlyCron() {
   <string>com.gamaze.hicortex-nightly</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${npxPath}</string>
-    <string>-y</string>
-    <string>${packageSpec}</string>
-    <string>nightly</string>
+${programArgs}
   </array>
   <key>StartCalendarInterval</key>
   <dict>
     <key>Hour</key>
-    <integer>2</integer>
+    <integer>${hour}</integer>
     <key>Minute</key>
     <integer>0</integer>
   </dict>
@@ -916,7 +1265,7 @@ function installNightlyCron() {
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${(0, node_path_1.dirname)(npxPath)}:/usr/local/bin:/usr/bin:/bin</string>
+    <string>${binDir}:/usr/local/bin:/usr/bin:/bin</string>
   </dict>
 </dict>
 </plist>`;
@@ -928,7 +1277,7 @@ function installNightlyCron() {
             }
             catch { }
             (0, node_child_process_1.execSync)(`launchctl load ${plistPath}`, { stdio: "pipe" });
-            console.log(`  ✓ Installed nightly cron (runs daily at 02:00)`);
+            console.log(`  ✓ Installed nightly cron (runs daily at ${hh}:00)`);
         }
         catch {
             console.log(`  ⚠ Could not load nightly plist. Load manually: launchctl load ${plistPath}`);
@@ -938,20 +1287,26 @@ function installNightlyCron() {
         const configDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "systemd", "user");
         const servicePath = (0, node_path_1.join)(configDir, "hicortex-nightly.service");
         const timerPath = (0, node_path_1.join)(configDir, "hicortex-nightly.timer");
+        // Never overwrite an existing schedule — users tune these. Fresh installs only.
+        if ((0, node_fs_1.existsSync)(timerPath)) {
+            console.log(`  ✓ Nightly timer already installed — leaving existing schedule as-is`);
+            return;
+        }
+        const execStart = [...binaryArgs, "nightly"].join(" ");
         const service = `[Unit]
 Description=Hicortex Nightly (distill + POST)
 
 [Service]
 Type=oneshot
-ExecStart=${npxPath} -y ${packageSpec} nightly
-Environment=PATH=/usr/local/bin:/usr/bin:/bin
+ExecStart=${execStart}
+Environment=PATH=${binDir}:/usr/local/bin:/usr/bin:/bin
 Environment=HOME=${(0, node_os_1.homedir)()}
 WorkingDirectory=${(0, node_os_1.homedir)()}`;
         const timer = `[Unit]
 Description=Hicortex Nightly Timer
 
 [Timer]
-OnCalendar=*-*-* 02:00:00
+OnCalendar=*-*-* ${hh}:00:00
 Persistent=true
 
 [Install]
@@ -962,7 +1317,7 @@ WantedBy=timers.target`;
         try {
             (0, node_child_process_1.execSync)("systemctl --user daemon-reload", { stdio: "pipe" });
             (0, node_child_process_1.execSync)("systemctl --user enable --now hicortex-nightly.timer", { stdio: "pipe" });
-            console.log(`  ✓ Installed nightly timer (runs daily at 02:00)`);
+            console.log(`  ✓ Installed nightly timer (runs daily at ${hh}:00)`);
         }
         catch {
             console.log(`  ⚠ Could not enable nightly timer. Enable manually: systemctl --user enable --now hicortex-nightly.timer`);