@cachly-dev/mcp-server 0.10.121 → 0.10.123

package/dist/src/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { jwtExpiryMs, checkJwt, handleApiError, diagnoseAuth, planAuthHeal, readClientCredentialsFromEnv, buildClientCredentialsBody, clientCredentialsTokenUrl } from './auth.js';
+import { cachlyUrl } from './cachly-url.js';
 import { notify } from './notifier.js';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
@@ -52,7 +53,7 @@ import { Redis } from 'ioredis';
 // Mutable so the `setup`/`init` CLI can honor a `--api-url` flag for self-hosting.
 // Reassigned (if at all) before any network call is made.
 let API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
-let JWT = process.env.CACHLY_JWT ?? '';
+let JWT = resolveApiKey() ?? '';
 const _EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
 // Resolve the package version at runtime from package.json so the telemetry
 // `version` field always matches the published npm version. A hardcoded constant
@@ -218,9 +219,11 @@ async function persistApiKeyToConfig(apiKey) {
             existing.env['CACHLY_JWT'] = apiKey;
         }
         else {
+            const freshEnv = {};
+            freshEnv['CACHLY_JWT'] = apiKey;
             cfg.mcpServers['cachly'] = {
                 command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'],
-                env: { CACHLY_JWT: apiKey },
+                env: freshEnv,
             };
         }
         await mkdir(dirname(claudePath), { recursive: true });
