Merge branch 'dev' into feature/session-persistence-new

2026-03-11 10:56:48 +05:30
parent 9642eb0268 bac23ec78a
commit e3d8d30b1b
353 changed files with 29419 additions and 3689 deletions
--- a/docs/05-project-onboarding-master.md
+++ b/docs/05-project-onboarding-master.md
@@ -1,8 +1,9 @@
 # KROW Workforce Platform - Project Onboarding Master Document

-> **Version:** 1.1
-> **Last Updated:** 2026-01-22
+> **Version:** 2.0
+> **Last Updated:** 2026-03-06
 > **Purpose:** Source of Truth for Team Onboarding & Sprint Planning
+> **Latest Milestone:** M4 (Released: March 5, 2026)

 ---

@@ -13,7 +14,8 @@
 3. [Core Domain Logic](#3-core-domain-logic)
 4. [Feature Gap Analysis](#4-feature-gap-analysis)
 5. [Data Connect & Development Strategy](#5-data-connect--development-strategy)
-6. [Definition of Done (DoD)](#6-definition-of-done-dod)
+6. [Release Process & Automation](#6-release-process--automation)
+7. [Definition of Done (DoD)](#7-definition-of-done-dod)

 ---

@@ -160,27 +162,54 @@ graph TB
   - Event-driven architecture for async operations
   - Clean separation from data layer

-3. **PostgreSQL Retention:**
+3. **Core API Services:**
+   - Document verification service
+   - File upload service with signed URLs
+   - LLM service for AI features (RAPID orders)
+   - Integrated via ApiService (Dio-based)
+
+4. **PostgreSQL Retention:**
   - Full data ownership and portability
   - Complex queries and reporting capabilities
   - Industry-standard for enterprise requirements

-4. **Monorepo Structure:**
+5. **Monorepo Structure:**
   ```
   krow-workforce-web/
   ├── apps/
   │   ├── web-dashboard/     # Vite + React
   │   ├── mobile/
   |   |  ├── apps/  
-   |   |  │   ├── client/       # Flutter (business app)
-   |   |  │   └── staff/       # Flutter (staff app)
+   |   |  │   ├── client/       # Flutter (business app) - v0.0.1-m4
+   |   |  │   └── staff/       # Flutter (staff app) - v0.0.1-m4
+   |   |  └── packages/
+   |   |      ├── features/
+   |   |      │   ├── client/     # Client app features
+   |   |      │   └── staff/      # Staff app features
+   |   |      │       └── profile_sections/  # Modular profile (M4)
+   |   |      │           ├── onboarding/    # Profile info, experience, emergency
+   |   |      │           ├── compliance/    # Documents, certificates, attire
+   |   |      │           ├── finances/      # Bank, tax forms, timecard
+   |   |      │           └── support/       # FAQs, privacy & security
+   |   |      ├── core/           # Cross-cutting concerns
+   |   |      ├── data_connect/   # Backend integration
+   |   |      ├── domain/         # Entities & failures
+   |   |      ├── design_system/  # UI components & theme
+   |   |      └── core_localization/ # i18n
   ├── backend/
   │   ├── dataconnect/       # Firebase Data Connect schemas
-   │   └── functions/         # Cloud Functions
+   │   ├── cloud-functions/   # Firebase Cloud Functions
+   │   ├── command-api/       # Command API service
+   │   └── core-api/          # Core API (verification, upload, LLM)
   ├── firebase/              # Firebase config
   ├── internal/
   │   └── launchpad/         # Internal tools & prototypes
+   ├── .github/
+   │   ├── workflows/         # GitHub Actions (release automation)
+   │   └── scripts/           # Release helper scripts
   └── docs/                  # Documentation
+       ├── MOBILE/            # Mobile dev docs
+       └── RELEASE/           # Release docs
   ```

 ---
@@ -634,7 +663,92 @@ These **must be ported** from legacy:
 11. **Push Notifications** - FCM integration
 12. **Geofencing** - Location-based clock validation

-### 4.6 Migration Strategy
+### 4.6 M4 Milestone Completion Status (Released: March 5, 2026)
+
+**Version:** v0.0.1-m4 (both staff and client apps)
+
+#### Staff App M4 Achievements
+
+**Profile Management - 13 Subsections (✅ Complete):**
+
+Via modular `profile_sections/` architecture:
+
+**Onboarding:**
+- ✅ Personal Info (name, email, phone, address, SSN)
+- ✅ Experience (work history, skills, preferences)
+- ✅ Emergency Contacts (safety contacts with relationship)
+
+**Compliance:**
+- ✅ Documents (ID verification, uploads)
+- ✅ Certificates (certifications with expiry tracking)
+- ✅ Attire (uniform verification with camera/gallery)
+
+**Finances:**
+- ✅ Bank Account (payout setup with validation)
+- ✅ Tax Forms (I-9, W-4 forms)
+- ✅ Time Card (hours log with history)
+
+**Support:**
+- ✅ FAQs (help articles)
+- ✅ Privacy & Security (settings, account management)
+
+**Profile Features:**
+- ✅ Benefits Overview (perks information)
+- ✅ Profile completion tracking
+
+**Architecture:**
+- ✅ Modular feature structure (`profile_sections/onboarding`, `/compliance`, `/finances`, `/support`)
+- ✅ Flutter Modular dependency injection
+- ✅ Data Connect integration with type-safe SDKs
+- ✅ Shared design system components
+
+#### M4 Core Features
+
+**Authentication:**
+- ✅ Firebase phone auth (OTP flow)
+- ✅ Email/password authentication
+- ✅ Profile setup wizard
+
+**Session Management:**
+- ✅ Clock in/out flow (prototype UI)
+- ✅ Shift viewing and management
+- ✅ Session status tracking
+
+**Core API Integration:**
+- ✅ Document verification service
+- ✅ File upload service with signed URLs
+- ✅ ApiService (Dio-based) with error handling
+
+**Release Automation:**
+- ✅ GitHub Actions workflows (product-release, hotfix-branch-creation)
+- ✅ APK signing with 24 GitHub Secrets
+- ✅ Automated changelog generation
+- ✅ Git tag automation
+- ✅ 8 helper scripts for release management
+
+#### Client App M4 Status
+
+**Completion:** 89% of 9 major feature categories
+
+**Key Features:**
+- ✅ Authentication (email/password)
+- ✅ Order management (4 types: one-time, rapid, recurring, permanent)
+- ✅ Coverage dashboard
+- ✅ Reports (daily ops, spend, forecast, performance, no-show)
+- ✅ Hub management
+- ✅ Settings and preferences
+
+#### Documentation M4
+
+- ✅ Comprehensive release guide (`docs/RELEASE/mobile-releases.md` - 900+ lines)
+- ✅ Mobile development documentation (6 files in `docs/MOBILE/`)
+- ✅ Release process quick reference
+- ✅ GitHub Actions workflow documentation
+- ✅ APK signing setup guide
+- ✅ Architecture principles and patterns
+- ✅ Use case completion audit
+
+### 4.7 Migration Strategy

 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -665,9 +779,9 @@ These **must be ported** from legacy:
 └─────────────────────────────────────────────────────────────────┘
 ```

-### 4.7 Mobile Prototype Analysis (Source Code)
+### 4.8 Mobile Prototype Analysis (Source Code)

-#### 4.7.1 Mobile Client App (Flutter)
+#### 4.8.1 Mobile Client App (Flutter)

 **Location:** `internal/launchpad/prototypes-src/mobile/apps/client/`

@@ -706,7 +820,7 @@ These **must be ported** from legacy:

 ---

-#### 4.7.2 Mobile Staff App (Flutter)
+#### 4.8.2 Mobile Staff App (Flutter)

 **Location:** `internal/launchpad/prototypes-src/mobile/apps/staff/`

@@ -776,7 +890,7 @@ These **must be ported** from legacy:

 ---

-### 4.8 Complete Feature Comparison (All 3 Apps)
+### 4.9 Complete Feature Comparison (All 3 Apps)

 | Feature | Legacy Mobile | Web Prototype | Mobile Prototype |
 |---------|--------------|---------------|------------------|
@@ -802,7 +916,7 @@ These **must be ported** from legacy:
 | **Penalty System** | ✅ | ❌ | ❌ |
 | **Staff Rating** | ✅ | ❌ | ❌ |

-### 4.9 Source Code Locations
+### 4.10 Source Code Locations

 | Component | Location | Tech |
 |-----------|----------|------|
@@ -926,9 +1040,133 @@ Based on minimal dependencies:

 ---

-## 6. Definition of Done (DoD)
+## 6. Release Process & Automation

-### 6.1 Feature-Level DoD (MVP Phase)
+### 6.1 Versioning Strategy
+
+**Mobile Apps:**
+- Format: `v{major}.{minor}.{patch}-{milestone}`
+- Example: `v0.0.1-m4` (current release)
+- Milestones: m1, m2, m3, m4, etc.
+- Auto-extracted from `apps/mobile/apps/{staff|client}/pubspec.yaml`
+
+**Git Tags:**
+- Format: `{app-name}/{version}`
+- Examples: `staff/v0.0.1-m4`, `client/v0.0.1-m4`
+
+### 6.2 GitHub Actions Workflows
+
+**1. Product Release (`.github/workflows/product-release.yml`)**
+- **Trigger:** Manual dispatch via GitHub UI
+- **Purpose:** Automated production releases with APK signing
+- **Process:**
+  1. Extracts version from `pubspec.yaml`
+  2. Builds signed APKs for both apps
+  3. Creates GitHub release with changelog
+  4. Tags release (e.g., `staff/v0.0.1-m4`)
+  5. Uploads APKs as release assets
+- **Secrets Required:** 24 GitHub Secrets for APK signing (see `docs/RELEASE/mobile-releases.md`)
+
+**2. Hotfix Branch Creation (`.github/workflows/hotfix-branch-creation.yml`)**
+- **Trigger:** Manual dispatch with version input
+- **Purpose:** Emergency fixes for production issues
+- **Process:**
+  1. Creates `hotfix/{version}` branch from latest tag
+  2. Opens PR back to `dev` branch
+  3. Auto-updates PR description with hotfix checklist
+
+**3. Helper Scripts (`.github/scripts/`)**
+- `extract-version.sh` - Extracts version from pubspec.yaml
+- `generate-changelog.sh` - Generates release notes from CHANGELOG
+- `create-release.sh` - Creates GitHub release
+- `upload-assets.sh` - Uploads APKs to release
+- `build-apk.sh` - Builds signed APK
+- `tag-release.sh` - Creates Git tags
+- `hotfix-branch.sh` - Creates hotfix branches
+- `update-pr.sh` - Updates PR descriptions
+
+### 6.3 APK Signing Setup
+
+**Required GitHub Secrets (per app):**
+```
+STAFF_UPLOAD_KEYSTORE_BASE64      # Base64-encoded keystore
+STAFF_UPLOAD_STORE_PASSWORD       # Keystore password
+STAFF_UPLOAD_KEY_ALIAS            # Key alias
+STAFF_UPLOAD_KEY_PASSWORD         # Key password
+STAFF_KEYSTORE_PROPERTIES_BASE64  # Base64-encoded key.properties
+
+CLIENT_UPLOAD_KEYSTORE_BASE64
+CLIENT_UPLOAD_STORE_PASSWORD
+CLIENT_UPLOAD_KEY_ALIAS
+CLIENT_UPLOAD_KEY_PASSWORD
+CLIENT_KEYSTORE_PROPERTIES_BASE64
+```
+
+### 6.4 CHANGELOG Format
+
+Each app maintains a separate CHANGELOG:
+- `apps/mobile/apps/staff/CHANGELOG.md`
+- `apps/mobile/apps/client/CHANGELOG.md`
+
+**Format:**
+```markdown
+## [Unreleased]
+
+### Added
+- New feature descriptions
+
+### Changed
+- Modified feature descriptions
+
+### Fixed
+- Bug fix descriptions
+
+## [0.0.1-m4] - 2026-03-05
+
+### Added
+- Profile management with 13 subsections
+- Documents & certificates management
+- Benefits overview
+...
+```
+
+### 6.5 Release Documentation
+
+**Comprehensive Guide:**
+- Location: `docs/RELEASE/mobile-releases.md`
+- Length: 900+ lines
+- Contents:
+  - Complete versioning strategy
+  - CHANGELOG format and examples
+  - GitHub Actions workflow details
+  - APK signing setup (with secret generation)
+  - Helper scripts reference
+  - Troubleshooting guide
+
+**Quick Reference:**
+- Location: `docs/MOBILE/05-release-process.md`
+- Links to comprehensive guide and workflows
+
+### 6.6 Local Release Commands (via Makefile)
+
+```bash
+# Build unsigned APKs locally
+make build-apk-staff
+make build-apk-client
+
+# Run GitHub Actions locally (requires act)
+make test-release-workflow
+
+# Generate changelog entries
+make changelog-staff
+make changelog-client
+```
+
+---
+
+## 7. Definition of Done (DoD)
+
+### 7.1 Feature-Level DoD (MVP Phase)

 A feature is **DONE** when:

@@ -944,7 +1182,7 @@ A feature is **DONE** when:

 > **Note (MVP):** For rapid MVP delivery, we focus on manual/integration testing directly in applications rather than unit tests. Automated test coverage will be added post-MVP.

-### 6.2 Sprint-Level DoD
+### 7.2 Sprint-Level DoD

 A sprint is **DONE** when:

@@ -956,7 +1194,7 @@ A sprint is **DONE** when:
 - [ ] Demo-ready for stakeholders
 - [ ] Documentation updated

-### 6.3 Code Quality Standards
+### 7.3 Code Quality Standards

 | Aspect | Standard |
 |--------|----------|
@@ -967,7 +1205,7 @@ A sprint is **DONE** when:
 | **PRs** | Template completed, 1+ approval |
 | **Testing (MVP)** | Manual testing in application |

-### 6.4 Commit Message Format
+### 7.4 Commit Message Format

 ```
 <type>(<scope>): <subject>
--- a/docs/DESIGN/product-specification.md
+++ b/docs/DESIGN/product-specification.md
--- a/docs/MILESTONES/M4/demos/m4-client-note.md
+++ b/docs/MILESTONES/M4/demos/m4-client-note.md
@@ -0,0 +1,82 @@
+# KROW Workforce Platform — M4 Guide
+
+**Version:** Milestone 4 (0.0.1-IlianaStaffM4 and 0.0.1-IlianaClientM4)
+**Estimated Duration:** 25-30 minutes
+
+---
+
+## 📦 Deliverables
+
+- **Client Mobile Application** (v0.0.1-IlianaClientM4)
+- **Staff Mobile Application** (v0.0.1-IlianaStaffM4)
+- **Full Demo Video** - Comprehensive walkthrough of all (M1 - M4) completed features of the mobile applications.
+
+---
+
+## 1. Overview
+
+### Core Improvements
+M4 delivers three key areas of improvement:
+
+1. **Overall Application Improvements**
+   - Auth session persistence: Users stay signed in after reopening the app
+   - Stability fixes from M3 client feedback and dev team discoveries
+   - UI/UX improvements across key screens for clarity and speed
+
+2. **Client App Updates**
+   - Complete order creation flow (Rapid, Permanent, Recurring orders)
+   - Shift manager assignment support
+   - Paid/unpaid break handling in orders
+   - Complete Reports section (Daily Ops, Spend, Coverage, No-show, Performance)
+   - Cost centres in hubs for location/business unit tracking
+   - Billing approval workflow for pending bills
+
+3. **Staff App Updates**
+   - Profile completion requirements gating payments and clockings
+   - Worker benefits integration
+   - Enhanced shift discovery with filtering by location
+   - Spanish localization support
+   - AI-verified document uploads (Attire, Documents, Certificates)
+   - FAQ and Privacy Policy
+   - Worker profile visibility controls
+
+---
+
+## 2. Required Test Accounts
+
+**Client Account (Business User):**
+- Email: `legendary@krowd.com`
+- Password: `Demo2026!`
+- Client Name: "KROW"
+
+**Staff Account (Worker):**
+- Phone: `+15557654321`
+- OTP Code: `123456` (testing mode)
+- Name: "Mariana Torres"
+
+***Note on Profile Completion***
+When a staff user hasn't completed their profile, they see an empty/incomplete state on their home screen. Currently tracked sections to mark as complete:
+- Profile Information (full name, email, phone, preferred locations)
+- Emergency Contact
+
+Future sections can be added as mandatory, such as Tax Forms, Bank Account, Documents, Certificates, and Attires.
+
+***Profile Blocking Rules***
+When the profile is incomplete, the following features are blocked to encourage completion:
+- Clock-in page is hidden
+- Payments are blocked
+- "My Shifts" and History sections are hidden
+- Users can view available shifts but cannot book them
+
+This ensures we have all necessary information for compliance and payroll before workers are allowed to work.
+
+---
+
+## 3. M4 Key Deliverables
+
+✅ Stronger reliability and stability
+✅ Completed client ordering and reporting workflows
+✅ Better profile and shift tooling for staff
+✅ AI-assisted document verification
+✅ Localization support (Spanish)
+✅ Improved billing and cost tracking controls
--- a/docs/MILESTONES/M5/planning/m5-client-clarifications.md
+++ b/docs/MILESTONES/M5/planning/m5-client-clarifications.md
@@ -0,0 +1,95 @@
+# Clarifications Required – Project Discovery
+
+During Milestone 4 (M5) planning, we identified several items that require clarification before development can proceed.
+
+Please review the questions below and share any relevant documents, examples, or preferences.
+
+---
+
+## Issue: Research: Validate worker SSN number in the US
+
+### Description
+We need to identify a viable approach/service to validate a worker’s SSN for the US market, compare 2–3 options, and recommend one with cost and risk considerations.
+
+### Existing Tools / Platforms
+- Are you currently using any service or process to validate SSNs (in the legacy app or elsewhere)? If yes, which tool(s) and what’s working/not working today?
+
+---
+
+## Issue: Research: Validate worker bank account details in the US
+
+### Description
+We need to identify a reliable, server-side way to validate worker bank account details for the US market (beyond basic UI checks), compare 2–3 options, and recommend one.
+
+### Existing Tools / Platforms
+- Do you currently use any tool/process for bank account validation or payouts? If yes, which platform(s) ?
+
+---
+
+## Issue: Research: Select payment platform for worker payouts
+
+### Description
+We need to select a payout/payment platform to pay workers, comparing options by cost, reliability, and integration effort, and then recommend a platform?
+
+### Existing Tools / Platforms
+- Are you already using a payments/payout platform today (or do you have a preferred vendor relationship)?
+
+---
+
+## Issue: Business: Create template model for PDF reports
+
+### Description
+We need to align PDF report formats across the client mobile and web platforms by defining a shared template model that’s ready to implement in both.
+
+### Existing Tools / Platforms
+- Do you already have existing PDF templates (or examples) you use today? If yes, can you share them and how they’re currently produced?
+
+---
+
+## Issue: Business: Finalize terms of service and privacy policy for mobile apps
+
+### Description
+We need approved Terms of Service and Privacy Policy documents for mobile apps.
+
+### Clarifications Needed
+1. Do you already have Terms of Service and a Privacy Policy draft we should implement?
+
+---
+
+## Issue: Business: Handle worker data requests
+
+### Description
+We need a documented workflow to handle worker requests for their personal data, covering intake, identity verification, fulfillment, and timelines.
+
+### Clarifications Needed
+1. How should requests be submitted (in-app, email, support form, other)?
+2. What verification steps are required before fulfilling a request?
+
+### Existing Tools / Platforms
+- Do you currently use a support/ticketing system or internal workflow for these requests?
+
+---
+
+## Issue: Business: Finalize key terminology used in the app
+
+### Description
+We need consistent, accurate product language across the app.
+
+### Clarifications Needed
+1. The "staff app" shall we call it “Worker App” or “Worker Mobile App” (or another term)?
+2. For worker registration, should we use “signup” or “onboarding” (or another term)?
+
+---
+
+## Issue: RESEARCH: How to calculate the reliability score of a worker
+
+### Description
+We need to define the formula and logic for a worker’s reliability score, including which signals feed the score, its scale, display expectations, and its relationship to star rating.
+
+### Clarifications Needed
+1. Is the reliability score given by clients, system-derived, or a combination?
+---
+
+## Additional Context
+
+If there are documents, workflows, screenshots, examples, policy notes, or tools related to these topics, please share them. Even rough notes are helpful — they will help us confirm requirements, choose the right integrations, and design the best user experience before implementation begins.
--- a/docs/MOBILE/00-agent-development-rules.md
+++ b/docs/MOBILE/00-agent-development-rules.md
@@ -92,7 +92,7 @@ You have access to `prototypes/` folders. When migrating code:

 1.  **Extract Assets**: 
    * You MAY copy icons, images, and colors. But they should be tailored to the current design system. Do not change the colours and typgorahys in the design system. They are final. And you have to use these in the UI.
-      * When you matching colous and typography, from the POC match it with the design system and use the colors and typography from the design system. As mentioned in the `apps/mobile/docs/03-design-system-usage.md`.
+      * When you matching colous and typography, from the POC match it with the design system and use the colors and typography from the design system. As mentioned in the `apps/mobile/docs/02-design-system-usage.md`.
 2.  **Extract Layouts**: You MAY copy `build` methods for UI structure.
 3.  **REJECT Architecture**: You MUST **NOT** copy the `GetX`, `Provider`, or `MVC` patterns often found in prototypes. Refactor immediately to **Bloc + Clean Architecture with Flutter Modular and Melos**.

@@ -103,7 +103,7 @@ If a user request is vague:
 1.  **STOP**: Do not guess domain fields or workflows.
 2.  **ANALYZE**: 
 - For architecture related questions, refer to `apps/mobile/docs/01-architecture-principles.md` or existing code.
- - For design system related questions, refer to `apps/mobile/docs/03-design-system-usage.md` or existing code.
+ - For design system related questions, refer to `apps/mobile/docs/02-design-system-usage.md` or existing code.
 3.  **DOCUMENT**: If you must make an assumption to proceed, add a comment `// ASSUMPTION: <explanation>` and mention it in your final summary.
 4.  **ASK**: Prefer asking the user for clarification on business rules (e.g., "Should a 'Job' have a 'status'?").

--- a/docs/MOBILE/01-architecture-principles.md
+++ b/docs/MOBILE/01-architecture-principles.md
@@ -105,11 +105,11 @@ graph TD
    - If not possible, and if that specific widget is used in multiple features, then try to create a shared widget in the `apps/mobile/packages/design_system/widgets`.
  - Theme definitions (Colors, Typography).
  - Assets (Icons, Images).
-  - More details on how to use this package is available in the `apps/mobile/docs/03-design-system-usage.md`.
+  - More details on how to use this package is available in the `apps/mobile/docs/02-design-system-usage.md`.
 - **RESTRICTION**: 
  - CANNOT change colours or typography.
  - Dumb widgets only. NO business logic. NO state management (Bloc).
-  - More details on how to use this package is available in the `apps/mobile/docs/03-design-system-usage.md`.
+  - More details on how to use this package is available in the `apps/mobile/docs/02-design-system-usage.md`.

 ### 2.6 Core Localization (`apps/mobile/packages/core_localization`)
 - **Role**: Centralized language and localization management.
--- a/docs/MOBILE/04-use-case-completion-audit.md
+++ b/docs/MOBILE/04-use-case-completion-audit.md
@@ -1,9 +1,10 @@
 # 📊 Use Case Completion Audit

-**Generated:** 2026-03-02  
+**Generated:** 2026-03-06  
 **Auditor Role:** System Analyst / Flutter Architect  
 **Source of Truth:** `docs/ARCHITECTURE/client-mobile-application/use-case.md`, `docs/ARCHITECTURE/staff-mobile-application/use-case.md`  
-**Codebase Checked:** `apps/mobile/packages/features/` and `apps/mobile/apps/` (actual production apps)
+**Codebase Checked:** `apps/mobile/packages/features/` and `apps/mobile/apps/` (actual production apps)  
+**Latest Milestone:** M4 (released 2026-03-05)

 ---

@@ -162,7 +163,7 @@
 | 2.1 Browse & Filter Jobs | Filter by Distance | ✅ | ✅ Completed | Distance/radius filtering implemented in shifts module. |
 | 2.1 Browse & Filter Jobs | View job card details | ✅ | ✅ Completed | Comprehensive job cards with pay, location, requirements. |
 | 2.3 Set Availability | Select dates/times → Save preferences | ✅ | ✅ Completed | `availability_page.dart` + AvailabilityBloc with 3 use cases. |
-| View Benefits | Browse available benefits | ✅ | 🚫 Completed | `benefits_overview_page.dart` (454 lines) fully implemented as part of home module. |
+| View Benefits | Browse available benefits | ✅ | ✅ Completed | `benefits_overview_page.dart` in home module. Documented in M4 milestone. |
 | Upcoming Shift Quick-Link | Next shift banner on home | ✅ | 🚫 Completed | Upcoming shifts display on worker home page. |

 ---
@@ -215,18 +216,18 @@
 | Use Case | Sub-Use Case | Production App | Status | Notes |
 |:---|:---|:---:|:---:|:---|
 | 5.1 Manage Compliance Documents | Navigate to Compliance Menu | ✅ | ✅ Completed | Compliance section in `staff_profile_page.dart`. |
-| 5.1 Manage Compliance Documents | Upload Certificates | ✅ | ✅ Completed | `certificates/` module with 4 use cases + 2 pages. |
-| 5.1 Manage Compliance Documents | View/Manage Identity Documents | ✅ | ✅ Completed | `documents/` module with upload + view functionality. |
-| 5.2 Manage Tax Forms | Complete W-4 digitally & submit | ✅ | ✅ Completed | `tax_forms/form_w4_page.dart` + FormW4Cubit + use cases. |
-| 5.2 Manage Tax Forms | Complete I-9 digitally & submit | ✅ | ✅ Completed | `tax_forms/form_i9_page.dart` + FormI9Cubit + use cases. |
-| 5.4 Account Settings | Update Bank Details | ✅ | ✅ Completed | `staff_bank_account/` module with page + cubit. |
-| 5.4 Account Settings | Access Support / FAQs | ✅ | ✅ Completed | `faqs/` module with search functionality + 2 use cases. |
-| Personal Info Management | Update profile information | ✅ | 🚫 Completed | `profile_info/` module with 3 pages (personal info, language, locations). |
-| Emergency Contact | Manage emergency contacts | ✅ | 🚫 Completed | `emergency_contact/` module with get + save use cases. |
-| Experience Management | Update industries and skills | ✅ | 🚫 Completed | `experience/` module with 3 use cases. |
-| Attire Management | Upload attire photos | ✅ | 🚫 Completed | `attire/` module with upload + photo management. |
-| Timecard Viewing | View clock-in/out history | ✅ | 🚫 Completed | `time_card/` module with get_time_cards use case. |
-| Privacy & Security | Manage privacy settings | ✅ | 🚫 Completed | `privacy_security/` module with 4 use cases + 2 pages. |
+| 5.1 Manage Compliance Documents | Upload Certificates | ✅ | ✅ Completed | `profile_sections/compliance/certificates/` module with 4 use cases + 2 pages. M4 feature. |
+| 5.1 Manage Compliance Documents | View/Manage Identity Documents | ✅ | ✅ Completed | `profile_sections/compliance/documents/` module with camera/gallery upload. M4 feature. |
+| 5.2 Manage Tax Forms | Complete W-4 digitally & submit | ✅ | ✅ Completed | `profile_sections/finances/tax_forms/form_w4_page.dart` + FormW4Cubit + use cases. |
+| 5.2 Manage Tax Forms | Complete I-9 digitally & submit | ✅ | ✅ Completed | `profile_sections/finances/tax_forms/form_i9_page.dart` + FormI9Cubit + use cases. |
+| 5.4 Account Settings | Update Bank Details | ✅ | ✅ Completed | `profile_sections/finances/staff_bank_account/` module with page + cubit. |
+| 5.4 Account Settings | Access Support / FAQs | ✅ | ✅ Completed | `profile_sections/support/faqs/` module with search functionality + 2 use cases. |
+| Personal Info Management | Update profile information | ✅ | ✅ Completed | `profile_sections/onboarding/profile_info/` module with 3 pages. Documented in M4. |
+| Emergency Contact | Manage emergency contacts | ✅ | ✅ Completed | `profile_sections/onboarding/emergency_contact/` module. Documented in M4. |
+| Experience Management | Update industries and skills | ✅ | ✅ Completed | `profile_sections/onboarding/experience/` module with 3 use cases. Documented in M4. |
+| Attire Management | Upload attire photos & verification | ✅ | ✅ Completed | `profile_sections/compliance/attire/` module with camera/gallery support. Documented in M4. |
+| Timecard Viewing | View clock-in/out history | ✅ | 🚫 Completed | `profile_sections/finances/time_card/` module with get_time_cards use case. |
+| Privacy & Security | Manage privacy settings & visibility | ✅ | ✅ Completed | `profile_sections/support/privacy_security/` module with 4 use cases + 2 pages. Documented in M4. |

 ---

@@ -235,7 +236,6 @@
 | Feature | Status | Notes |
 |:---|:---:|:---|
 | 5.3 KROW University Training | ❌ Missing | No training module exists. Module, video/quiz functionality not implemented. |
-| 5.4 View Benefits | ✅ **Actually Implemented** | Found in home module as `benefits_overview_page.dart` (454 lines). |
 | In-App Support Chat | ❌ Missing | No messaging module (only push notification support). |
 | Leaderboard | ❌ Missing | No competitive tracking/gamification module. |

@@ -269,7 +269,7 @@
 - ✅ Clock In/Out (GPS + NFC): 100%
 - ✅ Payments & Early Pay: 100%
 - ✅ Availability: 100%
- ✅ Profile & Compliance: 100% (11 subsections)
+- ✅ Profile & Compliance: 100% (13 subsections via modular `profile_sections` structure)
 - ❌ KROW University: 0% (training module not implemented)

 ---
@@ -292,7 +292,12 @@
  - **Presentation** (pages, widgets, BLoCs)
  - **Domain** (use cases, entities)
  - **Data** (repositories, models, data sources)
-  - **Dependency injection** via GetIt
+  - **Dependency injection** via Flutter Modular
+- **Modular Profile Sections** (M4): Staff profile features organized in `profile_sections/` with 4 sub-modules:
+  - `onboarding/` - Profile info, experience, emergency contacts
+  - `compliance/` - Documents, certificates, attire
+  - `finances/` - Bank account, tax forms, timecard
+  - `support/` - FAQs, privacy & security

 ### Known Technical Debt
 - **Coverage Re-post**: Mutation exists but noted as stub in code (needs backend wiring)
--- a/docs/MOBILE/05-release-process.md
+++ b/docs/MOBILE/05-release-process.md
@@ -0,0 +1,64 @@
+# Mobile Release Process
+
+**For complete release documentation, see: [docs/RELEASE/mobile-releases.md](../RELEASE/mobile-releases.md)**
+
+---
+
+## Quick Links
+
+### Release Workflows
+- **Product Release**: Trigger at: [GitHub Actions](https://github.com/Oloodi/krow-workforce/actions/workflows/product-release.yml)
+- **Hotfix Creation**: Trigger at: [GitHub Actions](https://github.com/Oloodi/krow-workforce/actions/workflows/hotfix-branch-creation.yml)
+
+### Key Concepts
+
+**Versioning**: We use semantic versioning with milestone suffixes (e.g., `0.0.1-m4`)
+- Defined in: `apps/mobile/apps/staff/pubspec.yaml` or `apps/mobile/apps/client/pubspec.yaml`
+- Auto-extracted by workflows (no manual input required)
+
+**CHANGELOGs**:
+- Staff: `apps/mobile/apps/staff/CHANGELOG.md`
+- Client: `apps/mobile/apps/client/CHANGELOG.md`
+- Format: `## [v0.0.1-m4] - Milestone 4 - 2026-03-05`
+
+**Git Tags**: `krow-withus-<app>-mobile/<env>-vX.Y.Z`
+- Example: `krow-withus-worker-mobile/dev-v0.0.1-m4`
+
+---
+
+## Quick Start
+
+### Standard Release
+
+1. **Update CHANGELOG** with user-facing changes
+2. **Update version** in `pubspec.yaml`
+3. **Commit and push** to dev branch
+4. **Trigger workflow**:
+   - Go to GitHub Actions → "📦 Product Release"
+   - Select app (worker/client) and environment (dev/stage/prod)
+   - Click "Run workflow"
+
+### Hotfix Release
+
+1. **Trigger workflow**:
+   - Go to GitHub Actions → "🚨 Product Hotfix - Create Branch"
+   - Enter current production version and issue description
+   - Workflow creates branch and updates version/CHANGELOG
+2. **Fix bug** on hotfix branch
+3. **Merge to main** and release to production
+
+---
+
+## For Complete Details
+
+See the comprehensive documentation: **[docs/RELEASE/mobile-releases.md](../RELEASE/mobile-releases.md)**
+
+This includes:
+- ✅ Detailed versioning strategy
+- ✅ CHANGELOG format guidelines
+- ✅ Step-by-step release procedures
+- ✅ APK signing setup (24 GitHub Secrets)
+- ✅ Helper scripts reference
+- ✅ Hotfix process
+- ✅ Troubleshooting guide
+- ✅ Release cadence (dev/stage/prod)
--- a/docs/RELEASE/mobile-releases.md
+++ b/docs/RELEASE/mobile-releases.md
@@ -0,0 +1,727 @@
+# Mobile App Release Process
+
+**For Staff Mobile & Client Mobile Apps**
+
+**Document Version**: 2.0  
+**Last Updated**: 2026-03-06  
+**Status**: ✅ Production Ready
+
+---
+
+## 📱 Overview
+
+This document covers the complete release process for both mobile applications:
+
+- **Staff Mobile App** (Worker Mobile) - `krow-withus-worker-mobile`
+- **Client Mobile App** - `krow-withus-client-mobile`
+
+Both apps:
+- Built with Flutter
+- Distributed via iOS App Store & Google Play Store
+- Maintain independent versions
+- Have independent CHANGELOGs
+- Released via GitHub Actions workflows
+
+---
+
+## 📐 Versioning Strategy
+
+### Semantic Versioning with Milestones
+
+We use **Semantic Versioning 2.0.0** with milestone suffixes:
+
+```
+MAJOR.MINOR.PATCH-milestone
+```
+
+**Examples:**
+- `0.0.1-m3` - Milestone 3 release
+- `0.0.1-m4` - Milestone 4 release
+- `1.0.0` - First production release (no suffix)
+- `1.0.1` - Production patch release
+
+**Version Rules:**
+- **MAJOR**: Breaking changes, major architectural updates
+- **MINOR**: New features, backward-compatible changes
+- **PATCH**: Bug fixes, minor improvements
+- **SUFFIX**: `-m3`, `-m4`, etc. for milestone tracking
+
+### Version Location
+
+Versions are defined in `pubspec.yaml`:
+
+**Staff Mobile:** `apps/mobile/apps/staff/pubspec.yaml`
+```yaml
+version: 0.0.1-m4+1
+```
+
+**Client Mobile:** `apps/mobile/apps/client/pubspec.yaml`
+```yaml
+version: 0.0.1-m4+1
+```
+
+**Format:** `X.Y.Z-suffix+buildNumber`
+- `0.0.1-m4` = version with milestone
+- `+1` = build number (for app stores)
+
+### Version Auto-Extraction
+
+GitHub Actions workflows automatically extract the version from `pubspec.yaml` using `.github/scripts/extract-version.sh`. **No manual version input required.**
+
+---
+
+## 📝 CHANGELOG Management
+
+### File Locations
+
+- **Staff Mobile:** `apps/mobile/apps/staff/CHANGELOG.md`
+- **Client Mobile:** `apps/mobile/apps/client/CHANGELOG.md`
+
+### Format Standard
+
+```markdown
+# [App Name] - Change Log
+
+## [v0.0.1-m4] - Milestone 4 - 2026-03-05
+
+### Added - [Category Name]
+- Feature description
+- Another feature
+
+### Fixed
+- Bug fix description
+
+### Changed
+- Changed behavior
+
+---
+
+## [v0.0.1-m3] - Milestone 3 - 2026-02-15
+
+### Added - [Category Name]
+...
+```
+
+### Section Guidelines
+
+Use these standard categories:
+- **Added**: New features
+- **Fixed**: Bug fixes
+- **Changed**: Changes to existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Security**: Security fixes
+
+### When to Update CHANGELOG
+
+✅ **Update BEFORE release:**
+- When milestone is complete
+- Document all user-facing changes
+- Include technical features if relevant
+
+❌ **Don't document:**
+- Internal refactoring (unless architecturally significant)
+- Development-only changes
+- Code formatting/linting
+
+---
+
+## 🏷️ Git Tag Format
+
+### Tag Structure
+
+```
+krow-withus-<app>-mobile/<env>-v<version>
+```
+
+### Examples
+
+**Staff Mobile (Worker):**
+```
+krow-withus-worker-mobile/dev-v0.0.1-m3
+krow-withus-worker-mobile/stage-v0.0.1-m4
+krow-withus-worker-mobile/prod-v1.0.0
+```
+
+**Client Mobile:**
+```
+krow-withus-client-mobile/dev-v0.0.1-m3
+krow-withus-client-mobile/stage-v0.0.1-m4
+krow-withus-client-mobile/prod-v1.0.0
+```
+
+### Tag Components
+
+| Component | Values | Example |
+|-----------|--------|---------|
+| Product | `worker`, `client` | `worker` |
+| Type | `mobile` | `mobile` |
+| Environment | `dev`, `stage`, `prod` | `dev` |
+| Version | From pubspec.yaml | `v0.0.1-m3` |
+
+**Note:** Tags include the full version with milestone suffix (e.g., `v0.0.1-m4`, not just `v0.0.1`)
+
+---
+
+## 🚀 Release Workflows
+
+### Release Types
+
+We have **2 GitHub Actions workflows** for releases:
+
+1. **Product Release** (`.github/workflows/product-release.yml`) - Standard releases
+2. **Hotfix Branch Creation** (`.github/workflows/hotfix-branch-creation.yml`) - Emergency fixes
+
+Both workflows use **manual triggers only** (`workflow_dispatch`) - no automatic releases.
+
+---
+
+## 📦 Standard Release Process
+
+### Step 1: Prepare Release
+
+1. **Ensure milestone is complete**
+   - All features implemented
+   - All tests passing
+   - Code reviews completed
+
+2. **Update CHANGELOG**
+   ```bash
+   # Edit the appropriate CHANGELOG file
+   vi apps/mobile/apps/staff/CHANGELOG.md
+   # OR
+   vi apps/mobile/apps/client/CHANGELOG.md
+   ```
+
+3. **Update version in pubspec.yaml**
+   ```yaml
+   # apps/mobile/apps/staff/pubspec.yaml
+   version: 0.0.1-m4+1
+   ```
+
+4. **Commit changes**
+   ```bash
+   git add apps/mobile/apps/staff/CHANGELOG.md apps/mobile/apps/staff/pubspec.yaml
+   git commit -m "docs(mobile): prepare staff app v0.0.1-m4 release"
+   git push origin dev
+   ```
+
+### Step 2: Trigger Release Workflow
+
+1. **Navigate to GitHub Actions**
+   - Go to: https://github.com/Oloodi/krow-workforce/actions
+   - Select **"📦 Product Release"** workflow
+
+2. **Click "Run workflow"**
+
+3. **Select parameters:**
+   - **Branch**: `dev` (or release branch)
+   - **Product**: `worker-mobile-app` or `client-mobile-app`
+   - **Environment**: `dev`, `stage`, or `prod`
+   - **Pre-release**: Check if this is not a production release
+
+4. **Click "Run workflow"**
+
+### Step 3: Monitor Workflow
+
+The workflow performs these steps automatically:
+
+1. ✅ **Validate & Create Release** (Job 1)
+   - Extract version from pubspec.yaml
+   - Validate version format
+   - Generate tag name
+   - Create Git tag
+   - Extract release notes from CHANGELOG
+   - Create GitHub Release with formatted notes
+
+2. 🔨 **Build Mobile Artifacts** (Job 2)
+   - Setup Node.js 20
+   - Install Firebase CLI
+   - Generate Data Connect SDK
+   - Setup Java 17
+   - Setup Flutter 3.38.x
+   - Bootstrap with Melos
+   - Decode keystore from secrets
+   - Build signed APK
+   - Verify APK signature
+   - Upload APK to GitHub Release
+
+### Step 4: Verify Release
+
+1. **Check GitHub Releases page**
+   - URL: https://github.com/Oloodi/krow-workforce/releases
+   - Verify release was created with correct tag
+   - Verify release notes display correctly
+   - Verify APK is attached (if applicable)
+
+2. **Test the release**
+   - Download APK (dev releases)
+   - Install on test device
+   - Verify app launches and core features work
+
+---
+
+## 🔥 Hotfix Process
+
+### When to Use Hotfix
+
+✅ **Use hotfix for:**
+- Critical bug in production affecting users
+- Data loss or security vulnerability
+- Service unavailable or major feature broken
+- Customer-blocking issue
+
+❌ **Don't use hotfix for:**
+- Minor bugs (can wait for next release)
+- Feature requests
+- UI/UX improvements
+- Styling issues
+
+### Hotfix Workflow
+
+1. **Navigate to GitHub Actions**
+   - Go to: https://github.com/Oloodi/krow-workforce/actions
+   - Select **"🚨 Product Hotfix - Create Branch"** workflow
+
+2. **Click "Run workflow"**
+
+3. **Fill in parameters:**
+   - **Product**: `worker-mobile-app` or `client-mobile-app`
+   - **Current Production Version**: e.g., `1.0.0` (without 'v' prefix)
+   - **Issue Description**: Brief description of the bug (used in CHANGELOG and branch name)
+
+4. **The workflow automatically:**
+   - Creates hotfix branch: `hotfix/krow-withus-worker-mobile/prod-v1.0.1`
+   - Increments PATCH version: `1.0.0` → `1.0.1`
+   - Updates `pubspec.yaml` with new version
+   - Updates CHANGELOG.md with hotfix entry
+   - Creates Pull Request with hotfix instructions
+
+5. **Fix the bug:**
+   ```bash
+   # Checkout the hotfix branch
+   git fetch origin
+   git checkout hotfix/krow-withus-worker-mobile/prod-v1.0.1
+   
+   # Make your fix
+   # ... edit files ...
+   
+   # Test thoroughly
+   flutter test
+   
+   # Commit your fix
+   git add .
+   git commit -m "fix(mobile): resolve critical production bug"
+   git push origin hotfix/krow-withus-worker-mobile/prod-v1.0.1
+   ```
+
+6. **Merge and Release:**
+   - Review and merge the Pull Request to `main` (or production branch)
+   - Trigger **Product Release** workflow with `prod` environment
+   - Workflow will create tag `krow-withus-worker-mobile/prod-v1.0.1`
+   - Deploy hotfix to production
+
+7. **Backport to dev:**
+   ```bash
+   git checkout dev
+   git merge hotfix/krow-withus-worker-mobile/prod-v1.0.1
+   git push origin dev
+   ```
+
+---
+
+## 🔐 APK Signing Setup
+
+### Overview
+
+All Android builds require signing with keystores. We use **24 GitHub Secrets** (12 per app × 2 apps):
+
+- 6 keystores (2 apps × 3 environments)
+- 4 secrets per keystore (base64, password, alias, key password)
+
+### Keystore Files
+
+**Worker Mobile (Staff App):**
+- `krow_with_us_staff_dev.jks` - ✅ Committed to repo
+- `krow_staff_staging.jks` - ⚠️ Store in GitHub Secrets only
+- `krow_staff_prod.jks` - ⚠️ Store in GitHub Secrets only
+
+**Client Mobile:**
+- `krow_with_us_client_dev.jks` - ✅ Committed to repo
+- `krow_client_staging.jks` - ⚠️ Store in GitHub Secrets only
+- `krow_client_prod.jks` - ⚠️ Store in GitHub Secrets only
+
+### Required GitHub Secrets
+
+#### Worker Mobile - 12 Secrets
+
+**Dev Environment:**
+- `WORKER_KEYSTORE_DEV_BASE64`
+- `WORKER_KEYSTORE_PASSWORD_DEV`
+- `WORKER_KEY_ALIAS_DEV`
+- `WORKER_KEY_PASSWORD_DEV`
+
+**Staging Environment:**
+- `WORKER_KEYSTORE_STAGING_BASE64`
+- `WORKER_KEYSTORE_PASSWORD_STAGING`
+- `WORKER_KEY_ALIAS_STAGING`
+- `WORKER_KEY_PASSWORD_STAGING`
+
+**Production Environment:**
+- `WORKER_KEYSTORE_PROD_BASE64`
+- `WORKER_KEYSTORE_PASSWORD_PROD`
+- `WORKER_KEY_ALIAS_PROD`
+- `WORKER_KEY_PASSWORD_PROD`
+
+#### Client Mobile - 12 Secrets
+
+**Dev Environment:**
+- `CLIENT_KEYSTORE_DEV_BASE64`
+- `CLIENT_KEYSTORE_PASSWORD_DEV`
+- `CLIENT_KEY_ALIAS_DEV`
+- `CLIENT_KEY_PASSWORD_DEV`
+
+**Staging Environment:**
+- `CLIENT_KEYSTORE_STAGING_BASE64`
+- `CLIENT_KEYSTORE_PASSWORD_STAGING`
+- `CLIENT_KEY_ALIAS_STAGING`
+- `CLIENT_KEY_PASSWORD_STAGING`
+
+**Production Environment:**
+- `CLIENT_KEYSTORE_PROD_BASE64`
+- `CLIENT_KEYSTORE_PASSWORD_PROD`
+- `CLIENT_KEY_ALIAS_PROD`
+- `CLIENT_KEY_PASSWORD_PROD`
+
+### Setup Using Helper Script
+
+We provide an interactive script to configure all secrets:
+
+```bash
+.github/scripts/setup-mobile-github-secrets.sh
+```
+
+This script will:
+1. Prompt for keystore file paths
+2. Convert keystores to base64
+3. Prompt for passwords and aliases
+4. Display GitHub CLI commands to set secrets
+5. Optionally execute the commands
+
+### Manual Setup
+
+If you prefer manual setup:
+
+```bash
+# 1. Convert keystore to base64
+base64 -i /path/to/keystore.jks | pbcopy
+
+# 2. Add to GitHub Secrets via web UI
+# Go to: Repository → Settings → Secrets and variables → Actions
+# Click "New repository secret"
+# Name: WORKER_KEYSTORE_PROD_BASE64
+# Value: Paste the base64 string
+
+# 3. Repeat for all 24 secrets
+```
+
+Or use GitHub CLI:
+
+```bash
+# Set a secret using gh CLI
+gh secret set WORKER_KEYSTORE_PROD_BASE64 < /path/to/keystore_base64.txt
+
+# Set multiple secrets
+gh secret set WORKER_KEYSTORE_PASSWORD_PROD -b "your_password"
+gh secret set WORKER_KEY_ALIAS_PROD -b "your_alias"
+gh secret set WORKER_KEY_PASSWORD_PROD -b "your_key_password"
+```
+
+### Verifying APK Signature
+
+After build, the workflow automatically verifies the APK signature using:
+
+```bash
+.github/scripts/verify-apk-signature.sh <path-to-apk> <expected-alias>
+```
+
+---
+
+## 📅 Release Cadence
+
+### Development Releases (dev)
+
+- **Frequency**: As needed (daily/weekly)
+- **Purpose**: Test features, integration testing
+- **Stability**: Unstable, may have bugs
+- **Distribution**: Internal testing only
+- **APK**: Signed with dev keystore
+- **Tag example**: `krow-withus-worker-mobile/dev-v0.0.1-m3`
+
+### Staging Releases (stage)
+
+- **Frequency**: Bi-weekly (end of sprints)
+- **Purpose**: QA testing, client demos
+- **Stability**: Stable, feature-complete
+- **Distribution**: QA team, stakeholders
+- **APK**: Signed with staging keystore
+- **Tag example**: `krow-withus-worker-mobile/stage-v0.0.1-m4`
+
+### Production Releases (prod)
+
+- **Frequency**: Monthly or milestone-based
+- **Purpose**: Public release to app stores
+- **Stability**: Production-grade, thoroughly tested
+- **Distribution**: Public (App Store, Play Store)
+- **APK**: Signed with production keystore
+- **Tag example**: `krow-withus-worker-mobile/prod-v1.0.0`
+
+---
+
+## 🛠️ Helper Scripts Reference
+
+All scripts are located in `.github/scripts/` and are used by workflows:
+
+### 1. extract-version.sh
+
+**Purpose**: Extract version from pubspec.yaml  
+**Usage**: 
+```bash
+.github/scripts/extract-version.sh <path-to-pubspec.yaml>
+```
+**Example**:
+```bash
+VERSION=$(.github/scripts/extract-version.sh apps/mobile/apps/staff/pubspec.yaml)
+echo $VERSION  # Output: 0.0.1-m4
+```
+
+### 2. generate-tag-name.sh
+
+**Purpose**: Generate consistent Git tag names  
+**Usage**:
+```bash
+.github/scripts/generate-tag-name.sh <app> <env> <version>
+```
+**Example**:
+```bash
+TAG=$(.github/scripts/generate-tag-name.sh worker dev 0.0.1-m4)
+echo $TAG  # Output: krow-withus-worker-mobile/dev-v0.0.1-m4
+```
+
+### 3. extract-release-notes.sh
+
+**Purpose**: Extract CHANGELOG section for a specific version  
+**Usage**:
+```bash
+.github/scripts/extract-release-notes.sh <app> <env> <version> <tag>
+```
+**Example**:
+```bash
+NOTES=$(.github/scripts/extract-release-notes.sh worker dev 0.0.1-m4 krow-withus-worker-mobile/dev-v0.0.1-m4)
+```
+
+**Output format**:
+```
+**Environment:** DEV
+**Tag:** krow-withus-worker-mobile/dev-v0.0.1-m4
+
+## What is new in this release
+
+[CHANGELOG content for v0.0.1-m4]
+```
+
+### 4. create-release-summary.sh
+
+**Purpose**: Generate GitHub Step Summary with emojis  
+**Usage**:
+```bash
+.github/scripts/create-release-summary.sh <app> <env> <version> <tag>
+```
+**Creates**: Formatted summary in GitHub Actions UI
+
+### 5. setup-apk-signing.sh
+
+**Purpose**: Setup APK signing environment variables  
+**Usage** (in workflow):
+```bash
+.github/scripts/setup-apk-signing.sh <app> <env>
+```
+**What it does**:
+- Decodes base64 keystore to file
+- Sets `CM_KEYSTORE_PATH_<APP>` environment variable
+- Sets keystore password, alias, and key password
+
+### 6. verify-apk-signature.sh
+
+**Purpose**: Verify APK is properly signed  
+**Usage**:
+```bash
+.github/scripts/verify-apk-signature.sh <apk-path> <expected-alias>
+```
+**Example**:
+```bash
+.github/scripts/verify-apk-signature.sh build/app/outputs/apk/release/app-release.apk androidreleasekey
+```
+
+### 7. attach-apk-to-release.sh
+
+**Purpose**: Upload APK to existing GitHub Release  
+**Usage**:
+```bash
+.github/scripts/attach-apk-to-release.sh <tag> <apk-path> <app>
+```
+**Example**:
+```bash
+.github/scripts/attach-apk-to-release.sh krow-withus-worker-mobile/dev-v0.0.1-m4 build/app/outputs/apk/release/app-release.apk worker
+```
+
+### 8. setup-mobile-github-secrets.sh
+
+**Purpose**: Interactive helper to configure all GitHub Secrets  
+**Usage**:
+```bash
+.github/scripts/setup-mobile-github-secrets.sh
+```
+**Interactive prompts for**:
+- Keystore file paths
+- Passwords and aliases
+- Generates GitHub CLI commands
+- Optionally executes commands
+
+---
+
+## 📋 Pre-Release Checklist
+
+Before triggering a release, ensure:
+
+### Code Quality
+- [ ] All automated tests pass
+- [ ] No critical linting errors
+- [ ] Code review completed (for stage/prod)
+- [ ] Security audit passed (for prod)
+
+### Documentation
+- [ ] CHANGELOG.md updated with all changes
+- [ ] Version in pubspec.yaml matches CHANGELOG
+- [ ] Breaking changes documented
+- [ ] Migration guide created (if needed)
+
+### Testing
+- [ ] Feature testing completed
+- [ ] Regression testing passed
+- [ ] Performance testing acceptable
+- [ ] Device compatibility verified
+
+### Configuration
+- [ ] Environment variables configured
+- [ ] API endpoints correct for environment
+- [ ] Feature flags set appropriately
+- [ ] Analytics tracking verified
+
+### GitHub Secrets (First-time setup)
+- [ ] All 24 secrets configured
+- [ ] Keystore passwords verified
+- [ ] Test build succeeded with signing
+
+---
+
+## 🐛 Troubleshooting
+
+### Workflow Fails: "Version not found in pubspec.yaml"
+
+**Cause**: Invalid version format or missing version  
+**Solution**:
+```yaml
+# Ensure version line in pubspec.yaml looks like:
+version: 0.0.1-m4+1
+# Not:
+version: 0.0.1  # Missing build number
+version: "0.0.1-m4+1"  # Don't quote the version
+```
+
+### Workflow Fails: "Secret not found"
+
+**Cause**: Missing GitHub Secret  
+**Solution**:
+1. Check secret name matches exactly (case-sensitive)
+2. Run `.github/scripts/setup-mobile-github-secrets.sh`
+3. Verify secrets at: Repository → Settings → Secrets and variables → Actions
+
+### APK Signing Fails
+
+**Cause**: Invalid keystore or wrong password  
+**Solution**:
+1. Verify keystore base64 encoding: `base64 -i keystore.jks | base64 -d > test.jks`
+2. Test password locally: `keytool -list -keystore test.jks`
+3. Verify alias: `keytool -list -v -keystore test.jks | grep "Alias name"`
+
+### CHANGELOG Not Extracted
+
+**Cause**: Version format doesn't match in CHANGELOG  
+**Solution**:
+```markdown
+# CHANGELOG.md must have this EXACT format:
+## [v0.0.1-m4] - Milestone 4 - 2026-03-05
+# OR
+## [0.0.1-m4] - Milestone 4 - 2026-03-05
+
+# The script tries both [vX.Y.Z] and [X.Y.Z] formats
+```
+
+### Tag Already Exists
+
+**Cause**: Trying to create a duplicate tag  
+**Solution**:
+```bash
+# Delete the existing tag (CAREFUL!)
+git tag -d krow-withus-worker-mobile/dev-v0.0.1-m4
+git push origin :refs/tags/krow-withus-worker-mobile/dev-v0.0.1-m4
+
+# Then re-run the workflow
+```
+
+---
+
+## 📚 Additional Resources
+
+### Related Documentation
+
+- [Agent Development Rules](../MOBILE/00-agent-development-rules.md)
+- [Architecture Principles](../MOBILE/01-architecture-principles.md)
+- [Mobile CI Workflow](../../.github/workflows/mobile-ci.yml)
+
+### GitHub Actions Workflows
+
+- **Product Release**: `.github/workflows/product-release.yml`
+- **Hotfix Branch Creation**: `.github/workflows/hotfix-branch-creation.yml`
+- **Mobile CI**: `.github/workflows/mobile-ci.yml`
+
+### Useful Commands
+
+```bash
+# View current version
+grep "^version:" apps/mobile/apps/staff/pubspec.yaml
+
+# List all mobile tags
+git tag -l "krow-withus-*-mobile/*"
+
+# View latest releases
+gh release list --limit 10
+
+# Download APK from release
+gh release download krow-withus-worker-mobile/dev-v0.0.1-m4 --pattern "*.apk"
+```
+
+---
+
+## 🔄 Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 2.0 | 2026-03-06 | Consolidated all release docs into single file |
+| 1.0 | 2026-03-05 | Initial separate documentation files |
+
+---
+
+**Questions or Issues?**  
+Contact the DevOps team or create an issue in the repository.