@nerviq/cli 0.0.1 → 0.9.0-beta.1

package/content/case-study-template.md

@@ -0,0 +1,91 @@
+# Case Study: [Project Name]
+
+## Overview
+
+| Field | Value |
+|-------|-------|
+| Project | [name] |
+| Repo type | [e.g., backend API, frontend SPA, monorepo, data pipeline] |
+| Team size | [e.g., solo, 3 developers, 15-person team] |
+| Prior Claude setup | [none / basic CLAUDE.md / mature .claude/ config] |
+| Claudex Setup version | [e.g., 1.9.0] |
+| Date | [YYYY-MM-DD] |
+
+## Before State
+
+**Audit score:** [X/100]
+**Organic score:** [X/100]
+
+What existed before running claudex-setup:
+- [ ] CLAUDE.md
+- [ ] .claude/settings.json
+- [ ] Custom commands
+- [ ] Rules
+- [ ] Hooks
+- [ ] Agents
+- [ ] MCP servers
+
+Key observations:
+- [What was good already]
+- [What was missing]
+- [What was risky or misconfigured]
+
+## What We Did
+
+**Mode used:** [discover / starter / augment / plan+apply / suggest-only]
+
+**Steps:**
+1. Ran `npx claudex-setup discover` to understand current state
+2. [Next step]
+3. [Next step]
+
+**Domain pack matched:** [e.g., backend-api]
+**MCP packs recommended:** [e.g., context7-docs, postgres-mcp]
+
+## Changes Applied
+
+| Change | Type | Risk | Applied? |
+|--------|------|------|----------|
+| [e.g., Created CLAUDE.md with architecture] | new file | low | yes |
+| [e.g., Added hooks for auto-lint] | new config | medium | yes |
+| [e.g., Added permission deny rules] | security | low | yes |
+
+**Strengths preserved:**
+- [What we explicitly kept unchanged]
+
+## After State
+
+**Audit score:** [X/100] (was [X/100])
+**Organic score:** [X/100] (was [X/100])
+**Score improvement:** +[X] points
+
+## Measured Impact
+
+| Metric | Before | After | Change |
+|--------|--------|-------|--------|
+| Audit score | X | X | +X |
+| Checks passing | X/84 | X/84 | +X |
+| Time to first productive session | Xm | Xm | -Xm |
+| [Other metric] | | | |
+
+## What Worked Well
+
+- [Specific thing that added clear value]
+- [Another]
+
+## What Could Be Better
+
+- [Specific improvement suggestion for the tool]
+- [Another]
+
+## Verdict
+
+**Would recommend:** [Yes / Yes with caveats / Not yet]
+
+**Best for:** [Who should try this based on our experience]
+
+**One-line summary:** [e.g., "Took our Claude setup from basic to production-ready in 15 minutes with zero breakage."]
+
+---
+
+*Generated with claudex-setup v[version]. Case study template from CLAUDEX.*

package/content/claims-governance.md

@@ -0,0 +1,37 @@
+# Claims Governance
+
+Use this checklist before publishing product-facing claims about Claudex Setup.
+
+## Allowed only with evidence
+
+- score delta claims
+- organic score delta claims
+- time-to-value claims
+- recommendation acceptance rate claims
+- reduction in manual corrections
+- benchmark outcomes on named repo types
+
+## Evidence standard
+
+Every claim should have:
+
+- a benchmark run or pilot report
+- the repo type or cohort it applies to
+- the date the evidence was collected
+- the exact metric definition
+- the comparison method (`before/after`, `control/pilot`, or `observed over time`)
+
+## Avoid
+
+- universal productivity multipliers
+- unsupported token savings claims
+- “works for every repo” language
+- suspiciously precise numbers without a method section
+- implying quality scores are objective truth rather than framework coverage
+
+## Safer phrasing
+
+- "In benchmark mode, this repo improved from 41/100 to 60/100."
+- "Starter-safe artifacts improved readiness on an isolated temp copy."
+- "Suggest-only mode gives mature teams a zero-write review path."
+- "Use governance mode to select permission profiles and inspect shipped hooks."

