@oculum/cli 1.0.8 → 1.0.10

package/dist/index.js

@@ -214,9 +214,9 @@ var require_help = __commonJS({
        */
       visibleCommands(cmd) {
         const visibleCommands = cmd.commands.filter((cmd2) => !cmd2._hidden);
-        const helpCommand = cmd._getHelpCommand();
-        if (helpCommand && !helpCommand._hidden) {
-          visibleCommands.push(helpCommand);
+        const helpCommand2 = cmd._getHelpCommand();
+        if (helpCommand2 && !helpCommand2._hidden) {
+          visibleCommands.push(helpCommand2);
         }
         if (this.sortSubcommands) {
           visibleCommands.sort((a, b3) => {
@@ -1304,12 +1304,12 @@ var require_command = __commonJS({
         enableOrNameAndArgs = enableOrNameAndArgs ?? "help [command]";
         const [, helpName, helpArgs] = enableOrNameAndArgs.match(/([^ ]+) *(.*)/);
         const helpDescription = description ?? "display help for command";
-        const helpCommand = this.createCommand(helpName);
-        helpCommand.helpOption(false);
-        if (helpArgs) helpCommand.arguments(helpArgs);
-        if (helpDescription) helpCommand.description(helpDescription);
+        const helpCommand2 = this.createCommand(helpName);
+        helpCommand2.helpOption(false);
+        if (helpArgs) helpCommand2.arguments(helpArgs);
+        if (helpDescription) helpCommand2.description(helpDescription);
         this._addImplicitHelpCommand = true;
-        this._helpCommand = helpCommand;
+        this._helpCommand = helpCommand2;
         return this;
       }
       /**
@@ -1319,13 +1319,13 @@ var require_command = __commonJS({
        * @param {string} [deprecatedDescription] - deprecated custom description used with custom name only
        * @return {Command} `this` command for chaining
        */
-      addHelpCommand(helpCommand, deprecatedDescription) {
-        if (typeof helpCommand !== "object") {
-          this.helpCommand(helpCommand, deprecatedDescription);
+      addHelpCommand(helpCommand2, deprecatedDescription) {
+        if (typeof helpCommand2 !== "object") {
+          this.helpCommand(helpCommand2, deprecatedDescription);
           return this;
         }
         this._addImplicitHelpCommand = true;
-        this._helpCommand = helpCommand;
+        this._helpCommand = helpCommand2;
         return this;
       }
       /**
@@ -11572,6 +11572,8 @@ var require_context_helpers = __commonJS({
     exports2.isDocumentationFile = isDocumentationFile;
     exports2.isScannerOrFixtureFile = isScannerOrFixtureFile;
     exports2.isClientBundledFile = isClientBundledFile;
+    exports2.isSeedOrDataGenFile = isSeedOrDataGenFile;
+    exports2.isEducationalVulnerabilityFile = isEducationalVulnerabilityFile;
     exports2.isEnvVarReference = isEnvVarReference;
     exports2.isNextPublicEnvVar = isNextPublicEnvVar;
     exports2.isComment = isComment;
@@ -11735,6 +11737,35 @@ var require_context_helpers = __commonJS({
       }
       return clientPatterns.some((pattern) => pattern.test(filePath));
     }
+    function isSeedOrDataGenFile(filePath) {
+      const patterns = [
+        /\/seed\//i,
+        /\/seeds\//i,
+        /seed-database\.(ts|js)$/i,
+        /\/seeder\./i,
+        /datacreator\.(ts|js)$/i,
+        /\/data\/.*creator/i,
+        /\/fixtures\//i,
+        /\.fixture\./i,
+        /\/generators?\//i,
+        /\/factories\//i,
+        /factory\.(ts|js)$/i
+      ];
+      return patterns.some((p2) => p2.test(filePath));
+    }
+    function isEducationalVulnerabilityFile(filePath) {
+      const patterns = [
+        /\/insecurity\.(ts|js)$/i,
+        /\/vulnerable\.(ts|js)$/i,
+        /\/intentionally-vulnerable/i,
+        /\/security-examples?\//i,
+        /\/vuln-examples?\//i,
+        /\/challenge-\d+/i,
+        // OWASP Juice Shop challenges
+        /\/exploit-examples?\//i
+      ];
+      return patterns.some((p2) => p2.test(filePath));
+    }
     function isEnvVarReference(line) {
       return /process\.env\.[A-Z_]+/.test(line) || /\$\{?[A-Z_]+\}?/.test(line) || /import\.meta\.env\.[A-Z_]+/.test(line) || /Deno\.env\.get\(/.test(line) || /os\.environ\[/.test(line) || // Python
       /os\.getenv\(/.test(line) || // Python
@@ -11977,12 +12008,12 @@ var require_entropy = __commonJS({
       const strings = [];
       const lines = content.split("\n");
       const patterns = [
-        /"([^"\\]|\\.){20,}"/g,
-        // Double-quoted strings 20+ chars
-        /'([^'\\]|\\.){20,}'/g,
-        // Single-quoted strings 20+ chars
-        /`([^`\\]|\\.){20,}`/g
-        // Template literals 20+ chars
+        /"[^"\\]{20,}(?:\\.[^"\\]*)*"/g,
+        // Double-quoted strings 20+ chars (unrolled loop)
+        /'[^'\\]{20,}(?:\\.[^'\\]*)*'/g,
+        // Single-quoted strings 20+ chars (unrolled loop)
+        /`[^`\\]{20,}(?:\\.[^`\\]*)*`/g
+        // Template literals 20+ chars (unrolled loop)
       ];
       lines.forEach((line, index) => {
         for (const pattern of patterns) {
@@ -15848,19 +15879,11 @@ var require_dangerous_functions = __commonJS({
         // Math.random() * 100 + 50 + 'px'
         /Math\.random.*\*\s*\d+\s*\+\s*\d+.*\bms\b/i,
         // Math.random() * 1000 + 500 + 'ms'
-        /Math\.random.*\*\s*\d+\s*\+\s*\d+.*\bs\b/i,
+        /Math\.random.*\*\s*\d+\s*\+\s*\d+.*\bs\b/i
         // Math.random() * 5 + 2 + 's'
-        // UI identifier generation (short strings for element IDs, keys, etc.)
-        /Math\.random\(\)\.toString\(36\)\.substring\(/,
-        // .toString(36).substring(2, 9) - short UI IDs
-        /Math\.random\(\)\.toString\(36\)\.substr\(/,
-        // .substr() variant
-        /Math\.random\(\)\.toString\(36\)\.slice\(/,
-        // .slice() variant
-        /Math\.random\(\)\.toString\(16\)\.substring\(/,
-        // .toString(16).substring() - hex UI IDs
-        /Math\.random\(\)\.toString\(16\)\.slice\(/
-        // hex slice variant
+        // NOTE: toString patterns removed - now handled by analyzeToStringPattern()
+        // which provides more granular severity classification (info/low/medium/high)
+        // based on truncation length and context
       ];
       if (cosmeticLinePatterns.some((p2) => p2.test(lineContent))) {
         return true;
@@ -15911,6 +15934,71 @@ var require_dangerous_functions = __commonJS({
       }
       return false;
     }
+    function extractFunctionContext(content, lineNumber) {
+      const lines = content.split("\n");
+      const start = Math.max(0, lineNumber - 10);
+      for (let i = lineNumber; i >= start; i--) {
+        const line = lines[i];
+        const funcDeclMatch = line.match(/(?:export\s+)?function\s+(\w+)/i);
+        if (funcDeclMatch) {
+          return funcDeclMatch[1].toLowerCase();
+        }
+        const arrowFuncMatch = line.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:function|\(|async)/i);
+        if (arrowFuncMatch) {
+          return arrowFuncMatch[1].toLowerCase();
+        }
+      }
+      return null;
+    }
+    function classifyFunctionIntent(functionName) {
+      if (!functionName)
+        return "unknown";
+      const lower = functionName.toLowerCase();
+      const uuidPatterns = ["uuid", "guid", "uniqueid", "correlationid"];
+      const idGenerationPatterns = /^(generate|create|make|build)(id|identifier)$/i;
+      if (uuidPatterns.some((p2) => lower.includes(p2)) || idGenerationPatterns.test(lower)) {
+        return "uuid";
+      }
+      const captchaPatterns = ["captcha", "puzzle", "mathproblem"];
+      if (captchaPatterns.some((p2) => lower.includes(p2)))
+        return "captcha";
+      if (lower.includes("challenge") && !lower.includes("auth"))
+        return "captcha";
+      const demoPatterns = ["seed", "fixture", "demo", "mock", "fake"];
+      if (demoPatterns.some((p2) => lower.includes(p2)))
+        return "demo";
+      const securityPatterns = ["token", "secret", "key", "password", "credential", "signature"];
+      const securityFunctionPattern = /^(generate|create|make)(token|secret|key|session|password|credential)/i;
+      if (securityPatterns.some((p2) => lower.includes(p2)) || securityFunctionPattern.test(lower)) {
+        return "security";
+      }
+      return "unknown";
+    }
+    function analyzeToStringPattern(lineContent) {
+      const toString36Match = lineContent.match(/Math\.random\(\)\.toString\(36\)/);
+      const toString16Match = lineContent.match(/Math\.random\(\)\.toString\(16\)/);
+      if (!toString36Match && !toString16Match) {
+        return { hasToString: false, base: null, isTruncated: false, truncationLength: null, intent: "unknown" };
+      }
+      const base = toString36Match ? 36 : 16;
+      const substringMatch = lineContent.match(/\.substring\((\d+)(?:,\s*(\d+))?\)/);
+      const sliceMatch = lineContent.match(/\.slice\((\d+)(?:,\s*(\d+))?\)/);
+      const substrMatch = lineContent.match(/\.substr\((\d+)(?:,\s*(\d+))?\)/);
+      const truncMatch = substringMatch || sliceMatch || substrMatch;
+      if (!truncMatch) {
+        return { hasToString: true, base, isTruncated: false, truncationLength: null, intent: "full-token" };
+      }
+      const start = parseInt(truncMatch[1]);
+      const end = truncMatch[2] ? parseInt(truncMatch[2]) : null;
+      const length = end ? end - start : null;
+      if (length && length <= 9) {
+        return { hasToString: true, base, isTruncated: true, truncationLength: length, intent: "short-ui-id" };
+      } else if (length && length <= 15) {
+        return { hasToString: true, base, isTruncated: true, truncationLength: length, intent: "business-id" };
+      } else {
+        return { hasToString: true, base, isTruncated: true, truncationLength: length, intent: "business-id" };
+      }
+    }
     function extractMathRandomVariableName(lineContent) {
       const assignmentMatch = lineContent.match(/(?:const|let|var)\s+(\w+)\s*=.*Math\.random/);
       if (assignmentMatch)
@@ -16021,9 +16109,7 @@ var require_dangerous_functions = __commonJS({
       const inUIContext = isCosmeticMathRandom(lineContent, content, lineNumber);
       const businessLogicPatterns = [
         /\b(business|order|invoice|customer|product|transaction)Id\b/i,
-        /\b(reference|tracking|confirmation)Number\b/i,
-        /\bgenerate.*Id\b/i,
-        /\bcreate.*Id\b/i
+        /\b(reference|tracking|confirmation)Number\b/i
       ];
       const inBusinessLogicContext = businessLogicPatterns.some((p2) => p2.test(context)) && !inSecurityContext;
       let contextDescription = "unknown context";
@@ -16267,12 +16353,24 @@ var require_dangerous_functions = __commonJS({
               }
             }
             if (funcPattern.name === "Math.random for security") {
+              if ((0, context_helpers_1.isSeedOrDataGenFile)(filePath)) {
+                break;
+              }
+              if ((0, context_helpers_1.isEducationalVulnerabilityFile)(filePath)) {
+                break;
+              }
               const varName = extractMathRandomVariableName(line);
               const nameRisk = classifyVariableNameRisk(varName);
               const context = analyzeMathRandomContext(content, filePath, index);
+              const functionName = extractFunctionContext(content, index);
+              const functionIntent = classifyFunctionIntent(functionName);
+              const toStringPattern = analyzeToStringPattern(line);
               if (context.inUIContext) {
                 break;
               }
+              if (functionIntent === "uuid" || functionIntent === "captcha") {
+                break;
+              }
               let severity2 = "medium";
               let confidence2 = "medium";
               let explanation = "";
@@ -16284,15 +16382,27 @@ var require_dangerous_functions = __commonJS({
                 explanation = " (test data generation)";
                 description = "Math.random() used in test context for generating mock data. Not security-critical, but consider crypto.randomUUID() for better uniqueness in tests.";
                 suggestedFix = "Consider crypto.randomUUID() for test data uniqueness, though Math.random() is acceptable in tests";
-              } else if (nameRisk === "high" || context.inSecurityContext) {
+              } else if (functionIntent === "demo") {
+                severity2 = "info";
+                confidence2 = "low";
+                explanation = " (seed/demo data generation)";
+                description = "Math.random() used for generating fixture/seed data. Not security-critical in development contexts.";
+                suggestedFix = "Acceptable for seed data. Use crypto.randomUUID() if uniqueness guarantees needed.";
+              } else if (nameRisk === "high" || context.inSecurityContext || functionIntent === "security") {
                 severity2 = "high";
                 confidence2 = "high";
                 explanation = " (security-sensitive context)";
                 description = "Math.random() is NOT cryptographically secure and MUST NOT be used for tokens, keys, passwords, or session IDs. This can lead to predictable values that attackers can exploit.";
                 suggestedFix = "Replace with crypto.randomBytes() or crypto.randomUUID() for security-sensitive operations";
-              } else if (nameRisk === "low" || context.inBusinessLogicContext) {
+              } else if (toStringPattern.intent === "short-ui-id") {
+                severity2 = "info";
+                confidence2 = "low";
+                explanation = " (UI correlation ID)";
+                description = "Math.random() used for short UI correlation IDs. Not security-critical, but collisions possible in high-volume scenarios.";
+                suggestedFix = "For UI correlation, crypto.randomUUID() provides better uniqueness guarantees";
+              } else if (nameRisk === "low" || context.inBusinessLogicContext || toStringPattern.intent === "business-id") {
                 severity2 = "low";
-                confidence2 = "medium";
+                confidence2 = "low";
                 explanation = " (business identifier)";
                 description = "Math.random() is being used for non-security purposes (business IDs, tracking numbers). While not critical, Math.random() can produce collisions in high-volume scenarios.";
                 suggestedFix = "Consider crypto.randomUUID() for better uniqueness guarantees and collision resistance";
@@ -36950,6 +37060,35 @@ Distinguish these patterns:
     - Cross-tenant storage: medium (data isolation risk)
   - Do NOT describe transient BYOK keys as "stored without encryption" - they are NOT stored
 
+**Math.random() for Security:**
+Distinguish legitimate uses from security-critical misuse:
+- **Seed/Data Generation Files**: Files in /seed/, /fixtures/, /factories/, datacreator.ts, *.fixture.* are for test data generation
+  - Math.random() in seed files is acceptable - these are never production security code
+  - REJECT findings from seed/data generation files entirely
+- **Educational Vulnerability Files**: Files named insecurity.ts, vulnerable.ts, or in /intentionally-vulnerable/ paths
+  - These are OWASP Juice Shop challenges or security training examples
+  - REJECT entirely - they're intentionally vulnerable for educational purposes
+- **UUID/Identifier Generation**: Functions named generateUUID(), createId(), correlationId(), etc.
+  - Use Math.random() for UI correlation, React keys, element IDs
+  - Short toString(36).substring(2, 9) patterns are for UI correlation, NOT security tokens
+  - REJECT unless function name explicitly indicates security (generateToken, createSessionId, generateSecret)
+- **CAPTCHA/Puzzle Generation**: Math.random() for CAPTCHA questions, puzzle difficulty, game mechanics
+  - These don't need cryptographic randomness - legitimate non-security use
+  - REJECT findings in CAPTCHA/puzzle generation functions
+- **Security-Sensitive Context**: Only keep as HIGH/CRITICAL when:
+  - Variable names indicate security: token, secret, key, auth, session, password
+  - Function names indicate security: generateToken, createSession, makeSecret
+  - Used in security-critical files: auth.ts, crypto.ts, session.ts
+  - Long toString() patterns without truncation (potential token generation)
+
+**Severity Ladder for Math.random():**
+- Seed/educational files: REJECT (not production code)
+- UUID/CAPTCHA functions: REJECT (legitimate use)
+- Short UI IDs (toString(36).substring(2, 9)): INFO (UI correlation, suggest crypto.randomUUID())
+- Business IDs: LOW (suggest crypto.randomUUID() for collision resistance)
+- Security contexts (tokens/secrets/keys): HIGH (cryptographic weakness)
+- Unknown context: MEDIUM (needs manual review)
+
 ### 3.6 DOM Sinks and Bootstrap Scripts
 Recognise LOW-RISK patterns:
 - Static scripts reading localStorage for theme/preferences
@@ -37130,19 +37269,23 @@ AI-generated structured outputs need validation before use in security-sensitive
    - Generic success messages
    - Placeholder comments in non-security code
 
-## Response Format
+## Response Format (OPTIMIZED FOR MINIMAL OUTPUT)
 
 For each candidate finding, return:
 \`\`\`json
 {
   "index": <number>,
   "keep": true | false,
-  "reason": "<brief explanation referencing specific code/context>",
-  "adjustedSeverity": "critical" | "high" | "medium" | "low" | "info" | null,
-  "validationNotes": "<optional: additional context for the developer>"
+  "adjustedSeverity": "critical" | "high" | "medium" | "low" | "info" | null,  // Only if keep=true
+  "notes": "<concise context for developer>"  // Only if keep=true, 1-2 sentences max
 }
 \`\`\`
 
+**CRITICAL**: To minimize costs:
+- For \`keep: false\` (rejected): ONLY include \`index\` and \`keep\` fields. NO explanation needed.
+- For \`keep: true\` (accepted): Include \`notes\` field with brief context (10-30 words). Be concise.
+- Omit \`adjustedSeverity\` if keeping original severity (null is wasteful).
+
 ## Severity Guidelines
 - **critical/high**: Realistically exploitable, should block deploys - ONLY for clear vulnerabilities
 - **medium/low**: Important but non-blocking, hardening opportunities - use sparingly
@@ -37165,7 +37308,35 @@ For each candidate finding, return:
    - No visible mitigating factors in context
    - Real-world attack scenario is plausible
 
-**REMEMBER**: You are the last line of defense against noise. A finding that reaches the user should be CLEARLY worth their time. When in doubt, REJECT.`;
+**REMEMBER**: You are the last line of defense against noise. A finding that reaches the user should be CLEARLY worth their time. When in doubt, REJECT.
+
+## Response Format
+
+For EACH file, provide a JSON object with the file path and validation results.
+Return a JSON array where each element has:
+- "file": the file path (e.g., "src/routes/api.ts")
+- "validations": array of validation results for that file's candidates
+
+Example response format (OPTIMIZED):
+\`\`\`json
+[
+  {
+    "file": "src/auth.ts",
+    "validations": [
+      { "index": 0, "keep": true, "adjustedSeverity": "medium", "notes": "Protected by middleware" },
+      { "index": 1, "keep": false }
+    ]
+  },
+  {
+    "file": "src/api.ts",
+    "validations": [
+      { "index": 0, "keep": true, "notes": "User input flows to SQL query" }
+    ]
+  }
+]
+\`\`\`
+
+**REMEMBER**: Rejected findings (keep: false) need NO explanation. Keep notes brief (10-30 words).`;
     var cachedProjectContext = null;
     async function makeAnthropicRequestWithRetry(requestFn, maxRetries = 3, initialDelayMs = 1e3) {
       let lastError = null;
@@ -37279,7 +37450,45 @@ For each candidate finding, return:
               { role: "system", content: HIGH_CONTEXT_VALIDATION_PROMPT },
               { role: "user", content: validationRequest }
             ],
-            max_completion_tokens: 4096
+            max_completion_tokens: 1500,
+            // Reduced from 4096 - optimized format needs less output
+            response_format: {
+              type: "json_schema",
+              json_schema: {
+                name: "validation_response",
+                strict: true,
+                schema: {
+                  type: "object",
+                  properties: {
+                    validations: {
+                      type: "array",
+                      items: {
+                        type: "object",
+                        properties: {
+                          file: { type: "string" },
+                          validations: {
+                            type: "array",
+                            items: {
+                              type: "object",
+                              properties: {
+                                index: { type: "number" },
+                                keep: { type: "boolean" }
+                              },
+                              required: ["index", "keep"],
+                              additionalProperties: true
+                            }
+                          }
+                        },
+                        required: ["file", "validations"],
+                        additionalProperties: false
+                      }
+                    }
+                  },
+                  required: ["validations"],
+                  additionalProperties: false
+                }
+              }
+            }
           }));
           statsLock.apiCalls++;
           const usage2 = response.usage;
@@ -37311,8 +37520,18 @@ For each candidate finding, return:
             }
             return batchFindings;
           }
+          let parsedContent;
+          try {
+            parsedContent = JSON.parse(content);
+            if (parsedContent.validations && Array.isArray(parsedContent.validations)) {
+              parsedContent = parsedContent.validations;
+            }
+          } catch (e2) {
+            console.warn("[OpenAI] Failed to parse JSON response:", e2);
+            parsedContent = content;
+          }
           const expectedFiles = fileDataList.map(({ filePath }) => filePath);
-          const validationResultsMap = parseMultiFileValidationResponse(content, expectedFiles);
+          const validationResultsMap = parseMultiFileValidationResponse(typeof parsedContent === "string" ? parsedContent : JSON.stringify(parsedContent), expectedFiles);
           for (const { filePath, findings: fileFindings } of fileDataList) {
             const fileResults = validationResultsMap.get(filePath);
             if (!fileResults || fileResults.length === 0) {
@@ -37501,8 +37720,8 @@ For each candidate finding, return:
           const validationRequest = buildMultiFileValidationRequest(fileDataList.map(({ file, findings: findings2 }) => ({ file, findings: findings2 })), context);
           const response = await makeAnthropicRequestWithRetry(() => client.messages.create({
             model: "claude-3-5-haiku-20241022",
-            max_tokens: 4096,
-            // Increased for multi-file responses
+            max_tokens: 1500,
+            // Reduced from 4096 - optimized format needs less output
             system: [
               {
                 type: "text",
@@ -37696,14 +37915,14 @@ Example response format:
   {
     "file": "src/auth.ts",
     "validations": [
-      { "index": 0, "keep": true, "reason": "Valid finding", "adjustedSeverity": null, "validationNotes": "..." },
-      { "index": 1, "keep": false, "reason": "False positive because..." }
+      { "index": 0, "keep": true, "adjustedSeverity": "medium", "notes": "Protected by middleware" },
+      { "index": 1, "keep": false }
     ]
   },
   {
     "file": "src/api.ts",
     "validations": [
-      { "index": 0, "keep": true, "reason": "...", "adjustedSeverity": "high", "validationNotes": "..." }
+      { "index": 0, "keep": true, "notes": "User input flows to SQL query" }
     ]
   }
 ]
@@ -37771,13 +37990,18 @@ Remember: Be AGGRESSIVE in rejecting false positives. Use the full file context
             continue;
           }
           const filePath = fileResult.file;
-          const validations = fileResult.validations.filter((item) => typeof item.index === "number" && typeof item.keep === "boolean").map((item) => ({
-            index: item.index,
-            keep: item.keep,
-            reason: item.reason || "",
-            adjustedSeverity: item.adjustedSeverity || null,
-            validationNotes: item.validationNotes || void 0
-          }));
+          const validations = fileResult.validations.filter((item) => typeof item.index === "number" && typeof item.keep === "boolean").map((item) => {
+            const notes = item.notes || item.validationNotes || item.reason || void 0;
+            return {
+              index: item.index,
+              keep: item.keep,
+              notes,
+              adjustedSeverity: item.adjustedSeverity || null,
+              // Keep legacy fields for backward compatibility
+              reason: item.reason,
+              validationNotes: item.validationNotes
+            };
+          });
           resultMap.set(filePath, validations);
         }
         for (const expectedFile of expectedFiles) {
@@ -37810,18 +38034,19 @@ Remember: Be AGGRESSIVE in rejecting false positives. Use the full file context
             validatedByAI: true,
             confidence: "high"
           };
+          const validationNotes = validation.notes || validation.validationNotes || validation.reason || void 0;
           if (validation.adjustedSeverity && validation.adjustedSeverity !== finding.severity) {
             adjustedFinding.originalSeverity = finding.severity;
             adjustedFinding.severity = validation.adjustedSeverity;
             adjustedFinding.validationStatus = "downgraded";
-            adjustedFinding.validationNotes = validation.validationNotes || validation.reason || "Severity adjusted by AI validation";
+            adjustedFinding.validationNotes = validationNotes || "Severity adjusted by AI validation";
           } else {
             adjustedFinding.validationStatus = "confirmed";
-            adjustedFinding.validationNotes = validation.validationNotes || validation.reason;
+            adjustedFinding.validationNotes = validationNotes;
           }
           processed.push(adjustedFinding);
         } else {
-          console.log(`[AI Validation] Rejected: ${finding.title} at ${finding.filePath}:${finding.lineNumber} - ${validation.reason}`);
+          console.log(`[AI Validation] Rejected: ${finding.title} at ${finding.filePath}:${finding.lineNumber}`);
         }
       }
       return processed;
@@ -37894,13 +38119,18 @@ Remember: Be AGGRESSIVE in rejecting false positives. Use the full file context
         const parsed = JSON.parse(jsonSlice);
         if (!Array.isArray(parsed))
           return [];
-        return parsed.filter((item) => typeof item.index === "number" && typeof item.keep === "boolean").map((item) => ({
-          index: item.index,
-          keep: item.keep,
-          reason: item.reason || "",
-          adjustedSeverity: item.adjustedSeverity || null,
-          validationNotes: item.validationNotes || void 0
-        }));
+        return parsed.filter((item) => typeof item.index === "number" && typeof item.keep === "boolean").map((item) => {
+          const notes = item.notes || item.validationNotes || item.reason || void 0;
+          return {
+            index: item.index,
+            keep: item.keep,
+            notes,
+            adjustedSeverity: item.adjustedSeverity || null,
+            // Keep legacy fields for backward compatibility
+            reason: item.reason,
+            validationNotes: item.validationNotes
+          };
+        });
       } catch (error) {
         console.error("Failed to parse validation response:", error);
         return [];
@@ -43083,6 +43313,16 @@ function getApiBaseUrl() {
 function setAuthCredentials(apiKey, email, tier) {
   updateConfig({ apiKey, email, tier });
 }
+function syncAuthFromVerification(verifyResponse) {
+  if (!verifyResponse.valid) return;
+  const config = getConfig();
+  if (!config.apiKey) return;
+  const email = verifyResponse.email || config.email;
+  const tier = verifyResponse.tier || config.tier || "free";
+  if (tier !== config.tier || email !== config.email) {
+    setAuthCredentials(config.apiKey, email, tier);
+  }
+}
 
 // src/utils/api.ts
 var APIError = class extends Error {
@@ -43239,8 +43479,11 @@ function enhanceAPIError(error) {
     case 401:
       return {
         message: "Authentication required",
-        suggestion: "Run `oculum login` to authenticate, or use `--depth cheap` for free scans.",
+        suggestion: "You need to login to use AI-powered scans.",
         category: "auth",
+        errorCode: "OCU-E401",
+        quickFix: "oculum login",
+        learnMoreUrl: "https://oculum.dev/docs/authentication",
         recoveryActions: [
           { label: "Login", command: "oculum login", action: "login" },
           { label: "Use free scan", action: "fallback" }
@@ -43250,8 +43493,11 @@ function enhanceAPIError(error) {
       if (error.reason === "insufficient_tier") {
         return {
           message: "This feature requires a Pro subscription",
-          suggestion: "Visit https://oculum.dev/billing to upgrade your plan.",
+          suggestion: "Validated and deep scans require a Pro plan.",
           category: "auth",
+          errorCode: "OCU-E403-TIER",
+          quickFix: "oculum scan . --depth cheap",
+          learnMoreUrl: "https://oculum.dev/billing",
           recoveryActions: [
             { label: "View pricing", action: "upgrade" },
             { label: "Use free scan", action: "fallback" }
@@ -43261,8 +43507,11 @@ function enhanceAPIError(error) {
       if (error.reason === "expired") {
         return {
           message: "Your API key has expired",
-          suggestion: "Generate a new key at https://oculum.dev/dashboard/api-keys",
+          suggestion: "Generate a new key to continue using AI-powered scans.",
           category: "auth",
+          errorCode: "OCU-E403-EXP",
+          quickFix: "oculum login",
+          learnMoreUrl: "https://oculum.dev/dashboard/api-keys",
           recoveryActions: [
             { label: "Login again", command: "oculum login", action: "login" }
           ]
@@ -43271,8 +43520,11 @@ function enhanceAPIError(error) {
       if (error.reason === "invalid_key") {
         return {
           message: "Invalid API key",
-          suggestion: "Your API key is not recognized. Please login again or check your key.",
+          suggestion: "Your API key is not recognized.",
           category: "auth",
+          errorCode: "OCU-E403-KEY",
+          quickFix: "oculum login",
+          learnMoreUrl: "https://oculum.dev/dashboard/api-keys",
           recoveryActions: [
             { label: "Login", command: "oculum login", action: "login" },
             { label: "Use free scan", action: "fallback" }
@@ -43281,19 +43533,24 @@ function enhanceAPIError(error) {
       }
       return {
         message: "Access denied",
-        suggestion: "Check your API key permissions or run `oculum login` to re-authenticate.",
+        suggestion: "Check your API key permissions.",
         category: "auth",
+        errorCode: "OCU-E403",
+        quickFix: "oculum login",
         recoveryActions: [
           { label: "Login", command: "oculum login", action: "login" }
         ]
       };
     case 429:
       const rateLimitInfo = error.reason === "quota_exceeded" ? "You've reached your monthly scan quota." : "Too many requests in a short period.";
-      const rateLimitSuggestion = error.reason === "quota_exceeded" ? "Your quota resets at the start of next month. Upgrade to Pro for higher limits." : "Wait a moment and try again. Consider using --depth cheap for unlimited local scans.";
+      const rateLimitSuggestion = error.reason === "quota_exceeded" ? "Your quota resets at the start of next month." : "Wait a moment before trying again.";
       return {
         message: rateLimitInfo,
         suggestion: rateLimitSuggestion,
         category: "server",
+        errorCode: error.reason === "quota_exceeded" ? "OCU-E429-QUOTA" : "OCU-E429-RATE",
+        quickFix: "oculum scan . --depth cheap",
+        learnMoreUrl: "https://oculum.dev/dashboard/usage",
         recoveryActions: [
           { label: "Use free local scan", command: "oculum scan . --depth cheap", action: "fallback" },
           { label: "View usage & upgrade", action: "upgrade" },
@@ -43306,8 +43563,11 @@ function enhanceAPIError(error) {
     case 503:
       return {
         message: "Oculum servers are experiencing issues",
-        suggestion: "Try again in a few minutes. Check https://status.oculum.dev for updates.",
+        suggestion: "This is temporary. Try again in a few minutes.",
         category: "server",
+        errorCode: `OCU-E${error.statusCode}`,
+        quickFix: "oculum scan . --depth cheap",
+        learnMoreUrl: "https://status.oculum.dev",
         recoveryActions: [
           { label: "Retry", action: "retry" },
           { label: "Use free scan (offline)", action: "fallback" }
@@ -43316,15 +43576,22 @@ function enhanceAPIError(error) {
     case 504:
       return {
         message: "Request timed out",
-        suggestion: "The scan may be too large. Try scanning fewer files or use `--depth cheap`.",
+        suggestion: "The scan may be too large for the server.",
         category: "server",
+        errorCode: "OCU-E504",
+        quickFix: "oculum scan . --depth cheap",
+        learnMoreUrl: "https://oculum.dev/docs/troubleshooting#timeout",
         recoveryActions: [
           { label: "Retry", action: "retry" },
           { label: "Use quick scan", action: "fallback" }
         ]
       };
     default:
-      return { message: error.message, category: "unknown" };
+      return {
+        message: error.message,
+        category: "unknown",
+        errorCode: "OCU-E000"
+      };
   }
 }
 function detectNetworkErrorType(msg) {
@@ -43372,6 +43639,7 @@ function enhanceStandardError(error) {
       message: `Path not found: ${path2}`,
       suggestion: "Check that the path exists and is spelled correctly.",
       category: "file",
+      errorCode: "OCU-E001",
       details: "The file or directory does not exist at the specified location."
     };
   }
@@ -43380,15 +43648,33 @@ function enhanceStandardError(error) {
       message: "Permission denied",
       suggestion: "Check file permissions or try running with appropriate access.",
       category: "file",
+      errorCode: "OCU-E002",
       details: "You do not have permission to access this file or directory."
     };
   }
+  if (msg.includes("self-signed") || msg.includes("unable to verify") || msg.includes("certificate") && (msg.includes("invalid") || msg.includes("expired"))) {
+    return {
+      message: "SSL certificate error",
+      suggestion: "Your network may be intercepting HTTPS traffic (corporate proxy).",
+      category: "network",
+      errorCode: "OCU-E003",
+      quickFix: "oculum scan . --depth cheap",
+      learnMoreUrl: "https://oculum.dev/docs/troubleshooting#ssl",
+      recoveryActions: [
+        { label: "Use offline scan", command: "oculum scan . --depth cheap", action: "fallback" },
+        { label: "View help", action: "help" }
+      ]
+    };
+  }
   if (msg.includes("fetch failed") || msg.includes("network") || msg.includes("econnrefused") || msg.includes("enotfound") || msg.includes("etimedout") || msg.includes("econnreset") || msg.includes("socket")) {
     const { type, suggestion } = detectNetworkErrorType(msg);
     return {
       message: type,
       suggestion,
       category: "network",
+      errorCode: "OCU-E004",
+      quickFix: "oculum scan . --depth cheap",
+      learnMoreUrl: "https://oculum.dev/docs/troubleshooting#network",
       recoveryActions: [
         { label: "Retry", action: "retry" },
         { label: "Use offline scan", action: "fallback" }
@@ -43400,52 +43686,105 @@ function enhanceStandardError(error) {
       message: "Invalid configuration file",
       suggestion: "Check your config file for valid JSON syntax.",
       category: "file",
+      errorCode: "OCU-E005",
+      learnMoreUrl: "https://oculum.dev/docs/configuration",
       details: "The configuration file contains invalid JSON. Use a JSON validator to find the error."
     };
   }
   if (msg.includes("no scannable files")) {
     return {
       message: "No scannable files found",
-      suggestion: "Check that the path contains supported file types (.js, .ts, .py, .go, etc.)",
+      suggestion: "Check that the path contains supported file types.",
       category: "scan",
-      details: "Supported extensions: .js, .jsx, .ts, .tsx, .py, .go, .java, .rb, .php, .yaml, .json"
+      errorCode: "OCU-E006",
+      details: "Supported: .js, .jsx, .ts, .tsx, .py, .go, .java, .rb, .php, .yaml, .json"
     };
   }
   if (msg.includes("symlink") || msg.includes("eloop")) {
     return {
       message: "Symbolic link error",
       suggestion: "There may be a circular symlink. Try scanning a specific directory instead.",
-      category: "file"
+      category: "file",
+      errorCode: "OCU-E007"
     };
   }
   if (msg.includes("heap") || msg.includes("memory") || msg.includes("enomem")) {
     return {
       message: "Out of memory",
-      suggestion: "The scan ran out of memory. Try scanning fewer files or a smaller directory.",
-      category: "scan"
+      suggestion: "The scan ran out of memory. Try scanning fewer files.",
+      category: "scan",
+      errorCode: "OCU-E008",
+      quickFix: 'NODE_OPTIONS="--max-old-space-size=4096" oculum scan .',
+      learnMoreUrl: "https://oculum.dev/docs/troubleshooting#memory"
+    };
+  }
+  if (msg.includes("enospc") || msg.includes("no space left")) {
+    return {
+      message: "Disk full",
+      suggestion: "Free up disk space and try again.",
+      category: "file",
+      errorCode: "OCU-E009"
     };
   }
-  return { message: error.message, category: "unknown" };
+  return {
+    message: error.message,
+    category: "unknown",
+    errorCode: "OCU-E000",
+    learnMoreUrl: "https://oculum.dev/docs/troubleshooting"
+  };
 }
 function formatError(enhanced) {
-  let output = source_default.red(`Error: ${enhanced.message}`);
+  const icon = getErrorIcon(enhanced.category);
+  const lines = [];
+  if (enhanced.errorCode) {
+    lines.push(source_default.red.bold(`${icon} ${enhanced.errorCode} ${enhanced.message}`));
+  } else {
+    lines.push(source_default.red.bold(`${icon} ${enhanced.message}`));
+  }
+  lines.push("");
   if (enhanced.suggestion) {
-    output += "\n" + source_default.dim(`Tip: ${enhanced.suggestion}`);
+    lines.push(source_default.white(enhanced.suggestion));
   }
   if (enhanced.details) {
-    output += "\n" + source_default.gray(`Details: ${enhanced.details}`);
+    lines.push(source_default.dim(enhanced.details));
+  }
+  if (enhanced.quickFix) {
+    lines.push("");
+    lines.push(source_default.bold("Quick fix:"));
+    lines.push(source_default.cyan(`  $ ${enhanced.quickFix}`));
   }
   if (enhanced.recoveryActions && enhanced.recoveryActions.length > 0) {
-    output += "\n\n" + source_default.dim("Possible actions:");
+    lines.push("");
+    lines.push(source_default.dim("Or try:"));
     for (const action of enhanced.recoveryActions) {
       if (action.command) {
-        output += "\n  " + source_default.cyan(`\u2022 ${action.label}: `) + source_default.white(action.command);
+        lines.push(source_default.dim("  - ") + source_default.white(action.label + ": ") + source_default.cyan(action.command));
       } else {
-        output += "\n  " + source_default.cyan(`\u2022 ${action.label}`);
+        lines.push(source_default.dim("  - ") + source_default.white(action.label));
       }
     }
   }
-  return output;
+  if (enhanced.learnMoreUrl) {
+    lines.push("");
+    lines.push(source_default.dim("Need help? ") + source_default.cyan.underline(enhanced.learnMoreUrl));
+  }
+  return lines.join("\n");
+}
+function getErrorIcon(category) {
+  switch (category) {
+    case "network":
+      return "\u{1F310}";
+    case "auth":
+      return "\u{1F510}";
+    case "file":
+      return "\u{1F4C1}";
+    case "scan":
+      return "\u{1F50D}";
+    case "server":
+      return "\u{1F5A5}\uFE0F";
+    default:
+      return "\u274C";
+  }
 }
 
 // src/utils/project-config.ts
@@ -43863,6 +44202,13 @@ async function runScanOnce(targetPath, options) {
   const config = getConfig();
   const noColor = options.color === false;
   const cancellationToken = (0, import_scanner.createCancellationToken)();
+  if ((options.depth === "validated" || options.depth === "deep") && isAuthenticated()) {
+    try {
+      const verified = await verifyApiKey(config.apiKey);
+      syncAuthFromVerification(verified);
+    } catch {
+    }
+  }
   if ((options.depth === "validated" || options.depth === "deep") && !isAuthenticated()) {
     if (!options.quiet) {
       console.log("");
@@ -43946,7 +44292,7 @@ async function runScanOnce(targetPath, options) {
   }
   try {
     spinner.start("Starting scan...");
-    const hasLocalAI = !!process.env.ANTHROPIC_API_KEY;
+    const hasLocalAI = !!(process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY);
     if (options.depth !== "cheap" && isAuthenticated() && !hasLocalAI) {
       spinner.text = `Backend ${options.depth} scan analyzing ${files.length} files...`;
       result = await callBackendAPI(
@@ -44066,26 +44412,37 @@ async function runScan(targetPath, cliOptions) {
   }
 }
 var scanCommand = new Command("scan").description("Scan a directory or file for security vulnerabilities").argument("[path]", "path to scan", ".").option("-d, --depth <depth>", "scan depth: cheap (free), validated, deep", "cheap").option("-m, --mode <mode>", "alias for --depth (quick, validated, deep)").option("-f, --format <format>", "output format: terminal, json, sarif, markdown", "terminal").option("--fail-on <severity>", "exit with error code if findings at severity", "high").option("--no-color", "disable colored output").option("-q, --quiet", "minimal output for CI (suppress spinners and decorations)").option("-v, --verbose", "show detailed scanner logs (debug mode)").option("-o, --output <file>", "write output to file").option("--incremental", "only scan changed files (requires git)").option("--diff <ref>", "diff against branch/commit for incremental scan").addHelpText("after", `
+Scan Modes:
+  cheap       Free      Fast pattern matching, runs locally
+                        Best for: Quick checks, CI/CD pipelines
+
+  validated   ~$0.03    AI validates findings, ~70% fewer false positives
+                        Best for: Pre-commit checks, PR reviews
+
+  deep        ~$0.10    Full semantic analysis with AI reasoning
+                        Best for: Security audits, release checks
+
 Examples:
-  $ oculum scan .                    # Scan current directory (quick/free)
-  $ oculum scan ./src                # Scan specific directory
-  $ oculum scan . --mode validated   # AI-validated scan (Pro)
-  $ oculum scan . -d validated       # Same as above (--depth alias)
-  $ oculum scan . --incremental      # Diff scan vs HEAD (changed files only)
-  $ oculum scan . --incremental --mode validated  # Diff scan with AI validation
-  $ oculum scan . --diff origin/main --mode validated  # Diff vs base branch
-  $ oculum scan . -f sarif -o out    # Output SARIF for GitHub
-  $ oculum scan . --fail-on critical # Only fail on critical issues
-  $ oculum scan . -q                 # Quiet mode for CI/CD
-
-Scan Modes (--mode or --depth):
-  quick      Fast pattern matching, runs locally (free) [alias: cheap]
-  validated  AI validates findings, ~70% fewer false positives (Pro)
-  deep       Full semantic analysis with AI reasoning (Pro)
-
-Project Config:
-  Create oculum.config.json in your project root to set defaults:
-  { "depth": "cheap", "format": "terminal", "failOn": "high" }
+  $ oculum scan .                      Scan current directory (free)
+  $ oculum scan . -d validated         AI-validated scan
+  $ oculum scan ./src --fail-on high   Fail CI on high severity findings
+  $ oculum scan . -f sarif -o report   Export for GitHub Code Scanning
+  $ oculum scan . --incremental        Only scan changed files (git)
+  $ oculum scan . --diff origin/main   Compare against base branch
+  $ oculum scan . -q                   Quiet mode for CI/CD
+
+Configuration:
+  Create oculum.config.json in your project:
+  {
+    "depth": "validated",
+    "failOn": "high",
+    "ignore": ["**/test/**"]
+  }
+
+More Help:
+  $ oculum help scan-modes             Detailed mode comparison
+  $ oculum help ci-setup               CI/CD integration examples
+  $ oculum help config                 Full configuration options
 `).action(runScan);
 
 // src/commands/auth.ts
@@ -44211,7 +44568,10 @@ async function status() {
   spinner.succeed("  Authenticated");
   console.log("");
   const email = result.email || config.email || "unknown";
-  const tier = result.tier || config.tier || "free";
+  const tier = result.tier || "free";
+  if (tier !== config.tier || email !== config.email) {
+    setAuthCredentials(config.apiKey, email, tier);
+  }
   const tierBadge = tier === "pro" ? source_default.bgBlue.white(" PRO ") : tier === "enterprise" ? source_default.bgMagenta.white(" ENTERPRISE ") : source_default.bgGray.white(" FREE ");
   console.log(source_default.dim("  Email: ") + source_default.white(email));
   console.log(source_default.dim("  Plan:  ") + tierBadge);
@@ -44788,10 +45148,10 @@ var foreach = (val, fn) => {
     fn(val);
   }
 };
-var addAndConvert = (main2, prop, item) => {
-  let container = main2[prop];
+var addAndConvert = (main3, prop, item) => {
+  let container = main3[prop];
   if (!(container instanceof Set)) {
-    main2[prop] = container = /* @__PURE__ */ new Set([container]);
+    main3[prop] = container = /* @__PURE__ */ new Set([container]);
   }
   container.add(item);
 };
@@ -44803,12 +45163,12 @@ var clearItem = (cont) => (key) => {
     delete cont[key];
   }
 };
-var delFromSet = (main2, prop, item) => {
-  const container = main2[prop];
+var delFromSet = (main3, prop, item) => {
+  const container = main3[prop];
   if (container instanceof Set) {
     container.delete(item);
   } else if (container === item) {
-    delete main2[prop];
+    delete main3[prop];
   }
 };
 var isEmptySet = (val) => val instanceof Set ? val.size === 0 : !val;
@@ -46853,6 +47213,7 @@ var CONFIG_DIR3 = (0, import_path6.join)((0, import_os4.homedir)(), ".oculum");
 var STATE_FILE = (0, import_path6.join)(CONFIG_DIR3, "state.json");
 var DEFAULT_STATE = {
   onboardingComplete: false,
+  setupWizardComplete: false,
   totalScans: 0,
   welcomeShown: false
 };
@@ -46881,7 +47242,7 @@ function updateUserState(updates) {
 }
 function isFirstTimeUser() {
   const state = getUserState();
-  return !state.onboardingComplete && state.totalScans === 0;
+  return !state.setupWizardComplete && !state.onboardingComplete && state.totalScans === 0;
 }
 function shouldShowWelcome() {
   const state = getUserState();
@@ -47797,6 +48158,9 @@ async function runAuthFlow() {
         const verified = await verifyApiKey(config.apiKey);
         if (verified.valid && verified.tier) {
           currentTier = verified.tier;
+          if (currentTier !== config.tier || verified.email && verified.email !== config.email) {
+            setAuthCredentials(config.apiKey, verified.email || config.email, currentTier);
+          }
         }
       } catch {
       }
@@ -47826,9 +48190,14 @@ async function runAuthFlow() {
           s.stop("Stored credentials are invalid or expired.");
           continue;
         }
+        const email = verified.email || getConfig().email || "unknown";
+        const tier = verified.tier || "free";
+        if (tier !== getConfig().tier || email !== getConfig().email) {
+          setAuthCredentials(getConfig().apiKey, email, tier);
+        }
         s.stop("Authenticated");
-        M2.info(`Email: ${verified.email || getConfig().email || "unknown"}`);
-        M2.info(`Tier: ${verified.tier || getConfig().tier || "unknown"}`);
+        M2.info(`Email: ${email}`);
+        M2.info(`Tier: ${tier}`);
       } catch (err) {
         s.stop("Verification failed");
         M2.error(String(err));
@@ -48397,9 +48766,251 @@ function getTimeAgo2(date) {
 }
 var usageCommand = new Command("usage").description("Show current usage and quota").option("--json", "Output as JSON").action(usage);
 
+// src/commands/help.ts
+var TOPICS = {
+  "scan-modes": showScanModes,
+  "ci-setup": showCISetup,
+  "config": showConfig,
+  "troubleshooting": showTroubleshooting
+};
+var helpCommand = new Command("help").description("Get detailed help on specific topics").argument("[topic]", "Help topic (scan-modes, ci-setup, config, troubleshooting)").action(async (topic) => {
+  if (!topic) {
+    showTopicList();
+    return;
+  }
+  const normalizedTopic = topic.toLowerCase().replace(/_/g, "-");
+  if (normalizedTopic in TOPICS) {
+    TOPICS[normalizedTopic]();
+  } else {
+    console.log(source_default.red(`Unknown topic: ${topic}
+`));
+    showTopicList();
+  }
+});
+function showTopicList() {
+  console.log(source_default.bold("\nOculum Help Topics\n"));
+  console.log(source_default.dim("\u2500".repeat(50)));
+  console.log();
+  console.log(source_default.cyan("  scan-modes      ") + source_default.white("Compare cheap, validated, and deep scans"));
+  console.log(source_default.cyan("  ci-setup        ") + source_default.white("GitHub Actions and GitLab CI examples"));
+  console.log(source_default.cyan("  config          ") + source_default.white("Configuration file documentation"));
+  console.log(source_default.cyan("  troubleshooting ") + source_default.white("Common issues and solutions"));
+  console.log();
+  console.log(source_default.dim("\u2500".repeat(50)));
+  console.log(source_default.dim("\nUsage: oculum help <topic>"));
+  console.log(source_default.dim("Example: oculum help scan-modes\n"));
+}
+function showScanModes() {
+  console.log(source_default.bold("\nScan Modes Comparison\n"));
+  console.log(source_default.dim("\u2500".repeat(60) + "\n"));
+  console.log(source_default.green.bold("  CHEAP (Quick Scan)"));
+  console.log(source_default.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(source_default.white("  Cost:       ") + source_default.green("Free"));
+  console.log(source_default.white("  Speed:      ") + source_default.white("~1000 files/second"));
+  console.log(source_default.white("  How:        ") + source_default.dim("Pattern matching + entropy analysis"));
+  console.log(source_default.white("  Best for:   ") + source_default.dim("Quick checks, CI/CD pipelines"));
+  console.log(source_default.white("  Limitation: ") + source_default.dim("May have more false positives\n"));
+  console.log(source_default.blue.bold("  VALIDATED"));
+  console.log(source_default.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(source_default.white("  Cost:       ") + source_default.yellow("~$0.03 per 300 files"));
+  console.log(source_default.white("  Speed:      ") + source_default.white("~30 seconds for 300 files"));
+  console.log(source_default.white("  How:        ") + source_default.dim("Pattern matching + AI validation"));
+  console.log(source_default.white("  Best for:   ") + source_default.dim("Pre-commit checks, PR reviews"));
+  console.log(source_default.white("  Benefit:    ") + source_default.dim("~70% fewer false positives\n"));
+  console.log(source_default.magenta.bold("  DEEP"));
+  console.log(source_default.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  console.log(source_default.white("  Cost:       ") + source_default.yellow("~$0.10 per 300 files"));
+  console.log(source_default.white("  Speed:      ") + source_default.white("~60 seconds for 300 files"));
+  console.log(source_default.white("  How:        ") + source_default.dim("Full semantic analysis with AI reasoning"));
+  console.log(source_default.white("  Best for:   ") + source_default.dim("Security audits, release checks"));
+  console.log(source_default.white("  Benefit:    ") + source_default.dim("Deepest analysis, remediation advice\n"));
+  console.log(source_default.dim("\u2500".repeat(60)));
+  console.log(source_default.bold("\nUsage Examples:\n"));
+  console.log(source_default.dim("  $ oculum scan .                ") + source_default.white("# Quick scan (free)"));
+  console.log(source_default.dim("  $ oculum scan . -d validated   ") + source_default.white("# AI-validated scan"));
+  console.log(source_default.dim("  $ oculum scan . -d deep        ") + source_default.white("# Deep semantic analysis"));
+  console.log();
+}
+function showCISetup() {
+  console.log(source_default.bold("\nCI/CD Integration\n"));
+  console.log(source_default.dim("\u2500".repeat(60) + "\n"));
+  console.log(source_default.bold("  GitHub Actions\n"));
+  console.log(source_default.dim("  Create .github/workflows/oculum.yml:\n"));
+  console.log(source_default.cyan(`  name: Security Scan
+  on: [push, pull_request]
+  jobs:
+    scan:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+        - run: npm install -g oculum
+        - run: oculum scan . --fail-on high
+          env:
+            OCULUM_API_KEY: \${{ secrets.OCULUM_API_KEY }}`));
+  console.log(source_default.dim("\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+  console.log(source_default.bold("  GitLab CI\n"));
+  console.log(source_default.dim("  Add to .gitlab-ci.yml:\n"));
+  console.log(source_default.cyan(`  security-scan:
+    image: node:20
+    script:
+      - npm install -g oculum
+      - oculum scan . --fail-on high
+    variables:
+      OCULUM_API_KEY: $OCULUM_API_KEY`));
+  console.log(source_default.dim("\n\u2500".repeat(60)));
+  console.log(source_default.bold("\nTips:\n"));
+  console.log(source_default.white("  - Use ") + source_default.cyan("--fail-on high") + source_default.white(" to fail builds on high/critical findings"));
+  console.log(source_default.white("  - Use ") + source_default.cyan("--format sarif") + source_default.white(" for GitHub Code Scanning integration"));
+  console.log(source_default.white("  - Use ") + source_default.cyan("-d cheap") + source_default.white(" for fastest scans (free, no API key needed)"));
+  console.log(source_default.white("  - Store API key in secrets, not in code\n"));
+}
+function showConfig() {
+  console.log(source_default.bold("\nConfiguration Files\n"));
+  console.log(source_default.dim("\u2500".repeat(60) + "\n"));
+  console.log(source_default.bold("  Project Config (oculum.config.json)\n"));
+  console.log(source_default.dim("  Create in your project root:\n"));
+  console.log(source_default.cyan(`  {
+    "depth": "validated",
+    "failOn": "high",
+    "format": "terminal",
+    "ignore": [
+      "**/node_modules/**",
+      "**/dist/**",
+      "**/*.test.ts"
+    ],
+    "include": [
+      "src/**"
+    ],
+    "watch": {
+      "debounce": 500,
+      "clear": true
+    }
+  }`));
+  console.log(source_default.dim("\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+  console.log(source_default.bold("  Config Options\n"));
+  console.log(source_default.white("  depth      ") + source_default.dim("Scan depth: cheap | validated | deep"));
+  console.log(source_default.white("  failOn     ") + source_default.dim("Exit code 1 on: critical | high | medium | low | none"));
+  console.log(source_default.white("  format     ") + source_default.dim("Output format: terminal | json | sarif | markdown"));
+  console.log(source_default.white("  output     ") + source_default.dim("Output file path"));
+  console.log(source_default.white("  quiet      ") + source_default.dim("Only show findings (boolean)"));
+  console.log(source_default.white("  ignore     ") + source_default.dim("Glob patterns to exclude"));
+  console.log(source_default.white("  include    ") + source_default.dim("Glob patterns to include"));
+  console.log(source_default.dim("\n  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+  console.log(source_default.bold("  Config File Priority\n"));
+  console.log(source_default.dim("  CLI flags > Project config > User config > Defaults\n"));
+  console.log(source_default.white("  Supported filenames:"));
+  console.log(source_default.dim("    - oculum.config.json"));
+  console.log(source_default.dim("    - .oculumrc.json"));
+  console.log(source_default.dim("    - .oculumrc\n"));
+}
+function showTroubleshooting() {
+  console.log(source_default.bold("\nTroubleshooting\n"));
+  console.log(source_default.dim("\u2500".repeat(60) + "\n"));
+  console.log(source_default.red.bold("  Authentication Errors\n"));
+  console.log(source_default.white('  "Authentication required"'));
+  console.log(source_default.dim("    \u2192 Run `oculum login` to authenticate"));
+  console.log(source_default.dim("    \u2192 Or use `--depth cheap` for free local scans\n"));
+  console.log(source_default.white('  "API key invalid or expired"'));
+  console.log(source_default.dim("    \u2192 Run `oculum login` to re-authenticate"));
+  console.log(source_default.dim("    \u2192 Check key at https://oculum.dev/dashboard/api-keys\n"));
+  console.log(source_default.white('  "Insufficient tier"'));
+  console.log(source_default.dim("    \u2192 Validated/deep scans require Pro subscription"));
+  console.log(source_default.dim("    \u2192 Visit https://oculum.dev/billing to upgrade\n"));
+  console.log(source_default.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+  console.log(source_default.yellow.bold("  Network Errors\n"));
+  console.log(source_default.white('  "Connection refused" / "Network error"'));
+  console.log(source_default.dim("    \u2192 Check your internet connection"));
+  console.log(source_default.dim("    \u2192 Use `--depth cheap` for offline scans"));
+  console.log(source_default.dim("    \u2192 Check https://status.oculum.dev\n"));
+  console.log(source_default.white('  "SSL certificate error"'));
+  console.log(source_default.dim("    \u2192 Corporate proxy may be intercepting HTTPS"));
+  console.log(source_default.dim("    \u2192 Use `--depth cheap` for offline scans"));
+  console.log(source_default.dim("    \u2192 Contact IT for proxy configuration\n"));
+  console.log(source_default.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+  console.log(source_default.blue.bold("  Scan Issues\n"));
+  console.log(source_default.white('  "No scannable files found"'));
+  console.log(source_default.dim("    \u2192 Check path exists: ls <path>"));
+  console.log(source_default.dim("    \u2192 Ensure files have supported extensions"));
+  console.log(source_default.dim("    \u2192 Check .gitignore isn't excluding files\n"));
+  console.log(source_default.white('  "Request timed out"'));
+  console.log(source_default.dim("    \u2192 Try scanning fewer files"));
+  console.log(source_default.dim("    \u2192 Use `--depth cheap` for large codebases"));
+  console.log(source_default.dim("    \u2192 Split into multiple scans\n"));
+  console.log(source_default.white('  "Out of memory"'));
+  console.log(source_default.dim("    \u2192 Scan a smaller directory"));
+  console.log(source_default.dim('    \u2192 Increase Node memory: NODE_OPTIONS="--max-old-space-size=4096"\n'));
+  console.log(source_default.dim("\u2500".repeat(60)));
+  console.log(source_default.bold("\nStill stuck?\n"));
+  console.log(source_default.white("  - Check docs: ") + source_default.cyan("https://oculum.dev/docs"));
+  console.log(source_default.white("  - Report issues: ") + source_default.cyan("https://github.com/oculum-dev/oculum/issues"));
+  console.log(source_default.white("  - Get support: ") + source_default.cyan("support@oculum.dev\n"));
+}
+
+// src/utils/ci-detect.ts
+var CI_ENV_VARS = [
+  "CI",
+  // Generic CI flag (GitHub Actions, GitLab CI, etc.)
+  "GITHUB_ACTIONS",
+  // GitHub Actions
+  "GITLAB_CI",
+  // GitLab CI
+  "JENKINS_URL",
+  // Jenkins
+  "CIRCLECI",
+  // CircleCI
+  "TRAVIS",
+  // Travis CI
+  "BUILDKITE",
+  // Buildkite
+  "DRONE",
+  // Drone CI
+  "TEAMCITY_VERSION",
+  // TeamCity
+  "BITBUCKET_COMMIT",
+  // Bitbucket Pipelines
+  "AZURE_HTTP_USER_AGENT",
+  // Azure Pipelines
+  "TF_BUILD",
+  // Azure Pipelines (alternative)
+  "CODEBUILD_BUILD_ID",
+  // AWS CodeBuild
+  "APPVEYOR",
+  // AppVeyor
+  "SEMAPHORE",
+  // Semaphore CI
+  "HEROKU_TEST_RUN_ID",
+  // Heroku CI
+  "RENDER",
+  // Render
+  "VERCEL",
+  // Vercel
+  "NETLIFY",
+  // Netlify
+  "CF_PAGES",
+  // Cloudflare Pages
+  "RAILWAY_ENVIRONMENT"
+  // Railway
+];
+function isCI() {
+  return CI_ENV_VARS.some((envVar) => !!process.env[envVar]);
+}
+function isInteractiveTerminal() {
+  return !!(process.stdin.isTTY && !isCI());
+}
+
 // src/index.ts
+function shouldRunUI() {
+  const programName = process.argv[1] || "";
+  const args = process.argv.slice(2);
+  const isOcAlias = programName.endsWith("oc") && !programName.endsWith("oculum");
+  const isUICommand = args.length === 0 || args.length === 1 && args[0] === "ui";
+  return isOcAlias || isUICommand;
+}
 var program2 = new Command();
-program2.name("oculum").description("AI-native security scanner for detecting vulnerabilities in LLM-generated code").version("1.0.7").addHelpText("after", `
+program2.name("oculum").description("AI-native security scanner for detecting vulnerabilities in LLM-generated code").version("1.0.9").addHelpText("after", `
 Quick Start:
   $ oculum scan .          Scan current directory (free)
   $ oculum ui              Interactive mode with guided setup
@@ -48412,11 +49023,13 @@ Common Commands:
   login                    Authenticate with Oculum
   status                   Check authentication status
   usage                    View credits and quota
+  help [topic]             Get help on specific topics
 
 Learn More:
   $ oculum scan --help     Detailed scan options
+  $ oculum help scan-modes Compare scan depth options
   $ oculum --help          All available commands
-  
+
 Documentation: https://oculum.dev/docs
 `);
 program2.addCommand(scanCommand, { isDefault: true });
@@ -48427,7 +49040,17 @@ program2.addCommand(upgradeCommand);
 program2.addCommand(usageCommand);
 program2.addCommand(watchCommand);
 program2.addCommand(uiCommand);
-program2.parse();
+program2.addCommand(helpCommand);
+async function main2() {
+  const interactive = isInteractiveTerminal();
+  if (interactive && shouldRunUI()) {
+    process.argv = ["node", "oculum", "ui"];
+    program2.parse();
+    return;
+  }
+  program2.parse();
+}
+main2();
 /*! Bundled license information:
 
 chokidar/esm/index.js:

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@oculum/cli",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "AI-native security scanner CLI for detecting vulnerabilities in AI-generated code, BYOK patterns, and modern web applications",
   "main": "dist/index.js",
   "bin": {
-    "oculum": "./dist/index.js"
+    "oculum": "./dist/index.js",
+    "oc": "./dist/index.js"
   },
   "author": "Felix Westin <felix.lwestin@gmail.com>",
   "license": "MIT",
@@ -18,7 +19,7 @@
     "url": "https://github.com/flexipie/oculum/issues"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --banner:js=\"#!/usr/bin/env node\" --define:process.env.OCULUM_API_URL='undefined' --define:VERSION='\"1.0.8\"'",
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --outfile=dist/index.js --banner:js=\"#!/usr/bin/env node\" --define:process.env.OCULUM_API_URL='undefined' --define:VERSION='\"1.0.9\"'",
     "dev": "npm run build -- --watch",
     "test": "echo \"No tests configured yet\"",
     "lint": "eslint src/"