feat: add Mermaid diagram files for 8 beginner Python concepts

Create concepts/diagrams/ with visual explanations for variables, loops,
types, functions, collections, files, errors, and error messages. Each
file contains 2-4 Mermaid diagrams targeting absolute beginners with
zero programming experience, and links back to its parent concept doc.

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

Author: travisjneuman

concepts/diagrams/collections-explained.md

@@ -0,0 +1,87 @@
+# Diagrams: Collections Explained
+
+[Back to concept](../collections-explained.md)
+
+---
+
+## Side-by-Side Comparison
+
+Each collection type has different properties. Pick the one that fits your needs.
+
+```mermaid
+flowchart TD
+    subgraph LIST ["list  [1, 2, 3]"]
+        L1["Mutable: YES"]
+        L2["Ordered: YES"]
+        L3["Indexed: YES - items[0]"]
+        L4["Duplicates: YES"]
+    end
+
+    subgraph TUPLE ["tuple  (1, 2, 3)"]
+        T1["Mutable: NO"]
+        T2["Ordered: YES"]
+        T3["Indexed: YES - items[0]"]
+        T4["Duplicates: YES"]
+    end
+
+    subgraph DICT ["dict  {'a': 1, 'b': 2}"]
+        D1["Mutable: YES"]
+        D2["Ordered: YES (3.7+)"]
+        D3["Indexed: BY KEY - items['a']"]
+        D4["Duplicate keys: NO"]
+    end
+
+    subgraph SET ["set  {1, 2, 3}"]
+        S1["Mutable: YES"]
+        S2["Ordered: NO"]
+        S3["Indexed: NO"]
+        S4["Duplicates: NO"]
+    end
+
+    style LIST fill:#4a9eff,stroke:#2670c2,color:#fff
+    style TUPLE fill:#20c997,stroke:#0ca678,color:#fff
+    style DICT fill:#ff922b,stroke:#e8590c,color:#fff
+    style SET fill:#cc5de8,stroke:#9c36b5,color:#fff
+```
+
+## Decision Tree: Which Collection Should I Use?
+
+```mermaid
+flowchart TD
+    START{"What do you<br/>need to store?"}
+    START -->|"Key-value pairs<br/>(name -> value)"| DICT_Q{"Will you<br/>change it?"}
+    DICT_Q -->|Yes| DICT["Use a DICT<br/>{&quot;name&quot;: &quot;Alice&quot;}"]
+    DICT_Q -->|No| DICT
+
+    START -->|"A group of<br/>unique items"| SET["Use a SET<br/>{&quot;a&quot;, &quot;b&quot;, &quot;c&quot;}"]
+
+    START -->|"An ordered<br/>sequence of items"| SEQ_Q{"Will you need<br/>to change it later?"}
+    SEQ_Q -->|"Yes — add, remove,<br/>or change items"| LIST["Use a LIST<br/>[1, 2, 3]"]
+    SEQ_Q -->|"No — it should<br/>never change"| TUPLE["Use a TUPLE<br/>(1, 2, 3)"]
+
+    style LIST fill:#4a9eff,stroke:#2670c2,color:#fff
+    style TUPLE fill:#20c997,stroke:#0ca678,color:#fff
+    style DICT fill:#ff922b,stroke:#e8590c,color:#fff
+    style SET fill:#cc5de8,stroke:#9c36b5,color:#fff
+```
+
+## How You Access Data in Each Collection
+
+```mermaid
+flowchart LR
+    subgraph "List / Tuple: By Position"
+        LA["items[0]"] --> LV["first item"]
+        LB["items[2]"] --> LW["third item"]
+        LC["items[-1]"] --> LX["last item"]
+    end
+
+    subgraph "Dict: By Key Name"
+        DA["person[&quot;name&quot;]"] --> DV["&quot;Alice&quot;"]
+        DB["person[&quot;age&quot;]"] --> DW["25"]
+    end
+
+    subgraph "Set: No Direct Access"
+        SA["Loop through it"] --> SV["for item in my_set:"]
+        SB["Check membership"] --> SW["&quot;a&quot; in my_set"]
+    end
+```

