From c3866b7d6b53e8abd3324cc87fcc4a14ea538d26 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 6 Dec 2025 23:46:25 +0100
Subject: [PATCH] docs: document debug signing and bundle id

---
 docs/mac/signing.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 docs/mac/signing.md

diff --git a/docs/mac/signing.md b/docs/mac/signing.md
new file mode 100644
index 000000000..91797d514
--- /dev/null
+++ b/docs/mac/signing.md
@@ -0,0 +1,24 @@
+# mac signing (debug builds)
+
+This app is usually built from `scripts/package-mac-app.sh`, which now:
+
+- sets a stable debug bundle identifier: `com.steipete.clawdis.debug`
+- writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
+- ad‑hoc signs the main binary, the bundled CLI, and the app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech)
+
+## Usage
+
+```bash
+# from repo root
+scripts/package-mac-app.sh
+```
+
+If you need a different bundle id (e.g. release build):
+
+```bash
+BUNDLE_ID=com.steipete.clawdis scripts/package-mac-app.sh
+```
+
+## Why
+
+TCC permissions are tied to the bundle identifier *and* code signature. Unsigned debug builds with changing UUIDs were causing macOS to forget grants after each rebuild. Ad‑hoc signing the binaries and keeping a fixed bundle id/path (`dist/Clawdis.app`) preserves the grants between builds, matching the VibeTunnel approach.