@awebai/oats 0.30.1 → 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
@@ -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/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/official-catalog.md

@@ -9,7 +9,7 @@ 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.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.3.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |

package/docs/packages.md

@@ -51,7 +51,7 @@ packages:
 - **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.5` 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,7 +74,7 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.0
+  oats.framework: v1.4.1
   oats.okf: v4.0.5
   oats.aweb: v1.17.1
 teams:
@@ -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.
@@ -332,11 +332,11 @@ A soul that names one of the package's capabilities with
   "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.5", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.0", "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/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
@@ -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

package/docs/workspaces.md

@@ -54,7 +54,7 @@ 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.0                   # bare version → resolves through the official catalog
+  oats.framework: v1.4.1                   # bare version → resolves through the official catalog
   oats.okf: v4.0.5
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 

package/lib/core.mjs

@@ -2992,7 +2992,7 @@ function* spawnBody(root, agent, o = {}) {
     return e;
   };
   // Workspace model: copy every resolved capability WHOLE into the new home
-  // (.oats/modules/<cap>/ + .agents/skills/<cap>/) and record modules/providers
+  // (.oats/modules/<cap>/, its skills flat in .agents/skills/<skill>/) and record modules/providers
   // in instance.json. Then REBUILD the capability rows against the copies that
   // landed (H1): until now `resolvedCfg.capabilities` were PLANNED rows (no
   // skills, no inject, no dir) — hooks, environment, requirements, retirement
@@ -3034,9 +3034,14 @@ function* spawnBody(root, agent, o = {}) {
         const row = rows.find((c) => c.id === r.module);
         if (r.type === "injection") { r.path = row?.inject; continue; }
         if (r.type === "skill-tree") {
-          const skillsRoot = join(home, ".agents", "skills", r.module);
+          // Module skills land flat in the canonical skills root; the entries are
+          // the names materialize placed for this module (what the resolution
+          // promised), verified against the root in the completeness check.
+          const skillsRoot = join(home, ".agents", "skills");
           r.path = existsSync(skillsRoot) ? skillsRoot : undefined;
-          r.entries = (row?.skills || []).map((p) => basename(p));
+          r.entries = Array.isArray(materializeOutcome?.skills)
+            ? materializeOutcome.skills.filter((s) => s.module === r.module).map((s) => s.name)
+            : (row?.skills || []).map((p) => basename(p));
         }
       }
     } catch (e) { throw rollbackEmptyOrPreparedHome(e); }
@@ -3074,30 +3079,43 @@ function* spawnBody(root, agent, o = {}) {
   }
   if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
 
-  // Skills: module skills were copied WHOLE into <home>/.agents/skills/<module>/
+  // Skills: module skills were copied WHOLE and FLAT into <home>/.agents/skills/<skill>/
   // by materialize (decision 7/13); here only the soul's own skills join them, one
-  // directory each. There is no override: a soul skill named like a module's
-  // directory is a duplicate (decision 16). The harness is launched with its normal
+  // directory each, at the same level — the one level every harness discovers. There
+  // is no override: a soul skill named like a module's skill is a duplicate (decision 16). The harness is launched with its normal
   // discovery — the machine's and the repo's skills are the harness's business.
   const sources = [];
   const soulSkills = join(soulDir, "skills");
   if (existsSync(soulSkills)) sources.push({ id: "soul", path: soulSkills });
   const chosen = new Map();
+  // Names compare case-insensitively: one directory per skill on a case-insensitive
+  // filesystem (APFS, NTFS) must not silently merge `Foo` into `foo`.
+  const moduleSkillOwner = new Map((materializeOutcome?.skills || []).map((s) => [s.name.toLowerCase(), s.module]));
+  const chosenKeys = new Map();
   const offer = (name, src, source) => {
-    if (chosen.has(name) || existsSync(join(home, ".agents", "skills", name))) throw oatsError("E_SKILL_DUPLICATE", `skill "${name}" from ${source} collides with ${chosen.get(name)?.source ?? `module ${name}'s skill directory`}`);
+    const key = name.toLowerCase();
+    if (chosenKeys.has(key) || moduleSkillOwner.has(key) || existsSync(join(home, ".agents", "skills", name))) {
+      const other = chosenKeys.get(key) ?? (moduleSkillOwner.has(key) ? `module ${moduleSkillOwner.get(key)}'s skill` : `the existing .agents/skills/${name}`);
+      throw oatsError("E_SKILL_DUPLICATE", `skill "${name}" from ${source} collides with ${other}`);
+    }
     chosen.set(name, { src, source });
