greprag 5.83.2 → 5.85.0

package/dist/commands/skill.js

@@ -1,18 +1,20 @@
 "use strict";
-// `greprag skill` — opt-in management for bundled advisor skills.
+// `greprag skill` — bundled advisor skills, and read access to the skill mirror.
 //
 // The package bundles `greprag/` (the front-door, auto-installed by init)
-// alongside opt-in advisor skills (`discord/`, `content-advisor/`,
-// `mechanic/`, future ones). Operators choose which advisors to add
-// to their Claude Code skill registry via this verb instead of having
-// them force-installed on every `npm i -g greprag@<new>`.
+// alongside opt-in advisor skills (`content-advisor/`, `mechanic/`, future
+// ones). Operators choose which advisors to add to their Claude Code skill
+// registry via this verb instead of having them force-installed on every
+// `npm i -g greprag@<new>`.
 //
-// Verbs:
-//   greprag skill list                — show bundled skills + install status
-//   greprag skill install <name>      — copy bundle/<name>/ → ~/.claude/skills/<name>/
-//   greprag skill uninstall <name>    — remove ~/.claude/skills/<name>/ (greprag/ refused)
+// Every other skill lives in git: dotclaude `skills/<name>/` (global) or
+// `<repo>/.claude/skills/<name>/` (project). GrepRAG mirrors the committed
+// files read-only; `skill mirror sync` ingests them. Commands that used to
+// write the mirror (edit, apply, snapshot create/promote, revert) refuse
+// and name the git folder to edit.
 //
 // adr: adr/skill-bundle-shape.md
+// adr: adr/skill-ownership-git.md
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -47,106 +49,85 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readOnlyNames = readOnlyNames;
 exports.runSkill = runSkill;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
-const proc_1 = require("../proc");
-const claude_lifecycle_cutover_1 = require("../claude-lifecycle-cutover");
 const native_skill_mirror_1 = require("../native-skill-mirror");
 const project_anchor_1 = require("../project-anchor");
 const skill_mirror_client_1 = require("../skill-mirror-client");
-const skill_landing_1 = require("../skill-landing");
+const skill_git_ingest_1 = require("../skill-git-ingest");
 const skill_staleness_1 = require("../skill-staleness");
-const load_1 = require("./load");
+const skill_landing_1 = require("../skill-landing");
 const CORE_SKILL = 'greprag';
-const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-/** `--only a,b` / `--only=a,b` / repeated `--only a --only b` → skill names. */
-function readOnlyNames(args) {
-    const raw = [];
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--only' && args[i + 1])
-            raw.push(args[++i]);
-        else if (args[i].startsWith('--only='))
-            raw.push(args[i].slice('--only='.length));
-    }
-    const names = [...new Set(raw.flatMap(value => value.split(',')).map(v => v.trim()).filter(Boolean))];
-    const invalid = names.filter(name => !SKILL_NAME_RE.test(name));
-    if (invalid.length > 0)
-        throw new Error(`--only got invalid skill name(s): ${invalid.join(', ')}`);
-    return names;
-}
-const SKILL_HELP = `greprag skill — manage bundled advisor skills
+const SKILL_HELP = `greprag skill — bundled advisor skills and the read-only skill mirror
 
 USAGE
   greprag skill list                  Show bundled skills and install status
   greprag skill install <name>        Install a bundled advisor skill
   greprag skill uninstall <name>      Remove a previously-installed advisor
-  greprag skill edit <name> [--skill-id <id>] [--scope project --project-id <id>]
-                                      Export/edit/apply helper; opens $EDITOR unless --no-open or Codex
-  greprag skill mirror sync [harness] Install native GrepRAG skill adapters
-    claude-code --cutover-lifecycle    Cut over commit/deploy/release only
-    claude-code --only <a,b>           Install adapters for named mirrored skills
-                                       (closes the gaps greprag load marks with *)
+  greprag skill history <name> [--skill-id <id>] [--limit <n>]
+                                      Every mirrored revision: date, source commit, changes
+  greprag skill diff <name> <revA> [<revB>]
+                                      Unified diff between two revisions (revB defaults to current)
+  greprag skill mirror sync [codex|opencode|all] [--force]
+                                      Ingest committed skills from git into the mirror,
+                                      then refresh Codex/OpenCode launchers
   greprag skill mirror export <name> --to <dir>
-                                      Export canonical skill bytes for editing
-  greprag skill mirror apply <dir> --skill <name> --expected-hash <hash>
-                                      Promote edited bytes with stale-write guard
-  greprag skill mirror snapshot create <name> --name <snapshot>
-  greprag skill mirror snapshot list <name>
-  greprag skill mirror snapshot show <name> --name <snapshot>
+                                      Copy the mirrored files into a folder (read only)
+  greprag skill mirror snapshot list|show <name> [--name <snapshot>]
   greprag skill mirror snapshot restore <name> --name <snapshot> --to <dir>
-  greprag skill mirror snapshot promote <name> --name <snapshot> --expected-hash <hash>
-                                      Promote snapshot bytes as the newest revision
-                                      Named package rollback points
+                                      Archived named snapshots (read only)
   greprag skill source stamp <name> --project <p> --path <rel> [--path <rel>...]
