refactor: move README-BUILD-GUARD.md to doc/ folder

- Move README-BUILD-GUARD.md from root to doc/ folder for better organization
- Update all references in README.md to point to new location
- Follows project structure conventions for documentation organization

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

README.md

@@ -36,7 +36,7 @@ git commit --no-verify
 git push --no-verify
 ```
 
-**📚 Full documentation**: See `README-BUILD-GUARD.md`
+**📚 Full documentation**: See `doc/README-BUILD-GUARD.md`
 
 ## 🚀 Quick Start
 
@@ -82,7 +82,7 @@ timesafari/
 ├── 📁 .husky/           # Git hooks (Build Architecture Guard)
 ├── 📄 BUILDING.md       # Build system documentation
 ├── 📄 pull_request_template.md # PR template
-└── 📄 README-BUILD-GUARD.md # Guard system documentation
+└── 📄 doc/README-BUILD-GUARD.md # Guard system documentation
 ```
 
 ## 🔧 Build System
@@ -97,7 +97,7 @@ This project supports multiple platforms:
 ## 📚 Documentation
 
 - **`BUILDING.md`** - Complete build system guide
-- **`README-BUILD-GUARD.md`** - Build Architecture Guard documentation
+- **`doc/README-BUILD-GUARD.md`** - Build Architecture Guard documentation
 - **`pull_request_template.md`** - PR template for build changes
 
 ## 🤝 Contributing
@@ -115,4 +115,4 @@ This project supports multiple platforms:
 
 **Note**: The Build Architecture Guard is active and will block
 commits/pushes that modify build files without proper documentation
-updates. See `README-BUILD-GUARD.md` for complete details.
+updates. See `doc/README-BUILD-GUARD.md` for complete details.

README-BUILD-GUARD.md → doc/README-BUILD-GUARD.md

@@ -230,6 +230,44 @@ git diff --name-only --cached
 3. **Team training** - Help developers understand the system
 4. **Continuous improvement** - Refine patterns and error messages
 
+## 🚨 **Troubleshooting**
+
+### Common Issues
+
+#### mapfile Command Not Found
+
+**Problem**: Pre-commit hook fails with `mapfile: command not found`
+
+**Cause**: The `mapfile` command is bash-specific and not available in all shell environments
+
+**Solution**: The script has been updated to use portable alternatives. If you encounter this issue:
+
+```bash
+# Verify the script is executable
+chmod +x scripts/build-arch-guard.sh
+
+# Test the script directly
+./scripts/build-arch-guard.sh --help
+
+# Check your shell environment
+echo $SHELL
+bash --version
+```
+
+**Prevention**: Ensure your development environment uses bash and the script has proper permissions
+
+### False Positives
+
+```bash
+# If guard blocks legitimate changes, check:
+# 1. Are you modifying a protected file pattern?
+# 2. Did you update BUILDING.md?
+# 3. Is BUILDING.md staged for commit?
+
+# View what the guard sees
+git diff --name-only --cached
+```
+
 ## 🔄 **Customization**
 
 ### Adding New Protected Paths
@@ -288,3 +326,11 @@ Track the effectiveness of your Build Architecture Guard:
 **Dependencies**: Husky, Git, Bash
 **Maintainer**: Development team
 **Related**: `pull_request_template.md`, `scripts/build-arch-guard.sh`
+
+## 📝 **Changelog**
+
+### 2025-08-22 - Shell Compatibility Fix
+- **Fixed**: Replaced `mapfile` command with portable alternative for cross-shell compatibility
+- **Impact**: Resolves "mapfile: command not found" errors in pre-commit hooks
+- **Files**: `scripts/build-arch-guard.sh`
+- **Testing**: Script now works across different shell environments

scripts/build-arch-guard.sh

@@ -111,7 +111,10 @@ main() {
     log_info "Running Build Architecture Guard..."
     
     # Collect changed files
-    mapfile -t changed_files < <(collect_files "$mode" "$arg")
+    changed_files=()
+    while IFS= read -r line; do
+        [[ -n "$line" ]] && changed_files+=("$line")
+    done < <(collect_files "$mode" "$arg")
     
     if [[ ${#changed_files[@]} -eq 0 ]]; then
         log_info "No files changed, guard check passed"