contextos-agents 1.5.0 → 1.6.1

package/.agents/mcp/server.mjs

@@ -2240,8 +2240,8 @@ var require_resolve = __commonJS({
       }
       return count;
     }
-    function getFullPath(resolver, id = "", normalize2) {
-      if (normalize2 !== false)
+    function getFullPath(resolver, id = "", normalize3) {
+      if (normalize3 !== false)
         id = normalizeId(id);
       const p5 = resolver.parse(id);
       return _getFullPath(resolver, p5);
@@ -3581,7 +3581,7 @@ var require_fast_uri = __commonJS({
     "use strict";
     var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizeComponentEncoding, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
-    function normalize2(uri, options) {
+    function normalize3(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
         serialize(parse3(uri, options), options);
@@ -3817,7 +3817,7 @@ var require_fast_uri = __commonJS({
     }
     var fastUri = {
       SCHEMES,
-      normalize: normalize2,
+      normalize: normalize3,
       resolve: resolve10,
       resolveComponent,
       equal,
@@ -6833,9 +6833,10 @@ var init_provider = __esm({
 // src/security/secret-filter.ts
 import * as path3 from "node:path";
 function isBlockedPath(filePath) {
-  const basename5 = path3.basename(filePath).toLowerCase();
-  const ext = path3.extname(filePath).toLowerCase();
-  const parts = filePath.split(path3.sep).map((p5) => p5.toLowerCase());
+  const normalized = path3.normalize(filePath);
+  const basename5 = path3.basename(normalized).toLowerCase();
+  const ext = path3.extname(normalized).toLowerCase();
+  const parts = normalized.split(/[/\\]/).map((p5) => p5.toLowerCase());
   if (BLOCKED_FILENAMES.some((f7) => basename5 === f7.toLowerCase())) {
     return true;
   }
@@ -6851,7 +6852,8 @@ function isBlockedPath(filePath) {
   return false;
 }
 function containsSecrets(content) {
-  const sample = content.slice(0, 5e3);
+  if (!content) return false;
+  const sample = content.length > 1e6 ? content.slice(0, 1e6) : content;
   return SECRET_CONTENT_PATTERNS.some((pattern) => pattern.test(sample));
 }
 function redactSecrets(text) {
@@ -6875,7 +6877,10 @@ var init_secret_filter = __esm({
       "credentials",
       "credentials.json",
       "service-account.json",
-      "serviceAccountKey.json"
+      "serviceAccountKey.json",
+      ".netrc",
+      ".git-credentials",
+      ".npmrc"
     ];
     BLOCKED_EXTENSIONS = [".pem", ".key", ".p12", ".pfx", ".jks", ".keystore"];
     BLOCKED_DIRS = [".ssh", ".gnupg", ".aws", ".azure", ".gcp", ".kube"];
@@ -6887,12 +6892,18 @@ var init_secret_filter = __esm({
       // GitHub personal access token
       /gho_[A-Za-z0-9]{36}/,
       // GitHub OAuth token
+      /github_pat_[A-Za-z0-9_]{82}/,
+      // GitHub fine-grained PAT
       /sk-[A-Za-z0-9]{32,}/,
       // OpenAI API key
       /sk-ant-[A-Za-z0-9-]{90,}/,
       // Anthropic API key
-      /AIza[A-Za-z0-9_-]{35}/
+      /AIza[A-Za-z0-9_-]{35}/,
       // Google API key
+      /npm_[A-Za-z0-9]{32,36}/,
+      // npm access token
+      /xox[baprs]-[A-Za-z0-9_-]{10,48}/
+      // Slack token
     ];
   }
 });
@@ -41559,121 +41570,6 @@ var require_browser = __commonJS({
   }
 });
 
-// ../node_modules/has-flag/index.js
-var require_has_flag = __commonJS({
-  "../node_modules/has-flag/index.js"(exports, module) {
-    "use strict";
-    module.exports = (flag, argv = process.argv) => {
-      const prefix = flag.startsWith("-") ? "" : flag.length === 1 ? "-" : "--";
-      const position = argv.indexOf(prefix + flag);
-      const terminatorPosition = argv.indexOf("--");
-      return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
-    };
-  }
-});
-
-// ../node_modules/supports-color/index.js
-var require_supports_color = __commonJS({
-  "../node_modules/supports-color/index.js"(exports, module) {
-    "use strict";
-    var os7 = __require("os");
-    var tty = __require("tty");
-    var hasFlag = require_has_flag();
-    var { env } = process;
-    var forceColor;
-    if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false") || hasFlag("color=never")) {
-      forceColor = 0;
-    } else if (hasFlag("color") || hasFlag("colors") || hasFlag("color=true") || hasFlag("color=always")) {
-      forceColor = 1;
-    }
-    if ("FORCE_COLOR" in env) {
-      if (env.FORCE_COLOR === "true") {
-        forceColor = 1;
-      } else if (env.FORCE_COLOR === "false") {
-        forceColor = 0;
-      } else {
-        forceColor = env.FORCE_COLOR.length === 0 ? 1 : Math.min(parseInt(env.FORCE_COLOR, 10), 3);
-      }
-    }
-    function translateLevel(level) {
-      if (level === 0) {
-        return false;
-      }
-      return {
-        level,
-        hasBasic: true,
-        has256: level >= 2,
-        has16m: level >= 3
-      };
-    }
-    function supportsColor(haveStream, streamIsTTY) {
-      if (forceColor === 0) {
-        return 0;
-      }
-      if (hasFlag("color=16m") || hasFlag("color=full") || hasFlag("color=truecolor")) {
-        return 3;
-      }
-      if (hasFlag("color=256")) {
-        return 2;
-      }
-      if (haveStream && !streamIsTTY && forceColor === void 0) {
-        return 0;
-      }
-      const min = forceColor || 0;
-      if (env.TERM === "dumb") {
-        return min;
-      }
-      if (process.platform === "win32") {
-        const osRelease = os7.release().split(".");
-        if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
-          return Number(osRelease[2]) >= 14931 ? 3 : 2;
-        }
-        return 1;
-      }
-      if ("CI" in env) {
-        if (["TRAVIS", "CIRCLECI", "APPVEYOR", "GITLAB_CI", "GITHUB_ACTIONS", "BUILDKITE"].some((sign) => sign in env) || env.CI_NAME === "codeship") {
-          return 1;
-        }
-        return min;
-      }
-      if ("TEAMCITY_VERSION" in env) {
-        return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION) ? 1 : 0;
-      }
-      if (env.COLORTERM === "truecolor") {
-        return 3;
-      }
-      if ("TERM_PROGRAM" in env) {
-        const version2 = parseInt((env.TERM_PROGRAM_VERSION || "").split(".")[0], 10);
-        switch (env.TERM_PROGRAM) {
-          case "iTerm.app":
-            return version2 >= 3 ? 3 : 2;
-          case "Apple_Terminal":
-            return 2;
-        }
-      }
-      if (/-256(color)?$/i.test(env.TERM)) {
-        return 2;
-      }
-      if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(env.TERM)) {
-        return 1;
-      }
-      if ("COLORTERM" in env) {
-        return 1;
-      }
-      return min;
-    }
-    function getSupportLevel(stream2) {
-      const level = supportsColor(stream2, stream2 && stream2.isTTY);
-      return translateLevel(level);
-    }
-    module.exports = {
-      supportsColor: getSupportLevel,
-      stdout: translateLevel(supportsColor(true, tty.isatty(1))),
-      stderr: translateLevel(supportsColor(true, tty.isatty(2)))
-    };
-  }
-});
-
 // node_modules/debug/src/node.js
 var require_node = __commonJS({
   "node_modules/debug/src/node.js"(exports, module) {
@@ -41692,7 +41588,7 @@ var require_node = __commonJS({
     );
     exports.colors = [6, 2, 3, 4, 5, 1];
     try {
-      const supportsColor = require_supports_color();
+      const supportsColor = __require("supports-color");
       if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
         exports.colors = [
           20,
@@ -118880,7 +118776,7 @@ var require_util5 = __commonJS({
       return url2;
     }
     exports.urlGenerate = urlGenerate;
-    function normalize2(aPath) {
+    function normalize3(aPath) {
       var path16 = aPath;
       var url2 = urlParse(aPath);
       if (url2) {
@@ -118917,7 +118813,7 @@ var require_util5 = __commonJS({
       }
       return path16;
     }
-    exports.normalize = normalize2;
+    exports.normalize = normalize3;
     function join10(aRoot, aPath) {
       if (aRoot === "") {
         aRoot = ".";
@@ -118943,7 +118839,7 @@ var require_util5 = __commonJS({
         aRootUrl.host = aPath;
         return urlGenerate(aRootUrl);
       }
-      var joined = aPath.charAt(0) === "/" ? aPath : normalize2(aRoot.replace(/\/+$/, "") + "/" + aPath);
+      var joined = aPath.charAt(0) === "/" ? aPath : normalize3(aRoot.replace(/\/+$/, "") + "/" + aPath);
       if (aRootUrl) {
         aRootUrl.path = joined;
         return urlGenerate(aRootUrl);
@@ -119125,7 +119021,7 @@ var require_util5 = __commonJS({
         }
         sourceURL = join10(urlGenerate(parsed), sourceURL);
       }
-      return normalize2(sourceURL);
+      return normalize3(sourceURL);
     }
     exports.computeSourceURL = computeSourceURL;
   }
@@ -162826,7 +162722,12 @@ function writeCodeBlocks(workDir, blocks) {
   for (const block of blocks) {
     const normalized = path13.normalize(block.filePath);
     if (normalized.startsWith("..") || path13.isAbsolute(normalized)) {
-      process.stderr.write(`[contextos-agent] Skipping unsafe path: ${block.filePath}
+      process.stderr.write(`[contextos-agent] Skipping unsafe path (traversal): ${block.filePath}
+`);
+      continue;
+    }
+    if (isBlockedPath(normalized) || !isPathAllowed(normalized, workDir)) {
+      process.stderr.write(`[contextos-agent] Skipping forbidden/policy-blocked path: ${block.filePath}
 `);
       continue;
     }
@@ -188780,20 +188681,8 @@ function buildContextPrompt(projectRoot, task, options = {}) {
 // src/mcp/tools/contextos.ts
 init_secret_filter();
 init_command_exists();
-var ALLOWED_VERIFY_TOOLS = /* @__PURE__ */ new Set([
-  "npm",
-  "npx",
-  "pnpm",
-  "yarn",
-  "pytest",
-  "python",
-  "python3",
-  "cargo",
-  "go",
-  "vitest",
-  "jest",
-  "node"
-]);
+var ALLOWED_VERIFY_TOOLS = /* @__PURE__ */ new Set(["npm", "npx", "pnpm", "yarn", "pytest", "cargo", "go", "vitest", "jest"]);
+var FORBIDDEN_VERIFY_ARGS = /* @__PURE__ */ new Set(["-e", "-c", "--eval", "--print", "-p", "--input-type"]);
 var STRICT_ENV_ALLOWLIST = /* @__PURE__ */ new Set([
   "PATH",
   "HOME",
@@ -188846,6 +188735,15 @@ async function runWorktreeVerification(worktreePath, command) {
       output: `Security error: Command "${rawTool}" is not in the allowed verification tools whitelist (${Array.from(ALLOWED_VERIFY_TOOLS).join(", ")})`
     };
   }
+  const args = parts.slice(1);
+  for (const arg of args) {
+    if (FORBIDDEN_VERIFY_ARGS.has(arg.toLowerCase())) {
+      return {
+        verified: false,
+        output: `Security error: Argument "${arg}" is not permitted in verify_command`
+      };
+    }
+  }
   const exePath = await resolveExecutablePath(rawTool);
   const targetExecutable = exePath || rawTool;
   return new Promise((resolveResult) => {

package/.agents/plugins.js

@@ -43,14 +43,20 @@ const PROMPT_INJECTION_PATTERNS = [
   /you\s+are\s+now/i,
   /system\s*:\s*/i,
   /\[SYSTEM\]/i,
+  /base64\s*,\s*[A-Za-z0-9+/=]{40,}/i,
+  /https?:\/\/[^\s)]+\/(?:exfil|steal|leak|webhook|collect)/i,
+  /\b(?:eval|exec|Function)\s*\(/i,
 ];
 
-function scanForPromptInjection(content) {
+function scanForPromptInjection(content, options = {}) {
   if (typeof content !== 'string') return false;
   const found = PROMPT_INJECTION_PATTERNS.filter(p => p.test(content));
   if (found.length > 0) {
-    console.warn(c.yellow('  ⚠️ Potential prompt injection detected in downloaded skill'));
-    console.warn(c.yellow(`     Patterns: ${found.map(p => p.source).join(', ')}`));
+    console.warn(c.red('  🚨 Potential prompt injection or unsafe pattern detected in skill:'));
+    console.warn(c.yellow(`     Pattern matches: ${found.map(p => p.source).join(', ')}`));
+    if (options.throwOnMatch) {
+      throw new Error(`Security validation failed: prompt injection detected (${found.length} pattern matches). Installation aborted. Pass --force-unsafe-prompts to override.`);
+    }
     return true;
   }
   return false;
@@ -166,7 +172,7 @@ function parseRef(ref) {
 }
 
 // ── GitHub installer ──────────────────────────────────────────────────────────
-async function installFromGitHub(descriptor, skillName, dryRun, checksum) {
+async function installFromGitHub(descriptor, skillName, dryRun, checksum, forceUnsafe = false) {
   const { owner, repo, gitRef, isPinned, subPath } = descriptor;
   const skillPath  = subPath || '';
   const base       = `https://raw.githubusercontent.com/${owner}/${repo}/${gitRef}`;
@@ -198,7 +204,7 @@ async function installFromGitHub(descriptor, skillName, dryRun, checksum) {
   if (checksum && sha256.toLowerCase() !== checksum.toLowerCase()) {
     throw new Error(`Checksum mismatch for ${skillName}: expected ${checksum}, got ${sha256}`);
   }
-  scanForPromptInjection(skillMdContent);
+  scanForPromptInjection(skillMdContent, { throwOnMatch: !forceUnsafe });
 
   // Optionally fetch skill.yaml if it exists
   const yamlUrl = skillPath
@@ -244,7 +250,7 @@ async function installFromGitHub(descriptor, skillName, dryRun, checksum) {
 }
 
 // ── npm installer ─────────────────────────────────────────────────────────────
-function installFromNpm(descriptor, skillName, dryRun, checksum) {
+function installFromNpm(descriptor, skillName, dryRun, checksum, forceUnsafe = false) {
   const pkgName = descriptor.package;
 
   if (dryRun) {
@@ -280,7 +286,7 @@ function installFromNpm(descriptor, skillName, dryRun, checksum) {
     if (checksum && sha256.toLowerCase() !== checksum.toLowerCase()) {
       throw new Error(`Checksum mismatch for ${skillName}: expected ${checksum}, got ${sha256}`);
     }
-    scanForPromptInjection(skillMdContent);
+    scanForPromptInjection(skillMdContent, { throwOnMatch: !forceUnsafe });
 
     const targetDir = path.join(PLUGINS_DIR, skillName);
     fs.rmSync(targetDir, { recursive: true, force: true });
@@ -321,9 +327,13 @@ function isSafeSkillName(skillName) {
 // ═════════════════════════════════════════════════════════════════════════════
 
 /**
- * skill add <ref> [--dry-run] [--checksum <sha256>]
+ * skill add <ref> [--dry-run] [--checksum <sha256>] [--force-unsafe-prompts]
  */
-async function add(ref, { dryRun = false, checksum } = {}) {
+async function add(ref, options = {}) {
+  const dryRun   = Boolean(options.dryRun || options['dry-run']);
+  const checksum = options.checksum || null;
+  const forceUnsafe = Boolean(options.forceUnsafe || options['force-unsafe-prompts']);
+
   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');
@@ -361,9 +371,9 @@ async function add(ref, { dryRun = false, checksum } = {}) {
   let installedSha256 = null;
   try {
     if (descriptor.type === 'github') {
-      installedSha256 = await installFromGitHub(descriptor, skillName, dryRun, checksum);
+      installedSha256 = await installFromGitHub(descriptor, skillName, dryRun, checksum, forceUnsafe);
     } else {
-      installedSha256 = installFromNpm(descriptor, skillName, dryRun, checksum);
+      installedSha256 = installFromNpm(descriptor, skillName, dryRun, checksum, forceUnsafe);
     }
   } catch (err) {
     console.error(c.red(`\n[ERROR] Failed to install '${skillName}': ${err.message}`));

package/.agents/resolver.js

@@ -225,13 +225,115 @@ function buildSkillIndex(projectDir = process.cwd()) {
   return index;
 }
 
+/**
+ * Phase 2: AST & Project Dependency Graph Analysis.
+ * Scans project manifests and configs to detect active technologies
+ * that keyword or regex matching in prompts might omit.
+ *
+ * @param {string} [projectDir=process.cwd()] - Project root directory
+ * @returns {Map<string, number>} Map of skill name to score weight
+ */
+function analyzeImportGraph(projectDir = process.cwd()) {
+  const techSignals = new Map();
+  if (!projectDir || !fs.existsSync(projectDir)) return techSignals;
+
+  const addSignal = (skill, weight) => {
+    techSignals.set(skill, (techSignals.get(skill) || 0) + weight);
+  };
+
+  // 1. Scan package.json dependencies and devDependencies
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const allDeps = {
+        ...(pkg.dependencies || {}),
+        ...(pkg.devDependencies || {}),
+        ...(pkg.peerDependencies || {}),
+      };
+
+      const DEP_SKILL_MAP = {
+        'react': 'react',
+        'react-dom': 'react',
+        'next': 'nextjs',
+        'prisma': 'database',
+        '@prisma/client': 'database',
+        'drizzle-orm': 'database',
+        'drizzle-kit': 'database',
+        'typeorm': 'database',
+        'mongoose': 'database',
+        'pg': 'database',
+        'mysql2': 'database',
+        'vitest': 'testing',
+        'jest': 'testing',
+        'playwright': 'testing',
+        '@playwright/test': 'testing',
+        'cypress': 'testing',
+        'express': 'node',
+        'fastify': 'node',
+        'hono': 'node',
+        '@nestjs/core': 'nestjs',
+        'typescript': 'typescript',
+        'zod': 'typescript',
+        'tailwindcss': 'ui-ux-pro',
+        'lucide-react': 'ui-ux-pro',
+        '@radix-ui/react-dialog': 'web-accessibility',
+        'framer-motion': 'impeccable-design',
+        'dockerode': 'docker',
+        'ioredis': 'system-design',
+        'kafkajs': 'microservices',
+        'amqplib': 'microservices',
+      };
+
+      for (const [dep, skill] of Object.entries(DEP_SKILL_MAP)) {
+        if (allDeps[dep]) {
+          addSignal(skill, 15);
+        }
+      }
+    } catch {
+      // ignore malformed package.json
+    }
+  }
+
+  // 2. Scan framework & tooling configuration files
+  const CONFIG_FILE_MAP = [
+    { file: 'tsconfig.json', skill: 'typescript', weight: 10 },
+    { file: 'next.config.js', skill: 'nextjs', weight: 15 },
+    { file: 'next.config.mjs', skill: 'nextjs', weight: 15 },
+    { file: 'next.config.ts', skill: 'nextjs', weight: 15 },
+    { file: 'tailwind.config.js', skill: 'ui-ux-pro', weight: 10 },
+    { file: 'tailwind.config.ts', skill: 'ui-ux-pro', weight: 10 },
+    { file: 'nest-cli.json', skill: 'nestjs', weight: 15 },
+    { file: 'prisma/schema.prisma', skill: 'database', weight: 15 },
+    { file: 'drizzle.config.ts', skill: 'database', weight: 15 },
+    { file: 'drizzle.config.js', skill: 'database', weight: 15 },
+    { file: 'Dockerfile', skill: 'docker', weight: 15 },
+    { file: 'docker-compose.yml', skill: 'docker', weight: 15 },
+    { file: 'docker-compose.yaml', skill: 'docker', weight: 15 },
+    { file: 'requirements.txt', skill: 'fastapi', weight: 15 },
+    { file: 'pyproject.toml', skill: 'fastapi', weight: 15 },
+    { file: 'vitest.config.ts', skill: 'testing', weight: 15 },
+    { file: 'vitest.config.js', skill: 'testing', weight: 15 },
+    { file: 'playwright.config.ts', skill: 'testing', weight: 15 },
+    { file: 'playwright.config.js', skill: 'testing', weight: 15 },
+  ];
+
+  for (const { file, skill, weight } of CONFIG_FILE_MAP) {
+    if (fs.existsSync(path.join(projectDir, file))) {
+      addSignal(skill, weight);
+    }
+  }
+
+  return techSignals;
+}
+
 /**
  * Resolves the minimal set of skills for a given prompt, file list, and phase.
  *
  * @param {ResolveSkillsOptions} [options={}] - Task context options
  * @returns {ResolvedSkillsResult} Resolved domain, role, and activated skill names
  */
-function resolveSkills({ prompt = '', files = [], phase = 'Build', domain = '' } = {}) {
+function resolveSkills({ prompt = '', files = [], phase = 'Build', domain = '', projectDir = process.cwd() } = {}) {
   const promptText = (prompt || '').toLowerCase();
   const scores = new Map();
 
@@ -267,6 +369,14 @@ function resolveSkills({ prompt = '', files = [], phase = 'Build', domain = '' }
     }
   }
 
+  // Phase 2: Merge AST & Project Dependency Graph Signals
+  if (projectDir) {
+    const astSignals = analyzeImportGraph(projectDir);
+    for (const [skill, astScore] of astSignals) {
+      scores.set(skill, (scores.get(skill) || 0) + astScore);
+    }
+  }
+
   // Sort matched domain skills by score descending
   const sortedDomainSkills = Array.from(scores.entries())
     .sort((a, b) => b[1] - a[1])
@@ -332,5 +442,6 @@ function formatDeclaration(resolution) {
 module.exports = {
   buildSkillIndex,
   resolveSkills,
+  analyzeImportGraph,
   formatDeclaration,
 };

package/.agents/stats.js

@@ -0,0 +1,133 @@
+/**
+ * .agents/stats.js
+ * ContextOS — Context Savings & Token Optimization Report
+ *
+ * Measures:
+ *   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
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const profiles = require('./profiles.js');
+
+function estimateTokens(text) {
+  // Common heuristic across GPT-4, Claude, Gemini: ~4 characters per token
+  return Math.max(1, Math.round(text.length / 4));
+}
+
+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;
+  if (fs.existsSync(agentsMdPath)) {
+    agentsMdChars = fs.readFileSync(agentsMdPath, 'utf8').length;
+  }
+
+  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');
+      if (fs.existsSync(skillMd)) {
+        skillCharMap.set(entry.name, fs.readFileSync(skillMd, 'utf8').length);
+      }
+    }
+  }
+
+  const totalSkillCount = skillCharMap.size;
+  let fullChars = agentsMdChars;
+  for (const chars of skillCharMap.values()) {
+    fullChars += chars;
+  }
+
+  // Active profile
+  const activeProfile = profiles.getActiveProfile(projectDir);
+  const profileName = activeProfile ? (activeProfile.name || activeProfile.profile) : 'startup (recommended)';
+  const excludedSkills = new Set(
+    activeProfile ? activeProfile.exclude_skills || [] : (profiles.getProfile('startup')?.exclude_skills || [])
+  );
+
+  let profileChars = agentsMdChars;
+  let profiledSkillCount = 0;
+  for (const [skill, chars] of skillCharMap) {
+    if (!excludedSkills.has(skill)) {
+      profileChars += chars;
+      profiledSkillCount++;
+    }
+  }
+
+  // Resolved context: 2 foundational skills + average 2 domain skills (e.g. react + ui-ux-pro)
+  const typicalResolvedSkills = ['engineering-workflow', 'ponytail-mindset', 'react', 'ui-ux-pro'];
+  let resolvedChars = agentsMdChars;
+  let resolvedSkillCount = 0;
+  for (const s of typicalResolvedSkills) {
+    if (skillCharMap.has(s)) {
+      resolvedChars += skillCharMap.get(s);
+      resolvedSkillCount++;
+    }
+  }
+
+  const fullTokens = estimateTokens({ length: fullChars });
+  const profileTokens = estimateTokens({ length: profileChars });
+  const resolvedTokens = estimateTokens({ length: resolvedChars });
+
+  const profileSavings = fullTokens > 0 ? (((fullTokens - profileTokens) / fullTokens) * 100).toFixed(1) : '0.0';
+  const resolvedSavings = fullTokens > 0 ? (((fullTokens - resolvedTokens) / fullTokens) * 100).toFixed(1) : '0.0';
+
+  return {
+    totalSkillCount,
+    profiledSkillCount,
+    resolvedSkillCount,
+    profileName,
+    full: { chars: fullChars, tokens: fullTokens },
+    profile: { chars: profileChars, tokens: profileTokens, savings: profileSavings },
+    resolved: { chars: resolvedChars, tokens: resolvedTokens, savings: resolvedSavings },
+  };
+}
+
+function runStats(projectDir = process.cwd()) {
+  const stats = calculateContextStats(projectDir);
+
+  console.log('\nContextOS — Context Savings Report\n');
+  console.log('┌──────────────────────────────────────┬─────────────┬──────────┐');
+  console.log('│ Mode                                 │   Tokens    │  Savings │');
+  console.log('├──────────────────────────────────────┼─────────────┼──────────┤');
+
+  const fullLabel = `Full (${stats.totalSkillCount} skills)`;
+  const fullTok = stats.full.tokens.toLocaleString().padStart(9);
+  console.log(`│ ${fullLabel.padEnd(36)} │ ${fullTok}   │     —    │`);
+
+  const profLabel = `Profile: ${stats.profileName} (${stats.profiledSkillCount} skills)`;
+  const profTok = stats.profile.tokens.toLocaleString().padStart(9);
+  const profSav = `${stats.profile.savings}%`.padStart(7);
+  console.log(`│ ${profLabel.slice(0, 36).padEnd(36)} │ ${profTok}   │  ${profSav} │`);
+
+  const resLabel = `Resolved: typical task (${stats.resolvedSkillCount} skills)`;
+  const resTok = stats.resolved.tokens.toLocaleString().padStart(9);
+  const resSav = `${stats.resolved.savings}%`.padStart(7);
+  console.log(`│ ${resLabel.slice(0, 36).padEnd(36)} │ ${resTok}   │  ${resSav} │`);
+
+  console.log('└──────────────────────────────────────┴─────────────┴──────────┘');
+  console.log('\nToken estimation: ~4 chars/token (GPT-4 / Claude / Gemini approximation)');
+  console.log('Dynamic skill resolution prevents prompt bloat and cuts LLM API costs.\n');
+
+  return stats;
+}
+
+if (require.main === module) {
+  runStats();
+}
+
+module.exports = {
+  calculateContextStats,
+  runStats,
+  estimateTokens,
+};