# The Bee Team - Pollinator Oasis Product Canon (full corpus)

> The four canonical documents for Pollinator Oasis, the Crown Bees pollination app built by The Bee Team (Dave Hunter + Scott Sands): what is live today, what we build next, the desired experience by persona and flow, and the design language it is all built in.

All four canon documents concatenated in reading order. The markdown is the single source of truth; this file is a generated convenience for loading the whole canon in one fetch. Per-document canonical URLs are listed at https://bt-canon.pages.dev/llms.txt.

---

<!-- canon: As-Built Spec v1.0.11 (Live . canon) - source: https://bt-canon.pages.dev/as-built-spec.md -->

# As-Built Spec - Pollinator Oasis (Crown Bees Pollination App)

> **Durable document** (designated Session 310). One of the four canonical project documents per
> the Hub methodology **[[10-Three-Document-Product-Canon]]**. This is the **As-Built**: it answers
> **"what is live right now?"** Its companions are the **UX Flow Atlas** (`ux-flow-atlas.md` - the
> experience we want), the **To Build Spec** (`next-build-spec.md` - what we build next), and the
> **Design System** (`design-system.md` - the look and feel).
>
> **Version v1.0.11.** Live coordinates: server `btt-server` **v61**, iPhone app **TestFlight build
> 24** running over-the-air update `3c52b3f5`, code at `ac5969c`. Living copy: this file; dated
> snapshots under `documents/snapshots/`.

**What this document is.** A plain description of the app as it actually exists today, written for
anyone on the team. Everything here has been checked against the running code, so it is the place to
start before anything else - including the change history.

**What it is not.** It is not a plan. Nothing here is aspirational: if it is written below, it
shipped. What we intend to build next lives in the To Build Spec, and the experience we are aiming
for lives in the UX Flow Atlas.

**How to read it.** Sections 1 to 5 are the app in plain language. The two appendices are for
engineers: Appendix A is the release history, and Appendix B maps each screen and route to its code.

**How this document is kept true.** It is checked against the running code - the expo-router route
tree, `apps/server/src/lib/email.ts`, and the shipped navigation components - not reconstructed from
memory or the commit history. Where this document and the git log disagree, this document is right.

---

## Section 1 - What Pollinator Oasis is today

Pollinator Oasis is a live iPhone app. It helps someone with a mason bee yard answer the question
that matters most to them each morning: **is today a good day to release my bees?**

The app answers that by pulling together the things that drive the decision. It watches the weather
where the yard actually is, tracks which plants are in bloom and how close they are to blooming,
follows the pollen in the air, and turns all of it into a single clear recommendation - **go, wait,
or hold**. Around that decision sit the supporting pieces: a five-day forecast, a seasonal bloom
chart for the yard, a to-do list of what each bee species needs right now, and a way to ask
questions.

The app is real and running. People sign in with their own email address, their own yard, and their
own data. It is distributed through Apple TestFlight rather than the public App Store, so today it
reaches invited testers rather than the general public.

**Where it runs.**

| | |
|---|---|
| **Version** | v1.0.11 |
| **Server** | Fly.io app `btt-server`, version **v61** |
| **iPhone app** | TestFlight **build 24** |
| **Over-the-air update** | group `3c52b3f5`, published 21 July - the JavaScript that build 24 actually runs |
| **Code** | `~/projects/the-bee-team/`, `main` at `ac5969c` |
| **Host** | `app.mybeecloud.com` |

**Two coordinates, not one.** From v1.0.11 the app on a phone is a **native build** plus an
**over-the-air update** layered on top of it, and they can come from different commits. Build 24 was
compiled from `69ed4b5`; the JavaScript it runs today came from `ac5969c` and arrived without an App
Store round-trip. When asking "what is live", both numbers matter.

The app reached its **v1.0 milestone on 5 July 2026**, when sign-in was wired into the interface
and the whole thing worked end to end for the first time. Everything since has been repair and
refinement rather than new territory. The ten releases behind that number are listed in Appendix A.

---

## Section 2 - How people sign in

**Signing in works by email.** Someone types in their email address, we send them a short code, and
they type it back. There is no password to forget. Behind the scenes Supabase issues the code and
Resend delivers the mail, but a person just sees an email arrive.

There is also a **Guest** button for anyone who wants to look around before committing. It opens a
real, working session with no email at all.

**One correction worth stating plainly.** Signing in through a Crown Bees Shopify account was built
far enough that the code is still in the repository, but **it never shipped and was never switched
on**. Anyone reading the commit history could reasonably conclude otherwise. They would be wrong.
Email is the only way in. This document, not the git log, is the record of what is true.

The emails arrive from **"Pollinator Oasis"**, the app's own name, even though the app currently
wears Crown Bees colours throughout.

---

## Section 3 - What is in the app

Someone who is signed in moves around the app through a **bar of five buttons across the bottom of
the screen**. That bar is the app's spine, and it is settled: Dave, Kellie and Scott agreed it on
13 July 2026.

The five are **Home**, **Weather**, **Ask**, **Yard** and **Advice**. Ask sits in the middle as
an orange circle, deliberately the brightest thing on the screen.

- **Home** is the morning answer. The release recommendation sits at the top, with the weather, the
  most urgent alert, this week's advice, and a snapshot of the yard beneath it.
- **Weather** is the five-day forecast for the yard, with the pollen reading for whichever day is
  selected.
- **Ask** opens the **AI BeeBot**, a Crown Bees assistant that answers bee questions in plain
  language. It is provided by our partner Rep and runs inside the app.
- **Yard** is the yard itself: the plants in it, the seasonal bloom and warmth chart, and the
  release decision with the reasoning behind it.
- **Advice** is the to-do list, grouped by bee species, of what needs doing now.

Three more screens sit behind those five. **Plant detail** opens when a plant card is tapped.
**Alerts** is the full alert feed, reached from the alert card on Home. **Profile** is the account,
reached from the avatar in the top bar.

### Three screens you cannot reach yet

Three finished screens ship inside the app that **nobody can currently tap their way to**. They are
built and they work; they simply have no door.

- **Diary**, the seasonal diary, is reachable only from the desktop web menu, which is hidden on any
  screen narrower than 980 pixels. On a phone - which is the product - it is unreachable.
- **Notifications** has no route to it at all. The bell in the top bar goes to Advice instead.
- **Paywall** is present but inert. Nothing opens it and it charges nobody.

This is the clearest gap between what is built and what a person can actually use, and closing it is
one of the jobs of the onboarding work in the To Build Spec. The individual gaps are tracked as
BT-117 for Notifications and BT-024 for the paywall.

One related note: the anti-robot check on the sign-in screen only runs on the web. The phone app
takes a different, server-checked route instead.

---

## Section 4 - What it looks like

The screens below are **photographs of the real app**, taken from TestFlight build 24 on a real
phone, with real sign-in and real data. They are not mockups or drawings. The full set of 28
captures, including every state not shown here, sits in `as-built-screens/` with a file-by-file
manifest.

**One thing to read past in the Yard photographs.** They were taken before the fourth tab and its
screen were renamed to **Yard**, so the heading in those captures still reads "My Yard". The name
used throughout this document is the one that ships. The captures are retaken at the next capture
pass rather than edited - we do not retouch photographs of the app.

**Nine of the twelve real screens are pictured.** The three with no way in - Diary, Notifications
and Paywall - are described above rather than photographed. We do not fabricate screenshots of
screens a person cannot reach.

### The five main tabs

**Home** - the release decision, weather, top alert, this week's advice, and the yard at a glance.

![Home screen](as-built-screens/home.png)

**Weather** - the forecast, day by day, with the pollen reading.

![Weather screen](as-built-screens/weather.png)

**Ask** - the AI BeeBot assistant.

![Ask screen](as-built-screens/ask.png)

**Yard** - the release decision, the seasonal bloom chart, and the plants.

![Yard screen](as-built-screens/myyard.png)

**Advice** - what to do now, grouped by species.

![Advice screen](as-built-screens/advice.png)

### The screens behind them

**Plant detail**, opened from a plant card.

![Plant detail screen](as-built-screens/plant-detail.png)

**Profile**, opened from the avatar.

![Profile screen](as-built-screens/profile.png)

**Alerts**, opened from the alert card on Home.

![Alerts screen](as-built-screens/alerts.png)

### Coming in the door

The welcome, the email sign-in, and setting up the yard's location.

![Welcome hero](as-built-screens/login-welcome.png)
![How it works](as-built-screens/login-howitworks.png)

![Email code step](as-built-screens/login-email-typed.png)
![OTP verify step](as-built-screens/login-otp-filled.png)

![Location permission](as-built-screens/onboarding-location-permission.png)
![Confirm yard](as-built-screens/onboarding-location-confirm.png)

### Also captured, not shown here

The gallery folder additionally holds Yard when empty, adding a plant, and choosing a yard size;
Advice with no location set and with a tip open; Home and Profile as a guest; and the full sequence
of sign-in states.

---

## Section 5 - The look and feel

The app is built in the **Crown Bees design system** - it does not merely resemble the brand, it is
the brand. New screens are assembled from the existing kit rather than styled from scratch.

- **Two colours carry everything.** Green (`#004322`) is the frame, the headings and the structure.
  Orange (`#e69100`) is reserved for the one thing we want tapped, which is why the Ask button is
  the only orange circle on the screen. Beyond those, only warm neutrals - never a cold grey.
- **Three status colours** and no more: green for go, amber for wait, red for hold.
- **One typeface**, Inter, at a small set of fixed sizes.
- **The top bar** carries the CROWNBEES wordmark, a notifications bell and the avatar. **The bottom
  bar** carries the five tabs described in Section 3.

The navigation described above is settled canon as of 13 July 2026. Alternatives sketched in the UX
Flow Atlas - such as Dave's Home / Bloom / Bees / Shop / Ask arrangement - are tracked as proposed
changes against this baseline, not as open questions.

The full vocabulary of colours, type and components lives in the **Design System** document
(`design-system.md`), which is the reference for anyone building a screen.

---

## Appendix A - Release history

Eleven releases since the v1.0 milestone on 5 July 2026. Newest first. Server versions are
`btt-server` deploys; build numbers are TestFlight.

**v1.0.11** - server v61, over the air to build 24, 21 July. The Profile screen told a guest that
signing out would delete their garden. It never did - the garden and everything in it survive - but
a guest session carries no password, so there is no way back to it afterwards. The screen now says
that instead, and the button reads "Yes, sign out" rather than "Sign out and delete". The offer to
"sign in to save your garden" is also gone: signing in would have started a fresh account and left
the guest garden behind, so it promised the opposite of what it did. The bee at the top of the
screen is now the Crown Bees bee rather than the stock emoji, which is a striped honeybee and not
the solitary bee this app is about. **This is the first release delivered over the air** - no new
build, no App Store round-trip. It reaches a phone on the second cold start after it downloads.

**v1.0.10** - server v61, build 24, 13 July. The two buttons on the Weather location form looked
tappable while they were switched off. They now fade to half strength when disabled, matching every
other button in the app. Found by testing on a real phone, which is the only place it shows.

**v1.0.9** - server v61, 12 July. Our own server logs were recording the rough coordinates of a
user's yard, accurate to about a kilometre, inside cache keys and error messages. The coordinate is
now stripped from all six places it leaked. Nothing changed for anyone using the app; this was about
what we ourselves store.

**v1.0.8** - server v60, 12 July. Nine repairs from a full review of the codebase. The two that
matter to a user: tapping "add plant" twice no longer creates two identical plant cards, and weather
errors no longer quote the yard's raw coordinates back at the screen. The rest hardened how the
server shuts down, talks to the database, and gives up on slow third parties.

**v1.0.7** - server v59, 11 July. Pollen readings vanished in the evening. Google's pollen service
rolls over its forecast at 5pm Pacific and refuses to serve the day that just ended, so the app was
left holding nothing. It now keeps a rolling record per location that survives the rollover.

**v1.0.6** - server v58, build 22, 11 July. Pollen on the Weather screen now matches the forecast
day you actually selected, rather than always showing today. Growing-degree-days moved off the
Weather card, since the yard is where that belongs.

**v1.0.5** - build 20, 10 July. The sign-in button swallowed the first tap when the keyboard was
open, which made it feel broken. Fixed, and it now says "Sending" while it works. Bottom-bar icons
and labels were enlarged.

**v1.0.4** - server v57, 10 July. The **Guest** button did not work on the phone at all: it always
returned "Could not start a guest session", because Supabase's robot check is web-only and the phone
could not satisfy it. Guest sessions now go through our own server instead. Verified on a real
device.

**v1.0.3** - server v54, 7 July. The **Ask** button and the AI BeeBot assistant arrived. The
assistant is provided by our partner Rep and embedded in the app rather than hosted by us.

**v1.0.2** - server v53, 6 July. The yard's bloom chart did not refresh after adding or removing a
plant until the screen was reopened.

**v1.0.1** - server v52, 5 July. Security headers added at the server. Rolled out in report-only
mode first, watched until it was clean, then switched on for real.

**v1.0** - server v50, 5 July. The milestone. Email sign-in wired into the interface and proven
working end to end on the live host.

---

## Appendix B - Engineering reference

Where each screen and route lives in the code, at `ac5969c`. Route files are under `apps/client/`;
shared components come from `@btt/ui` (`packages/ui/src/`); the server procedures they call are
grouped by namespace under `apps/server/src/routers/`.

