ersatztv/docs/handoffs/chicorytv-issue-queue.md

ChicoryTV issue-queue handoff (living document)

Paste the prompt below into a fresh session to work the next item. Each session ends by UPDATING THIS FILE in place (rewrite the state section and the queue for the next item) so it always holds the current handoff. History: created 2026-07-02 after the plan audit (#59 epic); all backend gap issues (#100–#111), all SPA screens (#84–#89, #93, #109), the rebrand (#90), the cutover root-flip (#91 phase a), full scheduling parity (#144/#162), media/troubleshooting parity (#141/#161/#158/#180), onboarding docs (#185), the collections/API-gap batch (#155/#151/#152-backend/#184), the multi/rerun/playlist SPA editors (#151/#152 PR #194, #153 PR #195), CI speedups (#190 PR #192), #145 playback troubleshooting (PR #199), #198 OpenAPI casing (PR #201) + #193 rerun existence-check (PR #200), the first #91-gate batch #210/#211/#213-partial (PR #214), and the search/media mutation batch #208/#209 (PR #216, shared Add-to layer) are MERGED. v26.5.0 in prod; v26.6.0 tagged (awaiting Komodo pin bump in server-management).

Session state (2026-07-10, #208/#209 session): #208 + #209 CLOSED via PR #216 (merged c63cadb8). New API surface: POST /api/playlists/{id}/items (wraps existing AddItemsToPlaylist; handler hardened to reject system playlists — latent Blazor-path gap) and GET /api/search/all-items (wraps QuerySearchIndexAllItems; Add-All = materialize-then-add, Blazor two-step parity — no query-based add command exists). SPA: shared Add-to layer web/src/media/addTo/ (Collection dialog w/ inline create, Playlist dialog filtering isSystem, Schedule dialog replicating AddProgramScheduleItem.ForMediaItem defaults — addTo/scheduleItem.ts, SaveAsSmartCollectionDialog, AddToMenu popover) + MediaPosterCard actions slot; wired into search (card drill-in, per-card add, Select toggle + selection bar, Add All, Save As Smart Collection) and browse/detail (multi-select + select-all-on-page, all four detail screens, per-show Quick/Deep scan gated Plex/Jellyfin/Emby, per-episode Media Info + Troubleshoot, seasons browse kind). Add-to-schedule is gated to shows/seasons/artists — the server validator (ProgramScheduleItemCommandBase.CollectionTypeMustBeValid) only accepts those per-media-item kinds, matching Blazor's ForMediaItem call sites (found by live E2E: movie adds 422'd). Also fixed: portal font bug (nothing set a body font; portaled dialogs fell back to Times — body rule added), a mount-debounce race (the 300ms query-debounce commit wiped in-progress selections; lastQueryRef no-change guard in Search+Browse screens), and the e2e-local.sh stale-asset gotcha (cp -R into an existing dir nests + serves the previous run's assets — script now rm-first). New issues: #217 (add-items handlers validate only 4/10 kinds — pre-existing), #218 (fresh-DB "Playouts 3" badge + "1 failing" chip). Retro/pre-review issues filed in adversarial-reviewer: #18 (this milestone + #214), #19 (upcoming #207/#212, #202, #91b, #197). #213 remains OPEN (reduced read-only-convenience scope).

Blazor removal (#91 phase b) remaining MUST-FIX gates, in order:

1. #207 (+#212) — schedules editor full mutation depth (endpoints exist; needs languages enumeration endpoint shared with #212 channel-editor pickers) ← NEXT (prompt below)
2. #202 — media-source management (write REST API + SPA screens; largest, riskiest)
3. #91 phase (b) removal PR — pattern redirects + catch-all (#204 plan), blazor-final tag (#205), auth posture note (#206), delete Pages/Shared/ViewModels/Validators + 6 packages (MudBlazor, MediatR.Courier.DependencyInjection, Blazored.FluentValidation, BlazorSortable, Heron.MudCalendar, Chronic.Core). Removal recon is DONE (2026-07-09 gate session): Courier consumers are 100% Blazor (AddCourier Startup.cs:394 dies too); the Startup MapWhen "blazor" branch (736–795) CO-HOSTS MapControllers/OpenAPI/Scalar — surgical removal only (MapBlazorHub:775, MapFallbackToPage:776, services 379–398); wwwroot/lib/*+css/site.css are _Host-only; check Locals/*.resx consumers before deleting; keep Extensions/ except NavigationManagerExtensions.cs.

Lessons for all remaining prompts (conventions live in docs/; this is workflow lore):

• READ docs/README.md → the convention docs FIRST; point recon/implementer agents at specific doc sections. Only recon the task-specific delta.
• blazor-route-parity.md now carries mutation-depth verdicts (2026-07-09 sweep table at the top of Section 2). A row is only trustworthy if its cluster verdict is PARITY-OK; the sweep evidence lives in the issues #207–#213. Keep the verdict table updated as gates close.
• "Screen exists" ≠ parity: the root cause of the false SPA-READY rows was same-session verification that never diffed capabilities against the Blazor page. Per-capability diff vs the Blazor page is the standard for any future parity claim.
• Several gaps are UNWIRED EXISTING endpoints (playout delete/reset, block copy, scan-show, collections add-item kinds) — check the endpoint index before building new API surface.
• Keep the MAIN checkout's web/node_modules fresh (npm install after pulling a PR that adds a dep) — worktrees copy it, and a stale copy broke typecheck in a #198 worktree.
• Playwright-MCP E2E: never open tabs/window.open for file-download endpoints — curl them. If browser tools stall repeatedly, pkill -f ms-playwright-mcp and drive a fresh session.
• The user's main checkout (/Users/timothy/ersatztv) stays ON main and pulled each session. Feature work in worktrees off origin/main; copy web/node_modules from the main checkout.
• Subagent connection drops = laptop sleep/transient; re-resume via SendMessage (work survives).
• Build/verify locally, then trust it; CI (VM 127) confirms (~9 min warm). Watch by commit status: /api/v1/repos/timothy/ersatztv/commits/{sha}/status.
• PR routine (works): worktree off origin/main → implement (opus judgment-heavy / sonnet mechanical; doc pointers + exact facts; csharp-lsp for C#) → API changes: build app project FIRST then ./scripts/update-openapi.sh then npm run generate:api → full local test pass → push, PR → fork adversarial review (SCOPED "review only") + live-E2E for UI changes (scripts/e2e-local.sh) → review fixes as follow-up COMMITS (never amend/force-push) → CI green → merge (consent per session) → structured close comments per CLAUDE.md protocol.
• Never run TWO committing agents on one worktree concurrently. Read-only review forks are fine.
• Reusable API facts: DTO records in ErsatzTV.Core/Api need file-scoped #nullable enable; ErsatzTV.Application has NO nullable context (CS8632); Option<T>→nullable = MatchUnsafe(v => (T?)v, () => null); LanguageExtensions.Apply collapses NotFoundError→422, so real 404s need a controller pre-check; id-taking child GETs get an OpenApiErrorResponseContractTests [TestCase].
• Arm a CI monitor the moment the PR opens — in the #216 session three PR runs sat red for ~an hour (a CI-only debounce-timing flake) while review/E2E ran, because CI was only checked "at the end". Also: concurrent runs can collide on the MySQL service host port 3306 ("port is already allocated") — that's infra flake, rerun; consider unpinning the host port.
• "Make X consistent with Y" review findings deserve new-code scrutiny — a #216 review fix propagated MediaBrowseScreen's mount-debounce selection-wipe race to SearchScreen instead of catching it. For any timer/effect, ask "when does this fire?" (incl. mount).
• SPA mutation affordances on media items: USE the shared web/src/media/addTo/ layer (spa-conventions §5c) — don't build screen-local pickers. Schedule adds are valid only for shows/seasons/artists (server validator).
• Live E2E seeding: the local library isn't API-seedable; the #216 E2E agent generated tiny ffmpeg testsrc MKVs + inserted LibraryPath rows via SQL then scanned. Recipe not yet in docs/e2e-local.md — worth adding next time it's needed.

---

PROMPT — #207 + #212: schedules editor mutation depth + channel-editor gaps

You are Fable, the ORCHESTRATOR in the main Claude Code session. Fable is EXPENSIVE: delegate (recon → Explore/haiku; mechanical → sonnet; judgment-heavy → opus; fable forks for review). FIRST read CLAUDE.md, docs/README.md + the convention docs it indexes, and the Lessons above.

HARD CONSTRAINTS:

• Work in worktrees off origin/main. Copy web/node_modules from the main checkout.
• PARALLELIZE BY DEFAULT: split the task into disjoint slices up front and run 3–4 implementer agents concurrently (recon agents are free — always fan those out). 3–4 concurrent dotnet/npm builds are fine on this Mac (M4, 10 cores, 16 GB); check uptime before a big fan-out — if 1-min load > ~6, drop to 2–3. Never 5+ builds (the historic crash was an 8–9-way fan-out). NEVER set ETV_UPDATE_GOLDENS.
• Never two committing agents on ONE worktree — give each parallel slice its own worktree branched off the feature branch and merge back. Sequence only where a slice genuinely depends on another's output (backend-first narrow, SPA-wide after worked well for #216).
• Merge consent in-conversation per session (prior pre-approvals do NOT carry over).
• Arm a CI monitor on the PR head sha AT PR-OPEN (commit-status endpoint), not at the end.
• Live-E2E via scripts/e2e-local.sh; NEVER exercise download endpoints via browser tabs (curl them). Adversarial review fork per PR diff, SCOPED "review only".

Task — close the #207 + #212 gates

Read issues #207 and #212 (bodies carry the #203-sweep evidence) and adversarial-reviewer #19 (pre-review asks). #207 is the screen the false-parity review made an example of: the SPA schedules editor is a near read-only viewer — schedule create/edit/delete missing, every per-item inspector control hard-coded disabled (~35 Blazor fields), add-item is defaults-only — while the REST endpoints already exist and are unused (PUT /api/schedules/{id}/items replace, POST .../items single-add with the FULL ScheduleItemRequest — see addTo/scheduleItem.ts for a working payload builder). Enumerate EVERY Blazor ScheduleItemsEditor.razor field and wire it (per-capability diff is the parity standard). #212 channel editor gaps: external logo URL, bare create, and pickers — needs a languages enumeration endpoint shared by both editors (preferred audio/subtitle language pickers); design that endpoint once. Record conventions in decisions.md; full PR routine (OpenAPI regen for any new endpoint; blazor-route-parity verdict rows for the schedules + channel-editor clusters). Comment + close #207/#212 per protocol.

On completion — REQUIRED last step

Update THIS handoff (pop the done items, promote #202 to next with a fresh prompt), commit to main, print the next prompt in a fenced code block.

---

Issue queue (work top-down)

1. #207 (+#212) schedules editor depth + channel-editor gaps ← PROMPT above.
2. #202 media-source management (write API + SPA) — largest; pre-review the API design (adversarial-reviewer #19) before building.
3. #91 phase (b) Blazor removal PR (gate cleared once 1–2 close; #204/#205/#206 fold in; removal recon in session state of the 2026-07-09 entry; adversarial pass mandatory).
4. #197 cold API contract+security review — HARD GATE on #58 close/go-live and MANDATORY before any remote exposure. Inputs: #215, #217, backlog nits.
5. Backlog: #215 (API playout mutations skip EntityLocker gating), #217 (add-items validates only 4/10 kinds), #218 (fresh-DB Playouts badge / "1 failing" chip), #213 remainder (logs sort/page-size persistence, block-history page-size/gating, list filters), #99 (TS/HLS-Direct session tracking), #66 (artwork magic-byte sniffing), CI: unpin MySQL service host port 3306 (concurrent-run collision), nits (unclamped pageSize, 30 MB bare 413, PlayoutController route Name=/lightweight exists-check, guide 21-include eager-load + fillerKind notes — #85/#102 comments), review nits from #216 (last-used-collection memory, detailBrowseItem cast). Cross-refs: v26.6.0 deploy = Komodo pin bump (server-management). Real-transcode E2E of the playback screen: once on the test container (ersatztv-test runs :latest) — local ffmpeg 8.1.2 lacks subtitles/zscale filters.