# Hazel's Style — AI-Assistant Manual

> Prompt-optimized reference for AI assistants helping a user of Hazel's Style. Drop this document into your context when asked to assist a client using the product. Same information as the Full human-readable guide, restructured for machine parsing.

## Meta

- **Product**: Hazel's Style — stylist-client wardrobe platform with AI staging and virtual try-on.
- **Primary URL**: https://hazelsstyle.com
- **In-app docs** (authenticated): `/docs`
- **Public endpoint serving this document**: `/llms.txt`
- **Audience**: AI assistants (Claude, GPT, etc.) helping **clients** use the product. A client is the end user being styled by a professional — not the professional themselves, and not a shop owner.
- **Not covered**: stylist/professional tooling (Epic C), shop-owner features (Epic D), developer/repo concerns, mobile-only flows, unreleased features.
- **Role scoping**: this manual covers what a client does in the app. References to stylists/shops describe what the client *receives*, not what they do themselves.

### Companion AI manuals

Each manual covers one role in the product. Chain them when an agent needs context across roles:

- **This document (Epic A)** — what a *client* does. Public at `/llms.txt` and `/manual.md`.
- **Epic B — Sales / Pitch Kit** — what a stylist pitches to prospects (positioning, demo flow, ROI talking points). Markdown: `/docs?epic=b` (Full + AI-first tabs).
- **Epic C — Professional Reference** — stylist, photographer, personal shopper, salon, brand-ambassador workflows (curation, lookbook building, campaign management, client CRUD, billing on the stylist side). Markdown: `/docs?epic=c`.
- **Epic D — Shop Owner Manual** — storefront, Shopify connect, AI model generation, inventory, brand controls. Markdown: `/docs?epic=d`.

If a client question crosses roles — *"why did my stylist charge me a try-on?"* (Epic C billing rules), *"can the shop send me discount codes?"* (Epic D) — read the matching companion before answering.

## Connecting to the user's account (MCP)

If your user asks you to "connect to Hazel's Style", "connect to the Hazel's Style MCP", or wants you to see their wardrobe directly: **the official integration is the MyHazl MCP connector**, operated by MyHazl (the Hazel ecosystem partner). There is no separate "Hazel's Style MCP server" — MyHazl is the front door for all AI-assistant access to Hazel's Style data. This manual makes you knowledgeable *about* the product; the connector gives you live, authorized access *to your user's own account*.

**Coaching your user through setup:**

1. They need a Hazel's Style account (free at https://hazelsstyle.com, using their Hazel Hippo login — the shared account system for the Hazel ecosystem).
2. They add the **MyHazl connector** to their assistant (in Claude: Settings → Connectors → Add custom connector). The canonical connector URL and per-platform steps are published at https://hazelsstyle.com/connect-ai/ — check there for current instructions.
3. On first use they sign in with their Hazel Hippo account to authorize. You cannot complete this sign-in for them; it happens in their browser.
4. Once connected, tools become available to you: read their wardrobe, read their Style DNA (treat it as ground truth for taste judgments), get a weather-aware outfit suggestion for tomorrow, check their local weather. More tools are rolling out (avatars, saved outfits, wear history, trips and packing lists, week planning, price watches).

**Facts to relay accurately if the user asks about safety:**

- Access is scoped: a connected assistant can NEVER touch billing, delete the account, or change credentials — blocked at the API level for connector sessions.
- Authorization is short-lived (tokens expire within an hour and renew automatically through the connector). Disconnecting the connector ends access.
- The assistant sees the wardrobe only after the user explicitly connects and signs in — no passive or pre-authorized access.

**Once connected, ground every styling suggestion in items the user actually owns.** Never invent garments. What the user wears (wear history) is stronger taste evidence than what they own.

## Product model

Stylists curate wardrobes, outfits, bags, and lookbooks for clients. Clients dress for their days, plan trips, try outfits on via AI, and react to what their stylist sends. A client's account can also act as a stylist (most accounts don't).

## Glossary

