@awebai/pi 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/pi",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "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

@@ -97,6 +97,7 @@ Bootstrap can be used in three broad modes:
 
 - 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.
+- If you are not already in an initialized aweb workspace, add --skip-roles and --skip-instructions so bootstrap does not try to install server-side state before any workspace is connected.
 
 Policy guidance:
 

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