fix: linting

- Currently toggles & stores correctly locally on project. Does not show on other screens.

.cursor/rules/README.md

@@ -0,0 +1,306 @@
+# .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
+- **`meta_research.mdc`** - Investigation and research workflow bundling
+
+### **Workflow State Management**
+
+The project uses a sophisticated workflow state management system to ensure systematic development processes and maintain code quality across all phases of development.
+
+#### **Workflow State System**
+
+The workflow state is managed through `.cursor/rules/.workflow_state.json` and enforces different modes with specific constraints. The system automatically tracks workflow progression and maintains a complete history of mode transitions.
+
+**Available Modes**:
+- **`diagnosis`** - Investigation and analysis phase (read-only)
+- **`fixing`** - Implementation and bug fixing phase (full access)
+- **`planning`** - Design and architecture phase (design only)
+- **`research`** - Investigation and research phase (investigation only)
+- **`documentation`** - Documentation writing phase (writing only)
+
+**Mode Constraints**:
+```json
+{
+  "diagnosis": {
+    "mode": "read_only",
+    "forbidden": ["modify", "create", "build", "commit"],
+    "allowed": ["read", "search", "analyze", "document"]
+  },
+  "fixing": {
+    "mode": "implementation",
+    "forbidden": [],
+    "allowed": ["modify", "create", "build", "commit", "test"]
+  }
+}
+```
+
+**Workflow History Tracking**:
+
+The system automatically maintains a `workflowHistory` array that records all mode transitions and meta-rule invocations:
+
+```json
+{
+  "workflowHistory": [
+    {
+      "mode": "research",
+      "invoked": "meta_core_always_on.mdc",
+      "timestamp": "2025-08-25T02:14:37Z"
+    },
+    {
+      "mode": "diagnosis",
+      "invoked": "meta_bug_diagnosis.mdc", 
+      "timestamp": "2025-08-25T02:14:37Z"
+    }
+  ]
+}
+```
+
+**History Entry Format**:
+- **`mode`**: The workflow mode that was activated
+- **`invoked`**: The specific meta-rule that triggered the mode change
+- **`timestamp`**: UTC timestamp when the mode transition occurred
+
+**History Purpose**:
+- **Workflow Continuity**: Track progression through development phases
+- **Meta-Rule Usage**: Monitor which rules are invoked and when
+- **Temporal Context**: Maintain chronological order of workflow changes
+- **State Persistence**: Preserve workflow history across development sessions
+- **Debugging Support**: Help diagnose workflow state issues
+- **Process Analysis**: Understand development patterns and meta-rule effectiveness
+
+#### **Commit Override System**
+
+The workflow includes a flexible commit override mechanism that allows commits on demand while maintaining workflow integrity:
+
+```json
+{
+  "overrides": {
+    "commit": {
+      "allowed": true,
+      "requires_override": true,
+      "override_reason": "user_requested"
+    }
+  }
+}
+```
+
+**Override Benefits**:
+- ✅ **Investigation Commits**: Document findings during diagnosis phases
+- ✅ **Work-in-Progress**: Commit partial solutions during complex investigations
+- ✅ **Emergency Fixes**: Commit critical fixes without mode transitions
+- ✅ **Flexible Workflow**: Maintain systematic approach while accommodating real needs
+
+**Override Limitations**:
+- ❌ **Does NOT bypass**: Version control rules, commit message standards, or security requirements
+- ❌ **Does NOT bypass**: Code quality standards, testing requirements, or documentation requirements
+
+#### **Workflow Enforcement**
+
+The system automatically enforces workflow constraints through the core always-on rules:
+
+**Before Every Interaction**:
+1. **Read current workflow state** from `.cursor/rules/.workflow_state.json`
+2. **Identify current mode** and its constraints
+3. **Validate user request** against current mode constraints
+4. **Enforce constraints** before generating response
+5. **Guide model behavior** based on current mode
+
+**Mode-Specific Enforcement**:
+- **Diagnosis Mode**: Blocks modification, creation, building, and commits
+- **Fixing Mode**: Allows full implementation and testing capabilities
+- **Planning Mode**: Focuses on design and architecture, blocks implementation
+- **Research Mode**: Enables investigation and analysis, blocks modification
+- **Documentation Mode**: Allows writing and editing, blocks implementation
+
+#### **Workflow Transitions**
+
+To change workflow modes, invoke the appropriate meta-rule:
+
+```bash
+# Switch to bug fixing mode
+@meta_bug_fixing.mdc
+
+# Switch to feature planning mode  
+@meta_feature_planning.mdc
+
+# Switch to documentation mode
+@meta_documentation.mdc
+```
+
+**Transition Requirements**:
+- **Mode Changes**: Require explicit meta-rule invocation
+- **State Updates**: Automatically update workflow state file
+- **Constraint Enforcement**: Immediately apply new mode constraints
+- **History Tracking**: Automatically maintained in `workflowHistory` array
+- **Timestamp Recording**: Each transition recorded with UTC timestamp
+
+#### **Integration with Development Process**
+
+The workflow system integrates seamlessly with existing development practices:
+
+**Version Control**:
+- All commits must follow TimeSafari commit message standards
+- Security audit checklists are enforced regardless of workflow mode
+- Documentation updates are required for substantial changes
+
+**Quality Assurance**:
+- Code quality standards (PEP8, TypeScript, etc.) are always enforced
+- Testing requirements apply to all implementation work
+- Documentation standards are maintained across all phases
+
+**Build System**:
+- Build Architecture Guard protects critical build files
+- Platform-specific build processes respect workflow constraints
+- Asset generation follows established patterns
+
+**Migration Context**:
+- Database migration work respects investigation vs. implementation phases
+- Component migration progress is tracked through workflow states
+
+## 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/always_on_rules.mdc

@@ -0,0 +1,192 @@
+# 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/app/architectural_decision_record.mdc

@@ -0,0 +1,193 @@
+# 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**: Jest for business logic and utilities
+
+- **E2E Tests**: Playwright for critical user journeys
+
+- **Platform Tests**: Test platform-specific implementations
+
+- **Integration Tests**: Test service interactions
+
+## 7. Key Principles
+
+### Platform Independence
+
+- **Abstract platform differences** behind interfaces
+
+- **Use factory pattern** for service selection
+
+- **Maintain consistent APIs** across platforms
+
+- **Graceful degradation** when features unavailable
+
+### Code Organization
+
+- **Single responsibility** for each service
+
+- **Interface segregation** for platform services
+
+- **Dependency injection** via mixins
+
+- **Composition over inheritance**
+
+---
+
+**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**: Critical
+**Estimated Effort**: Ongoing reference
+**Dependencies**: timesafari.mdc
+**Stakeholders**: Development team, Architecture team
+
+- [ ] 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
+
+### Before Architectural Decisions
+
+- [ ] **Decision Context**: Understand the architectural challenge to be addressed
+- [ ] **Stakeholder Identification**: Identify all decision makers and affected parties
+- [ ] **Research**: Research alternatives and gather evidence
+- [ ] **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

@@ -0,0 +1,173 @@
+---
+alwaysApply: false
+---
+# Time Safari Context
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Core application context
+
+## Project Overview
+
+Time Safari is an application designed to foster community building through
+gifts, gratitude, and collaborative projects. The app makes it easy and
+intuitive for users of any age and capability to recognize contributions,
+build trust networks, and organize collective action. It is built on services
+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.
+
+## Technical Foundation
+
+### 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
+
+### 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
+
+---
+
+**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
+
+- **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/architectural_decision_record.mdc

@@ -1,287 +0,0 @@
----
-description: 
-globs: 
-alwaysApply: true
----
-# TimeSafari Cross-Platform Architecture Guide
-
-## 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
-
-### 2.1 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 and type definitions
-└── assets/        # Static assets
-```
-
-### 2.2 Entry Points
-```
-src/
-├── main.ts              # Base entry
-├── main.common.ts       # Shared initialization
-├── main.capacitor.ts    # Mobile entry
-├── main.electron.ts     # Electron entry
-└── main.web.ts          # Web/PWA entry
-```
-
-### 2.3 Build Configurations
-```
-root/
-├── vite.config.common.mts    # Shared config
-├── vite.config.capacitor.mts # Mobile build
-├── vite.config.electron.mts  # Electron build
-└── vite.config.web.mts      # Web/PWA build
-```
-
-## 3. Service Architecture
-
-### 3.1 Service Organization
-```
-services/
-├── QRScanner/           # QR code scanning service
-│   ├── WebInlineQRScanner.ts
-│   └── interfaces.ts
-├── platforms/          # Platform-specific services
-│   ├── WebPlatformService.ts
-│   ├── CapacitorPlatformService.ts
-│   └── ElectronPlatformService.ts
-└── factory/           # Service factories
-    └── PlatformServiceFactory.ts
-```
-
-### 3.2 Service Factory Pattern
-```typescript
-// PlatformServiceFactory.ts
-export class PlatformServiceFactory {
-  private static instance: PlatformService | null = null;
-
-  public static getInstance(): PlatformService {
-    if (!PlatformServiceFactory.instance) {
-      const platform = process.env.VITE_PLATFORM || "web";
-      PlatformServiceFactory.instance = createPlatformService(platform);
-    }
-    return PlatformServiceFactory.instance;
-  }
-}
-```
-
-## 4. Feature Implementation Guidelines
-
-### 4.1 QR Code Scanning
-
-1. **Service Interface**
-```typescript
-interface QRScannerService {
-  checkPermissions(): Promise<boolean>;
-  requestPermissions(): Promise<boolean>;
-  isSupported(): Promise<boolean>;
-  startScan(): Promise<void>;
-  stopScan(): Promise<void>;
-  addListener(listener: ScanListener): void;
-  onStream(callback: (stream: MediaStream | null) => void): void;
-  cleanup(): Promise<void>;
-}
-```
-
-2. **Platform-Specific Implementation**
-```typescript
-// WebInlineQRScanner.ts
-export class WebInlineQRScanner implements QRScannerService {
-  private scanListener: ScanListener | null = null;
-  private isScanning = false;
-  private stream: MediaStream | null = null;
-  private events = new EventEmitter();
-
-  // Implementation of interface methods
-}
-```
-
-### 4.2 Deep Linking
-
-1. **URL Structure**
-```typescript
-// Format: timesafari://<route>[/<param>][?queryParam1=value1]
-interface DeepLinkParams {
-  route: string;
-  params?: Record<string, string>;
-  query?: Record<string, string>;
-}
-```
-
-2. **Platform Handlers**
-```typescript
-// Capacitor
-App.addListener("appUrlOpen", handleDeepLink);
-
-// Web
-router.beforeEach((to, from, next) => {
-  handleWebDeepLink(to.query);
-});
-```
-
-## 5. Build Process
-
-### 5.1 Environment Configuration
-```typescript
-// vite.config.common.mts
-export function createBuildConfig(mode: string) {
-  return {
-    define: {
-      'process.env.VITE_PLATFORM': JSON.stringify(mode),
-      // PWA is automatically enabled for web platforms via build configuration
-      __IS_MOBILE__: JSON.stringify(isCapacitor),
-      __USE_QR_READER__: JSON.stringify(!isCapacitor)
-    }
-  };
-}
-```
-
-### 5.2 Platform-Specific Builds
-
-```bash
-# Build commands from package.json
-"build:web": "vite build --config vite.config.web.mts",
-"build:capacitor": "vite build --config vite.config.capacitor.mts",
-"build:electron": "vite build --config vite.config.electron.mts"
-```
-
-## 6. Testing Strategy
-
-### 6.1 Test Configuration
-```typescript
-// playwright.config-local.ts
-const config: PlaywrightTestConfig = {
-  projects: [
-    {
-      name: 'web',
-      use: { browserName: 'chromium' }
-    },
-    {
-      name: 'mobile',
-      use: { ...devices['Pixel 5'] }
-    }
-  ]
-};
-```
-
-### 6.2 Platform-Specific Tests
-```typescript
-test('QR scanning works on mobile', async ({ page }) => {
-  test.skip(!process.env.MOBILE_TEST, 'Mobile-only test');
-  // Test implementation
-});
-```
-
-## 7. Error Handling
-
-### 7.1 Global Error Handler
-```typescript
-function setupGlobalErrorHandler(app: VueApp) {
-  app.config.errorHandler = (err, instance, info) => {
-    logger.error("[App Error]", {
-      error: err,
-      info,
-      component: instance?.$options.name
-    });
-  };
-}
-```
-
-### 7.2 Platform-Specific Error Handling
-```typescript
-// API error handling for Capacitor
-if (process.env.VITE_PLATFORM === 'capacitor') {
-  logger.error(`[Capacitor API Error] ${endpoint}:`, {
-    message: error.message,
-    status: error.response?.status
-  });
-}
-```
-
-## 8. Best Practices
-
-### 8.1 Code Organization
-- Use platform-specific directories for unique implementations
-- Share common code through service interfaces
-- Implement feature detection before using platform capabilities
-- Keep platform-specific code isolated in dedicated directories
-- Use TypeScript interfaces for cross-platform compatibility
-
-### 8.2 Platform Detection
-```typescript
-const platformService = PlatformServiceFactory.getInstance();
-const capabilities = platformService.getCapabilities();
-
-if (capabilities.hasCamera) {
-  // Implement camera features
-}
-```
-
-### 8.3 Feature Implementation
-1. Define platform-agnostic interface
-2. Create platform-specific implementations
-3. Use factory pattern for instantiation
-4. Implement graceful fallbacks
-5. Add comprehensive error handling
-6. Use dependency injection for better testability
-
-## 9. Dependency Management
-
-### 9.1 Platform-Specific Dependencies
-```json
-{
-  "dependencies": {
-    "@capacitor/core": "^6.2.0",
-    "electron": "^33.2.1",
-    "vue": "^3.4.0"
-  }
-}
-```
-
-### 9.2 Conditional Loading
-```typescript
-if (process.env.VITE_PLATFORM === 'capacitor') {
-  await import('@capacitor/core');
-}
-```
-
-## 10. Security Considerations
-
-### 10.1 Permission Handling
-```typescript
-async checkPermissions(): Promise<boolean> {
-  if (platformService.isCapacitor()) {
-    return await checkNativePermissions();
-  }
-  return await checkWebPermissions();
-}
-```
-
-### 10.2 Data Storage
-- Use secure storage mechanisms for sensitive data
-- Implement proper encryption for stored data
-- Follow platform-specific security guidelines
-- Regular security audits and updates
-
-This document should be updated as new features are added or platform-specific implementations change. Regular reviews ensure it remains current with the codebase.

.cursor/rules/architecture/README.md

@@ -0,0 +1,75 @@
+# Architecture Rules Directory
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-20
+**Status**: 🎯 **ACTIVE** - Architecture protection guidelines
+
+## Overview
+
+This directory contains MDC (Model Directive Configuration) rules that protect
+critical architectural components of the TimeSafari project. These rules ensure
+that changes to system architecture follow proper review, testing, and
+documentation procedures.
+
+## Available Rules
+
+### Build Architecture Guard (`build_architecture_guard.mdc`)
+
+Protects the multi-platform build system including:
+
+- Vite configuration files
+- Build scripts and automation
+- Platform-specific configurations (iOS, Android, Electron, Web)
+- Docker and deployment infrastructure
+- CI/CD pipeline components
+
+**When to use**: Any time you're modifying build scripts, configuration files,
+or deployment processes.
+
+**Authorization levels**:
+
+- **Level 1**: Minor changes (review required)
+- **Level 2**: Moderate changes (testing required)
+- **Level 3**: Major changes (ADR required)
+
+## Usage Guidelines
+
+### For Developers
+
+1. **Check the rule**: Before making architectural changes, review the relevant
+   rule
+2. **Follow the process**: Use the appropriate authorization level
+3. **Complete validation**: Run through the required checklist
+4. **Update documentation**: Keep BUILDING.md and related docs current
+
+### For Reviewers
+
+1. **Verify authorization**: Ensure changes match the required level
+2. **Check testing**: Confirm appropriate testing has been completed
+3. **Validate documentation**: Ensure BUILDING.md reflects changes
+4. **Assess risk**: Consider impact on other platforms and systems
+
+## Integration with Other Rules
+
+- **Version Control**: Works with `workflow/version_control.mdc`
+- **Research & Diagnostic**: Supports `research_diagnostic.mdc` for
+  investigations
+- **Software Development**: Aligns with development best practices
+- **Markdown Automation**: Integrates with `docs/markdown-automation.mdc` for
+  consistent documentation formatting
+
+## Emergency Procedures
+
+If architectural changes cause system failures:
+
+1. **Immediate rollback** to last known working state
+2. **Document the failure** with full error details
+3. **Investigate root cause** using diagnostic workflows
+4. **Update procedures** to prevent future failures
+
+---
+
+**Status**: Active architecture protection
+**Priority**: Critical
+**Maintainer**: Development team
+**Next Review**: 2025-09-20

.cursor/rules/architecture/build_architecture_guard.mdc

@@ -0,0 +1,186 @@
+
+# Build Architecture Guard Directive
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-22
+**Status**: 🎯 **ACTIVE** - Build system protection guidelines
+
+## Purpose
+
+Protect the TimeSafari building architecture from unauthorized changes that
+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.
+
+## 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
+
+- **Resource Generation**: `capacitor-assets` integration and verification
+
+- **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
+
+### 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
+
+### 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
+
+### 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
+
+- **Asset regeneration logic**: Automatic fallback for missing Android resources
+
+**Process**: Code review + platform testing + documentation update
+
+### 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
+
+## Prohibited Actions
+
+### ❌ 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
+
+---
+
+**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/camera-implementation.mdc

@@ -1,222 +0,0 @@
----
-description: 
-globs: 
-alwaysApply: false
----
-# Camera Implementation Documentation
-
-## Overview
-
-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
-
-### QRScannerDialog.vue
-
-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
-
-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
-
-### QRScanner Services
-
-#### WebDialogQRScanner
-
-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
-
-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
-
-#### WebPlatformService
-
-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
-
-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
-- Planned to use Electron's media APIs
-
-## 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
-- Various network conditions 

.cursor/rules/core/base_context.mdc

@@ -0,0 +1,217 @@
+---
+alwaysApply: false
+---
+```json
+
+{
+  "coaching_level": "standard",
+  "socratic_max_questions": 7,
+  "verbosity": "normal",
+  "timebox_minutes": null,
+  "format_enforcement": "strict"
+}
+
+```
+
+# Base Context — Human Competence First
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Core interaction guidelines
+
+## Purpose
+
+All interactions must *increase the human's competence over time* while
+completing the task efficiently. The model may handle menial work and memory
+extension, but must also promote learning, autonomy, and healthy work habits.
+The model should also **encourage human interaction and collaboration** rather
+than replacing it — outputs should be designed to **facilitate human discussion,
+decision-making, and creativity**, not to atomize tasks into isolated, purely
+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
+   repurposed.
+8. **Collaborative Bias**: Favor solutions that invite human review,
+   discussion, and iteration. When in doubt, ask "Who should this be shown
+   to?" or "Which human input would improve this?"
+
+## Toggle Definitions
+
+### coaching_level
+
+Determines the depth of learning support: `light` (short hooks),
+`standard` (balanced), `deep` (detailed).
+
+### socratic_max_questions
+
+The number of clarifying questions the model may ask before proceeding.
+If >0, questions should be targeted, minimal, and followed by reasonable
+assumptions if unanswered.
+
+### verbosity
+
+'terse' (just a sentence), `concise` (minimum commentary), `normal`
+(balanced explanation), or other project-defined levels.
+
+### timebox_minutes
+
+*integer or null* — When set to a positive integer (e.g., `5`), this acts
+as a **time budget** guiding the model to prioritize delivering the most
+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
+responses.
+
+### format_enforcement
+
+`strict` (reject outputs with format drift) or `relaxed` (minor deviations
+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.
+
+## 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)
+- [ ] At least one collaboration/discussion hook present
+- [ ] Output follows the **Output Contract** sections
+- [ ] Toggles respected; verbosity remains concise
+- [ ] Uncertainties/assumptions surfaced
+- [ ] No disallowed content
+- [ ] Uncertainties/assumptions surfaced.
+- [ ] No disallowed content.
+
+---
+
+**Status**: Active core guidelines
+**Priority**: Critical
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None (base ruleset)
+**Stakeholders**: All AI interactions

.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,105 +1,168 @@
 ---
-description: 
+globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts,
-globs: 
+  **/src/registerSQLWorker.js, **/
-alwaysApply: true
+services/AbsurdSqlDatabaseService.ts
+alwaysApply: false
 ---
+
 # Absurd SQL - Cursor Development Guide
 
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Database development guidelines
+
 ## Project Overview
-Absurd SQL is a backend implementation for sql.js that enables persistent SQLite databases in the browser by using IndexedDB as a block storage system. This guide provides rules and best practices for developing with this project in Cursor.
+
+Absurd SQL is a backend implementation for sql.js that enables persistent
+SQLite databases in the browser by using IndexedDB as a block storage system.
+This guide provides rules and best practices for developing with this project
+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
 
 ### 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
+
 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
+
 Recommended database settings:
+
 ```sql
+
 PRAGMA journal_mode=MEMORY;
 PRAGMA page_size=8192;  -- Optional, but recommended
+
 ```
 
 ### 6. Development Workflow
+
 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
 
 ### Worker Initialization
+
 ```javascript
+
 // Main thread
 import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread';
 
@@ -107,10 +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';
@@ -120,34 +186,88 @@ 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
 
 ### 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/) 
+
+- [SQL.js Documentation](https://github.com/sql-js/sql.js/)
+
+---
+
+**Status**: Active database development guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: Absurd SQL, SQL.js, IndexedDB
+**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

@@ -0,0 +1,62 @@
+# Legacy Dexie Database — Migration Guidelines
+
+> **Agent role**: Reference this file when working with legacy Dexie
+> 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

@@ -0,0 +1,105 @@
+---
+description: when doing anything with capacitor assets
+alwaysApply: false
+---
+
+# Asset Configuration Directive
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Asset management guidelines
+
+*Scope: Assets Only (icons, splashes, image pipelines) — not overall build
+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
+
+- 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
+
+```
+
+---
+
+**Status**: Active asset management directive
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: capacitor-assets toolchain
+**Stakeholders**: Development team, Build team
+
+  npx capacitor-assets generate  # produces platform assets; not committed
+
+# 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

@@ -0,0 +1,33 @@
+---
+globs: **/src/**/*
+alwaysApply: false
+---
+✅ 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

@@ -0,0 +1,178 @@
+# Investigation Report Example
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Investigation methodology example
+
+## Investigation — Registration Dialog Test Flakiness
+
+## Objective
+
+Identify root cause of flaky tests related to registration dialogs in contact
+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
+
+### Evidence-First Approach
+
+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
+
+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
+
+The investigation prevented:
+
+- Unnecessary database schema changes
+
+- Complex batch registration systems
+
+- Migration scripts for non-existent problems
+
+- Architectural changes based on assumptions
+
+---
+
+**Status**: Active investigation methodology
+**Priority**: High
+**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

@@ -0,0 +1,176 @@
+# Agent Contract — TimeSafari Logging (Unified, MANDATORY)
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Mandatory logging standards
+
+## Overview
+
+This document defines unified logging standards for the TimeSafari project,
+ensuring consistent, rest-parameter logging style using the project logger.
+No `console.*` methods are allowed in production code.
+
+## Scope and Goals
+
+**Scope**: Applies to all diffs and generated code in this workspace unless
+explicitly exempted below.
+
+**Goal**: One consistent, rest-parameter logging style using the project
+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)
+
+### DEBUG
+
+Use for method entry/exit, computed values, filters, loops, retries, and
+external call payload sizes.
+
+### INFO
+
+Use for user-visible lifecycle and completed operations.
+
+### WARN
+
+Use for recoverable issues, fallbacks, unexpected-but-handled conditions.
+
+### ERROR
+
+Use for unrecoverable failures, data integrity issues, and thrown
+exceptions.
+
+## Context Hygiene (Consistent, Minimal, Helpful)
+
+- **Component context**: Prefer scoped logger.
+
+- **Emojis**: Optional and minimal for visual scanning.
+
+- **Sensitive data**: Never log secrets (tokens, keys, passwords) or
+  payloads >10KB. Prefer IDs over objects; redact/hash when needed.
+
+## 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')`.
+
+## Exceptions (Tightly Scoped)
+
+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');
+
+```
+
+## 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).
+
+---
+
+**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

@@ -0,0 +1,262 @@
+---
+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,
+  "verbosity": "concise",
+  "timebox_minutes": null,
+  "format_enforcement": "strict"
+}
+
+```
+
+# Research & Diagnostic Workflow (R&D)
+
+## Purpose
+
+Provide a **repeatable, evidence-first** workflow to investigate features and
+defects **before coding**. Outputs are concise reports, hypotheses, and next
+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)
+
+---
+
+## Enhanced with Software Development Ruleset
+
+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
+
+---
+
+## Output Contract (strict)
+
+1) **Objective** — 1–2 lines
+2) **System Map (if helpful)** — short diagram or bullet flow (≤8 bullets)
+3) **Findings (Evidence-linked)** — bullets; each with file/function refs
+4) **Hypotheses & Failure Modes** — short list, each testable
+5) **Corrections** — explicit deltas from earlier assumptions (if any)
+6) **Diagnostics** — what to check next (logs, DB, env, repro steps)
+7) **Risks & Scope** — what could break; affected components
+8) **Decision/Next Steps** — what we'll do, who's involved, by when
+9) **References** — code paths, ADRs, docs
+10) **Competence & Collaboration Hooks** — brief, skimmable
+
+> Keep total length lean. Prefer links and bullets over prose.
+
+---
+
+## Quickstart Template
+
+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: `...`
+
+## 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>"
+
+```
+
+---
+
+## 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).
+
+- **Note uncertainty** explicitly.
+
+---
+
+## Code Path Tracing (Required for Software Investigations)
+
+Before proposing solutions, trace the actual execution path:
+
+- [ ] **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
+
+---
+
+## 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.
+
+---
+
+## Integration with Other Rulesets
+
+### With software_development.mdc
+
+- **Enhanced Evidence Validation**:
+
+  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
+
+---
+
+## 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.
+
+---
+
+## Optional Globs (examples)
+
+> Uncomment `globs` in the header if you want auto-attach behavior.
+
+- `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`
+
+## 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

@@ -0,0 +1,227 @@
+
+---
+
+alwaysApply: false
+---
+
+# Software Development Ruleset
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Core development guidelines
+
+## Purpose
+
+Specialized guidelines for software development tasks including code review,
+debugging, architecture decisions, and testing.
+
+## Core Principles
+
+### 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
+  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
+
+### 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
+
+### 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?"**
+
+## 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
+
+### 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
+
+---
+
+**See also**: `.cursor/rules/development/dependency_management.mdc` for
+  detailed dependency management practices.
+
+**Status**: Active development guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: base_context.mdc, research_diagnostic.mdc
+**Stakeholders**: Development team, Code review team
+
+## Model Implementation Checklist
+
+### 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

.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

@@ -0,0 +1,285 @@
+# Time Implementation — Technical Instructions
+
+> **Agent role**: Reference this file for detailed implementation instructions
+  when working with time handling in development.
+
+## 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
+
+**CRITICAL**: The LLM must actively query the system for current time rather
+than assuming or inventing times.
+
+### How to Check Current Time
+
+#### 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**
+
+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**
+
+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`
+
+## 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
+
+#### Database Storage
+
+```sql
+
+-- ✅ Good: Store in UTC
+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"
+}
+
+```
+
+#### Logging
+
+```python
+
+# ✅ Good: Log in UTC with timezone info
+
+logger.info(f"User action at {datetime.utcnow().isoformat()}Z (UTC)")
+
+```
+
+### Timezone Handling Best Practices
+
+#### 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
+
+#### 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
+
+---
+
+**See also**:
+
+- `.cursor/rules/development/time.mdc` for core principles
+
+- `.cursor/rules/development/time_examples.mdc` for practical examples
+
+**Status**: Active implementation guidelines
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**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

@@ -0,0 +1,212 @@
+---
+description: when dealing with types and Typesript
+alwaysApply: false
+---
+
+```json
+
+{
+  "coaching_level": "light",
+  "socratic_max_questions": 7,
+  "verbosity": "concise",
+  "timebox_minutes": null,
+  "format_enforcement": "strict"
+}
+
+```
+
+# TypeScript Type Safety Guidelines
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Type safety enforcement
+
+## Overview
+
+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]`.
+
+## Type Safety Enforcement
+
+### 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
+
+### 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
+
+### Implementation Guidelines
+
+- **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)
+
+### 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
+);
+
+```
+
+## Checklists
+
+**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‑ESLint — <https://typescript-eslint.io/rules/>
+
+- Vue 3 + TS — <https://vuejs.org/guide/typescript/>
+
+---
+
+**Status**: Active type safety guidelines
+**Priority**: High
+**Estimated Effort**: Ongoing reference
+**Dependencies**: TypeScript, ESLint, Vue 3
+**Stakeholders**: Development team
+
+- TS Handbook — <https://www.typescriptlang.org/docs/>
+
+- 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/development_guide.mdc

@@ -1,10 +0,0 @@
----
-description: rules used while developing
-globs: 
-alwaysApply: true
----
-✅ 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

.cursor/rules/docs/documentation.mdc

@@ -0,0 +1,37 @@
+---
+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.
+3. Prioritize **educational value**: the documents must clearly explain the
+   workings of the system.
+4. Avoid **shallow, generic, or filler explanations** often found in AI-generated
+   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_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/documentation.mdc

@@ -1,14 +0,0 @@
----
-alwaysApply: true
----
-# 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.
-3. Prioritize **educational value**: the documents must clearly explain the
-workings of the system.
-4. Avoid **shallow, generic, or filler explanations** often found in
-AI-generated documentation.
-5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding.
-6. Always check the local system date to determine current date.

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

