diff --git a/README.md b/README.md
index e2fc108..0c719d0 100644
--- a/README.md
+++ b/README.md
@@ -292,7 +292,7 @@ Open `http://<desktop-lan-ip>:8765` on the phone, for example `http://192.168.30
 The client can be viewed and design-iterated without a running daemon:
 
 - **Demo mode** — append `?demo=<name>` to the client URL (`firefox`, `default`, or `showcase`) to render a fixture layout with the WebSocket disabled. The `showcase` fixture exercises every icon path (Lucide glyphs, Simple Icons brand logos, per-button colour, a no-icon button, and the unknown-icon placeholder). Dev-only; adds no cost when the param is absent. (For forcing a *real* daemon layout with a live backend, use the per-client `?layout=<name>` pin — see [Layout override](#dev-ux-auto-ignore--layout-override).)
-- **Responsive gallery** — `cd client && npm run dev`, then open `/gallery.html`. Renders the real client in phone / large-phone / 7" / 10"-tablet iframes at once, with layout and orientation selectors — for checking how a layout reads across screen sizes. Dev-only entry, not in the production build.
+- **Responsive gallery** — `cd client && npm run dev`, then open `/gallery.html`. Renders the real client in phone / large-phone / 7" / 10"-tablet iframes at once, with layout, orientation, and **key hints** selectors — for checking how a layout reads across screen sizes (the key-hints toggle drives each frame's `?showKeyHints=1`). Dev-only entry, not in the production build.
 - **Ladle** (component workbench) — `cd client && npm run ladle`. Browse `ButtonGrid` / `Icon` / `JogStrip` stories in isolation with width/theme controls, plus `Surface → Device sizes` stories that render the grid in fixed phone/tablet frames (size + orientation) for a quick per-component resolution check. Stories live in `src/*.stories.tsx` (Storybook-compatible CSF).
 - **Lint** — `cd client && npm run lint` (ESLint flat config; `npm run build` still runs `tsc --noEmit`).
 
@@ -423,6 +423,7 @@ Tap the `settings` button in the bottom chrome for a control panel:
 - **Text size** (slider, float 0.5×–1.5×, default 1.0×) — multiplier for the button label (the caption under each icon), applied on top of Content size, so the text can be dialled down without shrinking the icon.
 - **Bottom bar** (slider, 40%–100%, default 100%) — size of the persistent bottom chrome bar (app badge, connection indicator, trackpad + settings buttons), so you can shrink it down on devices where it reads as too tall.
 - **Keep screen awake** (toggle, default on) — holds a Screen Wake Lock while the socket is open and the tab is visible, so a phone acting as the surface doesn't sleep mid-use. Released on tab hidden / socket disconnect; re-acquired on visible / reconnect. Unsupported browsers or denied permissions are logged and swallowed.
+- **Show key hints** (toggle, default off) — renders the key combo a button sends (its `action.key`, or the first `key` step of a macro) as a small dimmed caption under the label, e.g. `Ctrl+A`. Buttons whose action isn't a key combo (shell, url, dbus, …) show no hint.
 
 Values persist per-device to `localStorage` — closing and reopening the client keeps your tuning. The persistent right-side jogstrip stays live inside the settings view so you can feel scale/invert changes immediately.
 
@@ -437,6 +438,7 @@ http://<host>:5173/?labelScale=0.7
 http://<host>:5173/?jogWidth=0.6
 http://<host>:5173/?bottomScale=0.7
 http://<host>:5173/?wakeLock=0
+http://<host>:5173/?showKeyHints=1
 ```
 
 Daemon-side flick momentum can be tuned with CLI flags:
diff --git a/client/src/App.tsx b/client/src/App.tsx
index 21be492..e45841a 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -19,6 +19,7 @@ import {
   useLargerControls,
   useHighContrast,
   useReduceMotion,
+  useShowKeyHints,
   useScrollSettings,
   useTrackpadSettings,
   useWakeLockSetting,
@@ -143,6 +144,7 @@ export function App() {
   const largerControls = useLargerControls();
   const highContrast = useHighContrast();
   const reduceMotion = useReduceMotion();
+  const showKeyHints = useShowKeyHints();
   // Hold the wake lock while the user wants it AND the socket is live;
   // a stale surface with no daemon behind it has no reason to keep the
   // screen on. Visibility is handled inside the hook.
@@ -468,6 +470,8 @@ export function App() {
               onHighContrastChange={highContrast.setEnabled}
               reduceMotion={reduceMotion.enabled}
               onReduceMotionChange={reduceMotion.setEnabled}
+              showKeyHints={showKeyHints.enabled}
+              onShowKeyHintsChange={showKeyHints.setEnabled}
             />
           ) : layout?.error ? (
             <div className="layout-error" role="alert">
@@ -486,6 +490,7 @@ export function App() {
               mediaStates={media.states}
               onMediaCommand={mediaCommand}
               labelScale={labelScale.scale}
+              showKeyHints={showKeyHints.enabled}
             />
           ) : (
             <div className="empty">waiting for daemon…</div>
diff --git a/client/src/ButtonGrid.stories.tsx b/client/src/ButtonGrid.stories.tsx
index dd3e0e4..a009ae9 100644
--- a/client/src/ButtonGrid.stories.tsx
+++ b/client/src/ButtonGrid.stories.tsx
@@ -36,7 +36,8 @@ const contentScaleControl = {
 function Frame({
   name,
   contentScale,
-}: { name: keyof typeof DEMO_LAYOUTS } & ContentScaleArgs) {
+  showKeyHints,
+}: { name: keyof typeof DEMO_LAYOUTS; showKeyHints?: boolean } & ContentScaleArgs) {
   return (
     <div
       style={
@@ -51,6 +52,7 @@ function Frame({
         scrollScale={3}
         scrollInvert={false}
         onMediaCommand={noop}
+        showKeyHints={showKeyHints}
       />
     </div>
   );
@@ -76,3 +78,12 @@ export const Showcase: Story<ContentScaleArgs> = ({ contentScale }) => (
 );
 Showcase.args = contentScaleControl.args;
 Showcase.argTypes = contentScaleControl.argTypes;
+
+/** Key hints on: each button whose action is a key combo shows it as a small
+ * dimmed caption under the label (Firefox's combos map to real shortcuts).
+ * Buttons without a key action (e.g. showcase launchers) render no hint. */
+export const KeyHints: Story<ContentScaleArgs> = ({ contentScale }) => (
+  <Frame name="firefox" contentScale={contentScale} showKeyHints />
+);
+KeyHints.args = contentScaleControl.args;
+KeyHints.argTypes = contentScaleControl.argTypes;
diff --git a/client/src/ButtonGrid.tsx b/client/src/ButtonGrid.tsx
index e02ad70..4b3be00 100644
--- a/client/src/ButtonGrid.tsx
+++ b/client/src/ButtonGrid.tsx
@@ -32,10 +32,34 @@ type Props = {
   /** Multiplier for the meter widget's caption label so it scales with
    * the same user-facing "label size" preference as buttons. */
   labelScale?: number;
+  /** When true, buttons whose action is a key combo show that combo as a
+   * small caption under the label (e.g. ``Ctrl+A``). */
+  showKeyHints?: boolean;
 };
 
 const FALLBACK_DIM = 4;
 
+/** Title-case each token of a key combo so ``ctrl+a`` reads as ``Ctrl+A``.
+ * Purely presentational — the daemon-side combo string is untouched. */
+function prettifyCombo(combo: string): string {
+  return combo
+    .split("+")
+    .map((part) => (part.length <= 1 ? part.toUpperCase() : part[0].toUpperCase() + part.slice(1)))
+    .join("+");
+}
+
+/** The key combo a button sends on press, for the optional key-hint caption.
+ * Reads ``action.key`` (the shortcut form) and, for macros, the first ``key``
+ * step. Returns null for buttons whose action isn't a key combo (shell, url,
+ * dbus, …) so those render without a hint. */
+function keyHint(w: Widget): string | null {
+  const actionKey = w.action?.key;
+  if (typeof actionKey === "string" && actionKey.length > 0) return prettifyCombo(actionKey);
+  const step = w.macro?.steps.find((s) => s.type === "key" && s.value);
+  if (step) return prettifyCombo(step.value);
+  return null;
+}
+
 /** Derive grid dimensions from the layout's widget extents so cells fill the
  * chrome-excluded area rather than leaving empty 1fr rows/columns when a
  * layout doesn't use the full 4x4 space (ADR-0003: the client computes
@@ -65,6 +89,7 @@ export function ButtonGrid({
   labelScale,
   mediaStates,
   onMediaCommand,
+  showKeyHints,
 }: Props) {
   const autoOrientation = useOrientation();
   const orientation = orientationOverride ?? autoOrientation;
@@ -145,6 +170,7 @@ export function ButtonGrid({
           const buttonStyle: CSSProperties = w.color
             ? { ...style, backgroundColor: w.color }
             : style;
+          const hint = showKeyHints ? keyHint(w) : null;
           return (
             <button
               key={w.id}
@@ -164,6 +190,7 @@ export function ButtonGrid({
               ) : !w.icon ? (
                 <span className="label">{w.id}</span>
               ) : null}
+              {hint ? <span className="key-hint">{hint}</span> : null}
             </button>
           );
         }),
diff --git a/client/src/Gallery.tsx b/client/src/Gallery.tsx
index d0a6978..71ea1c4 100644
--- a/client/src/Gallery.tsx
+++ b/client/src/Gallery.tsx
@@ -23,15 +23,26 @@ const MAX_H = 360;
 
 type Orientation = "landscape" | "portrait";
 
-function Frame({ device, demo, orientation }: { device: Device; demo: string; orientation: Orientation }) {
+function Frame({
+  device,
+  demo,
+  orientation,
+  keyHints,
+}: {
+  device: Device;
+  demo: string;
+  orientation: Orientation;
+  keyHints: boolean;
+}) {
   const [w, h] = orientation === "landscape" ? [device.h, device.w] : [device.w, device.h];
   const scale = Math.min(1, MAX_W / w, MAX_H / h);
+  const src = `${import.meta.env.BASE_URL}?demo=${demo}${keyHints ? "&showKeyHints=1" : ""}`;
   return (
     <figure className="frame">
       <div className="frame-box" style={{ width: w * scale, height: h * scale }}>
         <iframe
           title={`${device.label} ${orientation}`}
-          src={`${import.meta.env.BASE_URL}?demo=${demo}`}
+          src={src}
           style={{
             width: w,
             height: h,
@@ -51,6 +62,7 @@ function Frame({ device, demo, orientation }: { device: Device; demo: string; or
 export function Gallery() {
   const [demo, setDemo] = useState(DEMO_NAMES[0] ?? "firefox");
   const [orientation, setOrientation] = useState<Orientation>("landscape");
+  const [keyHints, setKeyHints] = useState(false);
 
   return (
     <div className="gallery">
@@ -78,10 +90,18 @@ export function Gallery() {
             </button>
           ))}
         </div>
+        <div className="gallery-group">
+          <button
+            className={`gallery-btn${keyHints ? " on" : ""}`}
+            onClick={() => setKeyHints((v) => !v)}
+          >
+            key hints
+          </button>
+        </div>
       </header>
       <div className="gallery-grid">
         {DEVICES.map((d) => (
-          <Frame key={d.label} device={d} demo={demo} orientation={orientation} />
+          <Frame key={d.label} device={d} demo={demo} orientation={orientation} keyHints={keyHints} />
         ))}
       </div>
     </div>
diff --git a/client/src/Settings.stories.tsx b/client/src/Settings.stories.tsx
index eec5494..759ea14 100644
--- a/client/src/Settings.stories.tsx
+++ b/client/src/Settings.stories.tsx
@@ -37,6 +37,8 @@ export const Default: Story = () => (
       onHighContrastChange={noop}
       reduceMotion={false}
       onReduceMotionChange={noop}
+      showKeyHints={false}
+      onShowKeyHintsChange={noop}
     />
   </main>
 );
diff --git a/client/src/Settings.test.tsx b/client/src/Settings.test.tsx
index f698da7..d1e7ab3 100644
--- a/client/src/Settings.test.tsx
+++ b/client/src/Settings.test.tsx
@@ -31,6 +31,8 @@ function renderSettings(overrides: Partial<Parameters<typeof Settings>[0]> = {})
     onHighContrastChange: () => {},
     reduceMotion: false,
     onReduceMotionChange: () => {},
+    showKeyHints: false,
+    onShowKeyHintsChange: () => {},
   };
   return render(<Settings {...base} {...overrides} />);
 }
diff --git a/client/src/Settings.tsx b/client/src/Settings.tsx
index c195aff..b694442 100644
--- a/client/src/Settings.tsx
+++ b/client/src/Settings.tsx
@@ -52,6 +52,8 @@ type Props = {
   onHighContrastChange: (v: boolean) => void;
   reduceMotion: boolean;
   onReduceMotionChange: (v: boolean) => void;
+  showKeyHints: boolean;
+  onShowKeyHintsChange: (v: boolean) => void;
 };
 
 type Health = {
@@ -90,6 +92,8 @@ export function Settings({
   onHighContrastChange,
   reduceMotion,
   onReduceMotionChange,
+  showKeyHints,
+  onShowKeyHintsChange,
 }: Props) {
   const orientation = useOrientation();
   const standalone = useStandaloneMode();
@@ -234,6 +238,11 @@ export function Settings({
           value={wakeLockEnabled}
           onChange={onWakeLockChange}
         />
+        <SettingToggle
+          label="Show key hints"
+          value={showKeyHints}
+          onChange={onShowKeyHintsChange}
+        />
       </div>
 
       <h2 className="settings-title settings-title-sub">Accessibility</h2>
diff --git a/client/src/demo.ts b/client/src/demo.ts
index e330f28..e83bfd6 100644
--- a/client/src/demo.ts
+++ b/client/src/demo.ts
@@ -14,14 +14,14 @@ const FIREFOX: ServerLayout = {
   icon: { source: "simple-icons", name: "firefox" },
   jogstrip_enabled: true,
   widgets: [
-    { id: "new-tab", kind: "button", label: "New tab", icon: { source: "lucide", name: "plus" }, grid: [0, 0, 1, 1] },
-    { id: "new-window", kind: "button", label: "New window", icon: { source: "lucide", name: "app-window" }, grid: [1, 0, 1, 1] },
-    { id: "back", kind: "button", label: "Back", icon: { source: "lucide", name: "arrow-left" }, color: "#1e3a8a", grid: [2, 0, 1, 1] },
-    { id: "forward", kind: "button", label: "Forward", icon: { source: "lucide", name: "arrow-right" }, color: "#1e3a8a", grid: [3, 0, 1, 1] },
-    { id: "reload", kind: "button", label: "Reload", icon: { source: "lucide", name: "refresh-cw" }, grid: [0, 1, 1, 1] },
-    { id: "focus-url", kind: "button", label: "URL bar", icon: { source: "lucide", name: "link" }, grid: [1, 1, 1, 1] },
-    { id: "find", kind: "button", label: "Find", icon: { source: "lucide", name: "search" }, grid: [2, 1, 1, 1] },
-    { id: "close-tab", kind: "button", label: "Close tab", icon: { source: "lucide", name: "x" }, grid: [3, 1, 1, 1] },
+    { id: "new-tab", kind: "button", label: "New tab", icon: { source: "lucide", name: "plus" }, grid: [0, 0, 1, 1], action: { key: "ctrl+t" } },
+    { id: "new-window", kind: "button", label: "New window", icon: { source: "lucide", name: "app-window" }, grid: [1, 0, 1, 1], action: { key: "ctrl+n" } },
+    { id: "back", kind: "button", label: "Back", icon: { source: "lucide", name: "arrow-left" }, color: "#1e3a8a", grid: [2, 0, 1, 1], action: { key: "alt+left" } },
+    { id: "forward", kind: "button", label: "Forward", icon: { source: "lucide", name: "arrow-right" }, color: "#1e3a8a", grid: [3, 0, 1, 1], action: { key: "alt+right" } },
+    { id: "reload", kind: "button", label: "Reload", icon: { source: "lucide", name: "refresh-cw" }, grid: [0, 1, 1, 1], action: { key: "ctrl+r" } },
+    { id: "focus-url", kind: "button", label: "URL bar", icon: { source: "lucide", name: "link" }, grid: [1, 1, 1, 1], action: { key: "ctrl+l" } },
+    { id: "find", kind: "button", label: "Find", icon: { source: "lucide", name: "search" }, grid: [2, 1, 1, 1], action: { key: "ctrl+f" } },
+    { id: "close-tab", kind: "button", label: "Close tab", icon: { source: "lucide", name: "x" }, grid: [3, 1, 1, 1], action: { key: "ctrl+w" } },
   ],
 };
 
@@ -36,12 +36,12 @@ const YOUTUBE: ServerLayout = {
   web_app: true,
   jogstrip_enabled: true,
   widgets: [
-    { id: "play-pause", kind: "button", label: "Play/Pause", icon: { source: "lucide", name: "play" }, color: "#ff0000", grid: [0, 0, 1, 1] },
-    { id: "mute", kind: "button", label: "Mute", icon: { source: "lucide", name: "volume-x" }, grid: [1, 0, 1, 1] },
-    { id: "fullscreen", kind: "button", label: "Fullscreen", icon: { source: "lucide", name: "maximize" }, grid: [2, 0, 1, 1] },
-    { id: "back-10", kind: "button", label: "-10s", icon: { source: "lucide", name: "rewind" }, grid: [0, 1, 1, 1] },
-    { id: "fwd-10", kind: "button", label: "+10s", icon: { source: "lucide", name: "fast-forward" }, grid: [1, 1, 1, 1] },
-    { id: "captions", kind: "button", label: "Captions", icon: { source: "lucide", name: "captions" }, grid: [2, 1, 1, 1] },
+    { id: "play-pause", kind: "button", label: "Play/Pause", icon: { source: "lucide", name: "play" }, color: "#ff0000", grid: [0, 0, 1, 1], action: { key: "k" } },
+    { id: "mute", kind: "button", label: "Mute", icon: { source: "lucide", name: "volume-x" }, grid: [1, 0, 1, 1], action: { key: "m" } },
+    { id: "fullscreen", kind: "button", label: "Fullscreen", icon: { source: "lucide", name: "maximize" }, grid: [2, 0, 1, 1], action: { key: "f" } },
+    { id: "back-10", kind: "button", label: "-10s", icon: { source: "lucide", name: "rewind" }, grid: [0, 1, 1, 1], action: { key: "j" } },
+    { id: "fwd-10", kind: "button", label: "+10s", icon: { source: "lucide", name: "fast-forward" }, grid: [1, 1, 1, 1], action: { key: "l" } },
+    { id: "captions", kind: "button", label: "Captions", icon: { source: "lucide", name: "captions" }, grid: [2, 1, 1, 1], action: { key: "c" } },
   ],
 };
 
@@ -53,7 +53,7 @@ const DEFAULT: ServerLayout = {
     { id: "open-url", kind: "button", label: "Open example.com", icon: { source: "lucide", name: "globe" }, grid: [0, 0, 1, 1] },
     { id: "audio-toggle", kind: "button", label: "VLC Play/Pause", icon: { source: "lucide", name: "play" }, grid: [1, 0, 1, 1] },
     { id: "xterm", kind: "button", label: "xterm", icon: { source: "lucide", name: "terminal" }, grid: [2, 0, 1, 1] },
-    { id: "send-key", kind: "button", label: "Send Ctrl+T", icon: { source: "lucide", name: "keyboard" }, grid: [3, 0, 1, 1] },
+    { id: "send-key", kind: "button", label: "Send Ctrl+T", icon: { source: "lucide", name: "keyboard" }, grid: [3, 0, 1, 1], action: { key: "ctrl+t" } },
   ],
 };
 
diff --git a/client/src/settings-store.ts b/client/src/settings-store.ts
index 1c9e7e7..8a6b7ce 100644
--- a/client/src/settings-store.ts
+++ b/client/src/settings-store.ts
@@ -23,6 +23,7 @@ const LABEL_SCALE_KEY = "deckd.labelScale";
 const LARGER_CONTROLS_KEY = "deckd.largerControls";
 const HIGH_CONTRAST_KEY = "deckd.highContrast";
 const REDUCE_MOTION_KEY = "deckd.reduceMotion";
+const SHOW_KEY_HINTS_KEY = "deckd.showKeyHints";
 
 const WAKE_LOCK_DEFAULT = true;
 
@@ -379,3 +380,19 @@ export function useReduceMotion() {
 
   return { enabled, setEnabled };
 }
+
+/** Show key hints: renders the key combo a button sends (its ``action.key``)
+ * as a small caption under the label, so the user can see which keyboard
+ * shortcut each button triggers. Persisted per-device; defaults to off. */
+export function useShowKeyHints() {
+  const [enabled, setEnabledState] = useState<boolean>(() =>
+    readInitialBool("showKeyHints", SHOW_KEY_HINTS_KEY, false),
+  );
+
+  const setEnabled = useCallback((v: boolean) => {
+    setEnabledState(v);
+    safeSet(SHOW_KEY_HINTS_KEY, String(v));
+  }, []);
+
+  return { enabled, setEnabled };
+}
diff --git a/client/src/style.css b/client/src/style.css
index 0e85670..ce04d32 100644
--- a/client/src/style.css
+++ b/client/src/style.css
@@ -430,6 +430,19 @@ button:focus-visible {
   word-break: break-word;
 }
 