+    chosenKeys.set(key, source);
   };
-  // Same enumerator preflight used, so "what a tree promises" and "what gets
-  // copied" cannot drift apart.
-  for (const source of sources) for (const entry of skillEntriesIn(source.path)) offer(entry.name, entry.src, source.id);
-  mkdirSync(join(home, ".agents", "skills"), { recursive: true });
-  mkdirSync(join(home, ".claude"), { recursive: true });
-  for (const [name, selected] of [...chosen].sort(([a], [b]) => a.localeCompare(b))) {
-    // Pi's recursive skill scanner does not descend through directory symlinks.
-    // Copy each selected tree so the exact instance-local set is real and immutable.
-    copyTreeSafe(realpathSync(selected.src), join(home, ".agents", "skills", name));
-  }
-  if (!existsSync(join(home, ".claude", "skills"))) symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
+  // A refusal here comes after materialize populated the home: remove it whole,
+  // like every other failure between materialize and the completeness check.
+  try {
+    // Same enumerator preflight used, so "what a tree promises" and "what gets
+    // copied" cannot drift apart.
+    for (const source of sources) for (const entry of skillEntriesIn(source.path)) offer(entry.name, entry.src, source.id);
+    mkdirSync(join(home, ".agents", "skills"), { recursive: true });
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    for (const [name, selected] of [...chosen].sort(([a], [b]) => a.localeCompare(b))) {
+      // Pi's recursive skill scanner does not descend through directory symlinks.
+      // Copy each selected tree so the exact instance-local set is real and immutable.
+      copyTreeSafe(realpathSync(selected.src), join(home, ".agents", "skills", name));
+    }
+    if (!existsSync(join(home, ".claude", "skills"))) symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
+  } catch (e) { throw rollbackEmptyOrPreparedHome(e); }
 
   // EXPECTED == MATERIALIZED. Preflight proved every declared resource resolves;
   // this proves the copies actually landed, so "the composition is complete" is
@@ -3119,18 +3137,14 @@ function* spawnBody(root, agent, o = {}) {
       if (!chosen.has(name)) incomplete.push(`skill "${name}", promised by ${r.source} (${r.declared}), is missing from the composed set`);
     }
   }
-  // Prepared spawn: every module's declared skill must have been copied under
-  // .agents/skills/<module>/<skill>/ by materialize — verify the copies landed
-  // as readable skills (the module directory alone proves nothing).
+  // Prepared spawn: every module's declared skill must have been copied to
+  // .agents/skills/<skill>/ by materialize — verify the copies landed as
+  // readable skills, one level deep, where the harnesses discover them.
   if (o.prepared) {
-    for (const m of o.prepared.resolution.modules) for (const s of m.manifest.skills || []) {
-      const sk = join(home, ".agents", "skills", m.name);
-      if (!existsSync(sk)) { incomplete.push(`module "${m.name}" declares skills but .agents/skills/${m.name} is absent`); break; }
-    }
     for (const r of expectedResources) {
       if (r.deferred !== "materialize" || r.type !== "skill-tree") continue;
-      if (!r.path) { incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but .agents/skills/${r.module} is absent`); continue; }
-      if (!r.entries.length) incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but no skill was copied under .agents/skills/${r.module}`);
+      if (!r.path) { incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but .agents/skills is absent`); continue; }
+      if (!r.entries.length) incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but none of its skills was copied into .agents/skills`);
       for (const name of r.entries) if (!hasSkillDoc(join(r.path, name))) incomplete.push(`skill "${name}" (module ${r.module}) did not materialize as a readable SKILL.md`);
     }
   }
@@ -3475,7 +3489,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     if (triggerEventFile) recipe.env.OATS_TRIGGER_EVENT_FILE = triggerEventFile;
     const cmdline = renderLaunchRecipe(recipe, { home, instance });
 
