Say what the docs describe, in the order they describe it

A tidy across docs/, and every change is either something that had drifted
from the code or something a reader would trip over. Nothing here is a rewrite:
the audit documents keep their audit-time text, because that is what the scope
was decided against, and corrections are marked in place the way each file
already marks them.

The one that matters is crypto.md. Section 4.3's resourceType table stopped at
13 while CryptoSpec.AadResourceType has carried ConnectionLogEntry = 14,
ActivityLogEntry = 15 and ObjectStore = 16 since the logs and the buckets
shipped — and items have been sealed under all three. That file is normative, so
a table three item kinds behind the code is the sort of gap somebody
reimplementing this would build against. Nothing on the wire or on disk changes;
the list now says what the code has been doing, and it notes the thing that
makes it worth reading carefully — 14, 15 and 16 are the first members that are
not a fixed offset from their SyncEntityType counterparts, because 12 and 13
closed a hole and pushed the two enums apart.

manual-checks.md had Phase 3 in an order nobody could follow: 3.2b, then 3.2a,
then 3.4a, then 3.3. The letters are not the problem — they exist so a check can
keep its number for life, which is what lets HostGridTests cite 7.6 and
platform-flags.md cite 3.6-3.8 — so the sections are reordered and the numbers
are untouched, and the intro now says the convention out loud rather than
leaving the next person to infer it from two orphaned letters. Phases 8 and 9
got the horizontal rule every other phase has. The Phase 3 preamble still said
"a sidebar that now draws headings", which has been two different interfaces for
a while: the desktop's grid of cards and the phone's flat list.

7.6 cited MovingAHostToAGroup_FilesItAndLeavesItSelected, which was renamed in
the commit before this one. Every other Type.Member citation across all six
files was checked against src/ and tests/ the same way; those two were the only
ones pointing at nothing.

design-import-gaps.md's v3 section described the grid of cards without saying it
holds one level, and its Groups row still said the sidebar emits one heading per
group — true of the phone and not of the desktop. The team-groups row said a
host a teammate filed "shows under UNGROUPED", which is now only half the story
and the interesting half is why: the chip resolves through groupsById, which is
every readable vault, while the level resolves through Groups, which is the
active vault alone — so the card sits at the outermost level with its group's
name still on it. Verified against both call sites rather than reasoned about.

android-port.md's destination inventory is the desktop as it stood when the
audit was taken and is deliberately left that way, with a note at its head
saying so and two inline corrections where a reader would otherwise be misled:
the rail lost FILES and S3 to fixed tabs, and the hosts sidebar became a grid —
which is exactly why the headings this head draws are the phone's alone now.

adding-hosts-on-the-phone.md is a plan marked built, so its two open questions
are answered in place: GroupId did get into the merge test's with block, and the
server test that asserts a plaintext ParentId is refused survived under a name
that says what it means. Its "found on the way" note is marked still open,
because it is: LocalCacheProtector.For has no arm for ConnectionLogEntry,
ActivityLogEntry or ObjectStore, so ConflictStore.Record still throws for all
three. That outlived the phases that shipped them, which is the drift a note
like that exists to prevent.

