@awebai/oats 0.69.8 → 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.
@@ -2,66 +2,110 @@
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, 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.
11
+ Use for "get started with OATS", "set up / install / adopt OATS", "set up
12
+ OATS for this project", "join our OATS workspace", or when someone gives
13
+ you this file or its URL.
11
14
  ---
12
15
 
13
16
  # Getting started with OATS
14
17
 
15
18
  You are the person's own coding agent. This skill takes them from nothing to
16
19
  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.
20
-
21
- OATS in one paragraph: a **workspace** is one Git repository declaring which
22
- repositories belong to an organisation and which packages it trusts. A
23
- **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
-
27
- **A machine found-list.** Your prompt may hand you a found-list, a JSON file
28
- whose `machine.platform` is set (oats-omarchy's installer writes one). Then
29
- 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
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,
23
+ write a few files and spawn it. Then you are done.
24
+
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
37
+ changes. When the found-list lists a deployment whose `steward` is `true`,
38
+ tell the person this machine already has its workspace and steward, and
39
+ stop. Wherever a later step says to ask the
35
40
  person, on a machine found-list you tell them what happened, as it is, and
36
41
  stop instead: the person answers nothing after step 1.
37
42
 
38
43
  **How to work.**
39
44
  - **Ask first, then run.** Ask everything in one round (step 1), then run the
40
- 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 `!`.
41
89
  - **Secrets.** The person types only what you must never hold: passwords,
42
- 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).
46
- - Never ask for a secret in the conversation, and never write one to a file.
47
- - Never suggest Claude Code's `! <command>` for one: its command and output
48
- enter your context.
49
- - **Your shell may keep nothing between commands.** Many harnesses start each
50
- command in a new shell, in the same starting folder.
51
- - Run each fenced block below as one command.
52
- - When a later block needs a value an earlier one found (`V`, `ARCH`, a
53
- path), 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`).
54
99
  - **Sandboxes.** If your harness sandboxes commands, these steps need network
55
100
  access and writes in the home folder: ask the person to approve them.
56
101
  Starting the Desktop and opening a terminal also run outside the sandbox.
57
- - **Their own terminal, opened by you.** When a command must run in the
58
- person's terminal, write it to a file (`mktemp`; it holds no secret) after
59
- 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"`,
60
105
  with the folders `command -v node`, `command -v oats` and `command -v
61
- <harness>` print written in (a window may load no shell startup file, so a
62
- version manager's node would be missing), and a last line
63
- `printf '\nDone: close this window.\n'; read -r _`. Then open a window
64
- 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:
65
109
  - **macOS:** `osascript -e 'tell application "Terminal" to do script "sh F"'`.
66
110
  The first time, macOS may ask the person to let you control Terminal.
67
111
  - **Linux:** `systemd-run --user --collect --quiet -p KillMode=process -E DISPLAY -E WAYLAND_DISPLAY -E XAUTHORITY xdg-terminal-exec sh "F"`,
@@ -69,52 +113,137 @@ stop instead: the person answers nothing after step 1.
69
113
  only that exists. Through `systemd-run` the window gets their desktop
70
114
  session's environment, not yours.
71
115
 
72
- Tell them what to type there, and ask whether the window opened: a
73
- 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
74
118
  read-only command, never by reading the window, then delete the file.
75
- Only when no window opens do you give them the command to run themselves.
76
- - **Touch nothing you were not asked to.** Don't edit an existing
77
- 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.
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.
79
123
 
80
124
  ## 1. Ask, in one round
81
125
 
82
126
  On a machine found-list, ask the machine's round below instead of this list.
83
127
 
84
- - **The use case:** what they want agents to do.
85
- - **Their repositories and project:** which repositories agents should work
86
- in, where they are cloned on this machine, and which are private.
87
- - **Their knowledge tools:** where their team's knowledge lives today (a docs
88
- 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
+
89
157
  - **A new workspace, or an existing one?**
90
158
  - Existing: its repository reference, for example
91
- `git:github.com/acme/acme-oats`. They get it from whoever runs that
92
- 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.
93
163
  - 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).
