@awebai/oats 0.69.20 → 0.69.22

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 (53) hide show
  1. package/bin/oats.mjs +26 -3
  2. package/docs/capabilities.md +1 -1
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +311 -4
  5. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  6. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  7. package/docs/desktop-cli-api.md +80 -0
  8. package/docs/desktop.md +404 -177
  9. package/docs/implementation.md +15 -2
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge-capability-authoring.md +1 -1
  12. package/docs/official-catalog.md +44 -1
  13. package/docs/packages.md +2 -2
  14. package/docs/release-lane.md +8 -6
  15. package/docs/release-notes/v0.69.21.md +155 -0
  16. package/docs/release-notes/v0.69.22.md +221 -0
  17. package/docs/servers.md +5 -1
  18. package/docs/souls-and-instances.md +11 -0
  19. package/docs/tui.md +44 -4
  20. package/docs/upgrading.md +16 -5
  21. package/lib/capability-contract.mjs +2 -2
  22. package/lib/command-flags.mjs +1 -0
  23. package/lib/core.mjs +5 -3
  24. package/lib/instance-inspect.mjs +3 -0
  25. package/lib/instance-lifecycle.mjs +16 -0
  26. package/lib/instance-listing.mjs +8 -4
  27. package/lib/instance-pin.mjs +59 -0
  28. package/lib/kernel-features.mjs +1 -1
  29. package/lib/servers.mjs +8 -3
  30. package/package-catalog.json +1 -1
  31. package/package.json +1 -1
  32. package/packages/client/above-tested.mjs +3 -2
  33. package/packages/client/capability-list.mjs +69 -0
  34. package/packages/client/capability-origin.mjs +54 -0
  35. package/packages/client/cli-adapter.mjs +9 -1
  36. package/packages/client/deployment-data.mjs +3 -0
  37. package/packages/client/deployment-panel.mjs +2 -0
  38. package/packages/client/home-board.mjs +50 -0
  39. package/packages/client/instance-pin.mjs +28 -0
  40. package/packages/client/instance-record-outcome.mjs +31 -0
  41. package/packages/client/instance-tree.mjs +62 -20
  42. package/packages/client/keymap.mjs +11 -3
  43. package/packages/client/remote-roster.mjs +8 -1
  44. package/packages/client/roster-row-facts.mjs +50 -0
  45. package/packages/client/roster-sections.mjs +10 -7
  46. package/packages/client/soul-role.mjs +44 -0
  47. package/packages/client/waiting-on-you.mjs +10 -0
  48. package/packages/tui/lib/actions.mjs +11 -4
  49. package/packages/tui/lib/client.mjs +3 -1
  50. package/packages/tui/lib/main.mjs +16 -2
  51. package/packages/tui/lib/model.mjs +48 -5
  52. package/packages/tui/lib/store.mjs +28 -2
  53. package/skills/oats-getting-started/SKILL.md +283 -30
@@ -7,7 +7,7 @@
7
7
  // in. What it adds is the TUI's: the window, the clock times, and which fact stands on which line.
8
8
  import {
9
9
  TERMS, panelData, localDeploymentIds, displayLine, DETAIL_WITHHELD, originLead, instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree,
10
- hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, rosterSectionKey, sidebarSections, backgroundPlacement, BACKGROUND_FEATURE, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor, instanceDisplayName,
10
+ hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, rosterSectionKey, sidebarSections, backgroundPlacement, BACKGROUND_FEATURE, PIN_FEATURE, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor, instanceDisplayName,
11
11
  waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText, instanceActs, rowReason,
12
12
  identityMemory, viewModel, listedViews, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath, machineLabels,
13
13
  openAct, deployments as heldDeployments, localScrollKeys, hostScrollKeys, attachExit, preflightFailure, kernelLines,
@@ -149,6 +149,8 @@ export const BACKGROUND_ID = "\u0000background";
149
149
  * and kept for the run per workspace as `collapsed` is (by `state.open`): `state.background` holds the
150
150
  * ones open. */
151
151
  export const backgroundOpen = (state) => state.background.has(state.open);
152
+ /** Whether this run's kernel lists the pin's feature (instance-pin): a row's `pinned` orders the list only then. */
153
+ export const pinsListed = (state) => Array.isArray(state.cli?.features) && state.cli.features.includes(PIN_FEATURE);
152
154
 
153
155
  /** The key prefix of each run of instances related to no other, as the shared grouping names it
154
156
  * (`independent:<id>`). Read by key, not by label: a cluster whose root is named `independent` has that
@@ -172,7 +174,10 @@ function build(state, at) {
172
174
  // `ordered`: every row in the shared order of the whole roster, whatever is filtered, folded or in the
173
175
  // Background section (the lists of a soul's instances read it).
174
176
  const ordered = [];
175
- for (const part of rosterSections(instances, instances, deployments, TERMS)) for (const group of part.groups) for (const cluster of group.clusters) ordered.push(...cluster.instances);
177
+ // Pinned first (feature instance-pin), as in the Desktop: only when this run's kernel lists the feature; without
178
+ // it a row's `pinned` is ignored and the order is the roster's own.
179
+ const pins = pinsListed(state);
180
+ for (const part of rosterSections(instances, instances, deployments, TERMS, { pins })) for (const group of part.groups) for (const cluster of group.clusters) ordered.push(...cluster.instances);
176
181
  // The rows the Background section holds (#1579), the shared placement's: only when this run's kernel
177
182
  // lists the feature; without it a row's `background` is ignored and nothing below changes.
178
183
  const placement = backgroundPlacement(instances, Array.isArray(state.cli?.features) && state.cli.features.includes(BACKGROUND_FEATURE));
@@ -186,14 +191,14 @@ function build(state, at) {
186
191
  // left out makes an ambiguous name unique. The key without a placement is the deployment's alone.
187
192
  const deploymentOf = rosterSectionKey(deployments), bySection = new Map();
188
193
  for (const row of instances) { const key = deploymentOf(row); if (!bySection.has(key)) bySection.set(key, []); bySection.get(key).push(row); }
189
- const siblings = new Map([...bySection.values()].flatMap((own) => [...instanceSiblings(own)]));
194
+ const siblings = new Map([...bySection.values()].flatMap((own) => [...instanceSiblings(own, { pins })]));
190
195
  const matched = soul !== null ? filterInstanceTree(instances, soul.name, (row) => soul.names.includes(row.agent)) : filterInstanceTree(instances, query);
191
196
  const visible = matched.filter((i) => instanceVisibleInTree(i, instances, state.collapsed, state.open, filtering, { section }));
192
197
  const stale = (row) => rowStale(row, deployments);
193
198
  // The main tree's sections, and the Background section after them, each a tree of its own (the shared
194
199
  // sidebarSections). A filter draws the section open, so its matches show, and changes nothing stored;
195
200
  // the heading counts the rows the filter leaves in it.
196
- const { main: sections, background } = sidebarSections(instances, visible, deployments, TERMS, { placement, open: backgroundOpen(state) || filtering, listed: matched, stale });
201
+ const { main: sections, background } = sidebarSections(instances, visible, deployments, TERMS, { placement, open: backgroundOpen(state) || filtering, listed: matched, stale, pins });
197
202
  // How many instances each collapse folds away under its row: every descendant of the row in its
198
203
  // own section, as the shared walk finds them when it is asked with that collapse alone (so a
199
204
  // fold further down hides none of them from the count). A filter folds nothing away.
@@ -878,7 +883,7 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
878
883
  sibling: siblingText(r.siblings.get(instanceId(row))), text: `${row.instance} ${machine ?? ""}`,
879
884
  };
880
885
  };
881
- for (const section of rosterSections(r.instances, openable, r.deployments, TERMS, { lastFocus })) for (const group of section.groups) {
886
+ for (const section of rosterSections(r.instances, openable, r.deployments, TERMS, { lastFocus, pins: pinsListed(state) })) for (const group of section.groups) {
882
887
  const rows = group.clusters.flatMap((cluster) => cluster.instances).map(item).filter(matched);
883
888
  if (!rows.length) continue;
884
889
  // A group is named, and kept apart, by its deployment where there are several (the Desktop's palette.mjs).
@@ -1140,6 +1145,44 @@ export function actDecision(state, row, acts, verb) {
1140
1145
  return { open: true, verb, id, name, kind: lifecycle ? "lifecycle" : "start", machine, label: machine, home: row.home ?? null };
1141
1146
  }
1142
1147
 
1148
+ /** The TUI's own words around the pin key (feature instance-pin; docs/tui.md, "Pinning"), as parts the way
1149
+ * ACT_WORDS are. `unavailable` says why the key does nothing on a kernel that does not list the feature, and the
1150
+ * command that pins. */
1151
+ export const PIN_WORDS = Object.freeze({
1152
+ unavailable: [{ own: "This OATS can't pin instances: it doesn't list instance-pin. With a newer one, p or `oats instance pin <name> on|off` pins." }],
1153
+ pinning: (name, pinned) => [{ own: pinned ? "Pinning " : "Unpinning " }, { shown: name }, { own: "…" }],
1154
+ still: (name) => [{ own: "The pin of " }, { shown: name }, { own: " is still changing." }],
1155
+ done: (name, pinned) => [{ shown: name }, { own: pinned ? " is pinned to the top of its machine's list." : " is unpinned." }],
1156
+ notChanged: (name) => [{ own: "The pin of " }, { shown: name }, { own: " was not changed." }],
1157
+ unconfirmed: (name) => [{ own: "OATS didn't confirm the pin of " }, { shown: name }, { own: ". The list shows it once it is read again." }],
1158
+ });
1159
+
1160
+ /** What the pin key does on `row` (`acts`: its instanceActs answer): `{ open: true, id, name, pinned }`, `pinned`
1161
+ * the value it sets (Unpin on a pinned row, else Pin), or `{ open: false, said }`, the line that says why not:
1162
+ * without the feature, while this run's pin of the row is still changing, or on a row that offers no act of a
1163
+ * client's own (a held, retiring or unaddressable home: the shared reason). A remote row's host without the
1164
+ * feature is the kernel's to refuse (E_REMOTE_INCOMPATIBLE: nothing is sent), said as its refusal. */
1165
+ export function pinDecision(state, row, acts) {
1166
+ const name = row.instance, id = instanceId(row);
1167
+ const no = (said, under = []) => ({ open: false, said: Object.freeze({ said, under }) });
1168
+ if (!pinsListed(state)) return no(PIN_WORDS.unavailable);
1169
+ if (state.pinning?.has(id)) return no(PIN_WORDS.still(name));
1170
+ const held = acts.blocked ?? acts.limited;
1171
+ if (held) return no([], outside(reasonSpoken(held)));
1172
+ return { open: true, id, name, pinned: row.pinned !== true };
1173
+ }
1174
+
1175
+ /** The line after a pin's answer (packages/client instance-pin.mjs pinOutcome): the change, the kernel's refusal
1176
+ * under the TUI's sentence, or that OATS did not confirm it (the list read after it says what is true). */
1177
+ export function pinLine(name, pinned, answer) {
1178
+ if (answer?.status === "ok" && answer.pinned === pinned) return Object.freeze({ said: PIN_WORDS.done(name, pinned), under: Object.freeze([]) });
1179
+ if (answer?.status === "refused") {
1180
+ const said = kernelLines(answer.reason?.message, undefined, TERMS);
1181
+ return Object.freeze({ said: PIN_WORDS.notChanged(name), under: Object.freeze(said.length ? said : outside(displayLine(answer.reason?.code))) });
1182
+ }
1183
+ return Object.freeze({ said: PIN_WORDS.unconfirmed(name), under: Object.freeze([]) });
1184
+ }
1185
+
1143
1186
  /** What a start's or a restart's answer (the shared startInstance's) shows, as the act view's
1144
1187
  * lines: `{ said }` the TUI's own sentence in parts, `{ text }` a shared sentence or the kernel's
1145
1188
  * line (each already as the shared home words it). Chosen by the answer's fields and codes, never
@@ -12,7 +12,7 @@
12
12
  import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys, chordsRead, paletteKeys } from "./actions.mjs";
13
13
  import { CHORDS, chordFamilyFrom, collapseKey, workspaceStep, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
14
14
  import { defaultDetachKey } from "./config.mjs";
15
- import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
15
+ import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, PIN_WORDS, pinDecision, pinLine, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
16
16
  import { backKeyId, backKeySequences, isBackKey } from "./term/through.mjs";
17
17
  import { windowOf } from "./views/scroll.mjs";
18
18
  import { SPLIT_MIN, splitFits } from "./views/split.mjs";
@@ -133,7 +133,7 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
133
133
  selected: null, collapsed: new Set(), background: new Set(), filter: NO_FILTER, focus: "list", top: 0, loose: false, detailTop: 0, places: new Map(), unread: new Map(), unreadKeys: new Map(), workspaceCursor: null, colour,
134
134
  switcher: NO_SWITCHER,
135
135
  listed: NO_LIST, identities: new Map(),
136
- helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
136
+ helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(), pinning: new Set(),
137
137
  leaderKey: backKeyId(detachKey), leader: null, keyboard: null, keysRead, mac: platform === "darwin", chords: chordKeys(platform === "darwin", actions, CHORDS, keysRead.family, backKeyId(detachKey)), palette: null, paletteKeys: paletteKeys(platform === "darwin"), recent: new Map(), layouts: new Map(), restoring: null, leftFocus: null, souls: NO_SOULS, capabilities: NO_CAPABILITIES,
138
138
  spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
139
139
  notice: null,
@@ -737,6 +737,23 @@ function resumedHeard(state, reading) {
737
737
  return { state, effect: null };
738
738
  }
739
739
 
740
+ /** The pin key on `row` (feature instance-pin; lib/model.mjs pinDecision): at once, no confirmation. The line under
741
+ * the sidebar's title says it is changing, the row is held from a second press until the answer, and the loop runs
742
+ * the kernel's verb (`{ pin }`); a key it does nothing for says why on that line. */
743
+ function pinOn(state, row) {
744
+ const decision = pinDecision(state, row, instanceActs(row));
745
+ if (!decision.open) return { state: next(state, { outcome: decision.said }), effect: null };
746
+ const pinning = new Set(state.pinning); pinning.add(decision.id);
747
+ const outcome = Object.freeze({ said: PIN_WORDS.pinning(decision.name, decision.pinned), under: Object.freeze([]) });
748
+ return { state: next(state, { pinning, outcome }), effect: { pin: Object.freeze({ id: decision.id, row, pinned: decision.pinned }) } };
749
+ }
750
+ /** A pin answered (lib/main.mjs): the line says how, the row is free again, and the rows are read again, so the
751
+ * list moves (a refusal changes nothing, and the read says so too). */
752
+ function pinHeard(state, { id, name, pinned, answer }) {
753
+ const pinning = new Set(state.pinning); pinning.delete(id);
754
+ return { state: next(state, { pinning, outcome: pinLine(name, pinned, answer) }), effect: { refresh: { live: true } } };
755
+ }
756
+
740
757
  /** A Remove answered (lib/main.mjs): the switcher says how, and the list is read again. */
741
758
  function removedHeard(state, { name, ok, reason = null }) {
742
759
  const line = Object.freeze(ok ? { removed: name } : { notRemoved: name, message: reason?.message ?? "" });
@@ -1477,6 +1494,13 @@ function led(state, does, event, keymap) {
1477
1494
  const stay = { state, effect: null }, t = state.terminal;
1478
1495
  const inTerminal = t?.focus === "terminal" && state.view === "instances";
1479
1496
  if (does === "list") return toList(state);
1497
+ // The shared table's `b` (the Desktop's sidebar; the Desktop UI rework, slice 4): the list is the TUI's sidebar. With
1498
+ // a terminal shown, it takes the whole screen with the focus (as zoom does), and zoomed, the list comes back with the
1499
+ // focus (as Esc does). With none shown the list is all there is: nothing.
1500
+ if (does === "sidebar") {
1501
+ if (t === null || state.view !== "instances") return stay;
1502
+ return t.zoom ? toList(state) : { state: terminalWith(state, { focus: "terminal", zoom: true }), effect: null };
1503
+ }
1480
1504
  if (does === "palette") return { state: paletteOpened(state, event, inTerminal ? "terminal" : "list"), effect: null };
1481
1505
  if (does === "zoom" || does === "close-terminal") {
1482
1506
  if (t === null) return stay;
@@ -1661,6 +1685,7 @@ function reduced(state, event, keymap) {
1661
1685
  if (event.retiring !== undefined) return { state: next(state, { retiring: new Set(event.retiring) }), effect: null };
1662
1686
  if (event.listed !== undefined) return listedHeard(state, event.listed);
1663
1687
  if (event.removed !== undefined) return removedHeard(state, event.removed);
1688
+ if (event.pinned !== undefined) return pinHeard(state, event.pinned);
1664
1689
  // The machine sweep's reading: no line, at most a live read.
1665
1690
  if (event.resumed !== undefined) return resumedHeard(state, event.resumed);
1666
1691
  // Shown once, in the line under the sidebar's title, as the line after an open is.
@@ -1762,6 +1787,7 @@ function reduced(state, event, keymap) {
1762
1787
  return refused === true ? { state, effect: null } : refused !== null ? { state: next(state, { outcome: refused }), effect: null } : splitKey(state, action, false);
1763
1788
  }
1764
1789
  case "stop": case "retire": case "start": case "restart": return at < 0 ? stay : actOn(state, r.items[at].row, action);
1790
+ case "pin": return at < 0 || !r.items[at].row ? stay : pinOn(state, r.items[at].row);
1765
1791
  case "detail": return at < 0 ? stay : { state: next(state, { focus: state.focus === "detail" ? "list" : "detail" }), effect: null };
1766
1792
  case "up": case "down": case "top": case "bottom": case "page-up": case "page-down": {
1767
1793
  if (state.focus === "detail") return { state: next(state, { detailTop: scrolled(state.detailTop) }), effect: null };
@@ -4,7 +4,8 @@ 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
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
7
+ no sign-in, on the person's own account if they sign in, or on their own
8
+ aweb server), writes a new
8
9
  workspace's skeleton (or joins this machine to an existing workspace),
9
10
  spawns the workspace's setup expert, which does the rest, and opens the
10
11
  Desktop on it. Offers the TUI.
@@ -82,7 +83,10 @@ costs the person a round. After that yes, nothing more is asked.
82
83
  - **One yes covers the changes to their computer.** Step 1's message lists
83
84
  them in plain words, and their yes covers every one: don't ask again step
84
85
  by step. The list, from step 2's checks: the tools you install (on Linux
85
- per user, under `~/.local`; on macOS with Homebrew), the line that puts
86
+ per user, under `~/.local`; on macOS with Homebrew), on their own aweb
87
+ server (step 1) `aw` at the version this OATS release was tested with on
88
+ such a server, when none is installed or the installed one is older (a
89
+ newer one is kept), the line that puts
86
90
  them on their PATH in their shell's startup file (`~/.local/bin` on Linux;
87
91
  on macOS, Homebrew's `brew shellenv` line, only when Homebrew is new), the
88
92
  aweb channel plugin in Claude (Claude only) or pi's aweb extension,
@@ -235,6 +239,31 @@ the final values in one short message before you go on. The rules:
235
239
  - Tell them they attach themselves to that account later in the setup, with
236
240
  the setup expert. Only if they want the team on their own aweb account
237
241
  now, they sign in to it in their browser in step 5 instead.
242
+ - **Hosted aweb, or their own aweb server?** The line says "on aweb's
243
+ hosted service, unless you run your own aweb server"; hosted is the
244
+ default. Keep its second half in your own words too: it is how a
245
+ person with their own server learns this branch exists. With their own
246
+ server, the same round asks three things, none of them secret: the
247
+ namespace domain `ND` they control (for example
248
+ `agents.acme.com`, written in lowercase), the server's public address
249
+ `U` (`https://…`, the API URL their server gives its users), and whether
250
+ their server uses the public AWID registry. Answers given in the prompt
251
+ that started you are used without asking. When it uses a private
252
+ registry, ask its address too, the registry origin `RG` (`https://…`,
253
+ the scheme and host only, with no path), also not a secret. Step 9
254
+ records it for this deployment. Then tell them, in
255
+ plain words, what must already be in place on their side, since you
256
+ make none of it: the namespace's controller key on this computer, for
257
+ this computer account; the `_awid.ND` DNS record published for that
258
+ key; and their server reachable at `U`. On a private registry, that
259
+ record must name their registry: a key prepared without
260
+ `--registry RG` gives a record for the public registry, so tell them
261
+ to check that its value carries `registry=RG`. Step 9
262
+ checks them, read-only. On their own server there is no account `N` and
263
+ no step 5: the team is `<workspace>:ND`, created in step 9 in their
264
+ namespace, and `A` is `<workspace>-root` as on hosted. Never offer it on
265
+ a machine found-list, or for an existing workspace: its invite carries
266
+ the team and the server.
238
267
  - **The harness for the setup expert:** `claude`, `codex` or `pi`. Default:
239
268
  the one you are, if it is one of these.
240
269
  - **The deployment directory `D`:** where OATS lives on this machine.
@@ -533,7 +562,7 @@ installed CLI's catalog:
533
562
  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"
534
563
  ```
535
564
 
536
- It prints the two refs, for example `oats-framework/v1.26.0 v1.42.1`. If the
565
+ It prints the two refs, for example `oats-framework/v1.26.0 v1.45.0`. If the
537
566
  framework's version (after the `/`) is below `1.19.0`, or with aweb
538
567
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
539
568
  skill: stop, and tell the person to wait for the next OATS
@@ -560,12 +589,68 @@ you can check `"skills":[]`:
560
589
  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)))'
561
590
  ```
562
591
 
592
+ **On hosted aweb** (the default), the latest `aw`:
593
+
563
594
  ```bash
564
595
  npm install -g @awebai/aw && aw version
565
596
  ```
566
597
 
567
598
  `aw` must be 1.36.33 or later.
568
599
 
600
+ **On their own aweb server** (step 1), `aw` is the version this OATS
601
+ release's `oats.aweb` was tested with, which `oats.aweb` publishes in its
602
+ `aw-compat.json`: hosted aweb upgrades its server before a new `aw` comes
603
+ out, but their own server has no such order. Read that version at the exact
604
+ `oats.aweb` release the installed CLI's catalog names, never at `main`.
605
+ On a private registry (step 1), add ` private` at the end of the line,
606
+ after the catalog's path: that branch needs a later `oats.aweb`. This
607
+ prints `TESTED <version>`, or why it can't:
608
+
609
+ ```bash
610
+ node -e 'const c=require(process.argv[1]).packages["oats.aweb"],m=/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(c.url),v=/^v(\d+)\.(\d+)\.(\d+)$/.exec(c.ref);if(!m){console.log("NOT_GITHUB "+c.url);process.exit(1)}if(process.argv.length>3||![undefined,"private"].includes(process.argv[2])){console.log("FAILED usage");process.exit(1)}const f=process.argv[2]?[1,43,0]:[1,42,1];if(!v||v.slice(1).reduce((d,x,i)=>d||x-f[i],0)<0){console.log("TOO_OLD "+c.ref);process.exit(1)}const u="https://raw.githubusercontent.com/"+m[1]+"/"+m[2]+"/"+c.ref+"/"+c.path+"/capabilities/oats-aweb/aw-compat.json";fetch(u).then(r=>{if(!r.ok)throw new Error("HTTP "+r.status+" "+u);return r.json()}).then(j=>{if(Object.keys(j).sort().join()!=="min,tested"||typeof j.tested!=="string"||!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/.test(j.tested))throw new Error("unexpected "+JSON.stringify(j));console.log("TESTED "+j.tested)}).catch(e=>{console.log("FAILED "+e.message);process.exit(1)})' "$(oats root)/package-catalog.json"
611
+ ```
612
+
613
+ - **`TOO_OLD`:** this OATS release's `oats.aweb` is older than `v1.42.1`,
614
+ the first that sets up a team on a person's own server, or, on a private
615
+ registry, older than `v1.43.0`, the first that records the registry
616
+ (`oats aweb setup --registry`).
617
+ **`NOT_GITHUB` or `FAILED`:** the tested version can't be read. Either
618
+ way, the own-server branch stops here. Tell the person in one sentence,
619
+ and offer hosted aweb now (step 1's hosted defaults, `N` among them,
620
+ shown in one short message) or waiting for the next OATS release.
621
+ - **`TESTED <tested>`:** compare it with the `aw` already installed, in
622
+ `oats.aweb`'s own version order, where a pre-release of a newer version
623
+ counts as newer. With `<tested>` written in:
624
+
625
+ ```bash
626
+ node -e 'const P=(s)=>{const m=/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(s);if(!m)return null;const r=[m[1],m[2],m[3]].map(Number);return r.every(Number.isSafeInteger)?{r,p:m[4]?m[4].split("."):[]}:null};const C=(a,b)=>{for(let i=0;i<3;i++)if(a.r[i]!==b.r[i])return a.r[i]-b.r[i];if(!a.p.length||!b.p.length)return b.p.length-a.p.length;for(let i=0;i<Math.min(a.p.length,b.p.length);i++){const x=a.p[i],y=b.p[i],xn=/^\d+$/.test(x),yn=/^\d+$/.test(y);if(x===y)continue;if(xn&&yn)return x.length!==y.length?x.length-y.length:x<y?-1:1;if(xn!==yn)return xn?-1:1;return x<y?-1:1}return a.p.length-b.p.length};const t=P(process.argv[1]),l=/^aw (\S+)$/.exec(process.argv[2]||""),v=l&&P(l[1]);if(!t){console.log("FAILED tested "+process.argv[1]);process.exit(1)}const d=v?C(v,t):-1;console.log(d<0?"INSTALL":d===0?"EQUAL "+l[1]:"NEWER "+l[1])' "<tested>" "$(aw version 2>/dev/null | head -n 1)"
627
+ ```
628
+
629
+ - **`INSTALL`:** no `aw`, a version it can't read, or one below
630
+ `<tested>` (below `oats.aweb`'s floor included). Install exactly
631
+ `<tested>`, then check it:
632
+
633
+ ```bash
634
+ npm install -g "@awebai/aw@<tested>" && aw version && file -L "$(command -v aw)" && uname -m
635
+ ```
636
+
637
+ `aw version`'s first line must be exactly `aw <tested>`, and the `file`
638
+ line must name this machine's architecture, the one `uname -m` prints
639
+ (`x86-64` for `x86_64`, `aarch64` for `aarch64` on Linux; `x86_64` or
640
+ `arm64` on macOS). A different version, or a program for another
641
+ machine or no program at all (npm put a wrong or missing build in
642
+ place), stops the own-server branch as above. Where `file` itself is
643
+ missing (`command not found`), say so in the hand-over and rely on
644
+ `aw version`: a program that runs and prints its version was built for
645
+ this machine. Keep `aw <tested>` for the hand-over.
646
+ - **`EQUAL <tested>`:** that version is installed already: install
647
+ nothing. Keep `aw <tested>` for the hand-over.
648
+ - **`NEWER <version>`:** a newer `aw` is installed. Keep it, install
649
+ nothing, and go on: another deployment on this computer may need it.
650
+ Keep "aw <version> is newer than the tested <tested>; kept" for the
651
+ hand-over: it is the version this setup ran with.
652
+ - **`FAILED`** stops the own-server branch as above.
653
+
569
654
  **Then the Desktop. Every step verifies before it installs.** Wait for step
570
655
  3's download, then read its log. Run this once: it waits up to a minute
571
656
  for a `DONE` line ("How to work", the time budget):
@@ -650,8 +735,9 @@ Categories=Development;
650
735
 
651
736
  **Only for a new workspace with aweb whose person chose, in step 1, the team
652
737
  on their own aweb account now.** Otherwise skip it: step 9 creates the
653
- workspace's account (the default), joins an existing workspace and signs up a machine
654
- found-list.
738
+ workspace's account (the default), joins an existing workspace, signs up a machine
739
+ found-list and creates the team on their own aweb server, which has no
740
+ account to sign in to.
655
741
 
656
742
  The workspace's agents share one team, its **default team**, which the
657
743
  person's own aweb account creates here. Say to them, in your words, exactly
@@ -771,7 +857,7 @@ members:
771
857
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
772
858
  packages:
773
859
  oats.framework: v1.26.0 # the installed CLI's catalog versions (below)
774
- oats.aweb: v1.42.1 # messaging: agent identities, mail and chat
860
+ oats.aweb: v1.45.0 # messaging: agent identities, mail and chat
775
861
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
776
862
  defaults:
777
863
  capabilities:
@@ -789,6 +875,11 @@ defaultTeam: acme # every soul starts in this team
789
875
  9's signup creates, checked there against this line. With step 5's
790
876
  sign-in, it is `T` from step 5 instead, written in literally. Its label
791
877
  (here `acme`) is the workspace name.
878
+ - **On their own aweb server,** the team is `<workspace>:ND` (here
879
+ `acme:agents.acme.com`), with `ND` from step 1: the team step 9 creates
880
+ in their namespace, checked there against this line. It is the only team
881
+ and the default: no `default:…aweb.ai` team anywhere in the file, and no
882
+ `localTeams`.
792
883
  - **The `oats.machine` line,** at the catalog's
793
884
  `packages."oats.machine".ref`, only on a machine found-list.
794
885
  - **The `tasks` line** is step 1's tasks answer: `oats.aweb-tasks` without
@@ -933,6 +1024,30 @@ below; for another capability, follow its own setup skill, and stop if its
933
1024
  readiness still reports a problem.
934
1025
 
935
1026
  **With aweb (`oats.aweb`):**
1027
+
1028
+ **Their own aweb server on a private registry (step 1): record it first,**
1029
+ before item 1, with `RG` written in. Skip this on the public registry and
1030
+ on hosted aweb.
1031
+
1032
+ ```bash
1033
+ cd "D" && oats aweb setup --soul S --registry RG
1034
+ ```
1035
+
1036
+ It writes only `settings.oats.aweb.registry` in `D/oats-local.yaml`, the
1037
+ one setting that admits a private registry here: every later `oats aweb`
1038
+ command and every agent of `D` reads its registry from it. Never set
1039
+ `AWID_REGISTRY_URL` instead: oats.aweb refuses a private registry given
1040
+ that way (`registry-setting-required`), item 1's check included, until
1041
+ this setting is recorded. Success prints one line of JSON whose
1042
+ `registry` is `RG` as an origin (the host in lowercase, no trailing `/`).
1043
+ Its `next` lists "Restart resident serve" and "Restart wake": both are
1044
+ expected and need nothing from you, since this new deployment has no
1045
+ resident yet and item 6 installs the broker after this. An
1046
+ `E_SETUP_REGISTRY` refusal that starts `settings.oats.aweb.registry:`
1047
+ says what is wrong with the address (a path, `/api`, a query): ask the
1048
+ person for the registry's origin again and run this again. Anything
1049
+ else: stop, spawn nothing, and tell the person what it shows.
1050
+
936
1051
  1. **Check:**
937
1052
 
938
1053
  ```bash
@@ -957,8 +1072,9 @@ readiness still reports a problem.
957
1072
  `oats sync --dir D`, then check again.
958
1073
  2. **A new workspace without step 5's sign-in, and a machine found-list:
959
1074
  sign up the workspace's aweb account and team,** with `N` and `A` from
960
- step 1: no API key or token, nothing for the person to type. Preview
961
- first, then run it:
1075
+ step 1: no API key or token, nothing for the person to type. On their
1076
+ own aweb server there is no signup: take "Their own aweb server", the
1077
+ last part of this item, instead. Otherwise preview first, then run it:
962
1078
 
963
1079
  ```bash
964
1080
  cd "D" && oats aweb setup --soul S --username N --name A --label L --plan --json
@@ -972,11 +1088,20 @@ readiness still reports a problem.
972
1088
  - **Then tell the person,** in your words: this is the workspace's
973
1089
  team, on an aweb account created for it; they attach themselves to it
974
1090
  later in the setup, with the setup expert.
975
- - **`E_SETUP_NATIVE`:** most likely `N` is taken (the preview does not
976
- contact aweb, and aw's output is withheld); the run may also have left
977
- a root part-way. Never remove `D/.aw`, and never rerun blindly.
1091
+ - **`E_SETUP_USERNAME_UNAVAILABLE`:** aw refused `N` (its message says
1092
+ why: taken, reserved or its format), and nothing was created. On a
1093
+ machine found-list, ask nothing: tell the person what it says, and
1094
+ stop. Otherwise ask the person for another `N`, change the team line in
1095
+ `D/<repo>/oats-workspace.yaml` to `default:<new N>.aweb.ai`, commit and
1096
+ push it, run `oats sync --dir D`, then run the preview and the signup
1097
+ again with the new `N`.
1098
+ - **`E_SETUP_NATIVE`:** aw failed, and its output is withheld (the
1099
+ preview does not contact aweb). An oats.aweb older than the one that
1100
+ answers `E_SETUP_USERNAME_UNAVAILABLE` (awebai/oats-aweb#286) also
1101
+ fails this way when `N` is taken. The run may also have left a root
1102
+ part-way. Never remove `D/.aw`, and never rerun blindly.
978
1103
  On a machine found-list, ask nothing: tell the person that the run
979
- failed, most likely because `N` is taken, and stop.
1104
+ failed, and that `N` may be taken, and stop.
980
1105
  Otherwise look first, read-only: `test -e "D/.aw" && echo RETAINED`.
981
1106
  - **Nothing printed:** aw kept nothing, so `N` is free to change. Ask
982
1107
  the person for another `N`, change the team line in
@@ -989,6 +1114,57 @@ readiness still reports a problem.
989
1114
  unchanged, and it reuses that root. Anything else, the preview
990
1115
  failing included: stop, spawn nothing, and tell the person what it
991
1116
  shows.
1117
+ - **Their own aweb server (step 1), in place of the signup.** Nothing for
1118
+ the person to type, and no key passes through you. `ND`, `U` and `A`
1119
+ come from step 1, and `L` is step 7's label.
1120
+ - **First, the prerequisites, read-only:**
1121
+
1122
+ ```bash
1123
+ cd "D" && aw id namespace check-txt --domain ND --json; echo "exit=$?"
1124
+ ```
1125
+
1126
+ It fails when the controller key for `ND` is not on this computer
1127
+ for this account, or when the `_awid.ND` record is missing, not
1128
+ visible yet, or names another key. Its output says which. Then stop
1129
+ and spawn nothing. Tell the person in one plain sentence which one is
1130
+ missing, and that it's theirs to put in place, on their side. Once
1131
+ they say it is, run this part again from here. Never make the key
1132
+ (`aw id namespace prepare-controller`) or touch `~/.awid`.
1133
+ - **Then create the team,** registered with their server. It takes up
1134
+ to a few minutes. There is no preview, and it prints text, not JSON:
1135
+
1136
+ ```bash
1137
+ cd "D" && AWEB_URL="U" oats aweb setup --soul S --create L --namespace ND --name A
1138
+ ```
1139
+ - **Success** prints `✓ created <T>, accepted it into <root>, recorded
1140
+ roots[<T>]`. `<T>` must be step 7's team line, `L:ND`. Anything else:
1141
+ stop, spawn nothing, and tell the person what it shows. Two more of
1142
+ its lines are expected, and need nothing from you. Since step 7
1143
+ wrote no `localTeams`, it says the workspace "does not allow local
1144
+ teams" and shows `teams:` lines to commit: step 7 committed them
1145
+ already, so when the team they show is step 7's line, nothing is
1146
+ left to do. Its `readiness:` line can say
1147
+ `needs-configuration`: item 5's check decides, not that line.
1148
+ - **`team key: <path>`** is where the key of their agents' group now
1149
+ lives on this computer. Tell the person that, in plain words, and that
1150
+ they keep it backed up and never share it. The path, never the key,
1151
+ goes in the hand-over.
1152
+ - **"already exists in the registry, and its team key is not on this
1153
+ machine":** `L:ND` is taken in their namespace, and nothing was
1154
+ created. Ask the person for another name for the group, in the same
1155
+ form as the workspace name. In `D/<repo>/oats-workspace.yaml`, change
1156
+ the team's label, its `team:` and `defaultTeam` to it, then commit
1157
+ and push it, and run `oats sync --dir D`. Run the create again, with
1158
+ the new label as `L`.
1159
+ - **"re-run the same command to resume",** or a run that was killed or
1160
+ timed out: run the same line again, unchanged. It continues the
1161
+ create, and never makes a second team.
1162
+ - **Anything else** (a refused registration, a team-server record that
1163
+ names another address, a missing controller key): stop, spawn
1164
+ nothing, and tell the person in one sentence what it means. Never
1165
+ rerun it with other values.
1166
+ - **Then tell the person,** in your words: this is the group their
1167
+ agents talk in, on their own server, in their namespace `ND`.
992
1168
  3. **Existing workspace: the person gets an invite** from a member of `L`,
993
1169
  whose own agent runs
994
1170
  `oats aweb invite --soul <their soul> --label L --json` in their
@@ -1009,7 +1185,15 @@ readiness still reports a problem.
1009
1185
  owner decides.
1010
1186
  4. **Existing workspace: the person joins in their own terminal,** which you
1011
1187
  open for them ("How to work"), pasting the token at the hidden prompt,
1012
- with `D`, `S` and `A` filled in:
1188
+ with `D`, `S` and `A` filled in. Before you open it, list the per-team
1189
+ roots `D` already holds, read-only, and keep what it prints (often
1190
+ nothing) for item 5:
1191
+
1192
+ ```bash
1193
+ ls -d "D"/.aweb-roots/*/.aw 2>/dev/null
1194
+ ```
1195
+
1196
+ Then open the window:
1013
1197
 
1014
1198
  ```text
1015
1199
  cd "D" && sh -c 'stty -echo; printf "Invite token: "; read -r T; stty echo; echo; printf "%s\n" "$T" | oats aweb setup --soul S --invite-stdin --name A'
@@ -1032,17 +1216,38 @@ readiness still reports a problem.
1032
1216
  ```
1033
1217
 
1034
1218
  5. **After items 2 to 4, check again** (item 1), and expect `"member": true`.
1035
- On `"member": false`, stop and spawn nothing. With `"root": null` after
1036
- item 4's invite-only form, look first, read-only:
1037
- `ls -d "D"/.aweb-roots/*/.aw 2>/dev/null`. Nothing printed: the join
1038
- refused before redeeming anything: ask the person for the `E_SETUP_`
1039
- code their window shows (a code, no secret), tell them in plain words
1040
- what it means, and that a new invite is the inviter's to send. A path
1041
- printed for a label other than `L`: the invite was for that team, and
1042
- this machine joined it instead: tell them so, and that an invite for
1043
- `L` is the inviter's to send. Otherwise tell the person the run
1044
- left this machine's root outside `L`, with what the check shows, and
1045
- don't rerun the signup or the join (you can't see the join's output).
1219
+ On `"member": false`, stop and spawn nothing, and read why from what ran:
1220
+ - **`"root": null` after item 2's signup:** no root was made in `D/.aw`:
1221
+ the signup didn't finish. Tell the person so, with what the check
1222
+ shows, and don't rerun it.
1223
+ - **`"root": null` after a team create in item 2** (a create line, not
1224
+ the signup): the create recorded no root. Run the same create line
1225
+ again, unchanged, then check again.
1226
+ - **`"root": null` after item 4's invite-only form:** run item 4's
1227
+ listing again, read-only, and compare it with what it printed before
1228
+ the window opened: only a path that is new is this join's. The folder
1229
+ before `/.aw` is the team's label as the provider writes a team name:
1230
+ lowercase, each run of `_` or `.` as one `-`, and no `-` at either end
1231
+ (`My_Team.` is `my-team`). Write `L` that way too before you compare.
1232
+ - **No new path:** the join made no root here. It refused before
1233
+ redeeming anything, or aw's own accept failed and the join removed
1234
+ the empty folder it had made. Ask the person for the `E_SETUP_` code
1235
+ their window shows, if any (a code, no secret); with no code, ask
1236
+ what the window's last line says (no secret). Tell them in plain
1237
+ words what it means, and that a new invite is the inviter's to send.
1238
+ - **A new path under another name:** the invite was for that team,
1239
+ and this machine joined it instead: tell them so, and that an invite
1240
+ for `L` is the inviter's to send.
1241
+ - **A new path under `L`'s name:** the join began in `L`'s folder and
1242
+ didn't finish. Tell the person so, with what the check shows.
1243
+ - **`"root": null` after item 4's labelled form:** the join recorded no
1244
+ root: it stopped at a refusal or a failure, which its window shows.
1245
+ Ask for the `E_SETUP_` code there, if any, or else the window's last
1246
+ line (no secret), and tell the person in plain words what it means.
1247
+ - **With a `root`:** the run left this machine's root outside `L`. Tell
1248
+ the person so, with what the check shows.
1249
+
1250
+ Don't rerun the signup or the join (you can't see the join's output).
1046
1251
  When another machine of the same name may already be in the team, say
1047
1252
  that a taken name is a likely cause: the person who invited them can ask
1048
1253
  their own agent whether that name is in the group (its agent reads
@@ -1054,8 +1259,45 @@ readiness still reports a problem.
1054
1259
  `delivery: session`: its own channel wakes it (step 4). Any other setup
1055
1260
  expert is woken only by the host wake broker, and oats.aweb refuses to
1056
1261
  spawn or start it while no broker runs (`wake-daemon-not-running`). The
1057
- broker is the person's own user service, so it is theirs to start. Open
1058
- their own terminal ("How to work") running this, with `D` filled in:
1262
+ broker is the person's own user service, so it is theirs to start.
1263
+
1264
+ **On a private registry (step 1), first check the install yourself,**
1265
+ read-only: the broker must carry `RG`, and the status check below can't
1266
+ see which registry a running broker serves.
1267
+
1268
+ ```bash
1269
+ cd "D" && oats aweb wake install --plan --json
1270
+ ```
1271
+
1272
+ It changes nothing, and it refuses whatever the install would refuse.
1273
+ Only `"ok": true` lets you go on to their install below: then no other
1274
+ broker runs on this computer account, or the one that runs is the
1275
+ install's own and already carries `RG`, so the status check below
1276
+ proves the right broker. Otherwise its `error.code` decides:
1277
+ - **`E_WAKE_REGISTRY_CONFLICT`:** this computer account already runs a
1278
+ wake broker for another registry, or for none, most likely for
1279
+ another deployment, and one account's broker serves one registry.
1280
+ Stop, spawn nothing, and tell the person in plain words; the choice is
1281
+ theirs: run this deployment under another computer account, or move
1282
+ the other one, as the message says. Never uninstall the broker or
1283
+ deregister another deployment's homes yourself.
1284
+ - **`E_WAKE_UNSUPPORTED`** (a container, or a machine with neither
1285
+ launchd nor systemd): there is no service to install, and the plain
1286
+ `aw wake run` below would not carry `RG`. Stop and spawn nothing.
1287
+ Tell the person in one sentence, and offer a Claude or pi setup
1288
+ expert instead, which its own channel wakes: with that harness, this
1289
+ item is skipped.
1290
+ - **Any other refusal** (for example a broker started by hand or by
1291
+ another supervisor, `E_WAKE_RUNNING_UNSUPERVISED`, or a service the
1292
+ install didn't write, `E_WAKE_UNIT_CONFLICT`): stop and spawn nothing.
1293
+ A broker that is running now would pass the status check without
1294
+ carrying `RG`. Tell the person in plain words what its message says;
1295
+ the fix is theirs, and the message names it. Once they say it's done,
1296
+ run this check again. Never stop, uninstall or deregister a broker
1297
+ yourself.
1298
+
1299
+ Open their own terminal ("How to work") running this, with `D` filled
1300
+ in:
1059
1301
 
1060
1302
  ```text
1061
1303
  cd "D" && oats aweb wake install
@@ -1063,7 +1305,8 @@ readiness still reports a problem.
1063
1305
 
1064
1306
  In a container, or on a machine with neither launchd nor systemd (the
1065
1307
  command answers `E_WAKE_UNSUPPORTED`), there is no service to install:
1066
- the line is `aw wake run`, kept running as a supervised process.
1308
+ on the public registry, the line is `aw wake run`, kept running as a
1309
+ supervised process.
1067
1310
 
1068
1311
  Then check it yourself:
1069
1312
 
@@ -1146,8 +1389,12 @@ are cloned, knowledge tools, messaging wanted or not>
1146
1389
  team T on aweb account N, created for the workspace, not yet attached to
1147
1390
  the person (new workspace), or T owned by aweb account <handle>
1148
1391
  (signed in at step 5), or new account N signed up (machine found-list),
1149
- or joined L by invite (existing) | not set up (the setup expert has no
1150
- messaging)
1392
+ or joined L by invite (existing), or team T on their own aweb server U,
1393
+ namespace ND, registry public | RG (recorded in
1394
+ `settings.oats.aweb.registry`), aw <tested> (oats.aweb's tested
1395
+ version) or "aw <version> is newer than the tested <tested>; kept", its
1396
+ key at
1397
+ <team key path> | not set up (the setup expert has no messaging)
1151
1398
  - Harness channel mode: development, confirmed by OATS at each start
1152
1399
  (Claude with aweb) | none (Codex, pi or no messaging)
1153
1400
  - Tasks (new workspace with aweb): oats.aweb-tasks | none: the agents use
@@ -1311,7 +1558,13 @@ the setup expert, not in this message. You are done.
1311
1558
  push to a repository other than the new workspace's host they agreed to in
1312
1559
  step 1 (step 6 creates or clones it).
1313
1560
  - **Guess the team id:** it is the signup's `default:N.aweb.ai`, checked in
1314
- step 9, or step 5's answer after its sign-in.
1561
+ step 9, step 5's answer after its sign-in, or `<workspace>:ND` on their own
1562
+ aweb server, checked against step 9's create.
1563
+ - **On their own aweb server:** make or touch the namespace's controller key
1564
+ (`aw id namespace prepare-controller`, `~/.awid`), set or ask for
1565
+ `AWEB_API_KEY`, set `AWID_REGISTRY_URL` (a private registry is
1566
+ recorded by `oats aweb setup --registry` only), or write a hosted
1567
+ `default:…aweb.ai` team or `localTeams` into the workspace.
1315
1568
  - **Write a setup soul into the workspace:** the setup expert is
1316
1569
  `oats.framework`'s.
1317
1570
  - **The Desktop:** never download it through a browser, skip a verification