No code changed, so the suite is untouched at 1522 passing.
This commit is contained in:
2026-08-04 10:15:02 +02:00
parent 2a56ae3efb
commit 27bb1deb5d
5 changed files with 83 additions and 33 deletions
+9 -2
View File
@@ -105,6 +105,13 @@ the chrome, hosts and terminals, file transfer, the vault, teams, and preference
> double-pressing one opens it, and a breadcrumb trail above the cards is where you are and the way back —
> the same trail the transfers screen draws over a directory.
>
> **And the grid holds one level of that trail rather than every host.** A host filed under a group is drawn
> inside that group and not also on the screen the group's card sits on, which is what makes a card a place
> instead of a label: while the level above held everything anyway, opening a group could only ever subtract.
> The find box is the one thing that crosses a boundary — it searches the open group and everything under it,
> so a machine can be found without first remembering where it was filed, and the chip on a card is what says
> which group a result came out of. See `VaultViewModel.Matches`.
>
> **The type scale went up a point and the text ramp went white.** `#E3E7F4` was a blue-tinted white on
> blue-black surfaces, which costs contrast twice — once for being darker than white and once for sharing
> a hue with what it is drawn on. Every step of the ramp moved with the top, so the intervals the design
@@ -298,9 +305,9 @@ caption buttons and window title drawn on top of the application's own — two s
| Design element | Layer | What it would take | What ships instead |
| --- | --- | --- | --- |
| Tag chips (`nginx`, `eu`, `pg16`) | client-domain | A tag item type, and a way to put one on a host. | **Shipped.** `Tag = 5` is a live item kind and `HostSecret.TagIds` names them, merged per tag so two people tagging one host both keep theirs — which is what `HostTag = 6` was going to buy, so it stays reserved and unused. Chips are drawn on host rows on both heads and toggled in the host editor, which also creates one inline; renaming and deleting are a TAGS category on the keychain screen. The filter box still searches name, address and notes only — a chip is read rather than typed. |
| Groups `PRODUCTION` / `STAGING` / `PERSONAL` | client-domain | A host-group item type (`HostGroup = 4`, reserved) or a group field on `HostSecret`. | **Shipped**, as both: `VaultHostGroup` is a synced item kind and `HostSecret.GroupId` names one. Nested in the data and drawn flat — a group carries a `ParentId` and the defaults its hosts inherit, and the sidebar still emits one heading per group in label order with no indentation. A keychain with no groups renders exactly as it did before — one flat list, no headings. |
| Groups `PRODUCTION` / `STAGING` / `PERSONAL` | client-domain | A host-group item type (`HostGroup = 4`, reserved) or a group field on `HostSecret`. | **Shipped**, as both: `VaultHostGroup` is a synced item kind and `HostSecret.GroupId` names one. A group carries a `ParentId` and the defaults its hosts inherit, and the two heads draw the nesting differently on purpose. The desktop is a grid of cards holding one level at a time, the way a directory pane holds one directory; the phone has no room for a row of cards, so it flattens the whole tree into one heading per group in label order with no indentation. A keychain with no groups renders exactly as it did before on both — one flat list, no headings and no cards. |
| Group badge `TEAM·PLATFORM` | server | **Built in M3.** | The vault's name on each row, and the personal vault ordered first. Not the team's name: two of a team's vaults would then carry the same badge and the badge would be naming the wrong thing. Distinct from the groups above, and deliberately so — a group is a shelf the user chose, a vault is who can read the item. |
| Groups on a **team's** hosts | client-domain | A vault id on each group row for rename and delete, and a way to tell two vaults' identically-named groups apart in a list with one heading per group. | **Half shipped, and the half that shipped had to.** Every readable vault's groups are now read into the resolution map, because a group lends a port, a username and a binding — so a host whose group went unread would silently dial 22 as nobody while the machine is on 2222 as `deploy`. A missing heading is cosmetic; a missing port is a connection to the wrong place. The editable list is still the active vault's alone, so a host a teammate filed still shows under UNGROUPED and cannot be renamed or unfiled from here. |
| Groups on a **team's** hosts | client-domain | A vault id on each group row for rename and delete, and a way to tell two vaults' identically-named groups apart in a list with one heading per group. | **Half shipped, and the half that shipped had to.** Every readable vault's groups are now read into the resolution map, because a group lends a port, a username and a binding — so a host whose group went unread would silently dial 22 as nobody while the machine is on 2222 as `deploy`. A missing heading is cosmetic; a missing port is a connection to the wrong place. The editable list is still the active vault's alone, so a group a teammate made has no card and no heading and cannot be renamed from here. A host filed into one is drawn at the outermost level of the desktop's grid and under UNGROUPED on the phone — reachable either way, which is the point — with the chip on its card still naming the group, because the label is resolved through the wide map while the level is decided from the narrow list. |
| Per-host status dot, three colours | client-ssh | The amber state would mean "reachable but not connected", and nothing here ever probes a host. | Two states, both real: green when a terminal is open on that host, grey when not. |
| `· ⤷ bastion-eu` in the host subtitle | client-ssh | **Jump hosts are data-only.** `HostSecret.JumpHostIds` is a `JumpChain` that is stored, encrypted, synced and three-way merged — and nothing reads it at connect time. `SshConnectionRequest` carries one host. | Omitted. The stored chain is preserved untouched by every edit. |
| `SPLIT ⌘D` and side-by-side panes | client-ssh + ui | The renderer stacks panes and shows one (`terminal.css`: `.pane { position:absolute; inset:0; display:none }`). Tiling needs a real pane geometry and a splitter. | Omitted. Tabs ship instead, over the same one-WebView multiplexing. |