concepts/diagrams/errors-and-debugging.md

@@ -0,0 +1,78 @@
+# Diagrams: Errors and Debugging
+
+[Back to concept](../errors-and-debugging.md)
+
+---
+
+## Exception Hierarchy
+
+Python errors form a family tree. Catching a parent catches all its children too.
+
+```mermaid
+flowchart TD
+    BASE["BaseException<br/>(do not catch this)"]
+    BASE --> KBI["KeyboardInterrupt<br/>Ctrl+C pressed"]
+    BASE --> SYS["SystemExit<br/>Program told to quit"]
+    BASE --> EXC["Exception<br/>(catch this one)"]
+
+    EXC --> VAL["ValueError<br/>Right type,<br/>wrong value"]
+    EXC --> TYPE["TypeError<br/>Wrong type<br/>entirely"]
+    EXC --> NAME["NameError<br/>Name not<br/>found"]
+    EXC --> IDX["IndexError<br/>List index<br/>out of range"]
+    EXC --> KEY["KeyError<br/>Dict key<br/>not found"]
+    EXC --> ATTR["AttributeError<br/>Object has no<br/>such attribute"]
+    EXC --> FILE["FileNotFoundError<br/>File does<br/>not exist"]
+    EXC --> ZERO["ZeroDivisionError<br/>Divided<br/>by zero"]
+    EXC --> IMPORT["ImportError<br/>Module not<br/>found"]
+    EXC --> SYNTAX["SyntaxError<br/>Code is not<br/>valid Python"]
+
+    style BASE fill:#888,stroke:#666,color:#fff
+    style EXC fill:#4a9eff,stroke:#2670c2,color:#fff
+    style SYNTAX fill:#ff6b6b,stroke:#c0392b,color:#fff
+```
+
+## Try / Except / Else / Finally Flow
+
+```mermaid
+flowchart TD
+    START(["Start"]) --> TRY["TRY block<br/>Run the risky code"]
+    TRY --> ERR{"Did an<br/>error happen?"}
+
+    ERR -->|"Yes"| EXCEPT["EXCEPT block<br/>Handle the error"]
+    ERR -->|"No"| ELSE["ELSE block<br/>Runs only if<br/>NO error happened"]
+
+    EXCEPT --> FINALLY["FINALLY block<br/>ALWAYS runs<br/>(cleanup goes here)"]
+    ELSE --> FINALLY
+
+    FINALLY --> END(["Continue program"])
+
+    style TRY fill:#4a9eff,stroke:#2670c2,color:#fff
+    style EXCEPT fill:#ff6b6b,stroke:#c0392b,color:#fff
+    style ELSE fill:#51cf66,stroke:#27ae60,color:#fff
+    style FINALLY fill:#ffd43b,stroke:#f59f00,color:#000
+```
+
+## Debugging Decision Tree: What Kind of Error?
+
+```mermaid
+flowchart TD
+    START{"Your program<br/>has a problem"}
+
+    START -->|"Red error<br/>message appears"| RUNTIME["RUNTIME ERROR<br/>Program crashed"]
+    START -->|"No error, but<br/>wrong output"| LOGIC["LOGIC ERROR<br/>Code runs but<br/>does the wrong thing"]
+    START -->|"Error before<br/>code even runs"| SYNTAX["SYNTAX ERROR<br/>Python cannot<br/>read your code"]
+
+    SYNTAX --> S1["Check for:<br/>missing colons :<br/>unmatched ( ) [ ]<br/>bad indentation"]
+
+    RUNTIME --> R1["Read the error<br/>message carefully"]
+    R1 --> R2["Find the line<br/>number it points to"]
+    R2 --> R3["Check: what type<br/>of error is it?"]
+
+    LOGIC --> L1["Add print() statements<br/>to see what values<br/>your variables have"]
+    L1 --> L2["Compare expected<br/>vs actual output"]
+    L2 --> L3["Find where they<br/>first differ"]
+
+    style RUNTIME fill:#ff6b6b,stroke:#c0392b,color:#fff
+    style LOGIC fill:#ffd43b,stroke:#f59f00,color:#000
+    style SYNTAX fill:#cc5de8,stroke:#9c36b5,color:#fff
+```

