@awebai/oats 0.30.0 → 0.30.2

package/bin/oats.mjs

@@ -2823,7 +2823,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "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"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "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", "preview-composed-from"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);

package/docs/capabilities.md

@@ -28,7 +28,7 @@ A capability lives in one of two kinds of source:
 A soul says `capabilities: { <name>: { from: here | <repo key> | package } }`
 (or `off`); the workspace supplies defaults. At spawn every resolved
 capability is **copied whole** into the instance (`<home>/.oats/modules/<name>/`,
-skills into `<home>/.agents/skills/<name>/`), and the instance's `AGENTS.md` is
+its skills flat into `<home>/.agents/skills/<skill>/`), and the instance's `AGENTS.md` is
 generated without changing the canonical soul. Nothing is installed or
 activated at a deployment.
 
@@ -237,8 +237,8 @@ live.
 
 Every spawned instance gets a **full copy** of each capability its soul
 resolved to, under `<home>/.oats/modules/<capability>/` (manifest, `bin/`,
-injects, skills), and those skills under
-`<home>/.agents/skills/<capability>/<skill>/`. Its generated `AGENTS.md` is the
+injects, skills), and those skills flat under `<home>/.agents/skills/<skill>/`
+beside the soul's own, one level deep where harnesses discover them. Its generated `AGENTS.md` is the
 soul's `AGENTS.md`, the kernel and work-mode blocks, then each module's inject
 in name order. Two composed skills with one name fail the spawn
 (`E_SKILL_DUPLICATE`). The harness then starts normally, with its own skill

package/docs/design/2026-09-23-workspace-module-contracts.md

@@ -286,7 +286,8 @@ shims that throw `E_REMOVED { name, contract }`, pointing at this record.
    must match the lock's commit (`E_MATERIALIZE_INTEGRITY { why: "lock" }`); an unknown repo is
    `E_MATERIALIZE_SOURCE`.
 2. The copy's digest must equal the fetch's and any `module.digest` (`E_MATERIALIZE_INTEGRITY`).
-3. Copy skills whole to `<home>/.agents/skills/<name>/<skill>/`.
+3. Copy skills whole to `<home>/.agents/skills/<skill>/`, flat (0.30.2; the grouped
+   `<name>/<skill>/` layout this section first specified hid every skill from the harnesses).
 4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) + kernel blocks + module
    injects; operating guidance comes from a module such as `oats.core`. Keep `CLAUDE.md → AGENTS.md`
    and `.claude/skills → ../.agents/skills`.

package/docs/desktop-cli-api.md

