Add Mermaid diagrams to 14 READMEs for complex designs

- FSMs: Mealy FSM, Divisible by 3/5, Stopwatch Timer, Sequence Detector
- Serial/Parallel: Serialiser, Deserialiser
- Arithmetic: Ripple Carry Adder, Carry Select Adder, ALU
- Memory: Multi-Bit FIFO (state + data flow)
- Advanced: LFSR, Bubble Sort, Edge Detector

Diagrams visualize state machines, data flow, timing, and architecture

Author: nselvara

ip/06_Edge_Detector/README.md

@@ -28,6 +28,56 @@ Bonus - can you enhance your design to pulse `dout` on the same cycle as the ris
 Rising edge detector that registers the previous input value each clock cycle and outputs a single-cycle pulse when `din='1'` and differs from the registered value.
 The comparison `din /= din_reg` detects the transition, while the `din = '1'` check ensures it's specifically a rising edge.
 
+### Operation Diagram
+
+```mermaid
+flowchart LR
+    subgraph "Clock Cycle N"
+        din[din current] --> compare{din = 1<br/>AND<br/>din ≠ din_reg?}
+        din_reg[din_reg<br/>previous value] --> compare
+        compare -->|yes| pulse[dout = 1<br/>PULSE!]
+        compare -->|no| zero[dout = 0]
+    end
+
+    subgraph "Next Cycle"
+        din --> reg[Register]
+        reg --> din_reg_next[din_reg ← din]
+    end
+
+    style pulse fill:#ffe1e1
+    style zero fill:#ffe1e1
+    style din fill:#e1f5ff
+```
+
+### Timing Example
+
+```mermaid
+%%{init: {'theme':'base'}}%%
+gantt
+    title Edge Detection Timing
+    dateFormat X
+    axisFormat %L
+
+    section din
+    Low :0, 3
+    Rising Edge :milestone, 3, 3
+    High :3, 5
+    Falling Edge :milestone, 5, 5
+    Low :5, 7
+
+    section din_reg
+    Low :0, 4
+    High :4, 6
+    Low :6, 7
+
+    section dout
+    Low :0, 4
+    Pulse :crit, 4, 5
+    Low :5, 7
+```
+
+**Detection Logic:** `dout = (din AND (din XOR din_reg))` → True only on 0→1 transition.
+
 ---
 
 ## Source

ip/07_Serialiser/README.md

@@ -39,6 +39,39 @@ Serializer that captures a parallel input word when `din_en` asserts and shifts
 A `bit_index` counter tracks which bit to output, incrementing from 0 to `DATA_WIDTH-1`.
 The captured data remains in `din_reg` until the entire word is transmitted, then zeros out.
 
+### Operation Diagram
+
+```mermaid
+flowchart TD
+    Start([Start]) --> Reset{resetn?}
+    Reset -->|active| Zero[dout = 0<br/>din_reg = 0<br/>bit_index = 0]
+    Reset -->|inactive| CheckEn{din_en?}
+
+    CheckEn -->|yes| Capture[Capture din<br/>din_reg ← din<br/>bit_index = 0]
+    CheckEn -->|no| CheckIndex{bit_index <<br/>DATA_WIDTH?}
+
+    Capture --> OutputBit[dout ← din_reg bit_index]
+
+    CheckIndex -->|yes| OutputBit
+    CheckIndex -->|no| OutputZero[dout ← 0]
+
+    OutputBit --> Increment[bit_index++]
+    OutputZero --> NextCycle([Next Clock Cycle])
+    Increment --> NextCycle
+
+    NextCycle --> Reset
+
+    style Capture fill:#e1f5ff
+    style OutputBit fill:#ffe1e1
+    style OutputZero fill:#ffe1e1
+```
+
+**Timing:**
+
+- Cycle 0: `din_en=1` captures parallel word → outputs bit 0
+- Cycle 1-N: Shifts out bits 1 through DATA_WIDTH-1
+- Cycle N+1: All bits sent, outputs 0
+
 ---
 
 ## Source

ip/08_Deserialiser/README.md

