skills-manager-cli 2026.9.9 → 2026.9.10-1

package/README.md

@@ -2,62 +2,44 @@
 
 **English** | [简体中文](README.zh-CN.md)
 
-`skills-manager-cli` is a local-first CLI and dashboard for managing agent, Claude, and Codex skills from a registry-driven skill home.
+Manage your agent skills **from the conversation**: one `npx` command installs the manager skill, and from then on you just ask your agent — install, import, distribute, update, backfill provenance. Works with any skill-loading agent (Claude Code, Codex, Cursor, …).
 
 ## Quick Start
 
-**No setup needed** — just run:
-
 ```sh
-npx skills-manager-cli web
+npx skills-manager-cli
 ```
 
-This automatically creates and initializes `~/.skills-manager/` on first run.
-
-**Already have skills in `~/.claude/skills` or other agent runtimes?** Fold them in with `skills-manager init` — content moves into the hub, originals become symlinks (backed up first):
+That is the whole setup. Bootstrap creates the skill hub (`~/.skills-manager`), installs the **manager skill** into it from the bundled copy, and mounts it (symlink) into the agents it detects on your machine — you confirm the list in the one prompt it shows.
 
-```sh
-skills-manager init --dry-run   # preview
-skills-manager init             # import
-```
-
-**Want your agent to drive this CLI for you?** This repo ships an official agent skill (`skills/skills-manager/`) covering the full command surface plus the provenance-backfill workflow (adopt lockfile evidence → search & verify candidates → you approve each write, ADR-0012):
-
-```sh
-skills-manager add <this-repo-url> --skill skills-manager
-skills-manager distribute --to user --skill skills-manager
-```
+Then go back to your agent and say:
 
-Or install globally:
+> **帮我看看我的 skills：有哪些、装到哪些 agent 了、有没有能更新的**
+> (“Take stock of my skills: what I have, which agents they are wired into, and what has updates”)
 
-```sh
-npm install -g skills-manager-cli
-# or
-pnpm add -g skills-manager-cli
-skills-manager web
-```
+**Already have skills in `~/.claude/skills` or other agent runtimes?** Don't migrate during setup — just ask your agent:
 
-👉 **[See Getting Started guide](docs/GETTING_STARTED.md)** for detailed instructions and common tasks.
+> 帮我把现有的 skills 导入 skills-manager 并整理好来源
 
-## Install and Run
+Content moves into the hub, originals become symlinks (backed up first). Prefer to preview it yourself first? `skills-manager init --dry-run`.
 
-Use without installing globally:
+## How it works
 
-```sh
-npx skills-manager-cli web
+```text
+~/.skills-manager                        ← hub: the only content authority
+     skills/<name>/  ·  registry.yaml
+          │
+          │  distribute (symlink / copy)
+          ▼
+~/.claude/skills   ~/.cursor/skills   …  ← agent runtime dirs
+          ▲
+          │  drives, via `npx skills-manager-cli …`
+   your agent  ⇄  the manager skill
 ```
 
-Or install globally from a published package or packed tarball:
-
-```sh
-npm install -g skills-manager-cli
-# or
-pnpm add -g skills-manager-cli
-skills-manager web
-skills-manager doctor
-```
-
-`web` opens a local Vue/Fastify dashboard by default. Use `--no-open` to keep the browser closed.
+- The **manager skill** is the primary interface ([ADR-0014](docs/adr/0014-manager-skill-first-bootstrap.md)): the npx bootstrap installs it and nothing else; every management action afterwards happens through it, in agent conversation. No agent detected yet? Bootstrap still creates the hub and tells you how to mount later.
+- It keeps itself current: every CLI run compares the bundled copy with the hub copy and silently refreshes it — unless you edited the hub copy yourself, in which case it is yours and stays untouched.
+- The CLI underneath is a plain engine (JSON output, non-interactive flags) — see the [CLI reference](docs/CLI.md).
 
 ## Skill home layout
 
@@ -74,14 +56,15 @@ Skill home resolution priority:
 1. `--home <path>`
 2. `SKILL_HOME`
 3. current working directory when it already looks like a skill home
-4. `~/.skills-manager`, initialized automatically
+4. `~/.skills-manager` — created by bootstrap only; other commands point you at it instead of creating it
 
 ## Common commands
 
 ```sh
