@booklib/core 2.0.0

package/skills/programming-with-rust/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: programming-with-rust
+version: "1.0"
+license: MIT
+tags: [rust, systems-programming]
+description: >
+  Write and review Rust code using practices from "Programming with Rust" by Donis Marshall.
+  Covers ownership, borrowing, lifetimes, error handling with Result/Option, traits, generics,
+  pattern matching, closures, fearless concurrency, and macros. Use when writing Rust, reviewing
+  Rust code, or learning Rust idioms. Trigger on: "Rust", "ownership", "borrow checker",
+  "lifetimes", "Result", "Option", "traits", "fearless concurrency", ".rs files", "cargo".
+---
+
+# Programming with Rust Skill
+
+Apply the practices from Donis Marshall's "Programming with Rust" to review existing code and write new Rust. This skill operates in two modes: **Review Mode** (analyze code for violations of Rust idioms) and **Write Mode** (produce safe, idiomatic Rust from scratch).
+
+## Reference Files
+
+- `ref-01-fundamentals.md` — Ch 1-3: Rust model, tooling, variables, primitives, references
+- `ref-02-types-strings.md` — Ch 4-5: String vs &str, formatting, Display/Debug traits
+- `ref-03-control-collections.md` — Ch 6-7: Control flow, iterators, arrays, Vec, HashMap
+- `ref-04-ownership-lifetimes.md` — Ch 8-10: Ownership, move semantics, borrowing, lifetimes
+- `ref-05-functions-errors.md` — Ch 11-12: Functions, Result, Option, panics, custom errors
+- `ref-06-structs-generics.md` — Ch 13-14: Structs, impl blocks, generics, bounds
+- `ref-07-patterns-closures.md` — Ch 15-16: Pattern matching, closures, Fn/FnMut/FnOnce
+- `ref-08-traits.md` — Ch 17: Trait definition, dispatch, supertraits, associated types
+- `ref-09-concurrency.md` — Ch 18-19: Threads, channels, Mutex, RwLock, atomics
+- `ref-10-advanced.md` — Ch 20-23: Memory, interior mutability, macros, FFI, modules
+
+## How to Use This Skill
+
+**Before responding**, read the reference files relevant to the code's topic. For ownership/borrowing issues read `ref-04`. For error handling read `ref-05`. For a full review, read all files.
+
+---
+
+## Mode 1: Code Review
+
+When the user asks you to **review** Rust code, follow this process:
+
+### Step 1: Read Relevant References
+Identify which chapters apply. If unsure, read all reference files.
+
+### Step 2: Analyze the Code
+
+**CRITICAL: First assess whether the code is already idiomatic.** If the code correctly uses patterns like `Arc<Mutex<T>>` for shared state, `.expect("reason")` for mutex locks, `&str` parameters, custom error types with `Display + Error + From`, iterator adapters like `.find().cloned()`, or proper `Result`/`?` propagation — **acknowledge these as correct and do not manufacture problems**. The goal is accurate assessment, not finding something to criticize.
+
+Check these areas in order of severity:
+
+1. **Ownership & Borrowing** (Ch 8, 10): Unnecessary `.clone()` calls? Mutable borrow conflicts? Move semantics misunderstood? Cloning a single found item (e.g., `.find().cloned()`) is correct and intentional — do not flag it.
+2. **Lifetimes** (Ch 9): Missing or incorrect annotations? Can elision rules eliminate them? `'static` used where a shorter lifetime would do?
+3. **Error Handling** (Ch 12): Is `.unwrap()` used without a meaningful reason where `?` or proper matching belongs? `.expect("mutex poisoned")` with a descriptive reason string is correct idiomatic Rust — do not flag it. Are custom error types with `Display`, `Error`, and `From` implementations missing where they'd help callers?
+4. **Traits & Generics** (Ch 14, 17): Are trait bounds as narrow as possible? When a function could return a single concrete type, `impl Trait` is preferred over `Box<dyn Trait>` for zero-cost static dispatch. However, when a function **must** return one of multiple different concrete types at runtime (e.g., `if condition { Box::new(TypeA) } else { Box::new(TypeB) }`), `Box<dyn Trait>` is the correct and necessary choice — do not flag it as wrong. When reviewing code that uses `Box<dyn Trait>` for multiple-type returns, you should still **note** that if only one type were ever returned, `impl Trait` would be preferred — frame this as a general educational point, not a bug. Also note: trait methods that return `String` via `.clone()` could instead return `&str` with a lifetime annotation (`fn summary(&self) -> &str`) to avoid heap allocation — mention this as a suggestion.
+5. **Pattern Matching** (Ch 15): Are `match` arms exhaustive? Can `if let` / `while let` simplify single-arm matches? Are wildcards masking unhandled cases?
+6. **Concurrency** (Ch 18, 19): `Arc<Mutex<T>>` for shared mutable state across threads is correct idiomatic Rust — acknowledge it positively. Is shared state protected when it should be? Are channels used correctly? Note: `RwLock` is only preferable over `Mutex` when reads vastly outnumber writes — do not flag `Mutex` as wrong when `RwLock` would merely be an option.
+7. **Memory** (Ch 20): Is `RefCell` used outside of single-threaded interior mutability? Is `Box` used unnecessarily when stack allocation would work?
+8. **Idioms**: Is `for item in collection` preferred over manual indexing? Are iterator adapters (`map`, `filter`, `collect`) used over manual loops? `&str` parameters with `.to_string()` conversion at the boundary is correct — do not flag it.
+
+### Step 3: Report Findings
+
+If the code is already idiomatic, lead with that assessment and cite the patterns it uses correctly (with chapter references). Then mention any genuine improvements or minor suggestions.
+
+For each real issue, report:
+- **Chapter reference** (e.g., "Ch 12: Error Handling")
+- **Location** in the code
+- **What's wrong** (the anti-pattern)
+- **How to fix it** (the idiomatic Rust approach)
+- **Priority**: Critical (safety/correctness), Important (idiom/maintainability), Suggestion (polish)
+
+**Priority calibration:**
+- Implementing `Default` alongside a `new()` constructor is a **Suggestion** (polish), not Important. It is a minor note, not a real issue.
+- `Mutex` vs `RwLock` is a **Suggestion** when the existing `Mutex` is correct.
+- Returning `&str` instead of `String` from a trait method is a **Suggestion** when `String` works fine.
+- Never elevate suggestions to Important or Critical just to have something to say.
+- When code is already idiomatic, **limit suggestions to at most one minor polish note** (e.g., `Default`). Do not pile on additional suggestions like deriving `Clone` for structs that don't need it, adding `Default` to every type, or noting `RwLock` as an option. One suggestion maximum keeps the review signal clear.
+
+### Step 4: Provide Fixed Code
+Offer a corrected version with comments explaining each change.
+
+---
+
+## Mode 2: Writing New Code
+
+When the user asks you to **write** new Rust code, apply these core principles:
+
+### Ownership & Memory Safety
+
+1. **Prefer borrowing over cloning** (Ch 8). Pass `&T` or `&mut T` rather than transferring ownership when the caller still needs the value. Clone only when ownership genuinely needs to be duplicated.
+
+2. **Respect the single-owner rule** (Ch 8). Each value has exactly one owner. When you move a value, the old binding is invalid — design data flow around this.
+
+3. **Use lifetime elision** (Ch 9). Annotate lifetimes only when the compiler cannot infer them. Explicit annotations are for structs holding references and functions with multiple reference parameters where elision is ambiguous.
+
+4. **Prefer `&str` over `String` in function parameters** (Ch 4). Accept `&str` to work with both `String` (via deref coercion) and string literals without allocation.
+
+### Error Handling
+
+5. **Return `Result<T, E>`, never panic in library code** (Ch 12). Panics are for unrecoverable programmer errors. Use `Result` for anything that can fail at runtime.
+
+6. **Use the `?` operator for error propagation** (Ch 12). Replace `.unwrap()` chains with `?` to propagate errors cleanly to callers.
+
+7. **Define custom error types for public APIs** (Ch 12). Implement `std::error::Error` and use `thiserror` or manual `impl` to give callers structured errors they can match on.
+
+8. **Never use `.unwrap()` in production paths** (Ch 12). Use `.expect("reason")` only in tests or where panic is truly the right response. In all other cases, handle with `match`, `if let`, or `?`.
+
+### Traits & Generics
+
+9. **Prefer `impl Trait` over `dyn Trait` for return types when a single concrete type is returned** (Ch 17). Static dispatch is zero-cost. Use `dyn Trait` (typically `Box<dyn Trait>`) only when the function must return one of multiple different concrete types at runtime — that is genuinely the correct tool and should not be changed to `impl Trait`.
+
+10. **Use trait bounds instead of concrete types** (Ch 14). `fn process<T: Display + Debug>(item: T)` is more reusable than accepting a concrete type.
+
+11. **Implement standard traits** (Ch 17). Derive `Debug`, `Clone`, `PartialEq` where appropriate. Implement `Display` for user-facing output, `From`/`Into` for conversions.
+
+### Pattern Matching
+
+12. **Use `match` for exhaustive handling** (Ch 15). The compiler enforces exhaustiveness — treat it as a feature, not a burden.
+
+13. **Use `if let` for single-variant matching** (Ch 15). `if let Some(x) = opt { }` is cleaner than a two-arm `match` when you only care about one case.
+
+14. **Destructure in function parameters** (Ch 15). `fn process(&Point { x, y }: &Point)` avoids manual field access inside the body.
+
+### Concurrency
+
+15. **Use channels for message passing** (Ch 18). Prefer `std::sync::mpsc` channels over shared mutable state when threads can communicate by value.
+
+16. **Wrap shared state in `Arc<Mutex<T>>`** (Ch 19). `Arc` for shared ownership across threads, `Mutex` for mutual exclusion. `Arc<Mutex<T>>` is the correct default — only suggest `RwLock` if there is evidence that reads vastly outnumber writes and contention is a measured concern.
+
+17. **Prefer `Mutex::lock().unwrap()` with `.expect()`** (Ch 19). Poisoned mutexes indicate a panic in another thread — `.expect("mutex poisoned")` makes this explicit.
+
+### Code Structure Template
+
+```rust
+use std::fmt;
+
+/// Domain error type for public APIs (Ch 12)
+#[derive(Debug)]
+pub enum AppError {
+    NotFound(String),
+    InvalidInput(String),
+    Io(std::io::Error),
+}
+
+impl fmt::Display for AppError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            AppError::NotFound(msg) => write!(f, "not found: {msg}"),
+            AppError::InvalidInput(msg) => write!(f, "invalid input: {msg}"),
+            AppError::Io(e) => write!(f, "I/O error: {e}"),
+        }
+    }
+}
+
+impl std::error::Error for AppError {}
+
+impl From<std::io::Error> for AppError {
+    fn from(e: std::io::Error) -> Self {
+        AppError::Io(e)
+    }
+}
+
+/// Accept &str, not String (Ch 4)
+pub fn find_user(name: &str) -> Result<User, AppError> {
+    // Use ? for propagation (Ch 12)
+    let data = load_data()?;
+    data.iter()
+        .find(|u| u.name == name)
+        .cloned()  // clone only the found item (Ch 8)
+        .ok_or_else(|| AppError::NotFound(name.to_string()))
+}
+
+/// Derive standard traits (Ch 17)
+#[derive(Debug, Clone, PartialEq)]
+pub struct User {
+    pub name: String,
+    pub role: Role,
+}
+
+/// Enum for valid states (Ch 15)
+#[derive(Debug, Clone, PartialEq)]
+pub enum Role {
+    Admin,
+    Viewer,
+    Editor,
+}
+```
+
+---
+
+## Priority of Practices by Impact
+
+### Critical (Safety & Correctness)
+- Ch 8: Understand ownership — moving vs borrowing, no use-after-move
+- Ch 10: One mutable borrow OR many immutable borrows — never both
+- Ch 12: Never `.unwrap()` in production; use `Result` and `?`
+- Ch 19: Always protect shared mutable state with `Mutex` or `RwLock`
+
+### Important (Idiom & Maintainability)
+- Ch 4: Prefer `&str` params over `String`
+- Ch 9: Rely on lifetime elision; annotate only when required
+- Ch 12: Custom error types for public APIs
+- Ch 14/17: Trait bounds over concrete types; `impl Trait` over `dyn Trait` when returning a single concrete type; `Box<dyn Trait>` is correct when multiple concrete types may be returned
+- Ch 15: Exhaustive `match`; use `if let` for single-arm cases
+- Ch 17: Derive/implement standard traits (`Debug`, `Display`, `From`)
+
+### Suggestions (Polish)
+- Ch 6: Use iterator adapters (`map`, `filter`, `flat_map`) over manual loops
+- Ch 16: Use closures with `move` when capturing environment across thread boundaries
+- Ch 20: Prefer stack allocation; use `Box` only when size is unknown at compile time
+- Ch 21: Use `derive` macros before writing manual `impl` blocks

