@awebai/oats 0.22.0

package/docs/knowledge-theory.md

@@ -0,0 +1,97 @@
+# What belongs in a soul, and what belongs in an instance
+
+The knowledge layer's *format* is pluggable in OATS. The ideas below are not.
+They come from asking what memory means for an agent that outlives its
+sessions, and they apply whatever format or tooling you bind — OKF, plain
+markdown, or something else entirely.
+
+## The derivation
+
+A **soul** is identity across incarnations. So soul knowledge must be
+**incarnation-invariant** — true and binding for any future instance, on any
+model, in any session. "Durable AND would change what a future instance
+does" is the promotion bar, and it is really an invariance test.
+
+An **instance** is one incarnation's work. So instance memory is
+**indexical** — saturated with *I, here, now*. This branch. This blocker.
+This half-done plan. Indexical content cannot live in the soul, because its
+referents die when the instance does.
+
+That one distinction decides most placement questions on its own.
+
+## Harvest is de-indexicalization
+
+Moving knowledge from instance to soul is not copying files. It is
+rephrasing an insight so it survives its author. "The build broke until I
+cleared the cache" is indexical. "The build caches stale schemas — clear
+`.cache/schemas` after model changes" is invariant. Consolidation succeeds
+when the *I, here, now* is gone and the claim still holds.
+
+A useful corollary for any implementation: an instance file's format rigor
+should be proportional to its odds of surviving the instance. Working state
+can be loose. Promotion candidates should be written in soul genre from
+birth.
+
+## Capture and judgment are different jobs
+
+Instances should **capture without judging**. Writing an insight down is
+cheap and best done in the moment, by the one who had it. Judging whether it
+clears the promotion bar is expensive and best done deliberately, by
+something that is not in the middle of a task.
+
+Splitting the two has a second benefit. Agents that self-censor against a
+half-remembered bar write less. Agents told "capture everything non-obvious,
+judgment is someone else's job" write more, and the judge applies one
+consistent standard across all of them.
+
+## Knowledge consolidates through stages
+
+A fresh observation is not yet a lesson. It matures:
+
+| Stage | Example | Lives |
+|---|---|---|
+| Working state | "next: fix the failing test" | instance, rewritten freely |
+| Observation | "PATCH with nulls seems to be a no-op" | instance, captured as-is |
+| Lesson | "the API drops nulls — send empty strings" | soul, once verified |
+| Procedure | "steps to clear stuck queues" | soul, as a playbook or skill |
+
+The judge's routing question at the last step is one of shape. Facts that
+future instances should **know** become knowledge. Steps they should **run
+the same way** become skills. A correction to existing steps maintains the
+skill it corrects.
+
+## Decisions carry jurisdiction by location
+
+"We will retry twice, then escalate" can bind one task, or bind every future
+incarnation. The words are the same. The difference is where it is recorded
+— task decisions live and die with the instance's working state, soul
+decisions bind everyone after. Placement, not phrasing, carries the
+authority.
+
+## Souls hold slow state, not just timeless truth
+
+Not everything in a soul is eternal. A roadmap, a deployment's current
+shape, an open question — these are present-tense facts that tick at project
+speed rather than task speed. Durability is a spectrum. Task-fast state
+belongs to the instance. Project-slow state belongs to the soul and should
+carry dates, because it rots. Timeless lessons belong to the soul and mostly
+do not.
+
+## The knowledge structure is itself specialization
+
+Ship a minimal core ontology and let each soul grow the rest. An architect
+soul grows a roadmap section. A developer soul grows a codebase-gotchas
+section. A roadmap section in a developer soul is a smell — project
+direction belongs to whoever stewards the project.
+
+The test for growing a section is the promotion bar, one level up. Would
+future instances of *this* soul need to navigate this kind of knowledge? If
+yes, grow it and record why. If no, it is one concept, not a section.
+
+## Where OATS encodes these ideas
+
+In the reference implementation the ideas surface as: the okf integration's
+capture protocol (instances write, no judging), the memory-harvest agent
+(the judge, holding the bar and the routing table), and per-soul knowledge
+bundles that grow role-specific sections. Swap the format and the mechanics
+change. The ideas above should not.

package/docs/knowledge.md

