claudex-setup 1.16.0 → 1.16.1

package/README.md

@@ -1,6 +1,6 @@
 # claudex-setup
 
-> Score your repo's Claude Code setup against 84 checks. See what's missing, apply only what you approve with rollback, and benchmark the impact — without breaking existing config.
+> 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)
@@ -51,7 +51,11 @@ Tested on 4 real projects — not demos:
 
 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. Full 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)
+> Scores measured with claudex-setup@1.10.3 on 2026-04-03. Current npm latest: 1.16.0, 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
 
@@ -91,7 +95,7 @@ Most common gaps found: missing secrets protection, no deny rules, no mermaid di
       design: none (0/2)
      devops: none (0/4)
 
-  29/84 checks passing
+  29/85 checks passing
   Next command: npx claudex-setup setup
 ```
 
@@ -107,7 +111,7 @@ That prints a compact top-3 quick scan with one clear next command.
 
 | Command | What it does |
 |---------|-------------|
-| `npx claudex-setup` | **Discover** - Score 0-100 against 84 checks |
+| `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 |
@@ -119,11 +123,14 @@ That prints a compact top-3 quick scan with one clear next command.
 | `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 |
+| `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 deep-review` | **Deep Review** - AI-powered config analysis (needs API key) |
+| `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 |
 
+> Note: the `feedback` command is currently validated on the main working tree for the next release. If your installed npm build does not expose it yet, use the rest of the trust-first flow and pick it up on the next publish.
+
 ### Options
 
 | Flag | Effect |
@@ -134,6 +141,10 @@ That prints a compact top-3 quick scan with one clear next command.
 | `--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 |
@@ -246,6 +257,19 @@ 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.
+
+If your currently installed npm build does not expose `feedback` yet, treat this as next-release behavior rather than current npm-latest behavior.
+
+`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.
@@ -261,26 +285,26 @@ If you are using `npx` only, copy the same file from the GitHub repo at `content
 
 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.
 
-## 84 Checks Across 14 Categories
+## 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 |
-| Quality | 7 | verification loops, self-correction |
-| Git Safety | 5 | hooks, force-push protection |
-| Workflow | 8 | commands, skills, rules, agents |
-| Security | 6 | permissions, secrets, deny rules |
-| Automation | 5 | PreToolUse, PostToolUse, SessionStart |
-| Design | 4 | Mermaid, XML tags, structured prompts |
-| DevOps | 6 | Docker, CI, Terraform, K8s, pipelines |
-| Hygiene | 7 | .gitignore, cleanup, structure |
-| Performance | 3 | context management, compaction |
-| MCP | 3 | servers, Context7, integrations |
-| Prompting | 5 | constraints, validation, patterns, style |
-| Features | 3 | /security-review, Channels, modern features |
-| **Quality Deep** | **14** | **freshness, contradictions, deprecated patterns, maxTurns, $ARGUMENTS, hook specificity** |
+| 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
 
@@ -307,7 +331,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.15.1
+      - uses: DnaFin/claudex-setup@v1.16.0
         with:
           threshold: 50
 ```
@@ -333,6 +357,14 @@ 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:
@@ -355,7 +387,8 @@ These checks evaluate **quality**, not just existence. A well-configured project
 
 - **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 for analysis
+- **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

package/bin/cli.js

@@ -6,7 +6,7 @@ const { analyzeProject, printAnalysis, exportMarkdown } = require('../src/analyz
 const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBundle, printApplyResult } = require('../src/plans');
 const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile, renderGovernanceMarkdown } = require('../src/governance');
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
-const { writeSnapshotArtifact } = require('../src/activity');
+const { writeSnapshotArtifact, recordRecommendationOutcome, formatRecommendationOutcomeSummary, getRecommendationOutcomeSummary } = require('../src/activity');
 const { version } = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -18,8 +18,9 @@ const COMMAND_ALIASES = {
   starter: 'setup',
   suggest: 'suggest-only',
   gov: 'governance',
+  outcome: 'feedback',
 };
-const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'scan', 'feedback', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -62,13 +63,19 @@ function parseArgs(rawArgs) {
   let profile = 'safe-write';
   let mcpPacks = [];
   let requireChecks = [];
+  let feedbackKey = null;
+  let feedbackStatus = null;
+  let feedbackEffect = null;
+  let feedbackNotes = null;
+  let feedbackSource = null;
+  let feedbackScoreDelta = null;
   let commandSet = false;
   let extraArgs = [];
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require') {
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require' || arg === '--key' || arg === '--status' || arg === '--effect' || arg === '--notes' || arg === '--source' || arg === '--score-delta') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -80,6 +87,12 @@ function parseArgs(rawArgs) {
       if (arg === '--profile') profile = value.trim();
       if (arg === '--mcp-pack') mcpPacks = value.split(',').map(item => item.trim()).filter(Boolean);
       if (arg === '--require') requireChecks = value.split(',').map(item => item.trim()).filter(Boolean);
+      if (arg === '--key') feedbackKey = value.trim();
+      if (arg === '--status') feedbackStatus = value.trim();
+      if (arg === '--effect') feedbackEffect = value.trim();
+      if (arg === '--notes') feedbackNotes = value;
+      if (arg === '--source') feedbackSource = value.trim();
+      if (arg === '--score-delta') feedbackScoreDelta = value.trim();
       i++;
       continue;
     }
