claudex-setup 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [1.9.0] - 2026-03-31
+
+### Added
+- 3 new domain packs: `monorepo`, `mobile`, `regulated-lite` (7→10 total)
+- 3 new MCP packs: `github-mcp`, `postgres-mcp`, `memory-mcp` (2→5 total)
+- smart MCP pack recommendation based on detected domain packs
+- `suggest-only --out report.md` exports full analysis as shareable markdown
+- `why` explanations for all strengths preserved (20+ specific reasons)
+- `why` explanations for all gap findings (12+ specific reasons)
+- 5 new hooks in governance registry: duplicate-id-check, injection-defense, trust-drift-check, session-init, protect-catalog
+- case study template in `content/case-study-template.md`
+- hook risk level display in governance output (color-coded low/medium/high)
+
+### Fixed
+- **Settings hierarchy bug**: `noBypassPermissions` and `secretsProtection` checks now correctly read `.claude/settings.json` before `.claude/settings.local.json`, so personal maintainer overrides no longer fail the shared audit
+- domain pack detection now handles monorepo (nx.json, turbo.json, lerna.json, workspaces), mobile (React Native, Flutter, iOS/Android dirs), and regulated repos (SECURITY.md, compliance dirs)
+
+### Changed
+- strengths preserved section now shows 8 items (was 6) with specific value explanations
+- claudex-sync.json updated with domain pack, MCP pack, and anti-pattern counts
+
+## [1.8.0] - 2026-03-31
+
+### Added
+- domain pack recommendations for backend, frontend, data, infra, OSS, and enterprise-governed repos
+- MCP pack recommendations and merge support for `context7-docs` and `next-devtools`
+- workflow-evidence coverage in benchmark reports
+- runtime settings overlays so `apply --plan` still respects current `--profile` and `--mcp-pack` flags
+
+### Changed
+- benchmark now respects the selected profile and MCP pack options during isolated-copy runs
+- governance and suggest-only outputs now expose domain packs and MCP packs directly
+- README and docs clarify the local-vs-opt-in-network boundary for core flows vs `deep-review`
+- audit output now frames `setup` as starter-safe generation instead of an automatic full fix
+
 ## [1.7.0] - 2026-03-31
 
 ### Added

package/LICENSE

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

package/README.md

@@ -10,9 +10,10 @@
 
 ```bash
 npx claudex-setup              # Audit your project (10 seconds)
-npx claudex-setup setup        # Auto-fix everything
+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 benchmark    # Measure before/after in an isolated temp copy
 npx claudex-setup --threshold 60   # Fail CI if score is below 60
 ```
@@ -48,15 +49,15 @@ No install. No config. No dependencies.
       design: none (0/2)
      devops: none (0/4)
 
-  29/63 checks passing
-  Run npx claudex-setup setup to fix
+  29/62 checks passing
+  Run npx claudex-setup setup to create a starter-safe baseline
 ```
 
 ## All Commands
 
 | Command | What it does |
 |---------|-------------|
-| `npx claudex-setup` | **Discover** - Score 0-100 against 63 checks |
+| `npx claudex-setup` | **Discover** - Score 0-100 against 62 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 |
@@ -81,6 +82,8 @@ No install. No config. No dependencies.
 | `--out FILE` | Write JSON or markdown output to a file |
 | `--plan FILE` | Load a previously exported plan file |
 | `--only A,B` | Limit plan/apply to selected proposal ids |
+| `--profile NAME` | Choose a permission profile for write-capable flows |
+| `--mcp-pack A,B` | Merge named MCP packs into generated or patched settings |
 | `--dry-run` | Preview apply without writing files |
 | `--verbose` | Show all recommendations (not just critical/high) |
 | `--json` | Machine-readable JSON output (for CI) |
@@ -121,7 +124,7 @@ Each proposal bundle includes:
 
 - trigger reasons tied to failed checks
 - file previews and diff-style output
-- `create` vs `manual-review` classification
+- `create`, `patch`, or `manual-review` classification
 - risk/confidence labels
 
 Apply only the bundles you want:
@@ -130,7 +133,7 @@ Apply only the bundles you want:
 npx claudex-setup apply --plan claudex-plan.json --only claude-md,hooks
 ```
 
