Update docs for OSX use cases

Added and clarified some OSX-specific use cases

Added a .remarkrc file to prevent usage of personal settings.

docs/.remarkrc

@@ -0,0 +1,2 @@
+{}
+

docs/docs/development/new-shield.md

@@ -34,6 +34,8 @@ own prototype or handwired keyboard, it is recommended to use your own user conf
 of this guide, replace the `app/` directory in the ZMK main repository with the `config/` directory in your
 user config repository. For example, `app/boards/shields/<keyboard_name>` should now be
 `config/boards/shields/<keyboard_name>`.
+
+If you are compiling locally, you will still compile from within `zmk/app`, and you will need to provide the `DZMK_CONFIG` parameter to `west`, e.g., `-DZMK_CONFIG=/path/to/zmk-config/config`, where `/path/to` is the absolute path to your `zmk_config` directory.
 :::
 
 Shields for Zephyr applications go into the `boards/shields/` directory; since ZMK's Zephyr application lives in the `app/` subdirectory of the repository, that means the new shield directory should be:
@@ -78,7 +80,7 @@ which controls the display name of the device over USB and BLE.
 The updated new default values should always be wrapped inside a conditional on the shield config name defined in the `Kconfig.shield` file. Here's the simplest example file.
 
 :::warning
-Do not make the keyboard name too long, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your laptop / tablet.
+Do not make the keyboard name too long, otherwise the bluetooth advertising might fail and you will not be able to find your keyboard from your laptop / tablet. The recommended length is 16 characters or less.
 :::
 
 ```
@@ -95,6 +97,12 @@ You'll also want to set which half is the central side. Most boards set it to th
 Then on the peripheral half, you'll want to turn USB on so that it shows USB status on displays properly.
 Finally, you'll want to turn on the split option for both sides. This can all be seen below.
 
+:::note Reminder About Split Pairing
+
+Only the central side will pair with the OS. The non-central side will pair with the central side.
+
+:::
+
 ```
 if SHIELD_MY_BOARD_LEFT
 

docs/docs/development/setup.md

@@ -343,6 +343,13 @@ The install command is:
 brew install --cask gcc-arm-embedded
 ```
 
+And you'll need to set the following environment variables:
+
+```
+export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
+export GNUARMEMB_TOOLCHAIN_PATH=$(brew --prefix)
+```
+
 :::warning Security Controls Workaround
 
 Please be sure to read the [additional setup instructions](https://docs.zephyrproject.org/2.5.0/getting_started/installation_mac.html#mac-gatekeeper) needed to address security controls found in macOS 10.15 Catalina and newer
@@ -513,9 +520,20 @@ On Windows, only two environment variables need to be set for ZMK to build prope
 
 #### For Zephyr
 
-By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK.
+By default, the Zephyr™ SDK _should_ create a file named `~/.zephyrrc` with the correct environment variables to build ZMK.
 We suggest two main [options](https://docs.zephyrproject.org/2.5.0/guides/env_vars.html#option-3-using-zephyrrc-files) for how to load those settings.
 
+:::note `.zephyrrc` on OSX
+
+In case you don't have `~/.zephyrrc`, these are the two environment variables you will need:
+
+```
+export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
+export GNUARMEMB_TOOLCHAIN_PATH=$(brew --prefix)
+```
+
+:::
+
 ##### Per Shell
 
 To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory:

docs/docs/troubleshooting.md

@@ -5,7 +5,7 @@ sidebar_title: Troubleshooting
 
 ### Summary
 
-The following page provides suggestions for common errors that may occur during firmware compilation. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmk.dev/community/discord/invite).
+The following page provides suggestions for common errors that may occur during firmware compilation or the pairing process. If the information provided is insufficient to resolve the issue, feel free to seek out help from the [ZMK Discord](https://zmk.dev/community/discord/invite).
 
 ### File Transfer Error
 
@@ -67,6 +67,12 @@ Since then, a much simpler procedure of performing a bluetooth reset for split k
 After completing these steps, pair the halves of the split keyboard together by resetting them at the same time. Most commonly, this is done by grounding the reset pins
 for each of your keyboard's microcontrollers or pressing the reset buttons at the same time.
 
+### OSX Pairing Issues
+
+Sometimes, OSX will _say_ your board is connected, but no keypresses will be sent. Double check that everything else is working by plugging the main side in via USB; if both sides register keypresses, i.e., they are connected to each other, you may be affected by the trash stack.
+
+**See [this issue](https://github.com/zmkfirmware/zmk/issues/278) for more details on the error and how to resolve it.**
+
 ### Connectivity Issues
 
 Some users may experience a poor connection between the keyboard and the host. This might be due to poor quality BLE hardware, a metal enclosure on the keyboard or host, or the distance between them. Increasing the transmit power of the keyboard's BLE radio may reduce the severity of this problem. To do this, set the `CONFIG_BT_CTLR_TX_PWR_PLUS_8` configuration value in the `.conf` file of your user config directory as such: