docs: sync root docs, CONTRIBUTING tree, docs/*.md,

windows-quirks with the facade/siblings layout (#102117)

docs/session-lifecycle.md

@@ -1,7 +1,7 @@
 # Session Lifecycle
 
 > **Audience:** Gateway developers and maintainers
-> **Source files:** `gateway/session.py` (~1444 lines), `gateway/run.py` (~16800 lines), `gateway/config.py`
+> **Source files:** `gateway/session.py` (~1200 lines + `session_*.py` siblings), `gateway/run.py` (~5500 lines facade + `run_*.py` phases), `gateway/config.py`
 > **Last updated:** 2026-06-16
 
 ## Overview
@@ -14,9 +14,10 @@ The session system lives primarily in two modules:
 
 - `gateway/session.py` — Data model (`SessionSource`, `SessionEntry`, `SessionContext`),
   key generation (`build_session_key`), and the main store (`SessionStore`).
-- `gateway/run.py` — Gateway runner (`GatewayRunner`) that wires sessions into the message
-  processing pipeline: session expiry watching, agent caching, restart recovery, and message
-  queuing.
+- `gateway/run.py` — Gateway runner (`GatewayRunner`) facade that wires sessions into the message
+  processing pipeline; the phases live in `run_*.py` siblings: session expiry watching
+  (`run_watchers.py`), agent caching (`run_agent_cache.py`), restart recovery
+  (`session_recovery.py`), and message queuing (`run_busy.py`).
 
 ---
 

docs/streaming-tts.md

@@ -18,7 +18,7 @@ The streaming pipeline has four parts:
 3. **TTS provider** — a registered `StreamingTTSProvider` turns each sentence
    into raw PCM chunks (int16 mono at the provider's declared `sample_rate`)
 4. **Audio sink** — `sounddevice.OutputStream` for local playback
-   (`tools.tts_tool.stream_tts_to_speaker`), or a gateway platform adapter's
+   (`tools.tts_tool_speaker.stream_tts_to_speaker`), or a gateway platform adapter's
    `write_streaming_tts` seam (`gateway/streaming_tts_consumer.py`)
 
 Providers with no chunked API still get per-*sentence* playback via the proven