# Specification: Full Review — Documentation Repair

**Track ID:** review-docs_20260318
**Type:** Chore
**Created:** 2026-03-18
**Status:** Draft

## Summary

Fix all documentation correctness issues identified in the comprehensive code review: non-existent API references, wrong Python version requirements, stale architecture descriptions, incorrect color constant names, and misleading docstrings in the source code.

## Context

The documentation review found 4 High and 5 Medium severity issues where the published documentation either references APIs that don't exist, shows wrong Python version requirements (3.11+ when minimum is 3.10), or describes architectural patterns that no longer match the implementation. These issues mislead users who follow the documentation examples. Some acceptance criteria below address multiple issues from a single fix location, and some issues require fixes across multiple files, resulting in more criteria than issue count.

## Acceptance Criteria

- [ ] All code examples in `docs/` use only real, existing API methods
- [ ] Python version requirement shows 3.10+ throughout all docs, README, and badges
- [ ] `Colors.WARM_WHITE` / `Colors.COOL_WHITE` references replaced with `Colors.WARM` / `Colors.COOL`
- [ ] `breathe(cycles=0)` example corrected (0 is not valid; document correct infinite-loop pattern)
- [ ] Architecture overview updated to show all 8 layers (currently shows 4)
- [ ] Architecture overview updated to reflect background-receiver concurrency model (not `_request_lock`)
- [ ] Wrong URLs (`lifx.readthedocs.io`) corrected to `https://djelibeybi.github.io/lifx-async/`
- [ ] `Device.connect()` docstring clarifies state initialization requires `async with`
- [ ] `discover_mdns()` docstring updated to reflect it yields all Device types
- [ ] Test count in docs updated (currently says "700+" — actual is 2425+)
- [ ] `cd lifx` clone instructions corrected to `cd lifx-async`
- [ ] `docs/` link checker passes with no broken links

## Dependencies

- review-critical_20260318 — `discover_mdns()` return type fix (code change) should land first so docstring matches

## Out of Scope

- Adding new documentation sections or tutorials
- Improving the README beyond correctness fixes
- Architecture Decision Records (ADRs)
- API reference auto-generation improvements

## Technical Notes

### Non-existent APIs to fix (D-H4)

The following appear in docs but do not exist in the codebase:
- `find_lights()` → correct API is `find_by_label()`
- `discover()` used as async context manager → it is an async generator, use `async for`
- `conn.request_response()` → correct is `connection.request()` or `request_stream()`
- Wrong import paths in exceptions docs (packets imported from wrong module)
- `light.connect()` as instance method → correct is `await Light.from_ip()` or `Device.connect()`
- `light.disconnect()` → use `async with device:` context manager

### Architecture doc update (D-M3, D-M4)

`docs/architecture/overview.md` describes a 4-layer architecture and references `_request_lock` for request serialization. The actual design has 8 layers and uses a background receiver task with per-request `asyncio.Queue` instances keyed by `(source, sequence, serial)`. Update the concurrency model description and add the Animation, Effects, and Theme layers.

---

_Generated by Conductor. Review and edit as needed._
