@nerviq/cli 1.27.0 → 1.29.0

package/docs/category-definition-kit.md

@@ -0,0 +1,56 @@
+# Category Definition Kit
+
+Nerviq is the control plane for AI-enabled development.
+
+It helps teams govern how AI coding agents operate across a repo, align multiple tool surfaces, and keep that setup inspectable over time.
+
+## Category definition
+
+Nerviq belongs to:
+
+- AI agent governance
+- AI development control plane
+- configuration intelligence for coding-agent workflows
+
+It is not primarily:
+
+- a full SAST scanner
+- a prompt library
+- a single-vendor IDE helper
+- a generic policy engine with no repo context
+
+## Comparison matrix
+
+| Category | What it does well | Where Nerviq differs |
+|---|---|---|
+| SAST / code scanners | Finds code-level vulnerabilities and risky patterns | Nerviq focuses on the configuration, governance, drift, and operating model around AI agents. |
+| Policy-as-code | Defines enforcement rules and compliance logic | Nerviq is repo-native and AI-workflow-aware, with cross-platform agent surfaces, Harmony, and benchmark/proof flows. |
+| IDE plugins | Improve one editor experience | Nerviq governs the repo across tools instead of binding to one vendor surface only. |
+| Prompt libraries / starter kits | Speed up first setup | Nerviq keeps the setup measurable, aligned, and auditable after day one. |
+| DevEx / internal platform tooling | Standardizes workflows | Nerviq specifically targets AI-enabled development posture and multi-agent drift. |
+
+## Operating model
+
+1. Detect
+   Audit the repo, detect drift, and establish a live baseline.
+2. Align
+   Use Harmony, plan/apply, and policy layers to reduce contradictions safely.
+3. Govern
+   Add permissions, hooks, deny rules, diff gates, and org/team/repo policy inheritance.
+4. Prove
+   Preserve score semantics, snapshots, benchmark evidence, and public proof surfaces.
+5. Scale
+   Move from one repo to fleets, integration contracts, and gated first-tier distribution.
+
+## Adoption playbook
+
+| Stage | Primary user | Nerviq job |
+|---|---|---|
+| Single repo | developer or team lead | Find drift, score the setup, fix the basics, create proof. |
+| Team standard | DevEx / eng lead | Define operating profiles, policy packs, and CI drift gates. |
+| Org control plane | platform / security / governance | Apply policy inheritance, fleet semantics, and integration contracts. |
+| Market standard | external ecosystem | Publish proof, hold first-tier integrations to a gate, and keep the category language consistent. |
+
+## Positioning sentence
+
+Nerviq turns AI coding from a pile of local tool configs into a governed, measurable, cross-platform operating layer.

package/docs/ci-integration.md

@@ -0,0 +1,127 @@
+# CI Integration
+
+NERVIQ integrates with any CI system that can run Node.js. The audit command exits with a non-zero code when the project score falls below the configured threshold, so it plugs directly into your pipeline's pass/fail logic. Below are ready-to-use snippets for the most common providers.
+
+## GitHub Actions
+
+```yaml
+# .github/workflows/nerviq.yml
+name: NERVIQ Audit
+on: [push, pull_request]
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: nerviq/nerviq@v1
+        with:
+          threshold: 60
+```
+
+## GitLab CI
+
+See the full template at [`gitlab-ci-template.yml`](./gitlab-ci-template.yml). Copy it to your project root as `.gitlab-ci.yml` or include it via:
+
+```yaml
+include:
+  - local: 'path/to/gitlab-ci-template.yml'
+```
+
+## Bitbucket Pipelines
+
+See the full template at [`bitbucket-pipe.yml`](./bitbucket-pipe.yml). It includes three pipeline triggers:
+
+| Pipeline | Trigger | Purpose |
+|---|---|---|
+| `default` | Every push | Audit on all branches |
+| `pull-requests` | PR opened/updated | Gate PRs on score threshold |
+| `custom / harmony-audit` | Manual (UI) | Run Harmony multi-config audit |
+
+Quick inline example:
+
+```yaml
+# bitbucket-pipelines.yml
+image: node:20-slim
+
+pipelines:
+  default:
+    - step:
+        name: Nerviq Audit
+        script:
+          - npm install -g @nerviq/cli
+          - nerviq audit --json --threshold ${NERVIQ_THRESHOLD:-60}
+        artifacts:
+          - nerviq-report.json
+  pull-requests:
+    '**':
+      - step:
+          name: Nerviq PR Audit
+          script:
+            - npm install -g @nerviq/cli
+            - nerviq audit --json --threshold ${NERVIQ_THRESHOLD:-60} --out nerviq-report.json
+          artifacts:
+            - nerviq-report.json
+```
+
+Set `NERVIQ_THRESHOLD` in **Repository Settings > Pipelines > Variables** to override the default score of 60.
+
+## Pre-commit
+
+Use the [pre-commit](https://pre-commit.com) framework to run Nerviq automatically on every commit or push. Add to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/nerviq/nerviq
+    rev: v1.8.0
+    hooks:
+      - id: nerviq-audit
+        args: ['60']
+```
+
+See the full guide at [`pre-commit.md`](./pre-commit.md).
+
+## Generic CI (any provider)
+
+If your CI can run `npx`, no global install is needed:
+
+```bash
+npx @nerviq/cli audit --threshold 60
+```
+
+For faster repeat runs, install globally in a setup step:
+
+```bash
+npm install -g @nerviq/cli
+nerviq audit --json --threshold 60
+```
+
+## PR Drift Gating
+
+For pull-request workflows, gate drift against the managed Nerviq baseline instead of only checking the whole repo score:
+
+```bash
+npx @nerviq/cli audit --diff-only --drift-mode ci --threshold 60
+```
+
+This mode:
+
+- limits analysis to changed files plus linked governance/config surfaces
+- compares drift against the managed baseline when one exists
+- keeps score semantics explicit by treating this as a changed-file audit, not a full snapshot score
+
+## Fleet Rollups
+
+For organizations that want one artifact across multiple repos:
+
+```bash
+npx @nerviq/cli org scan ./app ./api ./infra --json --out nerviq-fleet.json
+```
+
+This returns:
+
+- repo-level `live-repo-audit-score` rows
+- an `org-live-average-score` rollup
+- fleet policy coverage
+- score bands
+- shared top evidence across repos

package/docs/claude-code-style.md

@@ -0,0 +1,24 @@
+# Claude Code Style
+
+## Output Style
+- Use camelCase for variables and functions, PascalCase for classes, and UPPER_SNAKE for constants.
+- Prefer `const`; never use `var`.
+- Write JSDoc for public functions and exported helpers when the contract is not obvious.
+- Keep functions small when practical, but prioritize readability over an arbitrary line limit.
+- Use descriptive test names that state the expected behavior.
+
+## Repo Shape
+```text
+bin/                CLI entry point
+src/                Core runtime, platform adapters, HTTP API, MCP transport
+sdk/                Public SDK with TypeScript types
+test/               Custom suite + Jest coverage
+tools/              Build, validation, and maintenance scripts
+docs/               Public and maintainer-facing documentation
+action/             GitHub Action
+vscode-extension/   VS Code surface
+```
+
+## Naming Notes
+- Use kebab-case for CLI commands and doc file names.
+- Follow the existing platform folder layout under `src/` instead of inventing new top-level shapes.

package/docs/claude-maintainer-ops.md

@@ -0,0 +1,19 @@
+# Claude Maintainer Ops
+
+## Working Notes
+- You are working inside the shipped product repo, not the research repo.
+- Keep public contracts stable across CLI JSON, HTTP serve, MCP transport, SDK, Action, and docs.
+- Favor small, test-backed refactors over broad rewrites.
+
+## Environment & Credentials
+- Credentials stay in local environment or local `.env` files and must never be copied into tracked files.
+- If a task needs account-level access, use local configuration only and keep the repo baseline credential-agnostic.
+
+## Security & Runtime
+- Be careful with untrusted paths, shell commands, and generated content.
+- Pin dependency versions and run `npm audit` before publish-oriented work.
+- When operating on large repos, consider token/context limits and prefer cached or incremental paths when they already exist.
+
+## Release Operations
+- Leave releases publish-ready for the human; do not publish automatically.
+- When public docs or messaging change, sync the site and research repos in the same cycle.

package/docs/external-validation.md

@@ -0,0 +1,78 @@
+# Nerviq External Validation Report
+
+**Date:** 2026-04-07
+**CLI Version:** 1.5.3 (2,431 checks)
+**Method:** `nerviq audit --json` on shallow clone of each repo's default branch
+**Repos tested:** 20 real open-source projects (selected for AI agent config presence)
+
+## Results
+
+| # | Repo | Stars | Score | Passed | Failed | CLAUDE.md | AGENTS.md | .cursorrules | Top 3 Missing |
+|---|------|-------|-------|--------|--------|-----------|-----------|-------------|---------------|
+| 1 | [supabase/supabase](https://github.com/supabase/supabase) | 175k⭐ | **44** | 106 | 177 | ❌ | ❌ | ❌ | Secrets protection; CLAUDE.md; Python CI |
+| 2 | [AudiusProject/apps](https://github.com/AudiusProject/apps) | - | **41** | 97 | 192 | ✅ | ❌ | ❌ | Secrets protection; Python CI; Swift tests |
+| 3 | [anthropics/anthropic-cookbook](https://github.com/anthropics/anthropic-cookbook) | - | **41** | 69 | 119 | ✅ | ❌ | ❌ | Secrets protection; PostToolUse hooks; XML constraints |
+| 4 | [medusajs/medusa](https://github.com/medusajs/medusa) | - | **40** | 73 | 129 | ✅ | ❌ | ❌ | Secrets protection; PostToolUse hooks; XML constraints |
+| 5 | [calcom/cal.com](https://github.com/calcom/cal.com) | - | **39** | 71 | 121 | ✅ | ✅ | ❌ | Verification commands; Secrets protection; PostToolUse hooks |
+| 6 | [langchain-ai/langchain](https://github.com/langchain-ai/langchain) | - | **37** | 66 | 119 | ✅ | ✅ | ❌ | Secrets protection; PostToolUse hooks; Custom commands |
+| 7 | [openai/codex](https://github.com/openai/codex) | - | **31** | 61 | 150 | ❌ | ✅ | ❌ | Verification commands; Secrets protection; CLAUDE.md |
+| 8 | [wei/socialify](https://github.com/wei/socialify) | - | **30** | 52 | 132 | ✅ | ✅ | ❌ | Verification commands; Secrets protection; PostToolUse hooks |
+| 9 | [metriport/metriport](https://github.com/metriport/metriport) | - | **30** | 59 | 168 | ❌ | ❌ | ✅ | Verification commands; Secrets protection; CLAUDE.md |
+| 10 | [frantracer/linkurator-frontend](https://github.com/frantracer/linkurator-frontend) | - | **29** | 39 | 139 | ✅ | ❌ | ❌ | Secrets protection; PostToolUse hooks; Custom commands |
+| 11 | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) | 111k⭐ | **26** | 44 | 141 | ❌ | ❌ | ❌ | Verification commands; Secrets protection; CLAUDE.md |
+| 12 | [uhop/node-re2](https://github.com/uhop/node-re2) | - | **25** | 34 | 129 | ✅ | ✅ | ✅ | .gitignore .env; Verification commands; Secrets protection |
+| 13 | [umijs/umi](https://github.com/umijs/umi) | - | **25** | 41 | 150 | ✅ | ❌ | ✅ | Verification commands; Secrets protection; PostToolUse hooks |
+| 14 | [grafana/docker-otel-lgtm](https://github.com/grafana/docker-otel-lgtm) | - | **24** | 44 | 174 | ✅ | ✅ | ❌ | Verification commands; Secrets protection; Python CI |
+| 15 | [vercel/ai](https://github.com/vercel/ai) | - | **24** | 46 | 163 | ✅ | ✅ | ❌ | Verification commands; Secrets protection; Python CI |
+| 16 | [rabbitmq/rabbitmq-server](https://github.com/rabbitmq/rabbitmq-server) | - | **23** | 48 | 156 | ✅ | ✅ | ❌ | Verification commands; Secrets protection; Python CI |
+| 17 | [t3-oss/create-t3-app](https://github.com/t3-oss/create-t3-app) | - | **20** | 33 | 150 | ❌ | ❌ | ❌ | Verification commands; Secrets protection; CLAUDE.md |
+| 18 | [grapeot/devin.cursorrules](https://github.com/grapeot/devin.cursorrules) | - | **13** | 21 | 161 | ❌ | ❌ | ✅ | Verification commands; Secrets protection; CLAUDE.md |
+| 19 | [anthropics/claude-code](https://github.com/anthropics/claude-code) | - | **11** | 21 | 161 | ❌ | ❌ | ❌ | .gitignore .env; Verification commands; Secrets protection |
+| 20 | [elixir-dx/dx](https://github.com/elixir-dx/dx) | - | **10** | 14 | 143 | ❌ | ❌ | ❌ | .gitignore .env; Verification commands; Secrets protection |
+
+## Key Findings
+
+### Score Distribution
+- **Average score: 28/100** — even repos with AI agent configs have significant gaps
+- **Highest: 44** (supabase/supabase) — large monorepo with good hygiene but no AI agent config
+- **Lowest: 10-11** (elixir-dx/dx, anthropics/claude-code) — minimal config files
+
+### Most Common Critical Gaps (appeared in 18+ repos)
+1. **Secrets protection not configured** — 19/20 repos (95%) lack deny rules for .env
+2. **No verification commands** — 17/20 repos (85%) don't tell the agent how to verify its own work
+3. **No PostToolUse hooks** — 16/20 repos (80%) miss automated checks after tool use
+
+### Repos WITH AI Agent Config Still Score Low
+- Repos with `CLAUDE.md` average **30/100** — having instructions is not enough
+- Repos with `CLAUDE.md` + `AGENTS.md` average **28/100** — instructions without hooks/permissions/verification still leave gaps
+- The gap between "has CLAUDE.md" and "well-configured for agents" is where Nerviq adds value
+
+### False Positive Assessment
+- **Secrets protection** on repos without .env: legitimate finding (should still protect against accidental creation)
+- **Python CI checks** on non-Python repos: these fire when `requirements.txt` is detected anywhere — could be a docs dependency. **Candidate for tighter scoping.**
+- **Stack-specific checks**: fire based on file detection, generally accurate
+
+### What Nerviq Got Right
+- Correctly detected CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md presence
+- Correctly identified verification commands (or lack thereof)
+- Correctly detected .gitignore patterns, hook configurations, permission profiles
+- Stack detection worked: Node.js, Python, Go, Rust, Java repos all detected correctly
+- Cross-platform configs detected where present (node-re2 had all three: CLAUDE.md + AGENTS.md + .cursorrules)
+
+### What Could Improve
+- Python CI check fires on repos with incidental Python (e.g., docs tooling) — needs relevance filter
+- Some enterprise/compliance checks are noise for small open-source projects
+- Score of 0-10 for repos with zero AI config is correct but not actionable — these users need onboarding, not a score
+
+## Methodology
+
+1. Selected 20 repos: mix of repos with known AI agent config files + popular open-source projects
+2. Shallow-cloned each repo (`git clone --depth 1`)
+3. Ran `nerviq audit --json` (read-only, no files written)
+4. Extracted score, pass/fail counts, and top 3 recommendations
+5. Manually verified CLAUDE.md/AGENTS.md/.cursorrules presence
+6. Assessed false positive candidates
+
+## Conclusion
+
+Nerviq correctly identifies meaningful gaps in AI coding agent configurations. Even repos that have adopted CLAUDE.md or AGENTS.md typically score 25-40/100, with secrets protection, verification commands, and hooks being the most consistently missing elements. The tool adds the most value in the gap between "has instructions file" and "well-governed agent setup."

package/docs/first-tier-integration-gate.md

@@ -0,0 +1,59 @@
+# First-Tier Integration Gate
+
+Nerviq ships first-tier integrations only when the product is ready to be judged by them.
+
+This gate exists to stop distribution-by-eagerness. A marketplace listing, IDE plugin, or prominent CI surface should amplify a trustworthy product, not expose unfinished semantics.
+
+## Gate dimensions
+
+### 1. Contract stability
+
+- machine-readable contracts exist where relevant
+- score semantics are explicit and documented
+- the integration does not depend on scraping unstable CLI text
+
+### 2. Public proof density
+
+- public before/after proof exists
+- benchmarkable public evidence exists across more than one repo shape
+- the product boundary is stated clearly, including what Nerviq is not
+
+### 3. Operational reliability
+
+- canonical test/build paths are green
+- no known release-blocking CI failures exist
+- setup, docs, and support paths are reproducible for external users
+
+### 4. Ownership and support
+
+- one repo clearly owns the surface
+- release/update flow is defined
+- incoming user issues can be triaged without ambiguity
+
+### 5. Category fit
+
+- the surface reinforces Nerviq as agent governance / AI development control plane
+- the integration does not blur Nerviq into a different category by accident
+- marketing copy and product behavior tell the same story
+
+## Surface posture
+
+| Surface | Posture | What this means |
+|---|---|---|
+| GitHub Action marketplace | Gated | The action can exist before the marketplace listing; broader distribution waits for the full first-tier bar. |
+| JetBrains plugin | Gated | IDE distribution waits until the plugin contract, install path, and support posture reinforce the core category instead of distracting from it. |
+| Shared/team dashboard | Gated | Monetization-facing surfaces stay behind trustworthy fleet semantics and control-plane clarity. |
+| Community seeding | Deferred until story is strong | Community distribution follows public proof plus category clarity, not the other way around. |
+
+## Unfreeze rule
+
+A first-tier surface can move forward only when:
+
+- the relevant gate dimensions are green
+- the owning repo is updated
+- public messaging is synchronized if the surface is public
+- the move strengthens Nerviq's standard story instead of fragmenting it
+
+## Why this matters
+
+Without this gate, new surfaces can create false momentum while weakening trust. With it, each external integration becomes proof that the product is stabilizing into a standard, not just expanding its footprint.

package/docs/getting-started.md

@@ -0,0 +1,119 @@
+# Getting Started with Nerviq
+
+The fastest way to understand Nerviq is not to memorize every command. It is to
+go through one short loop:
+
+1. detect platforms
+2. score the repo
+3. show the biggest gaps
+4. fix the basics
+5. check drift
+6. compare the improvement
+
+Install once:
+
+```bash
+npm i -g @nerviq/cli
+```
+
+For one-off use, `npx @nerviq/cli` works too.
+
+If you want the shortest possible command map inside the terminal, start with:
+
+```bash
+npx @nerviq/cli --beginner
+```
+
+That view only shows `audit`, `setup`, `fix`, `augment`, and `doctor`.
+
+---
+
+## The 6-Step First-Value Path
+
+### 1. Detect active platforms
+
+```bash
+npx @nerviq/cli harmony-audit
+```
+
+Use this first so you know which agent surfaces Nerviq actually found in the
+repo. If the project uses more than one AI coding tool, this is the first drift
+signal that matters.
+
+### 2. Score the current repo
+
+```bash
+npx @nerviq/cli audit --snapshot
+```
+
+This gives you the live baseline and saves the first audit snapshot. That
+snapshot matters because `compare` needs two snapshots later.
+
+### 3. Show the biggest gaps
+
+```bash
+npx @nerviq/cli audit --full
+```
+
+The short score is useful, but the full audit is where you see critical checks,
+top next actions, and weakest categories.
+
+### 4. Fix the basics safely
+
+```bash
+npx @nerviq/cli setup --auto
+npx @nerviq/cli fix --all-critical --auto
+```
+
+This is the fastest way to generate the starter-safe governance layer and then
+close the most obvious critical issues.
+
+### 5. Check drift again
+
+```bash
+npx @nerviq/cli harmony-audit
+```
+
+Re-run Harmony after the baseline changes so you can see whether the active
+platform surfaces are becoming more coherent.
+
+### 6. Show the improvement
+
+```bash
+npx @nerviq/cli audit --snapshot
+npx @nerviq/cli compare
+```
+
+This closes the loop: Nerviq should not only recommend changes, it should show
+that the repo actually improved.
+
+---
+
+## What You Should Have After Step 6
+
+- one clear baseline score
+- two saved audit snapshots
+- a concrete before/after comparison
+- a stronger starter-safe config layer
+- a better sense of whether the repo is drifting across platforms
+
+---
+
+## After First Value
+
+Once the six-step path makes sense, then go deeper:
+
+- `npx @nerviq/cli plan` and `npx @nerviq/cli apply --dry-run` for reviewable rollout
+- `npx @nerviq/cli governance --json` for policy and permission posture
+- `npx @nerviq/cli benchmark` for isolated projected uplift
+- `npx @nerviq/cli dashboard` for snapshot-backed reporting
+
+If you want a public inspectable example, see:
+
+- [DnaFin/nerviq-multi-agent-before-after](https://github.com/DnaFin/nerviq-multi-agent-before-after)
+
+## Need help?
+
+- **Docs:** [nerviq.net/docs/getting-started](https://nerviq.net/docs/getting-started)
+- **GitHub:** [github.com/nerviq/nerviq](https://github.com/nerviq/nerviq)
+- **Discord:** [Join the community](https://discord.gg/nerviq)

package/docs/gitlab-ci-template.yml

@@ -0,0 +1,54 @@
+# NERVIQ GitLab CI Template
+# Ready-to-copy .gitlab-ci.yml for running nerviq audit on every push/MR.
+# Copy this file to your project root as .gitlab-ci.yml (or include it).
+
+# ---------------------------------------------------------------------------
+# Global variables — override in GitLab CI/CD settings or per-job.
+# ---------------------------------------------------------------------------
+variables:
+  NERVIQ_THRESHOLD: "60"           # Minimum audit score (0-100) to pass
+  NODE_ENV: "production"
+
+# ---------------------------------------------------------------------------
+# Stages
+# ---------------------------------------------------------------------------
+stages:
+  - audit
+
+# ---------------------------------------------------------------------------
+# nerviq-audit — runs on every MR and push to main/master
+# ---------------------------------------------------------------------------
+nerviq-audit:
+  stage: audit
+  image: node:20-slim
+  # Run on merge requests AND pushes to the default branches
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH == "master"'
+  before_script:
+    - npm install -g @nerviq/cli
+  script:
+    - echo "Running NERVIQ audit (threshold=${NERVIQ_THRESHOLD})..."
+    - nerviq audit --json --threshold "${NERVIQ_THRESHOLD}" | tee nerviq-report.json
+  artifacts:
+    # Keep the JSON report for 30 days so it can be downloaded from the pipeline UI
+    paths:
+      - nerviq-report.json
+    expire_in: 30 days
+    when: always                   # Save artifact even if the job fails
+
+# ---------------------------------------------------------------------------
+# nerviq-harmony — deeper harmony audit, triggered manually
+# ---------------------------------------------------------------------------
+nerviq-harmony:
+  stage: audit
+  image: node:20-slim
+  rules:
+    - when: manual                 # Only runs when a developer clicks "Play"
+      allow_failure: true          # Manual jobs should not block the pipeline
+  before_script:
+    - npm install -g @nerviq/cli
+  script:
+    - echo "Running NERVIQ harmony audit..."
+    - nerviq harmony-audit