| Screen or route | Route file | Key components | Server procedures |
|---|---|---|---|
| Entry | `app/index.tsx` | (redirect to Home) | none |
| Home | `app/(app)/welcome.tsx` -> `components/WelcomeScreen.tsx` | DecisionBanner, AlertCard, YardAwarenessCard, WeeklyTipSheet | `garden.getReleaseDecision`, `garden.yardAwareness`, `weather.forecast`, `weather.myLocation`, `alerts.list`, `tip.current` |
| Weather | `app/(app)/weather.tsx` | Card, PollenGauge | `weather.forecast`, `weather.myLocation`, `weather.pollen`, `weather.setLocation` |
| Ask | `app/(app)/ask.tsx` (+ `ask.web.tsx`) | WebView-based | none - embeds the Rep assistant |
| Yard | `app/(app)/plants.tsx` | PlantCard, AddPlantCard, BloomConfirmRow, DecisionBanner, GddYearChart | `garden.listGardenPlants` / `addPlant` / `removePlant` / `getProfile` / `confirmBloom`, `weather.gddYear` |
| Advice | `app/(app)/advice.tsx` | SpeciesAccordion, ActionDetailSheet | `garden.adviceFeed`, `garden.markAdviceDone` |
| Plant detail | `app/plant/[key].tsx` | DetailHero, GddBar, KvList | `garden.getProfile`, `garden.getReleaseDecision` |
| Diary (no phone entry) | `app/(app)/diary.tsx` | Card, Pill, Button | `diary.list` / `create` / `remove` |
| Alerts | `app/(app)/alerts.tsx` | AlertFeedRow, Card | `alerts.list`, `weather.myLocation` |
| Notifications (no entry) | `app/(app)/notifications.tsx` | Card, Button | `notification.list` / `markRead` |
| Profile | `app/(app)/profile.tsx` | DetailHero, BeeIcon, KvList | `user.me`, `notification.getPreferences` |
| Paywall (inert) | `app/(app)/paywall.tsx` | Card, Pill, Button | none wired |
| Login | `app/login.tsx` | Hero, StepCard | `session.authStatus`, `auth.guestSignIn` |

**Entry** (`app/index.tsx`) is the app's root route: a bare redirect to Home, not a screen anyone
sees. The sign-in gate that sends a signed-out visitor to Login lives in the root layout's navigator
(`app/_layout.tsx`), not in Entry. This is why the map lists thirteen routes while Section 4 counts
twelve screens a person can actually see - Entry has no screen of its own.

The header and bottom bar (`SiteHeader`, `BottomTabBar` in `apps/client/components/`) wrap every
signed-in screen via `app/(app)/_layout.tsx`.

Two notes for anyone running it. The app boots against mock data with no backend at all in the iOS
and Android simulators (`cd apps/client && pnpm dev`, then press `i` or `a`). And migration `0023`,
which added the constraint stopping duplicate plants, was applied to production on 12 July and
deleted no rows, because there were no duplicates to clear.

---

*As-Built Spec v1.0.11 - The Bee Team. Reached v1.0 at Session 314 (5 July 2026) when email sign-in
was wired into the interface and deployed at btt-server v50. Eleven releases have followed; they are
listed in Appendix A with their versions, server deploys, and dates. Session 376 added the production screen
gallery. Session 387 rewrote the document in plain language and moved the release history and the
code map into appendices - the facts are unchanged and still reconciled to `69ed4b5`; only the voice
changed. Session 398 recorded the first release delivered over the air, which split "what is live"
into a native build and an update layered on it; the code map is now reconciled to `ac5969c`.
Session 403 renamed the fourth tab and its screen to **Yard** throughout. The bar already read
"Yard"; the screen heading and the web nav item still read "My Yard", and Scott's call was that the
two MUST agree. The code change is made and the documentation is written to the shipped name; the
release coordinates and the Appendix A entry are added when it is published, because the update
group identifier does not exist until then.
Production truth for "what is live", machine-verified at deploy. Change history lives in git, the
LMA records, and the dated snapshots, never this footer.*

---

<!-- canon: To Build Spec v0.2 (Draft) - source: https://bt-canon.pages.dev/to-build-spec.md -->

# To Build Spec - v0.2 (Guest onboarding funnel)

> **Durable document** (designated Session 310, 2026-07-05; retargeted to v1.1 at Session 314 when
> v1.0 shipped; **re-shaped to the To Build model + 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.3). This is the **To Build Spec** - it answers **"what
> are we building next, exactly - and on what plan?"** and holds the **roadmap, LOE, duration,
> prioritization, backlog detail, and the pixel-perfect build contract**. Filename kept as
> `next-build-spec.md` (the SOP allows the legacy name; the CLAUDE.md artifact table is the pointer
> authority). Living copy: this file; dated, version-stamped snapshots under `documents/snapshots/`.
> Companions: **As-Built Spec** (`as-built-spec.md` - v1.0.11, current production truth), **UX
> Flow Atlas** (`ux-flow-atlas.md` - the persona-by-flow desired-experience map), and **Design
> System** (`design-system.md` - the look-and-feel basis every screen planned here is rendered in).

**STATUS: DRAFT - NOT YET APPROVED (document v0.2).** This document plans **product release v1.1**
(the Guest onboarding funnel) - the release version is a **separate axis** from this document's own
version, which now runs the DRAFT **v0.x track** (promotes to v1.0 on approval). Versioning of the
evolving thinking begins here (Session 381, 2026-07-15). ~60-80% complete; significant changes are
still expected as Dave and Kellie's work locks - this is **not yet approved canon** (unlike the
As-Built and the Design System). The **plan** (Sections 1-5: what v1.1 is, the roadmap,
LOE/duration, prioritization, the Dave/Kellie candidate set, backlog detail) is authored from the
current backlog and the open Dave/Kellie requests - it is real, disposable reaction material, not
approved canon. The **pixel-perfect per-screen contract (Section 6) is an empty scaffold** - it is
authored at the v1.1 planning + delivery session and MUST pass the visual-preview + review gates
before anyone builds from it. Everything marked `[TO BE DEFINED / APPROVED - ...]` or listed in
Section 7 (Open Items) is not yet settled. **Do not build from this until Section 6 is filled.**

> **Predecessor:** v1.0 (email-OTP wired into the app = MVP) **shipped** at btt-server v50 on
> 2026-07-05 (Session 314) and folded into the As-Built, which now stands at **v1.0.11** (btt-server
> v61, client EAS build 24 running over-the-air update `3c52b3f5`, product `main` `ac5969c`). The
> retired v1.0 scaffold is preserved at `snapshots/2026-07-05-next-build-spec-v1.0.md`.

---

## Section 1 - What v1.1 is

**v1.1 = the Guest onboarding funnel - the value-first, no-signup-wall Guest track.**

- **The work:** build the Guest onboarding flow the funnel opens with - the user sees real,
  personalized value first and is asked for an account only when they commit. Maps to the roadmap
  features **F0** (onboarding flow foundation) plus **F1-F4** (Guest core -> Guest close), Section 2.
