@awebai/pi 0.1.15 → 0.1.17

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";
 }
@@ -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.15",
+  "version": "0.1.17",
   "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

@@ -1,6 +1,6 @@
 ---
 name: aweb-bootstrap
-description: This skill should be used when helping a human create or join an aweb team from a template (aw team bootstrap), choosing a template and team source (hosted new team, BYOT, API key, invite, or current workspace forwarding), selecting work-directory vs work-repo-url, provisioning optional worktree agents, and validating/re-running bootstrap safely.
+description: This skill should be used when helping a human create or join an aweb team from a template (aw team bootstrap), choosing a template and team source (hosted new team, BYOT, API key, invite, or current workspace forwarding), using the project-local agents/ layout or legacy work-directory/work-repo-url mode, provisioning optional worktree-bound agents, and validating/re-running bootstrap safely.
 allowed-tools: "Bash(aw *)"
 ---
 
@@ -20,27 +20,35 @@ Long-form reference: docs/team-bootstrap.md in the aweb repo.
 
 ## Mental model: what bootstrap is assembling
 
-`aw team bootstrap` combines four separate things that are easy to confuse:
+`aw team bootstrap` combines five separate things that are easy to confuse:
 
 1) Template repo — the blueprint.
 
-- Contains `team.yaml`, role playbooks, shared instructions, and `agents/<responsibility>/AGENTS.md` files.
+- Contains `team.yaml`, role playbooks, shared instructions, and `home/<responsibility>/AGENTS.md` files.
 - The template says what responsibilities should exist and which `role_name` each should use.
 
-2) Work directory or work repo — the thing agents work on.
+2) Generated project-local agents directory — where humans start agents.
 
-- `--work-directory` points at an existing folder.
-- `--work-repo-url` clones a repo into `<template>/worktrees/<derived-name>/` and uses that clone as the work directory.
-- Each responsibility workspace gets this directory symlinked as `./work`.
+- By default, run bootstrap from the root of the work repo.
+- Bootstrap creates `agents/` in that repo. Every live agent home is under `agents/home/<responsibility>/`.
+- The coordinator/global-style home normally has `work -> <repo-root>`.
+- Worktree-bound homes still live under `agents/home/<responsibility>/`; their `work` symlink points at `agents/worktrees/<alias-or-responsibility>/`.
+- Use `--agents-dir <name>` only when the repo already uses `agents/` for something else. If the target directory exists, bootstrap must fail before side effects.
 
-3) Team source — the authority/context the generated agents join.
+3) Legacy work directory or work repo — compatibility mode.
+
+- Passing `--work-directory` or `--work-repo-url` selects the old out-of-repo layout.
+- Do not combine `--agents-dir` with either legacy work flag.
+- Legacy mode is still supported for existing scripts/templates, but do not choose it for a new customer unless they explicitly need the old shape.
+
+4) Team source — the authority/context the generated agents join.
 
 - Hosted new team, existing hosted team via `AWEB_API_KEY`, explicit `--invite-token`, current workspace forwarding, or BYOT.
 - Exactly one explicit source is allowed. If no explicit source is set and cwd is already an aw workspace, bootstrap forwards that current team. If no current workspace exists and the run is interactive, bootstrap creates a hosted team. Non-interactive runs need an explicit source.
 
-4) Generated workspaces — the identities that will act.
+5) Generated workspaces — the identities that will act.
 
-- Each `agents/<responsibility>/` directory becomes an aw workspace with its own identity and team certificate.
+- Each `agents/home/<responsibility>/` directory becomes an aw workspace with its own identity and team certificate.
 - The **first generated plan** is the anchor: bootstrap connects it first, installs roles/instructions from that workspace's team context, then invites/connects the rest.
 - Do not assume a responsibility named `implementation` is special. The anchor is the first plan the CLI generated.
 
@@ -70,6 +78,9 @@ Do NOT bootstrap when:
 
 Canonical templates:
 