package/content/claude-code/audit-repo/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: audit-repo
+description: Run claudex-setup on the current repo and summarize the score, top gaps, and next command
+---
+
+Run `npx claudex-setup --json` in the current project directory and summarize the result.
+
+Your output should include:
+
+1. The overall score and organic score
+2. The top 3 next actions from `topNextActions`
+3. The suggested next command from `suggestedNextCommand`
+4. A short explanation of what the repo already does well if there are notable strengths
+
+Behavior rules:
+
+- If the user asks for the shortest version, run `npx claudex-setup --lite`
+- If the user wants deeper no-write analysis, run `npx claudex-setup augment --json`
+- If the score is below 50, explicitly recommend `npx claudex-setup setup`
+- Never apply changes automatically from this skill

package/content/claude-native-integration.md

@@ -0,0 +1,60 @@
+# Using claudex-setup from inside Claude Code
+
+## Skill: Audit Repo
+
+Add this to `.claude/skills/audit-repo.md` in any project:
+
+```markdown
+---
+name: audit-repo
+description: Run claudex-setup audit on the current project and show score + top gaps
+---
+
+Run `npx claudex-setup --json` on the current project directory.
+Parse the JSON output and present:
+1. Score X/100
+2. Top 3 critical/high gaps with fix descriptions
+3. Suggest next command based on score
+
+$ARGUMENTS — optional: --lite for quick scan
+```
+
+## Hook: Auto-audit on SessionStart
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "node -e \"try{const r=require('child_process').execSync('npx claudex-setup --json 2>/dev/null',{timeout:15000}).toString();const d=JSON.parse(r);if(d.score<50)console.log(JSON.stringify({systemMessage:'⚠️ Claude Code setup score: '+d.score+'/100. Consider running: npx claudex-setup --lite'}))}catch(e){console.log('{}')}\"",
+        "timeout": 20,
+        "statusMessage": "Checking Claude Code setup..."
+      }
+    ]
+  }
+}
+```
+
+## Agent: Setup Advisor
+
+Add to `.claude/agents/setup-advisor.md`:
+
+```markdown
+---
+name: setup-advisor
+description: Analyzes Claude Code setup and recommends improvements
+tools: [Bash, Read, Glob, Grep]
+model: haiku
+maxTurns: 10
+---
+
+You are a Claude Code setup advisor.
+
+1. Run `npx claudex-setup augment --json` on the current project
+2. Analyze gaps and strengths
+3. Recommend top 5 improvements with rationale
+4. If user approves, guide them through applying changes
+```

package/content/devto-article.json

@@ -0,0 +1,9 @@
+{
+  "article": {
+    "title": "Your Claude Code project scores 10/100. Here's how to fix it in 60 seconds.",
+    "published": false,
+    "tags": ["claude", "ai", "productivity", "devtools"],
+    "series": "Claude Code Optimization",
+    "body_markdown": "After cataloging **1,107 Claude Code entries** and verifying **948 with real evidence**, I found that most projects use barely 10% of what's available.\n\nI built a CLI that scores your project:\n\n```bash\nnpx claudex-setup\n```\n\nMost projects score **10-20 out of 100**. After running setup, they jump to **70+**.\n\n## The Top 10 Things You're Missing\n\n### 1. CLAUDE.md (Critical)\n\nClaude reads this file at the start of every session. Without it, Claude doesn't know your build commands, code style, or project rules.\n\nOur tool generates a smart CLAUDE.md that detects your framework, TypeScript config, and creates a Mermaid architecture diagram automatically.\n\n### 2. Mermaid Architecture Diagrams (73% Token Savings)\n\nA Mermaid diagram in CLAUDE.md gives Claude your project structure in a fraction of the tokens that prose requires.\n\n### 3. Hooks > CLAUDE.md Rules (100% vs 80%)\n\nCLAUDE.md instructions are advisory (~80% compliance). Hooks are deterministic (100%). Auto-lint after every edit. Every time.\n\n### 4. Custom Commands\n\nStop typing the same prompts. Create `/test`, `/deploy`, `/review` in `.claude/commands/`.\n\n### 5. Verification Loops (The #1 Best Practice)\n\n> *This is the single highest-leverage thing you can do.* — Anthropic Best Practices\n\nClaude performs dramatically better when it can verify its own work.\n\n### 6. XML Tags (30% Quality Boost)\n\nUse `<constraints>`, `<validation>` in CLAUDE.md for unambiguous instructions.\n\n### 7. Secrets Protection\n\nClaude Code loads `.env` automatically. Add deny rules to prevent reading sensitive files.\n\n### 8. /security-review\n\nBuilt-in OWASP Top 10 scanning. Most people don't know this command exists.\n\n### 9. Custom Agents\n\nSpecialized subagents: security-reviewer, test-writer in `.claude/agents/`.\n\n### 10. Skills (On-Demand Knowledge)\n\nReusable skills package expertise that Claude can load on demand.\n\n## Try It Now\n\n```bash\nnpx claudex-setup --lite       # Quick scan\nnpx claudex-setup              # Full audit\nnpx claudex-setup --snapshot   # Save evidence artifact\nnpx claudex-setup governance --out governance.md\n```\n\nFree, open source, zero dependencies.\n\n**GitHub:** [github.com/DnaFin/claudex-setup](https://github.com/DnaFin/claudex-setup)\n**npm:** [npmjs.com/package/claudex-setup](https://www.npmjs.com/package/claudex-setup)\n\n---\n\n*Built from a research catalog of 1,107 Claude Code entries, 948 verified with evidence.*"
+  }
+}