@@ -0,0 +1,163 @@
+# Camera Implementation Documentation
+
+## Overview
+
+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
+
+### QRScannerDialog.vue
+
+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
+
+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
+
+### QRScanner Services
+
+#### WebDialogQRScanner
+
+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
+
+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
+
+#### WebPlatformService
+
+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
+
+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).
+
+---
+
+**See also**:
+
+- `.cursor/rules/features/camera_technical.mdc` for
+
+  detailed technical implementation
+
+- `.cursor/rules/features/camera_platforms.mdc` for platform-specific details
+
+**Status**: Active camera implementation overview
+**Priority**: Medium
+**Estimated Effort**: Ongoing reference
+**Dependencies**: None
+**Stakeholders**: Development team, Camera feature team
+
+- 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

@@ -0,0 +1,207 @@
+---
+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`)
+- Apply Playwright test investigation rules (see `.cursor/rules/playwright_test_investigation.mdc`)

.cursor/rules/legacy_dexie.mdc

@@ -1,6 +0,0 @@
----
-description: 
-globs: 
-alwaysApply: true
----
-All references in the codebase to Dexie apply only to migration from IndexedDb to Sqlite and will be deprecated in future versions.

.cursor/rules/markdown.mdc

@@ -1,332 +0,0 @@
----
-globs: *.md
-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.
-
-## 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
-  ```

.cursor/rules/meta_bug_diagnosis.mdc

@@ -0,0 +1,288 @@
+# Meta-Rule: Bug Diagnosis Workflow
+
+**Author**: Matthew Raymer
+**Date**: August 24, 2025
+**Status**: 🎯 **ACTIVE** - Core workflow for all bug investigation
+
+## Purpose
+
+This meta-rule defines the systematic approach for investigating and diagnosing
+bugs, defects, and unexpected behaviors in the TimeSafari application. It ensures
+consistent, thorough, and efficient problem-solving workflows.
+
+## Workflow Constraints
+
+**This meta-rule enforces DIAGNOSIS MODE for all bundled sub-rules:**
+
+```json
+{
+  "workflowMode": "diagnosis",
+  "constraints": {
+    "mode": "read_only",
+    "forbidden": ["modify", "create", "build", "commit"],
+    "required": "complete_investigation_before_fixing"
+  }
+}
+```
+
+**All bundled sub-rules automatically inherit these constraints.**
+
+## Workflow State Update
+
+**When this meta-rule is invoked, update the workflow state file:**
+
+```json
+{
+  "currentMode": "diagnosis",
+  "lastInvoked": "meta_bug_diagnosis.mdc",
+  "timestamp": "2025-01-27T15:30:00Z",
+  "constraints": {
+    "mode": "read_only",
+    "forbidden": ["modify", "create", "build", "commit"],
+    "allowed": ["read", "search", "analyze", "document"],
+    "required": "complete_investigation_before_fixing"
+  }
+}
+```
+
+**State File Location**: `.cursor/rules/.workflow_state.json`
+
+**This enables the core always-on rule to enforce diagnosis mode constraints.**
+
+## When to Use
+
+**ALWAYS** - Apply this workflow to every bug investigation, regardless of
+severity or complexity. This ensures systematic problem-solving and prevents
+common investigation pitfalls.
+
+## Bundled Rules
+
+### **Investigation Foundation**
+
+- **`development/research_diagnostic.mdc`** - Research and investigation methodologies
+- **`development/logging_standards.mdc`** - Logging and debugging best practices
+- **`development/type_safety_guide.mdc`** - Type safety and error prevention
+
+### **Development Workflow**
+
+- **`workflow/version_control.mdc`** - Version control during investigation
+- **`development/software_development.mdc`** - Development best practices
+
+## Critical Development Constraints
+
+### **🚫 NEVER Use Build Commands During Diagnosis**
+
+**Critical Rule**: Never use `npm run build:web` or similar build commands during bug diagnosis
+
+- **Reason**: These commands block the chat and prevent effective troubleshooting
+- **Impact**: Blocks user interaction, prevents real-time problem solving
+- **Alternative**: Use safe, fast commands for investigation
+- **When to use build**: Only after diagnosis is complete and fixes are ready for testing
+
+### **Safe Diagnosis Commands**
+
+✅ **Safe to use during diagnosis:**
+- `npm run lint-fix` - Syntax and style checking
+- `npm run type-check` - TypeScript validation (if available)
+- `git status` - Version control status
+- `ls` / `dir` - File listing
+- `cat` / `read_file` - File content inspection
+- `grep_search` - Text pattern searching
+
+❌ **Never use during diagnosis:**
+- `npm run build:web` - Blocks chat
+- `npm run build:electron` - Blocks chat  
+- `npm run build:capacitor` - Blocks chat
+- Any long-running build processes
+
+## Investigation Workflow
+
+### **Phase 1: Problem Definition**
+
+1. **Gather Evidence**
+   - Error messages and stack traces
+   - User-reported symptoms
+   - System logs and timestamps
+   - Reproduction steps
+
+2. **Context Analysis**
+   - When did the problem start?
+   - What changed recently?
+   - Which platform/environment?
+   - User actions leading to the issue
+
+### **Phase 2: Systematic Investigation**
+
+1. **Code Inspection**
+   - Relevant file examination
+   - Import and dependency analysis
+   - Syntax and type checking
+   - Logic flow analysis
+
+2. **Environment Analysis**
+   - Platform-specific considerations
+   - Configuration and settings
+   - Database and storage state
+   - Network and API connectivity
+
+### **Phase 3: Root Cause Identification**
+
+1. **Pattern Recognition**
+   - Similar issues in codebase
+   - Common failure modes
+   - Platform-specific behaviors
+   - Recent changes impact
+
+2. **Hypothesis Testing**
+   - Targeted code changes
+   - Configuration modifications
+   - Environment adjustments
+   - Systematic elimination
+
+## Investigation Techniques
+
+### **Safe Code Analysis**
+
+- **File Reading**: Use `read_file` tool for targeted inspection
+- **Pattern Searching**: Use `grep_search` for code patterns
+- **Semantic Search**: Use `codebase_search` for related functionality
+- **Import Tracing**: Follow dependency chains systematically
+
+### **Error Analysis**
+
+- **Stack Trace Analysis**: Identify error origin and propagation
+- **Log Correlation**: Match errors with system events
+- **Timeline Reconstruction**: Build sequence of events
+- **Context Preservation**: Maintain investigation state
+
+### **Platform Considerations**
+
+- **Web Platform**: Browser-specific behaviors and limitations
+- **Electron Platform**: Desktop app considerations
+- **Capacitor Platform**: Mobile app behaviors
+- **Cross-Platform**: Shared vs. platform-specific code
+
+## Evidence Collection Standards
+
+### **Timestamps**
+
+- **UTC Format**: All timestamps in UTC for consistency
+- **Precision**: Include milliseconds for precise correlation
+- **Context**: Include relevant system state information
+- **Correlation**: Link events across different components
+
+### **Error Context**
+
+- **Full Error Objects**: Capture complete error information
+- **Stack Traces**: Preserve call stack for analysis
+- **User Actions**: Document steps leading to error
+- **System State**: Capture relevant configuration and state
+
+### **Reproduction Steps**
+
+- **Clear Sequence**: Step-by-step reproduction instructions
+- **Environment Details**: Platform, version, configuration
+- **Data Requirements**: Required data or state
+- **Expected vs. Actual**: Clear behavior comparison
+
+## Investigation Documentation
+
+### **Problem Summary**
+
+- **Issue Description**: Clear, concise problem statement
+- **Impact Assessment**: Severity and user impact
+- **Scope Definition**: Affected components and users
+- **Priority Level**: Based on impact and frequency
+
+### **Investigation Log**
+
+- **Timeline**: Chronological investigation steps
+- **Evidence**: Collected information and findings
+- **Hypotheses**: Tested theories and results
+- **Conclusions**: Root cause identification
+
+### **Solution Requirements**
+
+- **Fix Description**: Required changes and approach
+- **Testing Strategy**: Validation and verification steps
+- **Rollback Plan**: Reversion strategy if needed
+- **Prevention Measures**: Future issue prevention
+
+## Quality Standards
+
+### **Investigation Completeness**
+
+- **Evidence Sufficiency**: Adequate information for root cause
+- **Alternative Theories**: Considered and eliminated
+- **Platform Coverage**: All relevant platforms investigated
+- **Edge Cases**: Unusual scenarios considered
+
+### **Documentation Quality**
+
+- **Clear Communication**: Understandable to all stakeholders
+- **Technical Accuracy**: Precise technical details
+- **Actionable Insights**: Clear next steps and recommendations
+- **Knowledge Transfer**: Lessons learned for future reference
+
+## Common Pitfalls
+
+### **Investigation Mistakes**
+
+- **Jumping to Solutions**: Implementing fixes before understanding
+- **Insufficient Evidence**: Making assumptions without data
+- **Platform Blindness**: Ignoring platform-specific behaviors
+- **Scope Creep**: Expanding investigation beyond original problem
+
+### **Communication Issues**
+
+- **Technical Jargon**: Using unclear terminology
+- **Missing Context**: Insufficient background information
+- **Unclear Recommendations**: Vague or ambiguous next steps
+- **Poor Documentation**: Incomplete or unclear investigation records
+
+## Success Criteria
+
+- [ ] **Problem clearly defined** with sufficient evidence
+- [ ] **Root cause identified** through systematic investigation
+- [ ] **Solution approach determined** with clear requirements
+- [ ] **Documentation complete** for knowledge transfer
+- [ ] **No chat-blocking commands** used during investigation
+- [ ] **Platform considerations** properly addressed
+- [ ] **Timeline and context** properly documented
+
+## Integration with Other Meta-Rules
+
+### **Bug Fixing**
+
+- **Investigation Results**: Provide foundation for fix implementation
+- **Solution Requirements**: Define what needs to be built
+- **Testing Strategy**: Inform validation approach
+- **Documentation**: Support implementation guidance
+
+### **Feature Planning**
+
+- **Root Cause Analysis**: Identify systemic issues
+- **Prevention Measures**: Plan future issue avoidance
+- **Architecture Improvements**: Identify structural enhancements
+- **Process Refinements**: Improve development workflows
+
+### **Research and Documentation**
+
+- **Knowledge Base**: Contribute to troubleshooting guides
+- **Pattern Recognition**: Identify common failure modes
+- **Best Practices**: Develop investigation methodologies
+- **Team Training**: Improve investigation capabilities
+
+---
+
+**See also**:
+
+- `.cursor/rules/meta_bug_fixing.mdc` for implementing fixes
+- `.cursor/rules/meta_feature_planning.mdc` for planning improvements
+- `.cursor/rules/meta_documentation.mdc` for documentation standards
+
+**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,214 @@
+# 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.
+
+## Workflow Constraints
+
+**This meta-rule enforces FIXING MODE for all bundled sub-rules:**
+
+```json
+{
+  "workflowMode": "fixing",
+  "constraints": {
+    "mode": "implementation",
+    "allowed": ["modify", "create", "build", "test", "commit"],
+    "required": "diagnosis_complete_before_fixing"
+  }
+}
+```
+
+**All bundled sub-rules automatically inherit these constraints.**
+
+## Workflow State Update
+
+**When this meta-rule is invoked, update the workflow state file:**
+
+```json
+{
+  "currentMode": "fixing",
+  "lastInvoked": "meta_bug_fixing.mdc",
+  "timestamp": "2025-01-27T15:30:00Z",
+  "constraints": {
+    "mode": "implementation",
+    "allowed": ["modify", "create", "build", "test", "commit"],
+    "forbidden": [],
+    "required": "diagnosis_complete_before_fixing"
+  }
+}
+```
+
+**State File Location**: `.cursor/rules/.workflow_state.json`
+
+**This enables the core always-on rule to enforce fixing mode constraints.**
+
+## 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_change_evaluation.mdc

