claudex-setup 1.10.2 → 1.10.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [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.10.2] - 2026-04-02
 
 ### Fixed
@@ -11,6 +26,12 @@
 - 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

package/README.md

@@ -1,19 +1,36 @@
 # claudex-setup
 
-> Score your project 0-100 for Claude Code readiness. Discover gaps, export proposal bundles, apply safe starter changes with rollback, and benchmark the impact without touching your live repo.
+> Score your repo's Claude Code setup against 62 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
+
+- 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
 ```
@@ -41,18 +58,35 @@ No install. No config. No dependencies.
      CI pipeline configured
      → Add .github/workflows/ for automated testing
 
-  ⚡ Best next fixes
+  ⚡ 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/62 checks passing
-  Run npx claudex-setup setup to create a starter-safe baseline
+  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 |
@@ -84,6 +118,8 @@ No install. No config. No dependencies.
 | `--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 |
+| `--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) |
@@ -141,6 +177,7 @@ Use `governance` when the question is "can we pilot this safely?" instead of "wh
 
 ```bash
 npx claudex-setup governance
+npx claudex-setup governance --out governance.md
 ```
 
 It exposes:
@@ -152,6 +189,8 @@ It exposes:
 - 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.
@@ -181,6 +220,31 @@ Benchmark mode:
 - 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.
+
+## 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.
+
 ## 62 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.
@@ -227,7 +291,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.10.2
+      - uses: DnaFin/claudex-setup@v1.10.3
         with:
           threshold: 50
 ```
@@ -288,7 +352,7 @@ Every check traces to a verified technique from a systematic audit of:
 - 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. 954 were verified with real evidence. Continuously updated.
+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.
 

package/bin/cli.js

@@ -4,8 +4,9 @@ const { audit } = require('../src/audit');
 const { setup } = require('../src/setup');
 const { analyzeProject, printAnalysis, exportMarkdown } = require('../src/analyze');
 const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBundle, printApplyResult } = require('../src/plans');
-const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile } = require('../src/governance');
+const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile, renderGovernanceMarkdown } = require('../src/governance');
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
+const { writeSnapshotArtifact } = require('../src/activity');
 const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -133,6 +134,7 @@ const HELP = `
 
   Usage:
     npx claudex-setup                  Run audit on current directory
+    npx claudex-setup --lite           Run the quick-scan beginner view
     npx claudex-setup discover         Discover the highest-value improvements
     npx claudex-setup audit            Same as above
     npx claudex-setup starter          Alias for setup
@@ -156,6 +158,8 @@ const HELP = `
     --only A,B      Limit plan/apply to selected proposal ids or technique keys
     --profile NAME  Choose permission profile (read-only, suggest-only, safe-write, power-user, internal-research)
     --mcp-pack A,B  Merge named MCP packs into generated settings (e.g. context7-docs,next-devtools)
