Skip to content

docs: cumulative-rules narrative (Phase 2b.2) #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
raeq merged 2 commits into from
May 20, 2026
Merged

docs: cumulative-rules narrative (Phase 2b.2) #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
474fcdd
docs: cumulative-rules narrative (Phase 2b.2)
May 20, 2026
af8808d
review: fix rule→demo attributions; deep-link to README anchors; stre…
May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 27 additions & 21 deletions docs/learning-path.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,32 +16,38 @@ If you've never lit an LED with a battery, start with [the project's Hello World

## The demos in order

| # | Demo | What it teaches |
|----|-------------------------------|---------------------------------------------------------------------------------------|
| 1 | [`hello_led/`](../demos/hello_led/) | The minimal viable circuit — one LED, one resistor, two rails. Reading point.|
| 2 | [`penfold_light_switch/`](../demos/penfold_light_switch/)| First sensor circuit. LDR + comparator + transistor switch. Penfold BP107 P3.|
| 3 | [`water_alarm/`](../demos/water_alarm/) | Composing chips, wiring rails, latching logic. Four chips, two LEDs. |
| 4 | [`penfold_reaction_game/`](../demos/penfold_reaction_game/)| Sequential digital — counter ring + button-stops-clock topology. Penfold P22.|
| 5 | [`dice/`](../demos/dice/) | Classic 555 + 4017 + diode-OR matrix. Recognisable hobbyist staple. |
| 6 | [`digital_thermometer/`](../demos/digital_thermometer/) | First MCU project. ATmega328P + DHT11 + 7-seg display. Firmware-as-cell. |
| 7 | [`penfold_one_second_timer/`](../demos/penfold_one_second_timer/)| Op-amp relaxation oscillator with hysteresis. Penfold BP107 P8.|
| 8 | [`penfold_metronome/`](../demos/penfold_metronome/) | NE555 astable + speaker — the other classical astable. Penfold BP107 P9. |
| 9 | [`penfold_warbling_doorbuzzer/`](../demos/penfold_warbling_doorbuzzer/)| Oscillator composition — slow gates fast. Penfold BP107 P16. |
| 10 | [`doorbell_protector/`](../demos/doorbell_protector/) | Two-555 monostable with transistor switching and a relay. |
| 11 | [`fan_cooling/`](../demos/fan_cooling/) | First `Board` demo. TMP302 + MOSFET-switched fan. Connectors that mate. |
| 12 | [`backup_power/`](../demos/backup_power/) | TI Designs TIDA-03031. Three-stage power architecture (eFuse + boost + buck). |
| 13 | [`water_alarm_split/`](../demos/water_alarm_split/) | Same circuit as #3 but split across two boards via `mate()`. HAT pattern. |
| 14 | [`bldc_motor/`](../demos/bldc_motor/) | ATmega328P + DRV8313 + Hall sensors. Three-phase commutation. |
| 15 | [`isolated_rs232/`](../demos/isolated_rs232/) | TIDA-01230. Cross-domain isolation — first demo to exercise `GroundDomain`. |
| 16 | [`li_ion_fuel_gauge/`](../demos/li_ion_fuel_gauge/) | TIDA-00594. BQ27546-G1 fuel gauge with sense resistor + thermistor. |
| 17 | [`penfold_fuzz_unit/`](../demos/penfold_fuzz_unit/) | Audio domain — op-amp + clipping diodes. Guitar fuzz pedal. Penfold P30. |
| 18 | [`penfold_crystal_set/`](../demos/penfold_crystal_set/) | Passive-only RF — no Rail, no battery. Boundary case. Penfold BP107 P27. |
The *first catches* column names rules from [`the-rules.md`](the-rules.md) that this demo is the first place to surface — i.e. work the demos top-to-bottom and you'll see the framework refuse each rule in a real circuit by the time you reach the demo it's listed against.

