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

.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