@@ -0,0 +1,139 @@
+# Knowledge — layer 2
+
+Specialization is accumulated judgment. A specialist remembers what worked,
+what failed, what was decided, and which procedures are worth repeating.
+
+OATS treats knowledge as a pluggable layer. The kernel does not choose a
+memory format. The default integration, `oats-okf`, uses markdown OKF bundles
+for soul knowledge and simple files for instance state.
+
+> **Status and relationship to the turn record (2026-08-21).** This layer is
+> current and stays. It is the *semantic* memory of an agent team — reviewed,
+> de-indexicalized truths that travel with the soul — and is distinct from the
+> *episodic* memory provided by the turn record (`packages/record`: every
+> session captured verbatim, automatically). Today the harvester's input is
+> `notes/*.md`, the working agent's own in-session notes; the planned upgrade
+> (epic `aweb-abfz`) feeds the harvester from the captured record as well, so
+> lessons reach the soul even when an agent wrote no notes and never ran
+> harvest. The judgment machinery described here — the promotion bar, the
+> capture/judge split, the routing between knowledge and skills — is unchanged
+> by that upgrade; only the input channel widens.
+
+## What the kernel does not own
+
+The kernel is memory-agnostic. It provides lifecycle events:
+
+- `soul-scaffold`
+- `spawn`
+- `retire`
+
+A knowledge integration decides what to do with those events. If config
+resolves `knowledge: none`, the kernel creates no `STATE.md`, no `notes/`, no
+knowledge bundle, and no harvest flow.
+
+The ideas behind any of this — what belongs in a soul vs an instance,
+capture vs judgment, consolidation stages — are format-independent and live
+in [knowledge theory](knowledge-theory.md).
+
+## The default: oats-okf
+
+With `knowledge: okf`, the integration creates two memory spaces.
+
+| Space | Files | Purpose |
+|---|---|---|
+| Soul memory | `soul/knowledge/` | Long-term OKF bundle: lessons, decisions, playbooks, references, role-grown sections. |
+| Instance memory | `STATE.md`, `log.md`, `notes/` | Current task state, dated history, and captured insights. |
+
+The instance does not promote its own notes. It captures them, and after
+committing with pending notes it runs `oats okf harvest` (its okf injection
+carries this instruction), which spawns a **memory-harvest** agent. That
+harvester judges the notes and updates the soul; the delivery matches the
+soul's custody — a commit on the instance's branch for repo-resident souls,
+a PR to the soul's home repo for workspace-mode souls, and **direct edits
+with no commit** for local souls (their `local-agents/` home is
+uncommitted by contract). Then it retires.
+
+## Capture and judgment
+
+OATS splits memory work into two roles.
+
+**The working instance captures.** It keeps `STATE.md` current, appends
+milestones to `log.md`, and writes every non-obvious insight to `notes/`.
+It does not decide whether an insight is "important enough" for the soul.
+Capture should be cheap and in-flow.
+
+**The memory-harvest agent judges.** It reads pending notes and applies the
+promotion bar:
+
+> Promote only what is durable and would change what a future instance of
+> this soul does.
+
+For each note it chooses one outcome:
+
+| Outcome | Meaning |
+|---|---|
+| Promote | Move it into the right soul knowledge section, or into a soul skill if it is procedural. |
+| Merge | Fold it into an existing concept or skill. |
+| Drop | Delete it and log why it failed the bar. |
+
+This separation keeps working agents from overthinking memory, and gives
+promotion the deliberate attention it deserves.
+
+## Why instance memory and soul memory differ
+
+Instance memory is indexical. It talks about this task, this branch, this
+moment, this blocker. That is why it lives in `STATE.md`, `log.md`, and
+`notes/`.
+
+Soul memory must be incarnation-invariant. It should remain true for future
+instances, future models, and future sessions. A future instance should be
+able to read a concept and act differently because of it.
+
+Harvest is the conversion between the two. Notes are where an instance tries
+to phrase what it learned without "I, here, now". The harvester checks
+whether that conversion succeeded.
+
+## OKF concept types
+
+OKF itself does not prescribe one vocabulary. OATS conventions use these
+common types:
+
+| Type | Usual home | Meaning |
+|---|---|---|
+| `Instance State` | `STATE.md` | Current working state. Rewritten, not superseded. |
+| `Finding` | `notes/` | A captured observation whose durability is unproven. |
+| `Lesson` | Soul knowledge | A durable behavior-changing conclusion. |
+| `Decision` | `notes/` or soul knowledge | A decision and its rationale. Task-local decisions stay in `STATE.md` or `log.md`. |
+| `Playbook` | Soul knowledge or soul skills | Repeatable steps. Procedure-shaped notes usually become skills. |
+| `Reference` | Soul knowledge | External truth or stable internal reference. |
+
+Souls start with core knowledge sections:
+
+- `lessons/`
+- `decisions/`
+- `playbooks/`
+- `references/`
+
+Souls can grow role-specific sections such as `architecture/`, `codebase/`, or
+`roadmap/`. Add a section when future instances of that soul need to navigate
+that kind of knowledge.
+
+## What a working instance should do
+
+As you work:
+
+1. Keep `STATE.md` accurate. A fresh session should be able to resume from
+   its `# Next` section.
+2. Append dated milestones and decisions to `log.md`.
+3. Write non-obvious insights to `notes/` as one concept per file.
+4. Before every commit, bring memory up to date.
+5. Commit, then run `oats okf harvest` to send your notes to the soul.
+
+Do not hold back a note because you are unsure it is soul-grade. Capture
+first. The harvester judges.
+
+## Without a knowledge integration
+
+`knowledge: none` is valid. The agent gets no OATS memory files, no memory
+briefing, no harvest agent, and no OKF skills. It may still use whatever
+memory conventions the repo or harness already provides.

