@gymmymac/bob-widget 3.1.10 → 3.1.20

package/BOB-DOCUMENTATION.md

@@ -1,6 +1,6 @@
 # Bob Widget - Complete Documentation
 
-> **Version:** 3.1.10 | **Last Updated:** January 2025
+> **Version:** 3.1.19 | **Last Updated:** February 2026
 
 AI-powered automotive parts assistant widget for seamless integration into partner websites.
 
@@ -26,11 +26,12 @@ AI-powered automotive parts assistant widget for seamless integration into partn
 
 Bob is a friendly Kiwi auto parts expert that helps customers find the right parts for their vehicles through natural conversation. The widget is designed as a **"black box"** that auto-configures from the database—partners only need to provide a partner code.
 
-### Key Features (v3.1.10)
+### Key Features (v3.1.19)
 
 | Feature | Description |
 |---------|-------------|
 | **CLI Installer** | 3-stage installation via `npx @gymmymac/bob-widget carfix stage-a\|b\|c` |
+| **`--with-layout` Flag** | Stage B can generate CARFIX Header (72px) and BottomNav (72px) components |
 | **BobStandalone** | Auto-configures from database - 4 lines to integrate |
 | **No Hardcoded Blur** | Background uses CSS variable `--bob-blur-intensity` (default: 0) |
 | **Partner Config System** | All settings stored in `bob_partners` table |
@@ -733,6 +734,35 @@ Before proceeding to Stage B, confirm:
 
 Create the blank page that will host Bob. **Do NOT import Bob yet** - that happens in Stage C.
 
+#### CARFIX Layout Components (Required)
+
+Before creating the Bob container, ensure your CARFIX application has:
+
+1. **Fixed Header (72px)** - Fixed to top of viewport
+2. **Fixed Bottom Navigation (72px)** - Fixed to bottom of viewport
+
+**If these elements do NOT exist**, you must create them first. The 144px height offset
+in the container formula ASSUMES both elements are present.
+
+##### Option A: Use Existing Layout
+
+If your CARFIX app already has a header and bottom nav, confirm their heights:
+- Header: Must be exactly 72px
+- Bottom Nav: Must be exactly 72px (plus safe-area-inset-bottom on mobile)
+
+##### Option B: Generate Layout Components
+
+Run Stage B with the `--with-layout` flag to generate placeholder components:
+
+```bash
+npx @gymmymac/bob-widget carfix stage-b --target next-pages --with-layout
+```
+
+This generates:
+- `components/CarfixHeader.tsx` (72px header)
+- `components/CarfixBottomNav.tsx` (72px bottom nav)
+- `pages/ask-bob.tsx` (complete page with layout)
+
 #### Requirements
 
 1. Page must use the standard CARFIX layout (Header + Bottom Navigation)

package/CHANGELOG.md

@@ -5,6 +5,114 @@ All notable changes to the `@gymmymac/bob-widget` package will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.20] - 2026-02-13
+
+### Added
+- 📦 **CARFIX Installation Brief**: README.md now serves as the comprehensive installation document with full container preparation requirements, anti-patterns table, pre-mount checklist, and layout diagram
+- 🧪 **Quality Baseline Tests**: 36 unit tests locked in across rear brake filter, bundle discount pricing, and callback stability
+- 💰 **Bundle Discount Display**: Was/Now pricing with savings badges for service package tiers when `savingsAmount > 0`
+- 🛒 **Bundle Cart Metadata**: Cart items from service packages now include `is_bundle_item`, `bundle_discount_percentage`, `service_package_name`, and `quality_tier`
+
+### Changed
+- 📖 **README Overhaul**: Full installation brief is now front-and-center — visible on npm, GitHub, and in `node_modules`
+- 📐 **Container Anti-Patterns**: Documented all prohibited CSS properties (`overflow: hidden`, `transform`, etc.) that break Bob's layering
+
+---
+
+## [3.1.19] - 2026-02-04
+
+### Added
+- 🚗 **Vehicle Variant Deduplication**: Smart filtering removes duplicate vehicle variants based on parts-relevant specs (fuel type, engine capacity, power output) rather than superficial trim differences
+- 🗣️ **REGO Terminology Alignment**: Bob now treats "registration", "rego", "plate", and "number plate" identically
+
+### Fixed
+- 🔢 **Speech Count Alignment**: Bob's spoken variant count now matches the deduplicated UI cards shown on screen
+- 🎴 **Variant Card Display**: Cards now show specs-first format without characterization text
+
+### Documentation
+- 📝 **bottomOffset Clarification**: `bottomOffset` prop only applies to fixed-position variants. Contained/embedded variants position relative to their container (which should already be sized to fit between header/footer).
+
+---
+
+## [3.1.18] - 2026-01-28
+
+### Changed
+- 🗣️ **Language Consistency**: Replaced all "CFX" references with "CARFIX" in:
+  - Database prompts (sales_flow)
+  - Edge function tool descriptions
+  - Service package descriptions in carfix-tokens.ts
+- 💬 **Bob's Recommendations**: Bob now verbally recommends "CARFIX Value" tier (was "Standard")
+- 🎨 **Button Styling**: 
+  - CARFIX Value tier: Solid green (#22C55E) button with white text
+  - Other tiers: Light background with green text
+  - Removed cart icons from all Add buttons
+- 🏷️ **Badge Update**: "RECOMMENDED" pill renamed to "CARFIX VALUE"
+
+---
+
+## [3.1.17] - 2026-01-28
+
+### Changed
+- 🏷️ **Shelf Header**: Replaced "Bob's Shelf" with vehicle make/model (e.g., "Toyota RAV4")
+- 🗑️ **Service Packs Label**: Removed "CFX SERVICE PACKS" row to reclaim vertical space
+- 🎨 **Recommended Badge**: Changed green "Recommended" pill to blue "Carfix Value" 
+- 🛒 **Add Buttons**: Removed cart icons, centered button text
+- 🔘 **Chevron Handle**: Larger handle button (32px) positioned higher (-24px) to prevent clipping
+- 📐 **Chat Height**: Increased collapsed drawer from 90px to 110px for PTT button visibility
+
+---
+
+## [3.1.16] - 2026-01-28
+
+## [3.1.15] - 2026-01-28
+
+### Fixed
+- 🗣️ **State Terminology**: Default animation states updated to match V2 Bob:
+  - "talking" (was "talk")
+  - "researching" (was "research")
+  - "listening" (was "talk_pause")
+  - "idle" for complete state (was "complete")
+- 📐 **Chat Drawer Position**: Chat drawer now positioned at `bottom: 0` to sit below the counter overlay visually
+- 🖼️ **Counter Stretching**: Counter overlay now uses `object-fit: fill` to stretch to configured height
+- 📏 **Chat Height**: Increased collapsed chat drawer height from 70px to 90px
+
+---
+
+## [3.1.14] - 2026-01-28
+
+### Fixed
+- 📐 **ContainedChatDrawer Positioning**: Removed incorrect `bottomOffset` addition - container already accounts for host UI
+- 🎨 **Chat Drawer Height**: Chat drawer now correctly positions at `counterHeightPercent%` from container bottom
+- 📝 **Counter Overlay**: Single counter display verified (backdrop + overlay are separate layers)
+
+---
+
+## [3.1.13] - 2026-01-28
+
+### Fixed
+- 📐 **Chat Drawer Positioning**: Chat drawer now positions above counter overlay using `counterHeightPercent`
+- 🎨 **Visual Alignment**: Chat input and PTT button no longer overlap with counter graphic
+
+---
+
+## [3.1.12] - 2026-01-28
+
+### Fixed
+- 🎨 **Chat Drawer Z-Index**: Raised chat drawer z-index above counter overlay (z-80) to ensure visibility
+- 🎤 **PTT Button Layering**: Elevated PTT button and handle button z-index for proper layer hierarchy
+
+---
+
+## [3.1.11] - 2026-01-28
+
+### Added
+- 📐 **Stage B `--with-layout` Flag**: New CLI option generates CARFIX Header (72px) and Bottom Navigation (72px) components
+- 📖 **CARFIX Layout Components Section**: Documentation now explicitly provides Header and BottomNav code templates
+- 🧪 **Demo Route `/ask-bob`**: Added test route to demo repo with mock CARFIX layout for accurate local testing
+
+### Fixed
+- 📖 **Stage B Instructions**: Now include explicit layout component requirements instead of assuming they exist
+
 ## [3.1.10] - 2026-01-28
 
 ### Added

package/README.md

@@ -1,14 +1,14 @@
 # @gymmymac/bob-widget
 
-AI-powered automotive parts assistant widget for integration into partner websites.
+AI-powered automotive parts assistant widget for partner websites.
 
-**Current Version:** 3.1.10
+**Current Version:** 3.1.20 | **36 unit tests** | **8+ E2E scenarios** | Production-ready
 
 ---
 
-## 🚨 STOP - RUN THE INSTALLER FIRST
+## 🚨 STOP — RUN THE INSTALLER FIRST
 
-Bob v3.1.10 includes an **executable 3-stage installer**. Do NOT skip this step.
+Bob v3.1.19 includes an **executable 3-stage installer**. Do NOT skip this step.
 
 ```bash
 # Stage A: Forensic Scan & Purge (removes old Bob code)
@@ -21,62 +21,460 @@ npx @gymmymac/bob-widget carfix stage-b --target next-pages --output pages/ask-b
 npx @gymmymac/bob-widget carfix stage-c --partner CARFIX
 ```
 
-### 📖 Required Reading
+---
 
-| Document | Description |
-|----------|-------------|
-| **[BOB-DOCUMENTATION.md](./BOB-DOCUMENTATION.md)** | **Complete integration guide** - Contains CARFIX-specific installation steps, container height calculations, and verification tests. **START HERE.** |
-| **[CHANGELOG.md](./CHANGELOG.md)** | Version history and release notes |
-| **[install/carfix/](./install/carfix/)** | Installer scripts and templates |
+## 1. Peer Dependencies
 
-### ⚠️ Critical Installation Notes
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  }
+}
+```
 
-1. **3-Stage Installation Process**: Bob v3.1.10 requires a strict 3-stage installation via CLI. See the commands above.
-2. **Container Height**: Bob requires `height: calc(100dvh - 144px - env(safe-area-inset-bottom, 0px))` for CARFIX header/footer
-3. **HTTPS Required**: Push-to-Talk (PTT) requires HTTPS - will be disabled on HTTP connections
-4. **No Background Blur**: v3.1.10 removes hardcoded blur - background is crisp by default
+> `@supabase/supabase-js` and `@tanstack/react-query` are bundled — no action needed.  
+> If CARFIX already uses `@tanstack/react-query`, ensure v5+ compatibility.
 
 ---
 
-## Quick Start
-
-After completing the 3-stage installation:
+## 2. Minimal Integration (4 Lines)
 
 ```tsx
 import { BobStandalone } from '@gymmymac/bob-widget';
 
-<BobStandalone
-  partner="CARFIX"
-  sessionToken={sessionToken}
-  onAddToCart={(item) => addToCart(item)}
-  onNavigate={(url) => router.push(url)}
-  onCheckout={(url) => window.location.href = url}
-/>
+function AskBobPage() {
+  const router = useRouter();
+  const sessionToken = router.query.session as string;
+
+  return (
+    <div style={{
+      height: 'calc(100dvh - 144px - env(safe-area-inset-bottom, 0px))',
+      position: 'relative',
+      /* DO NOT use overflow: hidden — clips PTT button and chat drawer */
+    }}>
+      <BobStandalone
+        partner="CARFIX"
+        sessionToken={sessionToken}
+        bottomOffset={0}
+        zIndexBase={100}
+        onAddToCart={async (item) => await carfixCart.add(item)}
+        onNavigate={(url) => router.push(url)}
+        onCheckout={(checkoutUrl) => window.location.href = checkoutUrl}
+        onError={(error) => console.error('[Bob Error]', error)}
+      />
+    </div>
+  );
+}
+```
+
+> **Auto-configuration:** `partner="CARFIX"` loads all API URLs, credentials, layout defaults, and feature flags from the `bob_partners` database table. No manual config needed.
+
+---
+
+## 3. CARFIX API Configuration (Already in Database)
+
+```json
+{
+  "baseUrl": "https://flpzjbasdsfwoeruyxgp.supabase.co/functions/v1",
+  "apiKey": "(anon key — auto-loaded)",
+  "partnerCode": "CARFIX"
+}
+```
+
+### Available Endpoints
+
+| Endpoint | Purpose |
+|---|---|
+| `partner-api` | Session creation, cart, user context, orders |
+| `calculate-service-bundles` | Service packs with `preparedTiers[]` (incl. bundle discounts) |
+| `retrieve-vehicle-info` | NZ rego lookup |
+| `retrieve-parts` | Vehicle parts by category |
+
+---
+
+## 4. Host Container Preparation (MANDATORY)
+
+> ⚠️ **Bob will not render correctly if the host container is misconfigured.** Complete ALL items below before mounting `<BobStandalone>`.
+
+### 4.1 Container Requirements
+
+The CARFIX page that hosts Bob **must** provide a container element with these exact properties:
+
+```css
+/* The Bob container — EVERY property is required */
+.bob-container {
+  height: calc(100dvh - 144px - env(safe-area-inset-bottom, 0px));
+  position: relative;
+  width: 100%;
+
+  /* ❌ PROHIBITED — these WILL break Bob */
+  /* overflow: hidden;    ← Clips PTT button, chat drawer, and expand handle */
+  /* overflow: clip;      ← Same issue on WebKit */
+  /* overflow: auto;      ← Creates nested scroll context, breaks shelf scrolling */
+  /* overflow: scroll;    ← Same as above */
+  /* transform: ...;      ← Creates new stacking context, breaks z-index layering */
+}
+```
+
+```tsx
+// ✅ Correct JSX
+<div style={{
+  height: 'calc(100dvh - 144px - env(safe-area-inset-bottom, 0px))',
+  position: 'relative',
+  width: '100%',
+}}>
+  <BobStandalone partner="CARFIX" ... />
+</div>
+
+// ❌ WRONG — overflow hidden clips Bob's interactive elements
+<div style={{ height: '100%', overflow: 'hidden' }}>
+  <BobStandalone partner="CARFIX" ... />
+</div>
+```
+
+### 4.2 Height Calculation Breakdown
+
+| Component | Height | Notes |
+|---|---|---|
+| CARFIX Header | 72px | `position: fixed; top: 0; z-index: 40` |
+| CARFIX Bottom Nav | 72px | `position: fixed; bottom: 0; z-index: 30` |
+| **Total chrome** | **144px** | Subtracted from viewport |
+| Safe area inset | Variable | For notched devices (iPhone, etc.) |
+| **Bob container** | `100dvh - 144px - safe-area` | Everything between header and nav |
+
+### 4.3 Header & Bottom Nav Requirements
+
+Bob's UI layers (chat drawer at z-130, PTT at z-145) must sit **above** CARFIX navigation:
+
+```css
+/* CARFIX Header */
+.carfix-header {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 72px;
+  z-index: 40;    /* Bob uses zIndexBase=100, so Bob layers above this */
+}
+
+/* CARFIX Bottom Nav */
+.carfix-bottom-nav {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 72px;
+  z-index: 30;    /* Must be BELOW Bob's z-base of 100 */
+}
+```
+
+> **If your header or nav use `z-index: 50` or higher**, increase Bob's `zIndexBase` prop accordingly (e.g., `zIndexBase={150}`).
+
+### 4.4 Container Anti-Patterns (WILL CAUSE BUGS)
+
+| ❌ Don't Do This | Why It Breaks |
+|---|---|
+| `overflow: hidden` on container | Clips PTT button, chat drawer, and expand handle |
+| `overflow: auto/scroll` on container | Creates nested scroll context — product shelf scroll breaks |
+| `transform` on container or ancestors | Creates new stacking context — z-index layering fails |
+| `isolation: isolate` on container | Same stacking context issue (Bob manages its own isolation) |
+| Container height as `%` without parent height | Bob collapses to 0px |
+| Missing `position: relative` | Absolutely-positioned Bob layers escape the container |
+| Wrapping Bob in a scrollable parent | Bob has its own scroll management — nesting causes conflicts |
+
+### 4.5 Pre-Mount Checklist
+
+Before writing any integration code, verify:
+
+```
+□ Header is position: fixed, 72px tall, z-index ≤ 49
+□ Bottom nav is position: fixed, 72px tall, z-index ≤ 49
+□ Bob container uses calc(100dvh - 144px - env(safe-area-inset-bottom, 0px))
+□ Bob container has position: relative
+□ Bob container has NO overflow property set
+□ Bob container has NO transform property set
+□ No ancestor element between <body> and Bob container has overflow: hidden
+□ No ancestor element has a transform that creates a stacking context
+□ Container renders at correct height (inspect element in DevTools)
+□ HTTPS is enabled (required for Push-to-Talk microphone access)
+```
+
+---
+
+### 4.6 Layout Diagram
+
+```
+┌──────────────────────────────┐
+│  CARFIX Header (72px, z-40)  │  ← position: fixed; top: 0
+├──────────────────────────────┤
+│                              │
+│  Bob Container               │  ← position: relative
+│  height: calc(100dvh - 144px │     NO overflow property
+│          - safe-area-inset)  │     NO transform property
+│                              │
+│  ┌─ Bob Internal Layers ───┐ │
+│  │ PTT Button      z-145   │ │
+│  │ Chat Drawer     z-130   │ │
+│  │ Counter Overlay z-70    │ │
+│  │ Bob Character   z-60    │ │
+│  │ Product Shelf   z-55    │ │
+│  │ Backdrop        z-10    │ │
+│  └─────────────────────────┘ │
+│                              │
+├──────────────────────────────┤
+│  Bottom Nav (72px, z-30)     │  ← position: fixed; bottom: 0
+└──────────────────────────────┘
+```
+
+**Bob's internal z-index stack (relative to `zIndexBase={100}`):**
+
+| Layer | z-index |
+|---|---|
+| Chat PTT Button | 145 |
+| Chat Drawer | 130 |
+| Counter Overlay | 70 |
+| Bob Character | 60 |
+| Product Shelf | 55 |
+| Backdrop | 10 |
+
+---
+
+## 5. Callback Signatures
+
+### onAddToCart
+
+```typescript
+onAddToCart: (item: {
+  product_id: string;
+  product_name: string;
+  quantity: number;
+  unit_price: number;       // Final price (discount already applied for bundle items)
+  sku?: string;
+  brand?: string;
+  image_url?: string;
+  vehicle_id?: string;
+  // Bundle metadata (present when item is part of a service package)
+  is_bundle_item?: boolean;
+  bundle_discount_percentage?: number;
+  service_package_name?: string;
+  service_package_id?: string;
+  quality_tier?: string;    // "Economy" | "Standard" | "Premium" | "Performance"
+}) => Promise<void> | void;
+```
+
+### onNavigate
+
+```typescript
+onNavigate: (url: string) => void;
+// Example urls: "/product/SKU123", "/checkout"
+```
+
+### onCheckout
+
+```typescript
+onCheckout: (checkoutUrl: string) => void;
+// checkoutUrl is a full Stripe payment URL
+```
+
+### onError
+
+```typescript
+onError: (error: Error) => void;
+// Bob shows toast by default — this is for host-side logging
+```
+
+---
+
+## 6. Bundle Discount Fields (NEW)
+
+The `calculate-service-bundles` API returns these fields per `PreparedTier`:
+
+```typescript
+interface PreparedTier {
+  tierName: string;              // "Economy" | "Standard" | "Premium" | "Performance"
+  displayName: string;
+  description: string;
+  isRecommended: boolean;        // true = CARFIX Value tier
+  isHidden: boolean;             // true = filter out (duplicate price)
+
+  // Pricing (pre-calculated by API — never recompute)
+  totalPrice: number;            // Discounted bundle price
+  originalTotalPrice?: number;   // Full price before discount
+  savingsAmount?: number;        // Dollar savings
+  bundleDiscountPercentage?: number; // Discount % (0–50)
+
+  productCount: number;
+  dominantBrand: string | null;
+  brands: PreparedTierBrand[];
+  products: PreparedTierProduct[];
+}
+
+interface PreparedTierProduct {
+  partslotId: number;
+  partslotName: string;          // "BRAKE PADS FRONT"
+  sku: string;
+  name: string;
+  brand: string;
+  brandFullName: string;
+  brandImageUrl: string;         // Full URL — use directly in <img>
+  productImageUrl: string;       // Full URL — use directly in <img>
+  price: number;                 // Legacy unit price
+  unitPrice: number;             // Per-unit price
+  displayPrice: number;          // Total (unitPrice × perCarQty) — USE THIS
+  isRotor: boolean;              // Show "[Pair]" badge
+  isMultiQty: boolean;           // Show quantity breakdown (e.g. spark plugs)
+  perCarQty: number;
+  partNumber: string | null;
+  webDescription: string | null;
+  viscosity: string | null;
+  volume: number | null;
+}
+
+interface PreparedTierBrand {
+  name: string;
+  fullName: string;
+  imageUrl: string;              // Full URL
+}
+```
+
+### Rendering Rules
+
+1. **Filter hidden tiers:** `preparedTiers.filter(t => !t.isHidden)`
+2. **When `savingsAmount > 0`:** Show ~~$originalTotalPrice~~ → **$totalPrice** + "SAVE $XX — X% Bundle Deal"
+3. **When `savingsAmount === 0`:** Show `totalPrice` normally, no discount UI
+4. **Use `displayPrice`** for individual products (already includes quantity)
+5. **Never calculate prices client-side** — all values arrive pre-calculated
+
+---
+
+## 7. Session Handoff (Pre-authenticated Users)
+
+```
+1. CARFIX calls partner-api: { action: "create_session", vehicle_id: 42899 }
+   → vehicle_id MUST be a NUMBER (not string)
+   → Returns: { session_token: "abc123..." }
+
+2. Redirect to: /ask-bob?session=abc123...
+
+3. BobStandalone reads sessionToken → resolves vehicle + customer context
+```
+
+> **Critical:** `vehicle_id` must be numeric throughout the pipeline. String values cause silent API failures.
+
+---
+
+## 8. Design Tokens
+
+Exported from the package for use on CARFIX pages that mirror Bob's styling:
+
+```typescript
+import {
+  CARFIX_COLORS,
+  QUALITY_TIER_CONFIG,
+  IMAGE_URLS,
+  BADGE_CONFIG,
+  TYPOGRAPHY,
+  isRotorProduct,
+  getDisplayPrice,
+  formatNZD,
+} from '@gymmymac/bob-widget';
 ```
 
-**That's it!** Bob auto-configures from the database.
+### Key Colors
+
+| Token | Value | Usage |
+|---|---|---|
+| `primary` | `#0052CC` | Standard tier, CTAs, CARFIX Value |
+| `secondary` | `#38BDF8` | Accents, links |
+| `accent` | `#FF8C00` | Premium tier |
+| `success` | `#22C55E` | "Fits Vehicle" badges, Add to Cart |
+| `destructive` | `#EF4444` | Performance tier |
+
+### Tier Visual Config
+
+| Tier | Color | Background | Badge |
+|---|---|---|---|
+| Economy | `#475569` | `#F1F5F9` | 💰 |
+| Standard | `#0052CC` | `rgba(0,82,204,0.1)` | ⭐ CARFIX Value |
+| Premium | `#D97706` | `#FEF3C7` | 🏆 |
+| Performance | `#DC2626` | `#FEE2E2` | ⚡ |
 
 ---
 
-## What's New in v3.1.10
+## 9. Exported Types (Full List)
+
+```typescript
+// Components
+export { BobStandalone } from '@gymmymac/bob-widget';
+export type { StandaloneWidgetProps } from '@gymmymac/bob-widget';
 
-- 🛠️ **Executable CLI Installer**: Run `npx @gymmymac/bob-widget carfix stage-a|b|c`
-- 🎨 **Fixed Visual Issues**: Removed hardcoded blur, fixed Bob positioning/scale
-- 📦 **Full Package Distribution**: CLI, install scripts, and docs shipped in npm
-- 🔧 **Embedded Mode Default**: BobStandalone now uses `inline` variant (container-respecting)
-- 🔒 **Auth Isolation**: Unique storage keys prevent host-site auth collisions
+// Types
+export type {
+  HostContext, HostUserContext, HostVehicleContext, HostCartContext,
+  BobConfig, HostApiConfig, BobCallbacks, BobProviderConfig, BobLayoutConfig,
+  Product, CartItem, ServicePackage, PreparedTier, PreparedTierProduct, PreparedTierBrand,
+  Partslot, QualityTiers, Part,
+  PartnerConfig, PartnerFeatureFlags, EssentialCallbacks,
+  Vehicle, Message, HighlightedProduct,
+  BobAnalyticsEvent, BobGA4Config,
+} from '@gymmymac/bob-widget';
+```
 
