practicode 0.1.5 → 0.1.7

package/README.md

@@ -12,7 +12,14 @@ Personal coding practice, right in your terminal.
 
 `practicode` is a small Rust TUI for stdin/stdout practice: problem on the left, code on the right, judge loop in the same terminal.
 
-## Start
+## What You Get
+
+- Local stdin/stdout judging for Python, TypeScript, Java, and Rust.
+- A two-pane terminal UI with problem text, editor, output, and command palette.
+- Local-first problem history under ignored `.practicode/`, `problems/`, and `submissions/` paths.
+- Optional Codex or Claude Code help for hints and generated next problems.
+
+## Install
 
 ### Prerequisites
 
@@ -43,6 +50,14 @@ npm install
 npm start
 ```
 
+### Check Install
+
+```bash
+practicode --version
+practicode --smoke
+practicode --help
+```
+
 ## Daily Loop
 
 The code editor starts focused.
@@ -54,44 +69,60 @@ choose /run
 choose /next when it passes
 ```
 
-Typing `/` outside the editor opens the command palette. Use `up/down` to move, `Enter` to run or complete the selected command, and `Esc` to cancel.
+Typing `/` outside the editor opens the command palette. Use `up/down` to move, `Enter` to run or complete the selected command, and `Esc` to cancel. Press `?` for in-app help or `Ctrl+C` to quit.
 
 Submissions are saved as you type under `submissions/<problem-id>/solution.<ext>`.
 
+## CLI Flags
+
+| Flag | Action |
+| --- | --- |
+| `--help`, `-h` | Show non-interactive help |
+| `--version`, `-V` | Print the installed version |
+| `--smoke` | Print the current problem title and exit |
+
 ## Commands
 
 | Command | Action |
 | --- | --- |
 | `/run` | Judge the current submission |
 | `/code` | Return to the code editor |
-| `/next` | Open the next local problem, or ask AI to create one |
-| `/next easy string problem` | Ask AI for a custom next problem |
-| `/prev` | Go back through problem history |
-| `/list` | Browse problems with `up/down` or `j/k`, open with `Enter` |
+| `/next` | Open the next unsolved problem, or ask AI only when none remain |
+| `/generate easy string problem` | Ask AI to create a new problem now |
+| `/back` | Go back through problem history |
+| `/problems` | Browse problems with `up/down` or `j/k`, open with `Enter` |
 | `/open 2` | Open by number, id, or slug |
-| `/giveup` | Show the reference answer |
+| `/answer` | Show the reference answer |
 | `/hint` | Ask the selected AI for a concise hint |
 | `/hint explain my bug` | Ask the selected AI about the current problem and submission |
+| `/profile` | Show your current practice profile |
+| `/difficulty auto` | Set difficulty preference: `auto`, `easy`, `medium`, `hard` |
+| `/topics arrays, strings` | Set preferred topics for future problems |
+| `/avoid dp, graph` | Set topics to avoid in future problems |
 | `/provider codex` | Set AI provider and show local CLI/daemon status |
 | `/model auto` | Use the provider default model for `/hint` and AI-backed `/next` |
-| `/note prefer hashmap practice` | Append a standing note for future problem generation |
-| `/notes` | Show your local next-problem notes |
-| `/lang python` | Set code language: `python`, `ts`, `java`, `rust` |
+| `/language python` | Set code language: `python`, `ts`, `java`, `rust` |
 | `/ui en` | Set UI language: `en`, `ko`, `ja`, `zh`, `es` |
 | `/theme dark` | Set theme: `dark` or `light` |
 | `/update` | Show update instructions when a newer version is available |
 | `/exit` | Quit |
 
+Older command names such as `/prev`, `/list`, `/giveup`, and `/lang` still work as aliases.
+
 The default UI language is English. Switch it any time with `/ui ko`, `/ui ja`, `/ui zh`, or `/ui es`.
 
