@nerviq/cli 1.9.0 → 1.11.0

package/README.md

@@ -64,18 +64,31 @@ Nerviq scores your AI coding agent setup from 0 to 100, finds what's missing, an
   Next: nerviq setup
 ```
 
-## Quick Start
-
-```bash
-npx @nerviq/cli audit              # Quick scan: score + top 3 actions
-npx @nerviq/cli audit --full       # Full audit with all checks + badge
-npx @nerviq/cli setup              # Generate starter-safe baseline
-npx @nerviq/cli augment            # Improvement plan, no writes
-npx @nerviq/cli governance         # Permission profiles + policy packs
-npx @nerviq/cli benchmark          # Before/after in isolated copy
-```
-
-No install required. Zero dependencies.
+## Quick Start
+
+```bash
+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 --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
+npx @nerviq/cli benchmark          # Baseline vs projected score in isolated copy
+```
+
+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
+npx @nerviq/cli --beginner
+```
 
 ## Get Started by Role
 
@@ -128,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`
 
@@ -153,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`
 
@@ -236,14 +282,14 @@ Levels:
 | `nerviq plan` | Export proposal bundles with previews |
 | `nerviq apply` | Apply proposals with rollback |
 | `nerviq governance` | Permission profiles, hooks, policy packs |
-| `nerviq benchmark` | Before/after in isolated temp copy |
+| `nerviq benchmark` | Baseline vs projected score in isolated temp copy |
 | `nerviq check-health` | Detect regressions between audit snapshots |
 | `nerviq deep-review` | AI-powered config review (opt-in) |
 | `nerviq interactive` | Step-by-step guided wizard |
 | `nerviq watch` | Live monitoring with score delta |
-| `nerviq history` | Score history from snapshots |
-| `nerviq compare` | Compare latest vs previous |
-| `nerviq trend` | Export trend report |
+| `nerviq history` | Audit snapshot history from saved snapshots |
+| `nerviq compare` | Compare latest vs previous audit snapshot |
+| `nerviq trend` | Export audit snapshot trend report |
 | `nerviq feedback` | Record recommendation outcomes |
 | `nerviq anti-patterns` | Detect anti-patterns in current project |
 | `nerviq freshness` | Show verification freshness for all checks |
@@ -273,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 (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
 
@@ -333,9 +392,9 @@ If Nerviq helped you, consider giving it a ⭐ on [GitHub](https://github.com/ne
 
 **Not designed for:** Deeply customized setups with 20+ skills, agent teams, and bespoke MCP integrations. If you've already built advanced agent workflows, you may not need this.
 
-**Strongest at:** Agent configuration, workflow governance, repo policy hygiene, cross-platform alignment, and setup standardization.
-
-**Not a replacement for:** Deep architectural review of business logic, runtime performance profiling, or security penetration testing. Nerviq focuses on how your AI coding agents are configured and governed — not on what your application code does.
+**Strongest at:** AI agent governance, configuration intelligence, workflow policy hygiene, cross-platform alignment, and setup standardization.
+
+**Not a replacement for:** Deep architectural review of business logic, runtime performance profiling, full SAST coverage, secret scanning, or security penetration testing. Nerviq focuses on how your AI coding agents are configured and governed — not on what your application code does.
 
 **Confidence levels:** Every check includes a `confidence` score (0.0–1.0) and a `sourceUrl` linking to primary documentation. Checks marked `heuristic` are pattern-based and may produce false positives on non-standard project structures.
 
@@ -347,16 +406,3 @@ If Nerviq helped you, consider giving it a ⭐ on [GitHub](https://github.com/ne
 | `BETA` | Works but has limited real-world testing. API may change |
 | `EXPERIMENTAL` | Early stage, static rules, results may vary |
 
-## Previously nerviq-cli
-
-Nerviq was previously published as `nerviq-cli`. If you were using it:
-
-```bash
-# Old
-npx nerviq-cli
-
-# New
-npx @nerviq/cli audit
-```
-
-All features are preserved and expanded.