@awebai/oats 0.62.0 → 0.64.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +14 -1
  2. package/bin/oats.mjs +58 -23
  3. package/docs/desktop-cli-api.md +73 -3
  4. package/docs/execution-targets.md +45 -2
  5. package/docs/first-team.md +6 -0
  6. package/docs/official-catalog.md +1 -1
  7. package/docs/packages.md +5 -5
  8. package/docs/release-lane.md +13 -0
  9. package/docs/release-notes/v0.63.0.md +135 -0
  10. package/docs/release-notes/v0.64.0.md +105 -0
  11. package/docs/souls-and-instances.md +32 -7
  12. package/docs/upgrading.md +6 -3
  13. package/docs/workspaces.md +1 -1
  14. package/lib/core.mjs +100 -28
  15. package/lib/session-input.mjs +12 -2
  16. package/lib/tree-copy.mjs +188 -7
  17. package/package-catalog.json +1 -1
  18. package/package.json +1 -1
  19. package/packages/client/cli-locator.mjs +2 -2
  20. package/packages/client/instance-tree.mjs +53 -3
  21. package/packages/client/roster-sections.mjs +22 -6
  22. package/packages/record/bin/capture.mjs +59 -17
  23. package/packages/record/bin/setup.mjs +2 -1
  24. package/packages/record/docs/capture-service.md +89 -5
  25. package/packages/record/lib/capture-command-operation.mjs +2 -2
  26. package/packages/record/lib/capture-command-output.mjs +3 -2
  27. package/packages/record/lib/capture-command.mjs +20 -3
  28. package/packages/record/lib/capture-hook-runner.mjs +1 -1
  29. package/packages/record/lib/capture-index-reset.mjs +1 -0
  30. package/packages/record/lib/capture-lock.mjs +67 -33
  31. package/packages/record/lib/capture-pass.mjs +22 -8
  32. package/packages/record/lib/capture-run.mjs +1 -1
  33. package/packages/record/lib/capture-service-runner.mjs +1 -1
  34. package/packages/record/lib/capture-supervisor.mjs +24 -5
  35. package/packages/record/lib/capture-work-session.mjs +7 -4
  36. package/packages/record/lib/capture-worker.mjs +20 -4
  37. package/packages/record/lib/derived-state.mjs +30 -2
  38. package/packages/record/lib/index-db.mjs +118 -49
  39. package/packages/record/lib/store.mjs +13 -6
  40. package/skills/oats-getting-started/SKILL.md +438 -170
@@ -1,230 +1,498 @@
1
1
  ---
2
2
  name: oats-getting-started
3
3
  description: >-
4
- How to start with OATS (Open Agent Team Specification) from nothing — install
5
- the CLI and pi adapter, decide which repository hosts the organisation's
6
- workspace, write the three shared declarations (oats-workspace.yaml,
7
- oats-membership.yaml, souls/<name>/soul.yaml), realize the workspace on this
8
- machine with `oats onboard` and spawn the first soul. Use
9
- for "get started with OATS", "set up/install/adopt OATS", "create my first
10
- agent", or "how do I start using OATS".
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.
11
11
  ---
12
12
 
13
13
  # Getting started with OATS
14
14
 
