@awebai/oats 0.69.8 → 0.69.9

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.
@@ -2,36 +2,40 @@
2
2
  name: oats-getting-started
3
3
  description: >-
4
4
  The way into OATS (Open Agent Team Specification) for a person who has only
5
- a coding agent. Asks about their project, installs OATS and OATS Desktop,
6
- then either creates a new workspace with its own setup expert soul or joins
7
- this machine to an existing workspace, and ends by spawning the workspace's
8
- setup expert, which does the rest. Offers the TUI. Use for "get started
9
- with OATS", "set up / install / adopt OATS", "join our OATS workspace", or
10
- when someone gives you this file or its URL.
5
+ a coding agent. Asks about their project, installs OATS, OATS Desktop and
6
+ the messaging CLI, signs the person in to their messaging account and
7
+ creates the workspace's team, writes a new workspace's skeleton (or joins
8
+ this machine to an existing workspace), spawns the workspace's setup
9
+ expert, which does the rest, and opens the Desktop on it. Offers the TUI.
10
+ Use for "get started with OATS", "set up / install / adopt OATS", "set up
11
+ OATS for this project", "join our OATS workspace", or when someone gives
12
+ you this file or its URL.
11
13
  ---
12
14
 
13
15
  # Getting started with OATS
14
16
 
15
17
  You are the person's own coding agent. This skill takes them from nothing to
16
18
  a running **setup expert**: an OATS agent of their workspace that does the
17
- rest of the setup with them (Git, their repositories, knowledge, messaging,
18
- their first agents). You install, ask, write a few files and spawn it. Then
19
- you are done.
19
+ rest of the setup with them (their repositories, their own coordination,
20
+ knowledge and tasks capabilities, their first agents). You install, ask,
21
+ write a few files and spawn it. Then you are done.
20
22
 
21
23
  OATS in one paragraph: a **workspace** is one Git repository declaring which
22
24
  repositories belong to an organisation and which packages it trusts. A
23
25
  **soul** is a durable agent role defined in Git; an **instance** is a soul at
24
- work, in its own home and terminal. Each workspace has a setup expert soul,
25
- `<workspace>-oats-setup-expert`, which holds the `oats.setup` capability.
26
+ work, in its own home and terminal. A new workspace's setup expert is the
27
+ `oats.framework` package's soul `oats-setup-expert`, spawned as the instance
28
+ `<workspace>-oats-setup-expert`. It holds the `oats.setup` and
29
+ `oats.onboarding` capabilities.
26
30
 
27
31
  **A machine found-list.** Your prompt may hand you a found-list, a JSON file
28
32
  whose `machine.platform` is set (oats-omarchy's installer writes one). Then
29
33
  the workspace you make is this machine's own workspace. Its setup soul is
30
- the machine's steward, `oats.machine/steward`, in place of a setup expert
31
- soul of its own, and the steward gets a global aweb address. Steps 1, 5, 6
32
- and 7 say what changes. When the found-list lists a deployment whose
33
- `steward` is `true`, this machine already has its workspace and steward:
34
- tell the person so, and stop. Wherever a later step says to ask the
34
+ the machine's steward, `oats.machine/steward`, in place of the setup expert,
35
+ and the steward gets a global aweb address. Steps 1, 5, 7, 8 and 9 say what
36
+ changes. When the found-list lists a deployment whose `steward` is `true`,
37
+ this machine already has its workspace and steward: tell the person so, and
38
+ stop. Wherever a later step says to ask the
35
39
  person, on a machine found-list you tell them what happened, as it is, and
36
40
  stop instead: the person answers nothing after step 1.
37
41
 
@@ -40,9 +44,9 @@ stop instead: the person answers nothing after step 1.
40
44
  steps yourself and read back what each did.
41
45
  - **Secrets.** The person types only what you must never hold: passwords,
42
46
  tokens and logins. Before the spawn there are two ways for that: a browser
43
- device flow you start (the GitHub login, step 3), and the exact command in
44
- their own terminal (a `sudo` or Homebrew password, an aweb invite token),
45
- which you open for them (below).
47
+ device flow you start (the GitHub login, step 3, and the messaging login,
48
+ step 5), and the exact command in their own terminal (a `sudo` or Homebrew
49
+ password, an aweb invite token), which you open for them (below).
46
50
  - Never ask for a secret in the conversation, and never write one to a file.
47
51
  - Never suggest Claude Code's `! <command>` for one: its command and output
48
52
  enter your context.
@@ -50,7 +54,7 @@ stop instead: the person answers nothing after step 1.
50
54
  command in a new shell, in the same starting folder.
51
55
  - Run each fenced block below as one command.
52
56
  - When a later block needs a value an earlier one found (`V`, `ARCH`, a
53
- path), write that value in literally.
57
+ path, the team id `T`), write that value in literally.
54
58
  - **Sandboxes.** If your harness sandboxes commands, these steps need network
55
59
  access and writes in the home folder: ask the person to approve them.
56
60
  Starting the Desktop and opening a terminal also run outside the sandbox.
@@ -75,7 +79,8 @@ stop instead: the person answers nothing after step 1.
75
79
  Only when no window opens do you give them the command to run themselves.
76
80
  - **Touch nothing you were not asked to.** Don't edit an existing
77
81
  deployment's files (`oats-local.yaml`, `oats-lock.json`, `agents/`), and
78
- don't push to a repository the person did not create in step 5.
82
+ don't push to a repository the person did not create in step 6 or name as
83
+ the workspace's host there.
79
84
 
80
85
  ## 1. Ask, in one round
81
86
 
@@ -91,28 +96,36 @@ On a machine found-list, ask the machine's round below instead of this list.
91
96
  `git:github.com/acme/acme-oats`. They get it from whoever runs that
92
97
  workspace.
93
98
  - New: the **workspace name**: lowercase letters and digits, words joined
