@nerviq/cli 1.27.0 → 1.27.1

package/docs/methodology.md

@@ -0,0 +1,236 @@
+# How Nerviq Verifies 2,441 Checks (~300 Governance Rules × 8 Platforms)
+
+## Overview
+
+Nerviq is a rule-based audit engine for AI coding agent configurations with evidence tracking. Every check we ship is traceable to primary documentation or verified experiment results. Checks are structured assertions backed by official vendor docs, runtime experiments, and continuous feedback calibration — but they are rules, not AI-generated insights.
+
+This document explains the full lifecycle: how checks are created, verified, rated, maintained, and retired.
+
+## Check Anatomy
+
+Each check in the Nerviq catalog is a structured object with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Unique identifier following the `{CATEGORY}-{SEQUENCE}` pattern (e.g., `CU-A01`, `SC-B14`, `AU-C03`) |
+| `name` | `string` | Human-readable description of what the check detects |
+| `check(ctx)` | `function` | Detection function that inspects the `ProjectContext` and returns `true`, `false`, or `null` |
+| `impact` | `enum` | Severity level: `critical`, `high`, or `medium` |
+| `confidence` | `number` | Score from 0.0 to 1.0 reflecting certainty that this check is accurate and current |
+| `sourceUrl` | `string` | URL pointing to the official documentation backing this check |
+| `category` | `string` | One of 96 categories (e.g., `memory`, `security`, `quality`, `automation`, `hooks`) |
+| `fix` | `string` | Actionable remediation guidance shown when the check fails |
+
+### Return values
+
+The `check(ctx)` function receives a `ProjectContext` — a normalized view of the project's files, configuration, and environment. It returns:
+
+- `true` — the practice is present (pass)
+- `false` — the practice is missing (finding)
+- `null` — the check is not applicable to this project (e.g., a Node.js check in a Python project)
+
+Checks are keyed by a stable string identifier (e.g., `claudeMd`, `permissionDeny`, `codexAgentsMd`) that remains consistent across versions. This enables feedback tracking and trend analysis over time.
+
+## Verification Levels
+
+Every check is assigned a confidence score that maps to one of three verification levels:
+
+### HIGH confidence (0.7–1.0)
+
+The check is backed by official platform documentation **and** has been validated through a runtime experiment. A maintainer executed the check logic against real project fixtures and observed the expected outcome.
+
+| Condition | Score |
+|-----------|-------|
+| Runtime-verified with passing experiment and test coverage | **0.9** |
+| Community-confirmed (positive feedback rate > 80%) | **0.9** |
+| Documented in official vendor docs, not yet runtime-tested | **0.7** |
+
+This tier covers approximately 65% of the catalog. These checks appear as primary recommendations in audit output.
+
+### MEDIUM confidence (0.4–0.69)
+
+The check is backed by official documentation or established community best practice, but has not been independently verified through a runtime experiment. Common reasons: the platform feature is too new for full experiment coverage, or the check logic relies on behavioral observations that are difficult to isolate in a fixture.
+
+| Condition | Score |
+|-----------|-------|
+| Disputed (negative feedback rate > 50%) | **0.5** |
+| Documented but not yet experiment-verified | **0.5** |
+
+These checks appear in audit output but are ranked below HIGH-confidence checks at the same impact level.
+
+### HEURISTIC (0.0–0.39)
+
+Pattern-based detection that may produce false positives. These checks infer configuration quality from indirect signals (file size, naming patterns, structural heuristics) rather than direct feature detection.
+
+| Condition | Score |
+|-----------|-------|
+| Stale — not re-verified within 90 days | **0.3** |
+| Pattern-based with no direct documentation backing | **0.2** |
+
+Heuristic checks are never promoted to "recommended" status. They appear in verbose audit output and are clearly labeled.
+
+## The 5-Layer Evidence Chain
+
+Every check passes through five layers before reaching users:
+
+### Layer 1 — Official Source
+
+Each check starts with an official documentation reference. The `sourceUrl` field links directly to the platform vendor's docs (Anthropic, OpenAI, Google, GitHub, Cursor, Windsurf, Aider, OpenCode). No check exists without a traceable origin.
+
+### Layer 2 — Research Memo
+
+Findings from official sources are documented in structured research memos following the Anthropic-recommended research methodology: explore from multiple angles, form competing hypotheses, triangulate across independent sources, extract quotes before analyzing, identify gaps and contradictions, integrate with confidence levels, and self-critique.
+
+**448+ research documents** feed the current check catalog.
+
+### Layer 3 — Runtime Experiment
+
+Claims are tested in real project environments. Each experiment runs actual check logic against controlled fixtures — real directory structures, real configuration files, real tool outputs. Nothing is marked as verified without executing it and observing the output.
+
+**332+ experiments across 8 platforms** with real runtime evidence.
+
+### Layer 4 — Check Implementation
+
+The verified finding becomes a `check(ctx)` function operating on `ProjectContext`. The function is deterministic: same project state produces the same result.
+
+### Layer 5 — Test Coverage
+
+Every check is covered by matrix tests that verify correct behavior across project shapes. Golden matrices lock expected pass/fail outcomes so regressions are caught immediately. Platform-specific matrices ensure cross-platform correctness.
+
+## Freshness Cycle
+
+Stale checks are worse than missing checks — they create false confidence. Nerviq enforces a 90-day verification window.
+
+### 90-Day Rule
+
+Every check has a `lastVerified` date. Any check not re-verified within 90 days is marked stale. Stale checks:
+
+- Have their confidence score reduced to **0.3** (HEURISTIC tier)
+- Are flagged in audit output with a staleness warning
+- Are blocked from appearing as top recommendations until re-verified
+
+### Daily Changelog Watch
+
+A CI cron job monitors platform changelogs and release notes. When a platform ships a breaking change or deprecation, affected checks are flagged for immediate review — they do not wait for the 90-day window.
+
+### Staleness Blocking
+
+Stale checks cannot graduate to "recommended" status. They remain in the catalog for completeness but are deprioritized in all ranking algorithms until a maintainer re-verifies them against current platform behavior.
+
+## False Positive Management
+
+False positives erode trust. Nerviq has a structured feedback loop to catch and suppress them.
+
+### Reporting
+
+Users report whether a finding was helpful or not via the CLI:
+
+```
+npx nerviq feedback --key <checkKey> --status rejected --effect negative
+```
+
+Feedback is stored locally in `.nerviq/outcomes/` and aggregated per check key.
+
+### Confidence Calibration
+
+Feedback data flows directly into confidence scoring:
+
+- Checks with **>80% positive feedback** receive a confidence boost (up to +0.1)
+- Checks with **>50% negative feedback** receive a confidence reduction (down to 0.5)
+- Checks exceeding **30% "not helpful" rate** are deprioritized in recommendations
+
+### Feedback-Aware Ranking
+
+The `getRecommendationAdjustment` function computes a bounded adjustment (plus or minus 8 points) based on:
+
+- Accepted vs. rejected outcomes
+- Positive vs. negative effect ratings
+- Average score delta from before/after measurements
+
+This adjustment feeds into `topNextActions` and `quickWins` ranking, so recommendations improve with use.
+
+## Platform Coverage
+
+Nerviq covers 8 AI coding agent platforms:
+
+| Platform | Config Detection | Check Count |
+|----------|-----------------|-------------|
+| Claude Code | `CLAUDE.md`, `.claude/` | ~500 |
+| GitHub Copilot | `.github/copilot-instructions.md` | ~350 |
+| Cursor | `.cursor/rules/`, `.cursorrules` | ~350 |
+| Windsurf | `.windsurfrules`, `.windsurf/` | ~300 |
+| OpenAI Codex | `agents.md`, `AGENTS.md` | ~280 |
+| Google Gemini | `.gemini/` | ~250 |
+| Aider | `.aider.conf.yml`, `.aiderignore` | ~200 |
+| OpenCode | `opencode.json` | ~200 |
+
+Each platform has a dedicated context class that reads the correct config files and normalizes them into the shared `ProjectContext` interface. Platform-specific checks target a single platform. Cross-platform checks run through the **Harmony module**, which identifies practices that apply regardless of which agent a team uses (e.g., having a project instructions file, ignoring secrets, defining coding standards).
+
+## How Checks Are Added
+
+New checks follow a strict pipeline from research to production:
+
+```
+Research → Hypothesis → Experiment → Verify → Catalog → Implement
+```
+
+### Step-by-step
+
+1. **Research** — A platform changelog, documentation update, or community report identifies a potential new check. The finding is documented in a research memo with source URLs.
+
+2. **Hypothesis** — The researcher formulates what the check should detect and what impact level it warrants. At least 3 competing hypotheses are considered before committing to an approach.
+
+3. **Experiment** — The check logic is implemented as a standalone experiment and run against real project fixtures. The experiment must produce observable output.
+
+4. **Verify** — Results are reviewed. If the experiment passes, the check is marked as runtime-verified. If it fails or produces ambiguous results, it returns to research.
+
+5. **Catalog** — The verified check is added to the internal catalog with all required fields: `id`, `name`, `check`, `impact`, `confidence`, `sourceUrl`, `category`, `fix`.
+
+6. **Implement** — The cataloged check is implemented in the CLI audit engine and covered by matrix tests.
+
+### Minimum requirements for a new check
+
+- `sourceUrl` pointing to official documentation or a verifiable primary source
+- Minimum confidence score of **0.5** (no HEURISTIC-tier checks ship by default)
+- At least one passing fixture test
+- Assigned `impact` level with written justification
+- `fix` text that gives the user a concrete next step
+
+## Plugin Extension
+
+The check catalog is extensible. Any project can add custom checks by placing plugin modules in a configured directory. Plugins:
+
+1. Export an object of technique definitions matching the standard check structure
+2. Are loaded at audit time via `loadPlugins()` and merged into the active technique set
+3. Follow the same scoring, ranking, and feedback rules as built-in checks
+4. Can target any platform or be platform-agnostic
+
+This allows organizations to enforce internal standards using the same rule-based audit infrastructure with evidence tracking.
+
+## Transparency
+
+Every check has a `sourceUrl` pointing to official vendor documentation. This means:
+
+- Users can verify any finding by clicking through to the source
+- Disputed checks can be resolved by comparing the check logic against current docs
+- The audit is not a black box — it is a structured interpretation of documented best practices
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total checks | **2,441** (~300 unique rules × 8 platforms) |
+| Platforms covered | **8** |
+| Categories | **96** |
+| Stack-specific languages | **10** |
+| Research documents | **448+** |
+| Runtime experiments | **332+** |
+| Domain packs | **62** |
+| Impact levels | 3 (critical, high, medium) |
+| Confidence range | 0.0–1.0 |
+| Freshness window | 90 days |
+| Feedback tracking | Per-check, per-project, with trend analysis |
+
+---
+
+*This methodology is maintained as part of the Nerviq project. For implementation details, see the source code in `src/audit.js`, `src/activity.js`, `src/feedback.js`, and `src/freshness.js`.*