@@ -0,0 +1,383 @@
+# Meta-Rule: Change Evaluation and Breaking Change Detection
+
+**Author**: Matthew Raymer  
+**Date**: 2025-08-25  
+**Status**: 🎯 **ACTIVE** - Manually activated change evaluation rule
+
+## Purpose
+
+This meta-rule provides a systematic approach to evaluate changes between
+branches and detect potential breaking changes. It's designed to catch
+problematic model behavior by analyzing the nature, scope, and impact of
+code changes before they cause issues.
+
+## When to Use
+
+**Manual Activation Only** - This rule should be invoked when:
+
+- Reviewing changes before merging branches
+- Investigating unexpected behavior after updates
+- Validating that model-generated changes are safe
+- Analyzing the impact of recent commits
+- Debugging issues that may be caused by recent changes
+
+## Workflow State Enforcement
+
+**This meta-rule enforces current workflow mode constraints:**
+
+### **Current Workflow State**
+
+```json
+{
+  "workflowState": {
+    "currentMode": "diagnosis|fixing|planning|research|documentation",
+    "constraints": {
+      "mode": "read_only|implementation|design_only|investigation|writing_only",
+      "allowed": ["array", "of", "allowed", "actions"],
+      "forbidden": ["array", "of", "forbidden", "actions"]
+    }
+  }
+}
+```
+
+### **Mode-Specific Enforcement**
+
+**Diagnosis Mode (read_only):**
+
+- ❌ **Forbidden**: File modification, code creation, build commands, git
+  commits
+- ✅ **Allowed**: File reading, code analysis, investigation, documentation
+- **Response**: Focus on analysis and documentation, not implementation
+
+**Fixing Mode (implementation):**
+
+- ✅ **Allowed**: File modification, code creation, build commands, testing,
+  git commits
+- ❌ **Forbidden**: None (full implementation mode)
+- **Response**: Proceed with implementation and testing
+
+**Planning Mode (design_only):**
+
+- ❌ **Forbidden**: Implementation, coding, building, deployment
+- ✅ **Allowed**: Analysis, design, estimation, documentation, architecture
+- **Response**: Focus on planning and design, not implementation
+
+**Research Mode (investigation):**
+
+- ❌ **Forbidden**: File modification, implementation, deployment
+- ✅ **Allowed**: Investigation, analysis, research, documentation
+- **Response**: Focus on investigation and analysis
+
+**Documentation Mode (writing_only):**
+
+- ❌ **Forbidden**: Implementation, coding, building, deployment
+- ✅ **Allowed**: Writing, editing, formatting, structuring, reviewing
+- **Response**: Focus on documentation creation and improvement
+
+## Change Evaluation Process
+
+### **Phase 1: Change Discovery and Analysis**
+
+1. **Branch Comparison Analysis**
+
+   - Compare working branch with master/main branch
+   - Identify all changed files and their modification types
+   - Categorize changes by scope and impact
+
+2. **Change Pattern Recognition**
+
+   - Identify common change patterns (refactoring, feature addition, bug
+     fixes)
+   - Detect unusual or suspicious change patterns
+   - Flag changes that deviate from established patterns
+
+3. **Dependency Impact Assessment**
+
+   - Analyze changes to imports, exports, and interfaces
+   - Identify potential breaking changes to public APIs
+   - Assess impact on dependent components and services
+
+### **Phase 2: Breaking Change Detection**
+
+1. **API Contract Analysis**
+
+   - Check for changes to function signatures, method names, class
+     interfaces
+   - Identify removed or renamed public methods/properties
+   - Detect changes to configuration options and constants
+
+2. **Data Structure Changes**
+
+   - Analyze database schema modifications
+   - Check for changes to data models and interfaces
+   - Identify modifications to serialization/deserialization logic
+
+3. **Behavioral Changes**
+
+   - Detect changes to business logic and algorithms
+   - Identify modifications to error handling and validation
+   - Check for changes to user experience and workflows
+
+### **Phase 3: Risk Assessment and Recommendations**
+
+1. **Risk Level Classification**
+
+   - **LOW**: Cosmetic changes, documentation updates, minor refactoring
+   - **MEDIUM**: Internal API changes, configuration modifications,
+     performance improvements
+   - **HIGH**: Public API changes, breaking interface modifications, major
+     architectural changes
+   - **CRITICAL**: Database schema changes, authentication modifications,
+     security-related changes
+
+2. **Impact Analysis**
+
+   - Identify affected user groups and use cases
+   - Assess potential for data loss or corruption
+   - Evaluate impact on system performance and reliability
+
+3. **Mitigation Strategies**
+
+   - Recommend testing approaches for affected areas
+   - Suggest rollback strategies if needed
+   - Identify areas requiring additional validation
+
+## Implementation Guidelines
+
+### **Change Analysis Tools**
+
+1. **Git Diff Analysis**
+
+   ```bash
+   # Compare working branch with master
+   git diff master..HEAD --name-only
+   git diff master..HEAD --stat
+   git log master..HEAD --oneline
+   ```
+
+2. **File Change Categorization**
+
+   - **Core Files**: Application entry points, main services, critical
+     utilities
+   - **Interface Files**: Public APIs, component interfaces, data models
+   - **Configuration Files**: Environment settings, build configurations,
+     deployment scripts
+   - **Test Files**: Unit tests, integration tests, test utilities
+
+3. **Change Impact Mapping**
+
+   - Map changed files to affected functionality
+   - Identify cross-dependencies and ripple effects
+   - Document potential side effects and unintended consequences
+
+### **Breaking Change Detection Patterns**
+
+1. **Function Signature Changes**
+
+   ```typescript
+   // BEFORE
+   function processData(data: string, options?: Options): Result
+   
+   // AFTER - BREAKING CHANGE
+   function processData(data: string, options: Required<Options>): Result
+   ```
+
+2. **Interface Modifications**
+
+   ```typescript
+   // BEFORE
+   interface UserProfile {
+     name: string;
+     email: string;
+   }
+   
+   // AFTER - BREAKING CHANGE
+   interface UserProfile {
+     name: string;
+     email: string;
+     phone: string; // Required new field
+   }
+   ```
+
+3. **Configuration Changes**
+
+   ```typescript
+   // BEFORE
+   const config = {
+     apiUrl: 'https://api.example.com',
+     timeout: 5000
+   };
+   
+   // AFTER - BREAKING CHANGE
+   const config = {
+     apiUrl: 'https://api.example.com',
+     timeout: 5000,
+     retries: 3 // New required configuration
+   };
+   ```
+
+## Output Format
+
+### **Change Evaluation Report**
+
+```markdown
+# Change Evaluation Report
+
+## Executive Summary
+
+- **Risk Level**: [LOW|MEDIUM|HIGH|CRITICAL]
+- **Overall Assessment**: [SAFE|CAUTION|DANGEROUS|CRITICAL]
+- **Recommendation**: [PROCEED|REVIEW|HALT|IMMEDIATE_ROLLBACK]
+
+## Change Analysis
+
+### Files Modified
+
+- **Total Changes**: [X] files
+- **Core Files**: [X] files
+- **Interface Files**: [X] files
+- **Configuration Files**: [X] files
+- **Test Files**: [X] files
+
+### Change Categories
+
+- **Refactoring**: [X] changes
+- **Feature Addition**: [X] changes
+- **Bug Fixes**: [X] changes
+- **Configuration**: [X] changes
+- **Documentation**: [X] changes
+
+## Breaking Change Detection
+
+### API Contract Changes
+
+- **Function Signatures**: [X] modified
+- **Interface Definitions**: [X] modified
+- **Public Methods**: [X] added/removed/modified
+
+### Data Structure Changes
+
+- **Database Schema**: [X] modifications
+- **Data Models**: [X] changes
+- **Serialization**: [X] changes
+
+### Behavioral Changes
+
+- **Business Logic**: [X] modifications
+- **Error Handling**: [X] changes
+- **User Experience**: [X] changes
+
+## Risk Assessment
+
+### Impact Analysis
+
+- **User Groups Affected**: [Description]
+- **Use Cases Impacted**: [Description]
+- **Performance Impact**: [Description]
+- **Reliability Impact**: [Description]
+
+### Dependencies
+
+- **Internal Dependencies**: [List]
+- **External Dependencies**: [List]
+- **Configuration Dependencies**: [List]
+
+## Recommendations
+
+### Testing Requirements
+
+- [ ] Unit tests for modified components
+- [ ] Integration tests for affected workflows
+- [ ] Performance tests for changed algorithms
+- [ ] User acceptance tests for UI changes
+
+### Validation Steps
+
+- [ ] Code review by domain experts
+- [ ] API compatibility testing
+- [ ] Database migration testing
+- [ ] End-to-end workflow testing
+
+### Rollback Strategy
+
+- **Rollback Complexity**: [LOW|MEDIUM|HIGH]
+- **Rollback Time**: [Estimated time]
+- **Data Preservation**: [Strategy description]
+
+## Conclusion
+
+[Summary of findings and final recommendation]
+```
+
+## Usage Examples
+
+### **Example 1: Safe Refactoring**
+
+```bash
+@meta_change_evaluation.mdc analyze changes between feature-branch and master
+```
+
+### **Example 2: Breaking Change Investigation**
+
+```bash
+@meta_change_evaluation.mdc evaluate potential breaking changes in recent commits
+```
+
+### **Example 3: Pre-Merge Validation**
+
+```bash
+@meta_change_evaluation.mdc validate changes before merging feature-branch to master
+```
+
+## Success Criteria
+
+- [ ] **Change Discovery**: All modified files are identified and categorized
+- [ ] **Pattern Recognition**: Unusual change patterns are detected and flagged
+- [ ] **Breaking Change Detection**: All potential breaking changes are identified
+- [ ] **Risk Assessment**: Accurate risk levels are assigned with justification
+- [ ] **Recommendations**: Actionable recommendations are provided
+- [ ] **Documentation**: Complete change evaluation report is generated
+
+## Common Pitfalls
+
+- **Missing Dependencies**: Failing to identify all affected components
+- **Underestimating Impact**: Not considering ripple effects of changes
+- **Incomplete Testing**: Missing critical test scenarios for changes
+- **Configuration Blindness**: Overlooking configuration file changes
+- **Interface Assumptions**: Assuming internal changes won't affect external
+  users
+
+## Integration with Other Meta-Rules
+
+### **With Bug Diagnosis**
+
+- Use change evaluation to identify recent changes that may have caused
+  bugs
+- Correlate change patterns with reported issues
+
+### **With Feature Planning**
+
+- Evaluate the impact of planned changes before implementation
+- Identify potential breaking changes early in the planning process
+
+### **With Bug Fixing**
+
+- Validate that fixes don't introduce new breaking changes
+- Ensure fixes maintain backward compatibility
+
+---
+
+**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 change evaluation meta-rule
+**Priority**: High (applies to all change evaluation tasks)
+**Estimated Effort**: Ongoing reference
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: Development team, Quality Assurance team, Release
+Management team

.cursor/rules/meta_core_always_on.mdc

@@ -0,0 +1,311 @@
+---
+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.
+
+## Workflow Constraints
+
+**This meta-rule enforces ALWAYS-ON MODE for all bundled sub-rules:**
+
+```json
+{
+  "workflowMode": "always_on",
+  "constraints": {
+    "mode": "foundation",
+    "alwaysApplied": true,
+    "required": "applied_to_every_prompt"
+  }
+}
+```
+
+**All bundled sub-rules automatically inherit these constraints.**
+
+## Workflow State Enforcement
+
+**This meta-rule enforces current workflow mode constraints for all interactions:**
+
+### **Current Workflow State**
+```json
+{
+  "workflowState": {
+    "currentMode": "diagnosis|fixing|planning|research|documentation",
+    "constraints": {
+      "mode": "read_only|implementation|design_only|investigation|writing_only",
+      "allowed": ["array", "of", "allowed", "actions"],
+      "forbidden": ["array", "of", "forbidden", "actions"]
+    }
+  }
+}
+```
+
+### **Constraint Enforcement Rules**
+
+**Before responding to any user request, enforce current mode constraints:**
+
+1. **Read current workflow state** from `.cursor/rules/.workflow_state.json`
+2. **Identify current mode** and its constraints
+3. **Validate user request** against current mode constraints
+4. **Enforce constraints** before generating response
+5. **Guide model behavior** based on current mode
+
+### **Mode-Specific Enforcement**
+
+**Diagnosis Mode (read_only):**
+- ❌ **Forbidden**: File modification, code creation, build commands, git commits
+- ✅ **Allowed**: File reading, code analysis, investigation, documentation
+- **Response**: Guide user toward investigation and analysis, not implementation
+
+**Fixing Mode (implementation):**
+- ✅ **Allowed**: File modification, code creation, build commands, testing, git commits
+- ❌ **Forbidden**: None (full implementation mode)
+- **Response**: Proceed with implementation and testing
+
+**Planning Mode (design_only):**
+- ❌ **Forbidden**: Implementation, coding, building, deployment
+- ✅ **Allowed**: Analysis, design, estimation, documentation, architecture
+- **Response**: Focus on planning and design, not implementation
+
+**Research Mode (investigation):**
+- ❌ **Forbidden**: File modification, implementation, deployment
+- ✅ **Allowed**: Investigation, analysis, research, documentation
+- **Response**: Focus on investigation and analysis
+
+**Documentation Mode (writing_only):**
+- ❌ **Forbidden**: Implementation, coding, building, deployment
+- ✅ **Allowed**: Writing, editing, formatting, structuring, reviewing
+- **Response**: Focus on documentation creation and improvement
+
+### **Constraint Violation Response**
+
+**If user request violates current mode constraints:**
+
+```
+❌ **WORKFLOW CONSTRAINT VIOLATION**
+
+**Current Mode**: [MODE_NAME]
+**Requested Action**: [ACTION] 
+**Constraint Violation**: [DESCRIPTION]
+
+**What You Can Do Instead**:
+- [LIST OF ALLOWED ALTERNATIVES]
+
+**To Enable This Action**: Invoke @meta_[appropriate_mode].mdc
+```
+
+### **Mode Transition Guidance**
+
+**When user needs to change modes, provide clear guidance:**
+
+```
+🔄 **MODE TRANSITION REQUIRED**
+
+**Current Mode**: [CURRENT_MODE]
+**Required Mode**: [REQUIRED_MODE]
+**Action**: Invoke @meta_[required_mode].mdc
+
+**This will enable**: [DESCRIPTION OF NEW CAPABILITIES]
+```
+
+## 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
+- [ ] **Workflow State**: Read current mode constraints from state file
+- [ ] **Constraint Validation**: Validate user request against current mode
+
+### 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
+- [ ] **Mode Enforcement**: Apply current mode constraints to response
+- [ ] **Constraint Violations**: Block forbidden actions and guide alternatives
+
+### 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
+- [ ] **Mode Compliance**: Verify response stayed within current mode constraints
+- [ ] **Transition Guidance**: Provide clear guidance for mode changes if needed
+
+---
+
+**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
+
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: All AI interactions, Development team
+
+**Dependencies**: All bundled sub-rules
+**Stakeholders**: All AI interactions, Development team

.cursor/rules/meta_documentation.mdc

@@ -0,0 +1,275 @@
+# 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.
+
+## Workflow Constraints
+
+**This meta-rule enforces DOCUMENTATION MODE for all bundled sub-rules:**
+
+```json
+{
+  "workflowMode": "documentation",
+  "constraints": {
+    "mode": "writing_only",
+    "allowed": ["write", "edit", "format", "structure", "review"],
+    "forbidden": ["implement", "code", "build", "deploy"]
+  }
+}
+```
+
+**All bundled sub-rules automatically inherit these constraints.**
+
+## Workflow State Update
+
+**When this meta-rule is invoked, update the workflow state file:**
+
+```json
+{
+  "currentMode": "documentation",
+  "lastInvoked": "meta_documentation.mdc",
+  "timestamp": "2025-01-27T15:30:00Z",
+  "constraints": {
+    "mode": "writing_only",
+    "allowed": ["write", "edit", "format", "structure", "review"],
+    "forbidden": ["implement", "code", "build", "deploy"]
+  }
+}
+```
+
+**State File Location**: `.cursor/rules/.workflow_state.json`
+
+**This enables the core always-on rule to enforce documentation mode constraints.**
+
+## 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,226 @@
+# 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.
+
+## Workflow Constraints
+
+**This meta-rule enforces IMPLEMENTATION MODE for all bundled sub-rules:**
+
+```json
+{
+  "workflowMode": "implementation",
+  "constraints": {
+    "mode": "development",
+    "allowed": ["code", "build", "test", "refactor", "deploy"],
+    "required": "planning_complete_before_implementation"
+  }
+}
+```
+
+**All bundled sub-rules automatically inherit these constraints.**
+
+## Workflow State Update
+
+**When this meta-rule is invoked, update the workflow state file:**
+
+```json
+{
+  "currentMode": "implementation",
+  "lastInvoked": "meta_feature_implementation.mdc",
+  "timestamp": "2025-01-27T15:30:00Z",
+  "constraints": {
+    "mode": "development",
+    "allowed": ["code", "build", "test", "refactor", "deploy"],
+    "forbidden": [],
+    "required": "planning_complete_before_implementation"
+  }
+}
+```
+
+**State File Location**: `.cursor/rules/.workflow_state.json`
+
+**This enables the core always-on rule to enforce implementation mode constraints.**
+
+## 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,203 @@
+# 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.
+
+## Workflow Constraints
+
+**This meta-rule enforces PLANNING MODE for all bundled sub-rules:**
+
+```json
+{
+  "workflowMode": "planning",
+  "constraints": {
+    "mode": "design_only",
+    "allowed": ["analyze", "plan", "design", "estimate", "document"],
+    "forbidden": ["implement", "code", "build", "test", "deploy"]
+  }
+}
+```
+
+**All bundled sub-rules automatically inherit these constraints.**
+
+## Workflow State Update
+
+**When this meta-rule is invoked, update the workflow state file:**
+
+```json
+{
+  "currentMode": "planning",
+  "lastInvoked": "meta_feature_planning.mdc",
+  "timestamp": "2025-01-27T15:30:00Z",
+  "constraints": {
+    "mode": "design_only",
+    "allowed": ["analyze", "plan", "design", "estimate", "document"],
+    "forbidden": ["implement", "code", "build", "test", "deploy"]
+  }
+}
+```
+
+**State File Location**: `.cursor/rules/.workflow_state.json`
+
+**This enables the core always-on rule to enforce planning mode constraints.**
+
+## 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,285 @@
+# 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.
+
+## Workflow Constraints
+
+**This meta-rule enforces RESEARCH MODE for all bundled sub-rules:**
+
+```json
+{
+  "workflowMode": "research",
+  "constraints": {
+    "mode": "investigation",
+    "allowed": ["read", "search", "analyze", "plan"],
+    "forbidden": ["modify", "create", "build", "commit"]
+  }
+}
+```
+
+**All bundled sub-rules automatically inherit these constraints.**
+
+## Workflow State Update
+
+**When this meta-rule is invoked, update the workflow state file:**
+
+```json
+{
+  "currentMode": "research",
+  "lastInvoked": "meta_research.mdc",
+  "timestamp": "2025-01-27T15:30:00Z",
+  "constraints": {
+    "mode": "investigation",
+    "allowed": ["read", "search", "analyze", "plan"],
+    "forbidden": ["modify", "create", "build", "commit"]
+  }
+}
+```
+
+**State File Location**: `.cursor/rules/.workflow_state.json`
+
+**This enables the core always-on rule to enforce research mode constraints.**
+
+## 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/playwright-test-investigation.mdc

