DodoSSH/docs/design-import-gaps.md

What the design asked for and this build has not got

The Avalonia client's interface was rebuilt from a Claude Design project — a five-screen spec covering the chrome, hosts and terminals, file transfer, the vault, teams, and preferences.

Most of it landed. This file is the rest: every element of that design with nothing behind it, which project each piece would have to land in, and what the shipped interface does instead. That last column is the important one. This codebase states its limits rather than implying them — the README does it for revocation, for relay session recording and for what locking does not do — so nothing here was 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. Most of what follows is not a defect; it is M2 and M3 arriving in a design before it arrives in the code.

The shape of the problem

Three facts explain nearly every row below.

An SSH connection here opens exactly one channel. ISshConnection offers OpenShellAsync and nothing else (src/DodoSSH.Client.Ssh/SshConnection.cs). No SFTP subsystem, no port forwarding, no ProxyJump. That one fact removes the whole file-transfer screen, the FORWARDS chip, the status bar's port list, and every via bastion-eu in the design.

Teams are schema and nothing else. The team and team_membership tables exist from the first migration, with entities in DodoSSH.Domain/Teams.cs and a TeamRole enum — and no endpoint reads or writes any of it. VaultAccessService.ResolveAsync returns Denied for every vault that is not the caller's own personal one. That removes the Teams screen entirely, and with it every role chip, scope and "shared with" affordance the vault screen was drawn with.

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.

One thing cuts the other way and is worth knowing before planning any of this: the wire protocol already reserves the slots. SyncEntityType (src/DodoSSH.Contracts/SyncEntityType.cs) has HostGroup = 4, Tag = 5, HostTag = 6, HostCredential = 7, Snippet = 8 and PortForward = 9 — reserved, unused, and already covered by the AAD resource-type table. Groups, tags and snippets are new item types on an existing protocol rather than a protocol change.

---

Chrome — titlebar, nav rail, status bar

Design element	Layer	What it would take	What ships instead
Org chip dodotech / platform	contracts + server	An organisation name a client can read. VaultSummary.TeamId exists and is always null.	The vault's own name, and the account this machine is enrolled as.
SYNCED dot, always green	client-app	Nothing — the design's claim is simply unconditional.	Green only when a connection is held, the last sync pass actually reached the server, and the outbox is empty; otherwise UNREACHABLE, the count of changes still waiting, or OFFLINE. Holding an IVaultServer proves a sign-in once succeeded and nothing more, so a laptop whose lid has been shut all afternoon still has one — reachability comes from the outcome of the last pass. A permanently green light is the same as no light.
VAULT SYNCED 11:02	client-session	StoredSyncState.LastPulledAt/LastPushedAt are persisted, but VaultSession exposes the store as internal. A property away.	Omitted. The one honest sync fact — the outbox depth — is in the titlebar and the status bar.
⌘K command palette running commands	client-domain	A snippet or saved-command item type (SyncEntityType.Snippet = 8 is reserved).	Ctrl+K opens a real host search that connects on Enter. The box says "search hosts", not "search hosts · run command".
Status bar · via bastion-eu	client-ssh	Jump-host execution. See below.	Omitted.
Status bar port forwards	client-ssh	Port forwarding. See below.	Omitted.
Status bar sftp · 2 transfers	client-ssh	File transfer. See below.	Omitted.
Status bar locks in 09:41	client-app	An idle auto-lock. See preferences below.	Omitted.
IBM Plex Mono / IBM Plex Sans	ui	Shipping the font files as AvaloniaResource and registering them. The design loads them from Google Fonts, which a desktop app cannot.	Inter (already embedded) for prose, and the system monospace stack the terminal already names. Named once in App.axaml as MonoFont, so the substitution is reversible in one place.
⌘K, ⌥↵	ui	Nothing; the design is Mac-flavoured.	CTRL K. Development is Windows-only today (docs/platform-flags.md).

Also worth knowing: custom chrome went in as SystemDecorations="BorderOnly", not by extending the client area. ExtendClientAreaChromeHints was removed in Avalonia 12, so extending leaves the system caption buttons and window title drawn on top of the application's own — two sets of window controls, and "DodoSSH" printed twice. Measured, not assumed.

---

Hosts + terminal

