skills-manager-cli 2026.9.15 → 2026.10.26

package/README.md

@@ -1,15 +1,53 @@
 # Skills Manager
 
+[![npm](https://img.shields.io/npm/v/skills-manager-cli?color=cb3837)](https://www.npmjs.com/package/skills-manager-cli)
+[![npm downloads](https://img.shields.io/npm/dm/skills-manager-cli)](https://www.npmjs.com/package/skills-manager-cli)
+[![GitHub stars](https://img.shields.io/github/stars/shenysun/skills-manager?style=social)](https://github.com/shenysun/skills-manager/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/skills-manager-cli)](https://nodejs.org)
+
 **English** | [简体中文](README.zh-CN.md)
 
+
 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, …).
 
+> **CLI-first, conversation-driven.** This is `skills-manager-cli` — a terminal/npm tool with an optional local web dashboard. It is not a desktop app; if you were looking for the desktop application of the same name, that is a different project ([xingkongliang/skills-manager](https://github.com/xingkongliang/skills-manager)).
+
+**What makes it different:**
+
+- **One hub, every agent** — a single content library (`~/.skills-manager`) distributes any subset to any of the 70+ catalog agents, symlink or copy per target, with stale-copy detection and rollback.
+- **Five source types** — git repos and URLs, direct download URLs (SKILL.md / zip / tar), local zip archives, Claude plugin marketplaces, and well-known discovery indexes.
+- **Updates that don't cry wolf** — the update anchor is the git tree SHA of the skill's own subdirectory, so upstream commits outside the skill never light up an update.
+- **The resident-cost ledger** — every distributed skill's frontmatter charges each message; `skills-manager cost` accounts it per runtime path (approximate, `≈`) with report-only recall suggestions. Undistributed = zero. See [ADR-0018](docs/adr/0018-resident-cost-ledger.md).
+- **Provenance backfill** — imported skills without a source get one through lockfile-evidence adoption, agent-driven search, and your approval.
+- **The manager skill** — every management action happens in agent conversation ([ADR-0014](docs/adr/0014-manager-skill-first-bootstrap.md)); the CLI underneath is a plain JSON engine.
+
+
+## Why this instead of `gh skill` / `npx skills` / the desktop app?
+
+| | **skills-manager** | `gh skill` | `npx skills` | [desktop skills-manager](https://github.com/xingkongliang/skills-manager) |
+|---|---|---|---|---|
+| Primary UI | **Agent conversation** (manager skill) + CLI | GitHub CLI | CLI | Desktop GUI |
+| Hub model | Single `~/.skills-manager` → distribute subset | Per-agent / shared `.agents/skills` | Per install | Hub + presets |
+| Agents covered | **70+** (catalog snapshot) | ~48 | Depends on target | ~54 |
+| Non-GitHub sources | git / URL / zip / marketplace / well-known | GitHub (+ `--from-local`) | GitHub-centric | Marketplace + git |
+| Update signal | **Skill subtree tree-SHA** (no false positives) | Frontmatter tree SHA | Lockfile / metadata | App sync |
+| Context cost | Built-in **resident cost ledger** | — | — | — |
+| Multi-machine | Hub git sync (`sync push/pull`) | — | — | Device-code backup |
+| Install | `npx skills-manager-cli` | `gh extension` | `npx skills` | Desktop download |
+
+Pick this when you want **one library, many agents, conversation-driven ops**, and honest update/cost signals — not another one-shot installer.
+
 ## Quick Start
 
 ```sh
 npx skills-manager-cli
 ```
 
+![skills-manager demo](docs/assets/demo.gif)
+
+*`--help` and the resident context-cost ledger (`cost`) in action.*
+
 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.
 
 Then go back to your agent and say:
@@ -22,6 +60,20 @@ Then go back to your agent and say:
 
 Content moves into the hub, originals become symlinks (backed up first). Prefer to preview it yourself first? `skills-manager init --dry-run`.
 
+
+## Coming from `npx skills` or `gh skill`?
+
+You can keep installing with those tools. To consolidate into one hub (tree-SHA updates + the cost ledger) without re-downloading:
+
+```sh
+npx skills-manager-cli                 # bootstrap the hub + manager skill
+skills-manager init --dry-run          # preview importing existing runtime skills
+# or ask your agent: Import my existing skills into skills-manager
+skills-manager cost --share            # privacy-safe paste card of your resident skill tax
+```
+
+Runtime copies become hub-backed; originals are backed up first.
+
 ## How it works
 
 ```text
@@ -96,10 +148,11 @@ skills-manager provenance adopt                  # backfill lockfile evidence
 skills-manager categories set my-skill frontend     # tag with a domain category
 skills-manager categories apply frontend -a claude-code  # load only that domain
 skills-manager categories status                  # applied sets + drift
+skills-manager cost                              # resident context-cost ledger (report-only recall suggestions)
 skills-manager archive old-skill
 ```
 
-Sources can be GitHub shorthand (`owner/repo`), Git URLs, GitHub tree URLs, or local paths.
+Sources: GitHub shorthand (`owner/repo`), Git URLs, GitHub tree URLs, local paths, direct download URLs (single `SKILL.md` / zip / tar), local zip archives, plugin marketplaces (`.claude-plugin/marketplace.json`), and well-known discovery indexes — see the [CLI reference](docs/CLI.md).
 
 ## Optional: global install & dashboard
 

package/README.zh-CN.md

@@ -1,15 +1,53 @@
 # Skills Manager
 
+[![npm](https://img.shields.io/npm/v/skills-manager-cli?color=cb3837)](https://www.npmjs.com/package/skills-manager-cli)
+[![npm downloads](https://img.shields.io/npm/dm/skills-manager-cli)](https://www.npmjs.com/package/skills-manager-cli)
+[![GitHub stars](https://img.shields.io/github/stars/shenysun/skills-manager?style=social)](https://github.com/shenysun/skills-manager/stargazers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/skills-manager-cli)](https://nodejs.org)
+
 [English](README.md) | **简体中文**
 
+
 在**对话里**管理你的 agent skills：一条 `npx` 命令装上 manager skill，之后一切都直接吩咐你的 agent——安装、导入、分发、更新、补齐来源。任何会加载 skills 的 agent 都能用（Claude Code、Codex、Cursor、…）。
 
+> **CLI 优先、对话驱动。** 本项目是 `skills-manager-cli`——终端/npm 工具，附带可选的本地 web dashboard。它**不是**桌面应用；如果你找的是同名的桌面版，那是另一个项目（[xingkongliang/skills-manager](https://github.com/xingkongliang/skills-manager)）。
+
+**差异化在哪：**
+
+- **一个库，所有 agent**——单一内容库（`~/.skills-manager`）把任意子集分发到 catalog 里的 70+ agent，按目标选软链接或拷贝，带副本过期检测与回滚。
+- **五类源**——git 仓库与 URL、直下 URL（单个 `SKILL.md` / zip / tar）、本地 zip 归档、Claude 插件市场、well-known 发现索引。
+- **更新不误报**——更新锚点是 skill 自身子目录的 git tree SHA，上游动了 skill 之外的文件不会点亮「可更新」。
+- **常驻成本账本**——每个已分发 skill 的 frontmatter 都在按条消息计费；`skills-manager cost` 按运行时路径记账（近似口径，`≈` 展示）并给出只报告不执行的收回建议。未分发 = 零常驻。见 [ADR-0018](docs/adr/0018-resident-cost-ledger.md)。
+- **来源可回填**——没有来源的导入 skill，经锁文件证据采纳、agent 搜索、你批准三层流程补齐 provenance。
+- **manager skill**——所有管理动作都在 agent 对话里完成（[ADR-0014](docs/adr/0014-manager-skill-first-bootstrap.md)）；底层 CLI 是纯 JSON 引擎。
+
+
+## 为什么选它，而不是 `gh skill` / `npx skills` / 桌面版？
+
+| | **skills-manager** | `gh skill` | `npx skills` | [桌面版 skills-manager](https://github.com/xingkongliang/skills-manager) |
+|---|---|---|---|---|
+| 主界面 | **Agent 对话**（manager skill）+ CLI | GitHub CLI | CLI | 桌面 GUI |
+| 模型 | 单一 `~/.skills-manager` → 分发子集 | 按 agent / 共享 `.agents/skills` | 按次安装 | Hub + presets |
+| Agent 覆盖 | **70+**（catalog 快照） | ~48 | 视目标而定 | ~54 |
+| 非 GitHub 源 | git / URL / zip / marketplace / well-known | GitHub（+ `--from-local`） | 偏 GitHub | Marketplace + git |
+| 更新信号 | **skill 子目录 tree-SHA**（不误报） | frontmatter tree SHA | lockfile / metadata | App 同步 |
+| 上下文成本 | 内置**常驻成本账本** | — | — | — |
+| 多机同步 | Hub git 化（`sync push/pull`） | — | — | 设备码备份 |
+| 安装 | `npx skills-manager-cli` | `gh extension` | `npx skills` | 桌面安装包 |
+
+适合「**一个库、多 agent、对话驱动**，更新与成本信号要诚实」的场景——不是又一个一次性安装器。
+
 ## 快速开始
 
 ```sh
 npx skills-manager-cli
 ```
 
+![skills-manager demo](docs/assets/demo.gif)
+
+*演示：`--help` 与常驻上下文成本账本（`cost`）。*
+
 这就是全部的安装步骤。bootstrap 会创建技能库（`~/.skills-manager`），从包内副本把 **manager skill** 种进库，并（以软链接）挂载到它检测到的 agent——展示一次多选让你确认清单。
 
 然后回到你的 agent，说：
@@ -22,6 +60,20 @@ npx skills-manager-cli
 
 内容会移入库中，原位置变成软链接（先备份）。想先自己预览？`skills-manager init --dry-run`。
 
+
+## 从 `npx skills` 或 `gh skill` 过来？
+
+可以继续用它们安装。要把已有 skill 收进同一个 hub（树 SHA 更新 + 成本账本）、不必重下：
+
+```sh
+npx skills-manager-cli                 # 引导创建 hub + manager skill
+skills-manager init --dry-run          # 预览导入现有运行时 skill
+# 或对 agent 说：把我现有的 skills 导入 skills-manager
+skills-manager cost --share            # 可粘贴分享的常驻 skill 税卡片（无绝对路径）
+```
+
+运行时副本改为由 hub 托管；原文件会先备份。
+
 ## 工作原理
 
 ```text
@@ -96,10 +148,11 @@ skills-manager provenance adopt                  # 补采锁文件证据
 skills-manager categories set my-skill 前端       # 打领域类别标签
 skills-manager categories apply 前端 -a claude-code  # 只加载该领域
 skills-manager categories status                  # 已应用集合 + 漂移
+skills-manager cost                              # 常驻上下文成本账本（只报告不执行的收回建议）
 skills-manager archive old-skill
 ```
 
-来源（source）支持 GitHub 简写（`owner/repo`）、Git URL、GitHub tree URL 或本地路径。
+来源（source）：GitHub 简写（`owner/repo`）、Git URL、GitHub tree URL、本地路径、直下 URL（单个 `SKILL.md` / zip / tar）、本地 zip 归档、插件市场（`.claude-plugin/marketplace.json`）、well-known 发现索引——详见 [CLI 参考](docs/CLI.zh-CN.md)。
 
 ## 可选：全局安装与 dashboard
 

package/dist/cli/cost-output.js

@@ -0,0 +1,112 @@
+import { formatApproxTokens } from '../core/services/cost-ledger-service.js';
+/**
+ * Human rendering for `skills-manager cost` (spec context-cost, Q10 shape):
+ * path groups → per-skill lines → total + unmanaged line → the three
+ * suggestion layers. English per repo CLI convention; every number rides
+ * formatApproxTokens; every suggestion shows its verbatim command and nothing
+ * is ever executed.
+ */
+export function renderCostLedger(ledger) {
+    const lines = [];
+    lines.push(`Resident context cost (${ledger.method}) — total ${formatApproxTokens(ledger.totalTokens)} tokens across ${ledger.paths.length} runtime path(s)`);
+    for (const group of ledger.paths) {
+        lines.push('');
+        const family = group.agents.length > 0 ? group.agents.join(', ') : 'none';
+        lines.push(`${group.runtimeDir} (${group.kind}, agents: ${family}) — ${formatApproxTokens(group.tokens)}`);
+        const width = Math.max(0, ...group.skills.map((line) => line.skill.length));
+        for (const line of group.skills) {
+            const marks = [line.archived ? '(archived)' : null, line.incomplete ? 'incomplete' : null].filter(Boolean).join(' ');
+            lines.push(`  ${line.skill.padEnd(width)}  ${formatApproxTokens(line.tokens)}${marks ? `  ${marks}` : ''}`);
+        }
+    }
+    lines.push('');
+    lines.push(`${ledger.unmanaged} unmanaged skill(s) not counted`);
+    if (ledger.errors.length > 0) {
+        lines.push('Errors (counted as 0):');
+        for (const error of ledger.errors)
+            lines.push(`  ${error.skill} — ${error.runtimePath}: ${error.reason}`);
+    }
+    const suggestions = ledger.suggestions;
+    const empty = suggestions.archived.length === 0 && suggestions.topDescriptions.length === 0 && suggestions.scattered.length === 0;
+    lines.push('');
+    lines.push('Suggestions (report-only — nothing is executed):');
+    if (empty) {
+        lines.push('  none');
+        return `${lines.join('\n')}\n`;
+    }
+    if (suggestions.archived.length > 0) {
+        lines.push('Zero-controversy recalls (archived but still distributed):');
+        for (const item of suggestions.archived) {
+            lines.push(`  ${item.skill} (archived) ${formatApproxTokens(item.tokens)} — ${item.runtimeDir}`);
+            lines.push(`    ${item.command}`);
+        }
+    }
+    if (suggestions.topDescriptions.length > 0) {
+        const count = suggestions.topDescriptions.length;
+        lines.push(`Top ${count} most expensive description${count === 1 ? '' : 's'}:`);
+        for (const item of suggestions.topDescriptions) {
+            lines.push(`  ${item.skill} ${formatApproxTokens(item.tokens)} — ${item.runtimeDir}`);
+            lines.push(`    ${item.command}`);
+        }
+    }
+    if (suggestions.scattered.length > 0) {
+        lines.push('Scattered distributions (same skill on several paths — consolidate by recalling all but one):');
+        for (const item of suggestions.scattered) {
+            lines.push(`  ${item.skill} on ${item.runtimeDirs.length} paths: ${item.runtimeDirs.join(', ')}`);
+            for (const command of item.commands)
+                lines.push(`    ${command}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** The one-line resident-cost tail of a `preset apply` success (ADR-0019
+ *  US20): ≈-prefixed char-approx tokens, the same magnitude convention as the
+ *  ledger above. */
+export function renderPresetCostLine(cost) {
+    return `Resident cost: ${formatApproxTokens(cost.tokens)} tokens per message (${cost.method})`;
+}
+/**
+ * Privacy-safe paste card for `skills-manager cost --share` (growth wedge):
+ * no absolute paths, agent-family labels only, top skills by total tokens,
+ * a one-line CTA + repo URL. Same ledger, thinner surface.
+ */
+export function renderCostShare(ledger) {
+    const skillTotals = new Map();
+    for (const group of ledger.paths) {
+        for (const line of group.skills) {
+            skillTotals.set(line.skill, (skillTotals.get(line.skill) ?? 0) + line.tokens);
+        }
+    }
+    const skillCount = skillTotals.size;
+    const heaviest = [...skillTotals.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 3)
+        .map(([skill, tokens]) => `${skill} ${formatApproxTokens(tokens)}`);
+    const pathBits = ledger.paths.map((group) => {
+        const agents = group.agents.length > 0 ? group.agents.join('+') : 'none';
+        return `${group.kind}/${agents}`;
+    });
+    const lines = [];
+    lines.push(`Resident skill tax · ${ledger.method} · skills-manager`);
+    lines.push(`${formatApproxTokens(ledger.totalTokens)} tokens / message · ${skillCount} skill(s) · ${ledger.paths.length} path(s)`);
+    if (pathBits.length > 0)
+        lines.push(`Paths: ${pathBits.join(' · ')}`);
+    if (heaviest.length > 0)
+        lines.push(`Heaviest: ${heaviest.join(' · ')}`);
+    const archived = ledger.suggestions.archived.length;
+    const scattered = ledger.suggestions.scattered.length;
+    if (archived > 0 || scattered > 0) {
+        const watch = [];
+        if (archived > 0)
+            watch.push(`${archived} archived still distributed`);
+        if (scattered > 0)
+            watch.push(`${scattered} scattered`);
+        lines.push(`Watch: ${watch.join(' · ')}`);
+    }
+    if (ledger.unmanaged > 0)
+        lines.push(`${ledger.unmanaged} unmanaged skill(s) not counted`);
+    lines.push('Share: skills-manager cost --share');
+    lines.push('https://github.com/shenysun/skills-manager');
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=cost-output.js.map

package/dist/cli/cost-output.js.map

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

package/dist/cli/main.js

@@ -13,6 +13,7 @@ import { GitHubApiClient } from '../infra/github-api-client.js';
 import { HttpDownloadClient } from '../infra/http-download-client.js';
 import { DetectionService, detectionLogPath } from '../core/services/detection-service.js';
 import { runBootstrap, managerSkillBundle } from './bootstrap.js';
+import { renderCostLedger, renderCostShare, renderPresetCostLine } from './cost-output.js';
 const pkg = createRequire(import.meta.url)('../../package.json');
 const projectRoot = projectRootFromImportMeta(import.meta.url);
 function services(cmd, options = {}) {
@@ -140,6 +141,19 @@ function countErrored(s) {
 function staleOrErroredCount(s) {
     return Object.values(s.distribute.staleSummary()).reduce((total, count) => total + count, 0);
 }
+/** Report-only security scan after install/update: one stderr line per skill so stdout JSON stays parseable. */
+function remindSecurityScan(s, skills) {
+    if (skills.length === 0)
+        return;
+    for (const skill of skills) {
+        try {
+            console.error(s.security.formatSummaryLine(s.security.scanSkill(skill)));
+        }
+        catch {
+            /* scan must never break the install/update that already succeeded */
+        }
+    }
+}
 function remindStaleTargets(s) {
     const stale = staleOrErroredCount(s);
     if (stale > 0) {
@@ -210,6 +224,18 @@ program.command('edit')
 });
 // Domain categories: a free-form multi-valued registry axis, orthogonal to the
 // frozen legacy `category` (ADR-0015). Tag edits never touch runtime dirs.
+/** The applied-set column for `categories status`; a preset stamp rides beside the categories (US22), an unstamped path reads exactly as before. */
+function formatAppliedSet(applied) {
+    if (applied === null)
+        return 'no filter (no category set applied)';
+    if ('all' in applied)
+        return 'no filter (--all applied)';
+    return `categories: ${applied.categories.join(', ')}${applied.preset ? ` (preset: ${applied.preset})` : ''}`;
+}
+/** Shared drift phrasing so `categories status` and `preset list` never diverge — honest, never implied healthy (US6). */
+function driftNote(drift) {
+    return `${drift.length} skill(s) match the set but are undistributed: ${drift.join(', ')}`;
+}
 const categories = program.command('categories').description('Tag skills with domain categories and inspect the hub vocabulary');
 categories.command('set')
     .description('Replace the whole category list for a skill (no categories given = clear)')
@@ -278,12 +304,9 @@ categories.command('status')
     }
     for (const item of paths) {
         const agents = item.agents.length > 0 ? item.agents.join(', ') : 'none';
-        const set = item.applied === null
-            ? 'no filter (no category set applied)'
-            : 'all' in item.applied ? 'no filter (--all applied)' : `categories: ${item.applied.categories.join(', ')}`;
-        console.log(`${item.runtimeDir} (agents: ${agents}) — ${set}`);
+        console.log(`${item.runtimeDir} (agents: ${agents}) — ${formatAppliedSet(item.applied)}`);
         if (item.drift.length > 0) {
-            console.log(`  drift: ${item.drift.length} skill(s) match the set but are undistributed: ${item.drift.join(', ')}`);
+            console.log(`  drift: ${driftNote(item.drift)}`);
             const rerun = item.applied !== null && 'all' in item.applied
                 ? 'skills-manager categories apply --all'
                 : `skills-manager categories apply ${item.applied?.categories.join(' ')}`;
@@ -291,16 +314,80 @@ categories.command('status')
         }
     }
 });
-const provenance = program.command('provenance').description('Backfill provenance for source-less skills (lockfile evidence adoption, ADR-0011/0012)');
+// Named presets: a saved category list — the re-appliable loading-set档位
+// (ADR-0019). Storage only; switching runtime dirs is `preset apply`'s job.
+const preset = program.command('preset').description('Manage named lists of domain categories (re-appliable agent loading sets, ADR-0019)');
+preset.command('set')
+    .description('Replace the whole member list of a preset (overwrite-in-place when the name exists; categories need not exist in the hub yet)')
+    .argument('<name>')
+    .argument('<category...>')
+    .action((name, values, _opts, cmd) => {
+    const s = services(cmd);
+    const result = s.registry.setPreset(name, values);
+    s.activity.record({ action: 'cli-preset-set', summary: `set preset ${name}`, details: { preset: name, categories: values } });
+    print(result);
+});
+preset.command('list')
+    .description('List every preset with its member categories and mount footprint (drift on mounted paths reported as-is)')
+    .action((_opts, cmd) => {
+    const s = services(cmd);
+    const presets = s.registry.listPresets();
+    if (presets.length === 0) {
+        console.log('No presets yet — save one with `preset set <name> <category...>`.');
+        return;
+    }
+    // Mount footprint (US5/US6): which physical runtime paths currently carry
+    // each preset — zero mounts stay silent, and a drifted mount is reported,
+    // never implied healthy. Paths, not resolved-skill counts.
+    const statusPaths = s.distribute.categorySetStatus().paths;
+    for (const { name, categories } of presets) {
+        console.log(`${name}: ${categories.join(', ')}`);
+        const mounts = statusPaths.filter((item) => item.applied !== null && 'categories' in item.applied && item.applied.preset === name);
+        if (mounts.length === 0)
+            continue;
+        console.log(`  mounted on ${mounts.length} runtime path(s): ${mounts.map((item) => item.runtimeDir).join(', ')}`);
+        for (const item of mounts) {
+            if (item.drift.length === 0)
+                continue;
+            console.log(`  drift on ${item.runtimeDir}: ${driftNote(item.drift)}`);
+        }
+    }
+});
+preset.command('remove')
+    .description('Delete a preset and cascade-clear its name off every category-set record referencing it (applied categories kept, runtime untouched); reports how many paths the name was detached from')
+    .argument('<name>')
+    .action((name, _opts, cmd) => {
+    const s = services(cmd);
+    const { preset, detached } = s.distribute.removePresetCascade(name);
+    s.activity.record({ action: 'cli-preset-remove', summary: `removed preset ${name}, detached from ${detached} runtime path(s)`, details: { preset: name, detached } });
+    console.log(`Removed preset ${name} [${preset.categories.join(', ')}] — detached the name from ${detached} runtime path(s)`);
+});
+preset.command('apply')
+    .description("Rewrite the selected agents' runtime dirs to exactly the skills in the preset's categories (same strict semantics as `categories apply`: manager skill exempt, foreign untouched, uncategorized removed) and stamp the record with the preset name; success ends with the preset's resident-cost line")
+    .argument('<name>')
+    .option('-a, --agent <id...>', 'catalog agent ids (repeatable); defaults to the detected set')
+    .option('--json', 'machine-readable output for agents')
+    .action((name, opts, cmd) => {
+    const s = services(cmd);
+    const result = s.distribute.applyPreset(name, opts.agent);
+    const cost = s.cost.pathCost(result.paths.map((item) => item.runtimeDir));
+    const summary = `Applied preset ${name} [${result.categories.join(', ')}] to ${result.paths.length} runtime path(s)`;
+    s.activity.record({ action: 'cli-preset-apply', summary, details: { preset: name, categories: result.categories, agents: result.agents, costTokens: cost.tokens } });
+    if (opts.json)
+        return print({ ...result, cost });
+    console.log(summary);
+    console.log(renderPresetCostLine(cost));
+});
+const provenance = program.command('provenance').description('Backfill provenance for source-less skills (frontmatter & lockfile evidence adoption, ADR-0011/0012/0017)');
 provenance.command('adopt')
-    .description('Adopt npx skills lockfile evidence onto legacy imported skills that have no source yet')
+    .description('Adopt frontmatter/lockfile evidence onto legacy imported skills that have no source yet')
     .option('--dry-run', 'print what would be adopted without touching the registry')
     .option('-s, --skill <skill...>', 'limit adoption to specific skills')
     .action((opts, cmd) => {
     const s = services(cmd);
     const result = s.provenance.adopt({ dryRun: Boolean(opts.dryRun), skills: opts.skill });
     if (!opts.dryRun)
-        s.activity.record({ action: 'cli-provenance-adopt', summary: `Adopted lockfile evidence for ${result.adopted.map((item) => item.skill).join(', ') || 'nothing'}`, details: { adopted: result.adopted.map((item) => item.skill), skipped: result.skipped } });
+        s.activity.record({ action: 'cli-provenance-adopt', summary: `Adopted provenance evidence for ${result.adopted.map((item) => item.skill).join(', ') || 'nothing'}`, details: { adopted: result.adopted.map((item) => item.skill), skipped: result.skipped } });
     print(result);
 });
 provenance.command('list')
@@ -317,6 +404,108 @@ provenance.command('list')
     for (const skill of pending.locallyAuthored)
         console.log(`  ${skill}`);
 });
+// Hub git-ification for multi-machine sync (ADR-0020): each command thin, git
+// stays the merge tool, and the operator keeps every git decision.
+const sync = program.command('sync').description('Multi-machine sync via a git-ified hub (init/push/pull/status, ADR-0020)');
+sync.command('init')
+    .description('Turn the hub into a git repository (or adopt an existing one) with the canonical .gitignore and a baseline commit; optionally attach a remote')
+    .option('--remote <url>', 'git remote URL to attach as origin (a local bare repo works too)')
+    .action((opts, cmd) => {
+    const s = services(cmd);
+    const result = s.sync.init({ remote: opts.remote });
+    s.activity.record({ action: 'cli-sync-init', summary: `${result.mode} hub git-ification`, details: result });
+    // Zero-omission report (US-4): every dimension states what happened, including "nothing".
+    console.log(result.mode === 'adopted' ? 'adopted: existing git repository kept (history preserved)' : 'initialized: fresh git repository created');
+    console.log(result.ignoreLinesAdded.length > 0
+        ? `.gitignore: appended ${result.ignoreLinesAdded.length} line(s): ${result.ignoreLinesAdded.join(', ')}`
+        : '.gitignore: nothing to append (canonical lines already present)');
+    console.log(result.baselineCommit ? `baseline commit: ${result.baselineCommit}` : 'baseline commit: none (tree already clean)');
+    if (result.remote === null)
+        console.log('remote origin: not set (pass --remote <url> to attach one)');
+    else
+        console.log(result.remote.attached ? `remote origin: attached ${result.remote.url}` : `remote origin: already ${result.remote.url}`);
+    console.log('Reminder: the hub will be pushed to this remote — confirm it contains no secrets (tokens, keys, .env files).');
+});
+sync.command('status')
+    .description('Read-only sync status: git-ification, remote, dirty files, ahead/behind (last fetch), last sync commit — zero network')
+    .option('--json', 'machine-readable output for agents')
+    .action((opts, cmd) => {
+    const result = services(cmd).sync.status();
+    if (opts.json)
+        return print(result);
+    // Read-only probe: no activity record — status itself must not dirty the hub.
+    console.log(`hub: ${result.home}`);
+    if (!result.gitified) {
+        console.log(`git: no — ${result.hint}`);
+        return;
+    }
+    console.log('git: yes');
+    console.log(result.remote === null
+        ? 'remote origin: not configured (attach one with `sync init --remote <url>`)'
+        : `remote origin: ${result.remote}`);
+    console.log(result.dirtyFiles === 0 ? 'dirty files: 0 (clean tree)' : `dirty files: ${result.dirtyFiles}`);
+    console.log(result.aheadBehind === null
+        ? 'ahead/behind: unknown (no upstream tracking ref yet — set by your first push)'
+        : `ahead/behind: ahead ${result.aheadBehind.ahead}, behind ${result.aheadBehind.behind} (based on last fetch — run \`git -C ${result.home} fetch\` to refresh)`);
+    console.log(result.lastCommit === null
+        ? 'last sync commit: none yet (the hub repo has no commits)'
+        : `last sync commit: ${result.lastCommit.sha} ${result.lastCommit.message}`);
+});
+sync.command('push')
+    .description('Stage all changes, make one summary commit, and push to the remote (no empty commits)')
+    .action((_opts, cmd) => {
+    const s = services(cmd);
+    const result = s.sync.push();
+    // Honest summary: an in-sync push sent nothing, and the log must not claim one did.
+    s.activity.record({
+        action: 'cli-sync-push',
+        summary: result.upToDate ? 'Sync push: already in sync, nothing sent' : `Pushed hub to ${result.remote}`,
+        details: { commit: result.commit?.sha ?? null, upToDate: result.upToDate },
+    });
+    if (result.upToDate) {
+        console.log('already in sync: no changes to commit, remote is up to date');
+        return;
+    }
+    console.log(result.commit === null
+        ? 'commit: none (working tree clean — pushed existing local commits)'
+        : `commit: ${result.commit.sha} ${result.commit.message}`);
+    console.log(`pushed to origin: ${result.remote}`);
+});
+sync.command('pull')
+    .description('Fetch and merge the remote hub (merge commits allowed; a dirty tree is refused, never stashed; user-data conflicts are yours to resolve — only the tool-generated empty registry placeholder is reconciled)')
+    .action((_opts, cmd) => {
+    const s = services(cmd);
+    const result = s.sync.pull();
+    s.activity.record({
+        action: 'cli-sync-pull',
+        summary: result.upToDate ? 'Sync pull: already up to date' : `Pulled hub from ${result.remote}`,
+        details: { upToDate: result.upToDate, registryPlaceholderSuperseded: result.registryPlaceholderSuperseded, ...result.stats },
+    });
+    if (result.upToDate) {
+        console.log('already up to date: nothing to merge from the remote');
+        return;
+    }
+    console.log(`pulled from origin: ${result.remote}`);
+    const { added, updated, removed } = result.stats;
+    const segments = [
+        ...(added.length > 0 ? [`${added.length} added (${added.join(', ')})`] : []),
+        ...(updated.length > 0 ? [`${updated.length} updated (${updated.join(', ')})`] : []),
+        ...(removed.length > 0 ? [`${removed.length} removed (${removed.join(', ')})`] : []),
+    ];
+    console.log(segments.length > 0 ? `merged skills: ${segments.join(', ')}` : 'merged skills: none changed');
+    console.log(result.stats.registryChanged ? 'registry: changed' : 'registry: unchanged');
+    if (result.registryPlaceholderSuperseded !== null) {
+        // Zero-omission (ticket 07): the merge clashed on registry.yaml and the
+        // tool settled it because the local side was provably its own init
+        // placeholder — say so plainly.
+        console.log('registry conflict: resolved by keeping the remote registry (the local side was the empty init placeholder, not user data)');
+    }
+    // Plain text, on purpose (US-14): the follow-up stays the operator's call —
+    // nothing is detected, distributed, or marked.
+    if (added.length > 0) {
+        console.log('Newly pulled skills are not distributed yet — run `distribute --skill <name>` when you want them available to your agents.');
+    }
+});
 const backup = program.command('backup').description('Inspect and restore init backups (hub .backups/, 30-day retention)');
 backup.command('list')
     .description('List saved backups')
@@ -367,6 +556,50 @@ program.command('list')
         archived: Boolean(row.archived),
     })));
 });
+// The reference layer (ADR-0017): a zero-retention read channel. Raw stdout
+// under the `status` human-readable precedent — never JSON `print` — so agents
+// can pipe the skill body; the archived notice rides stderr to keep stdout
+// byte-exact. No borrow/cleanup lifecycle.
+program.command('get')
+    .description("Print a hub skill's full SKILL.md to stdout (zero-retention read; provenance evidence rides the frontmatter)")
+    .argument('<skill>')
+    .option('--path', 'print the canonical hub directory (absolute) for read-only borrowing of sibling files, instead of the file body')
+    .action((skill, opts, cmd) => {
+    const s = services(cmd);
+    const target = s.get.resolve(skill);
+    const archivedNotice = `Note: ${skill} is archived — still readable; it only left the management plane (updates, distribution).`;
+    if (opts.path) {
+        console.log(target.dir);
+        console.log('Read-only borrow: do not write into this directory — the hub is canonical; changes go through skills-manager commands.');
+        if (target.archived)
+            console.log(archivedNotice);
+        return;
+    }
+    if (target.archived)
+        console.error(archivedNotice);
+    process.stdout.write(s.get.read(target));
+});
+// The resident-cost ledger (ADR-0018): a read-only account grouped by physical
+// runtime path. Suggestions are report-only — each names the verbatim
+// undistribute command and never runs it. No filter flags in v1: consumers
+// filter the `--json` structure themselves.
+program.command('cost')
+    .description('Show the resident context-cost ledger: per-runtime-path token cost of distributed skill frontmatter, with report-only recall suggestions')
+    .option('--json', 'machine-readable output for agents')
+    .option('--share', 'privacy-safe paste card (no absolute paths) for X / HN / chat')
+    .option('--top <n>', 'how many of the most expensive descriptions to list', '5')
+    .action((opts, cmd) => {
+    const s = services(cmd);
+    const top = Number.parseInt(opts.top, 10);
+    if (!Number.isInteger(top) || top < 0)
+        throw new Error(`--top expects a non-negative integer, got "${opts.top}"`);
+    if (opts.json && opts.share)
+        throw new Error('use either --json or --share, not both');
+    const ledger = s.cost.ledger(top);
+    if (opts.json)
+        return print(ledger);
+    process.stdout.write(opts.share ? renderCostShare(ledger) : renderCostLedger(ledger));
+});
 program.command('add')
     .description('Discover from a source, then install selected skills')
     .argument('<source>', 'Git URL, GitHub owner/repo, GitHub tree URL, local path, local .zip archive, or http(s) URL of a single SKILL.md / zip / tar archive')
@@ -405,6 +638,7 @@ program.command('add')
     const result = s.install.installFromSourceSelection({ source, selectors, overwrite: Boolean(opts.yes), allowInsecureHttp, format });
     s.activity.record({ action: 'cli-add', summary: `Installed ${result.installed.join(', ')}`, details: { source, installed: result.installed } });
     print({ ...result, plan: { ...result.plan, source: redactCheckout(result.plan.source), selected: result.plan.selected.map(redactDiscovered) } });
+    remindSecurityScan(s, result.installed);
     remindStaleTargets(s);
 });
 program.command('update')
@@ -451,8 +685,19 @@ program.command('update')
     const result = opts.source ? s.update.updateSource(opts.source) : s.update.updateSkills(opts.skill);
     s.activity.record({ action: 'cli-update', summary: `Updated ${result.updated.join(', ')}`, details: result });
     print(result);
+    remindSecurityScan(s, result.updated);
     remindStaleTargets(s);
 });
+const audit = program.command('audit').description('Report-only audits over hub skills (security today; more subcommands later)');
+audit.command('security')
+    .description('Scan skill tree(s) for high-signal risks: shell exec, network calls, credential paths, secret-like strings (never blocks)')
+    .argument('[skills...]', 'canonical skill names; omit to scan every non-archived hub skill')
+    .action((skills, _opts, cmd) => {
+    const s = services(cmd);
+    const names = skills.length > 0 ? skills : s.registry.listSkills().map((skill) => skill.name);
+    const reports = s.security.scanSkills(names);
+    print(reports.length === 1 ? reports[0] : reports);
+});
 const distribute = program.command('distribute')
     .description('Distribute hub skills to user or project runtime directories')
     .option('--to <kind>', 'user or project')