Spec: Settee rebrand, Home, Up Next, watch progress, per-Profile Favourites and search

The issue describes a broad Settee rebrand and many connected features, but names no source files or tests. Start by reading the repository structure and its existing app entry points, then identify a single feature with its owner before taking work. Done would require the scoped change to meet its stated user stories while preserving the existing features.

Problem Statement

I watch movies and series on a Fire TV Stick with an app forked from OpenTV, a project that has since been abandoned. It plays well, but keeping track of what I'm watching is hard:

• I can mark movies and series as Favourites, but there is nowhere to see them.
• A series' episode list doesn't show which episodes I've Watched, so I can't tell where I left off.
• When I finish an episode, the series disappears from Continue Watching instead of offering the next episode.
• There is no Home screen: the app opens on the Live TV guide, and my Favourites and unfinished shows are buried in separate tabs.
• Everyone on the Fire Stick shares one Favourites list, even though each Profile has its own watch progress.
• Search uses the app's own on-screen keyboard, so I can't use the Fire TV remote's voice dictation, and it doesn't remember what I searched for.

The app still carries the original project's name, links, donation buttons and update channel, so it isn't really mine to develop and install.

Solution

Rebrand the app as Settee (uk.neutraltone.settee), my own app in my own repo, installed on the Fire Stick through the Downloader app and kept up to date by its built-in updater. Then build the features around what each Profile is watching:

• Home, the screen the app always opens on (after "Who's watching?" when there is more than one Profile). It shows:
  • a Live Preview of the last channel, when live TV was the Profile's most recent playback
  • Continue Watching, with one card per series showing its In Progress episode or its Up Next
  • rows of Favourite Shows, Favourite Movies and Favourite Channels
• Watched, In Progress and Unwatched shown on every episode, with thumbnails, badges and progress bars. The series page opens on a main button that resumes or plays the right episode.
• Up Next: finishing an episode puts the following one in Continue Watching. When the provider adds a new season, the series comes back with a "New episode" label.
• Favourites per Profile, with a Favourites row on Home and at the top of the Movies and Shows tabs.
• An options panel on the remote's Menu button (or holding Select): Mark watched/unwatched, Remove from Continue Watching, Add/remove Favourite.
• The device's own keyboard in place of the app's keyboard, so Fire TV voice dictation and Gboard's mic work. Search also remembers each Profile's Recent Searches.

User Stories

Rebrand and repo

