icoa-cli 2.19.8 → 2.19.9

package/dist/commands/ctf.js

@@ -151,10 +151,29 @@ export function registerCtfCommands(program) {
             console.log();
             printSuccess('Connection saved. You are ready!');
             console.log();
-            console.log(chalk.gray('  Next:'));
-            console.log(chalk.white('    exam list      ') + chalk.gray('View available exams'));
-            console.log(chalk.white('    challenges     ') + chalk.gray('View CTF challenges'));
-            console.log(chalk.white('    status         ') + chalk.gray('Check score & budget'));
+            const currentMode = getConfig().mode || '';
+            if (currentMode === 'olympiad') {
+                // Olympiad: guided step-by-step walkthrough
+                console.log(chalk.cyan('  ─────────────────────────────────────────────'));
+                console.log(chalk.bold.white('  How to compete:'));
+                console.log();
+                console.log(chalk.white('  Step 1  ') + chalk.bold.cyan('challenges') + chalk.gray('         Browse all challenges'));
+                console.log(chalk.white('  Step 2  ') + chalk.bold.cyan('open <id>') + chalk.gray('          Read challenge details'));
+                console.log(chalk.white('  Step 3  ') + chalk.bold.cyan('hint "your question"') + chalk.gray(' Ask AI for help'));
+                console.log(chalk.white('  Step 4  ') + chalk.bold.cyan('submit <id> <flag>') + chalk.gray('  Submit your answer'));
+                console.log();
+                console.log(chalk.gray('  More:'));
+                console.log(chalk.white('    scoreboard') + chalk.gray('     Live rankings'));
+                console.log(chalk.white('    status') + chalk.gray('         Your score & hint budget'));
+                console.log(chalk.white('    ai4ctf') + chalk.gray('         Free-chat with AI teammate'));
+                console.log(chalk.cyan('  ─────────────────────────────────────────────'));
+            }
+            else {
+                console.log(chalk.gray('  Next:'));
+                console.log(chalk.white('    exam list      ') + chalk.gray('View available exams'));
+                console.log(chalk.white('    challenges     ') + chalk.gray('View CTF challenges'));
+                console.log(chalk.white('    status         ') + chalk.gray('Check score & budget'));
+            }
         }
         catch (err) {
             spinner2.fail('Connection test failed');
@@ -181,6 +200,11 @@ export function registerCtfCommands(program) {
             country: '',
         });
         printSuccess('Logged out. Credentials cleared.');
+        console.log();
+        console.log(chalk.gray('  What now?'));
+        console.log(chalk.white('    join <url>') + chalk.gray('      Re-connect to competition'));
+        console.log(chalk.white('    setup') + chalk.gray('           Switch mode'));
+        console.log(chalk.white('    exit') + chalk.gray('            Quit ICOA CLI'));
     });
     // ─── icoa ctf activate <code> ───
     ctf
@@ -251,24 +275,54 @@ export function registerCtfCommands(program) {
             }
             const solved = challenges.filter((c) => c.solved_by_me).length;
             printHeader(`Challenges (${solved}/${challenges.length} solved)`);
