@prave/cli 1.4.8 → 1.4.10

package/dist/commands/install.js

@@ -89,14 +89,26 @@ export async function installCommand(slug, opts = {}) {
         process.exitCode = 1;
         return;
     }
-    // Best-effort analyze pass on the freshly written files.
+    // Best-effort analyze pass on the freshly written files. Silently
+    // catching all errors here used to hide a real failure mode: when the
+    // user's CLI token had expired, every analyze call returned 401, the
+    // install ledger filled up, but skill_metadata stayed empty — so the
+    // web dashboard rendered honest zeros and looked broken. We still
+    // don't bail on transient errors (the install itself succeeded), but
+    // we DO surface auth failures once so the user knows to re-login.
+    let authWarned = false;
     for (const s of installedSlugs) {
         const path = join(CONFIG.skillsDir, s, 'SKILL.md');
         try {
             const content = await readFile(path, 'utf8');
             await api
                 .post('/api/v1/intelligence/analyze', { content, file_path: path, agent_type: 'claude' }, true)
-                .catch(() => { });
+                .catch((err) => {
+                if (!authWarned && err instanceof ApiError && err.status === 401) {
+                    authWarned = true;
+                    log.warn('Your CLI session expired — Skill intelligence will be out of sync until you run `prave login`.');
+                }
+            });
         }
         catch {
             /* file unreadable — skip */

package/dist/commands/login.js

@@ -5,6 +5,7 @@ import { track } from '../lib/analytics.js';
 import { api, ApiError } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
 import { saveCredentials } from '../lib/credentials.js';
+import { readLocalConfig, writeLocalConfigPatch } from '../lib/local-config.js';
 import { log } from '../utils/logger.js';
 /**
  * `prave login` — device-code flow against the Prave API / Supabase session.
@@ -51,12 +52,23 @@ export async function loginCommand() {
             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.
+            // First-login onboarding only. The agent picker + hook installer
+            // used to fire on EVERY login, which was annoying for users who
+            // re-login often (CI environments, multi-machine setups, after a
+            // token expiry). Now we gate on a persisted flag in
+            // ~/.prave/config.json — once they've completed the picker once,
+            // it never auto-fires again. Manual re-run available via
+            // `prave settings agent`.
             try {
-                const { runAgentOnboarding } = await import('../lib/agent-onboarding.js');
-                await runAgentOnboarding();
+                const cfg = await readLocalConfig();
+                if (cfg.agent_onboarding_done !== true) {
+                    const { runAgentOnboarding } = await import('../lib/agent-onboarding.js');
+                    await runAgentOnboarding();
+                    await writeLocalConfigPatch({ agent_onboarding_done: true });
+                }
+                else {
+                    log.dim('Welcome back — run `prave settings agent` to change your agent setup.');
+                }
             }
             catch (onboardErr) {
                 log.dim(`Agent onboarding skipped: ${onboardErr.message}`);

package/dist/commands/settings.js

@@ -1,10 +1,9 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 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';
+import { writeLocalConfigPatch } from '../lib/local-config.js';
 import { log } from '../utils/logger.js';
 function detectOs() {
     if (process.platform === 'darwin')
@@ -13,20 +12,14 @@ function detectOs() {
         return 'windows';
     return 'linux';
 }
-async function loadLocalConfig() {
-    try {
-        const raw = await readFile(CONFIG.configPath, 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return {};
-    }
-}
 async function saveLocalConfig(settings) {
-    await mkdir(CONFIG.praveDir, { recursive: true });
-    const existing = await loadLocalConfig();
-    const next = { ...existing, agentSettings: settings };
-    await writeFile(CONFIG.configPath, JSON.stringify(next, null, 2), 'utf8');
+    // Mark onboarding done as a side effect — running `prave settings
+    // agent` manually counts as completing the picker, so the user won't
+    // get auto-prompted again on the next `prave login`.
+    await writeLocalConfigPatch({
+        agentSettings: settings,
+        agent_onboarding_done: true,
+    });
 }
 async function fetchSettings() {
     const { data } = await api.get('/api/v1/settings/agents', true);

package/dist/commands/usage.js

@@ -432,8 +432,8 @@ export async function usageStatusCommand() {
     const checkmark = (ok) => (ok ? chalk.green('✓') : chalk.red('✗'));
     log.info(chalk.bold('Usage tracking status'));
     console.log();
-    console.log(`  ${checkmark(toolHookInstalled)} PostToolUse hook (Skill tool fires): ${toolHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
-    console.log(`  ${checkmark(promptHookInstalled)} UserPromptSubmit hook (slash commands like /graphify): ${promptHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
+    console.log(`  ${checkmark(toolHookInstalled)} Skill invocation tracking: ${toolHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
+    console.log(`  ${checkmark(promptHookInstalled)} Slash-command tracking (e.g. /graphify): ${promptHookInstalled ? chalk.green('installed') : chalk.yellow('missing — `prave usage hook install`')}`);
     console.log(`  ${checkmark(apiReachable)} API reachable + auth valid: ${apiReachable ? chalk.green('yes') : chalk.red(apiMessage || 'no')}`);
     console.log(`  ${checkmark(Boolean(lastScanAt))} Transcript scanner watermark: ${lastScanAt ?? chalk.dim('never run — `prave sync` includes it')}`);
     console.log(`  ${checkmark(recent7 > 0)} Events in last 7 days: ${chalk.cyan(String(recent7))}`);
@@ -470,7 +470,7 @@ export async function usageStatusCommand() {
         console.log();
         log.warn('Telemetry may be incomplete. Suggested fixes:');
         if (!toolHookInstalled || !promptHookInstalled) {
-            log.dim('  • Run `prave usage hook install` to wire BOTH PostToolUse and UserPromptSubmit.');
+            log.dim('  • Run `prave usage hook install` to enable both Skill-fire and slash-command tracking.');
         }
         if (!apiReachable) {
             log.dim('  • Run `prave login` — your access token may have expired (silently 401-ing).');

package/dist/index.js

@@ -24,7 +24,7 @@ import { usageHookInstallCommand, usageHookUninstallCommand, usageReportCommand,
 import { whatdoesCommand } from './commands/whatdoes.js';
 import { whoamiCommand } from './commands/whoami.js';
 import { initAnalytics } from './lib/analytics.js';
-import { nudgeFirstRun } from './lib/nudge.js';
+import { captureAuthSnapshot, nudgeFirstRun } from './lib/nudge.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8'));
 initAnalytics(pkg.version);
@@ -49,7 +49,7 @@ const program = new Command()
     .addHelpText('after', '\nRun `prave <cmd> --help` for command-specific options.');
 program
     .command('login')
-    .description('Authenticate this machine via device-code (browser opens, no password is ever typed). Tokens are saved chmod-600 to ~/.prave/credentials.json and refresh automatically.')
+    .description('Sign this machine in (browser opens, no password typed). Credentials are stored securely on disk and refreshed automatically.')
     .action(loginCommand);
 program
     .command('logout')
@@ -130,17 +130,17 @@ const usage = program
     .description('Track which Skills you actually use (powers the optimiser)');
 usage
     .command('report')
-    .description('Internal: invoked by the Claude Code PostToolUse / UserPromptSubmit hook (reads stdin)')
-    .option('--source <kind>', 'hook channel that fired this report ("tool" or "prompt")', 'tool')
+    .description('Internal: invoked by the agent when a Skill fires (reads payload from stdin)')
+    .option('--source <kind>', 'event channel that fired this report', 'tool')
     .action((opts) => usageReportCommand(opts));
-const hook = usage.command('hook').description('Install/uninstall the Claude Code real-time usage hook');
+const hook = usage.command('hook').description('Enable / disable real-time Skill invocation tracking');
 hook
     .command('install')
-    .description('Add a PostToolUse hook to ~/.claude/settings.json')
+    .description('Enable real-time invocation tracking for your installed Skills')
     .action(usageHookInstallCommand);
 hook
     .command('uninstall')
-    .description('Remove the Prave-managed hook from ~/.claude/settings.json')
+    .description('Disable real-time invocation tracking')
     .action(usageHookUninstallCommand);
 program
     .command('mcp-server')
@@ -188,7 +188,7 @@ program
         '  prave optimize --remove-unused     # delete 30d-silent skills from disk',
         '',
         'Usage tracking (Pro+)',
-        '  prave usage hook install           # real-time PostToolUse hook',
+        '  prave usage hook install           # enable real-time invocation tracking',
         '  prave usage hook uninstall',
         '',
         'Settings',
@@ -204,6 +204,19 @@ program
         'Docs:   https://prave.app/docs',
     ].join('\n'));
 });
+// Capture auth state BEFORE the command runs. Critical for the
+// first-run welcome banner — if the user's very first command is
+// `prave login`, the postAction hook fires AFTER credentials are
+// saved, so a live auth check would read "signed in" and suppress
+// the welcome. The preAction snapshot freezes the pre-command state.
+program.hook('preAction', async () => {
+    try {
+        await captureAuthSnapshot();
+    }
+    catch {
+        /* never block the command on nudge bookkeeping */
+    }
+});
 // Global first-run banner. Fires once on the user's very first command
 // regardless of which one it was — catches commands that don't have a
 // per-action nudge wired in (e.g. `prave docs`, `prave conflicts`).