package/skills/programming-with-rust/evals/evals.json

@@ -0,0 +1,37 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-unwrap-clone-ownership",
+      "prompt": "Review this Rust code:\n\n```rust\nfn process_users(users: Vec<String>) -> Vec<String> {\n    let copy = users.clone();\n    let mut result = Vec::new();\n    for i in 0..copy.len() {\n        result.push(copy[i].clone());\n    }\n    result\n}\n\nfn read_file(path: String) -> String {\n    std::fs::read_to_string(path).unwrap()\n}\n\nfn find(map: HashMap<String, u32>, key: String) -> u32 {\n    map.get(&key).unwrap().clone()\n}\n```",
+      "expectations": [
+        "Flag Ch 8: users.clone() is unnecessary — borrow &[String] instead of taking ownership of Vec<String>",
+        "Flag Ch 6: manual index loop should be replaced with iterator adapters (.iter().cloned().collect())",
+        "Flag Ch 12: .unwrap() in read_file will panic on I/O error — should return Result<String, std::io::Error> and use ?",
+        "Flag Ch 8: find takes owned HashMap — borrows &HashMap<String, u32> instead",
+        "Flag Ch 12: .unwrap() in find panics on missing key — return Option<u32> or Result",
+        "Provide corrected versions using &[String], iterators, Result, ?, and &HashMap"
+      ]
+    },
+    {
+      "id": "eval-02-subtle-trait-dispatch",
+      "prompt": "Review this Rust code:\n\n```rust\nuse std::fmt;\n\ntrait Summarize {\n    fn summary(&self) -> String;\n}\n\nstruct Article { title: String, body: String }\nstruct Tweet { content: String }\n\nimpl Summarize for Article {\n    fn summary(&self) -> String { self.title.clone() }\n}\nimpl Summarize for Tweet {\n    fn summary(&self) -> String { self.content.clone() }\n}\n\n// Returns a trait object\nfn make_summary(is_article: bool) -> Box<dyn Summarize> {\n    if is_article {\n        Box::new(Article { title: String::from(\"news\"), body: String::from(\"...\") })\n    } else {\n        Box::new(Tweet { content: String::from(\"hello\") })\n    }\n}\n\n// Takes a trait object\nfn print_all(items: &Vec<Box<dyn Summarize>>) {\n    for item in items {\n        println!(\"{}\", item.summary());\n    }\n}\n```",
+      "expectations": [
+        "Note that Box<dyn Summarize> in make_summary is actually appropriate here because the function must return one of two different concrete types — this is a valid use of dynamic dispatch (Ch 17)",
+        "Flag &Vec<Box<dyn Summarize>> in print_all — prefer &[Box<dyn Summarize>] (a slice reference is more general than a Vec reference)",
+        "Suggest that if only one type were returned, impl Summarize would be preferred over Box<dyn Summarize> for zero-cost static dispatch (Ch 17)",
+        "Note .clone() in summary() implementations — title/body could be returned as &str with lifetime annotation to avoid allocation (Ch 8, 9)",
+        "Do NOT flag the dynamic dispatch in make_summary as wrong — it is the correct choice when returning heterogeneous types"
+      ]
+    },
+    {
+      "id": "eval-03-idiomatic-rust-already-good",
+      "prompt": "Review this Rust code:\n\n```rust\nuse std::fmt;\nuse std::sync::{Arc, Mutex};\n\n#[derive(Debug)]\npub enum StoreError {\n    NotFound(String),\n    Io(std::io::Error),\n}\n\nimpl fmt::Display for StoreError {\n    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {\n        match self {\n            StoreError::NotFound(k) => write!(f, \"key not found: {k}\"),\n            StoreError::Io(e) => write!(f, \"io error: {e}\"),\n        }\n    }\n}\n\nimpl std::error::Error for StoreError {}\n\nimpl From<std::io::Error> for StoreError {\n    fn from(e: std::io::Error) -> Self { StoreError::Io(e) }\n}\n\n#[derive(Debug, Clone)]\npub struct Record {\n    pub key: String,\n    pub value: String,\n}\n\npub struct Store {\n    records: Arc<Mutex<Vec<Record>>>,\n}\n\nimpl Store {\n    pub fn new() -> Self {\n        Store { records: Arc::new(Mutex::new(Vec::new())) }\n    }\n\n    pub fn insert(&self, key: &str, value: &str) {\n        let mut records = self.records.lock().expect(\"mutex poisoned\");\n        records.push(Record { key: key.to_string(), value: value.to_string() });\n    }\n\n    pub fn find(&self, key: &str) -> Result<Record, StoreError> {\n        let records = self.records.lock().expect(\"mutex poisoned\");\n        records\n            .iter()\n            .find(|r| r.key == key)\n            .cloned()\n            .ok_or_else(|| StoreError::NotFound(key.to_string()))\n    }\n}\n```",
+      "expectations": [
+        "Recognize this code is idiomatic Rust — do NOT manufacture issues",
+        "Acknowledge: custom StoreError with Display + Error + From (Ch 12), Arc<Mutex<T>> for shared state (Ch 19), &str parameters with .to_string() conversion (Ch 4), iterator .find().cloned() over manual loops (Ch 6), .expect('mutex poisoned') with reason string (Ch 19)",
+        "At most note that Default could be derived or implemented for Store alongside new()",
+        "Do not flag .cloned() on the found record — cloning a single found item is correct and intentional"
+      ]
+    }
+  ]
+}

