@nerviq/cli 1.10.0 → 1.11.0

package/README.md

@@ -70,7 +70,10 @@ Nerviq scores your AI coding agent setup from 0 to 100, finds what's missing, an
 npx @nerviq/cli --beginner         # Show only the 5 starter commands
 npx @nerviq/cli audit              # Quick scan: score + top 3 actions
 npx @nerviq/cli audit --full       # Full audit with all checks + badge
-npx @nerviq/cli audit --workspace packages/*  # Monorepo: root governance + workspace average/package scores
+npx @nerviq/cli audit --snapshot --tag "pre-refactor"  # Save a named snapshot for history/compare/trend
+npx @nerviq/cli compare            # Detailed per-check diff between latest 2 audit snapshots
+npx @nerviq/cli audit --webhook https://hooks.slack.com/services/...  # Push audit results to Slack/Discord/generic HTTP
+npx @nerviq/cli audit --workspace packages/*  # Monorepo: root governance + stack-specific workspace profiles
 npx @nerviq/cli setup              # Generate starter-safe baseline
 npx @nerviq/cli augment            # Improvement plan, no writes
 npx @nerviq/cli governance         # Permission profiles + policy packs
@@ -79,6 +82,8 @@ npx @nerviq/cli benchmark          # Baseline vs projected score in isolated cop
 
 No install required. Zero dependencies.
 
+Text-mode CLI output explains terms like `MCP`, `hooks`, `deny rules`, and `governance` inline when they appear, so a first audit is easier to read.
+
 If you want the shortest possible command list inside the terminal, start with:
 
 ```bash
@@ -136,22 +141,36 @@ npx @nerviq/cli synergy-report     # Multi-agent synergy analysis
 
 Synergy evaluates compound audit results, discovers compensation patterns (where one platform covers another's gaps), and ranks recommendations by cross-platform impact.
 
-## SDK — `@nerviq/sdk` `BETA`
-
-Programmatic access to all Nerviq capabilities:
-
-```js
-const { audit, harmonyAudit, synergyReport, detectPlatforms } = require('@nerviq/sdk');
-
-const result = await audit('.', 'claude');
-console.log(`Score: ${result.score}/100`);
-
-const platforms = detectPlatforms('.');
-console.log(`Active platforms: ${platforms.join(', ')}`);
-
-const harmony = await harmonyAudit('.');
-console.log(`Harmony score: ${harmony.harmonyScore}/100`);
-```
+## SDK — `@nerviq/sdk` `BETA`
+
+Programmatic access to all Nerviq capabilities:
+
+```js
+const { audit, harmonyAudit, detectPlatforms } = require('@nerviq/sdk');
+
+async function main() {
+  try {
+    const result = await audit('.', 'claude');
+    console.log(`Score: ${result.score}/100`);
+
+    const platforms = detectPlatforms('.');
+    console.log(`Active platforms: ${platforms.join(', ') || 'none detected'}`);
+
+    const harmony = await harmonyAudit('.');
+    console.log(`Harmony score: ${harmony.harmonyScore}/100`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : 'Unknown SDK error');
+    process.exitCode = 1;
+  }
+}
+
+main();
+```
+
+Stable SDK surfaces: `audit`, `harmonyAudit`, `detectPlatforms`, `getCatalog`  
+Experimental SDK surfaces: `synergyReport`, `routeTask`
+
+See [sdk/README.md](sdk/README.md) for full JavaScript examples, error handling guidance, and TypeScript usage.
 
 ## MCP Server — `nerviq serve`
 
@@ -161,11 +180,30 @@ Nerviq ships with a built-in MCP-compatible HTTP server for integration with AI
 npx @nerviq/cli serve --port 3000
 ```
 
-Endpoints:
-- `GET /api/health` — Server health check
-- `GET /api/catalog` — Full check catalog
-- `POST /api/audit` — Run audit on a directory
-- `GET /api/harmony` — Cross-platform harmony data
+Endpoints:
+- `GET /api/openapi.json` — Live OpenAPI 3.1 contract for this `serve` instance
+- `GET /api/health` — Server health check
+- `GET /api/catalog` — Full check catalog
+- `GET /api/audit` — Run audit on a directory and platform via query params
+- `GET /api/harmony` — Cross-platform harmony data
+
+All successful operational responses are wrapped in a JSON envelope:
+
+```json
+{
+  "data": {},
+  "meta": {
+    "version": "1.11.0",
+    "timestamp": "2026-04-09T12:00:00.000Z"
+  }
+}
+```
+
+Pull the contract directly into Swagger UI, Postman, or internal tooling:
+
+```bash
+curl http://127.0.0.1:3000/api/openapi.json > nerviq-openapi.json
+```
 
 ## Plugin System — `nerviq.config.js`
 
@@ -281,16 +319,29 @@ Levels:
 | `--verbose` | Full audit + medium-priority recommendations |
 | `--threshold N` | Exit 1 if score < N (for CI) |
 | `--json` | Machine-readable JSON output |
-| `--out FILE` | Write output to file |
-| `--snapshot` | Save audit snapshot for trending |
-| `--dry-run` | Preview changes without writing files |
-| `--config-only` | Only write config files, never source code |
-| `--auto` | Apply without prompts |
+| `--out FILE` | Write output to file |
+| `--webhook URL` | POST audit results to Slack, Discord, or a generic JSON endpoint |
+| `--webhook-header NAME:VALUE` | Add a custom webhook header; repeat the flag for multiple headers |
+| `--webhook-retries N` | Retry transient webhook failures (`429`, `5xx`, timeouts) up to `N` extra times |
+| `--snapshot` | Save audit snapshot for trending |
+| `--dry-run` | Preview changes without writing files |
+| `--config-only` | Only write config files, never source code |
+| `--auto` | Apply without prompts |
 | `--only A,B` | Limit apply to selected proposal IDs |
 | `--format sarif` | SARIF output for code scanning |
 | `--platform NAME` | Target platform (claude, codex, gemini, copilot, cursor, windsurf, aider, opencode) |
-| `--workspace GLOB` | Audit workspaces separately as package-level live audits (e.g. packages/*) |
-| `--external PATH` | Benchmark an external repo |
+| `--workspace GLOB` | Audit workspaces separately as package-level live audits with summary-only JSON rows (e.g. packages/*) |
+| `--external PATH` | Benchmark an external repo |
+
+Webhook delivery automatically retries transient failures twice by default. For authenticated internal endpoints, you can add custom headers such as:
+
+```bash
+npx @nerviq/cli audit \
+  --webhook https://ops.example.com/nerviq/audit \
+  --webhook-header "Authorization: Bearer $NERVIQ_WEBHOOK_TOKEN" \
+  --webhook-header "X-Nerviq-Environment: production" \
+  --webhook-retries 4
+```
 
 ## Backed by Research