@awebai/oats 0.22.0 → 0.22.1

package/README.md

@@ -16,9 +16,10 @@ session you can enter and steer.
 
 OATS works with **Pi** and **Claude Code**. A team may mix providers and models
 while sharing the same souls, package and config contracts, instance
-lifecycle, and coordination topology. Every conversation an agent has is
-captured into an append-only, searchable **turn record** that outlives models,
-harnesses, and this repository's own designs.
+lifecycle, and coordination topology. On machines where `oats setup` has run,
+the append-only, searchable **turn record** captures supported local transcripts
+and aw client logs. It outlives models, harnesses, and this repository's own
+designs.
 
 ## Contents
 
@@ -63,56 +64,34 @@ harnesses, and this repository's own designs.
   `sibling` relationships, can carry cross-machine identities through a
   messaging layer such as `oats.aweb`, and are visible together in OATS
   Desktop.
-- **Everything is on the record.** Claude Code, Pi, and Codex sessions, plus
-  aweb mail and chat, are captured as signed turns with exact provenance and
-  searched locally with `oats recall`.
+- **Supported conversations stay on the record.** On machines where `oats
+  setup` has run, OATS captures Claude Code, Pi, and Codex transcripts plus aw
+  client logs. It skips sources matched by the local record's ignore list.
+  Native session turns are content-addressed, not signed, and carry exact
+  provenance. Projected aweb mail and chat keep their original message
+  signatures verbatim. Search the captured content locally with `oats recall`.
 
 ## Quick start
 
-Requires Node.js 22 or newer and tmux.
+Follow [Run your first OATS team](docs/first-team.md) for the tested path:
+install the kernel and runtimes, adopt a development configuration, select
+an available harvester model, connect your team, and complete a real task
+through review, harvest, and retirement.
 
 ```bash
 npm install -g @awebai/oats@latest
-pi install npm:@awebai/oats-pi@latest   # only if you run agents in Pi
-```
-
-Initialize a workspace and check it:
-
-```bash
-cd my-workspace
-oats init
-oats doctor
-```
-
-Create a specialist and put it to work:
-
-```bash
-oats create backend-expert --type developers --repo . --work worktree
-oats spawn backend-expert --purpose implement --task "Add rate limiting to the public API"
-oats status --team
-oats retire <instance>
-```
-
-Or adopt a complete reference configuration from an official package:
-
-```bash
+pi install npm:@awebai/oats-pi@latest
+cd /path/to/project
 oats init --package oats.dev --config default
-oats install
 ```
 
-`oats init --package` acquires and exact-locks the full closure, validates the
-chosen template against its providers, writes it as your local
-`oats-config.yaml`, and records the adopted base so `oats config diff` and
-`oats config sync` can compare against it later.
-
-Start capturing the turn record on this machine:
-
-```bash
-oats setup
-oats recall "rate limiting"
-```
+Continue with the guide's model, team, and executable-trust setup before
+spawning. Initialization acquires packages; it does not authenticate a
+runtime or join a messaging team.
 
-A Pi agent can also load the `oats-getting-started` skill and guide the setup.
+See [the first-team example](docs/first-team-demo.md) for the real Pi and
+Claude tasks behind the guide. Existing OAS users: start with
+[the migration command](docs/migration-from-oas.md).
 
 ## How it works
 
@@ -207,10 +186,13 @@ Bare `oats install` restores the exact lock and never advances source state.
 
 ## The turn record
 
