@awebai/pi 0.1.11 → 0.1.12

package/package.json

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