@prave/cli 1.3.0 → 1.4.1

package/dist/commands/docs.js

@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+import open from 'open';
+import { CONFIG } from '../lib/config.js';
+/**
+ * `prave docs [slug]` — open the docs in the user's browser.
+ *
+ * No `slug` → opens https://prave.app/docs
+ * Slug given → opens https://prave.app/docs/<slug>
+ *
+ * No auth needed — the docs are public. The command exists purely so
+ * users don't have to alt-tab to a browser, type a URL, and hunt for
+ * the right section. From the terminal:
+ *
+ *   prave docs              # docs home
+ *   prave docs cli/run      # the Runs CLI reference
+ *   prave docs web/runs     # the Runs dashboard guide
+ *   prave docs pricing      # the plans page
+ */
+export async function docsCommand(slug) {
+    const cleaned = (slug ?? '').replace(/^\/+|\/+$/g, '').trim();
+    // CONFIG.webUrl points at the SPA host (https://prave.app in prod,
+    // http://localhost:5173 in dev). Docs always live under /docs.
+    const base = CONFIG.webUrl?.replace(/\/$/, '') ?? 'https://prave.app';
+    const url = cleaned ? `${base}/docs/${cleaned}` : `${base}/docs`;
+    console.log(`${chalk.dim('Opening')} ${chalk.cyan(url)}`);
+    try {
+        await open(url);
+    }
+    catch {
+        console.log(chalk.dim('(your browser did not open — copy the URL above)'));
+    }
+}

package/dist/commands/list.js

@@ -5,6 +5,7 @@ import { tokenTier } from '@prave/shared';
 import { track } from '../lib/analytics.js';
 import { api } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
+import { nudgeIfAnonymous } from '../lib/nudge.js';
 import { log } from '../utils/logger.js';
 const TIER_EMOJI = {
     lean: '🟢',
@@ -68,6 +69,7 @@ export async function listCommand(opts = {}) {
             console.log(`  ${chalk.cyan('•')} ${name}`);
         }
         log.dim(`\n${localSlugs.length} local skill${localSlugs.length === 1 ? '' : 's'} in ${CONFIG.skillsDir}`);
+        await nudgeIfAnonymous('list');
         return;
     }
     // Enriched path — pull intelligence and merge by slug (best-effort).

package/dist/commands/run.js