package/content/launch-posts.md

@@ -0,0 +1,226 @@
+# Launch Posts — Proof-Backed Distribution Assets
+
+**Status:** Complete — every asset below is anchored in measured proof, a canonical artifact, or a verified runtime surface  
+**Date:** 2026-04-03
+
+## Shared Proof Anchors
+
+Use these links as the canonical sources behind public claims:
+
+- Proof artifact index: https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md
+- CLAUDEX self-dogfood trace: https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/claudex-self-dogfood-proof-trace-2026-04-03.md
+- VTCLE case study: https://github.com/DnaFin/claudex/blob/main/research/case-study-vtcle-2026-04-03.md
+- Social case study: https://github.com/DnaFin/claudex/blob/main/research/case-study-social-2026-04-03.md
+- Polymiro case study: https://github.com/DnaFin/claudex/blob/main/research/case-study-polymiro-2026-04-03.md
+- Public proof metrics source: https://github.com/DnaFin/claudex/blob/main/research/claudex-proof-metrics-source-2026-04-03.md
+
+Measured-result boundary to preserve:
+
+- before/after scores were measured with `claudex-setup@1.10.3` on `2026-04-03`
+- current npm latest is `1.16.1`
+- current product surface is `85 checks`
+
+## Post 1: Reddit r/ClaudeAI
+
+**Title:** I built a CLI that audits your Claude Code setup — 85 checks, measured on 4 real repos
+
+**Body:**
+I built a zero-dependency CLI that audits how well a repo is set up for Claude Code.
+
+It checks `85` things across `CLAUDE.md`, hooks, commands, agents, skills, MCP config, permissions, diagrams, and verification loops.
+
+Measured on `2026-04-03` with `claudex-setup@1.10.3`:
+- CLAUDEX: `62 -> 90`
+- VTCLE: `46 -> 64`
+- Social: `40 -> 48`
+- Polymiro: `35 -> 48`
+
+```bash
+npx claudex-setup
+```
+
+It starts trust-first:
+- audit first
+- plan / suggest-only before writes
+- apply only what you approve
+- rollback artifacts for every applied batch
+
+Zero dependencies. No API keys. Runs local.
+
+GitHub: https://github.com/DnaFin/claudex-setup
+
+Proof and case studies:
+- https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md
+- https://github.com/DnaFin/claudex/blob/main/research/case-study-vtcle-2026-04-03.md
+- https://github.com/DnaFin/claudex/blob/main/research/case-study-social-2026-04-03.md
+- https://github.com/DnaFin/claudex/blob/main/research/case-study-polymiro-2026-04-03.md
+
+Would love feedback on what checks or rollout surfaces are still missing.
+
+**Evidence anchor:** proof artifact index + 3 external case studies + current proof source
+
+---
+
+## Post 2: Reddit r/ChatGPTCoding
+
+**Title:** Most Claude Code repos are missing the safety layer, not the model
+
+**Body:**
+The interesting problem with Claude Code is not "can it write code?".
+It's "is the repo actually set up so Claude can work safely and predictably?".
+
+I built `claudex-setup` to audit that surface:
+- `85` checks
+- zero dependencies
+- local-only by default
+- trust-first flow: audit -> plan -> apply -> rollback
+
+Measured on 4 real repos:
+- FastAPI repo: `46 -> 64`
+- React Native repo: `40 -> 48`
+- Python/Docker repo: `35 -> 48`
+- research engine repo: `62 -> 90`
+
+```bash
+npx claudex-setup
+```
+
+The most common misses were not exotic:
+- no deny rules
+- no secrets protection
+- no mermaid architecture
+- no hooks registered in settings
+
+Proof:
+https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md
+
+**Evidence anchor:** measured before/after traces + common gap summary from public proof set
+
+---
+
+## Post 3: Dev.to Article
+
+**Title:** What 4 Real Repos Taught Me About Claude Code Readiness
+
+**Body (excerpt):**
+I tested `claudex-setup` on 4 real repos and the pattern was clear:
+
+- the best teams still miss permission deny rules
+- mature repos often have hooks in files but not actually registered
+- non-standard settings formats are a real adoption trap
+- shared `settings.json` matters more than personal local overrides
+
+Measured on `2026-04-03` with `claudex-setup@1.10.3`:
+- CLAUDEX: `62 -> 90`
+- VTCLE: `46 -> 64`
+- Social: `40 -> 48`
+- Polymiro: `35 -> 48`
+
+The product today is strongest as:
+
+`audit -> plan -> safe apply -> governance -> benchmark`
+
+Not a code generator. Not an MCP installer. A trust layer for Claude Code repos.
+
+Proof packet:
+https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md
+
+**Evidence anchor:** proof artifact index + case-study docs + current proof source
+
+---
+
+## Post 4: Twitter/X Thread
+
+**Tweet 1:**
+I built a zero-dependency CLI that audits Claude Code readiness across `85` checks.
+
+Measured on 4 real repos:
+- `62 -> 90`
+- `46 -> 64`
+- `40 -> 48`
+- `35 -> 48`
+
+`npx claudex-setup`
+
+Proof: github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md
+
+**Tweet 2:**
+The most common misses were boring and important:
+- no deny rules
+- no secrets protection
+- no mermaid diagram
+- no hooks registered in settings
+
+It is much more "trust layer" than "AI magic".
+
+**Tweet 3:**
+What it does well today:
+- audit first
+- suggest / plan before writes
+- apply selectively
+- emit rollback artifacts
+- benchmark on isolated copy
+
+**Tweet 4:**
+Best result so far:
+- CLAUDEX self-dogfood: `62 -> 90`
+
+Best external proof:
+- VTCLE: `46 -> 64`
+
+Case studies:
+- github.com/DnaFin/claudex/blob/main/research/case-study-vtcle-2026-04-03.md
+- github.com/DnaFin/claudex/blob/main/research/case-study-social-2026-04-03.md
+- github.com/DnaFin/claudex/blob/main/research/case-study-polymiro-2026-04-03.md
+
+**Tweet 5:**
+Measured results were captured on `claudex-setup@1.10.3` on `2026-04-03`.
+Current npm latest is `1.16.1`, so exact scores can move slightly, but the proof packet is explicit about that boundary.
+
+**Evidence anchor:** proof artifact index + per-repo traces
+
+---
+
+## Post 5: Hacker News (Show HN)
+
+**Title:** Show HN: claudex-setup — audit Claude Code readiness with 85 checks
+
+**Body:**
+I built a CLI that audits how well a repo is set up for Claude Code.
+
+This is not a code-quality linter and not an MCP installer.
+It focuses on Claude workflow quality:
+- `CLAUDE.md`
+- hooks
+- commands
+- agents
+- skills
+- MCP config
+- permissions / deny rules
+- diagrams
+- verification loops
+
+Core workflow:
+- `npx claudex-setup`
+- `npx claudex-setup suggest-only`
+- `npx claudex-setup plan`
+- `npx claudex-setup apply`
+- `npx claudex-setup benchmark`
+
+Measured on 4 real repos on `2026-04-03` with `claudex-setup@1.10.3`:
+- CLAUDEX: `62 -> 90`
+- VTCLE: `46 -> 64`
+- Social: `40 -> 48`
+- Polymiro: `35 -> 48`
+
+Trust decisions that mattered:
+- zero dependencies
+- audit before write
+- rollback artifacts
+- cross-platform Node hooks
+- explicit proof packets instead of vague claims
+
+Proof packet:
+https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md
+
+**Evidence anchor:** proof artifact index + current npm proof source

