examples: add 5 starter recipes covering the full protocol surface

Before this commit, the only canonical reference for "how do I use DCP"
was the lamp example. A new user wanting to build a thermometer, a
relay switch, or a motor control had to reverse-engineer the pattern.
This commit adds five compile-clean device skeletons — each chosen to
teach a distinct slice of the protocol — plus an index page in
docs/RECIPES.md.

Coverage:

  relay_switch        bool param + idempotent + capability scope +
                      non-idempotent pulse intent
  sensor_dht22        read intent with units + unsolicited event push
                      on threshold + device-tracked mutable config
  stepper_motor       int + duration params + dry_run as motion preview
                      (LLM can ask "where would this move end?" without
                      spinning the shaft) + non-idempotent move
  encoder_input       the "event-only device" pattern — zero intents,
                      pure event source. Bindings array is literally
                      empty; firmware only ever calls send_event()
  door_lock           capability + dry_run as REAL safety story —
                      capability is `lock.admin` (not lock.write) so
                      the name signals seriousness, and admin requires
                      an explicitly-minted scoped token at runtime.
                      String-typed return values + state-change events
                      on any cause (including manual override).

Each recipe is a pair: examples/<name>_manifest.yaml + a corresponding
firmware/esp32/examples/<name>/<name>.ino sketch. All five compile
clean on both the ESP32 baseline (~289 KB / 22.5 KB) and ESP8266
NodeMCU (~239 KB IROM). Per-recipe variation against the protocol
baseline is under 1 KB — adding a recipe doesn't grow the DCP layer.

Hardware drivers in sensor_dht22 and door_lock are stubbed (mock
read functions, gpio-only actuator) so the skeletons compile without
any third-party library install. Each .ino has a clearly marked
"replace this with your driver" comment.

docs/RECIPES.md is the new index — table of recipes, per-recipe
explanation of what concept it teaches, and a "build your own"
pointer to ADDING_FEATURES.md. README TOC updated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: WaylandYang

README.md