@@ -34,6 +34,43 @@ Deserialiser that reconstructs a parallel word from serial input.
 Each clock cycle shifts the output register left and inserts the new `din` bit at the LSB position using the concatenation `dout <= dout(dout'high - 1 downto 0) & din`.
 After `DATA_WIDTH` clock cycles, the complete word appears at the output.
 
+### Operation Diagram
+
+```mermaid
+flowchart LR
+    subgraph "Clock Cycle N"
+        direction TB
+        din[din] --> shift[Shift Left]
+        dout_old[dout old] --> shift
+        shift --> dout_new[dout new]
+    end
+
+    subgraph "Bit Packing (LSB first)"
+        direction LR
+        bit0[Cycle 0<br/>din → bit 0] --> bit1[Cycle 1<br/>din → bit 1]
+        bit1 --> bit2[Cycle 2<br/>din → bit 2]
+        bit2 --> bitN[...<br/>Cycle N-1<br/>din → bit N-1]
+    end
+
+    subgraph "Output Word"
+        direction LR
+        msb[MSB<br/>oldest bit] -.-> mid[...] -.-> lsb[LSB<br/>newest bit]
+    end
+
+    style din fill:#e1f5ff
+    style dout_new fill:#ffe1e1
+```
+
+**Shift Register Operation:**
+
+```flow
+Cycle 0: dout = 0000_0000, din=1 → dout = 0000_0001
+Cycle 1: dout = 0000_0001, din=0 → dout = 0000_0010
+Cycle 2: dout = 0000_0010, din=1 → dout = 0000_0101
+Cycle 3: dout = 0000_0101, din=0 → dout = 0000_1010
+...
+```
+
 ---
 
 ## Source

ip/14_Stopwatch_Timer/README.md

@@ -35,6 +35,49 @@ The `start_reg` variable latches the start condition, continuing the count until
 When the counter reaches MAX, it wraps to zero.
 The start signal acts as a sticky enable - once asserted, counting continues autonomously until explicitly stopped.
 
+### State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> RESET: reset=1
+
+    RESET --> STOPPED: reset=0
+
+    STOPPED --> COUNTING: start_in=1
+    STOPPED --> RESET: reset=1
+
+    COUNTING --> COUNTING: count++<br/>(wrap at MAX)
+    COUNTING --> STOPPED: stop_in=1
+    COUNTING --> RESET: reset=1
+
+    note right of RESET
+        count_out = 0
+        start_reg = 0
+        Priority: Highest
+    end note
+
+    note right of STOPPED
+        count_out = frozen
+        start_reg = 0
+        Waiting for start
+    end note
+
+    note right of COUNTING
+        count_out increments
+        each clock cycle
+        start_reg = 1
+    end note
+```
+
+**Control Priority:** `reset` > `stop_in` > `start_in`
+
+**Operation:**
+
+- `start_in` latches into `start_reg` (sticky enable)
+- Once started, counting continues automatically
+- `stop_in` clears `start_reg` to halt counting
+- Counter wraps to 0 when reaching MAX
+
 ---
 
 ## Source

ip/15_Sequence_Detector/README.md

@@ -29,6 +29,56 @@ Parameterizable sequence detector using a shift register matched against a const
 Each clock shifts the serial input `din` into the register, with the code handling both ascending and descending bit orderings via compile-time selection.
 Detection pulses high when the shift register contents exactly match `SEQUENCE_PATTERN`.
 
+### State Diagram (for pattern "1010")
+
+```mermaid
+stateDiagram-v2
+    [*] --> IDLE: reset
+
+    IDLE --> SAW_1: din=1
+    IDLE --> IDLE: din=0
+
+    SAW_1 --> SAW_10: din=0
+    SAW_1 --> SAW_1: din=1
+
+    SAW_10 --> SAW_101: din=1
+    SAW_10 --> IDLE: din=0
+
+    SAW_101 --> DETECTED: din=0<br/>dout=1 ✓
+    SAW_101 --> SAW_1: din=1
+
+    DETECTED --> SAW_10: din=0
+    DETECTED --> SAW_1: din=1
+
+    note right of IDLE
+        shift_reg = xxxx
+        No match yet
+    end note
+
+    note right of SAW_1
+        shift_reg = xxx1
+        Partial match: "1"
+    end note
+
+    note right of SAW_10
+        shift_reg = xx10
+        Partial match: "10"
+    end note
+
+    note right of SAW_101
+        shift_reg = x101
+        Partial match: "101"
+    end note
+
+    note right of DETECTED
+        shift_reg = 1010
+        FULL MATCH!
+        dout pulses high
+    end note
+```
+
+**Implementation:** Shift register continuously shifts `din` in, comparator checks if register equals `SEQUENCE_PATTERN` ("1010").
+
 ---
 
 ## Source

ip/16_Divisible_by_3/README.md

@@ -34,6 +34,51 @@ Exploits the property that powers of 2 modulo 3 alternate between 1 and 2 (2^0
 The state machine tracks remainder {0,1,2} as each bit arrives, with state transitions encoding how each bit contributes to the running modulo-3 sum.
 Divisible when final state is `rem_0`.
 
+### State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> rem_0: reset
+
+    rem_0 --> rem_0: din=0<br/>dout=1
+    rem_0 --> rem_1: din=1<br/>dout=0
+
+    rem_1 --> rem_2: din=0<br/>dout=0
+    rem_1 --> rem_0: din=1<br/>dout=1
+
+    rem_2 --> rem_1: din=0<br/>dout=0
+    rem_2 --> rem_2: din=1<br/>dout=0
+
+    note right of rem_0
+        Remainder = 0
+        Divisible by 3!
+        dout = 1
+    end note
+
+    note right of rem_1
+        Remainder = 1
+        Not divisible
+        dout = 0
+    end note
+
+    note right of rem_2
+        Remainder = 2
+        Not divisible
+        dout = 0
+    end note
+```
+
+**State Transition Logic:**
+
+- When `din=0`: Left-shift the value (multiply by 2)
+  - rem_0 → rem_0: `(0×2) mod 3 = 0`
+  - rem_1 → rem_2: `(1×2) mod 3 = 2`
+  - rem_2 → rem_1: `(2×2) mod 3 = 1`
+- When `din=1`: Left-shift and add 1 (multiply by 2, add 1)
+  - rem_0 → rem_1: `(0×2+1) mod 3 = 1`
+  - rem_1 → rem_0: `(1×2+1) mod 3 = 0`
+  - rem_2 → rem_2: `(2×2+1) mod 3 = 2`
+
 ---
 
 ## Source