-`packages/record` is the load-bearing layer. Every conversation an agent has
-is captured as signed turns in an append-only, content-addressed, replicated
-record with exact provenance, and searched locally through a SQLite full-text
-index. It has no runtime dependencies beyond Node.
+`packages/record` is the load-bearing layer. On each machine where `oats setup`
+has run, it captures Claude Code, Pi, and Codex transcripts plus aw client logs.
+It skips sources matched by that record root's ignore list. Native session
+turns are content-addressed, not signed, and carry exact provenance. Projected
+aweb mail and chat keep their original message signatures verbatim. The
+append-only record can be replicated and searched locally through a SQLite
+full-text index. It has no runtime dependencies beyond Node.
 
 ```bash
 oats setup                 # install capture hooks and the background watcher
@@ -323,6 +305,7 @@ forms. Do not hand-edit the lock or installed stores.
 - [OATS Desktop](docs/desktop.md)
 - [Migration from OAS](docs/migration-from-oas.md)
 - [Release notes](docs/release-notes/)
+- [Architecture proposal, 2026-09-03](docs/2026-09-03-architecture-proposal.md): components, contracts, and what may be replaced (proposal, not shipped behavior)
 
 ## Contributing
 

package/bin/oats.mjs

@@ -2804,13 +2804,17 @@ function createCmd() {
   if (!name || name.startsWith("--")) die("usage: oats create <name> [--local] [--description <d>] [--type <agent-type>] [--repo <r>] [--work worktree|checkout|attached|workspace] [--runtime pi|claude] [--model <m>] [--instructions-file <f>]");
   const local = args.includes("--local");
   const startDir = dirFlag();
-  // --local can BOOTSTRAP a deployment: with no agents/ or local-agents/ yet,
-  // anchor at the enclosing git repo (else the start dir) — people can use OATS
-  // with local agents alone.
+  // `create` BOOTSTRAPS a deployment: with no agents/ or local-agents/ yet,
+  // anchor at the enclosing git repo (else the start dir). It is the command
+  // that populates the roster root, so it must not demand that the root
+  // already exist — that demand was the first thing a new user hit after
+  // `oats init` (a raw stack trace from ensureRoot). Local and committed souls
+  // anchor the same way; writeSoul creates the directories.
   let root = findRoot(startDir);
+  let bootstrapped = false;
   if (!root) {
-    if (!local) root = ensureRoot(startDir); // keeps the pointed error for committed souls
-    else root = join(defaultRepo(startDir) || resolve(startDir), "agents");
+    root = join(defaultRepo(startDir) || resolve(startDir), "agents");
+    bootstrapped = true;
   }
   const instrFile = flag("instructions-file");
   const r = coreCreateAgent(root, {
@@ -2818,7 +2822,8 @@ function createCmd() {
     work: flag("work"), runtime: flag("runtime"), model: flag("model"),
     instructions: instrFile ? readFileSync(instrFile, "utf8") : undefined,
   });
-  if (args.includes("--json")) { console.log(JSON.stringify(r, null, 2)); return; }
+  if (args.includes("--json")) { console.log(JSON.stringify({ ...r, ...(bootstrapped ? { agentsRoot: root } : {}) }, null, 2)); return; }
+  if (bootstrapped) console.log(`Created deployment root ${shortPath(root)} (this scope had no agents/ yet)`);
   console.log(`Created ${r.kind === "local" ? "LOCAL agent (uncommitted — soul lives in local-agents/, gitignored)" : "agent"} "${r.agent}" — soul at ${shortPath(r.soul)}`);
   console.log(`Edit ${shortPath(join(r.soul, "AGENTS.md"))} to define its role, then: oats spawn ${r.agent} --task "..."`);
 }

package/capabilities/oats-authoring/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OATS Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/capabilities/oats-authoring/oats-package.json

@@ -0,0 +1,11 @@
+{
+  "package": "oats.authoring",
+  "version": "1.0.0",
+  "description": "Official additive OATS guidance for capability, skill, and soul authoring.",
+  "compatibility": {
+    "oats": ">=0.19.0"
+  },
+  "capabilities": [
+    "."
+  ]
+}

package/capabilities/oats-authoring/oats.json

@@ -1,12 +1,12 @@
 {
   "capability": "oats.authoring",
   "version": "1.0.0",
-  "compatibility": { "oats": ">=0.6.2" },
+  "compatibility": { "oats": ">=0.19.0" },
   "description": "Additive framework-authoring guidance for capability packages, agent skills, and souls.",
   "requires": [],
   "skills": [
-    "../../skills/integration-authoring",
-    "../../skills/skill-craft",
-    "../../skills/soul-craft"
+    "skills/integration-authoring",
+    "skills/skill-craft",
+    "skills/soul-craft"
   ]
 }

package/capabilities/oats-authoring/skills/integration-authoring/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: integration-authoring
+description: >-
+  Route custom OATS capability-package and integration work to the framework's
+  integrations expert. Use when building, adapting, or debugging a reusable
+  capability, new task/messaging/knowledge integration, oats.json manifest,
+  lifecycle hook, or operational command—not merely activating an existing
+  package. Triggers: "custom integration", "capability package", "integrate
+  our tracker", "new messaging integration", "write an oats.json".
+---
+
+# Capability and integration authoring — delegate
+
+A capability package may ship skills, instance instructions, requirements,
+namespaced commands, and approved hooks. An integration is the constrained
+subtype implementing exactly one fundamental layer. Building either requires
+manifest, security, targeting-boundary, collision, and probe discipline; use
+the framework's **integrations-expert** soul rather than improvising.
+
+If the user only wants an existing package, use:
+
+```bash
+oats install <source>            # external acquisition + exact lock; inactive
+oats trust <id>                  # only if commands/hooks exist
+oats use <id> --global|--type <t>|--soul <s>
+```
+
+## 1. Verify the expert is available
+
+Run `oats status` and confirm the deployment can resolve the `integrations-expert` soul. If it is absent, ask the human which OATS framework deployment owns reusable package work; never locate or import private kernel files.
+
+## 2. Spawn the expert against the user's repository
+
+```bash
+oats spawn integrations-expert \
+  --purpose <package-slug> \
+  --repo <users-workspace-or-repo> \
+  --work checkout \
+  --task '<capability intent; layer if any; skills/instructions/commands/hooks; external tools; desired global/type/soul targets; distribution path>'
+```
+
+Use `--relation child --relative-to <your-instance>` only when the documented workflow makes the expert your child; otherwise leave the operator-origin spawn unrelated. The work tree is the user's repository, where a config-owned local package belongs under `.agents/capabilities/owned/<name>/`. A framework contribution belongs under `capabilities/<name>/` in the framework worktree; an independently published package uses its own repository.
+
+## 3. Brief the design boundary
+
+Tell the expert:
+
+- whether it is additive or implements exactly one of knowledge/messaging/tasks;
+- external requirements and executable surfaces;
+- intended distribution and version/compatibility;
+- desired config-owned targets and settings; and
+- expected skill/instruction/scaffold collisions.
+
+Targets never belong in the manifest. The expert must test exact pi/Claude
+instance materialization, generated instructions, lock/trust behavior,
+command gating, deterministic hooks, and scaffold ownership as applicable.
+
+## 4. Hand off
+
+Report the tmux window (`tmux attach -t pi-agents`). The expert follows its
+package/integration craft, runs a scaffold-only probe, and leaves acquisition
+and activation commands for the user. Its durable lessons harvest back into
+its soul.

package/capabilities/oats-authoring/skills/skill-craft/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: skill-craft
+description: >-
+  How to create, evaluate, and maintain agent skills (SKILL.md files per the
+  Agent Skills standard). Use when writing a new skill, improving or debugging
+  an existing one (skill not triggering, agent ignoring instructions, skill too
+  long), turning a repeated procedure or correction into a skill, deciding
+  whether knowledge belongs in a skill versus the knowledge base versus
+  AGENTS.md, bundling scripts into skills, or evaluating whether a skill
+  actually helps. Based on the agentskills.io creator guides and Anthropic
+  best practices.
+---
+
+# Skill craft — create, evaluate, maintain
+
+A skill is a directory with a `SKILL.md` (YAML frontmatter + markdown body),
+optionally `scripts/`, `references/`, `assets/`. Agents load only `name` +
+`description` at startup; the body loads **only when the description matches
+the task** — the description carries the entire burden of triggering.
+
+## Where does this knowledge belong? (decide first)
+
+- **Repeatable procedure** ("how to do X, again and again") → **skill**.
+- **Declarative fact/decision/lesson** ("what is true and why") → **OKF
+  concept** in the knowledge base (see `okf` skill). Skills may reference
+  concepts for the why.
+- **Applies to every session of this agent** (role, boundaries, core workflow)
+  → **AGENTS.md** (see `soul-craft`). Rule of thumb: AGENTS.md is loaded
+  always — keep it minimal; skills load on demand — put domain workflows there.
+
+## Creating a skill
+
+**Ground it in real expertise — never generate from thin air.** The valuable
+content is what a capable model *doesn't* already know: your APIs, your
+conventions, the corrections you had to make. Best sources: a hands-on task
+you just completed (extract the steps that worked, the corrections given, the
+formats used), runbooks, review comments, real failures and their fixes. A
+skill with generic content ("handle errors appropriately") is worthless — cut
+or ground it.
+
+**Frontmatter rules** (spec + hard-won):
+- `name`: lowercase alphanum + hyphens, ≤64 chars, **must match the directory
+  name**, no leading/trailing/double hyphens.
+- `description`: ≤1024 chars, non-empty. ⚠️ **Use a `>-` block scalar if it
+  contains any `: ` colon-space** — an unquoted colon breaks YAML parsing and
+  the skill silently fails to load. Verify new skills actually load.
+
+**Write the description for triggering** (it's the only thing the agent sees
+before deciding):
+- Imperative: "Use when..." not "This skill does...".
+- Name the **user intents** it serves, not the implementation. Include
+  trigger phrases users actually say, and cover cases where they don't name
+  the domain ("even if they don't mention X").
+- Precise beats broad: an over-broad description fires on near-miss tasks
+  and pollutes context.
+
+**Write the body for a loaded context window** — it competes with everything
+else once loaded:
+- **Only what the agent would get wrong without it.** For every line ask:
+  "would removing this cause mistakes?" No → cut.
+- ≤500 lines / ~5k tokens. Larger → move detail to `references/` and tell the
+  agent **when** to load each file ("read references/errors.md if the API
+  returns non-200"), not just that it exists.
+- **Defaults, not menus**: pick one tool/approach, mention alternatives in
+  one line. Match prescriptiveness to fragility: fragile sequences get exact
+  commands ("run exactly this"); judgment tasks get goals + why.
+- Procedures over answers: teach the approach that generalizes, with one
+  concrete worked example.
+- **Gotchas section** — often the highest-value part: concrete corrections to
+  mistakes the agent *will* make ("the /health endpoint lies; use /ready").
+- For multi-step workflows: an explicit checklist. For fragile output: a
+  template (agents pattern-match better than they follow prose). For
+  correctness-critical work: a validation loop (do → validate → fix → repeat)
+  or plan-validate-execute with a validator script.
+
+**Scripts**: when you see an agent reinventing the same logic across runs,
+write it once, test it, bundle it in `scripts/`, and reference it from the
+body with exact invocations. Prefer zero-dependency scripts; pin versions for
+`npx`/`uvx` one-offs. Scripts should print errors an agent can self-correct
+from ("field X not found — available: a, b, c").
+
+## Evaluating (before trusting)
+
+- **Trigger check**: draft ~10 realistic prompts that *should* fire the skill
+  (varied phrasing, some not naming the domain) and ~10 near-misses that
+  *shouldn't* (share keywords, need something else). Run them; the skill
+  triggered if its body was loaded. Fix the description, not the body, for
+  trigger failures.
+- **Output check**: run 2-3 real tasks **with and without** the skill. If
+  with-skill isn't clearly better, the skill isn't earning its context — cut
+  or sharpen it. Read execution traces, not just outputs: wasted steps mean
+  vague instructions, inapplicable instructions being followed, or menus
+  without defaults.
+
+## Maintaining
+
+- **Every correction is a candidate gotcha.** When a human (or reviewer)
+  corrects an agent following the skill, add the correction to the gotchas —
+  this is the single best maintenance loop.
+- Treat skills like code: prune on every edit; if the agent ignores a rule,
+  the skill is probably too long and the rule is drowning. Test behavior
+  changes by observing runs, not by rereading the text.
+- Never let a skill grow past one coherent unit of work — split like you'd
+  split a function.
+- Log skill changes in the soul's `knowledge/log.md` (`**Update**: skills/x —
+  added gotcha about …`) so knowledge history and skill history stay one
+  timeline. Knowledge maintenance and skill maintenance are the same duty:
+  declarative lessons go to OKF concepts, procedural lessons go to skills,
+  and each should link to the other.

package/capabilities/oats-authoring/skills/soul-craft/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: soul-craft
+description: >-
+  How to author and maintain an agent's soul — its AGENTS.md/CLAUDE.md
+  operating doc, soul.yaml config, and the balance between AGENTS.md, skills,
+  and the OKF knowledge base. Use when creating a new agent (writing its first
+  AGENTS.md), refining an existing soul that underperforms (agent ignores
+  instructions, drifts from its role, bloated operating doc), reviewing a
+  soul's setup, or deciding what goes in AGENTS.md versus a skill versus
+  knowledge. Based on the agents.md standard and Anthropic CLAUDE.md guidance.
+---
+
+# Soul craft — author and maintain agent operating docs
+
+A soul's `AGENTS.md` is loaded **every session of
+every instance**. It is the most expensive real estate in the agent's context:
+everything in it taxes every task, relevant or not. The craft is keeping it
+minimal and pushing everything else to on-demand layers.
+
+**Canonical files:** `AGENTS.md` and `.agents/skills/` are the canonical
+sources; `CLAUDE.md` and `.claude/skills` must always be relative symlinks to
+them, never independent files (the spawner creates these links — if you find a
+real CLAUDE.md file diverging from AGENTS.md, that's a defect: merge and relink).
+
+## The three-layer rule
+
+| Layer | Loaded | Belongs there |
+|---|---|---|
+| **AGENTS.md** | always | Role, boundaries, the default workflow, memory pointers — only what applies to *every* session |
+| **skills/** | on demand (description match) | Domain workflows, repeatable procedures ("how") — see `skill-craft` |
+| **knowledge/** | on demand (index-first) | Facts, decisions, lessons ("what/why") — format per the knowledge integration (default okf) |
+
+The test for every AGENTS.md line: **"would removing this cause mistakes in
+most sessions?"** No → move it to a skill or a knowledge concept, or cut it.
+Bloated operating docs cause agents to ignore the rules that matter — a rule
+being ignored is usually a symptom of too many rules.
+
+## Writing a soul's AGENTS.md
+
+Structure that works (keep the whole thing short — a screen or two):
+
+1. **Role, one paragraph.** Who this agent is, what it owns, where it stops.
+   Boundaries beat capabilities: "you never merge", "you never modify the
+   assignee", "UI belongs to the ui agent" prevent more damage than feature
+   lists add value.
+2. **Operating loop.** The default shape of a work session — for a developer:
+   read ticket → plan in STATE.md → implement in ./work → verify → commit →
+   review loop → hand off. Concrete, not aspirational.
+3. **Verification.** How this agent checks its own work: the build/test/lint
+   commands that must pass, what "done" means. An agent with a check it can
+   run closes its own loop; without one, "looks done" is the only signal.
+   Include exact commands the agent can't guess (`make test-unit`, not
+   "run the tests").
+4. **Memory pointers.** Where its knowledge and state live (knowledge base
+   index, STATE.md discipline). Point, don't duplicate — the protocol lives
+   with your knowledge integration (default okf: the memory-harvest skill).
+5. **Escalation.** When to stop and ask the human or coordinator: the
+   human-gate triggers (security, authz, migrations, contract breaks),
+   plus "report to your spawner, don't self-fix" for infrastructure faults.
+
+Style rules (from the agents.md standard + field experience):
+- Write commands, not prose: `pnpm vitest run -t "<name>"` beats "run the
+  relevant test".
+- Include only what can't be inferred from the repo: conventions that differ
+  from defaults, env quirks, etiquette (branch naming, PR format).
+- Exclude: standard language conventions, file-by-file codebase tours, API
+  docs (link instead), anything that changes weekly (that's knowledge),
+  self-evident advice ("write clean code").
+- Emphasis (**IMPORTANT**, YOU MUST) sparingly — it works, and it stops
+  working when everything is emphasized.
+- The repo's own AGENTS.md (in ./work) covers repo mechanics — the soul doc
+  covers the *role*. Don't duplicate the repo doc; instruct reading it.
+
+## soul.yaml
+
+Keep honest: `repo` (what it works on), `work` (worktree for builders,
+checkout for reviewers/coordinators), `runtime`, `model` (only pin when the
+role needs a specific one — reviewers on a different model than authors),
+`description` (one line; shows in rosters and pickers).
+
+## Maintaining a soul
+
+- **Change AGENTS.md rarely and deliberately** — it defines the agent. The
+  bar: a change in how the agent fundamentally operates, proven by instance
+  experience. Day-to-day lessons go to knowledge; procedures to skills.
+- When an instance repeatedly misbehaves, diagnose in order: (1) is the rule
+  drowning in a bloated doc? → prune the doc; (2) is it ambiguous? → sharpen
+  with a command or example; (3) is it missing? → add it, minimally. Test by
+  observing the next instance's behavior, not by rereading.
+- **Prune on every edit.** Adding a line? Look for two to cut.
+- Log every soul change in `knowledge/log.md` (`**Update**: AGENTS.md — …`)
+  so the soul's evolution is reconstructible.
+- Agents never rewrite their own role or safety boundaries; soul changes that
+  alter behavior go through the human (or a documented review workflow).
+- Periodic review (worth doing when spawning feels off): does the role still
+  match reality? Do skills cover the recurring procedures? Is the knowledge
+  index current? Are the verification commands still correct?
+
+## Bootstrapping a new soul
+
+Fastest path to a *grounded* soul (never write one from imagination):
+1. Do (or supervise) the role's work once in a plain session, noting
+   corrections, commands, and conventions as you go.
+2. Distill: role/boundaries/loop/verification/escalation → AGENTS.md;
+   repeated procedures → first skills; facts and decisions → first knowledge
+   concepts.
+3. Spawn an instance on a real task; watch where it stumbles; fold the
+   corrections back (doc, skill gotcha, or concept — per the three-layer rule).
+Two rounds of this beat any amount of upfront authoring.

package/capabilities/oats-aweb/oats.json

@@ -3,7 +3,7 @@
   "command": "aweb",
   "version": "1.8.0",
   "compatibility": {
-    "oats": ">=0.6.2"
+    "oats": ">=0.19.0"
   },
   "layer": "messaging",
   "description": "Messaging layer via aweb: per-instance team identities + native aw mail/chat skills + cross-machine team roster.",
@@ -16,21 +16,21 @@
     {
       "runtime": "pi",
       "package": "npm:@awebai/pi",
-      "why": "the aweb channel extension for pi sessions \u2014 real-time mail/chat awakenings; without it a pi instance can send with `aw` but is never woken by incoming messages",
+      "why": "the aweb channel extension for pi sessions — real-time mail/chat awakenings; without it a pi instance can send with `aw` but is never woken by incoming messages",
       "install": "https://aweb.ai/docs (installed into pi with `pi install npm:@awebai/pi`)"
     },
     {
       "runtime": "claude",
       "package": "aweb-channel@awebai-marketplace",
       "marketplace": "awebai/claude-plugins",
-      "why": "the aweb channel plugin for Claude Code sessions \u2014 real-time mail/chat awakenings; without it a Claude instance can send with `aw` but is never woken by incoming messages",
+      "why": "the aweb channel plugin for Claude Code sessions — real-time mail/chat awakenings; without it a Claude instance can send with `aw` but is never woken by incoming messages",
       "install": "https://aweb.ai/docs (installs the awebai marketplace and the aweb-channel plugin into Claude Code)"
     }
   ],
   "skills": [
-    "node_modules/@awebai/pi/skills/aweb-messaging",
-    "node_modules/@awebai/pi/skills/aweb-team-membership",
-    "node_modules/@awebai/pi/skills/aweb-identity"
+    "skills/aweb-messaging",
+    "skills/aweb-team-membership",
+    "skills/aweb-identity"
   ],
   "inject": "injects/aweb.md",
   "commands": {

package/capabilities/oats-aweb/skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Juan Reyero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/capabilities/oats-aweb/skills/VENDORED.md

@@ -0,0 +1,26 @@
+# Vendored aweb Agent Skills
+
+These reviewed resources are vendored from the MIT-licensed aweb repository:
+
+- Repository: <https://github.com/awebai/aweb.git>
+- Upstream package: `@awebai/pi@0.2.3`
+- Tag: `pi-v0.2.3`
+- Commit: `812bdeb1be8ed99dbd339a910a153e7b802501d4`
+- Registry integrity: `sha512-SnCT+5Ybh57G7+zwlfw6QRgAoyAVkyhcgRqIPPx47e+UcJdi5REXw9td806LveLEKAx0CwFTyxOInPH6mfs4EA==`
+- License: MIT; see [`LICENSE`](LICENSE)
+
+Vendored trees:
+
+- `aweb-messaging/`
+- `aweb-team-membership/`
+- `aweb-identity/`
+
+To update, check out the named upstream repository at the intended reviewed commit, update the constants in `scripts/sync-vendored-skills.mjs`, then run from this repository root:
+
+```bash
+node scripts/sync-vendored-skills.mjs --source /path/to/aweb
+npm test
+git diff -- capabilities/oats-aweb/skills
+```
+
+The sync command refuses a checkout whose `HEAD` differs from its pinned commit. Review the complete generated diff, upstream license, and triggering descriptions before changing the recorded version/ref. Runtime acquisition never fetches these resources.