package/content/pilot-rollout-kit.md

@@ -0,0 +1,30 @@
+# Pilot Rollout Kit
+
+## Suggested pilot shape
+
+1. Choose 1-2 repos with active owners and low blast radius.
+2. Run `discover`, `suggest-only`, and `governance` before any write flow.
+3. Pick one permission profile and document why it fits the pilot.
+4. Run `benchmark` to capture a baseline and expected value.
+5. Use `plan` and selective `apply` for the first write batch.
+
+## Approval checklist
+
+- Engineering owner approves scope.
+- Security owner approves permission profile and hooks.
+- Pilot owner records success metrics.
+- Rollback expectations are documented before apply.
+
+## Success metrics
+
+- readiness score delta
+- organic score delta
+- number of proposal bundles accepted
+- rollback-free apply rate
+- time to first useful Claude workflow
+
+## Rollback expectations
+
+- every apply run must produce a rollback artifact
+- rejected starter artifacts are deleted using the rollback manifest
+- rollback decisions are logged in the activity trail

package/content/release-checklist.md

@@ -0,0 +1,31 @@
+# claudex-setup Release Checklist
+
+Use this before tagging or publishing a release.
+
+## Code And Packaging
+
+- bump `package.json` version intentionally
+- update `CHANGELOG.md` with the shipped changes
+- run `npm test`
+- run `npm pack --dry-run`
+
+## Product Surface Consistency
+
+- verify `README.md` reflects the current CLI surface
+- verify `docs/index.html` reflects the current CLI surface
+- verify new flags and commands appear in `--help`
+- verify proof numbers and public claims match the current state
+
+## Trust And Governance
+
+- run `npx claudex-setup --snapshot` on the repo itself
+- run `npx claudex-setup governance --out governance.md`
+- verify MCP package names and env preflight behavior for changed packs
+- verify no recommendation regressions on known scenarios
+
+## Release Readiness
+
+- confirm npm publish target and account are correct
+- confirm git branch / commit matches the intended release
+- confirm any new templates or content files are included in the package
+- capture one final note about what changed and what still remains intentionally deferred