package/dist/lib/local-config.js

@@ -0,0 +1,44 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { CONFIG } from './config.js';
+/**
+ * Shared read / write for `~/.prave/config.json`.
+ *
+ * The same file holds three classes of state, all merged into one
+ * JSON object so callers can patch one key without clobbering the
+ * others:
+ *
+ *   • `agentSettings` — written by `prave settings`
+ *   • Nudge bookkeeping (`first_run`, `nudge_count`) — written by
+ *     the conversion-nudge module
+ *   • Onboarding flags (`agent_onboarding_done`) — written by
+ *     `prave login` so we only walk the user through the agent
+ *     picker once
+ *
+ * Previously each consumer reimplemented the same readFile / merge /
+ * writeFile dance — three copies in three files. Centralising here
+ * means a missing key in one consumer no longer wipes the keys
+ * another consumer just wrote.
+ */
+export async function readLocalConfig() {
+    try {
+        const raw = await readFile(CONFIG.configPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Merge-write: reads the current config, shallow-merges `patch`, and
+ * writes the result. Creates `~/.prave/` with restrictive mode (0700)
+ * if it doesn't exist yet.
+ */
+export async function writeLocalConfigPatch(patch) {
+    const existing = await readLocalConfig();
+    const next = { ...existing, ...patch };
+    await mkdir(CONFIG.praveDir, { recursive: true, mode: 0o700 });
+    await writeFile(CONFIG.configPath, JSON.stringify(next, null, 2), 'utf8');
+}

package/dist/lib/nudge-constants.js

@@ -47,7 +47,7 @@ export const NUDGE_DEEP = {
     bullets: [
         'AI-generated descriptions for all your Skills',
         'Conflict detection across your library',
-        '30-day usage history from PostToolUse hook',
+        '30-day Skill invocation history',
         'Cross-machine sync',
     ],
     cta: 'prave.app/signup  ·  free forever  ·  10 seconds',

package/dist/lib/nudge.js

@@ -1,9 +1,45 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import chalk from 'chalk';
-import { CONFIG } from './config.js';
 import { loadCredentials } from './credentials.js';
+import { readLocalConfig, writeLocalConfigPatch } from './local-config.js';
 import { isAlwaysShow, NUDGE_FIRST_RUN, nudgeFor, } from './nudge-constants.js';
+/**
+ * Conversion nudges for anonymous CLI users.
+ *
+ * 4,300 npm-installs, 1 signed-in account. The CLI works for anonymous
+ * users by design (lower friction = more installs) but the handoff to
+ * the dashboard was missing. These nudges fix that.
+ *
+ * Rules baked in here, not in the call sites:
+ *   • Silent for signed-in users. Always.
+ *   • Soft nudges throttled to ~1 in every 3 commands via a counter
+ *     persisted to ~/.prave/config.json (`nudge_count`).
+ *   • Strong nudges (overview/whatdoes/first-run) bypass the throttle —
+ *     they're the highest-intent moments and worth a fuller pitch.
+ *   • First-run banner shows once on the user's very first command;
+ *     `first_run: false` then locks it down forever.
+ *   • One nudge per process. Multiple commands chained in a wrapper
+ *     script don't spam.
+ *   • Skipped when stdout isn't a TTY (piped output, CI) and when
+ *     PRAVE_QUIET=1 / PRAVE_TELEMETRY=0.
+ */
 let alreadyNudged = false;
+/**
+ * Auth snapshot captured at command START, used at command END.
+ *
+ * Without this, `prave login` (very common first-ever command) traps
+ * us: the postAction hook fires AFTER credentials are saved, so the
+ * auth check inside canNudge() reads "signed in" → first-run banner
+ * suppressed → `first_run: false` written → user never sees the
+ * welcome message on any future command. The snapshot freezes the
+ * pre-command auth state so the first-run welcome still fires for a
+ * user whose very first command is the login itself.
+ */
+let wasAnonymousAtStart = null;
+export async function captureAuthSnapshot() {
+    if (wasAnonymousAtStart !== null)
+        return;
+    wasAnonymousAtStart = !(await isAuthenticated());
+}
 /* --------------------------------------------------------------------- */
 /*  Auth + state helpers                                                  */
 /* --------------------------------------------------------------------- */
@@ -18,24 +54,6 @@ export async function isAuthenticated() {
     }
     return true;
 }
-async function readConfig() {
-    try {
-        const raw = await readFile(CONFIG.configPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (parsed && typeof parsed === 'object')
-            return parsed;
-        return {};
-    }
-    catch {
-        return {};
-    }
-}
-async function writeConfigPatch(patch) {
-    const existing = await readConfig();
-    const next = { ...existing, ...patch };
-    await mkdir(CONFIG.praveDir, { recursive: true, mode: 0o700 });
-    await writeFile(CONFIG.configPath, JSON.stringify(next, null, 2), 'utf8');
-}
 /**
  * Counter-based throttle for soft nudges. Reads the current count,
  * increments, persists, and returns true when (count % 3 === 0) — so
@@ -43,10 +61,10 @@ async function writeConfigPatch(patch) {
  * we'd rather skip than be loud on the user's first real command.
  */
 export async function shouldShowNudge() {
-    const cfg = await readConfig();
+    const cfg = await readLocalConfig();
     const current = typeof cfg.nudge_count === 'number' ? cfg.nudge_count : 0;
     const next = current + 1;
-    await writeConfigPatch({ nudge_count: next });
+    await writeLocalConfigPatch({ nudge_count: next });
     return next % 3 === 0;
 }
 /* --------------------------------------------------------------------- */
@@ -101,13 +119,30 @@ async function canNudge() {
  * (no nudge_count yet AND first_run not yet set to false). Always strong,
  * always bypasses the throttle.
  *
+ * Uses the START-of-command auth snapshot, not live state. That way the
+ * banner still appears when the user's very first command is `prave
+ * login` itself — login completes, the postAction hook fires, and we
+ * still know they came in anonymous so the welcome is appropriate.
+ *
  * Returns true when shown — call sites use this to skip the regular nudge
  * on the same turn so we don't double-print.
  */
 export async function nudgeFirstRun() {
-    if (!(await canNudge()))
+    if (alreadyNudged)
+        return false;
+    if (!process.stdout.isTTY)
+        return false;
+    if (process.env.PRAVE_QUIET === '1')
+        return false;
+    if (process.env.PRAVE_TELEMETRY === '0')
+        return false;
+    // Honour the auth-at-start snapshot. If the user opened the session
+    // already authenticated, the welcome conversion banner doesn't fit —
+    // they don't need a "create free account" pitch.
+    const startedAnon = wasAnonymousAtStart ?? !(await isAuthenticated());
+    if (!startedAnon)
         return false;
-    const cfg = await readConfig();
+    const cfg = await readLocalConfig();
     // first_run defaults to "yes, show it" unless we've already flipped
     // the flag. A missing config file → first run.
     const alreadyShown = cfg.first_run === false;
@@ -115,7 +150,7 @@ export async function nudgeFirstRun() {
         return false;
     alreadyNudged = true;
     showNudge(NUDGE_FIRST_RUN);
-    await writeConfigPatch({ first_run: false });
+    await writeLocalConfigPatch({ first_run: false });
     return true;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.4.8",
+  "version": "1.4.10",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -54,7 +54,7 @@
     "ora": "^8.0.1",
     "tar": "^7.4.3",
     "undici": "^6.18.0",
-    "@prave/shared": "1.4.8"
+    "@prave/shared": "1.4.10"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",