# 🤖 Conversational onboarding & the admin mini-app — design

Status: **phases 1–3 implemented** (roles, the setup conversation, the Admin
app v1 — landed with this doc); later phases still proposed. Captured from
design discussion 2026-07-06.

> **Language note (2026-07-22):** this doc predates the anchor model
> (`accounts-and-recovery.md`) and still says "Save a passkey" / "backup" in
> places. The shipped flows say **"Sign in"** — the member-facing framing is
> signing in with Eleven, never the mechanism. Read the passkey/backup
> wording here as design history, not shipped copy. The "recovery kit"
> (§ keys, path 2) is likewise superseded by that doc's paper-kit phase.
Builds on `onboarding-and-home-server.md` (welcome page, home-server vault,
fragility banner — phases 1–3a shipped) and the `/tutorial` mini-app
(`web/static/tutorial.js`), whose client-driven, in-Eleven's-voice pattern
this design generalises.

> **Follow-on: `conversation-scripts.md`.** With iOS/Mac moving to fully
> native rendering, these conversations become **flows-as-data** interpreted
> by a per-platform engine (web first, Swift when the native surfaces land),
> so one script definition serves every client. The flows and trust
> boundaries described here are unchanged — only where the step logic lives.

## Goals

Two onboarding moments, one shape for both:

- **Server-admin onboarding.** Standing up a server should land the admin in
  the **chat view**, in a conversation with Eleven that walks setup — no
  `/admin` console, no forms-first overlay. `/admin` is eventually retired,
  replaced by an **admin mini-app** only admins can see.
- **User onboarding.** Joining from an invite link should land the joiner in
  the **chat view**, where Eleven runs a welcome script — name, avatar, "save
  your profile", then an invitation to take the tour.

The bar from CLAUDE.md holds: familiar before novel; a command/script invokes a
response *in place*; delight rides on top. Onboarding is a conversation because
that's the most familiar thing in a chat app — not because it's clever.

## Non-negotiables

- **The scripts are deterministic, always.** Client-driven, like `/tutorial` —
  never a bot round-trip, never AI. A fresh instance has no sidecar and no API
  key, and "enable AI?" is itself one of the setup questions, so AI cannot be a
  dependency of asking it. Eleven owns the *voice*; the logic is a script with
  tap-chips and captured composer answers. AI Eleven converses *after* setup,
  where present.
- **E2E rules unchanged.** Everything the scripts collect lands on existing
  trust boundaries: display names encrypted under the instance key; group name,
  server photo, and contact email are admin-set **branding/settings**
  (plaintext by design, already carved out in CLAUDE.md); no new plaintext
  categories are introduced.
- **One voice.** Where a bot sidecar exists, its welcome-DM behaviour stands
  down in favour of the client script (see *Joiner flow*): two Elevens must
  never greet the same person.

---

## 1. Prerequisite: admin becomes a role, not just a token

Today "admin" is only a bearer token (`requireAdmin` checks
`checkAdmin(token)`); roster users carry no admin flag. Everything here — an
admin-only mini-app, "first user is the admin", promoting others, moderators —
hangs off one change:

- **`users.role`**: `admin | moderator | member`. Moderator is in the enum
  from day one, unenforced at first, so it's designed-in rather than bolted on.
- **Role-based admin auth.** `/api/admin/*` accepts *either* the admin token
  *or* a member device token whose user has `role=admin`. The admin mini-app
  then works with the session the user already has — no token pasting.
- **First claimer is admin.** The first user to claim membership on a fresh
  instance gets `role=admin`. Admins can later grant/revoke `admin` (and
  `moderator`) on other users via the admin app.

**The admin token survives as a break-glass API credential** — it's how
`add-instance` provisions, how the runbook recovers access, and it's
auth-not-decryption by design. What retires is the `/admin` *page*, once the
mini-app reaches parity. Losing the token path entirely would leave "admin lost
their only device" with no recovery.

### Moderators (the aside, captured)

Problem: on instances where members can invite (`user_invites`), an invited
member currently has the same social surface as anyone else. Roster-affecting
powers should be tiered:

| power | member | moderator | admin |
|---|---|---|---|
| invite new people (when `user_invites` on) | ✓ | ✓ | ✓ |
| remove a user from the instance | – | ✓ | ✓ |
| rename another user | – | ✓ | ✓ |
| grant/revoke moderator | – | – | ✓ |
| grant/revoke admin | – | – | ✓ |
| instance settings, branding, bots | – | – | ✓ |

