@awebai/pi 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/pi",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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,14 +1,14 @@
 ---
 name: aweb-bootstrap
-description: This skill should be used when helping a human create a new aweb team from a template (aw team bootstrap), choosing a template and bootstrap mode (hosted vs BYOT vs manual), 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), selecting work-directory vs work-repo-url, provisioning optional worktree agents, and validating/re-running bootstrap safely.
 allowed-tools: "Bash(aw *)"
 ---
 
 # aweb Bootstrap
 
-Use this skill when a human wants to create a new aweb team for the first time, and you need to guide them through `aw team bootstrap` decisions and validation.
+Use this skill when a human wants to create or extend an aweb team from a reusable template, and you need to guide them through `aw team bootstrap` decisions and validation.
 
-This skill is about **decision policy + safe execution**, not memorizing flags.
+This skill is about **mental model + decision policy + safe execution**, not memorizing flags.
 
 Related skills:
 
@@ -18,13 +18,48 @@ Related skills:
 
 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:
+
+1) Template repo — the blueprint.
+
+- Contains `team.yaml`, role playbooks, shared instructions, and `agents/<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.
+
+- `--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`.
+
+3) 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.
+
+- Each `agents/<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.
+
+Aweb team source terms:
+
+- Hosted new team: aweb.ai creates/hosts the team.
+- API key: joins the hosted team represented by `AWEB_API_KEY`; `--aweb-url`/`AWEB_URL` is optional and defaults to hosted aweb.ai.
+- Invite token: first generated workspace accepts an existing invite.
+- Current workspace forwarding: caller cwd already has `.aw`; bootstrap creates a one-use invite from that active team.
+- BYOT: bring your own team. This includes bringing your own domain/namespace and controller key. Do not describe a separate domain-only bootstrap mode.
+
 ## Bootstrap vs join (first decision)
 
 Bootstrap when:
 
-- You are creating a brand-new team (new template repo clone, new identities, new role bundle).
+- You are creating a brand-new team from a template.
+- You are extending an existing team with a template-defined set of agent workspaces, roles, and instructions.
 - You want reproducible setup for multiple agents/workspaces.
-- You want a “one command creates the team + installs roles + provisions agent dirs” flow.
+- You want a “one command resolves the team source + installs roles + provisions agent dirs” flow.
 
 Do NOT bootstrap when:
 
@@ -79,30 +114,64 @@ B) --work-repo-url VALUE
 
 If both flags are set, treat it as a user error and stop.
 
-## Hosted vs BYOT vs manual bootstrap modes
+## Team source policy
+
+Non-dry-run bootstrap needs one coherent team source. This is the most important decision: it determines which team owns the roles, instructions, tasks, mail, chat, and membership certificates created during bootstrap.
+
+Resolution order:
 
-Bootstrap can be used in three broad modes:
+- If any explicit source is set (`AWEB_API_KEY`, `--invite-token`, `--username`, or `--namespace/--team`), do not set another explicit source.
+- If no explicit source is set and cwd is an initialized aw workspace, bootstrap forwards the current active team.
+- If no explicit source is set, cwd is not an aw workspace, and the run is interactive, bootstrap creates/uses a hosted team through onboarding prompts.
+- If no source can be resolved, stop and ask the human which team source to use.
 
-1) Hosted (aweb.ai)
+The first generated agent workspace is the anchor: bootstrap connects it first, installs roles/instructions from that workspace's team context, then invites/connects the remaining agents and any declared worktree agents.
+
+Supported sources:
+
+1) Hosted new team (aweb.ai)
 
 - Best for first-time teams.
-- Bootstrap will prompt for hosted onboarding details when appropriate, then provision each agent workspace.
+- Use `--username <name>` or run interactively in a TTY.
+- Bootstrap uses the same hosted onboarding path as `aw init` for the first generated workspace.
+
+2) Existing hosted team via API key
+
+- If `AWEB_API_KEY` is set, bootstrap joins the API key's hosted team.
+- `--aweb-url`/`AWEB_URL` is optional; when omitted, the hosted aweb.ai default is used. Set it only to target a non-default stack.
+- Do not also pass `--username`, `--invite-token`, or BYOT flags.
+
+3) Existing team via invite token
+
+- Pass `--invite-token <token>`.
+- Bootstrap accepts it into the first generated workspace, then creates further invites from that established team context.
+
+4) Current workspace forwarding
+
+- If the caller's cwd is already initialized for aw and no explicit source is set, bootstrap creates a one-use invite from the current active team and accepts it into the first generated workspace.
+- This is the safe default for adding a template team shape to the team you are already using.
 
-2) BYOT (your own controller + namespace)
+5) BYOT (bring your own team)
 