-skills-manager web --home ~/.skills-manager
-skills-manager doctor --home ~/.skills-manager
-skills-manager list --home ~/.skills-manager
+npx skills-manager-cli                            # bootstrap (default when no subcommand)
+skills-manager bootstrap --agent claude-code      # scripted bootstrap / mount later
+skills-manager doctor
+skills-manager list
 skills-manager add owner/repo --all --yes
 skills-manager distribute --to user --skill my-skill --agent claude-code
 skills-manager update --plan
@@ -99,6 +82,22 @@ skills-manager archive old-skill
 
 Sources can be GitHub shorthand (`owner/repo`), Git URLs, GitHub tree URLs, or local paths.
 
+## Optional: global install & dashboard
+
+Prefer typing a bare command? Install globally:
+
+```sh
+npm install -g skills-manager-cli   # or pnpm add -g skills-manager-cli
+```
+
+Prefer a visual interface? The local dashboard is an optional alternative to the conversation:
+
+```sh
+skills-manager web          # http://127.0.0.1:4777, --no-open to skip the browser
+```
+
+It offers the same library on one page: browse, install, update, and distribute. It never creates the hub — run bootstrap first.
+
 ## Development
 
 ```sh
@@ -109,6 +108,6 @@ pnpm test
 
 ## Documentation
 
-- **[Getting Started](docs/GETTING_STARTED.md)** — Installation, first launch, common tasks
+- **[Getting Started](docs/GETTING_STARTED.md)** — First run, importing existing skills, common tasks
 - **[CLI Reference](docs/CLI.md)** — Full command reference and advanced usage
 - **[Architecture](CONTEXT.md)** — Project structure and design decisions

package/README.zh-CN.md

@@ -2,62 +2,43 @@
 
 [English](README.md) | **简体中文**
 
-`skills-manager-cli` 是一个本地优先的 CLI 与网页控制台，基于注册表驱动的技能库（skill home）管理 agent、Claude、Codex 的技能。
+在**对话里**管理你的 agent skills：一条 `npx` 命令装上 manager skill，之后一切都直接吩咐你的 agent——安装、导入、分发、更新、补齐来源。任何会加载 skills 的 agent 都能用（Claude Code、Codex、Cursor、…）。
 
 ## 快速开始
 
-**无需任何安装** —— 直接运行：
-
 ```sh
-npx skills-manager-cli web
+npx skills-manager-cli
 ```
 
-首次运行时会自动创建并初始化 `~/.skills-manager/`。
-
-**已经在 `~/.claude/skills` 或其他 agent 运行时目录里有技能了？** 用 `skills-manager init` 一键收纳 —— 内容移入技能库，原位置变成软链接（会先备份）：
+这就是全部的安装步骤。bootstrap 会创建技能库（`~/.skills-manager`），从包内副本把 **manager skill** 种进库，并（以软链接）挂载到它检测到的 agent——展示一次多选让你确认清单。
 
-```sh
-skills-manager init --dry-run   # 预览
-skills-manager init             # 导入
-```
-
-**想让 agent 直接替你操作这个 CLI？** 本仓库自带一个官方 agent skill（`skills/skills-manager/`），覆盖全部命令，并内置「来源补齐」工作流（采纳锁文件证据 → 搜索并验证候选 → 你逐条拍板写入，ADR-0012）：
-
-```sh
-skills-manager add <本仓库地址> --skill skills-manager
-skills-manager distribute --to user --skill skills-manager
-```
+然后回到你的 agent，说：
 
-或者全局安装：
+> **帮我看看我的 skills：有哪些、装到哪些 agent 了、有没有能更新的**
 
-```sh
-npm install -g skills-manager-cli
-# 或
-pnpm add -g skills-manager-cli
-skills-manager web
-```
+**`~/.claude/skills` 等运行时目录里已经有 skills 了？** 不必在安装时迁移——直接吩咐：
 
-👉 **[查看入门指南](docs/GETTING_STARTED.zh-CN.md)** 了解详细用法与常见任务。
+> 帮我把现有的 skills 导入 skills-manager 并整理好来源
 
-## 安装与运行
+内容会移入库中，原位置变成软链接（先备份）。想先自己预览？`skills-manager init --dry-run`。
 
-免安装直接使用：
+## 工作原理
 
-```sh
-npx skills-manager-cli web
+```text
+~/.skills-manager                        ← 技能库：唯一的内容权威
+     skills/<name>/  ·  registry.yaml
+          │
+          │  分发（软链接 / 拷贝）
+          ▼
+~/.claude/skills   ~/.cursor/skills   …  ← agent 运行时目录
+          ▲
+          │  通过 `npx skills-manager-cli …` 驱动
+   你的 agent  ⇄  manager skill
 ```
 