-## AI Problems
+Your practice profile is saved in `.practicode/problem-state.json`. It keeps UI language, code language, theme, preferred difficulty, preferred topics, and topics to avoid. `auto` difficulty follows gradual progression; a fixed difficulty asks local selection and AI generation to prefer that level.
+
+## Problem Flow
+
+`/next` is local-first: it opens the next unsolved local problem before generating anything. When no unsolved problem remains, it asks the selected AI provider to create one.
 
-`/next <request>` passes your request into the selected AI problem generator.
+Use `/generate <request>` when you explicitly want to create a new problem now.
 
 ```text
-/next a slightly harder string problem
-/next hashmap practice, easy
-/next sorting problem, no graph yet
+/generate a slightly harder string problem
+/generate hashmap practice, easy
+/generate sorting problem, no graph yet
 ```
 
 Codex is the default provider:
@@ -129,9 +160,22 @@ npm update -g practicode
 cargo install --force practicode
 ```
 
-## Safety
+## Safety And Security
 
-`/run` executes your local submission as a normal process. practicode runs it from `.practicode/build/<problem-id>/run`, but this is not an OS sandbox. Only run code you trust.
+- `/run` executes your local submission as a normal process. practicode runs it from `.practicode/build/<problem-id>/run`, but this is not an OS sandbox. Only run code you trust.
+- `/hint` sends the current problem and submission to the selected AI provider CLI.
+- AI-backed `/next` can run a custom shell command from `settings.ai_next_command`; save only commands you trust.
+- Local `.env`, `.npmrc`, `.practicode/`, `problems/`, and `submissions/` are ignored by git. Do not commit tokens, private prompts, or answer keys.
+
+## Development Checks
+
+```bash
+cargo test
+cargo run -- --smoke
+cargo audit
+```
+
+This repo has no npm dependencies or lockfile today, so `npm audit` and `pnpm audit` are not applicable until a matching lockfile is added.
 
 ## Contributing
 
@@ -139,6 +183,8 @@ External contributions use the fork and pull request flow in [docs/CONTRIBUTING.
 
 Maintainer-only review and release notes live in [docs/MAINTAINING.md](docs/MAINTAINING.md).
 
+Code layout and extension boundaries live in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
 ## License
 
 practicode is MIT licensed. Third-party dependency license notes are in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).

package/assets/i18n/en.json

@@ -26,12 +26,17 @@
   "cmd_code": "Return to the code editor",
   "cmd_edit": "Return to the code editor",
   "cmd_next": "Open the next problem",
+  "cmd_generate": "Generate a new problem now",
   "cmd_prev": "Open the previous problem",
   "cmd_list": "Browse problems",
   "cmd_open": "Open by number, id, or slug",
   "cmd_giveup": "Show the reference answer",
   "cmd_hint": "Ask for a hint about the current problem",
   "cmd_ai": "Ask AI about the current problem and code",
+  "cmd_profile": "Show practice profile",
+  "cmd_difficulty": "Set preferred difficulty",
+  "cmd_topics": "Set preferred topics",
+  "cmd_avoid": "Set topics to avoid",
   "cmd_provider": "Set AI provider",
   "cmd_model": "Set AI model",
   "cmd_model_auto": "Use provider default model",

package/assets/i18n/es.json

@@ -26,12 +26,17 @@
   "cmd_code": "Volver al editor de codigo",
   "cmd_edit": "Volver al editor de codigo",
   "cmd_next": "Abrir el siguiente problema",
+  "cmd_generate": "Generar un problema nuevo ahora",
   "cmd_prev": "Abrir el problema anterior",
   "cmd_list": "Abrir la lista de problemas",
   "cmd_open": "Abrir por numero, id o slug",
   "cmd_giveup": "Mostrar la respuesta de referencia",
   "cmd_hint": "Pedir una pista para el problema actual",
   "cmd_ai": "Preguntar a AI sobre el problema y codigo actuales",
+  "cmd_profile": "Mostrar perfil de practica",
+  "cmd_difficulty": "Configurar dificultad preferida",
+  "cmd_topics": "Configurar temas preferidos",
+  "cmd_avoid": "Configurar temas a evitar",
   "cmd_provider": "Configurar AI provider",
   "cmd_model": "Configurar AI model",
   "cmd_model_auto": "Usar el modelo predeterminado del provider",

package/assets/i18n/ja.json

@@ -26,12 +26,17 @@
   "cmd_code": "コードエディタに戻る",
   "cmd_edit": "コードエディタに戻る",
   "cmd_next": "次の問題を開く",
+  "cmd_generate": "新しい問題を今すぐ生成",
   "cmd_prev": "前の問題を開く",
   "cmd_list": "問題一覧を開く",
   "cmd_open": "番号、id、slug で問題を開く",
   "cmd_giveup": "解答を見る",
   "cmd_hint": "現在の問題のヒントを依頼",
   "cmd_ai": "現在の問題とコードについて AI に質問",
+  "cmd_profile": "練習プロファイルを表示",
+  "cmd_difficulty": "希望難易度を設定",
+  "cmd_topics": "希望トピックを設定",
+  "cmd_avoid": "避けるトピックを設定",
   "cmd_provider": "AI provider を設定",
   "cmd_model": "AI model を設定",
   "cmd_model_auto": "provider の既定モデルを使用",

package/assets/i18n/ko.json

@@ -26,12 +26,17 @@
   "cmd_code": "코드 편집기로 돌아가기",
   "cmd_edit": "코드 편집기로 돌아가기",
   "cmd_next": "다음 문제 열기",
+  "cmd_generate": "새 문제를 바로 생성",
   "cmd_prev": "이전 문제 열기",
   "cmd_list": "문제 목록 열기",
   "cmd_open": "번호, id, slug로 문제 열기",
   "cmd_giveup": "정답 보기",
   "cmd_hint": "현재 문제 힌트 요청",
   "cmd_ai": "현재 문제와 코드에 대해 AI에게 질문",
+  "cmd_profile": "연습 프로파일 보기",
+  "cmd_difficulty": "선호 난이도 설정",
+  "cmd_topics": "선호 주제 설정",
+  "cmd_avoid": "피할 주제 설정",
   "cmd_provider": "AI provider 설정",
   "cmd_model": "AI model 설정",
   "cmd_model_auto": "provider 기본 모델 사용",

package/assets/i18n/zh.json

@@ -26,12 +26,17 @@
   "cmd_code": "回到代码编辑器",
   "cmd_edit": "回到代码编辑器",
   "cmd_next": "打开下一题",
+  "cmd_generate": "立即生成新题",
   "cmd_prev": "打开上一题",
   "cmd_list": "打开题目列表",
   "cmd_open": "按编号、id 或 slug 打开题目",
   "cmd_giveup": "显示参考答案",
   "cmd_hint": "请求当前题目的提示",
   "cmd_ai": "向 AI 询问当前题目和代码",
+  "cmd_profile": "显示练习配置",
+  "cmd_difficulty": "设置偏好难度",
+  "cmd_topics": "设置偏好主题",
+  "cmd_avoid": "设置要避开的主题",
   "cmd_provider": "设置 AI provider",
   "cmd_model": "设置 AI model",
   "cmd_model_auto": "使用 provider 默认模型",

package/assets/practicode-terminal.svg

@@ -1,24 +1,36 @@
 <svg width="1200" height="720" viewBox="0 0 1200 720" fill="none" xmlns="http://www.w3.org/2000/svg">
   <rect width="1200" height="720" fill="#070b12"/>
-  <rect x="64" y="52" width="1072" height="616" rx="10" fill="#0b111a" stroke="#1f6f7a" stroke-width="2"/>
-  <rect x="88" y="78" width="594" height="440" rx="4" fill="#0f1720" stroke="#00c2d1" stroke-width="2"/>
-  <rect x="704" y="78" width="408" height="440" rx="4" fill="#0d141c" stroke="#31536b" stroke-width="2"/>
-  <text x="112" y="112" fill="#d7e1ec" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="18" font-weight="700">Problem</text>
-  <text x="728" y="112" fill="#d7e1ec" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="18" font-weight="700">solution.py</text>
-  <text x="112" y="158" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="22" font-weight="700">001. Hello World</text>
-  <text x="112" y="204" fill="#c8d3f5" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">Difficulty: easy</text>
-  <text x="112" y="232" fill="#c8d3f5" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">Topics: io</text>
-  <text x="112" y="286" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17">Print exactly Hello, World! to stdout.</text>
-  <text x="112" y="352" fill="#00a8ff" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17" text-decoration="underline">Input</text>
-  <text x="112" y="386" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17">No input.</text>
-  <text x="112" y="442" fill="#00a8ff" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17" text-decoration="underline">Output</text>
-  <text x="112" y="476" fill="#f6c177" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17">Hello, World!</text>
-  <text x="728" y="158" fill="#6b7280" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17">  1</text>
-  <text x="776" y="158" fill="#7dd3fc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17">print</text>
-  <text x="828" y="158" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17">('Hello, World!')</text>
-  <rect x="64" y="536" width="1072" height="28" fill="#152033"/>
-  <text x="84" y="556" fill="#c8d3f5" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="15" font-weight="700">PRACTICODE | 001-hello-world | easy | idle | solved | code:written | python | next:ai | ai:codex/auto</text>
-  <rect x="64" y="586" width="1072" height="58" rx="2" fill="#0b1017" stroke="#008cff" stroke-width="2"/>
-  <text x="84" y="606" fill="#c8d3f5" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="15" font-weight="700">Command</text>
-  <text x="84" y="630" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="18">/ai hint about edge cases</text>
+  <rect x="54" y="42" width="1092" height="636" rx="10" fill="#0b111a" stroke="#214c5c" stroke-width="2"/>
+
+  <rect x="76" y="68" width="560" height="430" rx="4" fill="#0f1720" stroke="#00c2d1" stroke-width="2"/>
+  <rect x="664" y="68" width="458" height="430" rx="4" fill="#0d141c" stroke="#f8e71c" stroke-width="2"/>
+
+  <text x="92" y="91" fill="#16d6e8" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="15" font-weight="700">Problem</text>
+  <text x="680" y="91" fill="#f8e71c" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="15" font-weight="700">&gt; solution.py</text>
+
+  <text x="96" y="128" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="22" font-weight="700">001. Hello World</text>
+  <text x="96" y="164" fill="#c8d3f5" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">Difficulty: easy    Topics: io</text>
+  <text x="96" y="206" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17">Print exactly Hello, World! to stdout.</text>
+
+  <text x="96" y="286" fill="#00d2e8" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17" font-weight="700">Input</text>
+  <rect x="96" y="304" width="486" height="44" rx="3" fill="#101d28" stroke="#29495a"/>
+  <text x="112" y="332" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">No input.</text>
+
+  <text x="96" y="388" fill="#00d2e8" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="17" font-weight="700">Output</text>
+  <rect x="96" y="406" width="486" height="66" rx="3" fill="#101d28" stroke="#29495a"/>
+  <text x="112" y="446" fill="#f6c177" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">Hello, World!</text>
+
+  <text x="690" y="128" fill="#64748b" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">  1</text>
+  <text x="738" y="128" fill="#7dd3fc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">print</text>
+  <text x="790" y="128" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="16">('Hello, World!')</text>
+
+  <rect x="76" y="512" width="1046" height="30" fill="#152033"/>
+  <text x="94" y="533" fill="#c8d3f5" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="15" font-weight="700">PRACTICODE | 001-hello-world | easy | idle | assigned | code:written | python | Esc then / command</text>
+
+  <rect x="76" y="558" width="1046" height="48" rx="2" fill="#0b1017" stroke="#00c2d1" stroke-width="2"/>
+  <text x="94" y="579" fill="#16d6e8" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="15" font-weight="700">Command</text>
+  <text x="94" y="596" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="18">/</text>
+
+  <rect x="76" y="614" width="1046" height="46" rx="2" fill="#101923" stroke="#214c5c"/>
+  <text x="94" y="641" fill="#f8fafc" font-family="SFMono-Regular, Menlo, Consolas, monospace" font-size="15">/run  /next  /hint &lt;request&gt;  /profile  /difficulty auto  /topics arrays, strings</text>
 </svg>

package/docs/ARCHITECTURE.md

@@ -0,0 +1,25 @@
+# Architecture
+
+Practicode is local-first: user data stays under `.practicode/`, `problems/`, and `submissions/`.
+
+## Source Layout
+
+- `src/core.rs` owns problem data, state loading/saving, judging, and file generation.
+- `src/core/profile.rs` owns practice-profile defaults and normalization.
+- `src/tui.rs` owns Ratatui rendering and interaction flow.
+- `src/tui/commands.rs` owns the command palette catalog.
+- `src/ai.rs` owns provider commands, daemon/model checks, and AI prompts.
+- `src/update.rs` owns update checks.
+- `src/text.rs` owns terminal text editing and markdown/plain rendering helpers.
+
+## Extension Rules
+
+- Add domain logic under the owning module first; keep `tui.rs` as orchestration and rendering.
+- Add user-visible commands in `src/tui/commands.rs`, then route behavior in `PracticodeApp::handle_command`.
+- Add persisted profile settings to `Settings`, normalize them in `normalize_settings`, and cover old-state compatibility with tests.
+- Keep provider-specific behavior in `src/ai.rs`; TUI should ask for status or start tasks, not know provider internals.
+- Keep local user data backwards-compatible. Missing fields should default cleanly.
+
+## Release
+
+See [MAINTAINING.md](MAINTAINING.md) for tag-based releases.

package/docs/CONTRIBUTING.md

@@ -9,6 +9,7 @@ Maintainer-only review and release steps live in [MAINTAINING.md](MAINTAINING.md
 - Search existing issues and pull requests first.
 - Small bug fixes, docs fixes, tests, and localization updates can go straight to a pull request.
 - For larger UI, AI-generation, storage, or packaging changes, open an issue first so the scope is clear.
+- Check [ARCHITECTURE.md](ARCHITECTURE.md) before adding commands, settings, provider behavior, or persisted state.
 - Do not commit local practice data from `.practicode/`, `problems/`, or `submissions/`.
 - Do not include secrets, tokens, private prompts, or generated answer keys in docs or examples.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "practicode",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Local-first coding-test practice in a Rust terminal UI with optional AI help.",
   "license": "MIT",
   "repository": {

package/src/ai.rs

@@ -123,13 +123,22 @@ pub fn available_models(provider: &str) -> ModelCatalog {
 }
 
 pub fn default_ai_next_prompt(request: &str) -> String {
+    default_ai_next_prompt_with_settings(&Settings::default(), request)
+}
+
+pub fn default_ai_next_prompt_with_settings(settings: &Settings, request: &str) -> String {
     format!(
-        "Read AGENTS.md, docs/problem-authoring-notes.md if present, .practicode/problem_notes.md if present, problems/INDEX.md if present, .practicode/problem_bank.json if present, and .practicode/problem-state.json. Create exactly one new non-duplicate coding practice problem. The built-in 001-hello-world already exists, so do not duplicate it. User request: {}. Make the smallest valid edits: update .practicode/problem_bank.json, one problem directory, problems/INDEX.md, and .practicode/problem-state.json. Do not include the answer in the problem statement.",
+        "Read AGENTS.md, docs/problem-authoring-notes.md if present, .practicode/problem_notes.md if present, problems/INDEX.md if present, .practicode/problem_bank.json if present, and .practicode/problem-state.json. Create exactly one new non-duplicate coding practice problem. The built-in 001-hello-world already exists, so do not duplicate it. User request: {}. Practice profile: difficulty preference: {}; preferred topics: {}; avoid topics: {}; code language: {}; UI language: {}. Treat difficulty auto as gradual progression from state; otherwise prefer the requested difficulty unless the direct user request conflicts. Make the smallest valid edits: update .practicode/problem_bank.json, one problem directory, problems/INDEX.md, and .practicode/problem-state.json. Do not include the answer in the problem statement.",
         if request.is_empty() {
             "(none)"
         } else {
             request
-        }
+        },
+        settings.difficulty,
+        list_or_none(&settings.topics),
+        list_or_none(&settings.avoid_topics),
+        settings.language,
+        settings.ui_language
     )
 }
 
@@ -304,7 +313,9 @@ fn default_codex_next_command(root: &Path, settings: &Settings, request: &str) -
         exec.push_str(&format!(" --model {}", sh_quote(model)));
     }
     exec.push(' ');
-    exec.push_str(&sh_quote(&default_ai_next_prompt(request)));
+    exec.push_str(&sh_quote(&default_ai_next_prompt_with_settings(
+        settings, request,
+    )));
     format!("{start}; {exec}")
 }
 
@@ -322,7 +333,9 @@ fn default_claude_next_command(root: &Path, settings: &Settings, request: &str)
         claude.push_str(&format!(" --model {}", sh_quote(model)));
     }
     claude.push_str(" -p ");
-    claude.push_str(&sh_quote(&default_ai_next_prompt(request)));
+    claude.push_str(&sh_quote(&default_ai_next_prompt_with_settings(
+        settings, request,
+    )));
     format!(
         "claude daemon status >/dev/null 2>&1 || true; cd {}; {}",
         sh_quote(&root.display().to_string()),
@@ -338,6 +351,14 @@ fn output_text(stdout: &str, stderr: &str) -> String {
         .join("\n")
 }
 
+fn list_or_none(values: &[String]) -> String {
+    if values.is_empty() {
+        "(none)".to_string()
+    } else {
+        values.join(", ")
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::parse_model_list;

package/src/core/profile.rs

@@ -0,0 +1,29 @@
+pub const DIFFICULTIES: &[&str] = &["auto", "easy", "medium", "hard"];
+
+pub fn default_difficulty() -> String {
+    "auto".to_string()
+}
+
+pub fn normalize_difficulty(difficulty: &str) -> String {
+    let difficulty = difficulty.trim().to_lowercase();
+    if DIFFICULTIES.contains(&difficulty.as_str()) {
+        difficulty
+    } else {
+        default_difficulty()
+    }
+}
+
+pub fn parse_topic_list(value: &str) -> Vec<String> {
+    let mut topics = Vec::new();
+    for topic in value.split(',') {
+        let topic = topic.trim().trim_start_matches('#').trim().to_lowercase();
+        if !topic.is_empty() && !topics.contains(&topic) {
+            topics.push(topic);
+        }
+    }
+    topics
+}
+
+pub fn normalize_topic_list(topics: &[String]) -> Vec<String> {
+    parse_topic_list(&topics.join(","))
+}

package/src/core.rs

@@ -9,6 +9,11 @@ use std::{
     time::Duration,
 };
 
+mod profile;
+pub use profile::{
+    DIFFICULTIES, default_difficulty, normalize_difficulty, normalize_topic_list, parse_topic_list,
+};
+
 pub const LANGUAGES: &[&str] = &["python", "ts", "java", "rust"];
 pub use crate::i18n::{UI_LANGUAGES, normalize_ui_language, ui_text};
 pub const THEMES: &[&str] = &["dark", "light"];
@@ -25,6 +30,12 @@ pub struct Settings {
     pub ui_language: String,
     #[serde(default = "default_theme")]
     pub theme: String,
+    #[serde(default = "default_difficulty")]
+    pub difficulty: String,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub topics: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub avoid_topics: Vec<String>,
     #[serde(default = "default_editor")]
     pub editor: String,
     #[serde(default = "default_next_source")]
@@ -43,6 +54,9 @@ impl Default for Settings {
             language: default_language(),
             ui_language: default_ui_language(),
             theme: default_theme(),
+            difficulty: default_difficulty(),
+            topics: Vec::new(),
+            avoid_topics: Vec::new(),
             editor: default_editor(),
             next_source: default_next_source(),
             ai_provider: default_ai_provider(),
@@ -364,6 +378,9 @@ pub fn normalize_settings(settings: &mut Settings) {
     if !THEMES.contains(&settings.theme.as_str()) {
         settings.theme = "dark".to_string();
     }
+    settings.difficulty = normalize_difficulty(&settings.difficulty);
+    settings.topics = normalize_topic_list(&settings.topics);
+    settings.avoid_topics = normalize_topic_list(&settings.avoid_topics);
     settings.next_source = normalize_next_source(&settings.next_source);
     settings.ai_provider = normalize_ai_provider(&settings.ai_provider);
     if settings.ai_model.trim().is_empty() {
@@ -376,8 +393,9 @@ pub fn problem_by_id<'a>(bank: &'a [Problem], problem_id: &str) -> Option<&'a Pr
 }
 
 pub fn normalize_language(language: &str) -> String {
-    if LANGUAGES.contains(&language) {
-        language.to_string()
+    let language = language.trim().to_lowercase();
+    if LANGUAGES.contains(&language.as_str()) {
+        language
     } else {
         "python".to_string()
     }
@@ -756,7 +774,11 @@ pub fn next_problem(
         .iter()
         .map(|item| item.id.as_str())
         .collect::<Vec<_>>();
-    let preferred = &state.suggested_next_difficulty;
+    let preferred = if state.settings.difficulty == "auto" {
+        &state.suggested_next_difficulty
+    } else {
+        &state.settings.difficulty
+    };
     let problem = bank
         .iter()
         .find(|item| !seen.contains(&item.id.as_str()) && &item.difficulty == preferred)

package/src/lib.rs

@@ -14,9 +14,39 @@ pub mod text;
 pub mod tui;
 pub mod update;
 
+pub fn cli_help_text() -> &'static str {
+    "practicode - local-first coding-test practice in your terminal
+
+Usage:
+  practicode            Open the TUI
+  practicode --smoke    Print the current problem title and exit
+  practicode --version  Print the installed version
+  practicode --help     Show this help
+
+Inside the TUI:
+  Esc then /            Open the command palette
+  ?                     Open help
+  Ctrl+C                Quit"
+}
+
 pub fn run_cli() -> Result<()> {
     let root = env::current_dir().context("read current directory")?;
-    if env::args().any(|arg| arg == "--smoke") {
+    let args = env::args().skip(1).collect::<Vec<_>>();
+    if args
+        .iter()
+        .any(|arg| matches!(arg.as_str(), "-h" | "--help"))
+    {
+        println!("{}", cli_help_text());
+        return Ok(());
+    }
+    if args
+        .iter()
+        .any(|arg| matches!(arg.as_str(), "-V" | "--version"))
+    {
+        println!("practicode {}", update::CURRENT_VERSION);
+        return Ok(());
+    }
+    if args.iter().any(|arg| arg == "--smoke") {
         let bank = core::load_bank(&root)?;
         let state = core::load_state(&root, &bank)?;
         let problem = core::problem_by_id(&bank, &state.current_problem).unwrap_or(&bank[0]);
@@ -39,3 +69,16 @@ pub fn run_cli() -> Result<()> {
     );
     result
 }
+
+#[cfg(test)]
+mod tests {
+    use super::cli_help_text;
+
+    #[test]
+    fn cli_help_lists_non_interactive_flags_and_tui_exit() {
+        let help = cli_help_text();
+        assert!(help.contains("--smoke"));
+        assert!(help.contains("--version"));
+        assert!(help.contains("Ctrl+C"));
+    }
+}