@aiready/cli 0.7.20 → 0.7.21

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/cli@0.7.20 build /Users/pengcao/projects/aiready/packages/cli
+> @aiready/cli@0.7.21 build /Users/pengcao/projects/aiready/packages/cli
 > tsup src/index.ts src/cli.ts --format cjs,esm --dts
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -9,15 +9,15 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/chunk-3SG2GLFJ.mjs 3.80 KB
-ESM dist/index.mjs          138.00 B
-ESM dist/cli.mjs            35.13 KB
-ESM ⚡️ Build success in 16ms
+CJS dist/cli.js   43.96 KB
 CJS dist/index.js 4.93 KB
-CJS dist/cli.js   42.18 KB
-CJS ⚡️ Build success in 17ms
+CJS ⚡️ Build success in 51ms
+ESM dist/index.mjs          138.00 B
+ESM dist/cli.mjs            36.91 KB
+ESM dist/chunk-3SG2GLFJ.mjs 3.80 KB
+ESM ⚡️ Build success in 52ms
 DTS Build start
-DTS ⚡️ Build success in 508ms
+DTS ⚡️ Build success in 611ms
 DTS dist/cli.d.ts    20.00 B
 DTS dist/index.d.ts  1.22 KB
 DTS dist/cli.d.mts   20.00 B