- **Why it is next:** with the MVP (v1.0 auth) live, the Guest funnel is the next UX flow per
  Scott's Session 309 version ladder - it makes the product self-demonstrating before the account
  ask. (The desired experience per persona is the UX Flow Atlas's concern; this spec is the *plan*
  and the *build contract*.)
- **The skin rule:** every screen is rebuilt in the shipped Crown Bees Design System - the canon
  **Design System** doc (`design-system.md`, the 4th canon document; also summarized in As-Built
  Section 4). Dave & Kellie's mockups are the source of content, layout, copy, and flow - NOT their
  colors or fonts. Copy is taken word-for-word.

**Candidate screens (Guest track):** Welcome (value-first splash), Goals (goal-capture chips),
Region (location), Results (personalized plant list + Blooms/Bees toggle), Bloom & Bee Plan (rich:
diary + popups + bloom curves), Additional Details, Your Oasis preview, Choose Plan (Free vs Oasis
Pro matrix). The exact set is fixed by the boundary decision in Section 7.

---

## Section 2 - The roadmap (now homed here per the To Build model)

Per the SOP v0.2 routing (Section 11), the feature roadmap, phasing, and version assignment live in
the To Build Spec, not the Atlas. This table is relocated from the Atlas (Atlas Sections 3-4); the
Atlas's copy is superseded and MUST be removed when the Atlas is re-scoped to the UX Flow Atlas
(Open Item 7.8). Effort is in **sessions** under plan-then-deliver (each feature = 1 planning
session + N delivery sessions with build + visual QA + review gate).

| # | Feature | Screens | Complexity | Sessions (Atlas baseline) | Depends on | Version |
|---|---|---|---|---|---|---|
| **F0** | Onboarding flow foundation - flow router + Guest/Pro branch + DS screen shell, wired into app entry | infra | L | 3-4 | - | **v1.1** |
| **F1** | Guest core - Welcome, Goals, Region | 3 | S-M | 2 | F0 | **v1.1** |
| **F2** | Results - personalized plant list + Blooms/Bees toggle | 1 | M | 1-2 | F0 | **v1.1** |
| **F3** | Bloom & Bee Plan - diary, popups, bloom curves (rich) | 1 | L | 3-4 | F0 | **v1.1** (boundary Q, 7.1) |
| **F4** | Guest close - Additional Details, Your Oasis preview, Choose Plan | 3 | M | 2 | F0 | **v1.1** (boundary Q, 7.1) |
| **F5** | Account (email-OTP) wired into the app + guest-upgrade | 3 | L | 3-4 | F0 | **SHIPPED (v1.0)** |
| **F6** | Pro setup wizard - Trial Confirmed, Location, Bee Guidance, Setup Routing | 4 | M-L | 3 | F0, F5 | v1.2+ |
| **F7** | Inventory - Full / Simplified / Assessment | 3 | L | 3 | F6 | v1.2+ |
| **F8** | Plant + Bee inventory (rich add/remove, accordions) | 3 | L | 3-4 | F6 | v1.2+ |
| **F9** | Payoff + funnel landing into the live app | 1 | M | 1-2 | F1-F8 | v1.2+ |