@@ -36,7 +36,8 @@ 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-2","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
+             "preview-composed-from"],
  "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,6 +89,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `automations` | workspace triggers and schedules; `oats automations refresh` | `automationsApi: 1` |
 | `desktop-facts` | the facts under [Desktop facts](#desktop-facts-feature-desktop-facts-oats-0290) | |
 | `launch-preference` | soul and local launch preferences; `launch`, `launchCurrent`, `launchFrom`; `--reselect-launch`; `key` on soul and agent rows ([Launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) | |
+| `preview-composed-from` | `composedFrom` on preview `modules[]` ([Composition](#the-preview)) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -591,7 +593,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.0.4","ref":"v4.0.4"}}],
+              "capabilities":["oats.okf"],"souls":[],"latest":{"version":"4.0.5","ref":"v4.0.5"}}],
  "declaredPackages":["oats.framework","oats.okf"],"unsynced":["oats.framework"],"stale":[],
  "external":[{"source":"git:github.com/oss/experts@3c606e09…","soul":"security-reviewer"}],
  "problems":[],"warnings":[],
@@ -642,8 +644,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.0.4","kind":"package","package":"oats.okf",
-    "version":"4.0.4","repoKey":"github.com/awebai/oats-okf","commit":"a4ccca02…","teams":null,"defaultTeam":null,"private":false,
+   {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.0.5","kind":"package","package":"oats.okf",
+    "version":"4.0.5","repoKey":"github.com/awebai/oats-okf","commit":"26d8216f…","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/…)"}}],
@@ -1073,9 +1075,9 @@ it to a temporary copy (`soulFetched: true`).
 ```json
 {"modules":[
    {"name":"nw-tools","from":{"kind":"member","repoKey":"github.com/nw/agents","commit":"66566512…"},"layer":null,"private":false,"declares":[],
-    "changedSince":{"instance":"rm-2","was":"45b86f64…"}},
+    "changedSince":{"instance":"rm-2","was":"45b86f64…"},"composedFrom":"soul"},
    {"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
-    "layer":"knowledge","private":false,"declares":["state-dir"],"changedSince":false}],
+    "layer":"knowledge","private":false,"declares":["state-dir"],"changedSince":false,"composedFrom":"workspace"}],
  "teams":[{"label":"eng","team":"eng:nw.aweb.ai","default":true,"from":"shared"}],
  "defaultTeam":{"label":"eng","team":"eng:nw.aweb.ai","from":"soul"},
  "resolution":"abacbdb5a7975098d77007c8","declRevision":"068a0d3f1311a9e84e9aff2e","payloadRevision":"81a368006c610194aa35dbe0",
@@ -1124,9 +1126,18 @@ it to a temporary copy (`soulFetched: true`).
 
 **Composition.**
 - `modules[]` (feature `instance-modules`): `{name, from, layer, private,
-  declares, changedSince}`; `from` is what `instance.json` will record.
-  `changedSince` is `null` (no previous instance), `false` (unchanged since the
-  newest one) or `{instance, was}`.
+  declares, changedSince, composedFrom}`; `from` is what `instance.json` will
+  record. `changedSince` is `null` (no previous instance), `false` (unchanged
+  since the newest one) or `{instance, was}`.
+- `composedFrom` (feature `preview-composed-from`, OATS 0.30.2): why the
+  module is there — `"soul"` (the soul declares it, including a soul entry
+  that overrides a workspace default of the same name, a package soul's
+  `from: here`, and every module of a standalone view) or `"workspace"` (a
+  `defaults.<slot>` or `defaults.capabilities` entry). It is the same value
+  `oats inspect --soul` reports as `capabilities[].composedFrom`. It is
+  provenance only: it never enters `resolution`, `declRevision`,
+  `payloadRevision` or `decision.revision`, and `instance.json` does not
+  record it. `from` says where the bytes come from.
 - `capabilities[]` (`{name, origin}`, `origin` `package:<id>@<v>` or
   `member:<repoKey>@<commit>`) and `skills[]` (the soul's own skills as
   strings, module skills as `{name, source: "module:<cap>"}`) are display
@@ -1288,8 +1299,9 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
 `wake`; later starts add `restarts` and `restartCount`.
 
 - `modules.<cap>`: `{from, commit, digest, materializedAt}`; `digest` hashes
-  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied to
-  `<home>/.agents/skills/<cap>/<skill>/`.
+  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
+  `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
+  `<home>/.agents/skills/<cap>/<skill>/`).
 - `providers.<cap>`: the merged payload (`{}` when none).
 - `workspace`: `{key, name, deployment, commit, resolution, standalone, soul,
   layers}`. `name` is recorded, and every hook, command and operation of the

package/docs/first-team.md

@@ -120,7 +120,7 @@ oats status
 `--harness pi|claude|codex` picks the harness; complete any native folder
 trust or authentication prompt in the printed session. The instance home is
 `agents/<soul>/instances/<instance>/`; `work/` is its repository view;
-`.oats/modules/<cap>/` and `.agents/skills/<cap>/` are the copied capabilities;
+`.oats/modules/<cap>/` are the copied capabilities and `.agents/skills/<skill>/` their skills;
 `instance.json` records `modules` (from, commit, digest), `providers` and
 `workspace`. A running instance never changes under itself — a member that
 moves affects only new spawns, and `oats status` shows the drift

package/docs/implementation.md

@@ -30,7 +30,8 @@ published to npm. Its developer docs are in
 | `lib/` | the kernel (below) |
 | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
 | `skills/` | bootstrap skills shipped with the kernel |
-| `capabilities/` | generated mirrors of released package capabilities (for example `oats-okf*`), checked by `scripts/check-okf-mirror.mjs` |
+| `capabilities/` | this repository's own member capabilities (`oats-workspace-experts`), discovered at the member's latest state |
+| `mirrors/` | generated byte mirrors of the official packages' capabilities (for example `oats-okf*`, checked by `scripts/check-okf-mirror.mjs`): release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package |
 | `oats-package/` | the `oats.framework` package |
 | `souls/` | this repository's own souls (a workspace member) |
 | `docs/` | the reference pages, schemas, design records and release notes |

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.0.4
+  oats.okf: v4.0.5
   oats.aweb: v1.17.1
   oats.linear: v1.0.1
   oats.jira: v1.0.1

package/docs/knowledge-capability-authoring.md

@@ -29,7 +29,7 @@ an author soul:
 ```yaml
 # oats-workspace.yaml
 packages:
