@awebai/pi 0.1.14 → 0.1.16

package/README.md

@@ -40,7 +40,7 @@ Then restart pi (recommended; ensures packages/extensions are reloaded) or run:
 
 When aweb channel events arrive, the extension wakes the running pi session with:
 
-- the mail/chat/control/work event contents
+- the mail/chat/control/work event contents for legacy/server-readable events, or metadata-only notifications for encrypted v2 E2E content until local decryption succeeds
 - sender and conversation metadata
 - sender/authorship verification status
 - a prominent warning if verification fails or is unknown
@@ -53,6 +53,8 @@ Delivery behavior:
 
 On the first ready session for a workspace/team, the extension also injects a one-time welcome message that orients the agent to the aweb work loop and points at the bundled skills. The welcome is sentinel-gated under `~/.config/aw/pi-welcome.json` so reloads do not repeat it.
 
+For encrypted v2 E2E messages, plaintext may be shown or injected only after local decryption in the Pi/workspace process. Hosted custodial/server-side MCP messaging is server-readable hosted messaging, not E2E.
+
 The agent responds with normal shell commands, for example:
 
 ```bash
@@ -78,11 +80,13 @@ This package exposes the canonical aweb Agent Skills via `pi.skills`, so one ins
 - channel awakenings
 - instructions for using `aw` effectively
 
-Bundled v1 skills:
+Bundled skills:
 
-- `aweb-coordination` — session/work-loop policy for teams of agents.
+- `aweb-bootstrap` — creating or joining a team from a template; team source, work directory, and worktree-agent decisions.
+- `aweb-identity` — the agent's own identity: keypair, `did:key`/`did:aw`, the AWID registry, custodial vs self-custodial custody, addressability, inbound mode, contacts, key rotation.
+- `aweb-team-membership` — joining teams, multi-team membership, hosted vs BYOT team authority, team certificates, fresh BYOT setup, custody × authority.
+- `aweb-coordination` — session/work-loop policy for teams of agents: tasks, claims, locks, roles, instructions, worktrees.
 - `aweb-messaging` — mail/chat/channel-awakening response policy.
-- `aweb-team-membership` — joining teams, multi-team membership, hosted vs BYOT, custody, addressability, inbound mode, and contacts.
 
 The canonical skill bodies live at the repository root under `skills/`; this package copies them into the npm package for Pi rather than maintaining a separate Pi-only fork. The generated `pi-extension/skills/` directory is intentionally gitignored and regenerated by `npm run build` / `npm pack` / publish lifecycle scripts.
 
@@ -93,5 +97,6 @@ The extension uses `@awebai/channel-core`, shared with `@awebai/claude-channel`,
 - aweb signed API calls
 - SSE event subscription and reconnect
 - mail/chat fetch and read/ack behavior
+- encrypted-message event handling that keeps server notifications metadata-only and leaves plaintext display to local decryption
 - sender signature verification and trust normalization
 - formatting awakenings with trust warnings

package/dist/index.js

@@ -5904,6 +5904,42 @@ function escapeJSON3(s) {
   return result;
 }
 
+// ../channel-core/dist/local_aw.js
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+function createLocalAWDecryptProvider(options) {
+  const awCommand = options.awCommand || process.env.AW_BIN || "aw";
+  return {
+    async mailMessage(messageID) {
+      const id = messageID.trim();
+      if (!id)
+        return null;
+      const { stdout } = await execFileAsync(awCommand, ["mail", "show", "--message-id", id, "--json"], { cwd: options.workdir, timeout: 15e3, maxBuffer: 1024 * 1024 });
+      const payload = parseJSONOutput(stdout);
+      return (payload.messages || []).find((msg) => msg.message_id === id) || null;
+    },
+    async chatMessage(sessionID, messageID) {
+      const session = sessionID.trim();
+      const id = messageID.trim();
+      if (!session || !id)
+        return null;
+      const { stdout } = await execFileAsync(awCommand, ["chat", "history", "--session-id", session, "--message-id", id, "--limit", "1", "--json"], { cwd: options.workdir, timeout: 15e3, maxBuffer: 1024 * 1024 });
+      const payload = parseJSONOutput(stdout);
+      return (payload.messages || []).find((msg) => msg.message_id === id) || null;
+    }
+  };
+}
+function parseJSONOutput(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed)
+    throw new Error("aw returned empty JSON output");
+  const start = trimmed.indexOf("{");
+  if (start < 0)
+    throw new Error("aw JSON output did not contain an object");
+  return JSON.parse(trimmed.slice(start));
+}
+
 // ../channel-core/dist/channel.js
 import { dirname as dirname2, join as join2 } from "node:path";
 import { homedir } from "node:os";
@@ -6003,11 +6039,12 @@ function createChannelClient(config) {
 async function startChannelLoop(options) {
   const dispatched = /* @__PURE__ */ new Set();
   const deliveryStore = options.deliveryStore || await DeliveryStore.load(DEFAULT_DELIVERY_STORE_PATH);
+  const localDecrypt = options.localDecrypt || (options.workdir ? createLocalAWDecryptProvider({ workdir: options.workdir, awCommand: options.awCommand }) : void 0);
   const log = options.log || (() => {
   });
   for await (const event of streamAgentEvents(options.client, options.signal)) {
     try {
-      await dispatchAgentEvent({ ...options, deliveryStore }, dispatched, event);
+      await dispatchAgentEvent({ ...options, deliveryStore, localDecrypt }, dispatched, event);
       pruneDispatched(dispatched);
     } catch (err2) {
       log(`[aw-channel] dispatch error: ${err2}`);
@@ -6089,6 +6126,16 @@ async function dispatchMailEvent(options, dispatched, event) {
       continue;
     }
     const from = senderDisplayAddress(msg.from_alias, msg.from_address);
+    const decrypt = await resolveMailForDelivery(options, msg);
+    if (!decrypt.ok) {
+      await options.onAwakening({
+        kind: "mail",
+        content: "",
+        meta: encryptedDeliveryFailureMeta("mail", from, msg.message_id, conversationID, decrypt.error),
+        deliveryIntent: "wake"
+      });
+      continue;
+    }
     const trust = await normalizeMessageTrust(options, msg, msg.from_alias, msg.from_address, msg.to_did, msg.to_stable_id);
     msg.verification_status = trust.status;
     if (trust.stored)
@@ -6138,6 +6185,16 @@ async function dispatchChatEvent(options, dispatched, event) {
       continue;
     }
     const from = senderDisplayAddress(msg.from_agent, msg.from_address);
+    const decrypt = await resolveChatForDelivery(options, event.session_id, msg);
+    if (!decrypt.ok) {
+      await options.onAwakening({
+        kind: "chat",
+        content: "",
+        meta: encryptedDeliveryFailureMeta("chat", from, msg.message_id, conversationID, decrypt.error, event.session_id),
+        deliveryIntent: event.sender_waiting ? "steer" : "wake"
+      });
+      continue;
+    }
     const trust = await normalizeMessageTrust(options, msg, msg.from_agent, msg.from_address, msg.to_did, msg.to_stable_id);
     msg.verification_status = trust.status;
     if (trust.stored)
@@ -6177,6 +6234,58 @@ async function dispatchChatEvent(options, dispatched, event) {
 async function normalizeMessageTrust(options, msg, fromAlias, fromAddress, toDID, toStableID) {
   return options.trust.normalizeTrust(options.pinStore, msg.verification_status, senderTrustAddress(fromAlias, fromAddress), msg.from_did, msg.from_stable_id, toDID, toStableID, msg.rotation_announcement, msg.replacement_announcement, msg.signed_from || fromAddress || fromAlias || "");
 }
+async function resolveMailForDelivery(options, msg) {
+  if (!isEncryptedMessage(msg))
+    return { ok: true };
+  if (!options.localDecrypt?.mailMessage) {
+    return { ok: false, error: "local aw decrypt provider is not configured" };
+  }
+  try {
+    const decrypted = await options.localDecrypt.mailMessage(msg.message_id);
+    if (!decrypted || typeof decrypted.body !== "string") {
+      return { ok: false, error: "local aw did not return decrypted mail body" };
+    }
+    Object.assign(msg, decrypted);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function resolveChatForDelivery(options, sessionID, msg) {
+  if (!isEncryptedMessage(msg))
+    return { ok: true };
+  if (!options.localDecrypt?.chatMessage) {
+    return { ok: false, error: "local aw decrypt provider is not configured" };
+  }
+  try {
+    const decrypted = await options.localDecrypt.chatMessage(sessionID, msg.message_id);
+    if (!decrypted || typeof decrypted.body !== "string") {
+      return { ok: false, error: "local aw did not return decrypted chat body" };
+    }
+    Object.assign(msg, decrypted);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+function isEncryptedMessage(msg) {
+  return msg.content_mode === "encrypted_v2" || msg.message_version === 2 || msg.encrypted_envelope !== void 0;
+}
+function encryptedDeliveryFailureMeta(type2, from, messageID, conversationID, error, sessionID) {
+  const meta = {
+    type: type2,
+    from,
+    message_id: messageID,
+    encrypted: "true",
+    decrypted: "false",
+    decrypt_error: error
+  };
+  if (conversationID)
+    meta.conversation_id = conversationID;
+  if (sessionID)
+    meta.session_id = sessionID;
+  return meta;
+}
 function isTrustedVerificationStatus(status) {
   return status === "verified" || status === "verified_custodial";
 }
@@ -6338,7 +6447,7 @@ To enable aweb awakenings in pi:
 
 2. Then restart pi or run /reload.
 
-Once initialized, incoming aweb mail/chat/control events will wake this pi session with message contents and sender verification status. Use the aw CLI from pi's bash tool to respond.`;
+Once initialized, incoming aweb mail/chat/control events will wake this pi session with message content for legacy/server-readable events, or metadata-only notifications for encrypted E2E content until local decryption succeeds, plus sender verification status. Use the aw CLI from pi's bash tool to respond.`;
 }
 function welcomeKey(cwd, teamID, alias) {
   return `${WELCOME_VERSION}:${teamID}:${alias}:${cwd}`;
@@ -6363,7 +6472,7 @@ async function markWelcomeSeen(key) {
 function welcomeMessage(alias, teamID) {
   return `aweb for Pi is ready.
 
-You are connected as ${alias} in team ${teamID}. This package gives Pi two aweb capabilities: real-time channel awakenings for mail/chat/control events, and the canonical aweb skills for the aw CLI.
+You are connected as ${alias} in team ${teamID}. This package gives Pi two aweb capabilities: real-time channel awakenings for mail/chat/control events, and the canonical aweb skills for the aw CLI. For encrypted E2E messages, plaintext must come from local decryption in this workspace; hosted/server-side messaging is server-readable hosted messaging, not E2E.
 
 First moves:
 
@@ -6486,6 +6595,7 @@ ${message}`),
         stableID: config.stableID
       },
       signal,
+      workdir: ctx.cwd,
       onAwakening: (awakening) => sendAwakening(pi, awakening),
       log: (message) => {
         if (ctx.hasUI) ctx.ui.notify(message, "warning");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/pi",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Aweb for Pi: real-time channel awakenings, aw CLI onboarding, and aweb skills.",
   "type": "module",
   "main": "./dist/index.js",

package/skills/aweb-bootstrap/SKILL.md

@@ -76,10 +76,36 @@ Canonical templates:
 - awebai/aweb-team-company-surfaces (6 agents)
   Use when you want a cross-functional team: direction/engineering/operations/support/outreach/analytics.
 
-Fork vs use-as-is:
+Fork/edit vs use-as-is:
 
 - Use as-is to learn the flow or to run a standard team.
-- Fork when you want to customize roles, responsibilities, or instructions.
+- Clone or fork when you want to customize roles, responsibilities, or instructions before provisioning.
+- It is safe to edit the template checkout before applying it; `aw team bootstrap` reads `team.yaml`, `roles/`, `docs/`, and `agents/` from the local template directory at run time.
+
+## Customizing a template before applying it
+
+When the human wants different agents, role playbooks, names, or instructions, do not try to patch the generated workspaces after bootstrap. Clone/edit the template first, then bootstrap the edited local directory.
+
+Typical safe flow:
+
+```bash
+git clone https://github.com/awebai/aweb-team-dev-review.git my-team-template
+cd my-team-template
+# edit team.yaml, roles/*.md, docs/team.md, agents/<responsibility>/AGENTS.md
+aw team bootstrap . --dry-run --work-directory /path/to/work
+aw team bootstrap . --work-directory /path/to/work
+```
+
+What to edit:
+
+- `team.yaml` roles: add/remove role names and point each to a role file.
+- `team.yaml` agents: add/remove responsibility workspaces and set each `role_name`, `default_name`, and `default_alias`.
+- `team.yaml` worktrees: add/remove local git-worktree agents for code work.
+- `roles/*.md`: change operational playbooks installed with `aw roles`.
+- `docs/team.md`: change shared team instructions installed after the anchor connects.
+- `agents/<responsibility>/AGENTS.md`: change per-workspace startup context.
+
+Default agent names are accepted automatically. Only use `--ask-for-agent-names` when a human specifically wants an interactive rename prompt during bootstrap.
 
 ## Before running bootstrap (safety checks)
 
@@ -159,7 +185,7 @@ Supported sources:
 
 Decision recipe:
 
-- Human says “make me a new team” and has no existing aw context: use hosted (`--username` or interactive prompt). If using `--yes`, include `--username`; otherwise omit `--yes` so hosted onboarding can prompt.
+- Human says “make me a new team” and has no existing aw context: use hosted (`--username` or interactive prompt).
 - Human has a dashboard/API key: use `AWEB_API_KEY=... aw team bootstrap ...`; do not ask for `AWEB_URL` unless they are using a non-default stack.
 - Human pasted an invite: use `--invite-token`.
 - Human is already inside the team workspace that should own the new agents: use current workspace forwarding (no explicit source).

package/skills/aweb-bootstrap/references/bootstrap-scenarios.md

@@ -30,13 +30,13 @@ Checklist:
   - awebai/aweb-team-dev-review for a minimal 2-agent setup.
   - awebai/aweb-team-company-surfaces for a 6-agent cross-functional setup.
 
-Example (using an existing local work directory, with an explicit hosted username so --yes does not need prompts):
+Example (using an existing local work directory):
 
-  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --yes --username alice --work-directory /path/to/work
+  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --username alice --work-directory /path/to/work
 
 Example (clone the work repo into the template checkout):
 
-  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --yes --username alice --work-repo-url https://github.com/ORG/REPO.git
+  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --username alice --work-repo-url https://github.com/ORG/REPO.git
 
 Notes:
 
@@ -47,6 +47,25 @@ Notes:
 
   where derived-name is the git-style repo directory name (basename with .git stripped).
 
+## Scenario: customize the template before applying it
+
+Goal: change roles, agent responsibilities, names, aliases, or instructions before any team state is created.
+
+Checklist:
+
+- Clone or fork the template first.
+- Edit `team.yaml`, `roles/*.md`, `docs/team.md`, and `agents/<responsibility>/AGENTS.md` as needed.
+- Run `aw team bootstrap . --dry-run ...` from the template checkout to validate.
+- Bootstrap the local directory only after the plan looks right.
+
+Example:
+
+  git clone https://github.com/awebai/aweb-team-dev-review.git my-team-template
+  cd my-team-template
+  # edit team.yaml / roles / docs / agents
+  aw team bootstrap . --dry-run --work-directory /path/to/work
+  aw team bootstrap . --username alice --work-directory /path/to/work
+
 ## Scenario: BYOT (bring your own team)
 
 Goal: bootstrap a team under a namespace/domain you control.
@@ -60,7 +79,6 @@ Checklist:
 Example shape (values are placeholders):
 
   aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git \
-    --yes \
     --namespace example.com \
     --team dev \
     --work-directory /path/to/work

package/skills/aweb-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aweb-identity
-description: This skill should be used when working with an aweb identity itself — the Ed25519 signing keypair, `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.
+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 *)"
 ---
 
@@ -13,6 +13,7 @@ Use this skill when the question is about the agent's own identity — its keys,
 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.
@@ -26,6 +27,7 @@ Vocabulary used throughout this skill and referenced by sibling skills. Read onc
 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
@@ -55,10 +57,30 @@ When deciding which to run:
 | 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 | Encrypted in the hosted aweb account | Cloud-account operation (no local CLI command rotates a custodial key) | Browser/MCP agents on Claude.ai, ChatGPT, Claude Desktop |
+| 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 service init`, `aw id team accept-invite`, `aw id team fetch-cert`, and bootstrap/add-worktree flows. Current aw also creates/publishes the sender's key on the first default-E2E 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 `--plaintext`. Missing, stale, unsigned, or mismatched encryption-key discovery fails closed; do not retry as plaintext unless the human explicitly chooses `--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 tell users that hosted custodial/server-side messaging is end-to-end encrypted 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.
@@ -123,7 +145,7 @@ This generates a new keypair, registers the new `did:key` against the same `did:
 
 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.
+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)
 
@@ -139,6 +161,7 @@ Interpret failures by what's missing (file references assume a self-custodial CL
 
 - **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:

package/skills/aweb-messaging/SKILL.md

@@ -10,6 +10,12 @@ This skill is the playbook for aweb channel awakenings. When you receive an inje
 
 It also covers explicit user requests to send mail or chat through aweb.
 
+E2E messaging boundary: for encrypted v2 messages, AC/aweb servers route ciphertext and local clients decrypt before showing or injecting plaintext. Hosted custodial MCP, dashboard-side send/read, and server-side tools are **server-readable hosted messaging**, not E2E. Do not describe hosted custodial/server-side messaging as end-to-end encrypted.
+
+Legacy plaintext boundary: existing plaintext mail/chat remains legacy/server-readable while retained and must not be described as retroactively E2E. Mail and chat send E2E by default. If an intended E2E send fails because keys, capability, route support, or version support is missing/stale/mismatched, stop and report the exact failure. Do not resend as plaintext unless the human explicitly chooses `--plaintext`.
+
+Mixed-version boundary: old pre-E2E aw/channel/Pi clients may not have published recipient encryption keys yet. A current aw CLI creates/publishes the sender's local encryption key before default-E2E sends, but it cannot create keys for another recipient. If the recipient lacks a key, report that they need to upgrade aw/Pi/channel and publish a key. Use `--plaintext` only for an explicit human-approved server-readable upgrade note.
+
 If the event says to use the aw CLI and the response is not obvious, continue with this skill. For broader work coordination, load `aweb-coordination`. For recipient addressability, inbound-mode policy, team membership, or multi-team identity questions, load `aweb-team-membership`.
 
 ## Read the event first
@@ -73,9 +79,19 @@ aw chat extend-wait <from> "working on it, 2 minutes"
 
 Before replying to a confusing chat, inspect pending/open/history state. Do not use chat for broad FYI updates. Send mail instead.
 
+Mail and chat are E2E by default. Do not add `--e2ee`; it is a deprecated compatibility no-op. Use `--plaintext` only when the human explicitly asks for server-readable plaintext and policy allows it.
+
+```bash
+aw chat send-and-wait <alias-or-address> "..." --start-conversation
+aw chat send-and-leave <alias-or-address> "..."
+aw chat extend-wait <from> "working on it"
+```
+
+Read paths such as `aw chat pending`, `aw chat history`, and channel listen/decrypt paths show plaintext only after local decryption. If the encrypted send fails because a key, capability, route, or version is missing or stale, stop and report the exact error; do not resend as plaintext unless the human explicitly chooses `--plaintext`.
+
 ## Harness surfaces
 
-Terminal agents, Pi, and Claude Code can use the `aw` CLI directly. Custodial MCP/OAuth agents may have equivalent MCP tools for mail/chat. For Claude Code, do not use deprecated `aw run claude`; install the `aweb-channel` plugin for push events. Use the harness-native surface, but keep the same decision policy:
+Terminal agents, Pi, and Claude Code can use the `aw` CLI directly. Custodial MCP/OAuth agents may have equivalent MCP tools for mail/chat, but those hosted/server-side tool calls are server-readable hosted messaging unless plaintext and decryption stay fully outside AC/aweb. For Claude Code, do not use deprecated `aw run claude`; install the `aweb-channel` plugin for push events. Use the harness-native surface, but keep the same decision policy:
 
 - async update → mail
 - synchronous blocker → chat
@@ -95,6 +111,8 @@ Harness support differs:
 
 The channel is inbound only. Use `aw mail` or `aw chat` to respond.
 
+For E2E messages, channel/Pi/`aw run` may show plaintext only after local decryption in the user's workspace or client process. Server notifications and SSE payloads should be metadata-only for encrypted content. Recipient E2E capability and encryption keys must be identity-authorized; a service signature can assert route support only. If an event or tool error says an encryption key/capability is missing, stale, or mismatched, fail closed and report the error. Do not silently resend as plaintext. If the local channel/Pi process was upgraded from a pre-E2E version, run `aw id encryption-key setup` in the workspace before expecting it to receive encrypted messages.
+
 ## Control and work awakenings
 
 For control signals:

package/skills/aweb-team-membership/SKILL.md

@@ -12,8 +12,8 @@ Use this skill when the question is about teams — joining, leaving, switching
 
 This skill builds on the identity vocabulary in `aweb-identity` (keypair, `did:key`, `did:aw`, AWID, custodial vs self-custodial). Read that section first if any of those terms are unfamiliar. Team-specific additions:
 
-- **Team controller** — a keypair separate from member identities. Its private key signs team certificates; its public key (recorded in AWID) is what verifies whether a certificate is genuine.
-- **Team certificate** — a signed statement that a specific `did:key` is a member of a specific team, with an alias and metadata. Public; replicated in AWID. Stored locally in `.aw/team-certs/*.pem`.
+- **Team controller** — a keypair separate from member identities. Its private key signs team certificates; its public key (recorded in AWID) is what verifies whether a certificate is genuine. Team controllers authorize membership; they do not decrypt member conversations and must not substitute a member's E2E encryption key.
+- **Team certificate** — a signed statement that a specific `did:key` is a member of a specific team, with an alias and metadata. Public; replicated in AWID. Stored locally in `.aw/team-certs/*.pem`. A certificate proves team membership; it is not a message-decryption key.
 - **Team id** — canonical form is `<name>:<namespace>` (e.g. `personal:acme.com`, `aweb:juan.aweb.ai`). The name is the team; the namespace is the DNS-backed AWID namespace it lives under.
 - **Hosted vs BYOT team authority** — *hosted* means aweb holds the team controller signing key (for `*.aweb.ai` namespaces). *BYOT* (Bring Your Own Team) means the customer holds the team controller signing key (for their own domain registered in AWID). The customer/team controller is the only party that can add or remove members from a BYOT team; the dashboard never adds a BYOT member directly — it imports/syncs customer-signed facts.
 
@@ -30,13 +30,15 @@ Identity custody (where the private key lives) and team authority (who holds the
 
 | Team authority | Identity custody | Meaning |
 | --- | --- | --- |
-| Hosted | Custodial | aweb manages team authority AND holds the encrypted identity key (browser/MCP). |
+| Hosted | Custodial | aweb manages team authority AND holds hosted identity signing key material (browser/MCP). Messaging in this mode is server-readable hosted messaging, not E2E. |
 | Hosted | Self-custodial | aweb manages team authority; the terminal agent holds its own `.aw/signing.key`. |
 | BYOT | Self-custodial | the customer controls team authority; the agent holds its own key. |
 | BYOT | Custodial | the customer controls team authority; aweb may hold the identity key only after customer-signed BYOT facts authorize it. |
 
 A custodial identity has **no BYOT team authority** until the customer-signed team certificate and address facts match. Do not infer team authority from identity custody.
 
+For E2E messaging, custody and team membership are still not enough by themselves: the recipient's encryption public key must be identity-authorized as described in `docs/e2e-messaging-contract.md`. Team/namespace authority may distribute that assertion, but it must not replace the member's key. If an encryption-key check fails, do not suggest a team-controller workaround or plaintext fallback; stop and route the user to the approved identity/key setup or recovery flow.
+
 ## Readiness checks (membership level)
 
 Start with: