@nerviq/cli 1.27.0 → 1.29.0

package/docs/security-model.md

@@ -0,0 +1,63 @@
+# Security Model & Data Flow
+
+## Data Flow
+
+### What Nerviq Reads
+
+- **Config files**: `CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `.windsurfrules`, `.github/copilot-instructions.md`, `rules/`, and other platform-specific configs.
+- **Project metadata**: `package.json`, `.gitignore`, directory structure (top-level only).
+- **Snapshot input**: existing config state when `--snapshot` is used.
+
+### What Nerviq Writes
+
+- **Config files**: created or updated during `nerviq setup` and `nerviq apply`. Only writes to known config paths for detected platforms.
+- **Snapshot JSON**: `nerviq --snapshot` produces a point-in-time JSON export of your config state. Stored locally.
+- **Dashboard HTML**: `nerviq serve` generates a local HTML dashboard from snapshot data.
+
+### What Nerviq Sends Externally
+
+**Nothing, by default.** Nerviq performs no network requests during normal operation.
+
+Exception: `nerviq deep-review` sends selected config content to an AI provider for analysis. This is opt-in and requires explicit invocation. The user controls which files are included.
+
+## Telemetry
+
+Telemetry is **opt-in only**. Disabled by default.
+
+Enable with: `NERVIQ_TELEMETRY=1`
+
+When enabled, Nerviq collects:
+- Anonymous usage counts (commands run, platforms detected).
+- CLI version.
+
+Nerviq never collects:
+- File contents or snippets.
+- Repository names or paths.
+- Code, configs, or any project-specific data.
+
+## Supply Chain
+
+Nerviq has **zero npm dependencies**. The entire CLI is self-contained.
+
+- Nothing to audit in `node_modules`.
+- No transitive dependency risk.
+- SBOM available at `sbom.cdx.json` (CycloneDX format).
+
+## Attack Surface
+
+| Vector | Status |
+|---|---|
+| File system access | User-level permissions only. Reads/writes config files in the working directory. |
+| Network | No outbound requests by default. No daemon. No background process. |
+| Network listener | Only `nerviq serve` opens a local port. Explicit, user-initiated. |
+| MCP server | Opt-in. Must be explicitly configured in the platform's MCP settings. |
+| Elevated privileges | Never required. Runs as the current user. |
+| Environment variables | Reads `NERVIQ_TELEMETRY`, `NERVIQ_LICENSE_KEY`, and platform-standard vars only. |
+
+## AGPL-3.0 Implications
+
+Nerviq is licensed under AGPL-3.0. This affects distribution and network use but **not** the projects Nerviq configures. Generated config files are not derivative works.
+
+For full details see:
+- [COMMERCIAL.md](../COMMERCIAL.md) -- commercial licensing options.
+- [license-faq.md](license-faq.md) -- common questions about AGPL and Nerviq.

package/docs/shallow-risk.md

@@ -0,0 +1,246 @@
+# Shallow Risk Mode (experimental)
+
+`nerviq audit --shallow-risk` surfaces obvious problems at the
+intersection of your AI agent configuration and your codebase.
+It is opt-in, experimental, and deliberately narrow.
+
+## When to turn this on
+
+**You want this when:** your team runs one or more AI coding agents
+(Claude Code, Cursor, Codex, Copilot, Gemini, Windsurf, Aider,
+OpenCode) against a real repository and you want to catch the
+"silent mismatch" class of problems where your agent's declared
+context diverges from your actual code.
+
+**You don't want this when:** your goal is general-purpose code
+security. For that, pair NERVIQ with a dedicated tool (Semgrep,
+CodeQL, gitleaks, Dependabot). NERVIQ is not a SAST tool and has
+never claimed to be.
+
+## What it catches - by example
+
+### 1. Your agent config points at a file that doesn't exist
+
+```markdown
+<!-- CLAUDE.md -->
+## Security model
+
+See [docs/SECURITY.md](./docs/SECURITY.md) for how we handle
+secrets and compliance.
+```
+
+But `docs/SECURITY.md` doesn't exist. Claude Code follows the link,
+finds nothing, and quietly works with incomplete context. Every
+session.
+
+NERVIQ flags: `agent-config-missing-file: CLAUDE.md references
+docs/SECURITY.md but the file is missing. Agent guidance is
+incomplete.`
+
+### 2. Your agent config contradicts your actual codebase
+
+```markdown
+<!-- CLAUDE.md -->
+This is a Go microservice. Run `go test ./...` before committing.
+```
+
+The repo is actually Python. There is no `go.mod`. Claude
+recommends Go tooling forever.
+
+NERVIQ flags: `agent-config-stack-contradiction: CLAUDE.md declares
+primary stack as "Go" but the repo contains Python signals
+(pyproject.toml, 47 .py files) and no Go signals.`
+
+### 3. Two agents get contradictory instructions
+
+- `.cursor/rules/main.mdc`: "Use TypeScript strict mode."
+- `CLAUDE.md`: "This is a pure JavaScript project."
+
+Each agent does something slightly different. Teams hit drift
+they can't explain.
+
+NERVIQ flags: `agent-config-cross-platform-drift: CLAUDE.md and
+.cursor/rules/main.mdc disagree on primary language.`
+
+### 4. Your MCP server has no permission boundary
+
+```json
+// .claude/settings.json
+{
+  "mcpServers": {
+    "shell": {
+      "command": "node",
+      "args": ["./scripts/shell-mcp.js"],
+      "permissions": []
+    }
+  }
+}
+```
+
+`permissions: []` is empty. The MCP server can run anything.
+
+NERVIQ flags: `mcp-server-no-allowlist: MCP server "shell" in
+.claude/settings.json has empty permissions - full access, no
+allowlist. Review and add an allow-list.`
+
+### 5. Your hook script is referenced but missing
+
+```json
+// .claude/settings.json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "hooks": [{
+        "type": "command",
+        "command": ".claude/hooks/pre-commit.sh"
+      }]
+    }]
+  }
+}
+```
+
+The file `.claude/hooks/pre-commit.sh` doesn't exist. Every pre-tool
+hook silently fails and Claude proceeds anyway.
+
+NERVIQ flags: `hook-script-missing: .claude/settings.json declares a
+PreToolUse hook at .claude/hooks/pre-commit.sh, but the file is
+missing. Hook is silently skipped.`
+
+### 6. A secret ended up in an agent-config file
+
+```markdown
+<!-- CLAUDE.md -->
+## Testing
+
+For local smoke tests, use this Stripe test key:
+sk_live_<redacted-example>
+```
+
+That key made it into Git history inside `CLAUDE.md` specifically.
+NERVIQ catches secrets inside agent-config files because that's
+where we uniquely see them - not as a general secret scanner,
+which you should already be running.
+
+NERVIQ flags: `agent-config-secret-literal: CLAUDE.md contains a
+Stripe-live-key shape on line 42. Rotate the key and remove from
+history.`
+
+### 7. Your config uses keys the platform removed
+
+```yaml
+# .aider.conf.yml
+auto-commit: true
+weak-model: gpt-3.5-turbo
+```
+
+Aider 0.60 removed `auto-commit`. It is silently ignored. You
+believe your repo has auto-commit, but it does not.
+
+NERVIQ flags: `agent-config-deprecated-keys: .aider.conf.yml uses
+"auto-commit" (removed in Aider 0.60+). Config key is silently
+ignored.`
+
+### 8. Auto-approval on a destructive pattern
+
+```json
+// .claude/settings.json
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test *)",
+      "Bash(rm -rf *)"
+    ]
+  }
+}
+```
+
+`rm -rf *` is pre-approved. An agent loop deciding to "clean up"
+can now do so without asking.
+
+NERVIQ flags: `agent-config-dangerous-autoapprove: .claude/settings.json
+allow-list contains "Bash(rm -rf *)". This pattern is pre-approved
+and cannot be revoked per-invocation.`
+
+## What this mode explicitly does not catch
+
+For each of these, use the right tool. NERVIQ deliberately does
+not try to be "everything."
+
+| You need this | Use this, not NERVIQ |
+|---|---|
+| Find SQL injection, XSS, SSRF, open redirects in source | Semgrep, CodeQL |
+| Language-level code smells, style, complexity | ESLint, Bandit, rubocop, etc. |
+| Full secret scanning across repo + git history | gitleaks, truffleHog |
+| Dependency CVEs | Dependabot, Snyk, OSV |
+| Compliance (SOC 2 / PCI / HIPAA / ISO 27001) | a compliance platform |
+| Runtime exploitation / DAST | a DAST tool |
+
+NERVIQ's job is the agent-configuration <-> codebase bridge. That's
+what we uniquely see. The 8 patterns above reflect the real trust
+breaks we've observed in the 2026-04-08 UAT evaluations and across
+the 61-repo PP-08 corpus.
+
+## How to run it
+
+```bash
+# Full audit + shallow risk (recommended)
+npx @nerviq/cli audit --shallow-risk
+
+# Shallow risk only (fast precommit hook)
+npx @nerviq/cli audit --shallow-risk-only
+
+# Skip it entirely (default; no flag needed)
+npx @nerviq/cli audit
+
+# Emergency disable (overrides any flag):
+NERVIQ_SHALLOW_RISK=off npx @nerviq/cli audit --shallow-risk
+```
+
+### In CI, as a PR comment
+
+```yaml
+- run: npx @nerviq/cli audit --shallow-risk --format=markdown --out audit.md
+- uses: marocchino/sticky-pull-request-comment@v2
+  with:
+    path: audit.md
+```
+
+Shallow-risk findings are rendered in their own `### Shallow Risk`
+section with the experimental banner - clearly distinguished from
+the governance audit output so reviewers know what they're looking
+at.
+
+## Status: Experimental
+
+The 2026-04-14 initial release ships with 8 patterns. We are
+deliberately holding 2 of the 10 reserved slots empty until 30
+days of real user telemetry tells us which patterns users most
+wanted that we didn't anticipate.
+
+The feature graduates:
+- **Experimental -> Beta**: after 30 days of usage telemetry with
+  zero critical corpus-level false positives reported, and at
+  least one external user reporting that a pattern caught a real
+  issue.
+- **Beta -> GA**: after 50+ weekly active audits across 5 or more
+  distinct repos by real users.
+
+## Feedback
+
+Run `nerviq feedback` to send us a short note if a shallow-risk
+finding was wrong (false positive) or if we missed something
+obvious we should catch. We read every one. The initial pattern
+set was picked from real UAT evaluations; the reserved slots are
+explicitly waiting for real-user signal to fill.
+
+## Why "shallow"?
+
+Because the patterns are deliberately simple - file existence,
+key presence, regex match against agent-config files. No
+dataflow, no control-flow, no runtime. If the patterns were
+deep, we'd be Semgrep or CodeQL, and we're not.
+
+NERVIQ is sharp on the agent-governance lane. Shallow-risk is
+the opt-in extension that catches the obvious mismatches at the
+edge of that lane - the places users have told us trust breaks
+first.

