# ADR 0022: No hand-off and no connector

- **Status:** decided 23 Oct 2026, by the developer (D1–D3 below); built for v0.19.0
  (build 22).
- **Supersedes:** ADR 0006 (Claude reads studysets through a connector on the instance),
  and the hand-off to an AI assistant outside the app (decided 10 and 14 Oct 2026, Learn's
  `AGENTS.md`).
- **Followed by:** ADR 0021 (an assistant on the instance, on its operator's keys),
  accepted 25 Oct 2026.

## Context

Since 10 Oct a question asked from the app could leave it in two ways, both through the
person's own subscription, as Halkyon called no language model with an API key: the
hand-off opened the chosen assistant's new conversation (Lumo by default, ChatGPT,
Claude, …) with the question and the chosen parts written in, for the person to send; and
Claude's apps read the person's studysets through the instance's connector (ADR 0006: MCP
at `/mcp` with its own OAuth, connected with a code from Settings › Assistant › Connect
Claude). Beside them, the same field searched the web.

ADR 0021 proposes an assistant inside the app on an instance whose operator pays for it:
several providers on the operator's keys, granted per person, with limits and statistics,
and personal keys where the operator allows them. The developer asked on 23 Oct to "drop
the Assistant part that just opens the assistant outside of the app, but let's keep the
web open part", or else decide how the instance's own assistant and opening one's own
outside the app go together.

## Decisions (23 Oct 2026, the developer's)

- **D1 The hand-off goes now** (over keeping it until the instance's assistant comes,
  which was recommended): until then the field searches the web only.
- **D2 The connector goes too** (over keeping it, which was recommended): an instance has
  one way to an assistant, its operator's (ADR 0021), and nothing else on it reads
  people's content for a language model.
- **D3 In v0.19.0, the app and the server together** (over releasing v0.19.0 first and
  taking the server's part out with the next raise of `minimumAppBuild`, which was
  recommended): build 22 raises `minimumAppBuild` to 22 anyway, so no app that calls the
  connector's endpoints can use the instance after it, and nothing needs to stay for
  older apps.

## What goes, and what stays

1. **In the app:** the assistants a question opened in (`AiAssistant`, `AssistantHandOff`),
   the switch at the field's start between them and the web (`assistantTarget`), Settings'
   choice of assistant, Connect Claude with its route, cubit, repository and gateway, and
   their texts. A device's settings file from before keeps the old keys (`aiAssistant`,
   `customAssistantUrl`, `assistantTarget`) until the next change of a setting writes it
   anew without them; nothing reads them.
2. **On the server:** `lib/src/assistant/` (the MCP endpoint, its OAuth pages and metadata,
   the five tools, connect codes, tokens), `AssistantEndpoint`, the daily forgetting of
   the connector's codes and tokens, their lines in Learn's deletion hook,
   `instance.info().assistantConnectorUrl` (nullable, so an older app reads it as none),
   and Caddy's forwarding of `/mcp`, `/oauth/*` and `/.well-known/oauth-*`. A migration
   drops the five tables (`assistant_client`, `assistant_connect_code`,
   `assistant_connection`, `assistant_grant`, `assistant_token`) with every connection,
   code and token in them: from the deploy on, a connected Claude gets no answer, and
   people remove the connector in Claude's settings.
3. **Stays:** the field (`AssistantBar` on Home, `AssistantButton` in the Library, on a
   studyset and while studying), off unless the person turns it on in Settings, its chips
   of what the question is about (those a web search takes: a card's front, back, hints
   and explanation, never a studyset's name or description), and the web search through
   the engine chosen in Settings, or Android's own search.

## Consequences

- Until an instance offers ADR 0021's assistant, its people ask no language model from the
  app. learn.halkyon.eu, a public instance, offers none (ADR 0021: public instances leave
  the assistant unset).
- The instance reads payloads in one place fewer (ADR 0019's context named four).
- **The deploy breaks the rule that migrations keep the old server working until the
  switch**, for the minute between the maintenance run and the new server: the old one
  then answers the connector's calls with errors, and an account deleted meanwhile (by
  its owner, or the pruning) fails and is deleted when asked again, as the old server's
  deletion hook still deletes from the connector's tables. Keeping the tables a release
  longer would keep the rule, for codes and tokens nothing reads; since build 22 raises
  `minimumAppBuild` (D3), no released app syncs with that server by then.
- The privacy page (website repository) drops the connector and the hand-off to Lumo.