-                                      [--root <dir>] [--baseline <ref>]
-                                      Stamp a skill's local source baseline
+                                      Stamp a source binding into the skill's git SKILL.md
+
+WHERE SKILLS LIVE
+  Git owns every skill. Edit the folder, commit, and the mirror follows at the
+  next session start or \`greprag skill mirror sync\`:
+    global   ~/.claude/skills/<name>/          (the dotclaude repo)
+    project  <repo>/.claude/skills/<name>/
+    bundled  packages/cli/skill/<name>/        (the greprag repo)
+  Claude Code reads those folders directly. Codex and OpenCode get launchers
+  that run \`greprag load <name>\`, which serves the committed content.
+  Uncommitted edits are never mirrored.
 
-NOTES
-  • The 'greprag' skill is auto-installed and refreshed on every upgrade.
-    It cannot be uninstalled via this verb (delete the dir manually if
-    you really want it gone — postinstall will reinstall on next upgrade).
-  • Other bundled skills are opt-in and refresh-only on upgrade: once
-    installed, they stay current with the bundle; if never installed,
-    upgrades leave them out of your skill registry.
-  • Mirrored skill edits use export/apply semantics. \`skill edit\` only wraps
-    that flow: export current bytes, open an editor, show a diff summary, then
-    apply with the exported content hash.
-  • Codex agents must use a non-interactive path: \`skill mirror export\`, patch
-    files, then \`skill mirror apply\`. In Codex, \`skill edit\` skips the editor
-    and prints the guarded apply command; \`--no-open\` does the same explicitly.
-  • Source stamps are local Git facts. They update the local canonical skill
-    file, then mirror to GrepRAG when GREPRAG_API_KEY is configured.`;
-function formatAdoptionLine(prefix, entry) {
-    return entry.reason
-        ? `  ${prefix} ${entry.scope}:${entry.skillName} — ${entry.reason}`
-        : `  ${prefix} ${entry.scope}:${entry.skillName}`;
-}
-function printAdoptionDryRun(platform, result) {
-    const plan = result.plan;
-    const candidateCount = plan.candidates.length;
-    const managedCount = plan.managed.length;
-    const blockedCount = plan.blocked.length;
-    const skippedCount = plan.skipped.length;
-    const ignoredCount = plan.ignoredRoots.reduce((sum, root) => sum + root.skillCount, 0);
-    console.log(`${platform}: adoption dry-run: ${candidateCount} candidate(s), ${managedCount} managed, ${blockedCount} blocked, ${skippedCount} skipped, ${ignoredCount} ignored in unowned roots`);
-    for (const candidate of plan.candidates)
-        console.log(formatAdoptionLine('adopt', candidate));
-    for (const blocked of plan.blocked)
-        console.log(formatAdoptionLine('block', blocked));
-    for (const skipped of plan.skipped)
-        console.log(formatAdoptionLine('skip ', skipped));
-    for (const root of plan.ignoredRoots) {
-        console.log(`  ignore ${root.skillCount} skill(s) under ${root.root} — ${root.reason}`);
+REMOVED
+  skill edit, skill mirror apply, skill mirror snapshot promote|create,
+  and skill revert refuse: they wrote the mirror, which is
+  now read only. Use git (git log, git diff, git revert) on the skill folder.`;
+/** The current repo's own copy of a skill, if it has one. */
+function projectSkillDir(skill) {
+    for (const source of (0, skill_git_ingest_1.gitSkillSources)(process.cwd())) {
+        if (source.scope !== 'project')
+            continue;
+        const dir = path.join(source.repo, ...source.prefix.split('/'), skill);
+        if (fs.existsSync(path.join(dir, 'SKILL.md')))
+            return { dir, projectName: source.projectName };
     }
-}
-function printAdoptionSync(platform, result) {
-    const candidateCount = result.plan.candidates.length;
-    if (!candidateCount && !result.blocked && !result.skipped)
-        return;
-    console.log(`${platform}: native skill adoption: ${result.adopted}/${candidateCount} adopted, ${result.blocked} blocked, ${result.skipped} skipped`);
+    return null;
+}
+/** The folder holding a skill's one true copy: this repo's, else the global one. */
+function gitSkillDir(skill) {
+    const project = projectSkillDir(skill);
+    if (project)
+        return project.dir;
+    const global = path.join(os.homedir(), '.claude', 'skills', skill);
+    return fs.existsSync(path.join(global, 'SKILL.md')) ? global : null;
+}
+/** Where a skill's one true copy lives, for refusal text. */
+function gitSkillLocation(skill) {
+    if (skill_landing_1.BUNDLED_SKILLS.includes(skill))
+        return `packages/cli/skill/${skill}/ in the greprag repo`;
+    const project = projectSkillDir(skill);
+    if (project)
+        return `${project.dir} (the ${project.projectName || 'project'} repo)`;
+    return `${path.join(os.homedir(), '.claude', 'skills', skill)} (the dotclaude repo)`;
+}
+function refuseMirrorWrite(command, skill) {
+    const where = skill && !skill.startsWith('-') ? gitSkillLocation(skill) : 'the skill\'s git folder';
+    throw new Error(`Refusing \`greprag skill ${command}\`: the GrepRAG skill mirror is read only; git owns the skill. `
+        + `Edit ${where}, commit, then run \`greprag skill mirror sync\` (session start runs it too). `
+        + 'History and rollback are git log / git revert on that folder.');
 }
 function bundleRoot() {
     // Same resolution as init.ts Step 6 + postinstall.js
@@ -183,16 +164,6 @@ function getArg(args, name) {
     const idx = args.indexOf(name);
     return idx >= 0 ? args[idx + 1] : undefined;
 }
-function getMany(args, name) {
-    const out = [];
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === name && args[i + 1]) {
-            out.push(args[i + 1]);
-            i++;
-        }
-    }
-    return out;
-}
 function mirrorApiConfig() {
     const apiKey = process.env.GREPRAG_API_KEY || '';
     if (!apiKey)
@@ -234,18 +205,6 @@ function mirrorLookupQuery(args) {
     const qs = params.toString();
     return qs ? `?${qs}` : '';
 }
-function mirrorBodyScope(args) {
-    const scope = getArg(args, '--scope');
-    const projectId = getArg(args, '--project-id') || getArg(args, '--projectId');
-    const projectName = getArg(args, '--project-name') || getArg(args, '--projectName');
-    const replaces = getMany(args, '--replaces');
-    return {
-        ...(scope ? { scope } : {}),
-        ...(projectId ? { projectId } : {}),
-        ...(projectName ? { projectName } : {}),
-        ...(replaces.length ? { replaces } : {}),
-    };
-}
 function validMirrorRelPath(relative) {
     return /^(?!\.{1,2}(\/|$))[A-Za-z0-9._\/-]{1,200}\.md$/.test(relative) && !relative.includes('..');
 }
@@ -288,12 +247,6 @@ function listMarkdownFiles(root) {
     walk(root, '');
     return out;
 }
-function collectSkillPackageOrThrow(root) {
-    const files = (0, skill_mirror_client_1.collectSkillFiles)(path.resolve(root));
-    if (!files)
-        throw new Error(`No valid SKILL.md package found at ${path.resolve(root)}.`);
-    return files;
-}
 function fileMap(files) {
     return new Map(files.map(file => [file.path, file.content]));
 }
@@ -311,38 +264,6 @@ function diffSkillPackages(before, after) {
     }
     return diff;
 }
