feat: add Build Architecture Guard MDC directive

- Create comprehensive guard rules for build system protection
- Define protected file patterns and validation requirements
- Include risk matrix and required validation checklists
- Add emergency procedures and rollback playbooks

.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,295 @@
+---
+description: Guards against unauthorized changes to the TimeSafari building
+  architecture
+alwaysApply: false
+---
+
+# Build Architecture Guard Directive
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-20
+**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.
+
+## 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`
+
+### 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
+
+**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
+
+## 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
+
+### Desktop Platform
+
+- **Electron**: `npm run build:electron:dev` and packaging for target OS
+- **Verify**: Single-instance behavior and app boot
+
+### Auto-run (if affected)
+
+- **Test Mode**: `npm run auto-run:test` and platform variants
+- **Production Mode**: `npm run auto-run:prod` and platform variants
+
+### Clean and Rebuild
+
+- Run relevant `clean:*` scripts and ensure re-build works
+
+## Emergency Procedures
+
+### Build System Broken
+
+1. **Immediate**: Revert to last known working commit
+2. **Investigation**: Create issue with full error details
+3. **Testing**: Verify all platforms work after revert
+4. **Documentation**: Update `BUILDING.md` with failure notes
+
+### Platform-Specific Failure
+
+1. **Isolate**: Identify which platform is affected
+2. **Test Others**: Verify other platforms still work
+3. **Rollback**: Revert platform-specific changes
+4. **Investigation**: Debug in isolated environment
+
+## Integration Points
+
+### With Version Control
+
+- **Branch Protection**: Require reviews for build script changes
+- **Commit Messages**: Must reference ADR for major changes
+- **Testing**: All build changes must pass CI/CD pipeline
+
+### With Documentation
+
+- **BUILDING.md**: Must be updated for any script changes
+- **README.md**: Must reflect new build requirements
+- **CHANGELOG.md**: Must document breaking build changes
+
+### With Testing
+
+- **Pre-commit**: Run basic build validation
+- **CI/CD**: Full platform build testing
+- **Manual Testing**: Human verification of critical paths
+
+## Risk Matrix & Required Validation
+
+### Environment Handling
+
+- **Trigger**: Change to `.env.*` loading / variable names
+- **Validation**: Prove `dev/test/prod` builds; show environment echo in logs
+
+### Script Flow
+
+- **Trigger**: Reorder steps (prebuild → build → package), new flags
+- **Validation**: Dry-run + normal run, show exit codes & timing
+
+### Platform Packaging
+
+- **Trigger**: Electron NSIS/DMG/AppImage, Android/iOS bundle
+- **Validation**: Produce installer/artifact and open it; verify single-instance,
+  icons, signing
+
+### Service Worker / WASM
+
+- **Trigger**: `sw_combine.js`, WASM copy path
+- **Validation**: Verify combined SW exists and is injected; page loads offline;
+  WASM present
+
+### Docker
+
+- **Trigger**: New base image, build args
+- **Validation**: Build image locally; run container; list produced `/dist`
+
+### Signing/Notarization
+
+- **Trigger**: Cert path/profiles
+- **Validation**: Show signing logs + verify on target OS
+
+## PR Template (Paste into Description)
+
+- [ ] **Level**: L1 / L2 / L3 + justification
+- [ ] **Files & platforms touched**:
+- [ ] **Risk triggers & mitigations**:
+- [ ] **Commands run (paste logs)**:
+- [ ] **Artifacts (names + sha256)**:
+- [ ] **Docs updated (sections/links)**:
+- [ ] **Rollback steps verified**:
+- [ ] **CI**: Jobs passing and artifacts uploaded
+
+## Rollback Playbook
+
+### Immediate Rollback
+
+1. `git revert` or `git reset --hard <prev>`; restore prior `scripts/` or config
+   files
+2. Rebuild affected targets; verify old behavior returns
+3. Post-mortem notes → update this guard and `BUILDING.md` if gaps found
+
+### Rollback Verification
+
+- **Web**: `npm run build:web:dev` and `npm run build:web:prod`
+- **Mobile**: `npm run build:android:test` and `npm run build:ios:test`
+- **Desktop**: `npm run build:electron:dev` and packaging commands
+- **Clean**: Run relevant `clean:*` scripts and verify re-build works
+
+## 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
+
+**ADR must include**: motivation, alternatives, risks, validation plan, rollback,
+  doc diffs.
+
+## Competence Hooks
+
+### Why This Works
+
+- **Prevents Build Failures**: Catches issues before they reach production
+- **Maintains Consistency**: Ensures all platforms build identically
+- **Reduces Debugging Time**: Prevents build system regressions
+
+### Common Pitfalls
+
+- **Silent Failures**: Changes that work on one platform but break others
+- **Dependency Conflicts**: Updates that create version incompatibilities
+- **Documentation Drift**: Build scripts that don't match documentation
+
+### Next Skill Unlock
+
+- Learn to test build changes across all platforms simultaneously
+
+### Teach-back
+
+- "What three platforms must I test before committing a build script change?"
+
+## Collaboration Hooks
+
+### Team Review Requirements
+
+- **Platform Owners**: iOS, Android, Electron, Web specialists
+- **DevOps**: CI/CD pipeline maintainers
+- **QA**: Testing infrastructure owners
+
+### Discussion Prompts
+
+- "Which platforms will be affected by this build change?"
+- "How can we test this change without breaking existing builds?"
+- "What's our rollback plan if this change fails?"
+
+## Self-Check (Before Allowing Changes)
+
+- [ ] **Authorization Level**: Is this change appropriate for the level?
+- [ ] **Testing Plan**: Is there a comprehensive testing strategy?
+- [ ] **Documentation**: Will BUILDING.md be updated?
+- [ ] **Rollback**: Is there a safe rollback mechanism?
+- [ ] **Team Review**: Have appropriate stakeholders been consulted?
+- [ ] **CI/CD**: Will this pass the build pipeline?
+
+---
+
+**Status**: Active build system protection
+**Priority**: Critical
+**Estimated Effort**: Ongoing vigilance
+**Dependencies**: All build system components
+**Stakeholders**: Development team, DevOps, Platform owners
+**Next Review**: 2025-09-20