@prave/cli 0.5.0 → 1.0.1

package/dist/commands/login.js

@@ -33,6 +33,16 @@ export async function loginCommand() {
                 user_id: data.user_id,
             });
             spinner.succeed('Logged in.');
+            // 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.
+            try {
+                const { runAgentOnboarding } = await import('../lib/agent-onboarding.js');
+                await runAgentOnboarding();
+            }
+            catch (onboardErr) {
+                log.dim(`Agent onboarding skipped: ${onboardErr.message}`);
+            }
             return;
         }
         catch (err) {

package/dist/commands/settings.js

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
-import { AGENT_REGISTRY, AGENT_TYPES } from '@prave/shared';
+import { AGENT_REGISTRY } from '@prave/shared';
 import { api, ApiError } from '../lib/api.js';
 import { requireAuth } from '../lib/credentials.js';
 import { CONFIG } from '../lib/config.js';
@@ -36,37 +36,15 @@ async function patchSettings(patch) {
     const { data } = await api.put('/api/v1/settings/agents', patch, true);
     return data;
 }
-function isAgentType(s) {
-    return AGENT_TYPES.includes(s);
-}
-async function configureAgents(rl, current) {
-    console.log();
-    console.log(chalk.bold('Available agents:'));
-    for (const id of AGENT_TYPES) {
-        const meta = AGENT_REGISTRY[id];
-        const enabled = current.enabled_agents.includes(id) ? chalk.green('✓') : ' ';
-        console.log(`  ${enabled} ${chalk.cyan(meta.id.padEnd(8))} ${meta.label} ${chalk.dim('— ' + meta.description)}`);
-    }
-    const answer = (await rl.question(`\nEnter comma-separated agents to enable (default: ${current.enabled_agents.join(',') || 'claude'}): `)).trim();
-    let enabled = current.enabled_agents;
-    if (answer) {
-        const tokens = answer
-            .split(',')
-            .map((t) => t.trim().toLowerCase())
-            .filter(Boolean);
-        const invalid = tokens.filter((t) => !isAgentType(t));
-        if (invalid.length > 0) {
-            log.warn(`Unknown agents skipped: ${invalid.join(', ')}`);
-        }
-        enabled = tokens.filter(isAgentType);
-        if (enabled.length === 0) {
-            log.warn('No valid agents selected — keeping previous selection.');
-            return current;
-        }
-    }
-    const updated = await patchSettings({ enabled_agents: enabled });
+async function configureAgents(_rl, current) {
+    // Reuse the shared onboarding flow. Same UX as `prave login`: space to
+    // toggle, enter to confirm, plus an opt-in hook install. Persists via
+    // PUT /api/v1/settings/agents so web + CLI stay in lockstep.
+    const { runAgentOnboarding } = await import('../lib/agent-onboarding.js');
+    const updated = await runAgentOnboarding();
+    if (!updated)
+        return current;
     await saveLocalConfig(updated);
-    log.success(`Enabled agents: ${updated.enabled_agents.join(', ')}`);
     return updated;
 }
 async function configurePaths(rl, current) {

package/dist/commands/sync.js

@@ -88,4 +88,15 @@ export async function syncCommand() {
             }
         }
     }
+    // Tail end of sync: fire a quiet usage scan so the optimiser stays warm
+    // without the user having to remember an extra command. Quiet mode means
+    // we only log a one-liner ("Usage: 12 new, 88 known.") instead of taking
+    // over the spinner. Failures are non-fatal — sync's primary job is done.
+    try {
+        const { usageScanCommand } = await import('./usage.js');
+        await usageScanCommand({ quiet: true });
+    }
+    catch {
+        /* swallow — usage tracking is best-effort */
+    }
 }

package/dist/commands/usage.js

