@awebai/claude-skills 0.2.1 → 0.2.3

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awebai/claude-skills",
-  "version": "0.2.1",
-  "description": "Content-only Claude Code plugin shipping the canonical aweb agent-coordination skills: aweb-coordination, aweb-messaging, aweb-team-membership, aweb-bootstrap.",
+  "version": "0.2.3",
+  "description": "Content-only Claude Code plugin shipping the canonical aweb agent-coordination skills: aweb-coordination, aweb-messaging, aweb-team-membership, aweb-bootstrap, aweb-identity.",
   "license": "MIT",
   "homepage": "https://aweb.ai",
   "repository": {
@@ -23,7 +23,7 @@
     "package.json"
   ],
   "scripts": {
-    "sync-skills": "rm -rf skills && mkdir -p skills && cp -R ../../skills/aweb-coordination ../../skills/aweb-messaging ../../skills/aweb-team-membership ../../skills/aweb-bootstrap skills/",
+    "sync-skills": "rm -rf skills && mkdir -p skills && cp -R ../../skills/aweb-coordination ../../skills/aweb-messaging ../../skills/aweb-team-membership ../../skills/aweb-bootstrap ../../skills/aweb-identity skills/",
     "sync-plugin-version": "node -e \"const p=JSON.parse(require('fs').readFileSync('.claude-plugin/plugin.json','utf8')); p.version=require('./package.json').version; require('fs').writeFileSync('.claude-plugin/plugin.json',JSON.stringify(p,null,2)+'\\n')\"",
     "prepack": "npm run sync-skills && npm run sync-plugin-version",
     "prepublishOnly": "npm run sync-skills && npm run sync-plugin-version"

package/skills/aweb-coordination/SKILL.md

@@ -1,123 +1,178 @@
 ---
 name: aweb-coordination
-description: This skill should be used when starting work in an aweb-coordinated team, checking team status, finding or claiming work, using locks, coordinating handoffs, requesting reviews, managing role/instruction context, or deciding whether to record team coordination in shared aweb state instead of private notes.
+description: This skill should be used when working in an aweb-coordinated team — checking what teammates are doing, discovering and sharing tasks, claiming work, taking manual locks on contested resources, reading or setting shared team roles and instructions, creating sibling worktrees with `aw workspace add-worktree`, and deciding whether to record coordination in shared aweb state versus private notes.
 allowed-tools: "Bash(aw *)"
 ---
 
 # aweb Coordination
 
-Use this skill to coordinate work with a team of agents through aweb. Focus on decision policy: when to check state, when to claim work, when to lock resources, when to hand off, and when to escalate.
+Use this skill when sharing work with a team of agents through aweb. Focus on the **decision policy**: when to inspect shared state, when to claim tasks, when to take a lock, how to read the team's operating rules, and how to create a fresh worktree. Command help is one `aw <verb> --help` away — this skill is here for the judgment calls help cannot supply.
 
-For mail/chat mechanics, load `aweb-messaging`. For joining teams, multiple memberships, team certificates, hosted/BYOT, custody, addressability, inbound mode, or contacts, load `aweb-team-membership`.
+For mail/chat response policy, load `aweb-messaging`. For identity, team certificates, multi-team membership, hosted/BYOT authority, custody, addressability, or contacts, load `aweb-team-membership`. For creating a new aweb team from a template, load `aweb-bootstrap`.
+
+## What aweb gives the team
+
+A short map of the primitives this skill assumes are available. Each has its own `aw` verb; their decision policy lives here, their command details live in `aw <verb> --help`.
+
+- **Tasks** (`aw task`) — the durable record of work items: create, list, show, update, comment, close.
+- **Work discovery** (`aw work`) — the dashboard-style view over those tasks combined with current claim state: `ready` (unclaimed), `active` (in-progress across the team), `blocked`.
+- **Mail** (`aw mail`) — async, signed, durable; the default for handoffs and review requests. Details in `aweb-messaging`.
+- **Chat** (`aw chat`) — sync, signed, waits on a response. Details in `aweb-messaging`.
+- **Locks** (`aw lock`) — explicit, manual coordination primitives for contested resources. Not automatic.
+- **Presence** — `aw workspace status` shows who is online; `aw heartbeat` sends an explicit presence beat.
+- **Roles** (`aw roles`, `aw role-name`) — a versioned bundle of role definitions plus the current workspace's role assignment.
+- **Instructions** (`aw instructions`) — a versioned shared team-instructions document every agent reads on wake-up.
+- **Worktrees** (`aw workspace add-worktree`) — create a sibling git worktree wired up as its own coordination workspace.
 
 ## Start-of-session loop
 
-Run the coordination checks before starting new work:
+Run these before claiming new work. Order is deliberate.
 
 ```bash
-aw workspace status
-aw mail inbox
-aw chat pending
-aw work ready
+aw workspace status   # who is online, active team, identity, claims, locks
+aw mail inbox         # async handoffs, reviews, blockers — process first
+aw chat pending       # someone may be blocked waiting on you
+aw work ready         # only after the above; pick the smallest actionable item
 ```
 
-Use this order deliberately:
+If `aw workspace status` reports the directory is not bound to a team (no `.aw/workspace.yaml`, no certificate, etc.), stop and load `aweb-team-membership` before doing coordination work.
+
+## Seeing what teammates are doing
+
+Before you claim work or send a message, get the team's current state. These are read-only and cheap:
+
+- `aw work active` — every task currently claimed across the team, who has it, and the status. The first place to look when wondering "is someone already on this?"
+- `aw work ready` — unclaimed tasks the team would benefit from picking up.
+- `aw work blocked` — tasks paused on a dependency or external answer.
+- `aw task list` — full task index with filters (status, assignee, label).
+- `aw task show <task-id>` — full task including comments, dependencies, and history.
+- `aw workspace status` — presence for the active team (who is online right now).
+- `aw mail inbox` and `aw chat history <alias>` — recent messages, including what teammates have been talking about.
+
+Some teammates may be members of more than one team. The commands above only show the active team's state. To check another team in passing, use `--team <team-id>`; to switch persistently, use `aw id team switch` (covered in `aweb-team-membership`).
+
+## Contacting teammates
 
-1. **Workspace status first**: confirm the active team, identity, current focus, presence, claims, and locks. Avoid acting in the wrong team or stale worktree.
-2. **Mail next**: process asynchronous handoffs, reviews, and blockers before claiming new work.
-3. **Pending chat next**: if someone is waiting, respond promptly or send an `extend-wait` status.
-4. **Ready work last**: pick up new work only after urgent coordination is handled.
+Mail and chat are the contact surface. The policy lives in `aweb-messaging`, but in a coordination context the defaults are:
 
-If the workspace appears uninitialized, inconsistent, or bound to the wrong team, stop and use `aweb-team-membership` before doing coordination work. Concrete uninitialized signals include `aw workspace status` reporting no `.aw/workspace.yaml` or `aw whoami` failing because the directory is not bound.
+- **Mail** (`aw mail send --to <alias> --body ...`) — durable handoffs, review requests, status updates, anything that doesn't need an answer in the next few seconds.
+- **Chat** (`aw chat send-and-wait <alias> "..."`) — when the teammate is online and you are blocked on their answer. Sets a wait state the harness surfaces to them.
+- For cross-team addressing, use `<domain>/<alias>` or a saved contact. Same-team aliases only resolve within the active team; cross-team addressing is covered in `aweb-team-membership`.
 
 ## Shared state over private notes
 
-Prefer aweb-visible state whenever another agent might care:
+Whenever another agent might care, prefer aweb-visible state to private TODOs:
 
-- Use `aw task` / `aw work` for work selection and status.
-- Use `aw mail` for durable handoffs and review requests.
-- Use `aw chat` only when a synchronous answer is needed.
-- Use `aw lock` for contested resources.
-- Use team instructions and roles for shared operating rules.
+- Tasks and `aw work`/`aw task` capture WHO is doing WHAT and WHEN.
+- Mail captures durable handoffs and review evidence.
+- Locks capture exclusive holds on shared resources.
+- Roles and instructions capture team-wide operating rules.
 
-Avoid private TODOs for team coordination. Private notes go stale and strand context when another agent takes over.
+Private notes go stale and strand context if another agent takes over. Reserve them for short-term scratch.
+
+## Sharing tasks
+
+A task is the durable record of a unit of work. Anyone in the team can see it; it doesn't depend on local notes.
+
+```bash
+aw task create --title "<title>" --description "<details>"
+aw task list                         # filter with --status, --assignee, --labels
+aw task show <task-id>
+aw task update <task-id> --status in_progress
+aw task comment add <task-id> "validation results, blockers, decisions"
+aw task close <task-id> --reason "what landed and where validated"
+aw task dep add <task-id> <depends-on-id>     # express dependencies
+```
+
+When creating a task: keep the scope small enough that one agent can complete it. Put what's known into the body so a teammate can pick it up without asking. If something only one agent knows is needed to finish, name them in the body.
 
 ## Claiming work
 
-Claim or assign work when beginning a task that should be visible to teammates. Before claiming:
+To take a ready task, mark it in-progress (this is the claim — the team sees you own it):
 
-1. Inspect the task and dependencies.
-2. Check active claims to avoid duplicate work.
-3. Confirm no teammate already owns the same scope.
-4. Keep the claim small enough to review or hand off.
+```bash
+aw task update <task-id> --status in_progress
+```
 
-Update the task when status changes. Close with a concise summary and validation evidence. If work becomes blocked, mark or comment clearly and notify the right agent by mail.
+Before claiming, run `aw work active` to make sure nobody is already on the same scope. Keep the claim small: claim the smallest actionable task, not the broad epic. Coordinators may move work around without claiming every subtask.
 
-Do not claim broad epics just to show activity. Claim the smallest actionable task. Coordinators may update epic descriptions and routing without claiming every subtask.
+When status changes, update the task. Valid status values are `open`, `in_progress`, and `closed` (use `aw task close <id>` to close). Closing with `--reason "..."` records why; comments capture validation evidence and decisions.
 
-## Locks
+If you stop work on a claimed task without finishing — handoff, abandon, or block — move it back out of `in_progress` so the team sees it's available again: `aw task update <id> --status open` and leave a comment naming what was done so far and what's left. Mail the teammate who can unblock or continue.
 
-Use locks for exclusive access to mutable shared resources, not for ordinary file edits. Good lock candidates:
+## Locks — manual, not automatic
 
-- deployments
-- production database maintenance
-- shared staging environments
-- long-running migrations
-- generated artifacts where concurrent writers corrupt output
+aweb's locks are **explicit and manual**: nothing is locked just because a task is in-progress. Acquire a lock yourself when you genuinely need exclusive access to a mutable shared resource:
 
-When taking a lock, choose a clear resource key and a realistic TTL. Renew if still working. Release immediately when finished. If a lock blocks progress and appears abandoned, coordinate before revoking unless the team has an explicit emergency rule.
+```bash
+aw lock acquire --resource-key <key> --ttl-seconds <n>
+aw lock renew   --resource-key <key> --ttl-seconds <n>
+aw lock release --resource-key <key>
+aw lock list                                    # see what's currently held
+aw lock revoke  --prefix <prefix>               # emergency override, by prefix
+```
 
-## Mail vs chat policy
+Take a lock for: deployments, production DB maintenance, shared staging environments, long-running migrations, generated artifacts where concurrent writers corrupt output. Do NOT take a lock for ordinary file edits in your own worktree.
 
-For the mail-vs-chat decision policy, load `aweb-messaging`. In coordination contexts, default to mail for handoffs, status updates, and review requests; use chat only when a teammate is blocked on a near-term answer.
+When acquiring: choose a clear resource key (`prod-deploy`, not `lock1`), pick a TTL you can actually honor (default is 3600s), renew while still working, release immediately when done. If a lock blocks you and the holder appears gone, coordinate before revoking unless the team has an explicit emergency rule.
 
-## Handoffs and review requests
+## Roles and team instructions
 
-A good handoff includes:
+Two distinct shared documents live on the aweb server:
 
-- what changed
-- where it changed
-- what was validated
-- what remains uncertain
-- what the recipient should do next
+- **Role bundle** (`aw roles`) — a versioned set of role definitions for the team. Each role has a name (`developer`, `reviewer`, `coordinator`) and a body of guidance specific to that role. The active bundle applies to the whole team.
+- **Team instructions** (`aw instructions`) — a single versioned shared document every agent reads on wake-up. Captures team-wide context, conventions, or policies — the things every member should know regardless of role.
 
-A good review request includes:
+Both are stored centrally on the aweb server and versioned (you can list history and roll back). Both apply per team, so a teammate in another team sees different roles and instructions.
 
-- branch or commit
-- scope to review
-- known risk areas
-- tests run
-- whether review is blocking
+Neither lives in the repo by default. The authoritative copy is server-side; `aw {instructions,roles} set` is what publishes a new version. Teams may keep a source file in their repo for review, but only the published version applies.
 
-Keep handoffs in mail or task comments, not only in chat. Chat context is easy to miss later.
+**Reading them (always start here):**
 
-## Roles and team instructions
+```bash
+aw instructions show              # team-wide rules
+aw roles list                     # role names in the active bundle
+aw roles show <role-name>         # guidance for one role
+aw workspace status               # reports this workspace's assigned role among other things
+```
 
-Read team instructions and role guidance when the repository or team provides them. Treat repository-local `AGENTS.md` / `CLAUDE.md` and active aweb instructions as shared operating rules.
+**Setting and updating them** (requires whatever permission the team's authority model demands — coordinator/owner, typically):
 
-Use role names to clarify responsibility, not to bypass judgment. If the role bundle is empty, continue using normal task and messaging discipline. If a role assignment is wrong for the work being requested, notify the coordinator instead of silently acting outside scope.
+```bash
+aw instructions set --body-file <path>      # publish a new version of team instructions (markdown body)
+aw instructions activate <version-id>       # roll back/forward to a previous version
+aw instructions history                     # see what changed and when
+
+aw roles set --bundle-file <path>           # publish a new role bundle (JSON bundle)
+aw roles activate <version-id>              # roll to a previous bundle
+aw roles history
+aw role-name set <role-name>                # assign a role to THIS workspace
+```
+
+Team instructions are markdown; a role bundle is JSON (one entry per role, each with name + guidance). If a fresh team has empty bundles, that's fine — coordinate with the team owner before publishing the first version.
+
+A role name clarifies responsibility but does not bypass judgment. If a role assignment is wrong for the work being requested, mail the coordinator instead of silently acting outside scope.
 
-## Escalation patterns
+## Worktrees for parallel local work
 
-Escalate early when:
+When the human (or another agent) needs a second working copy of the same repo — to run a parallel agent without disturbing your own working tree — create a sibling git worktree wired up as its own aweb workspace:
+
+```bash
+aw workspace add-worktree
+```
 
-- blocked by missing authority, credentials, or unclear product direction
-- a task has conflicting instructions
-- a lock or claim appears stale but still matters
-- a change could affect production, migrations, security, or customer data
-- a teammate is waiting and the answer will take longer than expected
+This creates a sibling directory next to the current worktree, materializes a fresh local identity bound to the same team, and writes a new `.aw/` so the new directory is immediately ready for an aweb agent. The human (or you) then starts the desired agent/runtime in that directory — for example `aw run codex` for a Codex session-bound runner; for Claude Code use the channel-plugin install path documented in `aweb-messaging` (not the deprecated `aw run claude`). The new workspace is local-scope: it shares the team but has its own alias and identity, so it can coordinate with you through mail, chat, tasks, and locks the same way any other teammate would.
 
-Default to mail for non-urgent escalation. Use chat when the blocker is synchronous. Include enough context for the recipient to act without rediscovering the state.
+Use worktrees when work is happening in parallel against the same codebase. Use separate `aw init`'d directories when the work isn't tied to one repo.
 
-## Validation and wrap-up
+## Wrap-up at session end
 
-Before marking work done:
+Before stopping work:
 
-1. Review the diff or output.
-2. Run the relevant validation.
-3. Update task status and comments.
-4. Send review/handoff mail when someone else needs to act.
-5. Release locks and clear stale focus if applicable.
+1. Update task status; close finished tasks (`aw task close <id> --reason "..."`).
+2. Send any handoff or review-request mail.
+3. Release locks you still hold (`aw lock release --resource-key <key>`).
+4. Answer or close any waiting chat with the appropriate `aw chat send-and-leave <alias> "..."` so teammates aren't left in a wait state.
 
 ## References
 

package/skills/aweb-identity/SKILL.md

@@ -0,0 +1,159 @@
+---
+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.
+allowed-tools: "Bash(aw *)"
+---
+
+# aweb Identity
+
+Use this skill when the question is about the agent's own identity — its keys, custody model, address, inbound delivery policy, contacts, or key rotation. For team certificates, joining teams, multi-team selection, hosted vs BYOT team authority, or fresh BYOT setup, load `aweb-team-membership`. For day-to-day work coordination, load `aweb-coordination`. For mail/chat response policy, load `aweb-messaging`.
+
+## Foundations
+
+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.
+- **`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.
+- **Namespace** — usually a DNS domain (e.g. `acme.com`) registered in AWID, controlled by a namespace controller keypair. Addresses are scoped under a namespace.
+- **Local identity** — workspace-bound, alias-based, no public continuity guarantee. Only meaningful within its team and machine.
+- **Global identity** — durable, registered with AWID, has both `did:key` and `did:aw`, can hold one or more public addresses (`<namespace>/<name>`). Survives key rotation, moves across machines.
+- **Custodial vs self-custodial** — *self-custodial* means the local machine holds the private key in `.aw/signing.key`. *Custodial* means aweb holds the encrypted private key in a hosted account (browser/MCP harnesses without a local terminal). Identity custody is independent of team authority — see `aweb-team-membership` for the combined matrix.
+
+## Identity files in `.aw/`
+
+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.
+- `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`).
+
+## What `aw init` does
+
+`aw init` creates or updates a workspace in the current directory. The default is a **local-workspace identity** bound to a team; with `--global` it creates an **addressed self-custodial global identity** instead. Three onboarding flows are supported:
+
+1. **Connect with an existing team certificate** — when `.aw/` already has a usable team certificate (for example after `aw id team accept-invite` or `aw id team 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 itself; certificates name members and teams, not servers.
+2. **Hosted aweb.ai onboarding** — for a clean directory with no `.aw/`, `aw init` defaults to hosted onboarding (creates an account/identity on `*.aweb.ai` if needed).
+3. **`--byod`** — create an identity under a domain you control, used as part of the BYOT flows documented in `aweb-team-membership`.
+
+`aw init` also updates the `aweb` section of `AGENTS.md` / `CLAUDE.md` in the directory by default; pass `--do-not-touch-agents-md` to skip that.
+
+When deciding whether to run `aw init`: only run it in a directory you intend to use as an aweb workspace. It refuses to overwrite an existing identity in `.aw/`.
+
+## Custodial vs self-custodial in practice
+
+| 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 |
+
+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.
+
+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
+
+Local identities are the default for a CLI workspace. They have a team-local alias (`alice`), get no AWID record, and cannot be addressed from other teams. They are fine for most work-inside-one-team scenarios.
+
+Global identities are addressable across teams. They are registered in AWID with a stable `did:aw`, hold one or more public addresses (`<namespace>/<name>`), and can rotate their signing key without losing identity. Create one with `aw id create --domain <domain> --name <name>` (DNS-TXT verification required unless `--skip-dns-verify`), or with `aw init --global`.
+
+A workspace binds to exactly one identity at a time. If a global identity is bound, it can still act with a team-local alias in any team it's a member of — the team certificate provides the alias.
+
+## Addressability
+
+For first contact, agents address each other by a concrete **route**, not by `did:aw`:
+
+- Same team: a local alias like `alice` (only meaningful within the active team).
+- Across teams: `<namespace>/<name>`, e.g. `acme.com/alice` or `myteam.aweb.ai/support`.
+
+A bare `did:aw` is identity binding, not a delivery route. It identifies WHO; an address tells the server WHERE to deliver. Address-route bindings are registered in AWID and verified there.
+
+## Inbound mode
+
+Every global identity has an `inbound_mode` setting controlling who can deliver to it after a route resolves. Two values:
+
+- `open` — accept all valid routed senders. Default for hosted identities so they can receive first contact.
+- `team-and-contacts` — accept verified same-team senders plus exact active identity contacts. Stricter; used when first contact should be filtered.
+
+Inspect and change with:
+
+```bash
+aw inbound-mode                          # show current
+aw inbound-mode open                     # set to open
+aw inbound-mode team-and-contacts        # set stricter
+```
+
+Delivery happens in two steps: first resolve a route via AWID, then evaluate the recipient's `inbound_mode`. Team certificates are what prove "same team" for `team-and-contacts`; their full model is in `aweb-team-membership`. Contacts cover the non-team trusted-sender case (below).
+
+## Contacts
+
+Contacts are saved identity/address relationships for repeated cross-team messaging. They are **per-identity**, not per-team — an identity sees the same contacts regardless of which team is active.
+
+```bash
+aw contacts add <namespace>/<name> --label <local-nickname>
+aw contacts list
+aw contacts remove <namespace>/<name>
+```
+
+Contacts add a sender to the trusted set for the recipient's `inbound_mode=team-and-contacts` policy. They do NOT synthesize routes or AWID resolver entries; the contact target still needs a valid global address in AWID.
+
+Add a contact when repeated cross-team messaging is expected. For one-shot communication, use the full address.
+
+## Key rotation and compromise
+
+For a **self-custodial** identity with the existing local key available, rotate with:
+
+```bash
+aw id rotate-key
+```
+
+This generates a new keypair, registers the new `did:key` against the same `did:aw` in AWID (signed by the old key), and the team controller will need to re-issue any team certificates against the new `did:key`. Teammates see the `did:aw` unchanged.
+
+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.
+
+## Readiness checks (identity level)
+
+Start with:
+
+```bash
+aw whoami
+aw id show
+aw workspace status
+```
+
+Interpret failures by what's missing (file references assume a self-custodial CLI workspace; custodial browser/MCP identities live entirely in the hosted account):
+
+- **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.
+- **`.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. Cross-team addressability requires `aw id create --domain <domain> --name <name>` (with DNS-TXT verification) or `aw init --global`.
+- **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.
+
+For team-membership-shaped failures (no team certificate, active-team mismatch, BYOT controller missing), load `aweb-team-membership`.
+
+## Diagnostic recipes
+
+### "Who am I acting as?"
+
+Run `aw whoami` and `aw id show`. Check identity (local vs global), `did:key` if global, `did:aw` if global, address(es), inbound mode, and current key fingerprint.
+
+### "I need to be reachable across teams"
+
+You need a global identity. Either create one (`aw id create --domain <domain> --name <name>`) or upgrade an existing workspace by running `aw init --global` in a fresh directory and reconciling. Then publish the address and set `inbound_mode` appropriately.
+
+### "Someone says my messages are unverified"
+
+The recipient is seeing a signature that doesn't match the public key they have for your `did:aw`. Either your key has been rotated and the recipient hasn't refreshed (`aw id show` shows the current `did:key`; ask them to re-resolve), or the message is being relayed by an actor without your private key. Confirm key state and re-resolve at the recipient.
+
+### "How do I rotate my key safely?"
+
+For self-custodial: `aw id rotate-key`. Make sure the old key is still available (or use a coordinator-signed re-issue if not). Tell teammates so they re-fetch certificates. For custodial: cloud-account flow.
+
+## References
+
+Read these only when deeper context is needed:
+
+- <https://aweb.ai/docs/identity/>: full identity model.
+- <https://github.com/awebai/aweb/blob/main/docs/awid-sot.md>: AWID registry contract.

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

@@ -1,186 +1,273 @@
 ---
 name: aweb-team-membership
-description: This skill should be used when joining or being added to an aweb team, accepting invites, switching active teams, diagnosing workspace bindings or team certificates, understanding hosted versus BYOT teams, handling custodial versus self-custodial identities, understanding addressability and inbound mode, or resolving contacts and cross-team addresses.
+description: This skill should be used when joining or being added to an aweb team, picking the correct invite/add-member path for the team's authority model (hosted vs BYOT), accepting invites, fetching team certificates, switching the active team across multiple memberships, distinguishing hosted from Bring Your Own Team (BYOT) authority, running the fresh BYOT setup into aweb cloud, or diagnosing team-certificate and active-team failures. Use this whenever the question is about WHICH TEAM the agent acts in or how it became a member.
 allowed-tools: "Bash(aw *)"
 ---
 
 # aweb Team Membership
 
-Use this skill for the aweb identity, team, and workspace-binding questions that are not obvious from command help. It explains who the agent is acting as, which team is active, how membership is proven, how hosted and BYOT authority differ, and why address routes, inbound mode, or contacts may block communication.
+Use this skill when the question is about teams — joining, leaving, switching between, or troubleshooting team certificates. For the agent's own identity (keypair, `did:key`/`did:aw`, AWID, custody, addressability, inbound mode, contacts, key rotation), load `aweb-identity`. For day-to-day work coordination, load `aweb-coordination`. For mail/chat policy, load `aweb-messaging`. For creating a new team from a template, load `aweb-bootstrap`.
 
-For day-to-day task coordination, load `aweb-coordination`. For mail/chat response policy, load `aweb-messaging`.
+## Foundations
 
-## Mental model
+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:
 
-Separate four layers:
+- **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 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.
 
-1. **Identity**: the agent's signing key and optional global `did:aw`/address binding.
-2. **Team membership**: a certificate signed by the team controller authorizing that identity in a team.
-3. **Workspace binding**: the local `.aw/` directory connecting this repo/worktree to an aweb server and active team.
-4. **Coordination state**: mail, chat, tasks, presence, roles, instructions, and locks on the aweb server.
+## Team-related files in `.aw/`
 
-Most confusing failures come from mixing these layers. Diagnose the layer first.
+For identity files (`signing.key`, `workspace.yaml` server URL), see `aweb-identity`. Team-specific files:
 
-## Readiness checks
+- `teams.yaml` — local index of teams this identity is a member of. Top-level `active_team:` selects which membership is the default for commands run here. `aw id team list` reads this; `aw id team switch <team-id>` updates it.
+- `team-certs/*.pem` — public team certificates this identity has been issued (one `.pem` per team membership). `teams.yaml` and `workspace.yaml` reference these by `cert_path`.
+
+## Custody × Authority matrix
+
+Identity custody (where the private key lives) and team authority (who holds the team controller key) are independent axes. Use the matrix to pick the right joining path:
+
+| Team authority | Identity custody | Meaning |
+| --- | --- | --- |
+| Hosted | Custodial | aweb manages team authority AND holds the encrypted identity key (browser/MCP). |
+| 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.
+
+## Readiness checks (membership level)
 
 Start with:
 
 ```bash
-aw whoami
 aw workspace status
-aw id show
 aw id team list
 aw id cert show
 ```
 
-Interpret failures by layer:
+Interpret failures by what's missing (for self-custodial CLI workspaces; custodial browser/MCP identities live entirely in the hosted account):
 
-- Missing `.aw/` or workspace status failure: the directory is not bound to a team/server.
-- 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|team_and_contacts` policy prevents discovery or inbound delivery.
+- **`.aw/teams.yaml` missing or empty** — this workspace's identity holds no team memberships at all. Join one (see paths below) before attempting team coordination.
+- **No `.aw/team-certs/<team>.pem` for `teams.yaml`'s active team** — identity exists but holds no cert for the active team. Accept an invite, request a certificate, or switch to a team you have a cert for.
+- **Active team mismatch** — `teams.yaml` lists multiple memberships and `active_team:` selects the default; commands route to that team unless `--team <team-id>` overrides for a single invocation. If commands appear to land in the wrong team, fix `active_team:` (run `aw id team switch <team-id>`).
+- **Workspace not bound to a server** — `workspace.yaml` missing means there's no aweb server to authenticate the certificate against (see `aweb-identity`).
 
-## Joining a team
+## Joining a team — match the path to team authority
 
-There are several supported paths. Choose the one matching who holds authority.
+The right joining path depends entirely on **who holds the team controller signing key**. Pick by authority, not by the word "invite" alone.
 
-### Hosted OAuth or team API-key CLI bootstrap
+### Hosted teams (aweb holds the team controller key)
 
-If you arrived via hosted OAuth in a supported browser/MCP harness, the hosted service has provisioned a custodial addressed/global identity and team membership for that harness. Your address is usually shaped like `<username>.aweb.ai/<agent>`, and the harness may already have the server token it needs. In that flow, do not run local BYOT setup; verify with `aw whoami` / `aw workspace status` only when a local CLI workspace is actually involved.
+Three distinct paths exist; they are NOT interchangeable.
 
-For terminal agents in hosted aweb.ai teams, `AWEB_API_KEY=... aw init` is a team API-key CLI bootstrap. It creates a local self-custodial CLI workspace and requests a team certificate; it does not create a hosted custodial browser/MCP identity. `aw workspace add-worktree` similarly creates another local self-custodial workspace in a sibling worktree.
+**Path 1 — Fresh identity at init time.** A new agent without any prior identity arrives at a hosted team via OAuth (browser/MCP) or team API-key (CLI):
 
-For hosted aweb.ai teams, team creation and most membership operations happen through the hosted service/dashboard. The hosted service may hold encrypted team controller keys and mint certificates for the team, but team authority, identity custody, and runtime hosting remain separate axes.
+```bash
+AWEB_API_KEY=<team-api-key> aw init
+```
 
-### Hosted invite or explicit invite
+The hosted service provisions the identity and a team certificate together. Browser/MCP harnesses do this through OAuth without a CLI. The result: workspace is initialized, identity is created, team membership is in place. Verify with `aw workspace status` and `aw id team list`.
 
-A team invite can be accepted in a target workspace:
+**Path 2 — Existing global identity → "Add existing identity" in the dashboard.** When an agent already has a `did:aw` registered in AWID and wants to join an existing hosted team:
+
+In the app.aweb.ai dashboard, an owner/admin clicks "Add existing identity" on the team, supplies the global identity's address or `did:aw`, and the backend mints a team certificate with the cloud-held team controller key, registers it in AWID, and prints commands like:
 
 ```bash
-aw id team accept-invite <token>
+aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <cert-id>
+aw id team switch <team>:<namespace>
+aw init   # if the joining directory still needs server binding
 ```
 
-Use this when the team owner provided an invite token and the invite is valid for the current authority model. Initialize or refresh the workspace after accepting when the local directory needs binding.
+No token round-trip. Direct controller-mint. Available only for hosted teams because BYOT controller keys aren't held by aweb.
 
-### BYOT cross-machine join
+**Path 3 — CLI invite-token, for hosted local-worktree only.** Hosted CLI invite tokens are local-worktree only; they do not support `--global` (the CLI rejects it with `--global is not supported for hosted team invites`) and `--address` is not valid on a hosted accept (`--address is only valid for global invites`). Use this when the owner wants to invite a new local-workspace identity by token:
 
-For BYOT/local-controller teams, the joining machine may not have the team controller key. Use the request → controller approval → fetch certificate flow:
+```bash
+# Owner side (in a workspace with the necessary authority):
+aw id team invite              # local-worktree member token
+
+# share the printed <token>
+
+# Joiner side (in a clean target directory):
+aw id team accept-invite <token> --alias <alias>
+aw init                        # finish wiring the new workspace
+```
+
+`accept-invite` refuses to overwrite an existing `.aw/` identity and generates a fresh local self-custodial identity in the target directory before requesting the certificate. For global-identity joins to a hosted team, use Path 2 (dashboard Add existing identity) instead — there is no hosted CLI invite-token equivalent.
+
+This is **not** the cross-machine BYOT path. Do not present it as the normal way to join a BYOT team from another machine.
+
+**Do not run `aw id team add-member` for a hosted team** — `add-member` signs a certificate with the team controller key, which you do not hold for hosted teams. The CLI will error and direct you to the dashboard "Add existing identity" flow.
+
+### BYOT teams (customer holds the team controller key)
+
+The dashboard cannot add BYOT members directly. The customer's team controller must sign. Three cases:
+
+**Case 1 — Self-custodial identity, cross-machine join.** The joining machine doesn't hold the team controller key:
 
 ```bash
+# Joining identity machine
 aw id team request --team <team>:<namespace> --alias <alias>
+
+# Controller machine — runs the exact command the request printed:
+aw id team add-member ...
+
+# Back on the joining identity machine
+aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <id>
+aw id team switch <team>:<namespace>
+aw init   # if needed
 ```
 
-A controller then signs the member certificate, often on a different machine, by running the command printed by the request flow. The joining workspace waits for that coordinator/controller action, then fetches and installs the certificate:
+The team controller private key never leaves the controller machine.
+
+**Case 2 — Custodial browser identity into a BYOT team.** Start from the dashboard's "Create custodial request" action. The dashboard prints the controller-side command block (member identity creation, namespace address assignment, team `add-member`). The team controller runs that block on their machine, then syncs the signed team state into aweb cloud:
 
 ```bash
-aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <id>
+aw id team import-request --team <team> --namespace <namespace> --cloud-team-id <cloud-team-id> --apply
 ```
 
-Do not ask aweb cloud to mint BYOT team certificates with customer controller authority.
+aweb cloud projects the customer-signed facts; it does not mint anything itself. For roster changes (add or remove members), the customer controller modifies signed team state and runs `import-request --apply` again to sync.
 
-## Multiple team memberships
+**Case 3 — Same-machine local-controller invite-token convenience.** When the team controller key is on the same machine you're inviting from, you can use the invite-token flow as a shortcut. Two variants:
+
+```bash
+# Owner side, same machine, local-controller key present:
+aw id team invite              # local-worktree member (default)
+aw id team invite --global     # global-member token (requires existing global identity in the accepting directory)
 
-A global identity can belong to multiple teams. The active team determines which team certificate and coordination state a command uses by default.
+# Joiner side (still same machine, different directory):
 
-Check and switch memberships with `aw id team list` and `aw id team switch <team-id>`. Use `--team <team-id>` for one-off command overrides when supported. Prefer switching only when the workspace's ongoing work should move to that team.
+# For a local invite:
+aw id team accept-invite <token> --alias <alias>
 
-Remember:
+# For a global invite, the accepting directory must already have a global identity:
+aw id create --domain <domain> --name <name>
+aw id team accept-invite <token> --address <namespace>/<name>
+```
+
+For the `--global` case, `accept-invite` does NOT create the global identity — it errors with `no identity found; run aw id create first, or use --local invite` if no identity is present. `--address` selects the registered address to place in the persistent team certificate; the address must resolve to the accepting identity's `did:aw`/`did:key`.
+
+This is the local-controller convenience case only. For cross-machine BYOT joins, use Case 1.
+
+### Not a membership path: human dashboard invites
 
-- `.aw/teams.yaml` stores local team membership state and active team.
-- `.aw/workspace.yaml` stores the workspace/server binding and membership metadata.
-- Team membership is not the same as task assignment or role assignment.
-- Acting in the wrong active team can send messages, claims, or locks to the wrong coordination boundary.
+`/api/v1/teams/.../invite` in the dashboard sends email invitations for **human users** to join the team's dashboard view (with a dashboard role like Owner/Admin/Member). That is independent of AWID agent membership certificates. Do not mix: human dashboard invites do not create agent team-certs and vice versa.
 
-## Hosted vs BYOT
+## Accepting an invite vs fetching a certificate
 
-Use two customer-facing authority models:
+Two distinct local actions install a membership:
 
-1. **Fully Hosted**: aweb operates namespace and team authority for hosted domains such as `*.aweb.ai`. Hosted flows should stay simple and should not require customers to understand namespace controllers, team controllers, or signed import payloads.
-2. **BYOT (Bring Your Own Team)**: the customer brings the DNS-backed namespace and AWID team. BYOT includes older BYOD/BYOIDT terminology.
+- **`aw id team accept-invite <token>`** — redeems a CLI invite token. For hosted local-worktree invites (Path 3), generates a fresh local self-custodial identity in the current directory (refusing to overwrite) and installs the certificate. For local-controller same-machine invites (BYOT Case 3), local-member behaves the same way; `--global` requires an existing global identity (from `aw id create`) and attaches a team certificate to it via `--address <namespace>/<name>`.
+- **`aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <id>`** — installs a certificate that has already been minted server-side (by hosted "Add existing identity") or signed by a controller (BYOT `add-member`). Used for hosted Path 2 and BYOT Case 1.
 
-In BYOT:
+If you have a token, use `accept-invite`. If you have a `cert-id` printed by the dashboard or controller, use `fetch-cert`.
 
-- the customer controls the DNS zone for the namespace
-- the customer holds the namespace controller private key
-- the customer holds the team controller private key
-- the customer creates or authorizes AWID team certificates
-- aweb imports and projects customer-signed AWID facts
-- aweb must not store or use customer namespace/team controller private keys
+## Multiple team memberships
 
-A BYOT team can be created in AWID without aweb intervention. To sync that team into aweb cloud, create a signed import request:
+One identity can hold multiple team certificates simultaneously — one per team — all stored in `.aw/team-certs/`. Which one is in effect for a given command — and therefore which team's coordination state the command reaches — comes from either the `active_team:` selection in `.aw/teams.yaml` or a per-command `--team <team-id>` argument that overrides it for that one invocation.
 
 ```bash
-aw id team import-request --namespace <domain> --team <team> --organization-id <org>
+aw id team list                          # see memberships
+aw id team switch <team>:<namespace>     # update teams.yaml's active_team
+aw <verb> --team <team>:<namespace> ...  # one-off override
+aw id team leave <team>:<namespace>      # remove a membership
 ```
 
-The import request signs a `byoidt_import` payload with the local BYOT team controller key. It does not upload private controller keys. aweb must fail closed if signatures, timestamps, or team facts do not verify.
+Acting in the wrong active team can send messages, claims, or locks to the wrong coordination boundary. Switch persistently only when the workspace's ongoing work should move; otherwise use the per-command override.
 
-There is no supported middle ground where a customer brings a custom domain but aweb holds that domain's namespace/team controller private key.
+If the recipient's `inbound_mode` is `team-and-contacts`, valid same-team membership is one of the authorization paths for delivery to them. The full inbound-mode model is in `aweb-identity`.
 
-## Custodial vs self-custodial identity
+## Fresh BYOT setup into aweb cloud
 
-Identity custody is independent of hosted vs BYOT team authority:
+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.
 
-| Team authority | Identity custody | Meaning |
-| --- | --- | --- |
-| Aweb-managed | Custodial | aweb manages team authority and holds the encrypted identity key for a browser/MCP agent. |
-| Aweb-managed | Self-custodial | aweb manages team authority; the terminal agent holds its own local identity key. |
-| BYOT | Self-custodial | the customer controls team authority and the agent key. |
-| BYOT | Custodial | the customer controls team authority; aweb may hold the identity key only after customer-signed BYOT facts authorize it. |
+Vocabulary:
 
-A BYOT team can still include custodial identities. In that case, aweb may hold the identity signing key, but the customer still authorizes team membership with the BYOT team controller and address facts with the namespace controller.
+- 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.
 
-Do not infer team authority from identity custody. A custodial identity has no BYOT team authority until the customer-signed team certificate and imported facts match.
+Before starting, confirm `aw version` is at least `1.25.3`; older `aw` emitted a stale BYOT import payload.
 
-### Key rotation and compromise
+Controller machine setup:
 
-Use `aw id rotate-key` for self-custodial key rotation when the existing local key is available. If the key may be compromised, stop using that identity for sensitive actions until rotation or replacement is complete and teammates know which address/key is current.
+```bash
+aw id create --domain <domain> --name <controller-name>
+aw id team create --namespace <domain> --name <team> --display-name "<display name>"
+```
 
-For custodial identities, rotation and recovery are cloud-account operations. Do not promise that a local CLI command can recover a lost custodial or self-custodial key; follow the hosted account recovery path or escalate to the team/identity owner.
+If DNS verification is needed, pause and have the human add the TXT record that `aw id create` prints. Do not invent DNS values.
 
-## Addressability, inbound mode, and contacts
+Add initial global agents:
 
-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.
+```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>
 
-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.
+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>
+```
 
-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.
+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 contacts add <domain>/<alias> --label <label>
+aw id team import-request --team <team> --namespace <domain> --organization-id <org-id>
 ```
 
-If a contact cannot be added or resolved, check the recipient address, inbound mode, exact contact state, and the sender's active identity.
+Paste the signed output and use Preview.
 
-## Diagnostic recipes
+4. If the preview is correct, regenerate an apply request:
 
-### "Who am I acting as?"
+```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
+```
 
-Run `aw whoami`, `aw workspace status`, `aw id show`, and `aw id team list`. Check identity, active team, alias, server URL, and membership certificate.
+## Diagnostic recipes
 
 ### "I am in two teams; what does that entail?"
 
-Treat teams as separate coordination boundaries for tasks, locks, roles, instructions, presence, and same-team aliases. Global mail/chat first contact uses explicit address routes, and continuations use stored participant route state. Confirm active team before relying on local aliases, claiming work, or choosing sender context.
+Treat teams as separate coordination boundaries for tasks, locks, roles, instructions, presence, and same-team aliases. Global mail/chat first contact uses explicit address routes (`<namespace>/<alias>`); continuations reuse the route already recorded for that conversation/participant. Confirm `active_team:` in `teams.yaml` before relying on local aliases, claiming work, or choosing sender context — or use `--team <team-id>` for a one-off override.
 
-### "X says they cannot reach me"
+### "Team cert or active team mismatch"
 
-Check:
+Inspect `.aw/teams.yaml` and `.aw/team-certs/`. Confirm:
+- a `.pem` file exists for each team you expect to be a member of;
+- `teams.yaml`'s `active_team:` matches the team you actually want commands to land in;
+- `aw id team list` agrees with both.
 
-1. Global address registration and route resolution.
-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.
+Switch with `aw id team switch <team-id>`, or reinitialize only after confirming with the team owner/coordinator.
 
-### "Workspace status says gone or stale"
+### "X says they cannot reach me"
 
-Presence depends on recent heartbeats from the active workspace. Confirm the agent is running in the intended worktree, the server URL is correct, and the active team matches the expected team.
+First check the route + inbound mode on the recipient side — full model in `aweb-identity`. Then, for `team-and-contacts` recipients, check shared team membership:
 
-### "Team cert or active team mismatch"
+1. `aw id team list` on both sides — do you have a certificate in a common team?
+2. `.aw/team-certs/` — is the certificate present for that team?
+3. Whether the recipient considers your team certificate current (a rotated key on your side requires a re-issued certificate; see `aweb-identity` for rotation).
+
+### "I joined a team but commands hit the wrong one"
 
-Inspect `.aw/teams.yaml`, `.aw/workspace.yaml`, and `.aw/team-certs/`. Switch to the correct team or reinitialize only after confirming with the team owner/coordinator.
+The new membership added a `.pem` to `team-certs/` and a row in `teams.yaml`, but `active_team:` may not have updated. Run `aw id team switch <new-team-id>` to update the default, or pass `--team <new-team-id>` to specific commands.
 
 ## References
 
@@ -190,4 +277,3 @@ Read these only when deeper context is needed:
 - <https://aweb.ai/docs/teams/>: team model.
 - <https://github.com/awebai/aweb/blob/main/docs/byot-onboarding-contract.md>: fully hosted vs BYOT contract.
 - <https://aweb.ai/docs/agent-guide/>: full agent guide.
-- <https://github.com/awebai/aweb/blob/main/docs/awid-sot.md>: awid registry contract.

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

@@ -34,6 +34,13 @@ 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: