@awebai/oats 0.37.0 → 0.38.0

package/lib/resolve.mjs

@@ -57,7 +57,7 @@ import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { oatsError as baseOatsError } from "./errors.mjs";
 import * as defaultRemote from "./remote.mjs";
-import { BY_TEAM_REMOVED, reportRows, soulKeyOf, soulTeams, teamModel } from "./teams.mjs";
+import { BY_TEAM_REMOVED, reportRows, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
 import { bindRemote, packageProviding, readPackageManifests, validateLock } from "./packages.mjs";
 import { settingValueProblems } from "./capability-contract.mjs";
 import { memberRowByKey } from "./workspace.mjs";
@@ -617,9 +617,10 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
   assertSoulDiscovered(discovery, soulEntry);
   const definition = isObject(soulEntry.definition) ? soulEntry.definition : {};
   const soul = { name: soulEntry.name, repoKey: soulEntry.repoKey, commit: soulEntry.commit ?? null, path: soulEntry.path ?? null };
-  // Team model v2: the soul's teams HERE (the committed shared teams + oats-local.yaml). An unknown
-  // label (E_TEAM_UNKNOWN) or an ineligible souls.default (E_TEAM_NOT_ELIGIBLE) refuses the soul.
-  const soulTeamsHere = soulTeams(teamModel(discovery?.standalone === true ? null : workspace, local, { workspaceKey: discovery?.key ?? null }), soulKeyOf(soulEntry));
+  // Team model 3: the soul's teams HERE (the workspace's teams, defaultTeam and souls:, and the local teams
+  // it allows). An undeclared local default (E_TEAM_UNKNOWN) or local teams the workspace does not allow
+  // (E_WORKSPACE_SCHEMA local-teams-closed) refuse the soul.
+  const soulTeamsHere = soulTeams(teamModel(discovery?.standalone === true ? null : workspace, local, { workspaceKey: discovery?.key ?? null }), teamKeyOf(soulEntry));
 
   // Standalone: the soul's own repo only, workspace defaults unknown (decision 10).
   // What the soul turned off (feature desktop-facts): its own `off` over a lower layer, and a `<slot>: none`

package/lib/teams-verbs.mjs

@@ -1,18 +1,21 @@
 /**
- * The team model v2 verbs (docs/desktop-cli-api.md, `oats teams`, `oats soul teams`): CONFIG ONLY — they
- * never call a provider. Each reads the deployment's oats-local.yaml and the committed shared teams, and a
- * mutation rewrites oats-local.yaml in place (comments and every other key kept), after validating the
- * result: the local schema, and no label reference the write would leave unknown or ineligible.
+ * The team model 3 verbs (docs/desktop-cli-api.md, `oats teams`, `oats soul teams`): CONFIG ONLY — they
+ * never call a provider. Each reads the deployment's oats-local.yaml and the committed workspace file. The
+ * mutations (`oats teams add|remove|default`) edit the deployment's LOCAL teams and default, so they run only
+ * where the workspace allows local teams (`localTeams: true`, or the standalone view); they rewrite
+ * oats-local.yaml in place (comments and every other key kept), after validating the result: the local
+ * schema, and no label reference the write would leave unknown. A soul's teams are the workspace's
+ * `souls:`, edited by a PR to that file: `oats soul teams` only reads them.
  */
 import { readFileSync } from "node:fs";
 import YAML from "yaml";
 import { parseConfigData } from "./config-data.mjs";
 import { oatsError } from "./errors.mjs";
 import { validateLocal } from "./workspace.mjs";
-import { LOCAL_FILE, TEAM_ID_RE, pointerKey, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
+import { TEAM_ID_RE, localTeamsClosed, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
 import { writeFileAtomic } from "./packages.mjs";
 
-export const TEAMS_API = 1, SOUL_TEAMS_API = 1;
+export const TEAMS_API = 2, SOUL_TEAMS_API = 2;
 const LABEL_RE = /^[a-z0-9][a-z0-9._-]*$/;
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const byCodepoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
@@ -21,44 +24,46 @@ function fail(code, message, details) { const e = oatsError(code, message, detai
 /** Whether a messaging layer is active in this deployment: the workspace fills the messaging slot. */
 const messagingActive = (workspace) => isObject(workspace?.defaults?.messaging);
 
-/** `oats teams --json`. `ctx`: { deployment, local, workspace (the committed file, or null), workspaceKey }. */
+/** The default a soul without a `souls:` default gets here: the local one (where local teams are allowed),
+ *  else the workspace's → DefaultTeam | null. */
+function deploymentDefault(model) {
+  const [label, from] = model.localDefault !== null && model.labels.has(model.localDefault) ? [model.localDefault, "deployment"]
+    : model.workspaceDefault !== null ? [model.workspaceDefault, "workspace"] : [null, null];
+  return label === null || !model.labels.has(label) ? null : { label, team: model.labels.get(label).team, from };
+}
+
+/** `oats teams --json`. `ctx`: { deployment, local, workspace (the committed file, or null: standalone), workspaceKey,
+ *  soulKeys (the discovered souls' keys, for the `team-soul-unknown` typo guard; null when not known) }. */
 export function teamsDocument(ctx) {
   const model = teamModel(ctx.workspace, ctx.local, { workspaceKey: ctx.workspaceKey });
+  const def = deploymentDefault(model);
   const teams = [...model.labels.values()].sort((a, b) => byCodepoint(a.label, b.label))
-    .map((d) => ({ label: d.label, team: d.team, description: d.description, from: d.from, default: d.label === model.defaultTeam, at: d.at }));
+    .map((d) => ({ label: d.label, team: d.team, description: d.description, from: d.from, default: d.label === def?.label, at: d.at }));
   return {
-    teamsApi: TEAMS_API, deployment: ctx.deployment, defaultTeam: model.defaultTeam, teams,
-    souls: { teams: structuredClone(model.souls.teams), default: structuredClone(model.souls.default) },
-    problems: teamProblems(model, { messaging: messagingActive(ctx.workspace) }),
+    teamsApi: TEAMS_API, deployment: ctx.deployment, localTeams: model.localTeams, defaultTeam: def, teams,
+    souls: structuredClone(model.souls),
+    problems: teamProblems(model, { messaging: messagingActive(ctx.workspace), soulKeys: ctx.soulKeys ?? null }),
   };
 }
 
-/** `oats soul teams <soul>|'*' --json`: `key` is the soul's key ("*" for every soul), `soul` its name. */
+/** `oats soul teams <soul>|'*' --json`: `key` is the soul's key (teamKeyOf; "*" for the "*" pattern), `soul` its name. */
 export function soulTeamsDocument(ctx, { soul, key }) {
-  const model = teamModel(ctx.workspace, ctx.local, { workspaceKey: ctx.workspaceKey });
-  const t = soulTeams(model, key);
-  const list = (v) => (Array.isArray(v) ? [...v] : []);
-  return {
-    soulTeamsApi: SOUL_TEAMS_API, soul, key, defaultTeam: t.defaultTeam, teams: t.teams,
-    local: { teams: list(model.souls.teams[key]), default: key === "*" ? null : model.souls.default[key] ?? null },
-    all: list(model.souls.teams["*"]),
-  };
+  const t = soulTeams(teamModel(ctx.workspace, ctx.local, { workspaceKey: ctx.workspaceKey }), key);
+  return { soulTeamsApi: SOUL_TEAMS_API, soul, key, match: t.match, defaultMatch: t.defaultMatch, defaultTeam: t.defaultTeam, teams: t.teams };
 }
 
 /* ───────────────────────────── writing oats-local.yaml ─────────────────── */
 
 const clone = (v) => (v === undefined ? undefined : structuredClone(v));
-/** The four team keys of a local value, as plain data. */
+/** The two team keys of a local value, as plain data. */
 const teamState = (local) => ({
   teams: clone(isObject(local?.teams) ? local.teams : {}),
   defaultTeam: typeof local?.defaultTeam === "string" ? local.defaultTeam : null,
-  soulsTeams: clone(isObject(local?.souls?.teams) ? local.souls.teams : {}),
-  soulsDefault: clone(isObject(local?.souls?.default) ? local.souls.default : {}),
 });
 const modelOf = (ctx, local) => teamModel(ctx.workspace, local, { workspaceKey: ctx.workspaceKey });
-/** The refusals a state carries (unknown / ineligible references), keyed so a write can tell new ones. */
+/** The refusals a state carries (unknown references), keyed so a write can tell new ones. */
 const refusals = (ctx, local) => new Map(teamProblems(modelOf(ctx, local))
-  .filter((p) => p.code === "E_TEAM_UNKNOWN" || p.code === "E_TEAM_NOT_ELIGIBLE").map((p) => [`${p.code} ${p.at}`, p]));
+  .filter((p) => p.code === "E_TEAM_UNKNOWN").map((p) => [`${p.code} ${p.at}`, p]));
 const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 const readLocal = (ctx) => {
   const text = readFileSync(ctx.localPath, "utf8");
@@ -69,8 +74,7 @@ const readLocal = (ctx) => {
 
 /**
  * Edit `doc` from `before` to `next` SURGICALLY: only the entries that change are touched, so comments and
- * styles on everything else (inline comments on sibling entries, flow sequences) are kept. A map or list
- * left empty is removed, and so is an empty `souls`.
+ * styles on everything else (inline comments on sibling entries) are kept. A map left empty is removed.
  */
 function applyState(doc, before, next) {
   const map = (path, from, to, entry) => {
@@ -86,16 +90,6 @@ function applyState(doc, before, next) {
     for (const [k, v] of Object.entries(now)) if (!same(was[k], v)) doc.setIn([...path, k], v);
   });
   if (next.defaultTeam !== before.defaultTeam) { if (next.defaultTeam === null) doc.deleteIn(["defaultTeam"]); else doc.setIn(["defaultTeam"], next.defaultTeam); }
-  // A soul's list, item by item (its style — flow or block — and the other items' comments stay).
-  map(["souls", "teams"], before.soulsTeams, next.soulsTeams, (path, was, now) => {
-    const seq = doc.getIn(path, true);
-    if (!Array.isArray(was) || !YAML.isSeq(seq)) { doc.setIn(path, now); return; }
-    seq.items = seq.items.filter((item) => now.includes(YAML.isScalar(item) ? item.value : item));
-    for (const label of now) if (!was.includes(label)) seq.items.push(doc.createNode(label));
-  });
-  map(["souls", "default"], before.soulsDefault, next.soulsDefault, (path, _was, now) => doc.setIn(path, now));
-  const souls = doc.get("souls");
-  if (YAML.isMap(souls) && souls.items.length === 0) doc.delete("souls");
 }
 
 /**
@@ -103,14 +97,18 @@ function applyState(doc, before, next) {
  * refusal; both come from the file AS IT IS NOW (re-read here, never the command's startup snapshot), so
  * two verbs running together cannot drop each other's change: the write is compare-and-swap — when the
  * file changed after this read, the edit is redone on the new content (a few times, then E_LOCAL_CHANGED).
- * `check(local)` may refuse the result before anything is written. → { changed, local } (the value now).
+ * `verb` names the command and `writes` the keys it adds, for the refusal where the workspace does not
+ * allow local teams (local-teams-closed); a verb that only takes local teams away (`writes: null`) runs
+ * there too, since it moves the file toward what the workspace allows. → { changed, local } (the value now).
  */
-function editLocal(ctx, mutate, { check } = {}) {
+function editLocal(ctx, { verb, writes }, mutate) {
   for (let attempt = 0; attempt < 5; attempt++) {
     const { text, doc, local: current } = readLocal(ctx);
+    const model = modelOf(ctx, current);
+    if (model.localTeams === false && writes !== null) throw localTeamsClosed(writes, { verb });
     const before = teamState(current);
     const next = teamState(current);
-    mutate(next, modelOf(ctx, current));
+    mutate(next, model);
     if (same(next, before)) return { changed: false, local: current };
     applyState(doc, before, next);
     const out = doc.toString();
@@ -119,7 +117,6 @@ function editLocal(ctx, mutate, { check } = {}) {
     if (problems.length) throw fail("E_WORKSPACE_SCHEMA", `the rewritten oats-local.yaml would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`, { problems });
     const had = refusals(ctx, current);
     for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
-    if (check) check(local);
     if (readFileSync(ctx.localPath, "utf8") !== text) continue; // changed under us: redo on the new content
     writeFileAtomic(ctx.localPath, out);
     return { changed: true, local };
@@ -136,7 +133,7 @@ export function teamsAdd(ctx, label, { team, description } = {}) {
   assertLabel(label);
   if (typeof team !== "string" || !team.trim()) throw fail("E_BAD_ARGS", "oats teams add needs --team <provider team id>", { label });
   if (!TEAM_ID_RE.test(team.trim())) throw fail("E_BAD_ARGS", `${JSON.stringify(team)} is not a team id: it must match ${TEAM_ID_RE.source} (a letter or digit first; no whitespace or control characters; at most 256 characters)`, { label, team });
-  return editLocal(ctx, (s, model) => {
+  return editLocal(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
     if (model.labels.has(label)) {
       const from = model.labels.get(label).from;
       throw fail("E_TEAM_EXISTS", `team ${label} is already declared (${from === "shared" ? "shared, in oats-workspace.yaml" : "local, in oats-local.yaml"})${from === "local" ? ": remove it first (`oats teams remove`) to redefine it" : ""}`, { label, from });
@@ -147,9 +144,10 @@ export function teamsAdd(ctx, label, { team, description } = {}) {
   });
 }
 
-/** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). */
+/** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). Allowed where the workspace
+ *  does not allow local teams: removing them is the last step of committing them there. */
 export function teamsRemove(ctx, label) {
-  return editLocal(ctx, (s, model) => {
+  return editLocal(ctx, { verb: "oats teams remove", writes: null }, (s, model) => {
     if (!model.local.has(label)) {
       if (model.shared.has(label)) throw fail("E_TEAM_SHARED", `team ${label} is shared (declared in oats-workspace.yaml): it is edited by a PR to that file, never removed here`, { label, at: model.shared.get(label).at });
       throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared`, { label });
@@ -157,39 +155,15 @@ export function teamsRemove(ctx, label) {
     // A label also declared in the committed file still resolves after the local copy goes (the
     // collision's fix): its references stay valid, so only a purely local label must be unreferenced.
     const usedBy = model.shared.has(label) ? [] : teamReferences(model, label);
-    if (usedBy.length) throw fail("E_TEAM_IN_USE", `team ${label} is still referenced (${usedBy.join(", ")}): remove the references first (\`oats teams default\`, \`oats soul teams … --remove ${label}\`)`, { label, usedBy });
+    if (usedBy.length) throw fail("E_TEAM_IN_USE", `team ${label} is still referenced (${usedBy.join(", ")}): choose another default first (\`oats teams default\`)`, { label, usedBy });
     delete s.teams[label];
   });
 }
 
 /** `oats teams default <label>`: a label of either file. */
 export function teamsDefault(ctx, label) {
-  return editLocal(ctx, (s, model) => {
+  return editLocal(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
     if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
     s.defaultTeam = label;
   });
 }
-
-/**
- * `oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <l> | --clear-default]`.
- * `key` is the soul's key ("*" for every soul). → { changed, local }.
- */
-export function soulTeamsEdit(ctx, key, { add = [], remove = [], setDefault = null, clearDefault = false } = {}) {
-  if (key === "*" && (setDefault !== null || clearDefault)) throw fail("E_BAD_ARGS", "a default is per soul: --default / --clear-default need a soul, not '*' (the deployment's default is `oats teams default`)", { soul: key });
-  if (setDefault !== null && clearDefault) throw fail("E_BAD_ARGS", "choose --default <label> or --clear-default, not both");
-  // --default must name one of the soul's teams after the write.
-  const check = setDefault === null ? undefined : (local) => {
-    try { soulTeams(modelOf(ctx, local), key); }
-    catch (e) { if (e.code === "E_TEAM_NOT_ELIGIBLE") throw fail("E_TEAM_NOT_ELIGIBLE", `${e.message}; nothing was written`, { soul: key, label: setDefault, at: `${LOCAL_FILE}#/souls/default/${pointerKey(key)}` }); throw e; }
-  };
-  return editLocal(ctx, (s, model) => {
-    for (const label of [...add, ...remove, ...(setDefault !== null ? [setDefault] : [])]) {
-      if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
-    }
-    const list = Array.isArray(s.soulsTeams[key]) ? s.soulsTeams[key] : [];
-    const next = [...list.filter((l) => !remove.includes(l)), ...add.filter((l) => !list.includes(l) && !remove.includes(l))].filter((l, i, a) => a.indexOf(l) === i);
-    if (next.length) s.soulsTeams[key] = next; else delete s.soulsTeams[key];
-    if (clearDefault) delete s.soulsDefault[key];
-    if (setDefault !== null) s.soulsDefault[key] = setDefault;
-  }, { check });
-}

package/lib/teams.mjs

@@ -1,26 +1,29 @@
 /**
- * Team model v2 (docs/design/2026-09-27-team-model-v2.md, option B), pure.
+ * Team model 3 (docs/design/2026-10-02-team-model-3.md, awebai/oats#484), pure.
  *
  * Where teams live:
- *   - the committed oats-workspace.yaml `teams.<label> = { description?, team? }`: SHARED teams (edited
- *     by PR). A shared team without `team` is declared but not yet created (unmapped);
- *   - the deployment's oats-local.yaml `teams.<label> = { team, description? }`: LOCAL teams, plus
- *     `defaultTeam: <label>`, `souls.teams: { "*" | <soul key>: [labels] }` and
- *     `souls.default: { <soul key>: <label> }`.
- * A soul key is the soul's bare name, or `<package>/<soul>` for a package soul.
+ *   - the committed oats-workspace.yaml: SHARED teams `teams.<label> = { description?, team? }` (a shared
+ *     team without `team` is declared but not yet created: unmapped); `defaultTeam: <label>`, the
+ *     workspace's fallback default; `localTeams: true|false` (absent: false), whether deployments may
+ *     declare their own teams; and `souls: { <pattern>: { default?, teams?: [labels] | "any" } }`;
+ *   - the deployment's oats-local.yaml, only when the workspace says `localTeams: true` (or there is no
+ *     workspace file: the standalone view): LOCAL teams `teams.<label> = { team, description? }` and
+ *     `defaultTeam: <label>`. Otherwise they are refused (E_WORKSPACE_SCHEMA reason local-teams-closed).
+ * A soul's key is its qualified name (teamKeyOf): `<package>/<soul>` or `<member>/<soul>`.
  *
- * Resolution: labels = shared ∪ local (a label in both is `team-label-collision`; the SHARED definition
- * wins). defaultOf(soul) = souls.default[soul] ?? defaultTeam; a soul's teams = {defaultOf} ∪
- * souls.teams["*"] ∪ souls.teams[soul]. An undeclared label the soul reaches is E_TEAM_UNKNOWN; a
- * souls.default outside the soul's teams is E_TEAM_NOT_ELIGIBLE.
+ * Resolution: a `souls:` pattern is the soul's key, then `<member|package>/*`, then "*"; the most specific
+ * one that exists gives the soul's teams outright (no merging), and the most specific one that sets a
+ * `default` gives its default. Default, in order: that `default` (from "soul"); else the local
+ * `defaultTeam` when local teams are allowed ("deployment"); else the workspace's `defaultTeam`
+ * ("workspace"); else none. A soul's teams: its default, plus its pattern's `teams` ("any": every shared
+ * team), plus every local team when local teams are allowed. A label in both files is
+ * `team-label-collision` (the SHARED definition wins). Workspace labels are validated when the file is
+ * read (lib/workspace.mjs); a local default no file declares is E_TEAM_UNKNOWN.
  *
- * 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.38.0, awebai/oats#484) moves these choices into the committed workspace file. 0.36.x and
- * 0.37.x validate its keys (lib/workspace.mjs) without applying them, and warn about what 0.38.0 will refuse
- * (migrationProblems: team-model-3-migration).
+ * Rows (docs/desktop-cli-api.md, Teams): TeamRow { label, team, default, from: shared|local, via }, `via`
+ * ⊂ ["default", "workspace", "local"] in that order (why the soul may join it); 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: soul|deployment|workspace } | null.
  */
 import { oatsError } from "./errors.mjs";
 
@@ -41,12 +44,16 @@ export const LOCAL_FILE = "oats-local.yaml";
  *  validates its own id shape. Keep equal to docs/oats-{local,workspace}.schema.json. */
 export const TEAM_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$/;
 /** What 0.30 removed, named by the schema problems that replace them. */
-export const TEAM_MEMBERSHIP_MOVED = "team membership is local since 0.30: `oats soul teams`";
+export const TEAM_MEMBERSHIP_MOVED = "a soul's teams are decided by souls: in oats-workspace.yaml (team model 3, OATS 0.38.0)";
 export const BY_TEAM_REMOVED = "byTeam was removed in 0.30: a team's provider id is teams.<label>.team (oats-workspace.yaml for a shared team, oats-local.yaml for a local one)";
 
 const UNMAPPED_FIX = "its owner runs `oats aweb setup`, then commits the id";
+const CLOSED_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";
 
-/** The deployment's teams from the committed workspace and oats-local.yaml (either may be null). */
+/**
+ * The deployment's teams from the committed workspace and oats-local.yaml (either may be null; a null
+ * workspace is the standalone view, which has no workspace rules).
+ */
 export function teamModel(workspace, local, { workspaceKey = null } = {}) {
   const shared = new Map(), localTeams = new Map();
   for (const [label, def] of Object.entries(isObject(workspace?.teams) ? workspace.teams : {})) {
@@ -56,76 +63,124 @@ export function teamModel(workspace, local, { workspaceKey = null } = {}) {
   for (const [label, def] of Object.entries(isObject(local?.teams) ? local.teams : {})) {
     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);
+  const standalone = !isObject(workspace);
+  const allowed = standalone || workspace.localTeams === true;
+  const localKeys = ["teams", "defaultTeam"].filter((k) => isObject(local) && Object.hasOwn(local, 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.38.0) moves these keys; 0.36.x and 0.37.x only warn (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,
-    },
+    // true | false (the workspace's answer), null in the standalone view.
+    localTeams: standalone ? null : allowed,
+    // The oats-local.yaml keys the workspace refuses (local-teams-closed); [] when allowed.
+    closedKeys: allowed ? [] : localKeys,
+    localDefault: allowed ? str(local?.defaultTeam) : null,
+    workspaceDefault: standalone ? null : str(workspace.defaultTeam),
+    souls: !standalone && isObject(workspace.souls) ? workspace.souls : {},
+    soulsAt: `${workspaceKey ? `${workspaceKey}:` : ""}oats-workspace.yaml#/souls`,
   };
 }
 
-/** The key a soul has in souls.teams / souls.default. */
+/** The key a soul has in oats-local.yaml souls.launch: its bare name, or `<package>/<soul>` for a package soul. */
 export function soulKeyOf(soulEntry) {
   return typeof soulEntry?.package === "string" && typeof soulEntry.qualifiedName === "string" ? soulEntry.qualifiedName : soulEntry.name;
 }
+/** A member's name: the last segment of its repo key, without `.git` (`souls.disabled` and team keys use it). */
+export function memberNameOf(key) {
+  return String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/i, "") || String(key);
+}
+/** A soul's key in the workspace's `souls:` (team model 3): `<package>/<soul>` for a package soul,
+ *  `<member>/<soul>` for any other (its repository's name), as `souls.disabled` qualifies it. */
+export function teamKeyOf(soulEntry) {
+  if (typeof soulEntry?.package === "string") return typeof soulEntry.qualifiedName === "string" ? soulEntry.qualifiedName : `${soulEntry.package}/${soulEntry.name}`;
+  return `${memberNameOf(soulEntry?.repoKey ?? "")}/${soulEntry?.name}`;
+}
+
+/**
+ * What a team model v2 oats-local.yaml (`souls.teams`, `souls.default`) gave each soul, as the workspace
+ * `souls:` that gives the same (0.38.0's removed-key refusal prints it): "*" keeps `souls.teams["*"]`; each
+ * soul named gets its default and "*" ∪ its own list, since patterns never merge. A bare (member) soul
+ * name becomes `<member>/<soul>`, for the operator to qualify. → { souls } | null when neither key is set.
+ */
+export function soulsReplacement(local) {
+  const teams = isObject(local?.souls?.teams) ? local.souls.teams : null, defaults = isObject(local?.souls?.default) ? local.souls.default : null;
+  if (teams === null && defaults === null) return null;
+  const star = labelsOf(teams?.["*"]);
+  const souls = {};
+  if (star.length) souls["*"] = { teams: star };
+  const named = [...Object.keys(teams ?? {}), ...Object.keys(defaults ?? {})].filter((k, i, a) => k !== "*" && a.indexOf(k) === i);
+  for (const k of named) {
+    const def = str(defaults?.[k]);
+    const list = [...star, ...labelsOf(teams?.[k])].filter((l, i, a) => a.indexOf(l) === i);
+    souls[k.includes("/") ? k : `<member>/${k}`] = { ...(def !== null ? { default: def } : {}), teams: list };
+  }
+  return { souls };
+}
+
+/** Every discovered soul's key (teamKeyOf): confirmed members' (and a standalone view's own), external and
+ *  package souls. The typo guard (`team-soul-unknown`) checks the workspace's `souls:` keys against it. */
+export function discoveredTeamKeys(discovery) {
+  const keys = new Set();
+  for (const m of discovery?.members || []) if (m.confirmed || (discovery.standalone === true && m.key === discovery.key)) for (const s of m.souls || []) keys.add(teamKeyOf(s));
+  for (const x of discovery?.external || []) if (x?.soul) keys.add(teamKeyOf({ ...x.soul, repoKey: x.soul.repoKey ?? x.key }));
+  for (const s of discovery?.packageSouls || []) keys.add(teamKeyOf(s));
+  return keys;
+}
+
+/** The `souls:` patterns that apply to `key`, most specific first. */
+const patternsOf = (key) => (key === "*" ? ["*"] : [key, `${key.slice(0, key.lastIndexOf("/"))}/*`, "*"]);
 
 const unknown = (label, at) => fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared (${at}): declare it with \`oats teams add\`, or in oats-workspace.yaml teams: for a shared team`, { label, at });
+const closedMessage = (keys) => `${LOCAL_FILE} declares ${keys.join(", ")}, but oats-workspace.yaml does not allow local teams (localTeams: true): ${CLOSED_FIX}`;
+/** Whether `e` refuses a soul's TEAMS (an undeclared label, or local teams the workspace does not allow):
+ *  readiness reports it as a team item, a home falls back to its recorded teams. */
+export const isTeamRefusal = (e) => e?.code === "E_TEAM_UNKNOWN" || (e?.code === "E_WORKSPACE_SCHEMA" && e?.details?.reason === "local-teams-closed");
+/** Whether `e` refuses oats-local.yaml for the team keys 0.38.0 removed (`souls.teams` / `souls.default`):
+ *  a reader that otherwise falls back to a home's recorded teams must answer it instead. */
+export const isRemovedTeamKeys = (e) => e?.code === "E_WORKSPACE_SCHEMA" && Array.isArray(e?.details?.problems)
+  && e.details.problems.some((p) => p?.reason === "removed-key" && /^\/souls\/(teams|default)$/.test(p.path));
+/** The refusal of local teams the workspace does not allow (E_WORKSPACE_SCHEMA reason local-teams-closed). */
+export const localTeamsClosed = (keys, { verb = null } = {}) => fail("E_WORKSPACE_SCHEMA",
+  verb ? `${verb} writes ${keys.join(", ")} in ${LOCAL_FILE}, but oats-workspace.yaml does not allow local teams (localTeams: true): ${CLOSED_FIX}` : closedMessage(keys),
+  { reason: "local-teams-closed", path: LOCAL_FILE, keys: [...keys] });
 
 /**
- * One soul's teams here (key "*": the deployment default + souls.teams["*"]).
- * → { key, defaultTeam: DefaultTeam | null, teams: [TeamRow + via] } | throws E_TEAM_UNKNOWN / E_TEAM_NOT_ELIGIBLE.
- * `via` ⊂ ["default", "*", "soul"], in that order: why the soul has the team.
+ * One soul's teams here (key "*": what the "*" pattern gives).
+ * → { key, match, defaultMatch, defaultTeam: DefaultTeam | null, teams: [TeamRow] }; `match` / `defaultMatch`
+ * are the `souls:` keys its teams / its default come from (null: none). Throws E_WORKSPACE_SCHEMA
+ * (local-teams-closed) / E_TEAM_UNKNOWN.
  */
 export function soulTeams(model, key) {
-  const known = (label, at) => { if (!model.labels.has(label)) throw unknown(label, at); };
-  if (model.defaultTeam !== null) known(model.defaultTeam, `${LOCAL_FILE}#/defaultTeam`);
-  const star = labelsOf(model.souls.teams["*"]);
-  star.forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/*/${i}`));
-  const own = key === "*" ? [] : labelsOf(model.souls.teams[key]);
-  own.forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/${pointerKey(key)}/${i}`));
-  const override = key === "*" ? null : str(model.souls.default[key]);
-  if (override !== null) {
-    const at = `${LOCAL_FILE}#/souls/default/${pointerKey(key)}`;
-    known(override, at);
-    if (override !== model.defaultTeam && !star.includes(override) && !own.includes(override)) {
-      throw fail("E_TEAM_NOT_ELIGIBLE", `souls.default.${key} is ${JSON.stringify(override)}, which is not one of ${key}'s teams here — add it first (\`oats soul teams ${key} --add ${override}\`)`, { soul: key, label: override, at });
-    }
-  }
-  const defaultLabel = override ?? model.defaultTeam;
+  if (model.closedKeys.length) throw localTeamsClosed(model.closedKeys);
+  const patterns = patternsOf(key);
+  const match = patterns.find((p) => isObject(model.souls[p])) ?? null;
+  const defaultMatch = patterns.find((p) => isObject(model.souls[p]) && typeof model.souls[p].default === "string") ?? null;
+  if (model.localDefault !== null && !model.labels.has(model.localDefault)) throw unknown(model.localDefault, `${LOCAL_FILE}#/defaultTeam`);
+  const [defaultLabel, from] = defaultMatch !== null ? [model.souls[defaultMatch].default, "soul"]
+    : model.localDefault !== null ? [model.localDefault, "deployment"]
+    : model.workspaceDefault !== null ? [model.workspaceDefault, "workspace"] : [null, null];
   const via = new Map();
-  const add = (label, why) => { const v = via.get(label) ?? []; if (!v.includes(why)) v.push(why); via.set(label, v); };
+  const add = (label, why) => { if (!model.labels.has(label)) return; const v = via.get(label) ?? []; if (!v.includes(why)) v.push(why); via.set(label, v); };
   if (defaultLabel !== null) add(defaultLabel, "default");
-  for (const l of star) add(l, "*");
-  for (const l of own) add(l, "soul");
+  const listed = match === null ? [] : model.souls[match].teams === "any" ? [...model.shared.keys()] : labelsOf(model.souls[match].teams);
+  for (const l of listed) add(l, "workspace");
+  if (model.localTeams !== false) for (const l of model.local.keys()) add(l, "local");
   const teams = [...via].map(([label, v]) => {
     const d = model.labels.get(label);
     return { label, team: d.team, default: label === defaultLabel, from: d.from, via: v };
   }).sort((a, b) => (b.default - a.default) || byCodepoint(a.label, b.label));
-  const defaultTeam = defaultLabel === null ? null : { label: defaultLabel, team: model.labels.get(defaultLabel).team, from: override !== null ? "soul" : "deployment" };
-  return { key, defaultTeam, teams };
+  const defaultTeam = defaultLabel === null || !model.labels.has(defaultLabel) ? null : { label: defaultLabel, team: model.labels.get(defaultLabel).team, from };
+  return { key, match, defaultMatch, defaultTeam, teams };
 }
 
-/** TeamRows as the reports carry them (unmapped included, no `via`). */
-export const reportRows = (teams) => (teams || []).map(({ label, team, default: d, from }) => ({ label, team, default: d, from }));
+/** TeamRows as the reports carry them (unmapped included). A row a home recorded before team model 3 has
+ *  no `via`, and is reported as recorded (its eligibility is not guessed). */
+export const reportRows = (teams) => (teams || []).map(({ label, team, default: d, from, via }) => ({ label, team, default: d, from, ...(Array.isArray(via) ? { via: [...via] } : {}) }));
 /** TeamRows as OATS_TEAMS and instance.json carry them: mapped only. */
 export const envRows = (teams) => reportRows(teams).filter((r) => r.team !== null);
 
 /** Every reference to `label` in oats-local.yaml, in written order (`oats teams remove` refuses on any). */
 export function teamReferences(model, label) {
-  const refs = [];
-  if (model.defaultTeam === label) refs.push("defaultTeam");
-  for (const [key, list] of Object.entries(model.souls.teams)) if (labelsOf(list).includes(label)) refs.push(`souls.teams:${key}`);
-  for (const [key, l] of Object.entries(model.souls.default)) if (l === label) refs.push(`souls.default:${key}`);
-  return refs;
+  return model.localDefault === label ? ["defaultTeam"] : [];
 }
 
 const collisionProblem = (label, shared, local) => ({
@@ -135,64 +190,48 @@ const collisionProblem = (label, shared, local) => ({
   message: `team ${label} is declared in both oats-workspace.yaml (shared) and oats-local.yaml (local); the shared definition wins`,
   fix: "rename the local label in oats-local.yaml",
 });
-const unmappedProblem = (d, isDefault) => isDefault
-  ? { code: "team-unmapped", label: d.label, default: true, severity: "failure", at: d.at, message: `the default team ${d.label} has no provider id yet`, fix: `${UNMAPPED_FIX}; or choose another default with \`oats teams default\`` }
+/** Where another default is chosen: where this one comes from (`t` is soulTeams' answer). */
+const otherDefault = (t) => t.defaultTeam?.from === "soul" ? `in the souls: entry ${t.defaultMatch} of oats-workspace.yaml`
+  : t.defaultTeam?.from === "workspace" ? "defaultTeam in oats-workspace.yaml" : "with `oats teams default`";
+const unmappedProblem = (d, t) => d.label === t.defaultTeam?.label
+  ? { code: "team-unmapped", label: d.label, default: true, severity: "failure", at: d.at, message: `the default team ${d.label} has no provider id yet`,
+    fix: `${UNMAPPED_FIX}; or choose another ${t.defaultTeam.from === "workspace" ? "" : "default "}${otherDefault(t)}` }
   : { code: "team-unmapped", label: d.label, default: false, severity: "warning", at: d.at, message: `shared team ${d.label} has no provider id yet`, fix: UNMAPPED_FIX };
-const unconfiguredProblem = () => ({ code: "E_TEAM_UNCONFIGURED", severity: "failure", message: "no teams configured: run `oats aweb setup`", fix: "run `oats aweb setup` (it creates the teams and sets the default), or `oats teams add <label> --team <id>`" });
+/** No default: committed in the workspace file, or recorded here where local teams are allowed (the standalone
+ *  view has only the local way). */
+const unconfiguredProblem = (model) => ({ code: "E_TEAM_UNCONFIGURED", severity: "failure", message: "no teams configured: run `oats aweb setup`",
+  fix: model.localTeams === null ? "run `oats aweb setup` (it creates the teams and sets the default), or `oats teams add <label> --team <id>`"
+    : `run \`oats aweb setup\` to create a team, then commit it in oats-workspace.yaml as defaultTeam (or as a soul's default in souls:)${model.localTeams ? ", or record it here with `oats teams add <label> --team <id>`" : ""}` });
 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 and 0.37.x; 0.38.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.38.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.38.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" });
+  fix: "declare the team (`oats teams add`), or choose another default (`oats teams default`)" });
+const soulUnknownProblem = (key, at) => ({ code: "team-soul-unknown", severity: "warning", key, at,
+  message: `souls: ${key} names no soul of this workspace (a pattern is "*" or <member|package>/*)`, fix: "correct the key to a soul's qualified name (oats souls lists them), or remove it" });
+/** local-teams-closed as a problem (oats teams, readiness, doctor): the refusal's facts, never thrown. */
+export const localTeamsClosedProblem = (keys) => ({ code: "E_WORKSPACE_SCHEMA", severity: "failure", condition: "local-teams-closed", path: LOCAL_FILE, keys: [...keys],
+  message: closedMessage(keys), fix: CLOSED_FIX });
 
 /**
- * Readiness problems. Without `key`: the deployment's (`oats teams`): collisions, unmapped shared
- * teams (a failure when it is `defaultTeam`), every unknown reference, every ineligible
- * souls.default. With `key`: only what concerns that soul (`default` marks ITS default).
- * `messaging`: a messaging layer is active, so no default is E_TEAM_UNCONFIGURED.
+ * Readiness problems. Without `key`: the deployment's (`oats teams`): collisions, unmapped shared teams
+ * (a failure when it is the default a soul without a souls: default gets), an unknown local default.
+ * With `key`: only what concerns that soul (`default` marks ITS default). Local teams the workspace does
+ * not allow are the one problem either way. `messaging`: a messaging layer is active, so no default is
+ * E_TEAM_UNCONFIGURED. `soulKeys` (discoveredTeamKeys; null when the souls are not known): a `souls:` key
+ * that is neither a pattern nor one of them is `team-soul-unknown` (a typo guard, either way).
  */
-export function teamProblems(model, { key = null, messaging = false } = {}) {
+export function teamProblems(model, { key = null, messaging = false, soulKeys = null } = {}) {
+  if (model.closedKeys.length) return [localTeamsClosedProblem(model.closedKeys)];
   const problems = [];
-  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), ...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, ...migrationProblems(model)];
-  }
-  const labels = [...model.labels.keys()].sort(byCodepoint);
+  // An undeclared local default is reported; the rest is judged as if it were not set.
+  if (model.localDefault !== null && !model.labels.has(model.localDefault)) problems.push(refusalProblem(unknown(model.localDefault, `${LOCAL_FILE}#/defaultTeam`)));
+  const t = soulTeams(problems.length ? { ...model, localDefault: null } : model, key ?? "*");
+  const labels = key !== null ? t.teams.map((r) => r.label) : [...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)));
-  for (const label of labels) { const d = model.labels.get(label); if (d.team === null) problems.push(unmappedProblem(d, label === model.defaultTeam)); }
-  const known = (label, at) => { if (!model.labels.has(label)) problems.push(refusalProblem(unknown(label, at))); };
-  if (model.defaultTeam !== null) known(model.defaultTeam, `${LOCAL_FILE}#/defaultTeam`);
-  for (const [k, list] of Object.entries(model.souls.teams)) labelsOf(list).forEach((l, i) => known(l, `${LOCAL_FILE}#/souls/teams/${pointerKey(k)}/${i}`));
-  for (const [k, l] of Object.entries(model.souls.default)) if (typeof l === "string") known(l, `${LOCAL_FILE}#/souls/default/${pointerKey(k)}`);
-  for (const [k, l] of Object.entries(model.souls.default)) {
-    if (typeof l !== "string" || !model.labels.has(l)) continue;
-    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; }
+  for (const label of labels) { const d = model.labels.get(label); if (d.team === null) problems.push(unmappedProblem(d, t)); }
+  if (messaging && t.defaultTeam === null && model.localDefault === null) problems.push(unconfiguredProblem(model));
+  if (soulKeys !== null) for (const k of Object.keys(model.souls).sort(byCodepoint)) {
+    if (k !== "*" && !k.endsWith("/*") && !soulKeys.has(k)) problems.push(soulUnknownProblem(k, `${model.soulsAt}/${pointerKey(k)}`));
   }
-  if (messaging && model.defaultTeam === null) problems.push(unconfiguredProblem());
-  return [...problems, ...migrationProblems(model)];
+  return problems;
 }
 
 /**