# Skin Milionář — plan of record

Status: **built and in use — all phases F0-F5 done (2026-10-01); now in the tuning stage** (the user
decides changes one by one). All questions are decided (`900-decisions.md`). The roadmap is
`130-roadmap.md`; the board below is where an agent picks up the work.

This directory is the plan of record for `skin.milionar`, a full Kodi skin
forked from Estuary (Kodi 21.3 Omega) that ships inside the addon and puts
every part of Milionář one press away from Home. It was built in discussion
with the user; update a chapter when a decision lands, and let code comments
own the implementation detail once code exists.

Latest tuning (2026-10-12): unified sidebar activation and three classic-list
entry points for Filmy/Seriály/Vinyl (widgets only after user comparison); action widgets default last without
replacing existing layouts. See `050-home.md` §2 and `900-decisions.md`.
Collapsing Home sidebar (2026-10-12): icons-only rail while the focus is in the content, `230-sidebar.md`.
Second skin (2026-10-15): `skin.milionar.modern`, the modern glass look composed over this skin on the device,
selectable in the addon settings, `240-modern.md`.
Update check (2026-10-15): settings menu → "Zkontrolovat aktualizace", window 1124, Kodi installs; never in the
workspace, `250-update.md`.

## Current state (2026-10-01)

skin.milionar **1.3.1** is installed (dev symlink `addons/skin.milionar` →
`resources/skin.milionar`) and active in the user's Kodi. What exists and how it
was built (details in the chapters named):

- **Fork** of Estuary 4.0.0 (tag `21.3-Omega`), changed only where 030 §4 lists;
  `baseline.py difftree` = 23 files differ, 0 outside the list (030 §6).
- **Installer** in the service: copy, enable, offer switch once per addon
  version, `ReloadSkin()` on skin updates; all four install tests passed (040 §8).
- **Home**: menu Pokračovat, MyTV, MyCinema, Filmy, Seriály, Milionář, AI
  doporučení, (Kraska), TMDb / ČSFD, Videa, Doplňky with widget rows from the
  addon; settings button opens a menu; skin settings section "Milionář" (050 §6).
  **Kraska is hidden by default** (`MilionarDefaultsV2`, 2026-10-01) because the
  Stream Cinema API answers 404; it can be switched on in skin settings.
- **Widgets**: cache-based endpoints through the `main.py` fast path, 50-130 ms
  per row, service refresher for network rows, invalidation hooks (060 §7).
- **Search window 1120** with TMDb multi-search, library rows and history (070 §4).
- **Library integration**: "Milionář" button in the video info dialog (window
  1121) and a context menu entry in every skin (080 §4).
- **Harness** for this work: native 2560x1440 captures, `skin` / `reload` /
  `window` / `jsonrpc` / `log` commands, `scripts/skin_harness/` (100 §6).
- **Documentation of the finished feature**: `docs/features/012-skin-milionar.md`.

Next work: **`docs/plan/milionar-library/`** (the addon takes over the Kodi video library functions; L0 + L1 + L2 built 2026-10-01 (L2: next-episode logic and autoplay of the next episode / collection offer for every addon play): SQLite store `library.db`, TMDb cache, canonical play URLs `mplay`, a service tracker saving resume / watched state of every addon play (not MyTV / MyCinema), mirror into Kodi; My movies / My series live in the store, the old functions are wrappers; nothing in skin.milionar reads this data yet — that is L3/L4).

Open items: Kraska rows empty while the API is down; live-unverified were
`lib_resume`, "Hledat zdroje" end to end and clicking persons in search results;
the first fresh install from a `/deploy` ZIP is untested. The user's Videa menu
item is switched off in their skin settings (`HomeMenuNoVideosButton`), not by
design.

Working agreements made during the build: the full baseline compare is never
run on its own (only targeted checks of what changed, a full run only when the
user asks); main menu icons come from Estuary's `icons/sidemenu` set, nothing
is drawn; Pokračovat is the first menu item (050 §2).

## Follow-up plan (2026-10-01)

The addon's own library (My movies / My series, watched and resume state,
Continue, next episode across seasons, autoplay, slot-based Home rows, one
context menu) is planned in `docs/plan/milionar-library/`. It changes parts
of this skin (Continue rows, search rows 4–5, game picker, info button, widget
switches); its chapter 090 lists each touchpoint.

## Start here: the board (2026-10-01)

An agent handed this directory reads `AGENTS.md`, this file, then the row it
takes and the chapters that row names. Rows are in the order to do them.

| # | Task | Status | Blocked on / next step | Where |
|---|------|--------|------------------------|-------|
| F0 | Skin harness: native captures, window/skin/reload ops, Estuary baseline set | **done** (71 screens, 0 px diff) | — | 100 §6 |
| F1 | Fork Estuary 21.3 into `resources/skin.milionar/`, branding, installer in the service | **done** (install tests 1-4 passed) | — | 030 §6, 040 §8 |
| F2 | Home: Milionář menu items, top bar (settings menu, search), skin settings, widget endpoints | **done** (user OK 2026-10-01) | Kraska API 404 (external) | 050 §6, 060 §7 |
| F3 | Search window | **done** (user OK 2026-10-01) | — | 070 §4 |
| F4 | Library integration: info dialog button + context menu | **done** (user OK 2026-10-01) | — | 080 §4 |
| F5 | Acceptance and docs (`docs/features/012-skin-milionar.md`) | **done** (doc written; no full compare by decision) | — | 120 §4 |

Statuses: **done**, **ready** (fully specified; build it), **blocked** (on
what). The original plan is fully built; from here the user directs changes
("Current state" above lists what is open). Record each new decision in
`900-decisions.md` and the chapter it changes.

## Rules for an agent continuing this work

1. **Build what the chapters specify; do not reopen decisions.** If a fact
   found during implementation contradicts a decision, stop and ask the user
   with the question tool (options, recommendation), then record the answer
   in `900-decisions.md` and the chapter. Hand off after every phase with
   what to test; the next phase starts only after the user's OK.
2. **Live Kodi is the truth.** Every visible change is captured from the
   running Kodi and compared against the Estuary baseline (100, 120). Reading
   XML is not verification.
3. **Estuary 1:1.** Anything this plan does not explicitly change must render
   pixel-identical to Estuary 21.3 under the same data (120 §2).
4. **No regressions in the addon.** The addon keeps working with Estuary and
   any other skin; everything the skin needs from the addon is additive.
5. `service.py` changes need a Kodi restart (`kodi_live.py restart`); skin XML
   needs `ReloadSkin()` (`kodi_live.py reload`, built in F0); addon dialog XML
   and plugin Python reload on the next open.
6. After every phase update its chapter ("Result" with numbers and image
   paths), the roadmap row, and this board. No commits unless the user asks.
7. Chat in Czech, briefly; everything in the repository in English.
8. The skill `kodi-skin` holds the working rules for skin files; keep it in
   sync with what this plan learns.

## Tools for this work

| Command | Shows |
|---------|-------|
| `python3 scripts/dialog_harness/kodi_live.py status` | Kodi, listener, GUI size, current window |
| `kodi_live.py skin estuary\|milionar` (F0) | switch the active skin, auto-confirm "keep skin" |
| `kodi_live.py reload` (F0) | `ReloadSkin()` and a log check for skin errors |
| `kodi_live.py window <name> --native` (F0) | open a Kodi window, capture at native 2560x1440 |
| `python3 scripts/skin_harness/baseline.py capture\|compare` (F0) | the screen set under both skins, pixel diff report |
| `kodi_live.py open action=... --run`, `keys`, `shot`, `info` | existing: drive the addon and capture |
| `scripts/dialog_harness/compare_images.py` | existing: pixel metrics, side-by-side, diff |
| `~/Library/Logs/kodi.log` | skin XML errors, plugin timings (skill `kodi-debug`) |

## Goal

- A complete Kodi skin, `skin.milionar`, that **looks and behaves like
  Estuary 21.3** everywhere except where this plan says otherwise.
- **Home is built around Milionář**: MyTV, MyCinema, Continue watching,
  Milionář game, AI, Kraska, TMDb/ČSFD sit at the top of the main menu with
  their own widget rows; the library, videos and addons stay.
- **Top bar**: power as Estuary; settings opens a menu (Kodi / Skin /
  Milionář settings); search opens the addon's new search window (movies,
  series, people, library, history in one search).
- **Library items reach the addon**: a Milionář action in the video info
  dialog and in the context menu (source search, game, similar, add to
  MyTV/MyCinema).
- **Ships inside the addon**: installing or updating the addon installs or
  updates the skin and offers to switch to it.

## Locked decisions

These must not drift without updating this file (decided 2026-09-30):

1. **Architecture A.** A real skin addon `skin.milionar` (fork of Estuary
   4.0.0 from `xbmc/xbmc` tag `21.3-Omega`), not a full-screen window inside
   the plugin. The addon supplies widget content and actions.
2. **Bundled with the addon.** The skin source lives in
   `resources/skin.milionar/`. The addon service installs or updates it into
   `special://home/addons/skin.milionar` and asks to switch (040).
3. **Asking to switch:** on the first install **and after every addon update**
   while the skin is not active (040 §4).
4. **Look: Estuary 1:1 + Home.** No restyling; new elements reuse Estuary
   includes (`DialogBackgroundCommons`, `ButtonMenuList`, `IconButton`,
   `WidgetListPoster`, `InfoDialogButton`, …). The addon's own dialogs keep
   their current XML (`resources/skins/Default/`). Estuary's font set is not
   extended (010 §5).
5. **Branding:** id `skin.milionar`, name "Milionář", Milionář logo instead of
   the Kodi logo on Home, own icon and fanart; Estuary licence and credits
   kept (030 §3).
6. **Main menu:** Pokračovat, MyTV, MyCinema first (amended 2026-10-01: Pokračovat first); Movies, TV shows, Videos, Add-ons
   stay; Kraska is off by default (amended 2026-10-01); Music, Music videos, TV, Radio, Pictures, Games, Weather, Favourites
   are hidden by default and can be enabled in skin settings (050 §2).
7. **Everything optional:** every Milionář menu item and widget row has a
   skin setting, **on by default** (050 §5).
8. **Widgets as in 050 §3** (approved table).
9. **Search:** keyboard + OK (Estuary keyboard), then a results window with
   rows Movies, Series, People, In my library, Search history (070).
10. **Library integration:** info dialog **and** `kodi.context.item` in the
    addon (the context menu also works in other skins) with Search sources,
    Milionář game, Similar, Add to MyTV/MyCinema (080).
11. **Resolution stays 2560x1440.** Comparisons run on native 2560x1440
    captures, fork against Estuary under identical conditions (100 §2).
12. **Phased delivery F0–F5** with the user's test after every phase (130).
13. **Baseline covers everything**: playback screens with a local ffmpeg test
    video, and all 9 Videos views for movies and TV shows (120 §2).
14. **Kodi icon stays in dialog headers**; the Home logo is a Milionář
    wordmark built from the addon icon (030 §3).
15. **Icons are Estuary's own** (mapping in 050 §2); nothing is drawn.
16. **Milionář menu item** opens a topic picker (050 §4a).
17. **MyCinema recommendations** come from the films in the user's cinemas;
    **AI recommendations** get a new history store (060 §5–6).
18. **Info dialog gets one "Milionář" button** with an action menu (080 §2).

## Chapters

| File | Topic | Status |
|------|-------|--------|
| [010-current-state.md](010-current-state.md) | Audit of the addon, its library integration, UI and tooling before this work | done |
| [020-architecture.md](020-architecture.md) | Layers, file layout, how Kodi resolves windows, what the addon provides | approved |
| [030-fork.md](030-fork.md) | Forking Estuary 21.3: source, renames, branding, licence, what may change | approved |
| [040-install-update.md](040-install-update.md) | Service installer: copy, register, enable, ask, switch; dev symlink; uninstall | approved |
| [050-home.md](050-home.md) | Home: main menu, widget rows, top bar, settings menu, skin settings | approved |
| [060-widgets.md](060-widgets.md) | Plugin widget endpoints: fast entry, cache, refresh, item format | approved |
| [070-search.md](070-search.md) | Search window | approved |
| [080-library-actions.md](080-library-actions.md) | Info dialog button, context menu, new router actions | approved |
| [100-harness.md](100-harness.md) | Harness extensions for skin work | approved |
| [120-verification.md](120-verification.md) | Baseline, regression compare, per-phase checks, acceptance | approved |
| [130-roadmap.md](130-roadmap.md) | Phases F0–F5 with exit criteria | approved |
| [160-vinyl.md](160-vinyl.md) | Vinyl menu, account, music sources and widget refresh | implemented, targeted live checks passed |
| [170-context-manager.md](170-context-manager.md) | Per-widget menus, inherited lists, Vinyl/channel edits and Home shortcuts | implemented, targeted checks passed |
| [180-branding-accent.md](180-branding-accent.md) | Unified branding and six accent colours | targeted verification passed |
| [190-cinema.md](190-cinema.md) | Cinematic Filmy and Seriály sections: backdrop, hero of the selected title, card rows | built 2026-10-05; Filmy accepted, Seriály awaiting the user's test |
| [200-detail.md](200-detail.md) | Pinned media detail directly on Home, cast/collection/related rows, inline seasons and Back | built 2026-10-05; targeted offline and live checks passed |
| [210-vinyl-cinema.md](210-vinyl-cinema.md) | Cinematic Vinyl, title artwork, music card styles, detail and defaults preserving widget menus | built 2026-10-06; targeted offline checks passed; rendering awaiting user test |
| [220-hero-buttons.md](220-hero-buttons.md) | Hero button manager: per-widget buttons of the hero in every cinematic section, edited like the context menu | built 2026-10-06; offline and live checks passed; awaiting the user's test |
| [900-decisions.md](900-decisions.md) | Every decision with its chapter; no open questions | complete |