docs: add macOS developer setup and troubleshooting guides

docs/mac/dev-setup.md

@@ -0,0 +1,81 @@
+---
+summary: "Setup guide for developers working on the Clawdis macOS app"
+read_when:
+  - Setting up the macOS development environment
+---
+# macOS Developer Setup
+
+This guide covers the necessary steps to build and run the Clawdis macOS application from source.
+
+## Prerequisites
+
+Before building the app, ensure you have the following installed:
+
+1.  **Xcode**: Required for Swift development.
+2.  **Node.js & pnpm**: Required for the gateway and CLI components.
+3.  **Bun**: Required to package the embedded gateway relay.
+    ```bash
+    curl -fsSL https://bun.sh/install | bash
+    ```
+
+## 1. Initialize Submodules
+
+Clawdis depends on several submodules (like `Peekaboo`). You must initialize these recursively:
+
+```bash
+git submodule update --init --recursive
+```
+
+## 2. Install Dependencies
+
+Install the project-wide dependencies:
+
+```bash
+pnpm install
+```
+
+## 3. Build and Package the App
+
+To build the macOS app and package it into `dist/Clawdis.app`, run:
+
+```bash
+./scripts/package-mac-app.sh
+```
+
+If you don't have an Apple Developer ID certificate, the script will automatically use **ad-hoc signing** (`-`). 
+
+> **Note**: Ad-hoc signed apps may trigger security prompts. If the app crashes immediately with "Abort trap 6", see the [Troubleshooting](#troubleshooting) section.
+
+## 4. Install the CLI Helper
+
+The macOS app requires a symlink named `clawdis` in `/usr/local/bin` or `/opt/homebrew/bin` to manage background tasks.
+
+**To install it:**
+1.  Open the Clawdis app.
+2.  Go to the **General** settings tab.
+3.  Click **"Install CLI helper"** (requires administrator privileges).
+
+Alternatively, you can manually link it from your Admin account:
+```bash
+sudo ln -sf "/Users/$(whoami)/clawdis/dist/Clawdis.app/Contents/Resources/Relay/clawdis" /usr/local/bin/clawdis
+```
+
+## Troubleshooting
+
+### App Crashes on Permission Grant
+If the app crashes when you try to allow **Speech Recognition** or **Microphone** access, it may be due to a corrupted TCC cache or signature mismatch.
+
+**Fix:**
+1. Reset the TCC permissions:
+   ```bash
+   tccutil reset All com.steipete.clawdis.debug
+   ```
+2. If that fails, change the `BUNDLE_ID` temporarily in `scripts/package-mac-app.sh` to force a "clean slate" from macOS.
+
+### Gateway "Starting..." indefinitely
+If the gateway status stays on "Starting...", check if a zombie process is holding the port:
+
+```bash
+lsof -nP -i :18789
+```
+Kill any existing `node` or `clawdis` processes listening on that port and restart the app.

docs/mac/signing.md

@@ -11,7 +11,8 @@ This app is usually built from `scripts/package-mac-app.sh`, which now:
 - writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
 - calls `scripts/codesign-mac-app.sh` to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). Requires a valid signing identity.
 - uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
-- injects build metadata into Info.plist: `ClawdisBuildTimestamp` (UTC) and `ClawdisGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
+- inject build metadata into Info.plist: `ClawdisBuildTimestamp` (UTC) and `ClawdisGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
+- **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
 - reads `SIGN_IDENTITY` from the environment. Add `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"` (or your Developer ID Application cert) to your shell rc to always sign with your cert; otherwise signing falls back to ad‑hoc.
 
 ## Usage
@@ -20,20 +21,10 @@ This app is usually built from `scripts/package-mac-app.sh`, which now:
 # from repo root
 scripts/package-mac-app.sh               # ad-hoc signing
 SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # real cert
-
-# set it once in your shell profile for convenience
-echo 'export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"' >> ~/.zshrc
 ```
 
-If you need a different bundle id (e.g. release build):
-
-```bash
-BUNDLE_ID=com.steipete.clawdis scripts/package-mac-app.sh
-```
-
-Signing identity selection:
-- If `SIGN_IDENTITY` is unset, the script auto-picks a valid identity (Developer ID → Apple Distribution → Apple Development).
-- If no identities exist, the script fails with an error (no ad‑hoc fallback).
+### Ad-hoc Signing Note
+When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID.
 
 ## Build metadata for About
 

docs/troubleshooting.md

@@ -134,6 +134,35 @@ CLAWDIS keeps conversation history in memory.
 }
 ```
 
+## macOS Specific Issues
+
+### App Crashes when Granting Permissions (Speech/Mic)
+
+If the app disappears or shows "Abort trap 6" when you click "Allow" on a privacy prompt:
+
+**Fix 1: Reset TCC Cache**
+```bash
+tccutil reset All com.steipete.clawdis.debug
+```
+
+**Fix 2: Force New Bundle ID**
+If resetting doesn't work, change the `BUNDLE_ID` in `scripts/package-mac-app.sh` (e.g., add a `.test` suffix) and rebuild. This forces macOS to treat it as a new app.
+
+### Gateway stuck on "Starting..."
+
+The app connects to a local gateway on port `18789`. If it stays stuck:
+
+**Fix 1: Kill Zombie Processes**
+Another process might be holding the port.
+```bash
+lsof -nP -i :18789
+# Kill any matching PIDs
+kill -9 <PID>
+```
+
+**Fix 2: Check embedded gateway**
+Ensure the gateway relay was properly bundled. Run `./scripts/package-mac-app.sh` and ensure `bun` is installed.
+
 ## Debug Mode
 
 Get verbose logging: