@nerviq/cli 1.29.1 → 1.30.0

package/bin/cli.js

@@ -40,7 +40,7 @@ const COMMAND_ALIASES = {
   gov: 'governance',
   outcome: 'feedback',
 };
-const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'init', 'augment', 'suggest-only', 'plan', 'apply', 'fix', 'rollback', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'certify', 'serve', 'check-health', 'dashboard', 'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise', 'harmony-watch', 'harmony-governance', 'harmony-score', 'harmony-demo', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export', 'freshness', 'suggest-rules', 'profile', 'baseline', 'exception', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'org', 'setup', 'init', 'augment', 'suggest-only', 'plan', 'apply', 'fix', 'rollback', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'doctor', 'convert', 'migrate', 'catalog', 'certify', 'serve', 'check-health', 'dashboard', 'harmony-audit', 'harmony-sync', 'harmony-drift', 'harmony-advise', 'harmony-watch', 'harmony-governance', 'harmony-score', 'harmony-demo', 'harmony-add', 'synergy-report', 'anti-patterns', 'rules-export', 'freshness', 'suggest-rules', 'profile', 'baseline', 'exception', 'pr-check', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -675,6 +675,12 @@ const HELP = `
     nerviq exception list         Show active and expired exceptions
     nerviq exception prune        Remove expired exceptions
 
+  PR / CI INTEGRATION
+    nerviq pr-check               Composite PR check: audit + diff-only +
+                                  threshold gate, emits markdown + JSON for
+                                  PR-comment / GitHub-Action consumers
+    nerviq pr-check --threshold 80 --diff-base main --diff-head HEAD --json
+
   TEAM PROFILES
     nerviq profile save <name>    Save current preferences as a named profile
     nerviq profile load <name>    Load and display a saved profile
