Status: new, draft — needs review. Stitches the individual journeys (onboarding, today-list, night-planning) into one coherent story and lists what must be settled before screens are designed.

Onboarding → Today (day 0) → evening: Night Planning → Today (day 1) → during day → evening: Night Planning → …

flowchart LR
  Onboard["Onboarding<br/>first task, habit, Anchor"] --> Day0["Today, day 0"]
  Day0 --> Night["Evening: Night Planning"]
  Night --> Day1["Today, tomorrow"]
  Day1 --> Live["During the day<br/>tick, log, attend, focus"]
  Live --> Night
  Night -.->|skip tonight| Morning["Morning card<br/>two minutes to pick?"]
  Morning --> Live

The app is a daily rhythm: plan at night, live from one list by day. Everything else (Habits, Wellbeing, Settings) supports that loop.

Jamaal is both the app and its companion voice — calm, supportive, non-judgmental. It nudges gently, notices patterns, and stays out of the way otherwise. Technically: the rules engine emits typed signals and a message-template layer phrases them (see rules-engine.md), so the voice is consistent and testable. It appears as inline cards (Today guidance, overload warnings, "this one keeps slipping"), empty states, and notifications — never as a chat interface. There is no punitive tone: no red severity colours, misses are recorded honestly but framed gently.

1. Onboarding (onboarding.md): meet Jamaal → the idea → iCloud check → baseline capacity → notifications + evening time → first Task → first Habit → first Anchor (skippable) → ready.
2. Today opens with something in every section, the capacity slider set, and a card: "Tonight, we'll plan tomorrow."
3. During the first day the user completes, defers or ignores things. Nothing is punished.

Triggered by the evening notification the user set up in onboarding (or the in-app banner if they declined notifications, or by opening it from Today).

• Review today is light: there's little history. The first DayPlan starts the seven-day "gathering data" clock for Wellbeing.
• Carry forward — Keep/Later/Drop for anything incomplete; passed through if nothing is.
• Build tomorrow — the step with the most value on day one: it opens on tomorrow's fixed commitments and named free gaps (generated the moment the AnchorRule was created), then the user picks tasks and habits.
• Check the load — first time the user sees load states and the suggested level, introduced gently.
• Close the day — "Tomorrow is ready." and "Good night". Skip tonight is available throughout.

• Morning: optional morning nudge. Today shows the confirmed plan filtered by capacity. Tasks are ordered by the hidden Eisenhower lens; the user never sees quadrants.
• During the day: tick tasks, tap Anchors attended (or "Not today"), complete habit windows (counted habits use a stepper), defer what won't fit. One guidance card at most. Window-closing reminders as habit windows close.
• Evening: Night Planning again. The review now has real material and the wellbeing sparkline starts filling in.
• If the user skips planning: nothing is lost — incomplete dated tasks auto-defer at rollover and the 3rd-deferral date picker still catches chronic slippage.

Tab bar (floating pill): Today · Habits · Wellbeing · Settings

Night Planning is a full-screen modal launched from Today (or a notification). Onboarding runs once, before the tabs.

One design language, same four destinations, layout adapted to width:

Mac additionally gets menu-bar commands and keyboard shortcuts (new task, open Night Planning). Design the compact layout first, then the regular-width variants of Today, task detail and Night Planning; the rest stretch.

Source: Apple's HIG page Designing for iPhone Duo (new, September 2026). The device has an outer display (used closed) and an inner display (used open) joined by a hinge, in many poses (partly folded, standing, flat). Apple's guidance is not to design per pose: a compact-width layout for the outer display and a regular-width layout for the inner display cover every pose, and the app should resize rather than be reinvented. So the regular-width layouts above are also the Duo inner-display layouts.

What this means for Jamaal:

1. Use the system tab bar and toolbars, never a custom floating bar. The system moves them to the side on Duo automatically. The "floating pill tab bar" in the design direction must be the system Liquid Glass tab bar, not a hand-built one. Give every toolbar item both a title and a symbol, keep text-only buttons rare, and set visibility priority so Add task stays visible longest, then the Night Planning entry.
2. Today is a split view. Inner display: Today list and task detail side by side; outer display: one pane at a time (list, push to detail). Build with a navigation split view so it adapts to the fold. This replaces the earlier "trailing inspector" idea wherever the two would differ.
3. Same functions and state on both displays. Open or close the device mid-task and nothing resets. Night Planning's persisted session already supports this; selection, filters and the open sheet should survive too.
4. Night Planning is task-oriented: prefer keeping its toolbar over a tab bar when space is tight. Back or Close sits first on the vertical axis, then the prominent action (Next, Close the day). On the inner display the Plan tomorrow step can show candidate tasks and tomorrow's plan side by side, collapsing to one pane on the outer display.
5. Custom components must not assume a width. Capacity slider, completion ring, heatmap, sparkline and the wizard must resize and stay clear of the fold (reserved regions). For the heatmap grid, prefer an even number of columns so it divides cleanly (e.g. weeks as columns, in even counts).
6. Small adjustments when folding, not rearrangement. Sheets, alerts and menus move for the fold automatically; don't move key controls dramatically.
7. Right-to-left: side controls stay on the same side in RTL languages, which suits an Arabic-name app with Islamic-practice presets.
8. Any size: Split View multitasking means the app can appear at many sizes; use layout margins and safe areas, never fixed widths.

API and OS availability. The Duo-specific SwiftUI APIs (ArrangementView, ReservedRegion) are marked iOS 27.1 and beta at the time of writing, while the app's minimum is iOS 26. Standard system components adapt on their own; anything Duo-specific is gated behind an availability check, so the deployment target is unaffected. Preview and test with Device Hub in Xcode.

Pricing (CLAUDE.md): free download, 14-day full-access trial, then subscription only ($2.99/mo or $24.99/yr).

• Trial: app-managed. It starts at first launch with no payment up front and no card. Onboarding's final screen mentions it in one calm line ("14 days, everything included").
• Trial start date is StoreKit's original-download date (AppTransaction) when it can be reached, else the synced firstLaunchAt. The download date wins because the synced one could have been set early by a TestFlight build (#310); reinstalls and second devices never restart the trial either way.
• During the trial: nothing changes. Settings has a trial-status row ("9 days left"). Reminders about the end are gentle and infrequent (e.g. days 12 and 14).
• Day 15 — paywall: a calm full-screen paywall on next open. Monthly and yearly options, restore purchases, and a plain "Not now".
• Not subscribed → read-only: Today, habits, wellbeing and history stay fully viewable, and living the day still works (complete a task, log a habit, mark an Anchor, run a focus timer) so the day isn't held hostage. Locked: shaping the plan — creating or editing tasks, habits, anchors and categories, manual Defer and Drop, Night Planning, and changing capacity. A locked control stays visible and opens a calm sheet. The full per-action table is in the rules engine. Data export always works. A slim banner explains and offers to subscribe.
• Notifications around the trial are deliberately few and quiet. Proposal for the design pass: a short reminder on day 12 and day 14, and one on day 15; nothing after that (the in-app banner carries it from then on). No badge counts, no repeats, gentle wording, and they respect Focus modes. The evening Night Planning notification stops once the trial ends unsubscribed, and returns on subscribing. If notification permission is denied, the in-app banner covers everything.
• Subscribing lifts everything immediately; nothing is lost either way.

The authoritative screen and flow list is now the Screens and flows register (stable IDs, entry points, variants, what Design has drawn, phase). The inventory below is the earlier working list; where they differ, the register wins.

Legacy mockups are in mockups/legacy/ — layout/flow reference only; they predate ThreadsKit's cool palette.

Resolved in this reconciliation:

• Capacity model — two measures: an energy budget (low/medium/high, the user's call; minutes from a normal-day length; counts tasks only) and free time (working day minus fixed Anchors that cut it and flexible Anchors/habit minutes that subtract); a plan must fit both; meter headline is budget used with a quiet fit flag; soft day-end at a user-set time (default 19:00), midnight stays the hard rollover
• Night Planning shape — the design's five steps (Review today → Carry forward → Build tomorrow → Check the load → Close the day); no Reflect step or mood line (no self-reporting); Build tomorrow opens on tomorrow's fixed commitments with named free gaps (tasks not placed into gaps); Skip tonight with one quiet morning card and no guilt
• Night Planning session — persisted (CloudKit resume)
• Rollover vs. deferral — unified as deferral with auto-defer safety net
• Learning the normal day — suggest only: the app proposes a normal-day length from the last four weeks of actual focus time and never changes it by itself; weekday default levels (weekends low) live in UserSettings
• Day boundary — user-set rollover (default midnight), logical dates, floating calendar dates (noon UTC), lazy idempotent catch-up, one deferral per task per logical day, session close at the boundary instant
• Eisenhower — hidden, derived, drives order / capacity visibility / suggestions
• Categories — editable list, label + filter only
• Importance rules — three levels (low default, medium, high), set in Night Planning; medium/high require a date and never Someday; 3rd deferral eases to low; prompt when a plan has 5+ tasks and fewer than two medium/high
• Notification permission — asked in onboarding, with an in-app fallback
• Habit vs. Anchor boundary — salah is an Anchor; groups hold Habits only
• Anchor positioning — recurring rules (instances generated) plus one-offs; skipped status; named "Anchors" in the UI; rules managed in the Habits tab's Anchors segment
• Ritual features adopted into Anchors — interval-from-last-done (afterLast), exceptions ranges, delegated status, derived window states with attended logged only while open; "ritual" label retired, prayers stay an opt-in preset, HabitGroup kept
• AnchorRule config shapes — two families (computed prayer times; a shared scheduled recurrence + slots shape for school run, bin night, plant watering and custom); coarse device location for prayer times; Isha closes at Islamic midnight by default; Today shows a grouped row per rule with several Anchors a day; instances keyed by (rule, occurrenceDate, slotKey)
• Pricing / platforms / bundle ID — repo (CLAUDE.md) wins over v2
• Trial and subscription — app-managed 14-day trial, then read-only with a calm paywall
• iPad, Mac and iPhone Duo — adaptive layout: system tab bar/sidebar, split-view Today, Duo handled by compact (outer) and regular (inner) layouts
• Recurring tasks — simple repeat on Task, one live instance per series
• Habit kinds — binary, counted, timed (minutes; reuses the timer) and avoid (inverted logging; proposal, needs a design pass); pause with a reason; grouped sets stay HabitGroup; detected habits are v1.1
• Timer — focus sessions adopted from the design: ambient chip on every tab (Live Activity v1.1), count-up overrun with no nudge, explicit pause only, one timer at a time with a settle sheet, abandon logs partial time, auto-close at the day rollover; notes "smaller yes" (checklist in session, timestamped lines on finish/defer)

Settled by the journey walkthroughs (all eleven walked; see the gap log):

• Onboarding: only notifications (OB-05) and the Anchor step (OB-08) are skippable
• Anchor extras: reminders (per rule; prayer times remind at the start by default) and late correction of a closed window
• Category colours: five label tokens, ThreadsKit 1.2.0, hues to confirm against Design; habit heatmap colours come from Design's d1–d3 (threadskit-usage)
• Wellbeing score composition: tasks 35 / Anchors 25 / habits 20 / load 20, no self-reporting
• Backlog and manual ordering on Today: no backlog screen and no manual ordering in v1 (a hypothesis to validate)
• "Tonight vs. tomorrow" at odd hours: the day boundary and the planning target rule

Still open:

• Fonts: Fraunces + Hanken Grotesk + JetBrains Mono (as Design draws them); bundling and licences still to confirm in ThreadsKit
• The owner's open items are collected in the gap log

Not covered anywhere in the docs yet (checked by search). Grouped by what they would change.

Would change screens or journeys

• Trial and paywall. Resolved — see "Trial and subscription". Decided: the evening Night Planning notification stops when the trial ends unsubscribed (planning is locked), and trial-end reminders are notifications, kept non-intrusive (see "Trial and subscription").
• Adaptive layout. Resolved — see "Adaptive layout" and "iPhone Duo". Still to design: the regular-width variants (which double as Duo inner-display layouts) and a check of each screen at the outer display's compact size.
• Recurring tasks. Resolved — simple repeat on Task, see task.md.
• Calendar and other apps. Decided: out of v1 (one-off Anchors cover fixed-time events). The stated goal is to stop bouncing between reminder, task and calendar apps, but nothing says whether Jamaal reads calendar events, imports Reminders, or ignores them.
• Habit pause. Resolved — pause with a reason (travel, illness, cycle, other); paused days are unscheduled, not missed. See habit.md.
• Quick capture and system surfaces. Decided (revised 8 Oct 2026, ADR 0003): widgets are in v1 (Next Anchor and Today, on iPhone, iPad and Mac, with Lock Screen accessory widgets), which puts the store in an App Group from the first sync-enabled build. Still v1.1: App Intents and interactive widgets, Control Center controls, the share extension, quick capture, Live Activity, and a companion watchOS app. See Widgets and the watch.
• Privacy, export and account. Resolved — ST-08 (privacy statement, JSON export, delete my data). v2 called the app "privacy-first"; there is no data export/delete or privacy journey (also needed for App Store submission).

Would change the schema or engine

• CloudKit duplicates. Resolved — dedup keys in the schema overview. CloudKit forbids unique constraints, so two devices can each create the same thing: the three default categories on first launch, generated Anchor instances, a DayPlan per date, the automatic day-rollover deferral (double-incrementing deferralCount). The engine must be idempotent, with a dedup strategy, before implementation.
• ~~CloudKit schema is effectively append-only once deployed to production. Every field name in these docs should be considered final before the first production schema deploy.
• Editing rules. Resolved for Anchors (pending instances update in place, attended/missed/skipped are never rewritten — see rules-engine.md, module 3). Categories: an archived category's tasks keep and show their label and nothing in history changes; habit groups never delete their habits.
• Anchor reminders. Resolved (Journey 4, G-30). Module 6 mentions during-day guidance for upcoming anchors, but there's no per-rule lead time or reminder setting.
• Day boundary. Resolved — the app's day rolls over at a user-set time (default midnight); lazy, idempotent catch-up; at most one deferral per task per day; Night Planning targets the first date whose working-day start is still in the future. See The day boundary.

Quality and reach

• Accessibility. Beyond a "larger text" preference in v2, nothing on Dynamic Type, VoiceOver for the custom components (capacity slider, completion ring, heatmap), or colour-only states — the heatmap and load states must not rely on colour alone, and ThreadsKit's palette is small.
• Localisation. No RTL layout, Arabic strings, or Hijri-date handling, though Islamic practice presets are a stated use case and the name is Arabic.
• Roadmap docs. docs/roadmap/phases.md, docs/architecture/overview.md and docs/Home.md are empty, with the phase 2 pace checkpoint due end of October 2026.