-`apply` creates rollback manifests and activity artifacts under `.claude/claudex-setup/`, so every applied batch has a paper trail and a delete-based rollback path.
+`apply` creates rollback manifests and activity artifacts under `.claude/claudex-setup/`, so every applied batch has a paper trail and a create-or-patch rollback path.
 
 ## Governance And Pilot Readiness
 
@@ -145,8 +148,24 @@ It exposes:
 - permission profiles: `read-only`, `suggest-only`, `safe-write`, `power-user`, `internal-research`
 - hook registry with trigger point, purpose, side effects, risk, and rollback path
 - policy packs for baseline engineering, security-sensitive repos, OSS, and regulated-lite teams
+- domain packs for backend, frontend, data, infra, OSS, and enterprise-governed repos
+- MCP packs for live docs and framework-aware tooling such as Context7 and Next.js devtools
 - a pilot rollout kit with scope, approvals, success metrics, and rollback expectations
 
+## Domain Packs And MCP Packs
+
+`augment` and `suggest-only` now recommend repo-shaped guidance instead of giving every project the same advice.
+
+- domain packs identify the repo shape: `backend-api`, `frontend-ui`, `data-pipeline`, `infra-platform`, `oss-library`, `enterprise-governed`
+- MCP packs recommend current-tooling companions: `context7-docs` for live docs, `next-devtools` for Next.js repos
+- write-capable flows can merge MCP packs directly into `.claude/settings.json`
+
+```bash
+npx claudex-setup suggest-only --json
+npx claudex-setup setup --mcp-pack context7-docs
+npx claudex-setup apply --plan claudex-plan.json --only hooks --mcp-pack context7-docs,next-devtools
+```
+
 ## Benchmark And Evidence
 
 Use `benchmark` to measure the impact of starter-safe improvements without modifying your working repo:
@@ -160,9 +179,11 @@ Benchmark mode:
 - runs a baseline audit on your repo
 - copies the repo to an isolated temp workspace
 - applies starter-safe artifacts only in the copy
-- reruns the audit and emits before/after deltas, a case-study summary, and an executive recommendation
+- reruns the audit and emits before/after deltas, workflow-evidence coverage, a case-study summary, and an executive recommendation
+
+## 62 Checks Across 14 Categories
 
-## 63 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 |
 |----------|-------:|-----------|
@@ -206,7 +227,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@main
+      - uses: DnaFin/claudex-setup@v1.9.0
         with:
           threshold: 50
 ```
@@ -230,7 +251,7 @@ Already have a solid CLAUDE.md and hooks? Two things for you:
 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. Not pattern matching — real analysis. Your config goes to Anthropic API only, we never see it.
+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.
 
 ### Quality-Deep Checks
 
@@ -252,8 +273,9 @@ These checks evaluate **quality**, not just existence. A well-configured project
 
 ## Privacy
 
-- **Zero dependencies** - nothing to audit
-- **Runs 100% locally** - no cloud processing
+- **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
 - **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

@@ -2,9 +2,9 @@
 
 const { audit } = require('../src/audit');
 const { setup } = require('../src/setup');
-const { analyzeProject, printAnalysis } = require('../src/analyze');
+const { analyzeProject, printAnalysis, exportMarkdown } = require('../src/analyze');
 const { buildProposalBundle, printProposalBundle, writePlanFile, applyProposalBundle, printApplyResult } = require('../src/plans');
-const { getGovernanceSummary, printGovernanceSummary } = require('../src/governance');
+const { getGovernanceSummary, printGovernanceSummary, ensureWritableProfile } = require('../src/governance');
 const { runBenchmark, printBenchmark, writeBenchmarkReport } = require('../src/benchmark');
 const { version } = require('../package.json');
 
@@ -58,12 +58,14 @@ function parseArgs(rawArgs) {
   let out = null;
   let planFile = null;
   let only = [];
+  let profile = 'safe-write';
+  let mcpPacks = [];
   let commandSet = false;
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only') {
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -72,6 +74,8 @@ function parseArgs(rawArgs) {
       if (arg === '--out') out = value;
       if (arg === '--plan') planFile = value;
       if (arg === '--only') only = value.split(',').map(item => item.trim()).filter(Boolean);
+      if (arg === '--profile') profile = value.trim();
+      if (arg === '--mcp-pack') mcpPacks = value.split(',').map(item => item.trim()).filter(Boolean);
       i++;
       continue;
     }
@@ -96,6 +100,16 @@ function parseArgs(rawArgs) {
       continue;
     }
 
+    if (arg.startsWith('--profile=')) {
+      profile = arg.split('=').slice(1).join('=').trim();
+      continue;
+    }
+
+    if (arg.startsWith('--mcp-pack=')) {
+      mcpPacks = arg.split('=').slice(1).join('=').split(',').map(item => item.trim()).filter(Boolean);
+      continue;
+    }
+
     if (arg.startsWith('--')) {
       flags.push(arg);
       continue;
@@ -109,13 +123,13 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks };
 }
 
 const HELP = `
   claudex-setup v${version}
   Audit and optimize any project for Claude Code.