-或从已发布的包/本地打包的 tarball 全局安装：
-
-```sh
-npm install -g skills-manager-cli
-# 或
-pnpm add -g skills-manager-cli
-skills-manager web
-skills-manager doctor
-```
-
-`web` 默认自动打开本地 Vue/Fastify 控制台。加 `--no-open` 可保持浏览器关闭。
+- **manager skill** 是主界面（[ADR-0014](docs/adr/0014-manager-skill-first-bootstrap.md)）：npx bootstrap 只装它、别的什么都不做；之后所有管理动作都通过它在 agent 对话里完成。还没装任何 agent？bootstrap 照样建好技能库，并告诉你之后怎么挂载。
+- 它自己保持最新：CLI 每次运行都会对比包内副本与库内副本并静默刷新——除非你自己改过库内副本，那就是你的了，不再碰它。
+- 底层的 CLI 是纯粹的引擎（JSON 输出、非交互 flag）——见 [CLI 参考](docs/CLI.zh-CN.md)。
 
 ## 技能库（skill home）结构
 
@@ -74,14 +55,15 @@ skills-manager doctor
 1. `--home <path>`
 2. `SKILL_HOME`
 3. 当前目录（当它已经是一个技能库时）
-4. `~/.skills-manager`（自动初始化）
+4. `~/.skills-manager` —— 仅由 bootstrap 创建；其他命令只会提示你先跑 bootstrap，不再隐式创建
 
 ## 常用命令
 
 ```sh
-skills-manager web --home ~/.skills-manager
-skills-manager doctor --home ~/.skills-manager
-skills-manager list --home ~/.skills-manager
+npx skills-manager-cli                            # bootstrap（不带子命令时的默认行为）
+skills-manager bootstrap --agent claude-code      # 脚本化 bootstrap / 之后再挂载
+skills-manager doctor
+skills-manager list
 skills-manager add owner/repo --all --yes
 skills-manager distribute --to user --skill my-skill --agent claude-code
 skills-manager update --plan
@@ -99,6 +81,22 @@ skills-manager archive old-skill
 
 来源（source）支持 GitHub 简写（`owner/repo`）、Git URL、GitHub tree URL 或本地路径。
 
+## 可选：全局安装与 dashboard
+
+想直接敲裸命令？全局安装：
+
+```sh
+npm install -g skills-manager-cli   # 或 pnpm add -g skills-manager-cli
+```
+
+想要可视化界面？本地 dashboard 是对话之外的可选替代：
+
+```sh
+skills-manager web          # http://127.0.0.1:4777，--no-open 不自动开浏览器
+```
+
+它在单页里提供同一个技能库：浏览、安装、更新、分发。它不会创建技能库——请先跑 bootstrap。
+
 ## 开发
 
 ```sh
@@ -109,6 +107,6 @@ pnpm test
 
 ## 文档
 
-- **[入门指南](docs/GETTING_STARTED.zh-CN.md)** —— 安装、首次启动、常见任务
+- **[入门指南](docs/GETTING_STARTED.zh-CN.md)** —— 首次运行、导入现有技能、常见任务
 - **[CLI 参考](docs/CLI.zh-CN.md)** —— 完整命令参考与进阶用法
 - **[架构](CONTEXT.md)** —— 项目结构与设计决策（英文）

package/dist/cli/bootstrap-prompt.js