**v1.1 scope (F0 + F1-F4) = the full Guest track**, unless sliced per the boundary decision (7.1).
**Parallel tracks (not funnel-blocking):** Security NFR (**BT-094**, an OPEN seven-workstream
program, top priority - insertion point is Open Item 7.6); RepAI (**BT-062** - the Ask assistant,
**already SHIPPED** at v1.0.3/btt-server v54, so it is done, not pending); Naming/branding
(**BT-095**, renders Crown Bees + Dave's copy until resolved, post-MVP).

**Effort key:** XS already-shipped (0-1) | S static (1) | M selectors/branching (1-2) | L rich
interaction or cross-cutting (2-3) | XL subsystem + backend (3+).

---

## Section 3 - LOE and duration

**LOE (level of effort).** The Atlas-baseline estimate for the full v1.1 Guest track (F0 + F1-F4):

| Feature | Sessions (baseline) |
|---|---|
| F0 foundation | 3-4 |
| F1 Guest core | 2 |
| F2 Results | 1-2 |
| F3 Bloom & Bee Plan (rich) | 3-4 |
| F4 Guest close | 2 |
| **v1.1 total** | **~11-14 sessions** |

`[TO BE DERIVED / APPROVED - the rigorous LOE reconstruction]` Per BT-102 Section 5, the real LOE
baseline is reconstructed from our own delivered history (the version trail v50 -> v61, the dated
CSRs, `outputs/_timers/sessions.log`), estimating future work by analogy to comparable *delivered*
work - never a global session mean. **Two caveats that MUST shape the number:** (1) a large share of
sessions were framework/records/discipline work, not product delivery - anchor on shipped
increments; (2) throughput changed materially once subagent-driven development became the default,
so recent velocity is the predictive number and the early history is context, not baseline. The
Atlas baseline above predates that recalibration and likely overstates the session count for the
subagent era. This reconstruction is a dedicated analysis pass (it doubles as the delivered-roadmap
lane, BT-102 Section 5) and is not done here.

**Duration (calendar).** `[TO BE DERIVED - depends on the LOE pass + the working cadence]` Recent
cadence has been high and variable (e.g. Sessions 351-368 ran across 2026-07-10..07-13). Duration =
LOE (sessions) x the assumed sessions-per-day cadence, produced with the LOE pass. Not asserted here.

---

## Section 4 - Prioritization + the Dave/Kellie candidate set

**v1.1 priority order (proposed strawman):**

1. **Security NFR (BT-094)** where it must land - it is the standing top priority and the web is a
   live public surface (7.6).
2. **The Guest funnel (F0 + F1-F4)** - the v1.1 scope proper.
3. **Scott's live-review UI items (BT-052)** - small, high-signal fixes; candidates to fold in
   alongside F1-F4 (Forecast heading rename, guest note-save friendly error, Yard 1/3 cards).

**The Dave/Kellie next-release candidate set** (from BT-053 / `next-release-dave-kellie-changes.md`).
These are candidates Scott selects from - the catalog is the candidate set, not the commitment:

| Group | Asks (owning item) | Shape | v1.1 disposition (strawman) |
|---|---|---|---|
| **A - net-new** | Rep AI + ask-bar (BT-048); BeeBuyBack priority (BT-049); bee-success score (BT-050) | High value, each carries one open decision | **Defer past v1.1** - each is gated on a Dave/posture decision (7.4). RepAI's Ask surface already shipped (BT-062). |
| **B - folds** | intro-video entry (BT-013); beneficials beyond bees (BT-017); iNaturalist ID (BT-037); inventory (BT-040) | Bounded, content-light | **Candidates** - B1 intro-video entry (BT-013) fits the Guest funnel's Welcome/onboarding; others v1.2+. |
| **C - decisions** | subscription model CONFIRMED (BT-024); app-store go/no-go (BT-024/C2) | Scope-shaping, not build work | Subscription posture locked (SaaS). App-store go/no-go is a Dave decision (7.5); web-first regardless. |
| **D - Oasis waves** | reminders (BT-031), diary (BT-036), advice/reports/counter (BT-030..041) | Roadmap-scale sub-project | **Not v1.1** - pick a wave in its own planning track (post-funnel). |
| **E - routed out** | monitoring hardware / CV (BT-051) | Handed to pollinator-mesh | Out of app scope. |

**Unblock-question status (BT-053):** q1 (Rep-AI approach), q2 (BeeBuyBack direction), q4 (cocoon
scale) = Scott-answered; q5 (app stores - both, web first), q6 (parse Crown Bees YouTube) =
Dave/Kellie-answered; **q3 (bee-success scoring model, BT-050) still awaits Dave** - it blocks any
BT-050 work but not the Guest funnel.

---

## Section 5 - Backlog detail (relevant items)

The owning `BT-NNN` item is the single source of truth for each; this is the pointer map for v1.1.

- **The funnel features:** F0-F4 have no single owning BT item yet (they are Atlas-roadmap
  features). `[TO BE DEFINED - allocate BT items for F0-F4 at the v1.1 planning session, just-in-time
  per Port-24]` See also Open Item 7.7 (verify the F0-F9 identifiers were allocated, not
  pre-reserved).
- **Parallel / adjacent:** BT-094 (Security NFR, OPEN, top priority), BT-062 (RepAI - SHIPPED),
  BT-095 (branding, post-MVP), BT-052 (Scott's 3 live-review UI items).
- **Dave/Kellie candidates:** BT-013, BT-017, BT-037, BT-040, BT-048, BT-049, BT-050, BT-024;
  Oasis umbrella BT-030 (waves BT-031..041); BT-053 (this catalog's owner).
- **Recently shipped context (do not re-open):** BT-101 (native email-OTP send), BT-106 (native
  guest sign-in), BT-113 (fail-closed rate limiters), BT-115 (evening pollen), BT-117/wx-1 (weather
  disabled-button), BT-120 (apple-submit tool) - all in the As-Built version trail.

---

## Section 6 - Per-screen pixel-perfect build contract

`[TO BE AUTHORED at the v1.1 planning + delivery session]`

Empty scaffold. At the v1.1 delivery session, each in-scope Guest-track screen (Section 1) gets a
block here at pixel-perfect fidelity: exact copy (verbatim), layout, `@btt/ui` components + tokens
named, every interaction and state enumerated, and the flow-out. Build directly from these blocks
only once they pass the visual-preview + review gates. Sources for the pixel canon: the Guest-track
screen intents (UX Flow Atlas Section 2a) and Dave's wireframe-fidelity renders
(`../outputs/s305/img/canon/`). Until this section is filled, this document is a plan, not a build
contract - do not build from wireframes.

---

## Section 7 - Open Items / Questions

1. **The v1.1 boundary.** Is v1.1 = the **full** Guest track (F0-F4), or a **split** (e.g. F0-F2 as
   v1.1, F3-F4 as v1.2)? The recommended build sequence built the Guest track end-to-end to be
   demoable to Dave & Kellie; the version ladder can honor that as one v1.1 or slice it.
2. **Rich-screen sequencing.** F3 (Bloom & Bee Plan) is the highest-effort screen (rich diary +
   popups + live bloom-window SVG curves). Confirm whether it lands in v1.1 or defers to keep v1.1
   shippable sooner.
3. **LOE / duration method.** The rigorous reconstruction (Section 3, BT-102 Section 5) is a
   dedicated pass; until it runs, the Atlas-baseline numbers stand as strawman only.
4. **Dave/Kellie open decisions gating candidate asks:** q3 bee-success scoring model (BT-050,
   Dave's domain); Rep-AI-vs-BT-037 posture (BT-048 "app hosts an assistant" vs BT-037 "app curates
   prompts, does not host AI"); BeeBuyBack data target (BT-049, Zoho vs app backend - touches the
   Crown Bees commerce boundary, CLAUDE.md Section 7.4); named integrations (iNaturalist BT-037, MJV
   BT-017 - integration shape with Dave).
5. **App-store go/no-go (BT-024/C2).** Dave-level decision on whether to distribute via Apple/Google
   (forces the native IAP billing rail); web ships first regardless. (q5 answered: both stores, web
   first - confirm this is still the intent for v1.1 planning.)
6. **Security NFR (BT-094) insertion point.** Where the remaining open BT-094 workstreams (incl. PII
   export/delete) land against v1.1 - before, interleaved, or as a parallel track.
7. **F0-F9 identifier provenance (Port-24).** The Atlas already carries F0-F9. Verify these were
   allocated just-in-time, not pre-reserved, before they are reused as canonical feature IDs; and
   allocate the owning BT items for F0-F4 at the v1.1 planning session.
8. **Roadmap single-source (E7).** This section's roadmap (Section 2) is relocated from the Atlas;
   the Atlas's copy MUST be removed when the Atlas is re-scoped to the UX Flow Atlas, so the roadmap
   lives in exactly one place.
9. **Pixel canon source.** The net-new Guest screens have no approved pixel canon yet - Section 6 is
   authored through the visual-preview gate at the delivery session; the Atlas's Dave wireframes are
   the illustrative starting point, not canon.
10. **Guest-vs-account boundary detail.** The exact moment the funnel asks for an account (first
    save? Choose Plan? trial start?) is a UX decision the Atlas's persona matrix should settle;
    surface it there and reflect the answer in Section 6.

---

*To Build Spec v1.1 - The Bee Team Session 369 strawman (re-shaped from the v1.0-model Next Build
Spec scaffold to the SOP v0.2 To Build model: this document now holds the roadmap, LOE, duration,
prioritization, and backlog detail alongside the pixel-perfect contract). Target scope: the Guest
onboarding funnel (F0 + F1-F4). The plan is disposable reaction material; the per-screen pixel canon
(Section 6) is authored at the v1.1 delivery session and passes the gates before any build. Change
history lives in git + the LMA records + the dated snapshots, never this footer.*

---

<!-- canon: UX Flow Atlas v0.2 (Draft) - source: https://bt-canon.pages.dev/ux-flow-atlas.md -->

# 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.3). 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.11, 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 / 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.

---

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

---

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

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

| 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. The "Explore Dave's garden" demo path lets them see the full payoff before committing anything. 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 / 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).

| Persona | Desired experience |
|---|---|
| **The Newbee** | "What's in your garden?" with an easy picker; the app recommends and explains. The 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)

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

| 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

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

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

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

| Persona | Desired experience |
|---|---|
| **The Newbee** | Beginner kits front-and-center - a complete kit (house + cocoons) or a bare-bones starter, with a recommended quantity derived from their garden and a recommended delivery date, in plain terms. The in-app store means they never have to leave to buy what the app just told them they need. |
| **The Hobbyist** | Recommendations tuned to their logged inventory + past Crown Bees purchases; quantity +/- control, priority indicators, and Purchase History to track what they have ordered and when. Add-to-Cart keeps the buying moment inside the app. |
| **The Bee SME** | Precise quantity recommendations against a real inventory and garden model; multiple release/delivery dates for staged pollination; full Purchase History with tracking and returns. Expects the in-app store to be a genuine equivalent of the website, not a thin shim. |

---

## 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 |
| Dave "5 slides" onboarding (Jul 2 2026, newest) | `../_capture/2026-07-dave-flows/rendered/5slides.png` | Onboarding + Choose Plan (3.1 / 3.11) |
| Dave onboarding v1 (Jun 30 2026) | `../_capture/2026-07-dave-flows/rendered/allscreens.png` | Onboarding, earlier iteration (3.1) |
| Dave "5 window screens" annotated (Jun 26 2026) | `../_capture/2026-07-dave-flows/rendered/5window.png` | Onboarding design rationale (3.1) |
| Dave "Your Pollinator Oasis" overlay (Jun 26 2026) | `../_capture/2026-07-dave-flows/rendered/code.png` | GDD/bloom/bee overlay + explainer modals (3.3) |
| Dave "The core" Bloom & Bee Plan (Jun 30 2026) | `../_capture/2026-07-dave-flows/rendered/core.png` | The heavy-lifter bee plan (3.6) |
| Dave-email corpus + synthesis (Session 378) | `../_capture/2026-07-dave-flows/README.md` | Full corpus, supersession rules, Shop/commerce source (3.12) |

(Image durability - whether to copy these into the durable documents home - is deferred per SOP
Section 12 Q2; the owning backlog item is **BT-102**, which holds the canon document model and the
standing ruling that Atlas imagery is illustrative and never pixel canon.)

---

## 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. **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?
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.2 - 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.*

---

<!-- canon: Design System v1.0 (Approved . canon) - source: https://bt-canon.pages.dev/design-system.md -->

# Design System - Pollinator Oasis (Crown Bees Pollination App)

> **Durable document** (designated Session 370). One of the four canonical project documents per
> the Hub methodology **[[10-Three-Document-Product-Canon]]**. This is the **Design System**: it
> answers **"what does the product look and feel like?"** Its companions are the **As-Built**
> (`as-built-spec.md` - what is live), the **UX Flow Atlas** (`ux-flow-atlas.md` - the experience
> we want), and the **To Build Spec** (`next-build-spec.md` - what we build next).
>
> **Version v1.0.** Shipped-skin coordinates: server `btt-server` **v61**, iPhone app **TestFlight
> build 24**, code at `69ed4b5`. Living copy: this file; dated snapshots under
> `documents/snapshots/`.

**STATUS: APPROVED - canon (2026-07-15).** Everything in this document is settled. Scott confirmed
it with Dave and Kellie on 2026-07-13, and changes from here are tracked as deltas against this
baseline. The known drift in Appendix A is accepted and documented, not blocking. The product is
still 60-80% complete, so the design system may yet gain components - but the items it carries
today are settled.

**IP notice.** The design system **is the Crown Bees brand** - the sole IP of **Dave Hunter / Crown
Bees, LLC**. The `crown-bees-design` skill's own notice governs: *"(c) 2026 Dave Hunter / Crown
Bees, LLC. All rights reserved. Confidential - not for distribution. Produced by Scott Sands
(advisor) and Claude under Scott's direction, on behalf of Dave Hunter / Crown Bees, LLC. No IP
claim by Scott Sands or Claude."* The Bee Team's combined IP is the **app** that implements this
brand, per `IP-NOTICE.md` - not the brand itself. When BT extends the design system with
app-specific components (the `@btt/ui` net-adds), those components are combined BT work product
built in the Crown Bees brand.

**What this document is.** A plain description of the look and feel the app is built in - the Crown
Bees brand, as it actually ships today. Written for anyone on the team who needs to know what the
product should look like.

**What it is not.** It is not the design system itself. The colors, the type and the components
live once - in the brand skill and in the code - and this document points at them rather than
copying them. Copying would create a second place to be wrong. Reproduce from the sources in
Appendix A; never re-draw from memory.

**How to read it.** Sections 1 to 7 are the look and feel in plain language. The two appendices are
for engineers: Appendix A is the authoritative sources and the known drift, and Appendix B is the
version history.

---

## Section 1 - What the Crown Bees look is, and where it lives

The Crown Bees look is warm, plain and uncluttered.

**Two colors carry it**: a deep green for frames, headings and structure, and a single orange kept
for the one thing you should do next. Type is one family, Inter - tight and heavy for display,
comfortable for reading. Backgrounds are warm neutrals, never cold grey. Cards are white with a thin
warm border and no shadow at all. There is no photography, no texture and no pattern: surfaces are
flat fills, and the whole system allows exactly two gradients. Icons are emoji, used to mean
something rather than to decorate. And the app speaks like an expert gardener, never like a
marketer.

The rest of this document is that look, in detail.

**Where it lives.** The design system exists authoritatively in **two layers**, and they can drift.
Naming them, and the rule between them, is this document's first job.

| Layer | Where | Authority for |
|---|---|---|
| **Brand design authority** | the `crown-bees-design` skill (Appendix A names every file) | The **design intent** - what the brand is |
| **Implemented** | `packages/ui` in the product repo - the shipped tokens, plus the `@btt/ui` component and chart library | **What actually ships** - what renders in the app on iOS / Android |

**Where the brand came from.** The brand authority was extracted verbatim from the Crown Bees
Pollination Success App v0.1 prototype. **The prototype is the ultimate source: where the skill and
the prototype disagree, the prototype wins.**

**The rule.** The brand design authority governs *intent*; `packages/ui` governs *what is live*.
Where a shipped value differs from the brand authority, that is a **drift to reconcile** - the
implemented value is what the user sees (and so what the As-Built records), while the brand
authority states what it should be. Known drift is listed in Appendix A, so neither layer is read as
complete on its own. New work reproduces from **both**: the brand authority for the rules and the
voice, `packages/ui` for the exact shipped tokens and component APIs.

Building a new screen is **compose-from-the-kit**, not a reskin. The live app skin already **is**
this design system.

---

## Section 2 - Color

**Two brand colors carry everything.** Green is frame / heading / structure; orange is the **only**
call-to-action color, used sparingly so it always reads as "do this."

| Role | Hex | CSS var (skill) | Code token (`packages/ui`) |
|---|---|---|---|
| **Brand green** (primary) | `#004322` | `--cb-green` | `colors.green` |
| Green dark (hover / pressed) | `#002e17` | `--cb-green-dark` | `colors.greenDark` |
| Green light (hero terminus) | `#1d6a44` | `--cb-green-light` | `colors.greenLight` |
| **Action orange** (only CTA) | `#e69100` | `--cb-orange` | `colors.orange` |
| Orange light (pale surface) | `#fff6e6` | `--cb-orange-light` | `colors.orangeLight` |
| Orange dark (hover / pressed) | `#b87100` | `--cb-orange-dark` | `colors.orangeDark` |

**Semantic status trio** (GO / WAIT / HOLD): success green `#28a745` (`--cb-success` /
`colors.success`), warning amber `#eb9247` (`--cb-warning` / `colors.warning`), alert red `#e95050`
(`--cb-red` / `colors.red`). Red also carries "sale."

**Warm neutrals** (never cold grey): text `#222222`, muted `#6b6760`, soft `#888888`, white surface
`#ffffff`, page field `#f8f8f8`, cream highlight `#fdf6e6`, hairline border `#e6e3dd`, faint divider
`#f0ede6`. (Code tokens: `colors.text` / `textMuted` / `textSoft` / `bg` / `bgSoft` / `bgCream` /
`border` / `borderSoft`.)

**IP / confidentiality band palette** (always-on notices): parchment `#fdf6e3` (`--ip-bg`), brown
text `#6b5a2c` (`--ip-text`), gold border `#ecd9a3` (`--ip-border`).

**Status-pill tints** (pale bg + saturated text), via `pillTints` in code:

| Tone | bg | fg |
|---|---|---|
| green | `#e6f5ec` | `#28a745` |
| orange | `#fff2e0` | `#b87100` |
| red | `#fce8e8` | `#e95050` |
| blue | `#e6f0f7` | `#2c5fa3` |
| grey | `#ececec` | `#6b6760` |

**Chart accent palette** (added S209 / S242; implemented in `colors.ts`, see the Appendix A drift
note): clay `#bd6b43` (early-tier / harvest / temp) + claySoft `#f4e6dc`; sage `#74886b` (mid-tier /
Summer Leaf) + sageSoft `#eef2e9`; sky `#2c5fa3` (late-tier / threshold / GDD) + skySoft `#e6f0f7` /
skyBorder `#cfe0ee`; plum `#7a5ea8` (Huckleberry).

---

## Section 3 - Typography

**A single family: Inter** (weights 400-800), loaded via `@expo-google-fonts/inter` in the app and
Google Fonts in the skill. System-mono fallback (`SF Mono, Menlo, Consolas`) for code / labels only.
No serif in the live app.

**Font-family tokens** (`fontFamily` in `typography.ts`): `Inter_400Regular`, `Inter_500Medium`,
`Inter_600SemiBold`, `Inter_700Bold`, `Inter_800ExtraBold`.

**Scale** (size / weight / tracking), from `fontSize` + `fontWeight` + `letterSpacing`:

| Role | Size | Weight | Tracking | Note |
|---|---|---|---|---|
| hero | 36 | 800 | - | welcome hero h1 |
| h1 | 30 | 800 | -0.3 | display, tight + heavy |
| h2 | 22 | 700 | -0.2 | |
| h3 | 16 | 700 | - | |
| lead | 17 | 400 | - | intro paragraph, muted |
| body | 15 | 400 | - | line-height 1.5 (= 22.5) |
| small | 13 | 400 | - | captions / muted |
| micro | 11.5 | 500 | - | IP band, eyebrow (uppercase, +0.3 tracking) |

Display is tight and heavy; body is comfortable at 15/1.5.

---

## Section 4 - Spacing, radii, elevation, layout, motion

- **Spacing** (4px base, sparse map - reproduce the exact keys), `spacing` token:
  `1:4 / 2:8 / 3:12 / 4:16 / 6:24 / 8:32 / 12:48`.
- **Radii**, `radii` token: default `10`, lg `14` (cards / heroes / banners), xl `20`, pill `999`.
- **Elevation:** exactly **one shadow** in the system - the sticky header
  `0 1px 4px rgba(0,0,0,0.08)` (`shadows.header`, platform-aware via `Platform.select`). **Cards
  carry NO shadow** - a 1px warm border + 14px radius does the separating.
- **Layout:** content capped at **980px** centered, 16px side gutters (`--max-width` / `--gutter`).
- **Motion** (minimal, quick): screen fade-in `0.18s ease` (opacity 0->1, translateY 4px->0);
  hover / press `0.12s ease`; progress-bar width `0.4s`. No bounces, loops, or parallax.
- **Signature gradients (the only two):** the welcome **hero** `linear-gradient(135deg, green ->
  green-light)` and the **GDD progress bar** `linear-gradient(90deg, green -> orange)`. Everything
  else is a flat fill - no photography, textures, or patterns.

---

## Section 5 - Component vocabulary (`@btt/ui`)

The implemented library lives at `packages/ui/src/`; import from `@btt/ui`. Each has a test in
`__tests__/`. Compose screens from these; a component not already here is a **net-add** (flag it).

**Primitives:**
- `Button` - variants primary / outline / outlineOnDark / secondary / ghost / green / heroLight;
  sizes sm / md / lg. Hover darkens to the `-dark` token; disabled = 0.5 opacity.
- `Pill` - 5 tones (Section 2 tints); `toPillLabel` Title-Cases + strips punctuation, all-caps
  tokens survive. GO / WAIT / HOLD is **`DecisionBanner`**, not a Pill.
- `Card` - white fill, 1px warm border, 14px radius, no shadow; padding default 24 / tight 16.
- `Typography` - the Section 3 variant scale.
- `DecisionBanner` - the large, full-color GO / WAIT / HOLD banner (the app's most saturated
  surface, reserved for the daily release call). Distinct from Pill.
- `TopProgressBar` - the top loading line = the header's idle orange underline.

**Content components:** `Hero`, `DetailHero`, `StepCard`, `KvList`, `GddBar`, `PlantCard`,
`AddPlantCard`, `AdviceItem`, `KnowledgeCard`, `BloomConfirmRow`, `AlertFeedRow`,
`SpeciesAccordion`, `ActionDetailSheet`, `WeeklyTipSheet`, `TodayWeatherCard`, `WeatherGrid`,
`HomeSummaryCards`.

**Charts** (`packages/ui/src/charts/`): `ChartFrame`, `GddYearChart`, `PollenGauge`,
`VarietyTimelineChart`, `TempActiveBeesChart`, `BlossomWindowsChart` (+ `gdd-geometry` / `scale`
helpers).

**Chrome** (app-level, in `apps/client`, built on the kit):
- **SiteHeader** - green `#004322` app bar on every signed-in screen: orange-bee CROWNBEES
  wordmark -> Home, notifications bell -> Advice (orange unread badge), avatar -> Profile, a 3px
  orange bottom line (`TopProgressBar`). Mobile below 980px; horizontal nav row at/above 980px.
- **BottomTabBar** - white, mobile-only, five slots: **Home / Weather / [center orange "Ask" FAB]
  / Yard / Advice**. The FAB (54x54, orange, floating) is the Rep-AI "Ask" entry point (BT-062).

---

## Section 6 - Voice + iconography

**Voice** (from the prototype's copy): warm, plain-spoken, confidence-building - an expert
gardener, never a marketer.

- **Second person, possessive:** "your garden", "your bees", **My** Plants, **your** Crown Bees
  cart. The app speaks as "we" (Crown Bees).
- **Sentence case** for body and most headings. The three decision verbs **GO / WAIT / HOLD** are
  the only shouted words (plus all-caps status pills like `BLOOM ACTIVE`). Nav labels are Title
  Case ("My Plants", "Weather & Bees").
- **Action-oriented:** every screen reduces to a clear next action. Domain terms (Growing Degree
  Days, cocoons, hatchery) always paired with a plain consequence.
- **Concrete numbers**, no vague intensifiers. Contractions used freely.

**Iconography = emoji, used functionally** (never decoratively). No SVG / icon-font / line-icon
set - introducing one (Lucide / Heroicons / etc.) breaks from the source; flag if a true icon is
unavoidable.

- **Plant glyphs:** apple, pear, cherry, blueberry, peach, strawberry / raspberry, almond / nut,
  garden flowers.
- **Status / weather:** check (pass / GO), cross (fail), hourglass (wait), shield (guard), sprout,
  bee, bird, and the sun / cloud / rain forecast set.
- Keep new emoji at the same functional scale (22-36px).

---

## Section 7 - Logo + IP band

**The mark:** an apple / berry (a fruit body with two leaves holding seven seeds, one a **bee**)
locked up with the **CROWNBEES** wordmark (CROWN green, BEES orange). Current selection is
**"Option 2"** - a solid orange-disc bee (full color) / negative-space ring (reversed). Official
artwork lives in `assets/logos/`; never recolor or rebuild it.

| File | Role | Use on |
|---|---|---|
| `crown-bees-horizontal.png` | Primary - horizontal, full color | light backgrounds |
| `crown-bees-vertical.png` | Primary - vertical, full color | square spaces, app icons, badges |
| `crown-bees-horizontal-ondark.png` | Reversed - horizontal | Crown Green / dark backgrounds |
| `crown-bees-vertical-ondark.png` | Reversed - vertical | Crown Green / dark backgrounds |

**Logo color note:** the logo's orange is the artwork's own gold-orange `#F0A010` - intentionally a
hair warmer than the UI action orange `#e69100`. **Keep the logo's built-in orange; do not recolor
it to the UI token.** Clear space = the height of the "C" in CROWNBEES on all sides. Minimum ~120px
wide (horizontal) / ~90px tall (vertical) on screen. For infinite-scale print, request the original
vector from Crown Bees. Full rules: `LOGO.md`.

**IP / confidentiality band** appears on every brand surface and MUST stay visible: *"(c) 2026 Dave
Hunter / Crown Bees, LLC. All rights reserved. Confidential - not for distribution."* Rendered in
the parchment / brown / gold IP palette (Section 2). Blocks in `assets/ip-notice.html`.

---

## Appendix A - The authoritative sources, and the known drift

**Point here for exhaustive detail; reproduce from these, never from memory:**

| Source | Path | Authority for |
|---|---|---|
| Brand tokens (CSS) | `~/.claude/skills/crown-bees-design/colors_and_type.css` | Color + type + spacing + radii + motion, as design intent |
| Brand context / voice | `~/.claude/skills/crown-bees-design/README.md` | Brand story, copy voice, visual foundations, iconography |
| Logo usage | `~/.claude/skills/crown-bees-design/LOGO.md` | Logo files, color, clear space, do / don't |
| Logo artwork | `~/.claude/skills/crown-bees-design/assets/logos/` | The official logo files themselves |
| Token + component specimens | `~/.claude/skills/crown-bees-design/preview/` | Rendered color / type / spacing / component cards |
| UI-kit recreation | `~/.claude/skills/crown-bees-design/ui_kits/marketing-site/` | A faithful HTML recreation of the app + storefront |
| Implemented tokens | `packages/ui/src/tokens/*.ts` (product repo) | The **shipped** color / type / spacing / radii / shadow values |
| Implemented components | `packages/ui/src/components/*.tsx` + `charts/*.tsx` | The `@btt/ui` component APIs actually shipped |
| Full skin reference (narrative) | `outputs/s305/THE-BUILD-SPEC.md` Appendix A | The reproduction-grade skin write-up that seeded this document |

**Known drift between the two layers.** In both cases the implemented layer leads the brand
authority - the CSS is lagging shipped additions, not the other way round. Reconcile when the design
system is next revised.

1. **Radii xl:20.** `packages/ui` `radii` carries an `xl: 20` step the skill's `colors_and_type.css`
   does not list (skill has default 10 / lg 14 / pill 999). `xl:20` is shipped and canonical.
2. **Chart accent palette.** `colors.ts` carries the clay / sage / sky / plum chart accents (+ their
   soft tints, `skyBorder`) added S209 / S242; `colors_and_type.css` does not yet carry them. They
   are shipped, documented in THE-BUILD-SPEC Appendix A, and canonical - not yet back-ported to the
   skill CSS.

Neither drift is a defect in the app. A future revision should back-port both into the skill so the
two layers reconcile.

---

## Appendix B - Version history and provenance

**This document carries its own version, decoupled from product semver.** The As-Built version
tracks production and changes on every build. The design system changes far less often - only when
the design system itself changes, such as a new token, a new `@btt/ui` component, or a palette or
type shift. So this version bumps on design-system changes, and the shipped-skin coordinates
(server release, client build, commit) are pinned in the header for reference at authoring time.

**v1.0** - first authoring, Session 370 (2026-07-13). Reference-hub over the two authoritative
layers, reconciled against `packages/ui` at product `main` `69ed4b5` and the `crown-bees-design`
skill. Shipped-skin coordinates: btt-server v61, client EAS build 24.

**Provenance.** The design system was extracted from the Crown Bees Pollination Success App v0.1
prototype (`~/Documents/Claude/Vaults/Crown Bees/Crown-Bees-Pollination-App/prototype/index.html`)
into the `crown-bees-design` skill, then implemented in `packages/ui`. This document consolidates
the As-Built Section 4 skin summary and the THE-BUILD-SPEC Appendix A reference into the canonical
design-system entry point, per Scott's Session 369 direction that the Design System become the 4th
canon document. It is a reference-hub (Option A), not a copy - the token files and component source
remain the single source of truth in the skill and the code.

---

*Design System v1.0 - The Bee Team. The 4th canonical product document per the Hub Three-Document
Product Canon methodology (expanded to four at Session 369-370). The design system is the Crown
Bees brand (Dave Hunter / Crown Bees, LLC sole IP); the app that implements it is combined BT IP.
Reference-hub over two authoritative layers - the `crown-bees-design` brand skill (intent) and
`packages/ui` (what ships). Change history lives in git + the LMA records + the dated snapshots,
never this footer.*