From 98aecbef239c78a9e2bd436dbc6264bb942ad1ea Mon Sep 17 00:00:00 2001
From: Ebony Louis <55366651+EbonyLouis@users.noreply.github.com>
Date: Mon, 10 Feb 2025 16:44:00 -0500
Subject: [PATCH] docs: Add Mac M3 Permission Troubleshooting to Documentation
 (#1180)

Co-authored-by: Angie Jones <jones.angie@gmail.com>
---
 .../docs/getting-started/installation.md      |  8 +++++
 documentation/docs/troubleshooting.md         | 34 +++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/documentation/docs/getting-started/installation.md b/documentation/docs/getting-started/installation.md
index 6fb100873..cdfced6ff 100644
--- a/documentation/docs/getting-started/installation.md
+++ b/documentation/docs/getting-started/installation.md
@@ -46,6 +46,14 @@ import RateLimits from '@site/src/components/RateLimits';
         <div style={{ marginTop: '1rem' }}>
           1. Unzip the downloaded `Goose.zip` file.
           2. Run the executable file to launch the Goose desktop application.
+
+          :::note Permissions
+            If you’re on an Apple Mac M3 and the Goose desktop app shows no window on launch, check and update the following:
+
+            Ensure the `~/.config` directory has read and write access.
+
+            Goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the  [Troubleshooting Guide](/docs/troubleshooting.md#macos-permission-issues-m3-macs)
+          :::
         </div>
 
       </TabItem>
diff --git a/documentation/docs/troubleshooting.md b/documentation/docs/troubleshooting.md
index f40aebdf3..f6071951d 100644
--- a/documentation/docs/troubleshooting.md
+++ b/documentation/docs/troubleshooting.md
@@ -172,6 +172,40 @@ An example is the GitHub extension whose command is `npx -y @modelcontextprotoco
 
 ---
 
+### macOS Permission Issues (M3 Macs)
+
+If you encounter an issue where the Goose desktop app shows no window on launch, it may be due to file and folder permissions. This typically happens because Goose needs read and write access to the `~/.config` directory to create its log directory and file.
+
+#### How to Check and Fix Permissions:
+
+1. Open Terminal.
+2. Run the following command to check the current permissions for ~/.config:
+  ```sh
+  ls -ld ~/.config
+  ```
+**Example output:**
+  ```sh
+  drwx------  7 yourusername  staff  224 Jan 15 12:00 /Users/yourusername/.config
+  ```
+`rwx` indicates you have read (r), write (w), and execute (x) permissions for your user. If you do not see `rwx` for your user, follow the steps below.
+
+#### How to Grant Read and Write Permissions:
+
+1. To add the correct permissions, run the following commands:
+    ```sh
+    chmod u+rw ~/.config
+    ```
+    If the ~/.config directory does not exist, create it and then assign permissions:
+      ```sh
+      mkdir -p ~/.config
+      chmod u+rw ~/.config
+      ```
+2. Verify the change:
+    ```sh
+    ls -ld ~/.config
+    ```
+---
+
 ### Need Further Help? 
 If you have questions, run into issues, or just need to brainstorm ideas join the [Discord Community][discord]!