@awebai/oats 0.37.0 → 0.38.1

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.38.0): the workspace's fallback default team, a label of teams: in this file. 0.36.x and 0.37.x accept and validate 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.38.0): whether deployments may declare their own teams and defaultTeam in oats-local.yaml. Absent: false. 0.36.x and 0.37.x accept 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.38.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 and 0.37.x accept and validate 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.3` (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.18.1` | `oats.aweb` (messaging) | |
+| `oats.aweb` | `v1.20.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.3`) 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.3
+  oats.framework: v1.5.0
   oats.okf: v4.1.1
-  oats.aweb: v1.18.1
+  oats.aweb: v1.20.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.18.1                         # a catalog version
+oats package add oats.aweb v1.20.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.3", "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.3`
-resolves to tag `oats-framework/v1.4.3`. 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.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/release-notes/v0.38.1.md

@@ -0,0 +1,50 @@
+# OATS 0.38.1
+
+## Changed
+
+- **oats.aweb 1.20.0: `oats aweb roster` lists who is on the team and says
+  what each entry is** (awebai/oats-aweb#46). The roster printed only the
+  team's membership certificates (`aw id team members`). That listing omits
+  identities the registry does not list, such as a team's retained global
+  coordinator and dashboard humans. It also listed deployment roots and
+  certificates with no workspace exactly like agents. The roster is now the
+  union of those certificates and the team's workspace presence
+  (`aw workspace status`), read from the minting root. Each entry has its
+  sources (`certificate`, `presence` or both), its status (active, when last
+  seen, or `certificate only: no workspace record`) and a kind:
+  - `global identity`, from the identity scope, listed first;
+  - `human` and `hosted agent`, from the session context;
+  - `instance` and `deployment root`, from the workspace path;
+  - `unknown`.
+  An inferred kind says so, and nothing is called retired. aw does not mark a
+  team's coordinator, and the roster says so. When a source cannot be read,
+  or presence is past its 200-workspace cap, the roster still lists what it
+  has and says it is incomplete. `oats aweb roster --json` is now an oats.aweb
+  document (`{team, members, certificatesComplete, presenceComplete,
+  problems}`) instead of aw's raw listing. The oats-aweb skill, the inject
+  and the spawn brief say what the roster shows and what it can't tell you.
+
+## Fixed
+
+- **The Desktop opened from Finder no longer shows `/` as its workspace**
+  (awebai/oats#518). A Finder launch starts in `/`, and when no saved
+  workspace was a deployment, the Desktop served `/`. It titled the window
+  `/`, showed `E_NO_DEPLOYMENT` in Instances, and remembered `/` in
+  `windows.json` for every later launch. A folder that is not a deployment is
+  now never served, bound to a window or saved. With no deployment to open,
+  the window opens on the workspace switcher, which lists the deployments
+  directly inside `~/Agents` under "On this computer": one click opens one in
+  that window. A window remembered on `/` is forgotten at launch.
+
+- **A window with no workspace lists the workspaces served after it opened**
+  (awebai/oats#521). Its choices were fixed when it opened, so remote
+  workspaces arriving a few seconds after launch never appeared and the
+  switcher said "No workspace choices reported."
+
+- **Copying an agent's output in the Desktop** (awebai/oats#520). A plain
+  drag over a terminal now selects the text (tmux's copy mode, so it can
+  reach into the scrollback) and copies it to the clipboard on release;
+  ⌘C, Edit › Copy and the right-click menu find it there. The Desktop takes
+  tmux's copies (OSC 52) write-only: nothing in a terminal can read the
+  clipboard. Remote terminals (`oats session attach --server`) bind the same
+  drag. ⌘V is unchanged; Option-drag still makes a terminal-only selection.

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)).
 

package/docs/workspaces.md

@@ -35,7 +35,7 @@ workspace commit. Schemas: [`oats-workspace.schema.json`](oats-workspace.schema.
 [`oats-membership.schema.json`](oats-membership.schema.json),
 [`soul.schema.json`](soul.schema.json), [`oats-local.schema.json`](oats-local.schema.json);
 the lock's format is in [packages](packages.md#lock-v3). The JSON schemas encode
-shapes; domain rules (declared teams, duplicate members, canonical `from:` keys,
+shapes; domain rules (labels that are shared teams, duplicate members, canonical `from:` keys,
 the two `packages:` value forms) live in the kernel's `validateWorkspace` /
 `validateSoul`, which are the authority.
 
@@ -54,13 +54,16 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.4.3                   # bare version → resolves through the official catalog
+  oats.framework: v1.5.0                   # bare version → resolves through the official catalog
   oats.okf: v4.1.1
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # SHARED teams: the same provider team for everyone
   engineering: { description: Platform and release automation, team: "engineering:acme.aweb.ai" }
   reviewers:   { description: Code review }   # declared, not created yet (no `team` id): readiness team-unmapped
+defaultTeam: engineering                   # the workspace's default team; see Teams below
+souls:                                     # which teams each soul may join besides its default
+  platform/*: { teams: [reviewers] }
 
 defaults:
   capabilities:
@@ -146,7 +149,8 @@ its content digest.
 ### `oats-local.yaml`: the only per-machine file
 
 Which workspace this machine realizes, where member clones live, host-owned
-provider settings, this deployment's local teams and team membership, host
+provider settings, this deployment's local teams and default (where the
+workspace allows them), host
 facts for automations, and launch configurations. The full reference is
 [configuration.md](configuration.md).
 
@@ -308,89 +312,130 @@ Harnesses start normally, with their own skill discovery intact
 
 ## Teams
 
-A team is a messaging-provider team (for oats.aweb, an
-aweb team id `<team>:<namespace>`) under a **label**. Two files declare them:
-
-- **Shared teams**: the committed `oats-workspace.yaml` `teams.<label> =
-  { description?, team? }`: the same provider team for everyone, edited by a PR.
-  A shared team without `team` is declared but not created yet (readiness
-  `team-unmapped`): its owner creates it with the messaging provider, then
-  commits the id.
-- **Local teams**: the deployment's `oats-local.yaml` `teams.<label> = { team,
-  description? }`: a team only this deployment uses (a personal team). A label in
-  both files is `team-label-collision` (a warning); the **shared** definition
-  wins, and the fix is renaming the local label.
-
-`oats-local.yaml` also says which teams each soul belongs to **here**:
-
-- `defaultTeam: <label>`: the team every instance of this deployment lives in
-  (its default-team identity);
-- `souls.teams`: `"*"` for every soul, and a soul's own entry (its bare name, or
-  `<package>/<soul>` for a package soul) adds to it;
-- `souls.default`: a per-soul override of `defaultTeam`; it must be one of that
-  soul's teams (`E_TEAM_NOT_ELIGIBLE`).
-
-A soul's default is `souls.default[soul] ?? defaultTeam`; its teams are that
-default ∪ `souls.teams["*"]` ∪ `souls.teams[soul]`. A label no file declares is
-`E_TEAM_UNKNOWN` (a spawn, preview or `inspect --soul` of that soul is
-refused). At spawn an instance joins its **default** only; the others are
+A team is a messaging-provider team (for oats.aweb, an aweb team id
+`<team>:<namespace>`) under a **label**. An instance that sits in two teams is
+a bridge between them: one process reads both inboxes and could relay anything
+from one to the other. So which teams an organisation's instances may be in is
+the organisation's decision, committed in its workspace file and closed by
+default; a deployment's `oats-local.yaml` adds a team only where the workspace
+allows it. Souls stay team-free in their own repositories: an organisation
+says how souls behave in its teams in its `oats-workspace.yaml`, and someone
+running the same souls standalone sees none of it.
+
+**What this protects against, and what it does not.** The workspace's team
+rules prevent **accidental** joins in a cooperative installation, and they make
+the organisation's intended team set visible and reviewable in its git. That is
+all they claim. They do not stop an operator from bridging teams on purpose:
+whoever holds credentials for two teams can read under one identity and relay
+under the other, or copy content outside the messaging layer, and distinct keys
+do not prove distinct processes. The messaging provider's admission (for aweb,
+the team controller key signs memberships; hosted invites are mediated by the
+service) controls who holds credentials for a team, not what a process does
+with what it reads. A deployment's authority comes from the credentials it
+holds, not from its path or its name, and a team certificate carries no soul,
+workspace or home-team claim (such metadata would be self-asserted, not a
+control).
+
+### Where teams are declared
+
+```yaml
+# oats-workspace.yaml (committed, edited by PR)
+teams:                                   # SHARED teams: the same provider team for everyone
+  engineering: { team: "engineering:acme.aweb.ai" }
+  security:    { team: "security:acme.aweb.ai" }
+  docs:        { description: Docs rota }       # declared, not created yet: team-unmapped
+defaultTeam: engineering                 # the workspace's fallback default team (a shared label)
+localTeams: false                        # may deployments declare their own teams? (absent: false)
+souls:                                   # per soul pattern: its default team and the other teams it may join
+  "*": { teams: [] }                     # unlisted souls: default only (also what no entry means)
+  security-souls/*: { default: security, teams: [engineering] }
+  security-souls/incident-responder: { default: security, teams: [engineering, docs] }
+  oats.engineering/*: { teams: any }     # any: every shared team of this file
+```
+
+- **Shared teams** (`teams.<label> = { description?, team? }`): a shared team
+  without `team` is declared but not created yet (readiness `team-unmapped`):
+  its owner creates it with the messaging provider, then commits the id.
+- **`souls:` keys are patterns**: `<member>/<soul>` or `<package>/<soul>`,
+  `<member>/*` or `<package>/*`, and `"*"`, with the member and package names
+  `souls.disabled` uses (a member's name is its repository's). A bare soul name
+  is refused. A key that is neither a pattern nor a soul the workspace offers
+  is the warning `team-soul-unknown` (a typo guard).
+- **The most specific key wins outright** for a soul's teams, and lists never
+  merge: the soul's own key, then `<member|package>/*`, then `"*"`. The
+  default comes from the most specific key that sets one. So
+  `a/*: {default: security}` and `a/x: {teams: [docs]}` give `a/x` the default
+  `security` and the teams `[docs]` only.
+- **A soul no key matches** (and no `"*"`) has its default only. That applies
+  to member and package souls alike: a workspace opens a package explicitly.
+- **Every label** (`defaultTeam`, each `default`, each of `teams`) must be a
+  shared team of the same file; anything else is `E_WORKSPACE_SCHEMA` when the
+  file is read, never at a spawn on someone else's machine.
+- **Local teams** (`oats-local.yaml` `teams.<label> = { team, description? }`)
+  and a local `defaultTeam` are allowed only when the workspace says
+  `localTeams: true`. Otherwise every spawn, preview and inspect is refused with
+  `E_WORKSPACE_SCHEMA` (reason `local-teams-closed`), naming both fixes: add
+  `localTeams: true` to the workspace file, or commit the teams and the
+  default there and remove them locally. A label in both files is
+  `team-label-collision` (a warning): the **shared** definition wins, and the
+  fix is renaming the local label.
+- **The standalone view** (an explicit `standalone:`, or a fallback when the
+  workspace cannot be read) has no workspace rules: local teams and the local
+  `defaultTeam` apply there.
+- `soul.yaml` and `oats-membership.yaml` say nothing about teams.
+  `oats-local.yaml` `souls.teams` and `souls.default` were removed in 0.38.0:
+  they are refused, and the refusal prints the `souls:` to commit instead.
+
+### A soul's default team and its teams
+
+The default, in order:
+
+1. the soul's `default` from `souls:` (the most specific matching key that
+   sets one);
+2. else the deployment's `oats-local.yaml` `defaultTeam`, only when
+   `localTeams: true`;
+3. else the workspace's `defaultTeam`;
+4. else none (`E_TEAM_UNCONFIGURED` when a messaging layer is active).
+
+`defaultTeam.from` says which: `soul`, `deployment` or `workspace`.
+
+The teams a soul may join: its default, plus the `teams` of its most specific
+matching `souls:` key, plus, with `localTeams: true`, every local team the
+deployment declares. Each row says why (`via`: `default`, `workspace`,
+`local`). At spawn an instance joins its **default** only; the others are
 eligible: offered, and joined on request through the provider (`join=` at
-spawn, or its own verbs later). Nothing committed besides the shared `teams:`
-says anything about teams, and capabilities compose from the workspace defaults
-and the soul only, the same for everyone. **A label never gates, restricts,
-changes trust or partitions the knowledge store.**
+spawn, or its own verbs later), which refuses a team that is not eligible.
+A local default no file declares is `E_TEAM_UNKNOWN`. Capabilities compose
+from the workspace defaults and the soul only, the same for everyone. **A
+label never gates, restricts, changes trust or partitions the knowledge
+store.**
+
+### The verbs
 
-The verbs edit `oats-local.yaml` in place; they never call a provider:
+They never call a provider. `oats teams add` and `oats teams default` edit
+`oats-local.yaml` in place, where the workspace allows local teams; `oats teams
+remove` runs anywhere (removing local teams is how a deployment moves them into
+the workspace). A soul's teams are edited by a PR to `oats-workspace.yaml`:
+`oats soul teams` only reads them.
 
 ```
-oats teams [--json]                                  # this deployment's teams, ids, the default, problems
-oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the default)
-oats teams remove <label>                            # refused while referenced (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
-oats teams default <label>
-oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default] [--json]
+oats teams [--json]                                  # the teams, ids, the default, localTeams, the workspace's souls:, problems
+oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the local default)
+oats teams remove <label>                            # refused while it is the local default (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
+oats teams default <label>                           # the local default
+oats soul teams <soul>|'*' [--json]                  # a soul's default and teams here, and which souls: key gave them
 ```
 
-The messaging provider's own setup creates provider teams and records them with
-`oats teams add` (see the provider's documentation). The spawn preview, `inspect` and `oats souls` report a soul's
+The messaging provider's own setup creates provider teams (see the provider's
+documentation). The spawn preview, `inspect` and `oats souls` report a soul's
 `teams` and `defaultTeam`; readiness reports the team problems in
 `checks.configured` (`E_TEAM_UNCONFIGURED` when a messaging layer is active and
 there is no default; `team-unmapped`, blocking when it is the default;
-`default-team-changed` for a running instance). The provider receives them in
-its environment — see [capabilities.md](capabilities.md#teams-in-the-provider-environment).
-Exact shapes: [desktop-cli-api.md](desktop-cli-api.md#team-model-v2-feature-team-model-2-oats-0300-replaces-feature-teams).
-
-### Preparing for team model 3 (0.36.x)
-
-OATS 0.38.0 commits a soul's teams in the workspace (team model 3,
-awebai/oats#484): the teams an organisation's instances may join become its
-own decision, visible and reviewable in its git, so a deployment's
-`oats-local.yaml` no longer adds one by accident. 0.36.x and 0.37.x prepare for it, so
-every workspace and deployment can migrate first:
-
-- **`oats-workspace.yaml` accepts the new keys** and validates them, but
-  **does not apply them**: a soul's teams and default are still resolved as
-  above, from `oats-local.yaml`.
-
-  ```yaml
-  defaultTeam: engineering          # the workspace's fallback default team
-  localTeams: true                  # deployments may declare their own teams (absent: false)
-  souls:                            # per pattern: "*", <member|package>/*, <member|package>/<soul>
-    "*": { teams: [] }              # default only ({} says the same)
-    security-souls/*: { default: security, teams: [engineering] }
-    oats.engineering/*: { teams: any }   # every shared team
-  ```
-
-  `<member|package>` is the name `souls.disabled` uses. Every label (`defaultTeam`,
-  a `souls:` `default`, each of its `teams`) must be a shared team in `teams:` of
-  the same file; anything else is `E_WORKSPACE_SCHEMA` when the file is read. A
-  key naming a member or package the workspace does not have is not an error.
-- **The readiness warning `team-model-3-migration`** (never blocking) names
-  what 0.38.0 will refuse: `souls.teams` / `souls.default` in `oats-local.yaml`
-  (they move to `souls:`), and local `teams` / `defaultTeam` while the workspace
-  does not say `localTeams: true` (fix: add `localTeams: true`, or commit the
-  teams and `defaultTeam` in the workspace file). `oats teams`, readiness (and
-  so the Desktop) and `oats doctor` show it. The migration steps are in the
-  [0.36.1 release notes](release-notes/v0.36.1.md).
+local-teams-closed; `team-soul-unknown`; `default-team-changed` for a running
+instance). The provider receives them in its environment — see
+[capabilities.md](capabilities.md#teams-in-the-provider-environment). Exact
+shapes: [desktop-cli-api.md](desktop-cli-api.md#team-model-3-feature-team-model-3-oats-0370-replaces-feature-team-model-2).
+Why it is shaped this way: [team model 3](design/2026-10-02-team-model-3.md).
 
 ## Provider payloads have three homes