halkyon/apps/train/AGENTS.md

Halkyon Train

What holds for every app and package of this repository is in the root AGENTS.md; it applies here in full, and Learn's patterns (apps/learn/AGENTS.md) wherever Train needs the same thing.

• A shell on the shared packages, Todo's copied and renamed (decided 2026-10-28, ADR 0030, D12; what Train is to do: ADR 0030): signing in, the instances, the account and the look work; nothing of a person's is kept or synced yet, which waits for Train's first model (ADR 0030: synced with serverpod_offline_sync, every row sealed, D7). Packages: halkyon_train_server, halkyon_train_client (generated, never edited), halkyon_train_flutter; app ID app.halkyon.train on every platform; no web build. Licences as Learn's (server SSPL, client and app AGPL; LICENSE.md).
• The server includes halkyon_base (ADR 0014) and configures it in server.dart (trainBase(), lib/src/train_base.dart): its basics say it serves train (never change it once apps use it), sign-in mails name Halkyon Train, the source is this repository, minimumAppBuild 1, no data of its own to delete with a person yet (add a deletePersonData hook with Train's first table). Authentication through the module's builders: a password, SimpleLogin on the register, email codes proving an address, server-side sessions; no anonymous accounts (ADR 0020, D25), nor GitHub (D36). Accounts (ADR 0016): Train holds its own register when it runs alone, and is a member of the instance's register (Learn's server on learn.halkyon.eu) where the operator sets ACCOUNT_REGISTER_URL (trainBase(accounts: AccountsMode.fromEnvironment())) with the instance's shared INSTANCE_SECRET (instanceSecret); then sign-in, handles and profiles are the register's, the email settings are the register's alone, and an identified person's deletion goes to the register first. addInstanceRoutes serves the calls between the services on its web server, and the server doesn't start without the secret where it needs it. schedulePruning (lib/src/pruning.dart) keeps the module's pruning scheduled, one entry each however often the server starts (and cancels the one under the pruning's name before ADR 0020, D25): the anonymous accounts left from before daily, sign-up attempts and codes hourly, as the register the deletions its members haven't confirmed hourly, as a member the people the register no longer knows daily (each a no-op in the other mode). Session logs are never persisted, in any run mode. Migrations (2026-10-28): one initial one with Serverpod's tables, its auth modules' and the module's as they stand, nothing of Train's own (Todo's grew one by one with the module; Train starts where they ended). Tests (test/integration/train_server_test.dart) call the module's endpoints through the server's own dispatch (halkyon_base.<endpoint>), since the generated test tools expose the project's endpoints alone.
• The app is halkyon_app's InstanceGate and SessionGate with Train's frame (trainFrame: "Train" under "Halkyon", its icon, train.example.org, its own sentence) and ServerpodInstanceChecker(app: 'train'); TrainDependencies (AppDependencies<TrainPerson>) on one instance, TrainPerson (empty) per person; a person's app with an empty home and the account sheet: halkyon_app's AccountTiles (whose account on which instance, Switch account, Sign out, Delete account, which asks first) in Train's words, and halkyon_app's About (showAppAbout: the source of what the instance runs, from TrainDependencies.sourceCodeUrl, and the licence list). Texts through gen-l10n in British English (the template), German (informal du), an empty en_US and en_GB (test/l10n/arb_files_test.dart keeps them in step). The look follows the system's theme mode and language until Train has settings. Countries in where an instance keeps its data are named by halkyon_app's CLDR names (AssetCountryNames), its language picked by halkyon_app's resolveAppLocale. Widget tests start Train's whole tree with halkyon_app's fakes (test/app/train_app_test.dart).
• The icon is to be Lucide's bike fading from cobalt through violet and strawberry into carrot (ADR 0031). Until the icon tool for every app is decided and built (ADR 0031, What follows), Train carries Todo's icon (assets/icon/halkyon_train_icon.png and the platforms' launcher icons, copied) and no tool of its own. registerLucideLicense puts Lucide's notice (ISC) in the licence list.
• serverpod start runs in apps/train/halkyon_train_server (it launches the app from lib/driver.dart); .mcp.json's --server-dir names it when a session works on Train. Its tests need throwaway passwords in its git-ignored config/passwords.yaml (database, serviceSecret, serverSideSessionKeyHashPepper, emailSignInPepper) or from the environment, as CI gives them. Train's development server has ports of its own (API 8180, Insights 8181, web 8182, PostgreSQL 8190; the app's assets/config.json), so it runs beside Learn's, as a member of Learn's register; its tests use config/test.yaml's ports, as Learn's and Todo's do, which Melos runs one package at a time.