Design element	Layer	What it would take	What ships instead
Tag chips (nginx, eu, pg16)	client-domain	A tag item type and a host-tag join. Both reserved on the wire (Tag = 5, HostTag = 6), neither implemented, plus a payload schema bump on HostSecret.	Omitted. The filter box searches name, address and notes instead.
Groups PRODUCTION / STAGING / PERSONAL	client-domain	A host-group item type (HostGroup = 4, reserved) or a group field on HostSecret.	One collapsible heading, named after the vault — the only grouping a host actually has. A second appears when a second vault becomes reachable.
Group badge TEAM·PLATFORM	server	Teams.	Omitted.
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.
⇄ FORWARDS · 2	client-ssh	Port forwarding. SyncEntityType.PortForward = 9 is reserved; nothing in the SSH layer forwards anything.	Omitted.
SNIPPETS panel, ↵ to run	client-domain	A snippet item type (Snippet = 8, reserved).	Omitted.
Broadcast to all panes (⌥↵)	client-ssh	Input is routed strictly by session id in TerminalDataPlane.Dispatch; there is no fan-out. Needs splits first.	Omitted.
Pane header 24ms	client-ssh	Round-trip measurement. SSH.NET offers no RTT API.	Omitted.
Pane header aes256-gcm	client-ssh	The closest miss on this list. SshNetConnection holds the SshClient, so ConnectionInfo.CurrentServerEncryption is right there — it just is not on ISshConnection or surfaced by TerminalWorkspace.	Omitted; the tab strip shows the account and endpoint actually dialled.
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 sidebar already is.	Omitted. Connect opens a tab; Ctrl+K opens one by name.
Terminal font size (--termfs, 11–16px)	client-storage	See preferences.	Fixed at the renderer's 13px.

---

