fix: resolve mapfile compatibility issue in build architecture guard

- Replace mapfile command with portable alternative for cross-shell compatibility
- Add troubleshooting documentation for common shell compatibility issues
- Update BUILDING.md with Build Architecture Guard documentation
- Ensure script works across different shell environments

Fixes pre-commit hook failures on macOS and other systems where mapfile is not available.

BUILDING.md

@@ -78,6 +78,54 @@ npm run build:android:prod     # Android production build
 npm run build:electron:prod    # Electron production build
 ```
 
+### Build Architecture Guard
+
+The Build Architecture Guard protects your build system by enforcing documentation updates when build-critical files are modified. This ensures that all build changes are properly documented in `BUILDING.md`.
+
+#### How It Works
+
+- **Pre-commit Hook**: Automatically checks staged files before each commit
+- **Protected Files**: Build scripts, config files, and platform-specific code
+- **Documentation Requirement**: `BUILDING.md` must be updated alongside build changes
+- **Automatic Enforcement**: Git hooks prevent commits without proper documentation
+
+#### Protected File Patterns
+
+The guard monitors these sensitive paths:
+- `vite.config.*` - Build configuration
+- `scripts/**` - Build and utility scripts
+- `electron/**` - Desktop application code
+- `android/**` - Android platform code
+- `ios/**` - iOS platform code
+- `capacitor.config.ts` - Mobile configuration
+- `package.json` - Dependencies and scripts
+
+#### Using the Guard
+
+```bash
+# Test the guard locally
+./scripts/build-arch-guard.sh --staged
+
+# Bypass for emergency commits (use sparingly)
+git commit --no-verify
+
+# Setup the guard
+npm run guard:setup
+```
+
+#### Troubleshooting
+
+If you encounter `mapfile: command not found` errors:
+```bash
+# Ensure script is executable
+chmod +x scripts/build-arch-guard.sh
+
+# Test the script
+./scripts/build-arch-guard.sh --help
+```
+
+**Note**: The guard is active and will block commits that modify build files without updating `BUILDING.md`.
+
 ### Environment Configuration
 
 #### Quick Environment Setup