@awebai/oats 0.36.1 → 0.38.0

package/docs/design/2026-10-02-team-model-3.md

@@ -0,0 +1,146 @@
+# Team model 3: the teams a soul may join, and its default, are committed in the workspace
+
+**Status:** decided and implemented (kernel 0.38.0, feature `team-model-3`; prepared in 0.36.1).
+Specs: awebai/oats#484 and #485, agreed by both maintainers on 2026-10-02. This record supersedes the
+membership and default-team parts of [team model v2](2026-09-27-team-model-v2.md); v2's shared teams,
+unmapped ids, live teams and provider environment stand. The reference pages
+([workspaces.md](../workspaces.md#teams), [capabilities.md](../capabilities.md#teams-in-the-provider-environment),
+[desktop-cli-api.md](../desktop-cli-api.md#team-model-3-feature-team-model-3-oats-0370-replaces-feature-team-model-2))
+win on operator-visible behaviour.
+
+## Why
+
+**The local bridge.** An instance that sits in two teams is a bridge between them: one process reads
+both inboxes, holds both contexts in one session, and can relay anything from one to the other. Under
+team model v2, one person's `oats-local.yaml` could put an organisation's instance into a team the
+organisation never sees: a local extra team in `souls.teams`, or a local default team while its souls
+joined the organisation's shared teams. Either way it never showed in the organisation's git, and it
+differed per person and per machine. The organisation owns its teams' trust boundary, so the teams its
+instances can be in are its decision, committed in its workspace, and closed by default.
+
+**Scale.** With many souls and teams, per-deployment lists were repeated by every person on every
+machine.
+
+**Principle**, consistent with v2's "shared facts committed, personal choices local": everything
+workspace-specific lives in the workspace file; souls stay team-free in their repositories, open source
+included; an organisation says how souls behave in its teams in its own `oats-workspace.yaml`, and
+someone running the souls standalone sees none of it.
+
+## What it protects against, and what it does not
+
+The workspace's eligibility rules (`souls:`, `localTeams` closed by default) **prevent accidental joins**
+in a cooperative installation, and make the organisation's intended team set visible and reviewable in
+its git. That is all they claim.
+
+They are not anti-bridging enforcement, and neither is the messaging layer. Distinct keys do not prove
+distinct processes: an operator controlling two identities can read under one and relay under the
+other, or copy content outside the messaging layer. aweb admission controls who holds credentials for
+a team (the team controller key signs memberships; hosted invites are mediated by the service), 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. Today's team certificates carry no soul, workspace or home-team claim,
+and any such metadata would be self-asserted, so it would not be prevention. Enforcement on the
+messaging side (admission per root, claims in certificates, a namespace policy, bridge visibility for a
+team's owner) is a separate question for the aweb protocol owners.
+
+## The model
+
+### `oats-workspace.yaml`
+
+```yaml
+teams:                                   # shared teams, as in v2
+  engineering: { team: "engineering:acme.aweb.ai" }
+  security:    { team: "security:acme.aweb.ai" }
+  docs:        { team: "docs:acme.aweb.ai" }
+defaultTeam: engineering                 # the workspace's fallback default team (a shared label)
+localTeams: false                        # may deployments declare their own teams? (absent: false)
+souls:                                   # per pattern: the default team and the other teams a soul may join
+  "*": { teams: [] }
+  security-souls/*: { default: security, teams: [engineering] }
+  security-souls/incident-responder: { default: security, teams: [engineering, docs] }
+  oats.engineering/*: { teams: any }
+```
+
+- **Keys are patterns:** `<member>/<soul>` or `<package>/<soul>`, `<member>/*` or `<package>/*`, and
+  `"*"`, with the names `souls.disabled` already uses. A soul's key is its qualified name. Bare names are
+  refused: a bare name is ambiguous across members, and the qualified form is what the workspace sees.
+- **The most specific key wins outright for teams,** with no merging across levels; the default comes
+  from the most specific key that sets one. `a/*: {default: security}` and `a/x: {teams: [docs]}` give
+  `a/x` the default `security` and the teams `[docs]` only. Merging was rejected: an entry that adds to
+  a broader one hides what a soul can join behind two places, and the point of the model is that a
+  reviewer reads one entry.
+- **`any`** is every shared team of the file.
+- **A soul no key matches** (and no `"*"`) has its default only, member and package souls alike; a
+  workspace opens a package explicitly.
+- **Every label is a shared team of the same file.** An unknown label, or a default that isn't one, is
+  `E_WORKSPACE_SCHEMA` when the file is read, never at a spawn on someone else's machine. A key that is
+  neither a pattern nor a discovered soul's qualified name is the warning `team-soul-unknown` (a typo
+  guard; not an error, because the file is validated without discovery and packages come and go).
+
+### The default team, in order
+
+1. the soul's `default` from `souls:` (`from: "soul"`);
+2. else the deployment's `oats-local.yaml` `defaultTeam`, only when `localTeams: true`
+   (`from: "deployment"`);
+3. else the workspace's `defaultTeam` (`from: "workspace"`);
+4. else none (`E_TEAM_UNCONFIGURED` when a messaging layer is active).
+
+The soul's own default comes first because it is the organisation's most specific statement; a
+personal default, where allowed, comes before the workspace's fallback so a person can keep their own
+default team (awebai/oats sets `localTeams: true` for this).
+
+### The teams a soul may join
+
+Its default, plus the `teams` of its most specific matching key, plus, with `localTeams: true`, every
+local team the deployment declares (there is no per-soul local list: a deployment that is trusted with
+local teams is trusted with them for every soul). Each row says why: `via` ⊂ `default`, `workspace`,
+`local`. Unchanged from v2: an instance joins only its default at spawn; the others are offered and
+joined on request, and the messaging provider decides admission from the eligible rows it receives in
+`OATS_TEAMS`.
+
+### `oats-local.yaml`
+
+- `souls.teams` and `souls.default` are removed keys. The refusal names each key found and prints the
+  `souls:` that gives the same result (a v2 soul's teams were its default ∪ `"*"` ∪ its own list, so each
+  named soul's entry lists `"*"`'s teams too; a bare soul name is written `<member>/<soul>` for the
+  operator to qualify), so a deployment's migration is a copy, a qualification and a PR.
+- `teams` and `defaultTeam` are allowed only when the workspace says `localTeams: true`. Otherwise every
+  spawn, preview and inspect refuses with `E_WORKSPACE_SCHEMA` (reason `local-teams-closed`), and `oats
+  teams`, readiness and doctor report it as a failure. The message names both fixes: allow local teams,
+  or commit them in the workspace and remove them locally. The rule can only be checked where the
+  workspace file has been read, so it is not part of `oats-local.yaml`'s own validation.
+- The standalone view (explicit, or a fallback when the workspace can't be read) has no workspace rules:
+  it is an individual running souls outside any organisation, so local teams apply.
+- Verbs: `oats teams add` and `oats teams default` refuse where local teams are closed; `oats teams
+  remove` runs there, since removing local teams is the last step of committing them in the workspace.
+  `oats soul teams` is read only; its edit flags were removed (a soul's teams are a PR to the workspace).
+
+### `soul.yaml` and `oats-membership.yaml`
+
+Unchanged: they say nothing about teams, so a soul in a public repository carries no organisation's
+labels. Per-soul lists in `oats-membership.yaml` and teams in `soul.yaml` were rejected for the same
+reason v2 rejected them: labels belong to a workspace, and there should be one central place.
+
+## Reporting (contract)
+
+- `defaultTeam.from` (spawn preview, `inspect`, `oats souls`, readiness, `OATS_DEFAULT_TEAM_FROM`):
+  `soul`, `deployment` or `workspace`. `soul` changed meaning: it was the local `souls.default`.
+- Every `TeamRow` gains `via`.
+- `oats teams --json` is `teamsApi: 2`: `localTeams`, a `DefaultTeam` for the deployment, and the
+  workspace's `souls:` in place of the local `souls` block. `oats soul teams --json` is
+  `soulTeamsApi: 2`: `match` and `defaultMatch` (the `souls:` keys that applied) in place of `local` and
+  `all`. Feature `team-model-3` replaces `team-model-2`.
+- Readiness: local-teams-closed (failure) and `team-soul-unknown` (warning) join the team items;
+  `E_TEAM_NOT_ELIGIBLE` is no longer a kernel item (a soul's default is always one of its teams); it
+  remains the provider's join refusal.
+
+## 0.36.x → 0.38.0
+
+0.36.1 accepted and validated `defaultTeam`, `localTeams` and `souls:` without applying them, and warned
+(`team-model-3-migration`) about what 0.38.0 refuses, so every workspace could commit its side first, as
+0.29.4 did for 0.30. 0.38.0 applies the keys, refuses the old shape, and retires the warning. The steps
+for each kind of deployment are in the [0.38.0 release notes](../release-notes/v0.38.0.md).
+
+## Out of scope
+
+Enforcement on the aweb side (above); nested teams; the Desktop's team-editing UI (its own spec:
+anything that writes `souls.teams` or `souls.default` goes).

package/docs/design/README.md

@@ -17,7 +17,11 @@ successor, with a link to its full text.
 - [OKF knowledge operations](2026-09-26-okf-knowledge-operations.md): package
   souls, triggers and automations for harvest and maintenance.
 - [Team model v2](2026-09-27-team-model-v2.md): shared teams in the workspace,
-  local teams, the default team and membership in each deployment.
+  local teams, live teams and the provider environment (its membership and
+  default-team parts are superseded by team model 3).
+- [Team model 3](2026-10-02-team-model-3.md): the teams a soul may join, and
+  its default, are committed in the workspace; local teams only where the
+  workspace allows them.
 
 The Desktop's design brief for designers is in
 [packages/desktop/docs](../../packages/desktop/docs/design-brief.md).

package/docs/desktop-cli-api.md

@@ -37,7 +37,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
              "instance-git-remote","souls-declarations","lifecycle-plans","retire-retention","readiness","spawn-preview","instance-events",
              "instance-events-2","schedule-history","schedule-read-2","spawn-preview-2","spawn-idempotency","spawn-idempotency-2","spawn-apply-2",
              "workspace-v2","instance-modules","spawn-provider-payload","served-identity","packages-no-approval","spawn-name","settings-origins",
-             "team-model-2","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
+             "team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
              "preview-composed-from","observe-max-age","spawn-preview-max-age","capability-show","capture-file","workspace-identity"],
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
@@ -88,7 +88,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `settings-declared` | `declares` on inspect capabilities and preview modules | |
 | `capabilities-private` | `private` on `oats capabilities` rows | |
 | `layers-from` | `layers.<slot>.from` in inspect | |
-| `team-model-2` | every team field; `oats teams`, `oats soul teams` | `teamsApi: 1`, `soulTeamsApi: 1` (payload only) |
+| `team-model-3` | every team field; `oats teams`, `oats soul teams` (0.38.0; replaces `team-model-2`) | `teamsApi: 2`, `soulTeamsApi: 2` (payload only) |
 | `harness` | the harness names ([Harness input spellings](#the-harness-rename-feature-harness-oats-0270)) | |
 | `package-souls` | package soul rows, `qualifiedName`, `packages[].souls` | |
 | `triggers` | `oats trigger …` | `triggerApi: 1` (payload only) |
@@ -253,9 +253,11 @@ oats capabilities show <name> … --max-age <seconds> --json  (feature capabilit
   commit can no longer be fetched. Each is observed live, as without the flag.
   A live observation that fails is the usual error, never an older head.
 - **Refusals:** every other command, a spawn apply (with or without
-  `--expect-decision`; the form named is `spawn`), every edit form (`teams add|remove|default`,
-  `soul teams --add|--remove|--default|--clear-default`) and any `--server`
-  invocation refuse the flag before reading or writing anything, with
+  `--expect-decision`; the form named is `spawn`), every edit form (`teams add|remove|default`)
+  and any `--server`
+  invocation refuse the flag before reading or writing anything (the removed
+  `soul teams --add|--remove|--default|--clear-default` answer their own
+  `E_BAD_ARGS` first), with
   `E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
   verbs reuse observations (status, workspace status, souls, capabilities,
   capabilities show, inspect --soul|--home, spawn --preview, and the read
@@ -397,7 +399,8 @@ message}`.
 A soul whose resolution is refused is an inspect error with the resolver's
 code and details (`E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`,
 `E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`, `E_REQUIREMENT_INACTIVE`,
-`E_TEAM_UNKNOWN`, `E_TEAM_NOT_ELIGIBLE`); readiness reports the same condition
+`E_TEAM_UNKNOWN`, and `E_WORKSPACE_SCHEMA` reason `local-teams-closed`);
+readiness reports the same condition
 as an item. Soul lookup errors are those of [spawn](#spawn-errors).
 
 <a id="oats-readiness---home-----soul----dir----policy---json--readinessapi-2"></a>
@@ -595,6 +598,7 @@ A removed verb answers, before any namespace can claim it:
 | `status --team` | `E_BAD_ARGS` | `oats status` in the deployment |
 | `spawn --instance` | `E_BAD_ARGS` | `--purpose` or `--name` |
 | `spawn --ephemeral`, `--instructions-file`, `--def-file` | `E_BAD_ARGS` | a soul in a member repository |
+| `soul teams --add`, `--remove`, `--default`, `--clear-default` (0.38.0) | `E_BAD_ARGS` (`details: {flag, replacement}`) | `souls:` in `oats-workspace.yaml` |
 | `session … --native-record` | `E_BAD_ARGS` | none |
 
 `details.replacement` is the kernel's prose (shortened above): show it, do not
@@ -750,7 +754,7 @@ Read-only (it writes no lock):
 - `declaredPackages`: the ids in `packages:` (standalone: the kernel's
   default). `unsynced`: declared, not locked. `stale`: locked, no longer
   declared. `external[]`: `{source, soul}`.
-- `workspace.teams` (feature `team-model-2`): the shared teams `{label, team,
+- `workspace.teams` (feature `team-model-3`): the shared teams `{label, team,
   description}` by label; `[]` standalone.
 - `problems`, `warnings`: as in sync.
 - `automations` (feature `automations`): `{host, snapshot: {takenAt,
@@ -788,7 +792,7 @@ packages' capabilities and souls, sorted by name, then origin. Both carry
     "version":"4.1.1","repoKey":"github.com/awebai/oats-okf","commit":"e1d604f7…","teams":null,"defaultTeam":null,"private":false,
     "path":"oats-package/souls/knowledge-maintainer","work":"directory","description":"Reviews harvested knowledge.","harness":"pi","model":null,
     "harnessFrom":"kernel-default","file":{"path":"oats-package/souls/knowledge-maintainer/soul.yaml","url":null},
-    "spawnable":false,"problem":{"code":"E_TEAM_UNKNOWN","message":"team \"reviewers\" is not declared (oats-local.yaml#/souls/teams/…)"}}],
+    "spawnable":false,"problem":{"code":"E_TEAM_UNKNOWN","message":"team \"reviewers\" is not declared (oats-local.yaml#/defaultTeam): …"}}],
  "problems":[]}
 ```
 
@@ -804,13 +808,13 @@ are absent until `sync`.
 commit, teams, defaultTeam, private (always false), path, work, description`,
 plus the Desktop facts `harness, model, harnessFrom, file, spawnable,
 problem`, and (feature `launch-preference`) `key` and `launch`.
-- `key` is the soul key that `souls.teams`, `souls.default` and `souls.launch`
-  use, and that `oats soul teams <key>` takes: `qualifiedName` for a package
+- `key` is the soul key that `souls.launch` uses, and that
+  `oats soul teams <key>` takes: `qualifiedName` for a package
   soul, the bare `name` for a member or external soul. Two member souls that
   share a bare name share one entry (spawning that name is
   `E_SOUL_AMBIGUOUS`).
 - `launch` is a [Launch](#the-launch-report-launch).
-- `teams` and `defaultTeam` (feature `team-model-2`) are a
+- `teams` and `defaultTeam` (feature `team-model-3`) are a
   [TeamRow](#the-team-row-teamrow) list and a
   [DefaultTeam](#the-default-defaultteam); both `null` when the soul's teams
   do not resolve (`problem` names the `E_TEAM_*` code).
@@ -1012,7 +1016,7 @@ them. Gate each field below on it.
   v2 soul.yaml cannot). `spawnable`/`problem`: whether a spawn here would
   refuse, resolved without spawning, writing or reaching past the sync cache;
   `problem` is `{code, message}` or `null` (`E_SOUL_DISABLED`,
-  `E_TEAM_UNKNOWN`, `E_TEAM_NOT_ELIGIBLE`, `E_CAPABILITY_*`, `E_PACKAGE_*`,
+  `E_TEAM_UNKNOWN`, `E_WORKSPACE_SCHEMA` (local-teams-closed), `E_CAPABILITY_*`, `E_PACKAGE_*`,
   `E_LOCK_SCHEMA`, `E_REMOTE_*`, …). `file`: `{path, url}` of soul.yaml.
 - **Capabilities.** `layer` on every row, `null` outside the slots.
   `description` or `null`. `skills`, `commands`, `hooks`: names, sorted
@@ -1039,61 +1043,91 @@ them. Gate each field below on it.
   `…/tree/<commit>`); any other host gives `url: null` with `path` set.
   `path` is repository-relative.
 
+<a id="team-model-3-feature-team-model-3-oats-0370-replaces-feature-team-model-2"></a>
 <a id="team-model-v2-feature-team-model-2-oats-0300-replaces-feature-teams"></a>
 ## Teams
 
-Feature `team-model-2`: gate every team field and verb on it. Design:
-[team model v2](design/2026-09-27-team-model-v2.md); operator guide:
-[workspaces.md](workspaces.md).
-
-- **Shared teams** live in the committed `oats-workspace.yaml`:
-  `teams.<label> = {description?, team?}`. A shared team without `team` (the
-  provider id) is **unmapped**.
-- **Local** configuration lives in `oats-local.yaml`: `teams.<label> = {team,
-  description?}`, `defaultTeam: <label>`, `souls.teams: {"*": [labels],
-  "<soul>": [labels]}` and `souls.default: {"<soul>": <label>}`. A soul key is
-  the spawn name (`<package>/<soul>` for a package soul). A label matches
-  `[a-z0-9][a-z0-9._-]*`.
+Feature `team-model-3` (OATS 0.38.0; it replaces `team-model-2`): gate every
+team field and verb on it. Design: [team model 3](design/2026-10-02-team-model-3.md);
+operator guide: [workspaces.md](workspaces.md#teams).
+
+- **The workspace file** (`oats-workspace.yaml`, committed) holds the shared
+  teams `teams.<label> = {description?, team?}` (a shared team without `team`,
+  the provider id, is **unmapped**), `defaultTeam: <label>` (the workspace's
+  fallback default), `localTeams: true|false` (absent: false) and `souls:`
+  (per pattern, `{default?, teams?: [labels] | "any"}`). Every label there is
+  a shared label of that file; anything else is `E_WORKSPACE_SCHEMA` when the
+  file is read.
+- **`oats-local.yaml`** may declare local teams `teams.<label> = {team,
+  description?}` and `defaultTeam: <label>` only where the workspace says
+  `localTeams: true`, or in the standalone view (no workspace file is read).
+  Elsewhere they are refused: `E_WORKSPACE_SCHEMA` with details `{reason:
+  "local-teams-closed", path: "oats-local.yaml", keys}`, the message naming
+  both fixes. `souls.teams` and `souls.default` are removed keys
+  (`E_WORKSPACE_SCHEMA`, reason `removed-key`): the refusal names each key
+  found, and `details.replacement` is the `souls:` YAML to commit instead (a
+  bare soul name written `<member>/<soul>` for the operator to qualify), also
+  printed at the end of the message. Every command that reads the file
+  refuses, an instance home's messaging commands, operations, `inspect --home`
+  and `readiness --home` included: they never fall back to the home's
+  recorded teams for it. A home's other capability commands read only the
+  home's own record, as always.
+- **A soul's key** is its qualified name: `<package>/<soul>`, or
+  `<member>/<soul>` with the member repository's name (as `souls.disabled`
+  names it). A label matches `[a-z0-9][a-z0-9._-]*`.
 - **Team ids.** A `team` value (in either file, and `oats teams add --team`)
   matches `^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$`: the kernel's safety rule
   (never `-`-led, no whitespace or control characters, bounded). Otherwise
   `E_WORKSPACE_SCHEMA` (a file) or `E_BAD_ARGS` (the verb). The messaging
   provider validates its own id shape (oats.aweb: `<name>:<namespace>`).
-- **Resolution.** The soul's default is `souls.default[soul] ??
-  defaultTeam`; its teams are that default plus `souls.teams["*"]` plus
-  `souls.teams[soul]`. A label in both files is a `team-label-collision`
-  warning, and the shared definition wins. An undeclared label is
-  `E_TEAM_UNKNOWN`; a `souls.default` outside the soul's teams is
-  `E_TEAM_NOT_ELIGIBLE`.
+- **Resolution.** The `souls:` patterns for a soul are its key, then
+  `<member|package>/*`, then `"*"`. The most specific one that exists gives
+  the soul's teams outright (lists never merge); the most specific one that
+  sets `default` gives its default. So `a/*: {default: security}` and
+  `a/x: {teams: [docs]}` give `a/x` the default `security` and the teams
+  `[docs]` only. The default is that `default`; else the local `defaultTeam`
+  where local teams are allowed; else the workspace's `defaultTeam`; else
+  none. A soul's teams are its default, its pattern's `teams` (`any`: every
+  shared team) and, where local teams are allowed, every local team. A soul
+  no pattern matches has its default only. A label in both files is a
+  `team-label-collision` warning, and the shared definition wins. A local
+  default no file declares is `E_TEAM_UNKNOWN`.
 - **Removed keys** are `E_WORKSPACE_SCHEMA` with `reason: "removed-key"`:
+  `oats-local.yaml` `souls.teams` and `souls.default` (0.38.0);
   `messaging.byTeam`, `defaults.byTeam`, a soul.yaml `team`, an
-  oats-membership.yaml `team`, and `byTeam` in any provider payload layer.
-  Other payload keys are opaque (a `team` setting passes through).
+  oats-membership.yaml `team`, and `byTeam` in any provider payload layer
+  (0.30). Other payload keys are opaque (a `team` setting passes through).
 
 ### The team row (`TeamRow`)
 
-Exactly `{label, team, default, from}`:
+Exactly `{label, team, default, from, via}`:
 
 ```json
-[{"label":"antares","team":"antares:ana.aweb.ai","default":true,"from":"local"},
- {"label":"oats","team":"oats:oats.aweb.ai","default":false,"from":"shared"},
- {"label":"reviewers","team":null,"default":false,"from":"shared"}]
+[{"label":"security","team":"security:acme.aweb.ai","default":true,"from":"shared","via":["default"]},
+ {"label":"docs","team":null,"default":false,"from":"shared","via":["workspace"]},
+ {"label":"mine","team":"mine:ana.aweb.ai","default":false,"from":"local","via":["local"]}]
 ```
 
 `team` is `null` for an unmapped team. `default` is true on exactly the
 soul's default row; the others are teams an instance may join (offered, never
-joined automatically). `from` is `"shared"` or `"local"`. The default row
-comes first, then the rest by label (codepoint order). Reports include
-unmapped rows; `OATS_TEAMS` and `instance.json.teams` carry mapped rows only.
+joined automatically). `from` is where the label is defined: `"shared"` or
+`"local"`. `via` is why the soul may join it, an ordered non-empty subset of
+`"default"`, `"workspace"` (its `souls:` pattern) and `"local"` (a local team
+where local teams are allowed). The default row comes first, then the rest by
+label (codepoint order). Reports include unmapped rows; `OATS_TEAMS` and
+`instance.json.teams` carry mapped rows only. A home spawned before 0.38.0
+recorded rows without `via`, and they are reported as recorded.
 
 ### The default (`DefaultTeam`)
 
 ```json
-{"label":"antares","team":"antares:ana.aweb.ai","from":"deployment"}
+{"label":"security","team":"security:acme.aweb.ai","from":"soul"}
 ```
 
-`from` is `"deployment"` (`defaultTeam`) or `"soul"` (`souls.default`). It is
-`null` only when no default is configured (with messaging active, that is
+`from` is `"soul"` (the soul's `souls:` default in the workspace file; before
+0.38.0 it meant `oats-local.yaml` `souls.default`), `"deployment"` (the local
+`defaultTeam`) or `"workspace"` (the workspace's `defaultTeam`). It is `null`
+only when no default is configured (with messaging active, that is
 `E_TEAM_UNCONFIGURED`). An unmapped default is `{label, team: null, from}`,
 the blocking problem `team-unmapped`.
 
@@ -1119,9 +1153,12 @@ its spawn-time default until respawned (readiness says so with
 the teams in `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
 `OATS_DEFAULT_TEAM_FROM`, `OATS_TEAMS` and `OATS_TEAMS_SOURCE`:
 [capabilities.md](capabilities.md#teams-in-the-provider-environment).
-`OATS_WORKSPACE_NAME` is the recorded workspace name (the discovered one for a
-soul subject), `""` when unknown.
+`OATS_TEAMS` is exactly the soul's eligible mapped rows, so a provider that
+admits joins from it refuses any other team. `OATS_WORKSPACE_NAME` is the
+recorded workspace name (the discovered one for a soul subject), `""` when
+unknown.
 
+<a id="oats-teams"></a>
 ### `oats teams`
 
 ```text
@@ -1132,66 +1169,75 @@ oats teams default <label> --json
 ```
 
 ```json
-{"teamsApi":1,"deployment":"/w","defaultTeam":"antares",
- "teams":[{"label":"antares","team":"antares:ana.aweb.ai","description":null,"from":"local","default":true,"at":"oats-local.yaml#/teams/antares"},
-          {"label":"reviewers","team":null,"description":null,"from":"shared","default":false,"at":"github.com/awebai/oats:oats-workspace.yaml#/teams/reviewers"}],
- "souls":{"teams":{"*":["oats"],"oats-expert":["reviewers"]},"default":{"oats-expert":"oats"}},
- "problems":[{"code":"team-unmapped","label":"reviewers","default":false,"severity":"warning","at":"github.com/awebai/oats:oats-workspace.yaml#/teams/reviewers",
-              "message":"shared team reviewers has no provider id yet","fix":"its owner runs `oats aweb setup`, then commits the id"}]}
+{"teamsApi":2,"deployment":"/w","localTeams":true,"defaultTeam":{"label":"mine","team":"mine:ana.aweb.ai","from":"deployment"},
+ "teams":[{"label":"mine","team":"mine:ana.aweb.ai","description":null,"from":"local","default":true,"at":"oats-local.yaml#/teams/mine"},
+          {"label":"docs","team":null,"description":null,"from":"shared","default":false,"at":"github.com/acme/agents:oats-workspace.yaml#/teams/docs"}],
+ "souls":{"*":{"teams":["docs"]},"security-souls/*":{"default":"security","teams":["engineering"]}},
+ "problems":[{"code":"team-unmapped","label":"docs","default":false,"severity":"warning","at":"github.com/acme/agents:oats-workspace.yaml#/teams/docs",
+              "message":"shared team docs has no provider id yet","fix":"its owner runs `oats aweb setup`, then commits the id"}]}
 ```
 
-- `defaultTeam` is the deployment's label (or `null`), not a `DefaultTeam`.
+- `localTeams`: the workspace's answer (`true`/`false`), `null` in the
+  standalone view. `defaultTeam` is the `DefaultTeam` a soul without a
+  `souls:` default gets here (`from` `"deployment"` or `"workspace"`), or
+  `null`.
 - `teams[]`: every declared team by label, `{label, team, description, from,
-  default, at}`; `at` is a pointer into `oats-local.yaml` or
-  `<workspace key>:oats-workspace.yaml#/teams/<label>`. A collision shows the
-  shared definition.
-- `souls`: `souls.teams` and `souls.default` as written. `problems`: the
-  deployment's [team readiness items](#team-readiness-items).
+  default, at}`; `default` marks that `defaultTeam`; `at` is a pointer into
+  `oats-local.yaml` or `<workspace key>:oats-workspace.yaml#/teams/<label>`.
+  A collision shows the shared definition.
+- `souls`: the workspace's `souls:` as committed (`{}` when none).
+  `problems`: the deployment's [team readiness items](#team-readiness-items).
+  The command discovers the workspace (every member's souls), for the
+  `team-soul-unknown` check.
 - The verbs never call a provider. They validate, rewrite `oats-local.yaml` in
   place, and answer the document plus `changed: bool`.
-- **`add`**: the first team added also becomes `defaultTeam`. A label already
-  declared is `E_TEAM_EXISTS {label, from}`; a bad label or no `--team` is
-  `E_BAD_ARGS`.
-- **`remove`**: a referenced label is `E_TEAM_IN_USE {label, usedBy}` (each
-  `"defaultTeam"`, `"souls.teams:<key>"` or `"souls.default:<key>"`); a shared
-  label is `E_TEAM_SHARED {label, at}` (a label in both files can be removed
-  locally); unknown is `E_TEAM_UNKNOWN {label}`.
+- **Where local teams are not allowed**, `add` and `default` are refused
+  before anything is written: `E_WORKSPACE_SCHEMA {reason:
+  "local-teams-closed", path, keys}` (`keys` what the verb writes). `remove`
+  still runs there: taking local teams away is the last step of committing
+  them in the workspace.
+- **`add`**: the first team added also becomes the local `defaultTeam`. A
+  label already declared is `E_TEAM_EXISTS {label, from}`; a bad label or no
+  `--team` is `E_BAD_ARGS`.
+- **`remove`**: a label the local `defaultTeam` names is `E_TEAM_IN_USE
+  {label, usedBy: ["defaultTeam"]}`; a shared label is `E_TEAM_SHARED {label,
+  at}` (a label in both files can be removed locally); unknown is
+  `E_TEAM_UNKNOWN {label}`.
 - **`default`**: any declared label, else `E_TEAM_UNKNOWN`.
-- A write that would introduce an unknown or ineligible reference is refused
-  with that code; an invalid result is `E_WORKSPACE_SCHEMA`.
+- A write that would introduce an unknown reference is refused with that
+  code; an invalid result is `E_WORKSPACE_SCHEMA`.
+- **Writes** edit `oats-local.yaml` in place and touch only the entries that
+  change: comments and styles elsewhere, including inline comments on sibling
+  entries, are kept. Each verb re-reads the file and judges its refusals on it
+  as it is now, and writes only if the file did not change meanwhile (else it
+  redoes the edit on the new content). A file that keeps changing is
+  `E_LOCAL_CHANGED {path}`; nothing was written.
 
+<a id="oats-soul-teams"></a>
 ### `oats soul teams`
 
 ```text
-oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default] [--dir <d>] --json
-oats soul teams <soul>|'*' [--dir <d>] [--max-age <s>] --json    (the read form only)
+oats soul teams <soul>|'*' [--dir <d>] [--max-age <s>] --json
 ```
 
 ```json
-{"soulTeamsApi":1,"soul":"oats-expert","key":"oats-expert","defaultTeam":{"label":"oats","team":"oats:oats.aweb.ai","from":"soul"},
- "teams":[{"label":"oats","team":"oats:oats.aweb.ai","default":true,"from":"shared","via":["default","*"]},
-          {"label":"reviewers","team":null,"default":false,"from":"shared","via":["soul"]}],
- "local":{"teams":["reviewers"],"default":"oats"},"all":["oats"]}
+{"soulTeamsApi":2,"soul":"incident-responder","key":"security-souls/incident-responder",
+ "match":"security-souls/incident-responder","defaultMatch":"security-souls/*",
+ "defaultTeam":{"label":"security","team":"security:acme.aweb.ai","from":"soul"},
+ "teams":[{"label":"security","team":"security:acme.aweb.ai","default":true,"from":"shared","via":["default"]},
+          {"label":"docs","team":null,"default":false,"from":"shared","via":["workspace"]},
+          {"label":"engineering","team":"engineering:acme.aweb.ai","default":false,"from":"shared","via":["workspace"]}]}
 ```
 
-- Rows are `TeamRow` plus `via`, a non-empty ordered subset of `"default"`,
-  `"*"` and `"soul"`. `key` is the soul's `souls.*` key; `local` its own
-  entries; `all` is `souls.teams["*"]`.
-- For `'*'`: `soul` and `key` are `"*"`, `teams` the deployment default plus
-  `souls.teams["*"]`, `local.default: null`.
-- Mutations answer the document plus `changed`. Unknown label:
-  `E_TEAM_UNKNOWN {label}`. A `--default` outside the soul's teams:
-  `E_TEAM_NOT_ELIGIBLE {soul, label, at}` (`at`: `oats-local.yaml#/souls/default/<key>`,
-  `/` written `~1`). `--default`/`--clear-default` with
-  `'*'`, or both together: `E_BAD_ARGS`. Soul lookup: `E_SOUL_UNKNOWN`,
-  `E_SOUL_AMBIGUOUS`.
-- **Writes** (`oats teams add|remove|default`, `oats soul teams`) edit
-  `oats-local.yaml` in place and touch only the entries that change: comments
-  and styles elsewhere, including inline comments on sibling entries and flow
-  lists, are kept. Each verb re-reads the file and judges its refusals on it
-  as it is now, and writes only if the file did not change meanwhile (else it
-  redoes the edit on the new content). A file that keeps changing is
-  `E_LOCAL_CHANGED {path}`; nothing was written.
+- Read only. `key` is the soul's key; `match` the `souls:` key its teams come
+  from and `defaultMatch` the one its default comes from (`null`: none
+  matches, or none sets a default). For `'*'`, `soul`, `key` and the only
+  pattern tried are `"*"`. Soul lookup: `E_SOUL_UNKNOWN`, `E_SOUL_AMBIGUOUS`;
+  the soul's teams: `E_WORKSPACE_SCHEMA` (local-teams-closed), `E_TEAM_UNKNOWN`.
+- The edit flags `--add`, `--remove`, `--default` and `--clear-default` were
+  removed in 0.38.0: `E_BAD_ARGS` with details `{flag, replacement: "souls: in
+  oats-workspace.yaml (a PR to the workspace file)"}`, before anything else
+  is judged.
 
 ### The messaging provider's teams document
 
@@ -1218,8 +1264,9 @@ no `primary` and no `unmapped`: unmapped teams are kernel readiness items.
 `oats teams` lists them under `problems[]` as `{code, severity: "failure" |
 "warning", message, fix, …}`. `oats readiness` lists the soul's under
 `checks.configured` with `subject` `"team <label>"` (or `"teams"`), `producer:
-"team model"`, `code`, `reason`, `remedy`, `status: "fail"`, `required: true`
-for a failure and `false` for a warning, plus the problem's own keys.
+"team model"`, `code`, `reason` (the message), `remedy` (the fix), `status:
+"fail"`, `required: true` for a failure and `false` for a warning, plus the
+problem's own keys.
 
 | Code | Severity | Keys | When |
 |---|---|---|---|
@@ -1227,40 +1274,31 @@ for a failure and `false` for a warning, plus the problem's own keys.
 | `team-unmapped` | failure if `default`, else warning | `label`, `default`, `at` | a shared team without `team` |
 | `team-label-collision` | warning | `label`, `shared`, `local` (each `{team, description, at}`) | a label in both files |
 | `default-team-changed` | warning | `recorded`, `current` | `--home` with live teams: the default changed since the spawn |
-| `E_TEAM_UNKNOWN` | failure | `label`, `at` | a reference to an undeclared label |
-| `E_TEAM_NOT_ELIGIBLE` | failure | `soul`, `label`, `at` | `souls.default` outside the soul's teams |
-| `team-model-3-migration` | warning | `condition`, `keys` | 0.36.x: what OATS 0.37.0 (team model 3) refuses, one item per condition (below) |
-
-The `E_TEAM_UNKNOWN` and `E_TEAM_NOT_ELIGIBLE` codes are also spawn, preview and
-inspect refusals, with the same details.
-
-`team-model-3-migration` is a deployment fact, so every soul's readiness
-carries it, and `oats teams` lists it once. Its `condition`:
-
-- `local-soul-teams`: `oats-local.yaml` has `souls.teams` and/or
-  `souls.default` (`keys`: `["souls.teams", "souls.default"]` as found). They
-  move to `souls:` in `oats-workspace.yaml`.
-- `local-teams-closed`: `oats-local.yaml` declares `teams` and/or
-  `defaultTeam` (`keys`: `["teams", "defaultTeam"]` as found) and the
-  workspace file does not say `localTeams: true`. The `fix` names both
-  remedies: add `localTeams: true` to the workspace file, or commit the teams
-  and `defaultTeam` there and remove them locally. Never raised in the
-  standalone view, which has no workspace rules.
+| `E_TEAM_UNKNOWN` | failure | `label`, `at` | a local default no file declares |
+| `E_WORKSPACE_SCHEMA` | failure | `condition: "local-teams-closed"`, `path`, `keys` | `oats-local.yaml` declares `teams` / `defaultTeam` and the workspace does not allow local teams |
+| `team-soul-unknown` | warning | `key`, `at` | a `souls:` key that is neither `"*"` nor `<name>/*` nor a discovered soul's key (a typo guard) |
+
+`E_TEAM_UNKNOWN` and local-teams-closed are also spawn, preview and inspect
+refusals (local-teams-closed as `E_WORKSPACE_SCHEMA` with details `{reason,
+path, keys}`). While local teams are closed, that one item is the soul's only
+team item. `team-soul-unknown` is reported where the souls are discovered
+(`oats teams`, readiness).
 
 ```json
-{"code":"team-model-3-migration","severity":"warning","condition":"local-teams-closed","keys":["teams","defaultTeam"],
- "message":"oats-local.yaml declares teams, defaultTeam, but oats-workspace.yaml does not say localTeams: true: OATS 0.37.0 refuses local teams and a local defaultTeam unless the workspace allows them",
+{"code":"E_WORKSPACE_SCHEMA","severity":"failure","condition":"local-teams-closed","path":"oats-local.yaml","keys":["teams","defaultTeam"],
+ "message":"oats-local.yaml declares teams, defaultTeam, but oats-workspace.yaml does not allow local teams (localTeams: true): either (a) add `localTeams: true` to oats-workspace.yaml, or (b) commit the teams and defaultTeam in oats-workspace.yaml, then remove them from oats-local.yaml",
  "fix":"either (a) add `localTeams: true` to oats-workspace.yaml, or (b) commit the teams and defaultTeam in oats-workspace.yaml, then remove them from oats-local.yaml"}
 ```
 
-As a readiness item it is `{subject: "teams", status: "fail", required: false,
-producer: "team model", code, reason: <message>, remedy: <fix>, condition,
-keys}`. `oats doctor --json` lists the same problems under `problems[]`. Doctor
-stays offline: for `local-teams-closed` it reads only the workspace file this
-machine's parsed cache holds; when there is none, it adds no problem and says
-so in `information[]`: `"team-model-3-migration: whether oats-local.yaml
-teams/defaultTeam need localTeams: true couldn't be checked: this deployment
-hasn't observed its workspace yet; run oats sync"`.
+`oats doctor --json` lists local-teams-closed under `problems[]` (text: `!
+E_WORKSPACE_SCHEMA (local-teams-closed): …`). Doctor stays offline: it reads
+only the workspace file this machine's parsed cache holds; when there is
+none, it adds no problem and says so in `information[]`:
+`"local-teams-closed: whether oats-workspace.yaml allows oats-local.yaml
+teams/defaultTeam (localTeams: true) couldn't be checked: this deployment
+hasn't observed its workspace yet; run oats sync"`. A removed key in
+`oats-local.yaml` makes doctor answer that refusal, as for any unreadable
+local file.
 
 <a id="soul-launch-preferences-feature-launch-preference-oats-0300"></a>
 ## Launch preferences
@@ -1613,7 +1651,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 | `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
 | `E_SOUL_DISABLED` | `{name, qualifiedName, entry}` | listed in `souls.disabled` |
 | `E_UNKNOWN_AGENT` | | the resolved soul is not under the deployment's agents root |
-| `E_TEAM_UNKNOWN`, `E_TEAM_NOT_ELIGIBLE` | `{label, at}`, `{soul, label, at}` | the soul's teams do not resolve |
+| `E_TEAM_UNKNOWN`, `E_WORKSPACE_SCHEMA` (local-teams-closed) | `{label, at}`, `{reason, path, keys}` | the soul's teams do not resolve |
 | `E_NOT_A_MEMBER`, `E_MEMBERSHIP_UNCONFIRMED` | | the soul's repository is not a confirmed member |
 | `E_CAPABILITY_MISSING`, `E_CAPABILITY_PRIVATE`, `E_CAPABILITY_INCOMPATIBLE`, `E_COMPATIBILITY` | | a capability cannot be resolved |
 | `E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`, `E_LOCK_SCHEMA` | | the lock does not provide it (standalone: `{…, standalone: true, reason: "no-catalog", catalog}`) |