@awebai/oats 0.69.9 → 0.69.11

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