@awebai/oats 0.66.0 → 0.67.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/bin/oats.mjs +66 -13
  2. package/docs/capabilities.md +4 -4
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/desktop-cli-api.md +217 -6
  5. package/docs/desktop.md +101 -22
  6. package/docs/implementation.md +6 -5
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-lane.md +16 -0
  10. package/docs/release-notes/v0.67.0.md +366 -0
  11. package/docs/release-notes/v0.67.1.md +64 -0
  12. package/docs/servers.md +3 -2
  13. package/docs/souls-and-instances.md +20 -3
  14. package/docs/tui.md +570 -176
  15. package/docs/upgrading.md +107 -25
  16. package/docs/workspaces.md +1 -1
  17. package/lib/capability-contract.mjs +2 -2
  18. package/lib/core.mjs +126 -54
  19. package/lib/instance-color.mjs +58 -0
  20. package/lib/instance-inspect.mjs +107 -23
  21. package/lib/instance-lifecycle.mjs +21 -1
  22. package/lib/instance-naming.mjs +187 -0
  23. package/lib/instance-resolution.mjs +5 -1
  24. package/lib/materialize.mjs +62 -11
  25. package/lib/servers.mjs +15 -6
  26. package/lib/soul-composition.mjs +7 -3
  27. package/package-catalog.json +1 -1
  28. package/package.json +1 -1
  29. package/packages/client/cli-adapter.mjs +37 -5
  30. package/packages/client/cli-locator.mjs +2 -2
  31. package/packages/client/composed-gate.mjs +10 -2
  32. package/packages/client/deployment-data.mjs +5 -0
  33. package/packages/client/deployment-identity.mjs +40 -0
  34. package/packages/client/deployment-panel.mjs +3 -1
  35. package/packages/client/inspect-boundary.mjs +11 -7
  36. package/packages/client/inspect-cache.mjs +2 -2
  37. package/packages/client/instance-name.mjs +28 -0
  38. package/packages/client/instance-presentation.mjs +11 -0
  39. package/packages/client/keymap.mjs +85 -24
  40. package/packages/client/keys-file.mjs +122 -0
  41. package/packages/client/own-codes.mjs +4 -2
  42. package/packages/client/panel-views.mjs +62 -9
  43. package/packages/client/spawn-naming.mjs +31 -0
  44. package/packages/client/spawn-preview-cli.mjs +22 -7
  45. package/packages/client/spawn-preview-contract.mjs +24 -0
  46. package/packages/client/spawn-preview-facts.mjs +8 -4
  47. package/packages/client/spawn-preview.mjs +47 -2
  48. package/packages/tui/README.md +3 -3
  49. package/packages/tui/lib/actions.mjs +57 -14
  50. package/packages/tui/lib/client.mjs +8 -4
  51. package/packages/tui/lib/config.mjs +50 -9
  52. package/packages/tui/lib/main.mjs +40 -13
  53. package/packages/tui/lib/model.mjs +167 -63
  54. package/packages/tui/lib/read.mjs +53 -1
  55. package/packages/tui/lib/store.mjs +148 -54
  56. package/packages/tui/lib/term/keys.mjs +19 -5
  57. package/packages/tui/lib/term/kitty.mjs +36 -11
  58. package/packages/tui/lib/term/through.mjs +61 -28
  59. package/packages/tui/lib/views/frame.mjs +158 -79
  60. package/packages/tui/lib/views/help.mjs +109 -26
  61. package/packages/tui/lib/views/instances.mjs +59 -20
  62. package/packages/tui/lib/views/palette.mjs +14 -4
  63. package/packages/tui/lib/views/souls.mjs +2 -2
  64. package/packages/tui/lib/views/switcher.mjs +6 -1
  65. package/skills/oats-getting-started/SKILL.md +13 -8
package/docs/tui.md CHANGED
@@ -100,20 +100,20 @@ runs.
100
100
  Instances 1 │ state running