@@ -0,0 +1,267 @@
+import { readdir, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+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 { AGENT_REGISTRY } from '@prave/shared';
+import { loadCursor, saveCursor } from '../lib/usage-cursor.js';
+import { scanTranscriptsForUsage } from '../lib/usage-scanner.js';
+import { log } from '../utils/logger.js';
+/**
+ * `prave usage scan` — read every recent JSONL transcript on disk, find
+ * Skill invocations, and POST them to `/api/v1/intelligence/usage/batch`.
+ * Hour-bucket dedup happens server-side, so re-runs are cheap.
+ *
+ * Use `--since=7d` to override the watermark (handy when you've manually
+ * cleared the cursor or want to backfill). `--quiet` suppresses output —
+ * used by `prave sync` to chain a scan without spamming the terminal.
+ */
+export async function usageScanCommand(opts) {
+    const session = await requireAuth('prave usage scan');
+    if (!session)
+        return;
+    const since = opts.since ? parseSinceFlag(opts.since) : await loadCursor();
+    const spinner = opts.quiet ? null : ora('Scanning Claude Code transcripts…').start();
+    // 1. Gather installed slug list — this is our recognition allowlist.
+    const slugs = await listInstalledSlugs();
+    if (!slugs.length) {
+        spinner?.warn('No Skills installed locally — nothing to track.');
+        return;
+    }
+    // 2. Scan local JSONL transcripts.
+    let events = [];
+    try {
+        events = await scanTranscriptsForUsage(slugs, since);
+    }
+    catch (err) {
+        spinner?.fail(`Scan failed: ${err.message}`);
+        return;
+    }
+    if (!events.length) {
+        spinner?.succeed(`No new Skill invocations since ${since.toISOString()}.`);
+        await saveCursor();
+        return;
+    }
+    if (spinner)
+        spinner.text = `Mapping ${events.length} events to your Skill catalog…`;
+    // 3. Map slug → skill_metadata_id via the intelligence API.
+    let metadata = [];
+    try {
+        const { data } = await api.get('/api/v1/intelligence/skills', true);
+        metadata = data;
+    }
+    catch (err) {
+        spinner?.fail(err instanceof ApiError
+            ? `Couldn't fetch your Skill catalog: ${err.message}`
+            : 'Network error fetching your Skill catalog.');
+        return;
+    }
+    const slugToId = buildSlugMap(metadata);
+    const payload = events
+        .map((e) => {
+        const id = slugToId.get(e.slug);
+        if (!id)
+            return null;
+        return {
+            skill_metadata_id: id,
+            triggered_at: e.triggered_at,
+            trigger_phrase: e.trigger_phrase ?? null,
+        };
+    })
+        .filter((e) => Boolean(e));
+    if (!payload.length) {
+        spinner?.succeed('Found events, but none matched the Skills tracked on your account. Run `prave import --upload` first.');
+        return;
+    }
+    // 4. Send in chunks of 500 (server cap).
+    if (spinner)
+        spinner.text = `Reporting ${payload.length} events…`;
+    let inserted = 0;
+    let deduped = 0;
+    for (let i = 0; i < payload.length; i += 500) {
+        const slice = payload.slice(i, i + 500);
+        try {
+            const { data } = await api.post('/api/v1/intelligence/usage/batch', { events: slice }, true);
+            inserted += data.inserted;
+            deduped += data.deduped;
+        }
+        catch (err) {
+            spinner?.fail(`Upload failed mid-batch: ${err.message}`);
+            return;
+        }
+    }
+    await saveCursor();
+    if (spinner) {
+        spinner.succeed(`${chalk.bold(inserted)} new event${inserted === 1 ? '' : 's'} reported · ${deduped} already known.`);
+    }
+    else if (!opts.quiet) {
+        log.dim(`Usage: ${inserted} new, ${deduped} known.`);
+    }
+}
+/**
+ * `prave usage report` — invoked by the Claude Code `PostToolUse` hook.
+ * Reads the hook payload from stdin, extracts the Skill name, and fires
+ * a single-event POST. Errors are silent (we never want a hook failure
+ * to disturb the user's workflow).
+ */
+export async function usageReportCommand() {
+    // Hook payload arrives on stdin. If we can't read it, exit silently.
+    const stdinPayload = await readStdin();
+    if (!stdinPayload)
+        return;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(stdinPayload);
+    }
+    catch {
+        return;
+    }
+    const rawSlug = parsed.tool_input?.skill;
+    if (typeof rawSlug !== 'string' || !rawSlug.trim())
+        return;
+    const slug = rawSlug.toLowerCase().split(':').pop()?.trim();
+    if (!slug)
+        return;
+    // No auth → bail silently. The user is browsing logged-out; we're not
+    // going to bug them with a login prompt from a background hook.
+    const session = await requireAuthSilent();
+    if (!session)
+        return;
+    try {
+        const { data: metadata } = await api.get('/api/v1/intelligence/skills', true);
+        const id = buildSlugMap(metadata).get(slug);
+        if (!id)
+            return;
+        await api.post('/api/v1/intelligence/usage', { skill_metadata_id: id, trigger_phrase: null }, true);
+    }
+    catch {
+        /* silent — never break the host shell */
+    }
+}
+export async function usageHookInstallCommand() {
+    const session = await requireAuth('prave usage hook install');
+    if (!session)
+        return;
+    const agents = await fetchEnabledAgents();
+    if (!agents.length) {
+        log.warn('No agents enabled on your account. Run `prave settings` or `prave login` first.');
+        return;
+    }
+    const results = await installHooksForAgents(agents);
+    printAgentResults(results, 'install');
+}
+export async function usageHookUninstallCommand() {
+    const session = await requireAuth('prave usage hook uninstall');
+    if (!session)
+        return;
+    const agents = await fetchEnabledAgents();
+    if (!agents.length) {
+        // Nothing in the SaaS profile? Try removing from Claude anyway —
+        // the user might have installed manually.
+        const results = await uninstallHooksForAgents(['claude']);
+        printAgentResults(results, 'uninstall');
+        return;
+    }
+    const results = await uninstallHooksForAgents(agents);
+    printAgentResults(results, 'uninstall');
+}
+async function fetchEnabledAgents() {
+    try {
+        const { data } = await api.get('/api/v1/settings/agents', true);
+        return data.enabled_agents ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+function printAgentResults(results, verb) {
+    for (const r of results) {
+        const label = AGENT_REGISTRY[r.agent].label;
+        if (r.status === 'installed') {
+            log.success(`${label} hook ${verb === 'install' ? 'installed' : 'removed'}`);
+        }
+        else if (r.status === 'already') {
+            log.dim(`${label}: ${verb === 'install' ? 'already installed' : 'nothing to remove'}`);
+        }
+        else if (r.status === 'unsupported') {
+            log.dim(`${label}: real-time hook not yet supported — usage scan still tracks via \`prave sync\`.`);
+        }
+        else {
+            log.warn(`${label}: ${r.message ?? 'failed'}`);
+        }
+    }
+    if (verb === 'install') {
+        const installed = results.filter((r) => r.status === 'installed' || r.status === 'already');
+        if (installed.length) {
+            log.dim(`Run \`prave usage hook uninstall\` to remove. Supported agents: ${HOOK_SUPPORTED.join(', ')}.`);
+        }
+    }
+}
+async function listInstalledSlugs() {
+    try {
+        const entries = await readdir(CONFIG.skillsDir);
+        const slugs = [];
+        for (const name of entries) {
+            if (name.startsWith('.'))
+                continue;
+            const dir = join(CONFIG.skillsDir, name);
+            if ((await stat(dir).catch(() => null))?.isDirectory())
+                slugs.push(name.toLowerCase());
+        }
+        return slugs;
+    }
+    catch {
+        return [];
+    }
+}
+function buildSlugMap(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        if (!row.file_path)
+            continue;
+        // file_path looks like "<skillsDir>/<slug>/SKILL.md" — slug is the
+        // parent directory name. We also fall back to the row's `name` so a
+        // server that stored the slug in `name` still resolves.
+        const parts = row.file_path.split('/').filter(Boolean);
+        const skillIdx = parts.findIndex((p) => p === 'skills');
+        const slug = skillIdx >= 0 && parts[skillIdx + 1]
+            ? parts[skillIdx + 1].toLowerCase()
+            : (basename(row.file_path.replace(/\/SKILL\.md$/i, '')) || '').toLowerCase();
+        if (slug)
+            map.set(slug, row.id);
+        if (row.name)
+            map.set(row.name.toLowerCase(), row.id);
+    }
+    return map;
+}
+function parseSinceFlag(raw) {
+    const m = /^(\d+)([dh])$/.exec(raw.trim());
+    if (!m)
+        return new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+    const n = Number(m[1]);
+    const unit = m[2];
+    const ms = unit === 'h' ? n * 60 * 60 * 1000 : n * 24 * 60 * 60 * 1000;
+    return new Date(Date.now() - ms);
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return '';
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+        if (Buffer.concat(chunks).length > 1_000_000)
+            break;
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Auth check with no UX side-effects. Used by the hook so a logged-out
+ * user never sees a stray "please log in" message during their workflow.
+ */
+async function requireAuthSilent() {
+    const { loadCredentials } = await import('../lib/credentials.js');
+    return loadCredentials();
+}

package/dist/commands/whoami.js

@@ -17,6 +17,17 @@ export async function whoamiCommand() {
         process.exitCode = 1;
         return;
     }
+    // Detect creds left over from older CLI versions that predate the
+    // refresh-token flow. Without a refresh_token we can't auto-rotate the
+    // expired access_token, so the user gets stuck in a "session expired"
+    // loop. Direct them to `prave login` immediately rather than letting
+    // the API call fail confusingly.
+    if (!creds.refresh_token) {
+        log.warn('Stored credentials predate the refresh-token flow.');
+        log.dim('Run `prave login` once to upgrade — refreshes will be automatic afterwards.');
+        process.exitCode = 1;
+        return;
+    }
     try {
         const { data } = await api.get('/api/v1/me', true);
         const handle = data.username || data.display_name || data.email || creds.email || 'unknown';

package/dist/index.js

@@ -20,6 +20,7 @@ import { settingsCommand } from './commands/settings.js';
 import { syncCommand } from './commands/sync.js';
 import { uninstallCommand } from './commands/uninstall.js';
 import { updateCommand } from './commands/update.js';
+import { usageHookInstallCommand, usageHookUninstallCommand, usageReportCommand, usageScanCommand, } from './commands/usage.js';
 import { whatdoesCommand } from './commands/whatdoes.js';
 import { whoamiCommand } from './commands/whoami.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -100,6 +101,28 @@ program
     .description('Recommendations: underused, mergeable, and heavy skills')
     .option('--apply', 'placeholder for auto-apply')
     .action(optimizeCommand);
+const usage = program
+    .command('usage')
+    .description('Track which Skills you actually use (powers the optimiser)');
+usage
+    .command('scan')
+    .description('Scan local Claude Code transcripts and report invocations to Prave')
+    .option('--since <window>', 'override the watermark, e.g. "7d" or "12h"')
+    .option('--quiet', 'log a one-liner instead of a spinner')
+    .action(usageScanCommand);
+usage
+    .command('report')
+    .description('Internal: invoked by the Claude Code PostToolUse hook (reads stdin)')
+    .action(usageReportCommand);
+const hook = usage.command('hook').description('Install/uninstall the Claude Code real-time usage hook');
+hook
+    .command('install')
+    .description('Add a PostToolUse hook to ~/.claude/settings.json')
+    .action(usageHookInstallCommand);
+hook
+    .command('uninstall')
+    .description('Remove the Prave-managed hook from ~/.claude/settings.json')
+    .action(usageHookUninstallCommand);
 program
     .command('find <query>')
     .description('Smart skill search across local and marketplace')

package/dist/lib/agent-onboarding.js

@@ -0,0 +1,107 @@
+import { AGENT_REGISTRY, AGENT_TYPES } from '@prave/shared';
+import chalk from 'chalk';
+import { api } from './api.js';
+import { HOOK_SUPPORTED, installHooksForAgents } from './hook.js';
+import { checkboxPrompt } from './prompt.js';
+import { log } from '../utils/logger.js';
+/**
+ * Shared "pick which agents you use" flow. Called by `prave login`
+ * (right after credentials are saved) and reused by
+ * `prave settings → Agent Configuration` so the user gets exactly the
+ * same UX in both places — no 1-5 numeric menus, no comma-separated
+ * typing.
+ *
+ * After the pick we also offer to install the real-time hook on every
+ * supported agent. Hook installation is opt-in: if the user just wants
+ * the agents enabled without hooks, they hit `n` at the second prompt.
+ */
+export async function runAgentOnboarding() {
+    // 1. Pull whatever the SaaS profile already has so we prefill the
+    //    selection from the user's web settings.
+    let current = null;
+    try {
+        const { data } = await api.get('/api/v1/settings/agents', true);
+        current = data;
+    }
+    catch {
+        /* fresh user with no saved prefs — fall through to defaults */
+    }
+    const items = AGENT_TYPES.map((id) => {
+        const meta = AGENT_REGISTRY[id];
+        const supportsHook = HOOK_SUPPORTED.includes(id);
+        return {
+            value: id,
+            label: meta.label,
+            hint: supportsHook ? `${meta.description} · real-time hook` : meta.description,
+        };
+    });
+    const initial = (current?.enabled_agents ?? ['claude']);
+    const picked = await checkboxPrompt('Which agents should Prave manage?', items, { initial, minSelected: 1 });
+    if (!picked) {
+        log.warn('No agents selected — keeping previous selection.');
+        return current;
+    }
+    // 2. Persist to SaaS so web + CLI stay in sync.
+    let updated = current ?? {
+        user_id: '',
+        enabled_agents: [],
+        skill_paths: {},
+        detected_os: detectOs(),
+        updated_at: new Date().toISOString(),
+    };
+    try {
+        const { data } = await api.put('/api/v1/settings/agents', { enabled_agents: picked, detected_os: detectOs() }, true);
+        updated = data;
+        log.info(`Enabled agents: ${chalk.cyan(updated.enabled_agents.join(', '))}`);
+    }
+    catch (err) {
+        log.warn(`Couldn't sync agents to your account: ${err.message}`);
+        return current;
+    }
+    // 3. Offer to install the real-time hook on every agent that supports
+    //    it. We make this a single y/n — the hook itself is uniform across
+    //    the chosen agents, so a per-agent confirmation would be friction.
+    const supportedPicks = picked.filter((a) => HOOK_SUPPORTED.includes(a));
+    if (!supportedPicks.length) {
+        log.dim('No real-time hook contract for the agents you picked yet — usage will still be tracked via `prave usage scan` (auto-runs on `prave sync`).');
+        return updated;
+    }
+    const wantHook = await yesNoPrompt(`Install the real-time usage hook for ${supportedPicks
+        .map((a) => AGENT_REGISTRY[a].label)
+        .join(', ')}? [y/N] `);
+    if (!wantHook) {
+        log.dim('Skipped. Run `prave usage hook install` later to enable.');
+        return updated;
+    }
+    const results = await installHooksForAgents(picked);
+    for (const r of results) {
+        const label = AGENT_REGISTRY[r.agent].label;
+        if (r.status === 'installed')
+            log.success(`${label} hook installed`);
+        else if (r.status === 'already')
+            log.dim(`${label} hook already present`);
+        else if (r.status === 'unsupported')
+            log.dim(`${label}: ${r.message}`);
+        else
+            log.warn(`${label}: ${r.message ?? 'install failed'}`);
+    }
+    return updated;
+}
+function detectOs() {
+    if (process.platform === 'darwin')
+        return 'mac';
+    if (process.platform === 'win32')
+        return 'windows';
+    return 'linux';
+}
+async function yesNoPrompt(question) {
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const ans = (await rl.question(question)).trim().toLowerCase();
+        return ans === 'y' || ans === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/lib/hook.js

@@ -0,0 +1,131 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/**
+ * Real-time usage hook installer. Currently only Claude Code exposes a
+ * suitable hook contract (`PostToolUse` with stdin payload) — the other
+ * supported agents (Codex, Cursor, Gemini, Cline, Amp) don't yet ship
+ * a comparable mechanism, so for those we degrade gracefully and let
+ * the transcript scanner cover them once they do.
+ *
+ * The Claude block is wrapped with sentinel keys (`__prave_managed: true`)
+ * so the uninstaller can find and remove only the Prave entry without
+ * disturbing user-authored hooks. Idempotent: re-installing just refreshes.
+ */
+const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+const HOOK_MARKER = '__prave_managed';
+/**
+ * Agents that currently support a real-time invocation hook. Adding a new
+ * agent to this list means implementing its `installFor<Agent>` branch
+ * below; until then we surface "not yet supported" so users are never
+ * misled about what's actually being instrumented.
+ */
+export const HOOK_SUPPORTED = ['claude'];
+const HOOK_COMMAND = 'prave usage report';
+export async function installSkillHook() {
+    const settings = await readSettings();
+    settings.hooks ??= {};
+    settings.hooks.PostToolUse ??= [];
+    const blocks = settings.hooks.PostToolUse;
+    const existingIdx = blocks.findIndex((b) => b.matcher === 'Skill' && b.hooks?.some((h) => h[HOOK_MARKER]));
+    const fresh = {
+        matcher: 'Skill',
+        hooks: [{ type: 'command', command: HOOK_COMMAND, [HOOK_MARKER]: true }],
+    };
+    if (existingIdx >= 0) {
+        const existingCmd = blocks[existingIdx]?.hooks?.[0]?.command;
+        if (existingCmd === HOOK_COMMAND) {
+            return { installed: false, alreadyPresent: true, settingsPath: SETTINGS_PATH };
+        }
+        blocks[existingIdx] = fresh;
+    }
+    else {
+        blocks.push(fresh);
+    }
+    await writeSettings(settings);
+    return { installed: true, alreadyPresent: false, settingsPath: SETTINGS_PATH };
+}
+export async function installHooksForAgents(agents) {
+    const out = [];
+    for (const agent of agents) {
+        if (!HOOK_SUPPORTED.includes(agent)) {
+            out.push({
+                agent,
+                status: 'unsupported',
+                message: `${agent} doesn't expose a real-time hook contract yet — transcript scanner via \`prave sync\` will track usage when supported.`,
+            });
+            continue;
+        }
+        try {
+            const result = await installSkillHook();
+            out.push({
+                agent,
+                status: result.alreadyPresent ? 'already' : 'installed',
+                message: result.settingsPath,
+            });
+        }
+        catch (err) {
+            out.push({ agent, status: 'error', message: err.message });
+        }
+    }
+    return out;
+}
+export async function uninstallHooksForAgents(agents) {
+    const out = [];
+    for (const agent of agents) {
+        if (!HOOK_SUPPORTED.includes(agent)) {
+            out.push({ agent, status: 'unsupported' });
+            continue;
+        }
+        try {
+            const result = await uninstallSkillHook();
+            out.push({
+                agent,
+                status: result.removed ? 'installed' : 'already',
+                message: result.settingsPath,
+            });
+        }
+        catch (err) {
+            out.push({ agent, status: 'error', message: err.message });
+        }
+    }
+    return out;
+}
+export async function uninstallSkillHook() {
+    const settings = await readSettings();
+    const blocks = settings.hooks?.PostToolUse;
+    if (!blocks?.length)
+        return { removed: false, settingsPath: SETTINGS_PATH };
+    const before = blocks.length;
+    const filtered = blocks
+        .map((b) => ({
+        ...b,
+        hooks: b.hooks?.filter((h) => !h[HOOK_MARKER]),
+    }))
+        .filter((b) => (b.hooks?.length ?? 0) > 0);
+    if (filtered.length === before && filtered.every((b, i) => b.hooks?.length === blocks[i]?.hooks?.length)) {
+        return { removed: false, settingsPath: SETTINGS_PATH };
+    }
+    if (settings.hooks) {
+        settings.hooks.PostToolUse = filtered;
+        if (!filtered.length)
+            delete settings.hooks.PostToolUse;
+        if (Object.keys(settings.hooks).length === 0)
+            delete settings.hooks;
+    }
+    await writeSettings(settings);
+    return { removed: true, settingsPath: SETTINGS_PATH };
+}
+async function readSettings() {
+    try {
+        const raw = await readFile(SETTINGS_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+async function writeSettings(settings) {
+    await mkdir(dirname(SETTINGS_PATH), { recursive: true });
+    await writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2), 'utf8');
+}

package/dist/lib/prompt.js

@@ -0,0 +1,181 @@
+import { stdin, stdout } from 'node:process';
+import chalk from 'chalk';
+export async function checkboxPrompt(question, items, opts = {}) {
+    if (!stdin.isTTY || !stdout.isTTY) {
+        return fallbackPrompt(question, items, opts);
+    }
+    const selected = new Set(opts.initial ?? []);
+    let cursor = 0;
+    const minSelected = opts.minSelected ?? 0;
+    let dataHandler = null;
+    const cleanup = () => {
+        if (typeof stdin.setRawMode === 'function')
+            stdin.setRawMode(false);
+        if (dataHandler)
+            stdin.off('data', dataHandler);
+        stdin.pause();
+        stdout.write(showCursor);
+        stdout.write('\n');
+    };
+    return new Promise((resolve) => {
+        if (typeof stdin.setRawMode === 'function')
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdout.write(hideCursor);
+        let firstRender = true;
+        const render = () => {
+            if (!firstRender) {
+                // Move cursor up to the start of our last render and erase down.
+                stdout.write(`\x1b[${items.length + 2}A`);
+                stdout.write('\x1b[J');
+            }
+            firstRender = false;
+            stdout.write(`${chalk.bold(question)}  ${chalk.dim('(space=toggle, a=all, enter=confirm, esc=cancel)')}\n`);
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const isCursor = i === cursor;
+                const isSelected = selected.has(item.value);
+                const box = isSelected ? chalk.green('◉') : chalk.dim('◯');
+                const arrow = isCursor ? chalk.cyan('›') : ' ';
+                const label = isCursor ? chalk.cyan(item.label) : item.label;
+                const hint = item.hint ? chalk.dim(`  — ${item.hint}`) : '';
+                stdout.write(`${arrow} ${box} ${label}${hint}\n`);
+            }
+            const ok = selected.size >= minSelected;
+            stdout.write(`${chalk.dim(ok
+                ? `${selected.size} selected · enter to confirm`
+                : `at least ${minSelected} required · ${selected.size} selected`)}\n`);
+        };
+        /**
+         * Raw-byte parser. We listen to `data` directly instead of relying on
+         * `readline.emitKeypressEvents`, which is unreliable on macOS Terminal +
+         * iTerm under raw mode (the keypress event simply never fires for some
+         * users, leaving them stuck on whatever items the prompt prefilled).
+         *
+         * Sequences we care about:
+         *   ESC [ A/B/C/D     → arrow keys
+         *   0x0D / 0x0A       → return
+         *   0x20              → space
+         *   0x03              → ctrl-c
+         *   0x1B (alone)      → escape (heuristic: solo 0x1B with no follow-up)
+         *   "k" / "j" / "a"   → vim-style move + toggle-all
+         *   "q"               → cancel
+         */
+        const handle = (data) => {
+            // An entire keystroke can arrive as one chunk on most terminals, but
+            // we guard against multi-byte chunks by walking the buffer.
+            let i = 0;
+            while (i < data.length) {
+                const b = data[i];
+                // CSI escape sequences: ESC [ X
+                if (b === 0x1b && data[i + 1] === 0x5b && data.length > i + 2) {
+                    const arrow = data[i + 2];
+                    if (arrow === 0x41)
+                        cursor = (cursor - 1 + items.length) % items.length;
+                    else if (arrow === 0x42)
+                        cursor = (cursor + 1) % items.length;
+                    else if (arrow === 0x43) {
+                        // right arrow → toggle (some users default to this)
+                        const v = items[cursor].value;
+                        if (selected.has(v))
+                            selected.delete(v);
+                        else
+                            selected.add(v);
+                    }
+                    i += 3;
+                    continue;
+                }
+                // Bare ESC = cancel.
+                if (b === 0x1b && (data.length === i + 1 || data[i + 1] === undefined)) {
+                    cleanup();
+                    resolve(null);
+                    return;
+                }
+                // Ctrl-C.
+                if (b === 0x03) {
+                    cleanup();
+                    resolve(null);
+                    return;
+                }
+                // Enter — CR or LF.
+                if (b === 0x0d || b === 0x0a) {
+                    if (selected.size < minSelected) {
+                        i += 1;
+                        continue;
+                    }
+                    cleanup();
+                    resolve([...selected]);
+                    return;
+                }
+                // Space — toggle current.
+                if (b === 0x20) {
+                    const v = items[cursor].value;
+                    if (selected.has(v))
+                        selected.delete(v);
+                    else
+                        selected.add(v);
+                    i += 1;
+                    continue;
+                }
+                // Letters: a (toggle all), j (down), k (up), q (cancel).
+                if (b === 0x61) {
+                    if (selected.size === items.length)
+                        selected.clear();
+                    else
+                        for (const it of items)
+                            selected.add(it.value);
+                    i += 1;
+                    continue;
+                }
+                if (b === 0x6a) {
+                    cursor = (cursor + 1) % items.length;
+                    i += 1;
+                    continue;
+                }
+                if (b === 0x6b) {
+                    cursor = (cursor - 1 + items.length) % items.length;
+                    i += 1;
+                    continue;
+                }
+                if (b === 0x71) {
+                    cleanup();
+                    resolve(null);
+                    return;
+                }
+                // Unknown byte — advance and ignore.
+                i += 1;
+            }
+            render();
+        };
+        dataHandler = handle;
+        stdin.on('data', handle);
+        render();
+    });
+}
+const hideCursor = '\x1b[?25l';
+const showCursor = '\x1b[?25h';
+async function fallbackPrompt(question, items, opts) {
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        stdout.write(`${question}\n`);
+        for (const i of items) {
+            stdout.write(`  - ${i.value}${i.label !== i.value ? ` (${i.label})` : ''}${i.hint ? `  — ${i.hint}` : ''}\n`);
+        }
+        const def = (opts.initial ?? []).join(',');
+        const ans = (await rl.question(`Comma-separated values${def ? ` [${def}]` : ''}: `)).trim();
+        if (!ans && opts.initial)
+            return [...opts.initial];
+        if (!ans)
+            return [];
+        const valid = new Set(items.map((i) => i.value));
+        const tokens = ans
+            .split(',')
+            .map((s) => s.trim())
+            .filter((t) => valid.has(t));
+        return tokens;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/lib/usage-cursor.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CONFIG } from './config.js';
+/**
+ * Persistent watermark for the transcript scanner. Without it every
+ * `prave usage scan` would re-walk every JSONL we've ever recorded; with
+ * it we only re-process files modified since the last successful scan.
+ *
+ * Stored at `~/.prave/usage-cursor.json` (plain text, no secrets) so it
+ * survives across CLI versions and machine reboots.
+ */
+const CURSOR_PATH = join(CONFIG.praveDir, 'usage-cursor.json');
+export async function loadCursor() {
+    try {
+        const raw = await readFile(CURSOR_PATH, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.lastScanAt) {
+            const ms = Date.parse(parsed.lastScanAt);
+            if (!Number.isNaN(ms))
+                return new Date(ms);
+        }
+    }
+    catch {
+        /* fall through to default */
+    }
+    // First run: look back 30 days. Matches the optimiser's "30+ days
+    // unused" window so the very first scan can fully populate it.
+    return new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+}
+export async function saveCursor(at = new Date()) {
+    await mkdir(dirname(CURSOR_PATH), { recursive: true });
+    const state = { lastScanAt: at.toISOString() };
+    await writeFile(CURSOR_PATH, JSON.stringify(state, null, 2), 'utf8');
+}

package/dist/lib/usage-scanner.js

@@ -0,0 +1,154 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+/**
+ * Scan every .jsonl transcript newer than `since` for Skill invocations.
+ *
+ * @param installedSlugs the slugs we recognise — anything outside this
+ *  set is ignored to avoid noise from quoted text.
+ * @param since lower bound for transcript modification time. Defaults
+ *  to 30 days ago on a fresh run; the CLI persists a watermark in
+ *  `~/.prave/usage-cursor.json` so subsequent runs only re-scan recent
+ *  transcripts.
+ */
+export async function scanTranscriptsForUsage(installedSlugs, since) {
+    if (!installedSlugs.length)
+        return [];
+    const slugSet = new Set(installedSlugs);
+    const sinceMs = since.getTime();
+    const events = [];
+    const projectDirs = await safeReaddir(PROJECTS_DIR);
+    for (const projectName of projectDirs) {
+        const projectDir = join(PROJECTS_DIR, projectName);
+        const projectStat = await safeStat(projectDir);
+        if (!projectStat?.isDirectory())
+            continue;
+        const files = await safeReaddir(projectDir);
+        for (const file of files) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const path = join(projectDir, file);
+            const fileStat = await safeStat(path);
+            if (!fileStat || fileStat.mtimeMs < sinceMs)
+                continue;
+            try {
+                const raw = await readFile(path, 'utf8');
+                const lines = raw.split('\n');
+                for (const line of lines) {
+                    if (!line)
+                        continue;
+                    extractEventsFromLine(line, slugSet, sinceMs, events);
+                }
+            }
+            catch {
+                // Skip unreadable / corrupt JSONLs silently.
+            }
+        }
+    }
+    return events;
+}
+const COMMAND_NAME_RE = /<command-name>\s*\/?([a-z0-9][a-z0-9_-]{0,80})\s*<\/command-name>/gi;
+/**
+ * Per-line extractor. The transcript is one JSON object per line, but
+ * we don't always need to parse the whole thing — slash commands land in
+ * the `<command-name>` string and a regex hit on the raw line is enough.
+ *
+ * For the canonical Skill-tool path we DO parse (only when the line
+ * actually mentions `"name":"Skill"`, so the parse cost stays bounded).
+ */
+function extractEventsFromLine(line, slugSet, sinceMs, out) {
+    // Slash-command hits — cheap and don't require JSON.parse.
+    let m;
+    COMMAND_NAME_RE.lastIndex = 0;
+    while ((m = COMMAND_NAME_RE.exec(line))) {
+        const slug = m[1]?.toLowerCase();
+        if (!slug || !slugSet.has(slug))
+            continue;
+        const ts = sniffTimestamp(line, sinceMs);
+        if (!ts)
+            continue;
+        out.push({ slug, triggered_at: ts, trigger_phrase: `/${slug}` });
+    }
+    // Skill tool invocations — only parse when the line claims to have one.
+    if (!line.includes('"name":"Skill"'))
+        return;
+    try {
+        const obj = JSON.parse(line);
+        walkForSkillToolUse(obj, slugSet, sinceMs, out);
+    }
+    catch {
+        // Malformed line — ignore.
+    }
+}
+function walkForSkillToolUse(node, slugSet, sinceMs, out) {
+    if (!node)
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walkForSkillToolUse(item, slugSet, sinceMs, out);
+        return;
+    }
+    if (typeof node !== 'object')
+        return;
+    const obj = node;
+    // Detect a tool_use block at any level.
+    const block = obj;
+    if (block.type === 'tool_use' && block.name === 'Skill' && block.input?.skill) {
+        const slug = String(block.input.skill).toLowerCase().split(':').pop() ?? '';
+        if (slug && slugSet.has(slug)) {
+            const ts = sniffTimestampFromObject(obj, sinceMs);
+            if (ts)
+                out.push({ slug, triggered_at: ts, trigger_phrase: null });
+        }
+    }
+    // Recurse into known transcript fields. We don't blindly walk every
+    // value — that would re-parse user-prompt text trees we explicitly
+    // committed to NOT inspecting.
+    for (const key of ['message', 'content', 'children', 'tool_use', 'tool_results']) {
+        const child = obj[key];
+        if (child)
+            walkForSkillToolUse(child, slugSet, sinceMs, out);
+    }
+}
+/**
+ * Best-effort timestamp recovery from a JSONL line. Claude Code stamps
+ * each line with `"timestamp":"<iso>"` at the top level. If we can't
+ * find one, we drop the event (we'd rather lose a record than mis-date
+ * one).
+ */
+function sniffTimestamp(line, sinceMs) {
+    const match = /"timestamp"\s*:\s*"([^"]+)"/.exec(line);
+    if (!match)
+        return null;
+    const ts = match[1];
+    const ms = Date.parse(ts);
+    if (Number.isNaN(ms) || ms < sinceMs)
+        return null;
+    return ts;
+}
+function sniffTimestampFromObject(obj, sinceMs) {
+    const ts = obj.timestamp;
+    if (typeof ts !== 'string')
+        return null;
+    const ms = Date.parse(ts);
+    if (Number.isNaN(ms) || ms < sinceMs)
+        return null;
+    return ts;
+}
+async function safeReaddir(path) {
+    try {
+        return await readdir(path);
+    }
+    catch {
+        return [];
+    }
+}
+async function safeStat(path) {
+    try {
+        return await stat(path);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "0.5.0",
+  "version": "1.0.1",
   "description": "Prave CLI — import, export, install, sync Claude Skills.",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "open": "^10.1.0",
     "ora": "^8.0.1",
     "undici": "^6.18.0",
-    "@prave/shared": "0.4.0"
+    "@prave/shared": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",