-    // Module skills as materialize landed them (.agents/skills/<module>/<skill>/),
+    // Module skills as materialize landed them (flat, .agents/skills/<skill>/),
     // beside the soul's own: per-skill provenance `module:<cap>` (lead decision c3),
     // `from` = the home's module copy the skill was copied from.
     const moduleSkills = (materializeOutcome?.skills || []).map((row) => ({ name: row.name, source: `module:${row.module}`, from: join(home, row.from) }));

package/lib/instance-inspect.mjs

@@ -221,7 +221,7 @@ function capabilityRows(t) {
       return { ...op, argv: [m.command ?? null, op.command], available: !reason, reason };
     });
     // composedFrom (feature desktop-facts): where the soul's composition took it from — "workspace" |
-    // "team:<label>" | "soul" (layers-from vocabulary); null for a home (not recorded at spawn). `from` is the module's origin.
+    // "soul" (layers-from vocabulary); null for a home (not recorded at spawn). `from` is the module's origin.
     return { id: name, version: m.version ?? null, layer: m.layer ?? null, command: m.command ?? null, from, composedFrom: t.capabilitiesFrom?.[name] ?? null, dir,
       settings: obj(t.payloads[name]) ? t.payloads[name] : {}, declares: declaredSettings(m), compatibility: compatibilityRow(name, m), missingRequires: missing, operations };
   });

package/lib/instance-resolution.mjs

@@ -5,7 +5,7 @@
  *  its Git remotes in the operator's access context → find the soul among the
  *  confirmed members (or external souls) → resolve every capability by `from:`
  *  (member = latest state, package = the locked version) → materialize
- *  each capability WHOLE into the new home (`.oats/modules/`, `.agents/skills/`) →
+ *  each capability WHOLE into the new home (`.oats/modules/`, skills flat in `.agents/skills/`) →
  *  compose AGENTS.md → launch the harness normally.
  *
  *  This module owns the async half (discover + resolve) and the materialize call;
