From c9b65c3def8cbd21b4d582360a9ec47585a932df Mon Sep 17 00:00:00 2001
From: bwnyasse <5323628+bwnyasse@users.noreply.github.com>
Date: Tue, 3 Feb 2026 15:01:58 -0500
Subject: [PATCH] docs: add m3 demo documentation

This commit adds two new markdown files:

- `demos/m3-notes.md`: This file contains notes and feedback
 from the M3 demo.
- `demos/m3.md`: This file contains the feature demo plan for
 Milestone 3 of the KROW Workforce Platform. It includes
 information on the demo overview, environment setup, demo flows,
 and customer handover checklist.
---
 demos/m3-notes.md |  60 ++++++++
 demos/m3.md       | 356 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 416 insertions(+)
 create mode 100644 demos/m3-notes.md
 create mode 100644 demos/m3.md

diff --git a/demos/m3-notes.md b/demos/m3-notes.md
new file mode 100644
index 00000000..a9a7a265
--- /dev/null
+++ b/demos/m3-notes.md
@@ -0,0 +1,60 @@
+# KROW M3 Demo — Test Feedback
+
+**Date:** February 3, 2026
+
+---
+
+## Demo 1: Register Business & Show Empty States (Client App)
+
+- **Flickering company name:** Every time I navigate to the home screen, I see "your company" for a moment before it changes to the real name.
+- Creating a One-Time Order shows "No Vendors Available" — this is expected, OK.
+
+---
+
+## Demo 2: Register Staff & Show Empty States (Staff App)
+
+**Onboarding — Add preferred work locations:**
+- Suggestion: Use Google Maps to suggest only city names. Currently users can type anything, which will cause misspellings and inconsistent data. Important for the max distance feature.
+
+**Home page:**
+- Same flickering issue — shows "Krower" briefly before displaying the real name.
+
+**Profile page:**
+- Phone number should be read-only, or require re-verification if changed.
+- Emergency contact: "Save & Continue" works, but shouldn't we navigate to the profile page after? Other flows do this.
+- Tax Documents: Would be great to add a file uploader where our AI could identify documents and prefill fields.
+- Bank Account: Need to plan real bank verification (KYC)? Ensure the account is real and belongs to the user. Also, I can list banks but I don't see how to change/switch bank.
+
+**Home (empty state):**
+- Clicking "Find shifts →" does nothing. But "Find Shifts" with the search icon works.
+
+**My Availability:**
+- Working. Some latency, but OK for now.
+
+---
+
+## Demo 5: Client Creates a New Hub
+
+- Hub editing feature seems missing — we'll need this for NFC configuration later.
+- No confirmation before deleting a hub.
+
+---
+
+## Demo 6: Client Creates New Order
+
+- "Up Next (x)" counter is confusing. I created 2 orders but it shows "Up Next (1)". Sometimes shows 0 when navigating, then back to 1.
+
+---
+
+## Demo 8: Staff Logs In with Existing Account
+
+- If you accidentally click "Sign Up" with an existing phone number, you get stuck:
+  1. OTP screen shows error: "This user already has a staff profile. Please log in"
+  2. Clicking back → login → same OTP error loop
+  3. Only fix: kill and restart the app
+
+---
+
+## Demo 10: Staff Browses Available Shifts
+
+- **Blocker:** I don't see the shift I created as the Client.
\ No newline at end of file
diff --git a/demos/m3.md b/demos/m3.md
new file mode 100644
index 00000000..329549cd
--- /dev/null
+++ b/demos/m3.md
@@ -0,0 +1,356 @@
+# KROW Workforce Platform — Feature Demo Plan for Milestone 3
+
+**Version:** Milestone 3 (v3.0)  
+**Date:** February 3, 2026  
+**Audience:** Business Stakeholders, Customer Engineers, Sales Teams  
+**Duration:** 25-30 minutes
+
+---
+
+## 1️⃣ Demo Overview
+
+### Purpose
+
+This demo showcases the progress of the milestone 3.
+
+- **For Businesses (Client App):** One-time shift creation, worker management, real-time coverage tracking
+- **For Workers (Staff App):** Easy access to available shifts, clock-in and profile management
+- **Complete Workflow:** From shift posting and worker check-in and completion
+
+### Estimated Demo Duration
+
+**25-30 minutes**
+
+---
+
+## 2️⃣ Demo Environment Setup
+
+### Required Test Accounts
+
+**Client Account (Business User):**
+- Email: `legendary@krowd.com`
+- Password: `Demo2026!`
+- Client Name: "Krow"
+
+**Staff Account (Worker):**
+- Phone: `+15557654321`
+- OTP Code: `123456` (demo mode)
+- Name: "Mariana Torres"
+
+### Prerequisites
+1. ✅ Both apps installed on demo devices (or simulators)
+2. ✅ Network connection stable
+3. ✅ Seed data is ready to be populated (the database should be empty at start)
+
+### Make Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `make dataconnect-clean` | Clean the database before seeding |
+| `make dataconnect-seed` | Populate the database with seed data for demo |
+
+### Recent Fixes Applied
+- ✅ Fixed 2 bugs on TaxForm: marital status and Citizenship Status now properly saved
+- ✅ Fixed update screen after create or update TaxForm
+- ✅ Created seed data script
+- ✅ Created make commands to create and delete information in DataConnect
+
+---
+
+## 3️⃣ Demo Flows
+
+### Demo 0: Show Empty Database
+**Purpose:** Demonstrate the starting point before any data exists
+
+**Steps:**
+1. Run `make dataconnect-clean` to ensure database is empty
+2. Show the empty database in Firebase console
+
+---
+
+### Demo 1: Register Business & Show Empty States (Client App)
+**Purpose:** Show the client onboarding experience and empty states
+
+**Steps:**
+1. Open Client App → Tap "Create Account"
+2. Enter business email, and password
+3. Navigate to home page
+4. **Point out:** Empty dashboard, no orders, no workers, clean slate
+
+---
+
+### Demo 2: Register Staff & Show Empty States (Staff App)
+**Purpose:** Show the worker onboarding experience and empty states
+
+**Steps:**
+1. Open Staff App → Tap "Sign Up"
+2. Enter phone number and verify with OTP code
+3. Follow the onboarding process
+4. Navigate to home page
+5. **Point out:** Empty shifts list, no available work yet
+
+---
+
+### 🔄 PAUSE: Populate Database
+
+Run the seeding command:
+```bash
+make dataconnect-seed
+```
+
+---
+
+### Demo 3: Client Logs In with Existing Account
+**Purpose:** Show the sign-in experience for returning users
+
+**Screen:** Get Started → Sign In
+
+**Steps:**
+1. Restart Client App
+2. Tap "Sign In" button
+3. Enter credentials:
+   - Email: `legendary@krowd.com`
+   - Password: `Demo2026!`
+4. Tap "Sign In"
+
+---
+
+### Demo 4: Client Views Populated Dashboard
+**Purpose:** Show how the client app displays active operations
+
+**Steps:**
+1. After signing in, observe the home screen
+2. Navigate through populated sections:
+   - Home: Coverage stats, upcoming shifts
+   - Orders: Posted shifts with workers assigned
+   - Coverage: Real-time worker status
+
+**What to Notice:**
+- Coverage percentage for today's shifts
+- Workers checked in vs. needed
+- Late workers alerts
+- Today's estimated labor cost
+
+---
+
+### Demo 5: Client Creates a New Hub
+**Screen:** Hubs Tab → "Add Hub" button
+
+**Steps:**
+1. Navigate to Hubs tab in bottom navigation
+2. Tap the "+" or "Add Hub" button
+3. Fill in hub details:
+   - Hub name: "Downtown Convention Center"
+   - Address: Start typing and select from Google Places autocomplete
+4. Tap "Create Hub"
+5. See the new hub appear in the hubs list
+
+---
+
+### 📋 Main Demo Flow Explanation
+
+```
+Client Posts Shift [O1]
+    ↓
+*Vendor Accepts the Shift (Missing for now) / Vendor is selected by client* [O2] 
+    ↓
+Worker Searches for a Shift [O3]
+    ↓
+Worker Applies [O4]
+    ↓
+Confirmation (Missing for now, auto-confirmed)* [O5] 
+    ↓
+Worker Checks In [O6]
+    ↓
+Shift Completed [O7]
+```
+
+---
+
+### Demo 6: Client Creates New Order - [O1]
+**Purpose:** Walk through the shift creation process
+
+**Screen:** Orders Tab → "Post" button
+
+**What to Fill:**
+- Order name: "Spring Gala 2026"
+- Date: [Select upcoming date]
+- Location: [Select existing hub]
+- Add position: Server, Count: 3, Hours: 5PM-9PM
+
+---
+
+### Demo 7: Client Views Order Details
+**Purpose:** Show detailed shift information and worker assignments (second part is missing for now)
+
+**Screen:** Orders Tab → Tap on any order card
+
+**What to Notice:**
+- Event name and location
+- Roles needed (e.g., "2 Servers")
+- Clock in/out times
+- Estimated cost
+- Coverage percentage bar
+
+---
+
+### Demo 8: Staff Logs In with Existing Account
+**Purpose:** Show the worker sign-in experience
+
+**Screen:** Get Started → Sign In with Phone
+
+**Steps:**
+1. Restart the staff app
+2. Enter phone number: `5557654321`
+3. Tap "Send Code"
+4. Enter OTP: `123456`
+
+---
+
+### Demo 9: Staff Views Home Dashboard
+**Purpose:** Show worker's personalized dashboard
+
+**What to Notice:**
+- Today's Shifts section (confirmed shifts for today)
+- Tomorrow's Shifts section
+
+---
+
+### Demo 10: Staff Browses Available Shifts - [O3]
+**Purpose:** Show how workers discover and view available work
+
+**Screen:** Shifts → "Find Work"
+
+**What to Notice:**
+- List of shifts matching worker skills
+- Hourly rate prominently displayed
+- Role requirements (e.g., "Bartender - Spring Gala")
+- Date, time, and duration
+
+---
+
+### Demo 11: Staff Applies for Shift - [O4]
+**Purpose:** Show the application process from worker side
+
+**Screen:** Shift Details → "Apply Now" button
+
+**Steps:**
+1. Tap on an available shift to view details
+2. Review business name, location, pay, requirements
+3. Tap "Book Shift"
+4. See instant confirmation
+
+---
+
+### Demo 12: Staff Views Confirmed Shifts - [O5]
+**Purpose:** Show worker's shift management interface
+
+**Screen:** Shifts Tab → "My Shifts"
+
+**What to Notice:**
+- Week-by-week calendar navigation
+- Color-coded status (Confirmed, Pending, Completed)
+- Quick access to shift details and directions
+
+---
+
+### Demo 13: Client Monitors Coverage Dashboard - [O5]
+**Purpose:** Show real-time worker tracking capabilities
+
+**Screen:** Client App → Coverage Tab
+
+**What to Notice:**
+- Live worker status (Checked In, En Route, Late, Not Arrived)
+- Color-coded status badges (green, yellow, red)
+- Worker contact information
+- Real-time updates as workers check in
+
+---
+
+### Demo 14: Staff Checks In to Shift (Day of Event) - [O6]
+**Purpose:** Demonstrate the check-in process
+
+**Screen:** Home or My Shifts → Shift Card → "Check In" button
+
+**What to Notice:**
+- Timestamp automatically recorded
+- Status changes to "Checked In" with green indicator
+
+---
+
+### Demo 15: Client Sees Check-In Update - [O6]
+**Purpose:** Show cross-app interaction and real-time updates
+
+**Screen:** Client App → Coverage Tab
+
+**Action:** Press the update button on the top right to refresh worker statuses
+
+**What to Notice:**
+- Status update
+- Green "Checked In" badge appears
+- Check-in time displayed
+
+---
+
+### Demo 16: Staff Checks Out of Shift - [O7]
+**Purpose:** Demonstrate the check-out process and shift completion
+
+**Screen:** Home or My Shifts → Shift Card → "Check Out" button
+
+⚠️ **Note:** This feature is currently under fixing.
+
+**What to Notice:**
+- Check-out timestamp automatically recorded
+- Status changes to "Completed"
+- Total hours worked calculated automatically
+- Shift moves from active to history
+
+---
+
+### Demo 17: Client Views Completed Shift in Coverage - [O7]
+**Purpose:** Show how completed shifts appear in the client app
+
+**Screen:** Client App → Coverage Tab
+
+**Action:** Press the refresh button to update worker statuses
+
+**What to Notice:**
+- Worker status changes to "Completed"
+- Check-out time displayed alongside check-in time
+- Total hours worked visible
+- Shift marked as complete in orders list
+- Cost finalized based on actual hours
+
+---
+
+### Demo 18: Staff Profile Management
+**Purpose:** Demonstrate worker profile features and compliance management
+
+**Screen:** Staff App → Profile Tab
+
+**Steps:**
+1. Navigate to Profile tab in bottom navigation
+2. Review profile sections:
+   - **Profile Info:** Name, photo, contact details, date of birth
+   - **Statistics:** Total shifts worked, average rating, reliability score
+   - **Bank Account:** Linked payment account for direct deposit
+   - **Certificates:** Food Handler, ServSafe, Background Check status
+   - **Documents:** ID verification, work authorization
+   - **Tax Forms:** W-9, I-9 compliance documents *(bugs fixed: marital status and Citizenship Status now work properly)*
+   - **Time Card:** Historical shift records with hours and earnings
+
+---
+
+## 4️⃣ Customer Handover Checklist
+
+### Deliverables
+
+- [ ] Android apps (Client and Staff)
+- [ ] Demo account credentials (see below)
+
+### Demo Accounts
+
+| Account | Credentials |
+|---------|-------------|
+| **Client** | Email: `legendary@krowd.com` / Password: `Demo2026!` |
+| **Staff** | Phone: `+15557654321` / OTP: `123456` (demo mode) |
\ No newline at end of file