@awebai/oats 0.22.0

package/docs/configuration.md

@@ -0,0 +1,482 @@
+# Configuration
+
+OATS configuration lives in `oats-config.yaml` at a laptop, workspace, or
+repository root. It owns deployment policy: agent-type declarations, the three
+fundamental layer slots, additive capability activations, settings,
+exclusions, instruction overrides, and work modes.
+
+The CLI is the primary config author: `oats init` scaffolds the full shape,
+`oats use` writes capability entries, `oats create --type` sets a soul's type.
+Hand-editing is valid but never required. Packages never declare their
+targets. See the machine-readable
+[`oats-config.schema.json`](oats-config.schema.json) alongside the examples
+below.
+
+## Scopes
+
+Resolution walks from the soul's repository upward:
+
+1. repository;
+2. containing workspace(s); and
+3. laptop/home.
+
+A `global` binding applies to all souls governed by the level that declares
+it. It does not escape that scope. This lets a laptop set defaults, a workspace
+add shared team capabilities, and one repository make a narrower choice.
+
+```text
+~/oats-config.yaml
+~/workspace/oats-config.yaml
+~/workspace/service/oats-config.yaml
+```
+
+Use `oats doctor <context> --soul <name>` to inspect the result.
+
+## Schema
+
+```yaml
+name: example-service
+
+# ── Team — the deployment boundary. The closest scope declaring team: wins;
+# every repo under it resolves the same team (identity, discovery, messaging).
+team:
+  name: example-engineering
+  # id: example-engineering:example.com   # explicit provider team id (e.g. aweb <name>:<namespace>)
+
+# ── Agent types (families) ── declared here by name; each soul opts in via
+# `type: <name>` in its soul.yaml. Capability entries can target them.
+agent-types:
+  developers:
+    description: Agents that build and maintain the service
+  reviewers:
+    description: Agents that review changes
+
+capabilities:
+  # Fundamental layers — exclusive slots; a capability entry or an explicit none.
+  layers:
+    knowledge:
+      capability: oats.okf
+      from: installed
+      settings:
+        harvest-model: github-copilot/gpt-5.5
+      # injection-override: .agents/injections/capabilities/oats.okf.md
+    messaging: none
+    tasks:
+      capability: oats.linear
+      from: installed
+      agent-types:
+        developers:
+          enabled: true
+          settings: {team: ENG}
+      # injection-override: .agents/injections/capabilities/oats.linear.md
+
+  # Additive capabilities — non-exclusive; target global, agent-types, or souls.
+  additive:
+    example.review:
+      from: installed
+      agent-types:
+        developers:
+          enabled: true
+          settings:
+            depth: normal
+      souls:
+        security-reviewer:
+          enabled: true
+          settings:
+            depth: exhaustive
+      # injection-override: .agents/injections/capabilities/example.review.md
+
+skill-overrides:
+  review: example.review
+
+# ── Work modes — optional per-mode env bootstrap (briefings are packaged, not overridable).
+work-modes:
+  worktree:
+    # Runs inside each NEW worktree right after `git worktree add` — env setup
+    # scripts (installs, .env copying, direnv/mise). Relative to this config's dir.
+    setup: scripts/setup-worktree.sh
+
+# ── OATS defaults — the framework's baseline instruction block.
+oats:
+  # injection-override: .agents/injections/oats-defaults/oats.md
+
+# Extra unconditional instruction blocks for every instance at this scope.
+agents-md-injection:
+  repository: injects/repository.md
+```
+
+### `team`
+
+`team:` declares the deployment boundary — typically at the workspace scope.
+The closest scope declaring it wins, so every repo under `~/lfx` resolves the
+same team. `name:` is required; `id:` optionally pins the provider team id
+(for aweb, the canonical `<name>:<namespace>` form). Three things hang off
+it:
+
+- **Identity**: instances record their team in `instance.json` and their
+  TASK.md briefing; hooks receive `OATS_TEAM_NAME`/`OATS_TEAM_ID`/`OATS_TEAM_SCOPE`.
+- **Discovery**: `oats status --team` lists agents across every `agents/`
+  root in the team scope (the scope's own plus each member repo's), so an
+  agent in one repo can see teammates defined at the workspace level or in
+  sibling repos. There is no explicit member list — every repo under the
+  team scope is a member by construction.
+- **Cross-repo spawn/retire**: `oats spawn <soul>` and `oats retire <instance>`
+  resolve across the team scope's repos when the name isn't found locally
+  (unique match wins; ambiguity errors with guidance to pass `--dir`). The
+  instance homes with the soul's own repo, works in that repo, and resolves
+  that repo's config chain — spawning from elsewhere changes nothing about
+  the instance itself.
+- **Messaging**: the aweb integration joins spawned instances into the
+  resolved team (id wins over name; a bare name is resolved against the aweb
+  root's memberships), with the instance name as the discoverable alias.
+  Because every instance joins with its own name, the aweb team roster is
+  also the **cross-machine directory**: `oats aweb roster` lists team members
+  wherever they run, complementing the local `oats status --team`.
+
+### `agent-types`
+
+Agent types are agent families. Config declares type names (optionally with a
+description); membership is **not** listed in config — each soul opts in with
+an optional single `type: <name>` in its `soul.yaml` (`oats create --type <t>`
+sets it; `oats type add <name>` declares it in config). A type is identity: what kind of agent a soul is travels with the
+soul, while config decides what each type gets. Tags, dynamic selectors, and
+instance names are not supported.
+
+### `capabilities.layers`
+
+The three fundamental layers — `knowledge`, `messaging`, `tasks` — are
+exclusive slots with an explicit home. Each slot holds either a capability
+entry (`capability: <id>` plus optional `from`, targets, `settings`,
+`injection-override`) or the explicit string `none`, which suppresses an integration
+inherited from an outer scope. A slot absent from a config inherits from
+outer scopes; `oats init` writes all three so the resolution is visible.
+
+The entry's capability must declare the same layer in its manifest; a
+mismatch is an error, as is a layer-declaring capability placed under
+`additive`. A layer entry with no explicit targets is globally enabled at
+that scope.
+
+### `capabilities.additive`
+
+Additive capabilities are non-exclusive packages keyed by capability ID. A
+declaration without `global`, `agent-types`, or `souls` is acquired but
+inactive. A target value can be `true`, `false`, or an object containing
+`enabled` and `settings`.
+
+For a soul, matching global, agent-type, and soul bindings compose. Setting
+precedence is:
+
+1. soul;
+2. matching agent-type;
+3. global;
+4. at equal target specificity, closer config scope.
+
+Conflicting values at equal specificity and the same scope are errors. OATS
+never uses YAML order as an implicit winner. `enabled: false` uses the same
+precedence, allowing global enable → type exclusion → soul re-enable.
+
+### `from` (provenance)
+
+`from:` documents where the artifact must come from, and resolution enforces
+it: `installed` (acquired into `.agents/capabilities/installed/`,
+lock-governed — from the official marketplace by id, a git URL, or a local
+path), `owned` (authored at this scope under `.agents/capabilities/owned/`),
+or `path:<dir>` (development declaration pointing at a manifest directory).
+A mismatch between `from:` and the discovered artifact origin is an error.
+`from: bundled` was removed. Official capabilities are acquired like any other
+package, and acquisition never grants executable trust — approve executable
+surfaces explicitly with `oats trust <capability>`.
+
+### `injection-override`
+
+Every injectable item — each capability entry, each work mode, and the `oats:`
+kernel block — accepts an `injection-override:` key: a config-relative path replaces
+the packaged instruction file, `none` suppresses it, and `default` restores
+it. The closest scope declaring the key wins. Scaffolded configs carry these
+as commented-out lines pointing at the conventional locations:
+
+```text
+.agents/injections/capabilities/<capability-id>.md
+.agents/injections/oats-defaults/oats.md
+```
+
+The clean path is `oats inject eject <capability|oats>`: it copies
+the packaged default to the conventional path and sets the key — the ejected
+file then deliberately stops tracking package updates. Overrides are not
+allowed on `from: owned`/`path:` entries: the scope owns the package source,
+so its `injects/` file is edited directly.
+
+### `skill-overrides`
+
+Spawn fails when two sources contribute the same skill directory name. An
+explicit override maps that name to the winning source (`soul`, `kernel`, a
+capability ID, or a config source shown by doctor). Overrides are deliberate;
+OATS never keeps whichever filesystem entry happened to be discovered first.
+
+### Instruction sources
+
+`agents-md-injection` adds unconditional config-owned instruction files (it
+adds content; it does not override packaged defaults — that is `injection-override:`).
+Capability packages can ship an `inject`; work modes have their own source.
+
+OATS reads the canonical soul `AGENTS.md`, composes selected blocks in a new
+instance file, and records every source. It never reconciles deployment
+instructions into the committed soul; spawn and doctor are the composition
+boundaries.
+
+### Work modes
+
+Work modes remain soul/instance topology, not capability packages:
+
+- `worktree`: dedicated branch/worktree;
+- `checkout`: shared current checkout;
+- `attached`: another instance's work tree;
+- `workspace`: the whole team scope — cross-repo coordinators that read all
+  member repos but never edit them (their soul's knowledge updates arrive as
+  PRs to the soul's home repo).
+
+Work-mode briefings are packaged with the kernel and are not overridable;
+the only work-mode configuration is `setup:` — an env-bootstrap command that
+runs inside each fresh worktree after creation (a lot of teams prefer a
+script that sets up the environment: installs, .env copying, direnv/mise).
+Its failure warns without hiding the instance.
+
+## Acquisition and lockfile
+
+External acquisition writes `oats-lock.json` beside the declaring config in
+`lockfileVersion: 2`. It records two levels — a `packages` map (source, exact
+commit, selected path, payload integrity, dependencies) and a `capabilities`
+map (each materialized capability's version, provider package, path, artifact
+integrity, and executable trust):
+
+```json
+{
+  "lockfileVersion": 2,
+  "packages": {
+    "example.engineering": {
+      "source": "git:https://example.invalid/engineering.git@v1.4.2",
+      "version": "1.4.2",
+      "commit": "0123456789abcdef0123456789abcdef01234567",
+      "path": "oats-package",
+      "integrity": "sha256-…",
+      "dependencies": []
+    }
+  },
+  "capabilities": {
+    "example.review": {
+      "version": "1.4.2",
+      "package": "example.engineering",
+      "path": "capabilities/example-review",
+      "integrity": "sha256-…",
+      "trusted": false
+    }
+  }
+}
+```
+
+No command silently updates this record. Changed capability integrity blocks the
+artifact and resets its trust. `oats trust <id>` approves commands, hooks, and
+launch-environment authority only for the exact locked artifact integrity, and
+official identity never grants it.
+Declarative skill/instruction capabilities need a valid lock but no executable
+approval. Capabilities authored under a scope's `.agents/capabilities/owned/`
+follow their reviewed source provenance. Materialized artifacts live in
+`.agents/capabilities/installed/<id>/` beside their lock, stay gitignored, and
+are re-materialized by bare `oats install` with integrity verification.
+
+Legacy `lockfileVersion: 1` locks (per-capability marketplace installs) remain
+readable and usable. `oats migrate` converts a scope to the revised v2 lock
+**all-or-nothing**: if any entry cannot map to a package yet, the whole scope
+stays byte-identical v1 and keeps working, and a successful run converts the
+entire scope at once. There is no residue container — a converted lock never
+carries leftover v1 entries. The earlier transitional v2 shape — capability
+lists on package rows, a persistent `.agents/packages/installed/` store — is
+rejected as an invalid lock and recreated by a fresh acquisition, never
+migrated. See `docs/capabilities.md` (“Distribution packages”), the schemas
+`docs/oats-package.schema.json` / `docs/oats-lock.schema.json`, and
+`docs/design/package-engine-contract.md`.
+
+## CLI
+
+```bash
+oats init [--raw] [--template <name|path|git-url>] [--knowledge <id|none>] [--messaging <id|none>] [--tasks <id|none>]
+oats install [<id|git-url|path>] [--dir <dir>]  # acquire; bare form restores; inactive by default
+oats trust <capability> [--dir <dir>]
+oats use <capability> [--global|--type <t>|--soul <s>] [--disable] [--settings k=v [k2=v2 ...]]
+oats use none --layer <layer>
+oats type add <name> [--description <d>]   # declare an agent type
+oats type list
+oats inject eject <capability|oats>  # materialize an injection override
+oats create <name> --type <agent-type> ...
+oats doctor [context] --soul <name> [--json]
+```
+
+`oats init` writes only explicitly selected defaults, acquiring marketplace
+layer capabilities into this scope's installed/ store as needed; it does not
+activate every acquired package. `oats use`
+places a layer-declaring capability under `capabilities.layers.<layer>` and
+everything else under `capabilities.additive`, regenerating the conventional
+injection comments; custom comments inside the `capabilities:` block are not
+preserved.
+
+`oats use` activates **into a config file**, so it needs one at this scope or an
+outer one. In a scope with no `oats-config.yaml` anywhere in its chain, a
+capability already present in that scope's own `installed/` or `owned/` store
+fails with `E_NO_CONFIG` naming the initialization to run first — exactly
+`oats init --raw --dir <scope>`, which is offline, deterministic and writes only
+the minimal config — and then the same `oats use` command again. It never
+reports the capability as unacquired, and it writes nothing: authoring a
+scope's first config is `oats init`'s job.
+
+### Templates
+
+`oats init --template <name|path|git-url>` seeds the new config from a template
+config file: a local path, a git URL whose default branch carries an
+`oats-config.yaml`, or a name resolved through a `templates:` map declared in an
+outer scope (typically the laptop config):
+
+```yaml
+# ~/oats-config.yaml
+templates:
+  personal: ~/templates/personal-oats-config.yaml
+  team: https://example.invalid/oats-templates.git
+```
+
+A template seed is copied once. `init` copies the content, records provenance in
+a leading `# template:` comment, rewrites `name:`, strips the `templates:` map,
+and runs a restore so declared external capabilities are present. Later template
+edits never propagate silently.
+
+### Package config templates
+
+When the config and its capability providers travel together, prefer
+`oats init --package <source> [--config <name>]`. It validates a reference config
+template shipped by a distribution package and writes it as your local
+`oats-config.yaml`, recording the exact template as a commit-safe adopted base
+with package, template, and commit provenance. `oats config diff` and
+`oats config sync` compare against that base later. Installing the package alone
+adopts no template. See [Distribution packages](packages.md).
+
+## Fundamental-layer disable
+
+An inner scope can suppress an inherited integration without selecting a
+replacement:
+
+```yaml
+capabilities:
+  layers:
+    tasks: none
+```
+
+`oats use none --layer tasks` writes this. Pre-v0.9 spellings (`groups:`,
+top-level `layers:`, flat `capabilities.<id>` maps, `source:`,
+`agents-md-injection` on capability entries) are rejected with pointed
+migration errors. Key names are matched as own properties only, so a key
+spelled `constructor` or `toString` is reported as an unsupported key, never as
+a renamed one. `__proto__` is refused outright by every YAML reader — the
+kernel's and the desktop app's own read-only reader — and by the commands that
+WRITE config keys (`oats use --settings`, `--soul`, `--type`), all with
+`unsafe-config-key`: assigning it rewrites the parsed mapping's prototype
+instead of becoming data, which would hide the entry from every key validator.
+The kernel fails closed and reports the offending file; the desktop reader
+degrades that document to "not visible", per its read-only contract.
+
+Text that cannot be written as ONE YAML scalar on one line is refused. The
+policed inputs are exactly: `oats use --settings` keys and values, `oats use
+--soul` and `--type` names, `oats type add --description`, and the scaffolded
+`name:` value that `oats init` (in every form) and the first `oats use` / `oats
+type add` at a fresh scope take from the target directory's basename — a
+basename is filesystem input, so one carrying a newline would otherwise write
+arbitrary top-level blocks into the config.
+
+Refused: a control character (a newline in a `--settings` value used to inject
+whole extra capability entries into the file) or one of the three line breaks
+outside that range (U+0085, U+2028, U+2029 — U+2028/U+2029 made the reader drop
+the written line entirely, so the command reported success for a setting that
+was not there afterwards); leading or trailing whitespace a read would strip; a
+leading YAML structure indicator (`#`, `|`, `>`, `&`, `*`, `!`, `%`, `@`,
+`` ` ``, `,`, a quote, a flow bracket, or `- `/`? `/`: `); for a VALUE, an
+embedded `" #"` (which opens a trailing comment, so the rest would be dropped
+on read) and an empty value (`key:` with nothing after it reads back as an
+empty map, not an empty string); and — for keys and `--soul`/`--type` names —
+the `:` and `#` that end a key token. Those fail with `unsafe-config-value`
+(values, the scaffolded name included) or `unsafe-config-key` (keys and names),
+and nothing is written.
+
+The guarantee is a round trip through the OATS reader, not conformance to an
+external YAML parser: ordinary values are untouched because those characters
+are structural only in first position, so `expr=2 > 1`, `tag=v1.0#build`,
+`list=a,b` and even `mode=a: b` come back exactly as they were written.
+
+## Worked examples
+
+### All souls use OKF; only developers use Linear
+
+```yaml
+agent-types:
+  developers:
+    description: Souls with type: developers in their soul.yaml
+capabilities:
+  layers:
+    knowledge:
+      capability: oats.okf
+      from: installed
+    tasks:
+      capability: oats.linear
+      from: installed
+      agent-types:
+        developers:
+          enabled: true
+          settings: {team: ENG, project: Product}
+```
+
+### Laptop default with repository exclusion
+
+Laptop:
+
+```yaml
+capabilities:
+  layers:
+    messaging:
+      capability: oats.aweb
+      from: installed
+```
+
+Solo repository:
+
+```yaml
+capabilities:
+  layers:
+    messaging: none
+```
+
+### One marketplace capability for one soul
+
+```yaml
+capabilities:
+  additive:
+    vendor.security-review:
+      from: installed
+      souls:
+        security-reviewer: true
+```
+
+Acquire and trust executable surfaces before spawn; target activation alone
+does not download, update, or approve code.
+
+## Tmux scrolling during init
+
+Interactive `oats init` offers to add `set -g mouse on` to the existing
+`~/.tmux.conf` or XDG tmux config so agent windows scroll normally with a mouse
+or trackpad. It never changes terminal keyboard mappings. Agent-led and
+scripted setup should pass the user's answer explicitly:
+
+```bash
+oats init --tmux-mouse
+oats init --no-tmux-mouse
+oats init --raw --tmux-mouse
+```
+
+An accepted change is idempotent and reloads a running tmux server when
+possible. This machine preference is separate from capability acquisition and
+activation.

package/docs/conventions.md

@@ -0,0 +1,73 @@
+# Conventions — canonical files and generated views
+
+OATS uses one canonical source for durable soul content and generated,
+instance-local views for deployment composition.
+
+## Operating documents
+
+```text
+soul/AGENTS.md                  # canonical role instructions
+soul/CLAUDE.md -> AGENTS.md
+instance/AGENTS.md              # generated regular file
+instance/CLAUDE.md -> AGENTS.md
+```
+
+Never maintain an independent soul `CLAUDE.md`. Config-dependent capability,
+work-mode, and workspace instructions belong only in generated instance
+`AGENTS.md`; they must not be reconciled into the committed soul.
+
+Generated blocks use `<!-- oats:<source> src=<file> -->` markers for
+provenance. Edit the canonical soul, source file, or target binding, then spawn
+a new instance. `oats doctor --soul <name>` previews the same final composition.
+
+## Skills
+
+The only OATS-managed runtime skill root is the instance:
+
+```text
+instance/.agents/skills/                    # canonical exact set
+instance/.claude/skills -> ../.agents/skills
+```
+
+Spawn copies kernel + soul-private + active capability skills into real
+instance-local directories there. Directory symlinks are not used because
+harness recursive discovery may not descend through them. Packages retain
+skills in their own artifact; activation selects them for materialization. Config-level `.agents/skills` is not an OATS capability source
+or an ambient runtime discovery root.
+
+Pi starts spawned sessions with ambient skill and context discovery disabled
+and the one instance path explicit; its globally configured extensions remain
+enabled. Claude runs provider-native: it reads the instance's `.claude/skills`
+and `CLAUDE.md` symlinks, and the operator's own user and project
+configuration — skills, plugins, settings — stays in effect. Neither runtime
+gets a redirected config home. `composition.materialized.runtimePosture` in
+`instance.json` records what each instance actually exposes.
+`oats-getting-started` is the sole pre-workspace ambient bootstrap.
+
+Duplicate skill directory names are errors unless config's `skill-overrides`
+selects a source.
+
+## Package locations
+
+```text
+<package>/capabilities/<name>/oats.json                 # the official marketplace (install source, not ambient)
+<level>/.agents/capabilities/installed/<name>/oats.json # acquired (gitignored, restorable)
+<level>/.agents/capabilities/owned/<name>/oats.json     # authored at this scope (source; committed where the scope is a repo)
+<level>/oats-lock.json                                  # external source/integrity/trust
+```
+
+## Quick map
+
+| Thing | Canonical location |
+|---|---|
+| Config | `<level>/oats-config.yaml` |
+| Acquisition lock | `<level>/oats-lock.json` |
+| Soul operating doc | `soul/AGENTS.md` |
+| Soul Claude view | `soul/CLAUDE.md -> AGENTS.md` |
+| Soul-private skills | `soul/skills/` |
+| Instance operating doc | `instance/AGENTS.md` (generated) |
+| Instance skill set | `instance/.agents/skills/` |
+| Instance metadata | `instance/instance.json` |
+
+Symlinks prevent compatibility paths from drifting. Generated regular files
+separate canonical portable identity from scope-dependent runtime policy.