Merge branch 'master' into android-safe-area-insets

.cursor/rules/README.md

@@ -0,0 +1,151 @@
+# .cursor Rules Organization
+
+This directory contains all the rules and guidelines for AI assistants working
+with the TimeSafari project.
+
+## Directory Structure
+
+### **`core/`** - Core Principles and Context
+
+Core rules that apply to all AI interactions and provide fundamental context.
+
+- **`base_context.mdc`** - Human competence first principles and interaction guidelines
+- **`harbor_pilot_universal.mdc`** - Technical guide creation and investigation rules
+- **`less_complex.mdc`** - Minimalist solution principle and complexity guidelines
+
+### **`development/`** - Development Practices and Standards
+
+Rules for software development, coding standards, and development workflows.
+
+- **`software_development.mdc`** - Core development principles and evidence requirements
+- **`type_safety_guide.mdc`** - TypeScript type safety guidelines and best practices
+- **`development_guide.mdc`** - Development environment setup and standards
+- **`logging_standards.mdc`** - Logging implementation standards and rules
+- **`logging_migration.mdc`** - Migration from console.* to structured logging
+- **`time.mdc`** - Time handling principles and UTC standards
+- **`time_examples.mdc`** - Practical time implementation examples
+- **`time_implementation.mdc`** - Detailed time implementation guidelines
+- **`realistic_time_estimation.mdc`** - Time estimation framework and principles
+- **`planning_examples.mdc`** - Planning examples and best practices
+- **`complexity_assessment.mdc`** - Complexity evaluation and assessment
+- **`dependency_management.mdc`** - Dependency management and version control
+- **`asset_configuration.mdc`** - Asset configuration and build integration
+- **`research_diagnostic.mdc`** - Research and investigation workflows
+- **`investigation_report_example.mdc`** - Investigation report templates and examples
+- **`historical_comment_management.mdc`** - Historical comment transformation rules
+- **`historical_comment_patterns.mdc`** - Comment transformation patterns and examples
+
+### **`architecture/`** - Architecture and Design Patterns
+
+Rules for architectural decisions, patterns, and system design.
+
+- **`build_architecture_guard.mdc`** - Build system protection and change levels
+- **`build_validation.mdc`** - Build validation procedures and testing
+- **`build_testing.mdc`** - Build testing requirements and feedback collection
+
+### **`app/`** - Application-Specific Rules
+
+Rules specific to the TimeSafari application and its architecture.
+
+- **`timesafari.mdc`** - Core application context and principles
+- **`timesafari_platforms.mdc`** - Platform-specific implementation guidelines
+- **`timesafari_development.mdc`** - TimeSafari development workflow
+- **`architectural_decision_record.mdc`** - ADR creation and management
+- **`architectural_implementation.mdc`** - Architecture implementation guidelines
+- **`architectural_patterns.mdc`** - Architectural patterns and examples
+- **`architectural_examples.mdc`** - Architecture examples and testing
+
+### **`database/`** - Database and Data Management
+
+Rules for database operations, migrations, and data handling.
+
+- **`absurd-sql.mdc`** - Absurd SQL implementation and worker thread setup
+- **`legacy_dexie.mdc`** - Legacy Dexie migration guidelines
+
+### **`workflow/`** - Process and Workflow Management
+
+Rules for development workflows, version control, and process management.
+
+- **`version_control.mdc`** - Version control principles and commit guidelines
+- **`version_sync.mdc`** - Version synchronization and changelog management
+- **`commit_messages.mdc`** - Commit message format and conventions
+
+### **`features/** - Feature-Specific Implementations
+
+Rules for implementing specific features across platforms.
+
+- **`camera-implementation.mdc`** - Camera feature implementation overview
+- **`camera_technical.mdc`** - Technical camera implementation details
+- **`camera_platforms.mdc`** - Platform-specific camera implementation
+
+### **`docs/`** - Documentation Standards
+
+Rules for creating and maintaining documentation.
+
+- **`markdown_core.mdc`** - Core markdown formatting standards
+- **`markdown_templates.mdc`** - Document templates and examples
+- **`markdown_workflow.mdc`** - Markdown validation and workflow
+- **`documentation.mdc`** - Documentation generation principles
+- **`meta_rule_usage_guide.md`** - How to use meta-rules in practice
+
+### **`templates/`** - Templates and Examples
+
+Template files and examples for various documentation types.
+
+- **`adr_template.mdc`** - Architectural Decision Record template
+
+### **Meta-Rules** - Workflow Bundling
+
+High-level meta-rules that bundle related sub-rules for specific workflows.
+
+- **`meta_core_always_on.mdc`** - Core rules that apply to every single prompt
+- **`meta_documentation.mdc`** - Documentation writing and education workflow
+- **`meta_feature_planning.mdc`** - Feature planning workflow bundling
+- **`meta_bug_diagnosis.mdc`** - Bug investigation workflow bundling
+- **`meta_bug_fixing.mdc`** - Bug fix implementation workflow bundling
+- **`meta_feature_implementation.mdc`** - Feature implementation workflow bundling
+
+## Usage Guidelines
+
+1. **Always-On Rules**: Start with `meta_core_always_on.mdc` for every
+   single prompt
+2. **Core Rules**: Always apply rules from `core/` directory
+3. **Context-Specific**: Use rules from appropriate subdirectories based on
+   your task
+4. **Meta-Rules**: Use workflow-specific meta-rules for specialized tasks
+   - **Documentation**: Use `meta_documentation.mdc` for all documentation work
+   - **Getting Started**: See `docs/meta_rule_usage_guide.md` for comprehensive usage instructions
+5. **Cross-References**: All files contain updated cross-references to
+   reflect the new structure
+6. **Validation**: All files pass markdown validation and maintain
+   consistent formatting
+
+## Benefits of New Organization
+
+1. **Logical grouping** - Related rules are now co-located
+2. **Easier navigation** - Developers can quickly find relevant rules
+3. **Better maintainability** - Clear separation of concerns
+4. **Scalable structure** - Easy to add new rules in appropriate categories
+5. **Consistent cross-references** - All file links updated and working
+6. **Workflow bundling** - Meta-rules provide high-level workflow guidance
+7. **Feedback integration** - Built-in feedback mechanisms for continuous improvement
+8. **Educational focus** - Documentation emphasizes human competence over technical description
+
+## File Naming Convention
+
+- **Lowercase with underscores**: `file_name.mdc`
+- **Descriptive names**: Names clearly indicate the rule's purpose
+- **Consistent extensions**: All files use `.mdc` extension
+
+## Maintenance
+
+- **Cross-references**: Update when moving files between directories
+- **Markdown validation**: Run `npm run markdown:check` after any changes
+- **Organization**: Keep related rules in appropriate subdirectories
+- **Documentation**: Update this README when adding new rules or directories
+
+---
+
+**Status**: Active organization structure
+**Last Updated**: 2025-08-21
+**Maintainer**: Development team

.cursor/rules/app/architectural_decision_record.mdc

@@ -1,7 +1,3 @@
----
-description: when you need to understand the system architecture or make changes that impact the system architecture
-alwaysApply: false
----
 # TimeSafari Cross-Platform Architecture Guide
 
 **Author**: Matthew Raymer
@@ -12,17 +8,20 @@ alwaysApply: false
 
 | Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) |
 |---------|-----------|--------------------|-------------------|
-| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented |
+| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning |
+  Not Implemented |
 | Deep Linking | URL Parameters | App URL Open Events | Not Implemented |
 | File System | Limited (Browser API) | Capacitor Filesystem | Electron fs |
 | Camera Access | MediaDevices API | Capacitor Camera | Not Implemented |
-| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks |
+| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env
+  checks |
 
 ## 2. Project Structure
 
 ### Core Directories
 
 ```
+
 src/
 ├── components/     # Vue components
 ├── services/       # Platform services and business logic
@@ -37,14 +36,19 @@ src/
 ├── db/             # Database related code
 ├── interfaces/     # TypeScript interfaces
 └── assets/         # Static assets
+
 ```
 
 ### Entry Points
 
 - `main.ts` → Base entry
+
 - `main.common.ts` → Shared init
+
 - `main.capacitor.ts` → Mobile entry
+
 - `main.electron.ts` → Electron entry
+
 - `main.web.ts` → Web entry
 
 ## 3. Service Architecture
@@ -52,16 +56,18 @@ src/
 ### Service Organization
 
 ```tree
+
 services/
-├── QRScanner/           
+├── QRScanner/
 │   ├── WebInlineQRScanner.ts
 │   └── interfaces.ts
-├── platforms/          
+├── platforms/
 │   ├── WebPlatformService.ts
 │   ├── CapacitorPlatformService.ts
 │   └── ElectronPlatformService.ts
-└── factory/           
+└── factory/
     └── PlatformServiceFactory.ts
+
 ```
 
 ### Factory Pattern
@@ -74,279 +80,114 @@ Use a **singleton factory** to select platform services via
 ### QR Code Scanning
 
 - Define `QRScannerService` interface.
+
 - Implement platform-specific classes (`WebInlineQRScanner`, Capacitor,
+
   etc).
+
 - Provide `addListener` and `onStream` hooks for composability.
 
 ### Deep Linking
 
 - URL format: `timesafari://<route>[/<param>][?query=value]`
+
 - Web: `router.beforeEach` → parse query
+
 - Capacitor: `App.addListener("appUrlOpen", …)`
 
 ## 5. Build Process
 
 - `vite.config.common.mts` → shared config
+
 - Platform configs: `vite.config.web.mts`, `.capacitor.mts`,
+
   `.electron.mts`
+
 - Use `process.env.VITE_PLATFORM` for conditional loading.
 
 ```bash
+
 npm run build:web
 npm run build:capacitor
 npm run build:electron
+
 ```
 
 ## 6. Testing Strategy
 
-- **Unit tests** for services.
+- **Unit Tests**: Jest for business logic and utilities
-- **Playwright** for Web + Capacitor:
-  - `playwright.config-local.ts` includes web + Pixel 5.
-- **Electron tests**: add `spectron` or Playwright-Electron.
-- Mark tests with platform tags:
 
-  ```ts
+- **E2E Tests**: Playwright for critical user journeys
-  test.skip(!process.env.MOBILE_TEST, "Mobile-only test");
-  ```
 
-> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15
+- **Platform Tests**: Test platform-specific implementations
-> min) with QA to align on coverage and flaky test risks.
 
-## 7. Error Handling
+- **Integration Tests**: Test service interactions
 
-- Global Vue error handler → logs with component name.
+## 7. Key Principles
-- Platform-specific wrappers log API errors with platform prefix
-  (`[Capacitor API Error]`, etc).
-- Use structured logging (not `console.log`).
 
-## 8. Best Practices
+### Platform Independence
 
-- Keep platform code **isolated** in `platforms/`.
+- **Abstract platform differences** behind interfaces
-- Always define a **shared interface** first.
-- Use feature detection, not platform detection, when possible.
-- Dependency injection for services → improves testability.
-- Maintain **Competence Hooks** in PRs (2–3 prompts for dev
-  discussion).
 
-## 9. Dependency Management
+- **Use factory pattern** for service selection
 
-- Key deps: `@capacitor/core`, `electron`, `vue`.
+- **Maintain consistent APIs** across platforms
-- Use conditional `import()` for platform-specific libs.
 
-## 10. Security Considerations
+- **Graceful degradation** when features unavailable
 
-- **Permissions**: Always check + request gracefully.
+### Code Organization
-- **Storage**: Secure storage for sensitive data; encrypt when possible.
-- **Audits**: Schedule quarterly security reviews.
 
-## 11. ADR Process
+- **Single responsibility** for each service
 
-- All major architecture choices → log in `doc/adr/`.
+- **Interface segregation** for platform services
-- Use ADR template with Context, Decision, Consequences, Status.
-- Link related ADRs in PR descriptions.
 
-> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min
+- **Dependency injection** via mixins
-> design sync for discussion, not just async review.
 
-## 12. Collaboration Hooks
+- **Composition over inheritance**
-
-- **QR features**: Sync with Security before merging → permissions &
-  privacy.
-- **New platform builds**: Demo in team meeting → confirm UX
-  differences.
-- **Critical ADRs**: Present in guild or architecture review.
-
-## Self-Check
-
-- [ ] Does this feature implement a shared interface?
-- [ ] Are fallbacks + errors handled gracefully?
-- [ ] Have relevant ADRs been updated/linked?
-- [ ] Did I add competence hooks or prompts for the team?
-- [ ] Was human interaction (sync/review/demo) scheduled?
 
 ---
 
+**See also**:
+
+- `.cursor/rules/app/architectural_implementation.mdc` for
+
+  detailed implementation details
+
+- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and
+
+  examples
+
 **Status**: Active architecture guidelines
-**Priority**: High
+**Priority**: Critical
 **Estimated Effort**: Ongoing reference
-**Dependencies**: Vue 3, Capacitor, Electron, Vite
+**Dependencies**: timesafari.mdc
 **Stakeholders**: Development team, Architecture team
 
-- [ ] Are fallbacks + errors handled gracefully?  
-- [ ] Have relevant ADRs been updated/linked?  
-- [ ] Did I add competence hooks or prompts for the team?  
-- [ ] Was human interaction (sync/review/demo) scheduled?  
-# TimeSafari Cross-Platform Architecture Guide
-
-**Author**: Matthew Raymer
-**Date**: 2025-08-19
-**Status**: 🎯 **ACTIVE** - Architecture guidelines
-
-## 1. Platform Support Matrix
-
-| Feature | Web (PWA) | Capacitor (Mobile) | Electron (Desktop) |
-|---------|-----------|--------------------|-------------------|
-| QR Code Scanning | WebInlineQRScanner | @capacitor-mlkit/barcode-scanning | Not Implemented |
-| Deep Linking | URL Parameters | App URL Open Events | Not Implemented |
-| File System | Limited (Browser API) | Capacitor Filesystem | Electron fs |
-| Camera Access | MediaDevices API | Capacitor Camera | Not Implemented |
-| Platform Detection | Web APIs | Capacitor.isNativePlatform() | process.env checks |
-
-## 2. Project Structure
-
-### Core Directories
-
-```
-src/
-├── components/     # Vue components
-├── services/       # Platform services and business logic
-├── views/          # Page components
-├── router/         # Vue router configuration
-├── types/          # TypeScript type definitions
-├── utils/          # Utility functions
-├── lib/            # Core libraries
-├── platforms/      # Platform-specific implementations
-├── electron/       # Electron-specific code
-├── constants/      # Application constants
-├── db/             # Database related code
-├── interfaces/     # TypeScript interfaces
-└── assets/         # Static assets
-```
-
-### Entry Points
-
-- `main.ts` → Base entry
-- `main.common.ts` → Shared init
-- `main.capacitor.ts` → Mobile entry
-- `main.electron.ts` → Electron entry
-- `main.web.ts` → Web entry
-
-## 3. Service Architecture
-
-### Service Organization
-
-```tree
-services/
-├── QRScanner/           
-│   ├── WebInlineQRScanner.ts
-│   └── interfaces.ts
-├── platforms/          
-│   ├── WebPlatformService.ts
-│   ├── CapacitorPlatformService.ts
-│   └── ElectronPlatformService.ts
-└── factory/           
-    └── PlatformServiceFactory.ts
-```
-
-### Factory Pattern
-
-Use a **singleton factory** to select platform services via
-`process.env.VITE_PLATFORM`.
-
-## 4. Feature Guidelines
-
-### QR Code Scanning
-
-- Define `QRScannerService` interface.
-- Implement platform-specific classes (`WebInlineQRScanner`, Capacitor,
-  etc).
-- Provide `addListener` and `onStream` hooks for composability.
-
-### Deep Linking
-
-- URL format: `timesafari://<route>[/<param>][?query=value]`
-- Web: `router.beforeEach` → parse query
-- Capacitor: `App.addListener("appUrlOpen", …)`
-
-## 5. Build Process
-
-- `vite.config.common.mts` → shared config
-- Platform configs: `vite.config.web.mts`, `.capacitor.mts`,
-  `.electron.mts`
-- Use `process.env.VITE_PLATFORM` for conditional loading.
-
-```bash
-npm run build:web
-npm run build:capacitor
-npm run build:electron
-```
-
-## 6. Testing Strategy
-
-- **Unit tests** for services.
-- **Playwright** for Web + Capacitor:
-  - `playwright.config-local.ts` includes web + Pixel 5.
-- **Electron tests**: add `spectron` or Playwright-Electron.
-- Mark tests with platform tags:
-
-  ```ts
-  test.skip(!process.env.MOBILE_TEST, "Mobile-only test");
-  ```
-
-> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15
-> min) with QA to align on coverage and flaky test risks.
-
-## 7. Error Handling
-
-- Global Vue error handler → logs with component name.
-- Platform-specific wrappers log API errors with platform prefix
-  (`[Capacitor API Error]`, etc).
-- Use structured logging (not `console.log`).
-
-## 8. Best Practices
-
-- Keep platform code **isolated** in `platforms/`.
-- Always define a **shared interface** first.
-- Use feature detection, not platform detection, when possible.
-- Dependency injection for services → improves testability.
-- Maintain **Competence Hooks** in PRs (2–3 prompts for dev
-  discussion).
-
-## 9. Dependency Management
-
-- Key deps: `@capacitor/core`, `electron`, `vue`.
-- Use conditional `import()` for platform-specific libs.
-
-## 10. Security Considerations
-
-- **Permissions**: Always check + request gracefully.
-- **Storage**: Secure storage for sensitive data; encrypt when possible.
-- **Audits**: Schedule quarterly security reviews.
-
-## 11. ADR Process
-
-- All major architecture choices → log in `doc/adr/`.
-- Use ADR template with Context, Decision, Consequences, Status.
-- Link related ADRs in PR descriptions.
-
-> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min
-> design sync for discussion, not just async review.
-
-## 12. Collaboration Hooks
-
-- **QR features**: Sync with Security before merging → permissions &
-  privacy.
-- **New platform builds**: Demo in team meeting → confirm UX
-  differences.
-- **Critical ADRs**: Present in guild or architecture review.
-
-## Self-Check
-
-- [ ] Does this feature implement a shared interface?
-- [ ] Are fallbacks + errors handled gracefully?
 - [ ] Have relevant ADRs been updated/linked?
+
 - [ ] Did I add competence hooks or prompts for the team?
+
 - [ ] Was human interaction (sync/review/demo) scheduled?
 
----
+## Model Implementation Checklist
 
-**Status**: Active architecture guidelines
+### Before Architectural Decisions
-**Priority**: High
-**Estimated Effort**: Ongoing reference
-**Dependencies**: Vue 3, Capacitor, Electron, Vite
-**Stakeholders**: Development team, Architecture team
 
-- [ ] Are fallbacks + errors handled gracefully?  
+- [ ] **Decision Context**: Understand the architectural challenge to be addressed
-- [ ] Have relevant ADRs been updated/linked?  
+- [ ] **Stakeholder Identification**: Identify all decision makers and affected parties
-- [ ] Did I add competence hooks or prompts for the team?  
+- [ ] **Research**: Research alternatives and gather evidence
-- [ ] Was human interaction (sync/review/demo) scheduled?  
+- [ ] **Impact Assessment**: Assess impact on existing architecture
+
+### During Architectural Decisions
+
+- [ ] **Context Documentation**: Document the context and forces at play
+- [ ] **Decision Recording**: Record the decision and rationale clearly
+- [ ] **Consequences Analysis**: Analyze positive, negative, and neutral consequences
+- [ ] **Alternatives Documentation**: Document alternatives considered and why rejected
+
+### After Architectural Decisions
+
+- [ ] **ADR Creation**: Create or update Architectural Decision Record
+- [ ] **Team Communication**: Communicate decision to all stakeholders
+- [ ] **Implementation Planning**: Plan implementation of the architectural decision
+- [ ] **Documentation Update**: Update relevant architectural documentation

.cursor/rules/app/architectural_examples.mdc

@@ -0,0 +1,246 @@
+# Time Safari Architecture — Examples and Testing
+
+> **Agent role**: Reference this file for architectural examples and
+  testing patterns when working with TimeSafari architecture.
+
+## Error Handling Patterns
+
+### Global Error Handler
+
+```typescript
+
+// main.ts
+app.config.errorHandler = (err, instance, info) => {
+  const componentName = instance?.$options?.name || 'Unknown';
+  logger.error(`[${componentName}] Vue error`, err, info);
+};
+
+window.addEventListener('unhandledrejection', (event) => {
+  logger.error('[Global] Unhandled promise rejection', event.reason);
+});
+
+```
+
+### Platform-Specific Error Wrapping
+
+```typescript
+
+// services/platforms/CapacitorPlatformService.ts
+export class CapacitorPlatformService {
+  async getFileContents(path: string): Promise<string> {
+    try {
+      const result = await Filesystem.readFile({
+        path: path,
+        encoding: 'utf8'
+      });
+      return result.data;
+    } catch (error) {
+      logger.error('[Capacitor API Error] Failed to read file', error, path);
+      throw new Error(`Failed to read file: ${path}`);
+    }
+  }
+}
+
+```
+
+## Testing Patterns
+
+### Platform-Specific Test Skipping
+
+```typescript
+
+// tests/QRScanner.test.ts
+describe('QRScanner Service', () => {
+  test('should start scanning on web', async () => {
+    test.skip(process.env.VITE_PLATFORM !== 'web', 'Web-only test');
+
+    const scanner = new WebInlineQRScanner();
+    await scanner.startScanning();
+    // Assert scanning started
+  });
+
+  test('should start scanning on mobile', async () => {
+    test.skip(process.env.VITE_PLATFORM !== 'capacitor', 'Mobile-only test');
+
+    const scanner = new CapacitorQRScanner();
+    await scanner.startScanning();
+    // Assert scanning started
+  });
+});
+
+```
+
+### Mock Service Testing
+
+```typescript
+
+// tests/mocks/QRScannerMock.ts
+export class QRScannerMock implements QRScannerService {
+  private isScanning = false;
+  private listeners: Map<string, Function[]> = new Map();
+
+  async startScanning(): Promise<void> {
+    this.isScanning = true;
+    this.emit('scanningStarted');
+  }
+
+  async stopScanning(): Promise<void> {
+    this.isScanning = false;
+    this.emit('scanningStopped');
+  }
+
+  addListener(event: string, callback: Function): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event)!.push(callback);
+  }
+
+  removeListener(event: string, callback: Function): void {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      const index = callbacks.indexOf(callback);
+      if (index > -1) {
+        callbacks.splice(index, 1);
+      }
+    }
+  }
+
+  private emit(event: string, ...args: any[]): void {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      callbacks.forEach(callback => callback(...args));
+    }
+  }
+
+  getScanningState(): boolean {
+    return this.isScanning;
+  }
+}
+
+```
+
+## Integration Examples
+
+### Service Composition
+
+```typescript
+
+// services/QRScannerService.ts
+export class QRScannerService {
+  constructor(
+    private platformService: PlatformService,
+    private notificationService: NotificationService
+  ) {}
+
+  async startScanning(): Promise<void> {
+    try {
+      await this.platformService.startCamera();
+      this.notificationService.show('Camera started');
+    } catch (error) {
+      this.notificationService.showError('Failed to start camera');
+      throw error;
+    }
+  }
+}
+
+```
+
+### Component Integration
+
+```typescript
+
+// components/QRScannerDialog.vue
+export default class QRScannerDialog extends Vue {
+  @Inject() private qrScannerService!: QRScannerService;
+
+  async mounted() {
+    try {
+      await this.qrScannerService.startScanning();
+    } catch (error) {
+      this.$notify.error('Failed to start scanner');
+    }
+  }
+
+  beforeDestroy() {
+    this.qrScannerService.stopScanning();
+  }
+}
+
+```
+
+## Best Practices
+
+### Service Design
+
+- Keep services focused and single-purpose
+
+- Use dependency injection for service composition
+
+- Implement proper error handling and logging
+
+- Provide clear interfaces and contracts
+
+### Testing Strategy
+
+- Test platform-specific behavior separately
+
+- Use mocks for external dependencies
+
+- Test error conditions and edge cases
+
+- Validate service contracts and interfaces
+
+### Error Handling
+
+- Log errors with appropriate context
+
+- Provide user-friendly error messages
+
+- Implement graceful degradation
+
+- Handle platform-specific error scenarios
+
+---
+
+**See also**:
+
+- `.cursor/rules/app/architectural_decision_record.mdc` for
+
+  core architecture principles
+
+- `.cursor/rules/app/architectural_implementation.mdc` for
+
+  implementation details
+
+- `.cursor/rules/app/architectural_patterns.mdc` for core patterns
+
+**Status**: Active examples and testing guide
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: architectural_patterns.mdc
+**Stakeholders**: Development team, Testing team
+
+## Model Implementation Checklist
+
+### Before Architectural Examples
+
+- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use
+  case
+- [ ] **Service Design**: Plan service structure and dependencies
+- [ ] **Testing Strategy**: Plan testing approach for the example
+- [ ] **Error Handling**: Plan error handling and logging strategy
+
+### During Architectural Examples
+
+- [ ] **Service Implementation**: Implement focused, single-purpose services
+- [ ] **Dependency Injection**: Use proper dependency injection patterns
+- [ ] **Error Handling**: Implement proper error handling and logging
+- [ ] **Interface Design**: Provide clear interfaces and contracts
+
+### After Architectural Examples
+
+- [ ] **Testing Execution**: Test platform-specific behavior separately
+- [ ] **Service Validation**: Validate service contracts and interfaces
+- [ ] **Error Testing**: Test error conditions and edge cases
+- [ ] **Documentation**: Update architectural examples documentation

.cursor/rules/app/architectural_implementation.mdc

@@ -0,0 +1,139 @@
+# Time Safari Architecture — Implementation Details
+
+> **Agent role**: Reference this file for detailed implementation details when
+  working with TimeSafari architecture implementation.
+
+## Error Handling
+
+- Global Vue error handler → logs with component name.
+
+- Platform-specific wrappers log API errors with platform prefix
+
+  (`[Capacitor API Error]`, etc).
+
+- Use structured logging (not `console.log`).
+
+## Best Practices
+
+- Keep platform code **isolated** in `platforms/`.
+
+- Always define a **shared interface** first.
+
+- Use feature detection, not platform detection, when possible.
+
+- Dependency injection for services → improves testability.
+
+- Maintain **Competence Hooks** in PRs (2–3 prompts for dev
+
+  discussion).
+
+## Dependency Management
+
+- Key deps: `@capacitor/core`, `electron`, `vue`.
+
+- Use conditional `import()` for platform-specific libs.
+
+## Security Considerations
+
+- **Permissions**: Always check + request gracefully.
+
+- **Storage**: Secure storage for sensitive data; encrypt when possible.
+
+- **Audits**: Schedule quarterly security reviews.
+
+## ADR Process
+
+- All major architecture choices → log in `doc/adr/`.
+
+- Use ADR template with Context, Decision, Consequences, Status.
+
+- Link related ADRs in PR descriptions.
+
+> 🔗 **Human Hook:** When proposing a new ADR, schedule a 30-min
+> design sync for discussion, not just async review.
+
+## Collaboration Hooks
+
+- **QR features**: Sync with Security before merging → permissions &
+
+  privacy.
+
+- **New platform builds**: Demo in team meeting → confirm UX
+
+  differences.
+
+- **Critical ADRs**: Present in guild or architecture review.
+
+## Testing Implementation
+
+- **Unit tests** for services.
+
+- **Playwright** for Web + Capacitor:
+
+  - `playwright.config-local.ts` includes web + Pixel 5.
+
+- **Electron tests**: add `spectron` or Playwright-Electron.
+
+- Mark tests with platform tags:
+
+  ```ts
+
+  test.skip(!process.env.MOBILE_TEST, "Mobile-only test");
+
+  ```
+
+> 🔗 **Human Hook:** Before merging new tests, hold a short sync (≤15
+> min) with QA to align on coverage and flaky test risks.
+
+## Self-Check
+
+- [ ] Does this feature implement a shared interface?
+
+- [ ] Are fallbacks + errors handled gracefully?
+
+- [ ] Have relevant ADRs been updated/linked?
+
+- [ ] Did I add competence hooks or prompts for the team?
+
+- [ ] Was human interaction (sync/review/demo) scheduled?
+
+---
+
+**See also**:
+
+- `.cursor/rules/app/architectural_decision_record.mdc` for
+
+  core architecture principles
+
+- `.cursor/rules/app/architectural_patterns.mdc` for architectural patterns and
+
+  examples
+
+**Status**: Active implementation guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: architectural_decision_record.mdc
+**Stakeholders**: Development team, Architecture team
+
+## Model Implementation Checklist
+
+### Before Architectural Implementation
+
+- [ ] **Interface Review**: Verify feature implements shared interface
+- [ ] **ADR Review**: Check if ADR is required for major changes
+- [ ] **Security Assessment**: Assess security implications for QR features
+- [ ] **Platform Planning**: Plan platform-specific implementation details
+
+### During Architectural Implementation
+
+- [ ] **Interface Implementation**: Implement shared interfaces consistently
+- [ ] **Error Handling**: Implement graceful fallbacks and error handling
+- [ ] **Testing Strategy**: Plan unit tests for services and E2E tests
+- [ ] **Human Interaction**: Schedule syncs/reviews/demos as needed
+
+### After Architectural Implementation
+
+- [ ] **Interface Validation**: Verify shared interfaces are properly implemented
+- [ ] **Testing Execution**: Run unit tests and platform-specific tests
+- [ ] **ADR Updates**: Update relevant ADRs and link in PR descriptions
+- [ ] **Team Communication**: Share implementation results with team

.cursor/rules/app/architectural_patterns.mdc

@@ -0,0 +1,214 @@
+# Time Safari Architecture — Patterns and Examples
+
+> **Agent role**: Reference this file for architectural patterns and
+> examples when working with TimeSafari architecture design.
+
+## Architectural Patterns
+
+### Factory Pattern Implementation
+
+```typescript
+// PlatformServiceFactory.ts
+export class PlatformServiceFactory {
+  private static instance: PlatformServiceFactory;
+
+  static getInstance(): PlatformServiceFactory {
+    if (!PlatformServiceFactory.instance) {
+      PlatformServiceFactory.instance = new PlatformServiceFactory();
+    }
+    return PlatformServiceFactory.instance;
+  }
+
+  getQRScannerService(): QRScannerService {
+    const platform = process.env.VITE_PLATFORM;
+
+    switch (platform) {
+      case 'web':
+        return new WebInlineQRScanner();
+      case 'capacitor':
+        return new CapacitorQRScanner();
+      case 'electron':
+        return new ElectronQRScanner();
+      default:
+        throw new Error(`Unsupported platform: ${platform}`);
+    }
+  }
+}
+```
+
+### Service Interface Definition
+
+```typescript
+// interfaces/QRScannerService.ts
+export interface QRScannerService {
+  startScanning(): Promise<void>;
+  stopScanning(): Promise<void>;
+  addListener(event: string, callback: Function): void;
+  removeListener(event: string, callback: Function): void;
+}
+```
+
+### Platform-Specific Implementation
+
+```typescript
+// services/QRScanner/WebInlineQRScanner.ts
+export class WebInlineQRScanner implements QRScannerService {
+  private listeners: Map<string, Function[]> = new Map();
+
+  async startScanning(): Promise<void> {
+    // Web-specific implementation
+    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
+    // Process video stream for QR codes
+  }
+
+  async stopScanning(): Promise<void> {
+    // Stop video stream
+  }
+
+  addListener(event: string, callback: Function): void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event)!.push(callback);
+  }
+
+  removeListener(event: string, callback: Function): void {
+    const callbacks = this.listeners.get(event);
+    if (callbacks) {
+      const index = callbacks.indexOf(callback);
+      if (index > -1) {
+        callbacks.splice(index, 1);
+      }
+    }
+  }
+}
+```
+
+## Deep Linking Implementation
+
+### URL Format
+
+```
+timesafari://<route>[/<param>][?query=value]
+```
+
+### Web Implementation
+
+```typescript
+// router/index.ts
+router.beforeEach((to, from, next) => {
+  // Parse deep link parameters
+  if (to.query.deepLink) {
+    const deepLink = to.query.deepLink as string;
+    // Process deep link
+    handleDeepLink(deepLink);
+  }
+  next();
+});
+
+function handleDeepLink(deepLink: string) {
+  // Parse and route deep link
+  const url = new URL(deepLink);
+  const route = url.pathname;
+  const params = url.searchParams;
+
+  // Navigate to appropriate route
+  router.push({ name: route, query: Object.fromEntries(params) });
+}
+```
+
+### Capacitor Implementation
+
+```typescript
+// main.capacitor.ts
+import { App } from '@capacitor/app';
+
+App.addListener('appUrlOpen', (data) => {
+  const url = data.url;
+  // Parse deep link and navigate
+  handleDeepLink(url);
+});
+```
+
+## Platform Detection
+
+### Feature Detection vs Platform Detection
+
+```typescript
+// ✅ Good: Feature detection
+function hasCameraAccess(): boolean {
+  return 'mediaDevices' in navigator &&
+         'getUserMedia' in navigator.mediaDevices;
+}
+
+// ❌ Bad: Platform detection
+function isWeb(): boolean {
+  return process.env.VITE_PLATFORM === 'web';
+}
+```
+
+### Conditional Imports
+
+```typescript
+// services/platforms/index.ts
+export async function getPlatformService() {
+  const platform = process.env.VITE_PLATFORM;
+
+  switch (platform) {
+    case 'capacitor':
+      const { CapacitorPlatformService } =
+        await import('./CapacitorPlatformService');
+      return new CapacitorPlatformService();
+    case 'electron':
+      const { ElectronPlatformService } =
+        await import('./ElectronPlatformService');
+      return new ElectronPlatformService();
+    default:
+      const { WebPlatformService } =
+        await import('./WebPlatformService');
+      return new WebPlatformService();
+  }
+}
+```
+
+---
+
+**See also**:
+
+- `.cursor/rules/app/architectural_decision_record.mdc` for core
+  architecture principles
+- `.cursor/rules/app/architectural_implementation.mdc` for
+  implementation details
+- `.cursor/rules/app/architectural_examples.mdc` for examples and
+  testing patterns
+
+**Status**: Active patterns and examples
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: architectural_decision_record.mdc,
+  architectural_implementation.mdc
+**Stakeholders**: Development team, Architecture team
+
+## Model Implementation Checklist
+
+### Before Architectural Patterns
+
+- [ ] **Pattern Selection**: Choose appropriate architectural pattern for the use
+  case
+- [ ] **Platform Analysis**: Identify platform-specific requirements
+- [ ] **Service Planning**: Plan service structure and dependencies
+- [ ] **Testing Strategy**: Plan testing approach for the pattern
+
+### During Architectural Patterns
+
+- [ ] **Pattern Implementation**: Implement chosen architectural pattern
+- [ ] **Platform Abstraction**: Use platform abstraction layers appropriately
+- [ ] **Service Composition**: Compose services using dependency injection
+- [ ] **Interface Design**: Provide clear interfaces and contracts
+
+### After Architectural Patterns
+
+- [ ] **Pattern Validation**: Verify pattern is implemented correctly
+- [ ] **Platform Testing**: Test across all target platforms
+- [ ] **Service Testing**: Test service composition and dependencies
+- [ ] **Documentation**: Update architectural patterns documentation

.cursor/rules/app/timesafari.mdc

@@ -1,3 +1,6 @@
+---
+alwaysApply: false
+---
 # Time Safari Context
 
 **Author**: Matthew Raymer
@@ -15,10 +18,12 @@ that preserve privacy and data sovereignty.
 ## Core Goals
 
 1. **Connect**: Make it easy, rewarding, and non-threatening for people to
+
    connect with others who have similar interests, and to initiate activities
    together.
 
 2. **Reveal**: Widely advertise the great support and rewards that are being
+
    given and accepted freely, especially non-monetary ones, showing the impact
    gifts make in people's lives.
 
@@ -27,29 +32,45 @@ that preserve privacy and data sovereignty.
 ### Architecture
 
 - **Privacy-preserving claims architecture** via endorser.ch
+
 - **Decentralized Identifiers (DIDs)**: User identities based on
+
   public/private key pairs stored on devices
+
 - **Cryptographic Verification**: All claims and confirmations are
+
   cryptographically signed
+
 - **User-Controlled Visibility**: Users explicitly control who can see their
+
   identifiers and data
+
 - **Cross-Platform**: Web (PWA), Mobile (Capacitor), Desktop (Electron)
 
 ### Current Database State
 
 - **Database**: SQLite via Absurd SQL (browser) and native SQLite
+
   (mobile/desktop)
+
 - **Legacy Support**: IndexedDB (Dexie) for backward compatibility
+
 - **Status**: Modern database architecture fully implemented
 
 ### Core Technologies
 
 - **Frontend**: Vue 3 + TypeScript + vue-facing-decorator
+
 - **Styling**: TailwindCSS
+
 - **Build**: Vite with platform-specific configs
+
 - **Testing**: Playwright E2E, Jest unit tests
+
 - **Database**: SQLite (Absurd SQL in browser), IndexedDB (legacy)
+
 - **State**: Pinia stores
+
 - **Platform Services**: Abstracted behind interfaces with factory pattern
 
 ## Development Principles
@@ -57,22 +78,31 @@ that preserve privacy and data sovereignty.
 ### Code Organization
 
 - **Platform Services**: Abstract platform-specific code behind interfaces
+
 - **Service Factory**: Use `PlatformServiceFactory` for platform selection
+
 - **Type Safety**: Strict TypeScript, no `any` types, use type guards
+
 - **Modern Architecture**: Use current platform service patterns
 
 ### Architecture Patterns
 
 - **Dependency Injection**: Services injected via mixins and factory pattern
+
 - **Interface Segregation**: Small, focused interfaces over large ones
+
 - **Composition over Inheritance**: Prefer mixins and composition
+
 - **Single Responsibility**: Each component/service has one clear purpose
 
 ### Testing Strategy
 
 - **E2E**: Playwright for critical user journeys
+
 - **Unit**: Jest with F.I.R.S.T. principles
+
 - **Platform Coverage**: Web + Capacitor (Pixel 5) in CI
+
 - **Quality Assurance**: Comprehensive testing and validation
 
 ## Current Development Focus
@@ -80,102 +110,64 @@ that preserve privacy and data sovereignty.
 ### Active Development
 
 - **Feature Development**: Build new functionality using modern platform
+
   services
+
 - **Performance Optimization**: Improve app performance and user experience
+
 - **Platform Enhancement**: Leverage platform-specific capabilities
+
 - **Code Quality**: Maintain high standards and best practices
 
 ### Development Metrics
 
 - **Code Quality**: High standards maintained across all platforms
+
 - **Performance**: Optimized for all target devices
+
 - **Testing**: Comprehensive coverage maintained
+
 - **User Experience**: Focus on intuitive, accessible interfaces
 
-## Platform-Specific Considerations
-
-### Web (PWA)
-
-- **QR Scanning**: WebInlineQRScanner
-- **Deep Linking**: URL parameters
-- **File System**: Limited browser APIs
-- **Build**: `npm run build:web` (development build)
-
-### Mobile (Capacitor)
-
-- **QR Scanning**: @capacitor-mlkit/barcode-scanning
-- **Deep Linking**: App URL open events
-- **File System**: Capacitor Filesystem
-- **Build**: `npm run build:capacitor`
-
-### Desktop (Electron)
-
-- **File System**: Node.js fs
-- **Build**: `npm run build:electron`
-- **Distribution**: AppImage, DEB, DMG packages
-
-## Development Workflow
-
-### Build Commands
-
-```bash
-# Web (development)
-npm run build:web
-
-# Mobile
-npm run build:capacitor
-npm run build:native
-
-# Desktop
-npm run build:electron
-npm run build:electron:appimage
-npm run build:electron:deb
-npm run build:electron:dmg
-```
-
-### Testing Commands
-
-```bash
-# Web E2E
-npm run test:web
-
-# Mobile
-npm run test:mobile
-npm run test:android
-npm run test:ios
-
-# Type checking
-npm run type-check
-npm run lint-fix
-```
-
-## Key Constraints
-
-1. **Privacy First**: User identifiers remain private except when explicitly
-   shared
-2. **Platform Compatibility**: Features must work across all target platforms
-3. **Performance**: Must remain performant on older/simpler devices
-4. **Modern Architecture**: New features should use current platform services
-5. **Offline Capability**: Key functionality should work offline when feasible
-
-## Use Cases to Support
-
-1. **Community Building**: Tools for finding others with shared interests
-2. **Project Coordination**: Easy proposal and collaboration on projects
-3. **Reputation Building**: Showcasing contributions and reliability
-4. **Governance**: Facilitating decision-making and collective governance
-
-## Resources
-
-- **Testing**: `docs/migration-testing/`
-- **Architecture**: `docs/architecture-decisions.md`
-- **Build Context**: `docs/build-modernization-context.md`
-
 ---
 
-## Status: Active application context
+**See also**:
+
+- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details
+
+- `.cursor/rules/app/timesafari_development.mdc` for
+
+  development workflow details
+
+**Status**: Active application context
+**Priority**: Critical
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Development team, Product team
 
-- **Priority**: Critical
-- **Estimated Effort**: Ongoing reference
 - **Dependencies**: Vue 3, TypeScript, SQLite, Capacitor, Electron
+
 - **Stakeholders**: Development team, Product team
+
+## Model Implementation Checklist
+
+### Before TimeSafari Development
+
+- [ ] **Application Context**: Understand TimeSafari's community-building purpose
+- [ ] **Platform Analysis**: Identify target platforms (web, mobile, desktop)
+- [ ] **Architecture Review**: Review current platform service patterns
+- [ ] **Testing Strategy**: Plan testing approach for all platforms
+
+### During TimeSafari Development
+
+- [ ] **Platform Services**: Use abstracted platform services via interfaces
+- [ ] **Type Safety**: Implement strict TypeScript with type guards
+- **Modern Architecture**: Follow current platform service patterns
+- [ ] **Performance Focus**: Ensure performance on all target devices
+
+### After TimeSafari Development
+
+- [ ] **Cross-Platform Testing**: Test functionality across all platforms
+- [ ] **Performance Validation**: Verify performance meets requirements
+- [ ] **Code Quality**: Ensure high standards maintained
+- [ ] **Documentation Update**: Update relevant documentation

.cursor/rules/app/timesafari_development.mdc

@@ -0,0 +1,174 @@
+# Time Safari Development — Workflow and Processes
+
+> **Agent role**: Reference this file for development workflow details when
+  working with TimeSafari development processes.
+
+## Development Workflow
+
+### Build Commands
+
+```bash
+
+# Web (development)
+
+npm run build:web
+
+# Mobile
+
+npm run build:capacitor
+npm run build:native
+
+# Desktop
+
+npm run build:electron
+npm run build:electron:appimage
+npm run build:electron:deb
+npm run build:electron:dmg
+
+```
+
+### Testing Commands
+
+```bash
+
+# Web E2E
+
+npm run test:web
+
+# Mobile
+
+npm run test:mobile
+npm run test:android
+npm run test:ios
+
+# Type checking
+
+npm run type-check
+npm run lint-fix
+
+```
+
+## Development Principles
+
+### Code Organization
+
+- **Platform Services**: Abstract platform-specific code behind interfaces
+
+- **Service Factory**: Use `PlatformServiceFactory` for platform selection
+
+- **Type Safety**: Strict TypeScript, no `any` types, use type guards
+
+- **Modern Architecture**: Use current platform service patterns
+
+### Architecture Patterns
+
+- **Dependency Injection**: Services injected via mixins and factory pattern
+
+- **Interface Segregation**: Small, focused interfaces over large ones
+
+- **Composition over Inheritance**: Prefer mixins and composition
+
+- **Single Responsibility**: Each component/service has one clear purpose
+
+### Testing Strategy
+
+- **E2E**: Playwright for critical user journeys
+
+- **Unit**: Jest with F.I.R.S.T. principles
+
+- **Platform Coverage**: Web + Capacitor (Pixel 5) in CI
+
+- **Quality Assurance**: Comprehensive testing and validation
+
+## Current Development Focus
+
+### Active Development
+
+- **Feature Development**: Build new functionality using modern platform
+
+  services
+
+- **Performance Optimization**: Improve app performance and user experience
+
+- **Platform Enhancement**: Leverage platform-specific capabilities
+
+- **Code Quality**: Maintain high standards and best practices
+
+### Development Metrics
+
+- **Code Quality**: High standards maintained across all platforms
+
+- **Performance**: Optimized for all target devices
+
+- **Testing**: Comprehensive coverage maintained
+
+- **User Experience**: Focus on intuitive, accessible interfaces
+
+## Development Environment
+
+### Required Tools
+
+- **Node.js**: LTS version with npm
+
+- **Git**: Version control with proper branching strategy
+
+- **IDE**: VS Code with recommended extensions
+
+- **Platform Tools**: Android Studio, Xcode (for mobile development)
+
+### Environment Setup
+
+1. **Clone Repository**: `git clone <repository-url>`
+
+2. **Install Dependencies**: `npm install`
+
+3. **Environment Variables**: Copy `.env.example` to `.env.local`
+
+4. **Platform Setup**: Follow platform-specific setup guides
+
+### Quality Assurance
+
+- **Linting**: ESLint with TypeScript rules
+
+- **Formatting**: Prettier for consistent code style
+
+- **Type Checking**: TypeScript strict mode enabled
+
+- **Testing**: Comprehensive test coverage requirements
+
+---
+
+**See also**:
+
+- `.cursor/rules/app/timesafari.mdc` for core application context
+
+- `.cursor/rules/app/timesafari_platforms.mdc` for platform-specific details
+
+**Status**: Active development workflow
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: timesafari.mdc, timesafari_platforms.mdc
+**Stakeholders**: Development team, DevOps team
+
+## Model Implementation Checklist
+
+### Before TimeSafari Development
+
+- [ ] **Environment Setup**: Verify development environment is ready
+- [ ] **Platform Tools**: Ensure platform-specific tools are available
+- [ ] **Dependencies**: Check all required dependencies are installed
+- [ ] **Environment Variables**: Configure local environment variables
+
+### During TimeSafari Development
+
+- [ ] **Platform Services**: Use modern platform service patterns
+- [ ] **Code Quality**: Follow ESLint and TypeScript strict rules
+- [ ] **Testing**: Implement comprehensive testing strategy
+- [ ] **Performance**: Optimize for all target platforms
+
+### After TimeSafari Development
+
+- [ ] **Quality Checks**: Run linting, formatting, and type checking
+- [ ] **Testing**: Execute comprehensive tests across platforms
+- [ ] **Performance Validation**: Verify performance meets requirements
+- [ ] **Documentation**: Update development documentation

.cursor/rules/app/timesafari_platforms.mdc

@@ -0,0 +1,167 @@
+# Time Safari Platforms — Platform-Specific Considerations
+
+> **Agent role**: Reference this file for platform-specific details when working
+  with TimeSafari development across different platforms.
+
+## Platform-Specific Considerations
+
+### Web (PWA)
+
+- **QR Scanning**: WebInlineQRScanner
+
+- **Deep Linking**: URL parameters
+
+- **File System**: Limited browser APIs
+
+- **Build**: `npm run build:web` (development build)
+
+### Mobile (Capacitor)
+
+- **QR Scanning**: @capacitor-mlkit/barcode-scanning
+
+- **Deep Linking**: App URL open events
+
+- **File System**: Capacitor Filesystem
+
+- **Build**: `npm run build:capacitor`
+
+### Desktop (Electron)
+
+- **File System**: Node.js fs
+
+- **Build**: `npm run build:electron`
+
+- **Distribution**: AppImage, DEB, DMG packages
+
+## Platform Compatibility Requirements
+
+### Cross-Platform Features
+
+- **Core functionality** must work identically across all platforms
+
+- **Platform-specific enhancements** should be additive, not required
+
+- **Fallback behavior** must be graceful when platform features unavailable
+
+### Platform-Specific Capabilities
+
+- **Web**: Browser APIs, PWA features, responsive design
+
+- **Mobile**: Native device features, offline capability, app store compliance
+
+- **Desktop**: File system access, system integration, native performance
+
+## Build and Distribution
+
+### Build Commands
+
+```bash
+
+# Web (development)
+
+npm run build:web
+
+# Mobile
+
+npm run build:capacitor
+npm run build:native
+
+# Desktop
+
+npm run build:electron
+npm run build:electron:appimage
+npm run build:electron:deb
+npm run build:electron:dmg
+
+```
+
+### Testing Commands
+
+```bash
+
+# Web E2E
+
+npm run test:web
+
+# Mobile
+
+npm run test:mobile
+npm run test:android
+npm run test:ios
+
+# Type checking
+
+npm run type-check
+npm run lint-fix
+
+```
+
+## Key Constraints
+
+1. **Privacy First**: User identifiers remain private except when explicitly
+
+   shared
+
+2. **Platform Compatibility**: Features must work across all target platforms
+
+3. **Performance**: Must remain performant on older/simpler devices
+
+4. **Modern Architecture**: New features should use current platform services
+
+5. **Offline Capability**: Key functionality should work offline when feasible
+
+## Use Cases to Support
+
+1. **Community Building**: Tools for finding others with shared interests
+
+2. **Project Coordination**: Easy proposal and collaboration on projects
+
+3. **Reputation Building**: Showcasing contributions and reliability
+
+4. **Governance**: Facilitating decision-making and collective governance
+
+## Resources
+
+- **Testing**: `docs/migration-testing/`
+
+- **Architecture**: `docs/architecture-decisions.md`
+
+- **Build Context**: `docs/build-modernization-context.md`
+
+---
+
+**See also**:
+
+- `.cursor/rules/app/timesafari.mdc` for core application context
+- `.cursor/rules/app/timesafari_development.mdc` for
+
+  development workflow details
+
+**Status**: Active platform guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: timesafari.mdc
+**Stakeholders**: Development team, Platform teams
+
+## Model Implementation Checklist
+
+### Before Platform Development
+
+- [ ] **Platform Analysis**: Identify all target platforms (web, mobile, desktop)
+- [ ] **Feature Requirements**: Understand feature requirements across platforms
+- [ ] **Platform Constraints**: Review platform-specific limitations and capabilities
+- [ ] **Testing Strategy**: Plan testing approach for all target platforms
+
+### During Platform Development
+
+- [ ] **Cross-Platform Implementation**: Implement features across all platforms
+- [ ] **Platform Services**: Use current platform services for new features
+- [ ] **Performance Optimization**: Ensure performance on older/simpler devices
+- [ ] **Offline Capability**: Implement offline functionality where feasible
+
+### After Platform Development
+
+- [ ] **Cross-Platform Testing**: Test functionality across all target platforms
+- [ ] **Performance Validation**: Verify performance meets requirements
+- [ ] **Documentation Update**: Update platform-specific documentation
+- [ ] **Team Communication**: Share platform implementation results with team

.cursor/rules/architecture/build_architecture_guard.mdc

@@ -1,8 +1,3 @@
----
-description: Guards against unauthorized changes to the TimeSafari building
-  architecture
-alwaysApply: false
----
 
 # Build Architecture Guard Directive
 
@@ -17,34 +12,57 @@ could break the multi-platform build pipeline, deployment processes, or
 development workflow. This directive ensures all build system modifications
 follow proper review, testing, and documentation procedures.
 
-**Note**: Recent Android build system enhancements (2025-08-22) include sophisticated asset validation, platform-specific API routing, and automatic resource regeneration. These features require enhanced testing and validation procedures.
+**Note**: Recent Android build system enhancements (2025-08-22) include
+  sophisticated asset validation, platform-specific API routing, and automatic
+  resource regeneration. These features require enhanced testing and validation
+  procedures.
 
 ## Protected Architecture Components
 
 ### Core Build Infrastructure
 
 - **Vite Configuration Files**: `vite.config.*.mts` files
+
 - **Build Scripts**: All scripts in `scripts/` directory
+
 - **Package Scripts**: `package.json` build-related scripts
+
 - **Platform Configs**: `capacitor.config.ts`, `electron/`, `android/`,
+
   `ios/`
+
 - **Docker Configuration**: `Dockerfile`, `docker-compose.yml`
+
 - **Environment Files**: `.env.*`, `.nvmrc`, `.node-version`
 
 ### Android-Specific Build Validation
 
-- **Asset Validation Scripts**: `validate_android_assets()` function and resource checking
+- **Asset Validation Scripts**:
+
+  `validate_android_assets()` function and resource checking
+
 - **Resource Generation**: `capacitor-assets` integration and verification
-- **Platform-Specific IP Handling**: Android emulator vs physical device API routing
+
+- **Platform-Specific IP Handling**:
+
+  Android emulator vs physical device API routing
+
 - **Build Mode Validation**: Development/test/production mode handling
-- **Resource Fallback Logic**: Automatic regeneration of missing Android resources
+
+- **Resource Fallback Logic**:
+
+  Automatic regeneration of missing Android resources
 
 ### Critical Build Dependencies
 
 - **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode
+
 - **Asset Management**: `capacitor-assets.config.json`, asset scripts
+
 - **Testing Infrastructure**: Playwright, Jest, mobile test scripts
+
 - **CI/CD Pipeline**: GitHub Actions, build validation scripts
+
 - **Service Worker Assembly**: `sw_scripts/`, `sw_combine.js`, WASM copy steps
 
 ## Change Authorization Requirements
@@ -52,8 +70,11 @@ follow proper review, testing, and documentation procedures.
 ### Level 1: Minor Changes (Requires Review)
 
 - Documentation updates to `BUILDING.md`
+
 - Non-breaking script improvements
+
 - Test additions or improvements
+
 - Asset configuration updates
 
 **Process**: Code review + basic testing
@@ -61,11 +82,21 @@ follow proper review, testing, and documentation procedures.
 ### Level 2: Moderate Changes (Requires Testing)
 
 - New build script additions
+
 - Environment variable changes
+
 - Dependency version updates
+
 - Platform-specific optimizations
-- **Build script argument parsing**: New flag handling (--api-ip, --auto-run, --deploy)
+
-- **Platform-specific environment overrides**: Android API server IP customization
+- **Build script argument parsing**:
+
+  New flag handling (--api-ip, --auto-run, --deploy)
+
+- **Platform-specific environment overrides**:
+
+  Android API server IP customization
+
 - **Asset regeneration logic**: Automatic fallback for missing Android resources
 
 **Process**: Code review + platform testing + documentation update
@@ -73,8 +104,11 @@ follow proper review, testing, and documentation procedures.
 ### Level 3: Major Changes (Requires ADR)
 
 - Build system architecture changes
+
 - New platform support
+
 - Breaking changes to build scripts
+
 - Major dependency migrations
 
 **Process**: ADR creation + comprehensive testing + team review
@@ -84,290 +118,69 @@ follow proper review, testing, and documentation procedures.
 ### ❌ Never Allow Without ADR
 
 - **Delete or rename** core build scripts
+
 - **Modify** `package.json` build script names
+
 - **Change** Vite configuration structure
+
 - **Remove** platform-specific build targets
+
 - **Alter** Docker build process
+
 - **Modify** CI/CD pipeline without testing
 
 ### ❌ Never Allow Without Testing
 
 - **Update** build dependencies
+
 - **Change** environment configurations
+
 - **Modify** asset generation scripts
+
 - **Alter** test infrastructure
+
 - **Update** platform SDK versions
 
-## Required Validation Checklist
-
-### Before Any Build System Change
-
-- [ ] **Impact Assessment**: Which platforms are affected?
-- [ ] **Testing Plan**: How will this be tested across platforms?
-- [ ] **Rollback Plan**: How can this be reverted if it breaks?
-- [ ] **Documentation**: Will `BUILDING.md` need updates?
-- [ ] **Dependencies**: Are all required tools available?
-
-### After Build System Change
-
-- [ ] **Web Platform**: Does `npm run build:web:dev` work?
-- [ ] **Mobile Platforms**: Do iOS/Android builds succeed?
-- [ ] **Desktop Platform**: Does Electron build and run?
-- [ ] **Tests Pass**: Do all build-related tests pass?
-- [ ] **Documentation Updated**: Is `BUILDING.md` current?
-
-## Specific Test Commands (Minimum Required)
-
-### Web Platform
-
-- **Development**: `npm run build:web:dev` - serve and load app
-- **Production**: `npm run build:web:prod` - verify SW and WASM present
-
-### Mobile Platforms
-
-- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied
-- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds
-
-### Android Platform (Enhanced)
-- **Development Mode**: `npm run build:android --dev` - verify 10.0.2.2 API routing
-- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` - verify custom IP
-- **Asset Validation**: `npm run build:android --assets` - verify resource generation
-- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment
-
-### Desktop Platform
-
-- **Electron**: `npm run build:electron:dev` and packaging for target OS
-- **Verify**: Single-instance behavior and app boot
-
-### Auto-run (if affected)
-
-- **Test Mode**: `npm run auto-run:test` and platform variants
-- **Production Mode**: `npm run auto-run:prod` and platform variants
-
-### Clean and Rebuild
-
-- Run relevant `clean:*` scripts and ensure re-build works
-
-## Emergency Procedures
-
-### Build System Broken
-
-1. **Immediate**: Revert to last known working commit
-2. **Investigation**: Create issue with full error details
-3. **Testing**: Verify all platforms work after revert
-4. **Documentation**: Update `BUILDING.md` with failure notes
-
-### Platform-Specific Failure
-
-1. **Isolate**: Identify which platform is affected
-2. **Test Others**: Verify other platforms still work
-3. **Rollback**: Revert platform-specific changes
-4. **Investigation**: Debug in isolated environment
-
-## Integration Points
-
-### With Version Control
-
-- **Branch Protection**: Require reviews for build script changes
-- **Commit Messages**: Must reference ADR for major changes
-- **Testing**: All build changes must pass CI/CD pipeline
-
-### With Documentation
-
-- **BUILDING.md**: Must be updated for any script changes
-- **README.md**: Must reflect new build requirements
-- **CHANGELOG.md**: Must document breaking build changes
-
-### With Testing
-
-- **Pre-commit**: Run basic build validation
-- **CI/CD**: Full platform build testing
-- **Manual Testing**: Human verification of critical paths
-
-## Risk Matrix & Required Validation
-
-### Environment Handling
-
-- **Trigger**: Change to `.env.*` loading / variable names
-- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs
-
-### Script Flow
-
-- **Trigger**: Reorder steps (prebuild → build → package), new flags
-- **Validation**: Dry-run + normal run, show exit codes & timing
-
-### Platform Packaging
-
-- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle
-- **Validation**: Produce installer/artifact and open it; verify single-instance,
-  icons, signing
-
-### Service Worker / WASM
-
-- **Trigger**: `sw_combine.js`, WASM copy path
-- **Validation**: Verify combined SW exists and is injected; page loads offline;
-  WASM present
-
-### Docker
-
-- **Trigger**: New base image, build args
-- **Validation**: Build image locally; run container; list produced `/dist`
-
-### Android Asset Management
-- **Trigger**: Changes to `validate_android_assets()` function or resource paths
-- **Validation**: Run `npm run build:android --assets` and verify all mipmap/drawable resources
-- **Risk**: Missing splash screens or app icons causing build failures
-
-### Android API Routing
-- **Trigger**: Changes to Android-specific API server IP logic
-- **Validation**: Test both emulator (10.0.2.2) and custom IP modes
-- **Risk**: API connectivity failures on different device types
-
-### Signing/Notarization
-
-- **Trigger**: Cert path/profiles
-- **Validation**: Show signing logs + verify on target OS
-
-## PR Template (Paste into Description)
-
-- [ ] **Level**: L1 / L2 / L3 + justification
-- [ ] **Files & platforms touched**:
-- [ ] **Risk triggers & mitigations**:
-- [ ] **Commands run (paste logs)**:
-- [ ] **Artifacts (names + sha256)**:
-- [ ] **Docs updated (sections/links)**:
-- [ ] **Rollback steps verified**:
-- [ ] **CI**: Jobs passing and artifacts uploaded
-
-## Rollback Playbook
-
-### Immediate Rollback
-
-1. `git revert` or `git reset --hard <prev>`; restore prior `scripts/` or config
-   files
-2. Rebuild affected targets; verify old behavior returns
-3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found
-
-### Rollback Verification
-
-- **Web**: `npm run build:web:dev` and `npm run build:web:prod`
-- **Mobile**: `npm run build:android:test` and `npm run build:ios:test`
-- **Desktop**: `npm run build:electron:dev` and packaging commands
-- **Clean**: Run relevant `clean:*` scripts and verify re-build works
-
-### Android-Specific Rollback Verification
-- **Asset Generation**: `npm run build:android --assets` - verify resources regenerate
-- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes
-- **Resource Validation**: Check `android/app/src/main/res/` for all required assets
-- **Build Modes**: Verify development, test, and production modes all work
-- **Resource Fallback**: Confirm missing resources trigger automatic regeneration
-
-## ADR Trigger List
-
-Raise an ADR when you propose any of:
-
-- **New build stage** or reorder of canonical stages
-- **Replacement of packager** / packaging format
-- **New environment model** or secure secret handling scheme
-- **New service worker assembly** strategy or cache policy
-- **New Docker base** or multi-stage pipeline
-- **Relocation of build outputs** or directory conventions
-- **New Android build modes** or argument parsing logic
-- **Changes to asset validation** or resource generation strategy
-- **Modifications to platform-specific API routing** (Android emulator vs physical)
-- **New Android deployment strategies** or device management
-
-**ADR must include**: motivation, alternatives, risks, validation plan, rollback,
-  doc diffs.
-
-## Competence Hooks
-
-### Why This Works
-
-- **Prevents Build Failures**: Catches issues before they reach production
-- **Maintains Consistency**: Ensures all platforms build identically
-- **Reduces Debugging Time**: Prevents build system regressions
-
-### Common Pitfalls
-
-- **Silent Failures**: Changes that work on one platform but break others
-- **Dependency Conflicts**: Updates that create version incompatibilities
-- **Documentation Drift**: Build scripts that don't match documentation
-
-### Next Skill Unlock
-
-- Learn to test build changes across all platforms simultaneously
-
-### Teach-back
-
-- "What three platforms must I test before committing a build script change?"
-
-## Collaboration Hooks
-
-### Team Review Requirements
-
-- **Platform Owners**: iOS, Android, Electron, Web specialists
-- **DevOps**: CI/CD pipeline maintainers
-- **QA**: Testing infrastructure owners
-
-### Discussion Prompts
-
-- "Which platforms will be affected by this build change?"
-- "How can we test this change without breaking existing builds?"
-- "What's our rollback plan if this change fails?"
-
-## Self-Check (Before Allowing Changes)
-
-- [ ] **Authorization Level**: Is this change appropriate for the level?
-- [ ] **Testing Plan**: Is there a comprehensive testing strategy?
-- [ ] **Documentation**: Will BUILDING.md be updated?
-- [ ] **Rollback**: Is there a safe rollback mechanism?
-- [ ] **Team Review**: Have appropriate stakeholders been consulted?
-- [ ] **CI/CD**: Will this pass the build pipeline?
-
-## Continuous Improvement & Feedback
-
-### Feedback Collection
-
-The Build Architecture Guard system includes feedback mechanisms to continuously improve its effectiveness:
-
-- **User Feedback**: Script includes feedback prompts for guard improvements
-- **Pattern Analysis**: Monitor which file patterns trigger false positives/negatives
-- **Documentation Gaps**: Track which changes lack proper documentation
-- **Testing Effectiveness**: Measure how often guard catches actual issues
-
-### Feedback Integration Process
-
-1. **Collect Feedback**: Monitor guard execution logs and user reports
-2. **Analyze Patterns**: Identify common false positives or missed patterns
-3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback
-4. **Enhance Script**: Update `build-arch-guard.sh` with new validations
-5. **Test Changes**: Verify guard improvements don't introduce new issues
-6. **Document Updates**: Update guard documentation with new patterns
-
-### Feedback Categories
-
-- **False Positives**: Files flagged as sensitive that shouldn't be
-- **False Negatives**: Sensitive files that weren't caught
-- **Missing Patterns**: New file types that should be protected
-- **Overly Strict**: Patterns that are too restrictive
-- **Documentation Gaps**: Missing guidance for specific change types
-- **Testing Improvements**: Better validation procedures
-
-### Feedback Reporting
-
-When reporting guard issues, include:
-- **File patterns** that triggered false positives/negatives
-- **Build system changes** that weren't properly caught
-- **Documentation gaps** in current guard rules
-- **Testing procedures** that could be improved
-- **User experience** issues with guard enforcement
-
 ---
 
-**Status**: Active build system protection
+**See also**:
+
+- `.cursor/rules/architecture/build_validation.mdc` for
+
+  detailed validation procedures
+
+- `.cursor/rules/architecture/build_testing.mdc` for testing requirements
+
+**Status**: Active build protection guidelines
 **Priority**: Critical
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Development team, DevOps team, Build team
+
 **Estimated Effort**: Ongoing vigilance
 **Dependencies**: All build system components
 **Stakeholders**: Development team, DevOps, Platform owners
 **Next Review**: 2025-09-22
+
+## Model Implementation Checklist
+
+### Before Build Changes
+
+- [ ] **Change Level**: Determine if change is L1, L2, or L3
+- [ ] **Impact Assessment**: Assess impact on build system architecture
+- [ ] **ADR Requirement**: Check if ADR is required for major changes
+- [ ] **Testing Planning**: Plan appropriate testing for change level
+
+### During Build Changes
+
+- [ ] **Guard Compliance**: Ensure changes comply with build architecture guard
+- [ ] **Documentation**: Document changes according to level requirements
+- [ ] **Testing**: Execute appropriate testing for change level
+- [ ] **Review Process**: Follow required review process for change level
+
+### After Build Changes
+
+- [ ] **Validation**: Verify build system still functions correctly
+- [ ] **Documentation Update**: Update relevant documentation
+- [ ] **Team Communication**: Communicate changes to affected teams
+- [ ] **Monitoring**: Monitor for any build system issues

.cursor/rules/architecture/build_testing.mdc

@@ -0,0 +1,248 @@
+# Build Testing — Requirements and Emergency Procedures
+
+> **Agent role**: Reference this file for testing requirements and
+  emergency procedures when working with build architecture changes.
+
+## Emergency Procedures
+
+### Build System Broken
+
+1. **Immediate**: Revert to last known working commit
+
+2. **Investigation**: Create issue with full error details
+
+3. **Testing**: Verify all platforms work after revert
+
+4. **Documentation**: Update `BUILDING.md` with failure notes
+
+### Platform-Specific Failure
+
+1. **Isolate**: Identify which platform is affected
+
+2. **Test Others**: Verify other platforms still work
+
+3. **Rollback**: Revert platform-specific changes
+
+4. **Investigation**: Debug in isolated environment
+
+## Rollback Playbook
+
+### Immediate Rollback
+
+1. `git revert` or `git reset --hard <prev>`; restore prior `scripts/` or config
+
+   files
+
+2. Rebuild affected targets; verify old behavior returns
+
+3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found
+
+### Rollback Verification
+
+- **Web**: `npm run build:web:dev` and `npm run build:web:prod`
+
+- **Mobile**: `npm run build:android:test` and `npm run build:ios:test`
+
+- **Desktop**: `npm run build:electron:dev` and packaging commands
+
+- **Clean**: Run relevant `clean:*` scripts and verify re-build works
+
+### Android-Specific Rollback Verification
+
+- **Asset Generation**: `npm run build:android --assets` -
+
+  verify resources regenerate
+
+- **API Routing**: Test both `--dev` and `--dev --api-ip <custom>` modes
+
+- **Resource Validation**:
+
+  Check `android/app/src/main/res/` for all required assets
+
+- **Build Modes**: Verify development, test, and production modes all work
+
+- **Resource Fallback**:
+
+  Confirm missing resources trigger automatic regeneration
+
+## Integration Points
+
+### With Version Control
+
+- **Branch Protection**: Require reviews for build script changes
+
+- **Commit Messages**: Must reference ADR for major changes
+
+- **Testing**: All build changes must pass CI/CD pipeline
+
+### With Documentation
+
+- **BUILDING.md**: Must be updated for any script changes
+
+- **README.md**: Must reflect new build requirements
+
+- **CHANGELOG.md**: Must document breaking build changes
+
+### With Testing
+
+- **Pre-commit**: Run basic build validation
+
+- **CI/CD**: Full platform build testing
+
+- **Manual Testing**: Human verification of critical paths
+
+## Competence Hooks
+
+### Why This Works
+
+- **Prevents Build Failures**: Catches issues before they reach production
+
+- **Maintains Consistency**: Ensures all platforms build identically
+
+- **Reduces Debugging Time**: Prevents build system regressions
+
+### Common Pitfalls
+
+- **Silent Failures**: Changes that work on one platform but break others
+
+- **Dependency Conflicts**: Updates that create version incompatibilities
+
+- **Documentation Drift**: Build scripts that don't match documentation
+
+### Next Skill Unlock
+
+- Learn to test build changes across all platforms simultaneously
+
+### Teach-back
+
+- "What three platforms must I test before committing a build script change?"
+
+## Collaboration Hooks
+
+### Team Review Requirements
+
+- **Platform Owners**: iOS, Android, Electron, Web specialists
+
+- **DevOps**: CI/CD pipeline maintainers
+
+- **QA**: Testing infrastructure owners
+
+### Discussion Prompts
+
+- "Which platforms will be affected by this build change?"
+
+- "How can we test this change without breaking existing builds?"
+
+- "What's our rollback plan if this change fails?"
+
+## Self-Check (Before Allowing Changes)
+
+- [ ] **Authorization Level**: Is this change appropriate for the level?
+
+- [ ] **Testing Plan**: Is there a comprehensive testing strategy?
+
+- [ ] **Documentation**: Will BUILDING.md be updated?
+
+- [ ] **Rollback**: Is there a safe rollback mechanism?
+
+- [ ] **Team Review**: Have appropriate stakeholders been consulted?
+
+- [ ] **CI/CD**: Will this pass the build pipeline?
+
+## Continuous Improvement & Feedback
+
+### Feedback Collection
+
+The Build Architecture Guard system includes feedback mechanisms to continuously
+  improve its effectiveness:
+
+- **User Feedback**: Script includes feedback prompts for guard improvements
+
+- **Pattern Analysis**:
+
+  Monitor which file patterns trigger false positives/negatives
+
+- **Documentation Gaps**: Track which changes lack proper documentation
+
+- **Testing Effectiveness**: Measure how often guard catches actual issues
+
+### Feedback Integration Process
+
+1. **Collect Feedback**: Monitor guard execution logs and user reports
+
+2. **Analyze Patterns**: Identify common false positives or missed patterns
+
+3. **Update Rules**: Modify `build_architecture_guard.mdc` based on feedback
+
+4. **Enhance Script**: Update `build-arch-guard.sh` with new validations
+
+5. **Test Changes**: Verify guard improvements don't introduce new issues
+
+6. **Document Updates**: Update guard documentation with new patterns
+
+### Feedback Categories
+
+- **False Positives**: Files flagged as sensitive that shouldn't be
+
+- **False Negatives**: Sensitive files that weren't caught
+
+- **Missing Patterns**: New file types that should be protected
+
+- **Overly Strict**: Patterns that are too restrictive
+
+- **Documentation Gaps**: Missing guidance for specific change types
+
+- **Testing Improvements**: Better validation procedures
+
+### Feedback Reporting
+
+When reporting guard issues, include:
+
+- **File patterns** that triggered false positives/negatives
+
+- **Build system changes** that weren't properly caught
+
+- **Documentation gaps** in current guard rules
+
+- **Testing procedures** that could be improved
+
+- **User experience** issues with guard enforcement
+
+---
+
+**See also**:
+
+- `.cursor/rules/architecture/build_architecture_guard.mdc` for
+
+  core protection guidelines
+
+- `.cursor/rules/architecture/build_validation.mdc` for validation procedures
+
+**Status**: Active testing requirements
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: build_architecture_guard.mdc, build_validation.mdc
+**Stakeholders**: Development team, DevOps team, Build team
+
+## Model Implementation Checklist
+
+### Before Build Testing
+
+- [ ] **Test Planning**: Plan comprehensive testing strategy for build changes
+- [ ] **Platform Coverage**: Identify all platforms that need testing
+- [ ] **Risk Assessment**: Assess testing risks and mitigation strategies
+- [ ] **Resource Planning**: Plan testing resources and time requirements
+
+### During Build Testing
+
+- [ ] **Test Execution**: Execute planned tests across all platforms
+- [ ] **Issue Tracking**: Track and document any issues found
+- [ ] **Feedback Collection**: Collect feedback on testing effectiveness
+- [ ] **Documentation**: Document testing procedures and results
+
+### After Build Testing
+
+- [ ] **Result Analysis**: Analyze testing results and identify patterns
+- [ ] **Feedback Integration**: Integrate feedback into testing procedures
+- [ ] **Process Improvement**: Update testing procedures based on feedback
+- [ ] **Team Communication**: Share testing results and improvements with team

.cursor/rules/architecture/build_validation.mdc

@@ -0,0 +1,224 @@
+# Build Validation — Procedures and Requirements
+
+> **Agent role**: Reference this file for
+  detailed validation procedures when working with build architecture changes.
+
+## Required Validation Checklist
+
+### Before Any Build System Change
+
+- [ ] **Impact Assessment**: Which platforms are affected?
+
+- [ ] **Testing Plan**: How will this be tested across platforms?
+
+- [ ] **Rollback Plan**: How can this be reverted if it breaks?
+
+- [ ] **Documentation**: Will `BUILDING.md` need updates?
+
+- [ ] **Dependencies**: Are all required tools available?
+
+### After Build System Change
+
+- [ ] **Web Platform**: Does `npm run build:web:dev` work?
+
+- [ ] **Mobile Platforms**: Do iOS/Android builds succeed?
+
+- [ ] **Desktop Platform**: Does Electron build and run?
+
+- [ ] **Tests Pass**: Do all build-related tests pass?
+
+- [ ] **Documentation Updated**: Is `BUILDING.md` current?
+
+## Specific Test Commands (Minimum Required)
+
+### Web Platform
+
+- **Development**: `npm run build:web:dev` - serve and load app
+
+- **Production**: `npm run build:web:prod` - verify SW and WASM present
+
+### Mobile Platforms
+
+- **Android**: `npm run build:android:test` or `:prod` - confirm assets copied
+
+- **iOS**: `npm run build:ios:test` or `:prod` - verify build succeeds
+
+### Android Platform (Enhanced)
+
+- **Development Mode**: `npm run build:android --dev` -
+
+  verify 10.0.2.2 API routing
+
+- **Custom IP Mode**: `npm run build:android --dev --api-ip 192.168.1.100` -
+
+  verify custom IP
+
+- **Asset Validation**: `npm run build:android --assets` -
+
+  verify resource generation
+
+- **Deploy Mode**: `npm run build:android --deploy` - verify device deployment
+
+### Desktop Platform
+
+- **Electron**: `npm run build:electron:dev` and packaging for target OS
+
+- **Verify**: Single-instance behavior and app boot
+
+### Auto-run (if affected)
+
+- **Test Mode**: `npm run auto-run:test` and platform variants
+
+- **Production Mode**: `npm run auto-run:prod` and platform variants
+
+### Clean and Rebuild
+
+- Run relevant `clean:*` scripts and ensure re-build works
+
+## Risk Matrix & Required Validation
+
+### Environment Handling
+
+- **Trigger**: Change to `.env.*` loading / variable names
+
+- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs
+
+### Script Flow
+
+- **Trigger**: Reorder steps (prebuild → build → package), new flags
+
+- **Validation**: Dry-run + normal run, show exit codes & timing
+
+### Platform Packaging
+
+- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle
+
+- **Validation**: Produce installer/artifact and open it;
+
+  verify single-instance,
+  icons, signing
+
+### Service Worker / WASM
+
+- **Trigger**: `sw_combine.js`, WASM copy path
+
+- **Validation**: Verify combined SW exists and is injected; page loads offline;
+
+  WASM present
+
+### Docker
+
+- **Trigger**: New base image, build args
+
+- **Validation**: Build image locally; run container; list produced `/dist`
+
+### Android Asset Management
+
+- **Trigger**: Changes to `validate_android_assets()` function or resource paths
+
+- **Validation**:
+
+  Run `npm run build:android --assets` and verify all mipmap/drawable resources
+
+- **Risk**: Missing splash screens or app icons causing build failures
+
+### Android API Routing
+
+- **Trigger**: Changes to Android-specific API server IP logic
+
+- **Validation**: Test both emulator (10.0.2.2) and custom IP modes
+
+- **Risk**: API connectivity failures on different device types
+
+### Signing/Notarization
+
+- **Trigger**: Cert path/profiles
+
+- **Validation**: Show signing logs + verify on target OS
+
+## PR Template (Paste into Description)
+
+- [ ] **Level**: L1 / L2 / L3 + justification
+
+- [ ] **Files & platforms touched**:
+
+- [ ] **Risk triggers & mitigations**:
+
+- [ ] **Commands run (paste logs)**:
+
+- [ ] **Artifacts (names + sha256)**:
+
+- [ ] **Docs updated (sections/links)**:
+
+- [ ] **Rollback steps verified**:
+
+- [ ] **CI**: Jobs passing and artifacts uploaded
+
+## ADR Trigger List
+
+Raise an ADR when you propose any of:
+
+- **New build stage** or reorder of canonical stages
+
+- **Replacement of packager** / packaging format
+
+- **New environment model** or secure secret handling scheme
+
+- **New service worker assembly** strategy or cache policy
+
+- **New Docker base** or multi-stage pipeline
+
+- **Relocation of build outputs** or directory conventions
+
+- **New Android build modes** or argument parsing logic
+
+- **Changes to asset validation** or resource generation strategy
+
+- **Modifications to platform-specific API routing** (
+
+  Android emulator vs physical)
+
+- **New Android deployment strategies** or device management
+
+**ADR must include**:
+  motivation, alternatives, risks, validation plan, rollback,
+  doc diffs.
+
+---
+
+**See also**:
+
+- `.cursor/rules/architecture/build_architecture_guard.mdc` for
+
+  core protection guidelines
+
+- `.cursor/rules/architecture/build_testing.mdc` for testing requirements
+
+**Status**: Active validation procedures
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: build_architecture_guard.mdc
+**Stakeholders**: Development team, DevOps team, Build team
+
+## Model Implementation Checklist
+
+### Before Build Changes
+
+- [ ] **Level Assessment**: Determine build validation level (L1/L2/L3)
+- [ ] **Platform Analysis**: Identify all platforms affected by changes
+- [ ] **Risk Assessment**: Identify risk triggers and mitigation strategies
+- [ ] **Rollback Planning**: Plan rollback steps for build failures
+
+### During Build Implementation
+
+- [ ] **Validation Commands**: Run appropriate validation commands for level
+- [ ] **Platform Testing**: Test changes across all affected platforms
+- [ ] **Risk Mitigation**: Implement identified risk mitigation strategies
+- [ ] **Documentation**: Document all commands run and their outputs
+
+### After Build Implementation
+
+- [ ] **Artifact Validation**: Verify build artifacts are correct and accessible
+- [ ] **CI Verification**: Ensure CI jobs pass and artifacts are uploaded
+- [ ] **Documentation Update**: Update relevant documentation sections
+- [ ] **Team Communication**: Share build validation results with team

.cursor/rules/core/base_context.mdc

@@ -1,7 +1,8 @@
 ---
-alwaysApply: true
+alwaysApply: false
 ---
 ```json
+
 {
   "coaching_level": "standard",
   "socratic_max_questions": 7,
@@ -9,6 +10,7 @@ alwaysApply: true
   "timebox_minutes": null,
   "format_enforcement": "strict"
 }
+
 ```
 
 # Base Context — Human Competence First
@@ -30,13 +32,21 @@ machine-driven steps.
 ## Principles
 
 1. Competence over convenience: finish the task *and* leave the human more
+
    capable next time.
+
 2. Mentorship, not lectures: be concise, concrete, and immediately applicable.
+
 3. Transparency: show assumptions, limits, and uncertainty; cite when
+
    non-obvious.
+
 4. Optional scaffolding: include small, skimmable learning hooks that do not
+
    bloat output.
+
 5. Time respect: default to **lean output**; offer opt-in depth via toggles.
+
 6. Psychological safety: encourage, never condescend; no medical/clinical
    advice. No censorship!
 7. Reusability: structure outputs so they can be saved, searched, reused, and
@@ -72,12 +82,19 @@ essential parts of the task within that constraint.
 Behavior when set:
 
 1. **Prioritize Core Output** — Deliver the minimum viable solution or
+
    result first.
+
 2. **Limit Commentary** — Competence Hooks and Collaboration Hooks must be
+
    shorter than normal.
+
 3. **Signal Skipped Depth** — Omitted details should be listed under
+
    *Deferred for depth*.
+
 4. **Order by Value** — Start with blocking or high-value items, then
+
    proceed to nice-to-haves if budget allows.
 
 If `null`, there is no timebox — the model can produce full-depth
@@ -91,11 +108,17 @@ acceptable).
 ## Modes (select or combine)
 
 - **Doer**: produce the artifact fast, minimal commentary.
+
 - **Mentor**: add short "why/how" notes + next-step pointers.
+
 - **Socratic**: ask up to N targeted questions when requirements are
+
   ambiguous.
+
 - **Pair-Programmer/Pair-Writer**: explain tradeoffs as you implement.
+
 - **Facilitator**: structure output to be reviewable, commentable, and
+
   ready for group discussion.
 
 Default: Doer + short Mentor notes.
@@ -103,42 +126,85 @@ Default: Doer + short Mentor notes.
 ## Competence & Collaboration Levers (keep lightweight)
 
 - "Why this works" (≤3 bullets)
+
 - "Common pitfalls" (≤3 bullets)
+
 - "Next skill unlock" (1 tiny action or reading)
+
 - "Teach-back" (1 sentence prompt the human can answer to self-check)
+
 - "Discussion prompts" (≤2 short questions for peers/stakeholders)
 
 ## Output Contract (apply to every deliverable)
 
 - Clear **Objective** (1 line)
+
 - **Result** (artifact/code/answer)
+
 - **Use/Run** (how to apply/test)
+
 - **Competence Hooks** (the 4 learning levers above, kept terse)
+
 - **Collaboration Hooks** (discussion prompts or group review steps)
+
 - **Assumptions & Limits**
+
 - **References** (if used; links or titles)
 
 ## Do-Not
 
 - No filler, hedging, or moralizing.
+
 - No medical/mental-health advice; keep "healthy habits" to general work
+
   practices.
+
 - No invented facts; mark uncertainty plainly.
+
 - No censorship.
+
 - Avoid outputs that bypass human review when such review is valuable.
 
 ## Related Rulesets
 
 - **software_development.mdc**: For software-specific development practices
+
 - **research_diagnostic.mdc**: For investigation and research workflows
 
+## Model Implementation Checklist
+
+### Before Responding
+
+- [ ] **Toggle Review**: Check coaching_level, socratic_max_questions, verbosity,
+  timebox_minutes
+- [ ] **Mode Selection**: Choose appropriate mode(s) for the task
+- [ ] **Scope Understanding**: Clarify requirements and constraints
+- [ ] **Context Analysis**: Review relevant rulesets and dependencies
+
+### During Response Creation
+
+- [ ] **Output Contract**: Include all required sections (Objective, Result,
+  Use/Run, etc.)
+- [ ] **Competence Hooks**: Add at least one learning lever (≤120 words total)
+- [ ] **Collaboration Hooks**: Include discussion prompts or review steps
+- [ ] **Toggle Compliance**: Respect verbosity, timebox, and format settings
+
+### After Response Creation
+
+- [ ] **Self-Check**: Verify all checklist items are completed
+- [ ] **Format Validation**: Ensure output follows required structure
+- [ ] **Content Review**: Confirm no disallowed content included
+- [ ] **Quality Assessment**: Verify response meets human competence goals
+
 ## Self-Check (model, before responding)
 
 - [ ] Task done *and* at least one competence lever included (≤120 words
-  total).
+  total)
-- [ ] At least one collaboration/discussion hook present.
+- [ ] At least one collaboration/discussion hook present
-- [ ] Output follows the **Output Contract** sections.
+- [ ] Output follows the **Output Contract** sections
-- [ ] Toggles respected; verbosity remains concise.
+- [ ] Toggles respected; verbosity remains concise
+- [ ] Uncertainties/assumptions surfaced
+- [ ] No disallowed content
 - [ ] Uncertainties/assumptions surfaced.
 - [ ] No disallowed content.
 
@@ -149,6 +215,3 @@ Default: Doer + short Mentor notes.
 **Estimated Effort**: Ongoing reference
 **Dependencies**: None (base ruleset)
 **Stakeholders**: All AI interactions
-
-- [ ] Uncertainties/assumptions surfaced.
-- [ ] No disallowed content.

.cursor/rules/core/harbor_pilot_universal.mdc

@@ -0,0 +1,202 @@
+```json
+
+{
+  "coaching_level": "standard",
+  "socratic_max_questions": 2,
+  "verbosity": "concise",
+  "timebox_minutes": 10,
+  "format_enforcement": "strict"
+}
+
+```
+
+# Harbor Pilot Universal — Technical Guide Standards
+
+> **Agent role**: When creating technical guides, reference documents, or
+> implementation plans, apply these universal directives to ensure consistent
+> quality and structure.
+
+## Purpose
+
+- **Purpose fit**: Prioritizes human competence and collaboration while
+  delivering reproducible artifacts.
+
+- **Output Contract**: This directive **adds universal constraints** for any
+  technical topic while **inheriting** the Base Context contract sections.
+
+- **Toggles honored**: Uses the same toggle semantics; defaults above can be
+  overridden by the caller.
+
+## Core Directive
+
+Produce a **developer-grade, reproducible guide** for any technical topic
+that onboards a competent practitioner **without meta narration** and **with
+evidence-backed steps**.
+
+## Required Elements
+
+### 1. Time & Date Standards
+
+- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid
+  "today/yesterday".
+
+- Include at least **one diagram** (Mermaid preferred). Choose the most
+  fitting type:
+
+  - `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`,
+    `gantt` (timelines), or `classDiagram` (schemas).
+
+### 2. Evidence Requirements
+
+- **Reproducible Steps**: Every claim must have copy-paste commands
+
+- **Verifiable Outputs**: Include expected results, status codes, or
+  error messages
+
+- **Cite evidence** for *Works/Doesn't* items (timestamps, filenames,
+  line numbers, IDs/status codes, or logs).
+
+## Required Sections
+
+Follow this exact order **after** the Base Contract's **Objective → Result
+→ Use/Run** headers:
+
+1. **Artifacts & Links** - Repos/PRs, design docs, datasets/HARs/pcaps,
+   scripts/tools, dashboards.
+
+2. **Environment & Preconditions** - OS/runtime, versions/build IDs,
+   services/endpoints/URLs, credentials/auth mode.
+
+3. **Architecture / Process Overview** - Short prose + **one diagram**
+   selected from the list above.
+
+4. **Interfaces & Contracts** - Choose one: API-based (endpoint table),
+   Data/Files (I/O contract), or Systems/Hardware (interfaces).
+
+5. **Repro: End-to-End Procedure** - Minimal copy-paste steps with
+   code/commands and **expected outputs**.
+6. **What Works (with Evidence)** - Each item: **Time (UTC)** •
+   **Artifact/Req IDs** • **Status/Result** • **Where to verify**.
+7. **What Doesn't (Evidence & Hypotheses)** - Each failure: locus,
+   evidence snippet; short hypothesis and **next probe**.
+8. **Risks, Limits, Assumptions** - SLOs/limits, rate/size caps,
+   security boundaries, retries/backoff/idempotency patterns.
+9. **Next Steps (Owner • Exit Criteria • Target Date)** - Actionable,
+   assigned, and time-bound.
+
+## Quality Standards
+
+### Do
+
+- **Do** quantify progress only against a defined scope with acceptance
+  criteria.
+
+- **Do** include minimal sample payloads/headers or I/O schemas; redact
+  sensitive values.
+
+- **Do** keep commentary lean; if timeboxed, move depth to **Deferred
+  for depth**.
+
+- **Do** use specific, actionable language that guides implementation.
+
+### Don't
+
+- **Don't** use marketing language or meta narration ("Perfect!",
+  "tool called", "new chat").
+
+- **Don't** include IDE-specific chatter or internal rules unrelated to
+  the task.
+
+- **Don't** assume reader knowledge; provide context for all technical
+  decisions.
+
+## Model Implementation Checklist
+
+### Before Creating Technical Guides
+
+- [ ] **Scope Definition**: Clearly define problem, audience, and scope
+- [ ] **Evidence Collection**: Gather specific timestamps, file references, and logs
+- [ ] **Diagram Planning**: Plan appropriate diagram type for the technical process
+- [ ] **Template Selection**: Choose relevant sections from required sections list
+
+### During Guide Creation
+
+- [ ] **Evidence Integration**: Include UTC timestamps and verifiable evidence
+- [ ] **Diagram Creation**: Create Mermaid diagram that illustrates the process
+- [ ] **Repro Steps**: Write copy-paste ready commands with expected outputs
+- [ ] **Section Completion**: Fill in all required sections completely
+
+### After Guide Creation
+
+- [ ] **Validation**: Run through the validation checklist below
+- [ ] **Evidence Review**: Verify all claims have supporting evidence
+- [ ] **Repro Testing**: Test reproduction steps to ensure they work
+- [ ] **Peer Review**: Share with technical leads for feedback
+
+## Validation Checklist
+
+Before publishing, verify:
+
+- [ ] **Diagram included** and properly formatted (Mermaid syntax valid)
+- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for
+  each endpoint
+- [ ] **Environment section** includes all required dependencies and
+  versions
+- [ ] Every Works/Doesn't item has **UTC timestamp**, **status/result**,
+  and **verifiable evidence**
+- [ ] **Repro steps** are copy-paste ready with expected outputs
+- [ ] Base **Output Contract** sections satisfied
+  (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References)
+
+## Integration Points
+
+### Base Context Integration
+
+- Apply historical comment management rules (see
+
+  `.cursor/rules/development/historical_comment_management.mdc`)
+
+- Apply realistic time estimation rules (see
+
+  `.cursor/rules/development/realistic_time_estimation.mdc`)
+
+### Competence Hooks
+
+- **Why this works**: Structured approach ensures completeness and
+  reproducibility
+
+- **Common pitfalls**: Skipping evidence requirements, vague language
+
+- **Next skill unlock**: Practice creating Mermaid diagrams for different
+  use cases
+
+- **Teach-back**: Explain how you would validate this guide's
+  reproducibility
+
+### Collaboration Hooks
+
+- **Reviewers**: Technical leads, subject matter experts
+
+- **Stakeholders**: Development teams, DevOps, QA teams
+
+---
+
+**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human
+Competence First*
+
+**Priority**: Critical
+**Estimated Effort**: Ongoing reference
+**Dependencies**: base_context.mdc
+**Stakeholders**: All AI interactions, Development teams
+
+## Example Diagram Template
+
+```mermaid
+
+<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt |
+classDiagram>
+
+```
+
+**Note**: Replace the placeholder with an actual diagram that illustrates
+the technical process, architecture, or workflow being documented.

.cursor/rules/core/less_complex.mdc

@@ -0,0 +1,99 @@
+
+alwaysApply: false
+
+---
+
+# Minimalist Solution Principle (Cursor MDC)
+
+role: Engineering assistant optimizing for least-complex changes
+focus: Deliver the smallest viable diff that fully resolves the current
+bug/feature. Defer generalization unless justified with evidence.
+language: Match repository languages and conventions
+
+## Rules
+
+1. **Default to the least complex solution.** Fix the problem directly
+   where it occurs; avoid new layers, indirection, or patterns unless
+   strictly necessary.
+2. **Keep scope tight.** Implement only what is needed to satisfy the
+   acceptance criteria and tests for *this* issue.
+3. **Avoid speculative abstractions.** Use the **Rule of Three**:
+   don't extract helpers/patterns until the third concrete usage proves
+   the shape.
+4. **No drive-by refactors.** Do not rename, reorder, or reformat
+   unrelated code in the same change set.
+5. **Minimize surface area.** Prefer local changes over cross-cutting
+   rewires; avoid new public APIs unless essential.
+6. **Be dependency-frugal.** Do not add packages or services for
+   single, simple needs unless there's a compelling, documented reason.
+7. **Targeted tests only.** Add the smallest set of tests that prove
+   the fix and guard against regression; don't rewrite suites.
+8. **Document the "why enough."** Include a one-paragraph note
+   explaining why this minimal solution is sufficient *now*.
+
+## Future-Proofing Requires Evidence + Discussion
+
+Any added complexity "for the future" **must** include:
+
+- A referenced discussion/ADR (or issue link) summarizing the decision.
+- **Substantial evidence**, e.g.:
+  - Recurring incidents or tickets that this prevents (list IDs).
+  - Benchmarks or profiling showing a real bottleneck.
+  - Concrete upcoming requirements with dates/owners, not hypotheticals.
+  - Risk assessment comparing maintenance cost vs. expected benefit.
+- A clear trade-off table showing why minimal won't suffice.
+
+If this evidence is not available, **ship the minimal fix** and open a
+follow-up discussion item.
+
+## PR / Change Checklist (enforced by reviewer + model)
+
+- [ ] Smallest diff that fully fixes the issue (attach `git diff --stat`
+  if useful).
+- [ ] No unrelated refactors or formatting.
+- [ ] No new dependencies, or justification + ADR link provided.
+- [ ] Abstractions only if ≥3 call sites or strong evidence says
+  otherwise (cite).
+- [ ] Targeted tests proving the fix/regression guard.
+- [ ] Short "Why this is enough now" note in the PR description.
+- [ ] Optional: "Future Work (non-blocking)" section listing deferred
+  ideas.
+
+## Assistant Output Contract
+
+When proposing a change, provide:
+
+1. **Minimal Plan**: 3–6 bullet steps scoped to the immediate fix.
+2. **Patch Sketch**: Focused diffs/snippets touching only necessary
+   files.
+3. **Risk & Rollback**: One paragraph each on risk, quick rollback,
+   and test points.
+4. **(If proposing complexity)**: Link/inline ADR summary + evidence +
+   trade-offs; otherwise default to minimal.
+
+  One paragraph each on risk, quick rollback, and test points.
+5. **(If proposing complexity)**: Link/inline ADR summary + evidence +
+   trade-offs; otherwise default to minimal.
+
+## Model Implementation Checklist
+
+### Before Proposing Changes
+
+- [ ] **Problem Analysis**: Clearly understand the specific issue scope
+- [ ] **Evidence Review**: Gather evidence that justifies the change
+- [ ] **Complexity Assessment**: Evaluate if change requires added complexity
+- [ ] **Alternative Research**: Consider simpler solutions first
+
+### During Change Design
+
+- [ ] **Minimal Scope**: Design solution that addresses only the current issue
+- [ ] **Evidence Integration**: Include specific evidence for any complexity
+- [ ] **Dependency Review**: Minimize new dependencies and packages
+- [ ] **Testing Strategy**: Plan minimal tests that prove the fix
+
+### After Change Design
+
+- [ ] **Self-Review**: Verify solution follows minimalist principles
+- [ ] **Evidence Validation**: Confirm all claims have supporting evidence
+- [ ] **Complexity Justification**: Document why minimal approach suffices
+- [ ] **Future Work Planning**: Identify deferred improvements for later

.cursor/rules/database/absurd-sql.mdc

@@ -1,8 +1,10 @@
 ---
-globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, **/src/registerSQLWorker.js, **/
+globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts,
+  **/src/registerSQLWorker.js, **/
 services/AbsurdSqlDatabaseService.ts
 alwaysApply: false
 ---
+
 # Absurd SQL - Cursor Development Guide
 
 **Author**: Matthew Raymer
@@ -19,12 +21,14 @@ in Cursor.
 ## Project Structure
 
 ```
+
 absurd-sql/
 ├── src/               # Source code
 ├── dist/             # Built files
 ├── package.json      # Dependencies and scripts
 ├── rollup.config.js  # Build configuration
 └── jest.config.js    # Test configuration
+
 ```
 
 ## Development Rules
@@ -32,13 +36,17 @@ absurd-sql/
 ### 1. Worker Thread Requirements
 
 - All SQL operations MUST be performed in a worker thread
+
 - Main thread should only handle worker initialization and communication
+
 - Never block the main thread with database operations
 
 ### 2. Code Organization
 
 - Keep worker code in separate files (e.g., `*.worker.js`)
+
 - Use ES modules for imports/exports
+
 - Follow the project's existing module structure
 
 ### 3. Required Headers
@@ -46,14 +54,18 @@ absurd-sql/
 When developing locally or deploying, ensure these headers are set:
 
 ```
+
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
+
 ```
 
 ### 4. Browser Compatibility
 
 - Primary target: Modern browsers with SharedArrayBuffer support
+
 - Fallback mode: Safari (with limitations)
+
 - Always test in both modes
 
 ### 5. Database Configuration
@@ -61,8 +73,10 @@ Cross-Origin-Embedder-Policy: require-corp
 Recommended database settings:
 
 ```sql
+
 PRAGMA journal_mode=MEMORY;
 PRAGMA page_size=8192;  -- Optional, but recommended
+
 ```
 
 ### 6. Development Workflow
@@ -70,54 +84,77 @@ PRAGMA page_size=8192;  -- Optional, but recommended
 1. Install dependencies:
 
    ```bash
+
    yarn add @jlongster/sql.js absurd-sql
+
    ```
 
 2. Development commands:
+
    - `yarn build` - Build the project
+
    - `yarn jest` - Run tests
+
    - `yarn serve` - Start development server
 
 ### 7. Testing Guidelines
 
 - Write tests for both SharedArrayBuffer and fallback modes
+
 - Use Jest for testing
+
 - Include performance benchmarks for critical operations
 
 ### 8. Performance Considerations
 
 - Use bulk operations when possible
+
 - Monitor read/write performance
+
 - Consider using transactions for multiple operations
+
 - Avoid unnecessary database connections
 
 ### 9. Error Handling
 
 - Implement proper error handling for:
+
   - Worker initialization failures
+
   - Database connection issues
+
   - Concurrent access conflicts (in fallback mode)
+
   - Storage quota exceeded scenarios
 
 ### 10. Security Best Practices
 
 - Never expose database operations directly to the client
+
 - Validate all SQL queries
+
 - Implement proper access controls
+
 - Handle sensitive data appropriately
 
 ### 11. Code Style
 
 - Follow ESLint configuration
+
 - Use async/await for asynchronous operations
+
 - Document complex database operations
+
 - Include comments for non-obvious optimizations
 
 ### 12. Debugging
 
 - Use `jest-debug` for debugging tests
+
 - Monitor IndexedDB usage in browser dev tools
+
 - Check worker communication in console
+
 - Use performance monitoring tools
 
 ## Common Patterns
@@ -125,6 +162,7 @@ PRAGMA page_size=8192;  -- Optional, but recommended
 ### Worker Initialization
 
 ```javascript
+
 // Main thread
 import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread';
 
@@ -132,11 +170,13 @@ function init() {
   let worker = new Worker(new URL('./index.worker.js', import.meta.url));
   initBackend(worker);
 }
+
 ```
 
 ### Database Setup
 
 ```javascript
+
 // Worker thread
 import initSqlJs from '@jlongster/sql.js';
 import { SQLiteFS } from 'absurd-sql';
@@ -146,12 +186,13 @@ async function setupDatabase() {
   let SQL = await initSqlJs({ locateFile: file => file });
   let sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend());
   SQL.register_for_idb(sqlFS);
-  
+
   SQL.FS.mkdir('/sql');
   SQL.FS.mount(sqlFS, {}, '/sql');
-  
+
   return new SQL.Database('/sql/db.sqlite', { filename: true });
 }
+
 ```
 
 ## Troubleshooting
@@ -159,25 +200,37 @@ async function setupDatabase() {
 ### Common Issues
 
 1. SharedArrayBuffer not available
+
    - Check COOP/COEP headers
+
    - Verify browser support
+
    - Test fallback mode
 
 2. Worker initialization failures
+
    - Check file paths
+
    - Verify module imports
+
    - Check browser console for errors
 
 3. Performance issues
+
    - Monitor IndexedDB usage
+
    - Check for unnecessary operations
+
    - Verify transaction usage
 
 ## Resources
 
 - [Project Demo](https://priceless-keller-d097e5.netlify.app/)
+
 - [Example Project](https://github.com/jlongster/absurd-example-project)
+
 - [Blog Post](https://jlongster.com/future-sql-web)
+
 - [SQL.js Documentation](https://github.com/sql-js/sql.js/)
 
 ---
@@ -186,8 +239,35 @@ async function setupDatabase() {
 **Priority**: High
 **Estimated Effort**: Ongoing reference
 **Dependencies**: Absurd SQL, SQL.js, IndexedDB
-**Stakeholders**: Development team, Database team 
+**Stakeholders**: Development team, Database team
+
 - [Project Demo](https://priceless-keller-d097e5.netlify.app/)
+
 - [Example Project](https://github.com/jlongster/absurd-example-project)
+
 - [Blog Post](https://jlongster.com/future-sql-web)
+
 - [SQL.js Documentation](https://github.com/sql-js/sql.js/)
+
+## Model Implementation Checklist
+
+### Before Absurd SQL Implementation
+
+- [ ] **Browser Support**: Verify SharedArrayBuffer and COOP/COEP support
+- [ ] **Worker Setup**: Plan worker thread initialization and communication
+- [ ] **Database Planning**: Plan database schema and initialization
+- [ ] **Performance Planning**: Plan performance monitoring and optimization
+
+### During Absurd SQL Implementation
+
+- [ ] **Worker Initialization**: Set up worker threads with proper communication
+- [ ] **Database Setup**: Initialize SQLite database with IndexedDB backend
+- [ ] **File System**: Configure SQLiteFS with proper mounting
+- [ ] **Error Handling**: Implement proper error handling for worker failures
+
+### After Absurd SQL Implementation
+
+- [ ] **Cross-Browser Testing**: Test across different browsers and devices
+- [ ] **Performance Validation**: Monitor IndexedDB usage and performance
+- [ ] **Worker Validation**: Verify worker communication and database operations
+- [ ] **Documentation**: Update Absurd SQL implementation documentation

.cursor/rules/database/legacy_dexie.mdc

@@ -1,8 +1,62 @@
----
+# Legacy Dexie Database — Migration Guidelines
-globs: **/databaseUtil.ts,**/AccountViewView.vue,**/ContactsView.vue,**/DatabaseMigration.vue,**/NewIdentifierView.vue
-alwaysApply: false
----
-# What to do with Dexie
 
-All references in the codebase to Dexie apply only to migration from IndexedDb to
+> **Agent role**: Reference this file when working with legacy Dexie
-Sqlite and will be deprecated in future versions.
+> database code or migration patterns.
+
+## Overview
+
+All references in the codebase to Dexie apply only to migration from
+IndexedDb to Absurd SQL. Dexie is no longer used for new development.
+
+## Migration Status
+
+- **Legacy Code**: Existing Dexie implementations being migrated
+- **Target**: Absurd SQL with IndexedDB backend
+- **Timeline**: Gradual migration as features are updated
+
+## Key Principles
+
+- **No New Dexie**: All new database operations use Absurd SQL
+- **Migration Path**: Legacy code should be migrated when updated
+- **Backward Compatibility**: Maintain existing functionality during
+  migration
+
+## Integration Points
+
+- Apply these rules when updating database-related code
+- Use during feature development and refactoring
+- Include in database architecture decisions
+
+---
+
+**Status**: Legacy migration guidelines
+**Priority**: Low
+**Estimated Effort**: Ongoing reference
+**Dependencies**: absurd-sql.mdc
+**Stakeholders**: Database team, Development team
+
+All references in the codebase to Dexie apply only to migration from IndexedDb
+to Sqlite and will be deprecated in future versions.
+
+## Model Implementation Checklist
+
+### Before Legacy Dexie Work
+
+- [ ] **Migration Analysis**: Identify legacy Dexie code that needs migration
+- [ ] **Target Planning**: Plan migration to Absurd SQL with IndexedDB backend
+- [ ] **Backward Compatibility**: Plan to maintain existing functionality
+- [ ] **Testing Strategy**: Plan testing approach for migration
+
+### During Legacy Dexie Migration
+
+- [ ] **No New Dexie**: Ensure no new Dexie code is introduced
+- [ ] **Migration Implementation**: Implement migration to Absurd SQL
+- [ ] **Functionality Preservation**: Maintain existing functionality during migration
+- [ ] **Error Handling**: Implement proper error handling for migration
+
+### After Legacy Dexie Migration
+
+- [ ] **Functionality Testing**: Verify all functionality still works correctly
+- [ ] **Performance Validation**: Ensure performance meets or exceeds legacy
+- [ ] **Documentation Update**: Update database documentation
+- [ ] **Legacy Cleanup**: Remove deprecated Dexie code

.cursor/rules/development/asset_configuration.mdc

@@ -2,6 +2,7 @@
 description: when doing anything with capacitor assets
 alwaysApply: false
 ---
+
 # Asset Configuration Directive
 
 **Author**: Matthew Raymer
@@ -14,28 +15,43 @@ orchestration*
 ## Intent
 
 - Version **asset configuration files** (optionally dev-time generated).
+
 - **Do not** version platform asset outputs (Android/iOS/Electron); generate
+
   them **at build-time** with standard tools.
+
 - Keep existing per-platform build scripts unchanged.
 
 ## Source of Truth
 
 - **Preferred (Capacitor default):** `resources/` as the single master source.
+
 - **Alternative:** `assets/` is acceptable **only** if `capacitor-assets` is
+
   explicitly configured to read from it.
+
 - **Never** maintain both `resources/` and `assets/` as parallel sources.
+
   Migrate and delete the redundant folder.
 
 ## Config Files
 
 - Live under: `config/assets/` (committed).
+
 - Examples:
+
   - `config/assets/capacitor-assets.config.json` (or the path the tool
+
     expects)
+
   - `config/assets/android.assets.json`
+
   - `config/assets/ios.assets.json`
+
   - `config/assets/common.assets.yaml` (optional shared layer)
+
 - **Dev-time generation allowed** for these configs; **build-time
+
   generation is forbidden**.
 
 ## Build-Time Behavior
@@ -43,10 +59,13 @@ orchestration*
 - Build generates platform assets (not configs) using the standard chain:
 
 ```bash
+
 npm run build:capacitor        # web build via Vite (.mts)
 npx cap sync
 npx capacitor-assets generate  # produces platform assets; not committed
+
 # then platform-specific build steps
+
 ```
 
 ---
@@ -58,4 +77,29 @@ npx capacitor-assets generate  # produces platform assets; not committed
 **Stakeholders**: Development team, Build team
 
   npx capacitor-assets generate  # produces platform assets; not committed
-  # then platform-specific build steps
+
+# then platform-specific build steps
+
+## Model Implementation Checklist
+
+### Before Asset Configuration
+
+- [ ] **Source Review**: Identify current asset source location (`resources/` or
+  `assets/`)
+- [ ] **Tool Assessment**: Verify capacitor-assets toolchain is available
+- [ ] **Config Planning**: Plan configuration file structure and location
+- [ ] **Platform Analysis**: Understand asset requirements for all target platforms
+
+### During Asset Configuration
+
+- [ ] **Source Consolidation**: Ensure single source of truth (prefer `resources/`)
+- [ ] **Config Creation**: Create platform-specific asset configuration files
+- [ ] **Tool Integration**: Configure capacitor-assets to read from correct source
+- [ ] **Build Integration**: Integrate asset generation into build pipeline
+
+### After Asset Configuration
+
+- [ ] **Build Testing**: Verify assets generate correctly at build time
+- [ ] **Platform Validation**: Test asset generation across all platforms
+- [ ] **Documentation**: Update build documentation with asset generation steps
+- [ ] **Team Communication**: Communicate asset workflow changes to team

.cursor/rules/development/complexity_assessment.mdc

@@ -0,0 +1,177 @@
+# Complexity Assessment — Evaluation Frameworks
+
+> **Agent role**: Reference this file for
+  complexity evaluation frameworks when assessing project complexity.
+
+## 📊 Complexity Assessment Framework
+
+### **Technical Complexity Factors**
+
+#### **Code Changes**
+
+- **Simple**: Text, styling, configuration updates
+
+- **Medium**: New components, refactoring existing code
+
+- **Complex**: Architecture changes, new patterns, integrations
+
+- **Unknown**: New technologies, APIs, or approaches
+
+#### **Platform Impact**
+
+- **Single platform**: Web-only or mobile-only changes
+
+- **Two platforms**: Web + mobile or web + desktop
+
+- **Three platforms**: Web + mobile + desktop
+
+- **Cross-platform consistency**: Ensuring behavior matches across all platforms
+
+#### **Testing Requirements**
+
+- **Basic**: Unit tests for new functionality
+
+- **Comprehensive**: Integration tests, cross-platform testing
+
+- **User acceptance**: User testing, feedback integration
+
+- **Performance**: Load testing, optimization validation
+
+### **Dependency Complexity**
+
+#### **Internal Dependencies**
+
+- **Low**: Self-contained changes, no other components affected
+
+- **Medium**: Changes affect related components or services
+
+- **High**: Changes affect core architecture or multiple systems
+
+- **Critical**: Changes affect data models or core business logic
+
+#### **External Dependencies**
+
+- **None**: No external services or APIs involved
+
+- **Low**: Simple API calls or service integrations
+
+- **Medium**: Complex integrations with external systems
+
+- **High**: Third-party platform dependencies or complex APIs
+
+#### **Infrastructure Dependencies**
+
+- **None**: No infrastructure changes required
+
+- **Low**: Configuration updates or environment changes
+
+- **Medium**: New services or infrastructure components
+
+- **High**: Platform migrations or major infrastructure changes
+
+## 🔍 Complexity Evaluation Process
+
+### **Step 1: Technical Assessment**
+
+1. **Identify scope of changes** - what files/components are affected
+
+2. **Assess platform impact** - which platforms need updates
+
+3. **Evaluate testing needs** - what testing is required
+
+4. **Consider performance impact** - will this affect performance
+
+### **Step 2: Dependency Mapping**
+
+1. **Map internal dependencies** - what other components are affected
+
+2. **Identify external dependencies** - what external services are involved
+
+3. **Assess infrastructure needs** - what infrastructure changes are required
+
+4. **Evaluate risk factors** - what could go wrong
+
+### **Step 3: Complexity Classification**
+
+1. **Assign complexity levels** to each factor
+
+2. **Identify highest complexity** areas that need attention
+
+3. **Plan mitigation strategies** for high-complexity areas
+
+4. **Set realistic expectations** based on complexity assessment
+
+## 📋 Complexity Assessment Checklist
+
+- [ ] Technical scope identified and mapped
+
+- [ ] Platform impact assessed across all targets
+
+- [ ] Testing requirements defined and planned
+
+- [ ] Internal dependencies mapped and evaluated
+
+- [ ] External dependencies identified and assessed
+
+- [ ] Infrastructure requirements evaluated
+
+- [ ] Risk factors identified and mitigation planned
+
+- [ ] Complexity levels assigned to all factors
+
+- [ ] Realistic expectations set based on assessment
+
+## 🎯 Complexity Reduction Strategies
+
+### **Scope Reduction**
+
+- Break large features into smaller, manageable pieces
+
+- Focus on core functionality first, add polish later
+
+- Consider phased rollout to reduce initial complexity
+
+### **Dependency Management**
+
+- Minimize external dependencies when possible
+
+- Use abstraction layers to isolate complex integrations
+
+- Plan for dependency failures and fallbacks
+
+### **Testing Strategy**
+
+- Start with basic testing and expand coverage
+
+- Use automated testing to reduce manual testing complexity
+
+- Plan for iterative testing and feedback cycles
+
+## **See also**
+
+- `.cursor/rules/development/realistic_time_estimation.mdc` for the core principles
+
+- `.cursor/rules/development/planning_examples.mdc` for planning examples
+
+## Model Implementation Checklist
+
+### Before Complexity Assessment
+
+- [ ] **Problem Scope**: Clearly define the problem to be assessed
+- [ ] **Stakeholder Identification**: Identify all parties affected by complexity
+- [ ] **Context Analysis**: Understand technical and business context
+- [ ] **Assessment Criteria**: Define what factors determine complexity
+
+### During Complexity Assessment
+
+- [ ] **Technical Mapping**: Map technical scope and platform impact
+- [ ] **Dependency Analysis**: Identify internal and external dependencies
+- [ ] **Risk Evaluation**: Assess infrastructure needs and risk factors
+- [ ] **Complexity Classification**: Assign complexity levels to all factors
+
+### After Complexity Assessment
+
+- [ ] **Mitigation Planning**: Plan strategies for high-complexity areas
+- [ ] **Expectation Setting**: Set realistic expectations based on assessment
+- [ ] **Documentation**: Document assessment process and findings
+- [ ] **Stakeholder Communication**: Share results and recommendations

.cursor/rules/development/dependency_management.mdc

@@ -0,0 +1,177 @@
+# Dependency Management — Best Practices
+
+> **Agent role**: Reference this file for dependency management strategies and
+  best practices when working with software projects.
+
+## Dependency Management Best Practices
+
+### Pre-build Validation
+
+- **Check Critical Dependencies**:
+
+  Validate essential tools before executing build
+  scripts
+
+- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to
+
+  avoid PATH issues
+
+- **Environment Consistency**: Ensure all team members have identical dependency
+
+  versions
+
+### Common Pitfalls
+
+- **Missing npm install**: Team members cloning without running `npm install`
+
+- **PATH Issues**: Direct command execution vs. npm script execution differences
+
+- **Version Mismatches**: Different Node.js/npm versions across team members
+
+### Validation Strategies
+
+- **Dependency Check Scripts**: Implement pre-build validation for critical
+
+  dependencies
+
+- **Environment Requirements**:
+
+  Document and enforce minimum Node.js/npm versions
+
+- **Onboarding Checklist**: Standardize team member setup procedures
+
+### Error Messages and Guidance
+
+- **Specific Error Context**:
+
+  Provide clear guidance when dependency issues occur
+
+- **Actionable Solutions**: Direct users to specific commands (`npm install`,
+
+  `npm run check:dependencies`)
+
+- **Environment Diagnostics**: Implement comprehensive environment validation
+
+  tools
+
+### Build Script Enhancements
+
+- **Early Validation**: Check dependencies before starting build processes
+
+- **Graceful Degradation**: Continue builds when possible but warn about issues
+
+- **Helpful Tips**: Remind users about dependency management best practices
+
+## Environment Setup Guidelines
+
+### Required Tools
+
+- **Node.js**: Minimum version requirements and LTS recommendations
+
+- **npm**: Version compatibility and global package management
+
+- **Platform-specific tools**: Android SDK, Xcode, etc.
+
+### Environment Variables
+
+- **NODE_ENV**: Development, testing, production environments
+
+- **PATH**: Ensure tools are accessible from command line
+
+- **Platform-specific**: Android SDK paths, Xcode command line tools
+
+### Validation Commands
+
+```bash
+
+# Check Node.js version
+
+node --version
+
+# Check npm version
+
+npm --version
+
+# Check global packages
+
+npm list -g --depth=0
+
+# Validate platform tools
+
+npx capacitor doctor
+
+```
+
+## Dependency Troubleshooting
+
+### Common Issues
+
+1. **Permission Errors**: Use `sudo` sparingly, prefer `npm config set prefix`
+
+2. **Version Conflicts**: Use `npm ls` to identify dependency conflicts
+
+3. **Cache Issues**: Clear npm cache with `npm cache clean --force`
+
+4. **Lock File Issues**: Delete `package-lock.json` and `node_modules`,
+
+  then reinstall
+
+### Resolution Strategies
+
+- **Dependency Audit**: Run `npm audit` to identify security issues
+
+- **Version Pinning**: Use exact versions for critical dependencies
+
+- **Peer Dependency Management**: Ensure compatible versions across packages
+
+- **Platform-specific Dependencies**: Handle different requirements per platform
+
+## Best Practices for Teams
+
+### Onboarding
+
+- **Environment Setup Script**: Automated setup for new team members
+
+- **Version Locking**: Use `package-lock.json` and `yarn.lock` consistently
+
+- **Documentation**: Clear setup instructions with troubleshooting steps
+
+### Maintenance
+
+- **Regular Updates**: Schedule dependency updates and security patches
+
+- **Testing**: Validate changes don't break existing functionality
+
+- **Rollback Plan**: Maintain ability to revert to previous working versions
+
+**See also**:
+  `.cursor/rules/development/software_development.mdc` for core development principles.
+
+**Status**: Active dependency management guidelines
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: software_development.mdc
+**Stakeholders**: Development team, DevOps team
+
+## Model Implementation Checklist
+
+### Before Dependency Changes
+
+- [ ] **Current State Review**: Check current dependency versions and status
+- [ ] **Impact Analysis**: Assess impact of dependency changes on codebase
+- [ ] **Compatibility Check**: Verify compatibility with existing code
+- [ ] **Security Review**: Review security implications of dependency changes
+
+### During Dependency Management
+
+- [ ] **Version Selection**: Choose appropriate dependency versions
+- [ ] **Testing**: Test with new dependency versions
+- [ ] **Documentation**: Update dependency documentation
+- [ ] **Team Communication**: Communicate changes to team members
+
+### After Dependency Changes
+
+- [ ] **Comprehensive Testing**: Test all functionality with new dependencies
+- [ ] **Documentation Update**: Update all relevant documentation
+- [ ] **Deployment Planning**: Plan and execute deployment strategy
+- [ ] **Monitoring**: Monitor for issues after deployment

.cursor/rules/development/development_guide.mdc

@@ -2,8 +2,32 @@
 globs: **/src/**/*
 alwaysApply: false
 ---
-✅ use system date command to timestamp all interactions with accurate date and time
+✅ use system date command to timestamp all interactions with accurate date and
+  time
 ✅ python script files must always have a blank line at their end
 ✅ remove whitespace at the end of lines
 ✅ use npm run lint-fix to check for warnings
 ✅ do not use npm run dev let me handle running and supplying feedback
+
+## Model Implementation Checklist
+
+### Before Development Work
+
+- [ ] **System Date Check**: Use system date command for accurate timestamps
+- [ ] **Environment Setup**: Verify development environment is ready
+- [ ] **Linting Setup**: Ensure npm run lint-fix is available
+- [ ] **Code Standards**: Review project coding standards and requirements
+
+### During Development
+
+- [ ] **Timestamp Usage**: Include accurate timestamps in all interactions
+- [ ] **Code Quality**: Use npm run lint-fix to check for warnings
+- [ ] **File Standards**: Ensure Python files have blank line at end
+- [ ] **Whitespace**: Remove trailing whitespace from all lines
+
+### After Development
+
+- [ ] **Linting Check**: Run npm run lint-fix to verify code quality
+- [ ] **File Validation**: Confirm Python files end with blank line
+- [ ] **Whitespace Review**: Verify no trailing whitespace remains
+- [ ] **Documentation**: Update relevant documentation with changes

.cursor/rules/development/historical_comment_management.mdc

@@ -0,0 +1,119 @@
+# Historical Comment Management — Code Clarity Guidelines
+
+> **Agent role**: When encountering historical comments about removed
+> methods, deprecated patterns, or architectural changes, apply these
+> guidelines to maintain code clarity and developer guidance.
+
+## Overview
+
+Historical comments should either be **removed entirely** or **transformed
+into actionable guidance** for future developers. Avoid keeping comments
+that merely state what was removed without explaining why or what to do
+instead.
+
+## Decision Framework
+
+### When to Remove Comments
+
+- **Obsolete Information**: Comment describes functionality that no
+  longer exists
+- **Outdated Context**: Comment refers to old patterns that are no
+  longer relevant
+- **No Actionable Value**: Comment doesn't help future developers
+  make decisions
+
+### When to Transform Comments
+
+- **Migration Guidance**: Future developers might need to understand
+  the evolution
+- **Alternative Approaches**: The comment can guide future
+  implementation choices
+- **Historical Context**: Understanding the change helps with
+  current decisions
+
+## Transformation Patterns
+
+### 1. **Removed Method** → **Alternative Approach**
+
+```typescript
+// Before: Historical comment
+// turnOffNotifyingFlags method removed - notification state is now
+// managed by NotificationSection component
+
+// After: Actionable guidance
+// Note: Notification state management has been migrated to
+// NotificationSection component
+```
+
+### 2. **Deprecated Pattern** → **Current Best Practice**
+
+```typescript
+// Before: Historical comment
+// Database access has been migrated from direct IndexedDB calls to
+// PlatformServiceMixin
+
+// After: Actionable guidance
+// This provides better platform abstraction and consistent error
+// handling across web/mobile/desktop
+
+// When adding new database operations, use this.$getContact(),
+// this.$saveSettings(), etc.
+```
+
+## Best Practices
+
+### 1. **Use Actionable Language**: Guide future decisions, not just
+
+document history
+
+### 2. **Provide Alternatives**: Always suggest what to use instead
+
+### 3. **Update Related Docs**: If removing from code, consider
+
+adding to documentation
+
+### 4. **Keep Context**: Include enough information to understand
+
+why the change was made
+
+## Integration Points
+
+- Apply these rules when reviewing code changes
+- Use during code cleanup and refactoring
+- Include in code review checklists
+
+---
+
+**See also**:
+
+- `.cursor/rules/development/historical_comment_patterns.mdc` for detailed
+  transformation examples and patterns
+
+**Status**: Active comment management guidelines
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Development team, Code reviewers
+
+## Model Implementation Checklist
+
+### Before Comment Review
+
+- [ ] **Code Analysis**: Review code for historical or outdated comments
+- [ ] **Context Understanding**: Understand the current state of the codebase
+- [ ] **Pattern Identification**: Identify comments that need transformation or removal
+- [ ] **Documentation Planning**: Plan where to move important historical context
+
+### During Comment Management
+
+- [ ] **Transformation**: Convert historical comments to actionable guidance
+- [ ] **Alternative Provision**: Suggest current best practices and alternatives
+- [ ] **Context Preservation**: Maintain enough information to understand changes
+- [ ] **Documentation Update**: Move important context to appropriate documentation
+
+### After Comment Management
+
+- [ ] **Code Review**: Ensure transformed comments provide actionable value
+- [ ] **Documentation Sync**: Verify related documentation is updated
+- [ ] **Team Communication**: Share comment transformation patterns with team
+- [ ] **Process Integration**: Include comment management in code review checklists

.cursor/rules/development/historical_comment_patterns.mdc

@@ -0,0 +1,139 @@
+# Historical Comment Patterns — Transformation Examples
+
+> **Agent role**: Reference this file for specific patterns and
+  examples when transforming historical comments into actionable guidance.
+
+## 🔄 Transformation Patterns
+
+### 1. From Removal Notice to Migration Note
+
+```typescript
+
+// ❌ REMOVE THIS
+// turnOffNotifyingFlags method removed - 
+  notification state is now managed by NotificationSection component
+
+// ✅ TRANSFORM TO THIS
+// Note: Notification state management has been migrated to NotificationSection
+  component
+// which handles its own lifecycle and persistence via PlatformServiceMixin
+
+```
+
+### 2. From Deprecation Notice to Implementation Guide
+
+```typescript
+
+// ❌ REMOVE THIS
+// This will be handled by the NewComponent now
+// No need to call oldMethod() as it's no longer needed
+
+// ✅ TRANSFORM TO THIS
+// Note: This functionality has been migrated to NewComponent
+// which provides better separation of concerns and testability
+
+```
+
+### 3. From Historical Note to Architectural Context
+
+```typescript
+
+// ❌ REMOVE THIS
+// Old approach: used direct database calls
+// New approach: uses service layer
+
+// ✅ TRANSFORM TO THIS
+// Note: Database access has been abstracted through service layer
+// for better testability and platform independence
+
+```
+
+## 🚫 Anti-Patterns to Remove
+
+- Comments that only state what was removed
+
+- Comments that don't explain the current approach
+
+- Comments that reference non-existent methods
+
+- Comments that are self-evident from the code
+
+- Comments that don't help future decision-making
+
+## 📚 Examples
+
+### Good Historical Comment (Keep & Transform)
+
+```typescript
+
+// Note: Database access has been migrated from direct IndexedDB calls to
+  PlatformServiceMixin
+// This provides better platform abstraction and 
+  consistent error handling across web/mobile/desktop
+// When adding new database operations, use this.$getContact(),
+  this.$saveSettings(), etc.
+
+```
+
+### Bad Historical Comment (Remove)
+
+```typescript
+
+// Old method getContactFromDB() removed - now handled by PlatformServiceMixin
+// No need to call the old method anymore
+
+```
+
+## 🎯 When to Use Each Pattern
+
+### Migration Notes
+
+- Use when functionality has moved to a different component/service
+
+- Explain the new location and why it's better
+
+- Provide guidance on how to use the new approach
+
+### Implementation Guides
+
+- Use when patterns have changed significantly
+
+- Explain the architectural benefits
+
+- Show how to implement the new pattern
+
+### Architectural Context
+
+- Use when the change represents a system-wide improvement
+
+- Explain the reasoning behind the change
+
+- Help future developers understand the evolution
+
+---
+
+**See also**: `.cursor/rules/development/historical_comment_management.mdc` for
+  the core decision framework and best practices.
+
+## Model Implementation Checklist
+
+### Before Comment Review
+
+- [ ] **Code Analysis**: Review code for historical or outdated comments
+- [ ] **Pattern Identification**: Identify comments that need transformation or removal
+- [ ] **Context Understanding**: Understand the current state of the codebase
+- [ ] **Transformation Planning**: Plan how to transform or remove comments
+
+### During Comment Transformation
+
+- [ ] **Pattern Selection**: Choose appropriate transformation pattern
+- [ ] **Content Creation**: Create actionable guidance for future developers
+- [ ] **Alternative Provision**: Suggest current best practices and approaches
+- [ ] **Context Preservation**: Maintain enough information to understand changes
+
+### After Comment Transformation
+
+- [ ] **Code Review**: Ensure transformed comments provide actionable value
+- [ ] **Pattern Documentation**: Document transformation patterns for team use
+- [ ] **Team Communication**: Share comment transformation patterns with team
+- [ ] **Process Integration**: Include comment patterns in code review checklists

.cursor/rules/development/investigation_report_example.mdc

@@ -14,70 +14,100 @@ import scenarios.
 ## System Map
 
 - User action → ContactInputForm → ContactsView.addContact() →
+
   handleRegistrationPrompt()
+
 - setTimeout(1000ms) → Modal dialog → User response → Registration API call
+
 - Test execution → Wait for dialog → Assert dialog content → Click response
+
   button
 
 ## Findings (Evidence)
 
 - **1-second timeout causes flakiness** — evidence:
+
   `src/views/ContactsView.vue:971-1000`; setTimeout(..., 1000) in
   handleRegistrationPrompt()
+
 - **Import flow bypasses dialogs** — evidence:
+
   `src/views/ContactImportView.vue:500-520`; importContacts() calls
   $insertContact() directly, no handleRegistrationPrompt()
+
 - **Dialog only appears in direct add flow** — evidence:
+
   `src/views/ContactsView.vue:774-800`; addContact() calls
   handleRegistrationPrompt() after database insert
 
 ## Hypotheses & Failure Modes
 
 - H1: 1-second timeout makes dialog appearance unpredictable; would fail when
+
   tests run faster than 1000ms
+
 - H2: Test environment timing differs from development; watch for CI vs local
+
   test differences
 
 ## Corrections
 
 - Updated: "Multiple dialogs interfere with imports" → "Import flow never
+
   triggers dialogs - they only appear in direct contact addition"
+
 - Updated: "Complex batch registration needed" → "Simple timeout removal and
+
   test mode flag sufficient"
 
 ## Diagnostics (Next Checks)
 
 - [ ] Repro on CI environment vs local
+
 - [ ] Measure actual dialog appearance timing
+
 - [ ] Test with setTimeout removed
+
 - [ ] Verify import flow doesn't call handleRegistrationPrompt
 
 ## Risks & Scope
 
 - Impacted: Contact addition tests, registration workflow tests; Data: None;
+
   Users: Test suite reliability
 
 ## Decision / Next Steps
 
 - Owner: Development Team; By: 2025-01-28
+
 - Action: Remove 1-second timeout + add test mode flag; Exit criteria: Tests
+
   pass consistently
 
 ## References
 
 - `src/views/ContactsView.vue:971-1000`
+
 - `src/views/ContactImportView.vue:500-520`
+
 - `src/views/ContactsView.vue:774-800`
 
 ## Competence Hooks
 
 - Why this works: Code path tracing revealed separate execution flows,
+
   evidence disproved initial assumptions
+
 - Common pitfalls: Assuming related functionality without tracing execution
+
   paths, over-engineering solutions to imaginary problems
+
 - Next skill: Learn to trace code execution before proposing architectural
+
   changes
+
 - Teach-back: "What evidence shows that contact imports bypass registration
+
   dialogs?"
 
 ## Key Learning Points
@@ -87,8 +117,11 @@ import scenarios.
 This investigation demonstrates the importance of:
 
 1. **Tracing actual code execution** rather than making assumptions
+
 2. **Citing specific evidence** with file:line references
+
 3. **Validating problem scope** before proposing solutions
+
 4. **Considering simpler alternatives** before complex architectural changes
 
 ### Code Path Tracing Value
@@ -96,7 +129,9 @@ This investigation demonstrates the importance of:
 By tracing the execution paths, we discovered:
 
 - Import flow and direct add flow are completely separate
+
 - The "multiple dialog interference" problem didn't exist
+
 - A simple timeout removal would solve the actual issue
 
 ### Prevention of Over-Engineering
@@ -104,8 +139,11 @@ By tracing the execution paths, we discovered:
 The investigation prevented:
 
 - Unnecessary database schema changes
+
 - Complex batch registration systems
+
 - Migration scripts for non-existent problems
+
 - Architectural changes based on assumptions
 
 ---
@@ -115,3 +153,26 @@ The investigation prevented:
 **Estimated Effort**: Ongoing reference
 **Dependencies**: software_development.mdc
 **Stakeholders**: Development team, QA team
+
+## Model Implementation Checklist
+
+### Before Investigation
+
+- [ ] **Problem Definition**: Clearly define the problem to investigate
+- [ ] **Scope Definition**: Determine investigation scope and boundaries
+- [ ] **Methodology Planning**: Plan investigation approach and methods
+- [ ] **Resource Assessment**: Identify required resources and tools
+
+### During Investigation
+
+- [ ] **Evidence Collection**: Gather relevant evidence and data systematically
+- [ ] **Code Path Tracing**: Map execution flow for software investigations
+- [ ] **Analysis**: Analyze evidence using appropriate methods
+- [ ] **Documentation**: Document investigation process and findings
+
+### After Investigation
+
+- [ ] **Synthesis**: Synthesize findings into actionable insights
+- [ ] **Report Creation**: Create comprehensive investigation report
+- [ ] **Recommendations**: Provide clear, actionable recommendations
+- [ ] **Team Communication**: Share findings and next steps with team

.cursor/rules/development/logging_migration.mdc

@@ -0,0 +1,358 @@
+---
+alwaysApply: false
+---
+
+# Logging Migration — Patterns and Examples
+
+> **Agent role**: Reference this file for specific migration patterns and
+  examples when converting console.* calls to logger usage.
+
+## Migration — Auto‑Rewrites (Apply Every Time)
+
+### Exact Transforms
+
+- `console.debug(...)` → `logger.debug(...)`
+
+- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when
+
+  clearly stateful)
+
+- `console.info(...)` → `logger.info(...)`
+
+- `console.warn(...)` → `logger.warn(...)`
+
+- `console.error(...)` → `logger.error(...)`
+
+### Multi-arg Handling
+
+- First arg becomes `message` (stringify safely if non-string).
+
+- Remaining args map 1:1 to `...args`:
+
+  `console.info(msg, a, b)` → `logger.info(String(msg), a, b)`
+
+### Sole `Error`
+
+- `console.error(err)` → `logger.error(err.message, err)`
+
+### Object-wrapping Cleanup
+
+Replace `{{ userId, meta }}` wrappers with separate args:
+`logger.info('User signed in', userId, meta)`
+
+## Level Guidelines with Examples
+
+### DEBUG Examples
+
+```typescript
+
+logger.debug('[HomeView] reloadFeedOnChange() called');
+logger.debug('[HomeView] Current filter settings',
+  settings.filterFeedByVisible,
+  settings.filterFeedByNearby,
+  settings.searchBoxes?.length ?? 0);
+logger.debug('[FeedFilters] Toggling nearby filter',
+  this.isNearby, this.settingChanged, this.activeDid);
+
+```
+
+**Avoid**: Vague messages (`'Processing data'`).
+
+### INFO Examples
+
+```typescript
+
+logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM);
+logger.info('[StartView] User selected new seed generation');
+logger.info('[SearchAreaView] Search box stored',
+  searchBox.name, searchBox.bbox);
+logger.info('[ContactQRScanShowView] Contact registration OK',
+  contact.did);
+
+```
+
+**Avoid**: Diagnostic details that belong in `debug`.
+
+### WARN Examples
+
+```typescript
+
+logger.warn('[ContactQRScanShowView] Invalid scan result – no value',
+  resultType);
+logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL');
+logger.warn('[ContactQRScanShowView] JWT missing "own" field');
+
+```
+
+**Avoid**: Hard failures (those are `error`).
+
+### ERROR Examples
+
+```typescript
+
+logger.error('[HomeView Settings] initializeIdentity() failed', err);
+logger.error('[StartView] Failed to load initialization data', error);
+logger.error('[ContactQRScanShowView] Error processing contact QR',
+  error, rawValue);
+
+```
+
+**Avoid**: Expected user cancels (use `info`/`debug`).
+
+## Context Hygiene Examples
+
+### Component Context
+
+```typescript
+
+const log = logger.withContext('UserService');
+log.info('User created', userId);
+log.error('Failed to create user', error);
+
+```
+
+If not using `withContext`, prefix message with `[ComponentName]`.
+
+### Emoji Guidelines
+
+Recommended set for visual scanning:
+
+- Start/finish: 🚀 / ✅
+
+- Retry/loop: 🔄
+
+- External call: 📡
+
+- Data/metrics: 📊
+
+- Inspection: 🔍
+
+## Quick Before/After
+
+### **Before**
+
+```typescript
+
+console.log('User signed in', user.id, meta);
+console.error('Failed to update profile', err);
+console.info('Filter toggled', this.hasVisibleDid);
+
+```
+
+### **After**
+
+```typescript
+
+import { logger } from '@/utils/logger';
+
+logger.info('User signed in', user.id, meta);
+logger.error('Failed to update profile', err);
+logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid);
+
+```
+
+## Checklist (for every PR)
+
+- [ ] No `console.*` (or properly pragma'd in the allowed locations)
+
+- [ ] Correct import path for `logger`
+
+- [ ] Rest-parameter call shape (`message, ...args`)
+
+- [ ] Right level chosen (debug/info/warn/error)
+
+- [ ] No secrets / oversized payloads / throwaway context objects
+
+- [ ] Component context provided (scoped logger or `[Component]` prefix)
+
+**See also**:
+  `.cursor/rules/development/logging_standards.mdc` for the core standards and rules.
+
+# Logging Migration — Patterns and Examples
+
+> **Agent role**: Reference this file for specific migration patterns and
+  examples when converting console.* calls to logger usage.
+
+## Migration — Auto‑Rewrites (Apply Every Time)
+
+### Exact Transforms
+
+- `console.debug(...)` → `logger.debug(...)`
+
+- `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when
+
+  clearly stateful)
+
+- `console.info(...)` → `logger.info(...)`
+
+- `console.warn(...)` → `logger.warn(...)`
+
+- `console.error(...)` → `logger.error(...)`
+
+### Multi-arg Handling
+
+- First arg becomes `message` (stringify safely if non-string).
+
+- Remaining args map 1:1 to `...args`:
+
+  `console.info(msg, a, b)` → `logger.info(String(msg), a, b)`
+
+### Sole `Error`
+
+- `console.error(err)` → `logger.error(err.message, err)`
+
+### Object-wrapping Cleanup
+
+Replace `{{ userId, meta }}` wrappers with separate args:
+`logger.info('User signed in', userId, meta)`
+
+## Level Guidelines with Examples
+
+### DEBUG Examples
+
+```typescript
+
+logger.debug('[HomeView] reloadFeedOnChange() called');
+logger.debug('[HomeView] Current filter settings',
+  settings.filterFeedByVisible,
+  settings.filterFeedByNearby,
+  settings.searchBoxes?.length ?? 0);
+logger.debug('[FeedFilters] Toggling nearby filter',
+  this.isNearby, this.settingChanged, this.activeDid);
+
+```
+
+**Avoid**: Vague messages (`'Processing data'`).
+
+### INFO Examples
+
+```typescript
+
+logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM);
+logger.info('[StartView] User selected new seed generation');
+logger.info('[SearchAreaView] Search box stored',
+  searchBox.name, searchBox.bbox);
+logger.info('[ContactQRScanShowView] Contact registration OK',
+  contact.did);
+
+```
+
+**Avoid**: Diagnostic details that belong in `debug`.
+
+### WARN Examples
+
+```typescript
+
+logger.warn('[ContactQRScanShowView] Invalid scan result – no value',
+  resultType);
+logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL');
+logger.warn('[ContactQRScanShowView] JWT missing "own" field');
+
+```
+
+**Avoid**: Hard failures (those are `error`).
+
+### ERROR Examples
+
+```typescript
+
+logger.error('[HomeView Settings] initializeIdentity() failed', err);
+logger.error('[StartView] Failed to load initialization data', error);
+logger.error('[ContactQRScanShowView] Error processing contact QR',
+  error, rawValue);
+
+```
+
+**Avoid**: Expected user cancels (use `info`/`debug`).
+
+## Context Hygiene Examples
+
+### Component Context
+
+```typescript
+
+const log = logger.withContext('UserService');
+log.info('User created', userId);
+log.error('Failed to create user', error);
+
+```
+
+If not using `withContext`, prefix message with `[ComponentName]`.
+
+### Emoji Guidelines
+
+Recommended set for visual scanning:
+
+- Start/finish: 🚀 / ✅
+
+- Retry/loop: 🔄
+
+- External call: 📡
+
+- Data/metrics: 📊
+
+- Inspection: 🔍
+
+## Quick Before/After
+
+### **Before**
+
+```typescript
+
+console.log('User signed in', user.id, meta);
+console.error('Failed to update profile', err);
+console.info('Filter toggled', this.hasVisibleDid);
+
+```
+
+### **After**
+
+```typescript
+
+import { logger } from '@/utils/logger';
+
+logger.info('User signed in', user.id, meta);
+logger.error('Failed to update profile', err);
+logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid);
+
+```
+
+## Checklist (for every PR)
+
+- [ ] No `console.*` (or properly pragma'd in the allowed locations)
+
+- [ ] Correct import path for `logger`
+
+- [ ] Rest-parameter call shape (`message, ...args`)
+
+- [ ] Right level chosen (debug/info/warn/error)
+
+- [ ] No secrets / oversized payloads / throwaway context objects
+
+- [ ] Component context provided (scoped logger or `[Component]` prefix)
+
+**See also**:
+  `.cursor/rules/development/logging_standards.mdc` for the core standards and rules.
+
+## Model Implementation Checklist
+
+### Before Logging Migration
+
+- [ ] **Code Review**: Identify all `console.*` calls in the codebase
+- [ ] **Logger Import**: Verify logger utility is available and accessible
+- [ ] **Context Planning**: Plan component context for each logging call
+- [ ] **Level Assessment**: Determine appropriate log levels for each call
+
+### During Logging Migration
+
+- [ ] **Import Replacement**: Replace `console.*` with `logger.*` calls
+- [ ] **Context Addition**: Add component context using scoped logger or prefix
+- [ ] **Level Selection**: Choose appropriate log level (debug/info/warn/error)
+- [ ] **Parameter Format**: Use rest-parameter call shape (`message, ...args`)
+
+### After Logging Migration
+
+- [ ] **Console Check**: Ensure no `console.*` methods remain (unless pragma'd)
+- [ ] **Context Validation**: Verify all logging calls have proper context
+- [ ] **Level Review**: Confirm log levels are appropriate for each situation
+- [ ] **Testing**: Test logging functionality across all platforms

.cursor/rules/development/logging_standards.mdc

@@ -21,29 +21,49 @@ logger; no `console.*` in production code.
 ## Non‑Negotiables (DO THIS)
 
 - You **MUST** use the project logger; **DO NOT** use any `console.*`
+
   methods.
+
 - Import exactly as:
+
   - `import { logger } from '@/utils/logger'`
+
   - If `@` alias is unavailable, compute the correct relative path (do not
+
     fail).
+
 - Call signatures use **rest parameters**: `logger.info(message, ...args)`
+
 - Prefer primitives/IDs and small objects in `...args`; **never build a
+
   throwaway object** just to "wrap context".
+
 - Production defaults: Web = `warn+`, Electron = `error`, Dev/Capacitor =
+
   `info+` (override via `VITE_LOG_LEVEL`).
+
 - **Database persistence**: `info|warn|error` are persisted; `debug` is not.
+
   Use `logger.toDb(msg, level?)` for DB-only.
 
 ## Available Logger API (Authoritative)
 
 - `logger.debug(message, ...args)` — verbose internals, timings, input/output
+
   shapes
+
 - `logger.log(message, ...args)` — synonym of `info` for general info
+
 - `logger.info(message, ...args)` — lifecycle, state changes, success paths
+
 - `logger.warn(message, ...args)` — recoverable issues, retries, degraded mode
+
 - `logger.error(message, ...args)` — failures, thrown exceptions, aborts
+
 - `logger.toDb(message, level?)` — DB-only entry (default level = `info`)
+
 - `logger.toConsoleAndDb(message, isError)` — console + DB (use sparingly)
+
 - `logger.withContext(componentName)` — returns a scoped logger
 
 ## Level Guidelines (Use These Heuristics)
@@ -53,108 +73,34 @@ logger; no `console.*` in production code.
 Use for method entry/exit, computed values, filters, loops, retries, and
 external call payload sizes.
 
-```typescript
-logger.debug('[HomeView] reloadFeedOnChange() called');
-logger.debug('[HomeView] Current filter settings', 
-  settings.filterFeedByVisible, 
-  settings.filterFeedByNearby, 
-  settings.searchBoxes?.length ?? 0);
-logger.debug('[FeedFilters] Toggling nearby filter', 
-  this.isNearby, this.settingChanged, this.activeDid);
-```
-
-**Avoid**: Vague messages (`'Processing data'`).
-
 ### INFO
 
 Use for user-visible lifecycle and completed operations.
 
-```typescript
-logger.info('[StartView] Component mounted', process.env.VITE_PLATFORM);
-logger.info('[StartView] User selected new seed generation');
-logger.info('[SearchAreaView] Search box stored', 
-  searchBox.name, searchBox.bbox);
-logger.info('[ContactQRScanShowView] Contact registration OK', 
-  contact.did);
-```
-
-**Avoid**: Diagnostic details that belong in `debug`.
-
 ### WARN
 
 Use for recoverable issues, fallbacks, unexpected-but-handled conditions.
 
-```typescript
-logger.warn('[ContactQRScanShowView] Invalid scan result – no value', 
-  resultType);
-logger.warn('[ContactQRScanShowView] Invalid QR format – no JWT in URL');
-logger.warn('[ContactQRScanShowView] JWT missing "own" field');
-```
-
-**Avoid**: Hard failures (those are `error`).
-
 ### ERROR
 
 Use for unrecoverable failures, data integrity issues, and thrown
 exceptions.
 
-```typescript
-logger.error('[HomeView Settings] initializeIdentity() failed', err);
-logger.error('[StartView] Failed to load initialization data', error);
-logger.error('[ContactQRScanShowView] Error processing contact QR', 
-  error, rawValue);
-```
-
-**Avoid**: Expected user cancels (use `info`/`debug`).
-
 ## Context Hygiene (Consistent, Minimal, Helpful)
 
 - **Component context**: Prefer scoped logger.
 
-```typescript
+- **Emojis**: Optional and minimal for visual scanning.
-const log = logger.withContext('UserService');
-log.info('User created', userId);
-log.error('Failed to create user', error);
-```
-
-If not using `withContext`, prefix message with `[ComponentName]`.
-
-- **Emojis**: Optional and minimal for visual scanning. Recommended set:
-  - Start/finish: 🚀 / ✅
-  - Retry/loop: 🔄
-  - External call: 📡
-  - Data/metrics: 📊
-  - Inspection: 🔍
 
 - **Sensitive data**: Never log secrets (tokens, keys, passwords) or
   payloads >10KB. Prefer IDs over objects; redact/hash when needed.
 
-## Migration — Auto‑Rewrites (Apply Every Time)
-
-- Exact transforms:
-  - `console.debug(...)` → `logger.debug(...)`
-  - `console.log(...)` → `logger.log(...)` (or `logger.info(...)` when
-    clearly stateful)
-  - `console.info(...)` → `logger.info(...)`
-  - `console.warn(...)` → `logger.warn(...)`
-  - `console.error(...)` → `logger.error(...)`
-
-- Multi-arg handling:
-  - First arg becomes `message` (stringify safely if non-string).
-  - Remaining args map 1:1 to `...args`:
-    `console.info(msg, a, b)` → `logger.info(String(msg), a, b)`
-
-- Sole `Error`:
-  - `console.error(err)` → `logger.error(err.message, err)`
-
-- **Object-wrapping cleanup**: Replace `{{ userId, meta }}` wrappers with
-  separate args:
-  `logger.info('User signed in', userId, meta)`
-
 ## DB Logging Rules
 
 - `debug` **never** persists automatically.
+
 - `info|warn|error` persist automatically.
+
 - For DB-only events (no console), call `logger.toDb('Message',
   'info'|'warn'|'error')`.
 
@@ -163,60 +109,68 @@ If not using `withContext`, prefix message with `[ComponentName]`.
 Allowed paths (still prefer logger):
 
 - `**/*.test.*`, `**/*.spec.*`
+
 - `scripts/dev/**`, `scripts/migrate/**`
 
 To intentionally keep `console.*`, add a pragma on the previous line:
 
 ```typescript
+
 // cursor:allow-console reason="short justification"
 console.log('temporary output');
-```
 
-Without the pragma, rewrite to `logger.*`.
+```
 
 ## CI & Diff Enforcement
 
 - Do not introduce `console.*` anywhere outside allowed, pragma'd spots.
+
 - If an import is missing, insert it and resolve alias/relative path
   correctly.
+
 - Enforce rest-parameter call shape in reviews; replace object-wrapped
   context.
+
 - Ensure environment log level rules remain intact (`VITE_LOG_LEVEL`
   respected).
 
-## Quick Before/After
-
-### **Before**
-
-```typescript
-console.log('User signed in', user.id, meta);
-console.error('Failed to update profile', err);
-console.info('Filter toggled', this.hasVisibleDid);
-```
-
-### **After**
-
-```typescript
-import { logger } from '@/utils/logger';
-
-logger.info('User signed in', user.id, meta);
-logger.error('Failed to update profile', err);
-logger.debug('[FeedFilters] Filter toggled', this.hasVisibleDid);
-```
-
-## Checklist (for every PR)
-
-- [ ] No `console.*` (or properly pragma'd in the allowed locations)
-- [ ] Correct import path for `logger`
-- [ ] Rest-parameter call shape (`message, ...args`)
-- [ ] Right level chosen (debug/info/warn/error)
-- [ ] No secrets / oversized payloads / throwaway context objects
-- [ ] Component context provided (scoped logger or `[Component]` prefix)
-
 ---
 
+**See also**:
+  `.cursor/rules/development/logging_migration.mdc` for migration patterns and examples.
+
 **Status**: Active and enforced
 **Priority**: Critical
 **Estimated Effort**: Ongoing reference
 **Dependencies**: TimeSafari logger utility
 **Stakeholders**: Development team, Code review team
+
+## Model Implementation Checklist
+
+### Before Adding Logging
+
+- [ ] **Logger Import**: Import logger as `import { logger } from
+  '@/utils/logger'`
+- [ ] **Log Level Selection**: Determine appropriate log level
+  (debug/info/warn/error)
+- [ ] **Context Planning**: Plan what context information to include
+- [ ] **Sensitive Data Review**: Identify any sensitive data that needs redaction
+
+### During Logging Implementation
+
+- [ ] **Rest Parameters**: Use `logger.info(message, ...args)` format, not object
+  wrapping
+- [ ] **Context Addition**: Include relevant IDs, primitives, or small objects in
+  args
+- [ ] **Level Appropriateness**: Use correct log level for the situation
+- [ ] **Scoped Logger**: Use `logger.withContext(componentName)` for
+  component-specific logging
+
+### After Logging Implementation
+
+- [ ] **Console Check**: Ensure no `console.*` methods are used (unless in
+  allowed paths)
+- [ ] **Performance Review**: Verify logging doesn't impact performance
+- [ ] **DB Persistence**: Use `logger.toDb()` for database-only logging if needed
+- [ ] **Environment Compliance**: Respect `VITE_LOG_LEVEL` environment
+  variable

.cursor/rules/development/planning_examples.mdc

@@ -0,0 +1,160 @@
+# Planning Examples — No Time Estimates
+
+> **Agent role**: Reference this file for detailed planning examples and
+  anti-patterns when creating project plans.
+
+## 🎯 Example Planning (No Time Estimates)
+
+### **Example 1: Simple Feature**
+
+```
+
+Phase 1: Core implementation
+
+- Basic functionality
+
+- Single platform support
+
+- Unit tests
+
+Phase 2: Platform expansion
+
+- Multi-platform support
+
+- Integration tests
+
+Phase 3: Polish
+
+- User testing
+
+- Edge case handling
+
+```
+
+### **Example 2: Complex Cross-Platform Feature**
+
+```
+
+Phase 1: Foundation
+
+- Architecture design
+
+- Core service implementation
+
+- Basic web platform support
+
+Phase 2: Platform Integration
+
+- Mobile platform support
+
+- Desktop platform support
+
+- Cross-platform consistency
+
+Phase 3: Testing & Polish
+
+- Comprehensive testing
+
+- Error handling
+
+- User experience refinement
+
+```
+
+## 🚫 Anti-Patterns to Avoid
+
+- **"This should take X days"** - Red flag for time estimation
+
+- **"Just a few hours"** - Ignores complexity and testing
+
+- **"Similar to X"** - Without considering differences
+
+- **"Quick fix"** - Nothing is ever quick in software
+
+- **"No testing needed"** - Testing always takes effort
+
+## ✅ Best Practices
+
+### **When Planning:**
+
+1. **Break down everything** - no work is too small to plan
+
+2. **Consider all platforms** - web, mobile, desktop differences
+
+3. **Include testing strategy** - unit, integration, and user testing
+
+4. **Account for unknowns** - there are always surprises
+
+5. **Focus on dependencies** - what blocks what
+
+### **When Presenting Plans:**
+
+1. **Show the phases** - explain the logical progression
+
+2. **Highlight dependencies** - what could block progress
+
+3. **Define milestones** - clear success criteria
+
+4. **Identify risks** - what could go wrong
+
+5. **Suggest alternatives** - ways to reduce scope or complexity
+
+## 🔄 Continuous Improvement
+
+### **Track Progress**
+
+- Record planned vs. actual phases completed
+
+- Identify what took longer than expected
+
+- Learn from complexity misjudgments
+
+- Adjust planning process based on experience
+
+### **Learn from Experience**
+
+- **Underestimated complexity**: Increase complexity categories
+
+- **Missed dependencies**: Improve dependency mapping
+
+- **Platform surprises**: Better platform research upfront
+
+## 🎯 Integration with Harbor Pilot
+
+This rule works in conjunction with:
+
+- **Project Planning**: Focuses on phases and milestones
+
+- **Resource Allocation**: Based on complexity, not time
+
+- **Risk Management**: Identifies blockers and dependencies
+
+- **Stakeholder Communication**: Sets progress-based expectations
+
+---
+
+**See also**: `.cursor/rules/development/realistic_time_estimation.mdc` for
+  the core principles and framework.
+
+## Model Implementation Checklist
+
+### Before Planning
+
+- [ ] **Requirements Review**: Understand all requirements completely
+- [ ] **Stakeholder Input**: Gather input from all stakeholders
+- [ ] **Complexity Assessment**: Evaluate technical and business complexity
+- [ ] **Platform Analysis**: Consider requirements across all target platforms
+
+### During Planning
+
+- [ ] **Phase Definition**: Define clear phases and milestones
+- [ ] **Dependency Mapping**: Map dependencies between tasks
+- [ ] **Risk Identification**: Identify potential risks and challenges
+- [ ] **Testing Strategy**: Plan comprehensive testing approach
+
+### After Planning
+
+- [ ] **Stakeholder Review**: Review plan with stakeholders
+- [ ] **Documentation**: Document plan clearly with phases and milestones
+- [ ] **Team Communication**: Communicate plan to team
+- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms

.cursor/rules/development/realistic_time_estimation.mdc

@@ -0,0 +1,128 @@
+# Realistic Time Estimation — Development Guidelines
+
+> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases,
+> milestones, and complexity levels. Time estimates are consistently wrong
+> and create unrealistic expectations.
+
+## Purpose
+
+Development time estimates are consistently wrong and create unrealistic
+expectations. This rule ensures we focus on phases, milestones, and
+complexity rather than trying to predict specific timeframes.
+
+## Critical Rule
+
+**NEVER provide specific time estimates** (hours, days, weeks) for
+development tasks. Instead, use:
+
+- **Complexity levels** (Low, Medium, High, Critical)
+
+- **Phases and milestones** with clear acceptance criteria
+
+- **Platform-specific considerations** (Web, Mobile, Desktop)
+
+- **Testing requirements** and validation steps
+
+## Planning Framework
+
+### Complexity Assessment
+
+- **Low**: Simple changes, existing patterns, minimal testing
+
+- **Medium**: New features, moderate testing, some integration
+
+- **High**: Complex features, extensive testing, multiple platforms
+
+- **Critical**: Core architecture changes, full regression testing
+
+### Platform Categories
+
+- **Web**: Browser compatibility, responsive design, accessibility
+
+- **Mobile**: Native APIs, platform-specific testing, deployment
+
+- **Desktop**: Electron integration, system APIs, distribution
+
+### Testing Strategy
+
+- **Unit tests**: Core functionality validation
+
+- **Integration tests**: Component interaction testing
+
+- **E2E tests**: User workflow validation
+
+- **Platform tests**: Cross-platform compatibility
+
+## Process Guidelines
+
+### Planning Phase
+
+1. **Scope Definition**: Clear requirements and acceptance criteria
+
+2. **Complexity Assessment**: Evaluate technical and business complexity
+
+3. **Phase Breakdown**: Divide into logical, testable phases
+
+4. **Milestone Definition**: Define success criteria for each phase
+
+### Execution Phase
+
+1. **Phase 1**: Foundation and core implementation
+
+2. **Phase 2**: Feature completion and integration
+
+3. **Phase 3**: Testing, refinement, and documentation
+
+4. **Phase 4**: Deployment and validation
+
+### Validation Phase
+
+1. **Acceptance Testing**: Verify against defined criteria
+
+2. **Platform Testing**: Validate across target platforms
+
+3. **Performance Testing**: Ensure performance requirements met
+
+4. **Documentation**: Update relevant documentation
+
+## Remember
+
+**Your first estimate is wrong. Your second estimate is probably still
+wrong. Focus on progress, not deadlines.**
+
+---
+
+**See also**:
+
+- `.cursor/rules/development/planning_examples.mdc` for detailed planning examples
+
+- `.cursor/rules/development/complexity_assessment.mdc` for complexity evaluation
+
+**Status**: Active development guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Development team, Project managers
+
+## Model Implementation Checklist
+
+### Before Time Estimation
+
+- [ ] **Requirements Analysis**: Understand all requirements and acceptance criteria
+- [ ] **Complexity Assessment**: Evaluate technical and business complexity
+- [ ] **Platform Review**: Identify requirements across all target platforms
+- [ ] **Stakeholder Input**: Gather input from all affected parties
+
+### During Time Estimation
+
+- [ ] **Phase Breakdown**: Divide work into logical, testable phases
+- [ ] **Complexity Classification**: Assign complexity levels (Low/Medium/High/Critical)
+- [ ] **Platform Considerations**: Account for platform-specific requirements
+- [ ] **Testing Strategy**: Plan comprehensive testing approach
+
+### After Time Estimation
+
+- [ ] **Milestone Definition**: Define success criteria for each phase
+- [ ] **Progress Tracking**: Set up monitoring and tracking mechanisms
+- [ ] **Documentation**: Document estimation process and assumptions
+- [ ] **Stakeholder Communication**: Share estimation approach and progress focus

.cursor/rules/development/research_diagnostic.mdc

@@ -1,8 +1,12 @@
 ---
-description: Use this workflow when doing **pre-implementation research, defect investigations with uncertain repros, or clarifying system architecture and behaviors**.
+description: Use this workflow when doing **pre-implementation research, defect
+  investigations with uncertain repros, or clarifying system architecture and
+  behaviors**.
 alwaysApply: false
 ---
+
 ```json
+
 {
   "coaching_level": "light",
   "socratic_max_questions": 2,
@@ -10,6 +14,7 @@ alwaysApply: false
   "timebox_minutes": null,
   "format_enforcement": "strict"
 }
+
 ```
 
 # Research & Diagnostic Workflow (R&D)
@@ -23,7 +28,9 @@ steps—**not** code changes.
 ## When to Use
 
 - Pre-implementation research for new features
+
 - Defect investigations (repros uncertain, user-specific failures)
+
 - Architecture/behavior clarifications (e.g., auth flows, merges, migrations)
 
 ---
@@ -33,7 +40,9 @@ steps—**not** code changes.
 When investigating software issues, also apply:
 
 - **Code Path Tracing**: Required for technical investigations
+
 - **Evidence Validation**: Ensure claims are code-backed
+
 - **Solution Complexity Assessment**: Justify architectural changes
 
 ---
@@ -60,48 +69,73 @@ When investigating software issues, also apply:
 Copy/paste and fill:
 
 ```md
+
 # Investigation — <short title>
 
 ## Objective
+
 <one or two lines>
 
 ## System Map
+
 - <module> → <function> → <downstream>
+
 - <data path> → <db table> → <api>
 
 ## Findings (Evidence)
-- <claim> — evidence: `src/path/file.ts:function` (lines X–Y); log snippet/trace id
+
+- <claim> — 
+
+  evidence: `src/path/file.ts:function` (lines X–Y); log snippet/trace id
+
 - <claim> — evidence: `...`
 
 ## Hypotheses & Failure Modes
+
 - H1: <hypothesis>; would fail when <condition>
+
 - H2: <hypothesis>; watch for <signal>
 
 ## Corrections
+
 - Updated: <old statement> → <new statement with evidence>
 
 ## Diagnostics (Next Checks)
+
 - [ ] Repro on <platform/version>
+
 - [ ] Inspect <table/store> for <record>
+
 - [ ] Capture <log/trace>
 
 ## Risks & Scope
+
 - Impacted: <areas/components>; Data: <tables/keys>; Users: <segments>
 
 ## Decision / Next Steps
+
 - Owner: <name>; By: <date> (YYYY-MM-DD)
+
 - Action: <spike/bugfix/ADR>; Exit criteria: <binary checks>
 
 ## References
+
 - `src/...`
+
 - ADR: `docs/adr/xxxx-yy-zz-something.md`
+
 - Design: `docs/...`
 
 ## Competence Hooks
+
 - Why this works: <≤3 bullets>
+
 - Common pitfalls: <≤3 bullets>
+
 - Next skill: <≤1 item>
+
 - Teach-back: "<one question>"
+
 ```
 
 ---
@@ -109,8 +143,13 @@ Copy/paste and fill:
 ## Evidence Quality Bar
 
 - **Cite the source** (file:func, line range if possible).
+
 - **Prefer primary evidence** (code, logs) over inference.
-- **Disambiguate platform** (Web/Capacitor/Electron) and **state** (migration, auth).
+
+- **Disambiguate platform** (Web/Capacitor/Electron) and **state** (migration,
+
+  auth).
+
 - **Note uncertainty** explicitly.
 
 ---
@@ -119,10 +158,16 @@ Copy/paste and fill:
 
 Before proposing solutions, trace the actual execution path:
 
-- [ ] **Entry Points**: Identify where the flow begins (user action, API call, etc.)
+- [ ] **Entry Points**:
+
+  Identify where the flow begins (user action, API call, etc.)
+
 - [ ] **Component Flow**: Map which components/methods are involved
+
 - [ ] **Data Path**: Track how data moves through the system
+
 - [ ] **Exit Points**: Confirm where the flow ends and what results
+
 - [ ] **Evidence Collection**: Gather specific code citations for each step
 
 ---
@@ -130,7 +175,9 @@ Before proposing solutions, trace the actual execution path:
 ## Collaboration Hooks
 
 - **Syncs:** 10–15m with QA/Security/Platform owners for high-risk areas.
+
 - **ADR:** Record major decisions; link here.
+
 - **Review:** Share repro + diagnostics checklist in PR/issue.
 
 ---
@@ -139,13 +186,20 @@ Before proposing solutions, trace the actual execution path:
 
 ### With software_development.mdc
 
-- **Enhanced Evidence Validation**: Use code path tracing for technical investigations
+- **Enhanced Evidence Validation**:
-- **Architecture Assessment**: Apply complexity justification to proposed solutions
+
+  Use code path tracing for technical investigations
+
+- **Architecture Assessment**:
+
+  Apply complexity justification to proposed solutions
+
 - **Impact Analysis**: Assess effects on existing systems before recommendations
 
 ### With base_context.mdc
 
 - **Competence Building**: Focus on technical investigation skills
+
 - **Collaboration**: Structure outputs for team review and discussion
 
 ---
@@ -153,11 +207,17 @@ Before proposing solutions, trace the actual execution path:
 ## Self-Check (model, before responding)
 
 - [ ] Output matches the **Output Contract** sections.
+
 - [ ] Each claim has **evidence** or **uncertainty** is flagged.
+
 - [ ] Hypotheses are testable; diagnostics are actionable.
+
 - [ ] Competence + collaboration hooks present (≤120 words total).
+
 - [ ] Respect toggles; keep it concise.
+
 - [ ] **Code path traced** (for software investigations).
+
 - [ ] **Evidence validated** against actual code execution.
 
 ---
@@ -166,9 +226,37 @@ Before proposing solutions, trace the actual execution path:
 
 > Uncomment `globs` in the header if you want auto-attach behavior.
 
-- `src/platforms/**`, `src/services/**` — attach during service/feature investigations
+- `src/platforms/**`, `src/services/**` —
+
+  attach during service/feature investigations
+
 - `docs/adr/**` — attach when editing ADRs
 
 ## Referenced Files
 
-- Consider including templates as context: `@adr_template.mdc`, `@investigation_report_example.mdc`
+- Consider including templates as context: `@adr_template.mdc`,
+
+  `@investigation_report_example.mdc`
+
+## Model Implementation Checklist
+
+### Before Investigation
+
+- [ ] **Problem Definition**: Clearly define the research question or issue
+- [ ] **Scope Definition**: Determine investigation scope and boundaries
+- [ ] **Methodology Planning**: Plan investigation approach and methods
+- [ ] **Resource Assessment**: Identify required resources and tools
+
+### During Investigation
+
+- [ ] **Evidence Collection**: Gather relevant evidence and data systematically
+- [ ] **Code Path Tracing**: Map execution flow for software investigations
+- [ ] **Analysis**: Analyze evidence using appropriate methods
+- [ ] **Documentation**: Document investigation process and findings
+
+### After Investigation
+
+- [ ] **Synthesis**: Synthesize findings into actionable insights
+- [ ] **Report Creation**: Create comprehensive investigation report
+- [ ] **Recommendations**: Provide clear, actionable recommendations
+- [ ] **Team Communication**: Share findings and next steps with team

.cursor/rules/development/software_development.mdc

@@ -1,4 +1,9 @@
 
+---
+
+alwaysApply: false
+---
+
 # Software Development Ruleset
 
 **Author**: Matthew Raymer
@@ -15,34 +20,52 @@ debugging, architecture decisions, and testing.
 ### 1. Evidence-First Development
 
 - **Code Citations Required**: Always cite specific file:line references when
+
   making claims
+
 - **Execution Path Tracing**: Trace actual code execution before proposing
+
   architectural changes
+
 - **Assumption Validation**: Flag assumptions as "assumed" vs "evidence-based"
 
 ### 2. Code Review Standards
 
 - **Trace Before Proposing**: Always trace execution paths before suggesting
+
   changes
+
 - **Evidence Over Inference**: Prefer code citations over logical deductions
+
 - **Scope Validation**: Confirm the actual scope of problems before proposing
+
   solutions
 
 ### 3. Problem-Solution Validation
 
 - **Problem Scope**: Does the solution address the actual problem?
+
 - **Evidence Alignment**: Does the solution match the evidence?
+
 - **Complexity Justification**: Is added complexity justified by real needs?
+
 - **Alternative Analysis**: What simpler solutions were considered?
 
 ### 4. Dependency Management & Environment Validation
 
-- **Pre-build Validation**: Always validate critical dependencies before executing
+- **Pre-build Validation**:
+
+  Always validate critical dependencies before executing
   build scripts
+
 - **Environment Consistency**: Ensure team members have identical development
+
   environments
+
 - **Dependency Verification**: Check that required packages are installed and
+
   accessible
+
 - **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues
 
 ## Required Workflows
@@ -50,18 +73,27 @@ debugging, architecture decisions, and testing.
 ### Before Proposing Changes
 
 - [ ] **Code Path Tracing**: Map execution flow from entry to exit
+
 - [ ] **Evidence Collection**: Gather specific code citations and logs
+
 - [ ] **Assumption Surfacing**: Identify what's proven vs. inferred
+
 - [ ] **Scope Validation**: Confirm the actual extent of the problem
+
 - [ ] **Dependency Validation**: Verify all required dependencies are available
+
   and accessible
 
 ### During Solution Design
 
 - [ ] **Evidence Alignment**: Ensure solution addresses proven problems
+
 - [ ] **Complexity Assessment**: Justify any added complexity
+
 - [ ] **Alternative Evaluation**: Consider simpler approaches first
+
 - [ ] **Impact Analysis**: Assess effects on existing systems
+
 - [ ] **Environment Impact**: Assess how changes affect team member setups
 
 ## Software-Specific Competence Hooks
@@ -69,78 +101,53 @@ debugging, architecture decisions, and testing.
 ### Evidence Validation
 
 - **"What code path proves this claim?"**
+
 - **"How does data actually flow through the system?"**
+
 - **"What am I assuming vs. what can I prove?"**
 
 ### Code Tracing
 
 - **"What's the execution path from user action to system response?"**
+
 - **"Which components actually interact in this scenario?"**
+
 - **"Where does the data originate and where does it end up?"**
 
 ### Architecture Decisions
 
 - **"What evidence shows this change is necessary?"**
+
 - **"What simpler solution could achieve the same goal?"**
+
 - **"How does this change affect the existing system architecture?"**
 
 ### Dependency & Environment Management
 
 - **"What dependencies does this feature require and are they properly
+
   declared?"**
+
 - **"How will this change affect team member development environments?"**
+
 - **"What validation can we add to catch dependency issues early?"**
 
-## Dependency Management Best Practices
-
-### Pre-build Validation
-
-- **Check Critical Dependencies**: Validate essential tools before executing build
-  scripts
-- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to
-  avoid PATH issues
-- **Environment Consistency**: Ensure all team members have identical dependency
-  versions
-
-### Common Pitfalls
-
-- **Missing npm install**: Team members cloning without running `npm install`
-- **PATH Issues**: Direct command execution vs. npm script execution differences
-- **Version Mismatches**: Different Node.js/npm versions across team members
-
-### Validation Strategies
-
-- **Dependency Check Scripts**: Implement pre-build validation for critical
-  dependencies
-- **Environment Requirements**: Document and enforce minimum Node.js/npm versions
-- **Onboarding Checklist**: Standardize team member setup procedures
-
-### Error Messages and Guidance
-
-- **Specific Error Context**: Provide clear guidance when dependency issues occur
-- **Actionable Solutions**: Direct users to specific commands (`npm install`,
-  `npm run check:dependencies`)
-- **Environment Diagnostics**: Implement comprehensive environment validation
-  tools
-
-### Build Script Enhancements
-
-- **Early Validation**: Check dependencies before starting build processes
-- **Graceful Degradation**: Continue builds when possible but warn about issues
-- **Helpful Tips**: Remind users about dependency management best practices
-
 ## Integration with Other Rulesets
 
 ### With base_context.mdc
 
 - Inherits generic competence principles
+
 - Adds software-specific evidence requirements
+
 - Maintains collaboration and learning focus
 
 ### With research_diagnostic.mdc
 
 - Enhances investigation with code path tracing
+
 - Adds evidence validation to diagnostic workflow
+
 - Strengthens problem identification accuracy
 
 ## Usage Guidelines
@@ -148,78 +155,73 @@ debugging, architecture decisions, and testing.
 ### When to Use This Ruleset
 
 - Code reviews and architectural decisions
+
 - Bug investigation and debugging
+
 - Performance optimization
+
 - Feature implementation planning
+
 - Testing strategy development
 
 ### When to Combine with Others
 
 - **base_context + software_development**: General development tasks
+
 - **research_diagnostic + software_development**: Technical investigations
+
 - **All three**: Complex architectural decisions or major refactoring
 
 ## Self-Check (model, before responding)
 
 - [ ] Code path traced and documented
+
 - [ ] Evidence cited with specific file:line references
+
 - [ ] Assumptions clearly flagged as proven vs. inferred
+
 - [ ] Solution complexity justified by evidence
+
 - [ ] Simpler alternatives considered and documented
+
 - [ ] Impact on existing systems assessed
+
 - [ ] Dependencies validated and accessible
+
 - [ ] Environment impact assessed for team members
+
 - [ ] Pre-build validation implemented where appropriate
 
-## Additional Core Principles
+---
 
-### 4. Dependency Management & Environment Validation
+**See also**: `.cursor/rules/development/dependency_management.mdc` for
-- **Pre-build Validation**: Always validate critical dependencies before executing build scripts
+  detailed dependency management practices.
-- **Environment Consistency**: Ensure team members have identical development environments
-- **Dependency Verification**: Check that required packages are installed and accessible
-- **Path Resolution**: Use `npx` for local dependencies to avoid PATH issues
 
-## Additional Required Workflows
+**Status**: Active development guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: base_context.mdc, research_diagnostic.mdc
+**Stakeholders**: Development team, Code review team
 
-### Dependency Validation (Before Proposing Changes)
+## Model Implementation Checklist
-- [ ] **Dependency Validation**: Verify all required dependencies are available and accessible
 
-### Environment Impact Assessment (During Solution Design)
+### Before Development Work
+
+- [ ] **Code Path Tracing**: Map execution flow from entry to exit
+- [ ] **Evidence Collection**: Gather specific code citations and logs
+- [ ] **Assumption Surfacing**: Identify what's proven vs. inferred
+- [ ] **Scope Validation**: Confirm the actual extent of the problem
+
+### During Development
+
+- [ ] **Evidence Alignment**: Ensure solution addresses proven problems
+- [ ] **Complexity Assessment**: Justify any added complexity
+- [ ] **Alternative Evaluation**: Consider simpler approaches first
+- [ ] **Impact Analysis**: Assess effects on existing systems
+
+### After Development
+
+- [ ] **Code Path Validation**: Verify execution paths are correct
+- [ ] **Evidence Documentation**: Document all code citations and evidence
+- [ ] **Assumption Review**: Confirm all assumptions are documented
 - [ ] **Environment Impact**: Assess how changes affect team member setups
-
-## Additional Competence Hooks
-
-### Dependency & Environment Management
-- **"What dependencies does this feature require and are they properly declared?"**
-- **"How will this change affect team member development environments?"**
-- **"What validation can we add to catch dependency issues early?"**
-
-## Dependency Management Best Practices
-
-### Pre-build Validation
-- **Check Critical Dependencies**: Validate essential tools before executing build scripts
-- **Use npx for Local Dependencies**: Prefer `npx tsx` over direct `tsx` to avoid PATH issues
-- **Environment Consistency**: Ensure all team members have identical dependency versions
-
-### Common Pitfalls
-- **Missing npm install**: Team members cloning without running `npm install`
-- **PATH Issues**: Direct command execution vs. npm script execution differences
-- **Version Mismatches**: Different Node.js/npm versions across team members
-
-### Validation Strategies
-- **Dependency Check Scripts**: Implement pre-build validation for critical dependencies
-- **Environment Requirements**: Document and enforce minimum Node.js/npm versions
-- **Onboarding Checklist**: Standardize team member setup procedures
-
-### Error Messages and Guidance
-- **Specific Error Context**: Provide clear guidance when dependency issues occur
-- **Actionable Solutions**: Direct users to specific commands (`npm install`, `npm run check:dependencies`)
-- **Environment Diagnostics**: Implement comprehensive environment validation tools
-
-### Build Script Enhancements
-- **Early Validation**: Check dependencies before starting build processes
-- **Graceful Degradation**: Continue builds when possible but warn about issues
-- **Helpful Tips**: Remind users about dependency management best practices
-
-- **Narrow Types Properly**: Use type guards to narrow `unknown` types safely
-- **Document Type Decisions**: Explain complex type structures and their purpose

.cursor/rules/development/time.mdc

@@ -0,0 +1,146 @@
+# Time Handling in Development Workflow
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-17
+**Status**: 🎯 **ACTIVE** - Production Ready
+
+## Overview
+
+This guide establishes **how time should be referenced and used** across the
+development workflow. It is not tied to any one project, but applies to **all
+feature development, issue investigations, ADRs, and documentation**.
+
+## General Principles
+
+- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over
+
+  relative references like "last week."
+
+- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in
+
+  docs, issues, ADRs, and commits.
+
+- **Time zones**: Default to **UTC** unless explicitly tied to user-facing
+
+  behavior.
+
+- **Precision**: Only specify as much precision as needed (date vs. datetime vs.
+
+  timestamp).
+
+- **Consistency**: Align time references across ADRs, commits, and investigation
+
+  reports.
+
+## In Documentation & ADRs
+
+- Record decision dates using **absolute ISO dates**.
+
+- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` →
+
+  `2025-08-17`).
+
+- Avoid ambiguous terms like *recently*, *last month*, or *soon*.
+
+- For time-based experiments (e.g., A/B tests), always include:
+
+  - Start date
+
+  - Expected duration
+
+  - Review date checkpoint
+
+## In Code & Commits
+
+- Use **UTC timestamps** in logs, DB migrations, and serialized formats.
+
+- In commits, link changes to **date-bound ADRs or investigation docs**.
+
+- For migrations, include both **applied date** and **intended version window**.
+
+- Use constants for known fixed dates; avoid hardcoding arbitrary strings.
+
+## In Investigations & Research
+
+- Capture **when** an issue occurred (absolute time or version tag).
+
+- When describing failures: note whether they are **time-sensitive** (e.g.,
+
+  after
+  migrations, cache expirations).
+
+- Record diagnostic timelines in ISO format (not relative).
+
+- For performance regressions, annotate both **baseline timeframe** and
+
+  **measurement timeframe**.
+
+## Collaboration Hooks
+
+- During reviews, verify **time references are clear, absolute, and
+
+  standardized**.
+
+- In syncs, reframe relative terms ("this week") into shared absolute
+
+  references.
+
+- Tag ADRs with both **date created** and **review by** checkpoints.
+
+## Self-Check Before Submitting
+
+- [ ] Did I check the time using the **developer's actual system time and
+
+      timezone**?
+
+- [ ] Am I using absolute ISO dates?
+
+- [ ] Is UTC assumed unless specified otherwise?
+
+- [ ] Did I avoid ambiguous relative terms?
+
+- [ ] If duration matters, did I specify both start and end?
+
+- [ ] For future work, did I include a review/revisit date?
+
+---
+
+**See also**:
+
+- `.cursor/rules/development/time_implementation.mdc` for
+
+  detailed implementation instructions
+
+- `.cursor/rules/development/time_examples.mdc` for practical examples and patterns
+
+**Status**: Active time handling guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Development team, Documentation team
+
+**Maintainer**: Matthew Raymer
+**Next Review**: 2025-09-17
+
+## Model Implementation Checklist
+
+### Before Time-Related Work
+
+- [ ] **Time Context**: Understand what time information is needed
+- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601)
+- [ ] **Platform Check**: Identify platform-specific time requirements
+- [ ] **User Context**: Consider user's timezone and preferences
+
+### During Time Implementation
+
+- [ ] **UTC Usage**: Use UTC for all system and log timestamps
+- [ ] **Format Consistency**: Apply consistent time formatting patterns
+- [ ] **Timezone Handling**: Properly handle timezone conversions
+- [ ] **User Display**: Format times appropriately for user display
+
+### After Time Implementation
+
+- [ ] **Validation**: Verify time formats are correct and consistent
+- [ ] **Testing**: Test time handling across different scenarios
+- [ ] **Documentation**: Update relevant documentation with time patterns
+- [ ] **Review**: Confirm implementation follows time standards

.cursor/rules/development/time_examples.mdc

@@ -0,0 +1,243 @@
+# Time Examples — Practical Patterns
+
+> **Agent role**: Reference this file for practical examples and
+  patterns when working with time handling in development.
+
+## Examples
+
+### Good
+
+- "Feature flag rollout started on `2025-08-01` and will be reviewed on
+
+  `2025-08-21`."
+
+- "Migration applied on `2025-07-15T14:00Z`."
+
+- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` /
+
+  `2025-08-17T14:00Z (UTC)`."
+
+### Bad
+
+- "Feature flag rolled out last week."
+
+- "Migration applied recently."
+
+- "Now is August, so we assume this was last month."
+
+### More Examples
+
+#### Issue Reports
+
+- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue
+
+  persisted until `2025-08-17T15:45:00Z`."
+
+- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a
+
+  while."
+
+#### Release Planning
+
+- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing
+
+  window: `2025-08-20` to `2025-08-24`."
+
+- ❌ **Bad**: "Feature X will be released next week after testing."
+
+#### Performance Monitoring
+
+- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`.
+
+  Regression detected on `2025-08-15T14:00:00Z`."
+
+- ❌ **Bad**: "Performance was good last week but got worse this week."
+
+## Technical Implementation Examples
+
+### Database Storage
+
+```sql
+
+-- ✅ Good: Store in UTC
+created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+
+-- ❌ Bad: Store in local time
+created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+
+```
+
+### API Responses
+
+```json
+
+// ✅ Good: Include both UTC and local time
+{
+  "eventTime": "2025-08-17T14:00:00Z",
+  "localTime": "2025-08-17T10:00:00-04:00",
+  "timezone": "America/New_York"
+}
+
+// ❌ Bad: Only local time
+{
+  "eventTime": "2025-08-17T10:00:00-04:00"
+}
+
+```
+
+### Logging
+
+```python
+
+# ✅ Good: Log in UTC with timezone info
+
+logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)")
+
+# ❌ Bad: Log in local time
+
+logger.info(f"User action at {datetime.now()}")
+
+```
+
+## Timezone Handling Examples
+
+### Good Timezone Usage
+
+```typescript
+
+// ✅ Good: Store UTC, convert for display
+const eventTime = new Date().toISOString(); // Store in UTC
+const localTime = new Date().toLocaleString('en-US', {
+  timeZone: 'America/New_York'
+}); // Convert for display
+
+// ✅ Good: Include timezone context
+const timestamp = {
+  utc: "2025-08-17T14:00:00Z",
+  local: "2025-08-17T10:00:00-04:00",
+  timezone: "America/New_York"
+};
+
+```
+
+### Bad Timezone Usage
+
+```typescript
+
+// ❌ Bad: Assume timezone
+const now = new Date(); // Assumes system timezone
+
+// ❌ Bad: Mix formats
+const timestamp = "2025-08-17 10:00 AM"; // Ambiguous format
+
+```
+
+## Common Patterns
+
+### Date Range References
+
+```typescript
+
+// ✅ Good: Explicit date ranges
+const dateRange = {
+  start: "2025-08-01T00:00:00Z",
+  end: "2025-08-31T23:59:59Z"
+};
+
+// ❌ Bad: Relative ranges
+const dateRange = {
+  start: "beginning of month",
+  end: "end of month"
+};
+
+```
+
+### Duration References
+
+```typescript
+
+// ✅ Good: Specific durations
+const duration = {
+  value: 30,
+  unit: "days",
+  startDate: "2025-08-01T00:00:00Z"
+};
+
+// ❌ Bad: Vague durations
+const duration = "about a month";
+
+```
+
+### Version References
+
+```typescript
+
+// ✅ Good: Version with date
+const version = {
+  number: "1.2.3",
+  releaseDate: "2025-08-17T10:00:00Z",
+  buildDate: "2025-08-17T09:30:00Z"
+};
+
+// ❌ Bad: Version without context
+const version = "latest";
+
+```
+
+## References
+
+- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601)
+
+- [IANA Timezone Database](https://www.iana.org/time-zones)
+
+- [ADR Template](./adr_template.md)
+
+- [Research & Diagnostic Workflow](./research_diagnostic.mdc)
+
+---
+
+**Rule of Thumb**: Every time reference in development artifacts should be
+**clear in 6 months without context**, and aligned to the **developer's actual
+current time**.
+
+**Technical Rule of Thumb**: **Store in UTC, display in local time, always
+include timezone context.**
+
+---
+
+**See also**:
+
+- `.cursor/rules/development/time.mdc` for core principles
+
+- `.cursor/rules/development/time_implementation.mdc` for implementation instructions
+
+**Status**: Active examples and patterns
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: time.mdc, time_implementation.mdc
+**Stakeholders**: Development team, Documentation team
+
+## Model Implementation Checklist
+
+### Before Time Implementation
+
+- [ ] **Time Context**: Understand what time information needs to be implemented
+- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601)
+- [ ] **Platform Check**: Identify platform-specific time requirements
+- [ ] **User Context**: Consider user's timezone and display preferences
+
+### During Time Implementation
+
+- [ ] **UTC Storage**: Use UTC for all system and log timestamps
+- [ ] **Format Consistency**: Apply consistent time formatting patterns
+- [ ] **Timezone Handling**: Properly handle timezone conversions
+- [ ] **User Display**: Format times appropriately for user display
+
+### After Time Implementation
+
+- [ ] **Format Validation**: Verify time formats are correct and consistent
+- [ ] **Cross-Platform Testing**: Test time handling across different platforms
+- [ ] **Documentation**: Update relevant documentation with time patterns
+- [ ] **User Experience**: Confirm time display is clear and user-friendly

.cursor/rules/development/time_implementation.mdc

@@ -1,91 +1,28 @@
----
+# Time Implementation — Technical Instructions
-alwaysApply: true
----
-# Time Handling in Development Workflow
 
-**Author**: Matthew Raymer
+> **Agent role**: Reference this file for detailed implementation instructions
-**Date**: 2025-08-17
+  when working with time handling in development.
-**Status**: 🎯 **ACTIVE** - Production Ready
-
-## Overview
-
-This guide establishes **how time should be referenced and used** across the
-development workflow. It is not tied to any one project, but applies to **all
-feature development, issue investigations, ADRs, and documentation**.
-
-## General Principles
-
-- **Explicit over relative**: Always prefer absolute dates (`2025-08-17`) over
-  relative references like "last week."
-- **ISO 8601 Standard**: Use `YYYY-MM-DD` format for all date references in
-  docs, issues, ADRs, and commits.
-- **Time zones**: Default to **UTC** unless explicitly tied to user-facing
-  behavior.
-- **Precision**: Only specify as much precision as needed (date vs. datetime vs.
-  timestamp).
-- **Consistency**: Align time references across ADRs, commits, and investigation
-  reports.
-
-## In Documentation & ADRs
-
-- Record decision dates using **absolute ISO dates**.
-- For ongoing timelines, state start and end explicitly (e.g., `2025-08-01` →
-  `2025-08-17`).
-- Avoid ambiguous terms like *recently*, *last month*, or *soon*.
-- For time-based experiments (e.g., A/B tests), always include:
-
-  - Start date
-  - Expected duration
-  - Review date checkpoint
-
-## In Code & Commits
-
-- Use **UTC timestamps** in logs, DB migrations, and serialized formats.
-- In commits, link changes to **date-bound ADRs or investigation docs**.
-- For migrations, include both **applied date** and **intended version window**.
-- Use constants for known fixed dates; avoid hardcoding arbitrary strings.
-
-## In Investigations & Research
-
-- Capture **when** an issue occurred (absolute time or version tag).
-- When describing failures: note whether they are **time-sensitive** (e.g., after
-  migrations, cache expirations).
-- Record diagnostic timelines in ISO format (not relative).
-- For performance regressions, annotate both **baseline timeframe** and
-  **measurement timeframe**.
-
-## Collaboration Hooks
-
-- During reviews, verify **time references are clear, absolute, and
-  standardized**.
-- In syncs, reframe relative terms ("this week") into shared absolute
-  references.
-- Tag ADRs with both **date created** and **review by** checkpoints.
-
-## Self-Check Before Submitting
-
-- [ ] Did I check the time using the **developer's actual system time and
-      timezone**?
-- [ ] Am I using absolute ISO dates?
-- [ ] Is UTC assumed unless specified otherwise?
-- [ ] Did I avoid ambiguous relative terms?
-- [ ] If duration matters, did I specify both start and end?
-- [ ] For future work, did I include a review/revisit date?
 
 ## Real-Time Context in Developer Interactions
 
 - The model must always resolve **"current time"** using the **developer's
+
   actual system time and timezone**.
+
 - When generating timestamps (e.g., in investigation logs, ADRs, or examples),
+
   the model should:
 
   - Use the **developer's current local time** by default.
+
   - Indicate the timezone explicitly (e.g., `2025-08-17T10:32-05:00`).
+
   - Optionally provide UTC alongside if context requires cross-team clarity.
 
 - When interpreting relative terms like *now*, *today*, *last week*:
 
   - Resolve them against the **developer's current time**.
+
   - Convert them into **absolute ISO-8601 values** in the output.
 
 ## LLM Time Checking Instructions
@@ -98,15 +35,21 @@ than assuming or inventing times.
 #### 1. **Query System Time (Required)**
 
 - **Always start** by querying the current system time using available tools
+
 - **Never assume** what the current time is
+
 - **Never use** placeholder values like "current time" or "now"
 
 #### 2. **Available Time Query Methods**
 
 - **System Clock**: Use `date` command or equivalent system time function
+
 - **Programming Language**: Use language-specific time functions (e.g.,
+
   `Date.now()`, `datetime.now()`)
+
 - **Environment Variables**: Check for time-related environment variables
+
 - **API Calls**: Use time service APIs if available
 
 #### 3. **Required Time Information**
@@ -114,53 +57,75 @@ than assuming or inventing times.
 When querying time, always obtain:
 
 - **Current Date**: YYYY-MM-DD format
+
 - **Current Time**: HH:MM:SS format (24-hour)
+
 - **Timezone**: Current system timezone or UTC offset
+
 - **UTC Equivalent**: Convert local time to UTC for cross-team clarity
 
 #### 4. **Time Query Examples**
 
 ```bash
+
 # Example: Query system time
+
 $ date
+
 # Expected output: Mon Aug 17 10:32:45 EDT 2025
 
 # Example: Query UTC time
+
 $ date -u
+
 # Expected output: Mon Aug 17 14:32:45 UTC 2025
+
 ```
 
 ```python
+
 # Example: Python time query
+
 import datetime
 current_time = datetime.datetime.now()
 utc_time = datetime.datetime.utcnow()
 print(f"Local: {current_time}")
 print(f"UTC: {utc_time}")
+
 ```
 
 ```javascript
+
 // Example: JavaScript time query
 const now = new Date();
 const utc = new Date().toISOString();
 console.log(`Local: ${now}`);
 console.log(`UTC: ${utc}`);
+
 ```
 
 #### 5. **LLM Time Checking Workflow**
 
 1. **Query**: Actively query system for current time
+
 2. **Validate**: Confirm time data is reasonable and current
+
 3. **Format**: Convert to ISO 8601 format
+
 4. **Context**: Provide both local and UTC times when helpful
+
 5. **Document**: Show the source of time information
 
 #### 6. **Error Handling for Time Queries**
 
 - **If time query fails**: Ask user for current time or use "unknown time"
+
   with explanation
+
 - **If timezone unclear**: Default to UTC and ask for clarification
+
 - **If time seems wrong**: Verify with user before proceeding
+
 - **Always log**: Record when and how time was obtained
 
 #### 7. **Time Query Verification**
@@ -168,64 +133,37 @@ console.log(`UTC: ${utc}`);
 Before using queried time, verify:
 
 - [ ] Time is recent (within last few minutes)
+
 - [ ] Timezone information is available
+
 - [ ] UTC conversion is accurate
+
 - [ ] Format follows ISO 8601 standard
 
 ## Model Behavior Rules
 
 - **Never invent a "fake now"**: All "current time" references must come from
+
   the real system clock available at runtime.
+
 - **Check developer time zone**: If ambiguous, ask for clarification (e.g.,
+
   "Should I use UTC or your local timezone?").
+
 - **Format for clarity**:
 
   - Local time: `YYYY-MM-DDTHH:mm±hh:mm`
+
   - UTC equivalent (if needed): `YYYY-MM-DDTHH:mmZ`
 
-## Examples
-
-### Good
-
-- "Feature flag rollout started on `2025-08-01` and will be reviewed on
-  `2025-08-21`."
-- "Migration applied on `2025-07-15T14:00Z`."
-- "Issue reproduced on `2025-08-17T09:00-05:00 (local)` /
-  `2025-08-17T14:00Z (UTC)`."
-
-### Bad
-
-- "Feature flag rolled out last week."
-- "Migration applied recently."
-- "Now is August, so we assume this was last month."
-
-### More Examples
-
-#### Issue Reports
-
-- ✅ **Good**: "User reported login failure at `2025-08-17T14:30:00Z`. Issue
-  persisted until `2025-08-17T15:45:00Z`."
-- ❌ **Bad**: "User reported login failure earlier today. Issue lasted for a
-  while."
-
-#### Release Planning
-
-- ✅ **Good**: "Feature X scheduled for release on `2025-08-25`. Testing
-  window: `2025-08-20` to `2025-08-24`."
-- ❌ **Bad**: "Feature X will be released next week after testing."
-
-#### Performance Monitoring
-
-- ✅ **Good**: "Baseline performance measured on `2025-08-10T09:00:00Z`.
-  Regression detected on `2025-08-15T14:00:00Z`."
-- ❌ **Bad**: "Performance was good last week but got worse this week."
-
 ## Technical Implementation Notes
 
 ### UTC Storage Principle
 
 - **Store all timestamps in UTC** in databases, logs, and serialized formats
+
 - **Convert to local time only for user display**
+
 - **Use ISO 8601 format** for all storage: `YYYY-MM-DDTHH:mm:ss.sssZ`
 
 ### Common Implementation Patterns
@@ -233,18 +171,17 @@ Before using queried time, verify:
 #### Database Storage
 
 ```sql
+
 -- ✅ Good: Store in UTC
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
 
--- ❌ Bad: Store in local time
-created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
 ```
 
 #### API Responses
 
 ```json
+
 // ✅ Good: Include both UTC and local time
 {
   "eventTime": "2025-08-17T14:00:00Z",
@@ -252,20 +189,16 @@ updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
   "timezone": "America/New_York"
 }
 
-// ❌ Bad: Only local time
-{
-  "eventTime": "2025-08-17T10:00:00-04:00"
-}
 ```
 
 #### Logging
 
 ```python
+
 # ✅ Good: Log in UTC with timezone info
+
 logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)")
 
-# ❌ Bad: Log in local time
-logger.info(f"User action at {datetime.now()}")
 ```
 
 ### Timezone Handling Best Practices
@@ -273,19 +206,25 @@ logger.info(f"User action at {datetime.now()}")
 #### 1. Always Store Timezone Information
 
 - Include IANA timezone identifier (e.g., `America/New_York`)
+
 - Store UTC offset at time of creation
+
 - Handle daylight saving time transitions automatically
 
 #### 2. User Display Considerations
 
 - Convert UTC to user's preferred timezone
+
 - Show timezone abbreviation when helpful
+
 - Use relative time for recent events ("2 hours ago")
 
 #### 3. Edge Case Handling
 
 - **Daylight Saving Time**: Use timezone-aware libraries
+
 - **Leap Seconds**: Handle gracefully (rare but important)
+
 - **Invalid Times**: Validate before processing
 
 ### Common Mistakes to Avoid
@@ -293,37 +232,54 @@ logger.info(f"User action at {datetime.now()}")
 #### 1. Timezone Confusion
 
 - ❌ **Don't**: Assume server timezone is user timezone
+
 - ✅ **Do**: Always convert UTC to user's local time for display
 
 #### 2. Format Inconsistency
 
 - ❌ **Don't**: Mix different time formats in the same system
+
 - ✅ **Do**: Standardize on ISO 8601 for all storage
 
 #### 3. Relative Time References
 
 - ❌ **Don't**: Use relative terms in persistent storage
+
 - ✅ **Do**: Convert relative terms to absolute timestamps immediately
 
-## References
-
-- [ISO 8601 Date and Time Standard](https://en.wikipedia.org/wiki/ISO_8601)
-- [IANA Timezone Database](https://www.iana.org/time-zones)
-- [ADR Template](./adr_template.md)
-- [Research & Diagnostic Workflow](./research_diagnostic.mdc)
-
 ---
 
-**Rule of Thumb**: Every time reference in development artifacts should be
+**See also**:
-**clear in 6 months without context**, and aligned to the **developer's actual
-current time**.
 
-**Technical Rule of Thumb**: **Store in UTC, display in local time, always
+- `.cursor/rules/development/time.mdc` for core principles
-include timezone context.**
 
----
+- `.cursor/rules/development/time_examples.mdc` for practical examples
 
-**Status**: Active
+**Status**: Active implementation guidelines
-**Version**: 1.0
+**Priority**: Medium
-**Maintainer**: Matthew Raymer
+**Estimated Effort**: Ongoing reference
-**Next Review**: 2025-09-17
+**Dependencies**: time.mdc
+**Stakeholders**: Development team, DevOps team
+
+## Model Implementation Checklist
+
+### Before Time Implementation
+
+- [ ] **Time Context**: Understand what time information needs to be implemented
+- [ ] **Format Review**: Review time formatting standards (UTC, ISO 8601)
+- [ ] **Platform Check**: Identify platform-specific time requirements
+- [ ] **User Context**: Consider user's timezone and display preferences
+
+### During Time Implementation
+
+- [ ] **UTC Storage**: Use UTC for all system and log timestamps
+- [ ] **Format Consistency**: Apply consistent time formatting patterns
+- [ ] **Timezone Handling**: Properly handle timezone conversions
+- [ ] **User Display**: Format times appropriately for user display
+
+### After Time Implementation
+
+- [ ] **Format Validation**: Verify time formats are correct and consistent
+- [ ] **Cross-Platform Testing**: Test time handling across different platforms
+- [ ] **Documentation**: Update relevant documentation with time patterns
+- [ ] **User Experience**: Confirm time display is clear and user-friendly

.cursor/rules/development/type_safety_guide.mdc

@@ -2,7 +2,9 @@
 description: when dealing with types and Typesript
 alwaysApply: false
 ---
+
 ```json
+
 {
   "coaching_level": "light",
   "socratic_max_questions": 7,
@@ -10,6 +12,7 @@ alwaysApply: false
   "timebox_minutes": null,
   "format_enforcement": "strict"
 }
+
 ```
 
 # TypeScript Type Safety Guidelines
@@ -25,18 +28,25 @@ Practical rules to keep TypeScript strict and predictable. Minimize exceptions.
 ## Core Rules
 
 1. **No `any`**
+
    - Use explicit types. If unknown, use `unknown` and **narrow** via guards.
 
 2. **Error handling uses guards**
+
    - Reuse guards from `src/interfaces/**` (e.g., `isDatabaseError`,
+
      `isApiError`).
+
    - Catch with `unknown`; never cast to `any`.
 
 3. **Dynamic property access is type‑safe**
+
    - Use `keyof` + `in` checks:
 
      ```ts
+
      obj[k as keyof typeof obj]
+
      ```
 
    - Avoid `(obj as any)[k]`.
@@ -46,24 +56,45 @@ Practical rules to keep TypeScript strict and predictable. Minimize exceptions.
 ### Core Type Safety Rules
 
 - **No `any` Types**: Use explicit types or `unknown` with proper type guards
-- **Error Handling Uses Guards**: Implement and reuse type guards from `src/interfaces/**`
+
-- **Dynamic Property Access**: Use `keyof` + `in` checks for type-safe property access
+- **Error Handling Uses Guards**:
+
+  Implement and reuse type guards from `src/interfaces/**`
+
+- **Dynamic Property Access**:
+
+  Use `keyof` + `in` checks for type-safe property access
 
 ### Type Guard Patterns
+
 - **API Errors**: Use `isApiError(error)` guards for API error handling
-- **Database Errors**: Use `isDatabaseError(error)` guards for database operations
+
-- **Axios Errors**: Implement `isAxiosError(error)` guards for HTTP error handling
+- **Database Errors**:
+
+  Use `isDatabaseError(error)` guards for database operations
+
+- **Axios Errors**:
+
+  Implement `isAxiosError(error)` guards for HTTP error handling
 
 ### Implementation Guidelines
-- **Avoid Type Assertions**: Replace `as any` with proper type guards and interfaces
+
+- **Avoid Type Assertions**:
+
+  Replace `as any` with proper type guards and interfaces
+
 - **Narrow Types Properly**: Use type guards to narrow `unknown` types safely
+
 - **Document Type Decisions**: Explain complex type structures and their purpose
 
 ## Minimal Special Cases (document in PR when used)
 
 - **Vue refs / instances**: Use `ComponentPublicInstance` or specific
+
   component types for dynamic refs.
+
 - **3rd‑party libs without types**: Narrow immediately to a **known
+
   interface**; do not leave `any` hanging.
 
 ## Patterns (short)
@@ -71,31 +102,38 @@ Practical rules to keep TypeScript strict and predictable. Minimize exceptions.
 ### Database errors
 
 ```ts
+
 try { await this.$addContact(contact); }
 catch (e: unknown) {
   if (isDatabaseError(e) && e.message.includes("Key already exists")) {
     /* handle duplicate */
   }
 }
+
 ```
 
 ### API errors
 
 ```ts
+
 try { await apiCall(); }
 catch (e: unknown) {
   if (isApiError(e)) {
     const msg = e.response?.data?.error?.message;
   }
 }
+
 ```
 
 ### Dynamic keys
 
 ```ts
+
 const keys = Object.keys(newSettings).filter(
-  k => k in newSettings && newSettings[k as keyof typeof newSettings] !== undefined
+k => k in newSettings && newSettings[k as keyof typeof newSettings] !==
+  undefined
 );
+
 ```
 
 ## Checklists
@@ -103,28 +141,38 @@ const keys = Object.keys(newSettings).filter(
 **Before commit**
 
 - [ ] No `any` (except documented, justified cases)
+
 - [ ] Errors handled via guards
+
 - [ ] Dynamic access uses `keyof`/`in`
+
 - [ ] Imports point to correct interfaces/types
 
 **Code review**
 
 - [ ] Hunt hidden `as any`
+
 - [ ] Guard‑based error paths verified
+
 - [ ] Dynamic ops are type‑safe
+
 - [ ] Prefer existing types over re‑inventing
 
 ## Tools
 
 - `npm run lint-fix` — lint & auto‑fix
+
 - `npm run type-check` — strict type compilation (CI + pre‑release)
+
 - IDE: enable strict TS, ESLint/TS ESLint, Volar (Vue 3)
 
 ## References
 
-- TS Handbook — https://www.typescriptlang.org/docs/
+- TS Handbook — <https://www.typescriptlang.org/docs/>
-- TS‑ESLint — https://typescript-eslint.io/rules/
+
-- Vue 3 + TS — https://vuejs.org/guide/typescript/
+- TS‑ESLint — <https://typescript-eslint.io/rules/>
+
+- Vue 3 + TS — <https://vuejs.org/guide/typescript/>
 
 ---
 
@@ -134,6 +182,31 @@ const keys = Object.keys(newSettings).filter(
 **Dependencies**: TypeScript, ESLint, Vue 3
 **Stakeholders**: Development team
 
-- TS Handbook — https://www.typescriptlang.org/docs/
+- TS Handbook — <https://www.typescriptlang.org/docs/>
-- TS‑ESLint — https://typescript-eslint.io/rules/
+
-- Vue 3 + TS — https://vuejs.org/guide/typescript/
+- TS‑ESLint — <https://typescript-eslint.io/rules/>
+
+- Vue 3 + TS — <https://vuejs.org/guide/typescript/>
+
+## Model Implementation Checklist
+
+### Before Type Implementation
+
+- [ ] **Type Analysis**: Understand current type definitions and usage
+- [ ] **Interface Review**: Review existing interfaces and types
+- [ ] **Error Handling**: Plan error handling with type guards
+- [ ] **Dynamic Access**: Identify dynamic access patterns that need type safety
+
+### During Type Implementation
+
+- [ ] **Type Safety**: Ensure types provide meaningful safety guarantees
+- [ ] **Error Guards**: Implement proper error handling with type guards
+- [ ] **Dynamic Operations**: Use `keyof`/`in` for dynamic access
+- [ ] **Import Validation**: Verify imports point to correct interfaces/types
+
+### After Type Implementation
+
+- [ ] **Linting Check**: Run `npm run lint-fix` to verify code quality
+- [ ] **Type Check**: Run `npm run type-check` for strict type compilation
+- [ ] **Code Review**: Hunt for hidden `as any` and type safety issues
+- [ ] **Documentation**: Update type documentation and examples

.cursor/rules/docs/documentation.mdc

@@ -1,14 +1,37 @@
 ---
-alwaysApply: true
+alwaysApply: false
 ---
 # Directive for Documentation Generation
 
 1. Produce a **small, focused set of documents** rather than an overwhelming volume.
 2. Ensure the content is **maintainable and worth preserving**, so that humans
-are motivated to keep it up to date.
+   are motivated to keep it up to date.
 3. Prioritize **educational value**: the documents must clearly explain the
-workings of the system.
+   workings of the system.
-4. Avoid **shallow, generic, or filler explanations** often found in
+4. Avoid **shallow, generic, or filler explanations** often found in AI-generated
-AI-generated documentation.
+   documentation.
 5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding.
 6. Always check the local system date to determine current date.
+
+## Model Implementation Checklist
+
+### Before Documentation Creation
+
+- [ ] **Scope Definition**: Define what needs to be documented
+- [ ] **Audience Analysis**: Identify target readers and their needs
+- [ ] **Content Planning**: Plan focused, educational content structure
+- [ ] **Maintenance Planning**: Ensure content will be worth preserving
+
+### During Documentation Creation
+
+- [ ] **Educational Focus**: Clearly explain how the system works
+- [ ] **Depth and Clarity**: Provide genuine understanding, not surface explanations
+- [ ] **Focused Content**: Keep documents small and focused on specific topics
+- [ ] **Current Date**: Check local system date for time-sensitive content
+
+### After Documentation Creation
+
+- [ ] **Quality Review**: Ensure content is clear, deep, and useful
+- [ ] **Maintainability Check**: Verify content motivates humans to keep it updated
+- [ ] **Audience Validation**: Confirm content meets target reader needs
+- [ ] **Integration**: Integrate with existing documentation structure

.cursor/rules/docs/markdown-automation.mdc

@@ -1,79 +0,0 @@
----
-alwaysApply: true
----
-
-# Markdown Automation System
-
-**Author**: Matthew Raymer
-**Date**: 2025-08-20
-**Status**: 🎯 **ACTIVE** - Markdown formatting automation
-
-## Overview
-
-The Markdown Automation System ensures your markdown formatting standards are
-followed **during content generation** by AI agents, not just applied after the
-fact.
-
-## AI-First Approach
-
-### **Primary Method**: AI Agent Compliance
-
-- **AI agents follow markdown rules** while generating content
-- **No post-generation fixes needed** - content is compliant from creation
-- **Consistent formatting** across all generated documentation
-
-### **Secondary Method**: Automated Validation
-
-- **Pre-commit hooks** catch any remaining issues
-- **GitHub Actions** validate formatting before merge
-- **Manual tools** for bulk fixes when needed
-
-## How It Works
-
-### 1. **AI Agent Compliance** (Primary)
-
-- **When**: Every time AI generates markdown content
-- **What**: AI follows markdown rules during generation
-- **Result**: Content is properly formatted from creation
-
-### 2. **Pre-commit Hooks** (Backup)
-
-- **When**: Every time you commit
-- **What**: Catches any remaining formatting issues
-- **Result**: Clean, properly formatted markdown files
-
-### 3. **GitHub Actions** (Pre-merge)
-
-- **When**: Every pull request
-- **What**: Validates markdown formatting across all files
-- **Result**: Blocks merge if formatting issues exist
-
-## AI Agent Rules Integration
-
-The AI agent follows markdown rules defined in `.cursor/rules/docs/markdown.mdc`:
-
-- **alwaysApply: true** - Rules are enforced during generation
-- **Line Length**: AI never generates lines > 80 characters
-- **Blank Lines**: AI adds proper spacing around all elements
-- **Structure**: AI uses established templates and patterns
-
-## Available Commands
-
-### NPM Scripts
-
-- **`npm run markdown:setup`** - Install the automation system
-- **`npm run markdown:fix`** - Fix formatting in all markdown files
-- **`npm run markdown:check`** - Validate formatting without fixing
-
-## Benefits
-
-- **No more manual fixes** - AI generates compliant content from start
-- **Consistent style** - All files follow same standards
-- **Faster development** - No need to fix formatting manually
-
----
-
-**Status**: Active automation system
-**Priority**: High
-**Maintainer**: Development team
-**Next Review**: 2025-09-20

.cursor/rules/docs/markdown.mdc

@@ -1,366 +0,0 @@
----
-globs: ["*.md", "*.mdc"]
-alwaysApply: false
----
-# Cursor Markdown Ruleset for TimeSafari Documentation
-
-## Overview
-
-This ruleset enforces consistent markdown formatting standards across all project
-documentation, ensuring readability, maintainability, and compliance with
-markdownlint best practices.
-
-**⚠️ CRITICAL FOR AI AGENTS**: These rules must be followed DURING content
-generation, not applied after the fact. Always generate markdown that complies
-with these standards from the start.
-
-## AI Generation Guidelines
-
-### **MANDATORY**: Follow These Rules While Writing
-
-When generating markdown content, you MUST:
-
-1. **Line Length**: Never exceed 80 characters per line
-2. **Blank Lines**: Always add blank lines around headings, lists, and code
-   blocks
-3. **Structure**: Use proper heading hierarchy and document templates
-4. **Formatting**: Apply consistent formatting patterns immediately
-
-### **DO NOT**: Generate content that violates these rules
-
-- ❌ Generate long lines that need breaking
-- ❌ Create content without proper blank line spacing
-- ❌ Use inconsistent formatting patterns
-- ❌ Assume post-processing will fix violations
-
-### **DO**: Generate compliant content from the start
-
-- ✅ Write within 80-character limits
-- ✅ Add blank lines around all structural elements
-- ✅ Use established templates and patterns
-- ✅ Apply formatting standards immediately
-
-## General Formatting Standards
-
-### Line Length
-
-- **Maximum line length**: 80 characters
-- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line length
-  enforcement
-- **Rationale**: Ensures readability across different screen sizes and terminal
-  widths
-
-### Blank Lines
-
-- **Headings**: Must be surrounded by blank lines above and below
-- **Lists**: Must be surrounded by blank lines above and below
-- **Code blocks**: Must be surrounded by blank lines above and below
-- **Maximum consecutive blank lines**: 1 (no multiple blank lines)
-- **File start**: No blank lines at the beginning of the file
-- **File end**: Single newline character at the end
-
-### Whitespace
-
-- **No trailing spaces**: Remove all trailing whitespace from lines
-- **No tabs**: Use spaces for indentation
-- **Consistent indentation**: 2 spaces for list items and nested content
-
-## Heading Standards
-
-### Format
-
-- **Style**: ATX-style headings (`#`, `##`, `###`, etc.)
-- **Case**: Title case for general headings
-- **Code references**: Use backticks for file names and technical terms
-  - ✅ `### Current package.json Scripts`
-  - ❌ `### Current Package.json Scripts`
-
-### Hierarchy
-
-- **H1 (#)**: Document title only
-- **H2 (##)**: Major sections
-- **H3 (###)**: Subsections
-- **H4 (####)**: Sub-subsections
-- **H5+**: Avoid deeper nesting
-
-## List Standards
-
-### Unordered Lists
-
-- **Marker**: Use `-` (hyphen) consistently
-- **Indentation**: 2 spaces for nested items
-- **Blank lines**: Surround lists with blank lines
-
-### Ordered Lists
-
-- **Format**: `1.`, `2.`, `3.` (sequential numbering)
-- **Indentation**: 2 spaces for nested items
-- **Blank lines**: Surround lists with blank lines
-
-### Task Lists
-
-- **Format**: `- [ ]` for incomplete, `- [x]` for complete
-- **Use case**: Project planning, checklists, implementation tracking
-
-## Code Block Standards
-
-### Fenced Code Blocks
-
-- **Syntax**: Triple backticks with language specification
-- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown`
-- **Blank lines**: Must be surrounded by blank lines above and below
-- **Line length**: No enforcement within code blocks
-
-### Inline Code
-
-- **Format**: Single backticks for inline code references
-- **Use case**: File names, commands, variables, properties
-
-## Special Content Standards
-
-### JSON Examples
-
-```json
-{
-  "property": "value",
-  "nested": {
-    "property": "value"
-  }
-}
-```
-
-### Shell Commands
-
-```bash
-# Command with comment
-npm run build:web
-
-# Multi-line command
-VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
-  vite build --config vite.config.web.mts
-```
-
-### TypeScript Examples
-
-```typescript
-// Function with JSDoc
-/**
- * Get environment configuration
- * @param env - Environment name
- * @returns Environment config object
- */
-const getEnvironmentConfig = (env: string) => {
-  switch (env) {
-    case 'prod':
-      return { /* production settings */ };
-    default:
-      return { /* development settings */ };
-  }
-};
-```
-
-## File Structure Standards
-
-### Document Header
-
-```markdown
-# Document Title
-
-**Author**: Matthew Raymer
-**Date**: YYYY-MM-DD
-**Status**: 🎯 **STATUS** - Brief description
-
-## Overview
-
-Brief description of the document's purpose and scope.
-```
-
-### Section Organization
-
-1. **Overview/Introduction**
-2. **Current State Analysis**
-3. **Implementation Plan**
-4. **Technical Details**
-5. **Testing & Validation**
-6. **Next Steps**
-
-## Markdownlint Configuration
-
-### Required Rules
-
-```json
-{
-  "MD013": { "code_blocks": false },
-  "MD012": true,
-  "MD022": true,
-  "MD031": true,
-  "MD032": true,
-  "MD047": true,
-  "MD009": true
-}
-```
-
-### Rule Explanations
-
-- **MD013**: Line length (disabled for code blocks)
-- **MD012**: No multiple consecutive blank lines
-- **MD022**: Headings should be surrounded by blank lines
-- **MD031**: Fenced code blocks should be surrounded by blank lines
-- **MD032**: Lists should be surrounded by blank lines
-- **MD047**: Files should end with a single newline
-- **MD009**: No trailing spaces
-
-## Validation Commands
-
-### Check Single File
-
-```bash
-npx markdownlint docs/filename.md
-```
-
-### Check All Documentation
-
-```bash
-npx markdownlint docs/
-```
-
-### Auto-fix Common Issues
-
-```bash
-# Remove trailing spaces
-sed -i 's/[[:space:]]*$//' docs/filename.md
-
-# Remove multiple blank lines
-sed -i '/^$/N;/^\n$/D' docs/filename.md
-
-# Add newline at end if missing
-echo "" >> docs/filename.md
-```
-
-## Common Patterns
-
-### Implementation Plans
-
-```markdown
-## Implementation Plan
-
-### Phase 1: Foundation (Day 1)
-
-#### 1.1 Component Setup
-
-- [ ] Create new component file
-- [ ] Add basic structure
-- [ ] Implement core functionality
-
-#### 1.2 Configuration
-
-- [ ] Update configuration files
-- [ ] Add environment variables
-- [ ] Test configuration loading
-```
-
-### Status Tracking
-
-```markdown
-**Status**: ✅ **COMPLETE** - All phases finished
-**Progress**: 75% (15/20 components)
-**Next**: Ready for testing phase
-```
-
-### Performance Metrics
-
-```markdown
-#### 📊 Performance Metrics
-- **Build Time**: 2.3 seconds (50% faster than baseline)
-- **Bundle Size**: 1.2MB (30% reduction)
-- **Success Rate**: 100% (no failures in 50 builds)
-```
-
-## Enforcement
-
-### Pre-commit Hooks
-
-- Run markdownlint on all changed markdown files
-- Block commits with linting violations
-- Auto-fix common issues when possible
-
-### CI/CD Integration
-
-- Include markdownlint in build pipeline
-- Generate reports for documentation quality
-- Fail builds with critical violations
-
-### Team Guidelines
-
-- All documentation PRs must pass markdownlint
-- Use provided templates for new documents
-- Follow established patterns for consistency
-
-## Templates
-
-### New Document Template
-
-```markdown
-# Document Title
-
-**Author**: Matthew Raymer
-**Date**: YYYY-MM-DD
-**Status**: 🎯 **PLANNING** - Ready for Implementation
-
-## Overview
-
-Brief description of the document's purpose and scope.
-
-## Current State
-
-Description of current situation or problem.
-
-## Implementation Plan
-
-### Phase 1: Foundation
-
-- [ ] Task 1
-- [ ] Task 2
-
-## Next Steps
-
-1. **Review and approve plan**
-2. **Begin implementation**
-3. **Test and validate**
-
----
-
-**Status**: Ready for implementation
-**Priority**: Medium
-**Estimated Effort**: X days
-**Dependencies**: None
-**Stakeholders**: Development team
-```
-
----
-
-**Last Updated**: 2025-07-09
-**Version**: 1.0
-**Maintainer**: Matthew Raymer
-
-
-### Heading Uniqueness
-
-- **Rule**: No duplicate heading content at the same level
-- **Scope**: Within a single document
-- **Rationale**: Maintains clear document structure and navigation
-- **Example**:
-
-  ```markdown
-  ## Features        ✅
-  ### Authentication
-  ### Authorization
-
-  ## Features        ❌ (Duplicate heading)
-  ### Security
-  ### Performance
-  ```
-  ## Features        ❌ (Duplicate heading)
-  ### Security
-  ### Performance
-  ```

.cursor/rules/docs/markdown_core.mdc

@@ -0,0 +1,210 @@
+# Markdown Core Standards & Automation
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Core markdown standards and automation
+
+## Overview
+
+This file combines core markdown formatting standards with automation
+guidelines. AI agents must follow these rules DURING content generation,
+not apply them after the fact.
+
+**Primary Focus**: Create educational content that increases human
+competence, not just technical descriptions.
+
+## AI Generation Guidelines
+
+### **MANDATORY**: Follow These Rules While Writing
+
+When generating markdown content, you MUST:
+
+1. **Line Length**: Never exceed 80 characters per line
+2. **Blank Lines**: Always add blank lines around headings, lists, and
+   code blocks
+3. **Structure**: Use proper heading hierarchy and document templates
+4. **Formatting**: Apply consistent formatting patterns immediately
+5. **Educational Value**: Focus on increasing reader competence and
+   understanding
+
+### **DO NOT**: Generate content that violates these rules
+
+- ❌ Generate long lines that need breaking
+- ❌ Create content without proper blank line spacing
+- ❌ Use inconsistent formatting patterns
+- ❌ Assume post-processing will fix violations
+- ❌ Focus only on technical details without educational context
+- ❌ Assume reader has extensive prior knowledge
+
+### **DO**: Generate compliant content from the start
+
+- ✅ Write within 80-character limits
+- ✅ Add blank lines around all structural elements
+- ✅ Use established templates and patterns
+- ✅ Apply formatting standards immediately
+- ✅ Explain concepts before implementation details
+- ✅ Provide context and motivation for technical choices
+- ✅ Include examples that illustrate key concepts
+
+## Core Formatting Standards
+
+### Line Length
+
+- **Maximum line length**: 80 characters
+- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line
+  length enforcement
+- **Rationale**: Ensures readability across different screen sizes and
+  terminal widths
+
+### Blank Lines
+
+- **Headings**: Must be surrounded by blank lines above and below
+- **Lists**: Must be surrounded by blank lines above and below
+- **Code blocks**: Must be surrounded by blank lines above and below
+- **Maximum consecutive blank lines**: 1 (no multiple blank lines)
+- **File start**: No blank lines at the beginning of the file
+- **File end**: Single newline character at the end
+
+### Whitespace
+
+- **No trailing spaces**: Remove all trailing whitespace from lines
+- **No tabs**: Use spaces for indentation
+- **Consistent indentation**: 2 spaces for list items and nested content
+
+## Heading Standards
+
+### Format
+
+- **Style**: ATX-style headings (`#`, `##`, `###`, etc.)
+- **Case**: Title case for general headings
+- **Code references**: Use backticks for file names and technical terms
+  - ✅ `### Current package.json Scripts`
+  - ❌ `### Current Package.json Scripts`
+
+### Hierarchy
+
+- **H1 (#)**: Document title only
+- **H2 (##)**: Major sections
+- **H3 (###)**: Subsections
+- **H4 (####)**: Sub-subsections
+- **H5+**: Avoid deeper nesting
+
+## List Standards
+
+### Unordered Lists
+
+- **Marker**: Use `-` (hyphen) consistently
+- **Indentation**: 2 spaces for nested items
+- **Blank lines**: Surround lists with blank lines
+
+### Ordered Lists
+
+- **Format**: `1.`, `2.`, `3.` (sequential numbering)
+- **Indentation**: 2 spaces for nested items
+- **Blank lines**: Surround lists with blank lines
+
+### Task Lists
+
+- **Format**: `- [ ]` for incomplete, `- [x]` for complete
+- **Indentation**: 2 spaces for nested items
+- **Blank lines**: Surround lists with blank lines
+
+## Educational Content Standards
+
+### **Content Structure for Learning**
+
+- **Concept First**: Explain what something is before how to use it
+- **Context Matters**: Explain why and when to use a feature
+- **Progressive Disclosure**: Start simple, add complexity gradually
+- **Real Examples**: Use concrete, relatable scenarios
+- **Common Questions**: Anticipate and answer reader questions
+
+### **Writing for Understanding**
+
+- **Conversational Tone**: Write as if explaining to a colleague
+- **Active Voice**: "You can do this" not "This can be done"
+- **Question Format**: "What happens when..." to engage thinking
+- **Analogies**: Use familiar concepts to explain complex ideas
+- **Limitations**: Clearly state what solutions don't do
+
+## Code Block Standards
+
+### Inline Code
+
+- **Format**: Single backticks for inline code
+- **Use cases**: File names, commands, variables, technical terms
+- **Examples**: `package.json`, `npm run build`, `VITE_PLATFORM`
+
+### Code Blocks
+
+- **Format**: Triple backticks with language specification
+- **Language**: Always specify the language for syntax highlighting
+- **Blank lines**: Surround with blank lines above and below
+
+## Automation System
+
+### Available Commands
+
+- **`npm run markdown:fix`** - Fix formatting in all markdown files
+  using markdownlint-cli2 --fix
+- **`npm run markdown:check`** - Validate formatting without fixing
+  using markdownlint-cli2
+
+### How It Works
+
+1. **AI Agent Compliance** (Primary): AI follows markdown rules during
+   generation
+2. **Pre-commit Hooks** (Backup): Catches any remaining formatting
+   issues
+3. **GitHub Actions** (Pre-merge): Validates formatting before merge
+
+### Benefits
+
+- **No more manual fixes** - AI generates compliant content from start
+- **Consistent style** - All files follow same standards
+- **Faster development** - No need to fix formatting manually
+
+## Model Implementation Checklist
+
+### Before Generating Markdown Content
+
+- [ ] **Line Length**: Ensure no line exceeds 80 characters
+- [ ] **Blank Lines**: Add blank lines around headings, lists, and code blocks
+- [ ] **Whitespace**: Remove all trailing spaces, use 2-space indentation
+- [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only)
+- [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered)
+- [ ] **Code**: Specify language for fenced blocks, use backticks for inline
+- [ ] **Educational Focus**: Plan content structure for learning progression
+- [ ] **Audience Consideration**: Identify target reader knowledge level
+
+### After Generating Markdown Content
+
+- [ ] **Validation**: Run `npm run markdown:check` to verify compliance
+- [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found
+- [ ] **Review**: Confirm content follows established templates and patterns
+- [ ] **Cross-reference**: Link to related documentation and templates
+- [ ] **Educational Review**: Verify content increases reader competence
+- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly
+
+### Quality Assurance
+
+- [ ] **Readability**: Content is clear and follows project conventions
+- [ ] **Consistency**: Formatting matches existing documentation style
+- [ ] **Completeness**: All required sections and information included
+- [ ] **Accuracy**: Technical details are correct and up-to-date
+- [ ] **Educational Value**: Content increases reader understanding and competence
+- [ ] **Context Clarity**: Reader understands when and why to use the information
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
+- `.cursor/rules/docs/markdown_templates.mdc` for document templates
+- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
+
+**Status**: Active core standards and automation
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Documentation team, Development team

.cursor/rules/docs/markdown_templates.mdc

@@ -0,0 +1,314 @@
+# Markdown Templates & Examples
+
+> **Agent role**: Reference this file for document templates, structure,
+> and examples when creating new documentation.
+>
+> **Focus**: Create educational content that increases human competence,
+> not just technical descriptions.
+
+## Document Templates
+
+### Standard Document Template
+
+```markdown
+# Document Title
+
+**Author**: Matthew Raymer
+**Date**: YYYY-MM-DD
+**Status**: 🎯 **STATUS** - Brief description
+
+## Overview
+
+Brief description of the document's purpose and scope.
+
+**Educational Goal**: What will the reader learn and how will it increase
+their competence?
+
+## Current State
+
+Description of current situation or problem.
+
+**Why This Matters**: Explain the business value and user benefit of
+addressing this situation.
+
+## Implementation Plan
+
+### Phase 1: Foundation
+
+- [ ] Task 1
+- [ ] Task 2
+
+**Learning Context**: What concepts should the reader understand before
+proceeding with implementation?
+
+## Next Steps
+
+1. **Review and approve plan**
+2. **Begin implementation**
+3. **Test and validate**
+
+**Continued Learning**: Where can the reader go next to deepen their
+understanding?
+
+---
+
+**Status**: Ready for implementation
+**Priority**: Medium
+**Estimated Effort**: X days
+**Dependencies**: None
+**Stakeholders**: Development team
+```
+
+### Technical Specification Template
+
+```markdown
+# Technical Specification: [Feature Name]
+
+**Author**: Matthew Raymer
+**Date**: YYYY-MM-DD
+**Status**: 🎯 **DRAFT** - Under Review
+
+## Overview
+
+Brief description of the technical specification.
+
+**Business Context**: Why is this specification needed and what problem
+does it solve for users?
+
+## Requirements
+
+### Functional Requirements
+
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Non-Functional Requirements
+
+- [ ] Performance requirement
+- [ ] Security requirement
+
+## Technical Design
+
+### Architecture
+
+Description of the technical architecture.
+
+**Design Rationale**: Why was this architecture chosen over alternatives?
+What are the trade-offs and benefits?
+
+### Data Models
+
+```typescript
+interface ExampleModel {
+  id: string;
+  name: string;
+  createdAt: Date;
+}
+```
+
+### API Design
+
+```typescript
+interface APIResponse<T> {
+  success: boolean;
+  data: T;
+  error?: string;
+}
+```
+
+## Testing Strategy
+
+- [ ] Unit tests
+
+**Learning from Testing**: What insights does testing provide about the
+system's behavior and design?
+
+---
+
+## Educational Documentation Template
+
+### **Concept Explanation Template**
+
+```markdown
+## What is [Concept Name]?
+
+Brief, clear definition of the concept.
+
+## Why Does [Concept Name] Matter?
+
+Explain the business value and user benefit.
+
+## How Does [Concept Name] Work?
+
+High-level explanation of the mechanism.
+
+## When Would You Use [Concept Name]?
+
+Real-world scenarios and use cases.
+
+## Common Misconceptions
+
+Address typical misunderstandings.
+
+## Examples
+
+Concrete examples that illustrate the concept.
+
+## Next Steps
+
+Where to learn more about related concepts.
+```
+
+### **Tutorial Template**
+
+```markdown
+## Learning Objective
+
+What the reader will accomplish by the end.
+
+## Prerequisites
+
+What the reader should know before starting.
+
+## Step-by-Step Guide
+
+1. **Step 1**: What to do and why
+2. **Step 2**: What to do and why
+3. **Step 3**: What to do and why
+
+## Verification
+
+How to confirm the tutorial was successful.
+
+## Troubleshooting
+
+Common issues and how to resolve them.
+
+## What You've Learned
+
+Summary of key concepts and skills.
+
+## Next Steps
+
+Where to apply this knowledge next.
+```
+- [ ] Integration tests
+- [ ] E2E tests
+
+---
+
+**Status**: Draft
+**Priority**: High
+**Estimated Effort**: X days
+**Dependencies**: None
+**Stakeholders**: Development team
+
+```
+
+## Content Examples
+
+### JSON Examples
+
+```json
+{
+  "property": "value",
+  "nested": {
+    "property": "value"
+  }
+}
+```
+
+### Shell Commands
+
+```bash
+# Command with comment
+npm run build:web
+
+# Multi-line command
+VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
+  vite build --config vite.config.web.mts
+```
+
+### TypeScript Examples
+
+```typescript
+// Function with JSDoc
+const getEnvironmentConfig = (env: string) => {
+  switch (env) {
+    case 'prod':
+      return { /* production settings */ };
+    default:
+      return { /* development settings */ };
+  }
+};
+```
+
+## File Structure Standards
+
+### Document Header
+
+```markdown
+# Document Title
+
+**Author**: Matthew Raymer
+**Date**: YYYY-MM-DD
+**Status**: 🎯 **STATUS** - Brief description
+
+## Overview
+
+Brief description of the document's purpose and scope.
+```
+
+### Section Organization
+
+Standard sections: Overview, Current State, Implementation Plan,
+Technical Details, Testing & Validation, Next Steps
+
+## Common Patterns
+
+Standard implementation plans follow Phase 1 (Foundation), Phase 2
+(Features), Phase 3 (Testing & Polish) structure.
+
+## Model Implementation Checklist
+
+### Before Using Templates
+
+- [ ] **Template Selection**: Choose appropriate template for document type
+- [ ] **Structure Review**: Understand required sections and organization
+- [ ] **Content Planning**: Plan what information goes in each section
+- [ ] **Audience Analysis**: Ensure template matches target audience needs
+
+### During Template Usage
+
+- [ ] **Section Completion**: Fill in all required sections completely
+- [ ] **Example Integration**: Include relevant code examples and patterns
+- [ ] **Formatting Consistency**: Apply markdown standards from core rules
+- [ ] **Cross-references**: Link to related documentation and resources
+
+### After Template Usage
+
+- [ ] **Content Review**: Verify all sections contain appropriate content
+- [ ] **Formatting Check**: Run `npm run markdown:check` for compliance
+- [ ] **Template Validation**: Confirm document follows template structure
+- [ ] **Quality Assessment**: Ensure content meets project standards
+
+### Template-Specific Requirements
+
+- [ ] **Standard Documents**: Include all required metadata and sections
+- [ ] **Technical Specs**: Complete all requirement and design sections
+- [ ] **Implementation Plans**: Define clear phases and milestones
+- [ ] **Examples**: Provide relevant, working code examples
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
+- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
+- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
+
+**Status**: Active templates and examples
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: markdown_core.mdc
+**Stakeholders**: Documentation team, Development team

.cursor/rules/docs/markdown_workflow.mdc

@@ -0,0 +1,168 @@
+# Markdown Workflow & Validation
+
+> **Agent role**: Reference this file for markdown validation rules,
+> enforcement procedures, and workflow management.
+
+## Markdownlint Configuration
+
+### Core Rules
+
+```json
+{
+  "MD013": { "line_length": 80, "code_blocks": false },
+  "MD012": true,
+  "MD022": true,
+  "MD031": true,
+  "MD032": true,
+  "MD047": true,
+  "MD009": true,
+  "MD004": { "style": "dash" }
+}
+```
+
+### Rule Explanations
+
+- **MD013**: Line length (80 chars, disabled for code blocks)
+- **MD012**: No multiple consecutive blank lines
+- **MD022**: Headings should be surrounded by blank lines
+- **MD031**: Fenced code blocks should be surrounded by blank lines
+- **MD032**: Lists should be surrounded by blank lines
+- **MD047**: Files should end with a single newline
+- **MD009**: No trailing spaces
+- **MD004**: Consistent list markers (dash style)
+
+## Validation Commands
+
+### Check All MDC Files
+
+```bash
+npm run markdown:check
+```
+
+### Auto-fix Formatting Issues
+
+```bash
+npm run markdown:fix
+```
+
+### Check Single File
+
+```bash
+npx markdownlint-cli2 .cursor/rules/filename.mdc
+```
+
+## Enforcement Workflow
+
+### Pre-commit Hooks
+
+- **Automatic**: `lint-staged` runs `markdownlint-cli2 --fix` on all
+  staged `.mdc` files
+- **Result**: Files are automatically formatted before commit
+- **Blocking**: Commits with unfixable violations are blocked
+
+### CI/CD Integration
+
+- **Build Pipeline**: Include markdownlint in automated builds
+- **Quality Reports**: Generate documentation quality metrics
+- **Build Failure**: Fail builds with critical violations
+
+### Team Guidelines
+
+- **PR Requirements**: All documentation PRs must pass markdownlint
+- **Templates**: Use provided templates for new documents
+- **Patterns**: Follow established patterns for consistency
+- **Auto-fixing**: Let automation handle formatting, focus on content
+
+## Quality Assurance
+
+### Validation Checklist
+
+- [ ] All files pass `npm run markdown:check`
+- [ ] Line length under 80 characters
+- [ ] Proper blank line spacing around elements
+- [ ] No trailing spaces
+- [ ] Consistent list markers
+- [ ] Proper heading hierarchy
+- [ ] Code blocks have language specification
+
+### Common Issues & Fixes
+
+#### Trailing Spaces
+
+```bash
+# Remove trailing spaces
+sed -i 's/[[:space:]]*$//' .cursor/rules/**/*.mdc
+```
+
+#### Multiple Blank Lines
+
+```bash
+# Remove multiple blank lines
+sed -i '/^$/N;/^\n$/D' .cursor/rules/**/*.mdc
+```
+
+#### Missing Newlines
+
+```bash
+# Add newline at end if missing
+find .cursor/rules -name "*.mdc" -exec sed -i -e '$a\' {} \;
+```
+
+## Integration Points
+
+### Git Workflow
+
+1. **Edit**: Make changes to MDC files
+2. **Stage**: `git add .cursor/rules/filename.mdc`
+3. **Auto-fix**: `lint-staged` runs `markdownlint-cli2 --fix`
+4. **Commit**: Changes are committed with perfect formatting
+
+### Development Workflow
+
+1. **Create/Edit**: Use templates from `markdown_templates.mdc`
+2. **Validate**: Run `npm run markdown:check` before committing
+3. **Auto-fix**: Use `npm run markdown:fix` for bulk fixes
+4. **Review**: Ensure content quality, not just formatting
+
+## Model Implementation Checklist
+
+### Before Starting Workflow
+
+- [ ] **Configuration Review**: Understand markdownlint rules and settings
+- [ ] **Tool Availability**: Ensure markdownlint-cli2 is installed and working
+- [ ] **File Scope**: Identify which files need validation or fixing
+- [ ] **Backup Strategy**: Consider backing up files before bulk operations
+
+### During Workflow Execution
+
+- [ ] **Validation First**: Run `npm run markdown:check` to identify issues
+- [ ] **Issue Analysis**: Review and understand each validation error
+- [ ] **Auto-fix Application**: Use `npm run markdown:fix` for automatic fixes
+- [ ] **Manual Review**: Check files that couldn't be auto-fixed
+
+### After Workflow Completion
+
+- [ ] **Final Validation**: Confirm all files pass `npm run markdown:check`
+- [ ] **Quality Review**: Verify formatting meets project standards
+- [ ] **Documentation Update**: Update any related documentation or guides
+- [ ] **Team Communication**: Share workflow results and any manual fixes needed
+
+### Workflow-Specific Requirements
+
+- [ ] **Pre-commit Hooks**: Ensure lint-staged configuration is working
+- [ ] **CI/CD Integration**: Verify build pipeline includes markdown validation
+- [ ] **Team Guidelines**: Confirm all team members understand the workflow
+- [ ] **Error Resolution**: Document common issues and their solutions
+
+---
+
+**See also**:
+
+- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
+- `.cursor/rules/docs/markdown_templates.mdc` for document templates
+
+**Status**: Active workflow and validation
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: markdown_core.mdc, markdown_templates.mdc
+**Stakeholders**: Development team, Documentation team

.cursor/rules/features/camera-implementation.mdc

@@ -1,7 +1,3 @@
----
-description: when dealing with cameras in the application
-alwaysApply: false
----
 # Camera Implementation Documentation
 
 ## Overview
@@ -10,6 +6,7 @@ This document describes how camera functionality is implemented across the
 TimeSafari application. The application uses cameras for two main purposes:
 
 1. QR Code scanning
+
 2. Photo capture
 
 ## Components
@@ -21,17 +18,25 @@ Primary component for QR code scanning in web browsers.
 **Key Features:**
 
 - Uses `qrcode-stream` for web-based QR scanning
+
 - Supports both front and back cameras
+
 - Provides real-time camera status feedback
+
 - Implements error handling with user-friendly messages
+
 - Includes camera switching functionality
 
 **Camera Access Flow:**
 
 1. Checks for camera API availability
+
 2. Enumerates available video devices
+
 3. Requests camera permissions
+
 4. Initializes camera stream with preferred settings
+
 5. Handles various error conditions with specific messages
 
 ### PhotoDialog.vue
@@ -41,8 +46,11 @@ Component for photo capture and selection.
 **Key Features:**
 
 - Cross-platform photo capture interface
+
 - Image cropping capabilities
+
 - File selection fallback
+
 - Unified interface for different platforms
 
 ## Services
@@ -56,8 +64,11 @@ Web-based implementation of QR scanning.
 **Key Methods:**
 
 - `checkPermissions()`: Verifies camera permission status
+
 - `requestPermissions()`: Requests camera access
+
 - `isSupported()`: Checks for camera API support
+
 - Handles various error conditions with specific messages
 
 #### CapacitorQRScanner
@@ -67,8 +78,11 @@ Native implementation using Capacitor's MLKit.
 **Key Features:**
 
 - Uses `@capacitor-mlkit/barcode-scanning`
+
 - Supports both front and back cameras
+
 - Implements permission management
+
 - Provides continuous scanning capability
 
 ### Platform Services
@@ -80,7 +94,9 @@ Web-specific implementation of platform features.
 **Camera Capabilities:**
 
 - Uses HTML5 file input with capture attribute
+
 - Falls back to file selection if camera unavailable
+
 - Processes captured images for consistent format
 
 #### CapacitorPlatformService
@@ -90,133 +106,58 @@ Native implementation using Capacitor.
 **Camera Features:**
 
 - Uses `Camera.getPhoto()` for native camera access
+
 - Supports image editing
+
 - Configures high-quality image capture
+
 - Handles base64 image processing
 
 #### ElectronPlatformService
 
 Desktop implementation (currently unimplemented).
 
-**Status:**
+---
 
-- Camera functionality not yet implemented
+**See also**:
-- Planned to use Electron's media APIs
 
-## Platform-Specific Considerations
+- `.cursor/rules/features/camera_technical.mdc` for
 
-### iOS
+  detailed technical implementation
 
-- Requires `NSCameraUsageDescription` in Info.plist
+- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details
-- Supports both front and back cameras
-- Implements proper permission handling
 
-### Android
+**Status**: Active camera implementation overview
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Development team, Camera feature team
 
-- Requires camera permissions in manifest
-- Supports both front and back cameras
-- Handles permission requests through Capacitor
-
-### Web
-
-- Requires HTTPS for camera access
-- Implements fallback mechanisms
-- Handles browser compatibility issues
-
-## Error Handling
-
-### Common Error Scenarios
-
-1. No camera found
-2. Permission denied
-3. Camera in use by another application
-4. HTTPS required
-5. Browser compatibility issues
-
-### Error Response
-
-- User-friendly error messages
-- Troubleshooting tips
-- Clear instructions for resolution
-- Platform-specific guidance
-
-## Security Considerations
-
-### Permission Management
-
-- Explicit permission requests
-- Permission state tracking
-- Graceful handling of denied permissions
-
-### Data Handling
-
-- Secure image processing
-- Proper cleanup of camera resources
-- No persistent storage of camera data
-
-## Best Practices
-
-### Camera Access
-
-1. Always check for camera availability
-2. Request permissions explicitly
-3. Handle all error conditions
-4. Provide clear user feedback
-5. Implement proper cleanup
-
-### Performance
-
-1. Optimize camera resolution
-2. Implement proper resource cleanup
-3. Handle camera switching efficiently
-4. Manage memory usage
-
-### User Experience
-
-1. Clear status indicators
-2. Intuitive camera controls
-3. Helpful error messages
-4. Smooth camera switching
-5. Responsive UI feedback
-
-## Future Improvements
-
-### Planned Enhancements
-
-1. Implement Electron camera support
-2. Add advanced camera features
-3. Improve error handling
-4. Enhance user feedback
-5. Optimize performance
-
-### Known Issues
-
-1. Electron camera implementation pending
-2. Some browser compatibility limitations
-3. Platform-specific quirks to address
-
-## Dependencies
-
-### Key Packages
-
-- `@capacitor-mlkit/barcode-scanning`
-- `qrcode-stream`
-- `vue-picture-cropper`
-- Platform-specific camera APIs
-
-## Testing
-
-### Test Scenarios
-
-1. Permission handling
-2. Camera switching
-3. Error conditions
-4. Platform compatibility
-5. Performance metrics
-
-### Test Environment
-
-- Multiple browsers
 - iOS and Android devices
+
 - Desktop platforms
+
 - Various network conditions
+
+## Model Implementation Checklist
+
+### Before Camera Implementation
+
+- [ ] **Platform Analysis**: Understand camera requirements across all platforms
+- [ ] **Feature Planning**: Plan QR scanning and photo capture features
+- [ ] **Service Planning**: Plan camera service architecture
+- [ ] **Testing Strategy**: Plan testing across web, mobile, and desktop
+
+### During Camera Implementation
+
+- [ ] **Component Development**: Implement QRScannerDialog and PhotoDialog
+- [ ] **Service Implementation**: Implement platform-specific camera services
+- [ ] **Permission Handling**: Implement proper camera permission management
+- [ ] **Error Handling**: Implement graceful error handling for camera failures
+
+### After Camera Implementation
+
+- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms
+- [ ] **Feature Validation**: Verify QR scanning and photo capture work correctly
+- [ ] **Performance Testing**: Ensure camera performance meets requirements
+- [ ] **Documentation Update**: Update camera implementation documentation

.cursor/rules/features/camera_platforms.mdc

@@ -0,0 +1,225 @@
+# Camera Platform-Specific Implementation
+
+> **Agent role**:
+  Reference this file for platform-specific camera implementation details.
+
+## Web Platform
+
+### Implementation Details
+
+- Uses `getUserMedia` API for camera access
+
+- Implements fallback to file input if camera unavailable
+
+- Handles browser compatibility issues
+
+- Requires HTTPS for camera access
+
+### Browser Support
+
+- Chrome: Full support
+
+- Firefox: Full support
+
+- Safari: Limited support
+
+- Edge: Full support
+
+### Fallback Mechanisms
+
+1. Camera access via getUserMedia
+
+2. File input for image upload
+
+3. Drag and drop support
+
+4. Clipboard paste support
+
+## Mobile Platform (Capacitor)
+
+### iOS Implementation
+
+- Uses `@capacitor-mlkit/barcode-scanning`
+
+- Implements proper permission handling
+
+- Supports both front and back cameras
+
+- Handles camera switching
+
+### Android Implementation
+
+- Uses `@capacitor-mlkit/barcode-scanning`
+
+- Implements proper permission handling
+
+- Supports both front and back cameras
+
+- Handles camera switching
+
+### Permission Handling
+
+- Camera permissions requested at runtime
+
+- Permission state tracked and cached
+
+- Graceful handling of denied permissions
+
+- Clear user guidance for enabling permissions
+
+## Desktop Platform (Electron)
+
+### Current Status
+
+- Camera implementation pending
+
+- Will use platform-specific APIs
+
+- Requires proper permission handling
+
+- Will support both built-in and external cameras
+
+### Planned Implementation
+
+- Native camera access via Electron
+
+- Platform-specific camera APIs
+
+- Proper permission handling
+
+- Camera switching support
+
+## Platform Detection
+
+### Implementation
+
+- Uses `PlatformServiceFactory` for platform detection
+
+- Implements platform-specific camera services
+
+- Handles platform-specific error conditions
+
+- Provides platform-specific user guidance
+
+### Service Selection
+
+- Web: `WebPlatformService`
+
+- Mobile: `CapacitorPlatformService`
+
+- Desktop: `ElectronPlatformService`
+
+## Cross-Platform Compatibility
+
+### Common Interface
+
+- Unified camera service interface
+
+- Platform-specific implementations
+
+- Consistent error handling
+
+- Unified user experience
+
+### Feature Parity
+
+- Core camera functionality across platforms
+
+- Platform-specific optimizations
+
+- Consistent user interface
+
+- Unified error messages
+
+## Platform-Specific Features
+
+### Web
+
+- Browser-based camera access
+
+- File upload fallback
+
+- Drag and drop support
+
+- Clipboard paste support
+
+### Mobile
+
+- Native camera access
+
+- Barcode scanning
+
+- Photo capture
+
+- Camera switching
+
+### Desktop
+
+- Native camera access (planned)
+
+- External camera support (planned)
+
+- Advanced camera controls (planned)
+
+## Testing Strategy
+
+### Platform Coverage
+
+- Web: Multiple browsers
+
+- Mobile: iOS and Android devices
+
+- Desktop: Windows, macOS, Linux
+
+### Test Scenarios
+
+- Permission handling
+
+- Camera access
+
+- Error conditions
+
+- Platform compatibility
+
+- Performance metrics
+
+---
+
+**See also**:
+
+- `.cursor/rules/features/camera-implementation.mdc` for
+
+  core implementation overview
+
+- `.cursor/rules/features/camera_technical.mdc` for
+
+  technical implementation details
+
+**Status**: Active platform-specific implementation guide
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: camera-implementation.mdc
+**Stakeholders**: Development team, Platform team
+
+## Model Implementation Checklist
+
+### Before Camera Platform Implementation
+
+- [ ] **Platform Analysis**: Identify target platforms and their camera capabilities
+- [ ] **Feature Planning**: Plan platform-specific camera features
+- [ ] **Integration Planning**: Plan integration with existing camera systems
+- [ ] **Testing Strategy**: Plan testing across all target platforms
+
+### During Camera Platform Implementation
+
+- [ ] **Platform Services**: Implement platform-specific camera functionality
+- [ ] **Feature Development**: Implement planned camera features for each platform
+- [ ] **Integration**: Integrate with existing camera infrastructure
+- [ ] **Performance Optimization**: Optimize camera performance for each platform
+
+### After Camera Platform Implementation
+
+- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms
+- [ ] **Feature Validation**: Verify all planned features work correctly
+- [ ] **Performance Testing**: Ensure camera performance meets requirements
+- [ ] **Documentation Update**: Update platform-specific camera documentation

.cursor/rules/features/camera_technical.mdc

@@ -0,0 +1,203 @@
+# Camera Technical Implementation — Details and Best Practices
+
+> **Agent role**: Reference this file for
+  detailed technical implementation when working with camera features.
+
+## Platform-Specific Considerations
+
+### iOS
+
+- Requires `NSCameraUsageDescription` in Info.plist
+
+- Supports both front and back cameras
+
+- Implements proper permission handling
+
+### Android
+
+- Requires camera permissions in manifest
+
+- Supports both front and back cameras
+
+- Handles permission requests through Capacitor
+
+### Web
+
+- Requires HTTPS for camera access
+
+- Implements fallback mechanisms
+
+- Handles browser compatibility issues
+
+## Error Handling
+
+### Common Error Scenarios
+
+1. No camera found
+
+2. Permission denied
+
+3. Camera in use by another application
+
+4. HTTPS required
+
+5. Browser compatibility issues
+
+### Error Response
+
+- User-friendly error messages
+
+- Troubleshooting tips
+
+- Clear instructions for resolution
+
+- Platform-specific guidance
+
+## Security Considerations
+
+### Permission Management
+
+- Explicit permission requests
+
+- Permission state tracking
+
+- Graceful handling of denied permissions
+
+### Data Handling
+
+- Secure image processing
+
+- Proper cleanup of camera resources
+
+- No persistent storage of camera data
+
+## Best Practices
+
+### Camera Access
+
+1. Always check for camera availability
+
+2. Request permissions explicitly
+
+3. Handle all error conditions
+
+4. Provide clear user feedback
+
+5. Implement proper cleanup
+
+### Performance
+
+1. Optimize camera resolution
+
+2. Implement proper resource cleanup
+
+3. Handle camera switching efficiently
+
+4. Manage memory usage
+
+### User Experience
+
+1. Clear status indicators
+
+2. Intuitive camera controls
+
+3. Helpful error messages
+
+4. Smooth camera switching
+
+5. Responsive UI feedback
+
+## Future Improvements
+
+### Planned Enhancements
+
+1. Implement Electron camera support
+
+2. Add advanced camera features
+
+3. Improve error handling
+
+4. Enhance user feedback
+
+5. Optimize performance
+
+### Known Issues
+
+1. Electron camera implementation pending
+
+2. Some browser compatibility limitations
+
+3. Platform-specific quirks to address
+
+## Dependencies
+
+### Key Packages
+
+- `@capacitor-mlkit/barcode-scanning`
+
+- `qrcode-stream`
+
+- `vue-picture-cropper`
+
+- Platform-specific camera APIs
+
+## Testing
+
+### Test Scenarios
+
+1. Permission handling
+
+2. Camera switching
+
+3. Error conditions
+
+4. Platform compatibility
+
+5. Performance metrics
+
+### Test Environment
+
+- Multiple browsers
+
+- iOS and Android devices
+
+- Desktop platforms
+
+---
+
+**See also**:
+
+- `.cursor/rules/features/camera-implementation.mdc` for
+
+  core implementation overview
+
+- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details
+
+**Status**: Active technical implementation guide
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: camera-implementation.mdc
+**Stakeholders**: Development team, Camera feature team
+
+## Model Implementation Checklist
+
+### Before Camera Implementation
+
+- [ ] **Platform Analysis**: Identify target platforms and camera capabilities
+- [ ] **Permission Planning**: Plan permission handling for camera access
+- [ ] **Dependency Review**: Review required camera packages and APIs
+- [ ] **Testing Strategy**: Plan testing across multiple platforms
+
+### During Camera Implementation
+
+- [ ] **Platform Services**: Implement platform-specific camera services
+- [ ] **Permission Handling**: Implement proper camera permission handling
+- [ ] **Error Handling**: Implement graceful error handling for camera failures
+- [ ] **Performance Optimization**: Optimize camera performance and responsiveness
+
+### After Camera Implementation
+
+- [ ] **Cross-Platform Testing**: Test camera functionality across all platforms
+- [ ] **Permission Testing**: Test permission handling and user feedback
+- [ ] **Performance Validation**: Verify camera performance meets requirements
+- [ ] **Documentation Update**: Update camera technical documentation

.cursor/rules/harbor_pilot_universal.mdc

@@ -1,206 +0,0 @@
----
-alwaysApply: true
-inherits: base_context.mdc
----
-```json
-{
-  "coaching_level": "standard",
-  "socratic_max_questions": 2,
-  "verbosity": "concise",
-  "timebox_minutes": 10,
-  "format_enforcement": "strict"
-}
-```
-
-# Harbor Pilot — Universal Directive for Human-Facing Technical Guides
-
-**Author**: System/Shared  
-**Date**: 2025-08-21 (UTC)  
-**Status**: 🚢 ACTIVE — General ruleset extending *Base Context — Human Competence First*
-
-> **Alignment with Base Context**
-> - **Purpose fit**: Prioritizes human competence and collaboration while delivering reproducible artifacts.  
-> - **Output Contract**: This directive **adds universal constraints** for any technical topic while **inheriting** the Base Context contract sections.  
-> - **Toggles honored**: Uses the same toggle semantics; defaults above can be overridden by the caller.
-
----
-
-## Objective
-Produce a **developer-grade, reproducible guide** for any technical topic that onboards a competent practitioner **without meta narration** and **with evidence-backed steps**.
-
-## Scope & Constraints
-- **One Markdown document** as the deliverable.
-- Use **absolute dates** in **UTC** (e.g., `2025-08-21T14:22Z`) — avoid “today/yesterday”.
-- Include at least **one diagram** (Mermaid preferred). Choose the most fitting type:
-  - `sequenceDiagram` (protocols/flows), `flowchart`, `stateDiagram`, `gantt` (timelines), or `classDiagram` (schemas).
-- Provide runnable examples where applicable:
-  - **APIs**: `curl` + one client library (e.g., `httpx` for Python).
-  - **CLIs**: literal command blocks and expected output snippets.
-  - **Code**: minimal, self-contained samples (language appropriate).
-- Cite **evidence** for *Works/Doesn’t* items (timestamps, filenames, line numbers, IDs/status codes, or logs).
-- If something is unknown, output `TODO:<missing>` — **never invent**.
-
-## Required Sections (extends Base Output Contract)
-Follow this exact order **after** the Base Contract’s **Objective → Result → Use/Run** headers:
-
-1. **Context & Scope**
-   - Problem statement, audience, in/out-of-scope bullets.
-2. **Artifacts & Links**
-   - Repos/PRs, design docs, datasets/HARs/pcaps, scripts/tools, dashboards.
-3. **Environment & Preconditions**
-   - OS/runtime, versions/build IDs, services/endpoints/URLs, credentials/auth mode (describe acquisition, do not expose secrets).
-4. **Architecture / Process Overview**
-   - Short prose + **one diagram** selected from the list above.
-5. **Interfaces & Contracts (choose one)**
-   - **API-based**: Endpoint table (*Step, Method, Path/URL, Auth, Key Headers/Params, Sample Req/Resp ref*).
-   - **Data/Files**: I/O contract table (*Source, Format, Schema/Columns, Size, Validation rules*).
-   - **Systems/Hardware**: Interfaces table (*Port/Bus, Protocol, Voltage/Timing, Constraints*).
-6. **Repro: End-to-End Procedure**
-   - Minimal copy-paste steps with code/commands and **expected outputs**.
-7. **What Works (with Evidence)**
-   - Each item: **Time (UTC)** • **Artifact/Req IDs** • **Status/Result** • **Where to verify**.
-8. **What Doesn’t (Evidence & Hypotheses)**
-   - Each failure: locus (file/endpoint/module), evidence snippet; short hypothesis and **next probe**.
-9. **Risks, Limits, Assumptions**
-   - SLOs/limits, rate/size caps, security boundaries (CORS/CSRF/ACLs), retries/backoff/idempotency patterns.
-10. **Next Steps (Owner • Exit Criteria • Target Date)**
-    - Actionable, assigned, and time-bound.
-11. **References**
-    - Canonical docs, specs, tickets, prior analyses.
-
-> **Competence Hooks (per Base Context; keep lightweight):**
-> - *Why this works* (≤3 bullets) — core invariants or guarantees.  
-> - *Common pitfalls* (≤3 bullets) — the traps we saw in evidence.  
-> - *Next skill unlock* (1 line) — the next capability to implement/learn.  
-> - *Teach-back* (1 line) — prompt the reader to restate the flow/architecture.
-
-> **Collaboration Hooks (per Base Context):**
-> - Name reviewers for **Interfaces & Contracts** and the **diagram**.  
-> - Short **sign-off checklist** before merging/publishing the guide.
-
-## Do / Don’t (Base-aligned)
-- **Do** quantify progress only against a defined scope with acceptance criteria.
-- **Do** include minimal sample payloads/headers or I/O schemas; redact sensitive values.
-- **Do** keep commentary lean; if timeboxed, move depth to **Deferred for depth**.
-- **Don’t** use marketing language or meta narration (“Perfect!”, “tool called”, “new chat”).  
-- **Don’t** include IDE-specific chatter or internal rules unrelated to the task.
-
-## Validation Checklist (self-check before returning)
-- [ ] All Required Sections present and ordered.  
-- [ ] Diagram compiles (basic Mermaid syntax) and fits the problem.  
-- [ ] If API-based, **Auth** and **Key Headers/Params** are listed for each endpoint.  
-- [ ] Repro section includes commands/code **and expected outputs**.  
-- [ ] Every Works/Doesn’t item has **UTC timestamp**, **status/result**, and **verifiable evidence**.  
-- [ ] Next Steps include **Owner**, **Exit Criteria**, **Target Date**.  
-- [ ] Unknowns are `TODO:<missing>` — no fabrication.  
-- [ ] Base **Output Contract** sections satisfied (Objective/Result/Use/Run/Competence/Collaboration/Assumptions/References).
-
-## Universal Template (fill-in)
-```markdown
-# <Title> — Working Notes (As of YYYY-MM-DDTHH:MMZ)
-
-## Objective
-<one line>
-
-## Result
-<link to the produced guide file or say “this document”>
-
-## Use/Run
-<how to apply/test and where to run samples>
-
-## Context & Scope
-- Audience: <role(s)>
-- In scope: <bullets>
-- Out of scope: <bullets>
-
-## Artifacts & Links
-- Repo/PR: <link>
-- Data/Logs: <paths or links>
-- Scripts/Tools: <paths>
-- Dashboards: <links>
-
-## Environment & Preconditions
-- OS/Runtime: <details>
-- Versions/Builds: <list>
-- Services/Endpoints: <list>
-- Auth mode: <Bearer/Session/Keys + how acquired>
-
-## Architecture / Process Overview
-<short prose>
-```mermaid
-<one suitable diagram: sequenceDiagram | flowchart | stateDiagram | gantt | classDiagram>
-```
-
-## Interfaces & Contracts
-### If API-based
-| Step | Method | Path/URL | Auth | Key Headers/Params | Sample |
-|---|---|---|---|---|---|
-| <…> | <…> | <…> | <…> | <…> | below |
-
-### If Data/Files
-| Source | Format | Schema/Columns | Size | Validation |
-|---|---|---|---|---|
-| <…> | <…> | <…> | <…> | <…> |
-
-### If Systems/Hardware
-| Interface | Protocol | Timing/Voltage | Constraints | Notes |
-|---|---|---|---|---|
-| <…> | <…> | <…> | <…> | <…> |
-
-## Repro: End-to-End Procedure
-```bash
-# commands / curl examples (redacted where necessary)
-```
-```python
-# minimal client library example (language appropriate)
-```
-> Expected output: <snippet/checks>
-
-## What Works (Evidence)
-- ✅ <short statement>  
-  - **Time**: <YYYY-MM-DDTHH:MMZ>  
-  - **Evidence**: file/line/log or request id/status  
-  - **Verify at**: <where>
-
-## What Doesn’t (Evidence & Hypotheses)
-- ❌ <short failure> at `<component/endpoint/file>`  
-  - **Time**: <YYYY-MM-DDTHH:MMZ>  
-  - **Evidence**: <snippet/id/status>  
-  - **Hypothesis**: <short>  
-  - **Next probe**: <short>
-
-## Risks, Limits, Assumptions
-<bullets: limits, security boundaries, retries/backoff, idempotency, SLOs>
-
-## Next Steps
-| Owner | Task | Exit Criteria | Target Date (UTC) |
-|---|---|---|---|
-| <name> | <action> | <measurable outcome> | <YYYY-MM-DD> |
-
-## References
-<links/titles>
-
-## Competence Hooks
-- *Why this works*: <≤3 bullets>
-- *Common pitfalls*: <≤3 bullets>
-- *Next skill unlock*: <1 line>
-- *Teach-back*: <1 line>
-
-## Collaboration Hooks
-- Reviewers: <names/roles>
-- Sign-off checklist: <≤5 checks>
-
-## Assumptions & Limits
-<bullets>
-
-## Deferred for depth
-<park deeper material here to respect timeboxing>
-```
-
----
-
-**Notes for Implementers:**  
-- Respect Base *Do-Not* (no filler, no invented facts, no censorship).  
-- Prefer clarity over completeness when timeboxed; capture unknowns explicitly.
-- Apply historical comment management rules (see `.cursor/rules/historical_comment_management.mdc`)
-- Apply realistic time estimation rules (see `.cursor/rules/realistic_time_estimation.mdc`)

.cursor/rules/historical_comment_management.mdc

@@ -1,236 +0,0 @@
----
-description: when comments are generated by the model
-alwaysApply: false
----
-# Historical Comment Management — Harbor Pilot Directive
-
-> **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance.
-
-## 🎯 Purpose
-
-Historical comments should either be **removed entirely** or **transformed into actionable guidance** for future developers. Avoid keeping comments that merely state what was removed without explaining why or what to do instead.
-
-## 📋 Decision Framework
-
-### Remove Historical Comments When:
-- **Obsolete Information**: Comment describes functionality that no longer exists
-- **No Action Required**: Comment doesn't help future developers make decisions
-- **Outdated Context**: Comment refers to old patterns that are no longer relevant
-- **Self-Evident**: The current code clearly shows the current approach
-
-### Transform Historical Comments When:
-- **Architectural Context**: The change represents a significant pattern shift
-- **Migration Guidance**: Future developers might need to understand the evolution
-- **Decision Rationale**: The "why" behind the change is still relevant
-- **Alternative Approaches**: The comment can guide future implementation choices
-
-## 🔄 Transformation Patterns
-
-### 1. From Removal Notice to Migration Note
-```typescript
-// ❌ REMOVE THIS
-// turnOffNotifyingFlags method removed - notification state is now managed by NotificationSection component
-
-// ✅ TRANSFORM TO THIS
-// Note: Notification state management has been migrated to NotificationSection component
-// which handles its own lifecycle and persistence via PlatformServiceMixin
-```
-
-### 2. From Deprecation Notice to Implementation Guide
-```typescript
-// ❌ REMOVE THIS
-// This will be handled by the NewComponent now
-// No need to call oldMethod() as it's no longer needed
-
-// ✅ TRANSFORM TO THIS
-// Note: This functionality has been migrated to NewComponent
-// which provides better separation of concerns and testability
-```
-
-### 3. From Historical Note to Architectural Context
-```typescript
-// ❌ REMOVE THIS
-// Old approach: used direct database calls
-// New approach: uses service layer
-
-// ✅ TRANSFORM TO THIS
-// Note: Database access has been abstracted through service layer
-// for better testability and platform independence
-```
-
-## 🚫 Anti-Patterns to Remove
-
-- Comments that only state what was removed
-- Comments that don't explain the current approach
-- Comments that reference non-existent methods
-- Comments that are self-evident from the code
-- Comments that don't help future decision-making
-
-## ✅ Best Practices
-
-### When Keeping Historical Context:
-1. **Explain the "Why"**: Why was the change made?
-2. **Describe the "What"**: What is the current approach?
-3. **Provide Context**: When might this information be useful?
-4. **Use Actionable Language**: Guide future decisions, not just document history
-
-### When Removing Historical Context:
-1. **Verify Obsoleteness**: Ensure the information is truly outdated
-2. **Check for Dependencies**: Ensure no other code references the old approach
-3. **Update Related Docs**: If removing from code, consider adding to documentation
-4. **Preserve in Git History**: The change is preserved in version control
-
-## 🔍 Implementation Checklist
-
-- [ ] Identify historical comments about removed/deprecated functionality
-- [ ] Determine if comment provides actionable guidance
-- [ ] Transform useful comments into migration notes or architectural context
-- [ ] Remove comments that are purely historical without guidance value
-- [ ] Ensure remaining comments explain current approach and rationale
-- [ ] Update related documentation if significant context is removed
-
-## 📚 Examples
-
-### Good Historical Comment (Keep & Transform)
-```typescript
-// Note: Database access has been migrated from direct IndexedDB calls to PlatformServiceMixin
-// This provides better platform abstraction and consistent error handling across web/mobile/desktop
-// When adding new database operations, use this.$getContact(), this.$saveSettings(), etc.
-```
-
-### Bad Historical Comment (Remove)
-```typescript
-// Old method getContactFromDB() removed - now handled by PlatformServiceMixin
-// No need to call the old method anymore
-```
-
-## 🎯 Integration with Harbor Pilot
-
-This rule works in conjunction with:
-- **Component Creation Ideals**: Maintains architectural consistency
-- **Migration Patterns**: Documents evolution of patterns
-- **Code Review Guidelines**: Ensures comments provide value
-
-## 📝 Version History
-
-### v1.0.0 (2025-08-21)
-- Initial creation based on notification system cleanup
-- Established decision framework for historical comment management
-- Added transformation patterns and anti-patterns
-- Integrated with existing Harbor Pilot architecture rules
-# Historical Comment Management — Harbor Pilot Directive
-
-> **Agent role**: When encountering historical comments about removed methods, deprecated patterns, or architectural changes, apply these guidelines to maintain code clarity and developer guidance.
-
-## 🎯 Purpose
-
-Historical comments should either be **removed entirely** or **transformed into actionable guidance** for future developers. Avoid keeping comments that merely state what was removed without explaining why or what to do instead.
-
-## 📋 Decision Framework
-
-### Remove Historical Comments When:
-- **Obsolete Information**: Comment describes functionality that no longer exists
-- **No Action Required**: Comment doesn't help future developers make decisions
-- **Outdated Context**: Comment refers to old patterns that are no longer relevant
-- **Self-Evident**: The current code clearly shows the current approach
-
-### Transform Historical Comments When:
-- **Architectural Context**: The change represents a significant pattern shift
-- **Migration Guidance**: Future developers might need to understand the evolution
-- **Decision Rationale**: The "why" behind the change is still relevant
-- **Alternative Approaches**: The comment can guide future implementation choices
-
-## 🔄 Transformation Patterns
-
-### 1. From Removal Notice to Migration Note
-```typescript
-// ❌ REMOVE THIS
-// turnOffNotifyingFlags method removed - notification state is now managed by NotificationSection component
-
-// ✅ TRANSFORM TO THIS
-// Note: Notification state management has been migrated to NotificationSection component
-// which handles its own lifecycle and persistence via PlatformServiceMixin
-```
-
-### 2. From Deprecation Notice to Implementation Guide
-```typescript
-// ❌ REMOVE THIS
-// This will be handled by the NewComponent now
-// No need to call oldMethod() as it's no longer needed
-
-// ✅ TRANSFORM TO THIS
-// Note: This functionality has been migrated to NewComponent
-// which provides better separation of concerns and testability
-```
-
-### 3. From Historical Note to Architectural Context
-```typescript
-// ❌ REMOVE THIS
-// Old approach: used direct database calls
-// New approach: uses service layer
-
-// ✅ TRANSFORM TO THIS
-// Note: Database access has been abstracted through service layer
-// for better testability and platform independence
-```
-
-## 🚫 Anti-Patterns to Remove
-
-- Comments that only state what was removed
-- Comments that don't explain the current approach
-- Comments that reference non-existent methods
-- Comments that are self-evident from the code
-- Comments that don't help future decision-making
-
-## ✅ Best Practices
-
-### When Keeping Historical Context:
-1. **Explain the "Why"**: Why was the change made?
-2. **Describe the "What"**: What is the current approach?
-3. **Provide Context**: When might this information be useful?
-4. **Use Actionable Language**: Guide future decisions, not just document history
-
-### When Removing Historical Context:
-1. **Verify Obsoleteness**: Ensure the information is truly outdated
-2. **Check for Dependencies**: Ensure no other code references the old approach
-3. **Update Related Docs**: If removing from code, consider adding to documentation
-4. **Preserve in Git History**: The change is preserved in version control
-
-## 🔍 Implementation Checklist
-
-- [ ] Identify historical comments about removed/deprecated functionality
-- [ ] Determine if comment provides actionable guidance
-- [ ] Transform useful comments into migration notes or architectural context
-- [ ] Remove comments that are purely historical without guidance value
-- [ ] Ensure remaining comments explain current approach and rationale
-- [ ] Update related documentation if significant context is removed
-
-## 📚 Examples
-
-### Good Historical Comment (Keep & Transform)
-```typescript
-// Note: Database access has been migrated from direct IndexedDB calls to PlatformServiceMixin
-// This provides better platform abstraction and consistent error handling across web/mobile/desktop
-// When adding new database operations, use this.$getContact(), this.$saveSettings(), etc.
-```
-
-### Bad Historical Comment (Remove)
-```typescript
-// Old method getContactFromDB() removed - now handled by PlatformServiceMixin
-// No need to call the old method anymore
-```
-
-## 🎯 Integration with Harbor Pilot
-
-This rule works in conjunction with:
-- **Component Creation Ideals**: Maintains architectural consistency
-- **Migration Patterns**: Documents evolution of patterns
-- **Code Review Guidelines**: Ensures comments provide value
-
-## 📝 Version History
-
-### v1.0.0 (2025-08-21)
-- Initial creation based on notification system cleanup
-- Established decision framework for historical comment management
-- Added transformation patterns and anti-patterns
-- Integrated with existing Harbor Pilot architecture rules

.cursor/rules/meta_bug_diagnosis.mdc

@@ -0,0 +1,172 @@
+# Meta-Rule: Bug Diagnosis
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Bug investigation workflow bundling
+
+## Purpose
+
+This meta-rule bundles all the rules needed for systematic bug investigation
+and root cause analysis. Use this when bugs are reported, performance
+issues occur, or unexpected behavior happens.
+
+## When to Use
+
+- **Bug Reports**: Investigating reported bugs or issues
+- **Performance Issues**: Diagnosing slow performance or bottlenecks
+- **Unexpected Behavior**: Understanding why code behaves unexpectedly
+- **Production Issues**: Investigating issues in live environments
+- **Test Failures**: Understanding why tests are failing
+- **Integration Problems**: Diagnosing issues between components
+
+## Bundled Rules
+
+### **Investigation Process**
+
+- **`development/research_diagnostic.mdc`** - Systematic investigation
+  workflow with evidence collection and analysis
+- **`development/investigation_report_example.mdc`** - Investigation
+  documentation templates and examples
+- **`core/harbor_pilot_universal.mdc`** - Technical guide creation
+  for complex investigations
+
+### **Evidence Collection**
+
+- **`development/logging_standards.mdc`** - Logging implementation
+  standards for debugging and evidence collection
+- **`development/time.mdc`** - Timestamp requirements and time
+  handling standards for evidence
+- **`development/time_examples.mdc`** - Practical examples of
+  proper time handling in investigations
+
+### **Technical Context**
+
+- **`app/timesafari.mdc`** - Core application context and
+  architecture for understanding the system
+- **`app/timesafari_platforms.mdc`** - Platform-specific
+  considerations and constraints
+
+## Workflow Sequence
+
+### **Phase 1: Initial Investigation (Start Here)**
+
+1. **Research Diagnostic** - Use `research_diagnostic.mdc` for
+   systematic investigation approach
+2. **Evidence Collection** - Apply `logging_standards.mdc` and
+   `time.mdc` for proper evidence gathering
+3. **Context Understanding** - Review `timesafari.mdc` for
+   application context
+
+### **Phase 2: Deep Investigation**
+
+1. **Platform Analysis** - Check `timesafari_platforms.mdc` for
+   platform-specific issues
+2. **Technical Guide Creation** - Use `harbor_pilot_universal.mdc`
+   for complex investigation documentation
+3. **Evidence Analysis** - Apply `time_examples.mdc` for proper
+   timestamp handling
+
+### **Phase 3: Documentation & Reporting**
+
+1. **Investigation Report** - Use `investigation_report_example.mdc`
+   for comprehensive documentation
+2. **Root Cause Analysis** - Synthesize findings into actionable
+   insights
+
+## Success Criteria
+
+- [ ] **Root cause identified** with supporting evidence
+- [ ] **Evidence properly collected** with timestamps and context
+- [ ] **Investigation documented** using appropriate templates
+- [ ] **Platform factors considered** in diagnosis
+- [ ] **Reproduction steps documented** for verification
+- [ ] **Impact assessment completed** with scope defined
+- [ ] **Next steps identified** for resolution
+
+## Common Pitfalls
+
+- **Don't skip evidence collection** - leads to speculation
+- **Don't ignore platform differences** - misses platform-specific issues
+- **Don't skip documentation** - loses investigation insights
+- **Don't assume root cause** - verify with evidence
+- **Don't ignore time context** - misses temporal factors
+- **Don't skip reproduction steps** - makes verification impossible
+
+## Integration Points
+
+### **With Other Meta-Rules**
+
+- **Feature Planning**: Use complexity assessment for investigation planning
+- **Bug Fixing**: Investigation results feed directly into fix implementation
+- **Feature Implementation**: Investigation insights inform future development
+
+### **With Development Workflow**
+
+- Investigation findings inform testing strategy
+- Root cause analysis drives preventive measures
+- Evidence collection improves logging standards
+
+## Feedback & Improvement
+
+### **Sub-Rule Ratings (1-5 scale)**
+
+- **Research Diagnostic**: ___/5 - Comments: _______________
+- **Investigation Report**: ___/5 - Comments: _______________
+- **Technical Guide Creation**: ___/5 - Comments: _______________
+- **Logging Standards**: ___/5 - Comments: _______________
+- **Time Standards**: ___/5 - Comments: _______________
+
+### **Workflow Feedback**
+
+- **Investigation Effectiveness**: How well did the process help find root cause?
+- **Missing Steps**: What investigation steps should be added?
+- **Process Gaps**: Where did the workflow break down?
+
+### **Sub-Rule Improvements**
+
+- **Clarity Issues**: Which rules were unclear or confusing?
+- **Missing Examples**: What examples would make rules more useful?
+- **Template Improvements**: How could investigation templates be better?
+
+### **Overall Experience**
+
+- **Time Saved**: How much time did this meta-rule save you?
+- **Quality Improvement**: Did following these rules improve your investigation?
+- **Recommendation**: Would you recommend this meta-rule to others?
+
+## Model Implementation Checklist
+
+### Before Bug Investigation
+
+- [ ] **Problem Definition**: Clearly define what needs to be investigated
+- [ ] **Scope Definition**: Determine investigation scope and boundaries
+- [ ] **Evidence Planning**: Plan evidence collection strategy
+- [ ] **Stakeholder Identification**: Identify who needs to be involved
+
+### During Bug Investigation
+
+- [ ] **Rule Application**: Apply bundled rules in recommended sequence
+- [ ] **Evidence Collection**: Collect evidence systematically with timestamps
+- [ ] **Documentation**: Document investigation process and findings
+- [ ] **Validation**: Verify findings with reproduction steps
+
+### After Bug Investigation
+
+- [ ] **Report Creation**: Create comprehensive investigation report
+- [ ] **Root Cause Analysis**: Document root cause with evidence
+- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness
+- [ ] **Process Improvement**: Identify improvements for future investigations
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_feature_planning.mdc` for planning investigation work
+- `.cursor/rules/meta_bug_fixing.mdc` for implementing fixes
+- `.cursor/rules/meta_feature_implementation.mdc` for preventive measures
+
+**Status**: Active meta-rule for bug diagnosis
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Development team, QA team, DevOps team

.cursor/rules/meta_bug_fixing.mdc

@@ -0,0 +1,175 @@
+# Meta-Rule: Bug Fixing
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Bug fix implementation workflow bundling
+
+## Purpose
+
+This meta-rule bundles all the rules needed for implementing bug fixes
+with proper testing and validation. Use this after diagnosis when
+implementing the actual fix.
+
+## When to Use
+
+- **Post-Diagnosis**: After root cause is identified and fix is planned
+- **Fix Implementation**: When coding the actual bug fix
+- **Testing & Validation**: When testing the fix works correctly
+- **Code Review**: When reviewing the fix implementation
+- **Deployment**: When preparing the fix for deployment
+- **Documentation**: When documenting the fix and lessons learned
+
+## Bundled Rules
+
+### **Implementation Standards**
+
+- **`development/software_development.mdc`** - Core development
+  principles, evidence requirements, and testing strategy
+- **`development/type_safety_guide.mdc`** - Type-safe implementation
+  with proper error handling and type guards
+- **`development/logging_migration.mdc`** - Proper logging
+  implementation and migration from console.* calls
+
+### **Code Quality & Review**
+
+- **`development/historical_comment_management.mdc`** - Code quality
+  standards and comment transformation rules
+- **`development/historical_comment_patterns.mdc`** - Specific
+  patterns for transforming historical comments
+- **`development/complexity_assessment.mdc`** - Complexity evaluation
+  for fix implementation
+
+### **Platform & Testing**
+
+- **`app/timesafari_development.mdc`** - TimeSafari-specific
+  development workflow and testing requirements
+- **`app/timesafari_platforms.mdc`** - Platform-specific testing
+  and validation requirements
+- **`architecture/build_validation.mdc`** - Build system validation
+  and testing procedures
+
+## Workflow Sequence
+
+### **Phase 1: Fix Implementation (Start Here)**
+
+1. **Development Standards** - Apply `software_development.mdc` for
+   core implementation principles
+2. **Type Safety** - Use `type_safety_guide.mdc` for type-safe
+   implementation
+3. **Logging Implementation** - Apply `logging_migration.mdc` for
+   proper logging
+
+### **Phase 2: Quality & Review**
+
+1. **Code Quality** - Use `historical_comment_management.mdc` for
+   code quality standards
+2. **Complexity Assessment** - Apply `complexity_assessment.mdc` to
+   evaluate fix complexity
+3. **Code Review** - Follow review standards from bundled rules
+
+### **Phase 3: Testing & Validation**
+
+1. **Platform Testing** - Use `timesafari_platforms.mdc` for
+   platform-specific testing
+2. **Build Validation** - Apply `build_validation.mdc` for build
+   system compliance
+3. **Final Validation** - Verify fix works across all platforms
+
+## Success Criteria
+
+- [ ] **Fix implemented** following development standards
+- [ ] **Type safety maintained** with proper error handling
+- [ ] **Logging properly implemented** with component context
+- [ ] **Code quality standards met** with clean, maintainable code
+- [ ] **Testing completed** across all target platforms
+- [ ] **Build validation passed** with no build system issues
+- [ ] **Code review completed** with all feedback addressed
+- [ ] **Documentation updated** with fix details and lessons learned
+
+## Common Pitfalls
+
+- **Don't skip type safety** - leads to runtime errors
+- **Don't ignore logging** - makes future debugging harder
+- **Don't skip platform testing** - misses platform-specific issues
+- **Don't ignore code quality** - creates technical debt
+- **Don't skip build validation** - can break build system
+- **Don't forget documentation** - loses fix context for future
+
+## Integration Points
+
+### **With Other Meta-Rules**
+
+- **Bug Diagnosis**: Investigation results drive fix implementation
+- **Feature Implementation**: Fix patterns inform future development
+- **Feature Planning**: Fix complexity informs future planning
+
+### **With Development Workflow**
+
+- Fix implementation follows development standards
+- Testing strategy ensures fix quality
+- Code review maintains code quality
+
+## Feedback & Improvement
+
+### **Sub-Rule Ratings (1-5 scale)**
+
+- **Development Standards**: ___/5 - Comments: _______________
+- **Type Safety**: ___/5 - Comments: _______________
+- **Logging Migration**: ___/5 - Comments: _______________
+- **Code Quality**: ___/5 - Comments: _______________
+- **Platform Testing**: ___/5 - Comments: _______________
+
+### **Workflow Feedback**
+
+- **Implementation Clarity**: How clear was the implementation guidance?
+- **Testing Coverage**: Were testing requirements sufficient or excessive?
+- **Process Effectiveness**: How well did the workflow work for you?
+
+### **Sub-Rule Improvements**
+
+- **Clarity Issues**: Which rules were unclear or confusing?
+- **Missing Examples**: What examples would make rules more useful?
+- **Integration Problems**: Do any rules conflict or overlap?
+
+### **Overall Experience**
+
+- **Time Saved**: How much time did this meta-rule save you?
+- **Quality Improvement**: Did following these rules improve your fix?
+- **Recommendation**: Would you recommend this meta-rule to others?
+
+## Model Implementation Checklist
+
+### Before Bug Fixing
+
+- [ ] **Root Cause Understood**: Confirm root cause is clearly identified
+- [ ] **Fix Strategy Planned**: Plan implementation approach and testing
+- [ ] **Platform Impact Assessed**: Understand impact across all platforms
+- [ ] **Testing Strategy Planned**: Plan testing approach for the fix
+
+### During Bug Fixing
+
+- [ ] **Rule Application**: Apply bundled rules in recommended sequence
+- [ ] **Implementation**: Implement fix following development standards
+- [ ] **Testing**: Test fix across all target platforms
+- [ ] **Documentation**: Document implementation details and decisions
+
+### After Bug Fixing
+
+- [ ] **Validation**: Verify fix meets all success criteria
+- [ ] **Code Review**: Complete code review with team
+- [ ] **Deployment**: Deploy fix following deployment procedures
+- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflow
+- `.cursor/rules/meta_feature_implementation.mdc` for implementation patterns
+- `.cursor/rules/meta_feature_planning.mdc` for planning future work
+
+**Status**: Active meta-rule for bug fixing
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Development team, QA team, DevOps team

.cursor/rules/meta_core_always_on.mdc

@@ -0,0 +1,196 @@
+---
+alwaysApply: true
+---
+
+# Meta-Rule: Core Always-On Rules
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Core rules for every prompt
+
+## Purpose
+
+This meta-rule bundles the core rules that should be applied to **every single
+prompt** because they define fundamental behaviors, principles, and context
+that are essential for all AI interactions.
+
+## When to Use
+
+**ALWAYS** - These rules apply to every single prompt, regardless of the task
+or context. They form the foundation for all AI assistant behavior.
+
+## Bundled Rules
+
+### **Core Human Competence Principles**
+
+- **`core/base_context.mdc`** - Human competence first principles, interaction
+  guidelines, and output contract requirements
+- **`core/less_complex.mdc`** - Minimalist solution principle and complexity
+  guidelines
+
+### **Time & Context Standards**
+
+- **`development/time.mdc`** - Time handling principles and UTC standards
+- **`development/time_examples.mdc`** - Practical time implementation examples
+- **`development/time_implementation.mdc`** - Detailed time implementation
+  guidelines
+
+### **Version Control & Process**
+
+- **`workflow/version_control.mdc`** - Version control principles and commit
+  guidelines
+- **`workflow/commit_messages.mdc`** - Commit message format and conventions
+
+### **Application Context**
+
+- **`app/timesafari.mdc`** - Core TimeSafari application context and
+  development principles
+- **`app/timesafari_development.mdc`** - TimeSafari-specific development
+  workflow and quality standards
+
+## Why These Rules Are Always-On
+
+### **Base Context**
+
+- **Human Competence First**: Every interaction must increase human competence
+- **Output Contract**: All responses must follow the required structure
+- **Competence Hooks**: Learning and collaboration must be built into every response
+
+### **Time Standards**
+
+- **UTC Consistency**: All timestamps must use UTC for system operations
+- **Evidence Collection**: Time context is essential for debugging and investigation
+- **Cross-Platform**: Time handling affects all platforms and features
+
+### **Version Control**
+
+- **Commit Standards**: Every code change must follow commit message conventions
+- **Process Consistency**: Version control affects all development work
+- **Team Collaboration**: Commit standards enable effective team communication
+
+### **Application Context**
+
+- **Platform Awareness**: Every task must consider web/mobile/desktop platforms
+- **Architecture Principles**: All work must follow TimeSafari patterns
+- **Development Standards**: Quality and testing requirements apply to all work
+
+## Application Priority
+
+### **Primary (Apply First)**
+
+1. **Base Context** - Human competence and output contract
+2. **Time Standards** - UTC and timestamp requirements
+3. **Application Context** - TimeSafari principles and platforms
+
+### **Secondary (Apply as Needed)**
+
+1. **Version Control** - When making code changes
+2. **Complexity Guidelines** - When evaluating solution approaches
+
+## Integration with Other Meta-Rules
+
+### **Feature Planning**
+
+- Base context ensures human competence focus
+- Time standards inform planning and estimation
+- Application context drives platform considerations
+
+### **Bug Diagnosis**
+
+- Base context ensures systematic investigation
+- Time standards enable proper evidence collection
+- Application context provides system understanding
+
+### **Bug Fixing**
+
+- Base context ensures quality implementation
+- Time standards maintain logging consistency
+- Application context guides testing strategy
+
+### **Feature Implementation**
+
+- Base context ensures proper development approach
+- Time standards maintain system consistency
+- Application context drives architecture decisions
+
+## Success Criteria
+
+- [ ] **Base context applied** to every single prompt
+- [ ] **Time standards followed** for all timestamps and logging
+- [ ] **Version control standards** applied to all code changes
+- [ ] **Application context considered** for all platform work
+- [ ] **Human competence focus** maintained in all interactions
+- [ ] **Output contract structure** followed in all responses
+
+## Common Pitfalls
+
+- **Don't skip base context** - loses human competence focus
+- **Don't ignore time standards** - creates inconsistent timestamps
+- **Don't forget application context** - misses platform considerations
+- **Don't skip version control** - creates inconsistent commit history
+- **Don't lose competence focus** - reduces learning value
+
+## Feedback & Improvement
+
+### **Rule Effectiveness Ratings (1-5 scale)**
+
+- **Base Context**: ___/5 - Comments: _______________
+- **Time Standards**: ___/5 - Comments: _______________
+- **Version Control**: ___/5 - Comments: _______________
+- **Application Context**: ___/5 - Comments: _______________
+
+### **Always-On Effectiveness**
+
+- **Consistency**: Are these rules applied consistently across all prompts?
+- **Value**: Do these rules add value to every interaction?
+- **Overhead**: Are these rules too burdensome for simple tasks?
+
+### **Integration Feedback**
+
+- **With Other Meta-Rules**: How well do these integrate with workflow rules?
+- **Context Switching**: Do these rules help or hinder context switching?
+- **Learning Curve**: Are these rules easy for new users to understand?
+
+### **Overall Experience**
+
+- **Quality Improvement**: Do these rules improve response quality?
+- **Efficiency**: Do these rules make interactions more efficient?
+- **Recommendation**: Would you recommend keeping these always-on?
+
+## Model Implementation Checklist
+
+### Before Every Prompt
+
+- [ ] **Base Context**: Ensure human competence principles are active
+- [ ] **Time Standards**: Verify UTC and timestamp requirements are clear
+- [ ] **Application Context**: Confirm TimeSafari context is loaded
+- [ ] **Version Control**: Prepare commit standards if code changes are needed
+
+### During Response Creation
+
+- [ ] **Output Contract**: Follow required response structure
+- [ ] **Competence Hooks**: Include learning and collaboration elements
+- [ ] **Time Consistency**: Apply UTC standards for all time references
+- [ ] **Platform Awareness**: Consider all target platforms
+
+### After Response Creation
+
+- [ ] **Validation**: Verify all always-on rules were applied
+- [ ] **Quality Check**: Ensure response meets competence standards
+- [ ] **Context Review**: Confirm application context was properly considered
+- [ ] **Feedback Collection**: Note any issues with always-on application
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_feature_planning.mdc` for workflow-specific rules
+- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation workflows
+- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation
+- `.cursor/rules/meta_feature_implementation.mdc` for feature development
+
+**Status**: Active core always-on meta-rule
+**Priority**: Critical (applies to every prompt)
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: All AI interactions, Development team

.cursor/rules/meta_documentation.mdc

@@ -0,0 +1,237 @@
+# Meta-Rule: Documentation Writing & Education
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Documentation writing and education workflow
+
+## Purpose
+
+This meta-rule bundles documentation-related rules to create comprehensive,
+educational documentation that increases human competence rather than just
+providing technical descriptions.
+
+## When to Use
+
+**Use this meta-rule when**:
+- Writing new documentation
+- Updating existing documentation
+- Creating technical guides
+- Writing migration documentation
+- Creating architectural documentation
+- Writing user guides or tutorials
+
+## Bundled Rules
+
+### **Core Documentation Standards**
+
+- **`docs/markdown_core.mdc`** - Core markdown formatting and automation
+- **`docs/markdown_templates.mdc`** - Document templates and structure
+- **`docs/markdown_workflow.mdc`** - Documentation validation workflows
+
+### **Documentation Principles**
+
+- **`core/base_context.mdc`** - Human competence first principles
+- **`core/less_complex.mdc`** - Minimalist solution guidelines
+- **`development/software_development.mdc`** - Development documentation standards
+
+### **Context-Specific Rules**
+
+- **`app/timesafari.mdc`** - TimeSafari application context
+- **`app/timesafari_development.mdc`** - Development documentation patterns
+- **`architecture/architectural_patterns.mdc`** - Architecture documentation
+
+## Core Documentation Philosophy
+
+### **Education Over Technical Description**
+
+**Primary Goal**: Increase human competence and understanding
+**Secondary Goal**: Provide accurate technical information
+**Approach**: Explain the "why" before the "how"
+
+### **Human Competence Principles**
+
+1. **Context First**: Explain the problem before the solution
+2. **Learning Path**: Structure content for progressive understanding
+3. **Real Examples**: Use concrete, relatable examples
+4. **Common Pitfalls**: Warn about typical mistakes and misconceptions
+5. **Decision Context**: Explain why certain choices were made
+
+### **Documentation Hierarchy**
+
+1. **Conceptual Understanding** - What is this and why does it matter?
+2. **Context and Motivation** - When and why would you use this?
+3. **Technical Implementation** - How do you implement it?
+4. **Examples and Patterns** - What does it look like in practice?
+5. **Troubleshooting** - What can go wrong and how to fix it?
+
+## Implementation Guidelines
+
+### **Document Structure**
+
+**Mandatory Sections**:
+- **Overview**: Clear purpose and scope with educational context
+- **Why This Matters**: Business value and user benefit explanation
+- **Core Concepts**: Fundamental understanding before implementation
+- **Implementation**: Step-by-step technical guidance
+- **Examples**: Real-world usage patterns
+- **Common Issues**: Troubleshooting and prevention
+- **Next Steps**: Where to go from here
+
+**Optional Sections**:
+- **Background**: Historical context and evolution
+- **Alternatives**: Other approaches and trade-offs
+- **Advanced Topics**: Deep dive into complex scenarios
+- **References**: Additional learning resources
+
+### **Writing Style**
+
+**Educational Approach**:
+- **Conversational tone**: Write as if explaining to a colleague
+- **Progressive disclosure**: Start simple, add complexity gradually
+- **Active voice**: "You can do this" not "This can be done"
+- **Question format**: "What happens when..." to engage thinking
+- **Analogies**: Use familiar concepts to explain complex ideas
+
+**Technical Accuracy**:
+- **Precise language**: Use exact technical terms consistently
+- **Code examples**: Working, tested code snippets
+- **Version information**: Specify applicable versions and platforms
+- **Limitations**: Clearly state what the solution doesn't do
+
+### **Content Quality Standards**
+
+**Educational Value**:
+- [ ] **Concept clarity**: Reader understands the fundamental idea
+- [ ] **Context relevance**: Reader knows when to apply the knowledge
+- [ ] **Practical application**: Reader can implement the solution
+- [ ] **Problem prevention**: Reader avoids common mistakes
+- [ ] **Next steps**: Reader knows where to continue learning
+
+**Technical Accuracy**:
+- [ ] **Fact verification**: All technical details are correct
+- [ ] **Code validation**: Examples compile and run correctly
+- [ ] **Version compatibility**: Platform and version requirements clear
+- [ ] **Security consideration**: Security implications addressed
+- [ ] **Performance notes**: Performance characteristics documented
+
+## Document Types and Templates
+
+### **Technical Guides**
+
+**Focus**: Implementation and technical details
+**Structure**: Problem → Solution → Implementation → Examples
+**Education**: Explain the "why" behind technical choices
+
+### **Migration Documentation**
+
+**Focus**: Process and workflow guidance
+**Structure**: Context → Preparation → Steps → Validation → Troubleshooting
+**Education**: Help users understand migration benefits and risks
+
+### **Architecture Documentation**
+
+**Focus**: System design and decision rationale
+**Structure**: Problem → Constraints → Alternatives → Decision → Implementation
+**Education**: Explain design trade-offs and decision factors
+
+### **User Guides**
+
+**Focus**: Task completion and user empowerment
+**Structure**: Goal → Prerequisites → Steps → Verification → Next Steps
+**Education**: Help users understand the system's capabilities
+
+## Quality Assurance
+
+### **Review Checklist**
+
+**Educational Quality**:
+- [ ] **Clear learning objective**: What will the reader learn?
+- [ ] **Appropriate complexity**: Matches target audience knowledge
+- [ ] **Progressive disclosure**: Information builds logically
+- [ ] **Practical examples**: Real-world scenarios and use cases
+- [ ] **Common questions**: Anticipates and answers reader questions
+
+**Technical Quality**:
+- [ ] **Accuracy**: All technical details verified
+- [ ] **Completeness**: Covers all necessary information
+- [ ] **Consistency**: Terminology and formatting consistent
+- [ ] **Currency**: Information is up-to-date
+- [ ] **Accessibility**: Clear for target audience
+
+### **Validation Workflows**
+
+1. **Content Review**: Subject matter expert review
+2. **Educational Review**: Learning effectiveness assessment
+3. **Technical Review**: Accuracy and completeness validation
+4. **User Testing**: Real user comprehension testing
+5. **Continuous Improvement**: Regular updates based on feedback
+
+## Success Metrics
+
+### **Educational Effectiveness**
+
+- **Comprehension**: Users understand the concepts
+- **Application**: Users can implement the solutions
+- **Confidence**: Users feel capable and empowered
+- **Efficiency**: Users complete tasks faster
+- **Satisfaction**: Users find documentation helpful
+
+### **Technical Quality**
+
+- **Accuracy**: Zero technical errors
+- **Completeness**: All necessary information included
+- **Consistency**: Uniform style and format
+- **Maintainability**: Easy to update and extend
+- **Accessibility**: Clear for target audience
+
+## Common Pitfalls
+
+### **Educational Mistakes**
+
+- **Assumption overload**: Assuming too much prior knowledge
+- **Information dump**: Overwhelming with details
+- **Context missing**: Not explaining why something matters
+- **Example poverty**: Insufficient practical examples
+- **Feedback missing**: No way to verify understanding
+
+### **Technical Mistakes**
+
+- **Outdated information**: Not keeping content current
+- **Incomplete coverage**: Missing important details
+- **Inconsistent terminology**: Using different terms for same concepts
+- **Poor examples**: Non-working or confusing code
+- **Missing validation**: No way to verify correctness
+
+## Feedback and Improvement
+
+### **Continuous Learning**
+
+- **User feedback**: Collect and analyze user comments
+- **Usage metrics**: Track document usage and effectiveness
+- **Review cycles**: Regular content review and updates
+- **Community input**: Engage users in documentation improvement
+- **Best practices**: Stay current with documentation standards
+
+### **Quality Metrics**
+
+- **Readability scores**: Measure content clarity
+- **User satisfaction**: Survey-based quality assessment
+- **Task completion**: Success rate of documented procedures
+- **Support reduction**: Decrease in help requests
+- **Knowledge retention**: Long-term user understanding
+
+---
+
+**See also**:
+
+- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
+- `.cursor/rules/docs/markdown_templates.mdc` for document templates
+- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
+- `.cursor/rules/docs/meta_rule_usage_guide.md` for how to use meta-rules
+- `.cursor/rules/core/base_context.mdc` for human competence principles
+
+**Status**: Active documentation meta-rule
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Documentation team, Development team, Users

.cursor/rules/meta_feature_implementation.mdc

@@ -0,0 +1,187 @@
+# Meta-Rule: Feature Implementation
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Feature implementation workflow bundling
+
+## Purpose
+
+This meta-rule bundles all the rules needed for building features with
+proper architecture and cross-platform support. Use this when implementing
+planned features or refactoring existing code.
+
+## When to Use
+
+- **Feature Development**: Building new features from planning
+- **Code Refactoring**: Restructuring existing code for better architecture
+- **Platform Expansion**: Adding features to new platforms
+- **Service Implementation**: Building new services or components
+- **Integration Work**: Connecting features with existing systems
+- **Performance Optimization**: Improving feature performance
+
+## Bundled Rules
+
+### **Development Foundation**
+
+- **`app/timesafari_development.mdc`** - TimeSafari-specific
+  development workflow and quality standards
+- **`development/software_development.mdc`** - Core development
+  principles and evidence requirements
+- **`development/type_safety_guide.mdc`** - Type-safe implementation
+  with proper error handling
+
+### **Architecture & Patterns**
+
+- **`app/architectural_patterns.mdc`** - Design patterns and
+  architectural examples for features
+- **`app/architectural_examples.mdc`** - Implementation examples
+  and testing strategies
+- **`app/architectural_implementation.mdc`** - Implementation
+  guidelines and best practices
+
+### **Platform & Services**
+
+- **`app/timesafari_platforms.mdc`** - Platform abstraction
+  patterns and platform-specific requirements
+- **`development/asset_configuration.mdc`** - Asset management
+  and build integration
+- **`development/logging_standards.mdc`** - Proper logging
+  implementation standards
+
+### **Quality & Validation**
+
+- **`architecture/build_validation.mdc`** - Build system
+  validation and testing procedures
+- **`architecture/build_testing.mdc`** - Testing requirements
+  and feedback collection
+- **`development/complexity_assessment.mdc`** - Complexity
+  evaluation for implementation
+
+## Workflow Sequence
+
+### **Phase 1: Implementation Foundation (Start Here)**
+
+1. **Development Workflow** - Use `timesafari_development.mdc` for
+   development standards and workflow
+2. **Type Safety** - Apply `type_safety_guide.mdc` for type-safe
+   implementation
+3. **Architecture Patterns** - Use `architectural_patterns.mdc` for
+   design patterns
+
+### **Phase 2: Feature Development**
+
+1. **Platform Services** - Apply `timesafari_platforms.mdc` for
+   platform abstraction
+2. **Implementation Examples** - Use `architectural_examples.mdc`
+   for implementation guidance
+3. **Asset Configuration** - Apply `asset_configuration.mdc` for
+   asset management
+
+### **Phase 3: Quality & Testing**
+
+1. **Logging Implementation** - Use `logging_standards.mdc` for
+   proper logging
+2. **Build Validation** - Apply `build_validation.mdc` for build
+   system compliance
+3. **Testing & Feedback** - Use `build_testing.mdc` for testing
+   requirements
+
+## Success Criteria
+
+- [ ] **Feature implemented** following development standards
+- [ ] **Type safety maintained** with proper error handling
+- [ ] **Architecture patterns applied** consistently
+- [ ] **Platform abstraction implemented** correctly
+- [ ] **Logging properly implemented** with component context
+- [ ] **Assets configured** and integrated with build system
+- [ ] **Build validation passed** with no build system issues
+- [ ] **Testing completed** across all target platforms
+- [ ] **Code review completed** with all feedback addressed
+
+## Common Pitfalls
+
+- **Don't skip architecture patterns** - leads to inconsistent design
+- **Don't ignore platform abstraction** - creates platform-specific code
+- **Don't skip type safety** - leads to runtime errors
+- **Don't ignore logging** - makes future debugging harder
+- **Don't skip build validation** - can break build system
+- **Don't forget asset configuration** - leads to missing assets
+
+## Integration Points
+
+### **With Other Meta-Rules**
+
+- **Feature Planning**: Planning outputs drive implementation approach
+- **Bug Fixing**: Implementation patterns inform fix strategies
+- **Bug Diagnosis**: Implementation insights help with investigation
+
+### **With Development Workflow**
+
+- Implementation follows development standards
+- Architecture decisions drive implementation approach
+- Platform requirements inform testing strategy
+
+## Feedback & Improvement
+
+### **Sub-Rule Ratings (1-5 scale)**
+
+- **Development Workflow**: ___/5 - Comments: _______________
+- **Type Safety**: ___/5 - Comments: _______________
+- **Architecture Patterns**: ___/5 - Comments: _______________
+- **Platform Services**: ___/5 - Comments: _______________
+- **Build Validation**: ___/5 - Comments: _______________
+
+### **Workflow Feedback**
+
+- **Implementation Clarity**: How clear was the implementation guidance?
+- **Pattern Effectiveness**: How well did architecture patterns work?
+- **Platform Coverage**: How well did platform guidance cover your needs?
+
+### **Sub-Rule Improvements**
+
+- **Clarity Issues**: Which rules were unclear or confusing?
+- **Missing Examples**: What examples would make rules more useful?
+- **Integration Problems**: Do any rules conflict or overlap?
+
+### **Overall Experience**
+
+- **Time Saved**: How much time did this meta-rule save you?
+- **Quality Improvement**: Did following these rules improve your implementation?
+- **Recommendation**: Would you recommend this meta-rule to others?
+
+## Model Implementation Checklist
+
+### Before Feature Implementation
+
+- [ ] **Planning Review**: Review feature planning and requirements
+- [ ] **Architecture Planning**: Plan architecture and design patterns
+- [ ] **Platform Analysis**: Understand platform-specific requirements
+- [ ] **Testing Strategy**: Plan testing approach for the feature
+
+### During Feature Implementation
+
+- [ ] **Rule Application**: Apply bundled rules in recommended sequence
+- [ ] **Implementation**: Implement feature following development standards
+- [ ] **Testing**: Test feature across all target platforms
+- [ ] **Documentation**: Document implementation details and decisions
+
+### After Feature Implementation
+
+- [ ] **Validation**: Verify feature meets all success criteria
+- [ ] **Code Review**: Complete code review with team
+- [ ] **Testing**: Complete comprehensive testing across platforms
+- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_feature_planning.mdc` for planning workflow
+- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation patterns
+- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation insights
+
+**Status**: Active meta-rule for feature implementation
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Development team, Architecture team, QA team

.cursor/rules/meta_feature_planning.mdc

@@ -0,0 +1,165 @@
+# Meta-Rule: Feature Planning
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Feature planning workflow bundling
+
+## Purpose
+
+This meta-rule bundles all the rules needed for comprehensive feature planning
+across all platforms. Use this when starting any new feature development,
+planning sprints, or estimating work effort.
+
+## When to Use
+
+- **New Feature Development**: Planning features from concept to implementation
+- **Sprint Planning**: Estimating effort and breaking down work
+- **Architecture Decisions**: Planning major architectural changes
+- **Platform Expansion**: Adding features to new platforms
+- **Refactoring Planning**: Planning significant code restructuring
+
+## Bundled Rules
+
+### **Core Planning Foundation**
+
+- **`development/planning_examples.mdc`** - Planning templates, examples, and
+  best practices for structured planning
+- **`development/realistic_time_estimation.mdc`** - Time estimation framework
+  with complexity-based phases and milestones
+- **`development/complexity_assessment.mdc`** - Technical and business
+  complexity evaluation with risk assessment
+
+### **Platform & Architecture**
+
+- **`app/timesafari_platforms.mdc`** - Platform-specific requirements,
+  constraints, and capabilities across web/mobile/desktop
+- **`app/architectural_decision_record.mdc`** - ADR process for documenting
+  major architectural decisions and trade-offs
+
+### **Development Context**
+
+- **`app/timesafari.mdc`** - Core application context, principles, and
+  development focus areas
+- **`app/timesafari_development.mdc`** - TimeSafari-specific development
+  workflow and quality standards
+
+## Workflow Sequence
+
+### **Phase 1: Foundation (Start Here)**
+
+1. **Complexity Assessment** - Use `complexity_assessment.mdc` to evaluate
+   technical and business complexity
+2. **Time Estimation** - Apply `realistic_time_estimation.mdc` framework
+   based on complexity results
+3. **Core Planning** - Use `planning_examples.mdc` for structured planning
+   approach
+
+### **Phase 2: Platform & Architecture**
+
+1. **Platform Analysis** - Review `timesafari_platforms.mdc` for
+   platform-specific requirements
+2. **Architecture Planning** - Use `architectural_decision_record.mdc` if
+   major architectural changes are needed
+
+### **Phase 3: Implementation Planning**
+
+1. **Development Workflow** - Reference `timesafari_development.mdc` for
+   development standards and testing strategy
+2. **Final Planning** - Consolidate all inputs into comprehensive plan
+
+## Success Criteria
+
+- [ ] **Complexity assessed** and documented with risk factors
+- [ ] **Time estimate created** with clear phases and milestones
+- [ ] **Platform requirements identified** for all target platforms
+- [ ] **Architecture decisions documented** (if major changes needed)
+- [ ] **Testing strategy planned** with platform-specific considerations
+- [ ] **Dependencies mapped** between tasks and phases
+- [ ] **Stakeholder input gathered** and incorporated
+
+## Common Pitfalls
+
+- **Don't skip complexity assessment** - leads to unrealistic estimates
+- **Don't estimate without platform analysis** - misses platform-specific work
+- **Don't plan without stakeholder input** - creates misaligned expectations
+- **Don't ignore testing strategy** - leads to incomplete planning
+- **Don't skip architecture decisions** - creates technical debt
+
+## Integration Points
+
+### **With Other Meta-Rules**
+
+- **Bug Diagnosis**: Use complexity assessment for bug investigation planning
+- **Feature Implementation**: This planning feeds directly into implementation
+- **Code Review**: Planning standards inform review requirements
+
+### **With Development Workflow**
+
+- Planning outputs become inputs for sprint planning
+- Complexity assessment informs testing strategy
+- Platform requirements drive architecture decisions
+
+## Feedback & Improvement
+
+### **Sub-Rule Ratings (1-5 scale)**
+
+- **Complexity Assessment**: ___/5 - Comments: _______________
+- **Time Estimation**: ___/5 - Comments: _______________
+- **Planning Examples**: ___/5 - Comments: _______________
+- **Platform Analysis**: ___/5 - Comments: _______________
+- **Architecture Decisions**: ___/5 - Comments: _______________
+
+### **Workflow Feedback**
+
+- **Sequence Effectiveness**: Did the recommended order work for you?
+- **Missing Guidance**: What additional information would have helped?
+- **Process Gaps**: Where did the workflow break down?
+
+### **Sub-Rule Improvements**
+
+- **Clarity Issues**: Which rules were unclear or confusing?
+- **Missing Examples**: What examples would make rules more useful?
+- **Integration Problems**: Do any rules conflict or overlap?
+
+### **Overall Experience**
+
+- **Time Saved**: How much time did this meta-rule save you?
+- **Quality Improvement**: Did following these rules improve your planning?
+- **Recommendation**: Would you recommend this meta-rule to others?
+
+## Model Implementation Checklist
+
+### Before Feature Planning
+
+- [ ] **Scope Definition**: Clearly define the feature scope and boundaries
+- [ ] **Stakeholder Identification**: Identify all stakeholders and decision makers
+- [ ] **Platform Requirements**: Understand target platforms and constraints
+- [ ] **Complexity Assessment**: Plan complexity evaluation approach
+
+### During Feature Planning
+
+- [ ] **Rule Application**: Apply bundled rules in recommended sequence
+- [ ] **Documentation**: Document all planning decisions and rationale
+- [ ] **Stakeholder Input**: Gather and incorporate stakeholder feedback
+- [ ] **Validation**: Validate planning against success criteria
+
+### After Feature Planning
+
+- [ ] **Plan Review**: Review plan with stakeholders and team
+- [ ] **Feedback Collection**: Collect feedback on meta-rule effectiveness
+- [ ] **Documentation Update**: Update relevant documentation
+- [ ] **Process Improvement**: Identify improvements for future planning
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_bug_diagnosis.mdc` for investigation planning
+- `.cursor/rules/meta_feature_implementation.mdc` for implementation workflow
+- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation
+
+**Status**: Active meta-rule for feature planning
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Development team, Product team, Architecture team

.cursor/rules/meta_research.mdc

@@ -0,0 +1,247 @@
+# Meta-Rule: Enhanced Research Workflows
+
+**Author**: Matthew Raymer
+**Date**: 2025-01-27
+**Status**: 🎯 **ACTIVE** - Research and investigation workflows
+
+## Purpose
+
+This meta-rule bundles research-specific rules that should be applied when conducting
+systematic investigation, analysis, evidence collection, or research tasks. It provides
+a comprehensive framework for thorough, methodical research workflows that produce
+actionable insights and evidence-based conclusions.
+
+## When to Use
+
+**RESEARCH TASKS** - Apply this meta-rule when:
+
+- Investigating bugs, defects, or system issues
+- Conducting technical research or feasibility analysis
+- Analyzing codebases, architectures, or dependencies
+- Researching solutions, alternatives, or best practices
+- Collecting evidence for decision-making or documentation
+- Performing root cause analysis or impact assessment
+
+## Bundled Rules
+
+### **Core Research Principles**
+
+- **`development/research_diagnostic.mdc`** - Systematic investigation workflow
+  and evidence collection methodology
+- **`development/type_safety_guide.mdc`** - Type analysis and safety research
+  for TypeScript/JavaScript codebases
+
+### **Investigation & Analysis**
+
+- **`workflow/version_control.mdc`** - Git history analysis and commit research
+- **`workflow/commit_messages.mdc`** - Commit pattern analysis and history
+  investigation
+
+### **Platform & Context Research**
+
+- **`app/timesafari.mdc`** - Application context research and platform
+  understanding
+- **`app/timesafari_platforms.mdc`** - Platform-specific research and
+  capability analysis
+
+## Why These Rules Are Research-Focused
+
+### **Research Diagnostic**
+
+- **Systematic Approach**: Provides structured investigation methodology
+- **Evidence Collection**: Ensures thorough data gathering and documentation
+- **Root Cause Analysis**: Guides systematic problem investigation
+- **Impact Assessment**: Helps evaluate scope and consequences
+
+### **Type Safety Research**
+
+- **Code Analysis**: Enables systematic type system investigation
+- **Safety Assessment**: Guides research into type-related issues
+- **Migration Planning**: Supports research for architectural changes
+
+### **Version Control Research**
+
+- **History Analysis**: Enables investigation of code evolution
+- **Pattern Recognition**: Helps identify commit and change patterns
+- **Timeline Research**: Supports chronological investigation
+
+### **Platform Research**
+
+- **Capability Analysis**: Guides research into platform-specific features
+- **Context Understanding**: Ensures research considers application context
+- **Cross-Platform Research**: Supports multi-platform investigation
+
+## Application Priority
+
+### **Primary (Apply First)**
+
+1. **Research Diagnostic** - Systematic investigation methodology
+2. **Type Safety Guide** - Code analysis and type research
+3. **Application Context** - Platform and context understanding
+
+### **Secondary (Apply as Needed)**
+
+1. **Version Control** - When investigating code history
+2. **Platform Details** - When researching platform-specific capabilities
+
+## Integration with Other Meta-Rules
+
+### **Bug Diagnosis**
+
+- Research meta-rule provides investigation methodology
+- Core always-on ensures systematic approach
+- Application context provides system understanding
+
+### **Feature Planning**
+
+- Research meta-rule guides feasibility research
+- Core always-on ensures competence focus
+- Application context drives platform considerations
+
+### **Architecture Analysis**
+
+- Research meta-rule provides systematic analysis framework
+- Core always-on ensures quality standards
+- Application context informs architectural decisions
+
+### **Performance Investigation**
+
+- Research meta-rule guides systematic performance research
+- Core always-on ensures thorough investigation
+- Application context provides performance context
+
+## Research Workflow Phases
+
+### **Phase 1: Investigation Setup**
+
+1. **Scope Definition** - Define research boundaries and objectives
+2. **Context Gathering** - Collect relevant application and platform context
+3. **Methodology Selection** - Choose appropriate research approaches
+
+### **Phase 2: Evidence Collection**
+
+1. **Systematic Data Gathering** - Collect evidence using structured methods
+2. **Documentation** - Record all findings and observations
+3. **Validation** - Verify evidence accuracy and relevance
+
+### **Phase 3: Analysis & Synthesis**
+
+1. **Pattern Recognition** - Identify trends and patterns in evidence
+2. **Root Cause Analysis** - Determine underlying causes and factors
+3. **Impact Assessment** - Evaluate scope and consequences
+
+### **Phase 4: Conclusion & Action**
+
+1. **Evidence-Based Conclusions** - Draw conclusions from collected evidence
+2. **Actionable Recommendations** - Provide specific, implementable guidance
+3. **Documentation** - Create comprehensive research documentation
+
+## Success Criteria
+
+- [ ] **Research diagnostic applied** to all investigation tasks
+- [ ] **Type safety research** conducted for code analysis
+- [ ] **Evidence collection** systematic and comprehensive
+- [ ] **Root cause analysis** thorough and accurate
+- [ ] **Conclusions actionable** and evidence-based
+- [ ] **Documentation complete** and searchable
+
+## Common Research Pitfalls
+
+- **Don't skip systematic approach** - leads to incomplete investigation
+- **Don't ignore evidence validation** - creates unreliable conclusions
+- **Don't forget context** - misses important factors
+- **Don't skip documentation** - loses research value
+- **Don't rush conclusions** - produces poor recommendations
+
+## Research Quality Standards
+
+### **Evidence Quality**
+
+- **Completeness**: All relevant evidence collected
+- **Accuracy**: Evidence verified and validated
+- **Relevance**: Evidence directly addresses research questions
+- **Timeliness**: Evidence current and up-to-date
+
+### **Analysis Quality**
+
+- **Systematic**: Analysis follows structured methodology
+- **Objective**: Analysis free from bias and assumptions
+- **Thorough**: All evidence considered and evaluated
+- **Logical**: Conclusions follow from evidence
+
+### **Documentation Quality**
+
+- **Comprehensive**: All findings and methods documented
+- **Searchable**: Documentation easily findable and navigable
+- **Actionable**: Recommendations specific and implementable
+- **Maintainable**: Documentation structure supports updates
+
+## Feedback & Improvement
+
+### **Rule Effectiveness Ratings (1-5 scale)**
+
+- **Research Diagnostic**: ___/5 - Comments: _______________
+- **Type Safety Guide**: ___/5 - Comments: _______________
+- **Version Control**: ___/5 - Comments: _______________
+- **Platform Context**: ___/5 - Comments: _______________
+
+### **Research Workflow Effectiveness**
+
+- **Investigation Quality**: Are research tasks producing thorough results?
+- **Evidence Collection**: Is evidence gathering systematic and complete?
+- **Conclusion Quality**: Are conclusions actionable and evidence-based?
+- **Documentation Value**: Is research documentation useful and maintainable?
+
+### **Integration Feedback**
+
+- **With Other Meta-Rules**: How well does this integrate with workflow rules?
+- **Context Switching**: Do these rules help or hinder research context?
+- **Learning Curve**: Are these rules easy for new researchers to understand?
+
+### **Overall Research Experience**
+
+- **Quality Improvement**: Do these rules improve research outcomes?
+- **Efficiency**: Do these rules make research more efficient?
+- **Recommendation**: Would you recommend keeping this research meta-rule?
+
+## Model Implementation Checklist
+
+### Before Research Tasks
+
+- [ ] **Research Diagnostic**: Ensure systematic investigation methodology
+- [ ] **Type Safety Guide**: Prepare for code analysis if needed
+- [ ] **Application Context**: Load relevant platform and context information
+- [ ] **Version Control**: Prepare for history analysis if needed
+
+### During Research Execution
+
+- [ ] **Systematic Approach**: Follow structured investigation methodology
+- [ ] **Evidence Collection**: Gather comprehensive and validated evidence
+- [ ] **Documentation**: Record all findings and observations
+- [ ] **Context Awareness**: Consider application and platform context
+
+### After Research Completion
+
+- [ ] **Validation**: Verify all research phases completed
+- [ ] **Quality Check**: Ensure research meets quality standards
+- [ ] **Documentation Review**: Confirm research properly documented
+- [ ] **Feedback Collection**: Note any issues with research process
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_core_always_on.mdc` for core always-on rules
+- `.cursor/rules/meta_feature_planning.mdc` for feature development workflows
+- `.cursor/rules/meta_bug_diagnosis.mdc` for bug investigation workflows
+- `.cursor/rules/meta_bug_fixing.mdc` for fix implementation workflows
+
+**Status**: Active research meta-rule
+**Priority**: High (applies to all research tasks)
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Development team, Research team, Quality Assurance team
+description:
+globs:
+alwaysApply: false
+---

.cursor/rules/meta_rule_architecture.md

@@ -0,0 +1,103 @@
+# Meta-Rule Architecture Overview
+
+**Author**: Matthew Raymer
+**Date**: 2025-01-27
+**Status**: 📋 **ACTIVE** - Meta-rule organization and relationships
+
+## Meta-Rule Structure
+
+### **Core Always-On Rules** (`meta_core_always_on.mdc`)
+- **Purpose**: Applied to every single prompt
+- **Scope**: Human competence, time standards, version control, application context
+- **Priority**: Critical - foundation for all interactions
+
+### **Enhanced Research Workflows** (`meta_research.mdc`) ⭐ **NEW**
+- **Purpose**: Applied to research, investigation, and analysis tasks
+- **Scope**: Systematic investigation, evidence collection, root cause analysis
+- **Priority**: High - applies to all research tasks
+- **Bundles**: Research diagnostic, type safety, version control research, platform context
+
+### **Feature Development Workflows** (`meta_feature_planning.mdc`)
+- **Purpose**: Applied to feature planning and development tasks
+- **Scope**: Requirements analysis, architecture planning, implementation strategy
+- **Priority**: High - applies to feature development
+
+### **Bug Investigation Workflows** (`meta_bug_diagnosis.mdc`)
+- **Purpose**: Applied to bug investigation and diagnosis tasks
+- **Scope**: Defect analysis, evidence collection, root cause identification
+- **Priority**: High - applies to bug investigation
+
+### **Bug Fixing Workflows** (`meta_bug_fixing.mdc`)
+- **Purpose**: Applied to bug fixing and resolution tasks
+- **Scope**: Fix implementation, testing, validation
+- **Priority**: High - applies to bug resolution
+
+## Research Meta-Rule Integration
+
+### **When to Use Research Meta-Rule**
+
+The research meta-rule should be applied when:
+- **Investigating bugs** - systematic defect analysis
+- **Researching solutions** - feasibility and alternative analysis
+- **Analyzing codebases** - architecture and dependency research
+- **Collecting evidence** - systematic data gathering
+- **Root cause analysis** - systematic problem investigation
+- **Impact assessment** - scope and consequence evaluation
+
+### **How It Complements Other Meta-Rules**
+
+- **Core Always-On**: Provides foundation (competence, time, context)
+- **Research**: Adds systematic investigation methodology
+- **Feature Planning**: Guides feasibility research and analysis
+- **Bug Diagnosis**: Provides investigation framework
+- **Bug Fixing**: Informs fix strategy through research
+
+### **Research Workflow Phases**
+
+1. **Investigation Setup** - Scope, context, methodology
+2. **Evidence Collection** - Systematic data gathering
+3. **Analysis & Synthesis** - Pattern recognition, root cause
+4. **Conclusion & Action** - Evidence-based recommendations
+
+## Usage Examples
+
+### **Bug Investigation**
+```
+Apply: meta_core_always_on + meta_research + meta_bug_diagnosis
+Result: Systematic investigation with evidence collection and root cause analysis
+```
+
+### **Feature Research**
+```
+Apply: meta_core_always_on + meta_research + meta_feature_planning
+Result: Comprehensive feasibility research with platform context
+```
+
+### **Architecture Analysis**
+```
+Apply: meta_core_always_on + meta_research
+Result: Systematic architecture investigation with evidence-based conclusions
+```
+
+## Benefits of Enhanced Research Meta-Rule
+
+- **Systematic Approach**: Structured investigation methodology
+- **Evidence-Based**: Comprehensive data collection and validation
+- **Quality Standards**: Defined research quality criteria
+- **Integration**: Seamless integration with existing workflows
+- **Documentation**: Comprehensive research documentation standards
+
+## Next Steps
+
+1. **Test Research Meta-Rule** - Apply to next research task
+2. **Validate Integration** - Ensure smooth workflow integration
+3. **Collect Feedback** - Gather effectiveness ratings
+4. **Iterate** - Refine based on usage experience
+
+---
+
+**Status**: Active documentation
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All meta-rules
+**Stakeholders**: Development team, Research team

.cursor/rules/realistic_time_estimation.mdc

@@ -1,348 +0,0 @@
----
-description: when generating text that has project task work estimates
-alwaysApply: false
----
-# No Time Estimates — Harbor Pilot Directive
-
-> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, milestones, and complexity levels. Time estimates are consistently wrong and create unrealistic expectations.
-
-## 🎯 Purpose
-
-Development time estimates are consistently wrong and create unrealistic expectations. This rule ensures we focus on phases, milestones, and complexity rather than trying to predict specific timeframes.
-
-## 🚨 Critical Rule
-
-**DO NOT MAKE TIME ESTIMATES**
-- **Never provide specific time estimates** - they are always wrong
-- **Use phases and milestones** instead of days/weeks
-- **Focus on complexity and dependencies** rather than time
-- **Set expectations based on progress, not deadlines**
-
-## 📊 Planning Framework (Not Time Estimates)
-
-### **Complexity Categories**
-- **Simple**: Text changes, styling updates, minor bug fixes
-- **Medium**: New features, refactoring, component updates
-- **Complex**: Architecture changes, integrations, cross-platform work
-- **Unknown**: New technologies, APIs, or approaches
-
-### **Platform Complexity**
-- **Single platform**: Web-only or mobile-only changes
-- **Two platforms**: Web + mobile or web + desktop
-- **Three platforms**: Web + mobile + desktop
-- **Cross-platform consistency**: Ensuring behavior matches across all platforms
-
-### **Testing Complexity**
-- **Basic**: Unit tests for new functionality
-- **Comprehensive**: Integration tests, cross-platform testing
-- **User acceptance**: User testing, feedback integration
-
-## 🔍 Planning Process (No Time Estimates)
-
-### **Step 1: Break Down the Work**
-- Identify all subtasks and dependencies
-- Group related work into logical phases
-- Identify critical path and blockers
-
-### **Step 2: Define Phases and Milestones**
-- **Phase 1**: Foundation work (basic fixes, core functionality)
-- **Phase 2**: Enhancement work (new features, integrations)
-- **Phase 3**: Polish work (testing, user experience, edge cases)
-
-### **Step 3: Identify Dependencies**
-- **Technical dependencies**: What must be built first
-- **Platform dependencies**: What works on which platforms
-- **Testing dependencies**: What can be tested when
-
-### **Step 4: Set Progress Milestones**
-- **Milestone 1**: Basic functionality working
-- **Milestone 2**: All platforms supported
-- **Milestone 3**: Fully tested and polished
-
-## 📋 Planning Checklist (No Time Estimates)
-
-- [ ] Work broken down into logical phases
-- [ ] Dependencies identified and mapped
-- [ ] Milestones defined with clear criteria
-- [ ] Complexity levels assigned to each phase
-- [ ] Platform requirements identified
-- [ ] Testing strategy planned
-- [ ] Risk factors identified
-- [ ] Success criteria defined
-
-## 🎯 Example Planning (No Time Estimates)
-
-### **Example 1: Simple Feature**
-```
-Phase 1: Core implementation
-- Basic functionality
-- Single platform support
-- Unit tests
-
-Phase 2: Platform expansion
-- Multi-platform support
-- Integration tests
-
-Phase 3: Polish
-- User testing
-- Edge case handling
-```
-
-### **Example 2: Complex Cross-Platform Feature**
-```
-Phase 1: Foundation
-- Architecture design
-- Core service implementation
-- Basic web platform support
-
-Phase 2: Platform Integration
-- Mobile platform support
-- Desktop platform support
-- Cross-platform consistency
-
-Phase 3: Testing & Polish
-- Comprehensive testing
-- Error handling
-- User experience refinement
-```
-
-## 🚫 Anti-Patterns to Avoid
-
-- **"This should take X days"** - Red flag for time estimation
-- **"Just a few hours"** - Ignores complexity and testing
-- **"Similar to X"** - Without considering differences
-- **"Quick fix"** - Nothing is ever quick in software
-- **"No testing needed"** - Testing always takes effort
-
-## ✅ Best Practices
-
-### **When Planning:**
-1. **Break down everything** - no work is too small to plan
-2. **Consider all platforms** - web, mobile, desktop differences
-3. **Include testing strategy** - unit, integration, and user testing
-4. **Account for unknowns** - there are always surprises
-5. **Focus on dependencies** - what blocks what
-
-### **When Presenting Plans:**
-1. **Show the phases** - explain the logical progression
-2. **Highlight dependencies** - what could block progress
-3. **Define milestones** - clear success criteria
-4. **Identify risks** - what could go wrong
-5. **Suggest alternatives** - ways to reduce scope or complexity
-
-## 🔄 Continuous Improvement
-
-### **Track Progress**
-- Record planned vs. actual phases completed
-- Identify what took longer than expected
-- Learn from complexity misjudgments
-- Adjust planning process based on experience
-
-### **Learn from Experience**
-- **Underestimated complexity**: Increase complexity categories
-- **Missed dependencies**: Improve dependency mapping
-- **Platform surprises**: Better platform research upfront
-
-## 🎯 Integration with Harbor Pilot
-
-This rule works in conjunction with:
-- **Project Planning**: Focuses on phases and milestones
-- **Resource Allocation**: Based on complexity, not time
-- **Risk Management**: Identifies blockers and dependencies
-- **Stakeholder Communication**: Sets progress-based expectations
-
-## 📝 Version History
-
-### v2.0.0 (2025-08-21)
-- **Major Change**: Completely removed time estimation approach
-- **New Focus**: Phases, milestones, and complexity-based planning
-- **Eliminated**: All time multipliers, estimates, and calculations
-- **Added**: Dependency mapping and progress milestone framework
-
-### v1.0.0 (2025-08-21)
-- Initial creation based on user feedback about estimation accuracy
-- ~~Established realistic estimation multipliers and process~~
-- ~~Added comprehensive estimation checklist and examples~~
-- Integrated with Harbor Pilot planning and risk management
-
----
-
-## 🚨 Remember
-
-**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.**
-
-## 🚨 Remember
-
-**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.**
-# No Time Estimates — Harbor Pilot Directive
-
-> **Agent role**: **DO NOT MAKE TIME ESTIMATES**. Instead, use phases, milestones, and complexity levels. Time estimates are consistently wrong and create unrealistic expectations.
-
-## 🎯 Purpose
-
-Development time estimates are consistently wrong and create unrealistic expectations. This rule ensures we focus on phases, milestones, and complexity rather than trying to predict specific timeframes.
-
-## 🚨 Critical Rule
-
-**DO NOT MAKE TIME ESTIMATES**
-- **Never provide specific time estimates** - they are always wrong
-- **Use phases and milestones** instead of days/weeks
-- **Focus on complexity and dependencies** rather than time
-- **Set expectations based on progress, not deadlines**
-
-## 📊 Planning Framework (Not Time Estimates)
-
-### **Complexity Categories**
-- **Simple**: Text changes, styling updates, minor bug fixes
-- **Medium**: New features, refactoring, component updates
-- **Complex**: Architecture changes, integrations, cross-platform work
-- **Unknown**: New technologies, APIs, or approaches
-
-### **Platform Complexity**
-- **Single platform**: Web-only or mobile-only changes
-- **Two platforms**: Web + mobile or web + desktop
-- **Three platforms**: Web + mobile + desktop
-- **Cross-platform consistency**: Ensuring behavior matches across all platforms
-
-### **Testing Complexity**
-- **Basic**: Unit tests for new functionality
-- **Comprehensive**: Integration tests, cross-platform testing
-- **User acceptance**: User testing, feedback integration
-
-## 🔍 Planning Process (No Time Estimates)
-
-### **Step 1: Break Down the Work**
-- Identify all subtasks and dependencies
-- Group related work into logical phases
-- Identify critical path and blockers
-
-### **Step 2: Define Phases and Milestones**
-- **Phase 1**: Foundation work (basic fixes, core functionality)
-- **Phase 2**: Enhancement work (new features, integrations)
-- **Phase 3**: Polish work (testing, user experience, edge cases)
-
-### **Step 3: Identify Dependencies**
-- **Technical dependencies**: What must be built first
-- **Platform dependencies**: What works on which platforms
-- **Testing dependencies**: What can be tested when
-
-### **Step 4: Set Progress Milestones**
-- **Milestone 1**: Basic functionality working
-- **Milestone 2**: All platforms supported
-- **Milestone 3**: Fully tested and polished
-
-## 📋 Planning Checklist (No Time Estimates)
-
-- [ ] Work broken down into logical phases
-- [ ] Dependencies identified and mapped
-- [ ] Milestones defined with clear criteria
-- [ ] Complexity levels assigned to each phase
-- [ ] Platform requirements identified
-- [ ] Testing strategy planned
-- [ ] Risk factors identified
-- [ ] Success criteria defined
-
-## 🎯 Example Planning (No Time Estimates)
-
-### **Example 1: Simple Feature**
-```
-Phase 1: Core implementation
-- Basic functionality
-- Single platform support
-- Unit tests
-
-Phase 2: Platform expansion
-- Multi-platform support
-- Integration tests
-
-Phase 3: Polish
-- User testing
-- Edge case handling
-```
-
-### **Example 2: Complex Cross-Platform Feature**
-```
-Phase 1: Foundation
-- Architecture design
-- Core service implementation
-- Basic web platform support
-
-Phase 2: Platform Integration
-- Mobile platform support
-- Desktop platform support
-- Cross-platform consistency
-
-Phase 3: Testing & Polish
-- Comprehensive testing
-- Error handling
-- User experience refinement
-```
-
-## 🚫 Anti-Patterns to Avoid
-
-- **"This should take X days"** - Red flag for time estimation
-- **"Just a few hours"** - Ignores complexity and testing
-- **"Similar to X"** - Without considering differences
-- **"Quick fix"** - Nothing is ever quick in software
-- **"No testing needed"** - Testing always takes effort
-
-## ✅ Best Practices
-
-### **When Planning:**
-1. **Break down everything** - no work is too small to plan
-2. **Consider all platforms** - web, mobile, desktop differences
-3. **Include testing strategy** - unit, integration, and user testing
-4. **Account for unknowns** - there are always surprises
-5. **Focus on dependencies** - what blocks what
-
-### **When Presenting Plans:**
-1. **Show the phases** - explain the logical progression
-2. **Highlight dependencies** - what could block progress
-3. **Define milestones** - clear success criteria
-4. **Identify risks** - what could go wrong
-5. **Suggest alternatives** - ways to reduce scope or complexity
-
-## 🔄 Continuous Improvement
-
-### **Track Progress**
-- Record planned vs. actual phases completed
-- Identify what took longer than expected
-- Learn from complexity misjudgments
-- Adjust planning process based on experience
-
-### **Learn from Experience**
-- **Underestimated complexity**: Increase complexity categories
-- **Missed dependencies**: Improve dependency mapping
-- **Platform surprises**: Better platform research upfront
-
-## 🎯 Integration with Harbor Pilot
-
-This rule works in conjunction with:
-- **Project Planning**: Focuses on phases and milestones
-- **Resource Allocation**: Based on complexity, not time
-- **Risk Management**: Identifies blockers and dependencies
-- **Stakeholder Communication**: Sets progress-based expectations
-
-## 📝 Version History
-
-### v2.0.0 (2025-08-21)
-- **Major Change**: Completely removed time estimation approach
-- **New Focus**: Phases, milestones, and complexity-based planning
-- **Eliminated**: All time multipliers, estimates, and calculations
-- **Added**: Dependency mapping and progress milestone framework
-
-### v1.0.0 (2025-08-21)
-- Initial creation based on user feedback about estimation accuracy
-- ~~Established realistic estimation multipliers and process~~
-- ~~Added comprehensive estimation checklist and examples~~
-- Integrated with Harbor Pilot planning and risk management
-
----
-
-## 🚨 Remember
-
-**DO NOT MAKE TIME ESTIMATES. Use phases, milestones, and complexity instead. Focus on progress, not deadlines.**
-
-## 🚨 Remember
-
-**Your first estimate is wrong. Your second estimate is probably still wrong. Focus on progress, not deadlines.**

.cursor/rules/templates/adr_template.mdc

@@ -1,3 +1,7 @@
+---
+alwaysApply: false
+---
+
 # ADR Template
 
 ## ADR-XXXX-YY-ZZ: [Short Title]
@@ -11,37 +15,47 @@
 
 [Describe the forces at play, including technological, political, social, and
 project local. These forces are probably in tension, and should be called out as
-such. The language in this section is value-neutral. It is simply describing facts.]
+such. The language in this section is value-neutral. It is simply describing
+  facts.]
 
 ## Decision
 
-[Describe our response to these forces. We will use the past tense ("We will...").]
+[Describe our response to these forces. We will use the past tense (
+  "We will...").]
 
 ## Consequences
 
 ### Positive
+
 - [List positive consequences]
 
 ### Negative
+
 - [List negative consequences or trade-offs]
 
 ### Neutral
+
 - [List neutral consequences or notes]
 
 ## Alternatives Considered
 
 - **Alternative 1:** [Description] - [Why rejected]
+
 - **Alternative 2:** [Description] - [Why rejected]
+
 - **Alternative 3:** [Description] - [Why rejected]
 
 ## Implementation Notes
 
-[Any specific implementation details, migration steps, or technical considerations]
+[Any specific implementation details, migration steps, or
+  technical considerations]
 
 ## References
 
 - [Link to relevant documentation]
+
 - [Link to related ADRs]
+
 - [Link to external resources]
 
 ## Related Decisions
@@ -59,7 +73,26 @@ such. The language in this section is value-neutral. It is simply describing fac
 5. **Link to related issues** and documentation
 6. **Update status** as decisions evolve
 7. **Store in** `doc/architecture-decisions/` directory
-description:
+
-globs:
+## Model Implementation Checklist
-alwaysApply: false
+
----
+### Before ADR Creation
+
+- [ ] **Decision Context**: Understand the decision that needs to be made
+- [ ] **Stakeholder Identification**: Identify all decision makers
+- [ ] **Research**: Research alternatives and gather evidence
+- [ ] **Template Selection**: Choose appropriate ADR template
+
+### During ADR Creation
+
+- [ ] **Context Documentation**: Document the context and forces at play
+- [ ] **Decision Recording**: Record the decision and rationale
+- [ ] **Consequences Analysis**: Analyze positive, negative, and neutral consequences
+- [ ] **Alternatives Documentation**: Document alternatives considered
+
+### After ADR Creation
+
+- [ ] **Review**: Review ADR with stakeholders
+- [ ] **Approval**: Get approval from decision makers
+- [ ] **Communication**: Communicate decision to team
+- [ ] **Implementation**: Plan implementation of the decision

.cursor/rules/workflow/commit_messages.mdc

@@ -0,0 +1,196 @@
+# Commit Message Format and Templates
+
+> **Agent role**:
+  Reference this file for commit message formatting and templates.
+
+## Commit Message Format (Normative)
+
+### A. Subject Line (required)
+
+```
+
+<type>(<scope>)<!>: <summary>
+
+```
+
+- **type** (lowercase, Conventional Commits):
+
+  `feat|fix|refactor|perf|docs|test|build|chore|ci|revert`
+
+- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`)
+
+- **!**: include when a breaking change is introduced
+
+- **summary**: imperative mood, ≤ 72 chars, no trailing period
+
+**Examples**
+
+- `fix(api): handle null token in refresh path`
+
+- `feat(ui/login)!: require OTP after 3 failed attempts`
+
+### B. Body (optional, when it adds non-obvious value)
+
+- One blank line after subject.
+
+- Wrap at ~72 chars.
+
+- Explain **what** and **why**, not line-by-line "how".
+
+- Include brief notes like tests passing or TS/lint issues resolved
+
+  **only if material**.
+
+**Body checklist**
+
+- [ ] Problem/symptom being addressed
+
+- [ ] High-level approach or rationale
+
+- [ ] Risks, tradeoffs, or follow-ups (if any)
+
+### C. Footer (optional)
+
+- Issue refs: `Closes #123`, `Refs #456`
+
+- Breaking change (alternative to `!`):
+
+  `BREAKING CHANGE: <impact + migration note>`
+
+- Authors: `Co-authored-by: Name <email>`
+
+- Security: `CVE-XXXX-YYYY: <short note>` (if applicable)
+
+## Content Guidance
+
+### Include (when relevant)
+
+- Specific fixes/features delivered
+
+- Symptoms/problems fixed
+
+- Brief note that tests passed or TS/lint errors resolved
+
+### Avoid
+
+- Vague: *improved, enhanced, better*
+
+- Trivialities: tiny docs, one-liners, pure lint cleanups (separate,
+
+  focused commits if needed)
+
+- Redundancy: generic blurbs repeated across files
+
+- Multi-purpose dumps: keep commits **narrow and focused**
+
+- Long explanations that good inline code comments already cover
+
+**Guiding Principle:** Let code and inline docs speak. Use commits to
+highlight what isn't obvious.
+
+## Copy-Paste Templates
+
+### Minimal (no body)
+
+```text
+
+<type>(<scope>): <summary>
+
+```
+
+### Standard (with body & footer)
+
+```text
+
+<type>(<scope>)<!>: <summary>
+
+<why-this-change?>
+<what-it-does?>
+<risks-or-follow-ups?>
+
+Closes #<id>
+BREAKING CHANGE: <impact + migration>
+Co-authored-by: <Name> <email>
+
+```
+
+## Type Descriptions
+
+### feat
+
+New feature for the user
+
+### fix
+
+Bug fix for the user
+
+### docs
+
+Documentation only changes
+
+### style
+
+Changes that do not affect the meaning of the code
+
+### refactor
+
+Code change that neither fixes a bug nor adds a feature
+
+### perf
+
+Code change that improves performance
+
+### test
+
+Adding missing tests or correcting existing tests
+
+### build
+
+Changes that affect the build system or external dependencies
+
+### ci
+
+Changes to CI configuration files and scripts
+
+### chore
+
+Other changes that don't modify src or test files
+
+---
+
+**See also**:
+
+- `.cursor/rules/workflow/version_control.mdc` for
+
+  core version control principles
+
+- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details
+
+**Status**: Active commit message guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: version_control.mdc
+**Stakeholders**: Development team, AI assistants
+
+## Model Implementation Checklist
+
+### Before Creating Commits
+
+- [ ] **Change Review**: Review all changes to be committed
+- [ ] **Scope Assessment**: Determine if changes belong in single or multiple commits
+- [ ] **Message Planning**: Plan clear, descriptive commit message
+- [ ] **Convention Check**: Review commit message format requirements
+
+### During Commit Creation
+
+- [ ] **Type Selection**: Choose appropriate commit type (feat, fix, docs, etc.)
+- [ ] **Message Writing**: Write clear, concise commit message
+- [ ] **Body Content**: Add detailed description if needed
+- [ ] **Breaking Changes**: Document breaking changes with `!` and migration notes
+
+### After Commit Creation
+
+- [ ] **Message Review**: Verify commit message follows conventions
+- [ ] **Change Validation**: Confirm all intended changes are included
+- [ ] **Documentation**: Update any related documentation
+- [ ] **Team Communication**: Communicate significant changes to team

.cursor/rules/workflow/version_control.mdc

@@ -1,155 +1,41 @@
----
-description: interacting with git
-alwaysApply: false
----
 # Directive: Peaceful Co-Existence with Developers
 
 **Author**: Matthew Raymer
 **Date**: 2025-08-19
 **Status**: 🎯 **ACTIVE** - Version control guidelines
 
-## 1) Version-Control Ownership
+## Core Principles
+
+### 1) Version-Control Ownership
 
 - **MUST NOT** run `git add`, `git commit`, or any write action.
 - **MUST** leave staging/committing to the developer.
 
-## 2) Source of Truth for Commit Text
+### 2) Source of Truth for Commit Text
 
 - **MUST** derive messages **only** from:
+
   - files **staged** for commit (primary), and
   - files **awaiting staging** (context).
+
 - **MUST** use the **diffs** to inform content.
 - **MUST NOT** invent changes or imply work not present in diffs.
 
-## 3) Mandatory Preview Flow
+### 3) Mandatory Preview Flow
 
 - **ALWAYS** present, before any real commit:
+
   - file list + brief per-file notes,
   - a **draft commit message** (copy-paste ready),
   - nothing auto-applied.
 
-## 4) Version Synchronization Requirements
+### 4) Version Synchronization Requirements
 
 - **MUST** check for version changes in `package.json` before committing
-- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version
+- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version changes
-  changes
 - **MUST** validate version format consistency between both files
-- **MUST** include version bump commits in changelog with proper semantic
+- **MUST** include version bump commits in changelog with
-  versioning
+  proper semantic versioning
-
-### Version Sync Checklist (Before Commit)
-
-- [ ] `package.json` version matches latest `CHANGELOG.md` entry
-- [ ] New version follows semantic versioning
-  (MAJOR.MINOR.PATCH[-PRERELEASE])
-- [ ] Changelog entry includes all significant changes since last version
-- [ ] Version bump commit message follows `build(version): bump to X.Y.Z`
-  format
-- [ ] Breaking changes properly documented with migration notes
-- [ ] Alert developer in chat message that version has been updated
-
-### Version Change Detection
-
-- **Check for version changes** in staged/unstaged `package.json`
-- **Alert developer** if version changed but changelog not updated
-- **Suggest changelog update** with proper format and content
-- **Validate semantic versioning** compliance
-
-### Implementation Notes
-
-- **Version Detection**: Compare `package.json` version field with latest
-  changelog entry
-- **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]`
-  format
-- **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/)
-  standards
-- **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:`
-  in changelog
-- **Pre-release Versions**: Include beta/alpha/rc suffixes in both files
-  consistently
-
-## Commit Message Format (Normative)
-
-### A. Subject Line (required)
-
-```
-<type>(<scope>)<!>: <summary>
-```
-
-- **type** (lowercase, Conventional Commits):
-  `feat|fix|refactor|perf|docs|test|build|chore|ci|revert`
-- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`)
-- **!**: include when a breaking change is introduced
-- **summary**: imperative mood, ≤ 72 chars, no trailing period
-
-**Examples**
-
-- `fix(api): handle null token in refresh path`
-- `feat(ui/login)!: require OTP after 3 failed attempts`
-
-### B. Body (optional, when it adds non-obvious value)
-
-- One blank line after subject.
-- Wrap at ~72 chars.
-- Explain **what** and **why**, not line-by-line "how".
-- Include brief notes like tests passing or TS/lint issues resolved
-  **only if material**.
-
-**Body checklist**
-
-- [ ] Problem/symptom being addressed
-- [ ] High-level approach or rationale
-- [ ] Risks, tradeoffs, or follow-ups (if any)
-
-### C. Footer (optional)
-
-- Issue refs: `Closes #123`, `Refs #456`
-- Breaking change (alternative to `!`):
-  `BREAKING CHANGE: <impact + migration note>`
-- Authors: `Co-authored-by: Name <email>`
-- Security: `CVE-XXXX-YYYY: <short note>` (if applicable)
-
-## Content Guidance
-
-### Include (when relevant)
-
-- Specific fixes/features delivered
-- Symptoms/problems fixed
-- Brief note that tests passed or TS/lint errors resolved
-
-### Avoid
-
-- Vague: *improved, enhanced, better*
-- Trivialities: tiny docs, one-liners, pure lint cleanups (separate,
-  focused commits if needed)
-- Redundancy: generic blurbs repeated across files
-- Multi-purpose dumps: keep commits **narrow and focused**
-- Long explanations that good inline code comments already cover
-
-**Guiding Principle:** Let code and inline docs speak. Use commits to
-highlight what isn't obvious.
-
-## Copy-Paste Templates
-
-### Minimal (no body)
-
-```text
-<type>(<scope>): <summary>
-```
-
-### Standard (with body & footer)
-
-```text
-<type>(<scope>)<!>: <summary>
-
-<why-this-change?>
-<what-it-does?>
-<risks-or-follow-ups?>
-
-Closes #<id>
-BREAKING CHANGE: <impact + migration>
-Co-authored-by: <Name> <email>
-```
 
 ## Assistant Output Checklist (before showing the draft)
 
@@ -159,177 +45,42 @@ Co-authored-by: <Name> <email>
 - [ ] Body only if it adds non-obvious value
 - [ ] No invented changes; aligns strictly with diffs
 - [ ] Render as a single copy-paste block for the developer
+- [ ] No invented changes; aligns strictly with diffs
+- [ ] Render as a single copy-paste block for the developer
 
 ---
 
+**See also**:
+
+- `.cursor/rules/workflow/commit_messages.mdc` for commit message format and
+  templates
+- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details
+
 **Status**: Active version control guidelines
 **Priority**: High
 **Estimated Effort**: Ongoing reference
 **Dependencies**: git, package.json, CHANGELOG.md
 **Stakeholders**: Development team, AI assistants
 
-- [ ] No invented changes; aligns strictly with diffs
+## Model Implementation Checklist
-- [ ] Render as a single copy-paste block for the developer
 
-## 1) Version-Control Ownership
+### Before Version Control Work
 
-- **MUST NOT** run `git add`, `git commit`, or any write action.
+- [ ] **File Analysis**: Review files staged and awaiting staging
-- **MUST** leave staging/committing to the developer.
+- [ ] **Version Check**: Check for version changes in package.json
+- [ ] **Changelog Review**: Verify CHANGELOG.md is updated if version changed
+- [ ] **Diff Analysis**: Analyze actual changes from git diffs
 
-## 2) Source of Truth for Commit Text
+### During Version Control Work
 
-- **MUST** derive messages **only** from:
+- [ ] **Commit Preview**: Present file list with brief notes per file
-  - files **staged** for commit (primary), and
+- [ ] **Message Draft**: Provide focused draft commit message
-  - files **awaiting staging** (context).
+- [ ] **Format Validation**: Ensure message follows type(scope)! syntax
-- **MUST** use the **diffs** to inform content.
+- [ ] **Version Sync**: Validate version consistency between files
-- **MUST NOT** invent changes or imply work not present in diffs.
 
-## 3) Mandatory Preview Flow
+### After Version Control Work
 
-- **ALWAYS** present, before any real commit:
+- [ ] **Developer Control**: Leave staging/committing to developer
-  - file list + brief per-file notes,
+- [ ] **Message Validation**: Verify message aligns strictly with diffs
-  - a **draft commit message** (copy-paste ready),
+- [ ] **Version Validation**: Confirm version format consistency
-  - nothing auto-applied.
+- [ ] **Documentation**: Update relevant version control documentation
-
-## 4) Version Synchronization Requirements
-
-- **MUST** check for version changes in `package.json` before committing
-- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version
-  changes
-- **MUST** validate version format consistency between both files
-- **MUST** include version bump commits in changelog with proper semantic
-  versioning
-
-### Version Sync Checklist (Before Commit)
-
-- [ ] `package.json` version matches latest `CHANGELOG.md` entry
-- [ ] New version follows semantic versioning
-  (MAJOR.MINOR.PATCH[-PRERELEASE])
-- [ ] Changelog entry includes all significant changes since last version
-- [ ] Version bump commit message follows `build(version): bump to X.Y.Z`
-  format
-- [ ] Breaking changes properly documented with migration notes
-- [ ] Alert developer in chat message that version has been updated
-
-### Version Change Detection
-
-- **Check for version changes** in staged/unstaged `package.json`
-- **Alert developer** if version changed but changelog not updated
-- **Suggest changelog update** with proper format and content
-- **Validate semantic versioning** compliance
-
-### Implementation Notes
-
-- **Version Detection**: Compare `package.json` version field with latest
-  changelog entry
-- **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]`
-  format
-- **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/)
-  standards
-- **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:`
-  in changelog
-- **Pre-release Versions**: Include beta/alpha/rc suffixes in both files
-  consistently
-
-## Commit Message Format (Normative)
-
-### A. Subject Line (required)
-
-```
-<type>(<scope>)<!>: <summary>
-```
-
-- **type** (lowercase, Conventional Commits):
-  `feat|fix|refactor|perf|docs|test|build|chore|ci|revert`
-- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`)
-- **!**: include when a breaking change is introduced
-- **summary**: imperative mood, ≤ 72 chars, no trailing period
-
-**Examples**
-
-- `fix(api): handle null token in refresh path`
-- `feat(ui/login)!: require OTP after 3 failed attempts`
-
-### B. Body (optional, when it adds non-obvious value)
-
-- One blank line after subject.
-- Wrap at ~72 chars.
-- Explain **what** and **why**, not line-by-line "how".
-- Include brief notes like tests passing or TS/lint issues resolved
-  **only if material**.
-
-**Body checklist**
-
-- [ ] Problem/symptom being addressed
-- [ ] High-level approach or rationale
-- [ ] Risks, tradeoffs, or follow-ups (if any)
-
-### C. Footer (optional)
-
-- Issue refs: `Closes #123`, `Refs #456`
-- Breaking change (alternative to `!`):
-  `BREAKING CHANGE: <impact + migration note>`
-- Authors: `Co-authored-by: Name <email>`
-- Security: `CVE-XXXX-YYYY: <short note>` (if applicable)
-
-## Content Guidance
-
-### Include (when relevant)
-
-- Specific fixes/features delivered
-- Symptoms/problems fixed
-- Brief note that tests passed or TS/lint errors resolved
-
-### Avoid
-
-- Vague: *improved, enhanced, better*
-- Trivialities: tiny docs, one-liners, pure lint cleanups (separate,
-  focused commits if needed)
-- Redundancy: generic blurbs repeated across files
-- Multi-purpose dumps: keep commits **narrow and focused**
-- Long explanations that good inline code comments already cover
-
-**Guiding Principle:** Let code and inline docs speak. Use commits to
-highlight what isn't obvious.
-
-## Copy-Paste Templates
-
-### Minimal (no body)
-
-```text
-<type>(<scope>): <summary>
-```
-
-### Standard (with body & footer)
-
-```text
-<type>(<scope>)<!>: <summary>
-
-<why-this-change?>
-<what-it-does?>
-<risks-or-follow-ups?>
-
-Closes #<id>
-BREAKING CHANGE: <impact + migration>
-Co-authored-by: <Name> <email>
-```
-
-## Assistant Output Checklist (before showing the draft)
-
-- [ ] List changed files + 1–2 line notes per file
-- [ ] Provide **one** focused draft message (subject/body/footer)
-- [ ] Subject ≤ 72 chars, imperative mood, correct `type(scope)!` syntax
-- [ ] Body only if it adds non-obvious value
-- [ ] No invented changes; aligns strictly with diffs
-- [ ] Render as a single copy-paste block for the developer
-
----
-
-**Status**: Active version control guidelines
-**Priority**: High
-**Estimated Effort**: Ongoing reference
-**Dependencies**: git, package.json, CHANGELOG.md
-**Stakeholders**: Development team, AI assistants
-
-* [ ] No invented changes; aligns strictly with diffs
-* [ ] Render as a single copy-paste block for the developer

.cursor/rules/workflow/version_sync.mdc

@@ -0,0 +1,176 @@
+# Version Synchronization and Changelog Management
+
+> **Agent role**: Reference this file for version synchronization
+> requirements and changelog management.
+
+## Version Sync Checklist (Before Commit)
+
+- [ ] `package.json` version matches latest `CHANGELOG.md` entry
+- [ ] New version follows semantic versioning
+  (MAJOR.MINOR.PATCH[-PRERELEASE])
+- [ ] Changelog entry includes all significant changes since last version
+- [ ] Version bump commit message follows `build(version): bump to X.Y.Z`
+  format
+- [ ] Breaking changes properly documented with migration notes
+- [ ] Alert developer in chat message that version has been updated
+
+## Version Change Detection
+
+- **Check for version changes** in staged/unstaged `package.json`
+- **Alert developer** if version changed but changelog not updated
+- **Suggest changelog update** with proper format and content
+- **Validate semantic versioning** compliance
+
+## Implementation Notes
+
+### Version Detection
+
+- Compare `package.json` version field with latest changelog entry
+- Use semantic versioning validation
+- Check for pre-release version consistency
+
+### Semantic Validation
+
+- Ensure version follows `X.Y.Z[-PRERELEASE]` format
+- Validate major.minor.patch components
+- Handle pre-release suffixes (beta, alpha, rc)
+
+### Changelog Format
+
+- Follow [Keep a Changelog](https://keepachangelog.com/) standards
+- Use consistent section headers
+- Include breaking change notes
+- Maintain chronological order
+
+### Breaking Changes
+
+- Use `!` in commit message
+- Include `BREAKING CHANGE:` in changelog
+- Provide migration notes
+- Document impact clearly
+
+### Pre-release Versions
+
+- Include beta/alpha/rc suffixes consistently
+- Update both `package.json` and changelog
+- Maintain version number alignment
+- Document pre-release status
+
+## Changelog Sections
+
+### Added
+
+- New features
+- New capabilities
+- New dependencies
+
+### Changed
+
+- Changes in existing functionality
+- API changes
+- Performance improvements
+
+### Deprecated
+
+- Soon-to-be removed features
+- Migration paths
+- Sunset timelines
+
+### Removed
+
+- Removed features
+- Breaking changes
+- Deprecated items
+
+### Fixed
+
+- Bug fixes
+- Security patches
+- Performance fixes
+
+### Security
+
+- Security vulnerabilities
+- CVE references
+- Mitigation steps
+
+## Version Bump Guidelines
+
+### Patch (X.Y.Z+1)
+
+- Bug fixes
+- Documentation updates
+- Minor improvements
+
+### Minor (X.Y+1.Z)
+
+- New features
+- Backward-compatible changes
+- Significant improvements
+
+### Major (X+1.Y.Z)
+
+- Breaking changes
+- Major API changes
+- Incompatible changes
+
+## Pre-release Guidelines
+
+### Beta Versions
+
+- Feature complete
+- Testing phase
+- API stable
+
+### Alpha Versions
+
+- Early development
+- API may change
+- Limited testing
+
+### Release Candidates
+
+- Final testing
+- API frozen
+- Production ready
+
+---
+
+**See also**:
+
+- `.cursor/rules/workflow/version_control.mdc` for core version
+  control principles
+- `.cursor/rules/workflow/commit_messages.mdc` for commit message
+  format
+
+**Status**: Active version synchronization guide
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: version_control.mdc
+**Stakeholders**: Development team, Release team
+
+## Model Implementation Checklist
+
+### Before Version Changes
+
+- [ ] **Version Review**: Check current version in `package.json` and `CHANGELOG.md`
+- [ ] **Change Assessment**: Identify what type of version bump is needed (patch/minor/major)
+- [ ] **Breaking Changes**: Review if any changes are breaking and require
+  major version
+- [ ] **Pre-release Status**: Determine if this should be a pre-release version
+
+### During Version Synchronization
+
+- [ ] **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` format
+- [ ] **Package Update**: Update `package.json` version field
+- [ ] **Changelog Entry**: Add entry to `CHANGELOG.md` following Keep a Changelog
+  format
+- [ ] **Breaking Changes**: Document breaking changes with migration notes
+  if applicable
+
+### After Version Changes
+
+- [ ] **Commit Format**: Use `build(version): bump to X.Y.Z` commit message format
+- [ ] **Developer Alert**: Alert developer that version has been updated
+- [ ] **Validation**: Verify `package.json` and `CHANGELOG.md` are in sync
+- [ ] **Pre-release Handling**: Ensure pre-release versions are consistently formatted

.markdownlint-cli2.jsonc

@@ -0,0 +1,53 @@
+{
+  // Markdownlint configuration for TimeSafari .cursor/rules
+  "config": {
+    // Core formatting rules that can be auto-fixed
+    "MD013": {
+      "line_length": 80,
+      "code_blocks": false,
+      "tables": false,
+      "headings": false
+    },
+    "MD012": true,  // No multiple consecutive blank lines
+    "MD022": true,  // Headings should be surrounded by blank lines
+    "MD031": true,  // Fenced code blocks should be surrounded by blank lines
+    "MD032": true,  // Lists should be surrounded by blank lines
+    "MD047": true,  // Files should end with a single newline
+    "MD009": true,  // No trailing spaces
+    "MD010": true,  // No hard tabs
+    "MD004": { "style": "dash" },  // Consistent list markers
+    "MD029": { "style": "ordered" },  // Ordered list item prefix
+    
+    // Disable rules that conflict with existing content structure
+    "MD041": false,  // First line heading requirement
+    "MD025": false,  // Multiple top-level headings
+    "MD024": false,  // Duplicate headings
+    "MD036": false,  // Emphasis as headings
+    "MD003": false,  // Heading style consistency
+    "MD040": false,  // Fenced code language
+    "MD055": false,  // Table pipe style
+    "MD056": false,  // Table column count
+    "MD034": false,  // Bare URLs
+    "MD023": false   // Heading indentation
+  },
+  
+  "globs": [
+    ".cursor/rules/**/*.mdc",
+    "*.md",
+    "*.markdown",
+    "scripts/**/*.md",
+    "src/**/*.md",
+    "test-playwright/**/*.md",
+    "resources/**/*.md",
+    "doc/**/*.md",
+    "ios/**/*.md",
+    "electron/**/*.md"
+  ],
+  "ignores": [
+    "node_modules/**",
+    ".git/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**"
+  ]
+}

.markdownlint.json

@@ -1 +1,27 @@
-{"MD013": {"code_blocks": false}}
+{
+  "MD013": {
+    "line_length": 80,
+    "code_blocks": false,
+    "tables": false,
+    "headings": false
+  },
+  "MD012": true,
+  "MD022": true,
+  "MD031": true,
+  "MD032": true,
+  "MD047": true,
+  "MD009": true,
+  "MD010": true,
+  "MD004": { "style": "dash" },
+  "MD029": { "style": "ordered" },
+  "MD041": false,
+  "MD025": false,
+  "MD024": false,
+  "MD036": false,
+  "MD003": false,
+  "MD040": false,
+  "MD055": false,
+  "MD056": false,
+  "MD034": false,
+  "MD023": false
+}

BUILDING.md

@@ -344,17 +344,10 @@ current version to test DB migrations.
 [online](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/releases) or 
 `git tag 1.0.2 && git push origin 1.0.2`.
 
-- For test, build the app (because test server is not yet set up to build):
+- For test, build the app:
 
 ```bash
-TIME_SAFARI_APP_TITLE="TimeSafari_Test" \
+npm run build:web:test
-VITE_APP_SERVER=https://test.timesafari.app \
-VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F \
-VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch \
-VITE_DEFAULT_IMAGE_API_SERVER=https://test-image-api.timesafari.app \
-VITE_DEFAULT_PARTNER_API_SERVER=https://test-partner-api.endorser.ch \
-VITE_DEFAULT_PUSH_SERVER=https://test.timesafari.app \
-VITE_PASSKEYS_ENABLED=true npm run build:web
 ```
 
 ... and transfer to the test server:
@@ -2679,3 +2672,77 @@ All scripts use consistent error handling:
 **Note**: This documentation is maintained alongside the build system. For the
 most up-to-date information, refer to the actual script files and Vite
 configuration files in the repository.
+
+---
+
+## Build Changes Changelog
+
+### 2025-08-21 - Cursor Rules Refactoring and Build System Updates
+
+#### Package Dependencies Updated
+- **Added**: `markdownlint-cli2` v0.18.1 - Modern markdown linting with improved performance
+- **Added**: `@commitlint/cli` v18.6.1 - Conventional commit message validation
+- **Added**: `@commitlint/config-conventional` v18.6.2 - Conventional commit standards
+- **Updated**: `husky` v9.0.11 - Git hooks management
+- **Updated**: `lint-staged` v15.2.2 - Pre-commit linting automation
+
+#### Build Script Improvements
+- **Markdown Linting**: Replaced custom markdown scripts with `markdownlint-cli2`
+  - **Before**: `./scripts/fix-markdown.sh` and `./scripts/validate-markdown.sh`
+  - **After**: `markdownlint-cli2 --fix` and `markdownlint-cli2`
+  - **Benefits**: Faster execution, better error reporting, modern markdown standards
+
+#### Lint-Staged Configuration Enhanced
+- **Added**: Markdown file linting to pre-commit hooks
+  - **Pattern**: `*.{md,markdown,mdc}` files now automatically formatted
+  - **Command**: `markdownlint-cli2 --fix` runs before each commit
+  - **Coverage**: All markdown files including `.mdc` cursor rules
+
+#### Commit Message Standards
+- **Added**: Conventional commit validation via commitlint
+- **Configuration**: Extends `@commitlint/config-conventional`
+- **Enforcement**: Ensures consistent commit message format across the project
+
+#### Node.js Version Requirements
+- **Updated**: Minimum Node.js version requirements for new dependencies
+- **markdownlint-cli2**: Requires Node.js >=20
+- **Various utilities**: Require Node.js >=18 for modern ES features
+
+#### Build Process Impact
+- **No Breaking Changes**: All existing build commands continue to work
+- **Improved Quality**: Better markdown formatting and commit message standards
+- **Enhanced Automation**: More comprehensive pre-commit validation
+- **Performance**: Faster markdown linting with modern tooling
+
+---
+
+### 2025-08-21 - Commitlint Configuration Refinement
+
+#### Commit Message Validation Improvements
+- **Modified**: Commitlint configuration moved from `package.json` to dedicated `commitlint.config.js`
+- **Enhanced**: Strict validation rules downgraded from errors to warnings
+  - **Before**: `subject-case` and `subject-full-stop` rules caused red error messages
+  - **After**: Same rules now show yellow warnings without blocking commits
+- **Benefit**: Eliminates confusing red error messages while maintaining commit quality guidance
+
+#### Configuration Structure
+- **File**: `commitlint.config.js` - Dedicated commitlint configuration
+- **Extends**: `@commitlint/config-conventional` - Standard conventional commit rules
+- **Custom Rules**: 
+  - `subject-case: [1, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']]`
+  - `subject-full-stop: [1, 'never', '.']`
+- **Levels**: 
+  - `0` = Disabled, `1` = Warning, `2` = Error
+  - Current: Problematic rules set to warning level (1)
+
+#### User Experience Impact
+- **Before**: Red error messages on every push with strict commit rules
+- **After**: Yellow warning messages that provide guidance without disruption
+- **Workflow**: Commits and pushes continue to work while maintaining quality standards
+- **Feedback**: Developers still receive helpful commit message guidance
+
+---
+
+**Note**: This documentation is maintained alongside the build system. For the
+most up-to-date information, refer to the actual script files and Vite
+configuration files in the repository.

README.md

@@ -1,8 +1,26 @@
-# Time Safari Application
+# TimeSafari.app - Crowd-Funder for Time - PWA
 
-**Author**: Matthew Raymer
+[Time Safari](https://timesafari.org/) allows people to ease into collaboration: start with expressions of gratitude
-**Version**: 1.0.8-beta
+and expand to crowd-fund with time & money, then record and see the impact of contributions.
-**Description**: Time Safari Application
+
+## Roadmap
+
+See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities.
+
+## Setup & Building
+
+Quick start:
+
+* For setup, we recommend [pkgx](https://pkgx.dev), which installs what you need (either automatically or with the `dev` command). Core dependencies are typescript & npm; when building for other platforms, you'll need other things such as those in the pkgx.yaml & BUILDING.md files.
+
+```bash
+npm install
+npm run build:web:serve -- --test
+```
+
+To be able to make submissions: go to "profile" (bottom left), go to the bottom and expand "Show Advanced Settings", go to the bottom and to the "Test Page", and finally "Become User 0" to see all the functionality.
+
+See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker).
 
 ## 🛡️ Build Architecture Guard
 
@@ -38,37 +56,239 @@ git push --no-verify
 
 **📚 Full documentation**: See `doc/README-BUILD-GUARD.md`
 
-## 🚀 Quick Start
+## Development Database Clearing
 
-### Prerequisites
+TimeSafari provides a simple script-based approach to clear the local database (not the claim server) for development purposes.
 
-- Node.js 18+
+## Logging Configuration
-- npm, yarn, or pnpm
-- Git
 
-### Installation
+TimeSafari supports configurable logging levels via the `VITE_LOG_LEVEL` environment variable. This allows developers to control console output verbosity without modifying code.
+
+### Quick Usage
 
 ```bash
+# Show only errors
+VITE_LOG_LEVEL=error npm run dev
+
+# Show warnings and errors
+VITE_LOG_LEVEL=warn npm run dev
+
+# Show info, warnings, and errors (default)
+VITE_LOG_LEVEL=info npm run dev
+
+# Show all log levels including debug
+VITE_LOG_LEVEL=debug npm run dev
+```
+
+### Available Levels
+
+- **`error`**: Critical errors only
+- **`warn`**: Warnings and errors (default for production web)
+- **`info`**: Info, warnings, and errors (default for development/capacitor)
+- **`debug`**: All log levels including verbose debugging
+
+See [Logging Configuration Guide](doc/logging-configuration.md) for complete details.
+
+### Quick Usage
+```bash
+# Run the database clearing script
+./scripts/clear-database.sh
+
+# Then restart your development server
+npm run build:electron:dev  # For Electron
+npm run build:web:dev       # For Web
+```
+
+### What It Does
+
+#### **Electron (Desktop App)**
+- Automatically finds and clears the SQLite database files
+- Works on Linux, macOS, and Windows
+- Clears all data and forces fresh migrations on next startup
+
+#### **Web Browser**
+- Provides instructions for using custom browser data directories
+- Shows manual clearing via browser DevTools
+- Ensures reliable database clearing without browser complications
+
+### Safety Features
+- ✅ **Interactive Script**: Guides you through the process
+- ✅ **Platform Detection**: Automatically detects your OS
+- ✅ **Clear Instructions**: Step-by-step guidance for each platform
+- ✅ **Safe Paths**: Only clears TimeSafari-specific data
+
+### Manual Commands (if needed)
+
+#### **Electron Database Location**
+```bash
+# Linux
+rm -rf ~/.config/TimeSafari/*
+
+# macOS  
+rm -rf ~/Library/Application\ Support/TimeSafari/*
+
+# Windows
+rmdir /s /q %APPDATA%\TimeSafari
+```
+
+#### **Web Browser (Custom Data Directory)**
+```bash
+# Create isolated browser profile
+mkdir ~/timesafari-dev-data
+```
+
+## Domain Configuration
+
+TimeSafari uses a centralized domain configuration system to ensure consistent
+URL generation across all environments. This prevents localhost URLs from
+appearing in shared links during development.
+
+### Key Features
+- ✅ **Production URLs for Sharing**: All copy link buttons use production domain
+- ✅ **Environment-Specific Internal URLs**: Internal operations use appropriate
+  environment URLs
+- ✅ **Single Point of Control**: Change domain in one place for entire app
+- ✅ **Type-Safe Configuration**: Full TypeScript support
+
+### Quick Reference
+
+```typescript
+// For sharing functionality (environment-specific)
+import { APP_SERVER } from "@/constants/app";
+const shareLink = `${APP_SERVER}/deep-link/claim/123`;
+
+// For internal operations (environment-specific)
+import { APP_SERVER } from "@/constants/app";
+const apiUrl = `${APP_SERVER}/api/claim/123`;
+```
+
+### Documentation
+
+- [Constants and Configuration](src/constants/app.ts) - Core constants
+
+## Tests
+
+See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
+
+## Asset Management
+
+TimeSafari uses a standardized asset configuration system for consistent
+icon and splash screen generation across all platforms.
+
+### Asset Sources
+
+- **Single source of truth**: `resources/` directory (Capacitor default)
+- **Source files**: `icon.png`, `splash.png`, `splash_dark.png`
+- **Format**: PNG or SVG files for optimal quality
+
+### Asset Generation
+
+- **Configuration**: `config/assets/capacitor-assets.config.json`
+- **Schema validation**: `config/assets/schema.json`
+- **Build-time generation**: Platform assets generated via `capacitor-assets`
+- **No VCS commits**: Generated assets are never committed to version control
+
+### Development Commands
+
+```bash
+# Generate/update asset configurations
+npm run assets:config
+
+# Validate asset configurations
+npm run assets:validate
+
+# Clean generated platform assets (local dev only)
+npm run assets:clean
+
+# Build with asset generation
+npm run build:native
+```
+
+### Environment Setup & Dependencies
+
+Before building the application, ensure your development environment is properly
+configured:
+
+```bash
+# Install all dependencies (required first time and after updates)
 npm install
-npm run guard:setup  # Sets up Build Architecture Guard
+
+# Validate your development environment
+npm run check:dependencies
+
+# Check prerequisites for testing
+npm run test:prerequisites
 ```
 
-### Development
+**Common Issues & Solutions**:
 
-```bash
+- **"tsx: command not found"**: Run `npm install` to install devDependencies
-npm run build:web:dev    # Build web version
+- **"capacitor-assets: command not found"**: Ensure `@capacitor/assets` is installed
-npm run build:ios:test   # Build iOS test version
+- **Build failures**: Run `npm run check:dependencies` to diagnose environment issues
-npm run build:android:test # Build Android test version
-npm run build:electron:dev # Build Electron dev version
-```
 
-### Testing
+**Required Versions**:
+- Node.js: 18+ (LTS recommended)
+- npm: 8+ (comes with Node.js)
+- Platform-specific tools: Android Studio, Xcode (for mobile builds)
 
-```bash
+### Platform Support
-npm run test:web         # Run web tests
+
-npm run test:mobile      # Run mobile tests
+- **Android**: Adaptive icons with foreground/background, monochrome support
-npm run test:all         # Run all tests
+- **iOS**: LaunchScreen storyboard preferred, splash assets when needed
-```
+- **Web**: PWA icons generated during build to `dist/` (not committed)
+
+### Font Awesome Icons
+
+To add a Font Awesome icon, add to `fontawesome.ts` and reference with
+`font-awesome` element and `icon` attribute with the hyphenated name.
+
+## Other
+
+### Reference Material
+
+* Notifications can be type of `toast` (self-dismiss), `info`, `success`, `warning`, and `danger`.
+  They are done via [notiwind](https://www.npmjs.com/package/notiwind) and set up in App.vue.
+
+* [Customize Vue configuration](https://cli.vuejs.org/config/).
+
+* If you are deploying in a subdirectory, add it to `publicPath` in vue.config.js, eg: `publicPath: "/app/time-tracker/",`
+
+### Code Organization
+
+The project uses a centralized approach to type definitions and interfaces:
+
+* `src/interfaces/` - Contains all TypeScript interfaces and type definitions
+  * `deepLinks.ts` - Deep linking type system and Zod validation schemas
+  * `give.ts` - Give-related interfaces and type definitions
+  * `claims.ts` - Claim-related interfaces and verifiable credentials
+  * `common.ts` - Shared interfaces and utility types
+  * Other domain-specific interface files
+
+Key principles:
+- All interfaces and types are defined in the interfaces folder
+- Zod schemas are used for runtime validation and type generation
+- Domain-specific interfaces are separated into their own files
+- Common interfaces are shared through `common.ts`
+- Type definitions are generated from Zod schemas where possible
+
+### Database Architecture
+
+The application uses a platform-agnostic database layer with Vue mixins for service access:
+
+* `src/services/PlatformService.ts` - Database interface definition
+* `src/services/PlatformServiceFactory.ts` - Platform-specific service factory
+* `src/services/AbsurdSqlDatabaseService.ts` - SQLite implementation
+* `src/utils/PlatformServiceMixin.ts` - Vue mixin for database access with caching
+* `src/db/` - Legacy Dexie database (migration in progress)
+
+**Development Guidelines**:
+
+- Always use `PlatformServiceMixin` for database operations in components
+- Test with PlatformServiceMixin for new features
+- Use migration tools for data transfer between systems
+- Leverage mixin's ultra-concise methods: `$db()`, `$exec()`, `$one()`, `$contacts()`, `$settings()`
+
+**Architecture Decision**: The project uses Vue mixins over Composition API composables for platform service access. See [Architecture Decisions](doc/architecture-decisions.md) for detailed rationale.
 
 ## 📁 Project Structure
 
@@ -85,21 +305,6 @@ timesafari/
 └── 📄 doc/README-BUILD-GUARD.md # Guard system documentation
 ```
 
-## 🔧 Build System
-
-This project supports multiple platforms:
-
-- **Web**: Vite-based build with service worker support
-- **Mobile**: Capacitor-based iOS and Android builds
-- **Desktop**: Electron-based cross-platform desktop app
-- **Docker**: Containerized deployment options
-
-## 📚 Documentation
-
-- **`BUILDING.md`** - Complete build system guide
-- **`doc/README-BUILD-GUARD.md`** - Build Architecture Guard documentation
-- **`pull_request_template.md`** - PR template for build changes
-
 ## 🤝 Contributing
 
 1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files
@@ -107,12 +312,15 @@ This project supports multiple platforms:
 3. **Test your changes** - Ensure builds work on affected platforms
 4. **Document updates** - Keep BUILDING.md current and accurate
 
-## 📄 License
+## Kudos
 
-[Add your license information here]
+Gifts make the world go 'round!
 
----
+* [WebStorm by JetBrains](https://www.jetbrains.com/webstorm/) for the free open-source license
-
+* [Máximo Fernández](https://medium.com/@maxfarenas) for the 3D [code](https://github.com/maxfer03/vue-three-ns) and [explanatory post](https://medium.com/nicasource/building-an-interactive-web-portfolio-with-vue-three-js-part-three-implementing-three-js-452cb375ef80)
-**Note**: The Build Architecture Guard is active and will block
+* [Many tools & libraries](https://gitea.anomalistdesign.com/trent_larson/crowd-funder-for-time-pwa/src/branch/master/package.json#L10) such as Nodejs.org, IntelliJ Idea, Veramo.io, Vuejs.org, threejs.org
-commits/pushes that modify build files without proper documentation
+* [Bush 3D model](https://sketchfab.com/3d-models/lupine-plant-bf30f1110c174d4baedda0ed63778439)
-updates. See `doc/README-BUILD-GUARD.md` for complete details.
+* [Forest floor image](https://www.goodfreephotos.com/albums/textures/leafy-autumn-forest-floor.jpg)
+* Time Safari logo assisted by [DALL-E in ChatGPT](https://chat.openai.com/g/g-2fkFE8rbu-dall-e)
+* [DiceBear](https://www.dicebear.com/licenses/) and [Avataaars](https://www.dicebear.com/styles/avataaars/#details) for human-looking identicons
+* Some gratitude prompts thanks to [Develop Good Habits](https://www.developgoodhabits.com/gratitude-journal-prompts/)

android/app/capacitor.build.gradle

@@ -13,6 +13,7 @@ dependencies {
     implementation project(':capacitor-mlkit-barcode-scanning')
     implementation project(':capacitor-app')
     implementation project(':capacitor-camera')
+    implementation project(':capacitor-clipboard')
     implementation project(':capacitor-filesystem')
     implementation project(':capacitor-share')
     implementation project(':capacitor-status-bar')

android/app/src/main/assets/capacitor.plugins.json

@@ -15,6 +15,10 @@
 		"pkg": "@capacitor/camera",
 		"classpath": "com.capacitorjs.plugins.camera.CameraPlugin"
 	},
+	{
+		"pkg": "@capacitor/clipboard",
+		"classpath": "com.capacitorjs.plugins.clipboard.ClipboardPlugin"
+	},
 	{
 		"pkg": "@capacitor/filesystem",
 		"classpath": "com.capacitorjs.plugins.filesystem.FilesystemPlugin"

android/capacitor.settings.gradle

@@ -14,6 +14,9 @@ project(':capacitor-app').projectDir = new File('../node_modules/@capacitor/app/
 include ':capacitor-camera'
 project(':capacitor-camera').projectDir = new File('../node_modules/@capacitor/camera/android')
 
+include ':capacitor-clipboard'
+project(':capacitor-clipboard').projectDir = new File('../node_modules/@capacitor/clipboard/android')
+
 include ':capacitor-filesystem'
 project(':capacitor-filesystem').projectDir = new File('../node_modules/@capacitor/filesystem/android')
 

commitlint.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    // Downgrade strict case rules to warnings (level 1) instead of errors (level 2)
+    // This eliminates red error messages while maintaining helpful guidance
+    'subject-case': [1, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
+    'subject-full-stop': [1, 'never', '.'],
+  }
+};

doc/meta_rule_usage_guide.md

@@ -0,0 +1,272 @@
+# Meta-Rule Usage Guide: How to Use Meta-Rules in Practice
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21
+**Status**: 🎯 **ACTIVE** - Comprehensive meta-rule usage guide
+
+## Overview
+
+This guide explains how to use the TimeSafari meta-rule system in practice.
+Meta-rules are high-level rule bundles that provide workflow-specific guidance
+for different types of tasks.
+
+**Educational Goal**: Help developers understand when and how to apply
+meta-rules to maximize their effectiveness and avoid common mistakes.
+
+## Why Meta-Rules Matter
+
+**Meta-rules solve the problem of rule overload** by bundling related rules
+into logical workflows. Instead of manually selecting 10+ individual rules,
+you apply 1-3 meta-rules that automatically include everything you need.
+
+### **Benefits of Using Meta-Rules**
+
+- **Faster Setup**: No need to manually select individual rules
+- **Better Coverage**: Ensures you don't miss important rules
+- **Workflow Consistency**: Standardized approaches across the team
+- **Learning Efficiency**: Learn workflows, not individual rules
+- **Quality Assurance**: Built-in validation and feedback mechanisms
+
+## Meta-Rule Selection Strategy
+
+### **Step 1: Always Start with Core Always-On**
+
+**Every single interaction** starts with:
+```
+meta_core_always_on.mdc
+```
+
+This provides the foundation: human competence principles, time standards,
+version control, and application context.
+
+### **Step 2: Identify Your Primary Task Type**
+
+Choose the meta-rule that matches your main objective:
+
+| **Task Type** | **Primary Meta-Rule** | **When to Use** |
+|---------------|------------------------|------------------|
+| **Research/Investigation** | `meta_research.mdc` | Bug diagnosis, feasibility research, code analysis |
+| **Feature Planning** | `meta_feature_planning.mdc` | New feature design, requirements analysis |
+| **Feature Implementation** | `meta_feature_implementation.mdc` | Building features, coding, testing |
+| **Bug Diagnosis** | `meta_bug_diagnosis.mdc` | Investigating issues, root cause analysis |
+| **Bug Fixing** | `meta_bug_fixing.mdc` | Implementing fixes, validation |
+| **Documentation** | `meta_documentation.mdc` | Writing docs, creating guides, tutorials |
+
+### **Step 3: Add Context-Specific Meta-Rules (Optional)**
+
+For complex tasks, you might combine multiple meta-rules:
+
+```
+meta_core_always_on + meta_research + meta_bug_diagnosis
+```
+
+## Practical Usage Examples
+
+### **Example 1: Bug Investigation**
+
+**Scenario**: User reports that the contact list isn't loading properly
+
+**Meta-Rule Selection**:
+```
+meta_core_always_on + meta_research + meta_bug_diagnosis
+```
+
+**What This Gives You**:
+- **Core Always-On**: Human competence focus, time standards, context
+- **Research**: Systematic investigation methodology, evidence collection
+- **Bug Diagnosis**: Defect analysis framework, root cause identification
+
+**Workflow**:
+1. Apply core always-on for foundation
+2. Use research meta-rule for systematic investigation
+3. Apply bug diagnosis for defect analysis
+4. Follow the bundled workflow automatically
+
+### **Example 2: Feature Development**
+
+**Scenario**: Building a new contact search feature
+
+**Meta-Rule Selection**:
+```
+meta_core_always_on + meta_feature_planning + meta_feature_implementation
+```
+
+**What This Gives You**:
+- **Core Always-On**: Foundation principles and context
+- **Feature Planning**: Requirements analysis, architecture planning
+- **Feature Implementation**: Development workflow, testing strategy
+
+**Workflow**:
+1. Start with core always-on
+2. Use feature planning for design and requirements
+3. Switch to feature implementation for coding and testing
+
+### **Example 3: Documentation Creation**
+
+**Scenario**: Writing a migration guide for the new database system
+
+**Meta-Rule Selection**:
+```
+meta_core_always_on + meta_documentation
+```
+
+**What This Gives You**:
+- **Core Always-On**: Foundation and context
+- **Documentation**: Educational focus, templates, quality standards
+
+**Workflow**:
+1. Apply core always-on for foundation
+2. Use documentation meta-rule for educational content creation
+3. Follow educational templates and quality standards
+
+## Meta-Rule Application Process
+
+### **1. Load the Meta-Rule**
+
+When you start a task, explicitly state which meta-rules you're applying:
+
+```
+"I'm applying meta_core_always_on + meta_research for this bug investigation."
+```
+
+### **2. Follow the Bundled Workflow**
+
+Each meta-rule provides a complete workflow. Follow it step-by-step:
+
+- **Research Meta-Rule**: Investigation → Evidence → Analysis → Conclusion
+- **Feature Planning**: Requirements → Architecture → Strategy → Validation
+- **Bug Diagnosis**: Problem → Evidence → Root Cause → Solution
+
+### **3. Use the Bundled Rules**
+
+Meta-rules automatically include all necessary sub-rules. You don't need to
+manually select individual rules - they're already bundled.
+
+### **4. Validate Against Success Criteria**
+
+Each meta-rule includes success criteria. Use these to validate your work:
+
+- [ ] **Educational Quality**: Content increases human competence
+- [ ] **Technical Quality**: All technical details are accurate
+- [ ] **Workflow Completion**: All required steps completed
+- [ ] **Quality Standards**: Meets defined quality criteria
+
+## Common Meta-Rule Combinations
+
+### **Research + Diagnosis**
+```
+meta_core_always_on + meta_research + meta_bug_diagnosis
+```
+**Use for**: Complex bug investigations requiring systematic analysis
+
+### **Planning + Implementation**
+```
+meta_core_always_on + meta_feature_planning + meta_feature_implementation
+```
+**Use for**: End-to-end feature development from concept to deployment
+
+### **Research + Planning**
+```
+meta_core_always_on + meta_research + meta_feature_planning
+```
+**Use for**: Feasibility research and solution design
+
+### **Documentation + Context**
+```
+meta_core_always_on + meta_documentation + [context-specific]
+```
+**Use for**: Creating comprehensive, educational documentation
+
+## Best Practices
+
+### **✅ Do These Things**
+
+- **Always start with core always-on** - it's the foundation
+- **Choose the primary meta-rule** that matches your main task
+- **Follow the bundled workflow** step-by-step
+- **Use success criteria** to validate your work
+- **Collect feedback** on meta-rule effectiveness
+
+### **❌ Avoid These Mistakes**
+
+- **Don't skip core always-on** - you'll lose the foundation
+- **Don't apply too many meta-rules** - stick to 2-3 maximum
+- **Don't ignore the bundled workflow** - follow it systematically
+- **Don't forget validation** - use the success criteria
+- **Don't skip feedback collection** - it improves the system
+
+## Troubleshooting Common Issues
+
+### **Problem**: Meta-rules seem to conflict
+
+**Solution**: Meta-rules are designed to work together. If you see conflicts,
+you're probably applying too many. Stick to 2-3 meta-rules maximum.
+
+### **Problem**: I don't know which meta-rule to use
+
+**Solution**: Start with your primary task type. If you're investigating a bug,
+use research + bug diagnosis. If you're building a feature, use feature
+planning + implementation.
+
+### **Problem**: The meta-rule workflow seems too complex
+
+**Solution**: Meta-rules bundle complexity into manageable workflows. Follow
+the steps one at a time. The complexity is already organized for you.
+
+### **Problem**: I'm not seeing the expected behavior
+
+**Solution**: Ensure you're following the meta-rule workflow step-by-step.
+Meta-rules provide guidance, but you still need to execute the workflow.
+
+## Feedback and Improvement
+
+### **Rate Your Experience**
+
+After using a meta-rule, provide feedback:
+
+- **Effectiveness**: How well did the meta-rule work? (1-5 scale)
+- **Time Saved**: How much time did it save you?
+- **Quality Improvement**: Did it improve your work quality?
+- **Recommendation**: Would you recommend it to others?
+
+### **Continuous Improvement**
+
+Meta-rules evolve based on feedback:
+
+- **Usage patterns** - How teams use the rules
+- **Effectiveness ratings** - What works and what doesn't
+- **Integration feedback** - How well rules work together
+- **Quality metrics** - Impact on work quality
+
+## Quick Reference
+
+### **Meta-Rule Selection Matrix**
+
+| **Task** | **Primary** | **Secondary** | **Tertiary** |
+|----------|-------------|---------------|---------------|
+| **Bug Investigation** | `meta_research` | `meta_bug_diagnosis` | - |
+| **Feature Development** | `meta_feature_planning` | `meta_feature_implementation` | - |
+| **Documentation** | `meta_documentation` | - | - |
+| **Complex Research** | `meta_research` | `meta_bug_diagnosis` | `meta_feature_planning` |
+
+### **Always Remember**
+
+1. **Start with core always-on** - foundation for everything
+2. **Choose your primary meta-rule** - matches your main task
+3. **Follow the bundled workflow** - step-by-step execution
+4. **Validate against success criteria** - ensure quality
+5. **Provide feedback** - help improve the system
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_rule_architecture.md` for meta-rule structure overview
+- `.cursor/rules/meta_core_always_on.mdc` for foundation rules
+- `.cursor/rules/README.md` for complete rule organization
+
+**Status**: Active usage guide
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All meta-rules
+**Stakeholders**: Development team, Documentation team

doc/z-index-guide.md

@@ -0,0 +1,69 @@
+# Z-Index Guide — TimeSafari
+
+**Author**: Development Team  
+**Date**: 2025-08-25T19:38:09-08:00  
+**Status**: 🎯 **ACTIVE** - Z-index layering standards
+
+## Objective
+Establish consistent z-index values across the TimeSafari application to ensure proper layering of UI elements.
+
+## Result
+This document defines the z-index hierarchy for all UI components.
+
+## Use/Run
+Reference these values when implementing new components or modifying existing ones to maintain consistent layering.
+
+## Z-Index Hierarchy
+
+| Component | Z-Index | Usage |
+|-----------|---------|-------|
+| **Map** | `40` | Base map layer and map-related overlays |
+| **QuickNav** | `50` | Quick navigation bottom bar |
+| **Dialogs and Modals** | `100` | Modal dialogs, popups, and overlay content |
+| **Notifications and Toasts** | `120` | System notifications, alerts, and toast messages |
+
+## Best Practices
+
+1. **Never exceed 120** - Keep the highest z-index reserved for critical notifications
+2. **Use increments of 10** - Leave room for future additions between layers
+3. **Document exceptions** - If you need a z-index outside this range, document the reason
+4. **Test layering** - Verify z-index behavior across different screen sizes and devices
+
+## Common Pitfalls
+
+- **Avoid arbitrary values** - Don't use random z-index numbers
+- **Don't nest high z-index** - Keep child elements within their parent's z-index range
+- **Consider stacking context** - Remember that `position: relative` creates new stacking contexts
+
+## Next Steps
+
+| Owner | Task | Exit Criteria | Target Date |
+|-------|------|---------------|-------------|
+| Dev Team | Apply z-index classes to existing components | All components use defined z-index values | 2025-09-01 |
+
+## Competence Hooks
+
+- **Why this works**: Creates predictable layering hierarchy that prevents UI conflicts
+- **Common pitfalls**: Using arbitrary z-index values or exceeding the defined range
+- **Next skill unlock**: Learn about CSS stacking contexts and their impact on z-index
+- **Teach-back**: Explain the z-index hierarchy to a team member without referencing this guide
+
+## Collaboration Hooks
+
+- **Reviewers**: Frontend team, UI/UX designers
+- **Sign-off checklist**: 
+  - [ ] All new components follow z-index guidelines
+  - [ ] Existing components updated to use defined values
+  - [ ] Cross-browser testing completed
+  - [ ] Mobile responsiveness verified
+
+## Assumptions & Limits
+
+- Assumes modern browser support for z-index
+- Limited to 4 defined layers (expandable if needed)
+- Requires team discipline to maintain consistency
+
+## References
+
+- [MDN Z-Index Documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/z-index)
+- [CSS Stacking Context Guide](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context)

ios/App/Podfile

@@ -15,6 +15,7 @@ def capacitor_pods
   pod 'CapacitorMlkitBarcodeScanning', :path => '../../node_modules/@capacitor-mlkit/barcode-scanning'
   pod 'CapacitorApp', :path => '../../node_modules/@capacitor/app'
   pod 'CapacitorCamera', :path => '../../node_modules/@capacitor/camera'
+  pod 'CapacitorClipboard', :path => '../../node_modules/@capacitor/clipboard'
   pod 'CapacitorFilesystem', :path => '../../node_modules/@capacitor/filesystem'
   pod 'CapacitorShare', :path => '../../node_modules/@capacitor/share'
   pod 'CapacitorStatusBar', :path => '../../node_modules/@capacitor/status-bar'

ios/App/Podfile.lock

@@ -5,6 +5,8 @@ PODS:
     - Capacitor
   - CapacitorCamera (6.1.2):
     - Capacitor
+  - CapacitorClipboard (6.0.2):
+    - Capacitor
   - CapacitorCommunitySqlite (6.0.2):
     - Capacitor
     - SQLCipher
@@ -90,6 +92,7 @@ DEPENDENCIES:
   - "Capacitor (from `../../node_modules/@capacitor/ios`)"
   - "CapacitorApp (from `../../node_modules/@capacitor/app`)"
   - "CapacitorCamera (from `../../node_modules/@capacitor/camera`)"
+  - "CapacitorClipboard (from `../../node_modules/@capacitor/clipboard`)"
   - "CapacitorCommunitySqlite (from `../../node_modules/@capacitor-community/sqlite`)"
   - "CapacitorCordova (from `../../node_modules/@capacitor/ios`)"
   - "CapacitorFilesystem (from `../../node_modules/@capacitor/filesystem`)"
@@ -122,6 +125,8 @@ EXTERNAL SOURCES:
     :path: "../../node_modules/@capacitor/app"
   CapacitorCamera:
     :path: "../../node_modules/@capacitor/camera"
+  CapacitorClipboard:
+    :path: "../../node_modules/@capacitor/clipboard"
   CapacitorCommunitySqlite:
     :path: "../../node_modules/@capacitor-community/sqlite"
   CapacitorCordova:
@@ -141,6 +146,7 @@ SPEC CHECKSUMS:
   Capacitor: c95400d761e376be9da6be5a05f226c0e865cebf
   CapacitorApp: e1e6b7d05e444d593ca16fd6d76f2b7c48b5aea7
   CapacitorCamera: 9bc7b005d0e6f1d5f525b8137045b60cffffce79
+  CapacitorClipboard: 4443c3cdb7c77b1533dfe3ff0f9f7756aa8579df
   CapacitorCommunitySqlite: 0299d20f4b00c2e6aa485a1d8932656753937b9b
   CapacitorCordova: 8d93e14982f440181be7304aa9559ca631d77fff
   CapacitorFilesystem: 59270a63c60836248812671aa3b15df673fbaf74

package.json

@@ -1,6 +1,6 @@
 {
   "name": "timesafari",
-  "version": "1.0.8-beta",
+  "version": "1.1.0-beta",
   "description": "Time Safari Application",
   "author": {
     "name": "Time Safari Team"
@@ -99,8 +99,8 @@
     "build:electron:dmg:dev": "./scripts/build-electron.sh --dev --dmg",
     "build:electron:dmg:test": "./scripts/build-electron.sh --test --dmg",
     "build:electron:dmg:prod": "./scripts/build-electron.sh --prod --dmg",
-    "markdown:fix": "./scripts/fix-markdown.sh",
+    "markdown:fix": "markdownlint-cli2 --fix",
-    "markdown:check": "./scripts/validate-markdown.sh",
+    "markdown:check": "markdownlint-cli2",
     "markdown:setup": "./scripts/setup-markdown-hooks.sh",
     "prepare": "husky",
     "guard": "bash ./scripts/build-arch-guard.sh",
@@ -133,11 +133,10 @@
     "build:android:test:run:custom": "./scripts/build-android.sh --test --api-ip --auto-run"
   },
   "lint-staged": {
-    "*.{js,ts,vue,css,md,json,yml,yaml}": "eslint --fix || true"
+    "*.{js,ts,vue,css,json,yml,yaml}": "eslint --fix || true",
-  },
+    "*.{md,markdown,mdc}": "markdownlint-cli2 --fix"
-  "commitlint": { 
-    "extends": ["@commitlint/config-conventional"] 
   },
+
   "dependencies": {
     "@capacitor-community/electron": "^5.0.1",
     "@capacitor-community/sqlite": "6.0.2",
@@ -146,6 +145,7 @@
     "@capacitor/app": "^6.0.0",
     "@capacitor/camera": "^6.0.0",
     "@capacitor/cli": "^6.2.0",
+    "@capacitor/clipboard": "^6.0.2",
     "@capacitor/core": "^6.2.0",
     "@capacitor/filesystem": "^6.0.0",
     "@capacitor/ios": "^6.2.0",
@@ -228,6 +228,8 @@
   },
   "devDependencies": {
     "@capacitor/assets": "^3.0.5",
+    "@commitlint/cli": "^18.6.1",
+    "@commitlint/config-conventional": "^18.6.2",
     "@playwright/test": "^1.54.2",
     "@types/dom-webcodecs": "^0.1.7",
     "@types/jest": "^30.0.0",
@@ -255,13 +257,12 @@
     "eslint-plugin-prettier": "^5.2.1",
     "eslint-plugin-vue": "^9.32.0",
     "fs-extra": "^11.3.0",
+    "husky": "^9.0.11",
     "jest": "^30.0.4",
+    "lint-staged": "^15.2.2",
     "markdownlint": "^0.37.4",
     "markdownlint-cli": "^0.44.0",
-    "husky": "^9.0.11",
+    "markdownlint-cli2": "^0.18.1",
-    "lint-staged": "^15.2.2",
-    "@commitlint/cli": "^18.6.1",
-    "@commitlint/config-conventional": "^18.6.2",
     "npm-check-updates": "^17.1.13",
     "path-browserify": "^1.0.1",
     "postcss": "^8.4.38",

src/App.vue

@@ -4,7 +4,7 @@
   <!-- Messages in the upper-right - https://github.com/emmanuelsw/notiwind -->
   <NotificationGroup group="alert">
     <div
-      class="fixed z-[90] top-[max(1rem,env(safe-area-inset-top),var(--safe-area-inset-top,0px))] right-4 left-4 sm:left-auto sm:w-full sm:max-w-sm flex flex-col items-start justify-end"
+      class="fixed z-[120] top-[max(1rem,env(safe-area-inset-top),var(--safe-area-inset-top,0px))] right-4 left-4 sm:left-auto sm:w-full sm:max-w-sm flex flex-col items-start justify-end"
     >
       <Notification
         v-slot="{ notifications, close }"

src/assets/styles/tailwind.css

@@ -14,4 +14,12 @@
 		transform: translateX(100%);
 		background-color: #FFF !important;
 	}
+
+	.dialog-overlay {
+		@apply z-[100] fixed inset-0 bg-black/50 flex justify-center items-center p-6;
+	}
+
+	.dialog {
+		@apply bg-white p-4 rounded-lg w-full max-w-lg;
+	}
 }

src/components/ContactNameDialog.vue

@@ -1,7 +1,7 @@
 <!-- similar to UserNameDialog -->
 <template>
-  <div v-if="visible" :class="overlayClasses">
+  <div v-if="visible" class="dialog-overlay">
-    <div :class="dialogClasses">
+    <div class="dialog">
       <h1 :class="titleClasses">{{ title }}</h1>
       {{ message }}
       Note that their name is only stored on this device.
@@ -61,20 +61,6 @@ export default class ContactNameDialog extends Vue {
   title = "Contact Name";
   visible = false;
 
-  /**
-   * CSS classes for the modal overlay backdrop
-   */
-  get overlayClasses(): string {
-    return "z-index-50 fixed top-0 left-0 right-0 bottom-0 bg-black/50 flex justify-center items-center p-6";
-  }
-
-  /**
-   * CSS classes for the modal dialog container
-   */
-  get dialogClasses(): string {
-    return "bg-white p-4 rounded-lg w-full max-w-[500px]";
-  }
-
   /**
    * CSS classes for the dialog title
    */

src/components/FeedFilters.vue

@@ -212,30 +212,7 @@ export default class FeedFilters extends Vue {
 </script>
 
 <style>
-.dialog-overlay {
-  z-index: 50;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
 #dialogFeedFilters.dialog-overlay {
-  z-index: 100;
   overflow: scroll;
 }
-
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 500px;
-}
 </style>

src/components/GiftedDialog.vue

@@ -665,27 +665,3 @@ export default class GiftedDialog extends Vue {
   }
 }
 </script>
-
-<style>
-.dialog-overlay {
-  z-index: 50;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 500px;
-}
-</style>

src/components/GiftedPrompts.vue

@@ -291,27 +291,3 @@ export default class GivenPrompts extends Vue {
   }
 }
 </script>
-
-<style>
-.dialog-overlay {
-  z-index: 50;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 500px;
-}
-</style>

src/components/HiddenDidDialog.vue

@@ -1,9 +1,6 @@
 <template>
-  <div
+  <div v-if="isOpen" class="dialog-overlay">
-    v-if="isOpen"
+    <div class="dialog">
-    class="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center z-50"
-  >
-    <div class="bg-white rounded-lg p-6 max-w-2xl w-full mx-4">
       <!-- Header -->
       <div class="flex justify-between items-center mb-4">
         <h2 class="text-xl font-bold capitalize">{{ roleName }} Details</h2>

src/components/ImageMethodDialog.vue

@@ -1,5 +1,5 @@
 <template>
-  <div v-if="visible" class="dialog-overlay z-[60]">
+  <div v-if="visible" class="dialog-overlay">
     <div class="dialog relative">
       <div class="text-lg text-center font-bold relative">
         <h1 id="ViewHeading" class="text-center font-bold">
@@ -931,32 +931,6 @@ export default class ImageMethodDialog extends Vue {
 </script>
 
 <style>
-.dialog-overlay {
-  z-index: 50;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 700px;
-  max-height: 90vh;
-  overflow: hidden;
-  display: flex;
-  flex-direction: column;
-}
-
 /* Add styles for diagnostic panel */
 .diagnostic-panel {
   font-family: monospace;

src/components/InviteDialog.vue

@@ -93,27 +93,3 @@ export default class InviteDialog extends Vue {
   }
 }
 </script>
-
-<style>
-.dialog-overlay {
-  z-index: 50;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 500px;
-}
-</style>

src/components/OfferDialog.vue

@@ -312,28 +312,3 @@ export default class OfferDialog extends Vue {
   }
 }
 </script>
-
-<style scoped>
-.dialog-overlay {
-  position: fixed;
-  top: 0;
-  left: 0;
-  width: 100%;
-  height: 100%;
-  background: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  z-index: 50;
-}
-
-.dialog {
-  background: white;
-  padding: 1.5rem;
-  border-radius: 0.5rem;
-  max-width: 500px;
-  width: 90%;
-  max-height: 90vh;
-  overflow-y: auto;
-}
-</style>

src/components/OnboardingDialog.vue

@@ -307,27 +307,3 @@ export default class OnboardingDialog extends Vue {
   }
 }
 </script>
-
-<style>
-.dialog-overlay {
-  z-index: 40;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 500px;
-}
-</style>

src/components/PhotoDialog.vue

@@ -10,7 +10,7 @@ Comprehensive error handling * * @author Matthew Raymer * @version 1.0.0 * @file
 PhotoDialog.vue */
 
 <template>
-  <div v-if="visible" class="dialog-overlay z-[60]">
+  <div v-if="visible" class="dialog-overlay">
     <div class="dialog relative">
       <div class="text-lg text-center font-light relative z-50">
         <div id="ViewHeading" :class="headingClasses">
@@ -628,34 +628,6 @@ export default class PhotoDialog extends Vue {
 </script>
 
 <style>
-/* Dialog overlay styling */
-.dialog-overlay {
-  z-index: 60;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
-/* Dialog container styling */
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 700px;
-  max-height: 90vh;
-  overflow: hidden;
-  display: flex;
-  flex-direction: column;
-}
-
 /* Camera preview styling */
 .camera-preview {
   flex: 1;

src/components/RegistrationNotice.vue

@@ -1,33 +1,154 @@
+/** * @file RegistrationNotice.vue * @description Reusable component for
+displaying user registration status and related actions. * Shows registration
+notice when user is not registered, with options to show identifier info * or
+access advanced options. * * @author Jose Olarte III * @version 1.0.0 * @created
+2025-08-21T17:25:28-08:00 */
+
 <template>
   <div
-    v-if="!isRegistered && show"
+    id="noticeSomeoneMustRegisterYou"
-    id="noticeBeforeAnnounce"
+    class="bg-amber-200 text-amber-900 border-amber-500 border-dashed border text-center rounded-md overflow-hidden px-4 py-3 my-4"
-    class="bg-amber-200 text-amber-900 border-amber-500 border-dashed border text-center rounded-md overflow-hidden px-4 py-3 mt-4"
-    role="alert"
-    aria-live="polite"
   >
-    <p class="mb-4">
+    <p class="mb-4">{{ message }}</p>
-      Before you can publicly announce a new project or time commitment, a
+    <div class="grid grid-cols-1 gap-2 sm:flex sm:justify-center">
-      friend needs to register you.
+      <button
-    </p>
+        class="inline-block text-md font-bold bg-gradient-to-b from-blue-400 to-blue-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white px-4 py-2 rounded-md"
-    <button
+        @click="showNameThenIdDialog"
-      class="inline-block text-md bg-gradient-to-b from-blue-400 to-blue-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white px-4 py-2 rounded-md"
+      >
-      @click="shareInfo"
+        Show them {{ passkeysEnabled ? "default" : "your" }} identifier info
-    >
+      </button>
-      Share Your Info
+      <button
-    </button>
+        class="inline-block text-md bg-gradient-to-b from-slate-400 to-slate-700 shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.5)] text-white px-4 py-2 rounded-md"
+        @click="openAdvancedOptions"
+      >
+        See advanced options
+      </button>
+    </div>
   </div>
+  <UserNameDialog ref="userNameDialog" />
+  <ChoiceButtonDialog ref="choiceButtonDialog" />
 </template>
 
 <script lang="ts">
-import { Component, Vue, Prop, Emit } from "vue-facing-decorator";
+import { Component, Vue, Prop } from "vue-facing-decorator";
+import { Router } from "vue-router";
+import { Capacitor } from "@capacitor/core";
+import UserNameDialog from "./UserNameDialog.vue";
+import ChoiceButtonDialog from "./ChoiceButtonDialog.vue";
 
-@Component({ name: "RegistrationNotice" })
+/**
+ * RegistrationNotice Component
+ *
+ * Displays registration status notice and provides actions for unregistered users.
+ * Handles all registration-related flows internally without requiring parent component intervention.
+ *
+ * Template Usage:
+ * ```vue
+ * <RegistrationNotice
+ *   v-if="!isUserRegistered"
+ *   :passkeys-enabled="PASSKEYS_ENABLED"
+ *   :given-name="givenName"
+ *   message="Custom registration message here"
+ * />
+ * ```
+ *
+ * Component Dependencies:
+ * - UserNameDialog: Dialog for entering user name
+ * - ChoiceButtonDialog: Dialog for sharing method selection
+ */
+@Component({
+  name: "RegistrationNotice",
+  components: {
+    UserNameDialog,
+    ChoiceButtonDialog,
+  },
+})
 export default class RegistrationNotice extends Vue {
-  @Prop({ required: true }) isRegistered!: boolean;
+  $router!: Router;
-  @Prop({ required: true }) show!: boolean;
 
-  @Emit("share-info")
+  /**
-  shareInfo() {}
+   * Whether passkeys are enabled in the application
+   */
+  @Prop({ required: true })
+  passkeysEnabled!: boolean;
+
+  /**
+   * User's given name for dialog pre-population
+   */
+  @Prop({ required: true })
+  givenName!: string;
+
+  /**
+   * Custom message to display in the registration notice
+   * Defaults to "To share, someone must register you."
+   */
+  @Prop({ default: "To share, someone must register you." })
+  message!: string;
+
+  /**
+   * Shows name input dialog if needed
+   * Handles the full flow internally without requiring parent component intervention
+   */
+  showNameThenIdDialog() {
+    this.openUserNameDialog(() => {
+      this.promptForShareMethod();
+    });
+  }
+
+  /**
+   * Opens advanced options page
+   * Navigates directly to the start page
+   */
+  openAdvancedOptions() {
+    this.$router.push({ name: "start" });
+  }
+
+  /**
+   * Shows dialog for sharing method selection
+   * Provides options for different sharing scenarios
+   */
+  promptForShareMethod() {
+    (this.$refs.choiceButtonDialog as ChoiceButtonDialog).open({
+      title: "How can you share your info?",
+      text: "",
+      option1Text: "We are nearby with cameras",
+      option2Text: "Someone created a meeting room",
+      option3Text: "We will share some other way",
+      onOption1: () => {
+        this.handleQRCodeClick();
+      },
+      onOption2: () => {
+        this.$router.push({ name: "onboard-meeting-list" });
+      },
+      onOption3: () => {
+        this.$router.push({ name: "share-my-contact-info" });
+      },
+    });
+  }
+
+  /**
+   * Handles QR code sharing based on platform
+   * Navigates to appropriate QR code page
+   */
+  private handleQRCodeClick() {
+    if (Capacitor.isNativePlatform()) {
+      this.$router.push({ name: "contact-qr-scan-full" });
+    } else {
+      this.$router.push({ name: "contact-qr" });
+    }
+  }
+
+  /**
+   * Opens the user name dialog if needed
+   *
+   * @param callback Function to call after name is entered
+   */
+  openUserNameDialog(callback: () => void) {
+    if (!this.givenName) {
+      (this.$refs.userNameDialog as UserNameDialog).open(callback);
+    } else {
+      callback();
+    }
+  }
 }
 </script>

src/components/UserNameDialog.vue

@@ -134,27 +134,3 @@ export default class UserNameDialog extends Vue {
   }
 }
 </script>
-
-<style>
-.dialog-overlay {
-  z-index: 50;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 500px;
-}
-</style>

src/libs/endorserServer.ts

@@ -309,7 +309,7 @@ export function didInfoForContact(
   showDidForVisible: boolean = false,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): { known: boolean; displayName: string; profileImageUrl?: string } {
-  if (!did) return { displayName: "Someone Unnamed/Unknown", known: false };
+  if (!did) return { displayName: "Someone Not Named", known: false };
   if (did === activeDid) {
     return { displayName: "You", known: true };
   } else if (contact) {

src/libs/util.ts

@@ -657,7 +657,7 @@ export async function saveNewIdentity(
 
     await platformService.updateDefaultSettings({ activeDid: identity.did });
 
-    await platformService.insertDidSpecificSettings(identity.did);
+    await platformService.insertNewDidIntoSettings(identity.did);
   } catch (error) {
     logger.error("Failed to update default settings:", error);
     throw new Error(
@@ -954,7 +954,7 @@ export async function importFromMnemonic(
 
     try {
       // First, ensure the DID-specific settings record exists
-      await platformService.insertDidSpecificSettings(newId.did);
+      await platformService.insertNewDidIntoSettings(newId.did);
 
       // Then update with Test User #0 specific settings
       await platformService.updateDidSpecificSettings(newId.did, {

src/services/ClipboardService.ts

@@ -0,0 +1,185 @@
+import { Capacitor } from "@capacitor/core";
+import { Clipboard } from "@capacitor/clipboard";
+import { useClipboard } from "@vueuse/core";
+import { logger } from "@/utils/logger";
+
+/**
+ * Platform-agnostic clipboard service that handles both web and native platforms
+ * Provides reliable clipboard functionality across all platforms including iOS
+ */
+export class ClipboardService {
+  private static instance: ClipboardService | null = null;
+
+  /**
+   * Get singleton instance of ClipboardService
+   */
+  public static getInstance(): ClipboardService {
+    if (!ClipboardService.instance) {
+      ClipboardService.instance = new ClipboardService();
+    }
+    return ClipboardService.instance;
+  }
+
+  /**
+   * Copy text to clipboard with platform-specific handling
+   *
+   * @param text - The text to copy to clipboard
+   * @returns Promise that resolves when copy is complete
+   * @throws Error if copy operation fails
+   */
+  public async copyToClipboard(text: string): Promise<void> {
+    const platform = Capacitor.getPlatform();
+    const isNative = Capacitor.isNativePlatform();
+
+    logger.debug("[ClipboardService] Copying to clipboard:", {
+      text: text.substring(0, 50) + (text.length > 50 ? "..." : ""),
+      platform,
+      isNative,
+      timestamp: new Date().toISOString(),
+    });
+
+    try {
+      if (isNative && (platform === "ios" || platform === "android")) {
+        // Use native Capacitor clipboard for mobile platforms
+        await this.copyNative(text);
+      } else {
+        // Use web clipboard API for web/desktop platforms
+        await this.copyWeb(text);
+      }
+
+      logger.debug("[ClipboardService] Copy successful", {
+        platform,
+        timestamp: new Date().toISOString(),
+      });
+    } catch (error) {
+      logger.error("[ClipboardService] Copy failed:", {
+        error: error instanceof Error ? error.message : String(error),
+        platform,
+        timestamp: new Date().toISOString(),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Copy text using native Capacitor clipboard API
+   *
+   * @param text - The text to copy
+   * @returns Promise that resolves when copy is complete
+   */
+  private async copyNative(text: string): Promise<void> {
+    try {
+      await Clipboard.write({
+        string: text,
+      });
+    } catch (error) {
+      logger.error("[ClipboardService] Native copy failed:", {
+        error: error instanceof Error ? error.message : String(error),
+        timestamp: new Date().toISOString(),
+      });
+      throw new Error(
+        `Native clipboard copy failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  /**
+   * Copy text using web clipboard API with fallback
+   *
+   * @param text - The text to copy
+   * @returns Promise that resolves when copy is complete
+   */
+  private async copyWeb(text: string): Promise<void> {
+    try {
+      // Try VueUse clipboard first (handles some edge cases)
+      const { copy } = useClipboard();
+      await copy(text);
+    } catch (error) {
+      logger.warn(
+        "[ClipboardService] VueUse clipboard failed, trying native API:",
+        {
+          error: error instanceof Error ? error.message : String(error),
+          timestamp: new Date().toISOString(),
+        },
+      );
+
+      // Fallback to native navigator.clipboard
+      if (navigator.clipboard && navigator.clipboard.writeText) {
+        await navigator.clipboard.writeText(text);
+      } else {
+        throw new Error("Clipboard API not supported in this browser");
+      }
+    }
+  }
+
+  /**
+   * Read text from clipboard (platform-specific)
+   *
+   * @returns Promise that resolves to the clipboard text
+   * @throws Error if read operation fails
+   */
+  public async readFromClipboard(): Promise<string> {
+    const platform = Capacitor.getPlatform();
+    const isNative = Capacitor.isNativePlatform();
+
+    try {
+      if (isNative && (platform === "ios" || platform === "android")) {
+        // Use native Capacitor clipboard for mobile platforms
+        const result = await Clipboard.read();
+        return result.value || "";
+      } else {
+        // Use web clipboard API for web/desktop platforms
+        if (navigator.clipboard && navigator.clipboard.readText) {
+          return await navigator.clipboard.readText();
+        } else {
+          throw new Error("Clipboard read API not supported in this browser");
+        }
+      }
+    } catch (error) {
+      logger.error("[ClipboardService] Read from clipboard failed:", {
+        error: error instanceof Error ? error.message : String(error),
+        platform,
+        timestamp: new Date().toISOString(),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Check if clipboard is supported on current platform
+   *
+   * @returns boolean indicating if clipboard is supported
+   */
+  public isSupported(): boolean {
+    const platform = Capacitor.getPlatform();
+    const isNative = Capacitor.isNativePlatform();
+
+    if (isNative && (platform === "ios" || platform === "android")) {
+      return true; // Capacitor clipboard should work on native platforms
+    }
+
+    // Check web clipboard support
+    return !!(navigator.clipboard && navigator.clipboard.writeText);
+  }
+}
+
+/**
+ * Convenience function to copy text to clipboard
+ * Uses the singleton ClipboardService instance
+ *
+ * @param text - The text to copy to clipboard
+ * @returns Promise that resolves when copy is complete
+ */
+export async function copyToClipboard(text: string): Promise<void> {
+  return ClipboardService.getInstance().copyToClipboard(text);
+}
+
+/**
+ * Convenience function to read text from clipboard
+ * Uses the singleton ClipboardService instance
+ *
+ * @returns Promise that resolves to the clipboard text
+ */
+export async function readFromClipboard(): Promise<string> {
+  return ClipboardService.getInstance().readFromClipboard();
+}

src/services/PlatformService.ts

@@ -175,11 +175,11 @@ export interface PlatformService {
   updateDefaultSettings(settings: Record<string, unknown>): Promise<void>;
 
   /**
-   * Inserts DID-specific settings into the database.
+   * Inserts a new DID into the settings table.
    * @param did - The DID to associate with the settings
    * @returns Promise that resolves when the insertion is complete
    */
-  insertDidSpecificSettings(did: string): Promise<void>;
+  insertNewDidIntoSettings(did: string): Promise<void>;
 
   /**
    * Updates DID-specific settings in the database.

src/services/platforms/CapacitorPlatformService.ts

@@ -1319,7 +1319,7 @@ export class CapacitorPlatformService implements PlatformService {
     await this.dbExec(sql, params);
   }
 
-  async insertDidSpecificSettings(did: string): Promise<void> {
+  async insertNewDidIntoSettings(did: string): Promise<void> {
     await this.dbExec("INSERT INTO settings (accountDid) VALUES (?)", [did]);
   }
 

src/services/platforms/WebPlatformService.ts

@@ -681,7 +681,7 @@ export class WebPlatformService implements PlatformService {
     await this.dbExec(sql, params);
   }
 
-  async insertDidSpecificSettings(did: string): Promise<void> {
+  async insertNewDidIntoSettings(did: string): Promise<void> {
     await this.dbExec("INSERT INTO settings (accountDid) VALUES (?)", [did]);
   }
 

src/test/index.ts

@@ -50,6 +50,10 @@ export async function testServerRegisterUser() {
     "@/db/databaseUtil"
   );
   const settings = await retrieveSettingsForActiveAccount();
+  const currentDid = settings?.activeDid;
+  if (!currentDid) {
+    throw new Error("No active DID found");
+  }
 
   // Make a claim
   const vcClaim = {
@@ -57,7 +61,7 @@ export async function testServerRegisterUser() {
     "@type": "RegisterAction",
     agent: { identifier: identity0.did },
     object: SERVICE_ID,
-    participant: { identifier: settings.activeDid },
+    participant: { identifier: currentDid },
   };
 
   // Make a payload for the claim
@@ -94,5 +98,12 @@ export async function testServerRegisterUser() {
 
   const resp = await axios.post(url, payload, { headers });
   logger.log("User registration result:", resp);
+
+  const platformService = await PlatformServiceFactory.getInstance();
+  await platformService.updateDefaultSettings({ activeDid: currentDid });
+  await platformService.updateDidSpecificSettings(currentDid!, {
+    isRegistered: true,
+  });
+
   return resp;
 }

src/views/AccountViewView.vue

@@ -55,9 +55,11 @@
 
     <!-- Registration notice -->
     <RegistrationNotice
-      :is-registered="isRegistered"
+      v-if="!isRegistered"
-      :show="showRegistrationNotice"
+      :passkeys-enabled="PASSKEYS_ENABLED"
-      @share-info="onShareInfo"
+      :given-name="givenName"
+      message="Before you can publicly announce a new project or time commitment,
+        a friend needs to register you."
     />
 
     <!-- Notifications -->
@@ -781,6 +783,7 @@ import {
   DEFAULT_PUSH_SERVER,
   IMAGE_TYPE_PROFILE,
   NotificationIface,
+  PASSKEYS_ENABLED,
 } from "../constants/app";
 import { Contact } from "../db/tables/contacts";
 import {
@@ -851,6 +854,7 @@ export default class AccountViewView extends Vue {
   readonly DEFAULT_PUSH_SERVER: string = DEFAULT_PUSH_SERVER;
   readonly DEFAULT_IMAGE_API_SERVER: string = DEFAULT_IMAGE_API_SERVER;
   readonly DEFAULT_PARTNER_API_SERVER: string = DEFAULT_PARTNER_API_SERVER;
+  readonly PASSKEYS_ENABLED: boolean = PASSKEYS_ENABLED;
 
   // Identity and settings properties
   activeDid: string = "";
@@ -1789,20 +1793,6 @@ export default class AccountViewView extends Vue {
     this.doCopyTwoSecRedo(did, () => (this.showDidCopy = !this.showDidCopy));
   }
 
-  get showRegistrationNotice(): boolean {
-    // Show the notice if not registered and any other conditions you want
-    return !this.isRegistered;
-  }
-
-  onShareInfo() {
-    // Navigate to QR code sharing page - mobile uses full scan, web uses basic
-    if (Capacitor.isNativePlatform()) {
-      this.$router.push({ name: "contact-qr-scan-full" });
-    } else {
-      this.$router.push({ name: "contact-qr" });
-    }
-  }
-
   onRecheckLimits() {
     this.checkLimits();
   }

src/views/ContactGiftingView.vue

@@ -24,7 +24,7 @@
               icon="circle-question"
               class="text-slate-400 text-4xl"
             />
-            <span class="italic text-slate-400">(Unnamed/Unknown)</span>
+            <span class="italic text-slate-400">(Not Named)</span>
           </span>
           <span class="text-right">
             <button

src/views/ContactQRScanShowView.vue

@@ -140,7 +140,7 @@ import { AxiosError } from "axios";
 import { Buffer } from "buffer/";
 import QRCodeVue3 from "qr-code-generator-vue3";
 import { Component, Vue } from "vue-facing-decorator";
-import { useClipboard } from "@vueuse/core";
+
 import { QrcodeStream } from "vue-qrcode-reader";
 
 import QuickNav from "../components/QuickNav.vue";
@@ -183,8 +183,6 @@ import {
   NOTIFY_QR_PROCESSING_ERROR,
   createQRContactAddedMessage,
   createQRRegistrationSuccessMessage,
-  QR_TIMEOUT_SHORT,
-  QR_TIMEOUT_MEDIUM,
   QR_TIMEOUT_STANDARD,
   QR_TIMEOUT_LONG,
 } from "@/constants/notifications";
@@ -544,11 +542,7 @@ export default class ContactQRScanShow extends Vue {
       did: contact.did,
       name: contact.name,
     });
-    this.notify.toast(
+    this.notify.toast("Submitted", NOTIFY_QR_REGISTRATION_SUBMITTED.message);
-      "Submitted",
-      NOTIFY_QR_REGISTRATION_SUBMITTED.message,
-      QR_TIMEOUT_SHORT,
-    );
 
     try {
       const regResult = await register(
@@ -624,18 +618,15 @@ export default class ContactQRScanShow extends Vue {
       );
 
       // Copy the URL to clipboard
-      useClipboard()
+      const { copyToClipboard } = await import("../services/ClipboardService");
-        .copy(jwtUrl)
+      await copyToClipboard(jwtUrl);
-        .then(() => {
+      this.notify.toast(
-          this.notify.toast(
+        NOTIFY_QR_URL_COPIED.title,
-            "Copied",
+        NOTIFY_QR_URL_COPIED.message,
-            NOTIFY_QR_URL_COPIED.message,
+      );
-            QR_TIMEOUT_MEDIUM,
-          );
-        });
     } catch (error) {
-      logger.error("Failed to generate contact URL:", error);
+      this.$logAndConsole(`Error copying URL to clipboard: ${error}`, true);
-      this.notify.error("Failed to generate contact URL. Please try again.");
+      this.notify.error("Failed to copy URL to clipboard.");
     }
   }
 
@@ -643,13 +634,16 @@ export default class ContactQRScanShow extends Vue {
     this.notify.info(NOTIFY_QR_CODE_HELP.message, QR_TIMEOUT_LONG);
   }
 
-  onCopyDidToClipboard() {
+  async onCopyDidToClipboard() {
     //this.onScanDetect([{ rawValue: this.qrValue }]); // good for testing
-    useClipboard()
+    try {
-      .copy(this.activeDid)
+      const { copyToClipboard } = await import("../services/ClipboardService");
-      .then(() => {
+      await copyToClipboard(this.activeDid);
-        this.notify.info(NOTIFY_QR_DID_COPIED.message, QR_TIMEOUT_LONG);
+      this.notify.info(NOTIFY_QR_DID_COPIED.message, QR_TIMEOUT_LONG);
-      });
+    } catch (error) {
+      this.$logAndConsole(`Error copying DID to clipboard: ${error}`, true);
+      this.notify.error("Failed to copy DID to clipboard.");
+    }
   }
 
   openUserNameDialog() {
@@ -745,7 +739,6 @@ export default class ContactQRScanShow extends Vue {
       ) {
         setTimeout(() => {
           this.notify.confirm(
-            "Register",
             "Do you want to register them?",
             {
               onCancel: async (stopAsking?: boolean) => {

src/views/ContactsView.vue

@@ -130,10 +130,9 @@ import { JWTPayload } from "did-jwt";
 import * as R from "ramda";
 import { Component, Vue } from "vue-facing-decorator";
 import { RouteLocationNormalizedLoaded, Router } from "vue-router";
-import { useClipboard } from "@vueuse/core";
-// Capacitor import removed - using PlatformService instead
 
 import QuickNav from "../components/QuickNav.vue";
+import { copyToClipboard } from "../services/ClipboardService";
 import EntityIcon from "../components/EntityIcon.vue";
 import GiftedDialog from "../components/GiftedDialog.vue";
 import OfferDialog from "../components/OfferDialog.vue";
@@ -1192,12 +1191,14 @@ export default class ContactsView extends Vue {
     });
     // Use production URL for sharing to avoid localhost issues in development
     const contactsJwtUrl = `${APP_SERVER}/deep-link/contact-import/${contactsJwt}`;
-    useClipboard()
+    try {
-      .copy(contactsJwtUrl)
+      await copyToClipboard(contactsJwtUrl);
-      .then(() => {
+      // Use notification helper
-        // Use notification helper
+      this.notify.copied(NOTIFY_CONTACT_LINK_COPIED.message);
-        this.notify.copied(NOTIFY_CONTACT_LINK_COPIED.message);
+    } catch (error) {
-      });
+      this.$logAndConsole(`Error copying to clipboard: ${error}`, true);
+      this.notify.error("Failed to copy to clipboard. Please try again.");
+    }
   }
 
   private showCopySelectionsInfo() {

src/views/DIDView.vue

@@ -831,26 +831,3 @@ export default class DIDView extends Vue {
   }
 }
 </script>
-
-<style>
-.dialog-overlay {
-  z-index: 50;
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  bottom: 0;
-  background-color: rgba(0, 0, 0, 0.5);
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  padding: 1.5rem;
-}
-.dialog {
-  background-color: white;
-  padding: 1rem;
-  border-radius: 0.5rem;
-  width: 100%;
-  max-width: 500px;
-}
-</style>

src/views/DeepLinkErrorView.vue

@@ -1,6 +1,6 @@
 <template>
-  <div class="deep-link-error">
+  <!-- CONTENT -->
-    <div class="safe-area-spacer"></div>
+  <section id="Content" class="p-6 pb-24 max-w-3xl mx-auto">
     <h1>Invalid Deep Link</h1>
     <div class="error-details">
       <div class="error-message">
@@ -39,7 +39,7 @@
         </li>
       </ul>
     </div>
-  </div>
+  </section>
 </template>
 
 <script setup lang="ts">
@@ -114,18 +114,6 @@ onMounted(() => {
 </script>
 
 <style scoped>
-.deep-link-error {
-  padding-top: 60px;
-  padding-left: 20px;
-  padding-right: 20px;
-  max-width: 600px;
-  margin: 0 auto;
-}
-
-.safe-area-spacer {
-  height: max(env(safe-area-inset-top), var(--safe-area-inset-top, 0px));
-}
-
 h1 {
   color: #ff4444;
   margin-bottom: 24px;

src/views/DeepLinkRedirectView.vue

@@ -1,95 +1,87 @@
 <template>
   <!-- CONTENT -->
-  <section id="Content" class="relative w-[100vw] h-[100vh]">
+  <section id="Content" class="p-6 pb-24 max-w-3xl mx-auto">
-    <div
+    <div class="mb-4">
-      class="p-6 bg-white w-full max-w-[calc((100vh-max(env(safe-area-inset-top),var(--safe-area-inset-top,0px))-max(env(safe-area-inset-bottom),var(--safe-area-inset-bottom,0px)))*0.4)] mx-auto"
+      <h1 class="text-2xl text-center font-semibold relative px-7">
-    >
+        Redirecting to Time Safari
-      <div class="mb-4">
+      </h1>
-        <h1 class="text-xl text-center font-semibold relative mb-4">
-          Redirecting to Time Safari
-        </h1>
 
-        <div v-if="destinationUrl" class="space-y-4">
+      <div v-if="destinationUrl" class="space-y-4">
-          <!-- Platform-specific messaging -->
+        <!-- Platform-specific messaging -->
-          <div class="text-center text-gray-600 mb-4">
+        <div class="text-center text-gray-600 mb-4">
-            <p v-if="isMobile">
+          <p v-if="isMobile">
-              {{
+            {{
-                isIOS
+              isIOS
-                  ? "Opening Time Safari app on your iPhone..."
+                ? "Opening Time Safari app on your iPhone..."
-                  : "Opening Time Safari app on your Android device..."
+                : "Opening Time Safari app on your Android device..."
-              }}
+            }}
-            </p>
+          </p>
-            <p v-else>Opening Time Safari app...</p>
+          <p v-else>Opening Time Safari app...</p>
-            <p class="text-sm mt-2">
+          <p class="text-sm mt-2">
-              <span v-if="isMobile"
+            <span v-if="isMobile"
-                >If the app doesn't open automatically, use one of these
+              >If the app doesn't open automatically, use one of these
-                options:</span
+              options:</span
-              >
-              <span v-else>Choose how you'd like to open this link:</span>
-            </p>
-          </div>
-
-          <!-- Deep Link Button -->
-          <div class="text-center">
-            <a
-              :href="deepLinkUrl || '#'"
-              class="inline-block bg-blue-600 text-white px-6 py-3 rounded-lg font-medium hover:bg-blue-700 transition-colors"
-              @click="handleDeepLinkClick"
             >
-              <span v-if="isMobile">Open in Time Safari App</span>
+            <span v-else>Choose how you'd like to open this link:</span>
-              <span v-else>Try Opening in Time Safari App</span>
+          </p>
-            </a>
+        </div>
-          </div>
 
-          <!-- Web Fallback Link -->
+        <!-- Deep Link Button -->
-          <div class="text-center">
+        <div class="text-center">
-            <a
+          <a
-              :href="webUrl || '#'"
+            :href="deepLinkUrl || '#'"
-              target="_blank"
+            class="inline-block bg-blue-600 text-white px-6 py-3 rounded-lg font-medium hover:bg-blue-700 transition-colors"
-              class="inline-block bg-gray-600 text-white px-6 py-3 rounded-lg font-medium hover:bg-gray-700 transition-colors"
+            @click="handleDeepLinkClick"
-              @click="handleWebFallbackClick"
-            >
-              <span v-if="isMobile">Open in Web Browser Instead</span>
-              <span v-else>Open in Web Browser</span>
-            </a>
-          </div>
-
-          <!-- Manual Instructions -->
-          <div class="text-center text-sm text-gray-500 mt-4">
-            <p v-if="isMobile">
-              Or manually open:
-              <code class="bg-gray-100 px-2 py-1 rounded">{{
-                deepLinkUrl
-              }}</code>
-            </p>
-            <p v-else>
-              If you have the Time Safari app installed, you can also copy this
-              link:
-              <code class="bg-gray-100 px-2 py-1 rounded">{{
-                deepLinkUrl
-              }}</code>
-            </p>
-          </div>
-
-          <!-- Platform info for debugging -->
-          <div
-            v-if="isDevelopment"
-            class="text-center text-xs text-gray-400 mt-4"
           >
-            <p>
+            <span v-if="isMobile">Open in Time Safari App</span>
-              Platform: {{ isMobile ? (isIOS ? "iOS" : "Android") : "Desktop" }}
+            <span v-else>Try Opening in Time Safari App</span>
-            </p>
+          </a>
-            <p>User Agent: {{ userAgent.substring(0, 50) }}...</p>
-          </div>
         </div>
 
-        <div v-else-if="pageError" class="text-center text-red-500 mb-4">
+        <!-- Web Fallback Link -->
-          {{ pageError }}
+        <div class="text-center">
+          <a
+            :href="webUrl || '#'"
+            target="_blank"
+            class="inline-block bg-gray-600 text-white px-6 py-3 rounded-lg font-medium hover:bg-gray-700 transition-colors"
+            @click="handleWebFallbackClick"
+          >
+            <span v-if="isMobile">Open in Web Browser Instead</span>
+            <span v-else>Open in Web Browser</span>
+          </a>
         </div>
 
-        <div v-else class="text-center text-gray-600">
+        <!-- Manual Instructions -->
-          <p>Processing redirect...</p>
+        <div class="text-center text-sm text-gray-500 mt-4">
+          <p v-if="isMobile">
+            Or manually open:
+            <code class="bg-gray-100 px-2 py-1 rounded">{{ deepLinkUrl }}</code>
+          </p>
+          <p v-else>
+            If you have the Time Safari app installed, you can also copy this
+            link:
+            <code class="bg-gray-100 px-2 py-1 rounded">{{ deepLinkUrl }}</code>
+          </p>
         </div>
+
+        <!-- Platform info for debugging -->
+        <div
+          v-if="isDevelopment"
+          class="text-center text-xs text-gray-400 mt-4"
+        >
+          <p>
+            Platform: {{ isMobile ? (isIOS ? "iOS" : "Android") : "Desktop" }}
+          </p>
+          <p>User Agent: {{ userAgent.substring(0, 50) }}...</p>
+        </div>
+      </div>
+
+      <div v-else-if="pageError" class="text-center text-red-500 mb-4">
+        {{ pageError }}
+      </div>
+
+      <div v-else class="text-center text-gray-600">
+        <p>Processing redirect...</p>
       </div>
     </div>
   </section>

src/views/HelpView.vue

@@ -18,6 +18,7 @@
       <!-- Heading -->
       <h1 id="ViewHeading" class="text-4xl text-center font-light pt-4 mb-8">
         Help
+        <span class="text-xs text-gray-500">{{ package.version }}</span>
       </h1>
     </div>