@awebai/oats 0.69.9 → 0.69.10

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.
@@ -3,10 +3,11 @@ name: oats-getting-started
3
3
  description: >-
4
4
  The way into OATS (Open Agent Team Specification) for a person who has only
5
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.
6
+ the messaging CLI, creates the workspace's messaging account and team (with
7
+ no sign-in, or on the person's own account if they sign in), writes a new
8
+ workspace's skeleton (or joins this machine to an existing workspace),
9
+ spawns the workspace's setup expert, which does the rest, and opens the
10
+ Desktop on it. Offers the TUI.
10
11
  Use for "get started with OATS", "set up / install / adopt OATS", "set up
11
12
  OATS for this project", "join our OATS workspace", or when someone gives
12
13
  you this file or its URL.
@@ -16,56 +17,95 @@ description: >-
16
17
 
17
18
  You are the person's own coding agent. This skill takes them from nothing to
18
19
  a running **setup expert**: an OATS agent of their workspace that does the
19
- rest of the setup with them (their repositories, their own coordination,
20
- knowledge and tasks capabilities, their first agents). You install, ask,
20
+ rest of the setup with them (their repositories, their own coordination
21
+ and knowledge capabilities, a tracker they already use, their first
22
+ agents). You ask, install,
21
23
  write a few files and spawn it. Then you are done.
22
24
 
23
- OATS in one paragraph: a **workspace** is one Git repository declaring which
24
- repositories belong to an organisation and which packages it trusts. A
25
- **soul** is a durable agent role defined in Git; an **instance** is a soul at
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.
30
-
31
- **A machine found-list.** Your prompt may hand you a found-list, a JSON file
32
- whose `machine.platform` is set (oats-omarchy's installer writes one). Then
33
- the workspace you make is this machine's own workspace. Its setup soul is
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
25
+ A **workspace** is one Git repository declaring which repositories belong to
26
+ an organisation and which packages it trusts. A **soul** is a durable agent
27
+ role defined in Git; an **instance** is a soul at work, in its own home and
28
+ terminal. A new workspace's setup expert is `oats.framework`'s soul
29
+ `oats-setup-expert` (capabilities `oats.setup` and `oats.onboarding`),
30
+ spawned as `<workspace>-oats-setup-expert`.
31
+
32
+ **A machine found-list** is a JSON file in your prompt whose
33
+ `machine.platform` is set (oats-omarchy's installer writes one). The
34
+ workspace you make is then this machine's own, its setup soul is the
35
+ machine's steward, `oats.machine/steward`, in place of the setup expert, and
36
+ the steward gets a global aweb address; steps 1, 5, 7, 8 and 9 say what
36
37
  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
+ tell the person this machine already has its workspace and steward, and
38
39
  stop. Wherever a later step says to ask the
39
40
  person, on a machine found-list you tell them what happened, as it is, and
40
41
  stop instead: the person answers nothing after step 1.
41
42
 
42
43
  **How to work.**
43
44
  - **Ask first, then run.** Ask everything in one round (step 1), then run the
44
- steps yourself and read back what each did.
45
+ steps yourself and read back what each did. Touch nothing you were not
46
+ asked to (see "Never").
47
+ - **Talk to a newcomer, in everyday words.** They may not know what a
48
+ repository, Git, a terminal or a command is. Talk about their projects,
49
+ code and folders: "your agents' shared setup" (the workspace), "the setup
50
+ assistant" (the setup expert), "the group your agents talk in" (the team),
51
+ "the folder where your agents live" (`D`), and GitHub as "where your code
52
+ is kept online, so your agents and your colleagues can reach it". Unless
53
+ they ask or use the word first, don't say repository, workspace file,
54
+ soul, instance, root, harness, readiness, deployment, capability, CLI or
55
+ token, and don't show a file path, a command, an error code or raw output,
56
+ except the name the Desktop shows for the setup expert, which they click.
57
+ When a command fails, say in one sentence what it means and what you do
58
+ next. Keep a check's output and exit status for yourself
59
+ (`2>&1; echo "exit=$?"`), and don't show an expected failure as an error.
60
+ Before a step that takes over half a minute, say what it does and about
61
+ how long it takes.
62
+ - **One yes covers the changes to their computer.** Step 1's message lists
63
+ them in plain words, and their yes covers every one: don't ask again step
64
+ by step. The list, from step 2's checks: the tools you install (on Linux
65
+ per user, under `~/.local`; on macOS with Homebrew), the line that puts
66
+ them on their PATH in their shell's startup file (`~/.local/bin` on Linux;
67
+ on macOS, Homebrew's `brew shellenv` line, only when Homebrew is new), the
68
+ aweb channel plugin in Claude (Claude only) or pi's aweb extension,
69
+ without its skills (pi only), the folder where their agents
70
+ live (`D`, spelled out) marked as trusted by their coding agent, OATS
71
+ Desktop with its app-launcher entry, each system package step 2 found
72
+ missing, with what it is for, Git told to use their GitHub login (`gh auth
73
+ setup-git`, in `~/.gitconfig`), on Linux npm's per-user folder (in
74
+ `~/.npmrc`), and, for a new workspace whose host step 6 creates, the
75
+ private repository `<owner>/<repo>` on GitHub.
76
+ Name each change by what and where, not by kind: a permission check that
77
+ reads the conversation lets a step through only when their yes named it.
78
+ Never run `sudo` for something that was not on that list, even where no
79
+ password is asked; if they say no to a system package, tell them what will
80
+ not work without it.
81
+ - **When your harness's permission check stops a step on the list** and
82
+ asks the person to approve, tell them it is one of the changes they said
83
+ yes to. If it refuses the step outright, never run it another way
84
+ (another shell, a script, a window you open): ask the person once, naming
85
+ the change, whether you may make it, and try again once on their yes.
86
+ Still refused: tell them in one sentence which change is missing and what
87
+ won't work without it, and go on where you can. Never ask them to type a
88
+ command with `!`.
45
89
  - **Secrets.** The person types only what you must never hold: passwords,
46
- tokens and logins. Before the spawn there are two ways for that: a browser
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).
50
- - Never ask for a secret in the conversation, and never write one to a file.
51
- - Never suggest Claude Code's `! <command>` for one: its command and output
52
- enter your context.
53
- - **Your shell may keep nothing between commands.** Many harnesses start each
54
- command in a new shell, in the same starting folder.
55
- - Run each fenced block below as one command.
56
- - When a later block needs a value an earlier one found (`V`, `ARCH`, a
57
- path, the team id `T`), write that value in literally.
90
+ tokens and logins, by a browser device flow you start (GitHub, step 3; the
91
+ messaging login, step 5, only for the team on their own aweb account) or
92
+ by the exact command in their own terminal, which you open for them (a
93
+ `sudo` or Homebrew password, an aweb invite token; below). Never ask for a
94
+ secret in the conversation or write one to a file ("Never").
95
+ - **Your shell may keep nothing between commands** (many harnesses start
96
+ each command in a new shell, in the same starting folder). Run each fenced
97
+ block below as one command, and write in literally any value an earlier
98
+ one found (`V`, `ARCH`, a path, the team id `T`).
58
99
  - **Sandboxes.** If your harness sandboxes commands, these steps need network
59
100
  access and writes in the home folder: ask the person to approve them.
60
101
  Starting the Desktop and opening a terminal also run outside the sandbox.
