skillshop 2.0.0 → 2.2.0

package/src/legacy-cli.js

@@ -0,0 +1,1822 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import {
+  AgentsInstructionsError,
+  applyInstructions,
+  applyLocalFragments,
+  applyProjectInstructions,
+  composeAgentsInstructions,
+  hasProjectInstructions
+} from './agents-instructions.js';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const skillsContentRoot = path.join(packageRoot, 'skills-content');
+const agentsContentRoot = path.join(packageRoot, 'agents-content');
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+const lockFileName = '.skillshop-lock';
+const legacyLockFileName = '.skillz-lock';
+const registryFileName = 'repositories.json';
+const configFileName = 'config.json';
+const globalSkillsFileName = 'global-skills.json';
+const excludeBlockStart = '# >>> skillshop managed dependencies >>>';
+const excludeBlockEnd = '# <<< skillshop managed dependencies <<<';
+const legacyExcludeBlockStart = '# >>> skillz managed dependencies >>>';
+const legacyExcludeBlockEnd = '# <<< skillz managed dependencies <<<';
+const projectTemplateDirectory = path.join('.agents', 'instructions');
+const projectTemplateName = 'AGENTS.template.md';
+const defaultProjectTemplate = '# Project instructions\n\n{{ blocks }}\n';
+const internalUpgradeRefreshCommand = '__skillshop_upgrade_refresh';
+const internalUpgradeRefreshToken = 'skillshop-managed-upgrade-v1';
+const globalAgentsTargets = [
+  path.join('.codex', 'AGENTS.md'),
+  path.join('.agents', 'AGENTS.md'),
+  path.join('.copilot', 'copilot-instructions.md')
+];
+
+function lockPathFor(root) {
+  const current = path.join(root, lockFileName);
+  const legacy = path.join(root, legacyLockFileName);
+  return fs.existsSync(current) || !fs.existsSync(legacy) ? current : legacy;
+}
+
+function hasLock(root) {
+  return fs.existsSync(path.join(root, lockFileName)) || fs.existsSync(path.join(root, legacyLockFileName));
+}
+const agentOptions = [
+  { id: 'copilot', label: 'Copilot', local: '.github/skills', global: '.copilot/skills' },
+  { id: 'claude', label: 'Claude', local: '.claude/skills', global: '.claude/skills' },
+  { id: 'codex', label: 'Codex', local: '.agents/skills', global: '.agents/skills' },
+  { id: 'opencode', label: 'OpenCode', local: '.agents/skills', global: '.agents/skills' },
+  { id: 'others', label: 'Others', local: '.agents/skills', global: '.agents/skills' }
+];
+
+class CliError extends Error {}
+
+function unquote(value) {
+  const trimmed = value.trim();
+  const match = trimmed.match(/^(['"])(.*)\1$/);
+  return match ? match[2] : trimmed;
+}
+
+function validateSkillName(name) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name)) {
+    throw new CliError(`invalid skill name: ${name}`);
+  }
+}
+
+function skillMetadata(name) {
+  validateSkillName(name);
+  const sourceDir = path.join(skillsContentRoot, name);
+  const manifestPath = path.join(sourceDir, 'SKILL.md');
+
+  if (!fs.existsSync(manifestPath)) {
+    throw new CliError(`unknown skill: ${name}`);
+  }
+
+  const lines = fs.readFileSync(manifestPath, 'utf8').split(/\r?\n/);
+  if (lines[0] !== '---') {
+    throw new CliError(`${name}/SKILL.md has no front matter`);
+  }
+
+  const frontMatterEnd = lines.indexOf('---', 1);
+  const frontMatter = lines.slice(1, frontMatterEnd === -1 ? lines.length : frontMatterEnd);
+  const metadataStart = frontMatter.findIndex((line) => /^metadata:\s*$/.test(line));
+  let author;
+  let version;
+
+  if (metadataStart !== -1) {
+    for (const line of frontMatter.slice(metadataStart + 1)) {
+      if (line !== '' && !/^\s+/.test(line)) break;
+      const authorMatch = line.match(/^\s+author:\s*(.+)$/);
+      const versionMatch = line.match(/^\s+version:\s*(.+)$/);
+      if (authorMatch) author = unquote(authorMatch[1]);
+      if (versionMatch) version = unquote(versionMatch[1]);
+    }
+  }
+
+  if (!author || !version) {
+    throw new CliError(`${name}/SKILL.md must declare metadata.author and metadata.version`);
+  }
+
+  return { name, author, version, sourceDir };
+}
+
+function availableSkills() {
+  return fs.readdirSync(skillsContentRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => fs.existsSync(path.join(skillsContentRoot, name, 'SKILL.md')))
+    .sort();
+}
+
+function printHelp() {
+  console.log(`Usage:
+  skillshop init
+  skillshop config agents
+  skillshop agents init [--project <directory>]
+  skillshop agents [--project <directory>] [--check]
+  skillshop agents --global
+  skillshop <name> [--version <version>] [--global]
+  skillshop install <name> [--version <version>] [--global]
+  skillshop uninstall <name> [--global]
+  skillshop upgrade
+  skillshop update [name]
+  skillshop update --push
+  skillshop migrate [root ...]
+  skillshop list
+
+Install, uninstall, and update skills from the local registry.
+
+Agent instructions:
+  skillshop agents init creates a neutral .agents/instructions/AGENTS.template.md and renders it into a separate managed region in the project-root AGENTS.md. Existing text and prior managed guidance are preserved. Edit the template and sibling *.block.md sources, not the generated region.
+  Plain skillshop agents keeps the bounded bundled behavior until project sources exist; afterward it renders project sources. Missing sources in an initialized project are errors.
+  skillshop agents --check reports whether generated output is current and never writes. skillshop agents --global retains user-level instruction updates.
+  The default boundary is the nearest Git/worktree root, or the current directory outside Git. --project selects another directory relative to the current working directory. Nested projects need an explicit selection.
+  Source, block, template, and output paths containing symlink components, including dangling links, are rejected.
+  Templates accept {{ include "name.block.md" }}, {{ include 'name.block.md' }}, legacy {{ fragments["name.block.md"] }}, and {{ blocks }} for unreferenced blocks. Inserted block text is literal.
+
+Upgrade:
+  skillshop upgrade updates the npm installation that supplied the CLI, then refreshes recorded Skillshop-managed copies with the newly installed CLI. skillshop init is optional and upgrade does not generate AGENTS.md files.
+
+Options:
+  -g, --global             Use configured system skill directories without a project lockfile
+      --project <directory> Select the agents boundary relative to the current directory
+      --check               Check project-generated instructions without writing
+      --push               Update every registered repository
+  -v, --version <version>  Require an exact skill version
+  -h, --help               Show this help
+
+Conveniences:
+  skillshop i <name>          Alias for install
+  skillshop add <name>        Alias for install
+  skillshop rm <name>         Alias for uninstall
+  skillshop <name>@<version>  Install an exact version
+
+Available skills:
+  ${availableSkills().join('\n  ')}`);
+}
+
+function skillshopHome() {
+  if (process.env.SKILLSHOP_HOME) return process.env.SKILLSHOP_HOME;
+  if (process.env.SKILLZ_HOME) return process.env.SKILLZ_HOME;
+  const current = path.join(os.homedir(), '.skillshop');
+  const legacy = path.join(os.homedir(), '.skillz');
+  return fs.existsSync(current) || !fs.existsSync(legacy) ? current : legacy;
+}
+
+function configPath() {
+  return path.join(skillshopHome(), configFileName);
+}
+
+function readConfig() {
+  const filePath = configPath();
+  if (!fs.existsSync(filePath)) return null;
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${filePath}: ${error.message}`);
+  }
+
+  const knownAgents = new Set(agentOptions.map(({ id }) => id));
+  if (
+    config?.configVersion !== 1 ||
+    !Array.isArray(config.agents) ||
+    config.agents.length === 0 ||
+    config.agents.some((agent) => typeof agent !== 'string' || !knownAgents.has(agent))
+  ) {
+    throw new CliError(`${filePath} is not a supported skillshop config`);
+  }
+
+  return config;
+}
+
+function writeConfig(agents) {
+  const filePath = configPath();
+  const config = { configVersion: 1, agents: [...new Set(agents)] };
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}\n`);
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function configuredAgents(config) {
+  return config.agents.map((id) => agentOptions.find((option) => option.id === id));
+}
+
+function configuredSkillDirectories(config, scope, root = null) {
+  const base = scope === 'local' ? root : os.homedir();
+  return uniqueDestinations(configuredAgents(config).map((agent) => path.join(base, agent[scope])));
+}
+
+async function selectAgents() {
+  const terminal = createInterface({ input: process.stdin, output: process.stdout });
+  console.log('Which agents do you use? Select one or more:');
+  for (const [index, agent] of agentOptions.entries()) {
+    console.log(`  ${index + 1}. ${agent.label}`);
+  }
+  console.log('You can change this later with `skillshop config agents`.');
+
+  try {
+    while (true) {
+      if (process.stdin.readableEnded) throw new CliError('agent selection requires an answer');
+      let onEnd;
+      const inputEnded = new Promise((_, reject) => {
+        onEnd = () => reject(new CliError('agent selection requires an answer'));
+        process.stdin.once('end', onEnd);
+      });
+      let answer;
+      try {
+        answer = await Promise.race([
+          terminal.question('Enter numbers separated by commas: '),
+          inputEnded
+        ]);
+      } finally {
+        process.stdin.off('end', onEnd);
+      }
+      const indexes = answer.split(',').map((value) => Number(value.trim()) - 1);
+      if (
+        indexes.length > 0 &&
+        indexes.every((index) => Number.isInteger(index) && index >= 0 && index < agentOptions.length)
+      ) {
+        return [...new Set(indexes.map((index) => agentOptions[index].id))];
+      }
+      console.log(`Choose one or more numbers from 1 to ${agentOptions.length}.`);
+    }
+  } finally {
+    terminal.close();
+  }
+}
+
+async function configureAgents() {
+  const agents = await selectAgents();
+  writeConfig(agents);
+  const labels = configuredAgents({ agents }).map(({ label }) => label);
+  console.log(`Configured agents: ${labels.join(', ')}`);
+  console.log(`Wrote ${configPath()}`);
+}
+
+async function initialize() {
+  const config = readConfig();
+  if (!config) {
+    await configureAgents();
+    return;
+  }
+
+  console.log(`Agents already configured: ${configuredAgents(config).map(({ label }) => label).join(', ')}`);
+  console.log('Change this setting with `skillshop config agents`.');
+}
+
+function projectRoot(startDir, { required = true } = {}) {
+  let current = path.resolve(startDir);
+
+  while (true) {
+    if (fs.existsSync(path.join(current, '.git'))) return current;
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      if (!required) return null;
+      throw new CliError(`${path.resolve(startDir)} is not inside a Git repository`);
+    }
+    current = parent;
+  }
+}
+
+function directoriesToRoot(startDir, rootDir) {
+  const directories = [];
+  let current = path.resolve(startDir);
+
+  while (true) {
+    directories.push(current);
+    if (current === rootDir) return directories;
+
+    const parent = path.dirname(current);
+    if (parent === current) return [rootDir];
+    current = parent;
+  }
+}
+
+function findLockRoot(cwd, options) {
+  const root = projectRoot(cwd, options);
+  if (!root) return null;
+  return directoriesToRoot(cwd, root)
+    .find((directory) => hasLock(directory)) ?? null;
+}
+
+function resolveAgentDir(cwd) {
+  const root = projectRoot(cwd);
+  const directories = directoriesToRoot(cwd, root);
+
+  for (const agentDirName of ['.agents', '.github', '.codex']) {
+    for (const directory of directories) {
+      const candidate = path.join(directory, agentDirName);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+        return candidate;
+      }
+    }
+  }
+
+  return path.join(root, '.agents');
+}
+
+function emptyLock() {
+  return { lockfileVersion: 2, registry: 'local', skills: {} };
+}
+
+function readLock(root) {
+  const lockPath = lockPathFor(root);
+  if (!fs.existsSync(lockPath)) return emptyLock();
+
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${lockPath}: ${error.message}`);
+  }
+
+  if (![1, 2].includes(lock?.lockfileVersion) || lock.registry !== 'local' || !lock.skills || Array.isArray(lock.skills)) {
+    throw new CliError(`${lockPath} is not a supported skillshop lockfile`);
+  }
+
+  return lock;
+}
+
+function relativePath(root, target) {
+  return path.relative(root, target).split(path.sep).join('/');
+}
+
+function lockedTargets(root, name, entry) {
+  const paths = Array.isArray(entry?.paths) ? entry.paths : [entry?.path];
+  if (paths.length === 0 || paths.some((targetPath) => typeof targetPath !== 'string')) {
+    throw new CliError(`lock entry for ${name} has no install paths`);
+  }
+
+  return uniqueDestinations(paths.map((targetPath) => {
+    const target = path.resolve(root, targetPath);
+    const relative = path.relative(root, target);
+    if (relative === '' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new CliError(`lock entry for ${name} points outside the project`);
+    }
+    if (path.basename(target) !== name || path.basename(path.dirname(target)) !== 'skills') {
+      throw new CliError(`lock entry for ${name} is not a skills/${name} directory`);
+    }
+    assertLocalDestination(root, target, `lock entry for ${name}`);
+    return target;
+  }));
+}
+
+function inferredSkillDirectories(root, lock, cwd) {
+  const preferredName = lock.skills.skillshop ? 'skillshop' : lock.skills.skillz ? 'skillz' : Object.keys(lock.skills).sort()[0];
+  if (!preferredName) return [path.join(resolveAgentDir(cwd), 'skills')];
+  return lockedTargets(root, preferredName, lock.skills[preferredName]).map((target) => path.dirname(target));
+}
+
+function localSkillDirectories(root, lock, cwd) {
+  const config = readConfig();
+  const directories = config
+    ? configuredSkillDirectories(config, 'local', root)
+    : inferredSkillDirectories(root, lock, cwd);
+  for (const directory of directories) assertLocalDestination(root, directory, 'agent skill directory');
+  return directories;
+}
+
+function writeLock(root, lock) {
+  const skills = Object.fromEntries(
+    Object.entries(lock.skills)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, entry]) => [name, {
+        version: entry.version,
+        author: entry.author,
+        paths: lockedTargets(root, name, entry).map((target) => relativePath(root, target)).sort()
+      }])
+  );
+  const stableLock = { lockfileVersion: 2, registry: 'local', skills };
+  const lockPath = path.join(root, lockFileName);
+  const contents = `${JSON.stringify(stableLock, null, 2)}\n`;
+  if (fs.existsSync(lockPath) && fs.readFileSync(lockPath, 'utf8') === contents) return;
+  const temporaryPath = `${lockPath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, contents);
+  fs.renameSync(temporaryPath, lockPath);
+}
+
+function registryPath() {
+  return path.join(skillshopHome(), registryFileName);
+}
+
+function readRegistry() {
+  const filePath = registryPath();
+  if (!fs.existsSync(filePath)) return { registryVersion: 1, repositories: [] };
+
+  let registry;
+  try {
+    registry = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${filePath}: ${error.message}`);
+  }
+
+  if (
+    registry?.registryVersion !== 1 ||
+    !Array.isArray(registry.repositories) ||
+    registry.repositories.some((repository) => typeof repository !== 'string' || !path.isAbsolute(repository))
+  ) {
+    throw new CliError(`${filePath} is not a supported skillshop repository registry`);
+  }
+
+  return registry;
+}
+
+function canonicalPath(target) {
+  try {
+    return fs.realpathSync.native(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+function canonicalDestination(target) {
+  let existing = path.resolve(target);
+  const missing = [];
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return path.resolve(target);
+    missing.unshift(path.basename(existing));
+    existing = parent;
+  }
+  return path.join(canonicalPath(existing), ...missing);
+}
+
+function assertLocalDestination(root, target, label) {
+  const relative = path.relative(canonicalDestination(root), canonicalDestination(target));
+  if (relative === '' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside the project`);
+  }
+}
+
+function uniqueDestinations(targets) {
+  const seen = new Set();
+  return targets.filter((target) => {
+    const destination = canonicalDestination(target);
+    if (seen.has(destination)) return false;
+    seen.add(destination);
+    return true;
+  });
+}
+
+function staleTargets(previousTargets, targetDirs) {
+  const destinations = new Set(targetDirs.map(canonicalDestination));
+  return previousTargets.filter((target) => !destinations.has(canonicalDestination(target)));
+}
+
+function assertTargetsAvailable(name, targetDirs, previousTargets) {
+  const managedDestinations = new Set(previousTargets.map(canonicalDestination));
+  for (const targetDir of targetDirs) {
+    if (fs.existsSync(targetDir) && !managedDestinations.has(canonicalDestination(targetDir))) {
+      throw new CliError(`${targetDir} exists and is not managed as ${name} in ${lockFileName}`);
+    }
+  }
+}
+
+function writeRegistry(repositories) {
+  const filePath = registryPath();
+  const stableRegistry = {
+    registryVersion: 1,
+    repositories: [...new Set(repositories.map(canonicalPath))].sort()
+  };
+  const contents = `${JSON.stringify(stableRegistry, null, 2)}\n`;
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === contents) return;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, contents);
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function registerRepository(root) {
+  const registry = readRegistry();
+  writeRegistry([...registry.repositories, root]);
+}
+
+function gitOutput(root, args) {
+  try {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+  } catch (error) {
+    const detail = error.stderr?.trim();
+    throw new CliError(detail || `cannot inspect Git repository at ${root}`);
+  }
+}
+
+function managedGitPaths(root, lock) {
+  const gitRoot = canonicalPath(gitOutput(root, ['rev-parse', '--show-toplevel']));
+  const scope = relativePath(gitRoot, canonicalPath(root));
+  const scopedPath = (target) => relativePath(gitRoot, path.join(root, target));
+  const paths = [scopedPath(lockFileName)];
+  if (fs.existsSync(path.join(root, legacyLockFileName))) paths.push(scopedPath(legacyLockFileName));
+
+  for (const [name, entry] of Object.entries(lock.skills)) {
+    for (const target of lockedTargets(root, name, entry)) {
+      paths.push(scopedPath(relativePath(root, target)));
+    }
+  }
+
+  if (scope.startsWith('../') || path.isAbsolute(scope)) {
+    throw new CliError(`${root} is outside its Git repository`);
+  }
+
+  return { gitRoot, paths: [...new Set(paths)].sort() };
+}
+
+function gitExcludePattern(relative) {
+  const escaped = relative.replaceAll('\\', '\\\\').replace(/([ !#*?\[\]])/g, '\\$1');
+  return `/${escaped}${[lockFileName, legacyLockFileName].includes(path.posix.basename(relative)) ? '' : '/'}`;
+}
+
+function syncGitExclude(root, lock) {
+  const { paths } = managedGitPaths(root, lock);
+  const excludePathOutput = gitOutput(root, ['rev-parse', '--git-path', 'info/exclude']);
+  const excludePath = path.isAbsolute(excludePathOutput)
+    ? excludePathOutput
+    : path.resolve(root, excludePathOutput);
+  const existing = fs.existsSync(excludePath) ? fs.readFileSync(excludePath, 'utf8') : '';
+  const lines = existing.replace(/\r\n/g, '\n').split('\n');
+  const retained = [];
+  let insideBlock = false;
+
+  for (const line of lines) {
+    if (line === excludeBlockStart || line === legacyExcludeBlockStart) {
+      insideBlock = true;
+      continue;
+    }
+    if (line === excludeBlockEnd || line === legacyExcludeBlockEnd) {
+      insideBlock = false;
+      continue;
+    }
+    if (!insideBlock) retained.push(line);
+  }
+
+  while (retained.at(-1) === '') retained.pop();
+  const block = [excludeBlockStart, ...paths.map(gitExcludePattern), excludeBlockEnd];
+  const contents = `${[...retained, ...(retained.length ? [''] : []), ...block].join('\n')}\n`;
+  fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+  if (contents !== existing) fs.writeFileSync(excludePath, contents);
+}
+
+function untrackManagedPaths(root, lock) {
+  const { gitRoot, paths } = managedGitPaths(root, lock);
+  try {
+    execFileSync(
+      'git',
+      ['rm', '-r', '--cached', '-f', '--ignore-unmatch', '--', ...paths],
+      { cwd: gitRoot, stdio: 'ignore' }
+    );
+  } catch {
+    throw new CliError(`cannot remove managed skill dependencies from the Git index at ${gitRoot}`);
+  }
+}
+
+function maintainRepository(root, lock, { register = true, untrack = false } = {}) {
+  if (untrack) untrackManagedPaths(root, lock);
+  syncGitExclude(root, lock);
+  if (register) registerRepository(root);
+}
+
+function manifestParts(contents, label) {
+  const newline = contents.includes('\r\n') ? '\r\n' : '\n';
+  if (!contents.startsWith(`---${newline}`)) return { lines: [], body: contents, newline };
+  const end = contents.indexOf(`${newline}---`, 3);
+  if (end === -1 || !['', '\n', '\r'].includes(contents[end + newline.length + 3] ?? '')) {
+    throw new CliError(`${label} has unterminated front matter`);
+  }
+  return {
+    lines: contents.slice(3 + newline.length, end).split(newline),
+    body: contents.slice(end + newline.length + 3),
+    newline
+  };
+}
+
+function repairInstalledManifest(name, entry, manifestPath) {
+  const contents = fs.readFileSync(manifestPath, 'utf8');
+  const { lines, body, newline } = manifestParts(contents, manifestPath);
+  const sourcePath = path.join(skillsContentRoot, name, 'SKILL.md');
+  const sourceLines = fs.existsSync(sourcePath)
+    ? manifestParts(fs.readFileSync(sourcePath, 'utf8'), sourcePath).lines
+    : [];
+  const sourceField = (key) => sourceLines.find((line) => line.startsWith(`${key}:`))?.slice(key.length + 1).trim();
+  const setField = (key, value) => {
+    const index = lines.findIndex((line) => line.startsWith(`${key}:`));
+    const replacement = `${key}: ${value}`;
+    if (index === -1) lines.push(replacement);
+    else if (unquote(lines[index].slice(key.length + 1)) !== unquote(value)) lines[index] = replacement;
+  };
+  setField('name', JSON.stringify(name));
+  const description = lines.find((line) => line.startsWith('description:'))?.slice(12).trim();
+  if (!description || ['""', "''", 'null', '~'].includes(description)) {
+    const fallback = sourceField('description');
+    if (!fallback) throw new CliError(`cannot restore description for ${manifestPath}`);
+    setField('description', fallback);
+  }
+
+  let metadataIndex = lines.findIndex((line) => /^metadata:/.test(line));
+  if (metadataIndex === -1) {
+    metadataIndex = lines.length;
+    lines.push('metadata:');
+  } else if (!/^metadata:\s*(?:#.*)?$/.test(lines[metadataIndex])) {
+    throw new CliError(`${manifestPath} must use a metadata block mapping`);
+  }
+  let metadataEnd = metadataIndex + 1;
+  while (metadataEnd < lines.length && /^(\s|$|#)/.test(lines[metadataEnd])) metadataEnd += 1;
+  const indent = lines.slice(metadataIndex + 1, metadataEnd)
+    .find((line) => /^\s+\S/.test(line))?.match(/^\s+/)[0] ?? '  ';
+  const metadata = {};
+  for (const key of ['author', 'version']) {
+    const fieldPrefix = `${indent}${key}:`;
+    const index = lines.findIndex((line, i) => i > metadataIndex && i < metadataEnd && line.startsWith(fieldPrefix));
+    const installed = index === -1 ? null : unquote(lines[index].slice(fieldPrefix.length));
+    const source = sourceLines.find((line) => new RegExp(`^\\s+${key}:`).test(line));
+    const value = typeof entry[key] === 'string' && entry[key].trim()
+      ? entry[key]
+      : installed && !['null', '~'].includes(installed) ? installed
+        : source ? unquote(source.slice(source.indexOf(':') + 1)) : null;
+    if (!value) throw new CliError(`cannot restore metadata.${key} for ${manifestPath}`);
+    metadata[key] = value;
+    const replacement = `${fieldPrefix} ${JSON.stringify(value)}`;
+    if (index === -1) {
+      lines.splice(metadataEnd, 0, replacement);
+      metadataEnd += 1;
+    } else if (installed !== value) lines[index] = replacement;
+  }
+  const separator = body && !body.startsWith(newline) ? newline + newline : '';
+  return { contents: `---${newline}${lines.join(newline)}${newline}---${separator}${body}`, metadata };
+}
+
+function readGlobalSkills() {
+  const filePath = path.join(skillshopHome(), globalSkillsFileName);
+  if (!fs.existsSync(filePath)) return emptyLock();
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new CliError(`cannot parse ${filePath}: ${error.message}`);
+  }
+  if (lock?.lockfileVersion !== 2 || lock.registry !== 'local' || !lock.skills || Array.isArray(lock.skills)) {
+    throw new CliError(`${filePath} is not a supported skillshop global manifest`);
+  }
+  return lock;
+}
+
+function globalTargets(name, entry) {
+  validateSkillName(name);
+  if (!Array.isArray(entry?.paths) || !entry.paths.length) {
+    throw new CliError(`global entry for ${name} has no install paths`);
+  }
+  return uniqueDestinations(entry.paths.map((target) => {
+    if (typeof target !== 'string' || !path.isAbsolute(target) ||
+        path.basename(target) !== name || path.basename(path.dirname(target)) !== 'skills') {
+      throw new CliError(`global entry for ${name} is not an absolute skills/${name} directory`);
+    }
+    assertLocalDestination(os.homedir(), target, `global entry for ${name}`);
+    return target;
+  }));
+}
+
+function writeGlobalSkills(lock) {
+  const skills = Object.fromEntries(Object.entries(lock.skills).sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, entry]) => {
+      const paths = globalTargets(name, entry).sort();
+      return [name, { paths, copies: Object.fromEntries(paths.map((target) => [target, entry.copies?.[target] ?? {}])) }];
+    }));
+  const filePath = path.join(skillshopHome(), globalSkillsFileName);
+  const contents = `${JSON.stringify({ ...emptyLock(), skills }, null, 2)}\n`;
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === contents) return;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.tmp-${process.pid}`;
+  fs.writeFileSync(temporaryPath, contents);
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function repairTrackedSkills(root, lock) {
+  const repairs = [];
+  for (const [name, entry] of Object.entries(lock.skills)) {
+    validateSkillName(name);
+    const targets = (root ? lockedTargets(root, name, entry) : globalTargets(name, entry))
+      .filter((target) => fs.existsSync(path.join(target, 'SKILL.md')));
+    if (!targets.length) {
+      delete lock.skills[name];
+      continue;
+    }
+    for (const target of targets) {
+      const manifestPath = path.join(target, 'SKILL.md');
+      assertLocalDestination(root ?? os.homedir(), manifestPath, `manifest for ${name}`);
+      const installation = root ? entry : entry.copies?.[target] ?? {};
+      const repair = repairInstalledManifest(name, installation, manifestPath);
+      if (root) Object.assign(entry, repair.metadata);
+      else {
+        entry.copies ??= {};
+        entry.copies[target] = repair.metadata;
+      }
+      repairs.push({ manifestPath, contents: repair.contents });
+    }
+    entry.paths = targets.map((target) => root ? relativePath(root, target) : target);
+  }
+  for (const { manifestPath, contents } of repairs) {
+    if (fs.readFileSync(manifestPath, 'utf8') !== contents) fs.writeFileSync(manifestPath, contents);
+  }
+}
+
+function reconcileRepository(root, { register = true } = {}) {
+  const lock = readLock(root);
+  repairTrackedSkills(root, lock);
+  writeLock(root, lock);
+  maintainRepository(root, lock, { register });
+}
+
+function reconcileCurrentRepository() {
+  if (fs.existsSync(path.join(skillshopHome(), globalSkillsFileName))) {
+    const globalSkills = readGlobalSkills();
+    repairTrackedSkills(null, globalSkills);
+    writeGlobalSkills(globalSkills);
+  }
+  const root = findLockRoot(process.cwd(), { required: false });
+  if (root) reconcileRepository(root, { register: false });
+  const registryExists = fs.existsSync(registryPath());
+  if (!root && !registryExists) return;
+  const registry = readRegistry();
+  const repositories = registry.repositories.filter((directory) => hasLock(directory));
+  if (root) repositories.push(root);
+  writeRegistry(repositories);
+}
+
+function replaceSkillDirectory(sourceDir, targetDir) {
+  const temporaryDir = `${targetDir}.skillshop-tmp-${process.pid}`;
+  fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+  fs.rmSync(temporaryDir, { recursive: true, force: true });
+  fs.cpSync(sourceDir, temporaryDir, { recursive: true, force: true });
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  fs.renameSync(temporaryDir, targetDir);
+}
+
+function installAt(name, requestedVersion, targetDir) {
+  const metadata = skillMetadata(name);
+  if (requestedVersion && requestedVersion !== metadata.version) {
+    throw new CliError(
+      `${name}@${requestedVersion} is unavailable; local registry provides ${name}@${metadata.version}`
+    );
+  }
+
+  const updating = fs.existsSync(targetDir);
+  replaceSkillDirectory(metadata.sourceDir, targetDir);
+  return { ...metadata, targetDir, updating };
+}
+
+function lockEntry(root, results) {
+  const [result] = results;
+  return {
+    version: result.version,
+    author: result.author,
+    paths: results.map(({ targetDir }) => relativePath(root, targetDir)).sort()
+  };
+}
+
+function installGlobal(name, requestedVersion) {
+  const config = readConfig();
+  const skillDirectories = config
+    ? configuredSkillDirectories(config, 'global')
+    : [path.join(os.homedir(), '.agents', 'skills')];
+
+  const globalSkills = readGlobalSkills();
+  for (const skillDirectory of skillDirectories) {
+    const targetDir = path.join(skillDirectory, name);
+    assertLocalDestination(os.homedir(), targetDir, `global installation for ${name}`);
+    const result = installAt(name, requestedVersion, targetDir);
+    const entry = globalSkills.skills[name] ?? { paths: [], copies: {} };
+    entry.paths = [...new Set([...entry.paths, targetDir])];
+    entry.copies[targetDir] = { author: result.author, version: result.version };
+    globalSkills.skills[name] = entry;
+    writeGlobalSkills(globalSkills);
+    console.log(`${result.updating ? 'Updated' : 'Installed'} ${name}@${result.version} at ${targetDir}`);
+  }
+}
+
+function instructionProjectRoot(cwd, selectedProject) {
+  if (selectedProject) {
+    const selected = path.resolve(cwd, selectedProject);
+    let stats;
+    try {
+      stats = fs.statSync(selected);
+    } catch {
+      throw new CliError(`project directory does not exist: ${selected}`);
+    }
+    if (!stats.isDirectory()) throw new CliError(`project path is not a directory: ${selected}`);
+    return canonicalPath(selected);
+  }
+
+  return canonicalPath(projectRoot(cwd, { required: false }) ?? cwd);
+}
+
+function isWithinDirectory(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function nearestAgentsFile(cwd, root) {
+  const start = canonicalPath(cwd);
+  let directory = isWithinDirectory(root, start) ? start : root;
+  while (isWithinDirectory(root, directory)) {
+    const candidate = path.join(directory, 'AGENTS.md');
+    if (fs.existsSync(candidate)) return candidate;
+    if (directory === root) break;
+    directory = path.dirname(directory);
+  }
+  return path.join(root, 'AGENTS.md');
+}
+
+function assertLocalInstructionSources(root, contentDirectory) {
+  assertNoInstructionSymlink(root, contentDirectory, 'local instruction source directory');
+  if (!fs.existsSync(contentDirectory)) return;
+  for (const entry of fs.readdirSync(contentDirectory, { withFileTypes: true })) {
+    if (entry.name.endsWith('.block.md')) {
+      const sourcePath = path.join(contentDirectory, entry.name);
+      const label = `local instruction source ${entry.name}`;
+      assertLocalDestination(root, sourcePath, label);
+      assertNoInstructionSymlink(root, sourcePath, label);
+    }
+  }
+}
+
+function assertNoInstructionSymlink(root, target, label) {
+  const boundary = path.resolve(root);
+  const absoluteTarget = path.resolve(target);
+  const relative = path.relative(boundary, absoluteTarget);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside the project`);
+  }
+
+  let current = boundary;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new CliError(`${label} contains a symlink path component`);
+      }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+}
+
+function installAgents(cwd, globalInstall, selectedProject) {
+  const composed = composeAgentsInstructions(agentsContentRoot);
+  const targetPaths = [];
+  const root = globalInstall ? null : instructionProjectRoot(cwd, selectedProject);
+  if (globalInstall) {
+    targetPaths.push(...globalAgentsTargets.map((target) => path.join(os.homedir(), target)));
+  } else {
+    const targetPath = nearestAgentsFile(cwd, root);
+    assertLocalDestination(root, targetPath, 'local agents instructions');
+    assertNoInstructionSymlink(root, targetPath, 'local agents instructions');
+    assertLocalInstructionSources(root, path.dirname(targetPath));
+    targetPaths.push(targetPath);
+  }
+
+  // Plan every target before writing any of them, so a rejected file leaves all files intact.
+  const planned = targetPaths.map((targetPath) => {
+    const existing = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, 'utf8') : '';
+    const bundled = applyInstructions(existing, composed.content, packageJson.version);
+    const local = applyLocalFragments(bundled.text, path.dirname(targetPath));
+    const action = existing === local.text ? 'unchanged' : bundled.action === 'installed' || local.action === 'installed' ? 'installed' : 'refreshed';
+    return { targetPath, action, text: local.text };
+  });
+
+  for (const { targetPath, action, text } of planned) {
+    if (action === 'unchanged') {
+      console.log(`Agents instructions already installed at ${targetPath}`);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, text);
+    console.log(
+      action === 'refreshed'
+        ? `Refreshed agents instructions at ${targetPath}`
+        : `Installed agents instructions at ${targetPath}`
+    );
+  }
+}
+
+function projectInstructionPaths(cwd, selectedProject) {
+  const root = instructionProjectRoot(cwd, selectedProject);
+  const sourceDirectory = path.join(root, projectTemplateDirectory);
+  const templatePath = path.join(sourceDirectory, projectTemplateName);
+  const outputPath = path.join(root, 'AGENTS.md');
+  const paths = [
+    [sourceDirectory, 'project instruction source directory'],
+    [templatePath, 'project instruction template'],
+    [outputPath, 'project agents output']
+  ];
+  for (const [target, label] of paths) {
+    assertLocalDestination(root, target, label);
+    assertNoInstructionSymlink(root, target, label);
+  }
+
+  if (fs.existsSync(sourceDirectory) && !fs.statSync(sourceDirectory).isDirectory()) {
+    throw new CliError(`project instruction source path is not a directory: ${sourceDirectory}`);
+  }
+  if (fs.existsSync(templatePath) && !fs.statSync(templatePath).isFile()) {
+    throw new CliError(`project instruction template is not a file: ${templatePath}`);
+  }
+  if (fs.existsSync(outputPath) && !fs.statSync(outputPath).isFile()) {
+    throw new CliError(`project agents output is not a file: ${outputPath}`);
+  }
+  if (fs.existsSync(sourceDirectory)) {
+    for (const entry of fs.readdirSync(sourceDirectory, { withFileTypes: true })) {
+      if (!entry.name.endsWith('.block.md')) continue;
+      const sourcePath = path.join(sourceDirectory, entry.name);
+      const label = `project instruction source ${entry.name}`;
+      assertLocalDestination(root, sourcePath, label);
+      assertNoInstructionSymlink(root, sourcePath, label);
+    }
+  }
+
+  return { root, sourceDirectory, templatePath, outputPath };
+}
+
+function renderProjectAgents(cwd, selectedProject, { initialize = false, check = false } = {}) {
+  let paths = projectInstructionPaths(cwd, selectedProject);
+  if (initialize) {
+    fs.mkdirSync(paths.sourceDirectory, { recursive: true });
+    if (!fs.existsSync(paths.templatePath)) {
+      fs.writeFileSync(paths.templatePath, defaultProjectTemplate);
+    }
+    paths = projectInstructionPaths(cwd, selectedProject);
+  }
+
+  if (!fs.existsSync(paths.templatePath)) {
+    throw new CliError(`project instruction template is missing; run "skillshop agents init" first: ${paths.templatePath}`);
+  }
+
+  const composed = composeAgentsInstructions(paths.sourceDirectory, projectTemplateName).content;
+  const existing = fs.existsSync(paths.outputPath) ? fs.readFileSync(paths.outputPath, 'utf8') : '';
+  const planned = applyProjectInstructions(existing, composed, packageJson.version);
+
+  if (check) {
+    if (fs.existsSync(paths.outputPath) && planned.text === existing) {
+      console.log(`Project agents instructions are current at ${paths.outputPath}`);
+      return;
+    }
+    console.error(
+      `Project agents instructions are ${fs.existsSync(paths.outputPath) ? 'stale' : 'missing'} at ${paths.outputPath}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (planned.text === existing) {
+    console.log(`Project agents instructions already current at ${paths.outputPath}`);
+    return;
+  }
+  fs.writeFileSync(paths.outputPath, planned.text);
+  console.log(`${planned.action === 'refreshed' ? 'Refreshed' : 'Rendered'} project agents instructions at ${paths.outputPath}`);
+}
+
+function projectAgentsConfigured(cwd, selectedProject) {
+  const root = instructionProjectRoot(cwd, selectedProject);
+  const sourceDirectory = path.join(root, projectTemplateDirectory);
+  const outputPath = path.join(root, 'AGENTS.md');
+  for (const candidate of [sourceDirectory, outputPath]) {
+    try {
+      const stat = fs.lstatSync(candidate);
+      if (candidate === sourceDirectory) return true;
+      if (stat.isFile() && hasProjectInstructions(fs.readFileSync(candidate, 'utf8'))) return true;
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+  return false;
+}
+
+function installLocal(name, requestedVersion, cwd) {
+  const root = findLockRoot(cwd) ?? projectRoot(cwd);
+  const lock = readLock(root);
+  const config = readConfig();
+  const skillDirectories = localSkillDirectories(root, lock, cwd);
+  const names = [...new Set([...Object.keys(lock.skills), name, 'skillshop'])].sort();
+  const installs = names.map((skillName) => {
+    const metadata = skillMetadata(skillName);
+    const targetDirs = config || !lock.skills[skillName]
+      ? skillDirectories.map((directory) => path.join(directory, skillName))
+      : lockedTargets(root, skillName, lock.skills[skillName]);
+    const previousTargets = lock.skills[skillName]
+      ? lockedTargets(root, skillName, lock.skills[skillName])
+      : [];
+    return { metadata, targetDirs, previousTargets };
+  });
+  const requestedMetadata = installs.find(({ metadata }) => metadata.name === name).metadata;
+  if (requestedVersion && requestedVersion !== requestedMetadata.version) {
+    throw new CliError(
+      `${name}@${requestedVersion} is unavailable; local registry provides ${name}@${requestedMetadata.version}`
+    );
+  }
+  for (const { metadata, targetDirs, previousTargets } of installs) {
+    assertTargetsAvailable(metadata.name, targetDirs, previousTargets);
+  }
+
+  for (const { metadata, targetDirs, previousTargets } of installs) {
+    const version = metadata.name === name ? requestedVersion : null;
+    const results = targetDirs.map((targetDir) => installAt(metadata.name, version, targetDir));
+    for (const staleTarget of staleTargets(previousTargets, targetDirs)) {
+      fs.rmSync(staleTarget, { recursive: true, force: true });
+    }
+    lock.skills[metadata.name] = lockEntry(root, results);
+    for (const result of results) {
+      console.log(
+        `${result.updating ? 'Updated' : 'Installed'} ${result.name}@${result.version} at ${result.targetDir}`
+      );
+    }
+  }
+
+  writeLock(root, lock);
+  maintainRepository(root, lock);
+  console.log(`Wrote ${path.join(root, lockFileName)}`);
+}
+
+function uninstallGlobal(name) {
+  const config = readConfig();
+  const skillDirectories = config
+    ? configuredSkillDirectories(config, 'global')
+    : [path.join(os.homedir(), '.agents', 'skills')];
+  const targets = skillDirectories.map((directory) => path.join(directory, name));
+  const installedTargets = targets.filter((target) => fs.existsSync(target));
+  if (installedTargets.length === 0) {
+    throw new CliError(`${name} is not installed globally in the configured skill directories`);
+  }
+
+  for (const targetDir of installedTargets) {
+    fs.rmSync(targetDir, { recursive: true });
+    console.log(`Uninstalled ${name} from ${targetDir}`);
+  }
+  const globalSkills = readGlobalSkills();
+  if (globalSkills.skills[name]) {
+    const remaining = staleTargets(globalTargets(name, globalSkills.skills[name]), installedTargets);
+    if (remaining.length) globalSkills.skills[name].paths = remaining;
+    else delete globalSkills.skills[name];
+    writeGlobalSkills(globalSkills);
+  }
+}
+
+function uninstallLocal(name, cwd) {
+  const root = findLockRoot(cwd);
+  if (!root) throw new CliError(`no ${lockFileName} found in this project`);
+
+  const lock = readLock(root);
+  if (!lock.skills[name]) {
+    throw new CliError(`${name} is not listed in ${path.join(root, lockFileName)}`);
+  }
+
+  const targetDirs = lockedTargets(root, name, lock.skills[name]);
+  for (const targetDir of targetDirs) fs.rmSync(targetDir, { recursive: true, force: true });
+  delete lock.skills[name];
+  writeLock(root, lock);
+  maintainRepository(root, lock);
+
+  for (const targetDir of targetDirs) console.log(`Uninstalled ${name} from ${targetDir}`);
+  console.log(`Updated ${path.join(root, lockFileName)}`);
+}
+
+function updateLocal(requestedName, cwd, options = {}) {
+  const root = findLockRoot(cwd);
+  if (!root) throw new CliError(`no ${lockFileName} found in this project`);
+
+  const lock = readLock(root);
+  if (requestedName && !lock.skills[requestedName]) {
+    throw new CliError(`${requestedName} is not listed in ${path.join(root, lockFileName)}`);
+  }
+
+  const names = requestedName ? [requestedName] : Object.keys(lock.skills);
+  const config = readConfig();
+  const skillDirectories = localSkillDirectories(root, lock, cwd);
+
+  const updates = [...new Set(names)].sort().map((name) => {
+    const metadata = skillMetadata(name);
+    const targetDirs = config
+      ? skillDirectories.map((directory) => path.join(directory, name))
+      : lockedTargets(root, name, lock.skills[name]);
+    const previousTargets = lockedTargets(root, name, lock.skills[name]);
+    return { metadata, targetDirs, previousTargets };
+  });
+  for (const { metadata, targetDirs, previousTargets } of updates) {
+    assertTargetsAvailable(metadata.name, targetDirs, previousTargets);
+  }
+
+  for (const { metadata, targetDirs, previousTargets } of updates) {
+    const results = targetDirs.map((targetDir) => installAt(metadata.name, null, targetDir));
+    for (const staleTarget of staleTargets(previousTargets, targetDirs)) {
+      fs.rmSync(staleTarget, { recursive: true, force: true });
+    }
+    lock.skills[metadata.name] = lockEntry(root, results);
+    for (const result of results) {
+      console.log(`Updated ${result.name}@${result.version} at ${result.targetDir}`);
+    }
+  }
+
+  writeLock(root, lock);
+  maintainRepository(root, lock, options);
+  console.log(`Updated ${path.join(root, lockFileName)}`);
+}
+
+function updateAllRepositories() {
+  const registry = readRegistry();
+  const retained = [];
+  const failures = [];
+
+  for (const root of registry.repositories) {
+    if (!hasLock(root)) {
+      console.log(`Removed missing repository ${root}`);
+      continue;
+    }
+
+    retained.push(root);
+    console.log(`Updating ${root}`);
+    try {
+      reconcileRepository(root, { register: false });
+      updateLocal(null, root, { register: false });
+    } catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      failures.push(`${root}: ${error.message}`);
+      console.error(`skillshop: ${root}: ${error.message}`);
+    }
+  }
+
+  writeRegistry(retained);
+  if (failures.length) {
+    throw new CliError(`failed to update ${failures.length} registered ${failures.length === 1 ? 'repository' : 'repositories'}`);
+  }
+  console.log(`Updated ${retained.length} registered ${retained.length === 1 ? 'repository' : 'repositories'}`);
+}
+
+function assertNoManagedSymlink(base, target, label) {
+  const boundary = path.resolve(base);
+  const absoluteTarget = path.resolve(target);
+  const relative = path.relative(boundary, absoluteTarget);
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new CliError(`${label} resolves outside its managed root`);
+  }
+
+  let current = boundary;
+  for (const segment of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new CliError(`${label} contains a symlink path component`);
+      }
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (error.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+}
+
+function replaceManagedSkillDirectory(sourceDir, targetDir) {
+  const temporaryDir = `${targetDir}.skillshop-upgrade-tmp-${process.pid}`;
+  const backupDir = `${targetDir}.skillshop-upgrade-backup-${process.pid}`;
+  fs.rmSync(temporaryDir, { recursive: true, force: true });
+  fs.rmSync(backupDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(targetDir), { recursive: true });
+  fs.cpSync(sourceDir, temporaryDir, { recursive: true, force: true });
+
+  const hadTarget = fs.existsSync(targetDir);
+  if (hadTarget) fs.renameSync(targetDir, backupDir);
+  try {
+    fs.renameSync(temporaryDir, targetDir);
+    fs.rmSync(backupDir, { recursive: true, force: true });
+  } catch (error) {
+    if (hadTarget && !fs.existsSync(targetDir) && fs.existsSync(backupDir)) {
+      fs.renameSync(backupDir, targetDir);
+    }
+    throw error;
+  } finally {
+    fs.rmSync(temporaryDir, { recursive: true, force: true });
+  }
+}
+
+function upgradeSummary() {
+  return { updated: 0, unchanged: 0, missing: 0, failed: [] };
+}
+
+function validateManagedCopy(root, target, name) {
+  assertNoManagedSymlink(root, target, `managed ${name} copy`);
+  let targetStats;
+  try {
+    targetStats = fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+  if (!targetStats.isDirectory()) throw new CliError(`${target} is not a managed skill directory`);
+
+  const manifestPath = path.join(target, 'SKILL.md');
+  assertNoManagedSymlink(root, manifestPath, `managed ${name} manifest`);
+  let manifestStats;
+  try {
+    manifestStats = fs.lstatSync(manifestPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new CliError(`${manifestPath} is missing from a recorded skill copy`);
+    throw error;
+  }
+  if (!manifestStats.isFile()) throw new CliError(`${manifestPath} is not a regular skill manifest`);
+  return true;
+}
+
+function refreshManagedLock(root, lock, { global = false, summary }) {
+  let changed = false;
+  for (const name of Object.keys(lock.skills).sort()) {
+    const entry = lock.skills[name];
+    try {
+      const metadata = skillMetadata(name);
+      const targets = global ? globalTargets(name, entry) : lockedTargets(root, name, entry);
+      const base = global ? os.homedir() : root;
+      const existingTargets = [];
+      for (const target of targets) {
+        if (validateManagedCopy(base, target, name)) existingTargets.push(target);
+        else summary.missing += 1;
+      }
+
+      if (!existingTargets.length) {
+        delete lock.skills[name];
+        changed = true;
+        continue;
+      }
+
+      const successfulTargets = [];
+      let skillFailed = false;
+      for (const target of existingTargets) {
+        const recordedVersion = global ? entry.copies?.[target]?.version : entry.version;
+        if (recordedVersion === metadata.version) {
+          summary.unchanged += 1;
+          successfulTargets.push(target);
+          continue;
+        }
+        try {
+          replaceManagedSkillDirectory(metadata.sourceDir, target);
+          summary.updated += 1;
+          successfulTargets.push(target);
+        } catch (error) {
+          summary.failed.push(`${name} at ${target}: ${error.message}`);
+          skillFailed = true;
+        }
+      }
+
+      if (global) {
+        const keptTargets = skillFailed ? targets : successfulTargets;
+        entry.paths = keptTargets;
+        entry.copies ??= {};
+        for (const target of successfulTargets) {
+          const previous = entry.copies[target] ?? {};
+          entry.copies[target] = { ...previous, author: metadata.author, version: metadata.version };
+        }
+        if (!skillFailed) changed = true;
+        if (!entry.paths.length) {
+          delete lock.skills[name];
+          changed = true;
+        }
+      } else if (!skillFailed) {
+        entry.paths = successfulTargets.map((target) => relativePath(root, target)).sort();
+        entry.author = metadata.author;
+        entry.version = metadata.version;
+        changed = true;
+      } else if (existingTargets.length !== targets.length) {
+        entry.paths = existingTargets.map((target) => relativePath(root, target)).sort();
+        changed = true;
+      }
+    } catch (error) {
+      summary.failed.push(`${name}: ${error.message}`);
+    }
+  }
+
+  if (changed) {
+    try {
+      if (global) writeGlobalSkills(lock);
+      else writeLock(root, lock);
+    } catch (error) {
+      summary.failed.push(`could not save ${global ? 'global skill manifest' : path.join(root, lockFileName)}: ${error.message}`);
+    }
+  }
+}
+
+function refreshManagedCopies(scope) {
+  const summary = upgradeSummary();
+  if (scope === 'local') {
+    const owner = localPackageOwner();
+    if (!owner) {
+      summary.failed.push('fresh Skillshop package is no longer attached to a local npm dependency');
+    } else {
+      try {
+        const lock = readLock(owner.root);
+        refreshManagedLock(owner.root, lock, { summary });
+      } catch (error) {
+        summary.failed.push(`${owner.root}: ${error.message}`);
+      }
+    }
+  } else if (scope === 'global') {
+    try {
+      const globalLock = readGlobalSkills();
+      refreshManagedLock(null, globalLock, { global: true, summary });
+    } catch (error) {
+      summary.failed.push(`global managed copies: ${error.message}`);
+    }
+
+    try {
+      const registry = readRegistry();
+      for (const root of registry.repositories) {
+        if (!hasLock(root)) continue;
+        try {
+          const lock = readLock(root);
+          refreshManagedLock(root, lock, { summary });
+        } catch (error) {
+          summary.failed.push(`${root}: ${error.message}`);
+        }
+      }
+    } catch (error) {
+      summary.failed.push(`registered project copies: ${error.message}`);
+    }
+  } else {
+    summary.failed.push(`unsupported managed-copy scope: ${scope}`);
+  }
+
+  console.log(
+    `Managed-copy refresh summary: ${summary.updated} updated, ${summary.unchanged} unchanged, ${summary.missing} missing paths pruned, ${summary.failed.length} failed.`
+  );
+  if (summary.failed.length) {
+    for (const failure of summary.failed) console.error(`skillshop: upgrade refresh: ${failure}`);
+    console.error('skillshop: npm upgrade succeeded, but managed-copy refresh was incomplete');
+    process.exitCode = 1;
+  } else {
+    console.log(`Refreshed Skillshop-managed copies for ${scope} scope.`);
+  }
+}
+
+const migrationSkipDirectories = new Set([
+  '.git',
+  '.skillshop',
+  '.skillz',
+  '.Trash',
+  'Library',
+  'node_modules'
+]);
+
+function discoverLockRoots(startPath, roots) {
+  let stat;
+  try {
+    stat = fs.statSync(startPath);
+  } catch {
+    return;
+  }
+
+  if (stat.isFile()) {
+    if ([lockFileName, legacyLockFileName].includes(path.basename(startPath))) roots.add(canonicalPath(path.dirname(startPath)));
+    return;
+  }
+  if (!stat.isDirectory()) return;
+
+  if (hasLock(startPath)) roots.add(canonicalPath(startPath));
+
+  let entries;
+  try {
+    entries = fs.readdirSync(startPath, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.isSymbolicLink() || migrationSkipDirectories.has(entry.name)) continue;
+    discoverLockRoots(path.join(startPath, entry.name), roots);
+  }
+}
+
+function migrateRepositories(requestedRoots, cwd) {
+  const registry = readRegistry();
+  const roots = new Set(registry.repositories);
+  const searchRoots = requestedRoots.length
+    ? requestedRoots.map((root) => path.resolve(cwd, root))
+    : [os.homedir()];
+
+  for (const searchRoot of searchRoots) discoverLockRoots(searchRoot, roots);
+
+  const migrated = [];
+  const failures = [];
+  for (const root of [...roots].sort()) {
+    if (!hasLock(root)) continue;
+
+    try {
+      reconcileRepository(root, { register: false });
+      const lock = readLock(root);
+      maintainRepository(root, lock, { register: false, untrack: true });
+      migrated.push(root);
+      console.log(`Migrated ${root}`);
+    } catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      failures.push(`${root}: ${error.message}`);
+      console.error(`skillshop: ${root}: ${error.message}`);
+    }
+  }
+
+  writeRegistry(migrated);
+  if (failures.length) {
+    throw new CliError(`failed to migrate ${failures.length} ${failures.length === 1 ? 'repository' : 'repositories'}`);
+  }
+  console.log(`Migrated ${migrated.length} ${migrated.length === 1 ? 'repository' : 'repositories'}`);
+}
+
+function parseSkillSpec(spec, requestedVersion) {
+  const separator = spec.lastIndexOf('@');
+  if (separator <= 0) return { name: spec, version: requestedVersion };
+
+  const name = spec.slice(0, separator);
+  const inlineVersion = spec.slice(separator + 1);
+  if (!inlineVersion) throw new CliError(`missing version in ${spec}`);
+  if (requestedVersion && requestedVersion !== inlineVersion) {
+    throw new CliError(`conflicting versions requested for ${name}`);
+  }
+  return { name, version: inlineVersion };
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  let globalInstall = false;
+  let pushUpdate = false;
+  const agentsTargets = [];
+  let requestedVersion = null;
+  let selectedProject = null;
+  let checkProject = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--global' || argument === '-g') {
+      globalInstall = true;
+    } else if (argument === '--push') {
+      pushUpdate = true;
+    } else if (argument === '--check') {
+      checkProject = true;
+    } else if (argument === '--project') {
+      selectedProject = argv[index + 1];
+      if (!selectedProject) throw new CliError('--project requires a directory');
+      index += 1;
+    } else if (argument.startsWith('--project=')) {
+      selectedProject = argument.slice('--project='.length);
+      if (!selectedProject) throw new CliError('--project requires a directory');
+    } else if (argument === '--codex' || argument === '--copilot') {
+      throw new CliError(`${argument} is no longer supported; use agents --global`);
+    } else if (argument === '--version' || argument === '-v') {
+      requestedVersion = argv[index + 1];
+      if (!requestedVersion) throw new CliError(`${argument} requires a version`);
+      index += 1;
+    } else if (argument.startsWith('--version=')) {
+      requestedVersion = argument.slice('--version='.length);
+      if (!requestedVersion) throw new CliError('--version requires a version');
+    } else if (argument.startsWith('-')) {
+      throw new CliError(`unknown option: ${argument}`);
+    } else {
+      positional.push(argument);
+    }
+  }
+
+  return {
+    positional,
+    globalInstall,
+    pushUpdate,
+    requestedVersion,
+    selectedProject,
+    checkProject,
+    agentsTargets: [...new Set(agentsTargets)]
+  };
+}
+
+function listSkills() {
+  for (const name of availableSkills()) {
+    const metadata = skillMetadata(name);
+    console.log(`${name}@${metadata.version} — ${metadata.author}`);
+  }
+}
+
+function packageDependencySection(manifest) {
+  for (const section of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies']) {
+    if (Object.hasOwn(manifest?.[section] ?? {}, 'skillshop')) return section;
+  }
+  return null;
+}
+
+function localPackageOwner() {
+  const installedPackageRoot = canonicalPath(packageRoot);
+  let current = path.dirname(installedPackageRoot);
+  while (true) {
+    const manifestPath = path.join(current, 'package.json');
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const section = packageDependencySection(manifest);
+        const declaredInstall = path.join(current, 'node_modules', 'skillshop');
+        if (section && fs.existsSync(declaredInstall) && canonicalPath(declaredInstall) === installedPackageRoot) {
+          return { root: current, section };
+        }
+      } catch (error) {
+        if (error instanceof SyntaxError) throw new CliError(`cannot parse ${manifestPath}: ${error.message}`);
+        throw error;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function npmGlobalRoot() {
+  try {
+    return path.resolve(execFileSync('npm', ['root', '--global'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim());
+  } catch (error) {
+    const detail = error.stderr?.toString().trim();
+    throw new CliError(`cannot determine the active npm global package directory${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+function npmPrefixFromRoot(globalRoot) {
+  const parent = path.dirname(globalRoot);
+  return path.basename(parent) === 'lib' ? path.dirname(parent) : parent;
+}
+
+function resolveUpgradeScope() {
+  const localOwner = localPackageOwner();
+  if (localOwner) return { type: 'local', root: localOwner.root, dependencySection: localOwner.section, packageRoot };
+
+  const insideNodeModules = canonicalPath(packageRoot).split(path.sep).includes('node_modules');
+  const activeGlobalRoot = npmGlobalRoot();
+  if (canonicalPath(path.join(activeGlobalRoot, 'skillshop')) === canonicalPath(packageRoot)) {
+    return { type: 'global', prefix: npmPrefixFromRoot(activeGlobalRoot), packageRoot };
+  }
+  if (insideNodeModules) {
+    throw new CliError(
+      `cannot match this installed Skillshop package to the active npm global prefix (${activeGlobalRoot}); no upgrade was run`
+    );
+  }
+
+  // Preserve the historical source-checkout behavior: install the package into
+  // the active npm global prefix without editing the checkout's package files.
+  return { type: 'global-checkout', packageRoot };
+}
+
+function runUpgradeInstall(scope) {
+  const args = scope.type === 'local'
+    ? ['install', `--save-${scope.dependencySection === 'dependencies' ? 'prod' : scope.dependencySection === 'devDependencies' ? 'dev' : scope.dependencySection === 'optionalDependencies' ? 'optional' : 'peer'}`, 'skillshop@latest']
+    : scope.type === 'global'
+      ? ['install', '--global', '--prefix', scope.prefix, 'skillshop@latest']
+      : ['install', '--global', 'skillshop@latest'];
+  try {
+    execFileSync('npm', args, {
+      cwd: scope.type === 'local' ? scope.root : process.cwd(),
+      stdio: 'inherit'
+    });
+  } catch (error) {
+    const status = Number.isInteger(error.status) ? ` (exit ${error.status})` : '';
+    throw new CliError(`npm upgrade failed${status}; managed copies were not refreshed`);
+  }
+}
+
+function freshUpgradePackageRoot(scope) {
+  if (scope.type !== 'global-checkout') return scope.packageRoot;
+  return path.join(npmGlobalRoot(), 'skillshop');
+}
+
+function upgrade() {
+  const scope = resolveUpgradeScope();
+  const scopeLabel = scope.type === 'local'
+    ? `project dependency in ${scope.root}`
+    : scope.type === 'global'
+      ? `global installation at ${scope.packageRoot}`
+      : 'global installation (source-checkout compatibility mode)';
+  console.log(`Upgrading Skillshop ${scopeLabel}...`);
+  runUpgradeInstall(scope);
+
+  let freshCliPath;
+  try {
+    freshCliPath = path.join(freshUpgradePackageRoot(scope), 'src', 'cli.js');
+    if (!fs.statSync(freshCliPath).isFile()) throw new Error('not a file');
+  } catch {
+    throw new CliError('npm upgrade succeeded, but the newly installed Skillshop CLI could not be found for managed-copy refresh');
+  }
+
+  const child = spawnSync(process.execPath, [freshCliPath, internalUpgradeRefreshCommand], {
+    cwd: scope.type === 'local' ? scope.root : process.cwd(),
+    env: {
+      ...process.env,
+      SKILLSHOP_INTERNAL_UPGRADE_TOKEN: internalUpgradeRefreshToken,
+      SKILLSHOP_INTERNAL_UPGRADE_SCOPE: scope.type === 'local' ? 'local' : 'global'
+    },
+    stdio: 'inherit'
+  });
+  if (child.error) {
+    throw new CliError(`npm upgrade succeeded, but fresh Skillshop managed-copy refresh could not start: ${child.error.message}`);
+  }
+  if (child.status !== 0) {
+    const status = child.status === null ? 'without an exit status' : `with exit ${child.status}`;
+    throw new CliError(`npm upgrade succeeded, but fresh Skillshop managed-copy refresh failed ${status}`);
+  }
+}
+
+async function main(argv) {
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    printHelp();
+    return;
+  }
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  const { positional, globalInstall, pushUpdate, requestedVersion, selectedProject, checkProject, agentsTargets } = parseArgs(argv);
+  const command = positional[0];
+
+  if ((selectedProject || checkProject) && command !== 'agents') {
+    throw new CliError('--project and --check are only valid with agents');
+  }
+
+  if (command === internalUpgradeRefreshCommand) {
+    if (
+      process.env.SKILLSHOP_INTERNAL_UPGRADE_TOKEN !== internalUpgradeRefreshToken ||
+      positional.length !== 1 ||
+      requestedVersion || globalInstall || pushUpdate || selectedProject || checkProject || agentsTargets.length
+    ) {
+      throw new CliError('invalid internal upgrade continuation');
+    }
+    refreshManagedCopies(process.env.SKILLSHOP_INTERNAL_UPGRADE_SCOPE);
+    return;
+  }
+
+  if (command === 'init') {
+    if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('init does not accept arguments or options');
+    }
+    await initialize();
+    return;
+  }
+
+  if (command === 'config') {
+    if (positional.length !== 2 || positional[1] !== 'agents' || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('config expects `agents` and does not accept options');
+    }
+    await configureAgents();
+    return;
+  }
+
+  if (command === 'list' || command === 'ls') {
+    if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('list does not accept skill or install options');
+    }
+    listSkills();
+    return;
+  }
+
+  if (command === 'upgrade') {
+    if (positional.length !== 1 || requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('upgrade does not accept arguments or options');
+    }
+    upgrade();
+    return;
+  }
+
+  if (command === 'update' || command === 'up') {
+    if (agentsTargets.length) throw new CliError('--codex and --copilot are only valid with agents');
+    if (globalInstall) throw new CliError('global updates are not tracked; reinstall the global skill by name');
+    if (requestedVersion) throw new CliError('update uses the current registry versions and does not accept --version');
+    if (positional.length > 2) throw new CliError('update accepts at most one locked skill name');
+    if (pushUpdate && positional.length !== 1) {
+      throw new CliError('push update does not accept a skill name');
+    }
+    if (pushUpdate) updateAllRepositories();
+    else updateLocal(positional[1] ?? null, process.cwd());
+    return;
+  }
+
+  if (command === 'migrate') {
+    if (requestedVersion || globalInstall || pushUpdate || agentsTargets.length) {
+      throw new CliError('migrate does not accept install or update options');
+    }
+    migrateRepositories(positional.slice(1), process.cwd());
+    return;
+  }
+
+  if (command === 'agents') {
+    const initializeProject = positional.length === 2 && positional[1] === 'init';
+    if (
+      positional.length > 2 ||
+      (positional.length === 2 && !initializeProject) ||
+      requestedVersion ||
+      pushUpdate ||
+      agentsTargets.length
+    ) {
+      throw new CliError('agents does not accept skill or update options');
+    }
+    if (globalInstall) {
+      if (initializeProject || selectedProject || checkProject) {
+        throw new CliError('--global cannot be combined with project agents options');
+      }
+      installAgents(process.cwd(), true);
+      return;
+    }
+    if (initializeProject && checkProject) throw new CliError('agents init does not accept --check');
+    if (initializeProject || checkProject || projectAgentsConfigured(process.cwd(), selectedProject)) {
+      renderProjectAgents(process.cwd(), selectedProject, {
+        initialize: initializeProject,
+        check: checkProject
+      });
+    } else {
+      installAgents(process.cwd(), false, selectedProject);
+    }
+    return;
+  }
+
+  const uninstallAliases = new Set(['uninstall', 'remove', 'rm']);
+  if (uninstallAliases.has(command)) {
+    if (agentsTargets.length) throw new CliError('--codex and --copilot are only valid with agents');
+    if (requestedVersion) throw new CliError('uninstall does not accept --version');
+    if (pushUpdate) throw new CliError('--push is only valid with update');
+    if (positional.length !== 2) throw new CliError('uninstall expects exactly one skill name');
+
+    const name = positional[1];
+    validateSkillName(name);
+    if (globalInstall) uninstallGlobal(name);
+    else uninstallLocal(name, process.cwd());
+    return;
+  }
+
+  const installAliases = new Set(['install', 'i', 'add']);
+  if (agentsTargets.length) throw new CliError('--codex and --copilot are only valid with agents');
+  const spec = installAliases.has(command) ? positional[1] : command;
+  const expectedLength = installAliases.has(command) ? 2 : 1;
+  if (!spec || positional.length !== expectedLength) {
+    throw new CliError('expected exactly one skill name');
+  }
+  if (pushUpdate) throw new CliError('--push is only valid with update');
+
+  const { name, version } = parseSkillSpec(spec, requestedVersion);
+  validateSkillName(name);
+  if (globalInstall) installGlobal(name, version);
+  else installLocal(name, version, process.cwd());
+}
+
+function isIsolatedAgentsInvocation(argv) {
+  // Preserve the top-level help/version routing before looking for a command.
+  // main() handles help anywhere and the standalone version form without parsing.
+  if (argv[0] === '--help' || argv[0] === '-h') return false;
+  if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) return false;
+
+  // parseArgs accepts project options on either side of the command. Ignore help
+  // flags here because main() handles them before parsing, then classify using
+  // the same positional-command rules as execution.
+  try {
+    const args = argv.filter((argument) => argument !== '--help' && argument !== '-h');
+    return parseArgs(args).positional[0] === 'agents';
+  } catch {
+    return false;
+  }
+}
+
+function isUpgradeFlowInvocation(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return false;
+  if (
+    argv[0] === internalUpgradeRefreshCommand &&
+    process.env.SKILLSHOP_INTERNAL_UPGRADE_TOKEN === internalUpgradeRefreshToken
+  ) return true;
+  try {
+    return parseArgs(argv).positional[0] === 'upgrade';
+  } catch {
+    return false;
+  }
+}
+
+export async function runLegacyCli(argv) {
+  const isolatedAgentsCommand = isIsolatedAgentsInvocation(argv);
+  const upgradeFlow = isUpgradeFlowInvocation(argv);
+  const skipLegacyReconciliation = isolatedAgentsCommand || upgradeFlow;
+  try {
+    if (!skipLegacyReconciliation) reconcileCurrentRepository();
+    try {
+      await main(argv);
+    } finally {
+      if (!skipLegacyReconciliation) reconcileCurrentRepository();
+    }
+  } catch (error) {
+    if (!(error instanceof CliError) && !(error instanceof AgentsInstructionsError)) throw error;
+    console.error(`skillshop: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+export function reconcileLegacyState() {
+  reconcileCurrentRepository();
+}