contextos-agents 2.3.1 → 2.3.2

package/.agents/adapters/cursor/export.js

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { getSkillEntrypointPath, AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
+const { getSkillEntrypointPath, readSkillMetadata, AGENTS_MD_PATH, collectSkillDirectories, stripFrontmatter } = require('../shared.js');
 const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'cursor@2';
@@ -74,25 +74,9 @@ function getSkillGlobsAndFlags(skillName, skillDir = null) {
 function buildSkillSection(skillDir) {
   const skillName = path.basename(skillDir);
   const skillMdPath = getSkillEntrypointPath(skillDir);
-  const yamlPath = path.join(skillDir, 'skill.yaml');
-
-  let title = skillName;
-  let description = '';
-  if (fs.existsSync(yamlPath)) {
-    const yaml = fs.readFileSync(yamlPath, 'utf8');
-    title = extractYamlField(yaml, 'name') || skillName;
-    description = extractYamlField(yaml, 'description') || '';
-  }
 
   if (!fs.existsSync(skillMdPath)) return null;
-
-  const raw = fs.readFileSync(skillMdPath, 'utf8');
-  const body = stripFrontmatter(raw).trimEnd();
-
-  if (!description) {
-    const firstLine = body.split(/\r?\n/).map(l => l.trim()).find(l => l && !l.startsWith('#'));
-    description = firstLine || '';
-  }
+  const { name: title, description } = readSkillMetadata(skillDir);
 
   const descLine = description ? `> ${description.replace(/\r?\n+/g, ' ').trim()}\n` : '';
   return `\n## Skill: ${title}\n${descLine}*Rule file: \`.cursor/rules/${skillName}.mdc\` (load on demand)*\n`;
@@ -101,18 +85,10 @@ function buildSkillSection(skillDir) {
 function generateCursorMdc(skillDir, context) {
   const skillName = path.basename(skillDir);
   const skillMdPath = getSkillEntrypointPath(skillDir);
-  const yamlPath = path.join(skillDir, 'skill.yaml');
 
   if (!fs.existsSync(skillMdPath)) return null;
 
-  let title = skillName;
-  let description = `ContextOS rules for ${skillName}`;
-  if (fs.existsSync(yamlPath)) {
-    const yaml = fs.readFileSync(yamlPath, 'utf8');
-    title = extractYamlField(yaml, 'name') || skillName;
-    const desc = extractYamlField(yaml, 'description');
-    if (desc) description = desc;
-  }
+  const { name: title, description } = readSkillMetadata(skillDir);
 
   let raw = fs.readFileSync(skillMdPath, 'utf8');
   const body = stripFrontmatter(raw).trimEnd();

package/.agents/adapters/gemini/export.js

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { getSkillEntrypointPath, readSkillManifest, collectSkillDirectories, renderSkillResources } = require('../shared.js');
+const { getSkillEntrypointPath, readSkillMetadata, stripFrontmatter, collectSkillDirectories, renderSkillResources } = require('../shared.js');
 const { registerAdapter, applyArtifacts } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'gemini@2';
@@ -14,14 +14,13 @@ function describe() {
   return {
     name: 'gemini',
     version: '2.0.0',
-    description: 'Compiles modular skills for Gemini 3.8 and Google Antigravity IDE',
+    description: 'Compiles shared native skills and supporting resources for documented client discovery paths',
     targetPattern: '.agents/generated/gemini/skills/**/SKILL.md',
   };
 }
 
 function renderGeminiSkill(skillDir, context) {
   const skillName = path.basename(skillDir);
-  const manifest = readSkillManifest(skillDir);
   const existingSkillMdPath = getSkillEntrypointPath(skillDir);
 
   if (!fs.existsSync(existingSkillMdPath)) {
@@ -29,13 +28,12 @@ function renderGeminiSkill(skillDir, context) {
   }
 
   const name = skillName;
-  const description = manifest?.description || `ContextOS skill for ${name}`;
-  const mergedContent = fs.readFileSync(existingSkillMdPath, 'utf8').replace(/^---[\s\S]*?---\r?\n/, '');
+  const { description } = readSkillMetadata(skillDir);
+  const mergedContent = stripFrontmatter(fs.readFileSync(existingSkillMdPath, 'utf8'));
 
   const outputContent = `---
 name: ${name}
-description: >
-  ${description}
+description: ${JSON.stringify(description)}
 ---
 ${mergedContent.trim()}
 `.replace(/\r\n/g, '\n');

package/.agents/adapters/shared.js

@@ -53,7 +53,7 @@ function resetDirectory(directory) {
 }
 
 function stripFrontmatter(content) {
-  return content.replace(/^---[\s\S]*?---\r?\n/, '').trimStart();
+  return content.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/, '').trimStart();
 }
 
 function extractYamlField(yamlText, field) {
@@ -126,6 +126,18 @@ function getSkillEntrypointPath(skillDir) {
   return require('../filesystem/index.js').resolveManagedPath(skillDir, manifest?.entrypoint || 'SKILL.md').resolvedPath;
 }
 
+/** Routing metadata follows the declared manifest, then the real entrypoint. */
+function readSkillMetadata(skillDir, { fallbackDescription } = {}) {
+  const manifest = readSkillManifest(skillDir);
+  const entrypoint = getSkillEntrypointPath(skillDir);
+  const raw = fs.existsSync(entrypoint) ? fs.readFileSync(entrypoint, 'utf8') : '';
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const frontmatter = match ? require('../compiler/vendor/yaml.js').parse(match[1]) : {};
+  const name = manifest?.displayName || manifest?.name || frontmatter?.name || path.basename(skillDir);
+  const description = manifest?.description || frontmatter?.description || fallbackDescription || `ContextOS skill for ${name}`;
+  return { name, description: typeof description === 'string' ? description.trim() : description };
+}
+
 /** Copy declared resources beside exported entrypoints without inlining them. */
 function renderSkillResources(skillDir, destinations, metadata) {
   const manifest = readSkillManifest(skillDir);
@@ -158,5 +170,6 @@ module.exports = {
   stripFrontmatter,
   renderSkillResources,
   readSkillManifest,
+  readSkillMetadata,
   getSkillEntrypointPath,
 };

package/.agents/adapters/zed/export.js

@@ -5,7 +5,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { getSkillEntrypointPath, AGENTS_MD_PATH, collectSkillDirectories, extractYamlField, stripFrontmatter } = require('../shared.js');
+const { getSkillEntrypointPath, readSkillMetadata, AGENTS_MD_PATH, collectSkillDirectories, stripFrontmatter } = require('../shared.js');
 const { registerAdapter, applyArtifacts, createProvenanceHeader } = require('../pure-compiler.js');
 
 const GENERATOR_ID = 'zed@2';
@@ -22,25 +22,13 @@ function describe() {
 function buildSkillSection(skillDir) {
   const skillName = path.basename(skillDir);
   const skillMdPath = getSkillEntrypointPath(skillDir);
-  const yamlPath = path.join(skillDir, 'skill.yaml');
-
-  let title = skillName;
-  let description = '';
-  if (fs.existsSync(yamlPath)) {
-    const yaml = fs.readFileSync(yamlPath, 'utf8');
-    title = extractYamlField(yaml, 'name') || skillName;
-    description = extractYamlField(yaml, 'description') || '';
-  }
 
   if (!fs.existsSync(skillMdPath)) return null;
-
   const raw = fs.readFileSync(skillMdPath, 'utf8');
   const body = stripFrontmatter(raw);
-
-  if (!description) {
-    const firstLine = body.split(/\r?\n/).map(l => l.trim()).find(l => l && !l.startsWith('#'));
-    description = firstLine || '';
-  }
+  // Preserve the existing body preview for skills without routing metadata.
+  const fallbackDescription = body.split(/\r?\n/).map(line => line.trim()).find(line => line && !line.startsWith('#'));
+  const { name: title, description } = readSkillMetadata(skillDir, { fallbackDescription });
 
   const descLine = description ? `> ${description.replace(/\r?\n+/g, ' ').trim()}\n` : '';
   const promptRef = `*Prompt template: \`.zed/prompts/${skillName}.md\` (Use via /${skillName})*\n`;

package/.agents/compiled/registry.v2.json

@@ -1,19 +1,19 @@
 {
   "schemaVersion": 2,
   "compilerVersion": "2.0.0",
-  "sourceGraphHash": "sha256:efcac8692b9208232aa09a065009438cd7b151e7f4d19366d75b699645cddf94",
+  "sourceGraphHash": "sha256:1b5d0e2b86f8dc023ed48da798410c82c6d2855db15d6af500b575cb60234bd6",
   "skills": {
     "context-manager": {
       "id": "context-manager",
       "displayName": "context-manager",
       "version": "1.0.0",
-      "description": "Smart context selection engine. Analyzes the current task, consults the Project Graph, and returns only the documents and skills needed to prevent token overflow.\n",
+      "description": "Compatibility alias for context-os context selection and budgeting.",
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:dba3a018c55b687bf5256592664266affe322ed71b042a4ceed3f07bc30363d7",
-      "resourceTreeHash": "sha256:8743abc29abf19fa93481f09a836d48ec4279030991f3cf6bc2082738c48c54a",
-      "estimatedTokens": 858,
+      "entrypointHash": "sha256:68da81d3dc530bd37260f61923c6dd4a3bc862a96500129fefd61cfa2021323b",
+      "resourceTreeHash": "sha256:c3a338efabd770e57bcaec7a127bc281cb718626f6a84a904f850164984aa5fe",
+      "estimatedTokens": 304,
       "source": ".agents/core/skills/context-manager/skill.yaml",
       "signals": {
         "aliases": [
@@ -30,7 +30,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 858
+        "estimatedTokens": 304
       },
       "resources": [
         {
@@ -66,9 +66,9 @@
       "category": "general",
       "type": "compiler",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:ab14bcd603573c975a69cb95b5ef8a305de8eb888c81c20c994121313f017239",
-      "resourceTreeHash": "sha256:1f9422adff6b9e69772dfeff2e1c9c9f8615b5fae56f8b60d2d7bef4a5c1c7fb",
-      "estimatedTokens": 1365,
+      "entrypointHash": "sha256:3d333bd492b24f62f4a5314bbbddd4a08014a8867645bedebbe9329a8d76e2d5",
+      "resourceTreeHash": "sha256:75f2c5ef977ad763b1bd84f5b2934fb317c9cc853760fa76a38f713aa422fddd",
+      "estimatedTokens": 562,
       "source": ".agents/core/skills/context-os/skill.yaml",
       "signals": {
         "aliases": [
@@ -85,7 +85,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 1365
+        "estimatedTokens": 562
       },
       "resources": [
         {
@@ -137,9 +137,9 @@
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:e729b3bc21cecef2a39b64f0b301715974697600524629fa05609fd2d9175b48",
-      "resourceTreeHash": "sha256:6371d58615c6b5ba47c1523f6f99c106dcd9d99c5abc30338b4a3504271a23f1",
-      "estimatedTokens": 418,
+      "entrypointHash": "sha256:a36e56bf2b8ad3711e1209f9d7ee68de1a1e3d6fbf864eed423bdf4527474a5e",
+      "resourceTreeHash": "sha256:db770f6c0fe81ab7a4952ebf6391e36f4e0b53571ff09c9a3d36af770185ea77",
+      "estimatedTokens": 430,
       "source": ".agents/core/skills/engineering-workflow/skill.yaml",
       "signals": {
         "aliases": [
@@ -156,7 +156,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 418
+        "estimatedTokens": 430
       },
       "resources": [
         {
@@ -188,13 +188,13 @@
       "id": "gemini-precision",
       "displayName": "gemini-precision",
       "version": "1.0.0",
-      "description": "High-precision engineering and execution guardrails optimized for Google Gemini models. Enforces zero-assumption file inspection, complete non-lazy implementations, surgical blast-radius containment, and mandatory proof-of-work execution.",
+      "description": "Execution guidance for Gemini: inspect code, preserve scope, and report relevant verification evidence.",
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:bd091c13a5c15c2ac55a8c27b309ffdd8e0a5a8b8260198808b70e45e685b9fd",
-      "resourceTreeHash": "sha256:8ae82b8dd89128820c8b28c7e9e8aac878f363381dd2a11043b8aff9d03ae35e",
-      "estimatedTokens": 1890,
+      "entrypointHash": "sha256:d0e1c8331b25d663c153a88ed7e88d349f2e8662f919a6d390f5e94cfee81093",
+      "resourceTreeHash": "sha256:343b58798199f697e8c547963e41f3160793e69a43ffa9feb5109450368d55e0",
+      "estimatedTokens": 444,
       "source": ".agents/core/skills/gemini-precision/skill.yaml",
       "signals": {
         "aliases": [
@@ -211,7 +211,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 1890
+        "estimatedTokens": 444
       },
       "resources": [
         {
@@ -243,9 +243,9 @@
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:baeb5f187b8ea491f4854e6287c29d5c58b436c327e8df46c04651e6deb43513",
-      "resourceTreeHash": "sha256:d720b3727681e63f5212e97687b9ad32326685f22493214edc8750a3f504347a",
-      "estimatedTokens": 343,
+      "entrypointHash": "sha256:60eb7b902ae8faf4c4205cf99abad4401ee2ec528b9c8490f909aa7db95fb5f2",
+      "resourceTreeHash": "sha256:4afcb9bffe3b4d6912d3d6c35b1a197b6471c9789f277295a2de6c56727eae34",
+      "estimatedTokens": 310,
       "source": ".agents/core/skills/gstack-roles/skill.yaml",
       "signals": {
         "aliases": [
@@ -262,7 +262,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 343
+        "estimatedTokens": 310
       },
       "resources": [
         {
@@ -298,9 +298,9 @@
       "category": "general",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:837795e41d09af94040fb9ae318126c6ff3a24bf35b43bbf4cb2888a5067a950",
-      "resourceTreeHash": "sha256:3a4d757373ad00ae321c25d0774d35d0f8c9f25b1e95d58303ffb68d0128fd59",
-      "estimatedTokens": 413,
+      "entrypointHash": "sha256:d1d70efd4fec48ff5209c93bb18ce52039abc92c83f04d9aa691d0d147ed1b44",
+      "resourceTreeHash": "sha256:b760eceafd9d0e88df852029a262078b3089040edbf947d71a32fad6845be32b",
+      "estimatedTokens": 402,
       "source": ".agents/core/skills/ponytail-mindset/skill.yaml",
       "signals": {
         "aliases": [
@@ -317,7 +317,7 @@
       },
       "context": {
         "priority": 50,
-        "estimatedTokens": 413
+        "estimatedTokens": 402
       },
       "resources": [
         {
@@ -353,9 +353,9 @@
       "category": "backend",
       "type": "instruction-only",
       "entrypoint": "SKILL.md",
-      "entrypointHash": "sha256:5daec60e9bb1c49a2b66e43d73e897397507e3604ef4bf02588d35cfd59b1903",
-      "resourceTreeHash": "sha256:b4302851046e1faffc18bc600c79d92d1da7f31bed03781eee89e84ddedc4956",
-      "estimatedTokens": 2237,
+      "entrypointHash": "sha256:7d73d176ef08f6ae6210db12ecf0088e0177d12d4e365a626cfbb3d7236ccdad",
+      "resourceTreeHash": "sha256:a4e2b342b27a7c4532977f4788d8a406273ab1008c1a06bb4941da5a96752aa3",
+      "estimatedTokens": 1351,
       "source": ".agents/core/skills/security/skill.yaml",
       "signals": {
         "aliases": [
@@ -423,7 +423,7 @@
       },
       "context": {
         "priority": 90,
-        "estimatedTokens": 2237
+        "estimatedTokens": 1351
       },
       "resources": [
         {
@@ -457,7 +457,7 @@
           "level": "must",
           "enforcement": "runtime",
           "checker": "secret-scanner",
-          "summary": "Zero plaintext credentials, private keys, or API tokens committed to repository"
+          "summary": "Scan configured inputs for supported credential patterns; report input scope, exclusions, and scanner results"
         },
         {
           "id": "SEC-003",
@@ -506,7 +506,7 @@
       "level": "must",
       "enforcement": "runtime",
       "checker": "secret-scanner",
-      "summary": "Zero plaintext credentials, private keys, or API tokens committed to repository",
+      "summary": "Scan configured inputs for supported credential patterns; report input scope, exclusions, and scanner results",
       "sourceSkill": "security"
     },
     "SEC-003": {

package/.agents/compiled/registry.v2.sha256

@@ -1 +1 @@
-sha256:efcac8692b9208232aa09a065009438cd7b151e7f4d19366d75b699645cddf94  registry.v2.json
+sha256:1b5d0e2b86f8dc023ed48da798410c82c6d2855db15d6af500b575cb60234bd6  registry.v2.json

package/.agents/compiler/manifest-compiler.js

@@ -277,14 +277,14 @@ class ManifestCompiler {
     if (!fs.existsSync(filePath)) return null;
     const content = fs.readFileSync(filePath, 'utf8');
     if (!content.startsWith('---')) return null;
-    const endIdx = content.indexOf('---', 3);
-    if (endIdx === -1) return { malformed: true };
-    const rawYaml = content.slice(3, endIdx).trim();
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)/);
+    if (!match) return { malformed: true };
+    const rawYaml = match[1].trim();
     const parsed = parseYaml(rawYaml);
     return {
       raw: rawYaml,
       parsed,
-      contentWithoutFrontmatter: content.slice(endIdx + 3).trim(),
+      contentWithoutFrontmatter: match[2].trim(),
     };
   }
 
@@ -299,7 +299,7 @@ class ManifestCompiler {
 
     const entrypoint = parsed.entrypoint || 'SKILL.md';
     const version = parsed.version ? String(parsed.version) : '1.0.0';
-    const description = parsed.description || `ContextOS skill for ${displayName}`;
+    let description = parsed.description || `ContextOS skill for ${displayName}`;
     const type = parsed.type || 'instruction-only';
     const category = parsed.category || 'general';
 
@@ -319,6 +319,9 @@ class ManifestCompiler {
     const entrypointFile = path.join(skillDir, entrypoint);
     if (fs.existsSync(entrypointFile)) {
       const fm = this.readFrontmatter(entrypointFile);
+      if (!parsed.description && typeof fm?.parsed?.description === 'string' && fm.parsed.description.trim()) {
+        description = fm.parsed.description.trim();
+      }
       if (fm && fm.parsed && fm.parsed.name) {
         const fmSlug = String(fm.parsed.name).trim().toLowerCase().replace(/\s+/g, '-');
         discoveredAliases.push(fmSlug);

package/.agents/core/skills/context-manager/EXAMPLES.md

@@ -1,19 +1,7 @@
-# context-manager Examples — Anti-patterns vs ContextOS Standard
+# context-manager compatibility examples
 
-## Example 1: Context Selection
+Use the canonical [context-os](../context-os/SKILL.md). An explicit resolver
+request for context-manager redirects to context-os; the warning explains the mapping.
+A directly loaded alias should follow the same canonical instructions.
 
-### Anti-pattern: Context Window Dumping
-
-```text
-Agent reads all 180 files in src/ into context to debug a single button click handler.
-Result: Exhausts 150k tokens, reaches rate limits, and forgets user instructions.
-```
-
-### Best practice: ContextOS Standard (Targeted AST Traversal)
-
-```text
-1. Inspect package.json and AGENTS.md.
-2. Grep for target symbol: grep_search for 'SubmitButton'.
-3. Read ONLY components/SubmitButton.tsx and its direct import types/button.ts.
-Total tokens used: <1,500 tokens. Fast, accurate, zero hallucinations.
-```
+Inspect relevant files, callers, and resolver warnings. Package evidence does not guarantee a complete symbol graph or total prompt budget.

package/.agents/core/skills/context-manager/SKILL.md

@@ -1,126 +1,36 @@
 ---
 name: context-manager
-description: >
-  Smart context selection engine. Analyzes the current task, consults the 
-  Project Graph, and returns only the documents and skills needed. 
-  Prevents context window overflow by loading minimum relevant information.
+description: "Compatibility alias for context-os context selection and budgeting."
 ---
 
 # context-manager
 
 ## Overview
 
-Deterministic context window optimizer. Analyzes user task intent and queries project dependency graphs to inject minimal relevant files and skills, preventing LLM attention loss and context pollution.
+Deprecated compatibility identifier. Use [context-os](../context-os/SKILL.md) for the canonical instructions.
 
 ## When to Use
 
-Activate during multi-file investigations, large refactorings, or complex tasks where dumping entire directory trees would blow past context budgets.
+An existing configuration or user explicitly names context-manager.
 
 ## Rules & Patterns
 
-You are the **Context Manager**. Your job is to prevent context overload.
-
-## How It Works
-
-When given a task:
-
-### Step 1: Classify the task
-
-```yaml
-task:
-  type: [frontend | backend | fullstack | architecture | bugfix | refactor | deploy | review]
-  scope: [module | feature | file | project-wide]
-  module: {{module_name from Project Graph}}
-```
-
-### Step 2: Consult the Project Graph
-
-If `docs/PROJECT_GRAPH.md` or `.graphify/graph.json` exists (or activate `graphify` skill to extract AST dependencies):
-
-1. Find the module this task belongs to
-2. Get the module's dependencies
-3. Get the module's required skills
-4. Get the files this task will likely touch
-
-### Step 3: Apply Context Rules
-
-Load `references/context-rules.md` and apply the task type → document mapping.
-
-### Step 4: Return Context Package
-
-Output a context package:
-
-```yaml
-context:
-  documents:
-    required:
-      - docs/API.md          # sections: [appointments]
-      - docs/ARCHITECTURE.md # sections: [backend, api-layer]
-    optional:
-      - docs/decisions/0003-postgres.md
-    skipped:
-      - docs/UI.md           # reason: backend task
-      - docs/DATABASE.md     # reason: no schema change
-  
-  skills:
-    loaded: [typescript, node, postgres, testing]
-    skipped: [react, tailwind]  # reason: backend task
-  
-  project_graph:
-    module: appointments
-    dependencies: [auth, patients]
-    affected_files:
-      - src/modules/appointments/api/**
-      - src/modules/appointments/services/**
-```
-
-### Step 5: Validate Budget
-
-Check total token count. If over budget (see context-rules.md):
-
-1. Trim Level 1 docs to summaries
-2. Load only affected sections of Level 2 docs
-3. Keep Level 3 (skills) at full detail
-
-## Context Caching
-
-After first compilation for a module, cache the result:
-
-```
-.cache/
-  frontend.context.yaml
-  backend.context.yaml
-  appointments.context.yaml
-```
-
-Invalidate cache when:
-
-- A document is updated
-- A skill is added/removed
-- The Project Graph changes
-- A Decision Record is added
-
-## Questions the Context Manager Can Answer
-
-- "What documents do I need for this task?"
-- "Which skills should be loaded?"
-- "What modules are affected by this change?"
-- "Is this context package within budget?"
-- "Why was this document skipped?"
-
+Apply the canonical skill without loading a duplicate process. Existing authorization, proportional verification, and optional role declarations carry forward. The resolver redirects this identifier and reports an alias warning.
 
 ## Code Examples
 
-See `EXAMPLES.md` for detailed code examples.
+Explicit context-manager selection resolves to context-os; inspect the resolver result rather than assuming both bodies were loaded.
 
 ## Validation Checklist
 
-What to verify during the review phase before completing the task.
+- [ ] Canonical guidance is used.
+- [ ] Alias resolution adds no duplicate body.
+- [ ] Evidence scope and limitations are stated.
 
 ## Common Mistakes
 
-Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+Treating this compatibility name as an independent engine or a mandatory ceremony.
 
 ## Integration Notes
 
-How this skill interacts with other skills.
+Keep legacy links available. Read [references/context-rules.md](references/context-rules.md) only for compatibility details.

package/.agents/core/skills/context-manager/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
-# context-manager Troubleshooting & Common Mistakes
+# context-manager compatibility troubleshooting
 
-## 1. Token Budget Blowout
-
-- **Symptom**: Model performance drops significantly, losing earlier conversational context.
-- **Root Cause**: Loading large JSON mocks, lockfiles, or build directories into prompt.
-- **Fix**: Never read package-lock.json, dist/, or build artifacts unless explicitly debugging bundle outputs.
+- Duplicate process: load the canonical context-os instructions once.
+- Repeated approval or banners: preserve existing authorization and optional roles.
+- Conflicting legacy guidance: use the canonical skill and update the stale link.
+- Claimed automation: inspect actual CLI results and distinguish instructions
+  from runtime enforcement.