164
+ by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Refuse
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.
174
+ - **Several repositories:** a dedicated host repository, private, created
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.
184
+ - **Messaging between agents:** which messaging capability, or none. The
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.
107
196
  - **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
108
197
  the one you are, if it is one of these.
109
- - **The deployment directory `D`:** where OATS lives on this machine. Any
110
- 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.
116
- - **OATS Desktop:** installed and started unless they decline. **The TUI**
117
- (`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.
118
247
 
119
248
  **The machine's round.** Read the found-list, then ask only these choices,
120
249
  together, each with its default and one line on what it is. Enter, or
@@ -124,12 +253,12 @@ steward takes them up with the person later.
124
253
  - **The workspace:** a new one, the machine's own. Its name defaults to the
125
254
  hostname, lowercased, with every character outside `[a-z0-9-]` turned
126
255
  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.
256
+ `<github.login>/<workspace>-oats`, private, a dedicated host. Or an
257
+ existing workspace's reference.
129
258
  - **The namespace `N`:** the part of every agent's address before the `/`,
130
259
  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`.
260
+ the hostname, normalised as above, so the namespace is the machine's own.
261
+ Messaging is aweb, and the root's name `A` is `<workspace>-root`.
133
262
  - **The steward's name:** lowercase letters and digits, words joined by
134
263
  single `-`. Default: `steward`. It gives `R`, the steward's instance name
135
264
  here and the name in its address, `N.aweb.ai/R`. `R` is the chosen name,
@@ -141,45 +270,97 @@ steward takes them up with the person later.
141
270
  - **OATS Desktop:** installed and started by default; the TUI not opened.
142
271
  - **The harness:** the found-list's `harness`. Ask only when it names none,
143
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
+ ```
144
294
 
145
295
  ## 2. Check, and install what is missing
146
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
+
147
302
  ```bash
148
- 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
149
304
  ```
150
305
 
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`).
306
+ - **Versions:** Node 22 or later; Git 2.45 or later recommended (partial
307
+ caches; older Git works with whole-tree fetches); `gh` 2.49 or later
308
+ (step 3 uses `gh attestation`).
153
309
  - **The harness** they chose must be installed and logged in (`claude
154
310
  --version`, `codex --version` or `pi --version`).
155
311
  - **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
156
- - **Without Homebrew,** it installs in their own Terminal, which you open
157
- for them ("How to work") with the command under “Install Homebrew” on
158
- <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
159
315
  `brew shellenv` line to their `~/.zprofile` yourself, as its “Next
