led-ticker-core 2.0.0__tar.gz

led_ticker_core-2.0.0/.claude/commands/review-docs.md

@@ -0,0 +1,171 @@
+---
+description: Multi-persona panel review of the led-ticker docs site (PM, UX, prospective user, technical writer). Sonnet-powered personas in parallel; Opus synthesis in chat.
+---
+
+# Docs site panel review
+
+Review the led-ticker docs site with a four-persona panel: a product manager, a UX engineer, a moderately-technical prospective user, and a technical writer. Reviews run against a fresh **local build** of the site (`docs/site/dist/`) — the deployed site at <https://docs.ledticker.dev> sits behind Cloudflare Access, so personas Read rendered HTML files locally instead of WebFetching URLs. Bonus: this works on feature branches before any deploy lands.
+
+## Scope
+
+`$ARGUMENTS` may name a subset of personas to run — accepted tokens: `pm`, `ux`, `user`, `writer`. Examples:
+
+- `/review-docs` — all four personas + synthesis
+- `/review-docs writer ux` — only the writer + UX engineer (typical re-run after a polish PR)
+- `/review-docs writer` — single-persona run; skip synthesis, surface the writer's review directly
+
+If `$ARGUMENTS` is empty, run all four. Otherwise run only the named personas.
+
+## Step 0 — build the site
+
+Before dispatching any persona, run `make docs-build` from the repo root to ensure `docs/site/dist/` is fresh. Astro builds incrementally (~3 sec when nothing changed). If the build fails, halt and surface the error to the user — do NOT proceed with a stale or missing dist, and do NOT have personas read source MDX as a fallback (the synthesis depends on rendered output for the user-persona review and on consistent file paths across personas).
+
+```bash
+make docs-build
+```
+
+Confirm the build succeeded by checking that `docs/site/dist/index.html` exists. If `make docs-build` errors out for environment reasons (missing pnpm, etc.), surface the actual error rather than retrying — the build is a real prerequisite, not a soft check.
+
+## Dispatch
+
+Spawn the chosen personas as parallel `Agent` calls in a SINGLE message (multiple Agent tool uses → genuine parallelism). Each call uses:
+
+- `subagent_type: "general-purpose"`
+- `model: "sonnet"` — these are scoped lens-based reads; Sonnet handles them fine and the cost matters when this gets re-run
+- `description`: short label like `"PM docs review"`
+- `prompt`: the verbatim persona prompt below
+
+After all dispatched personas return, do the synthesis pass YOURSELF in this conversation (you're on Opus). Don't dispatch synthesis as a fifth agent — the personas' reviews are already loaded in your context, and synthesis is exactly the cross-persona pattern matching + bumper-sticker thesis judgment that earns Opus's cost. Skip the synthesis section if only one persona was requested.
+
+## Path mapping
+
+Personas read rendered HTML from `docs/site/dist/` using the Read tool. URL → file path mapping:
+
+| URL | File path |
+|---|---|
+| `/` | `docs/site/dist/index.html` |
+| `/getting-started/` | `docs/site/dist/getting-started/index.html` |
+| `/widgets/message/` | `docs/site/dist/widgets/message/index.html` |
+| `/concepts/fonts/` | `docs/site/dist/concepts/fonts/index.html` |
+| (any path ending `/`) | append `index.html` |
+
+The HTML files include the full Starlight chrome (sidebar, nav, theme), so personas see what a deployed visitor would see — minus the actual hosting URL. Internal `<a href="/widgets/message/">` links don't auto-navigate; personas follow them by reading the next file's path.
+
+---
+
+## Persona 1 — Product manager
+
+```
+You're a product manager evaluating whether the led-ticker docs site converts a curious developer into someone who has built + deployed their first sign within an hour. The site is built locally at docs/site/dist/ — read rendered HTML files with the Read tool (the deployed site isn't public).
+
+Walk this journey, in order, using Read:
+1. docs/site/dist/index.html              (homepage)
+2. docs/site/dist/getting-started/index.html
+3. docs/site/dist/hardware/smallsign/index.html  (or hardware/building-your-own/ if that reads as more on-ramp-y)
+4. docs/site/dist/widgets/message/index.html
+5. docs/site/dist/reference/cli/index.html
+
+After each page, jot what a curious developer would take away vs. what they'd still be unsure about. Then return a single review:
+
+- **First impression** (2-3 sentences). What's the dominant feeling — capable / overwhelmed / curious / lost?
+- **Findings** (5-7). For each: severity (showstopper / important / nice-to-have), the page (use URL form like `/widgets/message/` for readability), what's wrong from a conversion-funnel POV (not "this paragraph is unclear" — "a developer at this point would not know whether to buy panels or run the renderer first"), and a concrete suggestion (one sentence).
+- **Friction inventory.** List the moments in the journey where a developer would stall, close the tab, or open Reddit to ask.
+- **Ship-readiness call.** One of: "ready to share with the developer crowd as-is", "polish before sharing widely", or "would lose users in current state". One sentence justifying.
+
+If you found nothing in a category, explicitly say "No findings in this lane" rather than inflating. The synthesis step downstream will weight your honest call against three other personas, so soft-positive feedback hurts more than it helps.
+```
+
+## Persona 2 — UX engineer
+
+```
+You're a UX engineer doing an IA + scannability audit of the led-ticker docs site. The site is built locally at docs/site/dist/ — read rendered HTML files with the Read tool (the deployed site isn't public). The HTML includes the full Starlight chrome (sidebar, nav, theme), so what you see is what a visitor sees.
+
+Walk the site like a UX engineer would — meaning: do the sidebar walk first (read `docs/site/dist/index.html` and skim the nav structure, then walk top-level pages from each sidebar group), then go deep on three pages of varied type. URL form like `/widgets/message/` corresponds to `docs/site/dist/widgets/message/index.html`.
+
+Lens specifically:
+- **Sidebar IA.** Does the grouping match how the user thinks about the product? Are categories the right size (3-15 items)? Anything that should be promoted to a top-level item, or demoted into a subgroup?
+- **Page structure consistency.** Pick three pages from different sections. Do their headings follow the same pattern? Do components (tables, callouts, code blocks, related-pages clusters) appear in similar positions?
+- **Scannability.** Could someone in a hurry get the gist of each page from headings + bolded leads alone? Where does the prose force linear reading when a table or list would scan better?
+- **Entry-point obviousness.** Where does someone arriving at the homepage / a deep link know to go next? Are CTAs concrete or vague?
+
+Return:
+- **First impression** (2-3 sentences) on the IA + scannability story.
+- **Findings** (5-7). Severity-tagged. Page URL + concrete suggestion.
+- **Sidebar audit.** One paragraph specifically on the sidebar, with concrete rename / regroup proposals if any.
+- **Ship-readiness call.** Same scale as the PM.
+
+Don't over-weight visual polish (Starlight defaults are out of scope). Focus on structure and information flow.
+```
+
+## Persona 3 — Moderately-technical prospective user
+
+```
+You are NOT an AI reviewer in this prompt. Stay in character throughout.
+
+You're a developer who just saw led-ticker mentioned on Hacker News. You've done embedded / Raspberry Pi work before but never touched an LED matrix panel. You have ~30 minutes to decide: do I want to build one of these for my office? Or move on?
+
+Three questions you want the docs to answer:
+1. Could I actually build this myself, with reasonable effort and parts cost?
+2. What does the end product look like in real life — would I be proud of it?
+3. How hard is the config? Will I be writing TOML for hours, or is it a 10-line file?
+
+The site is built locally at docs/site/dist/ — read rendered HTML files with the Read tool. The HTML includes the sidebar / nav / theme, so what you see is what a visitor sees. URL form like `/widgets/message/` maps to `docs/site/dist/widgets/message/index.html`. Internal links don't auto-navigate; follow them by reading the next file.
+
+Browse however you naturally would — start at `docs/site/dist/index.html`, follow links that look promising, abandon pages that get too dense. Don't be exhaustive — be a real visitor.
+
+Return:
+- **What you actually read** (page URLs in URL form `/like-this/`, in the order you read them).
+- **First impression** (2-3 sentences in your own voice — not in marketing-speak).
+- **Where you got hooked.** Specific pages or paragraphs that made you lean in. Quote a sentence or two each.
+- **Where you got bounced or confused.** Specific moments. What would a beginner have to Google to keep going? What jargon went unexplained?
+- **The verdict.** Would you build this? Why or why not? If "no", what would it take to flip you to "yes"? If "yes", what's the first thing you'd do tomorrow?
+
+Be honest. The goal of this review is to find the gaps, not to validate the docs. If something rocks, say so once. If something stinks, say so as many times as it deserves.
+```
+
+## Persona 4 — Technical writer
+
+```
+You're a technical writer doing a copy / voice / style audit of the led-ticker docs site. The site author is specifically worried that parts may sound "AI heavy" — you should weight that concern.
+
+The site is built locally at docs/site/dist/ — read rendered HTML files with the Read tool. URL form like `/widgets/message/` maps to `docs/site/dist/widgets/message/index.html`. You may also Read the source MDX at `docs/site/src/content/docs/<slug>.mdx` if you want to verify a copy issue is in the source rather than introduced by Starlight's render.
+
+Sample 5-7 pages across types: an index page, a concept page, a widget page, a hardware page, a reference page, a tools page.
+
+Specifically scan for AI-heavy tells:
+- **Padded openers.** "This page covers…", "In this guide we'll explore…", "Let's take a look at…"
+- **Hedging language.** "It's worth noting that…", "broadly speaking", "in essence", "generally"
+- **AI-favorite vocabulary.** "comprehensive", "robust", "powerful", "seamlessly", "leverage", "unlock", "explore", "delve into", "navigate"
+- **Em-dash overuse.** Em-dashes are a fingerprint when used to splice every sentence into two clauses.
+- **Mechanical parallel structure.** Three-bullet lists where each bullet starts with the same gerund or imperative and feels rhythmically generated rather than written.
+- **Listicles where prose would flow.** A bullet list of three short items often reads more naturally as one sentence.
+- **Sentences that could be phrases. Phrases that could be words.**
+
+Also check:
+- **Voice consistency.** Does the same author appear to have written every page, or do voices drift?
+- **Cognitive load.** Where does a sentence carry too many subclauses? Where do paragraphs run too long without a paragraph break to breathe?
+- **Headings earning their weight.** Are H2s/H3s descriptive, or generic ("Overview", "Usage", "Notes")?
+
+Return:
+- **AI-heaviness heat map.** 3-5 specific paragraphs you think read most AI-ish, with the page URL + the original paragraph + a concrete rewrite. The rewrite is the deliverable — "this could be tighter" without showing how is not useful.
+- **Voice consistency note.** One paragraph: do the pages sound like one writer, or many? Where are the seams?
+- **Five general rewrites.** Pick five sentences from anywhere on the site that exemplify a fixable copy issue. Original + rewrite + one-line reason.
+- **Headings audit.** List any H2 / H3 you'd rename or remove.
+
+Avoid being precious. Some "AI tells" are just clear technical writing (parallel structure in API docs is fine). Flag the ones that hurt readability or make the docs sound generic, not the ones that just pattern-match.
+```
+
+---
+
+## Synthesis (when ≥2 personas ran)
+
+After the dispatched personas return, compile a single punch list directly in this conversation:
+
+1. **Convergence map.** A table: finding | personas that raised it | severity assigned by each. Items raised by ≥3 personas go to the top.
+2. **Showstopper section.** Any "would lose users" / "ship-blocker" calls, with cross-references to the personas that raised them.
+3. **Important section.** Findings raised by ≥2 personas, or one persona with high confidence.
+4. **Nice-to-have section.** Single-persona polish items.
+5. **AI-heaviness summary.** Pull the writer's heat map verbatim, plus any "felt mechanical" / "felt generic" comments from the other personas.
+6. **Recommended sequence.** If we did 3-5 follow-up PRs, what order would address the most weight first?
+
+End with one paragraph naming the convergent **thesis** across personas — what's the dominant story the panel is telling about the docs? (E.g. "structurally solid but the on-ramp is too dense" vs "well-paced but some pages drift into AI-generated voice".) That paragraph is the bumper sticker.

led_ticker_core-2.0.0/.claude/skills/creating-a-config/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: creating-a-config
+description: Use when a user wants to build, extend, or refine a led-ticker config.toml — handles "new config from scratch", "add a widget to my config", or "tune what's already there". Knows the bigsign vs smallsign tradeoffs, widget/transition catalogs, and the CLAUDE.md gotcha list.
+---
+
+# Creating a led-ticker Config
+
+You are guiding the user through building or modifying a `config/config.toml` for the led-ticker. There are three modes: **new**, **add**, **refine**.
+
+## Step 0: Detect mode
+
+Determine the user's intent:
+
+- `new` — user said "build a config" / "make a sign" / similar. OR no `config/config.toml` exists.
+- `add` — user said "add a widget" / "add a section". `config/config.toml` exists.
+- `refine` — user said "looks too small" / "too fast" / "fix the colors". `config/config.toml` exists.
+
+If ambiguous, ask:
+> "Are you starting fresh, adding to an existing config, or tuning what's already there?"
+
+Announce: "Using creating-a-config skill in **\<mode\>** mode."
+
+## TOML structure reminder (all modes)
+
+Every config has this skeleton:
+
+```toml
+[display]
+rows = 32
+cols = 64
+chain = 8
+default_scale = 4
+# ... hardware knobs
+
+[title]
+delay = 5
+
+[transitions]
+default = "push_left"
+duration = 0.5
+easing = "ease_in_out"
+between_sections = "dissolve"
+
+# Each section is an array entry:
+[[playlist.section]]
+mode = "swap"          # or "forever_scroll" or "infini_scroll"
+hold_time = 6
+loop_count = 1
+
+[playlist.section.title]   # optional title card
+type = "message"
+text = "Weather"
+color = [255, 150, 190]
+
+[[playlist.section.widget]]   # one or more widgets per section
+type = "weather.current"
+location = "Brooklyn"
+units = "imperial"
+
+[[playlist.section.widget]]   # additional widgets allowed
+type = "message"
+text = "More info"
+```
+
+The skill produces configs in THIS structure. Never use top-level `[section_name]` headers in place of `[[playlist.section]]`.
+
+---
+
+## `new` mode (3-phase wizard)
+
+### Phase 1: Outline
+
+Load `references/hardware-guide.md`.
+
+Ask these 7 questions, one at a time. Use multi-choice format where listed.
+
+1. **Sign target:** small (160×16) / bigsign (256×64)
+   *(Note: "both" is reserved for future parallel-config support; if the user picks both, explain that's not yet supported and ask them to pick one.)*
+2. **Use case category:** store window / personal feed / event countdown / sports scoreboard / art piece / mixed
+3. **Viewing distance:** close (≤6ft) / medium (6–20ft) / far (20ft+)
+   *(Drives default font sizes — consult `references/hardware-guide.md` distance table.)*
+4. **Content sources** (multi-select): rss / weather / custom messages / gifs+images / sports / crypto / countdown
+5. **Brand presence:** none / colors only / colors+fonts / colors+fonts+logo
+6. **Tone:** minimal / playful / info-dense / branded-pro
+7. **Cadence:** always-on continuous loop / scheduled windows
+
+After all 7 answers, propose a section list. Load `references/snippets.md`; look up snippets keyed by (use_case × content_source × sign_target); produce one section per content source. Present to the user as section names with widgets, e.g.:
+
+```
+Proposed sections:
+  Section 1 (mode=forever_scroll):  welcome banner — message widget
+  Section 2 (mode=swap):            weather — weather widget
+  Section 3 (mode=swap):            handle — two_row widget
+  Section 4 (mode=swap):            hours countdown — countdown widget
+```
+
+User confirms or edits the list (add / remove / reorder).
+
+### Phase 2: Per-section pass
+
+Load `references/snippets.md`, `references/widget-selection.md`, `references/asset-handling.md`, `references/decision-rules.md`. For each chosen widget's options (field names, types, defaults), read its fact-pack `docs/content-source/widgets/<type>.md` — that is the source of truth for params; author TOML from it.
+
+**Brand font defaults (carried across all sections):**
+
+If Phase 1 brand presence was `colors+fonts` or `colors+fonts+logo`, the user has already named one or more font files (collected per `references/asset-handling.md`). Pick a per-tier default font_size from the asset-handling viewing-distance table BEFORE entering the per-section loop, e.g. medium-distance bigsign + Inter-Bold → 22. Use this as the default for every text-bearing widget (message, countdown, two_row, weather, image/gif overlay text, plus `[playlist.section.title]` blocks). Don't re-ask per section.
+
+Sections-pass loop — for each confirmed section in the outline:
+
+1. Look up the snippet matching (use_case × widget × sign_target) in `references/snippets.md`.
+2. Ask only the widget-specific questions the snippet's "must customize" list requires. Use AskUserQuestion. **If the user picked a custom brand font in Phase 1, also append `font` / `font_size` / `font_threshold` to every text-bearing widget in this section even if the snippet's must-customize list omits them** — the snippets are pre-fonts and need the brand applied.
+3. For asset-bearing sections (gif, image, custom font): collect assets per `references/asset-handling.md`. Place fonts in `config/fonts/<file>` and images in `config/assets/<file>`. Verify the path exists before referencing it in TOML. Never fetch URLs silently.
+4. Write the section's TOML to the in-progress config buffer using the `[[playlist.section]]` / `[[playlist.section.widget]]` structure. If the section has a `[playlist.section.title]` and brand fonts are in play, apply the brand font to the title too.
+5. Run per-section lint: run `led-ticker validate config/config.toml --json` and surface any `errors` or `warnings` from the output as flag-and-ask items, citing each `rule` and `fix` field. Then check font-size vs viewing distance (see step 5a below) and any remaining issues from `references/decision-rules.md` not caught by the validator.
+
+   **Additionally** check font-size vs viewing distance: if Phase 1 distance was `medium` and the user picked a `font_size ≥ 24`, OR distance was `far` and `font_size < 22`, flag with: "Phase 1 distance was <X>; recommended `font_size` is <range>; you picked <N>. Want me to align with the recommendation?" Cite `references/asset-handling.md` viewing-distance table.
+
+6. Brief "looks good?" before moving to the next section.
+
+### Phase 3: Polish
+
+Load `references/transition-selection.md`, `references/decision-rules.md`. For each transition family's catalog and tuning (durations, easing, sweep colors), read its fact-pack `docs/content-source/transitions/<family>.md` (`push`, `wipe`, `sprite`, `special`).
+
+Ask these questions (5–7 total, condensed where possible):
+
+1. **Default transition + duration + easing** — offer 3 picks based on Phase 1 tone. Consult the "Selecting a transition" table in `references/transition-selection.md`:
+   - Minimal → `cut` or `wipe_left`
+   - Playful → `nyancat.alternating` or `pokeball.alternating`
+   - Info-dense → `push_up` or `wipe_up`
+   - Branded-pro → `wipe_alternating` with `transition_color` from the brand palette
+2. **`between_sections` transition** — usually different from the default; suggest `dissolve` for branded-pro, `cut` for minimal.
+3. **Default `hold_time`** — defaults: continuous loop → 5s, scheduled windows → 10s.
+4. **Brightness** — defaults: small=60, bigsign=60; ask if user wants different.
+5. **Bigsign refresh tuning** — only ask if sign=bigsign AND tone=info-dense. Suggest `pwm_bits = 8` — the RIO backend is the library default, no knob needed (consult `references/hardware-guide.md` refresh tuning notes).
+6. **Save destination** — propose `config/config.<descriptive-slug>.toml` based on Phase 1 answers (e.g. `firebird-bigsign`, `office-rss-small`); ask if user wants to override. After write, ask: "Activate this as the live config? (copies to `config/config.toml`, backs up any existing to `config/config.toml.bak`)"
+
+Run final validation: run `led-ticker validate config/config.toml --json`. Surface all `errors` as mandatory fixes and `warnings` as flag-and-ask before writing. Also do a full pass over `references/decision-rules.md` for any issues not caught by the validator.
+
+Write the file with all three top-level blocks (`[display]`, `[title]`, `[transitions]`) plus all the `[[playlist.section]]` entries.
+
+Print:
+- Path written (and whether it is the live config or a named alternate)
+- Test command: `make test`
+- Hardware run command: `docker compose up` (verify against `Makefile` / `compose.yaml`)
+- Any flagged-but-unfixed violations from validation
+
+---
+
+## `add` mode
+
+Load `references/widget-selection.md`, `references/snippets.md`, `references/asset-handling.md`, `references/decision-rules.md`. For each chosen widget's options, read its fact-pack `docs/content-source/widgets/<type>.md` — the source of truth for params.
+
+1. Read `config/config.toml`. Extract: sign target (from `default_scale` + display dims), brand colors (from `bg_color` / common `font_color` values), default transition / hold / easing, existing sections list. Also **infer use_case** from existing widgets — e.g., presence of the `baseball.scores` / `baseball.standings` plugin widgets (`led-ticker-baseball`) → `sports`; multiple `rss.feed` + `weather.current` → `personal_feed`; a single `gif`/`image` filling the panel → `art`; mixed content with brand colors + handle → `store_window`. The inferred use_case drives snippet lookup in step 3. If you're not confident, ask the user: "I'm reading this as a <X> config — does that match?"
+2. Ask: "What kind of section do you want to add?" — multi-select from `references/widget-selection.md`.
+3. For each chosen widget: same flow as `new` Phase 2 — look up the snippet by (inferred-use_case × widget × sign) in `references/snippets.md`, ask the snippet's "must customize" questions, collect any assets, write the section TOML, run per-section lint.
+4. Ask: "Where to insert?" — end / before \<section N\> / after \<section N\>.
+5. Show full diff. First in-place edit per session creates `config/config.toml.bak` (overwrites any prior `.bak` without prompting).
+6. Apply edit only on user approval.
+
+No Phase 3 — global `[transitions]` and `hold_time` are not re-asked. The new section gets its own `transition` / `transition_color` from the chosen snippet (snippets often pin a per-section transition); for everything not set on the new section, the existing global `[transitions]` config applies.
+
+---
+
+## `refine` mode
+
+Load `references/decision-rules.md`, `references/widget-selection.md`, `references/transition-selection.md`.
+
+1. Read `config/config.toml`. Run `led-ticker validate config/config.toml --json` and cache the output as the base violation list (`errors` and `warnings` from the JSON). Also run a full pass over `references/decision-rules.md` for any issues not yet caught by the validator.
+2. Ask one symptom-style multi-select question:
+   - "Too small to read at viewing distance"
+   - "Too aggressive / busy"
+   - "Too slow / too much dead time"
+   - "Too fast / can't read it"
+   - "Wrong colors / bad contrast"
+   - "Image fit looks bad"
+   - "Border / animation feels off"
+   - "Other (free text)"
+3. For each selected symptom, map to specific deltas using this table:
+
+   | Symptom | Inspect | Propose |
+   |---------|---------|---------|
+   | Too small at far + bigsign + currently BDF | `font` field on text widgets | Hires Inter at `font_size = 24–32` (consult `references/asset-handling.md` distance table). Migrate from BDF default. |
+   | Too small + already hires | `font_size` value | Bump `font_size` up one tier (16→22, 22→28, 28→32). |
+   | Too aggressive / busy | `font_color`, `border`, transitions | Swap per-char `rainbow` → `color_cycle`. Replace `wipe_alternating` / `nyancat.alternating` → `cut` or `wipe_left`. Lengthen `hold_time` by 50%. Drop animated `border` to constant or remove. |
+   | Too slow / too much dead time | `hold_time`, `transition_duration` | Reduce `hold_time` by 30–50%. If `transition_duration > 1000`, drop to 600. Consider `cut` for inter-widget transitions. |
+   | Too fast / can't read it | `hold_time`, `transition_duration` | Raise `hold_time` by 50%. If using fast transitions (`cut`, `push_left` at 400ms), bump duration to 800ms or swap to a wipe. |
+   | Wrong colors / bad contrast | `bg_color` vs `font_color` luminance | If both colors are light or both are dark, adjust one for contrast (rough luminance heuristic: sum of RGB channels; push them apart). For brand-locked colors, propose adding a `border` for separation. |
+   | Image fit looks bad + `fit="stretch"` + non-matching aspect | `fit`, image dimensions | Propose `fit="pillarbox"` (image wider than panel) or `fit="letterbox"` (image taller than panel) per `references/asset-handling.md` decision tree. Add `image_align` if pillarboxing. |
+   | Border / animation feels off | `border.speed`, `border.char_offset`, `border.thickness`, `animation` | If border feels too fast: lower `speed` (default 4 on bigsign; try 2). Too uniform: raise `char_offset`. Too thin from far: increase `thickness` from 1 to 2. Typewriter feels off-pace: tune `frames_per_char` (default 3; raise for slower reveal). |
+
+4. After addressing stated symptoms, surface the step-1 violation list as flag-and-ask. Each item: "I also noticed: \<rule violation\> (severity) — want me to fix? Per `references/decision-rules.md` rule N."
+5. Show each proposed delta as a unified diff. User approves per delta.
+6. Apply approved edits. First in-place edit per session backs up to `config/config.toml.bak` (overwrites any prior `.bak` without prompting).
+
+---
+
+## Validation: flag-and-ask philosophy
+
+The skill **never silently auto-fixes a violation.** Every flag is presented to the user with the rule cited (`per references/decision-rules.md rule N`). The user decides whether to apply the fix. This applies in all three modes at all three checkpoints:
+
+1. Per-section lint (Phase 2 of `new`, or per-section in `add`)
+2. Phase 3 final validation (assembled config, `new` mode only)
+3. Symptom + catch-all flag-and-ask (`refine` mode)

led_ticker_core-2.0.0/.claude/skills/creating-a-config/references/asset-handling.md

@@ -0,0 +1,101 @@
+<!-- Derived from CLAUDE.md sections: "Hi-res fonts on the bigsign", "Per-widget font_threshold", "Match thresholds within a font family", "Inline Emoji", "GIF widget and Still-image widget". Last synced: 2026-05-07. -->
+
+# Asset Handling Playbook
+
+## Brand colors (hex → RGB)
+
+The skill solicits hex codes (e.g. `#E5306C`) and converts to `[r,g,b]` lists.
+
+**Application sites table:**
+
+| Brand role | TOML field |
+|-----------|------------|
+| Background tone (per-section bg) | `bg_color` |
+| Background tone (per-row band on TwoRow / image) | `top_bg_color` / `bottom_bg_color` |
+| Primary text | `font_color` |
+| Per-row text (TwoRow / image two-row mode) | `top_color` / `bottom_color` |
+| Accent / highlight | per-char `gradient` `from`/`to`, or constant on a single section |
+| Transition flash | `transition_color` |
+| Border | `border = [r,g,b]` (constant) or `border = {style="constant", color=[r,g,b]}` |
+
+## Custom fonts
+
+**Placement:** `config/fonts/<file>` (flat directory; no family subdir). Files are gitignored — they don't go in the repo.
+
+**Font size by viewing distance** (bigsign):
+
+| Distance | Inter-Regular | Inter-Bold | Beloved Sans Regular | Beloved Sans Bold |
+|----------|---------------|------------|----------------------|-------------------|
+| Close (≤6 ft) | 16 | 16 | 18 | 18 |
+| Medium (6–20 ft) | 22 | 22 | 24 | 24 |
+| Far (20 ft+) | 28 | 28 | 32 | 32 |
+
+**Threshold rule (CRITICAL):** Within a font family, Bold weights MUST use the same `font_threshold` as Regular so weight contrast survives. E.g.:
+
+```toml
+# CORRECT — weight contrast survives
+[hello]
+font = "Beloved-Sans-Regular"
+font_size = 24
+font_threshold = 80
+
+[hello_bold]
+font = "Beloved-Sans-Bold"
+font_size = 24
+font_threshold = 80   # same as Regular
+
+# WRONG — Bold appears thinner than Regular!
+[hello]
+font_threshold = 80
+
+[hello_bold]
+font_threshold = 128  # default — inverts weight contrast
+```
+
+**Threshold defaults:**
+- Inter family at any size: 128 (default)
+- Beloved Sans Regular at 24-32: 80 (thin strokes need lower threshold)
+- Beloved Sans Bold paired with above: 80 (match Regular)
+
+**Type:** must be `int` 0-255. Floats and bools are rejected.
+
+## Images / GIFs
+
+**Placement:** `config/assets/<file>`. The repository ships two CC0 sample-media families: the Firebird **phoenix** (`phoenix.gif`, `phoenix_transparent.gif`, `phoenix.png`, `phoenix_transparent.png`, `phoenix.webp`), derived via `tools/derive_phoenix_assets.py`; and the **pride** rainbow assets (`pride.gif`, `pride_trans.gif`, `pride.png`, `pride_trans.png`), project-generated CC0 derived via `tools/derive_pride_assets.py` (`make derive-pride`). Both families are documented in `config/assets/ATTRIBUTION.md`. For real-brand / customer-IP / third-party media (logos, band photos, product images), the convention is to NOT commit them — users drop their own assets into `config/assets/` locally. If you need to ship custom assets with a deployment, use a tar.gz bundle alongside the example config: extract on the Pi, override the live config. See the Firebird example config for the pattern.
+
+**Fit-mode decision tree:**
+
+1. Image aspect matches panel aspect (ratio within ±10%) → `fit = "stretch"` is fine; `fit = "pillarbox"` works too.
+2. Image is taller than panel aspect → `fit = "letterbox"` (black bars top/bottom).
+3. Image is wider than panel aspect → `fit = "pillarbox"` (black bars left/right). Use `image_align = "left" | "center" | "right"` to anchor.
+4. Image needs to fill the panel and aspect doesn't matter → `fit = "crop"`.
+5. Image has transparent regions and you want text to walk "behind" the silhouette → any fit EXCEPT stretch (stretch leaves no transparent regions).
+
+**Scroll layering** (`text_align` for marquees over images):
+
+- `text_align = "scroll"` — text drawn first, image painted on top with skip-black. Text walks BEHIND the image silhouette and is exposed only through transparent / black regions. Use with RGBA images that have meaningful alpha (logos, sprites). Don't use with opaque RGB photos — text will be hidden.
+- `text_align = "scroll_over"` — image painted first, text drawn on top. Text walks IN FRONT, always visible regardless of image content. Use with opaque images (dance video, photos) where there's nothing transparent to peek through, OR when you want guaranteed legibility.
+- `text_align = "auto"` — resolves based on `image_align`: `left` → text starts on right, `right` → starts on left, `center` → `scroll_over`. Good when you don't want to think about it.
+
+**Two-row text overlay decision:**
+- One line of text → use single-row knobs (`text`, `text_align`, `text_valign`, `font_size`).
+- Two lines (top held + bottom scrolling) → set `bottom_text` to switch to two-row mode. Single-row knobs are then refused.
+
+**Hold time / loops:**
+- Still image: `hold_time` (default 5).
+- GIF: `gif_loops` (default 1) × native frame durations.
+- With `text_loops > 0` on either: `hold_time` becomes a duration FLOOR; the source extends to fit the marquee.
+
+## URLs and handles
+
+| User says | Lands as |
+|-----------|----------|
+| "Instagram @handle" | `:instagram: @handle` in `two_row.bottom_text` |
+| "Email me@example.com" | `:email: me@example.com` in `two_row.bottom_text` |
+| "Weather in Brooklyn" | `weather.current` widget with `location = "Brooklyn, NY"` |
+| "RSS feed at <url>" | `rss.feed` widget with `feed_url = "<url>"` |
+| "Mets fan" | `baseball.scores` widget with `team = "NYM"` (needs the `led-ticker-baseball` plugin) |
+| "BTC price" | `crypto.coingecko` widget (via `led-ticker-crypto` plugin) with `symbol_id = "bitcoin"`, `symbol = "BTC"`, `currency = "USD"` |
+| "Countdown to <date>" | `[countdown]` widget with `date = "<YYYY-MM-DD>"` |
+
+**No silent network fetches.** If user gives an asset URL, the skill asks them to download and provide the local path.