61
- - **Their own terminal, opened by you.** When a command must run in the
62
- person's terminal, write it to a file (`mktemp`; it holds no secret) after
63
- a first line `export PATH="<node dir>:<oats dir>:<harness dir>:$HOME/.local/bin:$PATH"`,
102
+ - **Their own terminal, opened by you.** Write the command to a file
103
+ (`mktemp`; it holds no secret) after a first line
104
+ `export PATH="<node dir>:<oats dir>:<harness dir>:$HOME/.local/bin:$PATH"`,
64
105
  with the folders `command -v node`, `command -v oats` and `command -v
65
- <harness>` print written in (a window may load no shell startup file, so a
66
- version manager's node would be missing), and a last line
67
- `printf '\nDone: close this window.\n'; read -r _`. Then open a window
68
- that runs it, with `F` the file's path written in:
106
+ <harness>` print written in (a window may load no shell startup file), and
107
+ a last line `printf '\nDone: close this window.\n'; read -r _`. Then open
108
+ a window that runs it, with `F` the file's path written in:
69
109
  - **macOS:** `osascript -e 'tell application "Terminal" to do script "sh F"'`.
70
110
  The first time, macOS may ask the person to let you control Terminal.
71
111
  - **Linux:** `systemd-run --user --collect --quiet -p KillMode=process -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY xdg-terminal-exec sh "F"`,
@@ -73,61 +113,137 @@ stop instead: the person answers nothing after step 1.
73
113
  only that exists. Through `systemd-run` the window gets their desktop
74
114
  session's environment, not yours.
75
115
 
76
- Tell them what to type there, and ask whether the window opened: a
77
- command that started is no proof of a window. Check the result with a
116
+ Tell them what to type there, and ask whether the window opened (a
117
+ command that started is no proof of one). Check the result with a
78
118
  read-only command, never by reading the window, then delete the file.
79
- Only when no window opens do you give them the command to run themselves.
80
- - **Touch nothing you were not asked to.** Don't edit an existing
81
- deployment's files (`oats-local.yaml`, `oats-lock.json`, `agents/`), and
82
- don't push to a repository the person did not create in step 6 or name as
83
- the workspace's host there.
119
+ When no window opens: for a secret, a login or a `sudo` or Homebrew
120
+ password, give them the command to run in a terminal of their own, the
121
+ one time a person types a command; otherwise tell them what did not
122
+ happen, and leave it to the setup expert.
84
123
 
85
124
  ## 1. Ask, in one round
86
125
 
87
126
  On a machine found-list, ask the machine's round below instead of this list.
88
127
 
89
- - **The use case:** what they want agents to do.
90
- - **Their repositories and project:** which repositories agents should work
91
- in, where they are cloned on this machine, and which are private.
92
- - **Their knowledge tools:** where their team's knowledge lives today (a docs
93
- repository, a wiki, Notion, Confluence, none).
128
+ **First, step 2's checks.** They only read, so run them before the message
129
+ (not its installs): the changes to their computer that the message lists
130
+ are what they found missing.
131
+
132
+ **The message.** Ask three things, and in the same message propose
133
+ everything else as defaults they accept with "ok" or change:
134
+ 1. What they want their agents to help with (the use case), and where their
135
+ notes and documentation live today, if anywhere (a docs repository, a
136
+ wiki, Notion, Confluence).
137
+ 2. Which projects the agents should work on: the folders on this computer,
138
+ or where the code is kept online. Work out the rest yourself (where
139
+ each is cloned, whether it's private: `git -C <dir> remote -v`,
140
+ `gh repo view <owner>/<repo> --json visibility`); ask only what you
141
+ can't find.
142
+ 3. Whether they're starting fresh, or joining agents that someone on their
143
+ team already set up (then the reference that person gives them).
144
+
145
+ Then the defaults, one plain line each: the workspace name, where its two
146
+ files live (the host, in plain words: "kept with your notes-app code on
147
+ GitHub", or "in a new private space on your GitHub, `<workspace>-oats`"),
148
+ the messaging account, the folder where their agents live, OATS Desktop
149
+ installed and opened, the name on their commits (only when Git has none),
150
+ where their agents keep track of work (tasks, below), and the changes to
151
+ their computer ("How to work"). Don't ask for the GitHub
152
+ owner (below), or for the coding agent the setup expert runs on: it is you,
153
+ when you are `claude`, `codex` or `pi`. When an answer changes a default (a
154
+ name, a host, a fresh start or a join), derive every default again and show
155
+ the final values in one short message before you go on. The rules:
156
+
94
157
  - **A new workspace, or an existing one?**
95
158
  - Existing: its repository reference, for example
96
- `git:github.com/acme/acme-oats`. They get it from whoever runs that
97
- workspace.
159
+ `git:github.com/acme/acme-oats`, from whoever runs that workspace. Until
160
+ step 8, take its name from the reference's repository name without a
161
+ trailing `-oats` (`acme`), for the folder `D` only. Step 8 gives its real
162
+ name, which `A` and the setup expert's name use.
98
163
  - New: the **workspace name**: lowercase letters and digits, words joined
99
164
  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.
165
+ `agents`: OATS keeps instance homes in a folder of that name. Default:
166
+ their project's name (its repository's, or its folder's), normalised as
167
+ in the machine's round, with repeated `-` collapsed and a leading or
168
+ trailing `-` dropped (`My_App_` gives `my-app`); with no project, ask
169
+ for a name.
170
+ - **New workspace: the host,** the one repository that holds the
171
+ workspace's files:
172
+ - **One repository (a monorepo):** that repository, the files at its root;
173
+ its owner and name come from its remote.
105
174
  - **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.
175
+ in step 6 and named `<workspace>-oats`. Its owner is the one their
176
+ repositories share, when they share one; otherwise their GitHub login.
177
+ - **No repositories yet:** their first one, created in step 6, named
178
+ `<workspace>`, under their GitHub login.
179
+
180
+ The GitHub login is `gh api user --jq .login`: now, if gh is logged in,
181
+ else after step 3; until then the line says "your GitHub account". If any
182
+ repository of theirs is private, the host is private: the workspace file
183
+ names every member.
114
184
  - **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.
185
+ default, and the one this skill sets up, is aweb (`oats.aweb`): agents
186
+ that can mail each other can coordinate. For
187
+ another, leave messaging out here: the setup expert adds it. A new
188
+ workspace with aweb gets an aweb account of its own, which step 9 creates
189
+ with no sign-in:
190
+ - the messaging account's name `N`: the part of every agent's address
191
+ before the `/`, in the same form as the workspace name, default
192
+ `<workspace>-oats`. The root's name `A` is `<workspace>-root`.
193
+ - Tell them they attach themselves to that account later in the setup, with
194
+ the setup expert. Only if they want the team on their own aweb account
195
+ now, they sign in to it in their browser in step 5 instead.
120
196
  - **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
121
197
  the one you are, if it is one of these.
122
- - **The deployment directory `D`:** where OATS lives on this machine. Any
123
- folder but their home folder itself works: ask for it, and suggest none.
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.
129
- - **OATS Desktop:** installed and started unless they decline. **The TUI**
130
- (`oats tui`, a terminal client, preview): opened for them or not.
198
+ - **The deployment directory `D`:** where OATS lives on this machine.
199
+ Default: `<home>/Agents/<workspace>`; any folder but their home folder
200
+ itself works (`oats onboard` lists it in `~/.oats/config/deployments.json`,
201
+ where the Desktop and the TUI find it). Write `D` everywhere as an absolute
202
+ path, with the home folder spelled out: never `~`, which the shell does not
203
+ expand inside quotes.
204
+ - **OATS Desktop:** installed and started unless they decline. Offer the TUI
205
+ (`oats tui`, a terminal client, preview) only if they ask for a terminal
206
+ client or decline the Desktop.
207
+ - **The name on their commits:** whenever step 2's checks printed
208
+ `NO_GIT_IDENTITY`, and only for a new workspace (step 7 commits only for
209
+ one). Default: the name Git already has (`git config --global user.name`),
210
+ when it has one; else their computer account's full name
211
+ (`getent passwd "$(id -un)" | cut -d: -f5 | cut -d, -f1` on Linux, `id -F`
212
+ on macOS); when that is empty or just their login name capitalised
213
+ (`Ubuntu` for `ubuntu`), their GitHub profile name, found after step 3
214
+ (`gh api user --jq '.name // .login'`), and the line says "your GitHub
215
+ name". Step 7 uses it without asking again.
216
+ - **Tasks, a new workspace with aweb only:** where the agents track work.
217
+ The default is aweb's task list (`oats.aweb-tasks`). It gives way only to
218
+ a tracker the person already uses, which you find, never ask about. The
219
+ first message can't know their projects yet, so its line says "aweb's
220
+ task list, unless your projects already use a tracker"; once they have
221
+ named them, look, and the final-values message (above) gives the result.
222
+ A tracker is:
223
+ - **GitHub issues:** a project's GitHub repository with an issue, open or
224
+ closed, updated in the last 180 days and not opened by a bot:
225
+ `gh issue list -R <owner>/<repo> --state all --limit 1 --json number --jq length --search "updated:>=<date 180 days ago> -author:app/renovate -author:app/dependabot"`
226
+ prints `1`. Issues switched on but unused are no tracker, and so is a
227
+ repository with issues switched off (the command says they are
228
+ disabled). If gh isn't logged in yet, step 3 runs this check after its
229
+ login.
230
+ - **Jira, Linear or another tracker:** the person named it in their
231
+ answers, or ticket keys are in the project's recent branch names or
232
+ commit subjects (`git -C <dir> log -50 --format=%s`,
233
+ `git -C <dir> branch -a --format='%(refname:short)'`): one prefix
234
+ matching `[A-Z][A-Z0-9]{1,9}-[1-9][0-9]*` with two different numbers,
235
+ other than `UTF`, `SHA`, `ISO`, `RFC`, `CVE`, `ES`, `HTTP`, `TLS`,
236
+ `PEP` and `GPT`.
237
+
238
+ With a tracker, the agents keep using it: the line says so ("your agents
239
+ use your GitHub issues; the setup assistant connects them") and step 7
240
+ writes `tasks: none`; the setup expert connects the tracker with the
241
+ person later. Without one, the line says "aweb's task list, shared by your
242
+ agents". Ask only when unsure, as the final-values message's one open
243
+ line, prefilled with the answer you'd pick: ticket keys the person didn't
244
+ name, a project kept somewhere other than GitHub (its issues can't be
245
+ read), or a `gh issue list` that failed for another reason. An existing
246
+ workspace or a machine found-list has no tasks line: its owner decided.
131
247
 
132
248
  **The machine's round.** Read the found-list, then ask only these choices,
133
249
  together, each with its default and one line on what it is. Enter, or
@@ -154,32 +270,57 @@ steward takes them up with the person later.
154
270
  - **OATS Desktop:** installed and started by default; the TUI not opened.
155
271
  - **The harness:** the found-list's `harness`. Ask only when it names none,
156
272
  with the one you are as the default.
273
+ - **The name on its commits:** as in the list above, when Git has none.
274
+ - **The changes to this computer:** the list in "How to work", from step 2's
275
+ checks, as one line; "yes" covers it.
276
+
277
+ **This machine's name** (an existing workspace only, below) is its short
278
+ hostname (`hostname -s`, never the full domain name), normalised as in the
279
+ machine's round: `ada-s-laptop`. When that is a name many machines share
280
+ (`localhost`, `ubuntu`, `debian`, `fedora`, `raspberrypi`, or a model name
281
+ such as `macbook-pro`), add `-` and the first eight characters of a keyed
282
+ hash of the machine's id: `ubuntu-7d41e0c9`. Never the id itself: the whole
283
+ team sees this name, and the id is confidential (machine-id(5)). Linux:
284
+
285
+ ```bash
286
+ printf 'oats-machine-name:%s' "$(cat /etc/machine-id)" | sha256sum | cut -c1-8
287
+ ```
288
+
289
+ macOS:
290
+
291
+ ```bash
292
+ printf 'oats-machine-name:%s' "$(ioreg -rd1 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}')" | shasum -a 256 | cut -c1-8
293
+ ```
157
294
 
158
295
  ## 2. Check, and install what is missing
159
296
 
297
+ You ran this step's checks (the commands that only read) before step 1's
298
+ message. Install now what they found missing, as step 1's yes allows.
299
+ `sudo -n true` is not one of those checks: it runs after the yes, right
300
+ before the first line that needs `sudo`.
301
+
160
302
  ```bash
161
- uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
303
+ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g; { git config --global user.name && git config --global user.email; } >/dev/null || echo NO_GIT_IDENTITY
162
304
  ```
163
305
 
164
306
  - **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`).