1. As the owner, I want the app to be called Settee everywhere I see it (launcher, About screen, update prompts), so that it is clearly my app and not the abandoned OpenTV.
2. As the owner, I want Settee to install as a separate app from OpenTV, so that I can set it up while OpenTV is still on the Fire Stick and uninstall OpenTV when I'm happy.
3. As the owner, I want the project in its own public repo with the full history, and the old fork archived, so that it is no longer tied to the original project.
4. As the owner, I want the About screen to say Settee is based on OpenTV and keep the GPL licence, so that the original authors are credited and the licence is respected.
5. As the owner, I want every donation link, public issue template, install website and link to the original project's services removed, so that nothing points people at a project that no longer exists.
6. As the owner, I want every existing feature (sync, recordings, Stalker, Stremio, parental controls, translations) kept working, so that the rebrand costs me nothing I use.
7. As the owner, I want each release to publish a fixed-name settee.apk at a link that always serves the latest version, so that a Downloader short code installs Settee on a new Fire Stick.
8. As the owner, I want the built-in updater to check my repo's releases, so that updating the Fire Stick is a single "Update" press.
9. As the owner, I want releases signed with a real, backed-up key, so that every update installs over the previous version.
10. As the owner, I want the version to start at 0.1.0, with Android's version code worked out from the version name, so that a release only bumps the version in one place.
11. As the owner, I want commits in the form type(#issue): description, checked by a commit hook and a check on PR titles, so that the history and changelog stay consistent.
12. As the owner, I want release-please to collect merged work into a release PR that I merge when I want to ship, so that half-finished work never reaches the Fire Stick.
13. As the owner, I want the database to start fresh at version 1 without the original project's migrations, so that the schema carries no history I don't need.

Profiles

14. As a household member, I want to be asked "Who's watching?" when the app starts and there is more than one Profile, so that Home shows my own things.
15. As a single viewer, I want to go straight to Home when there is only one Profile, so that I'm never asked a pointless question.

Home

16. As a viewer, I want the app to always open on Home, so that what I'm watching and my Favourites are the first things I see.
17. As a viewer whose last playback was a live channel, I want a Live Preview of that channel playing muted at the top of Home, with what's on now and next, so that I can jump back in with one press.
18. As a viewer, I want the highlight to start on the Live Preview when it is shown, so that Select goes straight back to the channel full screen with sound.
19. As a viewer whose last playback was a movie or episode, I want no Live Preview, so that Home leads with Continue Watching instead.
20. As a viewer, I want the Live Preview to stop as soon as I leave Home or play anything else, so that it never uses my provider's only stream connection for something else.
21. As a viewer on an account with one stream at a time, I want a "Live preview on Home" setting (on by default), so that I can turn the preview off when others in the house are watching.
22. As a viewer, I want Home to show Continue Watching, Favourite Shows, Favourite Movies and Favourite Channels, in that order, so that everything I care about is on one screen.
23. As a viewer, I want an empty row to be hidden, so that Home never shows blank shelves.
24. As a new Profile with nothing watched or favourited, I want a one-line hint on Home, so that I know how it will fill up.
25. As a viewer, I want the "boot to last channel" setting removed, so that there is one consistent way back into live TV.

Watch progress

26. As a viewer, I want a movie or episode to count as Watched once I've played past 93% of it, so that stopping at the end credits still counts.
27. As a viewer, I want episodes I skipped to stay Unwatched, so that the app never claims I've seen something I haven't.
28. As a viewer, I want to mark any episode or movie as Watched by hand, so that I can record things I watched elsewhere.
29. As a viewer, I want to mark a Watched episode or movie as Unwatched, so that I can undo a mistake or rewatch it.
30. As a viewer, I want marking by hand to count exactly like watching, so that Up Next follows what I marked.
31. As a viewer, I want my watch progress kept separate from other Profiles', so that someone else's viewing doesn't move my place.

Up Next and Continue Watching

32. As a viewer who has just finished an episode, I want the following episode to appear in Continue Watching as Up Next, so that I can carry on without opening the series.
33. As a viewer finishing the last episode of a season, I want Up Next to be the first episode of the next season, so that I move on to it.
34. As a viewer, I want Up Next always worked out from the episode I most recently Watched, so that skipping ahead takes my place with me.
35. As a viewer who has finished every available episode, I want the series to leave Continue Watching, so that the row only holds things I can actually watch.
36. As a viewer, I want a finished series to come back to Continue Watching with a "New episode" label when the provider adds an episode, so that I notice a new season without checking.
37. As a viewer, I want only series I've watched at least one episode of checked for new episodes, so that the app doesn't download episode lists for hundreds of series I don't care about.
38. As a viewer, I want each series to appear at most once in Continue Watching (its In Progress episode, or else its Up Next), so that the row isn't cluttered with several episodes of one show.
39. As a viewer, I want a series card to show the series name, "S2 · E4", the series artwork and a progress bar, so that I can tell at a glance what it is and how far in I am.
40. As a viewer, I want selecting a Continue Watching card to start playing straight away (resuming where I left off), so that carrying on takes one press.
41. As a viewer, I want Continue Watching ordered by when I last played each item, with a series that has a new episode placed by when it was noticed, so that what I'm into right now is first.
42. As a viewer, I want Home to show all of Continue Watching, the Movies tab only movies and the Shows tab only series, so that each tab stays on topic.
43. As a viewer, I want to remove a series from Continue Watching and have it stay hidden until I next watch an episode or a new one appears, so that I can drop a show without losing its history.
44. As a viewer, I want removing an In Progress movie or episode to clear its resume point, so that it starts from the beginning next time.

Series page

45. As a viewer, I want each episode row to show a thumbnail, so that the episode list is easier to scan.
46. As a viewer, I want an episode with no thumbnail from the provider to show the series artwork with the episode number on top, so that rows never look broken.
47. As a viewer, I want Watched episodes to show a ✓ badge, so that I can see what I've seen.
48. As a viewer, I want In Progress episodes to show a ▶ badge and a progress bar, so that I can see what I'm part-way through.
49. As a viewer, I want Unwatched episodes to show no badge, so that the badges stand out.
50. As a viewer, I want the series page's main button to say "Resume S2 E4" when an episode is In Progress, "Play S2 E5" for Up Next, and "Play S1 E1" otherwise, so that one press does the right thing.
51. As a viewer, I want the highlight to start on that main button when the page opens, so that I don't have to hunt for my place in a long episode list.

Favourites

52. As a viewer, I want my Favourites to be my own and not shared with other Profiles, so that my Home and Favourites rows reflect my taste.
53. As a viewer, I want this for channels, movies and series alike, so that Favourites behave the same everywhere.
54. As a household, I want hidden channels and channel order to stay shared across the device, so that tidying the provider's list is done once.
55. As a viewer, I want a Favourites row at the top of the Movies and Shows tabs, under Continue Watching, so that I can find my Favourites without going Home.
56. As a viewer with more than one device, I want my Favourites synced to the Profile with the same name on my other devices, so that "Tony" has the same Favourites everywhere.

Options panel

57. As a Fire TV user, I want the remote's Menu (≡) button to open an options panel for the highlighted item, so that the app follows Fire TV convention.
58. As a user of a remote without a Menu button, or of a phone, I want holding Select to open the same panel, so that the options are always reachable.
59. As a viewer, I want the panel to offer Mark watched/unwatched, Remove from Continue Watching and Add/remove Favourite, showing only the actions that apply to that item, so that the panel is short and relevant.

Keyboard and search

60. As a Fire TV user, I want text boxes to open Fire TV's own keyboard, so that I can hold the remote's mic button and dictate.
61. As an Android TV or phone user, I want text boxes to open my device's keyboard, so that Gboard's voice input works.
62. As a viewer, I want this in all four places that currently use the app's keyboard (search, profile names, channel renaming, the channel manager), so that typing works the same everywhere.
63. As a viewer, I want a search saved as a Recent Search when I open one of its results, so that half-typed words never fill the list.
64. As a viewer, I want my last 10 Recent Searches shown when the search box is empty, so that I can repeat a search in one press.
65. As a viewer, I want my Recent Searches kept separate from other Profiles', so that searches stay personal.
66. As a viewer, I want to remove one Recent Search with the Menu button, or clear them all, so that I can tidy the list.

Implementation Decisions

Rebrand

• Display name Settee. The application ID changes to uk.neutraltone.settee; the debug build keeps its .debug suffix. The Kotlin package stays app.opentv, to avoid touching every file and to keep the code easy to compare with upstream.
• Repo: a new public repo neutraltone/settee with the full history pushed. The fork neutraltone/opentv is archived. The issue tracker moves with it, so the agent docs (issue tracker, CLAUDE.md) are updated to name the new repo and drop the fork wording.
• The updater's repo name points at neutraltone/settee. The release workflow publishes settee-<tag>.apk and a fixed-name settee.apk, so releases/latest/download/settee.apk always serves the latest. The owner registers the Downloader short code by hand; that is a separate ready-for-human ticket.
• Signing: a real release key, provided to the release workflow through the repo's GitHub Actions secrets (the workflow already reads them), and backed up by the owner in 1Password. This must be in place before the first release goes on the Fire Stick.
• Removed: FUNDING.yml, the public issue templates, the GitHub Pages install site and its workflow, and the About screen's donation link, QR code and links to the upstream project. The About screen gains a "Based on OpenTV" line. The GPL licence file and per-file copyright headers stay.
• Renamed in code so that "Home" means only the new Home: the Live TV guide screen (HomeScreen) becomes LiveScreen, and the tabbed shell route (Routes.HOME) becomes Routes.MAIN.
• Versioning: versionName starts at 0.1.0, and versionCode is computed in Gradle as major×10000 + minor×100 + patch. CHANGELOG.md restarts, with one line pointing to OpenTV's history.
• Database: reset to schema version 1, deleting the old migrations and exported schemas. Until the first tagged release, wiping the data on a schema change is acceptable. From the first tagged release on, every schema change ships a hand-written migration and the wipe fallback is removed.
• Process: commits follow type(#issue): description. The issue scope is required for feat, fix, refactor and perf, and optional for docs, chore, ci, test and build; release-please's own chore(main): release x.y.z commits must pass. Enforcement is a shell commit-msg hook in .githooks/ (enabled with core.hooksPath) plus a GitHub check on PR titles. No Husky and no Node tooling. Each ticket gets its own branch and PR, squash-merged with a conventional title. release-please (a GitHub Action) keeps a release PR updated with the changelog and the version in Gradle; merging it tags the release, which triggers the existing release build.

Viewer Library (new deep module)

• A single module answers every "what has this Profile watched and kept?" question and owns every change to that state. It is wired into ServiceLocator and used by the view models; screens never query the progress, favourites or search tables directly.
• Queries (each for a given Profile, as observable streams):
  • Continue Watching, filtered to all, movies or series
  • each episode's watch status (Watched, In Progress with its progress, or Unwatched) for one series
  • the series page's main action (resume episode, Up Next episode, or first episode)
  • Favourites of each kind
  • Recent Searches
  • the Live Preview channel, or nothing
• Commands:
  • record playback progress for a movie or episode
  • record that a live channel was played
  • mark a movie or episode Watched or Unwatched
  • remove an item from Continue Watching
  • set or unset a Favourite
  • save a Recent Search, remove one, or clear them all
  • accept each series' "last updated" time from catalogue refresh
• Rules it enforces:
  • Watched means past 93%, or marked by hand. The threshold replaces the current 95% everywhere.
  • Up Next is the episode after the most recently Watched one, in (season, episode) order, crossing into the next season. Hand marks count as watching.
  • At most one Continue Watching card per series. Ordered by last activity, where a newly noticed episode counts as activity at the time it was noticed.
  • Removing a series hides it until the next playback or mark of one of its episodes, or a new episode arriving. Removing an In Progress item deletes its resume point.
  • Recent Searches: at most 10 per Profile, newest first, with a repeated term moved to the top rather than duplicated.
  • The Live Preview channel is the last live channel the Profile played, and only when live was the Profile's most recent playback of any kind.
• New-episode detection: catalogue refresh already stores each series' provider "last updated" time. When that time moves forward for a series where the Profile has Watched at least one episode, the Viewer Library asks for that series' episodes to be fetched. Episode fetching is passed into the module, so the provider client is not a dependency. New episodes then drive Up Next and the "New episode" label. Detection runs for every Profile on the device.
• Episodes stay lazily loaded. The Viewer Library may trigger a fetch, but never assumes a series' episodes are present.

Schema changes

• Favourites leave the channels, movies and series rows and move to a per-Profile favourites table keyed by Profile, item kind and the item's identity. Identity is the stream URL for channels and movies, and the provider series ID for series, so Favourites survive catalogue refreshes and match across devices. See ADR 0001. Hidden channels and channel order stay on the channel rows.
• A per-Profile Recent Searches table (Profile, search text, time).
• Per-Profile state for "last live channel played and when", "series removed from Continue Watching" and "series with a new episode, noticed when".
• Hand marks are stored as watch progress at full duration (Watched), or by deleting the progress (Unwatched), so sync carries them for free.
• No migrations are needed for these changes (pre-release, fresh database). Existing favourites are not carried over.

Sync

• The sync data's Favourites become per Profile, grouped by Profile name like watch progress, using the same identities (stream URL or series ID). Merging stays additive: a Favourite set on either device is kept. Settee devices only sync with Settee devices; compatibility with upstream OpenTV's sync data is not required.

UI

• Home is a new first tab and the start destination, after a "Who's watching?" step on launch when there are 2+ Profiles. Its rows, in order: Live Preview, Continue Watching, Favourite Shows, Favourite Movies, Favourite Channels. Empty rows are hidden; with every row empty, a one-line hint shows. The Live Preview reuses the guide's existing preview player, plays muted, starts with the highlight, and is torn down when Home leaves the screen. A "Live preview on Home" setting defaults to on. The boot-to-last-channel setting and its startup behaviour are removed.
• The Movies and Shows tabs get a Favourites row under their Continue Watching row, and their Continue Watching is filtered to their own kind.
• Continue Watching cards for series show the series name, "S2 · E4", series artwork and a progress bar (empty for Up Next), with a "New episode" label where it applies.
• Series page: the main button says Resume / Play S·E / Play S1 E1 and starts with the highlight; the page does not auto-scroll. Episode rows gain a thumbnail (falling back to series artwork with the episode number on top), a ✓ badge for Watched, and a ▶ badge with a progress bar for In Progress.
• Options panel: one shared panel, opened by the Menu key on any highlighted movie, series, episode, channel, Continue Watching card or Recent Search, and by holding Select. It lists only the actions that apply to that item.
• Keyboard: the app's own keyboard is replaced by a standard text field that opens the device's keyboard, in search, profile naming, channel renaming and the channel manager. Getting the highlight into a text box and back out with a D-pad must be checked on a Fire Stick early. The app's own keyboard component is deleted once nothing uses it.
• Search shows Recent Searches when the box is empty, and records a Recent Search when a result is opened.
• New user-facing strings are added in English only; other languages fall back to English.

Testing Decisions

• A good test drives a module through its public interface and asserts what a viewer would observe ("Up Next is S2 E1", "the series is not in Continue Watching"). It never asserts on table rows, internal flags or which private function ran. Tests read like the user stories and use the glossary's terms.

• Viewer Library (main seam). Tested against an in-memory Room database under Robolectric, with a controllable clock and a fake episode fetcher. Covers:

  • the 93% threshold
  • Up Next across episodes and seasons, and after skipping ahead
  • hand marks counting as watching
  • one card per series, ordering, and filtering by kind
  • removal and when a removed series reappears
  • new-episode detection only for series the Profile has watched
  • per-Profile isolation of progress, Favourites and Recent Searches
  • the Recent Searches cap and de-duplication
  • Live Preview eligibility
  • Favourites surviving a catalogue refresh

  Prior art: XmltvChannelParseTest's Robolectric setup (@Config(sdk = [34], application = android.app.Application::class), a plain Application so WorkManager isn't scheduled) and the existing room-testing dependency.

• Sync (second seam). Gather from one in-memory database and apply into another, then assert that each Profile's Favourites and watch progress arrive under the same Profile name and that merging is additive.

• Compose UI. Add ui-test-junit4 and ui-test-manifest and run Compose UI tests on the JVM under Robolectric (no device). Screens are tested through their content composables with UI state passed in. Cover:

  • initial highlight: the Live Preview when present, otherwise the first row; the series page main button
  • badges and progress bars for each episode status
  • the main button's label in each case
  • the Menu key and holding Select opening the options panel, with only the applicable actions
  • empty rows hidden and the hint shown
  • Recent Searches shown when the search box is empty

  There is no prior art for UI tests in the repo; this spec introduces it.

• Not automated: the rebrand, Gradle version-code formula, release-please, signing and the Downloader install. These are verified by CI building and releasing, plus a manual checklist on the Android TV emulator and the Fire Stick (install, update over a previous release, voice dictation into a text box, Live Preview on a one-connection account).

• The parsers' existing unit tests must keep passing throughout.

Out of Scope

• "Alexa, find X in Settee" from outside the app (Amazon only offers that through catalogue integration for apps in its store).
• Publishing to the Amazon Appstore or Google Play.
• Removing existing features or translations; translating the new strings.
• Renaming the Kotlin package.
• Compatibility of sync with upstream OpenTV devices.
• Migrating existing OpenTV favourites or watch history.
• Episodes the Profile never played being inferred as Watched.

Further Notes

• Terms follow GLOSSARY.md (Profile, Watched, In Progress, Unwatched, Up Next, Continue Watching, Favourite, Recent Search, Home, Live Preview). ADR 0001 records why Favourites belong to a Profile.
• The rebrand should land first, as its own ticket. Every later ticket and release then lives in the new repo.
• Several statements in CLAUDE.md become false with this work: the fork notes, the 95% threshold, the release steps, the updater repo, favourites being a column, and the migrations policy. The tickets that change those behaviours update it.
• Up Next and Continue Watching depend on episode data being present. Because episodes load lazily, a series whose episodes have never been fetched gets them fetched when its first episode's progress is recorded (it was opened to play it, so they will normally already be there).