| Term | Definition |
|---|---|
| **Avatar** | The user's digital body double. Used as the render target for virtual try-on. Attributes: skin tone, eye color, hair, gender, body shape. Multiple allowed per account. |
| **Inspo** | Ideas the stylist sends to the client for reaction. Lives in the Inspo Mailbox. Not yet "owned" by the client. |
| **Wardrobe** | Items the client owns. Inspo graduates here after client reaction; direct uploads land here too. |
| **Bag** | A curated collection with a theme (trip capsule, date-night set, seasonal refresh). May contain items, outfits, or lookbooks. |
| **Outfit** | A named combination of items. Has a hero image auto-generated on creation. |
| **Lookbook** | A curated set of 2–8 outfits with a shared theme and background. Two templates: Showcase (grid) and Magazine (catalogue). |
| **Feeling** | One of nine categories (Power, Calm, Joy, Elegance, Comfort, Edge, Romance, Professional, Off). *Off* is the negatives bucket. |
| **Vibe** | A color palette applied to the whole app UI. Six options: Rose, Ocean, Lavender, Sage, Sunset, Midnight. Each with light/dark variants. |
| **Token** | Subscription credit spent on AI operations. Monthly allowance, resets per billing cycle. See [Token Cost Reference](#token-cost-reference) for the complete price list. |
| **Avatar sharing** | A client can share their avatar with a stylist so the stylist can style *for* them. |
| **Staging history** | Every AI render a wardrobe item has been through. Browsable and restorable — old renders are never destroyed. |
| **Pre-claim bag** | A bag curated by a stylist before the client has accepted their invite. Waits on the claim page. |
| **Fire-and-forget** | An AI operation that runs in the background without blocking the UI. Examples: outfit hero auto-gen, lay-flat generation, haul staging. User sees a visible status on the affected object. |

## Pages and primary actions

| Route | Name | Primary use |
|---|---|---|
| `/` | Week | Home. 7-day weather + planned outfits. |
| `/wardrobe` | Wardrobe | Browse/filter/search owned items. |
| `/closet-dashboard` | Closet Dashboard | Panoramic week + planning surface. |
| `/mailbox` | Inspo Mailbox | React to stylist suggestions. |
| `/bag` | Bag | View curated collections from the stylist. |
| `/outfits` | Outfits | Browse outfits; open detail. |
| `/lookbooks` | Lookbooks | Browse lookbooks; open viewer. |
| `/photo-booth` | Photo Booth | Virtual try-on (Quick Pick / Inspiration). |
| `/trip-planner` | Trips | Plan trips + packing list. |
| `/style-studio` | Style Studio | Play games (Fling, Clueless Closet, Who Wore It Better). |
| `/havatar` | Avatars | Create and manage avatars. |
| `/settings` | Settings | Profile, vibe, theme, notifications, quick links. |
| `/billing` | Billing | Subscription, tokens, payment methods, invoices. |

Sidebar contains the full menu. A floating action button (FAB) in the corner is customizable with up to five shortcuts.

---

## Chapter: Getting Started

- **Entry**: stylist sends an invite (text or email).
- **Auth paths**: new email/password, existing Hazel-family email/password, or Sign in with Google.
- **Forgot password**: reset link valid for 30 minutes.
- **"Email already exists"**: the email is already in use across the Hazel family (shared SSO). Advise sign-in rather than re-register.
- **Claim page**: if stylist pre-curated items, user sees count of waiting items before claiming.
- **Post-claim**: lands on Wardrobe with pre-curated items highlighted.
- **Billing identity**: the charge line on the user's card reads *HAZELSTYLE MYHAZL.COM*. This is the Hazel family's shared billing — not a mistake.
- **Point users here when**: they can't find how to log in, they received an invite, or they're asking about the email-already-exists error.

## Chapter: Your Avatar

- **Route**: `/havatar`
- **Purpose**: create the digital body double used for try-on rendering.
- **Wizard steps**: photo upload → crop/enhance → AI skin-tone analysis (free, 0 tokens) → manual override if desired → eye/hair/gender/body-shape → save.
- **Duration**: ~2 minutes for a first-time setup.
- **Body shape**: constrained by selected gender.
- **Age safeguard**: under-18 detection blocks creation. Cannot be overridden. AI-based check runs on the reference photo.
- **Multiple avatars**: allowed. One is primary. Relationship types: `self`, `family`, `client`.
- **Sharing**: client can share avatar with stylist (read-only style surface); stylist can share back with the client it represents. Sharing is revocable.
- **QR-pairing flow**: lets the user use their phone as the camera for the reference photo. Pairs persist across sessions via a trust token.
- **Point users here when**: they want to try on outfits but have no avatar, they want to create an avatar for a family member, or they're a stylist wanting to style for a specific client.

## Chapter: Your Wardrobe

- **Route**: `/wardrobe`
- **Purpose**: browse, filter, and search owned items.
- **View modes**: grid or rows. Preference persists per user (server-synced).
- **Filters**: color, occasion, season, weather temperature (with an "include unspecified" toggle), and **feeling**.
- **Search**: synonym-aware (*jean* finds *denim*, *sneaker* finds *trainer*, *tee* finds *T-shirt*).
- **Item detail**: notes, staging history (original / mannequin / lay-flat, all toggleable + restorable), affiliate link if any, preferred-view toggle, feeling tags.
- **Three renders per item**: every wardrobe item has up to three image states — the original uploaded photo, a mannequin render, and a lay-flat render. User sets which is the default across the app (preferred image view in settings).
- **Deletion**: soft-delete; items go to the recycling bin (sidebar footer). Time-bound recovery window: ~30 days on standard plans, ~60 days on Pro. Items hidden from the standard-plan bin between 31–60 days are still physically present — upgrading to Pro brings them back into view if they haven't yet hit the 60-day purge. After 60 days, items are permanently purged and not recoverable. The Recycling Bin page shows the exact retention and flags items expiring soon.
- **New-items welcome**: when the stylist has added pieces since the last visit, the wardrobe greets the user with a carousel of new pieces and a *show me just these* filter shortcut. Dismissible with *No thanks*; badge clears on its own.
- **Point users here when**: they want to find a piece they own, filter their closet by mood/weather/color, see alternate renders of an item, or recover something deleted.

## Chapter: Closet Dashboard

- **Route**: `/closet-dashboard`
- **Purpose**: the panoramic planning surface. Week view is for at-a-glance; Closet Dashboard is for *planning*.
- **What's on it**:
  - **Day carousel** — full week, day-by-day, each with weather theme, high/low, precipitation odds, and the planned outfit (or empty slot).
  - **Hourly temperature curve** — select a day, see the trajectory from morning through evening.
  - **Trip days** use the destination's forecast, not the user's home zip.
  - **Avatar switcher** — flip the dashboard between multiple avatars (self + family).
  - **Calendar events** — imported events sit under each day so outfits map to actual obligations.
- **How users plan**: open a day → see weather + calendar + current outfit → if no outfit, the picker opens inline → move to next day. ~5 minutes for a whole week.
- **Distinction from Week (`/`)**: Week is a compact home view; Closet Dashboard is the deep planner with hourly curves, trip blends, and avatar switching.
- **Point users here when**: they want to plan multiple days at once, they have a trip mid-week and want to see destination weather, or they're managing outfits for more than one avatar.

## Chapter: Adding Clothes

Four intake paths. Each has a distinct use case.

- **Single upload** — one photo at a time. User fills in category, brand, size, occasions. Best for piecemeal additions. Cost: 11 tokens (detect + stage, bundled).
- **Bulk haul** — up to 50 photos at once. Batch review at the end. Best for initial onboarding. Cost: ~11 tokens per item (detection + staging).
- **Live haul** — phone camera as live input streamed to desktop. Paired via QR (6-digit code fallback). Trust-token reconnect across sessions. Voice capture, flash, shutter sfx. Cost: 9 tokens per item (bundled, ~18% cheaper than discrete upload).
- **Chrome extension** — *Hazel's Style — Inspo Capture*. Right-click any image on any retailer. Sends to the **Inspo Mailbox**, not the wardrobe. Stylist-review path.

**Key distinction**: direct uploads go to the wardrobe. Chrome extension goes to the mailbox for stylist review.

**Failed detection handling**: when AI cannot parse a piece (bad lighting, occlusion, challenging angle), the app surfaces a visible error on the item with options to retry with a better photo, fill in manually with no staging, or skip. Never fails silently.

- **Point users here when**: they want to add a new piece, onboard an existing closet, capture something while shopping online, or stream clothes in live.

## Chapter: Inspo Mailbox

- **Route**: `/mailbox`
- **Purpose**: workspace where the stylist sends ideas and the client reacts.
- **Reactions**: love (graduates to wardrobe) / pass (dismissed) / more like this (stays in mailbox as positive signal for stylist).
- **Live updates**: new items appear without a refresh (Socket.IO-backed on the `/mailbox` namespace).
- **Multi-avatar**: a single item can be assigned to multiple avatars; each has per-avatar status (pending, processing, detected, staging, completed, sent).
- **Source labels**: each item shows where it came from (Chrome extension, iPhone, Android, web upload).
- **First-run**: a one-time intro modal explains the mailbox concept.
- **Distinction**: mailbox = ideas. Wardrobe = owned. Bag = curated collection with intent.
- **Point users here when**: they want to see what their stylist has sent, they want to react to suggestions, or they've just installed the Chrome extension and want to verify it lands here.

## Chapter: The Bag

- **Route**: `/bag`
- **Purpose**: a curated themed collection from the stylist (trip capsule, date-night options, seasonal refresh).
- **Polymorphic contents**: clothing items, outfits, and/or lookbooks.
- **Narrative**: has a theme; unlike individual inspo items, a bag is a coherent set.
- **Messaging**: stylist↔client messaging is **not in-bag** — it happens in [The Loom](/loom), one persistent conversation per relationship (Phase 1 cutover, 2026-04-27). A bag can be sent into a Loom thread as a rich card the client can react to in context. Pre-Loom bag chat history was migrated into The Loom and badged *"Imported from old chat."*
- **Pre-claim**: stylists can pre-curate a bag before the client accepts the invite. It's waiting when they claim.
- **Point users here when**: they're asking about a collection their stylist sent, they want to react to a bag's contents inside The Loom, or they want to see a pre-claim collection after first login.

## Chapter: Outfits

- **Route**: `/outfits`
- **Purpose**: named combinations of items. Stylist- or client-built.
- **Hero image**: auto-generated on creation (fire-and-forget); regenerable with style choice (avatar render or neutral mannequin).
- **Cost attribution**: 10 tokens per hero image. Charged to whoever *creates* the outfit. Stylist-built outfits never draw from the client's bucket. Client-built outfits cost the client 10 tokens each.
- **Regenerate modal**: opens a style picker — avatar vs. mannequin, pose options, backdrop options. User can save preferred style as default. Regeneration costs 10 tokens, charged to whoever triggers it.
- **Detail view**: hero, items (with per-item view toggles — mannequin / lay-flat / original), AI styling tips (free, regenerable), notes, affiliate links, inline feelings tag.
- **Feelings tagging**: user can mark intent feelings for an outfit; feeds the Vibe Check model.
- **Point users here when**: they want to see what goes together, they want to regenerate an unflattering hero, or they want to tag how an outfit makes them feel.

## Chapter: Lookbooks

- **Route**: `/lookbooks`
- **Purpose**: curated sets of 2–8 outfits with a shared theme and background — **built by the stylist for the client**. Clients view and share; they don't spend tokens here.
- **Templates**:
  - **Showcase** — polished grid layout.
  - **Magazine** — catalogue-style spread with prices, affiliate links, shopping-trip summary page.
- **Backgrounds (10)**: Parisian Atelier, Boho Corner, Soho Loft, Velvet Lounge, Coastal Retreat, Gentleman's Tailor, Neon Popup, Garden Conservatory, Light Studio, Dark Studio.
- **Sharing**: every lookbook has a public slug URL; recipients don't need an account. Free for the client.
- **Cost to the client**: **zero**. Lookbook creation costs are on the stylist's side (documented in Epic C / D).
- **Point users here when**: they want to browse their capsules, view a specific lookbook, or share one externally.

## Chapter: Virtual Try-On

- **Route**: `/photo-booth`
- **Purpose**: AI renders outfits on the user's avatar.
- **Modes**:
  - **Quick Pick** (15 tokens) — user selects wardrobe items + pose + background + expression → AI render.
  - **Inspiration** (20 tokens) — user uploads a reference photo → AI composes a similar outfit on the user using their wardrobe.
- **Pattern/texture preservation**: prompts preserve original item patterns (stripes, plaid, geometric).
- **Output**: saved to a gallery; can be inserted into a lookbook or shared.
- **Poses available**: standing, walking, candid, sitting, action.
- **Backgrounds available**: studio, street, interior, outdoor.
- **Point users here when**: they want to see themselves in an outfit before wearing/buying, they want to replicate a reference photo on themselves, or they want to build a lookbook from try-on results.

## Chapter: Week & Weather

- **Route**: `/`
- **Purpose**: home view. 7-day weather paired with planned outfits.
- **Desktop**: all seven days visible.
- **Mobile**: 3-day carousel with chunky nav arrows.
- **Day expand**: hourly temperature chart, layering warning when the day has a large temperature swing, outfit tip keyed to weather.
- **Planned outfit**: if a user has planned a specific outfit for a day, it renders on their avatar in that day card. Auto-gen of the planned-day overlay: 20 tokens (same as Photo Booth).
- **Zip code**: set via the weather widget in the header. Required for forecast.
- **Point users here when**: they want to plan tomorrow, they want to see the week, or they haven't set a zip code.

## Chapter: Trips & Packing

- **Route**: `/trip-planner`
- **Purpose**: plan multi-day trips with weather-aware packing lists.
- **Trip fields**: name, date range, destination, optional agenda text.
- **Destination picker**: one destination box, domestic or international. User types a city; after a short pause Hazel looks it up. One match auto-fills; two or more matches show a candidate list (e.g. `Paris, Île-de-France, FR` vs `Paris, Texas, US`) to pick from. State is optional; country comes from the pick. Each pick also captures the destination's time zone, shown as a `(local time)` hint on the trip card when the destination differs from the user's phone time zone.
- **Timeline**: day-by-day view. Sticky month/year headers if the trip crosses months.
- **Packing list**: auto-generated from outfits scoped to the trip.
- **Stylist-set trips**: a stylist may have pre-created a trip on the client's behalf (often paired with a trip-capsule bag). The client can edit it like any other trip.
- **Point users here when**: they're planning a trip, they want a packing list, or they're asking about a trip their stylist set up for them.

## Chapter: Calendar Imports

- **Paths**:
  - **iCal URL** — paste a calendar feed. Modal has step-by-step instructions for Google, Outlook, and Apple.
  - **Sign in with Google** — proxied through the shared Hazel account; reads the calendar directly.
- **Display**: imported events show on Week view and day-detail.
- **Per-avatar scoping**: an import can be tied to one or more avatars, or left unscoped (shows for all). Many-to-many.
- **Refresh**: imports re-sync automatically; stale-time ~5 min on the client.
- **Point users here when**: they want work events on their Week view, they have a family calendar that should show only for specific avatars, or they're asking how to add Google Calendar.

## Chapter: Vibe Check

- **Purpose**: feeling-first dressing. Let the user ask "how do I want to feel?" instead of "what should I wear?"
- **Categories (9)**: Power, Calm, Joy, Elegance, Comfort, Edge, Romance, Professional, **Off** (negatives bucket).
- **Negatives in Off**: Insecure, Weak, Dirty, Uncomfortable, Frumpy, Dull, Disheveled, Stiff.
- **Calibration**: short wizard on first run (~3 minutes); can be revisited any time. User tags feelings on a handful of wardrobe pieces to seed the model.
- **Closet check-in (quarterly recalibration)**: ~every 90 days the app surfaces a closet check-in prompt — a short recalibration pass so the feeling profile stays in sync with wardrobe and life changes. Dismissible; reappears in another 90 days.
- **Surfaces**:
  - Wardrobe Feeling filter (filter by any of the positive categories).
  - Outfit detail inline feelings tagger (mark intent feelings).
  - Feeling lookbooks — auto-generated from observed patterns. Examples: a *Confident* lookbook, a *Comfort* lookbook. Refresh as the wardrobe grows.
  - Pattern insights — surfaces phrases like "you feel *Confident* in leather" or (from Off) "you feel *Dull* in navy workwear." The negative insights are the app's cue to rethink pieces.
- **Adoption curve**: the feeling-first framing takes a session or two to feel natural; once it clicks, it replaces "what should I wear" as the default question.
- **Point users here when**: they don't know what to wear, they want to see what they feel confident in, they want to tag how an outfit makes them feel, or they're curious about the Off/negative-feeling insights.

## Chapter: Style Studio

- **Route**: `/style-studio`
- **Purpose**: playful AI features and mini-games.
- **Games**:
  - **Fling** — real-time wardrobe swap with a friend. Sponsor-funded when offered (free to the client in that case). Both users join a session, shuffle through each other's closets, and build a "possibility pile" from what they'd borrow. End state: overlap view.
  - **Clueless Closet** — retro 90s UI outfit matcher; lands on a match and generates a photo (20 tokens for the matched photo). First roll lands on MIS-MATCH for comedy; second roll finds PERFECT MATCH.
  - **Who Wore It Better** (35 tokens) — stylist-vs-client voting showdown. Both style the same pieces; side-by-side output.
- **Point users here when**: they want something light/fun, they want to interact with a friend, or they're bored and curious.

## Chapter: Shopping

- **Shops**: `/shop/:slug` — branded storefronts per stylist. Public.
- **Actions**: follow, favorite, browse merch, browse outfits, try on (sponsor-funded try-ons sometimes, free to client in that case).
- **Shopping Mode**: a context activated when the user is on a shop page. Adds a sidebar with cart/try-on/save-for-later actions.
- **Checkout**: proxied through Shopify. Payment and fulfillment happen on the shop's Shopify; the client's Hazel's Style account is not charged.
- **Shop Similar**: an AI-powered "find items like this to buy" action on any wardrobe item (5 tokens). Uses Gemini analysis + shopping search.
- **Point users here when**: they want to browse their stylist's shop, they've favorited items they want to revisit, they're mid-shop and asking about checkout, or they want to find shoppable alternatives to a wardrobe piece.

## Chapter: Settings & Personalization

- **Route**: `/settings`
- **Sections**:
  - **Profile** — name, email, picture, zip code.
  - **Vibes** — 6 palettes × light/dark. Changes the entire app UI (sidebar, accents, charts), not just a theme toggle.
  - **Theme** — light / dark / system.
  - **Notifications** — per-category channel preferences (in-app / email / web push).
  - **Quick Links** — customizable FAB shortcuts (max 5).
  - **Preferred image view** — mannequin or lay-flat as default across the app.
  - **Staging decency** — mannequin underlayer preference (white / black / grey / none). Most users pick white or none depending on whether they want styled or isolated renders.
- **In-product tips**: one-time dismissible; persistence is server-side (follows user across devices).
- **Point users here when**: they want to personalize, change the theme or vibe, tune notifications, customize their FAB, or adjust how clothes render on the mannequin.

## Chapter: Notifications

- **Channels (3)**: in-app (bell icon), email, web push (VAPID).
- **Categories**: wardrobe updates, try-on results, shop alerts, campaign updates, fling invites, live-haul invites, token-balance alerts, weekly digest. AI-pipeline categories: staging complete/partial-failure/failed, hero complete, layflat complete.
- **Per-category preferences**: user selects which channels fire per category.
- **Low-token threshold**: user-configurable (default 100); drives the token-low alert.
- **AI-pipeline noise**: granular, can be noisy with everything on. Most users keep them on in-app only.
- **Point users here when**: they're getting too many alerts, they want to know when a specific event triggers a push, or they want to turn on browser push.

## Chapter: Tokens & Billing

- **Route**: `/billing`
- **Model**: subscription includes monthly token allowance; resets each cycle. Tokens fund every AI operation (detection, staging, try-on, photo booth, lookbook generation, outfit hero, week-plan overlay, shop similar, etc.).

### What a token is

- A token is the **unit of AI work** in the app. Roughly one simple AI call = one token; some operations cost more because they chain multiple model calls to produce a better result.
- Tokens are **not** dollars, minutes, or credits. They're an internal unit.
- Users **do not** buy tokens per-action. A monthly allowance is included with their plan and resets each billing cycle, like data on a phone plan.

### Who pays for what

Token attribution is a common point of confusion. The rule:

- **The account that triggers the AI operation pays.** An outfit created by a stylist on their account charges the stylist's bucket; an outfit created by a client on their account charges the client's bucket.
- **Lookbook creation** (Showcase + Magazine) is a stylist/professional action. Clients view and share lookbooks for free.
- **Shop Model Generate / Shop Model Video** are shop-owner actions. See Epic D.
- **Sponsored operations** deduct from a linked professional/campaign budget first, falling back to the user's own balance if the sponsor budget is exhausted. The app always surfaces sponsored state to the user *before* the operation runs.

### Sponsorship UX (portal entry)

When a client enters the app through a professional's portal (a custom link from their stylist, a shared storefront, or a campaign URL), the professional may sponsor some or all of the client's AI operations. The client sees sponsorship state directly on every action button:

- **Full price** — regular cost displayed, e.g. `Try on (15 tokens)`. Client pays from their own balance.
- **Strike-through price** — original cost struck through, actual cost (free or reduced) shown next to it, e.g. `Try on (~~15~~ free)` or `Try on (~~15~~ 5 tokens)`. Professional is sponsoring all or part.

**How to explain this to a client asking about it**:

- "The price you see after the strike-through is what you'll actually be charged."
- "If there's no strike-through, you're paying full price."
- "Your stylist decides what to sponsor and for how long — some cover everything, some only specific features."
- "Pre-flight checks show both your balance and the sponsored amount together, so you won't get surprised at the end."

Professionals can scope sponsorship at the portal level, per feature, or for a specific campaign window. From the client's perspective, the only signal is what the button shows — they don't need to know what the professional's sponsorship rules are, just how to read the strike-through.

### Token cost reference — client-payable operations

Only operations a **client** can trigger on their own account. Stylist-only and shop-owner-only costs are documented in Epics C and D respectively.

| Operation | Tokens |
|---|---:|
| **Intake (adding clothes)** | |
| Single upload (detect + stage, bundled) | 11 |
| Bulk haul (per item, detect + stage) | ~11 |
| Live haul (per item, bundled) | 9 |
| Lay-flat render (per item) | 8 |
| Mannequin + lay-flat bundle (per item) | 12 |
| Skin-tone detection (avatar setup) | 0 |
| **Client-built outfits** | |
| Outfit hero image (when *client* creates the outfit) | 10 |
| Regenerate outfit hero | 10 |
| **Try-On / Photo Booth** | |
| Photo Booth — Quick Pick | 15 |
| Photo Booth — Inspiration | 20 |
| Photo Booth — customizable (pose/expression/bg) | 20 |
| **Week & planning** | |
| Week-plan auto-overlay (planned day on avatar) | 20 |
| **Style Studio (unsponsored)** | |
| Who Wore It Better | 35 |
| Clueless Closet match photo | 20 |
| Claim creator's pre-staged outfit | 0 |
| **Shopping** | |
| Shop Similar | 5 |
| **Horatio's Studio (pose coaching)** | |
| Start session | 10 |
| Pose frame analysis (per frame) | 3 |
| Coaching audio TTS (per clip) | 1 |

**Free for clients**: skin-tone detection, AI styling tips, viewing/sharing lookbooks, background swaps on existing lookbooks, claim staging from a creator, anything sponsored by a stylist or campaign.

### Typical monthly spend (client-side only)

A regular-use client lands in the **300–600 token** range per month in steady state, after the one-time Bulk Haul onboarding. Breakdown of a typical month:

- 10 Quick Pick try-ons: 150 tokens
- 2 Inspiration try-ons: 40 tokens
- 6 Week-plan overlays (busy days only): 120 tokens
- 2 Shop Similar lookups: 10 tokens

Total: ~320 tokens. Add ~275 in the first month for Bulk Haul onboarding.

**What does *not* count toward the client's spend**: outfits the stylist builds, lookbooks the stylist curates, campaign photo content, any try-on sponsored by the stylist's shop. Those costs sit on the stylist's or shop's bucket, not the client's.

### Balance & low-balance behavior

- **Balance display**: sidebar footer (always visible) + `/billing` (detailed).
- **Low-balance banner**: appears when balance drops below user's configurable threshold (default 100).
- **Pre-flight checks**: every AI operation checks balance *before* spending. If insufficient, the app surfaces a modal with a top-up link. Nothing fails silently.
- **Fire-and-forget exception**: background operations (outfit hero auto-gen, haul staging) that run out of tokens mid-run skip gracefully, show a visible status on the affected object, and surface a one-time toast with a billing link.

### Auto-refill

- Optional; off by default. Configurable threshold + pack size at `/billing`.
- Charges payment method automatically when balance drops below the threshold.

### Plan changes

- Preview dialog before any plan change shows: projected balance, proration on current cycle, bonus tokens on new plan, clawback if downgrading, negative-balance warning if change would underwater the account.

### Billing backend

- Hazel Hippo (shared-family account). One subscription spans all Hazel apps; one card charge.
- **Card statement line**: *HAZELSTYLE MYHAZL.COM*. Confusing on first read; it's the shared family billing account.
- Shared balance means tokens unused here aren't lost — they're usable across the Hazel family where tokens are supported.

- **Point users here when**: they want to check balance, change plans, turn on auto-refill, understand why their card shows *HAZELSTYLE MYHAZL.COM*, or they're asking what a token is and what it buys.

---

## How to help a user

1. **Default to the UI.** For most questions, tell the user which page handles the thing and what they'll see. Cite the route and the action.
2. **Use the in-app `?` icon.** The contextual help is page-aware and often more current than this document.
3. **Flag token operations up front with the actual cost.** If an action will consume tokens, tell the user the specific number from the cost table above before they run it. The app does this too — confirmation lowers friction.
4. **Respect the stylist relationship.** For styling direction, the stylist is canonical. Users can escalate via email.
5. **Don't invent features.** If this document doesn't mention a capability, it almost certainly isn't in the product. Redirect to [Settings](/settings) or the stylist.
6. **Quote routes, not paths as code.** Link like `[Wardrobe](/wardrobe)` rather than "go to /wardrobe" in bare text. If the client is in-app, they can click the link.
7. **Use the Vibe Check feeling vocabulary.** When the user asks about how an outfit makes them feel, use the nine-category vocabulary (Power, Calm, Joy, Elegance, Comfort, Edge, Romance, Professional, Off). The app's pattern insights and lookbook grouping are keyed to these categories.

## What this document doesn't cover

- Stylist admin tooling (branding, invites, client CRUD, campaign analytics).
- Developer/repo/contributor concerns.
- Native-mobile-specific UX (haptics, share sheet, push-widget).
- Unreleased or flag-gated features.

---

*Same information as the Full human guide, re-cast for AI context. Served publicly at `/llms.txt`. Last updated 2026-05-24.*