-  oats.framework: v1.4.0            # provides oats.core, oats.setup, oats.knowledge-theory
+  oats.framework: v1.4.1            # provides oats.core, oats.setup, oats.knowledge-theory
 
 # souls/<author-soul>/soul.yaml
 capabilities:

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.0.4
+  oats.okf: v4.0.5
 defaults:
   knowledge: { oats.okf: { from: package } }
 stores:
@@ -207,9 +207,9 @@ its `oats trigger test` passes.
 
 | Capability | Composed into | Skills | Inject |
 |---|---|---|---|
-| `oats.okf` | every working soul it serves | [`okf-consultation`](../capabilities/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../capabilities/oats-okf/skills/okf-instance-knowledge/SKILL.md) | Consult soul and instance knowledge; capture with judgment. |
-| `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../capabilities/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` | A judge; its staged roots are its only write surface. |
-| `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../capabilities/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../capabilities/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) | One PR per instance; never supersede silently. |
+| `oats.okf` | every working soul it serves | [`okf-consultation`](../mirrors/oats-okf/skills/okf-consultation/SKILL.md), [`okf-instance-knowledge`](../mirrors/oats-okf/skills/okf-instance-knowledge/SKILL.md) | Consult soul and instance knowledge; capture with judgment. |
+| `oats.okf-harvest` | `oats.okf/knowledge-harvester` | `knowledge-theory`, [`knowledge-harvest`](../mirrors/oats-okf-harvest/skills/knowledge-harvest/SKILL.md), `okf-authoring` | A judge; its staged roots are its only write surface. |
+| `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` | `knowledge-theory`, [`knowledge-review`](../mirrors/oats-okf-maintenance/skills/knowledge-review/SKILL.md), `okf-authoring`, [`okf-trigger-setup`](../mirrors/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md) | One PR per instance; never supersede silently. |
 
 Working souls get no promotion doctrine: only the harvester judges and only
 the maintainer merges. `knowledge-theory` and `okf-authoring` ship as

package/docs/official-catalog.md

@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.4.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
-| `oats.okf` | `v4.0.4` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
+| `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.okf` | `v4.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
 | `oats.aweb` | `v1.17.1` | `oats.aweb` (messaging) | |
-| `oats.engineering` | `v1.1.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.engineering` | `v1.3.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
 | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
 | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
 | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
@@ -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.0.4`); `oats sync` resolves it through the
+  `packages:` map (`oats.okf: v4.0.5`); `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.0.4                                    # bare version → the official catalog
+  oats.okf: v4.0.5                                    # 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.0.4`, `4.0.4`, `1.0.0-rc.1`): the id is looked up in
+- **Bare version** (`v4.0.5`, `4.0.5`, `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.0.4` or `oats-framework/v1.4.0`) and the payload path. An id
+  convention (`v4.0.5` or `oats-framework/v1.4.1`) 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.0
-  oats.okf: v4.0.4
+  oats.framework: v1.4.1
+  oats.okf: v4.0.5
   oats.aweb: v1.17.1
 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.0.4 ✓ (@ a4ccca02)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.okf 4.0.5 ✓ (@ 26d8216f)
 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.0.4",
-      "commit": "a4ccca0230b75961daa00f59f29b8264be6fb5e8",
+      "version": "4.0.5",
+      "commit": "26d8216f8ce986cad1ffa7a8291b4a4978510ee2",
       "integrity": "sha256-…",
       "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
     },
@@ -212,7 +212,7 @@ At spawn a `from: package` module is fetched at the lock's commit from the
 lock's `url`, at the manifest-listed directory (`oats-package.json#capabilities[]`
 entry), into `<home>/.oats/modules/<cap>/`; the copy's digest is verified
 against what the fetch reported; skills are copied to