+- awebai/aweb-team-coord-worktrees (3 agents)
+  Use when you want a coordinator plus isolated developer/reviewer git worktrees in the current repo.
+
 - awebai/aweb-team-dev-review (2 agents)
   Use when you want the smallest meaningful team: implementation + review.
 
@@ -80,7 +91,7 @@ Fork/edit vs use-as-is:
 
 - Use as-is to learn the flow or to run a standard team.
 - 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.
+- It is safe to edit the template checkout before applying it; `aw team bootstrap` reads `team.yaml`, `roles/`, `docs/`, and `home/` from the local template directory at run time.
 
 ## Customizing a template before applying it
 
@@ -91,54 +102,87 @@ 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
+# edit team.yaml, roles/*.md, docs/team.md, home/<responsibility>/AGENTS.md
+cd /path/to/project-repo
+aw team bootstrap /path/to/my-team-template --dry-run
+aw team bootstrap /path/to/my-team-template --username alice
 ```
 
 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.
+- `team.yaml` agents: add/remove responsibility workspaces and set each `role_name`, `default_name`, `default_alias`, optional `home_template`, and optional `work`.
+- Use `work: repo_root` for an agent whose `work` symlink points to the project repo root.
+- Use `work: git_worktree` for an agent whose `work` symlink points to a generated git worktree under `agents/worktrees/`.
 - `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.