-  Backed by research from 1,107 cataloged Claude Code entries.
+  Backed by CLAUDEX research and evidence.
 
   Usage:
     npx claudex-setup                  Run audit on current directory
@@ -140,6 +154,8 @@ const HELP = `
     --out FILE      Write JSON or markdown output to a file
     --plan FILE     Load a previously exported plan file
     --only A,B      Limit plan/apply to selected proposal ids 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)
     --dry-run       Preview apply without writing files
     --verbose       Show all recommendations (not just critical/high)
     --json          Output as JSON (for CI pipelines)
@@ -153,7 +169,11 @@ const HELP = `
     npx claudex-setup augment
     npx claudex-setup suggest-only --json
     npx claudex-setup plan --out claudex-plan.json
+    npx claudex-setup plan --profile safe-write
+    npx claudex-setup setup --mcp-pack context7-docs
     npx claudex-setup apply --plan claudex-plan.json --only hooks,commands
+    npx claudex-setup apply --mcp-pack context7-docs,next-devtools --only hooks
+    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 --json --threshold 60
@@ -195,6 +215,8 @@ async function main() {
     out: parsed.out,
     planFile: parsed.planFile,
     only: parsed.only,
+    profile: parsed.profile,
+    mcpPacks: parsed.mcpPacks,
     dir: process.cwd()
   };
 
@@ -219,6 +241,15 @@ async function main() {
     process.exit(1);
   }
 