94
- by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Also
95
- the GitHub **owner** of its repository (their user, or an organisation
96
- they can create repositories in) and the repository's name. Suggest
97
- `<workspace>-oats`. Refuse `agents`: OATS keeps instance homes in a
98
- folder of that name.
99
- - **Messaging between agents (aweb):** wanted or not (recommended: agents
100
- that can mail each other can coordinate).
101
- - New workspace: a **username** `N` for a new hosted aweb account
102
- (lowercase letters, digits and `-`), not a secret. Step 7 signs it up
103
- with no API key, and its team is `default:N.aweb.ai`. Also a name `A`
104
- for this machine's messaging root, such as `<workspace>-root`.
105
- - Existing workspace that already has it: this machine needs it before the
106
- setup expert can spawn (step 7).
99
+ by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Refuse
100
+ `agents`: OATS keeps instance homes in a folder of that name.
101
+ - **New workspace: where the workspace lives.** The workspace's files live in
102
+ one repository, its host. Three cases, from their repositories:
103
+ - **One repository (a monorepo):** the host is that repository, and the
104
+ files go at its root. Ask for its GitHub owner and name.
105
+ - **Several repositories:** a dedicated host repository, private, created
106
+ in step 6. Ask for its owner (their user, or an organisation they can
107
+ create repositories in) and name; suggest `<workspace>-oats`.
108
+ - **No repositories yet:** create their first one in step 6; it is the
109
+ host. Ask for its owner and name.
110
+
111
+ Whatever the case, if any repository of theirs is private, the host is
112
+ private: the workspace file names every member, so whoever reads it sees
113
+ the list.
114
+ - **Messaging between agents:** which messaging capability, or none. The
115
+ default, and the one this skill sets up, is aweb (`oats.aweb`):
116
+ recommended, because agents that can mail each other can coordinate. A new
117
+ workspace needs nothing more from them now: they sign in to their aweb
118
+ account, or create one, in their browser in step 5. For another messaging
119
+ capability, leave messaging out here: the setup expert adds it.
107
120
  - **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
108
121
  the one you are, if it is one of these.
109
122
  - **The deployment directory `D`:** where OATS lives on this machine. Any
110
123
  folder but their home folder itself works: ask for it, and suggest none.
111
- From OATS 0.65.0, `oats onboard` adds `D` to this computer's list of
112
- deployments (`~/.oats/config/deployments.json`, which `oats deployments`
113
- reads), so the Desktop and the TUI find it wherever it is. Write `D` everywhere
114
- below as an absolute path, with the home folder spelled out: never `~`,
115
- which the shell does not expand inside quotes.
124
+ `oats onboard` adds `D` to this computer's list of deployments
125
+ (`~/.oats/config/deployments.json`, which `oats deployments` reads), so the
126
+ Desktop and the TUI find it wherever it is. Write `D` everywhere below as
127
+ an absolute path, with the home folder spelled out: never `~`, which the
128
+ shell does not expand inside quotes.
116
129
  - **OATS Desktop:** installed and started unless they decline. **The TUI**
117
130
  (`oats tui`, a terminal client, preview): opened for them or not.
118
131
 
@@ -124,12 +137,12 @@ steward takes them up with the person later.
124
137
  - **The workspace:** a new one, the machine's own. Its name defaults to the
125
138
  hostname, lowercased, with every character outside `[a-z0-9-]` turned
126
139
  into `-` (`Ada's-Laptop` gives `ada-s-laptop`). Its repository defaults to
127
- `<github.login>/<workspace>-oats`, private. Or an existing workspace's
128
- reference.
140
+ `<github.login>/<workspace>-oats`, private, a dedicated host. Or an
141
+ existing workspace's reference.
129
142
  - **The namespace `N`:** the part of every agent's address before the `/`,
130
143
  which other people's agents use to reach this machine's agents. Default:
131
- the hostname, normalised as above, so the namespace is the machine's own. Messaging is
132
- on, and the root's name `A` is `<workspace>-root`.
144
+ the hostname, normalised as above, so the namespace is the machine's own.
145
+ Messaging is aweb, and the root's name `A` is `<workspace>-root`.
133
146
  - **The steward's name:** lowercase letters and digits, words joined by
134
147
  single `-`. Default: `steward`. It gives `R`, the steward's instance name
135
148
  here and the name in its address, `N.aweb.ai/R`. `R` is the chosen name,
@@ -148,8 +161,9 @@ steward takes them up with the person later.
148
161
  uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
149
162
  ```
150
163
 
151
- - **Versions:** Node 22 or later; Git 2.45 or later is best (older works,
152
- fetching more); `gh` 2.49 or later (step 4 uses `gh attestation`).
164
+ - **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
165
+ caches), and older Git works with whole-tree fetches; `gh` 2.49 or later
166
+ (step 4 uses `gh attestation`).
153
167
  - **The harness** they chose must be installed and logged in (`claude
154
168
  --version`, `codex --version` or `pi --version`).
155
169
  - **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
@@ -166,14 +180,29 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
166
180
  - **gh:** from GitHub's own apt or rpm repository
167
181
  (<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), because
168
182
  distributions ship versions too old for step 4.
169
- - **Node 22:** from NodeSource or a version manager when the distribution's
170
- is older.
183
+ - **Node 22:** distributions ship older ones (Debian 13 has 20, Ubuntu
184
+ 24.04 has 18). On Debian and Ubuntu, x64 or arm64, from NodeSource:
185
+
186
+ ```bash
187
+ curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
188
+ ```
189
+ - **Git 2.45 (recommended):** Debian 13's is new enough. Ubuntu 24.04
190
+ ships 2.43; on Ubuntu, x64 or arm64, from the git-core PPA:
191
+
192
+ ```bash
193
+ sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
194
+ ```
171
195
  - **Passwords:** a line that needs `sudo` goes to their own terminal,
172
196
  unless `sudo -n true` succeeds.
197
+ - **Then check again** with `node --version` and `git --version`. When
198
+ Node is still under 22 (on another distribution, or where that route does
199
+ not apply), stop: tell the person the minimum and the version found, and
200
+ go no further until they have installed it. Git under 2.45 is no stop:
201
+ tell them it works with whole-tree fetches, and go on.
173
202
  - **npm's global folder** (`npm prefix -g`) must be writable for step 4's
174
- install (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
175
- under `/usr`, as NodeSource installs it), either they run that install with
176
- `sudo` in their own terminal, or set a per-user prefix:
203
+ installs (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
204
+ under `/usr`, as NodeSource installs it), either they run those installs
205
+ with `sudo` in their own terminal, or set a per-user prefix:
177
206
  `npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
