@awebai/oats 0.66.0 → 0.68.0

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 (81) hide show
  1. package/bin/oats.mjs +166 -17
  2. package/docs/capabilities.md +58 -9
  3. package/docs/capability-manifest.schema.json +5 -1
  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 +463 -13
  7. package/docs/desktop.md +363 -67
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +46 -6
  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-lane.md +16 -0
  16. package/docs/release-notes/v0.67.0.md +366 -0
  17. package/docs/release-notes/v0.67.1.md +64 -0
  18. package/docs/release-notes/v0.68.0.md +504 -0
  19. package/docs/servers.md +8 -2
  20. package/docs/souls-and-instances.md +58 -6
  21. package/docs/tui.md +1033 -237
  22. package/docs/upgrading.md +164 -26
  23. package/docs/workspaces.md +2 -2
  24. package/lib/capability-contract.mjs +8 -7
  25. package/lib/core.mjs +331 -75
  26. package/lib/instance-color.mjs +58 -0
  27. package/lib/instance-events.mjs +1 -1
  28. package/lib/instance-inspect.mjs +107 -23
  29. package/lib/instance-lifecycle.mjs +21 -1
  30. package/lib/instance-naming.mjs +187 -0
  31. package/lib/instance-resolution.mjs +10 -6
  32. package/lib/instance-upgrade.mjs +1445 -0
  33. package/lib/materialize.mjs +287 -89
  34. package/lib/servers.mjs +24 -11
  35. package/lib/soul-composition.mjs +7 -3
  36. package/lib/upgrade-state.mjs +101 -0
  37. package/lib/workspace.mjs +4 -1
  38. package/lib/worktree.mjs +103 -12
  39. package/package-catalog.json +5 -4
  40. package/package.json +1 -1
  41. package/packages/client/cli-adapter.mjs +52 -6
  42. package/packages/client/cli-locator.mjs +2 -2
  43. package/packages/client/composed-gate.mjs +10 -2
  44. package/packages/client/deployment-data.mjs +5 -0
  45. package/packages/client/deployment-identity.mjs +40 -0
  46. package/packages/client/deployment-panel.mjs +9 -3
  47. package/packages/client/inspect-boundary.mjs +11 -7
  48. package/packages/client/inspect-cache.mjs +2 -2
  49. package/packages/client/instance-name.mjs +28 -0
  50. package/packages/client/instance-presentation.mjs +11 -0
  51. package/packages/client/keymap.mjs +133 -28
  52. package/packages/client/keys-file.mjs +126 -0
  53. package/packages/client/own-codes.mjs +4 -2
  54. package/packages/client/panel-views.mjs +78 -12
  55. package/packages/client/spawn-naming.mjs +32 -0
  56. package/packages/client/spawn-preview-cli.mjs +58 -7
  57. package/packages/client/spawn-preview-contract.mjs +59 -0
  58. package/packages/client/spawn-preview-facts.mjs +8 -4
  59. package/packages/client/spawn-preview.mjs +81 -3
  60. package/packages/client/team-members.mjs +4 -1
  61. package/packages/client/workspace-step.mjs +25 -0
  62. package/packages/tui/README.md +7 -7
  63. package/packages/tui/lib/actions.mjs +92 -25
  64. package/packages/tui/lib/client.mjs +9 -4
  65. package/packages/tui/lib/config.mjs +50 -9
  66. package/packages/tui/lib/main.mjs +65 -24
  67. package/packages/tui/lib/model.mjs +292 -75
  68. package/packages/tui/lib/read.mjs +53 -1
  69. package/packages/tui/lib/store.mjs +469 -100
  70. package/packages/tui/lib/term/keys.mjs +22 -6
  71. package/packages/tui/lib/term/kitty.mjs +54 -11
  72. package/packages/tui/lib/term/screen.mjs +15 -6
  73. package/packages/tui/lib/term/through.mjs +66 -28
  74. package/packages/tui/lib/views/frame.mjs +223 -165
  75. package/packages/tui/lib/views/help.mjs +134 -29
  76. package/packages/tui/lib/views/instances.mjs +63 -22
  77. package/packages/tui/lib/views/palette.mjs +14 -4
  78. package/packages/tui/lib/views/souls.mjs +2 -2
  79. package/packages/tui/lib/views/switcher.mjs +6 -1
  80. package/packages/tui/lib/views/workspaces.mjs +55 -0
  81. package/skills/oats-getting-started/SKILL.md +96 -42
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,139 @@ 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 list of workspaces is always shown. Its heading holds **Add local
229
+ workspace…** (the **+**). The list has one row per workspace this window can show, whatever
230
+ machine it is on: every workspace the Desktop serves, those only on servers
231
+ included, and the deployments no workspace matched ([One workspace, several
232
+ machines](#one-workspace-several-machines)), after them in the same list.
233
+
234
+ With one workspace the list is one compact row. With many it scrolls within
235
+ about six rows, the current row stays in view, and while rows are cut off
236
+ below, a line under the list says how many ("2 more below"), with the
237
+ needs-input mark at its right when one of them has an instance that needs
238
+ input.
239
+
240
+ **Show only the current workspace** is the toggle before the **+** in the
241
+ heading, for working in one workspace at a time. Pressed (its icon in the
242
+ accent colour), the list shows the current workspace's row alone. Nothing
243
+ stands for the others: no "N more" line, and no needs-input mark for one of
244
+ them that waits. Press it again, or use ⌥⇧⌘O on macOS / Ctrl+Alt+Shift+O on
245
+ Linux and Windows (the same in every chord family, and from a terminal) or the
246
+ palette's **Show only the current workspace**, to see every workspace again.
247
+ Ctrl+X then ↑ / ↓ still move to the previous / next workspace, which then
248
+ shows alone. A window choosing a workspace shows them all. The choice is remembered on this
249
+ computer.
250
+
251
+ - **A row is one line: a circle and the workspace's name.** No icon, no
252
+ machine, no state: a workspace's own pages show its machines and
253
+ deployments. The circle is the one an instance row has, in the same place.
254
+ A long name ends in an ellipsis, and the row's tooltip is the whole name.
255
+ - **The current workspace** has its circle filled, like a running
256
+ instance's, and its name in bold; the others have the ring a stopped
257
+ instance has. It has no background of its own: the selection's background
258
+ marks the current page (Workspace overview or Automations), so the
259
+ sidebar fills one "you are here" row. A screen reader hears it as current,
260
+ and the list's description names it, by the same name as its row.
261
+ - **The needs-input mark.** A row has an exclamation mark (a small amber
262
+ disc with a "!") at its right end when an instance of that workspace needs
263
+ input, the same mark an instance's **Needs input** pill starts with: the claim the instance roster shows
264
+ for that instance, from a running session (OATS with the `waiting-on-you`
265
+ feature), as the Desktop already reads it for the workspaces it serves.
266
+ Every row can have it, the current one included. The row's name then ends
267
+ in ", needs input" for a screen reader, and its tooltip says "An instance
268
+ here needs input". What isn't known shows no mark, never a guess: a
269
+ deployment that isn't live (stale, not reached, its last read failed) and
270
+ an oats without `waiting-on-you`. The mark never moves a row: the order
271
+ stays the same whoever waits.
272
+ - **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+X then ↑ /
273
+ ↓, which are also ⌥↑ / ⌥↓ on macOS and Alt+↑ / Alt+↓ on Linux and Windows
274
+ in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
275
+ selection; one another window shows moves here ([A workspace another window
276
+ shows](#a-workspace-another-window-shows)). The leader's ↑ / ↓ go to the
277
+ previous / next row, and stop at the ends ("No workspace above this one." /
278
+ "No workspace below this one."). Each is a pick, so walking the list with
279
+ them moves every workspace it passes that another window shows into this
280
+ window.
281
+ - **Open in new window** is in a row's context menu (a right-click, or
282
+ Shift+F10 or the Menu key), and ⌘Enter on macOS / Ctrl+Enter on Linux and
283
+ Windows does it from the keyboard. It opens the workspace in its own window,
284
+ or brings the window that shows it to the front.
285
+ - **Keyboard.** The list is one Tab stop, Up/Down/Home/End move in it, and
286
+ `w` in the sidebar, Ctrl+X then `o`, ⌥⌘O / Alt+O and the palette's
287
+ **Workspace: switch…** focus it. The full keys are in [the keyboard
288
+ reference](../packages/desktop/docs/desktop-keyboard.md#the-list-of-workspaces).
289
+
290
+ **Add local workspace…** lists the deployments on this computer that are not
291
+ open: those on this computer's deployments list and a saved one. Each is one
292
+ button: a click, or Enter on it, adds it (checked first) and opens it in this
293
+ window; a failure says why in the dialog, with focus back on it. The dialog
294
+ counts these alone ("2 workspaces to add"). After them, under **Can't be
295
+ opened**, come the rows of this computer's list that can't be opened, each
296
+ saying why in a word, and they open nothing: **Missing** (the folder is gone, or its volume
297
+ isn't mounted), **Not a deployment** (no `oats-local.yaml` any more), or
298
+ **Can't be checked** (OATS couldn't read the folder). The full sentence is the
299
+ row's tooltip and what a screen reader hears. **Remove** beside such a row
300
+ takes it off the list (Right Arrow, then Enter, from the keyboard); nothing on
301
+ disk changes. With an oats that has no deployments list, the dialog offers the
302
+ saved deployments alone and says "This oats can't list this computer's
303
+ deployments. Update oats."; a list read that failed says "Couldn't read this
304
+ computer's deployments:" and why. **Browse…** chooses any other folder, and one without
305
+ `oats-local.yaml` is offered onboarding.
306
+
307
+ A window with no workspace (a New Window, or one whose workspace moved to
308
+ another window) shows "Choose a workspace" and focuses the list. When the
309
+ Desktop serves no workspace at all, so the list is empty, it opens **Add local
310
+ workspace…** instead. Closing the dialog leaves "Choose a workspace", whose
311
+ button opens it again.
312
+
313
+ ### A workspace another window shows
314
+
315
+ Picking a workspace another window shows moves it to this window: a pick from
316
+ the list, the workspace select of
317
+ the Workspace page, and a spawn whose new instance is in that workspace.
318
+ Nothing else comes to the front. The other window lets the workspace go: it
319
+ shows the workspace it showed most recently before that one among those the
320
+ Desktop still serves and no other window shows, else no workspace ("Choose a
321
+ workspace"). It closes every tab it had of the workspace that moved. The
322
+ Desktop waits at most 2 seconds for the other window; one that answers late
323
+ ends the same way, and so does one that was still opening or reloading:
324
+ once it comes up it shows no workspace, never the one that moved. **Open in
325
+ new window** still brings the other window to the front instead.
326
+
327
+ Only the terminals and the split move with the workspace: this window opens
328
+ the same terminal tabs in the same split, each with a fresh viewer, and the
329
+ agents keep running. File, brain and view tabs do not move: they close in the
330
+ other window.
331
+
189
332
  ## Capabilities and spawning
190
333
 
191
- **Workspace › Capabilities** lists what the workspace offers, in three
192
- sections: **Workspace owned** (from the member repos, for every soul),
334
+ **Workspace › Capabilities** is in two parts, each with its title:
335
+ **Workspace defaults** (below), then **All capabilities**, what the
336
+ workspace offers. Under the **All capabilities** title, a row of segments
337
+ jumps to its three sections: **Workspace owned** (from the member repos, for every soul),
193
338
  **Repo owned** (only for souls of the same repo) and **Packages** (pinned
194
339
  versions). Workspace owned and Repo owned are grouped by the repository
195
340
  that defines each capability. The groups are headed like the Souls tab:
@@ -200,29 +345,83 @@ pills (**All**, then one per repository, each with its count) show one
200
345
  repository at a time; "N of M shown" appears while a pill or the search
201
346
  narrows the list.
202
347
 
348
+ Above All capabilities, **Workspace defaults** shows what every soul of the
349
+ workspace starts with, unless it turns one off. It is one panel with two
350
+ groups. **Core capabilities** (at most one of each per soul) is always
351
+ **Knowledge**, **Messaging** and **Tasks**. **Additional capabilities** (any
352
+ number per soul) lists the other capabilities the workspace gives every soul,
353
+ or says there are none. Each default is shown the same way: its tile, the
354
+ capability and its source (a package and its pinned version, or a repository
355
+ and "latest"). Click it to open the capability's page. An empty core slot
356
+ shows **None**: there is no workspace default, and each soul chooses its
357
+ own. A core capability the workspace names among its other defaults, rather
358
+ than in its slot, is shown under Core, in that slot, as the kernel fills the
359
+ slot with it. An additional default the workspace turned off is struck through and
360
+ says "turned off by the workspace". A workspace that sets no defaults, a
361
+ standalone deployment for example, shows one line saying so. The search and
362
+ the repository pills never narrow or hide this section. It is read from
363
+ `oats workspace status --json`: an OATS that does not report the defaults
364
+ shows no such part, and the Desktop does not guess them from the souls. The
365
+ defaults have no segment of their own: the segments are All capabilities'.
366
+ Teams add no capabilities (removed in 0.30), so there are no team defaults
367
+ to show.
368
+
369
+ The round **i** button in the toolbar, beside the search (**About capabilities**), opens
370
+ **What capabilities are**: what a capability gives a soul's instances (skills,
371
+ commands and instructions, the instructions injected into each instance's
372
+ composed `AGENTS.md` after the soul's own), the three places one comes from
373
+ (Workspace owned, Repo owned, Packages), which three capabilities are core
374
+ (knowledge, messaging and tasks, at most one of each per soul) and that every
375
+ other one is additional, and what workspace defaults are and why they
376
+ matter: every soul gets them, they give an organisation's agents one shared
377
+ way of working, and a knowledge default keeps what agents learn and the
378
+ procedures the organisation writes down for later instances; a soul can turn
379
+ one off and name its own in its place.
380
+ **Close** or Esc closes it and returns the focus to the button; leaving the
381
+ tab or the workspace closes it too. **Workspace › Souls** has the same button
382
+ at the end of its toolbar, **About souls**, which explains what a soul is.
383
+
203
384
  A soul's page (open a soul from **Workspace › Souls**) ends with
204
- **Instructions**, what its instances are told: the soul's own `AGENTS.md`,
205
- read like a capability's injected instructions (a navigation tree on the left,
206
- the file on the right), at its path in the soul's repository. It comes from the
207
- same inspection as the rest of the page, so **Refresh** re-reads it and keeps
208
- what you had open, and your place in it. A file over 200,000 characters is
209
- shown cut, and says so.
210
-
211
- With an OATS that composes a soul's instructions (0.46.0 and later), the tree
212
- also has **Instance**: its **AGENTS.md**, *after spawn, with injects*, is the
213
- file a spawn of this soul on this computer would write, with one entry per part
214
- (the soul's own text, then each block OATS and the soul's capabilities add, in
215
- order). Open it to read the whole document; choose a part to go to it. Each
216
- part's header says where it comes from (**From this soul** or **Injected by …**)
217
- and names its file; a capability's part has **Open capability**, and **Copy
218
- composed AGENTS.md** copies the exact file. When the soul can't be composed
219
- here, the group says so and the problem shows at the top of the page. For a
220
- soul on another machine (a server workspace), the page shows the composed file
221
- when that machine supports it: this computer's OATS must be 0.49.0 or later, to
222
- pass on what each server reports about itself, and the server's OATS must say
223
- it composes a soul's instructions (0.49.0 and later report this). Until a
224
- server reports it (an older server, or one whose last read failed), its soul
225
- pages show only the soul's own `AGENTS.md`, with no **Instance** group.
385
+ **Instructions**, what its instances are told, read like a capability's
386
+ injected instructions (a navigation tree on the left, the file on the right).
387
+ The tree has two sections, a rule between them:
388
+
389
+ - **Defined in this soul**: its own `AGENTS.md`, at its path in the soul's
390
+ repository, and, with an OATS that reports a soul's skills, its **Skills**.
391
+ Open a skill to list its files; a file opens in the reader under its
392
+ repository path.
393
+ - **Composed for an instance**: what an instance of this soul gets. Its
394
+ **AGENTS.md**, *after spawn, with injects*, and its **Skills**, each saying
395
+ where it comes from. With an OATS that lists every skill a spawn gives the
396
+ instance (0.67.0 and later), the Skills are that list: the soul's own, each
397
+ **From this soul**, and the ones its capabilities add, each **From** the
398
+ capability. A capability's skill file opens under its place in the instance
399
+ home (`.oats/modules/<capability>/…`), with **Open capability** above it. With
400
+ an older OATS the skills listed are the soul's own, and a note says that the
401
+ skills capabilities add are listed by a newer OATS. For a soul on another
402
+ machine, the server's OATS must list them too, as for the composed
403
+ AGENTS.md below.
404
+
405
+ Both come from the same inspection as the rest of the page, so **Refresh**
406
+ re-reads them and keeps what you had open, and your place in it. A file over
407
+ 200,000 characters is shown cut, and says so.
408
+
409
+ The composed **AGENTS.md** needs an OATS that composes a soul's instructions
410
+ (0.46.0 and later). It is the file a spawn of this soul on this computer would
411
+ write, with one entry per part (the soul's own text, then each block OATS and
412
+ the soul's capabilities add, in order). Open it to read the whole document;
413
+ choose a part to go to it. Each part's header says where it comes from
414
+ (**From this soul** or **Injected by …**) and names its file; a capability's
415
+ part has **Open capability**, and **Copy composed AGENTS.md** copies the exact
416
+ file. When the soul can't be composed here, the section says so and the problem
417
+ shows at the top of the page. For a soul on another machine (a server
418
+ workspace), the page shows the composed file when that machine supports it:
419
+ this computer's OATS must be 0.49.0 or later, to pass on what each server
420
+ reports about itself, and the server's OATS must say it composes a soul's
421
+ instructions (0.49.0 and later report this). Until a server reports it (an
422
+ older server, or one whose last read failed), its soul pages show no composed
423
+ **AGENTS.md**. A soul's skills follow the same rule, with the server's OATS
424
+ saying it reports them.
226
425
 
227
426
  The **Spawn** dialog's left column, **What will be created**, starts with the
228
427
  new instance's name and its home. Then come where it works, its harness and
@@ -230,6 +429,63 @@ model (with where that choice came from), its default team and the teams it may
230
429
  also join, and its relationship when it has one. Under them are its core
231
430
  capabilities and its other capabilities.
232
431
 
432
+ The dialog's first field is the **Opening instruction**, and the dialog opens
433
+ with the cursor in it (after a restored instruction's text). In a narrow window,
434
+ **What will be created** comes after the form's last field, above **Spawn**:
435
+ scroll down with the fields to read it.
436
+
437
+ The dialog's last field before **Developer settings** is **Name · optional**.
438
+ Left empty, the kernel numbers the new instance (`<soul>-<n>`). A name you type
439
+ is used in lowercase and gets the soul's role, the last word of the soul's
440
+ name, as its suffix:
441
+ `desktop-improvements` for `oats-desktop-expert` becomes
442
+ `desktop-improvements-expert`. A name that already ends in the role, or is
443
+ the role, stays as typed. The line under the field shows the final name, and a
444
+ name that is too long, invalid or already taken is explained there. A spawn
445
+ on a server takes the exact name the same way when that machine's OATS can
446
+ take one (feature `spawn-name`, read from its last roster answer), and its
447
+ name is explained there too when that machine refuses it. With an OATS older
448
+ than 0.26.0 on either side, which can't take an exact name, or a server whose
449
+ OATS this computer has not heard from, what you type is a purpose instead: the
450
+ instance is named `<soul>-<purpose>`, and the field shows that prefix.
451
+
452
+ **Named from its task.** When the installed OATS can suggest names (feature
453
+ `spawn-suggest-name`), the help under an empty Name reads "Left empty, the
454
+ instance is named from its task." Once the Opening instruction holds at
455
+ least seven words, the Desktop asks OATS for a name as you type. The soul's
456
+ own harness reads the instruction and replies with a short name for the work,
457
+ and the role is added as its suffix. The name shows as the field's
458
+ placeholder ("release-notes-manager"), on the line under the field ("(from
459
+ the task)") and in **What will be created**. It belongs to the instruction it
460
+ was made for: when you change the instruction it goes, and the Desktop asks
461
+ again for the new instruction while it holds seven words or more. Typing in
462
+ Name replaces it and stops suggestions for the rest of the dialog, even if
463
+ you empty the field again. Press **Spawn** with Name empty and no name yet, and the
464
+ dialog says **Naming…** and asks once, however short the instruction. When OATS
465
+ can't name it, the instance is numbered and a notification says why, for
466
+ example "Named oats-desktop-expert-3: naming took longer than 20 seconds."
467
+ That happens when there is no instruction, when the harness doesn't suggest
468
+ names (Codex), when there is no answer within 20 seconds, when the harness
469
+ couldn't be asked, and when its reply wasn't a name. Each request is a call
470
+ to the harness's model: nothing is asked before you type, and nothing runs on
471
+ a timer.
472
+
473
+ A spawn on a server whose OATS takes an exact name is named from its task the
474
+ same way, with one difference: the name is chosen on this computer. The
475
+ Opening instruction is sent to this computer's harness and model, as for a
476
+ spawn here: the Harness you chose, else the soul's default on that server,
477
+ else Claude Code, with this computer's launch configuration for it. That needs
478
+ an OATS here that can name a spawn for another machine (feature
479
+ `instance-suggest-name`). When it can't, or the name couldn't be chosen here,
480
+ the server names the instance itself from its task if its OATS can (feature
481
+ `spawn-apply-suggest-name`): the help reads "Left empty, the instance is named
482
+ from its task on <server>." Otherwise the server numbers it, and the help reads
483
+ "Named by <server> when it spawns." Naming never stops a spawn on a server.
484
+ When the instance is numbered where it would have been named, a notification
485
+ says why, as for a spawn here. A name chosen here is not checked on the server
486
+ until the spawn: one that is already taken there is refused, and explained
487
+ under the field.
488
+
233
489
  When capabilities set up the new worktree (OATS 0.49.0 and later), **Setup**
234
490
  names them, in the order they run, and says this can take several minutes. Such
235
491
  a spawn may run for a long time: its roster row reads **Setting up worktree…**
@@ -295,21 +551,34 @@ When the retire has ended without finishing, the row says so and offers only
295
551
 
296
552
  ## One workspace, several machines
297
553
 
298
- The switcher lists each workspace once, however many deployments it has: the
554
+ The list of workspaces has each workspace once, however many deployments it has: the
299
555
  deployments you opened on this Mac and those your registered servers report,
300
556
  matched by the workspace each one reports (its repository key and default
301
557
  team, by the kernel's rules). It needs a CLI with the `workspace-identity`
302
558
  feature (OATS 0.36.0); without it each deployment has its own entry.
303
559
 
304
- - **Deployments.** The **Deployments** page (formerly the Active overview)
305
- shows the workspace's overview trees. **All** stacks one section per
306
- deployment, each headed by its machine and folder ("This Mac ·
307
- ~/acme", "altair · ~/northwind"). Then each deployment has a tab of
308
- its own, named by its machine ("altair"; "This Mac · oats-v2" when this Mac
309
- holds two). A workspace with one deployment shows just that deployment's
310
- tab. The tab you chose is remembered per workspace. With two or more
311
- deployments, the sidebar's instance list is grouped under one heading per
312
- machine; with one, it has no headings.
560
+ - **Machines.** **Workspace › Machines** (once the Deployments page, and
561
+ the Active overview before that) shows the workspace's overview trees.
562
+ One sentence above them says what a machine is: "Each machine runs this
563
+ workspace in a folder of its own. The instances under a machine run on
564
+ that machine." **All** stacks one section per deployment, each headed by
565
+ its machine and folder ("This Mac · ~/acme", "altair · ~/northwind"),
566
+ with "Instances on this machine" or "Instances on altair" under it. Then
567
+ each deployment has a tab of its own, named by its machine ("altair";
568
+ "This Mac · oats-v2" when this Mac holds two). A workspace with one
569
+ deployment shows just that deployment's tab, its tree under the same
570
+ heading. The tab you chose is
571
+ remembered per workspace. With two or more deployments, the sidebar's
572
+ instance list is grouped under one heading per machine; with one, it has
573
+ no headings.
574
+ - **An instance's card.** Clicking an instance on the Machines tab shows
575
+ what it reports and two buttons. **Go to instance** opens its terminal tab;
576
+ for a stopped instance it reads **Start…** and opens the Start dialog.
577
+ **Go to soul** opens the soul it was spawned from on the Workspace page. It
578
+ is disabled, and says why, when that soul can't be told or shown exactly:
579
+ the instance records none, it is no longer among the deployment's souls,
580
+ several match, another soul of the deployment has the same name, or the
581
+ instance is on a deployment other than the one the Workspace page shows. Restart with… stays in the instance's menu and its panel.
313
582
  - **Not shown live.** A deployment that can't be shown live says why in a few
314
583
  words on its heading ("ssh needs a prompt", "Timed out", "OATS too old to
315
584
  report its workspace"), and **How to fix** under it gives the full sentence
@@ -318,19 +587,22 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
318
587
  needs `oats sync` or fixing in `oats-local.yaml`, or this computer's OATS
319
588
  can't read other machines. A server that can't be reached stays under the
320
589
  workspace it last reported, marked "remembered".
321
- - **The switcher.** Each workspace names its machines on one line ("This Mac ·
590
+ - **The list of workspaces.** Each workspace names its machines on one line ("This Mac ·
322
591
  altair"), with a mark when one of them isn't live.
323
592
  - **Not matched to a workspace.** A deployment that can't be matched is
324
- listed on its own under that heading in the switcher, with its machine and
325
- a short reason; choosing it opens its tab on the Deployments page. When this
593
+ listed on its own under that heading in the list, with its machine and
594
+ a short reason; choosing it opens its tab on the Machines tab. When this
326
595
  computer's OATS is too old to report workspaces, nothing can be matched:
327
596
  each deployment is listed on its own, as before, and its heading says to
328
597
  update OATS.
329
598
  - **Actions.** Everything you do to an instance goes to that instance's own
330
599
  deployment. Workspace-wide pages (Setup, Capabilities, Sync, Automations,
331
600
  Schedules, Teams configuration) act on the workspace's first deployment on
332
- this Mac, else its first, and say "On <deployment>" when there are two or
333
- more.
601
+ this Mac, else its first. None of them names it: not Souls,
602
+ Capabilities, Teams or Setup, nor the Automations page, nor a soul's, a
603
+ capability's or a team's page. The side panel names it ("On This Mac ·
604
+ ~/acme", under a soul's name) when there are two or more, as do Brain and
605
+ the Sync sheet, and the Machines tab shows each deployment on its own tab.
334
606
  - **Spawn.** With two or more deployments, the Spawn dialog asks first which
335
607
  one to spawn in (and says "Runs on" in its summary), starting on the one you last used in that workspace when it
336
608
  offers the soul, else the first that does (this Mac first). With one, it
@@ -342,7 +614,8 @@ deployment. Details are in
342
614
 
343
615
  ## Scheduling agents and wake messages
344
616
 
345
- Open **Schedules** in the selected workspace to launch a new agent on a cron,
617
+ Open **Automations › Schedules** in the selected workspace (the sidebar's
618
+ **Automations**, or ⌘3 / Ctrl+3) to launch a new agent on a cron,
346
619
  wake an existing agent with a message, or harvest its knowledge. **Schedule…**
347
620
  on a Soul roster card preselects that soul. Choose the task or message, repeat
348
621
  pattern and time zone; new agent jobs also offer harness, model, permissions
@@ -409,7 +682,7 @@ member and what each member state means. Then **Shared through Git** lists
409
682
  what the workspace declares (Members, with the host first and tagged
410
683
  **Host**, Packages and Defaults). **This computer** lists what is not shared:
411
684
  this deployment's settings, lock, CLI and instances, the member clones, and
412
- the machines that run the workspace.
685
+ the machines that run the workspace (**Registered machines**).
413
686
 
414
687
  ## A workspace's machines
415
688
 
@@ -417,7 +690,7 @@ A window offers only the machines that run its workspace: those whose
417
690
  registration reports the same workspace key as the window's deployment on this
418
691
  computer (OATS CLI with `servers-per-workspace` and `server-connect`). The
419
692
  spawn dialog's **Where to run** lists "This computer" and those machines; the
420
- Workspace › Setup tab lists them with their OATS version and whether they can
693
+ Workspace › Setup tab's **Registered machines** lists them with their OATS version and whether they can
421
694
  be reached, with **Check** and **Remove**. Registrations whose key is not known
422
695
  yet are checked once in the background after the Desktop starts.
423
696
 
@@ -438,8 +711,8 @@ saved route. A machine registered for a workspace no window shows is not
438
711
  contacted, so a machine that is switched off no longer slows every window's
439
712
  roster. Opening a window on another workspace reads its machines at once. Until
440
713
  it does, that workspace's machines are shown as they were last read, marked
441
- stale, and the switcher still lists them, not counted live. The read covers every machine again while a window
442
- shows the switcher, and on the first read after the Desktop starts. With an
714
+ stale, and the list of workspaces still lists them, not counted live. The read covers every machine again while a window
715
+ has no workspace, and on the first read after the Desktop starts. With an
443
716
  older CLI, every registered machine is read, as before.
444
717
 
445
718
  ## Instances on servers
@@ -545,6 +818,29 @@ right of its parent, and related instances are grouped together. Siblings are
545
818
  joined by a dotted line through their dots. A parent's line to its children
546
819
  runs just to the right of the dotted line, so the two never merge.
547
820
 
821
+ ## An instance's colour
822
+
823
+ An instance can have a colour, one of the soul palette's six (Sand, Sage,
824
+ Slate, Mauve, Clay, Olive). Its dot shows it wherever the instance is listed:
825
+ the sidebar, its terminal tab, the command palette and the overview. A running
826
+ instance's dot is filled with the colour, a stopped one's is a ring in it. An
827
+ instance whose state is unknown keeps the warning dot, and one without a colour
828
+ looks as before. The shape says the state, never the colour alone.
829
+
830
+ To set it, open **Instance: name and colour…** from the command palette, or
831
+ press Alt+R (⌥⌘R on macOS; Ctrl+Alt+R in the Ctrl+Alt family). It acts on the instance of the terminal you
832
+ are in, else the focused sidebar row, else the active terminal tab's instance.
833
+ The dialog shows the instance's name, which can't be changed yet, and the
834
+ colours as buttons: **None** and the six. Arrow keys move between them; Enter,
835
+ Space or a click sets the colour at once, and **Saved.** or OATS's refusal
836
+ appears under the title. The dialog stays open until you close it.
837
+
838
+ The colour is the instance's own, kept in its home by OATS
839
+ (`oats instance color`). Setting one needs OATS 0.67.0 or later on this
840
+ computer, and for an instance on a server, on that server too; until then the
841
+ buttons are disabled and the dialog says which is missing. An instance whose
842
+ home is being spawned or retired can't be given a colour meanwhile.
843
+
548
844
  ## Identity marks and harness badges
549
845
 
550
846
  Souls, capabilities and workspaces carry a coloured two-letter mark beside
@@ -597,7 +893,7 @@ unknown or unreported harness shows "?". Sources and licences are in
597
893
  | 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. |
598
894
  | 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. |
599
895
  | 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. |
600
- | 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. |
896
+ | 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. |
601
897
 
602
898
  For bugs, attach the terminal output of the app (`OATS Desktop` prints
603
899
  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),