contextos-agents 2.2.0 → 2.3.1

package/.agents/generated/gemini/skills/security/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/.agents/plugins.js

@@ -1221,11 +1221,11 @@ async function search(query) {
  * both core (builtin) and plugins.
  * Adapters call this instead of reading CORE_SKILLS directly.
  */
-function collectAllSkillDirs(targetRoot) {
+function collectAllSkillDirs(targetRoot, options = {}) {
   const isTargetExplicit = Boolean(targetRoot);
   const root = targetRoot || process.cwd();
-  const agentsDir = path.join(root, '.agents');
-  const localCore = path.join(agentsDir, 'core', 'skills');
+  const agentsDir = options.agentsDir || path.join(root, '.agents');
+  const localCore = options.coreSkillsDir || path.join(agentsDir, 'core', 'skills');
   const localPlugins = path.join(agentsDir, 'plugins');
 
   const coreDir = fs.existsSync(localCore) ? localCore : (isTargetExplicit ? null : CORE_SKILLS);
@@ -1252,13 +1252,32 @@ function collectAllSkillDirs(targetRoot) {
           const subDir = path.join(nestedSkills, sub);
           if (fs.statSync(subDir).isDirectory()) dirs.push(subDir);
         }
-      } else if (fs.existsSync(path.join(d, 'SKILL.md')) || fs.existsSync(path.join(d, 'skill.yaml'))) {
+      } else if (fs.existsSync(path.join(d, 'SKILL.md')) || fs.existsSync(path.join(d, 'skill.yaml')) || fs.existsSync(path.join(d, 'skill.v2.yaml'))) {
         dirs.push(d);
       }
     }
   }
 
-  return dirs;
+  // Higher ownership tiers replace an upstream skill with the same ID. Preserve
+  // upstream duplicates so the compiler can still diagnose conflicting installs.
+  for (const tier of ['vendor', 'project']) {
+    const tierRoot = path.join(agentsDir, tier, 'skills');
+    if (!fs.existsSync(tierRoot)) continue;
+    for (const name of fs.readdirSync(tierRoot).sort()) {
+      const dir = path.join(tierRoot, name);
+      const { resolvedPath } = require('./filesystem/index.js').resolveManagedPath(root, path.relative(root, dir));
+      if (!fs.statSync(resolvedPath).isDirectory()) continue;
+      if (!fs.existsSync(path.join(dir, 'SKILL.md')) && !fs.existsSync(path.join(dir, 'skill.yaml')) && !fs.existsSync(path.join(dir, 'skill.v2.yaml'))) continue;
+      for (let i = dirs.length - 1; i >= 0; i--) {
+        if (path.basename(dirs[i]) === name) dirs.splice(i, 1);
+      }
+      dirs.push(dir);
+    }
+  }
+  if (isTargetExplicit) {
+    for (const dir of dirs) require('./filesystem/index.js').resolveManagedPath(root, path.relative(root, dir));
+  }
+  return dirs.sort();
 }
 
 module.exports = {

package/.agents/resolver/canonical-resolver.js

@@ -650,6 +650,12 @@ class CanonicalResolver {
         }
       }
 
+      if (resolvedId === 'security' && ['keyword', 'file_glob', 'explicit', 'safety_required'].includes(kind)) {
+        if (profileExcluded.delete(resolvedId)) {
+          warnings.push({ code: 'CTX_REQUIRED_SECURITY_PROFILE_CONFLICT', message: 'Task safety guidance overrides the profile exclusion of security.' });
+        }
+        kind = 'safety_required';
+      }
       if (profileExcluded.has(resolvedId)) return;
       if (!evidenceBySkill.has(resolvedId)) evidenceBySkill.set(resolvedId, []);
       evidenceBySkill.get(resolvedId).push({ kind, weight, reason });
@@ -836,6 +842,10 @@ class CanonicalResolver {
       }
     }
 