-## Dependencies
+---
 
-Only requires:
-- `react` ^18.0.0
-- `react-dom` ^18.0.0
+## 10. Post-Install Verification Checklist
+
+```
+□ npm install completes without peer dependency warnings
+□ BobStandalone renders loading spinner, then Bob appears
+□ Bob character sits between header (72px) and bottom nav (72px)
+□ Chat drawer opens above bottom navigation (z-index check)
+□ PTT button is visible and not clipped
+□ Vehicle lookup works (try rego: HZP550)
+□ Service packages appear with tier cards
+□ Bundle discount shows Was/Now pricing where applicable
+□ "Add to Cart" callback fires with correct item shape
+□ Session handoff works (pass ?session=TOKEN)
+□ No console errors (filter for [Bob)
+□ Mobile: safe-area-inset respected on notched devices
+```
 
-All other dependencies are bundled.
+---
+
+## 11. Test Baseline
+
+Bob ships with **36 unit tests** and **8+ E2E scenarios** covering:
+
+- Callback mapping and stability
+- Tier validation and empty states
+- Rear Brake Disc/Drum filter logic
+- Bundle discount display and cart pricing
+- Vehicle lookup flow
+- Service package rendering
+
+Run locally: `cd packages/bob-widget && npx vitest run`
+
+---
+
+## 📖 Additional Documentation
+
+| Document | Description |
+|----------|-------------|
+| **[BOB-DOCUMENTATION.md](./BOB-DOCUMENTATION.md)** | Complete integration guide with troubleshooting |
+| **[CHANGELOG.md](./CHANGELOG.md)** | Version history and release notes |
+| **[install/carfix/](./install/carfix/)** | Installer scripts, templates, and verification checklists |
+
+---
 
 ## Support
 
-For integration issues, check the troubleshooting section in [BOB-DOCUMENTATION.md](./BOB-DOCUMENTATION.md#9-troubleshooting).
+For integration issues, the Bob team needs:
+1. Browser console output (filter for `[Bob`)
+2. Network tab showing failed API calls
+3. Screenshot of layout issue
+4. Device / browser / viewport info
 
 ## License