@awebai/oats 0.67.1 → 0.68.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 (64) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +316 -63
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/release-notes/v0.68.1.md +102 -0
  17. package/docs/servers.md +6 -1
  18. package/docs/souls-and-instances.md +38 -3
  19. package/docs/tui.md +663 -243
  20. package/docs/upgrading.md +66 -6
  21. package/docs/workspaces.md +2 -2
  22. package/lib/capability-contract.mjs +6 -5
  23. package/lib/core.mjs +222 -38
  24. package/lib/instance-events.mjs +1 -1
  25. package/lib/instance-resolution.mjs +5 -5
  26. package/lib/instance-upgrade.mjs +1445 -0
  27. package/lib/materialize.mjs +225 -78
  28. package/lib/servers.mjs +11 -7
  29. package/lib/upgrade-state.mjs +101 -0
  30. package/lib/workspace.mjs +4 -1
  31. package/lib/worktree.mjs +103 -12
  32. package/package-catalog.json +5 -4
  33. package/package.json +1 -1
  34. package/packages/client/cli-adapter.mjs +15 -1
  35. package/packages/client/cli-locator.mjs +2 -2
  36. package/packages/client/deployment-panel.mjs +6 -2
  37. package/packages/client/instance-display-name.mjs +18 -0
  38. package/packages/client/keymap.mjs +89 -45
  39. package/packages/client/keys-file.mjs +9 -5
  40. package/packages/client/panel-views.mjs +16 -3
  41. package/packages/client/spawn-naming.mjs +7 -6
  42. package/packages/client/spawn-preview-cli.mjs +37 -1
  43. package/packages/client/spawn-preview-contract.mjs +35 -0
  44. package/packages/client/spawn-preview.mjs +35 -2
  45. package/packages/client/team-members.mjs +4 -1
  46. package/packages/client/workspace-step.mjs +25 -0
  47. package/packages/tui/README.md +5 -5
  48. package/packages/tui/lib/actions.mjs +51 -27
  49. package/packages/tui/lib/client.mjs +4 -2
  50. package/packages/tui/lib/config.mjs +4 -4
  51. package/packages/tui/lib/main.mjs +27 -13
  52. package/packages/tui/lib/model.mjs +143 -21
  53. package/packages/tui/lib/store.mjs +343 -68
  54. package/packages/tui/lib/term/keys.mjs +5 -3
  55. package/packages/tui/lib/term/kitty.mjs +28 -10
  56. package/packages/tui/lib/term/screen.mjs +15 -6
  57. package/packages/tui/lib/term/through.mjs +33 -28
  58. package/packages/tui/lib/views/capabilities.mjs +6 -6
  59. package/packages/tui/lib/views/frame.mjs +88 -109
  60. package/packages/tui/lib/views/help.mjs +57 -35
  61. package/packages/tui/lib/views/instances.mjs +48 -30
  62. package/packages/tui/lib/views/souls.mjs +9 -8
  63. package/packages/tui/lib/views/workspaces.mjs +55 -0
  64. package/skills/oats-getting-started/SKILL.md +92 -43
package/docs/desktop.md CHANGED
@@ -112,6 +112,23 @@ PATH, not the Desktop's. A tmux server that was already running keeps its own
112
112
  environment; restart it if its sessions should get the new PATH, which ends
113
113
  its sessions: `tmux -L oats kill-server` for the OATS tmux server, where instances run, and `tmux kill-server` for your default server, where an instance started by an earlier kernel may still be.
114
114
 
115
+ ## Updating
116
+
117
+ Installing a new version doesn't change a Desktop that is already running: an
118
+ AppImage runs from its own mount, and a DEB or another copy of the app hands
119
+ its launch to the running app, which opens or focuses a window and carries on
120
+ in the old version. To switch, quit Desktop (close every window) and open it
121
+ again.
122
+
123
+ From this version on, a launch of a different version says so: the running
124
+ Desktop opens or focuses the window as usual, then asks whether to **Restart
125
+ into** the version you opened, naming the file it starts, or **Keep** the
126
+ running one. Restarting closes Desktop's windows and starts the version you
127
+ opened; your agents keep running in their sessions. When the copy you opened can't be found again (its file was
128
+ moved or removed), the message only tells you to quit and open it again. Both
129
+ copies must be this version or later: a running Desktop older than this one
130
+ can't tell you, and neither can a launch of one.
131
+
115
132
  ## Opening a workspace
116
133
 
117
134
  The app opens the workspaces you had open, plus the directory it was
