Update capture-screen skill docs and versioning

capture-screen/SKILL.md

@@ -227,6 +227,65 @@ These methods were tested and confirmed to fail on macOS:
 | Python `import Quartz` (PyObjC) | `ModuleNotFoundError` | PyObjC not installed in system Python; don't attempt to install it — use Swift instead |
 | `osascript` window id | Wrong format | Returns AppleScript window index, not CGWindowID needed by `screencapture -l` |
 
+## Permission Troubleshooting
+
+`swift scripts/get_window_id.swift` reads on-screen windows via CoreGraphics, so it needs Screen Recording permission on macOS.
+
+Use this order:
+
+1. Confirm trigger
+2. Confirm target identity
+3. Add/enable exact app in Settings
+
+If the command fails with `ERROR: Failed to enumerate windows`, do this:
+
+```bash
+open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
+```
+
+Or print the same checklist directly from the script:
+
+```bash
+swift scripts/get_window_id.swift --permission-hint screen
+swift scripts/get_window_id.swift --permission-hint microphone
+```
+
+Then:
+
+1. In Privacy & Security → Screen Recording, enable the target app.
+2. If your app is missing from the list:
+    - Ensure you granted permission to the real app bundle (not `swift` / terminal helpers).
+    - For CLI tools, build/run as a packaged `.app` during permission verification.
+    - Click `+` and add the `.app` manually from `/Applications`.
+3. Re-run the command after restarting the app.
+4. If this is a CLI workflow, also check whether the launcher is a helper binary:
+   - In most cases the entry shown in TCC is the helper process (`swift`, `Terminal`, `iTerm`, etc.), not the business app.
+   - Permission still works after helper-level grant, but it is not ideal for final UX.
+
+For mic-access-related prompts, use the same pattern with the microphone pane:
+
+```bash
+open "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone"
+```
+
+The same rule still applies: the system can only show permissions for a concrete `.app` bundle. If the request is made by a helper binary, the settings list can be misleading or empty for your product app.
+
+### Quick Check Template
+
+```text
+1) Error: permission denied
+2) Open target pane
+3) Verify identity shown by OS = identity you granted
+4) If not matched, use the script-reported candidate identities and grant the launcher process
+5) Reopen/restart and verify
+```
+
+For production apps, avoid requesting permissions via `swift`/`python` entry points; always route permission checks in the packaged app process so users only see one target.
+
+If you maintain another macOS permission-related flow, reuse this standardized triage template:
+
+- [permission-triage-template.md](references/permission-triage-template.md)
+
 ## Supported Applications
 
 | Application | Window ID | AppleScript Control | Notes |