package/docs/layers.md

@@ -0,0 +1,110 @@
+# The five layers of agent specialization
+
+A capable model in a fresh session is not a specialist. A specialist has
+identity, habits, memory, teammates, and work to track. OATS names those needs
+as five layers.
+
+Two layers are the OATS pattern itself: **soul** and **instances**. The kernel
+implements them directly. The other three are formally defined, exclusive
+contracts: **knowledge**, **messaging**, and **tasks**. An integration is the
+capability package selected to bind one contract to a real tool; general
+capability packages remain additive.
+
+## The layers at a glance
+
+| Layer | Question it answers | Owner |
+|---|---|---|
+| **Soul** | Who is this agent, and how does it grow? | Kernel |
+| **Knowledge** | Where does learning live, and how is it promoted? | Integration |
+| **Instances** | How does a soul run work in the world? | Kernel |
+| **Messaging** | How can this instance be reached by the team? | Integration |
+| **Tasks** | Where does shared work state live? | Integration |
+
+## 1. Soul — durable expert identity
+
+A soul is what an agent *is* when no session is running. It contains the
+agent's operating doc (`AGENTS.md`), its own skills, and any long-term
+knowledge its knowledge layer provides.
+
+A soul is committed and reviewed like code. It has no terminal, no network
+identity, and no current task. It is the expert template that compounds over
+many incarnations.
+
+The kernel owns this layer. The shape of a soul is the pattern itself:
+`soul.yaml`, canonical files, symlinks, and directory layout. Deployment
+capabilities compose into instances and never redefine or mutate the soul.
+
+## 2. Knowledge — learning that survives sessions
+
+Specialization requires memory. The knowledge layer decides where memory
+lives, what kinds exist, and how learning moves from an instance into the
+soul.
+
+The kernel is memory-agnostic. It only provides lifecycle events such as
+`soul-scaffold`, `spawn`, and `retire`. A knowledge integration
+uses those events to create memory files, teach the protocol, and run
+promotion.
+
+The default `oats-okf` integration creates an OKF bundle in the soul and
+`STATE.md`, `log.md`, and `notes/` in instances. Instances capture what they
+learn, and after committing with pending notes run `oats okf harvest`, which
+spawns a memory-harvest agent that judges notes and promotes
+what belongs in the soul.
+
+If config resolves `knowledge: none`, none of this exists. The agent works
+with whatever memory its harness or repo already provides.
+
+See [Knowledge](knowledge.md).
+
+## 3. Instances — the soul doing work
+
+An instance is one running incarnation of a soul. It has a home directory, a
+work tree, a task briefing, metadata, and possibly episodic memory.
+
+Instances are disposable by design. Sessions crash, context windows fill, and
+models change. The soul survives. With a knowledge integration, what matters
+feeds back into the soul as the instance works.
+
+The kernel owns this layer: spawn, exact skill/instruction composition,
+retire, work modes, tmux windows, metadata, and lifecycle hook points.
+(There is no resume command; a retired instance is gone — its session
+transcript survives in the turn record if capture is running.)
+
+See [Souls and instances](souls-and-instances.md).
+
+## 4. Messaging — reachable team identities
+
+Team agents need to reach humans and each other. The messaging layer maps an
+instance name to a communication identity, then cleans that identity up when
+the instance retires.
+
+The default integration is `oats-aweb`. It gives each instance an aweb identity
+and teaches agents to use `aw mail` and `aw chat`.
+
+Messaging is deliberately narrow. It is about communication only. Task
+coordination belongs to layer 5.
+
+## 5. Tasks — shared work state
+
+Work needs a queue and status that outlive any one instance: planned, in
+flight, blocked, done. OATS does not choose the tracker. It only requires that
+agents know where the shared work state lives and how to use it.
+
+There is no shipped default task integration. One deployment can bind Jira,
+another Linear, another GitHub Issues. The LFX-style Jira integration is just
+skills plus an injection that points agents at those skills.
+
+## Why the split matters
+
+Souls and instances are the stable core. Moving them out would leave nothing
+to specialize.
+
+Knowledge, messaging, and tasks vary by team. They should be easy to swap.
+One workspace can run OKF + aweb + Jira. Another can run a team wiki + Slack
++ Linear. A repo can disable messaging with `messaging: none`. The soul stays
+the same kind of object. Only its layer bindings change.
+
+Layer exclusivity prevents two task systems or knowledge protocols from
+competing inside one soul context. Capability targeting still allows another
+soul to select a different provider. See [Integrations](integrations.md) and
+[Capability packages](capabilities.md).