@@ -0,0 +1,301 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { resolve, relative, basename, sep } from 'node:path';
+import { Buffer } from 'node:buffer';
+import chalk from 'chalk';
+import open from 'open';
+import ora from 'ora';
+import * as tar from 'tar';
+import { request } from 'undici';
+import { isLikelyTextPath, scanForSecrets, } from '@prave/shared';
+import { api, ApiError } from '../lib/api.js';
+import { CONFIG } from '../lib/config.js';
+import { loadCredentials, requireAuth } from '../lib/credentials.js';
+import { log } from '../utils/logger.js';
+/**
+ * `prave run` — scheduled server-side skill executions on Prave's
+ * infrastructure.
+ *
+ *   prave run deploy [path]       # bundle dir → upload → open wizard
+ *   prave run list                # list my deployed runs
+ *   prave run logs <slug>         # tail the most recent execution logs
+ *
+ * `deploy` is the headline action — the rest just expose the same data
+ * the dashboard already shows. The wizard handles schedule + agent
+ * selection in the browser because picking from an agent dropdown
+ * filtered to "which API keys do I have" is way clearer in a UI than
+ * an interactive prompt.
+ */
+// Sane-default ignore list for `tar.create` — none of these belong in
+// a deployable bundle and dragging them up adds noise to the scan +
+// bloats storage.
+const TAR_IGNORE = new Set([
+    '.git',
+    '.github',
+    '.next',
+    '.turbo',
+    '.svelte-kit',
+    '.cache',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.venv',
+    'venv',
+    '__pycache__',
+    '.DS_Store',
+]);
+const MAX_BUNDLE_BYTES = 20 * 1024 * 1024; // matches API + Supabase Storage cap
+const MAX_FILES = 200;
+export async function runDeployCommand(pathArg) {
+    const root = resolve(pathArg ?? process.cwd());
+    const rootStat = await stat(root).catch(() => null);
+    if (!rootStat?.isDirectory()) {
+        log.error(`Not a directory: ${root}`);
+        process.exit(1);
+    }
+    // Sanity check — the dir should *look* like a skill project. We don't
+    // hard-reject; we just warn if there's no SKILL.md anywhere.
+    const skillMd = await findSkillMd(root);
+    if (!skillMd) {
+        log.warn('No SKILL.md found in this directory. Deploys still work without it, but the runner will not have skill-shaped context for the agent.');
+    }
+    const creds0 = await requireAuth('prave run');
+    if (!creds0)
+        return;
+    // 1. Local secret-scan BEFORE we ship anything. Cheap defence in
+    // depth — even though the API scans again, surfacing the finding
+    // pre-upload saves the user a round-trip and avoids briefly storing
+    // a secret-bearing tarball in our bucket.
+    const localFindings = await preflightScan(root);
+    if (localFindings.length > 0) {
+        log.error('Bundle contains files that look like secrets:');
+        for (const f of localFindings.slice(0, 10)) {
+            console.error(`  ${chalk.red('•')} ${f.rule}  ${chalk.dim(f.path)}${f.line ? `:${f.line}` : ''}`);
+        }
+        console.error(chalk.dim('\nRemove these files (or scrub the values) and re-run.\n' +
+            'For env vars, ship a .env.example template instead — Prave\n' +
+            'will prompt you for the real values during the wizard.'));
+        process.exit(1);
+    }
+    // 2. Mint the deploy session
+    const initSpinner = ora('Opening deploy session…').start();
+    let session;
+    try {
+        const { data } = await api.post('/api/v1/deploy/init', {}, true);
+        session = data.session;
+        initSpinner.succeed('Session opened');
+    }
+    catch (err) {
+        initSpinner.fail(`Could not open deploy session: ${err.message}`);
+        process.exit(1);
+    }
+    // 3. Pack the directory into a gzipped tar in memory. tar.create's
+    // `cwd` option is critical — paths inside the archive must be
+    // RELATIVE to the project root, not absolute.
+    const packSpinner = ora('Bundling project…').start();
+    let tarball;
+    try {
+        tarball = await packDirectory(root);
+        packSpinner.succeed(`Bundled ${formatBytes(tarball.length)}`);
+    }
+    catch (err) {
+        packSpinner.fail(`Bundle failed: ${err.message}`);
+        process.exit(1);
+    }
+    if (tarball.length > MAX_BUNDLE_BYTES) {
+        log.error(`Bundle is ${formatBytes(tarball.length)}, cap is ${formatBytes(MAX_BUNDLE_BYTES)}. ` +
+            'Add large files to .gitignore-style noise (or place them in node_modules / .git which we already skip).');
+        process.exit(1);
+    }
+    // 4. Stream the tarball to /deploy/upload. We use undici directly
+    // because api.ts only does JSON.
+    const uploadSpinner = ora('Uploading to Prave…').start();
+    const creds = await loadCredentials();
+    if (!creds) {
+        uploadSpinner.fail('Credentials expired mid-flight — please re-login.');
+        process.exit(1);
+    }
+    const uploadUrl = `${CONFIG.apiUrl}/api/v1/deploy/upload?session=${encodeURIComponent(session.session_id)}`;
+    try {
+        const { statusCode, body } = await request(uploadUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/gzip',
+                Authorization: `Bearer ${creds.access_token}`,
+            },
+            body: tarball,
+        });
+        const text = await body.text();
+        if (statusCode >= 400) {
+            const parsed = safeJson(text);
+            const msg = parsed?.error ?? `HTTP ${statusCode}`;
+            uploadSpinner.fail(`Upload rejected: ${msg}`);
+            process.exit(1);
+        }
+        uploadSpinner.succeed('Upload complete');
+    }
+    catch (err) {
+        uploadSpinner.fail(`Upload failed: ${err.message}`);
+        process.exit(1);
+    }
+    // 5. Open the browser at the wizard
+    console.log();
+    console.log(chalk.bold('Finish in the browser:'));
+    console.log(chalk.cyan('  ' + session.wizard_url));
+    try {
+        await open(session.wizard_url);
+    }
+    catch {
+        /* user can copy the URL manually */
+    }
+}
+export async function runListCommand() {
+    if (!(await requireAuth('prave run list')))
+        return;
+    const spinner = ora('Fetching runs…').start();
+    try {
+        const { data } = await api.get('/api/v1/runs', true);
+        spinner.stop();
+        if (!data.runs.length) {
+            console.log(chalk.dim('No runs yet. `prave run deploy` to schedule your first one.'));
+            return;
+        }
+        for (const r of data.runs) {
+            const nextRun = r.next_run_at
+                ? new Date(r.next_run_at).toLocaleString()
+                : chalk.dim('paused');
+            const status = r.status === 'active'
+                ? chalk.green('active')
+                : r.status === 'paused'
+                    ? chalk.yellow('paused')
+                    : chalk.red(r.status);
+            console.log(`  ${chalk.bold(r.name)}  ${chalk.dim(r.slug)}\n` +
+                `    ${chalk.dim(`agent=${r.agent}  schedule=${r.schedule_kind}  status=${status}  next=${nextRun}`)}`);
+        }
+    }
+    catch (err) {
+        spinner.fail(err.message);
+        process.exit(err instanceof ApiError ? 1 : 1);
+    }
+}
+export async function runLogsCommand(slug) {
+    if (!(await requireAuth('prave run logs')))
+        return;
+    const spinner = ora(`Fetching logs for ${slug}…`).start();
+    try {
+        const { data } = await api.get(`/api/v1/runs/${encodeURIComponent(slug)}/executions?limit=10`, true);
+        spinner.stop();
+        if (!data.executions.length) {
+            console.log(chalk.dim('No executions yet. The first one will appear after the next scheduled fire.'));
+            return;
+        }
+        const latest = data.executions[0];
+        const status = latest.status === 'success'
+            ? chalk.green(latest.status)
+            : latest.status === 'running'
+                ? chalk.cyan(latest.status)
+                : chalk.red(latest.status);
+        console.log(`${chalk.bold(slug)}  ${chalk.dim(latest.started_at)}  ${status}` +
+            (latest.duration_ms !== null ? chalk.dim(`  (${latest.duration_ms}ms)`) : ''));
+        console.log();
+        console.log(latest.log_text ?? chalk.dim('(no log captured)'));
+        if (latest.error_message) {
+            console.log();
+            console.log(chalk.red('Error: ') + latest.error_message);
+        }
+    }
+    catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+}
+// ── helpers ──────────────────────────────────────────────────────────
+async function findSkillMd(root) {
+    // Top-level only — most skill projects ship SKILL.md at the root.
+    // Deeper search would be wasted work for the warning we'd print.
+    try {
+        const entries = await readdir(root);
+        return entries.find((n) => n.toLowerCase() === 'skill.md') ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function preflightScan(root) {
+    const inputs = [];
+    let files = 0;
+    let bytes = 0;
+    const visit = async (dir) => {
+        if (files >= MAX_FILES)
+            return;
+        if (bytes >= MAX_BUNDLE_BYTES)
+            return;
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (TAR_IGNORE.has(entry.name))
+                continue;
+            if (entry.name.startsWith('._'))
+                continue;
+            const abs = `${dir}${sep}${entry.name}`;
+            if (entry.isDirectory()) {
+                await visit(abs);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            files++;
+            const rel = relative(root, abs).split(sep).join('/');
+            if (!isLikelyTextPath(rel)) {
+                inputs.push({ path: rel });
+                continue;
+            }
+            try {
+                const content = await readFile(abs, 'utf8');
+                bytes += content.length;
+                inputs.push({ path: rel, content });
+            }
+            catch {
+                inputs.push({ path: rel });
+            }
+        }
+    };
+    await visit(root);
+    return scanForSecrets(inputs).findings;
+}
+async function packDirectory(root) {
+    // Top-level entries only — tar.create resolves them against `cwd`.
+    const entries = (await readdir(root)).filter((n) => !TAR_IGNORE.has(n));
+    if (entries.length === 0) {
+        throw new Error('Project directory is empty.');
+    }
+    const stream = tar.create({
+        gzip: true,
+        cwd: root,
+        portable: true,
+        // Prefix all paths with the project's basename so the runner
+        // gets a `<project>/SKILL.md` shape, not a flat dump at the
+        // archive root.
+        prefix: basename(root),
+        filter: (_path) => true,
+    }, entries);
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n}B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)}KB`;
+    return `${(n / 1024 / 1024).toFixed(2)}MB`;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/search.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { track } from '../lib/analytics.js';
 import { api } from '../lib/api.js';
+import { nudgeIfAnonymous } from '../lib/nudge.js';
 import { log } from '../utils/logger.js';
 const SLUG_COL = 32;
 function formatInstalls(n) {
@@ -41,4 +42,5 @@ export async function searchCommand(query) {
     if (skills.length > 0) {
         console.log(chalk.dim('  → prave install <slug>'));
     }
+    await nudgeIfAnonymous('search');
 }

package/dist/commands/uninstall.js

@@ -2,15 +2,23 @@ import { rm } from 'node:fs/promises';
 import { join, resolve, sep } from 'node:path';
 import ora from 'ora';
 import { track } from '../lib/analytics.js';
+import { api, ApiError } from '../lib/api.js';
 import { CONFIG } from '../lib/config.js';
+import { loadCredentials } from '../lib/credentials.js';
 import { assertSlug, InvalidSlugError } from '../lib/slug.js';
 /**
- * `prave uninstall <slug>` — removes ~/.claude/skills/<slug> recursively.
- * No remote call: uninstalls are local-only; the install record stays
- * for analytics + history.
+ * `prave uninstall <slug>` — removes ~/.claude/skills/<slug> AND tells
+ * the server to drop the corresponding install record so the
+ * dashboard counter goes down.
  *
- * Slug is validated against [a-z0-9][a-z0-9-]{0,63} before any path math
- * so a hostile arg like `../../etc` cannot escape the skills directory.
+ * The remote DELETE is best-effort: a network failure or "not logged
+ * in" state still lets the local rm succeed (so the user isn't stuck
+ * with dead files when offline). The mismatch then heals on the next
+ * `prave sync` or manual dashboard cleanup.
+ *
+ * Slug is validated against [a-z0-9][a-z0-9-]{0,63} before any path
+ * math so a hostile arg like `../../etc` cannot escape the skills
+ * directory.
  */
 export async function uninstallCommand(slug) {
     track('cli_uninstall', { slug });
@@ -37,10 +45,33 @@ export async function uninstallCommand(slug) {
     const spinner = ora(`Removing ${slug}…`).start();
     try {
         await rm(dir, { recursive: true, force: true });
-        spinner.succeed(`Removed ${dir}`);
     }
     catch (err) {
-        spinner.fail(`Couldn’t remove ${slug}: ${err.message}`);
+        spinner.fail(`Couldn't remove ${slug}: ${err.message}`);
         process.exitCode = 1;