307
+ caches; older Git works with whole-tree fetches); `gh` 2.49 or later
308
+ (step 3 uses `gh attestation`).
167
309
  - **The harness** they chose must be installed and logged in (`claude
168
310
  --version`, `codex --version` or `pi --version`).
169
311
  - **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
170
- - **Without Homebrew,** it installs in their own Terminal, which you open
171
- for them ("How to work") with the command under “Install Homebrew” on
172
- <https://brew.sh>, since it asks for their password. Then add its
312
+ - **Without Homebrew,** it asks for their password, so it installs in
313
+ their own Terminal, which you open for them ("How to work"), with the
314
+ command under “Install Homebrew” on <https://brew.sh>. Then add its
173
315
  `brew shellenv` line to their `~/.zprofile` yourself, as its “Next
174
- steps” say.
175
- - Your running process does not see their new PATH. Start each later
176
- command with `eval "$(/opt/homebrew/bin/brew shellenv)"`
177
- (`/usr/local/bin/brew` on Intel), or ask them to restart you.
316
+ steps” say, and start each later command of yours with
317
+ `eval "$(/opt/homebrew/bin/brew shellenv)"` (`/usr/local/bin/brew` on
318
+ Intel): your running process does not see their new PATH.
178
319
  - **Linux:**
179
320
  - **Packages:** the distribution's, for git and tmux.
180
321
  - **gh:** from GitHub's own apt or rpm repository
181
- (<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), because
182
- distributions ship versions too old for step 4.
322
+ (<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), not the
323
+ distribution's, which is too old.
183
324
  - **Node 22:** distributions ship older ones (Debian 13 has 20, Ubuntu
184
325
  24.04 has 18). On Debian and Ubuntu, x64 or arm64, from NodeSource:
185
326
 
@@ -192,23 +333,34 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
192
333
  ```bash
193
334
  sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
194
335
  ```
195
- - **Passwords:** a line that needs `sudo` goes to their own terminal,
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.
202
- - **npm's global folder** (`npm prefix -g`) must be writable for step 4's
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:
206
- `npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
207
- each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
208
- (your shell does not reread their profile). Add that line to their shell's
336
+ - **The Desktop's system libraries** (x64): ALSA and FUSE 2. Check:
337
+
338
+ ```bash
339
+ for l in libasound.so.2 libfuse.so.2; do PATH="$PATH:/sbin:/usr/sbin" ldconfig -p | grep -q "$l" || echo "MISSING $l"; done
340
+ ```
341
+
342
+ - **ALSA missing:** the Desktop needs it, so step 1's list names its
343
+ package: `libasound2t64` on Ubuntu 24.04 and Debian 13, `libasound2`
344
+ before them, `alsa-lib` on Fedora.
345
+ - **FUSE 2 missing:** install nothing. Step 10 starts the AppImage with
346
+ `--appimage-extract-and-run`, which needs no FUSE.
347
+ - **Passwords:** a line that needs `sudo` runs only after their yes in
348
+ step 1, and goes to their own terminal unless `sudo -n true` succeeds.
349
+ - **Then check again** with `node --version` and `git --version`. Node still
350
+ under 22 (another distribution, or where that route does not apply): stop,
351
+ tell the person the minimum and the version found, and go no further until
352
+ they have installed it. Git under 2.45 is no stop: tell them it works with
353
+ whole-tree fetches, and go on.
354
+ - **npm's global folder** must be writable for step 4's installs
355
+ (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node under
356
+ `/usr`, as NodeSource installs it), set a per-user prefix,
357
+ `npm config set prefix ~/.local`, as step 1's list said (when Node will
358
+ come from NodeSource, the list names the per-user folder and its PATH
359
+ line). Then start each later command of yours with
360
+ `export PATH="$HOME/.local/bin:$PATH"`, and add that line to their shell's
209
361
  startup file yourself, so their own terminal finds `oats` too, and tell
210
- them you did: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc`
211
- (for fish, `fish -c 'fish_add_path ~/.local/bin'` instead).
362
+ them: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc` (for fish,
363
+ `fish -c 'fish_add_path ~/.local/bin'` instead).
212
364
 
213
365
  ```bash
214
366
  RC="$HOME/.bashrc"; case "$SHELL" in *zsh) RC="$HOME/.zshrc";; esac; grep -qsF '$HOME/.local/bin' "$RC" || printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$RC"; echo "$RC"
@@ -217,25 +369,22 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
217
369
 
218
370
  ## 3. Log in to GitHub
219
371
 
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:
372
+ Check first:
224
373
 
225
374
  ```bash
226
375
  gh auth status
227
376
  ```
228
377
 
229
378
  If it is logged in, let Git use it (without this, step 6's push and step 8
230
- fail with "could not read Username"), then go to step 4:
379
+ fail with "could not read Username"), then go on below:
231
380
 
232
381
  ```bash
233
382
  gh auth setup-git
234
383
  ```
235
384
 
236
- If it is not logged in, start the login yourself, detached and without a
237
- terminal (use your harness's background mode if it has one). gh then prints
238
- a one-time code and a URL instead of opening a browser, and waits:
385
+ If not, start the login yourself, detached and without a terminal (your
386
+ harness's background mode if it has one); gh prints a one-time code and a
387
+ URL instead of opening a browser, and waits:
239
388
 
240
389
  ```bash
241
390
  nohup gh auth login --web --hostname github.com --git-protocol https --skip-ssh-key </dev/null >"$HOME/.oats-gh-login.txt" 2>&1 &
@@ -249,62 +398,125 @@ cat "$HOME/.oats-gh-login.txt"
249
398
 
250
399
  - **Give the person the code, and open the URL** in their browser
251
400
  (`open https://github.com/login/device` on macOS, `xdg-open …` on Linux;
252
- give them the URL if that fails). The code is not a secret: only their own
253
- signed-in browser can use it. They enter the code and approve. A code expires after about 15
254
- minutes; then start again.
401
+ give them the URL if that fails). They enter the code (not a secret) and
402
+ approve. It expires after about 15 minutes; then start again.
255
403
  - **Once they say they approved,** check the login and let Git use it:
256
404
 
257
405
  ```bash
258
406
  gh auth status && gh auth setup-git && rm -f "$HOME/.oats-gh-login.txt"
259
407
  ```
260
408
 
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.
265
-
266
- ## 4. Install OATS Desktop, the CLI and the messaging CLI
409
+ The token stays in gh's store and never reaches you. Now run step 1's
410
+ GitHub-issues check if it waited for this login; a tracker it finds changes
411
+ the tasks line, so tell the person in one sentence. If the check fails for
412
+ another reason (access refused, say), ask now in one line, prefilled with
413
+ their GitHub issues (`tasks: none`): never aweb's task list beside a
414
+ tracker you couldn't rule out. That is all the Git
415
+ setup this needs: an SSH key, commit signing and the DCO sign-off are the
416
+ setup expert's `/oats-git-setup`, when Git access is broken or the person
417
+ wants them.
267
418
 
268
- The Desktop accepts a band of CLI versions around its own, so install it
269
- first, then the CLI of the same version `V`. Find `V`, and on macOS `ARCH`:
419
+ **Then find the OATS version `V`,** and on macOS `ARCH`; step 4 installs the
420
+ CLI and the Desktop of this one version:
270
421
 
271
422
  ```bash
272
423
  npm view @awebai/oats version
273
424
  sysctl -n hw.optional.arm64 2>/dev/null # macOS: 1 means ARCH=arm64, otherwise ARCH=x64
274
425
  ```
275
426
 