package/skills/programming-with-rust/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 1,
+  "passed": 15,
+  "total": 15,
+  "baseline_pass_rate": 0.733,
+  "baseline_passed": 11,
+  "baseline_total": 15,
+  "delta": 0.267,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-28",
+  "non_standard_provider": true
+}

package/skills/programming-with-rust/examples/after.md

@@ -0,0 +1,107 @@
+# After: Programming with Rust
+
+The same service rewritten with idiomatic Rust — proper ownership, Result-based error handling, borrowing over cloning, iterator adapters, and trait bounds.
+
+```rust
+use std::collections::HashMap;
+use std::fmt;
+use std::sync::{Arc, Mutex};
+
+// Custom error type — callers can match on variants (Ch 12)
+#[derive(Debug)]
+pub enum ConfigError {
+    Io(std::io::Error),
+    UserNotFound(String),
+}
+
+impl fmt::Display for ConfigError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ConfigError::Io(e) => write!(f, "I/O error: {e}"),
+            ConfigError::UserNotFound(name) => write!(f, "user not found: {name}"),
+        }
+    }
+}
+
+impl std::error::Error for ConfigError {}
+
+impl From<std::io::Error> for ConfigError {
+    fn from(e: std::io::Error) -> Self {
+        ConfigError::Io(e)
+    }
+}
+
+// &str instead of String — works with both literals and String via deref coercion (Ch 4)
+// Returns Result — caller decides how to handle failure (Ch 12)
+fn load_config(path: &str) -> Result<String, ConfigError> {
+    let content = std::fs::read_to_string(path)?;  // ? propagates I/O error (Ch 12)
+    Ok(content)
+}
+
+// Borrows the map — no clone, caller retains ownership (Ch 8, 10)
+fn get_user<'a>(users: &'a HashMap<String, String>, name: &str) -> Result<&'a str, ConfigError> {
+    users
+        .get(name)
+        .map(|s| s.as_str())
+        .ok_or_else(|| ConfigError::UserNotFound(name.to_string()))
+}
+
+// Iterator adapters replace manual index loop (Ch 6)
+fn active_names(users: &[(String, bool)]) -> Vec<&str> {
+    users
+        .iter()
+        .filter(|(_, active)| *active)
+        .map(|(name, _)| name.as_str())
+        .collect()
+}
+
+// Safe shared counter with Arc<Mutex<T>> (Ch 19)
+fn make_counter() -> Arc<Mutex<u32>> {
+    Arc::new(Mutex::new(0))
+}
+
+fn increment(counter: &Arc<Mutex<u32>>) {
+    let mut count = counter.lock().expect("mutex poisoned");
+    *count += 1;
+}
+
+// Trait bound instead of concrete type — accepts anything Display (Ch 14, 17)
+fn print_item(item: &impl fmt::Display) {
+    println!("{item}");
+}
+
+fn main() -> Result<(), ConfigError> {
+    let config = load_config("config.toml")?;  // ? instead of unwrap (Ch 12)
+    println!("{config}");
+
+    let mut users = HashMap::new();
+    users.insert(String::from("alice"), String::from("admin"));
+
+    // Borrow users — still usable after the call (Ch 8)
+    let role = get_user(&users, "alice")?;
+    println!("{role}");
+    println!("{users:?}");  // still valid — was only borrowed
+
+    let items = vec![
+        (String::from("alice"), true),
+        (String::from("bob"), false),
+    ];
+    let names = active_names(&items);
+    println!("{names:?}");
+
+    let counter = make_counter();
+    increment(&counter);
+    println!("count: {}", counter.lock().unwrap());
+
+    Ok(())
+}
+```
+
+**Key improvements:**
+- `ConfigError` gives callers structured, matchable errors (Ch 12)
+- `?` replaces `.unwrap()` for clean error propagation (Ch 12)
+- `&str` / `&HashMap` parameters borrow instead of consuming (Ch 4, 8, 10)
+- Iterator adapters replace manual index loops (Ch 6)
+- `Arc<Mutex<T>>` replaces `unsafe static mut` for safe shared state (Ch 19)
+- `impl fmt::Display` trait bound instead of concrete `String` parameter (Ch 14, 17)
+- `main()` returns `Result` so errors surface cleanly (Ch 12)

