Resolved README conflict

.agent/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "mcp__paper__get_basic_info",
+      "mcp__paper__get_screenshot",
+      "mcp__paper__get_tree_summary",
+      "mcp__paper__update_styles",
+      "mcp__paper__set_text_content",
+      "mcp__paper__get_computed_styles",
+      "mcp__paper__finish_working_on_nodes",
+      "mcp__paper__get_font_family_info",
+      "mcp__paper__rename_nodes",
+      "mcp__paper__write_html",
+      "mcp__paper__get_children",
+      "mcp__paper__create_artboard",
+      "mcp__paper__delete_nodes",
+      "mcp__paper__get_jsx",
+      "mcp__paper__get_node_info",
+      "mcp__paper__duplicate_nodes"
+    ]
+  }
+}

.agent/skills/krow-mobile-architecture/SKILL.md

@@ -0,0 +1,900 @@
+---
+name: krow-mobile-architecture
+description: KROW mobile app Clean Architecture implementation including package structure, dependency rules, feature isolation, BLoC lifecycle management, session handling, and Data Connect connectors pattern. Use this when architecting new mobile features, debugging state management issues, preventing prop drilling, managing BLoC disposal, implementing session stores, or setting up connector repositories. Essential for maintaining architectural integrity across staff and client apps.
+---
+
+# KROW Mobile Architecture
+
+This skill defines the authoritative mobile architecture for the KROW platform. All code must strictly adhere to these principles to prevent architectural degradation.
+
+## When to Use This Skill
+
+- Architecting new mobile features
+- Debugging state management or BLoC lifecycle issues
+- Preventing prop drilling in UI code
+- Managing session state and authentication
+- Implementing Data Connect connector repositories
+- Setting up feature modules and dependency injection
+- Understanding package boundaries and dependencies
+- Refactoring legacy code to Clean Architecture
+
+## 1. High-Level Architecture
+
+KROW follows **Clean Architecture** in a **Melos Monorepo**. Dependencies flow **inward** toward the Domain.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Apps (Entry Points)                  │
+│  • apps/mobile/apps/client                              │
+│  • apps/mobile/apps/staff                               │
+│  Role: DI roots, navigation assembly, env config        │
+└─────────────────┬───────────────────────────────────────┘
+                  │ depends on
+┌─────────────────▼───────────────────────────────────────┐
+│                   Features (Vertical Slices)            │
+│  • apps/mobile/packages/features/client/*               │
+│  • apps/mobile/packages/features/staff/*                │
+│  Role: Pages, BLoCs, Use Cases, Feature Repositories    │
+└─────┬───────────────────────────────────────┬───────────┘
+      │ depends on                            │ depends on
+┌─────▼────────────────┐              ┌───────▼───────────┐
+│   Design System      │              │  Core Localization│
+│  • UI components     │              │  • LocaleBloc     │
+│  • Theme/colors      │              │  • Translations   │
+│  • Typography        │              │  • ErrorTranslator│
+└──────────────────────┘              └───────────────────┘
+                  │ both depend on
+┌─────────────────▼───────────────────────────────────────┐
+│               Services (Interface Adapters)             │
+│  • data_connect: Backend integration, session mgmt      │
+│  • core: Extensions, base classes, utilities            │
+└─────────────────┬───────────────────────────────────────┘
+                  │ both depend on
+┌─────────────────▼───────────────────────────────────────┐
+│                Domain (Stable Core)                     │
+│  • Entities (immutable data models)                     │
+│  • Failures (domain-specific errors)                    │
+│  • Pure Dart only, zero Flutter dependencies            │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Critical Rule:** Dependencies point INWARD only. Domain knows nothing about the outer layers.
+
+## 2. Package Structure & Responsibilities
+
+### 2.1 Apps (`apps/mobile/apps/`)
+
+**Role:** Application entry points and DI roots
+
+**Responsibilities:**
+- Initialize Flutter Modular
+- Assemble features into navigation tree
+- Inject concrete implementations (from `data_connect`) into features
+- Configure environment-specific settings (dev/stage/prod)
+- Initialize session management
+
+**Structure:**
+```
+apps/mobile/apps/staff/
+├── lib/
+│   ├── main.dart              # Entry point, session initialization
+│   ├── app_module.dart        # Root module, imports features
+│   ├── app_widget.dart        # MaterialApp setup
+│   └── src/
+│       ├── navigation/        # Typed navigators
+│       └── widgets/           # SessionListener wrapper
+└── pubspec.yaml
+```
+
+**RESTRICTION:** NO business logic. NO UI widgets (except App and Main).
+
+### 2.2 Features (`apps/mobile/packages/features/<APP>/<FEATURE>`)
+
+**Role:** Vertical slices of user-facing functionality
+
+**Internal Structure:**
+```
+features/staff/profile/
+├── lib/
+│   ├── src/
+│   │   ├── domain/
+│   │   │   ├── repositories/        # Repository interfaces
+│   │   │   │   └── profile_repository_interface.dart
+│   │   │   └── usecases/           # Application logic
+│   │   │       └── get_profile_usecase.dart
+│   │   ├── data/
+│   │   │   └── repositories_impl/   # Repository concrete classes
+│   │   │       └── profile_repository_impl.dart
+│   │   └── presentation/
+│   │       ├── blocs/              # State management
+│   │       │   └── profile_cubit.dart
+│   │       ├── pages/              # Screens (StatelessWidget preferred)
+│   │       │   └── profile_page.dart
+│   │       └── widgets/            # Reusable UI components
+│   │           └── profile_header.dart
+│   └── profile_feature.dart        # Barrel file (public API only)
+└── pubspec.yaml
+```
+
+**Key Principles:**
+- **Presentation:** UI Pages and Widgets, BLoCs/Cubits for state
+- **Application:** Use Cases (business logic orchestration)
+- **Data:** Repository implementations (backend integration)
+- **Pages as StatelessWidget:** Move state to BLoCs for better performance and testability
+
+**RESTRICTION:** Features MUST NOT import other features. Communication happens via:
+- Shared domain entities
+- Session stores (`StaffSessionStore`, `ClientSessionStore`)
+- Navigation via Modular
+- Data Connect connector repositories
+
+### 2.3 Domain (`apps/mobile/packages/domain`)
+
+**Role:** The stable, pure heart of the system
+
+**Responsibilities:**
+- Define **Entities** (immutable data models using Data Classes or Freezed)
+- Define **Failures** (domain-specific error types)
+
+**Structure:**
+```
+domain/
+├── lib/
+│   └── src/
+│       ├── entities/
+│       │   ├── user.dart
+│       │   ├── staff.dart
+│       │   └── shift.dart
+│       └── failures/
+│           ├── failure.dart        # Base class
+│           ├── auth_failure.dart
+│           └── network_failure.dart
+└── pubspec.yaml
+```
+
+**Example Entity:**
+```dart
+import 'package:equatable/equatable.dart';
+
+class Staff extends Equatable {
+  final String id;
+  final String name;
+  final String email;
+  final StaffStatus status;
+  
+  const Staff({
+    required this.id,
+    required this.name,
+    required this.email,
+    required this.status,
+  });
+  
+  @override
+  List<Object?> get props => [id, name, email, status];
+}
+```
+
+**RESTRICTION:** 
+- NO Flutter dependencies (no `import 'package:flutter/material.dart'`)
+- NO `json_annotation` or serialization code
+- Only `equatable` for value equality
+- Pure Dart only
+
+### 2.4 Data Connect (`apps/mobile/packages/data_connect`)
+
+**Role:** Interface Adapter for Backend Access
+
+**Responsibilities:**
+- Centralized connector repositories (see Data Connect Connectors Pattern section)
+- Implement Firebase Data Connect service layer
+- Map Domain Entities ↔ Data Connect generated code
+- Handle Firebase exceptions → domain failures
+- Provide `DataConnectService` with session management
+
+**Structure:**
+```
+data_connect/
+├── lib/
+│   ├── src/
+│   │   ├── services/
+│   │   │   ├── data_connect_service.dart     # Core service
+│   │   │   └── mixins/
+│   │   │       └── session_handler_mixin.dart
+│   │   ├── connectors/                        # Connector pattern (see below)
+│   │   │   ├── staff/
+│   │   │   │   ├── domain/
+│   │   │   │   │   ├── repositories/
+│   │   │   │   │   │   └── staff_connector_repository.dart
+│   │   │   │   │   └── usecases/
+│   │   │   │   │       └── get_profile_completion_usecase.dart
+│   │   │   │   └── data/
+│   │   │   │       └── repositories/
+│   │   │   │           └── staff_connector_repository_impl.dart
+│   │   │   ├── order/
+│   │   │   └── shifts/
+│   │   └── session/
+│   │       ├── staff_session_store.dart
+│   │       └── client_session_store.dart
+│   └── krow_data_connect.dart               # Exports
+└── pubspec.yaml
+```
+
+**RESTRICTION:**
+- NO feature-specific logic
+- Connectors are domain-neutral and reusable
+- All queries follow Clean Architecture (domain interfaces → data implementations)
+
+### 2.5 Design System (`apps/mobile/packages/design_system`)
+
+**Role:** Visual language and component library
+
+**Responsibilities:**
+- Theme definitions (`UiColors`, `UiTypography`)
+- UI constants (`spacingL`, `radiusM`, etc.)
+- Shared widgets (if reused across multiple features)
+- Assets (icons, images, fonts)
+
+**Structure:**
+```
+design_system/
+├── lib/
+│   └── src/
+│       ├── ui_colors.dart
+│       ├── ui_typography.dart
+│       ├── ui_icons.dart
+│       ├── ui_constants.dart
+│       ├── ui_theme.dart          # ThemeData factory
+│       └── widgets/               # Shared UI components
+│           └── custom_button.dart
+└── assets/
+    ├── icons/
+    └── images/
+```
+
+**RESTRICTION:**
+- Dumb widgets ONLY (no state management)
+- NO business logic
+- Colors and typography are IMMUTABLE (no feature can override)
+
+### 2.6 Core Localization (`apps/mobile/packages/core_localization`)
+
+**Role:** Centralized i18n management
+
+**Responsibilities:**
+- Define all user-facing strings in `l10n/`
+- Provide `LocaleBloc` for locale state management
+- Export `TranslationProvider` for `context.strings` access
+- Map domain failures to localized error messages via `ErrorTranslator`
+
+**Feature Integration:**
+```dart
+// Features access strings
+Text(context.strings.loginButton)
+
+// BLoCs emit domain failures (not strings)
+emit(AuthError(InvalidCredentialsFailure()));
+
+// UI translates failures to localized messages
+final message = ErrorTranslator.translate(failure, context.strings);
+```
+
+**App Setup:**
+```dart
+// App imports LocalizationModule
+class AppModule extends Module {
+  @override
+  List<Module> get imports => [LocalizationModule()];
+}
+
+// Wrap app with providers
+BlocProvider<LocaleBloc>(
+  create: (_) => Modular.get<LocaleBloc>(),
+  child: TranslationProvider(
+    child: MaterialApp.router(...),
+  ),
+)
+```
+
+### 2.7 Core (`apps/mobile/packages/core`)
+
+**Role:** Cross-cutting concerns
+
+**Responsibilities:**
+- Extension methods (NavigationExtensions, ListExtensions, etc.)
+- Base classes (UseCase, Failure, BlocErrorHandler)
+- Logger configuration
+- Result types for functional error handling
+
+## 3. Dependency Direction Rules
+
+1. **Domain Independence:** `domain` knows NOTHING about outer layers
+   - Defines *what* needs to be done, not *how*
+   - Pure Dart, zero Flutter dependencies
+   - Stable contracts that rarely change
+
+2. **UI Agnosticism:** Features depend on `design_system` for UI and `domain` for logic
+   - Features do NOT know about Firebase or backend details
+   - Backend changes don't affect feature implementation
+
+3. **Data Isolation:** `data_connect` depends on `domain` to know interfaces
+   - Implements domain repository interfaces
+   - Maps backend models to domain entities
+   - Does NOT know about UI
+
+**Dependency Flow:**
+```
+Apps → Features → Design System
+                → Core Localization
+                → Data Connect → Domain
+                              → Core
+```
+
+## 4. Data Connect Service & Session Management
+
+### 4.1 Session Handler Mixin
+
+**Location:** `apps/mobile/packages/data_connect/lib/src/services/mixins/session_handler_mixin.dart`
+
+**Responsibilities:**
+- Automatic token refresh (triggered when <5 minutes to expiry)
+- Firebase auth state listening
+- Role-based access validation
+- Session state stream emissions
+- 3-attempt retry with exponential backoff (1s → 2s → 4s)
+
+**Key Method:**
+```dart
+// Call once on app startup
+DataConnectService.instance.initializeAuthListener(
+  allowedRoles: ['STAFF', 'BOTH'],  // or ['CLIENT', 'BUSINESS', 'BOTH']
+);
+```
+
+### 4.2 Session Listener Widget
+
+**Location:** `apps/mobile/apps/<app>/lib/src/widgets/session_listener.dart`
+
+**Responsibilities:**
+- Wraps entire app to listen to session state changes
+- Shows user-friendly dialogs for session expiration/errors
+- Handles navigation on auth state changes
+
+**Usage:**
+```dart
+// main.dart
+runApp(
+  SessionListener(  // ← Critical wrapper
+    child: ModularApp(module: AppModule(), child: AppWidget()),
+  ),
+);
+```
+
+### 4.3 Repository Pattern with Data Connect
+
+**Step 1:** Define interface in feature domain:
+```dart
+// features/staff/profile/lib/src/domain/repositories/
+abstract interface class ProfileRepositoryInterface {
+  Future<Staff> getProfile(String id);
+}
+```
+
+**Step 2:** Implement using `DataConnectService.run()`:
+```dart
+// features/staff/profile/lib/src/data/repositories_impl/
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  final DataConnectService _service = DataConnectService.instance;
+  
+  @override
+  Future<Staff> getProfile(String id) async {
+    return await _service.run(() async {
+      final response = await _service.connector
+          .getStaffById(id: id)
+          .execute();
+      return _mapToStaff(response.data.staff);
+    });
+  }
+}
+```
+
+**Benefits of `_service.run()`:**
+- ✅ Auto validates user is authenticated
+- ✅ Refreshes token if <5 min to expiry
+- ✅ Executes the query
+- ✅ 3-attempt retry with exponential backoff
+- ✅ Maps exceptions to domain failures
+
+### 4.4 Session Store Pattern
+
+After successful auth, populate session stores:
+
+**Staff App:**
+```dart
+StaffSessionStore.instance.setSession(
+  StaffSession(
+    user: user,
+    staff: staff,
+    ownerId: ownerId,
+  ),
+);
+```
+
+**Client App:**
+```dart
+ClientSessionStore.instance.setSession(
+  ClientSession(
+    user: user,
+    business: business,
+  ),
+);
+```
+
+**Lazy Loading:** If session is null, fetch from backend and update:
+```dart
+final session = StaffSessionStore.instance.session;
+if (session?.staff == null) {
+  final staff = await getStaffById(session!.user.uid);
+  StaffSessionStore.instance.setSession(
+    session.copyWith(staff: staff),
+  );
+}
+```
+
+## 5. Feature Isolation & Communication
+
+### Zero Direct Imports
+
+```dart
+// ❌ FORBIDDEN
+import 'package:staff_profile/staff_profile.dart';  // in another feature
+
+// ✅ ALLOWED
+import 'package:krow_domain/krow_domain.dart';      // shared domain
+import 'package:krow_core/krow_core.dart';          // shared utilities
+import 'package:design_system/design_system.dart';  // shared UI
+```
+
+### Navigation: Typed Navigators with Safe Extensions
+
+**Safe Navigation Extensions** (from `core` package):
+```dart
+extension NavigationExtensions on IModularNavigator {
+  /// Safely navigate with fallback to home
+  Future<void> safeNavigate(String route) async {
+    try {
+      await navigate(route);
+    } catch (e) {
+      await navigate('/home');  // Fallback
+    }
+  }
+  
+  /// Safely push with fallback to home
+  Future<T?> safePush<T>(String route) async {
+    try {
+      return await pushNamed<T>(route);
+    } catch (e) {
+      await navigate('/home');
+      return null;
+    }
+  }
+  
+  /// Safely pop with guard against empty stack
+  void popSafe() {
+    if (canPop()) {
+      pop();
+    } else {
+      navigate('/home');
+    }
+  }
+}
+```
+
+**Typed Navigators:**
+```dart
+// apps/mobile/apps/staff/lib/src/navigation/staff_navigator.dart
+extension StaffNavigator on IModularNavigator {
+  Future<void> toStaffHome() => safeNavigate(StaffPaths.home);
+  
+  Future<void> toShiftDetails(String shiftId) => 
+      safePush('${StaffPaths.shifts}/$shiftId');
+  
+  Future<void> toProfileEdit() => safePush(StaffPaths.profileEdit);
+}
+```
+
+**Usage in Features:**
+```dart
+// ✅ CORRECT
+Modular.to.toStaffHome();
+Modular.to.toShiftDetails(shiftId: '123');
+Modular.to.popSafe();
+
+// ❌ AVOID
+Modular.to.navigate('/home');  // No safety
+Navigator.push(...);            // No Modular integration (except when popping a dialog).
+```
+
+### Data Sharing Patterns
+
+Features don't share state directly. Use:
+
+1. **Domain Repositories:** Centralized data sources
+2. **Session Stores:** `StaffSessionStore`, `ClientSessionStore` for app-wide context
+3. **Event Streams:** If needed, via `DataConnectService` streams
+4. **Navigation Arguments:** Pass IDs, not full objects
+
+## 6. App-Specific Session Management
+
+### Staff App
+
+```dart
+// main.dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  
+  DataConnectService.instance.initializeAuthListener(
+    allowedRoles: ['STAFF', 'BOTH'],
+  );
+  
+  runApp(
+    SessionListener(
+      child: ModularApp(module: StaffAppModule(), child: StaffApp()),
+    ),
+  );
+}
+```
+
+**Session Store:** `StaffSessionStore`
+- Fields: `user`, `staff`, `ownerId`
+- Lazy load: `getStaffById()` if staff is null
+
+**Navigation:**
+- Authenticated → `Modular.to.toStaffHome()`
+- Unauthenticated → `Modular.to.toInitialPage()`
+
+### Client App
+
+```dart
+// main.dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  
+  DataConnectService.instance.initializeAuthListener(
+    allowedRoles: ['CLIENT', 'BUSINESS', 'BOTH'],
+  );
+  
+  runApp(
+    SessionListener(
+      child: ModularApp(module: ClientAppModule(), child: ClientApp()),
+    ),
+  );
+}
+```
+
+**Session Store:** `ClientSessionStore`
+- Fields: `user`, `business`
+- Lazy load: `getBusinessById()` if business is null
+
+**Navigation:**
+- Authenticated → `Modular.to.toClientHome()`
+- Unauthenticated → `Modular.to.toInitialPage()`
+
+## 7. Data Connect Connectors Pattern
+
+**Problem:** Without connectors, each feature duplicates backend queries.
+
+**Solution:** Centralize all backend queries in `data_connect/connectors/`.
+
+### Structure
+
+Mirror backend connector structure:
+
+```
+data_connect/lib/src/connectors/
+├── staff/
+│   ├── domain/
+│   │   ├── repositories/
+│   │   │   └── staff_connector_repository.dart      # Interface
+│   │   └── usecases/
+│   │       └── get_profile_completion_usecase.dart
+│   └── data/
+│       └── repositories/
+│           └── staff_connector_repository_impl.dart # Implementation
+├── order/
+├── shifts/
+└── user/
+```
+
+**Maps to backend:**
+```
+backend/dataconnect/connector/
+├── staff/
+├── order/
+├── shifts/
+└── user/
+```
+
+### Clean Architecture in Connectors
+
+**Domain Interface:**
+```dart
+// staff_connector_repository.dart
+abstract interface class StaffConnectorRepository {
+  Future<bool> getProfileCompletion();
+  Future<Staff> getStaffById(String id);
+}
+```
+
+**Use Case:**
+```dart
+// get_profile_completion_usecase.dart
+class GetProfileCompletionUseCase {
+  final StaffConnectorRepository _repository;
+  
+  GetProfileCompletionUseCase({required StaffConnectorRepository repository})
+      : _repository = repository;
+  
+  Future<bool> call() => _repository.getProfileCompletion();
+}
+```
+
+**Data Implementation:**
+```dart
+// staff_connector_repository_impl.dart
+class StaffConnectorRepositoryImpl implements StaffConnectorRepository {
+  final DataConnectService _service;
+  
+  @override
+  Future<bool> getProfileCompletion() async {
+    return _service.run(() async {
+      final staffId = await _service.getStaffId();
+      final response = await _service.connector
+          .getStaffProfileCompletion(id: staffId)
+          .execute();
+      
+      return _isProfileComplete(response);
+    });
+  }
+}
+```
+
+### Feature Integration
+
+**Step 1:** Feature registers connector repository:
+```dart
+// staff_main_module.dart
+class StaffMainModule extends Module {
+  @override
+  void binds(Injector i) {
+    i.addLazySingleton<StaffConnectorRepository>(
+      StaffConnectorRepositoryImpl.new,
+    );
+    
+    i.addLazySingleton(
+      () => GetProfileCompletionUseCase(
+        repository: i.get<StaffConnectorRepository>(),
+      ),
+    );
+    
+    i.addLazySingleton(
+      () => StaffMainCubit(
+        getProfileCompletionUsecase: i.get(),
+      ),
+    );
+  }
+}
+```
+
+**Step 2:** BLoC uses it:
+```dart
+class StaffMainCubit extends Cubit<StaffMainState> {
+  final GetProfileCompletionUseCase _getProfileCompletionUsecase;
+  
+  Future<void> loadProfileCompletion() async {
+    final isComplete = await _getProfileCompletionUsecase();
+    emit(state.copyWith(isProfileComplete: isComplete));
+  }
+}
+```
+
+### Benefits
+
+✅ **No Duplication** - Query implemented once, used by many features  
+✅ **Single Source of Truth** - Backend change → update one place  
+✅ **Reusability** - Any feature can use any connector  
+✅ **Testability** - Mock connector repo to test features  
+✅ **Scalability** - Easy to add connectors as backend grows  
+
+## 8. Avoiding Prop Drilling: Direct BLoC Access
+
+### The Problem
+
+Passing data through intermediate widgets creates maintenance burden:
+
+```dart
+// ❌ BAD: Prop drilling
+ProfilePage(status: status)
+  → ProfileHeader(status: status)
+    → ProfileLevelBadge(status: status)  // Only widget that needs it
+```
+
+### The Solution: BlocBuilder in Leaf Widgets
+
+```dart
+// ✅ GOOD: Direct BLoC access
+class ProfileLevelBadge extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<ProfileCubit, ProfileState>(
+      builder: (context, state) {
+        if (state.profile == null) return const SizedBox.shrink();
+        
+        final level = _mapStatusToLevel(state.profile!.status);
+        return LevelBadgeUI(level: level);
+      },
+    );
+  }
+}
+```
+
+### Guidelines
+
+1. **Leaf Widgets Access BLoC:** Widgets needing specific data should use `BlocBuilder`
+2. **Container Widgets Stay Simple:** Parent widgets only manage layout
+3. **No Unnecessary Props:** Don't pass data to intermediate widgets
+4. **Single Responsibility:** Each widget has one reason to exist
+
+**Decision Tree:**
+```
+Does this widget need data?
+├─ YES, leaf widget → Use BlocBuilder
+├─ YES, container → Use BlocBuilder in child
+└─ NO → Don't add prop
+```
+
+## 9. BLoC Lifecycle & State Emission Safety
+
+### The Problem: StateError After Dispose
+
+When async operations complete after BLoC is closed:
+```
+StateError: Cannot emit new states after calling close
+```
+
+**Root Causes:**
+1. Transient BLoCs created with `BlocProvider(create:)` → disposed prematurely
+2. Multiple BlocProviders disposing same singleton
+3. User navigates away during async operation
+
+### The Solution: Singleton BLoCs + Safe Emit
+
+#### Step 1: Register as Singleton
+
+```dart
+// ✅ GOOD: Singleton registration
+i.addLazySingleton<ProfileCubit>(
+  () => ProfileCubit(useCase1, useCase2),
+);
+
+// ❌ BAD: Creates new instance each time
+i.add(ProfileCubit.new);
+```
+
+#### Step 2: Use BlocProvider.value()
+
+```dart
+// ✅ GOOD: Reuse singleton
+final cubit = Modular.get<ProfileCubit>();
+BlocProvider<ProfileCubit>.value(
+  value: cubit,
+  child: MyWidget(),
+)
+
+// ❌ BAD: Creates duplicate
+BlocProvider<ProfileCubit>(
+  create: (_) => Modular.get<ProfileCubit>(),
+  child: MyWidget(),
+)
+```
+
+#### Step 3: Safe Emit with BlocErrorHandler
+
+**Location:** `apps/mobile/packages/core/lib/src/presentation/mixins/bloc_error_handler.dart`
+
+```dart
+mixin BlocErrorHandler<S> on Cubit<S> {
+  void _safeEmit(void Function(S) emit, S state) {
+    try {
+      emit(state);
+    } on StateError catch (e) {
+      developer.log(
+        'Could not emit state: ${e.message}. Bloc may have been disposed.',
+        name: runtimeType.toString(),
+      );
+    }
+  }
+}
+```
+
+**Usage:**
+```dart
+class ProfileCubit extends Cubit<ProfileState> with BlocErrorHandler<ProfileState> {
+  Future<void> loadProfile() async {
+    emit(state.copyWith(status: ProfileStatus.loading));
+    
+    await handleError(
+      emit: emit,
+      action: () async {
+        final profile = await getProfile();
+        emit(state.copyWith(status: ProfileStatus.loaded, profile: profile));
+        // ✅ Safe even if BLoC disposed
+      },
+      onError: (errorKey) => state.copyWith(status: ProfileStatus.error),
+    );
+  }
+}
+```
+
+### Pattern Summary
+
+| Pattern | When to Use | Risk |
+|---------|------------|------|
+| Singleton + BlocProvider.value() | Long-lived features | Low |
+| Transient + BlocProvider(create:) | Temporary widgets | Medium |
+| Direct BlocBuilder | Leaf widgets | Low |
+
+## 10. Anti-Patterns to Avoid
+
+❌ **Feature imports feature**
+```dart
+import 'package:staff_profile/staff_profile.dart';  // in another feature
+```
+
+❌ **Business logic in BLoC**
+```dart
+on<LoginRequested>((event, emit) {
+  if (event.email.isEmpty) {  // ← Use case responsibility
+    emit(AuthError('Email required'));
+  }
+});
+```
+
+❌ **Direct Data Connect in features**
+```dart
+final response = await FirebaseDataConnect.instance.query();  // ← Use repository
+```
+
+❌ **Global state variables**
+```dart
+User? currentUser;  // ← Use SessionStore
+```
+
+❌ **Direct Navigator.push**
+```dart
+Navigator.push(context, MaterialPageRoute(...));  // ← Use Modular
+```
+
+❌ **Hardcoded navigation**
+```dart
+Modular.to.navigate('/profile');  // ← Use safe extensions
+```
+
+## Summary
+
+The architecture enforces:
+- **Clean Architecture** with strict layer boundaries
+- **Feature Isolation** via zero cross-feature imports
+- **Session Management** via DataConnectService and SessionListener
+- **Connector Pattern** for reusable backend queries
+- **BLoC Lifecycle** safety with singletons and safe emit
+- **Navigation Safety** with typed navigators and fallbacks
+
+When implementing features:
+1. Follow package structure strictly
+2. Use connector repositories for backend access
+3. Register BLoCs as singletons with `.value()`
+4. Use safe navigation extensions
+5. Avoid prop drilling with direct BLoC access
+6. Keep domain pure and stable
+
+Architecture is not negotiable. When in doubt, refer to existing well-structured features or ask for clarification.

.agent/skills/krow-mobile-design-system/SKILL.md

@@ -0,0 +1,717 @@
+---
+name: krow-mobile-design-system
+description: KROW mobile design system usage rules covering colors, typography, icons, spacing, and UI component patterns. Use this when implementing UI in KROW mobile features, matching POC designs to production, creating themed widgets, enforcing visual consistency, or reviewing UI code compliance. Prevents hardcoded values and ensures brand consistency across staff and client apps. Critical for maintaining immutable design tokens.
+---
+
+# KROW Mobile Design System Usage
+
+This skill defines mandatory standards for UI implementation using the shared `apps/mobile/packages/design_system`. All UI must consume design system tokens exclusively.
+
+## When to Use This Skill
+
+- Implementing any UI in mobile features
+- Migrating POC/prototype designs to production
+- Creating new themed widgets or components
+- Reviewing UI code for design system compliance
+- Matching colors and typography from designs
+- Adding icons, spacing, or layout elements
+- Setting up theme configuration in apps
+- Refactoring UI code with hardcoded values
+
+## Core Principle
+
+**Design tokens (colors, typography, spacing) are IMMUTABLE and defined centrally.**
+
+Features consume tokens but NEVER modify them. The design system maintains visual coherence across all apps.
+
+## 1. Design System Ownership
+
+### Centralized Authority
+
+- `apps/mobile/packages/design_system` owns:
+  - All brand assets
+  - Colors and semantic color mappings
+  - Typography and font configurations
+  - Core UI components
+  - Icons and images
+  - Spacing, radius, elevation constants
+
+### No Local Overrides
+
+**✅ CORRECT:**
+```dart
+// Feature uses design system
+import 'package:design_system/design_system.dart';
+
+Container(
+  color: UiColors.background,
+  padding: EdgeInsets.all(UiConstants.spacingL),
+  child: Text(
+    'Hello',
+    style: UiTypography.display1m,
+  ),
+)
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Custom colors in feature
+const myBlue = Color(0xFF1A2234);
+
+// ❌ Custom text styles in feature
+const myStyle = TextStyle(fontSize: 24, fontWeight: FontWeight.bold);
+
+// ❌ Theme overrides in feature
+Theme(
+  data: ThemeData(primaryColor: Colors.blue),
+  child: MyWidget(),
+)
+```
+
+### Extension Policy
+
+If a required style is missing:
+1. **FIRST:** Add it to `design_system` following existing patterns
+2. **THEN:** Use it in your feature
+
+**DO NOT** create temporary workarounds with hardcoded values.
+
+## 2. Package Structure
+
+```
+apps/mobile/packages/design_system/
+├── lib/
+│   ├── src/
+│   │   ├── ui_colors.dart          # Color tokens
+│   │   ├── ui_typography.dart      # Text styles
+│   │   ├── ui_icons.dart           # Icon exports
+│   │   ├── ui_constants.dart       # Spacing, radius, elevation
+│   │   ├── ui_theme.dart           # ThemeData factory
+│   │   └── widgets/                # Shared UI components
+│   │       ├── custom_button.dart
+│   │       └── custom_app_bar.dart
+│   └── design_system.dart          # Public exports
+├── assets/
+│   ├── icons/
+│   ├── images/
+│   └── fonts/
+└── pubspec.yaml
+```
+
+## 3. Colors Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiColors for all color needs
+Container(color: UiColors.background)
+Text('Hello', style: TextStyle(color: UiColors.foreground))
+Icon(Icons.home, color: UiColors.primary)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Hardcoded hex colors
+Container(color: Color(0xFF1A2234))
+
+// ❌ Material color constants
+Container(color: Colors.blue)
+
+// ❌ Opacity on hardcoded colors
+Container(color: Color(0xFF1A2234).withOpacity(0.5))
+```
+
+### Available Color Categories
+
+**Brand Colors:**
+- `UiColors.primary` - Main brand color
+- `UiColors.secondary` - Secondary brand color
+- `UiColors.accent` - Accent highlights
+
+**Semantic Colors:**
+- `UiColors.background` - Page background
+- `UiColors.foreground` - Primary text color
+- `UiColors.card` - Card/container background
+- `UiColors.border` - Border colors
+- `UiColors.mutedForeground` - Secondary text
+
+**Status Colors:**
+- `UiColors.success` - Success states
+- `UiColors.warning` - Warning states
+- `UiColors.error` - Error states
+- `UiColors.info` - Information states
+
+### Color Matching from POCs
+
+When migrating POC designs:
+
+1. **Find closest match** in `UiColors`
+2. **Use existing color** even if slightly different
+3. **DO NOT add new colors** without design team approval
+
+**Example Process:**
+```dart
+// POC has: Color(0xFF2C3E50)
+// Find closest: UiColors.background or UiColors.card
+// Use: UiColors.card
+
+// POC has: Color(0xFF27AE60)
+// Find closest: UiColors.success
+// Use: UiColors.success
+```
+
+### Theme Access
+
+Colors can also be accessed via theme:
+```dart
+// Both are valid:
+Container(color: UiColors.primary)
+Container(color: Theme.of(context).colorScheme.primary)
+```
+
+## 4. Typography Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiTypography for all text
+Text('Title', style: UiTypography.display1m)
+Text('Body', style: UiTypography.body1r)
+Text('Label', style: UiTypography.caption1m)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Custom TextStyle
+Text('Title', style: TextStyle(
+  fontSize: 24,
+  fontWeight: FontWeight.bold,
+))
+
+// ❌ Manual font configuration
+Text('Body', style: TextStyle(
+  fontFamily: 'Inter',
+  fontSize: 16,
+))
+
+// ❌ Modifying existing styles inline
+Text('Title', style: UiTypography.display1m.copyWith(
+  fontSize: 28,  // ← Don't override size
+))
+```
+
+### Available Typography Styles
+
+**Display Styles (Large Headers):**
+- `UiTypography.display1m` - Display Medium
+- `UiTypography.display1sb` - Display Semi-Bold
+- `UiTypography.display1b` - Display Bold
+
+**Heading Styles:**
+- `UiTypography.heading1m` - H1 Medium
+- `UiTypography.heading1sb` - H1 Semi-Bold
+- `UiTypography.heading1b` - H1 Bold
+- `UiTypography.heading2m` - H2 Medium
+- `UiTypography.heading2sb` - H2 Semi-Bold
+
+**Body Styles:**
+- `UiTypography.body1r` - Body Regular
+- `UiTypography.body1m` - Body Medium
+- `UiTypography.body1sb` - Body Semi-Bold
+- `UiTypography.body2r` - Body 2 Regular
+
+**Caption/Label Styles:**
+- `UiTypography.caption1m` - Caption Medium
+- `UiTypography.caption1sb` - Caption Semi-Bold
+- `UiTypography.label1m` - Label Medium
+
+### Allowed Customizations
+
+**✅ ALLOWED (Color Only):**
+```dart
+// You MAY change color
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(
+    color: UiColors.error,  // ← OK
+  ),
+)
+```
+
+**❌ FORBIDDEN (Size, Weight, Family):**
+```dart
+// ❌ Don't change size
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontSize: 28),
+)
+
+// ❌ Don't change weight
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontWeight: FontWeight.w900),
+)
+
+// ❌ Don't change family
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontFamily: 'Roboto'),
+)
+```
+
+### Typography Matching from POCs
+
+When migrating:
+1. Identify text role (heading, body, caption)
+2. Find closest matching style in `UiTypography`
+3. Use existing style even if size/weight differs slightly
+
+## 5. Icons Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiIcons
+Icon(UiIcons.home)
+Icon(UiIcons.profile)
+Icon(UiIcons.chevronLeft)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Direct icon library imports
+import 'package:lucide_icons/lucide_icons.dart';
+Icon(LucideIcons.home)
+
+// ❌ Font Awesome direct
+import 'package:font_awesome_flutter/font_awesome_flutter.dart';
+FaIcon(FontAwesomeIcons.house)
+```
+
+### Why Centralize Icons?
+
+1. **Consistency:** Same icon for same action everywhere
+2. **Branding:** Unified icon set with consistent stroke weight
+3. **Swappability:** Change icon library in one place
+
+### Icon Libraries
+
+Design system uses:
+- `typedef _IconLib = LucideIcons;` (primary)
+- `typedef _IconLib2 = FontAwesomeIcons;` (secondary)
+
+**Features MUST NOT import these directly.**
+
+### Adding New Icons
+
+If icon missing:
+1. Add to `ui_icons.dart`:
+```dart
+class UiIcons {
+  static const home = _IconLib.home;
+  static const newIcon = _IconLib.newIcon;  // Add here
+}
+```
+2. Use in feature:
+```dart
+Icon(UiIcons.newIcon)
+```
+
+## 6. Spacing & Layout Constants
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiConstants for spacing
+Padding(padding: EdgeInsets.all(UiConstants.spacingL))
+SizedBox(height: UiConstants.spacingM)
+Container(
+  padding: EdgeInsets.symmetric(
+    horizontal: UiConstants.spacingL,
+    vertical: UiConstants.spacingM,
+  ),
+)
+
+// Use UiConstants for radius
+Container(
+  decoration: BoxDecoration(
+    borderRadius: BorderRadius.circular(UiConstants.radiusM),
+  ),
+)
+
+// Use UiConstants for elevation
+elevation: UiConstants.elevationLow
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Magic numbers
+Padding(padding: EdgeInsets.all(16.0))
+SizedBox(height: 24.0)
+BorderRadius.circular(8.0)
+elevation: 2.0
+```
+
+### Available Constants
+
+**Spacing:**
+```dart
+UiConstants.spacingXs   // Extra small
+UiConstants.spacingS    // Small
+UiConstants.spacingM    // Medium
+UiConstants.spacingL    // Large
+UiConstants.spacingXl   // Extra large
+UiConstants.spacing2xl  // 2x Extra large
+```
+
+**Border Radius:**
+```dart
+UiConstants.radiusS     // Small
+UiConstants.radiusM     // Medium
+UiConstants.radiusL     // Large
+UiConstants.radiusXl    // Extra large
+UiConstants.radiusFull  // Fully rounded
+```
+
+**Elevation:**
+```dart
+UiConstants.elevationNone
+UiConstants.elevationLow
+UiConstants.elevationMedium
+UiConstants.elevationHigh
+```
+
+## 7. Smart Widgets Usage
+
+### When to Use
+
+- **Prefer standard Flutter Material widgets** styled via theme
+- **Use design system widgets** for non-standard patterns
+- **Create new widgets** in design system if reused >3 features
+
+### Navigation in Widgets
+
+Widgets with navigation MUST use safe methods:
+
+**✅ CORRECT:**
+```dart
+// In UiAppBar back button:
+import 'package:flutter_modular/flutter_modular.dart';
+import 'package:krow_core/krow_core.dart';
+
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Modular.to.popSafe(),  // ← Safe pop
+)
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Direct Navigator
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Navigator.pop(context),
+)
+
+// ❌ Unsafe Modular
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Modular.to.pop(),  // Can crash
+)
+```
+
+### Composition Over Inheritance
+
+**✅ CORRECT:**
+```dart
+// Compose standard widgets
+Container(
+  padding: EdgeInsets.all(UiConstants.spacingL),
+  decoration: BoxDecoration(
+    color: UiColors.card,
+    borderRadius: BorderRadius.circular(UiConstants.radiusM),
+  ),
+  child: Column(
+    children: [
+      Text('Title', style: UiTypography.heading1sb),
+      SizedBox(height: UiConstants.spacingM),
+      Text('Body', style: UiTypography.body1r),
+    ],
+  ),
+)
+```
+
+**❌ AVOID:**
+```dart
+// ❌ Deep custom widget hierarchies
+class CustomCard extends StatelessWidget {
+  // Complex custom implementation
+}
+```
+
+## 8. Theme Configuration
+
+### App Setup
+
+Apps initialize theme ONCE in root MaterialApp:
+
+**✅ CORRECT:**
+```dart
+// apps/mobile/apps/staff/lib/app_widget.dart
+import 'package:design_system/design_system.dart';
+
+class StaffApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(
+      theme: StaffTheme.light,  // ← Design system theme
+      darkTheme: StaffTheme.dark,  // ← Optional dark mode
+      themeMode: ThemeMode.system,
+      // ...
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Custom theme in app
+MaterialApp.router(
+  theme: ThemeData(
+    primaryColor: Colors.blue,  // ← NO!
+  ),
+)
+
+// ❌ Theme override in feature
+Theme(
+  data: ThemeData(...),
+  child: MyFeatureWidget(),
+)
+```
+
+### Accessing Theme
+
+**Both methods valid:**
+```dart
+// Method 1: Direct design system import
+import 'package:design_system/design_system.dart';
+Text('Hello', style: UiTypography.body1r)
+
+// Method 2: Via theme context
+Text('Hello', style: Theme.of(context).textTheme.bodyMedium)
+```
+
+**Prefer Method 1** for explicit type safety.
+
+## 9. POC → Production Workflow
+
+### Step 1: Implement Structure (POC Matching)
+
+Implement UI layout exactly matching POC:
+```dart
+// Temporary: Match POC visually
+Container(
+  color: Color(0xFF1A2234),  // ← POC color
+  padding: EdgeInsets.all(16.0),  // ← POC spacing
+  child: Text(
+    'Title',
+    style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),  // ← POC style
+  ),
+)
+```
+
+**Purpose:** Ensure visual parity with POC before refactoring.
+
+### Step 2: Architecture Refactor
+
+Move to Clean Architecture:
+- Extract business logic to use cases
+- Move state management to BLoCs
+- Implement repository pattern
+- Use dependency injection
+
+### Step 3: Design System Integration
+
+Replace hardcoded values:
+```dart
+// Production: Design system tokens
+Container(
+  color: UiColors.background,  // ← Found closest match
+  padding: EdgeInsets.all(UiConstants.spacingL),  // ← Used constant
+  child: Text(
+    'Title',
+    style: UiTypography.heading1sb,  // ← Matched typography
+  ),
+)
+```
+
+**Color Matching:**
+- POC `#1A2234` → `UiColors.background`
+- POC `#3498DB` → `UiColors.primary`
+- POC `#27AE60` → `UiColors.success`
+
+**Typography Matching:**
+- POC `24px bold` → `UiTypography.heading1sb`
+- POC `16px regular` → `UiTypography.body1r`
+- POC `14px medium` → `UiTypography.caption1m`
+
+**Spacing Matching:**
+- POC `16px` → `UiConstants.spacingL`
+- POC `8px` → `UiConstants.spacingM`
+- POC `4px` → `UiConstants.spacingS`
+
+## 10. Anti-Patterns & Common Mistakes
+
+### ❌ Magic Numbers
+```dart
+// BAD
+EdgeInsets.all(12.0)
+SizedBox(height: 24.0)
+BorderRadius.circular(8.0)
+
+// GOOD
+EdgeInsets.all(UiConstants.spacingM)
+SizedBox(height: UiConstants.spacingL)
+BorderRadius.circular(UiConstants.radiusM)
+```
+
+### ❌ Local Themes
+```dart
+// BAD
+Theme(
+  data: ThemeData(primaryColor: Colors.blue),
+  child: MyWidget(),
+)
+
+// GOOD
+// Use global theme defined in app
+```
+
+### ❌ Hex Hunting
+```dart
+// BAD: Copy-paste from Figma
+Container(color: Color(0xFF3498DB))
+
+// GOOD: Find matching design system color
+Container(color: UiColors.primary)
+```
+
+### ❌ Direct Icon Library
+```dart
+// BAD
+import 'package:lucide_icons/lucide_icons.dart';
+Icon(LucideIcons.home)
+
+// GOOD
+Icon(UiIcons.home)
+```
+
+### ❌ Custom Text Styles
+```dart
+// BAD
+Text('Title', style: TextStyle(
+  fontSize: 24,
+  fontWeight: FontWeight.bold,
+  fontFamily: 'Inter',
+))
+
+// GOOD
+Text('Title', style: UiTypography.heading1sb)
+```
+
+## 11. Design System Review Checklist
+
+Before merging UI code:
+
+### ✅ Design System Compliance
+- [ ] No hardcoded `Color(...)` or `0xFF...` hex values
+- [ ] No custom `TextStyle(...)` definitions
+- [ ] All spacing uses `UiConstants.spacing*`
+- [ ] All radius uses `UiConstants.radius*`
+- [ ] All elevation uses `UiConstants.elevation*`
+- [ ] All icons from `UiIcons`, not direct library imports
+- [ ] Theme consumed from design system, no local overrides
+- [ ] Layout matches POC intent using design system primitives
+
+### ✅ Architecture Compliance
+- [ ] No business logic in widgets
+- [ ] State managed by BLoCs
+- [ ] Navigation uses Modular safe extensions
+- [ ] Localization used for all text (no hardcoded strings)
+- [ ] No direct Data Connect queries in widgets
+
+### ✅ Code Quality
+- [ ] Widget build methods concise (<50 lines)
+- [ ] Complex widgets extracted to separate files
+- [ ] Meaningful widget names
+- [ ] Doc comments on reusable widgets
+
+## 12. When to Extend Design System
+
+### Add New Color
+**When:** New brand color approved by design team
+
+**Process:**
+1. Add to `ui_colors.dart`:
+```dart
+class UiColors {
+  static const myNewColor = Color(0xFF123456);
+}
+```
+2. Update theme if needed
+3. Use in features
+
+### Add New Typography Style
+**When:** New text style pattern emerges across multiple features
+
+**Process:**
+1. Add to `ui_typography.dart`:
+```dart
+class UiTypography {
+  static const myNewStyle = TextStyle(
+    fontSize: 20,
+    fontWeight: FontWeight.w600,
+    fontFamily: _fontFamily,
+  );
+}
+```
+2. Use in features
+
+### Add Shared Widget
+**When:** Widget reused in 3+ features
+
+**Process:**
+1. Create in `lib/src/widgets/`:
+```dart
+// my_widget.dart
+class MyWidget extends StatelessWidget {
+  // Implementation using design system tokens
+}
+```
+2. Export from `design_system.dart`
+3. Use across features
+
+## Summary
+
+**Core Rules:**
+1. **All colors from `UiColors`** - Zero hex codes in features
+2. **All typography from `UiTypography`** - Zero custom TextStyle
+3. **All spacing/radius/elevation from `UiConstants`** - Zero magic numbers
+4. **All icons from `UiIcons`** - Zero direct library imports
+5. **Theme defined once** in app entry point
+6. **POC → Production** requires design system integration step
+
+**The Golden Rule:** Design system is immutable. Features adapt to the system, not the other way around.
+
+When implementing UI:
+1. Import `package:design_system/design_system.dart`
+2. Use design system tokens exclusively
+3. Match POC intent with available tokens
+4. Request new tokens only when truly necessary
+5. Never create temporary hardcoded workarounds
+
+Visual consistency is non-negotiable. Every pixel must come from the design system.

.agent/skills/krow-mobile-development-rules/SKILL.md

@@ -0,0 +1,646 @@
+---
+name: krow-mobile-development-rules
+description: Enforce KROW mobile app development standards including file structure, naming conventions, logic placement boundaries, localization, Data Connect integration, and prototype migration rules. Use this skill whenever working on KROW Flutter mobile features, creating new packages, implementing BLoCs, integrating with backend, or migrating from prototypes. Critical for maintaining clean architecture and preventing architectural degradation.
+---
+
+# KROW Mobile Development Rules
+
+These rules are **NON-NEGOTIABLE** enforcement guidelines for the KROW mobile application. They prevent architectural degradation and ensure consistency across the codebase.
+
+## When to Use This Skill
+
+- Creating new mobile features or packages
+- Implementing BLoCs, Use Cases, or Repositories
+- Integrating with Firebase Data Connect backend
+- Migrating code from prototypes
+- Reviewing mobile code for compliance
+- Setting up new feature modules
+- Handling user sessions and authentication
+- Implementing navigation flows
+
+## 1. File Creation & Package Structure
+
+### Feature-First Packaging
+
+**✅ DO:**
+- Create new features as independent packages:
+  ```
+  apps/mobile/packages/features/<app_name>/<feature_name>/
+  ├── lib/
+  │   ├── src/
+  │   │   ├── domain/
+  │   │   │   ├── repositories/
+  │   │   │   └── usecases/
+  │   │   ├── data/
+  │   │   │   └── repositories_impl/
+  │   │   └── presentation/
+  │   │       ├── blocs/
+  │   │       ├── pages/
+  │   │       └── widgets/
+  │   └── <feature_name>.dart  # Barrel file
+  └── pubspec.yaml
+  ```
+
+**❌ DON'T:**
+- Add features to `apps/mobile/packages/core` directly
+- Create files in app directories (`apps/mobile/apps/client/` or `apps/mobile/apps/staff/`)
+- Create cross-feature or cross-app dependencies (features must not import other features)
+
+### Path Conventions (Strict)
+
+Follow these exact paths:
+
+| Layer | Path Pattern | Example |
+|-------|-------------|---------|
+| **Entities** | `apps/mobile/packages/domain/lib/src/entities/<entity>.dart` | `user.dart`, `shift.dart` |
+| **Repository Interface** | `.../features/<app>/<feature>/lib/src/domain/repositories/<name>_repository_interface.dart` | `auth_repository_interface.dart` |
+| **Repository Impl** | `.../features/<app>/<feature>/lib/src/data/repositories_impl/<name>_repository_impl.dart` | `auth_repository_impl.dart` |
+| **Use Cases** | `.../features/<app>/<feature>/lib/src/application/<name>_usecase.dart` | `login_usecase.dart` |
+| **BLoCs** | `.../features/<app>/<feature>/lib/src/presentation/blocs/<name>_bloc.dart` | `auth_bloc.dart` |
+| **Pages** | `.../features/<app>/<feature>/lib/src/presentation/pages/<name>_page.dart` | `login_page.dart` |
+| **Widgets** | `.../features/<app>/<feature>/lib/src/presentation/widgets/<name>_widget.dart` | `password_field.dart` |
+
+### Barrel Files
+
+**✅ DO:**
+```dart
+// lib/auth_feature.dart
+export 'src/presentation/pages/login_page.dart';
+export 'src/domain/repositories/auth_repository_interface.dart';
+// Only export PUBLIC API
+```
+
+**❌ DON'T:**
+```dart
+// Don't export internal implementation details
+export 'src/data/repositories_impl/auth_repository_impl.dart';
+export 'src/presentation/blocs/auth_bloc.dart';
+```
+
+## 2. Naming Conventions (Dart Standard)
+
+| Type | Convention | Example | File Name |
+|------|-----------|---------|-----------|
+| **Files** | `snake_case` | `user_profile_page.dart` | - |
+| **Classes** | `PascalCase` | `UserProfilePage` | - |
+| **Variables** | `camelCase` | `userProfile` | - |
+| **Interfaces** | End with `Interface` | `AuthRepositoryInterface` | `auth_repository_interface.dart` |
+| **Implementations** | End with `Impl` | `AuthRepositoryImpl` | `auth_repository_impl.dart` |
+| **BLoCs** | End with `Bloc` or `Cubit` | `AuthBloc`, `ProfileCubit` | `auth_bloc.dart` |
+| **Use Cases** | End with `UseCase` | `LoginUseCase` | `login_usecase.dart` |
+
+## 3. Logic Placement (Zero Tolerance Boundaries)
+
+### Business Rules → Use Cases ONLY
+
+**✅ CORRECT:**
+```dart
+// login_usecase.dart
+class LoginUseCase extends UseCase<User, LoginParams> {
+  @override
+  Future<Either<Failure, User>> call(LoginParams params) async {
+    // Business logic here: validation, transformation, orchestration
+    if (params.email.isEmpty) {
+      return Left(ValidationFailure('Email required'));
+    }
+    return await repository.login(params);
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Business logic in BLoC
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) {
+    if (event.email.isEmpty) {  // ← NO! This is business logic
+      emit(AuthError('Email required'));
+    }
+  });
+}
+
+// ❌ Business logic in Widget
+class LoginPage extends StatelessWidget {
+  void _login() {
+    if (_emailController.text.isEmpty) {  // ← NO! This is business logic
+      showSnackbar('Email required');
+    }
+  }
+}
+```
+
+### State Logic → BLoCs ONLY
+
+**✅ CORRECT:**
+```dart
+// auth_bloc.dart
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) async {
+    emit(AuthLoading());
+    final result = await loginUseCase(LoginParams(email: event.email));
+    result.fold(
+      (failure) => emit(AuthError(failure)),
+      (user) => emit(AuthAuthenticated(user)),
+    );
+  });
+}
+
+// login_page.dart (StatelessWidget)
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<AuthBloc, AuthState>(
+      builder: (context, state) {
+        if (state is AuthLoading) return LoadingIndicator();
+        if (state is AuthError) return ErrorWidget(state.message);
+        return LoginForm();
+      },
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ setState in Pages for complex state
+class LoginPage extends StatefulWidget {
+  @override
+  State<LoginPage> createState() => _LoginPageState();
+}
+
+class _LoginPageState extends State<LoginPage> {
+  bool _isLoading = false;  // ← NO! Use BLoC
+  String? _error;          // ← NO! Use BLoC
+  
+  void _login() {
+    setState(() => _isLoading = true);  // ← NO! Use BLoC
+  }
+}
+```
+
+**RECOMMENDATION:** Pages should be `StatelessWidget` with state delegated to BLoCs.
+
+### Data Transformation → Repositories
+
+**✅ CORRECT:**
+```dart
+// profile_repository_impl.dart
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  @override
+  Future<Staff> getProfile(String id) async {
+    final response = await dataConnect.getStaffById(id: id).execute();
+    // Data transformation happens here
+    return Staff(
+      id: response.data.staff.id,
+      name: response.data.staff.name,
+      // Map Data Connect model to Domain entity
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ JSON parsing in UI
+class ProfilePage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    final json = jsonDecode(response.body);  // ← NO!
+    final name = json['name'];
+  }
+}
+
+// ❌ JSON parsing in Domain Use Case
+class GetProfileUseCase extends UseCase<Staff, String> {
+  @override
+  Future<Either<Failure, Staff>> call(String id) async {
+    final response = await http.get('/staff/$id');
+    final json = jsonDecode(response.body);  // ← NO!
+  }
+}
+```
+
+### Navigation → Flutter Modular + Safe Extensions
+
+**✅ CORRECT:**
+```dart
+// Use Safe Navigation Extensions
+import 'package:krow_core/krow_core.dart';
+
+// In widget/BLoC:
+Modular.to.safePush('/profile');
+Modular.to.safeNavigate('/home');
+Modular.to.popSafe();
+
+// Even better: Use Typed Navigators
+Modular.to.toStaffHome();  // Defined in StaffNavigator
+Modular.to.toShiftDetails(shiftId: '123');
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Direct Navigator.push
+Navigator.push(
+  context,
+  MaterialPageRoute(builder: (_) => ProfilePage()),
+);
+
+// ❌ Direct Modular navigation without safety
+Modular.to.navigate('/profile');  // ← Can cause blank screens
+Modular.to.pop();  // ← Can crash if stack is empty
+```
+
+**PATTERN:** All navigation MUST have fallback to Home page. Safe extensions automatically handle this.
+
+### Session Management → DataConnectService + SessionHandlerMixin
+
+**✅ CORRECT:**
+```dart
+// In main.dart:
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  
+  // Initialize session listener (pick allowed roles for app)
+  DataConnectService.instance.initializeAuthListener(
+    allowedRoles: ['STAFF', 'BOTH'],  // for staff app
+  );
+  
+  runApp(
+    SessionListener(  // Wraps entire app
+      child: ModularApp(module: AppModule(), child: AppWidget()),
+    ),
+  );
+}
+
+// In repository:
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  final DataConnectService _service = DataConnectService.instance;
+  
+  @override
+  Future<Staff> getProfile(String id) async {
+    // _service.run() handles:
+    // - Auth validation
+    // - Token refresh (if <5 min to expiry)
+    // - Error handling with 3 retries
+    return await _service.run(() async {
+      final response = await _service.connector
+          .getStaffById(id: id)
+          .execute();
+      return _mapToStaff(response.data.staff);
+    });
+  }
+}
+```
+
+**PATTERN:**
+- **SessionListener** widget wraps app and shows dialogs for session errors
+- **SessionHandlerMixin** in `DataConnectService` provides automatic token refresh
+- **3-attempt retry logic** with exponential backoff (1s → 2s → 4s)
+- **Role validation** configurable per app
+
+## 4. Localization Integration (core_localization)
+
+All user-facing text MUST be localized.
+
+### String Management
+
+**✅ CORRECT:**
+```dart
+// In presentation layer:
+import 'package:core_localization/core_localization.dart';
+
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Text(context.strings.loginButton);  // ← From localization
+    return ElevatedButton(
+      onPressed: _login,
+      child: Text(context.strings.submit),
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Hardcoded English strings
+Text('Login')
+Text('Submit')
+ElevatedButton(child: Text('Click here'))
+```
+
+### BLoC Integration
+
+**✅ CORRECT:**
+```dart
+// BLoCs emit domain failures (not localized strings)
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) async {
+    final result = await loginUseCase(params);
+    result.fold(
+      (failure) => emit(AuthError(failure)),  // ← Domain failure
+      (user) => emit(AuthAuthenticated(user)),
+    );
+  });
+}
+
+// UI translates failures to user-friendly messages
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<AuthBloc, AuthState>(
+      builder: (context, state) {
+        if (state is AuthError) {
+          final message = ErrorTranslator.translate(
+            state.failure,
+            context.strings,
+          );
+          return ErrorWidget(message);  // ← Localized
+        }
+      },
+    );
+  }
+}
+```
+
+### App Setup
+
+Apps must import `LocalizationModule()`:
+```dart
+// app_module.dart
+class AppModule extends Module {
+  @override
+  List<Module> get imports => [
+    LocalizationModule(),  // ← Required
+    DataConnectModule(),
+  ];
+}
+
+// main.dart
+runApp(
+  BlocProvider<LocaleBloc>(  // ← Expose locale state
+    create: (_) => Modular.get<LocaleBloc>(),
+    child: TranslationProvider(  // ← Enable context.strings
+      child: MaterialApp.router(...),
+    ),
+  ),
+);
+```
+
+## 5. Data Connect Integration
+
+All backend access goes through `DataConnectService`.
+
+### Repository Pattern
+
+**Step 1:** Define interface in feature domain:
+```dart
+// domain/repositories/profile_repository_interface.dart
+abstract interface class ProfileRepositoryInterface {
+  Future<Staff> getProfile(String id);
+  Future<bool> updateProfile(Staff profile);
+}
+```
+
+**Step 2:** Implement using `DataConnectService.run()`:
+```dart
+// data/repositories_impl/profile_repository_impl.dart
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  final DataConnectService _service = DataConnectService.instance;
+  
+  @override
+  Future<Staff> getProfile(String id) async {
+    return await _service.run(() async {
+      final response = await _service.connector
+          .getStaffById(id: id)
+          .execute();
+      return _mapToStaff(response.data.staff);
+    });
+  }
+}
+```
+
+**Benefits of `_service.run()`:**
+- ✅ Automatic auth validation
+- ✅ Token refresh if needed
+- ✅ 3-attempt retry with exponential backoff
+- ✅ Consistent error handling
+
+### Session Store Pattern
+
+After successful auth, populate session stores:
+```dart
+// For Staff App:
+StaffSessionStore.instance.setSession(
+  StaffSession(
+    user: user,
+    staff: staff,
+    ownerId: ownerId,
+  ),
+);
+
+// For Client App:
+ClientSessionStore.instance.setSession(
+  ClientSession(
+    user: user,
+    business: business,
+  ),
+);
+```
+
+**Lazy Loading:** If session is null, fetch via `getStaffById()` or `getBusinessById()` and update store.
+
+## 6. Prototype Migration Rules
+
+When migrating from `prototypes/`:
+
+### ✅ MAY Copy
+- Icons, images, assets (but match to design system)
+- `build` methods for UI layout structure
+- Screen flow and navigation patterns
+
+### ❌ MUST REJECT & REFACTOR
+- `GetX`, `Provider`, or `MVC` patterns
+- Any state management not using BLoC
+- Direct HTTP calls (must use Data Connect)
+- Hardcoded colors/typography (must use design system)
+- Global state variables
+- Navigation without Modular
+
+### Colors & Typography Migration
+**When matching POC to production:**
+1. Find closest color in `UiColors` (don't add new colors without approval)
+2. Find closest text style in `UiTypography`
+3. Use design system constants, NOT POC hardcoded values
+
+**DO NOT change the design system itself.** Colors and typography are FINAL. Match your feature to the system, not the other way around.
+
+## 7. Handling Ambiguity
+
+If requirements are unclear:
+
+1. **STOP** - Don't guess domain fields or workflows
+2. **ANALYZE** - Refer to:
+   - Architecture: `apps/mobile/docs/01-architecture-principles.md`
+   - Design System: `apps/mobile/docs/02-design-system-usage.md`
+   - Existing features for patterns
+3. **DOCUMENT** - Add `// ASSUMPTION: <explanation>` if you must proceed
+4. **ASK** - Prefer asking user for clarification on business rules
+
+## 8. Dependencies
+
+### DO NOT
+- Add 3rd party packages without checking `apps/mobile/packages/core` first
+- Add `firebase_auth` or `firebase_data_connect` to Feature packages (they belong in `data_connect` only)
+- Use `addSingleton` for BLoCs (always use `add` method in Modular)
+
+### DO
+- Use `DataConnectService.instance` for backend operations
+- Use Flutter Modular for dependency injection
+- Register BLoCs with `i.addSingleton<CubitType>(() => CubitType(...))`
+- Register Use Cases as factories or singletons as needed
+
+## 9. Error Handling Pattern
+
+### Domain Failures
+```dart
+// domain/failures/auth_failure.dart
+abstract class AuthFailure extends Failure {
+  const AuthFailure(String message) : super(message);
+}
+
+class InvalidCredentialsFailure extends AuthFailure {
+  const InvalidCredentialsFailure() : super('Invalid credentials');
+}
+```
+
+### Repository Error Mapping
+```dart
+// Map Data Connect exceptions to Domain failures
+try {
+  final response = await dataConnect.query();
+  return Right(response);
+} on DataConnectException catch (e) {
+  if (e.message.contains('unauthorized')) {
+    return Left(InvalidCredentialsFailure());
+  }
+  return Left(ServerFailure(e.message));
+}
+```
+
+### UI Feedback
+```dart
+// BLoC emits error state
+emit(AuthError(failure));
+
+// UI shows user-friendly message
+if (state is AuthError) {
+  final message = ErrorTranslator.translate(state.failure, context.strings);
+  ScaffoldMessenger.of(context).showSnackBar(
+    SnackBar(content: Text(message)),
+  );
+}
+```
+
+### Session Errors
+`SessionListener` automatically shows dialogs for:
+- Session expiration
+- Token refresh failures
+- Network errors during auth
+
+## 10. Testing Requirements
+
+### Unit Tests
+```dart
+// Test use cases with real repository implementations
+test('login with valid credentials returns user', () async {
+  final useCase = LoginUseCase(repository: mockRepository);
+  final result = await useCase(LoginParams(email: 'test@test.com'));
+  expect(result.isRight(), true);
+});
+```
+
+### Widget Tests
+```dart
+// Test UI widgets and BLoC interactions
+testWidgets('shows loading indicator when logging in', (tester) async {
+  await tester.pumpWidget(
+    BlocProvider<AuthBloc>(
+      create: (_) => authBloc,
+      child: LoginPage(),
+    ),
+  );
+  
+  authBloc.add(LoginRequested(email: 'test@test.com'));
+  await tester.pump();
+  
+  expect(find.byType(LoadingIndicator), findsOneWidget);
+});
+```
+
+### Integration Tests
+- Test full feature flows end-to-end with Data Connect
+- Use dependency injection to swap implementations if needed
+
+## 11. Clean Code Principles
+
+### Documentation
+- ✅ Add human readable doc comments for `dartdoc`  for all classes and methods.
+```dart
+/// Authenticates user with email and password.
+/// 
+/// Returns [User] on success or [AuthFailure] on failure.
+/// Throws [NetworkException] if connection fails.
+class LoginUseCase extends UseCase<User, LoginParams> {
+  // ...
+}
+```
+
+### Single Responsibility
+- Keep methods focused on one task
+- Extract complex logic to separate methods
+- Keep widget build methods concise
+- Extract complex widgets to separate files
+
+### Meaningful Names
+```dart
+// ✅ GOOD
+final isProfileComplete = await checkProfileCompletion();
+final userShifts = await fetchUserShifts();
+
+// ❌ BAD
+final flag = await check();
+final data = await fetch();
+```
+
+## Enforcement Checklist
+
+Before merging any mobile feature code:
+
+### Architecture Compliance
+- [ ] Feature follows package structure (domain/data/presentation)
+- [ ] No business logic in BLoCs or Widgets
+- [ ] All state management via BLoCs
+- [ ] All backend access via repositories
+- [ ] Session accessed via SessionStore, not global state
+- [ ] Navigation uses Flutter Modular safe extensions
+- [ ] No feature-to-feature imports
+
+### Code Quality
+- [ ] No hardcoded strings (use localization)
+- [ ] No hardcoded colors/typography (use design system)
+- [ ] All spacing uses UiConstants
+- [ ] Doc comments on public APIs
+- [ ] Meaningful variable names
+- [ ] Zero analyzer warnings
+
+### Integration
+- [ ] Data Connect queries via `_service.run()`
+- [ ] Error handling with domain failures
+- [ ] Proper dependency injection in modules
+
+## Summary
+
+The key principle: **Clean Architecture with zero tolerance for violations.** Business logic in Use Cases, state in BLoCs, data access in Repositories, UI in Widgets. Features are isolated, backend is centralized, localization is mandatory, and design system is immutable.
+
+When in doubt, refer to existing features following these patterns or ask for clarification. It's better to ask than to introduce architectural debt.

.agent/skills/krow-mobile-release/SKILL.md

@@ -0,0 +1,778 @@
+---
+name: krow-mobile-release
+description: KROW mobile app release process including versioning strategy, CHANGELOG management, GitHub Actions workflows, APK signing, Git tagging, and hotfix procedures. Use this when preparing mobile releases, updating CHANGELOGs, triggering release workflows, creating hotfix branches, troubleshooting release issues, or documenting release features. Covers both staff (worker) and client mobile products across dev/stage/prod environments.
+---
+
+# KROW Mobile Release Process
+
+This skill defines the comprehensive release process for KROW mobile applications (staff and client). It covers versioning, changelog management, GitHub Actions automation, and hotfix procedures.
+
+## When to Use This Skill
+
+- Preparing for a mobile app release
+- Updating CHANGELOG files with new features
+- Triggering GitHub Actions release workflows
+- Creating hotfix branches for production issues
+- Understanding version numbering strategy
+- Setting up APK signing secrets
+- Troubleshooting release workflow failures
+- Documenting release notes
+- Managing release cadence (dev → stage → prod)
+
+## Quick Reference
+
+### Release Workflows
+- **Product Release:** [GitHub Actions - Product Release](https://github.com/Oloodi/krow-workforce/actions/workflows/product-release.yml)
+- **Hotfix Creation:** [GitHub Actions - Product Hotfix](https://github.com/Oloodi/krow-workforce/actions/workflows/hotfix-branch-creation.yml)
+
+### Key Files
+- **Staff CHANGELOG:** `apps/mobile/apps/staff/CHANGELOG.md`
+- **Client CHANGELOG:** `apps/mobile/apps/client/CHANGELOG.md`
+- **Staff Version:** `apps/mobile/apps/staff/pubspec.yaml`
+- **Client Version:** `apps/mobile/apps/client/pubspec.yaml`
+
+### Comprehensive Documentation
+For complete details, see: [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) (900+ lines)
+
+## 1. Versioning Strategy
+
+### Format
+
+```
+v{major}.{minor}.{patch}-{milestone}
+```
+
+**Examples:**
+- `v0.0.1-m4` - Milestone 4 release
+- `v0.1.0-m5` - Minor version bump for Milestone 5
+- `v1.0.0` - First production release (no milestone suffix)
+
+### Semantic Versioning Rules
+
+**Major (X.0.0):**
+- Breaking changes
+- Complete architecture overhaul
+- Incompatible API changes
+
+**Minor (0.X.0):**
+- New features
+- Backwards-compatible additions
+- Milestone completions
+
+**Patch (0.0.X):**
+- Bug fixes
+- Security patches
+- Performance improvements
+
+**Milestone Suffix:**
+- `-m1`, `-m2`, `-m3`, `-m4`, etc.
+- Indicates pre-production milestone phase
+- Removed for production releases
+
+### Version Location
+
+Versions are defined in `pubspec.yaml`:
+
+**Staff App:**
+```yaml
+# apps/mobile/apps/staff/pubspec.yaml
+name: krow_staff_app
+version: 0.0.1-m4+1  # version+build_number
+```
+
+**Client App:**
+```yaml
+# apps/mobile/apps/client/pubspec.yaml
+name: krow_client_app
+version: 0.0.1-m4+1
+```
+
+**Format:** `version+build`
+- `version`: Semantic version with milestone (e.g., `0.0.1-m4`)
+- `build`: Build number (increments with each build, e.g., `+1`, `+2`)
+
+## 2. CHANGELOG Management
+
+### Format
+
+Each app maintains a separate CHANGELOG following [Keep a Changelog](https://keepachangelog.com/) format.
+
+**Structure:**
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- New feature descriptions
+
+### Changed
+- Modified feature descriptions
+
+### Fixed
+- Bug fix descriptions
+
+### Removed
+- Removed feature descriptions
+
+## [0.0.1-m4] - Milestone 4 - 2026-03-05
+
+### Added
+- Profile management with 13 subsections
+- Documents & certificates management
+- Benefits overview section
+- Camera/gallery support for attire verification
+
+### Changed
+- Enhanced session management with auto token refresh
+
+### Fixed
+- Navigation fallback to home on invalid routes
+```
+
+### Section Guidelines
+
+**[Unreleased]**
+- Work in progress
+- Features merged to dev but not released
+- Updated continuously during development
+
+**[Version] - Milestone X - Date**
+- Released version
+- Format: `[X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
+- Organized by change type (Added/Changed/Fixed/Removed)
+
+### Change Type Definitions
+
+**Added:**
+- New features
+- New UI screens
+- New API integrations
+- New user-facing capabilities
+
+**Changed:**
+- Modifications to existing features
+- UI/UX improvements
+- Performance enhancements
+- Refactored code (if user-facing impact)
+
+**Fixed:**
+- Bug fixes
+- Error handling improvements
+- Crash fixes
+- UI/UX issues resolved
+
+**Removed:**
+- Deprecated features
+- Removed screens or capabilities
+- Discontinued integrations
+
+### Writing Guidelines
+
+**✅ GOOD:**
+```markdown
+### Added
+- Profile management with 13 subsections organized into onboarding, compliance, finances, and support categories
+- Documents & certificates management with upload, status tracking, and expiry dates
+- Camera and gallery support for attire verification with photo capture
+- Benefits overview section displaying perks and company information
+```
+
+**❌ BAD:**
+```markdown
+### Added
+- New stuff
+- Fixed things
+- Updated code
+```
+
+**Key Principles:**
+- Be specific and descriptive
+- Focus on user-facing changes
+- Mention UI screens, features, or capabilities
+- Avoid technical jargon users won't understand
+- Group related changes together
+
+### Updating CHANGELOG Workflow
+
+**Step 1:** During development, add to `[Unreleased]`:
+```markdown
+## [Unreleased]
+
+### Added
+- New shift calendar view with month/week toggle
+- Shift acceptance confirmation dialog
+
+### Fixed
+- Navigation crash when popping empty stack
+```
+
+**Step 2:** Before release, move to version section:
+```markdown
+## [0.1.0-m5] - Milestone 5 - 2026-03-15
+
+### Added
+- New shift calendar view with month/week toggle
+- Shift acceptance confirmation dialog
+
+### Fixed
+- Navigation crash when popping empty stack
+
+## [Unreleased]
+<!-- Empty for next development cycle -->
+```
+
+**Step 3:** Update version in `pubspec.yaml`:
+```yaml
+version: 0.1.0-m5+1
+```
+
+## 3. Git Tagging Strategy
+
+### Tag Format
+
+```
+krow-withus-<app>-mobile/<env>-vX.Y.Z
+```
+
+**Components:**
+- `<app>`: `worker` (staff) or `client`
+- `<env>`: `dev`, `stage`, or `prod`
+- `vX.Y.Z`: Semantic version (from pubspec.yaml)
+
+**Examples:**
+```
+krow-withus-worker-mobile/dev-v0.0.1-m4
+krow-withus-worker-mobile/stage-v0.0.1-m4
+krow-withus-worker-mobile/prod-v0.0.1-m4
+krow-withus-client-mobile/dev-v0.0.1-m4
+```
+
+### Tag Creation
+
+Tags are created automatically by GitHub Actions workflows. Manual tagging:
+
+```bash
+# Staff app - dev environment
+git tag krow-withus-worker-mobile/dev-v0.0.1-m4
+git push origin krow-withus-worker-mobile/dev-v0.0.1-m4
+
+# Client app - prod environment
+git tag krow-withus-client-mobile/prod-v1.0.0
+git push origin krow-withus-client-mobile/prod-v1.0.0
+```
+
+### Tag Listing
+
+```bash
+# List all mobile tags
+git tag -l "krow-withus-*-mobile/*"
+
+# List staff app tags
+git tag -l "krow-withus-worker-mobile/*"
+
+# List production tags
+git tag -l "krow-withus-*-mobile/prod-*"
+```
+
+## 4. GitHub Actions Workflows
+
+### 4.1 Product Release Workflow
+
+**File:** `.github/workflows/product-release.yml`
+
+**Purpose:** Automated production releases with APK signing
+
+**Trigger:** Manual dispatch via GitHub UI
+
+**Inputs:**
+- `app`: Select `worker` (staff) or `client`
+- `environment`: Select `dev`, `stage`, or `prod`
+
+**Process:**
+1. ✅ Extracts version from `pubspec.yaml` automatically
+2. ✅ Builds signed APKs for selected app
+3. ✅ Creates GitHub release with CHANGELOG notes
+4. ✅ Tags release (e.g., `krow-withus-worker-mobile/dev-v0.0.1-m4`)
+5. ✅ Uploads APKs as release assets
+6. ✅ Generates step summary with emojis
+
+**Key Features:**
+- **No manual version input** - reads from pubspec.yaml
+- **APK signing** - uses GitHub Secrets for keystore
+- **CHANGELOG extraction** - pulls release notes automatically
+- **Visual feedback** - emojis in all steps
+
+**Usage:**
+```
+1. Go to: GitHub Actions → "📦 Product Release"
+2. Click "Run workflow"
+3. Select app (worker/client)
+4. Select environment (dev/stage/prod)
+5. Click "Run workflow"
+6. Wait for completion (~5-10 minutes)
+```
+
+**Release Naming:**
+```
+Krow With Us - Worker Product - DEV - v0.0.1-m4
+Krow With Us - Client Product - PROD - v1.0.0
+```
+
+### 4.2 Product Hotfix Workflow
+
+**File:** `.github/workflows/hotfix-branch-creation.yml`
+
+**Purpose:** Emergency production fix automation
+
+**Trigger:** Manual dispatch with version input
+
+**Inputs:**
+- `current_version`: Current production version (e.g., `0.0.1-m4`)
+- `issue_description`: Brief description of the hotfix
+
+**Process:**
+1. ✅ Creates `hotfix/<version>` branch from latest production tag
+2. ✅ Auto-increments PATCH version (e.g., `0.0.1-m4` → `0.0.2-m4`)
+3. ✅ Updates `pubspec.yaml` with new version
+4. ✅ Updates `CHANGELOG.md` with hotfix section
+5. ✅ Creates PR back to main branch
+6. ✅ Includes hotfix instructions in PR description
+
+**Usage:**
+```
+1. Go to: GitHub Actions → "🚨 Product Hotfix - Create Branch"
+2. Click "Run workflow"
+3. Enter current production version (e.g., 0.0.1-m4)
+4. Enter issue description (e.g., "critical crash on login")
+5. Click "Run workflow"
+6. Workflow creates branch and PR
+7. Fix bug on hotfix branch
+8. Merge PR to main
+9. Use Product Release workflow to deploy
+```
+
+**Hotfix Branch Naming:**
+```
+hotfix/0.0.2-m4-critical-crash-on-login
+```
+
+### 4.3 Helper Scripts
+
+**Location:** `.github/scripts/`
+
+**Available Scripts:**
+1. **extract-version.sh** - Extract version from pubspec.yaml
+2. **generate-tag-name.sh** - Generate standardized tag names
+3. **extract-release-notes.sh** - Extract CHANGELOG sections
+4. **create-release-summary.sh** - Generate GitHub Step Summary with emojis
+
+**Script Permissions:**
+```bash
+chmod +x .github/scripts/*.sh
+```
+
+**Usage Example:**
+```bash
+# Extract version from staff app
+.github/scripts/extract-version.sh apps/mobile/apps/staff/pubspec.yaml
+
+# Generate tag name
+.github/scripts/generate-tag-name.sh worker dev 0.0.1-m4
+
+# Extract release notes for version
+.github/scripts/extract-release-notes.sh apps/mobile/apps/staff/CHANGELOG.md 0.0.1-m4
+```
+
+## 5. APK Signing Setup
+
+### Required GitHub Secrets (24 Total)
+
+**Per App (12 secrets each):**
+
+**Staff (Worker) App:**
+```
+STAFF_UPLOAD_KEYSTORE_BASE64       # Base64-encoded keystore file
+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 file
+```
+
+**Client App:**
+```
+CLIENT_UPLOAD_KEYSTORE_BASE64
+CLIENT_UPLOAD_STORE_PASSWORD
+CLIENT_UPLOAD_KEY_ALIAS
+CLIENT_UPLOAD_KEY_PASSWORD
+CLIENT_KEYSTORE_PROPERTIES_BASE64
+```
+
+### Generating Secrets
+
+**Step 1: Create Keystore**
+
+```bash
+# For staff app
+keytool -genkey -v \
+  -keystore staff-upload-keystore.jks \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -alias staff-upload
+
+# For client app
+keytool -genkey -v \
+  -keystore client-upload-keystore.jks \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -alias client-upload
+```
+
+**Step 2: Base64 Encode**
+
+```bash
+# Encode keystore
+base64 -i staff-upload-keystore.jks | tr -d '\n' > staff-keystore.txt
+
+# Encode key.properties
+base64 -i key.properties | tr -d '\n' > key-props.txt
+```
+
+**Step 3: Add to GitHub Secrets**
+
+```
+Repository → Settings → Secrets and variables → Actions → New repository secret
+```
+
+Add each secret:
+- Name: `STAFF_UPLOAD_KEYSTORE_BASE64`
+- Value: Contents of `staff-keystore.txt`
+
+Repeat for all 24 secrets.
+
+### key.properties Format
+
+```properties
+storePassword=your_store_password
+keyPassword=your_key_password
+keyAlias=staff-upload
+storeFile=../staff-upload-keystore.jks
+```
+
+## 6. Release Process (Step-by-Step)
+
+### Standard Release (Dev/Stage/Prod)
+
+**Step 1: Prepare CHANGELOG**
+
+Update `CHANGELOG.md` with all changes since last release:
+```markdown
+## [0.1.0-m5] - Milestone 5 - 2026-03-15
+
+### Added
+- Shift calendar with month/week views
+- Enhanced navigation with typed routes
+- Profile completion wizard
+
+### Fixed
+- Session token refresh timing
+- Navigation fallback logic
+```
+
+**Step 2: Update Version**
+
+Edit `pubspec.yaml`:
+```yaml
+version: 0.1.0-m5+1  # Changed from 0.0.1-m4+1
+```
+
+**Step 3: Commit and Push**
+
+```bash
+git add apps/mobile/apps/staff/CHANGELOG.md
+git add apps/mobile/apps/staff/pubspec.yaml
+git commit -m "chore(staff): prepare v0.1.0-m5 release"
+git push origin dev
+```
+
+**Step 4: Trigger Workflow**
+
+1. Go to GitHub Actions → "📦 Product Release"
+2. Click "Run workflow"
+3. Select branch: `dev`
+4. Select app: `worker` (or `client`)
+5. Select environment: `dev` (or `stage`, `prod`)
+6. Click "Run workflow"
+
+**Step 5: Monitor Progress**
+
+Watch workflow execution:
+- ⏳ Version extraction
+- ⏳ APK building
+- ⏳ APK signing
+- ⏳ GitHub Release creation
+- ⏳ Tag creation
+- ⏳ Asset upload
+
+**Step 6: Verify Release**
+
+1. Check GitHub Releases page
+2. Download APK to verify
+3. Install on test device
+4. Verify version in app
+
+### Hotfix Release
+
+**Step 1: Identify Production Issue**
+
+- Critical bug in production
+- User-reported crash
+- Security vulnerability
+
+**Step 2: Trigger Hotfix Workflow**
+
+1. Go to GitHub Actions → "🚨 Product Hotfix - Create Branch"
+2. Click "Run workflow"
+3. Enter current version: `0.0.1-m4`
+4. Enter description: `Critical crash on login screen`
+5. Click "Run workflow"
+
+**Step 3: Review Created Branch**
+
+Workflow creates:
+- Branch: `hotfix/0.0.2-m4-critical-crash-on-login`
+- PR to `main` branch
+- Updated `pubspec.yaml`: `0.0.2-m4+1`
+- Updated `CHANGELOG.md` with hotfix section
+
+**Step 4: Fix Bug**
+
+```bash
+git checkout hotfix/0.0.2-m4-critical-crash-on-login
+
+# Make fixes
+# ... code changes ...
+
+git add .
+git commit -m "fix(auth): resolve crash on login screen"
+git push origin hotfix/0.0.2-m4-critical-crash-on-login
+```
+
+**Step 5: Merge PR**
+
+1. Review PR on GitHub
+2. Approve and merge to `main`
+3. Delete hotfix branch
+
+**Step 6: Release to Production**
+
+1. Use Product Release workflow
+2. Select `main` branch
+3. Select `prod` environment
+4. Deploy hotfix
+
+## 7. Release Cadence
+
+### Development (dev)
+
+- **Frequency:** Multiple times per day
+- **Purpose:** Testing features in dev environment
+- **Branch:** `dev`
+- **Audience:** Internal development team
+- **Approval:** Not required
+
+### Staging (stage)
+
+- **Frequency:** 1-2 times per week
+- **Purpose:** QA testing, stakeholder demos
+- **Branch:** `main`
+- **Audience:** QA team, stakeholders
+- **Approval:** Tech lead approval
+
+### Production (prod)
+
+- **Frequency:** Every 2-3 weeks (milestone completion)
+- **Purpose:** End-user releases
+- **Branch:** `main`
+- **Audience:** All users
+- **Approval:** Product owner + tech lead approval
+
+### Milestone Releases
+
+- **Frequency:** Every 2-4 weeks
+- **Version Bump:** Minor version (e.g., `0.1.0-m5` → `0.2.0-m6`)
+- **Process:**
+  1. Complete all milestone features
+  2. Update CHANGELOG with comprehensive release notes
+  3. Deploy to stage for final QA
+  4. After approval, deploy to prod
+  5. Create GitHub release with milestone summary
+
+## 8. Troubleshooting
+
+### Workflow Fails: Version Extraction
+
+**Error:** "Could not extract version from pubspec.yaml"
+
+**Solutions:**
+1. Verify `pubspec.yaml` exists at expected path
+2. Check version format: `version: X.Y.Z-mN+B`
+3. Ensure no extra spaces or tabs
+4. Verify file is committed and pushed
+
+### Workflow Fails: APK Signing
+
+**Error:** "Keystore password incorrect"
+
+**Solutions:**
+1. Verify GitHub Secrets are set correctly
+2. Re-generate and re-encode keystore
+3. Check key.properties format
+4. Ensure passwords don't contain special characters that need escaping
+
+### Workflow Fails: CHANGELOG Extraction
+
+**Error:** "Could not find version in CHANGELOG"
+
+**Solutions:**
+1. Verify CHANGELOG format matches: `## [X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
+2. Check square brackets are present
+3. Ensure version matches pubspec.yaml
+4. Add version section if missing
+
+### Tag Already Exists
+
+**Error:** "tag already exists"
+
+**Solutions:**
+1. Delete existing tag locally and remotely:
+```bash
+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
+```
+2. Re-run workflow
+
+### Build Fails: Flutter Errors
+
+**Error:** "flutter build failed"
+
+**Solutions:**
+1. Test build locally first:
+```bash
+cd apps/mobile/apps/staff
+flutter build apk --release
+```
+2. Fix any analyzer errors
+3. Ensure all dependencies are compatible
+4. Clear build cache:
+```bash
+flutter clean
+flutter pub get
+```
+
+## 9. Local Testing
+
+Before triggering workflows, test builds locally:
+
+### Building APKs Locally
+
+**Staff App:**
+```bash
+cd apps/mobile/apps/staff
+flutter clean
+flutter pub get
+flutter build apk --release
+```
+
+**Client App:**
+```bash
+cd apps/mobile/apps/client
+flutter clean
+flutter pub get
+flutter build apk --release
+```
+
+### Testing Release Notes
+
+Extract CHANGELOG section:
+```bash
+.github/scripts/extract-release-notes.sh \
+  apps/mobile/apps/staff/CHANGELOG.md \
+  0.0.1-m4
+```
+
+### Verifying Version
+
+Extract version from pubspec:
+```bash
+.github/scripts/extract-version.sh \
+  apps/mobile/apps/staff/pubspec.yaml
+```
+
+## 10. Best Practices
+
+### CHANGELOG
+- ✅ Update continuously during development
+- ✅ Be specific and user-focused
+- ✅ Group related changes
+- ✅ Include UI/UX changes
+- ❌ Don't include technical debt or refactoring (unless user-facing)
+- ❌ Don't use vague descriptions
+
+### Versioning
+- ✅ Use semantic versioning strictly
+- ✅ Increment patch for bug fixes
+- ✅ Increment minor for new features
+- ✅ Keep milestone suffix until production
+- ❌ Don't skip versions
+- ❌ Don't use arbitrary version numbers
+
+### Git Tags
+- ✅ Follow standard format
+- ✅ Let workflow create tags automatically
+- ✅ Keep tags synced with releases
+- ❌ Don't create tags manually unless necessary
+- ❌ Don't reuse deleted tags
+
+### Workflows
+- ✅ Test builds locally first
+- ✅ Monitor workflow execution
+- ✅ Verify release assets
+- ✅ Test APK on device before announcing
+- ❌ Don't trigger multiple workflows simultaneously
+- ❌ Don't bypass approval process
+
+## Summary
+
+**Release Process Overview:**
+1. Update CHANGELOG with changes
+2. Update version in pubspec.yaml
+3. Commit and push to appropriate branch
+4. Trigger Product Release workflow
+5. Monitor execution and verify release
+6. Test APK on device
+7. Announce to team/users
+
+**Key Files:**
+- `apps/mobile/apps/staff/CHANGELOG.md`
+- `apps/mobile/apps/client/CHANGELOG.md`
+- `apps/mobile/apps/staff/pubspec.yaml`
+- `apps/mobile/apps/client/pubspec.yaml`
+
+**Key Workflows:**
+- Product Release (standard releases)
+- Product Hotfix (emergency fixes)
+
+**For Complete Details:**
+See [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) - 900+ line comprehensive guide with:
+- Detailed APK signing setup
+- Complete troubleshooting guide
+- All helper scripts documentation
+- Release checklist
+- Security best practices
+
+When in doubt, refer to the comprehensive documentation or ask for clarification before releasing to production.

.agent/skills/krow-paper-design/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: krow-paper-design
+description: KROW Paper design file conventions covering design tokens, component patterns, screen structure, and naming rules. Use this when creating or updating screens in the Paper design tool, auditing designs for token compliance, building new flows, or restructuring existing frames. Ensures visual consistency across all Paper design files for the KROW staff and client apps.
+---
+
+# KROW Paper Design Conventions
+
+This skill defines the design token system, component patterns, screen structure conventions, and workflow rules established for the KROW Design Revamp Paper file. All design work in Paper must follow these conventions.
+
+## When to Use This Skill
+
+- Creating new screens or flows in Paper
+- Updating existing frames to match the design system
+- Auditing designs for token compliance
+- Adding components (buttons, chips, inputs, badges, cards)
+- Structuring shift detail pages, onboarding flows, or list screens
+- Setting up navigation patterns (back buttons, bottom nav, CTAs)
+- Reviewing Paper designs before handoff to development
+
+## 1. Design Tokens
+
+### Color Palette
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Primary | `#0A39DF` | CTAs, active states, links, selected chips, nav active icons, pay rates |
+| Foreground | `#121826` | Headings, primary text, dark UI elements |
+| Text Secondary | `#6A7382` | Labels, captions, inactive nav, section headers, placeholder text, back chevrons |
+| Secondary BG | `#F1F3F5` | Subtle backgrounds, dividers, map placeholders |
+| Border | `#D1D5DB` | Card borders, unselected chip borders, outline button borders |
+| Input Border | `#E2E8F0` | Text input borders (lighter than general border) |
+| Destructive | `#F04444` | Error states, destructive actions (e.g., Request Swap) |
+| Background | `#FAFBFC` | Page/artboard background |
+| Card BG | `#FFFFFF` | Card surfaces, input backgrounds |
+| Success | `#059669` | Active status dot, checkmark icons, requirement met |
+| Warning Amber | `#D97706` | Urgent/Pending badge text |
+
+### Semantic Badge Colors
+
+| Badge | Background | Text Color |
+|-------|-----------|------------|
+| Active | `#ECFDF5` | `#059669` |
+| Confirmed | `#EBF0FF` | `#0A39DF` |
+| Pending | `#FEF9EE` | `#D97706` |
+| Urgent | `#FEF9EE` | `#D97706` |
+| One-Time | `#ECFDF5` | `#059669` |
+| Recurring | `#EBF0FF` | `#0A39DF` (use `#EFF6FF` bg on detail pages) |
+
+### Typography
+
+| Style | Font | Size | Weight | Line Height | Usage |
+|-------|------|------|--------|-------------|-------|
+| Display | Inter Tight | 28px | 700 | 34px | Page titles (Find Shifts, My Shifts) |
+| H1 | Inter Tight | 24px | 700 | 30px | Detail page titles (venue names) |
+| H2 | Inter Tight | 20px | 700 | 26px | Section headings |
+| H3 | Inter Tight | 18px | 700 | 22px | Card titles, schedule values |
+| Body Large | Manrope | 16px | 600 | 20px | Button text, CTA labels |
+| Body Default | Manrope | 14px | 400-500 | 18px | Body text, descriptions |
+| Body Small | Manrope | 13px | 400-500 | 16px | Card metadata, time/pay info |
+| Caption | Manrope | 12px | 500-600 | 16px | Small chip text, tab labels |
+| Section Label | Manrope | 11px | 700 | 14px | Uppercase section headers (letter-spacing: 0.06em) |
+| Badge Text | Manrope | 11px | 600-700 | 14px | Status badge labels (letter-spacing: 0.04em) |
+| Nav Label | Manrope | 10px | 600 | 12px | Bottom nav labels |
+
+### Spacing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Page padding | 24px | Horizontal padding from screen edge |
+| Section gap | 16-24px | Between major content sections |
+| Group gap | 8-12px | Within a section (e.g., label to input) |
+| Element gap | 4px | Tight spacing (e.g., subtitle under title) |
+| Bottom safe area | 40px | Padding below last element / CTA |
+
+### Border Radii
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| sm | 8px | Small chips, badges, status pills, map placeholder |
+| md | 12px | Cards, inputs, location cards, contact cards, search fields |
+| lg | 14px | Buttons, CTA containers, shift cards (Find Shifts) |
+| xl | 24px | Not commonly used |
+| pill | 999px | Progress bar segments only |
+
+## 2. Component Patterns
+
+### Buttons
+
+**Primary CTA:**
+- Background: `#0A39DF`, radius: 14px, height: 52px
+- Text: Manrope 16px/600, color: `#FFFFFF`
+- Padding: 16px vertical, 16px horizontal
+
+**Secondary/Outline Button:**
+- Background: `#FFFFFF`, border: 1.5px `#D1D5DB`, radius: 14px, height: 52px
+- Text: Manrope 16px/600, color: `#121826`
+
+**Destructive Outline Button:**
+- Background: `#FFFFFF`, border: 1.5px `#F04444`, radius: 14px
+- Text: Manrope 14px/600, color: `#F04444`
+
+**Back Icon Button (Bottom CTA):**
+- 52x52px square, border: 1.5px `#D1D5DB`, radius: 14px, background: `#FFFFFF`
+- Contains chevron-left SVG (20x20, viewBox 0 0 24 24, stroke `#121826`, strokeWidth 2)
+- Path: `M15 18L9 12L15 6`
+
+### Chips
+
+**Default (Large) - for role/skill selection:**
+- Selected: bg `#EFF6FF`, border 1.5px `#0A39DF`, radius 10px, padding 12px/16px
+  - Checkmark icon (14x14, stroke `#0A39DF`), text Manrope 14px/600 `#0A39DF`
+- Unselected: bg `#FFFFFF`, border 1.5px `#6A7382`, radius 10px, padding 12px/16px
+  - Text Manrope 14px/500 `#6A7382`
+
+**Small - for tabs, filters:**
+- Selected: bg `#EFF6FF`, border 1.5px `#0A39DF`, radius 8px, padding 6px/12px
+  - Checkmark icon (12x12), text Manrope 12px/600 `#0A39DF`
+- Unselected: bg `#FFFFFF`, border 1.5px `#D1D5DB`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/500 `#6A7382`
+- Active (filled): bg `#0A39DF`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/600 `#FFFFFF`
+- Dark (filters button): bg `#121826`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/600 `#FFFFFF`, with leading icon
+
+**Status Badges:**
+- Radius: 8px, padding: 4px/8px
+- Text: Manrope 11px/600-700, uppercase, letter-spacing 0.04em
+- Colors follow semantic badge table above
+
+### Text Inputs
+
+- Border: 1.5px `#E2E8F0`, radius: 12px, padding: 12px/14px
+- Background: `#FFFFFF`
+- Placeholder: Manrope 14px/400, color `#6A7382`
+- Filled: Manrope 14px/500, color `#121826`
+- Label above: Manrope 14px/500, color `#121826`
+- Focused: border color `#0A39DF`, border-width 2px
+- Error: border color `#F04444`, helper text `#F04444`
+
+### Cards (Shift List Items)
+
+- Background: `#FFFFFF`, border: 1px `#D1D5DB`, radius: 12-14px
+- Padding: 16px
+- Content: venue name (Manrope 15px/600 `#121826`), subtitle (Manrope 13px/400 `#6A7382`)
+- Metadata row: icon (14px, `#6A7382`) + text (Manrope 13px/500 `#6A7382`)
+- Pay rate: Inter Tight 18px/700 `#0A39DF`
+
+### Schedule/Pay Info Cards
+
+- Two-column layout with 12px gap
+- Background: `#FFFFFF`, border: 1px `#D1D5DB`, radius: 12px, padding: 16px
+- Label: Manrope 11px/500-700 uppercase `#6A7382` (letter-spacing 0.05em)
+- Value: Inter Tight 18px/700 `#121826` (schedule) or `#121826` (pay)
+- Sub-text: Manrope 13px/400 `#6A7382`
+
+### Contact/Info Rows
+
+- Container: radius 12px, border 1px `#D1D5DB`, background `#FFFFFF`, overflow clip
+- Row: padding 13px/16px, gap 10px, border-bottom 1px `#F1F3F5` (except last)
+- Icon: 16px, stroke `#6A7382`
+- Label: Manrope 13px/500 `#6A7382`, width 72px fixed
+- Value: Manrope 13px/500 `#121826` (or `#0A39DF` for phone/links)
+
+### Section Headers
+
+- Text: Manrope 11px/700, uppercase, letter-spacing 0.06em, color `#6A7382`
+- Gap to content below: 10px
+
+## 3. Screen Structure
+
+### Artboard Setup
+
+- Width: 390px (iPhone standard)
+- Height: 844px (default), or `fit-content` for scrollable detail pages
+- Background: `#FAFBFC`
+- Flex column layout, overflow: clip
+
+### Frame Naming Convention
+
+```
+<app>-<section>-<screen_number>-<screen_name>
+```
+
+Examples:
+- `staff-1-1-splash`
+- `staff-2-3-personal-information`
+- `staff-4-1-my-shifts`
+- `staff-5-2-shift-details`
+- `shift-5-3-confirmation`
+
+Section headers use: `<number> - <Section Name>` (e.g., `4 - My Shifts`)
+
+### Status Bar
+
+- Height: 44px, full width (390px)
+- Left: "9:41" text (system font)
+- Right: Signal, WiFi, Battery SVG icons (68px wide)
+
+### Header Back Button
+
+- Placed below status bar in a combined "Status Bar + Back" frame (390x72px)
+- Chevron SVG: 20x20, viewBox 0 0 24 24, stroke `#6A7382`, strokeWidth 2
+- Path: `M15 18L9 12L15 6`
+- Back button frame: 390x28px, padding-left: 24px
+
+### Progress Bar (Onboarding)
+
+- Container: 342px wide (24px margins), 3px height segments
+- Segments: pill radius (999px), gap between
+- Filled: `#0A39DF`, Unfilled: `#F1F3F5`
+
+### Bottom CTA Convention
+
+- Pinned to bottom using `marginTop: auto` on the CTA container
+- Layout: flex row, gap 12px, padding 0 24px
+- Back button: 52x52px icon-only button with chevron-left (stroke `#121826`)
+- Primary CTA: flex 1, height 52px, radius 14px, bg `#0A39DF`
+- Bottom safe padding: 40px (on artboard paddingBottom)
+
+### Bottom Navigation Bar
+
+- Full width, padding: 10px top, 28px bottom
+- Border-top: 1px `#F1F3F5`, background: `#FFFFFF`
+- 5 items: Home, Shifts, Find, Payments, Profile
+- Active: icon stroke `#0A39DF`, label Manrope 10px/600 `#0A39DF`
+- Inactive: icon stroke `#6A7382`, label Manrope 10px/600 `#6A7382`
+- Active icon may have light fill (e.g., `#EBF0FF` on calendar/search)
+
+## 4. Screen Templates
+
+### List Screen (My Shifts, Find Shifts)
+
+```
+Artboard (390x844, bg #FAFBFC)
+  Status Bar (390x44)
+  Header Section
+    Page Title (Display: Inter Tight 28px/700)
+    Tab/Filter Chips (Small chip variant)
+  Content
+    Date Header (Section label style, uppercase)
+    Shift Cards (12px radius, 1px border #D1D5DB)
+  Bottom Nav Bar
+```
+
+### Detail Screen (Shift Details)
+
+```
+Artboard (390x fit-content, bg #FAFBFC)
+  Status Bar (390x44)
+  Header Bar (Back chevron + "Shift Details" title + share icon)
+  Badges Row (status chips)
+  Role Title (H1) + Venue (with avatar)
+  Schedule/Pay Cards (two-column)
+  Job Description (section label + body text)
+  Location (card with map + address)
+  Requirements (section label + checkmark list)
+  Shift Contact (section label + contact card with rows)
+  [Optional] Note from Manager (warm bg card)
+  Bottom CTA (pinned)
+```
+
+### Onboarding Screen
+
+```
+Artboard (390x844, bg #FAFBFC, justify: flex-start, paddingBottom: 40px)
+  Status Bar + Back (390x72)
+  Progress Bar (342px, 3px segments)
+  Step Counter ("Step X of Y" - Body Small)
+  Page Title (H1: Inter Tight 24px/700)
+  [Optional] Subtitle (Body Default)
+  Form Content (inputs, chips, sliders)
+  Bottom CTA (marginTop: auto - back icon + Continue)
+```
+
+### Confirmation Screen
+
+```
+Artboard (390x844, bg #FAFBFC)
+  Status Bar
+  Centered Content
+    Success Icon (green circle + checkmark)
+    Title (Display: Inter Tight 26px/700, centered)
+    Subtitle (Body Default, centered, #6A7382)
+    Details Card (border #D1D5DB, rows with label/value pairs)
+  Bottom CTAs (primary + outline)
+```
+
+## 5. Workflow Rules
+
+### Write Incrementally
+
+Each `write_html` call should produce ONE visual group:
+- A header, a card, a single list row, a button bar, a section
+- Never batch an entire screen in one call
+
+### Review Checkpoints
+
+After every 2-3 modifications, take a screenshot and evaluate:
+- **Spacing**: Uneven gaps, cramped groups
+- **Typography**: Hierarchy, readability, correct font/weight
+- **Contrast**: Text legibility, element distinction
+- **Alignment**: Vertical lanes, horizontal alignment
+- **Clipping**: Content cut off at edges
+- **Token compliance**: All values match design system tokens
+
+### Color Audit Process
+
+When updating frames to match the design system:
+1. Get computed styles for all text, background, border elements
+2. Map old colors to design system tokens:
+   - Dark navy (`#0F4C81`, `#1A3A5C`) -> Primary `#0A39DF`
+   - Near-black (`#111827`, `#0F172A`) -> Foreground `#121826`
+   - Gray variants (`#94A3B8`, `#64748B`, `#475569`) -> Text Secondary `#6A7382`
+   - Green accents (`#20B486`) -> Primary `#0A39DF` (for pay) or `#059669` (for status)
+3. Batch update using `update_styles` with multiple nodeIds per style change
+4. Verify with screenshots
+
+### Structural Consistency
+
+When creating matching screens (e.g., two shift detail views):
+- Use identical section ordering
+- Match section header styles (11px/700 uppercase `#6A7382`)
+- Use same card/row component patterns
+- Maintain consistent padding and gap values
+
+## 6. SVG Icon Patterns
+
+### Chevron Left (Back)
+```html
+<svg width="20" height="20" viewBox="0 0 24 24" fill="none">
+  <path d="M15 18L9 12L15 6" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Map Pin
+```html
+<svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+  <path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0 1 18 0z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="10" r="3" stroke="#6A7382" stroke-width="2"/>
+</svg>
+```
+
+### User (Supervisor)
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="7" r="4" stroke="#6A7382" stroke-width="2"/>
+</svg>
+```
+
+### Phone
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.127.96.361 1.903.7 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.907.339 1.85.573 2.81.7A2 2 0 0 1 22 16.92z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Checkmark (Requirement Met)
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M22 4L12 14.01l-3-3" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Chip Checkmark
+```html
+<!-- Large chip (14x14) -->
+<svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+
+<!-- Small chip (12x12) -->
+<svg width="12" height="12" viewBox="0 0 14 14" fill="none">
+  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+## 7. Anti-Patterns
+
+### Colors
+- Never use `#0F4C81`, `#1A3A5C` (old navy) - use `#0A39DF` (Primary)
+- Never use `#111827`, `#0F172A` - use `#121826` (Foreground)
+- Never use `#94A3B8`, `#64748B`, `#475569` - use `#6A7382` (Text Secondary)
+- Never use `#20B486` for pay rates - use `#0A39DF` (Primary)
+- Never use `#E2E8F0` for card borders - use `#D1D5DB` (Border)
+
+### Components
+- Never use pill radius (999px) for chips or badges - use 8px or 10px
+- Never use gradient backgrounds on buttons
+- Never mix font families within a role (headings = Inter Tight, body = Manrope)
+- Never place back buttons at the bottom of frames - always after status bar
+- Never hardcode CTA position - use `marginTop: auto` for bottom pinning
+
+### Structure
+- Never batch an entire screen in one `write_html` call
+- Never skip review checkpoints after 2-3 modifications
+- Never create frames without following the naming convention
+- Never use `justifyContent: space-between` on artboards with many direct children - use `marginTop: auto` on the CTA instead
+
+## Summary
+
+**The design file is the source of truth for visual direction.** Every element must use the established tokens:
+
+1. **Colors**: 7 core tokens + semantic badge colors
+2. **Typography**: Inter Tight (headings) + Manrope (body), defined scale
+3. **Spacing**: 24px page padding, 16-24px section gaps, 40px bottom safe area
+4. **Radii**: 8px (chips/badges), 12px (cards/inputs), 14px (buttons/CTAs)
+5. **Components**: Buttons, chips (large/small), inputs, cards, badges, nav bars
+6. **Structure**: Status bar > Back > Content > Bottom CTA (pinned)
+7. **Naming**: `<app>-<section>-<number>-<name>`
+
+When in doubt, screenshot an existing screen and match its patterns exactly.

.agents/settings.local.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(grep:*)",
+      "mcp__paper__get_basic_info",
+      "mcp__paper__get_screenshot",
+      "mcp__paper__get_tree_summary",
+      "mcp__paper__update_styles",
+      "mcp__paper__set_text_content",
+      "mcp__paper__get_computed_styles",
+      "mcp__paper__finish_working_on_nodes",
+      "mcp__paper__get_font_family_info",
+      "mcp__paper__rename_nodes",
+      "mcp__paper__write_html",
+      "mcp__paper__get_children",
+      "mcp__paper__create_artboard",
+      "mcp__paper__delete_nodes",
+      "mcp__paper__get_jsx",
+      "mcp__paper__get_node_info",
+      "mcp__paper__duplicate_nodes"
+    ]
+  }
+}

.agents/skills/api-authentication/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: api-authentication
+description: Implement secure API authentication with JWT, OAuth 2.0, API keys, and session management. Use when securing APIs, managing tokens, or implementing user authentication flows.
+---
+
+# API Authentication
+
+## Overview
+
+Implement comprehensive authentication strategies for APIs including JWT tokens, OAuth 2.0, API keys, and session management with proper security practices.
+
+## When to Use
+
+- Securing API endpoints
+- Implementing user login/logout flows
+- Managing access tokens and refresh tokens
+- Integrating OAuth 2.0 providers
+- Protecting sensitive data
+- Implementing API key authentication
+
+## Instructions
+
+### 1. **JWT Authentication**
+
+```javascript
+// Node.js JWT Implementation
+const express = require('express');
+const jwt = require('jsonwebtoken');
+const bcrypt = require('bcrypt');
+
+const app = express();
+const SECRET_KEY = process.env.JWT_SECRET || 'your-secret-key';
+const REFRESH_SECRET = process.env.REFRESH_SECRET || 'your-refresh-secret';
+
+// User login endpoint
+app.post('/api/auth/login', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+
+    // Find user in database
+    const user = await User.findOne({ email });
+    if (!user) {
+      return res.status(401).json({ error: 'Invalid credentials' });
+    }
+
+    // Verify password
+    const isValid = await bcrypt.compare(password, user.password);
+    if (!isValid) {
+      return res.status(401).json({ error: 'Invalid credentials' });
+    }
+
+    // Generate tokens
+    const accessToken = jwt.sign(
+      { userId: user.id, email: user.email, role: user.role },
+      SECRET_KEY,
+      { expiresIn: '15m' }
+    );
+
+    const refreshToken = jwt.sign(
+      { userId: user.id },
+      REFRESH_SECRET,
+      { expiresIn: '7d' }
+    );
+
+    // Store refresh token in database
+    await RefreshToken.create({ token: refreshToken, userId: user.id });
+
+    res.json({
+      accessToken,
+      refreshToken,
+      expiresIn: 900,
+      user: { id: user.id, email: user.email, role: user.role }
+    });
+  } catch (error) {
+    res.status(500).json({ error: 'Authentication failed' });
+  }
+});
+
+// Refresh token endpoint
+app.post('/api/auth/refresh', (req, res) => {
+  const { refreshToken } = req.body;
+
+  if (!refreshToken) {
+    return res.status(401).json({ error: 'Refresh token required' });
+  }
+
+  try {
+    const decoded = jwt.verify(refreshToken, REFRESH_SECRET);
+
+    // Verify token exists in database
+    const storedToken = await RefreshToken.findOne({
+      token: refreshToken,
+      userId: decoded.userId
+    });
+
+    if (!storedToken) {
+      return res.status(401).json({ error: 'Invalid refresh token' });
+    }
+
+    // Generate new access token
+    const newAccessToken = jwt.sign(
+      { userId: decoded.userId },
+      SECRET_KEY,
+      { expiresIn: '15m' }
+    );
+
+    res.json({ accessToken: newAccessToken, expiresIn: 900 });
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid refresh token' });
+  }
+});
+
+// Middleware to verify JWT
+const verifyToken = (req, res, next) => {
+  const authHeader = req.headers['authorization'];
+  const token = authHeader && authHeader.split(' ')[1]; // Bearer token
+
+  if (!token) {
+    return res.status(401).json({ error: 'Access token required' });
+  }
+
+  try {
+    const decoded = jwt.verify(token, SECRET_KEY);
+    req.user = decoded;
+    next();
+  } catch (error) {
+    if (error.name === 'TokenExpiredError') {
+      return res.status(401).json({ error: 'Token expired', code: 'TOKEN_EXPIRED' });
+    }
+    res.status(403).json({ error: 'Invalid token' });
+  }
+};
+
+// Protected endpoint
+app.get('/api/profile', verifyToken, (req, res) => {
+  res.json({ user: req.user });
+});
+
+// Logout endpoint
+app.post('/api/auth/logout', verifyToken, async (req, res) => {
+  try {
+    await RefreshToken.deleteOne({ userId: req.user.userId });
+    res.json({ message: 'Logged out successfully' });
+  } catch (error) {
+    res.status(500).json({ error: 'Logout failed' });
+  }
+});
+```
+
+### 2. **OAuth 2.0 Implementation**
+
+```javascript
+const passport = require('passport');
+const GoogleStrategy = require('passport-google-oauth20').Strategy;
+
+passport.use(new GoogleStrategy(
+  {
+    clientID: process.env.GOOGLE_CLIENT_ID,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    callbackURL: '/api/auth/google/callback'
+  },
+  async (accessToken, refreshToken, profile, done) => {
+    try {
+      let user = await User.findOne({ googleId: profile.id });
+
+      if (!user) {
+        user = await User.create({
+          googleId: profile.id,
+          email: profile.emails[0].value,
+          firstName: profile.name.givenName,
+          lastName: profile.name.familyName
+        });
+      }
+
+      return done(null, user);
+    } catch (error) {
+      return done(error);
+    }
+  }
+));
+
+// OAuth routes
+app.get('/api/auth/google',
+  passport.authenticate('google', { scope: ['profile', 'email'] })
+);
+
+app.get('/api/auth/google/callback',
+  passport.authenticate('google', { failureRedirect: '/login' }),
+  (req, res) => {
+    const token = jwt.sign(
+      { userId: req.user.id, email: req.user.email },
+      SECRET_KEY,
+      { expiresIn: '7d' }
+    );
+    res.redirect(`/dashboard?token=${token}`);
+  }
+);
+```
+
+### 3. **API Key Authentication**
+
+```javascript
+// API Key middleware
+const verifyApiKey = (req, res, next) => {
+  const apiKey = req.headers['x-api-key'];
+
+  if (!apiKey) {
+    return res.status(401).json({ error: 'API key required' });
+  }
+
+  try {
+    // Verify API key format and existence
+    const keyHash = crypto.createHash('sha256').update(apiKey).digest('hex');
+    const apiKeyRecord = await ApiKey.findOne({ key_hash: keyHash, active: true });
+
+    if (!apiKeyRecord) {
+      return res.status(401).json({ error: 'Invalid API key' });
+    }
+
+    req.apiKey = apiKeyRecord;
+    next();
+  } catch (error) {
+    res.status(500).json({ error: 'Authentication failed' });
+  }
+};
+
+// Generate API key endpoint
+app.post('/api/apikeys/generate', verifyToken, async (req, res) => {
+  try {
+    const apiKey = crypto.randomBytes(32).toString('hex');
+    const keyHash = crypto.createHash('sha256').update(apiKey).digest('hex');
+
+    const record = await ApiKey.create({
+      userId: req.user.userId,
+      key_hash: keyHash,
+      name: req.body.name,
+      active: true
+    });
+
+    res.json({ apiKey, message: 'Save this key securely' });
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to generate API key' });
+  }
+});
+
+// Protected endpoint with API key
+app.get('/api/data', verifyApiKey, (req, res) => {
+  res.json({ data: 'sensitive data for API key holder' });
+});
+```
+
+### 4. **Python Authentication Implementation**
+
+```python
+from flask import Flask, request, jsonify
+from flask_jwt_extended import JWTManager, create_access_token, jwt_required
+from werkzeug.security import generate_password_hash, check_password_hash
+from functools import wraps
+
+app = Flask(__name__)
+app.config['JWT_SECRET_KEY'] = 'secret-key'
+jwt = JWTManager(app)
+
+@app.route('/api/auth/login', methods=['POST'])
+def login():
+    data = request.get_json()
+    user = User.query.filter_by(email=data['email']).first()
+
+    if not user or not check_password_hash(user.password, data['password']):
+        return jsonify({'error': 'Invalid credentials'}), 401
+
+    access_token = create_access_token(
+        identity=user.id,
+        additional_claims={'email': user.email, 'role': user.role}
+    )
+
+    return jsonify({
+        'accessToken': access_token,
+        'user': {'id': user.id, 'email': user.email}
+    }), 200
+
+@app.route('/api/protected', methods=['GET'])
+@jwt_required()
+def protected():
+    from flask_jwt_extended import get_jwt_identity
+    user_id = get_jwt_identity()
+    return jsonify({'userId': user_id}), 200
+
+def require_role(role):
+    def decorator(fn):
+        @wraps(fn)
+        @jwt_required()
+        def wrapper(*args, **kwargs):
+            from flask_jwt_extended import get_jwt
+            claims = get_jwt()
+            if claims.get('role') != role:
+                return jsonify({'error': 'Forbidden'}), 403
+            return fn(*args, **kwargs)
+        return wrapper
+    return decorator
+
+@app.route('/api/admin', methods=['GET'])
+@require_role('admin')
+def admin_endpoint():
+    return jsonify({'message': 'Admin data'}), 200
+```
+
+## Best Practices
+
+### ✅ DO
+- Use HTTPS for all authentication
+- Store tokens securely (HttpOnly cookies)
+- Implement token refresh mechanism
+- Set appropriate token expiration times
+- Hash and salt passwords
+- Use strong secret keys
+- Validate tokens on every request
+- Implement rate limiting on auth endpoints
+- Log authentication attempts
+- Rotate secrets regularly
+
+### ❌ DON'T
+- Store passwords in plain text
+- Send tokens in URL parameters
+- Use weak secret keys
+- Store sensitive data in JWT payload
+- Ignore token expiration
+- Disable HTTPS in production
+- Log sensitive tokens
+- Reuse API keys across services
+- Store credentials in code
+
+## Security Headers
+
+```javascript
+app.use((req, res, next) => {
+  res.setHeader('X-Content-Type-Options', 'nosniff');
+  res.setHeader('X-Frame-Options', 'DENY');
+  res.setHeader('X-XSS-Protection', '1; mode=block');
+  res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+  next();
+});
+```

.agents/skills/api-contract-testing/SKILL.md

@@ -0,0 +1,624 @@
+---
+name: api-contract-testing
+description: Verify API contracts between services to ensure compatibility and prevent breaking changes. Use for contract testing, Pact, API contract validation, schema validation, and consumer-driven contracts.
+---
+
+# API Contract Testing
+
+## Overview
+
+Contract testing verifies that APIs honor their contracts between consumers and providers. It ensures that service changes don't break dependent consumers without requiring full integration tests. Contract tests validate request/response formats, data types, and API behavior independently.
+
+## When to Use
+
+- Testing microservices communication
+- Preventing breaking API changes
+- Validating API versioning
+- Testing consumer-provider contracts
+- Ensuring backward compatibility
+- Validating OpenAPI/Swagger specifications
+- Testing third-party API integrations
+- Catching contract violations in CI
+
+## Key Concepts
+
+- **Consumer**: Service that calls an API
+- **Provider**: Service that exposes the API
+- **Contract**: Agreement on API request/response format
+- **Pact**: Consumer-defined expectations
+- **Schema**: Structure definition (OpenAPI, JSON Schema)
+- **Stub**: Generated mock from contract
+- **Broker**: Central repository for contracts
+
+## Instructions
+
+### 1. **Pact for Consumer-Driven Contracts**
+
+#### Consumer Test (Jest/Pact)
+```typescript
+// tests/pact/user-service.pact.test.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { UserService } from '../../src/services/UserService';
+
+const { like, eachLike, iso8601DateTimeWithMillis } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'OrderService',
+  provider: 'UserService',
+  port: 1234,
+  dir: './pacts',
+});
+
+describe('User Service Contract', () => {
+  const userService = new UserService('http://localhost:1234');
+
+  describe('GET /users/:id', () => {
+    test('returns user when found', async () => {
+      await provider
+        .given('user with ID 123 exists')
+        .uponReceiving('a request for user 123')
+        .withRequest({
+          method: 'GET',
+          path: '/users/123',
+          headers: {
+            Authorization: like('Bearer token'),
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: {
+            id: like('123'),
+            email: like('user@example.com'),
+            name: like('John Doe'),
+            age: like(30),
+            createdAt: iso8601DateTimeWithMillis('2024-01-01T00:00:00.000Z'),
+            role: like('user'),
+          },
+        })
+        .executeTest(async (mockServer) => {
+          const user = await userService.getUser('123');
+
+          expect(user.id).toBe('123');
+          expect(user.email).toBeDefined();
+          expect(user.name).toBeDefined();
+        });
+    });
+
+    test('returns 404 when user not found', async () => {
+      await provider
+        .given('user with ID 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+        })
+        .willRespondWith({
+          status: 404,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: {
+            error: like('User not found'),
+            code: like('USER_NOT_FOUND'),
+          },
+        })
+        .executeTest(async (mockServer) => {
+          await expect(userService.getUser('999')).rejects.toThrow(
+            'User not found'
+          );
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    test('creates new user', async () => {
+      await provider
+        .given('user does not exist')
+        .uponReceiving('a request to create user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: {
+            email: like('newuser@example.com'),
+            name: like('New User'),
+            age: like(25),
+          },
+        })
+        .willRespondWith({
+          status: 201,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: {
+            id: like('new-123'),
+            email: like('newuser@example.com'),
+            name: like('New User'),
+            age: like(25),
+            createdAt: iso8601DateTimeWithMillis(),
+            role: 'user',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          const user = await userService.createUser({
+            email: 'newuser@example.com',
+            name: 'New User',
+            age: 25,
+          });
+
+          expect(user.id).toBeDefined();
+          expect(user.email).toBe('newuser@example.com');
+        });
+    });
+  });
+
+  describe('GET /users/:id/orders', () => {
+    test('returns user orders', async () => {
+      await provider
+        .given('user 123 has orders')
+        .uponReceiving('a request for user orders')
+        .withRequest({
+          method: 'GET',
+          path: '/users/123/orders',
+          query: {
+            limit: '10',
+            offset: '0',
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          body: {
+            orders: eachLike({
+              id: like('order-1'),
+              total: like(99.99),
+              status: like('completed'),
+              createdAt: iso8601DateTimeWithMillis(),
+            }),
+            total: like(5),
+            hasMore: like(false),
+          },
+        })
+        .executeTest(async (mockServer) => {
+          const response = await userService.getUserOrders('123', {
+            limit: 10,
+            offset: 0,
+          });
+
+          expect(response.orders).toBeDefined();
+          expect(Array.isArray(response.orders)).toBe(true);
+          expect(response.total).toBeDefined();
+        });
+    });
+  });
+});
+```
+
+#### Provider Test (Verify Contract)
+```typescript
+// tests/pact/user-service.provider.test.ts
+import { Verifier } from '@pact-foundation/pact';
+import path from 'path';
+import { app } from '../../src/app';
+import { setupTestDB, teardownTestDB } from '../helpers/db';
+
+describe('Pact Provider Verification', () => {
+  let server;
+
+  beforeAll(async () => {
+    await setupTestDB();
+    server = app.listen(3001);
+  });
+
+  afterAll(async () => {
+    await teardownTestDB();
+    server.close();
+  });
+
+  test('validates the expectations of OrderService', () => {
+    return new Verifier({
+      provider: 'UserService',
+      providerBaseUrl: 'http://localhost:3001',
+      pactUrls: [
+        path.resolve(__dirname, '../../pacts/orderservice-userservice.json'),
+      ],
+      // Provider state setup
+      stateHandlers: {
+        'user with ID 123 exists': async () => {
+          await createTestUser({ id: '123', name: 'John Doe' });
+        },
+        'user with ID 999 does not exist': async () => {
+          await deleteUser('999');
+        },
+        'user 123 has orders': async () => {
+          await createTestUser({ id: '123' });
+          await createTestOrder({ userId: '123' });
+        },
+      },
+    })
+      .verifyProvider()
+      .then((output) => {
+        console.log('Pact Verification Complete!');
+      });
+  });
+});
+```
+
+### 2. **OpenAPI Schema Validation**
+
+```typescript
+// tests/contract/openapi.test.ts
+import request from 'supertest';
+import { app } from '../../src/app';
+import OpenAPIValidator from 'express-openapi-validator';
+import fs from 'fs';
+import yaml from 'js-yaml';
+
+describe('OpenAPI Contract Validation', () => {
+  let validator;
+
+  beforeAll(() => {
+    const spec = yaml.load(
+      fs.readFileSync('./openapi.yaml', 'utf8')
+    );
+
+    validator = OpenAPIValidator.middleware({
+      apiSpec: spec,
+      validateRequests: true,
+      validateResponses: true,
+    });
+  });
+
+  test('GET /users/:id matches schema', async () => {
+    const response = await request(app)
+      .get('/users/123')
+      .expect(200);
+
+    // Validate against OpenAPI schema
+    expect(response.body).toMatchObject({
+      id: expect.any(String),
+      email: expect.stringMatching(/^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/),
+      name: expect.any(String),
+      age: expect.any(Number),
+      createdAt: expect.stringMatching(/^\d{4}-\d{2}-\d{2}T/),
+    });
+  });
+
+  test('POST /users validates request body', async () => {
+    const invalidUser = {
+      email: 'invalid-email',  // Should fail validation
+      name: 'Test',
+    };
+
+    await request(app)
+      .post('/users')
+      .send(invalidUser)
+      .expect(400);
+  });
+});
+```
+
+### 3. **JSON Schema Validation**
+
+```python
+# tests/contract/test_schema_validation.py
+import pytest
+import jsonschema
+from jsonschema import validate
+import json
+
+# Define schemas
+USER_SCHEMA = {
+    "type": "object",
+    "required": ["id", "email", "name"],
+    "properties": {
+        "id": {"type": "string"},
+        "email": {"type": "string", "format": "email"},
+        "name": {"type": "string"},
+        "age": {"type": "integer", "minimum": 0, "maximum": 150},
+        "role": {"type": "string", "enum": ["user", "admin"]},
+        "createdAt": {"type": "string", "format": "date-time"},
+    },
+    "additionalProperties": False
+}
+
+ORDER_SCHEMA = {
+    "type": "object",
+    "required": ["id", "userId", "total", "status"],
+    "properties": {
+        "id": {"type": "string"},
+        "userId": {"type": "string"},
+        "total": {"type": "number", "minimum": 0},
+        "status": {
+            "type": "string",
+            "enum": ["pending", "paid", "shipped", "delivered", "cancelled"]
+        },
+        "items": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["productId", "quantity", "price"],
+                "properties": {
+                    "productId": {"type": "string"},
+                    "quantity": {"type": "integer", "minimum": 1},
+                    "price": {"type": "number", "minimum": 0},
+                }
+            }
+        }
+    }
+}
+
+class TestAPIContracts:
+    def test_get_user_response_schema(self, api_client):
+        """Validate user endpoint response against schema."""
+        response = api_client.get('/api/users/123')
+
+        assert response.status_code == 200
+        data = response.json()
+
+        # Validate against schema
+        validate(instance=data, schema=USER_SCHEMA)
+
+    def test_create_user_request_schema(self, api_client):
+        """Validate create user request body."""
+        valid_user = {
+            "email": "test@example.com",
+            "name": "Test User",
+            "age": 30,
+        }
+
+        response = api_client.post('/api/users', json=valid_user)
+        assert response.status_code == 201
+
+        # Response should also match schema
+        validate(instance=response.json(), schema=USER_SCHEMA)
+
+    def test_invalid_request_rejected(self, api_client):
+        """Invalid requests should be rejected."""
+        invalid_user = {
+            "email": "not-an-email",
+            "age": -5,  # Invalid age
+        }
+
+        response = api_client.post('/api/users', json=invalid_user)
+        assert response.status_code == 400
+
+    def test_order_response_schema(self, api_client):
+        """Validate order endpoint response."""
+        response = api_client.get('/api/orders/order-123')
+
+        assert response.status_code == 200
+        validate(instance=response.json(), schema=ORDER_SCHEMA)
+
+    def test_order_items_array_validation(self, api_client):
+        """Validate nested array schema."""
+        order_data = {
+            "userId": "user-123",
+            "items": [
+                {"productId": "prod-1", "quantity": 2, "price": 29.99},
+                {"productId": "prod-2", "quantity": 1, "price": 49.99},
+            ]
+        }
+
+        response = api_client.post('/api/orders', json=order_data)
+        assert response.status_code == 201
+
+        result = response.json()
+        validate(instance=result, schema=ORDER_SCHEMA)
+```
+
+### 4. **REST Assured for Java**
+
+```java
+// ContractTest.java
+import io.restassured.RestAssured;
+import io.restassured.module.jsv.JsonSchemaValidator;
+import org.junit.jupiter.api.Test;
+import static io.restassured.RestAssured.*;
+import static org.hamcrest.Matchers.*;
+
+public class UserAPIContractTest {
+
+    @Test
+    public void getUserShouldMatchSchema() {
+        given()
+            .pathParam("id", "123")
+        .when()
+            .get("/api/users/{id}")
+        .then()
+            .statusCode(200)
+            .body(JsonSchemaValidator.matchesJsonSchemaInClasspath("schemas/user-schema.json"))
+            .body("id", notNullValue())
+            .body("email", matchesPattern("^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$"))
+            .body("age", greaterThanOrEqualTo(0));
+    }
+
+    @Test
+    public void createUserShouldValidateRequest() {
+        String userJson = """
+            {
+                "email": "test@example.com",
+                "name": "Test User",
+                "age": 30
+            }
+            """;
+
+        given()
+            .contentType("application/json")
+            .body(userJson)
+        .when()
+            .post("/api/users")
+        .then()
+            .statusCode(201)
+            .body("id", notNullValue())
+            .body("email", equalTo("test@example.com"))
+            .body("createdAt", matchesPattern("\\d{4}-\\d{2}-\\d{2}T.*"));
+    }
+
+    @Test
+    public void getUserOrdersShouldReturnArray() {
+        given()
+            .pathParam("id", "123")
+            .queryParam("limit", 10)
+        .when()
+            .get("/api/users/{id}/orders")
+        .then()
+            .statusCode(200)
+            .body("orders", isA(java.util.List.class))
+            .body("orders[0].id", notNullValue())
+            .body("orders[0].status", isIn(Arrays.asList(
+                "pending", "paid", "shipped", "delivered", "cancelled"
+            )))
+            .body("total", greaterThanOrEqualTo(0));
+    }
+
+    @Test
+    public void invalidRequestShouldReturn400() {
+        String invalidUser = """
+            {
+                "email": "not-an-email",
+                "age": -5
+            }
+            """;
+
+        given()
+            .contentType("application/json")
+            .body(invalidUser)
+        .when()
+            .post("/api/users")
+        .then()
+            .statusCode(400)
+            .body("error", notNullValue());
+    }
+}
+```
+
+### 5. **Contract Testing with Postman**
+
+```json
+// postman-collection.json
+{
+  "info": {
+    "name": "User API Contract Tests"
+  },
+  "item": [
+    {
+      "name": "Get User",
+      "request": {
+        "method": "GET",
+        "url": "{{baseUrl}}/users/{{userId}}"
+      },
+      "test": "
+        pm.test('Response status is 200', () => {
+          pm.response.to.have.status(200);
+        });
+
+        pm.test('Response matches schema', () => {
+          const schema = {
+            type: 'object',
+            required: ['id', 'email', 'name'],
+            properties: {
+              id: { type: 'string' },
+              email: { type: 'string', format: 'email' },
+              name: { type: 'string' },
+              age: { type: 'integer' }
+            }
+          };
+
+          pm.response.to.have.jsonSchema(schema);
+        });
+
+        pm.test('Email format is valid', () => {
+          const data = pm.response.json();
+          pm.expect(data.email).to.match(/^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$/);
+        });
+      "
+    }
+  ]
+}
+```
+
+### 6. **Pact Broker Integration**
+
+```yaml
+# .github/workflows/contract-tests.yml
+name: Contract Tests
+
+on: [push, pull_request]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+
+      - run: npm ci
+      - run: npm run test:pact
+
+      - name: Publish Pacts
+        run: |
+          npx pact-broker publish ./pacts \
+            --consumer-app-version=${{ github.sha }} \
+            --broker-base-url=${{ secrets.PACT_BROKER_URL }} \
+            --broker-token=${{ secrets.PACT_BROKER_TOKEN }}
+
+  provider-tests:
+    runs-on: ubuntu-latest
+    needs: consumer-tests
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+
+      - run: npm ci
+      - run: npm run test:pact:provider
+
+      - name: Can I Deploy?
+        run: |
+          npx pact-broker can-i-deploy \
+            --pacticipant=UserService \
+            --version=${{ github.sha }} \
+            --to-environment=production \
+            --broker-base-url=${{ secrets.PACT_BROKER_URL }} \
+            --broker-token=${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+## Best Practices
+
+### ✅ DO
+- Test contracts from consumer perspective
+- Use matchers for flexible matching
+- Validate schema structure, not specific values
+- Version your contracts
+- Test error responses
+- Use Pact broker for contract sharing
+- Run contract tests in CI
+- Test backward compatibility
+
+### ❌ DON'T
+- Test business logic in contract tests
+- Hard-code specific values in contracts
+- Skip error scenarios
+- Test UI in contract tests
+- Ignore contract versioning
+- Deploy without contract verification
+- Test implementation details
+- Mock contract tests
+
+## Tools
+
+- **Pact**: Consumer-driven contracts (multiple languages)
+- **Spring Cloud Contract**: JVM contract testing
+- **OpenAPI/Swagger**: API specification and validation
+- **Postman**: API contract testing
+- **REST Assured**: Java API testing
+- **Dredd**: OpenAPI/API Blueprint testing
+- **Spectral**: OpenAPI linting
+
+## Examples
+
+See also: integration-testing, api-versioning-strategy, continuous-testing for comprehensive API testing strategies.

.agents/skills/api-security-hardening/SKILL.md

@@ -0,0 +1,659 @@
+---
+name: api-security-hardening
+description: Secure REST APIs with authentication, rate limiting, CORS, input validation, and security middleware. Use when building or hardening API endpoints against common attacks.
+---
+
+# API Security Hardening
+
+## Overview
+
+Implement comprehensive API security measures including authentication, authorization, rate limiting, input validation, and attack prevention to protect against common vulnerabilities.
+
+## When to Use
+
+- New API development
+- Security audit remediation
+- Production API hardening
+- Compliance requirements
+- High-traffic API protection
+- Public API exposure
+
+## Implementation Examples
+
+### 1. **Node.js/Express API Security**
+
+```javascript
+// secure-api.js - Comprehensive API security
+const express = require('express');
+const helmet = require('helmet');
+const rateLimit = require('express-rate-limit');
+const mongoSanitize = require('express-mongo-sanitize');
+const xss = require('xss-clean');
+const hpp = require('hpp');
+const cors = require('cors');
+const jwt = require('jsonwebtoken');
+const validator = require('validator');
+
+class SecureAPIServer {
+  constructor() {
+    this.app = express();
+    this.setupSecurityMiddleware();
+    this.setupRoutes();
+  }
+
+  setupSecurityMiddleware() {
+    // 1. Helmet - Set security headers
+    this.app.use(helmet({
+      contentSecurityPolicy: {
+        directives: {
+          defaultSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'"],
+          scriptSrc: ["'self'"],
+          imgSrc: ["'self'", "data:", "https:"]
+        }
+      },
+      hsts: {
+        maxAge: 31536000,
+        includeSubDomains: true,
+        preload: true
+      }
+    }));
+
+    // 2. CORS configuration
+    const corsOptions = {
+      origin: (origin, callback) => {
+        const whitelist = [
+          'https://example.com',
+          'https://app.example.com'
+        ];
+
+        if (!origin || whitelist.includes(origin)) {
+          callback(null, true);
+        } else {
+          callback(new Error('Not allowed by CORS'));
+        }
+      },
+      credentials: true,
+      optionsSuccessStatus: 200,
+      methods: ['GET', 'POST', 'PUT', 'DELETE'],
+      allowedHeaders: ['Content-Type', 'Authorization']
+    };
+
+    this.app.use(cors(corsOptions));
+
+    // 3. Rate limiting
+    const generalLimiter = rateLimit({
+      windowMs: 15 * 60 * 1000, // 15 minutes
+      max: 100, // limit each IP to 100 requests per windowMs
+      message: 'Too many requests from this IP',
+      standardHeaders: true,
+      legacyHeaders: false,
+      handler: (req, res) => {
+        res.status(429).json({
+          error: 'rate_limit_exceeded',
+          message: 'Too many requests, please try again later',
+          retryAfter: req.rateLimit.resetTime
+        });
+      }
+    });
+
+    const authLimiter = rateLimit({
+      windowMs: 15 * 60 * 1000,
+      max: 5, // Stricter limit for auth endpoints
+      skipSuccessfulRequests: true
+    });
+
+    this.app.use('/api/', generalLimiter);
+    this.app.use('/api/auth/', authLimiter);
+
+    // 4. Body parsing with size limits
+    this.app.use(express.json({ limit: '10kb' }));
+    this.app.use(express.urlencoded({ extended: true, limit: '10kb' }));
+
+    // 5. NoSQL injection prevention
+    this.app.use(mongoSanitize());
+
+    // 6. XSS protection
+    this.app.use(xss());
+
+    // 7. HTTP Parameter Pollution prevention
+    this.app.use(hpp());
+
+    // 8. Request ID for tracking
+    this.app.use((req, res, next) => {
+      req.id = require('crypto').randomUUID();
+      res.setHeader('X-Request-ID', req.id);
+      next();
+    });
+
+    // 9. Security logging
+    this.app.use(this.securityLogger());
+  }
+
+  securityLogger() {
+    return (req, res, next) => {
+      const startTime = Date.now();
+
+      res.on('finish', () => {
+        const duration = Date.now() - startTime;
+
+        const logEntry = {
+          timestamp: new Date().toISOString(),
+          requestId: req.id,
+          method: req.method,
+          path: req.path,
+          statusCode: res.statusCode,
+          duration,
+          ip: req.ip,
+          userAgent: req.get('user-agent')
+        };
+
+        // Log suspicious activity
+        if (res.statusCode === 401 || res.statusCode === 403) {
+          console.warn('Security event:', logEntry);
+        }
+
+        if (res.statusCode >= 500) {
+          console.error('Server error:', logEntry);
+        }
+      });
+
+      next();
+    };
+  }
+
+  // JWT authentication middleware
+  authenticateJWT() {
+    return (req, res, next) => {
+      const authHeader = req.headers.authorization;
+
+      if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        return res.status(401).json({
+          error: 'unauthorized',
+          message: 'Missing or invalid authorization header'
+        });
+      }
+
+      const token = authHeader.substring(7);
+
+      try {
+        const decoded = jwt.verify(token, process.env.JWT_SECRET, {
+          algorithms: ['HS256'],
+          issuer: 'api.example.com',
+          audience: 'api.example.com'
+        });
+
+        req.user = decoded;
+        next();
+      } catch (error) {
+        if (error.name === 'TokenExpiredError') {
+          return res.status(401).json({
+            error: 'token_expired',
+            message: 'Token has expired'
+          });
+        }
+
+        return res.status(401).json({
+          error: 'invalid_token',
+          message: 'Invalid token'
+        });
+      }
+    };
+  }
+
+  // Input validation middleware
+  validateInput(schema) {
+    return (req, res, next) => {
+      const errors = [];
+
+      // Validate request body
+      if (schema.body) {
+        for (const [field, rules] of Object.entries(schema.body)) {
+          const value = req.body[field];
+
+          if (rules.required && !value) {
+            errors.push(`${field} is required`);
+            continue;
+          }
+
+          if (value) {
+            // Type validation
+            if (rules.type === 'email' && !validator.isEmail(value)) {
+              errors.push(`${field} must be a valid email`);
+            }
+
+            if (rules.type === 'uuid' && !validator.isUUID(value)) {
+              errors.push(`${field} must be a valid UUID`);
+            }
+
+            if (rules.type === 'url' && !validator.isURL(value)) {
+              errors.push(`${field} must be a valid URL`);
+            }
+
+            // Length validation
+            if (rules.minLength && value.length < rules.minLength) {
+              errors.push(`${field} must be at least ${rules.minLength} characters`);
+            }
+
+            if (rules.maxLength && value.length > rules.maxLength) {
+              errors.push(`${field} must be at most ${rules.maxLength} characters`);
+            }
+
+            // Pattern validation
+            if (rules.pattern && !rules.pattern.test(value)) {
+              errors.push(`${field} format is invalid`);
+            }
+          }
+        }
+      }
+
+      if (errors.length > 0) {
+        return res.status(400).json({
+          error: 'validation_error',
+          message: 'Input validation failed',
+          details: errors
+        });
+      }
+
+      next();
+    };
+  }
+
+  // Authorization middleware
+  authorize(...roles) {
+    return (req, res, next) => {
+      if (!req.user) {
+        return res.status(401).json({
+          error: 'unauthorized',
+          message: 'Authentication required'
+        });
+      }
+
+      if (roles.length > 0 && !roles.includes(req.user.role)) {
+        return res.status(403).json({
+          error: 'forbidden',
+          message: 'Insufficient permissions'
+        });
+      }
+
+      next();
+    };
+  }
+
+  setupRoutes() {
+    // Public endpoint
+    this.app.get('/api/health', (req, res) => {
+      res.json({ status: 'healthy' });
+    });
+
+    // Protected endpoint with validation
+    this.app.post('/api/users',
+      this.authenticateJWT(),
+      this.authorize('admin'),
+      this.validateInput({
+        body: {
+          email: { required: true, type: 'email' },
+          name: { required: true, minLength: 2, maxLength: 100 },
+          password: { required: true, minLength: 8 }
+        }
+      }),
+      async (req, res) => {
+        try {
+          // Sanitized and validated input
+          const { email, name, password } = req.body;
+
+          // Process request
+          res.status(201).json({
+            message: 'User created successfully',
+            userId: '123'
+          });
+        } catch (error) {
+          res.status(500).json({
+            error: 'internal_error',
+            message: 'An error occurred'
+          });
+        }
+      }
+    );
+
+    // Error handling middleware
+    this.app.use((err, req, res, next) => {
+      console.error('Unhandled error:', err);
+
+      res.status(500).json({
+        error: 'internal_error',
+        message: 'An unexpected error occurred',
+        requestId: req.id
+      });
+    });
+  }
+
+  start(port = 3000) {
+    this.app.listen(port, () => {
+      console.log(`Secure API server running on port ${port}`);
+    });
+  }
+}
+
+// Usage
+const server = new SecureAPIServer();
+server.start(3000);
+```
+
+### 2. **Python FastAPI Security**
+
+```python
+# secure_api.py
+from fastapi import FastAPI, HTTPException, Depends, Security, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+from pydantic import BaseModel, EmailStr, validator, Field
+import jwt
+from datetime import datetime, timedelta
+import re
+from typing import Optional, List
+import secrets
+
+app = FastAPI()
+security = HTTPBearer()
+limiter = Limiter(key_func=get_remote_address)
+
+# Rate limiting
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# CORS configuration
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "https://example.com",
+        "https://app.example.com"
+    ],
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE"],
+    allow_headers=["Content-Type", "Authorization"],
+    max_age=3600
+)
+
+# Trusted hosts
+app.add_middleware(
+    TrustedHostMiddleware,
+    allowed_hosts=["example.com", "*.example.com"]
+)
+
+# Security headers middleware
+@app.middleware("http")
+async def add_security_headers(request, call_next):
+    response = await call_next(request)
+
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["X-Frame-Options"] = "DENY"
+    response.headers["X-XSS-Protection"] = "1; mode=block"
+    response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+    response.headers["Content-Security-Policy"] = "default-src 'self'"
+    response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+    response.headers["Permissions-Policy"] = "geolocation=(), microphone=(), camera=()"
+
+    return response
+
+# Input validation models
+class CreateUserRequest(BaseModel):
+    email: EmailStr
+    name: str = Field(..., min_length=2, max_length=100)
+    password: str = Field(..., min_length=8)
+
+    @validator('password')
+    def validate_password(cls, v):
+        if not re.search(r'[A-Z]', v):
+            raise ValueError('Password must contain uppercase letter')
+        if not re.search(r'[a-z]', v):
+            raise ValueError('Password must contain lowercase letter')
+        if not re.search(r'\d', v):
+            raise ValueError('Password must contain digit')
+        if not re.search(r'[!@#$%^&*]', v):
+            raise ValueError('Password must contain special character')
+        return v
+
+    @validator('name')
+    def validate_name(cls, v):
+        # Prevent XSS in name field
+        if re.search(r'[<>]', v):
+            raise ValueError('Name contains invalid characters')
+        return v
+
+class APIKeyRequest(BaseModel):
+    name: str = Field(..., max_length=100)
+    expires_in_days: int = Field(30, ge=1, le=365)
+
+# JWT token verification
+def verify_token(credentials: HTTPAuthorizationCredentials = Security(security)):
+    try:
+        token = credentials.credentials
+
+        payload = jwt.decode(
+            token,
+            "your-secret-key",
+            algorithms=["HS256"],
+            audience="api.example.com",
+            issuer="api.example.com"
+        )
+
+        return payload
+
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token has expired"
+        )
+    except jwt.InvalidTokenError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token"
+        )
+
+# Role-based authorization
+def require_role(required_roles: List[str]):
+    def role_checker(token_payload: dict = Depends(verify_token)):
+        user_role = token_payload.get('role')
+
+        if user_role not in required_roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Insufficient permissions"
+            )
+
+        return token_payload
+
+    return role_checker
+
+# API key authentication
+def verify_api_key(api_key: str):
+    # Constant-time comparison to prevent timing attacks
+    if not secrets.compare_digest(api_key, "expected-api-key"):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid API key"
+        )
+    return True
+
+# Endpoints
+@app.get("/api/health")
+@limiter.limit("100/minute")
+async def health_check():
+    return {"status": "healthy"}
+
+@app.post("/api/users")
+@limiter.limit("10/minute")
+async def create_user(
+    user: CreateUserRequest,
+    token_payload: dict = Depends(require_role(["admin"]))
+):
+    """Create new user (admin only)"""
+
+    # Hash password before storing
+    # hashed_password = bcrypt.hashpw(user.password.encode(), bcrypt.gensalt())
+
+    return {
+        "message": "User created successfully",
+        "user_id": "123"
+    }
+
+@app.post("/api/keys")
+@limiter.limit("5/hour")
+async def create_api_key(
+    request: APIKeyRequest,
+    token_payload: dict = Depends(verify_token)
+):
+    """Generate API key"""
+
+    # Generate secure random API key
+    api_key = secrets.token_urlsafe(32)
+
+    expires_at = datetime.now() + timedelta(days=request.expires_in_days)
+
+    return {
+        "api_key": api_key,
+        "expires_at": expires_at.isoformat(),
+        "name": request.name
+    }
+
+@app.get("/api/protected")
+async def protected_endpoint(token_payload: dict = Depends(verify_token)):
+    return {
+        "message": "Access granted",
+        "user_id": token_payload.get("sub")
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000, ssl_certfile="cert.pem", ssl_keyfile="key.pem")
+```
+
+### 3. **API Gateway Security Configuration**
+
+```yaml
+# nginx-api-gateway.conf
+# Nginx API Gateway with security hardening
+
+http {
+    # Security headers
+    add_header X-Frame-Options "DENY" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-XSS-Protection "1; mode=block" always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    add_header Content-Security-Policy "default-src 'self'" always;
+
+    # Rate limiting zones
+    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;
+    limit_req_zone $binary_remote_addr zone=auth_limit:10m rate=1r/s;
+    limit_conn_zone $binary_remote_addr zone=conn_limit:10m;
+
+    # Request body size limit
+    client_max_body_size 10M;
+    client_body_buffer_size 128k;
+
+    # Timeout settings
+    client_body_timeout 12;
+    client_header_timeout 12;
+    send_timeout 10;
+
+    server {
+        listen 443 ssl http2;
+        server_name api.example.com;
+
+        # SSL configuration
+        ssl_certificate /etc/ssl/certs/api.example.com.crt;
+        ssl_certificate_key /etc/ssl/private/api.example.com.key;
+        ssl_protocols TLSv1.2 TLSv1.3;
+        ssl_ciphers HIGH:!aNULL:!MD5;
+        ssl_prefer_server_ciphers on;
+        ssl_session_cache shared:SSL:10m;
+        ssl_session_timeout 10m;
+
+        # API endpoints
+        location /api/ {
+            # Rate limiting
+            limit_req zone=api_limit burst=20 nodelay;
+            limit_conn conn_limit 10;
+
+            # CORS headers
+            add_header Access-Control-Allow-Origin "https://app.example.com" always;
+            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE" always;
+            add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
+
+            # Block common exploits
+            if ($request_method !~ ^(GET|POST|PUT|DELETE|HEAD)$ ) {
+                return 444;
+            }
+
+            # Proxy to backend
+            proxy_pass http://backend:3000;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+
+            # Timeouts
+            proxy_connect_timeout 60s;
+            proxy_send_timeout 60s;
+            proxy_read_timeout 60s;
+        }
+
+        # Auth endpoints with stricter limits
+        location /api/auth/ {
+            limit_req zone=auth_limit burst=5 nodelay;
+
+            proxy_pass http://backend:3000;
+        }
+
+        # Block access to sensitive files
+        location ~ /\. {
+            deny all;
+            return 404;
+        }
+    }
+}
+```
+
+## Best Practices
+
+### ✅ DO
+- Use HTTPS everywhere
+- Implement rate limiting
+- Validate all inputs
+- Use security headers
+- Log security events
+- Implement CORS properly
+- Use strong authentication
+- Version your APIs
+
+### ❌ DON'T
+- Expose stack traces
+- Return detailed errors
+- Trust user input
+- Use HTTP for APIs
+- Skip input validation
+- Ignore rate limiting
+
+## Security Checklist
+
+- [ ] HTTPS enforced
+- [ ] Authentication required
+- [ ] Authorization implemented
+- [ ] Rate limiting active
+- [ ] Input validation
+- [ ] CORS configured
+- [ ] Security headers set
+- [ ] Error handling secure
+- [ ] Logging enabled
+- [ ] API versioning
+
+## Resources
+
+- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
+- [API Security Best Practices](https://github.com/shieldfy/API-Security-Checklist)
+- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)

.agents/skills/database-migration-management/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: database-migration-management
+description: Manage database migrations and schema versioning. Use when planning migrations, version control, rollback strategies, or data transformations in PostgreSQL and MySQL.
+---
+
+# Database Migration Management
+
+## Overview
+
+Implement robust database migration systems with version control, rollback capabilities, and data transformation strategies. Includes migration frameworks and production deployment patterns.
+
+## When to Use
+
+- Schema versioning and evolution
+- Data transformations and cleanup
+- Adding/removing tables and columns
+- Index creation and optimization
+- Migration testing and validation
+- Rollback planning and execution
+- Multi-environment deployments
+
+## Migration Framework Setup
+
+### PostgreSQL - Schema Versioning
+
+```sql
+-- Create migrations tracking table
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INTEGER,
+  checksum VARCHAR(64)
+);
+
+-- Create migration log table
+CREATE TABLE migration_logs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  version BIGINT NOT NULL,
+  status VARCHAR(20) NOT NULL,
+  error_message TEXT,
+  rolled_back_at TIMESTAMP,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Function to record migration
+CREATE OR REPLACE FUNCTION record_migration(
+  p_version BIGINT,
+  p_name VARCHAR,
+  p_duration_ms INTEGER
+) RETURNS void AS $$
+BEGIN
+  INSERT INTO schema_migrations (version, name, duration_ms)
+  VALUES (p_version, p_name, p_duration_ms)
+  ON CONFLICT (version) DO UPDATE
+  SET executed_at = CURRENT_TIMESTAMP;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+### MySQL - Migration Tracking
+
+```sql
+-- Create migrations table for MySQL
+CREATE TABLE schema_migrations (
+  version BIGINT PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  executed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  duration_ms INT,
+  checksum VARCHAR(64)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+
+-- Migration status table
+CREATE TABLE migration_status (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  version BIGINT NOT NULL,
+  status ENUM('pending', 'completed', 'failed', 'rolled_back'),
+  error_message TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+## Common Migration Patterns
+
+### Adding Columns
+
+**PostgreSQL - Safe Column Addition:**
+
+```sql
+-- Migration: 20240115_001_add_phone_to_users.sql
+
+-- Add column with default (non-blocking)
+ALTER TABLE users
+ADD COLUMN phone VARCHAR(20) DEFAULT '';
+
+-- Add constraint after population
+ALTER TABLE users
+ADD CONSTRAINT phone_format
+CHECK (phone = '' OR phone ~ '^\+?[0-9\-\(\)]{10,}$');
+
+-- Create index
+CREATE INDEX CONCURRENTLY idx_users_phone ON users(phone);
+
+-- Rollback:
+-- DROP INDEX CONCURRENTLY idx_users_phone;
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+**MySQL - Column Addition:**
+
+```sql
+-- Migration: 20240115_001_add_phone_to_users.sql
+
+-- Add column with ALTER
+ALTER TABLE users
+ADD COLUMN phone VARCHAR(20) DEFAULT '',
+ADD INDEX idx_phone (phone);
+
+-- Rollback:
+-- ALTER TABLE users DROP COLUMN phone;
+```
+
+### Renaming Columns
+
+**PostgreSQL - Column Rename:**
+
+```sql
+-- Migration: 20240115_002_rename_user_name_columns.sql
+
+-- Rename columns
+ALTER TABLE users RENAME COLUMN user_name TO full_name;
+ALTER TABLE users RENAME COLUMN user_email TO email_address;
+
+-- Update indexes
+REINDEX TABLE users;
+
+-- Rollback:
+-- ALTER TABLE users RENAME COLUMN email_address TO user_email;
+-- ALTER TABLE users RENAME COLUMN full_name TO user_name;
+```
+
+### Creating Indexes Non-blocking
+
+**PostgreSQL - Concurrent Index Creation:**
+
+```sql
+-- Migration: 20240115_003_add_performance_indexes.sql
+
+-- Create indexes without blocking writes
+CREATE INDEX CONCURRENTLY idx_orders_user_created
+ON orders(user_id, created_at DESC);
+
+CREATE INDEX CONCURRENTLY idx_products_category_active
+ON products(category_id)
+WHERE active = true;
+
+-- Verify index creation
+SELECT schemaname, tablename, indexname, idx_scan
+FROM pg_stat_user_indexes
+WHERE indexname LIKE 'idx_%';
+
+-- Rollback:
+-- DROP INDEX CONCURRENTLY idx_orders_user_created;
+-- DROP INDEX CONCURRENTLY idx_products_category_active;
+```
+
+**MySQL - Online Index Creation:**
+
+```sql
+-- Migration: 20240115_003_add_performance_indexes.sql
+
+-- Create indexes with ALGORITHM=INPLACE and LOCK=NONE
+ALTER TABLE orders
+ADD INDEX idx_user_created (user_id, created_at),
+ALGORITHM=INPLACE, LOCK=NONE;
+
+-- Monitor progress
+SELECT * FROM INFORMATION_SCHEMA.PROCESSLIST
+WHERE INFO LIKE 'ALTER TABLE%';
+```
+
+### Data Transformations
+
+**PostgreSQL - Data Cleanup Migration:**
+
+```sql
+-- Migration: 20240115_004_normalize_email_addresses.sql
+
+-- Normalize existing email addresses
+UPDATE users
+SET email = LOWER(TRIM(email))
+WHERE email != LOWER(TRIM(email));
+
+-- Remove duplicates by keeping latest
+DELETE FROM users
+WHERE id NOT IN (
+  SELECT DISTINCT ON (LOWER(email)) id
+  FROM users
+  ORDER BY LOWER(email), created_at DESC
+);
+
+-- Rollback: Restore from backup (no safe rollback for data changes)
+```
+
+**MySQL - Bulk Data Update:**
+
+```sql
+-- Migration: 20240115_004_update_product_categories.sql
+
+-- Update multiple rows with JOIN
+UPDATE products p
+JOIN category_mapping cm ON p.old_category = cm.old_name
+SET p.category_id = cm.new_category_id
+WHERE p.old_category IS NOT NULL;
+
+-- Verify update
+SELECT COUNT(*) as updated_count
+FROM products
+WHERE category_id IS NOT NULL;
+```
+
+### Table Structure Changes
+
+**PostgreSQL - Alter Table Migration:**
+
+```sql
+-- Migration: 20240115_005_modify_order_columns.sql
+
+-- Add new column
+ALTER TABLE orders
+ADD COLUMN status_updated_at TIMESTAMP;
+
+-- Add constraint
+ALTER TABLE orders
+ADD CONSTRAINT valid_status
+CHECK (status IN ('pending', 'processing', 'completed', 'cancelled'));
+
+-- Set default for existing records
+UPDATE orders
+SET status_updated_at = updated_at
+WHERE status_updated_at IS NULL;
+
+-- Make column NOT NULL
+ALTER TABLE orders
+ALTER COLUMN status_updated_at SET NOT NULL;
+
+-- Rollback:
+-- ALTER TABLE orders DROP COLUMN status_updated_at;
+-- ALTER TABLE orders DROP CONSTRAINT valid_status;
+```
+
+## Testing Migrations
+
+**PostgreSQL - Test in Transaction:**
+
+```sql
+-- Test migration in transaction (will be rolled back)
+BEGIN;
+
+-- Run migration statements
+ALTER TABLE users ADD COLUMN test_column VARCHAR(255);
+
+-- Validate data
+SELECT COUNT(*) FROM users;
+SELECT COUNT(DISTINCT email) FROM users;
+
+-- Rollback if issues found
+ROLLBACK;
+
+-- Or commit if all good
+COMMIT;
+```
+
+**Validate Migration:**
+
+```sql
+-- Check migration was applied
+SELECT version, name, executed_at FROM schema_migrations
+WHERE version = 20240115005;
+
+-- Verify table structure
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_name = 'users'
+ORDER BY ordinal_position;
+```
+
+## Rollback Strategies
+
+**PostgreSQL - Bidirectional Migrations:**
+
+```sql
+-- Migration file: 20240115_006_add_user_status.sql
+
+-- ===== UP =====
+CREATE TYPE user_status AS ENUM ('active', 'suspended', 'deleted');
+ALTER TABLE users ADD COLUMN status user_status DEFAULT 'active';
+
+-- ===== DOWN =====
+-- ALTER TABLE users DROP COLUMN status;
+-- DROP TYPE user_status;
+```
+
+**Rollback Execution:**
+
+```sql
+-- Function to rollback to specific version
+CREATE OR REPLACE FUNCTION rollback_to_version(p_target_version BIGINT)
+RETURNS TABLE (version BIGINT, name VARCHAR, status VARCHAR) AS $$
+BEGIN
+  -- Execute down migrations in reverse order
+  RETURN QUERY
+  SELECT m.version, m.name, 'rolled_back'::VARCHAR
+  FROM schema_migrations m
+  WHERE m.version > p_target_version
+  ORDER BY m.version DESC;
+END;
+$$ LANGUAGE plpgsql;
+```
+
+## Production Deployment
+
+**Safe Migration Checklist:**
+
+- Test migration on production-like database
+- Verify backup exists before migration
+- Schedule during low-traffic window
+- Monitor table locks and long-running queries
+- Have rollback plan ready
+- Test rollback procedure
+- Document all changes
+- Run in transaction when possible
+- Verify data integrity after migration
+- Update application code coordinated with migration
+
+**PostgreSQL - Long Transaction Safety:**
+
+```sql
+-- Use statement timeout to prevent hanging migrations
+SET statement_timeout = '30min';
+
+-- Use lock timeout to prevent deadlocks
+SET lock_timeout = '5min';
+
+-- Run migration with timeouts
+ALTER TABLE large_table
+ADD COLUMN new_column VARCHAR(255),
+ALGORITHM='INPLACE';
+```
+
+## Migration Examples
+
+**Combined Migration - Multiple Changes:**
+
+```sql
+-- Migration: 20240115_007_refactor_user_tables.sql
+
+BEGIN;
+
+-- 1. Create new column with data from old column
+ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
+UPDATE users SET full_name = first_name || ' ' || last_name;
+
+-- 2. Add indexes
+CREATE INDEX idx_users_full_name ON users(full_name);
+
+-- 3. Add new constraint
+ALTER TABLE users
+ADD CONSTRAINT email_unique UNIQUE(email);
+
+-- 4. Drop old columns (after verification)
+-- ALTER TABLE users DROP COLUMN first_name;
+-- ALTER TABLE users DROP COLUMN last_name;
+
+COMMIT;
+```
+
+## Resources
+
+- [Flyway - Java Migration Tool](https://flywaydb.org/)
+- [Liquibase - Database Changelog](https://www.liquibase.org/)
+- [Alembic - Python Migration](https://alembic.sqlalchemy.org/)
+- [PostgreSQL ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)
+- [MySQL ALTER TABLE](https://dev.mysql.com/doc/refman/8.0/en/alter-table.html)

.agents/skills/find-skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

.agents/skills/gcp-cloud-run/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: gcp-cloud-run
+description: "Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-dri..."
+source: vibeship-spawner-skills (Apache 2.0)
+risk: unknown
+---
+
+# GCP Cloud Run
+
+## Patterns
+
+### Cloud Run Service Pattern
+
+Containerized web service on Cloud Run
+
+**When to use**: ['Web applications and APIs', 'Need any runtime or library', 'Complex services with multiple endpoints', 'Stateless containerized workloads']
+
+```javascript
+```dockerfile
+# Dockerfile - Multi-stage build for smaller image
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM node:20-slim
+WORKDIR /app
+
+# Copy only production dependencies
+COPY --from=builder /app/node_modules ./node_modules
+COPY src ./src
+COPY package.json ./
+
+# Cloud Run uses PORT env variable
+ENV PORT=8080
+EXPOSE 8080
+
+# Run as non-root user
+USER node
+
+CMD ["node", "src/index.js"]
+```
+
+```javascript
+// src/index.js
+const express = require('express');
+const app = express();
+
+app.use(express.json());
+
+// Health check endpoint
+app.get('/health', (req, res) => {
+  res.status(200).send('OK');
+});
+
+// API routes
+app.get('/api/items/:id', async (req, res) => {
+  try {
+    const item = await getItem(req.params.id);
+    res.json(item);
+  } catch (error) {
+    console.error('Error:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+  console.log('SIGTERM received, shutting down gracefully');
+  server.close(() => {
+    console.log('Server closed');
+    process.exit(0);
+  });
+});
+
+const PORT = process.env.PORT || 8080;
+const server = app.listen(PORT, () => {
+  console.log(`Server listening on port ${PORT}`);
+});
+```
+
+```yaml
+# cloudbuild.yaml
+steps:
+  # Build the container image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA', '.']
+
+  # Push the container image
+  - name: 'gcr.io/cloud-builders/docker'
+    args: ['push', 'gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA']
+
+  # Deploy to Cloud Run
+  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
+    entrypoint: gcloud
+    args:
+      - 'run'
+      - 'deploy'
+      - 'my-service'
+      - '--image=gcr.io/$PROJECT_ID/my-service:$COMMIT_SHA'
+      - '--region=us-central1'
+      - '--platform=managed'
+      - '--allow-unauthenticated'
+      - '--memory=512Mi'
+      - '--cpu=1'
+      - '--min-instances=1'
+      - '--max-instances=100'
+
+```
+
+### Cloud Run Functions Pattern
+
+Event-driven functions (formerly Cloud Functions)
+
+**When to use**: ['Simple event handlers', 'Pub/Sub message processing', 'Cloud Storage triggers', 'HTTP webhooks']
+
+```javascript
+```javascript
+// HTTP Function
+// index.js
+const functions = require('@google-cloud/functions-framework');
+
+functions.http('helloHttp', (req, res) => {
+  const name = req.query.name || req.body.name || 'World';
+  res.send(`Hello, ${name}!`);
+});
+```
+
+```javascript
+// Pub/Sub Function
+const functions = require('@google-cloud/functions-framework');
+
+functions.cloudEvent('processPubSub', (cloudEvent) => {
+  // Decode Pub/Sub message
+  const message = cloudEvent.data.message;
+  const data = message.data
+    ? JSON.parse(Buffer.from(message.data, 'base64').toString())
+    : {};
+
+  console.log('Received message:', data);
+
+  // Process message
+  processMessage(data);
+});
+```
+
+```javascript
+// Cloud Storage Function
+const functions = require('@google-cloud/functions-framework');
+
+functions.cloudEvent('processStorageEvent', async (cloudEvent) => {
+  const file = cloudEvent.data;
+
+  console.log(`Event: ${cloudEvent.type}`);
+  console.log(`Bucket: ${file.bucket}`);
+  console.log(`File: ${file.name}`);
+
+  if (cloudEvent.type === 'google.cloud.storage.object.v1.finalized') {
+    await processUploadedFile(file.bucket, file.name);
+  }
+});
+```
+
+```bash
+# Deploy HTTP function
+gcloud functions deploy hello-http \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-http \
+  --allow-unauthenticated \
+  --region us-central1
+
+# Deploy Pub/Sub function
+gcloud functions deploy process-messages \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-topic my-topic \
+  --region us-central1
+
+# Deploy Cloud Storage function
+gcloud functions deploy process-uploads \
+  --gen2 \
+  --runtime nodejs20 \
+  --trigger-event-filters="type=google.cloud.storage.object.v1.finalized" \
+  --trigger-event-filters="bucket=my-bucket" \
+  --region us-central1
+```
+```
+
+### Cold Start Optimization Pattern
+
+Minimize cold start latency for Cloud Run
+
+**When to use**: ['Latency-sensitive applications', 'User-facing APIs', 'High-traffic services']
+
+```javascript
+## 1. Enable Startup CPU Boost
+
+```bash
+gcloud run deploy my-service \
+  --cpu-boost \
+  --region us-central1
+```
+
+## 2. Set Minimum Instances
+
+```bash
+gcloud run deploy my-service \
+  --min-instances 1 \
+  --region us-central1
+```
+
+## 3. Optimize Container Image
+
+```dockerfile
+# Use distroless for minimal image
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+
+FROM gcr.io/distroless/nodejs20-debian12
+WORKDIR /app
+COPY --from=builder /app/node_modules ./node_modules
+COPY src ./src
+CMD ["src/index.js"]
+```
+
+## 4. Lazy Initialize Heavy Dependencies
+
+```javascript
+// Lazy load heavy libraries
+let bigQueryClient = null;
+
+function getBigQueryClient() {
+  if (!bigQueryClient) {
+    const { BigQuery } = require('@google-cloud/bigquery');
+    bigQueryClient = new BigQuery();
+  }
+  return bigQueryClient;
+}
+
+// Only initialize when needed
+app.get('/api/analytics', async (req, res) => {
+  const client = getBigQueryClient();
+  const results = await client.query({...});
+  res.json(results);
+});
+```
+
+## 5. Increase Memory (More CPU)
+
+```bash
+# Higher memory = more CPU during startup
+gcloud run deploy my-service \
+  --memory 1Gi \
+  --cpu 2 \
+  --region us-central1
+```
+```
+
+## Anti-Patterns
+
+### ❌ CPU-Intensive Work Without Concurrency=1
+
+**Why bad**: CPU is shared across concurrent requests. CPU-bound work
+will starve other requests, causing timeouts.
+
+### ❌ Writing Large Files to /tmp
+
+**Why bad**: /tmp is an in-memory filesystem. Large files consume
+your memory allocation and can cause OOM errors.
+
+### ❌ Long-Running Background Tasks
+
+**Why bad**: Cloud Run throttles CPU to near-zero when not handling
+requests. Background tasks will be extremely slow or stall.
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | high | ## Calculate memory including /tmp usage |
+| Issue | high | ## Set appropriate concurrency |
+| Issue | high | ## Enable CPU always allocated |
+| Issue | medium | ## Configure connection pool with keep-alive |
+| Issue | high | ## Enable startup CPU boost |
+| Issue | medium | ## Explicitly set execution environment |
+| Issue | medium | ## Set consistent timeouts |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

.agents/skills/krow-mobile-architecture/SKILL.md

@@ -0,0 +1,900 @@
+---
+name: krow-mobile-architecture
+description: KROW mobile app Clean Architecture implementation including package structure, dependency rules, feature isolation, BLoC lifecycle management, session handling, and Data Connect connectors pattern. Use this when architecting new mobile features, debugging state management issues, preventing prop drilling, managing BLoC disposal, implementing session stores, or setting up connector repositories. Essential for maintaining architectural integrity across staff and client apps.
+---
+
+# KROW Mobile Architecture
+
+This skill defines the authoritative mobile architecture for the KROW platform. All code must strictly adhere to these principles to prevent architectural degradation.
+
+## When to Use This Skill
+
+- Architecting new mobile features
+- Debugging state management or BLoC lifecycle issues
+- Preventing prop drilling in UI code
+- Managing session state and authentication
+- Implementing Data Connect connector repositories
+- Setting up feature modules and dependency injection
+- Understanding package boundaries and dependencies
+- Refactoring legacy code to Clean Architecture
+
+## 1. High-Level Architecture
+
+KROW follows **Clean Architecture** in a **Melos Monorepo**. Dependencies flow **inward** toward the Domain.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Apps (Entry Points)                  │
+│  • apps/mobile/apps/client                              │
+│  • apps/mobile/apps/staff                               │
+│  Role: DI roots, navigation assembly, env config        │
+└─────────────────┬───────────────────────────────────────┘
+                  │ depends on
+┌─────────────────▼───────────────────────────────────────┐
+│                   Features (Vertical Slices)            │
+│  • apps/mobile/packages/features/client/*               │
+│  • apps/mobile/packages/features/staff/*                │
+│  Role: Pages, BLoCs, Use Cases, Feature Repositories    │
+└─────┬───────────────────────────────────────┬───────────┘
+      │ depends on                            │ depends on
+┌─────▼────────────────┐              ┌───────▼───────────┐
+│   Design System      │              │  Core Localization│
+│  • UI components     │              │  • LocaleBloc     │
+│  • Theme/colors      │              │  • Translations   │
+│  • Typography        │              │  • ErrorTranslator│
+└──────────────────────┘              └───────────────────┘
+                  │ both depend on
+┌─────────────────▼───────────────────────────────────────┐
+│               Services (Interface Adapters)             │
+│  • data_connect: Backend integration, session mgmt      │
+│  • core: Extensions, base classes, utilities            │
+└─────────────────┬───────────────────────────────────────┘
+                  │ both depend on
+┌─────────────────▼───────────────────────────────────────┐
+│                Domain (Stable Core)                     │
+│  • Entities (immutable data models)                     │
+│  • Failures (domain-specific errors)                    │
+│  • Pure Dart only, zero Flutter dependencies            │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Critical Rule:** Dependencies point INWARD only. Domain knows nothing about the outer layers.
+
+## 2. Package Structure & Responsibilities
+
+### 2.1 Apps (`apps/mobile/apps/`)
+
+**Role:** Application entry points and DI roots
+
+**Responsibilities:**
+- Initialize Flutter Modular
+- Assemble features into navigation tree
+- Inject concrete implementations (from `data_connect`) into features
+- Configure environment-specific settings (dev/stage/prod)
+- Initialize session management
+
+**Structure:**
+```
+apps/mobile/apps/staff/
+├── lib/
+│   ├── main.dart              # Entry point, session initialization
+│   ├── app_module.dart        # Root module, imports features
+│   ├── app_widget.dart        # MaterialApp setup
+│   └── src/
+│       ├── navigation/        # Typed navigators
+│       └── widgets/           # SessionListener wrapper
+└── pubspec.yaml
+```
+
+**RESTRICTION:** NO business logic. NO UI widgets (except App and Main).
+
+### 2.2 Features (`apps/mobile/packages/features/<APP>/<FEATURE>`)
+
+**Role:** Vertical slices of user-facing functionality
+
+**Internal Structure:**
+```
+features/staff/profile/
+├── lib/
+│   ├── src/
+│   │   ├── domain/
+│   │   │   ├── repositories/        # Repository interfaces
+│   │   │   │   └── profile_repository_interface.dart
+│   │   │   └── usecases/           # Application logic
+│   │   │       └── get_profile_usecase.dart
+│   │   ├── data/
+│   │   │   └── repositories_impl/   # Repository concrete classes
+│   │   │       └── profile_repository_impl.dart
+│   │   └── presentation/
+│   │       ├── blocs/              # State management
+│   │       │   └── profile_cubit.dart
+│   │       ├── pages/              # Screens (StatelessWidget preferred)
+│   │       │   └── profile_page.dart
+│   │       └── widgets/            # Reusable UI components
+│   │           └── profile_header.dart
+│   └── profile_feature.dart        # Barrel file (public API only)
+└── pubspec.yaml
+```
+
+**Key Principles:**
+- **Presentation:** UI Pages and Widgets, BLoCs/Cubits for state
+- **Application:** Use Cases (business logic orchestration)
+- **Data:** Repository implementations (backend integration)
+- **Pages as StatelessWidget:** Move state to BLoCs for better performance and testability
+
+**RESTRICTION:** Features MUST NOT import other features. Communication happens via:
+- Shared domain entities
+- Session stores (`StaffSessionStore`, `ClientSessionStore`)
+- Navigation via Modular
+- Data Connect connector repositories
+
+### 2.3 Domain (`apps/mobile/packages/domain`)
+
+**Role:** The stable, pure heart of the system
+
+**Responsibilities:**
+- Define **Entities** (immutable data models using Data Classes or Freezed)
+- Define **Failures** (domain-specific error types)
+
+**Structure:**
+```
+domain/
+├── lib/
+│   └── src/
+│       ├── entities/
+│       │   ├── user.dart
+│       │   ├── staff.dart
+│       │   └── shift.dart
+│       └── failures/
+│           ├── failure.dart        # Base class
+│           ├── auth_failure.dart
+│           └── network_failure.dart
+└── pubspec.yaml
+```
+
+**Example Entity:**
+```dart
+import 'package:equatable/equatable.dart';
+
+class Staff extends Equatable {
+  final String id;
+  final String name;
+  final String email;
+  final StaffStatus status;
+  
+  const Staff({
+    required this.id,
+    required this.name,
+    required this.email,
+    required this.status,
+  });
+  
+  @override
+  List<Object?> get props => [id, name, email, status];
+}
+```
+
+**RESTRICTION:** 
+- NO Flutter dependencies (no `import 'package:flutter/material.dart'`)
+- NO `json_annotation` or serialization code
+- Only `equatable` for value equality
+- Pure Dart only
+
+### 2.4 Data Connect (`apps/mobile/packages/data_connect`)
+
+**Role:** Interface Adapter for Backend Access
+
+**Responsibilities:**
+- Centralized connector repositories (see Data Connect Connectors Pattern section)
+- Implement Firebase Data Connect service layer
+- Map Domain Entities ↔ Data Connect generated code
+- Handle Firebase exceptions → domain failures
+- Provide `DataConnectService` with session management
+
+**Structure:**
+```
+data_connect/
+├── lib/
+│   ├── src/
+│   │   ├── services/
+│   │   │   ├── data_connect_service.dart     # Core service
+│   │   │   └── mixins/
+│   │   │       └── session_handler_mixin.dart
+│   │   ├── connectors/                        # Connector pattern (see below)
+│   │   │   ├── staff/
+│   │   │   │   ├── domain/
+│   │   │   │   │   ├── repositories/
+│   │   │   │   │   │   └── staff_connector_repository.dart
+│   │   │   │   │   └── usecases/
+│   │   │   │   │       └── get_profile_completion_usecase.dart
+│   │   │   │   └── data/
+│   │   │   │       └── repositories/
+│   │   │   │           └── staff_connector_repository_impl.dart
+│   │   │   ├── order/
+│   │   │   └── shifts/
+│   │   └── session/
+│   │       ├── staff_session_store.dart
+│   │       └── client_session_store.dart
+│   └── krow_data_connect.dart               # Exports
+└── pubspec.yaml
+```
+
+**RESTRICTION:**
+- NO feature-specific logic
+- Connectors are domain-neutral and reusable
+- All queries follow Clean Architecture (domain interfaces → data implementations)
+
+### 2.5 Design System (`apps/mobile/packages/design_system`)
+
+**Role:** Visual language and component library
+
+**Responsibilities:**
+- Theme definitions (`UiColors`, `UiTypography`)
+- UI constants (`spacingL`, `radiusM`, etc.)
+- Shared widgets (if reused across multiple features)
+- Assets (icons, images, fonts)
+
+**Structure:**
+```
+design_system/
+├── lib/
+│   └── src/
+│       ├── ui_colors.dart
+│       ├── ui_typography.dart
+│       ├── ui_icons.dart
+│       ├── ui_constants.dart
+│       ├── ui_theme.dart          # ThemeData factory
+│       └── widgets/               # Shared UI components
+│           └── custom_button.dart
+└── assets/
+    ├── icons/
+    └── images/
+```
+
+**RESTRICTION:**
+- Dumb widgets ONLY (no state management)
+- NO business logic
+- Colors and typography are IMMUTABLE (no feature can override)
+
+### 2.6 Core Localization (`apps/mobile/packages/core_localization`)
+
+**Role:** Centralized i18n management
+
+**Responsibilities:**
+- Define all user-facing strings in `l10n/`
+- Provide `LocaleBloc` for locale state management
+- Export `TranslationProvider` for `context.strings` access
+- Map domain failures to localized error messages via `ErrorTranslator`
+
+**Feature Integration:**
+```dart
+// Features access strings
+Text(context.strings.loginButton)
+
+// BLoCs emit domain failures (not strings)
+emit(AuthError(InvalidCredentialsFailure()));
+
+// UI translates failures to localized messages
+final message = ErrorTranslator.translate(failure, context.strings);
+```
+
+**App Setup:**
+```dart
+// App imports LocalizationModule
+class AppModule extends Module {
+  @override
+  List<Module> get imports => [LocalizationModule()];
+}
+
+// Wrap app with providers
+BlocProvider<LocaleBloc>(
+  create: (_) => Modular.get<LocaleBloc>(),
+  child: TranslationProvider(
+    child: MaterialApp.router(...),
+  ),
+)
+```
+
+### 2.7 Core (`apps/mobile/packages/core`)
+
+**Role:** Cross-cutting concerns
+
+**Responsibilities:**
+- Extension methods (NavigationExtensions, ListExtensions, etc.)
+- Base classes (UseCase, Failure, BlocErrorHandler)
+- Logger configuration
+- Result types for functional error handling
+
+## 3. Dependency Direction Rules
+
+1. **Domain Independence:** `domain` knows NOTHING about outer layers
+   - Defines *what* needs to be done, not *how*
+   - Pure Dart, zero Flutter dependencies
+   - Stable contracts that rarely change
+
+2. **UI Agnosticism:** Features depend on `design_system` for UI and `domain` for logic
+   - Features do NOT know about Firebase or backend details
+   - Backend changes don't affect feature implementation
+
+3. **Data Isolation:** `data_connect` depends on `domain` to know interfaces
+   - Implements domain repository interfaces
+   - Maps backend models to domain entities
+   - Does NOT know about UI
+
+**Dependency Flow:**
+```
+Apps → Features → Design System
+                → Core Localization
+                → Data Connect → Domain
+                              → Core
+```
+
+## 4. Data Connect Service & Session Management
+
+### 4.1 Session Handler Mixin
+
+**Location:** `apps/mobile/packages/data_connect/lib/src/services/mixins/session_handler_mixin.dart`
+
+**Responsibilities:**
+- Automatic token refresh (triggered when <5 minutes to expiry)
+- Firebase auth state listening
+- Role-based access validation
+- Session state stream emissions
+- 3-attempt retry with exponential backoff (1s → 2s → 4s)
+
+**Key Method:**
+```dart
+// Call once on app startup
+DataConnectService.instance.initializeAuthListener(
+  allowedRoles: ['STAFF', 'BOTH'],  // or ['CLIENT', 'BUSINESS', 'BOTH']
+);
+```
+
+### 4.2 Session Listener Widget
+
+**Location:** `apps/mobile/apps/<app>/lib/src/widgets/session_listener.dart`
+
+**Responsibilities:**
+- Wraps entire app to listen to session state changes
+- Shows user-friendly dialogs for session expiration/errors
+- Handles navigation on auth state changes
+
+**Usage:**
+```dart
+// main.dart
+runApp(
+  SessionListener(  // ← Critical wrapper
+    child: ModularApp(module: AppModule(), child: AppWidget()),
+  ),
+);
+```
+
+### 4.3 Repository Pattern with Data Connect
+
+**Step 1:** Define interface in feature domain:
+```dart
+// features/staff/profile/lib/src/domain/repositories/
+abstract interface class ProfileRepositoryInterface {
+  Future<Staff> getProfile(String id);
+}
+```
+
+**Step 2:** Implement using `DataConnectService.run()`:
+```dart
+// features/staff/profile/lib/src/data/repositories_impl/
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  final DataConnectService _service = DataConnectService.instance;
+  
+  @override
+  Future<Staff> getProfile(String id) async {
+    return await _service.run(() async {
+      final response = await _service.connector
+          .getStaffById(id: id)
+          .execute();
+      return _mapToStaff(response.data.staff);
+    });
+  }
+}
+```
+
+**Benefits of `_service.run()`:**
+- ✅ Auto validates user is authenticated
+- ✅ Refreshes token if <5 min to expiry
+- ✅ Executes the query
+- ✅ 3-attempt retry with exponential backoff
+- ✅ Maps exceptions to domain failures
+
+### 4.4 Session Store Pattern
+
+After successful auth, populate session stores:
+
+**Staff App:**
+```dart
+StaffSessionStore.instance.setSession(
+  StaffSession(
+    user: user,
+    staff: staff,
+    ownerId: ownerId,
+  ),
+);
+```
+
+**Client App:**
+```dart
+ClientSessionStore.instance.setSession(
+  ClientSession(
+    user: user,
+    business: business,
+  ),
+);
+```
+
+**Lazy Loading:** If session is null, fetch from backend and update:
+```dart
+final session = StaffSessionStore.instance.session;
+if (session?.staff == null) {
+  final staff = await getStaffById(session!.user.uid);
+  StaffSessionStore.instance.setSession(
+    session.copyWith(staff: staff),
+  );
+}
+```
+
+## 5. Feature Isolation & Communication
+
+### Zero Direct Imports
+
+```dart
+// ❌ FORBIDDEN
+import 'package:staff_profile/staff_profile.dart';  // in another feature
+
+// ✅ ALLOWED
+import 'package:krow_domain/krow_domain.dart';      // shared domain
+import 'package:krow_core/krow_core.dart';          // shared utilities
+import 'package:design_system/design_system.dart';  // shared UI
+```
+
+### Navigation: Typed Navigators with Safe Extensions
+
+**Safe Navigation Extensions** (from `core` package):
+```dart
+extension NavigationExtensions on IModularNavigator {
+  /// Safely navigate with fallback to home
+  Future<void> safeNavigate(String route) async {
+    try {
+      await navigate(route);
+    } catch (e) {
+      await navigate('/home');  // Fallback
+    }
+  }
+  
+  /// Safely push with fallback to home
+  Future<T?> safePush<T>(String route) async {
+    try {
+      return await pushNamed<T>(route);
+    } catch (e) {
+      await navigate('/home');
+      return null;
+    }
+  }
+  
+  /// Safely pop with guard against empty stack
+  void popSafe() {
+    if (canPop()) {
+      pop();
+    } else {
+      navigate('/home');
+    }
+  }
+}
+```
+
+**Typed Navigators:**
+```dart
+// apps/mobile/apps/staff/lib/src/navigation/staff_navigator.dart
+extension StaffNavigator on IModularNavigator {
+  Future<void> toStaffHome() => safeNavigate(StaffPaths.home);
+  
+  Future<void> toShiftDetails(String shiftId) => 
+      safePush('${StaffPaths.shifts}/$shiftId');
+  
+  Future<void> toProfileEdit() => safePush(StaffPaths.profileEdit);
+}
+```
+
+**Usage in Features:**
+```dart
+// ✅ CORRECT
+Modular.to.toStaffHome();
+Modular.to.toShiftDetails(shiftId: '123');
+Modular.to.popSafe();
+
+// ❌ AVOID
+Modular.to.navigate('/home');  // No safety
+Navigator.push(...);            // No Modular integration
+```
+
+### Data Sharing Patterns
+
+Features don't share state directly. Use:
+
+1. **Domain Repositories:** Centralized data sources
+2. **Session Stores:** `StaffSessionStore`, `ClientSessionStore` for app-wide context
+3. **Event Streams:** If needed, via `DataConnectService` streams
+4. **Navigation Arguments:** Pass IDs, not full objects
+
+## 6. App-Specific Session Management
+
+### Staff App
+
+```dart
+// main.dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  
+  DataConnectService.instance.initializeAuthListener(
+    allowedRoles: ['STAFF', 'BOTH'],
+  );
+  
+  runApp(
+    SessionListener(
+      child: ModularApp(module: StaffAppModule(), child: StaffApp()),
+    ),
+  );
+}
+```
+
+**Session Store:** `StaffSessionStore`
+- Fields: `user`, `staff`, `ownerId`
+- Lazy load: `getStaffById()` if staff is null
+
+**Navigation:**
+- Authenticated → `Modular.to.toStaffHome()`
+- Unauthenticated → `Modular.to.toInitialPage()`
+
+### Client App
+
+```dart
+// main.dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  
+  DataConnectService.instance.initializeAuthListener(
+    allowedRoles: ['CLIENT', 'BUSINESS', 'BOTH'],
+  );
+  
+  runApp(
+    SessionListener(
+      child: ModularApp(module: ClientAppModule(), child: ClientApp()),
+    ),
+  );
+}
+```
+
+**Session Store:** `ClientSessionStore`
+- Fields: `user`, `business`
+- Lazy load: `getBusinessById()` if business is null
+
+**Navigation:**
+- Authenticated → `Modular.to.toClientHome()`
+- Unauthenticated → `Modular.to.toInitialPage()`
+
+## 7. Data Connect Connectors Pattern
+
+**Problem:** Without connectors, each feature duplicates backend queries.
+
+**Solution:** Centralize all backend queries in `data_connect/connectors/`.
+
+### Structure
+
+Mirror backend connector structure:
+
+```
+data_connect/lib/src/connectors/
+├── staff/
+│   ├── domain/
+│   │   ├── repositories/
+│   │   │   └── staff_connector_repository.dart      # Interface
+│   │   └── usecases/
+│   │       └── get_profile_completion_usecase.dart
+│   └── data/
+│       └── repositories/
+│           └── staff_connector_repository_impl.dart # Implementation
+├── order/
+├── shifts/
+└── user/
+```
+
+**Maps to backend:**
+```
+backend/dataconnect/connector/
+├── staff/
+├── order/
+├── shifts/
+└── user/
+```
+
+### Clean Architecture in Connectors
+
+**Domain Interface:**
+```dart
+// staff_connector_repository.dart
+abstract interface class StaffConnectorRepository {
+  Future<bool> getProfileCompletion();
+  Future<Staff> getStaffById(String id);
+}
+```
+
+**Use Case:**
+```dart
+// get_profile_completion_usecase.dart
+class GetProfileCompletionUseCase {
+  final StaffConnectorRepository _repository;
+  
+  GetProfileCompletionUseCase({required StaffConnectorRepository repository})
+      : _repository = repository;
+  
+  Future<bool> call() => _repository.getProfileCompletion();
+}
+```
+
+**Data Implementation:**
+```dart
+// staff_connector_repository_impl.dart
+class StaffConnectorRepositoryImpl implements StaffConnectorRepository {
+  final DataConnectService _service;
+  
+  @override
+  Future<bool> getProfileCompletion() async {
+    return _service.run(() async {
+      final staffId = await _service.getStaffId();
+      final response = await _service.connector
+          .getStaffProfileCompletion(id: staffId)
+          .execute();
+      
+      return _isProfileComplete(response);
+    });
+  }
+}
+```
+
+### Feature Integration
+
+**Step 1:** Feature registers connector repository:
+```dart
+// staff_main_module.dart
+class StaffMainModule extends Module {
+  @override
+  void binds(Injector i) {
+    i.addLazySingleton<StaffConnectorRepository>(
+      StaffConnectorRepositoryImpl.new,
+    );
+    
+    i.addLazySingleton(
+      () => GetProfileCompletionUseCase(
+        repository: i.get<StaffConnectorRepository>(),
+      ),
+    );
+    
+    i.addLazySingleton(
+      () => StaffMainCubit(
+        getProfileCompletionUsecase: i.get(),
+      ),
+    );
+  }
+}
+```
+
+**Step 2:** BLoC uses it:
+```dart
+class StaffMainCubit extends Cubit<StaffMainState> {
+  final GetProfileCompletionUseCase _getProfileCompletionUsecase;
+  
+  Future<void> loadProfileCompletion() async {
+    final isComplete = await _getProfileCompletionUsecase();
+    emit(state.copyWith(isProfileComplete: isComplete));
+  }
+}
+```
+
+### Benefits
+
+✅ **No Duplication** - Query implemented once, used by many features  
+✅ **Single Source of Truth** - Backend change → update one place  
+✅ **Reusability** - Any feature can use any connector  
+✅ **Testability** - Mock connector repo to test features  
+✅ **Scalability** - Easy to add connectors as backend grows  
+
+## 8. Avoiding Prop Drilling: Direct BLoC Access
+
+### The Problem
+
+Passing data through intermediate widgets creates maintenance burden:
+
+```dart
+// ❌ BAD: Prop drilling
+ProfilePage(status: status)
+  → ProfileHeader(status: status)
+    → ProfileLevelBadge(status: status)  // Only widget that needs it
+```
+
+### The Solution: BlocBuilder in Leaf Widgets
+
+```dart
+// ✅ GOOD: Direct BLoC access
+class ProfileLevelBadge extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<ProfileCubit, ProfileState>(
+      builder: (context, state) {
+        if (state.profile == null) return const SizedBox.shrink();
+        
+        final level = _mapStatusToLevel(state.profile!.status);
+        return LevelBadgeUI(level: level);
+      },
+    );
+  }
+}
+```
+
+### Guidelines
+
+1. **Leaf Widgets Access BLoC:** Widgets needing specific data should use `BlocBuilder`
+2. **Container Widgets Stay Simple:** Parent widgets only manage layout
+3. **No Unnecessary Props:** Don't pass data to intermediate widgets
+4. **Single Responsibility:** Each widget has one reason to exist
+
+**Decision Tree:**
+```
+Does this widget need data?
+├─ YES, leaf widget → Use BlocBuilder
+├─ YES, container → Use BlocBuilder in child
+└─ NO → Don't add prop
+```
+
+## 9. BLoC Lifecycle & State Emission Safety
+
+### The Problem: StateError After Dispose
+
+When async operations complete after BLoC is closed:
+```
+StateError: Cannot emit new states after calling close
+```
+
+**Root Causes:**
+1. Transient BLoCs created with `BlocProvider(create:)` → disposed prematurely
+2. Multiple BlocProviders disposing same singleton
+3. User navigates away during async operation
+
+### The Solution: Singleton BLoCs + Safe Emit
+
+#### Step 1: Register as Singleton
+
+```dart
+// ✅ GOOD: Singleton registration
+i.addLazySingleton<ProfileCubit>(
+  () => ProfileCubit(useCase1, useCase2),
+);
+
+// ❌ BAD: Creates new instance each time
+i.add(ProfileCubit.new);
+```
+
+#### Step 2: Use BlocProvider.value()
+
+```dart
+// ✅ GOOD: Reuse singleton
+final cubit = Modular.get<ProfileCubit>();
+BlocProvider<ProfileCubit>.value(
+  value: cubit,
+  child: MyWidget(),
+)
+
+// ❌ BAD: Creates duplicate
+BlocProvider<ProfileCubit>(
+  create: (_) => Modular.get<ProfileCubit>(),
+  child: MyWidget(),
+)
+```
+
+#### Step 3: Safe Emit with BlocErrorHandler
+
+**Location:** `apps/mobile/packages/core/lib/src/presentation/mixins/bloc_error_handler.dart`
+
+```dart
+mixin BlocErrorHandler<S> on Cubit<S> {
+  void _safeEmit(void Function(S) emit, S state) {
+    try {
+      emit(state);
+    } on StateError catch (e) {
+      developer.log(
+        'Could not emit state: ${e.message}. Bloc may have been disposed.',
+        name: runtimeType.toString(),
+      );
+    }
+  }
+}
+```
+
+**Usage:**
+```dart
+class ProfileCubit extends Cubit<ProfileState> with BlocErrorHandler<ProfileState> {
+  Future<void> loadProfile() async {
+    emit(state.copyWith(status: ProfileStatus.loading));
+    
+    await handleError(
+      emit: emit,
+      action: () async {
+        final profile = await getProfile();
+        emit(state.copyWith(status: ProfileStatus.loaded, profile: profile));
+        // ✅ Safe even if BLoC disposed
+      },
+      onError: (errorKey) => state.copyWith(status: ProfileStatus.error),
+    );
+  }
+}
+```
+
+### Pattern Summary
+
+| Pattern | When to Use | Risk |
+|---------|------------|------|
+| Singleton + BlocProvider.value() | Long-lived features | Low |
+| Transient + BlocProvider(create:) | Temporary widgets | Medium |
+| Direct BlocBuilder | Leaf widgets | Low |
+
+## 10. Anti-Patterns to Avoid
+
+❌ **Feature imports feature**
+```dart
+import 'package:staff_profile/staff_profile.dart';  // in another feature
+```
+
+❌ **Business logic in BLoC**
+```dart
+on<LoginRequested>((event, emit) {
+  if (event.email.isEmpty) {  // ← Use case responsibility
+    emit(AuthError('Email required'));
+  }
+});
+```
+
+❌ **Direct Data Connect in features**
+```dart
+final response = await FirebaseDataConnect.instance.query();  // ← Use repository
+```
+
+❌ **Global state variables**
+```dart
+User? currentUser;  // ← Use SessionStore
+```
+
+❌ **Direct Navigator.push**
+```dart
+Navigator.push(context, MaterialPageRoute(...));  // ← Use Modular
+```
+
+❌ **Hardcoded navigation**
+```dart
+Modular.to.navigate('/profile');  // ← Use safe extensions
+```
+
+## Summary
+
+The architecture enforces:
+- **Clean Architecture** with strict layer boundaries
+- **Feature Isolation** via zero cross-feature imports
+- **Session Management** via DataConnectService and SessionListener
+- **Connector Pattern** for reusable backend queries
+- **BLoC Lifecycle** safety with singletons and safe emit
+- **Navigation Safety** with typed navigators and fallbacks
+
+When implementing features:
+1. Follow package structure strictly
+2. Use connector repositories for backend access
+3. Register BLoCs as singletons with `.value()`
+4. Use safe navigation extensions
+5. Avoid prop drilling with direct BLoC access
+6. Keep domain pure and stable
+
+Architecture is not negotiable. When in doubt, refer to existing well-structured features or ask for clarification.

.agents/skills/krow-mobile-design-system/SKILL.md

@@ -0,0 +1,717 @@
+---
+name: krow-mobile-design-system
+description: KROW mobile design system usage rules covering colors, typography, icons, spacing, and UI component patterns. Use this when implementing UI in KROW mobile features, matching POC designs to production, creating themed widgets, enforcing visual consistency, or reviewing UI code compliance. Prevents hardcoded values and ensures brand consistency across staff and client apps. Critical for maintaining immutable design tokens.
+---
+
+# KROW Mobile Design System Usage
+
+This skill defines mandatory standards for UI implementation using the shared `apps/mobile/packages/design_system`. All UI must consume design system tokens exclusively.
+
+## When to Use This Skill
+
+- Implementing any UI in mobile features
+- Migrating POC/prototype designs to production
+- Creating new themed widgets or components
+- Reviewing UI code for design system compliance
+- Matching colors and typography from designs
+- Adding icons, spacing, or layout elements
+- Setting up theme configuration in apps
+- Refactoring UI code with hardcoded values
+
+## Core Principle
+
+**Design tokens (colors, typography, spacing) are IMMUTABLE and defined centrally.**
+
+Features consume tokens but NEVER modify them. The design system maintains visual coherence across all apps.
+
+## 1. Design System Ownership
+
+### Centralized Authority
+
+- `apps/mobile/packages/design_system` owns:
+  - All brand assets
+  - Colors and semantic color mappings
+  - Typography and font configurations
+  - Core UI components
+  - Icons and images
+  - Spacing, radius, elevation constants
+
+### No Local Overrides
+
+**✅ CORRECT:**
+```dart
+// Feature uses design system
+import 'package:design_system/design_system.dart';
+
+Container(
+  color: UiColors.background,
+  padding: EdgeInsets.all(UiConstants.spacingL),
+  child: Text(
+    'Hello',
+    style: UiTypography.display1m,
+  ),
+)
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Custom colors in feature
+const myBlue = Color(0xFF1A2234);
+
+// ❌ Custom text styles in feature
+const myStyle = TextStyle(fontSize: 24, fontWeight: FontWeight.bold);
+
+// ❌ Theme overrides in feature
+Theme(
+  data: ThemeData(primaryColor: Colors.blue),
+  child: MyWidget(),
+)
+```
+
+### Extension Policy
+
+If a required style is missing:
+1. **FIRST:** Add it to `design_system` following existing patterns
+2. **THEN:** Use it in your feature
+
+**DO NOT** create temporary workarounds with hardcoded values.
+
+## 2. Package Structure
+
+```
+apps/mobile/packages/design_system/
+├── lib/
+│   ├── src/
+│   │   ├── ui_colors.dart          # Color tokens
+│   │   ├── ui_typography.dart      # Text styles
+│   │   ├── ui_icons.dart           # Icon exports
+│   │   ├── ui_constants.dart       # Spacing, radius, elevation
+│   │   ├── ui_theme.dart           # ThemeData factory
+│   │   └── widgets/                # Shared UI components
+│   │       ├── custom_button.dart
+│   │       └── custom_app_bar.dart
+│   └── design_system.dart          # Public exports
+├── assets/
+│   ├── icons/
+│   ├── images/
+│   └── fonts/
+└── pubspec.yaml
+```
+
+## 3. Colors Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiColors for all color needs
+Container(color: UiColors.background)
+Text('Hello', style: TextStyle(color: UiColors.foreground))
+Icon(Icons.home, color: UiColors.primary)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Hardcoded hex colors
+Container(color: Color(0xFF1A2234))
+
+// ❌ Material color constants
+Container(color: Colors.blue)
+
+// ❌ Opacity on hardcoded colors
+Container(color: Color(0xFF1A2234).withOpacity(0.5))
+```
+
+### Available Color Categories
+
+**Brand Colors:**
+- `UiColors.primary` - Main brand color
+- `UiColors.secondary` - Secondary brand color
+- `UiColors.accent` - Accent highlights
+
+**Semantic Colors:**
+- `UiColors.background` - Page background
+- `UiColors.foreground` - Primary text color
+- `UiColors.card` - Card/container background
+- `UiColors.border` - Border colors
+- `UiColors.mutedForeground` - Secondary text
+
+**Status Colors:**
+- `UiColors.success` - Success states
+- `UiColors.warning` - Warning states
+- `UiColors.error` - Error states
+- `UiColors.info` - Information states
+
+### Color Matching from POCs
+
+When migrating POC designs:
+
+1. **Find closest match** in `UiColors`
+2. **Use existing color** even if slightly different
+3. **DO NOT add new colors** without design team approval
+
+**Example Process:**
+```dart
+// POC has: Color(0xFF2C3E50)
+// Find closest: UiColors.background or UiColors.card
+// Use: UiColors.card
+
+// POC has: Color(0xFF27AE60)
+// Find closest: UiColors.success
+// Use: UiColors.success
+```
+
+### Theme Access
+
+Colors can also be accessed via theme:
+```dart
+// Both are valid:
+Container(color: UiColors.primary)
+Container(color: Theme.of(context).colorScheme.primary)
+```
+
+## 4. Typography Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiTypography for all text
+Text('Title', style: UiTypography.display1m)
+Text('Body', style: UiTypography.body1r)
+Text('Label', style: UiTypography.caption1m)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Custom TextStyle
+Text('Title', style: TextStyle(
+  fontSize: 24,
+  fontWeight: FontWeight.bold,
+))
+
+// ❌ Manual font configuration
+Text('Body', style: TextStyle(
+  fontFamily: 'Inter',
+  fontSize: 16,
+))
+
+// ❌ Modifying existing styles inline
+Text('Title', style: UiTypography.display1m.copyWith(
+  fontSize: 28,  // ← Don't override size
+))
+```
+
+### Available Typography Styles
+
+**Display Styles (Large Headers):**
+- `UiTypography.display1m` - Display Medium
+- `UiTypography.display1sb` - Display Semi-Bold
+- `UiTypography.display1b` - Display Bold
+
+**Heading Styles:**
+- `UiTypography.heading1m` - H1 Medium
+- `UiTypography.heading1sb` - H1 Semi-Bold
+- `UiTypography.heading1b` - H1 Bold
+- `UiTypography.heading2m` - H2 Medium
+- `UiTypography.heading2sb` - H2 Semi-Bold
+
+**Body Styles:**
+- `UiTypography.body1r` - Body Regular
+- `UiTypography.body1m` - Body Medium
+- `UiTypography.body1sb` - Body Semi-Bold
+- `UiTypography.body2r` - Body 2 Regular
+
+**Caption/Label Styles:**
+- `UiTypography.caption1m` - Caption Medium
+- `UiTypography.caption1sb` - Caption Semi-Bold
+- `UiTypography.label1m` - Label Medium
+
+### Allowed Customizations
+
+**✅ ALLOWED (Color Only):**
+```dart
+// You MAY change color
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(
+    color: UiColors.error,  // ← OK
+  ),
+)
+```
+
+**❌ FORBIDDEN (Size, Weight, Family):**
+```dart
+// ❌ Don't change size
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontSize: 28),
+)
+
+// ❌ Don't change weight
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontWeight: FontWeight.w900),
+)
+
+// ❌ Don't change family
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontFamily: 'Roboto'),
+)
+```
+
+### Typography Matching from POCs
+
+When migrating:
+1. Identify text role (heading, body, caption)
+2. Find closest matching style in `UiTypography`
+3. Use existing style even if size/weight differs slightly
+
+## 5. Icons Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiIcons
+Icon(UiIcons.home)
+Icon(UiIcons.profile)
+Icon(UiIcons.chevronLeft)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Direct icon library imports
+import 'package:lucide_icons/lucide_icons.dart';
+Icon(LucideIcons.home)
+
+// ❌ Font Awesome direct
+import 'package:font_awesome_flutter/font_awesome_flutter.dart';
+FaIcon(FontAwesomeIcons.house)
+```
+
+### Why Centralize Icons?
+
+1. **Consistency:** Same icon for same action everywhere
+2. **Branding:** Unified icon set with consistent stroke weight
+3. **Swappability:** Change icon library in one place
+
+### Icon Libraries
+
+Design system uses:
+- `typedef _IconLib = LucideIcons;` (primary)
+- `typedef _IconLib2 = FontAwesomeIcons;` (secondary)
+
+**Features MUST NOT import these directly.**
+
+### Adding New Icons
+
+If icon missing:
+1. Add to `ui_icons.dart`:
+```dart
+class UiIcons {
+  static const home = _IconLib.home;
+  static const newIcon = _IconLib.newIcon;  // Add here
+}
+```
+2. Use in feature:
+```dart
+Icon(UiIcons.newIcon)
+```
+
+## 6. Spacing & Layout Constants
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiConstants for spacing
+Padding(padding: EdgeInsets.all(UiConstants.spacingL))
+SizedBox(height: UiConstants.spacingM)
+Container(
+  padding: EdgeInsets.symmetric(
+    horizontal: UiConstants.spacingL,
+    vertical: UiConstants.spacingM,
+  ),
+)
+
+// Use UiConstants for radius
+Container(
+  decoration: BoxDecoration(
+    borderRadius: BorderRadius.circular(UiConstants.radiusM),
+  ),
+)
+
+// Use UiConstants for elevation
+elevation: UiConstants.elevationLow
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Magic numbers
+Padding(padding: EdgeInsets.all(16.0))
+SizedBox(height: 24.0)
+BorderRadius.circular(8.0)
+elevation: 2.0
+```
+
+### Available Constants
+
+**Spacing:**
+```dart
+UiConstants.spacingXs   // Extra small
+UiConstants.spacingS    // Small
+UiConstants.spacingM    // Medium
+UiConstants.spacingL    // Large
+UiConstants.spacingXl   // Extra large
+UiConstants.spacing2xl  // 2x Extra large
+```
+
+**Border Radius:**
+```dart
+UiConstants.radiusS     // Small
+UiConstants.radiusM     // Medium
+UiConstants.radiusL     // Large
+UiConstants.radiusXl    // Extra large
+UiConstants.radiusFull  // Fully rounded
+```
+
+**Elevation:**
+```dart
+UiConstants.elevationNone
+UiConstants.elevationLow
+UiConstants.elevationMedium
+UiConstants.elevationHigh
+```
+
+## 7. Smart Widgets Usage
+
+### When to Use
+
+- **Prefer standard Flutter Material widgets** styled via theme
+- **Use design system widgets** for non-standard patterns
+- **Create new widgets** in design system if reused >3 features
+
+### Navigation in Widgets
+
+Widgets with navigation MUST use safe methods:
+
+**✅ CORRECT:**
+```dart
+// In UiAppBar back button:
+import 'package:flutter_modular/flutter_modular.dart';
+import 'package:krow_core/krow_core.dart';
+
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Modular.to.popSafe(),  // ← Safe pop
+)
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Direct Navigator
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Navigator.pop(context),
+)
+
+// ❌ Unsafe Modular
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Modular.to.pop(),  // Can crash
+)
+```
+
+### Composition Over Inheritance
+
+**✅ CORRECT:**
+```dart
+// Compose standard widgets
+Container(
+  padding: EdgeInsets.all(UiConstants.spacingL),
+  decoration: BoxDecoration(
+    color: UiColors.card,
+    borderRadius: BorderRadius.circular(UiConstants.radiusM),
+  ),
+  child: Column(
+    children: [
+      Text('Title', style: UiTypography.heading1sb),
+      SizedBox(height: UiConstants.spacingM),
+      Text('Body', style: UiTypography.body1r),
+    ],
+  ),
+)
+```
+
+**❌ AVOID:**
+```dart
+// ❌ Deep custom widget hierarchies
+class CustomCard extends StatelessWidget {
+  // Complex custom implementation
+}
+```
+
+## 8. Theme Configuration
+
+### App Setup
+
+Apps initialize theme ONCE in root MaterialApp:
+
+**✅ CORRECT:**
+```dart
+// apps/mobile/apps/staff/lib/app_widget.dart
+import 'package:design_system/design_system.dart';
+
+class StaffApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(
+      theme: StaffTheme.light,  // ← Design system theme
+      darkTheme: StaffTheme.dark,  // ← Optional dark mode
+      themeMode: ThemeMode.system,
+      // ...
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Custom theme in app
+MaterialApp.router(
+  theme: ThemeData(
+    primaryColor: Colors.blue,  // ← NO!
+  ),
+)
+
+// ❌ Theme override in feature
+Theme(
+  data: ThemeData(...),
+  child: MyFeatureWidget(),
+)
+```
+
+### Accessing Theme
+
+**Both methods valid:**
+```dart
+// Method 1: Direct design system import
+import 'package:design_system/design_system.dart';
+Text('Hello', style: UiTypography.body1r)
+
+// Method 2: Via theme context
+Text('Hello', style: Theme.of(context).textTheme.bodyMedium)
+```
+
+**Prefer Method 1** for explicit type safety.
+
+## 9. POC → Production Workflow
+
+### Step 1: Implement Structure (POC Matching)
+
+Implement UI layout exactly matching POC:
+```dart
+// Temporary: Match POC visually
+Container(
+  color: Color(0xFF1A2234),  // ← POC color
+  padding: EdgeInsets.all(16.0),  // ← POC spacing
+  child: Text(
+    'Title',
+    style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),  // ← POC style
+  ),
+)
+```
+
+**Purpose:** Ensure visual parity with POC before refactoring.
+
+### Step 2: Architecture Refactor
+
+Move to Clean Architecture:
+- Extract business logic to use cases
+- Move state management to BLoCs
+- Implement repository pattern
+- Use dependency injection
+
+### Step 3: Design System Integration
+
+Replace hardcoded values:
+```dart
+// Production: Design system tokens
+Container(
+  color: UiColors.background,  // ← Found closest match
+  padding: EdgeInsets.all(UiConstants.spacingL),  // ← Used constant
+  child: Text(
+    'Title',
+    style: UiTypography.heading1sb,  // ← Matched typography
+  ),
+)
+```
+
+**Color Matching:**
+- POC `#1A2234` → `UiColors.background`
+- POC `#3498DB` → `UiColors.primary`
+- POC `#27AE60` → `UiColors.success`
+
+**Typography Matching:**
+- POC `24px bold` → `UiTypography.heading1sb`
+- POC `16px regular` → `UiTypography.body1r`
+- POC `14px medium` → `UiTypography.caption1m`
+
+**Spacing Matching:**
+- POC `16px` → `UiConstants.spacingL`
+- POC `8px` → `UiConstants.spacingM`
+- POC `4px` → `UiConstants.spacingS`
+
+## 10. Anti-Patterns & Common Mistakes
+
+### ❌ Magic Numbers
+```dart
+// BAD
+EdgeInsets.all(12.0)
+SizedBox(height: 24.0)
+BorderRadius.circular(8.0)
+
+// GOOD
+EdgeInsets.all(UiConstants.spacingM)
+SizedBox(height: UiConstants.spacingL)
+BorderRadius.circular(UiConstants.radiusM)
+```
+
+### ❌ Local Themes
+```dart
+// BAD
+Theme(
+  data: ThemeData(primaryColor: Colors.blue),
+  child: MyWidget(),
+)
+
+// GOOD
+// Use global theme defined in app
+```
+
+### ❌ Hex Hunting
+```dart
+// BAD: Copy-paste from Figma
+Container(color: Color(0xFF3498DB))
+
+// GOOD: Find matching design system color
+Container(color: UiColors.primary)
+```
+
+### ❌ Direct Icon Library
+```dart
+// BAD
+import 'package:lucide_icons/lucide_icons.dart';
+Icon(LucideIcons.home)
+
+// GOOD
+Icon(UiIcons.home)
+```
+
+### ❌ Custom Text Styles
+```dart
+// BAD
+Text('Title', style: TextStyle(
+  fontSize: 24,
+  fontWeight: FontWeight.bold,
+  fontFamily: 'Inter',
+))
+
+// GOOD
+Text('Title', style: UiTypography.heading1sb)
+```
+
+## 11. Design System Review Checklist
+
+Before merging UI code:
+
+### ✅ Design System Compliance
+- [ ] No hardcoded `Color(...)` or `0xFF...` hex values
+- [ ] No custom `TextStyle(...)` definitions
+- [ ] All spacing uses `UiConstants.spacing*`
+- [ ] All radius uses `UiConstants.radius*`
+- [ ] All elevation uses `UiConstants.elevation*`
+- [ ] All icons from `UiIcons`, not direct library imports
+- [ ] Theme consumed from design system, no local overrides
+- [ ] Layout matches POC intent using design system primitives
+
+### ✅ Architecture Compliance
+- [ ] No business logic in widgets
+- [ ] State managed by BLoCs
+- [ ] Navigation uses Modular safe extensions
+- [ ] Localization used for all text (no hardcoded strings)
+- [ ] No direct Data Connect queries in widgets
+
+### ✅ Code Quality
+- [ ] Widget build methods concise (<50 lines)
+- [ ] Complex widgets extracted to separate files
+- [ ] Meaningful widget names
+- [ ] Doc comments on reusable widgets
+
+## 12. When to Extend Design System
+
+### Add New Color
+**When:** New brand color approved by design team
+
+**Process:**
+1. Add to `ui_colors.dart`:
+```dart
+class UiColors {
+  static const myNewColor = Color(0xFF123456);
+}
+```
+2. Update theme if needed
+3. Use in features
+
+### Add New Typography Style
+**When:** New text style pattern emerges across multiple features
+
+**Process:**
+1. Add to `ui_typography.dart`:
+```dart
+class UiTypography {
+  static const myNewStyle = TextStyle(
+    fontSize: 20,
+    fontWeight: FontWeight.w600,
+    fontFamily: _fontFamily,
+  );
+}
+```
+2. Use in features
+
+### Add Shared Widget
+**When:** Widget reused in 3+ features
+
+**Process:**
+1. Create in `lib/src/widgets/`:
+```dart
+// my_widget.dart
+class MyWidget extends StatelessWidget {
+  // Implementation using design system tokens
+}
+```
+2. Export from `design_system.dart`
+3. Use across features
+
+## Summary
+
+**Core Rules:**
+1. **All colors from `UiColors`** - Zero hex codes in features
+2. **All typography from `UiTypography`** - Zero custom TextStyle
+3. **All spacing/radius/elevation from `UiConstants`** - Zero magic numbers
+4. **All icons from `UiIcons`** - Zero direct library imports
+5. **Theme defined once** in app entry point
+6. **POC → Production** requires design system integration step
+
+**The Golden Rule:** Design system is immutable. Features adapt to the system, not the other way around.
+
+When implementing UI:
+1. Import `package:design_system/design_system.dart`
+2. Use design system tokens exclusively
+3. Match POC intent with available tokens
+4. Request new tokens only when truly necessary
+5. Never create temporary hardcoded workarounds
+
+Visual consistency is non-negotiable. Every pixel must come from the design system.

.agents/skills/krow-mobile-development-rules/SKILL.md

@@ -0,0 +1,646 @@
+---
+name: krow-mobile-development-rules
+description: Enforce KROW mobile app development standards including file structure, naming conventions, logic placement boundaries, localization, Data Connect integration, and prototype migration rules. Use this skill whenever working on KROW Flutter mobile features, creating new packages, implementing BLoCs, integrating with backend, or migrating from prototypes. Critical for maintaining clean architecture and preventing architectural degradation.
+---
+
+# KROW Mobile Development Rules
+
+These rules are **NON-NEGOTIABLE** enforcement guidelines for the KROW mobile application. They prevent architectural degradation and ensure consistency across the codebase.
+
+## When to Use This Skill
+
+- Creating new mobile features or packages
+- Implementing BLoCs, Use Cases, or Repositories
+- Integrating with Firebase Data Connect backend
+- Migrating code from prototypes
+- Reviewing mobile code for compliance
+- Setting up new feature modules
+- Handling user sessions and authentication
+- Implementing navigation flows
+
+## 1. File Creation & Package Structure
+
+### Feature-First Packaging
+
+**✅ DO:**
+- Create new features as independent packages:
+  ```
+  apps/mobile/packages/features/<app_name>/<feature_name>/
+  ├── lib/
+  │   ├── src/
+  │   │   ├── domain/
+  │   │   │   ├── repositories/
+  │   │   │   └── usecases/
+  │   │   ├── data/
+  │   │   │   └── repositories_impl/
+  │   │   └── presentation/
+  │   │       ├── blocs/
+  │   │       ├── pages/
+  │   │       └── widgets/
+  │   └── <feature_name>.dart  # Barrel file
+  └── pubspec.yaml
+  ```
+
+**❌ DON'T:**
+- Add features to `apps/mobile/packages/core` directly
+- Create files in app directories (`apps/mobile/apps/client/` or `apps/mobile/apps/staff/`)
+- Create cross-feature or cross-app dependencies (features must not import other features)
+
+### Path Conventions (Strict)
+
+Follow these exact paths:
+
+| Layer | Path Pattern | Example |
+|-------|-------------|---------|
+| **Entities** | `apps/mobile/packages/domain/lib/src/entities/<entity>.dart` | `user.dart`, `shift.dart` |
+| **Repository Interface** | `.../features/<app>/<feature>/lib/src/domain/repositories/<name>_repository_interface.dart` | `auth_repository_interface.dart` |
+| **Repository Impl** | `.../features/<app>/<feature>/lib/src/data/repositories_impl/<name>_repository_impl.dart` | `auth_repository_impl.dart` |
+| **Use Cases** | `.../features/<app>/<feature>/lib/src/application/<name>_usecase.dart` | `login_usecase.dart` |
+| **BLoCs** | `.../features/<app>/<feature>/lib/src/presentation/blocs/<name>_bloc.dart` | `auth_bloc.dart` |
+| **Pages** | `.../features/<app>/<feature>/lib/src/presentation/pages/<name>_page.dart` | `login_page.dart` |
+| **Widgets** | `.../features/<app>/<feature>/lib/src/presentation/widgets/<name>_widget.dart` | `password_field.dart` |
+
+### Barrel Files
+
+**✅ DO:**
+```dart
+// lib/auth_feature.dart
+export 'src/presentation/pages/login_page.dart';
+export 'src/domain/repositories/auth_repository_interface.dart';
+// Only export PUBLIC API
+```
+
+**❌ DON'T:**
+```dart
+// Don't export internal implementation details
+export 'src/data/repositories_impl/auth_repository_impl.dart';
+export 'src/presentation/blocs/auth_bloc.dart';
+```
+
+## 2. Naming Conventions (Dart Standard)
+
+| Type | Convention | Example | File Name |
+|------|-----------|---------|-----------|
+| **Files** | `snake_case` | `user_profile_page.dart` | - |
+| **Classes** | `PascalCase` | `UserProfilePage` | - |
+| **Variables** | `camelCase` | `userProfile` | - |
+| **Interfaces** | End with `Interface` | `AuthRepositoryInterface` | `auth_repository_interface.dart` |
+| **Implementations** | End with `Impl` | `AuthRepositoryImpl` | `auth_repository_impl.dart` |
+| **BLoCs** | End with `Bloc` or `Cubit` | `AuthBloc`, `ProfileCubit` | `auth_bloc.dart` |
+| **Use Cases** | End with `UseCase` | `LoginUseCase` | `login_usecase.dart` |
+
+## 3. Logic Placement (Zero Tolerance Boundaries)
+
+### Business Rules → Use Cases ONLY
+
+**✅ CORRECT:**
+```dart
+// login_usecase.dart
+class LoginUseCase extends UseCase<User, LoginParams> {
+  @override
+  Future<Either<Failure, User>> call(LoginParams params) async {
+    // Business logic here: validation, transformation, orchestration
+    if (params.email.isEmpty) {
+      return Left(ValidationFailure('Email required'));
+    }
+    return await repository.login(params);
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Business logic in BLoC
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) {
+    if (event.email.isEmpty) {  // ← NO! This is business logic
+      emit(AuthError('Email required'));
+    }
+  });
+}
+
+// ❌ Business logic in Widget
+class LoginPage extends StatelessWidget {
+  void _login() {
+    if (_emailController.text.isEmpty) {  // ← NO! This is business logic
+      showSnackbar('Email required');
+    }
+  }
+}
+```
+
+### State Logic → BLoCs ONLY
+
+**✅ CORRECT:**
+```dart
+// auth_bloc.dart
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) async {
+    emit(AuthLoading());
+    final result = await loginUseCase(LoginParams(email: event.email));
+    result.fold(
+      (failure) => emit(AuthError(failure)),
+      (user) => emit(AuthAuthenticated(user)),
+    );
+  });
+}
+
+// login_page.dart (StatelessWidget)
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<AuthBloc, AuthState>(
+      builder: (context, state) {
+        if (state is AuthLoading) return LoadingIndicator();
+        if (state is AuthError) return ErrorWidget(state.message);
+        return LoginForm();
+      },
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ setState in Pages for complex state
+class LoginPage extends StatefulWidget {
+  @override
+  State<LoginPage> createState() => _LoginPageState();
+}
+
+class _LoginPageState extends State<LoginPage> {
+  bool _isLoading = false;  // ← NO! Use BLoC
+  String? _error;          // ← NO! Use BLoC
+  
+  void _login() {
+    setState(() => _isLoading = true);  // ← NO! Use BLoC
+  }
+}
+```
+
+**RECOMMENDATION:** Pages should be `StatelessWidget` with state delegated to BLoCs.
+
+### Data Transformation → Repositories
+
+**✅ CORRECT:**
+```dart
+// profile_repository_impl.dart
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  @override
+  Future<Staff> getProfile(String id) async {
+    final response = await dataConnect.getStaffById(id: id).execute();
+    // Data transformation happens here
+    return Staff(
+      id: response.data.staff.id,
+      name: response.data.staff.name,
+      // Map Data Connect model to Domain entity
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ JSON parsing in UI
+class ProfilePage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    final json = jsonDecode(response.body);  // ← NO!
+    final name = json['name'];
+  }
+}
+
+// ❌ JSON parsing in Domain Use Case
+class GetProfileUseCase extends UseCase<Staff, String> {
+  @override
+  Future<Either<Failure, Staff>> call(String id) async {
+    final response = await http.get('/staff/$id');
+    final json = jsonDecode(response.body);  // ← NO!
+  }
+}
+```
+
+### Navigation → Flutter Modular + Safe Extensions
+
+**✅ CORRECT:**
+```dart
+// Use Safe Navigation Extensions
+import 'package:krow_core/krow_core.dart';
+
+// In widget/BLoC:
+Modular.to.safePush('/profile');
+Modular.to.safeNavigate('/home');
+Modular.to.popSafe();
+
+// Even better: Use Typed Navigators
+Modular.to.toStaffHome();  // Defined in StaffNavigator
+Modular.to.toShiftDetails(shiftId: '123');
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Direct Navigator.push
+Navigator.push(
+  context,
+  MaterialPageRoute(builder: (_) => ProfilePage()),
+);
+
+// ❌ Direct Modular navigation without safety
+Modular.to.navigate('/profile');  // ← Can cause blank screens
+Modular.to.pop();  // ← Can crash if stack is empty
+```
+
+**PATTERN:** All navigation MUST have fallback to Home page. Safe extensions automatically handle this.
+
+### Session Management → DataConnectService + SessionHandlerMixin
+
+**✅ CORRECT:**
+```dart
+// In main.dart:
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  
+  // Initialize session listener (pick allowed roles for app)
+  DataConnectService.instance.initializeAuthListener(
+    allowedRoles: ['STAFF', 'BOTH'],  // for staff app
+  );
+  
+  runApp(
+    SessionListener(  // Wraps entire app
+      child: ModularApp(module: AppModule(), child: AppWidget()),
+    ),
+  );
+}
+
+// In repository:
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  final DataConnectService _service = DataConnectService.instance;
+  
+  @override
+  Future<Staff> getProfile(String id) async {
+    // _service.run() handles:
+    // - Auth validation
+    // - Token refresh (if <5 min to expiry)
+    // - Error handling with 3 retries
+    return await _service.run(() async {
+      final response = await _service.connector
+          .getStaffById(id: id)
+          .execute();
+      return _mapToStaff(response.data.staff);
+    });
+  }
+}
+```
+
+**PATTERN:**
+- **SessionListener** widget wraps app and shows dialogs for session errors
+- **SessionHandlerMixin** in `DataConnectService` provides automatic token refresh
+- **3-attempt retry logic** with exponential backoff (1s → 2s → 4s)
+- **Role validation** configurable per app
+
+## 4. Localization Integration (core_localization)
+
+All user-facing text MUST be localized.
+
+### String Management
+
+**✅ CORRECT:**
+```dart
+// In presentation layer:
+import 'package:core_localization/core_localization.dart';
+
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Text(context.strings.loginButton);  // ← From localization
+    return ElevatedButton(
+      onPressed: _login,
+      child: Text(context.strings.submit),
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Hardcoded English strings
+Text('Login')
+Text('Submit')
+ElevatedButton(child: Text('Click here'))
+```
+
+### BLoC Integration
+
+**✅ CORRECT:**
+```dart
+// BLoCs emit domain failures (not localized strings)
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) async {
+    final result = await loginUseCase(params);
+    result.fold(
+      (failure) => emit(AuthError(failure)),  // ← Domain failure
+      (user) => emit(AuthAuthenticated(user)),
+    );
+  });
+}
+
+// UI translates failures to user-friendly messages
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<AuthBloc, AuthState>(
+      builder: (context, state) {
+        if (state is AuthError) {
+          final message = ErrorTranslator.translate(
+            state.failure,
+            context.strings,
+          );
+          return ErrorWidget(message);  // ← Localized
+        }
+      },
+    );
+  }
+}
+```
+
+### App Setup
+
+Apps must import `LocalizationModule()`:
+```dart
+// app_module.dart
+class AppModule extends Module {
+  @override
+  List<Module> get imports => [
+    LocalizationModule(),  // ← Required
+    DataConnectModule(),
+  ];
+}
+
+// main.dart
+runApp(
+  BlocProvider<LocaleBloc>(  // ← Expose locale state
+    create: (_) => Modular.get<LocaleBloc>(),
+    child: TranslationProvider(  // ← Enable context.strings
+      child: MaterialApp.router(...),
+    ),
+  ),
+);
+```
+
+## 5. Data Connect Integration
+
+All backend access goes through `DataConnectService`.
+
+### Repository Pattern
+
+**Step 1:** Define interface in feature domain:
+```dart
+// domain/repositories/profile_repository_interface.dart
+abstract interface class ProfileRepositoryInterface {
+  Future<Staff> getProfile(String id);
+  Future<bool> updateProfile(Staff profile);
+}
+```
+
+**Step 2:** Implement using `DataConnectService.run()`:
+```dart
+// data/repositories_impl/profile_repository_impl.dart
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  final DataConnectService _service = DataConnectService.instance;
+  
+  @override
+  Future<Staff> getProfile(String id) async {
+    return await _service.run(() async {
+      final response = await _service.connector
+          .getStaffById(id: id)
+          .execute();
+      return _mapToStaff(response.data.staff);
+    });
+  }
+}
+```
+
+**Benefits of `_service.run()`:**
+- ✅ Automatic auth validation
+- ✅ Token refresh if needed
+- ✅ 3-attempt retry with exponential backoff
+- ✅ Consistent error handling
+
+### Session Store Pattern
+
+After successful auth, populate session stores:
+```dart
+// For Staff App:
+StaffSessionStore.instance.setSession(
+  StaffSession(
+    user: user,
+    staff: staff,
+    ownerId: ownerId,
+  ),
+);
+
+// For Client App:
+ClientSessionStore.instance.setSession(
+  ClientSession(
+    user: user,
+    business: business,
+  ),
+);
+```
+
+**Lazy Loading:** If session is null, fetch via `getStaffById()` or `getBusinessById()` and update store.
+
+## 6. Prototype Migration Rules
+
+When migrating from `prototypes/`:
+
+### ✅ MAY Copy
+- Icons, images, assets (but match to design system)
+- `build` methods for UI layout structure
+- Screen flow and navigation patterns
+
+### ❌ MUST REJECT & REFACTOR
+- `GetX`, `Provider`, or `MVC` patterns
+- Any state management not using BLoC
+- Direct HTTP calls (must use Data Connect)
+- Hardcoded colors/typography (must use design system)
+- Global state variables
+- Navigation without Modular
+
+### Colors & Typography Migration
+**When matching POC to production:**
+1. Find closest color in `UiColors` (don't add new colors without approval)
+2. Find closest text style in `UiTypography`
+3. Use design system constants, NOT POC hardcoded values
+
+**DO NOT change the design system itself.** Colors and typography are FINAL. Match your feature to the system, not the other way around.
+
+## 7. Handling Ambiguity
+
+If requirements are unclear:
+
+1. **STOP** - Don't guess domain fields or workflows
+2. **ANALYZE** - Refer to:
+   - Architecture: `apps/mobile/docs/01-architecture-principles.md`
+   - Design System: `apps/mobile/docs/02-design-system-usage.md`
+   - Existing features for patterns
+3. **DOCUMENT** - Add `// ASSUMPTION: <explanation>` if you must proceed
+4. **ASK** - Prefer asking user for clarification on business rules
+
+## 8. Dependencies
+
+### DO NOT
+- Add 3rd party packages without checking `apps/mobile/packages/core` first
+- Add `firebase_auth` or `firebase_data_connect` to Feature packages (they belong in `data_connect` only)
+- Use `addSingleton` for BLoCs (always use `add` method in Modular)
+
+### DO
+- Use `DataConnectService.instance` for backend operations
+- Use Flutter Modular for dependency injection
+- Register BLoCs with `i.addSingleton<CubitType>(() => CubitType(...))`
+- Register Use Cases as factories or singletons as needed
+
+## 9. Error Handling Pattern
+
+### Domain Failures
+```dart
+// domain/failures/auth_failure.dart
+abstract class AuthFailure extends Failure {
+  const AuthFailure(String message) : super(message);
+}
+
+class InvalidCredentialsFailure extends AuthFailure {
+  const InvalidCredentialsFailure() : super('Invalid credentials');
+}
+```
+
+### Repository Error Mapping
+```dart
+// Map Data Connect exceptions to Domain failures
+try {
+  final response = await dataConnect.query();
+  return Right(response);
+} on DataConnectException catch (e) {
+  if (e.message.contains('unauthorized')) {
+    return Left(InvalidCredentialsFailure());
+  }
+  return Left(ServerFailure(e.message));
+}
+```
+
+### UI Feedback
+```dart
+// BLoC emits error state
+emit(AuthError(failure));
+
+// UI shows user-friendly message
+if (state is AuthError) {
+  final message = ErrorTranslator.translate(state.failure, context.strings);
+  ScaffoldMessenger.of(context).showSnackBar(
+    SnackBar(content: Text(message)),
+  );
+}
+```
+
+### Session Errors
+`SessionListener` automatically shows dialogs for:
+- Session expiration
+- Token refresh failures
+- Network errors during auth
+
+## 10. Testing Requirements
+
+### Unit Tests
+```dart
+// Test use cases with real repository implementations
+test('login with valid credentials returns user', () async {
+  final useCase = LoginUseCase(repository: mockRepository);
+  final result = await useCase(LoginParams(email: 'test@test.com'));
+  expect(result.isRight(), true);
+});
+```
+
+### Widget Tests
+```dart
+// Test UI widgets and BLoC interactions
+testWidgets('shows loading indicator when logging in', (tester) async {
+  await tester.pumpWidget(
+    BlocProvider<AuthBloc>(
+      create: (_) => authBloc,
+      child: LoginPage(),
+    ),
+  );
+  
+  authBloc.add(LoginRequested(email: 'test@test.com'));
+  await tester.pump();
+  
+  expect(find.byType(LoadingIndicator), findsOneWidget);
+});
+```
+
+### Integration Tests
+- Test full feature flows end-to-end with Data Connect
+- Use dependency injection to swap implementations if needed
+
+## 11. Clean Code Principles
+
+### Documentation
+- ✅ Add human readable doc comments for `dartdoc`  for all classes and methods.
+```dart
+/// Authenticates user with email and password.
+/// 
+/// Returns [User] on success or [AuthFailure] on failure.
+/// Throws [NetworkException] if connection fails.
+class LoginUseCase extends UseCase<User, LoginParams> {
+  // ...
+}
+```
+
+### Single Responsibility
+- Keep methods focused on one task
+- Extract complex logic to separate methods
+- Keep widget build methods concise
+- Extract complex widgets to separate files
+
+### Meaningful Names
+```dart
+// ✅ GOOD
+final isProfileComplete = await checkProfileCompletion();
+final userShifts = await fetchUserShifts();
+
+// ❌ BAD
+final flag = await check();
+final data = await fetch();
+```
+
+## Enforcement Checklist
+
+Before merging any mobile feature code:
+
+### Architecture Compliance
+- [ ] Feature follows package structure (domain/data/presentation)
+- [ ] No business logic in BLoCs or Widgets
+- [ ] All state management via BLoCs
+- [ ] All backend access via repositories
+- [ ] Session accessed via SessionStore, not global state
+- [ ] Navigation uses Flutter Modular safe extensions
+- [ ] No feature-to-feature imports
+
+### Code Quality
+- [ ] No hardcoded strings (use localization)
+- [ ] No hardcoded colors/typography (use design system)
+- [ ] All spacing uses UiConstants
+- [ ] Doc comments on public APIs
+- [ ] Meaningful variable names
+- [ ] Zero analyzer warnings
+
+### Integration
+- [ ] Data Connect queries via `_service.run()`
+- [ ] Error handling with domain failures
+- [ ] Proper dependency injection in modules
+
+## Summary
+
+The key principle: **Clean Architecture with zero tolerance for violations.** Business logic in Use Cases, state in BLoCs, data access in Repositories, UI in Widgets. Features are isolated, backend is centralized, localization is mandatory, and design system is immutable.
+
+When in doubt, refer to existing features following these patterns or ask for clarification. It's better to ask than to introduce architectural debt.

.agents/skills/krow-mobile-release/SKILL.md

@@ -0,0 +1,778 @@
+---
+name: krow-mobile-release
+description: KROW mobile app release process including versioning strategy, CHANGELOG management, GitHub Actions workflows, APK signing, Git tagging, and hotfix procedures. Use this when preparing mobile releases, updating CHANGELOGs, triggering release workflows, creating hotfix branches, troubleshooting release issues, or documenting release features. Covers both staff (worker) and client mobile products across dev/stage/prod environments.
+---
+
+# KROW Mobile Release Process
+
+This skill defines the comprehensive release process for KROW mobile applications (staff and client). It covers versioning, changelog management, GitHub Actions automation, and hotfix procedures.
+
+## When to Use This Skill
+
+- Preparing for a mobile app release
+- Updating CHANGELOG files with new features
+- Triggering GitHub Actions release workflows
+- Creating hotfix branches for production issues
+- Understanding version numbering strategy
+- Setting up APK signing secrets
+- Troubleshooting release workflow failures
+- Documenting release notes
+- Managing release cadence (dev → stage → prod)
+
+## Quick Reference
+
+### Release Workflows
+- **Product Release:** [GitHub Actions - Product Release](https://github.com/Oloodi/krow-workforce/actions/workflows/product-release.yml)
+- **Hotfix Creation:** [GitHub Actions - Product Hotfix](https://github.com/Oloodi/krow-workforce/actions/workflows/hotfix-branch-creation.yml)
+
+### Key Files
+- **Staff CHANGELOG:** `apps/mobile/apps/staff/CHANGELOG.md`
+- **Client CHANGELOG:** `apps/mobile/apps/client/CHANGELOG.md`
+- **Staff Version:** `apps/mobile/apps/staff/pubspec.yaml`
+- **Client Version:** `apps/mobile/apps/client/pubspec.yaml`
+
+### Comprehensive Documentation
+For complete details, see: [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) (900+ lines)
+
+## 1. Versioning Strategy
+
+### Format
+
+```
+v{major}.{minor}.{patch}-{milestone}
+```
+
+**Examples:**
+- `v0.0.1-m4` - Milestone 4 release
+- `v0.1.0-m5` - Minor version bump for Milestone 5
+- `v1.0.0` - First production release (no milestone suffix)
+
+### Semantic Versioning Rules
+
+**Major (X.0.0):**
+- Breaking changes
+- Complete architecture overhaul
+- Incompatible API changes
+
+**Minor (0.X.0):**
+- New features
+- Backwards-compatible additions
+- Milestone completions
+
+**Patch (0.0.X):**
+- Bug fixes
+- Security patches
+- Performance improvements
+
+**Milestone Suffix:**
+- `-m1`, `-m2`, `-m3`, `-m4`, etc.
+- Indicates pre-production milestone phase
+- Removed for production releases
+
+### Version Location
+
+Versions are defined in `pubspec.yaml`:
+
+**Staff App:**
+```yaml
+# apps/mobile/apps/staff/pubspec.yaml
+name: krow_staff_app
+version: 0.0.1-m4+1  # version+build_number
+```
+
+**Client App:**
+```yaml
+# apps/mobile/apps/client/pubspec.yaml
+name: krow_client_app
+version: 0.0.1-m4+1
+```
+
+**Format:** `version+build`
+- `version`: Semantic version with milestone (e.g., `0.0.1-m4`)
+- `build`: Build number (increments with each build, e.g., `+1`, `+2`)
+
+## 2. CHANGELOG Management
+
+### Format
+
+Each app maintains a separate CHANGELOG following [Keep a Changelog](https://keepachangelog.com/) format.
+
+**Structure:**
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- New feature descriptions
+
+### Changed
+- Modified feature descriptions
+
+### Fixed
+- Bug fix descriptions
+
+### Removed
+- Removed feature descriptions
+
+## [0.0.1-m4] - Milestone 4 - 2026-03-05
+
+### Added
+- Profile management with 13 subsections
+- Documents & certificates management
+- Benefits overview section
+- Camera/gallery support for attire verification
+
+### Changed
+- Enhanced session management with auto token refresh
+
+### Fixed
+- Navigation fallback to home on invalid routes
+```
+
+### Section Guidelines
+
+**[Unreleased]**
+- Work in progress
+- Features merged to dev but not released
+- Updated continuously during development
+
+**[Version] - Milestone X - Date**
+- Released version
+- Format: `[X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
+- Organized by change type (Added/Changed/Fixed/Removed)
+
+### Change Type Definitions
+
+**Added:**
+- New features
+- New UI screens
+- New API integrations
+- New user-facing capabilities
+
+**Changed:**
+- Modifications to existing features
+- UI/UX improvements
+- Performance enhancements
+- Refactored code (if user-facing impact)
+
+**Fixed:**
+- Bug fixes
+- Error handling improvements
+- Crash fixes
+- UI/UX issues resolved
+
+**Removed:**
+- Deprecated features
+- Removed screens or capabilities
+- Discontinued integrations
+
+### Writing Guidelines
+
+**✅ GOOD:**
+```markdown
+### Added
+- Profile management with 13 subsections organized into onboarding, compliance, finances, and support categories
+- Documents & certificates management with upload, status tracking, and expiry dates
+- Camera and gallery support for attire verification with photo capture
+- Benefits overview section displaying perks and company information
+```
+
+**❌ BAD:**
+```markdown
+### Added
+- New stuff
+- Fixed things
+- Updated code
+```
+
+**Key Principles:**
+- Be specific and descriptive
+- Focus on user-facing changes
+- Mention UI screens, features, or capabilities
+- Avoid technical jargon users won't understand
+- Group related changes together
+
+### Updating CHANGELOG Workflow
+
+**Step 1:** During development, add to `[Unreleased]`:
+```markdown
+## [Unreleased]
+
+### Added
+- New shift calendar view with month/week toggle
+- Shift acceptance confirmation dialog
+
+### Fixed
+- Navigation crash when popping empty stack
+```
+
+**Step 2:** Before release, move to version section:
+```markdown
+## [0.1.0-m5] - Milestone 5 - 2026-03-15
+
+### Added
+- New shift calendar view with month/week toggle
+- Shift acceptance confirmation dialog
+
+### Fixed
+- Navigation crash when popping empty stack
+
+## [Unreleased]
+<!-- Empty for next development cycle -->
+```
+
+**Step 3:** Update version in `pubspec.yaml`:
+```yaml
+version: 0.1.0-m5+1
+```
+
+## 3. Git Tagging Strategy
+
+### Tag Format
+
+```
+krow-withus-<app>-mobile/<env>-vX.Y.Z
+```
+
+**Components:**
+- `<app>`: `worker` (staff) or `client`
+- `<env>`: `dev`, `stage`, or `prod`
+- `vX.Y.Z`: Semantic version (from pubspec.yaml)
+
+**Examples:**
+```
+krow-withus-worker-mobile/dev-v0.0.1-m4
+krow-withus-worker-mobile/stage-v0.0.1-m4
+krow-withus-worker-mobile/prod-v0.0.1-m4
+krow-withus-client-mobile/dev-v0.0.1-m4
+```
+
+### Tag Creation
+
+Tags are created automatically by GitHub Actions workflows. Manual tagging:
+
+```bash
+# Staff app - dev environment
+git tag krow-withus-worker-mobile/dev-v0.0.1-m4
+git push origin krow-withus-worker-mobile/dev-v0.0.1-m4
+
+# Client app - prod environment
+git tag krow-withus-client-mobile/prod-v1.0.0
+git push origin krow-withus-client-mobile/prod-v1.0.0
+```
+
+### Tag Listing
+
+```bash
+# List all mobile tags
+git tag -l "krow-withus-*-mobile/*"
+
+# List staff app tags
+git tag -l "krow-withus-worker-mobile/*"
+
+# List production tags
+git tag -l "krow-withus-*-mobile/prod-*"
+```
+
+## 4. GitHub Actions Workflows
+
+### 4.1 Product Release Workflow
+
+**File:** `.github/workflows/product-release.yml`
+
+**Purpose:** Automated production releases with APK signing
+
+**Trigger:** Manual dispatch via GitHub UI
+
+**Inputs:**
+- `app`: Select `worker` (staff) or `client`
+- `environment`: Select `dev`, `stage`, or `prod`
+
+**Process:**
+1. ✅ Extracts version from `pubspec.yaml` automatically
+2. ✅ Builds signed APKs for selected app
+3. ✅ Creates GitHub release with CHANGELOG notes
+4. ✅ Tags release (e.g., `krow-withus-worker-mobile/dev-v0.0.1-m4`)
+5. ✅ Uploads APKs as release assets
+6. ✅ Generates step summary with emojis
+
+**Key Features:**
+- **No manual version input** - reads from pubspec.yaml
+- **APK signing** - uses GitHub Secrets for keystore
+- **CHANGELOG extraction** - pulls release notes automatically
+- **Visual feedback** - emojis in all steps
+
+**Usage:**
+```
+1. Go to: GitHub Actions → "📦 Product Release"
+2. Click "Run workflow"
+3. Select app (worker/client)
+4. Select environment (dev/stage/prod)
+5. Click "Run workflow"
+6. Wait for completion (~5-10 minutes)
+```
+
+**Release Naming:**
+```
+Krow With Us - Worker Product - DEV - v0.0.1-m4
+Krow With Us - Client Product - PROD - v1.0.0
+```
+
+### 4.2 Product Hotfix Workflow
+
+**File:** `.github/workflows/hotfix-branch-creation.yml`
+
+**Purpose:** Emergency production fix automation
+
+**Trigger:** Manual dispatch with version input
+
+**Inputs:**
+- `current_version`: Current production version (e.g., `0.0.1-m4`)
+- `issue_description`: Brief description of the hotfix
+
+**Process:**
+1. ✅ Creates `hotfix/<version>` branch from latest production tag
+2. ✅ Auto-increments PATCH version (e.g., `0.0.1-m4` → `0.0.2-m4`)
+3. ✅ Updates `pubspec.yaml` with new version
+4. ✅ Updates `CHANGELOG.md` with hotfix section
+5. ✅ Creates PR back to main branch
+6. ✅ Includes hotfix instructions in PR description
+
+**Usage:**
+```
+1. Go to: GitHub Actions → "🚨 Product Hotfix - Create Branch"
+2. Click "Run workflow"
+3. Enter current production version (e.g., 0.0.1-m4)
+4. Enter issue description (e.g., "critical crash on login")
+5. Click "Run workflow"
+6. Workflow creates branch and PR
+7. Fix bug on hotfix branch
+8. Merge PR to main
+9. Use Product Release workflow to deploy
+```
+
+**Hotfix Branch Naming:**
+```
+hotfix/0.0.2-m4-critical-crash-on-login
+```
+
+### 4.3 Helper Scripts
+
+**Location:** `.github/scripts/`
+
+**Available Scripts:**
+1. **extract-version.sh** - Extract version from pubspec.yaml
+2. **generate-tag-name.sh** - Generate standardized tag names
+3. **extract-release-notes.sh** - Extract CHANGELOG sections
+4. **create-release-summary.sh** - Generate GitHub Step Summary with emojis
+
+**Script Permissions:**
+```bash
+chmod +x .github/scripts/*.sh
+```
+
+**Usage Example:**
+```bash
+# Extract version from staff app
+.github/scripts/extract-version.sh apps/mobile/apps/staff/pubspec.yaml
+
+# Generate tag name
+.github/scripts/generate-tag-name.sh worker dev 0.0.1-m4
+
+# Extract release notes for version
+.github/scripts/extract-release-notes.sh apps/mobile/apps/staff/CHANGELOG.md 0.0.1-m4
+```
+
+## 5. APK Signing Setup
+
+### Required GitHub Secrets (24 Total)
+
+**Per App (12 secrets each):**
+
+**Staff (Worker) App:**
+```
+STAFF_UPLOAD_KEYSTORE_BASE64       # Base64-encoded keystore file
+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 file
+```
+
+**Client App:**
+```
+CLIENT_UPLOAD_KEYSTORE_BASE64
+CLIENT_UPLOAD_STORE_PASSWORD
+CLIENT_UPLOAD_KEY_ALIAS
+CLIENT_UPLOAD_KEY_PASSWORD
+CLIENT_KEYSTORE_PROPERTIES_BASE64
+```
+
+### Generating Secrets
+
+**Step 1: Create Keystore**
+
+```bash
+# For staff app
+keytool -genkey -v \
+  -keystore staff-upload-keystore.jks \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -alias staff-upload
+
+# For client app
+keytool -genkey -v \
+  -keystore client-upload-keystore.jks \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -alias client-upload
+```
+
+**Step 2: Base64 Encode**
+
+```bash
+# Encode keystore
+base64 -i staff-upload-keystore.jks | tr -d '\n' > staff-keystore.txt
+
+# Encode key.properties
+base64 -i key.properties | tr -d '\n' > key-props.txt
+```
+
+**Step 3: Add to GitHub Secrets**
+
+```
+Repository → Settings → Secrets and variables → Actions → New repository secret
+```
+
+Add each secret:
+- Name: `STAFF_UPLOAD_KEYSTORE_BASE64`
+- Value: Contents of `staff-keystore.txt`
+
+Repeat for all 24 secrets.
+
+### key.properties Format
+
+```properties
+storePassword=your_store_password
+keyPassword=your_key_password
+keyAlias=staff-upload
+storeFile=../staff-upload-keystore.jks
+```
+
+## 6. Release Process (Step-by-Step)
+
+### Standard Release (Dev/Stage/Prod)
+
+**Step 1: Prepare CHANGELOG**
+
+Update `CHANGELOG.md` with all changes since last release:
+```markdown
+## [0.1.0-m5] - Milestone 5 - 2026-03-15
+
+### Added
+- Shift calendar with month/week views
+- Enhanced navigation with typed routes
+- Profile completion wizard
+
+### Fixed
+- Session token refresh timing
+- Navigation fallback logic
+```
+
+**Step 2: Update Version**
+
+Edit `pubspec.yaml`:
+```yaml
+version: 0.1.0-m5+1  # Changed from 0.0.1-m4+1
+```
+
+**Step 3: Commit and Push**
+
+```bash
+git add apps/mobile/apps/staff/CHANGELOG.md
+git add apps/mobile/apps/staff/pubspec.yaml
+git commit -m "chore(staff): prepare v0.1.0-m5 release"
+git push origin dev
+```
+
+**Step 4: Trigger Workflow**
+
+1. Go to GitHub Actions → "📦 Product Release"
+2. Click "Run workflow"
+3. Select branch: `dev`
+4. Select app: `worker` (or `client`)
+5. Select environment: `dev` (or `stage`, `prod`)
+6. Click "Run workflow"
+
+**Step 5: Monitor Progress**
+
+Watch workflow execution:
+- ⏳ Version extraction
+- ⏳ APK building
+- ⏳ APK signing
+- ⏳ GitHub Release creation
+- ⏳ Tag creation
+- ⏳ Asset upload
+
+**Step 6: Verify Release**
+
+1. Check GitHub Releases page
+2. Download APK to verify
+3. Install on test device
+4. Verify version in app
+
+### Hotfix Release
+
+**Step 1: Identify Production Issue**
+
+- Critical bug in production
+- User-reported crash
+- Security vulnerability
+
+**Step 2: Trigger Hotfix Workflow**
+
+1. Go to GitHub Actions → "🚨 Product Hotfix - Create Branch"
+2. Click "Run workflow"
+3. Enter current version: `0.0.1-m4`
+4. Enter description: `Critical crash on login screen`
+5. Click "Run workflow"
+
+**Step 3: Review Created Branch**
+
+Workflow creates:
+- Branch: `hotfix/0.0.2-m4-critical-crash-on-login`
+- PR to `main` branch
+- Updated `pubspec.yaml`: `0.0.2-m4+1`
+- Updated `CHANGELOG.md` with hotfix section
+
+**Step 4: Fix Bug**
+
+```bash
+git checkout hotfix/0.0.2-m4-critical-crash-on-login
+
+# Make fixes
+# ... code changes ...
+
+git add .
+git commit -m "fix(auth): resolve crash on login screen"
+git push origin hotfix/0.0.2-m4-critical-crash-on-login
+```
+
+**Step 5: Merge PR**
+
+1. Review PR on GitHub
+2. Approve and merge to `main`
+3. Delete hotfix branch
+
+**Step 6: Release to Production**
+
+1. Use Product Release workflow
+2. Select `main` branch
+3. Select `prod` environment
+4. Deploy hotfix
+
+## 7. Release Cadence
+
+### Development (dev)
+
+- **Frequency:** Multiple times per day
+- **Purpose:** Testing features in dev environment
+- **Branch:** `dev`
+- **Audience:** Internal development team
+- **Approval:** Not required
+
+### Staging (stage)
+
+- **Frequency:** 1-2 times per week
+- **Purpose:** QA testing, stakeholder demos
+- **Branch:** `main`
+- **Audience:** QA team, stakeholders
+- **Approval:** Tech lead approval
+
+### Production (prod)
+
+- **Frequency:** Every 2-3 weeks (milestone completion)
+- **Purpose:** End-user releases
+- **Branch:** `main`
+- **Audience:** All users
+- **Approval:** Product owner + tech lead approval
+
+### Milestone Releases
+
+- **Frequency:** Every 2-4 weeks
+- **Version Bump:** Minor version (e.g., `0.1.0-m5` → `0.2.0-m6`)
+- **Process:**
+  1. Complete all milestone features
+  2. Update CHANGELOG with comprehensive release notes
+  3. Deploy to stage for final QA
+  4. After approval, deploy to prod
+  5. Create GitHub release with milestone summary
+
+## 8. Troubleshooting
+
+### Workflow Fails: Version Extraction
+
+**Error:** "Could not extract version from pubspec.yaml"
+
+**Solutions:**
+1. Verify `pubspec.yaml` exists at expected path
+2. Check version format: `version: X.Y.Z-mN+B`
+3. Ensure no extra spaces or tabs
+4. Verify file is committed and pushed
+
+### Workflow Fails: APK Signing
+
+**Error:** "Keystore password incorrect"
+
+**Solutions:**
+1. Verify GitHub Secrets are set correctly
+2. Re-generate and re-encode keystore
+3. Check key.properties format
+4. Ensure passwords don't contain special characters that need escaping
+
+### Workflow Fails: CHANGELOG Extraction
+
+**Error:** "Could not find version in CHANGELOG"
+
+**Solutions:**
+1. Verify CHANGELOG format matches: `## [X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
+2. Check square brackets are present
+3. Ensure version matches pubspec.yaml
+4. Add version section if missing
+
+### Tag Already Exists
+
+**Error:** "tag already exists"
+
+**Solutions:**
+1. Delete existing tag locally and remotely:
+```bash
+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
+```
+2. Re-run workflow
+
+### Build Fails: Flutter Errors
+
+**Error:** "flutter build failed"
+
+**Solutions:**
+1. Test build locally first:
+```bash
+cd apps/mobile/apps/staff
+flutter build apk --release
+```
+2. Fix any analyzer errors
+3. Ensure all dependencies are compatible
+4. Clear build cache:
+```bash
+flutter clean
+flutter pub get
+```
+
+## 9. Local Testing
+
+Before triggering workflows, test builds locally:
+
+### Building APKs Locally
+
+**Staff App:**
+```bash
+cd apps/mobile/apps/staff
+flutter clean
+flutter pub get
+flutter build apk --release
+```
+
+**Client App:**
+```bash
+cd apps/mobile/apps/client
+flutter clean
+flutter pub get
+flutter build apk --release
+```
+
+### Testing Release Notes
+
+Extract CHANGELOG section:
+```bash
+.github/scripts/extract-release-notes.sh \
+  apps/mobile/apps/staff/CHANGELOG.md \
+  0.0.1-m4
+```
+
+### Verifying Version
+
+Extract version from pubspec:
+```bash
+.github/scripts/extract-version.sh \
+  apps/mobile/apps/staff/pubspec.yaml
+```
+
+## 10. Best Practices
+
+### CHANGELOG
+- ✅ Update continuously during development
+- ✅ Be specific and user-focused
+- ✅ Group related changes
+- ✅ Include UI/UX changes
+- ❌ Don't include technical debt or refactoring (unless user-facing)
+- ❌ Don't use vague descriptions
+
+### Versioning
+- ✅ Use semantic versioning strictly
+- ✅ Increment patch for bug fixes
+- ✅ Increment minor for new features
+- ✅ Keep milestone suffix until production
+- ❌ Don't skip versions
+- ❌ Don't use arbitrary version numbers
+
+### Git Tags
+- ✅ Follow standard format
+- ✅ Let workflow create tags automatically
+- ✅ Keep tags synced with releases
+- ❌ Don't create tags manually unless necessary
+- ❌ Don't reuse deleted tags
+
+### Workflows
+- ✅ Test builds locally first
+- ✅ Monitor workflow execution
+- ✅ Verify release assets
+- ✅ Test APK on device before announcing
+- ❌ Don't trigger multiple workflows simultaneously
+- ❌ Don't bypass approval process
+
+## Summary
+
+**Release Process Overview:**
+1. Update CHANGELOG with changes
+2. Update version in pubspec.yaml
+3. Commit and push to appropriate branch
+4. Trigger Product Release workflow
+5. Monitor execution and verify release
+6. Test APK on device
+7. Announce to team/users
+
+**Key Files:**
+- `apps/mobile/apps/staff/CHANGELOG.md`
+- `apps/mobile/apps/client/CHANGELOG.md`
+- `apps/mobile/apps/staff/pubspec.yaml`
+- `apps/mobile/apps/client/pubspec.yaml`
+
+**Key Workflows:**
+- Product Release (standard releases)
+- Product Hotfix (emergency fixes)
+
+**For Complete Details:**
+See [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) - 900+ line comprehensive guide with:
+- Detailed APK signing setup
+- Complete troubleshooting guide
+- All helper scripts documentation
+- Release checklist
+- Security best practices
+
+When in doubt, refer to the comprehensive documentation or ask for clarification before releasing to production.

.agents/skills/krow-paper-design/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: krow-paper-design
+description: KROW Paper design file conventions covering design tokens, component patterns, screen structure, and naming rules. Use this when creating or updating screens in the Paper design tool, auditing designs for token compliance, building new flows, or restructuring existing frames. Ensures visual consistency across all Paper design files for the KROW staff and client apps.
+---
+
+# KROW Paper Design Conventions
+
+This skill defines the design token system, component patterns, screen structure conventions, and workflow rules established for the KROW Design Revamp Paper file. All design work in Paper must follow these conventions.
+
+## When to Use This Skill
+
+- Creating new screens or flows in Paper
+- Updating existing frames to match the design system
+- Auditing designs for token compliance
+- Adding components (buttons, chips, inputs, badges, cards)
+- Structuring shift detail pages, onboarding flows, or list screens
+- Setting up navigation patterns (back buttons, bottom nav, CTAs)
+- Reviewing Paper designs before handoff to development
+
+## 1. Design Tokens
+
+### Color Palette
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Primary | `#0A39DF` | CTAs, active states, links, selected chips, nav active icons, pay rates |
+| Foreground | `#121826` | Headings, primary text, dark UI elements |
+| Text Secondary | `#6A7382` | Labels, captions, inactive nav, section headers, placeholder text, back chevrons |
+| Secondary BG | `#F1F3F5` | Subtle backgrounds, dividers, map placeholders |
+| Border | `#D1D5DB` | Card borders, unselected chip borders, outline button borders |
+| Input Border | `#E2E8F0` | Text input borders (lighter than general border) |
+| Destructive | `#F04444` | Error states, destructive actions (e.g., Request Swap) |
+| Background | `#FAFBFC` | Page/artboard background |
+| Card BG | `#FFFFFF` | Card surfaces, input backgrounds |
+| Success | `#059669` | Active status dot, checkmark icons, requirement met |
+| Warning Amber | `#D97706` | Urgent/Pending badge text |
+
+### Semantic Badge Colors
+
+| Badge | Background | Text Color |
+|-------|-----------|------------|
+| Active | `#ECFDF5` | `#059669` |
+| Confirmed | `#EBF0FF` | `#0A39DF` |
+| Pending | `#FEF9EE` | `#D97706` |
+| Urgent | `#FEF9EE` | `#D97706` |
+| One-Time | `#ECFDF5` | `#059669` |
+| Recurring | `#EBF0FF` | `#0A39DF` (use `#EFF6FF` bg on detail pages) |
+
+### Typography
+
+| Style | Font | Size | Weight | Line Height | Usage |
+|-------|------|------|--------|-------------|-------|
+| Display | Inter Tight | 28px | 700 | 34px | Page titles (Find Shifts, My Shifts) |
+| H1 | Inter Tight | 24px | 700 | 30px | Detail page titles (venue names) |
+| H2 | Inter Tight | 20px | 700 | 26px | Section headings |
+| H3 | Inter Tight | 18px | 700 | 22px | Card titles, schedule values |
+| Body Large | Manrope | 16px | 600 | 20px | Button text, CTA labels |
+| Body Default | Manrope | 14px | 400-500 | 18px | Body text, descriptions |
+| Body Small | Manrope | 13px | 400-500 | 16px | Card metadata, time/pay info |
+| Caption | Manrope | 12px | 500-600 | 16px | Small chip text, tab labels |
+| Section Label | Manrope | 11px | 700 | 14px | Uppercase section headers (letter-spacing: 0.06em) |
+| Badge Text | Manrope | 11px | 600-700 | 14px | Status badge labels (letter-spacing: 0.04em) |
+| Nav Label | Manrope | 10px | 600 | 12px | Bottom nav labels |
+
+### Spacing
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Page padding | 24px | Horizontal padding from screen edge |
+| Section gap | 16-24px | Between major content sections |
+| Group gap | 8-12px | Within a section (e.g., label to input) |
+| Element gap | 4px | Tight spacing (e.g., subtitle under title) |
+| Bottom safe area | 40px | Padding below last element / CTA |
+
+### Border Radii
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| sm | 8px | Small chips, badges, status pills, map placeholder |
+| md | 12px | Cards, inputs, location cards, contact cards, search fields |
+| lg | 14px | Buttons, CTA containers, shift cards (Find Shifts) |
+| xl | 24px | Not commonly used |
+| pill | 999px | Progress bar segments only |
+
+## 2. Component Patterns
+
+### Buttons
+
+**Primary CTA:**
+- Background: `#0A39DF`, radius: 14px, height: 52px
+- Text: Manrope 16px/600, color: `#FFFFFF`
+- Padding: 16px vertical, 16px horizontal
+
+**Secondary/Outline Button:**
+- Background: `#FFFFFF`, border: 1.5px `#D1D5DB`, radius: 14px, height: 52px
+- Text: Manrope 16px/600, color: `#121826`
+
+**Destructive Outline Button:**
+- Background: `#FFFFFF`, border: 1.5px `#F04444`, radius: 14px
+- Text: Manrope 14px/600, color: `#F04444`
+
+**Back Icon Button (Bottom CTA):**
+- 52x52px square, border: 1.5px `#D1D5DB`, radius: 14px, background: `#FFFFFF`
+- Contains chevron-left SVG (20x20, viewBox 0 0 24 24, stroke `#121826`, strokeWidth 2)
+- Path: `M15 18L9 12L15 6`
+
+### Chips
+
+**Default (Large) - for role/skill selection:**
+- Selected: bg `#EFF6FF`, border 1.5px `#0A39DF`, radius 10px, padding 12px/16px
+  - Checkmark icon (14x14, stroke `#0A39DF`), text Manrope 14px/600 `#0A39DF`
+- Unselected: bg `#FFFFFF`, border 1.5px `#6A7382`, radius 10px, padding 12px/16px
+  - Text Manrope 14px/500 `#6A7382`
+
+**Small - for tabs, filters:**
+- Selected: bg `#EFF6FF`, border 1.5px `#0A39DF`, radius 8px, padding 6px/12px
+  - Checkmark icon (12x12), text Manrope 12px/600 `#0A39DF`
+- Unselected: bg `#FFFFFF`, border 1.5px `#D1D5DB`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/500 `#6A7382`
+- Active (filled): bg `#0A39DF`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/600 `#FFFFFF`
+- Dark (filters button): bg `#121826`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/600 `#FFFFFF`, with leading icon
+
+**Status Badges:**
+- Radius: 8px, padding: 4px/8px
+- Text: Manrope 11px/600-700, uppercase, letter-spacing 0.04em
+- Colors follow semantic badge table above
+
+### Text Inputs
+
+- Border: 1.5px `#E2E8F0`, radius: 12px, padding: 12px/14px
+- Background: `#FFFFFF`
+- Placeholder: Manrope 14px/400, color `#6A7382`
+- Filled: Manrope 14px/500, color `#121826`
+- Label above: Manrope 14px/500, color `#121826`
+- Focused: border color `#0A39DF`, border-width 2px
+- Error: border color `#F04444`, helper text `#F04444`
+
+### Cards (Shift List Items)
+
+- Background: `#FFFFFF`, border: 1px `#D1D5DB`, radius: 12-14px
+- Padding: 16px
+- Content: venue name (Manrope 15px/600 `#121826`), subtitle (Manrope 13px/400 `#6A7382`)
+- Metadata row: icon (14px, `#6A7382`) + text (Manrope 13px/500 `#6A7382`)
+- Pay rate: Inter Tight 18px/700 `#0A39DF`
+
+### Schedule/Pay Info Cards
+
+- Two-column layout with 12px gap
+- Background: `#FFFFFF`, border: 1px `#D1D5DB`, radius: 12px, padding: 16px
+- Label: Manrope 11px/500-700 uppercase `#6A7382` (letter-spacing 0.05em)
+- Value: Inter Tight 18px/700 `#121826` (schedule) or `#121826` (pay)
+- Sub-text: Manrope 13px/400 `#6A7382`
+
+### Contact/Info Rows
+
+- Container: radius 12px, border 1px `#D1D5DB`, background `#FFFFFF`, overflow clip
+- Row: padding 13px/16px, gap 10px, border-bottom 1px `#F1F3F5` (except last)
+- Icon: 16px, stroke `#6A7382`
+- Label: Manrope 13px/500 `#6A7382`, width 72px fixed
+- Value: Manrope 13px/500 `#121826` (or `#0A39DF` for phone/links)
+
+### Section Headers
+
+- Text: Manrope 11px/700, uppercase, letter-spacing 0.06em, color `#6A7382`
+- Gap to content below: 10px
+
+## 3. Screen Structure
+
+### Artboard Setup
+
+- Width: 390px (iPhone standard)
+- Height: 844px (default), or `fit-content` for scrollable detail pages
+- Background: `#FAFBFC`
+- Flex column layout, overflow: clip
+
+### Frame Naming Convention
+
+```
+<app>-<section>-<screen_number>-<screen_name>
+```
+
+Examples:
+- `staff-1-1-splash`
+- `staff-2-3-personal-information`
+- `staff-4-1-my-shifts`
+- `staff-5-2-shift-details`
+- `shift-5-3-confirmation`
+
+Section headers use: `<number> - <Section Name>` (e.g., `4 - My Shifts`)
+
+### Status Bar
+
+- Height: 44px, full width (390px)
+- Left: "9:41" text (system font)
+- Right: Signal, WiFi, Battery SVG icons (68px wide)
+
+### Header Back Button
+
+- Placed below status bar in a combined "Status Bar + Back" frame (390x72px)
+- Chevron SVG: 20x20, viewBox 0 0 24 24, stroke `#6A7382`, strokeWidth 2
+- Path: `M15 18L9 12L15 6`
+- Back button frame: 390x28px, padding-left: 24px
+
+### Progress Bar (Onboarding)
+
+- Container: 342px wide (24px margins), 3px height segments
+- Segments: pill radius (999px), gap between
+- Filled: `#0A39DF`, Unfilled: `#F1F3F5`
+
+### Bottom CTA Convention
+
+- Pinned to bottom using `marginTop: auto` on the CTA container
+- Layout: flex row, gap 12px, padding 0 24px
+- Back button: 52x52px icon-only button with chevron-left (stroke `#121826`)
+- Primary CTA: flex 1, height 52px, radius 14px, bg `#0A39DF`
+- Bottom safe padding: 40px (on artboard paddingBottom)
+
+### Bottom Navigation Bar
+
+- Full width, padding: 10px top, 28px bottom
+- Border-top: 1px `#F1F3F5`, background: `#FFFFFF`
+- 5 items: Home, Shifts, Find, Payments, Profile
+- Active: icon stroke `#0A39DF`, label Manrope 10px/600 `#0A39DF`
+- Inactive: icon stroke `#6A7382`, label Manrope 10px/600 `#6A7382`
+- Active icon may have light fill (e.g., `#EBF0FF` on calendar/search)
+
+## 4. Screen Templates
+
+### List Screen (My Shifts, Find Shifts)
+
+```
+Artboard (390x844, bg #FAFBFC)
+  Status Bar (390x44)
+  Header Section
+    Page Title (Display: Inter Tight 28px/700)
+    Tab/Filter Chips (Small chip variant)
+  Content
+    Date Header (Section label style, uppercase)
+    Shift Cards (12px radius, 1px border #D1D5DB)
+  Bottom Nav Bar
+```
+
+### Detail Screen (Shift Details)
+
+```
+Artboard (390x fit-content, bg #FAFBFC)
+  Status Bar (390x44)
+  Header Bar (Back chevron + "Shift Details" title + share icon)
+  Badges Row (status chips)
+  Role Title (H1) + Venue (with avatar)
+  Schedule/Pay Cards (two-column)
+  Job Description (section label + body text)
+  Location (card with map + address)
+  Requirements (section label + checkmark list)
+  Shift Contact (section label + contact card with rows)
+  [Optional] Note from Manager (warm bg card)
+  Bottom CTA (pinned)
+```
+
+### Onboarding Screen
+
+```
+Artboard (390x844, bg #FAFBFC, justify: flex-start, paddingBottom: 40px)
+  Status Bar + Back (390x72)
+  Progress Bar (342px, 3px segments)
+  Step Counter ("Step X of Y" - Body Small)
+  Page Title (H1: Inter Tight 24px/700)
+  [Optional] Subtitle (Body Default)
+  Form Content (inputs, chips, sliders)
+  Bottom CTA (marginTop: auto - back icon + Continue)
+```
+
+### Confirmation Screen
+
+```
+Artboard (390x844, bg #FAFBFC)
+  Status Bar
+  Centered Content
+    Success Icon (green circle + checkmark)
+    Title (Display: Inter Tight 26px/700, centered)
+    Subtitle (Body Default, centered, #6A7382)
+    Details Card (border #D1D5DB, rows with label/value pairs)
+  Bottom CTAs (primary + outline)
+```
+
+## 5. Workflow Rules
+
+### Write Incrementally
+
+Each `write_html` call should produce ONE visual group:
+- A header, a card, a single list row, a button bar, a section
+- Never batch an entire screen in one call
+
+### Review Checkpoints
+
+After every 2-3 modifications, take a screenshot and evaluate:
+- **Spacing**: Uneven gaps, cramped groups
+- **Typography**: Hierarchy, readability, correct font/weight
+- **Contrast**: Text legibility, element distinction
+- **Alignment**: Vertical lanes, horizontal alignment
+- **Clipping**: Content cut off at edges
+- **Token compliance**: All values match design system tokens
+
+### Color Audit Process
+
+When updating frames to match the design system:
+1. Get computed styles for all text, background, border elements
+2. Map old colors to design system tokens:
+   - Dark navy (`#0F4C81`, `#1A3A5C`) -> Primary `#0A39DF`
+   - Near-black (`#111827`, `#0F172A`) -> Foreground `#121826`
+   - Gray variants (`#94A3B8`, `#64748B`, `#475569`) -> Text Secondary `#6A7382`
+   - Green accents (`#20B486`) -> Primary `#0A39DF` (for pay) or `#059669` (for status)
+3. Batch update using `update_styles` with multiple nodeIds per style change
+4. Verify with screenshots
+
+### Structural Consistency
+
+When creating matching screens (e.g., two shift detail views):
+- Use identical section ordering
+- Match section header styles (11px/700 uppercase `#6A7382`)
+- Use same card/row component patterns
+- Maintain consistent padding and gap values
+
+## 6. SVG Icon Patterns
+
+### Chevron Left (Back)
+```html
+<svg width="20" height="20" viewBox="0 0 24 24" fill="none">
+  <path d="M15 18L9 12L15 6" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Map Pin
+```html
+<svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+  <path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0 1 18 0z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="10" r="3" stroke="#6A7382" stroke-width="2"/>
+</svg>
+```
+
+### User (Supervisor)
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="7" r="4" stroke="#6A7382" stroke-width="2"/>
+</svg>
+```
+
+### Phone
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.127.96.361 1.903.7 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.907.339 1.85.573 2.81.7A2 2 0 0 1 22 16.92z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Checkmark (Requirement Met)
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M22 4L12 14.01l-3-3" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Chip Checkmark
+```html
+<!-- Large chip (14x14) -->
+<svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+
+<!-- Small chip (12x12) -->
+<svg width="12" height="12" viewBox="0 0 14 14" fill="none">
+  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+## 7. Anti-Patterns
+
+### Colors
+- Never use `#0F4C81`, `#1A3A5C` (old navy) - use `#0A39DF` (Primary)
+- Never use `#111827`, `#0F172A` - use `#121826` (Foreground)
+- Never use `#94A3B8`, `#64748B`, `#475569` - use `#6A7382` (Text Secondary)
+- Never use `#20B486` for pay rates - use `#0A39DF` (Primary)
+- Never use `#E2E8F0` for card borders - use `#D1D5DB` (Border)
+
+### Components
+- Never use pill radius (999px) for chips or badges - use 8px or 10px
+- Never use gradient backgrounds on buttons
+- Never mix font families within a role (headings = Inter Tight, body = Manrope)
+- Never place back buttons at the bottom of frames - always after status bar
+- Never hardcode CTA position - use `marginTop: auto` for bottom pinning
+
+### Structure
+- Never batch an entire screen in one `write_html` call
+- Never skip review checkpoints after 2-3 modifications
+- Never create frames without following the naming convention
+- Never use `justifyContent: space-between` on artboards with many direct children - use `marginTop: auto` on the CTA instead
+
+## Summary
+
+**The design file is the source of truth for visual direction.** Every element must use the established tokens:
+
+1. **Colors**: 7 core tokens + semantic badge colors
+2. **Typography**: Inter Tight (headings) + Manrope (body), defined scale
+3. **Spacing**: 24px page padding, 16-24px section gaps, 40px bottom safe area
+4. **Radii**: 8px (chips/badges), 12px (cards/inputs), 14px (buttons/CTAs)
+5. **Components**: Buttons, chips (large/small), inputs, cards, badges, nav bars
+6. **Structure**: Status bar > Back > Content > Bottom CTA (pinned)
+7. **Naming**: `<app>-<section>-<number>-<name>`
+
+When in doubt, screenshot an existing screen and match its patterns exactly.

.claude/agent-memory/architecture-reviewer/MEMORY.md

@@ -0,0 +1,77 @@
+# Architecture Reviewer Memory
+
+## Project Structure Confirmed
+- Feature packages: `apps/mobile/packages/features/<app>/<feature>/`
+- Domain: `apps/mobile/packages/domain/`
+- Design system: `apps/mobile/packages/design_system/`
+- Core: `apps/mobile/packages/core/`
+- Data Connect: `apps/mobile/packages/data_connect/`
+- `client_orders_common` is at `apps/mobile/packages/features/client/orders/orders_common/` (shared across order features)
+
+## BLoC Registration Pattern
+- BLoCs registered with `i.add<>()` (transient) per CLAUDE.md -- NOT singletons
+- This means `BlocProvider(create:)` is CORRECT (not `BlocProvider.value()`)
+- `SafeBloc` mixin exists in core alongside `BlocErrorHandler`
+
+## Known Pre-existing Issues (create_order feature)
+- All 3 order BLoCs make direct `_service.connector` calls for loading vendors, hubs, roles, and managers instead of going through use cases/repositories (CRITICAL per rules, but pre-existing)
+- `firebase_data_connect` and `firebase_auth` are listed as direct dependencies in `client_create_order/pubspec.yaml` (should only be in `data_connect` package)
+- All 3 order pages use `Modular.to.pop()` instead of `Modular.to.popSafe()` for the back button
+
+## Known Staff App Issues (full scan 2026-03-19)
+- [recurring_violations.md](recurring_violations.md) - Detailed violation patterns
+
+### Critical
+- ProfileCubit calls repository directly (no use cases, no interface)
+- BenefitsOverviewCubit calls repository.getDashboard() directly (bypasses use case)
+- StaffMainCubit missing BlocErrorHandler mixin
+- firebase_auth imported directly in auth feature repos (2 files)
+
+### High (Widespread)
+- 53 instances of `context.read<>()` without `ReadContext()` wrapper
+- ~20 hardcoded Color(0x...) values in home/benefits widgets
+- 5 custom TextStyle() in faqs_widget and tax_forms
+- 8 copyWith(fontSize:) overrides on UiTypography
+- ~40 hardcoded SizedBox spacing values
+- Hardcoded nav labels in staff_nav_items_config.dart
+- Zero test files across entire staff feature tree
+
+## Design System Tokens
+- Colors: `UiColors.*`
+- Typography: `UiTypography.*`
+- Spacing: `UiConstants.space*` (e.g., `space3`, `space4`, `space6`)
+- App bar: `UiAppBar`
+
+## Known Client App Issues (full scan 2026-03-19)
+
+### Critical
+- Reports feature: All 7 report BLoCs call ReportsRepository directly (no use cases)
+- OneTimeOrderBloc, PermanentOrderBloc, RecurringOrderBloc call _queryRepository directly for loading vendors/hubs/roles
+- OneTimeOrderBloc._onSubmitted has payload building business logic (should be in use case)
+- ClientMainCubit missing BlocErrorHandler mixin
+- firebase_auth imported directly in authentication and settings feature repos (2 packages)
+
+### High (Widespread)
+- 17 hardcoded Color(0x...) across reports, coverage, billing, hubs
+- 11 Material Colors.* usage (coverage, billing, reports)
+- 66 standalone TextStyle() (almost all in reports feature)
+- ~145 hardcoded EdgeInsets spacing values
+- ~97 hardcoded SizedBox dimensions
+- ~42 hardcoded BorderRadius.circular values
+- 6 unsafe Modular.to.pop() calls (settings, hubs)
+- BlocProvider(create:) used in no_show_report_page for Modular.get singleton
+- Zero test files across entire client feature tree
+- 2 hardcoded user-facing strings ("Export coming soon")
+- 9 files with blanket ignore_for_file directives (reports feature)
+
+### Naming Convention Violations
+- CoverageRepository, BillingRepository, ReportsRepository missing "Interface" suffix
+- IViewOrdersRepository uses "I" prefix instead of "Interface" suffix
+
+## Review Patterns (grep-based checks)
+- `Color(0x` for hardcoded colors
+- `TextStyle(` for custom text styles
+- `Navigator.` for direct navigator usage
+- `import.*features/` for cross-feature imports (must be zero)
+- `_service.connector` in BLoC files for direct data connect calls
+- `Modular.to.pop()` for unsafe navigation (should be `popSafe()`)

.claude/agent-memory/mobile-architecture-reviewer/MEMORY.md

@@ -0,0 +1,22 @@
+# Mobile Architecture Reviewer Memory
+
+## Project Structure
+- Features: `apps/mobile/packages/features/{client,staff}/<feature>/`
+- Design System: `apps/mobile/packages/design_system/`
+- Shimmer primitives: `design_system/lib/src/widgets/shimmer/` (UiShimmer, UiShimmerBox, UiShimmerCircle, UiShimmerLine, presets)
+- UiConstants spacing: space0=0, space1=4, space2=8, space3=12, space4=16, space5=20, space6=24, space8=32, space10=40, space12=48
+
+## Design System Conventions
+- `UiConstants.radiusLg`, `radiusMd`, `radiusSm`, `radiusFull` are `static final` (not const) - cannot use `const` at call sites
+- Shimmer placeholder dimensions (width/height of boxes/lines/circles) are visual content sizes, not spacing - the design system presets use UiConstants for these too
+- `Divider(height: 1, thickness: 0.5)` is a common pattern in the codebase for thin dividers
+
+## Common Pre-Existing Issues (Do Not Flag as New)
+- Report detail pages use hardcoded `top: 60` for AppBar clearance (all 6 report pages)
+- Payments page and billing page have hardcoded strings (pre-existing, not part of shimmer changes)
+- `shift_details_page.dart` has hardcoded strings and Navigator.of usage (pre-existing)
+
+## Review Patterns
+- Skeleton files are pure presentation widgets (StatelessWidget) - no BLoC, no business logic, no navigation
+- Skeleton files only import `design_system` and `flutter/material.dart` - clean dependency
+- Barrel file `index.dart` in `reports_page/` widgets dir is an internal barrel, not public API

.claude/agent-memory/mobile-builder/MEMORY.md

@@ -0,0 +1,226 @@
+# Mobile Builder Agent Memory
+
+## Design System - Shimmer Primitives
+- Shimmer widgets are in `packages/design_system/lib/src/widgets/shimmer/`
+- Available: `UiShimmer`, `UiShimmerBox`, `UiShimmerCircle`, `UiShimmerLine`, `UiShimmerListItem`, `UiShimmerStatsCard`, `UiShimmerSectionHeader`, `UiShimmerList`
+- `UiShimmerList.itemBuilder` takes `(int index)` -- single parameter, not `(BuildContext, int)`
+- `UiShimmerBox.borderRadius` accepts `BorderRadius?` (nullable), uses `UiConstants.radiusMd` as default
+- All shimmer shapes render as solid white containers; the parent `UiShimmer` applies the animated gradient
+- Exported via `design_system.dart` barrel
+
+## Staff App Feature Locations
+- Shifts: `packages/features/staff/shifts/` -- has ShiftsPage (tabbed: MyShifts/Find/History) + ShiftDetailsPage
+- Home: `packages/features/staff/home/` -- WorkerHomePage with sections (TodaysShifts, TomorrowsShifts, Recommended, Benefits, QuickActions)
+- Payments: `packages/features/staff/payments/` -- PaymentsPage with gradient header + stats + payment history
+- Home cubit: `HomeStatus` enum (initial, loading, loaded, error)
+- Shifts bloc: `ShiftsStatus` enum + sub-loading flags (`availableLoading`, `historyLoading`)
+- Payments bloc: uses sealed state classes (`PaymentsLoading`, `PaymentsLoaded`, `PaymentsError`)
+
+## UiConstants Spacing Tokens
+- Use `UiConstants.space1` through `UiConstants.space24` for spacing
+- Radius: `UiConstants.radiusSm`, `radiusMd`, `radiusLg`, `radiusFull`, `radiusBase`, `radiusMdValue` (double)
+- `UiConstants.radiusFull` is a `BorderRadius`, `UiConstants.radiusMdValue` is a `double`
+
+## Barrel Files (Staff Features)
+- Shifts: `lib/staff_shifts.dart` exports modules only
+- Payments: `lib/staff_payements.dart` (note: typo in filename) exports module only
+- Home: `lib/staff_home.dart` exports module only
+- These barrel files only export modules, not individual widgets -- skeleton widgets don't need to be added
+
+## Client App Feature Locations
+- Coverage: `packages/features/client/client_coverage/`
+- Home: `packages/features/client/home/` (no loading spinner -- renders default data during load)
+- Billing: `packages/features/client/billing/` (billing_page, pending_invoices_page, invoice_ready_page)
+- Reports: `packages/features/client/reports/` (reports_page with metrics_grid, plus 6 sub-report pages)
+- Reports barrel: `widgets/reports_page/index.dart`
+- Hubs: `packages/features/client/hubs/` (client_hubs_page + hub_details_page + edit_hub_page)
+
+## Staff Profile Sections (shimmer done)
+- Compliance: certificates, documents, tax_forms -- all have shimmer skeletons
+- Finances: staff_bank_account, time_card -- all have shimmer skeletons
+- Onboarding: attire, profile_info (personal_info_page only) -- have shimmer skeletons
+- Support: faqs, privacy_security (including legal sub-pages) -- have shimmer skeletons
+- Pages that intentionally keep CircularProgressIndicator (action/submit spinners):
+  - form_i9_page, form_w4_page (submit button spinners)
+  - experience_page (save button spinner)
+  - preferred_locations_page (save button + overlay spinner)
+  - certificate_upload_page, document_upload_page, attire_capture_page (form/upload pages, no initial load)
+  - language_selection_page (no loading state, static list)
+- LegalDocumentSkeleton is shared between PrivacyPolicyPage and TermsOfServicePage
+
+## Key Patterns Observed
+- BenefitsOverviewPage also has CircularProgressIndicator (not shimmer-ified yet)
+- ShiftDetailsPage has a dialog-level spinner in the "applying" dialog -- this is intentional, not a page loading state
+- Hub details/edit pages use CircularProgressIndicator as action overlays (save/delete) -- keep as-is, not initial load
+- Client home page uses shimmer skeleton during loading (ClientHomePageSkeleton + ClientHomeHeaderSkeleton)
+
+## V2 API Migration Patterns
+- `BaseApiService` is registered in `CoreModule` as a lazy singleton (injected as `i.get<BaseApiService>()`)
+- `BaseApiService` type lives in `krow_domain`; `ApiService` impl lives in `krow_core`
+- V2 endpoints: `V2ApiEndpoints.staffDashboard` etc. from `krow_core/core.dart`
+- V2 domain shift entities: `TodayShift`, `AssignedShift`, `OpenShift` (separate from core `Shift`)
+- V2 `Benefit`: uses `targetHours`/`trackedHours`/`remainingHours` (int) -- old used `entitlementHours`/`usedHours` (double)
+- Staff dashboard endpoint returns all home data in one call (todaysShifts, tomorrowsShifts, recommendedShifts, benefits, staffName)
+- Navigator has `toShiftDetailsById(String shiftId)` for cases where only the ID is available
+- `StaffDashboard` entity updated to use typed lists: `List<TodayShift>`, `List<AssignedShift>`, `List<OpenShift>`
+- Staff home feature migrated (Phase 2): removed krow_data_connect, firebase_data_connect, staff_shifts deps
+- [V2 Profile Migration](project_v2_profile_migration.md) -- entity mappings and DI patterns for all profile sub-packages
+- Staff clock-in migrated (Phase 3): repo impl → V2 API, removed Data Connect deps
+  - V2 `Shift` entity: `startsAt`/`endsAt` (DateTime), `locationName` (String?), no `startTime`/`endTime`/`clientName`/`hourlyRate`/`location`
+  - V2 `AttendanceStatus`: `isClockedIn` getter (not `isCheckedIn`), `clockInAt` (not `checkInTime`), no `checkOutTime`/`activeApplicationId`
+  - `AttendanceStatus` constructor requires `attendanceStatus: AttendanceStatusType.notClockedIn` for default
+  - Clock-out uses `shiftId` (not `applicationId`) -- V2 API resolves assignment from shiftId
+  - `listTodayShifts` endpoint returns `{ items: [...] }` with TodayShift-like shape (no lat/lng, hourlyRate, clientName)
+  - `getCurrentAttendanceStatus` returns flat object `{ activeShiftId, attendanceStatus, clockInAt }`
+  - Clock-in/out POST endpoints return `{ attendanceEventId, assignmentId, sessionId, status, validationStatus }` -- repo re-fetches status after
+  - Geofence: lat/lng not available from listTodayShifts or shiftDetail endpoints (lives on clock_points table, not returned by BE)
+  - `BaseApiService` not exported from `krow_core/core.dart` -- must import from `krow_domain/krow_domain.dart`
+
+## Staff Shifts Feature Migration (Phase 3 -- completed)
+- Migrated from `krow_data_connect` + `DataConnectService` to `BaseApiService` + `V2ApiEndpoints`
+- Removed deps: `krow_data_connect`, `firebase_auth`, `firebase_data_connect`, `geolocator`, `google_maps_flutter`, `meta`
+- State uses 5 typed lists: `List<AssignedShift>`, `List<OpenShift>`, `List<PendingAssignment>`, `List<CancelledShift>`, `List<CompletedShift>`
+- ShiftDetail (not Shift) used for detail page -- loaded by BLoC via API, not passed as route argument
+- Money: `hourlyRateCents` (int) / 100 for display -- all V2 shift entities use cents
+- Dates: All V2 entities have `DateTime` fields (not `String`) -- no more `DateTime.parse()` in widgets
+- AssignmentStatus enum drives bottom bar logic (accepted=clock-in, assigned=accept/decline, null=apply)
+- Old `Shift` entity still exists in domain but only used by clock-in feature -- shift list/detail pages use V2 entities
+- ShiftDetailsModule route no longer receives `Shift` data argument -- uses `shiftId` param only
+- `toShiftDetailsById(String)` is the standard navigation for V2 (no entity passing)
+- Profile completion: moved into feature repo impl via `V2ApiEndpoints.staffProfileCompletion` + `ProfileCompletion.fromJson`
+- Find Shifts tab: removed geolocator distance filter and multi-day grouping (V2 API handles server-side)
+- Renamed use cases: `GetMyShiftsUseCase` → `GetAssignedShiftsUseCase`, `GetAvailableShiftsUseCase` → `GetOpenShiftsUseCase`, `GetHistoryShiftsUseCase` → `GetCompletedShiftsUseCase`, `GetShiftDetailsUseCase` → `GetShiftDetailUseCase`
+
+## Client Home Feature Migration (Phase 4 -- completed)
+- Migrated from `krow_data_connect` + `DataConnectService` to `BaseApiService` + `V2ApiEndpoints`
+- Removed deps: `krow_data_connect`, `firebase_data_connect`, `intl`
+- V2 entities: `ClientDashboard` (replaces `HomeDashboardData`), `RecentOrder` (replaces `ReorderItem`)
+- `ClientDashboard` contains nested `SpendingSummary`, `CoverageMetrics`, `LiveActivityMetrics`
+- Money: `weeklySpendCents`, `projectedNext7DaysCents`, `averageShiftCostCents` (int) / 100 for display
+- Two API calls: `GET /client/dashboard` (all metrics + user/biz info) and `GET /client/reorders` (returns `{ items: [...] }`)
+- Removed `GetUserSessionDataUseCase` -- user/business info now part of `ClientDashboard`
+- `LiveActivityWidget` rewritten from StatefulWidget with direct DC calls to StatelessWidget consuming BLoC state
+- Dead code removed: `ShiftOrderFormSheet`, `ClientHomeSheets`, `CoverageDashboard` (all unused)
+- `RecentOrder` entity: `id`, `title`, `date` (DateTime?), `hubName` (String?), `positionCount` (int), `orderType` (OrderType)
+- Module imports `CoreModule()` (not `DataConnectModule()`), injects `BaseApiService` into repo
+- State has `dashboard` (ClientDashboard?) with computed getters `businessName`, `userName`
+- No photoUrl in V2 dashboard response -- header shows letter avatar only
+
+## Client Billing Feature Migration (Phase 4 -- completed)
+- Migrated from `krow_data_connect` + `BillingConnectorRepository` to `BaseApiService` + `V2ApiEndpoints`
+- Removed deps: `krow_data_connect`, `firebase_data_connect`
+- Deleted old presentation models: `BillingInvoice`, `BillingWorkerRecord`, `SpendingBreakdownItem`
+- V2 domain entities used directly: `Invoice`, `BillingAccount`, `SpendItem`, `CurrentBill`, `Savings`
+- Old domain types removed: `BusinessBankAccount`, `InvoiceItem`, `InvoiceWorker`, `BillingPeriod` enum
+- Money: all amounts in cents (int). State has computed `currentBillDollars`, `savingsDollars`, `spendTotalCents` getters
+- `Invoice` V2 entity: `invoiceId`, `invoiceNumber`, `amountCents` (int), `status` (InvoiceStatus enum), `dueDate`, `paymentDate`, `vendorId`, `vendorName`
+- `BillingAccount` V2 entity: `accountId`, `bankName`, `providerReference`, `last4`, `isPrimary`, `accountType` (AccountType enum)
+- `SpendItem` V2 entity: `category`, `amountCents` (int), `percentage` (double) -- server-side aggregation by role
+- Spend breakdown: replaced `BillingPeriod` enum with `BillingPeriodTab` (local) + `SpendBreakdownParams` (startDate/endDate ISO strings)
+- API response shapes: list endpoints return `{ items: [...] }`, scalar endpoints spread data (`{ currentBillCents, requestId }`)
+- Approve/dispute: POST to `V2ApiEndpoints.clientInvoiceApprove(id)` / `clientInvoiceDispute(id)`
+- Completion review page: `BillingInvoice` replaced with `Invoice` -- worker-level data not available in V2 (widget placeholder)
+- `InvoiceStatus` enum has `.value` property for display and `fromJson` factory with safe fallback to `unknown`
+
+## Client Reports Feature Migration (Phase 4 -- completed)
+- Migrated from `krow_data_connect` + `ReportsConnectorRepository` to `BaseApiService` + `V2ApiEndpoints`
+- Removed deps: `krow_data_connect`
+- 7 report endpoints: summary, daily-ops, spend, coverage, forecast, performance, no-show
+- Old `ReportsSummary` entity replaced with V2 `ReportSummary` (different fields: totalShifts, totalSpendCents, averageCoveragePercentage, averagePerformanceScore, noShowCount, forecastAccuracyPercentage)
+- `businessId` removed from all events/repo -- V2 API resolves from auth token
+- DailyOps: old `DailyOpsShift` replaced with `ShiftWithWorkers` (from coverage_domain). `TimeRange` has `startsAt`/`endsAt` (not `start`/`end`)
+- Spend: `SpendReport` uses `totalSpendCents` (int), `chart` (List<SpendDataPoint> with `bucket`/`amountCents`), `breakdown` (List<SpendItem> with `category`/`amountCents`/`percentage`)
+- Coverage: `CoverageReport` uses `averageCoveragePercentage`, `filledWorkers`, `neededWorkers`, `chart` (List<CoverageDayPoint> with `day`/`needed`/`filled`/`coveragePercentage`)
+- Forecast: `ForecastReport` uses `forecastSpendCents`, `averageWeeklySpendCents`, `totalWorkerHours`, `weeks` (List<ForecastWeek> with `week`/`shiftCount`/`workerHours`/`forecastSpendCents`/`averageShiftCostCents`)
+- Performance: V2 uses int percentages (`fillRatePercentage`, `completionRatePercentage`, `onTimeRatePercentage`) and `averageFillTimeMinutes` (double) -- convert to hours: `/60`
+- NoShow: `NoShowReport` uses `totalNoShowCount`, `noShowRatePercentage`, `workersWhoNoShowed`, `items` (List<NoShowWorkerItem> with `staffId`/`staffName`/`incidentCount`/`riskStatus`/`incidents`)
+- Module injects `BaseApiService` via `i.get<BaseApiService>()` -- no more `DataConnectModule` import
+
+## Client Hubs Feature Migration (Phase 5 -- completed)
+- Migrated from `krow_data_connect` + `HubsConnectorRepository` + `DataConnectService` to `BaseApiService` + `V2ApiEndpoints`
+- Removed deps: `krow_data_connect`, `firebase_auth`, `firebase_data_connect`, `http`
+- V2 `Hub` entity: `hubId` (not `id`), `fullAddress` (not `address`), `costCenterId`/`costCenterName` (flat, not nested `CostCenter` object)
+- V2 `CostCenter` entity: `costCenterId` (not `id`), `name` only (no `code` field)
+- V2 `HubManager` entity: `managerAssignmentId`, `businessMembershipId`, `managerId`, `name`
+- API response shapes: `GET /client/hubs` returns `{ items: [...] }`, `GET /client/cost-centers` returns `{ items: [...] }`
+- Create/update return `{ hubId, created: true }` / `{ hubId, updated: true }` -- repo returns hubId String
+- Delete: soft-delete (sets status=INACTIVE). Backend rejects if hub has active orders (409 HUB_DELETE_BLOCKED)
+- Assign NFC: `POST /client/hubs/:hubId/assign-nfc` with `{ nfcTagId }`
+- Module no longer imports `DataConnectModule()` -- `BaseApiService` available from parent `CoreModule()`
+- `UpdateHubArguments.id` renamed to `UpdateHubArguments.hubId`; `CreateHubArguments.address` renamed to `.fullAddress`
+- `HubDetailsDeleteRequested.id` renamed to `.hubId`; `EditHubAddRequested.address` renamed to `.fullAddress`
+- Navigator still passes full `Hub` entity via route args (not just hubId)
+
+## Client Orders Feature Migration (Phase 5 -- completed)
+- 3 sub-packages migrated: `orders_common`, `view_orders`, `create_order`
+- Removed deps: `krow_data_connect`, `firebase_data_connect`, `firebase_auth` from all; kept `intl` in create_order and orders_common
+- V2 `OrderItem` entity: `itemId`, `orderId`, `orderType` (OrderType enum), `roleName`, `date` (DateTime), `startsAt`/`endsAt` (DateTime), `requiredWorkerCount`, `filledCount`, `hourlyRateCents`, `totalCostCents` (int cents), `locationName` (String?), `status` (ShiftStatus enum), `workers` (List<AssignedWorkerSummary>)
+- Old entities deleted: `OneTimeOrder`, `RecurringOrder`, `PermanentOrder`, `ReorderData`, `OneTimeOrderHubDetails`, `RecurringOrderHubDetails`
+- `AssignedWorkerSummary`: `applicationId` (String?), `workerName` (String? -- nullable!), `role` (String?), `confirmationStatus` (ApplicationStatus?)
+- V2 `Vendor` entity: field is `companyName` (not `name`) -- old code used `vendor.name`
+- V2 `ShiftStatus` enum: only has `draft`, `open`, `pendingConfirmation`, `assigned`, `active`, `completed`, `cancelled`, `unknown` -- no `filled`/`confirmed`/`pending`
+- `OrderType` enum has `unknown` variant -- must handle in switch statements
+- View orders: removed `GetAcceptedApplicationsForDayUseCase` -- V2 returns workers inline with order items
+- View orders cubit: date filtering now uses `_isSameDay(DateTime, DateTime)` instead of string comparison
+- Create order BLoCs: build `Map<String, dynamic>` V2 payloads instead of old entity objects
+- V2 create endpoints: `POST /client/orders/one-time` (requires `orderDate`), `/recurring` (requires `startDate`/`endDate`/`recurrenceDays`), `/permanent` (requires `startDate`/`daysOfWeek`)
+- V2 edit endpoint: `POST /client/orders/:orderId/edit` -- creates edited copy, cancels original
+- V2 cancel endpoint: `POST /client/orders/:orderId/cancel` with optional `reason`
+- Reorder uses `OrderPreview` (from `V2ApiEndpoints.clientOrderReorderPreview`) instead of old `ReorderData`
+- `OrderPreview` has nested `OrderPreviewShift` > `OrderPreviewRole` structure
+- Query repo: `getHubs()` replaces `getHubsByOwner(businessId)` -- V2 resolves business from auth token
+- `OneTimeOrderPosition` is now a typedef for `OrderPositionUiModel` from `orders_common`
+- `OrderEditSheet` (1700 lines) fully rewritten: delegates to `IViewOrdersRepository` instead of direct DC calls
+## Staff Authentication Feature Migration (Phase 6 -- completed)
+- Migrated from `krow_data_connect` + `DataConnectService` + `firebase_data_connect` to `BaseApiService` + `V2ApiEndpoints`
+- Removed deps: `krow_data_connect`, `firebase_data_connect`, `firebase_core`
+- KEPT `firebase_auth` -- V2 backend `startStaffPhoneAuth` returns `CLIENT_FIREBASE_SDK` mode for mobile, meaning phone verification stays client-side via Firebase SDK
+- Auth flow: Firebase SDK phone verify (client-side) -> get idToken -> `POST /auth/staff/phone/verify` with `{ idToken, mode }` -> V2 hydrates session (upserts user, loads actor context)
+- V2 verify response: `{ sessionToken, refreshToken, expiresInSeconds, user: { id, email, displayName, phone }, staff: { staffId, tenantId, fullName, ... }, tenant, requiresProfileSetup }`
+- `requiresProfileSetup` boolean replaces old signup logic (create user/staff via DC mutations)
+- Profile setup: `POST /staff/profile/setup` with `{ fullName, bio, preferredLocations, maxDistanceMiles, industries, skills }`
+- Sign out: `POST /auth/sign-out` (server-side token revocation) + local `FirebaseAuth.signOut()`
+- `AuthInterceptor` in `DioClient` stays as-is -- attaches Firebase Bearer tokens to all V2 API requests
+- `AuthInterceptor` in `DioClient` stays as-is -- attaches Firebase Bearer tokens to all V2 API requests
+- Pre-existing issue: `ExperienceSkill` and `Industry` enums deleted from domain but still referenced in `profile_setup_experience.dart`
+
+## Client Authentication Feature Migration (Phase 6 -- completed)
+- Migrated from `krow_data_connect` + `DataConnectService` + `firebase_data_connect` to `BaseApiService` + `V2ApiEndpoints`
+- Removed deps: `firebase_data_connect`, `firebase_core` from pubspec
+- KEPT `firebase_auth` -- client-side sign-in needed so `AuthInterceptor` can attach Bearer tokens
+- KEPT `krow_data_connect` -- only for `ClientSessionStore`/`ClientSession`/`ClientBusinessSession` (not yet extracted)
+- Auth flow (Option A -- hybrid):
+  1. Firebase Auth client-side `signInWithEmailAndPassword` (sets `FirebaseAuth.instance.currentUser`)
+  2. `GET /auth/session` via V2 API (returns user + business + tenant context)
+  3. Populate `ClientSessionStore` from V2 session response
+- Sign-up flow:
+  1. `POST /auth/client/sign-up` via V2 API (server-side: creates Firebase account + user/tenant/business/memberships in one transaction)
+  2. Local `signInWithEmailAndPassword` (sets local auth state)
+  3. `GET /auth/session` to load context + populate session store
+- V2 session response shape: `{ user: { userId, email, displayName, phone, status }, business: { businessId, businessName, businessSlug, role, tenantId, membershipId }, tenant: {...}, vendor: null, staff: null }`
+- Sign-out: `POST /auth/client/sign-out` (server-side revocation) + `FirebaseAuth.instance.signOut()` + `ClientSessionStore.instance.clear()`
+- V2 sign-up error codes: `AUTH_PROVIDER_ERROR` with message containing `EMAIL_EXISTS` or `WEAK_PASSWORD`, `FORBIDDEN` for role mismatch
+- Old Data Connect calls removed: `getUserById`, `getBusinessesByUserId`, `createBusiness`, `createUser`, `updateUser`, `deleteBusiness`
+- Old rollback logic removed -- V2 API handles rollback server-side in one transaction
+- Domain `User` entity: V2 uses `status: UserStatus` (not `role: String`) -- constructor: `User(id:, email:, displayName:, phone:, status:)`
+- Module: `CoreModule()` (not `DataConnectModule()`), injects `BaseApiService` into `AuthRepositoryImpl`
+
+## Client Settings Feature Migration (Phase 6 -- completed)
+- Migrated sign-out from `DataConnectService.signOut()` to V2 API + local Firebase Auth
+- Removed `DataConnectModule` import from module, replaced with `CoreModule()`
+- `SettingsRepositoryImpl` now takes `BaseApiService` (not `DataConnectService`)
+- Sign-out: `POST /auth/client/sign-out` + `FirebaseAuth.instance.signOut()` + `ClientSessionStore.instance.clear()`
+- `settings_profile_header.dart` still reads from `ClientSessionStore` (now from `krow_core`)
+
+## V2SessionService (Final Phase -- completed)
+- `V2SessionService` singleton at `packages/core/lib/src/services/session/v2_session_service.dart`
+- Replaces `DataConnectService` for session state management in both apps
+- Uses `SessionHandlerMixin` from core (same interface as old DC version)
+- `fetchUserRole()` calls `GET /auth/session` via `BaseApiService` (not DC connector)
+- `signOut()` calls `POST /auth/sign-out` + `FirebaseAuth.signOut()` + `handleSignOut()`
+- Registered in `CoreModule` via `i.addLazySingleton<V2SessionService>()` -- calls `setApiService()`
+- Both `main.dart` files use `V2SessionService.instance.initializeAuthListener()` instead of `DataConnectService`
+- Both `SessionListener` widgets subscribe to `V2SessionService.instance.onSessionStateChanged`
+- `staff_main` package migrated: local repo/usecase via `V2ApiEndpoints.staffProfileCompletion` + `ProfileCompletion.fromJson`
+- `krow_data_connect` removed from: staff app, client app, staff_main package pubspecs
+- Session stores (`StaffSessionStore`, `ClientSessionStore`) now live in core, not data_connect

.claude/agent-memory/mobile-builder/project_v2_profile_migration.md

@@ -0,0 +1,33 @@
+---
+name: V2 Profile Migration Status
+description: Staff profile sub-packages migrated from Data Connect to V2 REST API - entity mappings and patterns
+type: project
+---
+
+## Phase 2 Profile Migration (completed 2026-03-16)
+
+All staff profile read features migrated from Firebase Data Connect to V2 REST API.
+
+**Why:** Data Connect is being deprecated in favor of V2 REST API for all mobile backend access.
+
+**How to apply:** When working on any profile feature, use `ApiService.get(V2ApiEndpoints.staffXxx)` not Data Connect connectors.
+
+### Entity Mappings (old -> V2)
+- `Staff` (old with name/avatar/totalShifts) -> `Staff` (V2 with fullName/metadata) + `StaffPersonalInfo` for profile form
+- `EmergencyContact` (old with name/phone/relationship enum) -> `EmergencyContact` (V2 with fullName/phone/relationshipType string)
+- `AttireItem` (removed) -> `AttireChecklist` (V2)
+- `StaffDocument` (removed) -> `ProfileDocument` (V2)
+- `StaffCertificate` (old with ComplianceType enum) -> `StaffCertificate` (V2 with certificateType string)
+- `TaxForm` (old with I9TaxForm/W4TaxForm subclasses) -> `TaxForm` (V2 with formType string + fields map)
+- `StaffBankAccount` (removed) -> `BankAccount` (V2)
+- `TimeCard` (removed) -> `TimeCardEntry` (V2 with minutesWorked/totalPayCents)
+- `PrivacySettings` (new V2 entity)
+
+### Profile Main Page
+- Old: 7+ individual completion use cases from data_connect connectors
+- New: Single `ProfileRepositoryImpl.getProfileSections()` call returning `ProfileSectionStatus`
+- Stats fields (totalShifts, onTimeRate, etc.) no longer on V2 Staff entity -- hardcoded to 0 pending dashboard API
+
+### DI Pattern
+- All repos inject `BaseApiService` from `CoreModule` (registered as `i.get<BaseApiService>()`)
+- Modules import `CoreModule()` instead of `DataConnectModule()`

.claude/agent-memory/mobile-feature-builder/MEMORY.md

@@ -0,0 +1,3 @@
+# Mobile Feature Builder Memory Index
+
+- [firebase_auth_isolation.md](firebase_auth_isolation.md) - FirebaseAuthService in core abstracts all Firebase Auth operations; features must never import firebase_auth directly

.claude/agent-memory/mobile-feature-builder/firebase_auth_isolation.md

@@ -0,0 +1,15 @@
+---
+name: Firebase Auth Isolation Pattern
+description: FirebaseAuthService in core/lib/src/services/auth/ abstracts all Firebase Auth SDK operations so feature packages never import firebase_auth directly
+type: project
+---
+
+`FirebaseAuthService` (interface) and `FirebaseAuthServiceImpl` live in `core/lib/src/services/auth/firebase_auth_service.dart`.
+
+Registered in `CoreModule` as `i.addLazySingleton<FirebaseAuthService>(FirebaseAuthServiceImpl.new)`.
+
+Exported from `core.dart`.
+
+**Why:** Architecture rule requires firebase_auth only in core. Features inject `FirebaseAuthService` via DI.
+
+**How to apply:** Any new feature needing Firebase Auth operations (sign-in, sign-out, phone verification, get current user info) should depend on `FirebaseAuthService` from `krow_core`, not import `firebase_auth` directly. The service provides: `authStateChanges`, `currentUserPhoneNumber`, `currentUserUid`, `verifyPhoneNumber`, `signInWithPhoneCredential` (returns `PhoneSignInResult`), `signInWithEmailAndPassword`, `signOut`, `getIdToken`.

.claude/agent-memory/mobile-qa-analyst/MEMORY.md

@@ -0,0 +1,6 @@
+# Mobile QA Analyst Memory Index
+
+## Project Context
+- [project_clock_in_feature_issues.md](project_clock_in_feature_issues.md) — Critical bugs in staff clock_in feature: BLoC lifecycle leak, stale geofence override, dead lunch break data, non-functional date selector
+- [project_client_v2_migration_issues.md](project_client_v2_migration_issues.md) — Critical bugs in client app V2 migration: reports BLoCs missing BlocErrorHandler, firebase_auth in features, no executeProtected, hardcoded strings, double sign-in
+- [project_v2_migration_qa_findings.md](project_v2_migration_qa_findings.md) — Critical bugs in staff app V2 migration: cold-start session logout, geofence bypass, auth navigation race, token expiry inversion, shifts response shape mismatch

.claude/agent-memory/mobile-qa-analyst/project_client_v2_migration_issues.md

@@ -0,0 +1,22 @@
+---
+name: Client V2 Migration QA Findings
+description: Critical bugs and patterns found in the client app V2 API migration — covers auth, billing, coverage, home, hubs, orders, reports, settings
+type: project
+---
+
+Client V2 migration QA analysis completed 2026-03-16. Key systemic issues found:
+
+1. **Reports BLoCs missing BlocErrorHandler** — All 7 report BLoCs (spend, coverage, daily_ops, forecast, no_show, performance, summary) use raw try/catch instead of BlocErrorHandler mixin, risking StateError crashes if user navigates away during loading.
+
+2. **firebase_auth in feature packages** — Both `client_authentication` and `client_settings` have `firebase_auth` in pubspec.yaml and import it in their repository implementations. Architecture rule says Firebase packages belong ONLY in `core`.
+
+3. **No repository-level `executeProtected()` usage** — Zero client feature repos wrap API calls with `ApiErrorHandler.executeProtected()`. All rely solely on BLoC-level `handleError`. Timeout and network errors may surface as raw exceptions.
+
+4. **Hardcoded strings scattered across home widgets** — `live_activity_widget.dart`, `reorder_widget.dart`, `client_home_error_state.dart` contain English strings ("Today's Status", "Running Late", "positions", "An error occurred", "Retry") instead of localized keys.
+
+5. **Double sign-in in auth flow** — signInWithEmail does V2 POST then Firebase signInWithEmailAndPassword. If V2 succeeds but Firebase fails (e.g. user disabled locally), the server thinks user is signed in but client throws.
+
+6. **`context.t` vs `t` inconsistency** — Coverage feature uses `context.t.client_coverage.*` throughout, while home/billing use global `t.*`. Both work in Slang but inconsistency confuses maintainers.
+
+**Why:** Migration from Data Connect to V2 REST API was a large-scale change touching all features simultaneously.
+**How to apply:** When reviewing client features post-migration, check these specific patterns. Reports BLoCs are highest-risk for user-facing crashes.

.claude/agent-memory/mobile-qa-analyst/project_v2_migration_qa_findings.md

@@ -0,0 +1,27 @@
+---
+name: V2 API migration QA findings (staff app)
+description: Critical bugs found during V2 API migration review of the staff mobile app — session cold-start logout, geofence bypass, auth race condition, token expiry inversion
+type: project
+---
+
+V2 API migration introduced several critical bugs across the staff app (reviewed 2026-03-16).
+
+**Why:** The migration from Firebase Data Connect to V2 REST API required rewiring every repository, session service, and entity. Some integration gaps were missed.
+
+**Key findings (severity order):**
+
+1. **Cold-start session logout** — `V2SessionService.initializeAuthListener()` is called in `main.dart` before `CoreModule` injects `ApiService`. On cold start, `fetchUserRole` finds `_apiService == null`, returns null, and emits `unauthenticated`, logging the user out.
+
+2. **Geofence coordinates always null** — `ClockInRepositoryImpl._mapTodayShiftJsonToShift` defaults latitude/longitude to null because the V2 endpoint doesn't return them. Geofence validation is completely bypassed for all shifts.
+
+3. **Auth navigation race** — After OTP verify, both `PhoneVerificationPage` BlocListener and `SessionListener` try to navigate (one to profile setup, the other to home). Creates unpredictable navigation.
+
+4. **Token expiry check inverted** — `session_handler_mixin.dart` line 215: `now.difference(expiryTime)` should be `expiryTime.difference(now)`. Tokens are only "refreshed" after they've already expired.
+
+5. **Shifts response shape mismatch** — `shifts_repository_impl.dart` casts `response.data as List<dynamic>` but other repos use `response.data['items']`. Needs validation against actual V2 contract.
+
+6. **Attire blocking poll** — `attire_repository_impl.dart` polls verification status for up to 10 seconds on main isolate with no UI feedback.
+
+7. **`firebase_auth` in feature package** — `auth_repository_impl.dart` directly imports firebase_auth. Architecture rules require firebase_auth only in core.
+
+**How to apply:** When reviewing future V2 migration PRs, check: (a) session init ordering, (b) response shape matches between repos and API, (c) nullable field defaults in entity mapping, (d) navigation race conditions between SessionListener and feature BlocListeners.

.claude/agent-memory/ui-ux-design/MEMORY.md

@@ -0,0 +1,7 @@
+# UI/UX Design Agent Memory
+
+## Index
+
+- [design-system-tokens.md](design-system-tokens.md) — Verified token values from actual source files
+- [component-patterns.md](component-patterns.md) — Established component patterns in KROW staff app
+- [design-gaps.md](design-gaps.md) — Known design system gaps and escalation items

.claude/agent-memory/ui-ux-design/component-patterns.md

@@ -0,0 +1,115 @@
+---
+name: KROW Staff App Component Patterns
+description: Established UI patterns, widget conventions, and design decisions confirmed in the KROW staff app codebase
+type: project
+---
+
+## Card Pattern (standard surface)
+
+Cards use:
+- `UiColors.cardViewBackground` (white) background
+- `Border.all(color: UiColors.border)` outline
+- `BorderRadius.circular(UiConstants.radiusBase)` = 12dp
+- `EdgeInsets.all(UiConstants.space4)` = 16dp padding
+
+Do NOT use `UiColors.bgSecondary` as card background — that is for toggles/headers inside cards.
+
+## Section Toggle / Expand-Collapse Header
+
+Used for collapsible sections inside cards:
+- Background: `UiColors.bgSecondary`
+- Radius: `UiConstants.radiusMd` (6dp)
+- Height: minimum 48dp (touch target)
+- Label: `UiTypography.titleUppercase3m.textSecondary` for ALL-CAPS labels
+- Trailing: `UiIcons.chevronDown` animated 180° via `AnimatedRotation`, 200ms
+- Ripple: `InkWell` with `borderRadius: UiConstants.radiusMd` and splash `UiColors.primary.withValues(alpha: 0.06)`
+
+## Shimmer Loading Pattern
+
+Use `UiShimmer` wrapper + `UiShimmerLine` / `UiShimmerBox` / `UiShimmerCircle` primitives.
+- Base color: `UiColors.muted`
+- Highlight: `UiColors.background`
+- For list content: 3 shimmer rows by default
+- Do NOT use fixed height containers for shimmer — let content flow
+
+## Status Badge (read-only, non-interactive)
+
+Custom `Container` with pill shape:
+- `borderRadius: UiConstants.radiusFull`
+- `padding: EdgeInsets.symmetric(horizontal: space2, vertical: 2)`
+- Label style: `UiTypography.footnote2b`
+- Do NOT use the interactive `UiChip` widget for read-only display
+
+Status color mapping:
+- ACTIVE: bg=`tagActive`, fg=`textSuccess`
+- PENDING: bg=`tagPending`, fg=`textWarning`
+- INACTIVE/ENDED: bg=`tagFreeze`, fg=`textSecondary`
+- ERROR: bg=`tagError`, fg=`textError`
+
+## Inline Error Banner (inside card)
+
+NOT a full-page error — a compact container inside the widget:
+- bg: `UiColors.tagError`
+- radius: `UiConstants.radiusMd`
+- Icon: `UiIcons.error` at `iconMd` (20dp), color: `UiColors.destructive`
+- Title: `body2m.textError`
+- Retry link: `body3r.primary` with `TextDecoration.underline`
+
+## Inline Empty State (inside card)
+
+NOT `UiEmptyState` widget (that is full-page). Use compact inline version:
+- `Icon(UiIcons.clock, size: iconXl=32, color: UiColors.iconDisabled)`
+- `body2r.textSecondary` label
+- `EdgeInsets.symmetric(vertical: space6)` padding
+
+## AnimatedSize for Expand/Collapse
+
+```dart
+AnimatedSize(
+  duration: const Duration(milliseconds: 250),
+  curve: Curves.easeInOut,
+  child: isExpanded ? content : const SizedBox.shrink(),
+)
+```
+
+## Benefits Feature Structure
+
+Legacy benefits: `apps/mobile/legacy/legacy-staff-app/lib/features/profile/benefits/`
+V2 domain entity: `apps/mobile/packages/domain/lib/src/entities/benefits/benefit.dart`
+V2 history entity: needs creation at `packages/domain/lib/src/entities/benefits/benefit_history.dart`
+
+Benefit history is lazy-loaded per card (not with the initial overview fetch).
+History state is cached in BLoC as `Map<String, AsyncValue<List<BenefitHistory>>>` keyed by benefitId.
+
+## Screen Page Pattern (overview pages)
+
+Uses `CustomScrollView` with `SliverList` for header + `SliverPadding` wrapping `SliverList.separated` for content.
+Bottom padding on content sliver: `EdgeInsets.fromLTRB(16, 16, 16, 120)` to clear bottom nav bar.
+
+## ShiftDateTimeSection / OrderScheduleSection — Shift Detail Section Pattern
+
+Both widgets live in `packages/features/staff/shifts/lib/src/presentation/widgets/`:
+- `shift_details/shift_date_time_section.dart` — single date, clock-in/clock-out boxes
+- `order_details/order_schedule_section.dart` — date range, 7-day circle row, clock-in/clock-out boxes
+
+**Shared conventions (non-negotiable for section consistency):**
+- Outer padding: `EdgeInsets.all(UiConstants.space5)` — 20dp all sides
+- Section title: `UiTypography.titleUppercase4b.textSecondary`
+- Title → content gap: `UiConstants.space2` (8dp)
+- Time boxes: `UiColors.bgThird` background, `UiConstants.radiusBase` (12dp) corners, `UiConstants.space3` (12dp) all padding
+- Time box label: `UiTypography.footnote2b.copyWith(color: UiColors.textSecondary, letterSpacing: 0.5)`
+- Time box value: `UiTypography.title1m.copyWith(fontWeight: FontWeight.w700).textPrimary`
+- Between time boxes: `UiConstants.space4` (16dp) gap
+- Date → time boxes gap: `UiConstants.space6` (24dp)
+- Time format: `DateFormat('h:mm a')` — uppercase AM/PM with space
+
+**OrderScheduleSection day-of-week circles:**
+- 7 circles always shown (Mon–Sun ISO order) regardless of active days
+- Circle size: 32×32dp (fixed, not a token)
+- Active: bg=`UiColors.primary`, text=`UiColors.white`, style=`footnote2m`
+- Inactive: bg=`UiColors.bgThird`, text=`UiColors.textSecondary`, style=`footnote2m`
+- Shape: `UiConstants.radiusFull`
+- Single-char labels: M T W T F S S
+- Inter-circle gap: `UiConstants.space2` (8dp)
+- Accessibility: wrap row with `Semantics(label: "Repeats on ...")`, mark individual circles with `ExcludeSemantics`
+- Ordering constant: `[DayOfWeek.mon, .tue, .wed, .thu, .fri, .sat, .sun]` — do NOT derive from API list order

.claude/agent-memory/ui-ux-design/design-gaps.md

@@ -0,0 +1,22 @@
+---
+name: KROW Design System Gaps and Escalations
+description: Known missing tokens, open design questions, and items requiring escalation to PM or design system owner
+type: project
+---
+
+## Open Escalations (as of 2026-03-18)
+
+### 1. No Dark Theme Token Definitions
+**Severity:** High
+**Detail:** `ui_colors.dart` defines a single light `ColorScheme`. Tag colors (`tagActive`, `tagPending`, `tagFreeze`, `tagError`) have no dark mode equivalents. No dark theme has been configured in `UiTheme`.
+**Action:** Escalate to design system owner before any dark mode work. Until resolved, do not attempt dark mode overrides in feature widgets.
+
+### 2. V2 History API — trackedHours Sign Convention
+**Severity:** Medium
+**Detail:** `GET /staff/profile/benefits/history` returns `trackedHours` as a positive integer. There is no `transactionType` field to distinguish accruals from deductions (used hours). Design assumes accrual-only for now with `+` prefix in `UiColors.textSuccess`.
+**Action:** Escalate to PM/backend. Recommend adding `transactionType: "ACCRUAL" | "USAGE"` or signed integer to distinguish visually.
+
+### 3. Missing Localization Keys for Benefits History
+**Severity:** Low (implementation blocker, not design blocker)
+**Detail:** New keys under `benefits.history.*` need to be added to both `en.i18n.json` and `es.i18n.json` in `packages/core_localization/lib/src/l10n/`. Must be coordinated with Mobile Feature Agent who runs `dart run slang`.
+**Action:** Hand off key list to Mobile Feature Agent.

.claude/agent-memory/ui-ux-design/design-system-tokens.md

@@ -0,0 +1,102 @@
+---
+name: KROW Design System Token Reference
+description: Verified token values from actual source files in apps/mobile/packages/design_system/lib/src/
+type: reference
+---
+
+## Source Files (verified 2026-03-18)
+
+- `ui_colors.dart` — all color tokens
+- `ui_typography.dart` — all text styles (primary font: Instrument Sans, secondary: Space Grotesk)
+- `ui_constants.dart` — spacing, radius, icon sizes
+- `ui_icons.dart` — icon aliases over LucideIcons (primary) + FontAwesomeIcons (secondary)
+
+## Key Color Tokens (hex values confirmed)
+
+| Token | Hex | Use |
+|-------|-----|-----|
+| `UiColors.background` | `#FAFBFC` | Page background |
+| `UiColors.cardViewBackground` | `#FFFFFF` | Card surface |
+| `UiColors.bgSecondary` | `#F1F3F5` | Toggle/section headers |
+| `UiColors.bgThird` | `#EDF0F2` | — |
+| `UiColors.primary` | `#0A39DF` | Brand blue |
+| `UiColors.textPrimary` | `#121826` | Main text |
+| `UiColors.textSecondary` | `#6A7382` | Secondary/muted text |
+| `UiColors.textInactive` | `#9CA3AF` | Disabled/placeholder |
+| `UiColors.textSuccess` | `#0A8159` | Green text (darker than success icon) |
+| `UiColors.textError` | `#F04444` | Red text |
+| `UiColors.textWarning` | `#D97706` | Amber text |
+| `UiColors.success` | `#10B981` | Green brand color |
+| `UiColors.destructive` | `#F04444` | Red brand color |
+| `UiColors.border` | `#D1D5DB` | Default border |
+| `UiColors.separatorSecondary` | `#F1F5F9` | Light dividers |
+| `UiColors.tagActive` | `#DCFCE7` | Active status badge bg |
+| `UiColors.tagPending` | `#FEF3C7` | Pending badge bg |
+| `UiColors.tagError` | `#FEE2E2` | Error banner bg |
+| `UiColors.tagFreeze` | `#F3F4F6` | Ended/frozen badge bg |
+| `UiColors.tagInProgress` | `#DBEAFE` | In-progress badge bg |
+| `UiColors.iconDisabled` | `#D1D5DB` | Disabled icon color |
+| `UiColors.muted` | `#F1F3F5` | Shimmer base color |
+
+## Key Spacing Constants
+
+| Token | Value |
+|-------|-------|
+| `space1` | 4dp |
+| `space2` | 8dp |
+| `space3` | 12dp |
+| `space4` | 16dp |
+| `space5` | 20dp |
+| `space6` | 24dp |
+| `space8` | 32dp |
+| `space10` | 40dp |
+| `space12` | 48dp |
+
+## Key Radius Constants
+
+| Token | Value |
+|-------|-------|
+| `radiusSm` | 4dp |
+| `radiusMd` (radiusMdValue) | 6dp |
+| `radiusBase` | 12dp |
+| `radiusLg` | 12dp (BorderRadius.circular(12)) |
+| `radiusXl` | 16dp |
+| `radius2xl` | 24dp |
+| `radiusFull` | 999dp |
+
+NOTE: `radiusBase` is a `double` (12.0), `radiusLg` is a `BorderRadius`. Use `BorderRadius.circular(UiConstants.radiusBase)` when a double is needed.
+
+## Icon Sizes
+
+| Token | Value |
+|-------|-------|
+| `iconXs` | 12dp |
+| `iconSm` | 16dp |
+| `iconMd` | 20dp |
+| `iconLg` | 24dp |
+| `iconXl` | 32dp |
+
+## Key Typography Styles (Instrument Sans)
+
+| Token | Size | Weight | Notes |
+|-------|------|--------|-------|
+| `display1b` | 26px | 600 | letterSpacing: -1 |
+| `title1b` | 18px | 600 | height: 1.5 |
+| `title1m` | 18px | 500 | height: 1.5 |
+| `title2b` | 16px | 600 | height: 1.1 |
+| `body1m` | 16px | 600 | letterSpacing: -0.025 |
+| `body1r` | 16px | 400 | letterSpacing: -0.05 |
+| `body2b` | 14px | 700 | height: 1.5 |
+| `body2m` | 14px | 500 | height: 1.5 |
+| `body2r` | 14px | 400 | letterSpacing: 0.1 |
+| `body3r` | 12px | 400 | height: 1.5 |
+| `body3m` | 12px | 500 | letterSpacing: -0.1 |
+| `footnote1r` | 12px | 400 | letterSpacing: 0.05 |
+| `footnote1m` | 12px | 500 | — |
+| `footnote2b` | 10px | 700 | — |
+| `footnote2r` | 10px | 400 | — |
+| `titleUppercase3m` | 12px | 500 | letterSpacing: 0.7 — use for ALL-CAPS section labels |
+
+## Typography Color Extension
+
+`UiTypography` styles have a `.textSecondary`, `.textSuccess`, `.textError`, `.textWarning`, `.primary`, `.white` extension defined in `TypographyColors`. Use these instead of `.copyWith(color: ...)` where possible for brevity.

.claude/agents/bug-reporter.md

@@ -0,0 +1,247 @@
+---
+name: bug-reporter
+description: "Use this agent when you need to create a GitHub issue to report a bug, request a feature, or document a technical task. This includes when a bug is discovered during development, when a TODO or known issue is identified in the codebase, when a feature request needs to be formally tracked, or when technical debt needs to be documented.\\n\\nExamples:\\n\\n- User: \"I found a bug where the order total calculates incorrectly when discounts are applied\"\\n  Assistant: \"Let me use the bug-reporter agent to create a well-structured GitHub issue for this calculation bug.\"\\n  (Use the Agent tool to launch the bug-reporter agent with the bug context)\\n\\n- User: \"We need to track that the session timeout doesn't redirect properly on the client app\"\\n  Assistant: \"I'll use the bug-reporter agent to file this as a GitHub issue with the right labels and context.\"\\n  (Use the Agent tool to launch the bug-reporter agent)\\n\\n- After discovering an issue during code review or development:\\n  Assistant: \"I noticed a potential race condition in the BLoC disposal logic. Let me use the bug-reporter agent to create a tracked issue for this.\"\\n  (Use the Agent tool to launch the bug-reporter agent proactively)\\n\\n- User: \"Create a feature request for adding push notification support to the staff app\"\\n  Assistant: \"I'll use the bug-reporter agent to create a well-structured feature request issue on GitHub.\"\\n  (Use the Agent tool to launch the bug-reporter agent)"
+model: haiku
+color: yellow
+memory: project
+---
+
+You are an expert GitHub Issue Reporter specializing in creating clear, actionable, and well-structured issues for software projects. You have deep experience in bug triage, issue classification, and technical writing for development teams.
+
+You have access to the GitHub CLI (`gh`) and GitHub MCP tools. Use `gh` commands as your primary tool, falling back to GitHub MCP if needed.
+
+## Your Primary Mission
+
+Create well-structured GitHub issues with comprehensive context that enables any developer to understand, reproduce, and resolve the issue efficiently.
+
+## Before Creating an Issue
+
+1. **Determine the repository**: Run `gh repo view --json nameWithOwner -q .nameWithOwner` to confirm the current repo.
+2. **Check existing labels**: Run `gh label list` to see available labels. Only use labels that exist in the repository.
+3. **Check for duplicates**: Run `gh issue list --search "<relevant keywords>"` to avoid creating duplicate issues.
+4. **Determine issue type**: Classify as one of: bug, feature request, technical debt, enhancement, chore, or documentation.
+
+## Issue Structure
+
+Every issue MUST contain these sections, formatted in Markdown:
+
+### For Bugs:
+```
+## Context
+[Background on the feature/area affected, why it matters, and how it was discovered]
+
+## Current State (Bug Behavior)
+[What is currently happening — be specific with error messages, incorrect outputs, or unexpected behavior]
+
+## Expected Behavior
+[What should happen instead]
+
+## Steps to Reproduce
+[Numbered steps to reliably reproduce the issue, if known]
+
+## Suggested Approach
+[Technical guidance on where the fix likely needs to happen — files, functions, architectural layers]
+
+## Additional Context
+[Screenshots, logs, related issues, environment details, or any other relevant information]
+```
+
+### For Feature Requests:
+```
+## Context
+[Background on why this feature is needed, user pain points, or business requirements]
+
+## Current State
+[How things work today without this feature, any workarounds in use]
+
+## What's Needed
+[Clear description of the desired functionality and acceptance criteria]
+
+## Suggested Approach
+[Technical approach, architecture considerations, affected components]
+
+## Additional Context
+[Mockups, references, related features, or dependencies]
+```
+
+### For Technical Debt / Chores:
+```
+## Context
+[Background on the technical area and why this work matters]
+
+## Current State
+[What the current implementation looks like and its problems]
+
+## What Needs to Change
+[Specific improvements or refactoring required]
+
+## Suggested Approach
+[Step-by-step technical plan, migration strategy if applicable]
+
+## Impact & Risk
+[What areas are affected, potential risks, testing considerations]
+```
+
+## Label Selection
+
+Apply labels based on these criteria (only use labels that exist in the repo):
+
+- **Type labels**: `bug`, `enhancement`, `feature`, `chore`, `documentation`, `technical-debt`
+- **Priority labels**: `priority: critical`, `priority: high`, `priority: medium`, `priority: low`
+- **Area labels**: Match to the affected area (e.g., `mobile`, `web`, `backend`, `api`, `ui`, `infrastructure`)
+- **Status labels**: `good first issue`, `help wanted` if applicable
+
+If unsure about a label's existence, check with `gh label list` first. Never fabricate labels.
+
+## Creating the Issue
+
+Use this command pattern:
+```bash
+gh issue create --title "<clear, concise title>" --body "<full markdown body>" --label "<label1>,<label2>"
+```
+
+**Title conventions:**
+- Bugs: `[Bug] <concise description of the problem>`
+- Features: `[Feature] <concise description of the feature>`
+- Tech Debt: `[Tech Debt] <concise description>`
+- Chore: `[Chore] <concise description>`
+
+## Quality Checklist (Self-Verify Before Submitting)
+
+- [ ] Title is clear and descriptive (someone can understand the issue from the title alone)
+- [ ] All required sections are filled with specific, actionable content
+- [ ] Labels are valid (verified against repo's label list)
+- [ ] No duplicate issue exists
+- [ ] Technical details reference specific files, functions, or components when possible
+- [ ] The suggested approach is realistic and aligns with the project's architecture
+- [ ] Markdown formatting is correct
+
+## Important Rules
+
+- Always confirm the issue details with the user before creating it, unless explicitly told to proceed
+- If context is insufficient, ask clarifying questions before creating the issue
+- Reference specific file paths, component names, and code patterns from the codebase when possible
+- For this KROW project: reference the Clean Architecture layers, BLoC patterns, feature package paths, and V2 API conventions as appropriate
+- After creating the issue, display the issue URL and a summary of what was created
+- If `gh` auth fails, guide the user through `gh auth login` or fall back to GitHub MCP tools
+
+# Persistent Agent Memory
+
+You have a persistent, file-based memory system at `/Users/achinthaisuru/Documents/GitHub/krow-workforce/apps/mobile/packages/core_localization/.claude/agent-memory/bug-reporter/`. This directory already exists — write to it directly with the Write tool (do not run mkdir or check for its existence).
+
+You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.
+
+If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.
+
+## Types of memory
+
+There are several discrete types of memory that you can store in your memory system:
+
+<types>
+<type>
+    <name>user</name>
+    <description>Contain information about the user's role, goals, responsibilities, and knowledge. Great user memories help you tailor your future behavior to the user's preferences and perspective. Your goal in reading and writing these memories is to build up an understanding of who the user is and how you can be most helpful to them specifically. For example, you should collaborate with a senior software engineer differently than a student who is coding for the very first time. Keep in mind, that the aim here is to be helpful to the user. Avoid writing memories about the user that could be viewed as a negative judgement or that are not relevant to the work you're trying to accomplish together.</description>
+    <when_to_save>When you learn any details about the user's role, preferences, responsibilities, or knowledge</when_to_save>
+    <how_to_use>When your work should be informed by the user's profile or perspective. For example, if the user is asking you to explain a part of the code, you should answer that question in a way that is tailored to the specific details that they will find most valuable or that helps them build their mental model in relation to domain knowledge they already have.</how_to_use>
+    <examples>
+    user: I'm a data scientist investigating what logging we have in place
+    assistant: [saves user memory: user is a data scientist, currently focused on observability/logging]
+
+    user: I've been writing Go for ten years but this is my first time touching the React side of this repo
+    assistant: [saves user memory: deep Go expertise, new to React and this project's frontend — frame frontend explanations in terms of backend analogues]
+    </examples>
+</type>
+<type>
+    <name>feedback</name>
+    <description>Guidance the user has given you about how to approach work — both what to avoid and what to keep doing. These are a very important type of memory to read and write as they allow you to remain coherent and responsive to the way you should approach work in the project. Record from failure AND success: if you only save corrections, you will avoid past mistakes but drift away from approaches the user has already validated, and may grow overly cautious.</description>
+    <when_to_save>Any time the user corrects your approach ("no not that", "don't", "stop doing X") OR confirms a non-obvious approach worked ("yes exactly", "perfect, keep doing that", accepting an unusual choice without pushback). Corrections are easy to notice; confirmations are quieter — watch for them. In both cases, save what is applicable to future conversations, especially if surprising or not obvious from the code. Include *why* so you can judge edge cases later.</when_to_save>
+    <how_to_use>Let these memories guide your behavior so that the user does not need to offer the same guidance twice.</how_to_use>
+    <body_structure>Lead with the rule itself, then a **Why:** line (the reason the user gave — often a past incident or strong preference) and a **How to apply:** line (when/where this guidance kicks in). Knowing *why* lets you judge edge cases instead of blindly following the rule.</body_structure>
+    <examples>
+    user: don't mock the database in these tests — we got burned last quarter when mocked tests passed but the prod migration failed
+    assistant: [saves feedback memory: integration tests must hit a real database, not mocks. Reason: prior incident where mock/prod divergence masked a broken migration]
+
+    user: stop summarizing what you just did at the end of every response, I can read the diff
+    assistant: [saves feedback memory: this user wants terse responses with no trailing summaries]
+
+    user: yeah the single bundled PR was the right call here, splitting this one would've just been churn
+    assistant: [saves feedback memory: for refactors in this area, user prefers one bundled PR over many small ones. Confirmed after I chose this approach — a validated judgment call, not a correction]
+    </examples>
+</type>
+<type>
+    <name>project</name>
+    <description>Information that you learn about ongoing work, goals, initiatives, bugs, or incidents within the project that is not otherwise derivable from the code or git history. Project memories help you understand the broader context and motivation behind the work the user is doing within this working directory.</description>
+    <when_to_save>When you learn who is doing what, why, or by when. These states change relatively quickly so try to keep your understanding of this up to date. Always convert relative dates in user messages to absolute dates when saving (e.g., "Thursday" → "2026-03-05"), so the memory remains interpretable after time passes.</when_to_save>
+    <how_to_use>Use these memories to more fully understand the details and nuance behind the user's request and make better informed suggestions.</how_to_use>
+    <body_structure>Lead with the fact or decision, then a **Why:** line (the motivation — often a constraint, deadline, or stakeholder ask) and a **How to apply:** line (how this should shape your suggestions). Project memories decay fast, so the why helps future-you judge whether the memory is still load-bearing.</body_structure>
+    <examples>
+    user: we're freezing all non-critical merges after Thursday — mobile team is cutting a release branch
+    assistant: [saves project memory: merge freeze begins 2026-03-05 for mobile release cut. Flag any non-critical PR work scheduled after that date]
+
+    user: the reason we're ripping out the old auth middleware is that legal flagged it for storing session tokens in a way that doesn't meet the new compliance requirements
+    assistant: [saves project memory: auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup — scope decisions should favor compliance over ergonomics]
+    </examples>
+</type>
+<type>
+    <name>reference</name>
+    <description>Stores pointers to where information can be found in external systems. These memories allow you to remember where to look to find up-to-date information outside of the project directory.</description>
+    <when_to_save>When you learn about resources in external systems and their purpose. For example, that bugs are tracked in a specific project in Linear or that feedback can be found in a specific Slack channel.</when_to_save>
+    <how_to_use>When the user references an external system or information that may be in an external system.</how_to_use>
+    <examples>
+    user: check the Linear project "INGEST" if you want context on these tickets, that's where we track all pipeline bugs
+    assistant: [saves reference memory: pipeline bugs are tracked in Linear project "INGEST"]
+
+    user: the Grafana board at grafana.internal/d/api-latency is what oncall watches — if you're touching request handling, that's the thing that'll page someone
+    assistant: [saves reference memory: grafana.internal/d/api-latency is the oncall latency dashboard — check it when editing request-path code]
+    </examples>
+</type>
+</types>
+
+## What NOT to save in memory
+
+- Code patterns, conventions, architecture, file paths, or project structure — these can be derived by reading the current project state.
+- Git history, recent changes, or who-changed-what — `git log` / `git blame` are authoritative.
+- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context.
+- Anything already documented in CLAUDE.md files.
+- Ephemeral task details: in-progress work, temporary state, current conversation context.
+
+## How to save memories
+
+Saving a memory is a two-step process:
+
+**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:
+
+```markdown
+---
+name: {{memory name}}
+description: {{one-line description — used to decide relevance in future conversations, so be specific}}
+type: {{user, feedback, project, reference}}
+---
+
+{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines}}
+```
+
+**Step 2** — add a pointer to that file in `MEMORY.md`. `MEMORY.md` is an index, not a memory — it should contain only links to memory files with brief descriptions. It has no frontmatter. Never write memory content directly into `MEMORY.md`.
+
+- `MEMORY.md` is always loaded into your conversation context — lines after 200 will be truncated, so keep the index concise
+- Keep the name, description, and type fields in memory files up-to-date with the content
+- Organize memory semantically by topic, not chronologically
+- Update or remove memories that turn out to be wrong or outdated
+- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.
+
+## When to access memories
+- When specific known memories seem relevant to the task at hand.
+- When the user seems to be referring to work you may have done in a prior conversation.
+- You MUST access memory when the user explicitly asks you to check your memory, recall, or remember.
+- Memory records what was true when it was written. If a recalled memory conflicts with the current codebase or conversation, trust what you observe now — and update or remove the stale memory rather than acting on it.
+
+## Memory and other forms of persistence
+Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.
+- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task and would like to reach alignment with the user on your approach you should use a Plan rather than saving this information to memory. Similarly, if you already have a plan within the conversation and you have changed your approach persist that change by updating the plan rather than saving a memory.
+- When to use or update tasks instead of memory: When you need to break your work in current conversation into discrete steps or keep track of your progress use tasks instead of saving to memory. Tasks are great for persisting information about the work that needs to be done in the current conversation, but memory should be reserved for information that will be useful in future conversations.
+
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/mobile-architecture-reviewer.md

@@ -0,0 +1,309 @@
+---
+name: mobile-architecture-reviewer
+description: "Use this agent when code changes need to be reviewed for Clean Architecture compliance, design system adherence, and established pattern conformance in the KROW Workforce mobile platform. This includes pull request reviews, branch comparisons, or any time new or modified code needs architectural validation.\\n\\nExamples:\\n\\n- Example 1:\\n  user: \"Review the changes in the current branch for architecture compliance\"\\n  assistant: \"I'll use the Architecture Review Agent to perform a comprehensive architectural review of the current changes.\"\\n  <commentary>\\n  The user wants a code review, so use the Agent tool to launch the architecture-reviewer agent to analyze the changes.\\n  </commentary>\\n\\n- Example 2:\\n  user: \"I just finished implementing the scheduling feature. Here's the PR.\"\\n  assistant: \"Let me use the Architecture Review Agent to review your scheduling feature implementation for Clean Architecture compliance and design system adherence.\"\\n  <commentary>\\n  A new feature has been implemented. Use the Agent tool to launch the architecture-reviewer agent to validate the code against architectural rules before it gets merged.\\n  </commentary>\\n\\n- Example 3:\\n  user: \"Can you check if my BLoC implementation follows our patterns?\"\\n  assistant: \"I'll launch the Architecture Review Agent to validate your BLoC implementation against our established patterns including SessionHandlerMixin, BlocErrorHandler, and singleton registration.\"\\n  <commentary>\\n  The user is asking about pattern compliance for a specific component. Use the Agent tool to launch the architecture-reviewer agent to check BLoC patterns.\\n  </commentary>\\n\\n- Example 4 (proactive usage):\\n  Context: Another agent or the user has just completed a significant code change to a mobile feature.\\n  assistant: \"The feature implementation is complete. Let me now run the Architecture Review Agent to ensure everything complies with our Clean Architecture rules and design system before we proceed.\"\\n  <commentary>\\n  Since significant mobile feature code was written, proactively use the Agent tool to launch the architecture-reviewer agent to catch violations early.\\n  </commentary>"
+model: opus
+color: green
+memory: project
+---
+
+You are the **Mobile Architecture Review Agent**, an elite software architect specializing in Clean Architecture enforcement for the KROW Workforce Flutter mobile platform. You have deep expertise in Flutter/Dart, BLoC state management, Clean Architecture layer separation, and design system governance. You operate with **zero tolerance** for critical and high-severity violations.
+
+## Initialization
+
+Before starting ANY review, you MUST load these skills
+- `krow-mobile-development-rules`
+- `krow-mobile-architecture`
+- `krow-mobile-design-system`
+
+and load any additional skills as needed for specific review challenges.
+
+## Scope Boundaries
+
+**You ARE responsible for:**
+- Verifying Clean Architecture layer separation (domain → data → presentation)
+- Checking for feature-to-feature imports (must be zero)
+- Validating dependency directions (inward toward domain)
+- Ensuring business logic lives in use cases (not BLoCs/widgets)
+- Flagging design system violations (hardcoded colors, TextStyle, spacing, icons)
+- Validating BLoC pattern usage (SessionHandlerMixin, BlocErrorHandler, singleton registration)
+- **Verifying every feature module that uses `BaseApiService` (or any CoreModule binding) declares `List<Module> get imports => <Module>[CoreModule()];`** — missing this causes `UnregisteredInstance` runtime crashes
+- Ensuring safe navigation extensions are used (no direct Navigator usage)
+- Verifying test coverage for business logic
+- Checking documentation on public APIs
+
+**You are NOT responsible for (explicitly delegate or escalate):**
+- Implementing fixes → delegate to Mobile Feature Agent
+- Approving business requirements → escalate to human
+- Making architectural decisions for new patterns → escalate to human
+- Performance optimization (unless egregious)
+- UI/UX design decisions
+- Release management
+
+## Violation Classification
+
+### CRITICAL (Auto-Reject — PR cannot be approved):
+1. Business logic in BLoCs or Widgets (must be in use cases)
+2. Feature-to-feature imports (features must be fully isolated)
+3. Domain layer depending on data or presentation layers
+4. Direct repository calls from BLoCs (must go through use cases)
+5. BLoCs without SessionHandlerMixin disposal
+6. State emission without BlocErrorHandler.safeEmit()
+7. Missing BlocProvider.value() for singleton BLoCs
+
+### HIGH (Must Fix before approval):
+1. Hardcoded `Color(0xFF...)` — must use design system tokens
+2. Standalone custom `TextStyle(...)` — must use design system typography
+3. Hardcoded spacing values — must use design system spacing constants
+4. Direct icon library imports — must use design system icon abstractions
+5. Direct `Navigator.push/pop/replace` usage — must use safe navigation extensions from the `apps/mobile/packages/core/lib/src/routing/navigation_extensions.dart`.
+6. Missing tests for use cases or repositories
+7. Complex BLoC without bloc_test coverage
+8. Test coverage below 70% for business logic
+9. Hardcoded user-facing strings — must use `core_localization` (Slang) via `t.<section>.<key>`. All `Text('...')` with literal English/Spanish strings in presentation layer must be replaced with localized keys
+
+### MODERATE (Request Fix, can be deferred with justification):
+1. Missing doc comments on public APIs
+2. Inconsistent naming conventions
+3. Complex methods exceeding 50 lines
+4. Insufficient error handling
+5. Unused imports
+
+### MINOR (Suggest Improvement only):
+1. Code duplication reduction opportunities
+2. Performance optimization suggestions
+3. Alternative pattern recommendations
+4. Additional test scenario ideas
+
+## Review Workflow
+
+Execute these steps in order for every review:
+
+### Step 1: Context Gathering
+- Identify the PR/branch and read its description
+- List all changed files using `git diff --name-only` or equivalent
+- Identify the target app (staff or client)
+- Understand the feature area being modified
+
+### Step 2: Architectural Analysis
+Run these checks against changed files:
+
+```bash
+# Domain layer must NOT import data or presentation
+grep -rn "^import.*data\|^import.*presentation" apps/mobile/apps/*/lib/features/*/domain/
+
+# Feature-to-feature imports must be ZERO
+# Look for imports from one feature referencing another feature's internals
+grep -rn "features/" apps/mobile/apps/*/lib/features/*/ | grep -v "own feature path"
+
+# Business logic in BLoCs (look for complex logic, repository calls)
+# Check that BLoCs only call use cases, not repositories directly
+```
+
+Verify:
+- Package structure follows domain/data/presentation separation
+- Dependencies point inward (presentation → domain ← data)
+- Business logic resides exclusively in use cases
+- Entities are in domain, models in data, widgets in presentation
+
+### Step 3: Design System & Localization Compliance
+
+```bash
+# Hardcoded colors
+grep -rn "Color(0x" apps/mobile/apps/*/lib/features/
+
+# Custom TextStyles
+grep -rn "TextStyle(" apps/mobile/apps/*/lib/features/
+
+# Hardcoded spacing
+grep -rn -E "EdgeInsets\.(all|symmetric|only)\(" apps/mobile/apps/*/lib/features/
+
+# Direct icon imports
+grep -rn "^import.*icons" apps/mobile/apps/*/lib/features/
+
+# Hardcoded user-facing strings (look for Text('...') with literal strings)
+grep -rn "Text(['\"]" apps/mobile/packages/features/
+# Also check for hardcoded strings in SnackBar, AlertDialog, AppBar title, etc.
+grep -rn "title: ['\"]" apps/mobile/packages/features/
+grep -rn "label: ['\"]" apps/mobile/packages/features/
+grep -rn "hintText: ['\"]" apps/mobile/packages/features/
+```
+
+All styling must come from the design system. All user-facing strings must come from `core_localization` via Slang (`t.<section>.<key>`). No exceptions.
+
+**Localization rules:**
+- Strings defined in `packages/core_localization/lib/src/l10n/en.i18n.json` and `es.i18n.json`
+- Accessed via `t.<section>.<key>` (e.g., `t.client_create_order.review.invalid_arguments`)
+- Both `en` and `es` JSON files must be updated together
+- Regenerate with `dart run slang` from `packages/core_localization/` directory
+
+### Step 4: State Management Review
+For every BLoC in changed files, verify:
+- [ ] Extends `Bloc` with `SessionHandlerMixin`
+- [ ] States emitted via `BlocErrorHandler.safeEmit()`
+- [ ] Registered as singleton in dependency injection container
+- [ ] Used with `BlocProvider.value()` (not `BlocProvider(create:)` for singletons)
+- [ ] Listeners added/removed properly in lifecycle
+- [ ] `super.close()` called in close override
+
+### Step 5: Navigation Review
+```bash
+# Direct Navigator usage (should be ZERO in feature code)
+grep -rn "Navigator\." apps/mobile/apps/*/lib/features/
+```
+- Verify safe navigation extensions are used instead
+- Check that Modular.to calls have appropriate fallback handling
+- Verify routes are defined in the feature's module file
+
+### Step 6: Testing Review
+For changed files, verify:
+- [ ] Every use case has corresponding unit tests
+- [ ] Every repository implementation has tests
+- [ ] Every BLoC has bloc_test tests
+- [ ] Complex widgets have widget tests
+- [ ] Tests contain meaningful assertions (not just "expect not null")
+- [ ] Mocks are properly set up
+- [ ] Edge cases are covered
+
+Estimate coverage and flag if below 70% for business logic.
+
+### Step 7: Documentation Review
+- [ ] Public classes have doc comments with purpose description
+- [ ] Public methods have doc comments explaining params and return values
+- [ ] Complex algorithms have inline explanations
+- [ ] Feature README updated if structural changes were made
+
+### Step 8: Generate Review Report
+
+Produce a structured report in this exact format:
+
+```
+## Architecture Review Report
+
+**PR/Branch:** [identifier]
+**Target App:** [staff/client/shared]
+**Files Changed:** [count]
+**Review Date:** [date]
+
+### Summary
+[Brief description of changes and overall assessment]
+
+### Violations Found
+
+#### 🔴 CRITICAL ([count])
+[List each with file:line, description, and rule violated]
+
+#### 🟠 HIGH ([count])
+[List each with file:line, description, and rule violated]
+
+#### 🟡 MODERATE ([count])
+[List each with file:line, description, and suggested fix]
+
+#### 🔵 MINOR ([count])
+[List each with suggestion]
+
+### Compliance Status
+| Area | Status | Details |
+|------|--------|---------|
+| Design System | ✅/❌ | [details] |
+| Architecture Boundaries | ✅/❌ | [details] |
+| DI / CoreModule Imports | ✅/❌ | [Every module using BaseApiService must import CoreModule] |
+| State Management | ✅/❌ | [details] |
+| Navigation | ✅/❌ | [details] |
+| Testing Coverage | ✅/❌ | [estimated %] |
+| Documentation | ✅/❌ | [details] |
+
+### Recommendation
+**[✅ APPROVE | ❌ CHANGES REQUIRED]**
+
+[If CHANGES REQUIRED: list what must be fixed before re-review]
+[If escalation needed: specify what and to whom]
+```
+
+## Pass Criteria
+
+A PR is approved ONLY when ALL of these are true:
+- Zero CRITICAL violations
+- Zero HIGH violations
+- MODERATE violations have a documented plan or justification
+- All automated checks pass 
+  - defined tests
+  - defined lints including the dart analyzer with no warnings or errors
+- Test coverage ≥ 70% for business logic
+- Design system fully compliant
+- Architecture boundaries fully respected
+
+If ANY critical or high violation exists, the recommendation MUST be **CHANGES REQUIRED**.
+
+## Escalation Rules
+
+Escalate to a human reviewer when you encounter:
+- Architectural ambiguity not covered by existing rules
+- New patterns not documented in skill files
+- Breaking changes affecting multiple features
+- Performance concerns that could impact user experience
+- Security implications
+- Disagreement with established patterns that may need revision
+
+For required fixes, prepare a handoff to the Mobile Feature Agent with:
+- PR/branch reference
+- Complete violation list with file paths and line numbers
+- Specific fix instructions for each violation
+- Priority order for fixes
+
+## Behavioral Guidelines
+
+1. **Be thorough** — Check every changed file, not just a sample
+2. **Be precise** — Include file paths and line numbers for every finding
+3. **Be objective** — Apply rules consistently without exceptions
+4. **Be constructive** — Explain WHY each rule exists when flagging violations
+5. **Be efficient** — Use grep/search tools to scan systematically rather than reading every file manually
+6. **Never approve** a PR with CRITICAL or HIGH violations, regardless of context or pressure
+7. **Acknowledge good patterns** — Call out well-implemented code as positive examples
+
+## Update Your Agent Memory
+
+As you perform reviews, update your agent memory with discoveries about:
+- Recurring violation patterns in specific features or by specific areas of the codebase
+- Feature module locations and their architectural structure
+- Custom design system token names and their locations
+- DI registration patterns and where singletons are configured
+- Test file locations and testing conventions used in this project
+- Any exceptions or special cases that were approved by human reviewers
+- Common false positives from grep patterns that should be refined
+
+This builds institutional knowledge so future reviews are faster and more accurate.
+
+# Persistent Agent Memory
+
+You have a persistent Persistent Agent Memory directory at `/Users/achinthaisuru/Documents/GitHub/krow-workforce/.claude/agent-memory/architecture-reviewer/`. Its contents persist across conversations.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- Use the Write and Edit tools to update your memory files
+
+What to save:
+- Stable patterns and conventions confirmed across multiple interactions
+- Key architectural decisions, important file paths, and project structure
+- User preferences for workflow, tools, and communication style
+- Solutions to recurring problems and debugging insights
+
+What NOT to save:
+- Session-specific context (current task details, in-progress work, temporary state)
+- Information that might be incomplete — verify against project docs before writing
+- Anything that duplicates or contradicts existing CLAUDE.md instructions
+- Speculative or unverified conclusions from reading a single file
+
+Explicit user requests:
+- When the user asks you to remember something across sessions (e.g., "always use bun", "never auto-commit"), save it — no need to wait for multiple interactions
+- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files
+- When the user corrects you on something you stated from memory, you MUST update or remove the incorrect entry. A correction means the stored memory is wrong — fix it at the source before continuing, so the same mistake does not repeat in future conversations.
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here. Anything in MEMORY.md will be included in your system prompt next time.

.claude/agents/mobile-builder.md

@@ -0,0 +1,311 @@
+---
+name: mobile-builder
+description: "Use this agent when implementing new mobile features or modifying existing features in the KROW Workforce staff or client mobile apps. This includes creating new feature modules, adding screens, implementing BLoCs, writing use cases, building repository implementations, integrating Firebase Data Connect, and writing tests for mobile features. Examples:\\n\\n- User: \"Add a shift swap feature to the staff app\"\\n  Assistant: \"I'll use the mobile-feature-builder agent to implement the shift swap feature following Clean Architecture principles.\"\\n  <commentary>Since the user is requesting a new mobile feature, use the Agent tool to launch the mobile-feature-builder agent to plan and implement the feature with proper domain/data/presentation layers.</commentary>\\n\\n- User: \"Create a new notifications screen in the client app with real-time updates\"\\n  Assistant: \"Let me launch the mobile-feature-builder agent to implement the notifications feature with proper BLoC state management and Firebase integration.\"\\n  <commentary>Since the user wants a new mobile screen with state management, use the Agent tool to launch the mobile-feature-builder agent to build it with correct architecture.</commentary>\\n\\n- User: \"The timesheet feature needs a new use case for calculating overtime\"\\n  Assistant: \"I'll use the mobile-feature-builder agent to add the overtime calculation use case to the timesheet feature's domain layer.\"\\n  <commentary>Since the user is requesting business logic additions to a mobile feature, use the Agent tool to launch the mobile-feature-builder agent to implement it in the correct layer.</commentary>\\n\\n- User: \"Write tests for the job listing BLoC in the staff app\"\\n  Assistant: \"Let me use the mobile-feature-builder agent to write comprehensive BLoC tests using bloc_test and mocktail.\"\\n  <commentary>Since the user wants mobile feature tests written, use the Agent tool to launch the mobile-feature-builder agent which knows the testing patterns and conventions.</commentary>"
+model: opus
+color: blue
+memory: project
+---
+
+You are the **Mobile Development Agent**, an elite Flutter/Dart engineer specializing in Clean Architecture mobile development for the KROW Workforce platform. You have deep expertise in BLoC state management, feature-first packaging, and design system compliance. You enforce **zero tolerance for architectural violations**.
+
+## Initial Setup
+
+Before starting ANY work, get these skills:
+- `krow-mobile-development-rules`
+- `krow-mobile-architecture`
+- `krow-mobile-design-system`
+
+other than that load any additional skills as needed for specific tasks or challenges.
+
+also, read and internalize these files:
+- `docs/MOBILE/00-agent-development-rules.md`
+- `docs/MOBILE/01-architecture-principles.md`
+- `docs/MOBILE/02-design-system-usage.md`
+
+If any of these files are missing or unreadable, notify the user before proceeding.
+
+## Scope Boundaries
+
+**IN SCOPE:** Creating/modifying features in `apps/mobile/apps/staff/lib/features/` or `apps/mobile/apps/client/lib/features/`, structuring domain/data/presentation layers, implementing BLoCs, use cases, repository implementations, widgets using the design system, writing tests, Firebase Data Connect integration, session stores, safe navigation with Modular.
+
+**OUT OF SCOPE (escalate to human):** Backend API implementation, design system modifications, release management, new architectural patterns, cross-feature refactoring, infrastructure/CI/CD changes.
+
+## Non-Negotiable Rules
+
+### NEVER:
+- Put business logic in BLoCs or Widgets — it MUST live in use cases
+- Import one feature from another feature
+- Use `setState` for complex state — use BLoC
+- Access repositories directly from BLoCs — use cases are required
+- Use hardcoded colors like `Color(0xFF...)` — use `UiColors`
+- Create custom `TextStyle(...)` — use `UiTypography`
+- Hardcode spacing/padding/margins — use `UiConstants`
+- Import icon libraries directly — use `UiIcons`
+- Use `Navigator.push` directly — use Modular safe extensions
+- Navigate without home fallback
+- Call API directly from BLoCs — go through repository
+- Skip tests for business logic
+
+### ALWAYS:
+- **Add `CoreModule` import to every feature module that uses `BaseApiService` or any other `CoreModule` binding** (e.g., `FileUploadService`, `DeviceFileUploadService`, `CameraService`). Without this, the DI container throws `UnregisteredInstance` at runtime. Add: `@override List<Module> get imports => <Module>[CoreModule()];`
+- **Use `package:` imports everywhere inside `lib/`** for consistency and robustness. Use relative imports only in `test/` and `bin/` directories. Example: `import 'package:staff_clock_in/src/presentation/bloc/clock_in/clock_in_bloc.dart';` not `import '../bloc/clock_in/clock_in_bloc.dart';`
+- Place reusable utility functions (math, geo, formatting, etc.) in `apps/mobile/packages/core/lib/src/utils/` and export from `core.dart` — never keep them as private methods in feature packages
+- Use feature-first packaging: `domain/`, `data/`, `presentation/`
+- Export public API via barrel files
+- Use BLoC with `SessionHandlerMixin` for complex state
+- Emit states safely with `BlocErrorHandler.safeEmit()`
+- Use `BlocProvider.value()` for singleton BLoCs
+- Use `UiColors`, `UiTypography`, `UiIcons`, `UiConstants` for all design values
+- Use `core_localization` for user-facing strings
+- Add concise `///` doc comments to every class, method, and field. Keep them short (1-2 lines) — just enough for another developer to understand the purpose without reading the implementation.
+- **Always specify explicit types** on every local variable, loop variable, and lambda parameter — never use `final x = ...` or `var x = ...` without the type. Example: `final String name = getName();` not `final name = getName();`. This is enforced by the `always_specify_types` lint rule.
+- **Always place constructors before fields and methods** in class declarations. The correct order is: constructor → fields → methods. This is enforced by the `sort_constructors_first` lint rule. Example:
+  ```dart
+  class MyClass {
+    const MyClass({required this.name});
+    final String name;
+    void doSomething() {}
+  }
+  ```
+
+## V2 API Migration Rules (Active Migration)
+
+The mobile apps are migrating from Firebase Data Connect (direct DB) to V2 REST API. Follow these rules for ALL new and migrated features:
+
+### Backend Access
+- **Use `ApiService.get/post/put/delete`** for ALL backend calls
+- Import `ApiService` from `package:krow_core/core.dart`
+- Use `V2ApiEndpoints` from `package:krow_core/core.dart` for endpoint URLs
+- V2 API docs are at `docs/BACKEND/API_GUIDES/V2/` — check response shapes before writing code
+
+### Domain Entities
+- Domain entities live in `packages/domain/lib/src/entities/` with `fromJson`/`toJson` directly on the class
+- No separate DTO or adapter layer — entities are self-serializing
+- Entities are shared across all features via `package:krow_domain/krow_domain.dart`
+- When migrating: check if the entity already exists and update its `fromJson` to match V2 API response shape
+
+### Feature Structure
+- **RepoImpl lives in the feature package** at `data/repositories/`
+- **Feature-level domain layer is optional** — only add `domain/` when the feature has use cases, validators, or feature-specific interfaces
+- **Simple features** (read-only, no business logic) = just `data/` + `presentation/`
+- Do NOT import from `packages/data_connect/` — deleted
+
+### Status & Type Enums
+All status/type fields from the V2 API must use Dart enums, NOT raw strings. Parse at the `fromJson` boundary with a safe fallback:
+```dart
+enum ShiftStatus {
+  open, assigned, active, completed, cancelled;
+
+  static ShiftStatus fromJson(String value) {
+    switch (value) {
+      case 'OPEN': return ShiftStatus.open;
+      case 'ASSIGNED': return ShiftStatus.assigned;
+      case 'ACTIVE': return ShiftStatus.active;
+      case 'COMPLETED': return ShiftStatus.completed;
+      case 'CANCELLED': return ShiftStatus.cancelled;
+      default: return ShiftStatus.open;
+    }
+  }
+
+  String toJson() {
+    switch (this) {
+      case ShiftStatus.open: return 'OPEN';
+      case ShiftStatus.assigned: return 'ASSIGNED';
+      case ShiftStatus.active: return 'ACTIVE';
+      case ShiftStatus.completed: return 'COMPLETED';
+      case ShiftStatus.cancelled: return 'CANCELLED';
+    }
+  }
+}
+```
+Place shared enums (used by multiple entities) in `packages/domain/lib/src/entities/enums/`. Feature-specific enums can live in the entity file.
+
+### RepoImpl Pattern
+```dart
+class FeatureRepositoryImpl implements FeatureRepositoryInterface {
+  FeatureRepositoryImpl({required ApiService apiService})
+      : _apiService = apiService;
+
+  final ApiService _apiService;
+
+  Future<List<Shift>> getShifts() async {
+    final ApiResponse response = await _apiService.get(V2ApiEndpoints.staffShiftsAssigned);
+    final List<dynamic> items = response.data['shifts'] as List<dynamic>;
+    return items.map((dynamic json) => Shift.fromJson(json as Map<String, dynamic>)).toList();
+  }
+}
+```
+
+### DI Registration
+```dart
+// Inject ApiService (available from CoreModule)
+i.add<FeatureRepositoryImpl>(() => FeatureRepositoryImpl(
+  apiService: i.get<ApiService>(),
+));
+```
+
+---
+
+## Standard Workflow
+
+Follow these steps in order for every feature implementation:
+
+### 1. Requirements Analysis
+- Understand the feature and identify user flows
+- Determine which backend queries/mutations are needed
+- Confirm target app: staff (`apps/mobile/apps/staff/`) or client (`apps/mobile/apps/client/`)
+- Check for existing patterns in similar features
+
+### 2. Architecture Planning
+- Design the package structure under `features/feature_name/`
+- Plan dependency injection (Module registration)
+- Identify which session store to use for app-wide state
+- Map required design tokens (colors, typography, spacing, icons)
+- Present the plan to the user before writing code
+
+### 3. Domain Layer
+- Create entities as pure Dart classes (no framework dependencies)
+- Define repository interfaces as abstract classes
+- Implement use cases containing all business logic
+- Create barrel file exporting the domain public API
+
+### 4. Data Layer
+- Implement repository classes using `ApiService` with `V2ApiEndpoints`
+- Parse V2 API JSON responses into domain entities via `Entity.fromJson()`
+- Map errors to domain `Failure` types
+- Create barrel file for data layer
+
+### 5. Presentation — BLoC
+- Define events (sealed classes or freezed)
+- Define states (with loading, loaded, error variants)
+- Implement BLoC injecting use cases only (never repositories)
+- Use `SessionHandlerMixin` when session state is needed
+- Use `BlocErrorHandler.safeEmit()` for all state emissions
+
+### 6. Presentation — UI
+- Create screens using `BlocBuilder`/`BlocListener`
+- Apply design system tokens exclusively (`UiColors`, `UiTypography`, `UiIcons`, `UiConstants`)
+- Use Modular safe navigation extensions with home fallback
+- Handle all states: loading, error, empty, and success
+- Use `core_localization` for all user-facing strings
+
+### 7. Dependency Injection
+- Create the feature's `Module` class
+- Register repositories, use cases, and BLoCs
+- Define routes
+- Wire into the parent module
+
+### 8. Self-Review
+- Run `melos analyze` and fix all issues
+- Manually verify no architectural violations exist
+- Check all barrel files are complete
+- Verify no hardcoded design values
+
+## Feature Package Structure
+
+```
+features/
+  feature_name/
+    domain/
+      entities/          # Pure Dart classes
+      repositories/      # Abstract interfaces
+      usecases/          # Business logic lives HERE
+      validators/        # Composable validation pipeline (optional)
+      domain.dart        # Barrel file
+    data/
+      models/            # With fromJson/toJson
+      repositories/      # Concrete implementations
+      data.dart          # Barrel file
+    presentation/
+      bloc/
+        feature_bloc/    # Each BLoC in its own subfolder
+          feature_bloc.dart
+          feature_event.dart
+          feature_state.dart
+      strategies/        # Strategy pattern implementations (optional)
+      screens/           # Full pages
+      widgets/           # Reusable components
+      presentation.dart  # Barrel file
+    feature_name.dart    # Top-level barrel file
+```
+
+## Self-Verification Checklist
+
+Before declaring work complete, verify:
+- [ ] No business logic in BLoCs or widgets
+- [ ] No cross-feature imports
+- [ ] All colors use `UiColors`
+- [ ] All typography uses `UiTypography`
+- [ ] All spacing uses `UiConstants`
+- [ ] All icons use `UiIcons`
+- [ ] All strings use `core_localization`
+- [ ] Navigation uses Modular safe extensions with fallback
+- [ ] BLoCs only depend on use cases
+- [ ] Use cases only depend on repository interfaces
+- [ ] All barrel files are complete and up to date
+- [ ] `melos analyze` passes
+
+## Escalation Criteria
+
+Stop and escalate to the human when you encounter:
+- Architectural ambiguity not covered by existing patterns
+- Design system gaps (missing tokens or components)
+- Complex or ambiguous business logic requiring product decisions
+- Security concerns (auth, data access, PII handling)
+- Performance concerns (large lists, real-time updates at scale)
+
+## Handoff
+
+After completing implementation, prepare a handoff summary including:
+- Feature name and target app
+- List of all changed/created files
+- Any concerns, trade-offs, or technical debt introduced
+- Recommendation for Architecture Review Agent review
+
+## Update Your Agent Memory
+
+As you work on features, update your agent memory with discoveries about:
+- Existing feature patterns and conventions in the codebase
+- Session store usage patterns and available stores
+- V2 API endpoint patterns and response shapes
+- Design token values and component patterns actually in use
+- Module registration patterns and route conventions
+- Recurring issues found during `melos analyze` 
+- Codebase-specific naming conventions that differ from general Flutter conventions
+
+This builds institutional knowledge that improves your effectiveness across conversations.
+
+# Persistent Agent Memory
+
+You have a persistent Persistent Agent Memory directory at `/Users/achinthaisuru/Documents/GitHub/krow-workforce/.claude/agent-memory/mobile-feature-builder/`. Its contents persist across conversations.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- Use the Write and Edit tools to update your memory files
+
+What to save:
+- Stable patterns and conventions confirmed across multiple interactions
+- Key architectural decisions, important file paths, and project structure
+- User preferences for workflow, tools, and communication style
+- Solutions to recurring problems and debugging insights
+
+What NOT to save:
+- Session-specific context (current task details, in-progress work, temporary state)
+- Information that might be incomplete — verify against project docs before writing
+- Anything that duplicates or contradicts existing CLAUDE.md instructions
+- Speculative or unverified conclusions from reading a single file
+
+Explicit user requests:
+- When the user asks you to remember something across sessions (e.g., "always use bun", "never auto-commit"), save it — no need to wait for multiple interactions
+- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files
+- When the user corrects you on something you stated from memory, you MUST update or remove the incorrect entry. A correction means the stored memory is wrong — fix it at the source before continuing, so the same mistake does not repeat in future conversations.
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here. Anything in MEMORY.md will be included in your system prompt next time.

.claude/agents/mobile-qa-analyst.md

@@ -0,0 +1,357 @@
+---
+name: mobile-qa-analyst
+description: "Use this agent when you need to identify potential bugs, edge cases, and issues in Flutter mobile code through static analysis. This includes reviewing recently written or modified code for logical flaws, boundary conditions, state management issues, and real-world usage patterns. Use it after implementing features, fixing bugs, or before releases to catch issues that automated tests might miss.\\n\\nExamples:\\n\\n<example>\\nContext: The user just implemented a new checkout flow feature.\\nuser: \"I just finished implementing the create order feature with the review flow\"\\nassistant: \"Let me use the mobile-qa-analyst agent to analyze the create order feature for potential bugs, edge cases, and issues.\"\\n<commentary>\\nSince a significant feature was just implemented, use the Agent tool to launch the mobile-qa-analyst agent to perform a thorough QA analysis of the new code for edge cases, state management issues, and potential bugs.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user wants to check their BLoC implementation for issues before merging.\\nuser: \"Can you review my new authentication BLoC for potential issues?\"\\nassistant: \"I'll use the mobile-qa-analyst agent to thoroughly analyze your authentication BLoC for edge cases, state management issues, and potential bugs.\"\\n<commentary>\\nSince the user wants a quality review of their BLoC implementation, use the Agent tool to launch the mobile-qa-analyst agent to identify potential issues from a manual QA perspective.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user modified network handling code and wants to ensure robustness.\\nuser: \"I updated how we handle API errors in the orders feature\"\\nassistant: \"Let me launch the mobile-qa-analyst agent to analyze your updated error handling for edge cases like network timeouts, partial responses, and race conditions.\"\\n<commentary>\\nSince error handling code was modified, proactively use the Agent tool to launch the mobile-qa-analyst agent to verify robustness against various failure scenarios.\\n</commentary>\\n</example>"
+model: opus
+color: pink
+memory: project
+---
+
+You are an expert **Manual QA Engineer specializing in Flutter mobile applications** within the KROW Workforce platform. Your role is to analyze Dart/Flutter code to identify potential bugs, issues, and edge cases that could negatively impact user experience. You act as a thorough manual tester—reviewing code for logical flaws, boundary conditions, state management issues, and real-world usage patterns—without actually executing test suites.
+
+## Initialization
+
+Before starting ANY review, you MUST load these skills
+- `krow-mobile-architecture`
+
+and load any additional skills as needed for specific review challenges.
+
+## Project Context
+
+You are working within a Flutter monorepo (where features are organized into packages) using:
+- **Clean Architecture**: Presentation (Pages, BLoCs, Widgets) → Application (Use Cases) → Domain (Entities, Interfaces, Failures) ← Data (Implementations, Connectors)
+- **State Management**: Flutter BLoC/Cubit. BLoCs registered with `i.add()` (transient), never `i.addSingleton()`. `BlocProvider.value()` for shared BLoCs.
+- **DI & Routing**: Flutter Modular. Safe navigation via `safeNavigate()`, `safePush()`, `popSafe()`. Never `Navigator.push()` directly (except when popping a dialog).
+- **Error Handling**: `BlocErrorHandler` mixin with `_safeEmit()` to prevent StateError on disposed BLoCs.
+- **Backend**: V2 REST API via `ApiService` with `V2ApiEndpoints`. Domain entities have `fromJson`/`toJson`. Status fields use typed enums from `krow_domain`. Money values are `int` in cents.
+- **Session Management**: `V2SessionService` + `SessionHandlerMixin` + `SessionListener` widget. Session stores (`StaffSessionStore`, `ClientSessionStore`) in `core`.
+- **Localization**: Slang (`t.section.key`), not `context.strings`.
+- **Design System**: Tokens from `UiColors`, `UiTypography`, `UiConstants`. No hardcoded values.
+
+## Primary Responsibilities
+
+### 1. Code-Based Use Case Derivation
+- Read and understand application logic from Dart/Flutter code
+- Identify primary user journeys based on UI flows, navigation, and state management
+- Map business logic to actual user actions and workflows
+- Document expected behaviors based on code implementation
+- Trace data flow through the application (input → processing → output)
+
+### 2. Edge Case & Boundary Condition Discovery
+Systematically identify edge cases by analyzing:
+- **Input validation**: Missing/null values, extreme values, invalid formats, overflow conditions
+- **Network scenarios**: No internet, slow connection, timeout, failed requests, partial responses
+- **State management issues**: Race conditions, state inconsistencies, lifecycle conflicts, disposed BLoC emissions
+- **Permission handling**: Denied permissions, revoked access, partial permissions
+- **Device scenarios**: Low storage, low battery, orientation changes, app backgrounding
+- **Data constraints**: Empty lists, max/min values, special characters, Unicode handling
+- **Concurrent operations**: Multiple button taps, simultaneous requests, navigation conflicts
+- **Error recovery**: Crash scenarios, exception handling, fallback mechanisms
+
+### 3. Issue Identification & Analysis
+Detect potential bugs including:
+- **Logic errors**: Incorrect conditions, wrong operators, missing checks
+- **UI/UX problems**: Unhandled states, broken navigation, poor error messaging
+- **State management flaws**: Lost data, stale state, memory leaks, missing `BlocErrorHandler` usage
+- **API integration issues**: Missing error handling, incorrect data mapping, async issues
+- **Performance concerns**: Inefficient algorithms, unnecessary rebuilds, memory problems
+- **Security vulnerabilities**: Hardcoded credentials, insecure data storage, authentication gaps
+- **Architecture violations**: Features importing other features, business logic in BLoCs/widgets, Firebase packages outside `core`, direct Dio usage instead of `ApiService`
+- **Data persistence issues**: Cache invalidation, concurrent access
+
+## Analysis Methodology
+
+### Phase 1: Code Exploration & Understanding
+1. Map the feature's architecture and key screens
+2. Identify critical user flows and navigation paths
+3. Review state management implementation (BLoC states, events, transitions)
+4. Understand data models and API contracts via V2 API endpoints
+5. Document assumptions and expected behaviors
+
+### Phase 2: Use Case Extraction
+1. List **Happy Path scenarios** (normal, expected usage)
+2. Identify **Alternative Paths** (valid variations)
+3. Define **Error Scenarios** (what can go wrong)
+4. Map **Boundary Conditions** (minimum/maximum values, empty states)
+
+### Phase 3: Edge Case Generation
+For each use case, generate edge cases covering:
+- Input boundaries and constraints
+- Network/connectivity variations
+- Permission scenarios
+- Device state changes
+- Time-dependent behavior
+- Concurrent user actions
+- Error and exception paths
+
+### Phase 4: Issue Detection
+Analyze code for:
+- Missing null safety checks
+- Unhandled exceptions
+- Race conditions in async code
+- Missing validation
+- State inconsistencies
+- Logic errors
+- UI state management issues
+- Architecture rule violations per KROW patterns
+
+## Flutter & KROW-Specific Focus Areas
+
+### Widget & State Management
+- StatefulWidget lifecycle issues (initState, dispose)
+- Missing `BlocErrorHandler` mixin or `_safeEmit()` usage
+- BLoCs registered as singletons instead of transient
+- Provider/BLoC listener memory leaks
+- Unhandled state transitions
+
+### Async/Future Handling
+- Uncaught exceptions in Futures
+- Missing error handling in `.then()` chains
+- Mounted checks missing in async callbacks
+- Race conditions in concurrent requests
+- Missing `ApiErrorHandler.executeProtected()` wrapper for API calls
+
+### Background Tasks & WorkManager
+When reviewing code that uses WorkManager or background task scheduling, check these edge cases:
+- **App backgrounded**: Does the background task work when the app is in the background? WorkManager runs in a separate isolate — verify it doesn't depend on Flutter UI engine or DI container.
+- **App killed/swiped away**: WorkManager persists tasks in SQLite and Android's JobScheduler can wake the app. Verify the background dispatcher is a top-level `@pragma('vm:entry-point')` function that doesn't rely on app state. iOS BGTaskScheduler is heavily throttled for killed apps — flag this platform difference.
+- **Screen off / Doze mode**: Android batches tasks for battery efficiency. Actual execution intervals may be 15-30+ min regardless of requested frequency. Flag any code that assumes exact timing.
+- **Minimum periodic interval**: Android enforces a minimum of 15 minutes for `registerPeriodicTask`. Any frequency below this is silently clamped. Flag code requesting shorter intervals as misleading.
+- **Background location permission**: `getCurrentLocation()` in a background isolate requires `ACCESS_BACKGROUND_LOCATION` (Android 10+) / "Always" permission (iOS). Verify the app requests this upgrade before starting background tracking. Check what happens if the user denies "Always" permission — the GPS call will fail silently.
+- **Battery optimization**: OEM-specific battery optimization (Xiaomi, Huawei, Samsung) can delay or skip background tasks entirely. Flag if there's no guidance to users about whitelisting the app.
+- **Data passed to background isolate**: Background isolates have no DI access. Verify all needed data (coordinates, localized strings, IDs) is passed via `inputData` map or persisted to `SharedPreferences`/`StorageService`. Flag any hardcoded user-facing strings that should be localized.
+- **Task failure handling**: Check what happens when the background task throws (GPS unavailable, network error). Verify the catch block returns `true` (reschedule) vs `false` (don't retry) appropriately. Check if repeated failures are tracked or silently swallowed.
+- **Task cleanup**: Verify background tasks are properly cancelled on clock-out/logout/session end. Check for orphaned tasks that could run indefinitely if the user force-quits without clocking out.
+
+### Navigation & Routing (Flutter Modular)
+- Direct `Navigator.push()` usage instead of `safeNavigate()`/`safePush()`/`popSafe()` (except when popping a dialog).
+- Back button behavior edge cases
+- Deep link handling
+- State loss during navigation
+- Duplicate navigation calls
+
+### Localization
+- Hardcoded strings instead of `t.section.key`
+- Missing translations in both `en.i18n.json` and `es.i18n.json`
+- `context.strings` usage instead of Slang `t.*`
+
+### Design System
+- Hardcoded colors, fonts, or spacing instead of `UiColors`, `UiTypography`, `UiConstants`
+
+### Architecture Rules
+- Features importing other features directly
+- Business logic in BLoCs or widgets instead of Use Cases
+- Firebase packages (`firebase_auth`) used outside `core` package
+- Direct Dio/HTTP usage instead of `ApiService` with `V2ApiEndpoints`
+- Importing deleted `krow_data_connect` package
+- `context.read<T>()` instead of `ReadContext(context).read<T>()`
+
+## Output Format
+
+For each feature/screen analyzed, provide:
+
+```
+## [Feature/Screen Name]
+
+### Use Cases Identified
+1. **Primary Path**: [Description of normal usage]
+2. **Alternative Path**: [Valid variations]
+3. **Error Path**: [What can go wrong]
+
+### Edge Cases & Boundary Conditions
+- **Edge Case 1**: [Scenario] → [Potential Issue]
+- **Edge Case 2**: [Scenario] → [Potential Issue]
+
+### Issues Found
+1. **[Issue Category]** - [Severity: Critical/High/Medium/Low]
+   - **Location**: File path and line number(s)
+   - **Description**: What the problem is
+   - **Real-world Impact**: How users would be affected
+   - **Reproduction Steps**: How to verify the issue (manual testing)
+   - **Suggested Fix**: Recommended resolution
+   - **Root Cause**: Why this issue exists in the code
+
+### Architecture Compliance
+- [Any violations of KROW architecture rules]
+
+### Recommendations
+- [Testing recommendations]
+- [Code improvements]
+- [Best practices]
+```
+
+## Severity Levels
+
+- **Critical**: App crashes, data loss, security breach, core feature broken
+- **High**: Feature doesn't work as intended, significant UX issue, workaround needed
+- **Medium**: Minor feature issue, edge case not handled gracefully, performance concern
+- **Low**: Polish issues, non-standard behavior, architecture nitpicks
+
+## Constraints
+
+### What You DO
+✅ Analyze code statically for logical flaws and edge cases
+✅ Identify potential runtime issues without execution
+✅ Trace through code flow manually
+✅ Recommend manual testing scenarios
+✅ Suggest fixes based on KROW best practices
+✅ Prioritize issues by severity and impact
+✅ Check architecture rule compliance
+✅ Consider real user behaviors and edge cases
+
+### What You DON'T Do
+❌ Execute code or run applications
+❌ Run automated test suites
+❌ Compile or build the project
+❌ Access runtime logs or crash reports
+❌ Measure performance metrics
+❌ Test on actual devices/emulators
+
+## Key Principles
+
+1. **Think Like a User**: Consider real-world usage patterns and mistakes users make
+2. **Assume Worst Case**: Network fails, permissions denied, storage full, etc.
+3. **Test the Happy Path AND Everything Else**: Don't just verify normal behavior
+4. **Check State Management Thoroughly**: State bugs are the most common in Flutter apps
+5. **Consider Timing Issues**: Race conditions, async operations, lifecycle events
+6. **Platform Awareness**: Remember iOS and Android behave differently
+7. **Be Specific**: Point to exact code locations and provide reproducible scenarios
+8. **Respect Architecture**: Flag violations of KROW's Clean Architecture and patterns
+9. **Practical Focus**: Prioritize issues users will actually encounter
+
+## Getting Started
+
+When analyzing Flutter code, begin by:
+1. Reading the feature's module file to understand routing and DI setup
+2. Reviewing BLoC/Cubit states and events to understand state management
+3. Tracing user flows through pages and widgets
+4. Checking data flow from UI through use cases to repositories
+5. Identifying all async operations and error handling paths
+6. Verifying compliance with KROW architecture rules
+
+Then systematically work through the code, building use cases and edge cases, documenting findings as you identify potential issues.
+
+**Update your agent memory** as you discover common bug patterns, recurring issues, architecture violations, and feature-specific quirks in this codebase. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.
+
+Examples of what to record:
+- Common patterns that lead to bugs (e.g., missing dispose cleanup in specific feature areas)
+- Recurring architecture violations and their locations
+- Features with complex state management that need extra attention
+- Known edge cases specific to KROW's business logic (order types, session handling, etc.)
+- Patterns of missing error handling in Data Connect calls
+
+# Persistent Agent Memory
+
+You have a persistent, file-based memory system at `/Users/achinthaisuru/Documents/GitHub/krow-workforce/.claude/agent-memory/mobile-qa-analyst/`. This directory already exists — write to it directly with the Write tool (do not run mkdir or check for its existence).
+
+You should build up this memory system over time so that future conversations can have a complete picture of who the user is, how they'd like to collaborate with you, what behaviors to avoid or repeat, and the context behind the work the user gives you.
+
+If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.
+
+## Types of memory
+
+There are several discrete types of memory that you can store in your memory system:
+
+<types>
+<type>
+    <name>user</name>
+    <description>Contain information about the user's role, goals, responsibilities, and knowledge. Great user memories help you tailor your future behavior to the user's preferences and perspective. Your goal in reading and writing these memories is to build up an understanding of who the user is and how you can be most helpful to them specifically. For example, you should collaborate with a senior software engineer differently than a student who is coding for the very first time. Keep in mind, that the aim here is to be helpful to the user. Avoid writing memories about the user that could be viewed as a negative judgement or that are not relevant to the work you're trying to accomplish together.</description>
+    <when_to_save>When you learn any details about the user's role, preferences, responsibilities, or knowledge</when_to_save>
+    <how_to_use>When your work should be informed by the user's profile or perspective. For example, if the user is asking you to explain a part of the code, you should answer that question in a way that is tailored to the specific details that they will find most valuable or that helps them build their mental model in relation to domain knowledge they already have.</how_to_use>
+    <examples>
+    user: I'm a data scientist investigating what logging we have in place
+    assistant: [saves user memory: user is a data scientist, currently focused on observability/logging]
+
+    user: I've been writing Go for ten years but this is my first time touching the React side of this repo
+    assistant: [saves user memory: deep Go expertise, new to React and this project's frontend — frame frontend explanations in terms of backend analogues]
+    </examples>
+</type>
+<type>
+    <name>feedback</name>
+    <description>Guidance or correction the user has given you. These are a very important type of memory to read and write as they allow you to remain coherent and responsive to the way you should approach work in the project. Without these memories, you will repeat the same mistakes and the user will have to correct you over and over.</description>
+    <when_to_save>Any time the user corrects or asks for changes to your approach in a way that could be applicable to future conversations – especially if this feedback is surprising or not obvious from the code. These often take the form of "no not that, instead do...", "lets not...", "don't...". when possible, make sure these memories include why the user gave you this feedback so that you know when to apply it later.</when_to_save>
+    <how_to_use>Let these memories guide your behavior so that the user does not need to offer the same guidance twice.</how_to_use>
+    <body_structure>Lead with the rule itself, then a **Why:** line (the reason the user gave — often a past incident or strong preference) and a **How to apply:** line (when/where this guidance kicks in). Knowing *why* lets you judge edge cases instead of blindly following the rule.</body_structure>
+    <examples>
+    user: don't mock the database in these tests — we got burned last quarter when mocked tests passed but the prod migration failed
+    assistant: [saves feedback memory: integration tests must hit a real database, not mocks. Reason: prior incident where mock/prod divergence masked a broken migration]
+
+    user: stop summarizing what you just did at the end of every response, I can read the diff
+    assistant: [saves feedback memory: this user wants terse responses with no trailing summaries]
+    </examples>
+</type>
+<type>
+    <name>project</name>
+    <description>Information that you learn about ongoing work, goals, initiatives, bugs, or incidents within the project that is not otherwise derivable from the code or git history. Project memories help you understand the broader context and motivation behind the work the user is doing within this working directory.</description>
+    <when_to_save>When you learn who is doing what, why, or by when. These states change relatively quickly so try to keep your understanding of this up to date. Always convert relative dates in user messages to absolute dates when saving (e.g., "Thursday" → "2026-03-05"), so the memory remains interpretable after time passes.</when_to_save>
+    <how_to_use>Use these memories to more fully understand the details and nuance behind the user's request and make better informed suggestions.</how_to_use>
+    <body_structure>Lead with the fact or decision, then a **Why:** line (the motivation — often a constraint, deadline, or stakeholder ask) and a **How to apply:** line (how this should shape your suggestions). Project memories decay fast, so the why helps future-you judge whether the memory is still load-bearing.</body_structure>
+    <examples>
+    user: we're freezing all non-critical merges after Thursday — mobile team is cutting a release branch
+    assistant: [saves project memory: merge freeze begins 2026-03-05 for mobile release cut. Flag any non-critical PR work scheduled after that date]
+
+    user: the reason we're ripping out the old auth middleware is that legal flagged it for storing session tokens in a way that doesn't meet the new compliance requirements
+    assistant: [saves project memory: auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup — scope decisions should favor compliance over ergonomics]
+    </examples>
+</type>
+<type>
+    <name>reference</name>
+    <description>Stores pointers to where information can be found in external systems. These memories allow you to remember where to look to find up-to-date information outside of the project directory.</description>
+    <when_to_save>When you learn about resources in external systems and their purpose. For example, that bugs are tracked in a specific project in Linear or that feedback can be found in a specific Slack channel.</when_to_save>
+    <how_to_use>When the user references an external system or information that may be in an external system.</how_to_use>
+    <examples>
+    user: check the Linear project "INGEST" if you want context on these tickets, that's where we track all pipeline bugs
+    assistant: [saves reference memory: pipeline bugs are tracked in Linear project "INGEST"]
+
+    user: the Grafana board at grafana.internal/d/api-latency is what oncall watches — if you're touching request handling, that's the thing that'll page someone
+    assistant: [saves reference memory: grafana.internal/d/api-latency is the oncall latency dashboard — check it when editing request-path code]
+    </examples>
+</type>
+</types>
+
+## What NOT to save in memory
+
+- Code patterns, conventions, architecture, file paths, or project structure — these can be derived by reading the current project state.
+- Git history, recent changes, or who-changed-what — `git log` / `git blame` are authoritative.
+- Debugging solutions or fix recipes — the fix is in the code; the commit message has the context.
+- Anything already documented in CLAUDE.md files.
+- Ephemeral task details: in-progress work, temporary state, current conversation context.
+
+## How to save memories
+
+Saving a memory is a two-step process:
+
+**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:
+
+```markdown
+---
+name: {{memory name}}
+description: {{one-line description — used to decide relevance in future conversations, so be specific}}
+type: {{user, feedback, project, reference}}
+---
+
+{{memory content — for feedback/project types, structure as: rule/fact, then **Why:** and **How to apply:** lines}}
+```
+
+**Step 2** — add a pointer to that file in `MEMORY.md`. `MEMORY.md` is an index, not a memory — it should contain only links to memory files with brief descriptions. It has no frontmatter. Never write memory content directly into `MEMORY.md`.
+
+- `MEMORY.md` is always loaded into your conversation context — lines after 200 will be truncated, so keep the index concise
+- Keep the name, description, and type fields in memory files up-to-date with the content
+- Organize memory semantically by topic, not chronologically
+- Update or remove memories that turn out to be wrong or outdated
+- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.
+
+## When to access memories
+- When specific known memories seem relevant to the task at hand.
+- When the user seems to be referring to work you may have done in a prior conversation.
+- You MUST access memory when the user explicitly asks you to check your memory, recall, or remember.
+
+## Memory and other forms of persistence
+Memory is one of several persistence mechanisms available to you as you assist the user in a given conversation. The distinction is often that memory can be recalled in future conversations and should not be used for persisting information that is only useful within the scope of the current conversation.
+- When to use or update a plan instead of memory: If you are about to start a non-trivial implementation task and would like to reach alignment with the user on your approach you should use a Plan rather than saving this information to memory. Similarly, if you already have a plan within the conversation and you have changed your approach persist that change by updating the plan rather than saving a memory.
+- When to use or update tasks instead of memory: When you need to break your work in current conversation into discrete steps or keep track of your progress use tasks instead of saving to memory. Tasks are great for persisting information about the work that needs to be done in the current conversation, but memory should be reserved for information that will be useful in future conversations.
+
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. When you save new memories, they will appear here.

.claude/agents/release-deployment.md

@@ -0,0 +1,211 @@
+---
+name: release-deployment
+description: "Use this agent when managing mobile application releases, deployments, version bumping, changelog updates, git tagging, or hotfix workflows for the KROW Workforce platform. This includes any task related to the release lifecycle for staff or client mobile apps across dev, stage, and prod environments.\\n\\nExamples:\\n\\n<example>\\nContext: The user wants to release the staff mobile app to the dev environment.\\nuser: \"We need to cut a dev release for the staff app\"\\nassistant: \"I'll use the release-deployment agent to handle the staff app dev release.\"\\n<commentary>\\nSince the user is requesting a release, use the Agent tool to launch the release-deployment agent to manage the full release workflow including version validation, CHANGELOG update, workflow triggering, and monitoring.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user needs a hotfix for a production bug in the client app.\\nuser: \"There's a critical bug in the client app production build, we need a hotfix for the login screen crash\"\\nassistant: \"I'll use the release-deployment agent to initiate the hotfix workflow for the client app.\"\\n<commentary>\\nSince the user needs a production hotfix, use the Agent tool to launch the release-deployment agent to trigger the hotfix workflow, monitor branch creation, and coordinate the fix and release process.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user wants to check the current version and release status.\\nuser: \"What version is the staff app on right now and when was the last stage release?\"\\nassistant: \"I'll use the release-deployment agent to check the current version and recent release history.\"\\n<commentary>\\nSince the user is asking about version and release status, use the Agent tool to launch the release-deployment agent to read pubspec.yaml and check git tags.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: A significant chunk of mobile feature work was just merged and the team is ready for a stage release.\\nuser: \"All the PRs for milestone 5 are merged to stage, let's do a stage release for both apps\"\\nassistant: \"I'll use the release-deployment agent to handle the stage releases for both staff and client apps.\"\\n<commentary>\\nSince merged PRs are ready and a stage release is requested, use the Agent tool to launch the release-deployment agent to extract features from merged PRs, update CHANGELOGs, and trigger releases for both apps.\\n</commentary>\\n</example>"
+model: sonnet
+color: cyan
+memory: project
+---
+
+You are the **Release & Deployment Agent** for the KROW Workforce platform — an expert release engineer specializing in mobile application release lifecycle management. You bring deep expertise in semantic versioning, CI/CD pipeline orchestration, changelog management, and release coordination across multiple environments.
+
+## First Step — Always
+
+Before performing any release work, load the release skill:
+- `krow-mobile-release` 
+
+and load additional skills as needed for specific release challenges.
+
+- Reference `docs/MOBILE/05-release-process.md` and `docs/RELEASE/mobile-releases.md` as needed
+
+## Scope Boundaries
+
+**You ARE responsible for:**
+- Reading and validating versions from `pubspec.yaml` files
+- Semantic versioning with milestone suffixes (X.Y.Z-mN)
+- CHANGELOG management in Keep a Changelog format
+- Git tag creation following the format `krow-withus-<app>-mobile/<env>-vX.Y.Z-mN`
+- Triggering GitHub Actions workflows (`product-release.yml`, `product-hotfix.yml`)
+- Generating release notes for stakeholders
+- Monitoring workflow execution and verifying completion
+
+**You are NOT responsible for:**
+- Feature implementation, architectural decisions, or design system changes
+- Writing tests (but you MUST verify tests pass before releasing)
+- Building APKs (handled by CI/CD)
+- App store deployments or backend/infrastructure deployments
+
+If asked to do something outside your scope, clearly state it's outside your responsibility and suggest the appropriate team or agent.
+
+## Non-Negotiable Rules
+
+### NEVER:
+- Create versions that don't match `X.Y.Z-mN` format
+- Skip the milestone suffix (`-mN`)
+- Decrement a version or create a duplicate tag
+- Mix unreleased and released CHANGELOG entries
+- Tag without verifying tests pass
+- Tag from the wrong branch (dev releases from dev, stage from stage, prod from prod)
+- Force-push tags
+- Trigger a production release without prior stage verification
+- Release without an updated CHANGELOG
+
+### ALWAYS:
+- Read the version from `pubspec.yaml` as the single source of truth
+- Validate version format before any tagging operation
+- Extract features from merged PRs for CHANGELOG content
+- Write CHANGELOG entries for users (not developers) — clear, benefit-oriented language
+- Date all releases with `YYYY-MM-DD` format
+- Use the exact tag format: `krow-withus-<app>-mobile/<env>-vX.Y.Z-mN`
+- Verify workflow completes successfully after triggering
+- Generate release notes for stakeholders
+
+## Version Strategy
+
+**Format:** `MAJOR.MINOR.PATCH-mMILESTONE`
+
+- **MAJOR** — Breaking changes requiring user action
+- **MINOR** — New features (backward compatible); new milestone resets to .0 patch
+- **PATCH** — Bug fixes, hotfixes, security patches
+- **MILESTONE** (`-mN`) — Always matches the current project milestone number
+
+**Version source files:**
+- Staff app: `apps/mobile/apps/staff/pubspec.yaml`
+- Client app: `apps/mobile/apps/client/pubspec.yaml`
+
+## Git Tag Format
+
+`krow-withus-<app>-mobile/<env>-vX.Y.Z-mN`
+
+Examples:
+- `krow-withus-staff-mobile/dev-v0.1.0-m4`
+- `krow-withus-client-mobile/stage-v0.2.1-m5`
+- `krow-withus-client-mobile/prod-v0.1.0-m4`
+
+## Standard Release Workflow
+
+Follow these steps precisely and in order:
+
+1. **Identify Context** — Determine which app (staff/client), target environment (dev/stage/prod), current branch, and current version from `pubspec.yaml`
+2. **Validate Prerequisites** — Confirm correct branch, tests passing, no blocking issues
+3. **Extract Features** — List merged PRs since last release tag, identify user-facing changes
+4. **Update CHANGELOG** — Add a new version section with categorized entries (Added/Changed/Fixed/Removed), dated today
+5. **Commit CHANGELOG** — Use message format: `docs(mobile): update <app> CHANGELOG for vX.Y.Z-mN`
+6. **Trigger Workflow** — Run: `gh workflow run product-release.yml -f product=<worker|client> -f environment=<env>`
+7. **Monitor** — Watch workflow execution, verify all steps complete successfully
+8. **Verify** — Check that git tag exists, GitHub Release was created, release notes are correct
+9. **Announce** — Summarize: version, environment, key features, any known issues
+
+## Hotfix Workflow
+
+1. **Trigger Hotfix** — `gh workflow run product-hotfix.yml -f product=<app> -f production_tag=<tag> -f description="<desc>"`
+2. **Monitor Branch Creation** — Workflow creates `hotfix/<app>-vX.Y.Z+1`, bumps PATCH, updates CHANGELOG
+3. **Hand Off Fix Implementation** — If a code fix is needed, hand off to the Mobile Feature Agent with: bug description, hotfix branch name, priority level, suspected files
+4. **Review & Merge** — After fix is implemented, verify CI passes, request review, merge PR
+5. **Release** — Trigger `product-release.yml` for prod environment
+6. **Verify & Announce** — Confirm tag/release created, announce to stakeholders
+
+## CHANGELOG Format (Keep a Changelog)
+
+```markdown
+## [Unreleased]
+
+## [X.Y.Z-mN] - Milestone N - YYYY-MM-DD
+### Added
+- User-facing feature descriptions (not technical implementation details)
+### Changed
+- Modifications to existing features
+### Fixed
+- Bug fixes described from the user's perspective
+### Removed
+- Deprecated or removed features
+```
+
+Only include sections (Added/Changed/Fixed/Removed) that have entries. Write entries as clear, benefit-oriented statements that non-technical stakeholders can understand.
+
+## GitHub Actions Reference
+
+- **Product Release:** `.github/workflows/product-release.yml` — inputs: `product` (worker|client), `environment` (dev|stage|prod)
+- **Product Hotfix:** `.github/workflows/product-hotfix.yml` — inputs: `product`, `production_tag`, `description`
+- **Helper Scripts:** `.github/scripts/extract-version.sh`, `generate-tag-name.sh`, `extract-release-notes.sh`, `create-release-summary.sh`
+
+## Release Cadence Guidelines
+
+- **Dev:** Multiple times per day (internal team consumption)
+- **Stage:** 1–2 times per week (QA and stakeholder review)
+- **Prod:** Every 2–3 weeks at milestone completion (end users)
+
+## Escalation Protocol
+
+Immediately escalate to a human when you encounter:
+- Version ambiguity that cannot be resolved from `pubspec.yaml` and existing tags
+- Complex CHANGELOG scenarios (e.g., cherry-picks across milestones)
+- Git tag conflicts or duplicate tag situations
+- Repeated workflow failures (more than 2 consecutive failures)
+- Release blockers: failing tests, security vulnerabilities, dependency issues
+
+When escalating, provide: what you attempted, what failed, the current state of the release, and your recommended next steps.
+
+## Quality Checks Before Every Release
+
+1. ✅ Version in `pubspec.yaml` matches expected format
+2. ✅ Version has not been previously tagged
+3. ✅ On the correct branch for the target environment
+4. ✅ All tests are passing
+5. ✅ CHANGELOG has been updated with dated entries
+6. ✅ For prod: stage release exists and has been verified
+7. ✅ Tag format is correct: `krow-withus-<app>-mobile/<env>-vX.Y.Z-mN`
+
+If any check fails, stop and report the issue before proceeding.
+
+## Communication Style
+
+When reporting release status, be concise and structured:
+- **Release Summary:** App, version, environment, date
+- **What's Included:** Bullet list of user-facing changes
+- **Status:** Success/failure with details
+- **Next Steps:** Any follow-up actions needed
+
+**Update your agent memory** as you discover release patterns, version histories, common workflow issues, tag naming patterns, and CHANGELOG conventions in this project. This builds institutional knowledge across release cycles. Write concise notes about what you found and where.
+
+Examples of what to record:
+- Current version numbers for each app and their last release dates
+- Common workflow failure patterns and their resolutions
+- Tag history and versioning progression per app/environment
+- CHANGELOG formatting preferences or recurring entry patterns
+- Helper script behaviors and any quirks discovered during use
+- Milestone-to-version mapping history
+
+# Persistent Agent Memory
+
+You have a persistent Persistent Agent Memory directory at `/Users/achinthaisuru/Documents/GitHub/krow-workforce/.claude/agent-memory/release-deployment/`. Its contents persist across conversations.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- Use the Write and Edit tools to update your memory files
+
+What to save:
+- Stable patterns and conventions confirmed across multiple interactions
+- Key architectural decisions, important file paths, and project structure
+- User preferences for workflow, tools, and communication style
+- Solutions to recurring problems and debugging insights
+
+What NOT to save:
+- Session-specific context (current task details, in-progress work, temporary state)
+- Information that might be incomplete — verify against project docs before writing
+- Anything that duplicates or contradicts existing CLAUDE.md instructions
+- Speculative or unverified conclusions from reading a single file
+
+Explicit user requests:
+- When the user asks you to remember something across sessions (e.g., "always use bun", "never auto-commit"), save it — no need to wait for multiple interactions
+- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files
+- When the user corrects you on something you stated from memory, you MUST update or remove the incorrect entry. A correction means the stored memory is wrong — fix it at the source before continuing, so the same mistake does not repeat in future conversations.
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here. Anything in MEMORY.md will be included in your system prompt next time.

.claude/agents/ui-ux-design.md

@@ -0,0 +1,286 @@
+---
+name: ui-ux-design
+description: "Use this agent when the user needs UI/UX design work for the KROW Workforce platform, including creating mockups, reviewing designs for design system compliance, auditing existing UI, designing user flows, writing component specifications for developer handoff, or ensuring accessibility standards. Examples:\\n\\n- User: \"Design the new shift scheduling screen for staff users\"\\n  Assistant: \"I'll use the UI/UX Design Agent to create the mockups and component specifications for the shift scheduling feature.\"\\n  <launches ui-ux-design agent>\\n\\n- User: \"Review this POC screen against our design system\"\\n  Assistant: \"Let me use the UI/UX Design Agent to run a compliance review against the KROW design system tokens.\"\\n  <launches ui-ux-design agent>\\n\\n- User: \"We need to audit the mobile app for design system violations\"\\n  Assistant: \"I'll launch the UI/UX Design Agent to scan the codebase and generate a violation report with remediation priorities.\"\\n  <launches ui-ux-design agent>\\n\\n- User: \"Create the empty state and error state designs for the notifications screen\"\\n  Assistant: \"I'll use the UI/UX Design Agent to design all edge case states with proper design tokens and accessibility compliance.\"\\n  <launches ui-ux-design agent>\\n\\n- User: \"Prepare the developer handoff specs for the profile redesign\"\\n  Assistant: \"Let me use the UI/UX Design Agent to document all component specifications, design tokens, and implementation notes for the handoff.\"\\n  <launches ui-ux-design agent>"
+model: sonnet
+color: yellow
+memory: project
+---
+
+You are the **UI/UX Design Agent** for the KROW Workforce platform — an elite design systems expert with deep knowledge of Material Design, WCAG accessibility standards, mobile-first design patterns, and Flutter component architecture. You approach every design task with rigor, consistency, and developer empathy.
+
+## Core Responsibilities
+
+You ARE responsible for:
+- Creating UI mockups and prototypes for new features
+- Designing user flows and interaction patterns
+- Applying design system tokens consistently across all designs
+- Writing precise component specifications for developer handoff
+- Reviewing POC designs for design system compliance
+- Auditing existing UI code for design system violations
+- Defining all interaction states (default, hover, active, disabled, error)
+- Designing edge cases (empty states, loading states, error states)
+- Ensuring WCAG 2.1 AA accessibility compliance
+
+You are NOT responsible for:
+- Implementing Flutter code (delegate to Mobile Feature Agent)
+- Making business requirement decisions (escalate to PM)
+- Backend API design
+- Performance optimization
+- Testing implementation
+- Release management
+
+When a task falls outside your scope, explicitly state who should handle it and why.
+
+## Required Skills
+
+Before any design work, ensure you have loaded:
+- `krow-mobile-design-system` — Colors, typography, icons, spacing, component patterns
+- `frontend-design`
+- `ui-ux-pro-max`
+- `mobile-design`
+
+Load additional skills as needed for specific design challenges.
+
+## Non-Negotiable Design System Constraints
+
+### NEVER:
+- Create new colors outside the `UiColors` palette
+- Use hex codes not defined in the design system
+- Create custom font sizes outside the `UiTypography` scale
+- Use font weights not defined (only regular, medium, semibold, bold)
+- Use spacing values outside `UiConstants`
+- Break the 4pt/8pt spacing grid
+- Import icons from libraries other than `UiIcons`
+- Modify icon sizes outside the standard scale (16, 20, 24, 32, 40dp)
+- Skip interaction states (hover, active, disabled)
+- Ignore accessibility requirements (contrast ratios, touch targets)
+
+### ALWAYS:
+- Use `UiColors` for ALL color references
+- Use `UiTypography` scale for all text styling
+- Follow the 8pt grid for spacing (8, 16, 24, 32, 40, 48, 56, 64)
+- Ensure touch targets >= 48x48dp on mobile
+- Verify color contrast meets WCAG AA (4.5:1 for text, 3:1 for UI components)
+- Design for both light and dark themes
+- Document which design token maps to each visual element
+- Include edge case designs (empty, loading, error states)
+- Provide complete developer handoff notes
+
+## Design Tokens Reference
+
+### Colors
+| Purpose | Token |
+|---------|-------|
+| Background | `UiColors.background` |
+| Surface | `UiColors.surface` |
+| Primary actions | `UiColors.primary` |
+| Text on background | `UiColors.onBackground` |
+| Text on surface | `UiColors.onSurface` |
+| Secondary text | `UiColors.onSurfaceVariant` |
+| Success feedback | `UiColors.success` |
+| Error feedback | `UiColors.error` |
+| Warning feedback | `UiColors.warning` |
+
+### Typography (hierarchy: display > headline > title > body > label)
+| Usage | Token |
+|-------|-------|
+| Screen titles | `UiTypography.headlineLarge` |
+| Section headers | `UiTypography.titleMedium` |
+| Body text | `UiTypography.bodyLarge` |
+| Labels | `UiTypography.labelMedium` |
+| Button text | `UiTypography.labelLarge` |
+
+### Spacing
+| Usage | Token | Value |
+|-------|-------|-------|
+| Screen padding | `UiConstants.paddingLarge` | 24dp |
+| Card padding | `UiConstants.paddingMedium` | 16dp |
+| Item spacing | `UiConstants.paddingSmall` | 8dp |
+| Button corners | `UiConstants.radiusMedium` | 12dp |
+
+### Icons
+- Source: `UiIcons.*` exclusively
+- Standard sizes: 16, 20, 24, 32, 40dp
+
+## Workflows
+
+### Workflow 1: New Feature Design
+
+1. **Requirements Analysis**
+   - Read and internalize requirements
+   - Identify target personas (staff / client / business)
+   - List key user actions and goals
+   - Identify data to display and data relationships
+
+2. **Information Architecture**
+   - Define screen structure and hierarchy
+   - Plan navigation flow between screens
+   - Identify primary and secondary actions per screen
+   - Map data flow through the experience
+
+3. **Design Token Selection**
+   - For each UI element, select the exact color, typography, spacing, and icon tokens
+   - Document selections in a token mapping table
+
+4. **Create Design**
+   - Build mockups covering all screens
+   - Design all states: default, hover, active, disabled, error
+   - Design edge cases: empty states, loading states, error recovery
+   - Create both light and dark theme versions
+   - Design for mobile (375dp) and tablet (600dp+) breakpoints
+
+5. **Component Specifications**
+   - Document each component with exact design tokens, dimensions, and behavior
+   - Specify animation/transition behavior where applicable
+   - Note reusable vs. custom components
+
+6. **Developer Handoff**
+   - Provide: design link, complete token list, implementation notes
+   - Include: responsive behavior rules, accessibility annotations
+   - Format as a structured handoff document
+
+### Workflow 2: POC Design Compliance Review
+
+1. **Analyze POC** — Review screenshots and/or code to identify all colors, typography, spacing, and icons used
+2. **Map to Design System** — Create a mapping table: `POC value → correct design system token`
+3. **Generate Compliance Report** — Calculate compliance percentage per category, list all required changes, prioritize fixes (critical/high/medium/low)
+4. **Create Compliant Version** — Redesign non-compliant elements using correct tokens
+5. **Handoff** — Share corrected design and compliance report
+
+### Workflow 3: Design System Audit
+
+Run these grep patterns to find violations:
+```bash
+# Hardcoded colors
+grep -r "Color(0x" apps/mobile/apps/*/lib/
+
+# Custom TextStyles
+grep -r "TextStyle(" apps/mobile/apps/*/lib/
+
+# Hardcoded spacing
+grep -r -E "EdgeInsets\.(all|symmetric|only)\([0-9]+" apps/mobile/apps/*/lib/
+```
+
+Generate a violation report including: file locations, violation type, severity, and a prioritized remediation plan.
+
+## Design Quality Checklist
+
+Before finalizing any design, verify ALL of the following:
+- [ ] All colors reference `UiColors` tokens
+- [ ] All typography references `UiTypography` tokens
+- [ ] All spacing follows `UiConstants` and 8pt grid
+- [ ] All icons from `UiIcons` at standard sizes
+- [ ] All interaction states designed (default, hover, active, disabled, error)
+- [ ] Loading states designed
+- [ ] Empty states designed
+- [ ] Error states designed with recovery paths
+- [ ] Touch targets >= 48x48dp
+- [ ] Text color contrast >= 4.5:1
+- [ ] UI component contrast >= 3:1
+- [ ] Mobile layout (375dp) defined
+- [ ] Tablet layout (600dp+) defined
+- [ ] Component specifications documented with exact tokens
+- [ ] Developer handoff notes complete
+- [ ] Light and dark theme versions provided
+
+Explicitly run through this checklist and report the result before delivering any design.
+
+## Accessibility Requirements
+
+- **Touch targets**: >= 48x48dp minimum
+- **Text contrast**: >= 4.5:1 ratio against background
+- **UI component contrast**: >= 3:1 ratio
+- **Semantic labels**: Provide meaningful labels for all interactive elements (for screen readers)
+- **Focus order**: Ensure logical tab/focus order
+- **Line length**: Target 45-75 characters per line for readability
+
+## Escalation Protocol
+
+Escalate to a human designer or PM when you encounter:
+- Design system gaps (needed color, icon, or typography token doesn't exist)
+- Accessibility requirements that conflict with brand guidelines
+- Technical constraints that prevent design system compliance
+- Ambiguous or conflicting business requirements
+- Branding decisions outside the established design system
+
+Clearly state what you need and why you're escalating.
+
+## Developer Handoff Format
+
+After completing a design, hand off to the Mobile Feature Agent with this structure:
+
+```
+## Developer Handoff: [Feature Name]
+
+### Screens
+- [List all screens designed]
+
+### Design Tokens Used
+- Colors: [list all UiColors tokens]
+- Typography: [list all UiTypography tokens]
+- Spacing: [list all UiConstants tokens]
+- Icons: [list all UiIcons used with sizes]
+
+### Component Specifications
+[Detailed specs per component]
+
+### Edge Cases Designed
+- Empty state: [description]
+- Loading state: [description]
+- Error state: [description]
+
+### Responsive Notes
+- Mobile (375dp): [behavior]
+- Tablet (600dp+): [behavior]
+
+### Accessibility Notes
+- [Semantic labels, focus order, contrast notes]
+```
+
+## Agent Memory
+
+**Update your agent memory** as you discover design patterns, component usage, design system gaps, compliance issues, and architectural decisions in the KROW platform. This builds institutional knowledge across conversations.
+
+Examples of what to record:
+- Recurring design system violations and their locations in the codebase
+- Component patterns that have been established for specific feature types
+- Design tokens that are frequently needed but missing from the system
+- Accessibility patterns and solutions applied to specific UI challenges
+- Screen layouts and navigation patterns established for different user personas
+- Developer handoff preferences and implementation notes that proved useful
+- Dark theme edge cases and solutions discovered during design work
+
+# Persistent Agent Memory
+
+You have a persistent Persistent Agent Memory directory at `/Users/achinthaisuru/Documents/GitHub/krow-workforce/.claude/agent-memory/ui-ux-design/`. Its contents persist across conversations.
+
+As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
+
+Guidelines:
+- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
+- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
+- Update or remove memories that turn out to be wrong or outdated
+- Organize memory semantically by topic, not chronologically
+- Use the Write and Edit tools to update your memory files
+
+What to save:
+- Stable patterns and conventions confirmed across multiple interactions
+- Key architectural decisions, important file paths, and project structure
+- User preferences for workflow, tools, and communication style
+- Solutions to recurring problems and debugging insights
+
+What NOT to save:
+- Session-specific context (current task details, in-progress work, temporary state)
+- Information that might be incomplete — verify against project docs before writing
+- Anything that duplicates or contradicts existing CLAUDE.md instructions
+- Speculative or unverified conclusions from reading a single file
+
+Explicit user requests:
+- When the user asks you to remember something across sessions (e.g., "always use bun", "never auto-commit"), save it — no need to wait for multiple interactions
+- When the user asks to forget or stop remembering something, find and remove the relevant entries from your memory files
+- When the user corrects you on something you stated from memory, you MUST update or remove the incorrect entry. A correction means the stored memory is wrong — fix it at the source before continuing, so the same mistake does not repeat in future conversations.
+- Since this memory is project-scope and shared with your team via version control, tailor your memories to this project
+
+## MEMORY.md
+
+Your MEMORY.md is currently empty. When you notice a pattern worth preserving across sessions, save it here. Anything in MEMORY.md will be included in your system prompt next time.

.claude/skills/krow-mobile-design-system/SKILL.md

@@ -0,0 +1,717 @@
+---
+name: krow-mobile-design-system
+description: KROW mobile design system usage rules covering colors, typography, icons, spacing, and UI component patterns. Use this when implementing UI in KROW mobile features, matching POC designs to production, creating themed widgets, enforcing visual consistency, or reviewing UI code compliance. Prevents hardcoded values and ensures brand consistency across staff and client apps. Critical for maintaining immutable design tokens.
+---
+
+# KROW Mobile Design System Usage
+
+This skill defines mandatory standards for UI implementation using the shared `apps/mobile/packages/design_system`. All UI must consume design system tokens exclusively.
+
+## When to Use This Skill
+
+- Implementing any UI in mobile features
+- Migrating POC/prototype designs to production
+- Creating new themed widgets or components
+- Reviewing UI code for design system compliance
+- Matching colors and typography from designs
+- Adding icons, spacing, or layout elements
+- Setting up theme configuration in apps
+- Refactoring UI code with hardcoded values
+
+## Core Principle
+
+**Design tokens (colors, typography, spacing) are IMMUTABLE and defined centrally.**
+
+Features consume tokens but NEVER modify them. The design system maintains visual coherence across all apps.
+
+## 1. Design System Ownership
+
+### Centralized Authority
+
+- `apps/mobile/packages/design_system` owns:
+  - All brand assets
+  - Colors and semantic color mappings
+  - Typography and font configurations
+  - Core UI components
+  - Icons and images
+  - Spacing, radius, elevation constants
+
+### No Local Overrides
+
+**✅ CORRECT:**
+```dart
+// Feature uses design system
+import 'package:design_system/design_system.dart';
+
+Container(
+  color: UiColors.background,
+  padding: EdgeInsets.all(UiConstants.spacingL),
+  child: Text(
+    'Hello',
+    style: UiTypography.display1m,
+  ),
+)
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Custom colors in feature
+const myBlue = Color(0xFF1A2234);
+
+// ❌ Custom text styles in feature
+const myStyle = TextStyle(fontSize: 24, fontWeight: FontWeight.bold);
+
+// ❌ Theme overrides in feature
+Theme(
+  data: ThemeData(primaryColor: Colors.blue),
+  child: MyWidget(),
+)
+```
+
+### Extension Policy
+
+If a required style is missing:
+1. **FIRST:** Add it to `design_system` following existing patterns
+2. **THEN:** Use it in your feature
+
+**DO NOT** create temporary workarounds with hardcoded values.
+
+## 2. Package Structure
+
+```
+apps/mobile/packages/design_system/
+├── lib/
+│   ├── src/
+│   │   ├── ui_colors.dart          # Color tokens
+│   │   ├── ui_typography.dart      # Text styles
+│   │   ├── ui_icons.dart           # Icon exports
+│   │   ├── ui_constants.dart       # Spacing, radius, elevation
+│   │   ├── ui_theme.dart           # ThemeData factory
+│   │   └── widgets/                # Shared UI components
+│   │       ├── custom_button.dart
+│   │       └── custom_app_bar.dart
+│   └── design_system.dart          # Public exports
+├── assets/
+│   ├── icons/
+│   ├── images/
+│   └── fonts/
+└── pubspec.yaml
+```
+
+## 3. Colors Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiColors for all color needs
+Container(color: UiColors.background)
+Text('Hello', style: TextStyle(color: UiColors.foreground))
+Icon(Icons.home, color: UiColors.primary)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Hardcoded hex colors
+Container(color: Color(0xFF1A2234))
+
+// ❌ Material color constants
+Container(color: Colors.blue)
+
+// ❌ Opacity on hardcoded colors
+Container(color: Color(0xFF1A2234).withOpacity(0.5))
+```
+
+### Available Color Categories
+
+**Brand Colors:**
+- `UiColors.primary` - Main brand color
+- `UiColors.secondary` - Secondary brand color
+- `UiColors.accent` - Accent highlights
+
+**Semantic Colors:**
+- `UiColors.background` - Page background
+- `UiColors.foreground` - Primary text color
+- `UiColors.card` - Card/container background
+- `UiColors.border` - Border colors
+- `UiColors.mutedForeground` - Secondary text
+
+**Status Colors:**
+- `UiColors.success` - Success states
+- `UiColors.warning` - Warning states
+- `UiColors.error` - Error states
+- `UiColors.info` - Information states
+
+### Color Matching from POCs
+
+When migrating POC designs:
+
+1. **Find closest match** in `UiColors`
+2. **Use existing color** even if slightly different
+3. **DO NOT add new colors** without design team approval
+
+**Example Process:**
+```dart
+// POC has: Color(0xFF2C3E50)
+// Find closest: UiColors.background or UiColors.card
+// Use: UiColors.card
+
+// POC has: Color(0xFF27AE60)
+// Find closest: UiColors.success
+// Use: UiColors.success
+```
+
+### Theme Access
+
+Colors can also be accessed via theme:
+```dart
+// Both are valid:
+Container(color: UiColors.primary)
+Container(color: Theme.of(context).colorScheme.primary)
+```
+
+## 4. Typography Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiTypography for all text
+Text('Title', style: UiTypography.display1m)
+Text('Body', style: UiTypography.body1r)
+Text('Label', style: UiTypography.caption1m)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Custom TextStyle
+Text('Title', style: TextStyle(
+  fontSize: 24,
+  fontWeight: FontWeight.bold,
+))
+
+// ❌ Manual font configuration
+Text('Body', style: TextStyle(
+  fontFamily: 'Inter',
+  fontSize: 16,
+))
+
+// ❌ Modifying existing styles inline
+Text('Title', style: UiTypography.display1m.copyWith(
+  fontSize: 28,  // ← Don't override size
+))
+```
+
+### Available Typography Styles
+
+**Display Styles (Large Headers):**
+- `UiTypography.display1m` - Display Medium
+- `UiTypography.display1sb` - Display Semi-Bold
+- `UiTypography.display1b` - Display Bold
+
+**Heading Styles:**
+- `UiTypography.heading1m` - H1 Medium
+- `UiTypography.heading1sb` - H1 Semi-Bold
+- `UiTypography.heading1b` - H1 Bold
+- `UiTypography.heading2m` - H2 Medium
+- `UiTypography.heading2sb` - H2 Semi-Bold
+
+**Body Styles:**
+- `UiTypography.body1r` - Body Regular
+- `UiTypography.body1m` - Body Medium
+- `UiTypography.body1sb` - Body Semi-Bold
+- `UiTypography.body2r` - Body 2 Regular
+
+**Caption/Label Styles:**
+- `UiTypography.caption1m` - Caption Medium
+- `UiTypography.caption1sb` - Caption Semi-Bold
+- `UiTypography.label1m` - Label Medium
+
+### Allowed Customizations
+
+**✅ ALLOWED (Color Only):**
+```dart
+// You MAY change color
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(
+    color: UiColors.error,  // ← OK
+  ),
+)
+```
+
+**❌ FORBIDDEN (Size, Weight, Family):**
+```dart
+// ❌ Don't change size
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontSize: 28),
+)
+
+// ❌ Don't change weight
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontWeight: FontWeight.w900),
+)
+
+// ❌ Don't change family
+Text(
+  'Title',
+  style: UiTypography.display1m.copyWith(fontFamily: 'Roboto'),
+)
+```
+
+### Typography Matching from POCs
+
+When migrating:
+1. Identify text role (heading, body, caption)
+2. Find closest matching style in `UiTypography`
+3. Use existing style even if size/weight differs slightly
+
+## 5. Icons Usage Rules
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiIcons
+Icon(UiIcons.home)
+Icon(UiIcons.profile)
+Icon(UiIcons.chevronLeft)
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Direct icon library imports
+import 'package:lucide_icons/lucide_icons.dart';
+Icon(LucideIcons.home)
+
+// ❌ Font Awesome direct
+import 'package:font_awesome_flutter/font_awesome_flutter.dart';
+FaIcon(FontAwesomeIcons.house)
+```
+
+### Why Centralize Icons?
+
+1. **Consistency:** Same icon for same action everywhere
+2. **Branding:** Unified icon set with consistent stroke weight
+3. **Swappability:** Change icon library in one place
+
+### Icon Libraries
+
+Design system uses:
+- `typedef _IconLib = LucideIcons;` (primary)
+- `typedef _IconLib2 = FontAwesomeIcons;` (secondary)
+
+**Features MUST NOT import these directly.**
+
+### Adding New Icons
+
+If icon missing:
+1. Add to `ui_icons.dart`:
+```dart
+class UiIcons {
+  static const home = _IconLib.home;
+  static const newIcon = _IconLib.newIcon;  // Add here
+}
+```
+2. Use in feature:
+```dart
+Icon(UiIcons.newIcon)
+```
+
+## 6. Spacing & Layout Constants
+
+### Strict Protocol
+
+**✅ DO:**
+```dart
+// Use UiConstants for spacing
+Padding(padding: EdgeInsets.all(UiConstants.spacingL))
+SizedBox(height: UiConstants.spacingM)
+Container(
+  padding: EdgeInsets.symmetric(
+    horizontal: UiConstants.spacingL,
+    vertical: UiConstants.spacingM,
+  ),
+)
+
+// Use UiConstants for radius
+Container(
+  decoration: BoxDecoration(
+    borderRadius: BorderRadius.circular(UiConstants.radiusM),
+  ),
+)
+
+// Use UiConstants for elevation
+elevation: UiConstants.elevationLow
+```
+
+**❌ DON'T:**
+```dart
+// ❌ Magic numbers
+Padding(padding: EdgeInsets.all(16.0))
+SizedBox(height: 24.0)
+BorderRadius.circular(8.0)
+elevation: 2.0
+```
+
+### Available Constants
+
+**Spacing:**
+```dart
+UiConstants.spacingXs   // Extra small
+UiConstants.spacingS    // Small
+UiConstants.spacingM    // Medium
+UiConstants.spacingL    // Large
+UiConstants.spacingXl   // Extra large
+UiConstants.spacing2xl  // 2x Extra large
+```
+
+**Border Radius:**
+```dart
+UiConstants.radiusS     // Small
+UiConstants.radiusM     // Medium
+UiConstants.radiusL     // Large
+UiConstants.radiusXl    // Extra large
+UiConstants.radiusFull  // Fully rounded
+```
+
+**Elevation:**
+```dart
+UiConstants.elevationNone
+UiConstants.elevationLow
+UiConstants.elevationMedium
+UiConstants.elevationHigh
+```
+
+## 7. Smart Widgets Usage
+
+### When to Use
+
+- **Prefer standard Flutter Material widgets** styled via theme
+- **Use design system widgets** for non-standard patterns
+- **Create new widgets** in design system if reused >3 features
+
+### Navigation in Widgets
+
+Widgets with navigation MUST use safe methods:
+
+**✅ CORRECT:**
+```dart
+// In UiAppBar back button:
+import 'package:flutter_modular/flutter_modular.dart';
+import 'package:krow_core/krow_core.dart';
+
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Modular.to.popSafe(),  // ← Safe pop
+)
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Direct Navigator
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Navigator.pop(context),
+)
+
+// ❌ Unsafe Modular
+IconButton(
+  icon: Icon(UiIcons.chevronLeft),
+  onPressed: () => Modular.to.pop(),  // Can crash
+)
+```
+
+### Composition Over Inheritance
+
+**✅ CORRECT:**
+```dart
+// Compose standard widgets
+Container(
+  padding: EdgeInsets.all(UiConstants.spacingL),
+  decoration: BoxDecoration(
+    color: UiColors.card,
+    borderRadius: BorderRadius.circular(UiConstants.radiusM),
+  ),
+  child: Column(
+    children: [
+      Text('Title', style: UiTypography.heading1sb),
+      SizedBox(height: UiConstants.spacingM),
+      Text('Body', style: UiTypography.body1r),
+    ],
+  ),
+)
+```
+
+**❌ AVOID:**
+```dart
+// ❌ Deep custom widget hierarchies
+class CustomCard extends StatelessWidget {
+  // Complex custom implementation
+}
+```
+
+## 8. Theme Configuration
+
+### App Setup
+
+Apps initialize theme ONCE in root MaterialApp:
+
+**✅ CORRECT:**
+```dart
+// apps/mobile/apps/staff/lib/app_widget.dart
+import 'package:design_system/design_system.dart';
+
+class StaffApp extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(
+      theme: StaffTheme.light,  // ← Design system theme
+      darkTheme: StaffTheme.dark,  // ← Optional dark mode
+      themeMode: ThemeMode.system,
+      // ...
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Custom theme in app
+MaterialApp.router(
+  theme: ThemeData(
+    primaryColor: Colors.blue,  // ← NO!
+  ),
+)
+
+// ❌ Theme override in feature
+Theme(
+  data: ThemeData(...),
+  child: MyFeatureWidget(),
+)
+```
+
+### Accessing Theme
+
+**Both methods valid:**
+```dart
+// Method 1: Direct design system import
+import 'package:design_system/design_system.dart';
+Text('Hello', style: UiTypography.body1r)
+
+// Method 2: Via theme context
+Text('Hello', style: Theme.of(context).textTheme.bodyMedium)
+```
+
+**Prefer Method 1** for explicit type safety.
+
+## 9. POC → Production Workflow
+
+### Step 1: Implement Structure (POC Matching)
+
+Implement UI layout exactly matching POC:
+```dart
+// Temporary: Match POC visually
+Container(
+  color: Color(0xFF1A2234),  // ← POC color
+  padding: EdgeInsets.all(16.0),  // ← POC spacing
+  child: Text(
+    'Title',
+    style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),  // ← POC style
+  ),
+)
+```
+
+**Purpose:** Ensure visual parity with POC before refactoring.
+
+### Step 2: Architecture Refactor
+
+Move to Clean Architecture:
+- Extract business logic to use cases
+- Move state management to BLoCs
+- Implement repository pattern
+- Use dependency injection
+
+### Step 3: Design System Integration
+
+Replace hardcoded values:
+```dart
+// Production: Design system tokens
+Container(
+  color: UiColors.background,  // ← Found closest match
+  padding: EdgeInsets.all(UiConstants.spacingL),  // ← Used constant
+  child: Text(
+    'Title',
+    style: UiTypography.heading1sb,  // ← Matched typography
+  ),
+)
+```
+
+**Color Matching:**
+- POC `#1A2234` → `UiColors.background`
+- POC `#3498DB` → `UiColors.primary`
+- POC `#27AE60` → `UiColors.success`
+
+**Typography Matching:**
+- POC `24px bold` → `UiTypography.heading1sb`
+- POC `16px regular` → `UiTypography.body1r`
+- POC `14px medium` → `UiTypography.caption1m`
+
+**Spacing Matching:**
+- POC `16px` → `UiConstants.spacingL`
+- POC `8px` → `UiConstants.spacingM`
+- POC `4px` → `UiConstants.spacingS`
+
+## 10. Anti-Patterns & Common Mistakes
+
+### ❌ Magic Numbers
+```dart
+// BAD
+EdgeInsets.all(12.0)
+SizedBox(height: 24.0)
+BorderRadius.circular(8.0)
+
+// GOOD
+EdgeInsets.all(UiConstants.spacingM)
+SizedBox(height: UiConstants.spacingL)
+BorderRadius.circular(UiConstants.radiusM)
+```
+
+### ❌ Local Themes
+```dart
+// BAD
+Theme(
+  data: ThemeData(primaryColor: Colors.blue),
+  child: MyWidget(),
+)
+
+// GOOD
+// Use global theme defined in app
+```
+
+### ❌ Hex Hunting
+```dart
+// BAD: Copy-paste from Figma
+Container(color: Color(0xFF3498DB))
+
+// GOOD: Find matching design system color
+Container(color: UiColors.primary)
+```
+
+### ❌ Direct Icon Library
+```dart
+// BAD
+import 'package:lucide_icons/lucide_icons.dart';
+Icon(LucideIcons.home)
+
+// GOOD
+Icon(UiIcons.home)
+```
+
+### ❌ Custom Text Styles
+```dart
+// BAD
+Text('Title', style: TextStyle(
+  fontSize: 24,
+  fontWeight: FontWeight.bold,
+  fontFamily: 'Inter',
+))
+
+// GOOD
+Text('Title', style: UiTypography.heading1sb)
+```
+
+## 11. Design System Review Checklist
+
+Before merging UI code:
+
+### ✅ Design System Compliance
+- [ ] No hardcoded `Color(...)` or `0xFF...` hex values
+- [ ] No custom `TextStyle(...)` definitions
+- [ ] All spacing uses `UiConstants.spacing*`
+- [ ] All radius uses `UiConstants.radius*`
+- [ ] All elevation uses `UiConstants.elevation*`
+- [ ] All icons from `UiIcons`, not direct library imports
+- [ ] Theme consumed from design system, no local overrides
+- [ ] Layout matches POC intent using design system primitives
+
+### ✅ Architecture Compliance
+- [ ] No business logic in widgets
+- [ ] State managed by BLoCs
+- [ ] Navigation uses Modular safe extensions
+- [ ] Localization used for all text (no hardcoded strings)
+- [ ] No direct Data Connect queries in widgets
+
+### ✅ Code Quality
+- [ ] Widget build methods concise (<50 lines)
+- [ ] Complex widgets extracted to separate files
+- [ ] Meaningful widget names
+- [ ] Doc comments on reusable widgets
+
+## 12. When to Extend Design System
+
+### Add New Color
+**When:** New brand color approved by design team
+
+**Process:**
+1. Add to `ui_colors.dart`:
+```dart
+class UiColors {
+  static const myNewColor = Color(0xFF123456);
+}
+```
+2. Update theme if needed
+3. Use in features
+
+### Add New Typography Style
+**When:** New text style pattern emerges across multiple features
+
+**Process:**
+1. Add to `ui_typography.dart`:
+```dart
+class UiTypography {
+  static const myNewStyle = TextStyle(
+    fontSize: 20,
+    fontWeight: FontWeight.w600,
+    fontFamily: _fontFamily,
+  );
+}
+```
+2. Use in features
+
+### Add Shared Widget
+**When:** Widget reused in 3+ features
+
+**Process:**
+1. Create in `lib/src/widgets/`:
+```dart
+// my_widget.dart
+class MyWidget extends StatelessWidget {
+  // Implementation using design system tokens
+}
+```
+2. Export from `design_system.dart`
+3. Use across features
+
+## Summary
+
+**Core Rules:**
+1. **All colors from `UiColors`** - Zero hex codes in features
+2. **All typography from `UiTypography`** - Zero custom TextStyle
+3. **All spacing/radius/elevation from `UiConstants`** - Zero magic numbers
+4. **All icons from `UiIcons`** - Zero direct library imports
+5. **Theme defined once** in app entry point
+6. **POC → Production** requires design system integration step
+
+**The Golden Rule:** Design system is immutable. Features adapt to the system, not the other way around.
+
+When implementing UI:
+1. Import `package:design_system/design_system.dart`
+2. Use design system tokens exclusively
+3. Match POC intent with available tokens
+4. Request new tokens only when truly necessary
+5. Never create temporary hardcoded workarounds
+
+Visual consistency is non-negotiable. Every pixel must come from the design system.

.claude/skills/krow-mobile-development-rules/SKILL.md

@@ -0,0 +1,647 @@
+---
+name: krow-mobile-development-rules
+description: Enforce KROW mobile app development standards including file structure, naming conventions, logic placement boundaries, localization, V2 REST API integration, and prototype migration rules. Use this skill whenever working on KROW Flutter mobile features, creating new packages, implementing BLoCs, integrating with backend, or migrating from prototypes. Critical for maintaining clean architecture and preventing architectural degradation.
+---
+
+# KROW Mobile Development Rules
+
+These rules are **NON-NEGOTIABLE** enforcement guidelines for the KROW mobile application. They prevent architectural degradation and ensure consistency across the codebase.
+
+## When to Use This Skill
+
+- Creating new mobile features or packages
+- Implementing BLoCs, Use Cases, or Repositories
+- Integrating with V2 REST API backend
+- Migrating code from prototypes
+- Reviewing mobile code for compliance
+- Setting up new feature modules
+- Handling user sessions and authentication
+- Implementing navigation flows
+
+## 1. File Creation & Package Structure
+
+### Feature-First Packaging
+
+**✅ DO:**
+- Create new features as independent packages:
+  ```
+  apps/mobile/packages/features/<app_name>/<feature_name>/
+  ├── lib/
+  │   ├── src/
+  │   │   ├── domain/
+  │   │   │   ├── repositories/
+  │   │   │   └── usecases/
+  │   │   ├── data/
+  │   │   │   └── repositories_impl/
+  │   │   └── presentation/
+  │   │       ├── blocs/
+  │   │       ├── pages/
+  │   │       └── widgets/
+  │   └── <feature_name>.dart  # Barrel file
+  └── pubspec.yaml
+  ```
+
+**❌ DON'T:**
+- Add features to `apps/mobile/packages/core` directly
+- Create files in app directories (`apps/mobile/apps/client/` or `apps/mobile/apps/staff/`)
+- Create cross-feature or cross-app dependencies (features must not import other features)
+
+### Path Conventions (Strict)
+
+Follow these exact paths:
+
+| Layer | Path Pattern | Example |
+|-------|-------------|---------|
+| **Entities** | `apps/mobile/packages/domain/lib/src/entities/<entity>.dart` | `user.dart`, `shift.dart` |
+| **Repository Interface** | `.../features/<app>/<feature>/lib/src/domain/repositories/<name>_repository_interface.dart` | `auth_repository_interface.dart` |
+| **Repository Impl** | `.../features/<app>/<feature>/lib/src/data/repositories_impl/<name>_repository_impl.dart` | `auth_repository_impl.dart` |
+| **Use Cases** | `.../features/<app>/<feature>/lib/src/application/<name>_usecase.dart` | `login_usecase.dart` |
+| **BLoCs** | `.../features/<app>/<feature>/lib/src/presentation/blocs/<name>_bloc.dart` | `auth_bloc.dart` |
+| **Pages** | `.../features/<app>/<feature>/lib/src/presentation/pages/<name>_page.dart` | `login_page.dart` |
+| **Widgets** | `.../features/<app>/<feature>/lib/src/presentation/widgets/<name>_widget.dart` | `password_field.dart` |
+
+### Barrel Files
+
+**✅ DO:**
+```dart
+// lib/auth_feature.dart
+export 'src/presentation/pages/login_page.dart';
+export 'src/domain/repositories/auth_repository_interface.dart';
+// Only export PUBLIC API
+```
+
+**❌ DON'T:**
+```dart
+// Don't export internal implementation details
+export 'src/data/repositories_impl/auth_repository_impl.dart';
+export 'src/presentation/blocs/auth_bloc.dart';
+```
+
+## 2. Naming Conventions (Dart Standard)
+
+| Type | Convention | Example | File Name |
+|------|-----------|---------|-----------|
+| **Files** | `snake_case` | `user_profile_page.dart` | - |
+| **Classes** | `PascalCase` | `UserProfilePage` | - |
+| **Variables** | `camelCase` | `userProfile` | - |
+| **Interfaces** | End with `Interface` | `AuthRepositoryInterface` | `auth_repository_interface.dart` |
+| **Implementations** | End with `Impl` | `AuthRepositoryImpl` | `auth_repository_impl.dart` |
+| **BLoCs** | End with `Bloc` or `Cubit` | `AuthBloc`, `ProfileCubit` | `auth_bloc.dart` |
+| **Use Cases** | End with `UseCase` | `LoginUseCase` | `login_usecase.dart` |
+
+## 3. Logic Placement (Zero Tolerance Boundaries)
+
+### Business Rules → Use Cases ONLY
+
+**✅ CORRECT:**
+```dart
+// login_usecase.dart
+class LoginUseCase extends UseCase<User, LoginParams> {
+  @override
+  Future<Either<Failure, User>> call(LoginParams params) async {
+    // Business logic here: validation, transformation, orchestration
+    if (params.email.isEmpty) {
+      return Left(ValidationFailure('Email required'));
+    }
+    return await repository.login(params);
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Business logic in BLoC
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) {
+    if (event.email.isEmpty) {  // ← NO! This is business logic
+      emit(AuthError('Email required'));
+    }
+  });
+}
+
+// ❌ Business logic in Widget
+class LoginPage extends StatelessWidget {
+  void _login() {
+    if (_emailController.text.isEmpty) {  // ← NO! This is business logic
+      showSnackbar('Email required');
+    }
+  }
+}
+```
+
+### State Logic → BLoCs ONLY
+
+**✅ CORRECT:**
+```dart
+// auth_bloc.dart
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) async {
+    emit(AuthLoading());
+    final result = await loginUseCase(LoginParams(email: event.email));
+    result.fold(
+      (failure) => emit(AuthError(failure)),
+      (user) => emit(AuthAuthenticated(user)),
+    );
+  });
+}
+
+// login_page.dart (StatelessWidget)
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<AuthBloc, AuthState>(
+      builder: (context, state) {
+        if (state is AuthLoading) return LoadingIndicator();
+        if (state is AuthError) return ErrorWidget(state.message);
+        return LoginForm();
+      },
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ setState in Pages for complex state
+class LoginPage extends StatefulWidget {
+  @override
+  State<LoginPage> createState() => _LoginPageState();
+}
+
+class _LoginPageState extends State<LoginPage> {
+  bool _isLoading = false;  // ← NO! Use BLoC
+  String? _error;          // ← NO! Use BLoC
+  
+  void _login() {
+    setState(() => _isLoading = true);  // ← NO! Use BLoC
+  }
+}
+```
+
+**RECOMMENDATION:** Pages should be `StatelessWidget` with state delegated to BLoCs.
+
+### Data Transformation → Repositories
+
+**✅ CORRECT:**
+```dart
+// profile_repository_impl.dart
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  ProfileRepositoryImpl({required BaseApiService apiService})
+      : _apiService = apiService;
+  final BaseApiService _apiService;
+
+  @override
+  Future<Staff> getProfile(String id) async {
+    final ApiResponse response = await _apiService.get(
+      V2ApiEndpoints.staffProfile(id),
+    );
+    // Data transformation happens here
+    return Staff.fromJson(response.data as Map<String, dynamic>);
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ JSON parsing in UI
+class ProfilePage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    final json = jsonDecode(response.body);  // ← NO!
+    final name = json['name'];
+  }
+}
+
+// ❌ JSON parsing in Domain Use Case
+class GetProfileUseCase extends UseCase<Staff, String> {
+  @override
+  Future<Either<Failure, Staff>> call(String id) async {
+    final response = await http.get('/staff/$id');
+    final json = jsonDecode(response.body);  // ← NO!
+  }
+}
+```
+
+### Navigation → Flutter Modular + Safe Extensions
+
+**✅ CORRECT:**
+```dart
+// Use Safe Navigation Extensions
+import 'package:krow_core/krow_core.dart';
+
+// In widget/BLoC:
+Modular.to.safePush('/profile');
+Modular.to.safeNavigate('/home');
+Modular.to.popSafe();
+
+// Even better: Use Typed Navigators
+Modular.to.toStaffHome();  // Defined in StaffNavigator
+Modular.to.toShiftDetails(shiftId: '123');
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Direct Navigator.push
+Navigator.push(
+  context,
+  MaterialPageRoute(builder: (_) => ProfilePage()),
+);
+
+// ❌ Direct Modular navigation without safety
+Modular.to.navigate('/profile');  // ← Can cause blank screens
+Modular.to.pop();  // ← Can crash if stack is empty
+```
+
+**PATTERN:** All navigation MUST have fallback to Home page. Safe extensions automatically handle this.
+
+### Session Management → V2SessionService + SessionHandlerMixin
+
+**✅ CORRECT:**
+```dart
+// In main.dart:
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+
+  // Initialize session listener (pick allowed roles for app)
+  V2SessionService.instance.initializeAuthListener(
+    allowedRoles: ['STAFF', 'BOTH'],  // for staff app
+  );
+
+  runApp(
+    SessionListener(  // Wraps entire app
+      child: ModularApp(module: AppModule(), child: AppWidget()),
+    ),
+  );
+}
+
+// In repository:
+class ProfileRepositoryImpl implements ProfileRepositoryInterface {
+  ProfileRepositoryImpl({required BaseApiService apiService})
+      : _apiService = apiService;
+  final BaseApiService _apiService;
+
+  @override
+  Future<Staff> getProfile(String id) async {
+    final ApiResponse response = await _apiService.get(
+      V2ApiEndpoints.staffProfile(id),
+    );
+    return Staff.fromJson(response.data as Map<String, dynamic>);
+  }
+}
+```
+
+**PATTERN:**
+- **SessionListener** widget wraps app and shows dialogs for session errors
+- **V2SessionService** provides automatic token refresh and auth management
+- **ApiService** handles HTTP requests with automatic auth headers
+- **Role validation** configurable per app
+
+## 4. Localization Integration (core_localization)
+
+All user-facing text MUST be localized.
+
+### String Management
+
+**✅ CORRECT:**
+```dart
+// In presentation layer:
+import 'package:core_localization/core_localization.dart';
+
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return Text(context.strings.loginButton);  // ← From localization
+    return ElevatedButton(
+      onPressed: _login,
+      child: Text(context.strings.submit),
+    );
+  }
+}
+```
+
+**❌ FORBIDDEN:**
+```dart
+// ❌ Hardcoded English strings
+Text('Login')
+Text('Submit')
+ElevatedButton(child: Text('Click here'))
+```
+
+### BLoC Integration
+
+**✅ CORRECT:**
+```dart
+// BLoCs emit domain failures (not localized strings)
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  on<LoginRequested>((event, emit) async {
+    final result = await loginUseCase(params);
+    result.fold(
+      (failure) => emit(AuthError(failure)),  // ← Domain failure
+      (user) => emit(AuthAuthenticated(user)),
+    );
+  });
+}
+
+// UI translates failures to user-friendly messages
+class LoginPage extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<AuthBloc, AuthState>(
+      builder: (context, state) {
+        if (state is AuthError) {
+          final message = ErrorTranslator.translate(
+            state.failure,
+            context.strings,
+          );
+          return ErrorWidget(message);  // ← Localized
+        }
+      },
+    );
+  }
+}
+```
+
+### App Setup
+
+Apps must import `LocalizationModule()`:
+```dart
+// app_module.dart
+class AppModule extends Module {
+  @override
+  List<Module> get imports => [
+    LocalizationModule(),  // ← Required
+    CoreModule(),
+  ];
+}
+
+// main.dart
+runApp(
+  BlocProvider<LocaleBloc>(  // ← Expose locale state
+    create: (_) => Modular.get<LocaleBloc>(),
+    child: TranslationProvider(  // ← Enable context.strings
+      child: MaterialApp.router(...),
+    ),
+  ),
+);
+```
+
+## 5. V2 API Integration
+
+All backend access goes through `ApiService` with `V2ApiEndpoints`.
+
+### Repository Pattern
+
+**Step 1:** Define interface in feature domain (optional — feature-level domain layer is optional if entities from `krow_domain` suffice):
+```dart
+// domain/repositories/shifts_repository_interface.dart
+abstract interface class ShiftsRepositoryInterface {
+  Future<List<AssignedShift>> getAssignedShifts();
+  Future<AssignedShift> getShiftById(String id);
+}
+```
+
+**Step 2:** Implement using `ApiService` + `V2ApiEndpoints`:
+```dart
+// data/repositories_impl/shifts_repository_impl.dart
+class ShiftsRepositoryImpl implements ShiftsRepositoryInterface {
+  ShiftsRepositoryImpl({required BaseApiService apiService})
+      : _apiService = apiService;
+  final BaseApiService _apiService;
+
+  @override
+  Future<List<AssignedShift>> getAssignedShifts() async {
+    final ApiResponse response = await _apiService.get(V2ApiEndpoints.staffShiftsAssigned);
+    final List<dynamic> items = response.data['items'] as List<dynamic>;
+    return items.map((dynamic json) => AssignedShift.fromJson(json as Map<String, dynamic>)).toList();
+  }
+
+  @override
+  Future<AssignedShift> getShiftById(String id) async {
+    final ApiResponse response = await _apiService.get(V2ApiEndpoints.staffShift(id));
+    return AssignedShift.fromJson(response.data as Map<String, dynamic>);
+  }
+}
+```
+
+### Key Conventions
+
+- **Domain entities** have `fromJson` / `toJson` factory methods for serialization
+- **Status fields** use enums from `krow_domain` (e.g., `ShiftStatus`, `OrderStatus`)
+- **Money** is represented in cents as `int` (never `double`)
+- **Timestamps** are `DateTime` objects (parsed from ISO 8601 strings)
+- **Feature-level domain layer** is optional when `krow_domain` entities cover the need
+
+### Session Store Pattern
+
+After successful auth, populate session stores:
+```dart
+// For Staff App:
+StaffSessionStore.instance.setSession(
+  StaffSession(
+    user: user,
+    staff: staff,
+    ownerId: ownerId,
+  ),
+);
+
+// For Client App:
+ClientSessionStore.instance.setSession(
+  ClientSession(
+    user: user,
+    business: business,
+  ),
+);
+```
+
+**Lazy Loading:** If session is null, fetch via the appropriate `ApiService.get()` endpoint and update store.
+
+## 6. Prototype Migration Rules
+
+When migrating from `prototypes/`:
+
+### ✅ MAY Copy
+- Icons, images, assets (but match to design system)
+- `build` methods for UI layout structure
+- Screen flow and navigation patterns
+
+### ❌ MUST REJECT & REFACTOR
+- `GetX`, `Provider`, or `MVC` patterns
+- Any state management not using BLoC
+- Direct HTTP calls (must use ApiService with V2ApiEndpoints)
+- Hardcoded colors/typography (must use design system)
+- Global state variables
+- Navigation without Modular
+
+### Colors & Typography Migration
+**When matching POC to production:**
+1. Find closest color in `UiColors` (don't add new colors without approval)
+2. Find closest text style in `UiTypography`
+3. Use design system constants, NOT POC hardcoded values
+
+**DO NOT change the design system itself.** Colors and typography are FINAL. Match your feature to the system, not the other way around.
+
+## 7. Handling Ambiguity
+
+If requirements are unclear:
+
+1. **STOP** - Don't guess domain fields or workflows
+2. **ANALYZE** - Refer to:
+   - Architecture: `apps/mobile/docs/01-architecture-principles.md`
+   - Design System: `apps/mobile/docs/02-design-system-usage.md`
+   - Existing features for patterns
+3. **DOCUMENT** - Add `// ASSUMPTION: <explanation>` if you must proceed
+4. **ASK** - Prefer asking user for clarification on business rules
+
+## 8. Dependencies
+
+### DO NOT
+- Add 3rd party packages without checking `apps/mobile/packages/core` first
+- Add `firebase_auth` or `firebase_data_connect` to Feature packages (they belong in `core` only)
+
+### DO
+- Use `ApiService` with `V2ApiEndpoints` for backend operations
+- Use Flutter Modular for dependency injection
+- Register BLoCs with `i.add<CubitType>(() => CubitType(...))` (transient)
+- Register Use Cases as factories or singletons as needed
+
+## 9. Error Handling Pattern
+
+### Domain Failures
+```dart
+// domain/failures/auth_failure.dart
+abstract class AuthFailure extends Failure {
+  const AuthFailure(String message) : super(message);
+}
+
+class InvalidCredentialsFailure extends AuthFailure {
+  const InvalidCredentialsFailure() : super('Invalid credentials');
+}
+```
+
+### Repository Error Mapping
+```dart
+// Map API errors to Domain failures using ApiErrorHandler
+try {
+  final response = await _apiService.get(V2ApiEndpoints.staffProfile(id));
+  return Right(Staff.fromJson(response.data as Map<String, dynamic>));
+} catch (e) {
+  return Left(ApiErrorHandler.mapToFailure(e));
+}
+```
+
+### UI Feedback
+```dart
+// BLoC emits error state
+emit(AuthError(failure));
+
+// UI shows user-friendly message
+if (state is AuthError) {
+  final message = ErrorTranslator.translate(state.failure, context.strings);
+  ScaffoldMessenger.of(context).showSnackBar(
+    SnackBar(content: Text(message)),
+  );
+}
+```
+
+### Session Errors
+`SessionListener` automatically shows dialogs for:
+- Session expiration
+- Token refresh failures
+- Network errors during auth
+
+## 10. Testing Requirements
+
+### Unit Tests
+```dart
+// Test use cases with real repository implementations
+test('login with valid credentials returns user', () async {
+  final useCase = LoginUseCase(repository: mockRepository);
+  final result = await useCase(LoginParams(email: 'test@test.com'));
+  expect(result.isRight(), true);
+});
+```
+
+### Widget Tests
+```dart
+// Test UI widgets and BLoC interactions
+testWidgets('shows loading indicator when logging in', (tester) async {
+  await tester.pumpWidget(
+    BlocProvider<AuthBloc>(
+      create: (_) => authBloc,
+      child: LoginPage(),
+    ),
+  );
+  
+  authBloc.add(LoginRequested(email: 'test@test.com'));
+  await tester.pump();
+  
+  expect(find.byType(LoadingIndicator), findsOneWidget);
+});
+```
+
+### Integration Tests
+- Test full feature flows end-to-end with V2 API
+- Use dependency injection to swap implementations if needed
+
+## 11. Clean Code Principles
+
+### Documentation
+- ✅ Add human readable doc comments for `dartdoc`  for all classes and methods.
+```dart
+/// Authenticates user with email and password.
+/// 
+/// Returns [User] on success or [AuthFailure] on failure.
+/// Throws [NetworkException] if connection fails.
+class LoginUseCase extends UseCase<User, LoginParams> {
+  // ...
+}
+```
+
+### Single Responsibility
+- Keep methods focused on one task
+- Extract complex logic to separate methods
+- Keep widget build methods concise
+- Extract complex widgets to separate files
+
+### Meaningful Names
+```dart
+// ✅ GOOD
+final isProfileComplete = await checkProfileCompletion();
+final userShifts = await fetchUserShifts();
+
+// ❌ BAD
+final flag = await check();
+final data = await fetch();
+```
+
+## Enforcement Checklist
+
+Before merging any mobile feature code:
+
+### Architecture Compliance
+- [ ] Feature follows package structure (domain/data/presentation)
+- [ ] No business logic in BLoCs or Widgets
+- [ ] All state management via BLoCs
+- [ ] All backend access via repositories
+- [ ] Session accessed via SessionStore, not global state
+- [ ] Navigation uses Flutter Modular safe extensions
+- [ ] No feature-to-feature imports
+
+### Code Quality
+- [ ] No hardcoded strings (use localization)
+- [ ] No hardcoded colors/typography (use design system)
+- [ ] All spacing uses UiConstants
+- [ ] Doc comments on public APIs
+- [ ] Meaningful variable names
+- [ ] Zero analyzer warnings
+
+### Integration
+- [ ] V2 API calls via `ApiService` + `V2ApiEndpoints`
+- [ ] Error handling with domain failures
+- [ ] Proper dependency injection in modules
+
+## Summary
+
+The key principle: **Clean Architecture with zero tolerance for violations.** Business logic in Use Cases, state in BLoCs, data access in Repositories (via `ApiService` + `V2ApiEndpoints`), UI in Widgets. Features are isolated, backend access is centralized through the V2 REST API layer, localization is mandatory, and design system is immutable.
+
+When in doubt, refer to existing features following these patterns or ask for clarification. It's better to ask than to introduce architectural debt.

.claude/skills/krow-mobile-release/SKILL.md

@@ -0,0 +1,778 @@
+---
+name: krow-mobile-release
+description: KROW mobile app release process including versioning strategy, CHANGELOG management, GitHub Actions workflows, APK signing, Git tagging, and hotfix procedures. Use this when preparing mobile releases, updating CHANGELOGs, triggering release workflows, creating hotfix branches, troubleshooting release issues, or documenting release features. Covers both staff (worker) and client mobile products across dev/stage/prod environments.
+---
+
+# KROW Mobile Release Process
+
+This skill defines the comprehensive release process for KROW mobile applications (staff and client). It covers versioning, changelog management, GitHub Actions automation, and hotfix procedures.
+
+## When to Use This Skill
+
+- Preparing for a mobile app release
+- Updating CHANGELOG files with new features
+- Triggering GitHub Actions release workflows
+- Creating hotfix branches for production issues
+- Understanding version numbering strategy
+- Setting up APK signing secrets
+- Troubleshooting release workflow failures
+- Documenting release notes
+- Managing release cadence (dev → stage → prod)
+
+## Quick Reference
+
+### Release Workflows
+- **Product Release:** [GitHub Actions - Product Release](https://github.com/Oloodi/krow-workforce/actions/workflows/product-release.yml)
+- **Hotfix Creation:** [GitHub Actions - Product Hotfix](https://github.com/Oloodi/krow-workforce/actions/workflows/hotfix-branch-creation.yml)
+
+### Key Files
+- **Staff CHANGELOG:** `apps/mobile/apps/staff/CHANGELOG.md`
+- **Client CHANGELOG:** `apps/mobile/apps/client/CHANGELOG.md`
+- **Staff Version:** `apps/mobile/apps/staff/pubspec.yaml`
+- **Client Version:** `apps/mobile/apps/client/pubspec.yaml`
+
+### Comprehensive Documentation
+For complete details, see: [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) (900+ lines)
+
+## 1. Versioning Strategy
+
+### Format
+
+```
+v{major}.{minor}.{patch}-{milestone}
+```
+
+**Examples:**
+- `v0.0.1-m4` - Milestone 4 release
+- `v0.1.0-m5` - Minor version bump for Milestone 5
+- `v1.0.0` - First production release (no milestone suffix)
+
+### Semantic Versioning Rules
+
+**Major (X.0.0):**
+- Breaking changes
+- Complete architecture overhaul
+- Incompatible API changes
+
+**Minor (0.X.0):**
+- New features
+- Backwards-compatible additions
+- Milestone completions
+
+**Patch (0.0.X):**
+- Bug fixes
+- Security patches
+- Performance improvements
+
+**Milestone Suffix:**
+- `-m1`, `-m2`, `-m3`, `-m4`, etc.
+- Indicates pre-production milestone phase
+- Removed for production releases
+
+### Version Location
+
+Versions are defined in `pubspec.yaml`:
+
+**Staff App:**
+```yaml
+# apps/mobile/apps/staff/pubspec.yaml
+name: krow_staff_app
+version: 0.0.1-m4+1  # version+build_number
+```
+
+**Client App:**
+```yaml
+# apps/mobile/apps/client/pubspec.yaml
+name: krow_client_app
+version: 0.0.1-m4+1
+```
+
+**Format:** `version+build`
+- `version`: Semantic version with milestone (e.g., `0.0.1-m4`)
+- `build`: Build number (increments with each build, e.g., `+1`, `+2`)
+
+## 2. CHANGELOG Management
+
+### Format
+
+Each app maintains a separate CHANGELOG following [Keep a Changelog](https://keepachangelog.com/) format.
+
+**Structure:**
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- New feature descriptions
+
+### Changed
+- Modified feature descriptions
+
+### Fixed
+- Bug fix descriptions
+
+### Removed
+- Removed feature descriptions
+
+## [0.0.1-m4] - Milestone 4 - 2026-03-05
+
+### Added
+- Profile management with 13 subsections
+- Documents & certificates management
+- Benefits overview section
+- Camera/gallery support for attire verification
+
+### Changed
+- Enhanced session management with auto token refresh
+
+### Fixed
+- Navigation fallback to home on invalid routes
+```
+
+### Section Guidelines
+
+**[Unreleased]**
+- Work in progress
+- Features merged to dev but not released
+- Updated continuously during development
+
+**[Version] - Milestone X - Date**
+- Released version
+- Format: `[X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
+- Organized by change type (Added/Changed/Fixed/Removed)
+
+### Change Type Definitions
+
+**Added:**
+- New features
+- New UI screens
+- New API integrations
+- New user-facing capabilities
+
+**Changed:**
+- Modifications to existing features
+- UI/UX improvements
+- Performance enhancements
+- Refactored code (if user-facing impact)
+
+**Fixed:**
+- Bug fixes
+- Error handling improvements
+- Crash fixes
+- UI/UX issues resolved
+
+**Removed:**
+- Deprecated features
+- Removed screens or capabilities
+- Discontinued integrations
+
+### Writing Guidelines
+
+**✅ GOOD:**
+```markdown
+### Added
+- Profile management with 13 subsections organized into onboarding, compliance, finances, and support categories
+- Documents & certificates management with upload, status tracking, and expiry dates
+- Camera and gallery support for attire verification with photo capture
+- Benefits overview section displaying perks and company information
+```
+
+**❌ BAD:**
+```markdown
+### Added
+- New stuff
+- Fixed things
+- Updated code
+```
+
+**Key Principles:**
+- Be specific and descriptive
+- Focus on user-facing changes
+- Mention UI screens, features, or capabilities
+- Avoid technical jargon users won't understand
+- Group related changes together
+
+### Updating CHANGELOG Workflow
+
+**Step 1:** During development, add to `[Unreleased]`:
+```markdown
+## [Unreleased]
+
+### Added
+- New shift calendar view with month/week toggle
+- Shift acceptance confirmation dialog
+
+### Fixed
+- Navigation crash when popping empty stack
+```
+
+**Step 2:** Before release, move to version section:
+```markdown
+## [0.1.0-m5] - Milestone 5 - 2026-03-15
+
+### Added
+- New shift calendar view with month/week toggle
+- Shift acceptance confirmation dialog
+
+### Fixed
+- Navigation crash when popping empty stack
+
+## [Unreleased]
+<!-- Empty for next development cycle -->
+```
+
+**Step 3:** Update version in `pubspec.yaml`:
+```yaml
+version: 0.1.0-m5+1
+```
+
+## 3. Git Tagging Strategy
+
+### Tag Format
+
+```
+krow-withus-<app>-mobile/<env>-vX.Y.Z
+```
+
+**Components:**
+- `<app>`: `worker` (staff) or `client`
+- `<env>`: `dev`, `stage`, or `prod`
+- `vX.Y.Z`: Semantic version (from pubspec.yaml)
+
+**Examples:**
+```
+krow-withus-worker-mobile/dev-v0.0.1-m4
+krow-withus-worker-mobile/stage-v0.0.1-m4
+krow-withus-worker-mobile/prod-v0.0.1-m4
+krow-withus-client-mobile/dev-v0.0.1-m4
+```
+
+### Tag Creation
+
+Tags are created automatically by GitHub Actions workflows. Manual tagging:
+
+```bash
+# Staff app - dev environment
+git tag krow-withus-worker-mobile/dev-v0.0.1-m4
+git push origin krow-withus-worker-mobile/dev-v0.0.1-m4
+
+# Client app - prod environment
+git tag krow-withus-client-mobile/prod-v1.0.0
+git push origin krow-withus-client-mobile/prod-v1.0.0
+```
+
+### Tag Listing
+
+```bash
+# List all mobile tags
+git tag -l "krow-withus-*-mobile/*"
+
+# List staff app tags
+git tag -l "krow-withus-worker-mobile/*"
+
+# List production tags
+git tag -l "krow-withus-*-mobile/prod-*"
+```
+
+## 4. GitHub Actions Workflows
+
+### 4.1 Product Release Workflow
+
+**File:** `.github/workflows/product-release.yml`
+
+**Purpose:** Automated production releases with APK signing
+
+**Trigger:** Manual dispatch via GitHub UI
+
+**Inputs:**
+- `app`: Select `worker` (staff) or `client`
+- `environment`: Select `dev`, `stage`, or `prod`
+
+**Process:**
+1. ✅ Extracts version from `pubspec.yaml` automatically
+2. ✅ Builds signed APKs for selected app
+3. ✅ Creates GitHub release with CHANGELOG notes
+4. ✅ Tags release (e.g., `krow-withus-worker-mobile/dev-v0.0.1-m4`)
+5. ✅ Uploads APKs as release assets
+6. ✅ Generates step summary with emojis
+
+**Key Features:**
+- **No manual version input** - reads from pubspec.yaml
+- **APK signing** - uses GitHub Secrets for keystore
+- **CHANGELOG extraction** - pulls release notes automatically
+- **Visual feedback** - emojis in all steps
+
+**Usage:**
+```
+1. Go to: GitHub Actions → "📦 Product Release"
+2. Click "Run workflow"
+3. Select app (worker/client)
+4. Select environment (dev/stage/prod)
+5. Click "Run workflow"
+6. Wait for completion (~5-10 minutes)
+```
+
+**Release Naming:**
+```
+Krow With Us - Worker Product - DEV - v0.0.1-m4
+Krow With Us - Client Product - PROD - v1.0.0
+```
+
+### 4.2 Product Hotfix Workflow
+
+**File:** `.github/workflows/hotfix-branch-creation.yml`
+
+**Purpose:** Emergency production fix automation
+
+**Trigger:** Manual dispatch with version input
+
+**Inputs:**
+- `current_version`: Current production version (e.g., `0.0.1-m4`)
+- `issue_description`: Brief description of the hotfix
+
+**Process:**
+1. ✅ Creates `hotfix/<version>` branch from latest production tag
+2. ✅ Auto-increments PATCH version (e.g., `0.0.1-m4` → `0.0.2-m4`)
+3. ✅ Updates `pubspec.yaml` with new version
+4. ✅ Updates `CHANGELOG.md` with hotfix section
+5. ✅ Creates PR back to main branch
+6. ✅ Includes hotfix instructions in PR description
+
+**Usage:**
+```
+1. Go to: GitHub Actions → "🚨 Product Hotfix - Create Branch"
+2. Click "Run workflow"
+3. Enter current production version (e.g., 0.0.1-m4)
+4. Enter issue description (e.g., "critical crash on login")
+5. Click "Run workflow"
+6. Workflow creates branch and PR
+7. Fix bug on hotfix branch
+8. Merge PR to main
+9. Use Product Release workflow to deploy
+```
+
+**Hotfix Branch Naming:**
+```
+hotfix/0.0.2-m4-critical-crash-on-login
+```
+
+### 4.3 Helper Scripts
+
+**Location:** `.github/scripts/`
+
+**Available Scripts:**
+1. **extract-version.sh** - Extract version from pubspec.yaml
+2. **generate-tag-name.sh** - Generate standardized tag names
+3. **extract-release-notes.sh** - Extract CHANGELOG sections
+4. **create-release-summary.sh** - Generate GitHub Step Summary with emojis
+
+**Script Permissions:**
+```bash
+chmod +x .github/scripts/*.sh
+```
+
+**Usage Example:**
+```bash
+# Extract version from staff app
+.github/scripts/extract-version.sh apps/mobile/apps/staff/pubspec.yaml
+
+# Generate tag name
+.github/scripts/generate-tag-name.sh worker dev 0.0.1-m4
+
+# Extract release notes for version
+.github/scripts/extract-release-notes.sh apps/mobile/apps/staff/CHANGELOG.md 0.0.1-m4
+```
+
+## 5. APK Signing Setup
+
+### Required GitHub Secrets (24 Total)
+
+**Per App (12 secrets each):**
+
+**Staff (Worker) App:**
+```
+STAFF_UPLOAD_KEYSTORE_BASE64       # Base64-encoded keystore file
+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 file
+```
+
+**Client App:**
+```
+CLIENT_UPLOAD_KEYSTORE_BASE64
+CLIENT_UPLOAD_STORE_PASSWORD
+CLIENT_UPLOAD_KEY_ALIAS
+CLIENT_UPLOAD_KEY_PASSWORD
+CLIENT_KEYSTORE_PROPERTIES_BASE64
+```
+
+### Generating Secrets
+
+**Step 1: Create Keystore**
+
+```bash
+# For staff app
+keytool -genkey -v \
+  -keystore staff-upload-keystore.jks \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -alias staff-upload
+
+# For client app
+keytool -genkey -v \
+  -keystore client-upload-keystore.jks \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000 \
+  -alias client-upload
+```
+
+**Step 2: Base64 Encode**
+
+```bash
+# Encode keystore
+base64 -i staff-upload-keystore.jks | tr -d '\n' > staff-keystore.txt
+
+# Encode key.properties
+base64 -i key.properties | tr -d '\n' > key-props.txt
+```
+
+**Step 3: Add to GitHub Secrets**
+
+```
+Repository → Settings → Secrets and variables → Actions → New repository secret
+```
+
+Add each secret:
+- Name: `STAFF_UPLOAD_KEYSTORE_BASE64`
+- Value: Contents of `staff-keystore.txt`
+
+Repeat for all 24 secrets.
+
+### key.properties Format
+
+```properties
+storePassword=your_store_password
+keyPassword=your_key_password
+keyAlias=staff-upload
+storeFile=../staff-upload-keystore.jks
+```
+
+## 6. Release Process (Step-by-Step)
+
+### Standard Release (Dev/Stage/Prod)
+
+**Step 1: Prepare CHANGELOG**
+
+Update `CHANGELOG.md` with all changes since last release:
+```markdown
+## [0.1.0-m5] - Milestone 5 - 2026-03-15
+
+### Added
+- Shift calendar with month/week views
+- Enhanced navigation with typed routes
+- Profile completion wizard
+
+### Fixed
+- Session token refresh timing
+- Navigation fallback logic
+```
+
+**Step 2: Update Version**
+
+Edit `pubspec.yaml`:
+```yaml
+version: 0.1.0-m5+1  # Changed from 0.0.1-m4+1
+```
+
+**Step 3: Commit and Push**
+
+```bash
+git add apps/mobile/apps/staff/CHANGELOG.md
+git add apps/mobile/apps/staff/pubspec.yaml
+git commit -m "chore(staff): prepare v0.1.0-m5 release"
+git push origin dev
+```
+
+**Step 4: Trigger Workflow**
+
+1. Go to GitHub Actions → "📦 Product Release"
+2. Click "Run workflow"
+3. Select branch: `dev`
+4. Select app: `worker` (or `client`)
+5. Select environment: `dev` (or `stage`, `prod`)
+6. Click "Run workflow"
+
+**Step 5: Monitor Progress**
+
+Watch workflow execution:
+- ⏳ Version extraction
+- ⏳ APK building
+- ⏳ APK signing
+- ⏳ GitHub Release creation
+- ⏳ Tag creation
+- ⏳ Asset upload
+
+**Step 6: Verify Release**
+
+1. Check GitHub Releases page
+2. Download APK to verify
+3. Install on test device
+4. Verify version in app
+
+### Hotfix Release
+
+**Step 1: Identify Production Issue**
+
+- Critical bug in production
+- User-reported crash
+- Security vulnerability
+
+**Step 2: Trigger Hotfix Workflow**
+
+1. Go to GitHub Actions → "🚨 Product Hotfix - Create Branch"
+2. Click "Run workflow"
+3. Enter current version: `0.0.1-m4`
+4. Enter description: `Critical crash on login screen`
+5. Click "Run workflow"
+
+**Step 3: Review Created Branch**
+
+Workflow creates:
+- Branch: `hotfix/0.0.2-m4-critical-crash-on-login`
+- PR to `main` branch
+- Updated `pubspec.yaml`: `0.0.2-m4+1`
+- Updated `CHANGELOG.md` with hotfix section
+
+**Step 4: Fix Bug**
+
+```bash
+git checkout hotfix/0.0.2-m4-critical-crash-on-login
+
+# Make fixes
+# ... code changes ...
+
+git add .
+git commit -m "fix(auth): resolve crash on login screen"
+git push origin hotfix/0.0.2-m4-critical-crash-on-login
+```
+
+**Step 5: Merge PR**
+
+1. Review PR on GitHub
+2. Approve and merge to `main`
+3. Delete hotfix branch
+
+**Step 6: Release to Production**
+
+1. Use Product Release workflow
+2. Select `main` branch
+3. Select `prod` environment
+4. Deploy hotfix
+
+## 7. Release Cadence
+
+### Development (dev)
+
+- **Frequency:** Multiple times per day
+- **Purpose:** Testing features in dev environment
+- **Branch:** `dev`
+- **Audience:** Internal development team
+- **Approval:** Not required
+
+### Staging (stage)
+
+- **Frequency:** 1-2 times per week
+- **Purpose:** QA testing, stakeholder demos
+- **Branch:** `main`
+- **Audience:** QA team, stakeholders
+- **Approval:** Tech lead approval
+
+### Production (prod)
+
+- **Frequency:** Every 2-3 weeks (milestone completion)
+- **Purpose:** End-user releases
+- **Branch:** `main`
+- **Audience:** All users
+- **Approval:** Product owner + tech lead approval
+
+### Milestone Releases
+
+- **Frequency:** Every 2-4 weeks
+- **Version Bump:** Minor version (e.g., `0.1.0-m5` → `0.2.0-m6`)
+- **Process:**
+  1. Complete all milestone features
+  2. Update CHANGELOG with comprehensive release notes
+  3. Deploy to stage for final QA
+  4. After approval, deploy to prod
+  5. Create GitHub release with milestone summary
+
+## 8. Troubleshooting
+
+### Workflow Fails: Version Extraction
+
+**Error:** "Could not extract version from pubspec.yaml"
+
+**Solutions:**
+1. Verify `pubspec.yaml` exists at expected path
+2. Check version format: `version: X.Y.Z-mN+B`
+3. Ensure no extra spaces or tabs
+4. Verify file is committed and pushed
+
+### Workflow Fails: APK Signing
+
+**Error:** "Keystore password incorrect"
+
+**Solutions:**
+1. Verify GitHub Secrets are set correctly
+2. Re-generate and re-encode keystore
+3. Check key.properties format
+4. Ensure passwords don't contain special characters that need escaping
+
+### Workflow Fails: CHANGELOG Extraction
+
+**Error:** "Could not find version in CHANGELOG"
+
+**Solutions:**
+1. Verify CHANGELOG format matches: `## [X.Y.Z-mN] - Milestone N - YYYY-MM-DD`
+2. Check square brackets are present
+3. Ensure version matches pubspec.yaml
+4. Add version section if missing
+
+### Tag Already Exists
+
+**Error:** "tag already exists"
+
+**Solutions:**
+1. Delete existing tag locally and remotely:
+```bash
+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
+```
+2. Re-run workflow
+
+### Build Fails: Flutter Errors
+
+**Error:** "flutter build failed"
+
+**Solutions:**
+1. Test build locally first:
+```bash
+cd apps/mobile/apps/staff
+flutter build apk --release
+```
+2. Fix any analyzer errors
+3. Ensure all dependencies are compatible
+4. Clear build cache:
+```bash
+flutter clean
+flutter pub get
+```
+
+## 9. Local Testing
+
+Before triggering workflows, test builds locally:
+
+### Building APKs Locally
+
+**Staff App:**
+```bash
+cd apps/mobile/apps/staff
+flutter clean
+flutter pub get
+flutter build apk --release
+```
+
+**Client App:**
+```bash
+cd apps/mobile/apps/client
+flutter clean
+flutter pub get
+flutter build apk --release
+```
+
+### Testing Release Notes
+
+Extract CHANGELOG section:
+```bash
+.github/scripts/extract-release-notes.sh \
+  apps/mobile/apps/staff/CHANGELOG.md \
+  0.0.1-m4
+```
+
+### Verifying Version
+
+Extract version from pubspec:
+```bash
+.github/scripts/extract-version.sh \
+  apps/mobile/apps/staff/pubspec.yaml
+```
+
+## 10. Best Practices
+
+### CHANGELOG
+- ✅ Update continuously during development
+- ✅ Be specific and user-focused
+- ✅ Group related changes
+- ✅ Include UI/UX changes
+- ❌ Don't include technical debt or refactoring (unless user-facing)
+- ❌ Don't use vague descriptions
+
+### Versioning
+- ✅ Use semantic versioning strictly
+- ✅ Increment patch for bug fixes
+- ✅ Increment minor for new features
+- ✅ Keep milestone suffix until production
+- ❌ Don't skip versions
+- ❌ Don't use arbitrary version numbers
+
+### Git Tags
+- ✅ Follow standard format
+- ✅ Let workflow create tags automatically
+- ✅ Keep tags synced with releases
+- ❌ Don't create tags manually unless necessary
+- ❌ Don't reuse deleted tags
+
+### Workflows
+- ✅ Test builds locally first
+- ✅ Monitor workflow execution
+- ✅ Verify release assets
+- ✅ Test APK on device before announcing
+- ❌ Don't trigger multiple workflows simultaneously
+- ❌ Don't bypass approval process
+
+## Summary
+
+**Release Process Overview:**
+1. Update CHANGELOG with changes
+2. Update version in pubspec.yaml
+3. Commit and push to appropriate branch
+4. Trigger Product Release workflow
+5. Monitor execution and verify release
+6. Test APK on device
+7. Announce to team/users
+
+**Key Files:**
+- `apps/mobile/apps/staff/CHANGELOG.md`
+- `apps/mobile/apps/client/CHANGELOG.md`
+- `apps/mobile/apps/staff/pubspec.yaml`
+- `apps/mobile/apps/client/pubspec.yaml`
+
+**Key Workflows:**
+- Product Release (standard releases)
+- Product Hotfix (emergency fixes)
+
+**For Complete Details:**
+See [`docs/RELEASE/mobile-releases.md`](docs/RELEASE/mobile-releases.md) - 900+ line comprehensive guide with:
+- Detailed APK signing setup
+- Complete troubleshooting guide
+- All helper scripts documentation
+- Release checklist
+- Security best practices
+
+When in doubt, refer to the comprehensive documentation or ask for clarification before releasing to production.

.claude/skills/krow-paper-design/SKILL.md

@@ -0,0 +1,597 @@
+---
+name: krow-paper-design
+description: KROW Paper design file conventions covering design tokens, component patterns, screen structure, and naming rules. Use this when creating or updating screens in the Paper design tool, auditing designs for token compliance, building new flows, or restructuring existing frames. Ensures visual consistency across all Paper design files for the KROW staff and client apps.
+---
+
+# KROW Paper Design Conventions
+
+This skill defines the design token system, component patterns, screen structure conventions, and workflow rules established for the KROW Design Revamp Paper file. All design work in Paper must follow these conventions.
+
+## When to Use This Skill
+
+- Creating new screens or flows in Paper
+- Updating existing frames to match the design system
+- Auditing designs for token compliance
+- Adding components (buttons, chips, inputs, badges, cards)
+- Structuring shift detail pages, onboarding flows, or list screens
+- Setting up navigation patterns (back buttons, bottom nav, CTAs)
+- Reviewing Paper designs before handoff to development
+
+## 1. Design Tokens
+
+### Color Palette
+
+**Primary:**
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Background | `#FAFBFC` | Page/artboard background |
+| Foreground | `#121826` | Headings, primary text, dark UI elements |
+| Primary | `#0A39DF` | CTAs, active states, links, selected chips, nav active icons, pay rates |
+| Primary Fg | `#F7FAFC` | Light foreground on primary surfaces |
+
+**Semantic:**
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Secondary | `#F1F3F5` | Subtle backgrounds, dividers, secondary button bg |
+| Accent | `#F9E547` | Highlight, warning chip accents |
+| Text Secondary | `#6A7382` | Labels, captions, inactive nav, section headers, back chevrons |
+| Destructive | `#F04444` | Error states, destructive actions |
+
+**Border & Input:**
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Border | `#D1D5DB` | Card borders, unselected chip borders, outline button borders |
+| Input | `#F5F6F8` | Text input background (read-only/disabled states) |
+
+**Status:**
+| Token | Hex | Usage |
+|-------|-----|-------|
+| Success | `#10B981` | Accept buttons, active status, checkmarks |
+| Info | `#0A39DF` | Informational badges (same as Primary) |
+| Warning | `#D97706` | Urgent/Pending badge text |
+| Neutral | `#94A3B8` | Disabled text, placeholder text |
+| Danger | `#F04444` | Error badges, destructive (same as Destructive) |
+
+**Gradients:**
+| Token | Definition | Usage |
+|-------|-----------|-------|
+| mobileHero | Foreground → Primary → Primary Fg | Hero sections, splash screens |
+| adminHero | Primary → Success | Admin/dashboard hero cards |
+
+### Semantic Badge Colors
+
+| Badge | Background | Text Color |
+|-------|-----------|------------|
+| Active | `#ECFDF5` | `#059669` |
+| Confirmed | `#EBF0FF` | `#0A39DF` |
+| Pending | `#FEF9EE` | `#D97706` |
+| Urgent | `#FEF9EE` | `#D97706` |
+| One-Time | `#ECFDF5` | `#059669` |
+| Recurring | `#EFF6FF` | `#0A39DF` |
+
+### Typography
+
+**Inter Tight — Headings:**
+| Style | Size | Weight | Letter Spacing | Line Height | Usage |
+|-------|------|--------|---------------|-------------|-------|
+| Display | 28px | 700 | -0.02em | 34px | Page titles (Find Shifts, My Shifts) |
+| Heading 1 | 24px | 700 | -0.02em | 30px | Detail page titles (venue names) |
+| Heading 2 | 20px | 700 | -0.01em | 26px | Section headings |
+| Heading 3 | 18px | 700 | -0.01em | 22px | Card titles, schedule values |
+| Heading 4 | 16px | 700 | — | 20px | Card titles (standard cards), sub-headings |
+
+**Manrope — Body:**
+| Style | Size | Weight | Line Height | Usage |
+|-------|------|--------|-------------|-------|
+| Body Large Regular | 16px | 400 | 20px | Long body text |
+| Body Large Medium | 16px | 500 | 20px | Emphasized body text |
+| Body Large Semibold | 16px | 600 | 20px | Strong labels, Full Width CTA text (15px) |
+| Body Default | 14px | 400 | 18px | Body text, descriptions |
+| Body Default Semibold | 14px | 600 | 18px | Button text, chip text, bold body |
+| Caption | 12px | 400 | 16px | Small text, helper text, input labels |
+| Overline Label | 11px | 600 | 14px | Uppercase section headers (letter-spacing: 0.06em) |
+| Badge Text | 11px | 600-700 | 14px | Status badge labels (letter-spacing: 0.04em) |
+| Nav Label | 10px | 600 | 12px | Bottom nav labels |
+
+### Spacing Scale
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Tight spacing (subtitle under title) |
+| sm | 8px | Element gap within groups |
+| md | 12px | Group gap (label to input) |
+| lg | 16px | Card padding, medium section gap |
+| xl | 24px | Page margins, section gap |
+| 2xl | 32px | Large section separation |
+
+**Page Layout:**
+| Token | Value |
+|-------|-------|
+| Page margins | 24px |
+| Section gap | 24px |
+| Card padding | 16px |
+| Element gap | 8-12px |
+| Background | `#FAFBFC` |
+| Bottom safe area | 40px |
+
+### Border Radii
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| sm | 8px | Small chips, badges, status pills |
+| md | 12px | Cards, inputs, list row containers, data rows |
+| lg | 18px | Hero cards, gradient cards |
+| xl | 24px | Large containers |
+| pill | 999px | Progress bar segments only |
+
+### Icon Sizes
+
+Standard sizes: 16, 20, 24, 32dp
+
+## 2. Component Patterns
+
+### Buttons
+
+All buttons: radius 14px, padding 12px/24px, text Manrope 14px/600
+
+**Primary:**
+- Background: `#0A39DF`, text: `#FFFFFF`
+
+**Secondary:**
+- Background: `#F1F3F5`, border: 1.5px `#D1D5DB`, text: `#121826`
+
+**Destructive:**
+- Background: `#F04444`, text: `#FFFFFF`
+
+**Disabled:**
+- Background: `#F1F3F5`, no border, text: `#94A3B8`
+
+**Accept:**
+- Background: `#10B981`, text: `#FFFFFF`
+
+**Dark:**
+- Background: `#121826`, text: `#FFFFFF`
+
+**Full Width CTA:**
+- Same as Primary but `width: 100%`, padding 14px/24px, text Manrope 15px/600
+
+**Back Icon Button (Bottom CTA):**
+- 52x52px square, border: 0.5px `#D1D5DB`, radius: 14px, background: `#FFFFFF`
+- Contains chevron-left SVG (20x20, viewBox 0 0 24 24, stroke `#121826`, strokeWidth 2)
+- Path: `M15 18L9 12L15 6`
+
+### Chips
+
+All chips: border 1.5px, text Manrope 14px/600, gap 8px for icon+text
+
+**Default (Large) - for role/skill selection:**
+- Selected: bg `#EFF6FF`, border `#0A39DF`, radius 10px, padding 12px/16px
+  - Checkmark icon (14x14, stroke `#0A39DF`), text `#0A39DF`
+- Unselected: bg `#FFFFFF`, border `#6A7382`, radius 10px, padding 12px/16px
+  - Text Manrope 14px/500 `#6A7382`
+
+**Warning Chips:**
+- Selected: bg `#F9E5471A`, border `#E6A817`, radius 10px, padding 12px/16px
+  - Checkmark icon (stroke `#E6A817`), text `#E6A817`
+- Unselected: bg `#FFFFFF`, border `#F0D78C`, radius 10px, padding 12px/16px
+  - Text `#E6A817`
+
+**Error Chips:**
+- Selected: bg `#FEF2F2`, border `#F04444`, radius 10px, padding 12px/16px
+  - Checkmark icon (stroke `#F04444`), text `#F04444`
+- Unselected: bg `#FFFFFF`, border `#FECACA`, radius 10px, padding 12px/16px
+  - Text `#F04444`
+
+**Small - for tabs, filters:**
+- Selected: bg `#EFF6FF`, border 1.5px `#0A39DF`, radius 8px, padding 6px/12px
+  - Checkmark icon (12x12), text Manrope 12px/600 `#0A39DF`
+- Unselected: bg `#FFFFFF`, border 1.5px `#D1D5DB`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/500 `#6A7382`
+- Active (filled): bg `#0A39DF`, radius 8px, padding 6px/12px
+  - Text Manrope 12px/600 `#FFFFFF`
+
+**XSmall (Status Chips):**
+- For inline status indicators on list rows, section overviews, and cards
+- Height: ~20px, padding: 3px/8px, no border
+- Text: Manrope 11px/700, uppercase, letter-spacing 0.03-0.04em
+- Variants:
+  - Required/Pending: bg `#FEF9EE`, text `#D97706`, radius 6px
+  - Active/Complete: bg `#ECFDF5`, text `#059669`, radius 6px
+  - Confirmed/Info: bg `#E9F0FF`, text `#0A39DF`, radius 6px
+  - Error/Rejected: bg `#FEF2F2`, text `#F04444`, radius 6px
+  - Neutral/Disabled: bg `#F1F3F5`, text `#94A3B8`, radius 6px
+
+**Status Badges (legacy):**
+- Radius: 8px, padding: 4px/8px
+- Text: Manrope 11px/600-700, uppercase, letter-spacing 0.04em
+- Colors follow semantic badge table above
+- Prefer XSmall Chips for new designs
+
+### Text Inputs
+
+- Border: 1.5px `#E2E8F0`, radius: 12px, padding: 12px/14px
+- Background: `#FFFFFF`
+- Placeholder: Manrope 14px/400, color `#94A3B8`
+- Filled: Manrope 14px/400, color `#111827`
+- Label above: Manrope 12px/400, spacing 0%:
+  - Default/filled: color `#94A3B8`
+  - Filled with value: color `#6A7382`
+  - Focused: color `#0A39DF`
+  - Error: color `#F04444`
+  - Disabled: color `#94A3B8`
+- Focused: border color `#0A39DF`, border-width 2px
+- Error: border color `#F04444`, border-width 2px, background `#FEF2F2`
+- Error helper text: Manrope 12px/400, color `#F04444`
+
+### Border Width
+
+- **Standard border width: `0.5px`** — All card borders, dividers, and outline buttons use `0.5px` unless explicitly stated otherwise.
+- **Text inputs: `1.5px`** — To ensure visibility and distinction from card borders.
+- **Chips: `1.5px`** — All chip variants (default, warning, error, small).
+- **Secondary buttons: `1.5px`** — Outline/secondary button borders.
+
+### Cards
+
+**Standard Card:**
+- Background: `#FFFFFF`, border: 0.5px `#D1D5DB`, radius: 12px, padding: 16px
+- Title: Inter Tight 16px/700 `#121826`
+- Body: Manrope 14px/400 `#6A7382`
+- Gap: 8px between title and body
+
+**Hero / Gradient Card:**
+- Radius: 18px, padding: 20px, gap: 6px
+- Background: gradient (mobileHero or adminHero)
+- Label: Manrope 12px/400 `#FFFFFFB3` (white 70%)
+- Value: Inter Tight 28px/700 `#FFFFFF`
+- Sub-text: Manrope 12px/400 `#FFFFFF99` (white 60%)
+
+**List Rows (grouped):**
+- Container: radius 12px, border 0.5px `#D1D5DB`, background `#FFFFFF`, overflow clip
+- Row: padding ~16px, gap between text elements 2px
+- Row title: Manrope 14px/600 `#121826`
+- Row subtitle: Manrope 13px/400 `#6A7382`
+- Row divider: 1px `#D1D5DB` (between rows, not on last)
+- Chevron: `›` or SVG, `#6A7382`
+
+**Data Row:**
+- Background: `#F1F3F5`, radius: 12px, padding: 12px
+- Label: Manrope 11px/400 `#6A7382`
+- Value: Inter Tight 20px/700 `#121826`
+- Layout: flex row, equal width columns, gap 8px
+
+### Notice Banners
+
+Contextual banners for alerts, warnings, and informational notices. Used in forms, review screens, and detail pages.
+
+- Container: radius 10px, padding 14px, gap 6px, flex column
+- Icon + Title row: flex row, gap 8-10px, align center
+- Icon: 18×18 SVG, same color as text
+- Title: Manrope 14px/600, line-height 18px
+- Body: Manrope 12px/400, line-height 18px
+
+**Variants:**
+| Variant | Background | Color | Title Weight | Icon |
+|---------|-----------|-------|-------------|------|
+| Error | `#FEF2F2` | `#F04444` | 600 | ⊗ (circle-x) |
+| Warning | `#FEF9EE` | `#E6A817` | 600 | △ (triangle-alert) |
+| Info/Notice | `#E9F0FF` | `#0A39DF` | 600 | ⓘ (circle-info) |
+| Success | `#ECFDF5` | `#059669` | 600 | ✓ (circle-check) |
+
+### Contact/Info Rows
+
+- Container: radius 12px, border 0.5px `#D1D5DB`, background `#FFFFFF`, overflow clip
+- Row: padding 13px/16px, gap 10px, border-bottom 0.5px `#F1F3F5` (except last)
+- Icon: 16px, stroke `#6A7382`
+- Label: Manrope 13px/500 `#6A7382`, width 72px fixed
+- Value: Manrope 13px/500 `#121826` (or `#0A39DF` for phone/links)
+
+### Shift Cards
+
+Two variants for displaying shifts in lists. Cards are grouped under month headers.
+
+**Common card container:**
+- Background: `#FFFFFF`, border: 0.5px `#D1D5DB`, radius: 12px, padding: 16px, gap: 12px
+
+**Header row** (top of card):
+- Layout: flex row, space-between
+- Left side: Role title + Venue subtitle (stacked)
+  - Role: Inter Tight 16px/600 `#121826` (primary — always most prominent)
+  - Venue: Manrope 13px/400 `#6A7382`
+- Right side: XSmall status chip (flex-shrink 0)
+
+**Details row** (bottom of card):
+- Layout: flex row, space-between, align start
+- Left column (flex column, gap 6px): date, time, location — each as icon (16px `#6A7382`) + text (Manrope 13px/500-600 `#6A7382`) row with 6px gap
+- Right column (earnings — only in Variant 1)
+
+**Variant 1 — With Earnings (Completed shifts):**
+- Right side shows earnings, right-aligned:
+  - Amount: Inter Tight 14px/600 `#121826` (e.g., "$192.00")
+  - Rate below: Manrope 13px/500 `#6A7382` (e.g., "6 hrs · $32/hr")
+
+**Variant 2 — Without Earnings (Cancelled, No-Show, Upcoming):**
+- No right-side earnings section — details row takes full width
+
+**Status chip variants on shift cards:**
+| Status | Background | Text |
+|--------|-----------|------|
+| Confirmed | `#E9F0FF` | `#0A39DF` |
+| Active | `#ECFDF5` | `#059669` |
+| Pending | `#FEF9EE` | `#D97706` |
+| Completed | `#ECFDF5` | `#059669` |
+| Swap Requested | `#FEF9EE` | `#D97706` |
+| No-Show | `#FEF2F2` | `#F04444` |
+| Cancelled | `#F1F3F5` | `#6A7382` |
+
+### Section Headers
+
+- Text: Manrope 11px/600, uppercase, letter-spacing 0.06em, color `#6A7382`
+- Gap to content below: 10px
+
+## 3. Screen Structure
+
+### Artboard Setup
+
+- Width: 390px (iPhone standard)
+- Height: 844px (default), or `fit-content` for scrollable detail pages
+- Background: `#FAFBFC`
+- Flex column layout, overflow: clip
+
+### Frame Naming Convention
+
+```
+<app>-<section>-<screen_number>-<screen_name>
+```
+
+Examples:
+- `staff-1-1-splash`
+- `staff-2-3-personal-information`
+- `staff-4-1-my-shifts`
+- `staff-5-2-shift-details`
+- `shift-5-3-confirmation`
+
+Section headers use: `<number> - <Section Name>` (e.g., `4 - My Shifts`)
+
+### Status Bar
+
+- Height: 44px, full width (390px)
+- Left: "9:41" text (system font)
+- Right: Signal, WiFi, Battery SVG icons (68px wide)
+
+### Header Back Button
+
+- Placed below status bar in a combined "Status Bar + Back" frame (390x72px)
+- Chevron SVG: 20x20, viewBox 0 0 24 24, stroke `#6A7382`, strokeWidth 2
+- Path: `M15 18L9 12L15 6`
+- Back button frame: 390x28px, padding-left: 24px
+
+### Progress Bar (Onboarding)
+
+- Container: 342px wide (24px margins), 3px height segments
+- Segments: pill radius (999px), gap between
+- Filled: `#0A39DF`, Unfilled: `#F1F3F5`
+
+### Bottom CTA Convention
+
+- Pinned to bottom using `marginTop: auto` on the CTA container
+- Layout: flex row, gap 12px, padding 0 24px
+- Back button: 52x52px icon-only button with chevron-left (stroke `#121826`)
+- Primary CTA: flex 1, height 52px, radius 14px, bg `#0A39DF`
+- Bottom safe padding: 40px (on artboard paddingBottom)
+
+### Bottom Navigation Bar
+
+- Full width, padding: 10px top, 28px bottom
+- Border-top: 1px `#F1F3F5`, background: `#FFFFFF`
+- 5 items: Home, Shifts, Find, Payments, Profile
+- Active: icon stroke `#0A39DF`, label Manrope 10px/600 `#0A39DF`
+- Inactive: icon stroke `#6A7382`, label Manrope 10px/600 `#6A7382`
+- Active icon may have light fill (e.g., `#EBF0FF` on calendar/search)
+
+## 4. Screen Templates
+
+### List Screen (My Shifts, Find Shifts)
+
+```
+Artboard (390x844, bg #FAFBFC)
+  Status Bar (390x44)
+  Header Section
+    Page Title (Display: Inter Tight 28px/700)
+    Tab/Filter Chips (Small chip variant)
+  Content
+    Date Header (Section label style, uppercase)
+    Shift Cards (12px radius, 1px border #D1D5DB)
+  Bottom Nav Bar
+```
+
+### Detail Screen (Shift Details)
+
+```
+Artboard (390x fit-content, bg #FAFBFC)
+  Status Bar (390x44)
+  Header Bar (Back chevron + "Shift Details" title + share icon)
+  Badges Row (status chips)
+  Role Title (H1) + Venue (with avatar)
+  Schedule/Pay Cards (two-column)
+  Job Description (section label + body text)
+  Location (card with map + address)
+  Requirements (section label + checkmark list)
+  Shift Contact (section label + contact card with rows)
+  [Optional] Note from Manager (warm bg card)
+  Bottom CTA (pinned)
+```
+
+### Onboarding Screen
+
+```
+Artboard (390x844, bg #FAFBFC, justify: flex-start, paddingBottom: 40px)
+  Status Bar + Back (390x72)
+  Progress Bar (342px, 3px segments)
+  Step Counter ("Step X of Y" - Body Small)
+  Page Title (H1: Inter Tight 24px/700)
+  [Optional] Subtitle (Body Default)
+  Form Content (inputs, chips, sliders)
+  Bottom CTA (marginTop: auto - back icon + Continue)
+```
+
+### Confirmation Screen
+
+```
+Artboard (390x844, bg #FAFBFC)
+  Status Bar
+  Centered Content
+    Success Icon (green circle + checkmark)
+    Title (Display: Inter Tight 26px/700, centered)
+    Subtitle (Body Default, centered, #6A7382)
+    Details Card (border #D1D5DB, rows with label/value pairs)
+  Bottom CTAs (primary + outline)
+```
+
+## 5. Interaction Patterns
+
+### Modals → Bottom Sheets
+All modal/dialog interactions MUST use bottom sheets, never centered modal dialogs.
+- Sheet: white bg, 18px top-left/top-right radius, padding 24px, bottom safe area 34px
+- Handle bar: 40px wide, 4px height, `#D1D5DB`, centered, 999px radius, 8px margin-bottom
+- Overlay: `rgba(18, 24, 38, 0.55)` scrim behind sheet
+- Title: Inter Tight 20px/700, `#121826`
+- Subtitle: Manrope 13px/400, `#6A7382`
+- Primary CTA: full-width at bottom of sheet
+- Dismiss: "Skip" or "Cancel" text link below CTA, or swipe-down gesture
+
+### Long Lists with Date Filters
+When displaying lists with date filtering (e.g., shift history, timecards, payment history):
+- Group items by **month** (e.g., "MARCH 2026", "FEBRUARY 2026")
+- Month headers use Overline Label style: Manrope 11px/600, uppercase, `#6A7382`, letter-spacing 0.06em
+- Gap: 10px below month header to first item, 24px between month groups
+- Most recent month first (reverse chronological)
+- Date filter at top (chip or dropdown): "Last 30 days", "Last 3 months", "This year", custom range
+
+## 6. Workflow Rules
+
+### Write Incrementally
+
+Each `write_html` call should produce ONE visual group:
+- A header, a card, a single list row, a button bar, a section
+- Never batch an entire screen in one call
+
+### Review Checkpoints
+
+After every 2-3 modifications, take a screenshot and evaluate:
+- **Spacing**: Uneven gaps, cramped groups
+- **Typography**: Hierarchy, readability, correct font/weight
+- **Contrast**: Text legibility, element distinction
+- **Alignment**: Vertical lanes, horizontal alignment
+- **Clipping**: Content cut off at edges
+- **Token compliance**: All values match design system tokens
+
+### Color Audit Process
+
+When updating frames to match the design system:
+1. Get computed styles for all text, background, border elements
+2. Map old colors to design system tokens:
+   - Dark navy (`#0F4C81`, `#1A3A5C`) -> Primary `#0A39DF`
+   - Near-black (`#111827`, `#0F172A`) -> Foreground `#121826`
+   - Gray variants (`#94A3B8`, `#64748B`, `#475569`) -> Text Secondary `#6A7382`
+   - Green accents (`#20B486`) -> Primary `#0A39DF` (for pay) or `#059669` (for status)
+3. Batch update using `update_styles` with multiple nodeIds per style change
+4. Verify with screenshots
+
+### Structural Consistency
+
+When creating matching screens (e.g., two shift detail views):
+- Use identical section ordering
+- Match section header styles (11px/700 uppercase `#6A7382`)
+- Use same card/row component patterns
+- Maintain consistent padding and gap values
+
+## 7. SVG Icon Patterns
+
+### Chevron Left (Back)
+```html
+<svg width="20" height="20" viewBox="0 0 24 24" fill="none">
+  <path d="M15 18L9 12L15 6" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Map Pin
+```html
+<svg width="18" height="18" viewBox="0 0 24 24" fill="none">
+  <path d="M21 10c0 7-9 13-9 13s-9-6-9-13a9 9 0 0 1 18 0z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="10" r="3" stroke="#6A7382" stroke-width="2"/>
+</svg>
+```
+
+### User (Supervisor)
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M20 21v-2a4 4 0 0 0-4-4H8a4 4 0 0 0-4 4v2" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="12" cy="7" r="4" stroke="#6A7382" stroke-width="2"/>
+</svg>
+```
+
+### Phone
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.127.96.361 1.903.7 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.907.339 1.85.573 2.81.7A2 2 0 0 1 22 16.92z" stroke="#6A7382" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Checkmark (Requirement Met)
+```html
+<svg width="16" height="16" viewBox="0 0 24 24" fill="none">
+  <path d="M22 11.08V12a10 10 0 1 1-5.93-9.14" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M22 4L12 14.01l-3-3" stroke="#059669" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+### Chip Checkmark
+```html
+<!-- Large chip (14x14) -->
+<svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+
+<!-- Small chip (12x12) -->
+<svg width="12" height="12" viewBox="0 0 14 14" fill="none">
+  <path d="M2.5 7L5.5 10L11.5 4" stroke="#0A39DF" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+```
+
+## 8. Anti-Patterns
+
+### Colors
+- Never use `#0F4C81`, `#1A3A5C` (old navy) - use `#0A39DF` (Primary)
+- Never use `#111827`, `#0F172A` - use `#121826` (Foreground)
+- Never use `#94A3B8`, `#64748B`, `#475569` - use `#6A7382` (Text Secondary)
+- Never use `#20B486` for pay rates - use `#0A39DF` (Primary)
+- Never use `#E2E8F0` for card borders - use `#D1D5DB` (Border)
+
+### Components
+- Never use pill radius (999px) for chips or badges - use 8px or 10px
+- Never use gradient backgrounds on buttons
+- Never mix font families within a role (headings = Inter Tight, body = Manrope)
+- Never place back buttons at the bottom of frames - always after status bar
+- Never hardcode CTA position - use `marginTop: auto` for bottom pinning
+
+### Structure
+- Never batch an entire screen in one `write_html` call
+- Never skip review checkpoints after 2-3 modifications
+- Never create frames without following the naming convention
+- Never use `justifyContent: space-between` on artboards with many direct children - use `marginTop: auto` on the CTA instead
+- Never use centered modal dialogs — always use bottom sheets for modal interactions
+- Never show long date-filtered lists without grouping by month
+
+## Summary
+
+**The design file is the source of truth for visual direction.** Every element must use the established tokens:
+
+1. **Colors**: 7 core tokens + semantic badge colors
+2. **Typography**: Inter Tight (headings) + Manrope (body), defined scale
+3. **Spacing**: 24px page padding, 16-24px section gaps, 40px bottom safe area
+4. **Radii**: 8px (chips/badges), 12px (cards/inputs), 14px (buttons/CTAs)
+5. **Components**: Buttons, chips (large/small), inputs, cards, badges, nav bars
+6. **Structure**: Status bar > Back > Content > Bottom CTA (pinned)
+7. **Naming**: `<app>-<section>-<number>-<name>`
+
+When in doubt, screenshot an existing screen and match its patterns exactly.

.firebaserc

@@ -0,0 +1,30 @@
+{
+  "projects": {
+    "default": "krow-workforce-dev",
+    "dev": "krow-workforce-dev",
+    "staging": "krow-workforce-staging"
+  },
+  "targets": {
+    "krow-workforce-dev": {
+      "hosting": {
+        "launchpad": [
+          "krow-workforce-dev-launchpad"
+        ],
+        "app-dev": [
+          "krow-workforce-dev"
+        ],
+        "app-staging": [
+          "krow-workforce-staging"
+        ]
+      }
+    },
+    "krow-workforce-staging": {
+      "hosting": {
+        "app-staging": [
+          "krow-workforce-staging"
+        ]
+      }
+    }
+  },
+  "etags": {}
+}

.geminiignore

@@ -0,0 +1,85 @@
+# =============================================================================
+# KROW Workforce - .geminiignore
+#
+# Indicates to Gemini which files/folders to ignore during analysis
+# to maintain relevant context and save tokens.
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Standard Ignores (Same as .gitignore)
+# -----------------------------------------------------------------------------
+node_modules/
+dist/
+build/
+coverage/
+.git/
+.idea/
+.vscode/
+.DS_Store
+secrets/
+.env*
+
+# -----------------------------------------------------------------------------
+# Package Manager Locks (Too large / No semantic value)
+# -----------------------------------------------------------------------------
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+pubspec.lock
+
+# -----------------------------------------------------------------------------
+# Build Artifacts & Caches
+# -----------------------------------------------------------------------------
+.firebase/
+.vite/
+.dart_tool/
+.pub-cache/
+.gradle/
+__pycache__/
+*.tsbuildinfo
+*.cache
+*.log
+
+# -----------------------------------------------------------------------------
+# Large Binary / Media Files
+# -----------------------------------------------------------------------------
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.ico
+*.svg
+*.mp4
+*.mov
+*.pdf
+*.zip
+*.tar.gz
+*.apk
+*.aab
+*.ipa
+
+# -----------------------------------------------------------------------------
+# Generated Code (Reduce noise unless specifically debugging)
+# -----------------------------------------------------------------------------
+# Data Connect generated SDKs are useful for reference, but can be verbose.
+# Uncomment if you want Gemini to ignore them completely.
+# **/dataconnect-generated/
+
+# -----------------------------------------------------------------------------
+# Documentation to KEEP (Force Include)
+# -----------------------------------------------------------------------------
+# Ensure these are never ignored even if a broad rule matches
+!README.md
+!CONTRIBUTING.md
+!docs/*.md
+!docs/**/*.md
+
+# -----------------------------------------------------------------------------
+# Specific Directories
+# -----------------------------------------------------------------------------
+# Prototypes: We WANT Gemini to see these for context if they are synced locally,
+# even if they are ignored by Git. So we do NOT ignore them here.
+
+# Temporary migration folders
+_legacy/
+krow-workforce-export-latest/

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,78 @@
+## 📋 Description
+
+<!-- Provide a clear and concise description of your changes -->
+
+## 🔗 Related Issues
+
+<!-- Link any related issues using #issue_number -->
+
+
+## 🎯 Type of Change
+
+<!-- Mark the relevant option with an "x" -->
+
+- [ ] 🐛 **Bug fix** (non-breaking change that fixes an issue)
+- [ ] ✨ **Feature** (non-breaking change that adds functionality)
+- [ ] 📝 **Documentation** (changes to docs, comments, or README)
+- [ ] 🔧 **Refactor** (code change that doesn't affect functionality)
+- [ ] ⚡ **Performance** (improvement in performance or optimization)
+- [ ] 🔐 **Security** (security fix or improvement)
+- [ ] 🎨 **Style** (formatting, linting, or minor code style changes)
+- [ ] 🏗️ **Architecture** (significant structural changes)
+
+## 📦 Affected Areas
+
+<!-- Mark the relevant areas that were modified -->
+
+- [ ] 📱 **Mobile** (Flutter - Client/Worker app)
+- [ ] 🌐 **Web** (React Dashboard)
+- [ ] 🔌 **Backend** (APIs, Data Connect, Cloud Functions)
+- [ ] 🗄️ **Database** (Schema changes, migrations)
+- [ ] 🚀 **CI/CD** (GitHub Actions, deployment configs)
+- [ ] 📚 **Documentation** (Docs, onboarding guides)
+
+## ✅ Testing
+
+<!-- Describe how you tested these changes -->
+
+**Test Details:**
+<!-- Provide specific test cases or scenarios -->
+
+## 🔄 Breaking Changes
+
+<!-- Are there any breaking changes? If yes, describe them -->
+
+- [ ] No breaking changes
+- [ ] Yes, breaking changes:
+
+**Details:**
+<!-- Describe migration path or deprecation period if applicable -->
+
+## 🎯 Checklist
+
+<!-- Complete this before requesting review -->
+
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex logic
+- [ ] Documentation updated (if applicable)
+- [ ] No new console warnings/errors
+- [ ] Tests pass locally
+- [ ] Branch is up-to-date with `dev`
+- [ ] Commit messages are clear and descriptive
+- [ ] Sensitive data is not committed
+- [ ] Environment variables documented (if added)
+
+## 📝 Additional Notes
+
+<!-- Any additional context, decisions, or considerations -->
+
+## 🔍 Review Checklist for Maintainers
+
+- [ ] Code quality and readability
+- [ ] Design patterns follow project conventions
+- [ ] Performance implications reviewed
+- [ ] Security concerns addressed
+- [ ] Documentation is complete
+- [ ] Breaking changes properly communicated
+- [ ] Cross-platform compatibility (if applicable)

.github/scripts/attach-apk-to-release.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+# =============================================================================
+# Attach APK to GitHub Release
+# =============================================================================
+# This script attaches a built APK to a GitHub Release with proper naming
+#
+# Usage:
+#   ./attach-apk-to-release.sh <tag_name> <app> <app_name> <version> <environment>
+#
+# Arguments:
+#   tag_name    - Git tag name (e.g., krow-withus-worker-mobile/dev-v0.1.0)
+#   app         - worker-mobile-app or client-mobile-app
+#   app_name    - staff or client (internal build folder name)
+#   version     - Version number (e.g., 0.1.0)
+#   environment - dev, stage, or prod
+#
+# Environment Variables:
+#   GH_TOKEN - GitHub token for gh CLI authentication
+# =============================================================================
+
+set -e
+
+TAG_NAME="$1"
+APP="$2"
+APP_NAME="$3"
+VERSION="$4"
+ENV="$5"
+
+if [ -z "$TAG_NAME" ] || [ -z "$APP" ] || [ -z "$APP_NAME" ] || [ -z "$VERSION" ] || [ -z "$ENV" ]; then
+    echo "❌ Error: Missing required arguments" >&2
+    echo "Usage: $0 <tag_name> <app> <app_name> <version> <environment>" >&2
+    exit 1
+fi
+
+# Find APK in build output
+APK_PATH="apps/mobile/apps/${APP_NAME}/build/app/outputs/flutter-apk/app-release.apk"
+
+if [ ! -f "$APK_PATH" ]; then
+    echo "❌ Error: APK not found at $APK_PATH" >&2
+    echo "Searching for APK files..." >&2
+    find apps/mobile/apps/${APP_NAME} -name "*.apk"
+    exit 1
+fi
+
+# Create proper APK name based on app type
+if [ "$APP" = "worker-mobile-app" ]; then
+    APK_NAME="krow-withus-worker-mobile-${ENV}-v${VERSION}.apk"
+else
+    APK_NAME="krow-withus-client-mobile-${ENV}-v${VERSION}.apk"
+fi
+
+# Copy APK with proper name
+cp "$APK_PATH" "/tmp/$APK_NAME"
+
+# Upload to GitHub Release
+echo "📤 Uploading $APK_NAME to release $TAG_NAME..." >&2
+gh release upload "$TAG_NAME" "/tmp/$APK_NAME" --clobber
+
+echo "✅ APK attached to release: $APK_NAME" >&2

.github/scripts/create-release-summary.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Generate release summary for GitHub Actions
+# Usage: ./create-release-summary.sh <app> <environment> <version> <tag_name>
+
+set -e
+
+APP=$1
+ENV=$2
+VERSION=$3
+TAG_NAME=$4
+
+if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ] || [ -z "$TAG_NAME" ]; then
+  echo "❌ Error: Missing required parameters"
+  echo "Usage: ./create-release-summary.sh <app> <environment> <version> <tag_name>"
+  exit 1
+fi
+
+# Determine display names
+if [ "$APP" = "worker-mobile-app" ]; then
+  APP_DISPLAY="Worker Product"
+  APP_EMOJI="👷"
+else
+  APP_DISPLAY="Client Product"
+  APP_EMOJI="💼"
+fi
+
+ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]')
+RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${VERSION}"
+
+# Environment emoji
+case "$ENV" in
+  dev)
+    ENV_EMOJI="🔧"
+    ;;
+  stage)
+    ENV_EMOJI="🎭"
+    ;;
+  prod)
+    ENV_EMOJI="🚀"
+    ;;
+  *)
+    ENV_EMOJI="📦"
+    ;;
+esac
+
+# Generate summary
+cat << EOF >> $GITHUB_STEP_SUMMARY
+## 🎉 Release Created Successfully
+
+### ${APP_EMOJI} Application Details
+- **App:** ${APP_DISPLAY}
+- **Environment:** ${ENV_EMOJI} ${ENV_UPPER}
+- **Version:** \`${VERSION}\`
+- **Tag:** \`${TAG_NAME}\`
+
+### 📦 Release Information
+**Release Name:** ${RELEASE_NAME}
+
+### ✅ Next Steps
+
+1. 🔍 **Verify** the tag and release on GitHub
+2. 🏗️ **Trigger** CodeMagic build (if configured)
+3. 📱 **Monitor** app store deployment
+4. 📚 **Update** project documentation if needed
+5. 🎯 **Communicate** release to stakeholders
+
+### 🔗 Quick Links
+- [View Tag](../../releases/tag/${TAG_NAME})
+- [Release Documentation](../../docs/release/MOBILE_RELEASE_PLAN.md)
+- [CHANGELOG](../../apps/mobile/apps/${APP}/CHANGELOG.md)
+EOF
+
+echo "✅ Summary generated successfully"

.github/scripts/extract-release-notes.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+# Extract release notes from CHANGELOG for a specific version
+# Usage: ./extract-release-notes.sh <app> <version> <environment> <tag_name> <output_file>
+
+set -e
+
+APP=$1
+VERSION=$2
+ENV=$3
+TAG_NAME=$4
+OUTPUT_FILE=$5
+
+if [ -z "$APP" ] || [ -z "$VERSION" ] || [ -z "$ENV" ] || [ -z "$TAG_NAME" ] || [ -z "$OUTPUT_FILE" ]; then
+  echo "❌ Error: Missing required parameters" >&2
+  echo "Usage: ./extract-release-notes.sh <app> <version> <environment> <tag_name> <output_file>" >&2
+  exit 1
+fi
+
+# Determine CHANGELOG path and app name
+if [ "$APP" = "worker-mobile-app" ]; then
+  CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md"
+  APP_NAME="Staff Product (Worker)"
+else
+  CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md"
+  APP_NAME="Client Product"
+fi
+
+# Try to extract release notes for this version
+if [ -f "$CHANGELOG_PATH" ]; then
+  echo "📝 Found CHANGELOG at $CHANGELOG_PATH" >&2
+  
+  # Extract section for this version
+  # Look for ## [vVERSION] or ## [VERSION] and collect content until next ## [ header
+  # Try with 'v' prefix first (common format), then without
+  CHANGELOG_CONTENT=$(awk "/^## \[v${VERSION}\]/{flag=1; next} /^## \[/{flag=0} flag" "$CHANGELOG_PATH")
+  
+  # If still empty, try without 'v' prefix
+  if [ -z "$CHANGELOG_CONTENT" ]; then
+    CHANGELOG_CONTENT=$(awk "/^## \[${VERSION}\]/{flag=1; next} /^## \[/{flag=0} flag" "$CHANGELOG_PATH")
+  fi
+  
+  if [ -z "$CHANGELOG_CONTENT" ]; then
+    echo "⚠️ Warning: No CHANGELOG entry found for version $VERSION" >&2
+    NOTES="**Environment:** $ENV
+**Tag:** $TAG_NAME
+
+## What is new in this release
+
+⚠️ No CHANGELOG entry found for this version. Please update the CHANGELOG manually."
+  else
+    echo "✅ Extracted release notes for version $VERSION" >&2
+    NOTES="**Environment:** $ENV
+**Tag:** $TAG_NAME
+
+## What is new in this release
+
+$CHANGELOG_CONTENT"
+  fi
+else
+  echo "⚠️ Warning: CHANGELOG not found at $CHANGELOG_PATH" >&2
+  NOTES="**Environment:** $ENV
+**Tag:** $TAG_NAME
+
+## What is new in this release
+
+⚠️ CHANGELOG file not found at $CHANGELOG_PATH"
+fi
+
+# Save to output file
+echo "$NOTES" > "$OUTPUT_FILE"
+echo "✅ Release notes saved to $OUTPUT_FILE" >&2

.github/scripts/extract-version.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Extract version from version file for products
+# Usage: ./extract-version.sh <app>
+# app: worker-mobile-app or client-mobile-app
+
+set -e
+
+APP=$1
+
+if [ -z "$APP" ]; then
+  echo "❌ Error: App parameter required (worker-mobile-app or client-mobile-app)" >&2
+  exit 1
+fi
+
+# Determine pubspec path
+if [ "$APP" = "worker-mobile-app" ]; then
+  PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml"
+  APP_NAME="Staff Product (Worker)"
+else
+  PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml"
+  APP_NAME="Client Product"
+fi
+
+# Check if pubspec exists
+if [ ! -f "$PUBSPEC_PATH" ]; then
+  echo "❌ Error: pubspec.yaml not found at $PUBSPEC_PATH" >&2
+  echo "📁 Current directory: $(pwd)" >&2
+  echo "📂 Directory contents:" >&2
+  ls -la apps/mobile/apps/ 2>&1 | head -20 >&2
+  exit 1
+fi
+
+# Extract version (format: X.Y.Z+buildNumber or X.Y.Z-suffix)
+VERSION_LINE=$(grep "^version:" "$PUBSPEC_PATH")
+if [ -z "$VERSION_LINE" ]; then
+  echo "❌ Error: Could not find version in $PUBSPEC_PATH" >&2
+  exit 1
+fi
+
+# Extract full version including suffix/build number
+VERSION=$(echo "$VERSION_LINE" | sed 's/version: *//' | tr -d ' ')
+
+# Validate version format (X.Y.Z with optional +build or -suffix)
+# Use grep for better portability across different bash versions
+if ! echo "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(\+[a-zA-Z0-9]+|-[a-zA-Z0-9]+)?$'; then
+  echo "❌ Error: Invalid version format in pubspec.yaml: $VERSION" >&2
+  echo "Expected format: X.Y.Z, X.Y.Z+build, or X.Y.Z-suffix (e.g., 0.1.0, 0.1.0+12, 0.1.0-m3)" >&2
+  exit 1
+fi
+
+echo "✅ Extracted version from $PUBSPEC_PATH: $VERSION" >&2
+echo "$VERSION"

.github/scripts/generate-tag-name.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Generate tag name for product release
+# Usage: ./generate-tag-name.sh <app> <environment> <version>
+
+set -e
+
+APP=$1
+ENV=$2
+VERSION=$3
+
+if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ]; then
+  echo "❌ Error: Missing required parameters" >&2
+  echo "Usage: ./generate-tag-name.sh <app> <environment> <version>" >&2
+  exit 1
+fi
+
+# Strip -mobile-app suffix from app name for cleaner tag names
+# worker-mobile-app -> worker, client-mobile-app -> client
+APP_TAG=$(echo "$APP" | sed 's/-mobile-app$//')
+
+TAG_NAME="krow-withus-${APP_TAG}-mobile/${ENV}-v${VERSION}"
+echo "$TAG_NAME"

.github/scripts/setup-apk-signing.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+
+# =============================================================================
+# Setup APK Signing for GitHub Actions
+# =============================================================================
+# This script configures Android APK signing by decoding keystores from
+# GitHub Secrets and setting up environment variables for build.gradle.kts
+#
+# Usage:
+#   ./setup-apk-signing.sh <app> <environment> <temp_dir>
+#
+# Arguments:
+#   app         - worker-mobile-app or client-mobile-app
+#   environment - dev, stage, or prod
+#   temp_dir    - Temporary directory for keystore files (e.g., ${{ runner.temp }})
+#
+# Environment Variables (must be set):
+#   WORKER_KEYSTORE_DEV_BASE64, WORKER_KEYSTORE_STAGING_BASE64, WORKER_KEYSTORE_PROD_BASE64
+#   WORKER_KEYSTORE_PASSWORD_DEV, WORKER_KEYSTORE_PASSWORD_STAGING, WORKER_KEYSTORE_PASSWORD_PROD
+#   WORKER_KEY_ALIAS_DEV, WORKER_KEY_ALIAS_STAGING, WORKER_KEY_ALIAS_PROD
+#   WORKER_KEY_PASSWORD_DEV, WORKER_KEY_PASSWORD_STAGING, WORKER_KEY_PASSWORD_PROD
+#   CLIENT_KEYSTORE_DEV_BASE64, CLIENT_KEYSTORE_STAGING_BASE64, CLIENT_KEYSTORE_PROD_BASE64
+#   CLIENT_KEYSTORE_PASSWORD_DEV, CLIENT_KEYSTORE_PASSWORD_STAGING, CLIENT_KEYSTORE_PASSWORD_PROD
+#   CLIENT_KEY_ALIAS_DEV, CLIENT_KEY_ALIAS_STAGING, CLIENT_KEY_ALIAS_PROD
+#   CLIENT_KEY_PASSWORD_DEV, CLIENT_KEY_PASSWORD_STAGING, CLIENT_KEY_PASSWORD_PROD
+# =============================================================================
+
+set -e
+
+APP="$1"
+ENV="$2"
+TEMP_DIR="$3"
+
+if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$TEMP_DIR" ]; then
+    echo "❌ Error: Missing required arguments" >&2
+    echo "Usage: $0 <app> <environment> <temp_dir>" >&2
+    exit 1
+fi
+
+echo "🔐 Setting up Android signing for $APP in $ENV environment..." >&2
+
+# Determine which keystore to use
+if [ "$APP" = "worker-mobile-app" ]; then
+    APP_TYPE="WORKER"
+    APP_NAME="STAFF"  # CodeMagic uses STAFF in env var names
+else
+    APP_TYPE="CLIENT"
+    APP_NAME="CLIENT"
+fi
+
+# Convert environment to uppercase for env var names
+ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]')
+if [ "$ENV_UPPER" = "STAGE" ]; then
+    ENV_UPPER="STAGING"  # CodeMagic uses STAGING instead of STAGE
+fi
+
+# Get the keystore secret name dynamically
+KEYSTORE_BASE64_VAR="${APP_TYPE}_KEYSTORE_${ENV_UPPER}_BASE64"
+KEYSTORE_PASSWORD_VAR="${APP_TYPE}_KEYSTORE_PASSWORD_${ENV_UPPER}"
+KEY_ALIAS_VAR="${APP_TYPE}_KEY_ALIAS_${ENV_UPPER}"
+KEY_PASSWORD_VAR="${APP_TYPE}_KEY_PASSWORD_${ENV_UPPER}"
+
+# Get values using indirect expansion
+KEYSTORE_BASE64="${!KEYSTORE_BASE64_VAR}"
+KEYSTORE_PASSWORD="${!KEYSTORE_PASSWORD_VAR}"
+KEY_ALIAS="${!KEY_ALIAS_VAR}"
+KEY_PASSWORD="${!KEY_PASSWORD_VAR}"
+
+# Check if secrets are configured
+if [ -z "$KEYSTORE_BASE64" ]; then
+    echo "⚠️  WARNING: Keystore secret $KEYSTORE_BASE64_VAR is not configured!" >&2
+    echo "⚠️  APK will be built UNSIGNED for $ENV environment." >&2
+    echo "⚠️  Please configure GitHub Secrets as documented in docs/RELEASE/APK_SIGNING_SETUP.md" >&2
+    exit 0
+fi
+
+# Create temporary directory for keystore
+KEYSTORE_DIR="${TEMP_DIR}/keystores"
+mkdir -p "$KEYSTORE_DIR"
+KEYSTORE_PATH="$KEYSTORE_DIR/release.jks"
+
+# Decode keystore from base64
+echo "$KEYSTORE_BASE64" | base64 -d > "$KEYSTORE_PATH"
+
+if [ ! -f "$KEYSTORE_PATH" ]; then
+    echo "❌ Failed to decode keystore!" >&2
+    exit 1
+fi
+
+echo "✅ Keystore decoded successfully" >&2
+echo "📦 Keystore size: $(ls -lh "$KEYSTORE_PATH" | awk '{print $5}')" >&2
+
+# Export environment variables for build.gradle.kts
+# Note: build.gradle.kts expects variables WITHOUT app suffix
+echo "CI=true" >> $GITHUB_ENV
+echo "CM_KEYSTORE_PATH=$KEYSTORE_PATH" >> $GITHUB_ENV
+echo "CM_KEYSTORE_PASSWORD=$KEYSTORE_PASSWORD" >> $GITHUB_ENV
+echo "CM_KEY_ALIAS=$KEY_ALIAS" >> $GITHUB_ENV
+echo "CM_KEY_PASSWORD=$KEY_PASSWORD" >> $GITHUB_ENV
+
+echo "✅ Signing environment configured for $APP_NAME ($ENV environment)" >&2
+echo "🔑 Using key alias: $KEY_ALIAS" >&2
+echo "📝 Environment variables exported:" >&2
+echo "   - CI=true" >&2
+echo "   - CM_KEYSTORE_PATH=$KEYSTORE_PATH" >&2
+echo "   - CM_KEY_ALIAS=$KEY_ALIAS" >&2

.github/scripts/setup-mobile-github-secrets.sh

@@ -0,0 +1,262 @@
+#!/bin/bash
+
+# =============================================================================
+# GitHub Secrets Setup Helper
+# =============================================================================
+# This script helps you configure GitHub Secrets for APK signing
+# 
+# Usage:
+#   ./setup-mobile-github-secrets.sh
+#
+# Reference: docs/RELEASE/APK_SIGNING_SETUP.md
+# =============================================================================
+
+set -e
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "$REPO_ROOT"
+
+echo "🔐 GitHub Secrets Setup Helper for APK Signing"
+echo "================================================"
+echo ""
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Track successful secret generations
+SECRETS_FOUND=0
+TOTAL_SECRETS=24
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+print_secret_config() {
+    local app=$1
+    local env=$2
+    local keystore_path=$3
+    local password=$4
+    local alias=$5
+    local key_password=$6
+    
+    local app_upper=$(echo "$app" | tr '[:lower:]' '[:upper:]')
+    local env_upper=$(echo "$env" | tr '[:lower:]' '[:upper:]')
+    
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "  ${app_upper} Mobile - ${env_upper} Environment"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    
+    if [ -f "$keystore_path" ]; then
+        echo -e "${GREEN}✅ Keystore found:${NC} $keystore_path"
+        
+        # Show keystore info
+        echo ""
+        echo "📋 Keystore Information:"
+        keytool -list -v -keystore "$keystore_path" -storepass "$password" 2>/dev/null | head -n 15 || echo "  (Use keytool to inspect)"
+        
+        # Generate base64
+        echo ""
+        echo "📦 Base64 Encoded Keystore:"
+        echo ""
+        BASE64_OUTPUT=$(base64 -i "$keystore_path")
+        echo "$BASE64_OUTPUT"
+        echo ""
+        
+        echo "GitHub Secrets to create:"
+        echo ""
+        echo "  ${app_upper}_KEYSTORE_${env_upper}_BASE64"
+        echo "  ${app_upper}_KEYSTORE_PASSWORD_${env_upper} = $password"
+        echo "  ${app_upper}_KEY_ALIAS_${env_upper}         = $alias"
+        echo "  ${app_upper}_KEY_PASSWORD_${env_upper}      = $key_password"
+        echo ""
+        
+        # Increment success counter (4 secrets per keystore)
+        SECRETS_FOUND=$((SECRETS_FOUND + 4))
+        
+    else
+        echo -e "${YELLOW}⚠️  Keystore not found:${NC} $keystore_path"
+        echo ""
+        echo "This keystore should be stored securely (CodeMagic or secure storage)."
+        echo ""
+    fi
+}
+
+# =============================================================================
+# Worker Mobile (Staff App)
+# =============================================================================
+
+echo ""
+echo "═══════════════════════════════════════════════════════"
+echo "  WORKER MOBILE (Staff App) Configuration"
+echo "═══════════════════════════════════════════════════════"
+
+# DEV Environment
+print_secret_config \
+    "worker" \
+    "dev" \
+    "$REPO_ROOT/apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks" \
+    "krowwithus" \
+    "krow_staff_dev" \
+    "krowwithus"
+
+# STAGING Environment
+print_secret_config \
+    "worker" \
+    "staging" \
+    "$REPO_ROOT/keystores/krow_staff_staging.jks" \
+    "YOUR_STAGING_PASSWORD" \
+    "krow_staff_staging" \
+    "YOUR_STAGING_KEY_PASSWORD"
+
+# PROD Environment
+print_secret_config \
+    "worker" \
+    "prod" \
+    "$REPO_ROOT/keystores/krow_staff_prod.jks" \
+    "YOUR_PROD_PASSWORD" \
+    "krow_staff_prod" \
+    "YOUR_PROD_KEY_PASSWORD"
+
+# =============================================================================
+# Client Mobile
+# =============================================================================
+
+echo ""
+echo "═══════════════════════════════════════════════════════"
+echo "  CLIENT MOBILE Configuration"
+echo "═══════════════════════════════════════════════════════"
+
+# DEV Environment
+print_secret_config \
+    "client" \
+    "dev" \
+    "$REPO_ROOT/apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks" \
+    "krowwithus" \
+    "krow_client_dev" \
+    "krowwithus"
+
+# STAGING Environment
+print_secret_config \
+    "client" \
+    "staging" \
+    "$REPO_ROOT/keystores/krow_client_staging.jks" \
+    "YOUR_STAGING_PASSWORD" \
+    "krow_client_staging" \
+    "YOUR_STAGING_KEY_PASSWORD"
+
+# PROD Environment
+print_secret_config \
+    "client" \
+    "prod" \
+    "$REPO_ROOT/keystores/krow_client_prod.jks" \
+    "YOUR_PROD_PASSWORD" \
+    "krow_client_prod" \
+    "YOUR_PROD_KEY_PASSWORD"
+
+# =============================================================================
+# Summary
+# =============================================================================
+
+echo ""
+echo "═══════════════════════════════════════════════════════"
+echo "  SUMMARY"
+echo "═══════════════════════════════════════════════════════"
+echo ""
+echo "Total secrets needed: ${TOTAL_SECRETS}"
+echo "Secrets successfully generated: ${SECRETS_FOUND}"
+echo ""
+echo "  • 6 keystores (base64 encoded)"
+echo "  • 6 keystore passwords"
+echo "  • 6 key aliases"
+echo "  • 6 key passwords"
+echo ""
+
+if [ $SECRETS_FOUND -gt 0 ]; then
+    echo "Generated secrets to add to GitHub:"
+    echo ""
+    
+    # Worker Dev Secrets
+    if [ -f "$REPO_ROOT/apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks" ]; then
+        echo "  ✅ WORKER_KEYSTORE_DEV_BASE64"
+        echo "     $(base64 -i "$REPO_ROOT/apps/mobile/apps/staff/android/app/krow_with_us_staff_dev.jks")"
+        echo ""
+        echo "  ✅ WORKER_KEYSTORE_PASSWORD_DEV"
+        echo "     krowwithus"
+        echo ""
+        echo "  ✅ WORKER_KEY_ALIAS_DEV"
+        echo "     krow_staff_dev"
+        echo ""
+        echo "  ✅ WORKER_KEY_PASSWORD_DEV"
+        echo "     krowwithus"
+        echo ""
+    fi
+    
+    # Client Dev Secrets
+    if [ -f "$REPO_ROOT/apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks" ]; then
+        echo "  ✅ CLIENT_KEYSTORE_DEV_BASE64"
+        echo "     $(base64 -i "$REPO_ROOT/apps/mobile/apps/client/android/app/krow_with_us_client_dev.jks")"
+        echo ""
+        echo "  ✅ CLIENT_KEYSTORE_PASSWORD_DEV"
+        echo "     krowwithus"
+        echo ""
+        echo "  ✅ CLIENT_KEY_ALIAS_DEV"
+        echo "     krow_client_dev"
+        echo ""
+        echo "  ✅ CLIENT_KEY_PASSWORD_DEV"
+        echo "     krowwithus"
+        echo ""
+    fi
+fi
+
+if [ $SECRETS_FOUND -lt $TOTAL_SECRETS ]; then
+    echo "Missing secrets (keystores not found):"
+    echo ""
+    
+    if [ ! -f "$REPO_ROOT/keystores/krow_staff_staging.jks" ]; then
+        echo "  ⚠️  WORKER_KEYSTORE_STAGING_BASE64"
+        echo "  ⚠️  WORKER_KEYSTORE_PASSWORD_STAGING"
+        echo "  ⚠️  WORKER_KEY_ALIAS_STAGING"
+        echo "  ⚠️  WORKER_KEY_PASSWORD_STAGING"
+    fi
+    
+    if [ ! -f "$REPO_ROOT/keystores/krow_staff_prod.jks" ]; then
+        echo "  ⚠️  WORKER_KEYSTORE_PROD_BASE64"
+        echo "  ⚠️  WORKER_KEYSTORE_PASSWORD_PROD"
+        echo "  ⚠️  WORKER_KEY_ALIAS_PROD"
+        echo "  ⚠️  WORKER_KEY_PASSWORD_PROD"
+    fi
+    
+    if [ ! -f "$REPO_ROOT/keystores/krow_client_staging.jks" ]; then
+        echo "  ⚠️  CLIENT_KEYSTORE_STAGING_BASE64"
+        echo "  ⚠️  CLIENT_KEYSTORE_PASSWORD_STAGING"
+        echo "  ⚠️  CLIENT_KEY_ALIAS_STAGING"
+        echo "  ⚠️  CLIENT_KEY_PASSWORD_STAGING"
+    fi
+    
+    if [ ! -f "$REPO_ROOT/keystores/krow_client_prod.jks" ]; then
+        echo "  ⚠️  CLIENT_KEYSTORE_PROD_BASE64"
+        echo "  ⚠️  CLIENT_KEYSTORE_PASSWORD_PROD"
+        echo "  ⚠️  CLIENT_KEY_ALIAS_PROD"
+        echo "  ⚠️  CLIENT_KEY_PASSWORD_PROD"
+    fi
+    
+    echo ""
+    echo "Retrieve missing keystores from CodeMagic Team Settings or secure storage."
+fi
+
+echo ""
+echo "To configure GitHub Secrets:"
+echo ""
+echo "  1. Go to: https://github.com/Oloodi/krow-workforce/settings/secrets/actions"
+echo "  2. Click 'New repository secret'"
+echo "  3. Add each secret listed above"
+echo ""
+echo "For complete documentation, see:"
+echo "  docs/RELEASE/APK_SIGNING_SETUP.md"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""

.github/scripts/verify-apk-signature.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+# =============================================================================
+# Verify APK Signature
+# =============================================================================
+# This script verifies that an APK is properly signed and displays
+# certificate information
+#
+# Usage:
+#   ./verify-apk-signature.sh <apk_path>
+#
+# Arguments:
+#   apk_path - Path to the APK file to verify
+# =============================================================================
+
+set -e
+
+APK_PATH="$1"
+
+if [ -z "$APK_PATH" ]; then
+    echo "❌ Error: Missing APK path" >&2
+    echo "Usage: $0 <apk_path>" >&2
+    exit 1
+fi
+
+if [ ! -f "$APK_PATH" ]; then
+    echo "❌ APK not found at: $APK_PATH" >&2
+    exit 1
+fi
+
+echo "🔍 Verifying APK signature..." >&2
+
+# Check if APK is signed
+if jarsigner -verify -verbose "$APK_PATH" 2>&1 | grep -q "jar verified"; then
+    echo "✅ APK is properly signed!" >&2
+    
+    # Extract certificate details
+    echo "" >&2
+    echo "📜 Certificate Details:" >&2
+    jarsigner -verify -verbose -certs "$APK_PATH" 2>&1 | grep -A 3 "X.509" || true
+    
+    # Get signer info
+    echo "" >&2
+    echo "🔑 Signer Information:" >&2
+    keytool -printcert -jarfile "$APK_PATH" | head -n 15
+    
+else
+    echo "⚠️  WARNING: APK signature verification failed or APK is unsigned!" >&2
+    echo "" >&2
+    echo "This may happen if:" >&2
+    echo "  1. GitHub Secrets are not configured for this environment" >&2
+    echo "  2. Keystore credentials are incorrect" >&2
+    echo "  3. Build configuration didn't apply signing" >&2
+    echo "" >&2
+    echo "See: docs/RELEASE/APK_SIGNING_SETUP.md for setup instructions" >&2
+    
+    # Don't fail the build, just warn
+    # exit 1
+fi

.github/workflows/backend-foundation.yml

@@ -0,0 +1,67 @@
+name: Backend Foundation
+
+on:
+  workflow_dispatch: # Manual trigger only — auto-triggers disabled (free plan)
+  workflow_dispatch:
+
+jobs:
+  backend-foundation-makefile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate backend make targets
+        run: |
+          make backend-help
+          make help | grep "backend-"
+
+      - name: Dry-run backend automation targets
+        run: |
+          make -n backend-enable-apis ENV=dev
+          make -n backend-bootstrap-dev ENV=dev
+          make -n backend-deploy-core ENV=dev
+          make -n backend-deploy-commands ENV=dev
+          make -n backend-deploy-workers ENV=dev
+          make -n backend-smoke-core ENV=dev
+          make -n backend-smoke-commands ENV=dev
+          make -n backend-logs-core ENV=dev
+          make -n backend-bootstrap-v2-dev ENV=dev
+          make -n backend-deploy-core-v2 ENV=dev
+          make -n backend-deploy-commands-v2 ENV=dev
+          make -n backend-deploy-query-v2 ENV=dev
+          make -n backend-smoke-core-v2 ENV=dev
+          make -n backend-smoke-commands-v2 ENV=dev
+          make -n backend-smoke-query-v2 ENV=dev
+          make -n backend-logs-core-v2 ENV=dev
+
+  backend-services-tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        service:
+          - backend/core-api
+          - backend/command-api
+          - backend/query-api
+    defaults:
+      run:
+        working-directory: ${{ matrix.service }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: ${{ matrix.service }}/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        env:
+          AUTH_BYPASS: "true"
+          LLM_MOCK: "true"
+        run: npm test

.github/workflows/hotfix-branch-creation.yml

@@ -0,0 +1,332 @@
+name: 🚨 Hotfix Branch Creation
+
+on:
+  workflow_dispatch:
+    inputs:
+      app:
+        description: '📦 Product'
+        required: true
+        type: choice
+        options:
+          - worker-mobile-app
+          - client-mobile-app
+      tag:
+        description: '🏷️ Current Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0 or dev/stage)'
+        required: true
+        type: string
+      issue_description:
+        description: '📝 Brief issue description'
+        required: true
+        type: string
+
+jobs:
+  create-hotfix-branch:
+    name: 🚨 Create Hotfix Branch
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          
+      - name: 🔍 Validate tag exists
+        id: validate_tag
+        run: |
+          TAG="${{ github.event.inputs.tag }}"
+          
+          if ! git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "❌ Error: Tag '$TAG' does not exist"
+            echo "Available tags:"
+            git tag -l "krow-withus-*-mobile/*" | tail -20
+            exit 1
+          fi
+          
+          echo "✅ Tag exists: $TAG"
+          
+          # Extract version from tag
+          VERSION=$(echo "$TAG" | grep -oP 'v\K[0-9]+\.[0-9]+\.[0-9]+' || echo "")
+          if [ -z "$VERSION" ]; then
+            echo "❌ Error: Could not extract version from tag"
+            exit 1
+          fi
+          
+          echo "current_version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "📌 Current version: $VERSION"
+          
+      - name: 🔢 Calculate hotfix version
+        id: hotfix_version
+        run: |
+          CURRENT="${{ steps.validate_tag.outputs.current_version }}"
+          
+          # Split version into parts
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+          
+          # Increment PATCH version
+          NEW_PATCH=$((PATCH + 1))
+          HOTFIX_VERSION="${MAJOR}.${MINOR}.${NEW_PATCH}"
+          
+          echo "hotfix_version=${HOTFIX_VERSION}" >> $GITHUB_OUTPUT
+          echo "🆕 Hotfix version: $HOTFIX_VERSION"
+          
+      - name: 🌿 Generate branch name
+        id: branch
+        run: |
+          APP="${{ github.event.inputs.app }}"
+          VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          
+          # Strip -mobile-app suffix for cleaner branch names
+          APP_CLEAN=$(echo "$APP" | sed 's/-mobile-app$//')
+          
+          BRANCH_NAME="hotfix/krow-withus-${APP_CLEAN}-mobile-v${VERSION}"
+          echo "branch_name=${BRANCH_NAME}" >> $GITHUB_OUTPUT
+          echo "🌿 Branch to create: $BRANCH_NAME"
+          
+      - name: 🔍 Check if hotfix branch already exists
+        run: |
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          
+          if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
+            echo "❌ Error: Branch $BRANCH already exists"
+            exit 1
+          fi
+          
+          echo "✅ Branch does not exist, proceeding..."
+          
+      - name: 🌿 Create hotfix branch from tag
+        run: |
+          TAG="${{ github.event.inputs.tag }}"
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Checkout the tag
+          git checkout "$TAG"
+          
+          # Create new branch
+          git checkout -b "$BRANCH"
+          
+          echo "✅ Created branch $BRANCH from tag $TAG"
+          
+      - name: 📝 Update version files
+        id: update_versions
+        run: |
+          APP="${{ github.event.inputs.app }}"
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          
+          if [ "$APP" = "worker-mobile-app" ]; then
+            PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml"
+            CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md"
+            APP_NAME="Staff Product"
+          else
+            PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml"
+            CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md"
+            APP_NAME="Client Product"
+          fi
+          
+          # Update pubspec.yaml version
+          if [ -f "$PUBSPEC_PATH" ]; then
+            # Extract current version and build number
+            CURRENT_VERSION_LINE=$(grep "^version:" "$PUBSPEC_PATH")
+            CURRENT_BUILD=$(echo "$CURRENT_VERSION_LINE" | grep -oP '\+\K[0-9]+' || echo "1")
+            NEW_BUILD=$((CURRENT_BUILD + 1))
+            
+            # Update version line
+            sed -i "s/^version:.*/version: ${HOTFIX_VERSION}+${NEW_BUILD}/" "$PUBSPEC_PATH"
+            
+            echo "✅ Updated $PUBSPEC_PATH to ${HOTFIX_VERSION}+${NEW_BUILD}"
+            echo "updated_files=true" >> $GITHUB_OUTPUT
+          else
+            echo "⚠️ Warning: $PUBSPEC_PATH not found"
+            echo "updated_files=false" >> $GITHUB_OUTPUT
+          fi
+          
+      - name: 📋 Add CHANGELOG entry
+        run: |
+          APP="${{ github.event.inputs.app }}"
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          ISSUE="${{ github.event.inputs.issue_description }}"
+          
+          if [ "$APP" = "worker-mobile-app" ]; then
+            CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md"
+            APP_NAME="Staff Product"
+          else
+            CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md"
+            APP_NAME="Client Product"
+          fi
+          
+          if [ -f "$CHANGELOG_PATH" ]; then
+            DATE=$(date +%Y-%m-%d)
+            
+            # Extract title and body
+            TITLE=$(head -n 1 "$CHANGELOG_PATH")
+            BODY=$(tail -n +2 "$CHANGELOG_PATH")
+            
+            # Rebuild CHANGELOG with hotfix entry
+            echo "$TITLE" > "$CHANGELOG_PATH"
+            echo "" >> "$CHANGELOG_PATH"
+            echo "## [${HOTFIX_VERSION}] - ${DATE} - HOTFIX" >> "$CHANGELOG_PATH"
+            echo "" >> "$CHANGELOG_PATH"
+            echo "### Fixed" >> "$CHANGELOG_PATH"
+            echo "- ${ISSUE}" >> "$CHANGELOG_PATH"
+            echo "" >> "$CHANGELOG_PATH"
+            echo "---" >> "$CHANGELOG_PATH"
+            echo "" >> "$CHANGELOG_PATH"
+            echo "$BODY" >> "$CHANGELOG_PATH"
+            
+            echo "✅ Added CHANGELOG entry for hotfix $HOTFIX_VERSION"
+          else
+            echo "⚠️ Warning: $CHANGELOG_PATH not found"
+          fi
+          
+      - name: 💾 Commit version changes
+        run: |
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          ISSUE="${{ github.event.inputs.issue_description }}"
+          
+          git add -A
+          git commit -m "chore: prepare hotfix v${HOTFIX_VERSION}
+
+HOTFIX: ${ISSUE}
+
+- Bump version to ${HOTFIX_VERSION}
+- Add CHANGELOG entry
+- Ready for bug fix commits
+
+From tag: ${{ github.event.inputs.tag }}"
+          
+          echo "✅ Committed version changes"
+          
+      - name: 🚀 Push hotfix branch
+        run: |
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          
+          git push origin "$BRANCH"
+          
+          echo "✅ Pushed branch: $BRANCH"
+          
+      - name: 📄 Create Pull Request
+        id: create_pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          ISSUE="${{ github.event.inputs.issue_description }}"
+          APP="${{ github.event.inputs.app }}"
+          
+          # Strip -mobile-app suffix for cleaner tag names
+          APP_CLEAN=$(echo "$APP" | sed 's/-mobile-app$//')
+          
+          if [ "$APP" = "worker-mobile-app" ]; then
+            APP_DISPLAY="Worker Product"
+          else
+            APP_DISPLAY="Client Product"
+          fi
+          
+          PR_TITLE="🚨 HOTFIX: ${APP_DISPLAY} v${HOTFIX_VERSION} - ${ISSUE}"
+          
+          PR_BODY="## 🚨 HOTFIX - URGENT FIX
+
+**App:** ${APP_DISPLAY}
+**Version:** ${HOTFIX_VERSION}
+**From:** \`${{ github.event.inputs.tag }}\`
+
+### Issue
+${ISSUE}
+
+### Impact
+<!-- Describe how many users are affected and severity -->
+
+### Solution
+<!-- Describe the fix (will be added as you commit fixes) -->
+
+### Testing
+<!-- Describe local verification -->
+
+---
+
+## ⚠️ Hotfix Process
+
+1. ✅ Hotfix branch created
+2. ⏳ **NEXT:** Make your bug fix commits to this branch
+3. ⏳ Test the fix locally
+4. ⏳ Request expedited review (< 15 minutes)
+5. ⏳ Merge to main and create production tag
+
+### To add your fix:
+\`\`\`bash
+git checkout $BRANCH
+# Make your changes
+git commit -m \"fix: [description]\"
+git push origin $BRANCH
+\`\`\`
+
+### After merging:
+\`\`\`bash
+# Tag and release
+git checkout main
+git pull origin main
+git tag -a krow-withus-${APP_CLEAN}-mobile/prod-v${HOTFIX_VERSION} -m \"HOTFIX: ${ISSUE}\"
+git push origin krow-withus-${APP_CLEAN}-mobile/prod-v${HOTFIX_VERSION}
+\`\`\`
+
+---
+
+**Ref:** [Hotfix Process Documentation](../docs/release/HOTFIX_PROCESS.md)"
+          
+          # Create PR
+          PR_URL=$(gh pr create \
+            --base main \
+            --head "$BRANCH" \
+            --title "$PR_TITLE" \
+            --body "$PR_BODY" \
+            --label "hotfix,urgent,production")
+          
+          echo "pr_url=${PR_URL}" >> $GITHUB_OUTPUT
+          echo "✅ Pull Request created: $PR_URL"
+          
+      - name: 📊 Hotfix Summary
+        run: |
+          # Strip -mobile-app suffix for cleaner tag names
+          APP_CLEAN=$(echo "${{ github.event.inputs.app }}" | sed 's/-mobile-app$//')
+          
+          echo "## 🚨 Hotfix Branch Created" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**App:** ${{ github.event.inputs.app }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Issue:** ${{ github.event.inputs.issue_description }}" >> $GITHUB_STEP_SUMMARY
+          echo "**From Tag:** \`${{ github.event.inputs.tag }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "**Current Version:** ${{ steps.validate_tag.outputs.current_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Hotfix Version:** ${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Branch:** \`${{ steps.branch.outputs.branch_name }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 🔧 Next Steps" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "1. **Checkout the hotfix branch:**" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "   git fetch origin" >> $GITHUB_STEP_SUMMARY
+          echo "   git checkout ${{ steps.branch.outputs.branch_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "2. **Make your bug fix(es)** - Keep changes minimal!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "3. **Test locally** - Verify the fix works" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "4. **Request expedited review** - Target < 15 minutes" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "5. **Merge PR and create production tag:**" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "   git checkout main" >> $GITHUB_STEP_SUMMARY
+          echo "   git pull origin main" >> $GITHUB_STEP_SUMMARY
+          echo "   git tag -a krow-withus-${APP_CLEAN}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }} -m \"HOTFIX: ${{ github.event.inputs.issue_description }}\"" >> $GITHUB_STEP_SUMMARY
+          echo "   git push origin krow-withus-${APP_CLEAN}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if [ -n "${{ steps.create_pr.outputs.pr_url }}" ]; then
+            echo "**Pull Request:** ${{ steps.create_pr.outputs.pr_url }}" >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/maestro-e2e.yml

@@ -0,0 +1,67 @@
+# Maestro E2E Tests
+# Runs on: manual trigger, or when maestro flows change
+# Requires secrets: TEST_STAFF_PHONE, TEST_STAFF_OTP, TEST_CLIENT_EMAIL, TEST_CLIENT_PASSWORD
+# Optional: TEST_CLIENT_COMPANY, TEST_STAFF_SIGNUP_PHONE
+name: Maestro E2E
+
+on:
+  workflow_dispatch: # Manual trigger only — auto-triggers disabled (free plan)
+
+jobs:
+  maestro-e2e:
+    name: 🎭 Maestro E2E
+    runs-on: macos-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v4
+
+      - name: 🦋 Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: '3.38.x'
+          channel: 'stable'
+          cache: true
+
+      - name: 🔧 Install Firebase CLI
+        run: npm install -g firebase-tools
+
+      - name: 📦 Get dependencies
+        run: make mobile-install
+
+      - name: 🔨 Build Staff APK
+        run: make mobile-staff-build PLATFORM=apk MODE=debug
+
+      - name: 🔨 Build Client APK
+        run: make mobile-client-build PLATFORM=apk MODE=debug
+
+      - name: 📲 Start emulator
+        uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 33
+          target: default
+          arch: x86_64
+          profile: Nexus 6
+          script: |
+            # Install Maestro
+            curl -Ls "https://get.maestro.mobile.dev" | bash
+            export PATH="$HOME/.maestro/bin:$PATH"
+            maestro --version
+
+            # Install APKs
+            adb install -r apps/mobile/apps/staff/build/app/outputs/flutter-apk/app-debug.apk
+            adb install -r apps/mobile/apps/client/build/app/outputs/flutter-apk/app-debug.apk
+
+            # Run auth flows (Staff + Client)
+            maestro test --shard-split=1 \
+              apps/mobile/apps/staff/maestro/auth/sign_in.yaml \
+              apps/mobile/apps/staff/maestro/auth/sign_up.yaml \
+              apps/mobile/apps/client/maestro/auth/sign_in.yaml \
+              apps/mobile/apps/client/maestro/auth/sign_up.yaml \
+              -e TEST_STAFF_PHONE="${{ secrets.TEST_STAFF_PHONE }}" \
+              -e TEST_STAFF_OTP="${{ secrets.TEST_STAFF_OTP }}" \
+              -e TEST_STAFF_SIGNUP_PHONE="${{ secrets.TEST_STAFF_SIGNUP_PHONE }}" \
+              -e TEST_CLIENT_EMAIL="${{ secrets.TEST_CLIENT_EMAIL }}" \
+              -e TEST_CLIENT_PASSWORD="${{ secrets.TEST_CLIENT_PASSWORD }}" \
+              -e TEST_CLIENT_COMPANY="${{ secrets.TEST_CLIENT_COMPANY }}"

.github/workflows/mobile-ci.yml

@@ -0,0 +1,239 @@
+name: Mobile CI
+
+on:
+  workflow_dispatch: # Manual trigger only — auto-triggers disabled (free plan)
+  workflow_dispatch:
+
+jobs:
+  detect-changes:
+    name: 🔍 Detect Mobile Changes
+    runs-on: ubuntu-latest
+    outputs:
+      mobile-changed: ${{ steps.detect.outputs.mobile-changed }}
+      changed-files: ${{ steps.detect.outputs.changed-files }}
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: 🔎 Detect changes in apps/mobile
+        id: detect
+        run: |
+          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            # For PR, compare all changes against base branch (not just latest commit)
+            # Using three-dot syntax (...) shows all files changed in the PR branch
+            BASE_REF="${{ github.event.pull_request.base.ref }}"
+            CHANGED_FILES=$(git diff --name-only origin/$BASE_REF...HEAD 2>/dev/null || echo "")
+          else
+            # For push, compare with previous commit
+            if [[ "${{ github.event.before }}" == "0000000000000000000000000000000000000000" ]]; then
+              # Initial commit, check all files
+              CHANGED_FILES=$(git ls-tree -r --name-only HEAD)
+            else
+              CHANGED_FILES=$(git diff --name-only ${{ github.event.before }} ${{ github.event.after }})
+            fi
+          fi
+
+          # Filter for files in apps/mobile
+          MOBILE_CHANGED=$(echo "$CHANGED_FILES" | grep -c "^apps/mobile/" || echo "0")
+          
+          if [[ $MOBILE_CHANGED -gt 0 ]]; then
+            echo "mobile-changed=true" >> $GITHUB_OUTPUT
+            # Get list of changed Dart files in apps/mobile
+            MOBILE_FILES=$(echo "$CHANGED_FILES" | grep "^apps/mobile/" | grep "\.dart$" || echo "")
+            echo "changed-files<<EOF" >> $GITHUB_OUTPUT
+            echo "$MOBILE_FILES" >> $GITHUB_OUTPUT
+            echo "EOF" >> $GITHUB_OUTPUT
+            echo "✅ Changes detected in apps/mobile/"
+            echo "📝 Changed files:"
+            echo "$MOBILE_FILES"
+          else
+            echo "mobile-changed=false" >> $GITHUB_OUTPUT
+            echo "changed-files=" >> $GITHUB_OUTPUT
+            echo "⏭️  No changes detected in apps/mobile/ - skipping checks"
+          fi
+
+  compile:
+    name: 🏗️ Compile Mobile App
+    runs-on: macos-latest
+    needs: detect-changes
+    if: needs.detect-changes.outputs.mobile-changed == 'true'
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+
+      - name: 🦋 Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: '3.38.x'
+          channel: 'stable'
+          cache: true
+
+      - name: 🔧 Install Firebase CLI
+        run: |
+          npm install -g firebase-tools
+
+      - name: 📦 Get Flutter dependencies
+        run: |
+          make mobile-install
+
+      - name: 🔨 Run compilation check
+        run: |
+          set -o pipefail
+
+          echo "🏗️ Building client app for Android (dev mode)..."
+          if ! make mobile-client-build PLATFORM=apk MODE=debug 2>&1 | tee client_build.txt; then
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "❌ CLIENT APP BUILD FAILED"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            exit 1
+          fi
+          
+          echo ""
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          
+          echo "🏗️ Building staff app for Android (dev mode)..."
+          if ! make mobile-staff-build PLATFORM=apk MODE=debug 2>&1 | tee staff_build.txt; then
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo "❌ STAFF APP BUILD FAILED"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            exit 1
+          fi
+          
+          echo ""
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          echo "✅ Build check PASSED - Both apps built successfully"
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  lint:
+    name: 🧹 Lint Changed Files
+    runs-on: macos-latest
+    needs: detect-changes
+    if: needs.detect-changes.outputs.mobile-changed == 'true' && needs.detect-changes.outputs.changed-files != ''
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+
+      - name: 🦋 Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: '3.38.x'
+          channel: 'stable'
+          cache: true
+
+      - name: 🔧 Install Firebase CLI
+        run: |
+          npm install -g firebase-tools
+
+      - name: 📦 Get Flutter dependencies
+        run: |
+          make mobile-install
+
+      - name: 🔍 Lint changed Dart files
+        run: |
+          set -o pipefail
+          
+          # Get the list of changed files
+          CHANGED_FILES="${{ needs.detect-changes.outputs.changed-files }}"
+          
+          if [[ -z "$CHANGED_FILES" ]]; then
+            echo "⏭️  No Dart files changed, skipping lint"
+            exit 0
+          fi
+          
+          echo "🎯 Running lint on changed files:"
+          echo "$CHANGED_FILES"
+          echo ""
+          
+          # Run dart analyze on each changed file
+          HAS_ERRORS=false
+          FAILED_FILES=()
+          
+          while IFS= read -r file; do
+            if [[ -n "$file" && "$file" == *.dart && -f "$file" ]]; then
+              echo "📝 Analyzing: $file"
+              
+              if ! dart analyze "$file" 2>&1 | tee -a lint_output.txt; then
+                HAS_ERRORS=true
+                FAILED_FILES+=("$file")
+              fi
+              echo ""
+            fi
+          done <<< "$CHANGED_FILES"
+          
+          echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          
+          # Check if there were any errors
+          if [[ "$HAS_ERRORS" == "true" ]]; then
+            echo "❌ LINT ERRORS FOUND IN ${#FAILED_FILES[@]} FILE(S):"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            for file in "${FAILED_FILES[@]}"; do
+              echo "  ❌ $file"
+            done
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            echo ""
+            echo "See details above for each file"
+            exit 1
+          else
+            echo "✅ Lint check PASSED for all changed files"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          fi
+
+  status-check:
+    name: 📊 CI Status Check
+    runs-on: ubuntu-latest
+    needs: [detect-changes, compile, lint]
+    if: always()
+    steps:
+      - name: 🔍 Check mobile changes detected
+        run: |
+          if [[ "${{ needs.detect-changes.outputs.mobile-changed }}" == "true" ]]; then
+            echo "✅ Mobile changes detected - running full checks"
+          else
+            echo "⏭️  No mobile changes detected - skipping checks"
+          fi
+
+      - name: 🏗️ Report compilation status
+        if: needs.detect-changes.outputs.mobile-changed == 'true'
+        run: |
+          if [[ "${{ needs.compile.result }}" == "success" ]]; then
+            echo "✅ Compilation check: PASSED"
+          else
+            echo "❌ Compilation check: FAILED"
+            exit 1
+          fi
+
+      - name: 🧹 Report lint status
+        if: needs.detect-changes.outputs.mobile-changed == 'true' && needs.detect-changes.outputs.changed-files != ''
+        run: |
+          if [[ "${{ needs.lint.result }}" == "success" ]]; then
+            echo "✅ Lint check: PASSED"
+          else
+            echo "❌ Lint check: FAILED"
+            exit 1
+          fi
+
+      - name: 🎉 Final status
+        if: always()
+        run: |
+          echo ""
+          echo "╔════════════════════════════════════╗"
+          echo "║  📊 Mobile CI Pipeline Summary     ║"
+          echo "╚════════════════════════════════════╝"
+          echo ""
+          echo "🔍 Change Detection: ${{ needs.detect-changes.result }}"
+          echo "🏗️ Compilation:      ${{ needs.compile.result }}"
+          echo "🧹 Lint Check:       ${{ needs.lint.result }}"
+          echo ""
+          
+          if [[ "${{ needs.detect-changes.result }}" != "success" || \
+                ("${{ needs.detect-changes.outputs.mobile-changed }}" == "true" && \
+                 ("${{ needs.compile.result }}" != "success" || "${{ needs.lint.result }}" != "success")) ]]; then
+            echo "❌ Pipeline FAILED"
+            exit 1
+          else
+            echo "✅ Pipeline PASSED"
+          fi

.github/workflows/product-release.yml

@@ -0,0 +1,289 @@
+name: 📦 Product Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      app:
+        description: '📦 Product'
+        required: true
+        type: choice
+        options:
+          - worker-mobile-app
+          - client-mobile-app
+      environment:
+        description: '🌍 Environment'
+        required: true
+        type: choice
+        options:
+          - dev
+          - stage
+          - prod
+      create_github_release:
+        description: '📦 Create GitHub Release'
+        required: true
+        type: boolean
+        default: true
+      prerelease:
+        description: '🔖 Mark as Pre-release'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  validate-and-create-release:
+    name: 🚀 Create Product Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag_name: ${{ steps.tag.outputs.tag_name }}
+      
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          
+      - name: 🏃🏾‍♂️ Make scripts executable
+        run: |
+          chmod +x .github/scripts/*.sh
+          echo "✅ Scripts are now executable"
+          
+      - name: 📖 Extract version from version file
+        id: version
+        run: |
+          VERSION=$(.github/scripts/extract-version.sh "${{ github.event.inputs.app }}")
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "📌 Extracted version: ${VERSION}"
+          
+      - name: 🏷️ Generate tag name
+        id: tag
+        run: |
+          TAG_NAME=$(.github/scripts/generate-tag-name.sh \
+            "${{ github.event.inputs.app }}" \
+            "${{ github.event.inputs.environment }}" \
+            "${{ steps.version.outputs.version }}")
+          echo "tag_name=${TAG_NAME}" >> $GITHUB_OUTPUT
+          echo "🎯 Tag to create: ${TAG_NAME}"
+          
+      - name: 🔍 Check if tag already exists
+        run: |
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then
+            echo "❌ Error: Tag $TAG_NAME already exists"
+            echo "💡 Tip: Update the version in the version file before creating a new release"
+            exit 1
+          fi
+          echo "✅ Tag does not exist, proceeding..."
+          
+      - name: 📋 Extract release notes from CHANGELOG
+        id: release_notes
+        run: |
+          .github/scripts/extract-release-notes.sh \
+            "${{ github.event.inputs.app }}" \
+            "${{ steps.version.outputs.version }}" \
+            "${{ github.event.inputs.environment }}" \
+            "${{ steps.tag.outputs.tag_name }}" \
+            "/tmp/release_notes.md"
+          echo "notes_file=/tmp/release_notes.md" >> $GITHUB_OUTPUT
+          
+      - name: 🏷️ Create Git Tag
+        run: |
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          APP="${{ github.event.inputs.app }}"
+          ENV="${{ github.event.inputs.environment }}"
+          VERSION="${{ steps.version.outputs.version }}"
+          
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          git tag -a "$TAG_NAME" -m "🚀 Release ${APP} product ${VERSION} to ${ENV}"
+          git push origin "$TAG_NAME"
+          
+          echo "✅ Tag created and pushed: $TAG_NAME"
+          
+      - name: 📦 Create GitHub Release
+        if: ${{ github.event.inputs.create_github_release == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          APP="${{ github.event.inputs.app }}"
+          ENV="${{ github.event.inputs.environment }}"
+          VERSION="${{ steps.version.outputs.version }}"
+          
+          # Generate release title
+          if [ "$APP" = "worker-mobile-app" ]; then
+            APP_DISPLAY="Worker Mobile Application"
+          else
+            APP_DISPLAY="Client Mobile Application"
+          fi
+          
+          ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]')
+          RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${VERSION}"
+          
+          echo "📦 Creating GitHub Release: $RELEASE_NAME"
+          
+          # Create release
+          if [ "${{ github.event.inputs.prerelease }}" = "true" ]; then
+            gh release create "$TAG_NAME" \
+              --title "$RELEASE_NAME" \
+              --notes-file "${{ steps.release_notes.outputs.notes_file }}" \
+              --prerelease
+            echo "🔖 Pre-release created successfully"
+          else
+            gh release create "$TAG_NAME" \
+              --title "$RELEASE_NAME" \
+              --notes-file "${{ steps.release_notes.outputs.notes_file }}"
+            echo "✅ Release created successfully"
+          fi
+          
+      - name: 📊 Generate Release Summary
+        run: |
+          .github/scripts/create-release-summary.sh \
+            "${{ github.event.inputs.app }}" \
+            "${{ github.event.inputs.environment }}" \
+            "${{ steps.version.outputs.version }}" \
+            "${{ steps.tag.outputs.tag_name }}"
+  
+  build-mobile-artifacts:
+    name: 📱 Build Mobile APK
+    runs-on: ubuntu-latest
+    needs: validate-and-create-release
+    if: ${{ github.event.inputs.app == 'worker-mobile-app' || github.event.inputs.app == 'client-mobile-app' }}
+    permissions:
+      contents: write
+    
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          
+      - name: 🟢 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          
+      - name: 🔥 Install Firebase CLI
+        run: |
+          npm install -g firebase-tools
+          firebase --version
+          echo "ℹ️ Note: Firebase CLI installed for Data Connect SDK generation"
+          echo "ℹ️ If SDK generation fails, ensure Data Connect SDK files are committed to repo"
+          
+      - name: ☕ Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'zulu'
+          java-version: '17'
+          
+      - name: 🐦 Setup Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: '3.38.x'
+          channel: 'stable'
+          cache: true
+          
+      - name: 🔧 Install Melos
+        run: |
+          dart pub global activate melos
+          echo "$HOME/.pub-cache/bin" >> $GITHUB_PATH
+          
+      - name: 📦 Install Dependencies
+        run: |
+          make mobile-install
+          
+      - name: 🔐 Setup APK Signing
+        env:
+          # Worker Mobile (Staff App) Secrets
+          WORKER_KEYSTORE_DEV_BASE64: ${{ secrets.WORKER_KEYSTORE_DEV_BASE64 }}
+          WORKER_KEYSTORE_STAGING_BASE64: ${{ secrets.WORKER_KEYSTORE_STAGING_BASE64 }}
+          WORKER_KEYSTORE_PROD_BASE64: ${{ secrets.WORKER_KEYSTORE_PROD_BASE64 }}
+          WORKER_KEYSTORE_PASSWORD_DEV: ${{ secrets.WORKER_KEYSTORE_PASSWORD_DEV }}
+          WORKER_KEYSTORE_PASSWORD_STAGING: ${{ secrets.WORKER_KEYSTORE_PASSWORD_STAGING }}
+          WORKER_KEYSTORE_PASSWORD_PROD: ${{ secrets.WORKER_KEYSTORE_PASSWORD_PROD }}
+          WORKER_KEY_ALIAS_DEV: ${{ secrets.WORKER_KEY_ALIAS_DEV }}
+          WORKER_KEY_ALIAS_STAGING: ${{ secrets.WORKER_KEY_ALIAS_STAGING }}
+          WORKER_KEY_ALIAS_PROD: ${{ secrets.WORKER_KEY_ALIAS_PROD }}
+          WORKER_KEY_PASSWORD_DEV: ${{ secrets.WORKER_KEY_PASSWORD_DEV }}
+          WORKER_KEY_PASSWORD_STAGING: ${{ secrets.WORKER_KEY_PASSWORD_STAGING }}
+          WORKER_KEY_PASSWORD_PROD: ${{ secrets.WORKER_KEY_PASSWORD_PROD }}
+          
+          # Client Mobile Secrets
+          CLIENT_KEYSTORE_DEV_BASE64: ${{ secrets.CLIENT_KEYSTORE_DEV_BASE64 }}
+          CLIENT_KEYSTORE_STAGING_BASE64: ${{ secrets.CLIENT_KEYSTORE_STAGING_BASE64 }}
+          CLIENT_KEYSTORE_PROD_BASE64: ${{ secrets.CLIENT_KEYSTORE_PROD_BASE64 }}
+          CLIENT_KEYSTORE_PASSWORD_DEV: ${{ secrets.CLIENT_KEYSTORE_PASSWORD_DEV }}
+          CLIENT_KEYSTORE_PASSWORD_STAGING: ${{ secrets.CLIENT_KEYSTORE_PASSWORD_STAGING }}
+          CLIENT_KEYSTORE_PASSWORD_PROD: ${{ secrets.CLIENT_KEYSTORE_PASSWORD_PROD }}
+          CLIENT_KEY_ALIAS_DEV: ${{ secrets.CLIENT_KEY_ALIAS_DEV }}
+          CLIENT_KEY_ALIAS_STAGING: ${{ secrets.CLIENT_KEY_ALIAS_STAGING }}
+          CLIENT_KEY_ALIAS_PROD: ${{ secrets.CLIENT_KEY_ALIAS_PROD }}
+          CLIENT_KEY_PASSWORD_DEV: ${{ secrets.CLIENT_KEY_PASSWORD_DEV }}
+          CLIENT_KEY_PASSWORD_STAGING: ${{ secrets.CLIENT_KEY_PASSWORD_STAGING }}
+          CLIENT_KEY_PASSWORD_PROD: ${{ secrets.CLIENT_KEY_PASSWORD_PROD }}
+        run: |
+          .github/scripts/setup-apk-signing.sh \
+            "${{ github.event.inputs.app }}" \
+            "${{ github.event.inputs.environment }}" \
+            "${{ runner.temp }}"
+          
+      - name: 🏗️ Build APK
+        id: build_apk
+        run: |
+          APP="${{ github.event.inputs.app }}"
+          
+          if [ "$APP" = "worker-mobile-app" ]; then
+            echo "📱 Building Staff (Worker) APK..."
+            make mobile-staff-build PLATFORM=apk MODE=release
+            APP_NAME="staff"
+          else
+            echo "📱 Building Client APK..."
+            make mobile-client-build PLATFORM=apk MODE=release
+            APP_NAME="client"
+          fi
+          
+          # Find the generated APK (Flutter places it in build/app/outputs/flutter-apk/)
+          APK_PATH=$(find apps/mobile/apps/${APP_NAME}/build/app/outputs/flutter-apk -name "app-release.apk" 2>/dev/null | head -n 1)
+          
+          # Fallback to searching entire apps directory if not found
+          if [ -z "$APK_PATH" ]; then
+            APK_PATH=$(find apps/mobile/apps/${APP_NAME} -name "app-release.apk" | head -n 1)
+          fi
+          
+          if [ -z "$APK_PATH" ]; then
+            echo "❌ Error: APK not found!"
+            echo "Searched in apps/mobile/apps/${APP_NAME}/"
+            find apps/mobile/apps/${APP_NAME} -name "*.apk" || echo "No APK files found"
+            exit 1
+          fi
+          
+          echo "✅ APK built successfully: $APK_PATH"
+          echo "app_name=${APP_NAME}" >> $GITHUB_OUTPUT
+          echo "apk_path=${APK_PATH}" >> $GITHUB_OUTPUT
+          
+      - name: ✅ Verify APK Signature
+        run: |
+          .github/scripts/verify-apk-signature.sh "${{ steps.build_apk.outputs.apk_path }}"
+          
+      - name: 📤 Upload APK as Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ github.event.inputs.app }}-${{ needs.validate-and-create-release.outputs.version }}-${{ github.event.inputs.environment }}
+          path: apps/mobile/apps/${{ steps.build_apk.outputs.app_name }}/build/app/outputs/flutter-apk/app-release.apk
+          if-no-files-found: error
+          retention-days: 30
+          
+      - name: 📦 Attach APK to GitHub Release
+        if: ${{ github.event.inputs.create_github_release == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          .github/scripts/attach-apk-to-release.sh \
+            "${{ needs.validate-and-create-release.outputs.tag_name }}" \
+            "${{ github.event.inputs.app }}" \
+            "${{ steps.build_apk.outputs.app_name }}" \
+            "${{ needs.validate-and-create-release.outputs.version }}" \
+            "${{ github.event.inputs.environment }}"

.github/workflows/web-quality.yml

@@ -0,0 +1,52 @@
+name: Web Quality
+
+on:
+  workflow_dispatch: # Manual trigger only — auto-triggers disabled (free plan)
+
+jobs:
+  web-quality:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/web
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+          run_install: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+          cache-dependency-path: apps/web/pnpm-lock.yaml
+
+      - name: Setup Firebase CLI
+        working-directory: .
+        run: npm install -g firebase-tools
+
+      - name: Generate Data Connect SDK
+        working-directory: .
+        run: |
+          cp backend/dataconnect/dataconnect.dev.yaml backend/dataconnect/dataconnect.yaml
+          firebase dataconnect:sdk:generate --non-interactive
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build

.gitignore

@@ -0,0 +1,201 @@
+# ==============================================================================
+# GLOBAL & OS
+# ==============================================================================
+.DS_Store
+.DS_Store?
+._*
+.AppleDouble
+.LSOverride
+.Spotlight-V100
+.Trashes
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+desktop.ini
+$RECYCLE.BIN/
+.Trash-*
+
+# IDE & Editors
+.idea/
+*.iml
+*.iws
+*.swp
+*.swo
+*~
+\#*\#
+.\#*
+
+# Logs & Cache
+*.log
+*.cache
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+*.pid
+*.seed
+*.pid.lock
+
+# Temporary Files
+*.tmp
+*.temp
+tmp/
+temp/
+scripts/issues-to-create.md
+
+# ==============================================================================
+# SECURITY (CRITICAL)
+# ==============================================================================
+# Secrets directory (contains API keys, service accounts)
+secrets/
+# Environment files
+.env
+.env.local
+.env.*.local
+.env.development
+.env.production
+.env.test
+!.env.example
+
+# Certificates & Keys
+*.pem
+*.key
+*.jks
+*.keystore
+*.p12
+*.cer
+
+# GCP Service Account Keys
+gcp_keys/
+**/*.service-account.json
+**/sa.json
+
+# NPM Auth
+.npmrc
+**/.npmrc
+!**/.npmrc.template
+
+# ==============================================================================
+# NODE.JS / WEB (React, Vite, Functions)
+# ==============================================================================
+node_modules/
+dist/
+dist-ssr/
+coverage/
+!**/lib/**/coverage/
+!**/src/**/coverage/
+.nyc_output/
+.vite/
+.temp/
+*.local
+.eslintcache
+.stylelintcache
+.npm
+.turbo
+.vercel
+
+# Vite timestamps
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+
+# Generated Data Connect SDKs in web projects
+# Generally ignored as they are regenerated on build
+**/dataconnect-generated/
+
+# ==============================================================================
+# FLUTTER / MOBILE
+# ==============================================================================
+# Flutter/Dart
+.dart_tool/
+.pub-cache/
+.flutter-plugins
+.flutter-plugins-dependencies
+
+# Firebase Data Connect Generated SDK (regenerated via make mobile-install)
+**/dataconnect_generated/
+
+# Android
+.gradle/
+**/android/app/libs/
+**/android/local.properties
+
+# Build outputs
+build/
+
+# iOS
+**/ios/Flutter/Generated.xcconfig
+**/ios/Flutter/flutter_export_environment.sh
+**/ios/Podfile.lock
+**/ios/Pods/
+**/ios/.symlinks/
+
+# Ephemeral files (generated by Flutter for desktop platforms)
+**/linux/flutter/ephemeral/
+**/windows/flutter/ephemeral/
+**/macos/Flutter/ephemeral/
+**/ios/Flutter/ephemeral/
+
+# ==============================================================================
+# FIREBASE & BACKEND
+# ==============================================================================
+# Firebase Cache & Emulators
+.firebase/
+dataconnect/.dataconnect/
+backend/dataconnect/.dataconnect/
+backend/dataconnect/dataconnect.yaml
+
+# Debug Logs (Recursive)
+**/firebase-debug.log
+**/firebase-debug.*.log
+**/firestore-debug.log
+**/ui-debug.log
+**/database-debug.log
+**/pubsub-debug.log
+
+# Python Virtual Envs (if used)
+venv/
+env/
+ENV/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# ==============================================================================
+# PROJECT SPECIFIC
+# ==============================================================================
+# Secure hashes are committed, but the raw user list is usually kept for reference
+# unless it contains sensitive info. Here we explicitly ignore the raw file.
+internal/launchpad/iap-users.txt
+
+# Generated Prototypes (must be synced locally via 'make sync-prototypes')
+internal/launchpad/prototypes/web/*
+!internal/launchpad/prototypes/web/.keep
+internal/launchpad/prototypes/mobile/**/*
+!internal/launchpad/prototypes/mobile/**/.keep
+
+# Prototype Source Code (synced for AI/Claude context, not for version control)
+internal/launchpad/prototypes-src/
+
+# Temporary migration artifacts
+_legacy/
+krow-workforce-export-latest/
+skills/
+skills-lock.json
+
+# Data Connect Generated SDKs (Explicit)
+apps/mobile/packages/data_connect/lib/src/dataconnect_generated/
+apps/web/src/dataconnect-generated/
+
+# Legacy mobile applications
+apps/mobile/legacy/*
+
+
+AGENTS.md
+TASKS.md
+CLAUDE.md
+.claude/agents/paper-designer.md
+.claude/agent-memory/paper-designer
+\n# Android Signing (Secure)\n**.jks\n**key.properties

.vscode/launch.json

@@ -0,0 +1,127 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        // ===================== Client App =====================
+        {
+            "name": "Client [DEV] - Android",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/client/lib/main.dart",
+            "args": [
+                "--flavor", "dev",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.dev.json"
+            ]
+        },
+        {
+            "name": "Client [DEV] - iOS",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/client/lib/main.dart",
+            "args": [
+                "--flavor", "dev",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.dev.json"
+            ]
+        },
+        {
+            "name": "Client [STG] - Android",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/client/lib/main.dart",
+            "args": [
+                "--flavor", "stage",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.stage.json"
+            ]
+        },
+        {
+            "name": "Client [STG] - iOS",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/client/lib/main.dart",
+            "args": [
+                "--flavor", "stage",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.stage.json"
+            ]
+        },
+        {
+            "name": "Client [PROD] - Android",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/client/lib/main.dart",
+            "args": [
+                "--flavor", "prod",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.prod.json"
+            ]
+        },
+        {
+            "name": "Client [PROD] - iOS",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/client/lib/main.dart",
+            "args": [
+                "--flavor", "prod",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.prod.json"
+            ]
+        },
+        // ===================== Staff App =====================
+        {
+            "name": "Staff [DEV] - Android",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/staff/lib/main.dart",
+            "args": [
+                "--flavor", "dev",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.dev.json"
+            ]
+        },
+        {
+            "name": "Staff [DEV] - iOS",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/staff/lib/main.dart",
+            "args": [
+                "--flavor", "dev",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.dev.json"
+            ]
+        },
+        {
+            "name": "Staff [STG] - Android",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/staff/lib/main.dart",
+            "args": [
+                "--flavor", "stage",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.stage.json"
+            ]
+        },
+        {
+            "name": "Staff [STG] - iOS",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/staff/lib/main.dart",
+            "args": [
+                "--flavor", "stage",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.stage.json"
+            ]
+        },
+        {
+            "name": "Staff [PROD] - Android",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/staff/lib/main.dart",
+            "args": [
+                "--flavor", "prod",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.prod.json"
+            ]
+        },
+        {
+            "name": "Staff [PROD] - iOS",
+            "request": "launch",
+            "type": "dart",
+            "program": "apps/mobile/apps/staff/lib/main.dart",
+            "args": [
+                "--flavor", "prod",
+                "--dart-define-from-file=${workspaceFolder}/apps/mobile/config.prod.json"
+            ]
+        }
+    ]
+}

CHANGELOG.md

@@ -0,0 +1,31 @@
+# KROW Workforce Change Log
+
+| Date | Version | Change |
+|---|---|---|
+| 2026-02-24 | 0.1.0 | Confirmed dev owner access and current runtime baseline in `krow-workforce-dev`. |
+| 2026-02-24 | 0.1.1 | Added backend foundation implementation plan document. |
+| 2026-02-24 | 0.1.2 | Added API implementation contract and transition route aliases. |
+| 2026-02-24 | 0.1.3 | Added auth-first security policy with deferred role-map integration hooks. |
+| 2026-02-24 | 0.1.4 | Locked defaults for idempotency, validation, bucket split, model provider, and p95 objectives. |
+| 2026-02-24 | 0.1.5 | Added backend makefile module and CI workflow for backend target validation. |
+| 2026-02-24 | 0.1.6 | Added Cloud SQL-backed idempotency storage, migration script, and command API test coverage. |
+| 2026-02-24 | 0.1.7 | Added `/health` endpoints and switched smoke checks to `/health` for Cloud Run compatibility. |
+| 2026-02-24 | 0.1.8 | Enabled dev frontend reachability and made deploy auth mode environment-aware (`dev` public, `staging` private). |
+| 2026-02-24 | 0.1.9 | Switched core API from mock behavior to real GCS upload/signed URLs and real Vertex model calls in dev deployment. |
+| 2026-02-24 | 0.1.10 | Hardened core APIs with signed URL ownership/expiry checks, object existence checks, and per-user LLM rate limiting. |
+| 2026-02-24 | 0.1.11 | Added frontend-ready core API guide and linked M4 API catalog to it as source of truth for consumption. |
+| 2026-02-24 | 0.1.12 | Reduced M4 API docs to core-only scope and removed command-route references until command implementation is complete. |
+| 2026-02-24 | 0.1.13 | Added verification architecture contract with endpoint design and workflow split for attire, government ID, and certification. |
+| 2026-02-24 | 0.1.14 | Implemented core verification endpoints in dev and updated frontend/API docs with live verification route contracts. |
+| 2026-02-24 | 0.1.15 | Added live Vertex Flash Lite attire verification path and third-party adapter scaffolding for government ID and certification checks. |
+| 2026-02-24 | 0.1.16 | Added M4 target schema blueprint doc with first-principles modular model, constraints, and migration phases. |
+| 2026-02-24 | 0.1.17 | Added full current-schema mermaid model relationship map to the M4 target schema blueprint. |
+| 2026-02-24 | 0.1.18 | Updated schema blueprint with explicit multi-tenant stakeholder model and phased RBAC rollout with shadow mode before enforcement. |
+| 2026-02-24 | 0.1.19 | Added customer stakeholder-wheel mapping and future stakeholder extension model to the M4 schema blueprint. |
+| 2026-02-25 | 0.1.20 | Added roadmap CSV schema-reconciliation document with stakeholder capability matrix and concrete schema gap analysis. |
+| 2026-02-25 | 0.1.21 | Updated target schema blueprint with roadmap-evidence section plus attendance/offense, stakeholder-network, and settlement-table coverage. |
+| 2026-02-25 | 0.1.22 | Updated core actor scenarios with explicit business and vendor user partitioning via membership tables. |
+| 2026-02-25 | 0.1.23 | Updated schema blueprint and reconciliation docs to add `business_memberships` and `vendor_memberships` as first-class data actors. |
+| 2026-02-25 | 0.1.24 | Removed stale `m4-discrepencies.md` document from M4 planning docs cleanup. |
+| 2026-02-25 | 0.1.25 | Added target schema model catalog with keys and domain relationship diagrams for slide/workshop use. |
+| 2026-02-26 | 0.1.26 | Added isolated v2 backend foundation targets, scaffolded `backend/query-api`, and expanded backend CI dry-runs/tests for v2/query. |

Makefile

@@ -0,0 +1,120 @@
+# KROW Workforce Project Makefile
+# -------------------------------
+# This is the main entry point. It includes modular Makefiles from the 'makefiles/' directory.
+
+# The default command to run if no target is specified.
+.DEFAULT_GOAL := help
+
+# --- Include Modules ---
+include makefiles/common.mk
+include makefiles/web.mk
+include makefiles/launchpad.mk
+include makefiles/mobile.mk
+include makefiles/dataconnect.mk
+include makefiles/backend.mk
+include makefiles/tools.mk
+
+# --- Main Help Command ---
+.PHONY: help
+
+help:
+	@echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@echo " 🚀 KROW Workforce - Available Makefile Commands"
+	@echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@echo ""
+	@echo "  📦 WEB FRONTEND (apps/web)"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make web-install          Install web frontend dependencies"
+	@echo "  make web-info             List web development commands"
+	@echo "  make web-dev              Start local web frontend dev server"
+	@echo "  make web-build [ENV=dev]  Build web frontend for production (dev/staging)"
+	@echo "  make web-lint             Run linter for web frontend"
+	@echo "  make web-test             Run tests for web frontend"
+	@echo "  make web-preview          Preview web frontend build"
+	@echo "  make web-deploy [ENV=dev] Build and deploy web app (dev/staging)"
+	@echo ""
+	@echo "  Aliases:"
+	@echo "  make install              → web-install"
+	@echo "  make dev                  → web-dev"
+	@echo "  make build                → web-build"
+	@echo "  make deploy-app           → web-deploy"
+	@echo ""
+	@echo "  🏠 LAUNCHPAD (internal/launchpad)"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make launchpad-dev              Start launchpad dev server (Firebase Hosting)"
+	@echo "  make deploy-launchpad-hosting   Deploy launchpad to Firebase Hosting"
+	@echo ""
+	@echo "  📱 MOBILE APPS (apps/mobile)"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make mobile-install                      Bootstrap mobile workspace + SDK"
+	@echo "  make mobile-info                         List mobile development commands"
+	@echo "  make mobile-client-dev-android [DEVICE=android]   Run client app (Android)"
+	@echo "  make mobile-client-build PLATFORM=apk    Build client app (apk/ipa/etc)"
+	@echo "  make mobile-staff-dev-android [DEVICE=android]    Run staff app (Android)"
+	@echo "  make mobile-staff-build PLATFORM=apk     Build staff app (apk/ipa/etc)"
+	@echo "  make mobile-analyze                     Run flutter analyze for client+staff"
+	@echo "  make mobile-test                        Run flutter test for client+staff"
+	@echo "  make mobile-hot-reload                   Hot reload running Flutter app"
+	@echo "  make mobile-hot-restart                  Hot restart running Flutter app"
+	@echo "  make test-e2e                            Run full Maestro E2E suite (Client + Staff auth)"
+	@echo "  make test-e2e-client                     Run Client Maestro E2E only"
+	@echo "  make test-e2e-staff                      Run Staff Maestro E2E only"
+	@echo ""
+	@echo "  🗄️  DATA CONNECT & LEGACY V1 BACKEND (legacy/dataconnect-v1)"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make dataconnect-init                Initialize Firebase Data Connect"
+	@echo "  make dataconnect-deploy [ENV=dev]        Deploy Data Connect schemas (dev/staging)"
+	@echo "  make dataconnect-sql-migrate [ENV=dev]   Apply pending SQL migrations"
+	@echo "  make dataconnect-generate-sdk [ENV=dev]  Regenerate Data Connect client SDK"
+	@echo "  make dataconnect-sync [ENV=dev]          Fast sync: deploy connector + generate SDK"
+	@echo "  make dataconnect-sync-full [ENV=dev]     Full sync: deploy + migrate + generate SDK"
+	@echo "  make dataconnect-seed [ENV=dev]          Seed database with test data"
+	@echo "  make dataconnect-clean [ENV=dev]         Delete all data from Data Connect"
+	@echo "  make dataconnect-test [ENV=dev]          Test Data Connect deployment (dry-run)"
+	@echo "  make dataconnect-enable-apis [ENV=dev]   Enable required GCP APIs"
+	@echo "  make dataconnect-bootstrap-db            ONE-TIME: Full Cloud SQL + Data Connect setup (dev)"
+	@echo "  make dataconnect-bootstrap-validation-database  ONE-TIME: Setup validation database"
+	@echo "  make dataconnect-backup-dev-to-validation       Backup dev database to validation"
+	@echo ""
+	@echo "  ☁️  BACKEND FOUNDATION (Cloud Run + Workers)"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make backend-help                     Show backend foundation commands"
+	@echo "  make backend-enable-apis [ENV=dev]   Enable backend GCP APIs"
+	@echo "  make backend-bootstrap-dev            Bootstrap backend foundation resources (dev)"
+	@echo "  make backend-migrate-idempotency      Create/upgrade command idempotency table"
+	@echo "  make backend-deploy-core [ENV=dev]   Build and deploy core API service"
+	@echo "  make backend-deploy-commands [ENV=dev] Build and deploy command API service"
+	@echo "  make backend-deploy-workers [ENV=dev] Deploy async worker functions scaffold"
+	@echo "  make backend-smoke-core [ENV=dev]    Run health smoke test for core service (/health)"
+	@echo "  make backend-smoke-commands [ENV=dev] Run health smoke test for command service (/health)"
+	@echo "  make backend-logs-core [ENV=dev]     Tail/read logs for core service"
+	@echo ""
+	@echo "  ☁️  BACKEND FOUNDATION V2 (Isolated Parallel Stack)"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make backend-bootstrap-v2-dev [ENV=dev]   Bootstrap isolated v2 resources + SQL instance"
+	@echo "  make backend-deploy-core-v2 [ENV=dev]     Build and deploy core API v2 service"
+	@echo "  make backend-deploy-commands-v2 [ENV=dev] Build and deploy command API v2 service"
+	@echo "  make backend-deploy-query-v2 [ENV=dev]    Build and deploy query API v2 scaffold"
+	@echo "  make backend-v2-migrate-idempotency       Create/upgrade command idempotency table for v2 DB"
+	@echo "  make backend-smoke-core-v2 [ENV=dev]      Run health smoke test for core API v2 (/health)"
+	@echo "  make backend-smoke-commands-v2 [ENV=dev]  Run health smoke test for command API v2 (/health)"
+	@echo "  make backend-smoke-query-v2 [ENV=dev]     Run health smoke test for query API v2 (/health)"
+	@echo "  make backend-logs-core-v2 [ENV=dev]       Tail/read logs for core API v2"
+	@echo ""
+	@echo "  🛠️  DEVELOPMENT TOOLS"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make install-melos             Install Melos globally (for mobile dev)"
+	@echo "  make install-git-hooks         Install git pre-push hook (protect main/dev)"
+	@echo "  make sync-prototypes           Sync prototypes from client-krow-poc repo"
+	@echo "  make clean-branches            Delete local branches (keeps main/dev/demo/**/protected)"
+	@echo "  make setup-mobile-ci-secrets   Setup GitHub Secrets for mobile APK signing (CI/CD)"
+	@echo ""
+	@echo "  ℹ️  HELP"
+	@echo "  ────────────────────────────────────────────────────────────────────"
+	@echo "  make help                 Show this help message"
+	@echo ""
+	@echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+	@echo " 💡 Tip: Run 'make mobile-install' first for mobile development"
+	@echo " 💡 Tip: Use 'make dataconnect-sync-full' after schema changes"
+	@echo " 💡 Tip: Default ENV=dev, use ENV=staging for staging environment"
+	@echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

PROTECTED_BRANCHES.md

@@ -0,0 +1,5 @@
+# Protected Branches
+
+- `main`
+- `dev`
+- `demo/**`

README.md

@@ -1,18 +0,0 @@
-## TuckerF Workolik - Streamlit App
-
-A modern Streamlit application with Postgres-backed authentication and a clean architecture. Includes three pages: See logs, See payload, and Mailer.
-
-### Quickstart
-1. Create a `.env` file from `.env.example` and fill values.
-2. Install dependencies:
-```
-pip install -r requirements.txt
-```
-3. Run the app:
-```
-streamlit run app.py
-```
-
-### Notes
-- `pages/` lives at project root (Streamlit requirement).
-- All other implementation code is under `app_core/` for clean structure.

apps/mobile/.gitignore

@@ -0,0 +1,22 @@
+# Old apps prototypes
+prototypes/*
+
+# AI prompts
+ai_prompts/*
+
+# Docs
+docs/*
+
+# Template feature
+packages/features/shared/template_feature/*
+
+# Generated files
+*.g.dart
+*.freezed.dart
+
+# Dart/Flutter
+.dart_tool/
+.packages
+.pub-cache/
+.pub/
+build/

apps/mobile/README.md

@@ -0,0 +1,133 @@
+# KROW Workforce Mobile 📱
+
+This folder holds the mobile app code for the KROW Workforce apps.
+This project uses [Melos](https://melos.invertase.dev/) to manage multiple Flutter packages and applications.
+
+## 📂 Project Structure
+
+The project is organized into modular packages to ensure separation of concerns and maintainability.
+
+- **`apps/`**: Main application entry points.
+  - `client`: The application for businesses/clients.
+  - `staff`: The application for workforce/staff.
+  - `design_system_viewer`: A gallery of our design system components.
+- **`packages/`**: Shared logic and feature modules.
+  - `features/`: UI and business logic for specific features (e.g., Auth, Home, Hubs).
+    - `features/client`: Client specific features.
+    - `features/staff`: Staff specific features.
+  - `design_system/`: Shared UI components, tokens (colors, spacing), and core widgets.
+  - `domain/`: Shared business entities and repository interfaces.
+  - `data_connect/`: Data access layer (Mocks and Firebase Data Connect SDK).
+  - `core_localization/`: Internationalization using Slang.
+  - `core/`: Base utilities and common logic.
+
+## 🚀 Getting Started
+
+### 1. Prerequisites
+Ensure you have the Flutter SDK installed and configured.
+
+### 2. Android Keystore Setup (Required for Release Builds)
+
+To build release APKs/AABs for Android, you need the signing keystores. The keystore configuration (`key.properties`) is committed to the repository, but the actual keystore files are **not** for security reasons.
+
+#### For Local Development (First-time Setup)
+
+Contact your team lead to obtain the keystore files:
+- `krow_with_us_client_dev.jks` - Client app signing keystore
+- `krow_with_us_staff_dev.jks` - Staff app signing keystore
+
+Once you have the keystores, copy them to the respective app directories:
+
+```bash
+# Copy keystores to their locations
+cp krow_with_us_client_dev.jks apps/mobile/apps/client/android/app/
+cp krow_with_us_staff_dev.jks apps/mobile/apps/staff/android/app/
+```
+
+The `key.properties` configuration files are already in the repository:
+- `apps/mobile/apps/client/android/key.properties`
+- `apps/mobile/apps/staff/android/key.properties`
+
+No manual property file creation is needed — just place the `.jks` files in the correct locations.
+
+#### For CI/CD (CodeMagic)
+
+CodeMagic uses a native keystore management system. Follow these steps:
+
+**Step 1: Upload Keystores to CodeMagic**
+1. Go to **CodeMagic Team Settings** → **Code signing identities** → **Android keystores**
+2. Upload the keystore files with these **Reference names** (important!):
+   - `krow_client_dev` (for dev builds)
+   - `krow_client_staging` (for staging builds)
+   - `krow_client_prod` (for production builds)
+   - `krow_staff_dev` (for dev builds)
+   - `krow_staff_staging` (for staging builds)
+   - `krow_staff_prod` (for production builds)
+3. When uploading, enter the keystore password, key alias, and key password for each keystore
+
+**Step 2: Automatic Environment Variables**
+CodeMagic automatically injects the following environment variables based on the keystore reference:
+- `CM_KEYSTORE_PATH_CLIENT` / `CM_KEYSTORE_PATH_STAFF` - Path to the keystore file
+- `CM_KEYSTORE_PASSWORD_CLIENT` / `CM_KEYSTORE_PASSWORD_STAFF` - Keystore password
+- `CM_KEY_ALIAS_CLIENT` / `CM_KEY_ALIAS_STAFF` - Key alias
+- `CM_KEY_PASSWORD_CLIENT` / `CM_KEY_PASSWORD_STAFF` - Key password
+
+**Step 3: Build Configuration**
+The `build.gradle.kts` files are already configured to:
+- Use CodeMagic environment variables when running in CI (`CI=true`)
+- Fall back to `key.properties` for local development
+
+Reference: [CodeMagic Android Signing Documentation](https://docs.codemagic.io/yaml-code-signing/signing-android/)
+
+### 3. Initial Setup
+Run the following command from the **project root** to install Melos, bootstrap all packages, generate localization files, and generate the Firebase Data Connect SDK:
+
+```bash
+# Using Makefile (Recommended)
+make mobile-install
+```
+
+This command will:
+- Install Melos if not already installed
+- Generate the Firebase Data Connect SDK from schema files
+- Bootstrap all packages (install dependencies)
+- Generate localization files
+
+**Note:** The Firebase Data Connect SDK files (`dataconnect_generated/`) are auto-generated and not committed to the repository. They will be regenerated automatically when you run `make mobile-install` or any mobile development commands.
+
+### 4. Running the Apps
+You can run the applications using Melos scripts or through the `Makefile`:
+
+First, find your device ID:
+```bash
+flutter devices
+```
+
+#### Client App
+```bash
+# Using Melos
+melos run start:client -- -d <device_id>
+# Using Makefile (DEVICE defaults to 'android' if not specified)
+make mobile-client-dev-android DEVICE=<device_id>
+```
+
+#### Staff App
+```bash
+# Using Melos
+melos run start:staff -- -d <device_id>
+# Using Makefile (DEVICE defaults to 'android' if not specified)
+make mobile-staff-dev-android DEVICE=<device_id>
+```
+
+## 🛠 Useful Commands
+
+- **Bootstrap**: `melos bootstrap` (Installs all dependencies)
+- **Generate All**: `melos run gen:all` (Localization + Code Generation)
+- **Analyze**: `melos run analyze:all`
+- **Test**: `melos run test:all`
+- **Help**: `melos run info` (Shows all available custom scripts)
+
+## 🏗 Coding Principles
+- **Clean Architecture**: We strictly follow Domain-Driven Design and Clean Architecture.
+- **Modularity**: Every feature should be its own package in `packages/features/`. Client and staff specific features should be in their respective packages.
+- **Consistency**: Use the `design_system` package for all UI elements to ensure a premium, unified look.

apps/mobile/analysis_options.yaml

@@ -0,0 +1,27 @@
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  exclude:
+    - "**/dataconnect_generated/**"
+    - "**/*.g.dart"
+    - "**/*.freezed.dart"
+    - "**/*.config.dart"
+    - "apps/mobile/prototypes/**"
+  errors:
+    # Set the severity of the always_specify_types rule to warning as requested.
+    always_specify_types: warning
+
+linter:
+  rules:
+    # Every variable should have an explicit type.
+    - always_specify_types
+    
+    # Additional common best practices not always enforced by default
+    - prefer_const_constructors
+    - prefer_const_declarations
+    - prefer_final_locals
+    - avoid_void_async
+    - unawaited_futures
+    - sort_constructors_first
+    - camel_case_types
+    - library_private_types_in_public_api

apps/mobile/apps/client/.gitignore

@@ -0,0 +1,45 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

apps/mobile/apps/client/.metadata

@@ -0,0 +1,45 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "3b62efc2a3da49882f43c372e0bc53daef7295a6"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+      base_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+    - platform: android
+      create_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+      base_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+    - platform: ios
+      create_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+      base_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+    - platform: linux
+      create_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+      base_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+    - platform: macos
+      create_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+      base_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+    - platform: web
+      create_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+      base_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+    - platform: windows
+      create_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+      base_revision: 3b62efc2a3da49882f43c372e0bc53daef7295a6
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

apps/mobile/apps/client/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Client Mobile App - Change Log
+
+## [v0.0.1-m3] - Milestone 3 - 2026-02-15
+
+### Added - Authentication & Onboarding
+- Business email and password authentication
+- Client account registration
+- Business onboarding flow
+- Company information setup
+
+### Added - Home Dashboard
+- Welcome screen with business name
+- Coverage statistics for today:
+  - Coverage percentage
+  - Workers checked in vs needed
+  - Open positions count
+- Late workers alerts with visual indicators
+- Today's estimated labor cost
+- Upcoming shifts section
+- Quick action buttons:
+  - Create Order
+  - Hubs management
+
+### Added - Hub Management
+- Hubs page accessible from settings
+- Hub creation flow:
+  - Hub name input
+  - Address autocomplete with Google Maps Places API
+  - Hub creation confirmation
+- Hubs list view showing all created hubs
+- Hub card display with name, address, and tag ID
+
+### Added - Order Creation
+- Orders tab in bottom navigation
+- "+ Post" button to create new orders
+- Order type selection screen:
+  - One-Time orders (implemented)
+- One-Time Order creation form:
+  - Order name
+  - Date picker
+  - Hub selection
+  - Position management:
+    - Role selection
+    - Worker count
+    - Start/end time
+    - Shift duration calculation
+  - Cost estimation
+- Order creation confirmation
+
+### Added - Order Management
+- Orders list view with:
+  - Order cards showing date, location, time
+  - Worker count (filled/needed)
+  - Coverage percentage bar
+  - Status indicators (OPEN, FILLED, IN PROGRESS)
+- Order details view:
+  - Event name and location
+  - Roles and worker requirements
+  - Clock in/out times
+  - Estimated cost
+  - Coverage percentage
+  - Map integration with directions
+
+### Added - Coverage Monitoring
+- Coverage tab in bottom navigation
+- Real-time worker status dashboard:
+  - Checked In (green indicator)
+  - En Route (yellow indicator)
+  - Late (red indicator)
+  - Not Arrived status
+- Color-coded status badges
+- Worker information cards
+- Active shift monitoring
+
+### Added - Navigation
+- Bottom navigation bar with tabs:
+  - Coverage
+  - Billing
+  - Home
+  - Orders
+  - Reports
+- Settings menu accessible from home screen
+- Back navigation handling
+
+### Added - Settings
+- Settings page with options:
+  - Hubs management
+  - Profile editing
+  - Notifications preferences
+  - Log out
+
+### Technical Features
+- Firebase authentication integration
+- Data Connect backend integration
+- Google Maps Places API for address autocomplete
+- Real-time worker status tracking
+- Cost calculation engine
+- Coverage percentage calculations
+
+### Known Limitations
+- Orders require hub assignment
+- Currently supports one-time orders only
+- Order approval flow not yet implemented
+- RAPID, Recurring, and Permanent order types are placeholders
+
+---
+
+## [v0.0.1-m4] - Milestone 4 - 2026-03-05
+
+### Added - Enhanced Authentication & Session Management
+- Authentication session persistence across app restarts
+- Automatic login with valid session tokens
+- Improved user experience with seamless session handling
+
+### Added - RAPID Order Creation (AI-Powered)
+- Voice input for order creation with audio recording
+- Text input for order description
+- Multi-platform audio recording support (iOS/Android)
+- AI transcription service for voice-to-text conversion
+- AI parsing to generate order drafts from natural language
+- Same-day order support for urgent coverage needs
+- Populated order form matching one-time order structure
+- Edit AI-generated order before submission
+- Quick order creation workflow
+- Audio file upload for transcription
+- RAPID order verification page with refinements
+- Hub and role matching for order creation
+
+### Added - Recurring Order Support
+- Recurring order creation flow
+- Schedule configuration interface
+- Recurring patterns (daily, weekly, custom)
+- Recurring order management
+
+### Added - Permanent Order Support
+- Permanent order creation flow
+- Long-term position setup
+- Permanent order management
+
+### Added - Enhanced Order Management
+- Hide edit icon for past or completed orders
+- Updated Reorder modal supporting all order types:
+  - One-Time reorder
+  - RAPID reorder
+  - Recurring reorder
+  - Permanent reorder
+- Reorder functionality with order type awareness
+- Hub manager assignment to orders
+- Cost center entity linking to hubs
+- Completion review UI with:
+  - Actions summary
+  - Amount display
+  - Info sections
+  - Worker listing
+- Invoice management improvements
+
+### Added - Comprehensive Reports System
+- Reports page with AI-powered insights
+- Three AI-generated insights on reports landing page
+- Six report types:
+  1. **Daily Ops Report**: Daily operational metrics and statistics
+  2. **Spend Report**: Labor cost analysis and spend tracking
+  3. **Coverage Report**: Shift coverage analytics and trends
+  4. **No-Show Report**: Worker attendance and no-show tracking
+  5. **Performance Report**: Worker performance metrics and ratings
+  6. *(Reserved for future report type)*
+
+### Added - Hub Management Enhancements
+- Dedicated hub details interface
+- Detailed hub information view
+- Hub editing page (separate interface)
+- Enhanced hub navigation
+
+### Added - Home Dashboard Enhancements
+- Reorder quick action button
+### Added - Home Dashboard Enhancements
+- Reorder quick action button for fast order duplication
+- Insights quick action button for AI analytics
+- Direct access to AI insights from home
+- Refactored home widgets with SectionLayout:
+  - Today's shifts section with titles
+  - Tomorrow's shifts section
+  - Coverage widget improvements
+  - Live activity widget enhancements
+  - Spending widget updates
+- Full-width dividers for better visual separation
+- Improved dashboard widget organization
+
+### Improved - User Experience
+- Better order type selection flow
+- Enhanced order creation UX across all types
+- Improved reports navigation
+- Better hub management interface
+- Bottom navigation bar show/hide based on route changes
+- Enhanced navigation robustness with error handling
+- Improved invoice page layout with reordered titles
+- Session management improvements with proper role validation
+- Enhanced settings page navigation flow
+- Better amount widget styling in completion review
+
+### Fixed
+- Client app crash issues resolved
+- Shift booking status inconsistencies fixed
+- Session navigation errors corrected
+- Formatting and code clarity improvements across codebase
+
+### Technical Features
+- Backend transaction support for order creation
+- Order validation (minimum hours check)
+- Shift creation validation
+- 24-hour cancellation policy enforcement
+- Enhanced backend reporting APIs
+- AI insights generation system
+- Core API integration:
+  - RAPID order transcription endpoints
+  - Order parsing services  
+  - File upload with signed URLs
+  - LLM services
+- ApiService with Dio for standardized API requests
+- DataConnectService integration across all repositories
+- Enhanced session management with SessionListener
+- Role-based session handling
+
+### Known Limitations
+- RAPID order parsing requires clear voice/text input
+- AI insights require sufficient historical data
+- Reports may have limited data in early usage
+- PDF export for reports not yet implemented
+
+---

apps/mobile/apps/client/analysis_options.yaml

@@ -0,0 +1 @@
+include: ../../analysis_options.yaml

apps/mobile/apps/client/android/.gitignore

@@ -0,0 +1,13 @@
+gradle-wrapper.jar
+/.gradle
+/captures/
+/gradlew
+/gradlew.bat
+/local.properties
+GeneratedPluginRegistrant.java
+.cxx/
+
+# Remember to never publicly share your keystore files.
+# See https://flutter.dev/to/reference-keystore
+**/*.keystore
+**/*.jks

apps/mobile/apps/client/android/app/build.gradle.kts

@@ -0,0 +1,132 @@
+import java.util.Base64
+import java.util.Properties
+
+plugins {
+    id("com.android.application")
+    id("kotlin-android")
+    // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins.
+    id("dev.flutter.flutter-gradle-plugin")
+    id("com.google.gms.google-services")
+}
+
+val dartDefinesString = project.findProperty("dart-defines") as? String ?: ""
+val dartEnvironmentVariables = mutableMapOf<String, String>()
+dartDefinesString.split(",").forEach {
+    if (it.isNotEmpty()) {
+        val decoded = String(Base64.getDecoder().decode(it))
+        val components = decoded.split("=")
+        if (components.size == 2) {
+            dartEnvironmentVariables[components[0]] = components[1]
+        }
+    }
+}
+
+// Load flavor-specific key properties: key.dev.properties, key.stage.properties, key.prod.properties
+// The active flavor is resolved from the Gradle task name (e.g. assembleDevRelease -> dev)
+fun resolveFlavorFromTask(): String {
+    val taskNames = gradle.startParameter.taskNames.joinToString(" ").lowercase()
+    return when {
+        taskNames.contains("prod") -> "prod"
+        taskNames.contains("stage") -> "stage"
+        else -> "dev"
+    }
+}
+
+val activeFlavorForSigning = resolveFlavorFromTask()
+val keystoreProperties = Properties().apply {
+    val propertiesFile = rootProject.file("key.${activeFlavorForSigning}.properties")
+    if (propertiesFile.exists()) {
+        load(propertiesFile.inputStream())
+    }
+}
+
+android {
+    namespace = "com.krowwithus.client"
+    compileSdk = flutter.compileSdkVersion
+    ndkVersion = flutter.ndkVersion
+
+    compileOptions {
+        isCoreLibraryDesugaringEnabled = true
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = JavaVersion.VERSION_17.toString()
+    }
+
+    defaultConfig {
+        // applicationId is set per flavor below
+        // For more information, see: https://flutter.dev/to/review-gradle-config.
+        minSdk = flutter.minSdkVersion
+        targetSdk = flutter.targetSdkVersion
+        versionCode = flutter.versionCode
+        versionName = flutter.versionName
+        manifestPlaceholders["GOOGLE_MAPS_API_KEY"] = dartEnvironmentVariables["GOOGLE_MAPS_API_KEY"] ?: ""
+    }
+
+    flavorDimensions += "environment"
+    productFlavors {
+        create("dev") {
+            dimension = "environment"
+            applicationId = "dev.krowwithus.client"
+            resValue("string", "app_name", "KROW With Us Business [DEV]")
+        }
+        create("stage") {
+            dimension = "environment"
+            applicationId = "stage.krowwithus.client"
+            resValue("string", "app_name", "KROW With Us Business [STG]")
+        }
+        create("prod") {
+            dimension = "environment"
+            applicationId = "prod.krowwithus.client"
+            resValue("string", "app_name", "KROW Client")
+        }
+    }
+
+    signingConfigs {
+        create("release") {
+            if (System.getenv()["CI"] == "true") {
+                // CodeMagic CI environment
+                storeFile = file(System.getenv()["CM_KEYSTORE_PATH"] ?: "")
+                storePassword = System.getenv()["CM_KEYSTORE_PASSWORD"]
+                keyAlias = System.getenv()["CM_KEY_ALIAS"]
+                keyPassword = System.getenv()["CM_KEY_PASSWORD"]
+            } else {
+                // Local development environment — loads from key.<flavor>.properties
+                keyAlias = keystoreProperties["keyAlias"] as String?
+                keyPassword = keystoreProperties["keyPassword"] as String?
+                storeFile = keystoreProperties["storeFile"]?.let { file(it) }
+                storePassword = keystoreProperties["storePassword"] as String?
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            signingConfig = signingConfigs.getByName("release")
+        }
+    }
+}
+
+// Skip google-services processing for flavors whose google-services.json
+// contains placeholder values (e.g. prod before the Firebase project exists).
+// Once a real config is dropped in, the task automatically re-enables.
+afterEvaluate {
+    tasks.matching {
+        it.name.startsWith("process") && it.name.endsWith("GoogleServices")
+    }.configureEach {
+        val taskFlavor = name.removePrefix("process").removeSuffix("GoogleServices")
+            .removeSuffix("Debug").removeSuffix("Release").lowercase()
+        val configFile = file("src/$taskFlavor/google-services.json")
+        enabled = configFile.exists() && configFile.readText().contains("\"mobilesdk_app_id\": \"1:")
+    }
+}
+
+dependencies {
+    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
+}
+
+flutter {
+    source = "../.."
+}

apps/mobile/apps/client/android/app/src/debug/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>

apps/mobile/apps/client/android/app/src/dev/google-services.json

@@ -0,0 +1,170 @@
+{
+  "project_info": {
+    "project_number": "933560802882",
+    "project_id": "krow-workforce-dev",
+    "storage_bucket": "krow-workforce-dev.firebasestorage.app"
+  },
+  "client": [
+    {
+      "client_info": {
+        "mobilesdk_app_id": "1:933560802882:android:da13569105659ead7757db",
+        "android_client_info": {
+          "package_name": "com.krowwithus.client"
+        }
+      },
+      "oauth_client": [
+        {
+          "client_id": "933560802882-qbl6keingmd14fepn6qp76agdmbr84fg.apps.googleusercontent.com",
+          "client_type": 1,
+          "android_info": {
+            "package_name": "com.krowwithus.client",
+            "certificate_hash": "f5491c60ec20eb27bb3ec581352ba653053f3740"
+          }
+        },
+        {
+          "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+          "client_type": 3
+        }
+      ],
+      "api_key": [
+        {
+          "current_key": "AIzaSyDBYhflhK6DThKnS7RM-9raKdvyKzLUjY4"
+        }
+      ],
+      "services": {
+        "appinvite_service": {
+          "other_platform_oauth_client": [
+            {
+              "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+              "client_type": 3
+            },
+            {
+              "client_id": "933560802882-29olj9ku64jbe9h7flinha6hbi8qrluh.apps.googleusercontent.com",
+              "client_type": 2,
+              "ios_info": {
+                "bundle_id": "com.krowwithus.staff"
+              }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "client_info": {
+        "mobilesdk_app_id": "1:933560802882:android:1ae05d85c865f77c7757db",
+        "android_client_info": {
+          "package_name": "com.krowwithus.staff"
+        }
+      },
+      "oauth_client": [
+        {
+          "client_id": "933560802882-nh589kkndmur9hgibkgg5g8lhmo7mg3v.apps.googleusercontent.com",
+          "client_type": 1,
+          "android_info": {
+            "package_name": "com.krowwithus.staff",
+            "certificate_hash": "a6ef7fe8ade313e69377b178544192d835b29153"
+          }
+        },
+        {
+          "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+          "client_type": 3
+        }
+      ],
+      "api_key": [
+        {
+          "current_key": "AIzaSyDBYhflhK6DThKnS7RM-9raKdvyKzLUjY4"
+        }
+      ],
+      "services": {
+        "appinvite_service": {
+          "other_platform_oauth_client": [
+            {
+              "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+              "client_type": 3
+            },
+            {
+              "client_id": "933560802882-29olj9ku64jbe9h7flinha6hbi8qrluh.apps.googleusercontent.com",
+              "client_type": 2,
+              "ios_info": {
+                "bundle_id": "com.krowwithus.staff"
+              }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "client_info": {
+        "mobilesdk_app_id": "1:933560802882:android:1eb46251032273cb7757db",
+        "android_client_info": {
+          "package_name": "dev.krowwithus.client"
+        }
+      },
+      "oauth_client": [
+        {
+          "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+          "client_type": 3
+        }
+      ],
+      "api_key": [
+        {
+          "current_key": "AIzaSyDBYhflhK6DThKnS7RM-9raKdvyKzLUjY4"
+        }
+      ],
+      "services": {
+        "appinvite_service": {
+          "other_platform_oauth_client": [
+            {
+              "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+              "client_type": 3
+            },
+            {
+              "client_id": "933560802882-29olj9ku64jbe9h7flinha6hbi8qrluh.apps.googleusercontent.com",
+              "client_type": 2,
+              "ios_info": {
+                "bundle_id": "com.krowwithus.staff"
+              }
+            }
+          ]
+        }
+      }
+    },
+    {
+      "client_info": {
+        "mobilesdk_app_id": "1:933560802882:android:ee100eab75b6b04c7757db",
+        "android_client_info": {
+          "package_name": "dev.krowwithus.staff"
+        }
+      },
+      "oauth_client": [
+        {
+          "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+          "client_type": 3
+        }
+      ],
+      "api_key": [
+        {
+          "current_key": "AIzaSyDBYhflhK6DThKnS7RM-9raKdvyKzLUjY4"
+        }
+      ],
+      "services": {
+        "appinvite_service": {
+          "other_platform_oauth_client": [
+            {
+              "client_id": "933560802882-grp98a1v7amflnnup68vh01tj06eaem1.apps.googleusercontent.com",
+              "client_type": 3
+            },
+            {
+              "client_id": "933560802882-29olj9ku64jbe9h7flinha6hbi8qrluh.apps.googleusercontent.com",
+              "client_type": 2,
+              "ios_info": {
+                "bundle_id": "com.krowwithus.staff"
+              }
+            }
+          ]
+        }
+      }
+    }
+  ],
+  "configuration_version": "1"
+}

apps/mobile/apps/client/android/app/src/dev/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@android:color/white"/>
+    <foreground android:drawable="@mipmap/launcher_icon"/>
+</adaptive-icon>

apps/mobile/apps/client/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,48 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <application
+        android:label="@string/app_name"
+        android:name="${applicationName}"
+        android:icon="@mipmap/launcher_icon">
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:launchMode="singleTop"
+            android:taskAffinity=""
+            android:theme="@style/LaunchTheme"
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
+            android:hardwareAccelerated="true"
+            android:windowSoftInputMode="adjustResize">
+            <!-- Specifies an Android theme to apply to this Activity as soon as
+                 the Android process has started. This theme is visible to the user
+                 while the Flutter UI initializes. After that, this theme continues
+                 to determine the Window background behind the Flutter UI. -->
+            <meta-data
+              android:name="io.flutter.embedding.android.NormalTheme"
+              android:resource="@style/NormalTheme"
+              />
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN"/>
+                <category android:name="android.intent.category.LAUNCHER"/>
+            </intent-filter>
+        </activity>
+        <!-- Don't delete the meta-data below.
+             This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
+        <meta-data
+            android:name="flutterEmbedding"
+            android:value="2" />
+        <meta-data
+            android:name="com.google.android.geo.API_KEY"
+            android:value="${GOOGLE_MAPS_API_KEY}" />
+    </application>
+    <!-- Required to query activities that can process text, see:
+         https://developer.android.com/training/package-visibility and
+         https://developer.android.com/reference/android/content/Intent#ACTION_PROCESS_TEXT.
+
+         In particular, this is used by the Flutter engine in io.flutter.plugin.text.ProcessTextPlugin. -->
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.PROCESS_TEXT"/>
+            <data android:mimeType="text/plain"/>
+        </intent>
+    </queries>
+</manifest>

apps/mobile/apps/client/android/app/src/main/java/io/flutter/plugins/GeneratedPluginRegistrant.java

@@ -0,0 +1,84 @@
+package io.flutter.plugins;
+
+import androidx.annotation.Keep;
+import androidx.annotation.NonNull;
+import io.flutter.Log;
+
+import io.flutter.embedding.engine.FlutterEngine;
+
+/**
+ * Generated file. Do not edit.
+ * This file is generated by the Flutter tool based on the
+ * plugins that support the Android platform.
+ */
+@Keep
+public final class GeneratedPluginRegistrant {
+  private static final String TAG = "GeneratedPluginRegistrant";
+  public static void registerWith(@NonNull FlutterEngine flutterEngine) {
+    try {
+      flutterEngine.getPlugins().add(new com.mr.flutter.plugin.filepicker.FilePickerPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin file_picker, com.mr.flutter.plugin.filepicker.FilePickerPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new io.flutter.plugins.firebase.auth.FlutterFirebaseAuthPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin firebase_auth, io.flutter.plugins.firebase.auth.FlutterFirebaseAuthPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new io.flutter.plugins.firebase.core.FlutterFirebaseCorePlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin firebase_core, io.flutter.plugins.firebase.core.FlutterFirebaseCorePlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new com.dexterous.flutterlocalnotifications.FlutterLocalNotificationsPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin flutter_local_notifications, com.dexterous.flutterlocalnotifications.FlutterLocalNotificationsPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new io.flutter.plugins.flutter_plugin_android_lifecycle.FlutterAndroidLifecyclePlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin flutter_plugin_android_lifecycle, io.flutter.plugins.flutter_plugin_android_lifecycle.FlutterAndroidLifecyclePlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new com.baseflow.geolocator.GeolocatorPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin geolocator_android, com.baseflow.geolocator.GeolocatorPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new io.flutter.plugins.imagepicker.ImagePickerPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin image_picker_android, io.flutter.plugins.imagepicker.ImagePickerPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new dev.fluttercommunity.plus.packageinfo.PackageInfoPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin package_info_plus, dev.fluttercommunity.plus.packageinfo.PackageInfoPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new io.flutter.plugins.pathprovider.PathProviderPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin path_provider_android, io.flutter.plugins.pathprovider.PathProviderPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new com.llfbandit.record.RecordPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin record_android, com.llfbandit.record.RecordPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new io.flutter.plugins.sharedpreferences.SharedPreferencesPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin shared_preferences_android, io.flutter.plugins.sharedpreferences.SharedPreferencesPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new io.flutter.plugins.urllauncher.UrlLauncherPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin url_launcher_android, io.flutter.plugins.urllauncher.UrlLauncherPlugin", e);
+    }
+    try {
+      flutterEngine.getPlugins().add(new dev.fluttercommunity.workmanager.WorkmanagerPlugin());
+    } catch (Exception e) {
+      Log.e(TAG, "Error registering plugin workmanager_android, dev.fluttercommunity.workmanager.WorkmanagerPlugin", e);
+    }
+  }
+}

apps/mobile/apps/client/android/app/src/main/kotlin/com/krowwithus/client/MainActivity.kt

@@ -0,0 +1,5 @@
+package com.krowwithus.client
+
+import io.flutter.embedding.android.FlutterActivity
+
+class MainActivity : FlutterActivity()

apps/mobile/apps/client/android/app/src/main/res/drawable-v21/launch_background.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Modify this file to customize your launch splash screen -->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="?android:colorBackground" />
+
+    <!-- You can insert your own image assets here -->
+    <!-- <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@mipmap/launch_image" />
+    </item> -->
+</layer-list>

apps/mobile/apps/client/android/app/src/main/res/drawable/launch_background.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Modify this file to customize your launch splash screen -->
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="@android:color/white" />
+
+    <!-- You can insert your own image assets here -->
+    <!-- <item>
+        <bitmap
+            android:gravity="center"
+            android:src="@mipmap/launch_image" />
+    </item> -->
+</layer-list>

apps/mobile/apps/client/android/app/src/main/res/values-night/styles.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is on -->
+    <style name="LaunchTheme" parent="@android:style/Theme.Black.NoTitleBar">
+        <!-- Show a splash screen on the activity. Automatically removed when
+             the Flutter engine draws its first frame -->
+        <item name="android:windowBackground">@drawable/launch_background</item>
+    </style>
+    <!-- Theme applied to the Android Window as soon as the process has started.
+         This theme determines the color of the Android Window while your
+         Flutter UI initializes, as well as behind your Flutter UI while its
+         running.
+
+         This Theme is only used starting with V2 of Flutter's Android embedding. -->
+    <style name="NormalTheme" parent="@android:style/Theme.Black.NoTitleBar">
+        <item name="android:windowBackground">?android:colorBackground</item>
+    </style>
+</resources>

apps/mobile/apps/client/android/app/src/main/res/values/styles.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- Theme applied to the Android Window while the process is starting when the OS's Dark Mode setting is off -->
+    <style name="LaunchTheme" parent="@android:style/Theme.Light.NoTitleBar">
+        <!-- Show a splash screen on the activity. Automatically removed when
+             the Flutter engine draws its first frame -->
+        <item name="android:windowBackground">@drawable/launch_background</item>
+    </style>
+    <!-- Theme applied to the Android Window as soon as the process has started.
+         This theme determines the color of the Android Window while your
+         Flutter UI initializes, as well as behind your Flutter UI while its
+         running.
+
+         This Theme is only used starting with V2 of Flutter's Android embedding. -->
+    <style name="NormalTheme" parent="@android:style/Theme.Light.NoTitleBar">
+        <item name="android:windowBackground">?android:colorBackground</item>
+    </style>
+</resources>

apps/mobile/apps/client/android/app/src/profile/AndroidManifest.xml

@@ -0,0 +1,7 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- The INTERNET permission is required for development. Specifically,
+         the Flutter tool needs it to communicate with the running application
+         to allow setting breakpoints, to provide hot reload, etc.
+    -->
+    <uses-permission android:name="android.permission.INTERNET"/>
+</manifest>