178
207
  each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
179
208
  (your shell does not reread their profile). Add that line to their shell's
@@ -188,14 +217,16 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
188
217
 
189
218
  ## 3. Log in to GitHub
190
219
 
191
- OATS reads the workspace and its repositories with Git, using the person's
192
- GitHub access. Check first:
220
+ GitHub stays where the flow needs it: the Desktop's download and its
221
+ attestation (step 4), creating and pushing the host repository (step 6), and
222
+ OATS reading the workspace and its repositories with Git (step 8). Check
223
+ first:
193
224
 
194
225
  ```bash
195
226
  gh auth status
196
227
  ```
197
228
 
198
- If it is logged in, let Git use it (without this, step 5's push and step 6
229
+ If it is logged in, let Git use it (without this, step 6's push and step 8
199
230
  fail with "could not read Username"), then go to step 4:
200
231
 
201
232
  ```bash
@@ -227,10 +258,12 @@ cat "$HOME/.oats-gh-login.txt"
227
258
  gh auth status && gh auth setup-git && rm -f "$HOME/.oats-gh-login.txt"
228
259
  ```
229
260
 
230
- The token stays in gh's store and never reaches you. SSH keys, commit
231
- signing and the DCO sign-off come later, from the setup expert.
261
+ The token stays in gh's store and never reaches you. That is all the Git
262
+ setup this needs. An SSH key, commit signing and the DCO sign-off are
263
+ optional: the setup expert's `/oats-git-setup` sets them up when Git access
264
+ is broken or the person wants them, and says plainly what it changes.
232
265
 
233
- ## 4. Install OATS Desktop, then the CLI, at the same version
266
+ ## 4. Install OATS Desktop, the CLI and the messaging CLI
234
267
 
235
268
  The Desktop accepts a band of CLI versions around its own, so install it
236
269
  first, then the CLI of the same version `V`. Find `V`, and on macOS `ARCH`:
@@ -307,14 +340,14 @@ Terminal=false
307
340
  Categories=Development;
308
341
  ```
309
342
 
310
- - **Without FUSE** (step 8's start fails with a FUSE message; Ubuntu 22.04
343
+ - **Without FUSE** (step 10's start fails with a FUSE message; Ubuntu 22.04
311
344
  and later ship without `libfuse2`), add ` --appimage-extract-and-run` after
312
- the AppImage's path in `Exec=` and in step 8's start. That needs no
345
+ the AppImage's path in `Exec=` and in step 10's start. That needs no
313
346
  `sudo`; installing `libfuse2` (`libfuse2t64` on Ubuntu 24.04) does.
314
347
  - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
315
348
  download, say so and go on.
316
349
 
317
- **Don't start the Desktop yet;** step 8 starts it on the new deployment.
350
+ **Don't start the Desktop yet;** step 10 starts it on the new deployment.
318
351
 
319
352
  **Then the CLI, and for pi its bridge:**
320
353
 
@@ -323,24 +356,150 @@ npm install -g "@awebai/oats@V" && oats version
323
356
  pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
324
357
  ```
325
358
 
326
- ## 5. The workspace
359
+ **A new workspace needs `oats.framework` 1.18.0 or later,** the release
360
+ that ships the setup expert soul. Read the installed CLI's catalog:
327
361
 
328
- **New workspace.** Create its repository, private, inside the deployment
329
- directory `D`, then write the files below in it.
330
- - **Private** is the safe default: the workspace file names every member, so
331
- whoever reads it sees the list.
332
- - **`D/<repo>` must not exist yet:** an existing folder's files would end up
333
- in the first commit.
362
+ ```bash
363
+ node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
364
+ ```
365
+
366
+ It prints the two refs, for example `oats-framework/v1.19.0 v1.33.1`. If the
367
+ framework's version (the part after the `/`) is below `1.18.0`, this OATS
368
+ release is older than this skill: stop, and tell the person to wait for the
369
+ next OATS release. Never write a setup soul into the workspace in its place.
370
+
371
+ **With aweb, the messaging CLI `aw`, and the harness's aweb channel.**
372
+ Skip this without messaging. The channel is what wakes an agent when mail
373
+ arrives: Claude
374
+ `claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
375
+ pi `pi install npm:@awebai/pi`; Codex nothing (it is woken another way, which
376
+ the setup expert sets up).
377
+
378
+ ```bash
379
+ npm install -g @awebai/aw && aw version
380
+ ```
381
+
382
+ `aw` must be 1.36.33 or later.
383
+
384
+ ## 5. Your messaging account and the workspace's team
385
+
386
+ **New workspace with aweb only.** An existing workspace joins in step 9, and
387
+ a machine found-list signs up there too: skip this step for both.
388
+
389
+ The workspace's agents share one team, its **default team**. Here the person
390
+ signs in to their own aweb account, and that account creates the team. Say
391
+ to them, in your words, exactly three things:
392
+ - you are creating a team for the workspace, owned by your aweb account;
393
+ - you sign in as yourself, in your own browser;
394
+ - every agent you spawn joins this default team. More teams are an explicit
395
+ later choice.
396
+
397
+ Don't say that the agents are attributed or bound to them: the team is owned
398
+ by their account, and tying each agent to them is a later step the setup
399
+ expert offers.
400
+
401
+ **The workspace key `K`** is the host repository's key: `github.com/<owner>/<repo>`,
402
+ with the host's owner and name from step 1 (for `acme/acme-oats`,
403
+ `github.com/acme/acme-oats`). It must be exactly this: aweb keys the team on
404
+ that string, and a different spelling makes a different team.
405
+
406
+ **Sign in.** First check whether this machine's `aw` is signed in already:
407
+
408
+ ```bash
409
+ aw auth status --json
410
+ ```
411
+
412
+ If it prints `"status": "authorized"` with an `account`, go on to the team.
413
+ Otherwise start the login yourself, detached, as with GitHub. aw prints a URL
414
+ and a one-time code, and waits:
334
415
 
335
416
  ```bash
336
- mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
417
+ nohup aw auth login </dev/null >"$HOME/.oats-aw-login.txt" 2>&1 &
337
418
  ```
338
419
 
339
- Then write the files below in `D/<repo>`, all in this one first commit.
340
- They show a workspace named `acme`, in the repository `acme/acme-oats`,
341
- with Claude as the harness and messaging for the aweb username `acme-ana`:
342
- write the person's own workspace name, repository, harness and username in
343
- their place.
420
+ A few seconds later, in a separate command:
421
+
422
+ ```bash
423
+ cat "$HOME/.oats-aw-login.txt"
424
+ ```
425
+
426
+ Open the URL in their browser and give them the code. They sign in, or
427
+ create their aweb account there, and approve. The code is not a secret, and
428
+ the login's token stays in aw's store and never reaches you. Once they say
429
+ they approved:
430
+
431
+ ```bash
432
+ aw auth status --json && rm -f "$HOME/.oats-aw-login.txt"
433
+ ```
434
+
435
+ `account.id` is the account `ACCOUNT`; `account.handle` is its name, to tell
436
+ the person.
437
+
438
+ **Create the team, with its root in `D/.aw`.** On a first run `D/.aw` must
439
+ not exist yet: if it does and this skill did not make it, stop, and ask the
440
+ person what it is. With `D`, `K`, the workspace name and `ACCOUNT` written in:
441
+
442
+ ```bash
443
+ mkdir -p "D" && test ! -e "D/.aw" && cd "D" && aw --identity-home "D/.aw" team ensure --workspace-key "K" --label "<workspace>" --expect-account "ACCOUNT" --json
444
+ ```
445
+
446
+ - **Success** prints a JSON answer. Its `canonical_team_id` is the team id
447
+ `T`, of the form `<name>:<domain>`: step 7 writes it into the workspace.
448
+ Never write its `team_id` (an internal id), and never guess `T`.
449
+ - **It installs the team's root** in `D/.aw`: the identity that adds each
450
+ agent the person spawns to the team, with no login at spawn. It holds keys:
451
+ leave it alone.
452
+ - **A failure** prints one line on stderr and exits 2:
453
+ - `authorization-required`: the login is missing or expired. Sign in
454
+ again, then rerun.
455
+ - `identity-home-occupied`: `D/.aw` holds something else. Stop and tell the
456
+ person.
457
+ - `unsupported-server`, or anything else: stop and tell the person what it
458
+ printed.
459
+ - **After an interrupted run** (killed, timed out, or its answer lost),
460
+ `D/.aw` exists, and the first-run line stops at its check. Run the same
461
+ call without that check, with exactly the same `D`, `K`, workspace name and
462
+ `ACCOUNT`: aw continues its own run, or answers `identity-home-occupied`
463
+ for anything else. Never remove or edit `D/.aw`.
464
+
465
+ ```bash
466
+ cd "D" && aw --identity-home "D/.aw" team ensure --workspace-key "K" --label "<workspace>" --expect-account "ACCOUNT" --json
467
+ ```
468
+
469
+ Tell the person the team exists, owned by their aweb account `<handle>`.
470
+
471
+ ## 6. The host repository
472
+
473
+ **New workspace,** by step 1's case. `<repo>` is the host's name.
474
+ - **A dedicated host (several repositories), or the first repository (no
475
+ repositories yet):** create it inside `D`, private unless every repository
476
+ of theirs is public. `D/<repo>` must not exist yet: an existing folder's
477
+ files would end up in the first commit.
478
+
479
+ ```bash
480
+ mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
481
+ ```
482
+ - **A monorepo:** clone it into `D`, so the setup expert's tools find it
483
+ there. If `D/<repo>` already holds a clone of it, use that clone.
484
+
485
+ ```bash
486
+ mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo clone "<owner>/<repo>" "<repo>" && git -C "<repo>" status --short --branch
487
+ ```
488
+
489
+ Its root must not hold `oats-workspace.yaml` or `oats-membership.yaml`
490
+ yet: if it does, stop and ask the person.
491
+
492
+ The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
493
+ `git:github.com/acme/acme-oats`.
494
+
495
+ **Existing workspace.** `W` is the reference they gave. Write nothing in its
496
+ repositories.
497
+
498
+ ## 7. The skeleton
499
+
500
+ **New workspace.** Write two files at the root of `D/<repo>`, in one commit.
501
+ They show a workspace named `acme`, hosted in `acme/acme-oats`, with aweb:
502
+ write the person's own workspace name, host and team id in their place.
344
503
 
345
504
  `oats-workspace.yaml`:
346
505
 
@@ -348,42 +507,33 @@ their place.
348
507
  schemaVersion: 2
349
508
  name: acme
350
509
  members:
351
- - git:github.com/acme/acme-oats # the host is a member too
510
+ - git:github.com/acme/acme-oats # the host; the setup expert adds the others
352
511
  packages:
353
- oats.framework: v1.18.0 # the installed CLI's catalog versions (below)
354
- oats.aweb: v1.32.1 # messaging, and tasks: agent identities, mail, chat and tasks
512
+ oats.framework: v1.19.0 # the installed CLI's catalog versions (below)
513
+ oats.aweb: v1.33.1 # messaging: agent identities, mail and chat
355
514
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
356
515
  defaults:
357
516
  capabilities:
358
517
  oats.core: { from: package }
359
518
  messaging: { oats.aweb: { from: package } }
360
- tasks: { oats.aweb-tasks: { from: package } } # aweb tasks: assignment, claims, status and handoff
361
519
  teams:
362
- acme: { description: The acme workspace's aweb team, team: "default:acme-ana.aweb.ai" }
520
+ acme: { description: The acme workspace's team, team: "T" }
363
521
  defaultTeam: acme # every soul starts in this team
364
522
  ```
365
523
 
366
- - **The versions** are the installed CLI's catalog's:
367
- `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`
368
- (for example `oats-framework/v1.18.0`: write the part after the `/`) and
369
- `packages."oats.aweb".ref`, but never below `v1.31.0`: that release
370
- carries `oats.aweb-tasks`, and a bare version resolves through the
371
- catalog's tag convention even when the installed catalog names an older
372
- one.
524
+ - **The versions** are the ones step 4 printed: the framework's (the part
525
+ after `oats-framework/`) and `oats.aweb`'s, but never below `v1.31.0` for
526
+ `oats.aweb`.
527
+ - **The team** is `T` from step 5, written in literally; its label (here
528
+ `acme`) is the workspace name. On a machine found-list, which signs up in
529
+ step 9, it is `default:N.aweb.ai`, with `N` the namespace from step 1.
373
530
  - **On a machine found-list only,** keep the `oats.machine` line, at the