concepts/diagrams/files-and-paths.md

@@ -0,0 +1,82 @@
+# Diagrams: Files and Paths
+
+[Back to concept](../files-and-paths.md)
+
+---
+
+## File I/O Flowchart
+
+The safe way to work with files uses a `with` statement, which closes the file automatically.
+
+```mermaid
+flowchart TD
+    subgraph "WITHOUT with (risky)"
+        A1["f = open("data.txt")"] --> A2["data = f.read()"]
+        A2 --> A3{"Error<br/>happens?"}
+        A3 -->|No| A4["f.close()"]
+        A3 -->|Yes| A5["FILE LEFT OPEN!<br/>Resource leak"]
+        style A5 fill:#ff6b6b,stroke:#c0392b,color:#fff
+    end
+
+    subgraph "WITH with (safe)"
+        B1["with open(&quot;data.txt&quot;) as f:"] --> B2["data = f.read()"]
+        B2 --> B3{"Error<br/>happens?"}
+        B3 -->|No| B4["File closed<br/>automatically"]
+        B3 -->|Yes| B5["File STILL closed<br/>automatically"]
+        style B4 fill:#51cf66,stroke:#27ae60,color:#fff
+        style B5 fill:#51cf66,stroke:#27ae60,color:#fff
+    end
+```
+
+## Path Types: Absolute vs Relative
+
+```mermaid
+flowchart TD
+    subgraph "Absolute Path (full address)"
+        ABS["/home/user/projects/data.txt"]
+        ABS_W["C:\Users\user\projects\data.txt"]
+        ABS_NOTE["Always starts from the root<br/>Works from anywhere"]
+    end
+
+    subgraph "Relative Path (directions from here)"
+        REL1["data.txt<br/>(same folder)"]
+        REL2["../data.txt<br/>(one folder up)"]
+        REL3["sub/data.txt<br/>(inside subfolder)"]
+        REL_NOTE["Depends on where<br/>you are right now"]
+    end
+
+    CWD["Your current<br/>working directory:<br/>/home/user/projects/"]
+    CWD -->|"+ data.txt"| RESULT1["/home/user/projects/data.txt"]
+    CWD -->|"+ ../data.txt"| RESULT2["/home/user/data.txt"]
+    CWD -->|"+ sub/data.txt"| RESULT3["/home/user/projects/sub/data.txt"]
+
+    style ABS_NOTE fill:#4a9eff,stroke:#2670c2,color:#fff
+    style REL_NOTE fill:#ffd43b,stroke:#f59f00,color:#000
+```
+
+## File Mode Decision Tree
+
+The `mode` argument in `open()` controls what you can do with the file.
+
+```mermaid
+flowchart TD
+    START{"What do you<br/>want to do?"}
+
+    START -->|"Read existing<br/>content"| R["mode=&quot;r&quot;<br/>(default)<br/>Read only"]
+    START -->|"Write new content<br/>(erase old)"| W["mode=&quot;w&quot;<br/>Write — erases<br/>existing content!"]
+    START -->|"Add to the end<br/>(keep old)"| A_MODE["mode=&quot;a&quot;<br/>Append — adds<br/>to the end"]
+    START -->|"Create new file<br/>(fail if exists)"| X["mode=&quot;x&quot;<br/>Exclusive create"]
+
+    R --> TEXT_Q{"Text or<br/>binary data?"}
+    W --> TEXT_Q
+    A_MODE --> TEXT_Q
+    X --> TEXT_Q
+
+    TEXT_Q -->|"Text<br/>(words, CSV, JSON)"| TEXT["No extra flag<br/>open(&quot;f.txt&quot;, &quot;r&quot;)"]
+    TEXT_Q -->|"Binary<br/>(images, PDFs)"| BIN["Add b<br/>open(&quot;f.png&quot;, &quot;rb&quot;)"]
+
+    style W fill:#ff6b6b,stroke:#c0392b,color:#fff
+    style A_MODE fill:#51cf66,stroke:#27ae60,color:#fff
+    style R fill:#4a9eff,stroke:#2670c2,color:#fff
+    style X fill:#ffd43b,stroke:#f59f00,color:#000
+```