101
101
  > ● dev │ harness claude, claude-opus-5-5 (so…
102
102
  │ work worktree, agents/dev
103
- ● reviewer !│ team eng
103
+ ● reviewer Needs input │ team eng
104
104
  ○ helper │ started 11:00
105
105
  ──────────────────────────────────────│ home …oy/agents/dev/instances/dev
106
106
  Souls 2 │
107
107
  Capabilities 3 │
108
108
  ──────────────────────────────────────│
109
- Alt+O commands │
109
+ Ctrl+X commands │
110
110
  Ctrl+K palette │
111
111
  Enter open │
112
112
  n spawn │
113
+ w workspaces │
113
114
  ? help │
114
115
  q quit │
115
116
  │
116
- │
117
117
  ```
118
118
 
119
119
  The screen is the sidebar on the left and the main area on the right, with
@@ -143,13 +143,15 @@ while a terminal is open); under 80 columns it has the whole width.
143
143
  workspace with no instances reads `No agents yet: n spawns one`, with the
144
144
  key `spawn` has (`No agents yet.` when it has none).
145
145
  - **The cheat sheet** comes last, under a rule: a few keys, one per row,
146
- the key in bold and what it does beside it. Its first row is always the
147
- leader, `Alt+O commands`, which reaches every action; then
146
+ the key in bold and what it does beside it. Its first row is the
147
+ leader, `Ctrl+X commands`, which reaches every action (but while a
148
+ terminal has the focus under the kitty keyboard protocol, below); then
148
149
  `Ctrl+K palette`. In a view's list it names what `Enter` does now
149
150
  (`open`, `focus terminal` on the row whose terminal is open, `detail`
150
151
  in the Souls and Capabilities views), then `n spawn` where it spawns,
152
+ `w workspaces` (the [switcher](#the-switcher)) in the Instances view,
151
153
  and `? help` and `q quit` last; with the detail's focus `Tab back`
152
- comes before `Enter`. The other keys (the acts, `/`, `Tab`, `r`, `w`,
154
+ comes before `Enter`. The other keys (the acts, `/`, `Tab`, `r`,
153
155
  and a terminal's `z`, `c`, `[` and `]`) are not listed there:
154
156
  the leader's hint, the palette and the help name them. While the
155
157
  terminal has the focus, in an overlay and in the filter field it names
@@ -180,8 +182,21 @@ while a terminal is open); under 80 columns it has the whole width.
180
182
  indent alone says which instance is under which: no mark is drawn for
181
183
  it. A row whose instances are folded away (`h`) says how many after its
182
184
  name: `+1`.
183
- - **Each row** is the mark of its state and the name, then `!` at the
184
- right when it needs input. The harness and the state in words are in
185
+ - **Each row** is the mark of its state and the name, then, when it needs
186
+ input, a tag at its right edge in the Desktop's words: `Needs input`. A
187
+ folded row with waiting instances among those it folds away says how
188
+ many: `3 below`, and `99+ below` past 99. A row that needs input itself
189
+ and folds waiting ones away says `Needs input`, as the Desktop's row
190
+ does: the detail's `below` line names the others. The tag is in reverse
191
+ video in the waiting colour, and on the selected row, which is in reverse
192
+ video already, it is the waiting colour not reversed, a gap in the
193
+ selection's bar; under `NO_COLOR` the reverse video alone carries it. On
194
+ a narrow row the tag gives way first: it says its words only where the
195
+ whole name, its `+1` and the row's word in its column all fit beside them,
196
+ and else shrinks to `!`, or the count alone (`3`, `99+`), still in
197
+ reverse video, in the cells every row keeps at its right edge. So the
198
+ tag never cuts a name, a word or a mark: those give way as on a row
199
+ that does not wait. The harness and the state in words are in
185
200
  the detail. A row has a word, dim, only where its mark cannot say it: the
186
201
  state of a home a spawn or a retire holds (`Retire didn't finish`), or
187
202
  the shared words for why an instance cannot be reached or opened:
@@ -274,13 +289,24 @@ in its workspace for the rest of the run, also while it is not reached.
274
289
  | `?` | `?` | state unknown: the kernel or the terminal probe could not tell, or the instance's machine was not reached |
275
290
  | `◆` | `#` | held by a spawn or a retire: under way (Retiring…), failed or not finished ([below](#held-rows)) |
276
291
  | `+n` | `+n` | after a name: n instances folded away below it |
277
- | `!` | `!` | needs input |
278
- | `!N` | `!N` | N instances folded away below it need input |
292
+ | `Needs input` | `Needs input` | needs input: a tag in reverse video at the row's right edge, `!` where the whole name does not fit beside the words |
293
+ | `N below` | `N below` | N instances folded away below it need input, `N` where the whole name does not fit beside the words |
279
294
  | `>` | `>` | the selected row (also drawn in reverse video), and the pane the movement keys act on |
280
295
  | `*` | `*` | in the switcher: the workspace that is open |
281
296
 
282
297
  Every state has a mark of its own shape, so nothing is told by colour alone.
283
298
 
299
+ **An instance's colour** (feature `instance-color`; set with
300
+ `oats instance color <instance> <colour>`, [desktop-cli-api.md](desktop-cli-api.md#an-instances-colour-oats-instance-color))
301
+ colours its mark, in the list and in a soul's detail: a running mark in it, a
302
+ stopped one and one with a shell left in it dim in it. `?` and `◆` keep their
303
+ own look whatever the colour, and an instance with no colour looks as above.
304
+ The six colours are the terminal's: `sand` yellow, `sage` green, `slate` blue,
305
+ `mauve` magenta, `clay` red, `olive` cyan, the souls' own map. Which colour a
306
+ row shows is the Desktop's rule (`instanceColor` in `packages/client`); an
307
+ older kernel reports none. Setting a colour from the TUI is not in this
308
+ version.
309
+
284
310
  <a id="held-rows"></a>**A held row** says in its word what holds it, by the
285
311
  Desktop's rule:
286
312
 
@@ -332,7 +358,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
332
358
  ## Open an agent's terminal
333
359
 
334
360
  ```
335
- acme-platform │ backend-lead
361
+ acme-platform │[backend-lead]
336
362
  │$ make docs
337
363
  Instances 1 │Building the reference...
338
364
  > ● backend-lead │
@@ -341,30 +367,40 @@ fit; the detail shows them whole. The TUI's own words end the same way:
341
367
  Souls 2 │
342
368
  Capabilities 3 │
343
369
  ──────────────────────────────│
344
- Alt+O commands │
345
- Alt+O Esc the list │
346
- Alt+O Alt+O types Alt+O │
370
+ Ctrl+X commands │
371
+ Ctrl+X Esc the list │
372
+ Ctrl+X Ctrl+X types Ctrl+X │
347
373
  ```
348
374
 
349
375
  - **`Enter` on an instance that runs** opens its terminal on the right of
350
- the sidebar, where the detail was, over every row. Its top row names the
351
- agent (and `on <machine>` for one of another machine); under it is the
376
+ the sidebar, where the detail was, over every row. Its top row is the
377
+ [tab bar](#tabs), here one tab: the agent's name in brackets (and
378
+ ` · <machine>` for one of another machine); under it is the
352
379
  agent's screen, as the agent draws it, in its own colours. While a
353
380
  terminal is open the sidebar keeps 30 columns at most, also while the
354
381
  detail stands in the terminal's place, and a name longer than its row is
355
382
  cut with `…` (`...` in ASCII).
356
383
  - **The terminal has the focus.** What you type, what you paste and every
357
384
  key go to the agent exactly as typed, `Ctrl+C`, `Ctrl+Z`, `Esc` and `q`
358
- among them, but for **[the leader](#the-leader)** (`Alt+O`, `Ctrl+\` on
359
- macOS, unless [`tui.json`](#change-the-keys-tuijson) names another), the
360
- one key the TUI takes from the agent, and the [chords](#chords) while your
361
- terminal sends them. Under the kitty keyboard protocol every key reaches
385
+ among them, but for **[the leader](#the-leader)** (`Ctrl+X`, unless
386
+ [`tui.json`](#change-the-keys-tuijson) names another), the
387
+ one key the TUI takes from the agent, and the [chords](#chords) (the
388
+ Ctrl+Alt ones, or the Ctrl+Shift ones under
389
+ [the option](#switch-to-ctrlshift), while your terminal sends them). Under the kitty keyboard protocol every key reaches
362
390
  the agent as the bytes it sends without it. The leader then `Esc` gives the
363
391
  focus to the list; the leader twice types the leader into the agent; the
364
392
  leader then another key does what that key does from anywhere. While the
365
393
  terminal has the focus the cheat sheet names those three:
366
- `Alt+O commands`, `Alt+O Esc the list`, `Alt+O Alt+O types Alt+O`. A
367
- leader inside a bracketed paste is pasted, not taken.
394
+ `Ctrl+X commands`, `Ctrl+X Esc the list`, `Ctrl+X Ctrl+X types Ctrl+X`.
395
+ While the terminal confirms the kitty keyboard protocol
396
+ ([Chords](#chords)) the chords come first: `Ctrl+Alt+K palette`,
397
+ `Alt+Shift+Up/Down agent`, `Alt+Shift+Left/Right tab` (with two tabs or
398
+ more), `Ctrl+Alt+W close`, `Ctrl+Alt+Z zoom` (`Ctrl+Shift+K`,
399
+ `Ctrl+Shift+W` and `Ctrl+Shift+M` under the option), then the leader's three.
400
+ Without it the leader's three lead, and the Alt+Shift arrows follow them.
401
+ On a short screen the sheet gives up rows from its end, and the leader's
402
+ `commands` last of all. A leader inside a bracketed paste is pasted, not
403
+ taken.
368
404
  - **With the list focused** the terminal stays open, and the agent's screen
369
405
  is still drawn as it changes. The cheat sheet names `Enter focus terminal`
370
406
  on its row; the leader's hint names `z zoom` and `w close terminal`.
@@ -387,8 +423,9 @@ fit; the detail shows them whole. The TUI's own words end the same way:
387
423
  sheet shows it again. Beside the sidebar the terminal is never narrower
388
424
  than 40 columns: with less room it has the whole screen too.
389
425
  - **With the whole screen** (zoomed, or a narrow terminal) no cheat sheet is
390
- drawn. The terminal's title row carries the keys at its right, dim:
391
- `Alt+O commands Alt+O Esc the list`, and while the leader waits, the
426
+ drawn. The terminal's tab bar carries the keys at its right, dim:
427
+ `Ctrl+X commands Ctrl+X Esc the list`, after the chords under the kitty
428
+ keyboard protocol, as many as fit, and while the leader waits, the
392
429
  leader's hint, as many keys as fit, `Esc the list` last. The agent's
393
430
  screen keeps every row under it.
394
431
  - **A terminal also closes by itself** when its viewer ends, shown or
@@ -430,7 +467,7 @@ fit; the detail shows them whole. The TUI's own words end the same way:
430
467
  ## Tabs
431
468
 
432
469
  ```
433
- acme-platform │ backend-lead docs-writer• qa-runner
470
+ acme-platform │[backend-lead]│ docs-writer• │ qa-runner
434
471
  │$ make test
435
472
  Instances 1 │ok 41 of 41
436
473
  > ● backend-lead │
@@ -440,30 +477,34 @@ fit; the detail shows them whole. The TUI's own words end the same way:
440
477
  Souls 2 │
441
478
  Capabilities 3 │
442
479
  ──────────────────────────────│
443
- Alt+O commands │
444
- Alt+O Esc the list │
445
- Alt+O Alt+O types Alt+O │
480
+ Ctrl+X commands │
481
+ Ctrl+X Esc the list │
482
+ Ctrl+X Ctrl+X types Ctrl+X │
446
483
  ```
447
484
 
448
485
  Each terminal open in the panel is a tab, and the panel holds up to four.
449
486
 
450
- - **The tab strip** is the panel's top row: each tab's agent, in the order
451
- the tabs were opened. With one tab the row reads as
452
- [above](#open-an-agents-terminal), the agent's name alone.
453
- - **The shown tab** is the one whose screen the panel draws. Its name is
454
- in reverse video while the terminal has the focus, and bold otherwise.
455
- - **The other tabs are hidden**, their names plain. A hidden tab whose
456
- agent wrote since it was last shown has `•` after its name (`*` in
457
- ASCII); the mark goes when the tab is shown. A hidden tab's screen is
458
- not read: only that its agent wrote.
459
- - **An agent of another machine** reads `<name>`, then a dim
460
- `on <machine>`.
461
- - **A strip longer than its row is cut** in this order: the hidden tabs'
462
- `on <machine>`, then the hidden tabs' names, each to an equal share of
463
- what the shown tab leaves, with `…` (`...` in ASCII), then the shown
464
- tab's `on <machine>`; then the hidden tabs farthest from the shown one
465
- are left out of the row (they stay open). The shown tab's name stays
466
- whole while the row can hold it.
487
+ - **The tab bar** is the panel's top row whenever a terminal is open, with
488
+ one tab or many, as a terminal's own tabs read: each tab's agent, in the
489
+ order the tabs were opened, a dim `│` (`|` in ASCII) between two tabs.
490
+ - **The shown tab** is the one whose screen the panel draws, the front
491
+ tab. It stands in brackets, `[backend-lead]`, a mark that needs no
492
+ style, so it reads the same under `NO_COLOR` and in ASCII. Its name is
493
+ bold, and the whole tab is in reverse video while the terminal has the
494
+ focus.
495
+ - **The other tabs are hidden**, dim, a cell on each side of the name. A
496
+ hidden tab whose agent wrote since it was last shown has `•` after its
497
+ name (`*` in ASCII), not dim; the mark goes when the tab is shown. A
498
+ hidden tab's screen is not read: only that its agent wrote.
499
+ - **An agent of another machine** reads `<name> · <machine>` inside its
500
+ tab, the machine dim (`-` for `·` in ASCII): `[billing-lead · garnet]`.
501
+ - **A bar longer than its row is cut** in this order: the hidden tabs'
502
+ machines, then the hidden tabs' names, each to an equal share of what
503
+ the shown tab leaves, with `…` (`...` in ASCII), then the shown tab's
504
+ machine; then the hidden tabs farthest from the shown one are left out
505
+ of the row with their dividers (they stay open). The shown tab's name
506
+ stays whole while the row can hold it, and is cut last.
507
+ - The TUI takes no mouse input: a tab is shown with the keys below.
467
508
  - **Opening.** `Enter` on a row, an instance in
468
509
  [the palette](#the-palette), the leader then `Up` or `Down`, and a
469
510
  [spawn](#spawning-an-agent)'s new agent open a terminal the same way:
@@ -474,7 +515,7 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
474
515
  machine is asked whether it can be opened, another open does nothing,
475
516
  and neither does a key that shows another tab.
476
517
  - **At four tabs nothing closes by itself.** The open does nothing, and
477
- the line under the title says `4 terminals are open; close one with Alt+O w.`
518
+ the line under the title says `4 terminals are open; close one with Ctrl+X w.`
478
519
  (with your leader, when [`tui.json`](#change-the-keys-tuijson) names
479
520
  another). A tab still starting, and an agent of another machine while
480
521
  it is asked, hold a place among the four. An instance that cannot be
@@ -485,7 +526,7 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
485
526
  open. The leader then
486
527
  `Left` or `Right` does the same from any focus, and from another view
487
528
  goes to the Instances view first.
488
- - The strip does not wrap: on the first tab `[` does nothing, and on the
529
+ - The bar does not wrap: on the first tab `[` does nothing, and on the
489
530
  last `]`; the leader then `Left` or `Right` there leaves even the focus
490
531
  where it was.
491
532
  - The focus does not move: in the terminal it stays in the terminal,
@@ -493,10 +534,11 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
493
534
  - **Showing a tab selects its instance's row** in the list and brings it
494
535
  into view: a filter that hides the row is cleared, and an instance
495
536
  folded over it is opened.
496
- - **The palette** lists the instances most recently opened or shown first,
497
- as the Desktop's does. When the first of them is the shown tab's, the
498
- palette opens with the second selected, so the palette then `Enter` goes
499
- back to the terminal shown before it.
537
+ - **The palette** groups the instances as [The palette](#the-palette) says,
538
+ the group last used first, as the Desktop's does. When the first of them
539
+ is the shown tab's, the palette opens on the instance shown before it,
540
+ wherever its group puts it, so the palette then `Enter` goes back to that
541
+ terminal.
500
542
  - **Closing.** The leader then `w`, or `c` in the Instances view, closes the
501
543
  shown tab: its agent keeps running. The tab to its right is shown, else
502
544
  the one to its left.
@@ -512,11 +554,13 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
512
554
  and the list takes the focus.
513
555
  - A hidden tab: the shown tab and the focus stay as they were.
514
556
  - **Zoom** (`z`, or the leader then `z`) gives the shown tab the whole
515
- screen. The strip stays its top row, and the other tabs stay open.
557
+ screen. The tab bar stays its top row, and the other tabs stay open.
516
558
  - **The tabs are the open workspace's.** Opening another workspace in
517
559
  [the switcher](#the-switcher) closes them all, and so does the open
518
560
  workspace no longer being listed; their agents keep running. Coming back
519
- opens none of them again.
561
+ opens none of them again. Opening the same workspace again, with its
562
+ deployment of this machine now opened beside another machine's, keeps
563
+ them.
520
564
 
521
565
  ## Splits
522
566
 
@@ -531,13 +575,13 @@ Each terminal open in the panel is a tab, and the panel holds up to four.
531
575
  Souls 2 │ │
532
576
  Capabilities 3 │ │
533
577
  ──────────────────────────────│ │
534
- Alt+O commands │ │
535
- Alt+O Esc the list │ │
536
- Alt+O Alt+O types Alt+O │ │
578
+ Ctrl+X commands │ │
579
+ Ctrl+X Esc the list │ │
580
+ Ctrl+X Ctrl+X types Ctrl+X │ │
537
581
  ```
538
582
 
539
583
  The panel can be split in two **groups**, side by side or one above the
540
- other. Each group is a panel of [tabs](#tabs) of its own: a strip, a shown
584
+ other. Each group is a panel of [tabs](#tabs) of its own: a tab bar, a shown
541
585
  tab and the marks of its hidden ones.
542
586
 
543
587
  - **Splitting.** The leader then `|` splits the panel side by side, and the
@@ -548,14 +592,14 @@ tab and the marks of its hidden ones.
548
592
  - **There are at most two groups.** With two, the split keys do nothing,
549
593
  and the line under the title says `The panel has two groups already.`
550
594
  - **Each group needs 40 columns side by side, and 8 rows one above the
551
- other**, its strip counted. The panel beside the sidebar then needs 81
595
+ other**, its tab bar counted. The panel beside the sidebar then needs 81
552
596
  columns (a terminal of 112), or 17 rows. A split that would leave a
553
597
  group smaller does nothing, and the line says so:
554
598
  `No room to split side by side: each group needs 40 columns.` or
555
599
  `No room to split one above the other: each group needs 8 rows.`
556
600
  - **What is drawn.** A rule separates the groups. Both groups' shown tabs
557
601
  are drawn as their agents write; hidden tabs only set their marks.
558
- - The focused group's strip is drawn as with one group: its shown tab in
602
+ - The focused group's tab bar is drawn as with one group: its shown tab in
559
603
  reverse while its terminal has the focus, bold otherwise. The other
560
604
  group's shown tab is bold, never in reverse, so one terminal at a time
561
605
  reads as the one you type into.
@@ -579,7 +623,7 @@ tab and the marks of its hidden ones.
579
623
  - any other: a new tab in the focused group, after its shown tab, or as
580
624
  the first tab of the empty group.
581
625
  - **The four tabs are counted across both groups.** At four, the line
582
- says `4 terminals are open; close one with Alt+O w.` as with one group.
626
+ says `4 terminals are open; close one with Ctrl+X w.` as with one group.
583
627
  - **Moving between the groups.** The leader then `Tab` from a terminal goes
584
628
  to the other group's shown terminal, or to the other group when it is
585
629
  empty. From the list it goes to the focused group's terminal, or, with
@@ -625,7 +669,7 @@ them, from the same code.
625
669
  ──────────────────────────────────────│ ● dev-1 ● dev-2
626
670
  Capabilities 3 │ i shows them in the Instances view.
627
671
  ──────────────────────────────────────│
628
- Alt+O commands │
672
+ Ctrl+X commands │
629
673
  Ctrl+K palette │
630
674
  Enter detail │
631
675
  n spawn │
@@ -694,7 +738,7 @@ them, from the same code.
694
738
  oats-okf · package · v1.2.0 │
695
739
  okf-knowledge Knowledge │ Used by 2 souls
696
740
  ──────────────────────────────────────│ ■ dev ·2 · 1 on an older version
697
- Alt+O commands │ ■ reviewer ·1
741
+ Ctrl+X commands │ ■ reviewer ·1
698
742
  Ctrl+K palette │
699
743
  Enter detail │
700
744
  ? help │
@@ -772,17 +816,17 @@ sidebar's title says `workspaces` and no view is open; under 80 columns the
772
816
  switcher covers the whole screen.
773
817
 
774
818
  ```
775
- workspaces │ > * acme-platform This machine · garnet
776
- │ ledger quartz
777
- Instances 1 │ Not matched to a workspace
778
- Souls 2 │ basalt ssh needs a prompt
779
- Capabilities 3 │ On this machine, not opened
780
- ────────────────────────────────────────────────│ acme-docs ~/acme-docs
781
- Alt+O commands │ sandbox Not found.
782
- Ctrl+K palette │
783
- Enter open │
784
- / filter │
785
- r refresh │
819
+ workspaces │ > * acme-platform
820
+ │ This machine
821
+ Instances 1 │ garnet
822
+ Souls 2 │ lfx
823
+ Capabilities 3 │ This machine · not opened
824
+ ────────────────────────────────────────────────│ athenea (lfx)
825
+ Ctrl+X commands │ Not matched to a workspace
826
+ Ctrl+K palette │ basalt ssh needs a prompt
827
+ Enter open │ On this machine, not opened
828
+ / filter │ acme-docs Timed out · ~/acme-docs
829
+ r refresh │ sandbox Not found.
786
830
  Esc close │
787
831
  ? help │
788
832
  q quit │
@@ -790,20 +834,36 @@ switcher covers the whole screen.
790
834
 
791
835
  It lists, in this order:
792
836
 
793
- - **The workspaces this run knows**, one row each: the name, the machines
794
- its deployments are on, and at the right edge how many of its deployments
795
- are not live (`1 deployment not live`). A workspace here is what the
796
- rules shared with the Desktop make of the deployments opened in this run
797
- and of what the registered machines answered: the ones that report the
798
- same workspace are one row. `*` marks the workspace that is open.
837
+ - **The workspaces**, one row each, by name. Under each stands one dim line
838
+ per deployment of it:
839
+ - the machine it is on (`This machine`, `garnet`), with the folder's last
840
+ segment when one machine holds two deployments of it;
841
+ - then its state when it is not live: `not opened` for a deployment of
842
+ this computer's list that this run has not opened, else the words the
843
+ sidebar's headings use (`not observed`, `not reached`, `stale`,
844
+ `remembered`).
845
+
846
+ A workspace is what the rules shared with the Desktop make of the
847
+ deployments opened in this run, of what the registered machines answered,
848
+ and of the deployments of this computer's list whose workspace was read
849
+ (below): the ones that report the same workspace (its key and default
850
+ team) are one row, whichever machine they are on. Its name is the one a
851
+ deployment of this machine gives it: the workspace's own name once one is
852
+ opened and read, the folder's name of one that is not, else the last part
853
+ of the workspace's key. `*` marks the workspace that is open.
799
854
  - **`Not matched to a workspace`**: what those rules matched to no
800
855
  workspace, each by its own name with a short reason. A machine that has
801
856
  not answered in this run is listed here.
802
857
  - **`On this machine, not opened`**: the rows of this computer's list of
803
- deployments (`oats deployments`) that this run has not opened, in the
804
- list's order, each by its folder's name and its path. Nothing is read from
805
- one before it is picked. A row that cannot be opened says why where its
806
- path stood, and does not open:
858
+ deployments (`oats deployments`) that this run has not opened and that no
859
+ workspace took, in the list's order, each by its folder's name and its
860
+ path. A row whose workspace is not known yet says nothing more; one whose
861
+ read failed says why before its path (`Timed out`, `Not read`), and so
862
+ does one whose workspace attaches to none (`Workspace not known yet`,
863
+ `Invalid workspace reference`, `Reports no workspace`), so a narrow row
864
+ cuts the path, not the reason; both still open.
865
+ A row that cannot be opened says why where its path stood, and does not
866
+ open:
807
867
 
808
868
  | The row says | The list's state |
809
869
  |---|---|
@@ -811,9 +871,26 @@ It lists, in this order:
811
871
  | `Not an OATS deployment any more.` | `not-a-deployment`: the folder has no `oats-local.yaml` |
812
872
  | `Can't be read.` | `unreadable`: the check failed, for example for a permission |
813
873
 
814
- The list is read when the switcher opens, on `r` in it and after a
815
- Remove. When a read fails, the rows of the last read stay, under a line
816
- that says the list could not be read, with the kernel's message.
874
+ The list is read once at the start, when the switcher opens, on `r` in
875
+ it and after a Remove. When a read fails, the rows of the last read stay,
876
+ under a line that says the list could not be read, with the kernel's
877
+ message.
878
+
879
+ **How a deployment of the list finds its workspace.** Each row of the list
880
+ that this run has not opened and that the kernel says is a deployment is
881
+ read for its workspace identity: `oats status --dir <path> --json`, the
882
+ same read an opened deployment gets, whose `workspace` object says which
883
+ workspace and default team it is.
884
+
885
+ - **When:** once at the start, and again each time the switcher is opened
886
+ and on `r` in it, after the list is read. Never on a timer.
887
+ - **How:** one at a time, each with its own 30 seconds, all of them within
888
+ 60 seconds. A read still running when the 60 seconds are up is ended,
889
+ and it and the ones not begun say `Timed out`.
890
+ - **The switcher never waits for them:** it is drawn at once, and each
891
+ answer moves its row into its workspace's as it comes in. A later
892
+ answer replaces an earlier one; nothing else is read from such a
893
+ deployment until it is opened.
817
894
 
818
895
  | Key | Does |
819
896
  |---|---|
@@ -825,9 +902,16 @@ It lists, in this order:
825
902
  | `Esc` | while a Remove is asked, keeps the row; else clears a kept filter; else closes the switcher, back to the view that was open |
826
903
  | `1` | closes the switcher, back to the view that was open |
827
904
 
828
- **Enter on a workspace** opens its view. **Enter on a row of the list**
829
- opens that deployment in this run: from then on it is read with the others,
830
- and its workspace is the open view. A folder that stopped being a deployment
905
+ **Enter on a workspace** opens its view. Every deployment of it on this
906
+ machine that this run has not opened is opened first: asked whether it is
907
+ still a deployment, as a row of the list is, then read with the others from
908
+ then on. The view holds it and the other machines' deployments of the
909
+ workspace at once, `not observed` until its first read. One that is no
910
+ longer a deployment is not opened, and the workspace opens on its other
911
+ deployments; with none to open, the switcher stays and the list is read
912
+ again. **Enter on a row of the list** opens that deployment in this run:
913
+ from then on it is read with the others, and its workspace is the open
914
+ view. A folder that stopped being a deployment
831
915
  since the list was read is not opened: its row says
832
916
  `Not an OATS deployment any more.` where its path stood.
833
917
 
@@ -1028,7 +1112,7 @@ the TUI adds only what to do next, naming its keys or an `oats` command:
1028
1112
 
1029
1113
  | Outcome | What follows |
1030
1114
  |---|---|
1031
- | created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the sidebar in a new [tab](#tabs), with the focus in it. With four tabs open the line says it was created, then `4 terminals are open; close one with Alt+O w.`, and nothing opens. Not running after two reads: the line says it is not visible yet, and nothing opens later by itself |
1115
+ | created and started | the instances are read at once; when the new row appears it is selected and its terminal opens beside the sidebar in a new [tab](#tabs), with the focus in it. With four tabs open the line says it was created, then `4 terminals are open; close one with Ctrl+X w.`, and nothing opens. Not running after two reads: the line says it is not visible yet, and nothing opens later by itself |
1032
1116
  | created, but not started, or its wake not saved, or not finished | the line says so; nothing opens. A home the spawn left reads as [held](#held-rows) |
1033
1117
  | not known (the answer was lost, or still running at the deadline) | the line says so, and `C` checks its result once, without spawning again: it is offered only then |
1034
1118
  | its cleanup is owed | the line says so and names the retire |
@@ -1040,6 +1124,140 @@ The line after leaving says so and names `oats status` to see it.
1040
1124
 
1041
1125
  ## Keys
1042
1126
 
1127
+ The keys come in three layers:
1128
+
1129
+ 1. **In the list:** plain keys, such as `n` to spawn, `w` for the switcher, `/` to filter ([In the list](#in-the-list)).
1130
+ 2. **Anywhere, an agent's terminal included:** the [chords](#chords), `Ctrl+Alt+K` and the rest by default, `Ctrl+Shift+K` and the rest [as the option](#switch-to-ctrlshift). Not plain `Ctrl+K`: that is the agent's, kill to the end of the line in Claude Code, Codex, pi and the shell.
1131
+ 3. **Always:** [the leader](#the-leader), `Ctrl+X` then a key, in every terminal.
1132
+
1133
+ ### Every action's keys
1134
+
1135
+ The same keys in `oats tui` and in OATS Desktop. A column per way in: the
1136
+ list's key (the Desktop's sidebar has the same, but `Ctrl+K`), the chord in
1137
+ each family on Linux and Windows, the Desktop's chord on macOS (where
1138
+ `oats tui` has no chords), and the key after the leader. `–` is no key of
1139
+ that kind.
1140
+
1141
+ | Action | In the list | Ctrl+Alt (default) | Ctrl+Shift (the option) | macOS Desktop | The leader then |
1142
+ |---|---|---|---|---|---|
1143
+ | the palette | `Ctrl+K` | `Ctrl+Alt+K` | `Ctrl+Shift+K` | `⌘K` | `k`, `Space` |
1144
+ | spawn an agent (the Desktop's Quick Open) | `n` | `Ctrl+Alt+P` | `Ctrl+Shift+P` | `⌘P` | `n` |
1145
+ | the switcher | `w` | `Ctrl+Alt+O` | `Ctrl+Shift+S` | `⌥⌘O` | `o` |
1146
+ | zoom the shown terminal | `z` | `Ctrl+Alt+Z` | `Ctrl+Shift+M` | `⌥⌘Z` | `z` |
1147
+ | close the shown terminal's tab | `c` | `Ctrl+Alt+W` | `Ctrl+Shift+W` | `⌘W` | `w` |
1148
+ | split side by side | `\|` | `Ctrl+Alt+E` | `Ctrl+Shift+E` | `⌘\` | `\|` |
1149
+ | split one above the other | `-` | `Ctrl+Alt+Shift+E` | `Ctrl+Shift+D` | `⌘⇧\` | `-` |
1150
+ | the other group | – | `Ctrl+Alt+A` | `Ctrl+Alt+A` (kept) | `⌥⌘A` | `Tab` |
1151
+ | the filter | `/` | `Ctrl+Alt+F` | `Ctrl+Alt+F` (kept) | `⌘F` | `/` |
1152
+ | the terminal of the instance before, after | – | `Alt+Shift+Up`, `Alt+Shift+Down` | `Alt+Shift+Up`, `Alt+Shift+Down` (kept) | `⌥⌘↑`, `⌥⌘↓` | `Up`, `Down` |
1153
+ | the tab before, after | `[`, `]` | `Alt+Shift+Left`, `Alt+Shift+Right` | `Alt+Shift+Left`, `Alt+Shift+Right` (kept) | `⌥⌘←`, `⌥⌘→` | `Left`, `Right` |
1154
+ | the first to eighth tab, the last | – | `Ctrl+Alt+1` to `Ctrl+Alt+9` | `Ctrl+Alt+1` to `Ctrl+Alt+9` (kept) | `⌥⌘1` to `⌥⌘9` | – |
1155
+ | an instance's name and colour (OATS Desktop only) | – | `Ctrl+Alt+R` | `Ctrl+Alt+R` (kept) | `⌥⌘R` | – |
1156
+ | move the tab to the other group | – | – | – | – | `m` |
1157
+ | close the empty group | – | – | – | – | `x` |
1158
+ | stop, restart, start, retire | `X`, `R`, `S`, `D` | – | – | – | `X`, `R`, `S`, `D` |
1159
+ | spawn another of the soul | `N` | – | – | – | `N` |
1160
+ | the Instances, Souls, Capabilities views | `1`, `2`, `3` | – | – | – | `1`, `2`, `3` |
1161
+ | the help | `?` | – | – | – | `?` |
1162
+ | the list | `Esc` | – | – | – | `Esc` |
1163
+
1164
+ The option moves seven chords to Ctrl+Shift. The others keep their key in
1165
+ both families, marked kept: Ctrl+Shift with an arrow selects text in inputs
1166
+ and editors, Ctrl+Shift with a digit is a shifted symbol on most layouts,
1167
+ and Ctrl+Shift+A and Ctrl+Shift+F are taken by terminals (kitty, Ghostty,
1168
+ and for F Alacritty and GNOME Terminal too) and by agents (Codex's
1169
+ Ctrl+Shift+A, pi's Ctrl+Shift+F). `Ctrl+Alt+R` is the Desktop's alone, not
1170
+ one of the seven: `oats tui` has no such action and binds no key for it. The list's own keys for moving and
1171
+ reading are in [In the list](#in-the-list). The tables come from
1172
+ `packages/client/keymap.mjs` (`CHORDS`, `PLAIN_KEYS`, `LEADER_TABLE`), which
1173
+ both clients read.
1174
+
1175
+ ### Which family for my terminal
1176
+
1177
+ For `oats tui`, on Linux and Windows. `✓` is a family whose chords reach
1178
+ `oats tui` in that terminal, `✗` one whose chords do not, with the reason.
1179
+ The leader works in all of them. In OATS Desktop both families work.
1180
+
1181
+ | Terminal | Ctrl+Alt (default) | Ctrl+Shift (the option) |
1182
+ |---|---|---|
1183
+ | foot | ✓ | ✓ |
1184
+ | Alacritty | ✓ | ✓ |
1185
+ | Ghostty | ✓ | ✗ Ghostty closes its own tab on Ctrl+Shift+W, taking oats tui with it |
1186
+ | kitty | ✓ | ✗ kitty takes Ctrl+Shift+K, P, S, W and E for itself; W closes its window, `oats tui` with it |
1187
+ | WezTerm | ✓ with `enable_kitty_keyboard`; without it only the Alt+Shift arrows | ✗ WezTerm takes Ctrl+Shift+K, P, M and W for itself: clear the scrollback, its command palette, hide the window, close the tab |
1188
+ | GNOME Terminal | ✗ no kitty keyboard protocol (VTE has none): only the Alt+Shift arrows arrive | ✗ no kitty keyboard protocol: a Ctrl+Shift letter reaches a program as the Ctrl letter |
1189
+ | Konsole | ✓ since 26.08 | ✗ Konsole takes all seven for itself; Ctrl+Shift+W closes the tab |
1190
+ | Windows Terminal | ✓, but `Ctrl+Alt+1` to `9` are its tabs, and the Alt+Shift arrows resize its split panes | ✗ Windows Terminal takes Ctrl+Shift+K, P, M, W and D for itself; W closes the pane |
1191
+
1192
+ Each terminal's defaults at the release
1193
+ [the full matrix](#which-terminals-let-the-chords-through) names.
1194
+
1195
+ ### Switch to Ctrl+Shift
1196
+
1197
+ On Linux and Windows. macOS has no option: the Desktop keeps its ⌘ chords
1198
+ there, and `oats tui` the leader.
1199
+
1200
+ - **In OATS Desktop:** the Shortcuts page (`Ctrl+,`), at its top, **Shortcut
1201
+ family, shared with oats tui**: choose **Ctrl+Shift (foot, Alacritty)**. The Desktop writes the
1202
+ file below and switches its keys at once. **Ctrl+Alt (default)** switches
1203
+ back. A change by hand reaches the Desktop when it next gets the focus.
1204
+ - **Or by hand:** write `$OATS_HOME_DIR/config/keys.json`, else
1205
+ `~/.oats/config/keys.json`, beside [`tui.json`](#change-the-keys-tuijson):
1206
+
1207
+ ```json
1208
+ { "chords": "ctrl+shift" }
1209
+ ```
1210
+
1211
+ `"ctrl+alt"` is the default.
1212
+ - **`oats tui` reads it at its start:** restart it after a change, from the
1213
+ Desktop or by hand.
1214
+ - **Nothing to fix when it is wrong.** A missing file, one that cannot be
1215
+ read or is larger than 16 KiB, one that is not a JSON object, one with no
1216
+ `chords` or another value: each means Ctrl+Alt, and the help says why
1217
+ (`keys.json: unknown chords value, using Ctrl+Alt`). The Desktop changes
1218
+ only `chords` and keeps every other key in the file; a file it cannot
1219
+ keep whole it leaves as it is, and says so.
1220
+ - **It is the clients' file.** The kernel never reads it, and `tui.json`
1221
+ does not hold it.
1222
+ - **Your own keys still win, row by row.** A key you give an action in
1223
+ `tui.json`'s `keys` is not bound as a chord, and an action you rebind in
1224
+ the Desktop's shortcuts editor keeps your key in either family; the
1225
+ editor shows a clash with a key the option takes.
1226
+ - **In `oats tui` the option needs the kitty keyboard protocol**
1227
+ ([Chords](#chords)). Without it a Ctrl+Shift letter is the Ctrl letter,
1228
+ so the TUI binds none: only the Alt+Shift arrows are chords, and the
1229
+ leader does the rest.
1230
+ - **The help says which family is in force.** In `oats tui` the help (`?`)
1231
+ opens its chords with a line: `Shortcuts: Ctrl+Alt. For Ctrl+Shift (foot,
1232
+ Alacritty), set "chords": "ctrl+shift" in keys.json and restart.`, or
1233
+ `Shortcuts: Ctrl+Shift, from keys.json.`, or, in a terminal that does not
1234
+ confirm the protocol, `Shortcuts: Ctrl+Shift, from keys.json, but this
1235
+ terminal does not confirm the kitty keyboard protocol: use the leader.`
1236
+ The Desktop's Shortcuts page shows the choice, `oats tui uses it from its
1237
+ next start.` under it, and the same note when the file was not taken.
1238
+
1239
+ ### What the option takes from an agent
1240
+
1241
+ With the option on, both clients take the seven Ctrl+Shift chords from
1242
+ every focus, an agent's terminal included: the agent never gets them.
1243
+
1244
+ - **Of the agents' own keys, that is one:** pi's Ctrl+Shift+P (previous
1245
+ model, [pi's keys](https://github.com/earendil-works/pi/blob/26293e74f664c2cfb731b22a653cccf852830e00/packages/coding-agent/docs/keybindings.md#L154))
1246
+ spawns an agent instead. No other Ctrl+Shift key of Claude Code, Codex or
1247
+ pi is among the seven.
1248
+ - **The plain Ctrl letters stay the agent's:** `Ctrl+K`, `Ctrl+P`,
1249
+ `Ctrl+W` and the rest.
1250
+ - **A Ctrl+Shift chord is only ever the protocol's report of it,** with
1251
+ Shift in it. Without the protocol a terminal sends Ctrl+Shift+D as
1252
+ `Ctrl+D` (end of input) and Ctrl+Shift+M as `Enter`; those stay the
1253
+ agent's, and the list's.
1254
+ - **IBus 1.5.24 and older** opens its emoji picker on Ctrl+Shift+E
1255
+ ([its setting](https://github.com/ibus/ibus/blob/1.5.24/data/dconf/org.freedesktop.ibus.gschema.xml#L186);
1256
+ a newer IBus may keep an old setting) before either client sees it. There
1257
+ the leader then `|` splits side by side.
1258
+
1259
+ ### In the list
1260
+
1043
1261
  | Key | Does |
1044
1262
  |---|---|
1045
1263
  | `Up` `k`, `Down` `j` | move the selection; with the detail focused, scroll it |
@@ -1060,9 +1278,9 @@ The line after leaving says so and names `oats status` to see it.
1060
1278
  | `c` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
1061
1279
  | `[`, `]` | in the Instances view, shows the tab before or after the shown one |
1062
1280
  | `\|`, `-` | in the Instances view, [splits](#splits) the panel side by side or one above the other |
1063
- | `Alt+O` (`Ctrl+\` on macOS) | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
1281
+ | `Ctrl+X` | [the leader](#the-leader), from every focus ([`tui.json`](#change-the-keys-tuijson) can name another key) |
1064
1282
  | `Ctrl+K` | opens [the palette](#the-palette); `Ctrl+K` again closes it |
1065
- | `Ctrl+Shift+K`, `Ctrl+Tab` and the other [chords](#chords) | where your terminal sends them, what the leader then a key does, from every focus |
1283
+ | `Ctrl+Alt+K`, `Alt+Shift+Up` and the other [chords](#chords) (`Ctrl+Shift+K` and the rest [with the option](#switch-to-ctrlshift)) | what the leader then a key does, from every focus; the Ctrl+Alt and Ctrl+Shift ones where your terminal sends them. While [the palette](#the-palette) is open, `Alt+Shift+Up` and `Alt+Shift+Down` are its own |
1066
1284
  | `X`, `D`, `S`, `R` | stop, retire, start, restart the selected agent, [after a confirmation](#stopping-starting-restarting-and-retiring) |
1067
1285
  | `n` | [spawns an agent](#spawning-an-agent): the soul picker, then the preview |
1068
1286
  | `N` | spawns another of the selected instance's soul: its preview |
@@ -1084,30 +1302,37 @@ instance can always be read, however many they are. The selection stays
1084
1302
  where it is, and the list returns to it at the next key that moves it.
1085
1303
 
1086
1304
  The help screen is generated from the table the program acts on, so it
1087
- always lists the keys that work, the leader's among them, the chords while
1088
- your terminal sends them, the palette's and the spawn prompt's, with the
1305
+ always lists the keys that work, the leader's among them, the
1306
+ [chords](#chords) (first of all while your terminal confirms the kitty
1307
+ keyboard protocol), the palette's and the spawn prompt's, with the
1089
1308
  marks and with what this version does not do. Its top row has the time of the read and the count of withheld rows
1090
1309
  ([What it shows](#what-it-shows)). The movement keys scroll it. While
1091
- a terminal has the focus the table's keys are the agent's: the leader alone
1092
- is the TUI's, with the chords while your terminal sends them.
1310
+ a terminal has the focus the table's keys are the agent's: the leader and
1311
+ the chords alone are the TUI's.
1093
1312
 
1094
1313
  ### The leader
1095
1314
 
1096
1315
  Every action is reached by keys from every focus, a terminal's too: the
1097
1316
  leader (tui.json's `open.detachKey`), then one plain key. The leader is
1098
- `Alt+O` on Linux and Windows and `Ctrl+\` on macOS, unless
1099
- [`tui.json`](#change-the-keys-tuijson) names another key, `C-\` among
1100
- them. `Alt+O` is reached with one hand on every keyboard layout, where
1101
- `Ctrl+\` is a stretch on most and needs AltGr on many. macOS keeps
1102
- `Ctrl+\` because its terminals type `ø` for Option+O unless they are set
1103
- to use Option as Meta.
1317
+ `Ctrl+X` on every platform, as in OATS Desktop (where, on Linux and
1318
+ Windows, `Ctrl+X` stays Cut in a text field), unless
1319
+ [`tui.json`](#change-the-keys-tuijson) names another key: `M-o` names
1320
+ `Alt+O` and `C-\` names `Ctrl+\`, the leaders of earlier versions on
1321
+ Linux and Windows and on macOS. `Ctrl+X` is Emacs' prefix key: the same
1322
+ key on every platform and keyboard layout, and one byte in every terminal
1323
+ without the kitty keyboard protocol, so it needs neither the protocol nor
1324
+ any timing (below). Its cost is the programs
1325
+ that read `Ctrl+X` themselves, which take the leader twice (the
1326
+ leader again types it into the terminal): in the shell `Ctrl+X Ctrl+E`,
1327
+ which edits the command line in your editor, is `Ctrl+X` twice, then
1328
+ `Ctrl+E`, and nano exits with `Ctrl+X` twice.
1104
1329
 
1105
1330
  | The leader, then | Does |
1106
1331
  |---|---|
1107
1332
  | `k` or `Space` | opens [the palette](#the-palette) |
1108
1333
  | `1`, `2`, `3` | the Instances, Souls and Capabilities views |
1109
1334
  | `Up`, `Down` | opens the terminal of the instance before or after, in the list as it is drawn, the focus in it: from the shown terminal's instance, or from the selection when none is open. It shows the instance's tab when it has one, else opens a new [tab](#tabs). Rows that cannot be opened are passed over, and the list does not wrap |
1110
- | `Left`, `Right` | shows the tab before or after the shown one; the strip does not wrap, and the focus stays where it was |
1335
+ | `Left`, `Right` | shows the tab before or after the shown one; the tab bar does not wrap, and the focus stays where it was |
1111
1336
  | `z` | zooms the shown terminal in or out; with the list focused, gives it the focus and the whole screen |
1112
1337
  | `w` | closes the shown terminal's tab and shows the tab beside it; the agent keeps running |
1113
1338
  | `\|`, `-` | [splits](#splits) the panel side by side or one above the other |
@@ -1123,7 +1348,7 @@ to use Option as Meta.
1123
1348
  | the leader again | types the leader into the terminal that has the focus, which keeps it; with the list focused, only closes the hint |
1124
1349
 
1125
1350
  - **While the leader waits** for its key the cheat sheet's rows are its
1126
- hint: `Alt+O then`, then a row per key, `Esc the list` last. It names
1351
+ hint: `Ctrl+X then`, then a row per key, `Esc the list` last. It names
1127
1352
  these keys but `n` and `N` (`z` and `w` only while a terminal is open,
1128
1353
  `Left` and `Right` only with two tabs or more, `|` and `-` while the
1129
1354
  panel has one group, `Tab` with two, then `m` while the focused group
@@ -1137,15 +1362,25 @@ to use Option as Meta.
1137
1362
  read, so a paste can never run a command. In a terminal the bytes before
1138
1363
  the leader in that read still go to the agent. A leader inside a
1139
1364
  bracketed paste is pasted text.
1140
- - **In a terminal `Alt+O` is one keypress only.** A terminal sends `Alt+O`
1141
- as `Esc` then `o`. Those bytes count as the leader when they arrive in
1142
- one read, or split across reads within 10 ms. An `Esc` then `o` typed as
1143
- two keys reaches the agent unchanged: in vim that is "leave insert mode,
1144
- open a line". Over a slow link two keys typed apart can arrive in one
1145
- read and act as the leader, and one `Alt+O` can arrive split and reach
1146
- the agent as `Esc` and `o`. Under the kitty keyboard protocol
1147
- ([Chords](#chords)) there is no timing: `Alt+O` is one sequence and `Esc`
1148
- another, so each is told exactly, in a terminal and in the list.
1365
+ - **`Ctrl+X` is one byte.** Without the kitty keyboard protocol
1366
+ ([Chords](#chords)) every terminal sends it as `0x18`, which no read
1367
+ splits and nothing has to time; under the protocol it is `CSI 120;5u`,
1368
+ which the TUI reads as `Ctrl+X` too. `Ctrl+Shift+X` and `Ctrl+Alt+X` are
1369
+ not the leader under the protocol: each is a key of its own, which
1370
+ nothing binds, and in a terminal it reaches the agent as the bytes it
1371
+ sends without the protocol. Without it most terminals send `0x18` for
1372
+ `Ctrl+Shift+X` as for `Ctrl+X`, so there it is the leader. In a terminal
1373
+ `Esc` then `0x18` in one read is `Ctrl+Alt+X`, and goes to the agent.
1374
+ - **An Alt leader is one keypress only.** A leader `tui.json` names with
1375
+ `M-`, such as `M-o` (`Alt+O`), is sent by a terminal as `Esc` then `o`.
1376
+ Those bytes count as the leader when they arrive in one read, or split
1377
+ across reads within 10 ms. An `Esc` then `o` typed as two keys reaches
1378
+ the agent unchanged: in vim that is "leave insert mode, open a line".
1379
+ Over a slow link two keys typed apart can arrive in one read and act as
1380
+ the leader, and one `Alt+O` can arrive split and reach the agent as `Esc`
1381
+ and `o`. Under the kitty keyboard protocol there is no timing: `Alt+O` is
1382
+ one sequence and `Esc` another, so each is told exactly, in a terminal
1383
+ and in the list.
1149
1384
  - **In the list no leader is needed:** the plain keys work as they always
1150
1385
  have, and the leader works there too.
1151
1386
  - **What was open under it is settled first,** from whatever view: a
@@ -1159,47 +1394,80 @@ to use Option as Meta.
1159
1394
 
1160
1395
  ### Chords
1161
1396
 
1162
- Where your terminal lets them through, the OATS Desktop's Ctrl+Shift chords
1163
- work in `oats tui` too, as extras: each does what the leader then a key
1164
- does, from every focus, a terminal's too, and never reaches the agent. The
1165
- leader stays the key that always works, and the cheat sheet does not name
1166
- the chords.
1167
-
1168
- | Chord (Linux and Windows) | Does: the leader then |
1169
- |---|---|
1170
- | `Ctrl+Shift+K` | `k`, the palette |
1171
- | `Ctrl+Shift+P` | `n`, spawn an agent |
1172
- | `Ctrl+Tab`, `Ctrl+Shift+Tab` | `Right`, `Left`: the next or the previous tab |
1173
- | `Ctrl+Shift+W` | `w`, close the shown terminal |
1174
- | `Ctrl+Shift+F` | `/`, the filter |
1175
- | `Ctrl+Shift+E`, `Ctrl+Shift+O` | `\|`, `-`: split right, split down |
1176
-
1177
- On macOS the Desktop's chords hold ⌘, which a terminal never passes to a
1178
- program: there `Ctrl+Tab` and `Ctrl+Shift+Tab` are the only chords. The
1179
- chords are the Desktop's (`CHORDS` in `packages/client/keymap.mjs`), and the
1180
- TUI keeps no copy. The Desktop's Ctrl+1, Ctrl+2 and Ctrl+3 (its stages) are
1181
- its own.
1182
-
1183
- - **Only where the terminal says it can.** A terminal sends these keys apart
1184
- from `Ctrl+K`, `Ctrl+P` and the others only under the kitty keyboard
1185
- protocol. As it takes the terminal, `oats tui` asks for the protocol with
1186
- flags 1 and 4 (`CSI > 5 u`) and asks the terminal which flags it has
1187
- (`CSI ? u`). Only when the answer holds flag 1 does it read the protocol,
1188
- take the chords and list them in the help. With no answer within 2
1189
- seconds, or one without flag 1, it pops the protocol, and the rest of the
1190
- run is as without it. The answer may come split and late over a slow
1191
- link, so until it comes (at most those 2 seconds) an `Esc` pressed on its
1192
- own may wait for the next key or for the wait's end, as it may begin the
1193
- answer. foot, Ghostty, kitty, Alacritty and WezTerm answer.
1194
- GNOME Terminal and the other VTE terminals, and Terminal.app, do not:
1195
- there the chords are absent.
1196
- - **Your terminal may take some first.** foot takes Ctrl+Shift+C, V, R, N,
1197
- O, U, Z, X and Q for itself, so `Ctrl+Shift+O` never reaches `oats tui`
1198
- there. The help says so.
1397
+ A chord does in one keypress what the leader then a key does, from every
1398
+ focus, an agent's terminal too, and never reaches the agent. The OATS
1399
+ Desktop has the same chords (`CHORDS` in `packages/client/keymap.mjs`, which
1400
+ both read; the TUI keeps no copy). The leader stays the key that always
1401
+ works, and the one for help, the views and the acts (stop, restart, start,
1402
+ retire), which have no chord.
1403
+
1404
+ Every chord, in both families, with what it does and the leader's key for
1405
+ it, is in [Every action's keys](#every-actions-keys). While the palette is
1406
+ open, `Alt+Shift+Up` and `Alt+Shift+Down` move between its groups instead
1407
+ ([The palette](#the-palette)).
1408
+
1409
+ `CHORDS` also holds the Desktop's `edit-instance` (`Ctrl+Alt+R`, its name and
1410
+ colour dialog). The TUI has no such action, so it binds no key for it and
1411
+ `Ctrl+Alt+R` stays the agent's.
1412
+
1413
+ They are one family: Ctrl+Alt with a letter or a digit acts, and Alt+Shift
1414
+ with the leader's arrow moves. No terminal in the table below takes them by
1415
+ default, and no agent (Claude Code, Codex, pi) reads them. Ctrl+Shift with a
1416
+ letter, the obvious family, is mostly the terminals' own: kitty binds 22 of
1417
+ those letters, Ghostty 13, and foot, GNOME Terminal, WezTerm, Konsole and
1418
+ Windows Terminal their own. So it is the option, for the terminals that
1419
+ leave the seven letters alone ([Which family for my
1420
+ terminal](#which-family-for-my-terminal)). With the option a row's
1421
+ Ctrl+Shift key replaces its Ctrl+Alt key, which then reaches the agent as
1422
+ it would without the TUI. On macOS the TUI has no chords: the Desktop's
1423
+ hold ⌘, which a terminal never passes to a program.
1424
+
1425
+ - **The Ctrl+Alt and Ctrl+Shift chords only where the terminal says it
1426
+ can.** Without the kitty keyboard protocol a terminal sends `Ctrl+Alt+K`
1427
+ as `Esc` then `Ctrl+K`, the same bytes as those two keys typed for the
1428
+ agent, and `Ctrl+Shift+K` as `Ctrl+K`. As
1429
+ it takes the terminal, `oats tui` asks for the protocol with flags 1 and 4
1430
+ (`CSI > 5 u`) and asks the terminal which flags it has (`CSI ? u`). Only
1431
+ when the answer holds flag 1 does it read the protocol and take the
1432
+ chords of its family. With no answer within 2 seconds, or one without flag 1,
1433
+ it pops the protocol, and the rest of the run is as without it. The
1434
+ answer may come split and late over a slow link, so until it comes (at
1435
+ most those 2 seconds) an `Esc` pressed on its own may wait for the next
1436
+ key or for the wait's end, as it may begin the answer.
1437
+ - **The Alt+Shift arrows everywhere.** Each sends a sequence of its own,
1438
+ with the protocol or without it (`CSI 1;4A` for `Alt+Shift+Up`), so the
1439
+ TUI takes them in every terminal. `Ctrl+Alt+Shift` with an arrow is not
1440
+ one of them.
1441
+ - **The help and the cheat sheet lead with the chords** while the terminal
1442
+ confirms the protocol: one row per chord, then the leader and its key
1443
+ ("or `Ctrl+X` then `k`"), and the leader's own section after them. Without
1444
+ the protocol the leader leads, and only the Alt+Shift arrows are listed
1445
+ as chords. The help's chords open with the family in force
1446
+ ([Switch to Ctrl+Shift](#switch-to-ctrlshift)). The cheat sheet names chords while an agent's terminal has the
1447
+ focus; the list's names its own keys, which need no modifier.
1448
+ - **Your terminal may take some first** ([the matrix](#which-terminals-let-the-chords-through)).
1449
+ Windows Terminal takes `Ctrl+Alt+1` to `Ctrl+Alt+9` for its own tabs, and
1450
+ the Alt+Shift arrows while its panes are split. GNOME Terminal and the
1451
+ other VTE terminals, Konsole before 26.08, and WezTerm unless
1452
+ `enable_kitty_keyboard` is set have no protocol: there only the Alt+Shift
1453
+ arrows reach `oats tui`. The leader works in every terminal.
1454
+ - **A character typed with AltGr stays a character.** On Windows `AltGr` is
1455
+ `Ctrl+Alt`: on a Spanish layout `Ctrl+Alt+E` types `€` and `Ctrl+Alt+2`
1456
+ `@`, on a Polish one `Ctrl+Alt+A` types `ą`. A key that arrives as text is
1457
+ never a chord: on such a layout those chords are the layout's, and the
1458
+ leader still does what they do. On Linux and macOS `AltGr` and Option are
1459
+ keys of their own.
1199
1460
  - **Every other key reads as it does without the protocol.** `Ctrl+Shift+L`
1200
1461
  is `Ctrl+L`, `Ctrl+Enter` is `Enter`, and so on: the protocol only adds
1201
- the chords, and tells `Alt+O` from `Esc` then `o` exactly
1202
- ([The leader](#the-leader)).
1462
+ the chords of the family in force, tells an Alt leader such as `Alt+O`
1463
+ from `Esc` then `o` exactly, and tells `Ctrl+Shift+X` from the leader
1464
+ `Ctrl+X` ([The leader](#the-leader)). Under the default family the seven
1465
+ Ctrl+Shift letters of the option are such keys too: `Ctrl+Shift+D` is
1466
+ `Ctrl+D`.
1467
+ - **A Ctrl+Shift chord is read from the protocol alone,** from a report
1468
+ that holds Shift, never from the byte a terminal sends without it:
1469
+ `Ctrl+D` (end of input) and `Enter` (`Ctrl+M`) stay what they are, with
1470
+ the option on too.
1203
1471
  - **An agent gets what it gets without the protocol.** Every key typed
1204
1472
  into an agent's terminal is turned back into the bytes the same key sends
1205
1473
  without it, the legacy encoding of xterm and the terminals that follow it:
@@ -1221,22 +1489,123 @@ its own.
1221
1489
  terminal: the shell at a suspend is the only one `oats tui` ever gives
1222
1490
  it to.
1223
1491
 
1492
+ #### Which terminals let the chords through
1493
+
1494
+ Each terminal's documented default key bindings, read from its source or
1495
+ manual at the release named. `✗` is a chord the terminal takes for itself
1496
+ by default, `~` one it takes only in a state it names, `·` one it passes on.
1497
+ WT is Windows Terminal; iTerm2 and Terminal.app are on macOS, where the TUI
1498
+ has no chords (above) and the column is for reference.
1499
+
1500
+ | Chord | foot | kitty | Ghostty | Alacritty | GNOME Terminal | WezTerm | Konsole | WT | iTerm2 | Terminal.app |
1501
+ |---|---|---|---|---|---|---|---|---|---|---|
1502
+ | `Ctrl+Alt+K` `P` `O` `Z` `W` `E` `A` `F` | · | · | · | · | · | · | · | · | · | · |
1503
+ | `Ctrl+Alt+Shift+E` | · | · | · | · | · | · | · | · | · | · |
1504
+ | `Ctrl+Alt+1` to `9` | · | · | · | · | · | · | · | ✗ its tabs | · | · |
1505
+ | `Alt+Shift+` arrows | · | · | · | · | · | · | · | ~ pane resize, passed on with one pane | · | · |
1506
+ | the option's `Ctrl+Shift+K` `P` `S` `M` `W` `E` `D` | · | ✗ `K` `P` `S` `W` `E` | ✗ `P` `W` `E` | · | ✗ `W` | ✗ `K` `P` `M` `W` | ✗ all seven | ✗ `K` `P` `M` `W` `D` | – | – |
1507
+ | kitty protocol, flags 1 and 4 | yes, since 1.10.3 | yes | yes | yes, since 0.13 | no (VTE has none) | only with `enable_kitty_keyboard` | yes, since 26.08 | yes, since 1.25 | yes | no |
1508
+ | Release read | 1.28.0 | 0.49.2 | 1.3.1 | 0.17.0 | 3.60.0 (VTE 0.84.1) | 20240203 | 26.08.2 | 1.25.2733 | 3.7 | macOS 15 |
1509
+
1510
+ Where a terminal has no protocol, its cells say only what it takes: the
1511
+ chord does not reach the TUI there anyway. macOS has no Ctrl+Shift option,
1512
+ hence `–`. What the
1513
+ terminals take besides, near these chords:
1514
+
1515
+ - Konsole: `Ctrl+Alt+S`, `N`, `M`, `U`, `H`, `G`, `I`, `0`, `[`, `]`, `\`
1516
+ and `,`.
1517
+ - Windows Terminal: `Ctrl+Alt+,`, `Ctrl+Alt+Left`, and `Alt` with an arrow
1518
+ (pane focus).
1519
+ - kitty: `Ctrl+Shift+Alt+T`. Ghostty: `Ctrl+Shift+Alt+J`, and `Ctrl+Alt`
1520
+ with an arrow (split focus). WezTerm: `Ctrl+Shift+Alt` with an arrow,
1521
+ `'` and `5`.
1522
+
1523
+ The desktops' global keys come before any terminal's:
1524
+
1525
+ | Desktop (release read) | Takes, near the chords | Takes none of |
1526
+ |---|---|---|
1527
+ | GNOME 49 to 51 | `Ctrl+Alt` with an arrow (workspaces) and with `Shift` (move to a workspace), `Ctrl+Alt+Tab`, `Ctrl+Alt+Esc`, `Ctrl+Alt+Delete`, `Ctrl+Alt+F1` to `F12`, `Ctrl+Shift+Alt+R`, `Shift+Alt+Tab`; Ubuntu adds `Ctrl+Alt+T` | the chords above |
1528
+ | KDE Plasma 6.8.1 | `Ctrl+Alt+Delete`, `Ctrl+Alt+F1` to `F12`, `Alt+Shift+Tab`, `Alt+Shift+F2`; Konsole, where installed, `Ctrl+Alt+T` | the chords above |
1529
+ | Omarchy 4.0.4 (Hyprland) | `Ctrl+Alt+Delete`, `Ctrl+Alt+Tab`, `Ctrl+Alt+Shift+Tab`, `Alt+Shift+Tab` | the chords above |
1530
+
1531
+ From
1532
+ [GNOME's window manager keys](https://gitlab.gnome.org/GNOME/gsettings-desktop-schemas/-/blob/49.1/schemas/org.gnome.desktop.wm.keybindings.gschema.xml.in),
1533
+ [mutter's](https://gitlab.gnome.org/GNOME/mutter/-/blob/49.8/data/org.gnome.mutter.wayland.gschema.xml.in),
1534
+ [the shell's](https://gitlab.gnome.org/GNOME/gnome-shell/-/blob/49.10/data/org.gnome.shell.gschema.xml.in)
1535
+ and [the settings daemon's](https://gitlab.gnome.org/GNOME/gnome-settings-daemon/-/blob/49.1/data/org.gnome.settings-daemon.plugins.media-keys.gschema.xml.in);
1536
+ [KWin's](https://invent.kde.org/plasma/kwin/-/blob/v6.8.1/src/tabbox/tabbox.cpp#L330-L335),
1537
+ [the session's](https://invent.kde.org/plasma/plasma-workspace/-/blob/v6.8.1/startkde/session-shortcuts/main.cpp#L40)
1538
+ and [KRunner's](https://invent.kde.org/plasma/plasma-workspace/-/blob/v6.8.1/krunner/org.kde.krunner.desktop.cmake#L135);
1539
+ and [Omarchy's](https://github.com/basecamp/omarchy/blob/v4.0.4/default/hypr/bindings/tiling.lua).
1540
+
1541
+ Sources:
1542
+ [foot](https://codeberg.org/dnkl/foot/src/tag/1.28.0/config.c#L3362-L3445)
1543
+ ([protocol](https://codeberg.org/dnkl/foot/src/tag/1.28.0/CHANGELOG.md#L2222-L2245)),
1544
+ [kitty](https://github.com/kovidgoyal/kitty/blob/v0.49.2/kitty/options/definition.py#L3650-L4711)
1545
+ ([protocol](https://github.com/kovidgoyal/kitty/blob/v0.49.2/docs/keyboard-protocol.rst#L302-L309)),
1546
+ [Ghostty](https://github.com/ghostty-org/ghostty/blob/v1.3.1/src/config/Config.zig#L6392-L7146)
1547
+ ([protocol](https://github.com/ghostty-org/ghostty/blob/v1.3.1/src/terminal/kitty/key.zig#L79-L84)),
1548
+ [Alacritty](https://github.com/alacritty/alacritty/blob/v0.17.0/alacritty/src/config/bindings.rs#L430-L562)
1549
+ ([protocol](https://github.com/alacritty/alacritty/blob/v0.17.0/CHANGELOG.md#L243)),
1550
+ [GNOME Terminal](https://gitlab.gnome.org/GNOME/gnome-terminal/-/blob/3.60.0/src/org.gnome.Terminal.gschema.xml#L362-L631)
1551
+ ([VTE has no protocol](https://gitlab.gnome.org/GNOME/vte/-/work_items/2601)),
1552
+ [WezTerm](https://wezterm.org/config/default-keys.html)
1553
+ (and [commands.rs](https://github.com/wezterm/wezterm/blob/20240203-110809-5046fc22/wezterm-gui/src/commands.rs#L109-L140),
1554
+ which gives each ⌘ default a Ctrl+Shift twin;
1555
+ [protocol](https://wezterm.org/config/lua/config/enable_kitty_keyboard.html)),
1556
+ [Konsole](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/ViewManager.cpp#L120-L393)
1557
+ (and [SessionController.cpp](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/session/SessionController.cpp#L660-L955),
1558
+ [MainWindow.cpp](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/MainWindow.cpp#L430-L470),
1559
+ where `ACCEL` is Ctrl+Shift ([Shortcut_p.h](https://invent.kde.org/utilities/konsole/-/blob/v26.08.2/src/Shortcut_p.h#L17-L25)),
1560
+ and KDE's Save As, Ctrl+Shift+S;
1561
+ [protocol](https://invent.kde.org/utilities/konsole/-/commit/1983d2b4735d6b61b74cf85854acc1cb4d2445d5)),
1562
+ [Windows Terminal](https://github.com/microsoft/terminal/blob/v1.25.2733.0/src/cascadia/TerminalSettingsModel/defaults.json#L721-L803)
1563
+ ([protocol](https://github.com/microsoft/terminal/releases/tag/v1.25.622.0)),
1564
+ [iTerm2](https://github.com/gnachman/iTerm2/blob/beb7cfbffeb3ae482042b08a8dd2590cd2cf4ee5/plists/DefaultGlobalKeyMap.plist)
1565
+ ([keys](https://iterm2.com/documentation-preferences-keys.html)),
1566
+ [Terminal.app](https://support.apple.com/guide/terminal/keyboard-shortcuts-trmlshtcts/mac).
1567
+ The agents' keys:
1568
+ [Claude Code](https://code.claude.com/docs/en/keybindings),
1569
+ [Codex](https://github.com/openai/codex/blob/e1b9c9457ceca75a99b034a5df39ac48c3998d15/codex-rs/tui/src/keymap.rs#L1673-L2003),
1570
+ [pi](https://github.com/earendil-works/pi/blob/26293e74f664c2cfb731b22a653cccf852830e00/packages/coding-agent/docs/keybindings.md).
1571
+ Of the shells' keys, bash's readline binds `Ctrl+Alt+E` and `Ctrl+Alt+F`
1572
+ (expand the line, a word forward); under the protocol the TUI takes them
1573
+ from an agent's line editor, which no agent above binds them in.
1574
+
1224
1575
  ### The palette
1225
1576
 
1226
1577
  The leader then `k` (or `Space`), or `Ctrl+K` in the list, opens one input
1227
1578
  over a list, as the OATS Desktop's ⌘K does. From 80 columns it covers the
1228
1579
  main area and the sidebar stays beside it, its cheat sheet naming the
1229
- palette's keys (`Enter run`, `Up/Down move`, `Esc close`); under 80 columns
1230
- it covers the whole screen, with those keys on its first row. While it is
1231
- open no terminal is drawn and the TUI reads the keys. The help lists its
1232
- keys under The palette.
1233
-
1234
- - **It lists, in this order:** the instances that can be opened, the most
1235
- recently opened or shown in this run first (when the first is the shown tab's,
1236
- the second is selected as it opens), then the list's order, each with its
1237
- state mark, its name, for another machine `on <machine>`, and, dim, its
1238
- siblings as the detail names them (`sibling of <names>`), which are cut
1239
- first when the row is short and are never matched by a query; the souls
1580
+ palette's keys (`Enter run`, `Up/Down move`, `Esc close`, then
1581
+ `Alt+Shift+Up/Down group`, which macOS has not); under 80 columns it covers
1582
+ the whole screen, with those keys on its first row, as many as fit (at 60
1583
+ columns `group` gives way). While it is open no terminal is drawn and the
1584
+ TUI reads the keys. The help lists its keys under The palette.
1585
+
1586
+ - **It lists, in this order:** the instances that can be opened, in groups;
1587
+ then the souls, the capabilities, the views, the acts and the commands,
1588
+ one group each.
1589
+ - **The instances are grouped as the sidebar groups them:** a cluster under
1590
+ its name, and a run of single instances under `independent`. Where the
1591
+ view has several deployments, each group is one deployment's, and its
1592
+ label names the machine first (`<machine> · <group>`).
1593
+ - **Each instance group has a label row:** its label, dim, before its rows.
1594
+ It is never selected: `Up`/`Down` and `PageUp`/`PageDown` pass over it,
1595
+ and the palette opens on the first row under it. A group with no instance
1596
+ that can be opened is not listed.
1597
+ - **The group last used comes first,** as in the Desktop's palette, and so
1598
+ does the cluster, the root and the child: the one with the instance opened
1599
+ or shown most recently in this run first, then the list's order (the
1600
+ sidebar keeps its own order). When the first instance is the shown tab's,
1601
+ the palette opens on the instance shown before it, wherever its group puts
1602
+ it (the second instance, when none was shown before): `Enter` goes back to
1603
+ that terminal.
1604
+ - **An instance's row** has its state mark, its name, for another machine
1605
+ `on <machine>`, and, dim, its siblings as the detail names them
1606
+ (`sibling of <names>`), which are cut first when the row is short and are
1607
+ never matched by a query.
1608
+ - **The other groups:** the souls
1240
1609
  of the open workspace, once they were read (by [the Souls
1241
1610
  view](#the-souls-view), the Capabilities view or a spawn), and choosing
1242
1611
  one shows the Souls view with it selected; its capabilities, once [the
@@ -1249,12 +1618,25 @@ keys under The palette.
1249
1618
  catalog lists its soul; then Spawn an agent, Workspaces, Refresh and Help, and [the split's](#splits)
1250
1619
  rows where each applies.
1251
1620
  Each row says at its right edge what kind it is: `instance`, `soul`,
1252
- `capability`, `view`, `act` or `command`.
1253
- - **Typing filters it** with the Desktop's subsequence match, a prefix
1254
- first: each kind keeps the rows that match, the best first.
1621
+ `capability`, `view`, `act` or `command`. A label row says none.
1622
+ - **Typing filters it** with the Desktop's subsequence match. An instance
1623
+ group keeps the rows that match, in its own order, and a group with none
1624
+ loses its label row. Each other group keeps the rows that match, the best
1625
+ first, a prefix first.
1255
1626
  `Backspace` removes a character, and a paste adds its first line.
1256
1627
  `Up`/`Down` (and `PageUp`/`PageDown`) move, `Enter` runs the selected
1257
1628
  row, `Esc` closes it.
1629
+ - **`Alt+Shift+Down` goes to the next group, `Alt+Shift+Up` to the one
1630
+ before:** to its first row. Past the last group it wraps to the first,
1631
+ and before the first to the last; with one group, both go to its first
1632
+ row. While the palette is open these keys are its own: they win over the
1633
+ chords `Alt+Shift+Up` and `Alt+Shift+Down` ([Chords](#chords)), so they
1634
+ open no agent and leave the palette open, with or without the kitty
1635
+ keyboard protocol. The leader then `Up` or `Down` still opens one. The
1636
+ Desktop's palette has the same pair (`PALETTE_KEYS` in
1637
+ `packages/client/keymap.mjs`, which both read).
1638
+ - **On macOS there is no group key:** the Desktop's hold `⌘`, which a
1639
+ terminal never passes to a program.
1258
1640
  - **Running a row** settles what was open under the palette, as the leader
1259
1641
  does: an instance shows its tab, or opens its terminal in a new one, in
1260
1642
  the Instances view, the focus in it ([Tabs](#tabs)); an act opens its
@@ -1292,7 +1674,9 @@ kernel's own files, so it is `$OATS_HOME_DIR/config/tui.json` when
1292
1674
  `OATS_HOME_DIR` is set (the same rule as this computer's list of
1293
1675
  deployments). `XDG_CONFIG_HOME` is not read for it. It never writes the file,
1294
1676
  except to [move it](#the-move-from-configoats) from where earlier versions
1295
- read it. With no file the keys are the ones above.
1677
+ read it. With no file the keys are the ones above. Which chord family it
1678
+ binds is not here: it is `keys.json`, beside it, which the Desktop shares
1679
+ ([Switch to Ctrl+Shift](#switch-to-ctrlshift)).
1296
1680
 
1297
1681
  ```json
1298
1682
  { "keys": { "quit": ["q"], "refresh": ["r", "f5"], "suspend": [] }, "ascii": false, "open": { "detachKey": "F12" } }
@@ -1300,7 +1684,8 @@ read it. With no file the keys are the ones above.
1300
1684
 
1301
1685
  - `keys.<action>` is the list of keys of that action. It **replaces** the
1302
1686
  action's keys; an empty list leaves the action with no key. An action you
1303
- do not name keeps its keys.
1687
+ do not name keeps its keys. A [chord](#chords) whose key you give an
1688
+ action here is not bound: your key wins, row by row, in either family.
1304
1689
  - The actions are `up`, `down`, `top`, `bottom`, `page-up`, `page-down`,
1305
1690
  `collapse`, `expand`, `detail`, `filter`, `refresh`, `instances`,
1306
1691
  `souls`, `capabilities`, `workspaces`, `palette`, `open`, `soul-instances`, `zoom`, `close-terminal`,
@@ -1325,14 +1710,16 @@ read it. With no file the keys are the ones above.
1325
1710
  keys of their own.
1326
1711
  - `ascii: true` is `--ascii`.
1327
1712
  - `open.detachKey` is **[the leader](#the-leader)**. When you name none
1328
- it is `M-o` (`Alt+O`) on Linux and Windows and `C-\` (`Ctrl+\`) on
1329
- macOS; `C-\` stays a key you can name on every platform. It is
1713
+ it is `C-x` (`Ctrl+X`) on every platform. `M-o` (`Alt+O`) and `C-\`
1714
+ (`Ctrl+\`), the defaults of earlier versions, are keys you can name, as
1715
+ in `"open": {"detachKey": "M-o"}`; a `detachKey` your file names is
1716
+ kept as it is. It is
1330
1717
  `oats tui`'s own: it never reaches the kernel, and it reaches the agent
1331
1718
  only when you press it twice in the agent's terminal.
1332
1719
  It is read as a key wherever the TUI reads keys, so it may not be a key
1333
1720
  an action has: `C-l` is `redraw`'s `Ctrl+L`, `C-k` the palette's
1334
1721
  `Ctrl+K`, `C-j` is `Enter`. That holds for the default too: a file that
1335
- gives `alt+o` to an action on Linux or Windows names another leader as
1722
+ gives `ctrl+x` to an action names another leader as
1336
1723
  well. It is one of these, written as shown: `C-` with a letter but `h`, `i` and `m` (a
1337
1724
  terminal sends those as `Backspace`, `Tab` and `Enter`) or one of `\`
1338
1725
  `]` `^` `_`; `M-` with a lower-case letter or a digit; or `F1` to `F12`,
@@ -1462,9 +1849,9 @@ with the Desktop (`packages/client/`).
1462
1849
  asked for one, and no other machine is shown.
1463
1850
  - **This computer's list of deployments is the kernel's**, read and changed
1464
1851
  through the same kernel, with 15 seconds and 4 MiB each, from `/`:
1465
- - `oats deployments --json`, at a start outside every deployment with no
1466
- `--dir` (before the terminal is taken), when the switcher opens, on `r`
1467
- in it and after a Remove. One runs at a time: one asked for while one is
1852
+ - `oats deployments --json`, at the start (outside every deployment with
1853
+ no `--dir`, before the terminal is taken), when the switcher opens, on
1854
+ `r` in it and after a Remove. One runs at a time: one asked for while one is
1468
1855
  on its way runs after it, however many times it was asked, and the
1469
1856
  answer taken is that later one's.
1470
1857
  - `oats deployments add <path> --via tui --json`, once a run, for the
@@ -1473,9 +1860,16 @@ with the Desktop (`packages/client/`).
1473
1860
 
1474
1861
  An add and a remove are changes: `oats tui` never ends one, and one still
1475
1862
  running as it leaves is named in one line after the screen is left.
1863
+ - **The workspace of each row of that list the run has not opened** is
1864
+ one more read, `oats status --dir <path> --json` with `--max-age 60`, by
1865
+ the same kernel ([the switcher](#the-switcher)): at the start, when the
1866
+ switcher opens and on `r` in it, one at a time, 30 seconds each and 60
1867
+ seconds for all of them; never from the reads' cadence above. A kernel
1868
+ that reports no workspace identities is not asked.
1476
1869
  - **One look at the file system serves the switcher**, and it reads no
1477
- file's content: when a row of the list is opened, that one directory is
1478
- asked for a regular `oats-local.yaml`.
1870
+ file's content: when a row of the list, or a workspace with such a row,
1871
+ is opened, each of those directories is asked for a regular
1872
+ `oats-local.yaml`.
1479
1873
  - **Opening an agent runs one more command,** `oats session attach --home
1480
1874
  <home>`, by the same kernel, in a pane of the run's private tmux server
1481
1875
  ([above](#open-an-agents-terminal)), with no key of its own. For an agent