@awebai/oats 0.36.1 → 0.38.0

package/docs/desktop.md

@@ -104,6 +104,39 @@ opened, or your home directory when there is none (never ~/Downloads);
 
 Launch flags for scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
 
+### One window per workspace
+
+Each workspace has at most one window, titled with the workspace's name (a
+workspace on a server: `name — server`).
+
+- **Switching.** Choosing a workspace in the switcher shows it in the current
+  window. If that workspace already has a window, that window comes to the
+  front instead and the current one doesn't change.
+- **Open in new window.** Each workspace in the switcher has an **Open in new
+  window** button beside it. From the keyboard: Right Arrow on the workspace,
+  then Enter, or ⌘Enter on macOS / Ctrl+Enter on Linux and Windows. A
+  workspace that already has a window is brought to the front.
+- **New Window.** On macOS, **File → New Window** (⌘⇧N); everywhere,
+  **Window: new window** in the command palette. The new window has no
+  workspace yet: it opens the switcher, and shows "Choose a workspace" until
+  you pick one. It reads nothing until then.
+- **Moving between windows.** On macOS, ⌘\` cycles the app's windows, and the
+  **Window** menu lists them.
+- **Restore.** Quitting and relaunching brings every window back with its
+  size and place (moved onto a visible display if its own is gone). A window
+  whose workspace isn't served at launch doesn't come back, but it is
+  remembered until you close it while its workspace is served. With nothing
+  to restore, one window opens on the last workspace you used.
+- **Launching again.** Running the app again (`open -a "OATS Desktop" --args
+  --dir <deployment>`, or from inside a deployment) adds that deployment if
+  needed and brings its window to the front, opening one if it has none. Any
+  other launch brings the most recently used window to the front.
+- **Closing.** Closing a window leaves the other windows, and their
+  terminals, running. Closing the last window quits the app.
+- Tabs belong to their window: a workspace's terminals and tabs stay in the
+  window they were opened in, and switching that window back to the
+  workspace brings them back.
+
 ## One workspace, several machines
 
 The switcher lists each workspace once, however many deployments it has: the

package/docs/first-team.md

@@ -102,17 +102,24 @@ that its session will stop at the folder-trust prompt, and so does
 With a messaging capability in the soul's composition, every instance lives in
 a team, and readiness fails with `E_TEAM_UNCONFIGURED` until there is a
 default. Create the team with your messaging provider (its own docs say how;
-for `oats.aweb`, see its skills), then record it here:
+for `oats.aweb`, see its skills), then commit it in `oats-workspace.yaml` as a
+**shared** team and the workspace's default:
+
+```yaml
+teams:
+  research: { team: "<provider team id>" }
+defaultTeam: research
+```
 
 ```bash
