# Specification: Docs IA Restructure

**Track ID:** docs-ia-restructure_20260319
**Type:** Chore
**Created:** 2026-03-19
**Status:** Draft

## Summary

Restructure the user-facing documentation to eliminate ~1,365 lines of content duplication, relocate misplaced pages to correct sections, add missing cross-links, and update the mkdocs.yml navigation to follow a clear progressive disclosure hierarchy (Getting Started → User Guide → API Reference).

## Context

An IA review of `docs/` revealed that Effects content is scattered across 6+ files with ~1,500 lines duplicated, Themes is duplicated across 3 sections, Animation has a verbatim copy in both User Guide and API Reference, and several pages live in the wrong section (Protocol Deep Dive in User Guide, Ceiling Lights as standalone user guide). Four API reference pages are orphaned with zero inbound links.

## Acceptance Criteria

- [ ] `getting-started/effects-gallery.md` deleted (redundant with effects.md)
- [ ] `getting-started/effects.md` trimmed to ~100 lines intro + links to User Guide
- [ ] New `user-guide/effects.md` contains the canonical effects guide (moved from getting-started)
- [ ] `api/animation.md` reduced to brief API overview + link to user guide (no duplicated prose)
- [ ] `getting-started/themes.md` trimmed to ~40 lines (just "apply a theme" + link to User Guide)
- [ ] `user-guide/protocol-deep-dive.md` relocated to `architecture/`
- [ ] `user-guide/troubleshooting.md` cross-links to effects-troubleshooting.md
- [ ] Orphaned pages linked: `api/network.md`, `api/high-level.md`, `migration/effect-api-changes.md`, `api/colors.md`
- [ ] Progressive disclosure links added (Getting Started → User Guide → API Reference)
- [ ] `mkdocs.yml` nav updated to reflect new structure
- [ ] `uv run mkdocs build` completes with no errors
- [ ] No broken internal links in docs

## Dependencies

- review-docs_20260318 (completed) — correctness fixes should land first

## Out of Scope

- Writing new documentation content
- Changing API reference auto-generation (mkdocstrings config)
- README.md restructure
- Changelog changes (auto-generated)

## Technical Notes

- This is a docs-only change — no Python source code modifications
- `api/effects.md` is a hand-written reference (no mkdocstrings `:::` directives) — keep as reference, just remove any prose that duplicates the User Guide
- `api/animation.md` is a prose duplicate of `user-guide/animation.md` — trim to a brief overview + link to user guide + key API reference details
- `getting-started/effects.md` is 906 lines; the bulk should become `user-guide/effects.md` with the getting-started version becoming a brief intro
- File moves require updating both the physical file AND `mkdocs.yml` nav entries
- Internal links using relative paths (e.g., `../api/effects.md`) must be updated when files move

---

_Generated by Conductor. Review and edit as needed._