374
- catalog's `packages."oats.machine".ref`, and write none of the
375
- `souls/<workspace>-oats-setup-expert` files below: the steward is the
376
- workspace's setup soul. Elsewhere, leave the line out.
377
- - **The team** is `default:N.aweb.ai`, with `N` the username from step 1;
378
- its label (here `acme`) is the workspace name.
379
- - **Tasks** use aweb, the same identities as messaging: agents assign,
380
- claim and hand off work as aweb tasks the person sees on the aweb
381
- dashboard. A workspace that uses Jira or Linear writes that provider in
382
- `tasks:` instead (the setup expert sets it up).
531
+ catalog's `packages."oats.machine".ref`. Elsewhere, leave it out.
383
532
  - **Without messaging,** leave out the `oats.aweb` line, the `messaging`
384
- line, the `tasks` line, `teams` and `defaultTeam`.
385
- - **Add nothing else:** knowledge and the person's own repositories come
386
- with the setup expert.
533
+ line, `teams` and `defaultTeam`.
534
+ - **Add nothing else:** no soul (the setup expert is `oats.framework`'s), no
535
+ `tasks:` default, no knowledge. The setup expert authors the workspace's
536
+ own coordination, knowledge and tasks capabilities with the person.
387
537
 
388
538
  `oats-membership.yaml`:
389
539
 
@@ -392,95 +542,27 @@ schemaVersion: 2
392
542
  workspace: git:github.com/acme/acme-oats
393
543
  ```
394
544
 
395
- `souls/acme-oats-setup-expert/soul.yaml`:
396
-
397
- ```yaml
398
- schemaVersion: 2
399
- name: acme-oats-setup-expert
400
- description: The OATS setup expert for the acme workspace — onboards machines and people, and keeps this workspace's OATS setup working.
401
- work: worktree # it changes this repository from its own worktree
402
- capabilities:
403
- oats.setup: { from: package }
404
- knowledge: none # so it spawns on a machine before knowledge is set up there
405
- launch: { harness: claude } # the harness the person chose: claude, codex or pi
406
- ```
407
-
408
- `souls/acme-oats-setup-expert/AGENTS.md`, and beside it the symlink
409
- `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`):
410
-
411
- ```markdown
412
- # acme-oats-setup-expert
413
-
414
- You are the OATS setup expert for the acme workspace. You set up and keep
415
- working this workspace's OATS: its machines, members, souls, packages,
416
- knowledge, messaging and automations. The `oats.setup` capability is your
417
- toolkit: its briefing says what the person types and what you run, and its
418
- skills hold every procedure. Start with `/oats-setup-model`. When your task
419
- is a hand-over from the getting-started skill, follow `/oats-setup-expert`,
420
- or `/oats-onboarding` if your `oats.setup` is older than 2.8.0 and lacks it.
421
- ```
422
-
423
- `souls/acme-developer/soul.yaml`, a first developer for the person's tasks:
424
-
425
- ```yaml
426
- schemaVersion: 2
427
- name: acme-developer
428
- description: A developer in the acme workspace — builds what its task asks.
429
- work: directory # its own folder; the setup expert points it at the person's repositories later
430
- knowledge: none
431
- launch: { harness: claude }
432
- ```
433
-
434
- `souls/acme-developer/AGENTS.md`, and beside it the symlink
435
- `CLAUDE.md -> AGENTS.md`:
436
-
437
- ```markdown
438
- # acme-developer
439
-
440
- You are a developer in the acme workspace. You build what your task asks,
441
- in your own `work/` directory: write the code, run it and test it. Keep the
442
- solution small and simple. When you finish, say what you built, where it is
443
- and how you checked it. If you are blocked on a decision, ask whoever gave
444
- you the task.
445
- ```
446
-
447
- **Keep the soul this thin.** Everything it knows comes from `oats.setup`, so
448
- it improves when the workspace's `oats.framework` pin moves. It has no
449
- knowledge of its own, so it can be spawned on a machine before knowledge is
450
- set up there. It takes the workspace's messaging and doesn't empty that
451
- slot: a setup soul that empties the messaging slot the workspace fills is
452
- not the workspace's operator, and gets no mail.
453
-
454
545
  **Commit and push.**
455
- - This first commit goes straight to the new repository's default branch: it
456
- is the person's own, just created. Later changes come from the setup
457
- expert, by its briefing's rule for shared files (`oats.setup`'s
458
- `/oats-workspace-config`, "Change a shared file"). From oats.setup 2.8.3
459
- (oats.framework 1.13.4), it pushes straight to the default branch when its
460
- checks show nobody else can push there and nothing guards that branch, and
461
- for a member repository only on the person's yes; otherwise it opens a
462
- pull request. An older `oats.setup` always opens one.
546
+ - **A repository created in step 6:** the first commit goes straight to its
547
+ default branch: it is the person's own, just created.
548
+ - **A monorepo:** show the person the two files first. Commit to its default
549
+ branch only on their yes. If the push is refused (a protected branch, say),
550
+ push a branch instead, open a pull request, tell them, and stop until it is
551
+ merged.
463
552
  - If `git config user.email` prints nothing, the person's Git identity is not
464
553
  set up yet. After they confirm their name, commit with
465
554
  `-c user.name="<their name>" -c user.email="<their noreply address>"`. The
466
555
  noreply address comes from
467
- `gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`. The
468
- setup expert sets up their identity properly later.
556
+ `gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`.
469
557
 
470
558
  ```bash
471
- cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, team, setup expert, developer" && git push -u origin HEAD
559
+ cd "D/<repo>" && git add oats-workspace.yaml oats-membership.yaml && git commit -m "OATS workspace acme: workspace and team" && git push -u origin HEAD
472
560
  ```
473
561
 
474
- The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
475
- `git:github.com/acme/acme-oats`.
476
-
477
- **Existing workspace.** `W` is the reference they gave. Write nothing in its
478
- repositories.
479
-
480
- ## 6. Onboard this machine
562
+ ## 8. Onboard this machine
481
563
 
482
564
  ```bash
483
- oats onboard D --workspace W
565
+ oats onboard D --workspace W --json
484
566
  ```
485
567
 
486
568
  - **Effects:** it writes `D/oats-local.yaml` and `D/agents/`, reads every
@@ -491,53 +573,73 @@ oats onboard D --workspace W
491
573
  - **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
492
574
  person whether to use it as it is or to choose another directory.
493
575
 
494
- **Find the setup expert soul, `S`.**
495
- - **From OATS 0.61.0,** the next step `oats onboard` prints names the soul
496
- that holds `oats.setup`, the workspace's setup expert (`--json`:
497
- `next.spawn`).
498
- - **Before 0.61.0,** read `oats souls --dir D --json`: the soul named
499
- `<workspace>-oats-setup-expert`, else one whose definition declares
500
- `oats.setup`.
576
+ **The setup expert, `S`, and its spawn line.** `result.next.spawn` is the
577
+ line to spawn it with. For a new workspace it names `oats.framework`'s
578
+ `oats-setup-expert` with `--name <workspace>-oats-setup-expert`; when it
579
+ carries another name or no `--name`, the text output of `oats onboard` says
580
+ why. `S` is the soul it names.
501
581
  - **On a machine found-list,** `S` is `oats.machine/steward`. An existing
502
582
  workspace that doesn't offer it: stop, and say that its owner adds
503
583
  `oats.machine` to its `packages:`.
504
- - **An existing workspace with no such soul:** stop. Show the person the soul
505
- files from step 5 and say that the workspace's owner adds them by pull
506
- request to its host repository. Once that is merged, run
507
- `oats sync --dir D` and look for `S` again.
584
+ - **An existing workspace with no setup soul** (`next.spawn` is `null`): stop.
585
+ Say that its owner pins `oats.framework` 1.18.0 or later, which ships
586
+ `oats-setup-expert`. Once that is merged, run `oats sync --dir D` and look
587
+ again.
508
588
 
509
589
  **The clone.** A soul with `work: worktree` needs a clone of its repository
510
- at `D/<repo name>`. A new workspace already has it (step 5). For an existing
511
- one, clone the repository that holds `S` with the `git clone` line
590
+ at `D/<repo name>`. `oats-setup-expert` works in a directory of its own and
591
+ needs none. For an existing workspace whose setup soul is the workspace's
592
+ own, clone the repository that holds it with the `git clone` line
512
593
  `oats onboard` printed for it, if that line says it is missing.
513
594
 
514
- **On a machine found-list, record the steward's harness** on this machine
515
- first. Its soul names none, and without this every later check (readiness,
516
- harness trust) and the spawn would use the default, pi:
595
+ **Record the setup expert's harness** on this machine. A package soul names
596
+ none, and without this every later check (readiness, harness trust) and the
597
+ spawn would use the default, pi:
517
598
 
518
599
  ```bash
519
600
  oats soul launch set S --harness <harness> --dir D --plan
520
601
  oats soul launch set S --harness <harness> --dir D
521
602
  ```
522
603
 
523
- ## 7. Hand over to the setup expert
604
+ ## 9. Messaging on this machine
605
+
606
+ Read `oats inspect --soul S --dir D --json`. Its `result.layers.messaging.id`
607
+ names the soul's messaging capability; `null` means none, and then skip this
608
+ step. Otherwise the setup expert can't spawn on this machine until that
609
+ capability is set up here. That setup is the capability's own; its readiness
610
+ names what is missing:
611
+
612
+ ```bash
613
+ oats readiness --soul S --dir D --json
614
+ ```
524
615
 
525
- **Messaging on this machine first, when the setup expert takes it.** Read
526
- `oats inspect --soul S --dir D --json`. If its `result.layers.messaging.id`
527
- is `oats.aweb`, the workspace has messaging, and the setup expert
528
- can't spawn on this machine until it has messaging too. Set it up now:
529
- 1. **Install `aw`, and the harness's aweb channel** (Claude:
530
- `claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
531
- pi: `pi install npm:@awebai/pi`; Codex: nothing). Then:
616
+ The messaging items must not report a problem. aweb, the default, is set up
617
+ as below. For another messaging capability, follow its own setup skill, and
618
+ stop if its readiness still reports a problem.
619
+
620
+ **With aweb (`oats.aweb`):**
621
+ 1. **Check:**
532
622
 
