@prave/cli 1.2.1 → 1.3.0

package/README.md

@@ -172,7 +172,7 @@ API health and uptime: [status.prave.app](https://status.prave.app) — auto-ref
 - 📖 [**CLI Cheat Sheet**](https://prave.app/docs/cli/cheat-sheet) — every command on one page
 - 💚 [**status.prave.app**](https://status.prave.app) — real-time health
 - 🐛 [**GitHub Issues**](https://github.com/eppstudio/prave/issues) — bug reports & feature requests
-- ✉️ [info@epplab-studio.de](mailto:info@epplab-studio.de) — direct contact
+- ✉️ [hello@epplab-studio.de](mailto:hello@epplab-studio.de) — direct contact
 
 ## License
 

package/dist/commands/deploy.js

@@ -3,7 +3,7 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import chalk from 'chalk';
 import ora from 'ora';
-import { AGENT_REGISTRY } from '@prave/shared';
+import { AGENT_REGISTRY, compileSkill } from '@prave/shared';
 import { track } from '../lib/analytics.js';
 import { api, ApiError } from '../lib/api.js';
 import { requireAuth } from '../lib/credentials.js';
@@ -41,34 +41,30 @@ async function fetchRemoteSkill(slug) {
     }
     return data.content;
 }
-function describeContentForCursor(content, slug) {
-    // Has frontmatter? best-effort rename triggers: → globs:
-    const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
-    if (fmMatch && fmMatch[1] !== undefined) {
-        const body = content.slice(fmMatch[0].length);
-        const fmInner = fmMatch[1].replace(/(^|\n)triggers:/g, '$1globs:');
-        return `---\n${fmInner}\n---\n${body}`;
-    }
-    // No frontmatter — synthesize
-    const trimmed = content.trim().replace(/\s+/g, ' ').slice(0, 200);
-    return `---\nname: ${slug}\ndescription: ${trimmed}\n---\n${content}`;
-}
-function buildDestPath(agent, basePath, os, slug) {
+/**
+ * Build the on-disk write path for the given agent + slug. The
+ * `compileSkill()` import from `@prave/shared` decides the *content*
+ * transform (e.g. Cursor `.mdc` frontmatter rewrite); this function
+ * only resolves the absolute filesystem location by combining the
+ * agent's `basePath` from user settings with the relative path the
+ * shared compiler returned.
+ */
+function buildDestPath(agent, basePath, os, slug, relPath) {
     const expanded = expandHome(basePath, os);
-    if (agent === 'cursor') {
-        // .cursor/rules/<slug>.mdc — the basePath already points at .cursor/rules
-        return {
-            dir: expanded,
-            file: join(expanded, `${slug}.mdc`),
-            converted: true,
-            display: `${basePath.replace(/[\\/]+$/, '')}/${slug}.mdc`,
-        };
-    }
+    // The shared compiler returns POSIX-style relPaths
+    // (e.g. `<slug>/SKILL.md` or `.cursor/rules/<slug>.mdc`). For
+    // Cursor specifically the user's `basePath` already points at
+    // `.cursor/rules/`, so we collapse the leading `.cursor/rules/`
+    // to avoid the path duplicating to `.cursor/rules/.cursor/rules/`.
+    const collapsed = agent === 'cursor' && relPath.startsWith('.cursor/rules/')
+        ? relPath.slice('.cursor/rules/'.length)
+        : relPath;
+    const file = join(expanded, ...collapsed.split('/'));
+    const dir = file.slice(0, file.length - collapsed.split('/').slice(-1)[0].length - 1);
     return {
-        dir: join(expanded, slug),
-        file: join(expanded, slug, 'SKILL.md'),
-        converted: false,
-        display: `${basePath.replace(/[\\/]+$/, '')}/${slug}/SKILL.md`,
+        dir,
+        file,
+        display: `${basePath.replace(/[\\/]+$/, '')}/${collapsed}`,
     };
 }
 export async function deployCommand(skillName, opts = {}) {
@@ -146,10 +142,12 @@ export async function deployCommand(skillName, opts = {}) {
         const meta = AGENT_REGISTRY[agent];
         const paths = settings.skill_paths[agent] ?? meta.defaultPath;
         const basePath = os === 'windows' ? paths.windows : paths.mac;
-        const dest = buildDestPath(agent, basePath, os, skillName);
-        const content = dest.converted
-            ? describeContentForCursor(source, skillName)
-            : source;
+        // Shared compileSkill() is the single source of truth — same
+        // function the SaaS /dashboard/compile page calls, so the CLI
+        // and the web zip produce byte-identical output for the same
+        // SKILL.md.
+        const artifact = compileSkill(source, skillName, agent);
+        const dest = buildDestPath(agent, basePath, os, skillName, artifact.path);
         spinner.text = `→ ${meta.label}`;
         if (opts.dryRun) {
             okCount += 1;
@@ -157,7 +155,7 @@ export async function deployCommand(skillName, opts = {}) {
         }
         try {
             await mkdir(dest.dir, { recursive: true });
-            await writeFile(dest.file, content, 'utf8');
+            await writeFile(dest.file, artifact.content, 'utf8');
             okCount += 1;
         }
         catch (err) {
@@ -169,8 +167,9 @@ export async function deployCommand(skillName, opts = {}) {
         const meta = AGENT_REGISTRY[agent];
         const paths = settings.skill_paths[agent] ?? meta.defaultPath;
         const basePath = os === 'windows' ? paths.windows : paths.mac;
-        const dest = buildDestPath(agent, basePath, os, skillName);
-        const tag = dest.converted ? chalk.dim(' (converted)') : '';
+        const artifact = compileSkill(source, skillName, agent);
+        const dest = buildDestPath(agent, basePath, os, skillName, artifact.path);
+        const tag = artifact.converted ? chalk.dim(' (converted)') : '';
         console.log(`${chalk.green('✓')} ${meta.label.padEnd(14)} → ${dest.display}${tag}`);
     }
     const elapsed = ((Date.now() - start) / 1000).toFixed(1);

package/dist/commands/login.js

@@ -39,6 +39,17 @@ export async function loginCommand() {
                 expires_at: data.expires_at ?? undefined,
             });
             spinner.succeed('Logged in.');
+            // Replay any Skill-invocation events the hook buffered while the
+            // user was offline / signed out. Silent when nothing's queued;
+            // prints "Syncing N events…" + a confirmation when the file has
+            // real backlog. Failures swallowed inside.
+            try {
+                const { flushBufferedTelemetry } = await import('../lib/flush-telemetry.js');
+                await flushBufferedTelemetry();
+            }
+            catch (flushErr) {
+                log.dim(`Telemetry sync skipped: ${flushErr.message}`);
+            }
             // Onboarding: prefill from the SaaS profile, let the user toggle
             // with space/enter, persist back, and offer to install hooks.
             // Failures here are non-fatal — login succeeded.

package/dist/commands/mcp-install.js

@@ -0,0 +1,197 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, writeFile, stat } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import process from 'node:process';
+import chalk from 'chalk';
+import { track } from '../lib/analytics.js';
+import { log } from '../utils/logger.js';
+const ENTRY_NPX = {
+    command: 'npx',
+    args: ['-y', '@prave/cli', 'mcp-server'],
+};
+const ENTRY_GLOBAL = {
+    command: 'prave',
+    args: ['mcp-server'],
+};
+export async function mcpInstallCommand() {
+    track('cli_mcp_install');
+    const target = resolveClaudeDesktopConfigPath();
+    if (!target) {
+        log.error(`This OS (${platform()}) isn't supported by Claude Desktop yet. Use the manual JSON snippet from /dashboard/settings/mcp instead.`);
+        process.exitCode = 1;
+        return;
+    }
+    // Prefer the global `prave` binary when it's on PATH — it's faster
+    // (no npx resolution at every Claude Desktop launch), version-pinned
+    // by the user (no surprise updates mid-session), and the config
+    // entry is two tokens shorter. Fall back to the npx form when the
+    // user is on a one-shot `npx @prave/cli mcp install` path.
+    const hasGlobalPrave = await detectGlobalPrave();
+    const PRAVE_ENTRY = hasGlobalPrave ? ENTRY_GLOBAL : ENTRY_NPX;
+    // Read existing config, tolerate the "file doesn't exist yet" case
+    // — Claude Desktop creates the file on first launch, but users often
+    // run our setup BEFORE opening the app for the first time.
+    let existing = {};
+    let fileExisted = false;
+    try {
+        const raw = await readFile(target, 'utf8');
+        fileExisted = true;
+        try {
+            existing = JSON.parse(raw);
+        }
+        catch (err) {
+            log.error(`Couldn't parse ${target} as JSON (${err.message}). Fix it manually or delete it and re-run.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            log.error(`Couldn't read ${target}: ${err.message}`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // Idempotency check — if a `prave` entry with our exact command +
+    // args already exists, don't churn the file.
+    const current = existing.mcpServers?.prave;
+    if (current &&
+        current.command === PRAVE_ENTRY.command &&
+        JSON.stringify(current.args ?? []) === JSON.stringify(PRAVE_ENTRY.args ?? [])) {
+        log.success('Prave MCP server is already wired into Claude Desktop.');
+        log.dim(`Config: ${target}`);
+        log.dim('Restart Claude Desktop if you haven\'t since the last edit.');
+        return;
+    }
+    // Backup before mutating. Only when the file existed — there's
+    // nothing to back up otherwise.
+    if (fileExisted) {
+        try {
+            const raw = await readFile(target, 'utf8');
+            await writeFile(`${target}.bak`, raw, 'utf8');
+        }
+        catch (err) {
+            log.warn(`Couldn't write ${target}.bak — proceeding anyway: ${err.message}`);
+        }
+    }
+    // Merge our entry, preserving everything else (including any other
+    // MCP servers the user has configured).
+    const nextConfig = {
+        ...existing,
+        mcpServers: {
+            ...(existing.mcpServers ?? {}),
+            prave: PRAVE_ENTRY,
+        },
+    };
+    try {
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, JSON.stringify(nextConfig, null, 2) + '\n', 'utf8');
+    }
+    catch (err) {
+        log.error(`Couldn't write ${target}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    log.success('Prave MCP server installed for Claude Desktop.');
+    console.log();
+    console.log(`  ${chalk.dim('Config:')}  ${target}`);
+    if (fileExisted) {
+        console.log(`  ${chalk.dim('Backup:')}  ${target}.bak`);
+    }
+    else {
+        console.log(`  ${chalk.dim('Note:')}    New config file created.`);
+    }
+    console.log(`  ${chalk.dim('Mode:')}    ${hasGlobalPrave
+        ? 'global `prave` binary (fast, no npx hop)'
+        : 'npx (no global install needed)'}`);
+    console.log();
+    log.info('Next:');
+    log.dim('  1. Restart Claude Desktop.');
+    log.dim('  2. Prave\'s tools appear in the MCP panel.');
+    log.dim('  3. Try: "Find me a skill for React testing".');
+    if (!hasGlobalPrave) {
+        console.log();
+        log.dim(`Tip: ${chalk.bold('npm i -g @prave/cli')} once, and Claude Desktop boots Prave a second faster (no npx resolution).`);
+    }
+    // Ping the heartbeat so the SaaS Settings → MCP card shows
+    // "Connection wired" even before the user fires the first real
+    // tool call. Best-effort; failure swallowed.
+    void pingHeartbeatBestEffort();
+}
+/* ─── internals ─────────────────────────────────────────────────── */
+function resolveClaudeDesktopConfigPath() {
+    const home = homedir();
+    switch (platform()) {
+        case 'darwin':
+            return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+        case 'win32': {
+            const appData = process.env.APPDATA;
+            if (!appData)
+                return null;
+            return join(appData, 'Claude', 'claude_desktop_config.json');
+        }
+        case 'linux':
+            return join(home, '.config', 'Claude', 'claude_desktop_config.json');
+        default:
+            return null;
+    }
+}
+async function pingHeartbeatBestEffort() {
+    try {
+        const { api } = await import('../lib/api.js');
+        await api.post('/api/v1/me/mcp-heartbeat', {}, true);
+    }
+    catch {
+        // No creds yet, or API unreachable — fine. The first real tool
+        // call from Claude Desktop will set the heartbeat anyway.
+    }
+}
+/**
+ * Is the `prave` binary globally installed and on PATH?
+ *
+ * Uses `which` (POSIX) / `where` (Windows) to probe. Returns true only
+ * when the resolved path is NOT inside an npx temp directory — that
+ * way running this command via `npx @prave/cli mcp install` doesn't
+ * fool the detector into thinking the user has a permanent install
+ * (the resolved binary in that case is in `~/.npm/_npx/...`).
+ *
+ * Timeout: 1s. If `which` hangs (shouldn't ever, but networked
+ * filesystems are weird), we fall back to the npx form. Worst case
+ * is one extra npx hop per Claude Desktop launch — not a correctness
+ * issue.
+ */
+async function detectGlobalPrave() {
+    return new Promise((resolve) => {
+        const cmd = platform() === 'win32' ? 'where' : 'which';
+        const child = spawn(cmd, ['prave'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let output = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            resolve(false);
+        }, 1_000);
+        child.stdout?.on('data', (chunk) => {
+            output += chunk.toString('utf8');
+        });
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code !== 0 || !output.trim()) {
+                resolve(false);
+                return;
+            }
+            // Filter out npx-temp paths so an in-flight `npx @prave/cli` run
+            // doesn't get mistaken for a global install.
+            const firstLine = output.split('\n')[0]?.trim() ?? '';
+            const looksLikeNpxTemp = /[/\\](_npx|\.npm[/\\]_npx|npm-cache[/\\]_npx)[/\\]/i.test(firstLine);
+            resolve(!looksLikeNpxTemp);
+        });
+    });
+}
+// Silences the unused-import lint when no other branch reads `stat`.
+// The function is kept here intentionally for future expansion (e.g.
+// staleness check on `.bak` files) without re-adding the import.
+void stat;

package/dist/commands/mcp-server.js

@@ -0,0 +1,211 @@
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { api, ApiError } from '../lib/api.js';
+import { loadCredentials } from '../lib/credentials.js';
+const TOOLS = [
+    {
+        name: 'prave_search_skills',
+        description: 'Search the public Prave catalogue of Claude Skills. Returns up to 20 results. Use this when the user is exploring which Skill to install, or asking what Skills exist for a domain.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Keyword or phrase to search. Searches name + description + tags.',
+                },
+                category: {
+                    type: 'string',
+                    description: 'Optional category filter (e.g. "testing", "design", "deployment"). See the Discover page for the full list.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 20,
+                    default: 10,
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'prave_whatdoes',
+        description: 'Look up one Skill by slug. Returns the canonical name, description, tags, install count, and rating. Useful as a confirmation step before `prave_install_skill`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'Skill slug, e.g. "vercel-labs-agent-skills-react-best-practices".' },
+            },
+            required: ['slug'],
+        },
+    },
+    {
+        name: 'prave_my_skills',
+        description: 'List Skills the signed-in user has installed locally or authored. Useful when the user asks "what Skills do I already have?".',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'prave_audit_library',
+        description: 'Return the Skill Intelligence overview for the signed-in user: total Skill count, library token footprint, trigger count over the last 30 days, conflicts detected, and the 5 token-heaviest Skills. Use this when the user asks about token cost, performance, or which Skills to trim.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'prave_install_skill',
+        description: 'Install a Skill from the catalogue into the user\'s local agent directory (~/.claude/skills/). Spawns the `prave install <slug>` CLI subprocess and streams its output back. Use only after confirming the slug with `prave_whatdoes`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                slug: { type: 'string', description: 'Skill slug to install.' },
+            },
+            required: ['slug'],
+        },
+    },
+];
+export async function mcpServerCommand() {
+    // Auth check up-front. If the user runs `prave mcp-server` without
+    // logging in, the MCP frame would otherwise look healthy but every
+    // tool call would fail with 401 — confusing. Emit a clear stderr
+    // message and exit, so Claude Desktop's MCP UI surfaces a bad-config
+    // error instead of letting the user wonder.
+    const creds = await loadCredentials();
+    if (!creds) {
+        process.stderr.write('prave mcp-server: not logged in. Run `prave login` first.\n');
+        process.exit(1);
+    }
+    const server = new Server({ name: 'prave-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args = {} } = req.params;
+        // Best-effort heartbeat — every successful tool call pings the
+        // server so the Settings → MCP card knows the user is wired in.
+        // Fired-and-forgotten; failures don't break the tool response.
+        void pingHeartbeat();
+        try {
+            switch (name) {
+                case 'prave_search_skills':
+                    return await handleSearch(args);
+                case 'prave_whatdoes':
+                    return await handleWhatdoes(args);
+                case 'prave_my_skills':
+                    return await handleMySkills();
+                case 'prave_audit_library':
+                    return await handleAuditLibrary();
+                case 'prave_install_skill':
+                    return await handleInstallSkill(args);
+                default:
+                    return mcpError(`Unknown tool: ${name}`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof ApiError ? err.message : err.message;
+            return mcpError(msg);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Block forever — the transport keeps the event loop alive while
+    // stdio is open. Process exits cleanly when the parent (Claude
+    // Desktop) closes the pipe.
+}
+/* ─── tool handlers ────────────────────────────────────────────── */
+async function handleSearch(args) {
+    const params = new URLSearchParams();
+    params.set('q', args.query);
+    if (args.category)
+        params.set('category', args.category);
+    params.set('limit', String(Math.min(20, Math.max(1, args.limit ?? 10))));
+    const { data } = await api.get(`/api/v1/skills?${params.toString()}`, true);
+    const items = data.items ?? [];
+    const lines = items.map((s) => `• ${s.name} (${s.slug}) — ${s.description ?? 'no description'} · ↓${s.install_count}`);
+    return mcpText(lines.length
+        ? `Found ${lines.length} Skill${lines.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}`
+        : `No Skills matched "${args.query}".`);
+}
+async function handleWhatdoes(args) {
+    const { data } = await api.get(`/api/v1/skills/${encodeURIComponent(args.slug)}`, true);
+    return mcpText([
+        `${data.name} (${data.slug})`,
+        data.description ?? '(no description)',
+        '',
+        `Tags: ${data.tags.length ? data.tags.join(', ') : '(none)'}`,
+        `Installs: ${data.install_count}`,
+        data.rating != null ? `Rating: ${data.rating.toFixed(1)}/5` : '',
+    ]
+        .filter(Boolean)
+        .join('\n'));
+}
+async function handleMySkills() {
+    const { data } = await api.get('/api/v1/me/skills', true);
+    const items = data.items ?? [];
+    if (items.length === 0) {
+        return mcpText('You haven\'t installed or authored any Skills yet. Try `prave_search_skills` to browse the catalogue.');
+    }
+    const lines = items.map((s) => `• ${s.name} (${s.slug})`);
+    return mcpText(`You have ${items.length} Skill${items.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}`);
+}
+async function handleAuditLibrary() {
+    const { data } = await api.get('/api/v1/intelligence/overview', true);
+    const heaviestLines = data.heaviest
+        .slice(0, 5)
+        .map((s) => `  • ${s.name ?? s.slug ?? '(unnamed)'} — ${s.estimated_tokens.toLocaleString()} tokens`);
+    return mcpText([
+        `Skill Intelligence overview`,
+        ``,
+        `Total Skills indexed: ${data.total_skills}`,
+        `Library token footprint: ${data.total_estimated_tokens.toLocaleString()} tokens`,
+        `Triggered in last 30 days: ${data.triggered_30d}`,
+        `Conflicts detected: ${data.conflict_count}`,
+        ``,
+        `Top 5 token-heaviest:`,
+        ...(heaviestLines.length ? heaviestLines : ['  (none indexed yet — run `prave sync`)']),
+    ].join('\n'));
+}
+async function handleInstallSkill(args) {
+    // Run the existing CLI install command as a subprocess. Identical
+    // behavior to a user typing `prave install <slug>` — same plan
+    // checks, same dependency resolution, same on-disk effects. Tail
+    // the output for the MCP response.
+    return await new Promise((resolve) => {
+        const child = spawn(process.argv[0] ?? 'node', [process.argv[1] ?? '', 'install', args.slug], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => {
+            resolve(mcpError(`Failed to spawn install: ${err.message}`));
+        });
+        child.on('close', (code) => {
+            const output = (stdout + (stderr ? `\n${stderr}` : '')).trim() ||
+                (code === 0 ? `Installed ${args.slug}.` : `Install exited with code ${code}.`);
+            resolve(code === 0
+                ? mcpText(output)
+                : mcpError(output));
+        });
+    });
+}
+/* ─── helpers ──────────────────────────────────────────────────── */
+function mcpText(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function mcpError(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+async function pingHeartbeat() {
+    try {
+        await api.post('/api/v1/me/mcp-heartbeat', {}, true);
+    }
+    catch {
+        // Heartbeat is fire-and-forget. The MCP tool still works even
+        // when the heartbeat endpoint is unreachable (e.g. brief API
+        // outage); the SaaS Settings card just won't update its
+        // last-seen timestamp.
+    }
+}

package/dist/commands/usage.js

@@ -7,6 +7,7 @@ import { api, ApiError } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
 import { requireAuth } from '../lib/credentials.js';
 import { HOOK_SUPPORTED, installHooksForAgents, uninstallHooksForAgents, } from '../lib/hook.js';
+import { bufferEvent } from '../lib/telemetry-buffer.js';
 import { AGENT_REGISTRY } from '@prave/shared';
 import { loadCursor, saveCursor } from '../lib/usage-cursor.js';
 import { scanTranscriptsForUsage } from '../lib/usage-scanner.js';
@@ -159,12 +160,6 @@ export async function usageReportCommand(opts = {}) {
     }
     if (debug)
         await debugLog(`slug=${slug}`);
-    const session = await requireAuthSilent();
-    if (!session) {
-        if (debug)
-            await debugLog('no auth — skipping');
-        return;
-    }
     // Build the telemetry blob from whatever Claude Code shipped in the
     // payload. Everything is best-effort — missing fields just don't
     // appear in `meta`. The server schema (usageMetaSchema) validates
@@ -192,11 +187,30 @@ export async function usageReportCommand(opts = {}) {
         if (typeof obj.prompt === 'string')
             meta.prompt_chars = obj.prompt.length;
     }
+    const triggered_at = new Date().toISOString();
+    const session = await requireAuthSilent();
+    // No credentials? Don't drop the event — buffer it to disk. The next
+    // `prave login` (or any authenticated command that calls
+    // `flushBufferedTelemetry`) replays the file against the same
+    // by-slug endpoint, so no Skill invocation is ever lost just because
+    // the user happened to be signed out at hook-fire time.
+    if (!session) {
+        await bufferEvent({
+            slug,
+            agent_type: 'claude',
+            triggered_at,
+            meta: { ...meta, source },
+        });
+        await hookLog(`${source}:buffered slug=${slug}`);
+        if (debug)
+            await debugLog(`no auth — buffered to telemetry-queue`);
+        return;
+    }
     try {
         const { data } = await api.post('/api/v1/intelligence/usage/by-slug', {
             slug,
             agent_type: 'claude',
-            triggered_at: new Date().toISOString(),
+            triggered_at,
             meta: { ...meta, source },
         }, true);
         await hookLog(`${source}:ok slug=${slug} recorded=${data.recorded} stub=${data.created_stub}`);
@@ -205,11 +219,18 @@ export async function usageReportCommand(opts = {}) {
         }
     }
     catch (err) {
+        // Network down or API error while authenticated — also buffer so
+        // the event isn't lost. The next successful command will replay.
+        await bufferEvent({
+            slug,
+            agent_type: 'claude',
+            triggered_at,
+            meta: { ...meta, source },
+        });
         const msg = err.message;
-        await hookLog(`${source}:err slug=${slug} ${msg.slice(0, 120)}`);
+        await hookLog(`${source}:buffered-on-err slug=${slug} ${msg.slice(0, 80)}`);
         if (debug)
-            await debugLog(`error: ${msg}`);
-        /* silent — never break the host shell */
+            await debugLog(`api error, buffered: ${msg}`);
     }
 }
 /**

package/dist/index.js

@@ -12,6 +12,8 @@ import { installCommand } from './commands/install.js';
 import { listCommand } from './commands/list.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
+import { mcpInstallCommand } from './commands/mcp-install.js';
+import { mcpServerCommand } from './commands/mcp-server.js';
 import { optimizeCommand } from './commands/optimize.js';
 import { overviewCommand } from './commands/overview.js';
 import { searchCommand } from './commands/search.js';
@@ -161,6 +163,15 @@ program
     .option('--agent <agent>', 'restrict deploy to a single agent (claude-code | codex | cursor | gemini | cline | amp)')
     .option('--dry-run', 'log every destination path but write nothing — preview before committing')
     .action(deployCommand);
+program
+    .command('mcp-server')
+    .description('Run the Prave MCP server over stdio. Wire into Claude Desktop / Cursor MCP / Continue.dev via { "command": "npx", "args": ["-y", "@prave/cli", "mcp-server"] }. Exposes search, install, audit, my-skills, whatdoes as MCP tools.')
+    .action(mcpServerCommand);
+program
+    .command('mcp install')
+    .alias('mcp-install')
+    .description('One-command setup: patches Claude Desktop\'s config to wire the Prave MCP server. Idempotent, takes a `.bak` of any existing config, preserves other mcpServers entries. Restart Claude Desktop after running.')
+    .action(mcpInstallCommand);
 // ─── Help command — full quick-reference ───────────────────────────
 program
     .command('cheat')

package/dist/lib/flush-telemetry.js

@@ -0,0 +1,42 @@
+import chalk from 'chalk';
+import { api } from './api.js';
+import { log } from '../utils/logger.js';
+import { flushBuffered, pendingTelemetryCount, } from './telemetry-buffer.js';
+/**
+ * Replay any offline-buffered Skill-invocation events. Called by
+ * `prave login` (right after credentials land on disk) and also by
+ * the API client on every successful authenticated request, so the
+ * queue drains opportunistically even without a fresh login.
+ *
+ * Behavior:
+ *   - silent when the queue is empty (most invocations)
+ *   - prints "Syncing N telemetry events…" + a success or partial
+ *     line when there's a non-zero count
+ *   - never throws — telemetry failures must not break the CLI
+ *
+ * `force` skips the early "empty?" check, useful right after login
+ * where we know we just succeeded and want the user to see whatever
+ * sync number lands (even if zero — feels reassuring).
+ */
+export async function flushBufferedTelemetry(opts = {}) {
+    try {
+        const pending = await pendingTelemetryCount();
+        if (pending === 0 && !opts.force)
+            return;
+        if (pending === 0)
+            return; // even with force, no spinner for 0
+        log.info(`${chalk.cyan('●')} You have telemetry updates from offline sessions. Syncing ${chalk.bold(pending)} event${pending === 1 ? '' : 's'} to your dashboard…`);
+        const result = await flushBuffered(async (body) => {
+            await api.post('/api/v1/intelligence/usage/by-slug', body, true);
+        });
+        if (result.failed === 0) {
+            log.success(`Synced ${chalk.bold(result.sent)} telemetry event${result.sent === 1 ? '' : 's'}. Dashboard is up to date.`);
+        }
+        else {
+            log.warn(`Synced ${result.sent} of ${result.total} — ${result.failed} will retry on the next run.`);
+        }
+    }
+    catch {
+        /* swallow — telemetry sync is best-effort */
+    }
+}

package/dist/lib/telemetry-buffer.js

@@ -0,0 +1,131 @@
+import { appendFile, mkdir, readFile, stat, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONFIG } from './config.js';
+/**
+ * Offline telemetry buffer.
+ *
+ * When the PostToolUse hook fires while the user is logged out (no
+ * credentials in ~/.prave/credentials.json), the Skill invocation would
+ * otherwise be lost — the hook can't reach the API. Instead we append
+ * the event as one JSON line to `~/.prave/telemetry-queue.jsonl` and
+ * replay the whole file the next time the user logs in (or runs any
+ * command that hits the API while authenticated).
+ *
+ * Each line is the exact payload the live hook would have POSTed to
+ * `/api/v1/intelligence/usage/by-slug`, so replay is "send each line
+ * through the same endpoint". Server-side dedup (per-minute bucket
+ * keyed by `skill_metadata_id + agent_type`) makes the flush idempotent
+ * — a flush that crashes mid-way can re-run with no double-counting.
+ *
+ * The queue file is hard-capped at 5000 events (~600 KB of JSONL).
+ * Beyond that we drop the oldest line per fire — telemetry is best-
+ * effort, never something that should grow unbounded on disk.
+ */
+export const TELEMETRY_QUEUE_FILE = join(CONFIG.praveDir, 'telemetry-queue.jsonl');
+const MAX_QUEUE_LINES = 5_000;
+const QUEUE_ROTATE_AT_BYTES = 1_000_000; // 1 MB safety stop
+/**
+ * Append one event to the queue. Best-effort: any FS failure is
+ * swallowed because the hook MUST NOT throw — failing telemetry can
+ * never break the user's editor.
+ */
+export async function bufferEvent(event) {
+    try {
+        await mkdir(CONFIG.praveDir, { recursive: true });
+        // Rotate before append if the file got too big. We keep the
+        // newest half — recent telemetry is more valuable than ancient
+        // backlog the user probably doesn't care about anymore.
+        const info = await stat(TELEMETRY_QUEUE_FILE).catch(() => null);
+        if (info && info.size > QUEUE_ROTATE_AT_BYTES) {
+            const raw = await readFile(TELEMETRY_QUEUE_FILE, 'utf8').catch(() => '');
+            const lines = raw.split('\n').filter(Boolean);
+            if (lines.length > MAX_QUEUE_LINES) {
+                const trimmed = lines.slice(-Math.floor(MAX_QUEUE_LINES / 2));
+                await writeFile(TELEMETRY_QUEUE_FILE, trimmed.join('\n') + '\n', 'utf8');
+            }
+        }
+        await appendFile(TELEMETRY_QUEUE_FILE, JSON.stringify(event) + '\n', 'utf8');
+    }
+    catch {
+        /* swallow — telemetry is best-effort */
+    }
+}
+/**
+ * Read the queue. Returns parsed events plus the raw line count so
+ * callers can report "N events synced". Skips malformed lines silently
+ * — a single corrupt write must not kill an entire replay.
+ */
+async function readQueue() {
+    const raw = await readFile(TELEMETRY_QUEUE_FILE, 'utf8').catch(() => null);
+    if (!raw)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const t = line.trim();
+        if (!t)
+            continue;
+        try {
+            const parsed = JSON.parse(t);
+            if (parsed.slug && parsed.triggered_at)
+                out.push(parsed);
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    return out;
+}
+/**
+ * Replay the queue against the by-slug endpoint and delete the file on
+ * full success. Caller passes the already-authenticated POST helper so
+ * we don't introduce a circular dep on api.ts.
+ *
+ * On partial failure (network blip mid-flush), the remaining events
+ * are rewritten so a later attempt picks up where we left off. Order
+ * is preserved across rewrites.
+ */
+export async function flushBuffered(postBySlug) {
+    const events = await readQueue();
+    if (!events.length)
+        return { sent: 0, failed: 0, total: 0 };
+    let sent = 0;
+    const remaining = [];
+    for (let i = 0; i < events.length; i++) {
+        const ev = events[i];
+        if (!ev)
+            continue;
+        try {
+            await postBySlug({ ...ev, source: 'buffered' });
+            sent += 1;
+        }
+        catch {
+            // Keep this one and every event after it for the next attempt.
+            // We don't push-and-continue because a network blip likely means
+            // every subsequent POST will fail too — better to stop fast.
+            remaining.push(...events.slice(i));
+            break;
+        }
+    }
+    if (remaining.length === 0) {
+        await unlink(TELEMETRY_QUEUE_FILE).catch(() => { });
+    }
+    else {
+        await writeFile(TELEMETRY_QUEUE_FILE, remaining.map((e) => JSON.stringify(e)).join('\n') + '\n', 'utf8').catch(() => { });
+    }
+    return { sent, failed: remaining.length, total: events.length };
+}
+/**
+ * Cheap "is there anything to flush?" check — used by login/whoami to
+ * decide whether to print the "syncing pending telemetry" line at all.
+ * Returns 0 when the file doesn't exist OR is empty.
+ */
+export async function pendingTelemetryCount() {
+    const raw = await readFile(TELEMETRY_QUEUE_FILE, 'utf8').catch(() => null);
+    if (!raw)
+        return 0;
+    let n = 0;
+    for (const line of raw.split('\n'))
+        if (line.trim())
+            n += 1;
+    return n;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -26,14 +26,14 @@
   "homepage": "https://prave.app",
   "bugs": {
     "url": "https://github.com/eppstudio/prave/issues",
-    "email": "info@epplab-studio.de"
+    "email": "hello@epplab-studio.de"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/eppstudio/prave.git",
     "directory": "apps/cli"
   },
-  "author": "EppLab Studio <info@epplab-studio.de> (https://epplab-studio.de)",
+  "author": "EppLab Studio <hello@epplab-studio.de> (https://epplab-studio.de)",
   "license": "MIT",
   "engines": {
     "node": ">=18"
@@ -46,12 +46,13 @@
     "dist"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "open": "^10.1.0",
     "ora": "^8.0.1",
     "undici": "^6.18.0",
-    "@prave/shared": "1.2.1"
+    "@prave/shared": "1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",