lanework/DESIGN/11-command-nexus.md

# Command Nexus

The single source of truth for **every command and action the app can perform** — what exists, the context it applies in, its default binding, and whether it can be customized. Behavior is specified in the home docs (cross-referenced per row); this inventory is normative for *existence, context, and bindings*: a command absent here doesn't exist, and adding one means adding a row here first. 04-interactions.md's contract underwrites the tables — every board function has a menu item, keyboard-reachable and remappable, with a default chord only where one earns its keyspace — the "— (no default)" rows below are deliberate — and configuration as the one carve-out (04 ▸ The map) — and 04 remains normative for the behavior behind the rows.

## Customizability classes

| Class | Meaning | Customization |
|---|---|---|
| **M** | Menu command | Remappable system-natively (System Settings ▸ Keyboard ▸ App Shortcuts — 04 ▸ Configurable bindings). Titles are API. |
| **M−** | Menu command, effectively fixed | Undo/Redo only: NSUndoManager rewrites their titles dynamically, which defeats title-matched remapping (04). |
| **G** | Fixed grammar key | Platform grammar, deliberately not remappable — Finder's own Return/arrows aren't either (04 ▸ Grammar). |
| **P** | Pointer grammar | Clicks, drags, modifiers — not customizable. |
| **C** | Configuration control | Form-like controls (board popover, chooser, welcome); the keyboard path is reachability (Board Info ⌘I + Tab-reachable controls), not bindings — 04's configuration carve-out. |

**Toolbar presence is a separate axis**, orthogonal to the classes: toolbar items mirror menu commands, their presence per window is user-customizable (Customize Toolbar — 03-board-ui.md ▸ Toolbar; defaults and catalogs live there), and a toolbar is never a function's only home. Labels match menu titles except Undo/Redo, whose toolbar labels stay static (03).

## Menu commands (M unless noted)

| Menu | Command | Default | Context |
|---|---|---|---|
| File | New Card | ⌘N | Board window; disabled on a zero-lane board. Target rule: 04 |
| File | New Lane | ⇧⌘N | Board window |
| File | New Board… (opens the template chooser) | ⌥⌘N | Everywhere |
| File | Open… | ⌘O | Everywhere; standard open panel (boards = `.kanban` packages and extension-less board folders — 01) |
| File | Open Recent ▸ (with Clear Menu) | — | Everywhere; reads the board registry (02) |
| File | Board Info (opens the board popover) | ⌘I | Board window |
| File | Duplicate (the board — a Finder-style "copy" sibling, 03 ▸ Welcome; never the selection) | ⇧⌘S | Board window |
| File | Save as Template | — (no default) | Board window; 09-templates.md |
| File | Reveal in Finder | — (no default) | Board window: the selection's folder(s), or the board root with nothing selected; card window: the card's folder — the selected attachment's file instead when the attachments section is focused |
| File | Add Attachment… | ⇧⌘A | Card window |
| File | Delete | ⌘⌫ | Board window, live selection (chord twin of Put Back — validation enables exactly one). Deliberately **not** extended to the card window: an enabled ⌘⌫ key equivalent would steal delete-to-line-start from the window's text surfaces, so there the card's delete is the sidebar Actions button (05) |
| File | Put Back | ⌘⌫ | Board window, tombstoned selection (chord twin of Delete) |
| File | Delete Immediately | ⌥⌘⌫ | Board window, tombstoned selection; confirmed on boards without git history (mode none / repo-nested), immediate on git boards — 03 ▸ Trash |
| File | Empty Trash… (confirmed) | ⇧⌘⌫ | Board window, trash non-empty |
| File | Close | ⌘W | Any window; flushes per 02 ▸ Windows |
| Edit | Undo / Redo (M−) | ⌘Z / ⇧⌘Z | Focus-routed (06 ▸ Undo routing): text undo in a focused editor, git undo otherwise; git undo disabled on no-git and repo-nested boards |
| Edit | Cut / Copy / Paste | ⌘X / ⌘C / ⌘V | Board window: cards and lanes (cards-XOR-lanes selections; lane paste lands after the anchor lane — 04 ▸ Clipboard; on a zero-lane board only a lane payload pastes — 04 ▸ ⌘N target rule); in the trash, ⌘C copy-out only (card and lane entries), ⌘X disabled (04 ▸ The trash); text editors: standard text clipboard |
| Edit | Select All | ⌘A | Board: all visible live cards (filter-respecting); text editors: the text |
| Edit | Find | ⌘F | Board window: board search (04 ▸ Search); card window: find-in-text (05) |
| Edit | Find Next / Find Previous | ⌘G / ⇧⌘G | Card window: the find bar's stepping; disabled in the board window — board search is a live filter, not a cursor. **Use Selection for Find (⌘E) is deliberately absent**: the chord belongs to View ▸ Edit Body, which outranks the text view's binding; a user who wants it back remaps Edit Body system-natively |
| Board | Open Card | ⌘↩ | Board window, sole selected live card; during an inline title edit (placeholder or rename), commits it and opens — the one board command enabled mid-edit (04 ▸ Grammar) |
| Board | Rename | — (cards: Return in place) | Board window, sole selected card/lane; a lane's only rename path (Return on a lane creates); exists for completeness and remapping |
| Board | Style… (the style editor; selection-aware) | ⌥⌘S | Board window: selected cards or lane; nothing selected = the board |
| Board | Move Up / Move Down | ⌥⌘↑ / ⌥⌘↓ | Card selection within one lane (within-lane sort, logical order; non-contiguous selections gather behind their first card on the first press); disabled when the selection spans lanes; inert on lanes and on tombstoned cards |
| Board | Move Left / Move Right | ⌘← / ⌘→ | Lane selection only (one slot; never into the trash) — cards cross lanes by drag or Cut/Paste, not ⌘-arrows |
| Board | Increase Lane Width / Decrease Lane Width (the stepper's re-divide semantics, never the window's size — 03 ▸ Lane) | ⌥⌘→ / ⌥⌘← | Selected lane |
| Board | Pull / Push | — (no default) | Remote-backed boards only (07); popover twins exist |
| View | Show Trash (checkmark toggle) | ⇧⌘T | Board window |
| View | Edit Body (checkmark toggle) | ⌘E | Card window; disabled while Raw Source is active |
| View | Raw Source (checkmark toggle; toggling off = Apply) | ⌥⌘E | Card window |
| View | History | — (no default) | Card window; focuses the sidebar History section (05); git boards only — section absent, item disabled on mode none / repo-nested |

