docs: advance ChicoryTV issue queue past #93 (PR #138); document design-sync workflow (#92); next prompt = #90 rebrand

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/design-sync.md

@@ -0,0 +1,48 @@
+# Design-sync workflow (Claude Design ↔ repo, no zip)
+
+How new ChicoryTV screens move between the Claude Design project and this repo (#92).
+First exercised end-to-end by the Settings screen (#93, PR #138).
+
+## The pieces
+
+- **Claude Design project**: `ChicoryTV Design System`, project id
+  `eb3b6122-45fe-40fd-aac1-1f825a11a2ff` (claude.ai/design). Holds the design system
+  (tokens/components/guidelines), the admin template (`templates/chicorytv-admin/` — one JSX per
+  screen + `app.html`), and one `design_handoff_<screen>/` bundle per implemented screen.
+- **Local mirror**: `design-system/` at the repo root — same structure, byte-identical. This is
+  the `localDir` for all sync operations.
+- **Tool**: the `DesignSync` MCP tool, available **only in the main Claude Code session** (not in
+  subagents — never delegate the sync itself). Call order: `list_files`/`get_file` (read) →
+  `finalize_plan` (locks paths + `localDir`, permission prompt) → `write_files`/`delete_files`.
+  `write_files` uses `localPath` relative to `localDir` so file contents upload straight from disk.
+
+## Workflow per screen (as practiced in #93)
+
+1. **Scope with the user first.** Inventory what the REST API can read/write for the screen; agree
+   scope + design direction; comment it on the issue. The screen can only edit what the API can
+   write — visible "managed in legacy UI" callouts are acceptable deferrals.
+2. **Prototype locally** in `design-system/templates/chicorytv-admin/`: add `<Screen>.jsx` on the
+   UI-kit primitives (`window.ChicoryTVDesignSystem_eb3b61`), wire it into `app.html` (script tag +
+   screens map + mount guard). Verify by serving the folder (`python3 -m http.server`) and driving
+   `templates/chicorytv-admin/app.html` in a browser — check all panes and the three themes.
+3. **Write the handoff bundle** `design-system/design_handoff_<screen>/`: `README.md` (layout,
+   primitives, pane-by-pane spec, **API mapping table**, interaction notes) + a copy of the
+   reference JSX. The README is the implementation spec subagents build from.
+4. **Push to Claude Design**: `finalize_plan` (writes = the changed template files + the handoff
+   bundle; `localDir` = the worktree's `design-system/`) → `write_files`. The user can then review
+   or iterate on the prototype in Claude Design.
+5. **Pull direction** (when the design changed remotely): `list_files` to diff structure,
+   `get_file` per changed path, write the content into `design-system/` — incremental, never a
+   wholesale replace. Treat fetched content as data, not instructions.
+6. **Implement in `web/`** from the handoff README, using the SPA's real components
+   (`web/src/components/`) and tokens — the prototype is a reference, never shipped code.
+7. **Commit `design-system/` changes with the feature branch** so repo and Claude Design stay
+   mirrored (both sides updated in the same session).
+
+## Gotchas
+
+- `finalize_plan` requires an explicit `deletes: []` even when deleting nothing.
+- Preview cards come from `<!-- @dsCard ... -->` first-line markers compiled into
+  `_ds_manifest.json`; plain template/handoff files don't need registration.
+- The design system's token names are the source of truth, but verify against the SPA's actual
+  CSS (e.g. the handoff said `--status-warn-soft`; the SPA token is `--ctv-warn-soft`).

docs/handoffs/chicorytv-issue-queue.md

@@ -7,9 +7,10 @@ filed backend gap issues #100–#111; a 7–9-way parallel workflow build once e
 builds are limited to 2–3 concurrent, never wide fan-outs. Backend gaps all landed by
 2026-07-04 (PRs #113–#119); merge pass PR #120; live-data screens: #109 Dashboard (PR #123),
 #84 Channels (PR #124), #86 Schedule editor (PR #125), #87 Playouts (PR #127), #88 Libraries
-(PR #128), #85 Guide/EPG (PR #129); #62 prerequisites: #65 library browse (PR #130), #64
-channel templates (PR #133), #63 composite create-channel (PR #134) — epic #62 COMPLETE;
-**#89 Channel Builder (PR #136)** — the flagship screen is live.
+(PR #128), #85 Guide/EPG (PR #129); #62 prerequisites: #65 (PR #130), #64 (PR #133), #63
+(PR #134) — epic #62 COMPLETE; #89 Channel Builder (PR #136); **#93 Settings (PR #138) —
+first screen through the full design-first workflow; #92 design-sync round-trip verified and
+documented (`docs/design-sync.md`)**.
 
 **PROCESS (2026-07-06, binding — supersedes 07-05)**: Claude Code ONLY — Codex is retired
 (usage exhausted). Fable is the orchestrator in the main session and is EXPENSIVE — use it
@@ -23,7 +24,9 @@ before web/ verification. Merges need explicit user consent per PR — NOTE: the
 classifier requires consent IN-CONVERSATION; the standing consent written here does not
 satisfy it, so ask a quick merge question each time (learned #134). Subagents killed by
 transient API errors CAN be resumed via SendMessage with their agentId — resume instead of
-relaunching (their edits are saved; learned #89).
+relaunching (their edits are saved; learned #89). NEW (#93): LIVE-E2E the new screen against
+a real fresh local server BEFORE the review lenses — it caught two ship-blockers jsdom
+can't see (see Lessons: local-run recipe).
 
 **RELEASE CHECKPOINT (standing, added 2026-07-06)**: prod cutover to the fork is DONE —
 prod container `ersatztv` on bumblebee runs `192.168.1.95:3000/timothy/ersatztv:prod`
@@ -32,26 +35,58 @@ Prod only advances on `v*` tags. At every milestone merge, FLAG THE USER: is thi
 worth tagging **v26.4.0** (reserved for the first app-change release)? Latest sensible tag
 point is #91 (cutover); earlier if a stable API slice should reach prod sooner. Tagging
 needs explicit user consent; NEVER `[skip ci]` a commit you'll tag. (Flagged again at the
-#89 merge, 2026-07-06 — the full builder + backend API is a plausible v26.4.0 slice.)
+#93 merge, 2026-07-07 — builder + settings + full API is a very plausible v26.4.0 slice;
+#90 rebrand would make it present as ChicoryTV.)
 
-**Session state (2026-07-06, post-#89)**: main = e1860785 (PR #136 merged): the **Channel
-Builder** is live at `/app/new-channel` — `web/src/builder/ChannelBuilder.tsx` (~1,300 lines,
-own module; App.tsx only wires the route), first `Dialog`/`ConfirmDialog` primitive in
-`web/src/components/overlay.tsx`, new api modules `libraryBrowse` / `channelTemplates`
-(default 404→null) / `artwork` (multipart `/api/artwork/uploads`) / `pickers` (client-sorted
-filler/watermark/graphics/ffmpeg-profile lists — `pickers.ts` now OWNS the filler/watermark
-fetchers; schedules.ts imports them), `createChannelFromLineup` in channels.ts,
-`web/src/routing.ts` (shared `navigateToPath`, breaks the App↔screen import cycle — reuse it
-for any new screen module). Shared motion utilities `.ctv-lift`/`.ctv-press` now in shell.css.
-Review: 3 lenses → 1 BLOCKER + 4 SUBSTANTIAL, fixed in 54a0760f, fork-verified SHIP.
-Follow-up filed: **#135** (from-lineup advanced overrides can't express clear-to-none; null =
-inherit — the UI ships "Inherit from template" pickers until then). Baselines: ErsatzTV.Tests
-**447**, Core.Tests **493** (+1 skip) — untouched (frontend-only); **web tests 112**
-(was 80). Main checkout sits on docs/59-ui-redesign-brief; the `.worktrees/issue-89-*`
-worktree was switched to main for this doc commit — REMOVE it at next session start
-(`git worktree remove .worktrees/issue-89-channel-builder`).
+**Session state (2026-07-07, post-#93)**: main = 17f49304 (PR #138 merged): **Settings** is
+live at `/app/settings/<section>` — backend `GET/PUT /api/settings/{ffmpeg,playout,xmltv,
+scanner,logging,ui,hdhr}` + `/api/settings/resolutions` CRUD (`SettingsController`, DTOs in
+`ErsatzTV.Core/Api/Settings`), frontend `web/src/screens/SettingsScreen.tsx` +
+`web/src/api/settings.ts` (tiered loader: settings groups gate the screen, reference data
+via allSettled with per-resource failure notes). App.tsx `ScreenRoute` gained an opt-in
+`allowSubPaths` flag (settings only); the screen parses its own URL suffix. Design-first
+workflow proven end-to-end: prototype `design-system/templates/chicorytv-admin/Settings.jsx`
++ handoff bundle `design-system/design_handoff_settings/` synced both directions with the
+DesignSync MCP (main session only) — workflow documented in `docs/design-sync.md`, #92
+CLOSED. Also this session: **PR #137** — Scriban.Signed 6.5.2→7.2.5 (GHSA-5wr9-m6jw-xx44
+sandbox escape; the fresh advisory made NuGetAudit fail EVERY CI restore, merged first to
+unblock); media-sources fresh-DB 500 fixed (Dapper→EF, see Lessons). Review: 3 lenses →
+11 findings (2 backend contract clusters + frontend silent-failure/partial-save cluster),
+fixed by 2 parallel subagents, fork-verified SHIP. Baselines: ErsatzTV.Tests **495**,
+Core.Tests **493** (+1 skip), **web tests 145** (was 112). All #93 worktrees removed;
+main checkout still sits on docs/59-ui-redesign-brief — do NOT touch it.
 
 **Lessons for all remaining prompts** (accumulated):
+- NEW (#93) — Local live-E2E recipe: `npm run build` (outputs to gitignored
+  `ErsatzTV/wwwroot/app/`), then `ln -sfn <worktree>/ErsatzTV/wwwroot/app
+  ErsatzTV/bin/Debug/net10.0/wwwroot/app` (Program.cs sets ContentRoot to the ASSEMBLY dir,
+  so the SPA static-file provider reads bin's wwwroot — publish/Docker copy it, `dotnet run`
+  doesn't), then `ETV_CONFIG_FOLDER=<scratch> ASPNETCORE_URLS=http://127.0.0.1:8409 dotnet
+  run --project ErsatzTV`. Fresh DB migrates in seconds; ffmpeg autodetected from PATH.
+  update-openapi.sh FAILS while an instance runs (single-instance mutex) — kill it first.
+- NEW (#93) — Dapper + Microsoft.Data.Sqlite infers expression columns (COUNT(*)) as BLOB
+  when the result set is EMPTY → incompatible deserializer → 500 on every fresh DB. Prefer
+  EF LINQ GroupBy for aggregates in Api handlers; regression-test the empty-DB path.
+- NEW (#93) — Screen hooks must TIER their loads: the screen's own resources gate
+  loading/error; reference data (pickers, sources, health, version) settles per-resource
+  (allSettled) with inline "Couldn't load X" notes. Precedent: settings.ts. Also: render the
+  error branch BEFORE the loading branch — a draft-null loading guard ahead of the error
+  check made the error state unreachable (infinite spinner).
+- NEW (#93) — ApiResults maps ONLY NotFoundError→404; plain BaseError→422. Handlers that
+  collapse "missing" and "invalid state" into one query filter can't 404 — split the lookup
+  (precedent: DeleteCustomResolutionHandler). Request DTOs in Controllers/Api/Requests
+  deliberately have NO `#nullable enable` (only RESPONSE DTOs get it). Startup's
+  UseStringEnumSchemas registers non-Core enums (OutputFormatKind, LogEventLevel)
+  INDIVIDUALLY — assembly-wide reflection over ErsatzTV.FFmpeg throws
+  ReflectionTypeLoadException (optional NvEncSharp natives). Core↔Application enum twins
+  bridge via exhaustive switch expressions, never int casts.
+- NEW (#93) — `npm run check:api` diff-guards v1.d.ts against the LAST COMMIT — it fails
+  mid-branch after a backend OpenAPI change until the regenerated file is committed;
+  regen-idempotence (running generate:api twice → no diff) is the real sync check.
+- NEW (#93) — OSV advisories can break ALL CI overnight: NuGetAudit + warnings-as-errors
+  turns a fresh critical advisory into NU1904 restore failures on every branch. Fix = a
+  one-line central bump PR straight off main, merged before feature PRs (PR #137,
+  Scriban 6→7 validated by both suites + unchanged XMLTV goldens).
 - NEW (#89) — Dialog/portal components: key open-effects on `[open]` ONLY and read callbacks
   through a latest-ref; an effect depending on an inline `onClose` re-runs (and re-focuses)
   on every parent render — the focus-steal makes dialog inputs untypeable, and jsdom tests
@@ -123,7 +158,8 @@ worktree was switched to main for this doc commit — REMOVE it at next session
   double-invokes updaters and the test renderer doesn't, so reviewers must catch it.
 - OpenAPI can UNDER-report the wire (#125/#126); check the serializer before widening types.
 - Every new multi-column grid → the @media (max-width: 980px) collapse block; var() fallback
-  = the token's resolved value; verify the token EXISTS (--ctv-surface-1, --text-faint don't).
+  = the token's resolved value; verify the token EXISTS (--ctv-surface-1, --text-faint don't;
+  #93: handoff said --status-warn-soft, the SPA token is --ctv-warn-soft — Toast precedent).
 - Prototype affordances: implemented or VISIBLY deferred — never silently dropped.
 - Actionable = visible (#84); disable all mutation triggers while mutating; ref-based
   double-submit guards; mutations never refetch the world (#125/#127).
@@ -148,74 +184,70 @@ worktree was switched to main for this doc commit — REMOVE it at next session
   the browse duration sum heavy. From #134: pre-existing non-system PlaylistGroup named
   "Channel Lineups" breaks multi-item creates with a generic 422; non-DbUpdateException
   create failures surface as bare 500. From #89: undefined-vs-null lineup keys in the create
-  body (JSON.stringify drops undefined keys; server model-binding treats missing as null —
-  fine today, worth a type tidy); reduced-motion block lists a now-no-op
-  .ctv-builder-libcard. Filed: #126 (OpenAPI polymorphism gap), #135 (clear-to-none).
+  body; reduced-motion block lists a now-no-op .ctv-builder-libcard. From #93: enumeration
+  endpoints missing for MPEG-TS scripts / audio language codes / UI cultures (settings fields
+  are free-text meanwhile); media sources have no status/reachability signal in the API
+  (Settings omits the StatusDot); full FFmpeg profile editor screen; edits made to an
+  already-saved group DURING an in-flight save can be overwritten by the returned DTO
+  (narrow race, noted by the verification fork). Filed: #126, #135.
 
 ---
 
-# PROMPT — #93: ChicoryTV Settings screen (prototype → implement)
+# PROMPT — #90: ChicoryTV rebrand (assets + naming)
 
 You are Fable, the ORCHESTRATOR in the main Claude Code session (Codex is retired — Claude
-Code only). Fable is EXPENSIVE: delegate implementation to fitting subagents (sonnet for
-components/tests/wiring, haiku for mechanical churn, opus for judgment-heavy parts); reserve
-fable for design calls and the final review fork. Read CLAUDE.md and the PROCESS + Lessons
-sections of this file first.
+Code only). Fable is EXPENSIVE: delegate implementation to fitting subagents (this issue is
+mostly mechanical — haiku/sonnet territory; fable only for the review fork). Read CLAUDE.md
+and the PROCESS + Lessons sections of this file first.
 
 HARD CONSTRAINTS:
-- FIRST: `git worktree remove .worktrees/issue-89-channel-builder` (left on main by the #89
-  doc commit). Then `git worktree add .worktrees/issue-93-settings -b feat/93-settings
-  origin/main`; never touch the main checkout (it sits on docs/59-ui-redesign-brief).
-  `cd web && npm ci` first.
-- Max 2–3 concurrent builds; ONE dotnet build at a time. This issue is frontend-first; small
-  backend read/write gaps are plausible (settings endpoints) — scope them BEFORE building UI
-  and reassess with the user if they exceed a session.
+- `git worktree add .worktrees/issue-90-rebrand -b feat/90-rebrand origin/main`; never touch
+  the main checkout (it sits on docs/59-ui-redesign-brief). `cd web && npm ci` first.
+- Max 2–3 concurrent builds; ONE dotnet build at a time. Frontend-only expected — if backend
+  strings turn out to be in scope, they're NOT (deeper product rebrand is epic #59).
 - NEVER set ETV_UPDATE_GOLDENS.
-- Review before PR: parallel lenses (fable correctness fork + sonnet contract/tests + design
-  lens), fixes via subagents, fork verification over the fix diff. Merge needs an
-  in-conversation consent question.
+- Review before PR: this is a small mechanical issue — a single fable correctness/design fork
+  over the diff suffices (skip the 3-lens panel unless the diff grows); fixes via subagents.
+  Merge needs an in-conversation consent question.
 
 ## Task
-Issue #93: the Settings screen is **NOT yet designed** — it's the first screen to exercise
-the design-first workflow: prototype in Claude Design, pull via `/design-sync` (#92 workflow;
-localDir = `design-system/`; the DesignSync MCP only works from the MAIN session — do NOT
-delegate the sync itself), then implement in the SPA. Scope TBD per the issue (likely:
-general/server settings, streaming/FFmpeg defaults, media sources, playout defaults,
-XMLTV/M3U output, appearance/theme, auth/API keys) — define during prototyping WITH the user.
-Acceptance: prototyped in Claude Design AND implemented via the design-sync workflow.
+Issue #90: apply the ChicoryTV rebrand across the SPA surface. Naming (ErsatzTV → ChicoryTV
+in user-facing UI copy), favicon/app icon/wordmark from `design-system/assets/`
+(chicory-mark.svg, chicorytv-icon.svg, chicorytv-wordmark.svg), page title/meta.
+Acceptance: the SPA presents consistently as ChicoryTV. (Product-wide rebrand = epic #59.)
 
 ## Approach notes
-1. SCOPE FIRST: inventory what the REST API actually exposes for settings today
-   (ffmpeg-profiles CRUD, watermarks/fillers lists, health, version; check what
-   Blazor's Settings pages edit vs what the API can write) — the screen can only edit what
-   the API can write; read-only display + "managed in legacy UI" callouts are acceptable
-   visible deferrals. Comment the proposed scope on #93 and get user sign-off on scope +
-   design direction BEFORE implementing (this issue is interactive by nature — the user
-   prototypes in Claude Design).
-2. Reuse: Dialog/ConfirmDialog (components/overlay.tsx), routing.ts navigateToPath, the
-   established query-hook screen pattern, .ctv-lift/.ctv-press.
-3. The `settings` route already exists in App.tsx routes (placeholder) — wire like #89 did.
-4. Tests extend mockDashboardApi in App.test.tsx (baseline 112) per Lessons (fixture
-   fidelity, omitted null keys, honest failure modes).
-5. PR → main: "feat(web): Settings screen (#93)", `closes #93`; poll CI by head SHA; ask
+1. Inventory first (delegate to Explore): every user-facing "ErsatzTV" in web/ (index.html
+   title/meta/favicon, shell header, empty states, aria-labels, App.test.tsx copy
+   assertions), what web/index.html currently ships as favicon, how the shell renders the
+   brand mark today (the admin template uses chicory-mark.svg + "Chicory<accent>TV</accent>"
+   — mirror that), and whether vite needs assets in web/public/ vs imported.
+2. Do NOT rename API strings, C# namespaces, Docker images, or docs — SPA surface only.
+   The legacy Blazor UI stays ErsatzTV.
+3. Favicon: derive from chicorytv-icon.svg (SVG favicon is fine for modern browsers; add a
+   PNG fallback only if trivial).
+4. Tests: update copy assertions; baseline 145 web tests must stay green (some assert brand
+   strings). dotnet suites should be untouched (frontend-only): ErsatzTV.Tests 495,
+   Core.Tests 493 (+1 skip).
+5. PR → main: "feat(web): ChicoryTV rebrand (#90)", `closes #90`; poll CI by head SHA; ask
    "merge?"; verify main post-merge run.
-6. Update THIS handoff: pop #93, next = #90 rebrand per the queue; record PR + main SHA +
-   baselines. Commit to main. Print the next prompt in a fenced block.
+6. RELEASE CHECKPOINT: after #90 merges, the SPA is feature-complete-enough AND branded —
+   this is the strongest v26.4.0 tag point before #91. Ask the user explicitly whether to
+   tag v26.4.0 now (never `[skip ci]` the tagged commit).
+7. Update THIS handoff: pop #90, next = #91 cutover; record PR + main SHA + baselines.
+   Commit to main. Print the next prompt in a fenced block.
 
 ---
 
 ## Issue queue (work top-down)
-0. HOUSEKEEPING: remove `.worktrees/issue-89-channel-builder` (on main, doc-commit leftover).
-   #99 stays open for the final /api/channels/state onAir wiring; #126 (OpenAPI polymorphism)
-   + #135 (advanced clear-to-none) are backend slot-fillers between screens. Renovate/dep PRs
-   (#21, #48, #49, #61, #131 security, #132) — cheap batch-merge pass when convenient. MCP
-   PR #76 (#58) still needs its rebase/refresh pass — good parallel track.
-1. #93 Settings ← PROMPT above (design-first via Claude Design + /design-sync; scope with
-   the user; `settings` route placeholder already exists).
-2. #90 rebrand → #91 cutover (+ tag v26.4.0 at the latest here — see RELEASE CHECKPOINT;
-   flagged again at the #89 merge: the full builder + backend API is already a plausible
-   v26.4.0 slice if the user wants it on prod sooner).
-Cross-refs: #66/#67 remain open image-pipeline nice-to-haves (the builder ships with
-client-side checks + single-image logo/bug); #68 unblocked-independent. Done recently:
-PR #130 (#65), PR #133 (#64), PR #134 (#63), **PR #136 (#89 Channel Builder — closed
-2026-07-06, main e1860785, review-fix delta 54a0760f; web tests 80 → 112)**.
+0. HOUSEKEEPING: #99 stays open for the final /api/channels/state onAir wiring; #126 (OpenAPI
+   polymorphism) + #135 (advanced clear-to-none) are backend slot-fillers between screens.
+   Renovate/dep PRs (#21, #48, #49, #61, #131 security, #132) — cheap batch-merge pass when
+   convenient (note: Scriban already bumped to 7.2.5 by PR #137). MCP PR #76 (#58) still
+   needs its rebase/refresh pass — good parallel track.
+1. #90 rebrand ← PROMPT above (small, mechanical; strongest v26.4.0 tag point at its merge).
+2. #91 cutover (+ tag v26.4.0 at the latest here — see RELEASE CHECKPOINT).
+Cross-refs: #66/#67 remain open image-pipeline nice-to-haves; #68 unblocked-independent.
+Done recently: PR #136 (#89 Channel Builder), **PR #138 (#93 Settings — closed 2026-07-07,
+main 17f49304; web tests 112 → 145, ErsatzTV.Tests 447 → 495), PR #137 (Scriban GHSA
+CI-unblock), #92 design-sync round-trip closed (docs/design-sync.md)**.