-oats teams add research --team <provider team id>   # a local team; the first one becomes the default
-oats teams                                           # shared and local teams, and the default
+oats teams                                           # shared and local teams, the default, the workspace's souls:
 ```
 
-A team the whole workspace uses is committed as a **shared** team in
-`oats-workspace.yaml`; which souls join which team on this machine is
-`oats soul teams` ([workspaces.md](workspaces.md#teams)). Without messaging,
-skip this step.
+Which other teams each soul may join is committed there too, in `souls:`
+([workspaces.md](workspaces.md#teams)). A team only this deployment uses is a
+**local** team (`oats teams add research --team <provider team id>`; the first
+one becomes this deployment's default), which the workspace must allow with
+`localTeams: true`. Without messaging, skip this step.
 
 ## 4. Look before you spawn
 

package/docs/integrations.md

@@ -41,7 +41,7 @@ arrives from.
 # oats-workspace.yaml: one default per slot, for every soul
 packages:
   oats.okf: v4.1.1
-  oats.aweb: v1.17.7
+  oats.aweb: v1.19.0
   oats.linear: v1.0.1
   oats.jira: v1.0.1
 defaults:

package/docs/oats-local.schema.json

@@ -126,28 +126,16 @@
           "uniqueItems": true,
           "items": { "type": "string", "pattern": "^(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*$" }
         },
-        "teams": {
-          "description": "Which teams each soul belongs to on this deployment (`oats soul teams` writes it): \"*\" applies to every soul; a soul's own entry (its bare name, or <package>/<soul> for a package soul) adds to it. Every soul is also in its default. Eligible, never auto-joined: an instance joins its default at spawn and the others on request.",
-          "type": "object",
-          "propertyNames": { "type": "string", "pattern": "^(?:\\*|(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*)$" },
-          "additionalProperties": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/label" } }
-        },
         "launch": {
           "description": "Launch preferences on this machine (0.30; feature launch-preference), overriding the soul's own launch: \"*\" applies to every soul; a soul's own entry (its bare name, or <package>/<soul>) wins over it. A value is a launch configuration's name (in launch-configs of this file) or an inline { harness, model? }. Explicit spawn flags win over both. A changed preference affects no existing home until --reselect-launch or a respawn.",
           "type": "object",
           "propertyNames": { "type": "string", "pattern": "^(?:\\*|(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*)$" },
           "additionalProperties": { "oneOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, { "$ref": "#/$defs/launchPreference" } ] }
-        },
-        "default": {
-          "description": "A per-soul override of defaultTeam (`oats soul teams <soul> --default <label>`); it must be one of that soul's teams here (E_TEAM_NOT_ELIGIBLE).",
-          "type": "object",
-          "propertyNames": { "type": "string", "pattern": "^(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*$" },
-          "additionalProperties": { "$ref": "#/$defs/label" }
         }
       }
     },
     "teams": {
-      "description": "LOCAL teams (`oats teams add` writes it): <label>: { team, description? }, the messaging provider's team id for a team only this deployment uses. Shared teams are committed in oats-workspace.yaml teams:; a label in both is team-label-collision (the shared one wins).",
+      "description": "LOCAL teams (`oats teams add` writes it): <label>: { team, description? }, the messaging provider's team id for a team only this deployment uses. Allowed only when oats-workspace.yaml says localTeams: true (or in the standalone view); otherwise E_WORKSPACE_SCHEMA reason local-teams-closed. Every soul may join every local team. Shared teams are committed in oats-workspace.yaml teams:; a label in both is team-label-collision (the shared one wins). souls.teams and souls.default were removed in 0.38.0: souls: in oats-workspace.yaml.",
       "type": "object",
       "propertyNames": { "$ref": "#/$defs/label" },
       "additionalProperties": {
@@ -162,7 +150,7 @@
     },
     "defaultTeam": {
       "$ref": "#/$defs/label",
-      "description": "The team every instance of this deployment lives in (its primary identity), unless souls.default overrides it for a soul: a label of teams here or in oats-workspace.yaml (`oats teams default` writes it; the first `oats teams add` sets it)."
+      "description": "This deployment's default team (`oats teams default` writes it; the first `oats teams add` sets it): a label of teams here or in oats-workspace.yaml. Allowed only when oats-workspace.yaml says localTeams: true (or in the standalone view). A soul's souls: default in the workspace wins over it; it wins over the workspace's defaultTeam."
     }
   },
   "$defs": {

package/docs/oats-workspace.schema.json

@@ -25,21 +25,21 @@
       "type": "object",
       "propertyNames": { "$ref": "#/$defs/label" },
       "additionalProperties": { "$ref": "#/$defs/team" },
-      "description": "SHARED teams: <label>: { description?, team? }. `team` is the messaging provider's team id, the same for everyone; without it the team is declared but not yet created (readiness team-unmapped). Local teams, the default and which teams each soul belongs to live in the deployment's oats-local.yaml (`oats teams`, `oats soul teams`). A label never gates, restricts or partitions anything."
+      "description": "SHARED teams: <label>: { description?, team? }. `team` is the messaging provider's team id, the same for everyone; without it the team is declared but not yet created (readiness team-unmapped). The default team and which teams each soul may join are defaultTeam and souls: below; a deployment's local teams live in its oats-local.yaml where localTeams allows them. A label never gates, restricts or partitions anything."
     },
     "defaultTeam": {
       "$ref": "#/$defs/label",
-      "description": "Team model 3 (0.37.0): the workspace's fallback default team, a label of teams: in this file. 0.36.x accepts and validates it without applying it."
+      "description": "The workspace's fallback default team, a label of teams: in this file: a soul's souls: default wins over it, and so does a deployment's local defaultTeam where localTeams: true."
     },
     "localTeams": {
       "type": "boolean",
-      "description": "Team model 3 (0.37.0): whether deployments may declare their own teams and defaultTeam in oats-local.yaml. Absent: false. 0.36.x accepts it without applying it."
+      "description": "Whether deployments may declare their own teams and defaultTeam in oats-local.yaml (every soul may join a local team). Absent: false; then local teams and a local defaultTeam are refused (E_WORKSPACE_SCHEMA reason local-teams-closed)."
     },
     "souls": {
       "type": "object",
       "propertyNames": { "type": "string", "pattern": "^(?:\\*|[a-z0-9][a-z0-9._-]*/(?:\\*|[a-z0-9]+(?:-[a-z0-9]+)*))$" },
       "additionalProperties": { "$ref": "#/$defs/soulTeams" },
-      "description": "Team model 3 (0.37.0): per soul pattern (\"*\", <member|package>/* or <member|package>/<soul>; the most specific key wins outright), the soul's default team and the other teams it may join. Every label is a label of teams: in this file. 0.36.x accepts and validates it without applying it."
+      "description": "Per soul pattern (\"*\", <member|package>/* or <member|package>/<soul>), the soul's default team and the other teams it may join. The most specific key gives the soul's teams outright (lists never merge); the most specific key that sets a default gives its default. A soul no key matches has its default only. Every label is a label of teams: in this file."
     },
     "defaults": { "$ref": "#/$defs/defaults" },
     "stores": {

package/docs/official-catalog.md

@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.4.2` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.framework` | `oats-framework/v1.5.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.1.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
-| `oats.aweb` | `v1.17.7` | `oats.aweb` (messaging) | |
+| `oats.aweb` | `v1.19.0` | `oats.aweb` (messaging) | |
 | `oats.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |

package/docs/packages.md

@@ -51,7 +51,7 @@ packages:
 - **Bare version** (`v4.1.1`, `4.1.1`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.1.1` or `oats-framework/v1.4.2`) and the payload path. An id
