feat: add step-by-step WALKTHROUGH.md files for 12 key beginner projects

Walkthroughs guide learners through the thinking process without giving
away the complete solution. Each covers understanding the problem, planning,
incremental steps with "predict before you scroll" prompts, common mistakes,
testing guidance, and extension ideas.

Level 00 (3 walkthroughs): shorter, simpler for absolute beginners
Level 0 (3 walkthroughs): detailed with Mermaid diagrams
Level 1 (3 walkthroughs): detailed with Mermaid pipeline diagrams
Level 2 (3 walkthroughs): detailed with Mermaid diagrams and z-score explanation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: travisjneuman

projects/level-0/01-terminal-hello-lab/WALKTHROUGH.md

@@ -0,0 +1,136 @@
+# Walkthrough: Terminal Hello Lab
+
+> This guide walks through the **thinking process** for building this project.
+> It does NOT give you the complete solution. For that, see [SOLUTION.md](./SOLUTION.md).
+
+## Before reading this
+
+**Try the project yourself first.** Spend at least 20 minutes.
+If you have not tried yet, close this file and open the [project README](./README.md).
+
+---
+
+## Understanding the problem
+
+You need to build a script that asks the user for their name and which day of their Python journey it is, then prints a decorated banner, a personalised greeting, a fun fact, and an info card. The key functions are `greet()`, `build_banner()`, `build_info_card()`, and `run_hello_lab()`.
+
+This is your first project with **tests**. The functions must return values (not just print), so the tests can call them directly and check the output.
+
+## Planning before code
+
+```mermaid
+flowchart TD
+    A[User types name and day] --> B[greet: build greeting string]
+    A --> C[build_banner: create bordered title]
+    B --> D[run_hello_lab: print everything]
+    C --> D
+    D --> E[build_info_card: collect summary dict]
+    E --> F[Print info card]
+```
+
+Break the project into three independent building blocks, then one function that ties them together:
+
+1. **greet()** -- take a name, return a greeting string
+2. **build_banner()** -- take a title, return a bordered banner
+3. **build_info_card()** -- take name/language/day, return a dictionary
+4. **run_hello_lab()** -- call the above, print everything, return the info card
+
+## Step 1: The greeting function
+
+Start with the simplest piece. `greet()` takes a name and returns a string.
+
+```python
+def greet(name: str) -> str:
+    return f"Hello, {name}! Welcome to Python."
+```
+
+The f-string `f"Hello, {name}!"` inserts the value of `name` into the text. This is cleaner than concatenation (`"Hello, " + name + "!"`).
+
+### Predict before you scroll
+
+What does `greet("Ada")` return? What about `greet("")`? Is an empty-name greeting a problem the tests will care about?
+
+## Step 2: The banner function
+
+The banner wraps a title in asterisks. You need:
+- A top border (a line of `*` characters)
+- The title, centred
+- A bottom border
+
+```python
+def build_banner(title: str, width: int = 40) -> str:
+    border = "*" * width
+    centered_title = title.center(width)
+    return f"{border}\n{centered_title}\n{border}"
+```
+
+Two things to notice:
+- `"*" * width` repeats the `*` character `width` times. This is **string multiplication**.
+- `.center(width)` pads the string with spaces on both sides so it sits in the middle.
+
+### Predict before you scroll
+
+If `width` is 40 and `title` is `"HI"`, how many spaces will appear before `"HI"` in the centred line?
+
+## Step 3: The info card
+
+This function collects facts into a dictionary. Dictionaries let you label data with keys instead of relying on position.
+
+```python
+def build_info_card(name: str, language: str, day: int) -> dict:
+    return {
+        "name": name,
+        "language": language,
+        "learning_day": day,
+        "greeting": greet(name),  # reuses greet()!
+    }
+```
+
+Notice that `build_info_card` calls `greet()` inside it. Functions can call other functions -- this is **composition**.
+
+## Step 4: Tying it together
+
+`run_hello_lab()` is the orchestrator. It calls the building blocks, prints output, and returns the info card.
+
+```python
+def run_hello_lab(name: str, day: int) -> dict:
+    print(build_banner("TERMINAL HELLO LAB"))
+    print()
+    print(greet(name))
+    print(f"\tDay {day} of your Python journey.")
+    # ...
+    return build_info_card(name, "Python", day)
+```
+
+The `\t` inside the f-string is a **tab character** -- it indents the text.
+
+## Common mistakes
+
+| Mistake | Why it happens | How to fix |
+|---------|---------------|------------|
+| `greet()` prints instead of returning | Confusing `print()` with `return` | `print()` shows text on screen; `return` sends data back to the caller. Tests need `return`. |
+| Banner width is wrong | Forgetting that `.center()` pads to a total width, not adds that much padding | `.center(40)` makes the whole string 40 characters wide |
+| `int(input(...))` crashes on non-numbers | The user typed letters instead of a number | Wrap in `try/except ValueError` or check `.isdigit()` first |
+| Forgetting `if __name__ == "__main__"` | Not understanding the guard | Without it, the `input()` calls run when tests import the file |
+
+## Testing your solution
+
+Run the tests from the project directory:
+
+```bash
+pytest -q
+```
+
+The five tests check:
+- `greet("Ada")` contains "Ada" and "Hello"
+- `greet()` works for multiple different names
+- `build_banner("MY TITLE")` contains the title and has 3 lines
+- `build_banner("HI", width=20)` produces borders exactly 20 characters wide
+- `build_info_card("Test", "Python", 5)` returns a dict with all expected keys
+
+If a test fails, read the assertion error carefully -- it tells you what value it expected vs. what it got.
+
+## What to explore next
+
+1. Add a `build_greeting_box()` function that wraps the greeting in a box made of `+`, `-`, and `|` characters
+2. Add input validation: what should happen if the user types nothing for their name, or letters for the day number?