276
- **Every step verifies before it installs.** If a download or a check fails
277
- (the release's Desktop assets can lag its npm package), skip the Desktop,
278
- say so, and go on with the CLI. Never skip a check to make it install.
427
+ **Then start the Desktop's download, in the background,** unless they
428
+ declined the Desktop or this machine has none (Linux arm64, step 4); it runs
429
+ while step 4 installs the CLI. With `V` written in, and `F` the release
430
+ file: `oats-desktop-V-linux-x86_64.AppImage` on Linux x64,
431
+ `oats-desktop-V-mac-ARCH.zip` on macOS (where `shasum -a 256 -c -` replaces
432
+ `sha256sum -c -`). It prints `VERIFIED` only when the download, the
433
+ checksum and the release's attestation all pass:
434
+
435
+ ```bash
436
+ W="$(mktemp -d)" && echo "$W" && { nohup sh -c 'cd "$1" && gh release download "vV" -R awebai/oats -p "F" -p SHA256SUMS.txt && grep " F\$" SHA256SUMS.txt | sha256sum -c - && gh attestation verify "F" --repo awebai/oats && echo VERIFIED; echo DONE' sh "$W" </dev/null >"$W.log" 2>&1 & }
437
+ ```
438
+
439
+ Write the folder it prints in as `<W>` in step 4.
440
+
441
+ ## 4. Install OATS Desktop, the CLI and the messaging CLI
442
+
443
+ The CLI and the Desktop are both of version `V` (step 3). **First the CLI,
444
+ and for pi its bridge,** while the Desktop's download runs:
445
+
446
+ ```bash
447
+ npm install -g "@awebai/oats@V" && oats version
448
+ pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
449
+ ```
450
+
451
+ **A new workspace needs `oats.framework` 1.19.0 or later** (its setup
452
+ expert attaches the person to the workspace's messaging account). Read the
453
+ installed CLI's catalog:
454
+
455
+ ```bash
456
+ 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"
457
+ ```
458
+
459
+ It prints the two refs, for example `oats-framework/v1.20.0 v1.34.0`. If the
460
+ framework's version (after the `/`) is below `1.19.0`, or with aweb
461
+ `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
462
+ skill: stop, and tell the person to wait for the next OATS
463
+ release. Never write a setup soul into the workspace in its place.
464
+
465
+ **With aweb, the messaging CLI `aw`, and the harness's aweb channel,** which
466
+ wakes an agent when mail arrives (skip this without messaging): Claude
467
+ `claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
468
+ pi `pi install npm:@awebai/pi`, then its entry in pi's `settings.json` set
469
+ to load none of the skills it bundles (OATS puts no machine-wide skills on
470
+ a computer; each agent gets its own); Codex nothing (the setup expert sets
471
+ up its wake). The pi entry, which prints it so you can check `"skills":[]`:
472
+
473
+ ```bash
474
+ node -e 'const fs=require("fs"),path=require("path"),os=require("os");const f=path.join(process.env.PI_CODING_AGENT_DIR||path.join(os.homedir(),".pi","agent"),"settings.json");const s=JSON.parse(fs.readFileSync(f,"utf8"));const ours=(e)=>(typeof e==="string"?e:e&&e.source||"").startsWith("npm:@awebai/pi");s.packages=(s.packages||[]).map((e)=>ours(e)?{...(typeof e==="object"?e:{}),source:typeof e==="string"?e:e.source,skills:[]}:e);fs.writeFileSync(f,JSON.stringify(s,null,2)+"\n");console.log(JSON.stringify(s.packages.filter(ours)))'
475
+ ```
476
+
477
+ ```bash
478
+ npm install -g @awebai/aw && aw version
479
+ ```
480
+
481
+ `aw` must be 1.36.33 or later.
279
482
 
280
- **macOS.** In one block, with `V` and `ARCH` written in. Install into
281
- `/Applications`, which needs an administrator; for a standard user, use
282
- `$HOME/Applications` (`mkdir -p "$HOME/Applications"`) in its place in every
283
- line below:
483
+ **Then the Desktop. Every step verifies before it installs.** Wait for step
484
+ 3's download, then read its log. Each run waits up to a minute; run it
485
+ again, up to five times, while the log has no `DONE` line:
284
486
 
285
487
  ```bash
286
- cd "$(mktemp -d)" && pwd &&
287
- gh release download "vV" -R awebai/oats -p "oats-desktop-V-mac-ARCH.zip" -p SHA256SUMS.txt &&
288
- grep " oats-desktop-V-mac-ARCH.zip\$" SHA256SUMS.txt | shasum -a 256 -c - &&
289
- gh attestation verify "oats-desktop-V-mac-ARCH.zip" --repo awebai/oats &&
488
+ for i in $(seq 60); do grep -qx DONE "<W>.log" && break; sleep 1; done; tail -n 5 "<W>.log"
489
+ ```
490
+
491
+ Install the Desktop only when the log has a `VERIFIED` line. If a download or
492
+ a check failed (its assets can lag the npm package), or it still has not
493
+ finished, skip the Desktop and say so. Never skip a check to
494
+ make it install, and never install or open this download before its
495
+ attestation has passed. A Desktop installed before this run stays as it is.
496
+
497
+ **macOS.** In one block, with `V` and `ARCH` written in. `/Applications`
498
+ needs an administrator; for a standard user, use `$HOME/Applications`
499
+ (`mkdir -p "$HOME/Applications"`) in its place in every line below:
500
+
501
+ ```bash
502
+ grep -qx VERIFIED "<W>.log" && cd "<W>" &&
290
503
  ditto -x -k "oats-desktop-V-mac-ARCH.zip" . &&
291
504
  codesign --verify --deep --strict "OATS Desktop.app" &&
292
505
  defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleIdentifier &&
293
506
  defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
294
507
  ```
295
508
 
296
- - **Expected:** `ai.oats.desktop` and `V`. The app is ad-hoc signed and not
297
- notarized; `codesign --verify` passing is what to expect.
298
- - **Download with `gh`, never through a browser.** `gh` sets no quarantine
299
- on what it downloads, and that copy starts from Finder. A browser download
300
- would be quarantined.
509
+ - **Expected:** `ai.oats.desktop` and `V`, with `codesign --verify` passing
510
+ (the app is ad-hoc signed and not notarized).
511
+ - **Download with `gh`, never through a browser,** which would quarantine
512
+ it; `gh`'s copy starts from Finder.
301
513
  - **Install it.** If the Desktop is running, tell the person and quit it;
302
514
  its agents keep running:
303
515
  `osascript -e 'quit app "OATS Desktop"'; for i in $(seq 20); do pgrep -xq "OATS Desktop" || break; sleep 1; done`.
304
- Then, with the folder `pwd` printed:
516
+ Then:
305
517
 
306
518
  ```bash
307
- cd "<that folder>" && rm -rf "/Applications/OATS Desktop.app" && ditto "OATS Desktop.app" "/Applications/OATS Desktop.app" && defaults read "/Applications/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
519
+ grep -qx VERIFIED "<W>.log" && test -d "<W>/OATS Desktop.app" && cd "<W>" && rm -rf "/Applications/OATS Desktop.app" && ditto "OATS Desktop.app" "/Applications/OATS Desktop.app" && defaults read "/Applications/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
308
520
  xattr -p com.apple.quarantine "/Applications/OATS Desktop.app" 2>/dev/null && echo QUARANTINED
309
521
  ```
310
522
 
@@ -312,18 +524,15 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
312
524
  if they agree (`xattr -dr com.apple.quarantine "/Applications/OATS
313
525
  Desktop.app"`): never silently.
314
526
 
315
- **Linux x64.** It needs glibc 2.34 or later (`ldd --version`). It installs
316
- per user, without sudo, and shows in the app launcher. If the Desktop is
527
+ **Linux x64.** It needs glibc 2.34 or later (`ldd --version`), installs per
528
+ user, without sudo, and shows in the app launcher. If the Desktop is
317
529
  running, tell the person and quit it first; its agents keep running:
318
530
  `pkill -o -u "$(id -u)" -x oats-desktop; for i in $(seq 20); do pgrep -u "$(id -u)" -x oats-desktop >/dev/null || break; sleep 1; done; pgrep -u "$(id -u)" -x oats-desktop >/dev/null && echo STILL_RUNNING`
319
531
  (the oldest process is the Desktop's main one). On `STILL_RUNNING`, ask the
320
532
  person to quit it.
321
533
 
322
534
  ```bash
323
- cd "$(mktemp -d)" &&
324
- gh release download "vV" -R awebai/oats -p "oats-desktop-V-linux-x86_64.AppImage" -p SHA256SUMS.txt &&
325
- grep " oats-desktop-V-linux-x86_64.AppImage\$" SHA256SUMS.txt | sha256sum -c - &&
326
- gh attestation verify "oats-desktop-V-linux-x86_64.AppImage" --repo awebai/oats &&
535
+ grep -qx VERIFIED "<W>.log" && cd "<W>" &&
327
536
  mkdir -p ~/.local/opt/oats-desktop ~/.local/share/applications &&
328
537
  install -m 755 "oats-desktop-V-linux-x86_64.AppImage" ~/.local/opt/oats-desktop/OATS-Desktop.AppImage
329
538
  ```
@@ -340,55 +549,25 @@ Terminal=false
340
549
  Categories=Development;
341
550
  ```
342
551
 
343
- - **Without FUSE** (step 10's start fails with a FUSE message; Ubuntu 22.04
344
- and later ship without `libfuse2`), add ` --appimage-extract-and-run` after
345
- the AppImage's path in `Exec=` and in step 10's start. That needs no
346
- `sudo`; installing `libfuse2` (`libfuse2t64` on Ubuntu 24.04) does.
347
- - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
348
- download, say so and go on.
552
+ - **Without FUSE 2** (step 2 printed `MISSING libfuse.so.2`; Ubuntu 22.04
553
+ and later ship without it), or when step 10's start fails with a FUSE
554
+ message, add ` --appimage-extract-and-run` after the AppImage's path in
555
+ `Exec=` and in step 10's start.
556
+ - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop and no
557
+ download: say so and go on.
349
558
 
350
559
  **Don't start the Desktop yet;** step 10 starts it on the new deployment.
351
560
 
352
- **Then the CLI, and for pi its bridge:**
353
-
354
- ```bash
355
- npm install -g "@awebai/oats@V" && oats version
356
- pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
357
- ```
358
-
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:
361
-
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
- ```
561
+ ## 5. Optional: the team on your own aweb account
381
562
 
382
- `aw` must be 1.36.33 or later.
563
+ **Only for a new workspace with aweb whose person chose, in step 1, the team
564
+ on their own aweb account now.** Otherwise skip it: step 9 creates the
565
+ workspace's account (the default), joins an existing workspace and signs up a machine
566
+ found-list.
383
567
 
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:
568
+ The workspace's agents share one team, its **default team**, which the
569
+ person's own aweb account creates here. Say to them, in your words, exactly
570
+ three things:
392
571
  - you are creating a team for the workspace, owned by your aweb account;
393
572
  - you sign in as yourself, in your own browser;
394
573
  - every agent you spawn joins this default team. More teams are an explicit
@@ -398,10 +577,9 @@ Don't say that the agents are attributed or bound to them: the team is owned
398
577
  by their account, and tying each agent to them is a later step the setup
399
578
  expert offers.
400
579
 
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.
580
+ **The workspace key `K`** is exactly `github.com/<owner>/<repo>`, the host's
581
+ owner and name from step 1 (`github.com/acme/acme-oats`): a different
582
+ spelling makes a different team.
405
583
 
406
584
  **Sign in.** First check whether this machine's `aw` is signed in already:
407
585
 
@@ -409,9 +587,9 @@ that string, and a different spelling makes a different team.
409
587
  aw auth status --json
410
588
  ```
411
589
 
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:
590
+ With `"status": "authorized"` and an `account`, go on to the team. Otherwise
591
+ start the login yourself, detached, as with GitHub; aw prints a URL and a
592
+ one-time code, and waits:
415
593
 
416
594
  ```bash
417
595
  nohup aw auth login </dev/null >"$HOME/.oats-aw-login.txt" 2>&1 &
@@ -423,10 +601,9 @@ A few seconds later, in a separate command:
423
601
  cat "$HOME/.oats-aw-login.txt"
424
602
  ```
425
603
 
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:
604
+ Open the URL in their browser and give them the code (not a secret). They
605
+ sign in, or create their aweb account there, and approve; the token stays in
606
+ aw's store. Once they say they approved:
430
607
 
431
608
  ```bash
432
609
  aw auth status --json && rm -f "$HOME/.oats-aw-login.txt"
@@ -436,29 +613,26 @@ aw auth status --json && rm -f "$HOME/.oats-aw-login.txt"
436
613
  the person.
437
614
 
438
615
  **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
616
+ not exist: if it does and this skill did not make it, stop and ask the
440
617
  person what it is. With `D`, `K`, the workspace name and `ACCOUNT` written in:
441
618
 
442
619
  ```bash
443
620
  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
621
  ```
445
622
 
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.
623
+ - **Success** prints JSON whose `canonical_team_id` is the team id `T`
624
+ (`<name>:<domain>`), which step 7 writes into the workspace. Never write
625
+ its `team_id` (an internal id), and never guess `T`.
626
+ - **It installs the team's root** in `D/.aw`, which adds each agent the
627
+ person spawns to the team, with no login. It holds keys: leave it alone.
452
628
  - **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.
629
+ `authorization-required` (the login is missing or expired): sign in again,
630
+ then rerun; `identity-home-occupied` (`D/.aw` holds something else),
631
+ `unsupported-server` or anything else: stop and tell the person what it
632
+ printed.
459
633
  - **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
634
+ `D/.aw` exists and the first-run line stops at its check. Run the call
635
+ without that check, with exactly the same `D`, `K`, workspace name and
462
636
  `ACCOUNT`: aw continues its own run, or answers `identity-home-occupied`
463
637
  for anything else. Never remove or edit `D/.aw`.
464
638
 
@@ -470,17 +644,16 @@ Tell the person the team exists, owned by their aweb account `<handle>`.
470
644
 
471
645
  ## 6. The host repository
472
646
 
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.
647
+ **New workspace,** by step 1's case; `<repo>` is the host's name.
648
+ - **A dedicated host, or the first repository:** create it inside `D`,
649
+ private unless every repository of theirs is public. `D/<repo>` must not
650
+ exist yet: its files would end up in the first commit.
478
651
 
479
652
  ```bash
480
653
  mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
481
654
  ```
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.
655
+ - **A monorepo:** clone it into `D`, where the setup expert's tools find it,
656
+ or use the clone of it already at `D/<repo>`.
484
657
 
485
658
  ```bash
486
659
  mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo clone "<owner>/<repo>" "<repo>" && git -C "<repo>" status --short --branch
@@ -489,17 +662,17 @@ Tell the person the team exists, owned by their aweb account `<handle>`.
489
662
  Its root must not hold `oats-workspace.yaml` or `oats-membership.yaml`
490
663
  yet: if it does, stop and ask the person.
491
664
 
492
- The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
493
- `git:github.com/acme/acme-oats`.
665
+ The workspace reference `W` is then `git:github.com/<owner>/<repo>`
666
+ (`git:github.com/acme/acme-oats`).
494
667
 
495
668
  **Existing workspace.** `W` is the reference they gave. Write nothing in its
496
669
  repositories.
497
670
 
498
671
  ## 7. The skeleton
499
672
 
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.
673
+ **New workspace.** Write two files at the root of `D/<repo>`, in one commit,
674
+ with the person's own workspace name, host and team id in place of the
675
+ example's (`acme`, hosted in `acme/acme-oats`, with aweb).
503
676
 
504
677
  `oats-workspace.yaml`:
505
678
 
@@ -509,31 +682,33 @@ name: acme
509
682
  members:
510
683
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
511
684
  packages:
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
685
+ oats.framework: v1.20.0 # the installed CLI's catalog versions (below)
686
+ oats.aweb: v1.34.0 # messaging: agent identities, mail and chat
514
687
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
515
688
  defaults:
516
689
  capabilities:
517
690
  oats.core: { from: package }
518
691
  messaging: { oats.aweb: { from: package } }
692
+ tasks: { oats.aweb-tasks: { from: package } } # or `tasks: none` (step 1)
519
693
  teams:
520
694
  acme: { description: The acme workspace's team, team: "T" }
521
695
  defaultTeam: acme # every soul starts in this team
522
696
  ```
523
697
 
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.
530
- - **On a machine found-list only,** keep the `oats.machine` line, at the
531
- catalog's `packages."oats.machine".ref`. Elsewhere, leave it out.
698
+ - **The versions** are the ones step 4 printed: the framework's (after
699
+ `oats-framework/`) and `oats.aweb`'s, that one never below `v1.33.1`.
700
+ - **The team** is `default:N.aweb.ai`, with `N` from step 1: the team step
701
+ 9's signup creates, checked there against this line. With step 5's
702
+ sign-in, it is `T` from step 5 instead, written in literally. Its label
703
+ (here `acme`) is the workspace name.
704
+ - **The `oats.machine` line,** at the catalog's
705
+ `packages."oats.machine".ref`, only on a machine found-list.
706
+ - **The `tasks` line** is step 1's tasks answer: `oats.aweb-tasks` without
707
+ a tracker, `tasks: none` with one. On a machine found-list, leave it out.
532
708
  - **Without messaging,** leave out the `oats.aweb` line, the `messaging`
533
- line, `teams` and `defaultTeam`.
709
+ line, the `tasks` line, `teams` and `defaultTeam`.
534
710
  - **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.
711
+ knowledge; the setup expert authors those with the person.
537
712
 
538
713
  `oats-membership.yaml`:
539
714
 
@@ -543,17 +718,16 @@ workspace: git:github.com/acme/acme-oats
543
718
  ```
544
719
 
545
720
  **Commit and push.**
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.
552
- - If `git config user.email` prints nothing, the person's Git identity is not
553
- set up yet. After they confirm their name, commit with
554
- `-c user.name="<their name>" -c user.email="<their noreply address>"`. The
555
- noreply address comes from
556
- `gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`.
721
+ - **A repository created in step 6:** straight to its default branch (it
722
+ is the person's own, just created).
723
+ - **A monorepo:** show the person the two files first, and commit to its
724
+ default branch only on their yes. If the push is refused (a protected
725
+ branch, say), push a branch, open a pull request, tell them, and stop until
726
+ it is merged.
727
+ - If `git config user.name` or `git config user.email` prints nothing in
728
+ `D/<repo>`, commit with the name step 1's yes covered:
729
+ `-c user.name="<their name>" -c user.email="<their noreply address>"`,
730
+ the address from `gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`.
557
731
 
558
732
  ```bash
559
733
  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
@@ -567,32 +741,34 @@ oats onboard D --workspace W --json
567
741
 
568
742
  - **Effects:** it writes `D/oats-local.yaml` and `D/agents/`, reads every
569
743
  member over Git and locks the packages.
570
- - **The host must be `confirmed`.** Another member with `cannot-read` is an
571
- access question for the setup expert, not a reason to stop. A host that
572
- can't be read is a GitHub access problem (step 3).
744
+ - **The host must be `confirmed`;** a host that can't be read is a GitHub
745
+ access problem (step 3). Another member with `cannot-read` is an access
746
+ question for the setup expert, not a reason to stop.
573
747
  - **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
574
748
  person whether to use it as it is or to choose another directory.
575
749
 
576
750
  **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.
751
+ line to spawn it with, and `S` is the soul it names. For a new workspace
752
+ that is `oats.framework`'s `oats-setup-expert` with
753
+ `--name <workspace>-oats-setup-expert`; for another name or no `--name`,
754
+ the text output of `oats onboard` says why.
755
+ - **An existing workspace's name** is its `--name` without the trailing
756
+ `-oats-setup-expert` or `-oats-setup` (`acme`); with no `--name` there,
757
+ keep step 1's.
581
758
  - **On a machine found-list,** `S` is `oats.machine/steward`. An existing
582
759
  workspace that doesn't offer it: stop, and say that its owner adds
583
760
  `oats.machine` to its `packages:`.
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.
588
-
589
- **The clone.** A soul with `work: worktree` needs a clone of its repository
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
593
- `oats onboard` printed for it, if that line says it is missing.
594
-
595
- **Record the setup expert's harness** on this machine. A package soul names
761
+ - **An existing workspace with no setup soul** (`next.spawn` is `null`):
762
+ stop, and say that its owner pins `oats.framework` 1.19.0 or later, whose
763
+ `oats-setup-expert` attaches the person to the account. Once that is merged, run `oats sync --dir D` and
764
+ look again.
765
+
766
+ **The clone.** `oats-setup-expert` needs none. A soul with `work: worktree`
767
+ needs a clone of its repository at `D/<repo name>`: for an existing
768
+ workspace whose setup soul is its own, run the `git clone` line
769
+ `oats onboard` printed for it, if it says it is missing.
770
+
771
+ **Record the setup expert's harness** on this machine: a package soul names
596
772
  none, and without this every later check (readiness, harness trust) and the
597
773
  spawn would use the default, pi:
598
774
 
@@ -604,18 +780,17 @@ oats soul launch set S --harness <harness> --dir D
604
780
  ## 9. Messaging on this machine
605
781
 
606
782
  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:
783
+ names the soul's messaging capability; with `null` (none), skip this step.
784
+ Otherwise the setup expert can't spawn here until that capability is set
785
+ up; its readiness names what is missing:
611
786
 
612
787
  ```bash
613
788
  oats readiness --soul S --dir D --json
614
789
  ```
615
790
 
616
791
  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.
792
+ below; for another capability, follow its own setup skill, and stop if its
793
+ readiness still reports a problem.
619
794
 
620
795
  **With aweb (`oats.aweb`):**
621
796
  1. **Check:**
@@ -624,68 +799,97 @@ stop if its readiness still reports a problem.
624
799
  cd "D" && oats aweb setup --soul S --check-only --json
625
800
  ```
626
801
 
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
802
+ Its `aw.status` must be `ok` (`aw` missing: install it and the harness's
803
+ channel as in step 4, then check again; anything else: stop and tell the
804
+ person why). Its `defaultTeam.label` is `L`, the setup expert's team.
805
+ - **A new workspace that signed in at step 5** expects `"member": true`
806
+ here: step 5 installed the root. Then this step is done.
807
+ Every other new workspace (the default, and a machine found-list)
808
+ has no root yet, so its `"member": false` here is expected: go on to
809
+ item 2.
810
+ - **`"member": false` after step 5's sign-in:** stop, spawn nothing, and
811
+ tell the person which fix applies. With
635
812
  `"root": null`, there is no root in `D/.aw`: step 5's team creation did
636
813
  not finish there, so run its line for an interrupted run, then check
637
814
  again. With a `root`, that root is not a member of `defaultTeam.team`:
638
815
  the team id step 7 wrote must be step 5's `canonical_team_id` exactly,
639
816
  so correct it in `oats-workspace.yaml`, commit and push it, run
640
817
  `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.
643
- Preview first, then run it:
818
+ 2. **A new workspace without step 5's sign-in, and a machine found-list:
819
+ sign up the workspace's aweb account and team,** with `N` and `A` from
820
+ step 1: no API key or token, nothing for the person to type. Preview
821
+ first, then run it:
644
822
 
645
823
  ```bash
646
824
  cd "D" && oats aweb setup --soul S --username N --name A --label L --plan --json
647
825
  cd "D" && oats aweb setup --soul S --username N --name A --label L --json
648
826
  ```
649
827
 
650
- The preview does not contact aweb, so it can't tell whether `N` is free.
651
- If the run fails with `E_SETUP_NATIVE` (most likely the username is
652
- taken; aw's output is withheld), don't rerun.
653
- On a machine found-list, ask nothing: tell the person that the run
654
- failed, most likely because `N` is taken, and stop.
655
- 3. **Existing workspace: the person gets an invite token** from a member of `L`, who runs
656
- `oats aweb invite --soul <their soul> --label L --json` in their own
657
- deployment and passes the token to the person privately, never by
658
- ordinary mail. They also give the aweb service URL `U`. Choose with the
659
- person a name `A` for this machine's messaging root, such as
660
- `<workspace>-<their machine>`. This works for a hosted team only: if the
661
- invite is refused, or the join says the team is not hosted, stop, and
662
- the workspace's owner decides.
828
+ - **The answer:** `result.team` must be
829
+ the team line step 7 wrote, `default:N.aweb.ai`, and
830
+ `result.membershipVerified` must be `true`. Otherwise stop, spawn
831
+ nothing, and tell the person what it shows.
832
+ - **Then tell the person,** in your words: this is the workspace's
833
+ team, on an aweb account created for it; they attach themselves to it
834
+ later in the setup, with the setup expert.
835
+ - **`E_SETUP_NATIVE`:** most likely `N` is taken (the preview does not
836
+ contact aweb, and aw's output is withheld); the run may also have left
837
+ a root part-way. Never remove `D/.aw`, and never rerun blindly.
838
+ On a machine found-list, ask nothing: tell the person that the run
839
+ failed, most likely because `N` is taken, and stop.
840
+ Otherwise look first, read-only: `test -e "D/.aw" && echo RETAINED`.
841
+ - **Nothing printed:** aw kept nothing, so `N` is free to change. Ask
842
+ the person for another `N`, change the team line in
843
+ `D/<repo>/oats-workspace.yaml` to `default:<new N>.aweb.ai`, commit
844
+ and push it, run `oats sync --dir D`, then run the preview and the
845
+ signup again with the new `N`.
846
+ - **`RETAINED`:** the run left a root. Keep `N` and the team line, and
847
+ run the preview again, unchanged. When its `result.team` is
848
+ `default:N.aweb.ai`, the account exists: run the signup again,
849
+ unchanged, and it reuses that root. Anything else, the preview
850
+ failing included: stop, spawn nothing, and tell the person what it
851
+ shows.
852
+ 3. **Existing workspace: the person gets an invite** from a member of `L`,
853
+ whose own agent runs
854
+ `oats aweb invite --soul <their soul> --label L --json` in their
855
+ deployment. The answer's `result.token` is the invite token,
856
+ passed to the person privately, never by ordinary mail. From oats.aweb
857
+ 1.33.1 the answer's `result.awebUrl` is the service URL `U`, no secret,
858
+ which the member passes too. When it is `null` or absent, leave
859
+ `--service U` out of item 4: the join then takes the service from the
860
+ invite, or fails and item 5 stops. This machine's messaging root is
861
+ `A` = `<workspace>-<this machine's name>` (step 1), with the workspace's
862
+ name from step 8: don't ask. Only a hosted team works: if the invite is
863
+ refused, or the join says the team is not hosted, stop; the workspace's
864
+ owner decides.
663
865
  4. **Existing workspace: the person joins in their own terminal,** which you
664
- open for them ("How to work"), typing the token at the hidden prompt. Its
665
- command, with `D`, `S`, `L`, `A` and `U` filled in:
866
+ open for them ("How to work"), typing the token at the hidden prompt,
867
+ with `D`, `S`, `L`, `A` and `U` filled in:
666
868
 
667
869
  ```text
668
870
  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'
669
871
  ```
872
+
670
873
  5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
671
874
  On `"member": false`, stop and spawn nothing: tell the person the run
672
875
  left this machine's root outside `L`, with what the check shows, and
673
- don't rerun the signup or the join.
674
-
876
+ don't rerun the signup or the join (you can't see the join's output).
877
+ When another machine of the same name may already be in the team, say
878
+ that a taken name is a likely cause: the person who invited them can ask
879
+ their own agent whether that name is in the group (its agent reads
880
+ `oats aweb roster --label L`); the fix (a new invite and a name for this
881
+ machine) is the workspace owner's. Never take the other machine's name.
675
882
  The setup expert does the rest of this machine's messaging
676
883
  (`/oats-host-delivery`).
677
884
 
678
- **The steward's global address (machine found-list only).** The steward
679
- gets a global, contacts-only aweb address, `<namespace>/R`, made by the
680
- team root you just signed up, with no API key and nothing for the person to
681
- type. `R` is the steward's name from step 1, for the resident and the
682
- instance alike.
683
-
684
- Without messaging there is no address to make: skip this. Otherwise it
685
- needs every one of these, and when one fails, take the fallback below:
885
+ **The steward's global address (machine found-list only).** The team root
886
+ you just signed up makes the steward a global, contacts-only aweb address,
887
+ `<namespace>/R` (`R` from step 1, for the resident and the instance alike),
888
+ with no API key and nothing for the person to type. Without messaging, skip
889
+ this. It needs all of these; when one fails, take the fallback below:
686
890
  - a new workspace: a root that joined by invite (items 3 and 4) does not own
687
891
  the namespace, so aweb would refuse the create;
688
- - `oats.aweb` 1.34.0 or later: the `oats.aweb` row of the
892
+ - `oats.aweb` 1.35.0 or later: the `oats.aweb` row of the
689
893
  `oats inspect` you read above, `result.capabilities[].version`;
690
894
  - aw 1.36.48 or later: `aw.version` in the check (item 1).
691
895
 
@@ -702,17 +906,17 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
702
906
  never makes a second one). Anything else, a refusal included (no team
703
907
  root, say), is the fallback.
704
908
  - **`--team-label L`** puts the resident in the team that is already the
705
- default, so the run maps nothing new and prints the spawn line as its one
706
- step (`result.steps`). If it prints another step first, stop and tell the
909
+ default, so the run prints the spawn line as its one step
910
+ (`result.steps`). If it prints another step first, stop and tell the
707
911
  person what it says: that step is theirs.
708
- - **Success** prints `PASS resident <address> …`, and `result.address` is
709
- the steward's address. Spawn with the grant-seat options below.
710
- - **A failure** is reported to the person as it is, and you spawn nothing.
711
- If the create was interrupted (killed, or timed out with no answer), run
712
- the same line again, unchanged, and nothing else. Never empty
912
+ - **Success** prints `PASS resident <address> …`; `result.address` is the
913
+ steward's address. Spawn with the grant-seat options below.
914
+ - **A failure:** report it to the person as it is, and spawn nothing. If
915
+ the create was interrupted (killed, or timed out with no answer), run the
916
+ same line again, unchanged, and nothing else. Never empty
713
917
  `D/.aweb-residents/R`: the identity may already exist.
714
- - **The fallback:** spawn the steward without the grant-seat options. It gets
715
- a local team identity, as every instance does. Tell the person in one line,
918
+ - **The fallback:** spawn the steward without the grant-seat options, with
919
+ a local team identity, as every instance has. Tell the person in one line,
716
920
  without asking anything: the steward has a local team identity and no
717
921
  global address because of <the reason>, and the GLOBAL residents and grant
718
922
  seats section of `/oats-aweb` moves it to one later. Never ask for a key.
@@ -740,39 +944,64 @@ are cloned, knowledge tools, messaging wanted or not>
740
944
  - New workspace only: host <owner>/<repo>, skeleton committed (pushed | in
741
945
  pull request <url>)
742
946
  - 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)
947
+ team T on aweb account N, created for the workspace, not yet attached to
948
+ the person (new workspace), or T owned by aweb account <handle>
949
+ (signed in at step 5), or new account N signed up (machine found-list),
950
+ or joined L by invite (existing) | not set up (the setup expert has no
951
+ messaging)
746
952
  - Harness channel mode: development, confirmed by OATS at each start
953
+ (Claude with aweb) | none (Codex, pi or no messaging)
954
+ - Tasks (new workspace with aweb): oats.aweb-tasks | none: the agents use
955
+ <GitHub issues in <repo> | <tracker the person named> | ticket keys
956
+ <PREFIX>-n>, for you to connect with the person; aweb's task list stays
957
+ empty
747
958
 
748
959
  ## Left to you
749
960
  Everything else, starting with /oats-setup-expert.
750
961
  ```
751
962
 
752
963
  **Claude and Codex only: trust the deployment directory first,** so the first
753
- start doesn't stop at the harness's folder-trust question. pi needs
754
- nothing. Use `codex` for Codex:
964
+ start doesn't stop at the folder-trust question (`codex` for Codex):
755
965
 
756
966
  ```bash
757
967
  oats harness trust --dir D --harness claude --plan
758
968
  oats harness trust --dir D --harness claude
759
969
  ```
760
970
 
761
- - **If either refuses a file** (on macOS, `~/.claude.json` can carry a mark
762
- the writer refuses), don't edit the file or its attributes. Open their
763
- own terminal ("How to work") with `cd "D" && claude` (or `codex`); they
764
- accept the harness's folder-trust question and exit.
971
+ - **If the trust command itself refuses a file** (on macOS,
972
+ `~/.claude.json` can carry a mark the writer refuses), don't edit the file
973
+ or its attributes. Open their own terminal ("How to work") running
974
+ `cd "D" && claude` (or `codex`), and tell them to answer yes when it asks
975
+ whether to trust the folder where their agents live, then close the
976
+ window. A refusal by your harness's permission check is "How to work"'s
977
+ case instead.
765
978
  - **Then check** that the `harness-trust` item of
766
979
  `oats readiness --soul S --dir D --json` passes.
767
980
 
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`).
981
+ **The channel mode.** With Claude and aweb, leave the default development
982
+ channel mode (Claude asks at each start whether to load the aweb channel,
983
+ and OATS confirms it), and don't set `delivery: session`; the setup expert
984
+ later offers the approved route, which needs `sudo`. Tell the person once,
985
+ before the spawn: a notice about a "development channel" may flash past when
986
+ the setup expert starts; OATS answers it, and the setup expert can remove it
987
+ later.
988
+
989
+ **An existing workspace names the setup expert after this machine,** since
990
+ every member's machine has its own in the same team, and two of one name
991
+ can't share it: put
992
+ `-<this machine's name>` (step 1) before `-oats-setup-expert` in
993
+ `next.spawn`'s `--name`, giving
994
+ `--name <workspace>-<this machine's name>-oats-setup-expert`. Over 64
995
+ characters, cut characters from the end of this machine's name until it fits
996
+ (then any `-` left last), so a rerun derives the same name and finds its own setup expert
997
+ (`E_INSTANCE_NAME_TAKEN`, below). A renamed machine gets a new setup expert;
998
+ its agent retires the old one. When `next.spawn` has no `--name` (a very
999
+ long workspace name), before spawning, look in `oats status --dir D --json` for a setup
1000
+ expert of `S` already here, and open that one instead of spawning a second.
1001
+ A new workspace keeps `next.spawn` as it is.
773
1002
 
774
1003
  **Preview the spawn, read it, then spawn,** with step 8's `next.spawn` line
775
- plus the hand-over:
1004
+ and the hand-over:
776
1005
 
777
1006
  ```bash
778
1007
  <next.spawn> --task-file D/.oats-handover.md --preview
@@ -793,31 +1022,33 @@ In the fallback, or without messaging, leave out both `--provider` options.
793
1022
  - **The preview** shows what the spawn would create. If it reports a
794
1023
  problem, stop and tell the person what it says.
795
1024
  - **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`.
1025
+ hand-over file (the home has it as `TASK.md`).
1026
+ - **A messaging name already held by another machine's agent** (the spawn
1027
+ names the conflict): spawn nothing more and rename nothing; tell the
1028
+ person another machine in the team uses this name, and the workspace
1029
+ owner decides the fix.
797
1030
  - **`E_SPAWN_INCOMPLETE`:** don't spawn again. Run `oats session inspect
