contextos-agents 2.1.1 → 2.2.0

package/.agents/ctx.js

@@ -55,10 +55,13 @@ function printHelp() {
   console.log('  watch                           Start continuous file watcher and auto-sync daemon');
   console.log('  init                            Show initialization guide');
   console.log('  install-skill <ref>             Alias for skill add (install a plugin)');
-  console.log('  skill add   <ref>               Install a plugin skill (GitHub or npm)');
+  console.log('  skill add   <ref|--all>         Install a plugin skill or all catalog skills (--all)');
   console.log('  skill remove <name>             Uninstall a plugin skill');
-  console.log('  skill list                      List installed skills (builtin + plugins)');
+  console.log('  skill list [--available]        List installed skills (and available catalog skills)');
   console.log('  skill search [query]            Search the community skill registry');
+  console.log('  skill override <name>           Create editable project copy of an upstream skill');
+  console.log('  skill diff <name>               Show differences between local override and upstream');
+  console.log('  skill eject <name>              Eject upstream skill to standalone project skill');
   console.log('');
   console.log('Plugin ref formats:');
   console.log('  username/repo                    GitHub repo root SKILL.md');
@@ -634,15 +637,17 @@ if (command === 'export') {
   }
 
   if (subcommand === 'add') {
+    const isAll = args.includes('--all') || ref === '--all' || ref === 'all';
     const forceUnsafe = args.includes('--force-unsafe-prompts') || args.includes('--force-unsafe');
-    plugins.add(ref, { dryRun, checksum, forceUnsafe }).catch(err => {
+    plugins.add(isAll ? '--all' : ref, { dryRun, checksum, forceUnsafe, all: isAll }).catch(err => {
       console.error(`[ERROR] ${err.message}`);
       process.exit(1);
     });
   } else if (subcommand === 'remove') {
     plugins.remove(ref);
   } else if (subcommand === 'list') {
-    plugins.list();
+    const available = args.includes('--available') || args.includes('-a') || args.includes('--all');
+    plugins.list({ available });
   } else if (subcommand === 'search') {
     const query = args.slice(2).join(' ');
     plugins.search(query).catch(err => {

package/.agents/plugins.js

@@ -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 = {
@@ -291,7 +310,7 @@ function parseRef(ref, projectRoot = null) {
 
   // 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(path.resolve(__dirname, '..'), 'catalog', 'skills', ref);
+  const pkgCatalogPath = path.join(getCatalogDir(), ref);
   if (fs.existsSync(pkgCatalogPath) && fs.existsSync(path.join(pkgCatalogPath, 'SKILL.md'))) {
     return {
       type: 'catalog',
@@ -636,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]
@@ -650,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');
@@ -663,7 +814,37 @@ async function add(ref, options = {}) {
     throw new Error(`Invalid plugin name derived from reference: '${skillName}'`);
   }
 
-  // Supply-chain source pinning check (Wave 6)
+  // 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(
       {
@@ -688,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);
@@ -779,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);
@@ -898,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)')}`);
   }
@@ -924,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/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.1.1
+      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.2.0
         with:
-          version: '2.1.1'       # 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
 ```

package/bin/index.js

@@ -7,6 +7,7 @@ const profiles = require('../.agents/profiles.js');
 const { isKnownCommand, getStatus, formatStatusText } = require('./commands.js');
 const { detectProjectAttributes } = require('./lib/detector.js');
 const lockfileLib = require('./lib/lockfile.js');
+const ui = require('./lib/ui.js');
 
 // ── CLI argument parsing ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
@@ -41,6 +42,27 @@ const flags = {
     return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? args[i + 1] : null;
   })(),
   githubAnnotations: args.includes('--github-annotations'),
+  all:         args.includes('--all') || args.includes('--full'),
+  preset:      (() => {
+    const i = args.indexOf('--preset');
+    return i !== -1 && args[i + 1] && !args[i + 1].startsWith('-') ? args[i + 1].toLowerCase() : null;
+  })(),
+};
+
+const PRESETS = {
+  frontend: [
+    'react', 'react-best-practices', 'nextjs', 'typescript',
+    'ui-ux-pro', 'impeccable-design', 'state-management', 'web-accessibility'
+  ],
+  backend: [
+    'node', 'fastapi', 'nestjs', 'system-design',
+    'api-design', 'microservices', 'ddd', 'database'
+  ],
+  devops: [
+    'docker', 'ci-cd', 'terraform', 'security-audit'
+  ],
+  full: null,
+  all: null,
 };
 
 // ── Help / Version ────────────────────────────────────────────────────────────
@@ -71,6 +93,8 @@ Options:
   --dry-run           Preview what will be copied without making changes
   --force             Overwrite an existing .agents/ folder
   --minimal           Install only 7 core skills (lightweight footprint)
+  --all, --full       Install all 36 catalog skills alongside 7 core skills
+  --preset <name>     Install domain preset (frontend, backend, devops, full)
   --profile <name>    Install a specific profile (mvp, startup, enterprise, frontend, backend)
   --auto              Auto-detect tech stack and apply recommended profile
   --project <path>    Specify target project root directory (default: current directory)
@@ -82,6 +106,7 @@ Options:
 
 Commands:
   init                Install and configure .agents/ in target project
+  skill <subcmd>      Manage skills (add, remove, list, search, override, diff, eject)
   gate                Run deterministic quality gate against adapter drift
   status              Display project configuration, active profile, and lockfile status
   update              Safely update skills without overwriting custom changes
@@ -119,9 +144,14 @@ Plugin ref formats:
   @scope/npm-package               A scoped npm skill package
 
 Examples:
-  npx contextos-agents init                     Install .agents/ with auto-detected stack
+  npx contextos-agents init                     Install Lean Core (7 foundational skills)
+  npx contextos-agents init --all               Install ContextOS with all 43 skills
+  npx contextos-agents init --preset frontend   Install ContextOS with frontend domain skills
   npx contextos-agents init --agent auto        Install and configure for detected stack & IDE
-  npx contextos-agents init --minimal           Install only 7 core essential skills
+  npx contextos skill add <name>                Install a domain skill from catalog
+  npx contextos skill add --all                 Install all catalog skills into existing project
+  npx contextos skill list --available          List all available catalog domain skills
+  npx contextos skill override <name>           Create editable local copy of a skill
   npx contextos status                          Show project configuration and lockfile status
   npx contextos doctor                          Run project health check
   npx contextos export gemini                   Compile skills for Gemini
@@ -178,7 +208,7 @@ if (mainCommand === 'detect') {
       }, null, 2));
     } else {
       console.log('\n══════════════════════════════════════════');
-      console.log('  ContextOS — Workspace Scoped Detection');
+      console.log('  ContextOS - Workspace Scoped Detection');
       console.log('══════════════════════════════════════════\n');
       console.log(`  Scope Path       : ${scopeArg}`);
       if (nearestPkg) {
@@ -193,7 +223,7 @@ if (mainCommand === 'detect') {
         if (evidence.length > 0) {
           console.log('\n  Scoped Evidence:');
           for (const ev of evidence.slice(0, 10)) {
-            console.log(`    • [${ev.source}] ${ev.target} (+${ev.weight}) — ${ev.description}`);
+            console.log(`    • [${ev.source}] ${ev.target} (+${ev.weight}) - ${ev.description}`);
           }
           if (evidence.length > 10) {
             console.log(`      ... and ${evidence.length - 10} more signals`);
@@ -212,7 +242,7 @@ if (mainCommand === 'detect') {
     }, null, 2));
   } else if (explain) {
     console.log('\n══════════════════════════════════════════');
-    console.log('  ContextOS — Workspace Evidence Graph');
+    console.log('  ContextOS - Workspace Evidence Graph');
     console.log('══════════════════════════════════════════\n');
     console.log(`  Repository Root  : ${graph.repositoryRoot}`);
     console.log(`  Fingerprint      : ${graph.fingerprint}`);
@@ -234,7 +264,7 @@ if (mainCommand === 'detect') {
     console.log('──────────────────────────────────────────\n');
   } else {
     const detection = detectProjectAttributes(process.cwd());
-    console.log('\nContextOS — Tech Stack & Environment Detection\n');
+    console.log('\nContextOS - Tech Stack & Environment Detection\n');
     console.log(`  Repository Root       : ${graph.repositoryRoot}`);
     console.log(`  Packages Detected     : ${graph.packages.map(p => `${p.id} (${p.root})`).join(', ')}`);
     console.log(`  Detected Technologies : ${detection.summary.technologies.join(', ')}`);
@@ -480,7 +510,32 @@ if (mainCommand === 'install-skill') {
           }).on('error', reject);
         });
         
-        const registry = await fetchRegistry();
+        let registry;
+        try {
+          registry = await fetchRegistry();
+        } catch {
+          const catalogDir = path.join(__dirname, '..', 'catalog', 'skills');
+          if (fs.existsSync(catalogDir)) {
+            const catalogSkills = fs.readdirSync(catalogDir).filter(n => {
+              try {
+                return fs.statSync(path.join(catalogDir, n)).isDirectory();
+              } catch {
+                return false;
+              }
+            });
+            registry = {
+              skills: catalogSkills.map(name => ({
+                name,
+                description: `Domain catalog skill: ${name}`,
+                github: null,
+                npm: name,
+              })),
+            };
+          } else {
+            console.error('[ERROR] Could not fetch remote registry and local catalog is unavailable.');
+            process.exit(1);
+          }
+        }
         const skillsList = (registry.skills || []).map((s, idx) => ({
           idx: idx + 1,
           name: s.name,
@@ -606,6 +661,13 @@ function installAtomically(source, target, options = {}) {
         return true;
       },
     });
+
+    const catalogSrc = path.join(__dirname, '..', 'catalog');
+    const catalogDest = path.join(stagingPath, 'catalog');
+    if (fs.existsSync(catalogSrc)) {
+      fs.cpSync(catalogSrc, catalogDest, { recursive: true, force: true });
+    }
+
     if (fs.existsSync(target)) {
       fs.renameSync(target, backupPath);
       movedExisting = true;
@@ -686,7 +748,7 @@ if (flags.dryRun) {
 
   console.log('[DRY-RUN] No files will be written.\n');
   if (fs.existsSync(targetPath)) {
-    console.log(`[WARN] .agents/ already exists — would be overwritten with --force.`);
+    console.log(`[WARN] .agents/ already exists - would be overwritten with --force.`);
   } else {
     console.log(`[OK] Would create .agents/ in: ${process.cwd()}`);
   }
@@ -706,7 +768,13 @@ if (flags.dryRun) {
 
 // ── Main install ──────────────────────────────────────────────────────────────
 if (!flags.json) {
-  console.log('Installing AI assistant skills (.agents/)...');
+  ui.renderBanner(version);
+  ui.renderStep(1, 4, 'Analyzing project environment & tech stack',
+    stackDetection.detected.length > 0
+      ? `Detected stack: ${stackDetection.detected.join(', ')}`
+      : 'Detected stack: Generic JavaScript environment'
+  );
+  console.log('');
 }
 
 try {
@@ -746,18 +814,14 @@ try {
   }
 
   if (!flags.json) {
-    console.log('[OK] .agents/ successfully installed in your project!');
-    if (flags.minimal) {
-      console.log('[OK] Minimal profile: 5 core skills installed.');
-      console.log('     (engineering-workflow, ponytail-mindset, gstack-roles, gemini-precision, react)');
-      console.log('     Tip: Add more skills anytime with: contextos skill add <name>');
-    }
-    if (stackDetection.detected.length > 0) {
-      console.log(`[OK] Detected project stack: ${stackDetection.detected.join(', ')}`);
-    }
-    if (ideDetection.detected.length > 0) {
-      console.log(`[OK] Detected developer environment: ${ideDetection.detected.join(', ')}`);
-    }
+    ui.renderStep(2, 4, 'Deploying Lean Core engine (.agents/)', [
+      'Installed 7 foundational core skills in .agents/core/skills/',
+      'Why 7? ContextOS uses a Lean Core to keep your AI context small, fast, and token-efficient.',
+      'To add domain skills (React, FastAPI, Docker, etc.): npx contextos skill add <name> (or --all)',
+    ]);
+    console.log('');
+    ui.renderStep(3, 4, 'Generating lockfile & security governance', 'contextos.lock.json synchronized');
+    console.log('');
   }
 
   // ── Deprecation warning for --with-mcp ────────────────────────────────────────────────
@@ -771,7 +835,7 @@ try {
   if (selectedProfile) {
     try {
       const applied = profiles.applyProfile(selectedProfile, process.cwd());
-      if (!flags.json) console.log(`[OK] Applied profile '${applied.name}' (excluded: ${(applied.exclude_skills || []).join(', ') || 'none'})`);
+      if (!flags.json) console.log(`  [OK] Applied profile '${applied.name}' (excluded: ${(applied.exclude_skills || []).join(', ') || 'none'})\n`);
     } catch (e) {
       if (flags.json) {
         console.error(JSON.stringify({ success: false, error: `Could not apply profile '${selectedProfile}': ${e.message}` }));
@@ -782,58 +846,112 @@ try {
     }
   }
 
-  if (!flags.json) {
-    console.log('[OK] Your AI assistant now has skills and rules configured.\n');
-  }
-
   // ── Auto-compile skills for target agents ──────────────────────────────────
   if (!flags.skipCompile) {
     const ctxPath = path.join(targetPath, 'ctx.js');
     if (fs.existsSync(ctxPath)) {
+      if (!flags.json) {
+        ui.renderStep(4, 4, 'Configuring AI assistants & compiling rules', `${targetAgents.join(', ')} synchronized`);
+        console.log('');
+      }
       const { execFileSync } = require('child_process');
       for (const ag of targetAgents) {
-        if (!flags.json) console.log(`Compiling skills for ${ag}...`);
         try {
           execFileSync(process.execPath, [ctxPath, 'export', ag], {
             cwd: process.cwd(),
-            stdio: flags.json ? 'ignore' : 'inherit',
+            stdio: 'ignore',
           });
         } catch (e) {
           if (flags.json) {
             console.error(JSON.stringify({ success: false, error: `Skill compilation for '${ag}' failed` }));
           } else {
-            console.error(`[ERROR] Skill compilation for '${ag}' failed — run manually: contextos export ${ag}`);
+            console.error(`  [ERROR] Skill compilation for '${ag}' failed - run manually: contextos export ${ag}`);
           }
           process.exit(1);
         }
       }
     }
   } else if (!flags.json) {
-    console.log('Tip: Run `contextos export gemini` to compile skills.');
+    ui.renderStep(4, 4, 'Configuring AI assistants & compiling rules', [
+      'Skipped auto-compilation (--skip-compile)',
+      'Tip: Run `contextos export gemini` to compile skills when ready.',
+    ]);
+    console.log('');
   }
 
   // ── --add-skill flag ────────────────────────────────────────────────────────
   if (flags.addSkill) {
-    const ctxPath = path.join(targetPath, 'ctx.js');
-    if (fs.existsSync(ctxPath)) {
+    const packageCtxPath = path.join(__dirname, '..', '.agents', 'ctx.js');
+    const ctxScript = fs.existsSync(packageCtxPath) ? packageCtxPath : path.join(targetPath, 'ctx.js');
+    if (fs.existsSync(ctxScript)) {
       if (!flags.json) console.log(`Installing plugin skill: ${flags.addSkill}`);
       try {
         const { execFileSync } = require('child_process');
-        execFileSync(process.execPath, [ctxPath, 'skill', 'add', flags.addSkill], {
+        const catalogDir = path.join(__dirname, '..', 'catalog', 'skills');
+        const subEnv = { ...process.env, CONTEXTOS_CATALOG_DIR: catalogDir };
+        execFileSync(process.execPath, [ctxScript, 'skill', 'add', flags.addSkill], {
           cwd: process.cwd(),
           stdio: flags.json ? 'ignore' : 'inherit',
+          env: subEnv,
         });
       } catch (e) {
         if (flags.json) {
           console.error(JSON.stringify({ success: false, error: `Skill install failed for ${flags.addSkill}` }));
         } else {
-          console.error(`[ERROR] Skill install failed — run manually: node .agents/ctx.js skill add ${flags.addSkill}`);
+          console.error(`[ERROR] Skill install failed - run manually: node .agents/ctx.js skill add ${flags.addSkill}`);
         }
         process.exit(1);
       }
     }
   }
 
+  // ── --all / --preset flags ──────────────────────────────────────────────────
+  if (flags.all || flags.preset) {
+    const packageCtxPath = path.join(__dirname, '..', '.agents', 'ctx.js');
+    const ctxScript = fs.existsSync(packageCtxPath) ? packageCtxPath : path.join(targetPath, 'ctx.js');
+    if (fs.existsSync(ctxScript)) {
+      const presetKey = flags.all ? 'full' : (flags.preset || 'full');
+      const { execFileSync } = require('child_process');
+      const catalogDir = path.join(__dirname, '..', 'catalog', 'skills');
+      const subEnv = { ...process.env, CONTEXTOS_CATALOG_DIR: catalogDir };
+
+      if (presetKey === 'full' || presetKey === 'all') {
+        if (!flags.json) console.log('\nInstalling all 36 catalog skills (--all)...');
+        try {
+          execFileSync(process.execPath, [ctxScript, 'skill', 'add', '--all'], {
+            cwd: process.cwd(),
+            stdio: flags.json ? 'ignore' : 'inherit',
+            env: subEnv,
+          });
+        } catch (e) {
+          if (!flags.json) console.error('  [WARN] Failed to install catalog skills:', e.message);
+        }
+      } else if (PRESETS[presetKey]) {
+        if (!flags.json) console.log(`  Installing preset '${presetKey}' skills:`);
+        const totalSkills = PRESETS[presetKey].length;
+        let count = 0;
+        for (const skillName of PRESETS[presetKey]) {
+          count++;
+          if (!flags.json) {
+            ui.renderProgressBar(count, totalSkills, skillName);
+          }
+          try {
+            execFileSync(process.execPath, [ctxScript, 'skill', 'add', skillName], {
+              cwd: process.cwd(),
+              stdio: 'ignore',
+              env: subEnv,
+            });
+          } catch (e) {
+            if (!flags.json) console.error(`\n  [WARN] Failed to install preset skill '${skillName}':`, e.message);
+          }
+        }
+        if (!flags.json) console.log('\n');
+      } else {
+        if (!flags.json) console.error(`  [WARN] Unknown preset '${flags.preset}'. Supported presets: frontend, backend, devops, full`);
+      }
+    }
+  }
+
   if (flags.json) {
     console.log(JSON.stringify({
       success: true,
@@ -844,27 +962,15 @@ try {
       agents: targetAgents,
       withMcp: flags.withMcp,
       minimal: flags.minimal,
+      all: flags.all,
+      preset: flags.preset,
     }, null, 2));
     process.exit(0);
   }
 
-  console.log('\n Next steps:');
-  console.log('  1. Open your project in your AI assistant');
-  console.log('  2. The assistant will automatically load .agents/AGENTS.md');
-  console.log('  3. Inspect project health anytime:');
-  console.log('       contextos doctor');
-  console.log('  4. Switch profiles anytime:');
-  console.log('       contextos profile list');
-  console.log('       contextos profile apply mvp');
-  console.log('  5. Export to other AI tools:');
-  console.log('       contextos export cursor   → .cursorrules & .cursor/rules');
-  console.log('       contextos export copilot  → .github/copilot-instructions.md');
-  console.log('       contextos export aider    → .aider.conf.yml + CONVENTIONS.md');
-  console.log('  6. Add community skills (plugins):');
-  console.log('       contextos skill add   username/my-skill');
-  console.log('       contextos skill list');
-
-  console.log('');
+  if (!flags.json) {
+    ui.renderSuccessCard();
+  }
 
 } catch (error) {
   if (flags.json) {

package/bin/lib/ui.js

@@ -0,0 +1,140 @@
+/**
+ * bin/lib/ui.js
+ * Terminal visual formatting & progress helpers for ContextOS.
+ * Zero external dependencies - uses standard Node.js ANSI and process streams.
+ */
+
+'use strict';
+
+const isTTY = Boolean(process.stdout && process.stdout.isTTY && !process.env.CI && process.env.NODE_ENV !== 'test');
+const noColor = Boolean(process.env.NO_COLOR || (!isTTY && !process.env.FORCE_COLOR));
+
+const c = {
+  cyan:    (s) => noColor ? s : `\x1b[36m${s}\x1b[0m`,
+  green:   (s) => noColor ? s : `\x1b[32m${s}\x1b[0m`,
+  yellow:  (s) => noColor ? s : `\x1b[33m${s}\x1b[0m`,
+  red:     (s) => noColor ? s : `\x1b[31m${s}\x1b[0m`,
+  blue:    (s) => noColor ? s : `\x1b[34m${s}\x1b[0m`,
+  magenta: (s) => noColor ? s : `\x1b[35m${s}\x1b[0m`,
+  dim:     (s) => noColor ? s : `\x1b[2m${s}\x1b[0m`,
+  bold:    (s) => noColor ? s : `\x1b[1m${s}\x1b[0m`,
+  gray:    (s) => noColor ? s : `\x1b[90m${s}\x1b[0m`,
+};
+
+/**
+ * Render a sleek ASCII brand banner with version.
+ */
+function renderBanner(version) {
+  const title = `ContextOS  v${version}`;
+  const subtitle = 'Deterministic Context & Policy Engine for Coding Agents';
+  const width = Math.max(title.length, subtitle.length) + 6;
+  const topBorder    = ` ╭${'─'.repeat(width)}╮`;
+  const bottomBorder = ` ╰${'─'.repeat(width)}╯`;
+
+  console.log('\n' + c.cyan(topBorder));
+  console.log(` ${c.cyan('│')}   ${c.bold(c.cyan('ContextOS'))}  ${c.dim('v' + version)}${' '.repeat(width - title.length - 3)}${c.cyan('│')}`);
+  console.log(` ${c.cyan('│')}   ${c.gray(subtitle)}${' '.repeat(width - subtitle.length - 3)}${c.cyan('│')}`);
+  console.log(c.cyan(bottomBorder) + '\n');
+}
+
+/**
+ * Format a step badge: e.g. [1/4]
+ */
+function formatStepBadge(step, total) {
+  return c.cyan(`[${step}/${total}]`);
+}
+
+/**
+ * Render an installation step with title and detailed item.
+ */
+function renderStep(step, total, title, detail = null, isSuccess = true) {
+  const badge = formatStepBadge(step, total);
+  console.log(`  ${badge}  ${c.bold(title)}`);
+  if (detail) {
+    const symbol = isSuccess ? c.green('✓') : c.yellow('•');
+    if (Array.isArray(detail)) {
+      if (detail.length > 0) {
+        console.log(`         ${symbol} ${detail[0]}`);
+        for (let i = 1; i < detail.length; i++) {
+          console.log(`           ${c.dim(detail[i])}`);
+        }
+      }
+    } else {
+      console.log(`         ${symbol} ${detail}`);
+    }
+  }
+}
+
+/**
+ * Render an interactive or batch progress bar for skills/files.
+ */
+function renderProgressBar(current, total, label = '', width = 26) {
+  const percent = total > 0 ? Math.min(100, Math.round((current / total) * 100)) : 100;
+  const filledCount = total > 0 ? Math.min(width, Math.round((current / total) * width)) : width;
+  const emptyCount = Math.max(0, width - filledCount);
+
+  const filledBar = '█'.repeat(filledCount);
+  const emptyBar  = '░'.repeat(emptyCount);
+  const barStr = `${c.cyan(filledBar)}${c.dim(emptyBar)}`;
+  const progressText = `[${barStr}] ${String(percent).padStart(3)}% (${current}/${total})${label ? ' ' + c.gray(label) : ''}`;
+
+  if (isTTY) {
+    process.stdout.write(`\r  ${progressText}   `);
+    if (current >= total) {
+      process.stdout.write('\n');
+    }
+  } else {
+    // In CI or non-TTY test runners, log only at completion to avoid log bloat
+    if (current === total) {
+      console.log(`  ${progressText}`);
+    }
+  }
+}
+
+/**
+ * Render the final readiness card with next steps and commands.
+ */
+function stripAnsi(str) {
+  return String(str).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function renderCardLine(content, innerWidth = 62) {
+  const visible = stripAnsi(content);
+  const padding = Math.max(0, innerWidth - visible.length);
+  return ` ${c.green('│')}  ${content}${' '.repeat(padding)}${c.green('│')}`;
+}
+
+/**
+ * Render the final readiness card with next steps and commands.
+ */
+function renderSuccessCard(options = {}) {
+  const innerWidth = 62;
+  const topBorder    = ` ╭${'─'.repeat(innerWidth + 2)}╮`;
+  const bottomBorder = ` ╰${'─'.repeat(innerWidth + 2)}╯`;
+
+  console.log('\n' + c.green(topBorder));
+  console.log(renderCardLine(c.bold(c.green('✓ Project ready for AI coding agents!')), innerWidth));
+  console.log(renderCardLine('', innerWidth));
+  console.log(renderCardLine(c.bold('Next steps:'), innerWidth));
+  console.log(renderCardLine(`1. Open project in your AI assistant (${c.cyan('Gemini')}, ${c.cyan('Cursor')}, ${c.cyan('Copilot')})`, innerWidth));
+  console.log(renderCardLine(`   Rules are auto-loaded from ${c.cyan('.agents/AGENTS.md')}`, innerWidth));
+  console.log(renderCardLine('', innerWidth));
+  console.log(renderCardLine('2. Explore and install domain skills:', innerWidth));
+  console.log(renderCardLine(`   ${c.cyan('contextos skill list --available')}`, innerWidth));
+  console.log(renderCardLine(`   ${c.cyan('contextos skill add <name>')}    (or ${c.cyan('--all')})`, innerWidth));
+  console.log(renderCardLine('', innerWidth));
+  console.log(renderCardLine('3. Inspect project health anytime:', innerWidth));
+  console.log(renderCardLine(`   ${c.cyan('contextos doctor')}`, innerWidth));
+  console.log(c.green(bottomBorder) + '\n');
+}
+
+module.exports = {
+  isTTY,
+  noColor,
+  c,
+  renderBanner,
+  formatStepBadge,
+  renderStep,
+  renderProgressBar,
+  renderSuccessCard,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "contextos-agents",
-    "version":  "2.1.1",
+    "version":  "2.2.0",
     "description":  "Deterministic context and policy compiler for supported AI coding agents.",
     "bin":  {
                 "contextos":  "./bin/index.js",