@@ -0,0 +1,80 @@
+import readline from 'node:readline';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+/**
+ * Minimal TTY multi-select (the CLI's only interactive moment — ADR-0014):
+ * ↑/↓ move, space toggles, `a` toggles all, enter confirms, ctrl-c aborts.
+ * Returns the selected ids; all options start checked unless `allByDefault` is false.
+ */
+export async function multiSelect(title, options, config = {}) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new Error('multiSelect requires a TTY');
+    if (options.length === 0)
+        return [];
+    const checked = options.map(() => config.allByDefault !== false);
+    let cursor = 0;
+    const stdin = process.stdin;
+    readline.emitKeypressEvents(stdin);
+    const priorRaw = stdin.isRaw ?? false;
+    stdin.setRawMode(true);
+    stdin.resume();
+    process.stdout.write('\x1b[?25l');
+    const cleanup = () => {
+        process.stdout.write('\x1b[?25h\n');
+        stdin.setRawMode(priorRaw);
+        if (!priorRaw)
+            stdin.pause();
+    };
+    const render = () => {
+        const lines = [
+            `${BOLD}${title}${RESET}`,
+            ...options.map((option, index) => {
+                const marker = checked[index] ? '[x]' : '[ ]';
+                const pointer = index === cursor ? `${CYAN}❯${RESET} ` : '  ';
+                const detail = option.detail ? `  ${DIM}${option.detail}${RESET}` : '';
+                return `${pointer}${marker} ${option.label}${detail}`;
+            }),
+            `${DIM}↑/↓ move · space toggle · a all · enter confirm · ctrl-c abort${RESET}`,
+        ];
+        const total = lines.length + 1; // +1: the newline the previous render ended on
+        process.stdout.write(`\x1b[${total}A\x1b[0J`);
+        process.stdout.write(lines.join('\n') + '\n');
+    };
+    return new Promise((resolve) => {
+        const finish = (selection) => {
+            stdin.removeListener('keypress', onKey);
+            cleanup();
+            resolve(selection);
+        };
+        const onKey = (_chunk, key) => {
+            if (key.ctrl && key.name === 'c') {
+                finish([]);
+                process.exitCode = 130;
+                return;
+            }
+            if (key.name === 'up' || key.name === 'k')
+                cursor = (cursor - 1 + options.length) % options.length;
+            else if (key.name === 'down' || key.name === 'j')
+                cursor = (cursor + 1) % options.length;
+            else if (key.name === 'space')
+                checked[cursor] = !checked[cursor];
+            else if (key.name === 'a') {
+                const all = checked.every(Boolean);
+                for (let i = 0; i < checked.length; i += 1)
+                    checked[i] = !all;
+            }
+            else if (key.name === 'return') {
+                finish(options.filter((_, index) => checked[index]).map((option) => option.id));
+                return;
+            }
+            else
+                return;
+            render();
+        };
+        stdin.on('keypress', onKey);
+        render();
+    });
+}
+//# sourceMappingURL=bootstrap-prompt.js.map

package/dist/cli/bootstrap-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-prompt.js","sourceRoot":"","sources":["../../src/cli/bootstrap-prompt.ts"],"names":[],"mappings":"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"}

package/dist/cli/bootstrap.js