798
1031
  --home H --json` and tell the person what it shows.
799
1032
  - **`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`.
1033
+ already exists; don't spawn another. Its home `H` is in the error; if it
1034
+ is stopped, start it with `oats session start --home H`. Either way, open
1035
+ it in the Desktop below.
803
1036
 
804
1037
  **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.
1038
+ expert selected. `I` is its instance name: the `--name` you spawned with
1039
+ (after `E_INSTANCE_NAME_TAKEN`, that same `--name`), else the one the spawn
1040
+ printed. Always pass `--instance`: a Desktop that does not know it ignores
1041
+ it.
809
1042
  - **macOS:**
810
1043
 
811
1044
  ```bash
812
1045
  open -n -a "OATS Desktop" --args --dir "D" --instance "I"
813
1046
  ```
814
1047
 
815
- If the Desktop is already running, the new launch hands `--dir` and
816
- `--instance` to it and exits.
817
- - **Linux:** start it yourself through their session manager, so it gets
818
- their desktop session's environment, not yours (yours may carry your
819
- harness's variables and sandbox, and the Desktop passes its environment to
820
- every agent it starts):
1048
+ A Desktop already running takes `--dir` and `--instance` from it.
1049
+ - **Linux:** start it through their session manager, so it gets their
1050
+ desktop session's environment, not yours (with your harness's variables
1051
+ and sandbox, which it would pass to every agent):
821
1052
 
822
1053
  ```bash