-function printSkillPackageDiff(label, diff) {
-    if (!diff.length) {
-        console.log(`${label}: no markdown changes`);
-        return;
-    }
-    console.log(`${label}:`);
-    for (const item of diff)
-        console.log(`  ${item.status.padEnd(7)} ${item.path}`);
-}
-function shellArg(value) {
-    return /^[A-Za-z0-9._:\/\\-]+$/.test(value)
-        ? value
-        : `"${value.replace(/(["\\$`])/g, '\\$1')}"`;
-}
-function forwardedMirrorArgs(args) {
-    const forwarded = new Set([
-        '--skill-id', '--skillId',
-        '--scope',
-        '--project-id', '--projectId',
-        '--project-name', '--projectName',
-        '--replaces',
-    ]);
-    const parts = [];
-    for (let i = 1; i < args.length; i++) {
-        const arg = args[i];
-        if (!forwarded.has(arg) || !args[i + 1])
-            continue;
-        parts.push(arg, shellArg(args[i + 1]));
-        i++;
-    }
-    return parts.join(' ');
-}
 /** Returns whether it wrote: under `check` it only lists the plan, so a caller reports success only on true. */
 function writeSkillPackage(targetDir, files, opts) {
     const target = path.resolve(targetDir);
@@ -368,26 +289,20 @@ function writeSkillPackage(targetDir, files, opts) {
     for (const file of files) {
         const destination = safePackagePath(target, file.path);
         fs.mkdirSync(path.dirname(destination), { recursive: true });
-        fs.writeFileSync(destination, file.content.endsWith('\n') ? file.content : file.content + '\n', 'utf8');
+        fs.writeFileSync(destination, file.content, 'utf8');
     }
     return true;
 }
-function printSkillMirrorConflict(params) {
-    const local = new Map(params.localFiles.map(file => [file.path, file.content]));
-    const remote = new Map(params.remoteFiles.map(file => [file.path, file.content]));
-    const paths = [...new Set([...local.keys(), ...remote.keys()])].sort();
-    console.error(`Conflict: ${params.skill} mirror changed since export.`);
-    console.error(`  expected: ${params.expectedHash}`);
-    console.error(`  current:  ${params.currentHash}`);
-    for (const relative of paths) {
-        const status = !local.has(relative) ? 'remote-only'
-            : !remote.has(relative) ? 'local-only'
-                : local.get(relative) === remote.get(relative) ? 'same'
-                    : 'changed';
-        if (status !== 'same')
-            console.error(`  ${status.padEnd(11)} ${relative}`);
-    }
-    console.error(`Export current mirror: greprag skill mirror export ${params.skill} --to <dir> --force`);
+/** Read the folder back and fail unless it holds exactly the files the mirror
+ *  sent, byte for byte. Catches a partial write and any file the package
+ *  reader would skip (size or count limits). */
+function verifyWrittenPackage(targetDir, files) {
+    const written = (0, skill_mirror_client_1.collectSkillFiles)(path.resolve(targetDir)) || [];
+    const diff = diffSkillPackages(files, written);
+    if (!diff.length)
+        return;
+    const detail = diff.map(item => `  ${item.status === 'removed' ? 'missing' : item.status} ${item.path}`).join('\n');
+    throw new Error(`export did not write the revision it fetched to ${path.resolve(targetDir)}:\n${detail}`);
 }
 async function runSkillMirrorExport(args) {
     const name = args[0];
@@ -401,142 +316,8 @@ async function runSkillMirrorExport(args) {
         throw new Error(`No mirrored files returned for ${name}.`);
     if (!writeSkillPackage(to, files, { force: args.includes('--force'), check: args.includes('--check'), exact: true }))
         return;
-    console.log(`Exported ${name} revision ${Number(data.revision || 0)} (${String(data.contentHash || '')})`);
-}
-async function loadMirrorPackage(skill, args) {
-    const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}${mirrorLookupQuery(args)}`);
-    const files = (data.files || [])
-        .filter((file) => typeof file.path === 'string' && typeof file.content === 'string');
-    if (!files.length)
-        throw new Error(`No mirrored files returned for ${skill}.`);
-    return {
-        files,
-        revision: Number(data.revision || 0),
-        contentHash: typeof data.contentHash === 'string' ? data.contentHash : (0, skill_mirror_client_1.computeMirrorHash)(files),
-    };
-}
-function editorCommand() {
-    return process.env.GREPRAG_EDITOR
-        || process.env.VISUAL
-        || process.env.EDITOR
-        || (process.platform === 'win32' ? 'notepad' : 'vi');
-}
-function codexHarnessDetected() {
-    return Boolean(process.env.CODEX_THREAD_ID || process.env.CODEX_CI || process.env.CODEX_SHELL);
-}
-function runEditor(target) {
-    const editor = editorCommand();
-    const result = (0, proc_1.safeSpawnSync)(editor, [target], { stdio: 'inherit', shell: true });
-    if (result.error)
-        throw new Error(`editor failed: ${result.error.message}`);
-    if (typeof result.status === 'number' && result.status !== 0) {
-        throw new Error(`editor exited with status ${result.status}`);
-    }
-}
-/** A skill the CLI ships as its own bundle has one canon, the bundle, and
- *  `greprag load` serves it for that skill's global id. A mirror write under
- *  its name would land in a row nothing reads. */
-function refuseBundledSkillWrite(skill) {
-    if (!(0, load_1.bundleOwnsSkill)(skill))
-        return;
-    throw new Error(`${skill} ships with the greprag CLI, so its canon is the bundle, not the skill mirror. Edit packages/cli/skill/${skill}/ in the greprag repo.`);
-}
-async function applySkillPackage(params) {
-    refuseBundledSkillWrite(params.skill);
-    const hash = (0, skill_mirror_client_1.computeMirrorHash)(params.files);
-    const body = {
-        files: params.files,
-        contentHash: hash,
-        ...mirrorBodyScope(params.args),
-        expectedHash: params.expectedHash,
-        ...(typeof params.expectedRevision === 'number' ? { expectedRevision: params.expectedRevision } : {}),
-    };
-    return mirrorApiJson('POST', `/v1/skillmirror/${encodeURIComponent(params.skill)}`, body);
-}
-async function assertCurrentMirrorHash(params) {
-    try {
-        const current = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(params.skill)}${mirrorLookupQuery(params.args)}`);
-        const currentHash = typeof current.contentHash === 'string' ? current.contentHash : '';
-        if (currentHash && currentHash !== params.expectedHash) {
-            const remoteFiles = (current.files || [])
-                .filter((file) => typeof file.path === 'string' && typeof file.content === 'string');
-            printSkillMirrorConflict({
-                skill: params.skill,
-                expectedHash: params.expectedHash,
-                currentHash,
-                localFiles: params.localFiles,
-                remoteFiles,
-            });
-            throw new Error('Refusing stale apply; re-export or merge against the current mirror.');
-        }
-    }
-    catch (err) {
-        if (!(err instanceof Error) || !/HTTP 404\b/.test(err.message))
-            throw err;
-    }
-}
-async function runSkillEdit(args) {
-    const skill = args[0];
-    if (!skill)
-        throw new Error('Usage: greprag skill edit <name> [--dir <dir>] [--no-open] [--force] [--keep]');
-    refuseBundledSkillWrite(skill);
-    const explicitDir = getArg(args, '--dir') || getArg(args, '--to');
-    const noOpen = args.includes('--no-open');
-    const keep = args.includes('--keep') || Boolean(explicitDir);
-    const workDir = explicitDir
-        ? path.resolve(explicitDir)
-        : fs.mkdtempSync(path.join(os.tmpdir(), `greprag-skill-edit-${skill}-`));
-    const loaded = await loadMirrorPackage(skill, args);
-    writeSkillPackage(workDir, loaded.files, {
-        force: args.includes('--force') || !explicitDir,
-        exact: true,
-    });
-    console.log(`Editing ${skill} revision ${loaded.revision} (${loaded.contentHash})`);
-    console.log(`Work dir: ${workDir}`);
-    const skipEditor = noOpen || codexHarnessDetected();
-    if (skipEditor) {
-        console.log(noOpen
-            ? 'Editor skipped.'
-            : 'Codex harness detected; editor skipped to avoid launching an interactive editor.');
-        const forward = forwardedMirrorArgs(args);
-        console.log(`Apply after editing: greprag skill mirror apply ${shellArg(workDir)} --skill ${skill}${forward ? ` ${forward}` : ''} --expected-hash ${loaded.contentHash}`);
-        return;
-    }
-    runEditor(path.join(workDir, 'SKILL.md'));
-    const edited = collectSkillPackageOrThrow(workDir);
-    const diff = diffSkillPackages(loaded.files, edited);
-    printSkillPackageDiff('Diff', diff);
-    if (!diff.length) {
-        if (!keep)
-            fs.rmSync(workDir, { recursive: true, force: true });
-        return;
-    }
-    await assertCurrentMirrorHash({ skill, expectedHash: loaded.contentHash, localFiles: edited, args });
-    const data = await applySkillPackage({ skill, files: edited, expectedHash: loaded.contentHash, args });
-    console.log(`Applied ${skill}: revision ${Number(data.revision || 0)} (${String(data.contentHash || (0, skill_mirror_client_1.computeMirrorHash)(edited))})`);
-    if (!keep)
-        fs.rmSync(workDir, { recursive: true, force: true });
-}
-async function runSkillMirrorApply(args) {
-    const dir = args[0];
-    const skill = getArg(args, '--skill') || (dir ? path.basename(path.resolve(dir)) : '');
-    if (!dir || !skill)
-        throw new Error('Usage: greprag skill mirror apply <dir> --skill <name> --expected-hash <hash>');
-    const expectedRevisionRaw = getArg(args, '--expected-revision') || getArg(args, '--expectedRevision');
-    const expectedHash = getArg(args, '--expected-hash') || getArg(args, '--expectedHash');
-    if (!expectedHash) {
-        throw new Error('Refusing unguarded apply; export first, then pass the exported --expected-hash <hash>.');
-    }
-    const files = collectSkillPackageOrThrow(dir);
-    await assertCurrentMirrorHash({ skill, expectedHash, localFiles: files, args });
-    const data = await applySkillPackage({
-        skill,
-        files,
-        expectedHash,
-        expectedRevision: expectedRevisionRaw ? Number(expectedRevisionRaw) : undefined,
-        args,
-    });
-    console.log(`Applied ${skill}: revision ${Number(data.revision || 0)} (${String(data.contentHash || (0, skill_mirror_client_1.computeMirrorHash)(files))})`);
+    verifyWrittenPackage(to, files);
+    console.log(`Exported ${name} revision ${Number(data.revision || 0)} (${String(data.contentHash || '')}) — a read-only copy; edit ${gitSkillLocation(name)} instead.`);
 }
 function snapshotNameArg(args) {
     const explicit = getArg(args, '--name');
@@ -561,9 +342,10 @@ async function runSkillMirrorSnapshot(args) {
     const verb = args[0];
     const skill = args[1];
     const rest = args.slice(2);
-    if (!verb || !skill) {
-        throw new Error('Usage: greprag skill mirror snapshot create|list|show|restore|promote <skill> [--name <snapshot>]');
-    }
+    if (verb === 'promote' || verb === 'create')
+        refuseMirrorWrite(`mirror snapshot ${verb}`, skill);
+    if (!verb || !skill)
+        throw new Error('Usage: greprag skill mirror snapshot list|show|restore <skill> [--name <snapshot>]');
     if (verb === 'list') {
         const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}/snapshots${mirrorLookupQuery(rest)}`);
         const snapshots = data.snapshots || [];
@@ -579,17 +361,6 @@ async function runSkillMirrorSnapshot(args) {
     const name = snapshotNameArg(rest);
     if (!name)
         throw new Error(`Usage: greprag skill mirror snapshot ${verb} <skill> --name <snapshot>`);
-    if (verb === 'create') {
-        const body = {
-            ...mirrorBodyScope(rest),
-            reason: getArg(rest, '--reason'),
-            force: rest.includes('--force'),
-        };
-        const data = await mirrorApiJson('POST', `/v1/skillmirror/${encodeURIComponent(skill)}/snapshots/${encodeURIComponent(name)}`, body);
-        const snap = data.snapshot;
-        console.log(`Snapshot ${String(snap.snapshotName || name)} stored for ${skill}: revision ${Number(snap.revision || 0)}`);
-        return;
-    }
     const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}/snapshots/${encodeURIComponent(name)}${mirrorLookupQuery(rest)}`);
     const snapshot = data.snapshot;
     if (verb === 'show') {
@@ -610,30 +381,140 @@ async function runSkillMirrorSnapshot(args) {
         const files = snapshotPresentFiles(snapshot);
         if (!writeSkillPackage(to, files, { force: rest.includes('--force'), check: rest.includes('--check'), exact: true }))
             return;
-        console.log(`Restored snapshot ${name} for ${skill} to ${path.resolve(to)}. Run apply with the expected revision if this should become canon.`);
+        console.log(`Restored snapshot ${name} for ${skill} to ${path.resolve(to)}. To make it current, copy what you need into ${gitSkillLocation(skill)} and commit.`);
         return;
     }
-    if (verb === 'promote') {
-        const expectedHash = getArg(rest, '--expected-hash') || getArg(rest, '--expectedHash');
-        if (!expectedHash) {
-            throw new Error('Usage: greprag skill mirror snapshot promote <skill> --name <snapshot> --expected-hash <current-live-hash>');
+    throw new Error('Usage: greprag skill mirror snapshot list|show|restore <skill> [--name <snapshot>]');
+}
+async function runSkillMirrorSync(args) {
+    if (args.includes('--cutover-lifecycle') || args.some(arg => arg === '--only' || arg.startsWith('--only='))) {
+        throw new Error('Claude Code reads skills from their git folders directly; there are no Claude Code adapters to install.');
+    }
+    const requested = args.find(arg => !arg.startsWith('-')) || 'all';
+    if (requested === 'claude-code') {
+        console.log('claude-code: no adapters; Claude Code reads ~/.claude/skills and <repo>/.claude/skills from git.');
+    }
+    const platforms = requested === 'all' || requested === 'claude-code'
+        ? [...native_skill_mirror_1.NATIVE_SKILL_ADAPTER_PLATFORMS]
+        : native_skill_mirror_1.NATIVE_SKILL_ADAPTER_PLATFORMS.includes(requested)
+            ? [requested]
+            : [];
+    if (!platforms.length)
+        throw new Error('Harness must be codex, opencode, claude-code or all.');
+    const { apiUrl, apiKey } = mirrorApiConfig();
+    const sources = (0, skill_git_ingest_1.gitSkillSources)(process.cwd());
+    const projectId = sources.find(source => source.scope === 'project')?.projectId;
+    if (args.includes('--dry-run')) {
+        for (const source of sources)
+            console.log(`would ingest committed skills from ${source.repo} ${source.prefix}/ (${source.scope})`);
+        return;
+    }
+    const hashes = await (0, skill_git_ingest_1.fetchMirrorHashes)(apiUrl, apiKey, projectId);
+    const ingest = await (0, skill_git_ingest_1.ingestCommittedSkills)({ apiUrl, apiKey, sources, mirrorHashes: hashes, force: args.includes('--force') });
+    console.log(`mirror: ${ingest.uploaded.length} skill(s) ingested from git${ingest.uploaded.length ? ` (${ingest.uploaded.join(', ')})` : ''}, ${ingest.current} current`);
+    for (const failure of ingest.failed)
+        console.error(`mirror: ${failure.name} failed — ${failure.error}`);
+    if (requested === 'claude-code')
+        return;
+    const anchor = (0, project_anchor_1.readAnchor)(process.cwd());
+    for (const platform of platforms) {
+        const result = await (0, native_skill_mirror_1.syncNativeSkillMirror)({
+            platform, apiUrl, apiKey,
+            projectId: anchor.projectId,
+            projectDir: process.cwd(),
+        });
+        console.log(`${platform}: ${(0, native_skill_mirror_1.nativeSkillMirrorSummary)(result)}`);
+    }
+    console.log('Restart open Codex/OpenCode sessions to refresh their native skill manifest.');
+}
+// ---------- Revision history: history / diff (read only) ------------------------
+// adr: adr/skill-revision-history.md
+function revisionArg(raw, label) {
+    const value = Number(String(raw || '').replace(/^r/i, ''));
+    if (!raw || !Number.isInteger(value) || value < 0)
+        throw new Error(`${label} must be a revision number such as 12 or r12`);
+    return value;
+}
+function positionals(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith('--')) {
+            if (args[i + 1] && !args[i + 1].startsWith('--'))
+                i++;
+            continue;
         }
-        const files = snapshotPresentFiles(snapshot);
-        if (!files.some(file => file.path === 'SKILL.md')) {
-            throw new Error(`Snapshot ${name} for ${skill} has no present SKILL.md file.`);
+        out.push(args[i]);
+    }
+    return out;
+}
+function authorLabel(author) {
+    if (!author)
+        return '';
+    const parts = [
+        typeof author.harness === 'string' ? author.harness : '',
+        typeof author.sessionId === 'string' ? author.sessionId.slice(0, 8) : '',
+        typeof author.chip === 'string' ? author.chip : '',
+    ].filter(Boolean);
+    const via = typeof author.via === 'string' ? author.via : '';
+    return [via, parts.join(' ')].filter(Boolean).join(' · ');
+}
+async function runSkillHistory(args) {
+    const skill = args[0];
+    if (!skill)
+        throw new Error('Usage: greprag skill history <name> [--skill-id <id>] [--limit <n>]');
+    const limit = getArg(args, '--limit');
+    const qs = mirrorLookupQuery(args);
+    const sep = qs ? '&' : '?';
+    const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}/history${qs}${limit ? `${sep}limit=${encodeURIComponent(limit)}` : ''}`);
+    const revisions = data.revisions || [];
+    if (!revisions.length) {
+        console.log(`No recorded revisions for ${skill}.`);
+        return;
+    }
+    console.log(`${skill} (${String(data.skillId || '')}) — newest first`);
+    console.log(`current: r${String(revisions[0].revision)} ${String(revisions[0].contentHash || '')}`);
+    for (const r of revisions) {
+        const date = String(r.createdAt || '').replace('T', ' ').slice(0, 16);
+        console.log('');
+        console.log(`r${String(r.revision).padEnd(4)} ${date}  ${String(r.kind).padEnd(8)} ${authorLabel(r.author)}`);
+        console.log(`      ${String(r.reason || '')}`);
+        const labels = r.labels || [];
+        if (labels.length)
+            console.log(`      snapshots: ${labels.join(', ')}`);
+        if (typeof r.revertedFrom === 'number')
+            console.log(`      bytes of r${r.revertedFrom}`);
+        const changes = r.changes || [];
+        if (r.comparedTo === null || r.comparedTo === undefined) {
+            console.log(`      first recorded revision (${Number(r.fileCount || 0)} files)`);
         }
-        const diff = diffSkillPackages([], files);
-        if (rest.includes('--check')) {
-            console.log(`Would promote snapshot ${name} for ${skill} with expected hash ${expectedHash}.`);
-            printSkillPackageDiff('Snapshot files', diff);
-            return;
+        else if (!changes.length) {
+            console.log(`      no file changes vs r${String(r.comparedTo)}`);
         }
-        await assertCurrentMirrorHash({ skill, expectedHash, localFiles: files, args: rest });
-        const data = await applySkillPackage({ skill, files, expectedHash, args: rest });
-        console.log(`Promoted snapshot ${name} for ${skill}: revision ${Number(data.revision || 0)} (${String(data.contentHash || (0, skill_mirror_client_1.computeMirrorHash)(files))})`);
+        else {
+            const files = changes.map(c => `${String(c.status)} ${String(c.path)}`).join(', ');
+            console.log(`      +${Number(r.added || 0)} -${Number(r.removed || 0)} vs r${String(r.comparedTo)}: ${files}`);
+        }
+    }
+}
+async function runSkillDiff(args) {
+    const [skill, revA, revB] = positionals(args);
+    if (!skill || !revA)
+        throw new Error('Usage: greprag skill diff <name> <revA> [<revB>] [--skill-id <id>]');
+    const from = revisionArg(revA, 'revA');
+    const to = revB === undefined ? undefined : revisionArg(revB, 'revB');
+    const qs = mirrorLookupQuery(args);
+    const params = `${qs ? `${qs}&` : '?'}from=${from}${to === undefined ? '' : `&to=${to}`}`;
+    const data = await mirrorApiJson('GET', `/v1/skillmirror/${encodeURIComponent(skill)}/diff${params}`);
+    const files = data.files || [];
+    console.log(`${skill}: r${String(data.from)} → r${String(data.to)}`);
+    if (!files.length) {
+        console.log('No differences.');
         return;
     }
-    throw new Error('Usage: greprag skill mirror snapshot create|list|show|restore|promote <skill> [--name <snapshot>]');
+    for (const file of files) {
+        console.log('');
+        console.log(String(file.patch || `${String(file.status)} ${String(file.path)}`));
+    }
 }
 async function runSkill(args) {
     const sub = args[0];
@@ -644,7 +525,13 @@ async function runSkill(args) {
     const bundled = listBundled();
     switch (sub) {
         case 'edit':
-            await runSkillEdit(args.slice(1));
+        case 'revert':
+            refuseMirrorWrite(sub, args[1]);
+        case 'history':
+            await runSkillHistory(args.slice(1));
+            return;
+        case 'diff':
+            await runSkillDiff(args.slice(1));
             return;
         case 'mirror': {
             const mirrorVerb = args[1] || 'sync';
@@ -653,139 +540,40 @@ async function runSkill(args) {
                 return;
             }
             if (mirrorVerb === 'apply') {
-                await runSkillMirrorApply(args.slice(2));
-                return;
+                const skill = getArg(args, '--skill') || (args[2] ? path.basename(path.resolve(args[2])) : undefined);
+                refuseMirrorWrite('mirror apply', skill);
             }
             if (mirrorVerb === 'snapshot') {
                 await runSkillMirrorSnapshot(args.slice(2));
                 return;
             }
-            if (mirrorVerb !== 'sync') {
-                console.error('Usage: greprag skill mirror sync|export|apply|snapshot ...');
-                process.exit(1);
-            }
-            const dryRun = args.includes('--dry-run');
-            const claudeLifecycleCutover = args.includes('--cutover-lifecycle');
-            // `--only a,b` names the mirrored skills to materialize as claude-code
-            // adapters — the one command that closes an adapter gap the catalog and
-            // the SessionStart announce report, without arming a fleet-wide sweep.
-            const onlyNames = readOnlyNames(args.slice(2));
-            const positional = args.slice(2).filter((arg, index, all) => !arg.startsWith('-') && all[index - 1] !== '--only');
-            const requested = positional[0] || 'all';
-            const platforms = requested === 'all'
-                ? [...native_skill_mirror_1.NATIVE_SKILL_ADAPTER_PLATFORMS]
-                : ['claude-code', 'codex', 'opencode'].includes(requested)
-                    ? [requested]
-                    : [];
-            if (platforms.length === 0) {
-                console.error('Harness must be claude-code, codex, opencode, or all.');
-                process.exit(1);
-            }
-            if (claudeLifecycleCutover && requested !== 'claude-code') {
-                throw new Error('--cutover-lifecycle requires harness claude-code.');
-            }
-            if (onlyNames.length > 0 && requested !== 'claude-code') {
-                throw new Error('--only requires harness claude-code.');
-            }
-            const claudeTargeted = claudeLifecycleCutover || onlyNames.length > 0;
-            const apiUrl = process.env.GREPRAG_API_URL || 'https://api.greprag.com';
-            const anchor = (0, project_anchor_1.readAnchor)(process.cwd());
-            if (requested === 'all') {
-                console.log('claude-code: native skill adapter sync disabled until Claude cutover approval.');
-            }
-            for (const platform of platforms) {
-                if (platform === 'claude-code' && claudeTargeted) {
-                    const names = onlyNames.length > 0 ? onlyNames : [...claude_lifecycle_cutover_1.CLAUDE_LIFECYCLE_SKILLS];
-                    if (dryRun) {
-                        console.log(`claude-code: targeted cutover would manage only ${names.join(', ')}; companion files remain untouched.`);
-                        continue;
-                    }
-                    const apiKey = process.env.GREPRAG_API_KEY || '';
-                    if (!apiKey)
-                        throw new Error('GREPRAG_API_KEY not set — run `greprag init` first.');
-                    const result = await (0, claude_lifecycle_cutover_1.syncClaudeLifecycleCutover)({ apiUrl, apiKey, names });
-                    const active = result.installed + result.updated + result.current;
-                    console.log(`claude-code: ${active} adapter(s) active (${names.join(', ')}); all other Claude skills remain unmanaged.`);
-                    if (result.backupDir)
-                        console.log(`claude-code: replaced prompts backed up at ${result.backupDir}`);
-                    continue;
-                }
-                if (!(0, native_skill_mirror_1.nativeSkillMirrorEnabled)(platform)) {
-                    console.log(`${platform}: native skill adapter sync disabled until Claude cutover approval.`);
-                    continue;
-                }
-                if (dryRun) {
-                    printAdoptionDryRun(platform, {
-                        plan: (0, skill_mirror_client_1.dryRunNativeSkillAdoption)({
-                            platform,
-                            projectId: anchor.projectId,
-                            projectName: anchor.projectName,
-                            projectDir: process.cwd(),
-                        }),
-                        adopted: 0,
-                        blocked: 0,
-                        skipped: 0,
-                    });
-                    continue;
-                }
-                const apiKey = process.env.GREPRAG_API_KEY || '';
-                if (!apiKey)
-                    throw new Error('GREPRAG_API_KEY not set — run `greprag init` first.');
-                const adoption = await (0, skill_mirror_client_1.syncNativeSkillAdoptions)({
-                    platform, apiUrl, apiKey,
-                    projectId: anchor.projectId,
-                    projectName: anchor.projectName,
-                    projectDir: process.cwd(),
-                });
-                printAdoptionSync(platform, adoption);
-                const result = await (0, native_skill_mirror_1.syncNativeSkillMirror)({
-                    platform, apiUrl, apiKey,
-                    projectId: anchor.projectId,
-                    projectDir: process.cwd(),
-                });
-                console.log(`${platform}: ${(0, native_skill_mirror_1.nativeSkillMirrorSummary)(result)}`);
-            }
-            if (!dryRun)
-                console.log('Restart open harness sessions to refresh their native skill manifest.');
+            if (mirrorVerb !== 'sync')
+                throw new Error('Usage: greprag skill mirror sync|export|snapshot ...');
+            await runSkillMirrorSync(args.slice(2));
             return;
         }
         case 'source': {
-            if (args[1] !== 'stamp') {
-                console.error('Usage: greprag skill source stamp <name> --project <p> --path <rel> [--path <rel>...] [--root <dir>] [--baseline <ref>]');
-                process.exit(1);
-            }
+            const usage = 'Usage: greprag skill source stamp <name> --project <p> --path <rel> [--path <rel>...] [--root <dir>] [--baseline <ref>]';
             const name = args[2];
             const rest = args.slice(3);
             const project = getArg(rest, '--project');
-            const paths = getMany(rest, '--path');
-            if (!name || !project || paths.length === 0) {
-                console.error('Usage: greprag skill source stamp <name> --project <p> --path <rel> [--path <rel>...] [--root <dir>] [--baseline <ref>]');
-                process.exit(1);
-            }
-            const homeDir = process.env.HOME || process.env.USERPROFILE || '';
-            const skillDir = (0, skill_landing_1.resolveSkillDir)(name, process.cwd(), homeDir);
+            const paths = rest.flatMap((arg, i) => (arg === '--path' && rest[i + 1] ? [rest[i + 1]] : []));
+            if (args[1] !== 'stamp' || !name || !project || paths.length === 0)
+                throw new Error(usage);
+            const skillDir = gitSkillDir(name);
             if (!skillDir)
-                throw new Error(`No local canonical skill found for ${name}.`);
+                throw new Error(`No git folder with a SKILL.md found for ${name}; looked at ${gitSkillLocation(name)}.`);
             const root = getArg(rest, '--root') || (0, skill_staleness_1.resolveSourceRoot)(project, process.cwd());
             if (!root)
                 throw new Error(`No local Git checkout found for source project ${project}.`);
             const skillPath = path.join(skillDir, 'SKILL.md');
-            const before = fs.readFileSync(skillPath, 'utf-8');
             const stamped = (0, skill_staleness_1.stampSourceBinding)({
-                skillMd: before, project, root, paths,
+                skillMd: fs.readFileSync(skillPath, 'utf-8'), project, root, paths,
                 baselineCommit: getArg(rest, '--baseline'),
             });
             fs.writeFileSync(skillPath, stamped.content.endsWith('\n') ? stamped.content : stamped.content + '\n');
-            console.log(`Stamped ${name}: ${project} @ ${stamped.binding.baselineCommit.slice(0, 8)} (${stamped.binding.paths.length} paths)`);
-            const apiKey = process.env.GREPRAG_API_KEY || '';
-            if (apiKey) {
-                const apiUrl = process.env.GREPRAG_API_URL || 'https://api.greprag.com';
-                const outcome = await (0, skill_mirror_client_1.maybeMirrorSkill)({ skill: name, cwd: process.cwd(), apiUrl, apiKey });
-                console.log(`Mirror: ${outcome}`);
-            }
-            else {
-                console.log('Mirror: skipped (GREPRAG_API_KEY not set; next skill use will retry).');
-            }
+            console.log(`Stamped ${name}: ${project} @ ${stamped.binding.baselineCommit.slice(0, 8)} (${stamped.binding.paths.length} paths) in ${skillPath}`);
+            console.log('Commit it; the mirror picks it up at the next session start or `greprag skill mirror sync`.');
             return;
         }
         case 'list': {