@@ -24,7 +24,7 @@ import { resolveSoul, kernelCompatibility } from "./resolve.mjs";
 import { BY_TEAM_REMOVED, recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "./teams.mjs";
 import { launchLayers } from "./launch-preference.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
-import { materialize, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
+import { materialize, moduleSkills, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
 import { fetchRemoteTree } from "./remote.mjs";
 import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -524,9 +524,11 @@ export function toCapabilityRows(resolution, home) {
   for (const m of resolution.modules) {
     const dir = join(home, MODULES_DIR, m.name);
     const manifest = m.manifest;
-    const skills = [];
-    const skillsRoot = join(home, SKILLS_DIR, m.name);
-    if (existsSync(skillsRoot)) for (const e of readdirSync(skillsRoot, { withFileTypes: true })) if (e.isDirectory()) skills.push(join(skillsRoot, e.name));
+    // Skills are flat under <home>/.agents/skills/<skill>/; which of them this module
+    // contributed is read from its own copy, enumerated exactly as materialize placed them.
+    const skills = existsSync(dir)
+      ? moduleSkills(resolution, m, dir).map((s) => join(home, SKILLS_DIR, s.name)).filter((p) => existsSync(p))
+      : [];
     const inject = manifest.inject ? join(dir, manifest.inject) : undefined;
     rows.push({
       id: m.name, capability: m.name, manifest, layer: manifest.layer ?? undefined, command: manifest.command,
@@ -564,8 +566,12 @@ function requiredHooksOf(manifest) {
   return Object.entries(hooks).filter(([, s]) => s && typeof s === "object" && s.required === true).map(([e]) => e);
 }
 
-/** What a preview shows about modules: from/commit/digest per module and whether
- *  it changed since the newest existing instance of the same soul in `agentsRoot`. */
+/** What a preview shows about modules: from/commit/digest per module, whether
+ *  it changed since the newest existing instance of the same soul in `agentsRoot`,
+ *  and `composedFrom` (feature preview-composed-from): why the soul's composition
+ *  has it — "soul" | "workspace", the resolution's capabilitiesFrom. Provenance
+ *  only: it is outside every fingerprint. `null` only for a resolution without
+ *  capabilitiesFrom (an older in-process caller); never for a resolved module. */
 export function modulesPreview(resolution, agentsRoot, soulName) {
   let previous = null;
   const instancesDir = join(agentsRoot, soulName, "instances");
@@ -583,7 +589,8 @@ export function modulesPreview(resolution, agentsRoot, soulName) {
   return resolution.modules.map((m) => {
     const prev = previous?.modules?.[m.name];
     const changedSince = !previous ? null : !prev ? { instance: previous.name, was: null } : (prev.commit !== m.from.commit ? { instance: previous.name, was: prev.commit } : false);
-    return { name: m.name, from: m.from, layer: m.manifest.layer ?? null, private: !!m.private, declares: declaredSettings(m.manifest), changedSince };
+    return { name: m.name, from: m.from, layer: m.manifest.layer ?? null, private: !!m.private, declares: declaredSettings(m.manifest), changedSince,
+      composedFrom: resolution.capabilitiesFrom?.[m.name] ?? null };
   });
 }
 

package/lib/materialize.mjs

@@ -6,7 +6,9 @@
  * materialize(resolution, home, options)
  *   For every module of the resolution: fetch its capability directory whole into
  *   <home>/.oats/modules/<name>/, verify the copy's content digest, copy its skills as
- *   FULL copies into <home>/.agents/skills/<name>/<skill>/, compose <home>/AGENTS.md
+ *   FULL copies into <home>/.agents/skills/<skill>/ — FLAT, one level deep, where every
+ *   harness discovers them (Claude Code through .claude/skills/<skill>/); skill names are
+ *   unique across the modules (E_SKILL_DUPLICATE) — compose <home>/AGENTS.md
  *   (soul body + each module's inject, same marker comments as the kernel composer),
  *   keep the CLAUDE.md / .claude/skills aliases, and record modules + providers in
  *   <home>/instance.json.
@@ -16,7 +18,7 @@
  * place. Any failure before the commit removes the staging directory and leaves the home
  * exactly as it was (a `.oats/` directory created only for staging is removed too). The
  * commit re-checks the home's shape (no symlink planted at .oats/.agents/.claude or the
- * module targets during the fetch), then runs a short sequence of renames — modules,
+ * module and skill targets during the fetch), then runs a short sequence of renames — modules,
  * skills, AGENTS.md, instance.json, and the CLAUDE.md / .claude/skills aliases — with a
  * rollback journal: should any step fail, everything already placed is undone and the
  * previous AGENTS.md / instance.json restored before a named error (E_MATERIALIZE_HOME)
@@ -205,7 +207,7 @@ function hasSkillDoc(dir) {
 /** The skills a module contributes → [{ name, path }] (path relative to the module root).
  * Precedence: resolution.skills rows for the module; else manifest.skills; else every
  * skills/<dir>/SKILL.md in the fetched tree. */
-function moduleSkills(resolution, module, moduleDir) {
+export function moduleSkills(resolution, module, moduleDir) {
   const declared = (resolution.skills || []).filter((s) => s && s.module === module.name);
   const rows = [];
   if (declared.length) {
@@ -335,13 +337,22 @@ export async function materialize(resolution, home, options = {}) {
   const parents = [join(homeAbs, ".oats"), modulesRoot, join(homeAbs, ".agents"), skillsRoot, join(homeAbs, ".claude")];
   /** The home must still be what we checked: module targets absent, every parent a real directory (or absent).
    * Run before the fetch AND immediately before the commit — a symlink planted in between must not be written through. */
+  // Skill targets are known only once each module is fetched; the commit-time re-check covers them.
+  // skill name, lower-cased → { module, path, name }: one directory per skill, and on a
+  // case-insensitive filesystem `Foo` and `foo` are one directory.
+  const skillOwners = new Map();
   const assertHomeShape = () => {
     for (const { module } of sources) {
-      for (const target of [join(modulesRoot, module.name), join(skillsRoot, module.name)]) {
-        let st = null;
-        try { st = lstatSync(target); } catch {}
-        if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
-      }
+      const target = join(modulesRoot, module.name);
+      let st = null;
+      try { st = lstatSync(target); } catch {}
+      if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
+    }
+    for (const owner of skillOwners.values()) {
+      const name = owner.name, target = join(skillsRoot, name);
+      let st = null;
+      try { st = lstatSync(target); } catch {}
+      if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries a skill named ${name}; materialize never overwrites a skill in place`, { home: homeAbs, module: owner.module, skill: name, path: target });
     }
     for (const p of parents) {
       let st = null;
@@ -378,7 +389,6 @@ export async function materialize(resolution, home, options = {}) {
     mkdirSync(join(staging, "skills"), { recursive: true, mode: 0o755 });
 
     const moduleRows = [], skillRows = [], capabilityBlocks = [], recorded = {};
-    const skillOwners = new Map();
     for (const { module, source } of sources) {
       const stagedModule = join(staging, "modules", module.name);
       const finalModule = join(modulesRoot, module.name);
@@ -412,15 +422,21 @@ export async function materialize(resolution, home, options = {}) {
       }
 
       for (const skill of moduleSkills(resolution, module, stagedModule)) {
-        const owner = skillOwners.get(skill.name);
-        if (owner && owner !== module.name) {
-          throw fail("E_SKILL_DUPLICATE", `skill ${JSON.stringify(skill.name)} is contributed by both ${owner} and ${module.name}`, { name: skill.name, modules: [owner, module.name] });
+        // Skills land flat, so a name is one directory in the home: two sources for one
+        // name — two modules, or two paths of one module — are a duplicate.
+        const key = skill.name.toLowerCase();
+        const owner = skillOwners.get(key);
+        if (owner && owner.module === module.name && owner.path === skill.path && owner.name === skill.name) continue;
+        if (owner) {
+          const detail = owner.module === module.name ? `${module.name} (${owner.path} and ${skill.path})` : `both ${owner.module} and ${module.name}`;
+          const names = owner.name === skill.name ? JSON.stringify(skill.name) : `${JSON.stringify(owner.name)} / ${JSON.stringify(skill.name)} (one directory on a case-insensitive filesystem)`;
+          throw fail("E_SKILL_DUPLICATE", `skill ${names} is contributed by ${detail}`, { name: skill.name, modules: [owner.module, module.name] });
         }
-        skillOwners.set(skill.name, module.name);
+        skillOwners.set(key, { module: module.name, path: skill.path, name: skill.name });
         const src = join(stagedModule, ...skill.path.split("/"));
-        const staged = join(staging, "skills", module.name, skill.name);
+        const staged = join(staging, "skills", skill.name);
         copyTree(src, staged, `${module.name}/${skill.path}`);
-        skillRows.push({ module: module.name, name: skill.name, from: `${MODULES_DIR}/${module.name}/${skill.path}`.split(sep).join("/"), path: join(skillsRoot, module.name, skill.name) });
+        skillRows.push({ module: module.name, name: skill.name, from: `${MODULES_DIR}/${module.name}/${skill.path}`.split(sep).join("/"), path: join(skillsRoot, skill.name) });
       }
 
       for (const rel of moduleInjects(resolution, module, stagedModule)) {
@@ -478,10 +494,8 @@ export async function materialize(resolution, home, options = {}) {
     };
     try {
       for (const p of [join(homeAbs, ".oats"), modulesRoot, join(homeAbs, ".agents"), skillsRoot, join(homeAbs, ".claude")]) mkdirTracked(p);
-      for (const { module } of sources) {
-        placeDir(join(staging, "modules", module.name), join(modulesRoot, module.name));
-        if (existsSync(join(staging, "skills", module.name))) placeDir(join(staging, "skills", module.name), join(skillsRoot, module.name));
-      }
+      for (const { module } of sources) placeDir(join(staging, "modules", module.name), join(modulesRoot, module.name));
+      for (const row of skillRows) placeDir(join(staging, "skills", row.name), row.path);
       swapIn(join(staging, "AGENTS.md"), join(homeAbs, "AGENTS.md"), "AGENTS.md");
       swapIn(join(staging, "instance.json"), instanceFile, "instance.json");
       // Aliases (relative symlinks), only when absent — the canonical-plus-alias construction stays; inside the transaction.

package/package-catalog.json

@@ -33,7 +33,7 @@
     },
     "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "oats-framework/v1.4.0",
+      "ref": "oats-framework/v1.4.1",
       "path": "oats-package"
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.30.1",
+  "version": "0.30.2",
   "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,7 +60,7 @@ members:
   - git:github.com/acme/agents          # the host is a member too
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.0                # bare versions resolve through the official catalog
+  oats.framework: v1.4.1                # bare versions resolve through the official catalog
   oats.okf: v4.0.5
 defaults:
   capabilities: { oats.core: { from: package } }