Noizefield · vjcharles · Feb 20, 2026 · Feb 20, 2026
diff --git a/.claude/rules/agent.md b/.claude/rules/agent.md
@@ -1,14 +1,22 @@
 # APC AGENT (Master Dispatcher)
 
 **Role:** You are the Lead Architect of the audio-plugin-coder (APC).
-**System:** Windows 11 | VS Code | JUCE 8 | Visage | WebView | CMake.
+**System:** Windows 11 / macOS | VS Code | JUCE 8 | Visage | WebView | CMake.
 
 ## ⚠️ CRITICAL RULES (ANTI-HALLUCINATION)
 
 ### 1. OS & Shell Protocol
-*   **No Bash/Linux:** NEVER use `mkdir -p`, `rm`, `cp`.
-*   **PowerShell Only:** Use `New-Item`, `Remove-Item`, `Copy-Item`.
-*   **Path Separators:** Always use backslashes (`\`) for paths in commands.
+Detect the current platform and use the appropriate shell and commands.
+
+*   **Windows (PowerShell):**
+    *   Use `New-Item`, `Remove-Item`, `Copy-Item`.
+    *   Path separators: backslashes (`\`).
+    *   Script extension: `.ps1`
+*   **macOS (Bash/Zsh):**
+    *   Use `mkdir -p`, `rm`, `cp -R`.
+    *   Path separators: forward slashes (`/`).
+    *   Script extension: `.sh`
+*   **NEVER mix shells:** Do not run PowerShell commands on macOS or Bash commands on Windows.
 
 ### 2. UI Architecture Protocol (The Fork)
 You must determine the **UI_FRAMEWORK** selection from `status.json` before generating code.
@@ -26,10 +34,17 @@ You must determine the **UI_FRAMEWORK** selection from `status.json` before gene
 
 ### 3. Build Protocol
 *   **NEVER** run `cmake` manually.
+
+**Windows:**
 *   **Preview (Visage):** `powershell -ExecutionPolicy Bypass -File .\scripts\preview-design.ps1 -PluginName <Name>`
 *   **Preview (WebView):** Open `plugins/[Name]/Design/index.html` in Edge/Chrome.
 *   **Full Build:** `powershell -ExecutionPolicy Bypass -File .\scripts\build-and-install.ps1 -PluginName <Name>`
 
+**macOS:**
+*   **Preview (Visage):** `bash scripts/preview-design.sh <Name>`
+*   **Preview (WebView):** Open `plugins/[Name]/Design/index.html` in Safari/Chrome.
+*   **Full Build:** `bash scripts/build-and-install.sh <Name>`
+
 ## 🛑 PHASE GATING PROTOCOL (STRICT)
 **You are strictly forbidden from "rushing ahead."**
 
@@ -38,8 +53,8 @@ You must determine the **UI_FRAMEWORK** selection from `status.json` before gene
     *   **Check Framework:** If `ui_framework` is "visage", do not suggest HTML.
     *   **Use State Management:** Import `scripts/state-management.ps1` and use `Test-PluginState` for validation.
 2.  **One Phase at a Time:** You may ONLY execute instructions from the *current* active Skill file.
-3.  **State Updates:** After each phase completion, use `Update-PluginState` to update `status.json`.
-4.  **Error Recovery:** Always backup state before major operations using `Backup-PluginState`.
+3.  **State Updates:** After each phase completion, update `status.json` using `Update-PluginState` (Windows) or `update_plugin_state` (macOS).
+4.  **Error Recovery:** Always backup state before major operations using `Backup-PluginState` (Windows) or `backup_plugin_state` (macOS).
 5.  **Termination Rule:** After completing the output for a command, you must **STOP**. Do not auto-start the next phase.
 
 ## 📂 FILE SYSTEM PROTOCOL
@@ -250,8 +265,10 @@ Applying documented solution...
 *   **State:** `ship_complete`
 
 ### MAINTENANCE
-*   **Backup:** `/backup [Name]` -> `powershell -File .\scripts\backup.ps1 ...`
-*   **Rollback:** `/rollback [Name]` -> `powershell -File .\scripts\rollback.ps1 ...`
+*   **Backup (Windows):** `/backup [Name]` -> `powershell -File .\scripts\backup.ps1 ...`
+*   **Backup (macOS):** `/backup [Name]` -> `bash scripts/backup.sh ...`
+*   **Rollback (Windows):** `/rollback [Name]` -> `powershell -File .\scripts\rollback.ps1 ...`
+*   **Rollback (macOS):** `/rollback [Name]` -> `bash scripts/rollback.sh ...`
 
 ---
 **DEFAULT BEHAVIOR:**

diff --git a/.claude/rules/file-naming-conventions.md b/.claude/rules/file-naming-conventions.md
@@ -128,7 +128,8 @@ Design\
 2. **Framework Awareness:** File creation depends on UI framework selection
 3. **Version Control:** Use Git for tracking changes, not file versioning in Source\
 4. **State Tracking:** Always update `status.json` after each phase
-5. **Path Separators:** Use backslashes (\) in PowerShell commands and Windows paths
+5. **Path Separators:** Use backslashes (`\`) on Windows (PowerShell), forward slashes (`/`) on macOS/Linux (Bash)
+6. **Script Equivalents:** Every `.ps1` script in `scripts/` has a `.sh` counterpart for macOS/Linux
 
 ## 🔗 Cross-Skill References
 
@@ -145,14 +146,15 @@ Design\
 - **`..claude\guides\state-management-guide.md`** - State management documentation
 
 ### Script Files
-- **`scripts\state-management.ps1`** - Core state management PowerShell module
+- **`scripts\state-management.ps1`** - Core state management PowerShell module (Windows)
+- **`scripts/state-management.sh`** - Core state management Bash module (macOS/Linux)
 - **`scripts\validate-state-management.ps1`** - State management validation script
 
 ### State Operations
-- **State Initialization:** `New-PluginState` function
-- **State Updates:** `Update-PluginState` function with validation
-- **State Validation:** `Test-PluginState` function for prerequisites
-- **Error Recovery:** `Backup-PluginState` and `Restore-PluginState` functions
+- **State Initialization:** `New-PluginState` (Windows) / `new_plugin_state` (macOS)
+- **State Updates:** `Update-PluginState` (Windows) / `update_plugin_state` (macOS)
+- **State Validation:** `Test-PluginState` (Windows) / `test_plugin_state` (macOS)
+- **Error Recovery:** `Backup-PluginState` / `backup_plugin_state` and `Restore-PluginState` / `restore_plugin_state`
 
 ## 🛠️ Validation
 

diff --git a/.claude/rules/juce-build-protocols.md b/.claude/rules/juce-build-protocols.md
@@ -1,18 +1,24 @@
 # JUCE 8 CRITICAL SYSTEM PROTOCOLS
-**REQUIRED READING:** strict constraints for Windows 11 & APC Monorepo.
+**REQUIRED READING:** strict constraints for Windows 11 / macOS & APC Monorepo.
 ## 1. ⚠️ GOLDEN BUILD RULES (HIGHEST PRIORITY)
 ### A. The "One-Script" Rule
-- **NEVER** run cmake, msbuild, or cl.exe manually.
-- **NEVER** try to copy VST3 files manually.
+- **NEVER** run cmake, msbuild, cl.exe, or xcodebuild manually.
+- **NEVER** try to copy VST3/AU files manually.
 - **ALWAYS** use the master script for Building, Installing, and Repairing.
-- **COMMAND:** .\scripts\build-and-install.ps1 -PluginName "TailSync"
+- **Windows:** `.\scripts\build-and-install.ps1 -PluginName "TailSync"`
+- **macOS:** `bash scripts/build-and-install.sh TailSync`
 ### B. Monorepo & Path Logic
-- **Root Context:** All build operations must happen from the Repository Root _nps/).
+- **Root Context:** All build operations must happen from the Repository Root.
 - **Subdirectories:** NEVER run commands inside plugins/[Name]/.
-- **Environment:**
+- **Environment (Windows):**
   - OS: **Windows 11**
-  - Shell: **PowerShell** (Bashrmmkdir -p are FORBIDDEN).
-  - Create Folders: New-Item -ItemType Directory -Force -Path "..."
+  - Shell: **PowerShell**
+  - Create Folders: `New-Item -ItemType Directory -Force -Path "..."`
+- **Environment (macOS):**
+  - OS: **macOS 10.13+**
+  - Shell: **Bash/Zsh**
+  - Create Folders: `mkdir -p "..."`
+  - CMake Generator: **Xcode** (universal binary: x86_64 + arm64)
 ---
 ## 2. 📂 FILE STRUCTURE & WEBVIEW
 ### A. WebView/GUI Architecture

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -1,7 +1,6 @@
 {
   "permissions": {
     "allow": [
-      "Bash(powershell -Command:*)",
       "Bash(powershell -ExecutionPolicy Bypass -File \".\\\\scripts\\\\validate-webview-member-order.ps1\" -PluginName TestWebView)",
       "Bash(Get-ChildItem -Path \"R:\\\\_VST_Development_2026\\\\audio-plugin-coder\\\\.claude\\\\templates\\\\webview\" -Recurse -File)",
       "Bash(Select-Object -ExpandProperty FullName)",
@@ -15,7 +14,6 @@
       "Bash(powershell.exe -Command \"Copy-Item -Path ''R:\\\\_VST_Development_2026\\\\audio-plugin-coder\\\\build\\\\plugins\\\\nf_gnarly\\\\nf_gnarly_artefacts\\\\Release\\\\VST3\\\\NF Gnarly.vst3'' -Destination ''C:\\\\Program Files\\\\Common Files\\\\VST3\\\\'' -Recurse -Force; Write-Host ''VST3 copied successfully''\")",
       "Bash(powershell.exe -ExecutionPolicy Bypass -Command \"Set-Location ''R:\\\\_VST_Development_2026\\\\audio-plugin-coder''; cmake --build build --config Release --target nf_gnarly_VST3 2>&1 | Select-String -Pattern ''\\(error|Finished|Creating\\)'' | Select-Object -First 20\")",
       "Bash(powershell.exe -ExecutionPolicy Bypass -Command \"Set-Location ''R:\\\\_VST_Development_2026\\\\audio-plugin-coder''; cmake --build build --config Release --target nf_gnarly_VST3 2>&1 | Select-String -Pattern ''\\(error|warning|Finished\\)'' | Select-Object -First 10\")",
-      "Bash(grep:*)",
       "Bash(New-Item -ItemType Directory -Force -Path \"plugins\\\\CloudWash\\\\.ideas\")",
       "Bash(Get-ChildItem -Path \".claude\" -Recurse -File)",
       "Bash(Select-Object FullName)",
@@ -40,10 +38,7 @@
       "Bash(Select-Object -First 100)",
       "Bash(Start-Sleep -Seconds 5)",
       "Bash(findstr:*)",
-      "Bash(powershell:*)",
       "Bash(dir scripts:*)",
-      "Bash(python:*)",
-      "Bash(node -e:*)",
       "Bash(ls:*)",
       "Bash(Get-ChildItem -Path \"R:\\\\_VST_Development_2026\\\\audio-plugin-coder\\\\plugins\\\\CloudWash\" -Recurse -Filter \"*.html\")",
       "WebFetch(domain:github.com)",
@@ -75,6 +70,21 @@
       "Bash(git rm:*)",
       "Bash(Test-Path \"plugins\\\\CloudWash\\\\Org_Code\")",
       "Bash(git config:*)"
+    ],
+    "deny": [
+      "Bash(curl*)",
+      "Bash(wget*)",
+      "Bash(Invoke-WebRequest*)",
+      "Bash(Invoke-Expression*)",
+      "Bash(iex *)",
+      "Bash(*| bash*)",
+      "Bash(*| sh*)",
+      "Bash(*~/.ssh*)",
+      "Bash(*~/.aws*)",
+      "Bash(*base64 -d*)",
+      "Bash(node -e:*)",
+      "Bash(python -c:*)",
+      "Bash(python3 -c:*)"
     ]
   }
 }
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![JUCE](https://img.shields.io/badge/JUCE-8.0-blue.svg)](https://juce.com/)
-[![Platform](https://img.shields.io/badge/Platform-Windows%2011-0078D4.svg)](https://www.microsoft.com/windows)
+[![Platform](https://img.shields.io/badge/Platform-Windows%2011%20%7C%20macOS-0078D4.svg)](https://github.com/Noizefield/audio-plugin-coder)
 [![Sponsor](https://img.shields.io/badge/Sponsor-Project-pink.svg?style=social&logo=heart)](https://github.com/sponsors/Noizefield) 
 
 ## About Audio Plugin Coder 
@@ -49,28 +49,47 @@ Instead of manually juggling DSP architecture, UI frameworks, build systems, sta
 
 ### Prerequisites
 
-- Windows 11 or Linux (tested with Mint Linux) (macOS not yet tested)
+**Windows:**
+- Windows 11
 - PowerShell 7+
 - Visual Studio 2022 (with C++ development tools)
 - CMake 3.22+
 - Git
+
+**macOS:**
+- macOS 10.13+ (universal binary: Intel + Apple Silicon)
+- Xcode (with command line tools)
+- CMake 3.22+
+- Git
+- jq (`brew install jq`) - for state management scripts
+
+**Linux:**
+- Tested with Mint Linux
+- CMake 3.22+, GCC/Clang, Git
+
+**All platforms:**
 - **An LLM coding agent** (Claude Code, Antigravity, Kilo, Codex, Cursor)
 
 ### Installation
 
 1. **Clone the repository (with submodules):**
-```powershell
+```bash
 git clone --recursive https://github.com/Noizefield/audio-plugin-coder.git
 cd audio-plugin-coder
 ```
 
-Or clone normally and run setup:
+Or clone normally and run setup (Windows):
 ```powershell
 git clone https://github.com/Noizefield/audio-plugin-coder.git
 cd audio-plugin-coder
 .\scripts\setup.ps1
 ```
 
+Verify your environment (macOS):
+```bash
+bash scripts/system-check.sh
+```
+
 ### Bridge Templates (FFGL & Max/MSP)
 
 If you are specifically interested in building **FFGL Visual Plugins** or **Max for Live Externals**, use the included One-Click Setup script for Windows:
@@ -207,8 +226,11 @@ audio-plugin-coder/
 │       ├── Source/              # C++ code
 │       └── status.json          # State tracking
 ├── scripts/                     # Build automation
-│   ├── state-management.ps1
-│   └── build-and-install.ps1
+│   ├── build-and-install.ps1    # Windows build script
+│   ├── build-and-install.sh     # macOS build script
+│   ├── state-management.ps1     # Windows state management
+│   ├── state-management.sh      # macOS state management
+│   └── installer/               # Platform-specific installers
 └── build/                       # Compilation artifacts
 ```
 
@@ -280,7 +302,7 @@ APC includes an **auto-capture system** that learns from problems:
 APC works with any LLM-based coding agent that supports:
 - Custom workflows/slash commands
 - File system access
-- PowerShell execution
+- Shell execution (PowerShell on Windows, Bash on macOS/Linux)
 
 **Tested with:**
 - ✅ Claude Code (Anthropic)
@@ -290,11 +312,10 @@ APC works with any LLM-based coding agent that supports:
 
 ## 🛠️ Technology Stack
 
-- **JUCE 8** - Audio plugin framework
-- **CMake** - Build system
-- **PowerShell** - Automation scripting
 - **JUCE 8** - Audio plugin framework (includes DSP, GUI, etc.)
-- **WebView2** - Chromium-based web UI
+- **CMake** - Build system (Visual Studio on Windows, Xcode on macOS)
+- **PowerShell / Bash** - Automation scripting (platform-specific)
+- **WebView2 / WKWebView** - Web UI (Windows / macOS)
 - **YAML** - Knowledge base format
 - **Markdown** - Documentation and workflows
 
@@ -324,7 +345,7 @@ Comprehensive documentation is available in the [`docs/`](docs/) directory:
 - [x] Windows support
 - [x] GitHub Actions CI/CD
 - [x] Comprehensive documentation
-- [ ] macOS local build support
+- [x] macOS local build support
 - [x] Linux local build support
 - [x] visage (GUI) support (https://github.com/VitalAudio/visage)
 - [x] FFGL bridge templates (VJ plugins for Resolume, VDMX, etc.)
@@ -340,7 +361,7 @@ I am an independent developer pouring hundreds of hours (and significant API cos
 
 Developing a framework that works across different AI agents means constantly testing against paid tiers of Claude, Gemini, and others. I often run out of "Plan" usage just testing a single workflow improvement.
 
-If APC saves you time, helps you learn JUCE, or helps you ship a plugin, please consider supporting the development. It helps cover API costs and accelerates macOS support!
+If APC saves you time, helps you learn JUCE, or helps you ship a plugin, please consider supporting the development. It helps cover API costs and accelerates new features!
 
     ☕ Buy Me a Coffee / Sponsor on GitHub