+  convention (`v4.1.1` or `oats-framework/v1.5.0`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.2
+  oats.framework: v1.5.0
   oats.okf: v4.1.1
-  oats.aweb: v1.17.7
+  oats.aweb: v1.19.0
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
 defaults:
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
 ## `oats package add | remove`
 
 ```bash
-oats package add oats.aweb v1.17.7                         # a catalog version
+oats package add oats.aweb v1.19.0                         # a catalog version
 oats package add acme.tools git:github.com/acme/tools@v0.4.0
 oats package remove acme.tools
 ```
@@ -247,8 +247,9 @@ oats-package/
   souls; otherwise `E_SOUL_AMBIGUOUS` names each qualified form
   (`details.qualified`). A member soul's qualified form is `<member name>/<soul>`.
 - **Resolved** like any soul: the workspace defaults apply, `off` and
-  `<slot>: none` work, its teams here are keyed `<package>/<soul>` in
-  `oats-local.yaml` `souls.teams`, and `from: here` means **this package** at the locked commit
+  `<slot>: none` work, its teams are keyed `<package>/<soul>` (or `<package>/*`)
+  in the workspace's `souls:` (unlisted, it joins its default only), and
+  `from: here` means **this package** at the locked commit
   (a capability it does not provide is `E_CAPABILITY_MISSING`).
 - **Spawned** at the locked commit: the soul is fetched into the per-commit
   soul cache and its digest must equal the lock's (`E_PACKAGE_INTEGRITY
@@ -332,11 +333,11 @@ A soul that names one of the package's capabilities with
   "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.1.1", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.2", "path": "oats-package" }
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.5.0", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.4.2`
-resolves to tag `oats-framework/v1.4.2`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.5.0`
+resolves to tag `oats-framework/v1.5.0`. Resolving through the catalog never
 advances a lock by itself: `oats sync` does, and says so.

package/docs/release-notes/v0.37.0.md

@@ -0,0 +1,111 @@
+# OATS 0.37.0
+
+## Added
+
+- **The Desktop opens one window per workspace** (awebai/oats#481). Each
+  workspace has at most one window, titled with its name (a workspace on a
+  server: `name — server`). Choosing a workspace in the switcher shows it in the
+  current window, or brings its own window to the front when it has one.
+  Each workspace in the switcher has an **Open in new window** button
+  (keyboard: Right Arrow then Enter, or ⌘Enter / Ctrl+Enter). On macOS,
+  **File → New Window** (⌘⇧N) opens a window with no workspace that asks you
+  to choose one, and ⌘\` cycles the windows; on Linux and Windows the command
+  palette has **Window: new window**, with no default chord. Quitting and
+  relaunching brings every window back with its size and place; a window
+  whose workspace isn't served at launch stays remembered until you close it
+  while it is served. Launching the app again with `--dir <deployment>`
+  brings that deployment's window to the front, adding the deployment if
+  needed. An unfocused window re-reads its instance list at the server's
+  blurred cadence (30 s). A window's requests always carry its own
+  workspace: one the server doesn't serve is refused with
+  `E_WORKSPACE_NOT_SERVED`, never answered with another workspace's data.
+  Window positions are kept in `windows.json` in the app's data folder.
+
+## Changed
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.38.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.37.0 together: the
+  Desktop 0.36.x refuses a 0.37 CLI.
+
+- **Team model 3 is OATS 0.38.0, not 0.37.0.** 0.37.0 keeps 0.36.1's
+  behaviour: the new `oats-workspace.yaml` keys are validated but not applied,
+  and the `team-model-3-migration` warning, which now names 0.38.0, says what
+  0.38.0 will refuse. The migration steps in the 0.36.1 notes apply unchanged.
+
+- **oats.framework 1.4.3** (oats.setup 2.2.2, catalog and workspace pin
+  `oats-framework/v1.4.3`): the `oats-teams` and
+  `oats-workspace-config` skills say team model 3 is 0.38.0, and that 0.36.x
+  and 0.37.x keep applying the local team keys. Remove them only when the
+  deployment moves to 0.38.0.
+
+- **oats.aweb 1.18.1** (catalog and workspace pin, and the bundled mirror):
+  how mail reaches a session now depends on the runtime. Under the default
+  `delivery: channel`, Claude Code takes mail and chat through its
+  `aweb-channel` plugin and pi through the `@awebai/pi` extension, and
+  neither goes through the host wake broker. Codex keeps the wake broker. A
+  Codex home under `channel` is now registered with it at every start, where
+  before it got no wake at all. Every start of a home re-decides the path for
+  that start's runtime and leaves the home on exactly one path. A start that
+  cannot register or deregister the home is refused. Existing instances keep
+  the delivery they were spawned with until they are respawned.
+  `delivery: session` still sends every runtime through the broker.
+
+  oats.aweb 1.18.1 declares `launchPreview` (see Fixed below). A launch
+  preview, including Desktop's start dialog, and a start refused by
+  preflight change no broker registration: the hook calls `aw` only in the
+  real run, after preflight has passed.
+
+## Fixed
+
+- **Launch hooks no longer have side effects under a preview, or before a
+  start's preflight has passed** (awebai/oats#500). A launch hook may register
+  a home with its provider; oats.aweb's registers it with the host wake
+  broker. But `oats launch-config preview`, which Desktop's start dialog
+  calls for running homes, ran every hook for real. A start refused by
+  preflight, including a start of a home that was already running, had also
+  run them. Previewing a running Claude home with another harness could
+  therefore change how that live session is woken.
+
+  A capability now declares that its launch hook is preview-aware, with
+  `"launchPreview": true` at the top level of its manifest. The kernel reads
+  the declaration from the home's own module copy. A preview-aware hook
+  runs twice per start:
+  - **As a preview,** with `OATS_LAUNCH_PREVIEW=1` in the hook environment
+    (a new, additive hook environment variable). This run's contribution
+    drives the preflight and the rendered command.
+  - **For real, without the flag,** only once every check has passed, and
+    before a restart stops the running harness.
+
+  A preview runs only the first pass. A preview-aware hook must change
+  nothing under the flag. It must also return the same contribution either
+  way, apart from the values of the env names its preview answer lists in
+  `volatileEnv` (below). If the real run's contribution differs otherwise,
+  the start is refused with `E_LAUNCH_PREPARATION` and nothing is stopped or
+  started.
+
+  A hook that doesn't declare `launchPreview` runs as it did in 0.36: once
+  per start, for real, during preflight. `oats launch-config preview` never
+  runs it; the preview shows its recorded contribution and says so. The
+  kernel never passes on an `OATS_LAUNCH_PREVIEW` inherited from the
+  environment.
+
+  **Provider authors:** declare `launchPreview` once your launch hook
+  honours `OATS_LAUNCH_PREVIEW`, and expect it to run twice per start
+  (docs/capabilities.md). oats.aweb 1.18.1 does. A kernel before 0.37
+  ignores the key and runs the hook once, as before.
+- **Existing homes whose launch hook renews a credential at every start
+  start again** (awebai/oats#504). The first version of the two-pass rule
+  above ran every launch hook twice. A hook from before the preview flag
+  then really ran under the preview too, and a hook that answers new values
+  at every call failed the comparison. That covers oats.aweb homes with
+  `identity.mode: global` and `renew: launch`, which mint a grant at each
+  start: their starts were refused with `E_LAUNCH_PREPARATION`. Two passes
+  are now opt-in, through `launchPreview`.
+
+  A preview-aware hook can also name, in its preview answer, env whose
+  values only the real run can know, such as `"volatileEnv":
+  ["AWEB_IDENTITY_HOME"]`. The start takes those values from the real run
+  and leaves them out of the comparison. Each must be a name the same hook
+  returned. A harness configuration selector (`CLAUDE_CONFIG_DIR`,
+  `CODEX_HOME`, `PI_CODING_AGENT_DIR`) is refused as volatile, because the
+  package probe reads it before the real run.

package/docs/release-notes/v0.38.0.md

@@ -0,0 +1,128 @@
+# OATS 0.38.0
+
+## Changed (breaking)
+
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.39.0`**, so it runs against
+  this release's kernel. Install the CLI and the Desktop 0.38.0 together: the
+  Desktop 0.37.x refuses a 0.38 CLI.
+
+- **Team model 3: the teams a soul may join, and its default, are committed
+  in the workspace** (awebai/oats#484; feature `team-model-3` replaces
+  `team-model-2`). An instance in two teams is a bridge between them, so which
+  teams an organisation's instances may be in is now its decision, committed
+  in `oats-workspace.yaml` and closed by default. This prevents accidental
+  joins and makes the intended team set reviewable in git; it does not stop a
+  deliberate relay by someone holding credentials for two teams (see
+  docs/design/2026-10-02-team-model-3.md).
+  - `oats-workspace.yaml` `defaultTeam`, `localTeams` and `souls:` (accepted
+    since 0.36.1) now apply. `souls:` keys are `"*"`, `<member|package>/*` and
+    `<member|package>/<soul>`; the most specific key gives a soul's teams
+    outright (lists never merge), and the most specific key that sets one
+    gives its default: `a/*: {default: security}` and `a/x: {teams: [docs]}`
+    give `a/x` the default `security` and the teams `[docs]` only. `teams:
+    any` is every shared team. A soul no key matches has its default only,
+    package souls included.
+  - A soul's default team is its `souls:` default; else the deployment's
+    `oats-local.yaml` `defaultTeam`, only when the workspace says
+    `localTeams: true`; else the workspace's `defaultTeam`; else none.
+    `defaultTeam.from` and `OATS_DEFAULT_TEAM_FROM` are `soul`, `deployment`
+    or `workspace`; `soul` now means the workspace's `souls:` default (it was
+    the local `souls.default`).
+  - A soul may join its default, its `souls:` teams and, with
+    `localTeams: true`, every local team. Every team row carries `via`
+    (`default`, `workspace`, `local`), in reports, `OATS_TEAMS` and
+    `instance.json`.
+  - `oats-local.yaml` `souls.teams` and `souls.default` are refused
+    (`E_WORKSPACE_SCHEMA`, reason `removed-key`). The refusal names each key
+    and prints the `souls:` to commit instead (`details.replacement`); `oats
+    doctor` answers with it.
+  - `oats-local.yaml` `teams` and `defaultTeam` are refused unless the
+    workspace says `localTeams: true` (`E_WORKSPACE_SCHEMA`, reason
+    `local-teams-closed`, naming both fixes). Spawn, preview and inspect
+    refuse; `oats teams`, readiness and `oats doctor` (offline, from the cached
+    workspace file) report it as a failure. The standalone view allows them.
+  - `oats teams add` and `oats teams default` are refused where local teams
+    are closed; `oats teams remove` still works there. `oats soul teams` is
+    read only: `--add`, `--remove`, `--default` and `--clear-default` are
+    `E_BAD_ARGS`, naming `souls:` in `oats-workspace.yaml`.
+  - `oats teams --json` is `teamsApi: 2` (`localTeams`, a `DefaultTeam`, the
+    workspace's `souls:`) and now discovers the workspace's souls; `oats soul
+    teams --json` is `soulTeamsApi: 2` (`key` is the qualified soul key,
+    `match` and `defaultMatch` name the `souls:` keys that applied).
+  - New readiness items: local-teams-closed (failure) and `team-soul-unknown`
+    (a warning for a `souls:` key that names no soul of the workspace).
+    `team-model-3-migration` is retired, and the kernel no longer reports
+    `E_TEAM_NOT_ELIGIBLE` (a soul's default is always eligible).
+  - Shapes: docs/desktop-cli-api.md, under Teams.
+- **The Desktop follows team model 3.** With a 0.38 CLI (feature `team-model-3`) the Workspace ›
+  Teams page shows the workspace's `souls:` read only, and offers Add and Make default for local teams
+  only where the workspace says `localTeams: true`; where it doesn't, a local team still in
+  `oats-local.yaml` keeps Remove under the kernel's local-teams-closed message. A soul's *Teams here* is
+  read only: it says where the soul's default and teams come from and that they change as `souls:` in
+  `oats-workspace.yaml` (a PR to the workspace file). The Desktop never sends the removed `oats soul
+  teams` edit flags, and a 0.37 or older CLI keeps the team model v2 views.
+- **oats.aweb 1.19.0** (catalog and workspace pin, and the bundled mirror),
+  for team model 3. A default team that comes from the workspace's
+  `defaultTeam` is reported as `from: "workspace"` in `oats aweb teams --json`
+  and the recorded meta (1.18 reported it as `deployment`). `oats aweb setup
+  --create` asks the kernel whether the workspace allows local teams before it
+  creates anything; where it does not, it creates the team and its per-team
+  root, records no local team, and prints the `teams:` entry (and
+  `defaultTeam:`) to commit in `oats-workspace.yaml`, or the `localTeams: true`
+  alternative. `--username` and setup's other advice say the same where local
+  teams are closed, and an unmapped default's remedy names `defaultTeam:` in
+  the workspace file. Joining stays limited to the eligible `OATS_TEAMS` rows.
+
+- **oats.framework 1.5.0** (oats.core 2.3.0, oats.setup 2.3.0; catalog and
+  workspace pin `oats-framework/v1.5.0`): the skills
+  describe team model 3. `oats-teams`, `oats-workspace-config`,
+  `oats-setup-model`, `oats-onboarding` and the setup inject say a soul's teams
+  and default are committed in `souls:` of `oats-workspace.yaml`, local teams
+  only with `localTeams: true`; `oats-operate` and `oats-souls` say where an
+  instance's teams come from.
+
+## Upgrade
+
+Before upgrading a deployment, its workspace must say what its
+`oats-local.yaml` said. 0.36.1 and 0.37.x already accept the workspace keys,
+and their `team-model-3-migration` warnings list what each deployment has to
+move.
+
+1. **In the workspace file** (a PR, once everyone who reads it runs 0.36.1 or
+   later):
+   - commit `souls:` entries for what the deployments' `souls.teams` and
+     `souls.default` said. A v2 soul's teams were its default, `"*"`'s teams
+     and its own, and patterns never merge, so a soul's own entry lists
+     `"*"`'s teams too. Qualify bare soul names with their member's name
+     (`<member>/<soul>`, as `souls.disabled` names it). Running 0.38.0 against
+     an unmigrated `oats-local.yaml` prints this snippet for you;
+   - commit `defaultTeam: <label>` when the deployments' default is a shared
+     team;
+   - for local (personal) teams and a local default, choose: (a) keep them
+     personal, with `localTeams: true`; or (b) commit them in `teams:` (and the
+     default as `defaultTeam:`).
+2. **In each `oats-local.yaml`**, when the deployment moves to 0.38.0: remove
+   `souls.teams` and `souls.default`, and, under (b), the local `teams` and
+   `defaultTeam` (`oats teams remove` works while local teams are closed).
+3. **Check:** `oats teams` lists no problems, and `oats spawn <soul>
+   --preview` shows each soul's `defaultTeam` and `teams` as intended. Running
+   instances keep their spawn-time default; readiness reports
+   `default-team-changed` where it moved, and a respawn follows it.
+
+What each kind of deployment changes:
+
+- **A workspace whose people keep personal teams or a personal default** (for
+  example awebai/oats): `localTeams: true`, plus `souls:` for the souls'
+  shared teams (e.g. `"*": { teams: [oats] }`); drop `souls.teams` locally.
+- **A workspace whose default team is a committed shared team**: commit
+  `defaultTeam: <label>` and the `souls:` entries; drop the local
+  `defaultTeam` (and any `souls.*` team keys).
+- **A standalone deployment**: nothing changes for local teams and the local
+  default; drop `souls.teams` and `souls.default` (a standalone view has no
+  `souls:` patterns: every soul may join every local team).
+
+Consumers: the Desktop's team views read `teamsApi: 1` / `soulTeamsApi: 1` and
+edit through `oats soul teams --add`; they follow in their own change. Another
+messaging provider receives `OATS_DEFAULT_TEAM_FROM=workspace` and `via` on
+the `OATS_TEAMS` rows; one that records local teams with `oats teams add` needs
+the workspace to allow them (oats.aweb 1.19.0 does both, above).

package/docs/souls-and-instances.md

@@ -164,8 +164,8 @@ composed skills and instructions, a spawn records:
     "key": "github.com/acme/agents", "commit": "3f2a9c1e…", "resolution": "20ec8ec527311d71d0973086",
     "soul": { "repoKey": "github.com/acme/agents", "commit": "3f2a9c1e…" }
   },
-  "teams": [{ "label": "ana-acme", "team": "ana-acme:ana.aweb.ai", "default": true, "from": "local" },
-            { "label": "engineering", "team": "engineering:acme.aweb.ai", "default": false, "from": "shared" }],
+  "teams": [{ "label": "ana-acme", "team": "ana-acme:ana.aweb.ai", "default": true, "from": "local", "via": ["default", "local"] },
+            { "label": "engineering", "team": "engineering:acme.aweb.ai", "default": false, "from": "shared", "via": ["workspace"] }],
   "defaultTeam": { "label": "ana-acme", "team": "ana-acme:ana.aweb.ai", "from": "deployment" }
 }
 ```
@@ -183,7 +183,8 @@ composed skills and instructions, a spawn records:
   compares `workspace.soul` with the member's current commit too: `soul: <name>
   from <member> @ <c7>  [member moved since …]` (`--json`: `instances[].soul`).
 - `teams` / `defaultTeam`: the soul's teams at spawn, exactly as the providers
-  received them (mapped teams only) and its default: evidence, never rewritten.
+  received them (mapped teams only, each with `via`: why the soul may join it)
+  and its default: evidence, never rewritten.
   A running home's hooks and messaging commands read the teams live
   ([capabilities.md](capabilities.md#teams-in-the-provider-environment)).