@nerviq/cli 0.0.1 → 0.9.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,181 @@
+# Changelog
+
+## [1.16.2] - 2026-04-03
+
+### Changed
+- bumped the local release line to `1.16.2` so the next publish does not overwrite the already-live `1.16.1` npm release
+- synchronized README, docs, launch copy, and proof-facing state to distinguish clearly between public npm latest (`1.16.1`) and local release prep (`1.16.2`)
+
+### Fixed
+- release-truth drift across package metadata, docs, and public-facing proof references
+
+## [1.16.1] - 2026-04-03
+
+### Added
+- `feedback` command validation on the public npm package line
+- stronger secret detection coverage for Anthropic-style keys
+- deep-review sanitization and secret redaction hardening
+- watch-mode resilience improvements across recursive and non-recursive platforms
+
+### Changed
+- increased verified check count from `84` to `85`
+- proof-backed product copy and case-study traceability improvements
+
+## [1.10.3] - 2026-04-02
+
+### Added
+- `--snapshot` support for `audit`, `augment`, `suggest-only`, `benchmark`, and `governance`, writing normalized evidence artifacts under `.claude/claudex-setup/snapshots/`
+- shared snapshot history via `index.json` so before/after work can accumulate into a single local evidence spine
+- `governance --out governance.md` for a shareable governance / pilot-readiness artifact
+- packaged Claude-native `audit-repo` skill template under `content/claude-code/audit-repo/`
+- lightweight release checklist in `content/release-checklist.md`
+
+### Changed
+- default audit now surfaces `Top 5 Next Actions` with rationale, traceability, risk, confidence, and a suggested next command
+- `--lite` now gives a shorter beginner-first top-3 quick scan
+- README and docs now reflect snapshot artifacts, governance export, and the Claude-native skill path
+- packaged content and public-facing counts are now aligned with the current CLAUDEX state
+
+## [1.14.0] - 2026-04-03
+
+### Added
+- Check-level test matrix: 327 verified scenarios across all 84 checks
+- Golden matrix: 12 repo profile tests with expected results
+
+### Fixed
+- `hooks` check now detects hooks in settings.json (not only .claude/hooks/ dir)
+- `context7Mcp` check now reads .mcp.json
+- `skillUsesPaths` now traverses skill subdirectories (skills/name/SKILL.md)
+- `lintCommand` now matches npm/yarn/pnpm/bun lint commands
+
+## [1.13.0] - 2026-04-03
+
+### Added
+- 10 new checks (74→84): project description, directory structure, multiple hook types, stop-failure hook, skill paths, MCP env config, gitignore local settings, .env.example, package scripts, type checking
+- 15 new tests (58→73): history/compare/trend, new checks structure, CLI commands, deny depth, negative instructions, --require flag
+- All references updated to 74→84 checks
+
+## [1.12.0] - 2026-04-03
+
+### Added
+- 12 new checks (62→74): test coverage, agent tool restrictions, auto-memory, sandbox, deny rule depth, git attribution, effort level, snapshot history, worktree, negative instructions, output style, CI variants
+- 8 new stacks (22→30): Deno, Bun, Elixir, Astro, Remix, NestJS, Laravel, .NET
+- Deeper domain detection: llamaindex, crewai, autogen, ollama for AI/ML; paypal, square, adyen, medusa for ecommerce; chromatic, style-dictionary for design; capacitor, ionic for mobile
+
+### Fixed
+- `githubActionsOrCI` check used non-existent `ctx.hasFile()` — now uses `ctx.fileContent()`
+- `.NET` stack detection no longer uses glob patterns
+
+## [1.11.0] - 2026-04-03
+
+### Added
+- `history` command — show score timeline from saved snapshots
+- `compare` command — diff latest vs previous snapshot with delta, regressions, improvements
+- `trend --out report.md` — export trend report as shareable markdown
+- `--require A,B` CI flag — exit code 1 if named checks fail (policy guardrails)
+- Agentic DX positioning in README
+- Real results table (4 case studies) in README
+- Claude-native integration guide (skill, hook, agent examples)
+- Trust-first help text reordering
+
+### Fixed
+- Hook checks (hooksInSettings, preToolUse, postToolUse, sessionStart) now OR across settings.json and settings.local.json
+
+## [1.10.2] - 2026-04-02
+
+### Fixed
+- MCP recommendations are now less speculative: `postgres-mcp` requires explicit Postgres signals, `figma-mcp` only appears for design-system repos, and `mcp-security` is no longer auto-added just because multiple packs were suggested
+- `sentry-mcp` now requires real observability signals or stricter operational domains instead of appearing for every frontend/backend repo
+- design-system detection now respects `.storybook/` directories directly, improving frontend pack accuracy
+
+### Added
+- MCP preflight warnings for `setup`, `plan`, and `apply` when selected packs require missing environment variables
+- user-facing docs now reflect the actual 22 detected stacks
+
+## [1.10.1] - 2026-04-02
+
+### Fixed
+- corrected MCP pack package names to verified npm packages
+- aligned settings hierarchy checks with shared settings precedence
+
+## [1.10.0] - 2026-04-01
+
+### Added
+- 11 new MCP packs (15→26): sequential-thinking, jira-confluence, ga4-analytics, search-console, n8n-workflows, zendesk, infisical-secrets, shopify, huggingface, blender, wordpress
+- 7 new domain packs (10→17→16 final): ecommerce, ai-ml, devops-cicd, design-system, docs-content, security-focused
+- Smart recommendation for all new packs based on detected stack and domain
+- Detection logic: Storybook, Docusaurus, Stripe, LangChain, GitHub Actions, auth deps
+
+## [1.9.0] - 2026-03-31
+
+### Added
+- 3 new domain packs: `monorepo`, `mobile`, `regulated-lite` (7→10 total)
+- 3 new MCP packs: `github-mcp`, `postgres-mcp`, `memory-mcp` (2→5 total)
+- smart MCP pack recommendation based on detected domain packs
+- `suggest-only --out report.md` exports full analysis as shareable markdown
+- `why` explanations for all strengths preserved (20+ specific reasons)
+- `why` explanations for all gap findings (12+ specific reasons)
+- 5 new hooks in governance registry: duplicate-id-check, injection-defense, trust-drift-check, session-init, protect-catalog
+- case study template in `content/case-study-template.md`
+- hook risk level display in governance output (color-coded low/medium/high)
+
+### Fixed
+- **Settings hierarchy bug**: `noBypassPermissions` and `secretsProtection` checks now correctly read `.claude/settings.json` before `.claude/settings.local.json`, so personal maintainer overrides no longer fail the shared audit
+- domain pack detection now handles monorepo (nx.json, turbo.json, lerna.json, workspaces), mobile (React Native, Flutter, iOS/Android dirs), and regulated repos (SECURITY.md, compliance dirs)
+
+### Changed
+- strengths preserved section now shows 8 items (was 6) with specific value explanations
+- claudex-sync.json updated with domain pack, MCP pack, and anti-pattern counts
+
+## [1.8.0] - 2026-03-31
+
+### Added
+- domain pack recommendations for backend, frontend, data, infra, OSS, and enterprise-governed repos
+- MCP pack recommendations and merge support for `context7-docs` and `next-devtools`
+- workflow-evidence coverage in benchmark reports
+- runtime settings overlays so `apply --plan` still respects current `--profile` and `--mcp-pack` flags
+
+### Changed
+- benchmark now respects the selected profile and MCP pack options during isolated-copy runs
+- governance and suggest-only outputs now expose domain packs and MCP packs directly
+- README and docs clarify the local-vs-opt-in-network boundary for core flows vs `deep-review`
+- audit output now frames `setup` as starter-safe generation instead of an automatic full fix
+
+## [1.7.0] - 2026-03-31
+
+### Added
+- `augment` / `suggest-only` repo-aware analysis with strengths, gaps, top actions, risk notes, and rollout order
+- `plan` command for exportable proposal bundles with file previews and diff-style output
+- `apply` command for selective starter-safe apply flows with rollback manifests and activity artifacts
+- `governance` command with permission profiles, hook registry, policy packs, and pilot rollout guidance
+- `benchmark` command that measures before/after impact in an isolated temp copy and exports evidence reports
+- claims governance and pilot rollout docs in `content/`
+
+### Changed
+- `setup` now exposes reusable planning primitives and returns written/preserved file summaries
+- CLI now supports `--out`, `--plan`, `--only`, and `--dry-run`
+- README and docs now reflect the actual product surface instead of only audit/setup flows
+- benchmark and proposal workflows now preserve existing files by default and treat mature repos as review-first
+
+## [0.2.0] - 2026-03-31
+
+### Added
+- 50+ audit checks (up from 16)
+- 8 new categories: Design, DevOps, Hygiene, Performance, MCP, Prompting, Git Safety, Automation
+- 6 new stack detections: Svelte, Flutter, Ruby, Java, Kotlin, Swift
+- Improved CLAUDE.md template with Mermaid diagrams and XML constraints
+- Auto-sync with CLAUDEX research catalog (1,107 items)
+- Copy-paste config snippets in fix suggestions
+
+### Changed
+- Knowledge base upgraded from 972 to 1,107 verified techniques
+- Better scoring weights per category
+
+## [0.1.0] - 2026-03-30
+
+### Added
+- Initial release
+- 16 audit checks
+- Automatic setup with CLAUDE.md, hooks, commands, skills, rules, agents
+- Stack detection for 12 frameworks
+- JSON output mode

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CLAUDEX Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,447 @@
+# claudex-setup
+
+> Score your repo's Claude Code setup against 85 checks. See what's missing, apply only what you approve with rollback, and benchmark the impact — without breaking existing config.
+
+[![npm version](https://img.shields.io/npm/v/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
+[![npm downloads](https://img.shields.io/npm/dm/claudex-setup)](https://www.npmjs.com/package/claudex-setup)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+### What this is
+
+- The **Agentic DX layer for Claude Code** — audit, improve, govern, and benchmark how Claude works with your repo
+- A **Claude Code workflow audit and improvement tool** — not an MCP installer, not a code generator
+- Scores your repo 0-100 across CLAUDE.md, hooks, commands, agents, skills, MCP, security, and more
+- Proposes changes as diffs you review — applies only what you approve, with rollback for every change
+- Includes governance (permission profiles, hook registry, policy packs) and benchmark (isolated before/after)
+
+### What this is NOT
+
+- Not an MCP setup tool (MCP packs are one of 26 features, not the product)
+- Not a code generator or refactoring tool — it configures how Claude works with your repo, not the code itself
+- Not a replacement for hand-crafted CLAUDE.md — generated output is a strong starting point, not a final answer
+- Not a score you should chase blindly — 90/100 with bad code is still bad code
+
+## Quick Start
+
+```bash
+npx claudex-setup --lite      # Quick beginner scan: top 3 fixes + next command
+npx claudex-setup              # Audit your project (10 seconds)
+npx claudex-setup --snapshot   # Save a normalized snapshot under .claude/claudex-setup/
+npx claudex-setup setup        # Create a starter-safe baseline
+npx claudex-setup augment      # Repo-aware plan, no writes
+npx claudex-setup plan         # Export proposal bundles with file previews
+npx claudex-setup governance   # See permission profiles, packs, and pilot guidance
+npx claudex-setup governance --out governance.md  # Export a shareable governance report
+npx claudex-setup benchmark    # Measure before/after in an isolated temp copy
+npx claudex-setup --threshold 60   # Fail CI if score is below 60
+```
+
+No install. No config. No dependencies.
+
+## Real Results
+
+Tested on 4 real projects — not demos:
+
+| Project | Type | Before | After | Delta |
+|---------|------|--------|-------|-------|
+| CLAUDEX | Research engine, Python | 62 | 90 | **+28** |
+| VTCLE | Marketing automation, FastAPI | 46 | 64 | **+18** |
+| Social | Mobile app, React Native | 40 | 48 | **+8** |
+| Polymiro | Prediction system, Python/Docker | 35 | 48 | **+13** |
+
+Most common gaps found: missing secrets protection, no deny rules, no mermaid diagram, no hooks in settings.
+
+> Scores measured with claudex-setup@1.10.3 on 2026-04-03. Current npm latest: 1.16.1, so exact scores may differ slightly on the newer release.
+>
+> Canonical proof artifacts: [Index](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md) | [CLAUDEX trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/claudex-self-dogfood-proof-trace-2026-04-03.md) | [VTCLE trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/vtcle-proof-trace-2026-04-03.md) | [Social trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/social-proof-trace-2026-04-03.md) | [Polymiro trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/polymiro-proof-trace-2026-04-03.md)
+>
+> Narrative case studies: [VTCLE](https://github.com/DnaFin/claudex/blob/main/research/case-study-vtcle-2026-04-03.md) | [Social](https://github.com/DnaFin/claudex/blob/main/research/case-study-social-2026-04-03.md) | [Polymiro](https://github.com/DnaFin/claudex/blob/main/research/case-study-polymiro-2026-04-03.md)
+
+## What You Get
+
+```
+  claudex-setup audit
+  ═══════════════════════════════════════
+  Detected: React, TypeScript, Docker
+
+  ████████████████░░░░ 78/100
+
+  ✅ Passing
+     CLAUDE.md project instructions
+     Mermaid architecture diagram
+     Hooks (PreToolUse + PostToolUse)
+     Custom slash commands (5 commands)
+     XML constraint blocks
+     Secrets protection configured
+
+  🟡 High Impact
+     CI pipeline configured
+     → Add .github/workflows/ for automated testing
+
+  ⚡ Top 5 Next Actions
+     1. Add CLAUDE.md verification criteria
+        Why: Claude needs an explicit verification loop before handoff
+        Trace: failed-check:verificationLoop | impact:critical | category:quality
+        Risk: high | Confidence: high
+        Fix: Add test/lint/build commands to CLAUDE.md so Claude can verify its own work
+
+     2. Configure safe permissions + deny rules
+        Why: Explicit permissions are the main safety layer for repo writes
+        Trace: failed-check:permissionDeny | impact:high | category:security
+        Risk: medium | Confidence: high
+        Fix: Add permissions.deny rules to block dangerous operations
+
+  Weakest areas:
+      design: none (0/2)
+     devops: none (0/4)
+
+  29/85 checks passing
+  Next command: npx claudex-setup setup
+```
+
+Want the shortest possible first run?
+
+```bash
+npx claudex-setup --lite
+```
+
+That prints a compact top-3 quick scan with one clear next command.
+
+## All Commands
+
+| Command | What it does |
+|---------|-------------|
+| `npx claudex-setup` | **Discover** - Score 0-100 against 85 checks |
+| `npx claudex-setup discover` | **Discover** - Alias for audit mode |
+| `npx claudex-setup setup` | **Starter** - Smart CLAUDE.md + hooks + commands + agents |
+| `npx claudex-setup starter` | **Starter** - Alias for setup mode |
+| `npx claudex-setup setup --auto` | **Auto-setup** - No prompts, apply all |
+| `npx claudex-setup augment` | **Augment** - Repo-aware improvement plan, no writes |
+| `npx claudex-setup suggest-only` | **Suggest-Only** - Structured recommendation report, no writes |
+| `npx claudex-setup plan` | **Plan** - Export proposal bundles with previews, rationale, and file-level changes |
+| `npx claudex-setup apply` | **Apply** - Apply ready proposal bundles with rollback + activity artifacts |
+| `npx claudex-setup governance` | **Governance** - Permission profiles, hook registry, policy packs, pilot kit |
+| `npx claudex-setup benchmark` | **Benchmark** - Before/after evidence from an isolated temp copy |
+| `npx claudex-setup interactive` | **Wizard** - Step-by-step guided tour |
+| `npx claudex-setup watch` | **Watch** - Live monitoring with score delta and cross-platform directory fallback |
+| `npx claudex-setup badge` | **Badge** - Generate shields.io badge for README |
+| `npx claudex-setup feedback` | **Feedback** - Record local recommendation outcomes or show outcome summary |
+| `npx claudex-setup deep-review` | **Deep Review** - AI-powered config analysis (Claude Code or API key, selected config only) |
+| `npx claudex-setup insights` | **Insights** - View community aggregate stats |
+
+## Codex Preview On Main
+
+The current published npm package is still Claude-first.
+
+On the current main branch and next release line, `claudex-setup` also includes a Codex vertical through:
+
+- `npx claudex-setup --platform codex`
+- `npx claudex-setup --platform codex augment`
+- `npx claudex-setup --platform codex suggest-only`
+- `npx claudex-setup --platform codex setup`
+- `npx claudex-setup --platform codex plan`
+- `npx claudex-setup --platform codex apply`
+- `npx claudex-setup --platform codex governance`
+- `npx claudex-setup --platform codex benchmark`
+
+That means the Codex line now has:
+
+- audit and `--lite`
+- no-write advisory flows (`augment`, `suggest-only`)
+- setup / plan / apply
+- governance and benchmark
+- initial domain pack recommendations (`baseline-general`, `backend-api`, `frontend-ui`, `enterprise-governed`, `monorepo`, `infra-platform`)
+
+Current pre-release validation artifacts:
+
+- [Codex v1.0 validation summary](https://github.com/DnaFin/claudex/blob/main/research/codex-v1.0-validation-results-v1-2026-04-03.md)
+- [Codex case study — CLAUDEX](https://github.com/DnaFin/claudex/blob/main/research/case-study-codex-claudex-2026-04-03.md)
+- [Codex case study — claudex-setup](https://github.com/DnaFin/claudex/blob/main/research/case-study-codex-claudex-setup-2026-04-03.md)
+- [Codex case study — VTCLE](https://github.com/DnaFin/claudex/blob/main/research/case-study-codex-vtcle-2026-04-03.md)
+
+Boundary note:
+
+- these Codex artifacts are measured on the local `1.16.2` pre-release line
+- do not present them as npm-latest proof until the Codex-capable package line is published
+
+### Options
+
+| Flag | Effect |
+|------|--------|
+| `--threshold N` | Exit with code 1 if score is below `N` (great for CI) |
+| `--out FILE` | Write JSON or markdown output to a file |
+| `--plan FILE` | Load a previously exported plan file |
+| `--only A,B` | Limit plan/apply to selected proposal ids |
+| `--profile NAME` | Choose a permission profile for write-capable flows |
+| `--mcp-pack A,B` | Merge named MCP packs into generated or patched settings |
+| `--key NAME` | Recommendation key for `feedback` logging |
+| `--status VALUE` | Outcome status: `accepted`, `rejected`, or `deferred` |
+| `--effect VALUE` | Outcome effect: `positive`, `neutral`, or `negative` |
+| `--score-delta N` | Optional observed score delta tied to the feedback event |
+| `--snapshot` | Save a normalized artifact under `.claude/claudex-setup/snapshots/` |
+| `--lite` | Show a short top-3 quick scan with one clear next command |
+| `--dry-run` | Preview apply without writing files |
+| `--verbose` | Show all recommendations (not just critical/high) |
+| `--json` | Machine-readable JSON output (for CI) |
+| `--auto` | Apply setup files without prompts |
+| `--insights` | Enable anonymous usage insights (off by default) |
+
+## Smart CLAUDE.md Generation
+
+Not a generic template. The `setup` command actually analyzes your project:
+
+- **Reads package.json** - includes your actual test, build, lint, dev commands
+- **Reads pyproject.toml** - uses Python project name/description when package.json does not exist
+- **Detects framework** - Next.js Server Components, Django models, FastAPI Pydantic, React hooks
+- **TypeScript-aware** - detects strict mode, adds TS-specific rules
+- **Auto Mermaid diagram** - scans directories and generates architecture visualization (Mermaid diagrams are more token-efficient than prose descriptions, per Anthropic docs)
+- **XML constraint blocks** - adds `<constraints>` and `<verification>` with context-aware rules
+- **Verification criteria** - auto-generates checklist from your actual commands
+- **Safer settings.json** - generated hooks config now includes `acceptEdits` plus deny rules for dangerous or secret-sensitive operations
+
+## Mode Model
+
+- **Discover**: score the repo, surface critical issues, and show the best next actions
+- **Starter**: generate a safe baseline when the repo has little or no Claude setup
+- **Augment**: inspect the current repo and build a structured improvement plan without writing files
+- **Suggest-Only**: same no-write analysis, optimized for sharing or manual review
+- **Governance**: surface permission profiles, shipped hooks, policy packs, and pilot guidance
+- **Benchmark**: prove value on an isolated copy before touching the real repo
+
+## Proposal + Apply Workflow
+
+Use `plan` when you want a file-by-file proposal bundle before any write happens:
+
+```bash
+npx claudex-setup plan --out claudex-plan.json
+```
+
+Each proposal bundle includes:
+
+- trigger reasons tied to failed checks
+- file previews and diff-style output
+- `create`, `patch`, or `manual-review` classification
+- risk/confidence labels
+
+Apply only the bundles you want:
+
+```bash
+npx claudex-setup apply --plan claudex-plan.json --only claude-md,hooks
+```
+
+`apply` creates rollback manifests and activity artifacts under `.claude/claudex-setup/`, so every applied batch has a paper trail and a create-or-patch rollback path.
+
+## Governance And Pilot Readiness
+
+Use `governance` when the question is "can we pilot this safely?" instead of "what files can you generate?".
+
+```bash
+npx claudex-setup governance
+npx claudex-setup governance --out governance.md
+```
+
+It exposes:
+
+- permission profiles: `read-only`, `suggest-only`, `safe-write`, `power-user`, `internal-research`
+- hook registry with trigger point, purpose, side effects, risk, and rollback path
+- policy packs for baseline engineering, security-sensitive repos, OSS, and regulated-lite teams
+- 16 domain packs: backend-api, frontend-ui, data-pipeline, infra-platform, oss-library, enterprise-governed, monorepo, mobile, regulated-lite, ecommerce, ai-ml, devops-cicd, design-system, docs-content, security-focused, baseline-general
+- 26 MCP packs: Context7, Next.js devtools, GitHub, PostgreSQL, Playwright, Docker, Notion, Linear, Sentry, Slack, Stripe, Figma, Shopify, Hugging Face, Blender, WordPress, Jira/Confluence, GA4, Search Console, n8n, Zendesk, Infisical, Composio, memory, sequential-thinking, mcp-security
+- a pilot rollout kit with scope, approvals, success metrics, and rollback expectations
+
+Use `--out governance.md` if you want a shareable artifact for leads, platform teams, or security review.
+
+## Domain Packs And MCP Packs
+
+`augment` and `suggest-only` now recommend repo-shaped guidance instead of giving every project the same advice.
+
+- 16 domain packs identify repo shape and recommend relevant modules
+- 26 MCP packs recommend tooling companions matched to your detected domain and stack
+- write-capable flows can merge MCP packs directly into `.claude/settings.json`
+
+```bash
+npx claudex-setup suggest-only --json
+npx claudex-setup setup --mcp-pack context7-docs
+npx claudex-setup apply --plan claudex-plan.json --only hooks --mcp-pack context7-docs,next-devtools
+```
+
+## Benchmark And Evidence
+
+Use `benchmark` to measure the impact of starter-safe improvements without modifying your working repo:
+
+```bash
+npx claudex-setup benchmark --out benchmark.md
+```
+
+Benchmark mode:
+
+- runs a baseline audit on your repo
+- copies the repo to an isolated temp workspace
+- applies starter-safe artifacts only in the copy
+- reruns the audit and emits before/after deltas, workflow-evidence coverage, a case-study summary, and an executive recommendation
+
+If you want repeatable evidence artifacts for before/after work, add `--snapshot` to `audit`, `augment`, `suggest-only`, `benchmark`, or `governance`.
+
+```bash
+npx claudex-setup --snapshot
+npx claudex-setup augment --snapshot
+npx claudex-setup benchmark --snapshot
+```
+
+Snapshots are written to `.claude/claudex-setup/snapshots/` with a shared envelope and an `index.json` history file.
+
+If you want a local-first recommendation loop, record what actually helped:
+
+```bash
+npx claudex-setup feedback --key permissionDeny --status accepted --effect positive --score-delta 12
+npx claudex-setup feedback
+```
+
+Feedback stays under `.claude/claudex-setup/outcomes/` and is used only as a local ranking signal. Recommendations with repeated positive outcomes get a measured boost; recommendations with repeated negative or rejected outcomes get pushed down.
+
+`watch` uses native `fs.watch` with recursive directory watches where the platform supports them, and an expanded directory fallback elsewhere. That keeps nested `.claude/` and `.github/` changes visible on Linux too, while staying zero-dependency. Native filesystem watch semantics can still be noisier on very large repos or network filesystems, so the command is best treated as fast local feedback rather than a CI-grade signal.
+
+## Use Inside Claude Code
+
+If you want the first Claude-native entry point, copy the shipped skill template into your repo.
+
+If `claudex-setup` is installed locally in `node_modules`, use:
+
+```bash
+mkdir -p .claude/skills/audit-repo
+cp ./node_modules/claudex-setup/content/claude-code/audit-repo/SKILL.md .claude/skills/audit-repo/SKILL.md
+```
+
+If you are using `npx` only, copy the same file from the GitHub repo at `content/claude-code/audit-repo/SKILL.md`.
+
+The skill runs `npx claudex-setup --json`, summarizes the score, shows the top next actions, and points to the right next command without applying changes.
+
+## 85 Checks Across 14 Categories
+
+The exact applicable count can be lower on a given repo because stack-specific checks are skipped when they do not apply.
+
+| Category | Checks | Key items |
+|----------|-------:|-----------|
+| Memory | 8 | CLAUDE.md, architecture, conventions, imports |
+| Quality | 6 | verification loops, test/lint/build, testing strategy |
+| Git Safety | 6 | .gitignore, env protection, attribution, secret detection |
+| Workflow | 12 | commands, skills, rules, agents, snapshots |
+| Security | 7 | permissions, secrets, deny rules, sandbox awareness |
+| Automation | 7 | hook coverage, specificity, session and error hooks |
+| Design | 2 | frontend anti-slop guidance, styling signals |
+| DevOps | 5 | Docker, CI, Terraform, infra signals |
+| Hygiene | 8 | README, changelog, license, env example, version pinning |
+| Performance | 3 | context management, compaction, effort level |
+| MCP & Tools | 4 | servers, Context7, tool companions, env config |
+| Prompting | 6 | constraints, examples, negative rules, style guidance |
+| Features | 2 | channels, worktrees |
+| **Quality Deep** | **9** | **freshness, contradictions, deprecated patterns, maxTurns, $ARGUMENTS, hook specificity** |
+
+## Stack Detection
+
+Auto-detects and tailors output for 30 stacks:
+
+| | |
+|--|--|
+| **Frontend** | React, Vue, Angular, Next.js, Svelte, Astro |
+| **Backend** | Node.js, Python, Django, FastAPI, Express, NestJS, Spring Boot |
+| **Mobile** | React Native, Expo, Flutter, Swift, Kotlin |
+| **Systems** | Rust, Go, Java, Ruby, C++, Bazel, Deno, Bun |
+| **Language** | TypeScript |
+| **Infra** | Docker, Terraform, Kubernetes, Wrangler |
+
+## GitHub Action
+
+Add to `.github/workflows/claudex.yml`:
+
+```yaml
+name: CLAUDEX Audit
+on: [pull_request]
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DnaFin/claudex-setup@v1.16.1
+        with:
+          threshold: 50
+```
+
+## Badge
+
+Add a readiness badge to your README:
+
+```bash
+npx claudex-setup badge
+# Output: [![Claude Code Ready](https://img.shields.io/badge/...)](...)
+```
+
+## For Veteran Claude Code Users
+
+Already have a solid CLAUDE.md and hooks? Two things for you:
+
+### Deep Review (AI-powered)
+
+```bash
+npx claudex-setup deep-review
+```
+
+Claude reads your actual config and gives specific feedback: what's strong, what has issues, what's missing for your stack. This is an AI-assisted review, not a local heuristic audit. Your config goes to the Anthropic API only when you run this command; we do not receive it.
+
+Deep-review trust boundary:
+
+- sends only selected Claude-facing config surfaces: `CLAUDE.md`, settings, commands, agents, rules, hooks, and package scripts
+- truncates large files before sending
+- redacts embedded secrets before sending
+- treats embedded repo text as untrusted review data, not as instructions to follow
+- keeps all non-`deep-review` flows local
+
+### Quality-Deep Checks
+
+The v0.4.0 quality-deep checks catch what basic audits miss:
+
+| Check | What it catches |
+|-------|----------------|
+| **Freshness** | CLAUDE.md that doesn't mention modern features (hooks, skills, MCP) |
+| **Conciseness** | CLAUDE.md over 200 lines (wastes tokens every session) |
+| **Contradictions** | Conflicting rules ("always X" + "never X") |
+| **Hook specificity** | Hooks without matchers that fire on every tool call |
+| **Permission hygiene** | bypassPermissions still enabled in production |
+| **Command flexibility** | Commands without $ARGUMENTS (static, not reusable) |
+| **Agent limits** | Agents without maxTurns (can run forever) |
+| **Security workflow** | No /security-review in your process |
+| **Deprecated patterns** | Old model names, prefill, deprecated API formats |
+
+These checks evaluate **quality**, not just existence. A well-configured project with stale patterns will surface real improvements.
+
+## Privacy
+
+- **Zero dependencies** - nothing extra to audit
+- **Core flows run locally** - audit, setup, augment, plan, apply, governance, and benchmark run on your machine
+- **Deep review is opt-in** - only `deep-review` sends selected config to Anthropic or your local Claude Code session for analysis
+- **Deep review sanitizes before send** - selected snippets are truncated, secret-redacted, and wrapped as untrusted review data
+- **Benchmark uses an isolated temp copy** - your live repo is not touched
+- **Anonymous insights** - opt-in, no PII, no file contents (enable with `--insights`)
+- **MIT Licensed** - use anywhere
+
+## Backed by Research
+
+Every check traces to a verified technique from a systematic audit of:
+- All 73 official Claude Code documentation pages
+- 100+ community MCP servers verified via GitHub API
+- Anthropic blog posts and benchmark papers
+- 194 hands-on experiments with real evidence
+
+The catalog includes 1,107 entries (features, techniques, patterns, tools, stats, and known limitations) — not all are actionable checks. 948 were verified with real evidence. Continuously updated.
+
+**Note:** A hand-crafted CLAUDE.md that reflects your real conventions will always be better than a generated one. This tool is most useful for projects starting from zero, or as a checklist for what you might be missing.
+
+## Requirements
+
+- Node.js 18+
+- macOS, Linux, Windows
+- No global install (npx handles it)
+
+## License
+
+MIT