@prave/cli 1.1.1 → 1.2.0

package/README.md

@@ -0,0 +1,179 @@
+<div align="center">
+
+# `@prave/cli`
+
+**The Prave CLI — discover, install, author, version, test, and ship Skills to any AI agent from your terminal.**
+
+[![npm version](https://img.shields.io/npm/v/@prave/cli?color=06B6D4&label=npm&style=flat-square)](https://www.npmjs.com/package/@prave/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@prave/cli?color=06B6D4&label=downloads&style=flat-square)](https://www.npmjs.com/package/@prave/cli)
+[![node](https://img.shields.io/node/v/@prave/cli?color=06B6D4&label=node&style=flat-square)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@prave/cli?color=06B6D4&style=flat-square)](https://github.com/eppstudio/prave/blob/main/LICENSE)
+[![docs](https://img.shields.io/badge/docs-prave.app-06B6D4?style=flat-square)](https://prave.app/docs)
+[![status](https://img.shields.io/badge/status-status.prave.app-22c55e?style=flat-square)](https://status.prave.app)
+
+[**Website**](https://prave.app) · [**Documentation**](https://prave.app/docs) · [**CLI Cheat Sheet**](https://prave.app/docs/cli/cheat-sheet) · [**Status**](https://status.prave.app)
+
+</div>
+
+---
+
+## What is Prave?
+
+[Prave](https://prave.app) is the developer platform for the **complete lifecycle of AI agent Skills** — a registry to discover them, an editor to write them, an intelligence layer to keep your library lean, a tester to verify them, and this CLI to wire it all into your agent's skills directory on every machine you work from.
+
+The Skill format originated with [Claude Code](https://docs.claude.com/en/docs/claude-code/skills) (a folder with a `SKILL.md` and frontmatter). The same format works **out of the box** with any agent that auto-loads instruction files from a folder — Prave is agent-aware: each Skill is tagged with which agents understand it, and `prave deploy` mirrors a Skill across **Claude Code · OpenAI Codex · Cursor · Gemini CLI · Cline · Amp**, with more added as the ecosystem grows.
+
+This package is the **command-line surface**. The web app, the public registry, billing, and the API live at [prave.app](https://prave.app).
+
+## Install
+
+```bash
+npm install -g @prave/cli
+# or
+pnpm add -g @prave/cli
+# or
+yarn global add @prave/cli
+```
+
+Requires **Node.js 18+**.
+
+## Quick start
+
+```bash
+prave login              # device-code auth in your browser
+prave search "review pull requests"
+prave install pr-reviewer    # writes into your agent's skills folder
+prave deploy pr-reviewer     # mirror it to every agent you use
+prave list                   # what's now installed locally
+```
+
+That's enough to be useful. The full vocabulary is below.
+
+> **Multi-agent by default.** `prave install` writes to your primary agent's skills folder (Claude Code by default; configurable via `prave settings`). `prave deploy` then mirrors the Skill to every other agent you've enabled — Cursor, Codex, Gemini, Cline, Amp — converting between their respective rule-file formats automatically.
+
+### `prave sync` in practice
+
+`prave sync` shows you when you last ran it and confirms before doing any work — under 30 minutes ago and the default flips to `n`. Skills then install in parallel (concurrency 4) with a per-Skill progress counter:
+
+```bash
+$ prave sync
+Last sync: 2 hours ago — sync again? [Y/n] y
+Syncing 12 Skills — this takes about 15 seconds.
+✓ 12 / 12 — pr-reviewer
+Synced 12 · failed 0
+```
+
+The `last_sync_at` watermark persists at `~/.prave/state.json`. Pass `--yes` to skip the prompt in CI scripts.
+
+## Commands
+
+### Auth & account
+
+| Command        | What it does                                                                      |
+| -------------- | --------------------------------------------------------------------------------- |
+| `prave login`  | Browser device-code auth. Tokens stored chmod-600 at `~/.prave/credentials.json`. |
+| `prave logout` | Forget local credentials.                                                         |
+| `prave whoami` | Show signed-in user, plan, and credentials path.                                  |
+
+### Discover & install
+
+| Command                                                  | What it does                                  |
+| -------------------------------------------------------- | --------------------------------------------- |
+| `prave search <query>`                                   | Search the public Skill registry.             |
+| `prave install <slug>` `[--no-deps]`                     | Install into your agent's skills folder.      |
+| `prave uninstall <slug>`                                 | Remove a locally installed Skill.             |
+| `prave list` `[--remote] [--verbose]`                    | What's installed locally (or remote).         |
+| `prave export <slug>` `-o file.md`                       | Dump a Skill's `SKILL.md` without installing. |
+
+### Authoring & sync
+
+| Command                                         | What it does                                                                           |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `prave import` `[--upload --public\|--private]` | Scan your agent's skills folder, optionally publish to Prave.                          |
+| `prave deploy <slug>` `[--agent <name>]`        | Mirror a Skill across enabled agents (Claude / Cursor / Codex / Gemini / Cline / Amp). |
+| `prave sync`                                    | Pull updates for every locally installed Skill.                                        |
+| `prave update [<slug>]` `[--dry-run]`           | Diff installed Skills against the registry, pull what's outdated.                      |
+| `prave diff <slug>`                             | Local vs registry side-by-side diff.                                                   |
+
+### Intelligence
+
+| Command                              | What it does                                          |
+| ------------------------------------ | ----------------------------------------------------- |
+| `prave overview` `[--json]`          | Summary of token cost, conflicts, and library health. |
+| `prave whatdoes <slug>`              | Triggers, tokens, conflicts for a Skill.              |
+| `prave conflicts`                    | Cross-Skill collision check.                          |
+| `prave optimize` `[--remove-unused]` | Recommendations: heavy / underused / mergeable.       |
+
+### Usage tracking _(Pro+)_
+
+| Command                           | What it does                                              |
+| --------------------------------- | --------------------------------------------------------- |
+| `prave usage hook install`        | Real-time invocation tracking for agents that support it. |
+| `prave usage hook uninstall`      | Remove the real-time hook.                                |
+| `prave usage scan` `[--since 7d]` | Transcript scanner — backfill recent invocations.         |
+| `prave usage status`              | Hook health, recent counts, and top Skills.               |
+
+> **Coverage today:** Real-time tracking lives natively on Claude Code via its plugin contract. For every other agent, the **transcript scanner** auto-runs at the tail of `prave sync` and reads the agent's local conversation history to extract Skill invocations — so Intelligence and the optimiser stay accurate everywhere. Real-time hooks for Cursor / Codex / Gemini / Cline / Amp ship as soon as those agents expose an equivalent contract.
+
+### Settings
+
+| Command          | What it does                                                |
+| ---------------- | ----------------------------------------------------------- |
+| `prave settings` | Configure agents, providers, and credits from the terminal. |
+| `prave cheat`    | Print the full one-page command reference.                  |
+
+## Auto-update
+
+`prave login` retries on `401` once with a fresh access token swapped via your stored `refresh_token`. You won't see "expired token" mid-install — re-authenticating is only required when the **refresh token itself** is rejected (you signed out everywhere or were idle for 30+ days).
+
+## Privacy & telemetry
+
+The CLI sends a **fire-and-forget event per command** (e.g. `cli_install`, `cli_sync`, `cli_login_started`) to PostHog EU Cloud so we can see which commands matter to users. Events carry your Supabase user-id once you've logged in (or a stable per-machine UUID at `~/.prave/anon-id` if you haven't), plus OS family, OS release, Node.js version, and the CLI version — no command arguments, no Skill content, no file paths.
+
+**Opt out** by setting:
+
+```bash
+PRAVE_TELEMETRY=0
+```
+
+(also accepts `false`, `off`, `no`). When set, no event ever leaves your machine.
+
+Full data-protection details: [Privacy Policy](https://prave.app/legal/privacy).
+
+## Where things live
+
+The exact Skill location depends on the agent — `prave settings` lets you reconfigure per-agent paths, and `prave list` always reflects what is actually on disk. The defaults:
+
+```
+Claude Code   ~/.claude/skills/<slug>/SKILL.md
+Cursor        ~/.cursor/rules/<slug>.mdc
+Codex         ~/.codex/skills/<slug>/SKILL.md
+Gemini CLI    ~/.gemini/skills/<slug>/SKILL.md
+Cline         ~/.cline/rules/<slug>.md
+Amp           ~/.amp/skills/<slug>/SKILL.md
+```
+
+Local Prave state:
+
+```
+~/.prave/credentials.json          # access + refresh tokens (chmod 600)
+~/.prave/anon-id                   # anonymous telemetry id (pre-login)
+~/.prave/usage-cursor.json         # transcript scanner watermark
+```
+
+## Status
+
+API health and uptime: [status.prave.app](https://status.prave.app) — auto-refreshes every 30 seconds, shows the live build version + commit SHA, and surfaces incidents from the last 30 days.
+
+## Links
+
+- 🌐 [**prave.app**](https://prave.app) — the platform
+- 📚 [**prave.app/docs**](https://prave.app/docs) — full documentation
+- 📖 [**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
+
+## License
+
+[MIT](https://github.com/eppstudio/prave/blob/main/LICENSE) © [EppLab Studio](https://epplab-studio.de)

package/dist/commands/import.js

@@ -1,5 +1,6 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import chalk from 'chalk';
 import ora from 'ora';
 import { track } from '../lib/analytics.js';
@@ -74,8 +75,42 @@ export async function importCommand(opts) {
         }
         return;
     }
-    // Visibility is required on every upload — no silent default.
-    if (opts.public === opts.private) {
+    // Visibility resolution. Order:
+    //   1. Explicit flags win — covers CI / scripted usage.
+    //   2. Interactive TTY with no flags → prompt the user (default: private,
+    //      because mistakenly making private notes public is far worse than
+    //      mistakenly keeping public ones private).
+    //   3. Non-TTY with no flags → hard error so a script never silently
+    //      uploads to the wrong visibility.
+    let visibility;
+    if (opts.public !== opts.private) {
+        visibility = opts.private ? 'private' : 'public';
+    }
+    else if (process.stdin.isTTY && skills.length > 0) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            const ans = (await rl.question(`\nUpload ${skills.length} local Skill${skills.length === 1 ? '' : 's'} as PUBLIC (visible in marketplace) or PRIVATE (only your account)? [public/private/cancel] `))
+                .trim()
+                .toLowerCase();
+            if (ans === 'cancel' || ans === 'c' || ans === 'q' || ans === 'quit') {
+                log.dim('Upload cancelled.');
+                return;
+            }
+            if (ans === 'public' || ans === 'pub') {
+                visibility = 'public';
+            }
+            else {
+                // Default to private on blank input or anything else (including
+                // ambiguous abbreviations like "p"). Better to upload-private and
+                // re-publish than to leak.
+                visibility = 'private';
+            }
+        }
+        finally {
+            rl.close();
+        }
+    }
+    else {
         log.warn('Specify visibility: --public or --private (one is required on upload).');
         log.dim('Examples:');
         log.dim('  prave import --upload --private    # only you can see them');
@@ -83,7 +118,6 @@ export async function importCommand(opts) {
         process.exitCode = 1;
         return;
     }
-    const visibility = opts.private ? 'private' : 'public';
     // Plan gate: authoring (public + private) is Pro+. Free is read-only on
     // the registry side — discover, install, bookmark, but no upload.
     const me = await fetchMyPlan();

package/dist/commands/install.js

@@ -73,7 +73,13 @@ export async function installCommand(slug, opts = {}) {
             await pullOne(s, { hasSession: true, force: Boolean(opts.force) });
         }
         installedSlugs = slugs;
-        spinner.succeed(`Installed ${slugs.length} skill${slugs.length === 1 ? '' : 's'} → ${CONFIG.skillsDir}`);
+        // Root slug = the user-requested one (last item by depth-sort), deps are
+        // the remaining ones. If `--no-deps` was passed, slugs is just [slug].
+        const depCount = slugs.length - 1;
+        const summary = depCount > 0
+            ? `Installed ${slug} + ${depCount} dep${depCount === 1 ? '' : 's'} → ${CONFIG.skillsDir}`
+            : `Installed ${slug} → ${CONFIG.skillsDir}`;
+        spinner.succeed(summary);
         if (slugs.length > 1) {
             log.dim(`   chain: ${slugs.join(' → ')}`);
         }

package/dist/commands/search.js

@@ -2,6 +2,18 @@ import chalk from 'chalk';
 import { track } from '../lib/analytics.js';
 import { api } from '../lib/api.js';
 import { log } from '../utils/logger.js';
+const SLUG_COL = 32;
+function formatInstalls(n) {
+    // Thousands separator. Locale-pinned to en-US so CI snapshots stay stable.
+    return n.toLocaleString('en-US');
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    if (max <= 1)
+        return '…';
+    return text.slice(0, max - 1) + '…';
+}
 export async function searchCommand(query) {
     track('cli_search', { length: query.length });
     const { data: skills } = await api.get(`/api/v1/skills?q=${encodeURIComponent(query)}&limit=25`);
@@ -9,7 +21,24 @@ export async function searchCommand(query) {
         log.dim(`No skills match "${query}".`);
         return;
     }
+    console.log(chalk.dim(`  ${skills.length} results`));
+    const cols = process.stdout.columns ?? 80;
+    // Description is indented 4 spaces. Reserve 1 char for the trailing
+    // ellipsis, leave the rest for content.
+    const descBudget = Math.max(20, cols - 4);
     for (const s of skills) {
-        console.log(`  ${chalk.cyan('•')} ${s.slug}  ${chalk.dim(s.description ?? '')}  ${chalk.magenta(`↓ ${s.install_count}`)}`);
+        const installsText = `↓ ${formatInstalls(s.install_count)}`;
+        const slugCell = s.slug.padEnd(SLUG_COL, ' ');
+        console.log(`  ${chalk.cyan('•')} ${slugCell}${chalk.magenta(installsText)}`);
+        const desc = s.description?.trim();
+        if (desc) {
+            console.log(`    ${chalk.dim(truncate(desc, descBudget))}`);
+        }
+        else {
+            console.log(`    ${chalk.dim('(no description)')}`);
+        }
+    }
+    if (skills.length > 0) {
+        console.log(chalk.dim('  → prave install <slug>'));
     }
 }

package/dist/commands/settings.js

@@ -100,14 +100,6 @@ async function configureOs(rl, current) {
     log.success(`OS set to ${updated.detected_os}`);
     return updated;
 }
-async function showAccount() {
-    console.log();
-    log.dim('Account info:');
-    log.dim(`  API: ${CONFIG.apiUrl}`);
-    log.dim(`  Credentials: ${CONFIG.credentialsPath}`);
-    log.dim(`  Local config: ${CONFIG.configPath}`);
-    log.dim('Run `prave whoami` for full identity, or `prave logout` to sign out.');
-}
 export async function settingsCommand() {
     const _session = await requireAuth("prave settings");
     if (!_session)
@@ -129,9 +121,8 @@ export async function settingsCommand() {
             console.log(`  ${chalk.cyan('1)')} Agent Configuration`);
             console.log(`  ${chalk.cyan('2)')} Skill Paths`);
             console.log(`  ${chalk.cyan('3)')} OS Settings`);
-            console.log(`  ${chalk.cyan('4)')} Account`);
-            console.log(`  ${chalk.cyan('5)')} Exit`);
-            const ans = (await rl.question('\nChoose [1-5]: ')).trim();
+            console.log(`  ${chalk.cyan('4)')} Exit`);
+            const ans = (await rl.question('\nChoose [1-4]: ')).trim();
             try {
                 if (ans === '1')
                     current = await configureAgents(rl, current);
@@ -139,9 +130,7 @@ export async function settingsCommand() {
                     current = await configurePaths(rl, current);
                 else if (ans === '3')
                     current = await configureOs(rl, current);
-                else if (ans === '4')
-                    await showAccount();
-                else if (ans === '5' || ans === '' || ans.toLowerCase() === 'exit') {
+                else if (ans === '4' || ans === '' || ans.toLowerCase() === 'exit') {
                     break;
                 }
                 else {

package/dist/commands/sync.js

@@ -7,18 +7,64 @@ import { track } from '../lib/analytics.js';
 import { CONFIG } from '../lib/config.js';
 import { requireAuth } from '../lib/credentials.js';
 import { fetchMyPlan, formatUpgradeHint } from '../lib/plan.js';
+import { readState, writeState } from '../lib/state.js';
+import { formatRelative, msSince } from '../lib/time.js';
 import { log } from '../utils/logger.js';
 import { installCommand } from './install.js';
+/**
+ * Empirical per-skill timing — `installCommand` does ~1 registry GET +
+ * ~1 file write + ~1 best-effort POST analyze, which clocks in around
+ * 0.4s on a warm connection. With concurrency=4 we approximate effective
+ * ~0.4s per skill / 4 ≈ 0.1s, but include a safety multiplier so the
+ * estimate doesn't oversell. End result: estimate ~ 0.15s/skill, rounded
+ * to nearest 5s with a 5s floor.
+ */
+const SECONDS_PER_SKILL = 0.15;
+const SYNC_CONCURRENCY = 4;
+function estimateSeconds(count) {
+    const raw = count * SECONDS_PER_SKILL;
+    const rounded = Math.round(raw / 5) * 5;
+    return Math.max(5, rounded);
+}
+/**
+ * Inline concurrency limiter — runs `fn(item)` for each item, never letting
+ * more than `limit` promises be in-flight at once. Returns when all settle.
+ *
+ * We deliberately avoid `Promise.all` over the full list to keep the agent
+ * gentle on the API and on the user's disk; ~3-4x throughput vs sequential
+ * is the goal, not "fire 200 requests at once".
+ */
+async function runWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (true) {
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
 /**
  * `prave sync` — re-pulls every locally installed Skill from the
  * registry. Picks up SKILL.md edits without the user having to remember
  * each slug.
  *
- * The deploy-to-all-agents question is asked ONCE up-front for the entire
- * queue (regression fix: it used to fire per Skill, forcing the user to
- * mash `y` 30 times). The answer is then threaded into every
- * `installCommand` invocation via `skipDeployPrompt: true` and we run a
- * single batched deploy at the end.
+ * Behaviours layered on top of the basic loop:
+ *   • Last-sync timestamp persisted to ~/.prave/state.json — used to nudge
+ *     against accidental rapid re-syncs (<30 min) and to skip the prompt
+ *     entirely on the first ever run.
+ *   • Concurrency-limited parallel pulls (4 in flight) — ~3-4x faster than
+ *     the previous sequential loop.
+ *   • Per-skill progress: spinner text ticks "Installed N / M — slug" so
+ *     the user can see actual liveness on slow connections.
+ *   • The deploy-to-all-agents question is asked ONCE up-front for the
+ *     entire queue and threaded into every `installCommand` invocation
+ *     via `skipDeployPrompt: true`. A single batched deploy runs at the
+ *     end.
  */
 export async function syncCommand() {
     track('cli_sync');
@@ -33,6 +79,38 @@ export async function syncCommand() {
         log.dim(formatUpgradeHint('explorer'));
         return;
     }
+    // Last-sync nudge. We read state up-front because if the user bails on
+    // the prompt we don't want to overwrite their last-sync timestamp.
+    const state = await readState();
+    if (state.last_sync_at) {
+        const since = msSince(state.last_sync_at);
+        const pretty = formatRelative(state.last_sync_at);
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        let proceed = true;
+        try {
+            // Stronger nudge when the user just synced (<30 min). Default flips
+            // to "no" — they almost certainly hit the wrong command.
+            if (since !== null && since < 30 * 60 * 1000) {
+                const ans = (await rl.question(`Last sync: ${pretty}. Sync again? [y/N] `))
+                    .trim()
+                    .toLowerCase();
+                proceed = ans === 'y' || ans === 'yes';
+            }
+            else {
+                const ans = (await rl.question(`Last sync: ${pretty}. Sync again? [Y/n] `))
+                    .trim()
+                    .toLowerCase();
+                proceed = ans === '' || ans === 'y' || ans === 'yes';
+            }
+        }
+        finally {
+            rl.close();
+        }
+        if (!proceed) {
+            log.dim('Sync cancelled.');
+            return;
+        }
+    }
     const spinner = ora('Scanning local Skills…').start();
     let entries = [];
     try {
@@ -53,6 +131,9 @@ export async function syncCommand() {
         return;
     }
     spinner.succeed(`Found ${slugs.length} installed Skill${slugs.length === 1 ? '' : 's'}.`);
+    // Pre-flight time estimate — sets expectations before the user hits Y.
+    const estSeconds = estimateSeconds(slugs.length);
+    console.log(chalk.dim(`Syncing ${slugs.length} Skill${slugs.length === 1 ? '' : 's'} — this takes about ${estSeconds} seconds.`));
     // Ask the deploy question ONCE for the whole batch.
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     let deployAfter = false;
@@ -65,19 +146,34 @@ export async function syncCommand() {
     finally {
         rl.close();
     }
+    // Parallel install with live progress counter.
+    const progress = ora(`Installed 0 / ${slugs.length}`).start();
+    let done = 0;
     let updated = 0;
     let failed = 0;
-    for (const slug of slugs) {
+    await runWithConcurrency(slugs, SYNC_CONCURRENCY, async (slug) => {
         try {
             await installCommand(slug, { noDeps: true, skipDeployPrompt: true });
             updated++;
         }
         catch {
             failed++;
-            console.log(chalk.red(`  ✗ ${slug}`));
         }
+        finally {
+            done++;
+            progress.text = `Installed ${done} / ${slugs.length} — ${slug}`;
+        }
+    });
+    if (failed === 0) {
+        progress.succeed(`Synced ${updated} / ${slugs.length}`);
+    }
+    else {
+        progress.warn(`Synced ${updated} · failed ${failed}`);
     }
-    log.dim(`\nSynced ${updated} · failed ${failed}`);
+    // Persist last-sync timestamp regardless of partial failures — the user
+    // *did* attempt a sync, and we want the cooldown to apply to retries
+    // just as much as to the happy path.
+    await writeState({ last_sync_at: new Date().toISOString() }).catch(() => { });
     if (deployAfter && updated > 0) {
         const { deployCommand } = await import('./deploy.js');
         log.info(`\nDeploying ${updated} Skills to configured agents…`);

package/dist/index.js

@@ -7,7 +7,6 @@ import { conflictsCommand } from './commands/conflicts.js';
 import { deployCommand } from './commands/deploy.js';
 import { diffCommand } from './commands/diff.js';
 import { exportCommand } from './commands/export.js';
-import { findCommand } from './commands/find.js';
 import { importCommand } from './commands/import.js';
 import { installCommand } from './commands/install.js';
 import { listCommand } from './commands/list.js';
@@ -155,13 +154,6 @@ 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')
-    .option('--local', 'only search local skills')
-    .option('--marketplace', 'only search the marketplace')
-    .option('--smart', 'use the LLM-assisted search endpoint')
-    .action(findCommand);
 program
     .command('deploy <skillname>')
     .description('Deploy a Skill to every configured agent (Claude Code, Codex, Cursor, Gemini, Cline, Amp). Free plan deploys to Claude Code only; Pro and Max deploy across all six. The skill must already exist locally — use `prave install` first or point to a SKILL.md folder.')
@@ -183,7 +175,6 @@ program
         '',
         'Discover & install',
         '  prave search <q>                   # public skill search',
-        '  prave find <q> [--smart|--local]   # smart cross-source search',
         '  prave install <slug> [--no-deps]   # install into ~/.claude/skills/',
         '  prave uninstall <slug>             # remove a local skill',
         '  prave list [--remote] [--verbose]  # what is installed (or remote)',

package/dist/lib/state.js

@@ -0,0 +1,34 @@
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONFIG } from './config.js';
+const STATE_PATH = join(CONFIG.praveDir, 'state.json');
+export async function readState() {
+    try {
+        const raw = await readFile(STATE_PATH, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Atomic write — write to .tmp, then rename. Prevents partial JSON if the
+ * process dies mid-write (which would otherwise make the next readState()
+ * throw on JSON.parse and quietly reset state to {}).
+ */
+export async function writeState(patch) {
+    await mkdir(CONFIG.praveDir, { recursive: true, mode: 0o700 });
+    const current = await readState();
+    const next = { ...current, ...patch };
+    const tmp = `${STATE_PATH}.tmp`;
+    await writeFile(tmp, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
+    await rename(tmp, STATE_PATH);
+    // Re-apply mode after rename — defensive: rename preserves the source's
+    // mode, but if a stale state.json exists with looser perms, this brings
+    // it back to user-only.
+    await chmod(STATE_PATH, 0o600);
+    return next;
+}

package/dist/lib/time.js

@@ -0,0 +1,55 @@
+/**
+ * Human-friendly relative time formatting for CLI output.
+ *
+ * Returns short English phrases like "2 hours ago", "12 minutes ago",
+ * "yesterday". Uses absolute thresholds rather than Intl.RelativeTimeFormat
+ * because we want consistent CLI copy across locales (the rest of the CLI
+ * is English-only).
+ */
+export function formatRelative(date) {
+    const d = date instanceof Date ? date : new Date(date);
+    const now = Date.now();
+    const ms = now - d.getTime();
+    const sec = Math.round(ms / 1000);
+    if (sec < 0)
+        return 'just now';
+    if (sec < 45)
+        return 'just now';
+    const min = Math.round(sec / 60);
+    if (min < 2)
+        return 'a minute ago';
+    if (min < 60)
+        return `${min} minutes ago`;
+    const hr = Math.round(min / 60);
+    if (hr < 2)
+        return 'an hour ago';
+    if (hr < 24)
+        return `${hr} hours ago`;
+    const day = Math.round(hr / 24);
+    if (day < 2)
+        return 'yesterday';
+    if (day < 30)
+        return `${day} days ago`;
+    const month = Math.round(day / 30);
+    if (month < 2)
+        return 'a month ago';
+    if (month < 12)
+        return `${month} months ago`;
+    const year = Math.round(day / 365);
+    if (year < 2)
+        return 'a year ago';
+    return `${year} years ago`;
+}
+/**
+ * Returns the gap (in ms) between `date` and now, or null if undefined.
+ * Convenience wrapper used by callers that need both raw delta and pretty
+ * output without re-parsing the date.
+ */
+export function msSince(date) {
+    if (date == null)
+        return null;
+    const d = date instanceof Date ? date : new Date(date);
+    if (Number.isNaN(d.getTime()))
+        return null;
+    return Date.now() - d.getTime();
+}

package/package.json

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

package/dist/commands/find.js

@@ -1,103 +0,0 @@
-import { createInterface } from 'node:readline/promises';
-import chalk from 'chalk';
-import ora from 'ora';
-import { tokenTier } from '@prave/shared';
-import { track } from '../lib/analytics.js';
-import { api, ApiError } from '../lib/api.js';
-import { log } from '../utils/logger.js';
-const TIER_EMOJI = {
-    lean: '🟢',
-    medium: '🟡',
-    heavy: '🔴',
-};
-function formatTokens(n) {
-    if (n < 1000)
-        return `~${n}`;
-    return `~${(n / 1000).toFixed(1)}k`;
-}
-function renderResult(r, idx) {
-    const badge = r.source === 'local'
-        ? chalk.cyan('[local]')
-        : chalk.magenta('[marketplace]');
-    const tier = TIER_EMOJI[tokenTier(r.estimated_tokens)];
-    const slash = r.slash_command ? chalk.dim(` ${r.slash_command}`) : '';
-    const installs = r.source === 'marketplace' && typeof r.install_count === 'number'
-        ? chalk.dim(` · ${r.install_count} installs`)
-        : '';
-    console.log(`${chalk.bold(`${idx + 1}.`)} ${badge} ${chalk.bold(r.name)}${slash}  ${tier} ${chalk.dim(formatTokens(r.estimated_tokens))}${installs}`);
-    if (r.description)
-        log.dim(`   ${r.description}`);
-}
-export async function findCommand(query, opts = {}) {
-    track('cli_find', {
-        length: query.length,
-        mode: opts.smart ? 'smart' : opts.local ? 'local' : opts.marketplace ? 'marketplace' : 'both',
-    });
-    const scope = opts.local
-        ? 'local'
-        : opts.marketplace
-            ? 'marketplace'
-            : 'both';
-    const spinner = ora(opts.smart ? 'Smart-searching…' : 'Searching…').start();
-    try {
-        let results;
-        if (opts.smart) {
-            const { data } = await api.post('/api/v1/intelligence/llm-search', { query }, true);
-            spinner.stop();
-            console.log(chalk.dim(`Task: ${data.task}`));
-            if (data.suggested_triggers.length > 0) {
-                log.dim(`Suggested triggers: ${data.suggested_triggers.join(', ')}`);
-            }
-            console.log();
-            results = data.results;
-        }
-        else {
-            const { data } = await api.post('/api/v1/intelligence/search', { query, scope }, true);
-            spinner.stop();
-            results = data;
-        }
-        if (results.length === 0) {
-            log.dim('No matches.');
-            return;
-        }
-        const top = results.slice(0, 5);
-        top.forEach((r, i) => renderResult(r, i));
-        if (opts.local)
-            return; // skip prompt when local-only
-        const installable = top.find((r) => r.source === 'marketplace' && !r.is_installed);
-        if (!installable)
-            return;
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        try {
-            const answer = (await rl.question(`\nInstall ${chalk.bold(installable.slug)}? [y/N] `)).trim().toLowerCase();
-            if (answer === 'y' || answer === 'yes') {
-                const { installCommand } = await import('./install.js');
-                await installCommand(installable.slug, {});
-            }
-        }
-        finally {
-            rl.close();
-        }
-    }
-    catch (err) {
-        spinner.stop();
-        if (err instanceof ApiError && err.status === 402) {
-            // Server returned the semantic-search upsell. Render it as a
-            // structured upgrade hint instead of a raw error so the message
-            // reads like guidance, not a crash.
-            log.error(err.message);
-            console.log();
-            console.log(chalk.dim('   Pro · $12/mo includes:'));
-            console.log(chalk.dim('     · `prave search "<natural language>"` ranked by intent'));
-            console.log(chalk.dim('     · Skill Intelligence audit + 30-day trigger telemetry'));
-            console.log(chalk.dim('     · Cross-machine sync · Tester · Authoring'));
-            console.log();
-            console.log(`   ${chalk.bold('→ Upgrade:')} ${chalk.cyan('https://prave.app/#pricing')}`);
-            console.log(chalk.dim('   Or browse the registry without semantic search:'), chalk.cyan('https://prave.app/discover'));
-            process.exitCode = 1;
-            return;
-        }
-        log.error(err instanceof ApiError ? err.message : err.message);
-        process.exitCode = 1;
-    }
-}