package/skills/programming-with-rust/examples/before.md

@@ -0,0 +1,59 @@
+# Before: Programming with Rust
+
+A user service with common Rust anti-patterns — ownership misuse, panic-prone error handling, unnecessary cloning, and poor trait design.
+
+```rust
+use std::collections::HashMap;
+
+// No custom error type — callers can't match on failures
+fn load_config(path: String) -> String {  // takes owned String unnecessarily
+    std::fs::read_to_string(path).unwrap()  // panics on any I/O error
+}
+
+// Clones entire map just to read it
+fn get_user(users: HashMap<String, String>, name: String) -> String {
+    let users_copy = users.clone();  // unnecessary clone of the whole map
+    match users_copy.get(&name) {
+        Some(user) => user.clone(),
+        None => String::from("unknown"),  // silently returns fallback — hides missing users
+    }
+}
+
+// Accumulates with a manual loop instead of iterator adapters
+fn active_names(users: Vec<(String, bool)>) -> Vec<String> {
+    let mut result = Vec::new();
+    for i in 0..users.len() {
+        if users[i].1 == true {
+            result.push(users[i].0.clone());
+        }
+    }
+    result
+}
+
+// Shared state with no synchronization
+static mut COUNTER: u32 = 0;
+
+fn increment() {
+    unsafe {
+        COUNTER += 1;  // data race — undefined behavior in concurrent code
+    }
+}
+
+// Concrete type parameter instead of trait bound
+fn print_user(user: String) {
+    println!("{}", user);
+}
+
+fn main() {
+    let config = load_config(String::from("config.toml"));
+    println!("{}", config);
+
+    let mut users = HashMap::new();
+    users.insert(String::from("alice"), String::from("admin"));
+
+    // Moves users into get_user — can't use it after
+    let name = get_user(users, String::from("alice"));
+    println!("{}", name);
+    // println!("{:?}", users);  // would fail: users was moved
+}
+```