+    if (risk.value === 'high' || risk.value === 'destructive') {
+      addEvidence('security', 'safety_required', 100, `Required safety guidance for ${risk.value} risk task`);
+    }
+
     // 3. Compute Candidate Scores & Intent Precedence
     const candidates = [];
     for (const [id, evList] of evidenceBySkill.entries()) {
@@ -850,7 +860,7 @@ class CanonicalResolver {
         if ((e.kind === 'keyword' || e.kind === 'alias') && e.weight >= 20) {
           hasDirectTaskIntent = true;
         }
-        if (e.kind === 'explicit' || e.kind === 'profile_required') {
+        if (e.kind === 'explicit' || e.kind === 'profile_required' || e.kind === 'safety_required') {
           isMandatory = true;
           hasDirectTaskIntent = true;
         }
@@ -929,7 +939,7 @@ class CanonicalResolver {
     const closureMap = new Map();
     for (const item of initialSelection) {
       const rawEst = skillsDict[item.id]?.estimatedTokens || 1000;
-      const estTokens = Math.min(rawEst, BUDGET_TIERS.SKILL_BODY);
+      const estTokens = rawEst;
       closureMap.set(item.id, {
         id: item.id,
         displayName: skillsDict[item.id]?.displayName || item.id,
@@ -953,7 +963,7 @@ class CanonicalResolver {
           }
         } else {
           const rawEst = skillsDict[reqId]?.estimatedTokens || 1000;
-          const estTokens = Math.min(rawEst, BUDGET_TIERS.SKILL_BODY);
+          const estTokens = rawEst;
           closureMap.set(reqId, {
             id: reqId,
             displayName: skillsDict[reqId]?.displayName || reqId,
@@ -1000,7 +1010,12 @@ class CanonicalResolver {
     }
 
     // 7. Token Budget Planner & Capability Clustering
-    const BASE_SKILLS = ['ponytail-mindset', 'engineering-workflow'];
+    const plannedPhase = resolvePhaseAndRole(explicitPhase, task, []).phase.value;
+    const BASE_SKILLS = ['engineering-workflow'];
+    if (risk.value !== 'routine' && plannedPhase === 'Build') BASE_SKILLS.push('ponytail-mindset');
+    for (let i = BASE_SKILLS.length - 1; i >= 0; i--) {
+      if (!skillsDict[BASE_SKILLS[i]]) BASE_SKILLS.splice(i, 1);
+    }
     let baseTokens = 0;
 
     for (const baseId of BASE_SKILLS) {
@@ -1009,7 +1024,8 @@ class CanonicalResolver {
       }
     }
 
-    let allocatedDynamicTokens = 0;
+    // Foundation bodies occupy the same budget as task-specific skills.
+    let allocatedDynamicTokens = baseTokens;
     const admitted = new Map(); // id -> candidate entry
 
     // Separate mandatory vs optional candidates
@@ -1017,7 +1033,7 @@ class CanonicalResolver {
     const optionalCandidates = [];
 
     for (const cand of closureMap.values()) {
-      const isMandatory = cand.reasons.some(r => r.kind === 'explicit' || r.kind === 'profile_required');
+      const isMandatory = cand.reasons.some(r => r.kind === 'explicit' || r.kind === 'profile_required' || r.kind === 'safety_required');
       if (isMandatory) {
         mandatoryCandidates.push(cand);
       } else {
@@ -1131,6 +1147,25 @@ class CanonicalResolver {
       }
     }
 
+    const totalSelectedTokens = finalSelected.reduce((sum, skill) => sum + skill.estimatedTokens, 0);
+    for (const skill of finalSelected) {
+      if (!skillsDict[skill.id]) {
+        warnings.push({ code: 'CTX_SELECTED_SKILL_UNAVAILABLE', message: `Selected skill "${skill.id}" has no installed manifest. Install it before assembling runtime context.` });
+      }
+    }
+    if (finalSelected.length > maxSkillsLimit) {
+      warnings.push({ code: 'CTX_RESOLVER_SKILL_LIMIT_EXCEEDED', message: `Required skills and dependencies occupy ${finalSelected.length} slots; soft maxSkills limit is ${maxSkillsLimit}.` });
+    }
+    if (finalSelected.length > maxSkillsLimit) {
+      warnings.push({ code: 'CTX_RESOLVER_SKILL_LIMIT_EXCEEDED', message: `Required skills and dependencies occupy ${finalSelected.length} slots; soft maxSkills limit is ${maxSkillsLimit}.` });
+    }
+    if (totalSelectedTokens > budgetTokens && !warnings.some(w => w.code === 'CTX_RESOLVER_BUDGET_EXCEEDED')) {
+      warnings.push({
+        code: 'CTX_RESOLVER_BUDGET_EXCEEDED',
+        message: `Soft context budget (${budgetTokens} tokens) exceeded by required/foundation skill bodies (total: ${totalSelectedTokens} tokens). Client instructions and chat history are additional.`,
+      });
+    }
+
     // 9. Domain, Phase & Role
     let domain = request.domain || '';
     if (!domain) {
@@ -1208,7 +1243,7 @@ class CanonicalResolver {
       excluded,
       conflicts,
       warnings,
-      totalEstimatedTokens: baseTokens + allocatedDynamicTokens,
+      totalEstimatedTokens: totalSelectedTokens,
       // Legacy compatibility properties
       skills: allSelectedIds,
     };
@@ -1229,6 +1264,7 @@ class CanonicalResolver {
     const lines = [
       `[DOMAIN: ${res.domain}] [PHASE: ${phaseStr}] [ROLE: ${res.role}] [MODE: ${modeStr}] [LENSES: ${lensesStr}] [RISK: ${riskStr}]`,
       `Skills loaded: ${skillsList}`,
+      'Selection declaration only; skill bodies are read by the consuming client or prompt assembler.',
     ];
     if (res.workflow && res.workflow.steps && res.workflow.steps.length > 0) {
       lines.push(`Workflow (${res.workflow.name}): ${res.workflow.steps[0]}`);

package/.agents/resolver/resolve-args.js

@@ -0,0 +1,31 @@
+'use strict';
+
+function parseResolveArgs(args) {
+  const result = { task: '', files: [], explicitPhase: undefined, contextBudgetTokens: undefined, json: false, explain: false };
+  const task = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--json') result.json = true;
+    else if (arg === '--explain') result.explain = true;
+    else if (['--files', '--phase', '--budget'].includes(arg)) {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (arg === '--files') result.files = value.split(',').map(file => file.trim()).filter(Boolean);
+      else if (arg === '--phase') result.explicitPhase = value;
+      else {
+        if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))) {
+          throw new Error('--budget must be a positive integer');
+        }
+        result.contextBudgetTokens = Number(value);
+      }
+    } else if (arg === '--') {
+      task.push(...args.slice(i + 1));
+      break;
+    } else if (arg.startsWith('-')) throw new Error(`Unknown resolve option: ${arg}`);
+    else task.push(arg);
+  }
+  result.task = task.join(' ');
+  return result;
+}
+
+module.exports = { parseResolveArgs };

package/.agents/stats.js

@@ -6,7 +6,7 @@
  *   1. Full context payload (all skills + AGENTS.md)
  *   2. Profiled context payload (after applying active profile exclusions)
  *   3. Dynamically resolved context (lean on-demand skill set for typical tasks)
- *   4. Concrete token savings percentage and cost reductions
+ *   4. Character-based payload estimates, not provider billing or quality results
  */
 
 'use strict';
@@ -22,7 +22,6 @@ function estimateTokens(text) {
 
 function calculateContextStats(projectDir = process.cwd()) {
   const agentsDir = path.join(projectDir, '.agents');
-  const skillsDir = path.join(agentsDir, 'core', 'skills');
   const agentsMdPath = path.join(agentsDir, 'AGENTS.md');
 
   let agentsMdChars = 0;
@@ -31,15 +30,13 @@ function calculateContextStats(projectDir = process.cwd()) {
   }
 
   const skillCharMap = new Map();
-  if (fs.existsSync(skillsDir)) {
-    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+  const { collectSkillDirectories } = require('./adapters/shared.js');
+  const allDirs = collectSkillDirectories({ exclude_skills: [] }, projectDir);
+  for (const directory of allDirs) {
+      const skillMd = path.join(directory, 'SKILL.md');
       if (fs.existsSync(skillMd)) {
-        skillCharMap.set(entry.name, fs.readFileSync(skillMd, 'utf8').length);
+        skillCharMap.set(path.basename(directory), fs.readFileSync(skillMd, 'utf8').length);
       }
-    }
   }
 
   const totalSkillCount = skillCharMap.size;
@@ -50,9 +47,9 @@ function calculateContextStats(projectDir = process.cwd()) {
 
   // Active profile
   const activeProfile = profiles.getActiveProfile(projectDir);
-  const profileName = activeProfile ? (activeProfile.name || activeProfile.profile) : 'startup (recommended)';
+  const profileName = activeProfile ? (activeProfile.name || activeProfile.profile) : 'none';
   const excludedSkills = new Set(
-    activeProfile ? activeProfile.exclude_skills || [] : (profiles.getProfile('startup')?.exclude_skills || [])
+    activeProfile ? activeProfile.exclude_skills || [] : []
   );
 
   let profileChars = agentsMdChars;

package/.agents/workspace/workspace-graph.js

@@ -23,6 +23,8 @@ const DEFAULT_IGNORED_DIRS = new Set([
   '.git',
   'node_modules',
   '.contextos-worktrees',
+  '.swarm-worktrees',
+  '.external-skills',
   '.agents',
   'dist',
   'build',
@@ -121,6 +123,7 @@ class WorkspaceGraphBuilder {
     this.maxDepth = options.maxDepth || 8;
     this.maxPackages = options.maxPackages || 500;
     this.ignoredDirs = new Set([...DEFAULT_IGNORED_DIRS, ...(options.ignoredDirs || [])]);
+    this.includeNestedRepositories = options.includeNestedRepositories === true;
   }
 
   /**
@@ -223,7 +226,11 @@ class WorkspaceGraphBuilder {
         return;
       }
 
-      for (const entry of entries) {
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (packages.length >= this.maxPackages) {
+          hitLimit = true;
+          break;
+        }
         if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
         if (this.ignoredDirs.has(entry.name)) continue;
 
@@ -236,10 +243,8 @@ class WorkspaceGraphBuilder {
         }
 
         // Symlink escape guard: must remain within root realpath
-        if (
-          !realEntryPath.startsWith(visitedDirs.values().next().value) &&
-          !realEntryPath.startsWith(realRoot)
-        ) {
+        const realRelative = path.relative(realRoot, realEntryPath);
+        if (realRelative === '..' || realRelative.startsWith(`..${path.sep}`) || path.isAbsolute(realRelative)) {
           continue;
         }
 
@@ -253,7 +258,12 @@ class WorkspaceGraphBuilder {
           workspaceGlobs.length === 0 ||
           workspaceGlobs.some((g) => g.test(relPath));
 
-        const pkg = this._inspectDirectoryForPackage(fullPath, relPath, realRoot);
+        if (fs.existsSync(path.join(fullPath, '.git')) &&
+            !this.includeNestedRepositories && !(workspaceGlobs.length > 0 && isDeclared)) {
+          continue;
+        }
+
+        const pkg = isDeclared ? this._inspectDirectoryForPackage(fullPath, relPath, realRoot) : null;
         if (pkg) {
           packages.push(pkg);
           packageIdSet.add(pkg.id);

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,7 +40,13 @@ You do not need to clone anything manually. Just open your terminal in the root
 npx contextos-agents init
 ```
 
-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.
+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:
 
@@ -53,6 +59,20 @@ npx contextos-agents init --all               # Install all 36 catalog skills at
 
 ### Options
 
+Try the [small local demo](examples/quickstart/README.md) to install the package 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.
+
+Core 2.3.1 / MCP 0.4.1 are being prepared as a maintenance release; they are not yet published.
+See the [candidate checklist](docs/PATCH_RELEASE_2.3.1.md) and
+[live client check](docs/LIVE_CLIENT_CHECK_RU.md).
+Core 2.3.0 and MCP 0.4.0 remain the published pair. See the [release 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 released source,
+cross-platform CI and archive identities. Automatic client routing and the external
+pilot remain unverified. 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
@@ -70,13 +90,13 @@ npx contextos-agents --skip-compile     # Skip auto-compilation step
 
 Modern development teams face fragmented AI tooling: engineers use Cursor, Claude Code, GitHub Copilot, Gemini, Zed, and Aider. Each tool requires its own proprietary rules format, leading to configuration drift, contradictory standards, and unvetted AI slop (`// TODO`, leaked secrets).
 
-Artificially truncating skills to save tokens degrades model reasoning and induces hallucinations. Instead, ContextOS ensures that agents receive complete, high-fidelity engineering context from a single version-controlled source.
+ContextOS preserves selected skill bodies and reports budget overflow instead of silently truncating required instructions. Whether a client loads and follows those rules requires separate verification. The current [calibration](docs/BENCHMARK_RESULTS.md) found no quality advantage over vanilla on its test corpus.
 
 **ContextOS is not another coding agent.** It is the deterministic context compiler and policy engine for the agents your team already uses.
 
 ### The Three Pillars
 
-1. **Portable (Multi-Agent):** Define your engineering skills once in standard Markdown. ContextOS compiles native configurations for all supported agents (Gemini, Claude Code, Cursor, Copilot, Aider, and Zed).
+1. **Portable (Multi-Agent):** Define your engineering skills once in standard Markdown. ContextOS generates agent-specific exports (Gemini, Claude Code, Cursor, Copilot, Aider, and Zed); native loading and manual templates are distinguished in the compatibility matrix.
 2. **High-Fidelity & Focused:** The resolver maps domain skills to relevant tasks without lossy truncation, delivering rich, complete context to the model.
 3. **Verifiable in CI:** Lockfile v2 provenance, dual-hash verification, and CI quality gates detect configuration drift and enforce quality guardrails before merge.
 
@@ -93,15 +113,16 @@ contextos resolve "review authentication changes" \
   --explain
 ```
 
-Selected:
-  security              explicit task match
-  engineering-workflow  required dependency
+Example excerpt from the repository configuration (selection and scores depend on installed skills, files and profile):
 
-Excluded:
-  context-manager       domain relevance filter
+```text
+Selected Skills:
+  ✓ engineering-workflow   score: 100  tokens: ~418  (foundation: Core skill)
+  ✓ security               score: 185  tokens: ~2237  (safety_required: Touched file "src/auth/session.ts" matches glob "**/*auth*" (+25); safety_required: Touched file "src/auth/session.ts" matches pattern (+60); safety_required: Required safety guidance for high risk task)
+  ✓ typescript             score:  60  tokens: ~1000  (file_glob: Touched file "src/auth/session.ts" matches pattern (+60))
+```
 
-Risk: high
-Context status: complete and verified
+Selection does not imply installation or activation. If TypeScript is not installed, the CLI also reports `CTX_SELECTED_SKILL_UNAVAILABLE`; install it with `contextos skill add typescript` before runtime assembly.
 
 ## Dynamic Skill Resolution & Unified CLI (`contextos` / `ctx.js`)
 
@@ -114,8 +135,9 @@ ContextOS provides a unified CLI (`contextos` or `npx contextos-agents`) and loc
 contextos resolve "Build an accessible modal component with React and Tailwind"
 
 # Output:
-# [DOMAIN: Frontend] [PHASE: Build] [ROLE: Senior Developer]
-# Skills loaded: ponytail-mindset, engineering-workflow, gemini-precision
+# [DOMAIN: Frontend] [PHASE: Build] [ROLE: Senior Developer] [MODE: CHANGE] [LENSES: accessibility] [RISK: standard]
+# Skills loaded: ponytail-mindset, engineering-workflow, react, web-accessibility, ui-ux-pro
+# Selection declaration only; skill bodies are read by the consuming client or prompt assembler.
 
 # Resolve with full evidence scoring explanation:
 contextos resolve "security review" --files apps/web/app/login/page.tsx --explain
@@ -188,12 +210,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:
@@ -207,13 +231,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.2.0
+      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@v2.3.1
         with:
-          version: '2.2.0'       # Pinned version of contextos-agents runner
+          version: '2.3.1'       # Pinned version of contextos-agents runner
           adapters: 'all'        # Adapters to verify (or specific: 'cursor', 'claude')
           working-directory: '.' # Project root directory
 ```
 
+The example targets the forthcoming v2.3.1 release; use it after that tag and package are published.
+Until then, keep both pins at v2.3.0 / 2.3.0. The existing `v2.3.0` action tag defaults to CLI 2.2.0,
+so retain the explicit `version`. Updating the action source does not change an existing tag.
+
 The action executes the verified ContextOS quality gate in-process from the pinned package version, verifying generated AI adapter configs against source skills without executing untrusted scripts from pull requests, and without requiring a Node.js project or running `npm test`.
 
 ## Optional MCP integration (Beta)
@@ -223,10 +251,12 @@ The MCP server is a separate beta package. It is not part of the stable `context
 Install it separately if you want to try the beta integration:
 
 ```bash
-npm install --save-dev @contextos/mcp
+npm install --save-dev contextos-mcp
 npx contextos-mcp --dir .
 ```
 
+The former `@contextos/mcp` 0.3.x package is historical; use `contextos-mcp` for current releases.
+
 The MCP server is read-only by default. Runtime execution remains experimental and is outside the stable core scope.
 
 ## Security - Third-Party Skills

package/bin/index.js

@@ -100,7 +100,7 @@ Options:
   --project <path>    Specify target project root directory (default: current directory)
   --target <adapters> Target adapter(s) to verify or export (default: all)
   --github-annotations Emit GitHub Actions workflow commands and step summary
-  --with-mcp, --mcp   [DEPRECATED] Use the separate @contextos/mcp package instead
+  --with-mcp, --mcp   [DEPRECATED] Use the separate contextos-mcp package instead
   --skip-compile      Skip running ctx.js export after installation
   --add-skill <ref>   Install a community plugin skill after setup
 

package/bin/lib/ui.js

@@ -116,8 +116,8 @@ function renderSuccessCard(options = {}) {
   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('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));