Add comprehensive macOS ARM setup documentation and improve build troubleshooting

[hjonck]

Summary

I've created comprehensive documentation to help users successfully build Claudia on macOS ARM (Apple Silicon) machines. This addresses common platform-specific binary conflicts that prevent successful builds and would significantly improve the developer onboarding experience.

Problem

Users attempting to build Claudia from source on Apple Silicon Macs frequently encounter these build-blocking errors:

• "Cannot find module @tauri-apps/cli-darwin-x64"
• "Cannot find module @rollup/rollup-darwin-x64"
• "Cannot find module @esbuild/darwin-x64"
• "Cannot find module '../lightningcss.darwin-arm64.node'"
• "resource path 'binaries/claude-code-x86_64-apple-darwin' doesn't exist"

These errors prevent users from successfully building the application and significantly hurt the first-time contributor experience.

Proposed Changes

I've created two documentation improvements that would solve these issues:

1. Enhanced README.md Troubleshooting Section

Added a new troubleshooting item (#6) specifically for macOS ARM issues with:

• Clear error message identification
• Step-by-step solution commands
• Architecture detection script
• Link to detailed setup guide

Changes made:

• Added ARM64-specific troubleshooting in the existing troubleshooting section
• Included proactive warning in Prerequisites section for Apple Silicon users
• Added copy-paste ready terminal commands for quick fixes

2. Comprehensive Setup Guide: TAURI_MACOS_ARM_SETUP.md

Created a detailed standalone guide covering:

• Prerequisites - All required tools and runtimes
• Step-by-step installation - Platform-specific package installation
• Common issues and solutions - 5 most frequent problems with exact fixes
• Architecture detection script - Automated setup for both ARM64 and Intel
• Verification steps - Commands to confirm successful setup
• Best practices - Environment setup recommendations

Benefits

✅ Improved User Experience

• Reduces setup friction for 60%+ of Mac developers (Apple Silicon users)
• Prevents common build failures before they happen
• Provides clear, actionable solutions when issues occur

✅ Reduced Support Burden

• Fewer GitHub issues about build failures
• Self-service documentation for common problems
• Clear escalation path from quick fixes to detailed guide

✅ Better Developer Onboarding

• New contributors can get started faster
• Clear documentation builds confidence
• Proactive warnings prevent frustration

✅ Real-World Tested

• Validated on actual Apple Silicon hardware
• Tested with complex builds including external binaries
• Works with both Bun and npm package managers

Implementation Details

Quick Fix Integration (README.md)

6. **macOS ARM (Apple Silicon) platform-specific issues**
   
   If you encounter errors like:
   - `"Cannot find module @tauri-apps/cli-darwin-x64"`
   - `"Cannot find module @rollup/rollup-darwin-x64"`
   
   **Solution**: Install ARM64-specific packages:
   ```bash
   npm install @tauri-apps/cli-darwin-arm64 --save-dev
   npm install @rollup/rollup-darwin-arm64 --save-dev
   npm install @esbuild/darwin-arm64 --save-dev
   npm install lightningcss-darwin-arm64 --save-dev
   
   # Clean and rebuild
   rm -rf node_modules package-lock.json
   bun install
   bun run tauri build

### Architecture Detection Script
```bash
#!/bin/bash
ARCH=$(uname -m)
if [[ "$ARCH" == "arm64" ]]; then
    echo "Installing ARM64 packages..."
    npm install @tauri-apps/cli-darwin-arm64 --save-dev
    npm install @rollup/rollup-darwin-arm64 --save-dev
    npm install @esbuild/darwin-arm64 --save-dev
    npm install lightningcss-darwin-arm64 --save-dev
elif [[ "$ARCH" == "x86_64" ]]; then
    echo "Installing x64 packages..."
    npm install @tauri-apps/cli-darwin-x64 --save-dev
    npm install @rollup/rollup-darwin-x64 --save-dev
    npm install @esbuild/darwin-x64 --save-dev
    npm install lightningcss-darwin-x64 --save-dev
fi

Files to Add/Modify

1. README.md - Enhanced troubleshooting section (modifications)
2. TAURI_MACOS_ARM_SETUP.md - Comprehensive setup guide (new file)
3. detect-and-install.sh - Architecture detection script (optional new file)

Community Impact

This documentation would help:

• New contributors get started without frustration
• Apple Silicon users (growing majority of Mac developers) build successfully
• Maintainers by reducing repetitive support questions
• Project adoption by removing a major onboarding barrier

Ready to Implement

I have:

• ✅ Complete documentation ready for integration
• ✅ Tested solutions on real Apple Silicon hardware
• ✅ Clear implementation plan with minimal maintenance overhead
• ✅ Willingness to maintain these docs as tools evolve

Would the team be interested in adding this documentation to help users build Claudia successfully on Apple Silicon Macs?

Related

I've also submitted this as a proposal to the Tauri team for inclusion in their official documentation: tauri-apps/tauri#13771