823
1054
  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
@@ -825,36 +1056,58 @@ deployment, so pass it always.
825
1056
 
826
1057
  - **`STARTED`:** it shows `D`, with `I` selected.
827
1058
  - **A FUSE message:** see step 4, then start it again.
828
- - **Anything else,** or no `systemd-run`: tell the person what it printed.
829
- They open **OATS Desktop** from their app launcher, and it lists `D` in
1059
+ - **Anything else,** or no `systemd-run`: tell the person what it printed;
1060
+ they open **OATS Desktop** from their app launcher, which lists `D` in
830
1061
  its switcher.
831
- - **Never start it with an emptied environment** (`env -i`): it then loses
832
- HOME, and Git loses the person's login.
833
-
834
- **The TUI**, if they wanted it, runs in a terminal of its own: open it in
835
- their own terminal, as "How to work" says, with the command
836
- `oats tui --dir "D"`.
837
-
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.
842
1062
 
843
- It will ask them only what the hand-over leaves open, and it opens a pane in
844
- its own window when they need to type a secret. You are done.
1063
+ **The TUI:** open their own terminal ("How to work") running
1064
+ `oats tui --dir "D"` when they asked for it in step 1, or have no Desktop
1065
+ and say yes to it in the hand-over below.
1066
+
1067
+ **Hand over to the setup expert,** in a short message in plain words:
1068
+ - what is ready: their agents' shared setup, kept on GitHub, the group their
1069
+ agents talk in, and the setup assistant running; on a machine found-list,
1070
+ the steward, and its address when it has one;
1071
+ - **where to go now:** "Switch to the OATS Desktop window. Click
1072
+ **<I's display form>** under Instances on the left, if it isn't
1073
+ selected: it has already started and will ask you its first question
1074
+ there. You can close this chat." `I`'s display form is how the Desktop
1075
+ lists it: `-` turned into spaces, the first letter capitalised
1076
+ (`acme-oats-setup-expert` shows as "Acme oats setup expert"). Without the
1077
+ Desktop, offer to open a terminal window where they can talk to it (the
1078
+ TUI, above), and say the same about it there. When neither opens, tell
1079
+ them the setup assistant is running, and the OATS Desktop, once
1080
+ installed, shows it;
1081
+ - what the setup assistant does next, in one line: it learns how they work,
1082
+ then sets up their projects and their first agents with them, and it
1083
+ opens a small hidden prompt when they need to type a password or a key;
1084
+ - a new workspace with aweb only, where their agents track work, in one
1085
+ line, with how to change it: "Your agents share aweb's task list; to use
1086
+ another tracker later, ask the setup assistant to switch." With a
1087
+ tracker: "Your agents use your <GitHub issues | tracker>; the setup
1088
+ assistant connects them. Leave aweb's task list empty: one task there
1089
+ opts your whole group in to it. To use aweb's task list instead, ask the
1090
+ setup assistant."
1091
+
1092
+ Don't list homes, paths, versions or commands in this message. You are
1093
+ done.
845
1094
 
