# UX Flow Atlas - Pollinator Oasis (Crown Bees Pollination App)

> **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: STRAWMAN (v0.1), Session 369.** 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).

**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.

---

## Section 1 - The three personas

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).

| Persona | Who they are | What they want | Evidence / anchor |
|---|---|---|---|
| **The Newbee** | New to mason bees and/or pollinator gardening. Little prior knowledge; may have just bought a bee house or nothing yet. | Value-first proof, low friction, plain language, defaults chosen for them, encouragement. "Just tell me what to plant and when." High drop-off risk - the funnel must earn trust fast. | The shipped onboarding `Just starting` default; the build spec's "new gardener primary persona" (BT-102 Section 3); Kellie's "New to App?" Dave-intro-video ask (BT-013). |
| **The Hobbyist** | A few seasons in. Has a garden and probably a bee house; some working knowledge. | To optimize and track - GDD/bloom timing, diary, year-over-year improvement, add plants and bees, moderate control. Will pay for Oasis Pro if it demonstrably improves outcomes. | The shipped `A few seasons` / `Experienced` buckets; the live My Yard chart + diary + advice the app already ships. |
| **The Bee SME** | Expert. Deep mason / leafcutter / wild-bee knowledge; possibly a Crown Bees advocate or heavy customer. | Power, data, and control with minimal hand-holding - year-over-year analytics, cocoon counts, success metrics, reports, BeeBuyBack. Values accuracy and depth; impatient with over-simplification. | The shipped `Expert` bucket; Dave's Oasis power features (cocoon counter BT-038, reports BT-040, BeeBuyBack BT-049). |

**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).

---

## Section 2 - The user flows (the rows)

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.

---

## Section 3 - The matrix (desired experience per persona, per flow)

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)

| Persona | Desired experience |
|---|---|
| **The Newbee** | The primary target. See real personalized value in under 60 seconds with zero signup wall. Plain-language goals ("Support wild bees / Grow more food / Beautiful garden / I'm just learning"), a location, then a concrete plant list they trust. An optional Dave-intro-video entry ("New to App?", BT-013) reassures. No jargon; defaults pre-chosen. |
| **The Hobbyist** | Value-first still, but wants to feel the depth quickly - the Blooms/Bees toggle, bloom windows, bee-release timing. Willing to give more input (region precision, existing plants) for a better plan. Skims the hand-holding. |
| **The Bee SME** | Impatient with onboarding; wants a fast path to the powerful surfaces and to skip or compress the guided funnel. Values accuracy of the plant/timing data over encouragement. `[TO BE DEFINED - APPROVED: does the SME get a "skip to full app" express lane?]` |

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

| Persona | Desired experience |
|---|---|
| **The Newbee** | Asked for an account only at the moment of commitment (first save or trial start), not before. Email-OTP is the settled low-friction mechanism (no password). Clear "why now" framing. |
| **The Hobbyist** | Understands the trade; wants the trial to unlock the tracking depth (diary, year-over-year). Frictionless upgrade from an existing Guest session (guest-upgrade preserves their work). |
| **The Bee SME** | Likely converts fast if the power features are real. Expects the account to persist serious data. `[TO BE DEFINED - the exact guest->account data-carry-over boundary; see To Build 7.10]` |

### 3.3 Build a garden / My Yard

| Persona | Desired experience |
|---|---|
| **The Newbee** | "What's in your garden?" with an easy picker; the app recommends and explains. The My Yard GO/WAIT/HOLD release decision + seasonal chart tells them *what to do now* in plain terms. |
| **The Hobbyist** | Adds/removes plants freely, reads the GDD/bloom chart, tracks the yard over the season. Wants the chart to reflect their real plants and refresh cleanly (shipped: cache-invalidation fix v1.0.2). |
| **The Bee SME** | Wants quantities, precision, and the full plant/bee data model; power add/remove; year-over-year plant history (Oasis reports). |

### 3.4 Check my weather

| Persona | Desired experience |
|---|---|
| **The Newbee** | Simple forecast + pollen + a clear "is it a good day?" read. Location set once, easily. (Shipped: the v1.0.10 disabled-button visual makes the setup form honest.) |
| **The Hobbyist** | Forecast-day pollen (shipped v1.0.6) + the bloom/GDD context to plan garden tasks around the weather. |
| **The Bee SME** | Wants the underlying data reliability and detail; GDD as a first-class readout (shipped in the Yard). `[TO BE DEFINED - does the SME want raw GDD/history surfaced here?]` |

### 3.5 Get advice