533
623
  ```bash
534
- cd "D" && oats aweb setup --soul S --install-aw --check-only --json
624
+ cd "D" && oats aweb setup --soul S --check-only --json
535
625
  ```
536
626
 
537
- Its `aw.status` must be `ok` or `done`; stop on `failed` and tell the
538
- person why. Its `defaultTeam.label` is `L`, the setup expert's team. For a new workspace it must equal the label you wrote under `teams:` (the workspace name, not the username `N`); if it differs, stop and tell the person.
539
- 2. **New workspace: sign up its aweb account and team,** with `N` and `A`
540
- from step 1. No API key, no token and nothing for the person to type.
627
+ Its `aw.status` must be `ok`. If `aw` is missing, install it and the
628
+ harness's channel as step 4 says, then check again; stop on anything else
629
+ and tell the person why. Its `defaultTeam.label` is `L`, the setup expert's team.
630
+ - **A new workspace** expects `"member": true` here: step 5 installed the
631
+ root. Then this step is done. A machine found-list skipped step 5, so
632
+ its `"member": false` here is expected: go on to item 2.
633
+ - **`"member": false` on a new workspace, without a machine found-list:**
634
+ stop, spawn nothing, and tell the person which fix applies. With
635
+ `"root": null`, there is no root in `D/.aw`: step 5's team creation did
636
+ not finish there, so run its line for an interrupted run, then check
637
+ again. With a `root`, that root is not a member of `defaultTeam.team`:
638
+ the team id step 7 wrote must be step 5's `canonical_team_id` exactly,
639
+ so correct it in `oats-workspace.yaml`, commit and push it, run
640
+ `oats sync --dir D`, then check again.
641
+ 2. **Machine found-list: sign up its aweb account and team,** with `N` and
642
+ `A` from step 1. No API key, no token and nothing for the person to type.
541
643
  Preview first, then run it:
