halkyon/docs/adr/0045-halkyon-days.md

# ADR 0045: Halkyon Days, its apps, names and domains

- **Status:** decided 12 Nov 2026 by the developer: D1 to D8 and D12 are their own
  choices, D11 too (over the agent's recommendation to keep `halkyon_`), and D16; D9,
  D10, D13 to D15 and D17 the agent's recommendations, which they chose, as the answers
  to the open questions. Step 1 built 12 Nov 2026: the organisation renamed, every
  URL naming it changed; the repository is public again since that day. Amended the
  same day by the developer: step 2 waits until halkyon.li opens to the public, which
  also moves it off the host at home (an open question below); the snap names
  `halkyon` and `myrmex` are registered, the Snap Store account's publisher named
  Halkyon Days (`halkyon-days`). Step 3 built 13 Nov 2026. Amended on 13 Nov 2026
  by the developer for step 4: D18 and D19 (the agent's recommendations, which they
  chose), and the names step 4 keeps: Train and Meditate stay "Halkyon Train" and
  "Halkyon Meditate" for now, "Halkyon" over their word in their wordmark, cobalt over
  copper; the Proton Pass items of Halkyon's and Myrmex's keystores renamed by the
  developer after the apps (`Halkyon – Android release keystore`, `Myrmex – …`), as
  the release tool finds an app's item by its name. Amended on 13 Nov 2026 by the
  developer for step 5: D20 to D24.
- **Builds on:** ADR 0015 (one repository), ADR 0016 (one account across an instance),
  ADR 0017 (a password and an authenticator), ADR 0020 (SimpleLogin), ADR 0031 (the
  apps' icons), ADR 0039 (halkyon.li at home).
- **Amends:** ADR 0039, whose halkyon.li was the family's instance alone (D6); ADR
  0016, for Halkyon and Myrmex (D7); ADR 0020, whose SimpleLogin goes out of use (D8);
  ADR 0031, D3, D6 and D11, for Halkyon's icon (D14); halkyone_ui's theme, every
  app's around cobalt (D18, D19).

## Context

Halkyon began as one learning app, then grew a family under its name: Halkyon Learn,
Todo, Train and Meditate, sharing an account on an instance (ADR 0016). Of them, Learn
is the one the developer means to open to the public, Todo the next; Train, Meditate
and Shop depend on content the operator owns and serves, and stay personal. A family
named after one app runs into Todoist's trouble: its maker was named after its first
product and had to rename itself Doist once there was a second. And the apps' names,
"Halkyon Learn", "Halkyon Todo", describe rather than name.

The developer's names (11 and 12 Nov 2026) follow one myth and one theme. Halcyon, the
kingfisher, is Alcyone (Ἀλκυόνη), who with her husband Ceyx (Κῆυξ) was turned into a
kingfisher (Ovid, *Metamorphoses* XI); every winter Aeolus, her father, calms the winds
for the days she nests on the sea, the *halcyon days*. Myrmex (μύρμηξ, "ant") was a
girl of Attica whom Athena turned into an ant (Servius on the *Aeneid*, 4.402); the
ants of Aegina became the Myrmidons (Ovid, *Metamorphoses* VII). Mortals turned into
animals, and the calm the halcyon days bring, are the family's thread: software that
gives people calm from prying, surveillance-capitalist eyes.

## Decisions

- **D1 The project is Halkyon Days** (the developer's): the umbrella, not an app; with a
  K, as the apps and halkyon.app have it ("Halcyon Days" is a British enamel-box brand
  and an album). It names what the apps give, and keeps apart from any one of them, so
  it never has to change as Todoist's maker had to. People see it on the project's
  site, in the apps' About ("part of Halkyon Days") and at the foot of the instances'
  pages.
- **D2 Halkyon is the learning app** (the developer's), "Halkyon Learn" until now: the
  kingfisher, the project's first app and the one that gave it its name, as Proton
  Mail is Proton's. Its icon becomes the kingfisher (D14).
- **D3 Myrmex is the task app** (the developer's), "Halkyon Todo" until now: the ant, an
  image of tasks carried together. Said "MUR-mex" in English, "Mürmex" or "Mirmex" in
  German. Its icon keeps Lucide's `list-todo` until an ant is drawn for it, as the
  kingfisher was commissioned. Before the name is published: a trademark search
  (EUIPO, the app stores); none was found by the agent's quick search (11 Nov), but for
  an ant-keeping hobby project, *Agora Myrmex*.
- **D4 Keyx is the voice assistant, later** (the developer's): Ceyx, Alcyone's husband,
  with a K as Halkyon has one. Nothing of it is built.
- **D5 The domains** (the developer's, 12 Nov 2026):

  | Domain | What | Holds people's data |
  |---|---|---|
  | `halky.one` | the project's site: `/` Halkyon Days, `/halkyon`, `/myrmex`, `/keyx` (later), and the F-Droid repository, `/fdroid/repo` | no |
  | `index.halky.one` | the index of published studysets across instances (the hybrid distribution model), a running service of its own, kept apart from the static site | its own records alone |
  | `halkyon.li` | the public Halkyon instance | yes |
  | `myrmex.li` | the public Myrmex instance (registered by the developer, 12 Nov) | yes |
  | `halkyon.app` | redirects to `halky.one`, so old links keep working | no |

  *halky.one* reads as *Halkyone*, Alcyone's Greek name; *.li* is Lindau's common
  abbreviation, the developer's home on Lake Constance, where kingfishers fish. The
  project's domain knows nobody; only an instance holds people's data, which is a
  privacy story of its own. The pages are paths, not subdomains: one static site.
  `index.halky.one` takes the place of the earlier thought of `halky.one` itself for
  the distribution model. Moving the F-Droid repository now costs its one user re-adding
  it; later it would cost everyone.
- **D6 halkyon.li is Halkyon's public instance** (the developer's), where ADR 0039 made
  it the family's alone; it stays on the host at home behind ramiel (ADR 0039's
  network, sandbox and backups hold). Who may sign up there is open (below).
- **D7 Halkyon and Myrmex keep their accounts apart** (the developer's): each server
  holds a register of its own (ADR 0016's `AccountsMode.fromEnvironment()` without
  `ACCOUNT_REGISTER_URL`), with its own handles, account domain (`halkyon.li`,
  `myrmex.li`), operators, secrets and privacy page. Nothing passes between them, so
  neither instance learns who uses the other. ADR 0016's register stays for an operator
  who wants one account across their services; Halkyon Days' public instances don't.
  Agents (ADR 0044) are Halkyon's.
- **D8 People sign up and in with an email address, a password and an authenticator**
  (the developer's): ADR 0017's way alone, SimpleLogin out of use (`SIGN_IN_WAYS=
  password` on both instances), switched off by configuration first and its code
  removed once no account depends on it (the developer's choice, on the agent's
  recommendation): ADR 0020's sign-in, the callback page, and the OpenID Connect module
  `halkyon_oidc` (server, client, Flutter), written to be published for others and
  kept in git's history should it be wanted again. An account signing in with
  SimpleLogin alone (the developer's own) sets a password from its Profile first,
  through a code mailed to its address (ADR 0017's fourth reading).
- **D9 Train and Meditate stay personal, on registers of their own** (the agent's
  recommendation, which the developer chose): today they are members of Learn's register, so on
  a public halkyon.li every Halkyon account could sign in to them. Each holds its own,
  with `SIGN_UP=closed` once the family's accounts exist; `INSTANCE_SECRET` and
  `INSTANCE_MEMBERS` go out of use. Over keeping them members, which would need a
  per-service approval the module doesn't have.
- **D10 The app IDs follow halky.one** (the agent's recommendation, which the
  developer chose):
  `one.halky.halkyon` and `one.halky.myrmex`, Android's and iOS's IDs being domains
  reversed. The developer is the apps' only user, so the change costs a reinstall of
  each on their devices (their data comes back with the first sync) and new F-Droid
  entries; later it would cost everyone. The signing keys stay.
- **D11 In the code, `halkyone_` is the project's prefix, the apps' names below it**
  (the developer's, over the agent's recommendation to keep `halkyon_` for the shared
  packages and `halkyon_learn_*` for Halkyon's): *Halkyone* as halky.one spells it.
  The shared packages become `halkyone_ui`, `halkyone_app`, `halkyone_base_server` and
  `_client`, `halkyone_core`, `halkyone_content`, `halkyone_editor`, `halkyone_keys`,
  `halkyone_llm`, `halkyone_interop` (`halkyon_oidc` goes, D8); the apps' become
  `halkyone_halkyon_server`, `_client`, `_flutter`, `_core`, `_curator`, `_agent`,
  `halkyone_myrmex_…`, `halkyone_train_…`, `halkyone_meditate_…`. The folders take the
  apps' names: `apps/halkyon/`, `apps/myrmex/`, later `apps/keyx/`, beside
  `apps/train/` and `apps/meditate/`. The name an instance's basics give its app (ADR
  0014) becomes `halkyon` and `myrmex`. Release tags become `halkyon-v…` and
  `myrmex-v…`, the earlier `learn-v…`, `v…` and `todo-v…` counting as their history.
  What changes with the names, the developer being the apps' only user: the classes'
  prefix on the wire and the module's endpoints (`halkyon_base.…`), so builds before
  and after don't mix; and Serverpod's record of applied migrations, kept per module
  name, which each database renames in one statement as the renamed servers first
  deploy (its SQL explained then), or they would create the module's tables again.
- **D12 The organisation is `halkyon-days`** (the developer's): code.halkyon.app's
  `project-halkyon` renamed, its repositories keeping their names (`halkyon`, `website`
  and the forks), every URL naming it changed in one commit (below).
- **D13 The deploy's variables carry their service's name** (the agent's
  recommendation, which the developer chose, over a file of variables per service): with a register each (D7, D9), every register's
  secrets are its own, and the unprefixed ones Learn has had since it ran alone become
  `HALKYON_…`. What the operator shares across services stays unprefixed.

  | Today | Becomes |
  |---|---|
  | `LEARN_DOMAIN`, `LEARN_PUBLIC_HOST`, `LEARN_POSTGRES_PASSWORD`, `LEARN_SESSION_KEY_HASH_PEPPER` | `HALKYON_…` |
  | `TODO_DOMAIN`, `TODO_POSTGRES_PASSWORD`, `TODO_SESSION_KEY_HASH_PEPPER` | `MYRMEX_…` |
  | `ACCOUNT_DOMAIN`, `EMAIL_SIGN_IN_PEPPER`, `EMAIL_FROM`, `TOTP_KEY`, `RECOVERY_CODE_KEY`, `SIGN_IN_DECOY_KEY`, `SIGN_IN_WAYS`, `SIGN_UP`, `AGENTS`, `SIMPLELOGIN_…` | `HALKYON_…`, and each register's own as `MYRMEX_…`, `TRAIN_…`, `MEDITATE_…` (but `AGENTS`, Halkyon's alone) |
  | `INSTANCE_SECRET`, `INSTANCE_MEMBERS`, `INSTANCE_MEMBER_…` | gone (D9) |
  | `EMAIL_SMTP_…`, `DATA_LOCATION`, `BACKUP_LOCATION`, `SOURCE_URL`, `COMPOSE_FILE`, `JELLYFIN_…`, `FILE_LIMIT_…`, the maps', weather's and Photon's | unchanged, the operator's |

  `compose.learn.yaml` and `compose.todo.yaml` become `compose.halkyon.yaml` and
  `compose.myrmex.yaml`, `sidecars/todo.caddy` `myrmex.caddy`; the Compose project keeps
  its name, `halkyon-learn`, as Docker names its volumes after it.
- **D14 Halkyon's icon is the kingfisher** (the agent's recommendation on the developer's
  wish of 12 Nov, which they chose): the commissioned drawing in its own colours, cobalt
  back and orange belly, on ADR 0031's white tile, its themed variants the bird's
  outline; on its launch screen too. Myrmex, Train and Meditate keep their glyphs, and
  their launch screens the kingfisher in their colours (ADR 0031, D11) until Myrmex has
  its ant. ADR 0031 records it as D12 when built.

- **D15 The public instances ask the operator's approval at first** (the agent's
  recommendation, which the developer chose): `SIGN_UP=approval` on halkyon.li and
  myrmex.li (ADR 0021), opened once the operator trusts them.
- **D16 The developer's account moves into Myrmex's register whole** (the developer's
  choice, carrying their tasks over): Todo's rows are named by the account's ID and
  sealed with its keys, so only the same account, not a new one, opens them. As
  Myrmex's server becomes a register, the account's rows (its ID, address, password
  verifier, wrapped keys and authenticator) are copied from Halkyon's register into
  Myrmex's in one step of the switch, its SQL explained then; the same password and
  authenticator sign in on both, apart from then on.
- **D17 The snaps are registered anew as `halkyon` and `myrmex`** (the agent's
  recommendation, which the developer chose), where the Snap Store has them free;
  `halkyon-learn` and `halkyon-todo` are closed, their one user moving over. Both
  registered 12 Nov 2026 under the account that publishes the others, its publisher
  shown as Halkyon Days.
- **D18 Each app has a colour of its own, Myrmex strawberry** (the agent's
  recommendation, which the developer chose on 13 Nov 2026): an app with a name of its
  own shows that name alone in its wordmark, in its own colour, Halkyon in cobalt and
  Myrmex in strawberry (`BrandWordmark.alone`, `AppFrame.productAlone`), where Train and
  Meditate keep "Halkyon" over their word. The colour is the theme's primary role
  (halkyone_ui's `AppPrimary`, `appTheme(primary:)`): buttons, links, switches, the
  add and voice buttons, filled buttons and the first start's wash; neutrals, slate
  blue and copper stay every app's. Myrmex's strawberry is deeper than the palette's
  (#EC3E7C, too light for white on it or as text on white): #C21E5C, white on it at
  5.8:1, the fill in both modes as cobalt's deep shade is; #FFB1C9 its text and marks
  in dark mode; containers #FFD9E3 on #3F0018 light and #5C1130 under #FFD9E3 dark.
  Halkyon, Train and Meditate keep cobalt. Alternatives were the palette's strawberry
  as it is (too light for text, 3.6:1), a darker berry nearer purple (losing the
  strawberry), and cobalt for every app with strawberry only on the navigation bar, as
  before (the developer wanted Myrmex's own colour on its buttons).
- **D19 Errors are a true red in every app** (the agent's recommendation after looking
  at Proton's apps, which the developer chose on 13 Nov 2026): Myrmex's strawberry
  would be read as an error beside Material's default error colour, a crimson; so
  every app, Halkyon too, takes a red far from it in hue: #B3261E light, white on it,
  container #F9DEDC with #410E0B; dark #FF6B5E, saturated rather than Material's pastel
  #FFB4AB, with #3B0905 on it, container #5C1712 with #FFDAD5. Proton's apps keep
  strong reds in their dark themes too (Mail's #F5385A, Wallet's #FB7878), but theirs
  are crimson (349°), 12° from our strawberry (337°); ours sits at 3°.
- **D20 Each register signs in with a SimpleLogin app of its own** (the developer's
  choice, over the agent's recommendation of one app shared by the four until
  SimpleLogin goes): Halkyon keeps the instance's app, its callback moved to
  `https://halkyon.li/simplelogin-callback`; Myrmex, Train and Meditate each take one
  of the developer's apps kept in reserve (SimpleLogin made no new ones after 22 Oct
  2026), with their secrets as `MYRMEX_SIMPLELOGIN_…`, `TRAIN_…` and `MEDITATE_…`.
  SimpleLogin gives a person a different ID in each app (ADR 0020), so a copied
  identity would match nothing: the account is linked on each new register by its
  operator instead (D21). Each server serves the forwarding page, the privacy page and
  the profile pages itself, as a register does.
- **D21 Only the developer's account moves, linked by the operator** (the developer's
  choices): D16 for Myrmex, Train and Meditate alike, nobody else's, as nobody else
  uses them. The switch copies the account's keys (its `account_password` row: the
  wrapped keys and the public keys, which no register's secret touches) and its
  operator's scope into each; not its email identity, authenticator or recovery
  codes, which are keyed with Halkyon's secrets, each register having its own (D7);
  they come back with a password, once there is mail (D8). Then the developer signs
  in on each with its SimpleLogin app, which makes an account waiting for approval,
  and `deploy/host/link-simplelogin.sh` moves that SimpleLogin identity onto the
  developer's account and deletes the empty one. Over building the link into the
  module's operator screen: no code for a step taken once. Train and Meditate are
  `SIGN_UP=closed` once linked (D9); Halkyon and Myrmex stay on approval (D15).
- **D22 learn.halkyon.li and todo.halkyon.li go** (the developer's choice, over
  redirecting them): Halkyon answers at `halkyon.li`, Myrmex at `myrmex.li`, Train and
  Meditate where they are; the old names leave HAProxy, Caddy and DNS. Only the
  developer's own links named them. Halkyon's and Myrmex's builds connect to
  `https://halkyon.li/` and `https://myrmex.li/`; Train's keeps `train.halkyon.eu`
  until the developer decides otherwise.
- **D23 The databases, the superuser and the images take the new names too** (the
  developer's choice, over keeping them as the Compose project keeps its own):
  `halkyon_learn` becomes `halkyon_halkyon`, as database and as the instance's
  PostgreSQL superuser, `halkyon_todo` `halkyon_myrmex`, as database and role, and
  the images `halkyon-halkyon-server`, `halkyon-halkyon-dictionaries` and
  `halkyon-myrmex-server`, the service `todo-server` `myrmex-server`. The Compose
  project and its edge network keep `halkyon-learn`, as Docker names the volumes
  after the project. The servers' development and test databases keep their names, as
  renaming them would start each developer's own database empty.
- **D24 The switch is a script run once by hand** (the agent's recommendation, which
  the developer chose, over two deploys): `deploy/redeploy.sh` runs as the copy
  deployed, which predates step 3's carrying of the migration records, and can't
  rename a database a server holds open. `deploy/host/switch-0045.sh`, run as
  `deploy` on the instance's host once the night's CI run passed, checks the
  signatures as redeploy.sh does, dumps every database, stops the services, renames
  the databases and the superuser, rewrites `.env` (`deploy/host/env-0045.sh`: D13's
  names, a register's secrets made for each), fast-forwards, carries the migration
  records, migrates, copies the developer's account into the other registers (D21),
  starts everything and waits for each server; deploys after it are redeploy.sh's
  again. It runs from a copy taken out of the commit, as the deployed checkout lacks
  it, and goes on where it stopped when run again.

## Steps

1. **The organisation's rename** (D12): the developer renames `project-halkyon` in
   Forgejo; one commit changes every URL naming it (the servers' source links, which
   the AGPL requires, and their tests; the forks in the pubspecs and the lock; the
   F-Droid metadata, the snaps, the release configurations; the docs); the checkouts'
   remotes follow (the laptop, the server's `~deploy/halkyon`, balthasar's). The local
   folder keeps its name, as the agent's memory and the worktrees know it by its path.
2. **Sign-in** (D8): the developer's account gets a password; `SIGN_IN_WAYS=password`
   on the instance; then SimpleLogin's code and `halkyon_oidc` go. Moved after step 5
   on 12 Nov 2026 (the developer's choice): a password needs mail, which halkyon.li
   doesn't send (ADR 0039, D4), and SimpleLogin serves the developer alone until
   halkyon.li opens to the public, so it waits for that, with mail set up then. Step 3
   therefore renames the module's SimpleLogin part with the rest, and leaves
   `halkyon_oidc` its name: written for others, it isn't Halkyon's.
3. **The packages' rename** (D10, D11), in a worktree with `serverpod start` stopped,
   the generated code made anew and the full check passing: the shared packages to
   `halkyone_…`; `apps/learn/` to `apps/halkyon/` with `halkyone_halkyon_…`, its snap
   recipe moved from the root to `apps/halkyon/snap/`; `apps/todo/` to `apps/myrmex/`
   with `halkyone_myrmex_…`; Train's and Meditate's packages to `halkyone_train_…` and
   `halkyone_meditate_…`; the app IDs; the instances' app names; the release tool's
   configuration, tags and history; the migrations' module names (D11).
4. **The names people see** (D2, D3, D14): Halkyon's and Myrmex's texts, the launcher's
   labels, windows, mails, the privacy and profile pages, the listings; Halkyon's
   kingfisher icon; "part of Halkyon Days" in About. Built 13 Nov 2026 with D18 and
   D19, "part of Halkyon Days" at the foot of the instances' pages too.
5. **The deploy** (D7, D9, D13, D15, D16): the variables and compose files renamed;
   Myrmex, Train and Meditate on registers of their own, the developer's account copied
   into Myrmex's (and Train's and Meditate's, as their data is named by it too);
   `myrmex.li` in Caddy; `SIGN_UP=approval`; the builds' instances (`serverUrl` in each
   `release.dart`) `https://halkyon.li/` and `https://myrmex.li/`; learn.halkyon.eu and
   todo.halkyon.eu go with their server, which retires this month (ADR 0039), as nobody
   but the developer used them.
6. **The releases** (D10, D17): the first builds under the new IDs, on F-Droid and as
   the snaps `halkyon` and `myrmex`; the developer installs them in place of the old.
7. **The site** (D5): halky.one's pages in the website's repository, the F-Droid
   repository moved, halkyon.app redirecting.
8. **The index** (D5): `index.halky.one`, with the distribution model, later.

## Open questions

- **Shop**: personal, as Train and Meditate (ADR 0039); whether it takes a name of the
  same myth later.
- **Where the public instances run** (raised 12 Nov 2026, amending D6 once decided):
  a public halkyon.li leaves the host at home. The agent's recommendation: the servers
  and their databases on a rented server in Germany (Hetzner, netcup) rather than
  Serverpod Cloud, whose Growth plan comes to about $80 a month a server against
  €10–20 for one rented server holding both, and whose region and data processing
  agreement its pages don't name; the sidecars (LanguageTool, maps, search, weather)
  staying at home, where a failure costs a feature for a while; backups to the host at
  home. Open with it: the provider, the server's size (measured on the host at home
  first), mail, the legal pages (an imprint, the privacy page, the agreements with the
  hoster and Proton, a contact for reports of illegal content) and the limits of a
  public instance (files, the operator's assistants).