-- Use when the team’s namespace and controller key live in your environment.
-- Bootstrap can create/ensure the team in that namespace and provision all agents.
+- Use `--namespace <domain> --team <slug>` when the team's namespace/domain and controller key live in your environment.
+- BYOT includes bringing your own domain; there is no separate supported domain-only bootstrap mode.
+- Bootstrap creates/ensures the team in that namespace, invites the first generated workspace, then uses it as the anchor.
 
-3) Manual (print next commands)
+Decision recipe:
 
-- Use when you cannot or should not auto-provision from this run (for example, non-interactive environments or policy constraints).
-- Bootstrap will print the next `aw init ...` commands to run inside each agent directory.
+- 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).
+- Human controls a namespace/domain and wants the team under that namespace: use BYOT (`--namespace` + `--team`).
 
 Policy guidance:
 
 - Prefer hosted for “get a working team now”.
-- Prefer BYOT when you need local control over identity and routing.
-- Prefer manual when you need human confirmation at each step.
+- Prefer API key or invite when the team already exists but the caller is not already inside it.
+- Prefer current workspace forwarding when you are already inside the target team.
+- Prefer BYOT when you need local control over the team namespace/domain and routing.
+- Use `--dry-run` for planning only. The old manual "print commands after installing server state from caller cwd" flow is not coherent and should not be recommended.
 
 ## Worktree agents (team.yaml worktrees:)
 

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

@@ -4,6 +4,21 @@ This reference is support material for the aweb-bootstrap skill. Use it when you
 
 It is intentionally narrower than docs/team-bootstrap.md: it focuses on common decision points and failure modes.
 
+## Quick mental model
+
+- Template repo = blueprint for roles, instructions, and responsibility directories.
+- Work directory/repo = the project/content agents see as `./work`.
+- 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.
+
+Team-source precedence:
+
+- Explicit sources conflict: use only one of `AWEB_API_KEY`, `--invite-token`, `--username`, or `--namespace/--team`.
+- With no explicit source, an initialized caller cwd forwards its current active team.
+- With no explicit source and no caller workspace, an interactive run uses hosted onboarding.
+- Non-interactive runs need an explicit source or initialized caller workspace.
+
 ## Scenario: first-time hosted team from a template (recommended)
 
 Goal: create a new aweb.ai team and provision agent workspaces from a template.
@@ -32,14 +47,15 @@ Notes:
 
   where derived-name is the git-style repo directory name (basename with .git stripped).
 
-## Scenario: BYOT (your own controller + namespace)
+## Scenario: BYOT (bring your own team)
 
-Goal: bootstrap a team under a namespace you control.
+Goal: bootstrap a team under a namespace/domain you control.
 
 Checklist:
 
-- Confirm you have a controller identity key for the namespace.
-- Decide whether bootstrap should auto-provision (interactive) or just print next commands.
+- Confirm you have a controller identity key for the namespace/domain.
+- Remember BYOT includes bringing your own domain; there is no separate supported domain-only bootstrap mode.
+- Bootstrap will connect the first generated workspace, install roles/instructions there, then invite/connect the remaining agents.
 
 Example shape (values are placeholders):
 
@@ -54,14 +70,44 @@ If you are also self-hosting the coordination stack, add:
   --aweb-url http://localhost:8000
   --registry http://localhost:8010
 
-## Scenario: manual mode (print next commands)
+## Scenario: existing hosted team via API key
+
+Goal: provision a template into the hosted team associated with an API key.
+
+Checklist:
+
+- Set AWEB_API_KEY.
+- Optionally set AWEB_URL or pass --aweb-url to target a non-default stack; otherwise the hosted default is used.
+- Do not also pass --username, --invite-token, or BYOT flags.
+
+Example:
+
+  AWEB_API_KEY=aw_sk_... \
+    aw team bootstrap /path/to/template --work-directory /path/to/work
+
+## Scenario: existing team via invite token
+
+Goal: accept an invite into the first generated workspace and use it as the anchor for the rest of bootstrap.
+
+Example:
+
+  aw team bootstrap /path/to/template \
+    --invite-token <token> \
+    --work-directory /path/to/work
+
+## Scenario: current workspace forwarding
 
-Goal: validate the plan and generate the next steps without changing server state.
+Goal: run bootstrap from an existing aw workspace and forward that active team into the generated template workspaces.
 
 Checklist:
 
-- Use dry-run to see the plan.
-- Use the printed aw init commands inside each agent directory.
+- Confirm `aw workspace status` succeeds in the caller cwd.
+- Do not pass another explicit team source.
+- Bootstrap will create a one-use invite from the current active team for the first generated workspace.
+
+## Scenario: dry-run planning
+
+Goal: validate the plan and see generated workspace commands without changing files, identities, or server state.
 
 Example:
 

package/skills/aweb-identity/SKILL.md

