Stop the relay checkbox promising a connection this client cannot make

Ticking "Connect through the server relay" moved the host's address and port out of the encrypted payload into plaintext columns on the server — the single deliberate privacy concession in the design, per ADR 0004 — and then the client dialled the address directly, exactly as it does with the box clear. VaultViewModel builds SshConnectionRequest(hostname, port, username, credential) and nothing on this side reads RelayEnabled at all. The connection failed the way it always had, for a machine the laptop could not reach, with nothing saying the box had done nothing. The server half is built and shipped: tickets, the WebSocket, the deny list, the CHECK constraint that enforces a non-null address for a relay-enabled host. What does not exist is the client's path to it, so this is an unfinished feature rather than a broken one — but the control in front of it was collecting the cost of the finished version. Both heads now say so, in the label and in the first sentence of the paragraph under it. Not disabled, and that is the one decision here worth stating: a host somebody has already ticked has to be able to lose the flag, and a control greyed out with the concession switched on would trap it there. Tickable and honest beats untickable and stuck. This is step 0 of docs/reaching-a-host-you-cannot-dial.md, and the only step of it that should ship alone — the sentence is written to be deleted when the bridge lands. VERIFIED. Build clean, 112 layout tests. The drawer's paragraph is longer than it was and the host editor is measured with the drawer open at the window's minimum, so the wrap is held inside the column rather than assumed to fit.
Write down the two things a user is promised and does not get
2026-08-07 08:47:02 +02:00 · 2026-08-07 08:44:21 +02:00 · 2026-08-07 08:43:49 +02:00
7 changed files with 435 additions and 366 deletions
@@ -1,349 +0,0 @@
 # Adding hosts on the phone
 The phone can read a keychain and connect through it. It cannot put anything in one. This document is the
 plan for the change that fixes that, and it is written to be picked up cold — the decisions, the reasons, the
 ordered work, and the traps that are already known.
 > **Status: built.** All six steps. Each one compiled with the whole suite green before the next began,
 > which is the rule the ordering below sets.
 >
 > | Step | State | Notes |
 > | --- | --- | --- |
 > | 1. `HostGroupSecret` grows | **Done** | Five fields, a version rule the codec did not have, a byte pin, and the "groups are flat" prose rewritten in all four places it appeared. |
 > | 2. The `Tag` item kind | **Done** | Secret, codec, merge, cipher, repository, both registries, EF entity and the generated `AddTagItem` migration. |
 > | 3. `HostSecret` grows, `Port` goes nullable | **Done** | `TagSet`, `TagIds`, `Port` as `int?`, `AsksForPassword`, both schema versions, and `HostInheritance` — the resolver. |
 > | 4. The shared view model | **Done** | Every choke point below, plus the group editor the plan never assigned a step to and without which nothing could set a default at all. |
 > | 5. The phone | **Done** | The `+`, the sheet, both editor cards, the back guard and EDIT on the connect bar. |
 > | 6. Tests and false prose | **Done** | Plus a fourth "groups are flat" site in `README.md` this plan did not list, and a cross-vault resolution bug the scouting for it turned up. |
 >
 > **Tags shipped after the six steps, in a seventh pass.** They were storable and unreachable when step 6
 > closed — a full item kind that no screen drew. Both heads now show a chip per tag on a host row and toggle
 > them in the host editor, which also creates one inline, because wanting a tag and tagging a host are the
 > same moment. Renaming and deleting live in a TAGS category on the keychain screen: a tag is an item so
 > that renaming it is one write instead of twenty, and that rename needed somewhere to happen.
 >
 > That pass also made the desktop host editor scroll. A picker's height is a chip per tag in the keychain,
 > so no fixed height holds it — which the layout suite caught the moment its seeder grew tags.
 >
 > **`HostFields.From` was answered by a refusal rather than by threading the resolver into the sync engine.**
 > A relay host may not inherit its port; `HostSecret.TryValidate` refuses one that tries. A plaintext column
 > derived from a *different* item goes stale when that item is edited and nothing re-pushes the hosts beneath
 > it, so the relay would keep dialling the old port — which is worse than the restriction.
 >
 > **One decision was taken that this plan did not specify.** "Three states where there were two" is four, not
 > three: a host can bind a key, bind a credential, be pinned to a typed password, or take its group's answer,
 > and two nullable ids express three of those. Naming neither id now means *inherit*, so
 > `HostSecret.AsksForPassword` was added to say "a typed password, even under a group that lends a key" out
 > loud. Nothing stored changed meaning — no group could lend a binding before this build, so every existing
 > host resolves exactly as it did.
 ## What was asked for
 A floating `+` at the bottom right of the phone's HOSTS screen, opening a menu at the bottom offering **new
 host** or **new group**.
 A **host** carries: which vault it is filed into (personal or a team's), an alias, a hostname or IP address, a
 group, tags, an SSH port, and a username with either a password or an SSH key.
 A **group** carries: an alias, an optional parent group, and a default SSH port, username and
 password-or-key — **defaults for the hosts inside it**.
 ## The shape of the problem
 Three of those fields do not exist at any layer, and one of them is refused on the record.
 | Asked for | What exists today |
 | --- | --- |
 | The `+` and the editors behind it | Nothing. `Theme/Phone.axaml` has no `.fab` class, and its comment says an unused style would be "a claim that the control exists somewhere". `HostsScreen.axaml`'s own v2 note says hosts are created on the desktop and sync down. *(This row named a `ConnectionsScreen.axaml` as a second site. No such file exists or ever has; and the `HostsScreen` statement is an XAML comment, so no phone screen ever rendered that sentence to a user.)* |
 | Vault picker | **Built.** `VaultViewModel.TargetVaults` / `SelectedTargetVault` / `HasVaultChoice`, hidden at one vault. The desktop's keychain screen already draws it. |
 | Alias, hostname, port, username, key-or-password, group | **Built**, in the shared `VaultViewModel` host editor — `EditorLabel`, `EditorHostname`, `EditorPort`, `EditorUsername`, `EditorAuthenticationChoices`, `EditorGroupChoices`, `SaveHostCommand`. The phone has never bound any of it. |
 | Tags | **Nothing.** `SyncEntityType.Tag = 5` and `HostTag = 6` are reserved slots with nothing behind them. `HostSecret` has no tag field. |
 | A group's parent | **Refused on the record.** `HostGroupSecret`'s own remark says groups are flat because two clients can each re-parent A under B and B under A offline, a scalar merge accepts both, and the result is a cycle no reader can draw and the server cannot see, because it is inside the payload. |
 | A group's defaults | **Nothing.** `HostGroupSecret` has exactly one field, `Label`. |
 So the phone half is mostly wiring. The domain half is three new capabilities, and one of them overturns a
 written decision.
 ## The three decisions
 **Tags are a real vault item, and a host names them.** A tag is a shared, reusable thing — the point of it is
 to put the same tag on twenty machines and filter by it later — so it needs an identity of its own, not a
 string repeated inside twenty payloads. `SyncEntityType.Tag = 5` becomes a live item kind. Membership is a
 `TagIds` set on `HostSecret`, **not** the reserved `HostTag = 6` join.
 The reason to skip the join is that the merge does not need it. The argument for `HostSecret.GroupId` living on
 the host is that filing two hosts into one group must be two writes to two items; the same holds here. What a
 join would have bought beyond that is two machines tagging *the same* host without one of them losing — and
 `ThreeWayMerge.Map` already gives that. It resolves a keyed collection key by key, honouring presence and
 absence, which is set semantics with removals. `HostOptions` is merged through it today via `ToNameMap()`, and
 a tag set keyed by tag id is the same shape. So `HostTag = 6` stays reserved and unused, and the second run
 through the item-kind checklist is not spent.
 **Group defaults are inherited, not copied.** A host that leaves a field blank uses its group's value; a host
 that fills one in overrides it. The editor shows the group's value as the field's placeholder, so the form
 says what leaving it blank will get you. Copying the values into the host at create time was the alternative
 and it was rejected: it makes a group a one-shot template rather than a live default, and changing a group
 would then leave every host that had ever been created under it pinned to the old value.
 **Groups get a parent, and the resolver breaks cycles.** `HostGroupSecret` gains `ParentId`. The editor refuses
 a parent that is already a descendant, which stops a cycle being made here; the resolver walks with a visited
 set and stops at a repeat, which contains a cycle that arrives from somewhere else. A cycle therefore degrades
 to a group that reads as a root — flat headings, defaults unresolved past that point — instead of hanging the
 connect path, and clearing the parent in the editor is the repair. **This is the load-bearing part of the
 decision:** with inheritance the chain is walked at connect time, so an unguarded cycle is not an undrawable
 sidebar, it is a shell that never opens.
 `HostGroupSecret`'s "No parent. Groups are flat." remark and `HostGroupSecretTests`' class remark both become
 false prose and must be rewritten to say what replaced the argument, not deleted. Same for the four rows in
 `docs/design-import-gaps.md` recording the phone's missing `+`.
 ## What the payload becomes
 ```
 HostSecret                            HostGroupSecret
  Label                                 Label
  Hostname                              ParentId            ← new, optional
  Port            int? — null inherits  DefaultPort         ← new
  Username        null inherits, "" none DefaultUsername    ← new
  Notes                                 DefaultSshKeyId     ← new
  JumpHostIds                           DefaultCredentialId ← new
  Options
  SshKeyId        null inherits       TagSecret
  CredentialId    null inherits         Label
  AsksForPassword ← new, true only
  GroupId         null = ungrouped
  TagIds          ← new
  RelayEnabled
 ```
 `Port` becoming `int?` is the change with the widest blast radius, and it is unavoidable: `int` with a default
 of 22 has no way to say "I have no port of my own". `HostSecret.DefaultPort = 22` stays, as the last fallback
 after the chain runs out.
 ### Three states where there were two
 `SshKeyId` and `CredentialId` both null currently *means* "ask for a password each time" — a decision, not an
 absence. `AuthenticationChoice`'s own remark argues at length that the two must never be conflated.
 Inheritance adds a state, so the picker needs an explicit **"Inherit from group"** entry beside **"Password
 (ask each time)"**, and `Bound(...)` needs to distinguish them. `Username` has the same problem: null means
 "no username" today and is refused at connect; it has to come to mean "inherit", with "no username" still
 reachable and still refused.
 **Built as four states, not three, because two nullable ids only carry three.** Key, credential, typed
 password, inherit — and naming neither id was the third and is now the fourth. `HostSecret.AsksForPassword`
 carries the difference: null is "not stated", which walks the chain and lands on a typed password if the
 chain lends nothing, and `true` is "a typed password, even under a group that lends a key". Only `true` is
 ever written, and a decoded `false` folds back to null, so a host that never touched the field encodes
 exactly as it did before it existed. `Username` needed no field — an empty string is "no username" and null
 is "inherit". `Port` needed none either: there is no "explicitly no port", only 22 at the end of the chain.
 Mutual exclusion moves with it. `HostSecret.TryValidate` enforces "a key or a credential, never both" per
 record; a host naming a credential under a group naming a key is two individually valid records that resolve to
 two bindings. **Exclusion has to be enforced at resolution**, host-over-group, and the resolver must never
 return both.
 ## The order to build it in
 Each step compiles and its tests pass before the next one starts. Steps 1–3 are the domain and are
 prerequisites for everything; step 4 is the only user-visible one.
 ### 1. `HostGroupSecret` grows
 `src/DodoSSH.Client.Domain/HostGroupSecret.cs`, `HostGroupSecretCodec.cs`, `HostGroupSecretMerge.cs`.
 - Add `ParentId`, `DefaultPort`, `DefaultUsername`, `DefaultSshKeyId`, `DefaultCredentialId`.
 - `TryValidate`: reject `Guid.Empty` for each id, reject a `ParentId` equal to the group's own id where that is
  knowable, apply the same 1–65535 range rule to `DefaultPort`, and refuse a group naming both a default key
  and a default credential.
 - **The codec needs the host codec's rule, which it does not have today.** `HostGroupSecretCodec` stamps
  `CurrentSchemaVersion` unconditionally. Copy `HostSecretCodec.SchemaVersionFor` — a *maximum over the fields
  actually present*, not a ladder — or upgrading one machine makes every group read-only on every other. A
  group carrying none of the new fields must still encode at version 1, byte for byte.
 - `HostGroupSecretMerge` gains the five fields, each a scalar.
 - Add a group byte pin mirroring `AddingTheKeyField_DidNotChangeTheBytesOfAHostWithoutOne`. The group codec has
  none, and the same "old vaults must re-encode identically" argument applies to it.
 ### 2. The `Tag` item kind
 `SyncEntityType.Tag = 5`, `CryptoSpec.AadResourceType.Tag = 8`, `ChangeEntityType.Tag = 5` and the
 `PublicAPI.Unshipped.txt` line **already exist** — no contract change, no crypto-spec change, no `docs/crypto.md`
 change. `LocalCacheProtector`'s AAD switch already maps `Tag`.
 New: `TagSecret.cs`, `TagSecretCodec.cs`, `TagSecretMerge.cs` in `DodoSSH.Client.Domain`; `TagCipher.cs`,
 `TagRepository.cs` in `DodoSSH.Client.Sync`. Edited: `Client.Sync/ItemKinds.cs` (registry entry + `TagKind`),
 `VaultSession.cs` (a `Tags` repository beside `HostGroups`), `Domain/Hosts.cs` (`VaultTag`),
 `Infrastructure/DodoDbContext.cs`, `Infrastructure/Configurations/HostAndSyncConfigurations.cs`,
 `Api/Features/Sync/ItemKinds.cs` (registry entry + server `TagKind`).
 **A server migration is required** — a tag is its own table. Generate it, do not hand-write it:
 `dotnet ef migrations add AddTagItem --project src/DodoSSH.Infrastructure`, committing all three resulting file
 changes. **No client migration**: `ClientCacheContext` has one `item` table keyed by `(VaultId, EntityType,
 EntityId)`, so a new kind is new rows.
 Four traps, all of which pass a naive test suite:
 - **`TagCipher` must say `AadResourceType.Tag` as a constant, never cast from `SyncEntityType.Tag`.** Tag is 5
  on the wire and 8 in the crypto enum. A cast seals tags under `Credential`, which encrypts and decrypts
  perfectly on the machine that wrote it and is a spec violation nothing notices until another implementation
  refuses the item — and the AAD is frozen into stored ciphertext. `AadResourceTypeTests` is the test that
  catches this, and it only catches it once `PinnedPairs` and `SealSample` have a Tag arm.
 - **The `ItemKinds.Registry` entry is what `SyncEngine` pulls with.** `SyncedTypes` is projected from it. Miss
  it and tags encrypt, merge and list perfectly on the machine that made them and are never once requested from
  the server.
 - **`TagKind.Fields` returns `null`, not an empty `SyncPlaintextFields`.** An empty record still serialises
  `relayEnabled: false`, which invites a reader to believe the type has a relay setting that is off.
 - **`ValidateFields` must refuse everything, with reasons.** There is no default; an unimplemented one accepts
  whatever arrives. `RelatedId` matters more here than it did for a group — it is the field a future `HostTag`
  would reach for, and `SyncPlaintextFields` is frozen so it cannot be removed. Follow `SnippetKind` and
  `ObjectStoreKind`, which are more complete than `HostGroupKind`.
 ### 3. `HostSecret` grows, and `Port` goes nullable
 `HostSecret.cs`, `HostSecretCodec.cs`, `HostSecretMerge.cs`, plus a new `TagSet` value type and a new resolver.
 - `TagSet` is a structural-equality wrapper in the shape of `JumpChain` — a plain `IReadOnlyList<Guid>` on a
  record gets reference equality from the compiler-generated `Equals`, which would make every host read as
  changed on every sync pass and two identical edits register as a conflict. Unlike `JumpChain` it is a *set*:
  order carries no meaning, so it sorts and dedupes, and it exposes a `ToIdMap()` for the merge.
 - `HostSecretMerge` merges `TagIds` through `ThreeWayMerge.Map`, per tag, so two people each adding a different
  tag to one host both keep theirs. It is not a scalar; a whole-value merge here would silently drop one side.
 - `Port` becomes `int?`. `TryValidate`'s `is < 1 or > 65535` is already false for null, which is the wanted
  behaviour but is silent — say so in a comment, and fix the message, which interpolates `{Port}` and renders
  empty for null.
 - **`SchemaVersionFor` needs branches for both new fields, and this is the one that loses data if forgotten.**
  A host with `Port = null` written at version 1 omits the property (`WhenWritingNull`); an older client
  deserialises `int Port` as 0, `TryValidate` refuses it, and the item reads as **unreadable rather than
  read-only** — gone, not locked. Add `PortInheritSchemaVersion = 5` and `TagIdsSchemaVersion = 5` (or 5 and 6)
  and make both bump the maximum.
 - **`AddingTheKeyField_DidNotChangeTheBytesOfAHostWithoutOne` pins the exact bytes** of a minimal host,
  including `"port":22`. A host that now inherits its port drops that key. Keep the pinned literal for a host
  with an explicit port, and add a companion for the inheriting one — do not edit the old literal to match
  whatever the code produces.
 - `TagIds` must serialise **last** in `HostPayloadDocument`, and empty must serialise as absent, or every host
  in every vault looks changed on the first sync after the upgrade.
 New file: the resolver. Given a host and the group list, walk `GroupId` then `ParentId` with a visited set,
 returning resolved port, username and binding, plus which group each came from — the editor needs the second
 half for its placeholders. It must never return both a key and a credential.
 ### 4. The shared view model, and the two heads
 `VaultViewModel` is where nearly all of it lands, and both heads get it at once because both bind the same
 properties.
 The choke points, from the connect-path trace:
 - **`TryBuildAuthentication(HostSecret, …)` and `TryBuildConnectionRequest(HostSecret, …)`** both take a bare
  `HostSecret` — this signature is where group context is currently lost. Both must take the resolved value.
  This is the single highest-leverage change: it is the only auth resolution in the product, and both heads
  and both transports go through it.
 - The credential-username fallback becomes three levels: credential → host → group chain.
 - `Complete(...)` must refuse on an empty username only *after* the chain has been consulted.
 - `HostRowViewModel.Address`, `Dialled`, `TransfersViewModel`'s connected-to label and
  `TerminalWorkspace.Describe` must show the **dialled** address. `MainWindowViewModel.Rank` searches
  `Address`, so an unresolved one makes hosts unfindable by their real port.
 - **`HostFields.From` in `HostCipher` must emit the resolved port.** This is the one place where an unresolved
  read is a wrong wire rather than a wrong label: it fills the relay's plaintext columns, which is what the
  *server* dials. A relay host with a null port also fails server validation outright.
 - Host-key pinning keys on host and port. `ForgetHostKeyAsync` and the "pin in use" endpoint set read
  `row.Host.Port` directly — a host inheriting 2222 pins under 2222 while both look under 22.
 - `HostRowViewModel.Authentication`, `SelectedHostAsksForAPassword` (in **both** `VaultViewModel` and
  `TransfersViewModel`) and `SelectedHostAuthenticationNote` all switch on the host's own two ids and must
  switch on the resolved binding, with new wording for a binding that came from a group.
 - **`HostsBoundTo`** counts hosts naming a key explicitly. A key deleted while only a *group* names it warns
  nobody and then refuses every host under that group at connect time. It must walk groups too.
 - The editor: load must distinguish "unset" from "explicitly this", `BuildHost` must preserve that in both
  directions, and each field needs the resolved value as its placeholder.
 - `ImportViewModel.IsAlreadyPresent` compares port and username directly, so a stored host inheriting 22 will
  never match an imported host at 22 and the import screen re-offers duplicates. Decide whether an imported
  block with no `Port` should inherit rather than pin 22 — `SshConfigResolver` returns `DefaultPort` today.
 ### 5. The phone
 `Views/HostsScreen.axaml` and `Theme/Phone.axaml`. No csproj edit — Avalonia globs `**/*.axaml`. Compiled
 bindings are on, so a binding to a property that does not exist is a build error; `TreatWarningsAsErrors` is on
 repo-wide, so any XAML warning fails CI.
 - A `Button.fab` style, and the comment that currently refuses one rewritten to say what it now opens.
 - The `+` needs a `Panel` wrapping the screen's root `Grid` so it can sit bottom-right without moving. Placing
  it inside the list row would put it above the connect bar, which appears and disappears with the selection.
 - The bottom sheet follows `HostKeySheet.axaml`, the head's one existing sheet: a scrim
  (`Border Background="#9E0E1220"`, a literal because the palette holds no alpha surface), a bottom-aligned
  `Border` with `CornerRadius="22,22,0,0"`, a decorative grab handle, and **no tap-to-dismiss** unless it is
  wired by hand, because nothing on this head implements it.
 - **Scrim reach is a real choice.** Declared inside `HostsScreen`, a scrim darkens the screen area only and the
  64px nav bar stays lit and tappable. To cover the display the sheet has to sit in `PhoneShell.axaml` beside
  `HostKeySheet`, which is exactly why that control lives there.
 - **The back gesture needs a new guard**, above the `switch` in `PhoneShell.axaml.cs`, in the shape of the
  host-key guard: back should close the sheet or the editor rather than leave the screen. The comment on that
  method states an invariant about the switch cases staying in step with the surface tests — so add a guard,
  do not extend the switch. *(This named `IsVaultsSurface` and `IsConnectionsSurface`. Neither exists
  anywhere in the repo; the real properties are `IsMoreSurface` and `IsTerminalSurface`, and only the first
  is what the switch mirrors.)*
 - The editors follow `SnippetsScreen.axaml`: a `Border Classes="card"` in the same grid row as the list,
  toggled on `IsEditing`, with the list toggled on `!IsEditing`. There is no dialog, no modal and no
  editor-screen anywhere on this head, and the reason is written down — a form stacked over the list hides what
  it is about.
 - Editing an existing host comes nearly free: the shared `IsEditing` panel serves both, so the connect bar gets
  an EDIT button beside CONNECT. Not asked for, but a `+` that adds hosts with no way to correct one is a
  strange thing to ship.
 ### 6. Tests
 House style: `Subject_Predicate`, articles included, the predicate smuggling in the reason
 (`_RefusesRatherThanFallingBackToThePassword`). No `Async` suffix on test methods; always on private helpers.
 Every class carries a remark naming the class of failure it exists to catch. xunit.v3 + Shouldly, with the
 because-string used as prose.
 - Three shared builders need the new fields: `Domain.Tests/HostFactory.cs`, `Sync.Tests/SyncHarness.cs`,
  `Sync.Tests/HostCipherTests.cs`. There is no shared group factory and with five new fields there should be.
 - Three guard tests fail by design and that is what they are for:
  `HostSecretMergeTests.EveryScalarField_IsRoutedThroughAMerge` (note `GroupId` is missing from its `with`
  block today — an existing gap worth closing while there) *(closed: `GroupId` is in that block now)*,
  `ValueSemanticsTests.TryValidate_RejectsWhatCannotBeStored`, and the two "groups are flat" remarks.
 - `ItemKindsTests.ThePullFilterNamesEveryTypeThisBuildSynchronises` is an ordered list — add Tag in registry
  order. `AadResourceTypeTests` needs `PinnedPairs`, a `SealSample` arm and a `NewTag()` builder.
 - `SyncEndpointTests.AHostGroupCarryingAParent_IsRejected` asserts the server refuses a plaintext `ParentId`
  with a reason containing "flat". Putting the parent **inside the payload** does not break it mechanically,
  but its stated reason becomes wrong. It should survive with a rewritten comment — the parent lives in the
  payload, the plaintext column stays refused, and ADR 0004 is why. Decide that deliberately rather than
  letting it drift. *(Decided that way, and the name says it now:
  `SyncEndpointTests.AHostGroupCarryingAPlaintextParent_IsRejected`. The column is still refused and the
  reason is the trust model rather than flatness.)*
 - `Push_AnUnsupportedEntityType_IsInvalidNotAFailedBatch` picks the first type with no kind registered, very
  likely Tag today. It self-heals to `HostTag` via `Assert.SkipWhen`.
 - `App.Layout.Tests` measures pixels and bends rather than breaks. Extend the seeders — nesting and a tag row
  change what the widest realistic content is — rather than the assertions. `ScreenLayoutTests.cs:1310` pins
  `ChangedFields = "Hostname, Port, Username, Options, Group"` as a literal; add `Tags` to keep it measuring
  the worst case.
 - `ShellFlowTests.ReadyToConnectAsync` gives its host both a username and a port, so the inheritance tests need
  a host with neither, or the group is never the source.
 ## Found on the way, and out of scope
 `LocalCacheProtector`'s AAD switch is missing `ConnectionLogEntry`, `ActivityLogEntry` and `ObjectStore`, so
 `ConflictStore.Record` throws `ArgumentOutOfRangeException` on a conflict for any of those three. Pre-existing,
 unrelated to any of this, and `Tag` is already in that switch. Worth a separate fix.
 > **Fixed 2026-08-04**, having outlived the phases that shipped the logs and the buckets — which is exactly
 > the drift a note like this is meant to prevent, so it is worth saying what let it last. Of the three callers
 > of `AadResourceTypes.For`, two reach it only when an item carries plaintext fields and none of these three
 > does; the third, `ConflictStore.RecordAsync`, calls it unconditionally but is reached only by a real merge
 > conflict, which every existing test raised against a `Host`. The arms are in, and two tests now hold them
 > there: `CacheStoreTests.AConflict_CanBeRecordedForEveryKindOfItem` records one per kind, and
 > `AadResourceTypeTests.EverySyncableType_HasAnArmInTheStorageMapping` fails on the *next* item type added
 > without one, by name rather than by a list kept by hand.
 ## Prose that becomes false
 Not a tidy-up — these are the places the codebase currently tells a user or a maintainer that this feature is
 deliberately absent, and each states a reason that will no longer hold.
 - `Theme/Phone.axaml` — the "No floating action button" block.
 - `Views/HostsScreen.axaml` — the v2 and v3 notes on the missing `+`.
 - ~~`Views/ConnectionsScreen.axaml`~~ — **this file does not exist and never did.** The real inventory is
  the two above plus `README.md`, `docs/android-port.md` and `docs/design-import-gaps.md`. Neither phone
  site was "rendered on screen": both are XAML comments.
 - `HostGroupSecret.cs` and `HostGroupSecretTests.cs` — "No parent. Groups are flat."
 - `docs/design-import-gaps.md` — the **Add host** row, the two floating-button rows, the "Tag / HostTag still
  reserved and unused" paragraph, and the tag-chips and groups-on-a-team's-hosts rows in the Hosts table.
@@ -160,7 +160,7 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
 > | **Share this host** | Omitted, as the vault screen's `SHARED WITH · 6` is. A grant is per *vault* and per-item sharing is M5; a button here would imply this one host could be handed over, which is the thing the architecture does not do. |
 > | **Add Telnet**, and **Serial** in the toolbar | Omitted. `ISshConnection` is the only transport there is. This is also why the card subtitle's `ssh` is a constant today rather than a reading — it is stated in `HostRowViewModel.Summary`, which is the one place in this interface where a constant is printed on purpose. |
 > | **+ SSH ID, Certificate, FIDO2** | Omitted. `IDENTITIES` and `CERTIFICATES` have been on this document's list since the first import — neither is even a reserved `SyncEntityType` — and there is no security-key path anywhere in the SSH layer. One control offering three item types that do not exist. |
-> | The **Backspace / Default** row | Omitted. It is a terminal setting, and the client has no preferences store and no frame to carry one to the renderer — see the Preferences section. It would be a control whose value could not survive the window closing. |
+> | The **Backspace / Default** row | Omitted, and it is the one row on this list that could now be built cheaply — a setting, an opcode and a control, the way the text size was. What it lacks is a reason: which byte backspace sends is a fact about the remote's `stty`, so a client-side switch fixes a mismatch by hiding it. See the Preferences section. |
 > | The **chevron beside the vault name** | The name alone, and the move behind the pane's ⋯ menu instead. A host *can* now be moved between vaults, so the gap is no longer that there is nothing to offer — it is that a chevron on a subtitle implies an edit, and this is not one: the two vaults are encrypted under different keys, so it is a re-seal into one and a tombstone in the other, the host takes a new id, and its group and tags stay behind. A control that implied "just change this field" would be describing something else. Where a *new* host goes is still asked in the host editor, as a picker beside the name. A group moves too, from its card's right-click menu, and takes its nested groups and every host filed under them; keys, passwords and buckets take theirs from the keychain screen's standing picker and cannot be moved yet. |
 > | **Show more ⌄** | Not drawn as a disclosure. What it would hide — notes, the relay switch, forgetting the host key — is in the editor, one press away, and a second fold inside a pane that already scrolls is a second place for a field to be missing from. |
 > | **Port Forwarding** in the sidebar | Nothing, for the third time in this document. |
@@ -173,8 +173,9 @@ it for revocation, for relay session recording and for what locking does not do
 rendered with invented data to make a screenshot look finished. Where a feature does not exist, the
 interface either omits it or says so.
-Read alongside [the milestone plan](../README.md#milestones). Most of what follows is not a defect; it is
+Read alongside [the milestone plan](../README.md#milestones). Most of what follows is not a defect. M2 and
-M2 and M3 arriving in a design before it arrives in the code.
+M3 have since arrived and their rows say so; what is left is either M5 — per-item content keys, and the
 sharing that would rest on them — or a decision recorded here not to build the thing at all.
 ## The shape of the problem
@@ -204,9 +205,12 @@ reason and is gone: membership is granted only to an account that exists, so the
 reservation fails to cover. The status stays reserved, because the column holds it in nobody's database and
 a client must not fail on a value a later server might send. See [ADR 0009](adr/0009-team-access-model.md).
-**The client has no preferences store.** It writes exactly two files — `cache.db` and `device.key` — and the
+**The client's settings file holds two things.** It writes three files — `cache.db`, `device.key` and
-cache has six tables, none of them settings. Nothing on the design's TERMINAL preferences panel can be
+`settings.json` — and the cache's six tables still hold none of them. `ClientSettings` carries the
-saved, and there is no frame on the terminal data plane that would carry a change to the renderer anyway.
+terminal's text size and whether this machine looks for a newer build on its own, and both survive a
 restart. Everything else on the design's TERMINAL panel is unbuilt rather than unbuildable: the data plane
 grew `TerminalServerOpcode.FontSize` to carry the one that shipped, so a second option is an opcode, a
 setting and a control rather than a new mechanism.
 **Three things the design did not ask for and this build now has.** A key can be generated in the client
 rather than pasted in (`SshKeyGenerator`, and the `openssh-key-v1` container is written by hand — see
@@ -326,7 +330,7 @@ caption buttons and window title drawn on top of the application's own — two s
 | Pane header showing the running command and `following` | client-ssh | The host moves opaque bytes and never parses terminal output. Would need shell integration (OSC 133) on the remote. | Omitted. |
 | A `local · zsh` tab | client-ssh | Every session here is an SSH channel. Needs ConPTY and a second session kind. | Omitted. |
 | Tab strip `+` button | ui | Not missing so much as redundant: the real operation is *select a host, press Connect*, which the hosts grid already is. | **Shipped**, as the palette rather than a menu: it opens what Ctrl+K opens, so the strip and the shortcut are one way of doing one thing. A `MenuFlyout` offering "SSH" and "local shell" is the nicer answer and is not verifiably safe above the terminal's native child window — and there is no local shell to offer. |
-| Terminal font size (`--termfs`, 11–16px) | client-storage | See preferences. | Fixed at the renderer's 13px. |
+| Terminal font size (`--termfs`, 11–16px) | client-storage | — | **Shipped**, and wider than the design's range: 8–32px from the preferences screen or Ctrl+plus/minus/0 over a terminal, carried by `TerminalServerOpcode.FontSize` and kept in `settings.json`. It resizes the grid rather than magnifying it, so every live pane refits and the remotes are told how many columns they now have. |
 ---
@@ -350,11 +354,11 @@ connect, and it goes through the same host key gate, the same pin and the same t
 | Remote listing with `NAME/SIZE/MODIFIED/PERMS` | client-ssh | All four. `PosixMode` renders `drwxr-xr-x` from the bits SFTP hands over; setuid, setgid and sticky are not shown, because SSH.NET does not surface them and `rwx` where `rws` is true would be worse than nothing. |
 | Local listing | client-transfer | `LocalDirectory`, which is where this client's `System.IO` now lives. `PERMS` is blank on the local side rather than filled with a plausible-looking POSIX mode that is not a fact about a file on Windows. |
 | Transfer queue, progress, throughput | client-transfer | `FileTransferQueue`. One transfer at a time, so the rate on a row is the rate of the link rather than a share of it. Throughput is measured over a half-second window, not averaged since the start. |
-| `resume supported` | client-transfer | **Within a run of the application.** Every transfer writes to a `.dodossh-part` file beside its destination and is renamed into place at the end, so an interrupted one can never be mistaken for a finished one, and `RESUME` carries on from the part file's own length. A part file found at startup is *not* resumed: nothing records what wrote it, and resuming on the strength of a name matching is how a corrupt artefact gets delivered with nothing reporting a failure. Making it survive a restart needs the preferences store this client has not got — see below. |
+| `resume supported` | client-transfer | **Within a run of the application.** Every transfer writes to a `.dodossh-part` file beside its destination and is renamed into place at the end, so an interrupted one can never be mistaken for a finished one, and `RESUME` carries on from the part file's own length. A part file found at startup is *not* resumed: nothing records what wrote it, and resuming on the strength of a name matching is how a corrupt artefact gets delivered with nothing reporting a failure. Making it survive a restart needs somewhere to record *what* wrote each part file — the source, the offset and the run — which is a table rather than a setting; `settings.json` holds two scalars and is not that. |
 | Design element | Layer | What it would take | What ships instead |
 | --- | --- | --- | --- |
-| Per-host last directory | client-storage | Somewhere to persist two panes' navigation state. There is still no settings table. | The remote pane opens on the account's home directory, which the server canonicalises during the handshake; the local pane opens on the user profile. |
+| Per-host last directory | client-storage | Somewhere to persist two panes' navigation state per host, which is a table rather than a scalar — `settings.json` holds two of those and is the wrong shape for a row per machine. | The remote pane opens on the account's home directory, which the server canonicalises during the handshake; the local pane opens on the user profile. |
 | `sftp over bastion-eu` | client-ssh | Jump hosts, as above. `HostSecret.JumpHostIds` is still stored, synced, merged and read by nothing. | Omitted. |
 | Overwriting a file that is already there | ui | A prompt, which means a modal this window has no idiom for. | Refused, with the name that is in the way. The remote pane has DELETE and MKDIR so the refusal is not a dead end. |
 | Dragging between the panes | ui | Drag-and-drop between two `ListBox`es, plus a drop target that is a directory rather than a row. | Two arrow buttons between the panes, pointing at the pane the file is going to. |
@@ -476,8 +480,8 @@ lists the rest as absent rather than omitting it silently.
 | Design element | Layer | What it would take |
 | --- | --- | --- |
-| Any preference, saved | client-storage | A seventh table in the client cache, or a preference item type in the vault. Which one matters: the vault syncs, so a preference stored there follows you between machines, and a terminal font size probably should not. |
+| Any preference, saved | — | **Two are.** `settings.json` beside the cache holds the terminal's text size and whether this machine checks for updates on its own. It is deliberately not in the vault: the vault syncs, so a preference kept there would follow you between machines, and a font size chosen for a laptop screen should not arrive on a desktop. Anything per-host or per-item wants a table instead — see the transfers rows above. |
-| Terminal font, size, cursor style, cursor blink, scrollback | client-terminal | The store, **and** a frame to carry it. `TerminalServerOpcode` has four values (`Output`, `SessionOpened`, `SessionClosed`, `SessionActivated`) and none carries an option. |
+| Terminal font, cursor style, cursor blink, scrollback | client-terminal | A setting, an opcode and a control, in that order — the mechanism is no longer the obstacle. `TerminalServerOpcode.FontSize` proved the path and `ClientSettings` is where the value would live; what none of these four has is somebody deciding it is worth a row on the preferences screen. |
 | Font family picker offering IBM Plex Mono | ui | Shipping the font, as above. |
 | Audible bell | client-terminal + ui | xterm.js 6 removed `bellStyle` and `bellSound`; what remains is an `onBell` event, so the page would have to make the sound itself. |
 | `GENERAL` section | ui | There is no general setting to put in it. The theme is fixed by decision, and window size is not persisted. |
@@ -0,0 +1,201 @@
 # Reaching a host you cannot dial
 Some machines do not answer from where the user is sitting. This product has **two** answers to that, and
 neither of them works.
 - The **relay** pipes raw TCP through the deployment. The server half is built and shipped; the client
  half does not exist, and both heads offer a checkbox that promises it.
 - A **jump host** reaches the target through a machine already in the keychain. `HostSecret.JumpHostIds`
  stores the chain; nothing writes it and nothing reads it.
 This document is the comparison between them, which is the thing that has to be settled before either is
 built, and then the plan. It replaces an earlier draft of `docs/jump-hosts.md` that recommended deleting the
 jump chain — see the last section for why that was wrong.
 > **Status: step 0 done, the rest planned.**
 >
 > | Step | State | Notes |
 > | --- | --- | --- |
 > | 0. Stop promising the relay | **Done** | Both heads say the box is not wired up and that ticking it stores the address and changes nothing. Left tickable, so a host already carrying the flag can lose it |
 > | 1. The loopback bridge | Not started | ADR 0004's "one mechanism, two features" |
 > | 2. Jump hosts over it | Not started | No server change at all |
 > | 3. The relay over it | Not started | Ticket call, WebSocket, then the same bridge |
 > | 4. File transfer parity | Not started | The transfers screen opens its own connection |
 ## ◆ The relay's checkbox is a false promise, and that is a defect
 `HostSecret.RelayEnabled` is stored, validated — a relay host may not inherit its port — encoded, merged,
 and drawn as a checkbox in the host editor on **both** heads. The desktop's says *"Connect through the
 server relay"* and warns underneath that the address will be stored on the server in plain text. The
 phone's says the same at more length.
 Nothing on the client reads it. `VaultViewModel` builds `SshConnectionRequest(hostname, port, username,
 credential)` and `SshNetConnectionFactory` dials that address directly, whether the box is ticked or not.
 So a user who ticks it **pays the privacy and gets nothing**: the host's address and port leave the
 encrypted payload and land in plaintext columns on the server — the one deliberate concession in the whole
 design, per ADR 0004 — and the connection is still made from their laptop to the machine they already could
 not reach. It then fails exactly as it did before, with no hint that the box did nothing.
 This is worse than the jump chain, which is invisible and harmless. It is a control that spends something
 real.
 **Step 0 is done.** Both heads now name the absence in the label and lead the paragraph under it with what
 ticking the box actually does today — the way this codebase already handles port forwarding on the phone's
 More screen. It is left *tickable* rather than disabled, deliberately: a host that already carries the flag
 has to be able to lose it, and a disabled control would trap the concession on. The sentence comes out again
 at step 3.
 ## The comparison
 Both answers put something between the user and a machine they cannot dial. What differs is *what* is in
 between, what it costs, and who has to own it.
 | | Relay | Jump host |
 | --- | --- | --- |
 | **Reaches** | Anything the **deployment** can reach | Anything a **machine already in the keychain** can reach |
 | **Asks of the deployment** | It must sit where it can dial the target, and have the relay enabled | Nothing. The server is not involved at all |
 | **Tells the operator** | The host's address and port, in plaintext columns, for every opted-in host — plus an audit row per session: target, duration, bytes, close reason, client IP | Nothing beyond the sync metadata every item already produces |
 | **The intermediate's credentials** | None to manage. The deployment is the intermediate | The bastion is an ordinary host: its own key or password, its own host key to pin, its own group defaults |
 | **Where SSH terminates** | On the laptop. The relay sees ciphertext, and ADR 0004 is emphatic that no recording is possible | On the laptop. The bastion forwards a TCP stream inside a session the user opened to it |
 | **When it is unavailable** | Deployment down, no connection — including to hosts that were reachable directly | Bastion down, no connection to what is behind it |
 | **Fits an estate where** | The DodoSSH server is *inside* the network the targets are on | A bastion is the policy and the server is outside — which is the ordinary enterprise shape |
 | **Auditable by the operator** | Yes, coarsely, and that is a feature for a team deployment | No, and that is a feature for a private one |
 **The two are not substitutes, and the deciding question is where the deployment sits.** The relay only
 answers "unreachable" when the server has line of sight the laptop lacks — a deployment inside the VPC, on
 the office network, on the same Tailnet. Point it at a self-hosted box outside the target's network, which
 is what most people running this on a VPS will have, and the relay reaches nothing the laptop could not
 already reach.
 **And you do not get to choose other people's topology.** Shipping this to strangers means shipping into
 estates whose shape is already decided, and bastion-fronted is the common one. Their `ssh_config` says so:
 the importer reads `ProxyJump`, records it as an option and writes a note on the host saying *"DodoSSH does
 not route through a jump host yet"* — a first-run experience that names the limitation on the hosts it
 matters for.
 **A relay is not a bastion with better manners.** ADR 0004 rejected "server terminates SSH" and kept
 zero-knowledge, which is right and is not what a jump host asks for either: forwarding a TCP stream through
 a machine the user has authenticated to reveals nothing to the operator, because the operator is not in it.
 The privacy ordering is the opposite of what the ADR's framing suggests — the relay is the mechanism that
 costs a plaintext address, and the jump host is the one that costs nothing.
 ## They are one piece of work, and ADR 0004 says so
 The last consequence in ADR 0004, written before either half was built:
 > On the client, SSH.NET cannot be handed a pre-connected stream, so the relay is reached via a loopback TCP
 > bridge. The same bridge provides ProxyJump via a SOCKS5 dynamic forward — **one mechanism, two features**.
 That is the plan, and it holds up against the pinned package. SSH.NET 2025.1.0 offers
 `ForwardedPortDynamic`, which is a SOCKS5 proxy served over an established `SshClient`, and
 `ConnectionInfo(host, port, username, ProxyTypes, proxyHost, proxyPort, proxyUsername, proxyPassword,
 AuthenticationMethod[])` with `ProxyTypes.Socks5` — checked in `Renci.SshNet.xml` rather than remembered. So:
 - **Jump host:** connect to the bastion as an ordinary host, `AddForwardedPort(new ForwardedPortDynamic(0))`
  on it, then dial the target with a `ConnectionInfo` pointed at that loopback SOCKS5 port. A chain of two
  is the same trick twice.
 - **Relay:** the same shape with a different thing on the loopback socket — a listener that pipes bytes into
  the `dodossh.relay.v1` WebSocket instead of into a bastion's forward.
 Which means the transport work is shared and the ordering is: bridge, then the cheap feature, then the one
 that needs the server.
 ## The work, in order
 **0. Stop promising the relay.** The checkbox states that the relay is not wired up yet. One line on each
 head, and it is the only step that should ship on its own.
 **1. The bridge.** A loopback `TcpListener` on an ephemeral port that accepts exactly one connection, hands
 it to a `Stream` supplied by whoever opened the bridge, and disposes with the session. It belongs in
 `Client.Ssh` beside `SshNetConnectionFactory`, and it needs to bind `127.0.0.1` explicitly — a bridge on
 `0.0.0.0` is an open SOCKS proxy on the user's network for the life of a shell.
 **2. Jump hosts.** No server change. In order:
 - `SshConnectionRequest` grows a route: the resolved chain, each hop carrying what a connect needs, so the
  SSH layer is handed hops rather than ids and never looks anything up.
 - `VaultViewModel` resolves `JumpHostIds` to hosts in the same vault, applying group inheritance per hop the
  way the target already gets it, and refuses a chain that crosses a vault — the same refusal
  `RefusesTheDrop` and the group picker already make, for the same reason.
 - Per-hop host keys. Each hop is a separate handshake against a separate endpoint, so the pin, the unknown
  key prompt and the changed-key refusal run per hop. **The prompt has to name which hop it is about**, or
  somebody approves a bastion's fingerprint believing it is the target's — see `HostKeyCard`, which is built
  around one connection and one question.
 - Per-hop credentials, including a hop that wants a typed password. `IsAskingForConnectPassword` asks about
  one host today.
 - Teardown: the hops belong to the outer session and go with it, including when the outer connect fails
  half way. A leaked bastion connection is an open session on a machine the user believes they left.
 - The schema version. A chain becomes a real field, so it joins the ladder in `HostSecretCodec` — a host
  carrying one must not be editable by a client that would drop it. That is the whole point of the rule.
 - The editor: a picker over other hosts in the same vault, and the host detail's subtitle finally getting
  the `⤷ bastion-eu` the design asked for.
 **3. The relay.** `POST /relay/tickets` with the host id, then the WebSocket with the ticket in
 `Sec-WebSocket-Protocol`, piped into the bridge from step 1. The ticket is single-use and expires in 30
 seconds, so it is fetched per connect and never cached. Then the checkbox from step 0 becomes true.
 **4. File transfer.** `ISftpSessionFactory.OpenSftpAsync` opens its own second connection, so a host that
 needs a chain or a relay to reach needs it there too, or SFTP silently fails for exactly the hosts this
 work exists for.
 ## Traps already known
 **A relay host may not inherit its port, and a jump host has no such rule.** `TryValidate` enforces the
 first because the server stores the port and a group edit would silently change what the relay dials. The
 chain has no plaintext counterpart, so it inherits normally — do not copy the restriction across out of
 symmetry.
 **Two hosts can name each other.** A chain is ids, and nothing stops A jumping through B while B jumps
 through A. Resolve iteratively with a visited set and refuse a cycle before dialling anything, rather than
 discovering it as a stack overflow inside a connect.
 **The bastion's own group defaults matter.** A hop is a host, so it resolves its port, username and binding
 through `HostInheritance` exactly as the target does. Skipping that dials 22 as nobody on a bastion that is
 on 2222 as `deploy`.
 **`ForwardedPortDynamic(0)` and reading the port back.** Binding an ephemeral port and then asking for the
 one that was assigned is the part that varies between SSH.NET versions; pin it with a test that opens one
 against the test `sshd` rather than trusting the number.
 **The relay bridge and the jump bridge are the same class and not the same lifetime.** A ticket is
 single-use with a 30-second expiry; a bastion's forward lives as long as the session. Sharing the listener
 is right, sharing a lifetime policy is not.
 ## Tests
 - A two-hop connect against the Testcontainers `sshd`, which `Client.Ssh.Tests` already stands up — one
  container as bastion, one as target, with the target refusing connections from anywhere else.
 - A cycle in a chain is refused before any socket is opened.
 - Each hop's host key is asked about separately, and the question names the hop.
 - A chain crossing a vault is refused with a reason, as the group picker's is.
 - The bridge binds loopback only — assert the bound address, because the failure is silent and the
  consequence is an open proxy.
 - SFTP to a host behind a chain, once step 4 lands.
 - Mutations that must fail something: bind the bridge on `IPAddress.Any`; drop the visited set; skip group
  inheritance for a hop; and tear down the outer session without the hops.
 ## Prose that becomes false
 - `docs/design-import-gaps.md` — the host subtitle's `⤷ bastion-eu` row, the SFTP `sftp over bastion-eu`
  row, and the status bar's `via bastion-eu` row, all of which say jump hosts are data-only.
 - `Client.Import/ImportedHost.cs` — the note written onto every imported host with a `ProxyJump`, and the
  remark above it.
 - `README.md` and `docs/android-port.md` wherever the relay is described as available.
 - ADR 0004 gains a note that its last consequence was built, and how.
 ## What the first draft of this document got wrong
 It recommended deleting `JumpHostIds`, on the evidence that nothing writes it, nothing reads it, and it is
 missing from the schema-version ladder. The first two facts are true and the conclusion did not follow.
 Two things were missed. **ADR 0004 had already designed the implementation** — the loopback bridge, the
 SOCKS5 dynamic forward, "one mechanism, two features" — so the transport was a solved problem sitting in an
 accepted ADR, and the fortnight that draft estimated was priced without it. And **the stored shape is
 right**: an ordered list of host ids is exactly what a chain is, the merge arm is already correct, and the
 missing schema version is a line to add rather than evidence of a bad model.
 The lesson is narrower than "read the ADRs": it is that *nothing reads this field* was taken as evidence the
 field was a mistake, when it was evidence of an unfinished feature — and the same reasoning applied one
 paragraph further would have found the relay checkbox, which is the same shape and is actively lying to
 users.
@@ -0,0 +1,195 @@
 # Unlocking without the passphrase
 Every account here is issued a recovery code at enrollment. It is generated on the client, it wraps the
 identity bundle, the server stores that wrap, and both heads go to some trouble to make sure the user writes
 it down — the phone raises `FLAG_SECURE` for that screen alone and refuses to let anybody click past it.
 **Nothing can use it.** There is no code path in this product that opens a recovery wrap. This document is
 the plan for the change that fixes that, and it is written to be picked up cold.
 > **Status: planned. None of the six steps below is built.**
 >
 > | Step | State | Notes |
 > | --- | --- | --- |
 > | 1. The endpoint that serves the wrap | Not started | `GET /api/v1/me/recovery-wrap`, and deliberately not `/me` |
 > | 2. `SessionOpener.UnlockWithRecoveryAsync` | Not started | The unwrap, then the path `UnlockAsync` already takes |
 > | 3. Setting a new passphrase | Not started | `PUT /api/v1/me/wrap`. Delivers *change passphrase* as well |
 > | 4. Both heads | Not started | A way in from the unlock screen, and a box for the code |
 > | 5. The prose that becomes false | Not started | Three shipped claims disagree with each other today |
 > | 6. `crypto.md`'s status note | Not started | "One of four ways" is one of two, and will be one of three |
 ## What is wrong
 Walk the failure through, because it is worse than a missing feature.
 Forget the passphrase and the identity bundle cannot be unwrapped. No bundle means no vault keys, and no
 vault keys means every item in every vault is unreadable. Signing out and back in does not help: the server
 hands back the same passphrase wrap. The device key would be the other door, and **sign-out withdraws it** —
 which is the advice the unlock screen gives for exactly this situation. The recovery wrap sitting on the
 server is the only thing left, and nothing opens it.
 So the loss is total and permanent, and the thing built to prevent it is inert.
 Meanwhile the product says three things about this, and they do not agree with one another:
 | What it says | Where | True today |
 | --- | --- | --- |
 | "The code is the only thing standing between a forgotten passphrase and an unrecoverable vault" | `docs/manual-checks.md` §10.2 | **No.** It stands between nothing |
 | "losing it *along with* the passphrase means the vault is unrecoverable" | `docs/android-port.md`, state 4 | **No.** It implies the code alone is enough |
 | "Signing out … is the only answer to a forgotten passphrase — nothing can recover one" | `README.md`, Locking | Yes, and it contradicts both of the above |
 The third is the honest one. That is the state this plan changes, and until it does, the first two are the
 two sentences in this repository most likely to cost somebody their keychain.
 ## What already exists
 More than half of it, which is why this is worth doing now rather than treating as a feature.
 - **The code.** `ClientEnrollment.GenerateRecoveryCode` — 160 bits, base32 over a 32-character alphabet with
  `I`, `L`, `O` and `U` left out so a transcription cannot land on a different valid code, printed as
  32 characters in groups of five.
 - **The wrap.** The same class derives `KEK_rc` under `Argon2Profile.RandomSecret` (64 MiB, 3 passes) and
  sends `RecoveryWrappedPrivateKey` and `RecoveryKdfParameters` with the enrollment.
 - **The row.** `EnrollmentService` stores it as `UserKeyWrapKind.Recovery`, beside the passphrase and device
  wraps.
 - **The specification.** `docs/crypto.md` §2 gives the parameters for `KEK_rc` and §3 puts the wrap in the
  key hierarchy beside the passphrase and device ones. Nothing below needs a spec change.
 - **The cache.** `LocalCacheKey` derives from the identity bundle under `dsh1/localcache/v2`, not from `MK`
  — see the changed-2026-07-30 note in `crypto.md` §3.2. That change was made partly *for* this: a recovery
  unlock derives a different `MK` and would otherwise open the identity and then fail to read the cache it
  had itself written. It is already paid for and currently untested from this direction.
 ## What is missing, exactly
 | | Gap | Where it lands |
 | --- | --- | --- |
 | A | Nothing serves the wrap. `MeResponse` carries `WrappedPrivateKey` and `KdfParameters` — the passphrase pair, and only that | `DodoSSH.Contracts`, `Api/Features/Identity` |
 | B | No unlock path. `SessionOpener` has `UnlockAsync` and `UnlockWithDeviceAsync`, and nothing else | `Client.Session` |
 | C | No way to set a new passphrase afterwards. No endpoint, no client path, no UI | server + client |
 | D | No way in from either unlock screen | `UnlockCard.axaml`, Android `LockedScreen.axaml` |
 The device wrap is not a precedent for A: it is cached locally in `StoredUnlockMaterial` at the moment it is
 registered, so it never has to be fetched.
 ## The decisions, and the reasons
 **A separate endpoint, not `/me`.** `GET /api/v1/me/recovery-wrap`, called only when somebody has said they
 have forgotten their passphrase. `/me` is fetched by every client at every launch, and putting the recovery
 wrap in it would hand that blob to anybody holding a stolen OIDC session, permanently, for no benefit. The
 wrap's real defence is Argon2id over 160 bits and it does not stop being safe in the response — this is the
 cheaper rule of not serving what nothing needs. It answers 404 for an account with no recovery row, which is
 every account enrolled by a client that did not send one.
 **Online only, and the screen says so.** The wrap is deliberately *not* added to `StoredUnlockMaterial`.
 Caching it would put a second door on every laptop, protected by a weaker KDF profile than the passphrase
 one, for a case that already requires a network — recovery begins with signing in.
 **Setting a new passphrase is part of the flow, not a follow-up.** Without it the account unlocks with a
 one-time code forever, and the code is a thing people keep on paper. This is the same re-wrap a *change
 passphrase* feature needs, so step 3 delivers both; change-passphrase is then a button, not a project.
 **The identity key is not rotated.** Rotating it would invalidate every vault key grant the account holds
 and force a rekey of every vault it can read — see [ADR 0010](adr/0010-vault-key-rotation.md) for what one
 of those costs, and it is per vault. Nothing about the bundle is compromised by its owner proving possession
 of it, so there is nothing to rotate away from. Identity key rotation is M5 and stays there.
 **The recovery code is not re-issued after use.** Issuing a new one means asking somebody to write down a
 new code at the exact moment they have demonstrated they lose things, and the old code is not weakened by
 having been typed. "Issue a new recovery code" is a separate feature with its own screen, and it is the
 right place for that question.
 **Rate limiting is wanted here and is not a blocker.** This is the first endpoint in the product with a
 guessable secret behind it, and `docs/platform-flags.md` records that rate limiting is unimplemented (M2).
 Argon2id at 64 MiB is the cost that matters — a guessing attack pays it per attempt — so this ships without
 and the endpoint is the reason to do the M2 item next.
 ## The work, in order
 Each step compiles with the whole suite green before the next begins.
 1. **The endpoint.** `GET /api/v1/me/recovery-wrap`, returning the wrap and its `KdfParameters`, or 404. A
   contract type, an entry in `PublicAPI.Unshipped.txt`, and a `SyncEndpointTests`-style refusal test for an
   account without one.
 2. **The unlock.** `SessionOpener.UnlockWithRecoveryAsync(string code)`: canonicalise the code, derive
   `KEK_rc` from the served parameters, unwrap the bundle, and then join the path `UnlockAsync` already
   takes from the moment it holds one. Nothing after the unwrap should be new code — if it is, the two
   unlocks have diverged and one of them is wrong.
 3. **The re-wrap.** `PUT /api/v1/me/wrap` taking a new passphrase wrap and its parameters, and the client
   half that derives the new `KEK_pp` and calls it. Forced as the last step of a recovery: the session is
   open, so refusing to go further until a passphrase is set costs nothing and is the only moment the user
   is certainly present.
 4. **Both heads.** A "forgotten your passphrase?" route from `UnlockCard` and from Android's
   `LockedScreen`, a box that accepts the code as printed, and the new-passphrase form after it. The phone's
   version has to survive the keyboard covering the box — `docs/manual-checks.md` §10.3 lists the five boxes
   that already do, and this is a sixth.
 5. **The prose.** Below.
 6. **`crypto.md`.** A status note, not a spec change — see the last section.
 ## Traps already known
 **◆ The code is derived from the string exactly as displayed, dashes included.** `GenerateRecoveryCode`
 says so where it builds the groups: the separators are not decoration to be stripped before hashing, they
 are part of the input. So step 2 must *canonicalise to the printed form* rather than normalise it away —
 up-case, then re-group in fives — and it must not simply strip dashes and hash what is left. Getting this
 wrong produces a code that verifies nowhere and an error message that says the code is wrong.
 **The alphabet has holes in it.** `I`, `L`, `O` and `U` are not in it. A user who writes `O` for `0` should
 be met with a code that works, so the canonicaliser should fold the four missing letters onto their
 look-alikes before deriving. That is a deliberate leniency and belongs beside the alphabet's own comment.
 **The two KDF profiles are not the same, and the stored parameters are what to use.** The passphrase wrap is
 `PassphraseDefault` (256 MiB, 4 passes) and the recovery wrap is `RandomSecret` (64 MiB, 3), which is
 correct — 160 random bits do not need the same stretching as a chosen phrase. Derive from the parameters the
 server served with the wrap, never from a profile constant, or an account enrolled by a client with
 different settings will refuse a valid code.
 **The cache property is untested from this direction.** A recovery unlock derives a different `MK` and must
 still read a cache written under a passphrase unlock. That works today because `LocalCacheKey` hangs off the
 bundle, and no test asserts it, because nothing could reach the state. Assert it in step 2 rather than
 trusting the note in `crypto.md`.
 **Sign-out is the neighbouring path and must stay reachable.** The unlock screen offers signing out as the
 answer to a forgotten passphrase. It stays: recovery needs the code, and somebody without it still needs a
 way to hand a laptop on. What changes is that it stops being the *only* answer, so the copy on both screens
 has to place them beside each other rather than replacing one with the other.
 ## Tests
 - Round trip: enrol, recover, unlock, set a new passphrase, unlock again with it.
 - The old passphrase stops working after step 3, and the recovery code still does.
 - A wrong code is refused without disclosing whether the account has a recovery wrap at all.
 - The cache written under a passphrase unlock is readable after a recovery unlock — the `localcache/v2`
  property, asserted rather than assumed.
 - An account with no recovery row: the endpoint 404s and the screen says the code was never issued rather
  than that it is wrong.
 - One `SystemTests` pass against the real API, because this is a two-endpoint flow and that suite is the one
  that consumes the artefacts that ship.
 - Mutations to confirm each test can fail: reverse the canonicalisation so dashes are stripped; derive from
  `Argon2Profile.RandomSecret` instead of from the served parameters; and skip the forced re-wrap in step 3.
 ## Prose that becomes false
 Not a tidy-up. Each of these currently tells a user something that this change makes wrong in the other
 direction, and two of them are wrong right now.
 - `docs/manual-checks.md` §10.2 — "the only thing standing between a forgotten passphrase and an
  unrecoverable vault". True once this ships, false today. It also needs a new check: typing a code from
  paper, which is the one part of this no test can perform.
 - `docs/android-port.md`, state 4 — "losing it along with the passphrase means the vault is unrecoverable".
 - `README.md`, Locking — "Signing out … is the only answer to a forgotten passphrase — nothing can recover
  one." Correct today and the sentence this change exists to falsify.
 - `docs/design-import-gaps.md`, Preferences — "a forgotten passphrase — which is unrecoverable by
  construction, so the unlock screen would otherwise be a dead end", which is the stated justification for
  signing out being on that screen. The justification survives; the parenthesis does not.
 - Both unlock screens, wherever they name signing out as the answer.
 ## The spec's "four ways"
 `docs/crypto.md` §3.2 says a passphrase is "only one of four ways to open a vault" — passphrase, device,
 recovery and escrow. Two exist. This change makes it three; escrow is M5 by decision and has an enum member
 and nothing else.
 **Do not edit that sentence.** It is normative and it is about the DSH1 format, where four ways is exactly
 right. What is missing is a statement about *this build*, so add a short table under §3.2 saying which wrap
 kinds this client can create and which it can open, and update it here rather than in the frozen prose. Land
 it in the same commit as step 2, so the two can never disagree again.
@@ -1099,13 +1099,20 @@
            ◆ The one control here that publishes something. Turning it on copies this host's address and
            port into plaintext columns the server can read, which is the single deliberate concession in
            the design — see ADR 0004 — so it says so rather than being a switch labelled "relay".
            ◆ AND IT SAYS, FIRST, THAT IT BUYS NOTHING TODAY. The relay's server half is built and this
            client has no path to it — the connect path dials the address directly whether this is ticked or
            not — so the box as it stood spent that concession and delivered nothing for it. Left tickable
            rather than disabled, so a host already carrying the flag can lose it. See
            docs/reaching-a-host-you-cannot-dial.md.
          -->
          <CheckBox IsChecked="{Binding EditorRelayEnabled}" MinHeight="44">
-            <TextBlock Classes="mono" FontSize="11.5" Text="Reach this host through the server relay"
+            <TextBlock Classes="mono" FontSize="11.5"
                       Text="Reach this host through the server relay (not wired up yet)"
                       TextWrapping="Wrap" />
          </CheckBox>
          <TextBlock Classes="body"
-                     Text="The relay dials on your behalf, so this host's address and port are stored on the server in the clear. Everything else about it stays encrypted. A relayed host also needs a port of its own rather than its group's." />
+                     Text="Not built yet: this app always dials the host itself, so ticking this stores the address on the server and changes nothing about how the host is reached. When it works, the relay will dial on your behalf — which is why the address and port have to be stored in the clear. Everything else about the host stays encrypted either way, and a relayed host needs a port of its own rather than its group's." />
          <Grid ColumnDefinitions="*,8,*" Margin="0,6,0,0">
            <Button Grid.Column="0" Classes="primary" Height="44" Content="SAVE"
@@ -514,14 +514,25 @@
                </ComboBox>
                <CheckBox IsChecked="{Binding EditorRelayEnabled}"
-                          Content="Connect through the server relay" />
+                          Content="Connect through the server relay (not wired up yet)" />
                <!--
                  Stated at the moment the decision is made, which is the only place it means anything. With
                  relay off the server stores no address at all; with it on the server must be able to
                  resolve the target, or it becomes an authenticated open proxy into the operator's network.
                  ◆ AND IT SAYS, FIRST, THAT TICKING IT BUYS NOTHING TODAY. The server half of the relay is
                  built and this client has no path to it: VaultViewModel dials the address directly whether
                  this is ticked or not. So the box as it stood spent the one deliberate privacy concession
                  in the design — the address in plaintext columns — and delivered a connection that failed
                  exactly as it had before, with nothing saying why.
                  Left tickable rather than disabled, because a host that already carries the flag has to be
                  able to lose it, and a disabled control would trap the concession on. See
                  docs/reaching-a-host-you-cannot-dial.md, which is the plan that makes this sentence
                  removable.
                -->
                <TextBlock Classes="hint" FontSize="11"
-                           Text="The relay stores this host's address on the server in plain text. Everything else stays encrypted." />
+                           Text="Not built yet: this client always dials the host itself, so ticking this stores the address on the server and changes nothing about how the host is reached. When it does work, the relay will dial on your behalf — which is why the address and port have to be stored in plain text. Everything else about the host stays encrypted either way." />
                <!--
                  Withdrawing host key trust lives here, in the host's own settings, because a changed host
@@ -256,9 +256,9 @@
          </Style>
        </ItemsControl.Styles>
        <TextBlock Classes="gap"
-                   Text="Terminal font, size, cursor and scrollback — the renderer hard-codes them, and nothing carries a change to it." />
+                   Text="Terminal font, cursor and scrollback — the renderer hard-codes those three. The text size above is the one that is not, and it is the path the others would follow if they were worth a row here." />
        <TextBlock Classes="gap"
-                   Text="A beta channel — there is one release channel, and a switch offering a second would be a preference with nothing behind it." />
+                   Text="Changing channel from in here — there is a nightly as well as a release, but which one a copy follows is fixed when it is built, so moving between them means installing the other one." />
        <TextBlock Classes="gap"
                   Text="Auto-lock after idle — nothing tracks idleness, and the lock policy would have to decide what to do about a shell mid-job." />
        <TextBlock Classes="gap"