Enforcement is a later phase (see *Phasing*); the schema and the admin-app UI
should assume it from the start.

## 2. The admin mini-app

A mini-app (per `web/static/apps/README.md`) that replaces the `/admin`
console. Visible only to users with `role=admin` — the gate lives in the app
framework (an app can declare `adminOnly`), not scattered through `shell.js`.

Surface (parity with today's `admin.js`, reachable in-app instead of on a
separate page): invites, roster (remove/rename, now also roles), group name,
server photo, contact email, `user_invites` toggle, bot config, test push.
Companion-view shape (Chat | Interface) fits naturally: the Interface is the
console; the Chat view is where admin-flavoured bot responses land (e.g.
`/invite` already exists as a command).

Retirement is two-step: (1) ship the app, `/admin` stays; (2) once parity is
proven in use, `/admin` becomes a redirect/pointer and the page + `admin.js`
are deleted.

## 3. Server-admin onboarding (first run)

### Entry

`lchat add-instance <host>` stops printing an `/admin#token=` link and instead
prints a one-time **setup link** — a normal invite marked `grants_admin`
(claiming it creates the membership *and* sets `role=admin`). The printed
admin token / admin link remain available (`lchat admin-link <host>`) as the
break-glass path.

Landing on the setup link does what invites do today: claim, generate the
keypair, and — already true — the first member bootstraps the **instance key**
client-side (`shell.js`, `generateKey()` when no holders exist). The admin
lands in the chat view with a conversation with Eleven already open.

### The setup script

Client-driven, keyed on: caller has `role=admin` **and** the server-side
`setup_complete` config flag is unset. Steps, each one message + captured
answer or tap-chip, each landing on an *existing* endpoint (now reachable with
role-based auth):

1. **Your name** → `postLabel` (encrypted under the instance key, as today).
2. **Group name** → `POST /api/admin/group`.
3. **Contact email** → `admin_email` in `POST /api/admin/settings` (exists).
4. **Server photo** → `POST /api/admin/server-avatar` (plaintext branding, as
   designed). Offered as a chip that opens the picker; skippable.
5. **Enable AI?** → a new instance setting (see §6). Presented honestly: on
   hosted instances it takes effect; on self-hosted it's a preference the
   sidecar respects when one exists.
6. **Can people invite other people?** → `user_invites` (exists).
7. **Who is this space for?** (#1374) — the plan question, moved here from the
   create flow so creating is never pay-gated. Web-only, and only when home's
   public `/api/pricebook` answers with tiers (native wrappers and self-hosted
   spaces never see it); a paid answer becomes a "Set up your plan" chip on
   the finish line that hands off to home's upgrade picker. The space runs
   free until that tap.
8. **The key ceremony** (next section) — deliberately near-last, so it's the
   note the setup ends on.

On completion the script sets `setup_complete` and hands over: "you can change
any of this later — I've put an **Admin** app in your sidebar."

Answers are captured the `/tutorial` way — the script asks, and either a chip
tap or the next composer submit is consumed as the answer (deterministic
"extraction"; no parsing cleverness). The conversation itself is local
notices (`buildLocalNotice`), not server messages: nothing needs to persist
except the settings each step writes.

### The key ceremony

One precision the copy must get right: what the admin must not lose is their
**credential bundle** (private key + session), not "the instance key" per se.
The instance key is re-wrappable by any other holder — but on a fresh
one-member server *they are the only holder*, so losing their keys loses the
server transitively. The script says so, sternly, in Eleven's voice: **we
cannot get this back for you, and that is the design working.**

Offered paths, in order:

1. **Primary — "Save a passkey"** (one click). The shipped phase-3a home-server
   enrolment popup: credentials into the vault blob, one Face ID. This is the
   same mechanism as the fragility banner's CTA; completing it here means the
   banner never appears for this user.
2. **Secondary — download a recovery kit.** A small file (1Password
   Emergency-Kit style) for people who won't do passkeys: origin, display
   name, the private key, and a re-auth credential. **New work + an open
   design question:** session tokens are revocable, so the kit likely wants a
   durable server-side credential (a long-lived "recovery token" whose hash
   the server stores, exchangeable once for a fresh session — same
   hash-only-storage discipline as the admin token). Needs its own short
   design pass before building.
3. **Not offered: screenshots.** Screenshots sync to cloud photo libraries in
   plaintext and are casually browsed and shared. Recommending one would
   undercut the seriousness the step is trying to convey. (A QR inside the
   recovery-kit file is possible later polish for cross-device import.)

The step is skippable — it's their server — but skipping routes into the
existing fragility banner's double-dismiss discipline rather than silence.

## 4. User onboarding (joining from an invite)

Same dance, assembled almost entirely from shipped parts:

- **Chat view first, no overlays.** The join flow's name overlay goes away;
  claiming an invite lands directly in the chat view with Eleven's welcome
  conversation open.
- **Welcome script** (client-driven, keyed on first-open-after-join):
  1. **Name** → `postLabel`.
  2. **Avatar** → existing avatar upload; chip opens the picker; skippable.
  3. **"Save your profile"** — the phase-3a enrolment popup, one click and
     redirect. This *is* the post-join nudge from `onboarding-and-home-server.md`,
     now delivered in Eleven's voice (one voice: the old backup toast is
     already slated for retirement; this replaces the banner's first
     appearance too, for joiners who complete it).
  4. **"Take the tour"** — the existing chip into `/tutorial`.
