docs: the assistant answering in Learn, as step 3 built it

Learn's AGENTS.md describes the field with the assistants answering in it
(ADR 0021, step 3): who answers, the scope, the conversation sheet and its
lookups, images, private studysets' warnings, kept conversations and the
tasks; and the testing trap of awaiting a finished subscription's cancel.
The shared packages' READMEs name providerTermsOf and onThisMachine.
Learn's README no longer says there is no end-to-end encryption, which
private studysets changed (ADR 0019).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>

AGENTS.md

@@ -10,7 +10,7 @@ Halkyon's apps and the packages they share, in one repository and one pub worksp
 - **`packages/`**: what the apps share, each with its README and licence, which the apps take by path (`path: ../../../packages/<package>`), so a change to a shared package and to the apps using it is one commit:
   - `halkyon_ui`: Halkyon's look, the theme around cobalt and copper, Noto Sans bundled, the window-size classes and the widgets every screen is built of, with texts of its own (English, German).
   - `halkyon_base_server`, `halkyon_base_client`: the Serverpod module every Halkyon server includes (ADR 0014): signing in (a password with TOTP and the resets of ADR 0017, SimpleLogin on `halkyon_oidc`, email codes proving an address; no anonymous accounts since ADR 0020, D25, nor GitHub since D36), an account's ways in and its deletion with a hook for each app's own data, the pruning, the instance's basics, people's handles and public profiles, who may sign up (`SIGN_UP`: open, approval, closed) with the accounts waiting for approval and the instance's operators who approve them (Halkyon Learn's ADR 0021, step 1), the operator's assistants forwarded on halkyon_llm with their grants, limits and counted figures, and the instance's privacy page made from its settings (step 2), and the instance's register (ADR 0016): one account per person across an operator's services, held by one service (Learn's server on learn.halkyon.eu) and asked by the others, its members (`ACCOUNT_REGISTER_URL`), all sharing a secret (`INSTANCE_SECRET`); its README says how.
-  - `halkyon_app`: every app's shell on the module's client (ADR 0014): the instances a device keeps accounts on and the first start, signing in and switching person, the gates building an app's dependencies per instance and per person, the sync service and where it stands, the account section of an app's settings (`AccountTiles`), the wait screen of an account waiting for approval and the operator's card, badge and screen (ADR 0021), the assistants of an app's settings (`AssistantsCard`: granted, agreed to, used, and the person's own keys) and the operator's grants on that screen (`AssistantGrantsCard`), with the repositories asking them through the module or a person's own key directly (step 2), About with the instance's source link (`showAppAbout`), the language every app picks (`resolveAppLocale`) and countries' and subdivisions' names (Unicode CLDR's, bundled), with texts that name the app.
+  - `halkyon_app`: every app's shell on the module's client (ADR 0014): the instances a device keeps accounts on and the first start, signing in and switching person, the gates building an app's dependencies per instance and per person, the sync service and where it stands, the account section of an app's settings (`AccountTiles`), the wait screen of an account waiting for approval and the operator's card, badge and screen (ADR 0021), the assistants of an app's settings (`AssistantsCard`: granted, agreed to, used, and the person's own keys) and the operator's grants on that screen (`AssistantGrantsCard`), with the repositories asking them through the module or a person's own key directly (step 2) and what an app's warning before a private studyset goes names (`providerTermsOf`, `OwnAssistant.onThisMachine`, step 3), About with the instance's source link (`showAppAbout`), the language every app picks (`resolveAppLocale`) and countries' and subdivisions' names (Unicode CLDR's, bundled), with texts that name the app.
   - `halkyon_core` (low-level primitives in pure Dart: ids, a logger, `SerialQueue`, `CoalescingRunner`) and `halkyon_interop` (contracts between apps, pure Dart).
   - `halkyon_keys` (pure Dart on libsodium, ADR 0017): an account's keys on the device, the password's Argon2id and SRP's x, the key pairs and their wrapping, the recovery phrase, data keys, content sealed and signed. SRP-6a's two halves are the module's (`halkyon_base_server`'s `base.dart`, `halkyon_base_client`'s `srp.dart`), as are TOTP and the recovery codes. `sodium`'s build hook compiles libsodium, so every machine that builds or tests needs a C compiler and `make`.
   - `halkyon_llm` (pure Dart, Halkyon Learn's ADR 0021, D15 and D46): language models' APIs streamed over plain HTTP, no SDKs: Anthropic's Messages API, OpenAI's chat completions (each known host's fields, D45) and its Responses API, behind one interface (`LlmClient`), with `FakeLlmClient` for tests; tested on replies written from the providers' documentation and on those `tool/record_llm.dart` records with a key (D36). The module forwards the operator's assistants with it, and the apps call a person's own provider. BSD-3-Clause as `halkyon_oidc`, `publish_to: none`.

apps/learn/README.md

@@ -16,9 +16,11 @@ instance are published, so anyone can see how an instance works and run their ow
   email address with a password and an authenticator, the password never leaving the
   device ([ADR 0020](../../docs/adr/0020-sign-in-with-simplelogin.md),
   [ADR 0017](../../docs/adr/0017-password-totp-and-keys.md)).
-- **No end-to-end encryption.** Content is readable by the operator of the instance, as on
+- **Private studysets are end-to-end encrypted.** A private studyset's content is sealed
-  Mastodon; whoever trusts no operator can run their own
+  on the device with the account's keys; what isn't private, and what is published, the
-  ([ADR 0002](../../docs/adr/0002-no-end-to-end-encryption.md)).
+  operator of the instance can read, as on Mastodon
+  ([ADR 0019](../../docs/adr/0019-private-studysets.md),
+  [ADR 0002](../../docs/adr/0002-no-end-to-end-encryption.md)).
 
 Targets: Linux, Windows, macOS, Android and iOS. There is no web build.
 

packages/halkyon_app/README.md

@@ -83,7 +83,11 @@ Written as the apps are: Dart 3.13's primary constructors, Material from
   `AssistantGrantsCard` on `InstanceOperatorScreen`: grants with their
   limits, granted, changed and taken back, and everyone's use by month.
   `package:halkyon_app/assistant_models.dart` holds the models alone, in
-  pure Dart, for an app's own models.
+  pure Dart, for an app's own models. For the app's warnings before a
+  private studyset's content goes (ADR 0021, D9): `providerTermsOf` names a
+  provider's terms by its host (checked for Anthropic, OpenAI, Google and
+  OpenRouter, null for any other), and `OwnAssistant.onThisMachine` says
+  whether a person's own assistant runs on this machine.
 - **About** (`showAppAbout`): the app's name (its frame's), its version,
   icon and legalese where it gives them, where the source of what the
   instance runs is (`InstanceSourceCode`, from `AppDependencies.sourceCodeUrl`;

packages/halkyon_llm/CHANGELOG.md

@@ -3,4 +3,4 @@
 * One interface (`LlmClient`) over Anthropic's Messages API, OpenAI's chat completions
   (with each known host's fields, and the local servers') and OpenAI's Responses API,
   streamed over plain HTTP; failures by kind; `FakeLlmClient` for tests; the recording
-  tool.
+  tool; `LlmEndpoint.onThisMachine`.

packages/halkyon_llm/README.md

@@ -54,7 +54,9 @@ removed. Cancelling the subscription aborts the request.
 A base URL is `https`, but for a model on the same machine or network (`localhost`, a
 private or link-local address, a single-label name such as a container's, `.local`,
 `.internal`, `.home.arpa`), as Ollama and llama.cpp serve it; anything else is a
-`FormatException` when the endpoint is made.
+`FormatException` when the endpoint is made. `onThisMachine` says whether its requests stay on
+this machine (a loopback address, or `localhost` as RFC 6761 reserves it), not merely on
+the local network, which may be shared.
 
 - **Chat completions** go to OpenAI, Mistral, Gemini's compatibility endpoint, OpenRouter
   and local servers. OpenAI, Mistral and Gemini refuse fields they don't know and differ