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. Nothing is built yet.
- **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).

## 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.

## 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, before the rename,
   so that they aren't renamed only to be removed.
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.
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.