@awebai/claude-skills 0.2.0 → 0.2.2

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "aweb-skills",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "aweb agent coordination skills — teach your Claude Code agent how to use the aw CLI for mail, chat, tasks, and team coordination."
 }

package/README.md

@@ -1,7 +1,8 @@
 # `@awebai/claude-skills`
 
-Content-only Claude Code plugin packaging the three canonical aweb skills:
-`aweb-coordination`, `aweb-messaging`, `aweb-team-membership`.
+Content-only Claude Code plugin packaging the four canonical aweb skills:
+`aweb-coordination`, `aweb-messaging`, `aweb-team-membership`, and
+`aweb-bootstrap`.
 
 Distinct from [`@awebai/claude-channel`](https://github.com/awebai/aweb/tree/main/channel),
 which ships the real-time channel runtime and requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/claude-skills",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Content-only Claude Code plugin shipping the canonical aweb agent-coordination skills: aweb-coordination, aweb-messaging, aweb-team-membership, aweb-bootstrap.",
   "license": "MIT",
   "homepage": "https://aweb.ai",

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

@@ -39,7 +39,7 @@ Interpret failures by layer:
 - Missing signing key: local identity is incomplete.
 - Missing team certificate: identity may exist but cannot act in the team.
 - Active team mismatch: the identity has multiple memberships but this workspace is using the wrong one.
-- Address route, inbound-mode, or contact failure: the sender and recipient may both exist, but route validation or `inbound_mode=open|contacts_only` policy prevents discovery or inbound delivery.
+- Address route, inbound-mode, or contact failure: the sender and recipient may both exist, but route validation or `inbound_mode=open|team_and_contacts` policy prevents discovery or inbound delivery.
 
 ## Joining a team
 
@@ -118,6 +118,86 @@ The import request signs a `byoidt_import` payload with the local BYOT team cont
 
 There is no supported middle ground where a customer brings a custom domain but aweb holds that domain's namespace/team controller private key.
 
+### Fresh BYOT setup into aweb cloud
+
+Use this flow when the user controls DNS for a domain and wants to create a customer-controlled AWID team, add agents, and import/sync it into app.aweb.ai.
+
+Vocabulary:
+
+- The namespace is the domain, e.g. `juanreyero.com`.
+- The team is named inside that namespace, e.g. `personal`; its AWID team id is `personal:juanreyero.com`.
+- 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.
+
+Controller machine setup:
+
+```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.
+
+Add initial global agents:
+
+```bash
+aw id create --domain <domain> --name alpha
+aw id team add-member --team <team> --namespace <domain> --did <alpha_did_key> --alias alpha --global --did-aw <alpha_did_aw>
+
+aw id create --domain <domain> --name beta
+aw id team add-member --team <team> --namespace <domain> --did <beta_did_key> --alias beta --global --did-aw <beta_did_aw>
+```
+
+Use the actual `did`/`did_aw` values printed by `aw id create`. Do not guess them.
+
+Import into aweb cloud:
+
+1. In app.aweb.ai, create or select the owner organization that should contain the imported team.
+2. Open the BYOT import flow. Prefer the command shown by the dashboard because it contains the correct `--organization-id`.
+3. First preview:
+
+```bash
+aw id team import-request --team <team> --namespace <domain> --organization-id <org-id>
+```
+
+Paste the signed output and use Preview.
+
+4. If the preview is correct, regenerate an apply request:
+
+```bash
+aw id team import-request --team <team> --namespace <domain> --organization-id <org-id> --apply
+```
+
+Paste it and use Import / sync.
+
+Sync later changes:
+
+- After the team exists in aweb cloud, use `--cloud-team-id <cloud-team-id>` instead of `--organization-id`.
+- The dashboard Connect / Sync page should show the exact command. Prefer that command.
+
+```bash
+aw id team import-request --team <team> --namespace <domain> --cloud-team-id <cloud-team-id> --apply
+```
+
+To add another self-custodial identity later, the identity machine uses the request/fetch flow; the controller machine signs membership; then the dashboard syncs the signed team state:
+
+```bash
+# joining identity machine
+aw id team request --team <team>:<domain> --alias <alias>
+
+# controller machine runs the printed add-member command
+
+# joining identity machine
+aw id team fetch-cert --namespace <domain> --team <team> --cert-id <id>
+
+# controller machine or any machine with the team controller key
+aw id team import-request --team <team> --namespace <domain> --cloud-team-id <cloud-team-id> --apply
+```
+
+To add a custodial browser identity to a BYOT team, start from the dashboard's "Create custodial request" action. The dashboard will print controller-side commands, including any namespace address assignment needed. Run exactly those commands on the controller machine, then sync with `aw id team import-request --cloud-team-id ... --apply`.
+
 ## Custodial vs self-custodial identity
 
 Identity custody is independent of hosted vs BYOT team authority:
@@ -143,7 +223,7 @@ For custodial identities, rotation and recovery are cloud-account operations. Do
 
 First contact to a global identity uses a concrete address route such as `<domain>/<alias>`. A bare `did:aw` is identity binding, not a first-contact delivery route. Legacy reachability fields may still appear in support/audit views, but they are compatibility/audit state, not live delivery authority.
 
-Delivery authorization is `inbound_mode=open|contacts_only`: `open` accepts valid senders after route validation, while `contacts_only` requires an exact active identity contact after the route is valid. Contacts do not synthesize routes and are not team-global authority.
+Delivery authorization is `inbound_mode=open|team_and_contacts`: `open` accepts valid routed senders, while `team_and_contacts` accepts verified same-team senders plus exact active identity contacts after the route is valid. Team membership is always delivery authority in `team_and_contacts`; contacts only add trusted non-team senders. Contacts do not synthesize routes or resolver visibility.
 
 Contacts are saved identity/address relationships for repeated cross-team messaging. They are per-identity, not per-team. Add a contact when repeated communication is expected; otherwise use a one-shot namespace address.
 
@@ -168,8 +248,8 @@ Treat teams as separate coordination boundaries for tasks, locks, roles, instruc
 Check:
 
 1. Global address registration and route resolution.
-2. Inbound mode (`open` or `contacts_only`).
-3. Exact active contact state when the recipient uses `contacts_only`.
+2. Inbound mode (`open` or `team_and_contacts`).
+3. Verified shared team membership, or exact active contact state for non-team senders, when the recipient uses `team_and_contacts`.
 4. Whether X is using a same-team alias or a concrete cross-team address.
 5. Whether the active team is the intended team for sender context.
 6. Whether the workspace has a valid certificate.

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

@@ -34,15 +34,22 @@ aw id team import-request --namespace <domain> --team <team> --organization-id <
 
 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.
 
+For the dashboard import/sync path:
+
+- Use `--organization-id <org-id>` only for the first import into an owner organization.
+- Use `--cloud-team-id <cloud-team-id>` for later syncs of an already-imported team.
+- Omit `--apply` for preview; add `--apply` only after the preview is correct.
+- The dashboard's Connect / Sync page should show the exact command for the current team. Prefer that command over reconstructing IDs by hand.
+
 ## Addressability, inbound mode, and contacts
 
 Addressability and delivery authorization are separate:
 
 - First contact uses a concrete address route (`domain/alias`).
 - `did:aw` is identity binding, not a first-contact delivery route.
-- `inbound_mode=open|contacts_only` controls delivery after route validation.
-- Exact active identity contacts authorize `contacts_only`; contacts do not create routes or resolver visibility.
-- Legacy reachability/access-mode fields may still appear in support or migration output, but they are compatibility/audit state, not live delivery authority.
+- `inbound_mode=open|team_and_contacts` controls delivery after route validation.
+- `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.