## Fixed grammar keys (G)

All board grammar keys are inert while a title editor is focused, and menu dispatch narrows to the text domain — board-scoped commands disable, text chords route to the field, Open Card ⌘↩ excepted (04 ▸ Grammar, focused-editor rule).

| Key | Context | Action |
|---|---|---|
| Arrows / ⇧-arrows | Board window | Spatial card navigation / extend selection; lane selected: ←/→ move lane selection; shown trash is the last container |
| ⌥↑ / ⌥↓ / ⌥← / ⌥→ | Board window | Jump: lane's first/last card; first/last lane; ⌥→ reaches the shown trash |
| Return | Board, lane selected | Create card at its bottom (placeholder; Return commits and re-selects the lane) |
| Return | Board, sole selected card | Inline rename; committing empty removes `title`; inert on multi-card selections |
| Escape | Board window | One layer per press: abandon editor, else clear search (focus to board), else deselect |
| ⌫ | Board, live selection | Tombstone — plain-key synonym of File ▸ Delete, kept grammar so no second "Delete" title exists (04) |
| Return | Card window, Preview | Enter Edit |
| Escape | Card window, Edit | Return to Preview |
| Return | Card window, title field | Commit title, focus into body |
| Escape / ⌘↩ | Card window, source mode | Cancel / Apply (leaving-by-toggle is Apply too — 05) |
| Arrows / Space / Return / ⌫ | Card window, attachments section focused | Row navigation / QuickLook / open / Remove to *system* Trash (05) |

## Pointer grammar (P)

- **Selection clicks** (board): click selects, ⌘-click toggles, ⇧-click range-extends, click-drag rubber-bands; lane empty-space click selects the lane, double-click creates a card. **Clicking never edits**; fast double-click opens the card window (04 ▸ Selection).
- **Drag & drop — the locality model** (04): within-board move / cross-board copy; **⌥ always forces copy, ⌘ always forces move**; multi-drag; lane header is the lane drag surface; drag-to-restore from the trash.
- **Lane edge drag** (03 ▸ Lane): window-growing resize between integer widths — the one width control that moves the window.
- **Finder file drops** (04): onto a card = attach; onto lane empty space = one card per file; anywhere on the card window = attach (05's payload-split precedence).
- **Preview** (05): task-list checkbox toggle (the one interactive exception), link opens, text selection; carousel paging on the card face (03).
- **Attachment rows** drag out their file URL (05). **Welcome rows**: single click selects, double click opens (03).

## Context menus

Context menus are the per-item action inventory VoiceOver reads (10 ▸ Actions). Every entry is a twin of a menu command, a fixed grammar key, or a configuration control — no function's only home:

| Surface | Entries |
|---|---|
| Card / lane | Open (cards), Rename, Style…, quick-style recents row (03), Delete |
| Trash entries | Put Back, Delete Immediately, Reveal in Finder (inspection before a purge; twin of File ▸ Reveal in Finder, which is not edit-shaped and stays enabled on tombstoned selections — 04 ▸ The trash) |
| Lane header | Width control (stepper — menu twins Increase/Decrease Lane Width) |
| Attachment row | Open, Remove (system Trash) — twins of the focused section's grammar keys (Return / ⌫ — 05); Reveal in Finder — twin of File ▸ Reveal in Finder in its attachments-focused context |
| Welcome recent | Open, Reveal in Finder, Forget (C — registry management, welcome-scoped) |

## Configuration controls (C)

- **Board popover** (Board Info ⌘I — 03 ▸ Board popover): board rename; embedded style editor; add-git (mode none) / repo-nested explanation (06); branch display, switch, create; commit-identity name/email (06); add/change remote, credential fields, machine SSH key Copy + Verify, Authentication-needed state (07); ahead/behind with Pull/Push buttons and the push-on-commit toggle.
- **Style editor** (three anchors — 03 ▸ Styling ▸ Controls): grids arrow-navigable, every well Tab-reachable.
- **Template chooser** (09): template selection; Reveal in Finder for the user store.
- **Welcome** (03): recents list; Forget.

## Standard macOS furniture

System-provided; the app adds nothing beyond convention: App menu (About, Hide, Quit — **no Settings pane in v1**: the only app-wide preferences, quick-style recents and `NSUserKeyEquivalents`, need no UI; ⌘, unused), Window menu, Help (carries the one line teaching the System Settings remap path — 04). **No Print story in v1** (⌘P unused). Customize Toolbar… per system convention (03).

## Changes from Kanban

- New doc — no pathfinder counterpart; 04's map table moved here (04 keeps the behavioral rules).
- The first compilation audit added two commands that existed only as context/pointer surfaces, violating 04's contract: **File ▸ Open… (⌘O)** and **File ▸ Reveal in Finder** (no default; selection-aware).

## Open questions

None currently.