ip/17_Divisible_by_5/README.md

@@ -34,6 +34,62 @@ Powers of 2 modulo 5 cycle as {1,2,4,3,1...}, which the state machine tracks acr
 Each input bit transitions the state according to its positional contribution modulo 5.
 Divisible when final state is `rem_0`.
 
+### State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> rem_0: reset
+
+    rem_0 --> rem_0: din=0<br/>dout=1
+    rem_0 --> rem_1: din=1<br/>dout=0
+
+    rem_1 --> rem_2: din=0<br/>dout=0
+    rem_1 --> rem_3: din=1<br/>dout=0
+
+    rem_2 --> rem_4: din=0<br/>dout=0
+    rem_2 --> rem_0: din=1<br/>dout=1
+
+    rem_3 --> rem_1: din=0<br/>dout=0
+    rem_3 --> rem_2: din=1<br/>dout=0
+
+    rem_4 --> rem_3: din=0<br/>dout=0
+    rem_4 --> rem_4: din=1<br/>dout=0
+
+    note right of rem_0
+        Remainder = 0
+        Divisible by 5!
+        dout = 1
+    end note
+
+    note right of rem_1
+        Remainder = 1
+        Not divisible
+    end note
+
+    note right of rem_2
+        Remainder = 2
+        Not divisible
+    end note
+
+    note right of rem_3
+        Remainder = 3
+        Not divisible
+    end note
+
+    note right of rem_4
+        Remainder = 4
+        Not divisible
+    end note
+```
+
+**Powers of 2 mod 5 cycle:** {1, 2, 4, 3, 1, 2, 4, 3, ...}
+
+- 2^0 mod 5 = 1
+- 2^1 mod 5 = 2
+- 2^2 mod 5 = 4
+- 2^3 mod 5 = 3
+- 2^4 mod 5 = 1 (cycle repeats)
+
 ---
 
 ## Source