contextos-agents 2.1.0 → 2.2.0

package/.agents/plugins.js

@@ -26,7 +26,7 @@ const https   = require('https');
 const crypto  = require('crypto');
 const { execFileSync } = require('child_process');
 const { ProjectMutationLock } = require('./filesystem/project-lock.js');
-const JournaledTransaction = require('./filesystem/journaled-transaction.js');
+const { JournaledTransaction } = require('./filesystem/journaled-transaction.js');
 const {
   calculateTreeDigest,
   validateArchiveEntry,
@@ -47,6 +47,25 @@ const REGISTRY_URL   = 'https://raw.githubusercontent.com/kok-o/contextos-agents
 const MAX_DOWNLOAD_BYTES = 5 * 1024 * 1024;
 const SAFE_SKILL_NAME = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 
+function getCatalogDir() {
+  if (process.env.CONTEXTOS_CATALOG_DIR && fs.existsSync(process.env.CONTEXTOS_CATALOG_DIR)) {
+    return process.env.CONTEXTOS_CATALOG_DIR;
+  }
+  const localAgentsCatalog = path.join(__dirname, 'catalog', 'skills');
+  if (fs.existsSync(localAgentsCatalog)) return localAgentsCatalog;
+
+  const relativeCatalog = path.join(path.resolve(__dirname, '..'), 'catalog', 'skills');
+  if (fs.existsSync(relativeCatalog)) return relativeCatalog;
+
+  try {
+    const pkgPath = require.resolve('contextos-agents/package.json', { paths: [__dirname, process.cwd()] });
+    const pkgCatalog = path.join(path.dirname(pkgPath), 'catalog', 'skills');
+    if (fs.existsSync(pkgCatalog)) return pkgCatalog;
+  } catch {}
+
+  return null;
+}
+
 // ── ANSI helpers ──────────────────────────────────────────────────────────────
 const NO_COLOR = process.env.NO_COLOR || !process.stdout.isTTY;
 const c = {
@@ -284,11 +303,49 @@ function isValidNpmPackage(name) {
   return /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/.test(name);
 }
 
-function parseRef(ref) {
+function parseRef(ref, projectRoot = null) {
   if (typeof ref !== 'string' || !ref.trim()) {
     throw new Error('A plugin reference is required');
   }
 
+  // 1. Built-in package catalog skills take strict precedence for catalog names.
+  // Consumer project local files can never spoof or hijack package catalog skills.
+  const pkgCatalogPath = path.join(getCatalogDir(), ref);
+  if (fs.existsSync(pkgCatalogPath) && fs.existsSync(path.join(pkgCatalogPath, 'SKILL.md'))) {
+    return {
+      type: 'catalog',
+      name: ref,
+      path: pkgCatalogPath,
+      isPinned: true,
+      raw: ref,
+    };
+  }
+
+  // 2. Explicit local references (must start with 'local:', './', '../', or 'file:')
+  if (ref.startsWith('local:') || ref.startsWith('./') || ref.startsWith('../') || ref.startsWith('file:')) {
+    const rawTarget = ref.startsWith('local:')
+      ? ref.slice(6)
+      : (ref.startsWith('file:') ? ref.slice(5) : ref);
+
+    const baseRoot = projectRoot || process.cwd();
+    let localDir = path.resolve(baseRoot, rawTarget);
+    if (!fs.existsSync(localDir)) {
+      localDir = path.join(baseRoot, 'catalog', 'skills', rawTarget);
+    }
+
+    if (fs.existsSync(localDir) && fs.existsSync(path.join(localDir, 'SKILL.md'))) {
+      const skillName = path.basename(localDir);
+      return {
+        type: 'catalog',
+        name: skillName,
+        path: localDir,
+        isPinned: true,
+        raw: ref,
+      };
+    }
+    throw new Error(`Local skill not found at: '${ref}'`);
+  }
+
   // Scoped packages contain a slash but are npm packages, not GitHub refs.
   if (ref.startsWith('@')) {
     if (!isValidNpmPackage(ref)) {
@@ -529,6 +586,62 @@ function installFromNpm(descriptor, skillName, dryRun, checksum, forceUnsafe = f
   return sha256;
 }
 
+// ── Catalog installer ─────────────────────────────────────────────────────────
+function installFromCatalog(descriptor, skillName, dryRun, checksum, forceUnsafe = false, tx = null) {
+  const sourceDir = descriptor.path;
+  const targetDir = path.join(PLUGINS_DIR, skillName);
+  const relTargetDir = toPosix(path.relative(ROOT, targetDir));
+
+  if (dryRun) {
+    console.log(c.dim(`  [DRY-RUN] Would copy catalog skill from: ${sourceDir}`));
+    return 'sha256:0000000000000000000000000000000000000000000000000000000000000000';
+  }
+
+  function copyRecursive(src, dest, relDest) {
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      const relPath = toPosix(path.join(relDest, entry.name));
+
+      if (entry.isDirectory()) {
+        copyRecursive(srcPath, destPath, relPath);
+      } else {
+        const content = fs.readFileSync(srcPath, 'utf8');
+        if (tx) {
+          tx.stageWrite(relPath, content);
+        } else {
+          fs.writeFileSync(destPath, content, 'utf8');
+        }
+      }
+    }
+  }
+
+  copyRecursive(sourceDir, targetDir, relTargetDir);
+
+  const primarySkillMd = path.join(sourceDir, 'SKILL.md');
+  const sha256 = fs.existsSync(primarySkillMd) ? crypto.createHash('sha256').update(fs.readFileSync(primarySkillMd)).digest('hex') : null;
+
+  const sourceMeta = {
+    source: 'catalog',
+    name: skillName,
+    path: toPosix(path.relative(ROOT, sourceDir)),
+    sha256,
+    installedAt: new Date().toISOString(),
+  };
+  if (tx) {
+    tx.stageWrite(`${relTargetDir}/.source`, JSON.stringify(sourceMeta, null, 2) + '\n');
+  } else {
+    fs.writeFileSync(path.join(targetDir, '.source'), JSON.stringify(sourceMeta, null, 2) + '\n');
+  }
+
+  console.log(c.green(`  ✓ Installed from built-in catalog: ${skillName}`));
+  return sha256;
+}
+
 // ── Derive skill name from ref ────────────────────────────────────────────────
 function deriveSkillName(ref) {
   // username/repo/path/to/my-skill → my-skill
@@ -542,9 +655,137 @@ function isSafeSkillName(skillName) {
   return typeof skillName === 'string' && SAFE_SKILL_NAME.test(skillName);
 }
 
-// ═════════════════════════════════════════════════════════════════════════════
-//  COMMANDS
-// ═════════════════════════════════════════════════════════════════════════════
+function findClosestSkill(target, candidates) {
+  let closest = null;
+  let minDistance = Infinity;
+  for (const item of candidates) {
+    if (item === target) return item;
+    if (item.includes(target) || target.includes(item)) return item;
+    const dist = levenshtein(target, item);
+    if (dist < minDistance && dist <= 3) {
+      minDistance = dist;
+      closest = item;
+    }
+  }
+  return closest;
+}
+
+function levenshtein(a, b) {
+  const m = a.length, n = b.length;
+  const d = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) d[i][0] = i;
+  for (let j = 0; j <= n; j++) d[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+    }
+  }
+  return d[m][n];
+}
+
+/**
+ * Batch install all available catalog skills.
+ */
+async function addAllFromCatalog(options = {}) {
+  const dryRun = Boolean(options.dryRun || options['dry-run']);
+  const force = Boolean(options.force);
+  const catalogDir = getCatalogDir();
+  if (!fs.existsSync(catalogDir)) {
+    throw new Error('Catalog directory not found in package');
+  }
+
+  const catalogSkills = fs.readdirSync(catalogDir).filter(n => {
+    const full = path.join(catalogDir, n);
+    return fs.statSync(full).isDirectory() && fs.existsSync(path.join(full, 'SKILL.md'));
+  });
+
+  console.log('');
+  console.log(c.bold(`Batch installing ${catalogSkills.length} catalog skills...`));
+
+  const lock = readLock();
+  const existingNames = new Set(lock.plugins.map(p => p.name));
+
+  const projectLock = new ProjectMutationLock(ROOT);
+  const tx = new JournaledTransaction(ROOT);
+  let lockToken = null;
+
+  let installedCount = 0;
+  let skippedCount = 0;
+  const newlyInstalled = [];
+
+  try {
+    lockToken = projectLock.acquire({ command: 'skill:add-all' });
+
+    for (const skillName of catalogSkills) {
+      if (existingNames.has(skillName) && !force) {
+        skippedCount++;
+        continue;
+      }
+
+      const descriptor = {
+        type: 'catalog',
+        name: skillName,
+        path: path.join(catalogDir, skillName),
+        isPinned: true,
+        raw: skillName,
+      };
+
+      const installedSha256 = installFromCatalog(descriptor, skillName, dryRun, null, false, tx);
+
+      if (!dryRun) {
+        const idx = lock.plugins.findIndex(p => p.name === skillName);
+        const entry = {
+          name: skillName,
+          ref: skillName,
+          type: 'catalog',
+          sha256: installedSha256,
+          installedAt: new Date().toISOString(),
+        };
+        if (idx >= 0) lock.plugins[idx] = entry;
+        else lock.plugins.push(entry);
+        newlyInstalled.push(skillName);
+      }
+      installedCount++;
+    }
+
+    if (!dryRun) {
+      writeLock(lock, tx);
+      tx.commit();
+
+      for (const skillName of newlyInstalled) {
+        const targetDir = path.join(PLUGINS_DIR, skillName);
+        if (fs.existsSync(targetDir)) {
+          const digestResult = calculateTreeDigest(targetDir);
+          const entry = lock.plugins.find(p => p.name === skillName);
+          if (entry) entry.treeDigest = digestResult.treeDigest;
+        }
+      }
+      writeLock(lock);
+    }
+
+    console.log('');
+    if (dryRun) {
+      console.log(c.dim(`[DRY-RUN] Would install ${installedCount} skills (${skippedCount} already installed - skipped).`));
+    } else {
+      console.log(c.green(c.bold(`✓ Batch install complete: ${installedCount} catalog skills installed.`)));
+      if (skippedCount > 0) {
+        console.log(c.dim(`  (${skippedCount} skills already installed - skipped)`));
+      }
+      console.log('');
+      console.log('  Next steps:');
+      console.log('    node .agents/ctx.js export all    # recompile with new skills');
+      console.log('    node .agents/ctx.js validate      # verify consistency');
+    }
+
+    return { installedCount, skippedCount };
+  } catch (err) {
+    console.error(c.red(`\n[ERROR] Batch installation failed: ${err.message}`));
+    process.exit(1);
+  } finally {
+    if (lockToken) projectLock.release(lockToken);
+  }
+}
 
 /**
  * skill add <ref> [--dry-run] [--checksum <sha256>] [--force-unsafe-prompts]
@@ -556,6 +797,10 @@ async function add(ref, options = {}) {
   const allowFloating = Boolean(options.allowFloating || options['allow-floating']);
   const force = Boolean(options.force);
 
+  if (ref === '--all' || ref === 'all' || options.all) {
+    return await addAllFromCatalog(options);
+  }
+
   if (!ref) {
     console.error(c.red('Usage: ctx.js skill add <ref> [--checksum <sha256>]'));
     console.error('  ref can be: username/repo, username/repo/path/to/skill, or npm-package-name');
@@ -569,8 +814,38 @@ async function add(ref, options = {}) {
     throw new Error(`Invalid plugin name derived from reference: '${skillName}'`);
   }
 
-  // Supply-chain source pinning check (Wave 6)
-  if (!dryRun) {
+  // 1. Check for conflict with builtin skills first
+  const builtinPath = path.join(CORE_SKILLS, skillName);
+  if (fs.existsSync(builtinPath)) {
+    console.error(c.red(`\n[ERROR] '${skillName}' conflicts with a built-in skill.`));
+    console.error(c.red('  Built-in skills cannot be overridden via --add-skill.'));
+    console.error(c.dim(`  To customize a built-in skill for your project, run: contextos skill override ${skillName}`));
+    process.exit(1);
+  }
+
+  // 2. If single word not in catalog, check for typo suggestion
+  if (descriptor.type !== 'catalog' && !ref.includes('/') && !ref.includes('@')) {
+    const catalogDir = getCatalogDir();
+    if (fs.existsSync(catalogDir)) {
+      const catalogSkills = fs.readdirSync(catalogDir).filter(n => {
+        try {
+          return fs.statSync(path.join(catalogDir, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+      const suggestion = findClosestSkill(skillName, catalogSkills);
+      if (suggestion) {
+        console.error(c.red(`\n[ERROR] Skill '${skillName}' not found in catalog.`));
+        console.log(c.yellow(`  Did you mean: "${suggestion}"?`));
+        console.log(c.dim('  Run "contextos skill list --available" to see all catalog skills.'));
+        process.exit(1);
+      }
+    }
+  }
+
+  // 3. Supply-chain source pinning check (Wave 6)
+  if (!dryRun && descriptor.type !== 'catalog') {
     const pinning = validatePluginPinning(
       {
         type: descriptor.type,
@@ -594,15 +869,6 @@ async function add(ref, options = {}) {
   console.log(c.bold(`Installing skill: ${c.cyan(skillName)}`));
   console.log(c.dim(`  Source: ${ref} (${descriptor.type})`));
 
-  // Check for conflict with builtin skills
-  const builtinPath = path.join(CORE_SKILLS, skillName);
-  if (fs.existsSync(builtinPath)) {
-    console.error(c.red(`\n[ERROR] '${skillName}' conflicts with a built-in skill.`));
-    console.error(c.red('  Built-in skills cannot be overridden via --add-skill.'));
-    console.error(c.dim('  To customize a built-in skill, fork the repo and submit a PR.'));
-    process.exit(1);
-  }
-
   // Check if already installed
   const lock     = readLock();
   const existing = lock.plugins.find(p => p.name === skillName);
@@ -637,7 +903,9 @@ async function add(ref, options = {}) {
     lockToken = projectLock.acquire({ command: 'skill:add' });
 
     let installedSha256 = null;
-    if (descriptor.type === 'github') {
+    if (descriptor.type === 'catalog') {
+      installedSha256 = installFromCatalog(descriptor, skillName, dryRun, checksum, forceUnsafe, tx);
+    } else if (descriptor.type === 'github') {
       installedSha256 = await installFromGitHub(descriptor, skillName, dryRun, checksum, forceUnsafe, tx);
     } else {
       installedSha256 = installFromNpm(descriptor, skillName, dryRun, checksum, forceUnsafe, tx);
@@ -683,6 +951,21 @@ async function add(ref, options = {}) {
       // We don't need to do anything since it wasn't committed
     }
     console.error(c.red(`\n[ERROR] Failed to install '${skillName}': ${err.message}`));
+    const catalogDir = getCatalogDir();
+    if (fs.existsSync(catalogDir)) {
+      const catalogSkills = fs.readdirSync(catalogDir).filter(n => {
+        try {
+          return fs.statSync(path.join(catalogDir, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+      const suggestion = findClosestSkill(skillName, catalogSkills);
+      if (suggestion) {
+        console.log(c.yellow(`  Did you mean: "${suggestion}"?`));
+        console.log(c.dim('  Run "contextos skill list --available" to see all catalog skills.'));
+      }
+    }
     process.exit(1);
   } finally {
     if (lockToken) projectLock.release(lockToken);
@@ -802,25 +1085,46 @@ function remove(skillName) {
 }
 
 /**
- * skill list
+ * skill list [options]
  */
-function list() {
+function list(options = {}) {
+  const showAvailable = Boolean(options.available || options['--available'] || options.all);
   const lock = readLock();
 
   // Builtin skills
   const builtins = fs.existsSync(CORE_SKILLS)
-    ? fs.readdirSync(CORE_SKILLS).filter(n => fs.statSync(path.join(CORE_SKILLS, n)).isDirectory())
+    ? fs.readdirSync(CORE_SKILLS).filter(n => {
+        try {
+          return fs.statSync(path.join(CORE_SKILLS, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
     : [];
 
   // Plugin skills
   const plugins = lock.plugins;
 
+  // Catalog skills
+  const catalogDir = getCatalogDir();
+  const catalogSkills = fs.existsSync(catalogDir)
+    ? fs.readdirSync(catalogDir).filter(n => {
+        try {
+          return fs.statSync(path.join(catalogDir, n)).isDirectory();
+        } catch {
+          return false;
+        }
+      })
+    : [];
+  const installedNames = new Set(plugins.map(p => p.name));
+  const availableCatalog = catalogSkills.filter(n => !installedNames.has(n));
+
   console.log('');
   console.log(c.bold('ContextOS Skills'));
   console.log('');
 
   // Built-ins
-  console.log(c.bold(`  Built-in (${builtins.length})`));
+  console.log(c.bold(`  Built-in Core (${builtins.length})`));
   for (const name of builtins) {
     console.log(`    ${c.cyan('●')} ${name}  ${c.dim('(core)')}`);
   }
@@ -828,22 +1132,39 @@ function list() {
   // Plugins
   console.log('');
   if (plugins.length === 0) {
-    console.log(c.bold('  Plugins (0)'));
-    console.log(c.dim('    No plugins installed yet.'));
-    console.log(c.dim('    Install one: node .agents/ctx.js skill add username/my-skill'));
+    console.log(c.bold('  Installed Plugins & Domain Skills (0)'));
+    console.log(c.dim('    No domain skills or plugins installed yet.'));
+    console.log(c.dim('    Install one: contextos skill add <name>  (or --all)'));
   } else {
-    console.log(c.bold(`  Plugins (${plugins.length})`));
+    console.log(c.bold(`  Installed Plugins & Domain Skills (${plugins.length})`));
     for (const p of plugins) {
       const when = p.installedAt ? new Date(p.installedAt).toLocaleDateString() : '?';
       console.log(`    ${c.green('●')} ${p.name}  ${c.dim(`← ${p.ref}  (installed ${when})`)}`);
     }
   }
 
+  // Available in Catalog
+  console.log('');
+  if (showAvailable || availableCatalog.length > 0) {
+    console.log(c.bold(`  Available in Catalog (${availableCatalog.length})`));
+    if (showAvailable) {
+      for (const name of availableCatalog) {
+        console.log(`    ${c.dim('○')} ${name}`);
+      }
+      console.log('');
+      console.log(c.dim('  Install with: contextos skill add <name>  (or contextos skill add --all)'));
+    } else {
+      console.log(c.dim(`    ${availableCatalog.length} domain skills available in local catalog.`));
+      console.log(c.dim('    Run "contextos skill list --available" to see all, or install with:'));
+      console.log(c.dim('    contextos skill add <name>  |  contextos skill add --all'));
+    }
+  }
+
   console.log('');
 }
 
 /**
- * skill search <query>  — searches the hosted registry.json
+ * skill search <query> - searches the hosted registry.json
  */
 async function search(query) {
   console.log(c.dim(`\nFetching registry from: ${REGISTRY_URL}\n`));

package/.agents/profiles.js

@@ -298,14 +298,26 @@ function validateProfile(profile, registry = null) {
 }
 
 /**
- * Lists all available project profiles defined in core/profiles.
+ * Lists all available project profiles defined in core/profiles and optionally consumer project.
+ * Searches built-in profiles in packageRoot, and if projectRoot is supplied, searches
+ * consumer project .agents/profiles, .agents/core/profiles, and profiles directories.
  *
+ * @param {string|null} [projectRoot=null] - Optional consumer project root
  * @returns {ProfileConfig[]} Array of profile configurations
  */
-function listProfiles() {
+function listProfiles(projectRoot = null) {
   const profiles = [];
   const searchDirs = [PROFILES_DIR, path.join(AGENTS_DIR, 'catalog', 'presets')];
 
+  if (projectRoot) {
+    const absConsumer = path.resolve(projectRoot);
+    searchDirs.push(
+      path.join(absConsumer, '.agents', 'profiles'),
+      path.join(absConsumer, '.agents', 'core', 'profiles'),
+      path.join(absConsumer, 'profiles')
+    );
+  }
+
   for (const dir of searchDirs) {
     if (!fs.existsSync(dir)) continue;
     const files = fs.readdirSync(dir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
@@ -314,22 +326,31 @@ function listProfiles() {
       const parsed = parseYamlProfile(content);
       if (!parsed.id) parsed.id = path.basename(file, path.extname(file));
       if (!parsed.name) parsed.name = parsed.id;
-      profiles.push(parsed);
+
+      // Consumer profiles can override or extend built-in profiles; deduplicate by id
+      const normId = parsed.id.toLowerCase();
+      const existingIdx = profiles.findIndex(p => p.id.toLowerCase() === normId);
+      if (existingIdx !== -1) {
+        profiles[existingIdx] = parsed;
+      } else {
+        profiles.push(parsed);
+      }
     }
   }
   return profiles;
 }
 
 /**
- * Finds a profile by its slug ID or title.
+ * Finds a profile by its slug ID or title across package and consumer roots.
  *
  * @param {string} name - Profile identifier or name
+ * @param {string|null} [projectRoot=null] - Optional consumer project root
  * @returns {ProfileConfig|null} Found profile or null
  */
-function getProfile(name) {
+function getProfile(name, projectRoot = null) {
   if (!name) return null;
   const clean = name.toLowerCase().trim();
-  const all = listProfiles();
+  const all = listProfiles(projectRoot);
   return all.find(p => p.id.toLowerCase() === clean || p.name.toLowerCase() === clean) || null;
 }
 
@@ -398,7 +419,7 @@ function getActiveProfile(projectDir = process.cwd(), targetFileOrScope = null)
     }
 
     if (matchedProfileName) {
-      const overrideProf = getProfile(matchedProfileName);
+      const overrideProf = getProfile(matchedProfileName, projectDir);
       if (overrideProf) {
         return {
           ...overrideProf,
@@ -424,9 +445,9 @@ function getActiveProfile(projectDir = process.cwd(), targetFileOrScope = null)
  * @returns {Object} Updated profile lock data
  */
 function applyProfile(profileName, projectDir = process.cwd(), options = {}) {
-  const profile = getProfile(profileName);
+  const profile = getProfile(profileName, projectDir);
   if (!profile) {
-    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles().map(p => p.id).join(', ')}`);
+    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles(projectDir).map(p => p.id).join(', ')}`);
   }
 
   validateProfile(profile);
@@ -563,9 +584,9 @@ function removeActiveProfile(projectDir = process.cwd(), options = {}) {
  * @returns {Object} Explanation structure
  */
 function explainProfile(profileName, projectDir = process.cwd()) {
-  const profile = getProfile(profileName);
+  const profile = getProfile(profileName, projectDir);
   if (!profile) {
-    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles().map(p => p.id).join(', ')}`);
+    throw new Error(`Profile '${profileName}' not found. Available profiles: ${listProfiles(projectDir).map(p => p.id).join(', ')}`);
   }
 
   return {

package/README.md

@@ -40,7 +40,16 @@ You do not need to clone anything manually. Just open your terminal in the root
 npx contextos-agents init
 ```
 
-The script will automatically detect your project tech stack, create the `.agents` folder, configure a neutral bootstrap profile, and compile it for your AI agent.
+By default, ContextOS sets up a focused **Lean Core** (7 essential skills: `engineering-workflow`, `ponytail-mindset`, `gemini-precision`, `security`, `context-os`, `context-manager`, and `gstack-roles`). This ensures your AI agent context remains lightweight and focused, preventing context degradation.
+
+Want more skills right away? Install pre-packaged presets or the entire catalog:
+
+```bash
+npx contextos-agents init --preset frontend   # React, Next.js, TypeScript, UI/UX, a11y
+npx contextos-agents init --preset backend    # System design, API design, Node.js, databases
+npx contextos-agents init --preset devops     # Docker, CI/CD, Terraform
+npx contextos-agents init --all               # Install all 36 catalog skills at once
+```
 
 ### Options
 
@@ -48,6 +57,8 @@ The script will automatically detect your project tech stack, create the `.agent
 npx contextos-agents --help             # Show all options
 npx contextos-agents --version          # Show version
 npx contextos-agents --minimal          # Install only the core bootstrap skills
+npx contextos-agents --all              # Install all 36 catalog domain skills during init
+npx contextos-agents --preset <name>    # Install stack preset: frontend, backend, devops, full
 npx contextos-agents --profile init     # Install with specific profile
 npx contextos-agents --auto             # Auto-detect tech stack and apply recommended profile
 npx contextos-agents --dry-run          # Preview what will be installed
@@ -110,6 +121,30 @@ contextos resolve "Build an accessible modal component with React and Tailwind"
 contextos resolve "security review" --files apps/web/app/login/page.tsx --explain
 ```
 
+### Skill & Catalog Management (`contextos skill`)
+
+Discover, install, and customize skills:
+
+```bash
+# Explore all available catalog skills (36 domain skills):
+contextos skill list --available
+
+# Install a specific skill from the catalog (with typo suggestions):
+contextos skill add fastapi
+
+# Install all 36 catalog skills at once:
+contextos skill add --all
+
+# Fork a built-in skill into your project for team customizations:
+contextos skill override gemini-precision
+
+# Diff your local customizations against upstream updates:
+contextos skill diff gemini-precision
+
+# Eject a skill to decouple it from upstream updates:
+contextos skill eject gemini-precision
+```
+
 ### Diagnostic Health Check (`contextos doctor`)
 
 Run a comprehensive pre-flight verification across your repository to ensure valid skills, profile alignment, and compiler synchronization:
@@ -172,9 +207,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.0.0
+      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.2.0
         with:
-          version: '2.0.0'       # Pinned version of contextos-agents runner
+          version: '2.2.0'       # Pinned version of contextos-agents runner
           adapters: 'all'        # Adapters to verify (or specific: 'cursor', 'claude')
           working-directory: '.' # Project root directory
 ```