skills-manager-cli 2026.9.11 → 2026.9.18

package/README.md

@@ -4,6 +4,17 @@
 
 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.
+
 ## Quick Start
 
 ```sh
@@ -96,10 +107,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

@@ -4,6 +4,17 @@
 
 在**对话里**管理你的 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 引擎。
+
 ## 快速开始
 
 ```sh
@@ -96,10 +107,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,68 @@
+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})`;
+}
+//# 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/insecure-http-confirm.js

@@ -0,0 +1,20 @@
+import readline from 'node:readline/promises';
+/**
+ * The plain-http confirmation (spec source-formats, US-12): an http:// URL
+ * source downloads only when the user says so — `--yes` on the command line
+ * or an interactive y/N. A non-interactive session (agent context, ADR-0014)
+ * declines: the core's insecure_http_unconfirmed error then names the remedy.
+ */
+export async function confirmInsecureHttp(url) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`Download ${url} over unencrypted http? [y/N] `)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=insecure-http-confirm.js.map

package/dist/cli/insecure-http-confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insecure-http-confirm.js","sourceRoot":"","sources":["../../src/cli/insecure-http-confirm.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,wBAAwB,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAW;IACnD,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAChE,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACtF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,GAAG,gCAAgC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACzG,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,KAAK,CAAC;IAC5C,CAAC;YAAS,CAAC;QACT,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/cli/main.js

@@ -2,13 +2,18 @@
 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 { isInsecureHttpSource, normalizeGitSourceUrl } from '../core/services/source-service.js';
+import { isUpdatableSourceType } from '../core/services/update-service.js';
+import { parseFormatFlag } from '../core/services/url-payload.js';
+import { confirmInsecureHttp } from './insecure-http-confirm.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 { HttpDownloadClient } from '../infra/http-download-client.js';
 import { DetectionService, detectionLogPath } from '../core/services/detection-service.js';
 import { runBootstrap, managerSkillBundle } from './bootstrap.js';
+import { renderCostLedger, renderPresetCostLine } from './cost-output.js';
 const pkg = createRequire(import.meta.url)('../../package.json');
 const projectRoot = projectRootFromImportMeta(import.meta.url);
 function services(cmd, options = {}) {
@@ -206,6 +211,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)')
@@ -274,12 +291,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(' ')}`;
@@ -287,16 +301,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')
@@ -313,6 +391,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')
@@ -359,30 +539,87 @@ program.command('list')
         name: row.name,
         title: row.title,
         category: row.category,
-        updatable: Boolean(row.source?.url && row.source?.subpath),
+        updatable: Boolean(row.source?.url && row.source?.subpath && isUpdatableSourceType(row.source.type)),
         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('--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}"`);
+    const ledger = s.cost.ledger(top);
+    if (opts.json)
+        return print(ledger);
+    process.stdout.write(renderCostLedger(ledger));
+});
 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')
+    .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')
     .option('--list', 'only list discovered skills')
     .option('--all', 'install all discovered skills')
     .option('-s, --skill <skill...>', 'skill name or source subpath to install')
-    .option('-y, --yes', 'overwrite existing skills without prompting')
-    .action((source, opts, cmd) => {
+    .option('-f, --format <format>', 'how to interpret a url payload: md, zip, or tar (tar covers tar/tar.gz/tgz) — the escape hatch when extension and Content-Type identify nothing')
+    .option('-y, --yes', 'overwrite existing skills without prompting; also confirms plain-http URL downloads')
+    .action(async (source, opts, cmd) => {
     const s = services(cmd);
+    const format = parseFormatFlag(opts.format);
+    // A plain-http url source downloads only with explicit confirmation
+    // (US-12): --yes on the command line or an interactive y/N — https and
+    // every other source kind needs none.
+    const allowInsecureHttp = isInsecureHttpSource(s.source.normalize(source))
+        ? Boolean(opts.yes) || await confirmInsecureHttp(source)
+        : false;
     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) });
-        });
+            // Marketplace sources present the two-level plugin → skills structure
+            // (US-15/17): every manifest plugin shows either its skills or why it
+            // cannot be consumed. Ordinary sources have no second level.
+            const view = s.source.marketplaceView(checkout, discovered);
+            return print({
+                source: redactCheckout(checkout),
+                ...(view ? { plugins: view.plugins } : {}),
+                discovered: discovered.map(redactDiscovered),
+            });
+        }, { allowInsecureHttp, format });
     }
     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) });
+    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) } });
     remindStaleTargets(s);
@@ -396,7 +633,7 @@ program.command('update')
     .action(async (opts, cmd) => {
     const s = services(cmd);
     if (opts.check) {
-        const detection = new DetectionService({ githubApi: new GitHubApiClient(), fs: new NodeFileSystem() });
+        const detection = new DetectionService({ githubApi: new GitHubApiClient(), http: new HttpDownloadClient(), fs: new NodeFileSystem() });
         const listed = s.registry.listSkills({ includeArchived: false });
         const outcomes = await detection.detect(s, listed);
         const detectionLog = detectionLogPath(s.resolution.root);
@@ -532,8 +769,8 @@ program.command('migrate-consumers')
     print(result);
 });
 program.command('rebuild-collections').description('Regenerate category collections').action((_opts, cmd) => { services(cmd).views.rebuildCollections(); print('collections rebuilt'); });
-program.command('archive').description('Archive canonical skills without permanent deletion').argument('<skills...>').action((skills, cmd) => print(services(cmd).archive.archiveSkills(skills)));
-program.command('adopt').description('Adopt a real directory from a generated view into canonical skills').argument('<view>').argument('<skill>').argument('[alsoConsumers...]').action((view, skill, alsoConsumers, cmd) => print(services(cmd).adopt.adopt(view, skill, alsoConsumers || [])));
+program.command('archive').description('Archive canonical skills without permanent deletion').argument('<skills...>').action((skills, _opts, cmd) => print(services(cmd).archive.archiveSkills(skills)));
+program.command('adopt').description('Adopt a real directory from a generated view into canonical skills').argument('<view>').argument('<skill>').argument('[alsoConsumers...]').action((view, skill, alsoConsumers, _opts, cmd) => print(services(cmd).adopt.adopt(view, skill, alsoConsumers || [])));
 program.parseAsync(process.argv).catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;