@@ -378,7 +381,7 @@ async function startDeviceFlow() {
         if (res.ok) {
             const data = await res.json();
             // Append the user_code so the web page (cachly.dev/device?code=…) auto-submits.
-            const base = data.verification_uri || 'https://cachly.dev/device';
+            const base = data.verification_uri || cachlyUrl('/device', 'ambient-signin');
             const verifyUrl = `${base}${base.includes('?') ? '&' : '?'}code=${encodeURIComponent(data.user_code)}`;
             return {
                 deviceCode: data.device_code,
@@ -472,6 +475,9 @@ async function pollDeviceFlow(flow) {
             // keep the token. Without this, JWT is lost on restart and brain_recall_count
             // is never incremented (telemetry has no api_key → no tenant resolution).
             void persistApiKeyToConfig(apiKey);
+            // GROW-015: also persist to ~/.cachly/credentials.json — the source the
+            // ambient hooks (bare OS processes, no MCP-config env) resolve at run time.
+            saveApiKey(apiKey);
             // Auto-provision: find or create the user's brain instance. resolveDefaultInstanceId
             // now lists existing instances and auto-provisions when the account has none,
             // so a single call covers both paths (and self-heals on every later tool call
@@ -627,20 +633,20 @@ async function getConnection(instance_id) {
         }
         else if (inst.status === 'failed') {
             hint = `❌ Brain instance "${inst.name}" failed to start.\n\n` +
-                `Our system will retry automatically. Check status at: https://cachly.dev/instances\n` +
+                `Our system will retry automatically. Check status at: ${cachlyUrl('/instances', 'instance-error')}\n` +
                 `If this persists, contact support@cachly.dev.`;
         }
         else if (inst.status === 'suspended') {
             hint = `⏸ Brain instance "${inst.name}" is suspended (billing issue).\n\n` +
-                `Update your payment method at: https://cachly.dev/billing`;
+                `Update your payment method at: ${cachlyUrl('/billing', 'upgrade')}`;
         }
         else if (inst.status === 'pending_payment') {
             hint = `💳 Brain instance "${inst.name}" is waiting for payment.\n\n` +
-                `Complete your checkout at: https://cachly.dev/instances`;
+                `Complete your checkout at: ${cachlyUrl('/instances', 'upgrade')}`;
         }
         else {
             hint = `Brain instance "${inst.name}" is not reachable (status: ${inst.status}).\n\n` +
-                `• View your instance at: https://cachly.dev/instances\n` +
+                `• View your instance at: ${cachlyUrl('/instances', 'instance-error')}\n` +
                 `• Run \`get_api_status\` for a full diagnostic.`;
         }
         throw new McpError(ErrorCode.InvalidRequest, hint);
@@ -754,14 +760,19 @@ import { handleRoadmapTool } from './handlers/roadmap.js';
 import { handleAdvancedTool } from './handlers/advanced.js';
 import { handleSyndicateTool } from './handlers/syndicate.js';
 import { handleFedbrainTool, _lastBrainFromGitCounts } from './handlers/fedbrain.js';
+import { extractFirstRecallProof, renderFirstRecallProof } from './first-recall-proof.js';
 import { installClsPostCommitHook, CLS_HOOK_VERSION } from './cls-hook.js';
 import { installAmbientHooks, AMBIENT_HOOK_VERSION } from './ambient-hooks.js';
-import { runAmbient, truncateToTokens, parseHookPayload, stopObservation } from './ambient-cli.js';
+import { runAmbient, parseHookPayload, stopObservation } from './ambient-cli.js';
 import { appendLedgerEntry, readLedger, defaultLedgerPath } from './ambient-ledger.js';
 import { loadAmbientMemory, saveAmbientMemory } from './ambient-memory.js';
+import { buildAmbientDeps } from './ambient-deps.js';
+import { resolveApiKey, saveApiKey } from './credentials.js';
+import { buildLessonsMarkdown, buildLessonsJsonl } from './brain-export.js';
 import { detectEditor as detectEditorImpl } from './editor.js';
 import { milestoneSent, markMilestoneSent } from './funnel-milestones.js';
-import { candidateIdFor, netBalance, shouldBackoff } from './ambient-recall.js';
+import { kostprobeUebrig, kostprobeVerbrauchen, kostprobeHinweis, schrankeNachKostproben, } from './kostprobe.js';
+import { netBalance, shouldBackoff } from './ambient-recall.js';
 import { handleShareTool } from './handlers/share.js';
 import { handleVizTool } from './handlers/viz.js';
 // ── Tools (imported from tools.ts) ─────────────────────────────────────────
@@ -776,6 +787,24 @@ let _firstCallSuccessSent = false;
 function detectEditor() {
     return detectEditorImpl();
 }
+/**
+ * Pulls topic + preview snippet out of a `smart_recall` result's top hit
+ * (format: `**💡 <topic>** ... \n> <preview>`). Returns `null` on any
+ * mismatch — the seed-path proof is a bonus, never invented.
+ */
+function extractTopHit(text) {
+    if (!text)
+        return null;
+    const topicMatch = text.match(/\*\*💡\s+([^*]+)\*\*/);
+    const whatMatch = text.match(/^>\s+(.+)$/m);
+    if (!topicMatch || !whatMatch)
+        return null;
+    const topic = topicMatch[1].trim();
+    const what = whatMatch[1].trim();
+    if (!topic || !what)
+        return null;
+    return { topic, what };
+}
 /** Derive an anonymous, non-reversible fingerprint from the JWT sub claim. */
 function _jwtUserFingerprint(jwt) {
     try {
@@ -871,7 +900,7 @@ const PREMIUM_PITCH = {
     global_learn: "Team Brain — contribute to your organization's shared memory.",
     global_recall: 'Team Brain — recall across your entire organization.',
 };
-const UPGRADE_URL_FG = 'https://cachly.dev/billing';
+const UPGRADE_URL_FG = cachlyUrl('/billing', 'upgrade');
 const _tierCache = new Map();
 async function getTierInfo(instanceId) {
     const cached = _tierCache.get(instanceId);
@@ -889,7 +918,21 @@ async function getTierInfo(instanceId) {
         return { tier: 'unknown', isFree: false };
     }
 }
-/** Returns an upgrade teaser if a free-tier caller reached for a premium tool, else null. */
+/**
+ * Entscheidet, was mit einem gesperrten Werkzeug auf der Gratis-Stufe
+ * passiert. Drei Ausgänge:
+ *
+ *   null        → durchlassen (kein Premium-Werkzeug, oder bezahlte Stufe,
+ *                 oder es sind noch Kostproben übrig)
+ *   {sperre}    → Text zurückgeben, Werkzeug NICHT ausführen
+ *   {kostprobe} → durchlassen UND nach dem Ergebnis einen Hinweis anhängen
+ *
+ * Warum überhaupt Kostproben: Gemessen am 11.08.2026 ist `premium_gate_hit`
+ * 36-mal gefeuert — von einer einzigen Person, dem Entwickler selbst, über
+ * fünf Wochen. Er hat nicht aufgerüstet. Die Schranke gab eine
+ * Verkaufsansage, nie eine Kostprobe; man vermisst nicht, was man nie hatte.
+ * Einzelheiten in kostprobe.ts.
+ */
 async function featureGate(name, instanceId) {
     if (!PREMIUM_TOOLS.has(name) || !instanceId)
         return null;
@@ -897,14 +940,14 @@ async function featureGate(name, instanceId) {
     if (!isFree)
         return null;
     const pitch = PREMIUM_PITCH[name] ?? 'A Premium intelligence feature.';
-    return [
-        `🔒 **\`${name}\` is a Premium feature**`,
-        ``,
-        `${pitch}`,
-        ``,
-        `Your Free Brain keeps full keyword + causal-graph recall, learning, and sessions — forever.`,
-        `Unlock the deeper layer (causal tracing · predictive risk · Team Brain) → ${UPGRADE_URL_FG}`,
-    ].join('\n');
+    if (kostprobeUebrig(name)) {
+        // Durchlassen und danach kurz sagen, was das war. Der Zähler wird erst
+        // HIER erhöht, also nur wenn wirklich ausgeführt wird — ein abgebrochener
+        // Aufruf darf keine Kostprobe kosten.
+        const verbraucht = kostprobeVerbrauchen(name);
+        return { kostprobe: kostprobeHinweis(name, verbraucht, UPGRADE_URL_FG) };
+    }
+    return { sperre: schrankeNachKostproben(name, pitch, UPGRADE_URL_FG) };
 }
 async function handleTool(name, args) {
     // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
@@ -954,7 +997,7 @@ async function handleTool(name, args) {
                 'That’s it — your Brain activates automatically the moment you finish',
                 'signing in. Just keep working; your next request arrives brain-powered.',
                 '',
-                '✨ Free forever · No credit card · 126 MCP tools · GDPR · EU servers',
+                '✨ Free forever · No credit card · 122 MCP tools · GDPR · EU servers',
             ].join('\n');
         }
         // Device flow unavailable (network issue) — fall back to manual setup
@@ -966,7 +1009,7 @@ async function handleTool(name, args) {
             '   npx @cachly-dev/mcp-server@latest autopilot',
             '   ```',
             '',
-            'Or get your API key at: https://cachly.dev/setup-ai',
+            `Or get your API key at: ${cachlyUrl('/setup-ai', 'ambient-signin')}`,
             '',
             '✨ Free tier includes: 1 Brain instance, persistent memory, semantic search.',
         ].join('\n');
@@ -977,12 +1020,19 @@ async function handleTool(name, args) {
         if (defaultId)
             args = { ...args, instance_id: defaultId };
     }
-    // Feature-Gate: free tier reaching for a Premium tool gets the upgrade pitch
-    // at the moment of need (the magic moment of basic recall stays untouched).
-    const gateMsg = await featureGate(name, args.instance_id);
-    if (gateMsg !== null) {
-        sendFunnelEvent('premium_gate_hit', { tool: name, instance_id: args.instance_id ?? '' });
-        return gateMsg;
+    // Feature-Gate mit Kostprobe: die ersten Läufe eines Premium-Werkzeugs
+    // laufen auf der Gratis-Stufe echt durch, erst danach kommt die Schranke.
+    // Der Hinweis wird an das ECHTE Ergebnis angehängt, nicht davorgesetzt —
+    // wirken soll die Antwort, nicht der Text.
+    const gate = await featureGate(name, args.instance_id);
+    let kostprobeHinweisText = '';
+    if (gate !== null) {
+        if ('sperre' in gate) {
+            sendFunnelEvent('premium_gate_hit', { tool: name, instance_id: args.instance_id ?? '' });
+            return gate.sperre;
+        }
+        kostprobeHinweisText = gate.kostprobe;
+        sendFunnelEvent('premium_taste_used', { tool: name, instance_id: args.instance_id ?? '' });
     }
     // Delegate brain tools (learn, recall, session, etc.)
     const brainResult = await handleBrainTool(name, args, getConnection, apiFetch);
@@ -1113,16 +1163,23 @@ async function handleTool(name, args) {
     const cacheResult = await handleCacheTool(name, args, getConnection, apiFetch);
     if (cacheResult !== null)
         return cacheResult;
+    // Der Kostproben-Hinweis wird NUR hier angehaengt — an den drei Handlern,
+    // die die gesperrten Werkzeuge bedienen: team.ts (team_*, global_*),
+    // advanced.ts (causal_trace) und syndicate.ts (brain_predict und die
+    // uebrigen Vorhersagen). Er kommt ans ENDE, hinter das echte Ergebnis:
+    // wirken soll die Antwort, nicht der Text. Bei allen anderen Werkzeugen ist
+    // kostprobeHinweisText leer und die Zeile aendert nichts.
+    const mitHinweis = (r) => (kostprobeHinweisText ? r + kostprobeHinweisText : r);
     // Delegate team/brain advanced tools
     const teamResult = await handleTeamTool(name, args, getConnection, apiFetch);
     if (teamResult !== null)
-        return teamResult;
+        return mitHinweis(teamResult);
     const roadmapResult = await handleRoadmapTool(name, args, getConnection, apiFetch);
     if (roadmapResult !== null)
         return roadmapResult;
     const advancedResult = await handleAdvancedTool(name, args, getConnection, apiFetch);
     if (advancedResult !== null)
-        return advancedResult;
+        return mitHinweis(advancedResult);
     const syndicateResult = await handleSyndicateTool(name, args, getConnection, apiFetch);
     if (syndicateResult !== null) {
         // brain_predict is in syndicate handler — track telemetry here.
@@ -1131,7 +1188,7 @@ async function handleTool(name, args) {
             const telemetryExtra = JWT ? { api_key: JWT, instance_id: instanceId } : { instance_id: instanceId };
             sendFunnelEvent('brain_predict', telemetryExtra);
         }
-        return syndicateResult;
+        return mitHinweis(syndicateResult);
     }
     const shareResult = await handleShareTool(name, args, getConnection, apiFetch);
     if (shareResult !== null)
@@ -1180,7 +1237,7 @@ async function handleTool(name, args) {
                     `  💓 Health:   ${healthStatus}`,
                     `  🔑 Auth:     ❌ CACHLY_JWT not set`,
                     ``,
-                    `💡 Get your API token at https://cachly.dev/instances → Settings → API Token`,
+                    `💡 Get your API token at ${cachlyUrl('/instances', 'api-status')} → Settings → API Token`,
                 ].join('\n');
             }
             // Decode JWT claims (inspection only, no verification)
@@ -1212,7 +1269,7 @@ async function handleTool(name, args) {
                 const listRes = await apiFetch('/api/v1/instances');
                 const instances = listRes.data ?? [];
                 if (instances.length === 0) {
-                    instanceInfo = '\n\n🧠 **Brain Instances:** none — create one at https://cachly.dev/instances';
+                    instanceInfo = `\n\n🧠 **Brain Instances:** none — create one at ${cachlyUrl('/instances', 'api-status')}`;
                 }
                 else {
                     const lines = ['\n\n🧠 **Brain Instances:**'];
@@ -1270,9 +1327,18 @@ async function handleTool(name, args) {
             ].join('\n');
         }
         default:
-            return `⚠️ Unknown tool: ${name}`;
+            throw new UnknownToolError(`Unknown tool: ${name}`);
     }
 }
+/**
+ * Thrown by handleTool for a tool name that matches none of the delegated
+ * handlers and none of the explicit switch cases. Caught by the top-level
+ * request handler and turned into an `isError` result — never a silent
+ * success — so a client can no longer mistake a missing handler for a
+ * completed call.
+ */
+class UnknownToolError extends Error {
+}
 // Pushed to every MCP host at connect time (initialize response). This is the
 // "SessionStart-equivalent" for harnesses without a per-prompt hook — Cursor,
 // Windsurf, Cline, Copilot agent-mode all surface `instructions`. It's a one-time
@@ -1381,6 +1447,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text }] };
     }
     catch (err) {
+        if (err instanceof UnknownToolError) {
+            return { content: [{ type: 'text', text: err.message }], isError: true };
+        }
         if (err instanceof McpError)
             throw err;
         const msg = err.message ?? String(err);
@@ -1435,14 +1504,25 @@ export const EDITOR_FILES = {
 export const CLAUDE_MD_MARKER_START = '<!-- cachly-brain-start -->';
 export const CLAUDE_MD_MARKER_END = '<!-- cachly-brain-end -->';
 const DEFAULT_API_URL = 'https://api.cachly.dev';
-// Build the env block written into an editor's MCP config. Self-hosting is
-// first-class: if the operator runs setup/init against their own backend
-// (CACHLY_API_URL set to a non-default URL), that URL is baked into the config so
-// the editor-launched server talks to the self-hosted instance — not api.cachly.dev.
-// For the default cloud backend we OMIT CACHLY_API_URL to keep configs clean (the
-// binary already defaults to it).
-export function buildServerEnv(apiKey, instanceId) {
-    const env = { CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId };
+/**
+ * Builds the `env` block written into an editor's MCP config. Self-hosting is
+ * first-class: if the operator runs setup/init against their own backend
+ * (CACHLY_API_URL set to a non-default URL), that URL is baked into the config
+ * so the editor-launched server talks to the self-hosted instance — not
+ * api.cachly.dev. For the default cloud backend we OMIT CACHLY_API_URL to keep
+ * configs clean (the binary already defaults to it).
+ *
+ * GROW-033: the API key itself is OMITTED by default, so every PROJECT config
+ * this feeds (`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, …) is safe
+ * to commit. The running server resolves its key at start time via
+ * `resolveApiKey` instead (env, then the home credentials file). Pass
+ * `{ includeApiKey: true }` only for the one config that never leaves the
+ * user's machine: the global `~/.claude/mcp.json`.
+ */
+export function buildServerEnv(apiKey, instanceId, opts = {}) {
+    const env = { CACHLY_BRAIN_INSTANCE_ID: instanceId };
+    if (opts.includeApiKey)
+        env.CACHLY_JWT = apiKey;
     if (API_URL && API_URL !== DEFAULT_API_URL)
         env.CACHLY_API_URL = API_URL;
     return env;
@@ -1482,9 +1562,19 @@ export function buildMcpConfig(apiKey, instanceId, editor) {
         },
     }, null, 2);
 }
-// mergeMcpConfig reads an existing config file (if any), merges the cachly entry,
-// and returns the updated JSON string — preserving all other MCP servers and settings.
-export async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsOps) {
+/**
+ * Reads an existing editor config file (if any), merges in the cachly entry,
+ * and returns the updated JSON string — preserving all other MCP servers and
+ * settings.
+ *
+ * BESTANDSSCHUTZ (GROW-033): before GROW-033 this file could carry the API
+ * key in `env.CACHLY_JWT` as plaintext. If a legacy install still has that
+ * Altbestand value in the file being merged, it is uebernommen into the home
+ * credentials store via `saveApiKey` (the same store `resolveApiKey` already
+ * reads) before the merged config below is built — so the project file stops
+ * carrying the secret without anyone losing access.
+ */
+export async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsOps, credOpts = {}) {
     const cachlyEntry = {
         command: 'npx',
         args: ['-y', '@cachly-dev/mcp-server@latest'],
@@ -1509,6 +1599,16 @@ export async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsO
         // Merge into experimental.modelContextProtocolServers array — replace cachly entry if present
         const exp = (existing['experimental'] ?? {});
         const servers = (exp['modelContextProtocolServers'] ?? []);
+        let legacyKey;
+        for (const s of servers) {
+            const env = (s['env'] ?? {});
+            if (env['CACHLY_JWT']) {
+                legacyKey = env['CACHLY_JWT'];
+                break;
+            }
+        }
+        if (legacyKey)
+            saveApiKey(legacyKey, credOpts);
         const filtered = servers.filter((s) => {
             const env = (s['env'] ?? {});
             return !env['CACHLY_JWT'] && !env['CACHLY_BRAIN_INSTANCE_ID'];
@@ -1520,12 +1620,20 @@ export async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsO
     if (editor === 'zed') {
         // Merge only context_servers.cachly — preserve all other Zed settings
         const cs = (existing['context_servers'] ?? {});
+        const previousCachly = cs['cachly'];
+        const legacyKey = previousCachly?.command?.env?.['CACHLY_JWT'];
+        if (legacyKey)
+            saveApiKey(legacyKey, credOpts);
         cs['cachly'] = { command: { path: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'], env: cachlyEntry.env }, settings: {} };
         existing['context_servers'] = cs;
         return JSON.stringify(existing, null, 2);
     }
     // Standard mcpServers format (Claude Code, Cursor, Windsurf, Copilot, Cline)
     const servers = (existing['mcpServers'] ?? {});
+    const previousCachly = servers['cachly'];
+    const legacyKey = previousCachly?.env?.['CACHLY_JWT'];
+    if (legacyKey)
+        saveApiKey(legacyKey, credOpts);
     servers['cachly'] = cachlyEntry;
     existing['mcpServers'] = servers;
     return JSON.stringify(existing, null, 2);
@@ -1658,7 +1766,7 @@ if (process.argv[2] === 'digest') {
     process.stdout.write('\n🧠 Fetching your weekly Brain digest...\n\n');
     try {
         // Fetch current stats
-        const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain/stats`, {
+        const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain-stats`, {
             headers: { Authorization: `Bearer ${apiKey}` },
             signal: AbortSignal.timeout(8000),
         });
@@ -1733,6 +1841,74 @@ if (process.argv[2] === 'digest') {
     }
     process.exit(0);
 }
+// ── CLI: cachly export ────────────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest export [--out DIR] [--format md|jsonl|both]
+// Writes your own Brain's lessons to disk: lessons.md to read, lessons.jsonl to
+// reuse. "No model lock-in — leave anytime and take your data," made real.
+if (process.argv[2] === 'export') {
+    const { writeFile, mkdir } = await import('node:fs/promises');
+    const { resolve } = await import('node:path');
+    const argv = process.argv.slice(3);
+    const flag = (name) => { const i = argv.indexOf(`--${name}`); return i !== -1 ? argv[i + 1] : undefined; };
+    const format = flag('format') ?? 'both';
+    if (format !== 'md' && format !== 'jsonl' && format !== 'both') {
+        console.log(`\n❌ Unknown --format "${format}" — use md, jsonl, or both.\n`);
+        process.exit(1);
+    }
+    const outDir = resolve(flag('out') ?? '.');
+    const apiKey = JWT || resolveApiKey() || '';
+    const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
+    if (!apiKey || !instanceId) {
+        console.log('\n⚠️  CACHLY_JWT and CACHLY_BRAIN_INSTANCE_ID must be set.');
+        console.log('   Run: npx @cachly-dev/mcp-server@latest autopilot\n');
+        process.exit(1);
+    }
+    process.stdout.write('\n📤 Exporting your Brain...\n\n');
+    try {
+        const memRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/memory`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: AbortSignal.timeout(8000),
+        });
+        if (!memRes.ok)
+            throw new Error(`memory HTTP ${memRes.status}`);
+        const mem = await memRes.json();
+        const lessons = (mem.top_lessons ?? []).map((l) => ({
+            topic: l.topic,
+            outcome: l.outcome,
+            severity: l.severity,
+            tags: l.tags,
+            whatWorked: l.what_worked,
+            ts: l.ts,
+            author: l.author,
+            recallCount: l.recall_count,
+        }));
+        if (lessons.length === 0) {
+            console.log('   No lessons in this Brain yet — nothing to export.\n');
+            process.exit(0);
+        }
+        await mkdir(outDir, { recursive: true });
+        const written = [];
+        if (format === 'md' || format === 'both') {
+            const mdPath = resolve(outDir, 'lessons.md');
+            await writeFile(mdPath, buildLessonsMarkdown(lessons), 'utf-8');
+            written.push(`${lessons.length} lesson${lessons.length === 1 ? '' : 's'} → ${mdPath}`);
+        }
+        if (format === 'jsonl' || format === 'both') {
+            const jsonlPath = resolve(outDir, 'lessons.jsonl');
+            await writeFile(jsonlPath, buildLessonsJsonl(lessons), 'utf-8');
+            written.push(`${lessons.length} lesson${lessons.length === 1 ? '' : 's'} → ${jsonlPath}`);
+        }
+        console.log('✅ Export complete:');
+        for (const line of written)
+            console.log(`   ${line}`);
+        console.log('');
+    }
+    catch (e) {
+        console.log(`\n❌ Could not export your Brain: ${e.message}\n`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
 // ── CLI: cachly invite ────────────────────────────────────────────────────────
 // Usage: npx @cachly-dev/mcp-server@latest invite [email]
 // Invites a teammate to share your Brain. Fastest referral loop.
@@ -1752,7 +1928,7 @@ if (process.argv[2] === 'invite') {
         if (!res.ok)
             throw new Error(`HTTP ${res.status}`);
         const data = await res.json();
-        const referralUrl = data.url ?? `https://cachly.dev/r/${data.code}`;
+        const referralUrl = data.url ?? cachlyUrl(`/r/${data.code}`, 'invite');
         const count = data.referral_count ?? 0;
         const slackMsg = `Hey, I've been using cachly to give my AI persistent memory across sessions — no more re-explaining my stack every morning.\n\nYou get a free Brain: ${referralUrl}`;
         const tweetText = encodeURIComponent(`I gave my AI persistent memory. It remembers fixes, patterns, and context across every session — no more re-explaining.\n\nTry it free: ${referralUrl}\n\n@cachlydev`);
@@ -1890,7 +2066,7 @@ if (process.argv[2] === 'join') {
         }
         catch (e) {
             console.log(`\n  ⚠️  Could not start sign-in: ${e.message}`);
-            console.log(`   Set CACHLY_JWT manually from https://cachly.dev/setup-ai\n`);
+            console.log(`   Set CACHLY_JWT manually from ${cachlyUrl('/setup-ai', 'join')}\n`);
             process.exit(1);
         }
     }
@@ -2074,7 +2250,7 @@ if (process.argv[2] === 'bench') {
         console.log('  \x1b[1m→ Give your AI this recall quality on your own work (free, 1–5 min):\x1b[0m');
         console.log('  \x1b[32m$ npx @cachly-dev/mcp-server@latest autopilot\x1b[0m');
         console.log('  \x1b[90m  Signs in, configures every editor, bootstraps from your git history.\x1b[0m');
-        console.log('  \x1b[90m  Or create your Brain at: \x1b[36mhttps://cachly.dev/setup-ai\x1b[0m');
+        console.log(`  \x1b[90m  Or create your Brain at: \x1b[36m${cachlyUrl('/setup-ai', 'bench')}\x1b[0m`);
         console.log('');
     }
     catch (e) {
@@ -2232,7 +2408,7 @@ if (process.argv[2] === 'demo') {
         authors: String(authors.size),
         hours: String(hoursWasted),
     });
-    const previewURL = `https://cachly.dev/preview?${previewParams.toString()}`;
+    const previewURL = cachlyUrl(`/preview?${previewParams.toString()}`, 'demo');
     console.log('  \x1b[1mMake this permanent (free, 1–5 minutes):\x1b[0m');
     console.log('  \x1b[32m$ npx @cachly-dev/mcp-server@latest autopilot\x1b[0m');
     console.log('');
@@ -2256,7 +2432,7 @@ if (process.argv[2] === 'share') {
     }
     process.stdout.write('\n🧠 Fetching your Brain stats...\n');
     try {
-        const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain/stats`, {
+        const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain-stats`, {
             headers: { Authorization: `Bearer ${apiKey}` },
             signal: AbortSignal.timeout(8000),
         });
@@ -2287,7 +2463,7 @@ if (process.argv[2] === 'share') {
         console.log('└─────────────────────────────────────────────────────────────┘');
         console.log('');
         // Tweet text
-        const shareUrl = 'https://cachly.dev?ref=share&utm_source=x&utm_medium=social&utm_campaign=cli-share';
+        const shareUrl = cachlyUrl('/', 'share');
         const tweet = `🧠 My AI coding assistant now has persistent memory.\n\n${lessons} lessons stored · ${recalls} recalls · ${level}\n\nFix a bug once → AI remembers forever. Across Claude Code, Cursor, Windsurf, Copilot.\n\n${shareUrl}\n\n#AIMemory #ClaudeCode #Cursor #DeveloperTools`;
         console.log('  \x1b[1m📋 Share on Twitter/X (copy this):\x1b[0m');
         console.log('  ─────────────────────────────────────');
@@ -2322,7 +2498,7 @@ if (process.argv[2] === 'publish') {
     process.stdout.write('\n🧠 Publishing Brain snapshot...\n');
     try {
         // Fetch stats for the card
-        const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain/stats`, {
+        const statsRes = await fetch(`${API_URL}/api/v1/instances/${instanceId}/brain-stats`, {
             headers: { Authorization: `Bearer ${apiKey}` },
             signal: AbortSignal.timeout(8000),
         });
@@ -2343,7 +2519,7 @@ if (process.argv[2] === 'publish') {
             throw new Error(`HTTP ${shareRes.status}`);
         const share = await shareRes.json();
         const shareId = share.share_id ?? 'unavailable';
-        const shareUrl = `https://cachly.dev/brain/share/${shareId}`;
+        const shareUrl = cachlyUrl(`/brain/share/${shareId}`, 'publish');
         console.log('');
         console.log('┌─────────────────────────────────────────────────────────────┐');
         console.log('│  📤 Brain Published  ·  powered by \x1b[35mcachly.dev\x1b[0m                │');
@@ -2372,7 +2548,7 @@ if (process.argv[2] === 'publish') {
     process.exit(0);
 }
 // ── CLI: cachly tool-specs / openapi ───────────────────────────────────────────
-// Emit the 120-tool surface in any agent framework's dialect, derived from the
+// Emit the 122-tool surface in any agent framework's dialect, derived from the
 // single TOOLS source of truth. Lets OpenAI Assistants, the Anthropic Messages
 // API, LangChain, CrewAI and AutoGen wrap cachly without hand-written glue.
 //   npx @cachly-dev/mcp-server tool-specs --format=openai   > cachly.openai.json
@@ -2412,7 +2588,7 @@ if (process.argv[2] === 'badge') {
         process.exit(1);
     }
     const badgeUrl = `${API_URL}/api/v1/badge/${instanceId}`;
-    const targetUrl = 'https://cachly.dev';
+    const targetUrl = cachlyUrl('/', 'badge');
     const markdown = `[![cachly Brain](${badgeUrl})](${targetUrl})`;
     const htmlBadge = `<a href="${targetUrl}"><img src="${badgeUrl}" alt="cachly Brain" /></a>`;
     console.log('');
@@ -2454,6 +2630,7 @@ if (!process.argv[2] && process.stdout.isTTY) {
     console.log('  \x1b[32m  npx @cachly-dev/mcp-server@latest demo\x1b[0m     ← Try it first (no account)');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest setup\x1b[0m    ← Interactive setup (pick editors)');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest health\x1b[0m   ← Check everything works');
+    console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest doctor\x1b[0m   ← Diagnose a broken or missing install');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest digest\x1b[0m   ← Weekly Brain summary');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest share\x1b[0m    ← Share your Brain stats');
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest badge\x1b[0m    ← README badge for your Brain');
@@ -2463,7 +2640,7 @@ if (!process.argv[2] && process.stdout.isTTY) {
     console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest upgrade\x1b[0m  ← Check for updates');
     console.log('');
     console.log('  \x1b[90mWorks with: Claude Code · Cursor · Windsurf · GitHub Copilot · Cline · Zed\x1b[0m');
-    console.log('  \x1b[90mFree forever · GDPR · German servers · 126 MCP tools\x1b[0m');
+    console.log('  \x1b[90mFree forever · GDPR · German servers · 122 MCP tools\x1b[0m');
     console.log('');
     process.exit(0);
 }
@@ -2507,7 +2684,7 @@ if (process.argv[2] === 'init') {
     if (!instanceId || !apiKey) {
         console.error('\nUsage: npx @cachly-dev/mcp-server@latest init --instance-id <uuid> --api-key <cky_live_...> [--editor claude|cursor|windsurf|copilot|continue] [--project-dir /path] [--api-url https://your-self-hosted-backend]\n');
         console.error('First time? Run the zero-config wizard (signs you in, auto-provisions): npx @cachly-dev/mcp-server@latest autopilot\n');
-        console.error('Get your credentials from: https://cachly.dev/setup-ai\n');
+        console.error(`Get your credentials from: ${cachlyUrl('/setup-ai', 'init')}\n`);
         process.exit(1);
     }
     const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
@@ -2516,6 +2693,7 @@ if (process.argv[2] === 'init') {
     const { existsSync: exInit } = await import('node:fs');
     const configExisted = exInit(configPath);
     const prevConfig = configExisted ? await readFile(configPath, 'utf-8').catch(() => '') : '';
+    saveApiKey(apiKey);
     const merged = await mergeMcpConfig(configPath, apiKey, instanceId, editor, { readFile, existsSync: exInit });
     // Idempotent: only write when the content actually changes.
     if (merged !== prevConfig) {
@@ -2551,7 +2729,7 @@ if (process.argv[2] === 'init') {
     // Only for Claude Code (the hooks config lives in .claude/settings.json).
     if (editor === 'claude') {
         try {
-            const a = await installAmbientHooks(projectDir, instanceId, JWT || undefined);
+            const a = await installAmbientHooks(projectDir, instanceId);
             const scriptVerb = a.scripts === 'written' ? '✅ Written' : a.scripts === 'upgraded' ? `✅ Upgraded (→ ${AMBIENT_HOOK_VERSION})` : '✓  Unchanged';
             console.log(`${scriptVerb}: .claude/hooks/ (Ambient Recall — session briefing, per-prompt recall, file briefing, auto-learn)`);
             if (a.settings === 'written')
@@ -2587,7 +2765,7 @@ if (process.argv[2] === 'status') {
     }
     try {
         const [statsRes, referralRes] = await Promise.all([
-            fetch(`${API_URL}/api/v1/instances/${instanceId}/brain/stats`, {
+            fetch(`${API_URL}/api/v1/instances/${instanceId}/brain-stats`, {
                 headers: { Authorization: `Bearer ${apiKey}` },
                 signal: AbortSignal.timeout(8000),
             }),
@@ -2676,10 +2854,10 @@ if (process.argv[2] === 'health') {
             const expMs = payload.exp ? payload.exp * 1000 : null;
             const minsLeft = expMs ? Math.floor((expMs - Date.now()) / 60_000) : null;
             if (expMs && expMs < Date.now()) {
-                fail(`JWT expired ${Math.abs(minsLeft)} minute(s) ago — get a new one: https://cachly.dev/setup-ai`);
+                fail(`JWT expired ${Math.abs(minsLeft)} minute(s) ago — get a new one: ${cachlyUrl('/setup-ai', 'health')}`);
             }
             else if (minsLeft !== null && minsLeft < 30) {
-                warn(`JWT expires in ${minsLeft} minute(s) — refresh soon at https://cachly.dev/setup-ai`);
+                warn(`JWT expires in ${minsLeft} minute(s) — refresh soon at ${cachlyUrl('/setup-ai', 'health')}`);
             }
             else {
                 ok(`JWT valid${minsLeft !== null ? ` (expires in ${Math.floor(minsLeft / 60)}h ${minsLeft % 60}m)` : ''}`);
@@ -2883,6 +3061,7 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
     const { resolve, dirname } = await import('node:path');
     const { createInterface } = await import('node:readline');
     const setupStartMs = Date.now();
+    const cliSource = _isAutopilotCli ? 'autopilot' : 'setup';
     // Self-hosting: `setup --api-url https://cachly.mycorp.internal` points the whole
     // wizard (auth, provisioning, config writes) at a private backend.
     const _apiUrlIdx = process.argv.indexOf('--api-url');
@@ -3031,7 +3210,7 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
         else {
             // Device flow unavailable — web fallback with automatic browser open
             sendFunnelEvent('device_flow_failed', { reason: 'device_flow_unavailable' });
-            const signupUrl = 'https://cachly.dev/setup-ai';
+            const signupUrl = cachlyUrl('/setup-ai', cliSource);
             console.log('   ⚠️  Could not start automatic sign-in. Opening browser for web sign-in...\n');
             console.log(`   URL: \x1b[36m${signupUrl}\x1b[0m`);
             console.log('   1. Sign up / log in at the URL above');
@@ -3102,8 +3281,8 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
         const msg = e.message;
         console.error(`\n\nFailed to fetch instances: ${msg}`);
         if (msg.includes('401')) {
-            console.error('Token rejected. Get a valid token at https://cachly.dev/setup-ai\n');
-            openInBrowser('https://cachly.dev/setup-ai');
+            console.error(`Token rejected. Get a valid token at ${cachlyUrl('/setup-ai', cliSource)}\n`);
+            openInBrowser(cachlyUrl('/setup-ai', cliSource));
         }
         rl.close();
         process.exit(1);
@@ -3152,8 +3331,8 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
             console.log(` failed: ${e.message}\n`);
         }
         if (instances.length === 0) {
-            console.error('\nCould not create an instance automatically. Opening https://cachly.dev/instances …\n');
-            openInBrowser('https://cachly.dev/instances');
+            console.error(`\nCould not create an instance automatically. Opening ${cachlyUrl('/instances', cliSource)} …\n`);
+            openInBrowser(cachlyUrl('/instances', cliSource));
             rl.close();
             process.exit(1);
         }
@@ -3207,6 +3386,7 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
     // always claiming "Brain is ready" even when a config never got written.
     const configWriteFailures = [];
     let configWriteSuccesses = 0;
+    saveApiKey(token);
     for (const editor of editorsToSetup) {
         const configFile = EDITOR_FILES[editor] ?? '.mcp.json';
         const configPath = resolve(cwd, configFile);
@@ -3242,7 +3422,7 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
         globalConfig.mcpServers['cachly'] = {
             command: 'npx',
             args: ['-y', '@cachly-dev/mcp-server@latest'],
-            env: buildServerEnv(token, instance.id),
+            env: buildServerEnv(token, instance.id, { includeApiKey: true }),
         };
         await writeFile(globalClaudePath, JSON.stringify(globalConfig, null, 2), 'utf-8');
         console.log(`✅ Written: ~/.claude/mcp.json  (global — works in every project)`);
@@ -3272,9 +3452,14 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
                 repo_path: cwd,
                 limit: 100,
             });
-            const match = gitResult.match(/(\d+) lesson/);
-            gitLessonCount = match ? parseInt(match[1], 10) : 0;
-            console.log(` ✓  ${match ? match[1] + ' lessons' : 'done'} extracted from git history`);
+            const ingestedMatch = gitResult.match(/Ingested: \*\*(\d+)\*\*/);
+            gitLessonCount = ingestedMatch ? parseInt(ingestedMatch[1], 10) : 0;
+            console.log(` ✓  ${gitLessonCount} lesson${gitLessonCount === 1 ? '' : 's'} extracted from git history`);
+            const gitProofBlock = extractFirstRecallProof(gitResult);
+            if (gitProofBlock) {
+                console.log('');
+                console.log(gitProofBlock);
+            }
         }
         catch (e) {
             console.log(` (skipped: ${e.message.slice(0, 80)})`);
@@ -3291,6 +3476,21 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
         try {
             await handleTool('brain_seed_starter', { instance_id: instance.id });
             console.log(' ✓');
+            // Bonus, never a blocker: run one real recall against the corpus we just
+            // seeded and show the top hit, so the seed path gets a proof too — not
+            // just the weaker '✓' it used to leave the user with.
+            try {
+                const seedRecallText = await handleTool('smart_recall', {
+                    instance_id: instance.id,
+                    query: 'docker build slow',
+                });
+                const seedHit = extractTopHit(seedRecallText);
+                if (seedHit) {
+                    console.log('');
+                    console.log(renderFirstRecallProof(seedHit.topic, seedHit.what));
+                }
+            }
+            catch { /* proof is a bonus, never blocks setup */ }
         }
         catch (e) {
             console.log(` (skipped: ${e.message.slice(0, 60)})`);
@@ -3300,7 +3500,7 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
     // Fetch brain health from the API to show the user what their agent will see.
     process.stdout.write('\n⏳ Fetching your Brain health preview...');
     try {
-        const brainRes = await fetch(`${API_URL}/api/v1/instances/${instance.id}/brain/stats`, {
+        const brainRes = await fetch(`${API_URL}/api/v1/instances/${instance.id}/brain-stats`, {
             headers: { Authorization: `Bearer ${token}` },
             signal: AbortSignal.timeout(6000),
         });
@@ -3370,7 +3570,7 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
     console.log(`\n🎉  Your AI just got a permanent brain.`);
     console.log(`   Restart your editor — from this session on, it arrives pre-briefed.\n`);
     console.log(`   No more re-explaining your stack. No repeated mistakes.\n`);
-    console.log(`   Dashboard: https://cachly.dev/instances/${instance.id}`);
+    console.log(`   Dashboard: ${cachlyUrl(`/instances/${instance.id}`, cliSource)}`);
     console.log(`\n   📛 Add a live badge to your README:`);
     console.log(`      npx @cachly-dev/mcp-server@latest badge\n`);
     // ── Step 6c: Governance bootstrap — assign the first admin role ─────────────
@@ -3425,6 +3625,24 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
             console.log(`\n✅  CLS git hook appended to existing post-commit.`);
     }
     catch { /* non-critical */ }
+    // ── Ambient Recall Phase 4: auto-install SessionStart + UserPromptSubmit hooks ─
+    // Only for Claude Code (the hooks config lives in .claude/settings.json). Without
+    // this call, setup/autosetup/autopilot never install the hooks that make the
+    // Brain speak up on its own — only `init` did (the bug POL-034 fixes).
+    if (editorsToSetup.includes('claude')) {
+        try {
+            const a = await installAmbientHooks(process.cwd(), instance.id);
+            const scriptVerb = a.scripts === 'written' ? '✅  Written' : a.scripts === 'upgraded' ? `✅  Upgraded (→ ${AMBIENT_HOOK_VERSION})` : '✓  Unchanged';
+            console.log(`${scriptVerb}: .claude/hooks/ (Ambient Recall — session briefing, per-prompt recall, file briefing, auto-learn)`);
+            if (a.settings === 'written')
+                console.log(`✅  Written: .claude/settings.json (Ambient Recall hooks wired)`);
+            else if (a.settings === 'merged')
+                console.log(`✅  Merged: .claude/settings.json (Ambient Recall hooks wired)`);
+            else
+                console.log(`✓  Ambient Recall hooks already wired in .claude/settings.json`);
+        }
+        catch { /* non-critical — ambient hooks are a best-effort feature */ }
+    }
     // Setup reached the end — close the funnel. Report config-write outcome so the
     // weekly funnel can spot permission/path problems blocking activation.
     JWT = token;
@@ -3452,7 +3670,7 @@ if (process.argv[2] === 'autosetup' || process.argv[2] === 'setup' || _isAutopil
             console.log(`     • ${f.file} — ${f.reason}`);
         console.log('\n   Fix the permissions above and re-run, or configure manually:');
         console.log(`     CACHLY_JWT=${token.slice(0, 12)}… CACHLY_BRAIN_INSTANCE_ID=${instance.id}`);
-        console.log(`   Docs: https://cachly.dev/docs/mcp\n`);
+        console.log(`   Docs: ${cachlyUrl('/docs/mcp', cliSource)}\n`);
         rl.close();
         await new Promise(r => setTimeout(r, 300));
         process.exit(1);
@@ -3568,8 +3786,15 @@ if (process.argv[2] === 'ambient-recall') {
         for await (const chunk of process.stdin)
             chunks.push(chunk);
         const raw = Buffer.concat(chunks).toString('utf-8');
+        // GROW-015: hooks run as bare OS processes and never see the MCP config's
+        // env, so JWT is usually still empty here — resolve it the same way every
+        // ambient/CLI caller does (env, then ~/.cachly, then a legacy .mcp.json).
         if (!JWT)
-            process.exit(0); // not authenticated → silent no-op
+            JWT = resolveApiKey() ?? '';
+        if (!JWT) {
+            console.error('cachly ambient-recall: no API key found (CACHLY_JWT/CACHLY_API_KEY env, ~/.cachly/credentials.json, or .mcp.json) — recall skipped for this turn.');
+            process.exit(0);
+        }
         const instanceId = process.env.CACHLY_BRAIN_INSTANCE_ID ?? _defaultInstanceId;
         // Stop event → auto-learn, never inject (roadmap §6.1 PostToolUse/Stop row).
         const stopPayload = parseHookPayload(raw);
@@ -3581,12 +3806,9 @@ if (process.argv[2] === 'ambient-recall') {
             process.exit(0);
         }
         let reported;
-        const out = await runAmbient(raw, {
-            timeoutMs: 3000, // §6.3 guardrail 4: never stall the prompt on a slow brain
-            // Ambient injection budget: one relevance-ranked briefing, hard-capped.
-            // smart_recall already returns its hits best-first, so the capped head is
-            // the high-signal part. Per-lesson structured candidates are a future slice.
-            gate: { topK: 1, maxTokens: 500 },
+        const out = await runAmbient(raw, buildAmbientDeps({
+            instanceId,
+            smartRecall: async (query) => String((await handleTool('smart_recall', { instance_id: instanceId, query })) ?? ''),
             loadMemory: () => loadAmbientMemory(),
             saveMemory: (m) => saveAmbientMemory(m),
             backoff: async () => shouldBackoff(await readLedger()),
@@ -3595,17 +3817,7 @@ if (process.argv[2] === 'ambient-recall') {
                 void appendLedgerEntry(entry);
                 reported = reportAmbientLedgerEvent(instanceId, entry); // org dashboard mirror
             },
-            recall: async (query) => {
-                if (!instanceId)
-                    return [];
-                const text = String((await handleTool('smart_recall', { instance_id: instanceId, query })) ?? '');
-                const miss = text.length < 80 || /No lessons found|no lessons|No matches found/i.test(text);
-                if (miss)
-                    return [];
-                const summary = truncateToTokens(text, 500);
-                return [{ id: candidateIdFor(summary), summary, confidence: 0.9, score: 0.9 }];
-            },
-        });
+        }));
         if (out)
             process.stdout.write(out);
         // Bounded flush so the dashboard mirror survives process.exit — never more
@@ -3764,6 +3976,8 @@ if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '')) {
     if (runningInTerminal) {
         // A human ran `npx @cachly-dev/mcp-server` directly with no credentials.
         // Show them how to set up, then exit cleanly.
+        const bannerSetupUrl = cachlyUrl('/setup-ai', 'first-run');
+        const bannerSetupLine = `║    👉  ${bannerSetupUrl}`.padEnd(66) + '║\n';
         const banner = '\n' +
             '╔══════════════════════════════════════════════════════════════════╗\n' +
             '║  🧠  cachly AI Brain — Setup required                           ║\n' +
@@ -3771,7 +3985,7 @@ if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '')) {
             '║                                                                  ║\n' +
             '║  CACHLY_JWT is not set. Get your free credentials at:           ║\n' +
             '║                                                                  ║\n' +
-            '║    👉  https://cachly.dev/setup-ai                              ║\n' +
+            bannerSetupLine +
             '║                                                                  ║\n' +
             '║  Then run the one-command setup wizard:                         ║\n' +
             '║                                                                  ║\n' +
@@ -3799,11 +4013,11 @@ else {
         const minsLeft = Math.floor((expMs - Date.now()) / 60_000);
         if (minsLeft <= 0) {
             process.stderr.write(`\n⚠️  cachly: CACHLY_JWT expired ${Math.abs(minsLeft)} minute(s) ago.\n` +
-                `   All tool calls will fail. Get a fresh token at https://cachly.dev/setup-ai\n\n`);
+                `   All tool calls will fail. Get a fresh token at ${cachlyUrl('/setup-ai', 'jwt-expiry')}\n\n`);
         }
         else if (minsLeft < 60) {
             process.stderr.write(`\n⚠️  cachly: CACHLY_JWT expires in ${minsLeft} minute(s).\n` +
-                `   Refresh it soon at https://cachly.dev/setup-ai to avoid interruptions.\n\n`);
+                `   Refresh it soon at ${cachlyUrl('/setup-ai', 'jwt-expiry')} to avoid interruptions.\n\n`);
         }
     }
 }