package/docs/new-platform-guide.md

@@ -0,0 +1,202 @@
+# New Platform Onboarding Guide
+
+How to add a new AI coding platform to Nerviq.
+
+## Overview
+
+Each platform in Nerviq follows a standardized structure with 14 source modules, dedicated tests, research documentation, and integration points. This guide walks through every step required to bring a new platform from zero to full parity.
+
+## Prerequisites
+
+- Access to the platform's official documentation
+- A test project configured for the platform
+- Familiarity with Nerviq's audit engine (`src/audit.js`)
+
+## Step 1: Research Phase
+
+Before writing code, produce the research deliverables:
+
+1. **Platform Research Doc** — `research/{platform}-platform-research-v1-YYYY-MM-DD.md`
+   - Architecture, config file formats, CLI commands, extension points
+   - Minimum 5 queries from different angles (Anthropic research protocol)
+   - Confidence levels for every claim
+
+2. **Gap Matrix** — `research/nerviq-{platform}-full-gap-matrix-YYYY-MM-DD.md`
+   - Compare platform capabilities against Claude Code baseline
+   - Identify all gaps and parity opportunities
+
+3. **Build Plan** — `research/nerviq-for-{platform}-build-plan-v3-final-YYYY-MM-DD.md`
+   - Phased implementation plan with deliverables per phase
+   - Dependencies and risk assessment
+
+4. **Parity Closure Plan** — `research/nerviq-{platform}-parity-closure-plan-v1-YYYY-MM-DD.md`
+   - Specific steps to close each identified gap
+
+## Step 2: Create Platform Source Modules
+
+Create the directory `src/{platform}/` with these 14 required modules:
+
+| # | File | Purpose |
+|---|------|---------|
+| 1 | `techniques.js` | Check definitions (id, name, check function, impact, category, fix) |
+| 2 | `config-parser.js` | Parse platform-specific config files |
+| 3 | `context.js` | `{Platform}ProjectContext` class with `is{Platform}Repo(dir)` detection |
+| 4 | `setup.js` | Generate starter config files for the platform |
+| 5 | `plans.js` | Proposal generation and application logic |
+| 6 | `governance.js` | Permission profiles, policy packs, governance rules |
+| 7 | `interactive.js` | Step-by-step guided wizard for the platform |
+| 8 | `deep-review.js` | AI-powered config review (opt-in) |
+| 9 | `freshness.js` | Freshness checks for platform-specific configs |
+| 10 | `domain-packs.js` | Domain-specific check packs (React, Python, etc.) |
+| 11 | `mcp-packs.js` | MCP server integration packs |
+| 12 | `activity.js` | Snapshot and activity tracking |
+| 13 | `patch.js` | Config patching and migration helpers |
+| 14 | `premium.js` | Premium/advanced checks |
+
+### Module template
+
+Each `techniques.js` must export an array of check objects:
+
+```js
+module.exports = [
+  {
+    key: '{platform}ConfigExists',
+    name: '{Platform} config file exists',
+    category: 'Memory & Context',
+    impact: 'critical',
+    check: (dir) => {
+      const fs = require('fs');
+      return fs.existsSync(`${dir}/.{platform}-config`);
+    },
+    fix: 'Create a .{platform}-config file in the project root.',
+    sourceUrl: 'https://docs.{platform}.dev/config',
+    confidence: 0.9,
+  },
+  // ... more checks
+];
+```
+
+Each `context.js` must export a class with static detection:
+
+```js
+class {Platform}ProjectContext {
+  static is{Platform}Repo(dir) {
+    const fs = require('fs');
+    return fs.existsSync(`${dir}/.{platform}-config`);
+  }
+}
+module.exports = { {Platform}ProjectContext };
+```
+
+## Step 3: Create Test Files
+
+| File | Purpose |
+|------|---------|
+| `test/{platform}.test.js` | Unit tests for all 14 modules |
+| `test/{platform}-check-matrix.js` | Matrix test: every check runs against fixtures |
+| `test/{platform}-golden-matrix.js` | Golden file test: audit output matches expected |
+| `test/{platform}-fixtures.js` | Test fixture generator |
+
+### Check matrix template
+
+The check matrix ensures every technique key in `techniques.js` is exercised:
+
+```js
+const techniques = require('../src/{platform}/techniques');
+const allKeys = techniques.map(t => t.key);
+
+for (const key of allKeys) {
+  // Verify check function exists and returns boolean
+  const technique = techniques.find(t => t.key === key);
+  const result = technique.check(fixtureDir);
+  assert(typeof result === 'boolean', `${key} must return boolean`);
+}
+```
+
+## Step 4: Integration Points
+
+### 4a. Register in `src/audit.js`
+
+Add platform detection and technique loading:
+
+```js
+// In the platform resolution logic
+if (platform === '{platform}') {
+  techniques = require('./{platform}/techniques');
+}
+```
+
+### 4b. Register in `src/public-api.js`
+
+Add to `PLATFORM_ORDER` and `PLATFORM_DETECTORS`:
+
+```js
+const { {Platform}ProjectContext } = require('./{platform}/context');
+
+// In PLATFORM_ORDER array:
+'{platform}',
+
+// In PLATFORM_DETECTORS object:
+{platform}: (dir) => {Platform}ProjectContext.is{Platform}Repo(dir),
+```
+
+### 4c. Register in `src/catalog.js`
+
+Ensure `generateCatalog()` includes the new platform's techniques.
+
+### 4d. Register in `bin/cli.js`
+
+Add platform validation in the CLI argument parser (the platform check near line 363).
+
+### 4e. Register in Harmony
+
+Add to `PLATFORM_AUDIT_MAP` in `src/harmony/audit.js`:
+
+```js
+{platform}: '{platform}',
+```
+
+### 4f. Update `action.yml`
+
+Add platform to the GitHub Action inputs if needed.
+
+## Step 5: Documentation
+
+- Update `README.md` platform table
+- Update `CHANGELOG.md` with the new platform entry
+- Add platform to `package.json` keywords
+- Update `docs/ARCHITECTURE.md` if it references platform list
+
+## 17-Point Deliverables Checklist
+
+Use this checklist to track completion. All items must be done before the platform is considered fully supported.
+
+- [ ] 1. Platform research document
+- [ ] 2. Gap matrix vs Claude Code baseline
+- [ ] 3. Build plan (v3 final)
+- [ ] 4. Parity closure plan
+- [ ] 5. `src/{platform}/techniques.js` — all checks with sourceUrl + confidence
+- [ ] 6. `src/{platform}/config-parser.js`
+- [ ] 7. `src/{platform}/context.js` — with `is{Platform}Repo()` detection
+- [ ] 8. `src/{platform}/setup.js`
+- [ ] 9. `src/{platform}/plans.js`
+- [ ] 10. `src/{platform}/governance.js`
+- [ ] 11. Remaining 8 modules (interactive, deep-review, freshness, domain-packs, mcp-packs, activity, patch, premium)
+- [ ] 12. `test/{platform}.test.js`
+- [ ] 13. `test/{platform}-check-matrix.js`
+- [ ] 14. `test/{platform}-golden-matrix.js`
+- [ ] 15. Integration in audit.js, public-api.js, catalog.js, cli.js
+- [ ] 16. Harmony integration
+- [ ] 17. README, CHANGELOG, and documentation updates
+
+## Quality Gates
+
+Before merging a new platform:
+
+1. All check-matrix tests pass: `node test/{platform}-check-matrix.js`
+2. All golden-matrix tests pass: `node test/{platform}-golden-matrix.js`
+3. Jest tests pass: `npx jest test/{platform}.test.js`
+4. Platform appears in `nerviq catalog` output
+5. `nerviq audit --platform {platform}` runs successfully on a real project
+6. Harmony audit includes the new platform
+7. Every technique has `sourceUrl` and `confidence >= 0.7`

