Onboarding: 'Create a community' needs an explanation layer — hosted (Builderlab) vs self-hosted paths, prerequisites up front

[sardoru]

Summary

First-run onboarding currently assumes you already know what a Buzz community is (a relay) and how the hosted service (Builderlab) fits in. As a new user trying to create my own community, I hit a chain of dead ends and unexplained errors before piecing the model together by reading source code. This issue proposes an explanation layer in onboarding: a two-path "Create a community" flow (hosted vs self-hosted) with prerequisites stated up front, plus an info affordance explaining the relay concept.

What happened (fresh user, macOS)

Desktop app (v0.4.18): On the welcome screen I clicked "Create your community" — it opened the browser at the buzz.xyz marketing home page, and nothing happened after that. No setup instructions, no return path into the app, no hint about what to do next. Complete dead end.

I can see that on current main the button now opens the Builderlab hosted sign-in instead (community-choice-create → setIsHostedSignInOpen(true)), which is a real improvement — but the information gap below still applies to the current flow.

CLI: I had installed buzz-cli first, hoping to create a community from there. Every relay-touching command failed with a JSON relay/network error, because the default BUZZ_RELAY_URL is http://localhost:3000 and nothing is listening there on a fresh machine (and BUZZ_PRIVATE_KEY is unset). Nothing in --help or the error output explains that a community is a relay, that there is no buzz community create, or where a relay is supposed to come from (hosted vs just dev vs the ghcr.io/block/buzz image).

Docs: The README quickstart is developer-oriented (just setup && just build, just dev); docs/multi-tenant-relay.md is a formal spec; RELEASING.md is for maintainers. There's currently no user-facing "How to create your community" page that the app or CLI could link to.

Friction points in the hosted (Builderlab) flow

Once I found the hosted flow, each requirement was discovered by failing rather than being stated up front:

• Builderlab is unexplained. The flow opens a browser to app.builderlab.xyz with no in-app context: what Builderlab is, why a separate account is needed, or what it will be used for.
• missing_mapping — "Connect your Buzz identity before creating a community." This ordering requirement (bind your npub to the Builderlab account first) is only surfaced as a post-hoc error.
• invalid_name — the name rule (^[a-z0-9]+(?:-[a-z0-9]+)*$, i.e. lowercase letters, numbers, hyphens) is only revealed after a rejected submission, not shown on the input.
• Limits and results are invisible until after the fact — the 3-community limit (limit_reached) and the resulting address shape (<name>.communities.buzz.xyz) aren't communicated before creation.
• identity_already_bound / pubkey_already_bound are confusing without an upfront explanation of the one-account-per-identity binding model.

Proposal

1. Two-path chooser on "Create a community". Instead of jumping straight into hosted sign-in, present two clearly described options:
   • Hosted (recommended) — "We run the relay for you at <name>.communities.buzz.xyz. You'll sign in with Builderlab, connect your Buzz identity, and pick a name (lowercase letters, numbers, hyphens; up to 3 communities)." Then the existing sign-in flow, with those steps shown as a checklist (Sign in → Connect identity → Name it).
   • Self-hosted — link to a task-oriented guide: run ghcr.io/block/buzz (or just dev), required env, then connect via the existing "I already have a community" / relay-URL path. Today self-hosting is only discoverable through developer docs.
2. Info icon on the welcome cards ("What's a community?") — one popover explaining the model: a community lives on a relay; your identity is a keypair that works on any relay; you can join with an invite, use a hosted relay, or run your own. This single paragraph would have saved me hours.
3. Preflight instead of postflight errors in the hosted flow — inline name validation with the rule visible, an explicit "Connect your Buzz identity" step before the create form (eliminating missing_mapping as a user-visible error), and the community limit shown up front.
4. CLI hint on connection failure — when the relay at the configured URL is unreachable, append a pointer: "No relay is running at <url>. To create or join a community, see <guide-url>."
5. Never link to the marketing home from onboarding — any external link should deep-link to a setup/how-to page.

Environment

• Buzz Desktop v0.4.18 (dead-end observed there; latest at time of writing v0.4.22), macOS (Apple Silicon)
• buzz-cli against default http://localhost:3000 on a machine with no local relay
• Hosted community successfully created afterwards (exchange.communities.buzz.xyz) — so the flow works once you know the shape; the gap is entirely in discoverability.

Happy to help draft the onboarding copy or the "Create your community" doc page if this direction sounds right.