+.cell-button .key-hint {
+  /* The key combo a button sends, shown under the label when the user
+     enables key hints. Deliberately smaller and dimmer than the label so it
+     reads as secondary metadata; monospace so combos line up legibly.
+     Scales with the same content/label preferences as the label. */
+  font-size: calc(clamp(7px, 1.2vw, 10px) * var(--content-scale) * var(--label-scale, 1));
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-weight: 500;
+  line-height: 1.1;
+  opacity: 0.6;
+  word-break: break-word;
+}
+
 /* Icon glyph (Lucide / Simple Icons), rendered above the label. The glyph is
    an ``<svg class="icon">`` itself, so size it directly — one fixed box for
    every source regardless of the set's intrinsic viewBox, so icons read at a
diff --git a/docs/adr/0010-grid-reflow.md b/docs/adr/0010-grid-reflow.md
new file mode 100644
index 0000000..36a06e7
--- /dev/null
+++ b/docs/adr/0010-grid-reflow.md
@@ -0,0 +1,56 @@
+# Grid layout: ordered-list reflow with a banded cell size
+
+**Supersedes [ADR-0004](0004-orientation-scaling.md).** Tracked in issue #92; not yet implemented at time of writing (the code still stores coordinates and transposes).
+
+ADR-0004 authored layouts as a fixed grid of absolute `[x, y, w, h]` coordinates and handled portrait by transposing them diagonally. That model assumes a grid whose shape is known when the layout is written — the Stream Deck premise, where the hardware *is* the grid. deckd's "deck" is an arbitrary browser viewport: a phone, a tablet, a laptop window being dragged narrower, a super-wide-but-short panel. There is no fixed grid shape to author against, so absolute coordinates are the wrong vocabulary. This ADR replaces them.
+
+## Decisions
+
+### Widgets are an ordered list that reflows; there are no coordinates
+
+A layout's `widgets` are an **ordered list**. The client packs them left-to-right and wraps down, computing the column count from the available width. `grid: [x, y, w, h]` is gone. A widget may carry an optional `size: [w, h]` **span** (default `[1, 1]`) for non-uniform widgets (a wide meter, a trackpad-as-cell); it expresses extent, never position.
+
+Positional muscle memory shifts from *absolute grid coordinate* to *sequence*: the third button is always the third button, wherever it wraps. This is acceptable because a user typically drives one machine from one controller and orders the buttons to taste — the case ADR-0004's per-coordinate stability was protecting is not worth the cost of a fixed grid.
+
+Packing is **strict order**: if a spanned widget doesn't fit at the end of a row, the trailing gap is left and the widget wraps down. No dense back-filling — that would reorder widgets visually and break the sequence the model relies on.
+
+### Portrait falls out of reflow; the transpose is deleted
+
+ADR-0004's diagonal transpose exists only to keep cells roughly square when a landscape-authored grid is shown in portrait. Reflow makes it unnecessary: a narrow (portrait) viewport simply fits fewer columns and wraps into more rows. The `[x,y,w,h] → [y,x,h,w]` transpose and the landscape-authoring convention are both removed. ADR-0004's "future extension" (`portrait:` / `landscape:` blocks) is likewise dropped — reflow covers the common case, and orientation-specific *button sets* are not a goal.
+
+### Cell size is a min/max band, held in client-side device settings
+
+Cells are neither a hard pixel size nor a pair of named modes. They live in a **size band** — as many columns of at least `MIN` (a readability floor) as the width allows, then every cell stretches equally to consume leftover width, capped at `MAX`. Cells stay **aspect-locked** (square) as they flex. Fill is **horizontal only**: the grid is top-aligned and leftover height is breathing room below, by choice, not omission.
+
+The band *is* the sizing behaviour that an earlier draft split into `fill` and `fixed` modes: a wide band with a low floor gives few large cells with everything visible ("fill"); a narrow band around a target gives constant density ("fixed"). No mode property is needed.
+
+Crucially, the band is a **client-side per-device preference ([ADR-0006](0006-widget-visual-styling.md)), not a layout property.** How big a comfortable button is depends on the screen and the hand, not on what the layout means — the same bucket as content scale, scroll scale, and wake lock. It lives in `localStorage`, never reaches the daemon, and every layout reflows to whatever band the user set. Layout YAML therefore carries **no pixel sizes**. The existing content-scale control (#37) should be folded into this single sizing setting so the two don't fight: the band sets cell size, and icon/label scale derives from it.
+
+### Overflow is the one genuinely per-layout knob
+
+When the defined widgets exceed the capacity the band yields at the current viewport, the behaviour is:
+
+- **clip** (default) — trailing widgets are off-surface and currently inaccessible. Ten buttons on a surface that fits eight means the last two cannot be reached. **No pagination in v1** (a candidate follow-on).
+- **shrink-to-fit** — allow cells below `MIN` so every widget fits.
+
+This is layout-semantic rather than device-ergonomic, so it may be a layout property (with a global default). It is the only sizing choice the layout author owns.
+
+### Full-surface widgets opt out of the flow
+
+A widget may declare itself full-surface (`size: full`) — it takes the whole chrome-excluded area and does not participate in packing. This is where the MPRIS `mediabrowser` lands: it is already a full-bleed view under [ADR-0008](0008-chrome-view-carveout.md), not a grid cell. Generalising "full-surface" from the hardcoded view set into a widget property is a follow-on, not required by this ADR.
+
+## Out of scope (deferred, deliberately)
+
+- **More buttons on a bigger screen.** A larger viewport shows the *same* widgets, reflowed — never extra ones. Overflow clips; it does not reveal.
+- **Pagination / scrolling** past the clip boundary. Named as the natural successor to clip mode, not built here.
+- **Cross-device visual consistency within one layout.** Reflow means the wrap point differs by screen; that is intended, given one-controller-per-machine.
+- **Per-device layouts** (a different button set per device). That is issue #38's axis — client identity — and a separate concern. This ADR is resolution/orientation-driven, never device-identity-driven.
+
+## Consequences
+
+- The `Widget` schema loses `grid: [x,y,w,h]` and gains an optional `size` (span or `full`). Both the TypeScript (`client/src/protocol.ts`) and Python protocols change together and must stay in parity (#76). This is a breaking layout-format change; existing `*.yaml` layouts need migration (drop `x,y`, keep `w,h` as `size`).
+- `client/src/orientation.ts`'s transpose logic and its call site in `ButtonGrid.tsx` are removed; `deriveDims` is replaced by width-driven column computation against the band.
+- `.grid` CSS moves from `repeat(N, 1fr)` to `repeat(auto-fill, minmax(MIN, 1fr))` with a `MAX` cap and an aspect-ratio lock (`client/src/style.css`).
+- A new min/max cell-size control joins the settings page (`client/src/settings-store.ts`), subsuming content-scale (#37).
+- **This blocks the layout editor (#82):** the editor becomes drag-to-*reorder* with a span control and an overflow toggle — not drag-to-XY on a fixed canvas — plus a viewport-preview toggle to inspect reflow at different widths. Its "grid arrangement UX" question should not be settled until this model lands.
+- A visual mockup of the reflow behaviour lives at `docs/mockups/grid-reflow.html`.
diff --git a/docs/mockups/grid-reflow.html b/docs/mockups/grid-reflow.html
new file mode 100644
index 0000000..cedc779
--- /dev/null
+++ b/docs/mockups/grid-reflow.html
@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>deckd — reflow mockup (fixed sizing)</title>
+<style>
+  :root {
+    --min: 104px;       /* cell size band: floor for readability… */
+    --max: 168px;       /* …ceiling so cells don't balloon on big screens */
+    --gap: 12px;
+    --bg: #0e1116;
+    --surface: #161b22;
+    --cell-bg: #21262d;
+    --cell-bg2: #2d333b;
+    --accent: #58a6ff;
+    --text: #e6edf3;
+    --muted: #7d8590;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; padding: 32px;
+    background: var(--bg);
+    color: var(--text);
+    font: 14px/1.4 -apple-system, "Segoe UI", Roboto, sans-serif;
+  }
+  h1 { font-size: 20px; margin: 0 0 4px; }
+  .sub { color: var(--muted); margin: 0 0 28px; max-width: 780px; }
+  .row { display: flex; flex-wrap: wrap; gap: 40px; align-items: flex-start; }
+
+  .device { }
+  .device h2 { font-size: 14px; margin: 0 0 2px; }
+  .device .dim { color: var(--muted); font-size: 12px; margin: 0 0 10px; font-variant-numeric: tabular-nums; }
+
+  /* The chrome-excluded surface. overflow:hidden makes off-surface cells vanish
+     (fixed mode, no pagination — the clipping the ticket describes). */
+  .surface {
+    background: var(--surface);
+    border: 1px solid #30363d;
+    border-radius: 14px;
+    padding: var(--gap);
+    overflow: hidden;
+    position: relative;
+  }
+  .grid {
+    display: grid;
+    /* BANDED sizing: as many columns of at least MIN as fit, then all stretch
+       equally (1fr) to consume leftover width — no dead margin. */
+    grid-template-columns: repeat(auto-fill, minmax(var(--min), 1fr));
+    grid-auto-rows: minmax(var(--min), 1fr);
+    gap: var(--gap);
+    justify-content: center;   /* remainder < one column reads as centered padding */
+  }
+  .cell {
+    background: linear-gradient(160deg, var(--cell-bg2), var(--cell-bg));
+    border: 1px solid #30363d;
+    border-radius: 12px;
+    display: flex; flex-direction: column;
+    align-items: center; justify-content: center;
+    gap: 8px;
+    aspect-ratio: 1 / 1;        /* aspect-locked: cells stay square as they flex */
+    max-width: var(--max);      /* growth ceiling; extra becomes centered padding */
+    max-height: var(--max);
+    width: 100%;
+    justify-self: center;
+    user-select: none;
+  }
+  .cell .icon { font-size: 30px; line-height: 1; }
+  .cell .label { font-size: 12px; color: var(--text); font-weight: 600; }
+  .cell .n { position: absolute; }
+  .badge {
+    display: inline-block; margin-top: 10px; font-size: 12px;
+    color: var(--muted);
+  }
+  .badge b { color: var(--accent); }
+  .clip-note { color: #f0883e; }
+</style>
+</head>
+<body>
+  <h1>deckd — reflow preview · banded cell size (104–168px)</h1>
+  <p class="sub">
+    The <b>same 12 buttons</b> in the same order. Cells live in a size <b>band</b>: at least 104px (readability
+    floor), stretching up to 168px to fill leftover width — so there's no dead margin until cells hit the ceiling.
+    Columns are computed from the floor; buttons reflow left-to-right and wrap down, cells stay square.
+    Nothing is repositioned per screen — only the wrap point and cell size change. Where the surface still can't
+    fit all 12, the trailing buttons are off-surface (no pagination yet).
+  </p>
+
+  <div class="row" id="row"></div>
+
+  <script>
+    const BUTTONS = [
+      ["💻","Code"], ["🦊","Firefox"], ["⌨️","Terminal"], ["💬","Slack"],
+      ["🎵","Spotify"], ["🐳","Docker"], ["📁","Files"], ["✉️","Mail"],
+      ["📸","Shot"], ["🔊","Volume"], ["🎙️","Mic"], ["🔒","Lock"],
+    ];
+    const MIN = 104, GAP = 12;   // column count is computed from the MIN of the band
+    // [label, width, height] of the chrome-excluded surface (landscape use).
+    const DEVICES = [
+      ["Phone (landscape)", 560, 288],
+      ["Tablet",            900, 468],
+      ["Laptop (wide-short)", 1180, 360],
+    ];
+
+    const row = document.getElementById("row");
+    for (const [name, w, h] of DEVICES) {
+      const cols = Math.floor((w - GAP) / (MIN + GAP));
+      const rows = Math.floor((h - GAP) / (MIN + GAP));
+      const capacity = cols * rows;
+      const shown = Math.min(BUTTONS.length, capacity);
+      const clipped = BUTTONS.length - shown;
+
+      const dev = document.createElement("div");
+      dev.className = "device";
+      dev.innerHTML = `
+        <h2>${name}</h2>
+        <p class="dim">${w}×${h} surface · ${cols} cols × ${rows} rows = ${capacity} slots</p>
+        <div class="surface" style="width:${w}px;height:${h}px">
+          <div class="grid"></div>
+        </div>
+        <div class="badge">
+          shows <b>${shown}</b> / ${BUTTONS.length} buttons
+          ${clipped ? `· <span class="clip-note">${clipped} off-surface (needs pagination later)</span>` : `· all fit`}
+        </div>`;
+      const grid = dev.querySelector(".grid");
+      BUTTONS.forEach(([icon, label], i) => {
+        const c = document.createElement("div");
+        c.className = "cell";
+        c.innerHTML = `<div class="icon">${icon}</div><div class="label">${label}</div>`;
+        grid.appendChild(c);
+      });
+      row.appendChild(dev);
+    }
+  </script>
+</body>
+</html>
diff --git a/docs/mockups/grid-reflow.png b/docs/mockups/grid-reflow.png
new file mode 100644
index 0000000..ff8181e
Binary files /dev/null and b/docs/mockups/grid-reflow.png differ