+    --snapshot      Save a normalized snapshot 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          Output as JSON (for CI pipelines)
@@ -166,8 +170,12 @@ const HELP = `
 
   Examples:
     npx claudex-setup
+    npx claudex-setup --lite
+    npx claudex-setup --snapshot
     npx claudex-setup augment
+    npx claudex-setup augment --snapshot
     npx claudex-setup suggest-only --json
+    npx claudex-setup governance --snapshot
     npx claudex-setup plan --out claudex-plan.json
     npx claudex-setup plan --profile safe-write
     npx claudex-setup setup --mcp-pack context7-docs
@@ -210,6 +218,8 @@ async function main() {
     verbose: flags.includes('--verbose'),
     json: flags.includes('--json'),
     auto: flags.includes('--auto'),
+    lite: flags.includes('--lite'),
+    snapshot: flags.includes('--snapshot'),
     dryRun: flags.includes('--dry-run'),
     threshold: parsed.threshold !== null ? Number(parsed.threshold) : null,
     out: parsed.out,
@@ -295,6 +305,9 @@ async function main() {
       return; // keep process alive for http
     } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
       const report = await analyzeProject({ ...options, mode: normalizedCommand });
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, normalizedCommand, report, {
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out && !options.json) {
         const fs = require('fs');
         const md = exportMarkdown(report);
@@ -302,6 +315,11 @@ async function main() {
         console.log(`\n  Report exported to ${options.out}\n`);
       }
       printAnalysis(report, options);
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
     } else if (normalizedCommand === 'plan') {
       const bundle = await buildProposalBundle(options);
       let artifact = null;
@@ -320,10 +338,34 @@ async function main() {
       const result = await applyProposalBundle(options);
       printApplyResult(result, options);
     } else if (normalizedCommand === 'governance') {
+      const fs = require('fs');
+      const path = require('path');
       const summary = getGovernanceSummary();
+      if (options.out) {
+        fs.mkdirSync(path.dirname(options.out), { recursive: true });
+        const content = path.extname(options.out).toLowerCase() === '.md'
+          ? renderGovernanceMarkdown(summary)
+          : JSON.stringify(summary, null, 2);
+        fs.writeFileSync(options.out, content, 'utf8');
+      }
       printGovernanceSummary(summary, options);
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'governance', summary, {
+        sourceCommand: normalizedCommand,
+      }) : null;
+      if (options.out && !options.json) {
+        console.log(`  Governance report written to ${options.out}`);
+        console.log('');
+      }
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
     } else if (normalizedCommand === 'benchmark') {
       const report = await runBenchmark(options);
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'benchmark', report, {
+        sourceCommand: normalizedCommand,
+      }) : null;
       if (options.out) {
         writeBenchmarkReport(report, options.out);
       }
@@ -332,6 +374,11 @@ async function main() {
         console.log(`  Benchmark report written to ${options.out}`);
         console.log('');
       }
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
     } else if (normalizedCommand === 'deep-review') {
       const { deepReview } = require('../src/deep-review');
       await deepReview(options);
@@ -345,6 +392,14 @@ async function main() {
       await setup(options);
     } else {
       const result = await audit(options);
+      const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, 'audit', result, {
+        sourceCommand: normalizedCommand,
+      }) : null;
+      if (snapshot && !options.json) {
+        console.log(`  Snapshot saved: ${snapshot.relativePath}`);
+        console.log(`  Snapshot index: ${snapshot.indexPath}`);
+        console.log('');
+      }
       if (options.threshold !== null && result.score < options.threshold) {
         if (!options.json) {
           console.error(`  Threshold failed: score ${result.score}/100 is below required ${options.threshold}/100.\n`);

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/58 | X/58 | +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/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,160 @@
+# Launch Posts — Ready to Publish
+
+## Post 1: Reddit r/ClaudeAI
+
+**Title:** I built a tool that audits your project for Claude Code optimization — scores you 0-100
+
+**Body:**
+After cataloging 1,107 Claude Code entries and verifying 948 of them with evidence, I built a CLI that checks if your project is actually set up to get the most out of Claude Code.
+
+Most projects score around 10-20/100. After running setup, they jump to 70+.
+
+```
+npx claudex-setup
+```
+
+It checks for: CLAUDE.md, hooks, custom commands, skills, agents, Mermaid diagrams, XML tags, path rules, MCP config, permissions, and more.
+
+Then `npx claudex-setup setup` auto-creates everything that's missing, tailored to your stack (React, Python, TypeScript, etc).
+
+Zero dependencies. No API keys. Runs entirely local.
+
+GitHub: https://github.com/DnaFin/claudex-setup
+
+Would love feedback!
+
+---
+
+## Post 2: Reddit r/ChatGPTCoding
+
+**Title:** Your Claude Code project is probably running at 10% efficiency. Here's how to check.
+
+**Body:**
+I spent weeks cataloging every Claude Code feature, technique, and best practice — 1,107 total, 948 verified with real evidence.
+
+Turns out most projects are missing basic stuff that makes a huge difference:
+- No CLAUDE.md (Claude doesn't know your project conventions)
+- No hooks (no auto-lint, no auto-test)
+- No custom commands (repeating the same prompts manually)
+- No Mermaid diagrams (wasting 73% more tokens on prose descriptions)
+
+Built a quick checker:
+```
+npx claudex-setup
+```
+
+Scores your project 0-100, tells you exactly what to fix, and can auto-apply everything.
+
+Free, open source, zero dependencies: https://github.com/DnaFin/claudex-setup
+
+---
+
+## Post 3: Dev.to Article
+
+**Title:** 1,107 Claude Code Entries: What I Learned Building the Most Comprehensive Catalog
+
+**Body (excerpt):**
+I set out to catalog every single Claude Code capability, technique, and best practice. After repeated research cycles, I have 1,107 entries — 948 verified with real evidence.
+
+Here are the top 10 things most developers are missing:
+
+1. **CLAUDE.md** — Claude reads this at the start of every session. Without it, Claude doesn't know your build commands, code style, or project rules.
+
+2. **Mermaid diagrams** — A Mermaid architecture diagram saves 73% tokens compared to describing your project in prose.
+
+3. **Hooks** — Auto-lint after every edit. Auto-test before every commit. Hooks fire 100% of the time, CLAUDE.md rules fire ~80%.
+
+4. **Custom commands** — `/test`, `/deploy`, `/review` — package your repeated workflows.
+
+5. **Verification loops** — Tell Claude how to verify its own work. Include test commands in CLAUDE.md.
+
+6. **Path-specific rules** — Different conventions for frontend vs backend files.
+
+7. **XML tags** — `<constraints>`, `<validation>` in CLAUDE.md = unambiguous instructions.
+
+8. **Custom agents** — Security reviewer, test writer — specialized subagents for focused tasks.
+
+9. **Skills** — Domain-specific workflows that load on demand, not every session.
+
+10. **MCP servers** — Connect Claude to your database, ticket system, Slack.
+
+I packaged this into a CLI that checks your project:
+```
+npx claudex-setup
+```
+
+Full catalog: https://github.com/DnaFin/claudex-setup
+
+---
+
+## Post 4: Twitter/X Thread
+
+**Tweet 1:**
+I cataloged 1,107 Claude Code entries and verified 948 of them with evidence.
+
+Most projects use less than 5% of what Claude Code can do.
+
+Here's a free tool that checks your project and tells you exactly what's missing:
+
+npx claudex-setup
+
+Thread 🧵👇
+
+**Tweet 2:**
+The #1 thing you're probably missing: CLAUDE.md
+
+It's a file Claude reads at the start of every session. Without it, Claude doesn't know your:
+- Build commands
+- Code style
+- Testing framework
+- Project architecture
+
+Takes 2 minutes to create. Impact: massive.
+
+**Tweet 3:**
+#2: Mermaid diagrams in CLAUDE.md
+
+A few hundred tokens of Mermaid syntax conveys what takes thousands of tokens in prose.
+
+73% token savings = faster responses, lower cost, better context.
+
+**Tweet 4:**
+#3: Hooks > CLAUDE.md rules
+
+CLAUDE.md instructions = ~80% compliance
+Hooks = 100% enforcement
+
+Auto-lint after edits. Block commits without tests. Prevent force-push.
+
+Hooks are deterministic. Instructions are advisory.
+
+**Tweet 5:**
+Want to check your project in 10 seconds?
+
+npx claudex-setup
+
+Scores 0-100. Shows what's missing. Auto-fixes with `setup`.
+
+Free. Open source. Zero dependencies.
+
+https://github.com/DnaFin/claudex-setup
+
+---
+
+## Post 5: Hacker News (Show HN)
+
+**Title:** Show HN: claudex-setup – Audit any project for Claude Code optimization (1,107 entries)
+
+**Body:**
+I built a CLI tool that scores your project against Claude Code best practices.
+
+After researching 1,107 entries (948 verified with evidence), most projects score 10-20 out of 100 because they're missing basic optimizations like CLAUDE.md files, hooks, custom commands, and architecture diagrams.
+
+npx claudex-setup → audit (0-100 score)
+npx claudex-setup setup → auto-fix
+
+Detects your stack (React, Python, TS, Rust, Go, etc) and tailors recommendations.
+
+Zero dependencies, no API keys, runs locally.
+
+https://github.com/DnaFin/claudex-setup

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,13 +1,14 @@
 {
   "name": "claudex-setup",
-  "version": "1.10.2",
-  "description": "Audit and improve Claude Code readiness with discover, plan, apply, governance, and benchmark workflows.",
+  "version": "1.10.3",
+  "description": "Score your repo's Claude Code setup against 62 checks. See gaps, apply fixes selectively with rollback, govern hooks and permissions, and benchmark impact — without breaking existing config.",
   "main": "src/index.js",
   "bin": {
     "claudex-setup": "bin/cli.js"
   },
   "files": [
     "bin",
+    "content",
     "src",
     "README.md",
     "CHANGELOG.md"

package/src/activity.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { version } = require('../package.json');
 
 function timestampId() {
   return new Date().toISOString().replace(/[:.]/g, '-');
@@ -9,9 +10,11 @@ function ensureArtifactDirs(dir) {
   const root = path.join(dir, '.claude', 'claudex-setup');
   const activityDir = path.join(root, 'activity');
   const rollbackDir = path.join(root, 'rollbacks');
+  const snapshotDir = path.join(root, 'snapshots');
   fs.mkdirSync(activityDir, { recursive: true });
   fs.mkdirSync(rollbackDir, { recursive: true });
-  return { root, activityDir, rollbackDir };
+  fs.mkdirSync(snapshotDir, { recursive: true });
+  return { root, activityDir, rollbackDir, snapshotDir };
 }
 
 function writeJson(filePath, payload) {
@@ -53,8 +56,116 @@ function writeRollbackArtifact(dir, payload) {
   };
 }
 
+function summarizeSnapshot(snapshotKind, payload) {
+  if (snapshotKind === 'audit') {
+    return {
+      score: payload.score,
+      organicScore: payload.organicScore,
+      passed: payload.passed,
+      failed: payload.failed,
+      checkCount: payload.checkCount,
+      suggestedNextCommand: payload.suggestedNextCommand,
+      topActionKeys: Array.isArray(payload.topNextActions)
+        ? payload.topNextActions.slice(0, 3).map(item => item.key)
+        : [],
+    };
+  }
+
+  if (snapshotKind === 'augment' || snapshotKind === 'suggest-only') {
+    return {
+      score: payload.projectSummary?.score,
+      organicScore: payload.projectSummary?.organicScore,
+      maturity: payload.projectSummary?.maturity,
+      domains: payload.projectSummary?.domains || [],
+      topActionKeys: Array.isArray(payload.topNextActions)
+        ? payload.topNextActions.slice(0, 3).map(item => item.key)
+        : [],
+    };
+  }
+
+  if (snapshotKind === 'benchmark') {
+    return {
+      beforeScore: payload.before?.score,
+      afterScore: payload.after?.score,
+      scoreDelta: payload.delta?.score,
+      organicDelta: payload.delta?.organicScore,
+      decisionGuidance: payload.executiveSummary?.decisionGuidance || null,
+    };
+  }
+
+  if (snapshotKind === 'governance') {
+    return {
+      permissionProfiles: Array.isArray(payload.permissionProfiles) ? payload.permissionProfiles.length : 0,
+      hooks: Array.isArray(payload.hookRegistry) ? payload.hookRegistry.length : 0,
+      policyPacks: Array.isArray(payload.policyPacks) ? payload.policyPacks.length : 0,
+      domainPacks: Array.isArray(payload.domainPacks) ? payload.domainPacks.length : 0,
+      mcpPacks: Array.isArray(payload.mcpPacks) ? payload.mcpPacks.length : 0,
+    };
+  }
+
+  return {};
+}
+
+function updateSnapshotIndex(snapshotDir, record) {
+  const indexPath = path.join(snapshotDir, 'index.json');
+  let entries = [];
+
+  if (fs.existsSync(indexPath)) {
+    try {
+      entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+      if (!Array.isArray(entries)) {
+        entries = [];
+      }
+    } catch {
+      entries = [];
+    }
+  }
+
+  entries.push(record);
+  fs.writeFileSync(indexPath, JSON.stringify(entries, null, 2), 'utf8');
+}
+
+function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
+  const id = timestampId();
+  const { snapshotDir } = ensureArtifactDirs(dir);
+  const filePath = path.join(snapshotDir, `${id}-${snapshotKind}.json`);
+  const summary = summarizeSnapshot(snapshotKind, payload);
+  const envelope = {
+    schemaVersion: 1,
+    artifactType: 'snapshot',
+    snapshotKind,
+    id,
+    createdAt: new Date().toISOString(),
+    generatedBy: `claudex-setup@${version}`,
+    directory: dir,
+    summary,
+    ...meta,
+    payload,
+  };
+
+  writeJson(filePath, envelope);
+
+  const record = {
+    id,
+    snapshotKind,
+    createdAt: envelope.createdAt,
+    relativePath: path.relative(dir, filePath),
+    summary,
+  };
+  updateSnapshotIndex(snapshotDir, record);
+
+  return {
+    id,
+    filePath,
+    relativePath: path.relative(dir, filePath),
+    indexPath: path.relative(dir, path.join(snapshotDir, 'index.json')),
+    summary,
+  };
+}
+
 module.exports = {
   ensureArtifactDirs,
   writeActivityArtifact,
   writeRollbackArtifact,
+  writeSnapshotArtifact,
 };

package/src/analyze.js

@@ -351,7 +351,7 @@ async function analyzeProject(options) {
     },
     strengthsPreserved: toStrengths(auditResult.results),
     gapsIdentified: toGaps(auditResult.results),
-    topNextActions: auditResult.quickWins,
+    topNextActions: auditResult.topNextActions || auditResult.quickWins,
     recommendedImprovements: toRecommendations(auditResult),
     recommendedDomainPacks,
     recommendedMcpPacks,
@@ -417,7 +417,14 @@ function printAnalysis(report, options = {}) {
     console.log(c('  Top 5 Next Actions', 'magenta'));
     report.topNextActions.slice(0, 5).forEach((item, index) => {
       console.log(`  ${index + 1}. ${item.name}`);
-      console.log(c(`     ${item.fix}`, 'dim'));
+      console.log(c(`     Why: ${item.why || item.fix}`, 'dim'));
+      if (Array.isArray(item.signals) && item.signals.length > 0) {
+        console.log(c(`     Trace: ${item.signals.join(' | ')}`, 'dim'));
+      }
+      if (item.risk || item.confidence) {
+        console.log(c(`     Risk: ${item.risk || 'low'} | Confidence: ${item.confidence || 'medium'}`, 'dim'));
+      }
+      console.log(c(`     Fix: ${item.fix}`, 'dim'));
     });
     console.log('');
   }
@@ -500,7 +507,15 @@ function exportMarkdown(report) {
     lines.push('## Top Next Actions');
     lines.push('');
     report.topNextActions.slice(0, 5).forEach((item, index) => {
-      lines.push(`${index + 1}. **${item.name}** — ${item.fix}`);
+      lines.push(`${index + 1}. **${item.name}**`);
+      lines.push(`   - Why: ${item.why || item.fix}`);
+      if (Array.isArray(item.signals) && item.signals.length > 0) {
+        lines.push(`   - Trace: ${item.signals.join(' | ')}`);
+      }
+      if (item.risk || item.confidence) {
+        lines.push(`   - Risk / Confidence: ${item.risk || 'low'} / ${item.confidence || 'medium'}`);
+      }
+      lines.push(`   - Fix: ${item.fix}`);
     });
     lines.push('');
   }

package/src/audit.js

@@ -30,10 +30,60 @@ function progressBar(score, max = 100, width = 20) {
 }
 
 const IMPACT_ORDER = { critical: 3, high: 2, medium: 1, low: 0 };
+const CATEGORY_MODULES = {
+  memory: 'CLAUDE.md',
+  quality: 'verification',
+  git: 'safety',
+  workflow: 'commands-agents-skills',
+  security: 'permissions',
+  automation: 'hooks',
+  design: 'design-rules',
+  devops: 'ci-devops',
+  hygiene: 'project-hygiene',
+  performance: 'context-management',
+  tools: 'mcp-tools',
+  prompting: 'prompt-structure',
+  features: 'modern-claude-features',
+  'quality-deep': 'quality-deep',
+};
+const ACTION_RATIONALES = {
+  noBypassPermissions: 'bypassPermissions skips the main safety layer. Explicit allow and deny rules create safer autonomy.',
+  secretsProtection: 'Without secret protection, Claude can accidentally inspect sensitive files and leak them into outputs.',
+  permissionDeny: 'Deny rules are the strongest way to prevent dangerous reads and destructive operations.',
+  settingsPermissions: 'Explicit permission settings make the workflow safer, more governable, and easier to review.',
+  testCommand: 'Without a test command, Claude cannot verify that its changes actually work before handoff.',
+  lintCommand: 'Without a lint command, Claude will miss formatting and style regressions that teams expect to catch automatically.',
+  buildCommand: 'Without a build command, compile and packaging failures stay invisible until later in the workflow.',
+  ciPipeline: 'CI is what turns a local setup improvement into a repeatable team-wide standard.',
+  securityReview: 'If you do not wire in security review guidance, high-risk changes are easier to ship without the right scrutiny.',
+  skills: 'Skills package reusable expertise so Claude does not need the same context re-explained every session.',
+  multipleAgents: 'Specialized agents unlock role-based work such as security review, implementation, and QA in parallel.',
+  multipleMcpServers: 'A richer MCP surface gives Claude access to live tools and documentation instead of stale assumptions.',
+  roleDefinition: 'A clear role definition calibrates how Claude thinks, explains, and validates work in this repo.',
+  importSyntax: 'Imported modules keep CLAUDE.md maintainable as the workflow grows more sophisticated.',
+  claudeMd: 'CLAUDE.md is the foundation of project-specific context. Without it, Claude starts every task half-blind.',
+  hooks: 'Hooks enforce the rules programmatically, which is much more reliable than relying on instructions alone.',
+  pathRules: 'Path-specific rules help Claude behave differently in different parts of the repo without global noise.',
+  context7Mcp: 'Live documentation reduces version drift and cuts down on confident but outdated answers.',
+};
 
-function getQuickWins(failed) {
+function riskFromImpact(impact) {
+  if (impact === 'critical') return 'high';
+  if (impact === 'high') return 'medium';
+  return 'low';
+}
+
+function confidenceFromImpact(impact) {
+  return impact === 'critical' || impact === 'high' ? 'high' : 'medium';
+}
+
+function getPrioritizedFailed(failed) {
   const prioritized = failed.filter(r => !(r.category === 'hygiene' && r.impact === 'low'));
-  const pool = prioritized.length > 0 ? prioritized : failed;
+  return prioritized.length > 0 ? prioritized : failed;
+}
+
+function getQuickWins(failed) {
+  const pool = getPrioritizedFailed(failed);
 
   return [...pool]
     .sort((a, b) => {
@@ -45,6 +95,87 @@ function getQuickWins(failed) {
     .slice(0, 3);
 }
 
+function buildTopNextActions(failed, limit = 5) {
+  const pool = getPrioritizedFailed(failed);
+
+  return [...pool]
+    .sort((a, b) => {
+      const impactA = IMPACT_ORDER[a.impact] ?? 0;
+      const impactB = IMPACT_ORDER[b.impact] ?? 0;
+      if (impactA !== impactB) return impactB - impactA;
+      return (a.fix || '').length - (b.fix || '').length;
+    })
+    .slice(0, limit)
+    .map(({ key, name, impact, fix, category }) => ({
+      key,
+      name,
+      impact,
+      category,
+      module: CATEGORY_MODULES[category] || category,
+      fix,
+      why: ACTION_RATIONALES[key] || fix,
+      risk: riskFromImpact(impact),
+      confidence: confidenceFromImpact(impact),
+      signals: [
+        `failed-check:${key}`,
+        `impact:${impact}`,
+        `category:${category}`,
+      ],
+    }));
+}
+
+function inferSuggestedNextCommand(result) {
+  const actionKeys = new Set((result.topNextActions || []).map(item => item.key));
+
+  if (result.failed === 0) {
+    return 'npx claudex-setup augment';
+  }
+
+  if (
+    result.score < 50 ||
+    actionKeys.has('claudeMd') ||
+    actionKeys.has('hooks') ||
+    actionKeys.has('settingsPermissions') ||
+    actionKeys.has('permissionDeny')
+  ) {
+    return 'npx claudex-setup setup';
+  }
+
+  if (result.score < 80) {
+    return 'npx claudex-setup suggest-only';
+  }
+
+  return 'npx claudex-setup augment';
+}
+
+function printLiteAudit(result, dir) {
+  console.log('');
+  console.log(colorize('  claudex-setup quick scan', 'bold'));
+  console.log(colorize('  ═══════════════════════════════════════', 'dim'));
+  console.log(colorize(`  Scanning: ${dir}`, 'dim'));
+  console.log('');
+  console.log(`  Score: ${colorize(`${result.score}/100`, 'bold')}`);
+  console.log('');
+
+  if (result.failed === 0) {
+    console.log(colorize('  Your Claude setup looks solid.', 'green'));
+    console.log(`  Next: ${colorize(result.suggestedNextCommand, 'bold')}`);
+    console.log('');
+    return;
+  }
+
+  console.log(colorize('  Top 3 things to fix right now:', 'magenta'));
+  console.log('');
+  result.liteSummary.topNextActions.forEach((item, index) => {
+    console.log(`  ${index + 1}. ${colorize(item.name, 'bold')}`);
+    console.log(colorize(`     Why: ${item.why}`, 'dim'));
+    console.log(colorize(`     Fix: ${item.fix}`, 'dim'));
+  });
+  console.log('');
+  console.log(`  Ready? Run: ${colorize(result.suggestedNextCommand, 'bold')}`);
+  console.log('');
+}
+
 async function audit(options) {
   const silent = options.silent || false;
   const ctx = new ProjectContext(options.dir);
@@ -91,6 +222,7 @@ async function audit(options) {
   const organicEarned = organicPassed.reduce((sum, r) => sum + (weights[r.impact] || 5), 0);
   const organicScore = maxScore > 0 ? Math.round((organicEarned / maxScore) * 100) : 0;
   const quickWins = getQuickWins(failed);
+  const topNextActions = buildTopNextActions(failed, 5);
   const result = {
     score,
     organicScore,
@@ -102,6 +234,12 @@ async function audit(options) {
     stacks,
     results,
     quickWins: quickWins.map(({ key, name, impact, fix, category }) => ({ key, name, impact, category, fix })),
+    topNextActions,
+  };
+  result.suggestedNextCommand = inferSuggestedNextCommand(result);
+  result.liteSummary = {
+    topNextActions: topNextActions.slice(0, 3),
+    nextCommand: result.suggestedNextCommand,
   };
 
   // Silent mode: skip all output, just return result
@@ -119,6 +257,12 @@ async function audit(options) {
     return result;
   }
 
+  if (options.lite) {
+    printLiteAudit(result, options.dir);
+    sendInsights(result);
+    return result;
+  }
+
   // Display results
   console.log('');
   console.log(colorize('  claudex-setup audit', 'bold'));
@@ -178,13 +322,16 @@ async function audit(options) {
     console.log('');
   }
 
-  // Quick wins
-  if (failed.length > 0) {
-    console.log(colorize('  ⚡ Best next fixes', 'magenta'));
-    for (let i = 0; i < quickWins.length; i++) {
-      const r = quickWins[i];
-      console.log(`     ${i + 1}. ${colorize(r.name, 'bold')}`);
-      console.log(colorize(`        → ${r.fix}`, 'dim'));
+  // Top next actions
+  if (topNextActions.length > 0) {
+    console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
+    for (let i = 0; i < topNextActions.length; i++) {
+      const item = topNextActions[i];
+      console.log(`     ${i + 1}. ${colorize(item.name, 'bold')}`);
+      console.log(colorize(`        Why: ${item.why}`, 'dim'));
+      console.log(colorize(`        Trace: ${item.signals.join(' | ')}`, 'dim'));
+      console.log(colorize(`        Risk: ${item.risk} | Confidence: ${item.confidence}`, 'dim'));
+      console.log(colorize(`        Fix: ${item.fix}`, 'dim'));
     }
     console.log('');
   }
@@ -194,7 +341,7 @@ async function audit(options) {
   console.log(`  ${colorize(`${passed.length}/${applicable.length}`, 'bold')} checks passing${skipped.length > 0 ? colorize(` (${skipped.length} not applicable)`, 'dim') : ''}`);
 
   if (failed.length > 0) {
-    console.log(`  Run ${colorize('npx claudex-setup setup', 'bold')} to create starter-safe defaults`);
+    console.log(`  Next command: ${colorize(result.suggestedNextCommand, 'bold')}`);
   }
 
   console.log('');

package/src/claudex-sync.json

@@ -1,11 +1,7 @@
 {
   "synced_from": "claudex",
-  "synced_at": "2026-03-31T19:30:00Z",
+  "synced_at": "2026-04-02T15:12:04Z",
   "total_items": 1107,
   "tested": 948,
-  "last_id": 1157,
-  "domain_packs": 16,
-  "mcp_packs": 26,
-  "anti_patterns": 53,
-  "contract_version": "1.0.0"
+  "last_id": 1157
 }

package/src/governance.js

@@ -386,6 +386,74 @@ function printGovernanceSummary(summary, options = {}) {
   console.log('');
 }
 
+function renderGovernanceMarkdown(summary) {
+  const lines = [
+    '# Claudex Setup Governance Report',
+    '',
+    'This report summarizes the shipped governance surface for Claude Code rollout, review, and pilot approval.',
+    '',
+    '## Permission Profiles',
+  ];
+
+  for (const profile of summary.permissionProfiles) {
+    lines.push(`- **${profile.label}** \`${profile.key}\` | risk: \`${profile.risk}\` | defaultMode: \`${profile.defaultMode}\``);
+    lines.push(`  - Use when: ${profile.useWhen}`);
+    lines.push(`  - Behavior: ${profile.behavior}`);
+    if (Array.isArray(profile.deny) && profile.deny.length > 0) {
+      lines.push(`  - Deny rules: ${profile.deny.join(', ')}`);
+    }
+  }
+
+  lines.push('', '## Hook Registry');
+  for (const hook of summary.hookRegistry) {
+    lines.push(`- **${hook.key}** \`${hook.triggerPoint}${hook.matcher ? ` ${hook.matcher}` : ''}\` | risk: \`${hook.risk}\``);
+    lines.push(`  - File: ${hook.file}`);
+    lines.push(`  - Purpose: ${hook.purpose}`);
+    lines.push(`  - Dry run: ${hook.dryRunExample}`);
+    lines.push(`  - Rollback: ${hook.rollbackPath}`);
+  }
+
+  lines.push('', '## Policy Packs');
+  for (const pack of summary.policyPacks) {
+    lines.push(`- **${pack.label}**`);
+    lines.push(`  - Use when: ${pack.useWhen}`);
+    lines.push(`  - Modules: ${pack.modules.join(', ')}`);
+  }
+
+  lines.push('', `## Domain Packs (${summary.domainPacks.length})`);
+  for (const pack of summary.domainPacks) {
+    lines.push(`- **${pack.label}**: ${pack.useWhen}`);
+  }
+
+  lines.push('', `## MCP Packs (${summary.mcpPacks.length})`);
+  for (const pack of summary.mcpPacks) {
+    lines.push(`- **${pack.label}**: ${Object.keys(pack.servers).join(', ')}`);
+  }
+
+  lines.push('', '## Pilot Rollout Kit', '### Recommended Scope');
+  for (const item of summary.pilotRolloutKit.recommendedScope) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push('', '### Approvals');
+  for (const item of summary.pilotRolloutKit.approvals) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push('', '### Success Metrics');
+  for (const item of summary.pilotRolloutKit.successMetrics) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push('', '### Rollback Expectations');
+  for (const item of summary.pilotRolloutKit.rollbackExpectations) {
+    lines.push(`- ${item}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
 module.exports = {
   PERMISSION_PROFILES,
   getPermissionProfile,
@@ -394,4 +462,5 @@ module.exports = {
   buildSettingsForProfile,
   getGovernanceSummary,
   printGovernanceSummary,
+  renderGovernanceMarkdown,
 };

package/src/insights.js

@@ -87,7 +87,8 @@ function sendInsights(auditResult) {
  */
 function getLocalInsights(auditResult) {
   const { results } = auditResult;
-  const failed = results.filter(r => !r.passed);
+  const applicable = results.filter(r => r.passed !== null);
+  const failed = applicable.filter(r => r.passed === false);
 
   // Top 3 most impactful fixes
   const impactOrder = { critical: 3, high: 2, medium: 1 };
@@ -98,7 +99,7 @@ function getLocalInsights(auditResult) {
 
   // Score breakdown by category
   const categories = {};
-  for (const r of results) {
+  for (const r of applicable) {
     const cat = r.category || 'other';
     if (!categories[cat]) categories[cat] = { passed: 0, total: 0 };
     categories[cat].total++;

package/src/techniques.js

@@ -1,6 +1,6 @@
 /**
  * CLAUDEX Technique Database
- * Curated from 1,107 verified techniques, filtered to actionable setup recommendations.
+ * Curated from 1107 verified techniques, filtered to actionable setup recommendations.
  * Each technique includes: what to check, how to fix, impact level.
  */