@@ -0,0 +1,356 @@
+---
+description: when working with playwright tests either generating them or using them to test code
+alwaysApply: false
+---
+# Playwright Test Investigation — Harbor Pilot Directive
+
+**Author**: Matthew Raymer  
+**Date**: 2025-08-21T14:22Z  
+**Status**: 🎯 **ACTIVE** - Playwright test debugging guidelines
+
+## Objective
+Provide systematic approach for investigating Playwright test failures with focus on UI element conflicts, timing issues, and selector ambiguity.
+
+## Context & Scope
+- **Audience**: Developers debugging Playwright test failures
+- **In scope**: Test failure analysis, selector conflicts, UI state investigation, timing issues
+- **Out of scope**: Test writing best practices, CI/CD configuration
+
+## Artifacts & Links
+- Test results: `test-results/` directory
+- Error context: `error-context.md` files with page snapshots
+- Trace files: `trace.zip` files for failed tests
+- HTML reports: Interactive test reports with screenshots
+
+## Environment & Preconditions
+- OS/Runtime: Linux/Windows/macOS with Node.js
+- Versions: Playwright test framework, browser drivers
+- Services: Local test server (localhost:8080), test data setup
+- Auth mode: None required for test investigation
+
+## Architecture / Process Overview
+Playwright test investigation follows a systematic diagnostic workflow that leverages built-in debugging tools and error context analysis.
+
+```mermaid
+flowchart TD
+    A[Test Failure] --> B[Check Error Context]
+    B --> C[Analyze Page Snapshot]
+    C --> D[Identify UI Conflicts]
+    D --> E[Check Trace Files]
+    E --> F[Verify Selector Uniqueness]
+    F --> G[Test Selector Fixes]
+    G --> H[Document Root Cause]
+    
+    B --> I[Check Test Results Directory]
+    I --> J[Locate Failed Test Results]
+    J --> K[Extract Error Details]
+    
+    D --> L[Multiple Alerts?]
+    L --> M[Button Text Conflicts?]
+    M --> N[Timing Issues?]
+    
+    E --> O[Use Trace Viewer]
+    O --> P[Analyze Action Sequence]
+    P --> Q[Identify Failure Point]
+```
+
+## Interfaces & Contracts
+
+### Test Results Structure
+| Component | Format | Content | Validation |
+|---|---|---|---|
+| Error Context | Markdown | Page snapshot in YAML | Verify DOM state matches test expectations |
+| Trace Files | ZIP archive | Detailed execution trace | Use `npx playwright show-trace` |
+| HTML Reports | Interactive HTML | Screenshots, traces, logs | Check browser for full report |
+| JSON Results | JSON | Machine-readable results | Parse for automated analysis |
+
+### Investigation Commands
+| Step | Command | Expected Output | Notes |
+|---|---|---|---|
+| Locate failed tests | `find test-results -name "*test-name*"` | Test result directories | Use exact test name patterns |
+| Check error context | `cat test-results/*/error-context.md` | Page snapshots | Look for UI state conflicts |
+| View traces | `npx playwright show-trace trace.zip` | Interactive trace viewer | Analyze exact failure sequence |
+
+## Repro: End-to-End Investigation Procedure
+
+### 1. Locate Failed Test Results
+```bash
+# Find all results for a specific test
+find test-results -name "*test-name*" -type d
+
+# Check for error context files
+find test-results -name "error-context.md" | head -5
+```
+
+### 2. Analyze Error Context
+```bash
+# Read error context for specific test
+cat test-results/test-name-test-description-browser/error-context.md
+
+# Look for UI conflicts in page snapshot
+grep -A 10 -B 5 "button.*Yes\|button.*No" test-results/*/error-context.md
+```
+
+### 3. Check Trace Files
+```bash
+# List available trace files
+find test-results -name "*.zip" | grep trace
+
+# View trace in browser
+npx playwright show-trace test-results/test-name/trace.zip
+```
+
+### 4. Investigate Selector Issues
+```typescript
+// Check for multiple elements with same text
+await page.locator('button:has-text("Yes")').count(); // Should be 1
+
+// Use more specific selectors
+await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes")').click();
+```
+
+## What Works (Evidence)
+- ✅ **Error context files** provide page snapshots showing exact DOM state at failure  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: `test-results/60-new-activity-New-offers-for-another-user-chromium/error-context.md` shows both alerts visible  
+  - **Verify at**: Error context files in test results directory
+
+- ✅ **Trace files** capture detailed execution sequence for failed tests  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: `trace.zip` files available for all failed tests  
+  - **Verify at**: Use `npx playwright show-trace <filename>`
+
+- ✅ **Page snapshots** reveal UI conflicts like multiple alerts with duplicate button text  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: YAML snapshots show registration + export alerts simultaneously  
+  - **Verify at**: Error context markdown files
+
+## What Doesn't (Evidence & Hypotheses)
+- ❌ **Generic selectors** fail with multiple similar elements at `test-playwright/testUtils.ts:161`  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: `button:has-text("Yes")` matches both "Yes" and "Yes, Export Data"  
+  - **Hypothesis**: Selector ambiguity due to multiple alerts with conflicting button text  
+  - **Next probe**: Use more specific selectors or dismiss alerts sequentially
+
+- ❌ **Timing-dependent tests** fail due to alert stacking at `src/views/ContactsView.vue:860,1283`  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: Both alerts use identical 1000ms delays, ensuring simultaneous display  
+  - **Hypothesis**: Race condition between alert displays creates UI conflicts  
+  - **Next probe**: Implement alert queuing or prevent overlapping alerts
+
+## Risks, Limits, Assumptions
+- **Trace file size**: Large trace files may impact storage and analysis time
+- **Browser compatibility**: Trace viewer requires specific browser support
+- **Test isolation**: Shared state between tests may affect investigation results
+- **Timing sensitivity**: Tests may pass/fail based on system performance
+
+## Next Steps
+| Owner | Task | Exit Criteria | Target Date (UTC) |
+|---|---|---|---|
+| Development Team | Fix test selectors for multiple alerts | All tests pass consistently | 2025-08-22 |
+| Development Team | Implement alert queuing system | No overlapping alerts with conflicting buttons | 2025-08-25 |
+| Development Team | Add test IDs to alert buttons | Unique selectors for all UI elements | 2025-08-28 |
+
+## References
+- [Playwright Trace Viewer Documentation](https://playwright.dev/docs/trace-viewer)
+- [Playwright Test Results](https://playwright.dev/docs/test-reporters)
+- [Test Investigation Workflow](./research_diagnostic.mdc)
+
+## Competence Hooks
+- **Why this works**: Systematic investigation leverages Playwright's built-in debugging tools to identify root causes
+- **Common pitfalls**: Generic selectors fail with multiple similar elements; timing issues create race conditions; alert stacking causes UI conflicts
+- **Next skill unlock**: Implement unique test IDs and handle alert dismissal order in test flows
+- **Teach-back**: "How would you investigate a Playwright test failure using error context, trace files, and page snapshots?"
+
+## Collaboration Hooks
+- **Reviewers**: QA team, test automation engineers
+- **Sign-off checklist**: Error context analyzed, trace files reviewed, root cause identified, fix implemented and tested
+
+## Assumptions & Limits
+- Test results directory structure follows Playwright conventions
+- Trace files are enabled in configuration (`trace: "retain-on-failure"`)
+- Error context files contain valid YAML page snapshots
+- Browser environment supports trace viewer functionality
+
+---
+
+**Status**: Active investigation directive  
+**Priority**: High  
+**Maintainer**: Development team  
+**Next Review**: 2025-09-21
+# Playwright Test Investigation — Harbor Pilot Directive
+
+**Author**: Matthew Raymer  
+**Date**: 2025-08-21T14:22Z  
+**Status**: 🎯 **ACTIVE** - Playwright test debugging guidelines
+
+## Objective
+Provide systematic approach for investigating Playwright test failures with focus on UI element conflicts, timing issues, and selector ambiguity.
+
+## Context & Scope
+- **Audience**: Developers debugging Playwright test failures
+- **In scope**: Test failure analysis, selector conflicts, UI state investigation, timing issues
+- **Out of scope**: Test writing best practices, CI/CD configuration
+
+## Artifacts & Links
+- Test results: `test-results/` directory
+- Error context: `error-context.md` files with page snapshots
+- Trace files: `trace.zip` files for failed tests
+- HTML reports: Interactive test reports with screenshots
+
+## Environment & Preconditions
+- OS/Runtime: Linux/Windows/macOS with Node.js
+- Versions: Playwright test framework, browser drivers
+- Services: Local test server (localhost:8080), test data setup
+- Auth mode: None required for test investigation
+
+## Architecture / Process Overview
+Playwright test investigation follows a systematic diagnostic workflow that leverages built-in debugging tools and error context analysis.
+
+```mermaid
+flowchart TD
+    A[Test Failure] --> B[Check Error Context]
+    B --> C[Analyze Page Snapshot]
+    C --> D[Identify UI Conflicts]
+    D --> E[Check Trace Files]
+    E --> F[Verify Selector Uniqueness]
+    F --> G[Test Selector Fixes]
+    G --> H[Document Root Cause]
+    
+    B --> I[Check Test Results Directory]
+    I --> J[Locate Failed Test Results]
+    J --> K[Extract Error Details]
+    
+    D --> L[Multiple Alerts?]
+    L --> M[Button Text Conflicts?]
+    M --> N[Timing Issues?]
+    
+    E --> O[Use Trace Viewer]
+    O --> P[Analyze Action Sequence]
+    P --> Q[Identify Failure Point]
+```
+
+## Interfaces & Contracts
+
+### Test Results Structure
+| Component | Format | Content | Validation |
+|---|---|---|---|
+| Error Context | Markdown | Page snapshot in YAML | Verify DOM state matches test expectations |
+| Trace Files | ZIP archive | Detailed execution trace | Use `npx playwright show-trace` |
+| HTML Reports | Interactive HTML | Screenshots, traces, logs | Check browser for full report |
+| JSON Results | JSON | Machine-readable results | Parse for automated analysis |
+
+### Investigation Commands
+| Step | Command | Expected Output | Notes |
+|---|---|---|---|
+| Locate failed tests | `find test-results -name "*test-name*"` | Test result directories | Use exact test name patterns |
+| Check error context | `cat test-results/*/error-context.md` | Page snapshots | Look for UI state conflicts |
+| View traces | `npx playwright show-trace trace.zip` | Interactive trace viewer | Analyze exact failure sequence |
+
+## Repro: End-to-End Investigation Procedure
+
+### 1. Locate Failed Test Results
+```bash
+# Find all results for a specific test
+find test-results -name "*test-name*" -type d
+
+# Check for error context files
+find test-results -name "error-context.md" | head -5
+```
+
+### 2. Analyze Error Context
+```bash
+# Read error context for specific test
+cat test-results/test-name-test-description-browser/error-context.md
+
+# Look for UI conflicts in page snapshot
+grep -A 10 -B 5 "button.*Yes\|button.*No" test-results/*/error-context.md
+```
+
+### 3. Check Trace Files
+```bash
+# List available trace files
+find test-results -name "*.zip" | grep trace
+
+# View trace in browser
+npx playwright show-trace test-results/test-name/trace.zip
+```
+
+### 4. Investigate Selector Issues
+```typescript
+// Check for multiple elements with same text
+await page.locator('button:has-text("Yes")').count(); // Should be 1
+
+// Use more specific selectors
+await page.locator('div[role="alert"]:has-text("Register") button:has-text("Yes")').click();
+```
+
+## What Works (Evidence)
+- ✅ **Error context files** provide page snapshots showing exact DOM state at failure  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: `test-results/60-new-activity-New-offers-for-another-user-chromium/error-context.md` shows both alerts visible  
+  - **Verify at**: Error context files in test results directory
+
+- ✅ **Trace files** capture detailed execution sequence for failed tests  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: `trace.zip` files available for all failed tests  
+  - **Verify at**: Use `npx playwright show-trace <filename>`
+
+- ✅ **Page snapshots** reveal UI conflicts like multiple alerts with duplicate button text  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: YAML snapshots show registration + export alerts simultaneously  
+  - **Verify at**: Error context markdown files
+
+## What Doesn't (Evidence & Hypotheses)
+- ❌ **Generic selectors** fail with multiple similar elements at `test-playwright/testUtils.ts:161`  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: `button:has-text("Yes")` matches both "Yes" and "Yes, Export Data"  
+  - **Hypothesis**: Selector ambiguity due to multiple alerts with conflicting button text  
+  - **Next probe**: Use more specific selectors or dismiss alerts sequentially
+
+- ❌ **Timing-dependent tests** fail due to alert stacking at `src/views/ContactsView.vue:860,1283`  
+  - **Time**: 2025-08-21T14:22Z  
+  - **Evidence**: Both alerts use identical 1000ms delays, ensuring simultaneous display  
+  - **Hypothesis**: Race condition between alert displays creates UI conflicts  
+  - **Next probe**: Implement alert queuing or prevent overlapping alerts
+
+## Risks, Limits, Assumptions
+- **Trace file size**: Large trace files may impact storage and analysis time
+- **Browser compatibility**: Trace viewer requires specific browser support
+- **Test isolation**: Shared state between tests may affect investigation results
+- **Timing sensitivity**: Tests may pass/fail based on system performance
+
+## Next Steps
+| Owner | Task | Exit Criteria | Target Date (UTC) |
+|---|---|---|---|
+| Development Team | Fix test selectors for multiple alerts | All tests pass consistently | 2025-08-22 |
+| Development Team | Implement alert queuing system | No overlapping alerts with conflicting buttons | 2025-08-25 |
+| Development Team | Add test IDs to alert buttons | Unique selectors for all UI elements | 2025-08-28 |
+
+## References
+- [Playwright Trace Viewer Documentation](https://playwright.dev/docs/trace-viewer)
+- [Playwright Test Results](https://playwright.dev/docs/test-reporters)
+- [Test Investigation Workflow](./research_diagnostic.mdc)
+
+## Competence Hooks
+- **Why this works**: Systematic investigation leverages Playwright's built-in debugging tools to identify root causes
+- **Common pitfalls**: Generic selectors fail with multiple similar elements; timing issues create race conditions; alert stacking causes UI conflicts
+- **Next skill unlock**: Implement unique test IDs and handle alert dismissal order in test flows
+- **Teach-back**: "How would you investigate a Playwright test failure using error context, trace files, and page snapshots?"
+
+## Collaboration Hooks
+- **Reviewers**: QA team, test automation engineers
+- **Sign-off checklist**: Error context analyzed, trace files reviewed, root cause identified, fix implemented and tested
+
+## Assumptions & Limits
+- Test results directory structure follows Playwright conventions
+- Trace files are enabled in configuration (`trace: "retain-on-failure"`)
+- Error context files contain valid YAML page snapshots
+- Browser environment supports trace viewer functionality
+
+---
+
+**Status**: Active investigation directive  
+**Priority**: High  
+**Maintainer**: Development team  
+**Next Review**: 2025-09-21

.cursor/rules/templates/adr_template.mdc

@@ -0,0 +1,98 @@
+---
+alwaysApply: false
+---
+
+# ADR Template
+
+## ADR-XXXX-YY-ZZ: [Short Title]
+
+**Date:** YYYY-MM-DD
+**Status:** [PROPOSED | ACCEPTED | REJECTED | DEPRECATED | SUPERSEDED]
+**Deciders:** [List of decision makers]
+**Technical Story:** [Link to issue/PR if applicable]
+
+## Context
+
+[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.]
+
+## Decision
+
+[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]
+
+## References
+
+- [Link to relevant documentation]
+
+- [Link to related ADRs]
+
+- [Link to external resources]
+
+## Related Decisions
+
+- [List related ADRs or decisions]
+
+---
+
+## Usage Guidelines
+
+1. **Copy this template** for new ADRs
+2. **Number sequentially** (ADR-001, ADR-002, etc.)
+3. **Use descriptive titles** that clearly indicate the decision
+4. **Include all stakeholders** in the deciders list
+5. **Link to related issues** and documentation
+6. **Update status** as decisions evolve
+7. **Store in** `doc/architecture-decisions/` directory
+
+## Model Implementation Checklist
+
+### 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/timesafari.mdc

@@ -1,316 +0,0 @@
----
-description:
-globs:
-alwaysApply: true
----
-# Time Safari Context
-
-## Project Overview
-
-Time Safari is an application designed to foster community building through gifts,
-gratitude, and collaborative projects. The app should make it extremely easy and
-intuitive for users of any age and capability to recognize contributions, build
-trust networks, and organize collective action. It is built on services that
-preserve privacy and data sovereignty.
-
-The ultimate goals of Time Safari are two-fold:
-
-1. **Connect** Make it easy, rewarding, and non-threatening for people to
-connect with others who have similar interests, and to initiate activities
-together. This helps people accomplish and learn from other individuals in
-less-structured environments; moreover, it helps them discover who they want
-to continue to support and with whom they want to maintain relationships.
-
-2. **Reveal** Widely advertise the great support and rewards that are being
-given and accepted freely, especially non-monetary ones. Using visuals and text,
-display the kind of impact that gifts are making in the lives of others. Also
-show useful and engaging reports of project statistics and personal accomplishments.
-
-
-## Core Approaches
-
-Time Safari should help everyday users build meaningful connections and organize
-collective efforts by:
-
-1. **Recognizing Contributions**: Creating permanent, verifiable records of gifts
-and contributions people give to each other and their communities.
-
-2. **Facilitating Collaboration**: Making it ridiculously easy for people to ask
-for or propose help on projects and interests that matter to them.
-
-3. **Building Trust Networks**: Enabling users to maintain their network and activity
-visibility. Developing reputation through verified contributions and references,
-which can be selectively shown to others outside the network.
-
-4. **Preserving Privacy**: Ensuring personal identifiers are only shared with
-explicitly authorized contacts, allowing private individuals including children
-to participate safely.
-
-5. **Engaging Content**: Displaying people's records in compelling stories, and
-highlighting those projects that are lifting people's lives long-term, both in
-physical support and in emotional-spiritual-creative thriving.
-
-
-## Technical Foundation
-
-This application is built on a privacy-preserving claims architecture (via
-endorser.ch) with these key characteristics:
-
-- **Decentralized Identifiers (DIDs)**: User identities are based on public/private
-key pairs stored on their devices
-- **Cryptographic Verification**: All claims and confirmations are
-cryptographically signed
-- **User-Controlled Visibility**: Users explicitly control who can see their
-identifiers and data
-- **Merkle-Chained Claims**: Claims are cryptographically chained for verification
-and integrity
-- **Native and Web App**: Works on Capacitor (iOS, Android), Desktop (Electron
-and CEFPython), and web browsers
-
-## User Journey
-
-The typical progression of usage follows these stages:
-
-1. **Gratitude & Recognition**: Users begin by expressing and recording gratitude
-for gifts received, building a foundation of acknowledgment.
-
-2. **Project Proposals**: Users propose projects and ideas, reaching out to connect
-with others who share similar interests.
-
-3. **Action Triggers**: Offers of help serve as triggers and motivations to execute
-proposed projects, moving from ideas to action.
-
-## Context for LLM Development
-
-When developing new functionality for Time Safari, consider these design principles:
-
-1. **Accessibility First**: Features should be usable by non-technical users with
-minimal learning curve.
-
-2. **Privacy by Design**: All features must respect user privacy and data sovereignty.
-
-3. **Progressive Enhancement**: Core functionality should work across all devices,
-with richer experiences where supported.
-
-4. **Voluntary Collaboration**: The system should enable but never coerce participation.
-
-5. **Trust Building**: Features should help build verifiable trust between users.
-
-6. **Network Effects**: Consider how features scale as more users join the platform.
-
-7. **Low Resource Requirements**: The system should be lightweight enough to run
-on inexpensive devices users already own.
-
-## Use Cases to Support
-
-LLM development should focus on enhancing these key use cases:
-
-1. **Community Building**: Tools that help people find others with shared
-interests and values.
-
-2. **Project Coordination**: Features that make it easy to propose collaborative
-projects and to submit suggestions and offers to existing ones.
-
-3. **Reputation Building**: Methods for users to showcase their contributions
-and reliability, in contexts where they explicitly reveal that information.
-
-4. **Governance Experimentation**: Features that facilitate decision-making and
-collective governance.
-
-## Constraints
-
-When developing new features, be mindful of these constraints:
-
-1. **Privacy Preservation**: User identifiers must remain private except when
-explicitly shared.
-
-2. **Platform Limitations**: Features must work within the constraints of the target
-app platforms, while aiming to leverage the best platform technology available.
-
-3. **Endorser API Limitations**: Backend features are constrained by the endorser.ch
-API capabilities.
-
-4. **Performance on Low-End Devices**: The application should remain performant
-on older/simpler devices.
-
-5. **Offline-First When Possible**: Key functionality should work offline when feasible.
-
-## Project Technologies
-
-- Typescript using ES6 classes using vue-facing-decorator
-- TailwindCSS
-- Vite Build Tool
-- Playwright E2E testing
-- IndexDB
-- Camera, Image uploads, QR Code reader, ...
-
-## Mobile Features
-
-- Deep Linking
-- Local Notifications via a custom Capacitor plugin
-
-## Project Architecture
-
-- The application must work on web browser, PWA (Progressive Web Application),
-  desktop via Electron, and mobile via Capacitor
-- Building for each platform is managed via Vite
-
-## Core Development Principles
-
-### DRY development
-
-- **Code Reuse**
-  - Extract common functionality into utility functions
-  - Create reusable components for UI patterns
-  - Implement service classes for shared business logic
-  - Use mixins for cross-cutting concerns
-  - Leverage TypeScript interfaces for shared type definitions
-
-- **Component Patterns**
-  - Create base components for common UI elements
-  - Implement higher-order components for shared behavior
-  - Use slot patterns for flexible component composition
-  - Create composable services for business logic
-  - Implement factory patterns for component creation
-
-- **State Management**
-  - Centralize state in Pinia stores
-  - Use computed properties for derived state
-  - Implement shared state selectors
-  - Create reusable state mutations
-  - Use action creators for common operations
-
-- **Error Handling**
-  - Implement centralized error handling
-  - Create reusable error components
-  - Use error boundary components
-  - Implement consistent error logging
-  - Create error type definitions
-
-- **Type Definitions**
-  - Create shared interfaces for common data structures
-  - Use type aliases for complex types
-  - Implement generic types for reusable components
-  - Create utility types for common patterns
-  - Use discriminated unions for state management
-
-- **API Integration**
-  - Create reusable API client classes
-  - Implement request/response interceptors
-  - Use consistent error handling patterns
-  - Create type-safe API endpoints
-  - Implement caching strategies
-
-- **Platform Services**
-  - Abstract platform-specific code behind interfaces
-  - Create platform-agnostic service layers
-  - Implement feature detection
-  - Use dependency injection for services
-  - Create service factories
-
-- **Testing**
-  - Create reusable test utilities
-  - Implement test factories
-  - Use shared test configurations
-  - Create reusable test helpers
-  - Implement consistent test patterns
-  - F.I.R.S.T. (for Unit Tests)
-    F – Fast
-    I – Independent
-    R – Repeatable
-    S – Self-validating
-    T – Timely
-
-### SOLID Principles
-
-- **Single Responsibility**: Each class/component should have only one reason to
-  change
-  - Components should focus on one specific feature (e.g., QR scanning, DID management)
-  - Services should handle one type of functionality (e.g., platform services,
-    crypto services)
-  - Utilities should provide focused helper functions
-
-- **Open/Closed**: Software entities should be open for extension but closed for
-  modification
-  - Use interfaces for service definitions
-  - Implement plugin architecture for platform-specific features
-  - Allow component behavior extension through props and events
-
-- **Liskov Substitution**: Objects should be replaceable with their subtypes
-  - Platform services should work consistently across web/mobile
-  - Authentication providers should be interchangeable
-  - Storage implementations should be swappable
-
-- **Interface Segregation**: Clients shouldn't depend on interfaces they don't use
-  - Break down large service interfaces into smaller, focused ones
-  - Component props should be minimal and purposeful
-  - Event emissions should be specific and targeted
-
-- **Dependency Inversion**: High-level modules shouldn't depend on low-level modules
-  - Use dependency injection for services
-  - Abstract platform-specific code behind interfaces
-  - Implement factory patterns for component creation
-
-### Law of Demeter
-
-- Components should only communicate with immediate dependencies
-- Avoid chaining method calls (e.g., `this.service.getUser().getProfile().getName()`)
-- Use mediator patterns for complex component interactions
-- Implement facade patterns for subsystem access
-- Keep component communication through defined events and props
-
-### Composition over Inheritance
-
-- Prefer building components through composition
-- Use mixins for shared functionality
-- Implement feature toggles through props
-- Create higher-order components for common patterns
-- Use service composition for complex features
-
-### Interface Segregation
-
-- Define clear interfaces for services
-- Keep component APIs minimal and focused
-- Split large interfaces into smaller, specific ones
-- Use TypeScript interfaces for type definitions
-- Implement role-based interfaces for different use cases
-
-### Fail Fast
-
-- Validate inputs early in the process
-- Use TypeScript strict mode
-- Implement comprehensive error handling
-- Add runtime checks for critical operations
-- Use assertions for development-time validation
-
-### Principle of Least Astonishment
-
-- Follow Vue.js conventions consistently
-- Use familiar naming patterns
-- Implement predictable component behaviors
-- Maintain consistent error handling
-- Keep UI interactions intuitive
-
-### Information Hiding
-
-- Encapsulate implementation details
-- Use private class members
-- Implement proper access modifiers
-- Hide complex logic behind simple interfaces
-- Use TypeScript's access modifiers effectively
-
-### Single Source of Truth
-
-- Use Pinia for state management
-- Maintain one source for user data
-- Centralize configuration management
-- Use computed properties for derived state
-- Implement proper state synchronization
-
-### Principle of Least Privilege
-
-- Implement proper access control
-- Use minimal required permissions
-- Follow privacy-by-design principles
-- Restrict component access to necessary data
-- Implement proper authentication/authorization

.cursor/rules/version_control.mdc

@@ -1,122 +0,0 @@
----
-alwaysApply: true
----
-# Directive: Peaceful Co-Existence with Developers
-
-## 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
-
-* **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
-
-* **ALWAYS** present, before any real commit:
-
-  * file list + brief per-file notes,
-  * a **draft commit message** (copy-paste ready),
-  * nothing auto-applied.
-
----
-
-# 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

.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

@@ -0,0 +1,86 @@
+# Directive: Peaceful Co-Existence with Developers
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-19
+**Status**: 🎯 **ACTIVE** - Version control guidelines
+
+## 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
+
+- **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
+
+- **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
+
+- **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
+
+## 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
+- [ ] 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
+
+## Model Implementation Checklist
+
+### Before Version Control Work
+
+- [ ] **File Analysis**: Review files staged and awaiting staging
+- [ ] **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
+
+### During Version Control Work
+
+- [ ] **Commit Preview**: Present file list with brief notes per file
+- [ ] **Message Draft**: Provide focused draft commit message
+- [ ] **Format Validation**: Ensure message follows type(scope)! syntax
+- [ ] **Version Sync**: Validate version consistency between files
+
+### After Version Control Work
+
+- [ ] **Developer Control**: Leave staging/committing to developer
+- [ ] **Message Validation**: Verify message aligns strictly with diffs
+- [ ] **Version Validation**: Confirm version format consistency
+- [ ] **Documentation**: Update relevant version control documentation

.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

.dockerignore

@@ -140,7 +140,7 @@ docker-compose*
 .dockerignore
 
 # CI/CD files
-.github
+
 .gitlab-ci.yml
 .travis.yml
 .circleci

.env.development

@@ -1,10 +1,14 @@
-
 # Only the variables that start with VITE_ are seen in the application import.meta.env in Vue.
 
+# Logging Configuration - Development environment gets maximum visibility
+VITE_LOG_LEVEL=debug
+
 # iOS doesn't like spaces in the app title.
 TIME_SAFARI_APP_TITLE="TimeSafari_Dev"
 VITE_APP_SERVER=http://localhost:8080
-# This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not production).
+# This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not
+
+
 VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F
 VITE_DEFAULT_ENDORSER_API_SERVER=http://localhost:3000
 # Using shared server by default to ease setup, which works for shared test users.

.env.production

@@ -1,6 +1,7 @@
 # Only the variables that start with VITE_ are seen in the application import.meta.env in Vue.
 
-
+# Logging Configuration - Production environment gets minimal logging for performance
+VITE_LOG_LEVEL=warn
 
 VITE_APP_SERVER=https://timesafari.app
 # This is the claim ID for actions in the BVC project.

.env.test

@@ -1,9 +1,14 @@
 # Only the variables that start with VITE_ are seen in the application import.meta.env in Vue.
 
+# Logging Configuration - Test environment gets balanced logging for debugging
+VITE_LOG_LEVEL=info
+
 # iOS doesn't like spaces in the app title.
 TIME_SAFARI_APP_TITLE="TimeSafari_Test"
 VITE_APP_SERVER=https://test.timesafari.app
+# This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not
 # This is the claim ID for actions in the BVC project, with the JWT ID on this environment (not production).
+
 VITE_BVC_MEETUPS_PROJECT_CLAIM_ID=https://endorser.ch/entity/01HWE8FWHQ1YGP7GFZYYPS272F
 VITE_DEFAULT_ENDORSER_API_SERVER=https://test-api.endorser.ch
 

.eslintrc.js

@@ -30,7 +30,7 @@ module.exports = {
     }],
     "no-console": process.env.NODE_ENV === "production" ? "error" : "warn",
     "no-debugger": process.env.NODE_ENV === "production" ? "error" : "warn",
-    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-explicit-any": "error",
     "@typescript-eslint/explicit-function-return-type": "off",
     "@typescript-eslint/no-unnecessary-type-constraint": "off",
     "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]

.github/workflows/playwright.yml

@@ -1,27 +0,0 @@
-name: Playwright Tests
-on:
-  push:
-    branches: [ main, master ]
-  pull_request:
-    branches: [ main, master ]
-jobs:
-  test:
-    timeout-minutes: 60
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-node@v4
-      with:
-        node-version: lts/*
-    - name: Install dependencies
-      run: npm ci
-    - name: Install Playwright Browsers
-      run: npx playwright install --with-deps
-    - name: Run Playwright tests
-      run: npx playwright test
-    - uses: actions/upload-artifact@v4
-      if: always()
-      with:
-        name: playwright-report
-        path: playwright-report/
-        retention-days: 30

.gitignore

@@ -51,11 +51,21 @@ vendor/
 # Build logs
 build_logs/
 
+# Guard feedback logs (for continuous improvement analysis)
+.guard-feedback.log
+
+# Workflow state file (contains dynamic state, not version controlled)
+.cursor/rules/.workflow_state.json
+
 # PWA icon files generated by capacitor-assets
 icons
 
 *.log
 
+# Build outputs
+dist/
+build/
+
 # Generated Android assets and resources (should be generated during build)
 android/app/src/main/assets/public/
 
@@ -64,6 +74,14 @@ android/app/src/main/res/drawable*/
 android/app/src/main/res/mipmap*/
 android/app/src/main/res/values/ic_launcher_background.xml
 
+# Android generated assets (deny-listed in CI)
+android/app/src/main/res/mipmap-*/ic_launcher*.png
+android/app/src/main/res/drawable*/splash*.png
+
+# iOS generated assets (deny-listed in CI)
+ios/App/App/Assets.xcassets/**/AppIcon*.png
+ios/App/App/Assets.xcassets/**/Splash*.png
+
 # Keep these Android configuration files in version control:
 # - android/app/src/main/assets/capacitor.plugins.json
 # - android/app/src/main/res/values/strings.xml
@@ -128,4 +146,5 @@ electron/out/
 # Gradle cache files
 android/.gradle/file-system.probe
 android/.gradle/caches/
-coverage
+coverage
+.husky-enabled

.husky/_/husky.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+#
+# Husky Helper Script
+# This file is sourced by all Husky hooks
+#
+if [ -z "$husky_skip_init" ]; then
+  debug () {
+    if [ "$HUSKY_DEBUG" = "1" ]; then
+      echo "husky (debug) - $1"
+    fi
+  }
+
+  readonly hook_name="$(basename -- "$0")"
+  debug "starting $hook_name..."
+
+  if [ "$HUSKY" = "0" ]; then
+    debug "HUSKY env variable is set to 0, skipping hook"
+    exit 0
+  fi
+
+  if [ -f ~/.huskyrc ]; then
+    debug "sourcing ~/.huskyrc"
+    . ~/.huskyrc
+  fi
+
+  readonly husky_skip_init=1
+  export husky_skip_init
+  sh -e "$0" "$@"
+  exitCode="$?"
+
+  if [ $exitCode != 0 ]; then
+    echo "husky - $hook_name hook exited with code $exitCode (error)"
+  fi
+
+  if [ $exitCode = 127 ]; then
+    echo "husky - command not found in PATH=$PATH"
+  fi
+
+  exit $exitCode
+fi

.husky/commit-msg

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+#
+# Husky Commit Message Hook
+# Validates commit message format using commitlint
+#
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run commitlint but don't fail the commit (|| true)
+# This provides helpful feedback without blocking commits
+npx commitlint --edit "$1" || true

.husky/pre-commit

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+#
+# Husky Pre-commit Hook
+# Runs lint-fix and Build Architecture Guard on staged files
+#
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "🔍 Running pre-commit hooks..."
+
+# Run lint-fix first
+echo "📝 Running lint-fix..."
+npm run lint-fix || {
+    echo
+    echo "❌ Linting failed. Please fix the issues and try again."
+    echo "💡 To bypass this check for emergency commits, use:"
+    echo "   git commit --no-verify"
+    echo
+    exit 1
+}
+
+# Then run Build Architecture Guard
+echo "🏗️  Running Build Architecture Guard..."
+bash ./scripts/build-arch-guard.sh --staged || {
+    echo
+    echo "❌ Build Architecture Guard failed. Please fix the issues and try again."
+    echo "💡 To bypass this check for emergency commits, use:"
+    echo "   git commit --no-verify"
+    echo
+    exit 1
+}
+
+echo "✅ All pre-commit checks passed!"
+

.husky/pre-push

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+#
+# Husky Pre-push Hook  
+# Runs Build Architecture Guard to check commits being pushed
+#
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "🔍 Running Build Architecture Guard (pre-push)..."
+
+# Get the remote branch we're pushing to
+REMOTE_BRANCH="origin/$(git rev-parse --abbrev-ref HEAD)"
+
+# Check if remote branch exists
+if git show-ref --verify --quiet "refs/remotes/$REMOTE_BRANCH"; then
+    RANGE="$REMOTE_BRANCH...HEAD"
+else
+    # If remote branch doesn't exist, check last commit
+    RANGE="HEAD~1..HEAD"
+fi
+
+bash ./scripts/build-arch-guard.sh --range "$RANGE" || {
+    echo
+    echo "💡 To bypass this check for emergency pushes, use:"
+    echo "   git push --no-verify"
+    echo
+    exit 1
+}

.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
+}

.node-version

@@ -0,0 +1 @@
+18.19.0

.nvmrc

@@ -0,0 +1 @@
+18.19.0

CHANGELOG.md

@@ -5,72 +5,89 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.3] - 2025.07.12
+## [1.0.7] - 2025.08.18
-### Changed
+
-- Photo is pinned to profile mode
 ### Fixed
-- Deep link URLs (and other prod settings)
+
-- Error in BVC begin view
+- Deep link for onboard-meeting-members
 
 ## [1.0.6] - 2025.08.09
+
 ### Fixed
+
 - Deep link errors where none would validate
 
-
 ## [1.0.5] - 2025.07.24
+
 ### Fixed
+
 - Export & import of contacts corrupted contact methods
 
-
 ## [1.0.4] - 2025.07.20 - 002f2407208d56cc59c0aa7c880535ae4cbace8b
+
 ### Fixed
+
 - Deep link for invite-one-accept
 
-
 ## [1.0.3] - 2025.07.12 - a9a8ba217cd6015321911e98e6843e988dc2c4ae
+
 ### Changed
+
 - Photo is pinned to profile mode
+
 ### Fixed
+
 - Deep link URLs (and other prod settings)
 - Error in BVC begin view
 
-
 ## [1.0.2] - 2025.06.20 - 276e0a741bc327de3380c4e508cccb7fee58c06d
+
 ### Added
+
 - Version on feed title
 
-
 ## [1.0.1] - 2025.06.20
+
 ### Added
+
 - Allow a user to block someone else's content from view
 
-
 ## [1.0.0] - 2025.06.20 - 5aa693de6337e5dbb278bfddc6bd39094bc14f73
+
 ### Added
+
 - Web-oriented migration from IndexedDB to SQLite
 
-
 ## [0.5.8]
+
 ### Added
+
 - /deep-link/ path for URLs that are shared with people
+
 ### Changed
+
 - External links now go to /deep-link/...
 - Feed visuals now have arrow imagery from giver to receiver
 
-
 ## [0.4.7]
+
 ### Fixed
+
 - Cameras everywhere
+
 ### Changed
+
 - IndexedDB -> SQLite
 
-
 ## [0.4.5] - 2025.02.23
-### Added
-- Total amounts of gives on project page
-### Changed in DB or environment
-- Requires Endorser.ch version 4.2.6+
 
+### Added
+
+- Total amounts of gives on project page
+
+### Changed in DB or environment
+
+- Requires Endorser.ch version 4.2.6+
 
 ## [0.4.4] - 2025.02.17
 

README-PR-TEMPLATE.md

@@ -0,0 +1,82 @@
+# Pull Request Template
+
+## Location
+
+The Build Architecture Guard PR template is located at:
+
+- **`pull_request_template.md`** (root directory)
+
+## Usage
+
+When creating a pull request in Gitea, this template will automatically populate the PR description with the required checklist.
+
+## Template Features
+
+### Change Level Classification
+
+- **L1**: Minor changes, documentation updates
+- **L2**: Moderate changes, new features, environment changes
+- **L3**: Major changes, architecture changes, new platforms
+
+### Required Fields for All Levels
+
+- Change level selection
+- Scope and impact description
+- Commands executed and their output
+- Documentation updates (BUILDING.md)
+- Rollback verification steps
+
+### Additional Requirements for L3
+
+- **ADR link**: Must provide URL to Architectural Decision Record
+- **Artifacts with SHA256**: Must list artifacts with cryptographic hashes
+
+## Integration
+
+This template works with:
+
+- **Gitea Actions**: `.gitea/workflows/build-guard.yml`
+- **Client-side hooks**: `.husky/` pre-commit and pre-push hooks
+- **Guard script**: `scripts/build-arch-guard.sh`
+
+## Example Usage
+
+```markdown
+### Change Level
+- [x] Level: **L2**
+
+**Why:** Adding new build script for Docker deployment
+
+### Scope & Impact
+- [x] Files & platforms touched: scripts/build-docker.sh,
+  BUILDING.md
+- [x] Risk triggers: Docker build process changes
+- [x] Mitigations/validation done: Tested on local Docker environment
+
+### Commands Run
+- [x] Web: `npm run build:web:docker` ✅
+- [x] Docker: `docker build -t test-image .` ✅
+
+### Artifacts
+- [x] Names + **sha256** of artifacts/installers:
+
+Artifacts:
+```text
+test-image.tar  a1b2c3d4e5f6...
+```
+
+### Docs
+- [x] **BUILDING.md** updated (sections): Docker deployment
+- [x] Troubleshooting updated: Added Docker troubleshooting section
+
+### Rollback
+- [x] Verified steps to restore previous behavior:
+  1. `git revert HEAD`
+  2. `docker rmi test-image`
+  3. Restore previous BUILDING.md
+```
+
+---
+
+**Note**: This template is enforced by the Build Architecture Guard
+system. Complete all required fields to ensure your PR can be merged.

README.md

@@ -3,36 +3,9 @@
 [Time Safari](https://timesafari.org/) allows people to ease into collaboration: start with expressions of gratitude
 and expand to crowd-fund with time & money, then record and see the impact of contributions.
 
-## Database Migration Status
-
-**Current Status**: The application is undergoing a migration from Dexie (IndexedDB) to SQLite using absurd-sql. This migration is in **Phase 2** with a well-defined migration fence in place.
-
-### Migration Progress
-- ✅ **SQLite Database Service**: Fully implemented with absurd-sql
-- ✅ **Platform Service Layer**: Unified database interface across platforms
-- ✅ **Settings Migration**: Core user settings transferred
-- ✅ **Account Migration**: Identity and key management
-- 🔄 **Contact Migration**: User contact data (via import interface)
-- 📋 **Code Cleanup**: Remove unused Dexie imports
-
-### Migration Fence
-The migration is controlled by a **migration fence** that separates legacy Dexie code from the new SQLite implementation. See [Migration Fence Definition](doc/migration-fence-definition.md) for complete details.
-
-**Key Points**:
-- Legacy Dexie database is disabled by default
-- All database operations go through `PlatformServiceMixin`
-- Migration tools provide controlled access to both databases
-- Clear separation between legacy and new code
-
-### Migration Documentation
-- [Migration Guide](doc/migration-to-wa-sqlite.md) - Complete migration process
-- [Migration Fence Definition](doc/migration-fence-definition.md) - Fence boundaries and rules
-- [Database Migration Guide](doc/database-migration-guide.md) - User-facing migration tools
-
 ## Roadmap
 
-See [project.task.yaml](project.task.yaml) for current priorities.
+See [ClickUp](https://sharing.clickup.com/9014278710/l/h/8cmnyhp-174/10573fec74e2ba0) for current priorities.
-(Numbers at the beginning of lines are estimated hours. See [taskyaml.org](https://taskyaml.org/) for details.)
 
 ## Setup & Building
 
@@ -42,14 +15,79 @@ Quick start:
 
 ```bash
 npm install
-npm run dev
+npm run build:web:serve -- --test
 ```
 
+To be able to take action on the platform: go to [the test page](http://localhost:8080/test) and click "Become User 0".
+
 See [BUILDING.md](BUILDING.md) for comprehensive build instructions for all platforms (Web, Electron, iOS, Android, Docker).
 
+## 🛡️ Build Architecture Guard
+
+This project uses **Husky Git hooks** to protect the build system
+architecture. When you modify build-critical files, the system
+automatically blocks commits until you update `BUILDING.md`.
+
+### Quick Setup
+
+```bash
+npm run guard:setup  # Install and activate the guard
+```
+
+### How It Works
+
+- **Pre-commit**: Blocks commits if build files changed without
+  BUILDING.md updates
+- **Pre-push**: Blocks pushes if commits contain undocumented build
+  changes
+- **Protected paths**: `scripts/`, `vite.config.*`, `electron/`,
+  `android/`, `ios/`, etc.
+
+### Usage
+
+```bash
+# Test the guard manually
+npm run guard:test
+
+# Emergency bypass (use sparingly)
+git commit --no-verify
+git push --no-verify
+```
+
+**📚 Full documentation**: See `doc/README-BUILD-GUARD.md`
+
 ## Development Database Clearing
 
-TimeSafari provides a simple script-based approach to clear the database for development purposes.
+TimeSafari provides a simple script-based approach to clear the local database (not the claim server) for development purposes.
+
+## Logging Configuration
+
+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
@@ -126,18 +164,83 @@ const apiUrl = `${APP_SERVER}/api/claim/123`;
 
 ### Documentation
 
-- [Domain Configuration System](docs/domain-configuration.md) - Complete guide
 - [Constants and Configuration](src/constants/app.ts) - Core constants
 
 ## Tests
 
 See [TESTING.md](test-playwright/TESTING.md) for detailed test instructions.
 
-## Icons
+## Asset Management
 
-Application icons are in the `assets` directory, processed by the `capacitor-assets` command.
+TimeSafari uses a standardized asset configuration system for consistent
+icon and splash screen generation across all platforms.
 
-To add a Font Awesome icon, add to fontawesome.ts and reference with `font-awesome` element and `icon` attribute with the hyphenated name.
+### 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
+
+# Validate your development environment
+npm run check:dependencies
+
+# Check prerequisites for testing
+npm run test:prerequisites
+```
+
+**Common Issues & Solutions**:
+
+- **"tsx: command not found"**: Run `npm install` to install devDependencies
+- **"capacitor-assets: command not found"**: Ensure `@capacitor/assets` is installed
+- **Build failures**: Run `npm run check:dependencies` to diagnose environment issues
+
+**Required Versions**:
+- Node.js: 18+ (LTS recommended)
+- npm: 8+ (comes with Node.js)
+- Platform-specific tools: Android Studio, Xcode (for mobile builds)
+
+### Platform Support
+
+- **Android**: Adaptive icons with foreground/background, monochrome support
+- **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
 
@@ -187,7 +290,29 @@ The application uses a platform-agnostic database layer with Vue mixins for serv
 
 **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.
 
-### Kudos
+## 📁 Project Structure
+
+```text
+timesafari/
+├── 📁 src/              # Source code
+├── 📁 scripts/          # Build and automation scripts
+├── 📁 electron/         # Electron configuration
+├── 📁 android/          # Android configuration  
+├── 📁 ios/              # iOS configuration
+├── 📁 .husky/           # Git hooks (Build Architecture Guard)
+├── 📄 BUILDING.md       # Build system documentation
+├── 📄 pull_request_template.md # PR template
+└── 📄 doc/README-BUILD-GUARD.md # Guard system documentation
+```
+
+## 🤝 Contributing
+
+1. **Follow the Build Architecture Guard** - Update BUILDING.md when modifying build files
+2. **Use the PR template** - Complete the checklist for build-related changes
+3. **Test your changes** - Ensure builds work on affected platforms
+4. **Document updates** - Keep BUILDING.md current and accurate
+
+## Kudos
 
 Gifts make the world go 'round!
 

TASK_storage.md

@@ -1,7 +1,6 @@
 
 # What to do about storage for native apps?
 
-
 ## Problem
 
 We can't trust iOS IndexedDB to persist. I want to start delivering an app to people now, in preparation for presentations mid-June: Rotary on June 12 and Porcfest on June 17.
@@ -14,7 +13,6 @@ We can't trust iOS IndexedDB to persist. I want to start delivering an app to pe
 
 Also, with sensitive data, the accounts info should be encrypted.
 
-
 # Options
 
 * There is a community [SQLite plugin for Capacitor](https://github.com/capacitor-community/sqlite) with encryption by [SQLCipher](https://github.com/sqlcipher/sqlcipher).
@@ -29,16 +27,12 @@ Also, with sensitive data, the accounts info should be encrypted.
 
 * Not an option yet: Dexie may support SQLite in [a future version](https://dexie.org/roadmap/dexie5.0).
 
-
-
 # Current Plan
 
 * Implement SQLite for Capacitor & web, with encryption. That will allow us to test quickly and keep the same interface for native & web, but we don't deal with migrations for current web users.
 
 * After that is delivered, write a migration for current web users from IndexedDB to SQLite.
 
-
-
 # Current method calls
 
 ... which is not 100% complete because the AI that generated thus claimed no usage of 'temp' DB.
@@ -80,5 +74,3 @@ Logs operations:
 db.logs.get(todayKey) - Gets logs for a specific day
 db.logs.update(todayKey, { message: fullMessage }) - Updates logs
 db.logs.clear() - Clears all logs
-
-

android/app/build.gradle

@@ -31,8 +31,8 @@ android {
         applicationId "app.timesafari.app"
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
-        versionCode 39
+        versionCode 40
-        versionName "1.0.6"
+        versionName "1.0.7"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
         aaptOptions {
              // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.

android/app/capacitor.build.gradle

@@ -13,8 +13,10 @@ 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')
     implementation project(':capawesome-capacitor-file-picker')
 
 }

android/app/src/main/AndroidManifest.xml

@@ -14,6 +14,7 @@
             android:label="@string/title_activity_main"
             android:launchMode="singleTask"
             android:screenOrientation="portrait"
+            android:windowSoftInputMode="adjustResize"
             android:theme="@style/AppTheme.NoActionBarLaunch">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />

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

@@ -29,7 +29,7 @@
 			"splashFullScreen": true,
 			"splashImmersive": true
 		},
-		"CapacitorSQLite": {
+		"CapSQLite": {
 			"iosDatabaseLocation": "Library/CapacitorDatabase",
 			"iosIsEncryption": false,
 			"iosBiometric": {

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"
@@ -23,6 +27,10 @@
 		"pkg": "@capacitor/share",
 		"classpath": "com.capacitorjs.plugins.share.SharePlugin"
 	},
+	{
+		"pkg": "@capacitor/status-bar",
+		"classpath": "com.capacitorjs.plugins.statusbar.StatusBarPlugin"
+	},
 	{
 		"pkg": "@capawesome/capacitor-file-picker",
 		"classpath": "io.capawesome.capacitorjs.plugins.filepicker.FilePickerPlugin"

android/app/src/main/java/app/timesafari/MainActivity.java

@@ -1,7 +1,16 @@
 package app.timesafari;
 
 import android.os.Bundle;
+import android.view.View;
+import android.view.WindowManager;
+import android.view.WindowInsetsController;
+import android.view.WindowInsets;
+import android.os.Build;
+import android.webkit.WebView;
+import android.webkit.WebSettings;
+import android.webkit.WebViewClient;
 import com.getcapacitor.BridgeActivity;
+import app.timesafari.safearea.SafeAreaPlugin;
 //import com.getcapacitor.community.sqlite.SQLite;
 
 public class MainActivity extends BridgeActivity {
@@ -9,7 +18,39 @@ public class MainActivity extends BridgeActivity {
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         
+        // Enable edge-to-edge display for modern Android
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            // Android 11+ (API 30+)
+            getWindow().setDecorFitsSystemWindows(false);
+            
+            // Set up system UI visibility for edge-to-edge
+            WindowInsetsController controller = getWindow().getInsetsController();
+            if (controller != null) {
+                controller.setSystemBarsAppearance(
+                    WindowInsetsController.APPEARANCE_LIGHT_STATUS_BARS | 
+                    WindowInsetsController.APPEARANCE_LIGHT_NAVIGATION_BARS,
+                    WindowInsetsController.APPEARANCE_LIGHT_STATUS_BARS | 
+                    WindowInsetsController.APPEARANCE_LIGHT_NAVIGATION_BARS
+                );
+                controller.setSystemBarsBehavior(WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE);
+            }
+        } else {
+            // Legacy Android (API 21-29)
+            getWindow().getDecorView().setSystemUiVisibility(
+                View.SYSTEM_UI_FLAG_LAYOUT_STABLE |
+                View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION |
+                View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN |
+                View.SYSTEM_UI_FLAG_LIGHT_STATUS_BAR |
+                View.SYSTEM_UI_FLAG_LIGHT_NAVIGATION_BAR
+            );
+        }
+        
+        // Register SafeArea plugin
+        registerPlugin(SafeAreaPlugin.class);
+        
         // Initialize SQLite
         //registerPlugin(SQLite.class);
     }
+    
+
 } 

android/app/src/main/java/app/timesafari/safearea/SafeAreaPlugin.java

@@ -0,0 +1,44 @@
+package app.timesafari.safearea;
+
+import android.os.Build;
+import android.view.WindowInsets;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+@CapacitorPlugin(name = "SafeArea")
+public class SafeAreaPlugin extends Plugin {
+
+    @PluginMethod
+    public void getSafeAreaInsets(PluginCall call) {
+        JSObject result = new JSObject();
+        
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+            WindowInsets insets = getActivity().getWindow().getDecorView().getRootWindowInsets();
+            if (insets != null) {
+                int top = insets.getInsets(WindowInsets.Type.statusBars()).top;
+                int bottom = insets.getInsets(WindowInsets.Type.navigationBars()).bottom;
+                int left = insets.getInsets(WindowInsets.Type.systemBars()).left;
+                int right = insets.getInsets(WindowInsets.Type.systemBars()).right;
+                
+                result.put("top", top);
+                result.put("bottom", bottom);
+                result.put("left", left);
+                result.put("right", right);
+                
+                call.resolve(result);
+                return;
+            }
+        }
+        
+        // Fallback values
+        result.put("top", 0);
+        result.put("bottom", 0);
+        result.put("left", 0);
+        result.put("right", 0);
+        
+        call.resolve(result);
+    }
+}

android/app/src/main/res/values/colors.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <color name="colorPrimary">#3F51B5</color>
+    <color name="colorPrimaryDark">#303F9F</color>
+    <color name="colorAccent">#FF4081</color>
+    <color name="ic_launcher_background">#FFFFFF</color>
+</resources>

android/app/src/main/res/values/styles.xml

@@ -18,5 +18,14 @@
 
     <style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
         <item name="android:background">@drawable/splash</item>
+        <item name="android:windowTranslucentStatus">false</item>
+        <item name="android:windowTranslucentNavigation">false</item>
+        <item name="android:windowDrawsSystemBarBackgrounds">true</item>
+        <item name="android:statusBarColor">@android:color/transparent</item>
+        <item name="android:navigationBarColor">@android:color/transparent</item>
+        <item name="android:windowLightStatusBar">true</item>
+        <item name="android:windowLightNavigationBar">true</item>
+        <item name="android:enforceStatusBarContrast">false</item>
+        <item name="android:enforceNavigationBarContrast">false</item>
     </style>
 </resources>

android/build.gradle

@@ -7,7 +7,7 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.12.0'
+        classpath 'com.android.tools.build:gradle:8.12.1'
         classpath 'com.google.gms:google-services:4.4.0'
 
         // NOTE: Do not place your application dependencies here; they belong

android/capacitor.settings.gradle

@@ -14,11 +14,17 @@ 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')
 
 include ':capacitor-share'
 project(':capacitor-share').projectDir = new File('../node_modules/@capacitor/share/android')
 
+include ':capacitor-status-bar'
+project(':capacitor-status-bar').projectDir = new File('../node_modules/@capacitor/status-bar/android')
+
 include ':capawesome-capacitor-file-picker'
 project(':capawesome-capacitor-file-picker').projectDir = new File('../node_modules/@capawesome/capacitor-file-picker/android')

assets/README.md

@@ -1,2 +0,0 @@
-
-Application icons are here. They are processed for android & ios by the `capacitor-assets` command, as indicated in the BUILDING.md file.

capacitor-assets.config.json

@@ -1,36 +1,32 @@
 {
   "icon": {
-    "ios": {
-      "source": "resources/ios/icon/icon.png",
-      "target": "ios/App/App/Assets.xcassets/AppIcon.appiconset"
-    },
     "android": {
-      "source": "resources/android/icon/icon.png",
+      "adaptive": {
+        "background": "#121212",
+        "foreground": "resources/icon.png",
+        "monochrome": "resources/icon.png"
+      },
       "target": "android/app/src/main/res"
     },
+    "ios": {
+      "padding": 0,
+      "target": "ios/App/App/Assets.xcassets/AppIcon.appiconset"
+    },
+    "source": "resources/icon.png",
     "web": {
-      "source": "resources/web/icon/icon.png",
       "target": "public/img/icons"
     }
   },
   "splash": {
-    "ios": {
-      "source": "resources/ios/splash/splash.png",
-      "target": "ios/App/App/Assets.xcassets/Splash.imageset"
-    },
     "android": {
-      "source": "resources/android/splash/splash.png",
+      "scale": "cover",
       "target": "android/app/src/main/res"
-    }
-  },
-  "splashDark": {
-    "ios": {
-      "source": "resources/ios/splash/splash_dark.png",
-      "target": "ios/App/App/Assets.xcassets/SplashDark.imageset"
     },
-    "android": {
+    "darkSource": "resources/splash_dark.png",
-      "source": "resources/android/splash/splash_dark.png",
+    "ios": {
-      "target": "android/app/src/main/res"
+      "target": "ios/App/App/Assets.xcassets",
-    }
+      "useStoryBoard": true
+    },
+    "source": "resources/splash.png"
   }
-} 
+}

capacitor.config.ts

@@ -0,0 +1,116 @@
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'app.timesafari',
+  appName: 'TimeSafari',
+  webDir: 'dist',
+  server: {
+    cleartext: true
+  },
+  plugins: {
+    App: {
+      appUrlOpen: {
+        handlers: [
+          {
+            url: 'timesafari://*',
+            autoVerify: true
+          }
+        ]
+      }
+    },
+    SplashScreen: {
+      launchShowDuration: 3000,
+      launchAutoHide: true,
+      backgroundColor: '#ffffff',
+      androidSplashResourceName: 'splash',
+      androidScaleType: 'CENTER_CROP',
+      showSpinner: false,
+      androidSpinnerStyle: 'large',
+      iosSpinnerStyle: 'small',
+      spinnerColor: '#999999',
+      splashFullScreen: true,
+      splashImmersive: true
+    },
+    CapSQLite: {
+      iosDatabaseLocation: 'Library/CapacitorDatabase',
+      iosIsEncryption: false,
+      iosBiometric: {
+        biometricAuth: false,
+        biometricTitle: 'Biometric login for TimeSafari'
+      },
+      androidIsEncryption: false,
+      androidBiometric: {
+        biometricAuth: false,
+        biometricTitle: 'Biometric login for TimeSafari'
+      },
+      electronIsEncryption: false
+    }
+  },
+  ios: {
+    contentInset: 'never',
+    allowsLinkPreview: true,
+    scrollEnabled: true,
+    limitsNavigationsToAppBoundDomains: true,
+    backgroundColor: '#ffffff',
+    allowNavigation: [
+      '*.timesafari.app',
+      '*.jsdelivr.net',
+      'api.endorser.ch'
+    ]
+  },
+  android: {
+    allowMixedContent: true,
+    captureInput: true,
+    webContentsDebuggingEnabled: false,
+    allowNavigation: [
+      '*.timesafari.app',
+      '*.jsdelivr.net',
+      'api.endorser.ch',
+      '10.0.2.2:3000'
+    ]
+  },
+  electron: {
+    deepLinking: {
+      schemes: ['timesafari']
+    },
+    buildOptions: {
+      appId: 'app.timesafari',
+      productName: 'TimeSafari',
+      directories: {
+        output: 'dist-electron-packages'
+      },
+      files: [
+        'dist/**/*',
+        'electron/**/*'
+      ],
+      mac: {
+        category: 'public.app-category.productivity',
+        target: [
+          {
+            target: 'dmg',
+            arch: ['x64', 'arm64']
+          }
+        ]
+      },
+      win: {
+        target: [
+          {
+            target: 'nsis',
+            arch: ['x64']
+          }
+        ]
+      },
+      linux: {
+        target: [
+          {
+            target: 'AppImage',
+            arch: ['x64']
+          }
+        ],
+        category: 'Utility'
+      }
+    }
+  }
+};
+
+export default config;

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', '.'],
+  }
+};