US-2.1. — As a user who already has a Hypermedia identity, I want to join a site from the browser so that I can participate in it.

Acceptance Criteria

Entry & join trigger

A Join button is visible in the site top bar when the user is not yet a member

Tapping Join opens a modal within the site context.

When user tries to comment, follow or bookmark the same flow starts.

The modal shows the site name (Ethosfera), explains it is built with Seed Hypermedia, and offers two options: Create identity or Already have a Hypermedia identity

A third low-commitment option is visible: "I have a different identity domain"

Tapping "Already have a Hypermedia identity" takes the user to the sign-in flow

Sign in — email

The sign-in screen is branded as Seed Hypermedia — distinct from the site UI

The headline reads "Sign in to join [site name]" — the goal stays visible

Email field is required and validates correct format before submission

Submitting a valid email advances to the passkey screen

Sign in — passkey

The passkey screen shows the email the user is signing in as

Primary action is "Sign in with passkey" using device biometrics or PIN

A fallback "Use another email" option is available

Successful passkey confirmation advances to the join confirmation screen

Join confirmation

The join confirmation screen shows the user's name and email so they can verify which identity they are joining with

Copy changes depending if it is one account or +1 account.

Primary CTA is "Continue as <account> which joins the site and returns the user to the site as a member

Joined state

The Join button disappears from the top bar

The user's avatar appears in the top bar

The comment and participation areas become active

A confirmation alert appears: "You've joined [site name] — you can now comment and participate" and auto-dismisses after ~3 seconds

Remove this step please if there is no more that one account!

Basic Flow

User arrives at Ethosfera as a guest and sees the Join button

User taps Join — modal opens within the site

User taps "Already have a Hypermedia identity"

User enters email linked to their Seed identity

User taps Continue — advances to passkey screen

User confirms with passkey (Face ID, Touch ID, or PIN)

Join confirmation screen shows name and email

User taps "Start participating" — joined

Returns to site as member — Join button gone, avatar visible, comment area active

Confirmation alert appears and auto-dismisses

Edge Cases

Email

⚠️ Invalid email format → inline error: "That doesn't look like a valid email. Check for typos and try again." Button disabled until fixed

⚠️ Email not linked to any Seed identity → error with option to create one instead: "No Seed identity found for this email. Want to create one?"

⚠️User enters email from a different domain/site → redirect to "I have an identity from another site" path

Passkey

⚠️ Passkey fails or is cancelled → returns to passkey screen with retry option and "Send a verification code instead" fallback

⚠️Device doesn't support passkey → verification code fallback offered automatically

⚠️User taps "Use another email" → returns to email screen, previous entry cleared

Navigation

⚠️User closes the modal mid-flow → returns to site as guest, no partial state created

⚠️User presses browser back mid-flow → returns to previous step without losing email entry

US-2.2. As a user who already has a remote Hypermedia identity , I want to join a site from the app so that I can participate in it.

When user comes from commenting content:

Acceptance Criteria

A Join button is visible in the site top bar. Tapping Join opens a modal within the app showing the site name and two options: Create identity in Hypermedia and Already have a Hypermedia identity, plus a quiet link "I have a different identity domain"

The modal copy explains the site is built with Hypermedia and that creating an identity takes two minutes — no technical language

Tapping "Already have a Hypermedia identity" takes the user to the email screen inside the Hypermedia sign-in flow

Valid email advances to the passkey screen showing "Good to see you again" and the email address to remind

Passkey confirmation uses device biometrics or PIN

On successful passkey confirmation the user sees a "Which account would you like to use?" screen showing all their available accounts, the currently active identity is pre-selected with a checkmark

Primary CTA is "Start participating" — one tap, no further steps

On joining, the site is added to Joined Sites in the sidebar immediately and the Join button disappears from the site top bar

A toast alert appears: "You've joined [site name] — you can now comment and participate" and auto-dismisses after ~5 seconds

No new identity is created — the user's existing remote identity is used throughout and user is as a full member with participation features

Basic Flow

User is viewing a site in the app — Join button visible in top bar

Taps Join — modal opens showing "Join [site name]"

Taps "Already have a Hypermedia identity"

Enters email linked to their Hypermedia identity

Taps Continue — passkey screen appears

Confirms with passkey

"Join [site name]" screen shows available accounts — primary identity pre-selected

Taps "Continue as <account>"

Returns to site as member — Join button gone, site added to sidebar, toast appears

Edge Cases

⚠️ Invalid email format → inline error: "That doesn't look like a valid email. Check for typos and try again." Button disabled until fixed

⚠️ Email not linked to any Hypermedia identity → "No Hypermedia identity found for this email." → prompted to create account

⚠️ Device does not support passkeys → fallback method offered, user not blocked (password needs to be developed later)

⚠️User cancels the biometric prompt → returns to passkey screen, can retry

⚠️ Passkey creation fails due to device error → retry option shown

Clear error messages: avoid: "Failed to fletched" "Invalid Handoff token" _ review this one by one

⚠️ User taps "Use another email" → returns to email screen, previous entry cleared

⚠️ User is already a member of this site → join confirmation is skipped, user lands directly as a member with no duplicate entry created

⚠️ User closes the modal mid-flow → returns to site as guest, no partial state created, Join button remains visible