846
1095
  ## Never
847
1096
 
848
- - **Ask for, read, print or store a secret,** or suggest `!` for one. If the
849
- person pastes one into the conversation anyway, don't repeat it, and tell
850
- them to rotate it.
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.
1097
+ - **Ask for, read, print or store a secret,** or suggest Claude Code's
1098
+ `! <command>` for one: its command and output enter your context. If the
1099
+ person pastes one anyway, don't repeat it, and tell them to rotate it.
1100
+ - **Overwrite or re-onboard** a deployment, edit an existing deployment's
1101
+ files (`oats-local.yaml`, `oats-lock.json`, `agents/`), touch `D/.aw`, or
1102
+ push to a repository other than the new workspace's host they agreed to in
1103
+ step 1 (step 6 creates or clones it).
1104
+ - **Guess the team id:** it is the signup's `default:N.aweb.ai`, checked in
1105
+ step 9, or step 5's answer after its sign-in.
854
1106
  - **Write a setup soul into the workspace:** the setup expert is
855
1107
  `oats.framework`'s.
856
1108
  - **The Desktop:** never download it through a browser, skip a verification
857
- step, strip quarantine without asking, or start it with `env -i`.
1109
+ step, strip quarantine without asking, or start it with an emptied
1110
+ environment (`env -i`: it loses HOME, and Git the person's login).
858
1111
  - **Put an absolute path or a credential** in `oats-workspace.yaml`,
859
1112
  `oats-membership.yaml` or a soul (the team id is not a secret).
860
1113
  - **Spawn** before `oats onboard` confirmed the host.