package/docs/versioning-policy.md

@@ -0,0 +1,63 @@
+# Versioning & Support Policy
+
+## Semver
+
+Nerviq follows [Semantic Versioning](https://semver.org/) strictly.
+
+- **Major** (X.0.0): Breaking changes to CLI interface, config format, or behavior.
+- **Minor** (0.X.0): New features, new platform support, new checks. Backward-compatible.
+- **Patch** (0.0.X): Bug fixes, documentation corrections, minor improvements.
+
+Pre-release versions use `-beta.N` or `-rc.N` suffixes and are not considered stable.
+
+## Breaking Changes
+
+Breaking changes are never introduced without notice.
+
+Process:
+1. The feature or behavior is marked `deprecated: true` in at least one minor release before removal.
+2. Deprecation is announced in `CHANGELOG.md` with migration instructions.
+3. The deprecated item is removed in the next major version.
+
+Examples of breaking changes:
+- Removing or renaming a CLI command or flag.
+- Changing config file output format in a way that breaks existing workflows.
+- Dropping support for a Node.js version.
+
+## Node.js Support
+
+| Version | Status |
+|---|---|
+| Node 18 (LTS) | Supported, tested in CI |
+| Node 20 (LTS) | Supported, tested in CI |
+| Node 22+ | Best-effort, not yet in CI matrix |
+| Node 16 and below | Not supported |
+
+Nerviq targets the two most recent LTS releases. When a Node.js LTS version reaches end-of-life, Nerviq drops support in the next major release.
+
+## Platform Support
+
+Nerviq actively maintains support for 8 AI coding platforms:
+
+| Platform | Config target |
+|---|---|
+| Claude Code | `CLAUDE.md`, `.claude/` |
+| Cursor | `.cursorrules`, `.cursor/rules/` |
+| Windsurf | `.windsurfrules` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Cline | `.clinerules` |
+| Aider | `.aider.conf.yml` |
+| Codex | `codex.md`, `agents.md` |
+| Amazon Q | `.qdeveloper/` |
+
+New platforms are added as minor version bumps. Existing platform support is never removed in a minor release.
+
+## Support Channels
+
+| Channel | Use case |
+|---|---|
+| [GitHub Issues](https://github.com/nicepkg/nerviq/issues) | Bug reports, feature requests, platform support questions |
+| Discord | Community discussion, tips, integrations |
+| business@nerviq.net | Enterprise licensing, SLA inquiries, bulk deployment |
+
+Response time targets: GitHub Issues triaged within 72 hours. Enterprise inquiries within 1 business day.

package/docs/why-nerviq.md

@@ -0,0 +1,82 @@
+# Why Nerviq
+
+> Vendors govern their own agent. Nerviq governs ALL your agents.
+
+Nerviq is AI agent governance and configuration intelligence for repositories using modern coding agents. It does **not** replace SAST, secret scanning, or deep application code review.
+
+---
+
+## The Problem
+
+Your team uses Claude Code, Cursor, and Copilot in the same repo. Each has its own config format, its own rules syntax, and its own way of handling permissions. Without governance:
+
+- **Config drift** — CLAUDE.md says "never modify tests", .cursorrules says nothing about it
+- **Security gaps** — Copilot has deny rules, but your Gemini setup doesn't
+- **Invisible standards** — New team members don't know which agent is configured for what
+- **No audit trail** — Nobody knows when configs changed or why scores dropped
+
+## Why Not Just Manage It Manually?
+
+| | Manual | Nerviq |
+|---|---|---|
+| Time to audit 8 platforms | Hours | 30 seconds |
+| Drift detection | None | Automatic |
+| Cross-platform sync | Copy-paste | `nerviq harmony-sync` |
+| Rollback on mistake | Hope you have git stash | `nerviq rollback` |
+| CI enforcement | Custom scripts | One-line GitHub Action |
+| Score trending | Spreadsheet | `nerviq history` |
+
+## Why Not Use Platform-Native Tools?
+
+GitHub governs Copilot. Anthropic governs Claude. Google governs Gemini.
+
+**None of them will govern their competitor's agent.**
+
+Nerviq is the only tool that sits above all 8 platforms and provides:
+- Unified scoring (0-100) across every platform
+- Cross-platform drift detection (Harmony)
+- Multi-agent synergy analysis (Synergy — Experimental)
+- One config standard, 8 platform outputs
+
+## Why Not Semgrep / Snyk / Security Scanners?
+
+Different category entirely. Semgrep scans **code** for vulnerabilities. Nerviq scans **agent configurations** for governance gaps.
+
+Semgrep won't tell you that your CLAUDE.md is missing verification commands, or that your .cursorrules conflict with your AGENTS.md, or that your Copilot setup lacks deny rules.
+
+## Three Use Cases
+
+### Solo Developer
+```bash
+npx @nerviq/cli audit        # See your score
+npx @nerviq/cli augment      # Get improvement plan
+npx @nerviq/cli benchmark    # Measure the difference
+```
+**Result:** Better-configured AI agents → better code output → fewer mistakes.
+
+### Team Lead / DevEx
+```bash
+npx @nerviq/cli governance   # Set team policies
+npx @nerviq/cli audit --json # Pipe to CI
+```
+**Result:** Consistent agent behavior across the team. No more "works on my machine" for AI configs.
+
+### Enterprise / Platform Engineering
+```bash
+npx @nerviq/cli harmony-audit      # Cross-platform health
+npx @nerviq/cli harmony-drift      # Detect drift
+npx @nerviq/cli harmony-governance # Unified policies
+```
+**Result:** Governance, compliance, and audit trails for AI agent operations at scale.
+
+## The Numbers
+
+- **2,441 checks** across 8 platforms (~300 unique governance rules adapted per platform) and 10 languages
+- **Every check** has a source URL, confidence score, and freshness date
+- **90-day freshness cycle** — stale checks are re-verified or removed
+- **Zero dependencies** — nothing to audit in the supply chain
+- **Runs locally** — your code never leaves your machine
+
+---
+
+[Get started](https://github.com/nerviq/nerviq) | [Documentation](https://nerviq.net) | [Discord](https://discord.gg/nerviq)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.27.0",
+  "version": "1.29.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",
   "bin": {
@@ -11,7 +11,12 @@
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "docs",
+    "contracts",
+    "sdk/README.md",
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "start": "node bin/cli.js",

package/sdk/README.md

@@ -0,0 +1,190 @@
+# @nerviq/sdk
+
+Programmatic SDK for Nerviq audit, Harmony, catalog access, and experimental Synergy workflows.
+
+## Install
+
+```bash
+npm install @nerviq/sdk
+```
+
+## Stability
+
+- Stable for production workflows: `audit`, `harmonyAudit`, `detectPlatforms`, `getCatalog`
+- Experimental advisory surfaces: `synergyReport`, `routeTask`
+- Local-first: the SDK reads your repo directly and does not require a background service
+
+## Quick Start
+
+```js
+const { audit, harmonyAudit, detectPlatforms } = require('@nerviq/sdk');
+
+async function main() {
+  const repoDir = process.cwd();
+
+  try {
+    const platforms = detectPlatforms(repoDir);
+    console.log(`Platforms: ${platforms.join(', ') || 'none detected'}`);
+
+    const auditResult = await audit(repoDir, 'claude');
+    console.log(`Claude score: ${auditResult.score}/100`);
+
+    const harmony = await harmonyAudit(repoDir);
+    console.log(`Harmony score: ${harmony.harmonyScore}/100`);
+  } catch (error) {
+    console.error(formatSdkError(error));
+    process.exitCode = 1;
+  }
+}
+
+function formatSdkError(error) {
+  if (error instanceof Error) {
+    return `Nerviq SDK error: ${error.message}`;
+  }
+  return 'Nerviq SDK error: unknown failure';
+}
+
+main();
+```
+
+## Common Patterns
+
+### 1. CI gate for one platform
+
+```js
+const { audit } = require('@nerviq/sdk');
+
+async function runGate(dir) {
+  const result = await audit(dir, 'codex');
+
+  if (result.score < 70) {
+    const reasons = result.topNextActions
+      .slice(0, 3)
+      .map((item) => `- ${item.name}`)
+      .join('\n');
+
+    throw new Error(`Nerviq gate failed (${result.score}/100)\n${reasons}`);
+  }
+
+  return result;
+}
+```
+
+### 2. Cross-platform reporting
+
+```js
+const { harmonyAudit } = require('@nerviq/sdk');
+
+async function buildAlignmentDigest(dir) {
+  const harmony = await harmonyAudit(dir);
+
+  return {
+    harmonyScore: harmony.harmonyScore,
+    activePlatforms: harmony.activePlatforms,
+    topRecommendation: harmony.recommendations[0] || null,
+    driftCount: harmony.drift?.summary?.total || 0,
+  };
+}
+```
+
+### 3. Catalog-backed search or UI helpers
+
+```js
+const { getCatalog } = require('@nerviq/sdk');
+
+const catalog = getCatalog();
+const criticalSecurityChecks = catalog.filter(
+  (check) => check.category === 'security' && check.impact === 'critical'
+);
+
+console.log(`Critical security checks: ${criticalSecurityChecks.length}`);
+```
+
+## Error Handling
+
+The SDK throws regular `Error` instances with operator-readable messages. The most common cases are:
+
+| Situation | Example message |
+| --- | --- |
+| `dir` missing or not a string | `dir is required and must be a string. Pass a valid directory path.` |
+| Directory does not exist | `Directory not found: /abs/path. Pass an existing directory path.` |
+| Unsupported platform | `Unsupported platform 'foo'. Use one of: claude, codex, ...` |
+| Empty routing description | `description is required and must be a non-empty string.` |
+
+Recommended pattern:
+
+```js
+try {
+  const result = await audit('/repo', 'claude');
+  console.log(result.score);
+} catch (error) {
+  if (error instanceof Error) {
+    console.error(error.message);
+  } else {
+    console.error('Unknown SDK failure');
+  }
+}
+```
+
+## TypeScript
+
+The SDK ships with `index.d.ts`, so you can import both functions and result interfaces directly.
+
+```ts
+import {
+  audit,
+  harmonyAudit,
+  routeTask,
+  type AuditResult,
+  type HarmonyResult,
+  type RoutingResult,
+} from "@nerviq/sdk";
+
+async function inspectRepo(dir: string): Promise<{
+  audit: AuditResult;
+  harmony: HarmonyResult;
+  routing: RoutingResult;
+}> {
+  const auditResult = await audit(dir, "claude");
+  const harmony = await harmonyAudit(dir);
+  const routing = routeTask(
+    "Review trust boundaries and MCP posture",
+    ["claude", "codex", "cursor"]
+  );
+
+  return {
+    audit: auditResult,
+    harmony,
+    routing,
+  };
+}
+```
+
+## API Surface
+
+```js
+const {
+  audit,
+  harmonyAudit,
+  synergyReport,
+  detectPlatforms,
+  getCatalog,
+  routeTask,
+} = require('@nerviq/sdk');
+```
+
+| Export | Stability | What it does |
+| --- | --- | --- |
+| `audit(dir, platform?)` | Stable | Run a single-platform audit and return score, findings, and next actions. |
+| `harmonyAudit(dir)` | Stable | Run cross-platform alignment and drift analysis. |
+| `detectPlatforms(dir)` | Stable | Detect which supported agent platforms are active in the repo. |
+| `getCatalog()` | Stable | Return the merged Nerviq check catalog. |
+| `synergyReport(dir)` | Experimental | Return research-phase multi-platform lift analysis and rendered report text. |
+| `routeTask(description, platforms?)` | Experimental | Suggest a platform mix for a task description using the current routing model. |
+
+## Notes
+
+- `audit()` defaults to `claude` when no platform is supplied.
+- `audit()` and `harmonyAudit()` are async because they inspect the repository on disk.
+- `getCatalog()` and `routeTask()` are synchronous helpers.
+- If you need a local HTTP surface instead of direct imports, use `nerviq serve` and pull the live contract from `/api/openapi.json`.

package/src/codex/setup.js

@@ -6,6 +6,7 @@ const { STACKS } = require('../techniques');
 const { writeActivityArtifact, writeRollbackArtifact } = require('../activity');
 const { CodexProjectContext } = require('./context');
 const { recommendCodexMcpPacks, packsToToml } = require('./mcp-packs');
+const { icon } = require('../output-icons');
 
 function detectScripts(ctx) {
   const pkg = ctx.jsonFile('package.json');
@@ -521,14 +522,14 @@ async function setupCodex(options) {
     const fullPath = path.join(options.dir, file.path);
     if (fs.existsSync(fullPath)) {
       preservedFiles.push(file.path);
-      log(`  \x1b[2m⏭️  Skipped ${file.path} (already exists — your version is kept)\x1b[0m`);
+      log(`  \x1b[2m${icon('skip')} Skipped ${file.path} (already exists - your version is kept)\x1b[0m`);
       continue;
     }
 
     fs.mkdirSync(path.dirname(fullPath), { recursive: true });
     fs.writeFileSync(fullPath, file.content, 'utf8');
     writtenFiles.push(file.path);
-    log(`  \x1b[32m✅\x1b[0m Created ${file.path}`);
+    log(`  \x1b[32m${icon('ok')}\x1b[0m Created ${file.path}`);
   }
 
   const skippedSet = new Set(preservedFiles);