| Persona | Desired experience |
|---|---|
| **The Newbee** | Timely, specific, few, plain to-dos ("do this now") off the trigger variables - not a firehose. |
| **The Hobbyist** | Species-specific mason-bee advice (BT-032) tied to their GDD/bloom + diary; a bit more depth. |
| **The Bee SME** | Full multi-species advice (mason / leafcutter / wild - BT-032/033/034), date-and-observation-driven, with the reasoning exposed. Extends to beneficials beyond bees (BT-017, Kellie's ask). |

### 3.6 Bee management / inventory (Oasis)

| Persona | Desired experience |
|---|---|
| **The Newbee** | Simplified inventory - "do you have a bee house?" + a short check-off; gentle. Most of this is post-trial. |
| **The Hobbyist** | Full inventory (bees, nesting material, tools), bee cards, add/remove, per-species tabs; connect Crown Bees order history. |
| **The Bee SME** | The rich bee-management surface: bloom curves, year-over-year accordions, **cocoon counter at scale** (thousands, per Scott's q4 answer superseding BT-038's handful assumption), BeeBuyBack priority (BT-049). |

### 3.7 Diary

| Persona | Desired experience |
|---|---|
| **The Newbee** | Optional, prompted lightly; "jot what you saw." Low pressure. |
| **The Hobbyist** | Seasonal notes with the ~2-weeks-before-anniversary self-reminders (BT-036); feeds advice. |
| **The Bee SME** | A rigorous observation log driving wild-bee reminders (+3wk/+6wk, BT-034) and feeding reports; year-over-year retention (BT-039). |

### 3.8 Ask / help (RepAI - shipped)

| Persona | Desired experience |
|---|---|
| **The Newbee** | The center "Ask" FAB is a safety net - ask anything in plain language; the AI BeeBot answers. Most valuable to this persona. |
| **The Hobbyist** | Quick answers to specific situational questions without leaving the app. |
| **The Bee SME** | May prefer the curated "What's this?" prompt/catalog paths (BT-037) and their own tools; the app curates, does not host, the AI (BT-037 posture - reconcile with BT-048, Open Item 5.4). |

### 3.9 Alerts & notifications

| Persona | Desired experience |
|---|---|
| **The Newbee** | Few, high-value, plain nudges ("release your bees this week"). Not overwhelming. (Note: Notifications is orphaned today - As-Built Section 3; the funnel wires its entry.) |
| **The Hobbyist** | Timely reminders off the trigger substrate (BT-031) tuned to their plants/bees; a choosable channel (Push / Email / SMS). |
| **The Bee SME** | Full, tunable reminder set across species with fixed Crown Bees harvest dates; minimal noise, maximal signal. |

### 3.10 Reports (Oasis, future)

| Persona | Desired experience |
|---|---|
| **The Newbee** | `[TO BE DEFINED - likely minimal; a simple "how did I do?" summary]` |
| **The Hobbyist** | Plant blooming history + basic success metrics year-over-year (BT-040). |
| **The Bee SME** | The full report suite: success metrics year-over-year (e.g. September apple counts across years), mason-bee success + pest counts, historical GDD series (BT-040) - the retained-data payoff (BT-039). |

### 3.11 Plans / subscription

| Persona | Desired experience |
|---|---|
| **The Newbee** | A clear, honest Free vs Oasis Pro ($20/yr) matrix at the moment of value; "Try 14 days free." Not pushed too early. |
| **The Hobbyist** | Sees the tracking/depth features gated behind Pro and understands the value; the likeliest converter. |
| **The Bee SME** | Converts for the power features (reports, analytics, BeeBuyBack priority); expects the Pro tier to be genuinely powerful. |

---

## Section 4 - Illustrative design assets (not pixel canon)

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.

| Asset | Path | Illustrates |
|---|---|---|
| Dave Jul 2 governing renders | `../outputs/s305/img/canon/dave-05-all-screens.png` | The whole funnel + Oasis surfaces |
| Clean Guest-flow render | `../outputs/s305/img/canon/dave-02-onboarding.png` | Onboarding (3.1) |
| Oasis preview render | `../outputs/s305/img/canon/dave-01-oasis-preview.png` | Your Oasis preview / Plans (3.11) |
| Experience selector render | `../outputs/s305/img/canon/zip-onboarding-experience-selector.png` | The four-bucket experience selector (Open Item 5.2) |
| Dave/Kellie change catalog | `next-release-dave-kellie-changes.md` (BT-053) | The asks that shape the desired experience |

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

---

## Section 5 - Open Items / Questions

1. **Validate the persona profiles.** The Section 1 profiles are strawman; confirm with Scott (and
   Dave for the SME/Hobbyist domain shape).
2. **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.
3. **Flow completeness.** Section 2 lists the flows we have; the matrix grows as flows are
   identified. Are any flows missing (e.g. Profile/account management, Shop/commerce, BeeBuyBack as
   its own flow)?
4. **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.
5. **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.
6. **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.
7. **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. 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.*