@awebai/oats 0.69.21 → 0.69.22

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 (36) hide show
  1. package/docs/container.md +311 -4
  2. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  3. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  4. package/docs/desktop.md +316 -130
  5. package/docs/implementation.md +14 -1
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge-capability-authoring.md +1 -1
  8. package/docs/official-catalog.md +44 -1
  9. package/docs/packages.md +2 -2
  10. package/docs/release-lane.md +8 -6
  11. package/docs/release-notes/v0.69.22.md +221 -0
  12. package/docs/tui.md +44 -4
  13. package/docs/upgrading.md +10 -5
  14. package/package-catalog.json +1 -1
  15. package/package.json +1 -1
  16. package/packages/client/above-tested.mjs +3 -2
  17. package/packages/client/capability-list.mjs +69 -0
  18. package/packages/client/capability-origin.mjs +54 -0
  19. package/packages/client/cli-adapter.mjs +9 -1
  20. package/packages/client/deployment-data.mjs +3 -0
  21. package/packages/client/deployment-panel.mjs +2 -0
  22. package/packages/client/home-board.mjs +50 -0
  23. package/packages/client/instance-pin.mjs +28 -0
  24. package/packages/client/instance-record-outcome.mjs +31 -0
  25. package/packages/client/instance-tree.mjs +62 -20
  26. package/packages/client/keymap.mjs +11 -3
  27. package/packages/client/remote-roster.mjs +8 -1
  28. package/packages/client/roster-sections.mjs +10 -7
  29. package/packages/client/soul-role.mjs +44 -0
  30. package/packages/client/waiting-on-you.mjs +10 -0
  31. package/packages/tui/lib/actions.mjs +11 -4
  32. package/packages/tui/lib/client.mjs +3 -1
  33. package/packages/tui/lib/main.mjs +16 -2
  34. package/packages/tui/lib/model.mjs +48 -5
  35. package/packages/tui/lib/store.mjs +28 -2
  36. package/skills/oats-getting-started/SKILL.md +88 -18
package/docs/desktop.md CHANGED
@@ -270,24 +270,71 @@ workspace on a server: `name — server`).
270
270
 
271
271
  The sidebar, top to bottom: the **Workspace** heading, with **Add local
272
272
  workspace…** (the **+**) at its end, over the list of workspaces; a thin line;
273
- two pinned rows, **Workspace overview** and **Automations**, drawn like the
273
+ two pinned rows, **Home** and **Automations**, drawn like the
274
274
  instance rows (Automations shows a red dot, and says "a run failed", while a
275
275
  schedule's last run failed: see [Scheduling agents](#scheduling-agents-and-wake-messages));
276
- another line; **Instances**, a heading with the running count over the list of
277
- instances; and, over a line, the foot, one bar: at its left **N need you**, the
276
+ another line; **Agents**, a heading with the running count over the list of
277
+ agents; and, over a line, the foot, one bar: at its left **N need you**, the
278
278
  number of this workspace's agents that need input (hidden when none does;
279
279
  it takes you to the first of them, in the roster's order, expanding a collapsed
280
280
  parent or opening the Background section to show it), and at its right
