halkyon/docs/adr/0041-learn-subjects.md

# ADR 0041: Learn's subjects: one per studyset, from a fixed list

- **Status:** decided 9 and 10 Nov 2026 by the developer: D1 to D4 and D6 are their own
  choices, D5 and D7 to D9 and D8's details the agent's recommendations, which they
  confirmed. D1 to D9 are built; D10 comes later.
- **Builds on:** ADR 0002 (payloads and their schemas), ADR 0005 (publishing), ADR 0031
  (the palette's twenty colours).

## Context

A library of a hundred studysets, most of them computing books and language courses,
shows them by title alone. Vaia files every studyset under a subject from a fixed
list, shown on its card with a stripe in the subject's colour, and lets the library be
narrowed to one.

## Decisions

- **D1.** One subject per studyset, from a fixed list of about Vaia's breadth, with
  *Other / not sure* last.
- **D2.** Each subject has a Lucide icon and a default colour from the palette. Choosing
  one gives the studyset that colour, which stays the studyset's to change.
- **D3.** Languages are one subject, *Languages*. The language itself comes from the
  studyset's front language, which every course already gives.
- **D4.** Computing is five subjects: *Computer science*, *Software engineering*, *Data
  science and AI*, *IT and operations*, *Security and privacy*. Most of the library is
  computing, and a single subject would narrow nothing.
- **D5.** The subject sits on the top studyset alone, which its sub-studysets show as
  theirs (`subjectOf`); their sheet offers none. It is kept in the studyset's sealed
  payload as `subject`, a subject's ID (schema 8), and so goes into archives and is
  published with the studyset, for Explore to filter by later.
- **D6.** The list is the agent's draft of 10 Nov 2026, taken as it is (below).
- **D7.** IDs are never renamed. An ID this app version doesn't know (a newer one's) is
  kept as it is and reads as no subject until another is picked.
- **D8.** The library, as Vaia's: a dropdown of the subjects in use, cards naming the
  subject under the title with a stripe in its colour, sections by recency (the last 7
  days, the last month, older), the archive last. Decided on 10 Nov 2026:
  - recent by the later of a card's last rating in the studyset (or inside it) and the
    studyset's own last change; one from before changes were recorded counts from when
    it was made, as its UUID v7 says (`lastUsedOf`, `shelvesOf`);
  - the starred on a shelf of their own on top, however long ago they were used;
  - the subject chosen kept on the device (`DeviceSettings.librarySubject`), all
    subjects where none is chosen or the one kept is no longer in use; a studyset
    without a subject, or with one this version doesn't know, is under *Other*;
  - the stripe is the studyset's own colour, the card's bar on top, which the subject
    sets when picked; the subject's line shows the subject's icon, and a language course
    its language beside (*Languages · Japanese*).
- **D9.** Existing studysets: the agent writes a subject into each of the developer's 72
  archives not yet imported; those already in the library get one by hand.
- **D10.** Explore filters by subject later; its releases don't keep the subject in a
  column yet (it is in each release's repository).

## The list (D6)

ID, English and German name, Lucide icon, default colour (`Subject`, `subject.dart`).

| Group | ID | English | German | Icon | Colour |
|---|---|---|---|---|---|
| Sciences and health | `biology` | Biology | Biologie | dna | fern |
| | `chemistry` | Chemistry | Chemie | flask-conical | reef |
| | `physics` | Physics | Physik | atom | slateblue |
| | `astronomy` | Astronomy | Astronomie | telescope | enzian |
| | `earth-sciences` | Earth sciences | Geowissenschaften | mountain | sahara |
| | `environmental-science` | Environmental science | Umweltwissenschaften | leaf | forest |
| | `medicine` | Medicine | Medizin | stethoscope | cerise |
| | `nursing` | Nursing | Pflege | heart-pulse | strawberry |
| | `pharmacy` | Pharmacy | Pharmazie | pill | pink |
| | `nutrition` | Nutrition | Ernährung | apple | carrot |
| | `psychology` | Psychology | Psychologie | brain | plum |
| | `sports-science` | Sports science | Sportwissenschaft | dumbbell | copper |
| Mathematics and computing | `mathematics` | Mathematics | Mathematik | sigma | cobalt |
| | `statistics` | Statistics | Statistik | chart-column | ocean |
| | `computer-science` | Computer science | Informatik | cpu | slateblue |
| | `software-engineering` | Software engineering | Softwareentwicklung | code | enzian |
| | `data-science-ai` | Data science and AI | Data Science und KI | brain-circuit | purple |
| | `it-operations` | IT and operations | IT und Betrieb | server | pine |
| | `security-privacy` | Security and privacy | Sicherheit und Datenschutz | shield-check | forest |
| | `engineering` | Engineering | Ingenieurwesen | cog | soil |
| | `architecture` | Architecture | Architektur | building-2 | sahara |
| Society | `history` | History | Geschichte | landmark | soil |
| | `geography` | Geography | Geografie | globe | pacific |
| | `politics` | Politics | Politik | vote | cobalt |
| | `law` | Law | Recht | scale | pickle |
| | `economics` | Economics | Volkswirtschaft | trending-up | olive |
| | `business` | Business | Betriebswirtschaft | briefcase | copper |
| | `marketing` | Marketing | Marketing | megaphone | carrot |
| | `accounting-finance` | Accounting and finance | Rechnungswesen und Finanzen | calculator | pine |
| | `sociology` | Sociology | Soziologie | users | plum |
| | `anthropology` | Anthropology | Anthropologie | footprints | sahara |
| | `education` | Education | Pädagogik | school | ocean |
| | `media-studies` | Media studies | Medienwissenschaft | tv | pink |
| | `philosophy` | Philosophy | Philosophie | lightbulb | purple |
| | `religious-studies` | Religious studies | Religionswissenschaft | book-open | olive |
| Languages and arts | `languages` | Languages | Sprachen | languages | cerise |
| | `literature` | Literature | Literatur | book-marked | strawberry |
| | `linguistics` | Linguistics | Linguistik | speech | enzian |
| | `art-design` | Art and design | Kunst und Design | palette | pink |
| | `music` | Music | Musik | music | plum |
| | `theatre-film` | Theatre and film | Theater und Film | clapperboard | cerise |
| Everyday | `cooking-hospitality` | Cooking and hospitality | Kochen und Gastronomie | chef-hat | carrot |
| | `driving-licences` | Driving and licences | Führerschein und Lizenzen | car | soil |
| Other | `other` | Other / not sure | Sonstiges / unsicher | circle-question-mark | none |

## Consequences

- A studyset saved by this version is in schema 8, which older versions refuse to read,
  as every schema before (ADR 0002): an archive with subjects imports from this version
  on.
- Adding a subject is cheap; renaming an ID isn't (D7), so names change, IDs don't.