@@ -850,6 +856,7 @@ async function main() {
     badge: flags.includes('--badge'),
     quiet: flags.includes('--quiet'),
     agentMode: flags.includes('--agent-mode'),
+    agentReady: flags.includes('--agent-ready'),
     autoSync: flags.includes('--auto-sync'),
     dryRun: flags.includes('--dry-run'),
     apply: flags.includes('--apply'),
@@ -1615,6 +1622,94 @@ async function main() {
       }
       process.exit(0);
     } else if (normalizedCommand === 'certify') {
+      // AI-13: --agent-ready mode runs a focused agent-readiness audit
+      // (separate from the general harmony-based certification). Six pass/fail
+      // criteria specific to whether AI coding agents can safely operate in
+      // this repo. Designed to be agent-callable: returns a clean JSON
+      // verdict object suitable for an agent to consume programmatically.
+      if (options.agentReady) {
+        const dir = options.dir || process.cwd();
+        const fs = require('fs');
+        const path = require('path');
+        const { audit } = require('../src/audit');
+        const result = await audit({ dir, silent: true });
+        const exists = (p) => fs.existsSync(path.join(dir, p));
+        const claudeMdPresent = exists('CLAUDE.md') || exists('.claude/CLAUDE.md');
+        const agentsMdPresent = exists('AGENTS.md');
+        const hasContext = claudeMdPresent || agentsMdPresent;
+        const gitignoreEnv = (() => {
+          if (!exists('.gitignore')) return false;
+          try {
+            const gi = fs.readFileSync(path.join(dir, '.gitignore'), 'utf8');
+            return /\.env\b/.test(gi);
+          } catch { return false; }
+        })();
+        const denyRulesConfigured = (() => {
+          if (!exists('.claude/settings.json')) return false;
+          try {
+            const s = JSON.parse(fs.readFileSync(path.join(dir, '.claude/settings.json'), 'utf8'));
+            const deny = (s.permissions && s.permissions.deny) || [];
+            return Array.isArray(deny) && deny.length > 0;
+          } catch { return false; }
+        })();
+        const hints = Array.isArray(result.shallowRiskHints) ? result.shallowRiskHints : [];
+        const noCriticalShallowRisk = !hints.some((h) => h && h.severity === 'critical');
+        const noStaleReferences = !(result.staleReferences && result.staleReferences.count > 0);
+        const checks = [
+          { id: 'agent-context-present', label: 'CLAUDE.md or AGENTS.md exists', passed: hasContext, critical: true },
+          { id: 'gitignore-blocks-env', label: '.gitignore blocks .env files', passed: gitignoreEnv, critical: true },
+          { id: 'deny-rules-configured', label: '.claude/settings.json has permission deny rules', passed: denyRulesConfigured, critical: false },
+          { id: 'no-critical-shallow-risk', label: 'No critical shallow-risk findings (secrets, dangerous auto-approve)', passed: noCriticalShallowRisk, critical: true },
+          { id: 'no-stale-references', label: 'No stale references in agent docs (PROD-03)', passed: noStaleReferences, critical: false },
+          { id: 'governance-score-floor', label: 'Audit score >= 50', passed: result.score >= 50, critical: false },
+        ];
+        const failedCritical = checks.filter((c) => c.critical && !c.passed);
+        const passedCount = checks.filter((c) => c.passed).length;
+        const verdict = failedCritical.length === 0
+          ? (passedCount === checks.length ? 'agent-ready-full' : 'agent-ready-with-caveats')
+          : 'not-agent-ready';
+        const payload = {
+          command: 'certify --agent-ready',
+          verdict,
+          passedCount,
+          totalChecks: checks.length,
+          score: result.score,
+          checks: checks.map((c) => ({
+            id: c.id,
+            label: c.label,
+            passed: c.passed,
+            critical: c.critical,
+          })),
+          badge: verdict === 'agent-ready-full'
+            ? '[![Nerviq agent-ready](https://img.shields.io/badge/nerviq-agent--ready-green)](https://nerviq.net)'
+            : verdict === 'agent-ready-with-caveats'
+              ? '[![Nerviq agent-ready (caveats)](https://img.shields.io/badge/nerviq-agent--ready--caveats-yellow)](https://nerviq.net)'
+              : '[![Nerviq not agent-ready](https://img.shields.io/badge/nerviq-not--agent--ready-red)](https://nerviq.net)',
+          exitCode: failedCritical.length === 0 ? 0 : 1,
+        };
+        if (options.json) {
+          process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+        } else {
+          console.log('');
+          console.log('  nerviq certify --agent-ready');
+          console.log('  ═══════════════════════════════════════');
+          console.log('');
+          const verdictColor = verdict === 'agent-ready-full' ? '\x1b[32m' : verdict === 'agent-ready-with-caveats' ? '\x1b[33m' : '\x1b[31m';
+          console.log(`  Verdict: ${verdictColor}${verdict}\x1b[0m  (${passedCount}/${checks.length} checks passed)`);
+          console.log('');
+          for (const c of checks) {
+            const mark = c.passed ? '\x1b[32m✓\x1b[0m' : (c.critical ? '\x1b[31m✗\x1b[0m' : '\x1b[33m!\x1b[0m');
+            const tag = c.critical ? '\x1b[2m[critical]\x1b[0m' : '\x1b[2m[advisory]\x1b[0m';
+            console.log(`  ${mark} ${c.label}  ${tag}`);
+          }
+          console.log('');
+          console.log(`  Badge:`);
+          console.log(`  ${payload.badge}`);
+          console.log('');
+        }
+        process.exit(payload.exitCode);
+      }
+
       const { certifyProject, generateCertBadge } = require('../src/certification');
       const certResult = await certifyProject(options.dir);
       if (options.json) {
@@ -1912,7 +2007,16 @@ async function main() {
       if (subcommand === 'list') {
         const records = listExceptions(options.dir);
         if (options.json) {
-          console.log(JSON.stringify(records, null, 2));
+          // BUG-06 fix: stable envelope shape for governance/compliance
+          // automation. Previously emitted raw array; consumers checking
+          // for `.records` (the conventional envelope key) got undefined.
+          // Now: { records: [...], count, generatedAt } — array shape is
+          // the same regardless of count (0, 1, or N).
+          console.log(JSON.stringify({
+            records,
+            count: records.length,
+            generatedAt: new Date().toISOString(),
+          }, null, 2));
         } else {
           console.log('');
           console.log(formatExceptionsList(records));
@@ -1931,7 +2035,14 @@ async function main() {
           scope: options.exceptionScope || 'all',
         });
         if (options.json) {
-          console.log(JSON.stringify(result.record, null, 2));
+          // BUG-06 fix: matched envelope shape for symmetry with `list`.
+          // Single-record add returns the same `records: [...]` array so
+          // automation can use one parser for both commands.
+          console.log(JSON.stringify({
+            records: result.record ? [result.record] : [],
+            count: result.record ? 1 : 0,
+            generatedAt: new Date().toISOString(),
+          }, null, 2));
         } else {
           console.log('');
           console.log(`  Exception added: ${result.record.id}`);
@@ -1956,6 +2067,110 @@ async function main() {
 
       console.error('\n  Error: exception supports `add`, `list`, and `prune`.\n');
       process.exit(1);
+    } else if (normalizedCommand === 'pr-check') {
+      // LOOP-02: composite PR-check command. Runs the right pieces in the
+      // right order with one consolidated PR-comment-friendly output.
+      // The primitives already exist (audit --diff-only --drift-mode ci,
+      // --threshold, --require, --format=markdown); pr-check just unifies
+      // them so Team-tier CI integrations don't have to assemble the
+      // composite themselves.
+      const dir = options.dir || process.cwd();
+      const threshold = options.threshold !== null ? options.threshold : 70;
+      const platform = options.platform;
+
+      // Step 1: full audit (markdown format, no harmony banner contamination
+      // because BUG-02 fixed the suppress).
+      const fullAudit = await audit({
+        dir,
+        platform,
+        silent: true,
+      });
+
+      // Step 2: diff-only audit if a baseline exists or --diff-base/--diff-head
+      // are provided. Otherwise gracefully skip.
+      let diffSection = null;
+      try {
+        const { getChangedFiles, buildDiffOnlyAuditView } = require('../src/diff-only');
+        const diffInfo = getChangedFiles(dir, {
+          diffBase: options.diffBase,
+          diffHead: options.diffHead,
+        });
+        if (diffInfo && Array.isArray(diffInfo.changedFiles) && diffInfo.changedFiles.length > 0) {
+          diffSection = buildDiffOnlyAuditView(fullAudit, diffInfo);
+        }
+      } catch {
+        diffSection = null;
+      }
+
+      // Step 3: build a markdown summary suitable for posting as a PR comment.
+      const lines = [];
+      lines.push('## Nerviq PR Check');
+      lines.push('');
+      lines.push(`- **Score:** ${fullAudit.score}/100 (organic ${fullAudit.organicScore || fullAudit.score}/100)`);
+      lines.push(`- **Threshold:** ${threshold}`);
+      lines.push(`- **Platform:** ${fullAudit.platformLabel || fullAudit.platform || platform || 'auto-detected'}`);
+      lines.push(`- **Failed checks:** ${fullAudit.failed} (passed ${fullAudit.passed})`);
+
+      if (fullAudit.staleReferences && fullAudit.staleReferences.count > 0) {
+        lines.push('');
+        lines.push(`### 📌 Stale references in agent docs: ${fullAudit.staleReferences.count}`);
+        for (const sample of fullAudit.staleReferences.topSample) {
+          lines.push(`- \`${sample.file || '?'}:${sample.line || '?'}\` — ${sample.fix}`);
+        }
+      }
+
+      if (diffSection && Array.isArray(diffSection.changedFiles) && diffSection.changedFiles.length > 0) {
+        lines.push('');
+        lines.push(`### Changed files in this PR: ${diffSection.changedFiles.length}`);
+        for (const cf of diffSection.changedFiles.slice(0, 10)) {
+          lines.push(`- \`${cf}\``);
+        }
+        if (diffSection.changedFiles.length > 10) {
+          lines.push(`- … and ${diffSection.changedFiles.length - 10} more`);
+        }
+      }
+
+      const topActions = (fullAudit.liteSummary && fullAudit.liteSummary.topNextActions) || [];
+      if (topActions.length > 0) {
+        lines.push('');
+        lines.push('### Top next actions');
+        for (const a of topActions.slice(0, 5)) {
+          lines.push(`- **${a.name}** (${a.impact}) — ${a.fix}`);
+        }
+      }
+
+      const gateFailed = fullAudit.score < threshold;
+      lines.push('');
+      lines.push(`### Gate: ${gateFailed ? '❌ FAIL' : '✅ PASS'}`);
+      lines.push(`Score ${fullAudit.score} ${gateFailed ? '<' : '≥'} threshold ${threshold}`);
+
+      const markdown = lines.join('\n');
+
+      if (options.json) {
+        const payload = {
+          command: 'pr-check',
+          gate: gateFailed ? 'fail' : 'pass',
+          threshold,
+          exitCode: gateFailed ? 1 : 0,
+          score: fullAudit.score,
+          organicScore: fullAudit.organicScore,
+          platform: fullAudit.platform,
+          platformLabel: fullAudit.platformLabel,
+          passed: fullAudit.passed,
+          failed: fullAudit.failed,
+          staleReferences: fullAudit.staleReferences || null,
+          changedFiles: diffSection ? diffSection.changedFiles : [],
+          topNextActions: topActions.slice(0, 5),
+          markdown,
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+      } else {
+        console.log('');
+        console.log(markdown);
+        console.log('');
+      }
+
+      process.exit(gateFailed ? 1 : 0);
     } else if (normalizedCommand === 'profile') {
       const { saveProfile, loadProfile, listProfiles, exportProfile, formatProfileList, formatProfile } = require('../src/profiles');
       const subcommand = parsed.extraArgs[0];
@@ -2296,6 +2511,10 @@ async function main() {
         process.exit(0);
       }
       // MOAT-01: Harmony-first default — when 2+ platforms and platform not explicit
+      // BUG-02 fix: also suppress the human-readable Harmony banner when a
+      // machine format is requested (sarif/junit/csv/markdown), so parsers
+      // consuming stdout don't have to add `--no-harmony-first` defensively.
+      const machineFormat = options.format && ['sarif', 'junit', 'csv', 'markdown'].includes(String(options.format).toLowerCase());
       let harmonyFirstResult = null;
       if (!options.platformExplicit && !options.noHarmonyFirst && !options.diffOnly && !options.driftMode && !options.workspace) {
         const detected = detectPlatforms(options.dir) || [];
@@ -2303,7 +2522,8 @@ async function main() {
           try {
             const { harmonyAudit } = require('../src/harmony/audit');
             harmonyFirstResult = await harmonyAudit({ dir: options.dir, silent: true });
-            if (!options.json && harmonyFirstResult) {
+            const suppressBanner = options.json || machineFormat;
+            if (!suppressBanner && harmonyFirstResult) {
               const hs = harmonyFirstResult.harmonyScore;
               const driftCount = (harmonyFirstResult.drift && harmonyFirstResult.drift.drifts) ? harmonyFirstResult.drift.drifts.length : 0;
               const platformLabels = (harmonyFirstResult.activePlatforms || []).map(p => p.label || p.platform).join(' + ');
@@ -2321,7 +2541,14 @@ async function main() {
 
       if (options.fix) {
         if (options.diffOnly) {
-          console.error('\n  Error: --diff-only cannot be combined with --fix.\n');
+          if (options.json) {
+            process.stdout.write(JSON.stringify({
+              error: '--diff-only cannot be combined with --fix.',
+              exitCode: 2,
+            }) + '\n');
+          } else {
+            console.error('\n  Error: --diff-only cannot be combined with --fix.\n');
+          }
           process.exit(2);
         }
 
@@ -2330,6 +2557,11 @@ async function main() {
         const failedResults = (auditResult.results || []).filter((item) => item.passed === false);
         const targetKeys = getFixableFailedResults(failedResults, { mode: 'audit' }).map((item) => item.key);
 
+        // BUG-01 fix: under --json, suppress human-readable autofix narration
+        // and emit the full outcome shape as one valid JSON document instead.
+        const silentLogger = options.json
+          ? { log() {}, warn() {}, error() {} }
+          : console;
         const outcome = await runAuditFixWorkflow({
           dir: options.dir,
           platform: options.platform,
@@ -2339,7 +2571,51 @@ async function main() {
           apply: options.apply,
           pr: options.pr,
           outputPath: options.out,
+          logger: silentLogger,
         });
+        if (options.json) {
+          // Serialize the outcome as the canonical machine contract for
+          // `audit --fix --json`. Includes plan, exitCode, patchArtifact,
+          // rollbackArtifact, reAudit summary, unresolvedKeys, warnings,
+          // and branchName when --pr was used.
+          const payload = {
+            command: 'audit --fix',
+            mode: outcome.branchName ? 'pr'
+              : (options.apply ? 'apply' : 'dry-run'),
+            exitCode: outcome.exitCode,
+            requestedKeys: outcome.requestedKeys || [],
+            plan: outcome.plan || [],
+            advisoryOnly: outcome.advisoryOnly || [],
+            patchArtifact: outcome.patchArtifact
+              ? {
+                  path: outcome.patchArtifact.path,
+                  relativePath: outcome.patchArtifact.relativePath,
+                }
+              : null,
+            rollbackArtifact: outcome.rollbackArtifact
+              ? {
+                  path: outcome.rollbackArtifact.path,
+                  relativePath: outcome.rollbackArtifact.relativePath,
+                }
+              : null,
+            reAudit: outcome.reAudit
+              ? {
+                  score: outcome.reAudit.score,
+                  organicScore: outcome.reAudit.organicScore,
+                  passed: Array.isArray(outcome.reAudit.results)
+                    ? outcome.reAudit.results.filter((r) => r.passed === true).length
+                    : null,
+                  failed: Array.isArray(outcome.reAudit.results)
+                    ? outcome.reAudit.results.filter((r) => r.passed === false).length
+                    : null,
+                }
+              : null,
+            unresolvedKeys: outcome.unresolvedKeys || [],
+            branchName: outcome.branchName || null,
+            warnings: outcome.warnings || [],
+          };
+          process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+        }
         process.exit(outcome.exitCode);
       }
 

package/docs/integration-contracts.md

@@ -92,7 +92,7 @@ Example:
     "suggestedNextCommand": "npx nerviq fix verificationLoop"
   },
   "meta": {
-    "cliVersion": "1.29.1",
+    "cliVersion": "1.30.0",
     "source": "nerviq-cli",
     "webhookFormat": "generic-audit-event"
   }

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.29.1",
+  "version": "1.30.0",
   "description": "The intelligent nervous system for AI coding agents — 2,441 checks (8 platforms × ~300 governance rules), 10 languages, 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./sdk": "./sdk/index.js",
+    "./sdk/types": "./sdk/index.d.ts",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "nerviq": "bin/cli.js",
     "@nerviq/cli": "bin/cli.js",
@@ -11,10 +17,10 @@
   "files": [
     "bin",
     "src",
+    "sdk",
     "README.md",
     "docs",
     "contracts",
-    "sdk/README.md",
     "CHANGELOG.md",
     "SECURITY.md"
   ],
@@ -25,10 +31,12 @@
     "verify:release-metadata": "node tools/validate-release-metadata.js",
     "prepublish:check": "node tools/pre-publish.js",
     "prepublishOnly": "node tools/pre-publish.js",
+    "postinstall": "node tools/postinstall.js || true",
     "test:jest": "jest",
     "test:coverage": "jest --coverage",
     "test:all": "npm test && npx jest && node test/check-matrix.js && node test/codex-check-matrix.js && node test/gemini-check-matrix.js && node test/copilot-check-matrix.js && node test/cursor-check-matrix.js && node test/windsurf-check-matrix.js && node test/aider-check-matrix.js && node test/opencode-check-matrix.js && node test/golden-matrix.js && node test/codex-golden-matrix.js && node test/gemini-golden-matrix.js && node test/copilot-golden-matrix.js && node test/cursor-golden-matrix.js && node test/windsurf-golden-matrix.js && node test/aider-golden-matrix.js && node test/opencode-golden-matrix.js",
     "benchmark:perf": "node tools/benchmark.js",
+    "announce:release": "node tools/announce-release.js",
     "catalog": "node -e \"const {generateCatalog}=require('./src/catalog');console.log(JSON.stringify(generateCatalog(),null,2))\""
   },
   "keywords": [

package/sdk/README.md

@@ -1,13 +1,22 @@
-# @nerviq/sdk
+# Nerviq SDK (bundled inside `@nerviq/cli`)
 
 Programmatic SDK for Nerviq audit, Harmony, catalog access, and experimental Synergy workflows.
 
 ## Install
 
 ```bash
-npm install @nerviq/sdk
+npm install @nerviq/cli
 ```
 
+The SDK ships bundled inside `@nerviq/cli` per MEMO-03 (B = BUNDLE, signed 2026-04-28). There is no separate `@nerviq/sdk` npm package — earlier docs that referenced one were aspirational. Both import paths below work:
+
+```js
+const sdk = require('@nerviq/cli/sdk');           // explicit SDK subpath (typed, input-validated)
+const { audit } = require('@nerviq/cli');          // top-level — same exports
+```
+
+The two paths return identical surface; pick whichever is cleaner for your codebase.
+
 ## Stability
 
 - Stable for production workflows: `audit`, `harmonyAudit`, `detectPlatforms`, `getCatalog`
@@ -17,7 +26,7 @@ npm install @nerviq/sdk
 ## Quick Start
 
 ```js
-const { audit, harmonyAudit, detectPlatforms } = require('@nerviq/sdk');
+const { audit, harmonyAudit, detectPlatforms } = require('@nerviq/cli/sdk');
 
 async function main() {
   const repoDir = process.cwd();

package/sdk/examples/langchain-integration.md

@@ -0,0 +1,128 @@
+# LangChain integration — using Nerviq as a tool
+
+> Reference example for AI-09. Wires `@nerviq/cli/sdk` into a LangChain
+> agent as a callable tool, so an autonomous LangChain agent can audit
+> its own repo, check Harmony Score, and surface stale references mid-task.
+>
+> Pairs with: [`self-governing-agent.js`](./self-governing-agent.js) +
+> [/docs/for-agents](https://nerviq.net/docs/for-agents) on the site.
+
+## Why an agent should call Nerviq
+
+A LangChain agent operating inside a developer's repo benefits from knowing whether the agent-config files it's reading are coherent across platforms. Without that awareness, the agent can confidently follow instructions in `CLAUDE.md` that contradict instructions in `AGENTS.md` — and produce code that breaks in someone else's tooling.
+
+Wiring Nerviq as a LangChain tool exposes three primitives:
+
+- `nerviq_audit` — score the repo on a specific platform
+- `nerviq_harmony` — measure cross-platform drift
+- `nerviq_stale_references` — surface the headline stale-reference findings
+
+## JavaScript / Node example
+
+```js
+const { audit, harmonyAudit } = require('@nerviq/cli/sdk');
+const { DynamicTool } = require('@langchain/core/tools');
+
+const nerviqAuditTool = new DynamicTool({
+  name: 'nerviq_audit',
+  description:
+    'Audit the AI coding agent configuration of the given repo directory. ' +
+    'Returns score (0-100), passed/failed counts, top stale-reference findings, ' +
+    'and topNextActions. Call this before substantive code changes when the ' +
+    'task touches CLAUDE.md, AGENTS.md, .cursor/rules, .mcp.json, or hooks.',
+  func: async (dir) => {
+    const result = await audit(dir || process.cwd(), 'claude');
+    return JSON.stringify({
+      score: result.score,
+      organicScore: result.organicScore,
+      passed: result.passed,
+      failed: result.failed,
+      staleReferences: result.staleReferences || null,
+      topNextActions: (result.liteSummary && result.liteSummary.topNextActions) || [],
+    }, null, 2);
+  },
+});
+
+const nerviqHarmonyTool = new DynamicTool({
+  name: 'nerviq_harmony',
+  description:
+    'Measure cross-platform configuration drift between AI coding agents in ' +
+    'the given repo. Returns harmonyScore (0-100) plus a list of named ' +
+    'drifts. Only meaningful when 2+ platforms are detected.',
+  func: async (dir) => {
+    const result = await harmonyAudit(dir || process.cwd());
+    return JSON.stringify({
+      harmonyScore: result.harmonyScore,
+      activePlatforms: result.activePlatforms,
+      drifts: (result.drift && result.drift.drifts) || [],
+    }, null, 2);
+  },
+});
+
+// Add to your agent's tool list:
+const tools = [nerviqAuditTool, nerviqHarmonyTool /*, ...your other tools */];
+```
+
+## Python via subprocess
+
+LangChain agents in Python can shell out to the CLI's `--agent-mode --json` surface:
+
+```python
+from langchain_core.tools import tool
+import json
+import subprocess
+
+@tool
+def nerviq_audit(dir: str = ".") -> str:
+    """Audit AI coding agent configuration. Returns score, stale references,
+    top next actions. Call before substantive code changes."""
+    result = subprocess.run(
+        ["npx", "@nerviq/cli", "audit", "--json", "--agent-mode", "--dir", dir],
+        capture_output=True, text=True, timeout=60,
+    )
+    if result.returncode not in (0, 1, 2):
+        return json.dumps({"error": result.stderr})
+    return result.stdout  # Already JSON
+```
+
+## CrewAI / AutoGen / generic orchestrators
+
+Same pattern: any orchestrator that supports tool definitions can wrap the SDK or shell out to `npx @nerviq/cli audit --json`. The JSON envelope is documented at [/docs/for-agents](https://nerviq.net/docs/for-agents) and stable per CTO-01..05 + BUG-01 (machine-output contract).
+
+For CrewAI specifically:
+
+```python
+from crewai.tools import tool
+import subprocess
+
+@tool("Nerviq audit tool")
+def nerviq_audit(dir: str = "."):
+    """Audit cross-platform AI coding agent configuration."""
+    out = subprocess.run(
+        ["npx", "@nerviq/cli", "audit", "--json", "--dir", dir],
+        capture_output=True, text=True, timeout=60,
+    ).stdout
+    return out
+```
+
+## Don't bypass user consent
+
+Per the [/docs/for-agents](https://nerviq.net/docs/for-agents) trust-boundary policy: the agent should NOT silently apply `--apply --auto` on critical fixes that materially modify governance posture (deny rules, MCP permissions, hooks). Surface the plan via the audit/harmony tool, let the user approve, then apply. The CLI gates `--apply` on `--auto` for exactly this reason — single-flag bypass is intentionally blocked.
+
+## When to call which tool
+
+| Situation | Call |
+|---|---|
+| Task start | `nerviq_audit` (always) |
+| Task touches multiple agents' config | `nerviq_harmony` (drift check) |
+| Stale-reference count > 0 in audit result | Surface to user via the audit response, ask whether to proceed |
+| Task complete | `nerviq_audit` again, compare scores, surface delta to user |
+| User accepts a recommendation | (Optionally) record via `npx @nerviq/cli feedback --key <K> --status accepted` so the local learning loop benefits |
+
+## Reference repo
+
+The full self-governing loop reference (5-step pre/harmony/task/post/feedback pattern) lives at [`sdk/examples/self-governing-agent.js`](./self-governing-agent.js). Read that first if you're implementing the orchestration manually rather than letting LangChain/CrewAI drive the loop.
+
+## License
+
+CC0 — copy, modify, integrate freely.