-`<home>/.agents/skills/<cap>/<skill>/`. `instance.json.modules.<cap>.from` is
+`<home>/.agents/skills/<skill>/` (flat). `instance.json.modules.<cap>.from` is
 `{ kind: "package", package, version, commit, integrity, repoKey }`. Bumping
 `packages:` and syncing affects **only new spawns**; `oats status` shows a
 running instance's package module as `moved` once the lock points elsewhere.
@@ -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.0.4", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.0", "path": "oats-package" }
+    "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.5", "path": "oats-package" },
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.1", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.4.0`
-resolves to tag `oats-framework/v1.4.0`. Resolving through the catalog never
+`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
 advances a lock by itself: `oats sync` does, and says so.

package/docs/plans/0.30-close-out.md

@@ -1,7 +1,7 @@
 # OATS 0.30 close-out: the shared plan
 
 The single source of truth for the rest of 0.30, owned by BOTH leads (oats-expert-knowledge-reworks
-and oats-expert-antares; Juan asked for joint work on 2026-09-28). Whoever changes the state updates
+and oats-expert-antares, succeeded by oats-expert-steward; Juan asked for joint work on 2026-09-28). Whoever changes the state updates
 this file.
 
 ## Rules
@@ -20,7 +20,7 @@ this file.
 | 5 | The 0.30.0 release PR (brief below) | lead | cli-dev-v2-native | briefed |
 | 6 | Full rehearsal re-run on the final heads (all cases, incl. 5 and 10); close-out; retire case 9; the 0.30 runbook for Juan and Pepe | Antares | — | DONE on the final heads (main kernel stamped 0.30.0 + aweb v1.17.1 + okf v4.0.4): all cases PASS (1–8, 10, onboarding (a)–(e) + resume, the BYOT leave/retire owner commands actually run → revoked, 22 clean retires). Known: 8 (E_SPAWN_FAILED), the BYOT membership limit. Runbook for Juan and Pepe: next |
 | 7a | automations.trust (#300, ACKed a0562b9f) + the Desktop grouping of `untrusted` with owner-mismatch (not here, with the remedy; a real-capture test): the Desktop PR merges BEFORE #300. Both land before the tag, or both go to 0.30.1 together | lead | cli-dev-okf-ops + ux-designer-desktop-redesign | routed |
-| 7 | Tag v0.30.0 after green main CI on the exact release SHA | Antares | — | after 5 and 6 |
+| 7 | Tag v0.30.0 after green main CI on the exact release SHA | Antares | — | DONE: v0.30.0 + oats-framework/v1.4.0 on dec58082 (main CI green on it); published @awebai/oats 0.30.0 (shasum 2e370157) + @awebai/oats-pi 0.30.0, latest; a clean-room onboard with the published package locks framework 1.4.0, aweb 1.17.1, okf 4.0.4, engineering 1.1.0 |
 
 **Sequence:** 1–4 in parallel → 6 on the final heads → 5 with the final pins → 7.
 
@@ -50,6 +50,22 @@ this file.
 8. A check of the PACKED tarball: its `package-catalog.json` carries oats.engineering 1.1.0,
    oats.aweb 1.17.1 and oats.okf 4.0.4.
 
+## Released (2026-09-29)
+**OATS 0.30.0** on npm (`@awebai/oats` and `@awebai/oats-pi`, latest), from `dec58082` (#297).
+Tags `v0.30.0` and `oats-framework/v1.4.0` are both on that SHA. Pins: oats.aweb 1.17.1,
+oats.okf 4.0.4, oats.engineering 1.1.0, framework 1.4.0. A clean-room `oats onboard` against the
+published package locks all of them without a catalog override.
+
+Found by the rehearsals, and fixed before the tag:
+- joined teams unusable against real aw;
+- okf readiness always `unknown`;
+- `oats aweb setup` from a deployment;
+- launch-hook warnings dropped;
+- `readiness --soul` with no soul copy;
+- a newcomer's first `--join`;
+- a stale `settings.team` orphaning identities on retire;
+- a BYOT retire with no owner command.
+
 ## After the tag
 - **Flag day:** the oats.engineering release with the souls' `launch:` (experts on Claude Code +
   Opus 5.5; `code-reviewer` on Codex + Astra; compat `>=0.30.0`), and committing the shared team id.
@@ -57,5 +73,11 @@ this file.
   - the kernel items that miss the tag: retire of homes whose session is gone, automations.trust;
   - deployment-scope capability commands without `--soul`;
   - the case-8 pre-check (`E_TEAM_UNCONFIGURED`).
+  - the kernel refuses an unrecognised spawn argument (a bare `join=oats` without
+    `--provider oats.aweb` was silently ignored, so the spawn joined nothing).
+  - a launch (spawn, `session start`, `session restart`) puts the spawning kernel's bin directory
+    FIRST on the instance's PATH and records it in the launch recipe, so plain `oats` inside an
+    instance is the kernel that made it (two kernels side by side: a 0.30 home ran the global 0.24.6
+    and `oats aweb` was `E_UNKNOWN_COMMAND`; the injected instructions tell agents to run plain `oats`).
 - **Parked:** item L (`git rm agents/`, cli-dev-v2-native). It needs the GitHub `workflow` token
   scope from the human on the lead's machine.

package/docs/release-lane.md

@@ -174,9 +174,14 @@ not weaken the pre-publish build/inventory/ABI gates.
 ## Mirroring a released `oats.okf`
 
 The standalone `awebai/oats-okf` repository is authoritative. This repository
-carries a generated mirror of its capabilities under `capabilities/oats-okf*/`
+carries a generated mirror of its capabilities under `mirrors/oats-okf*/`
 and the inventory `scripts/okf-source-inventory.json`; neither is edited by
-hand. After an okf release is tagged:
+hand. The inventory records each capability at its path inside the package
+(`capabilities/oats-okf`, what the tag attests) and, in `mirrorPaths`, where
+this repository keeps it. The mirror is not under `capabilities/`: this
+repository is a workspace member, and member discovery would list it as a
+latest-state member capability beside the package. After an okf release is
+tagged:
 
 1. Check out the release in a clean clone of `awebai/oats-okf` at the tagged
    commit, with the tag present locally and `origin` pointing at the official

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

@@ -0,0 +1,123 @@
+# OATS 0.30.1
+
+## Fixes
+
+- **Desktop: an instance-less soul no longer takes the whole roster down.**
+  `oats status --json` reports an agent row's `key` as `null` when no instance
+  records a workspace soul, as the roster contract documents. That happens for a
+  soul directory with no instances: after a spawn preview of a soul that has
+  never been spawned, or after its last instance is retired. The 0.30.0 Desktop
+  accepted only a string there, so one such row rejected the whole observation
+  with `E_CLI_PROTOCOL` ("The installed OATS CLI returned an invalid deployment
+  observation"). The Desktop now accepts `null` and still refuses any other
+  type.
+- **Knowledge readiness answers, fast.** With oats.okf 4.0.5, `oats readiness`
+  answers the knowledge check from okf's cache in the knowledge `stateDir`, well
+  inside the kernel's 30 s cap, instead of cloning every base and timing out as
+  `unknown` (measured: 7 s against 35 s and `unknown` before). A base that is
+  not cached yet, out of date or unreachable is reported as a named warning or
+  problem, never `unknown`. A spawn with harvest off fills the cache, spending at
+  most 20 s per base, and still refuses a soul that names a node its base does
+  not have.
+- **Desktop: a stored workspace selection the server no longer serves** (a
+  deleted deployment) locked the Desktop out: every roster refresh refused the
+  server's reply as "belongs to a different workspace", and the switcher
+  already showed the served workspace as active. A selection that is not
+  among the served workspaces is now treated like an empty one: both rosters
+  adopt the served workspace and the stored selection is replaced. A
+  selection the server does serve, answered with another workspace, is still
+  refused.
+- **Desktop: terminal tabs are back to native geometry.** 13px system
+  monospace, xterm's default line height, and 32px side gutters with no
+  vertical inset, as before Redesign v3. The block cursor is one cell tall
+  again. A font size you chose yourself is kept.
+- **Desktop: the spawn dialog could stay on "Reading defaults…" forever.**
+  A routine roster refresh restarted the spawn preview while it was still
+  being read, so on a machine where the preview takes several seconds it
+  never finished. The dialog now re-reads only when a fact the preview
+  depends on changes.
+
+## Packages
+
+- **oats.okf 4.0.5** (was 4.0.4 in 0.30.0): the knowledge readiness fix above.
+- **oats.engineering 1.3.0** (was 1.1.0 in 0.30.0).
+  - 1.2.0: the packaged `code-reviewer` launches on Codex with `gpt-6-astra` by default, a different model family from the developers it reviews. A machine without the `codex` binary gets `E_HARNESS_UNAVAILABLE` when it spawns `code-reviewer`, until it installs Codex or overrides the preference (`oats-local.yaml` `souls.launch`, or `--harness`/`--model` at spawn).
+  - 1.3.0: review happens on local branches, before the PR. The developer runs its adversarial loop with the `code-reviewer` on its local branch and hands the reviewed branch to its expert. The expert reviews that branch, and only when it accepts is a PR opened. A returned branch's delta goes back through the same reviewer first.
+
+## Changed
+
+- **Desktop: calmer selection, focus and search fields.** A selected segment
+  (Group by, List/Graph and similar) now uses the brand tint instead of
+  white-on-grey. Clicking a button, tab or row no longer draws a focus ring.
+  Keyboard focus stays visible as the tint plus a thin accent edge, not a
+  2px ring. Search and filter fields have a single border that turns accent
+  on focus, with no inner ring.
+  Sidebar instance rows are more compact, with a gap between highlighted rows,
+  and an instance's pull request number sits before its branch name instead of
+  on its own line.
+- **The official workspace lists each package capability once.** The `oats`
+  repository kept byte mirrors of the official packages' capabilities
+  (`oats.okf`, `oats.aweb`, `oats.jira`, …) under `capabilities/`, so `oats
+  capabilities` in the official workspace also listed each of them as a member
+  capability of `github.com/awebai/oats`, beside its package. The mirrors now
+  live in `mirrors/`, which member discovery does not read, and the npm
+  package no longer carries them (nothing read them at runtime: capabilities
+  resolve from Git at the locked commit). No operator action.
+- **Desktop: clearer Workspace views, and Spawn goes straight to the soul.**
+  Soul cards label their facts ("Team oats", "No instances" instead of a
+  bare "none"), group by repo by default, and keep a compact Spawn on the
+  instances line. Capabilities are compact one-line row cards with a
+  kind-coloured tile, their source and who uses them; a row opens the
+  capability page with the full description. Teams show one card per team,
+  split into shared and this-computer sections. Spawn on a soul card or the
+  soul page opens the spawn dialog for that soul, with a "What will be
+  created" preview (core capabilities and capabilities with their sources);
+  "Change soul" returns to the picker.
+- **Two Desktop souls.** The `oats-desktop-designer` soul is removed.
+  `oats-desktop-expert` now owns Desktop's UX and design direction as well as
+  its product rationale, and `oats-desktop-developer` builds all of
+  `packages/desktop`, including renderer views, styles, themes and copy.
+  Running designer instances keep working until they are retired; `oats
+  status` reports their soul as no longer present.
+- **The legacy Desktop soul trees are removed.** `agents/oats-desktop-engineer`
+  and `agents/ux-designer` were no longer offered souls. The
+  `oats-desktop-expert` knowledge node carries their durable rationale.
+- **The remaining legacy soul trees are removed.** `agents/cli-dev`,
+  `dev-coordinator`, `docs-expert`, `integrations-expert`, `lead`,
+  `oats-coordinator` and `oats-expert` were pre-v2 soul bundles, not offered
+  souls; the offered souls live in `souls/` and the packages. Their bundled
+  knowledge gate (`npm run validate:okf`) goes with them: the souls' knowledge
+  lives in the central knowledge base, which validates itself.
+- **Desktop: a calmer instance panel.** The summary bar under the terminal
+  (harness, tmux target, team marks, Details, Focus mode) is gone, and the
+  terminal gets its height. A panel toggle at the end of the tab bar shows or
+  hides the instance panel (⌥⌘B, Ctrl+Alt+B on Linux and Windows; also in the
+  command palette). Focus mode stays in the palette; in focus mode the panel
+  toggle and the sidebar's edge button stay visible and leave it. The Instance
+  tab drops Built from and Details. When the kernel reports drift, its header
+  shows an "older build" chip whose tooltip says what changed and that
+  re-spawning picks up the new state. Where it works is one card: the work mode
+  in plain words, then repo, branch and home. Messaging is a compact list of
+  teams, with an icon refresh and the identity address on its own line. The Git
+  & GitHub tab is now the Developer tab; it shows branch, changes and pull
+  request cards; the branch line says how far it is from main and, when it has
+  an upstream, how many commits are unpushed. An instance without Git by design
+  (directory or workspace mode) gets a calm "No Git for this instance" note
+  instead of a red error; a worktree that has gone missing still reports its
+  error.
+- **The official workspace's souls declare launch preferences.** Its experts,
+  developers and setup admin prefer Claude Code with Opus 5.5 (`launch:` in
+  each `soul.yaml`); each machine can override them in `oats-local.yaml`
+  `souls.launch`, and spawn flags win over both.
+
+## Still known in 0.30.1
+
+The 0.30.0 notes said the first two below would be fixed in 0.30.1. They are
+not in this release, and are planned for 0.30.2.
+
+- With no teams configured, a spawn is refused by the provider
+  (`E_SPAWN_FAILED`, relaying "no teams configured: run `oats aweb setup`"),
+  not by the kernel's `E_TEAM_UNCONFIGURED`.
+- A capability operator command run from a deployment needs `--soul <soul>`.
+- On a team you control (BYOT), retire cannot revoke membership; the retire
+  prints the owner's `aw id team remove-member` command, as in 0.30.0.

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

@@ -0,0 +1,85 @@
+# OATS 0.30.2
+
+## Changed
+
+- **Desktop: a faster, calmer load.** The backend reads a deployment's status
+  and workspace status in parallel, holds the souls and capabilities catalogs
+  and soul inspections server-side (re-read when the workspace state or a
+  Desktop mutation moves, or when viewed after 60 s), and slows its cycle
+  from 5 s to 30 s while no window is focused. Returning to the window no longer
+  re-reads the capabilities list or cancels the observation in flight. When
+  the installed CLI supports `--max-age`, background reads accept the kernel's
+  recent observation; `/api/panel`, `/api/agents`, `/api/workspace-sync` and
+  `/api/capabilities` inspect now report `observedAt` and `refreshing`.
+- **Desktop: Where it works shows the work folder.** The Instance tab's Where
+  it works card adds a Folder row, `<home>/work`, between Branch and Home, with
+  a copy button; in checkout, attached and workspace mode a muted "shared" tag
+  says it links to the tree other instances share.
+
+- **Desktop: consistent loading states.** The sidebar roster, the hierarchy,
+  the soul inspector and readiness now run on one state model: skeletons
+  shaped like the final content instead of false empty lists,
+  content and focus kept while refreshing, stale data labelled with its
+  observation's age and a Retry, and the actions that need current state held
+  with an accessible reason until a good read.
+
+- **Desktop: the Workspace view and the instance panel join the loading-state
+  model.** The Souls grid, the Capabilities tab and its capability pages, and
+  the instance panel's Soul and Messaging sections show skeletons at the real
+  row and card size instead of empty claims, keep their content (and a held
+  table) through a refresh or a failed re-read, and name a stale observation's
+  age with a Retry; the spawn dialog's harness, model and launch hints describe
+  the preview for the choices on screen only.
+- **The spawn preview says why each module is there.** Every `modules[]` row
+  of `oats spawn … --preview --json` carries `composedFrom`: `"soul"` when the
+  soul declares the capability (a package soul's `from: here` and every module
+  of a standalone view included), `"workspace"` when a workspace default
+  (`defaults.<slot>` or `defaults.capabilities`) gave it. It is the value
+  `oats inspect --soul` already reports as `capabilities[].composedFrom`.
+  Provenance only: `resolution`, `declRevision`, `payloadRevision` and the
+  spawn decision are unchanged, so a previewed decision still binds its apply.
+  Gate on the new feature `preview-composed-from`
+  ([Desktop CLI API](../desktop-cli-api.md#the-preview)).
+
+## Fixed
+
+- **Instance skills are flat again, so Claude Code finds them.** Since the
+  workspace model (0.25.0) spawn copied each module's skills grouped by
+  capability, `<home>/.agents/skills/<capability>/<skill>/SKILL.md`. Claude
+  Code discovers skills one level deep (`.claude/skills/<skill>/SKILL.md`), so
+  no capability skill resolved there: `/oats-operate`, `/oats-aweb`,
+  `/okf-consultation` and the rest were missing from the session although the
+  composed `AGENTS.md` tells the agent to load them. (pi's loader recurses, so
+  pi instances were not affected.) Spawn now copies every skill, the soul's
+  own and every module's, flat to `<home>/.agents/skills/<skill>/`, the
+  layout the Agent Skills convention and every harness expect;
+  `.claude/skills → ../.agents/skills` is unchanged. `instance.json` records
+  the flat paths (`capabilities[].skills`; a module's skill tree in
+  `composition.expected[].resolved` is the skills root).
+- **One skill name, one directory.** Every composed skill shares the flat
+  directory, so names are unique across the soul and its modules, compared
+  case-insensitively: a soul's own skill named like a module's skill, or two
+  names differing only in case, is `E_SKILL_DUPLICATE` at spawn and the home
+  is removed. A soul skill named like a *capability* (`oats.okf`) is no
+  longer a collision. No soul in this repository is affected.
+- **oats.framework 1.4.1** (oats.core 2.2.1): the `oats-operate` skill shows
+  the flat layout.
+
+**Existing Claude Code instances keep their grouped layout and still do not
+see their capability skills: respawn them to pick up the fix.** Nothing
+rewrites an existing home: a running instance never changes under itself, and
+moving its skills would contradict what its `instance.json` recorded. Until
+it is respawned, an agent can read a skill by path,
+`.agents/skills/<capability>/<skill>/SKILL.md`.
+
+## Still known in 0.30.2
+
+The 0.30.1 notes planned the first two below for 0.30.2. They are not in this
+release; they are planned for 0.30.3.
+
+- With no teams configured, a spawn is refused by the provider
+  (`E_SPAWN_FAILED`, relaying "no teams configured: run `oats aweb setup`"),
+  not by the kernel's `E_TEAM_UNCONFIGURED`.
+- A capability operator command run from a deployment needs `--soul <soul>`.
+- On a team you control (BYOT), retire cannot revoke membership; the retire
+  prints the owner's `aw id team remove-member` command, as in 0.30.0.

package/docs/souls-and-instances.md

@@ -122,8 +122,8 @@ full copy** of every capability the soul resolved to:
 <agents-root>/<soul>/instances/<instance>/
   AGENTS.md                        # generated: soul AGENTS.md + kernel/work-mode blocks + each module's inject
   CLAUDE.md → AGENTS.md
-  .agents/skills/                  # canonical skill tree — soul skills + <capability>/<skill>/ full copies
-    <capability>/<skill>/SKILL.md
+  .agents/skills/                  # canonical skill tree, flat: the soul's skills and every module's, full copies
+    <skill>/SKILL.md               # one level deep, where every harness discovers skills
   .claude/skills → ../.agents/skills
   .oats/modules/<capability>/      # the whole capability: oats.json, bin/, injects/, skills/ (hooks run from here)
   work/                            # worktree, checkout symlink, attached tree, or private directory
@@ -150,8 +150,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.0.4", "commit": "a4ccca02…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
-      "commit": "a4ccca02…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
+      "from": { "kind": "package", "package": "oats.okf", "version": "4.0.5", "commit": "26d8216f…", "integrity": "sha256-…", "repoKey": "github.com/awebai/oats-okf" },
+      "commit": "26d8216f…", "digest": "sha256-…", "materializedAt": "2026-09-24T10:12:44.201Z"
     }
   },
   "providers": {
@@ -193,7 +193,8 @@ bump affects only new spawns.
 OATS is a skill contributor, not a skill sandbox. The harness (pi, Claude Code,
 Codex) starts with cwd = the instance home and its **own** skill discovery
 intact: it sees, nearest first, the instance's `.agents/skills/` (soul skills
-and the copied capability skills), the repo's own `.agents/skills/` once it
+and the copied capability skills, all flat at `.agents/skills/<skill>/SKILL.md`,
+the one level deep Claude Code discovers through `.claude/skills`), the repo's own `.agents/skills/` once it
 works in `work/`, and whatever the operator keeps at machine level. All three
 are intended. Two *composed* skills with one name is a spawn error naming both
 capabilities (`E_SKILL_DUPLICATE`); a composed skill versus an ambient one is