@@ -119,17 +136,12 @@ launched with (`--dir`, or the folder it was started from) when that is an
119
136
  OATS deployment — the directory (the operator's choice) holding
120
137
  `oats-local.yaml` and `agents/`. A folder that is not a deployment is never
121
138
  opened: started from Finder, with nothing open to restore, the window shows
122
- the workspace switcher instead. It lists the deployments on this computer
123
- under **On this computer**: those on this computer's deployments list
124
- (`oats deployments`, see [Workspaces](workspaces.md)) and a saved one,
125
- that are not open. Click one to open it in this window. A deployment the list
126
- holds but that can't be opened says why: missing (the folder is gone, or its
127
- volume isn't mounted), not a deployment any more, or can't be checked. **Remove**
128
- beside a row takes it off the list (Right Arrow, then Enter, from the
129
- keyboard); nothing on disk changes. With an oats that has no such list, the
130
- switcher shows the saved deployments and says "This oats can't list this
131
- computer's deployments. Update oats." **Add local workspace… → Browse**
132
- points it at any other deployment.
139
+ "Choose a workspace" and opens **Add local workspace…** (the **+** at the top
140
+ of the sidebar). The dialog lists the deployments on this computer that are
141
+ not open: those on this computer's deployments list (`oats deployments`, see
142
+ [Workspaces](workspaces.md)) and a saved one. Click one, or press Enter on it,
143
+ to add it and open it in this window. **Browse…** points it at any other
144
+ deployment.
133
145
  A picked folder without `oats-local.yaml` is offered onboarding instead. The
134
146
  Desktop never parses the deployment: its members, lock state and header come
135
147
  from `oats workspace status`, and its instances from the deployment's one
@@ -148,17 +160,19 @@ Launch flags for scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
148
160
  Each workspace has at most one window, titled with the workspace's name (a
149
161
  workspace on a server: `name — server`).
150
162
 
