humanish 0.94.0 → 0.96.0

package/skills/humanish/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: humanish
-description: Install and configure Humanish CLI in a JavaScript app as an open-source-safe persona simulation harness. Use when an agent needs to add humanish, run safe first setup, create synthetic personas or scenarios, configure env var names without values, capture the email or SMS an app sends so a persona can complete an email-gated flow (e.g. a signup verification link or one-time code), run verification and Observer commands, or draft public-safe feedback issues without GitHub mutation.
+description: Install and configure Humanish CLI in a JavaScript app as an open-source-safe persona simulation harness. Use when an agent needs to add humanish, run safe first setup, create synthetic personas or scenarios, configure env var names without values, capture the email an app sends so a persona can complete an email-gated flow (e.g. a signup verification link or one-time code), run verification and Observer commands, or draft public-safe feedback issues without GitHub mutation.
 ---
 
 # Humanish CLI
@@ -36,10 +36,25 @@ Everything it shows has a machine-readable equivalent, which is what you want:
 | browsing runs | `npx humanish runs --json` |
 | starting a run | `npx humanish lab run <lab> --json --no-open` |
 | a run's outcome | `npx humanish review --run <id> --json` |
+| communication setup | `npx humanish comms providers --json` and `npx humanish comms connections list --json` |
 
 If a human asks you to "open the TUI", tell them the command to type; do not run
 it on their behalf.
 
+For AgentMail credential setup, a human can open `humanish tui`, press `c`,
+and choose **Add API key**. Hidden entry returns to Connections after saving or
+cancelling. The key is stored for that OS user, while the connection profile is
+project-local. Never ask for the key in chat. The CLI alternative is
+`humanish keys set agentmail` (hidden prompt; agents may use `--stdin` from an
+authorized credential source), followed by
+`humanish comms connections add agentmail --json`. Existing env/file precedence
+and `HUMANISH_STRICT_KEYS=1` still apply. Read installed provider capabilities:
+use `humanish comms check --online --json` for read-only authentication.
+Authentication does not establish mailbox permissions, capacity or delivery.
+`humanish comms configure --lab <path> --json` previews an ignored lab copy;
+add `--apply --plan-token <digest>` to save the reviewed version. Launch its
+exact returned path, not a basename that could resolve to another manifest.
+
 ## Setup Workflow
 
 1. Inspect public target-repo files only: `package.json`, docs, route/app
@@ -203,15 +218,36 @@ npx humanish watch first-run
 npx humanish lab run first-run --json --no-open
 ```
 
-### Off-app email/SMS verification (comms)
-
-When a flow is gated behind an email or SMS the app itself SENDS — a signup
-verification link, a one-time code, a magic link — add a `comms:` block. The
-harness redirects the app's email-API sends into a catch INSIDE the sandbox (no
-mail leaves the machine), gives the persona a synthetic inbox to open and click
-through, and writes a digest-only `humanish.comms-thread.v1` evidence artifact (no
-raw address/link/code persists). Reach for this whenever a persona must read mail
-the app sent it to finish a step.
+### Off-app email verification (comms)
+
+When a flow needs an email from the app — a verification link, one-time code or
+magic link — configure an inbox so the participant can read and use that message.
+Humanish supports local capture and fresh hosted receiving, with different setup
+and privacy behavior.
+
+Choose the transport to match the app:
+
+- **Local capture** (below): app send configuration can point at a test catch;
+  no external mail service is needed. It tests the email flow without proving
+  real delivery.
+- **Real AgentMail receiving**: use `comms.email: { connection: agentmail }`.
+  Humanish acquires one fresh hosted inbox per participant before desktops start.
+  The app sends normally. Requires a configured organization-scoped key and
+  app-url/clone/local-tree hosted computer-use participants; concurrent shared
+  worlds work, sequential shared worlds and local-agent do not. Do not combine
+  connection with capture settings or substitute fresh addresses for existing
+  account identities. `allowedOrigins` can name additional trusted link origins.
+
+Real mail can reach hosted desktops, actor models and analysis models. Screenshots
+can contain it. Such runs remain `local_only` even after screenshot blurring;
+this is a publication restriction, not local-only processing. Provider charges
+and model charges are separate. Use `humanish comms recover --json` after an
+interrupted run, then `humanish comms recover --run <id> --apply --json` for its
+privately recorded resources. Never derive deletion authority from run artifacts.
+SMS, participant sending, borrowed inboxes and other providers remain unavailable.
+See `docs/architecture/real-email-receiving.md` for limits and recovery.
+
+The following configuration selects **local capture**:
 
 ```yaml
 comms:
@@ -247,10 +283,15 @@ The app keeps calling its email API normally (Resend/SendGrid-shaped, or a custo
 profile); only the base URL is redirected. Route support: the clone/local-tree
 computer-use route (inbox on the sandbox's own loopback) and the CONCURRENT
 shared-world route (inbox getHost-exposed from the subject sandbox; the default
-since every seat now runs live at once). Declared anywhere else — app-url /
-operator-provided subjects, or a sequential `concurrency: 1` shared world — it is
-warned inert at parse: no catch exists there and no actor hears about an inbox.
-It needs `python3` in the subject sandbox (the stock E2B desktop has it).
+since every seat now runs live at once). SMTP capture is supported on per-lane
+provisioned routes; shared-world SMTP is rejected because it is not wired there.
+For app-url/operator-provided subjects, run `humanish comms catch` on a reachable
+host, point the app's email sends at that catch, and declare
+`comms.email.external.catchBaseUrl` (plus `inboxBaseUrl` if different). A declared
+`authTokenEnv` is an environment variable name, never a credential value.
+Sequential `concurrency: 1` shared-world email remains unwired; do not silently
+change study concurrency to work around that limitation. The in-sandbox catch
+needs `python3` (the stock E2B desktop has it).
 Evidence is digest-only (`humanish.comms-thread.v1` — counts and digests, never
 raw mail); the *readable* proof a persona saw the email is its screenshots of the
 inbox page. See `docs/contracts/schemas.md` for the full `comms:` shape and