@@ -119,6 +132,36 @@ function parseArgs(rawArgs) {
       continue;
     }
 
+    if (arg.startsWith('--key=')) {
+      feedbackKey = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--status=')) {
+      feedbackStatus = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--effect=')) {
+      feedbackEffect = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--notes=')) {
+      feedbackNotes = arg.split('=').slice(1).join('=');
+      continue;
+    }
+
+    if (arg.startsWith('--source=')) {
+      feedbackSource = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--score-delta=')) {
+      feedbackScoreDelta = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
     if (arg.startsWith('--')) {
       flags.push(arg);
       continue;
@@ -134,7 +177,7 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, extraArgs };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks, feedbackKey, feedbackStatus, feedbackEffect, feedbackNotes, feedbackSource, feedbackScoreDelta, extraArgs };
 }
 
 const HELP = `
@@ -166,8 +209,9 @@ const HELP = `
     npx claudex-setup benchmark        Before/after in isolated temp copy
     npx claudex-setup deep-review      AI-powered config review (opt-in, uses API)
     npx claudex-setup interactive      Step-by-step guided wizard
-    npx claudex-setup watch            Live monitoring on config changes
+    npx claudex-setup watch            Live monitoring on config changes with cross-platform watch fallback
     npx claudex-setup badge            Generate shields.io badge markdown
+    npx claudex-setup feedback         Record recommendation outcomes or show local outcome summary
 
   Options:
     --threshold N   Exit with code 1 if score is below N (useful for CI)
@@ -177,6 +221,12 @@ 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)
+    --key NAME      Recommendation key for feedback logging (e.g. permissionDeny)
+    --status VALUE  Feedback status: accepted, rejected, deferred
+    --effect VALUE  Feedback effect: positive, neutral, negative
+    --notes TEXT    Short notes to store with a feedback event
+    --source NAME   Source label for feedback event (default: manual-cli)
+    --score-delta N Optional observed score delta tied to the outcome
     --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
@@ -203,6 +253,8 @@ const HELP = `
     npx claudex-setup apply --profile power-user --only claude-md,hooks
     npx claudex-setup governance --json
     npx claudex-setup benchmark --out benchmark.md
+    npx claudex-setup feedback
+    npx claudex-setup feedback --key permissionDeny --status accepted --effect positive --score-delta 12
     npx claudex-setup --json --threshold 60
     npx claudex-setup setup --auto
     npx claudex-setup interactive
@@ -439,6 +491,41 @@ async function main() {
         console.log('  Insights request timed out. Run locally: npx claudex-setup');
       });
       return; // keep process alive for http
+    } else if (normalizedCommand === 'feedback') {
+      if (parsed.feedbackKey) {
+        if (!parsed.feedbackStatus) {
+          console.error('\n  Error: feedback logging requires --status when --key is provided.\n');
+          process.exit(1);
+        }
+        const artifact = recordRecommendationOutcome(options.dir, {
+          key: parsed.feedbackKey,
+          status: parsed.feedbackStatus,
+          effect: parsed.feedbackEffect || 'neutral',
+          notes: parsed.feedbackNotes || '',
+          source: parsed.feedbackSource || 'manual-cli',
+          scoreDelta: parsed.feedbackScoreDelta !== null ? Number(parsed.feedbackScoreDelta) : null,
+        });
+        const summary = getRecommendationOutcomeSummary(options.dir);
+        if (options.json) {
+          console.log(JSON.stringify({ artifact, summary }, null, 2));
+        } else {
+          console.log('');
+          console.log(`  Feedback recorded for ${parsed.feedbackKey}`);
+          console.log(`  Artifact: ${artifact.relativePath}`);
+          console.log('');
+          console.log(formatRecommendationOutcomeSummary(options.dir));
+          console.log('');
+        }
+      } else {
+        if (options.json) {
+          console.log(JSON.stringify(getRecommendationOutcomeSummary(options.dir), null, 2));
+        } else {
+          console.log('');
+          console.log(formatRecommendationOutcomeSummary(options.dir));
+          console.log('');
+        }
+      }
+      process.exit(0);
     } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
       const report = await analyzeProject({ ...options, mode: normalizedCommand });
       const snapshot = options.snapshot ? writeSnapshotArtifact(options.dir, normalizedCommand, report, {

package/content/launch-posts.md

@@ -1,159 +1,226 @@
-# Launch Posts — Ready to Publish
+# 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.0`
+- current product surface is `85 checks`
 
 ## Post 1: Reddit r/ClaudeAI
 
-**Title:** I built a tool that audits your project for Claude Code optimization — scores you 0-100
+**Title:** I built a CLI that audits your Claude Code setup — 85 checks, measured on 4 real repos
 
 **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. It runs 84 checks across CLAUDE.md, hooks, commands, agents, diagrams, and more.
+I built a zero-dependency CLI that audits how well a repo is set up for Claude Code.
 