+  if (['setup', 'apply', 'benchmark'].includes(normalizedCommand)) {
+    try {
+      ensureWritableProfile(options.profile, normalizedCommand, options.dryRun);
+    } catch (err) {
+      console.error(`\n  Error: ${err.message}\n`);
+      process.exit(1);
+    }
+  }
+
   try {
     if (normalizedCommand === 'badge') {
       const { getBadgeMarkdown } = require('../src/badge');
@@ -264,6 +295,12 @@ async function main() {
       return; // keep process alive for http
     } else if (normalizedCommand === 'augment' || normalizedCommand === 'suggest-only') {
       const report = await analyzeProject({ ...options, mode: normalizedCommand });
+      if (options.out && !options.json) {
+        const fs = require('fs');
+        const md = exportMarkdown(report);
+        fs.writeFileSync(options.out, md, 'utf8');
+        console.log(`\n  Report exported to ${options.out}\n`);
+      }
       printAnalysis(report, options);
     } else if (normalizedCommand === 'plan') {
       const bundle = await buildProposalBundle(options);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claudex-setup",
-  "version": "1.7.0",
-  "description": "Audit and optimize any project for Claude Code. Powered by 1107 verified techniques.",
+  "version": "1.9.0",
+  "description": "Audit and improve Claude Code readiness with discover, plan, apply, governance, and benchmark workflows.",
   "main": "src/index.js",
   "bin": {
     "claudex-setup": "bin/cli.js"
@@ -14,6 +14,7 @@
   ],
   "scripts": {
     "start": "node bin/cli.js",
+    "build": "npm pack --dry-run",
     "test": "node test/run.js"
   },
   "keywords": [

package/src/analyze.js

@@ -7,6 +7,8 @@ const path = require('path');
 const { audit } = require('./audit');
 const { ProjectContext } = require('./context');
 const { STACKS } = require('./techniques');
+const { detectDomainPacks } = require('./domain-packs');
+const { recommendMcpPacks } = require('./mcp-packs');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -168,6 +170,30 @@ function moduleFromCategory(category) {
   return map[category] || category;
 }
 
+const STRENGTH_REASONS = {
+  claudeMd: 'Foundation of Claude workflow. Every session benefits from this.',
+  mermaidArchitecture: 'Architecture diagram saves 73% tokens vs prose — high-value asset.',
+  verificationLoop: 'Claude can self-verify, catching errors before human review.',
+  hooks: 'Automated enforcement (100% vs 80% from instructions alone).',
+  hooksInSettings: 'Hook registration in settings ensures consistent automation.',
+  preToolUseHook: 'Pre-execution validation adds a safety layer.',
+  postToolUseHook: 'Post-execution automation catches issues immediately.',
+  sessionStartHook: 'Session initialization ensures consistent starting state.',
+  customCommands: 'Reusable workflows encoded as one-liner commands.',
+  settingsPermissions: 'Explicit permissions prevent accidental dangerous operations.',
+  permissionDeny: 'Deny rules block risky operations at the system level.',
+  pathRules: 'Scoped rules ensure different code areas get appropriate guidance.',
+  fewShotExamples: 'Code examples guide Claude to match your conventions.',
+  constraintBlocks: 'XML constraint blocks improve rule adherence by 40%.',
+  xmlTags: 'Structured prompt sections improve consistency.',
+  context7Mcp: 'Real-time docs eliminate version-mismatch hallucinations.',
+  mcpServers: 'External tool integration extends Claude capabilities.',
+  compactionAwareness: 'Context management keeps sessions efficient.',
+  agents: 'Specialized agents delegate complex tasks effectively.',
+  noSecretsInClaude: 'No secrets in config — good security hygiene.',
+  gitIgnoreEnv: 'Environment files are properly excluded from git.',
+};
+
 function toStrengths(results) {
   return results
     .filter(r => r.passed === true)
@@ -175,15 +201,30 @@ function toStrengths(results) {
       const order = { critical: 3, high: 2, medium: 1, low: 0 };
       return (order[b.impact] || 0) - (order[a.impact] || 0);
     })
-    .slice(0, 6)
+    .slice(0, 8)
     .map(r => ({
       key: r.key,
       name: r.name,
       category: r.category,
-      note: `Already present and worth preserving: ${r.name}.`,
+      why: STRENGTH_REASONS[r.key] || `Already configured and working: ${r.name}.`,
     }));
 }
 
+const GAP_REASONS = {
+  noBypassPermissions: 'bypassPermissions skips all safety checks. Use explicit allow rules for control without risk.',
+  secretsProtection: 'Without deny rules for .env, Claude can read secrets and potentially expose them in outputs.',
+  testCommand: 'Without a test command, Claude cannot verify its changes work before you review them.',
+  lintCommand: 'Without a lint command, Claude may produce inconsistently formatted code.',
+  buildCommand: 'Without a build command, Claude cannot catch compilation errors early.',
+  ciPipeline: 'CI ensures every change is automatically tested. Without it, bugs reach main branch faster.',
+  securityReview: 'Claude Code has built-in OWASP Top 10 scanning. Not using it leaves vulnerabilities undetected.',
+  skills: 'Skills encode domain expertise as reusable components. Without them, you repeat context every session.',
+  multipleAgents: 'Multiple agents enable parallel specialized work (security review + code writing simultaneously).',
+  multipleMcpServers: 'More MCP servers give Claude access to more external context (docs, databases, APIs).',
+  roleDefinition: 'A role definition helps Claude calibrate response depth and technical level.',
+  importSyntax: '@import keeps CLAUDE.md lean while still providing deep instructions in focused modules.',
+};
+
 function toGaps(results) {
   return results
     .filter(r => r.passed === false)
@@ -198,6 +239,7 @@ function toGaps(results) {
       impact: r.impact,
       category: r.category,
       fix: r.fix,
+      why: GAP_REASONS[r.key] || r.fix,
     }));
 }
 
@@ -275,6 +317,8 @@ async function analyzeProject(options) {
   const metadata = detectProjectMetadata(ctx);
   const maturity = detectMaturity(assets);
   const mainDirs = detectMainDirs(ctx);
+  const recommendedDomainPacks = detectDomainPacks(ctx, stacks, assets);
+  const recommendedMcpPacks = recommendMcpPacks(stacks, recommendedDomainPacks);
 
   const report = {
     mode,
@@ -284,6 +328,7 @@ async function analyzeProject(options) {
       description: metadata.description,
       directory: options.dir,
       stacks: stacks.map(s => s.label),
+      domains: recommendedDomainPacks.map(pack => pack.label),
       maturity,
       score: auditResult.score,
       organicScore: auditResult.organicScore,
@@ -308,6 +353,8 @@ async function analyzeProject(options) {
     gapsIdentified: toGaps(auditResult.results),
     topNextActions: auditResult.quickWins,
     recommendedImprovements: toRecommendations(auditResult),
+    recommendedDomainPacks,
+    recommendedMcpPacks,
     riskNotes: buildRiskNotes(auditResult, assets, maturity),
     optionalModules: buildOptionalModules(stacks, assets),
   };
@@ -332,6 +379,7 @@ function printAnalysis(report, options = {}) {
   console.log(c('  Project Summary', 'blue'));
   console.log(`  ${report.projectSummary.name}${report.projectSummary.description ? ` — ${report.projectSummary.description}` : ''}`);
   console.log(c(`  Stack: ${report.projectSummary.stacks.join(', ') || 'Unknown'}`, 'dim'));
+  console.log(c(`  Domain packs: ${report.projectSummary.domains.join(', ') || 'Baseline General'}`, 'dim'));
   console.log(c(`  Maturity: ${report.projectSummary.maturity} | Score: ${report.projectSummary.score}/100 | Organic: ${report.projectSummary.organicScore}/100`, 'dim'));
   console.log('');
 
@@ -348,7 +396,10 @@ function printAnalysis(report, options = {}) {
   if (report.strengthsPreserved.length > 0) {
     console.log(c('  Strengths Preserved', 'green'));
     for (const item of report.strengthsPreserved) {
-      console.log(`  - ${item.name}`);
+      console.log(`  ${c('✓', 'green')} ${item.name}`);
+      if (item.why) {
+        console.log(c(`    ${item.why}`, 'dim'));
+      }
     }
     console.log('');
   }
@@ -371,6 +422,24 @@ function printAnalysis(report, options = {}) {
     console.log('');
   }
 
+  if (report.recommendedDomainPacks.length > 0) {
+    console.log(c('  Recommended Domain Packs', 'blue'));
+    for (const pack of report.recommendedDomainPacks) {
+      console.log(`  - ${pack.label}`);
+      console.log(c(`    ${pack.useWhen}`, 'dim'));
+    }
+    console.log('');
+  }
+
+  if (report.recommendedMcpPacks.length > 0) {
+    console.log(c('  Recommended MCP Packs', 'blue'));
+    for (const pack of report.recommendedMcpPacks) {
+      console.log(`  - ${pack.label}`);
+      console.log(c(`    ${pack.adoption}`, 'dim'));
+    }
+    console.log('');
+  }
+
   if (report.riskNotes.length > 0) {
     console.log(c('  Risk Notes', 'red'));
     for (const note of report.riskNotes) {
@@ -394,4 +463,87 @@ function printAnalysis(report, options = {}) {
   }
 }
 
-module.exports = { analyzeProject, printAnalysis };
+function exportMarkdown(report) {
+  const lines = [];
+  lines.push(`# Claudex Setup Analysis Report`);
+  lines.push(`## ${report.mode === 'suggest-only' ? 'Suggest-Only' : 'Augment'} Mode`);
+  lines.push('');
+  lines.push(`**Project:** ${report.projectSummary.name}${report.projectSummary.description ? ` — ${report.projectSummary.description}` : ''}`);
+  lines.push(`**Date:** ${new Date().toISOString().split('T')[0]}`);
+  lines.push(`**Score:** ${report.projectSummary.score}/100 | **Organic:** ${report.projectSummary.organicScore}/100`);
+  lines.push(`**Stacks:** ${report.projectSummary.stacks.join(', ') || 'None detected'}`);
+  lines.push(`**Domain Packs:** ${report.projectSummary.domains.join(', ') || 'Baseline General'}`);
+  lines.push(`**Maturity:** ${report.projectSummary.maturity}`);
+  lines.push('');
+
+  if (report.strengthsPreserved.length > 0) {
+    lines.push('## Strengths Preserved');
+    lines.push('');
+    for (const item of report.strengthsPreserved) {
+      lines.push(`- **${item.name}** — ${item.why || 'Already configured.'}`);
+    }
+    lines.push('');
+  }
+
+  if (report.gapsIdentified.length > 0) {
+    lines.push('## Gaps Identified');
+    lines.push('');
+    lines.push('| Gap | Impact | Fix |');
+    lines.push('|-----|--------|-----|');
+    for (const item of report.gapsIdentified) {
+      lines.push(`| ${item.name} | ${item.impact} | ${item.fix} |`);
+    }
+    lines.push('');
+  }
+
+  if (report.topNextActions.length > 0) {
+    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('');
+  }
+
+  if (report.recommendedDomainPacks.length > 0) {
+    lines.push('## Recommended Domain Packs');
+    lines.push('');
+    for (const pack of report.recommendedDomainPacks) {
+      lines.push(`- **${pack.label}**: ${pack.useWhen}`);
+    }
+    lines.push('');
+  }
+
+  if (report.recommendedMcpPacks.length > 0) {
+    lines.push('## Recommended MCP Packs');
+    lines.push('');
+    for (const pack of report.recommendedMcpPacks) {
+      lines.push(`- **${pack.label}**: ${pack.useWhen}`);
+    }
+    lines.push('');
+  }
+
+  if (report.riskNotes.length > 0) {
+    lines.push('## Risk Notes');
+    lines.push('');
+    for (const note of report.riskNotes) {
+      lines.push(`- ⚠️ ${note}`);
+    }
+    lines.push('');
+  }
+
+  if (report.suggestedRolloutOrder.length > 0) {
+    lines.push('## Suggested Rollout Order');
+    lines.push('');
+    report.suggestedRolloutOrder.forEach((item, index) => {
+      lines.push(`${index + 1}. ${item}`);
+    });
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push(`*Generated by claudex-setup v${require('../package.json').version}*`);
+  return lines.join('\n');
+}
+
+module.exports = { analyzeProject, printAnalysis, exportMarkdown };

package/src/audit.js

@@ -194,7 +194,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 fix automatically`);
+    console.log(`  Run ${colorize('npx claudex-setup setup', 'bold')} to create starter-safe defaults`);
   }
 
   console.log('');
@@ -212,7 +212,7 @@ async function audit(options) {
     console.log('');
   }
 
-  console.log(colorize('  Powered by CLAUDEX - 1,107 verified Claude Code techniques', 'dim'));
+  console.log(colorize('  Backed by CLAUDEX research and evidence', 'dim'));
   console.log(colorize('  https://github.com/DnaFin/claudex-setup', 'dim'));
   console.log('');