Status: reconciled with master summary v2 — draft, needs review. Merges v2's five-screen intro (meet Jamaal, concept, capacity, notifications, ready) with the repo's guided creation of one example of each primitive.

Walks a new user through setting up the app and creating one example of each primitive, so all three are demonstrated (and something is on Today) before first real use. It also sets up the evening Night Planning reminder so the first planning session actually happens (see app-flow.md).

flowchart TD
  A["1. Meet Jamaal"] --> B["2. The idea<br/>Tasks, Habits, Anchors"]
  B --> C["3. iCloud check<br/>silent when all is well"]
  C --> D["4. Your normal day<br/>sets the medium level"]
  D --> E["5. Notifications and the<br/>evening planning time"]
  E --> F["6. Your first Task<br/>due today"]
  F --> G["7. Your first Habit<br/>a preset, or something else"]
  G --> H["8. Your first Anchor"]
  H --> I["9. Ready<br/>land on Today"]
  H -.->|Not now| I
  C -.->|signed out or offline| N["A plain note:<br/>works without iCloud"]
  N --> D

OB-02

OB-03

OB-04

OB-05

OB-06

OB-07

OB-08

OB-09

The steps in detail:

1. Meet Jamaal — the companion introduces itself: calm, supportive, non-judgmental. Tagline: "One list. Just today. Beautifully ordered."
2. The idea — one list for everything; three ways of tracking: things you do (Tasks), things you cultivate (Habits), things your life moves around (Anchors). A general productivity app — Islamic practices are presets, not a mode.
3. Account readiness — CloudKit / iCloud check. Silent when signed in and nothing is wrong; a plain explanation if iCloud is signed out, restricted or offline ("Jamaal works without iCloud; your data just won't sync until you sign in."). On a fresh install the step first waits briefly ("Checking iCloud…") for data to sync: if the account already has a UserSettings.onboardingCompletedAt, this is a second device, so the user sees a short Welcome back and skips the rest of onboarding.
4. Your normal day — "How much is a normal day?": focused work outside meetings and life admin (30 min–6 h, default 3 h; a rough guess is fine). This sets the medium level. Then "When does your working day usually end?" (default 19:00; most people pick 19:00–20:00). Then introduce the capacity slider (low/medium/high) and set an initial value, so it isn't unset on first Today view. Stored in the synced UserSettings (rules-engine.md).
5. Notifications & evening planning time — request notification permission, framed around the evening planning reminder, with a time picker (default 20:00) and the optional morning list time (default 08:00). Both times are synced; whether this device sends reminders is a local switch (on by default for iPhone, off for iPad and Mac). Skippable: if skipped or denied, the in-app planning banner takes over (see today-list.md).
6. Your first Task — "Something you need to do today." The task is created due today (Today or Tomorrow are the only choices), so Today is never empty on first use. The user may pick a category (the three defaults are introduced here) and an effort.
7. Your first Habit — the four presets in the habit catalogue (Qur'an reading, dhikr, exercise, running) or Something else (a binary daily habit with just a title); creates the Habit plus its first HabitTimeWindow. The other habit kinds are created later from the Habits tab.
8. Your first Anchor — the user picks a type — prayer times, school run, bin night, plant watering or custom — and fills its short form, creating an AnchorRule that generates the first Anchor instance(s). Users who don't have any of these can choose "Not now" — Today's Anchors section then explains what Anchors are and offers to add one (see open questions). The forms (shapes in anchor.md):
   • Prayer times — asks for when-in-use location only now, in context (never earlier), and falls back to searching for a city if the user declines. Then: calculation method (suggested from the region), madhab (standard or Hanafi), which prayers to include, and whether Isha closes at Islamic midnight (default) or Fajr. Advanced (collapsed): per-prayer minute adjustments and the high-latitude rule.
   • School run, bin night, plant watering, custom — one shared form: days (or "every N days / every N weeks" with a start date, or "N–M days after I last did it" for things like plants), one or more named time slots with an open window (or all day), and how long it takes. Each type opens with its own preset filled in and editable; custom opens blank with one empty slot. Exceptions (term breaks, holidays, travel, illness) are added later from the rule's edit screen, not during onboarding.
9. Ready — sets UserSettings.onboardingCompletedAt, then land on Today with a Task, a Habit and (usually) an Anchor present, plus a card: "Tonight, we'll plan tomorrow."

• Skippable steps: proposal — steps 1–4 and 6–7 are required; step 5 (notifications) and step 8 (Anchor) can be skipped, since a non-Muslim user with no school run shouldn't be forced to invent an Anchor. Needs confirmation; it trades "all three primitives demonstrated" for honesty.
• Anchor setup follows the settled positioning (ADR 0001): onboarding step 8 creates a recurring commitment (an AnchorRule). One-off Anchors aren't part of onboarding; they're introduced from Today's add button.
• Prayer setup length: method, madhab, prayers, Isha end and location is a lot for one onboarding step. Proposal: the visible form is location + method (with a region-based default) and a "Customise" disclosure for the rest.
• Sample content: whether steps 6–8 pre-fill sample values the user can edit, or start blank with placeholders.