542
644
 
543
645
  ```bash
@@ -547,12 +649,7 @@ can't spawn on this machine until it has messaging too. Set it up now:
547
649
 
548
650
  The preview does not contact aweb, so it can't tell whether `N` is free.
549
651
  If the run fails with `E_SETUP_NATIVE` (most likely the username is
550
- taken; aw's output is withheld), don't rerun yet: run
551
- `test -e "D/.aw" && echo HAS_AW`. If it prints `HAS_AW`, stop and tell the
552
- person what you saw. Otherwise ask the person for another `N`, then in
553
- `D/<repo>` change the team id in `oats-workspace.yaml` to
554
- `default:N.aweb.ai`, commit and push it, run `oats sync --dir D`, and run
555
- both lines again. Then skip items 3 and 4 and go to the check (item 5).
652
+ taken; aw's output is withheld), don't rerun.
556
653
  On a machine found-list, ask nothing: tell the person that the run
557
654
  failed, most likely because `N` is taken, and stop.
558
655
  3. **Existing workspace: the person gets an invite token** from a member of `L`, who runs
@@ -570,11 +667,10 @@ can't spawn on this machine until it has messaging too. Set it up now:
570
667
  ```text
571
668
  cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --join L --invite-stdin --name A --service U'
572
669
  ```
573
- 5. **Check,** and expect `"member": true`:
574
-
575
- ```bash
576
- cd "D" && oats aweb setup --soul S --check-only --json
577
- ```
670
+ 5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
671
+ On `"member": false`, stop and spawn nothing: tell the person the run
672
+ left this machine's root outside `L`, with what the check shows, and
673
+ don't rerun the signup or the join.
578
674
 
579
675
  The setup expert does the rest of this machine's messaging
580
676
  (`/oats-host-delivery`).
@@ -589,9 +685,9 @@ Without messaging there is no address to make: skip this. Otherwise it
589
685
  needs every one of these, and when one fails, take the fallback below:
590
686
  - a new workspace: a root that joined by invite (items 3 and 4) does not own
591
687
  the namespace, so aweb would refuse the create;
592
- - `oats.aweb` 1.33.0 or later: the `oats.aweb` row of the
688
+ - `oats.aweb` 1.34.0 or later: the `oats.aweb` row of the
593
689
  `oats inspect` you read above, `result.capabilities[].version`;
594
- - aw 1.36.48 or later: `aw.version` in the check (item 5).
690
+ - aw 1.36.48 or later: `aw.version` in the check (item 1).
595
691
 
596
692
  Plan, then create, both from `D` and with no `AWEB_API_KEY`:
597
693
 
@@ -621,13 +717,16 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
621
717
  global address because of <the reason>, and the GLOBAL residents and grant
622
718
  seats section of `/oats-aweb` moves it to one later. Never ask for a key.
623
719
 
720
+ ## 10. Spawn the setup expert, then show it
721
+
624
722
  **Write the hand-over** to `D/.oats-handover.md`. It holds no secret.
625
723
 
626
724
  ```markdown
