@awebai/oats 0.36.0 → 0.36.1

package/bin/oats.mjs

@@ -36,7 +36,7 @@ import {
   writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
   classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
 import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
-import { recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "../lib/teams.mjs";
+import { migrationProblems, recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "../lib/teams.mjs";
 import { launchLayers } from "../lib/launch-preference.mjs";
 import { parseConfigData } from "../lib/config-data.mjs";
 import * as remoteModule from "../lib/remote.mjs";
@@ -221,6 +221,19 @@ async function doctorComposition(ctx, soulName, ws, bail) {
   } finally { for (const c of cleanups) { try { c(); } catch { /* best effort: temporary copies only */ } } }
 }
 
+/** team-model-3-migration in doctor (0.36.x), OFFLINE like the rest of doctor: oats-local.yaml, and for its
+ *  local teams the workspace file this machine's parsed cache holds (cachedWorkspace: no git process, no
+ *  network). Without that file, whether local teams need `localTeams: true` is said to be unchecked
+ *  (information), never guessed. The standalone view has no workspace rules. → { problems, information } */
+function doctorTeamMigration(local) {
+  const standalone = typeof local.standalone === "string" && local.standalone !== "";
+  const file = standalone ? null : cachedWorkspace(local.workspace)?.file ?? null;
+  const model = teamModel(file, local);
+  const unchecked = !standalone && file === null && model.migration.teamKeys.length > 0;
+  return { problems: migrationProblems(model),
+    information: unchecked ? ["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"] : [] };
+}
+
 /** Workspace-model v2 doctor data, OFFLINE: the deployment declaration found
  * walking up from ctx (oats-local.yaml) and the lock v3 beside it. Doctor never
  * goes to the network for this view (only `--soul`, which resolves the soul like a
@@ -230,7 +243,7 @@ function doctorLockData(ctx) {
   let lockDir = ctx;
   try {
     const found = loadLocal(ctx);
-    out.local = { path: found.path, workspace: found.local.workspace };
+    out.local = { path: found.path, workspace: found.local.workspace, value: found.local };
     lockDir = dirname(found.path);
   } catch (e) {
     // An unreadable oats-local.yaml, or a 0.25 oats-config.yaml inside the deployment
@@ -584,12 +597,13 @@ function legacyLayoutProblems(root) {
 async function doctorWorkspaceJson(ctx, soulName, ws) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
   const agentsRoot = join(dirname(ws.local.path), "agents");
-  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean);
+  const migration = doctorTeamMigration(ws.local.value);
+  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...migration.problems].filter(Boolean);
   return {
     schemaVersion: 1, workspaceApi: 2, context: ctx,
     workspace: { file: ws.local.path, ref: ws.local.workspace },
     workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
-    information: operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : [],
+    information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...migration.information],
     composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
     ...(problems.length ? { problems } : {}),
   };
@@ -624,7 +638,10 @@ async function doctor(dir) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg) => die(`${msg} [${code}]`));
   printDoctorWorkspace(ws);
   const agentsRoot = join(dirname(ws.local.path), "agents");
+  const migration = doctorTeamMigration(ws.local.value);
   for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
+  for (const p of migration.problems) console.log(`\n! ${p.code}: ${p.message} — ${p.fix}`);
+  for (const line of migration.information) console.log(`\nINFO: ${line}`);
   if (soulName) {
     const information = operationalKnowledgeNote(composition, soulName);
     if (information) console.log(`\nINFO: ${information}`);

package/docs/configuration.md

@@ -81,6 +81,12 @@ refused (`E_WORKSPACE_SCHEMA`).
 How teams are resolved, and what a messaging provider does with them, is in
 [workspaces.md](workspaces.md#teams).
 
+OATS 0.37.0 (team model 3) removes `souls.teams` and `souls.default` (they move
+to `souls:` in `oats-workspace.yaml`) and allows `teams` and `defaultTeam` here
+only when the workspace file says `localTeams: true`. 0.36.x still applies all
+four keys and warns about them (`team-model-3-migration`): see
+[Preparing for team model 3](workspaces.md#preparing-for-team-model-3-036x).
+
 ## Launch configurations
 
 An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`

package/docs/desktop-cli-api.md

@@ -725,7 +725,7 @@ Read-only (it writes no lock):
              "souls":["rm"],"capabilities":["nw-house-style"],"publishes":null,"url":"https://github.com/nw/agents/tree/66566512…",
              "membershipFile":{"path":"oats-membership.yaml","url":"https://github.com/nw/agents/blob/66566512…/oats-membership.yaml"}}],
  "packages":[{"id":"oats.okf","version":"3.0.0","source":"catalog:oats.okf","commit":"ab897841…","integrity":"sha256-bada35…",
-              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.1.0","ref":"v4.1.0"}}],
+              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.1.1","ref":"v4.1.1"}}],
  "declaredPackages":["oats.framework","oats.okf"],"unsynced":["oats.framework"],"stale":[],
  "external":[{"source":"git:github.com/oss/experts@3c606e09…","soul":"security-reviewer"}],
  "problems":[],"warnings":[],
@@ -784,8 +784,8 @@ packages' capabilities and souls, sorted by name, then origin. Both carry
     "defaultTeam":{"label":"mine","team":"mine:ana.aweb.ai","from":"deployment"},
     "private":false,"path":"souls/writer","work":"directory","description":"Drafts campaigns.","harness":"pi","model":null,"harnessFrom":"kernel-default",
     "file":{"path":"souls/writer/soul.yaml","url":null},"spawnable":true,"problem":null},
-   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.1.0","kind":"package","package":"oats.okf",
-    "version":"4.1.0","repoKey":"github.com/awebai/oats-okf","commit":"e331a996…","teams":null,"defaultTeam":null,"private":false,
+   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.1.1","kind":"package","package":"oats.okf",
+    "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/…)"}}],
@@ -874,8 +874,8 @@ nothing reads a working clone.
 **The show:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.1.0",
- "commit":"e331a996…","path":"oats-package/capabilities/oats-okf",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","repoKey":"github.com/awebai/oats-okf","package":"oats.okf","version":"4.1.1",
+ "commit":"e1d604f7…","path":"oats-package/capabilities/oats-okf",
  "inject":{"path":"injects/okf.md","bytes":2422,"text":"## Knowledge: OKF\n\nYou have two kinds of knowledge. …","binary":false,"truncated":false},
  "skills":[{"name":"okf-consultation","path":"skills/okf-consultation","description":"Consulting your soul's knowledge with the `oats okf` CLI: …",
             "files":[{"path":"skills/okf-consultation/SKILL.md","bytes":6947},{"path":"skills/okf-consultation/references/consult.md","bytes":4465}],
@@ -901,7 +901,7 @@ nothing reads a working clone.
 **The `--file` answer:**
 
 ```json
-{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"e331a996…",
+{"capabilityShowApi":1,"name":"oats.okf","kind":"package","commit":"e1d604f7…",
  "file":{"path":"skills/okf-instance-knowledge/SKILL.md","bytes":4787,"text":"---\nname: okf-instance-knowledge\n…","binary":false,"truncated":false}}
 ```
 
@@ -1229,9 +1229,38 @@ for a failure and `false` for a warning, plus the problem's own keys.
 | `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 last two are also spawn, preview and inspect refusals, with the same
-details.
+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.
+
+```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",
+ "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"`.
 
 <a id="soul-launch-preferences-feature-launch-preference-oats-0300"></a>
 ## Launch preferences

package/docs/integrations.md

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

package/docs/knowledge.md

@@ -26,7 +26,7 @@ The workspace pins the package and fills the slot for every soul by default:
 ```yaml
 # oats-workspace.yaml (excerpt)
 packages:
-  oats.okf: v4.1.0
+  oats.okf: v4.1.1
 defaults:
   knowledge: { oats.okf: { from: package } }
 stores:

package/docs/oats-workspace.schema.json

@@ -27,6 +27,20 @@
       "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."
     },
+    "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."
+    },
+    "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."
+    },
+    "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."
+    },
     "defaults": { "$ref": "#/$defs/defaults" },
     "stores": {
       "type": "object",
@@ -111,6 +125,20 @@
         "team": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$", "description": "The messaging provider's team id (for oats.aweb, <team>:<namespace>). Absent: declared, not yet created. The kernel's safety rule: never '-'-led, no whitespace or control characters, at most 256 characters; the provider validates its own shape." }
       }
     },
+    "soulTeams": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "default": { "$ref": "#/$defs/label", "description": "The soul's default team: a label of teams: in this file." },
+        "teams": {
+          "anyOf": [
+            { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/label" } },
+            { "const": "any" }
+          ],
+          "description": "The other teams the soul may join: labels of teams: in this file, or \"any\" for every one. [] (or no teams) is default only."
+        }
+      }
+    },
     "defaults": {
       "type": "object",
       "additionalProperties": false,

package/docs/official-catalog.md

@@ -9,8 +9,8 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
-| `oats.okf` | `v4.1.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
+| `oats.framework` | `oats-framework/v1.4.2` (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.engineering` | `v1.5.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
@@ -27,7 +27,7 @@ no lock and adds nothing to an existing workspace.
 ## Find and use packages
 
 - A workspace pins an official package by **bare version** in its
-  `packages:` map (`oats.okf: v4.1.0`); `oats sync` resolves it through the
+  `packages:` map (`oats.okf: v4.1.1`); `oats sync` resolves it through the
   catalog to an exact commit, fetches it, verifies its integrity and locks it.
   A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
   not join a team or adopt the publisher's workspace. See

package/docs/packages.md

@@ -44,14 +44,14 @@ whole organisation:
 
 ```yaml
 packages:
-  oats.okf: v4.1.0                                    # bare version → the official catalog
+  oats.okf: v4.1.1                                    # bare version → the official catalog
   acme.tools: git:github.com/acme/tools@v0.4.0        # direct ref: git:<repo>@<tag or full OID>
 ```
 
-- **Bare version** (`v4.1.0`, `4.1.0`, `1.0.0-rc.1`): the id is looked up in
+- **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.0` or `oats-framework/v1.4.1`) and the payload path. An id
+  convention (`v4.1.1` or `oats-framework/v1.4.2`) 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,8 +74,8 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.1
-  oats.okf: v4.1.0
+  oats.framework: v1.4.2
+  oats.okf: v4.1.1
   oats.aweb: v1.17.7
 teams:
   platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -105,7 +105,7 @@ decision recorded in the lock.
 $ oats sync
 workspace  acme  (github.com/acme/agents @ 3f2a9c1e)
 members    agents ✓↔ (@ 3f2a9c1e)   platform ✓↔ (@ 77c0a1b2)   billing ✗ (no-backlink)
-packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.1.0 ✓ (@ e331a996)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.1.1 ✓ (@ e1d604f7)
 changed    acme.tools  — → 0.4.0 (@ 47f4b816)
 souls      9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
 teams      platform (shared) · this deployment's: oats teams
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
       "source": "catalog:oats.okf",
       "url": "https://github.com/awebai/oats-okf.git",
       "path": "oats-package",
-      "version": "4.1.0",
-      "commit": "e331a9969d10aabddaa5824991f1846c7dedb388",
+      "version": "4.1.1",
+      "commit": "e1d604f70c5e4cdc39602095f139383e61f69323",
       "integrity": "sha256-…",
       "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
     },
@@ -331,12 +331,12 @@ 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.0", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.1", "path": "oats-package" }
+    "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" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.4.1`
-resolves to tag `oats-framework/v1.4.1`. Resolving through the catalog never
+`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
 advances a lock by itself: `oats sync` does, and says so.

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

@@ -0,0 +1,103 @@
+# OATS 0.36.1
+
+## Changed
+
+- **oats.okf 4.1.1** (catalog and workspace pin, and the bundled mirrors):
+  three fixes to harvest completion and `harvest --once`.
+  - `oats okf complete` on an amended PR that is still open
+    (awebai/oats-okf#36). After the knowledge-maintainer pushed an amendment
+    on top of the delivered commit, `complete --run <id>` failed with `E_PR:
+    publication branch has unexpected commit; never force push`. The run is
+    now reported `delivered` when the known PR is open at the branch's tip
+    and Git shows that tip descends from the delivered commit; the answer
+    names the amended head. A tip that does not contain the delivered commit
+    is still refused with `E_PR`, and nothing is ever force-pushed. Ancestry
+    is read from the commit objects alone, so a checkout's grafts or
+    commit-graph file cannot fake it.
+  - `harvest --once`: one-shots of a seat no longer race
+    (awebai/oats-okf#39). The overlap checks and the install run under one
+    seat lock, so of two overlapping one-shots started together one installs
+    and the other gets `E_ONCE_OVERLAP`.
+  - `harvest --once`: a note edited between runs no longer strands a
+    draining one-shot (awebai/oats-okf#40). A rerun with the same manifest
+    continues from custody without reading the listed notes. Another
+    manifest listing a note a one-shot already holds is refused with
+    `E_ONCE_OVERLAP`, naming that one-shot, instead of a `sha256 mismatch`.
+- **Preparing for team model 3** (awebai/oats#485). OATS 0.37.0 commits the
+  teams an organisation's souls may join, and their default team, in the
+  workspace file, closed by default (awebai/oats#484), so the organisation's
+  intended team set is visible and reviewable in its git and a deployment's
+  `oats-local.yaml` no longer adds a team by accident. 0.36.1 lets every workspace and
+  deployment migrate before 0.37.0 refuses the old shape:
+  - `oats-workspace.yaml` accepts `defaultTeam`, `localTeams` and `souls:`,
+    and validates them: every label they name must be a shared team in
+    `teams:` of the same file (`E_WORKSPACE_SCHEMA` otherwise, when the file
+    is read). 0.36.1 does **not** apply them: a soul's teams and default are
+    still resolved from `oats-local.yaml`. Earlier releases refuse these keys,
+    so add them only once everyone who reads the workspace runs 0.36.1 or
+    later.
+  - A new readiness warning, `team-model-3-migration` (never blocking), names
+    what 0.37.0 will refuse. `oats teams`, `oats readiness` (and so the
+    Desktop's readiness view) and `oats doctor` show it. Its `condition` is
+    `local-soul-teams` when `oats-local.yaml` has `souls.teams` or
+    `souls.default`, and `local-teams-closed` when `oats-local.yaml` declares
+    `teams` or `defaultTeam` and the workspace file does not say
+    `localTeams: true` (never in the standalone view). `oats doctor` stays
+    offline: it checks `local-teams-closed` against the workspace file this
+    machine last observed, and says so when there is none yet (`oats sync`
+    fixes that). The shapes are in docs/desktop-cli-api.md, under Team
+    readiness items.
+- **oats.framework 1.4.2** (oats.setup 2.2.1; catalog and workspace pin
+  `oats-framework/v1.4.2`) ships the oats.setup skill changes made since
+  1.4.1, which deployments had not received:
+  - `oats-onboarding`: declare how this machine starts a harness once, as
+    that harness's default launch configuration (0.32.0, awebai/oats#368);
+    `oats spawn --preview` names the launch configuration that applies.
+  - `oats-workspace-config`: a soul's launch preference versus a host launch
+    configuration, `E_LAUNCH_CONFIG_INVALID` and `E_CLAUDE_CONFIG_REMOVED`
+    (awebai/oats#368), and the team model 3 workspace keys `defaultTeam`,
+    `localTeams` and `souls:` (awebai/oats#495).
+  - `oats-teams`: preparing for team model 3, and what each
+    `team-model-3-migration` condition asks for (awebai/oats#495).
+  - `oats-package-pins`: the example pins `oats.okf: v4.1.1`
+    (awebai/oats#494).
+
+## What 0.37.0 will change
+
+- **`souls:` in `oats-workspace.yaml` decides which teams a soul may join**
+  besides its default: the most specific key wins (`<member|package>/<soul>`,
+  then `<member|package>/*`, then `"*"`); `teams` is a list of shared labels
+  or `any`. A soul no key matches joins its default only. This applies to
+  package souls too: a workspace opens a package explicitly.
+- **A soul's default team**, in order: its `souls:` `default`; else the
+  deployment's `defaultTeam`, only when the workspace says
+  `localTeams: true`; else the workspace's `defaultTeam`.
+- **`oats-local.yaml` `souls.teams` and `souls.default` are refused**
+  (`E_WORKSPACE_SCHEMA`, reason `removed-key`), and so are `oats soul teams
+  --add/--remove/--default/--clear-default`.
+- **Local `teams` and `defaultTeam` are refused unless the workspace says
+  `localTeams: true`**, and so are `oats teams add/remove/default`. The
+  standalone view still allows them.
+
+## Upgrade
+
+Nothing is required for 0.36.1 itself. To be ready for 0.37.0
+(`oats teams` lists each deployment's `team-model-3-migration` warnings):
+
+1. **Now**, once everyone who reads the workspace runs 0.36.1 or later,
+   commit in `oats-workspace.yaml` the choices each deployment makes locally:
+   - a `souls:` entry for what `souls.teams` says (`"*": { teams: [...] }`
+     for every soul, `<member|package>/<soul>: { teams: [...] }` for one;
+     local keys are bare soul names, workspace keys are qualified by the
+     member or package, as in `souls.disabled`), with a `default:` for what
+     `souls.default` says;
+   - for local teams and a local `defaultTeam`, choose one: (a) keep them
+     personal, and add `localTeams: true`, which clears `local-teams-closed`
+     at once; or (b) commit the teams in `teams:` and the default as
+     `defaultTeam:`.
+2. **When the deployment moves to 0.37.0**, remove from its `oats-local.yaml`
+   `souls.teams`, `souls.default` and, under (b), the local `teams` and
+   `defaultTeam`. Not before: 0.36.1 does not apply the workspace keys, so
+   those local keys are still what decides a soul's teams and default until
+   then, and their warnings stay until they go. 0.37.0 refuses them, naming
+   the replacement.

package/docs/souls-and-instances.md

@@ -152,8 +152,8 @@ composed skills and instructions, a spawn records:
       "commit": "3f2a9c1e…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.118Z"
     },
     "oats.okf": {
-      "from": { "kind": "package", "package": "oats.okf", "version": "4.1.0", "commit": "e331a996…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
-      "commit": "e331a996…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
+      "from": { "kind": "package", "package": "oats.okf", "version": "4.1.1", "commit": "e1d604f7…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
+      "commit": "e1d604f7…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
     }
   },
   "providers": {

package/docs/workspaces.md

@@ -54,8 +54,8 @@ 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.1                   # bare version → resolves through the official catalog
-  oats.okf: v4.1.0
+  oats.framework: v1.4.2                   # 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
@@ -359,6 +359,39 @@ there is no default; `team-unmapped`, blocking when it is the default;
 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.37.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 prepares 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.37.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).
+
 ## Provider payloads have three homes
 
 | What it is | Where | Example |

package/lib/teams.mjs

@@ -17,6 +17,10 @@
  * Rows (docs/desktop-cli-api.md, Team model v2): TeamRow { label, team, default, from: shared|local },
  * the default first, then by label. Reports carry unmapped rows (team null); OATS_TEAMS and
  * instance.json carry mapped rows only. DefaultTeam { label, team, from: deployment|soul } | null.
+ *
+ * Team model 3 (0.37.0, awebai/oats#484) moves these choices into the committed workspace file. 0.36.x
+ * validates its keys (lib/workspace.mjs) without applying them, and warns about what 0.37.0 will refuse
+ * (migrationProblems: team-model-3-migration).
  */
 import { oatsError } from "./errors.mjs";
 
@@ -53,11 +57,19 @@ export function teamModel(workspace, local, { workspaceKey = null } = {}) {
     localTeams.set(label, { label, team: str(def?.team), description: str(def?.description), from: "local", at: `${LOCAL_FILE}#/teams/${pointerKey(label)}` });
   }
   const souls = isObject(local?.souls) ? local.souls : {};
+  const has = (v, k) => isObject(v) && Object.hasOwn(v, k);
   return {
     shared, local: localTeams,
     labels: new Map([...localTeams, ...shared]), // the committed definition wins a collision
     defaultTeam: str(local?.defaultTeam),
     souls: { teams: isObject(souls.teams) ? souls.teams : {}, default: isObject(souls.default) ? souls.default : {} },
+    // Team model 3 (0.37.0) moves these keys; 0.36.x only warns (migrationProblems). `localTeams` is
+    // the workspace's answer, null without a workspace file (the standalone view has no workspace rules).
+    migration: {
+      soulKeys: ["teams", "default"].filter((k) => has(local?.souls, k)).map((k) => `souls.${k}`),
+      teamKeys: ["teams", "defaultTeam"].filter((k) => has(local, k)),
+      localTeams: isObject(workspace) ? workspace.localTeams === true : null,
+    },
   };
 }
 
@@ -130,6 +142,27 @@ const unconfiguredProblem = () => ({ code: "E_TEAM_UNCONFIGURED", severity: "fai
 const refusalProblem = (e) => ({ code: e.code, ...e.details, severity: "failure", message: e.message,
   fix: e.code === "E_TEAM_UNKNOWN" ? "declare the team (`oats teams add`), or remove the reference" : "add the label to the soul's teams (`oats soul teams … --add`), or clear its default (`--clear-default`)" });
 
+/** The fields of a team-model-3-migration problem other than code/severity/message/fix, as every
+ *  surface (oats teams, readiness, doctor) carries them. */
+export const MIGRATION_CODE = "team-model-3-migration";
+/**
+ * The team-model-3-migration warnings (0.36.x; 0.37.0 refuses what they name): `local-soul-teams` when
+ * oats-local.yaml has souls.teams / souls.default, `local-teams-closed` when it declares teams /
+ * defaultTeam and the workspace file does not say `localTeams: true` (never without a workspace file).
+ */
+export function migrationProblems(model) {
+  const m = model.migration, problems = [];
+  if (m.soulKeys.length) problems.push({ code: MIGRATION_CODE, severity: "warning", condition: "local-soul-teams", keys: [...m.soulKeys],
+    message: `oats-local.yaml ${m.soulKeys.join(", ")}: OATS 0.37.0 refuses ${m.soulKeys.length > 1 ? "these keys" : "this key"}; which teams a soul may join, and its default, move to souls: in oats-workspace.yaml`,
+    fix: `commit the same choices as souls: entries in oats-workspace.yaml ("*" or <member|package>/<soul>: { default, teams }), then remove ${m.soulKeys.join(" and ")} from oats-local.yaml` });
+  if (m.teamKeys.length && m.localTeams === false) problems.push(localTeamsClosedProblem(m.teamKeys));
+  return problems;
+}
+/** `local-teams-closed` for the oats-local.yaml `keys` found (doctor builds it from its offline read). */
+export const localTeamsClosedProblem = (keys) => ({ code: MIGRATION_CODE, severity: "warning", condition: "local-teams-closed", keys: [...keys],
+  message: `oats-local.yaml declares ${keys.join(", ")}, 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`,
+  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" });
+
 /**
  * Readiness problems. Without `key`: the deployment's (`oats teams`): collisions, unmapped shared
  * teams (a failure when it is `defaultTeam`), every unknown reference, every ineligible
@@ -141,11 +174,11 @@ export function teamProblems(model, { key = null, messaging = false } = {}) {
   if (key !== null) {
     let t;
     try { t = soulTeams(model, key); }
-    catch (e) { if (e.code === "E_TEAM_UNKNOWN" || e.code === "E_TEAM_NOT_ELIGIBLE") return [refusalProblem(e)]; throw e; }
+    catch (e) { if (e.code === "E_TEAM_UNKNOWN" || e.code === "E_TEAM_NOT_ELIGIBLE") return [refusalProblem(e), ...migrationProblems(model)]; throw e; }
     for (const r of t.teams) if (model.shared.has(r.label) && model.local.has(r.label)) problems.push(collisionProblem(r.label, model.shared.get(r.label), model.local.get(r.label)));
     for (const r of t.teams) if (r.team === null) problems.push(unmappedProblem(model.labels.get(r.label), r.default));
     if (messaging && t.defaultTeam === null) problems.push(unconfiguredProblem());
-    return problems;
+    return [...problems, ...migrationProblems(model)];
   }
   const labels = [...model.labels.keys()].sort(byCodepoint);
   for (const label of labels) if (model.shared.has(label) && model.local.has(label)) problems.push(collisionProblem(label, model.shared.get(label), model.local.get(label)));
@@ -159,7 +192,7 @@ export function teamProblems(model, { key = null, messaging = false } = {}) {
     try { soulTeams(model, k); } catch (e) { if (e.code === "E_TEAM_NOT_ELIGIBLE" && e.details.soul === k) problems.push(refusalProblem(e)); else if (e.code !== "E_TEAM_UNKNOWN") throw e; }
   }
   if (messaging && model.defaultTeam === null) problems.push(unconfiguredProblem());
-  return problems;
+  return [...problems, ...migrationProblems(model)];
 }
 
 /**

package/lib/workspace.mjs

@@ -243,8 +243,22 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
     const d = value.defaults;
     for (const slot of ["knowledge", "messaging", "tasks", "capabilities"]) fromProblems(remote, d[slot], `/defaults/${slot}`, problems, { here: false });
   }
+  sharedLabelProblems(value, problems);
   return withRemovedKeys(problems, value, REMOVED_KEYS.workspace);
 }
+/** Team model 3: every label `defaultTeam` and `souls:` name is a shared team of this same file, so an
+ *  unknown label is refused when the file is read, never at a spawn on someone else's machine. */
+function sharedLabelProblems(value, problems) {
+  const shared = new Set(isObject(value.teams) ? Object.keys(value.teams) : []);
+  const known = (label, path) => { if (typeof label === "string" && !shared.has(label)) problems.push({ path, message: `${show(label)} is not a shared team: declare it in teams: of this file` }); };
+  known(value.defaultTeam, "/defaultTeam");
+  if (isObject(value.souls)) for (const [key, entry] of Object.entries(value.souls)) {
+    if (!isObject(entry)) continue;
+    const at = `/souls/${pointerKey(key)}`;
+    known(entry.default, `${at}/default`);
+    if (Array.isArray(entry.teams)) entry.teams.forEach((label, i) => known(label, `${at}/teams/${i}`));
+  }
+}
 export function validateMembership(value) { return withRemovedKeys(validateAgainst(schemaFor("membership"), value), value, REMOVED_KEYS.membership); }
 
 /** Keys 0.30 removed (team model v2): each is a schema problem naming its replacement, in place of

package/package-catalog.json

@@ -3,7 +3,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v4.1.0",
+      "ref": "v4.1.1",
       "path": "oats-package"
     },
     "oats.aweb": {
@@ -33,7 +33,7 @@
     },
     "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "oats-framework/v1.4.1",
+      "ref": "oats-framework/v1.4.2",
       "path": "oats-package"
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.36.0",
+  "version": "0.36.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/skills/oats-getting-started/SKILL.md

@@ -60,8 +60,8 @@ members:
   - git:github.com/acme/agents          # the host is a member too
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.1                # bare versions resolve through the official catalog
-  oats.okf: v4.1.0
+  oats.framework: v1.4.2                # bare versions resolve through the official catalog
+  oats.okf: v4.1.1
 defaults:
   capabilities: { oats.core: { from: package } }
   knowledge: { oats.okf: { from: package } }