281
- **New agent**, which opens Quick Open (⌘P / Alt+P, named in its tooltip) to
282
- pick a soul and then the spawn dialog, and **?**, which opens the keyboard
283
- shortcuts. The foot has no mark, no Hide sidebar button and no settings menu:
284
- ⌘B / Ctrl+Shift+B and the palette's **Sidebar: toggle (hide/show)** hide the
285
- sidebar, and the palette's **Theme: choose…**, **Font: choose…** and
286
- **Shortcuts: edit keyboard shortcuts…** open the theme, the font and the
287
- shortcuts. A window opens on the **Workspace overview** page, on its **Souls**
288
- tab: at launch, and after you choose a workspace for it. Connections is in the
289
- command palette (**Settings: Connections…**), and the palette opens with its
290
- shortcut or Ctrl+X then `k`.
281
+ **New agent**, which opens the command palette on its souls (⌘P / Alt+P,
282
+ named in its tooltip) to pick a soul and then the spawn dialog, and **?**,
283
+ which opens the keyboard shortcuts. The foot has no mark, no Hide sidebar
284
+ button and no settings menu: ⌘B / Ctrl+Shift+B and the palette's **Sidebar:
285
+ toggle (hide/show)** hide the sidebar, and the palette's **Appearance…** and
286
+ **Keyboard shortcuts…** open the two sheets for the theme and the fonts, and
287
+ for the keys. A window opens on **Home**: at launch, and after you choose a workspace
288
+ for it. Connections is in the
289
+ command palette (**Connections**, among its sections), and the palette opens with its
290
+ shortcut or the leader (Ctrl+Space) then `k`.
291
+ **Home** answers two questions on one page: what needs you, and what you
292
+ have.
293
+
294
+ - **The board.** **Needs you** lists the agents waiting on you, each with its
295
+ message, newest first; **Running** lists the live ones, newest first. A
296
+ group with nobody in it isn't shown. Stopped agents aren't on the board, and
297
+ a live agent is "running": OATS doesn't report working or idle yet, and the
298
+ Desktop doesn't guess it. There is no "New" group yet either, since nothing
299
+ records which agents stopped or finished since you last looked. Enter (or a
300
+ click) on a row opens it as it does in the roster: a running agent's
301
+ terminal, a stopped one's Start.
302
+ - **The overview.** Agents, Souls, Capabilities, Teams, Machines and Graph,
303
+ each with what you have ("You have 4 souls"). Enter opens that part of the
304
+ Workspace page on its tab (the Machines canvas stands in for the Graph for
305
+ now), and Esc there comes back to Home. Agents opens **Home › Agents**: every
306
+ agent, running or stopped, with its soul and machine, its state, and who
307
+ started it (the person it's attributed to, or the agent that spawned it).
308
+ An agent waiting on you wears the needs-input mark there too, and says
309
+ "needs you". Esc or the **‹ Home** button returns.
310
+ - **A workspace with no agents yet** shows what OATS does in two lines and
311
+ three keys (New agent, the command palette, Home), then the overview.
312
+
313
+ Home has no key of its own yet: the palette's **Home** (among its sections)
314
+ opens it. The
315
+ board never changes the roster's order: urgency is sorted on Home only.
316
+
317
+ **The command palette** (⌘K / Alt+K) is the one place to reach everything.
318
+ It lists, in order: the agents that need you (the newest first), your recent
319
+ agents (the sidebar's tree, the one you used last on top), the sections
320
+ (Home, Workspace overview and its tabs, Automations, Connections), the commands,
321
+ and one **New agent: <soul>** row per soul. Type to narrow it; `>` keeps only
322
+ the commands and `+` only the souls.
323
+
324
+ **The status line** runs along the bottom of the window. It shows the three
325
+ keys most useful where you are (in the roster: Enter, Stop and the palette;
326
+ in a terminal: the leader, close tab and the palette), says in one line why a
327
+ key could not act (the leader's line is drawn there), says what was just done
328
+ ("Workspace onboarded. The lock is written."), says when the terminal in front
329
+ loses its server and when it is back (the pane keeps its countdown and its
330
+ **Reconnect now**). It asks nothing: Stop, Start and Restart keep their
331
+ dialogs.
332
+
333
+ **The help sheet.** Press the leader (Ctrl+Space; Ctrl+X if you chose it) and a small sheet at the
334
+ bottom right lists the keys it takes where you are; the next key does its job
335
+ and the sheet goes. The leader then `?` keeps it open until Esc. To turn the
336
+ sheet off, untick **Show the help sheet when the leader is pressed** on the
337
+ Keyboard shortcuts sheet.
291
338
  The instances have no search field: to find one by name, type it in the
292
339
  command palette, which opens its terminal. ⌘F / Alt+F (**Focus the
293
340
  instance roster**) and `/` in the sidebar go to the roster's current row;
@@ -306,45 +353,49 @@ hidden; a window too narrow for it shows it narrower, and gives it back when
306
353
  the window grows again. The terminals refit as it moves, and their programs
307
354
  hear the new size once, when you let go.
308
355
 
309
- **Theme and font.** The palette's **Theme: choose…** and
310
- ⇧⌘Space / Ctrl+Shift+Space open the theme picker (White, Solarized, Dark, or
311
- This computer, which follows the computer's own theme). The font has a picker
312
- of its own, **Font: choose…** in the palette (no
313
- shortcut unless you give it one in the shortcuts editor), with two choices:
314
-
315
- - **Omarchy's font**, the default on a computer that runs Omarchy. On Linux the whole window and its
316
- terminals use the computer's monospace font, the one `omarchy font current`
317
- names and `omarchy font set` changes (fontconfig's `monospace`, on any
318
- Linux). A font changed that way shows when Desktop next starts, at the
319
- latest. On Windows it is the system's monospace font, for the window and the
320
- terminals. On macOS the choice is named **JetBrains Mono**, Omarchy's default
321
- face: the window uses it (or the system's monospace font where it is not
322
- installed), and the terminals keep Inconsolata. On every platform, instance
323
- names in the sidebar and on tabs are a little smaller in it (12px, from
324
- 12.5px), since a monospace face runs wider.
325
- - **System font**, the faces Desktop had before: the system's interface font
326
- for the window and Inconsolata in the terminals. It is the default on every
356
+ **Appearance.** The palette's **Appearance…** and ⇧⌘Space / Ctrl+Shift+Space
357
+ open the Appearance sheet, with three parts. **Theme**: System (Omarchy's theme on a computer that runs Omarchy, else
358
+ the system's light or dark setting; it was "This computer"), Dark, Light, and
359
+ More themes… (Solarized). **Font**, the terminals' font (the window's own
360
+ text is always the system's interface font):
361
+
362
+ - **This computer's monospace**, the default on a computer that runs Omarchy
363
+ (it was "Omarchy's font"). On Linux the terminals use the computer's
364
+ monospace font, the one `omarchy font current` names and `omarchy font set`
365
+ changes (fontconfig's `monospace`, on any Linux); a font changed that way
366
+ shows when Desktop next starts, at the latest. On Windows it is the system's
367
+ monospace font. It is not offered on macOS, where the terminals keep
368
+ Inconsolata.
369
+ - **System**: Inconsolata in the terminals. It is the default on every
327
370
  computer that doesn't run Omarchy (other Linux, macOS and Windows).
371
+ - **Choose…**: a font family by name, as the palette's **Terminal: set font
372
+ family…**.
373
+
374
+ And **Terminal font size**, the same size as ⌘= / Ctrl+= change. A choice
375
+ applies at once and the sheet stays open; Esc closes it.
376
+
377
+ Changed in the next release: the window's own text no longer follows the font
378
+ choice. Before, Omarchy's font made the whole window monospace; now only the
379
+ terminals use it (D2 of the Desktop UI rework).
328
380
 
329
381
  Desktop knows a computer runs Omarchy when Omarchy's theme directory
330
- (`~/.local/state/omarchy/current`) is there, the same one the **This computer**
382
+ (`~/.local/state/omarchy/current`) is there, the same one the **System**
331
383
  theme reads. A font you chose always wins over the default.
332
384
 
333
385
  The terminal's size belongs to the face its terminals are in, since the same
334
- size looks larger in a wider face. Omarchy's font in the terminals defaults to
386
+ size looks larger in a wider face. The computer's monospace in the terminals defaults to
335
387
  13px (JetBrains Mono, Omarchy's default face, at 13px), and Inconsolata, with
336
- System font, on macOS or when Omarchy's font shows System font's faces, to
388
+ System, on macOS or when the monospace shows Inconsolata, to
337
389
  15px, on every computer. A size you set is kept for that face only, and a
338
390
  font change never carries it to the other. Resetting the size or the zoom
339
391
  goes back to the default of the face in use.
340
392
 
341
393
  The computer's monospace font is used only once it draws at a fixed width.
342
- Desktop checks it at start and on each choice in the picker. Where the
394
+ Desktop checks it at start and on each choice in the sheet. Where the
343
395
  computer has no monospace font, or `monospace` names a bitmap font (which the
344
- window cannot draw), **Omarchy's font** shows System font's faces, and its row
345
- in the picker says **No monospace font on this computer: showing System
346
- font**. The choice stays Omarchy's font, so the computer's font is used once
347
- it draws.
396
+ terminals cannot draw), **This computer's monospace** shows Inconsolata, and its row
397
+ says **No monospace font on this computer: showing System**. The choice stays,
398
+ so the computer's font is used once it draws.
348
399
 
349
400
  The choice is kept on this computer, like the theme, and applies at once:
350
401
  open terminals switch font and take that face's size in place, and keep what
@@ -377,7 +428,8 @@ a choice saved for it is ignored.)
377
428
  - **The current workspace** has its circle filled, like a running
378
429
  instance's, and its name in bold; the others have the ring a stopped
379
430
  instance has. It has no background of its own: the selection's background
380
- marks the current page (Workspace overview or Automations), so the
431
+ marks the current page (Home, whose row also stands for the Workspace page it
432
+ opens, or Automations), so the
381
433
  sidebar fills one "you are here" row. A screen reader hears it as current,
382
434
  and the list's description names it, by the same name as its row.
383
435
  - **The needs-input mark.** A row has an exclamation mark (a small amber
@@ -391,7 +443,7 @@ a choice saved for it is ignored.)
391
443
  deployment that isn't live (stale, not reached, its last read failed) and
392
444
  an oats without `waiting-on-you`. The mark never moves a row: the order
393
445
  stays the same whoever waits.
394
- - **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+X then ↑ /
446
+ - **Picking a row** (a click, Enter, or the leader's ↑ / ↓, Ctrl+Space then ↑ /
395
447
  ↓, which are also ⌥↑ / ⌥↓ on macOS and Alt+↑ / Alt+↓ on Linux and Windows
396
448
  in the Alt family, the default) shows that workspace in this window, with its own tabs, layout and
397
449
  selection; one another window shows moves here ([A workspace another window
@@ -406,7 +458,7 @@ a choice saved for it is ignored.)
406
458
  Windows does it from the keyboard. It opens the workspace in its own window,
407
459
  or brings the window that shows it to the front.
408
460
  - **Keyboard.** The list is one Tab stop, Up/Down/Home/End move in it, and
409
- `w` in the sidebar, Ctrl+X then `o`, ⌥⌘O / Alt+O and the palette's
461
+ `w` in the sidebar, Ctrl+Space then `o`, ⌥⌘O / Alt+O and the palette's
410
462
  **Workspace: switch…** focus it. The full keys are in [the keyboard
411
463
  reference](../packages/desktop/docs/desktop-keyboard.md#the-list-of-workspaces).
412
464
 
@@ -454,40 +506,61 @@ other window.
454
506
 
455
507
  ## Capabilities and spawning
456
508
 
457
- **Workspace › Capabilities** is in two parts, each with its title:
458
- **Workspace defaults** (below), then **All capabilities**, what the
459
- workspace offers. Under the **All capabilities** title, a row of segments
460
- jumps to its three sections: **Workspace owned** (from the member repos, for every soul),
461
- **Repo owned** (only for souls of the same repo) and **Packages** (pinned
462
- versions). Workspace owned and Repo owned are grouped by the repository
463
- that defines each capability. The groups are headed like the Souls tab:
464
- repo name, then "member repo · host · N capabilities". The host repository
465
- comes first, then the others by name; capabilities from outside the member
466
- repos come last, under **external**. At the top right of Workspace owned,
467
- pills (**All**, then one per repository, each with its count) show one
468
- repository at a time; "N of M shown" appears while a pill or the search
469
- narrows the list.
470
-
471
- Above All capabilities, **Workspace defaults** shows what every soul of the
472
- workspace starts with, unless it turns one off. It is one panel with two
473
- groups. **Core capabilities** (at most one of each per soul) is always
474
- **Knowledge**, **Messaging** and **Tasks**. **Additional capabilities** (any
475
- number per soul) lists the other capabilities the workspace gives every soul,
476
- or says there are none. Each default is shown the same way: its tile, the
477
- capability and its source (a package and its pinned version, or a repository
478
- and "latest"). Click it to open the capability's page. An empty core slot
479
- shows **None**: there is no workspace default, and each soul chooses its
480
- own. A core capability the workspace names among its other defaults, rather
481
- than in its slot, is shown under Core, in that slot, as the kernel fills the
482
- slot with it. An additional default the workspace turned off is struck through and
483
- says "turned off by the workspace". A workspace that sets no defaults, a
484
- standalone deployment for example, shows one line saying so. The search and
485
- the repository pills never narrow or hide this section. It is read from
486
- `oats workspace status --json`: an OATS that does not report the defaults
487
- shows no such part, and the Desktop does not guess them from the souls. The
488
- defaults have no segment of their own: the segments are All capabilities'.
489
- Teams add no capabilities (removed in 0.30), so there are no team defaults
490
- to show.
509
+ **Workspace › Capabilities** lists every capability of the workspace as one
510
+ list of rows. Core capabilities (knowledge, messaging and tasks) come first,
511
+ in that order, each with a dim **core** tag; every other capability follows by
512
+ name. There are no sections, repository groups or colour marks. Each row
513
+ shows:
514
+
515
+ - the capability's name;
516
+ - who made it: a small ✓ in a circle for an official one (its tooltip says
517
+ which fact made it official: **Official: in the OATS catalog** or **Official:
518
+ from the OATS repository**), or **by** its source (a member repository's
519
+ name, or a git package's repository);
520
+ - one line of what it does (the manifest's description, cut to one line);
521
+ - its tags: **core**, **default** for one the workspace gives every soul,
522
+ **default · off** for one the workspace turns off, and **repo only** for one
523
+ only its own repository's souls can use.
524
+
525
+ A capability is official by a rule of the Desktop over what the kernel
526
+ already reports: a package the workspace pins from the catalog
527
+ (`oats workspace status` reports its source as `catalog:<id>`), or a
528
+ capability of the OATS repository itself. Its name proves nothing. The mark
529
+ says only that: it is not a trust claim, since being listed is not being
530
+ trusted. Its limit: `OATS_PACKAGE_CATALOG` can point the kernel at another
531
+ catalog file, and workspace status doesn't say which catalog was read, so an
532
+ operator who points it elsewhere sees that catalog's packages marked official.
533
+ A kernel fact for "official" is
534
+ [oats-project/oats#1981](https://github.com/oats-project/oats/issues/1981). A package's
535
+ name and version are not on this list: **Setup**'s Packages box shows them,
536
+ and so does the capability's page.
537
+
538
+ One sentence above the list says what defaults are: the capabilities the
539
+ workspace gives every soul, so its agents share one way of working. A soul
540
+ can turn a default off and choose its own instead. The sentence also says
541
+ which core slot no default fills, and names a declared default the list can't
542
+ show as a row. A workspace that sets no defaults (a standalone deployment, for
543
+ example) says so in that sentence. The search never narrows it. It is read
544
+ from `oats workspace status --json`: an OATS that doesn't report the defaults
545
+ shows no sentence and no tag, and the Desktop doesn't guess them from the
546
+ souls. The defaults are declared in the workspace file; the page only shows
547
+ them. Teams add no capabilities (removed in 0.30).
548
+
549
+ ↑ and ↓ move along the rows, and Enter opens a capability's page. The page
550
+ reads top to bottom:
551
+
552
+ - its name, its tags, and one line on where it comes from (who made it, then
553
+ the package and its pinned version, or the repository at its latest);
554
+ - **what it does**, as one paragraph;
555
+ - **Skills**: each skill's name and one line. Enter opens the whole skill in
556
+ the pane, read-only: its front matter as a table, then its text, with its
557
+ other files a press away. Esc returns to the capability;
558
+ - then, folded, each only when there is something to show: **Commands**,
559
+ **Settings** and the soul's **As <soul> resolves it** (opened from a soul),
560
+ **Triggers**, **Hooks**, **Used by**, **Comes from** (the commit,
561
+ fingerprint, path and manifest file) and **Files** (the injected
562
+ instructions and every skill file, in a tree with a reader). Enter or Space
563
+ unfolds one, and a fold stays open while the page refreshes.
491
564
 
492
565
  The round **i** button in the toolbar, beside the search (**About capabilities**), opens
493
566
  **What capabilities are**: what a capability gives a soul's instances (skills,
@@ -501,43 +574,86 @@ way of working, and a knowledge default keeps what agents learn and the
501
574
  procedures the organisation writes down for later instances; a soul can turn
502
575
  one off and name its own in its place.
503
576
  **Close** or Esc closes it and returns the focus to the button; leaving the
504
- tab or the workspace closes it too. **Workspace › Souls** has the same button
505
- at the end of its toolbar, **About souls**, which explains what a soul is.
506
-
507
- A soul's page (open a soul from **Workspace › Souls**) ends with
508
- **Instructions**, what its instances are told, read like a capability's
509
- injected instructions (a navigation tree on the left, the file on the right).
510
- The tree has two sections, a rule between them:
511
-
512
- - **Defined in this soul**: its own `AGENTS.md`, at its path in the soul's
513
- repository, and, with an OATS that reports a soul's skills, its **Skills**.
514
- Open a skill to list its files; a file opens in the reader under its
515
- repository path.
516
- - **Composed for an instance**: what an instance of this soul gets. Its
517
- **AGENTS.md**, *after spawn, with injects*, and its **Skills**, each saying
518
- where it comes from. With an OATS that lists every skill a spawn gives the
519
- instance (0.67.0 and later), the Skills are that list: the soul's own, each
520
- **From this soul**, and the ones its capabilities add, each **From** the
521
- capability. A capability's skill file opens under its place in the instance
522
- home (`.oats/modules/<capability>/…`), with **Open capability** above it. With
523
- an older OATS the skills listed are the soul's own, and a note says that the
524
- skills capabilities add are listed by a newer OATS. For a soul on another
525
- machine, the server's OATS must list them too, as for the composed
526
- AGENTS.md below.
527
-
528
- Both come from the same inspection as the rest of the page, so **Refresh**
529
- re-reads them and keeps what you had open, and your place in it. A file over
530
- 200,000 characters is shown cut, and says so.
531
-
532
- The composed **AGENTS.md** needs an OATS that composes a soul's instructions
533
- (0.46.0 and later). It is the file a spawn of this soul on this computer would
534
- write, with one entry per part (the soul's own text, then each block OATS and
535
- the soul's capabilities add, in order). Open it to read the whole document;
536
- choose a part to go to it. Each part's header says where it comes from
537
- (**From this soul** or **Injected by …**) and names its file; a capability's
538
- part has **Open capability**, and **Copy composed AGENTS.md** copies the exact
539
- file. When the soul can't be composed here, the section says so and the problem
540
- shows at the top of the page. For a soul on another machine (a server
577
+ tab or the workspace closes it too.
578
+
579
+ **Workspace › Souls** lists the souls the workspace offers. Its first line says
580
+ what a soul is. The souls are grouped by where they come from: the workspace's
581
+ own repository first, then its other member repositories, then each package,
582
+ then the external souls. Inside a group they are in kind order: maintainers,
583
+ experts, developers, operations, then the rest, each by name. The kind is read
584
+ from the soul's name (`packages/client/soul-role.mjs`): a name with a word
585
+ `setup`, `operator`, `admin`, `ops` or `operations` is operations; else a name
586
+ ending in `-maintainer`, `-expert` or `-developer` is that; else other. OATS
587
+ reports no role for a soul yet, so the name is the rule until it does
588
+ ([#1980](https://github.com/oats-project/oats/issues/1980)).
589
+
590
+ The souls show as a grid of cards or as a table: **v** (or **Grid** | **Table**
591
+ in the toolbar) switches between them, and each window remembers its choice,
592
+ also after a restart. A card shows the soul's name, what it does, how many of
593
+ its agents run, and its kind; a soul a spawn here would refuse also says why,
594
+ above its count. The table has the same souls as rows: name, what it does, kind,
595
+ agents running, harness · model, and **Ready** (or why a spawn here would be
596
+ refused; **—** when this OATS does not report it). A card or a row's name
597
+ opens the soul's page. A new agent of a soul starts from **New agent** on its
598
+ page, from Quick Open, or from the palette. Souls of a member repository that
599
+ has not confirmed its membership are listed last, under **Not available**,
600
+ with the reason; they open nothing.
601
+
602
+ A soul's page (open a soul from **Workspace › Souls**) is one column. Under its
603
+ name and what it does, a block of facts: **Harness · model** (what a spawn here
604
+ runs, and where that choice came from), **Teams** (the teams its agents may
605
+ join, the default marked; with team model v2, **Teams on this computer** folds
606
+ out the editable list), **Knowledge** (the nodes it owns and reads, when it
607
+ declares any) and **Ready**: the word, or the one thing that stops a spawn here
608
+ in one sentence, with **Details** folded under it (the problem in full and its
609
+ code, and the soul's readiness checks, read when you open it). Its capability
610
+ warnings follow. Its agents are not listed: the Souls grid and table count
611
+ them, and the roster lists them.
612
+
613
+ Then **Capabilities**, one list of rows: the core capabilities first (knowledge,
614
+ messaging, tasks), each with a dim **core** tag, then the others in the order
615
+ the workspace composes them. Each row has the capability's name, **by** where it
616
+ comes from, and one line of what it does (its description in the workspace's
617
+ catalog). Enter or a click opens the capability's page; ↑ and ↓ move between
618
+ the rows. What the soul turns off, and a core slot left empty, are one line
619
+ under the list.
620
+
621
+ Then its two prompts, as two tabs: **Soul instructions** (the soul's own
622
+ `AGENTS.md`, at its path in the soul's repository) and **Composed
623
+ instructions** (what its agents are actually told). The tabs are one stop for
624
+ Tab; ← and → (or Home and End) switch them. Each tab is a reader at a readable
625
+ width, with its sections listed on its left when the page is wide enough: the
626
+ own file's headings, the composed document's parts.
627
+
628
+ Under the tabs, **Skills** folds out the soul's skills, with an OATS that
629
+ reports them, in two sections:
630
+
631
+ - **Defined in this soul**: its own skills. Open a skill to list its files; a
632
+ file opens in the reader beside the list, under its repository path.
633
+ - **Every skill an agent gets**: each saying where it comes from. With an OATS
634
+ that lists every skill a spawn gives the agent (0.67.0 and later), that list:
635
+ the soul's own, each **From this soul**, and the ones its capabilities add,
636
+ each **From** the capability. A capability's skill file opens under its place
637
+ in the agent's home (`.oats/modules/<capability>/…`), with **Open
638
+ capability** above it. With an older OATS the skills listed are the soul's
639
+ own, and a note says that the skills capabilities add are listed by a newer
640
+ OATS. For a soul on another machine, the server's OATS must list them too, as
641
+ for the composed instructions below.
642
+
643
+ A link in either document to a listed skill file opens it there. Everything on
644
+ the page comes from the same inspection, so **Refresh** re-reads it and keeps
645
+ what you had open, and your place in it. A file over 200,000 characters is
646
+ shown cut, and says so.
647
+
648
+ The composed instructions need an OATS that composes a soul's instructions
649
+ (0.46.0 and later); without one, the tab says so. They are the `AGENTS.md` a
650
+ spawn of this soul on this computer would write, one section per part (the
651
+ soul's own text, then each block OATS and the soul's capabilities add, in
652
+ order). Each part's header says where it comes from (**From this soul** or
653
+ **Injected by …**) and names its file; a capability's part has **Open
654
+ capability**, and **Copy composed AGENTS.md** copies the exact file. When the
655
+ soul can't be composed here, the tab says so and the problem is the page's
656
+ **Ready** line. For a soul on another machine (a server
541
657
  workspace), the page shows the composed file when that machine supports it:
542
658
  this computer's OATS must be 0.49.0 or later, to pass on what each server
543
659
  reports about itself, and the server's OATS must say it composes a soul's
@@ -623,6 +739,13 @@ same themed look, and its open list follows the light or dark theme.
623
739
 
624
740
  ## Stopping and retiring
625
741
 
742
+ Stop and Retire open a centred sheet with what Desktop has read they will
743
+ do: Stop's children, and for Retire what goes (the home, the worktree and its
744
+ uncommitted work, the branch and pull request it leaves alone). After you
745
+ confirm a retire, the row reads Retiring…, then a dim "✕ name · retired" row
746
+ stays in its place for ten seconds. Start and Restart open their dialog, with
747
+ the harness, permissions and model.
748
+
626
749
  The Desktop runs one stop or retire at a time for its own requests. Another
627
750
  program using OATS at the same time, such as the `oats` command or the
628
751
  terminal client, is held off by OATS itself: from OATS 0.52.0, a stop and a
@@ -794,14 +917,21 @@ the CLI, cron semantics, observed outcomes and recovery commands.
794
917
 
795
918
  ## A workspace's teams and setup
796
919
 
797
- The Workspace › **Teams** tab has one card per team. Under its description,
920
+ The Workspace › **Teams** tab has two sections. **Workspace teams** are the
921
+ teams the workspace declares in `oats-workspace.yaml`: everyone who opens the
922
+ workspace sees them. **This computer's teams** are the teams declared only on
923
+ this computer, in its `oats-local.yaml` (the kernel's local teams), not
924
+ shared with the workspace. Each section says so in one sentence, and a team's
925
+ page lists **your agents** on it, on this computer and the machines added to
926
+ this workspace, never the team's whole membership. The Teams tab has one card per team. Under its description,
798
927
  **Default for** says whose default the team is: all souls of a repository, a
799
928
  single soul, or every soul without its own default for the default team. **May
800
929
  join** says who else may join it. Both are read from the workspace's committed
801
930
  `souls:`; a team nobody may join yet says so. The address (the team on the
802
931
  messaging provider) and the members running in it follow.
803
932
 
804
- The **Setup** tab's List view is one column. Under the workspace's name, one
933
+ The **Setup** tab is one list, in one column (its graph view went in the
934
+ Desktop UI rework). Under the workspace's name, one
805
935
  line counts its members (and those that need attention), its packages and the
806
936
  state of the lock. The next line says where the workspace is declared. An
807
937
  **Overview** says that the workspace's **host**, the repository that holds
@@ -809,9 +939,12 @@ state of the lock. The next line says where the workspace is declared. An
809
939
  packages. **For developers** (folded) explains how a repository becomes a
810
940
  member and what each member state means. Then **Shared through Git** lists
811
941
  what the workspace declares (Members, with the host first and tagged
812
- **Host**, Packages and Defaults). **This computer** lists what is not shared:
813
- this deployment's settings, lock, CLI and instances, the member clones, and
814
- the machines that run the workspace (**Registered machines**).
942
+ **Host**, Packages and Defaults). Each member's **Details** (or **Why?**, when
943
+ its handshake needs attention) opens its panel under its row: both sides of
944
+ the handshake, what it means now, its capabilities by name and the kernel's
945
+ own detail. **This computer** lists what is not shared: this deployment's
946
+ settings, lock, CLI and agents, and the member clones. The machines that run
947
+ the workspace are the **Machines** tab's.
815
948
 
816
949
  ## A workspace's machines
817
950
 
@@ -819,12 +952,17 @@ A window offers only the machines that run its workspace: those whose
819
952
  registration reports the same workspace key as the window's deployment on this
820
953
  computer (OATS CLI with `servers-per-workspace` and `server-connect`). The
821
954
  spawn dialog's **Where to run** lists "This computer" and those machines; the
822
- Workspace › Setup tab's **Registered machines** lists them with their OATS version and whether they can
823
- be reached, with **Check** and **Remove**. Registrations whose key is not known
824
- yet are checked once in the background after the Desktop starts.
955
+ Workspace › **Machines** tab lists the computers the workspace runs on: this
956
+ computer first (where the view has a deployment here: "reading…" or "not read"
957
+ until it is read), then each of those machines, with whether it can be reached
958
+ and its OATS version. A remote-only view lists its machines' deployments
959
+ instead. The Map and the roster show where agents run; the list counts none.
960
+ Enter on a machine opens it: its name, ssh host and folder,
961
+ **Check** and **Remove**. Registrations whose key is not known yet are checked
962
+ once in the background after the Desktop starts.
825
963
 
826
964
  **Add a machine to this workspace…** (the last entry of Where to run, and a
827
- button in Setup) takes an ssh host alias, a name, the folder on that machine
965
+ button on the Machines tab) takes an ssh host alias, a name, the folder on that machine
828
966
  and whether to install OATS there, and runs `oats server connect` from this
829
967
  deployment; when the workspace uses oats.aweb for messaging, it then runs `oats
830
968
  aweb connect` to join that machine to the workspace's team. Each step shows as
@@ -983,15 +1121,19 @@ and each instance linked as a sibling "sibling of" the other, after the row's
983
1121
  two lines.
984
1122
 
985
1123
  The sidebar shows the top-level instances only until you open one. An
986
- instance with children has a chevron before its name, with the number of
987
- instances under it at every depth. Click the chevron to show its group as
1124
+ instance with children has a chevron right after its name, with the number
1125
+ of instances under it at every depth, so every name at a level starts at the
1126
+ same place. Click the chevron to show its group as
988
1127
  it was drawn before, and click it again to hide the group. A click anywhere
989
1128
  else on the row still opens its terminal. From the keyboard, Right opens the
990
1129
  focused row and Left closes it. Every instance at the top of the tree, the
991
1130
  [Background section](#background-instances)'s included, starts collapsed in
992
1131
  each new window, except one still being set up or retired, or whose retire
993
1132
  failed: while its row shows that state, it has no chevron and its group
994
- stays open, so an instance under it that needs input is never hidden. An instance inside a group starts open, and each one with
1133
+ stays open, so an instance under it that needs input is never hidden. A
1134
+ group that holds a pinned instance, its top instance included, starts open
1135
+ too, so the pin is seen with its group ([Pinned instances](#pinned-instances));
1136
+ close it and it stays closed. An instance inside a group starts open, and each one with
995
1137
  children has its own chevron. What you open or close stays as you left it
996
1138
  until the window closes. **Show in roster**, `--instance` and a spawn from
997
1139
  the Desktop open the rows above the instance they show. The TUI's list still
@@ -1004,7 +1146,8 @@ changes for it. A group of related instances sits where its first instance's
1004
1146
  spawn time puts it, so spawning a child doesn't move the group, and starting
1005
1147
  or stopping an instance moves nothing. Instances spawned at the same moment
1006
1148
  are in name order, and an instance whose spawn time can't be read comes after
1007
- every one whose time can.
1149
+ every one whose time can. Pinned instances come before all of these, at every
1150
+ level ([Pinned instances](#pinned-instances)).
1008
1151
 
1009
1152
  Children that do their parent's work come first under it. When the instances'
1010
1153
  OATS has the `instance-same-work` feature, a child the kernel reports as doing
@@ -1062,7 +1205,8 @@ open.
1062
1205
 
1063
1206
  A row has no ⋯ button. Its actions (Open in split, Open pull request…,
1064
1207
  Knowledge & capabilities…, Start…, Restart with…, Stop…, Retire instance…,
1065
- Move to background or out of it ([Background instances](#background-instances)), and
1208
+ Move to background or out of it ([Background instances](#background-instances)),
1209
+ Pin to top or Unpin ([Pinned instances](#pinned-instances)), and
1066
1210
  Forget… for an instance its server no longer lists) are in the row's context
1067
1211
  menu (right-click, Shift+F10 or the ContextMenu key), as a workspace row's are.
1068
1212
  It opens where you right-click, or on the row from the keyboard; the arrow keys,
@@ -1118,6 +1262,47 @@ and for an instance on a server, on that server too. With an older OATS the
1118
1262
  sidebar lists every instance in the main tree, and the switch and the menu
1119
1263
  items are not shown.
1120
1264
 
1265
+ ## Pinned instances
1266
+
1267
+ A pinned instance is listed at the top of its machine's list, so the agents
1268
+ you come back to stay in reach. A pin changes only the order. The instance
1269
+ starts, opens, takes input and retires as any other.
1270
+
1271
+ - **The order.** Pinned instances come first at every level of the tree: the
1272
+ groups of a machine's list, the instances of a group, and the children of
1273
+ one parent. An instance counts as pinned when it or any instance below it
1274
+ is pinned. Pinning a child lifts its whole group to the top of its
1275
+ machine's list, and the path down to it rises among its siblings. A group
1276
+ that holds a pinned instance, its top instance included, doesn't start
1277
+ collapsed, so the pin is seen with its group; closed by hand, it stays
1278
+ closed until you open it. Among
1279
+ pinned instances the usual order stands: spawn time, newest first. There
1280
+ is no manual order. Under one parent, the children joined by the parent's
1281
+ line still come first ([the tree](#the-sidebars-instance-tree)). A pinned instance
1282
+ in the Background section is first in that section's own tree. A pinned
1283
+ child whose parent is on another machine is first only in its own
1284
+ machine's list. A filter never reorders the list. The command palette
1285
+ lists the instances you have focused by recency, as before, and every
1286
+ other instance in this order.
1287
+ - **The mark.** A pinned row shows a small pin after its name. A screen
1288
+ reader hears "Pinned" with the row's name. An instance that is listed
1289
+ first only because one below it is pinned carries no pin.
1290
+ - **Pinning.** A row's context menu offers **Pin to top**, or **Unpin** on a
1291
+ pinned instance, which runs `oats instance pin <name> on|off`. Each is an
1292
+ act at once, with no dialog. The row moves when the roster is next read,
1293
+ right after the change. The command palette offers **Agent: Pin to
1294
+ top** or **Agent: Unpin** for the instance the leader keys act on. An
1295
+ instance that is held (spawning, or being retired) offers neither.
1296
+ - **Shared.** The pin is kept in the instance's home, so everyone who views
1297
+ that machine sees the same pins, in the Desktop, the TUI and another
1298
+ machine's view. There is no pin of your own. Retiring a pinned instance
1299
+ removes its pin with it.
1300
+
1301
+ This needs OATS with the `instance-pin` feature on this computer, and for an
1302
+ instance on a server, on that server too. With an older OATS the list keeps
1303
+ its usual order, no row shows a pin, and the menu items and palette commands
1304
+ are not shown.
1305
+
1121
1306
  ## An instance's colour
1122
1307
 
1123
1308
  An instance can have a colour, one of the soul palette's six (Sand, Sage,
@@ -1260,11 +1445,12 @@ and adds fresh AppImage probes with `--dir <fixture> --instance smoke-probe`,
1260
1445
  asserting main's selection-request diagnostic. Repeated launches of the same
1261
1446
  arguments reach the running app. Both launches of the running fixture must
1262
1447
  open its terminal tab in the main area while keeping keyboard focus on its
1263
- roster row. Before the repeated running launch, the smoke switches to Workspace
1264
- overview, then requires that launch to reactivate the retained tab with exactly
1448
+ roster row. Before the repeated running launch, the smoke switches to Home,
1449
+ then requires that launch to reactivate the retained tab with exactly
1265
1450
  one viewer and no terminal focus event. CDP sends a key to the window;
1266
1451
  independent tmux pane/output reads prove no input reached the inert harness. The stopped fixture stays selected
1267
- only, with no tab or Start dialog, on Workspace overview. The smoke also
1452
+ only, with no tab or Start dialog, on Home (its row current and its view
1453
+ shown, since Home's row also stands for the Workspace page). The smoke also
1268
1454
  asserts that viewer cleanup restores its private tmux baseline. The fixture's
1269
1455
  workspace/member source, soul definition and inert harness executable are authored by the test-only
1270
1456
  [`launch-fixture.mjs`](../packages/desktop/test/helpers/launch-fixture.mjs).