@@ -32,7 +32,9 @@ A workspace can hold any combination of these. For team-related files (`teams.ya
 
 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 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`, performs DNS-TXT verification, 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 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.
@@ -45,7 +47,8 @@ These two commands look similar and are not interchangeable. The decision turns
 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 mint an identity I'll later attach to a BYOT team via controller-signed facts" → `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.
+- "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
 
@@ -56,6 +59,8 @@ When deciding which to run:
 
 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.
 
+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
@@ -141,8 +146,9 @@ Interpret failures by what's missing (file references assume a self-custodial CL
   - **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.
 
-  Note: AWID has signed endpoints to delete address/team facts under controller authority, but the `aw` CLI does not yet expose first-class `delete-address` / `delete-team` commands (tracked as aweb-aapr.25). Do not rely on operator-only or direct-DB cleanup as the normal recovery path.
-- **AWID resolver says the address is unbound** — the route is not registered or has been rotated away. Look up the address directly with `aw directory <namespace>/<name>`, 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 if the address record is genuinely missing.
+  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`.
 

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

@@ -190,18 +190,29 @@ Vocabulary:
 - Agents have addresses under the namespace, e.g. `juanreyero.com/alpha`.
 - Do not call `personal:juanreyero.com` an agent; it is the team id.
 
-Before starting, confirm `aw version` is at least `1.25.3`; older `aw` emitted a stale BYOT import payload.
+Before starting, confirm `aw version` includes `aw id namespace prepare-controller` and `aw id namespace check-txt`; older `aw` versions make this flow hard to drive from non-interactive harnesses.
 
 **Use `aw id create`, NOT `aw init --byod --global`, for the identity-prep commands in this section.** `aw init --byod --global` is workspace onboarding: it bootstraps the directory and connects it to the `default:<domain>` team on app.aweb.ai (the team created during BYOD onboarding), writing `workspace.yaml`, joining that team, and minting a team certificate. That short-circuits the controller-signed team-state import this section is about. `aw id create` only mints the identity in AWID and writes `.aw/identity.yaml` + `.aw/signing.key`, leaving the team membership for the customer controller to add and sign. If a user already ran the wrong command and needs to recover, see the matching diagnostic bullet in `aweb-identity`'s readiness checks.
 
-Controller machine setup (in a clean directory with no `.aw/`):
+Namespace controller setup (does not create an identity or team):
+
+```bash
+aw id namespace prepare-controller --domain <domain>
+```
+
+Pause and have the human add the printed `_awid.<domain>` TXT record. Do not invent DNS values. Tell the human to back up `~/.awid` now; it contains the namespace controller key. After DNS propagates, verify it:
+
+```bash
+aw id namespace check-txt --domain <domain>
+```
+
+Then create the BYOT team with the namespace controller key:
 
 ```bash
-aw id create --domain <domain> --name <controller-name>
 aw id team create --namespace <domain> --name <team> --display-name "<display name>"
 ```
 
-If DNS verification is needed, pause and have the human add the TXT record that `aw id create` prints. Do not invent DNS values.
+After team creation, tell the human to back up `~/.awid` again; it now also contains the team controller key under `~/.awid/team-keys/<domain>/<team>.key`.
 
 Add initial global agents:
 

package/skills/aweb-team-membership/references/team-membership-reference.md

@@ -24,6 +24,8 @@ In BYOT, the customer controls the DNS namespace controller and team controller.
 Key command surfaces:
 
 ```bash
+aw id namespace prepare-controller --domain <domain>
+aw id namespace check-txt --domain <domain>
 aw id create --name <name> --domain <domain>
 aw id team create --namespace <namespace> --name <team>
 aw id team request --team <team>:<namespace> --alias <alias>
@@ -32,7 +34,7 @@ aw id team fetch-cert --team <team> --namespace <namespace> --cert-id <id>
 aw id team import-request --namespace <domain> --team <team> --organization-id <org>
 ```
 
-Use current `aw ... --help` for exact flags. Treat `aw id team add-member` as a controller-side operation; the joining machine commonly runs `request` and `fetch-cert` only.
+Use current `aw ... --help` for exact flags. Treat `aw id namespace prepare-controller` as namespace-authority setup, not identity creation. Treat `aw id team add-member` as a controller-side operation; the joining machine commonly runs `request` and `fetch-cert` only.
 
 For the dashboard import/sync path:
 
@@ -51,7 +53,7 @@ Addressability and delivery authorization are separate:
 - `team_and_contacts` accepts verified same-team senders plus exact active identity contacts for trusted non-team senders. Contacts do not create routes or resolver visibility.
 - Legacy reachability fields may still appear in support or migration output, but they are compatibility/audit state, not live delivery authority.
 - `aw contacts ...` manages saved contact relationships.
-- `aw directory <domain>/<alias>` performs directory lookup.
+- `aw id namespace resolve <domain>/<alias> --json` performs a workspace-free directory lookup.
 
 ## Multi-team safety checklist