🤖 Native onboarding: a link → the app → signed in

Status: design (2026-07-09), sequenced for building. The goal, stated as the experience: someone taps an invite link and ends up in the native app, in the space, and signed in with a passkey — and when they later set up their other device (Mac first or iPhone first, either order), the passkey ceremony on the second device is the sync: everything appears.

This replaces the retired paste-a-link joins (deleted 2026-07-08 with the sign-in-only door) with something better, not with their return. The design leans on two invariants from docs/onboarding-and-home-server.md that are already load-bearing:

• Deferred claim. Opening a link never consumes the invite — claiming is an explicit tap. This is what makes "the app AND the browser both saw the link" safe: whoever joins claims; everyone else just looked.
• Fragments never reach a server. The invite secret T lives in the #fragment; native parsing (InviteLink.swift) and the claim derivation (InviteCrypto.derive) keep it that way.

What already exists (more than it looks)

The 2026-07-09 create-a-space work built the missing spine without meaning to advertise it:

• SpaceClaim (LChatCore) claims a key-invite natively: derive {id, wrapKey, claimSecret} from T, GET /api/key-invite/{id}, claim for a device token, generate the identity keypair, register the pubkey, resolve myUserId, even bootstrap the instance key when first-in. Today it handles the setup-invite shape; the member/DM and add-device shapes are small extensions (below).
• Every instance already serves the AASA. GET /.well-known/apple-app-site-association (main.go serveAASA) matches /join/* for the iOS app id on every instance, tested in handlers_test.go. The server side of universal links shipped long ago.
• inviteLink(fromOpenedURL:) + parseJoinLink (LChatCore) still parse both the custom scheme (elevenmessenger://add?url=… — the join page's "Open in Eleven" button) and raw https join links.
• Passkey sign-in and the vault sync are shipped on both platforms; the cross-device story ("the second device's passkey dance does the sync") is already true for everything in the vault.

What's missing is the middle: neither app currently handles a join URL at all (iOS has no onOpenURL; the Mac accepts only the sign-in callback), the iOS applinks entitlement covers *.elevenmessenger.com but not *.11ch.at where the fleet actually lives, and there's no native welcome screen.

The flow, end to end

A. The link opens the app (iOS first)

1. Entitlements: add applinks:*.11ch.at beside the existing applinks:*.elevenmessenger.com. (Apple's rule: one wildcard prefix per entry, every domain named in the shipped binary — so arbitrary custom domains like chat.paulca.com can't be covered generically. They keep the web join page, which still works everywhere, plus its "Open in Eleven" custom-scheme button that reaches the same handler.)
2. Handlers: onOpenURL + onContinueUserActivity(NSUserActivityTypeBrowsingWeb) on the iOS root → inviteLink(fromOpenedURL:) → parseJoinLink → present the welcome card (never claim here — deferred claim).
3. App not installed: the link lands on the web join page exactly as today. Distribution polish (smart App Store banner on join.html) is phase 4 of the onboarding doc and stays there.

B. The native welcome card

A sheet with the space's public branding (/api/group name + /api/server-avatar — public by design so this exact card can exist), the suggested name from the fragment's ~name tail prefilled into a name field, and one button: Join. Tapping Join is the explicit claim.

SpaceClaim grows the two remaining invite shapes (both already documented in join.js):

• Member/DM invite ({threadKey} payload): decrypt the thread key with wrapKey, generate the keypair, wrap the thread key to our own new pubkey, send that as wrapped in the claim. Lands in the pending DM.
• Add-device link ({priv, pub} payload): adopt the existing identity — no new keypair, no label publish.

Either way the result is a SavedInstance through the same app.add path, which persists it, selects it, and pushes it to the vault when signed in.

C. The passkey moment

Right after landing in the space — not before, the chat is the payoff — the app makes the save-your-spaces ask:

• No home session yet: one inline card at the top of the thread list (never a toast): "Keep this space safe — save it to Eleven" → the existing explicit mint (HomeSignInModel.backUp). This is the native twin of the welcome conversation's access step, which deliberately runs first on the web too. Declining defers, matching the web's reminder cadence.
• Session exists (e.g. an invited member who already had Eleven): nothing to ask — app.add already pushed the new space into the vault.

D. The second device

Nothing new to build: install the app → Sign in → the passkey ceremony restores the vault → every space appears with credentials, order, stars. This is shipped behavior; the design just makes it the stated contract: the sync IS the sign-in.

E. The Mac

Same shape, one platform beat behind (iOS-first rule):

1. Server: serveAASA adds the Mac app id (J5NDF5PCD8.com.elevenmessenger.messenger.mac) beside the iOS one — done (PR #1383).
2. Entitlements: the Mac gains its first applinks entries (same domains) — done (LChatMac.entitlements, with #1383's server half; the Mac App ID needs the Associated Domains capability before a release build's profile authorizes it).
3. LChatMacApp.onOpenURL grows a second accepted URL family: join links → the same welcome card in a sheet.

macOS routes universal links less aggressively than iOS (browser-first unless the user opts in), so the join page's "Open in Eleven" button matters more here — it fires the custom scheme, which macOS routes unconditionally.

What deliberately stays out

• ~~*No welcome conversation natively (yet).~~ Superseded — the interpreter shipped. The Swift flow interpreter is real now (FlowEngine.swift running the bundled Flows/welcome.json, a byte-derived copy of welcome.flow.js drift-gated by test/flow.test.mjs, hosted by ElevenConversationModel), and a native member/DM-invite claim creates the welcome app-thread and lands the joiner in the full conversation — which asks their name — on both platforms (SpaceClaim.claim → WelcomeLanding.markPending/threadToLand, #1376). The passkey ceremony step stays web-only by design (env.native skips it — native access is* the sign-in).
• No QR scanning revival, no paste field. Links open the app; that's the door. (The NSCameraUsageDescription string left from the retired QR flow should be dropped when the welcome card lands.)
• No change to web joins. join.html remains the universal fallback and the only path on uncovered custom domains.

Build order

1. iOS: entitlement + URL handlers + welcome card + SpaceClaim member/DM + add-device shapes (with tests against join.js's shapes) + the post-join passkey nudge. Ships alone; Mac unaffected.
2. Server: AASA gains the Mac app id (one-line change + test update).
3. Mac: entitlements + handler + the same card.
4. Polish: smart banner on join.html; drop the stale camera-permission string; revisit the welcome conversation once scripts run natively.

Risks / open questions

• TestFlight + associated domains: applinks work on TestFlight builds via the AASA's app id — no ?mode=developer needed for the new wildcard (that mode never worked on macOS anyway; see LChatMac-Dev.entitlements).
• Wildcard AASA fetch: Apple's CDN fetches the AASA per-host on install; *.11ch.at hosts each serve it (single binary — already true).
• A claimed-but-never-saved device: someone joins natively, never saves a passkey, loses the phone → the space is orphaned like any keyless loss. Unchanged from web behavior; the reminder cadence is the mitigation.