627
725
  # Onboarding hand-over from the getting-started skill
628
726
 
629
727
  - Workspace: <workspace> (W), new | existing; deployment directory: D
630
- - Setup expert: S, harness <harness>
728
+ - Host: <owner>/<repo>, a monorepo | a dedicated host | the first repository
729
+ - Setup expert: S, instance <name>, harness <harness>
631
730
  - Machine found-list only: steward R, address N.aweb.ai/R | local team
632
731
  identity (<the fallback's reason>)
633
732
 
@@ -638,9 +737,13 @@ are cloned, knowledge tools, messaging wanted or not>
638
737
  ## Done by the getting-started skill
639
738
  - Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
640
739
  - GitHub: gh logged in over https as <login>; no SSH key or signing set up
641
- - New workspace only: repository <owner>/<repo> created, first commit pushed
642
- - Messaging: new account N signed up, or joined L by invite; root A (aw <version>, <harness>
643
- channel installed) | not set up (the setup expert has no messaging)
740
+ - New workspace only: host <owner>/<repo>, skeleton committed (pushed | in
741
+ pull request <url>)
742
+ - Messaging: <capability>, aw <version>, <harness> channel installed;
743
+ team T owned by aweb account <handle> (new workspace), or new account N
744
+ signed up (machine found-list), or joined L by invite (existing) | not set
745
+ up (the setup expert has no messaging)
746
+ - Harness channel mode: development, confirmed by OATS at each start
644
747
 
645
748
  ## Left to you
646
749
  Everything else, starting with /oats-setup-expert.
@@ -662,15 +765,23 @@ oats harness trust --dir D --harness claude
662
765
  - **Then check** that the `harness-trust` item of
663
766
  `oats readiness --soul S --dir D --json` passes.
664
767
 
665
- **Preview the spawn, read it, then spawn:**
768
+ **The channel mode.** With Claude and aweb, the setup expert starts in the
769
+ development channel mode, the default: Claude asks once at each start
770
+ whether to load the aweb channel, and OATS confirms it for you. Leave it so.
771
+ Don't set `delivery: session`. The setup expert offers the approved route,
772
+ which needs no confirmation, later (it needs `sudo`).
773
+
774
+ **Preview the spawn, read it, then spawn,** with step 8's `next.spawn` line
775
+ plus the hand-over:
666
776
 
667
777
  ```bash
668
- oats spawn S --dir D --task-file D/.oats-handover.md --preview
669
- oats spawn S --dir D --task-file D/.oats-handover.md
778
+ <next.spawn> --task-file D/.oats-handover.md --preview
779
+ <next.spawn> --task-file D/.oats-handover.md
670
780
  ```
671
781
 
672
- **On a machine found-list,** name the steward `R` (its harness was recorded
673
- in step 6). With its global address:
782
+ For example, `oats spawn oats-setup-expert --dir D --name acme-oats-setup-expert --task-file D/.oats-handover.md`.
783
+
784
+ **On a machine found-list,** name the steward `R`. With its global address:
674
785
 
675
786
  ```bash
676
787
  oats spawn S --dir D --task-file D/.oats-handover.md --name R --provider oats.aweb identity.mode=global --provider oats.aweb identity.resident=R --preview
@@ -681,30 +792,42 @@ In the fallback, or without messaging, leave out both `--provider` options.
681
792
 
682
793
  - **The preview** shows what the spawn would create. If it reports a
683
794
  problem, stop and tell the person what it says.
684
- - **The spawn** prints the instance's home `H`. Then delete the hand-over
685
- file: the home has its copy as `TASK.md`.
795
+ - **The spawn** prints the instance's home `H` and its name. Then delete the
796
+ hand-over file: the home has its copy as `TASK.md`.
686
797
  - **`E_SPAWN_INCOMPLETE`:** don't spawn again. Run `oats session inspect
687
798
  --home H --json` and tell the person what it shows.
799
+ - **`E_INSTANCE_NAME_TAKEN`** (the preview or the spawn): the setup expert
800
+ already exists, so don't spawn another. Its home `H` is in the error. It
801
+ is opened in the Desktop below; if it is stopped, start it with
802
+ `oats session start --home H`.
803
+
804
+ **The Desktop**, if installed, opens on the new deployment with the setup
805
+ expert selected. `I` is its instance name: the one the spawn printed, which is
806
+ `next.spawn`'s `--name` when it has one (after `E_INSTANCE_NAME_TAKEN`, that
807
+ `--name`). A Desktop that does not know `--instance` ignores it and opens the
808
+ deployment, so pass it always.
809
+ - **macOS:**
688
810
 
689
- ## 8. Start the Desktop and the TUI, then hand over
811
+ ```bash
812
+ open -n -a "OATS Desktop" --args --dir "D" --instance "I"
813
+ ```
690
814
 
691
- **The Desktop**, if installed, starts on the new deployment:
692
- - **macOS:** `open -n -a "OATS Desktop" --args --dir D`. If the Desktop is
693
- already running, the new launch hands `--dir` to it and exits.
815
+ If the Desktop is already running, the new launch hands `--dir` and
816
+ `--instance` to it and exits.
694
817
  - **Linux:** start it yourself through their session manager, so it gets
695
818
  their desktop session's environment, not yours (yours may carry your
696
819
  harness's variables and sandbox, and the Desktop passes its environment to
697
820
  every agent it starts):
698
821
 
699
822
  ```bash
700
- U="oats-desktop-$(date +%s)"; LOG="$(mktemp)"; systemd-run --user --collect --quiet --unit "$U" -p KillMode=process -p StandardOutput="file:$LOG" -p StandardError="file:$LOG" -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY "$HOME/.local/opt/oats-desktop/OATS-Desktop.AppImage" --dir "D" && for i in $(seq 30); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null && break; sleep 1; done; sleep 3; if pgrep -u "$(id -u)" -x oats-desktop >/dev/null; then echo STARTED; else echo FAILED; tail -n 20 "$LOG"; fi
823
+ U="oats-desktop-$(date +%s)"; LOG="$(mktemp)"; systemd-run --user --collect --quiet --unit "$U" -p KillMode=process -p StandardOutput="file:$LOG" -p StandardError="file:$LOG" -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY "$HOME/.local/opt/oats-desktop/OATS-Desktop.AppImage" --dir "D" --instance "I" && for i in $(seq 30); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null && break; sleep 1; done; sleep 3; if pgrep -u "$(id -u)" -x oats-desktop >/dev/null; then echo STARTED; else echo FAILED; tail -n 20 "$LOG"; fi
701
824
  ```
702
825
 
703
- - **`STARTED`:** it shows `D`.
826
+ - **`STARTED`:** it shows `D`, with `I` selected.
704
827
  - **A FUSE message:** see step 4, then start it again.
705
828
  - **Anything else,** or no `systemd-run`: tell the person what it printed.
706
829
  They open **OATS Desktop** from their app launcher, and it lists `D` in
707
- its switcher (from OATS 0.65.0).
830
+ its switcher.
708
831
  - **Never start it with an emptied environment** (`env -i`): it then loses
709
832
  HOME, and Git loses the person's login.
710
833
 
@@ -712,10 +835,10 @@ In the fallback, or without messaging, leave out both `--provider` options.
712
835
  their own terminal, as "How to work" says, with the command
713
836
  `oats tui --dir "D"`.
714
837
 
715
- **Tell the person where the setup expert is** (on a machine found-list, the
716
- steward, and its address), and that it continues from
717
- here: in the Desktop or the TUI you started. Without either, they reach it
718
- with `oats session attach --home H` in a terminal.
838
+ **Tell the person where the setup expert is** (its instance name; on a
839
+ machine found-list, the steward, and its address), and that it continues
840
+ from here: in the Desktop or the TUI you started. Without either, they reach
841
+ it with `oats session attach --home H` in a terminal.
719
842
 
720
843
  It will ask them only what the hand-over leaves open, and it opens a pane in
721
844
  its own window when they need to type a secret. You are done.
@@ -725,11 +848,13 @@ its own window when they need to type a secret. You are done.
725
848
  - **Ask for, read, print or store a secret,** or suggest `!` for one. If the
726
849
  person pastes one into the conversation anyway, don't repeat it, and tell
727
850
  them to rotate it.
728
- - **Overwrite or re-onboard** a deployment, or push to a repository the
729
- person did not create in step 5.
851
+ - **Overwrite or re-onboard** a deployment, touch `D/.aw`, or push to a
852
+ repository the person did not create or name as the host in step 6.
853
+ - **Guess the team id:** it comes from step 5's answer.
854
+ - **Write a setup soul into the workspace:** the setup expert is
855
+ `oats.framework`'s.
730
856
  - **The Desktop:** never download it through a browser, skip a verification
731
857
  step, strip quarantine without asking, or start it with `env -i`.
732
858
  - **Put an absolute path or a credential** in `oats-workspace.yaml`,
733
- `oats-membership.yaml` or a soul (the aweb username in the team id is not
734
- a secret).
859
+ `oats-membership.yaml` or a soul (the team id is not a secret).
735
860
  - **Spawn** before `oats onboard` confirmed the host.