---
phase: 05-reliability-documentation
plan: 03
type: execute
wave: 1
depends_on: []
files_modified:
  - docs/user-guide/advanced-usage.md
  - docs/architecture/overview.md
  - CLAUDE.md
autonomous: true
requirements: [DOCS-02]
must_haves:
  truths:
    - "advanced-usage.md no longer recommends a two-pass quick/thorough discovery pattern — a single discover_devices() call re-broadcasts internally (DISC-01)"
    - "advanced-usage.md's fire-and-forget section directs sustained streaming to the Animation Guide (which paces via acks without per-call latency) and scopes fast=True to occasional low-latency one-shots"
    - "advanced-usage.md's error-handling guidance is contextualised: the library already retransmits within each request's timeout; app-level wrappers are for whole-operation failures"
    - "architecture/overview.md Layer 5 describes ack-gated pacing as internal behaviour, lists animation/flow.py in Key Files, and uses ~20 FPS framing"
    - "CLAUDE.md's Animation Layer bullet and discovery overall-timeout default match the shipped code (~20 FPS framing; 15.0 s default)"
    - "Findings F1 (docs/api/animation.md stale hand-written FPS prose — outside the D5-10 audit scope) and F3 (no wrong docstrings found) are recorded in the SUMMARY as findings, not fixed"
  artifacts:
    - path: "docs/user-guide/advanced-usage.md"
      provides: "Stale-content fixes: audit #9, #10, #11"
      contains: "fast=True"
    - path: "docs/architecture/overview.md"
      provides: "Stale-content fixes: audit #12, #13"
      contains: "animation/flow.py"
    - path: "CLAUDE.md"
      provides: "Repo-hygiene fix for finding F2 (stale FPS + discovery-default claims)"
      contains: "15.0"
  key_links:
    - from: "docs/user-guide/advanced-usage.md"
      to: "docs/user-guide/animation.md"
      via: "page-level relative link directing sustained streaming to the Animation Guide (page exists; its streaming anchor is created in parallel by plan 05-02, so link to the page, not an anchor)"
      pattern: "\\(animation\\.md\\)"
  prohibitions:
    - statement: "MUST NOT delete legitimate whole-operation retry guidance — contextualise it (the library already retransmits within each request); removal loses valid advice"
      category: values
      requirement_id: DOCS-02
    - statement: "MUST NOT edit docs/api/*.md, docs/changelog.md, or source docstrings — outside the locked audit scope (D5-10/D5-11); surface issues as findings instead"
      category: values
      requirement_id: DOCS-02
---