File transfer (the design's SFTP screen)

Nothing on this screen exists. It is listed in the nav rail and reaches a screen that says so, naming the milestone and what is missing — see ShellScreen for why it is not simply dropped from the rail.

Design element	Layer	What it would take
SFTP itself	client-ssh	An SFTP subsystem channel on ISshConnection. There is no SftpClient, ScpClient or transfer type anywhere in src/.
Remote listing with NAME/SIZE/MODIFIED/PERMS	client-ssh	The channel, plus a listing record and a POSIX mode formatter — nothing in the repo formats a drwxr-xr-x.
Local listing	client-app	The App project contains no System.IO usage at all. The only paths this client knows are its own two files.
Path breadcrumbs, per-host last directory	client-storage	Navigation state for two panes, and somewhere to persist it. There is no settings table.
Transfer queue, progress, throughput	client-ssh	A transfer engine. Do not reach for CreditWindow — that is a 256 KiB flow-control window for terminal output, not a transfer primitive.
resume supported	client-ssh	Offset-based reads and writes, plus partial-transfer bookkeeping that survives a restart.
sftp over bastion-eu	client-ssh	Jump hosts, as above.

---

Vault

The screen ships and is real: four categories over the vault's four item types, one table, a detail pane, and both editors. What follows is what the design drew around them.

Design element	Layer	What it would take	What ships instead
ACCESS column and your access → CONNECT-ONLY	server	Per-item ACLs. EncryptedPayload.DataKeyId is documented as the seam for per-item grants in M5. VaultSummary does carry an opaque int Permissions, but nothing gives the bits a meaning on the wire — PermissionFlags itself lives in DodoSSH.Domain — and those are per vault, never per item. There is no ConnectOnly role in TeamRole at all.	Omitted. The column shows sync state instead — whether a change is still sitting in this machine's outbox — which the design had no column for.
SHARED WITH · 6 avatars	server	The whole sharing stack: grants, a member directory, and re-wrapping a vault key for another account.	Omitted.
"Private key never leaves the vault. Sessions sign through the team agent (dodod)"	client-ssh	Both sentences are false here, and the second cannot be made true by this architecture. There is no agent of any kind, and the connect path decrypts the private key and hands the bytes to SSH.NET.	Omitted. The key editor already says what is true: the key and its passphrase are encrypted here and never reach the server in a readable form.
Scope rail: PERSONAL / TEAM · PLATFORM / TEAM · DATA	server	Team vaults. VaultAccessService.ListAsync filters to personal vaults owned by the caller.	The real vault list, which today has one entry, with a line saying why.
SCOPE column	server	As above — and note scope here is a property of a vault, never of an item.	Omitted.
LAST column (11:02, 1d ago)	contracts	No last-used timestamp at any layer. VaultItem<TSecret> is (id, secret, version, three sync flags).	Omitted.
FINGERPRINT for SSH keys	client-domain	SshKeySecret has no fingerprint field, and computing one means parsing key formats the type deliberately stores verbatim.	The DETAIL column carries what is known — whether a passphrase and a public half are stored. Pins show their real fingerprint, in full and untruncated.
•••• rotated jul 14 for passwords	client-domain	CredentialSecret has no rotation date or password age.	The account the password is for.
IDENTITIES category	contracts	A new item type, not even reserved in SyncEntityType.	Omitted.
CERTIFICATES category, expires 2026-09-01	contracts	Same ladder, plus certificate parsing.	Omitted.
18 items · 12 shared	server	The sharing stack.	N items · N not synced, counted over the rows on screen.
added by anna@dodotech.dev	contracts	The server records CreatedByUserId, but SyncChange carries no actor field and no other user's name is fetchable.	Omitted, and the detail pane says in one line that items record no author, no timestamps and no sharing.
created 2026-03-14	client-sync	Recoverable in principle — entity ids are UUIDv7 and carry a timestamp — but nothing surfaces it.	Omitted.
TEST CONNECT	ui	Connecting is host-scoped, not credential-scoped: there is nothing to test a credential against without a host.	Omitted.
REVOKE	server	Revoking someone else's access needs grants to revoke. Deleting an item is a different act and is already there. ADR 0001 also constrains how any future revoke may be presented: revocation is not retroactive.	Delete, named for what it does.
SSH KEY · ED25519	client-domain	No algorithm field, and deriving it means parsing the armour.	The type without the algorithm.
One + ADD CREDENTIAL button	ui	—	Two buttons, one per kind that can be added. "Credential" is a specific item type in this codebase (a username and a password), so using it as an umbrella word would collide with the vocabulary.
—	—	—	HOST KEYS is the reverse case: a fully-backed, shipped category the design had no slot for. It is in the rail.

---

Teams

Nothing on this screen exists. It is in the nav rail and reaches a screen that says so.

Design element	Layer	What it would take
The team itself	server	Team endpoints. The server has eight routes and none is about people.
Shared vaults	server	Vault creation, grants, and membership evaluation. Exactly one vault exists per user, created as a side effect of enrollment.
Roles (OWNER/ADMIN/MEMBER/CONNECT-ONLY/VIEWER)	contracts + server	TeamRole exists in DodoSSH.Domain, is read by no code path, has no wire representation, and has no ConnectOnly member.
Members table	server	A member DTO and a directory endpoint.
2FA ENFORCED and the per-member 2FA column	server	No two-factor concept exists anywhere — the only hit in the whole worktree is an aside in docs/crypto.md.
LAST ACTIVE	server	UserAccount.LastSeenAtUtc exists and is written at just-in-time provisioning and at enrollment, and never on an ordinary authenticated request — so the column cannot answer "last active".
Avatars	server	MeResponse has no picture field, and no other user's display name is fetchable.
Pending invites, resend, revoke	server	An invitation entity, a token with a lifetime, and an outbound mail path. MembershipStatus.Invited and TeamMembership.InvitedByUserId are the only hints, and nothing writes them.
SSO · OIDC · okta.dodotech.dev	server	Per-team SSO. Authentication is one global JWT scheme bound to one authority.

A trap for whoever builds this. GET /api/v1/meta advertises features: ["teams"] unconditionally (MetaEndpoints.cs). Do not gate a Teams screen on that string — it is true of every deployment today and means nothing.

---

Preferences

The screen ships with what is real — this machine's device key, locking, and syncing — and 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.
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.
KEYS & AGENT section	client-ssh	There is no agent, at all — no own agent, no forwarding, no Pageant or OpenSSH-agent interop.
SYNC & VAULT section	client-domain	Nothing here is adjustable. The auto-sync interval is a private static readonly with a remark arguing for its value.
SECURITY & SSO section	server	The SSO half needs team endpoints; there is no policy for the screen to show.
SHORTCUTS section	ui	There is no keybinding infrastructure and no rebinding surface.
Auto-lock after idle	client-session	An activity source, a decision about what counts as idle, and — the hard part — a policy for a shell mid-job. LockAsync's own remark already argues that an unattended timeout which killed a running job would be worse than the exposure it removed.
Require biometric to sign	crypto	Three separate falsehoods in one row. There is no signing service — the private key is decrypted and handed to SSH.NET whole, so there is no per-signature moment to interrupt; there are no connect-only keys; and per-use consent would need the key to live in the TPM, which is a different key hierarchy from the one in docs/crypto.md.
Pill toggle switches	ui	Purely presentational — App.axaml has no ToggleSwitch selector, so Fluent's default would appear un-themed beside the hairline chrome.

---

Two things the import changed on purpose

Hosts left the vault column. They have their own sidebar beside the terminal, and the vault screen holds keys, passwords and pinned host keys. This follows the design, and it is also the better split: the host list is what you look at while you work, and the rest is what you go and manage. VaultSection lost its Hosts member and gained All.

Tabs moved to the shell, not the vault. Locking disposes the vault and deliberately leaves shells running, so a tab list rebuilt per unlock would lose track of sessions that are still connected — the very sessions the unlock screen already counts. TerminalWorkspace gained SessionActivated on the wire, IsSessionLive, and a SessionEnded event so a tab can stop claiming to be connected.