- **Sidecar stand-down.** On bot instances, sidecar-Eleven currently
  welcome-DMs new members. The client script owns onboarding; the sidecar's
  welcome DM is suppressed (or reduced to creating the DM thread the script
  runs in). Two Elevens must not greet the same person.
- **Admin-editable welcome (later).** The script reads an optional
  admin-authored welcome blob from config (written via the admin app) and
  plays it before/instead of the stock greeting. Cheap hook to leave in the
  script's structure now; UI later.

## 5. Roles vs identity: who is "the admin" in the script?

`spaceInfo()` already exposes an administrator identity to the tutorial. With
roles on the roster this stops being config-only: the roster itself knows who
the admins are (useful for "contact an admin" chips, the moderator table
above, and the admin app's role management). `admin_name`/`admin_email` in
settings remain the *outward* contact surface (they're branding-adjacent);
role is the *authorisation* surface. Keep them distinct.

## 6. The AI toggle (honest scope)

"Enable AI on this server?" is a real setting with an operator-shaped
dependency: AI is a **sidecar deployment with an API key**, not something an
instance flag can conjure. Design:

- A new instance setting (e.g. `ai_enabled`), admin-writable, readable by the
  sidecar.
- The sidecar respects it: when off, Eleven runs deterministic-only (the
  existing per-bot kind machinery); when on — and a sidecar with a key exists —
  conversational AI is active.
- Hosted instances: flipping the toggle works end-to-end (sidecars are
  provisioned). Self-hosted without a sidecar: the setting records intent and
  the script/admin app says what's missing, pointing at `add-bot` docs.

This slice gets its own small design pass before building (interaction with
per-bot config, and whether "off" also silences AI for bots other than
Eleven).

---

## Phasing (each slice independently shippable)

1. **Roles** — `users.role`, first-claimer-is-admin, role-based
   `requireAdmin` alternative, moderator in the enum (unenforced). Pure
   server + schema; no UI change.
2. **Admin mini-app** — `adminOnly` app gate + the app itself over existing
   admin endpoints. `/admin` untouched.
3. **First-run setup script** — `grants_admin` setup invite from
   `add-instance`, the Eleven setup conversation, `setup_complete` flag.
   Ends with the passkey step only (recovery kit not yet built).
4. **Key ceremony completion** — recovery-kit design pass, then the
   download path.
5. **Joiner welcome script** — name/avatar/save-profile/tour, join overlay
   removal, sidecar welcome stand-down.
6. **Moderator enforcement** — the permission table in §1 enforced
   server-side; role management UI in the admin app.
7. **AI toggle** — design pass + `ai_enabled` + sidecar respect.
8. **Retire `/admin`** — after the app proves parity in use.

## Open decisions

- **Recovery kit re-auth credential**: durable recovery token (hash-only
  server storage) vs re-using the add-device machinery with a non-expiring
  variant. (§3, key ceremony — blocks phase 4 only.)
- **Sidecar stand-down mechanism**: suppress the welcome DM entirely, or keep
  the sidecar creating the DM thread and have the script play inside it?
- **Does `grants_admin` ride on key-invites or user-invites?** Setup is a
  key-invite shape (there's no inviter to wrap thread keys), but confirm
  against the invite-redesign fragment format (`#e1.<T>`).
- **Admin-editable welcome**: plain text blob vs a tiny script format
  (chips?). Start with text.
- **Moderator table details**: can moderators cancel invites? See other
  members' invite links? Decide when enforcing (phase 6).