+        return;
+    }
+    // Best-effort server-side ledger sweep. We only attempt it when the
+    // user is logged in — anonymous CLI usage (running before
+    // `prave login`) still does the local rm and exits cleanly.
+    const creds = await loadCredentials();
+    if (creds) {
+        try {
+            await api.del(`/api/v1/skills/${encodeURIComponent(slug)}/install`, true);
+            spinner.succeed(`Removed ${slug} (local + server install record)`);
+        }
+        catch (err) {
+            // 404 = install record already absent (matches our idempotent
+            // server behaviour). Anything else is a soft warning.
+            if (err instanceof ApiError && err.status === 404) {
+                spinner.succeed(`Removed ${slug} (local; server had no install record)`);
+            }
+            else {
+                spinner.warn(`Removed ${slug} locally — server ledger update failed (${err.message}). Run \`prave sync\` later to reconcile.`);
+            }
+        }
+    }
+    else {
+        spinner.succeed(`Removed ${slug} (local only — not signed in)`);
     }
 }

package/dist/commands/whatdoes.js

@@ -3,6 +3,7 @@ import ora from 'ora';
 import { tokenTier } from '@prave/shared';
 import { track } from '../lib/analytics.js';
 import { api, ApiError } from '../lib/api.js';
+import { nudgeIfAnonymous } from '../lib/nudge.js';
 import { log } from '../utils/logger.js';
 const TIER_BADGE = {
     lean: chalk.green('🟢 Lean'),
@@ -71,6 +72,7 @@ export async function whatdoesCommand(skillName) {
         console.log(`🔗 Requires:      ${requires}`);
         console.log(`${data.conflicts.length > 0 ? chalk.yellow('⚠️ ') : '⚠️ '}Conflicts:     ${conflicts}`);
         console.log(chalk.dim(RULE));
+        await nudgeIfAnonymous('whatdoes');
     }
     catch (err) {
         spinner.stop();

package/dist/index.js

@@ -6,6 +6,7 @@ import { Command } from 'commander';
 import { conflictsCommand } from './commands/conflicts.js';
 import { deployCommand } from './commands/deploy.js';
 import { diffCommand } from './commands/diff.js';
+import { docsCommand } from './commands/docs.js';
 import { exportCommand } from './commands/export.js';
 import { importCommand } from './commands/import.js';
 import { installCommand } from './commands/install.js';
@@ -16,6 +17,7 @@ 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 { runDeployCommand, runListCommand, runLogsCommand, } from './commands/run.js';
 import { searchCommand } from './commands/search.js';
 import { settingsCommand } from './commands/settings.js';
 import { syncCommand } from './commands/sync.js';
@@ -167,6 +169,26 @@ 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('docs [slug]')
+    .description('Open the docs in your browser. Bare `prave docs` lands on the home page; `prave docs cli/run` or `prave docs web/runs` jumps straight to a section.')
+    .action((slug) => docsCommand(slug));
+// ─── prave run — scheduled server-side executions (Runs) ──────────
+const run = program
+    .command('run')
+    .description('Schedule a skill to fire on a cron, executed by your chosen AI agent on Prave\'s sandbox. Bring the whole project — SKILL.md, scripts, .env.');
+run
+    .command('deploy [path]')
+    .description('Bundle the current directory (or `path`), upload it to Prave, and open the browser wizard to pick the schedule + agent.')
+    .action((path) => runDeployCommand(path));
+run
+    .command('list')
+    .description('List your scheduled runs with next-fire time + last status.')
+    .action(runListCommand);
+run
+    .command('logs <slug>')
+    .description('Print the latest execution log for a scheduled run.')
+    .action(runLogsCommand);
 program
     .command('mcp install')
     .alias('mcp-install')
@@ -215,6 +237,15 @@ program
         'Settings',
         '  prave settings                     # configure agents + paths',
         '',
+        'Runs (scheduled cron on Prave)',
+        '  prave run deploy                   # bundle cwd, upload, open wizard',
+        '  prave run list                     # your scheduled runs',
+        '  prave run logs <slug>              # tail latest execution log',
+        '',
+        'Docs',
+        '  prave docs                         # open the docs in your browser',
+        '  prave docs <slug>                  # jump to a section, e.g. cli/run',
+        '',
         'Telemetry',
         '  PRAVE_TELEMETRY=0                  # opt out of CLI usage analytics',
         '',

package/dist/lib/nudge.js

@@ -0,0 +1,61 @@
+import chalk from 'chalk';
+import { loadCredentials } from './credentials.js';
+let alreadyNudged = false;
+export async function nudgeIfAnonymous(context = 'generic') {
+    if (alreadyNudged)
+        return;
+    if (process.env.PRAVE_QUIET === '1')
+        return;
+    if (process.env.PRAVE_TELEMETRY === '0')
+        return; // user opted out of analytics
+    // CI / non-interactive shells are unlikely to act on a nudge — and
+    // the noise breaks pipe-parsing scripts.
+    if (!process.stdout.isTTY)
+        return;
+    const creds = await loadCredentials();
+    if (creds)
+        return; // logged-in → no nudge
+    alreadyNudged = true;
+    const cta = chalk.cyan('prave login');
+    const url = chalk.dim('— takes 10 seconds, free forever');
+    const message = (() => {
+        switch (context) {
+            case 'search':
+                return `${chalk.dim('Save these to your library, get token costs + conflicts.')}\n${chalk.dim('→')} ${cta} ${url}`;
+            case 'whatdoes':
+                return `${chalk.dim('Want the full audit — triggers, conflicts, token cost?')}\n${chalk.dim('→')} ${cta} ${url}`;
+            case 'list':
+                return `${chalk.dim('Sign in to see AI descriptions, conflicts and token cost.')}\n${chalk.dim('→')} ${cta} ${url}`;
+            case 'overview':
+                return `${chalk.dim('Track this over time on prave.app.')}\n${chalk.dim('→')} ${cta} ${url}`;
+            case 'generic':
+            default:
+                return `${chalk.dim('Get the full Skill Intelligence on prave.app.')}\n${chalk.dim('→')} ${cta} ${url}`;
+        }
+    })();
+    // One blank line so the nudge isn't glued to the command's main
+    // output. Two `console.log` calls so the chalk styles survive the
+    // pipeline cleanly.
+    console.log();
+    console.log(message);
+}
+/**
+ * Post-install banner used by package.json's `postinstall` script.
+ * Runs once after `npm i -g @prave/cli`. Stays short — npm's install
+ * log is already crowded.
+ */
+export function printPostInstallBanner() {
+    if (process.env.CI)
+        return;
+    if (process.env.PRAVE_QUIET === '1')
+        return;
+    console.log();
+    console.log(chalk.bold(`  Prave CLI installed.`));
+    console.log();
+    console.log(`  ${chalk.cyan('prave login')}        ${chalk.dim('— create your free account (browser)')}`);
+    console.log(`  ${chalk.cyan('prave search <q>')}   ${chalk.dim('— find any Claude Skill')}`);
+    console.log(`  ${chalk.cyan('prave docs')}         ${chalk.dim('— open the docs')}`);
+    console.log();
+    console.log(chalk.dim('  Docs: https://prave.app/docs · Issues: github.com/eppstudio/prave'));
+    console.log();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prave/cli",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Prave CLI — discover, install, version, test, and ship Claude Skills. The developer platform for the complete Skill lifecycle.",
   "type": "module",
   "keywords": [
@@ -43,7 +43,8 @@
   },
   "main": "dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "scripts/postinstall.mjs"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -51,11 +52,13 @@
     "commander": "^12.1.0",
     "open": "^10.1.0",
     "ora": "^8.0.1",
+    "tar": "^7.4.3",
     "undici": "^6.18.0",
-    "@prave/shared": "1.3.0"
+    "@prave/shared": "1.4.1"
   },
   "devDependencies": {
     "@types/node": "^20.12.7",
+    "@types/tar": "^6.1.13",
     "tsx": "^4.11.0",
     "typescript": "^5.4.5"
   },
@@ -67,6 +70,7 @@
     "cli": "tsx src/index.ts",
     "build": "tsc -p tsconfig.json && node scripts/inject-config.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit"
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "postinstall": "node scripts/postinstall.mjs"
   }
 }

package/scripts/postinstall.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * npm postinstall hook. Runs once after `npm i -g @prave/cli` (and on
+ * upgrades). Prints a small "you're set — what now?" banner so the
+ * thousands of CLI installs we're seeing actually find the dashboard
+ * + the docs.
+ *
+ * Silent in CI / non-interactive shells / when PRAVE_QUIET=1 is set.
+ * Also silent on dependent installs — npm sets `npm_config_global` to
+ * 'false' or unset when we're being installed as a dependency, and
+ * the banner is only useful for the global-install user.
+ */
+if (process.env.CI) process.exit(0)
+if (process.env.PRAVE_QUIET === '1') process.exit(0)
+// `npm_config_global` is `'true'` only for `npm i -g`. Skip for local
+// dependency installs (e.g. when our worker container builds).
+if (process.env.npm_config_global !== 'true') process.exit(0)
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`
+
+console.log()
+console.log(`  ${bold('Prave CLI installed.')}`)
+console.log()
+console.log(`  ${cyan('prave login')}        ${dim('— create your free account (browser)')}`)
+console.log(`  ${cyan('prave search <q>')}   ${dim('— find any Claude Skill')}`)
+console.log(`  ${cyan('prave docs')}         ${dim('— open the docs')}`)
+console.log()
+console.log(dim('  Docs: https://prave.app/docs · Issues: github.com/eppstudio/prave'))
+console.log()