UX Flow Atlas

Durable document (designated Session 310, 2026-07-05; re-scoped to the persona-by-flow matrix + strawman-authored at Session 369, 2026-07-13). One of the four canonical project documents per the Hub methodology [[10-Three-Document-Product-Canon]] (~/Documents/Claude/ Vaults/The Hub/25 Methodology/10-Three-Document-Product-Canon.md, v0.2). This is the UX Flow Atlas - it answers "what should the desired user experience be, for each kind of user?" and is the single source of truth for the *desired experience*, never for settled UI. Living copy: this file; dated, version-stamped snapshots under documents/snapshots/. Companions: As-Built Spec (as-built-spec.md - v1.0.10, current production truth), To Build Spec (next-build-spec.md - the v1.1 plan + build contract, which now owns the roadmap, LOE, and prioritization), and Design System (design-system.md - the look-and-feel basis; the desired experience in every cell below is rendered in the Crown Bees design system, not a new skin).

STATUS: DRAFT - NOT YET APPROVED (v0.2). ~60-80% complete; significant changes are still expected as Dave and Kellie's work locks. This document is not yet approved canon (unlike the As-Built and the Design System, which are canon). Versioning of the evolving thinking begins here (Session 381, 2026-07-15): DRAFT docs run the v0.x track and promote to v1.0 on approval. Still explicitly disposable reaction material (BT-102 Section 4: "we fully expect much of this to change once Dave and Kellie's updates land"). The personas and the matrix cells are drafted from current information - the shipped app, Dave's Pollination Oasis needs, and the persona-latent evidence in the product (BT-102 Section 3). Anything marked [TO BE DEFINED / APPROVED - ...] or listed in Section 5 (Open Items) is not settled. The value is in the descriptions, not the imagery; any images are illustrative and MUST NOT be treated as pixel canon (that lives in the To Build Spec).

Dave-email desired-state folded in (Session 378, 2026-07-14). Session 378 ingested Dave Hunter's recent design emails (Jun 24 - Jul 2, 2026 - the hand-built HTML phone mockups, captured in ../_capture/2026-07-dave-flows/) and folded the current desired-state into the cells below, newer superseding older: the Jul 2 value-first onboarding + Oasis Pro pricing (3.1 / 3.11), the "Your Oasis" GDD/bloom/bee overlay + explainer modals (3.3), the Bloom & Bee Plan release schedule (3.6), and a NEW Shop / commerce flow (3.12). This is captured as *desired-state*; it is not a build directive (Scott's Session 377 ruling: document the current state, build nothing until further Dave/Kellie alignment). The four-buckets-to-three-personas mapping was NOT invented (Open Item 5.2).

Dave's design-attachment detail folded in (Session 380, 2026-07-15). Dave's three email attachments were captured as Library notes and ingested to the Hub (project bt, the canonical source of record; notes under 50 Architecture Library/sources/): the 223-variety GDD crop-pollination dataset ([[2026-07-15-bt-gdd-crop-pollination-dataset]]), his Pollinator Oasis screen designs + README with a new Oasis Pro 7P-13P onboarding sub-flow ([[2026-07-15-bt-pollinator-oasis-screen-designs]]), and the REI purchase-history reference ([[2026-07-15-bt-rei-purchase-history-reference]]). Cells 3.1, 3.3, 3.11, and 3.12 cite them; the notes carry the transcribed detail and provenance (the GDD dataset is the biological engine behind the bloom-timing and bee-matching cells).

Nav is SETTLED CANON (2026-07-15). The current shipped navigation - the top nav (SiteHeader) and the 5-item Bottom Tab Bar (Home / Weather / Ask / My Yard / Advice) - is confirmed canon (Scott, with Dave and Kellie, discussed 2026-07-13); the As-Built Section 4 carries it. Dave's proposed Home / Bloom / Bees / Shop / Ask bottom bar and any menu-icon changes are tracked deltas against this baseline, not open questions. (Kellie's earlier "no hamburger" is folded into this: no hamburger; the settled pattern is the bottom tab bar above.) This nav decision is settled even though the surrounding flows in this DRAFT document are not.

