contextos-agents 1.5.0 → 1.6.0

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,
+};

package/.agents/watch.js

@@ -0,0 +1,161 @@
+/**
+ * .agents/watch.js
+ * ContextOS — Continuous Context Sync & File Watcher Daemon
+ *
+ * Watches:
+ *   1. .agents/core/skills/ — regenerates agent configs on skill markdown edits
+ *   2. package.json & manifests — detects tech stack drift and recommends profile adjustments
+ *
+ * Provides instant feedback during local development without manual re-exports.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const profiles = require('./profiles.js');
+
+/**
+ * Runs the ContextOS watch daemon.
+ *
+ * @param {string} [projectDir=process.cwd()] - Target project directory
+ * @param {Object} [options={}] - Watcher configuration options
+ * @param {number} [options.debounceMs=300] - Debounce delay in milliseconds
+ * @param {Function} [options.onSync] - Callback after a sync event completes
+ * @param {boolean} [options.exitOnSigint=true] - Whether to register process exit handlers
+ * @returns {Object} Controller object with a `close()` method
+ */
+function runWatch(projectDir = process.cwd(), options = {}) {
+  const debounceMs = options.debounceMs || 300;
+  const agentsDir = path.join(projectDir, '.agents');
+  const skillsDir = path.join(agentsDir, 'core', 'skills');
+  const ctxPath = path.join(agentsDir, 'ctx.js');
+
+  console.log('\n[ContextOS Watch] Initializing background continuous sync daemon...');
+  console.log(`[ContextOS Watch] Project directory: ${projectDir}`);
+
+  let lastStack = profiles.detectStack(projectDir);
+  console.log(`[ContextOS Watch] Initial stack: ${lastStack.detected.join(', ') || 'Generic JS'} (${lastStack.recommendedProfile})`);
+
+  let debounceTimer = null;
+  let isSyncing = false;
+  const watchers = [];
+
+  function triggerRecompile(sourceReason) {
+    if (debounceTimer) clearTimeout(debounceTimer);
+
+    debounceTimer = setTimeout(() => {
+      if (isSyncing) return;
+      isSyncing = true;
+
+      try {
+        const time = new Date().toLocaleTimeString();
+        console.log(`[${time}] [SYNC] Changes detected in ${sourceReason}. Recompiling agent skills...`);
+
+        if (fs.existsSync(ctxPath)) {
+          execFileSync(process.execPath, [ctxPath, 'export', 'all'], {
+            cwd: projectDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+          console.log(`[${time}] [OK] Skills exported to all agents (Gemini, Claude, Cursor, Copilot, Aider, Zed).`);
+        }
+
+        if (typeof options.onSync === 'function') {
+          options.onSync({ type: 'recompile', reason: sourceReason });
+        }
+      } catch (err) {
+        console.error(`[WARN] Auto-recompile failed: ${err.message}`);
+      } finally {
+        isSyncing = false;
+      }
+    }, debounceMs);
+  }
+
+  function checkStackChange() {
+    try {
+      const currentStack = profiles.detectStack(projectDir);
+      const prevStr = lastStack.detected.sort().join(',');
+      const currStr = currentStack.detected.sort().join(',');
+
+      if (prevStr !== currStr) {
+        const time = new Date().toLocaleTimeString();
+        console.log(`\n[${time}] [DETECT] Project dependencies changed!`);
+        console.log(`       Detected stack : ${currentStack.detected.join(', ')}`);
+        console.log(`       Recommendation : Profile '${currentStack.recommendedProfile}'`);
+        console.log(`       Run: contextos profile apply ${currentStack.recommendedProfile}\n`);
+        lastStack = currentStack;
+
+        if (typeof options.onSync === 'function') {
+          options.onSync({ type: 'stack_change', stack: currentStack });
+        }
+      }
+    } catch {
+      // ignore transient filesystem read errors
+    }
+  }
+
+  // 1. Watch .agents/core/skills/ directory
+  if (fs.existsSync(skillsDir)) {
+    try {
+      const skillsWatcher = fs.watch(skillsDir, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+        const norm = filename.replace(/\\/g, '/');
+        if (norm.endsWith('.md') || norm.endsWith('.json') || norm.endsWith('.yaml') || norm.endsWith('.yml')) {
+          triggerRecompile(`skills/${filename}`);
+        }
+      });
+      watchers.push(skillsWatcher);
+    } catch (e) {
+      console.warn(`[WARN] Could not establish recursive watcher on skills directory: ${e.message}`);
+    }
+  }
+
+  // 2. Watch package.json
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkgWatcher = fs.watch(pkgPath, () => {
+        checkStackChange();
+      });
+      watchers.push(pkgWatcher);
+    } catch (e) {
+      console.warn(`[WARN] Could not watch package.json: ${e.message}`);
+    }
+  }
+
+  console.log('[ContextOS Watch] Watching for skill updates and dependency shifts. Press Ctrl+C to stop.\n');
+
+  function close() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    for (const w of watchers) {
+      try {
+        w.close();
+      } catch {}
+    }
+  }
+
+  if (options.exitOnSigint !== false) {
+    const onExit = () => {
+      console.log('\n[ContextOS Watch] Stopping watcher daemon.');
+      close();
+      process.exit(0);
+    };
+    process.once('SIGINT', onExit);
+    process.once('SIGTERM', onExit);
+  }
+
+  return {
+    close,
+    triggerRecompile,
+    checkStackChange,
+  };
+}
+
+if (require.main === module) {
+  runWatch();
+}
+
+module.exports = {
+  runWatch,
+};

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/contextos-agents.svg)](https://www.npmjs.com/package/contextos-agents)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D16.7.0-brightgreen.svg)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](#testing)
 
 This is an open-source set of skills and behavioral rules for AI assistants. The package automatically installs an `.agents` folder into your project, teaching your AI assistant software development best practices (UI Design, Architecture, Security, and more).
@@ -49,10 +49,10 @@ Most AI coding assistants suffer from two extremes: they either operate in a vac
 
 ### Key Developer Advantages
 
-- 🚀 **Zero-Config Onboarding:** Run `npx contextos-agents` in your repository. It auto-detects your stack (React, Node, Python, etc.) and sets up the ideal profile in seconds.
-- 🎯 **Tailored Project Profiles:** Use `mvp` for lean, rapid prototyping without bloated microservices boilerplate, or `enterprise` for strict TDD, DDD, and security auditing.
-- 🛡️ **Autonomous Multi-Agent Worktrees:** Run parallel tasks safely with the bundled MCP server—subagents work in isolated Git worktrees without corrupting your active workspace.
-- 📊 **Verifiable Benchmarks:** Backed by reproducible side-by-side benchmarks demonstrating measurable code quality improvements and reduced token usage.
+- **Zero-Config Onboarding:** Run `npx contextos-agents` in your repository. It auto-detects your stack (React, Node, Python, etc.) and sets up the ideal profile in seconds.
+- **Tailored Project Profiles:** Use `mvp` for lean, rapid prototyping without bloated microservices boilerplate, or `enterprise` for strict TDD, DDD, and security auditing.
+- **Autonomous Multi-Agent Worktrees:** Run parallel tasks safely with the bundled MCP server—subagents work in isolated Git worktrees without corrupting your active workspace.
+- **Verifiable Benchmarks:** Backed by reproducible side-by-side benchmarks demonstrating measurable code quality improvements and reduced token usage.
 
 ## Project Profiles & Stack Auto-Detection
 
@@ -209,6 +209,32 @@ ContextOS commits generated adapter configurations (`.cursorrules`, `.cursor/rul
 - **Automated Sync & Drift Prevention:** CI strictly validates that generated exports match source skills (`node .agents/ctx.js validate`). Any uncommitted adapter drift fails CI checks via `git diff --exit-code`.
 - **Contributor Workflow:** Source rules are authored exclusively in `.agents/core/skills/<name>/SKILL.md`. Running `node .agents/ctx.js export all` regenerates all assistant configurations deterministically.
 
+### CI Quality Gate Action (`contextos-gate`)
+
+You can guard your repository against skill drift, secret leaks, and rule regressions using the official reusable GitHub Composite Action:
+
+```yaml
+# .github/workflows/pr-gate.yml
+name: ContextOS Quality Gate
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: kok-o/contextos-agents/.github/actions/contextos-gate@main
+        with:
+          node-version: '20'
+```
+
+The action validates skill frontmatter integrity, checks for adapter configuration drift, scans for accidental secrets or API keys, and runs your test suite.
+
 ### Plugin Skills & Validation
 
 You can expand your `.agents` folder with community plugins or validate your own custom skills using the top-level commands:
@@ -381,7 +407,7 @@ The runtime sandbox evaluates model outputs against real-world engineering invar
 | **DDD Order Aggregate Root** | Architecture & DDD | `ddd`, `system-design`, `decisions` | Immutable `Money` Value Object, state-machine invariants (PENDING → PAID → SHIPPED), explicit Domain Event classes with queue draining. |
 | **Resilient API Client** | Reliability & Async | `typescript`, `system-design`, `performance` | 3-state Circuit Breaker (CLOSED → OPEN → HALF-OPEN), `AbortController` timeouts, typed error taxonomy without credential leakage. |
 
-### Running Benchmarks Locally
+### Running Benchmarks Locally & in CI
 
 You can run the benchmark suite locally with your own API keys:
 
@@ -393,10 +419,24 @@ npm run benchmark:runtime -- --provider gemini --model gemini-2.5-flash
 # Run with OpenAI:
 $env:OPENAI_API_KEY = "sk-..."
 npm run benchmark:runtime -- --provider openai --model gpt-4o
+
+# Run complete multi-model runtime matrix (Gemini, OpenRouter, AgentRouter):
+GEMINI_API_KEY=... OPENROUTER_API_KEY=... AGENTROUTER_API_KEY=... node benchmarks/run-multi-runtime.cjs
 ```
 
 When executed, reports are generated in `benchmarks/results/` (`.html`, `.md`, `.json`) and tracked so results are visible and shareable.
 
+> [!NOTE]
+> **Why Runtime Benchmarks Are Dispatch-Only in CI:** Standard CI checks (`validate-skills.yml`) run hermetically without external API calls to avoid flaky network dependencies and API token expenditures on every pull request. Live runtime evaluation is triggered on demand via GitHub Actions **Workflow Dispatch** ([`benchmark-runtime.yml`](.github/workflows/benchmark-runtime.yml)) using secure repository secrets.
+
+
+## Security — Third-Party Skills
+
+ContextOS skills are **executable context** — they become part of the system prompt that controls your AI agent's behavior. A malicious skill could instruct the AI agent to exfiltrate environment variables, modify files, or ignore your project's security policies.
+
+> [!CAUTION]
+> **Install skills only from repositories you trust as you would trust executable code.** Skills installed via `ctx.js skill add` from npm or GitHub are not sandboxed. ContextOS includes a built-in prompt injection scanner, but it cannot guarantee safety of arbitrary third-party content.
+
 ## Contributing
 
 We are open to pull requests! See [CONTRIBUTING.md](./CONTRIBUTING.md) for a step-by-step guide on how to add a new skill.