160
- steps” say.
161
- - Your running process does not see their new PATH. Start each later
162
- command with `eval "$(/opt/homebrew/bin/brew shellenv)"`
163
- (`/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.
164
319
  - **Linux:**
165
320
  - **Packages:** the distribution's, for git and tmux.
166
321
  - **gh:** from GitHub's own apt or rpm repository
167
- (<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), because
168
- distributions ship versions too old for step 4.
169
- - **Node 22:** from NodeSource or a version manager when the distribution's
170
- is older.
171
- - **Passwords:** a line that needs `sudo` goes to their own terminal,
172
- unless `sudo -n true` succeeds.
173
- - **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:
177
- `npm config set prefix ~/.local`. Then put `~/.local/bin` on PATH: start
178
- each later command of yours with `export PATH="$HOME/.local/bin:$PATH"`
179
- (your shell does not reread their profile). Add that line to their shell's
322
+ (<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), not the
323
+ distribution's, which is too old.
324
+ - **Node 22:** distributions ship older ones (Debian 13 has 20, Ubuntu
325
+ 24.04 has 18). On Debian and Ubuntu, x64 or arm64, from NodeSource:
326
+
327
+ ```bash
328
+ curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs
329
+ ```
330
+ - **Git 2.45 (recommended):** Debian 13's is new enough. Ubuntu 24.04
331
+ ships 2.43; on Ubuntu, x64 or arm64, from the git-core PPA:
332
+
333
+ ```bash
334
+ sudo add-apt-repository -y ppa:git-core/ppa && sudo apt-get update && sudo apt-get install -y git
335
+ ```
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
180
361
  startup file yourself, so their own terminal finds `oats` too, and tell
181
- them you did: `~/.zshrc` when `$SHELL` ends in `zsh`, else `~/.bashrc`
182
- (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).
183
364
 
184
365
  ```bash
185
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"
@@ -188,23 +369,22 @@ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
188
369
 
189
370
  ## 3. Log in to GitHub
190
371
 
191
- OATS reads the workspace and its repositories with Git, using the person's
192
- GitHub access. Check first:
372
+ Check first:
193
373
 
194
374
  ```bash
195
375
  gh auth status
196
376
  ```
197
377
 
198
- If it is logged in, let Git use it (without this, step 5's push and step 6
199
- fail with "could not read Username"), then go to step 4:
378
+ If it is logged in, let Git use it (without this, step 6's push and step 8
379
+ fail with "could not read Username"), then go on below:
200
380
 
201
381
  ```bash
202
382
  gh auth setup-git
203
383
  ```
204
384
 
205
- If it is not logged in, start the login yourself, detached and without a
206
- terminal (use your harness's background mode if it has one). gh then prints
207
- 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:
208
388
 
209
389
  ```bash
210
390
  nohup gh auth login --web --hostname github.com --git-protocol https --skip-ssh-key </dev/null >"$HOME/.oats-gh-login.txt" 2>&1 &
@@ -218,60 +398,125 @@ cat "$HOME/.oats-gh-login.txt"
218
398
 
219
399
  - **Give the person the code, and open the URL** in their browser
220
400
  (`open https://github.com/login/device` on macOS, `xdg-open …` on Linux;
221
- give them the URL if that fails). The code is not a secret: only their own
222
- signed-in browser can use it. They enter the code and approve. A code expires after about 15
223
- 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.
224
403
  - **Once they say they approved,** check the login and let Git use it:
225
404
 
226
405
  ```bash
227
406
  gh auth status && gh auth setup-git && rm -f "$HOME/.oats-gh-login.txt"
228
407
  ```
229
408
 
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.
232
-
233
- ## 4. Install OATS Desktop, then the CLI, at the same version
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.
234
418
 
235
- The Desktop accepts a band of CLI versions around its own, so install it
236
- 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:
237
421
 
238
422
  ```bash
239
423
  npm view @awebai/oats version
240
424
  sysctl -n hw.optional.arm64 2>/dev/null # macOS: 1 means ARCH=arm64, otherwise ARCH=x64
241
425
  ```
242
426
 
243
- **Every step verifies before it installs.** If a download or a check fails
244
- (the release's Desktop assets can lag its npm package), skip the Desktop,
245
- 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.
246
482
 
247
- **macOS.** In one block, with `V` and `ARCH` written in. Install into
248
- `/Applications`, which needs an administrator; for a standard user, use
249
- `$HOME/Applications` (`mkdir -p "$HOME/Applications"`) in its place in every
250
- 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:
251
486
 
252
487
  ```bash
253
- cd "$(mktemp -d)" && pwd &&
254
- gh release download "vV" -R awebai/oats -p "oats-desktop-V-mac-ARCH.zip" -p SHA256SUMS.txt &&
255
- grep " oats-desktop-V-mac-ARCH.zip\$" SHA256SUMS.txt | shasum -a 256 -c - &&
256
- 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>" &&
257
503
  ditto -x -k "oats-desktop-V-mac-ARCH.zip" . &&
258
504
  codesign --verify --deep --strict "OATS Desktop.app" &&
259
505
  defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleIdentifier &&
260
506
  defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
261
507
  ```
262
508
 
263
- - **Expected:** `ai.oats.desktop` and `V`. The app is ad-hoc signed and not
264
- notarized; `codesign --verify` passing is what to expect.
265
- - **Download with `gh`, never through a browser.** `gh` sets no quarantine
266
- on what it downloads, and that copy starts from Finder. A browser download
267
- 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.
268
513
  - **Install it.** If the Desktop is running, tell the person and quit it;
269
514
  its agents keep running:
270
515
  `osascript -e 'quit app "OATS Desktop"'; for i in $(seq 20); do pgrep -xq "OATS Desktop" || break; sleep 1; done`.
271
- Then, with the folder `pwd` printed:
516
+ Then:
272
517
 
273
518
  ```bash
274
- 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
275
520
  xattr -p com.apple.quarantine "/Applications/OATS Desktop.app" 2>/dev/null && echo QUARANTINED
276
521
  ```
277
522
 
@@ -279,18 +524,15 @@ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
279
524
  if they agree (`xattr -dr com.apple.quarantine "/Applications/OATS
280
525
  Desktop.app"`): never silently.
281
526
 
282
- **Linux x64.** It needs glibc 2.34 or later (`ldd --version`). It installs
283
- 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
284
529
  running, tell the person and quit it first; its agents keep running:
285
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`
286
531
  (the oldest process is the Desktop's main one). On `STILL_RUNNING`, ask the
287
532
  person to quit it.
288
533
 
289
534
  ```bash
290
- cd "$(mktemp -d)" &&
291
- gh release download "vV" -R awebai/oats -p "oats-desktop-V-linux-x86_64.AppImage" -p SHA256SUMS.txt &&
292
- grep " oats-desktop-V-linux-x86_64.AppImage\$" SHA256SUMS.txt | sha256sum -c - &&
293
- gh attestation verify "oats-desktop-V-linux-x86_64.AppImage" --repo awebai/oats &&
535
+ grep -qx VERIFIED "<W>.log" && cd "<W>" &&
294
536
  mkdir -p ~/.local/opt/oats-desktop ~/.local/share/applications &&
295
537
  install -m 755 "oats-desktop-V-linux-x86_64.AppImage" ~/.local/opt/oats-desktop/OATS-Desktop.AppImage
296
538
  ```
@@ -307,40 +549,130 @@ Terminal=false
307
549
  Categories=Development;
308
550
  ```
309
551
 
310
- - **Without FUSE** (step 8's start fails with a FUSE message; Ubuntu 22.04
311
- 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
313
- `sudo`; installing `libfuse2` (`libfuse2t64` on Ubuntu 24.04) does.
314
- - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
315
- 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.
558
+
559
+ **Don't start the Desktop yet;** step 10 starts it on the new deployment.
560
+
561
+ ## 5. Optional: the team on your own aweb account
562
+
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.
316
567
 
317
- **Don't start the Desktop yet;** step 8 starts it on the new deployment.
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:
571
+ - you are creating a team for the workspace, owned by your aweb account;
572
+ - you sign in as yourself, in your own browser;
573
+ - every agent you spawn joins this default team. More teams are an explicit
574
+ later choice.
318
575
 
319
- **Then the CLI, and for pi its bridge:**
576
+ Don't say that the agents are attributed or bound to them: the team is owned
577
+ by their account, and tying each agent to them is a later step the setup
578
+ expert offers.
579
+
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.
583
+
584
+ **Sign in.** First check whether this machine's `aw` is signed in already:
320
585
 
321
586
  ```bash
322
- npm install -g "@awebai/oats@V" && oats version
323
- pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
587
+ aw auth status --json
588
+ ```
589
+
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:
593
+
594
+ ```bash
595
+ nohup aw auth login </dev/null >"$HOME/.oats-aw-login.txt" 2>&1 &
324
596
  ```
325
597
 
326
- ## 5. The workspace
598
+ A few seconds later, in a separate command:
599
+
600
+ ```bash
601
+ cat "$HOME/.oats-aw-login.txt"
602
+ ```
327
603
 
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.
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:
334
607
 
335
608
  ```bash
336
- mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
609
+ aw auth status --json && rm -f "$HOME/.oats-aw-login.txt"
337
610
  ```
338
611
 
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.
612
+ `account.id` is the account `ACCOUNT`; `account.handle` is its name, to tell
613
+ the person.
614
+
615
+ **Create the team, with its root in `D/.aw`.** On a first run `D/.aw` must
616
+ not exist: if it does and this skill did not make it, stop and ask the
617
+ person what it is. With `D`, `K`, the workspace name and `ACCOUNT` written in:
618
+
619
+ ```bash
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
621
+ ```
622
+
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.
628
+ - **A failure** prints one line on stderr and exits 2:
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.
633
+ - **After an interrupted run** (killed, timed out, or its answer lost),
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
636
+ `ACCOUNT`: aw continues its own run, or answers `identity-home-occupied`
637
+ for anything else. Never remove or edit `D/.aw`.
638
+
639
+ ```bash
640
+ cd "D" && aw --identity-home "D/.aw" team ensure --workspace-key "K" --label "<workspace>" --expect-account "ACCOUNT" --json
641
+ ```
642
+
643
+ Tell the person the team exists, owned by their aweb account `<handle>`.
644
+
645
+ ## 6. The host repository
646
+
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.
651
+
652
+ ```bash
653
+ mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
654
+ ```
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>`.
657
+
658
+ ```bash
659
+ mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo clone "<owner>/<repo>" "<repo>" && git -C "<repo>" status --short --branch
660
+ ```
661
+
662
+ Its root must not hold `oats-workspace.yaml` or `oats-membership.yaml`
663
+ yet: if it does, stop and ask the person.
664
+
665
+ The workspace reference `W` is then `git:github.com/<owner>/<repo>`
666
+ (`git:github.com/acme/acme-oats`).
667
+
668
+ **Existing workspace.** `W` is the reference they gave. Write nothing in its
669
+ repositories.
670
+
671
+ ## 7. The skeleton
672
+
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).
344
676
 
345
677
  `oats-workspace.yaml`:
346
678
 
@@ -348,42 +680,35 @@ their place.
348
680
  schemaVersion: 2
349
681
  name: acme
350
682
  members:
351
- - git:github.com/acme/acme-oats # the host is a member too
683
+ - git:github.com/acme/acme-oats # the host; the setup expert adds the others
352
684
  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
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
355
687
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
356
688
  defaults:
357
689
  capabilities:
358
690
  oats.core: { from: package }
359
691
  messaging: { oats.aweb: { from: package } }
360
- tasks: { oats.aweb-tasks: { from: package } } # aweb tasks: assignment, claims, status and handoff
692
+ tasks: { oats.aweb-tasks: { from: package } } # or `tasks: none` (step 1)
361
693
  teams:
362
- acme: { description: The acme workspace's aweb team, team: "default:acme-ana.aweb.ai" }
694
+ acme: { description: The acme workspace's team, team: "T" }
363
695
  defaultTeam: acme # every soul starts in this team
364
696
  ```
365
697
 
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.
373
- - **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).
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.
383
708
  - **Without messaging,** leave out the `oats.aweb` line, the `messaging`
384
709
  line, the `tasks` line, `teams` and `defaultTeam`.
385
- - **Add nothing else:** knowledge and the person's own repositories come
386
- with the setup expert.
710
+ - **Add nothing else:** no soul (the setup expert is `oats.framework`'s), no
711
+ knowledge; the setup expert authors those with the person.
387
712
 
388
713
  `oats-membership.yaml`:
389
714
 
@@ -392,206 +717,181 @@ schemaVersion: 2
392
717
  workspace: git:github.com/acme/acme-oats
393
718
  ```
394
719
 
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
720
  **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.
463
- - If `git config user.email` prints nothing, the person's Git identity is not
464
- set up yet. After they confirm their name, commit with
465
- `-c user.name="<their name>" -c user.email="<their noreply address>"`. The
466
- 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.
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"'`.
469
731
 
470
732
  ```bash
471
- cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, team, setup expert, developer" && git push -u origin HEAD
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
472
734
  ```
473
735
 
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
736
+ ## 8. Onboard this machine
481
737
 
482
738
  ```bash
483
- oats onboard D --workspace W
739
+ oats onboard D --workspace W --json
484
740
  ```
485
741
 
486
742
  - **Effects:** it writes `D/oats-local.yaml` and `D/agents/`, reads every
487
743
  member over Git and locks the packages.
488
- - **The host must be `confirmed`.** Another member with `cannot-read` is an
489
- access question for the setup expert, not a reason to stop. A host that
490
- 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.
491
747
  - **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
492
748
  person whether to use it as it is or to choose another directory.
493
749
 
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`.
750
+ **The setup expert, `S`, and its spawn line.** `result.next.spawn` is the
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.
501
758
  - **On a machine found-list,** `S` is `oats.machine/steward`. An existing
502
759
  workspace that doesn't offer it: stop, and say that its owner adds
503
760
  `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.
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.
508
765
 
509
- **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
512
- `oats onboard` printed for it, if that line says it is missing.
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.
513
770
 
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:
771
+ **Record the setup expert's harness** on this machine: a package soul names
772
+ none, and without this every later check (readiness, harness trust) and the
773
+ spawn would use the default, pi:
517
774
 
518
775
  ```bash
519
776
  oats soul launch set S --harness <harness> --dir D --plan
520
777
  oats soul launch set S --harness <harness> --dir D
521
778
  ```
522
779
 
523
- ## 7. Hand over to the setup expert
780
+ ## 9. Messaging on this machine
781
+
782
+ Read `oats inspect --soul S --dir D --json`. Its `result.layers.messaging.id`
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:
786
+
787
+ ```bash
788
+ oats readiness --soul S --dir D --json
789
+ ```
790
+
791
+ The messaging items must not report a problem. aweb, the default, is set up
792
+ below; for another capability, follow its own setup skill, and stop if its
793
+ readiness still reports a problem.
524
794
 
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:
795
+ **With aweb (`oats.aweb`):**
796
+ 1. **Check:**
532
797
 
533
798
  ```bash
534
- cd "D" && oats aweb setup --soul S --install-aw --check-only --json
799
+ cd "D" && oats aweb setup --soul S --check-only --json
535
800
  ```
536
801
 
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.
541
- Preview first, then run it:
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
812
+ `"root": null`, there is no root in `D/.aw`: step 5's team creation did
813
+ not finish there, so run its line for an interrupted run, then check
814
+ again. With a `root`, that root is not a member of `defaultTeam.team`:
815
+ the team id step 7 wrote must be step 5's `canonical_team_id` exactly,
816
+ so correct it in `oats-workspace.yaml`, commit and push it, run
817
+ `oats sync --dir D`, then check again.
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:
542
822
 
543
823
  ```bash
544
824
  cd "D" && oats aweb setup --soul S --username N --name A --label L --plan --json
545
825
  cd "D" && oats aweb setup --soul S --username N --name A --label L --json
546
826
  ```
547
827
 
548
- The preview does not contact aweb, so it can't tell whether `N` is free.
549
- 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).
556
- On a machine found-list, ask nothing: tell the person that the run
557
- failed, most likely because `N` is taken, and stop.
558
- 3. **Existing workspace: the person gets an invite token** from a member of `L`, who runs
559
- `oats aweb invite --soul <their soul> --label L --json` in their own
560
- deployment and passes the token to the person privately, never by
561
- ordinary mail. They also give the aweb service URL `U`. Choose with the
562
- person a name `A` for this machine's messaging root, such as
563
- `<workspace>-<their machine>`. This works for a hosted team only: if the
564
- invite is refused, or the join says the team is not hosted, stop, and
565
- 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.
566
865
  4. **Existing workspace: the person joins in their own terminal,** which you
567
- open for them ("How to work"), typing the token at the hidden prompt. Its
568
- 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:
569
868
 
570
869
  ```text
571
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'
572
871
  ```
573
- 5. **Check,** and expect `"member": true`:
574
-
575
- ```bash
576
- cd "D" && oats aweb setup --soul S --check-only --json
577
- ```
578
872
 
873
+ 5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
874
+ On `"member": false`, stop and spawn nothing: tell the person the run
875
+ left this machine's root outside `L`, with what the check shows, and
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.
579
882
  The setup expert does the rest of this machine's messaging
580
883
  (`/oats-host-delivery`).
581
884
 
582
- **The steward's global address (machine found-list only).** The steward
583
- gets a global, contacts-only aweb address, `<namespace>/R`, made by the
584
- team root you just signed up, with no API key and nothing for the person to
585
- type. `R` is the steward's name from step 1, for the resident and the
586
- instance alike.
587
-
588
- Without messaging there is no address to make: skip this. Otherwise it
589
- 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:
590
890
  - a new workspace: a root that joined by invite (items 3 and 4) does not own
591
891
  the namespace, so aweb would refuse the create;
592
- - `oats.aweb` 1.33.0 or later: the `oats.aweb` row of the
892
+ - `oats.aweb` 1.35.0 or later: the `oats.aweb` row of the
593
893
  `oats inspect` you read above, `result.capabilities[].version`;
594
- - aw 1.36.48 or later: `aw.version` in the check (item 5).
894
+ - aw 1.36.48 or later: `aw.version` in the check (item 1).
595
895
 
596
896
  Plan, then create, both from `D` and with no `AWEB_API_KEY`:
597
897
 
@@ -606,28 +906,31 @@ cd "D" && env -u AWEB_API_KEY oats aweb resident create R --team-label L --json
606
906
  never makes a second one). Anything else, a refusal included (no team
607
907
  root, say), is the fallback.
608
908
  - **`--team-label L`** puts the resident in the team that is already the
609
- default, so the run maps nothing new and prints the spawn line as its one
610
- 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
611
911
  person what it says: that step is theirs.
612
- - **Success** prints `PASS resident <address> …`, and `result.address` is
613
- the steward's address. Spawn with the grant-seat options below.
614
- - **A failure** is reported to the person as it is, and you spawn nothing.
615
- If the create was interrupted (killed, or timed out with no answer), run
616
- 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
617
917
  `D/.aweb-residents/R`: the identity may already exist.
618
- - **The fallback:** spawn the steward without the grant-seat options. It gets
619
- 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,
620
920
  without asking anything: the steward has a local team identity and no
621
921
  global address because of <the reason>, and the GLOBAL residents and grant
622
922
  seats section of `/oats-aweb` moves it to one later. Never ask for a key.
623
923
 
924
+ ## 10. Spawn the setup expert, then show it
925
+
624
926
  **Write the hand-over** to `D/.oats-handover.md`. It holds no secret.
625
927
 
626
928
  ```markdown
627
929
  # Onboarding hand-over from the getting-started skill
628
930
 
629
931
  - Workspace: <workspace> (W), new | existing; deployment directory: D
630
- - Setup expert: S, harness <harness>
932
+ - Host: <owner>/<repo>, a monorepo | a dedicated host | the first repository
933
+ - Setup expert: S, instance <name>, harness <harness>
631
934
  - Machine found-list only: steward R, address N.aweb.ai/R | local team
632
935
  identity (<the fallback's reason>)
633
936
 
@@ -638,39 +941,76 @@ are cloned, knowledge tools, messaging wanted or not>
638
941
  ## Done by the getting-started skill
639
942
  - Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
640
943
  - 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)
944
+ - New workspace only: host <owner>/<repo>, skeleton committed (pushed | in
945
+ pull request <url>)
946
+ - Messaging: <capability>, aw <version>, <harness> channel installed;
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)
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
644
958
 
645
959
  ## Left to you
646
960
  Everything else, starting with /oats-setup-expert.
647
961
  ```
648
962
 
649
963
  **Claude and Codex only: trust the deployment directory first,** so the first
650
- start doesn't stop at the harness's folder-trust question. pi needs
651
- nothing. Use `codex` for Codex:
964
+ start doesn't stop at the folder-trust question (`codex` for Codex):
652
965
 
653
966
  ```bash
654
967
  oats harness trust --dir D --harness claude --plan
655
968
  oats harness trust --dir D --harness claude
656
969
  ```
657
970
 
658
- - **If either refuses a file** (on macOS, `~/.claude.json` can carry a mark
659
- the writer refuses), don't edit the file or its attributes. Open their
660
- own terminal ("How to work") with `cd "D" && claude` (or `codex`); they
661
- 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.
662
978
  - **Then check** that the `harness-trust` item of
663
979
  `oats readiness --soul S --dir D --json` passes.
664
980
 
665
- **Preview the spawn, read it, then spawn:**
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.
1002
+
1003
+ **Preview the spawn, read it, then spawn,** with step 8's `next.spawn` line
1004
+ and the hand-over:
666
1005
 
667
1006
  ```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
1007
+ <next.spawn> --task-file D/.oats-handover.md --preview
1008
+ <next.spawn> --task-file D/.oats-handover.md
670
1009
  ```
671
1010
 
672
- **On a machine found-list,** name the steward `R` (its harness was recorded
673
- in step 6). With its global address:
1011
+ For example, `oats spawn oats-setup-expert --dir D --name acme-oats-setup-expert --task-file D/.oats-handover.md`.
1012
+
1013
+ **On a machine found-list,** name the steward `R`. With its global address:
674
1014
 
675
1015
  ```bash
676
1016
  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,55 +1021,93 @@ In the fallback, or without messaging, leave out both `--provider` options.
681
1021
 
682
1022
  - **The preview** shows what the spawn would create. If it reports a
683
1023
  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`.
1024
+ - **The spawn** prints the instance's home `H` and its name. Then delete the
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.
686
1030
  - **`E_SPAWN_INCOMPLETE`:** don't spawn again. Run `oats session inspect
687
1031
  --home H --json` and tell the person what it shows.
1032
+ - **`E_INSTANCE_NAME_TAKEN`** (the preview or the spawn): the setup expert
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.
1036
+
1037
+ **The Desktop**, if installed, opens on the new deployment with the setup
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.
1042
+ - **macOS:**
688
1043
 
689
- ## 8. Start the Desktop and the TUI, then hand over
1044
+ ```bash
1045
+ open -n -a "OATS Desktop" --args --dir "D" --instance "I"
1046
+ ```
690
1047
 
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.
694
- - **Linux:** start it yourself through their session manager, so it gets
695
- their desktop session's environment, not yours (yours may carry your
696
- harness's variables and sandbox, and the Desktop passes its environment to
697
- 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):
698
1052
 
699
1053
  ```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
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
701
1055
  ```
702
1056
 
703
- - **`STARTED`:** it shows `D`.
1057
+ - **`STARTED`:** it shows `D`, with `I` selected.
704
1058
  - **A FUSE message:** see step 4, then start it again.
705
- - **Anything else,** or no `systemd-run`: tell the person what it printed.
706
- They open **OATS Desktop** from their app launcher, and it lists `D` in
707
- its switcher (from OATS 0.65.0).
708
- - **Never start it with an emptied environment** (`env -i`): it then loses
709
- HOME, and Git loses the person's login.
710
-
711
- **The TUI**, if they wanted it, runs in a terminal of its own: open it in
712
- their own terminal, as "How to work" says, with the command
713
- `oats tui --dir "D"`.
714
-
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.
719
-
720
- It will ask them only what the hand-over leaves open, and it opens a pane in
721
- its own window when they need to type a secret. You are done.
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
1061
+ its switcher.
1062
+
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.
722
1094
 
723
1095
  ## Never
724
1096
 
725
- - **Ask for, read, print or store a secret,** or suggest `!` for one. If the
726
- person pastes one into the conversation anyway, don't repeat it, and tell
727
- 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.
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.
1106
+ - **Write a setup soul into the workspace:** the setup expert is
1107
+ `oats.framework`'s.
730
1108
  - **The Desktop:** never download it through a browser, skip a verification
731
- 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).
732
1111
  - **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).
1112
+ `oats-membership.yaml` or a soul (the team id is not a secret).
735
1113
  - **Spawn** before `oats onboard` confirmed the host.