package/docs/open-vsx-publishing.md

@@ -0,0 +1,46 @@
+# Publishing to Open VSX Registry
+
+## What is Open VSX?
+
+Open VSX is an open, vendor-neutral registry for VS Code extensions, hosted by the Eclipse Foundation.
+
+## Why Publish to Open VSX?
+
+Cursor IDE uses Open VSX (not Microsoft's VS Code Marketplace) as its extension backend. Microsoft's licensing blocks non-VS-Code forks from accessing their marketplace, so Cursor, VSCodium, and Gitpod all rely on Open VSX instead.
+
+**Publishing to Open VSX gives us compatibility with all three platforms for free.**
+
+See: [Cursor Marketplace Research (2026-04-06)](../../research/cursor-marketplace-research-2026-04-06.md)
+
+## VS Code Extension Source
+
+The Nerviq VS Code extension lives in this repo at [`vscode-extension/`](../vscode-extension/).
+
+## How to Get a Token
+
+1. Create an account at [accounts.eclipse.org](https://accounts.eclipse.org/)
+2. Go to [open-vsx.org](https://open-vsx.org/) and sign in with your Eclipse account
+3. Navigate to your user settings and generate an access token
+4. Store the token as `OVSX_TOKEN` in your GitHub repository secrets
+
+## How to Publish Manually
+
+```bash
+# Package the extension
+cd vscode-extension
+npm install
+npx @vscode/vsce package
+
+# Publish to Open VSX
+npx ovsx publish *.vsix -p <your-token>
+```
+
+## Automated Publishing
+
+A GitHub Actions workflow is available at [`.github/workflows/publish-ovsx.yml`](../.github/workflows/publish-ovsx.yml). It runs on manual dispatch (`workflow_dispatch`) and requires the `OVSX_TOKEN` secret to be configured.
+
+## References
+
+- [Open VSX Registry](https://open-vsx.org/)
+- [Open VSX Publishing Guide](https://github.com/eclipse/openvsx/wiki/Publishing-Extensions)
+- [Eclipse Foundation Account](https://accounts.eclipse.org/)

package/docs/platform-change-ingestion.md

@@ -0,0 +1,46 @@
+# Platform Change Ingestion
+
+How Nerviq stays current across Claude, Codex, Cursor, Copilot, Gemini CLI, Windsurf, Aider, and OpenCode.
+
+## Source of truth
+
+- `src/platform-change-manifest.js`
+- `.github/workflows/freshness-check.yml`
+- Platform-specific freshness modules under `src/*/freshness.js`
+
+The manifest is the canonical inventory for:
+- tracked P0 sources per platform
+- review cadence
+- daily freshness workflow details
+- propagation/update triggers
+
+## What gets tracked
+
+For each supported platform, Nerviq keeps:
+- official docs URLs
+- changelog / release-note URLs
+- freshness thresholds
+- propagation triggers that describe what must update when the platform changes
+
+## Cadence
+
+- Automation: daily freshness workflow at `06:00 UTC`
+- Manual review: weekly for 14-day sources, monthly for 30-day sources
+- Immediate review: any stale source or breaking platform change
+
+## Operational workflow
+
+1. The daily freshness workflow checks each platform's P0 sources.
+2. If a source is stale or unverified, the workflow opens or updates a GitHub issue.
+3. The maintainer verifies the source, updates the matching `freshness.js` file, and follows the propagation checklist.
+4. If config semantics changed, update the relevant checks plus `src/platform-change-manifest.js`.
+
+## Why this matters
+
+This is the layer that lets Nerviq say more than "we have source URLs."
+It creates an explicit system for:
+- what we watch
+- how often we review it
+- what code/docs must change when a platform moves
+
+That keeps freshness from becoming tribal knowledge or an ad-hoc chore.

package/docs/plugins.md

@@ -0,0 +1,101 @@
+# Nerviq Plugin System
+
+Nerviq supports custom checks via a plugin system. You can extend the audit with project-specific or organization-specific checks by creating a `nerviq.config.js` file in your project root.
+
+## Creating a Plugin
+
+1. Create `nerviq.config.js` in your project root.
+2. Export an object with a `plugins` array.
+3. Each plugin has a `name` and a `checks` object.
+
+```javascript
+// nerviq.config.js
+module.exports = {
+  plugins: [
+    {
+      name: 'my-org-standards',
+      checks: {
+        hasChangelog: {
+          id: 'ORG-001',
+          name: 'Project has a CHANGELOG',
+          check: (ctx) => ctx.files.includes('CHANGELOG.md'),
+          impact: 'medium',
+          category: 'hygiene',
+          fix: 'Create a CHANGELOG.md to track project changes.',
+          sourceUrl: 'https://keepachangelog.com',
+          confidence: 0.9,
+        },
+        hasCodeOwners: {
+          id: 'ORG-002',
+          name: 'CODEOWNERS file exists',
+          check: (ctx) => ctx.files.includes('CODEOWNERS') || ctx.files.includes('.github/CODEOWNERS'),
+          impact: 'high',
+          category: 'quality',
+          fix: 'Add a CODEOWNERS file to enforce review assignments.',
+          sourceUrl: null,
+          confidence: 0.8,
+        },
+      },
+    },
+  ],
+};
+```
+
+## Plugin API
+
+### Check Object Format
+
+Each check in the `checks` object must have these **required** fields:
+
+| Field      | Type       | Description                                                    |
+|------------|------------|----------------------------------------------------------------|
+| `id`       | `string`   | Unique identifier for the check (e.g. `'CUSTOM-001'`).        |
+| `name`     | `string`   | Human-readable name shown in audit results.                    |
+| `check`    | `function` | `(ctx) => boolean \| null`. Return `true` if passed, `false` if failed, `null` if not applicable. |
+| `impact`   | `string`   | One of: `'critical'`, `'high'`, `'medium'`, `'low'`.           |
+| `category` | `string`   | Category grouping (e.g. `'custom'`, `'hygiene'`, `'security'`). |
+| `fix`      | `string`   | Actionable fix message shown when the check fails.             |
+
+Optional fields:
+
+| Field        | Type     | Default | Description                                        |
+|--------------|----------|---------|----------------------------------------------------|
+| `sourceUrl`  | `string` | `null`  | URL to documentation or rationale for this check.  |
+| `confidence` | `number` | `0.5`   | Confidence level from 0 to 1.                      |
+
+### The Context Object (`ctx`)
+
+The `check` function receives a project context object with these useful properties and methods:
+
+- `ctx.files` -- array of all file paths in the project (relative to root)
+- `ctx.fileContent(path)` -- returns file contents as string, or empty string
+- `ctx.claudeMdContent()` -- returns CLAUDE.md content
+- `ctx.hasDir(path)` -- returns true if directory exists
+- `ctx.dirFiles(path)` -- returns array of files in a directory
+
+## How Plugin Checks Appear in Audit Results
+
+Plugin checks are merged into the standard audit and appear alongside built-in checks. In the results, plugin checks are keyed as `plugin:<plugin-name>:<check-key>`. For example, a check `hasChangelog` in plugin `my-org-standards` appears as:
+
+```
+plugin:my-org-standards:hasChangelog
+```
+
+Plugin checks are scored and weighted using the same `impact`-based system as built-in checks. They appear in:
+
+- The full results list
+- Failed check recommendations (if they fail)
+- Score calculations
+
+## Validation
+
+Nerviq validates all plugins at load time. Plugins with missing required fields are skipped and an error is logged. You can also validate a plugin programmatically:
+
+```javascript
+const { validatePlugin } = require('@nerviq/cli/src/plugins');
+
+const result = validatePlugin(myPlugin);
+if (!result.valid) {
+  console.error('Plugin errors:', result.errors);
+}
+```

package/docs/pre-commit.md

@@ -0,0 +1,58 @@
+# Pre-commit Hook Integration
+
+[pre-commit](https://pre-commit.com) is a framework for managing and running git hooks across projects using a shared configuration file.
+
+## Setup
+
+Install pre-commit if you haven't already:
+
+```bash
+pip install pre-commit
+```
+
+Add Nerviq to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/nerviq/nerviq
+    rev: v1.8.0
+    hooks:
+      - id: nerviq-audit
+        args: ['60']  # minimum score threshold
+```
+
+Then install the hooks:
+
+```bash
+pre-commit install
+```
+
+## Customization
+
+**Change the threshold** by editing the `args` value. The audit fails if the project score is below this number (0-100):
+
+```yaml
+args: ['80']  # stricter threshold
+```
+
+**Use pre-push instead of pre-commit** for a full audit that runs only when pushing:
+
+```yaml
+repos:
+  - repo: https://github.com/nerviq/nerviq
+    rev: v1.8.0
+    hooks:
+      - id: nerviq-audit-full
+        args: ['40']
+```
+
+Then install the push hook:
+
+```bash
+pre-commit install --hook-type pre-push
+```
+
+## Requirements
+
+- Node.js 18+
+- `npx` available on PATH (included with Node.js)