Fidelity rule. Descriptions carry the value - the words, the process flows, the desired experience per persona. Wireframes and even incorrect images are acceptable here; this document does not need approved visuals and MUST NOT be blocked waiting for them.

Scott's three personas (Session 340). These are the columns of the matrix. Profiles below are strawman - validated with Scott/Dave (Open Item 5.1).

The matrix rule (BT-102). User flows down one axis (Section 3), the three personas across the other, the desired experience in each cell. Each persona MUST be evaluated against the desired experience for each flow. Below, each flow is a subsection carrying its three persona rows (the matrix, sliced per flow for readability).

The flows we have today, from the shipped app (As-Built Section 3), the Guest funnel (To Build Section 1), and Dave's Oasis roadmap. The list grows as flows are identified (BT-102 Section 6 Q2 - Scott: the named flows were examples; start from the flows we have).

1. Onboarding - the Guest funnel (Welcome -> Goals -> Region -> Results -> ... -> Choose Plan).
2. Account / upgrade - create an account (email-OTP), Guest -> Pro trial.
3. Build a garden / My Yard - plant selection, plant cards, GDD/bloom chart, add/remove.
4. Check my weather - forecast + pollen + location setup.
5. Get advice - timely species to-dos and guidance.
6. Bee management / inventory - bee cards, cocoon counts, bee advice (Oasis).
7. Diary - seasonal notes, year-over-year self-reminders.
8. Ask / help - the RepAI assistant (shipped).
9. Alerts & notifications - the alert feed + the notifications engine.
10. Reports - year-over-year success metrics, bloom/GDD history (Oasis, future).
11. Plans / subscription - Free vs Oasis Pro.
12. Shop / commerce - the in-app Crown Bees store, Recommended Items to Order, and Purchase History (Dave's Jun-Jul 2026 desired-state; new flow, Session 378).

Strawman cells. Real, differentiated content where we can reason it; [TO BE DEFINED / APPROVED] where it genuinely needs Dave's domain input or a Scott decision.

3.1 Onboarding (Guest funnel)

Current desired-state (Dave, "5 slides" Jul 2 2026 - the authoritative onboarding). "Pollinator Oasis Onboarding: 6 screens, under 60 seconds, no signup wall." Welcome -> Goals (multi-select: Support wild bees / Grow more food / Beautiful garden / I'm just learning) -> Region (with an "Explore Dave's Pollinator Oasis" demo path into a Woodinville WA sample garden) -> Results (a concrete, trusted plant list) -> Bloom & Bee Plan -> Choose Plan (3.11). Design rationale (from the Jun 26 annotated version, which the Jul 2 refines): the account prompt appears only at the first *save* (no signup wall); the screen-2 goal selection pre-selects the screen-4 chips (feels instant and personal); location is framed as the value unlock (a benefit to the bees, not a data ask); chips keep users exploring with one-tap goal switching, no back-navigation.

Oasis Pro onboarding sub-flow (Dave's screen designs, Jun 26 2026; [[2026-07-15-bt-pollinator-oasis-screen-designs]]). Tapping "Try 14 days free" on Choose Plan (3.11) opens a 7-screen Pro setup path (Screens 7P-13P): account creation (Apple / Google / email) -> trial confirmed (14-day, no credit card) -> location confirmation -> setup preview -> bee guidance level + reminder channels -> plant selection (search locked on Free) -> bee inventory (Mason / Leafcutter / Wild). Two settled decisions: plant-selection granularity - Free taps a plant *type*, Pro opens a *variety picker* (Honeycrisp vs. Fuji); and beginner language - "gentle bees," not "mason bees."

3.2 Account / upgrade (email-OTP, Guest -> Pro)

3.3 Build a garden / My Yard

Current desired-state (Dave, "Your Pollinator Oasis" overlay, Jun 26 2026). A single "at a glance" screen overlaying the garden's bloom windows, GDD accumulation, and mason-bee activity across the season (Mar-Jun), with the user's own plants and pollination needs (e.g. "2 plum, 4 apple") mapped onto the timeline. Three teach-in-context modals: "What is GDD?" (plain language - Growing Degree Days are the invisible warmth clock both plants and bees run on; "284 GDD accumulated, Woodinville WA" places you in prime bloom territory); "Pollen gap detected" (flags a window where supporting pollen sources are thin for the bees and offers "Show me what to plant" - the advice / BT-023 tie-in); and "Bee Buy Back opens Oct 1" (Crown Bees surplus-cocoon buyback, apply-early priority).

The bloom windows and GDD accumulation are backed by Dave's 223-variety crop-pollination GDD dataset ([[2026-07-15-bt-gdd-crop-pollination-dataset]]): chill-hours-then-warmth timing, GDD-to-bloom per cultivar, and per-bee suitability (mason bees match early tree-fruit bloom at ~300-500 GDD). The per-cultivar granularity is what powers the Pro variety picker (3.1 / 3.11).

3.4 Check my weather

3.5 Get advice

3.6 Bee management / inventory (Oasis)

Current desired-state (Dave, "The core" Bloom & Bee Plan, Jun 30 2026 - "the heavy lifter of the app"). Month tabs across the season with a Bloom-window / Bee-plan toggle and a mason-bee release schedule laid out as a lifecycle: Overwinter -> Release -> Extend -> Pollination -> Protect & Store -> Harvest, aligned to the bloom timeline and the user's plants. This is the surface that connects the garden's bloom timing to concrete bee actions (when to release cocoons, when to harvest).

3.7 Diary

3.8 Ask / help (RepAI - shipped)

3.9 Alerts & notifications

3.10 Reports (Oasis, future)

3.11 Plans / subscription

Current desired-state (Dave, "Choose Plan", Jul 2 2026). Two tiers: Free ($0, "always free", [Start exploring]) vs Oasis Pro ($20/yr, i.e. $1.67/mo), 14-day free trial, no credit card required. This is the content that would activate the Paywall that ships inert / unreachable today (As-Built; BT-024). It sits at the end of the onboarding funnel (3.1) - shown at the moment of demonstrated value, not before.

What Pro gates (Dave's design decisions; [[2026-07-15-bt-pollinator-oasis-screen-designs]]): Free = general info + plant *type* selection with search locked; Oasis Pro = personalized GDD-timed / ZIP-specific guidance, the *variety picker* (specific cultivars), and unlocked search.

3.12 Shop / commerce (new - Dave's Jun 2026 desired-state)

Current desired-state (Dave, Jun 24 2026). The app should emulate the Crown Bees store experience internally rather than redirecting to the external website - a store button/icon surfaces the full store *inside* the app. Two anchor surfaces:

• Recommended Items to Order. Recommendations branch by user type: experienced users get items

based on inventory count + past purchases; new users (or experienced users with no inventory) get beginner kits (a complete kit with a house, or a bare-bones kit with holes). Pollination needs are driven by garden-page data (number of trees, etc.) to recommend a quantity of mason or leafcutter cocoons (the backing database is Dave-noted as not yet built). Each item shows a short description, a quantity +/- control, price, and a priority indicator; an "i" button opens a product-detail popup with pictures. Ordering is by checkbox (set quantity to zero to remove); the page ends in "Add to Cart" (deliberately not "Order Now") -> the cart, where shipping is chosen. The page also surfaces a recommended delivery date for the bees, pulled from bloom-timing tables, and supports multiple release/delivery dates.

• Purchase History (referenced against REI's pattern;

[[2026-07-15-bt-rei-purchase-history-reference]]). Reached from the account page: a year drop-down -> an order list (date + order number) -> an order detail (items, quantity, cost, a return-information button, and tracking information). The REI reference adds the pattern elements not yet specced here: in-store vs. shipped order cards, a member reward / co-op dividend per order, print-invoice, and per-item return windows.

Note (As-Built gap): the shipped app surfaces Shop on Home as the Crown Bees store; the desired in-app store emulation, Recommended Items, and Purchase History are not built (desired-state only, per Scott's Session 377 ruling). The backing pollination-needs database is a Dave-noted prerequisite, also not yet built.

Pointers to the wireframe-fidelity renders that illustrate the desired experience. Illustrative only - pixel canon lives in the To Build Spec, produced through the visual-preview gate.

(Image durability - whether to copy these into the durable documents home - is deferred per SOP Section 12 Q2.)

1. Validate the persona profiles. The Section 1 profiles are strawman; confirm with Scott (and

Dave for the SME/Hobbyist domain shape).

1. The four-buckets-to-three-personas mapping (BT-102 Section 3/6 Q1 - MUST NOT be invented).

The shipped onboarding selector has four buckets (Just starting, A few seasons, Experienced, Expert); Scott named three personas. Strawman proposal, REQUIRES SCOTT/DAVE APPROVAL - not settled: Newbee = Just starting; Hobbyist = A few seasons + Experienced; Bee SME = Expert. Does the selector change to three, or do two buckets resolve to one persona? This is the runtime persona-assignment decision; the matrix above does not depend on it (it is built on the three named personas), but the app's assignment logic does.

1. Flow completeness. Section 2 lists the flows we have; the matrix grows as flows are

identified. Shop / commerce was added as flow 12 / cell 3.12 (Session 378, from Dave's Jun 2026 desired-state). Still open: Profile / account management and BeeBuyBack as their own flows?

1. Rep-AI posture (BT-048 vs BT-037). Cell 3.8 assumes the app curates prompts and does not host

AI (BT-037), yet BT-048 asks for an in-app live assistant. Reconcile the desired experience before either is specced.

1. Dave/Kellie incoming material. BT-102 Section 7: Units 3/4 expect Dave/Kellie updates; much of

this document is expected to change when they land. Treat as reaction material.

1. Persona-driven differentiation depth. How much should the *shipped* app actually branch by

persona (BT-013/BT-015 already encode a new-vs-experienced branch) vs present one experience? A product decision the matrix should ultimately drive.

1. Cells marked [TO BE DEFINED] (3.1 SME express lane, 3.2 SME data boundary, 3.4 SME GDD

surfacing, 3.10 Newbee reports) need Scott/Dave input.

*UX Flow Atlas v0.1 - The Bee Team Session 369 strawman; Dave-email desired-state folded in Session 378 (2026-07-14): the Jul 2 value-first onboarding + Oasis Pro pricing, the Your Oasis overlay + explainer modals, the Bloom & Bee Plan, and the new Shop / commerce flow (3.12) - captured as desired-state, not a build directive (Scott's S377 ruling), with nav / menu left unsettled per Kellie. Dave's design-attachment detail (the 223-variety GDD crop-pollination dataset, the Oasis Pro 7P-13P onboarding sub-flow, the REI purchase-history pattern) was folded in Session 380 (2026-07-15), ingested to the Hub / Library (project bt) and cited in cells 3.1 / 3.3 / 3.11 / 3.12. Re-scoped from the wireframe roadmap map to the persona-by-flow matrix of desired experience (the roadmap, LOE, and version assignment moved to the To Build Spec per SOP v0.2; the prior roadmap-containing Atlas is preserved in git history). Explicitly disposable reaction material - the descriptions carry the value, the imagery is illustrative and never pixel canon. Change history lives in git + the LMA records + the dated snapshots, never this footer.*