15
- OATS gives an organisation durable **souls** (role definitions kept in Git),
16
- disposable **instances** (a soul at work, in its own home) and **capabilities**
17
- (skills, instructions and hooks copied whole into each instance at spawn). One
18
- **workspace** per organisation lists the repositories that belong to it. Do not
19
- run setup blindly: explain each decision and ask before writing a file,
20
- declaring a package or spawning.
15
+ You are the person's own coding agent. This skill takes them from nothing to
16
+ 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
+ **How to work.**
28
+ - **Ask first, then run.** Ask everything in one round (step 1), then run the
29
+ steps yourself and read back what each did.
30
+ - **Secrets.** The person types only what you must never hold: passwords,
31
+ tokens and logins. Before the spawn there are two ways for that: a browser
32
+ device flow you start (the GitHub login, step 3), and the exact command
33
+ for their own terminal (a `sudo` or Homebrew password, an aweb invite
34
+ token).
35
+ - Never ask for a secret in the conversation, and never write one to a file.
36
+ - Never suggest Claude Code's `! <command>` for one: its command and output
37
+ enter your context.
38
+ - **Your shell may keep nothing between commands.** Many harnesses start each
39
+ command in a new shell, in the same starting folder.
40
+ - Run each fenced block below as one command.
41
+ - When a later block needs a value an earlier one found (`V`, `ARCH`, a
42
+ path), write that value in literally.
43
+ - **Sandboxes.** If your harness sandboxes commands, these steps need network
44
+ access and writes in the home folder: ask the person to approve them.
45
+ - **Touch nothing you were not asked to.** Don't edit an existing
46
+ deployment's files (`oats-local.yaml`, `oats-lock.json`, `agents/`), and
47
+ don't push to a repository the person did not create in step 5.
48
+
49
+ ## 1. Ask, in one round
50
+
51
+ - **The use case:** what they want agents to do.
52
+ - **Their repositories and project:** which repositories agents should work
53
+ in, where they are cloned on this machine, and which are private.
54
+ - **Their knowledge tools:** where their team's knowledge lives today (a docs
55
+ repository, a wiki, Notion, Confluence, none).
56
+ - **A new workspace, or an existing one?**
57
+ - Existing: its repository reference, for example
58
+ `git:github.com/acme/acme-oats`. They get it from whoever runs that
59
+ workspace.
60
+ - New: the **workspace name**: lowercase letters and digits, words joined
61
+ by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Also
62
+ the GitHub **owner** of its repository (their user, or an organisation
63
+ they can create repositories in) and the repository's name. Suggest
64
+ `<workspace>-oats`. Refuse `agents`: OATS keeps instance homes in a
65
+ folder of that name.
66
+ - **Messaging between agents (aweb):** wanted or not. The setup expert sets it
67
+ up later. An existing workspace that already has it needs it on this
68
+ machine before the setup expert can spawn (step 7).
69
+ - **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
70
+ the one you are, if it is one of these.
71
+ - **The deployment directory `D`:** where OATS lives on this machine. Any
72
+ folder works. Suggest `~/Agents/<workspace>`: the Desktop and the TUI find
73
+ deployments directly inside `~/Agents` by themselves. Write `D` everywhere
74
+ below as an absolute path, with the home folder spelled out: never `~`,
75
+ which the shell does not expand inside quotes.
76
+ - **OATS Desktop:** installed and started unless they decline. **The TUI**
77
+ (`oats tui`, a terminal client, preview): opened for them or not.
78
+
79
+ ## 2. Check, and install what is missing
21
80
 