+- `home/<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)
 
-1) Run bootstrap from a directory that is NOT already inside a git repo/worktree.
+1) For the default layout, run bootstrap from the root of the project git repo.
 
-- If you are inside a git repo/worktree and you are using a remote template ref, bootstrap will refuse to clone by default.
-- Use `--template-cache-dir` as the explicit escape hatch when you must run from inside a repo.
+- Bootstrap creates `agents/` there.
+- If `agents/` exists, stop. Do not ask bootstrap to adopt, merge, or overwrite it.
+- If the project already has a different `agents/` directory, ask the human for a different `--agents-dir <name>`.
 
-2) Decide the “work” directory model (see next section). This affects whether agents share one checkout or get isolated worktrees.
+2) Decide the team source. This affects whether bootstrap creates a new hosted team, joins an API-key/invite team, forwards the current team, or uses BYOT.
 
-## Exactly one of: work-directory OR work-repo-url (XOR)
+3) Use legacy work flags only for old out-of-repo bootstrap scripts.
 
-Bootstrap needs a directory to symlink into each agent workspace as ./work.
+## Default layout: project-local agents/
 
-You must provide exactly one of:
+New bootstrap runs should normally use the default layout:
 
-A) --work-directory PATH
+```bash
+cd /path/to/project-repo
+aw team bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git --username alice
+```
 
-- Use when you already have a local directory you want agents to use as work.
-- For code teams with worktree agents (team.yaml worktrees:), PATH must be a git repo.
+Expected generated shape:
+
+```text
+agents/
+  team.yaml
+  docs/
+  roles/
+  home/
+    coordinator/
+      .aw/
+      AGENTS.md
+      work -> ../../..
+    developer/
+      .aw/
+      AGENTS.md
+      work -> ../../worktrees/dev
+    reviewer/
+      .aw/
+      AGENTS.md
+      work -> ../../worktrees/review
+  worktrees/
+    dev/
+    review/
+```
+
+The repo root itself is not an aw workspace. Start Codex, Claude Code, or Pi from an agent home, for example:
 
-B) --work-repo-url VALUE
+```bash
+cd agents/home/coordinator
+codex
+```
 
-- Use when you want bootstrap to clone a repo for you.
-- VALUE can be a URL or a local path; bootstrap runs “git clone VALUE” into:
+Bootstrap writes scoped `.gitignore` entries for `agents/home/*/.aw/` and `agents/worktrees/`. It must not ignore the whole `agents/` directory.
 
-  <template-checkout>/worktrees/<derived-name>/
+## Legacy mode: work-directory OR work-repo-url (XOR)
 
-  where <derived-name> matches git’s default directory naming (basename, .git stripped).
+Use legacy mode only for existing scripts/templates that expect generated homes outside the work repo.
 
-- That clone destination is then used as the effective work directory (symlinked as ./work in each agent workspace).
+- `--work-directory PATH`: use an existing local directory as each responsibility workspace's `./work`.
+- `--work-repo-url VALUE`: clone a repo into `<template-checkout>/worktrees/<derived-name>/` and use that clone as `./work`.
 
-If both flags are set, treat it as a user error and stop.
+If both flags are set, treat it as a user error and stop. If `--agents-dir` is combined with either legacy flag, treat it as a user error and stop.
 
 ## Team source policy
 
@@ -199,16 +243,17 @@ Policy guidance:
 - Prefer BYOT when you need local control over the team namespace/domain and routing.
 - Use `--dry-run` for planning only. It prints the resolved plan (template ref, work directory, team source, generated workspaces) without writing identities, files, or server state. Do not pair it with side-effecting flags expecting partial provisioning.
 
-## Worktree agents (team.yaml worktrees:)
+## Worktree-bound agents (`work: git_worktree`)
 
-Worktree agents are an OPTIONAL second layer for codebases where multiple agents will edit in parallel.
+Worktree-bound agents are for codebases where multiple agents will edit in parallel.
 
-- Responsibility workspaces live under agents/<responsibility>/.
-- Worktree agents live under worktrees/ and each has its own git worktree checkout and its own .aw/ identity state.
+- Every live home stays under `agents/home/<responsibility>/`.
+- A `work: git_worktree` agent gets a git checkout under `agents/worktrees/<alias-or-responsibility>/`.
+- Its home has `work -> ../../worktrees/<alias-or-responsibility>`.
 
-Turn worktree agents on when:
+Use `work: git_worktree` when:
 
-- The work directory is a git repo.
+- The project directory is a git repo.
 - Multiple agents will change files in parallel.
 - You want each agent’s edits isolated until you merge.
 
@@ -219,11 +264,11 @@ Leave it off when:
 
 Operational note:
 
-- Worktree agents are local-only identities by design; they are for parallel local work, not for global addressability.
+- Worktree-bound agents are local identities by default; they are for parallel local work, not for global addressability.
 
 ## After bootstrap: validate that the team is actually usable
 
-For each agent directory under agents/<responsibility>/:
+For each agent directory under `agents/home/<responsibility>/`:
 
 - Run `aw workspace status` to confirm:
   - the workspace is initialized
@@ -242,6 +287,7 @@ When iterating on templates or recovering from partial setup:
 - Use `--refresh-template` only when you intend to re-clone over a previous template checkout.
 - Treat identity/certificate state under .aw/ as the source of truth; do not delete it casually.
 - If you need to create a fresh workspace, do it in a new directory rather than mutating an existing identity in place.
+- If `agents/` already exists, do not retry over it. Pick a different `--agents-dir` or remove the existing directory only if the human confirms it is disposable.
 
 If bootstrap fails mid-way:
 

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

@@ -6,8 +6,9 @@ It is intentionally narrower than docs/team-bootstrap.md: it focuses on common d
 
 ## Quick mental model
 
-- Template repo = blueprint for roles, instructions, and responsibility directories.
-- Work directory/repo = the project/content agents see as `./work`.
+- Template repo = blueprint for roles, instructions, and agent home templates.
+- Default generated layout = project-local `agents/` directory containing `home/`, `worktrees/`, `roles/`, `docs/`, and `team.yaml`.
+- Work target = what each agent's `work` symlink points at: the repo root (`work: repo_root`) or a generated git worktree (`work: git_worktree`).
 - Team source = the authority the generated agents join.
 - First generated workspace = bootstrap anchor. It connects first; roles/instructions install through it; all other generated agents join through invites from that established team context.
 - BYOT means bring your own team, including your own namespace/domain and controller key. Do not present a separate domain-only bootstrap mode.
@@ -25,27 +26,28 @@ Goal: create a new aweb.ai team and provision agent workspaces from a template.
 
 Checklist:
 
-- Run from a directory that is not inside an existing git repo/worktree.
+- Run from the root of the project git repo.
+- Confirm the target agents directory does not already exist. Default: `agents/`.
 - Pick a template:
+  - awebai/aweb-team-coord-worktrees for coordinator + developer/reviewer worktrees.
   - 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):
+Example:
 
-  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --username alice --work-directory /path/to/work
+  cd /path/to/project-repo
+  aw team bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git --username alice
 
-Example (clone the work repo into the template checkout):
+Example with a non-default agents directory:
 
-  aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git --username alice --work-repo-url https://github.com/ORG/REPO.git
+  cd /path/to/project-repo
+  aw team bootstrap https://github.com/awebai/aweb-team-coord-worktrees.git --username alice --agents-dir aweb-agents
 
 Notes:
 
-- work-directory and work-repo-url are XOR: set exactly one.
-- When work-repo-url is used, bootstrap clones into:
-
-  <template-checkout>/worktrees/<derived-name>/
-
-  where derived-name is the git-style repo directory name (basename with .git stripped).
+- Bootstrap creates `agents/home/<agent>/` for every live agent home.
+- Worktree-bound agents get checkouts under `agents/worktrees/<alias-or-agent>/`.
+- The repo root is not an aw workspace; humans should start Codex/Claude/Pi from `agents/home/<agent>/`.
 
 ## Scenario: customize the template before applying it
 
@@ -54,17 +56,18 @@ Goal: change roles, agent responsibilities, names, aliases, or instructions befo
 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.
+- Edit `team.yaml`, `roles/*.md`, `docs/team.md`, and `home/<responsibility>/AGENTS.md` as needed.
+- Run `aw team bootstrap /path/to/template --dry-run` from the project repo root to validate.
+- Bootstrap the local template 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
+  # edit team.yaml / roles / docs / home
+  cd /path/to/project-repo
+  aw team bootstrap /path/to/my-team-template --dry-run
+  aw team bootstrap /path/to/my-team-template --username alice
 
 ## Scenario: BYOT (bring your own team)
 
@@ -80,8 +83,7 @@ Example shape (values are placeholders):
 
   aw team bootstrap https://github.com/awebai/aweb-team-dev-review.git \
     --namespace example.com \
-    --team dev \
-    --work-directory /path/to/work
+    --team dev
 
 If you are also self-hosting the coordination stack, add:
 
@@ -101,7 +103,7 @@ Checklist:
 Example:
 
   AWEB_API_KEY=aw_sk_... \
-    aw team bootstrap /path/to/template --work-directory /path/to/work
+    aw team bootstrap /path/to/template
 
 ## Scenario: existing team via invite token
 
@@ -110,8 +112,7 @@ Goal: accept an invite into the first generated workspace and use it as the anch
 Example:
 
   aw team bootstrap /path/to/template \
-    --invite-token <token> \
-    --work-directory /path/to/work
+    --invite-token <token>
 
 ## Scenario: current workspace forwarding
 
@@ -129,22 +130,32 @@ Goal: validate the plan and see generated workspace commands without changing fi
 
 Example:
 
-  aw team bootstrap /path/to/template --dry-run --work-directory /path/to/work
+  aw team bootstrap /path/to/template --dry-run
+
+## Legacy mode: old out-of-repo bootstrap
+
+Use legacy mode only for existing scripts/templates that still expect the old layout.
+
+- `--work-directory <path>` selects legacy work-directory mode.
+- `--work-repo-url <url-or-local-path>` selects legacy clone-then-bootstrap mode.
+- The two flags are XOR.
+- Do not combine `--agents-dir` with either legacy work flag.
 
-## Worktree agents: when to enable and what to expect
+## Worktree-bound agents: when to enable and what to expect
 
-Use worktree agents when multiple agents will edit code in parallel.
+Use `work: git_worktree` when multiple agents will edit code in parallel.
 
 Requirements:
 
-- The work directory must be a git repo.
-- The template must declare a worktrees: block in team.yaml.
+- The project directory must be a git repo.
+- The template declares `work: git_worktree` for the relevant agent in `team.yaml`.
 
 What bootstrap does:
 
-- It creates template worktrees/ (if missing) and git-excludes it locally.
-- It creates one git worktree per entry.
-- Each worktree agent gets its own .aw/ state and local-scope identity.
+- It creates `agents/worktrees/` and writes scoped `.gitignore` entries.
+- It creates one git worktree per `work: git_worktree` agent.
+- The live agent home remains under `agents/home/<responsibility>/`.
+- Each worktree-bound agent gets its own `.aw/` state and local-scope identity.
 
 Common pitfall:
 
@@ -152,7 +163,7 @@ Common pitfall:
 
 ## Quick validation after bootstrap
 
-In each generated agent directory (agents/<responsibility>/):
+In each generated agent directory (`agents/home/<responsibility>/`):
 
 - aw workspace status
 - aw whoami

package/skills/aweb-identity/SKILL.md

@@ -67,7 +67,7 @@ The normative E2E contract is `docs/e2e-messaging-contract.md`. Do not invent pr
 
 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. Missing, stale, unsigned, or mismatched encryption-key discovery fails closed; do not retry as plaintext unless the human explicitly chooses the separately named legacy plaintext mode from the final CLI. 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.
+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 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:
 
@@ -79,7 +79,7 @@ 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.
+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.
 
@@ -161,7 +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.
+- **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,9 +10,11 @@ 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.
+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 use the end-to-end label for hosted custodial/server-side messaging.
 
-Legacy plaintext boundary: existing plaintext mail/chat remains legacy/server-readable while retained and must not be described as retroactively E2E. 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 the approved legacy plaintext command/flag.
+Interim plaintext boundary: in the current aw CLI release, mail and chat are server-readable plaintext by default. Do not describe default CLI mail/chat as E2E. Pass `--e2ee` only when the human explicitly wants encrypted send; if that encrypted send fails because keys, capability, route support, or version support is missing/stale/mismatched, stop and report the exact failure. Do not silently retry as plaintext.
+
+Mixed-version boundary: old pre-E2E aw/channel/Pi clients may not have published recipient encryption keys yet. A current aw CLI can create/publish the sender's local encryption key for explicit `--e2ee` 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. Plain default sends and `--plaintext` are server-readable.
 
 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`.
 
@@ -77,15 +79,15 @@ 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.
 
-Encrypted chat is explicit. Use `--e2ee` only when the human or policy asks for E2E chat and every participant has identity-authorized encryption capability:
+Mail and chat are server-readable plaintext by default in the current aw CLI release. Add `--e2ee` only when the human explicitly wants an encrypted send; it fails closed if keys, capability, route support, or version support are missing. `--plaintext` is an explicit clarifier for the current default.
 
 ```bash
-aw chat send-and-wait <alias-or-address> "..." --start-conversation --e2ee
-aw chat send-and-leave <alias-or-address> "..." --e2ee
-aw chat extend-wait <from> "working on it" --e2ee
+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 `--e2ee` 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 the approved legacy plaintext path.
+Encrypted read paths such as `aw chat pending`, `aw chat history`, and channel listen/decrypt paths show plaintext only after local decryption. If an explicit `--e2ee` 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 server-readable plaintext.
 
 ## Harness surfaces
 
@@ -109,7 +111,7 @@ 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.
+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