@@ -0,0 +1,82 @@
+import { createRequire } from 'node:module';
+import { createRuntimeServices, projectRootFromImportMeta } from '../infra/runtime.js';
+import { MANAGER_SKILL_NAME } from '../core/index.js';
+import { normalizeGitSourceUrl } from '../core/services/source-service.js';
+import { SkillsManagerError } from '../shared/errors.js';
+import { multiSelect } from './bootstrap-prompt.js';
+const pkg = createRequire(import.meta.url)('../../package.json');
+const projectRoot = projectRootFromImportMeta(import.meta.url);
+const STARTER_PROMPT_ZH = '帮我看看我的 skills：有哪些、装到哪些 agent 了、有没有能更新的';
+const STARTER_PROMPT_EN = 'Take stock of my skills: what I have, which agents they are wired into, and what has updates';
+const IMPORT_PROMPT_ZH = '帮我把现有的 skills 导入 skills-manager 并整理好来源';
+export function managerSkillBundle() {
+    const raw = pkg.repository?.url || 'shenysun/skills-manager';
+    return { root: projectRoot, version: pkg.version, repoUrl: normalizeGitSourceUrl(raw.replace(/^git\+/, '')) };
+}
+/**
+ * The one-time setup, and the product's front door (ADR-0014): create the hub,
+ * seed the manager skill from the bundled copy, mount it to the chosen agents,
+ * print the starter prompt. It imports nothing — importing existing runtime
+ * skills is a conversational act for later, through the manager skill itself.
+ */
+export async function runBootstrap(opts, cmd) {
+    const globalOpts = cmd.optsWithGlobals();
+    const s = createRuntimeServices({ home: globalOpts.home, ensureDefaultHub: true }, projectRoot);
+    const bundle = managerSkillBundle();
+    const seeded = s.managerSkill.seed(bundle);
+    const seedNotes = {
+        seeded: `installed the manager skill (skills-manager v${bundle.version})`,
+        refreshed: `updated the manager skill to v${bundle.version}`,
+        'up-to-date': `manager skill already current (v${bundle.version})`,
+        'user-managed': 'kept the existing skills-manager copy (installed or edited outside bootstrap)',
+    };
+    console.log(`• skill home: ${s.resolution.root}${s.resolution.created ? ' (created)' : ''}`);
+    console.log(`• ${seedNotes[seeded.status]}`);
+    const detected = s.catalog.detected();
+    const agents = await chooseAgents(opts, detected, s.catalog.resolveGlobalDir.bind(s.catalog));
+    if (agents.length > 0) {
+        try {
+            const applied = s.distribute.apply({ to: 'user', skills: [MANAGER_SKILL_NAME], agents, mode: 'symlink', force: Boolean(opts.force) });
+            const dirs = [...new Set(applied.entries.map((entry) => entry.runtimePath))];
+            console.log(`• mounted to: ${dirs.join(', ')}`);
+        }
+        catch (error) {
+            if (error instanceof SkillsManagerError && error.code === 'distribute_foreign_exists') {
+                throw new SkillsManagerError('bootstrap_foreign_runtime', `${error.message} Re-run with --force to replace it, or remove it first.`);
+            }
+            throw error;
+        }
+    }
+    else {
+        console.log('• manager skill mounted nowhere yet.');
+        console.log('  To mount later: npx skills-manager-cli bootstrap --agent <id>');
+    }
+    // Bootstrap never imports — it only reports what the user can bring in later (ADR-0014).
+    try {
+        const preview = s.init.run({ dryRun: true });
+        if (preview.imported.length > 0) {
+            const conflicts = preview.conflicts.length > 0 ? ` (+${preview.conflicts.length} needing decisions)` : '';
+            console.log(`• found ${preview.imported.length} existing skill(s) in your agent dirs${conflicts}.`);
+            console.log(`  Import them later from your agent: “${IMPORT_PROMPT_ZH}”`);
+        }
+    }
+    catch {
+        /* zero detected agents — there is nothing to preview */
+    }
+    s.activity.record({ action: 'cli-bootstrap', summary: `Bootstrap: ${seeded.status}, mounted to ${agents.join(', ') || 'none'}`, details: { seeded: seeded.status, agents } });
+    console.log('\nAll set. Go back to your agent and say:');
+    console.log(`  “${STARTER_PROMPT_ZH}”`);
+    console.log(`  (“${STARTER_PROMPT_EN}”)`);
+}
+/** `--agent` wins; one detected agent needs no question; several get the picker in a TTY, all of them otherwise. */
+async function chooseAgents(opts, detected, resolveGlobalDir) {
+    if (opts.agent && opts.agent.length > 0)
+        return opts.agent;
+    if (detected.length <= 1)
+        return detected;
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return detected;
+    const options = detected.map((id) => ({ id, label: id, detail: resolveGlobalDir(id) ?? undefined }));
+    return multiSelect('Install the manager skill into:', options);
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/cli/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/cli/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/cli/main.js

@@ -3,11 +3,38 @@ import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { createRuntimeServices, projectRootFromImportMeta } from '../infra/runtime.js';
 import { normalizeGitSourceUrl } from '../core/services/source-service.js';
+import { SkillsManagerError } from '../shared/errors.js';
+import { redactCheckout, redactDiscovered } from '../shared/redact.js';
+import { NodeFileSystem } from '../infra/fs-skill-home.js';
+import { GitHubApiClient } from '../infra/github-api-client.js';
+import { DetectionService, detectionLogPath } from '../core/services/detection-service.js';
+import { runBootstrap, managerSkillBundle } from './bootstrap.js';
 const pkg = createRequire(import.meta.url)('../../package.json');
 const projectRoot = projectRootFromImportMeta(import.meta.url);
-function services(cmd) {
+function services(cmd, options = {}) {
     const opts = cmd.optsWithGlobals();
-    return createRuntimeServices({ home: opts.home }, projectRoot);
+    const runtime = createRuntimeServices({ home: opts.home, ensureDefaultHub: Boolean(options.bootstrap) }, projectRoot);
+    if (!options.bootstrap && !runtime.resolution.exists) {
+        throw new SkillsManagerError('no_skill_home', `No skill home at ${runtime.resolution.root} yet. Run \`npx skills-manager-cli\` first — it creates the hub and installs the manager skill. (Or point --home at an existing hub.)`);
+    }
+    selfCheckManagerSkill(runtime);
+    return runtime;
+}
+/**
+ * Every CLI run keeps the hub's manager skill in step with the bundled copy
+ * (ADR-0014) — refresh silently when we still own it, never touch a
+ * user-modified copy, and never let this break the actual command. Notices go
+ * to stderr so stdout stays parseable JSON.
+ */
+function selfCheckManagerSkill(s) {
+    try {
+        const result = s.managerSkill.selfCheck(managerSkillBundle());
+        if (result?.status === 'refreshed')
+            console.error(`Refreshed the manager skill to v${pkg.version} to match this CLI version.`);
+    }
+    catch {
+        /* the manager skill must never break an unrelated command */
+    }
 }
 function print(value) {
     if (typeof value === 'string')
@@ -22,6 +49,22 @@ program
     .version(pkg.version)
     .option('--home <path>', 'skill home path; overrides SKILL_HOME and cwd detection')
     .showHelpAfterError();
+// Bootstrap is the product's front door (ADR-0014): the no-arg run and the
+// named command share one handler. `--agent`/`--force` live on the named
+// command only — the no-arg path is the interactive/default experience.
+program.command('bootstrap')
+    .description('One-time setup: create the hub, install the manager skill, mount it to your agents (the default when no subcommand is given)')
+    .option('-a, --agent <id...>', 'catalog agent ids to mount to; skips the interactive picker')
+    .option('--force', 'replace an unmanaged skills-manager directory at a runtime path')
+    .action(runBootstrap);
+program.argument('[stray...]');
+program.action((stray, opts, cmd) => {
+    // A typo'd subcommand must not silently run bootstrap: with a program-level
+    // action, commander hands it over as an operand instead of erroring.
+    if (stray && stray.length > 0)
+        throw new Error(`unknown command '${stray[0]}'. Run 'skills-manager --help' for the command list.`);
+    return runBootstrap(opts, cmd);
+});
 const webCommand = (cmd, description) => cmd
     .description(description)
     .option('-p, --port <port>', 'port', '4777')
@@ -29,6 +72,12 @@ const webCommand = (cmd, description) => cmd
     .option('--no-open', 'do not open a browser')
     .action(async (opts, self) => {
     const globalOpts = self.optsWithGlobals();
+    // Single entry point (ADR-0014): the dashboard never creates the hub — bootstrap does.
+    const probe = createRuntimeServices({ home: globalOpts.home }, projectRoot);
+    if (!probe.resolution.exists) {
+        throw new SkillsManagerError('no_skill_home', `No skill home at ${probe.resolution.root} yet. Run \`npx skills-manager-cli\` first — it creates the hub and installs the manager skill.`);
+    }
+    selfCheckManagerSkill(probe);
     // Lazy: fastify/shiki/markdown load only for the dashboard command, not on every CLI invocation.
     const { startDashboardServer } = await import('../dashboard/server/main.js');
     return startDashboardServer({ home: globalOpts.home, port: Number(opts.port), host: opts.host, open: opts.open, projectRoot });
@@ -198,13 +247,30 @@ catalog.command('info')
     .description('Show the current catalog snapshot stamp and detected agents')
     .action((_opts, cmd) => {
     const s = services(cmd);
-    print({ snapshot: s.catalog.snapshotInfo(), detected: s.catalog.detected() });
+    // Detected agents carry their runtime dir: a bare id list gives a
+    // conversation nothing to choose by (ticket manager-skill-first/04).
+    const detected = s.catalog.detected().map((id) => ({ id, runtimeDir: s.catalog.resolveGlobalDir(id) }));
+    print({ snapshot: s.catalog.snapshotInfo(), detected });
 });
 program.command('list')
     .description('List installed skills')
     .option('--category <category>', 'filter category')
     .option('--include-archived', 'include archived entries')
-    .action((opts, cmd) => print(services(cmd).registry.listSkills({ category: opts.category, includeArchived: opts.includeArchived })));
+    .option('--brief', 'compact rows (name, title, category, updatable) — for conversation-sized output')
+    .action((opts, cmd) => {
+    const rows = services(cmd).registry.listSkills({ category: opts.category, includeArchived: opts.includeArchived });
+    if (!opts.brief)
+        return print(rows);
+    // Full rows carry complete descriptions and consumer lists — tens of KB on
+    // a real hub. The brief form answers "what do I have" without them.
+    return print(rows.map((row) => ({
+        name: row.name,
+        title: row.title,
+        category: row.category,
+        updatable: Boolean(row.source?.url && row.source?.subpath),
+        archived: Boolean(row.archived),
+    })));
+});
 program.command('add')
     .description('Discover from a source, then install selected skills')
     .argument('<source>', 'Git URL, GitHub owner/repo, GitHub tree URL, or local path')
@@ -214,25 +280,60 @@ program.command('add')
     .option('-y, --yes', 'overwrite existing skills without prompting')
     .action((source, opts, cmd) => {
     const s = services(cmd);
-    const checkout = s.source.checkout(source);
-    const discovered = s.source.discover(checkout);
-    if (opts.list)
-        return print({ source: checkout, discovered });
-    const selectors = opts.all ? discovered.map((skill) => skill.subpath) : (opts.skill || []);
-    if (!opts.all && selectors.length === 0)
+    if (opts.list) {
+        return s.source.withCheckout(source, undefined, (checkout) => {
+            const discovered = s.source.discover(checkout);
+            return print({ source: redactCheckout(checkout), discovered: discovered.map(redactDiscovered) });
+        });
+    }
+    if (!opts.all && (opts.skill || []).length === 0)
         throw new Error('Use --all or --skill <name-or-subpath> to choose skills in this non-interactive CLI.');
+    // Empty selectors mean "everything discovered" — the --all semantics.
+    const selectors = opts.all ? [] : (opts.skill || []);
     const result = s.install.installFromSourceSelection({ source, selectors, overwrite: Boolean(opts.yes) });
     s.activity.record({ action: 'cli-add', summary: `Installed ${result.installed.join(', ')}`, details: { source, installed: result.installed } });
-    print(result);
+    print({ ...result, plan: { ...result.plan, source: redactCheckout(result.plan.source), selected: result.plan.selected.map(redactDiscovered) } });
     remindStaleTargets(s);
 });
 program.command('update')
     .description('Update skills from registry sources')
     .option('-s, --skill <skill...>', 'skill(s) to update')
     .option('--source <key>', 'source group key from updates plan')
-    .option('--plan', 'print update plan')
-    .action((opts, cmd) => {
+    .option('--plan', 'print update plan (candidates only)')
+    .option('--check', 'run upstream freshness detection: stale / upToDate / failed / skipped per skill (uncalibrated entries adopt their observed anchor, ADR-0013)')
+    .action(async (opts, cmd) => {
     const s = services(cmd);
+    if (opts.check) {
+        const detection = new DetectionService({ githubApi: new GitHubApiClient(), fs: new NodeFileSystem() });
+        const listed = s.registry.listSkills({ includeArchived: false });
+        const outcomes = await detection.detect(s, listed);
+        const detectionLog = detectionLogPath(s.resolution.root);
+        const stale = [];
+        const failed = [];
+        const upToDate = [];
+        const skipped = [];
+        for (const skill of listed) {
+            const outcome = outcomes.get(skill.name);
+            // No outcome = not part of this round (source-less rows and friends):
+            // counted as skipped, same wording the dashboard uses — never dropped
+            // silently (adversary M4).
+            if (!outcome || outcome.detection === 'skipped') {
+                skipped.push(skill.name);
+                continue;
+            }
+            if (outcome.detection === 'failed')
+                failed.push({ skill: skill.name, log: detectionLog });
+            else if (outcome.hasUpdate)
+                stale.push({ skill: skill.name, url: skill.source.url ?? '' });
+            else
+                upToDate.push(skill.name);
+        }
+        print({ checked: stale.length + failed.length + upToDate.length + skipped.length, stale, upToDate, failed, skipped });
+        // A failed check is a failed check — scripts read the exit code (adversary M6).
+        if (failed.length > 0)
+            process.exitCode = 1;
+        return;
+    }
     if (opts.plan || (!opts.skill && !opts.source))
         return print(s.update.plan());
     const result = opts.source ? s.update.updateSource(opts.source) : s.update.updateSkills(opts.skill);