package/skills/programming-with-rust/references/api_reference.md

@@ -0,0 +1,152 @@
+# Programming with Rust — Chapter Reference
+
+All 23 chapters from Donis Marshall's "Programming with Rust" with key topics and priority levels.
+
+## Ch 1: Introduction to Rust
+**Key topics:** Functional programming, expression-oriented, pattern-oriented, safeness, ownership, lifetimes, fearless concurrency, zero-cost abstraction, Rust terminology, tools
+**Priority:** Foundation
+
+## Ch 2: Getting Started
+**Key topics:** Cargo, crates, library vs binary, `main` function, command-line arguments, comments, `rustup`
+**Priority:** Foundation
+
+## Ch 3: Variables
+**Key topics:** Immutability by default (`let` vs `let mut`), integer types, overflow behavior, floating point, boolean, char, pointers, references, operators
+**Priority:** Important — immutability by default is a key Rust safety idiom
+
+## Ch 4: Strings
+**Key topics:** `&str` (string slice, stack) vs `String` (heap-allocated, owned), deref coercion, `format!`, helpful string functions
+**Idiom:** Accept `&str` in function parameters — `String` derefs to `&str` automatically
+**Priority:** Important
+
+## Ch 5: Console
+**Key topics:** `println!`, positional/variable/named arguments, padding/alignment, `Display` trait, `Debug` trait, `format!`, `write!`
+**Priority:** Suggestion
+
+## Ch 6: Control Flow
+**Key topics:** `if` as expression, `while`, `for`/`in` (iterator-based), `loop`, `break`/`continue`, loop labels, `Iterator` trait
+**Idiom:** Use `for item in collection` over manual indexing; use iterator adapters over manual loops
+**Priority:** Important
+
+## Ch 7: Collections
+**Key topics:** Arrays (fixed-size, stack), slices, Vecs (heap, growable), multidimensional, `HashMap` (entry API, iteration, update)
+**Priority:** Important
+
+## Ch 8: Ownership
+**Key topics:** Stack vs heap, shallow vs deep copy, move semantics, borrow, copy semantics, `Clone` trait, `Copy` trait
+**Critical rules:**
+- Each value has exactly one owner
+- When owner goes out of scope, value is dropped
+- Move transfers ownership — old binding is invalid
+- `Copy` types (primitives) are copied instead of moved
+**Priority:** Critical
+
+## Ch 9: Lifetimes
+**Key topics:** Lifetime annotation syntax (`'a`), lifetime elision rules, function headers, complex lifetimes, `'static`, structs/methods with lifetimes, subtyping, anonymous lifetimes, generics and lifetimes
+**Idiom:** Rely on elision; annotate only when compiler cannot infer (multiple reference params with ambiguous output lifetime)
+**Priority:** Critical
+
+## Ch 10: References
+**Key topics:** Declaration, borrowing, dereferencing, comparing references, reference notation, mutability, limits to multiple borrowers
+**Critical rules:**
+- At any time: one `&mut T` OR any number of `&T` — never both
+- References must not outlive the referent
+**Priority:** Critical
+
+## Ch 11: Functions
+**Key topics:** Function definition, parameters, return values, `const fn`, nested functions, function pointers, function aliases
+**Priority:** Important
+
+## Ch 12: Error Handling
+**Key topics:** `Result<T, E>`, `Option<T>`, panics, `panic!` macro, handling panics, `.unwrap()`, `.expect()`, `?` operator, `match` on Result/Option, `.map()`, rich errors, custom error types
+**Critical rules:**
+- Library code: always `Result`, never panic
+- Use `?` for propagation, not `.unwrap()`
+- Define custom error types implementing `std::error::Error`
+- Implement `From<E>` for automatic `?` conversion
+**Priority:** Critical
+
+## Ch 13: Structures
+**Key topics:** Struct definition, alternate initialization, move semantics with structs, mutability, methods (`&self`, `&mut self`, `self`), associated functions (`new`), `impl` blocks, operator overloading, tuple structs, unit-like structs
+**Priority:** Important
+
+## Ch 14: Generics
+**Key topics:** Generic functions, trait bounds, `where` clause, generic structs, associated functions, generic enums, generic traits, explicit specialization
+**Idiom:** Use `where` clause for complex bounds; prefer narrowest possible bounds
+**Priority:** Important
+
+## Ch 15: Patterns
+**Key topics:** `let` destructuring, wildcards (`_`), complex patterns, ownership in patterns, irrefutable patterns, ranges, multiple patterns (`|`), control flow patterns, struct destructuring, function parameter patterns, `match` expressions, match guards
+**Idiom:** `match` is exhaustive — let the compiler enforce all cases; use `if let` for single-variant matches
+**Priority:** Important
+
+## Ch 16: Closures
+**Key topics:** Closure syntax, captured variables, closures as arguments/return values, `Fn` (immutable borrow), `FnMut` (mutable borrow), `FnOnce` (move/consume), `move` keyword, `impl` keyword for return types
+**Idiom:** Use `move` closures when passing to threads to transfer ownership of captured values
+**Priority:** Important
+
+## Ch 17: Traits
+**Key topics:** Trait definition, default functions, marker traits (`Send`, `Sync`), associated functions, associated types, extension methods, fully qualified syntax, supertraits, static dispatch (`impl Trait`), dynamic dispatch (`dyn Trait`), enums and traits
+**Critical rules:**
+- Prefer `impl Trait` (static, zero-cost) over `dyn Trait` (runtime overhead via vtable)
+- Use `dyn Trait` only when returning heterogeneous types or building plugin systems
+**Priority:** Critical
+
+## Ch 18: Threads 1
+**Key topics:** Synchronous vs asynchronous calls, `std::thread::spawn`, thread type, `Builder`, CSP (Communicating Sequential Process), async/sync/rendezvous channels (`mpsc`), `try_recv`, store example
+**Idiom:** Prefer message passing (channels) over shared state when possible
+**Priority:** Important
+
+## Ch 19: Threads 2
+**Key topics:** `Mutex<T>`, nonscoped mutex, mutex poisoning, `RwLock<T>`, condition variables (`Condvar`), atomic operations (`AtomicUsize`, etc.), store/load, fetch-and-modify, compare-and-exchange
+**Idiom:** Use `Arc<Mutex<T>>` for shared mutable state; `Arc<RwLock<T>>` for read-heavy workloads
+**Priority:** Critical
+
+## Ch 20: Memory
+**Key topics:** Stack vs heap allocation, static values, `Box<T>` (heap allocation), interior mutability pattern, `RefCell<T>` (runtime borrow checking, single-threaded), `OnceCell<T>` (lazy initialization)
+**Idiom:** Stack-allocate by default; use `Box` only when size is unknown at compile time or for recursive types
+**Priority:** Important
+
+## Ch 21: Macros
+**Key topics:** Tokens, declarative macros (`macro_rules!`), repetition, multiple matchers, procedural macros (derive, attribute, function-like), `#[derive(...)]`
+**Idiom:** Use `#[derive]` before writing manual `impl` blocks; write `macro_rules!` for repeated patterns
+**Priority:** Suggestion
+
+## Ch 22: Interoperability
+**Key topics:** FFI, `extern "C"`, `unsafe` blocks, `libc` crate, structs across FFI, `bindgen` (C → Rust), `cbindgen` (Rust → C)
+**Priority:** Suggestion (only when needed)
+
+## Ch 23: Modules
+**Key topics:** Module items, `pub` visibility, module files, `path` attribute, functions and modules, `crate`/`super`/`self` keywords, legacy module model
+**Idiom:** Organize by domain, not by type; keep `pub` surface minimal; use `pub(crate)` for internal-only APIs
+**Priority:** Important
+
+---
+
+## Priority Summary
+
+**Critical (understand deeply before writing any Rust)**
+- Ch 8: Ownership and move semantics
+- Ch 9: Lifetimes and elision
+- Ch 10: Borrowing rules (one `&mut` OR many `&`)
+- Ch 12: Error handling with Result, ?, custom errors
+- Ch 17: Trait dispatch (impl vs dyn)
+- Ch 19: Thread safety with Mutex/RwLock/Arc
+
+**Important (apply consistently)**
+- Ch 3: Immutability by default
+- Ch 4: `&str` vs `String`
+- Ch 6: Iterator-based loops
+- Ch 11: Function design
+- Ch 13: Structs and impl blocks
+- Ch 14: Generics and bounds
+- Ch 15: Exhaustive pattern matching
+- Ch 16: Closures and move semantics
+- Ch 18: Channels for concurrency
+- Ch 20: Stack vs heap, RefCell
+- Ch 23: Module visibility
+
+**Suggestion (apply when relevant)**
+- Ch 5: Formatting and Display/Debug
+- Ch 21: Macros and derive
+- Ch 22: FFI/interop