From 1c5b4c2a0f814d298f8c510802135dcf98e040d9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 25 Jul 2026 20:15:37 +0000
Subject: [PATCH 1/2] ui: make the desktop app keyboard-complete (invariant K1,
 GH #78)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

K1 promises B2 is fully operable from the keyboard, with the mouse an
accelerator rather than a requirement. The GUI didn't keep it: the file
tree had no arrow navigation (Tab-cycling 1500 rows was the only way in),
graph nodes weren't focusable at all, Rename / Move… / Link… existed only
behind a right-click, overlays neither took nor returned focus, and the
chords that did exist lived only in button tooltips.

The file tree now follows the ARIA `tree` pattern. Its shape *and its row
order* move into `ui/src/treenav.ts`, pure and tested, because the paint
and the arrow keys have to agree on that order down to the last tie-break
— a tree you can arrow through in a different order than you can see is
worse than no arrows at all. `render.ts` sorts through the same helpers.
Rows get `role="treeitem"`, `aria-level`, and a roving `tabindex` (one Tab
stop for the whole tree); ↑↓ walk visible rows, →← expand/enter and
collapse/exit, Home/End jump, and a bare letter is first-letter typeahead.
A delete hands focus to the neighbouring row rather than dropping it.

Overlay focus is one hook — `syncOverlayFocus()`, called at the end of
every `render()` and acting only on the open/close edge, so a toast timer's
repaint can't steal focus mid-Tab. Opening takes focus, Tab is trapped
while up, and closing restores it. Restoration is by identity that outlives
an innerHTML swap (path → id → element), which is also how `paintTree`
keeps a keyboard user in the tree across an unrelated repaint.

New keyboard paths: ⇧F10 / Menu opens the context menu on the focused tree
row or discovery card (the only route to Rename / Move… / Link…), F2
renames, ⌘⌫ now deletes the focused row (so folders get a chord, with the
confirm), ⌘1/⌘2/⌘3 put the keyboard in a pane, ⏎/Space activate a graph
node by dispatching the same click the mouse sends, ⏎ commits the link
modal, and ⏎ resets a pane gutter (the double-click's missing sibling).

Discoverability: `?` opens a shortcut sheet built from one table
(`ui/src/shortcuts.ts`), also reachable from Settings; menu items carry
their direct chord; the search box, gutters, graph toggle, and modals say
what keys they answer to. Focus rings are a single `:focus-visible` rule.

Verified in Chromium against the built bundle with a stubbed IPC: 32
keyboard paths, including focus restoration across repaints.

Also fixes a pre-existing `clippy::type_complexity` failure in
`link.rs`'s test table, tripped by Rust 1.96.1 and unrelated to this work
— it was failing the gate on any branch.

Refs: docs/design/invariants.md K1, crates/b2-desktop/CLAUDE.md

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BF2Fx3uMZjJ18oHCp5mebY
---
 CLAUDE.md                   |   6 +-
 crates/b2-core/src/link.rs  |   5 +-
 crates/b2-desktop/CLAUDE.md |  57 +++++
 ui/src/main.ts              | 478 ++++++++++++++++++++++++++++++++++--
 ui/src/panes.ts             |  10 +-
 ui/src/render.ts            | 261 ++++++++++++--------
 ui/src/shortcuts.test.ts    |  68 +++++
 ui/src/shortcuts.ts         |  85 +++++++
 ui/src/state.ts             |  17 ++
 ui/src/treenav.test.ts      | 231 +++++++++++++++++
 ui/src/treenav.ts           | 281 +++++++++++++++++++++
 ui/style.css                | 161 +++++++++++-
 12 files changed, 1517 insertions(+), 143 deletions(-)
 create mode 100644 ui/src/shortcuts.test.ts
 create mode 100644 ui/src/shortcuts.ts
 create mode 100644 ui/src/treenav.test.ts
 create mode 100644 ui/src/treenav.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index 09e2161..e4027e7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -245,7 +245,11 @@ if/when one lands — `index-engine.md` §5.)*
   syntax-highlighted from CodeMirror's own grammar registry (`@codemirror/language-data`, lazily
   loaded one language per chunk) — `ui/src/highlight.ts` drives *every* surface (reading view, live
   preview, source mode) from one resolver and one theme-aware `tok-*` palette, so a fence looks the
-  same read or edited.
+  same read or edited. The GUI is **keyboard-complete** (invariant K1): the file tree follows the
+  ARIA `tree` pattern over `ui/src/treenav.ts`'s row order — the *same* order `render.ts` paints, so
+  the arrows and the eye can't disagree — every overlay traps and restores focus, `⇧F10` is the
+  keyboard's right-click, and `?` shows the whole chord table (`ui/src/shortcuts.ts`). The four
+  obligations a new surface owes are in [`crates/b2-desktop/CLAUDE.md`](crates/b2-desktop/CLAUDE.md).
 
 ### The `Vault` façade (`b2-core/src/vault.rs`)
 