-I tested it on 4 real repos. A FastAPI marketing engine went from 46 to 64. A React Native social app went from 40 to 48. A Polymiro project jumped from 35 to 48. The CLAUDEX catalog repo itself: 62 to 90.
+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
 ```
 
-Then `npx claudex-setup setup` auto-creates everything that's missing, tailored to your stack (React, Python, TypeScript, etc).
+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 entirely local.
+Zero dependencies. No API keys. Runs local.
 
 GitHub: https://github.com/DnaFin/claudex-setup
 
-Would love feedback!
+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:** Your Claude Code project is probably running at 10% efficiency. Here's how to check.
+**Title:** Most Claude Code repos are missing the safety layer, not the model
 
 **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)
-
-I tested 4 real repos with 84 checks. Before optimization: scores ranged from 35 to 62. After: 48 to 90. A VTCLE FastAPI project jumped from 46→64 just from adding missing hooks and commands.
-
-```
+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
 ```
 
-Scores your project 0-100, tells you exactly what to fix, and can auto-apply everything.
+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
 
-Free, open source, zero dependencies: https://github.com/DnaFin/claudex-setup
+**Evidence anchor:** measured before/after traces + common gap summary from public proof set
 
 ---
 
 ## Post 3: Dev.to Article
 
-**Title:** 1,107 Claude Code Entries: What I Learned Building the Most Comprehensive Catalog
+**Title:** What 4 Real Repos Taught Me About Claude Code Readiness
 
 **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. I packaged this into an 84-check CLI audit and tested it on 4 real projects — scores before optimization ranged from 35 to 62, and after: 48 to 90.
+I tested `claudex-setup` on 4 real repos and the pattern was clear:
 
-Here are the top 10 things most developers are missing:
+- 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
 
-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.
+Measured on `2026-04-03` with `claudex-setup@1.10.3`:
+- CLAUDEX: `62 -> 90`
+- VTCLE: `46 -> 64`
+- Social: `40 -> 48`
+- Polymiro: `35 -> 48`
 
-2. **Mermaid diagrams** — A Mermaid architecture diagram saves 73% tokens compared to describing your project in prose.
+The product today is strongest as:
 
-3. **Hooks** — Auto-lint after every edit. Auto-test before every commit. Hooks fire 100% of the time, CLAUDE.md rules fire ~80%.
+`audit -> plan -> safe apply -> governance -> benchmark`
 
-4. **Custom commands** — `/test`, `/deploy`, `/review` — package your repeated workflows.
+Not a code generator. Not an MCP installer. A trust layer for Claude Code repos.
 
-5. **Verification loops** — Tell Claude how to verify its own work. Include test commands in CLAUDE.md.
+Proof packet:
+https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.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
+**Evidence anchor:** proof artifact index + case-study docs + current proof source
 
 ---
 
 ## 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.
+I built a zero-dependency CLI that audits Claude Code readiness across `85` checks.
 
-Tested on 4 real repos — a React Native app scored 40, a FastAPI engine scored 46. After auto-setup: 48 and 64. Here's the free 84-check audit:
+Measured on 4 real repos:
+- `62 -> 90`
+- `46 -> 64`
+- `40 -> 48`
+- `35 -> 48`
 
-npx claudex-setup
+`npx claudex-setup`
 
-Thread 🧵👇
+Proof: github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md
 
 **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
+The most common misses were boring and important:
+- no deny rules
+- no secrets protection
+- no mermaid diagram
+- no hooks registered in settings
 
-Takes 2 minutes to create. Impact: massive.
+It is much more "trust layer" than "AI magic".
 
 **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.
+What it does well today:
+- audit first
+- suggest / plan before writes
+- apply selectively
+- emit rollback artifacts
+- benchmark on isolated copy
 
 **Tweet 4:**
-#3: Hooks > CLAUDE.md rules
-
-CLAUDE.md instructions = ~80% compliance
-Hooks = 100% enforcement
+Best result so far:
+- CLAUDEX self-dogfood: `62 -> 90`
 
-Auto-lint after edits. Block commits without tests. Prevent force-push.
+Best external proof:
+- VTCLE: `46 -> 64`
 
-Hooks are deterministic. Instructions are advisory.
+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:**
-Want to check your project in 10 seconds?
+Measured results were captured on `claudex-setup@1.10.3` on `2026-04-03`.
+Current npm latest is `1.16.0`, so exact scores can move slightly, but the proof packet is explicit about that boundary.
 
-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
+**Evidence anchor:** proof artifact index + per-repo traces
 
 ---
 
 ## Post 5: Hacker News (Show HN)
 
-**Title:** Show HN: claudex-setup – Audit any project for Claude Code optimization (1,107 entries)
+**Title:** Show HN: claudex-setup — audit Claude Code readiness with 85 checks
 
 **Body:**
-I built a CLI tool that scores your project against Claude Code best practices.
-
-After researching 1,107 entries (948 verified with evidence), I tested 4 real repos with 84 checks. Scores before optimization: 35–62. After auto-setup: 48–90. The biggest jump was a research catalog repo going from 62 to 90.
-
-npx claudex-setup → audit (84 checks, 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
+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