concepts/diagrams/functions-explained.md

@@ -0,0 +1,99 @@
+# Diagrams: Functions Explained
+
+[Back to concept](../functions-explained.md)
+
+---
+
+## Function Call Sequence
+
+When you call a function, Python jumps into it, does work, then comes back with a result.
+
+```mermaid
+sequenceDiagram
+    participant Caller as Your Code
+    participant Func as Function
+
+    Caller->>Func: Call: greet("Alice")
+    Note over Func: name = "Alice"
+    Note over Func: Run the function body
+    Note over Func: Build result: "Hello, Alice!"
+    Func-->>Caller: Return: "Hello, Alice!"
+    Note over Caller: Continue with the result
+```
+
+## Parameter Passing Flow
+
+Arguments are values you send IN. The return value is what comes back OUT.
+
+```mermaid
+flowchart LR
+    subgraph Caller
+        A1["area = calculate(5, 3)"]
+    end
+
+    subgraph "Function: calculate(width, height)"
+        B1["width = 5"]
+        B2["height = 3"]
+        B3["result = 5 * 3"]
+        B4["return 15"]
+        B1 --> B2 --> B3 --> B4
+    end
+
+    A1 -->|"arguments go IN<br/>5 and 3"| B1
+    B4 -->|"return value<br/>comes OUT: 15"| A1
+
+    style A1 fill:#4a9eff,stroke:#2670c2,color:#fff
+    style B4 fill:#51cf66,stroke:#27ae60,color:#fff
+```
+
+## Call Stack: Nested Function Calls
+
+When functions call other functions, Python stacks them up and unwinds when each one finishes.
+
+```mermaid
+flowchart TD
+    subgraph "Step 1: main() runs"
+        S1["main() calls greet()"]
+    end
+
+    subgraph "Step 2: greet() runs"
+        S2["greet() calls format_name()"]
+    end
+
+    subgraph "Step 3: format_name() runs"
+        S3["format_name() returns &quot;ALICE&quot;"]
+    end
+
+    subgraph "Step 4: Unwinding"
+        S4["greet() gets &quot;ALICE&quot;, returns &quot;Hello, ALICE!&quot;"]
+    end
+
+    subgraph "Step 5: Done"
+        S5["main() gets &quot;Hello, ALICE!&quot;"]
+    end
+
+    S1 --> S2 --> S3 --> S4 --> S5
+```
+
+## Scope Chain: Where Python Looks for Names
+
+When you use a variable name, Python searches in this order (LEGB rule).
+
+```mermaid
+flowchart TD
+    LOOKUP["Python sees a name<br/>like x"] --> L{"1. Local?<br/>Inside this function?"}
+    L -->|Found| DONE(["Use that value"])
+    L -->|Not found| E{"2. Enclosing?<br/>Inside an outer function?"}
+    E -->|Found| DONE
+    E -->|Not found| G{"3. Global?<br/>At the top level<br/>of the file?"}
+    G -->|Found| DONE
+    G -->|Not found| B{"4. Built-in?<br/>Python built-in names?<br/>(print, len, range)"}
+    B -->|Found| DONE
+    B -->|Not found| ERR["NameError!<br/>Python cannot find it"]
+
+    style L fill:#4a9eff,stroke:#2670c2,color:#fff
+    style E fill:#51cf66,stroke:#27ae60,color:#fff
+    style G fill:#ffd43b,stroke:#f59f00,color:#000
+    style B fill:#cc5de8,stroke:#9c36b5,color:#fff
+    style ERR fill:#ff6b6b,stroke:#c0392b,color:#fff
+```