151
- - **Switching.** Choosing a workspace in the switcher shows it in the current
152
- window. If that workspace already has a window, that window comes to the
153
- front instead and the current one doesn't change.
154
- - **Open in new window.** Each workspace in the switcher has an **Open in new
155
- window** button beside it. From the keyboard: Right Arrow on the workspace,
156
- then Enter, or ⌘Enter on macOS / Ctrl+Enter on Linux and Windows. A
157
- workspace that already has a window is brought to the front.
163
+ - **Switching.** Picking a workspace in the sidebar's list shows it in the
164
+ current window. If another window shows it, it moves to this window, and the
165
+ other window shows another workspace ([A workspace another window
166
+ shows](#a-workspace-another-window-shows)). No other window comes to the
167
+ front.
168
+ - **Open in new window.** A workspace's row in the list opens it in its own
169
+ window from its context menu (a right-click, or Shift+F10 or the Menu key),
170
+ or with ⌘Enter on macOS / Ctrl+Enter on Linux and Windows. A workspace that
171
+ already has a window is brought to the front.
158
172
  - **New Window.** On macOS, **File → New Window** (⌘⇧N); everywhere,
159
173
  **Window: new window** in the command palette. The new window has no
160
- workspace yet: it opens the switcher, and shows "Choose a workspace" until
161
- you pick one. It reads nothing until then.
174
+ workspace yet: it shows "Choose a workspace" and focuses the list of
175
+ workspaces until you pick one. It reads nothing until then.
162
176
  - **Moving between windows.** On macOS, ⌘\` cycles the app's windows, and the
163
177
  **Window** menu lists them.
164
178
  - **Restore.** Quitting and relaunching brings every window back with its
@@ -169,12 +183,14 @@ workspace on a server: `name — server`).
169
183
  - **Launching again.** Running the app again (`open -a "OATS Desktop" --args
170
184
  --dir <deployment>`, or from inside a deployment) adds that deployment if
171
185
  needed and brings its window to the front, opening one if it has none. Any
172
- other launch brings the most recently used window to the front.
186
+ other launch brings the most recently used window to the front. A launch of
187
+ another version also offers to restart into it ([Updating](#updating)).
173
188
  - **Closing.** Closing a window leaves the other windows, and their
174
189
  terminals, running. Closing the last window quits the app.
175
190
  - Tabs belong to their window: a workspace's terminals and tabs stay in the
176
191
  window they were opened in, and switching that window back to the
177
- workspace brings them back.
192
+ workspace brings them back. A window whose workspace another window takes
193
+ over closes its tabs of that workspace.
178
194
  - A tab's terminal ends ("session ended") when its instance's tmux window
179
195
  goes, whatever your tmux `detach-on-destroy` setting: a tab never shows
180
196
  another instance's terminal. Stopping an instance leaves its tab open.
@@ -186,10 +202,150 @@ workspace on a server: `name — server`).
186
202
  An instance respawned under the same name is a new instance: opening it
187
203
  opens a new tab.
188
204
 
205
+ ## Workspaces
206
+
207
+ The sidebar, top to bottom: the **Workspace** heading, with **Show only the
208
+ current workspace** and **Add local workspace…** at its end, over the list of
209
+ workspaces; a thin line; the two main views, **Workspace overview** and
210
+ **Automations**, one under the other; another line; **Instances**, a heading
211
+ with the running count over the list of instances; and, over a line, the
212
+ foot, one bar: the OATS mark and the sidebar toggle (**Hide the sidebar**)
213
+ after it, and at the bar's right **Spawn instance**, its words alone (a ground
214
+ only on hover), which
215
+ opens Quick Open (⌘P / Alt+P, named in its tooltip) to pick a soul and then
216
+ the spawn dialog, and the settings cog, whose menu holds **Theme…** and **Keyboard
217
+ shortcuts…**, each with its shortcut. A window opens on the **Workspace
218
+ overview** page, on its **Souls** tab: at launch, and after you choose a
219
+ workspace for it. Connections is in the command palette
220
+ (**Settings: Connections…**), and the palette opens with its shortcut or
221
+ Ctrl+X then `k`.
222
+ The instances have no search field: to find one by name, type it in the
223
+ command palette, which opens its terminal. ⌘F / Alt+F (**Focus the
224
+ instance roster**) and `/` in the sidebar go to the roster's current row;
225
+ on an empty roster, to its one action, the foot's **Spawn instance**, where
226
+ F6 lands too (a failed read's **Retry** comes first).
227
+
228
+ The sidebar is 288px wide, and you can make it wider or narrower: drag its
229
+ right edge, between 240px and 480px (or 45% of the window, when that is
230
+ less, so the terminals keep the rest). With the keyboard, Tab to that edge
231
+ (after the settings cog) and use ← and → (8px a step, 32px with Shift), Home
232
+ and End for the narrowest and the widest. A double-click on the edge, Enter
233
+ on it, or the command palette's **Sidebar: reset width** put it back to 288px.
234
+ The width is remembered on this computer, and kept while the sidebar is
235
+ hidden; a window too narrow for it shows it narrower, and gives it back when
236
+ the window grows again. The terminals refit as it moves, and their programs
237
+ hear the new size once, when you let go.
238
+
239
+ The list of workspaces is always shown. Its heading holds **Add local
240
+ workspace…** (the **+**). The list has one row per workspace this window can show, whatever
241
+ machine it is on: every workspace the Desktop serves, those only on servers
242
+ included, and the deployments no workspace matched ([One workspace, several
243
+ machines](#one-workspace-several-machines)), after them in the same list.
244
+
245
+ With one workspace the list is one compact row. With many it scrolls within
246
+ about six rows, the current row stays in view, and while rows are cut off
247
+ below, a line under the list says how many ("2 more below"), with the
248
+ needs-input mark at its right when one of them has an instance that needs
249
+ input.
250
+
251
+ **Show only the current workspace** is the toggle before the **+** in the
252
+ heading, for working in one workspace at a time. Pressed (its icon in the
253
+ accent colour), the list shows the current workspace's row alone. Nothing
254
+ stands for the others: no "N more" line, and no needs-input mark for one of
255
+ them that waits. Press it again, or use ⌥⇧⌘O on macOS / Ctrl+Alt+Shift+O on
256
+ Linux and Windows (the same in every chord family, and from a terminal) or the
257
+ palette's **Show only the current workspace**, to see every workspace again.
258
+ Ctrl+X then ↑ / ↓ still move to the previous / next workspace, which then
259
+ shows alone. A window choosing a workspace shows them all. The choice is remembered on this
260
+ computer.
261
+
262
+ - **A row is one line: a circle and the workspace's name.** No icon, no
263
+ machine, no state: a workspace's own pages show its machines and
264
+ deployments. The circle is the one an instance row has, in the same place.
265
+ A long name ends in an ellipsis, and the row's tooltip is the whole name.
266
+ - **The current workspace** has its circle filled, like a running
267
+ instance's, and its name in bold; the others have the ring a stopped
268
+ instance has. It has no background of its own: the selection's background
269
+ marks the current page (Workspace overview or Automations), so the
270
+ sidebar fills one "you are here" row. A screen reader hears it as current,
271
+ and the list's description names it, by the same name as its row.
272
+ - **The needs-input mark.** A row has an exclamation mark (a small amber
273
+ disc with a "!") at its right end when an instance of that workspace needs
274
+ input, the same mark a waiting instance's dot shows in the instance tree: the claim the instance roster shows
275
+ for that instance, from a running session (OATS with the `waiting-on-you`
276
+ feature), as the Desktop already reads it for the workspaces it serves.
277
+ Every row can have it, the current one included. The row's name then ends
278
+ in ", needs input" for a screen reader, and its tooltip says "An instance
279
+ here needs input". What isn't known shows no mark, never a guess: a
280
+ deployment that isn't live (stale, not reached, its last read failed) and
281
+ an oats without `waiting-on-you`. The mark never moves a row: the order
282
+ stays the same whoever waits.
283
+ - **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+X then ↑ /
284
+ ↓, which are also ⌥↑ / ⌥↓ on macOS and Alt+↑ / Alt+↓ on Linux and Windows
285
+ in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
286
+ selection; one another window shows moves here ([A workspace another window
287
+ shows](#a-workspace-another-window-shows)). The leader's ↑ / ↓ go to the
288
+ previous / next row, and stop at the ends ("No workspace above this one." /
289
+ "No workspace below this one."). Each is a pick, so walking the list with
290
+ them moves every workspace it passes that another window shows into this
291
+ window.
292
+ - **Open in new window** is in a row's context menu (a right-click, or
293
+ Shift+F10 or the Menu key), and ⌘Enter on macOS / Ctrl+Enter on Linux and
294
+ Windows does it from the keyboard. It opens the workspace in its own window,
295
+ or brings the window that shows it to the front.
296
+ - **Keyboard.** The list is one Tab stop, Up/Down/Home/End move in it, and
297
+ `w` in the sidebar, Ctrl+X then `o`, ⌥⌘O / Alt+O and the palette's
298
+ **Workspace: switch…** focus it. The full keys are in [the keyboard
299
+ reference](../packages/desktop/docs/desktop-keyboard.md#the-list-of-workspaces).
300
+
301
+ **Add local workspace…** lists the deployments on this computer that are not
302
+ open: those on this computer's deployments list and a saved one. Each is one
303
+ button: a click, or Enter on it, adds it (checked first) and opens it in this
304
+ window; a failure says why in the dialog, with focus back on it. The dialog
305
+ counts these alone ("2 workspaces to add"). After them, under **Can't be
306
+ opened**, come the rows of this computer's list that can't be opened, each
307
+ saying why in a word, and they open nothing: **Missing** (the folder is gone, or its volume
308
+ isn't mounted), **Not a deployment** (no `oats-local.yaml` any more), or
309
+ **Can't be checked** (OATS couldn't read the folder). The full sentence is the
310
+ row's tooltip and what a screen reader hears. **Remove** beside such a row
311
+ takes it off the list (Right Arrow, then Enter, from the keyboard); nothing on
312
+ disk changes. With an oats that has no deployments list, the dialog offers the
313
+ saved deployments alone and says "This oats can't list this computer's
314
+ deployments. Update oats."; a list read that failed says "Couldn't read this
315
+ computer's deployments:" and why. **Browse…** chooses any other folder, and one without
316
+ `oats-local.yaml` is offered onboarding.
317
+
318
+ A window with no workspace (a New Window, or one whose workspace moved to
319
+ another window) shows "Choose a workspace" and focuses the list. When the
320
+ Desktop serves no workspace at all, so the list is empty, it opens **Add local
321
+ workspace…** instead. Closing the dialog leaves "Choose a workspace", whose
322
+ button opens it again.
323
+
324
+ ### A workspace another window shows
325
+
326
+ Picking a workspace another window shows moves it to this window: a pick from
327
+ the list, the workspace select of
328
+ the Workspace page, and a spawn whose new instance is in that workspace.
329
+ Nothing else comes to the front. The other window lets the workspace go: it
330
+ shows the workspace it showed most recently before that one among those the
331
+ Desktop still serves and no other window shows, else no workspace ("Choose a
332
+ workspace"). It closes every tab it had of the workspace that moved. The
333
+ Desktop waits at most 2 seconds for the other window; one that answers late
334
+ ends the same way, and so does one that was still opening or reloading:
335
+ once it comes up it shows no workspace, never the one that moved. **Open in
336
+ new window** still brings the other window to the front instead.
337
+
338
+ Only the terminals and the split move with the workspace: this window opens
339
+ the same terminal tabs in the same split, each with a fresh viewer, and the
340
+ agents keep running. File, brain and view tabs do not move: they close in the
341
+ other window.
342
+
189
343
  ## Capabilities and spawning
190
344
 
191
- **Workspace › Capabilities** lists what the workspace offers, in three
192
- sections: **Workspace owned** (from the member repos, for every soul),
345
+ **Workspace › Capabilities** is in two parts, each with its title:
346
+ **Workspace defaults** (below), then **All capabilities**, what the
347
+ workspace offers. Under the **All capabilities** title, a row of segments
348
+ jumps to its three sections: **Workspace owned** (from the member repos, for every soul),
193
349
  **Repo owned** (only for souls of the same repo) and **Packages** (pinned
194
350
  versions). Workspace owned and Repo owned are grouped by the repository
195
351
  that defines each capability. The groups are headed like the Souls tab:
@@ -200,6 +356,42 @@ pills (**All**, then one per repository, each with its count) show one
200
356
  repository at a time; "N of M shown" appears while a pill or the search
201
357
  narrows the list.
202
358
 
359
+ Above All capabilities, **Workspace defaults** shows what every soul of the
360
+ workspace starts with, unless it turns one off. It is one panel with two
361
+ groups. **Core capabilities** (at most one of each per soul) is always
362
+ **Knowledge**, **Messaging** and **Tasks**. **Additional capabilities** (any
363
+ number per soul) lists the other capabilities the workspace gives every soul,
364
+ or says there are none. Each default is shown the same way: its tile, the
365
+ capability and its source (a package and its pinned version, or a repository
366
+ and "latest"). Click it to open the capability's page. An empty core slot
367
+ shows **None**: there is no workspace default, and each soul chooses its
368
+ own. A core capability the workspace names among its other defaults, rather
369
+ than in its slot, is shown under Core, in that slot, as the kernel fills the
370
+ slot with it. An additional default the workspace turned off is struck through and
371
+ says "turned off by the workspace". A workspace that sets no defaults, a
372
+ standalone deployment for example, shows one line saying so. The search and
373
+ the repository pills never narrow or hide this section. It is read from
374
+ `oats workspace status --json`: an OATS that does not report the defaults
375
+ shows no such part, and the Desktop does not guess them from the souls. The
376
+ defaults have no segment of their own: the segments are All capabilities'.
377
+ Teams add no capabilities (removed in 0.30), so there are no team defaults
378
+ to show.
379
+
380
+ The round **i** button in the toolbar, beside the search (**About capabilities**), opens
381
+ **What capabilities are**: what a capability gives a soul's instances (skills,
382
+ commands and instructions, the instructions injected into each instance's
383
+ composed `AGENTS.md` after the soul's own), the three places one comes from
384
+ (Workspace owned, Repo owned, Packages), which three capabilities are core
385
+ (knowledge, messaging and tasks, at most one of each per soul) and that every
386
+ other one is additional, and what workspace defaults are and why they
387
+ matter: every soul gets them, they give an organisation's agents one shared
388
+ way of working, and a knowledge default keeps what agents learn and the
389
+ procedures the organisation writes down for later instances; a soul can turn
390
+ one off and name its own in its place.
391
+ **Close** or Esc closes it and returns the focus to the button; leaving the
392
+ tab or the workspace closes it too. **Workspace › Souls** has the same button
393
+ at the end of its toolbar, **About souls**, which explains what a soul is.
394
+
203
395
  A soul's page (open a soul from **Workspace › Souls**) ends with
204
396
  **Instructions**, what its instances are told, read like a capability's
205
397
  injected instructions (a navigation tree on the left, the file on the right).
@@ -260,31 +452,50 @@ name, as its suffix:
260
452
  `desktop-improvements` for `oats-desktop-expert` becomes
261
453
  `desktop-improvements-expert`. A name that already ends in the role, or is
262
454
  the role, stays as typed. The line under the field shows the final name, and a
263
- name that is too long, invalid or already taken is explained there. With an
264
- OATS older than 0.26.0, which can't take an exact name, and for a spawn on a
265
- server, what you type is a purpose instead: the instance is named
266
- `<soul>-<purpose>`, and the field shows that prefix.
455
+ name that is too long, invalid or already taken is explained there. A spawn
456
+ on a server takes the exact name the same way when that machine's OATS can
457
+ take one (feature `spawn-name`, read from its last roster answer), and its
458
+ name is explained there too when that machine refuses it. With an OATS older
459
+ than 0.26.0 on either side, which can't take an exact name, or a server whose
460
+ OATS this computer has not heard from, what you type is a purpose instead: the
461
+ instance is named `<soul>-<purpose>`, and the field shows that prefix.
267
462
 
268
463
  **Named from its task.** When the installed OATS can suggest names (feature
269
464
  `spawn-suggest-name`), the help under an empty Name reads "Left empty, the
270
465
  instance is named from its task." Once the Opening instruction holds at
271
- least three words and you stop typing for about a second and a half, the
272
- Desktop asks OATS for a name. The soul's own harness reads the instruction
273
- and replies with a short name for the work, and the role is added as its
274
- suffix. The name shows as the field's placeholder ("will be named
275
- release-notes-manager"), on the line under the field ("(from the task)") and
276
- in **What will be created**. It belongs to the instruction it was made for:
277
- when you change the instruction it goes, until the next pause. Typing in Name
278
- replaces it and stops suggestions for the rest of the dialog, even if you
279
- empty the field again. Press **Spawn** with Name empty and no name yet, and the
466
+ least seven words, the Desktop asks OATS for a name as you type. The soul's
467
+ own harness reads the instruction and replies with a short name for the work,
468
+ and the role is added as its suffix. The name shows as the field's
469
+ placeholder ("release-notes-manager"), on the line under the field ("(from
470
+ the task)") and in **What will be created**. It belongs to the instruction it
471
+ was made for: when you change the instruction it goes, and the Desktop asks
472
+ again for the new instruction while it holds seven words or more. Typing in
473
+ Name replaces it and stops suggestions for the rest of the dialog, even if
474
+ you empty the field again. Press **Spawn** with Name empty and no name yet, and the
280
475
  dialog says **Naming…** and asks once, however short the instruction. When OATS
281
476
  can't name it, the instance is numbered and a notification says why, for
282
477
  example "Named oats-desktop-expert-3: naming took longer than 20 seconds."
283
478
  That happens when there is no instruction, when the harness doesn't suggest
284
479
  names (Codex), when there is no answer within 20 seconds, when the harness
285
480
  couldn't be asked, and when its reply wasn't a name. Each request is a call
286
- to the harness's model: nothing is asked before you type, nothing runs on a
287
- timer, and a spawn on a server is not named this way.
481
+ to the harness's model: nothing is asked before you type, and nothing runs on
482
+ a timer.
483
+
484
+ A spawn on a server whose OATS takes an exact name is named from its task the
485
+ same way, with one difference: the name is chosen on this computer. The
486
+ Opening instruction is sent to this computer's harness and model, as for a
487
+ spawn here: the Harness you chose, else the soul's default on that server,
488
+ else Claude Code, with this computer's launch configuration for it. That needs
489
+ an OATS here that can name a spawn for another machine (feature
490
+ `instance-suggest-name`). When it can't, or the name couldn't be chosen here,
491
+ the server names the instance itself from its task if its OATS can (feature
492
+ `spawn-apply-suggest-name`): the help reads "Left empty, the instance is named
493
+ from its task on <server>." Otherwise the server numbers it, and the help reads
494
+ "Named by <server> when it spawns." Naming never stops a spawn on a server.
495
+ When the instance is numbered where it would have been named, a notification
496
+ says why, as for a spawn here. A name chosen here is not checked on the server
497
+ until the spawn: one that is already taken there is refused, and explained
498
+ under the field.
288
499
 
289
500
  When capabilities set up the new worktree (OATS 0.49.0 and later), **Setup**
290
501
  names them, in the order they run, and says this can take several minutes. Such
@@ -351,21 +562,34 @@ When the retire has ended without finishing, the row says so and offers only
351
562
 
352
563
  ## One workspace, several machines
353
564
 
354
- The switcher lists each workspace once, however many deployments it has: the
565
+ The list of workspaces has each workspace once, however many deployments it has: the
355
566
  deployments you opened on this Mac and those your registered servers report,
356
567
  matched by the workspace each one reports (its repository key and default
357
568
  team, by the kernel's rules). It needs a CLI with the `workspace-identity`
358
569
  feature (OATS 0.36.0); without it each deployment has its own entry.
359
570
 
360
- - **Deployments.** The **Deployments** page (formerly the Active overview)
361
- shows the workspace's overview trees. **All** stacks one section per
362
- deployment, each headed by its machine and folder ("This Mac ·
363
- ~/acme", "altair · ~/northwind"). Then each deployment has a tab of
364
- its own, named by its machine ("altair"; "This Mac · oats-v2" when this Mac
365
- holds two). A workspace with one deployment shows just that deployment's
366
- tab. The tab you chose is remembered per workspace. With two or more
367
- deployments, the sidebar's instance list is grouped under one heading per
368
- machine; with one, it has no headings.
571
+ - **Machines.** **Workspace › Machines** (once the Deployments page, and
572
+ the Active overview before that) shows the workspace's overview trees.
573
+ One sentence above them says what a machine is: "Each machine runs this
574
+ workspace in a folder of its own. The instances under a machine run on
575
+ that machine." **All** stacks one section per deployment, each headed by
576
+ its machine and folder ("This Mac · ~/acme", "altair · ~/northwind"),
577
+ with "Instances on this machine" or "Instances on altair" under it. Then
578
+ each deployment has a tab of its own, named by its machine ("altair";
579
+ "This Mac · oats-v2" when this Mac holds two). A workspace with one
580
+ deployment shows just that deployment's tab, its tree under the same
581
+ heading. The tab you chose is
582
+ remembered per workspace. With two or more deployments, the sidebar's
583
+ instance list is grouped under one heading per machine; with one, it has
584
+ no headings.
585
+ - **An instance's card.** Clicking an instance on the Machines tab shows
586
+ what it reports and two buttons. **Go to instance** opens its terminal tab;
587
+ for a stopped instance it reads **Start…** and opens the Start dialog.
588
+ **Go to soul** opens the soul it was spawned from on the Workspace page. It
589
+ is disabled, and says why, when that soul can't be told or shown exactly:
590
+ the instance records none, it is no longer among the deployment's souls,
591
+ several match, another soul of the deployment has the same name, or the
592
+ instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the instance's menu and its panel.
369
593
  - **Not shown live.** A deployment that can't be shown live says why in a few
370
594
  words on its heading ("ssh needs a prompt", "Timed out", "OATS too old to
371
595
  report its workspace"), and **How to fix** under it gives the full sentence
@@ -374,19 +598,22 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
374
598
  needs `oats sync` or fixing in `oats-local.yaml`, or this computer's OATS
375
599
  can't read other machines. A server that can't be reached stays under the
376
600
  workspace it last reported, marked "remembered".
377
- - **The switcher.** Each workspace names its machines on one line ("This Mac ·
601
+ - **The list of workspaces.** Each workspace names its machines on one line ("This Mac ·
378
602
  altair"), with a mark when one of them isn't live.
379
603
  - **Not matched to a workspace.** A deployment that can't be matched is
380
- listed on its own under that heading in the switcher, with its machine and
381
- a short reason; choosing it opens its tab on the Deployments page. When this
604
+ listed on its own under that heading in the list, with its machine and
605
+ a short reason; choosing it opens its tab on the Machines tab. When this
382
606
  computer's OATS is too old to report workspaces, nothing can be matched:
383
607
  each deployment is listed on its own, as before, and its heading says to
384
608
  update OATS.
385
609
  - **Actions.** Everything you do to an instance goes to that instance's own
386
610
  deployment. Workspace-wide pages (Setup, Capabilities, Sync, Automations,
387
611
  Schedules, Teams configuration) act on the workspace's first deployment on
388
- this Mac, else its first, and say "On <deployment>" when there are two or
389
- more.
612
+ this Mac, else its first. None of them names it: not Souls,
613
+ Capabilities, Teams or Setup, nor the Automations page, nor a soul's, a
614
+ capability's or a team's page. The side panel names it ("On This Mac ·
615
+ ~/acme", under a soul's name) when there are two or more, as do Brain and
616
+ the Sync sheet, and the Machines tab shows each deployment on its own tab.
390
617
  - **Spawn.** With two or more deployments, the Spawn dialog asks first which
391
618
  one to spawn in (and says "Runs on" in its summary), starting on the one you last used in that workspace when it
392
619
  offers the soul, else the first that does (this Mac first). With one, it
@@ -398,7 +625,8 @@ deployment. Details are in
398
625
 
399
626
  ## Scheduling agents and wake messages
400
627
 
401
- Open **Schedules** in the selected workspace to launch a new agent on a cron,
628
+ Open **Automations › Schedules** in the selected workspace (the sidebar's
629
+ **Automations**, or ⌘3 / Ctrl+3) to launch a new agent on a cron,
402
630
  wake an existing agent with a message, or harvest its knowledge. **Schedule…**
403
631
  on a Soul roster card preselects that soul. Choose the task or message, repeat
404
632
  pattern and time zone; new agent jobs also offer harness, model, permissions
@@ -465,7 +693,7 @@ member and what each member state means. Then **Shared through Git** lists
465
693
  what the workspace declares (Members, with the host first and tagged
466
694
  **Host**, Packages and Defaults). **This computer** lists what is not shared:
467
695
  this deployment's settings, lock, CLI and instances, the member clones, and
468
- the machines that run the workspace.
696
+ the machines that run the workspace (**Registered machines**).
469
697
 
470
698
  ## A workspace's machines
471
699
 
@@ -473,7 +701,7 @@ A window offers only the machines that run its workspace: those whose
473
701
  registration reports the same workspace key as the window's deployment on this
474
702
  computer (OATS CLI with `servers-per-workspace` and `server-connect`). The
475
703
  spawn dialog's **Where to run** lists "This computer" and those machines; the
476
- Workspace › Setup tab lists them with their OATS version and whether they can
704
+ Workspace › Setup tab's **Registered machines** lists them with their OATS version and whether they can
477
705
  be reached, with **Check** and **Remove**. Registrations whose key is not known
478
706
  yet are checked once in the background after the Desktop starts.
479
707
 
@@ -494,8 +722,8 @@ saved route. A machine registered for a workspace no window shows is not
494
722
  contacted, so a machine that is switched off no longer slows every window's
495
723
  roster. Opening a window on another workspace reads its machines at once. Until
496
724
  it does, that workspace's machines are shown as they were last read, marked
497
- stale, and the switcher still lists them, not counted live. The read covers every machine again while a window
498
- shows the switcher, and on the first read after the Desktop starts. With an
725
+ stale, and the list of workspaces still lists them, not counted live. The read covers every machine again while a window
726
+ has no workspace, and on the first read after the Desktop starts. With an
499
727
  older CLI, every registered machine is read, as before.
500
728
 
501
729
  ## Instances on servers
@@ -601,17 +829,42 @@ right of its parent, and related instances are grouped together. Siblings are
601
829
  joined by a dotted line through their dots. A parent's line to its children
602
830
  runs just to the right of the dotted line, so the two never merge.
603
831
 
832
+ A row shows the instance's name as words: each `-` is a space, and the first
833
+ letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
834
+ maintainer lanes". Only the row's label changes. The hover card, the command
835
+ palette (which still finds the instance by its name), its terminal tab, a
836
+ screen reader and the `oats` CLI all use the instance's real name. The TUI's
837
+ sidebar shows the same words.
838
+
839
+ A row's dot says the instance's state: filled while it runs, a ring when it is
840
+ stopped, a grey ring with a small grey centre when its state is unknown (the
841
+ command palette, Quick Open and the overview show it the same way). An
842
+ instance that needs input (a running session's claim, from OATS with the
843
+ `waiting-on-you` feature) shows the needs-input mark in place of its dot: a
844
+ slightly larger amber disc with a "!" cut out of it, the mark its terminal tab
845
+ and the workspace list show. Amber means needs input and nothing else.
846
+ Elsewhere, a dot that flags a problem is red: a keyboard shortcut that clashes
847
+ with another (on the settings cog), Setup or Teams needing attention (on the
848
+ Workspace page's tabs), and an automation that doesn't run here or a
849
+ scheduler that is off.
850
+ The row keeps its soul and repository on its second line. A screen reader
851
+ hears "Needs input" after the name, and the hover card gives the reason and
852
+ how long it has waited. A collapsed parent shows "! N below" on its second
853
+ line for the rows it hides that need input, beside its own mark when it waits
854
+ too. Rows never move or grow, and nothing animates.
855
+
604
856
  ## An instance's colour
605
857
 
606
858
  An instance can have a colour, one of the soul palette's six (Sand, Sage,
607
859
  Slate, Mauve, Clay, Olive). Its dot shows it wherever the instance is listed:
608
860
  the sidebar, its terminal tab, the command palette and the overview. A running
609
861
  instance's dot is filled with the colour, a stopped one's is a ring in it. An
610
- instance whose state is unknown keeps the warning dot, and one without a colour
611
- looks as before. The shape says the state, never the colour alone.
862
+ instance whose state is unknown keeps its grey bullseye, one that needs input
863
+ shows the needs-input mark in the sidebar, never in its colour, and one without
864
+ a colour looks as before. The shape says the state, never the colour alone.
612
865
 
613
866
  To set it, open **Instance: name and colour…** from the command palette, or
614
- press Ctrl+Alt+R (⌥⌘R on macOS). It acts on the instance of the terminal you
867
+ press Alt+R (⌥⌘R on macOS; Ctrl+Alt+R in the Ctrl+Alt family). It acts on the instance of the terminal you
615
868
  are in, else the focused sidebar row, else the active terminal tab's instance.
616
869
  The dialog shows the instance's name, which can't be changed yet, and the
617
870
  colours as buttons: **None** and the six. Arrow keys move between them; Enter,
@@ -676,7 +929,7 @@ unknown or unreported harness shows "?". Sources and licences are in
676
929
  | Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
677
930
  | macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
678
931
  | Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
679
- | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use the workspace switcher → Add workspace to select the right folder. |
932
+ | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use **Add local workspace…** (the **+** at the top of the sidebar) to select the right folder. |
680
933
 
681
934
  For bugs, attach the terminal output of the app (`OATS Desktop` prints
682
935
  server and CLI-discovery logs to stdout) and your platform/arch.
@@ -163,9 +163,11 @@ in section 2). The instance home is
163
163
  `agents/<soul>/instances/<instance>/`; `work/` is its repository view;
164
164
  `.oats/modules/<cap>/` are the copied capabilities and `.agents/skills/<skill>/` their skills;
165
165
  `instance.json` records `modules` (from, commit, digest), `providers` and
166
- `workspace`. A running instance never changes under itself — a member that
167
- moves affects only new spawns, and `oats status` shows the drift
168
- (`member moved since (now @ …)` / `capability no longer present`).
166
+ `workspace`. A running instance never changes under itself; a stopped one can
167
+ be moved to the locked package versions with `oats instance upgrade`. Member
168
+ modules and the soul body still require a new spawn. `oats status` shows the
169
+ drift (`member moved since (now @ …)` / `capability no longer present`). See
170
+ [upgrading package modules](upgrading.md#moving-existing-homes-to-locked-package-versions).
169
171
 
170
172
  Instance-specific provider values belong to the spawn:
171
173
  `oats spawn <soul> --provider <cap> key=value` (repeatable; dotted keys nest),