package/docs/migration-from-oas.md

@@ -0,0 +1,122 @@
+# Migrating from OAS to OATS
+
+Status: **the migration path exists in the kernel** — `oats migrate
+--from-oas`, one transactional conversion per scope (plan steps 1–3 below,
+all landed 2026-08-21). What remains is distribution: end users get the
+command with the v0.22.0 release (steps 4–6). This document keeps the facts
+in one place; the work is tracked as epic `aweb-abfy` in this team's aw
+tasks. Audited 2026-08-21 against a live OAS deployment
+(`@oas-framework/oas@0.20.0-aweb.1`).
+
+OATS was published as **OAS** (`@oas-framework/oas`, `@oas-framework/pi`)
+until the 2026-08-13 rename (commit `fa1e646`), which was a deliberate
+clean break: no compatibility shims, and no code in this repo recognizes
+`oas-*` names.
+
+## Do not migrate by hand yet
+
+The dangerous property of the original state was that it failed **quietly**:
+
+- On a scope with `oas-config.yaml`/`oas-lock.json`, `oats status` works
+  (the `agents/` layout is unchanged) — everything looks healthy.
+- But `oats doctor` finds no config, all layers are unresolved, and a spawn
+  produces instances **without the knowledge (`oas.okf`) and messaging
+  (`oas.aweb`) injections**. The compounding-memory and team-comms value
+  disappears with no error.
+- `oats migrate --official --dry-run` on such a scope reported "nothing to
+  migrate" and exited 0 — false success.
+
+Since plan step 1 landed (below), the silence is closed: `oats doctor` names
+an un-migrated OAS scope with the remedy, and every `oats migrate` form —
+plain or guided, dry run or apply — exits nonzero when `oas-config.yaml` /
+`oas-lock.json` are visible from the scope (detection is by name only; the
+kernel never parses OAS files).
+
+## Migrating: `oats migrate --from-oas`
+
+```bash
+oats migrate --from-oas --dry-run --dir <scope>   # full per-scope plan, touches nothing
+oats migrate --from-oas --dir <scope>             # convert this scope
+oats migrate --from-oas --recursive --dir <root>  # every visible OAS scope
+```
+
+One transaction per scope, two phases under one journal:
+
+1. **Rename phase** — `oas-config.yaml` → `oats-config.yaml` (line
+   transform: the `oas:` defaults key becomes `oats:` and capability ids
+   with catalog renames become their successors; comments and every other
+   byte survive), `oas-lock.json` → `oats-lock.json` verbatim, `oas.json` →
+   `oats.json` inside each installed capability dir, and
+   `.oas-scaffold-owners.json` → `.oats-scaffold-owners.json` in `agents/`
+   and `local-agents/` souls with owner ids mapped to their successors.
+2. **Chained guided conversion** — the existing v1→v2 official migration
+   runs on the renamed lock; the catalog's renaming aliases map each
+   `oas.*` entry onto the `oats.*` package that replaces it, re-acquiring
+   the artifacts (stale v1 integrity is resolved by re-acquisition, never
+   recomputed) and cleaning the superseded `oas`-named artifact dirs.
+
+Any failure in either phase restores the scope's original OAS-named bytes.
+A second run finds nothing and exits 0. Executable trust is re-earned after
+conversion (`oats trust` commands are printed), and comments inside your
+config that mention `oas` paths are left untouched — comments are yours.
+
+## The four breaks
+
+1. **File names.** The kernel reads only `oats-config.yaml`
+   (`lib/core.mjs:326`) and `oats-lock.json` (`lib/core.mjs:643`). OAS
+   scopes have `oas-config.yaml`, `oas-lock.json`, `oas.json` inside each
+   installed capability dir, and `.oas-scaffold-owners.json` in souls.
+2. **The config key.** The schema (`docs/oats-config.schema.json`,
+   `additionalProperties: false`) accepts an `oats:` defaults block and
+   rejects the `oas:` block an OAS config carries — renaming the file is
+   not enough.
+3. **Capability ids.** `oas.okf` / `oas.aweb` appear in the config, the
+   lock, and the `.agents/capabilities/installed/<id>/` directory names.
+4. **No catalog aliases.** `package-catalog.json` maps only `oats.*` ids;
+   a hand-renamed lock naming `marketplace:oas.okf` resolves to
+   `available: false` and the guided migration **holds the whole scope**
+   (`lib/core.mjs:3251-3262`, `:1416`).
+
+## Why an OAS user cannot even find OATS
+
+- `@awebai/oats` and `@awebai/oats-pi` are **not yet published**. The
+  v0.22.0 release notes exist and the three manifests are aligned; what
+  remains is the tag and the publish (`.github/workflows/release.yml`, or
+  the runnerless lane in `scripts/release-lane.mjs`).
+- `@oas-framework/oas` is still live on npm (0.21.2 as of 2026-09-03) and
+  **not deprecated**, so the old CLI's `oas update` (which checks that
+  package) never learns OATS exists.
+- The old OAS desktop probes for `@oas-framework/oas`; the new desktop
+  requires `@awebai/oats >=0.22.0 <0.23.0` — old app and new CLI are
+  mutually invisible, so desktop must ship in the same release.
+
+## The plan (epic `aweb-abfy`)
+
+1. **Done.** `oats migrate` / `oats doctor` detect an OAS scope and fail
+   **loud** with the exact remedy (never exit 0 on "nothing to migrate" when
+   `oas-*` siblings exist). `detectOasScopes` in `lib/core.mjs`,
+   `discoverOasScopes` in `lib/packages.mjs`, wired in `bin/oats.mjs`;
+   tests in `test/oas-scope-detection.test.mjs`.
+2. **Done.** Catalog aliases `oas.*` → `oats.*` so legacy locks map instead
+   of holding — as *renaming* aliases (`{ "package": "oats.okf",
+   "capability": "oats.okf" }`), because the replacement packages export the
+   successor ids, never the legacy ones. All seven 0.20 ids are mapped in
+   `package-catalog.json`.
+3. **Done.** `oats migrate --from-oas`: one transactional command covering
+   all four breaks (section above), fixture built from the real deployment
+   shape, idempotent, byte-identical rollback on failure, with a migrated
+   scope reaching green `oats doctor` and spawns composing the knowledge and
+   messaging injections again (`test/from-oas-migration.test.mjs`).
+4. v0.22.0 release: notes and version alignment are **done**; remaining are
+   the tag, npm publish of `@awebai/oats` + `@awebai/oats-pi`, and the
+   desktop GitHub Release.
+5. `npm deprecate` the `@oas-framework/*` packages with a pointer here.
+6. Close the `oats-okf` / `oats-aweb` publication gates so migrated scopes
+   can restore their capabilities under the new ids.
+
+Until 4–6 are done, OAS users (this includes real daily users) should stay
+on `@oas-framework/oas` — it keeps working and loses nothing by
+waiting. The conversion command exists, but until the v0.22.0 release it is
+only reachable from a repo checkout, and until the satellite publication
+gates close the catalog's package refs are not a supported acquisition
+source for migrated scopes.

