contextos-agents 2.1.1 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://github.com/kok-o/contextos-agents">
-    <img src="./Frame%202.png" alt="ContextOS Logo" width="88" height="88" />
+    <img src="./assets/logo.png" alt="ContextOS Logo" width="88" height="88" />
   </a>
 </p>
 
@@ -30,7 +30,7 @@
 
 ---
 
-ContextOS is a deterministic context and policy compiler for AI coding agents. It transforms your team's version-controlled engineering rules into focused, verifiable context for Gemini, Claude Code, Cursor, GitHub Copilot, Aider, and Zed - and detects configuration drift in CI.
+ContextOS is a deterministic context and policy compiler for AI coding agents. It exports version-controlled engineering rules and detects configuration drift in CI. See the [adapter compatibility matrix](docs/ADAPTER_COMPATIBILITY.md) for native paths, instruction indexes and manual templates; client loader verification is separate from export tests.
 
 ## Installation
 
@@ -40,14 +40,43 @@ 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 installs seven core skills: `engineering-workflow`, `ponytail-mindset`, `gemini-precision`, `security`, `context-os`, `context-manager`, and `gstack-roles`, then exports Gemini workspace skills. Supporting examples and references remain separate files. The actual context loaded and session cost depend on your client and task; ContextOS does not control an external client's chat history.
+
+Codex also discovers the shared `.agents/skills` directory. The default Cursor
+export always applies only the compact project bootstrap; skill bodies load by
+file patterns or agent request. Resolver token budgets are soft: mandatory safety
+guidance survives with an overflow warning. The experimental MCP prompt assembler
+keeps selected bodies whole and can reject an explicit hard character limit.
+
+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
 