22
- This skill is the one pre-workspace bootstrap. Once the first instance exists,
23
- the `oats.setup` capability's skills (and the `oats-operator-expert` soul, where
24
- the workspace offers it) carry the rest; spawned instances get their own skills.
81
+ ```bash
82
+ uname -sm; node --version; git --version; tmux -V; gh --version; npm prefix -g
83
+ ```
84
+
85
+ - **Versions:** Node 22 or later; Git 2.45 or later is best (older works,
86
+ fetching more); `gh` 2.49 or later (step 4 uses `gh attestation`).
87
+ - **The harness** they chose must be installed and logged in (`claude
88
+ --version`, `codex --version` or `pi --version`).
89
+ - **macOS:** with Homebrew (`brew --version`), `brew install node git tmux gh`.
90
+ - **Without Homebrew,** they install it in their own Terminal, since it asks
91
+ for their password: from <https://brew.sh>, the command under “Install
92
+ Homebrew”, then the “Next steps” lines it prints.
93
+ - Your running process does not see their new PATH. Start each later
94
+ command with `eval "$(/opt/homebrew/bin/brew shellenv)"`
95
+ (`/usr/local/bin/brew` on Intel), or ask them to restart you.
96
+ - **Linux:**
97
+ - **Packages:** the distribution's, for git and tmux.
98
+ - **gh:** from GitHub's own apt or rpm repository
99
+ (<https://github.com/cli/cli/blob/trunk/docs/install_linux.md>), because
100
+ distributions ship versions too old for step 4.
101
+ - **Node 22:** from NodeSource or a version manager when the distribution's
102
+ is older.
103
+ - **Passwords:** a line that needs `sudo` goes to their own terminal,
104
+ unless `sudo -n true` succeeds.
105
+ - **npm's global folder** (`npm prefix -g`) must be writable for step 4's
106
+ install (`test -w "$(npm prefix -g)/lib"`). If it is not (a system Node
107
+ under `/usr`), either they run that install with `sudo` in their own
108
+ terminal, or set a per-user prefix (`npm config set prefix ~/.local`, with
109
+ `~/.local/bin` on their PATH).
110
+ - **Windows** is not supported.
111
+
112
+ ## 3. Log in to GitHub
113
+
114
+ OATS reads the workspace and its repositories with Git, using the person's
115
+ GitHub access. Check first:
116
+
117
+ ```bash
118
+ gh auth status
119
+ ```
120
+
121
+ If it is not logged in, start the login yourself, detached and without a
122
+ terminal (use your harness's background mode if it has one). gh then prints
123
+ a one-time code and a URL instead of opening a browser, and waits:
124
+
125
+ ```bash
126
+ nohup gh auth login --web --hostname github.com --git-protocol https --skip-ssh-key </dev/null >"$HOME/.oats-gh-login.txt" 2>&1 &
127
+ ```
128
+
129
+ In a separate command, a few seconds later, read the code and the URL:
130
+
131
+ ```bash
132
+ cat "$HOME/.oats-gh-login.txt"
133
+ ```
134
+
135
+ - **Give the person the code and the URL** (`https://github.com/login/device`).
136
+ The code is not a secret: only their own signed-in browser can use it. They
137
+ open the URL, enter the code and approve. A code expires after about 15
138
+ minutes; then start again.
139
+ - **Once they say they approved,** check the login and let Git use it:
140
+
141
+ ```bash
142
+ gh auth status && gh auth setup-git && rm -f "$HOME/.oats-gh-login.txt"
143
+ ```
144
+
145
+ The token stays in gh's store and never reaches you. SSH keys, commit
146
+ signing and the DCO sign-off come later, from the setup expert.
147
+
148
+ ## 4. Install OATS Desktop, then the CLI, at the same version
149
+
150
+ The Desktop accepts a band of CLI versions around its own, so install it
151
+ first, then the CLI of the same version `V`. Find `V`, and on macOS `ARCH`:
152
+
153
+ ```bash
154
+ npm view @awebai/oats version
155
+ sysctl -n hw.optional.arm64 2>/dev/null # macOS: 1 means ARCH=arm64, otherwise ARCH=x64
156
+ ```
157
+
158
+ **Every step verifies before it installs.** If a download or a check fails
159
+ (the release's Desktop assets can lag its npm package), skip the Desktop,
160
+ say so, and go on with the CLI. Never skip a check to make it install.
161
+
162
+ **macOS.** In one block, with `V` and `ARCH` written in. Install into
163
+ `/Applications`, which needs an administrator; for a standard user, use
164
+ `$HOME/Applications` (`mkdir -p "$HOME/Applications"`) in its place in every
165
+ line below:
25
166
 
26
- ## 1. Install
167
+ ```bash
168
+ cd "$(mktemp -d)" && pwd &&
169
+ gh release download "vV" -R awebai/oats -p "oats-desktop-V-mac-ARCH.zip" -p SHA256SUMS.txt &&
170
+ grep " oats-desktop-V-mac-ARCH.zip\$" SHA256SUMS.txt | shasum -a 256 -c - &&
171
+ gh attestation verify "oats-desktop-V-mac-ARCH.zip" --repo awebai/oats &&
172
+ ditto -x -k "oats-desktop-V-mac-ARCH.zip" . &&
173
+ codesign --verify --deep --strict "OATS Desktop.app" &&
174
+ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleIdentifier &&
175
+ defaults read "$PWD/OATS Desktop.app/Contents/Info" CFBundleShortVersionString
176
+ ```
177
+
178
+ - **Expected:** `ai.oats.desktop` and `V`. The app is ad-hoc signed and not
179
+ notarized; `codesign --verify` passing is what to expect.
180
+ - **Download with `gh`, never through a browser.** `gh` sets no quarantine
181
+ on what it downloads, and that copy starts from Finder. A browser download
182
+ would be quarantined.
183
+ - **Install it.** If the Desktop is running, ask the person to quit it. Then,
184
+ with the folder `pwd` printed:
185
+
186
+ ```bash
187
+ 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
188
+ xattr -p com.apple.quarantine "/Applications/OATS Desktop.app" 2>/dev/null && echo QUARANTINED
189
+ ```
190
+
191
+ - **If it prints `QUARANTINED`,** tell the person. Remove the attribute only
192
+ if they agree (`xattr -dr com.apple.quarantine "/Applications/OATS
193
+ Desktop.app"`): never silently.
194
+
195
+ **Linux x64.** It needs glibc 2.34 or later (`ldd --version`). It installs
196
+ per user, without sudo, and shows in the app launcher:
27
197
 
28
198
  ```bash
29
- npm install -g @awebai/oats
30
- pi install npm:@awebai/oats-pi
199
+ cd "$(mktemp -d)" &&
200
+ gh release download "vV" -R awebai/oats -p "oats-desktop-V-linux-x86_64.AppImage" -p SHA256SUMS.txt &&
201
+ grep " oats-desktop-V-linux-x86_64.AppImage\$" SHA256SUMS.txt | sha256sum -c - &&
202
+ gh attestation verify "oats-desktop-V-linux-x86_64.AppImage" --repo awebai/oats &&
203
+ mkdir -p ~/.local/opt/oats-desktop ~/.local/share/applications &&
204
+ install -m 755 "oats-desktop-V-linux-x86_64.AppImage" ~/.local/opt/oats-desktop/OATS-Desktop.AppImage
31
205
  ```
32
206
 
33
- Install matching versions and upgrade both together (`oats update`). Reload pi
34
- after installing or upgrading the adapter. Check with `oats version`.
207
+ Then write `~/.local/share/applications/oats-desktop.desktop`, with `<home>`
208
+ their home directory's absolute path:
35
209
 
36
- ## 2. Decide where the workspace is hosted — first
210
+ ```text
211
+ [Desktop Entry]
212
+ Type=Application
213
+ Name=OATS Desktop
214
+ Exec=<home>/.local/opt/oats-desktop/OATS-Desktop.AppImage %U
215
+ Terminal=false
216
+ Categories=Development;
217
+ ```
218
+
219
+ - **Without FUSE** (the AppImage fails with a FUSE message), add
220
+ ` --appimage-extract-and-run` after the AppImage's path in `Exec=` and
221
+ wherever you start it.
222
+ - **Linux arm64** (`uname -m` says `aarch64`) has no Desktop: skip the
223
+ download, say so and go on.
224
+
225
+ **Don't start the Desktop yet;** step 8 starts it on the new deployment.
226
+
227
+ **Then the CLI, and for pi its bridge:**
228
+
229
+ ```bash
230
+ npm install -g "@awebai/oats@V" && oats version
231
+ pi install "npm:@awebai/oats-pi@V" # only when the harness is pi
232
+ ```
37
233
 
38
- The workspace file names every member repository, so whoever can read it sees
39
- the member list. Ask:
234
+ ## 5. The workspace
40
235
 
41
- - **Does the organisation already have an OATS workspace?** Then skip to step 4
42
- with its repository reference.
43
- - **Is any repository that will join private?** Then the workspace file lives
44
- in a private repository that is not itself a public member (a dedicated
45
- `<org>/workspace` repository is the honest shape). Otherwise any member,
46
- often a dedicated `agents` repository, can host it.
236
+ **New workspace.** Create its repository, private, inside the deployment
237
+ directory `D`, then write four files in it.
238
+ - **Private** is the safe default: the workspace file names every member, so
239
+ whoever reads it sees the list.
240
+ - **`D/<repo>` must not exist yet:** an existing folder's files would end up
241
+ in the first commit.
47
242
 
48
- Every member runs its capabilities' hooks on every operator's machine, gated
49
- only by membership. In a mixed public/private organisation keep executable
50
- capabilities in packages or private members, and only souls in public members.
243
+ ```bash
244
+ mkdir -p "D" && cd "D" && test ! -e "<repo>" && gh repo create "<owner>/<repo>" --private --clone && ls -a "<repo>"
245
+ ```
51
246
 
52
- ## 3. Write the shared declarations (in Git, reviewed like code)
247
+ Then write the four files below in `D/<repo>`. They show a workspace named
248
+ `acme`, in the repository `acme/acme-oats`, with Claude as the harness:
249
+ write the person's own workspace name, repository and harness in their
250
+ place.
53
251
 
54
- In the host repository, `oats-workspace.yaml`:
252
+ `oats-workspace.yaml`:
55
253
 
56
254
  ```yaml
57
255
  schemaVersion: 2
58
256
  name: acme
59
257
  members:
60
- - git:github.com/acme/agents # the host is a member too
61
- - git:github.com/acme/platform
258
+ - git:github.com/acme/acme-oats # the host is a member too
62
259
  packages:
63
- oats.framework: v1.13.1 # bare versions resolve through the official catalog
64
- oats.okf: v5.2.1
260
+ oats.framework: v1.13.3 # the installed CLI's catalog version (below)
65
261
  defaults:
66
- capabilities: { oats.core: { from: package } }
67
- knowledge: { oats.okf: { from: package } }
262
+ capabilities:
263
+ oats.core: { from: package }
68
264
  ```
69
265
 
70
- Take the current package versions from the official catalog
71
- (`package-catalog.json` in the OATS repository); ask which slots the user wants
72
- filled (knowledge, messaging, tasks) instead of copying the example. No absolute
73
- paths or accounts go in this file. Teams come with messaging (step 6).
266
+ - **The `oats.framework` version** is the installed CLI's catalog's:
267
+ `"$(oats root)/package-catalog.json"`, `packages."oats.framework".ref`,
268
+ for example `oats-framework/v1.13.3`. Write the part after the `/`.
269
+ - **Add nothing else:** knowledge, messaging and teams come with the setup
270
+ expert.
74
271
 
75
- Declaring a package in `packages:` is the decision to trust it: its commands
76
- and hooks run on every machine that spawns a soul using it. Show the user what
77
- each package runs (its capability manifests' `commands` and `hooks`) before
78
- adding its pin.
79
-
80
- In **every** member repository, including the host, `oats-membership.yaml`:
272
+ `oats-membership.yaml`:
81
273
 
82
274
  ```yaml
83
275
  schemaVersion: 2
84
- workspace: git:github.com/acme/agents
276
+ workspace: git:github.com/acme/acme-oats
85
277
  ```
86
278
 
87
- Membership is reciprocal: the workspace lists the repository and the
88
- repository names the workspace back. Neither alone is membership.
89
-
90
- A soul lives at `souls/<name>/` in a member repository: `soul.yaml`,
91
- `AGENTS.md` (its canonical instructions) and `CLAUDE.md -> AGENTS.md`.
279
+ `souls/acme-oats-setup-expert/soul.yaml`:
92
280
 
93
281
  ```yaml
94
282
  schemaVersion: 2
95
- name: backend-expert
96
- description: Owns backend architecture and implementation.
97
- work: worktree # worktree | checkout | directory | workspace
283
+ name: acme-oats-setup-expert
284
+ description: The OATS setup expert for the acme workspace — onboards machines and people, and keeps this workspace's OATS setup working.
285
+ work: worktree # it changes this repository by pull request, on its own branch
286
+ capabilities:
287
+ oats.setup: { from: package }
288
+ knowledge: none # so it spawns on a machine before knowledge is set up there
289
+ launch: { harness: claude } # the harness the person chose: claude, codex or pi
98
290
  ```
99
291
 
100
- A soul says where each extra capability comes from (`{ from: package }`,
101
- `{ from: here }` or `{ from: <member repo key> }`), never a version. A soul
102
- whose knowledge slot is filled by `oats.okf` also needs `okf.json` beside
103
- `soul.yaml`; `docs/knowledge.md` in the OATS repository shows its shape.
104
- Commit and push; OATS reads members over their remotes, not from local clones.
292
+ `souls/acme-oats-setup-expert/AGENTS.md`, and beside it the symlink
293
+ `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`):
105
294
 
106
- ## 4. Realize the workspace on this machine
295
+ ```markdown
296
+ # acme-oats-setup-expert
107
297
 
108
- Ask the user **which directory** holds this machine's deployment — usually the
109
- folder that already holds their clones. There is no required name.
298
+ You are the OATS setup expert for the acme workspace. You set up and keep
299
+ working this workspace's OATS: its machines, members, souls, packages,
300
+ knowledge, messaging and automations. The `oats.setup` capability is your
301
+ toolkit: its briefing says what the person types and what you run, and its
302
+ skills hold every procedure. Start with `/oats-setup-model`. When your task
303
+ is a hand-over from the getting-started skill, follow `/oats-setup-expert`,
304
+ or `/oats-onboarding` if your `oats.setup` is older than 2.8.0 and lacks it.
305
+ Change shared files only by pull request; the person reviews and merges them.
306
+ ```
307
+
308
+ **Keep the soul this thin.** Everything it knows comes from `oats.setup`, so
309
+ it improves when the workspace's `oats.framework` pin moves. It has no
310
+ knowledge of its own, so it can be spawned on a machine before knowledge is
311
+ set up there. It takes the workspace's messaging and doesn't empty that
312
+ slot: a setup soul that empties the messaging slot the workspace fills is
313
+ not the workspace's operator, and gets no mail. A new workspace has no
314
+ messaging yet; the setup expert adds it.
315
+
316
+ **Commit and push.**
317
+ - This first commit goes straight to the new repository's default branch: it
318
+ is the person's own, just created. Every later change is a pull request
319
+ from the setup expert.
320
+ - If `git config user.email` prints nothing, the person's Git identity is not
321
+ set up yet. After they confirm their name, commit with
322
+ `-c user.name="<their name>" -c user.email="<their noreply address>"`. The
323
+ noreply address comes from
324
+ `gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'`. The
325
+ setup expert sets up their identity properly later.
110
326
 
111
327
  ```bash
112
- oats onboard <dir> --workspace git:github.com/acme/agents
328
+ cd "D/<repo>" && git add -A && git commit -m "OATS workspace acme: workspace, membership, setup expert" && git push -u origin HEAD
113
329
  ```
114
330
 
115
- It writes `<dir>/oats-local.yaml` (the one per-machine file, never committed)
116
- and `agents/`, confirms each member, resolves and locks the packages, and prints
117
- the next steps. Fix any member that is not confirmed (`oats workspace status` says why) before going on.
331
+ The workspace reference `W` is then `git:github.com/<owner>/<repo>`, here
332
+ `git:github.com/acme/acme-oats`.
118
333
 
119
- Host-owned settings a package asks for (absolute paths, state directories) go
120
- under `settings:` in `oats-local.yaml`, never in the workspace file. For
121
- `oats.okf` that is `bindings-file` and `state-dir`; its own skill explains the
122
- bindings file.
334
+ **Existing workspace.** `W` is the reference they gave. Write nothing in its
335
+ repositories.
123
336
 
124
- ## 5. Sync after any change
337
+ ## 6. Onboard this machine
125
338
 
126
339
  ```bash
127
- oats sync --dir <dir> # resolve every pin to a commit, fetch, verify integrity, write oats-lock.json
340
+ oats onboard D --workspace W
128
341
  ```
129
342
 
130
- Run it after any change to the workspace file. It asks nothing; the lock pins
131
- each package to an exact commit and integrity, and content that no longer
132
- matches is refused (`E_PACKAGE_INTEGRITY`). Member capabilities come from
133
- membership.
134
-
135
- ## 6. Give the deployment a team (with messaging)
136
-
137
- If a messaging capability fills the messaging slot, every instance lives in a
138
- team, and readiness fails with `E_TEAM_UNCONFIGURED` until there is a default
139
- team. Create the team with the messaging provider (its own skills say how),
140
- then commit it in `oats-workspace.yaml` with its provider id, and make it the
141
- default:
142
-
143
- ```yaml
144
- teams:
145
- research: { team: <provider team id> }
146
- defaultTeam: research
343
+ - **Effects:** it writes `D/oats-local.yaml` and `D/agents/`, reads every
344
+ member over Git and locks the packages.
345
+ - **The host must be `confirmed`.** Another member with `cannot-read` is an
346
+ access question for the setup expert, not a reason to stop. A host that
347
+ can't be read is a GitHub access problem (step 3).
348
+ - **`E_ALREADY_ONBOARDED`:** `D` already is a deployment. Stop and ask the
349
+ person whether to use it as it is or to choose another directory.
350
+
351
+ **Find the setup expert soul, `S`.**
352
+ - **From OATS 0.61.0,** the next step `oats onboard` prints names the soul
353
+ that holds `oats.setup`, the workspace's setup expert (`--json`:
354
+ `next.spawn`).
355
+ - **Before 0.61.0,** read `oats souls --dir D --json`: the soul named
356
+ `<workspace>-oats-setup-expert`, else one whose definition declares
357
+ `oats.setup`.
358
+ - **An existing workspace with no such soul:** stop. Show the person the soul
359
+ files from step 5 and say that the workspace's owner adds them by pull
360
+ request to its host repository. Once that is merged, run
361
+ `oats sync --dir D` and look for `S` again.
362
+
363
+ **The clone.** A soul with `work: worktree` needs a clone of its repository
364
+ at `D/<repo name>`. A new workspace already has it (step 5). For an existing
365
+ one, clone the repository that holds `S` with the `git clone` line
366
+ `oats onboard` printed for it, if that line says it is missing.
367
+
368
+ ## 7. Hand over to the setup expert
369
+
370
+ **Messaging on this machine first, when the setup expert takes it.** Read
371
+ `oats inspect --soul S --dir D --json`. If its `result.layers.messaging.id`
372
+ is `oats.aweb`, the workspace has messaging, and the setup expert
373
+ can't spawn on this machine until it has messaging too. Set it up now:
374
+ 1. **Install `aw`, and the harness's aweb channel** (Claude:
375
+ `claude plugin marketplace add awebai/claude-plugins && claude plugin install aweb-channel@awebai-marketplace`;
376
+ pi: `pi install npm:@awebai/pi`; Codex: nothing). Then:
377
+
378
+ ```bash
379
+ cd "D" && oats aweb setup --soul S --install-aw --check-only --json
380
+ ```
381
+
382
+ Its `aw.status` must be `ok` or `done`; stop on `failed` and tell the
383
+ person why. Its `defaultTeam.label` is `L`, the setup expert's team.
384
+ 2. **The person gets an invite token** from a member of `L`, who runs
385
+ `oats aweb invite --soul <their soul> --label L --json` in their own
386
+ deployment and passes the token to the person privately, never by
387
+ ordinary mail. They also give the aweb service URL `U`. Choose with the
388
+ person a name `A` for this machine's messaging root, such as
389
+ `<workspace>-<their machine>`. This works for a hosted team only: if the
390
+ invite is refused, or the join says the team is not hosted, stop, and
391
+ the workspace's owner decides.
392
+ 3. **The person joins in their own terminal,** typing the token at the
393
+ hidden prompt. Give them the line with `D`, `S`, `L`, `A` and `U` filled
394
+ in:
395
+
396
+ ```text
397
+ 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'
398
+ ```
399
+ 4. **Check,** and expect `"member": true`:
400
+
401
+ ```bash
402
+ cd "D" && oats aweb setup --soul S --check-only --json
403
+ ```
404
+
405
+ The setup expert does the rest of this machine's messaging
406
+ (`/oats-host-delivery`).
407
+
408
+ **Write the hand-over** to `D/.oats-handover.md`. It holds no secret.
409
+
410
+ ```markdown
411
+ # Onboarding hand-over from the getting-started skill
412
+
413
+ - Workspace: <workspace> (W), new | existing; deployment directory: D
414
+ - Setup expert: S, harness <harness>
415
+
416
+ ## The person's answers
417
+ <step 1's answers, in their words: use case, repositories and where they
418
+ are cloned, knowledge tools, messaging wanted or not>
419
+
420
+ ## Done by the getting-started skill
421
+ - Installed: OATS <V> (oats version), OATS Desktop <V> | not installed (why)
422
+ - GitHub: gh logged in over https as <login>; no SSH key or signing set up
423
+ - New workspace only: repository <owner>/<repo> created, first commit pushed
424
+ - Messaging: this machine joined L as root A (aw <version>, <harness>
425
+ channel installed) | not set up (the setup expert has no messaging)
426
+
427
+ ## Left to you
428
+ Everything else, starting with /oats-setup-expert.
147
429
  ```
148
430
 
149
- Push, then sync and check:
431
+ **Claude and Codex only: trust the deployment directory first,** so the first
432
+ start doesn't stop at the harness's folder-trust question. pi needs
433
+ nothing. Use `codex` for Codex:
150
434
 
151
435
  ```bash
152
- oats sync --dir <dir>
153
- oats teams --dir <dir>
436
+ oats harness trust --dir D --harness claude --plan
437
+ oats harness trust --dir D --harness claude
154
438
  ```
155
439
 
156
- The teams an instance may join, and its default, are the organisation's
157
- decision, committed in this file: by default a soul joins its default team
158
- only, and `souls:` entries open other teams to a soul. A deployment declares
159
- teams of its own (`oats teams add`) only when the workspace says
160
- `localTeams: true` (`/oats-teams`, in `oats.setup`).
440
+ - **If either refuses a file** (on macOS, `~/.claude.json` can carry a mark
441
+ the writer refuses), don't edit the file or its attributes. The person
442
+ runs `cd D && claude` (or `codex`) in their own terminal, accepts the
443
+ harness's folder-trust question and exits.
444
+ - **Then check** that the `harness-trust` item of
445
+ `oats readiness --soul S --dir D --json` passes.
161
446
 
162
- ## 7. Spawn the first soul
163
-
164
- A soul with `work: worktree | checkout` needs a clone of its repository at
165
- `<dir>/<repo name>` (or named in `oats-local.yaml` `clones:`).
447
+ **Preview the spawn, read it, then spawn:**
166
448
 
167
449
  ```bash
168
- oats souls --dir <dir> # what the workspace offers, with origin and teams
169
- oats spawn backend-expert --preview # modules, commits, merged provider settings — nothing created
170
- oats spawn backend-expert --task "First concrete task"
171
- oats status
172
- ```
173
-
174
- Read the diagnostics below the `oats souls` table before choosing a soul.
175
- Both `oats souls` and `oats capabilities` print all catalog problems there,
176
- on stdout, while partial listings still exit 0. `--json` carries the same
177
- ordered `problems` rows with their owner and path fields (`repoKey`,
178
- `package`, `source`, `path`); a problem does not always mean an item is absent.
179
-
180
- OATS confirms Claude's development-channel prompt by itself whenever it
181
- launches Claude with `--dangerously-load-development-channels
182
- plugin:aweb-channel@awebai-marketplace` (the default `delivery: channel`,
183
- `claudeChannelMode: development`); see
184
- `docs/configuration.md#the-development-channel-confirmation`. There is no
185
- consent setting. To keep the prompt for a person, set
186
- `settings.oats.aweb.delivery: session` or `claudeChannelMode: approved` in
187
- `oats-local.yaml`. The approved route and the host wake broker are set up with
188
- oats.setup's `/oats-host-delivery`. An old `launchPromptAnswers` block is ignored with a warning
189
- (remove it); one with `awebDevelopmentChannel: false` is refused. Handle
190
- folder trust explicitly with `oats harness trust --dir D --harness claude --plan`,
191
- then the same command without `--plan` to apply. Run it on the target host with
192
- native configuration writers quiescent. Use `codex` or `all` for those selected
193
- harnesses; inspect the exact canonical root and effective native file first.
194
- The command changes only deployment-root trust and records an audit under
195
- `D/.agents/harness-trust.jsonl`. A failure can retain an applied native change;
196
- inspect its per-file outcome and audit before retrying. A refused entry's
197
- `problem` names the check that refused its file; for a macOS `@` marker, accept
198
- the harness's own folder-trust dialog instead and check the `harness-trust`
199
- item of `oats readiness` (see "When the writer refuses"). Nested Git boundaries
200
- can prevent Claude inheritance. See [harness trust](../../docs/harness-trust.md). Folder-trust
201
- and API-key questions remain unexpected and blocked. The confirmation is
202
- answered with one Enter only when the screen equals an entry of the tolerance
203
- list, on any pane width wide enough to wrap at word boundaries; a new Claude
204
- wording blocks loudly until a reviewed change adds it. `--no-launch` never
205
- answers. Where channels are unavailable for the Claude account, Claude ignores
206
- the flag and shows no confirmation: the start succeeds with `launchPrompts.status:
207
- "flag-ignored"`, no key, and a warning that the instance has no channel delivery,
208
- so mail and chat will not wake it until delivery changes.
209
- On a first spawn that notice can be hidden behind another one; the start then
210
- blocks, and the error says to look at the pane and restart a running session.
211
- If launch returns `E_SPAWN_INCOMPLETE`, inspect the retained home/pane:
212
- do not respawn, repeat keys or treat `launched:false` as an absent process.
213
- After the Enter, completion is reporting only: 2 s of consecutive clean captures
214
- (no question marker, no confirmation; the screen may change) complete; a marker
215
- or the confirmation coming back blocks; no such window by the 30 s bound is an
216
- observation timeout after the one Enter. See [the completion contract](../../docs/launch-prompt-completion.md).
217
- Unknown dialogs without a marker may be reported completed. Completion closes
218
- input authority, not a readiness or idle-state promise.
219
-
220
- Create and spawn only when asked. After the first spawn, the `oats.setup`
221
- skills carry the rest of the deployment (messaging, more souls, rebuilds); the
222
- `oats.authoring` package teaches writing capabilities, skills and souls. The
223
- model in full is `docs/workspaces.md` in the OATS repository.
224
-
225
- For a retained launch-prompt block after a submitted answer, inspect the existing
226
- launch event and private frame receipt as described in
227
- `docs/execution-targets.md#private-unmatched-launch-evidence`. Do not transmit raw
228
- screen text or treat a saved frame as a new accepted signature. A completed frame is also saved privately. A saved artifact alone
229
- does not establish completion: verify the final checked launch outcome. Missing
230
- effort or unsupported footer shapes can block while the pane is active.
450
+ oats spawn S --dir D --task-file D/.oats-handover.md --preview
451
+ oats spawn S --dir D --task-file D/.oats-handover.md
452
+ ```
453
+
454
+ - **The preview** shows what the spawn would create. If it reports a
455
+ problem, stop and tell the person what it says.
456
+ - **The spawn** prints the instance's home `H`. Then delete the hand-over
457
+ file: the home has its copy as `TASK.md`.
458
+ - **`E_SPAWN_INCOMPLETE`:** don't spawn again. Run `oats session inspect
459
+ --home H --json` and tell the person what it shows.
460
+
461
+ ## 8. Start the Desktop and the TUI, then hand over
462
+
463
+ **The Desktop**, if installed, starts on the new deployment:
464
+ - **macOS:** `open -n -a "OATS Desktop" --args --dir D`. If the Desktop is
465
+ already running, the new launch hands `--dir` to it and exits.
466
+ - **Linux:** the person opens **OATS Desktop** from their app launcher, so it
467
+ starts with their own session's environment, not yours. Then they pick `D`
468
+ in its switcher (**Add local workspace… → Browse**), unless `D` is
469
+ directly inside `~/Agents`.
470
+ - **Never start it with an emptied environment** (`env -i`): it then loses
471
+ HOME, and Git loses the person's login.
472
+
473
+ **The TUI**, if they wanted it, runs in a terminal of its own:
474
+ - **macOS:** open a Terminal window with
475
+ `osascript -e 'tell application "Terminal" to do script "oats tui --dir D"'`.
476
+ - **Linux:** give them `oats tui --dir D` for their terminal.
477
+
478
+ **Tell the person how to reach the setup expert**, and that it continues
479
+ from here:
480
+ - the Desktop;
481
+ - `oats tui --dir D`;
482
+ - `oats session attach --home H` in a terminal.
483
+
484
+ It will ask them only what the hand-over leaves open, and it opens a pane in
485
+ its own window when they need to type a secret. You are done.
486
+
487
+ ## Never
488
+
489
+ - **Ask for, read, print or store a secret,** or suggest `!` for one. If the
490
+ person pastes one into the conversation anyway, don't repeat it, and tell
491
+ them to rotate it.
492
+ - **Overwrite or re-onboard** a deployment, or push to a repository the
493
+ person did not create in step 5.
494
+ - **The Desktop:** never download it through a browser, skip a verification
495
+ step, strip quarantine without asking, or start it with `env -i`.
496
+ - **Put an absolute path, an account or a credential** in
497
+ `oats-workspace.yaml`, `oats-membership.yaml` or a soul.
498
+ - **Spawn** before `oats onboard` confirmed the host.