package/docs/oats-config.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/oats-config.schema.json",
+  "title": "OATS scoped configuration",
+  "$defs": {
+    "settings": { "type": "object", "additionalProperties": true },
+    "binding": {
+      "oneOf": [
+        { "type": "boolean" },
+        {
+          "type": "object",
+          "properties": {
+            "enabled": { "type": "boolean" },
+            "settings": { "$ref": "#/$defs/settings" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "injection-override": { "type": "string", "description": "Override an instruction injection: a config-relative path, none, or default. Convention: .agents/injections/…" },
+    "capabilityTargets": {
+      "type": "object",
+      "properties": {
+        "from": { "type": "string", "description": "Enforced provenance: installed | owned | path:<dir>." },
+        "global": { "$ref": "#/$defs/binding" },
+        "agent-types": {
+          "oneOf": [
+            { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+            { "type": "object", "additionalProperties": { "$ref": "#/$defs/binding" } }
+          ]
+        },
+        "souls": { "type": "object", "additionalProperties": { "$ref": "#/$defs/binding" } },
+        "settings": { "$ref": "#/$defs/settings" },
+        "injection-override": { "$ref": "#/$defs/injection-override" }
+      }
+    },
+    "layerEntry": {
+      "oneOf": [
+        { "const": "none" },
+        {
+          "allOf": [{ "$ref": "#/$defs/capabilityTargets" }],
+          "type": "object",
+          "required": ["capability"],
+          "properties": {
+            "capability": { "type": "string" },
+            "from": true, "global": true, "agent-types": true, "souls": true, "settings": true, "injection-override": true
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "additiveEntry": {
+      "allOf": [{ "$ref": "#/$defs/capabilityTargets" }],
+      "type": "object",
+      "properties": {
+        "from": true, "global": true, "agent-types": true, "souls": true, "settings": true, "injection-override": true
+      },
+      "additionalProperties": false
+    },
+    "workMode": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "properties": {
+            "setup": { "type": "string", "description": "Env-bootstrap command run inside each new worktree after creation (path relative to this config's directory)." }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "team": {
+      "type": "object",
+      "description": "The deployment/team boundary. Closest scope declaring team: wins; used for identity, cross-repo agent discovery (oats status --team), and messaging providers.",
+      "properties": {
+        "name": { "type": "string" },
+        "id": { "type": "string", "description": "Explicit provider team id (e.g. aweb <name>:<namespace>)." }
+      },
+      "required": ["name"],
+      "additionalProperties": false
+    },
+    "agent-types": {
+      "type": "object",
+      "description": "Agent families declared by name; membership is `type: <name>` in each soul.yaml.",
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "null" },
+          {
+            "type": "object",
+            "properties": { "description": { "type": "string" } },
+            "additionalProperties": false
+          }
+        ]
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "properties": {
+        "layers": {
+          "type": "object",
+          "description": "The three exclusive fundamental slots: a capability entry or an explicit none.",
+          "properties": {
+            "knowledge": { "$ref": "#/$defs/layerEntry" },
+            "messaging": { "$ref": "#/$defs/layerEntry" },
+            "tasks": { "$ref": "#/$defs/layerEntry" }
+          },
+          "additionalProperties": false
+        },
+        "additive": {
+          "type": "object",
+          "propertyNames": { "pattern": "^(?:@?[a-z0-9][a-z0-9._-]*[./])[a-z0-9][a-z0-9._/-]*$" },
+          "additionalProperties": { "$ref": "#/$defs/additiveEntry" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "skill-overrides": { "type": "object", "additionalProperties": { "type": "string" } },
+    "templates": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Named oats init templates: local config paths or git URLs whose main branch carries an oats-config.yaml." },
+    "agents-md-injection": { "oneOf": [{ "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } }], "description": "Extra unconditional instruction blocks (adds content; does not override packaged defaults)." },
+    "oats": {
+      "type": "object",
+      "properties": { "injection-override": { "$ref": "#/$defs/injection-override" } },
+      "additionalProperties": false
+    },
+    "work-modes": {
+      "type": "object",
+      "properties": {
+        "worktree": { "$ref": "#/$defs/workMode" },
+        "checkout": { "$ref": "#/$defs/workMode" },
+        "attached": { "$ref": "#/$defs/workMode" }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}