<objective>
Complete the D5-10 stale-content audit fixes outside the two DOCS host pages:
advanced-usage.md (audit #9–#11), architecture/overview.md (audit #12–#13), plus the
finding-F2 repo-hygiene fix in CLAUDE.md (its Animation Layer and discovery-timeout
claims contradict the shipped code; fixed here under the project's standing
"if you see it, fix it" rule — CLAUDE.md is repo instructions, not a docs-site page,
so no D5 locked decision constrains it). Findings F1 and F3 are surfaced, not fixed
(D5-11: prose-audit scope excludes docs/api/*.md and source docstrings).

Runs in Wave 1, parallel with plan 05-01 — zero file overlap; the one outbound link
this plan adds is page-level (animation.md), so it does not depend on any anchor
created by plans 05-01/05-02.

Purpose: no published page (or repo instruction file) contradicts the v1.1 wire
behaviour the other two plans document — old workarounds (two-pass discovery,
fast=True streaming loops) and inflated FPS claims are gone.

Output: updated docs/user-guide/advanced-usage.md, docs/architecture/overview.md,
CLAUDE.md; docs build stays clean.

Decisions implemented: D5-10, D5-11 (surface-don't-edit boundary).
</objective>

<execution_context>
@$HOME/.claude/gsd-core/workflows/execute-plan.md
@$HOME/.claude/gsd-core/templates/summary.md
</execution_context>

<context>
@.planning/phases/05-reliability-documentation/05-CONTEXT.md
@.planning/phases/05-reliability-documentation/05-RESEARCH.md
@.planning/phases/05-reliability-documentation/05-PATTERNS.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Fix advanced-usage.md's superseded workaround patterns (audit #9–#11)</name>
  <files>docs/user-guide/advanced-usage.md</files>
  <read_first>
    - docs/user-guide/advanced-usage.md (current state; the two-pass discovery section at lines 280–303; "Robust Error Handling" at lines 321–348; the fire-and-forget section at lines 553–594)
    - .planning/phases/05-reliability-documentation/05-RESEARCH.md (§Stale-Content Audit Findings items #9–#11; §State of the Art table — what changed v1.0 → v1.1)
  </read_first>
  <action>
    Three in-place fixes (D5-10 — fix contradictions in place; no new pages/sections):

    1. Audit #9 — the two-pass quick/thorough discovery section (### heading at line
       280, content through line 303, under `## Concurrency Patterns`): remove the
       section entirely — DISC-01 made the pattern obsolete (a single
       `discover_devices()` call re-broadcasts on an escalating schedule within the
       discovery window). Fold one sentence into the preceding "Multi-Device
       Control" section (or leave a single short paragraph in its place) stating
       that discovery already re-broadcasts internally and that a longer `timeout`
       is the lever for slow networks. The section heading is not listed in the
       page's top TOC (which lists `##` entries only), so no TOC edit is needed.

    2. Audit #10 — the fire-and-forget section (### heading at line 553, content
       through line 594, under `## Performance Optimization`): rework, don't delete.
       Retitle the heading to `### Fire-and-Forget Mode for Low-Latency One-Shots`.
       Replace the framing sentence at line 555 (which claims waiting for
       acknowledgement creates unacceptable latency for high-rate updates): since
       v1.1, sustained streaming belongs to the Animation layer, which paces
       delivery against device acks internally without per-call latency — link
       page-level to the Animation Guide with `(animation.md)` (do NOT link to a
       heading anchor inside it; its streaming section is being created in parallel
       by plan 05-02). Keep `fast=True` documented as valid for occasional
       low-latency one-shot updates where no confirmation is needed. Fix the loop
       example: the thirty-FPS loop comments at lines 565 and 579 and the
       33-millisecond sleep at line 579 — slow the example to 20 FPS
       (`asyncio.sleep(0.05)`) and reword its comments to match, or simplify the
       example to a one-shot (discretionary), as long as no thirty-FPS framing
       remains.

    3. Audit #11 — "Robust Error Handling" (lines 321–348): contextualise, don't
       delete (same treatment as troubleshooting's Connection Drops in plan 05-01).
       Add one or two sentences noting the library already retransmits within each
       request's timeout (v1.1 retry reshape), so the wrapper shown is for
       whole-operation failures, not per-packet reliability. Keep the example code.

    Australian English. No other sections change.
  </action>
  <verify>
    <automated>! grep -q 'Batched Discovery' docs/user-guide/advanced-usage.md && ! grep -q '0.033' docs/user-guide/advanced-usage.md && ! grep -qE '~?30 FPS' docs/user-guide/advanced-usage.md && grep -q 'Low-Latency One-Shots' docs/user-guide/advanced-usage.md && grep -qE '\(animation\.md\)' docs/user-guide/advanced-usage.md && uv run zensical build</automated>
  </verify>
  <acceptance_criteria>
    - `grep -c 'Batched Discovery' docs/user-guide/advanced-usage.md` outputs 0 (two-pass pattern gone) and the page mentions discovery re-broadcasting internally (grep -qi 're-broadcast' succeeds)
    - `grep -c '0.033' docs/user-guide/advanced-usage.md` outputs 0 and `grep -cE '~?30 FPS' docs/user-guide/advanced-usage.md` outputs 0
    - `grep -q '### Fire-and-Forget Mode for Low-Latency One-Shots' docs/user-guide/advanced-usage.md` succeeds and `grep -q 'fast=True' docs/user-guide/advanced-usage.md` still succeeds (capability kept, scope narrowed)
    - `grep -qE '\(animation\.md\)' docs/user-guide/advanced-usage.md` succeeds (page-level link, no anchor fragment: `grep -c 'animation.md#' docs/user-guide/advanced-usage.md` outputs 0)
    - The Robust Error Handling section still contains its try/except example AND a sentence noting the library retransmits within each request's timeout
    - `uv run zensical build` exits 0; `uv run zensical build 2>&1 | grep -i warning | grep -c 'advanced-usage'` outputs 0
  </acceptance_criteria>
  <done>Audit #9–#11 fixed: no two-pass discovery, fire-and-forget scoped to one-shots with sustained streaming pointed at the Animation Guide, retry wrapper contextualised; build clean.</done>
</task>

<task type="auto">
  <name>Task 2: Fix architecture/overview.md Layer 5 (audit #12–#13) + CLAUDE.md hygiene (finding F2); record findings F1/F3</name>
  <files>docs/architecture/overview.md, CLAUDE.md</files>
  <read_first>
    - docs/architecture/overview.md (Layer 5 block at lines 184–197: Purpose line 186, feature bullets 188–191, Key Files 193–197)
    - CLAUDE.md (Animation Layer bullet at line 160; Discovery DoS Protection overall-timeout line at line 255)
    - src/lifx/const.py line 28 (DISCOVERY_TIMEOUT = 15.0)
    - .planning/phases/05-reliability-documentation/05-RESEARCH.md (§Stale-Content Audit items #12–#13 and "Findings to surface, not fix" F1/F2/F3)
  </read_first>
  <action>
    1. Audit #12 — docs/architecture/overview.md line 186: the Layer 5 Purpose
       parenthetical claims thirty-plus FPS. Reword to the ~20 FPS platform ceiling
       framing (e.g. "High-frequency frame delivery for real-time effects (up to
       ~20 FPS over WiFi)").

    2. Audit #13 — same Layer 5 block: the "Direct UDP: Bypasses request/response"
       bullet is true but incomplete. Add one bullet describing ack-gated pacing as
       internal behaviour (frame delivery paced against device acknowledgements,
       latest-frame-wins — no consumer configuration). Behavioural wording only; no
       tuning constants (D5-09 applies here too). Add
       `animation/flow.py - Ack-gated flow control` to the Key Files list.

    3. Finding F2 (repo hygiene, standing "if you see it, fix it" rule — CLAUDE.md is
       not a docs-site page and no locked decision constrains it):
       - CLAUDE.md line 160: the Animation Layer bullet's parenthetical FPS figure is
         inflated; reword to "(up to ~20 FPS)" keeping the rest of the bullet.
       - CLAUDE.md line 255: the Discovery DoS Protection bullet states the overall
         discovery timeout default as five seconds; correct it to 15.0
         (`DISCOVERY_TIMEOUT`, src/lifx/const.py:28).

    4. Findings to surface, NOT fix (record verbatim in this plan's SUMMARY under a
       "Findings" heading for the operator):
       - F1: docs/api/animation.md line 5 (hand-written prose intro, not
         docstring-fed) still carries a thirty-plus-FPS claim — outside the D5-10
         audit scope (api/ pages); one-line fix if the operator opts in.
       - F3: no flatly wrong docstrings were found in the animation layer (the
         Animator/AnimatorStats docstrings were updated in Phase 4) — nothing to
         escalate under D5-11.

    Australian English. Do not touch docs/api/*.md, docs/changelog.md, or any source
    file.
  </action>
  <verify>
    <automated>! grep -q '30+ FPS' docs/architecture/overview.md && grep -q 'animation/flow.py' docs/architecture/overview.md && ! grep -qF '(30+ FPS)' CLAUDE.md && ! grep -q 'default: 5.0' CLAUDE.md && grep -q 'default: 15.0' CLAUDE.md && uv run zensical build</automated>
  </verify>
  <acceptance_criteria>
    - `grep -c '30+ FPS' docs/architecture/overview.md` outputs 0 and `grep -q '~20 FPS' docs/architecture/overview.md` succeeds
    - Layer 5 block contains an ack-gated pacing bullet mentioning latest-frame-wins, with no tuning constants (`grep -c 'expiry' docs/architecture/overview.md` outputs 0)
    - `grep -q 'animation/flow.py' docs/architecture/overview.md` succeeds (Key Files updated)
    - `grep -cF '(30+ FPS)' CLAUDE.md` outputs 0 and `grep -q '~20 FPS' CLAUDE.md` succeeds
    - `grep -c 'default: 5.0' CLAUDE.md` outputs 0 and `grep -q 'default: 15.0' CLAUDE.md` succeeds
    - `git diff --name-only` lists no path under docs/api/ and not docs/changelog.md and no file under src/
    - `uv run zensical build` exits 0; `uv run zensical build 2>&1 | grep -i warning | grep -c 'overview'` outputs 0
  </acceptance_criteria>
  <done>Overview Layer 5 reflects the shipped ack-gated behaviour with flow.py listed; CLAUDE.md matches the code; F1/F3 recorded as SUMMARY findings; build clean.</done>
</task>

</tasks>

<threat_model>
## Trust Boundaries

| Boundary | Description |
|----------|-------------|
| published docs → reader behaviour | Superseded workaround recipes drive readers into anti-patterns against real devices |
| repo instructions → agent behaviour | Stale CLAUDE.md claims misdirect future automated work |

## STRIDE Threat Register

| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|-----------|----------|-----------|----------|-------------|-----------------|
| T-05-06 | Information Disclosure | docs/architecture/overview.md Layer 5 bullet | low | mitigate | New bullet uses D4-01/D4-02 behavioural wording only; negative grep asserts no tuning constants |
| T-05-07 | Denial of Service | advanced-usage.md fire-and-forget example | low | mitigate | Example slowed to 20 FPS / one-shot scope; the flooding-prone streaming framing is removed |
| T-05-SC | Tampering | npm/pip/cargo installs | low | accept | No package-manager installs occur in this phase (RESEARCH §Package Legitimacy Audit: none) |
</threat_model>

<verification>
- `uv run zensical build` exits 0 after every task; no warning names advanced-usage.md or overview.md; warning total stays at the pre-edit baseline (RESEARCH.md records 8, all in docs/api/ pages this phase never edits)
- mkdocs.yml unchanged (D5-01); docs/api/*.md, docs/changelog.md, and all source files unchanged (D5-11)
- SUMMARY contains a "Findings" section recording F1 and F3
</verification>

<success_criteria>
- No published prose page still recommends pre-v1.1 workarounds (two-pass discovery, fast=True streaming loops) or inflated FPS figures
- architecture/overview.md accurately describes the Phase 4 animation layer including flow.py
- CLAUDE.md agrees with the shipped code (FPS framing, 15.0 s discovery default)
- F1/F3 surfaced for the operator without exceeding the locked audit scope
</success_criteria>

## Artifacts this phase produces (this plan's share)

- Retitled heading/anchor: `docs/user-guide/advanced-usage.md` → `### Fire-and-Forget Mode for Low-Latency One-Shots` (`#fire-and-forget-mode-for-low-latency-one-shots`; replaces the old fire-and-forget heading — no in-repo inbound links to the old anchor exist, and the build gate would surface any)
- Removed section: the two-pass discovery pattern in `docs/user-guide/advanced-usage.md` (lines 280–303 pre-edit)
- New Key Files entry: `animation/flow.py` in `docs/architecture/overview.md`
- Modified files: `docs/user-guide/advanced-usage.md`, `docs/architecture/overview.md`, `CLAUDE.md`
- No code symbols, no new pages, no nav entries

<output>
Create `.planning/phases/05-reliability-documentation/05-03-SUMMARY.md` when done.
Record in the summary: a "Findings" section with F1 (docs/api/animation.md:5 stale FPS prose — surfaced, not fixed, per D5-10 scope) and F3 (no wrong docstrings found), plus confirmation that docs/api/, changelog, and source files are untouched.
</output>