+            // Category descriptions for beginners
+            const catDesc = {
+                'Web': 'Find vulnerabilities in websites',
+                'Crypto': 'Break ciphers & encryption',
+                'Reversing': 'Analyze compiled programs',
+                'Rev': 'Analyze compiled programs',
+                'Pwn': 'Exploit binary vulnerabilities',
+                'Forensics': 'Investigate digital evidence',
+                'Misc': 'Creative & mixed challenges',
+                'OSINT': 'Open-source intelligence gathering',
+                'AI': 'AI security & adversarial ML',
+            };
+            // Difficulty based on points
+            const difficulty = (pts) => {
+                if (pts <= 100)
+                    return chalk.green('Easy');
+                if (pts <= 250)
+                    return chalk.yellow('Medium');
+                if (pts <= 500)
+                    return chalk.red('Hard');
+                return chalk.magenta('Expert');
+            };
             // Sort categories and display
             const rows = [...byCategory.entries()]
                 .sort(([a], [b]) => a.localeCompare(b))
                 .flatMap(([category, challs]) => {
-                const catRow = [chalk.cyan.bold(`── ${category} ──`), '', '', '', ''];
+                const desc = catDesc[category] || '';
+                const catLabel = desc
+                    ? chalk.cyan.bold(`── ${category} ──`) + ' ' + chalk.gray(desc)
+                    : chalk.cyan.bold(`── ${category} ──`);
+                const catRow = [catLabel, '', '', '', ''];
                 const challRows = challs
                     .sort((a, b) => a.value - b.value)
                     .map((c) => [
                     String(c.id),
                     c.solved_by_me ? chalk.gray.strikethrough(c.name) : c.name,
-                    chalk.gray(c.category),
                     c.solved_by_me ? chalk.gray(String(c.value)) : chalk.yellow(String(c.value)),
+                    c.solved_by_me ? chalk.gray('--') : difficulty(c.value),
                     c.solved_by_me ? chalk.green('✓') : chalk.gray('○'),
                 ]);
                 return [catRow, ...challRows];
             });
-            printTable(['#', 'Name', 'Category', 'Points', 'Solved'], rows);
+            printTable(['#', 'Name', 'Points', 'Difficulty', 'Solved'], rows);
             console.log(chalk.gray(`  ${challenges.length} challenges, ${solved} solved`));
