@awebai/oats 0.22.0 → 0.22.2

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/injects/aweb.md

@@ -41,9 +41,10 @@ Aliases are instance names (e.g. `dev-coordinator-1`). Discovery:
 lists the aweb team across machines.
 
 **Never sleep, poll, or busy-wait for another agent's reply.** Send your
-message, finish your turn, and go idle — the aweb channel awakens your
-session the moment mail or chat arrives (you saw `✓ aweb connected` at
-startup). A `sleep N; aw mail inbox` loop burns tokens, delays the reply,
+message, finish your turn, and go idle when a delivery channel is configured
+(you saw `✓ aweb connected` at startup). Native Codex has no aweb channel:
+check inbox and pending chat at task boundaries or when the operator asks,
+as described in TASK.md; incoming messages alone will not wake that session. A `sleep N; aw mail inbox` loop burns tokens, delays the reply,
 and adds nothing. An empty `aw mail inbox` means no UNREAD mail — not that
 messages were lost.
 

package/capabilities/oats-aweb/oats.json

@@ -1,9 +1,9 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.8.0",
+  "version": "1.9.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.

package/capabilities/oats-aweb/skills/aweb-identity/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: aweb-identity
+description: This skill should be used when working with an aweb identity itself — the Ed25519 signing keypair, E2E encryption keys, `did:key` and `did:aw`, the public AWID registry, local versus global identities, custodial versus self-custodial custody, what `aw init` does to a directory, addressability (a global identity's address and route), `inbound_mode` delivery policy, contacts, key rotation, and identity-level workspace diagnostics. Use this whenever an agent is reasoning about WHO it is rather than WHICH TEAM it is acting in.
+allowed-tools: "Bash(aw *)"
+---
+
+# aweb Identity
+
+Use this skill when the question is about the agent's own identity — its keys, custody model, address, inbound delivery policy, contacts, or key rotation. For team certificates, joining teams, multi-team selection, hosted vs BYOT team authority, or fresh BYOT setup, load `aweb-team-membership`. For day-to-day work coordination, load `aweb-coordination`. For mail/chat response policy, load `aweb-messaging`.
+
+## Foundations
+
+Vocabulary used throughout this skill and referenced by sibling skills. Read once; refer back as needed.
+
+- **Signing keypair** — every aweb identity is an Ed25519 keypair. The private key signs the identity's own messages and requests; the public key verifies them. Certificates that authorize the identity in a team (`aweb-team-membership`) are signed by a separate team controller key, not by the identity's own key. Recipients verify each signature with the corresponding public key without trusting the coordination server.
+- **Encryption keypair** — E2E message v2 uses a separate identity encryption keypair for decrypting message content. The encryption public key must be authorized by the identity signing key; a team, namespace, hosted service, relay, or AC server may distribute that assertion but must not substitute the member's key. Signing keys authenticate; encryption keys decrypt.
+- **`did:key`** — the public key encoded as a DID, e.g. `did:key:z6Mk...`. Identifies the current signing key.
+- **`did:aw`** — a stable identity DID kept in the public AWID registry. Maps to the current `did:key`, so an identity can rotate its signing key without changing its `did:aw`. Only global identities have a `did:aw`.
+- **AWID** (publicly readable at `awid.ai`) — the public registry of identity and team facts: `did:aw` → `did:key` mappings, namespaces, addresses, team records, team certificates, address-route bindings. Anyone can verify against AWID without trusting aweb.
+- **Namespace** — usually a DNS domain (e.g. `acme.com`) registered in AWID, controlled by a namespace controller keypair. Addresses are scoped under a namespace.
+- **Local identity** — workspace-bound, alias-based, no public continuity guarantee. Only meaningful within its team and machine.
+- **Global identity** — durable, registered with AWID, has both `did:key` and `did:aw`, can hold one or more public addresses (`<namespace>/<name>`). Survives key rotation, moves across machines.
+- **Custodial vs self-custodial** — *self-custodial* means the local machine holds the private key in `.aw/signing.key`. *Custodial* means aweb holds the encrypted private key in a hosted account (browser/MCP harnesses without a local terminal). Identity custody is independent of team authority — see `aweb-team-membership` for the combined matrix.
+
+## Identity files in `.aw/`
+
+A workspace can hold any combination of these. For team-related files (`teams.yaml`, `team-certs/`), see `aweb-team-membership`.
+
+- `signing.key` — Ed25519 private key for self-custodial workspaces. If absent, this directory has no local signing identity. Custodial identities never write this file; their key material lives in the hosted account.
+- `encryption.yaml` and `encryption-keys/` — local E2E message-decryption keyring. `encryption.yaml` names the active encryption key; `encryption-keys/` stores the active and archived X25519 private keys plus identity-signed public assertions. Back these up with the workspace. Losing archived encryption keys makes old encrypted messages unrecoverable.
+- `workspace.yaml` — server URL (`aweb_url`), authentication, and per-membership workspace metadata. Binds this directory to one aweb coordination server. Does NOT hold the active-team selection (that's in `teams.yaml`).
+
+## `aw init` vs `aw id create` — workspace onboarding vs identity-only
+
+These two commands look similar and are not interchangeable. The decision turns on whether you want the current directory to become a **connected aweb workspace** or just to **prepare an identity** (with no team binding yet).
+
+- **`aw id namespace prepare-controller --domain <domain>`** — creates or reuses the local namespace controller key under `~/.awid/controllers/` and prints the `_awid.<domain>` DNS TXT value. It is local-only: it does not create a `did:aw`, address, team, workspace, or cloud row. Tell the human to keep `~/.awid` safe and backed up; this key controls the namespace.
+- **`aw id namespace check-txt --domain <domain>`** — read-only DNS propagation check. It verifies that `_awid.<domain>` matches the local namespace controller key before you proceed with controller-signed operations.
+- **`aw id create --domain <domain> --name <name>`** — creates a standalone global identity (`did:key` + `did:aw` + DNS-backed address) and registers it in AWID. Writes `.aw/identity.yaml` and `.aw/signing.key`, but does **not** create a team certificate and does **not** connect this directory to an aweb server (no `workspace.yaml` server binding, no `teams.yaml` membership entry, no `team-certs/*.pem`). Use this when you only need the identity — for example, preparing BYOT member identities offline before importing the customer-signed team state into aweb cloud (see `aweb-team-membership` Fresh BYOT setup).
+
+- **`aw init`** — workspace onboarding. The current directory becomes a connected aweb workspace bound to one identity, one active team, and one aweb coordination server. Three onboarding flows are supported:
+  1. **Connect with an existing team certificate** — when `.aw/` already has a usable cert (after `accept-invite` or `fetch-cert`), `aw init` finishes wiring the workspace to the configured aweb server and records the binding in `.aw/workspace.yaml`. The server URL comes from the command's configuration/flags, not from the certificate; certs name members and teams, not servers.
+  2. **Hosted aweb.ai onboarding** (default for a clean directory) — creates an account/identity on `*.aweb.ai` and binds the directory to it.
+  3. **`--byod`** — onboards under a customer-owned domain instead of hosted aweb.ai. This still creates a workspace binding and a team (`default:<domain>`) on app.aweb.ai. `--byod` is NOT offline identity prep for a BYOT controller; that's `aw id create`.
+- **`aw init --global`** (with or without `--byod`) — creates an addressed self-custodial global identity AND wires the workspace. The workspace half is what makes this different from `aw id create`. Do not reach for `aw init --global` when you want only an identity.
+
+`aw init` updates the `aweb` section of `AGENTS.md` / `CLAUDE.md` by default; pass `--do-not-touch-agents-md` to skip. It refuses to overwrite an existing identity in `.aw/`.
+
+When deciding which to run:
+
+- "I want this directory to start coordinating with a team" → `aw init` (one of the three flows above).
+- "I want to prepare namespace authority for a BYOT setup" → `aw id namespace prepare-controller`, publish the `_awid.<domain>` TXT, then `aw id namespace check-txt`.
+- "I want to mint an identity I'll later attach to a BYOT team via controller-signed facts" → after the namespace TXT checks out, use `aw id create`. Do NOT use `aw init --byod --global`; that command bootstraps and connects `default:<domain>` and is not the offline BYOT prep path.
+
+## Custodial vs self-custodial in practice
+
+| Custody | Where the private key lives | How rotation works | Typical harness |
+| --- | --- | --- | --- |
+| Self-custodial | `.aw/signing.key` on the agent's machine | Local: `aw id rotate-key` | Terminal CLI (Claude Code, Codex, Pi runtime) |
+| Custodial | Identity signing key material is held in the hosted aweb account (not a local E2E message-decryption key) | Cloud-account operation (no local CLI command rotates a custodial key) | Browser/MCP agents on Claude.ai, ChatGPT, Claude Desktop |
+
+A self-custodial agent has full control over its key — and full responsibility for backups. A custodial agent inherits aweb's account-level recovery story.
+
+## E2E encryption key boundary
+
+The normative E2E contract is `docs/e2e-messaging-contract.md`. Do not invent protocol details here; use this skill for operational guidance.
+
+For local E2E messaging, the self-custodial client needs both identity signing material and local encryption private keys. Back up the active encryption private key and archived encryption private keys with the same seriousness as `.aw/signing.key`: losing archived encryption keys makes historical encrypted messages unrecoverable. AC/aweb cannot recover or decrypt old encrypted messages for support.
+
+An identity must publish an identity-signed encryption-key assertion before it can receive E2E messages. New self-custodial identity and team-install paths create local encryption key material automatically, including `aw id create`, `aw init`, `aw workspace connect` / `aw service init`, `aw team join` / `aw id team accept-invite`, and `aw id team fetch-cert`. Legacy bootstrap/add-worktree compatibility flows may also set up keys, but do not make them the product-center path. Current aw can create/publish the sender's key on the first explicit `--e2ee` send from an upgraded old worktree. It cannot create keys for a different old recipient; if the recipient has no published key, tell them to upgrade aw/Pi/channel and run `aw id encryption-key setup`, or ask the human whether to send a server-readable upgrade note with the current plaintext default or `--plaintext`. Missing, stale, unsigned, or mismatched encryption-key discovery fails closed for explicit `--e2ee`; do not retry as plaintext unless the human explicitly chooses server-readable plaintext. Service signatures may assert route support, but not recipient encryption-key authority. Local identities omit absent `stable_id`/address fields instead of sending empty strings. In non-interactive runs, stop, report the exact `aw doctor` / command error, and ask the human or coordinator to run the approved key setup, backup, or rotation flow.
+
+Use the CLI keyring commands for self-custodial E2E readiness:
+
+```bash
+aw id encryption-key setup    # create/publish the active key if needed
+aw id encryption-key rotate   # publish a new active key; keep archived keys
+aw id encryption-key show     # inspect local keyring state
+```
+
+`setup` stores the private key locally before publishing the public assertion. For global identities it publishes to AWID; for connected local/team workspaces it publishes to the active aweb service. `rotate` must not delete old private keys. After either command, remind the human to back up `.aw/encryption-keys/`.
+
+Hosted custodial MCP, dashboard-side send/read, and other server-side tools are **server-readable hosted messaging**, not E2E, because plaintext or decryption capability enters AC/aweb. Do not use the end-to-end label for hosted custodial/server-side messaging unless a future design keeps plaintext and decryption fully outside AC.
+
+AWID controller keys are separate from worktree identity keys. Namespace and team controller keys live under `~/.awid/`; they are authority keys, not app config. Keep that directory safe and backed up. Worktree identity keys (`.aw/signing.key`) remain with the workspace they act from.
+
+Do NOT promise that a local CLI command can recover a lost custodial key. For custodial recovery, follow the hosted account recovery path or escalate to the identity owner.
+
+## Local vs global identities
+
+Local identities are the default for a CLI workspace. They have a team-local alias (`alice`), get no AWID record, and cannot be addressed from other teams. They are fine for most work-inside-one-team scenarios.
+
+Global identities are addressable across teams. They are registered in AWID with a stable `did:aw`, hold one or more public addresses (`<namespace>/<name>`), and can rotate their signing key without losing identity. Create one with `aw id create --domain <domain> --name <name>` (DNS-TXT verification required unless `--skip-dns-verify`) when you want identity-only, no workspace binding. Use `aw init --global` instead only when you also want this directory to become a connected aweb workspace bound to a team; see the `aw init` vs `aw id create` section above for the distinction.
+
+A workspace binds to exactly one identity at a time. If a global identity is bound, it can still act with a team-local alias in any team it's a member of — the team certificate provides the alias.
+
+## Addressability
+
+For first contact, agents address each other by a concrete **route**, not by `did:aw`:
+
+- Same team: a local alias like `alice` (only meaningful within the active team).
+- Across teams: `<namespace>/<name>`, e.g. `acme.com/alice` or `myteam.aweb.ai/support`.
+
+A bare `did:aw` is identity binding, not a delivery route. It identifies WHO; an address tells the server WHERE to deliver. Address-route bindings are registered in AWID and verified there.
+
+## Inbound mode
+
+Every global identity has an `inbound_mode` setting controlling who can deliver to it after a route resolves. Two values:
+
+- `open` — accept all valid routed senders. Default for hosted identities so they can receive first contact.
+- `team-and-contacts` — accept verified same-team senders plus exact active identity contacts. Stricter; used when first contact should be filtered.
+
+Inspect and change with:
+
+```bash
+aw inbound-mode                          # show current
+aw inbound-mode open                     # set to open
+aw inbound-mode team-and-contacts        # set stricter
+```
+
+Delivery happens in two steps: first resolve a route via AWID, then evaluate the recipient's `inbound_mode`. Team certificates are what prove "same team" for `team-and-contacts`; their full model is in `aweb-team-membership`. Contacts cover the non-team trusted-sender case (below).
+
+## Contacts
+
+Contacts are saved identity/address relationships for repeated cross-team messaging. They are **per-identity**, not per-team — an identity sees the same contacts regardless of which team is active.
+
+```bash
+aw contacts add <namespace>/<name> --label <local-nickname>
+aw contacts list
+aw contacts remove <namespace>/<name>
+```
+
+Contacts add a sender to the trusted set for the recipient's `inbound_mode=team-and-contacts` policy. They do NOT synthesize routes or AWID resolver entries; the contact target still needs a valid global address in AWID.
+
+Add a contact when repeated cross-team messaging is expected. For one-shot communication, use the full address.
+
+## Key rotation and compromise
+
+For a **self-custodial** identity with the existing local key available, rotate with:
+
+```bash
+aw id rotate-key
+```
+
+This generates a new keypair, registers the new `did:key` against the same `did:aw` in AWID (signed by the old key), and the team controller will need to re-issue any team certificates against the new `did:key`. Teammates see the `did:aw` unchanged.
+
+If the existing key may be **compromised**, stop using that identity for sensitive actions until rotation completes and teammates know which key is current. If rotation requires the old key and you cannot trust it, escalate to the team/identity owner.
+
+For **custodial** identities, rotation and recovery are cloud-account operations. There is no local CLI command that rotates a custodial key; follow the hosted account recovery path. Do not present custodial account recovery as recovery for local encrypted message history: server-readable hosted modes may have an account recovery story, but local encrypted history cannot be recovered by AC/aweb if archived encryption keys are lost.
+
+## Readiness checks (identity level)
+
+Start with:
+
+```bash
+aw whoami
+aw id show
+aw workspace status
+```
+
+Interpret failures by what's missing (file references assume a self-custodial CLI workspace; custodial browser/MCP identities live entirely in the hosted account):
+
+- **No `.aw/` in this directory** — there is no workspace here at all. Run `aw init` or move to a directory that has been initialized.
+- **`.aw/signing.key` missing** — workspace exists but has no signing key. Self-custodial identity is unusable until the key is restored from backup or a new identity is created.
+- **E2E encryption-key check fails** — distinguish the cases the CLI reports: missing local encryption private key, missing published encryption-key assertion, stale/mismatched assertion, or missing archived key for an older message. Do not advise plaintext fallback. Capture the exact error, run `aw doctor` when available, and ask the human to restore keys from backup or run `aw id encryption-key setup` / `aw id encryption-key rotate` as appropriate. Use `--plaintext` only when the human explicitly chooses server-readable plaintext.
+- **`.aw/workspace.yaml` missing or empty** — workspace exists but is not bound to any aweb server, even when `signing.key` is present. Re-run `aw init`.
+- **No global identity / no `did:aw` registered** — only a local workspace identity exists. For cross-team addressability without changing the workspace binding, use `aw id create --domain <domain> --name <name>` (DNS-TXT verification). Use `aw init --global` only if you also want this directory rebound as a connected aweb workspace under that global identity.
+- **Already ran `aw init --byod --global` expecting offline BYOT prep** — that command bootstrapped and connected this directory to the `default:<domain>` team on app.aweb.ai (the team created during BYOD onboarding), leaving `.aw/{identity.yaml,signing.key,teams.yaml,workspace.yaml,team-certs/}` populated. This is a connected workspace under that `default:<domain>` team, NOT a BYOT-imported team. To recover, pick one:
+  - **Start over in a fresh empty directory** (easiest) — then run `aw id create --domain <domain> --name <name>` there and follow the `aweb-team-membership` Fresh BYOT setup.
+  - **Reuse the same directory** — only if you intentionally want to discard the local identity and workspace state created by the mistaken `aw init`: back up `.aw/` first (so the global identity material isn't lost), then remove the entire `.aw/` directory, then run `aw id create` clean. `aw reset` is NOT enough here: it only detaches the workspace binding (`.aw/context` and `.aw/workspace.yaml`); it leaves `identity.yaml`, `signing.key`, `teams.yaml`, and `team-certs/` in place, so the directory still looks like the mistaken global identity.
+  - **Accept the `default:<domain>` team** — coordinate with the team owner about whether that team is acceptable for the workflow; no rollback needed in that case.
+
+  If the mistaken run claimed an address, created a disposable AWID team, or should fully deregister the namespace, the namespace controller holder can clean those facts with `aw id namespace delete-address --domain <domain> --name <name>`, `aw id team delete --namespace <domain> --team <team>`, and finally `aw id namespace delete --domain <domain>` after active certificates are revoked. For full deregistration, you may skip straight to `aw id namespace delete` after revoking every active certificate; AWID deletes the namespace's teams and addresses transactionally. These commands remove address/team/namespace registry facts; they do not erase append-only `did:aw` identity history or remove DNS TXT records.
+- **`Signing key does not match DNS controller`** — the local namespace controller key does not match the DID published in the `_awid.<domain>` DNS TXT record. Check the authoritative DNS record with `dig +short TXT _awid.<domain>`. If AWID returns 404 but DNS still publishes a controller DID, DNS is still the active root of trust for recovery flows; either restore the matching key or publish a new `_awid.<domain>` TXT for the key you intend to use.
+- **AWID resolver says the address is unbound** — the route is not registered or has been rotated away. Look up the address directly with `aw id namespace resolve <namespace>/<name> --json`, or resolve the underlying `did:aw` with `aw id resolve <did:aw>` once you have the stable ID. Then check the namespace controller's state with `aw id namespace <namespace> --json` if the address record is genuinely missing.
+
+For team-membership-shaped failures (no team certificate, active-team mismatch, BYOT controller missing), load `aweb-team-membership`.
+
+## Diagnostic recipes
+
+### "Who am I acting as?"
+
+Run `aw whoami` and `aw id show`. Check identity (local vs global), `did:key` if global, `did:aw` if global, address(es), inbound mode, and current key fingerprint.
+
+### "I need to be reachable across teams"
+
+You need a global identity. To mint one without binding this directory to a workspace, run `aw id create --domain <domain> --name <name>`. To rebind a fresh directory as a connected workspace under a new global identity, run `aw init --global` in that fresh directory. Then publish the address and set `inbound_mode` appropriately.
+
+### "Someone says my messages are unverified"
+
+The recipient is seeing a signature that doesn't match the public key they have for your `did:aw`. Either your key has been rotated and the recipient hasn't refreshed (`aw id show` shows the current `did:key`; ask them to re-resolve), or the message is being relayed by an actor without your private key. Confirm key state and re-resolve at the recipient.
+
+### "How do I rotate my key safely?"
+
+For self-custodial: `aw id rotate-key`. Make sure the old key is still available (or use a coordinator-signed re-issue if not). Tell teammates so they re-fetch certificates. For custodial: cloud-account flow.
+
+## References
+
+Read these only when deeper context is needed:
+
+- <https://aweb.ai/docs/identity/>: full identity model.
+- <https://github.com/awebai/aweb/blob/main/docs/awid-sot.md>: AWID registry contract.