@@ -23,6 +23,7 @@
 - [Architecture](#architecture)
 - [Quickstart](#quickstart)
 - [Add a feature in 5 steps](docs/ADDING_FEATURES.md)
+- [Recipes — five ready-to-flash device skeletons](docs/RECIPES.md)
 - [Wire format](#wire-format) · full [SPEC.md](SPEC.md)
 - [Manifest](#manifest)
 - [Roadmap](#roadmap)

docs/RECIPES.md

@@ -0,0 +1,170 @@
+# DCP recipes
+
+Ready-to-flash skeletons for the five protocol shapes you'll most
+commonly want. Each one teaches a different slice of DCP and runs on
+an ESP32-class MCU. Hardware is cheap enough that you can buy the
+whole bench for ~¥40.
+
+| Recipe | What you'll learn | Approx. hardware cost |
+|---|---|---|
+| [`relay_switch`](#relay_switch) | bool param · idempotent · capability · non-idempotent pulse | ¥5 (5V relay module) |
+| [`sensor_dht22`](#sensor_dht22) | typed read intent with units · unsolicited event push · device-tracked config | ¥10 (DHT22) |
+| [`stepper_motor`](#stepper_motor) | int + duration params · `dry_run` as preview · non-idempotent move | ¥10 (28BYJ-48 + ULN2003) |
+| [`encoder_input`](#encoder_input) | **event-only device** — zero intents | ¥3 (KY-040) |
+| [`door_lock`](#door_lock) | capability + `dry_run` as **real safety story** · string return types · state-change events | ¥10 (SG90 servo) |
+
+Each recipe is a pair: a manifest (`examples/<name>_manifest.yaml`)
+and a firmware sketch (`firmware/esp32/examples/<name>/<name>.ino`).
+All five cross-compile clean on the full
+[ESP family build matrix](../README.md#cross-compile-clean-across-the-esp-family-xtensa--risc-v--esp8266).
+
+## Quick start (any recipe)
+
+```bash
+# 1. Wire your hardware per the comments at the top of the .ino
+# 2. Flash:
+arduino-cli compile --upload -p COM5 --fqbn esp32:esp32:esp32 \
+    --library firmware/esp32 firmware/esp32/examples/relay
+# 3. Run the bridge:
+dcp serve examples/relay_manifest.yaml --serial COM5
+# 4. Point your MCP client (Claude Desktop / Ollama / etc.) at dcp.
+```
+
+---
+
+## relay_switch
+
+A single-channel 5V relay (door buzzer, appliance switch, fan).
+
+- 3 intents: `set_relay(state)`, `read_relay()`, `pulse(duration)`
+- The `set_relay` intent is **idempotent** — setting "on" twice still
+  leaves it on. `pulse` is **non-idempotent** (two calls = two pulses)
+  and the manifest declares that explicitly.
+- Both `set_relay` and `pulse` are gated on `relay.write`; `read_relay`
+  only needs `relay.read`. A read-only session token cannot switch the
+  appliance.
+
+**Files**: [`examples/relay_manifest.yaml`](../examples/relay_manifest.yaml) ·
+[`firmware/esp32/examples/relay/relay.ino`](../firmware/esp32/examples/relay/relay.ino)
+
+---
+
+## sensor_dht22
+
+A DHT22 temperature + humidity sensor that PUSHES events when
+temperature crosses a configurable threshold — no polling needed
+from the LLM.
+
+- 2 read intents (`read_temperature`, `read_humidity`) with explicit
+  `unit: celsius` / `unit: percent` declared in the manifest, so the
+  LLM tool schema surfaces them and stops asking "Fahrenheit?"
+- 1 write intent (`set_alert_threshold`) that mutates device state
+  used by the event loop
+- 1 event (`threshold_exceeded`) emitted on rising edge of "above
+  threshold," with payload `{temperature, threshold}`
+
+The DHT22 driver call is stubbed (`read_dht_*()` returns mock data) so
+the example runs headlessly during compile-test. Drop in your
+favourite library (e.g. Adafruit DHT) at those two function bodies.
+
+**Files**: [`examples/sensor_dht22_manifest.yaml`](../examples/sensor_dht22_manifest.yaml) ·
+[`firmware/esp32/examples/sensor_dht22/sensor_dht22.ino`](../firmware/esp32/examples/sensor_dht22/sensor_dht22.ino)
+
+---
+
+## stepper_motor
+
+A 28BYJ-48 stepper driven by a ULN2003 board — curtain, valve, dial,
+small actuator, etc.
+
+- 3 intents: `step(direction, count, speed_rpm)`, `read_position()`,
+  `home()`
+- This is where **dry_run gets genuinely useful**: an LLM can ask
+  "what step position would this move end at?" and get
+  `{would_move_to: 2700, from: 1234}` without spinning the shaft.
+  Saves wear, time, and lets the LLM reason about reachability.
+- `step` and `home` are **non-idempotent** (each call advances state).
+  The manifest declares that explicitly so the LLM knows not to retry.
+- Half-step coil sequence implemented inline; coils released after
+  every move to avoid overheating.
+
+**Files**: [`examples/stepper_manifest.yaml`](../examples/stepper_manifest.yaml) ·
+[`firmware/esp32/examples/stepper/stepper.ino`](../firmware/esp32/examples/stepper/stepper.ino)
+
+---
+
+## encoder_input
+
+A KY-040 rotary encoder with integrated push button.
+
+This is the canonical **"the device has no intents"** pattern. The
+LLM does not command the encoder; it gets notified when the user
+turns or clicks. The `intents:` list in the manifest is literally
+empty, the bindings array in the firmware is literally empty, and the
+firmware only ever calls `send_event()`.
+
+Useful for: volume knobs, menu wheels, RPM counters, manual override
+inputs — anything where the LLM should react to user input but never
+drive that input itself.
+
+- 3 events: `encoder_turned(delta, position)`, `button_pressed`,
+  `button_long_press(held_ms)`
+- Polled in `loop()` with 5 ms debounce on CLK and 20 ms on the
+  button; long-press fires after 1 s of continuous press.
+
+**Files**: [`examples/encoder_manifest.yaml`](../examples/encoder_manifest.yaml) ·
+[`firmware/esp32/examples/encoder/encoder.ino`](../firmware/esp32/examples/encoder/encoder.ino)
+
+---
+
+## door_lock
+
+The capability + dry_run safety story made concrete: a servo (or
+solenoid) actuated door lock.
+
+- The capability name is **`lock.admin`**, not `lock.write` — the
+  manifest itself signals "this is dangerous." A reviewer reading the
+  manifest immediately sees that this intent is in a separate trust
+  tier from "read the temperature."
+- `dry_run` is the safety primitive in action: an LLM can be
+  ALLOWED to call `unlock` with `__dry_run__=true` (cheap,
+  reversible — returns "would transition locked → unlocked") but the
+  REAL unlock requires the `lock.admin` capability, which the
+  operator typically mints out of band with a short TTL:
+
+  ```bash
+  dcp token mint --caps lock.read,lock.admin --ttl 300
+  ```
+
+- The Bridge in the recommended `dcp serve --grant lock.read`
+  configuration grants **only read** by default. Admin must be
+  presented as a signed token per call.
+- A `state_changed(from, to)` event fires on any transition,
+  regardless of cause — so manual key turns are observable too.
+
+**Files**: [`examples/door_lock_manifest.yaml`](../examples/door_lock_manifest.yaml) ·
+[`firmware/esp32/examples/door_lock/door_lock.ino`](../firmware/esp32/examples/door_lock/door_lock.ino)
+
+---
+
+## Adding your own recipe
+
+The protocol is the same regardless of device. Use one of the above
+as your starting template, change the manifest to declare your
+intents and events, and replace the firmware handlers with your
+hardware-specific code. The full add-a-feature walkthrough is in
+[`ADDING_FEATURES.md`](ADDING_FEATURES.md).
+
+If you build a recipe for a piece of hardware that isn't covered
+here (BME280, NeoPixel strip, ultrasonic sensor, GPS module,
+PCA9685, ADS1115…), please open a PR — the cookbook grows by
+contribution.
+
+## Footprint stays flat
+
+Adding a recipe doesn't grow the DCP layer. All five recipes above
+land at the same ~290 KB / ~22.5 KB on ESP32-WROOM-32 — the
+variation is in the example sketch's own logic, not in any per-recipe
+protocol cost. The intent table is `switch(intent_id) → handler`, and
+each intent adds one row and one function. There is no plugin loader,
+no runtime registration, no per-handler dispatcher overhead.

examples/door_lock_manifest.yaml

@@ -0,0 +1,54 @@
+dcp: 0.3
+device:
+  id:     door-lock-frontdoor-01
+  model:  servo_actuated_lock
+  vendor: example.dev
+
+# Recipe: a smart door lock — the "capability + dry_run as real safety" demo.
+# Teaches:
+#   - capability scoping that GENUINELY MATTERS (the LLM should not be
+#     able to unlock your door just because it can also read the
+#     temperature). We use `lock.admin`, NOT `lock.write`, so the
+#     capability name itself signals "this is dangerous."
+#   - dry_run as a safety mechanism for irreversible actions: the LLM
+#     can preview "if I issue this unlock, the device state would go
+#     from locked -> unlocked" without actually unlatching.
+#   - non-idempotent admin actions explicitly declared
+#   - state-change events so anyone watching can see who/when
+#
+# Hardware (when wiring a real lock):
+#   - Hobby servo (SG90) on GPIO 13, signal only (servo VCC -> external 5V!)
+#   - For solenoid locks: replace the servo helper with relay control
+#
+# Pair with:
+#   dcp serve examples/door_lock_manifest.yaml --serial COM3 \
+#       --grant lock.read   # default: only read access
+#
+# Then mint a scoped admin token explicitly when you (the LLM operator)
+# want to allow unlock for a specific session:
+#   dcp token mint --caps lock.read,lock.admin --ttl 300
+
+intents:
+  - name: unlock
+    capability: lock.admin       # NOT lock.write — name signals danger
+    idempotent: false            # one physical unlock per call
+    dry_run:    true             # LLM can preview without unlatching
+
+  - name: lock
+    capability: lock.admin
+    idempotent: true             # locking already-locked door is a no-op
+    dry_run:    true
+
+  - name: read_state
+    # "locked" or "unlocked"
+    returns: { type: string }
+    capability: lock.read
+
+events:
+  - name: state_changed
+    # Emitted whenever the lock physically changes state, regardless of
+    # whether the change came from an intent call or a manual override.
+    payload:
+      from: { type: string }     # "locked" / "unlocked"
+      to:   { type: string }
+    capability: lock.read

examples/encoder_manifest.yaml

@@ -0,0 +1,40 @@
+dcp: 0.3
+device:
+  id:     encoder-volume-01
+  model:  ky040_rotary_encoder
+  vendor: example.dev
+
+# Recipe: a KY-040 rotary encoder with integrated push-button.
+# Teaches:
+#   - the "event-only device" pattern — the device has NO intents
+#     callable from the LLM side. It is a pure event source.
+#     The LLM gets notifications about turns and clicks; it does not
+#     command the encoder to do anything.
+#   - structured event payloads with multiple fields + units
+#
+# Hardware: KY-040 module — CLK + DT to two GPIOs with pullups,
+# SW (button) to a third GPIO with pullup.
+# Pair with:
+#   dcp serve examples/encoder_manifest.yaml --serial COM3
+
+# Empty intents list — this device only PUSHES, never RECEIVES.
+intents: []
+
+events:
+  - name: encoder_turned
+    payload:
+      # +1 = clockwise one detent, -1 = counterclockwise.
+      delta:    { type: int, range: [-10, 10] }
+      # Absolute position since power-on. Wraps at int32 limits.
+      position: { type: int }
+    capability: input.read
+
+  - name: button_pressed
+    # Fires once on press down (not on hold or release).
+    capability: input.read
+
+  - name: button_long_press
+    # Fires once when held > 1 second.
+    payload:
+      held_ms: { type: duration, unit: ms }
+    capability: input.read

examples/relay_manifest.yaml

@@ -0,0 +1,34 @@
+dcp: 0.3
+device:
+  id:     relay-garage-01
+  model:  generic_5v_relay
+  vendor: example.dev
+
+# Recipe: a single-channel 5V relay (door buzzer / appliance switch / fan).
+# Teaches:
+#   - boolean parameter
+#   - idempotent intents (setting "on" twice still leaves it on)
+#   - capability scopes that genuinely matter
+#     (relay.read can monitor; only relay.write can switch)
+#   - a non-idempotent pulse intent that MUST declare itself
+
+intents:
+  - name: set_relay
+    params:
+      state: { type: bool }
+    capability: relay.write
+    idempotent: true
+    dry_run:    true
+
+  - name: read_relay
+    returns: { type: bool }
+    capability: relay.read
+
+  - name: pulse
+    # Energise the relay for `duration` ms, then de-energise.
+    # Useful for door buzzers, magnetic locks, momentary signals.
+    params:
+      duration: { type: duration, unit: ms, range: [50, 5000], default: 200 }
+    capability: relay.write
+    idempotent: false      # calling twice = two pulses, not one
+    dry_run:    true

examples/sensor_dht22_manifest.yaml

@@ -0,0 +1,43 @@
+dcp: 0.3
+device:
+  id:     sensor-living-room-01
+  model:  dht22_temp_humidity
+  vendor: example.dev
+
+# Recipe: a DHT22 temperature + humidity sensor.
+# Teaches:
+#   - read intents that return typed scalar values with explicit units
+#     (`celsius`, `percent`) — the LLM sees these in the tool schema
+#     and stops asking "Fahrenheit?"
+#   - an unsolicited event stream — the device pushes notifications
+#     when temperature crosses a configured threshold, no polling
+#   - a "configure" intent that mutates device state used by events
+#
+# Hardware: DHT22 (AM2302), data pin to DHT_PIN below, 4.7 KOhm pullup
+# to VCC. Pair with:
+#   dcp serve examples/sensor_dht22_manifest.yaml --serial COM3
+
+intents:
+  - name: read_temperature
+    returns: { type: float, unit: celsius }
+    capability: env.read
+
+  - name: read_humidity
+    returns: { type: float, unit: percent, range: [0, 100] }
+    capability: env.read
+
+  - name: set_alert_threshold
+    # Reconfigure the temperature above which the device emits a
+    # threshold_exceeded event. Persists until next reboot.
+    params:
+      temperature: { type: float, unit: celsius, range: [-40, 80], default: 30.0 }
+    capability: env.write
+    idempotent: true
+    dry_run:    true
+
+events:
+  - name: threshold_exceeded
+    payload:
+      temperature: { type: float, unit: celsius }
+      threshold:   { type: float, unit: celsius }
+    capability: env.read

examples/stepper_manifest.yaml

@@ -0,0 +1,42 @@
+dcp: 0.3
+device:
+  id:     stepper-curtain-01
+  model:  28byj48_uln2003
+  vendor: example.dev
+
+# Recipe: a 28BYJ-48 stepper motor driven by a ULN2003 board.
+# Teaches:
+#   - non-idempotent intents (every step() call advances state)
+#   - dry_run as ACTUALLY VALUABLE — the LLM can preview the new motor
+#     position before committing the move ("would_move_to: step 2700")
+#   - integer + duration param mix
+#   - device-tracked state (position) exposed via a read intent
+#
+# Hardware: 28BYJ-48 stepper, ULN2003 driver board, IN1..IN4 -> 4 GPIOs.
+# 4096 native steps per revolution (with internal 64:1 gearbox).
+# Pair with:
+#   dcp serve examples/stepper_manifest.yaml --serial COM3
+
+intents:
+  - name: step
+    # Move the motor by `count` steps in the given `direction`.
+    # +1 = forward, -1 = reverse. The Bridge enforces both ranges.
+    params:
+      direction: { type: int, range: [-1, 1] }
+      count:     { type: int, range: [1, 4096], default: 512 }
+      speed_rpm: { type: int, range: [1, 15],   default: 8 }
+    capability: motor.write
+    idempotent: false           # cumulative — calling twice doubles the move
+    dry_run:    true
+
+  - name: read_position
+    # Current absolute step count (signed, can be negative after reverse).
+    returns: { type: int }
+    capability: motor.read
+
+  - name: home
+    # Move back to position 0. Non-idempotent because if you call it
+    # twice quickly the motor might already be moving from the first call.
+    capability: motor.write
+    idempotent: false
+    dry_run:    true