| # | Demo | What it teaches | First catches |
|----|------------------------------------------------------------------------|------------------------------------------------------------------------------|-------------------------------|
| 1 | [`hello_led/`](../demos/hello_led/) | The minimal viable circuit — one LED, one resistor, two rails. Reading point.| [Rules 1, 2](the-rules.md) |
| 2 | [`penfold_light_switch/`](../demos/penfold_light_switch/) | First sensor circuit. LDR + comparator + transistor switch. Penfold BP107 P3.| [Rules 3, 4](the-rules.md) |
| 3 | [`water_alarm/`](../demos/water_alarm/) | Composing chips, wiring rails, latching logic. Four chips, two LEDs. | [Rule 9](the-rules.md) |
| 4 | [`penfold_reaction_game/`](../demos/penfold_reaction_game/) | Sequential digital — counter ring + button-stops-clock topology. Penfold P22.| — |
| 5 | [`dice/`](../demos/dice/) | Classic 555 + 4017 + diode-OR matrix. Recognisable hobbyist staple. | — |
| 6 | [`digital_thermometer/`](../demos/digital_thermometer/) | First MCU project. ATmega328P + DHT11 + 7-seg display. Firmware-as-cell. | — |
| 7 | [`penfold_one_second_timer/`](../demos/penfold_one_second_timer/) | Op-amp relaxation oscillator with hysteresis. Penfold BP107 P8. | — |
| 8 | [`penfold_metronome/`](../demos/penfold_metronome/) | NE555 astable + speaker — the other classical astable. Penfold BP107 P9. | — |
| 9 | [`penfold_warbling_doorbuzzer/`](../demos/penfold_warbling_doorbuzzer/)| Oscillator composition — slow gates fast. Penfold BP107 P16. | — |
| 10 | [`doorbell_protector/`](../demos/doorbell_protector/) | Two-555 monostable with transistor switching and a relay. | — |
| 11 | [`fan_cooling/`](../demos/fan_cooling/) | First `Board` demo. TMP302 + MOSFET-switched fan. Connectors that mate. | [Rule 7](the-rules.md) |
| 12 | [`backup_power/`](../demos/backup_power/) | TI Designs TIDA-03031. Three-stage power architecture (eFuse + boost + buck).| — |
| 13 | [`water_alarm_split/`](../demos/water_alarm_split/) | Same circuit as #3 but split across two boards via `mate()`. HAT pattern. | [Rule 6](the-rules.md) |
| 14 | [`bldc_motor/`](../demos/bldc_motor/) | ATmega328P + DRV8313 + Hall sensors. Three-phase commutation. | — |
| 15 | [`isolated_rs232/`](../demos/isolated_rs232/) | TIDA-01230. Cross-domain isolation — first demo to exercise `GroundDomain`. | [Rule 5](the-rules.md) |
| 16 | [`li_ion_fuel_gauge/`](../demos/li_ion_fuel_gauge/) | TIDA-00594. BQ27546-G1 fuel gauge with sense resistor + thermistor. | — |
| 17 | [`penfold_fuzz_unit/`](../demos/penfold_fuzz_unit/) | Audio domain — op-amp + clipping diodes. Guitar fuzz pedal. Penfold P30. | — |
| 18 | [`penfold_crystal_set/`](../demos/penfold_crystal_set/) | Passive-only RF — no Rail, no battery. Boundary case. Penfold BP107 P27. | — |

Rules 8, 10, 11, and 12 are framework-internal refusals — they fire during refactors and new-design construction rather than in any specific demo's near-miss snippet. The full table of all twelve rules is on [`the-rules.md`](the-rules.md).

Cross-referencing the other way: [`the-rules.md`](the-rules.md) lists, for each rule, the demo where you'll first see it caught — so you can read either page first and find your way back to the other.

## What each demo gives you

Every demo folder has the same shape:

```
```text
demos/<name>/
<name>.py # the source — read this first
docs/
Expand Down
Loading