agentfold 0.1.0

package/agentfold.mjs

@@ -0,0 +1,1115 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveLayerPaths } from './lib/compose-layers.mjs';
+import { diffRenderMapAgainstProject } from './lib/diff.mjs';
+import { loadProfile } from './lib/load-profile.mjs';
+import { loadManifest, pruneManagedFiles, writeManifest } from './lib/manifest.mjs';
+import { buildRenderPlan } from './lib/pipeline-steps.mjs';
+import {
+  createLogger,
+  ensureDir,
+  listFiles,
+  parseCliArgs,
+  pathExists,
+  readJson,
+  removeDir,
+  toPosixPath,
+  writeJson,
+} from './lib/util.mjs';
+import { validatePlan } from './lib/validate.mjs';
+
+const selectableTypes = ['skills', 'prompts', 'rules', 'commands', 'mcp', 'subagents'];
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const kitRoot = __dirname;
+
+function resolveConfigRoot(options) {
+  if (options.config) return path.resolve(String(options.config));
+  return path.join(os.homedir(), '.agentfold');
+}
+
+function usage() {
+  console.log(`agentfold — layered AI agent configuration generator
+
+usage:
+  agentfold <command> [options]
+
+commands:
+  init           Bootstrap config hub (default: ~/.agentfold)
+  lint           Validate selected layers/profile
+  build          Render outputs into <config>/out
+  diff           Compare rendered outputs with project files
+  apply          Apply rendered outputs to project files
+  status         Show current configuration summary
+  doctor         Validate config hub and project health
+  explain        Show why a content file is included/excluded
+
+  create-layer   Scaffold a new layer directory
+  create-profile Scaffold a new profile JSON
+  list-layers    List available layers
+  list-profiles  List available profiles
+  list-tags      List allowed scope tags
+  add-tag        Add a scope tag
+  delete-tag     Delete a scope tag
+
+  add-rule       Add a rule file to a layer
+  add-skill      Add a skill directory to a layer
+  add-subagent   Add a subagent file to a layer
+  add-command    Add a command file to a layer
+  add-reference  Add a reference file to a layer
+
+options:
+  --config <path>    Config hub root (default: ~/.agentfold)
+  --project <path>   Target project root (default: cwd)
+  --profile <name>   Profile name (default: "default")
+  --output <path>    Build output folder (default: <config>/out)
+  --dry-run          For apply: show changes only
+  --prune            For apply: remove stale previously generated files
+  --name <value>     For create-layer/create-profile/add-*: resource name
+  --layer <name>     For add-*: target layer (default: "global")
+  --layers <list>    For create-profile: comma-separated layer names
+  --targets <list>   For init/create-profile: comma-separated targets (copilot,codex,cursor,claude)
+  --force            Overwrite existing resources
+  --tag <value>      For add-tag/delete-tag: tag value
+  --file <path>      For explain: content file to trace
+  --quiet            Reduce informational logs
+  --version          Print version
+`);
+}
+
+function normalizeTagValue(input) {
+  return String(input || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/_/g, '-')
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+function getTagsPath({ configRoot }) {
+  return path.join(configRoot, 'config', 'definitions', 'scope-tags.json');
+}
+
+async function readTagList(tagsPath) {
+  if (!(await pathExists(tagsPath))) {
+    return [];
+  }
+  const tags = await readJson(tagsPath);
+  if (!Array.isArray(tags)) {
+    throw new Error(`Expected tag array at ${tagsPath}`);
+  }
+  return tags.map((tag) => normalizeTagValue(tag)).filter(Boolean);
+}
+
+async function runListTags({ options, logger }) {
+  const configRoot = resolveConfigRoot(options);
+  const tagsPath = getTagsPath({ configRoot });
+  const tags = await readTagList(tagsPath);
+  const sorted = [...new Set(tags)].sort((a, b) => a.localeCompare(b));
+
+  logger.info(`Tags source: ${tagsPath}`);
+  for (const tag of sorted) {
+    console.log(tag);
+  }
+}
+
+async function runAddTag({ options, logger }) {
+  const rawTag = typeof options.tag === 'string' ? options.tag : options.name;
+  const normalizedTag = normalizeTagValue(rawTag);
+  if (!normalizedTag) {
+    throw new Error('add-tag requires --tag <value> (or --name <value>).');
+  }
+
+  validateKebabName(normalizedTag, 'Tag');
+
+  const configRoot = resolveConfigRoot(options);
+  const tagsPath = getTagsPath({ configRoot });
+  const existing = await readTagList(tagsPath);
+
+  const next = [...new Set([...existing, normalizedTag])].sort((a, b) => a.localeCompare(b));
+  if (next.length === existing.length) {
+    logger.info(`Tag already exists: ${normalizedTag}`);
+    return;
+  }
+
+  await ensureDir(path.dirname(tagsPath));
+  await writeJson(tagsPath, next);
+  logger.info(`Tag added: ${normalizedTag}`);
+  logger.info(`Updated tags file: ${tagsPath}`);
+}
+
+async function runDeleteTag({ options, logger }) {
+  const rawTag = typeof options.tag === 'string' ? options.tag : options.name;
+  const normalizedTag = normalizeTagValue(rawTag);
+  if (!normalizedTag) {
+    throw new Error('delete-tag requires --tag <value> (or --name <value>).');
+  }
+
+  validateKebabName(normalizedTag, 'Tag');
+
+  const configRoot = resolveConfigRoot(options);
+  const tagsPath = getTagsPath({ configRoot });
+  const existing = await readTagList(tagsPath);
+  const next = existing.filter((tag) => tag !== normalizedTag);
+
+  if (next.length === existing.length) {
+    logger.info(`Tag not found: ${normalizedTag}`);
+    return;
+  }
+
+  await writeJson(tagsPath, [...new Set(next)].sort((a, b) => a.localeCompare(b)));
+  logger.info(`Tag deleted: ${normalizedTag}`);
+  logger.info(`Updated tags file: ${tagsPath}`);
+}
+
+function parseCsvOption(raw) {
+  if (!raw || typeof raw !== 'string') {
+    return [];
+  }
+
+  return raw
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function validateKebabName(name, label) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+    throw new Error(`${label} must be kebab-case. Received: "${name}"`);
+  }
+}
+
+function createDefaultLayerSelect() {
+  const select = {};
+  for (const type of selectableTypes) {
+    select[type] = { tags: { mode: 'any', values: [] } };
+  }
+  return select;
+}
+
+async function scaffoldLayer({ layerRoot }) {
+  const layerDirs = [
+    'agents',
+    'commands',
+    'mcp',
+    'references',
+    'rules',
+    'skills',
+    'subagents',
+  ];
+
+  for (const folder of layerDirs) {
+    await ensureDir(path.join(layerRoot, folder));
+  }
+}
+
+async function runCreateLayer({ options, logger }) {
+  const layerName = typeof options.name === 'string' ? options.name.trim() : '';
+  if (!layerName) {
+    throw new Error('create-layer requires --name <layer-name>.');
+  }
+
+  if (layerName === 'global') {
+    throw new Error('Layer "global" is permanent and already reserved.');
+  }
+
+  validateKebabName(layerName, 'Layer name');
+
+  const configRoot = resolveConfigRoot(options);
+  const layerRoot = path.join(configRoot, 'layers', layerName);
+
+  const exists = await pathExists(layerRoot);
+  if (exists && !options.force) {
+    throw new Error(`Layer already exists: ${layerRoot}. Use --force to reuse it.`);
+  }
+
+  await scaffoldLayer({ layerRoot });
+  logger.info(`Layer ready: ${layerRoot}`);
+  logger.info('Next: add this layer to a profile with create-profile --layers global,<layer-name>.');
+}
+
+async function runCreateProfile({ options, logger }) {
+  const profileName = typeof options.name === 'string' ? options.name.trim() : '';
+  if (!profileName) {
+    throw new Error('create-profile requires --name <profile-name>.');
+  }
+
+  validateKebabName(profileName, 'Profile name');
+
+  const configRoot = resolveConfigRoot(options);
+  const requestedLayers = parseCsvOption(options.layers);
+  const requestedTargets = parseCsvOption(options.targets);
+  const allowedTargets = new Set(['copilot', 'codex', 'cursor', 'claude']);
+  const targets = (requestedTargets.length > 0 ? requestedTargets : ['codex']).map((target) => target.toLowerCase());
+
+  for (const target of targets) {
+    if (!allowedTargets.has(target)) {
+      throw new Error(`Unsupported target "${target}". Allowed: copilot,codex,cursor,claude.`);
+    }
+  }
+
+  const orderedLayers = [];
+  const seen = new Set();
+  for (const name of ['global', ...(requestedLayers.length > 0 ? requestedLayers : [])]) {
+    const normalized = String(name).trim();
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    validateKebabName(normalized, 'Layer name');
+    orderedLayers.push(normalized);
+    seen.add(normalized);
+  }
+
+  for (const layerName of orderedLayers) {
+    const layerPath = path.join(configRoot, 'layers', layerName);
+    if (!(await pathExists(layerPath))) {
+      await scaffoldLayer({ layerRoot: layerPath });
+      logger.info(`Created missing layer: ${layerPath}`);
+    }
+  }
+
+  const profileBody = {
+    name: profileName,
+    targets,
+    layers: orderedLayers.map((layerName) => ({
+      name: layerName,
+      select: createDefaultLayerSelect(),
+    })),
+  };
+
+  const profileDir = path.join(configRoot, 'config', 'profiles');
+  await ensureDir(profileDir);
+  const profilePath = path.join(profileDir, `${profileName}.json`);
+
+  const exists = await pathExists(profilePath);
+  if (exists && !options.force) {
+    throw new Error(`Profile already exists: ${profilePath}. Use --force to overwrite.`);
+  }
+
+  await writeJson(profilePath, profileBody);
+  logger.info(`Profile created: ${profilePath}`);
+}
+
+// ---------------------------------------------------------------------------
+// add-rule / add-skill / add-subagent / add-command / add-reference
+// ---------------------------------------------------------------------------
+
+function resolveLayerForAdd(options) {
+  const configRoot = resolveConfigRoot(options);
+  const layerName = typeof options.layer === 'string' ? options.layer.trim() : 'global';
+  validateKebabName(layerName, 'Layer name');
+  const layerRoot = path.join(configRoot, 'layers', layerName);
+  return { configRoot, layerName, layerRoot };
+}
+
+async function runAddRule({ options, logger }) {
+  const name = typeof options.name === 'string' ? options.name.trim() : '';
+  if (!name) throw new Error('add-rule requires --name <rule-name>.');
+  validateKebabName(name, 'Rule name');
+
+  const { layerRoot } = resolveLayerForAdd(options);
+  const filePath = path.join(layerRoot, 'rules', `${name}.md`);
+
+  if ((await pathExists(filePath)) && !options.force) {
+    throw new Error(`Rule already exists: ${filePath}. Use --force to overwrite.`);
+  }
+
+  const content = `---
+metadata:
+  scope:
+    tags: []
+---
+# ${name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())}
+
+<!-- Add your rule instructions here -->
+`;
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, 'utf8');
+  logger.info(`Rule created: ${filePath}`);
+}
+
+async function runAddSkill({ options, logger }) {
+  const name = typeof options.name === 'string' ? options.name.trim() : '';
+  if (!name) throw new Error('add-skill requires --name <skill-name>.');
+  validateKebabName(name, 'Skill name');
+
+  const { layerRoot } = resolveLayerForAdd(options);
+  const skillDir = path.join(layerRoot, 'skills', name);
+  const filePath = path.join(skillDir, 'SKILL.md');
+
+  if ((await pathExists(filePath)) && !options.force) {
+    throw new Error(`Skill already exists: ${filePath}. Use --force to overwrite.`);
+  }
+
+  const title = name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  const content = `---
+name: ${name}
+description: "TODO: describe when this skill should be invoked"
+metadata:
+  scope:
+    tags: []
+---
+# ${title}
+
+## When to Use
+
+<!-- Describe the trigger conditions for this skill -->
+
+## Steps
+
+1. <!-- Step 1 -->
+2. <!-- Step 2 -->
+3. <!-- Step 3 -->
+`;
+  await ensureDir(skillDir);
+  await fs.writeFile(filePath, content, 'utf8');
+  logger.info(`Skill created: ${filePath}`);
+}
+
+async function runAddSubagent({ options, logger }) {
+  const name = typeof options.name === 'string' ? options.name.trim() : '';
+  if (!name) throw new Error('add-subagent requires --name <subagent-name>.');
+  validateKebabName(name, 'Subagent name');
+
+  const { layerRoot } = resolveLayerForAdd(options);
+  const filePath = path.join(layerRoot, 'subagents', `${name}.agent.md`);
+
+  if ((await pathExists(filePath)) && !options.force) {
+    throw new Error(`Subagent already exists: ${filePath}. Use --force to overwrite.`);
+  }
+
+  const title = name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  const content = `---
+name: ${name}
+description: "TODO: describe what this agent specialises in"
+tools: [read, search]
+model: Auto (copilot)
+metadata:
+  scope:
+    tags: []
+---
+# ${title}
+
+<!-- System prompt for this sub-agent -->
+
+## Expertise
+
+<!-- Describe the agent's domain knowledge -->
+
+## Instructions
+
+<!-- Step-by-step workflow the agent should follow -->
+`;
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, 'utf8');
+  logger.info(`Subagent created: ${filePath}`);
+}
+
+async function runAddCommand({ options, logger }) {
+  const name = typeof options.name === 'string' ? options.name.trim() : '';
+  if (!name) throw new Error('add-command requires --name <command-name>.');
+  validateKebabName(name, 'Command name');
+
+  const { layerRoot } = resolveLayerForAdd(options);
+  const filePath = path.join(layerRoot, 'commands', `${name}.md`);
+
+  if ((await pathExists(filePath)) && !options.force) {
+    throw new Error(`Command already exists: ${filePath}. Use --force to overwrite.`);
+  }
+
+  const title = name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  const content = `---
+metadata:
+  scope:
+    tags: []
+---
+# ${title}
+
+## Usage
+
+<!-- Describe when and how to invoke this command -->
+
+## Steps
+
+1. <!-- Step 1 -->
+2. <!-- Step 2 -->
+`;
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, 'utf8');
+  logger.info(`Command created: ${filePath}`);
+}
+
+async function runAddReference({ options, logger }) {
+  const name = typeof options.name === 'string' ? options.name.trim() : '';
+  if (!name) throw new Error('add-reference requires --name <reference-name>.');
+  validateKebabName(name, 'Reference name');
+
+  const { layerRoot } = resolveLayerForAdd(options);
+  const filePath = path.join(layerRoot, 'references', `${name}.md`);
+
+  if ((await pathExists(filePath)) && !options.force) {
+    throw new Error(`Reference already exists: ${filePath}. Use --force to overwrite.`);
+  }
+
+  const title = name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+  const content = `# ${title}
+
+<!-- Reference content that other rules/skills can link to via .agents/references/${name}.md -->
+`;
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, 'utf8');
+  logger.info(`Reference created: ${filePath}`);
+}
+
+// ---------------------------------------------------------------------------
+// init
+// ---------------------------------------------------------------------------
+
+const STARTER_TAGS = [
+  'clean-code', 'testing', 'docs', 'frontend', 'backend', 'fullstack',
+];
+
+async function runInit({ options, logger }) {
+  const configRoot = resolveConfigRoot(options);
+
+  if ((await pathExists(path.join(configRoot, 'config'))) && !options.force) {
+    throw new Error(
+      `Config hub already exists at ${configRoot}. Use --force to re‑initialise.`
+    );
+  }
+
+  const requestedTargets = parseCsvOption(options.targets);
+  const allowedTargets = new Set(['copilot', 'codex', 'cursor', 'claude']);
+  const targets = (requestedTargets.length > 0 ? requestedTargets : ['codex'])
+    .map((t) => t.toLowerCase());
+  for (const t of targets) {
+    if (!allowedTargets.has(t)) {
+      throw new Error(`Unsupported target "${t}". Allowed: copilot,codex,cursor,claude.`);
+    }
+  }
+
+  // Scaffold global layer
+  const globalLayerRoot = path.join(configRoot, 'layers', 'global');
+  await scaffoldLayer({ layerRoot: globalLayerRoot });
+
+  // Default profile
+  const profileBody = {
+    name: 'default',
+    targets,
+    layers: [{ name: 'global', select: createDefaultLayerSelect() }],
+  };
+  await ensureDir(path.join(configRoot, 'config', 'profiles'));
+  await writeJson(path.join(configRoot, 'config', 'profiles', 'default.json'), profileBody);
+
+  // Starter tags
+  await ensureDir(path.join(configRoot, 'config', 'definitions'));
+  await writeJson(path.join(configRoot, 'config', 'definitions', 'scope-tags.json'), STARTER_TAGS);
+
+  logger.info(`Initialised config hub at ${configRoot}`);
+  logger.info(`Default profile: targets=[${targets.join(',')}], layers=[global]`);
+  logger.info('Next: agentfold create-layer --name <team> && agentfold create-profile --name <team> --layers <team>');
+}
+
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+
+async function runStatus({ options, logger }) {
+  const configRoot = resolveConfigRoot(options);
+  const projectRoot = path.resolve(String(options.project || process.cwd()));
+
+  // Load profile
+  let preset;
+  try {
+    preset = await loadProfile({
+      configRoot,
+      profileNameOverride: options.profile ? String(options.profile) : undefined,
+    });
+  } catch (err) {
+    logger.error(`Could not load profile: ${err.message}`);
+    return;
+  }
+
+  console.log(`Config:   ${configRoot}`);
+  console.log(`Profile:  ${preset.profileName} (${preset.profilePath})`);
+
+  const enabledTargets = Object.entries(preset.targets)
+    .filter(([, enabled]) => enabled)
+    .map(([name]) => name);
+  console.log(`Targets:  ${enabledTargets.join(', ') || '(none)'}`);
+
+  // Layers
+  let layers;
+  try {
+    layers = await resolveLayerPaths({ configRoot, preset });
+  } catch {
+    layers = [];
+  }
+
+  console.log(`Layers:   ${layers.length}`);
+  for (const layer of layers) {
+    const files = await listFiles(layer.path);
+    console.log(`  ${layer.name} — ${layer.path} (${files.length} file(s))`);
+  }
+
+  // Tags
+  console.log(`Tags:     ${preset.scopeTags.length}`);
+
+  // Manifest
+  const manifest = await loadManifest(projectRoot);
+  if (manifest) {
+    console.log(`Manifest: ${manifest.files.length} managed file(s), generated ${manifest.generatedAt}`);
+  } else {
+    console.log('Manifest: (none — run agentfold apply first)');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// doctor
+// ---------------------------------------------------------------------------
+
+async function runDoctor({ options, logger }) {
+  const configRoot = resolveConfigRoot(options);
+  const projectRoot = path.resolve(String(options.project || process.cwd()));
+  const checks = [];
+
+  function pass(label) { checks.push({ label, result: 'pass' }); }
+  function fail(label, detail) { checks.push({ label, result: 'FAIL', detail }); }
+  function warn(label, detail) { checks.push({ label, result: 'warn', detail }); }
+
+  // 1. Config root exists
+  if (await pathExists(configRoot)) {
+    pass(`Config root exists: ${configRoot}`);
+  } else {
+    fail('Config root exists', `Missing at ${configRoot} — run agentfold init`);
+  }
+
+  // 2. Load profile
+  let preset;
+  try {
+    preset = await loadProfile({
+      configRoot,
+      profileNameOverride: options.profile ? String(options.profile) : undefined,
+    });
+    pass(`Profile "${preset.profileName}" loads successfully`);
+  } catch (err) {
+    fail('Profile loads successfully', err.message);
+    printDoctorResults(checks);
+    return;
+  }
+
+  // 3. At least one target enabled
+  const enabledTargets = Object.entries(preset.targets)
+    .filter(([, enabled]) => enabled)
+    .map(([name]) => name);
+  if (enabledTargets.length > 0) {
+    pass(`Targets enabled: ${enabledTargets.join(', ')}`);
+  } else {
+    fail('At least one target enabled', 'No targets enabled');
+  }
+
+  // 4. Layer resolution
+  let layers = [];
+  try {
+    layers = await resolveLayerPaths({ configRoot, preset });
+    pass(`All ${layers.length} layer(s) resolve`);
+  } catch (err) {
+    fail('All layers resolve', err.message);
+  }
+
+  // 5. Canonical subdirectories in each layer
+  const canonicalDirs = ['agents', 'commands', 'mcp', 'references', 'rules', 'skills', 'subagents'];
+  for (const layer of layers) {
+    const missing = [];
+    for (const dir of canonicalDirs) {
+      if (!(await pathExists(path.join(layer.path, dir)))) {
+        missing.push(dir);
+      }
+    }
+    if (missing.length === 0) {
+      pass(`Layer "${layer.name}" has all canonical folders`);
+    } else {
+      warn(`Layer "${layer.name}" canonical folders`, `Missing: ${missing.join(', ')}`);
+    }
+  }
+
+  // 6. Tags validation
+  const scopeTagSet = new Set(preset.scopeTags);
+  let tagErrors = 0;
+  for (const layer of preset.layers) {
+    for (const type of selectableTypes) {
+      for (const tag of layer.select[type].tags.values) {
+        if (!scopeTagSet.has(tag)) {
+          fail(`Tag "${tag}" in ${layer.name}.${type}`, 'Not in scope-tags.json');
+          tagErrors++;
+        }
+      }
+    }
+  }
+  if (tagErrors === 0) {
+    pass('All profile tags are defined');
+  }
+
+  // 7. Orphaned layers — layers on disk not referenced by the active profile
+  const referencedNames = new Set(preset.layers.map((l) => l.name));
+  const layersDir = path.join(configRoot, 'layers');
+  if (await pathExists(layersDir)) {
+    const entries = await fs.readdir(layersDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && !referencedNames.has(entry.name)) {
+        warn(`Orphan layer: ${entry.name}`, 'Exists on disk but not in active profile');
+      }
+    }
+  }
+
+  // 8. Manifest staleness
+  const manifest = await loadManifest(projectRoot);
+  if (manifest) {
+    if (manifest.profile === preset.profileName) {
+      pass('Manifest matches active profile');
+    } else {
+      warn('Manifest profile mismatch', `Manifest: ${manifest.profile}, Active: ${preset.profileName}`);
+    }
+  } else {
+    warn('Manifest', 'No manifest found — run agentfold apply');
+  }
+
+  printDoctorResults(checks);
+}
+
+function printDoctorResults(checks) {
+  const icons = { pass: '✓', FAIL: '✗', warn: '!' };
+  let failures = 0;
+  for (const c of checks) {
+    const icon = icons[c.result] || '?';
+    const detail = c.detail ? ` — ${c.detail}` : '';
+    console.log(`  [${icon}] ${c.label}${detail}`);
+    if (c.result === 'FAIL') failures++;
+  }
+  if (failures > 0) {
+    process.exitCode = 1;
+    console.log(`\n${failures} check(s) failed.`);
+  } else {
+    console.log('\nAll checks passed.');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// list-layers
+// ---------------------------------------------------------------------------
+
+async function runListLayers({ options, logger }) {
+  const configRoot = resolveConfigRoot(options);
+  const found = [];
+
+  const layersDir = path.join(configRoot, 'layers');
+  if (await pathExists(layersDir)) {
+    const entries = await fs.readdir(layersDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        const layerPath = path.join(layersDir, entry.name);
+        const files = await listFiles(layerPath);
+        found.push({ name: entry.name, path: layerPath, files: files.length });
+      }
+    }
+  }
+
+  found.sort((a, b) => a.name.localeCompare(b.name));
+  if (found.length === 0) {
+    logger.info('No layers found.');
+    return;
+  }
+
+  for (const layer of found) {
+    console.log(`${layer.name}  ${layer.files} file(s)  ${layer.path}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// list-profiles
+// ---------------------------------------------------------------------------
+
+async function runListProfiles({ options, logger }) {
+  const configRoot = resolveConfigRoot(options);
+  const found = [];
+
+  const profilesDir = path.join(configRoot, 'config', 'profiles');
+  if (await pathExists(profilesDir)) {
+    const entries = await fs.readdir(profilesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.json')) {
+        const profilePath = path.join(profilesDir, entry.name);
+        try {
+          const raw = await readJson(profilePath);
+          found.push({
+            name: entry.name.replace(/\.json$/, ''),
+            path: profilePath,
+            layers: Array.isArray(raw.layers) ? raw.layers.length : 0,
+            targets: Array.isArray(raw.targets) ? raw.targets.join(',') : '',
+          });
+        } catch {
+          found.push({ name: entry.name.replace(/\.json$/, ''), path: profilePath, layers: '?', targets: '?' });
+        }
+      }
+    }
+  }
+
+  found.sort((a, b) => a.name.localeCompare(b.name));
+  if (found.length === 0) {
+    logger.info('No profiles found.');
+    return;
+  }
+
+  for (const p of found) {
+    console.log(`${p.name}  ${p.layers} layer(s)  targets=${p.targets}  ${p.path}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// explain
+// ---------------------------------------------------------------------------
+
+async function runExplain({ options, logger }) {
+  const filePath = typeof options.file === 'string' ? options.file.trim() : '';
+  if (!filePath) {
+    throw new Error('explain requires --file <path> pointing to a source content file.');
+  }
+
+  const configRoot = resolveConfigRoot(options);
+  const resolvedFile = path.resolve(filePath);
+
+  if (!(await pathExists(resolvedFile))) {
+    throw new Error(`File not found: ${resolvedFile}`);
+  }
+
+  // Load profile
+  const preset = await loadProfile({
+    configRoot,
+    profileNameOverride: options.profile ? String(options.profile) : undefined,
+  });
+  const layers = await resolveLayerPaths({ configRoot, preset });
+
+  // Determine which layer this file belongs to
+  let matchedLayer = null;
+  let relativeInLayer = null;
+  for (const layer of layers) {
+    const layerAbs = path.resolve(layer.path);
+    if (resolvedFile.startsWith(layerAbs + path.sep)) {
+      matchedLayer = layer;
+      relativeInLayer = path.relative(layerAbs, resolvedFile);
+      break;
+    }
+  }
+
+  if (!matchedLayer) {
+    console.log(`File is NOT inside any resolved layer for profile "${preset.profileName}".`);
+    console.log(`Resolved layers:`);
+    for (const l of layers) console.log(`  ${l.name} → ${l.path}`);
+    return;
+  }
+
+  console.log(`File:    ${resolvedFile}`);
+  console.log(`Layer:   ${matchedLayer.name} (${matchedLayer.path})`);
+  console.log(`Rel:     ${relativeInLayer}`);
+
+  // Determine content type from first path segment
+  const firstSegment = relativeInLayer.split(path.sep)[0];
+  const typeMap = {
+    skills: 'skills', rules: 'rules', commands: 'commands',
+    mcp: 'mcp', subagents: 'subagents', agents: 'agents',
+    references: 'references',
+  };
+  const contentType = typeMap[firstSegment] || null;
+  console.log(`Type:    ${contentType || '(unknown)'}`);
+
+  if (!contentType || !selectableTypes.includes(contentType)) {
+    console.log('Result:  INCLUDED (no scope filtering applies to this type)');
+    return;
+  }
+
+  // Check scope selector
+  const selector = matchedLayer.select[contentType];
+  const hasActiveSelector = selector.namespaces.length > 0 || selector.tags.values.length > 0;
+  if (!hasActiveSelector) {
+    console.log('Select:  (empty — all content passes)');
+    console.log('Result:  INCLUDED');
+    return;
+  }
+
+  console.log(`Select:  namespaces=${JSON.stringify(selector.namespaces)} tags=${JSON.stringify(selector.tags)}`);
+
+  // Parse frontmatter
+  const { normalizeScopeMetadata, matchesScope } = await import('./lib/scope.mjs');
+  const { parseFrontMatter } = await import('./lib/util.mjs');
+  const text = await fs.readFile(resolvedFile, 'utf8');
+  const fm = parseFrontMatter(text);
+  if (!fm) {
+    console.log('Front:   (none)');
+    console.log('Result:  EXCLUDED (no front matter to match against non-empty selector)');
+    return;
+  }
+
+  const metadata = normalizeScopeMetadata(fm);
+  console.log(`Front:   namespace="${metadata.namespace}" tags=${JSON.stringify(metadata.tags)}`);
+
+  const matched = matchesScope({ selector, metadata });
+  console.log(`Result:  ${matched ? 'INCLUDED' : 'EXCLUDED'}`);
+}
+
+// ---------------------------------------------------------------------------
+// render pipeline helpers
+// ---------------------------------------------------------------------------
+
+async function writeRenderMapToDirectory(renderMap, rootDir) {
+  await removeDir(rootDir);
+  await ensureDir(rootDir);
+
+  const entries = [...renderMap.entries()].sort(([a], [b]) => a.localeCompare(b));
+  for (const [relativePath, record] of entries) {
+    const destination = path.join(rootDir, relativePath);
+    await ensureDir(path.dirname(destination));
+    await fs.writeFile(destination, record.content, 'utf8');
+  }
+}
+
+async function gatherContext({ options, logger }) {
+  const configRoot = resolveConfigRoot(options);
+  const projectRoot = path.resolve(String(options.project || process.cwd()));
+  const outputRoot = path.resolve(String(options.output || path.join(configRoot, 'out')));
+
+  const preset = await loadProfile({
+    configRoot,
+    profileNameOverride: options.profile ? String(options.profile) : undefined,
+  });
+
+  const layers = await resolveLayerPaths({ configRoot, preset });
+  const build = await buildRenderPlan({
+    preset,
+    layers,
+    logger,
+    projectRoot,
+    configRoot,
+  });
+  const validation = await validatePlan({
+    preset,
+    layers,
+    skillDefinitions: build.skillDefinitions,
+    promptDefinitions: build.promptDefinitions,
+    subagentDefinitions: build.subagentDefinitions,
+  });
+
+  return { configRoot, projectRoot, outputRoot, preset, layers, build, validation };
+}
+
+function printValidation(validation, logger) {
+  for (const warning of validation.warnings) {
+    logger.warn(`Warning: ${warning}`);
+  }
+
+  if (validation.errors.length > 0) {
+    for (const error of validation.errors) {
+      logger.error(`Error: ${error}`);
+    }
+  }
+}
+
+async function runLint({ options, logger }) {
+  const context = await gatherContext({ options, logger });
+  printValidation(context.validation, logger);
+
+  if (context.validation.errors.length > 0) {
+    throw new Error(`Lint failed with ${context.validation.errors.length} error(s).`);
+  }
+
+  logger.info('Lint passed.');
+}
+
+async function runBuild({ options, logger }) {
+  const context = await gatherContext({ options, logger });
+  printValidation(context.validation, logger);
+
+  if (context.validation.errors.length > 0) {
+    throw new Error(`Build halted due to ${context.validation.errors.length} lint error(s).`);
+  }
+
+  await writeRenderMapToDirectory(context.build.renderMap, context.outputRoot);
+  logger.info(`Build complete: ${context.outputRoot}`);
+}
+
+async function ensureBuilt(context, logger) {
+  if (!(await pathExists(context.outputRoot))) {
+    logger.info('Build output missing; generating it now...');
+    await writeRenderMapToDirectory(context.build.renderMap, context.outputRoot);
+  }
+}
+
+function printDiff(diff) {
+  console.log(`Added: ${diff.added.length}`);
+  for (const relativePath of diff.added) {
+    console.log(`  + ${relativePath}`);
+  }
+
+  console.log(`Changed: ${diff.changed.length}`);
+  for (const relativePath of diff.changed) {
+    console.log(`  ~ ${relativePath}`);
+  }
+
+  console.log(`Removed: ${diff.removed.length}`);
+  for (const relativePath of diff.removed) {
+    console.log(`  - ${relativePath}`);
+  }
+}
+
+async function runDiff({ options, logger }) {
+  const context = await gatherContext({ options, logger });
+  printValidation(context.validation, logger);
+
+  if (context.validation.errors.length > 0) {
+    throw new Error(`Diff halted due to ${context.validation.errors.length} lint error(s).`);
+  }
+
+  await ensureBuilt(context, logger);
+  const previousManifest = await loadManifest(context.projectRoot);
+  const diff = await diffRenderMapAgainstProject({
+    renderMap: context.build.renderMap,
+    projectRoot: context.projectRoot,
+    previousManifest,
+  });
+
+  printDiff(diff);
+  if (diff.added.length + diff.changed.length + diff.removed.length > 0) {
+    process.exitCode = 1;
+  }
+}
+
+async function runApply({ options, logger }) {
+  const context = await gatherContext({ options, logger });
+  printValidation(context.validation, logger);
+
+  if (context.validation.errors.length > 0) {
+    throw new Error(`Apply halted due to ${context.validation.errors.length} lint error(s).`);
+  }
+
+  await ensureBuilt(context, logger);
+  const previousManifest = await loadManifest(context.projectRoot);
+  const diff = await diffRenderMapAgainstProject({
+    renderMap: context.build.renderMap,
+    projectRoot: context.projectRoot,
+    previousManifest,
+  });
+
+  if (options['dry-run']) {
+    logger.info('Apply dry-run mode. No files written.');
+    printDiff(diff);
+    return;
+  }
+
+  const sortedEntries = [...context.build.renderMap.entries()].sort(([a], [b]) => a.localeCompare(b));
+  for (const [relativePath, record] of sortedEntries) {
+    const destination = path.join(context.projectRoot, relativePath);
+    await ensureDir(path.dirname(destination));
+    await fs.writeFile(destination, record.content, 'utf8');
+  }
+
+  let deleted = [];
+  const isConfigRootProject =
+    path.resolve(context.projectRoot) === path.resolve(context.configRoot);
+  if (options.prune) {
+    deleted = await pruneManagedFiles({
+      previousManifest,
+      renderMap: context.build.renderMap,
+      projectRoot: context.projectRoot,
+      preservePaths: isConfigRootProject ? ['AGENTS.md'] : [],
+    });
+  }
+
+  const manifest = await writeManifest({
+    projectRoot: context.projectRoot,
+    preset: context.preset,
+    renderMap: context.build.renderMap,
+  });
+
+  logger.info(`Apply complete. Wrote ${manifest.files.length} managed file(s).`);
+  if (deleted.length > 0) {
+    logger.info(`Pruned ${deleted.length} stale generated file(s).`);
+    for (const relativePath of deleted) {
+      logger.info(`  - ${toPosixPath(relativePath)}`);
+    }
+  }
+}
+
+async function main() {
+  const { positional, options } = parseCliArgs(process.argv.slice(2));
+  const command = positional[0];
+  const logger = createLogger({ quiet: Boolean(options.quiet) });
+
+  if (options.version || command === '--version') {
+    const pkg = await readJson(path.join(kitRoot, 'package.json'));
+    console.log(`agentfold v${pkg.version}`);
+    return;
+  }
+
+  if (!command || command === 'help' || command === '--help') {
+    usage();
+    return;
+  }
+
+  const commands = [
+    'lint', 'build', 'diff', 'apply',
+    'init', 'status', 'doctor',
+    'create-layer', 'create-profile',
+    'list-layers', 'list-profiles',
+    'list-tags', 'add-tag', 'delete-tag',
+    'add-rule', 'add-skill', 'add-subagent', 'add-command', 'add-reference',
+    'explain',
+  ];
+
+  if (!commands.includes(command)) {
+    usage();
+    throw new Error(`Unknown command: ${command}`);
+  }
+
+  if (options.preset) {
+    throw new Error('The --preset option is no longer supported. Use --profile.');
+  }
+
+  if (options.bundled) {
+    throw new Error('The --bundled option is no longer supported. All content lives in the config hub (--config or ~/.agentfold).');
+  }
+
+  const dispatch = {
+    lint: runLint,
+    build: runBuild,
+    diff: runDiff,
+    apply: runApply,
+    init: runInit,
+    status: runStatus,
+    doctor: runDoctor,
+    'create-layer': runCreateLayer,
+    'create-profile': runCreateProfile,
+    'list-layers': runListLayers,
+    'list-profiles': runListProfiles,
+    'list-tags': runListTags,
+    'add-tag': runAddTag,
+    'delete-tag': runDeleteTag,
+    'add-rule': runAddRule,
+    'add-skill': runAddSkill,
+    'add-subagent': runAddSubagent,
+    'add-command': runAddCommand,
+    'add-reference': runAddReference,
+    explain: runExplain,
+  };
+
+  await dispatch[command]({ options, logger });
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});