To Build Spec

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 three 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 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.10, current production truth) and UX Flow Atlas (ux-flow-atlas.md - the persona-by-flow desired-experience map).

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.10 (btt-server v61, client EAS build 24, product main 69ed4b5). The retired v1.0 scaffold is preserved at snapshots/2026-07-05-next-build-spec-v1.0.md.

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.

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

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

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

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

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

1. The Guest funnel (F0 + F1-F4) - the v1.1 scope proper.
2. 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, My 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:

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.

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.

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

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.

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

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

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

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

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

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

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

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

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