+            if (solved === 0) {
+                console.log();
+                console.log(chalk.gray('  Tip: Start with ') + chalk.green('Easy') + chalk.gray(' challenges! Type ') + chalk.white('open <id>') + chalk.gray(' to read one.'));
+            }
         }
         catch (err) {
             spinner.fail('Failed to load challenges');
@@ -325,9 +379,19 @@ export function registerCtfCommands(program) {
                 console.log();
                 printInfo(`Quick connect: ${chalk.white(`connect ${id}`)}`);
             }
-            // Show helpful next actions
+            // Show guided next actions
             console.log();
-            console.log(chalk.gray(`  Next: hint "how to approach this?" | submit ${id} "icoa{flag}"`));
+            console.log(chalk.gray('  ─────────────────────────────────────────────'));
+            console.log(chalk.bold.white('  What to do next:'));
+            console.log(chalk.white(`    hint "how to start?"`) + chalk.gray('   Ask AI for guidance (Level A)'));
+            if (challenge.files && challenge.files.length > 0) {
+                console.log(chalk.white(`    files ${id}`) + chalk.gray('                Download challenge files'));
+            }
+            if (challenge.connection_info) {
+                console.log(chalk.white(`    connect ${id}`) + chalk.gray('              Connect to target'));
+            }
+            console.log(chalk.white(`    submit ${id} icoa{flag}`) + chalk.gray('   Submit your answer'));
+            console.log(chalk.gray('  ─────────────────────────────────────────────'));
         }
         catch (err) {
             spinner.fail('Failed to load challenge');

package/dist/commands/hint.js

@@ -1,10 +1,9 @@
 import chalk from 'chalk';
-import { confirm } from '@inquirer/prompts';
 import { generateHint } from '../lib/gemini.js';
 import { checkBudget, deductBudget, getBudgetDisplay, isTokenCapReached } from '../lib/budget.js';
 import { getConfig } from '../lib/config.js';
 import { logHint } from '../lib/logger.js';
-import { printError, printInfo, printMarkdown, printHeader, createSpinner } from '../lib/ui.js';
+import { printError, printMarkdown, printHeader, createSpinner } from '../lib/ui.js';
 function getChallengeContext() {
     const config = getConfig();
     if (config.currentChallengeName && config.currentChallengeCategory) {
@@ -28,16 +27,9 @@ async function handleHint(level, question) {
         printError(`Level ${level} hint budget exhausted (0 remaining).`);
         return;
     }
-    // Level C confirmation
+    // Level C warning (no confirm — crashes REPL)
     if (level === 'C') {
-        const proceed = await confirm({
-            message: `This will consume 1 of your ${remaining} remaining Critical Assists. Continue?`,
-            default: false,
-        });
-        if (!proceed) {
-            printInfo('Cancelled.');
-            return;
-        }
+        console.log(chalk.red.bold(`  Warning: Using 1 of ${remaining} Critical Assists remaining.`));
     }
     // Log BEFORE API call
     logHint(level, question, config.currentChallengeId || undefined);
@@ -56,8 +48,23 @@ async function handleHint(level, question) {
         deductBudget(level, result.tokensUsed);
         printHeader(`Level ${level} Hint — ${levelNames[level]}`);
         printMarkdown(result.text);
+        // Budget summary after hint
+        const afterBudget = checkBudget(level);
         console.log();
-        console.log(chalk.gray(`  Tokens used: ${result.tokensUsed} | Level ${level} remaining: ${checkBudget(level).remaining}`));
+        console.log(chalk.gray('  ─────────────────────────────────────────────'));
+        console.log(chalk.gray(`  Tokens used: ${result.tokensUsed} | Level ${level} remaining: ${afterBudget.remaining}`));
+        // Suggest next level if stuck
+        if (level === 'A') {
+            const bBudget = checkBudget('B');
+            console.log(chalk.gray('  Need more detail? ') + chalk.white('hint-b "your question"') + chalk.gray(` (${bBudget.remaining} left)`));
+        }
+        else if (level === 'B') {
+            const cBudget = checkBudget('C');
+            if (cBudget.remaining > 0) {
+                console.log(chalk.gray('  Still stuck? ') + chalk.white('hint-c "your question"') + chalk.gray(` (${cBudget.remaining} Critical Assists left)`));
+            }
+        }
+        console.log(chalk.gray('  ─────────────────────────────────────────────'));
         console.log();
     }
     catch (err) {
@@ -69,6 +76,11 @@ function showBudget() {
     printHeader('Hint Budget');
     console.log(getBudgetDisplay());
     console.log();
+    console.log(chalk.gray('  How to use hints:'));
+    console.log(chalk.white('    hint "what is XSS?"') + chalk.gray('          Level A — General guidance'));
+    console.log(chalk.white('    hint-b "analyze this code"') + chalk.gray('   Level B — Deep analysis'));
+    console.log(chalk.white('    hint-c "I\'m completely stuck"') + chalk.gray(' Level C — Critical assist'));
+    console.log();
 }
 export function registerHintCommands(program) {
     // ─── icoa hint <question> ───

package/dist/repl.js

@@ -236,34 +236,49 @@ export async function startRepl(program, resumeMode) {
             console.log();
         }
         else if (connected) {
-            console.log(chalk.green(`   Welcome back, ${config.userName}!`));
+            console.log(chalk.green.bold(`   Welcome back, ${config.userName}!`));
             console.log(chalk.gray(`   Connected to ${config.ctfdUrl}`));
-            console.log(chalk.gray('   logout to disconnect'));
+            console.log();
+            console.log(chalk.gray('   ─────────────────────────────────────────────'));
+            console.log(chalk.white('   Ready to compete? Start here:'));
+            console.log();
+            console.log(chalk.bold.cyan('     challenges') + chalk.gray('     Browse challenges by category'));
+            console.log(chalk.white('     status') + chalk.gray('         Your score & hint budget'));
+            console.log(chalk.white('     scoreboard') + chalk.gray('     Live rankings'));
+            console.log(chalk.white('     help') + chalk.gray('           Full command list'));
+            console.log(chalk.gray('   ─────────────────────────────────────────────'));
             console.log();
         }
         else if (activated) {
             ensureWorkspace();
-            console.log(chalk.green('   Welcome, competitor! Ready to hack.'));
+            console.log(chalk.green.bold('   Welcome, competitor!'));
             console.log(chalk.gray(`   Workspace: ${WORKSPACE}`));
             console.log();
-            console.log(chalk.gray('   Quick Start'));
-            console.log(chalk.gray('   ─────────────'));
-            console.log(chalk.white('   join <url>       ') + chalk.gray('Connect to competition'));
-            console.log(chalk.white('   challenges       ') + chalk.gray('View challenges'));
-            console.log(chalk.white('   hint <question>  ') + chalk.gray('Ask AI for help'));
-            console.log(chalk.white('   env              ') + chalk.gray('Check your tools'));
-            console.log(chalk.white('   help             ') + chalk.gray('All commands'));
+            console.log(chalk.gray('   ─────────────────────────────────────────────'));
+            console.log(chalk.white('   Get started:'));
+            console.log();
+            console.log(chalk.white('   Step 1  ') + chalk.bold.cyan('join <url>') + chalk.gray('   Connect to competition server'));
+            console.log(chalk.white('   Step 2  ') + chalk.bold.cyan('challenges') + chalk.gray('   Browse & solve challenges'));
+            console.log(chalk.white('   Step 3  ') + chalk.bold.cyan('hint') + chalk.gray('         Ask AI when stuck'));
+            console.log();
+            console.log(chalk.gray('   Also: ') + chalk.white('env') + chalk.gray(' check tools  ') + chalk.white('help') + chalk.gray(' all commands'));
+            console.log(chalk.gray('   ─────────────────────────────────────────────'));
             console.log();
         }
         else {
-            console.log(chalk.white('   Welcome to ICOA CLI!'));
+            console.log(chalk.bold.white('   Welcome to ICOA CLI — International Olympiad'));
+            console.log();
+            console.log(chalk.gray('   ─────────────────────────────────────────────'));
+            console.log(chalk.white('   To begin, activate your competition token:'));
             console.log();
-            console.log(chalk.gray('   Quick Start'));
-            console.log(chalk.gray('   ─────────────'));
-            console.log(chalk.white('   activate <token> ') + chalk.gray('Unlock with your access token'));
-            console.log(chalk.white('   ref <topic>      ') + chalk.gray('Browse tool references'));
-            console.log(chalk.white('   env              ') + chalk.gray('Check your tools'));
-            console.log(chalk.white('   help             ') + chalk.gray('All commands'));
+            console.log(chalk.bold.cyan('     activate <token>'));
+            console.log();
+            console.log(chalk.gray('   While waiting, explore:'));
+            console.log(chalk.white('     ref linux') + chalk.gray('       Quick reference for Linux'));
+            console.log(chalk.white('     ref web') + chalk.gray('         Quick reference for Web'));
+            console.log(chalk.white('     env') + chalk.gray('             Check your tools'));
+            console.log(chalk.white('     help') + chalk.gray('            All available commands'));
+            console.log(chalk.gray('   ─────────────────────────────────────────────'));
             console.log();
         }
     }
@@ -729,33 +744,35 @@ function printReplHelp(activated, mode = 'olympiad') {
         console.log();
         return;
     }
+    // How it works — workflow overview
+    console.log(chalk.cyan('  ═══════════════════════════════════════════════'));
+    console.log(chalk.bold.white('  How it works'));
+    console.log();
+    console.log(chalk.gray('  1. Browse ') + chalk.white('challenges') + chalk.gray(' and pick one'));
+    console.log(chalk.gray('  2. ') + chalk.white('open <id>') + chalk.gray(' to read the challenge'));
+    console.log(chalk.gray('  3. Use ') + chalk.white('hint') + chalk.gray(' / ') + chalk.white('hint-b') + chalk.gray(' / ') + chalk.white('hint-c') + chalk.gray(' when stuck'));
+    console.log(chalk.gray('  4. ') + chalk.white('submit <id> icoa{flag}') + chalk.gray(' to score points'));
+    console.log(chalk.gray('  5. Check ') + chalk.white('scoreboard') + chalk.gray(' to track your rank'));
+    console.log(chalk.cyan('  ═══════════════════════════════════════════════'));
+    console.log();
     console.log(chalk.bold.white('  Competition'));
     console.log(chalk.white('    join <url>          ') + chalk.gray('Connect to CTFd'));
-    console.log(chalk.white('    challenges (ch)     ') + chalk.gray('List challenges'));
-    console.log(chalk.white('    open <id>           ') + chalk.gray('View challenge details'));
+    console.log(chalk.white('    challenges (ch)     ') + chalk.gray('List challenges by category'));
+    console.log(chalk.white('    open <id>           ') + chalk.gray('Read challenge + get next steps'));
     console.log(chalk.white('    submit <id> <flag>  ') + chalk.gray('Submit a flag'));
-    console.log(chalk.white('    scoreboard (sb)     ') + chalk.gray('View scoreboard'));
-    console.log(chalk.white('    status              ') + chalk.gray('Competition status'));
+    console.log(chalk.white('    scoreboard (sb)     ') + chalk.gray('Live rankings'));
+    console.log(chalk.white('    status              ') + chalk.gray('Your score, budget & timer'));
     console.log(chalk.white('    time                ') + chalk.gray('Countdown timer'));
     console.log();
-    console.log(chalk.bold.white('  Exam'));
-    console.log(chalk.white('    exam list           ') + chalk.gray('Available exams'));
-    console.log(chalk.white('    exam start <id>     ') + chalk.gray('Begin an exam'));
-    console.log(chalk.white('    exam q [n]          ') + chalk.gray('View questions'));
-    console.log(chalk.white('    exam answer <n> <X> ') + chalk.gray('Answer question'));
-    console.log(chalk.white('    exam review         ') + chalk.gray('Review all answers'));
-    console.log(chalk.white('    exam submit         ') + chalk.gray('Submit for grading'));
-    console.log(chalk.white('    exam result         ') + chalk.gray('View your score'));
-    console.log();
-    console.log(chalk.bold.white('  AI'));
-    console.log(chalk.white('    ai4ctf              ') + chalk.gray('Chat with your AI teammate'));
-    console.log(chalk.white('    hint <question>     ') + chalk.gray('Level A — General guidance'));
-    console.log(chalk.white('    hint-b <question>   ') + chalk.gray('Level B — Deep analysis'));
-    console.log(chalk.white('    hint-c <question>   ') + chalk.gray('Level C — Critical assist'));
-    console.log(chalk.white('    hint budget         ') + chalk.gray('Check remaining budget'));
+    console.log(chalk.bold.white('  AI Teammate') + chalk.gray(' — 3 levels, use wisely'));
+    console.log(chalk.white('    hint "question"     ') + chalk.gray('Level A — General guidance (50 uses)'));
+    console.log(chalk.white('    hint-b "question"   ') + chalk.gray('Level B — Deep analysis (10 uses)'));
+    console.log(chalk.white('    hint-c "question"   ') + chalk.gray('Level C — Critical assist (2 uses)'));
+    console.log(chalk.white('    hint budget         ') + chalk.gray('Check remaining uses'));
+    console.log(chalk.white('    ai4ctf              ') + chalk.gray('Free-chat with AI (no limit)'));
     console.log();
     console.log(chalk.bold.white('  Tools'));
-    console.log(chalk.white('    ref [topic]         ') + chalk.gray('Quick reference'));
+    console.log(chalk.white('    ref [topic]         ') + chalk.gray('Quick reference (linux, web, crypto...)'));
     console.log(chalk.white('    shell               ') + chalk.gray('Docker sandbox'));
     console.log(chalk.white('    files <id>          ') + chalk.gray('Download challenge files'));
     console.log(chalk.white('    connect <id>        ') + chalk.gray('Connect to remote target'));
@@ -764,7 +781,8 @@ function printReplHelp(activated, mode = 'olympiad') {
     console.log();
     console.log(chalk.bold.white('  System'));
     console.log(chalk.white('    setup               ') + chalk.gray('Configure settings'));
-    console.log(chalk.white('    lang [code]         ') + chalk.gray('Switch language'));
+    console.log(chalk.white('    lang [code]         ') + chalk.gray('Switch language (15 supported)'));
+    console.log(chalk.white('    logout              ') + chalk.gray('Disconnect'));
     console.log(chalk.white('    clear               ') + chalk.gray('Clear screen'));
     console.log(chalk.white('    exit                ') + chalk.gray('Quit (session saved)'));
     console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icoa-cli",
-  "version": "2.19.8",
+  "version": "2.19.9",
   "description": "ICOA CLI — The world's first CLI-native CTF competition terminal",
   "type": "module",
   "bin": {