From bbaa844f8ce9e7184d5b5560486330adb225d253 Mon Sep 17 00:00:00 2001 From: kisfenyo Date: Sat, 18 Jul 2026 19:32:00 +0200 Subject: [PATCH] onboarding runbook --- .../runbooks/RUNBOOK-onboarding-draft-v3.md | 93 +++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 documentation/runbooks/RUNBOOK-onboarding-draft-v3.md diff --git a/documentation/runbooks/RUNBOOK-onboarding-draft-v3.md b/documentation/runbooks/RUNBOOK-onboarding-draft-v3.md new file mode 100644 index 0000000..6de6025 --- /dev/null +++ b/documentation/runbooks/RUNBOOK-onboarding-draft-v3.md @@ -0,0 +1,93 @@ +# DRAFT R-3 — Friend-alpha onboarding runbook (operator) + +> **Status: DRAFT, pre-rehearsal.** Generalized from `runbooks/RUNBOOK-rehearsal-v3.md` (S1–S8) and +> the shipped claim/escrow/self-bind flows. The N100 rehearsal EXECUTES this document; every +> `[REFINE]` slot gets filled from its friction notes, then this graduates to +> `documentation/runbooks/RUNBOOK-onboarding.md` and the rehearsal item collapses. +> Scope: **appliance hardware only** (BYO track is R-1/Peti, explicitly out of alpha scope). + +## A. Before the visit (operator, ~30 min, all remote-doable) + +1. **Hub:** create the customer (name, e-mail, domain `.felhom.eu`) — verify the CF tunnel + + zone token provisioning completes. Confirm the Day-0 manifest is current (agent, golden, + MinAgent) and the managed-update floor is at the intended release — a stale golden is fine + (the floor lifts the box post-install), a stale FLOOR is not. +2. **Hardware:** the standard appliance + its external HDD. One-time bench prep list: + memtest pass, SMART clean, BIOS queue for the single visit in B2. +3. **Install media:** the **reusable generic pairing ISO** (secret-free, slice C). Only rebuild it + when `scripts/` ships a new version — never per-customer. Flash via dd/Rufus-DD. + Loader note per firmware: mkimage requires **Secure Boot OFF** (F1); record the board model + + loader choice in the customer record. +4. **Paper:** the tester one-pager (R-11, printed or PDF), the tester agreement + (PETI-agreement sibling), and the recovery-code envelope step rehearsed in your head — the + escrow ceremony is the one moment that must not be rushed. + +## B. Install + bind (~15 min wall-clock) + +1. Boot the stick. ONE BIOS visit: boot order → USB, Secure Boot per loader, **restore-after-AC-loss + → Power On** (a power blip must never strand a household). +2. Unattended install (~3 min) → reboot → pairing mode: the console shows the Hungarian + **pairing-code banner**; the box appears under **Unclaimed appliances** at the hub + (verify uuid/MAC/SSH fingerprints match the physical box before binding — never bind a + fingerprint you didn't read off the console). +3. **Bind** to the customer. Self-bind path (customer enters the code themselves) preferred when + the customer is present — it is the flow real remote onboarding will use. `[REFINE: which path + the rehearsal used + friction]` +4. Watch the event sequence compose (expected: **seconds** between post-enroll legs — enroll → + claim-code issue → WG → fast-tick window → tunnel → PBS-DR descriptor poke → controller up → + claim e-mail lands → floor lift to current). **Any ~15-minute stall between two legs is a + finding** — capture which leg + wall-clocks. `[REFINE: reference wall-clock table from the + rehearsal]` + +## C. Customer zero script (the customer drives, operator narrates — ~30 min) + +This is the friction lens: the customer's hands on the keyboard, the operator's hands OFF. + +1. **Claim:** open the claim e-mail → claim the dashboard → set the dashboard password. + (R-4 gate: the e-mail must land in inbox, not spam — gmail proven; `[REFINE: freemail.hu + result]`.) +2. **Escrow ceremony:** run the recovery-code wizard → the awaiting card + („megerősítésre vár, legfeljebb 15 perc") → flips on ACK. The code goes on paper, into the + envelope, into the customer's drawer — **state plainly: without this code, a dead box means + the remote backup is unrecoverable; we cannot read it for them.** That sentence is the product. +3. **Storage:** enroll/format the external HDD via the wizard (customer clicks, operator explains + the destructive-confirm). +4. **First app:** deploy one app the household actually wants (paperless or immich recommended) — + through the catalog UI, no shortcuts. +5. **Sharing:** enable „Megosztás", set the household SMB password, create one share; open + `\\NÉV` from their own laptop. (Set expectations per the one-pager: device list may lag on + some routers; the address always works.) +6. **Protection proof — the customer performs a restore, unassisted** (this step IS the + capability-map evidence, per customer): drop a file on the share or into the app → „Távoli + mentés most" → wait for the snapshot → delete the file → the customer restores it via + **Visszaállítás** with the operator silent. If they can't without help, that's an R-11/UX + finding, not a customer failure — write it down verbatim. `[REFINE: rehearsal friction notes]` +7. **Alerts sanity:** show them what an alert e-mail looks like (the health-degradation mail); + confirm their address receives it. + +## D. Handover (10 min) + +- Walk the one-pager together: what it does, what it doesn't do yet, how to report. +- Reporting channel: **support@felhom.eu** (catch-all already delivers it) + the personal channel + for the friend circle. „Ha bármi furcsa: e-mail vagy üzenet, screenshot ha van." +- Sign the tester agreement. Leave the one-pager with them. +- Operator record: board model + loader, drive serials, claim date, escrow ACK timestamp, + friction notes. + +## E. Operator post-checks (same day, remote) + +1. Hub: customer row green; Offsite → Restic tab shows the first bytes within a report cycle; + PBS-DR gauge nominal (first PBS run on its own schedule — note, don't wait). +2. Floor convergence: controller at current, agent at MinAgent+. +3. Route friction notes: UX items → ROADMAP; one-pager corrections → R-11; runbook corrections → + this doc. + +## F. Standing rules + +- Never perform steps C1–C6 *for* the customer. The script's value is watching them do it. +- Never handle the recovery code — see it into the envelope, never into your hands or a photo. +- One onboarding per day maximum during alpha — the friction notes are the point, and they + degrade after the first. +- Post-rehearsal checklist item: rebuild the golden to the current controller before the FIRST + real tester (fresh boxes shouldn't sit in a stale window longer than needed), and re-verify the + Day-0 manifest after every controller release during alpha. \ No newline at end of file