Extend onboarding into a wizard (#163) (#169)

Reviewed-on: https://codeberg.org/jlmakiola/calendula/pulls/169

docs/ARCHITECTURE.md

@@ -27,7 +27,7 @@ the package list (recurring writes, save conflicts, reminder delivery).
 ```mermaid
 flowchart TD
     subgraph UI ["ui/ — Compose screens + ViewModels"]
-        Screens["Month / Week / Day\nDetail / Edit / Settings\nPermission + Reminder onboarding"]
+        Screens["Month / Week / Day\nDetail / Edit / Settings\nOnboarding wizard"]
     end
     subgraph Data ["data/"]
         Repo["CalendarRepository\n(interface + impl, Flow-based, io-dispatched)"]
@@ -78,8 +78,8 @@ flowchart TD
 ## Navigation
 
 There is no navigation library. `MainActivity` hosts `RootScreen`, which
-gates on the calendar permission and the one-time reminder onboarding, then
-shows `CalendarHost`. `CalendarHost` holds the active view (month/week/day)
+gates on the first-launch wizard (`ui/onboarding/`), then shows
+`CalendarHost`. `CalendarHost` holds the active view (month/week/day)
 plus overlay state for detail, edit, and settings — full-screen overlays
 driven by `AnimatedVisibility` with a *held-key* pattern: the last shown
 key stays alive through the slide-out so content never flashes empty.
@@ -87,6 +87,32 @@ A tapped reminder notification routes through `MainActivity` (`singleTop` +
 `onNewIntent`) as an external detail key that `CalendarHost` consumes
 exactly like an event tap.
 
+### First-launch wizard
+
+`ui/onboarding/` is a plan, not a navigation graph: `onboardingPlan()` is a
+pure function of the stored answers that returns the whole flow *plus* the
+step it is on, and `RootScreen` renders that step. Two rules make it work:
+
+- The plan keeps **completed** steps, so finishing one never renumbers the
+  counter under the user, and stepping *back* is just clearing the previous
+  step's answer — there is no separate back stack. The calendar grant is the
+  one step with nothing to return to, so back stops there.
+- The optional steps (backup, view) only exist for an install still on its
+  first run — `armOnboardingWizard()` arms on any launch holding the calendar
+  permission but refuses if the reminder step was already answered, and the
+  closing screen clears the flag again, so revoking and re-granting the
+  permission later never re-onboards anyone.
+
+Whether the backup step applies (nothing writable is synced anywhere) cannot
+be known before the grant, so it is assumed until the calendar list can be
+read: the flow may shrink after the grant, never sprout a step the counter
+had not accounted for.
+
+The flow closes on an "all set" screen, and the one-time calendar-visibility
+notice (#75) is a step in front of it rather than a dialog over the app — it
+is the only optional step an *already onboarded* install can be given, which
+is why it alone is not gated on the wizard being armed.
+
 ## Recurring writes
 
 The provider's invariants drive the design (learned the hard way, verified