docs: document mixed-bus scanning and new i2c helper APIs

Author: CameronBrooks11

docs/api-reference.md

@@ -850,6 +850,69 @@ int count = crumbs_controller_scan_for_crumbs(
     devices, 10, 10000);
 ```
 
+### Candidate-Address Scanner
+
+```c
+int crumbs_controller_scan_for_crumbs_candidates(
+    const crumbs_context_t *ctx,
+    const uint8_t *candidates,
+    size_t candidate_count,
+    int strict,
+    crumbs_i2c_write_fn write_fn,
+    crumbs_i2c_read_fn read_fn,
+    void *io_ctx,
+    uint8_t *found,
+    uint8_t *types,
+    size_t max_found,
+    uint32_t timeout_us);
+```
+
+Use this helper on mixed buses. It probes only the explicit addresses in `candidates` (deduplicated), avoiding full-range scans.
+
+---
+
+## Raw I2C Device Helpers
+
+```c
+typedef int (*crumbs_i2c_write_read_fn)(
+    void *user_ctx, uint8_t addr,
+    const uint8_t *tx, size_t tx_len,
+    uint8_t *rx, size_t rx_len,
+    uint32_t timeout_us,
+    int require_repeated_start);
+```
+
+`crumbs_i2c_write_read_fn` performs a combined write-then-read transaction. Return value is bytes read (`>=0`) or negative on error.
+
+Helper APIs bound to `crumbs_device_t`:
+
+```c
+int crumbs_i2c_dev_write(...);
+int crumbs_i2c_dev_read(...);
+int crumbs_i2c_dev_write_then_read(...);
+int crumbs_i2c_dev_read_reg_ex(...);
+int crumbs_i2c_dev_write_reg_ex(...);
+int crumbs_i2c_dev_read_reg_u8(...);
+int crumbs_i2c_dev_write_reg_u8(...);
+int crumbs_i2c_dev_read_reg_u16be(...);
+int crumbs_i2c_dev_write_reg_u16be(...);
+```
+
+Standard helper error codes:
+
+- `CRUMBS_I2C_DEV_E_INVALID` (`-1`)
+- `CRUMBS_I2C_DEV_E_WRITE` (`-2`)
+- `CRUMBS_I2C_DEV_E_READ` (`-3`)
+- `CRUMBS_I2C_DEV_E_SHORT_READ` (`-4`)
+- `CRUMBS_I2C_DEV_E_NO_REPEATED_START` (`-5`)
+- `CRUMBS_I2C_DEV_E_SIZE` (`-6`)
+
+`crumbs_i2c_dev_write_then_read` fallback behavior:
+
+- if `write_read_fn` is provided, it is used,
+- if it is NULL and `require_repeated_start == 0`, fallback is `dev->write_fn` + `dev->read_fn`,
+- if it is NULL and `require_repeated_start != 0`, returns `CRUMBS_I2C_DEV_E_NO_REPEATED_START`.
+
 ---
 
 ## Return Values and Error Codes

docs/architecture.md

@@ -8,7 +8,7 @@ CRUMBS is a lightweight I²C messaging protocol enabling controllers (e.g., sing
 
 **Key Principle**: CRUMBS is the transport layer. Module families define the application layer.
 
-**Key Constraint**: A single I²C bus uses one module family. The controller is compiled with that family's headers and only understands those type_ids and opcodes.
+**Key Constraint**: A single CRUMBS controller instance uses one module-family vocabulary (type_ids/opcodes). A physical I²C bus may also host non-CRUMBS peripherals, but CRUMBS discovery should then use constrained candidate-address scans rather than broad range probing.
 
 ### Design Goals
 
@@ -101,7 +101,7 @@ The same headers are used by peripheral firmware to implement handlers.
 - Self-documenting: Headers define the complete vocabulary
 - Version control: Headers can be versioned with the family
 
-**Trade-off:** Controllers cannot communicate with modules from different families (different vocabulary). One bus = one family.
+**Trade-off:** A controller cannot speak multiple CRUMBS vocabularies at once. This is a vocabulary constraint, not a hard prohibition on non-CRUMBS devices sharing the same physical bus.
 
 ### Physical Deployment
 
@@ -160,6 +160,8 @@ for (int i = 0; i < count; i++) {
 - **Strict mode** (`strict=1`): Read-only probes, safer for sensitive devices
 - **Non-strict mode** (`strict=0`): May send probe write to stimulate response
 
+On mixed buses (CRUMBS + non-CRUMBS), avoid broad address-range scans and prefer explicit candidate address lists.
+
 **Runtime device map example:**
 
 ```

docs/platform-setup.md

@@ -578,6 +578,17 @@ void setup() {
 void loop() {}
 ```
 
+If your physical bus also includes non-CRUMBS peripherals, avoid broad range scans and use an explicit candidate list:
+
+```c
+uint8_t candidates[] = {0x10, 0x12, 0x20};
+uint8_t found[8], types[8];
+int count = crumbs_controller_scan_for_crumbs_candidates(
+    &ctx, candidates, sizeof(candidates), 1,
+    crumbs_arduino_wire_write, crumbs_arduino_read, NULL,
+    found, types, 8, 10000);
+```
+
 ### I²C Bus Scanner (Linux)
 
 ```bash
@@ -598,6 +609,8 @@ sudo ./build/crumbs_simple_linux_controller scan
 sudo ./build/crumbs_simple_linux_controller scan strict
 ```
 
+For mixed buses, prefer candidate-address scanning in application code instead of broad `0x08..0x77` sweeps.
+
 ---
 
 ## Next Steps