package/.turbo/turbo-test.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/cli@0.7.20 test /Users/pengcao/projects/aiready/packages/cli
+> @aiready/cli@0.7.21 test /Users/pengcao/projects/aiready/packages/cli
 > vitest run
 
 [?25l
@@ -11,15 +11,15 @@
 
  Test Files 0 passed (1)
       Tests 0 passed (0)
-   Start at 17:31:23
+   Start at 10:41:17
    Duration 0ms
 [?2026l[?2026h
  ❯ src/__tests__/cli.test.ts 0/3
 
  Test Files 0 passed (1)
       Tests 0 passed (3)
-   Start at 17:31:23
-   Duration 201ms
+   Start at 10:41:17
+   Duration 301ms
 [?2026l ✓ src/__tests__/cli.test.ts (3 tests) 2ms
    ✓ CLI Unified Analysis (3)
      ✓ should run unified analysis with both tools 1ms
@@ -28,7 +28,7 @@
 
  Test Files  1 passed (1)
       Tests  3 passed (3)
-   Start at  17:31:23
-   Duration  275ms (transform 51ms, setup 0ms, import 203ms, tests 2ms, environment 0ms)
+   Start at  10:41:17
+   Duration  314ms (transform 57ms, setup 0ms, import 237ms, tests 2ms, environment 0ms)
 
 [?25h

package/dist/cli.js

@@ -120,8 +120,49 @@ var import_core = require("@aiready/core");
 var import_fs2 = require("fs");
 var packageJson = JSON.parse((0, import_fs2.readFileSync)((0, import_path.join)(__dirname, "../package.json"), "utf8"));
 var program = new import_commander.Command();
-program.name("aiready").description("AIReady - Unified AI-readiness analysis tools").version(packageJson.version).addHelpText("after", "\nCONFIGURATION:\n  Supports config files: aiready.json, aiready.config.json, .aiready.json, .aireadyrc.json, aiready.config.js, .aireadyrc.js\n  CLI options override config file settings");
-program.command("scan").description("Run unified analysis on a codebase").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score (0-100)").option("--weights <weights>", 'Override tool weights for scoring (e.g., "patterns:50,context:30,consistency:20")').option("--threshold <score>", "Minimum passing score for CI/CD (exits with code 1 if below)").action(async (directory, options) => {
+program.name("aiready").description("AIReady - Assess and improve AI-readiness of codebases").version(packageJson.version).addHelpText("after", `
+AI READINESS SCORING:
+  Get a 0-100 score indicating how AI-ready your codebase is.
+  Use --score flag with any analysis command for detailed breakdown.
+
+EXAMPLES:
+  $ aiready scan                          # Quick analysis of current directory
+  $ aiready scan --score                  # Get AI Readiness Score (0-100)
+  $ aiready scan --tools patterns         # Run only pattern detection
+  $ aiready patterns --similarity 0.6     # Custom similarity threshold
+  $ aiready scan --output json --output-file results.json
+
+GETTING STARTED:
+  1. Run 'aiready scan' to analyze your codebase
+  2. Use 'aiready scan --score' for AI readiness assessment
+  3. Create aiready.json for persistent configuration
+  4. Set up CI/CD with '--threshold' for quality gates
+
+CONFIGURATION:
+  Config files (searched upward): aiready.json, .aiready.json, aiready.config.*
+  CLI options override config file settings
+
+  Example aiready.json:
+  {
+    "scan": { "exclude": ["**/dist/**", "**/node_modules/**"] },
+    "tools": {
+      "pattern-detect": { "minSimilarity": 0.5 },
+      "context-analyzer": { "maxContextBudget": 15000 }
+    },
+    "output": { "format": "json", "directory": ".aiready" }
+  }
+
+VERSION: ${packageJson.version}
+DOCUMENTATION: https://aiready.dev/docs/cli
+GITHUB: https://github.com/caopengau/aiready-cli
+LANDING: https://github.com/caopengau/aiready-landing`);
+program.command("scan").description("Run comprehensive AI-readiness analysis (patterns + context + consistency)").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score (0-100) with breakdown").option("--weights <weights>", "Custom scoring weights (patterns:40,context:35,consistency:25)").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").addHelpText("after", `
+EXAMPLES:
+  $ aiready scan                                    # Analyze all tools
+  $ aiready scan --tools patterns,context           # Skip consistency
+  $ aiready scan --score --threshold 75             # CI/CD with threshold
+  $ aiready scan --output json --output-file report.json
+`).action(async (directory, options) => {
   console.log(import_chalk.default.blue("\u{1F680} Starting AIReady unified analysis...\n"));
   const startTime = Date.now();
   try {
@@ -354,7 +395,12 @@ program.command("scan").description("Run unified analysis on a codebase").argume
     (0, import_core.handleCLIError)(error, "Analysis");
   }
 });
-program.command("patterns").description("Run pattern detection analysis").argument("[directory]", "Directory to analyze", ".").option("-s, --similarity <number>", "Minimum similarity score (0-1)", "0.40").option("-l, --min-lines <number>", "Minimum lines to consider", "5").option("--max-candidates <number>", "Maximum candidates per block (performance tuning)").option("--min-shared-tokens <number>", "Minimum shared tokens for candidates (performance tuning)").option("--full-scan", "Disable smart defaults for comprehensive analysis (slower)").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for patterns (0-100)").action(async (directory, options) => {
+program.command("patterns").description("Detect duplicate code patterns that confuse AI models").argument("[directory]", "Directory to analyze", ".").option("-s, --similarity <number>", "Minimum similarity score (0-1)", "0.40").option("-l, --min-lines <number>", "Minimum lines to consider", "5").option("--max-candidates <number>", "Maximum candidates per block (performance tuning)").option("--min-shared-tokens <number>", "Minimum shared tokens for candidates (performance tuning)").option("--full-scan", "Disable smart defaults for comprehensive analysis (slower)").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for patterns (0-100)").addHelpText("after", `
+EXAMPLES:
+  $ aiready patterns                                 # Default analysis
+  $ aiready patterns --similarity 0.6               # Stricter matching
+  $ aiready patterns --min-lines 10                 # Larger patterns only
+`).action(async (directory, options) => {
   console.log(import_chalk.default.blue("\u{1F50D} Analyzing patterns...\n"));
   const startTime = Date.now();
   try {
@@ -458,7 +504,7 @@ program.command("patterns").description("Run pattern detection analysis").argume
     (0, import_core.handleCLIError)(error, "Pattern analysis");
   }
 });
-program.command("context").description("Run context window cost analysis").argument("[directory]", "Directory to analyze", ".").option("--max-depth <number>", "Maximum acceptable import depth", "5").option("--max-context <number>", "Maximum acceptable context budget (tokens)", "10000").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for context (0-100)").action(async (directory, options) => {
+program.command("context").description("Analyze context window costs and dependency fragmentation").argument("[directory]", "Directory to analyze", ".").option("--max-depth <number>", "Maximum acceptable import depth", "5").option("--max-context <number>", "Maximum acceptable context budget (tokens)", "10000").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for context (0-100)").action(async (directory, options) => {
   console.log(import_chalk.default.blue("\u{1F9E0} Analyzing context costs...\n"));
   const startTime = Date.now();
   try {
@@ -595,7 +641,7 @@ program.command("context").description("Run context window cost analysis").argum
     (0, import_core.handleCLIError)(error, "Context analysis");
   }
 });
-program.command("consistency").description("Check naming, patterns, and architecture consistency").argument("[directory]", "Directory to analyze", ".").option("--naming", "Check naming conventions (default: true)").option("--no-naming", "Skip naming analysis").option("--patterns", "Check code patterns (default: true)").option("--no-patterns", "Skip pattern analysis").option("--min-severity <level>", "Minimum severity: info|minor|major|critical", "info").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json, markdown", "console").option("--output-file <path>", "Output file path (for json/markdown)").option("--score", "Calculate and display AI Readiness Score for consistency (0-100)").action(async (directory, options) => {
+program.command("consistency").description("Check naming conventions and architectural consistency").argument("[directory]", "Directory to analyze", ".").option("--naming", "Check naming conventions (default: true)").option("--no-naming", "Skip naming analysis").option("--patterns", "Check code patterns (default: true)").option("--no-patterns", "Skip pattern analysis").option("--min-severity <level>", "Minimum severity: info|minor|major|critical", "info").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json, markdown", "console").option("--output-file <path>", "Output file path (for json/markdown)").option("--score", "Calculate and display AI Readiness Score for consistency (0-100)").action(async (directory, options) => {
   console.log(import_chalk.default.blue("\u{1F50D} Analyzing consistency...\n"));
   const startTime = Date.now();
   try {

package/dist/cli.mjs

@@ -24,8 +24,49 @@ import {
 import { readFileSync } from "fs";
 var packageJson = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
 var program = new Command();
-program.name("aiready").description("AIReady - Unified AI-readiness analysis tools").version(packageJson.version).addHelpText("after", "\nCONFIGURATION:\n  Supports config files: aiready.json, aiready.config.json, .aiready.json, .aireadyrc.json, aiready.config.js, .aireadyrc.js\n  CLI options override config file settings");
-program.command("scan").description("Run unified analysis on a codebase").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score (0-100)").option("--weights <weights>", 'Override tool weights for scoring (e.g., "patterns:50,context:30,consistency:20")').option("--threshold <score>", "Minimum passing score for CI/CD (exits with code 1 if below)").action(async (directory, options) => {
+program.name("aiready").description("AIReady - Assess and improve AI-readiness of codebases").version(packageJson.version).addHelpText("after", `
+AI READINESS SCORING:
+  Get a 0-100 score indicating how AI-ready your codebase is.
+  Use --score flag with any analysis command for detailed breakdown.
+
+EXAMPLES:
+  $ aiready scan                          # Quick analysis of current directory
+  $ aiready scan --score                  # Get AI Readiness Score (0-100)
+  $ aiready scan --tools patterns         # Run only pattern detection
+  $ aiready patterns --similarity 0.6     # Custom similarity threshold
+  $ aiready scan --output json --output-file results.json
+
+GETTING STARTED:
+  1. Run 'aiready scan' to analyze your codebase
+  2. Use 'aiready scan --score' for AI readiness assessment
+  3. Create aiready.json for persistent configuration
+  4. Set up CI/CD with '--threshold' for quality gates
+
+CONFIGURATION:
+  Config files (searched upward): aiready.json, .aiready.json, aiready.config.*
+  CLI options override config file settings
+
+  Example aiready.json:
+  {
+    "scan": { "exclude": ["**/dist/**", "**/node_modules/**"] },
+    "tools": {
+      "pattern-detect": { "minSimilarity": 0.5 },
+      "context-analyzer": { "maxContextBudget": 15000 }
+    },
+    "output": { "format": "json", "directory": ".aiready" }
+  }
+
+VERSION: ${packageJson.version}
+DOCUMENTATION: https://aiready.dev/docs/cli
+GITHUB: https://github.com/caopengau/aiready-cli
+LANDING: https://github.com/caopengau/aiready-landing`);
+program.command("scan").description("Run comprehensive AI-readiness analysis (patterns + context + consistency)").argument("[directory]", "Directory to analyze", ".").option("-t, --tools <tools>", "Tools to run (comma-separated: patterns,context,consistency)", "patterns,context,consistency").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score (0-100) with breakdown").option("--weights <weights>", "Custom scoring weights (patterns:40,context:35,consistency:25)").option("--threshold <score>", "Fail CI/CD if score below threshold (0-100)").addHelpText("after", `
+EXAMPLES:
+  $ aiready scan                                    # Analyze all tools
+  $ aiready scan --tools patterns,context           # Skip consistency
+  $ aiready scan --score --threshold 75             # CI/CD with threshold
+  $ aiready scan --output json --output-file report.json
+`).action(async (directory, options) => {
   console.log(chalk.blue("\u{1F680} Starting AIReady unified analysis...\n"));
   const startTime = Date.now();
   try {
@@ -258,7 +299,12 @@ program.command("scan").description("Run unified analysis on a codebase").argume
     handleCLIError(error, "Analysis");
   }
 });
-program.command("patterns").description("Run pattern detection analysis").argument("[directory]", "Directory to analyze", ".").option("-s, --similarity <number>", "Minimum similarity score (0-1)", "0.40").option("-l, --min-lines <number>", "Minimum lines to consider", "5").option("--max-candidates <number>", "Maximum candidates per block (performance tuning)").option("--min-shared-tokens <number>", "Minimum shared tokens for candidates (performance tuning)").option("--full-scan", "Disable smart defaults for comprehensive analysis (slower)").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for patterns (0-100)").action(async (directory, options) => {
+program.command("patterns").description("Detect duplicate code patterns that confuse AI models").argument("[directory]", "Directory to analyze", ".").option("-s, --similarity <number>", "Minimum similarity score (0-1)", "0.40").option("-l, --min-lines <number>", "Minimum lines to consider", "5").option("--max-candidates <number>", "Maximum candidates per block (performance tuning)").option("--min-shared-tokens <number>", "Minimum shared tokens for candidates (performance tuning)").option("--full-scan", "Disable smart defaults for comprehensive analysis (slower)").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for patterns (0-100)").addHelpText("after", `
+EXAMPLES:
+  $ aiready patterns                                 # Default analysis
+  $ aiready patterns --similarity 0.6               # Stricter matching
+  $ aiready patterns --min-lines 10                 # Larger patterns only
+`).action(async (directory, options) => {
   console.log(chalk.blue("\u{1F50D} Analyzing patterns...\n"));
   const startTime = Date.now();
   try {
@@ -362,7 +408,7 @@ program.command("patterns").description("Run pattern detection analysis").argume
     handleCLIError(error, "Pattern analysis");
   }
 });
-program.command("context").description("Run context window cost analysis").argument("[directory]", "Directory to analyze", ".").option("--max-depth <number>", "Maximum acceptable import depth", "5").option("--max-context <number>", "Maximum acceptable context budget (tokens)", "10000").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for context (0-100)").action(async (directory, options) => {
+program.command("context").description("Analyze context window costs and dependency fragmentation").argument("[directory]", "Directory to analyze", ".").option("--max-depth <number>", "Maximum acceptable import depth", "5").option("--max-context <number>", "Maximum acceptable context budget (tokens)", "10000").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json", "console").option("--output-file <path>", "Output file path (for json)").option("--score", "Calculate and display AI Readiness Score for context (0-100)").action(async (directory, options) => {
   console.log(chalk.blue("\u{1F9E0} Analyzing context costs...\n"));
   const startTime = Date.now();
   try {
@@ -499,7 +545,7 @@ program.command("context").description("Run context window cost analysis").argum
     handleCLIError(error, "Context analysis");
   }
 });
-program.command("consistency").description("Check naming, patterns, and architecture consistency").argument("[directory]", "Directory to analyze", ".").option("--naming", "Check naming conventions (default: true)").option("--no-naming", "Skip naming analysis").option("--patterns", "Check code patterns (default: true)").option("--no-patterns", "Skip pattern analysis").option("--min-severity <level>", "Minimum severity: info|minor|major|critical", "info").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json, markdown", "console").option("--output-file <path>", "Output file path (for json/markdown)").option("--score", "Calculate and display AI Readiness Score for consistency (0-100)").action(async (directory, options) => {
+program.command("consistency").description("Check naming conventions and architectural consistency").argument("[directory]", "Directory to analyze", ".").option("--naming", "Check naming conventions (default: true)").option("--no-naming", "Skip naming analysis").option("--patterns", "Check code patterns (default: true)").option("--no-patterns", "Skip pattern analysis").option("--min-severity <level>", "Minimum severity: info|minor|major|critical", "info").option("--include <patterns>", "File patterns to include (comma-separated)").option("--exclude <patterns>", "File patterns to exclude (comma-separated)").option("-o, --output <format>", "Output format: console, json, markdown", "console").option("--output-file <path>", "Output file path (for json/markdown)").option("--score", "Calculate and display AI Readiness Score for consistency (0-100)").action(async (directory, options) => {
   console.log(chalk.blue("\u{1F50D} Analyzing consistency...\n"));
   const startTime = Date.now();
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/cli",
-  "version": "0.7.20",
+  "version": "0.7.21",
   "description": "Unified CLI for AIReady analysis tools",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -11,10 +11,10 @@
   "dependencies": {
     "commander": "^14.0.0",
     "chalk": "^5.3.0",
-    "@aiready/pattern-detect": "0.9.22",
-    "@aiready/consistency": "0.6.16",
-    "@aiready/core": "0.7.13",
-    "@aiready/context-analyzer": "0.7.18"
+    "@aiready/pattern-detect": "0.9.23",
+    "@aiready/core": "0.7.14",
+    "@aiready/context-analyzer": "0.7.19",
+    "@aiready/consistency": "0.6.17"
   },
   "devDependencies": {
     "tsup": "^8.3.5",

package/src/cli.ts

@@ -28,22 +28,64 @@ const program = new Command();
 
 program
   .name('aiready')
-  .description('AIReady - Unified AI-readiness analysis tools')
+  .description('AIReady - Assess and improve AI-readiness of codebases')
   .version(packageJson.version)
-  .addHelpText('after', '\nCONFIGURATION:\n  Supports config files: aiready.json, aiready.config.json, .aiready.json, .aireadyrc.json, aiready.config.js, .aireadyrc.js\n  CLI options override config file settings');
+  .addHelpText('after', `
+AI READINESS SCORING:
+  Get a 0-100 score indicating how AI-ready your codebase is.
+  Use --score flag with any analysis command for detailed breakdown.
+
+EXAMPLES:
+  $ aiready scan                          # Quick analysis of current directory
+  $ aiready scan --score                  # Get AI Readiness Score (0-100)
+  $ aiready scan --tools patterns         # Run only pattern detection
+  $ aiready patterns --similarity 0.6     # Custom similarity threshold
+  $ aiready scan --output json --output-file results.json
+
+GETTING STARTED:
+  1. Run 'aiready scan' to analyze your codebase
+  2. Use 'aiready scan --score' for AI readiness assessment
+  3. Create aiready.json for persistent configuration
+  4. Set up CI/CD with '--threshold' for quality gates
+
+CONFIGURATION:
+  Config files (searched upward): aiready.json, .aiready.json, aiready.config.*
+  CLI options override config file settings
+
+  Example aiready.json:
+  {
+    "scan": { "exclude": ["**/dist/**", "**/node_modules/**"] },
+    "tools": {
+      "pattern-detect": { "minSimilarity": 0.5 },
+      "context-analyzer": { "maxContextBudget": 15000 }
+    },
+    "output": { "format": "json", "directory": ".aiready" }
+  }
+
+VERSION: ${packageJson.version}
+DOCUMENTATION: https://aiready.dev/docs/cli
+GITHUB: https://github.com/caopengau/aiready-cli
+LANDING: https://github.com/caopengau/aiready-landing`);
 
 program
   .command('scan')
-  .description('Run unified analysis on a codebase')
+  .description('Run comprehensive AI-readiness analysis (patterns + context + consistency)')
   .argument('[directory]', 'Directory to analyze', '.')
   .option('-t, --tools <tools>', 'Tools to run (comma-separated: patterns,context,consistency)', 'patterns,context,consistency')
   .option('--include <patterns>', 'File patterns to include (comma-separated)')
   .option('--exclude <patterns>', 'File patterns to exclude (comma-separated)')
   .option('-o, --output <format>', 'Output format: console, json', 'console')
   .option('--output-file <path>', 'Output file path (for json)')
-  .option('--score', 'Calculate and display AI Readiness Score (0-100)')
-  .option('--weights <weights>', 'Override tool weights for scoring (e.g., "patterns:50,context:30,consistency:20")')
-  .option('--threshold <score>', 'Minimum passing score for CI/CD (exits with code 1 if below)')
+  .option('--score', 'Calculate and display AI Readiness Score (0-100) with breakdown')
+  .option('--weights <weights>', 'Custom scoring weights (patterns:40,context:35,consistency:25)')
+  .option('--threshold <score>', 'Fail CI/CD if score below threshold (0-100)')
+  .addHelpText('after', `
+EXAMPLES:
+  $ aiready scan                                    # Analyze all tools
+  $ aiready scan --tools patterns,context           # Skip consistency
+  $ aiready scan --score --threshold 75             # CI/CD with threshold
+  $ aiready scan --output json --output-file report.json
+`)
   .action(async (directory, options) => {
     console.log(chalk.blue('🚀 Starting AIReady unified analysis...\n'));
 
@@ -343,7 +385,7 @@ program
 // Individual tool commands for convenience
 program
   .command('patterns')
-  .description('Run pattern detection analysis')
+  .description('Detect duplicate code patterns that confuse AI models')
   .argument('[directory]', 'Directory to analyze', '.')
   .option('-s, --similarity <number>', 'Minimum similarity score (0-1)', '0.40')
   .option('-l, --min-lines <number>', 'Minimum lines to consider', '5')
@@ -355,6 +397,12 @@ program
   .option('-o, --output <format>', 'Output format: console, json', 'console')
   .option('--output-file <path>', 'Output file path (for json)')
   .option('--score', 'Calculate and display AI Readiness Score for patterns (0-100)')
+  .addHelpText('after', `
+EXAMPLES:
+  $ aiready patterns                                 # Default analysis
+  $ aiready patterns --similarity 0.6               # Stricter matching
+  $ aiready patterns --min-lines 10                 # Larger patterns only
+`)
   .action(async (directory, options) => {
     console.log(chalk.blue('🔍 Analyzing patterns...\n'));
 
@@ -499,7 +547,7 @@ program
 
 program
   .command('context')
-  .description('Run context window cost analysis')
+  .description('Analyze context window costs and dependency fragmentation')
   .argument('[directory]', 'Directory to analyze', '.')
   .option('--max-depth <number>', 'Maximum acceptable import depth', '5')
   .option('--max-context <number>', 'Maximum acceptable context budget (tokens)', '10000')
@@ -675,7 +723,7 @@ program
 
   program
     .command('consistency')
-    .description('Check naming, patterns, and architecture consistency')
+    .description('Check naming conventions and architectural consistency')
     .argument('[directory]', 'Directory to analyze', '.')
     .option('--naming', 'Check naming conventions (default: true)')
     .option('--no-naming', 'Skip naming analysis')