+Try the [small local demo](examples/quickstart/README.md) to install the current
+candidate in a new folder, select a TypeScript skill, and add a team rule without
+calling a model API. The [five-minute guide](docs/product/onboarding.md) explains
+the same workflow for an existing project.
+
+For the current R2 candidates, see the [release preparation status](docs/R2_RELEASE_PREPARATION.md)
+and [upgrade/checkpoint rollback](docs/COMPACT_CONTEXT_MIGRATION.md). The
+[release manifest](docs/evidence/release-2.3.json) records the verified source,
+cross-platform CI and candidate archive identities. The client pilot and
+publication decision remain pending. Internal plans, local API probes
+and raw logs are excluded from the public release surface.
+
 ```bash
 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 +139,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:
@@ -153,12 +206,14 @@ contextos hook uninstall
 
 ### CI Quality Gate (`contextos gate`)
 
-Run the complete 8-point production quality gate locally:
+Check that generated adapter files match source skills and the active profile:
 
 ```bash
 contextos gate
 ```
 
+This is a configuration drift gate. Run your application's tests, typecheck and security checks separately. `resolve` recommends skills for a task; ordinary exports use all installed skills allowed by the profile. Resolver budgets are soft estimates of selected skill bodies and exclude client instructions, chat history and tool output.
+
 ### CI Quality Gate Action (contextos-gate)
 
 Guard your repository against skill drift, missing outputs, and rule regressions using the official GitHub Composite Action:
@@ -172,9 +227,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. Default init exports Gemini workspace skills.', innerWidth));
+  console.log(renderCardLine(`   Other clients: ${c.cyan('contextos export <agent>')}`, 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.3.0",
     "description":  "Deterministic context and policy compiler for supported AI coding agents.",
     "bin":  {
                 "contextos":  "./bin/index.js",
@@ -47,10 +47,13 @@
                     "validate:catalog":  "node .agents/ctx.js validate --catalog",
                     "lint:md":  "markdownlint README.md CONTRIBUTING.md GUIDE.md \".agents/core/skills/**/*.md\" --ignore \".agents/generated/**\" --config .markdownlint.json",
                     "check:secrets":  "node scripts/check-secrets.js --all",
+                    "check:consumer":  "node scripts/check-release-install.cjs",
+                    "check:migration":  "node scripts/check-release-migration.cjs",
+                    "check:release-surface":  "node scripts/check-release-surface.cjs",
                     "setup:hooks":  "node scripts/install-hooks.js",
                     "watch":  "node .agents/watch.js",
                     "test:skills":  "node scripts/verify-skill-examples.js",
-                    "test":  "node --test --test-concurrency=1 tests/install.test.js tests/lockfile.test.js tests/safe-writer.test.js tests/adapter-safety.test.js tests/update.test.js tests/uninstall.test.js tests/plugin-security.test.js tests/export.test.js tests/skills.test.js tests/validate.test.js tests/plugins.test.js tests/benchmark.test.js tests/benchmark-api.test.js tests/profile.test.js tests/resolver.test.js tests/cli-registry.test.js tests/profile-enforcement.test.js tests/doctor-hardening.test.js tests/manifest-compiler.test.js tests/canonical-resolver.test.js tests/workspace-graph.test.js tests/profiles-v2.test.js tests/safe-path.test.js tests/project-lock.test.js tests/journaled-transaction.test.js tests/pure-adapters.test.js tests/prompt-skill-system.test.js tests/runtime-state-machine.test.js tests/verification-reviewer-pipeline.test.js tests/durable-concurrency-locks.test.js tests/transactional-git.test.js tests/sandbox-execution.test.js tests/plugin-supply-chain.test.js tests/platform-hardening.test.js tests/customization-dx.test.js tests/claims-governance.test.js tests/benchmark-v2.test.js tests/init-engine.test.js tests/mutation-paths.test.js tests/tarball-smoke.test.js tests/catalog-export-integration.test.js tests/consumer-gate.test.js tests/adapter-compatibility.test.js tests/consumer-init.test.js tests/skill-examples.test.js tests/scan.test.js tests/hooks.test.js tests/recovery-cli.test.js tests/doctor-v2.test.js tests/resolver-parity.test.js tests/watch-coalescing.test.js",
+                    "test":  "node --test --test-concurrency=1 tests/install.test.js tests/lockfile.test.js tests/safe-writer.test.js tests/adapter-safety.test.js tests/update.test.js tests/uninstall.test.js tests/plugin-security.test.js tests/export.test.js tests/skills.test.js tests/validate.test.js tests/plugins.test.js tests/benchmark.test.js tests/benchmark-api.test.js tests/profile.test.js tests/resolver.test.js tests/cli-registry.test.js tests/profile-enforcement.test.js tests/doctor-hardening.test.js tests/manifest-compiler.test.js tests/canonical-resolver.test.js tests/workspace-graph.test.js tests/profiles-v2.test.js tests/safe-path.test.js tests/project-lock.test.js tests/journaled-transaction.test.js tests/pure-adapters.test.js tests/prompt-skill-system.test.js tests/runtime-state-machine.test.js tests/verification-reviewer-pipeline.test.js tests/durable-concurrency-locks.test.js tests/transactional-git.test.js tests/sandbox-execution.test.js tests/plugin-supply-chain.test.js tests/platform-hardening.test.js tests/customization-dx.test.js tests/claims-governance.test.js tests/benchmark-v2.test.js tests/init-engine.test.js tests/mutation-paths.test.js tests/tarball-smoke.test.js tests/catalog-export-integration.test.js tests/consumer-gate.test.js tests/adapter-compatibility.test.js tests/consumer-init.test.js tests/skill-examples.test.js tests/scan.test.js tests/hooks.test.js tests/recovery-cli.test.js tests/doctor-v2.test.js tests/resolver-parity.test.js tests/watch-coalescing.test.js tests/consumer-stabilization.test.js tests/focused-context.test.js tests/spend-guard.test.js tests/maintenance-benchmark.test.js tests/luna-agent-benchmark.test.js tests/release-surface.test.js",
                     "prepublishOnly":  "npm run validate \u0026\u0026 npm run build"
                 },
     "keywords":  [