diff --git a/crates/b2-core/src/link.rs b/crates/b2-core/src/link.rs
index 971180b..499c57b 100644
--- a/crates/b2-core/src/link.rs
+++ b/crates/b2-core/src/link.rs
@@ -236,6 +236,9 @@ fn extract_explanation(tail: &str) -> Option<String> {
 mod tests {
     use super::*;
 
+    /// One expected link, as the case tables spell it: `(type, target, caption, embed, typed)`.
+    type Expected<'a> = (&'a str, &'a str, Option<&'a str>, bool, bool);
+
     /// Shorthand: parse one line, return `(type, target, caption, embed, typed)`.
     fn parsed(line: &str) -> Vec<(String, String, Option<String>, bool, bool)> {
         parse_links(line)
@@ -246,7 +249,7 @@ mod tests {
 
     #[test]
     fn markdown_forms_yield_references_with_caption_and_embed() {
-        let cases: &[(&str, &[(&str, &str, Option<&str>, bool, bool)])] = &[
+        let cases: &[(&str, &[Expected])] = &[
             // ![alt](path) — embed with caption
             (
                 "See ![a sailboat](img/IMG_2041.jpg) here.",
diff --git a/crates/b2-desktop/CLAUDE.md b/crates/b2-desktop/CLAUDE.md
index 8ec8598..8cc51ef 100644
--- a/crates/b2-desktop/CLAUDE.md
+++ b/crates/b2-desktop/CLAUDE.md
@@ -89,6 +89,63 @@ add a UI concern to `b2-core`, that's the signal you're putting logic in the wro
   GUI/reindex threads), and the *implied* default scoped to `b2=debug` (not bare `debug`) so Tauri/wry/hyper
   tracing stays out of the file. `main` must hold the returned `WorkerGuard` for the whole run.
 
+## The keyboard contract (invariant K1)
+
+[invariants.md](../../docs/design/invariants.md) **K1** — *B2 is fully operable from the keyboard; the
+mouse is an accelerator, never a requirement* — names this file as its elaboration home. This is it.
+K1 governs the **GUI**: the `b2` CLI satisfies it by nature, so everything below is about
+`b2-desktop` + [`ui/`](../../ui) ([#78](https://github.com/AlteredCraft/B2/issues/78)).
+
+**The rule, in one line: no action reachable only by pointer.** If a gesture exists only as a click,
+a right-click, or a drag, it is a bug — not a missing nicety.
+
+### The four obligations
+
+Every new surface owes all four. They are cheap while you're building it and expensive to retrofit.
+
+1. **Reachable.** A focusable control in a sensible tab order, or a documented chord. A `<div>` you
+   attach a click handler to is a mouse-only control; make it a `<button>`, or give it `tabindex` +
+   `role` + a key that activates it. Graph nodes are the worked example: SVG `<g>` elements with
+   `tabindex="0"` + `role="button"`, whose ⏎/Space handler **dispatches the same click** the mouse
+   sends, so there is one activation path rather than two to keep in step.
+2. **Visible.** `:focus-visible` rings, in `style.css`'s focus block. A control you can reach but
+   can't see you've reached is not reachable. Never `outline: none` without putting an equal-or-louder
+   affordance in its place (the pane gutters' accent line is the one legitimate case).
+3. **Escapable.** An overlay takes focus on open, **traps ⇥** while it's up, and **restores focus** to
+   whatever opened it on close. `Escape` dismisses innermost-first; `Enter` confirms. All of this is
+   one hook — `syncOverlayFocus()` in `main.ts`, called at the end of every `render()` and acting only
+   on the open/close *edge*, so a toast timer's repaint never steals focus mid-⇥.
+4. **Discoverable.** A chord nobody can find is not kept. Add the row to `ui/src/shortcuts.ts` (the
+   `?` sheet) **in the same change** that wires it, and put the chord in the control's `title` — and,
+   where the action lives in a menu, beside the menu item, which is where a keyboard user learns the
+   shortcut that lets them skip the menu next time.
+
+### Where the pieces live
+
+- **`ui/src/treenav.ts`** — the file tree's pure logic, and the reason it's a separate module: the
+  paint (`render.ts`) and the arrow keys **must** agree on row order down to the last tie-break, so
+  the sort and the flatten live in one tested place. A tree you can arrow through in a different
+  order than you can see is worse than no arrows at all. The tree follows the ARIA `tree` pattern —
+  `role="tree"`/`treeitem`, `aria-level`, a **roving `tabindex`** (one Tab stop for the whole tree, not
+  one per file: a 1500-note vault is not a tab sequence), ↑↓ between visible rows, →← to expand/enter
+  and collapse/exit, Home/End, and first-letter typeahead.
+- **`ui/src/shortcuts.ts`** — the `?` sheet's one table. Modifiers as macOS glyphs (⌘ ⇧ ⌫ ⏎); keys
+  macOS spells out in its own menus stay words (Esc, Tab, Space, Home/End).
+- **`ui/src/main.ts`** — the wiring: the tree's own `keydown` (bound to the pane, so it answers before
+  the global chords), the global chord table, and the focus plumbing under
+  *"keyboard: focus plumbing"*.
+
+### Two things that bite
+
+- **A repaint destroys focus.** `innerHTML` swaps are how this UI renders, so anything holding focus
+  is gone after one — and the keyboard user is silently ejected to `<body>` by an unrelated toast or
+  watcher pulse. Restore by *identity that outlives the swap*, never by element: `paintTree` re-focuses
+  the tree's row **by path**, and `captureReturnFocus` returns a thunk (path → id → element) rather
+  than an element reference.
+- **WebKit doesn't focus a button on click.** So a `focusin` listener alone won't see a mouse user's
+  selection, and the keyboard's idea of "where I am" would drift from the mouse's. The tree's click
+  delegation sets `state.treeFocus` explicitly for this reason.
+
 ## Transport
 
 **Tauri IPC only** — the frontend `invoke`s these commands. This crate runs **no HTTP server**. An
diff --git a/ui/src/main.ts b/ui/src/main.ts
index 0e3d340..fcbdead 100644
--- a/ui/src/main.ts
+++ b/ui/src/main.ts
@@ -25,7 +25,24 @@ import { Decoration, type DecorationSet, EditorView, keymap, tooltips } from "@c
 import { api, errText, isWriteConflict } from "./api";
 import { state, type SideSection, type ThemePref, type TreeNodeRef } from "./state";
 import { dirChain, joinPath, normalizeName, parentDir } from "./newentry";
-import { baseName, canMoveInto, moveDestination, refKind, remapPath, renameDestination } from "./move";
+import {
+  baseName,
+  canMoveInto,
+  moveDestination,
+  type NodeKind,
+  refKind,
+  remapPath,
+  renameDestination,
+} from "./move";
+import {
+  arrowMove,
+  buildTree,
+  neighborPath,
+  rowIndex,
+  typeaheadTarget,
+  visibleRows,
+  type TreeRow,
+} from "./treenav";
 import { livePreview, wikilink } from "./livepreview";
 import { b2Highlighter, highlightCodeBlocks, resolveLang } from "./highlight";
 import { wikiCandidates, wikiInsertion, wikiQueryAt } from "./wikicomplete";
@@ -86,10 +103,17 @@ function paintTree(): void {
   };
   const restoreCreate = carry("tree-create-input", state.treeCreate !== null, false);
   const restoreRename = carry("tree-rename-input", state.treeRename !== null, true);
+  // Whether the keyboard is *in* the tree right now (K1): the innerHTML swap destroys
+  // the focused row and focus silently falls back to <body>, so an unrelated repaint —
+  // a toast timer, a watcher pulse, streamed reindex progress — would eject a keyboard
+  // user from the tree mid-navigation. Restored by path, not by element, since the
+  // element the focus was on no longer exists after the swap.
+  const hadRowFocus = focusedTreeRow() !== null;
   el("tree-pane").innerHTML = html;
   lastTreePaneHtml = html;
   restoreCreate();
   restoreRename();
+  if (hadRowFocus && !state.treeCreate && !state.treeRename) rovingRowEl()?.focus();
 }
 
 function render(): void {
@@ -140,8 +164,7 @@ function render(): void {
   } else {
     toast.hidden = true;
   }
-  // Focus the explanation field the moment the modal appears.
-  document.getElementById("link-explanation")?.focus();
+  syncOverlayFocus();
   syncFind(noteSwapped);
   if (noteSwapped) void paintCodeHighlights();
 }
@@ -423,6 +446,181 @@ function inTextEntry(): boolean {
   );
 }
 
+// --- keyboard: focus plumbing (invariant K1, GH #78) --------------------------------
+//
+// B2 is fully operable from the keyboard; the mouse is an accelerator, never a
+// requirement (docs/design/invariants.md K1). Three things make that true and all three
+// live here: the file tree navigates by arrow key (the ARIA `tree` pattern, walking the
+// row order treenav.ts also paints), every overlay takes focus on open and gives it back
+// on close, and every mouse-only gesture — the right-click menu above all — has a key
+// that reaches it. The chords themselves are wired in the global keydown handler at the
+// bottom of `wireEvents`; what's here is the focus bookkeeping they share.
+
+/** Every row the tree currently paints, in paint order — the list the arrows walk. */
+function treeRows(): TreeRow[] {
+  return visibleRows(buildTree(state.notes, state.resources, state.dirs), state.expandedDirs);
+}
+
+/** The DOM row for a vault path. Looked up by data attribute rather than by CSS
+ *  selector because a filename may contain anything a selector would choke on. */
+function treeRowEl(path: string | null): HTMLElement | null {
+  if (path === null) return null;
+  const rows = el("tree-pane").querySelectorAll<HTMLElement>(".tree-row[data-tree-row]");
+  for (const row of rows) if (row.dataset.treeRow === path) return row;
+  return null;
+}
+
+/** The row carrying the roving tabstop, as painted (treenav.ts `rovingPath`). */
+function rovingRowEl(): HTMLElement | null {
+  return el("tree-pane").querySelector<HTMLElement>('.tree-row[tabindex="0"]');
+}
+
+/** The tree row the keyboard is on right now, or null when focus is elsewhere. */
+function focusedTreeRow(): HTMLElement | null {
+  const active = document.activeElement;
+  if (!(active instanceof HTMLElement)) return null;
+  return active.closest<HTMLElement>("#tree-pane .tree-row[data-tree-row]");
+}
+
+/** A tree row element as the node ref that rename / move / delete all speak. */
+function treeRowRef(row: HTMLElement): TreeNodeRef {
+  const path = row.dataset.treeRow ?? "";
+  const nodeKind: NodeKind =
+    row.dataset.dir !== undefined
+      ? "folder"
+      : row.dataset.openResource !== undefined
+        ? "resource"
+        : "note";
+  return { path, nodeKind, label: baseName(path) };
+}
+
+/**
+ * Move keyboard focus to a tree row: state first (so the roving tabstop travels with
+ * it), then the repaint, then the DOM. `scrollIntoView` is what keeps a long vault
+ * navigable — arrowing off the bottom of the viewport must bring the row into view,
+ * exactly as a mouse-driven scroll would.
+ */
+function focusTreeRow(path: string): void {
+  state.treeFocus = path;
+  paintTree();
+  const row = treeRowEl(path);
+  row?.focus();
+  row?.scrollIntoView({ block: "nearest" });
+}
+
+/** Put the keyboard in the file tree (⌘1) — on the row it last left off at. */
+function focusTreePane(): void {
+  const row = rovingRowEl();
+  if (row) row.focus();
+  else el("tree-pane").focus();
+}
+
+/** Put the keyboard in the note (⌘2): the live editor while editing, else the pane
+ *  itself — which is the scroll container, so the arrows read the note from there. */
+function focusNotePane(): void {
+  if (state.editing && editorView) {
+    editorView.focus();
+    return;
+  }
+  el("note-pane").focus();
+}
+
+/** Put the keyboard in discovery (⌘3) — its first card, else the empty pane. */
+function focusSidePane(): void {
+  const pane = el("side-pane");
+  const first = pane.querySelector<HTMLElement>("button:not([disabled])");
+  (first ?? pane).focus();
+}
+
+// --- keyboard: overlay focus (K1) ---------------------------------------------------
+//
+// An overlay that opens without taking focus is a mouse-only control: the keyboard is
+// still on the page behind it, ⏎ hits whatever was focused before, and Tab walks the
+// page *under* the modal. So each overlay takes focus on open, keeps it (the Tab trap in
+// the keydown handler), and hands it back on close. One transition hook rather than a
+// per-modal dance: `render()` paints overlays declaratively, so the open/close *edge*
+// is the only honest place to move focus — moving it on every render would fight the
+// user's own Tab while a modal is up.
+
+type OverlayKind = "shortcuts" | "settings" | "move" | "delete" | "link" | "menu" | null;
+
+/** Which overlay is up, in the same precedence `modalHtml` renders them. */
+function currentOverlay(): OverlayKind {
+  if (state.shortcutsOpen) return "shortcuts";
+  if (state.settingsOpen) return "settings";
+  if (state.moveTarget) return "move";
+  if (state.deleteTarget) return "delete";
+  if (state.linkTarget) return "link";
+  if (state.contextMenu) return "menu";
+  return null;
+}
+
+const FOCUSABLE =
+  'button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), a[href], [tabindex]:not([tabindex="-1"])';
+
+/** The overlay's own focusable controls, in DOM order — what Tab cycles through, and
+ *  whose first entry receives focus on open. Menu items are deliberately `tabindex=-1`
+ *  (the menu is one stop, arrow-navigated), so they're collected by class instead. */
+function overlayFocusables(): HTMLElement[] {
+  const modal = document.querySelector<HTMLElement>("#modal-root .modal");
+  if (modal) return [...modal.querySelectorAll<HTMLElement>(FOCUSABLE)];
+  const menu = document.querySelector<HTMLElement>("#menu-root .context-menu");
+  return menu ? [...menu.querySelectorAll<HTMLElement>(".context-item")] : [];
+}
+
+/**
+ * A thunk that puts focus back where it was before an overlay opened. A *thunk*, not
+ * the element, because the element usually doesn't survive: opening a menu repaints
+ * the tree, which swaps the row that triggered it. Restore by identity that outlives a
+ * repaint — a tree row by its path (falling back to the roving row when the path is
+ * gone, e.g. it was just deleted), anything else by its element id, and only then by
+ * the element itself.
+ */
+function captureReturnFocus(): (() => void) | null {
+  const active = document.activeElement;
+  if (!(active instanceof HTMLElement) && !(active instanceof SVGElement)) return null;
+  if (active === document.body) return null;
+  const row = active.closest<HTMLElement>("#tree-pane .tree-row[data-tree-row]");
+  if (row) {
+    const path = row.dataset.treeRow ?? null;
+    return () => (treeRowEl(path) ?? rovingRowEl())?.focus();
+  }
+  if (active.id) {
+    const id = active.id;
+    return () => document.getElementById(id)?.focus();
+  }
+  return () => {
+    if (active.isConnected) active.focus();
+  };
+}
+
+let overlayShowing: OverlayKind = null;
+let overlayReturn: (() => void) | null = null;
+
+/** Called at the end of every `render()`: acts only on the open/close edge. */
+function syncOverlayFocus(): void {
+  const now = currentOverlay();
+  if (now === overlayShowing) return;
+  // The *first* overlay of a chain remembers where the keyboard was; a menu that hands
+  // off to a modal (Move… / Delete) keeps that original target, so closing the modal
+  // returns to the tree row, not to a menu item that no longer exists.
+  if (overlayShowing === null) overlayReturn = captureReturnFocus();
+  overlayShowing = now;
+  if (now === null) {
+    const back = overlayReturn;
+    overlayReturn = null;
+    // …unless an inline tree input just took the keyboard: Rename and New note are
+    // reached *through* the menu, so the menu closing must not yank focus back out
+    // of the input it just opened.
+    if (state.treeCreate || state.treeRename) return;
+    back?.();
+    return;
+  }
+  // The link modal opens on its explanation field — the one thing you came here to type.
+  const preferred = now === "link" ? document.getElementById("link-explanation") : null;
+  (preferred ?? overlayFocusables()[0])?.focus();
+}
+
 // Paint just the Back/Forward buttons' enabled state — never a pane rebuild. Disabled
 // at the stack's ends, and mid-op like the vault switcher (navGo also guards, for the
 // keyboard/mouse paths that don't go through a disabled button).
@@ -943,6 +1141,13 @@ async function executeDelete(node: TreeNodeRef): Promise<void> {
   if (affected && !fmEditGuard()) return;
   if (affected && state.editing && !(await closeEditor())) return;
 
+  // Where the keyboard lands once this row is gone (K1): the next visible row, else the
+  // previous one — the platform reflex after a delete, and the difference between arrow
+  // navigation that survives a delete and one that dumps focus back at the top. Computed
+  // *before* the delete, while the row is still in the list. Harmless for mouse users:
+  // it only moves the tree's roving tabstop.
+  const nextFocus = neighborPath(treeRows(), node.path);
+
   deleteInFlight = true;
   try {
     let what: string;
@@ -964,6 +1169,7 @@ async function executeDelete(node: TreeNodeRef): Promise<void> {
     // Clear state that pointed into the deleted subtree — before the watcher's
     // debounced pulse re-reads it and flashes "moved or removed" for our own delete.
     if (node.nodeKind === "folder") dropDirState(node.path);
+    state.treeFocus = nextFocus;
     if (affected) {
       state.current = null;
       state.currentResource = null;
@@ -1190,6 +1396,24 @@ function closeSettings(): void {
   render();
 }
 
+// --- the keyboard reference (?) ----------------------------------------------------
+//
+// K1's discoverable half: a promise nobody can find is not kept. The table lives in
+// shortcuts.ts; this is only the overlay's open/close. It renders *over* Settings (one
+// of its two entry points is a button there), so closing it leaves Settings as it was.
+
+function openShortcuts(): void {
+  state.contextMenu = null;
+  state.shortcutsOpen = true;
+  render();
+}
+
+function closeShortcuts(): void {
+  if (!state.shortcutsOpen) return;
+  state.shortcutsOpen = false;
+  render();
+}
+
 // --- appearance (light/dark) ------------------------------------------------------
 //
 // A pure front-end preference: "system" (the default) defers to the OS via the
@@ -2431,7 +2655,8 @@ function buildShell(): void {
         </button>
       </div>
       <form id="search-form" class="search" autocomplete="off">
-        <input id="search-input" type="search" placeholder="Search the vault…" aria-label="Search" />
+        <input id="search-input" type="search" placeholder="Search the vault…  ⇧⌘F" aria-label="Search"
+               title="Search the vault — ⇧⌘F (⌘F finds inside the open note)" />
       </form>
       <div class="topbar-right">
         <div id="reindex-progress" class="reindex-progress" hidden aria-live="polite">
@@ -2456,15 +2681,20 @@ function buildShell(): void {
     </header>
     <div id="embed-banner"></div>
     <main id="layout" class="layout">
-      <nav id="tree-pane" class="tree-pane"></nav>
+      <!-- The three panes carry tabindex="-1" so ⌘1/⌘2/⌘3 can put the keyboard *in* a
+           pane (K1) without adding three more stops to the Tab order. The note pane is
+           also the scroll container, so focusing it is what lets the arrows read a note. -->
+      <nav id="tree-pane" class="tree-pane" tabindex="-1"></nav>
       <div id="gutter-tree" class="gutter" role="separator" aria-orientation="vertical"
            aria-label="Resize the file tree" aria-controls="tree-pane" tabindex="0"
+           title="Drag, or ←/→ to resize (⇧ for a bigger step, Home/End for the limits, ⏎ to reset)"
            aria-valuemin="${BOUNDS.tree.min}" aria-valuemax="${BOUNDS.tree.max}"></div>
-      <section id="note-pane" class="note-pane"></section>
+      <section id="note-pane" class="note-pane" tabindex="-1"></section>
       <div id="gutter-side" class="gutter" role="separator" aria-orientation="vertical"
            aria-label="Resize the discovery pane" aria-controls="side-pane" tabindex="0"
+           title="Drag, or ←/→ to resize (⇧ for a bigger step, Home/End for the limits, ⏎ to reset)"
            aria-valuemin="${BOUNDS.side.min}" aria-valuemax="${BOUNDS.side.max}"></div>
-      <aside id="side-pane" class="side-pane"></aside>
+      <aside id="side-pane" class="side-pane" tabindex="-1"></aside>
       <div id="find-bar" class="find-bar" role="search" aria-label="Find in note" hidden>
         <div class="find-field">
           <svg class="find-glass" viewBox="0 0 16 16" width="13" height="13" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true">
@@ -2557,6 +2787,18 @@ function wireEvents(): void {
       return;
     }
 
+    // The keyboard sheet renders over everything (Settings included), so it claims the
+    // click first — otherwise the Settings branch below would swallow it.
+    if (state.shortcutsOpen) {
+      if (
+        target.closest("[data-shortcuts-close]") ||
+        target.classList.contains("modal-backdrop")
+      ) {
+        closeShortcuts();
+      }
+      return;
+    }
+
     if (target.closest("#open-settings")) {
       void openSettings();
       return;
@@ -2576,6 +2818,10 @@ function wireEvents(): void {
     // click on the backdrop itself closes it. Checked before the link-modal backdrop
     // branch so settings wins when it's up.
     if (state.settingsOpen) {
+      if (target.closest("[data-shortcuts-open]")) {
+        openShortcuts();
+        return;
+      }
       if (target.closest("#settings-provision")) {
         void provisionModel();
         return;
@@ -2705,6 +2951,13 @@ function wireEvents(): void {
       return;
     }
 
+    // A click on a tree row moves the keyboard's idea of "where I am" with it, so
+    // switching from mouse to keyboard resumes at the row just clicked rather than
+    // teleporting to the roving tabstop's fallback. (WebKit doesn't focus a button on
+    // click, so the `focusin` path alone wouldn't see this.)
+    const treeRow = target.closest<HTMLElement>("#tree-pane .tree-row[data-tree-row]");
+    if (treeRow) state.treeFocus = treeRow.dataset.treeRow ?? null;
+
     const dir = target.closest<HTMLElement>("[data-dir]");
     if (dir) {
       toggleDir(dir.dataset.dir ?? "");
@@ -2797,6 +3050,51 @@ function wireEvents(): void {
     openCardMenu(e.clientX, e.clientY, card.dataset.cardPath ?? "", card.dataset.cardTitle ?? "");
   });
 
+  // The file tree's own keyboard, the ARIA `tree` pattern (K1, GH #78). Bound to the
+  // pane rather than the document so it answers *before* the global chords below, and
+  // only while the keyboard is actually on a row. The moves themselves are pure and
+  // tested (treenav.ts `arrowMove`) — this half is just the DOM and the folding.
+  //
+  // ⏎ and Space are deliberately absent: a row IS a <button>, so the platform already
+  // turns both into the click the delegation above answers. Re-binding them here would
+  // be a second activation path to keep in sync with the first.
+  el("tree-pane").addEventListener("keydown", (e) => {
+    // The inline create/rename inputs live in this pane but are text entry — they own
+    // their keys (Enter/Escape), handled with the other text surfaces below.
+    if (e.target instanceof HTMLInputElement) return;
+    const row = (e.target as HTMLElement).closest<HTMLElement>(".tree-row[data-tree-row]");
+    if (!row) return;
+    const path = row.dataset.treeRow ?? "";
+    const rows = treeRows();
+
+    const move = arrowMove(rows, rowIndex(rows, path), e.key);
+    if (move) {
+      e.preventDefault();
+      if (move.kind === "focus") {
+        focusTreeRow(move.path);
+      } else {
+        // Expand/collapse keeps the focus where it is; the fold is the whole gesture.
+        if (move.kind === "expand") state.expandedDirs.add(move.path);
+        else state.expandedDirs.delete(move.path);
+        state.selectedDir = move.path; // folding a folder makes it the create context, as a click does
+        state.treeFocus = move.path;
+        render();
+        treeRowEl(move.path)?.focus();
+      }
+      return;
+    }
+
+    // First-letter typeahead — the reflex every file browser answers to. Guarded to
+    // bare printable keys so ⌘N, ⌘F and friends still reach the global handler.
+    if (e.key.length === 1 && e.key !== " " && !e.metaKey && !e.ctrlKey && !e.altKey) {
+      const hit = typeaheadTarget(rows, rowIndex(rows, path), e.key);
+      if (hit !== null) {
+        e.preventDefault();
+        focusTreeRow(hit);
+      }
+    }
+  });
+
   // The floating menu is positioned at fixed viewport coords, so any scroll or resize
   // strands it — dismiss rather than let it hover over the wrong card. Capture-phase so
   // a scroll inside the side pane (which doesn't bubble) is still caught.
@@ -2889,6 +3187,35 @@ function wireEvents(): void {
       }
       return;
     }
+    // An open overlay owns Tab (K1): without a trap, Tab walks the page *behind* the
+    // modal — focus vanishes under the backdrop and the overlay becomes dismissible
+    // only with the mouse. Wrapping keeps every control in it reachable, forever.
+    if (e.key === "Tab" && currentOverlay() !== null) {
+      const items = overlayFocusables();
+      if (items.length > 0) {
+        e.preventDefault();
+        const i = items.indexOf(document.activeElement as HTMLElement);
+        const step = e.shiftKey ? -1 : 1;
+        const next =
+          i < 0 ? (e.shiftKey ? items.length - 1 : 0) : (i + step + items.length) % items.length;
+        items[next].focus();
+      }
+      return;
+    }
+    // ↑/↓ walk an open context menu — the menu-pattern sibling of the tree's arrows.
+    // (⏎ needs no binding: the items are buttons.)
+    if (state.contextMenu && (e.key === "ArrowDown" || e.key === "ArrowUp")) {
+      const items = overlayFocusables();
+      if (items.length > 0) {
+        e.preventDefault();
+        const i = items.indexOf(document.activeElement as HTMLElement);
+        const n = items.length;
+        const next =
+          i < 0 ? (e.key === "ArrowDown" ? 0 : n - 1) : (i + (e.key === "ArrowDown" ? 1 : -1) + n) % n;
+        items[next].focus();
+      }
+      return;
+    }
     // The find bar's input: Enter steps (⇧Enter back), Escape closes. Everything else
     // falls through so the global chords (⌘F itself, ⇧⌘F) still work from the bar.
     if (findOpen && (e.target as HTMLElement).id === "find-input") {
@@ -2905,7 +3232,7 @@ function wireEvents(): void {
     }
     // ⌘F — find in the open note; ⇧⌘F — jump to the global vault-search box.
     if ((e.metaKey || e.ctrlKey) && !e.altKey && e.key.toLowerCase() === "f") {
-      if (state.settingsOpen || state.linkTarget || state.moveTarget || state.deleteTarget) return;
+      if (currentOverlay() !== null) return;
       e.preventDefault();
       if (e.shiftKey) focusGlobalSearch();
       else openFind();
@@ -2918,11 +3245,85 @@ function wireEvents(): void {
       return;
     }
     if ((e.metaKey || e.ctrlKey) && !e.altKey && e.key.toLowerCase() === "n") {
-      if (state.settingsOpen || state.linkTarget || state.moveTarget || state.deleteTarget) return; // a modal owns the keyboard
+      if (currentOverlay() !== null) return; // an overlay owns the keyboard
       e.preventDefault();
       startTreeCreate(e.shiftKey ? "folder" : "note", state.selectedDir);
       return;
     }
+    // ⇧F10 / the Menu key — the keyboard's right-click, and the entry point that makes
+    // Rename / Move… / Link… reachable without a mouse at all (they live only in the
+    // context menu). Opens the *same* menu the mouse does, anchored under whatever the
+    // keyboard is on: a tree row, or a discovery card / graph ghost.
+    if (e.key === "ContextMenu" || (e.shiftKey && e.key === "F10")) {
+      if (currentOverlay() !== null || state.vaultRoot === null) return;
+      const row = focusedTreeRow();
+      if (row) {
+        e.preventDefault();
+        const node = treeRowRef(row);
+        const dir = node.nodeKind === "folder" ? node.path : parentDir(node.path);
+        state.selectedDir = dir;
+        const box = row.getBoundingClientRect();
+        openTreeMenu(box.left + 12, box.bottom, dir, node.path ? node : null);
+        return;
+      }
+      const active = document.activeElement;
+      const card =
+        active instanceof HTMLElement || active instanceof SVGElement
+          ? active.closest<HTMLElement>(".card.candidate, .gnode.is-ghost")
+          : null;
+      if (card) {
+        e.preventDefault();
+        const box = card.getBoundingClientRect();
+        openCardMenu(
+          box.left + 12,
+          box.bottom,
+          card.dataset.cardPath ?? "",
+          card.dataset.cardTitle ?? "",
+        );
+      }
+      return;
+    }
+    // F2 — rename the focused tree row. The platform rename chord, and the direct path
+    // the context menu advertises next to the item.
+    if (e.key === "F2" && !e.shiftKey && !e.metaKey && !e.ctrlKey) {
+      const row = focusedTreeRow();
+      if (!row) return;
+      e.preventDefault();
+      startTreeRename(treeRowRef(row));
+      return;
+    }
+    // ? — the keyboard reference. Bare `?` (⇧/ on a US layout), so it can't collide
+    // with typing: any text surface is excluded, editing included.
+    if (e.key === "?" && !e.metaKey && !e.ctrlKey && !e.altKey) {
+      if (state.editing || inTextEntry()) return;
+      e.preventDefault();
+      if (state.shortcutsOpen) closeShortcuts();
+      else openShortcuts();
+      return;
+    }
+    // ⌘1 / ⌘2 / ⌘3 — put the keyboard in the files, the note, or discovery. Without
+    // them, reaching the tree means Tab-ing through the whole top bar first, which is
+    // "operable" only in the letter of K1, not its spirit.
+    if (
+      (e.metaKey || e.ctrlKey) &&
+      !e.altKey &&
+      !e.shiftKey &&
+      (e.key === "1" || e.key === "2" || e.key === "3")
+    ) {
+      if (currentOverlay() !== null) return;
+      e.preventDefault();
+      if (e.key === "1") focusTreePane();
+      else if (e.key === "2") focusNotePane();
+      else focusSidePane();
+      return;
+    }
+    // Enter commits the link modal from anywhere inside it — the keyboard sibling of
+    // "Commit link" (the explanation field is a plain input, so ⏎ would do nothing).
+    if (state.linkTarget && e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      void commitLink();
+      return;
+    }
     // Enter commits the folder-delete confirm (its keyboard sibling of the button).
     if (state.deleteTarget && e.key === "Enter") {
       e.preventDefault();
@@ -2931,25 +3332,44 @@ function wireEvents(): void {
       void executeDelete(node);
       return;
     }
-    // ⌘⌫ — delete the selected file (the tree's active row IS the open document).
-    // Reading view only: while editing — or in any text field — ⌘⌫ is the platform
-    // delete-to-line-start and must not be hijacked. Folders have no ⌘⌫ path (no
-    // folder-focus state exists); they delete via the context menu, which confirms.
+    // ⏎ / Space on a focused graph node. SVG has no native button activation, so the
+    // key becomes the click the delegation above already answers — one activation path
+    // for both hands, not two implementations to keep in step.
+    if (e.key === "Enter" || e.key === " ") {
+      const active = document.activeElement;
+      const node =
+        active instanceof SVGElement || active instanceof HTMLElement
+          ? active.closest(".gnode[tabindex]")
+          : null;
+      if (node) {
+        e.preventDefault();
+        node.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+        return;
+      }
+    }
+    // ⌘⌫ — delete. The focused tree row wins (a folder among them: it opens the
+    // confirm, so the one gesture now covers folders too); with the keyboard elsewhere
+    // it falls back to the open document, the reader's expectation. Reading view only:
+    // while editing — or in any text field — ⌘⌫ is the platform delete-to-line-start
+    // and must not be hijacked.
     if ((e.metaKey || e.ctrlKey) && !e.altKey && !e.shiftKey && e.key === "Backspace") {
-      if (state.settingsOpen || state.linkTarget || state.moveTarget || state.deleteTarget) return;
+      if (currentOverlay() !== null) return;
       if (state.editing || inTextEntry()) return;
-      const node: TreeNodeRef | null = state.current
-        ? { path: state.current.path, nodeKind: "note", label: baseName(state.current.path) }
-        : state.currentResource
-          ? {
-              path: state.currentResource.path,
-              nodeKind: "resource",
-              label: baseName(state.currentResource.path),
-            }
-          : null;
+      const row = focusedTreeRow();
+      const node: TreeNodeRef | null = row
+        ? treeRowRef(row)
+        : state.current
+          ? { path: state.current.path, nodeKind: "note", label: baseName(state.current.path) }
+          : state.currentResource
+            ? {
+                path: state.currentResource.path,
+                nodeKind: "resource",
+                label: baseName(state.currentResource.path),
+              }
+            : null;
       if (!node) return;
       e.preventDefault();
-      void executeDelete(node);
+      requestDelete(node);
       return;
     }
     if ((e.metaKey || e.ctrlKey) && e.key === ",") {
@@ -2962,7 +3382,7 @@ function wireEvents(): void {
     // owns the keyboard first; a resource or empty pane has nothing to edit. Works while
     // editing (CodeMirror leaves Mod-e unbound, so the event bubbles here) to flip back.
     if ((e.metaKey || e.ctrlKey) && !e.altKey && !e.shiftKey && e.key.toLowerCase() === "e") {
-      if (state.settingsOpen || state.linkTarget || state.moveTarget || state.deleteTarget) return;
+      if (currentOverlay() !== null) return;
       if (state.editing) {
         e.preventDefault();
         void exitEdit();
@@ -2973,6 +3393,12 @@ function wireEvents(): void {
       return;
     }
     if (e.key === "Escape") {
+      // Innermost first, always: the sheet renders over Settings, so Esc closes it and
+      // leaves Settings exactly as it was.
+      if (state.shortcutsOpen) {
+        closeShortcuts();
+        return;
+      }
       if (state.contextMenu) {
         closeContextMenu();
         return;
@@ -3022,7 +3448,7 @@ function wireEvents(): void {
     // search field). The buttons and mouse back/forward stay live everywhere — they
     // flush through navGo's edit-mode guard.
     if ((e.metaKey || e.ctrlKey) && !e.shiftKey && !e.altKey && !state.editing) {
-      if (state.settingsOpen || state.linkTarget || state.moveTarget || state.deleteTarget) return;
+      if (currentOverlay() !== null) return;
       const back = e.key === "[" || e.key === "ArrowLeft";
       const forward = e.key === "]" || e.key === "ArrowRight";
       if (!back && !forward) return;
diff --git a/ui/src/panes.ts b/ui/src/panes.ts
index f44dfdb..daeae68 100644
--- a/ui/src/panes.ts
+++ b/ui/src/panes.ts
@@ -196,8 +196,16 @@ export function initPanes(root: HTMLElement): void {
     });
 
     // Keyboard: a separator that only responds to a mouse is a separator half the
-    // people here can't move.
+    // people here can't move. Enter is the double-click above — the reset the drag
+    // gesture's own escape hatch offers, owed a key like every other click (K1).
     gutter.addEventListener("keydown", (e: KeyboardEvent) => {
+      if (e.key === "Enter") {
+        e.preventDefault();
+        desired[pane] = BOUNDS[pane].default;
+        apply();
+        save(desired);
+        return;
+      }
       const step = e.shiftKey ? 48 : 16;
       let delta = 0;
       if (e.key === "ArrowLeft") delta = pane === "tree" ? -step : step;
diff --git a/ui/src/render.ts b/ui/src/render.ts
index 9cbae28..43149ef 100644
--- a/ui/src/render.ts
+++ b/ui/src/render.ts
@@ -13,7 +13,17 @@ import { escapeHtml } from "./escape";
 import { RELATION_VERBS, type AppState, type SideSection } from "./state";
 import { allDirs, canMoveInto, renamePrefill } from "./move";
 import { shouldPromptEmbedInstall } from "./embedreminder";
-import type { NoteSummary, NoteView, ResourceExplainView, ResourceSummary } from "./types";
+import { SHORTCUTS } from "./shortcuts";
+import {
+  buildTree,
+  CLASS_GLYPHS,
+  rovingPath,
+  sortedFiles,
+  sortedSubdirs,
+  visibleRows,
+  type TreeDir,
+} from "./treenav";
+import type { NoteView, ResourceExplainView } from "./types";
 import {
   buildScene,
   NODE_R,
@@ -79,86 +89,10 @@ export function renderMarkdown(md: string): string {
 // the host stays a dumb adapter). Note rows reuse the `[data-open]` delegation that
 // search/discovery cards already use; resource rows get `[data-open-resource]`, which
 // opens the fallback card.
-
-/** One tree leaf — a note or a resource, normalized for display. */
-interface TreeFile {
-  kind: "note" | "resource";
-  path: string;
-  label: string;
-  /** The resource class glyph slot ("" for notes). */
-  glyph: string;
-}
-
-interface TreeDir {
-  name: string;
-  /** Vault-relative folder path, no trailing slash ("" for the root). */
-  path: string;
-  dirs: Map<string, TreeDir>;
-  files: TreeFile[];
-}
-
-/** A small, unobtrusive per-class marker so a resource reads as "not a note". */
-const CLASS_GLYPHS: Record<string, string> = {
-  image: "▣",
-  media: "▶",
-  pdf: "▤",
-  html: "◇",
-  text: "≡",
-  binary: "◆",
-};
-
-/** Fold the flat, path-ordered note + resource lists into one nested folder tree.
- *  `dirs` is the vault's full folder list (`list_dirs`, a live fs walk) — the
- *  structure half of the tree, so a folder renders even when it holds no file
- *  (the fs supports empty folders, so the tree does); a folder that also appears
- *  as a file's path prefix merges harmlessly. */
-function buildTree(
-  notes: NoteSummary[],
-  resources: ResourceSummary[],
-  dirs: Iterable<string>,
-): TreeDir {
-  const root: TreeDir = { name: "", path: "", dirs: new Map(), files: [] };
-  const descend = (dirPath: string): TreeDir => {
-    let dir = root;
-    if (!dirPath) return dir;
-    for (const seg of dirPath.split("/")) {
-      const full = dir.path ? `${dir.path}/${seg}` : seg;
-      let child = dir.dirs.get(seg);
-      if (!child) {
-        child = { name: seg, path: full, dirs: new Map(), files: [] };
-        dir.dirs.set(seg, child);
-      }
-      dir = child;
-    }
-    return dir;
-  };
-  const insert = (file: TreeFile) => {
-    const parts = file.path.split("/");
-    descend(parts.slice(0, -1).join("/")).files.push(file);
-  };
-  for (const note of notes) {
-    insert({ kind: "note", path: note.path, label: fileLabel(note), glyph: "" });
-  }
-  for (const r of resources) {
-    insert({
-      kind: "resource",
-      path: r.path,
-      label: r.path.split("/").pop() ?? r.path,
-      glyph: CLASS_GLYPHS[r.class] ?? CLASS_GLYPHS.binary,
-    });
-  }
-  for (const dir of dirs) {
-    descend(dir);
-  }
-  return root;
-}
-
-/** A note's display label: its title, else the filename without the `.md`. */
-function fileLabel(note: NoteSummary): string {
-  if (note.title) return note.title;
-  const base = note.path.split("/").pop() ?? note.path;
-  return base.replace(/\.md$/i, "");
-}
+//
+// The tree's shape and its *row order* live in treenav.ts — pure, tested, and shared
+// with the arrow-key navigation (K1, GH #78), because a tree you can arrow through in
+// a different order than you can see is worse than no arrows at all.
 
 /** The inline name input for a pending create (new note / new folder), rendered at
  *  the top of its target folder's children. The typed value lives only in the DOM —
@@ -187,13 +121,29 @@ function treeRenameRowHtml(prefill: string, glyph: string, pad: string): string
     </div>`;
 }
 
-/** Render one folder's children (its sub-folders, then its files), recursively. */
-function treeChildrenHtml(dir: TreeDir, state: AppState, depth: number): string {
-  const subdirs = [...dir.dirs.values()].sort((a, b) => a.name.localeCompare(b.name));
-  const files = [...dir.files].sort((a, b) => a.label.localeCompare(b.label));
+/**
+ * Render one folder's children (its sub-folders, then its files), recursively — in
+ * treenav.ts's order, which is also the order the arrow keys walk.
+ *
+ * `roving` is the one row that carries `tabindex="0"`: every other row is `-1`, so
+ * the tree is a *single* Tab stop and the arrow keys move within it (the ARIA tree
+ * pattern — a 1500-note vault is not a tab sequence). `data-tree-row` is the row's
+ * keyboard identity: main.ts looks a row up by path to move focus after a repaint,
+ * without having to build a CSS selector out of an arbitrary filename.
+ */
+function treeChildrenHtml(
+  dir: TreeDir,
+  state: AppState,
+  depth: number,
+  roving: string | null,
+): string {
   // Indent by depth; a folder's own chevron occupies the same slot a file's icon does,
   // so files sit one notch deeper than the folder header above them.
   const pad = (d: number) => `padding-left:${8 + d * 14}px`;
+  // ARIA levels are 1-based; the DOM is flat (rows are siblings, not nested lists),
+  // so `aria-level` is what tells a screen reader how deep a row sits.
+  const level = ` aria-level="${depth + 1}"`;
+  const tab = (path: string) => ` tabindex="${path === roving ? "0" : "-1"}"`;
 
   // An open create input renders first in its target folder (startTreeCreate
   // expanded the chain down to here, so a match is always visible).
@@ -202,25 +152,27 @@ function treeChildrenHtml(dir: TreeDir, state: AppState, depth: number): string
       ? treeCreateRowHtml(state.treeCreate.kind, pad(depth))
       : "";
 
-  const dirHtml = subdirs
+  const dirHtml = sortedSubdirs(dir)
     .map((sub) => {
       const open = state.expandedDirs.has(sub.path);
       const selected = state.selectedDir === sub.path ? " is-selected" : "";
       const header =
         state.treeRename?.path === sub.path
           ? treeRenameRowHtml(renamePrefill(sub.path, "folder"), open ? "▼" : "▶", pad(depth))
-          : `<button class="tree-row tree-dir${selected}" data-dir="${escapeHtml(
+          : `<button class="tree-row tree-dir${selected}" role="treeitem"${level}${tab(
+              sub.path,
+            )} data-tree-row="${escapeHtml(sub.path)}" data-dir="${escapeHtml(
               sub.path,
             )}" style="${pad(depth)}" aria-expanded="${open}" draggable="true">
           <span class="tree-caret">${open ? "▼" : "▶"}</span>
           <span class="tree-label">${escapeHtml(sub.name)}</span>
         </button>`;
-      const body = open ? treeChildrenHtml(sub, state, depth + 1) : "";
+      const body = open ? treeChildrenHtml(sub, state, depth + 1, roving) : "";
       return header + body;
     })
     .join("");
 
-  const fileHtml = files
+  const fileHtml = sortedFiles(dir)
     .map((file) => {
       if (state.treeRename?.path === file.path) {
         return treeRenameRowHtml(
@@ -231,7 +183,11 @@ function treeChildrenHtml(dir: TreeDir, state: AppState, depth: number): string
       }
       if (file.kind === "resource") {
         const active = state.currentResource?.path === file.path ? " is-active" : "";
-        return `<button class="tree-row tree-file tree-resource${active}" data-open-resource="${escapeHtml(
+        return `<button class="tree-row tree-file tree-resource${active}" role="treeitem"${level}${tab(
+          file.path,
+        )} aria-selected="${state.currentResource?.path === file.path}" data-tree-row="${escapeHtml(
+          file.path,
+        )}" data-open-resource="${escapeHtml(
           file.path,
         )}" style="${pad(depth)}" title="${escapeHtml(file.path)}" draggable="true">
             <span class="tree-caret tree-glyph">${file.glyph}</span>
@@ -239,7 +195,11 @@ function treeChildrenHtml(dir: TreeDir, state: AppState, depth: number): string
           </button>`;
       }
       const active = state.current?.path === file.path ? " is-active" : "";
-      return `<button class="tree-row tree-file${active}" data-open="${escapeHtml(
+      return `<button class="tree-row tree-file${active}" role="treeitem"${level}${tab(
+        file.path,
+      )} aria-selected="${state.current?.path === file.path}" data-tree-row="${escapeHtml(
+        file.path,
+      )}" data-open="${escapeHtml(
         file.path,
       )}" style="${pad(depth)}" title="${escapeHtml(file.path)}" draggable="true">
           <span class="tree-caret"></span>
@@ -283,10 +243,23 @@ export function treePaneHtml(state: AppState): string {
     </div>`;
   if (state.vaultRoot === null)
     return head + `<p class="tree-empty">No vault open.</p>`;
-  const body = treeChildrenHtml(buildTree(state.notes, state.resources, state.dirs), state, 0);
+  const tree = buildTree(state.notes, state.resources, state.dirs);
+  // The roving tabstop is resolved against the *visible* rows, so a folder collapsing
+  // under the focused row hands the tabstop back to something reachable rather than
+  // leaving the tree with no tabbable row at all.
+  const roving = rovingPath(
+    visibleRows(tree, state.expandedDirs),
+    state.treeFocus,
+    state.current?.path ?? state.currentResource?.path ?? null,
+  );
+  const body = treeChildrenHtml(tree, state, 0, roving);
   if (!body)
     return head + `<p class="tree-empty">No files indexed yet — Reindex to populate.</p>`;
-  return head + `<div class="tree">${body}</div>`;
+  return (
+    head +
+    `<div class="tree" role="tree" aria-label="Vault files"
+       title="↑↓ move · →← expand/collapse · ⏎ open · F2 rename · ⇧F10 menu">${body}</div>`
+  );
 }
 
 // --- pane builders --------------------------------------------------------------
@@ -737,7 +710,10 @@ const GRAPH_ICON = `<svg viewBox="0 0 16 16" width="14" height="14" aria-hidden=
 /** The graph toggle chip, shared by the reading bar (off) and the graph bar (on). */
 function graphToggleHtml(active: boolean): string {
   return `<button class="source-toggle graph-toggle${active ? " is-active" : ""}" data-toggle-graph
-      aria-pressed="${active}" title="${active ? "Back to reading" : "Show the connection graph"}">${GRAPH_ICON}</button>`;
+      aria-pressed="${active}" aria-label="${active ? "Back to reading" : "Show the connection graph"}"
+      title="${
+        active ? "Back to reading — Esc" : "Show the connection graph — nodes are Tab-reachable, ⏎ opens"
+      }">${GRAPH_ICON}</button>`;
 }
 
 /** Fixed-point SVG coordinate — keeps the markup compact and diff-stable. */
@@ -786,19 +762,36 @@ function nodeShapeHtml(n: GraphNode): string {
   }
 }
 
-/** The tooltip line(s) for a node — also the click affordance's explanation. */
+/** The tooltip line(s) for a node — also the activation affordance's explanation.
+ *  Phrased for both hands: an activatable node says "⏎", because the graph is
+ *  reachable by Tab and arrow keys too (K1, GH #78), not by mouse alone. */
 function nodeTitle(n: GraphNode): string {
   switch (n.kind) {
     case "anchor":
-      return `${n.full} — the open note. Click to return to reading.`;
+      return `${n.full} — the open note. Click or ⏎ to return to reading.`;
     case "ghost":
-      return `${n.full} — similar but not linked (similarity ${n.sub ?? "?"}). Click to link it; right-click for more.`;
+      return `${n.full} — similar but not linked (similarity ${n.sub ?? "?"}). Click or ⏎ to link it; right-click (or ⇧F10) for more.`;
     case "dangling":
       return `${n.full} resolves to no note or file — fix the link in the note.`;
     case "resource":
-      return `${n.full} (${n.sub ?? "file"}) — click to open.`;
+      return `${n.full} (${n.sub ?? "file"}) — click or ⏎ to open.`;
+    default:
+      return `${n.full} — click or ⏎ to open.`;
+  }
+}
+
+/** The accessible name for a focusable node — what a screen reader announces, and
+ *  what the node's own `<title>` can't be (that one is the mouse tooltip prose). */
+function nodeAriaLabel(n: GraphNode): string {
+  switch (n.kind) {
+    case "anchor":
+      return `${n.full} — the open note; back to reading`;
+    case "ghost":
+      return `${n.full} — similar but unlinked; link it`;
+    case "resource":
+      return `${n.full} — open this file`;
     default:
-      return `${n.full} — click to open.`;
+      return `${n.full} — open this note`;
   }
 }
 
@@ -808,6 +801,12 @@ function nodeTitle(n: GraphNode): string {
  * affordance rides existing delegation: notes reuse `data-open`, resources
  * `data-open-resource`; ghosts get `data-ghost-link` (→ the link palette) plus the
  * `data-card-*` pair the right-click menu reads; the anchor toggles back to reading.
+ *
+ * An activatable node is also a **keyboard** control (K1, GH #78): `tabindex="0"` puts
+ * it in the Tab order and `role="button"` says what it is, so a graph is walkable and
+ * openable with no mouse. main.ts turns ⏎/Space on a focused node into the same click
+ * these attributes already answer — one activation path, not two. A `dangling` node
+ * stays inert: it opens nothing (there's nothing there), so it isn't a tab stop.
  */
 function nodeGroupHtml(n: GraphNode, edges: GraphEdge[], order: number): string {
   const attrs: string[] = [`class="gnode is-${n.kind}"`, `style="--i:${order}"`];
@@ -821,6 +820,9 @@ function nodeGroupHtml(n: GraphNode, edges: GraphEdge[], order: number): string
       `data-card-title="${escapeHtml(n.title ?? "")}"`,
     );
   }
+  if (n.kind !== "dangling") {
+    attrs.push(`tabindex="0"`, `role="button"`, `aria-label="${escapeHtml(nodeAriaLabel(n))}"`);
+  }
   const r = NODE_R[n.kind];
   // Text goes on the side of the node facing *away* from the anchor (above for the
   // upper half of the scene), so a label never sits in its own edge's path.
@@ -1074,12 +1076,22 @@ function settingsModalHtml(state: AppState): string {
             : ""
         }
         <div class="modal-actions">
+          <button class="btn ghost" data-shortcuts-open title="Every chord B2 answers to — ?">Keyboard shortcuts</button>
           <button class="btn primary" data-settings-close>Done</button>
         </div>
       </div>
     </div>`;
 }
 
+/** One menu row. `chord` names the direct shortcut where one exists — a menu is where
+ *  a keyboard user *learns* the chord that lets them skip the menu next time. */
+function contextItemHtml(attr: string, label: string, chord = "", danger = false): string {
+  const hint = chord ? `<span class="context-chord">${chord}</span>` : "";
+  return `<button class="context-item${
+    danger ? " is-danger" : ""
+  }" ${attr} role="menuitem" tabindex="-1">${label}${hint}</button>`;
+}
+
 // The right-click menu — one overlay, two surfaces (state.ts `ContextMenuState`):
 // a discovery card (Open note / Link…, replacing the old inline "Link…" button) or
 // the file tree (New note / New folder in the folder under the cursor, named in a
@@ -1097,19 +1109,21 @@ export function contextMenuHtml(state: AppState): string {
     // targeting the folder context either way.
     const node = m.node
       ? `<div class="context-label">${escapeHtml(m.node.path)}</div>
-        <button class="context-item" data-ctx-rename role="menuitem">Rename</button>
-        <button class="context-item" data-ctx-move role="menuitem">Move…</button>
-        <button class="context-item is-danger" data-ctx-delete role="menuitem">Delete</button>
+        ${contextItemHtml("data-ctx-rename", "Rename", "F2")}
+        ${contextItemHtml("data-ctx-move", "Move…")}
+        ${contextItemHtml("data-ctx-delete", "Delete", "⌘⌫", true)}
         <div class="context-sep" role="separator"></div>`
       : `<div class="context-label">${escapeHtml(m.dir ? `${m.dir}/` : "vault root")}</div>`;
     items = `${node}
-        <button class="context-item" data-ctx-new-note role="menuitem">New note</button>
-        <button class="context-item" data-ctx-new-folder role="menuitem">New folder</button>`;
+        ${contextItemHtml("data-ctx-new-note", "New note", "⌘N")}
+        ${contextItemHtml("data-ctx-new-folder", "New folder", "⇧⌘N")}`;
   } else {
-    items = `<button class="context-item" data-ctx-open role="menuitem">Open note</button>
-        <button class="context-item" data-ctx-link role="menuitem">Link…</button>`;
+    items = `${contextItemHtml("data-ctx-open", "Open note", "⏎")}
+        ${contextItemHtml("data-ctx-link", "Link…")}`;
   }
-  return `<div class="context-menu" style="left:${m.x}px;top:${m.y}px" role="menu">${items}</div>`;
+  // `tabindex="-1"` on the menu itself makes the container focusable-by-script but not
+  // by Tab: main.ts moves focus to the first item on open and traps ↑↓/⏎/Esc inside.
+  return `<div class="context-menu" style="left:${m.x}px;top:${m.y}px" role="menu" tabindex="-1">${items}</div>`;
 }
 
 /** The Move… modal: pick a destination folder for the targeted tree node. Every
@@ -1138,6 +1152,7 @@ function moveModalHtml(state: AppState): string {
         <h3>Move ${escapeHtml(t.label)} to…</h3>
         <div class="move-dest-list">${rows}</div>
         <div class="modal-actions">
+          <span class="modal-hint">Tab / ↑↓ pick a folder · ⏎ moves · Esc cancels</span>
           <button class="btn ghost" data-cancel>Cancel</button>
         </div>
       </div>
@@ -1155,6 +1170,7 @@ function deleteModalHtml(state: AppState): string {
         <h3>Delete ${escapeHtml(t.label)}?</h3>
         <p class="muted">${escapeHtml(t.path)}/ and everything inside it will be deleted from the vault and the disk.</p>
         <div class="modal-actions">
+          <span class="modal-hint">⏎ deletes · Esc cancels</span>
           <button class="btn ghost" data-cancel>Cancel</button>
           <button class="btn danger" id="delete-confirm">Delete folder</button>
         </div>
@@ -1162,7 +1178,37 @@ function deleteModalHtml(state: AppState): string {
     </div>`;
 }
 
+/**
+ * The keyboard reference (`?`, or the Settings link) — the discoverable half of
+ * invariant K1: every chord the app answers to, in one place, from the one table in
+ * shortcuts.ts. Rendered *over* whatever else is open (Settings included), so closing
+ * it returns to exactly what was underneath.
+ */
+function shortcutsModalHtml(): string {
+  const groups = SHORTCUTS.map(
+    (g) => `<section class="keys-group">
+        <h4>${escapeHtml(g.title)}</h4>
+        <dl class="keys-list">${g.items
+          .map(
+            (s) => `<dt><kbd>${escapeHtml(s.keys)}</kbd></dt><dd>${escapeHtml(s.action)}</dd>`,
+          )
+          .join("")}</dl>
+      </section>`,
+  ).join("");
+  return `<div class="modal-backdrop">
+      <div class="modal modal-wide" role="dialog" aria-modal="true" aria-label="Keyboard shortcuts">
+        <h3>Keyboard shortcuts</h3>
+        <p class="muted">B2 is fully operable from the keyboard — the mouse is an accelerator, never a requirement.</p>
+        <div class="keys-grid">${groups}</div>
+        <div class="modal-actions">
+          <button class="btn primary" data-shortcuts-close>Done</button>
+        </div>
+      </div>
+    </div>`;
+}
+
 export function modalHtml(state: AppState): string {
+  if (state.shortcutsOpen) return shortcutsModalHtml();
   if (state.settingsOpen) return settingsModalHtml(state);
   if (state.moveTarget) return moveModalHtml(state);
   if (state.deleteTarget) return deleteModalHtml(state);
@@ -1190,6 +1236,7 @@ export function modalHtml(state: AppState): string {
           <input id="link-explanation" type="text" placeholder="why they connect" />
         </label>
         <div class="modal-actions">
+          <span class="modal-hint">⏎ commits · Esc cancels</span>
           <button class="btn ghost" data-cancel>Cancel</button>
           <button class="btn primary" id="link-commit">Commit link</button>
         </div>
diff --git a/ui/src/shortcuts.test.ts b/ui/src/shortcuts.test.ts
new file mode 100644
index 0000000..70f7b3c
--- /dev/null
+++ b/ui/src/shortcuts.test.ts
@@ -0,0 +1,68 @@
+// The keyboard reference's own shape (shortcuts.ts), pinned. Pure data — no DOM — so
+// node runs it straight off the source: `npm test`. Dependency-free like the others.
+//
+// These check the *sheet as an artifact*, not the wiring: whether a given chord is
+// actually bound lives in main.ts's keydown handler, which pulls in CodeMirror and the
+// stylesheet and so can't be imported here. What a table like this really gets wrong is
+// smaller and duller — a half-filled row that renders as a blank line, one chord listed
+// twice in the same group meaning two different things, or an entry spelled "Cmd+N"
+// among a page of ⌘N. Those are exactly the drifts that make a reference stop reading
+// as authoritative, and they're what's asserted below (K1, GH #78).
+import { SHORTCUTS } from "./shortcuts.ts";
+
+let passed = 0;
+
+function assert(cond: boolean, msg: string): void {
+  if (!cond) throw new Error(`assertion failed: ${msg}`);
+}
+function check(name: string, fn: () => void): void {
+  fn();
+  passed++;
+  console.log(`  ok  ${name}`);
+}
+
+check("every group has a title and at least one row", () => {
+  assert(SHORTCUTS.length > 0, "the sheet is not empty");
+  for (const g of SHORTCUTS) {
+    assert(g.title.trim() !== "", "a group with no title");
+    assert(g.items.length > 0, `an empty group: ${g.title}`);
+  }
+});
+
+check("every row is a full pair — a chord and what it does", () => {
+  for (const g of SHORTCUTS) {
+    for (const s of g.items) {
+      assert(s.keys.trim() !== "", `a row with no chord under ${g.title}`);
+      assert(s.action.trim() !== "", `a chord with no action: ${s.keys}`);
+    }
+  }
+});
+
+check("no chord is listed twice within one group", () => {
+  // Across groups is fine and deliberate — ⇧F10 opens a menu on a tree row *and* on a
+  // discovery card, ⏎ activates whatever is focused. Two meanings in one group is the
+  // contradiction: the reader has no way to tell which one applies.
+  for (const g of SHORTCUTS) {
+    const seen = new Set<string>();
+    for (const s of g.items) {
+      assert(!seen.has(s.keys), `${s.keys} appears twice under ${g.title}`);
+      seen.add(s.keys);
+    }
+  }
+});
+
+check("modifiers are written as macOS glyphs, never spelled out", () => {
+  // The sheet sits beside button tooltips that render ⌘/⇧, so a stray "Cmd+N" reads as
+  // a different app's documentation. Only the *modifiers* are held to this: macOS spells
+  // Esc / Tab / Space / Home / End out in its own menus, and so does B2's existing
+  // chrome ("Close (Esc)"), so those stay words — shortcuts.ts says why.
+  const spelled = /\b(cmd|command|ctrl|control|shift|alt|option|enter|return|backspace)\b/i;
+  for (const g of SHORTCUTS) {
+    for (const s of g.items) {
+      assert(!spelled.test(s.keys), `${JSON.stringify(s.keys)} spells out a modifier (${g.title})`);
+      assert(!s.keys.includes("+"), `${JSON.stringify(s.keys)} joins with "+" instead of adjacency`);
+    }
+  }
+});
+
+console.log(`shortcuts: ${passed} checks passed`);
diff --git a/ui/src/shortcuts.ts b/ui/src/shortcuts.ts
new file mode 100644
index 0000000..94f7f9b
--- /dev/null
+++ b/ui/src/shortcuts.ts
@@ -0,0 +1,85 @@
+// The keyboard reference — the single source of truth for what the `?` cheat sheet
+// shows. Pure data, no DOM, so node runs its test straight off the source
+// (`npm test`), like newentry.ts / move.ts / treenav.ts.
+//
+// Why a table rather than prose in a docs page: invariant K1 (docs/design/invariants.md,
+// GH #78) promises every mouse action has a keyboard path, and a promise nobody can
+// *find* is not kept. A shortcut that exists only in a button's `title` is discoverable
+// exactly once — by hovering the button you already knew about. This list is the app's
+// answer to "what can I do without the mouse", and adding a chord means adding a row
+// here in the same change, so the sheet can't quietly fall behind the wiring.
+//
+// B2 ships on macOS only (crates/b2-desktop), so modifiers are the platform's glyphs —
+// ⌘ command, ⇧ shift, ⌫ delete, ⏎ return — while keys macOS itself spells out in menus
+// stay spelled out (Esc, Tab, Space, Home/End). That's the split the app's existing
+// tooltips already use ("Close (Esc)"), and the one the sheet must not drift from:
+// ⎋ and ⇥ exist, but nobody reads them.
+
+/** One chord and what it does. `keys` is display text — the wiring lives in main.ts. */
+export interface Shortcut {
+  keys: string;
+  action: string;
+}
+
+export interface ShortcutGroup {
+  title: string;
+  items: Shortcut[];
+}
+
+export const SHORTCUTS: ShortcutGroup[] = [
+  {
+    title: "Getting around",
+    items: [
+      { keys: "⌘1 / ⌘2 / ⌘3", action: "Focus the files, the note, or discovery" },
+      { keys: "⇧⌘F", action: "Search the vault" },
+      { keys: "⌘F", action: "Find in this note" },
+      { keys: "⌘G / ⇧⌘G", action: "Next / previous match" },
+      { keys: "⌘[ / ⌘]", action: "Back / forward (⌘← / ⌘→ too)" },
+      { keys: "⏎", action: "Follow the focused link, card, or graph node" },
+    ],
+  },
+  {
+    title: "The file tree",
+    items: [
+      { keys: "↑ / ↓", action: "Move between rows" },
+      { keys: "→", action: "Expand a folder, or step into it" },
+      { keys: "←", action: "Collapse a folder, or step out to its parent" },
+      { keys: "Home / End", action: "First / last row" },
+      { keys: "A–Z", action: "Jump to the next row starting with that letter" },
+      { keys: "⏎ / Space", action: "Open the note or file; fold the folder" },
+      { keys: "⌘N / ⇧⌘N", action: "New note / new folder in the selected folder" },
+      { keys: "F2", action: "Rename the focused row" },
+      { keys: "⌘⌫", action: "Delete the focused row (a folder confirms first)" },
+      { keys: "⇧F10", action: "Open the row's menu — Rename, Move…, Delete" },
+    ],
+  },
+  {
+    title: "Reading and editing",
+    items: [
+      { keys: "⌘E", action: "Enter or leave edit mode" },
+      { keys: "⌘S", action: "Save now (editing autosaves anyway)" },
+      { keys: "⌘B / ⌘I", action: "Bold / italic" },
+      { keys: "⌘T", action: "Insert a table" },
+      { keys: "⇧⌘V", action: "Paste as plain text" },
+      { keys: "[[", action: "Wikilink completion — ↑↓ then ⏎" },
+      { keys: "⌘⏎", action: "Save the frontmatter drawer (Esc discards)" },
+    ],
+  },
+  {
+    title: "Discovery, graph, and menus",
+    items: [
+      { keys: "⇧F10", action: "Open a card's menu — Open note, Link…" },
+      { keys: "⏎ / Space", action: "Open a graph node; a ghost opens the link palette" },
+      { keys: "↑ / ↓", action: "Move through an open menu" },
+      { keys: "Esc", action: "Close a menu, a modal, the find bar, or the graph" },
+    ],
+  },
+  {
+    title: "The app",
+    items: [
+      { keys: "⌘,", action: "Settings" },
+      { keys: "?", action: "This sheet" },
+      { keys: "Tab", action: "Step through the controls on screen" },
+    ],
+  },
+];
diff --git a/ui/src/state.ts b/ui/src/state.ts
index f8d13c6..9a0177a 100644
--- a/ui/src/state.ts
+++ b/ui/src/state.ts
@@ -94,6 +94,15 @@ export interface AppState {
    * last folder row clicked/right-clicked. "" is the vault root (the default).
    */
   selectedDir: string;
+  /**
+   * The tree row the keyboard is on (its vault-relative path), or null before any
+   * arrow key has been pressed. Distinct from `selectedDir` (the *create* context)
+   * and from `current` (the *open* document): a keyboard user arrows across rows
+   * without opening them, which is the whole point of arrow navigation. Drives the
+   * roving `tabindex` (treenav.ts `rovingPath`), so the tree is one Tab stop rather
+   * than one per file — invariant K1, GH #78.
+   */
+  treeFocus: string | null;
   /** An inline name input open in the tree (new note / new folder in `dir`), or null. */
   treeCreate: { kind: "note" | "folder"; dir: string } | null;
   /** An inline rename input open on a tree row, or null. */
@@ -188,6 +197,12 @@ export interface AppState {
   linkRelation: string;
   /** The settings modal (⌘,) is open. */
   settingsOpen: boolean;
+  /**
+   * The keyboard-reference sheet (`?`) is open. Rendered *over* whatever else is up
+   * (it opens from Settings too), so it takes precedence in `modalHtml` and closes
+   * first on Escape — leaving the overlay underneath exactly as it was. K1, GH #78.
+   */
+  shortcutsOpen: boolean;
   /** Appearance preference (System/Light/Dark) — mirrors `localStorage`, shown in Settings. */
   theme: ThemePref;
   /** The embedding models offered in Settings — loaded when the modal opens, else empty. */
@@ -233,6 +248,7 @@ export const state: AppState = {
   dirs: [],
   expandedDirs: new Set<string>(),
   selectedDir: "",
+  treeFocus: null,
   treeCreate: null,
   treeRename: null,
   moveTarget: null,
@@ -259,6 +275,7 @@ export const state: AppState = {
   linkTarget: null,
   linkRelation: "references",
   settingsOpen: false,
+  shortcutsOpen: false,
   theme: "system",
   models: [],
   embedStats: [],
diff --git a/ui/src/treenav.test.ts b/ui/src/treenav.test.ts
new file mode 100644
index 0000000..0b675d1
--- /dev/null
+++ b/ui/src/treenav.test.ts
@@ -0,0 +1,231 @@
+// The file tree's navigation rules (treenav.ts), pinned. Pure logic — no DOM — so node
+// runs it straight off the source via its native type-stripping: `npm test`.
+// Dependency-free like newentry.test.ts / panes.test.ts (hand-rolled assert).
+//
+// What's under test is invariant K1's tree half (GH #78): the *visible* row order the
+// arrows walk, and the ARIA tree-pattern moves over it. The order matters twice over —
+// render.ts paints from the same `sortedSubdirs`/`sortedFiles` this flattens with, so
+// these cases are also the guard against the paint and the arrows drifting apart.
+import {
+  arrowMove,
+  buildTree,
+  neighborPath,
+  rovingPath,
+  rowIndex,
+  typeaheadTarget,
+  visibleRows,
+  type TreeRow,
+} from "./treenav.ts";
+import type { NoteSummary, ResourceSummary } from "./types.ts";
+
+let passed = 0;
+
+function assert(cond: boolean, msg: string): void {
+  if (!cond) throw new Error(`assertion failed: ${msg}`);
+}
+function equal(actual: unknown, expected: unknown, msg: string): void {
+  assert(
+    actual === expected,
+    `${msg} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
+  );
+}
+function check(name: string, fn: () => void): void {
+  fn();
+  passed++;
+  console.log(`  ok  ${name}`);
+}
+
+// --- fixtures ------------------------------------------------------------------------
+
+const note = (path: string, title: string | null = null): NoteSummary =>
+  ({ path, title }) as NoteSummary;
+const resource = (path: string, cls = "pdf"): ResourceSummary =>
+  ({ path, class: cls }) as ResourceSummary;
+
+/**
+ * A small vault with every shape that matters: nested folders, an empty folder (the fs
+ * is authoritative for structure, so it's a real row), a resource beside a note, and a
+ * title that sorts differently from its filename.
+ *
+ *   archive/            (folder, empty)
+ *   concepts/           (folder)
+ *     deep/             (folder)
+ *       nested.md
+ *     memory.md
+ *     spec.pdf
+ *   readme.md           ("Alpha" by title)
+ */
+const NOTES = [note("concepts/memory.md"), note("concepts/deep/nested.md"), note("readme.md", "Alpha")];
+const RESOURCES = [resource("concepts/spec.pdf")];
+const DIRS = ["archive", "concepts", "concepts/deep"];
+
+const tree = () => buildTree(NOTES, RESOURCES, DIRS);
+const rowsWith = (...expanded: string[]) => visibleRows(tree(), new Set(expanded));
+const paths = (rows: readonly TreeRow[]) => rows.map((r) => r.path).join("|");
+
+// --- visibleRows: the one order the paint and the arrows share ------------------------
+
+check("collapsed: only root-level rows, folders before files", () => {
+  equal(paths(rowsWith()), "archive|concepts|readme.md", "root rows");
+});
+
+check("an expanded folder's children follow it inline, sub-folders first", () => {
+  equal(
+    paths(rowsWith("concepts")),
+    "archive|concepts|concepts/deep|concepts/memory.md|concepts/spec.pdf|readme.md",
+    "one level open",
+  );
+});
+
+check("expansion nests, and a collapsed child hides its own subtree", () => {
+  equal(
+    paths(rowsWith("concepts", "concepts/deep")),
+    "archive|concepts|concepts/deep|concepts/deep/nested.md|concepts/memory.md|concepts/spec.pdf|readme.md",
+    "two levels open",
+  );
+  // `concepts/deep` expanded but its parent closed shows nothing: visibility is the
+  // whole ancestor chain, not a single flag.
+  equal(paths(rowsWith("concepts/deep")), "archive|concepts|readme.md", "an orphaned expansion is inert");
+});
+
+check("files sort by their display label, not their filename", () => {
+  // readme.md is titled "Alpha", so it sorts under A — exactly as the tree paints it.
+  const rows = visibleRows(buildTree([note("zulu.md", "Alpha"), note("alpha.md", "Zulu")], [], []), new Set());
+  equal(paths(rows), "zulu.md|alpha.md", "label order wins");
+});
+
+check("a row carries the depth, kind, and fold state the paint needs", () => {
+  const rows = rowsWith("concepts");
+  const concepts = rows[rowIndex(rows, "concepts")];
+  equal(concepts.nodeKind, "folder", "kind");
+  equal(concepts.depth, 0, "root-level depth");
+  equal(concepts.expanded, true, "expanded");
+  equal(concepts.hasChildren, true, "has children");
+  const archive = rows[rowIndex(rows, "archive")];
+  equal(archive.hasChildren, false, "an empty folder has nothing to step into");
+  const pdf = rows[rowIndex(rows, "concepts/spec.pdf")];
+  equal(pdf.nodeKind, "resource", "a resource is its own kind");
+  equal(pdf.depth, 1, "nested depth");
+});
+
+// --- arrowMove: the ARIA tree pattern ------------------------------------------------
+
+function move(rows: readonly TreeRow[], from: string | null, key: string) {
+  return arrowMove(rows, rowIndex(rows, from), key);
+}
+
+check("up/down step between visible rows and stop at the ends", () => {
+  const rows = rowsWith("concepts");
+  equal(move(rows, "archive", "ArrowDown")?.path, "concepts", "down");
+  equal(move(rows, "concepts", "ArrowUp")?.path, "archive", "up");
+  equal(move(rows, "archive", "ArrowUp"), null, "no wrap off the top");
+  equal(move(rows, "readme.md", "ArrowDown"), null, "no wrap off the bottom");
+});
+
+check("down never descends into a collapsed folder", () => {
+  const rows = rowsWith();
+  equal(move(rows, "concepts", "ArrowDown")?.path, "readme.md", "skips the hidden subtree");
+});
+
+check("Home/End jump to the first and last visible rows", () => {
+  const rows = rowsWith("concepts");
+  equal(move(rows, "concepts", "Home")?.path, "archive", "Home");
+  equal(move(rows, "concepts", "End")?.path, "readme.md", "End");
+});
+
+check("the first arrow press lands even with nothing focused", () => {
+  const rows = rowsWith();
+  equal(move(rows, null, "ArrowDown")?.path, "archive", "down → first");
+  equal(move(rows, null, "ArrowUp")?.path, "readme.md", "up → last");
+  equal(move(rows, null, "ArrowRight")?.path, "archive", "right → first");
+});
+
+check("right expands a collapsed folder, then steps into it", () => {
+  const closed = rowsWith();
+  const expand = move(closed, "concepts", "ArrowRight");
+  equal(expand?.kind, "expand", "collapsed → expand");
+  equal(expand?.path, "concepts", "the folder itself");
+  const open = rowsWith("concepts");
+  const into = move(open, "concepts", "ArrowRight");
+  equal(into?.kind, "focus", "expanded → step in");
+  equal(into?.path, "concepts/deep", "its first child");
+});
+
+check("right does nothing on a file, or on a folder with nothing in it", () => {
+  const rows = rowsWith("concepts");
+  equal(move(rows, "readme.md", "ArrowRight"), null, "a file has no children");
+  equal(move(rows, "archive", "ArrowRight"), null, "an empty folder stays put");
+});
+
+check("left collapses an expanded folder, else steps out to the parent", () => {
+  const open = rowsWith("concepts");
+  const collapse = move(open, "concepts", "ArrowLeft");
+  equal(collapse?.kind, "collapse", "expanded → collapse");
+  equal(collapse?.path, "concepts", "the folder itself");
+  const out = move(open, "concepts/memory.md", "ArrowLeft");
+  equal(out?.kind, "focus", "a file steps out");
+  equal(out?.path, "concepts", "to its folder");
+  equal(move(open, "concepts/deep", "ArrowLeft")?.path, "concepts", "a collapsed folder steps out too");
+  equal(move(open, "readme.md", "ArrowLeft"), null, "at the root there is nowhere out to");
+});
+
+check("a key the tree doesn't own is left alone", () => {
+  const rows = rowsWith();
+  equal(arrowMove(rows, 0, "Enter"), null, "Enter belongs to the button");
+  equal(arrowMove(rows, 0, "n"), null, "letters fall through to typeahead");
+  equal(arrowMove([], -1, "ArrowDown"), null, "an empty tree has no moves");
+});
+
+// --- typeahead ------------------------------------------------------------------------
+
+check("typeahead finds the next match after the focused row, wrapping", () => {
+  const rows = rowsWith("concepts");
+  equal(typeaheadTarget(rows, rowIndex(rows, "archive"), "c"), "concepts", "forward");
+  // From `concepts` itself, "c" wraps past the end and back to `concepts`.
+  equal(typeaheadTarget(rows, rowIndex(rows, "concepts"), "c"), "concepts", "wraps around to itself");
+  equal(typeaheadTarget(rows, -1, "a"), "archive", "from nowhere, the first match");
+});
+
+check("typeahead is case-insensitive and matches the *label*", () => {
+  const rows = rowsWith();
+  // readme.md's label is its title, "Alpha" — so `r` misses it and `a` finds it.
+  equal(typeaheadTarget(rows, -1, "A"), "archive", "upper-case needle");
+  equal(typeaheadTarget(rows, rowIndex(rows, "archive"), "a"), "readme.md", "the title, not the filename");
+  equal(typeaheadTarget(rows, -1, "z"), null, "no match is a miss, not a jump");
+});
+
+// --- the roving tabstop ----------------------------------------------------------------
+
+check("the tabstop prefers the keyboard's row, then the open note, then the first", () => {
+  const rows = rowsWith("concepts");
+  equal(rovingPath(rows, "concepts/memory.md", "readme.md"), "concepts/memory.md", "keyboard wins");
+  equal(rovingPath(rows, null, "readme.md"), "readme.md", "else the open document");
+  equal(rovingPath(rows, null, null), "archive", "else the first row");
+  equal(rovingPath([], "gone.md", "gone.md"), null, "an empty tree has no tabstop");
+});
+
+check("a tabstop that scrolled out of existence falls back rather than vanishing", () => {
+  // `concepts` collapsed: the focused child is no longer a row, so the tree must not be
+  // left with zero tabbable rows (Tab would skip it entirely).
+  const rows = rowsWith();
+  equal(rovingPath(rows, "concepts/memory.md", null), "archive", "collapsed away → first row");
+  equal(rovingPath(rows, "deleted.md", "readme.md"), "readme.md", "deleted → the open document");
+});
+
+// --- neighbour after a delete ----------------------------------------------------------
+
+check("a deleted row hands focus to the next row, else the previous one", () => {
+  const rows = rowsWith("concepts");
+  equal(neighborPath(rows, "archive"), "concepts", "next");
+  equal(neighborPath(rows, "readme.md"), "concepts/spec.pdf", "the last row falls back to the previous");
+  equal(neighborPath(rows, "nope.md"), null, "a row that isn't there has no neighbour");
+});
+
+check("a deleted folder's whole subtree goes with it", () => {
+  const rows = rowsWith("concepts", "concepts/deep");
+  // Not `concepts/deep` (inside it) and not its children — the next row at or above it.
+  equal(neighborPath(rows, "concepts"), "readme.md", "skips the subtree it takes along");
+  equal(neighborPath(rows, "concepts/deep"), "concepts/memory.md", "a nested folder, same rule");
+});
+
+console.log(`treenav: ${passed} checks passed`);
diff --git a/ui/src/treenav.ts b/ui/src/treenav.ts
new file mode 100644
index 0000000..fe46336
--- /dev/null
+++ b/ui/src/treenav.ts
@@ -0,0 +1,281 @@
+// The file tree's pure logic — no DOM, no IPC — so node runs its test straight off
+// the source (`npm test`), like newentry.ts / move.ts.
+//
+// Two jobs, deliberately in one module because they must agree: fold the flat
+// `list_notes` / `list_resources` / `list_dirs` listings into one nested folder tree
+// (`buildTree`), and flatten the *currently visible* rows of that tree into the single
+// ordered list keyboard navigation walks (`visibleRows`). The paint (render.ts's
+// `treeChildrenHtml`) and the arrow keys must agree on row order down to the last
+// tie-break, so the sort lives here once and both sides call it — a tree you can
+// arrow through in a different order than you can see is worse than no arrows at all.
+//
+// Invariant K1 (docs/design/invariants.md, GH #78): the tree is fully navigable from
+// the keyboard, following the ARIA `tree` pattern (up/down between visible rows,
+// right/left to expand/collapse or step in/out, Home/End, first-letter typeahead).
+
+import type { NodeKind } from "./move";
+import type { NoteSummary, ResourceSummary } from "./types";
+
+/** One tree leaf — a note or a resource, normalized for display. */
+export interface TreeFile {
+  kind: "note" | "resource";
+  path: string;
+  label: string;
+  /** The resource class glyph slot ("" for notes). */
+  glyph: string;
+}
+
+export interface TreeDir {
+  name: string;
+  /** Vault-relative folder path, no trailing slash ("" for the root). */
+  path: string;
+  dirs: Map<string, TreeDir>;
+  files: TreeFile[];
+}
+
+/** A small, unobtrusive per-class marker so a resource reads as "not a note". */
+export const CLASS_GLYPHS: Record<string, string> = {
+  image: "▣",
+  media: "▶",
+  pdf: "▤",
+  html: "◇",
+  text: "≡",
+  binary: "◆",
+};
+
+/** A note's display label: its title, else the filename without the `.md`. */
+export function fileLabel(note: NoteSummary): string {
+  if (note.title) return note.title;
+  const base = note.path.split("/").pop() ?? note.path;
+  return base.replace(/\.md$/i, "");
+}
+
+/** Fold the flat, path-ordered note + resource lists into one nested folder tree.
+ *  `dirs` is the vault's full folder list (`list_dirs`, a live fs walk) — the
+ *  structure half of the tree, so a folder renders even when it holds no file
+ *  (the fs supports empty folders, so the tree does); a folder that also appears
+ *  as a file's path prefix merges harmlessly. */
+export function buildTree(
+  notes: NoteSummary[],
+  resources: ResourceSummary[],
+  dirs: Iterable<string>,
+): TreeDir {
+  const root: TreeDir = { name: "", path: "", dirs: new Map(), files: [] };
+  const descend = (dirPath: string): TreeDir => {
+    let dir = root;
+    if (!dirPath) return dir;
+    for (const seg of dirPath.split("/")) {
+      const full = dir.path ? `${dir.path}/${seg}` : seg;
+      let child = dir.dirs.get(seg);
+      if (!child) {
+        child = { name: seg, path: full, dirs: new Map(), files: [] };
+        dir.dirs.set(seg, child);
+      }
+      dir = child;
+    }
+    return dir;
+  };
+  const insert = (file: TreeFile) => {
+    const parts = file.path.split("/");
+    descend(parts.slice(0, -1).join("/")).files.push(file);
+  };
+  for (const note of notes) {
+    insert({ kind: "note", path: note.path, label: fileLabel(note), glyph: "" });
+  }
+  for (const r of resources) {
+    insert({
+      kind: "resource",
+      path: r.path,
+      label: r.path.split("/").pop() ?? r.path,
+      glyph: CLASS_GLYPHS[r.class] ?? CLASS_GLYPHS.binary,
+    });
+  }
+  for (const dir of dirs) {
+    descend(dir);
+  }
+  return root;
+}
+
+/** The paint order for one folder's sub-folders: by name. */
+export function sortedSubdirs(dir: TreeDir): TreeDir[] {
+  return [...dir.dirs.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** The paint order for one folder's files: by display label (sub-folders first,
+ *  then files — the caller's concatenation order, mirrored by `visibleRows`). */
+export function sortedFiles(dir: TreeDir): TreeFile[] {
+  return [...dir.files].sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/** One navigable row, in paint order. Rows are identified by `path` alone: the
+ *  filesystem guarantees a folder and a file can never share one. */
+export interface TreeRow {
+  path: string;
+  nodeKind: NodeKind;
+  /** The text the row shows — what first-letter typeahead matches against. */
+  label: string;
+  /** 0 at the vault root; ARIA's `aria-level` is this + 1. */
+  depth: number;
+  /** Folders: expanded right now. Always false for a file. */
+  expanded: boolean;
+  /** Folders: has something under it to step into. Always false for a file. */
+  hasChildren: boolean;
+}
+
+/**
+ * Every row the tree currently paints, in paint order: for each folder — its own
+ * row, then (only when expanded) its children — and then the folder's files. The
+ * inline create/rename inputs are deliberately absent: they are text entry, not
+ * navigable rows, and they own the keyboard while they're open.
+ */
+export function visibleRows(root: TreeDir, expanded: ReadonlySet<string>): TreeRow[] {
+  const rows: TreeRow[] = [];
+  const walk = (dir: TreeDir, depth: number): void => {
+    for (const sub of sortedSubdirs(dir)) {
+      const open = expanded.has(sub.path);
+      rows.push({
+        path: sub.path,
+        nodeKind: "folder",
+        label: sub.name,
+        depth,
+        expanded: open,
+        hasChildren: sub.dirs.size > 0 || sub.files.length > 0,
+      });
+      if (open) walk(sub, depth + 1);
+    }
+    for (const file of sortedFiles(dir)) {
+      rows.push({
+        path: file.path,
+        nodeKind: file.kind,
+        label: file.label,
+        depth,
+        expanded: false,
+        hasChildren: false,
+      });
+    }
+  };
+  walk(root, 0);
+  return rows;
+}
+
+/** Where `path` sits in the visible list, or -1 (gone: collapsed away, deleted, moved). */
+export function rowIndex(rows: readonly TreeRow[], path: string | null): number {
+  if (path === null) return -1;
+  return rows.findIndex((r) => r.path === path);
+}
+
+/**
+ * The one row that carries `tabindex="0"` — the roving tabstop that makes the whole
+ * tree a *single* stop in the Tab order instead of one stop per file (a 1500-note
+ * vault is not a tab sequence). Preference order: the row the keyboard last focused,
+ * else the open document's row, else the first row — so Tab always lands somewhere
+ * meaningful, and lands where you left off.
+ */
+export function rovingPath(
+  rows: readonly TreeRow[],
+  focus: string | null,
+  activePath: string | null,
+): string | null {
+  if (rowIndex(rows, focus) !== -1) return focus;
+  if (rowIndex(rows, activePath) !== -1) return activePath;
+  return rows.length > 0 ? rows[0].path : null;
+}
+
+/**
+ * Where keyboard focus should land once `path` leaves the tree (a delete): the next
+ * visible row *outside* it — a folder takes its whole expanded subtree with it, so the
+ * next row at or above its depth — else the row before it, else nothing. Null when
+ * `path` isn't in the list at all.
+ */
+export function neighborPath(rows: readonly TreeRow[], path: string): string | null {
+  const i = rowIndex(rows, path);
+  if (i === -1) return null;
+  const depth = rows[i].depth;
+  for (let j = i + 1; j < rows.length; j++) {
+    if (rows[j].depth <= depth) return rows[j].path;
+  }
+  return i > 0 ? rows[i - 1].path : null;
+}
+
+/** What one navigation key does: move the focus, or fold the focused folder. */
+export type TreeMove =
+  | { kind: "focus"; path: string }
+  | { kind: "expand"; path: string }
+  | { kind: "collapse"; path: string };
+
+/** The enclosing folder's row path — what ArrowLeft steps out to. */
+export function parentRowPath(rows: readonly TreeRow[], index: number): string | null {
+  const depth = rows[index].depth;
+  for (let i = index - 1; i >= 0; i--) {
+    if (rows[i].depth < depth) return rows[i].path;
+  }
+  return null;
+}
+
+/**
+ * The ARIA tree-pattern move for one key, or null when the key means nothing here
+ * (so the caller leaves the event alone rather than swallowing it):
+ *
+ *   ArrowDown/Up  next / previous **visible** row (never into a collapsed folder)
+ *   Home/End      first / last visible row
+ *   ArrowRight    a collapsed folder expands; an expanded one steps to its first child
+ *   ArrowLeft     an expanded folder collapses; anything else steps out to its parent
+ *
+ * `from` is -1 when nothing is focused yet, which Down/Home resolve to the first row
+ * and Up/End to the last — so the first arrow press always lands.
+ */
+export function arrowMove(rows: readonly TreeRow[], from: number, key: string): TreeMove | null {
+  if (rows.length === 0) return null;
+  const last = rows.length - 1;
+  const at = (i: number): TreeMove => ({ kind: "focus", path: rows[i].path });
+  switch (key) {
+    case "Home":
+      return at(0);
+    case "End":
+      return at(last);
+    case "ArrowDown":
+      if (from < 0) return at(0);
+      return from < last ? at(from + 1) : null;
+    case "ArrowUp":
+      if (from < 0) return at(last);
+      return from > 0 ? at(from - 1) : null;
+    case "ArrowRight": {
+      if (from < 0) return at(0);
+      const row = rows[from];
+      if (row.nodeKind !== "folder") return null;
+      if (!row.expanded) return row.hasChildren ? { kind: "expand", path: row.path } : null;
+      // Expanded: the next row *is* the first child (visibleRows emits it inline).
+      return from < last && rows[from + 1].depth > row.depth ? at(from + 1) : null;
+    }
+    case "ArrowLeft": {
+      if (from < 0) return at(0);
+      const row = rows[from];
+      if (row.nodeKind === "folder" && row.expanded) return { kind: "collapse", path: row.path };
+      const parent = parentRowPath(rows, from);
+      return parent === null ? null : { kind: "focus", path: parent };
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * First-letter typeahead: the next row after `from` whose label starts with `ch`,
+ * wrapping past the end and back around to `from` itself. Null when nothing matches
+ * — the keystroke then falls through to the app's chords untouched.
+ */
+export function typeaheadTarget(
+  rows: readonly TreeRow[],
+  from: number,
+  ch: string,
+): string | null {
+  const needle = ch.toLowerCase();
+  const n = rows.length;
+  if (n === 0 || needle === "") return null;
+  const start = from < 0 ? -1 : from;
+  for (let k = 1; k <= n; k++) {
+    const row = rows[(start + k + n) % n];
+    if (row.label.toLowerCase().startsWith(needle)) return row.path;
+  }
+  return null;
+}
diff --git a/ui/style.css b/ui/style.css
index 8cceb98..07f2815 100644
--- a/ui/style.css
+++ b/ui/style.css
@@ -127,6 +127,28 @@ body {
   height: 100vh;
 }
 
+/* --- focus (invariant K1) ------------------------------------------------------
+   "Focus is always visible" is half of "fully operable from the keyboard": a control
+   you can reach but can't see you've reached is not reachable. One ring, everywhere,
+   so the whole app reads the same way under the keyboard — a 2px accent outline with
+   an offset so it clears the control rather than hugging its border.
+
+   `:focus-visible`, not `:focus`: the ring appears for keyboard focus and stays out of
+   the way of a mouse click, which is the browser heuristic doing exactly what we want.
+   Individual controls override this where their own affordance IS the ring (the pane
+   gutters' accent line) — never to remove it. */
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+/* The panes are script-focus targets for ⌘1/⌘2/⌘3, not tab stops — the ring would be a
+   window-sized box around a whole column. Their contents ring normally. */
+#tree-pane:focus,
+#note-pane:focus,
+#side-pane:focus {
+  outline: none;
+}
+
 /* --- top bar ------------------------------------------------------------------ */
 
 .topbar {
@@ -653,6 +675,15 @@ body.is-resizing {
 .tree-row:hover {
   background: var(--surface-2);
 }
+/* The keyboard's row (K1). The tree is one Tab stop with a roving tabindex, so this
+   ring is the *only* thing telling an arrow-key user where they are — it has to read
+   as clearly as the mouse's hover wash, hence the wash underneath it too. Inset, since
+   a row spans the pane's full width and an outset ring would clip on both edges. */
+.tree-row:focus-visible {
+  outline: none;
+  background: var(--surface-2);
+  box-shadow: inset 0 0 0 2px var(--accent);
+}
 
 .tree-caret {
   flex: 0 0 auto;
@@ -1685,7 +1716,10 @@ body.is-loading {
   padding: 4px;
 }
 .context-item {
-  display: block;
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 18px;
   width: 100%;
   text-align: left;
   background: none;
@@ -1697,15 +1731,37 @@ body.is-loading {
   padding: 7px 10px;
   cursor: pointer;
 }
-.context-item:hover {
+/* Arrow-keying a menu highlights exactly as hovering it does — the menu shouldn't
+   look like a different control depending on which hand opened it. */
+.context-item:hover,
+.context-item:focus-visible,
+.context-item:focus {
+  outline: none;
   background: var(--accent);
   color: #fff;
 }
+/* The direct chord beside an item — a menu is where a keyboard user *learns* the
+   shortcut that lets them skip the menu next time (K1). Quiet: it's a footnote to the
+   label, not a second label. */
+.context-chord {
+  flex: 0 0 auto;
+  font-size: 11px;
+  color: var(--muted);
+  opacity: 0.85;
+}
+.context-item:hover .context-chord,
+.context-item:focus-visible .context-chord,
+.context-item:focus .context-chord {
+  color: #fff;
+  opacity: 0.75;
+}
 /* A destructive menu item (Delete) reads as such before it's hovered. */
 .context-item.is-danger {
   color: var(--danger);
 }
-.context-item.is-danger:hover {
+.context-item.is-danger:hover,
+.context-item.is-danger:focus-visible,
+.context-item.is-danger:focus {
   background: var(--danger);
   color: #fff;
 }
@@ -1845,11 +1901,82 @@ body.is-loading {
 
 .modal-actions {
   display: flex;
+  align-items: center;
   justify-content: flex-end;
   gap: 10px;
   margin-top: 4px;
 }
 
+/* The ⏎/⎋ line in a modal's action row (K1): a dialog that only tells you about its
+   buttons is a dialog you have to reach for the mouse to be sure of. `margin-right:
+   auto` pushes it left so it reads as a caption, not a third button. */
+.modal-hint {
+  margin-right: auto;
+  font-size: 11.5px;
+  color: var(--muted);
+}
+/* Settings' link to the keyboard sheet sits left of Done: it's a way *out* to another
+   surface, not one of the dialog's own confirm/cancel pair. */
+.modal-actions [data-shortcuts-open] {
+  margin-right: auto;
+}
+
+/* --- the keyboard sheet (?) -----------------------------------------------------
+   The discoverable half of K1: every chord in one place. Wider than a normal modal
+   and columned, so the whole reference is one screen rather than a scroll. */
+.modal-wide {
+  max-width: 720px;
+  max-height: calc(100vh - 96px);
+  overflow-y: auto;
+}
+/* CSS multi-column, not a grid: the groups are wildly different lengths, and a grid
+   would leave a short column stranded beside a long one (rows align, so every group
+   pays for the tallest in its row). Columns flow, so the page packs. */
+.keys-grid {
+  columns: 2;
+  column-gap: 34px;
+  margin: 14px 0 18px;
+}
+.keys-group {
+  break-inside: avoid;
+}
+.keys-group h4 {
+  margin: 10px 0 6px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+/* Chord column fixed, description flowing — the chords line up down the page, which is
+   what makes the sheet scannable rather than a wall of pairs. */
+.keys-list {
+  display: grid;
+  grid-template-columns: minmax(72px, max-content) 1fr;
+  align-items: baseline;
+  gap: 3px 12px;
+  margin: 0;
+}
+.keys-list dt {
+  margin: 0;
+}
+.keys-list dd {
+  margin: 0;
+  font-size: 13px;
+  color: var(--text);
+}
+.keys-list kbd {
+  display: inline-block;
+  font: inherit;
+  font-size: 12px;
+  color: var(--text);
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  padding: 1px 6px;
+  white-space: nowrap;
+}
+
 /* --- Move… modal ---------------------------------------------------------------
    The destination-folder list: one row per folder, click to move. Scrolls past
    ~10 rows so a deep vault never grows the dialog off-screen. */
@@ -2185,10 +2312,24 @@ button.move-dest:hover {
     stroke 120ms ease,
     stroke-width 120ms ease;
 }
-.gnode:hover .gshape {
+/* Keyboard focus lights a node exactly as hovering it does (K1): graph nodes are ⇥
+   stops now, and a focused node has to be as obvious as a hovered one. The extra
+   outline ring on top is what distinguishes "the keyboard is here" from "the pointer
+   is passing over" — the default UA outline can't do this job on an SVG <g>, which is
+   why it's drawn on the shape. */
+.gnode:hover .gshape,
+.gnode:focus-visible .gshape {
   stroke: var(--accent);
   stroke-width: 2.2;
 }
+.gnode:focus {
+  outline: none;
+}
+.gnode:focus-visible .gshape {
+  outline: 2px solid var(--accent);
+  outline-offset: 3px;
+  border-radius: 50%;
+}
 
 .gnode.is-anchor .gshape {
   fill: var(--accent-soft);
@@ -2210,7 +2351,8 @@ button.move-dest:hover {
   stroke: var(--cat-latent);
   stroke-dasharray: 5 5;
 }
-.gnode.is-ghost:hover .gshape {
+.gnode.is-ghost:hover .gshape,
+.gnode.is-ghost:focus-visible .gshape {
   stroke: var(--cat-latent);
   stroke-width: 2.4;
 }
@@ -2258,11 +2400,16 @@ button.move-dest:hover {
   stroke-linejoin: round;
 }
 
-/* Hovering one node spotlights it and its edges; the rest of the scene steps back
-   (the anchor stays — it is the frame of reference). */
+/* Hovering — or ⇥-ing to — one node spotlights it and its edges; the rest of the scene
+   steps back (the anchor stays — it is the frame of reference). Two rules rather than
+   one selector list: `:has()` can't be folded here without the dim also applying to the
+   focused node itself. */
 .graph-svg:has(.gnode:hover) .gnode:not(:hover):not(.is-anchor) {
   opacity: 0.4;
 }
+.graph-svg:has(.gnode:focus-visible) .gnode:not(:focus-visible):not(.is-anchor) {
+  opacity: 0.4;
+}
 
 /* --- entrance: a quick staggered pop, honest about reduced motion --------------- */
 

From 8995dad0f4556144609fcef0d478858409bb87b1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 25 Jul 2026 23:28:50 +0000
Subject: [PATCH 2/2] ui: fix overlay focus return, the Tab trap's gap, and
 tree ARIA (PR #89 review)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three findings from review, all valid. The first turned out to be a
deeper bug than reported.

**Overlay focus return.** Closing the `?` sheet over Settings was
supposed to land on the "Keyboard shortcuts" button that opened it, and
didn't. The reported cause — `overlayReturn` captured only on the
null→overlay edge — was real but not the whole story: `captureReturnFocus`
read `document.activeElement` from inside `syncOverlayFocus`, which runs
at the *end* of `render()`, by which point `render()` has already swapped
`#modal-root`/`#menu-root` wholesale. The element that held focus is
destroyed and `activeElement` has fallen back to `<body>`, so the capture
returned null for *every* trigger living inside an overlay. Tree rows
looked fine only because `paintTree` self-heals by path independently.

So: track `lastFocused` continuously from a `focusin` listener (destroying
a focused node fires no `focusin`, so the last value is still the
trigger), and give the Settings button an id, since a thunk can only
re-find a control across the repaint by id. Focus bookkeeping also splits
into the two layers it always was — the sheet *stacks* over Settings while
everything else is mutually exclusive, so the sheet gets its own return
target while the base layer keeps capturing at the start of a chain (menu
→ Move… → close still lands on the tree row).

**Tab trap.** With no focusable controls the handler returned without
`preventDefault()`, letting Tab walk the page behind the backdrop —
precisely the failure the block exists to prevent. Swallowed
unconditionally now.

**Tree ARIA.** The inline create/rename rows are plain `<div>`s directly
inside the `role="tree"` container, so the tree owned a child of no known
role — while a screen-reader user is naming a note. `role="none"` on the
wrapper; the input keeps its own label.

Also guards `?` behind an open context menu, an edge the layering made
visible: a menu is transient and owns the keyboard like any other overlay.

Verified in Chromium: both sheet-from-Settings paths (mouse and keyboard)
now restore to the trigger, and the existing 32 keyboard paths still pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BF2Fx3uMZjJ18oHCp5mebY
---
 crates/b2-desktop/CLAUDE.md |  15 ++--
 ui/src/main.ts              | 144 +++++++++++++++++++++++++++---------
 ui/src/render.ts            |  22 ++++--
 3 files changed, 137 insertions(+), 44 deletions(-)

diff --git a/crates/b2-desktop/CLAUDE.md b/crates/b2-desktop/CLAUDE.md
index 8cc51ef..35fefba 100644
--- a/crates/b2-desktop/CLAUDE.md
+++ b/crates/b2-desktop/CLAUDE.md
@@ -137,11 +137,16 @@ Every new surface owes all four. They are cheap while you're building it and exp
 
 ### Two things that bite
 
-- **A repaint destroys focus.** `innerHTML` swaps are how this UI renders, so anything holding focus
-  is gone after one — and the keyboard user is silently ejected to `<body>` by an unrelated toast or
-  watcher pulse. Restore by *identity that outlives the swap*, never by element: `paintTree` re-focuses
-  the tree's row **by path**, and `captureReturnFocus` returns a thunk (path → id → element) rather
-  than an element reference.
+- **A repaint destroys focus — and it has already happened by the time you look.** `innerHTML` swaps
+  are how this UI renders, so anything holding focus is gone after one, and the keyboard user is
+  silently ejected to `<body>` by an unrelated toast or watcher pulse. Two consequences, and the
+  second is the one that bites: (a) restore by *identity that outlives the swap*, never by element —
+  `paintTree` re-focuses the tree's row **by path**, and `captureReturnFocus` returns a thunk
+  (path → id → element); (b) you cannot read `document.activeElement` at the end of `render()` to
+  learn what triggered an overlay, because `render()` swapped `#modal-root`/`#menu-root` on the way
+  there and the answer is already `<body>`. Hence `lastFocused`, tracked continuously from `focusin`
+  — destroying a focused node fires no `focusin`, so the last value is still the trigger. Any control
+  that has to be *returned to* therefore needs a stable `id` (`#settings-shortcuts` is one).
 - **WebKit doesn't focus a button on click.** So a `focusin` listener alone won't see a mouse user's
   selection, and the keyboard's idea of "where I am" would drift from the mouse's. The tree's click
   delegation sets `state.treeFocus` explicitly for this reason.
diff --git a/ui/src/main.ts b/ui/src/main.ts
index fcbdead..73d310f 100644
--- a/ui/src/main.ts
+++ b/ui/src/main.ts
@@ -544,9 +544,24 @@ function focusSidePane(): void {
 
 type OverlayKind = "shortcuts" | "settings" | "move" | "delete" | "link" | "menu" | null;
 
-/** Which overlay is up, in the same precedence `modalHtml` renders them. */
+/**
+ * Which overlay is up, in the same precedence `modalHtml` renders them — the guard
+ * every global chord asks before acting.
+ *
+ * Focus, though, treats this as **two layers**, because the `?` sheet is the one
+ * overlay that *stacks*: it renders over Settings (a button there is one of its two
+ * entry points) while Settings stays open underneath, so closing it must return to
+ * that button. Every other overlay is exclusive — a menu that hands off to Move… is
+ * *replaced*, not covered, so the modal returns to whatever opened the menu, never to
+ * a menu item that no longer exists. `baseOverlay` is this minus the sheet.
+ */
 function currentOverlay(): OverlayKind {
   if (state.shortcutsOpen) return "shortcuts";
+  return baseOverlay();
+}
+
+/** The exclusive overlay layer: at most one of these is ever up. */
+function baseOverlay(): OverlayKind {
   if (state.settingsOpen) return "settings";
   if (state.moveTarget) return "move";
   if (state.deleteTarget) return "delete";
@@ -568,19 +583,33 @@ function overlayFocusables(): HTMLElement[] {
   return menu ? [...menu.querySelectorAll<HTMLElement>(".context-item")] : [];
 }
 
+/**
+ * The last element that actually received focus.
+ *
+ * Tracked continuously rather than read on demand, because by the time an overlay's
+ * open edge is handled — at the end of `render()` — the DOM that held focus is already
+ * gone: `render()` swaps `#modal-root`/`#menu-root` wholesale, so `document.activeElement`
+ * has fallen back to `<body>` and the trigger is unrecoverable. `focusin` fires long
+ * before that, and *destroying* a focused node fires no `focusin` (only blur), so this
+ * still names the trigger at the moment we come to remember it. Set in `wireEvents`.
+ */
+let lastFocused: HTMLElement | SVGElement | null = null;
+
 /**
  * A thunk that puts focus back where it was before an overlay opened. A *thunk*, not
  * the element, because the element usually doesn't survive: opening a menu repaints
- * the tree, which swaps the row that triggered it. Restore by identity that outlives a
- * repaint — a tree row by its path (falling back to the roving row when the path is
- * gone, e.g. it was just deleted), anything else by its element id, and only then by
- * the element itself.
+ * the tree, which swaps the row that triggered it, and opening the `?` sheet swaps the
+ * Settings button that opened it. Restore by identity that outlives a repaint — a tree
+ * row by its path (falling back to the roving row when the path is gone, e.g. it was
+ * just deleted), anything else by its element id, and only then by the element itself.
  */
 function captureReturnFocus(): (() => void) | null {
-  const active = document.activeElement;
-  if (!(active instanceof HTMLElement) && !(active instanceof SVGElement)) return null;
-  if (active === document.body) return null;
-  const row = active.closest<HTMLElement>("#tree-pane .tree-row[data-tree-row]");
+  const active = lastFocused;
+  if (active === null || active === document.body) return null;
+  // Unscoped on purpose: `active` is usually *detached* by now, so an ancestor-matching
+  // selector (`#tree-pane .tree-row`) would find nothing. `data-tree-row` is emitted by
+  // the tree and nowhere else, so it identifies a row on its own.
+  const row = active.closest<HTMLElement>(".tree-row[data-tree-row]");
   if (row) {
     const path = row.dataset.treeRow ?? null;
     return () => (treeRowEl(path) ?? rovingRowEl())?.focus();
@@ -594,33 +623,64 @@ function captureReturnFocus(): (() => void) | null {
   };
 }
 
-let overlayShowing: OverlayKind = null;
-let overlayReturn: (() => void) | null = null;
+// One return target per layer (see `currentOverlay`). The base layer's is captured
+// when the *chain* starts, so menu → Move… → close lands back on the tree row; the
+// sheet's is captured every time it opens, since what it covers is still on screen.
+let baseShowing: OverlayKind = null;
+let baseReturn: (() => void) | null = null;
+let sheetShowing = false;
+let sheetReturn: (() => void) | null = null;
 
-/** Called at the end of every `render()`: acts only on the open/close edge. */
-function syncOverlayFocus(): void {
-  const now = currentOverlay();
-  if (now === overlayShowing) return;
-  // The *first* overlay of a chain remembers where the keyboard was; a menu that hands
-  // off to a modal (Move… / Delete) keeps that original target, so closing the modal
-  // returns to the tree row, not to a menu item that no longer exists.
-  if (overlayShowing === null) overlayReturn = captureReturnFocus();
-  overlayShowing = now;
-  if (now === null) {
-    const back = overlayReturn;
-    overlayReturn = null;
-    // …unless an inline tree input just took the keyboard: Rename and New note are
-    // reached *through* the menu, so the menu closing must not yank focus back out
-    // of the input it just opened.
-    if (state.treeCreate || state.treeRename) return;
-    back?.();
-    return;
-  }
+/** Move focus into the overlay that just opened. */
+function focusIntoOverlay(kind: OverlayKind): void {
   // The link modal opens on its explanation field — the one thing you came here to type.
-  const preferred = now === "link" ? document.getElementById("link-explanation") : null;
+  const preferred = kind === "link" ? document.getElementById("link-explanation") : null;
   (preferred ?? overlayFocusables()[0])?.focus();
 }
 
+/**
+ * Called at the end of every `render()`: acts only on open/close *edges*, never on a
+ * plain repaint — otherwise a toast timer would yank focus back to an overlay's first
+ * control while the user is mid-Tab.
+ */
+function syncOverlayFocus(): void {
+  const base = baseOverlay();
+  const sheet = state.shortcutsOpen;
+
+  if (base !== baseShowing) {
+    if (baseShowing === null) baseReturn = captureReturnFocus();
+    baseShowing = base;
+    if (base === null) {
+      const back = baseReturn;
+      baseReturn = null;
+      // Don't restore if the sheet is covering us (it owns focus and will restore on
+      // its own close), and not when an inline tree input just took the keyboard:
+      // Rename and New note are reached *through* the menu, so the menu closing must
+      // not yank focus back out of the input it just opened.
+      if (!sheet && !state.treeCreate && !state.treeRename) back?.();
+    } else if (!sheet) {
+      focusIntoOverlay(base);
+    }
+  }
+
+  // The sheet last, so it wins focus whenever it's up — it is the topmost layer.
+  if (sheet !== sheetShowing) {
+    sheetShowing = sheet;
+    if (sheet) {
+      sheetReturn = captureReturnFocus();
+      focusIntoOverlay("shortcuts");
+    } else {
+      const back = sheetReturn;
+      sheetReturn = null;
+      // No captured target means the sheet was opened by mouse (WebKit doesn't focus a
+      // button on click, so there was nothing focused to remember). Don't strand focus
+      // on <body> when the sheet was covering something — hand it to what's underneath.
+      if (back) back();
+      else if (base !== null) focusIntoOverlay(base);
+    }
+  }
+}
+
 // Paint just the Back/Forward buttons' enabled state — never a pane rebuild. Disabled
 // at the stack's ends, and mid-op like the vault switcher (navGo also guards, for the
 // keyboard/mouse paths that don't go through a disabled button).
@@ -2720,6 +2780,17 @@ function buildShell(): void {
 }
 
 function wireEvents(): void {
+  // Remember where the keyboard is, continuously (K1). `syncOverlayFocus` needs the
+  // element that *triggered* an overlay, and by the time it runs that element has been
+  // swapped out of the DOM — see `lastFocused`. Capture-phase isn't needed (`focusin`
+  // bubbles); `<body>` is skipped so a destroyed control doesn't read as a real target.
+  document.addEventListener("focusin", (e) => {
+    const t = e.target;
+    if ((t instanceof HTMLElement || t instanceof SVGElement) && t !== document.body) {
+      lastFocused = t;
+    }
+  });
+
   // Typing in the frontmatter mini-editor clears its inline error — the message
   // belonged to the save attempt that failed. Delegated (like the clicks below)
   // because the textarea renders dynamically.
@@ -3191,9 +3262,12 @@ function wireEvents(): void {
     // modal — focus vanishes under the backdrop and the overlay becomes dismissible
     // only with the mouse. Wrapping keeps every control in it reachable, forever.
     if (e.key === "Tab" && currentOverlay() !== null) {
+      // Swallowed unconditionally — an overlay that somehow renders with no focusable
+      // control must still not let Tab walk the page behind it, which is the exact
+      // failure this block exists to prevent.
+      e.preventDefault();
       const items = overlayFocusables();
       if (items.length > 0) {
-        e.preventDefault();
         const i = items.indexOf(document.activeElement as HTMLElement);
         const step = e.shiftKey ? -1 : 1;
         const next =
@@ -3293,9 +3367,11 @@ function wireEvents(): void {
       return;
     }
     // ? — the keyboard reference. Bare `?` (⇧/ on a US layout), so it can't collide
-    // with typing: any text surface is excluded, editing included.
+    // with typing: any text surface is excluded, editing included. A context menu owns
+    // the keyboard like any other overlay (Escape first); the sheet is allowed over a
+    // *modal* because Settings is one of its two entry points.
     if (e.key === "?" && !e.metaKey && !e.ctrlKey && !e.altKey) {
-      if (state.editing || inTextEntry()) return;
+      if (state.editing || inTextEntry() || state.contextMenu) return;
       e.preventDefault();
       if (state.shortcutsOpen) closeShortcuts();
       else openShortcuts();
diff --git a/ui/src/render.ts b/ui/src/render.ts
index 43149ef..b873d47 100644
--- a/ui/src/render.ts
+++ b/ui/src/render.ts
@@ -97,9 +97,14 @@ export function renderMarkdown(md: string): string {
 /** The inline name input for a pending create (new note / new folder), rendered at
  *  the top of its target folder's children. The typed value lives only in the DOM —
  *  main.ts commits on Enter/blur, cancels on Escape, and carries it across an
- *  unrelated tree repaint. */
+ *  unrelated tree repaint.
+ *
+ *  `role="none"` because this row sits inside the `role="tree"` container but is *not*
+ *  a `treeitem` — it's a text field. Without it the tree owns a child of no known
+ *  role, and it does so exactly while a screen-reader user is naming a note. The role
+ *  is not inherited by the focusable input inside, which keeps its own `aria-label`. */
 function treeCreateRowHtml(kind: "note" | "folder", pad: string): string {
-  return `<div class="tree-row tree-create" style="${pad}">
+  return `<div class="tree-row tree-create" role="none" style="${pad}">
       <span class="tree-caret">${kind === "folder" ? "▶" : ""}</span>
       <input id="tree-create-input" class="tree-create-input" type="text"
         placeholder="${kind === "note" ? "New note…" : "New folder…"}"
@@ -111,9 +116,10 @@ function treeCreateRowHtml(kind: "note" | "folder", pad: string): string {
 /** The inline rename input, rendered in place of the row being renamed — the
  *  rename sibling of `treeCreateRowHtml` (same commit/cancel wiring in main.ts,
  *  same value-carrying across repaints in paintTree). `glyph` keeps the row's
- *  own marker so the input reads as "this row, editable". */
+ *  own marker so the input reads as "this row, editable". `role="none"` for the same
+ *  reason as the create row above: a text field is not a `treeitem`. */
 function treeRenameRowHtml(prefill: string, glyph: string, pad: string): string {
-  return `<div class="tree-row tree-create" style="${pad}">
+  return `<div class="tree-row tree-create" role="none" style="${pad}">
       <span class="tree-caret">${glyph}</span>
       <input id="tree-rename-input" class="tree-create-input" type="text"
         value="${escapeHtml(prefill)}"
@@ -1000,6 +1006,11 @@ function embedStatsHtml(state: AppState): string {
 // holds the embedding model picker + the per-model embedding-time ledger; built to hold
 // more settings later. Mutually exclusive with the link modal in practice, so it takes
 // precedence in `modalHtml`.
+//
+// `#settings-shortcuts` (the link out to the `?` sheet) carries a *load-bearing* id:
+// the sheet renders over this modal, and closing it restores focus to that button —
+// which main.ts's `captureReturnFocus` can only re-find across the modal-root repaint
+// by id, since the element it was focused on is long gone by then.
 function settingsModalHtml(state: AppState): string {
   const models = state.models;
   const current = models.find((m) => m.current) ?? models[0];
@@ -1076,7 +1087,8 @@ function settingsModalHtml(state: AppState): string {
             : ""
         }
         <div class="modal-actions">
-          <button class="btn ghost" data-shortcuts-open title="Every chord B2 answers to — ?">Keyboard shortcuts</button>
+          <button class="btn ghost" id="settings-shortcuts" data-shortcuts-open
+                  title="Every chord B2 answers to — ?">Keyboard shortcuts</button>
           <button class="btn primary" data-settings-close>Done</button>
         </div>
       </div>