Stop the docs claiming absences that have since been built

An audit of README.md, the seven docs and the fourteen ADRs against the code, looking for what is described
as absent or planned. Most of it held. What did not is here, and it clusters: every stale claim but one is
downstream of the settings file arriving without this document noticing.

design-import-gaps said the client has no preferences store and writes exactly two files. It writes three —
ClientSettings is in settings.json beside the cache — and two preferences are saved through it. From that
one error followed four more: the terminal font size row said "fixed at the renderer's 13px" when it has
been 8 to 32 from a screen and three chords for some time; the transfer-resume row and the per-host last
directory row both blamed a store that now exists, when what they actually want is a table and a scalar file
is the wrong shape for one; and the Preferences table asserted no preference could be saved at all.

It also said TerminalServerOpcode has four values and none carries an option. It has eight, and one of them
is FontSize — which is the interesting part rather than a counting error, because that opcode is the proof
that the frame these rows say is missing can be built. The rows now say what each one would actually take,
which for three of the four is a setting, an opcode and a control, and for the Backspace row 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.

THE SAME TWO ERRORS WERE SHIPPED IN THE INTERFACE. The preferences screen carries a NOT BUILT YET list, so
that what the screen does not do is as legible as what it does — and it said terminal size was hard-coded a
hundred lines below a working size control, and said there is one release channel a month after the nightly
shipped. A list of absences is only worth having if it is true, and a screen contradicting itself in the
same scroll is worse than no list. Both lines are corrected rather than removed: the first now says which
three of the four are genuinely hard-coded, and the second says what is actually missing, which is a way to
change channel from inside the application rather than by installing the other build.

docs/adding-hosts-on-the-phone.md is deleted. It was a work plan whose own header says "Status: built. All
six steps." — nothing links to it, and the decisions it records are in the code it produced, including the
one it is proudest of: HostSecret.AsksForPassword carries its own remark on why naming neither binding had
to stop meaning "ask me". What was left was step ordering and per-test instructions for work that shipped.
Git keeps it.

crypto.md is deliberately untouched. It is normative and frozen, and its claims are about the DSH1 format
rather than about this build — including the one that reads oddly next to the code, that a passphrase is
one of four ways to open a vault. Under the spec it is. What is missing is a statement about what this
build can open, and that belongs beside the spec rather than inside it; see
docs/unlocking-without-the-passphrase.md.

VERIFIED. Build clean, 112 layout tests, 354 app tests. The preferences screen is measured by the layout
suite, so the longer copy is held inside the window at the minimum size rather than assumed to fit.
This commit is contained in:
2026-08-07 08:43:49 +02:00
parent d8cf16fb46
commit 88809f0d66
3 changed files with 17 additions and 362 deletions
+15 -11
View File
@@ -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
M2 and M3 arriving in a design before it arrives in the code.
Read alongside [the milestone plan](../README.md#milestones). Most of what follows is not a defect. M2 and
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
cache has six tables, none of them settings. Nothing on the design's TERMINAL preferences panel can be
saved, and there is no frame on the terminal data plane that would carry a change to the renderer anyway.
**The client's settings file holds two things.** It writes three files — `cache.db`, `device.key` and
`settings.json` — and the cache's six tables still hold none of them. `ClientSettings` carries the
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`, 1116px) | client-storage | See preferences. | Fixed at the renderer's 13px. |
| Terminal font size (`--termfs`, 1116px) | client-storage | — | **Shipped**, and wider than the design's range: 832px 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. |
| 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. |
| 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, 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. |