chore: open-source readiness pass

[raluagent-ai]

Open-source readiness pass for a public release of live-streamer. No runtime behavior changes — deletions, content scrubs, doc additions, and comment-only edits.

Deleted (internal / dev-only docs)

• REPORT.md, CHANGELOG.md (687-line internal engineering log)
• stream_orchestrator/PHASE_3_DESIGN.md — internal design doc containing live kill-test session IDs
• research/HEYGEN_REALTIME_STALL_20260602.md — internal HeyGen backend bug report
• docs/launch-fixes-spec.md, docs/prompt-restructure-spec.md, docs/word-end-backlog-gate-spec.md
• All of docs/notes/ (3), docs/plans/ (1), and docs/superpowers/plans/ (9) — empty dirs removed
• docs/superpowers/specs/2026-05-27-episode-v2-design-and-plan.md — a not-explicitly-listed doc I judged internal (authored "Claude (no mentor)", addressed to "a new Claude session with no memory")

Scrubbed (kept the file, fixed the content)

• canary (HeyGen internal staging-env name) removed from all code comments and docs — neutralized to "the HeyGen API" / "HeyGen" / "staging" as fit context. Covers stream_orchestrator/* (client/poller/supervisor/http_server/main/config.toml), ARCHITECTURE.md, RUN.md, TECHNICAL_OVERVIEW.md, showrunner/*, script_producer/producer_config.toml, the demo HTML. (One remaining "canary" in test_activity_state.py is the coal-mine sense — a canary test — left intact.)
• Live/internal IDs genericized: session id auto-40122cf8-0005 in runtime.py; example avatar_id/voice_id in RUN.md → <your-...> placeholders.
• Dangling doc links removed: STATUS.md, CHANGELOG.md, PLAN.md (none exist) from README/TECHNICAL_OVERVIEW; and PHASE_3_DESIGN.md / word-end-backlog-gate-spec.md pointers stripped from code comments now that those docs are gone.
• README test-count contradiction (1,742 vs 1,197) resolved — replaced with neutral wording ("each package ships its own pytest suite") since I couldn't run the suites here to verify an exact number.
• "internal monorepo extraction" framing softened in README + TECHNICAL_OVERVIEW to neutral standalone-project wording.
• stream_orchestrator/ARCHITECTURE.md: removed "draft — awaiting signoff / do not start implementation" scratch framing, the "Open questions for user signoff / before I start Phase 1" framing, ai-twitch-streamer/ references, and internal HeyGen backend source line-citations (controller :37-61, service :563-656, emitter :1001, …) → generic "HeyGen API".

Added

• LICENSE — MIT, Copyright (c) 2026 HeyGen
• CONTRIBUTING.md — per-package uv setup, Python 3.11, how to run tests, PR expectations
• README rewrite — crisp intro, two Mermaid diagrams (system architecture + roast lifecycle), Prerequisites, Setup, Run, Architecture table, and docs index. Every technical claim verified against the code: the 3-model split (episode author claude-opus-4-8, reactive planner claude-sonnet-4-6, chat ack claude-haiku-4-5), the M1↔HeyGen↔OBS↔Twitch flow, ports, and scripts.

Code hygiene

Conservative pass across the 4 packages. The code was already clean: the only print() in package source is the intentional notify.py stderr fallback (kept); no TODO/XXX/HACK/FIXME; no commented-out code blocks; no pdb/breakpoint; no placeholder/no-op tests. No logic changed — the only source edits are comment scrubs. All edited Python files pass py_compile.

Flagged for your call

• Test suites not run locally: uv isn't available in my environment, so I could not execute pytest. No logic changed, so risk is low, but please confirm CI is green. (For reference, def test_ counts: stream_orchestrator 217 · showrunner 1248 incl. 7 live · chat_ingester 111 · script_producer 53.)
• Pre-existing dangling MODULE_2_ARCHITECTURE.md references (~20, in stream_orchestrator/* and script_producer/* comments + MODULE_1_BRIEF.md, MODULE_2_BRIEF.md): these docs were dropped in the original extraction, before this PR. I left them untouched (out of scope, and mass comment-editing is risky) — flagging so you can decide whether to strip them.
• Nacos + internal backend file citations in a few code comments (config.py, config.toml, avatar_realtime_v3.py:401): reference HeyGen's internal config/backend. Low-sensitivity (no secrets), left intact — call if you want them genericized.
• Owner handles as test fixtures: heyular (Twitch) and ukimsanov (GitHub) appear throughout tests and a couple docs as example submitter data. They're your own public handles, not internal/sensitive, so I left them. Easy to sweep to a neutral placeholder if you'd prefer.
• ARCHITECTURE.md §15: I reframed the "signoff" header to "Design decisions" but the numbered items keep a light first-person voice ("I'll commit ~50 paragraphs…"). Not sensitive; left as-is.

— Ralu 🦦