package/package.json

@@ -1,8 +1,57 @@
 {
   "name": "@nerviq/cli",
-  "version": "0.0.1",
-  "description": "The intelligent nervous system for AI coding agents — audit, align, amplify",
-  "keywords": ["ai", "agent", "governance", "harmony", "audit", "nerviq"],
+  "version": "0.9.0-beta.1",
+  "description": "The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.",
+  "main": "src/index.js",
+  "bin": {
+    "nerviq": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "content",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "build": "npm pack --dry-run",
+    "test": "node test/run.js",
+    "test:jest": "jest",
+    "test:coverage": "jest --coverage",
+    "test:all": "node test/run.js && node test/check-matrix.js && node test/codex-check-matrix.js && node test/golden-matrix.js && node test/codex-golden-matrix.js && node test/security-tests.js && jest"
+  },
+  "keywords": [
+    "nerviq",
+    "ai-agents",
+    "agent-governance",
+    "agent-config",
+    "harmony",
+    "synergy",
+    "audit",
+    "claude",
+    "codex",
+    "gemini",
+    "copilot",
+    "cursor",
+    "windsurf",
+    "aider",
+    "developer-tools",
+    "cli",
+    "mcp",
+    "multi-agent"
+  ],
+  "author": "Nerviq <hello@nerviq.net>",
   "license": "AGPL-3.0",
-  "repository": "https://github.com/nerviq/nerviq"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nerviq/nerviq.git"
+  },
+  "homepage": "https://nerviq.net",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0"
+  }
 }