projects/level-0/07-first-file-reader/WALKTHROUGH.md

@@ -0,0 +1,152 @@
+# Walkthrough: First File Reader
+
+> This guide walks through the **thinking process** for building this project.
+> It does NOT give you the complete solution. For that, see [SOLUTION.md](./SOLUTION.md).
+
+## Before reading this
+
+**Try the project yourself first.** Spend at least 20 minutes.
+If you have not tried yet, close this file and open the [project README](./README.md).
+
+---
+
+## Understanding the problem
+
+You need to build a program that reads a text file, displays its contents with line numbers, and prints a summary (line count, word count, character count, non-empty lines). The program asks the user for a file path and handles the case where the file does not exist.
+
+This is your first encounter with **file I/O** -- reading data from a file on disk instead of from user input.
+
+## Planning before code
+
+```mermaid
+flowchart TD
+    A[User enters file path] --> B{File exists?}
+    B -->|No| C[Print error message]
+    B -->|Yes| D[read_file_lines: read all lines]
+    D --> E[format_with_line_numbers: add numbers]
+    D --> F[file_summary: count words/lines/chars]
+    E --> G[Display numbered contents]
+    F --> H[Display summary stats]
+```
+
+Three independent functions, plus error handling:
+
+1. **read_file_lines()** -- open a file, return a list of lines
+2. **format_with_line_numbers()** -- take lines, add line numbers
+3. **file_summary()** -- count lines, words, characters
+4. **Main block** -- ask for path, handle errors, display output
+
+## Step 1: Reading lines from a file
+
+The fundamental pattern for reading a file in Python:
+
+```python
+def read_file_lines(filepath: str) -> list:
+    with open(filepath, encoding="utf-8") as f:
+        return f.read().splitlines()
+```
+
+Two important things here:
+
+- **`with open(...) as f`** opens the file and guarantees it gets closed when you are done, even if an error occurs. Always use `with` for files.
+- **`.splitlines()`** splits the text on newline characters and returns a list. Unlike `.split("\n")`, it does not leave an extra empty string at the end if the file ends with a newline.
+
+### Predict before you scroll
+
+If `sample_input.txt` contains three lines (one blank), how many items will the returned list have? Will the blank line be included or skipped?
+
+## Step 2: Adding line numbers
+
+You want output like:
+
+```
+  1 | Welcome to your first file reader!
+  2 |
+  3 | This file has several lines of text.
+```
+
+The `enumerate()` function gives you both the index and the value as you loop:
+
+```python
+def format_with_line_numbers(lines: list) -> str:
+    if not lines:
+        return "(empty file)"
+
+    width = len(str(len(lines)))  # how many digits for the biggest line number
+
+    numbered = []
+    for i, line in enumerate(lines, start=1):
+        numbered.append(f"  {i:>{width}} | {line}")
+
+    return "\n".join(numbered)
+```
+
+The key trick is `f"{i:>{width}}"`. The `:>` means right-align, and `width` is how many characters wide to make the number. For a 100-line file, `width` would be 3, so line 1 displays as `  1` and line 100 displays as `100`.
+
+### Predict before you scroll
+
+Why does the function handle the empty-lines case separately at the top? What would go wrong if `lines` were an empty list and you tried to calculate `width`?
+
+## Step 3: Building the summary
+
+The summary counts several things about the file:
+
+```python
+def file_summary(filepath: str, lines: list) -> dict:
+    text = "\n".join(lines)
+    word_count = len(text.split())
+
+    name = filepath.replace("\\", "/").split("/")[-1]
+
+    return {
+        "file_name": name,
+        "lines": len(lines),
+        "words": word_count,
+        "characters": len(text),
+        "non_empty_lines": sum(1 for line in lines if line.strip()),
+    }
+```
+
+Notice the last line: `sum(1 for line in lines if line.strip())`. This is a **generator expression** that counts only lines that are not blank. `line.strip()` removes whitespace -- if what is left is an empty string, it is falsy, so the condition filters it out.
+
+## Step 4: Handling missing files
+
+In the main block, wrap the file reading in `try/except`:
+
+```python
+try:
+    lines = read_file_lines(filepath)
+except FileNotFoundError:
+    print(f"  File not found: {filepath}")
+```
+
+This prevents the program from crashing with an ugly traceback when the user types a wrong path.
+
+## Common mistakes
+
+| Mistake | Why it happens | How to fix |
+|---------|---------------|------------|
+| Using `f.readlines()` instead of `f.read().splitlines()` | Both read lines, but `readlines()` keeps the `\n` at the end of each line | Use `.read().splitlines()` for clean lines without trailing newlines |
+| Line numbers start at 0 | `enumerate()` defaults to `start=0` | Pass `start=1` to `enumerate()` |
+| Word count is wrong | Splitting on just `" "` misses tabs and multiple spaces | Use `.split()` with no argument -- it splits on any whitespace |
+| Crash on empty file | Dividing by zero or formatting empty data | Check `if not lines` at the start and return early |
+
+## Testing your solution
+
+Run the tests from the project directory:
+
+```bash
+pytest -q
+```
+
+The five tests check:
+- Reading a simple 3-line file returns the correct lines
+- Reading a missing file raises `FileNotFoundError`
+- `format_with_line_numbers()` adds correct line numbers
+- An empty file produces the `"(empty file)"` message
+- `file_summary()` returns correct line and word counts
+
+## What to explore next
+
+1. Add a feature that asks the user for start and end line numbers, then displays only that range
+2. After showing the summary, ask "Read another file? (y/n):" and loop if yes